Merge pull request #18 from agile-ts/develop

Develop

Author: bennobuilder

docs/other/DocSearch.md

@@ -0,0 +1,15 @@
+---
+id: interfaces
+title: Interfaces
+sidebar_label: Interfaces
+slug: /docsearch
+---
+
+Hello `docsearch` Team,
+
+As you can see I am the maintainer of this documentation
+and have the rights to edit it ^^
+
+With best regards
+
+BennoDev

docs/packages/core/features/collection/Introduction.md

@@ -12,8 +12,8 @@ WIP docs!
 :::
 
 A Collection holds a set of Information that we need to remember at a later point in time.
-It is designed for arrays of data objects following the same structure.
-Be aware that each collected Data needs an **unique primaryKey** to properly identify it later.
+It is designed for arrays of data objects following the same pattern.
+Be aware that each collected Data needs an **unique primaryKey** to get properly identified later.
 We instantiate a Collection with help of an [Agile Instance](../agile-instance/Introduction.md) here called `App`.
 By doing this the Collection gets automatically bound to the Agile Instance it was created from.
 ```ts
@@ -25,11 +25,11 @@ but there we have to pass the `Agile Instance`, to which the Collection should g
 const MY_COLLECTION = new Collection(App);
 ```
 Both instantiations lead to the same result, but we recommend using the former way.
-After we have successfully created our Collection, we can dynamically manipulate and work with it.
+After we have successfully created our Collection, we can work with it dynamically and easily.
 ```ts
 MY_COLLECTION.collect({id: 1, name: "jeff"}); // Add Item to Collection
-MY_COLLECTION.remove(1).everywhere(); // Remove Item from everywhere
-MY_COLLECTION.persist(); // Persists Collection Value into the Storage
+MY_COLLECTION.remove(1).everywhere(); // Remove Item from Collection
+MY_COLLECTION.persist(); // Persists Collection Value into a Storage
 ```
 Most methods we use to modify, mutate and access the Collection are chainable.
 ```ts
@@ -38,36 +38,48 @@ MY_COLLECTION.collect({id: 1, name: "jeff"}).persist().removeGroup('myGroup').re
 
 ## 🔹 Item
 
-Each Data we have added to the Collection, like with the `collect` method,
-gets applied to an Item and stored as such in our Collection. 
+Each Data Object we add to our Collection, for example with the `collect` method,
+gets transformed to an Item. This Item than gets stored in our Collection.
+We can simply access each Item with the `getItem` method and the correct primary Key.
 ```ts
 MY_COLLECTION.getItem(/* primary Key */); // Returns Item at the primary Key
 ```
-An Item is an extension of the State Class and offers the same powerful features.
+The cool thing about Items is, they are an extension of the `State Class`.
+This means that they have the same powerful tools like a State.
 ```ts
-const myItem = MY_COLLECTION.getItem(1);
+MY_COLLECTION.collect({id: 1, name: "jeff"}); // Collect Data
+const myItem = MY_COLLECTION.getItem(1); // Returns Item at primaryKey '1'
+myItem.value; // Returns '{id: 1, name: "jeff"}'
 myItem.patch({name: "frank"}); // Update property 'name' in Item
+myItem.undo(); // Undo latest change
 ```
 
 ## 👨‍👧‍👦 [Group](./group/Introduction.md)
 
 Often applications need to categorize and preserve ordering of structured data and
-in AgileTs Groups are the cleanest way to reach this goal. They allow us to
+in AgileTs Groups are the right way to reach this goal. They allow us to
 cluster together data from a Collection as an array of primary Keys.
+```ts
+MY_COLLECTION.createGroup("groupName", [/*initial Items*/]);
+```
 We might use a Group, if we want to have an array of 'Today Todos' from
 a Todo Collection or Posts that belong to the logged-in User from the Post Collection.
 ```ts
-MY_COLLECTION.createGroup("groupName", [/*initial Items*/]);
+USERS.collect(user);
+POSTS.collect(user.posts, user.id);
 ```
-We are able to create as many Groups as we want, and the Collection won't lose
-its redundant behaviour, since the Items are still stored in the Collection, and
-the Groups are only like an interface to it.
+Here we have two Collections, one for users and another for posts. 
+We can collect posts specific to a user and group them automatically by the user's id.
+
+In our Collection we are able to create as many Groups as we want, and the Collection won't lose
+its redundant behaviour. This is due to the fact, that each Item gets stored in the Collection itself and not in the Group.
+You can imagine a Group like an interface to the Collection Data.
 ```ts
 MY_COLLECTION.createGroup("group1", [1, 2, 3]);
 MY_COLLECTION.createGroup("group2", [2, 5, 8]);
 MY_COLLECTION.createGroup("group5000", [1, 10, 500, 5]);
 ```
-A Group is an extension of the State Class and offers the same powerful features.
+Also, a Group is an extension of the `State Class` and offers the same powerful features.
 ```ts
 MY_STATE.undo(); // Undo latest change
 MY_GROUP.reset(); // Reset Group to its intial Value
@@ -77,25 +89,36 @@ But be aware that the `value` might not be the output you expect.
 ```ts
 MY_GROUP.value; // Returns '[8, 5, 30, 1]'
 ```
-It holds the primary Keys of the Items the Group represent.
-To get the right value to the primary Keys just use `output` property.
+Because this property doesn't hold the Item Values, it contains the primary Keys the Group represents.
+To get the Item Value to each primary Keys, just use the `output` property.
 ```ts
 MY_GROUP.output; // Returns '[{ id: 8, name: 'jeff' }, ...]'
 ```
 
 ## 🔮 [Selector](./selector/Introduction.md)
 
-Selectors allow us to _select_ an Item from a Collection. 
-We might use the Selector, if we want to select a 'current User' from our User Collection or
-the 'current viewing Post' from our Post Collection.
+Selectors allow us to _select_ one specific Item from our Collection.
 ```ts
-MY_COLLECTION.createGroup("selectorName", /*to select Item Key*/);
+MY_COLLECTION.createSelector("selectorName", /*to select Item Key*/);
 ```
-A Selector is an extension of the State Class and offers the same powerful features.
+We might use the Selector, if we want to select the 'current logged-in User' from our User Collection.
 ```ts
-MY_STATE.undo(); // Undo latest change
+USERS.select(/* current logged-in userId */);
 ```
-But be aware that by mutating the Selector we won't modify the
+<br/>
+
+A Selector is also able to select a not existing Item, then it holds
+a reference to this Item. But be aware that the Value of the Selector is
+`undefined` during this period of time, since AgileTs doesn't know your desired Item.
+```ts
+MY_SELECTOR.select("notExistingItem");
+MY_SELECTOR.value; // Returns 'undefined' until it the Item got added to the Collection
+```
+A Selector is an extension of the State Class too and offers the same powerful features.
+```ts
+MY_SELECTOR.undo(); // Undo latest change
+```
+But be aware that by mutating the Selector Value we won't modify the
 selected Item in the Collection. To do that we have to modify the Item directly.
 ```ts
 MY_SELECTOR.item.set({id: 1, name: "jeff"});
@@ -105,18 +128,18 @@ MY_SELECTOR.item.set({id: 1, name: "jeff"});
 
 There are two ways to configure our Collection:
 
-- 1. The plain _object_ way, where we configure everything in an object.
+- **1.** The plain _object_ way, where we configure everything in an object.
      Here we are limited in the creation of Groups and Selectors,
      because we can't create them on our own. The Collection takes care of it instead,
-     which limits us in configuring of these Instances.
+     which limits us in configuring these Instances.
      ```ts
      const Collection = App.createCollection({
      key: 'dummyCollection',
      group: ["dummyGroup"]
      })
      ```
 
-- 2. The _function_ way, where we configure everything in an object too.
+- **2.** The _function_ way, where we configure everything in an object too.
      But this time the object has to be returned by a function, which has the collection as its only parameter.
      By approaching the collection, we are able to create Groups and Selectors on our own, which
      gives us more freedom in configuring these Instances.
@@ -129,8 +152,8 @@ There are two ways to configure our Collection:
      }))
      ```
 
-Here is a Typescript Interface for quick reference, however
-each property will be explained in more detail below.
+Here is a Typescript Interface of the configuration Object for quick reference, 
+however each property will be explained in more detail below.
 ```ts
 export interface CreateCollectionConfigInterface<DataType = DefaultItem> {
   groups?: { [key: string]: Group<any> } | string[];
@@ -142,6 +165,39 @@ export interface CreateCollectionConfigInterface<DataType = DefaultItem> {
 }
 ```
 
+### `groups`
+Here we define the initial [Groups](#groups) of our Collection.
+We have two options to add them. 
+The first way is to just pass an Array of Group Names, than
+AgileTs creates these Groups for us.
+```ts
+const MY_COLLECTION = App.createCollection({
+    groups: ["myGroup1", "myGroup2"]
+});
+```
+But if we want to add some initial Items to the Groups we have to go the
+`function` config way.
+```ts
+const MY_COLLECTION = App.createCollection((collection) => ({
+     key: 'dummyCollection',
+     group: {
+        myGroup1: collection.Group(["item1", "item2"]),
+        myGroup2: collection.Group(["item5", "item2", "item6"])
+      }
+     }))
+```
+
+### `key`
+The Key/Name is an optional property, that gets used to identify our Collection.
+This is pretty useful during debug sessions or if we persist our Collection,
+where it automatically uses the `key` as persist key.
+We recommend giving each Collection an unique `key`. It has only advantages.
+```ts
+const MY_COLLECTION = App.createCollection({
+    key: "myKey"
+});
+```
+
 
 ## 🟦 Typescript
 
@@ -154,4 +210,5 @@ interface UserInterface {
 const MY_COLLECTION = App.createState<UserInterface>();
 MY_COLLECTION.collect({id: "invalidType", animal: "Lion"}); // Error
 MY_COLLECTION.collect({id: 1, name: "hans"}); // Success
-```
+```
+This type defines the Value Type of the Collection Items.

docs/packages/core/features/collection/Properties.md

@@ -0,0 +1,12 @@
+---
+id: properties
+title: Properties
+sidebar_label: Properties
+slug: /core/collection/properties
+---
+
+:::warning
+
+WIP docs!
+
+:::

docs/packages/core/features/collection/group/Properties.md

@@ -0,0 +1,12 @@
+---
+id: properties
+title: Properties
+sidebar_label: Properties
+slug: /core/collection/group/properties
+---
+
+:::warning
+
+WIP docs!
+
+:::

docs/packages/core/features/collection/selector/Properties.md

@@ -0,0 +1,12 @@
+---
+id: properties
+title: Properties
+sidebar_label: Properties
+slug: /core/collection/selector/properties
+---
+
+:::warning
+
+WIP docs!
+
+:::

docs/packages/core/features/computed/Properties.md

@@ -0,0 +1,12 @@
+---
+id: properties
+title: Properties
+sidebar_label: Properties
+slug: /core/computed/properties
+---
+
+:::warning
+
+WIP docs!
+
+:::

docs/packages/core/features/state/Introduction.md

@@ -19,17 +19,17 @@ By doing this the State gets automatically bound to the Agile Instance it was cr
 const MY_STATE = App.createState("Hello World");
 ```
 There is also a way to use the plain `State Class`,
-but there we have to pass the `Agile Instance`, to which the State should get bound, beside the initial Value and config.
+but there we have to pass the `Agile Instance`, to which the State should get bound, beside the initial Value.
 ```ts
 const MY_STATE = new State(App, "Hello World");
 ```
 Both instantiations lead to the same result, but we recommend using the former way.
-After we have successfully created our State, we can dynamically manipulate and work with it.
+After we have successfully created our State, we can work with it dynamically and easily.
 ```ts
 MY_STATE.set("Hello There"); // Set State Value to "Hello There"
 MY_STATE.undo(); // Undo latest change
 MY_STATE.is("Hello World"); // Check if State has a specific Value
-MY_STATE.persist(); // Persist State Value into Storage
+MY_STATE.persist(); // Persist State Value into a Storage
 ```
 Most methods we use to modify, mutate and access the State are chainable.
 ```ts
@@ -38,7 +38,7 @@ MY_STATE.undo().set("Hello Hell").watch(() => {}).reset().invert().persist().typ
 
 ## 📭 Props
 
-`State` takes, beside the initial value an optional configuration object.
+A `State` takes, beside the initial value an optional configuration object.
 ```ts
 const MY_STATE = App.createState("myInitialValue", {
     key: "myKey",
@@ -56,8 +56,8 @@ export interface StateConfigInterface {
 ```
 
 ### `key`
-The Key/Name is an optional property, that gets used to identify a State.
-This is pretty useful during debug sessions or if we persist a State,
+The Key/Name is an optional property, that gets used to identify our State.
+This is pretty useful during debug sessions or if we persist our State,
 where it automatically uses the `key` as persist key.
 We recommend giving each State an unique `key`. It as only advantages.
 ```ts
@@ -74,9 +74,9 @@ Gets mostly used internal and has properly no use for you.
 
 :::
 
-`Dependents` is used to detect States, that depend on this State.
+Here we define which States depend on our State.
 This means if our State gets mutated and ingested into the Runtime,
-the depending State gets also ingested into the Runtime.
+the depending States gets also ingested into the Runtime.
 ```ts
 const MY_STATE = App.createState("myInitialValue", {
     dependents: [MY_STATE_2]
@@ -91,8 +91,8 @@ Gets mostly used internal and has properly no use for you.
 
 :::
 
-With `isPlaceholder` we define, that this State is a placeholder.
-Mostly a State is a Placeholder if we want to hold a reference to a State that hasn't been instantiated yet.
+With `isPlaceholder` we define, that our State is a placeholder.
+Mostly a State is a Placeholder if we want to hold a reference to it, because hasn't been instantiated yet.
 ```ts
 const MY_STATE = App.createState("myInitialValue", {
     isPlaceholder: true
@@ -112,4 +112,4 @@ Javascript users can also get rudimentary typesafe, with the `type` function.
 ```ts
 MY_STATE.type(String); // Now State only accept State Values
 ```
-Be aware that the `type` function currently only supports primitive types.
+Be aware that the `type` function currently only supports primitive types.

docs/quick_start/React.md

@@ -149,6 +149,8 @@ MY_FIRST_STATE.set(`Hello World ${++helloWorldCount}`);
 To bring some life into our small Application we update the State with the `set` function
 in which we just pass our desired new value. 
 
+To find out more about States, checkout our [State](../packages/core/features/state/Introduction.md) docs.
+
 <br />
 
 ---
@@ -253,6 +255,7 @@ Be aware that hooks can only be used in React Components!
 To add new Data to our Collection, we cann use the `collect` function.
 In this case we add the _currentInput_ to our Collection, with a random Id as primaryKey.
 
+To find out more about Collections, checkout our [Collection](../packages/core/features/collection/Introduction.md) docs.
 
 ## 🔍 More
 

sidebars.js

@@ -42,22 +42,23 @@ module.exports = {
                                     items: [
                                         "packages/core/features/collection/introduction",
                                         "packages/core/features/collection/methods",
+                                        "packages/core/features/collection/properties",
                                         {
                                             type: 'category',
                                             label: 'Group',
-                                            items: ["packages/core/features/collection/group/introduction", "packages/core/features/collection/group/methods"]
+                                            items: ["packages/core/features/collection/group/introduction", "packages/core/features/collection/group/methods", "packages/core/features/collection/group/properties"]
                                         },
                                         {
                                             type: 'category',
                                             label: 'Selector',
-                                            items: ["packages/core/features/collection/selector/introduction", "packages/core/features/collection/selector/methods"]
+                                            items: ["packages/core/features/collection/selector/introduction", "packages/core/features/collection/selector/methods", "packages/core/features/collection/selector/properties"]
                                         },
                                     ]
                                 },
                                 {
                                     type: 'category',
                                     label: 'Computed',
-                                    items: ["packages/core/features/computed/introduction", "packages/core/features/computed/methods"]
+                                    items: ["packages/core/features/computed/introduction", "packages/core/features/computed/methods", "packages/core/features/computed/properties"]
                                 },
                                 {
                                     type: 'category',