Merge pull request #24 from agile-ts/develop

Develop

Author: bennobuilder

docs/Interfaces.md

@@ -15,7 +15,7 @@ export const CodeSandBoxEmbed = ({ uri, height }) => (
     <iframe
         src={`https://codesandbox.io/embed/${uri}?fontsize=14&hidenavigation=0&theme=dark&view=preview`}
         title={"Code Sandbox"}
-        style={{width: "100%", height: height || 500, borderRadius: 4, overflow: "hidden"}}
+        style={{width: "100%", height: height || 500, borderRadius: 4, borderColor: "#6c69a0", overflow: "hidden"}}
         allow={
             "geolocation; microphone; camera; midi; vr; accelerometer; gyroscope; payment; ambient-light-sensor; encrypted-media; usb"
         }
@@ -25,11 +25,11 @@ export const CodeSandBoxEmbed = ({ uri, height }) => (
     />
 );
 
-# First State
+## 😎 First State
 
 <CodeSandBoxEmbed uri={"agilets-first-state-f12cz"}/>
 
 
-# Multieditor
+## 📝 Multieditor
 
 <CodeSandBoxEmbed uri={"multieditor-yxt4x"} height={800}/>

docs/examples/react/All.mdx

@@ -38,10 +38,10 @@ Here are some examples of Agile Sub Instances (ASI):
 
 These ASI's are created with the help of an `Agile Instance` and get automatically bound to it.
 In summary, the main tasks of an instantiated `Agile Class` (Agile Instance) are to:
-- manage and store Agile Sub Instances ([State](./features/state/Introduction.md), ..)
+- manage and store Agile Sub Instances ([State](../state/Introduction.md), ..)
 - ingest changes into the Runtime
-- trigger rerender on Integrations like [React](../react/Introduction.md)
-- permanently save values in any [Storage](./features/storage/Introduction.md) 
+- trigger rerender on Integrations like [React](../../../react/Introduction.md)
+- permanently save values in any [Storage](../storage/Introduction.md) 
 
 Be aware that each application using AgileTs should only have **one** `Agile Instance`.
 
@@ -119,4 +119,4 @@ The `Agile Class` is almost 100% typesafe.
 We can instantiate the `Agile Class` 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.
+There are a few [Style Guides](../../../../main/StyleGuide.md) which might help us with such hard decision.

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

@@ -104,6 +104,12 @@ USERS.select(/* current logged-in userId */);
 
 ## 📭 Props
 
+```ts
+App.createCollection(config);
+```
+
+### `config`
+
 Our `Collection` takes, an optional configuration object as its only property.
 There are two different ways to configure our Collection with these object.
 
@@ -144,7 +150,9 @@ export interface CreateCollectionConfigInterface<DataType = DefaultItem> {
 }
 ```
 
-### `groups`
+<br/>
+
+#### `groups`
 Here we define the initial [Groups](#groups) of our Collection.
 There are two ways of doing this.
 The first one is to pass an Array of Group Names.
@@ -168,7 +176,9 @@ const MY_COLLECTION = App.createCollection((collection) => ({
 With help of the Collection, we are able to 'instantiate' the Groups on our own,
 which gives us much more freedom configuring these.
 
-### `selectors`
+<br/>
+
+#### `selectors`
 Here we define the initial [Selectors](#selectors) of our Collection.
 As with the `groups` property, there are also 2 ways to define the Selector here.
 The first one is to pass an Array of Selector Names.
@@ -192,7 +202,9 @@ const MY_COLLECTION = App.createCollection((collection) => ({
 With help of the Collection, we are able to 'instantiate' the Selectors on our own,
 which gives us much more freedom configuring these.
 
-### `key`
+<br/>
+
+#### `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.
@@ -203,7 +215,9 @@ const MY_COLLECTION = App.createCollection({
 });
 ```
 
-### `primaryKey`
+<br/>
+
+#### `primaryKey`
 The primaryKey is used to define which property in the collected Data gets used as primaryKey.
 By default, it is `id`. Each collected Data needs one primaryKey otherwise, we are not able 
 to properly identify this Data later.
@@ -217,7 +231,9 @@ MY_COLLECTION.collect({key: 1, name: "hans"});
 // primary Key ----------
 ```
 
-### `defaultGroupKey`
+<br/>
+
+#### `defaultGroupKey`
 The defaultGroupKey is used to define the name/key of the default Group.
 The default Group represents all Items of the Collection.
 By default, what a wonder is it `default`. 
@@ -227,7 +243,9 @@ const MY_COLLECTION = App.createCollection({
 });
 ```
 
-### `initialData`
+<br/>
+
+#### `initialData`
 The initial Data of our Collection.
 ```ts
 const MY_COLLECTION = App.createCollection({

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

@@ -45,6 +45,147 @@ Returns the [Collection](./Introduction.md) it was called on.
 
 
 
-`Group()`
+## `Group()`
+
+Creates a new Group, without binding it properly to the Collection.
+This function is intended to be used in the `Collection Config`. 
+```ts {3}
+App.createCollection((collection) => ({
+    groups: {
+        myGroup: collection.Group(["item1", "item2"])
+    }
+}))
+```
+For creating groups in general we recommend using `createGroup`, 
+because it binds the Group properly to the Collection.
+
+### 📭 Props
+
+| Prop           | Type                                                                      | Default    | Description                                           | Required |
+|----------------|---------------------------------------------------------------------------|------------|-------------------------------------------------------|----------|
+| `initialItems` | Array<string \| number>                                                   | []         | Initial ItemKeys of the Group                         | No       |
+| `config`       | [GroupConfig](../../../../Interfaces.md#groupconfig)                      | {}         | Configuration                                         | No       |
+
+### 📄 Return
+Returns a fresh [Group](./group/Introduction.md).
+
+
+
+<br />
+
+---
+
+<br />
+
+
+
+## `Selector()`
+
+Creates a new Selector, without binding it properly to the Collection.
+This function is intended to be used in the `Collection Config`. 
+```ts {3}
+App.createCollection((collection) => ({
+    selectors: {
+        mySelector: collection.Selector("item1")
+    }
+}))
+```
+For creating selectors in general we recommend using `createSelector`, 
+because it binds the Selector properly to the Collection.
+
+### 📭 Props
+
+| Prop           | Type                                                                      | Default    | Description                                           | Required |
+|----------------|---------------------------------------------------------------------------|------------|-------------------------------------------------------|----------|
+| `initialKey`   | string \| number                                                          | undefined  | Key of Item that the Selector represents              | No       |
+| `config`       | [SelectorConfig](../../../../Interfaces.md#selectorconfig)                | {}         | Configuration                                         | No       |
+
+### 📄 Return
+Returns a fresh [Selector](./selector/Introduction.md).
+
+
+
+<br />
+
+---
+
+<br />
+
+
+
+## `initSelectors()`
+
+:::warning
+
+No public function! Is public because of testing hehe..
+
+:::
+
+
+
+<br />
+
+---
+
+<br />
+
+
+
+## `initGroups()`
+
+:::warning
+
+No public function! Is public because of testing hehe..
+
+:::
+
+
+
+<br />
+
+---
+
+<br />
+
+
+
+## `collect()`
+
+Allows us to collect Data and add it to our Collection.
+```ts
+MY_COLLECTION.collect({id: 1, name: "jeff"}); // Collect one Data
+MY_COLLECTION.collect([{id: 9, name: "hans"}, {id: 22, name: "frank"}]); // Collect multiple Datas
+```
+**Each Data needs one `primaryKey` to properly be identified later.** 
+In the above example, the `primaryKey` property is _'id'_, but we can change it in the `Collection Config`.
+If one Data Object contains a `primaryKey` which already exists, 
+the existing Data will be overwritten by default.
+
+To quickly add Data to specific Groups, 
+the collect method takes `groupKeys` beside the to collect Data.
+A Group is like an interface to the Data of a Collection.
+Each collected Data will be added to the _'default'_ Group by default.
+```ts
+MY_COLLECTION.collect({id: 1, name: "jeff"}, ["group1", "group2"]);
+```
+For each not existing passed `groupKey`, a new Group will automatically be created.
+For instance if the _'group1'_ from the above example doesn't exist, 
+a Group with the initial itemKeys ('[1]'), and the key 'group1' gets created.
+
+### 📭 Props
+
+| Prop           | Type                                                                      | Default    | Description                                           | Required |
+|----------------|---------------------------------------------------------------------------|------------|-------------------------------------------------------|----------|
+| `data`         | DataType \| Array<DataType\> (DataType = Object)                           | undefined  | Data which gets added to the Collection               | No       |
+| `groupKeys`    | string \| number                                                          | []         | Keys of Groups to which the Data gets added           | No       |
+| `config`       | [CollectConfig](../../../../Interfaces.md#collectconfig)                  | {}         | Configuration                                         | No       |
+
+### 📄 Return
+Returns the [Collection](./Introduction.md) it was called on.
+
+
+
+
+
 
 

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

@@ -54,6 +54,21 @@ Test the State yourself, it's only one click away. Just select your preferred Fr
 
 ## 📭 Props
 
+```ts
+App.createState(initialValue, config);
+```
+
+### `initialValue`
+
+The first Value which gets assigned to our State.
+```ts {1}
+const MY_STATE = App.createState("hello there");
+MY_STATE.value; // Returns 'hello there'
+MY_STATE.initialStateValue; // Returns 'hello there'
+```
+
+### `config`
+
 Our `State` takes, beside the initial value an optional configuration object.
 ```ts
 const MY_STATE = App.createState("myInitialValue", {
@@ -71,7 +86,9 @@ export interface StateConfigInterface {
 }
 ```
 
-### `key`
+<br/>
+
+#### `key`
 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.
@@ -82,7 +99,9 @@ const MY_STATE = App.createState("myInitialValue", {
 });
 ```
 
-### `dependents`
+<br/>
+
+#### `dependents`
 
 :::info
 
@@ -99,7 +118,9 @@ const MY_STATE = App.createState("myInitialValue", {
 });
 ```
 
-### `isPlaceholder`
+<br/>
+
+#### `isPlaceholder`
 
 :::info
 
@@ -120,8 +141,10 @@ MY_STATE.exists(); // false
 ## 🟦 Typescript
 
 `State` is almost 100% typesafe and takes an optional generic type for type safety.
-```ts
+```ts {1}
 const MY_STATE = App.createState<string>("Hello World");
+MY_STATE.set(1); // Error
+MY_STATE.set("hello space"); // Success
 ```
 This type defines the type of the State Value.
 Javascript users can also get rudimentary typesafe, with the `type` function.