Merge pull request #20 from agile-ts/develop

Develop

Author: bennobuilder

docs/packages/core/Introduction.md

@@ -21,37 +21,59 @@ slug: /core
 
 ## ❓ `core` 
 
-The `core` package is the brain of AgileTs and handles nearly everything related to AgileTs.
-- Manages your Agile Sub Instances ([State](./features/state/Introduction.md), ..)
-- Ingest changes into the Runtime
-- Triggers rerender on Integrations like [React](../react/Introduction.md)
-
-Each mentioned feature is related to the [`Agile Class`](./features/agile-instance/Introduction.md) which 
-is located in the `core`
+The `core` package is the brain of AgileTs. 
+Nearly everything that is related to AgileTs depends on this package.
+The main reason for this is that it includes the main Instance of AgileTs,
+the `Agile Class` here called `App`.
 ```ts
 const App = new Agile();
 ```
-Agile Sub Instance like 
+In summary, the main tasks of the `Agile Class` are to
+- manage and store our Agile Sub Instances ([State](./features/state/Introduction.md), ..)
+- ingest changes into the Runtime
+- trigger rerender on Integrations like [React](../react/Introduction.md)
+
+As you can guess each application uses AgileTs has to install
+the `core` package and instantiate such an `Agile Class`.
+To get some inspiration where to instantiate our `Agile Class`, checkout the [style guide](../../main/StyleGuide.md).
+Beside the `Agile Class` the `core` holds some other useful classes which are
+listed below. But each of these classes depends in some kind on the `Agile Class`.
+
+### ⚡️ [State](./features/state/Introduction.md)
+A State holds an Information that we need to remember at a later point in time.
+```ts
+const MY_STATE = App.createState("Hello there");
+MY_STATE.set("hi"); // Mutate State Value
+MY_STATE.undo(); // Undo latest change
+```
+
+### 👨‍👧‍👦 [Collection](./features/collection/Introduction.md)
+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 pattern.
+```ts
+const MY_COLLECTION = App.createCollection();
+MY_COLLECTION.collect({id: 1, name: "frank"}); // Add Data to Collection
+MY_COLLECTION.remove(1).everywhere(); // Remove Data at primary Key '1' from Collection
+```
+
+### 🤖 [Computed](./features/state/Introduction.md)
+A Computed is an extension of the State Class, it does auto compute its value depending on other Instances.
+```ts
+ const MY_COMPUTED = App.createComputed(() => (MY_STATE_1.value + MY_STATE_2.value));
+```
+
+### 🚌 [Event](./features/event/Introduction.md)
+```ts
+const MY_EVENT = App.createEvent();
+MY_EVENT.on(() => {console.log("hello there")}); // Print 'hello there' if Event gets triggered
+MY_EVENT.trigger(); // Trigger Event
+```
 
+## 🚀 Quick Links
 - [State](./features/state/Introduction.md)
-  ```ts
-   const MY_STATE = App.createState("Hello there");
-   ```
 - [Collection](./features/collection/Introduction.md)
-   ```ts
-   const MY_COLLECTION = App.createCollection();
-   ```
 - [Computed](./features/computed/Introduction.md)
-   ```ts
-   const MY_COMPUTED = App.createComputed(() => {});
-   ```
 - [Event](./features/event/Introduction.md)
-   ```ts
-   const MY_EVENT = App.createEvent();
-   ```
-  
-has it originates from the `Agile Class`.
-Each Application using AgileTs must instantiate such an Agile Instance.
-It doesn't matter where we instantiate our main Agile Instance,
-but be aware that it isn't recommend having multiple Agile Instances in one single Application.
-You might check out the [style guides](../../main/StyleGuide.md) to get some inspiration how to structure an Application having AgileTs as state manager.
+- [Group](./features/collection/group/Introduction.md)
+- [Selector](./features/collection/selector/Introduction.md)
+- [Storage](./features/storage/Introduction.md)

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

@@ -11,11 +11,16 @@ WIP docs!
 
 :::
 
-The _Agile Instance_ is created with `new Agile()`and should be unique to our application.
+The `Agile Class` is the foundation of AgileTs,
+nearly everything related to AgileTs depends in some kind on it.
 ```ts
 const App = new Agile();
 ```
-With an instantiated _Agile Instance_, we are able to create any Agile Sub Instances like
+Each created Agile Instance should be unique to our application,
+and we should avoid having multiple from these in one application.
+The Agile Instance can be seen as the store, which offers many powerful features
+to mutate and work with the stored Instances. 
+Such Instances can be created with help of the Agile Instance and get automatically stored in it.
 - [State](../state/Introduction.md)
   ```ts
    const MY_STATE = App.createState("Hello there");
@@ -33,10 +38,6 @@ With an instantiated _Agile Instance_, we are able to create any Agile Sub Insta
    const MY_EVENT = App.createEvent();
    ```
 
-These Sub Instances created with the help of the `Agile Class` are automatically bound to it.
-Because of the storing behaviour, the `Agile Class` can also be seen as a Store, 
-that offers many features to mutate and work with the stored Instances.
-
 ## 📭 Props
 
 `Agile` takes an optional configuration object as its only parameter.
@@ -60,9 +61,11 @@ export interface CreateAgileConfigInterface {
 
 ### `logConfig`
 
-The logConfig is thought to configure the Logger of AgileTs.
-For instance, we can configure if we want to log all messages or 
-only warnings. [Here](../../../../Interfaces.md#createloggerconfig) you can find all configuration options.
+The `logConfig` is thought to configure the Logger of AgileTs.
+The Agile Logger simply logs important events in the console, like warnings or errors,
+but it also logs runtime events if this is desired.
+So for instance here we can configure if we want to log all messages or 
+only warnings. 
 ```ts
 const App = new Agile({
   logConfig: {
@@ -71,25 +74,29 @@ const App = new Agile({
   },
 });
 ```
+To find out more about possible configuration options, checkout the [CreateLoggerConfigInterface](../../../../Interfaces.md#createloggerconfig).
 
 
 ### `localStorage`
 
-Defines whether we want to use the Local Storage as default Storage or not.
-If we use the Local Storage each Agile Sub Instance we persist, gets stored in the Local Storage by default.
-We aren't limited to the Local Storage, we can configure our own [Storage](../storage/Introduction.md). 
-This is in a Mobile Environment necessary, because there the Local Storage doesn't exist.
-With `App.registerStorage()` we can register our wished [Storage](../storage/Introduction.md).
+Defines whether AgileTs creates an interface to the `localStorage` for us.
+If we have decided to use the local storage, each Agile Sub Instance we
+persist, gets stored into the `localStorage` by default.
 ```ts
 const App = new Agile({
   localStorage: false // default true
 });
 ```
+Of course, we aren't limited to the `localStorage`. 
+We are able to create an Interface to any [Storage](../storage/Introduction.md) we want.
+For instance is this necessary in the Mobile Environment, because there
+the `localStorage` doesn't exists. With `App.registerStorage()` we can register our own [Storage](../storage/Introduction.md).
 
 ### `waitForMount`
 
-With `waitForMount` we define if AgileTs should wait
-with causing rerender on an unmounted Component until it got mounted.
+With this flag we can determine 
+whether AgileTs should wait until unmounted 
+components are mounted before rerendering them.
 ```ts
 const App = new Agile({
   waitForMount: false // default true
@@ -99,12 +106,11 @@ const App = new Agile({
 
 ## 🟦 Typescript
 
-`Agile Class` is almost 100% typesafe.
+The `Agile Class` is almost 100% typesafe.
 
 ## 🗺 Where to instantiate?
 
-You can instantiate the Agile Instance where ever you want. 
-Directly in your Component, in an extra File or on Paper. 
-It doesn't matter as long as you can work with it.
-There are a few [Style Guides](../../../../main/StyleGuide.md) where you can get some inspiration
-how to structure an Application using AgileTs.
+We can instantiate the Agile Instance of our application where ever we want.
+Directly in our Component, in a separate file or on paper.
+It doesn't matter as long as we can work with it.
+There are a few [Style Guides](../../../../main/StyleGuide.md) which might help us with such hard decision.