Merge pull request #78 from agile-ts/develop

updated docusaurus

Author: bennobuilder

docs/packages/core/Introduction.md

@@ -26,18 +26,18 @@ It contains the main Instance of AgileTs, called [`Agile Class`](./features/agil
 ```ts
 const App = new Agile();
 ```
-In summary, the most important tasks of the `Agile Class` are to:
-- manage `Agile Sub Instances`, like [States](./features/state/Introduction.md), ..
-- ingest changes into the `runtime`
-- trigger rerender in Integrations like [React](../react/Introduction.md)
-- store values in any [Storage](./features/storage/Introduction.md)
+In summary the main tasks of the `AgileClass` are to:
+- queuing `Agile Sub Instance` changes in the `runtime` and preventing race conditions
+- provide configuration object
+- update/rerender subscribed Components through Integrations like the [React Integration](../react/Introduction.md)
+- Integrating with persistent [Storage](./features/storage/Introduction.md)
 
-Each application using AgileTs needs the `core` package 
+Each application using AgileTs needs the `core` package installed
 and has to instantiate a `Agile Class` often called `App`.
 To get some inspiration where to instantiate the `Agile Class`, check out the [Style Guide](../../main/StyleGuide.md) Section.
 Besides, the `Agile Class` the `core` holds some other useful classes,
 which represent the actual features of AgileTs, since the `Agile Class`
-is mostly used internally.
+is mostly used internally as interface to Storages and Frameworks.
 
 ### ⚡️ [State](./features/state/Introduction.md)
 A State holds an Information that we need to remember at a later point in time.

docs/packages/core/features/agile-instance/Introduction.md

@@ -16,9 +16,11 @@ The `Agile Class` is the main Instance of AgileTs and should be unique to our ap
 ```ts
 const App = new Agile();
 ```
-It can be seen as our application manager. Each `Agile Sub Instance` (ASI) holds a reference 
-to the `Agile Class` and depends on its functionalities. <br/>
-For reference here are some `Agile Sub Instances` (ASI):
+It can be seen as the interface to any Storage, or the Frameworks AgileTs is implemented in like React.
+In addition, it manages the changes of `Agile Sub Instances` to prevent race conditions.
+Each `Agile Sub Instance` (ASI) holds a reference to the `Agile Class` and depends on its functionalities.
+Furthermore, ASI's are created with the help of an instantiated `Agile Class`.
+For reference here are some `Agile Sub Instances` (ASI) created with an `Agile Instance` called `App`:
 
 - [State](../state/Introduction.md)
   ```ts
@@ -38,11 +40,10 @@ For reference here are some `Agile Sub Instances` (ASI):
    ```
 
 In summary the main tasks of the `AgileClass` are to:
-- manage Agile Sub Instances, like [States](../state/Introduction.md), ..
-- ingest changes into the Runtime (queue system for managing ASI mutations)
+- queuing `Agile Sub Instance` changes in the `runtime` and preventing race conditions
 - provide configuration object
-- trigger rerender on Integrations like [React](../../../react/Introduction.md)
-- store values in any [Storage](../storage/Introduction.md)
+- update/rerender subscribed Components through Integrations like the [React Integration](../../../react/Introduction.md)
+- Integrating with persistent [Storage](../storage/Introduction.md)
 
 ## 📭 Props
 
@@ -82,7 +83,6 @@ const App = new Agile({
 ```
 To find out more about possible configuration options, checkout the [CreateLoggerConfigInterface](../../../../Interfaces.md#createloggerconfig).
 
-
 #### `localStorage`
 
 Defines whether AgileTs should create an interface to the `localStorage` for us or not.

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

@@ -33,8 +33,8 @@ Most methods we use to modify, mutate and access the Collection are chainable.
 MY_COLLECTION.collect({id: 1, name: "jeff"}).persist().removeGroup('myGroup').reset();
 ```
 
-### 🔨 Use case
 
+### 🔨 Use case
 For instance a Collection can be used to remember a flexible array of Todo objects.
 ```ts
 const TODOS = App.createCollection();
@@ -50,16 +50,19 @@ We do that to keep track of which todo relates to which user.
 Now that we `cleaned our bathroom`,
 we remove the todo related to the id `1` from the Collection and all Groups (-> everywhere).
 
+
 ### ⛳️ Sandbox
 Test the Collection yourself. It's only one click away. Just select your preferred Framework below.
 - [React](https://codesandbox.io/s/agilets-first-collection-uyi9g)
 - Vue (coming soon)
 - Angular (coming soon)
 
+
 ## 🗂 Collection Classes
 
 A Collection consists of several classes, all of which play an important role.
 
+
 ### 🔹 Item
 
 Each Data Object we add to our Collection (for example, with the `collect()` method)
@@ -109,6 +112,7 @@ 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 the ordering of structured data.
@@ -143,6 +147,7 @@ POSTS.collect(user.posts, user.id);
 In the above code snippet, 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.
 
+
 ### 🔮 [Selector](./selector/Introduction.md)
 
 Sometimes we need access to one specific Item of a Collection in the long term.
@@ -158,9 +163,10 @@ mySelector.patch({name: "frank"}); // Update property 'name' in Item
 ```
 For instance, a Selector finds its use, to select the currently logged-in user from a User Collection.
 ```ts
-USERS.select(/* current logged-in userId */);
+const CURRENT_USER = USERS.select(/* current logged-in userId */);
 ```
 
+
 ## 📭 Props
 
 ```ts
@@ -263,15 +269,16 @@ which gives us much more freedom in configuring them.
 <br/>
 
 #### `key`
-The name/key is an optional property that is used to identify a specific Collection.
-Such key is pretty useful during debug sessions or if we persist our Collection,
-it automatically uses the Collection `key` as persist key.
-We recommend giving each Collection a unique `key`, since it has only advantages.
+The optional property `key/name` should be a unique `string/number` to identify the Collection later.
 ```ts
 const MY_COLLECTION = App.createCollection({
   key: "myKey"
 });
 ```
+We recommend giving each Collection a unique `key`, since it has only advantages:
+- helps us during debug sessions
+- makes it easier to identify the Collection
+- no need for separate persist Key
 
 <br/>
 
@@ -310,6 +317,7 @@ const MY_COLLECTION = App.createCollection({
 });
 ```
 
+
 ## 🟦 Typescript
 
 A `Collection` is almost 100% typesafe and takes an optional generic type for type safety 

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

@@ -12,11 +12,13 @@ Here are valuable properties of the `Collection Class` listed.
 :::
 
 ## `agileInstance`
-Agile Instance to which the Collection belongs
+
+The [`agileInstance`](../agile-instance/Introduction.md) to which the Collection belongs.
 ```ts
-MY_STATE.agileInstance(); // Returns a Agile Instance
+MY_COLLECTION.agileInstance(); // Returns a Agile Instance
 ```
-Note that it is stored as a function in the Collection, to avoid endless deep classes.
+Be aware that the `agileInstance` property is of the type function,
+to avoid endless deep classes.
 
 
 
@@ -29,12 +31,17 @@ Note that it is stored as a function in the Collection, to avoid endless deep cl
 
 
 ## `key`
-Current key/name of the Collection.
-It is used to uniquely identify the Collection.
-Besides getting the `key`, we can also assign a new `key` with help of this property.
-```ts
-MY_COLLECTION.key = "myCoolCollection";
-MY_COLLECTION.key; // Returns 'myCoolCollection'
+
+The current `key/name` of the Collection,
+which is used to uniquely identify it.
+```ts {2}
+const MY_COLLECTION = App.createCollection({key: 'jeffKey'});
+MY_COLLECTION.key; // Returns 'jeffKey'
+```
+Besides, accessing the `key`, we can also assign a new `key` through this property.
+```ts {1}
+MY_STATE.key = "myCoolState";
+MY_STATE.key; // Returns 'myCoolState'
 ```
 
 
@@ -48,13 +55,14 @@ MY_COLLECTION.key; // Returns 'myCoolCollection'
 
 
 ## `size`
-How many Items are stored in the Collection right now.
+
+Represents how many Items are currently stored in the Collection.
 ```ts {3}
 MY_COLLECTION.collect({id: 1, name: "jeff"});
 MY_COLLECTION.collect({id: 5, name: "frank"});
 MY_COLLECTION.size; // Returns 2
 ```
-Be aware that placeholder Items doesn't get counted.
+Placeholder Items doesn't get counted.
 
 
 
@@ -67,7 +75,8 @@ Be aware that placeholder Items doesn't get counted.
 
 
 ## `data`
-All Items of the Collection are stored here.
+
+The `data` object holds all Items of the Collection.
 ```ts {3}
 MY_COLLECTION.collect({id: 1, name: "jeff"});
 MY_COLLECTION.collect({id: 5, name: "frank"});
@@ -77,23 +86,14 @@ MY_COLLECTION.data; // Returns (see below)
 //   5: Item({id: 5, name: "frank"})
 // }
 ```
-We recommend using the `getAllItems` function to get assess to all Items,
-```ts {1}
-MY_COLLECTION.getAllItems(); // Returns (see below)
-// [
-//   Item({id: 1, name: "jeff"}),
-//   Item({id: 5, name: "frank"})
-// ]
-```
-or the `default Group`.
+We do not recommend accessing the `data` object directly in your code,
+as it is intended for internal use and shouldn't be used outside the AgileTs codebase.
+The Collection provides all the methods to access the `data` object without further thinking.
+For example, to get one specific Item, we should use the `getItem()` method.
 ```ts {1}
-MY_COLLECTION.getGroup(MY_COLLECTION.config.defaultGroupKey).items; // Returns (see below)
-// [
-//   Item({id: 1, name: "jeff"}),
-//   Item({id: 5, name: "frank"})
-// ]
+MY_COLLECTION.getItem(1); // Good pattern
+MY_COLLECTION.data[1]; // Bad pattern
 ```
-Because the `data` property isn't thought to be used in the outer world.
 
 
 
@@ -106,11 +106,12 @@ Because the `data` property isn't thought to be used in the outer world.
 
 
 ## `isPersisted`
-If the State Value got successfully persisted into an external Storage like the [Local Storage](https://developer.mozilla.org/de/docs/Web/API/Window/localStorage).
+
+If the Collection `value` is stored in an external Storage like the [Local Storage](https://developer.mozilla.org/de/docs/Web/API/Window/localStorage).
 ```ts {1,3}
-MY_COLLECTION.isPersisted; // Returns false
+MY_COLLECTION.isPersisted; // Returns 'false'
 MY_COLLECTION.persist();
-MY_COLLECTION.isPersisted; // Returns true (if the persisting was successfull)
+MY_COLLECTION.isPersisted; // Returns 'true' if the persist was successful
 ```
 
 
@@ -124,7 +125,8 @@ MY_COLLECTION.isPersisted; // Returns true (if the persisting was successfull)
 
 
 ## `groups`
-Here all [Groups](./group/Introduction.md) of the Collection are stored.
+
+All [Groups](./group/Introduction.md) of the Collection are stored in the `groups` property.
 ```ts {3}
 MY_COLLECTION.createGroup("group1", [1, 2, 3]);
 MY_COLLECTION.createGroup("group2", [1, 7, 4]);
@@ -134,13 +136,13 @@ MY_COLLECTION.groups; // Returns (see below)
 //   group2: Group([1, 7, 4])
 // }
 ```
-If we want to get access to one specific Group, we should use
-```ts
-MY_COLLECTION.getGroup("group1");
-```
-instead of 
-```ts
-MY_COLLECTION.groups["group1"]
+We do not recommend accessing the `groups` object directly in your code,
+as it is intended for internal use and shouldn't be used outside the AgileTs codebase.
+The Collection provides all the methods to access the `groups` object without further thinking.
+For example, to get one specific Group, we should use the `getGroup()` method.
+```ts {1}
+MY_COLLECTION.getGroup(1); // Good pattern
+MY_COLLECTION.groups[1]; // Bad pattern
 ```
 
 
@@ -154,22 +156,23 @@ MY_COLLECTION.groups["group1"]
 
 
 ## `selectors`
-Here all [Selectors](./selector/Introduction.md) of the Collection are stored.
+
+All [Selectors](./selector/Introduction.md)  of the Collection are stored in the `selectors` property.
 ```ts {3}
-MY_COLLECTION.createGroup("selector1", 1);
-MY_COLLECTION.createGroup("selector2", 7);
-MY_COLLECTION.groups; // Returns (see below)
+MY_COLLECTION.createSelector("selector1", 1);
+MY_COLLECTION.createSelector("selector2", 7);
+MY_COLLECTION.selectors; // Returns (see below)
 // {
 //   selector1: Selector(1),
 //   selector2: Selector(7)
 // }
 ```
-If we want to get access to one specific Selector, we should use
-```ts
-MY_COLLECTION.getSelector("selector1");
-```
-instead of
-```ts
-MY_COLLECTION.selectors["selector1"]
+We do not recommend accessing the `selectors` object directly in your code,
+as it is intended for internal use and shouldn't be used outside the AgileTs codebase.
+The Collection provides all the methods to access the `selectors` object without further thinking.
+For example, to get one specific Selector, we should use the `getSelector()` method.
+```ts {1}
+MY_COLLECTION.getSelector(1); // Good pattern
+MY_COLLECTION.selector[1]; // Bad pattern
 ```