Merge pull request #26 from agile-ts/develop

Develop

Author: bennobuilder

.env

@@ -0,0 +1,2 @@
+SKIP_PREFLIGHT_CHECK=true
+BROWSER=chrome

docs/Interfaces.md

@@ -0,0 +1,35 @@
+---
+id: all
+title: React Examples
+sidebar_label: All
+slug: /examples/react
+---
+
+:::warning
+
+WIP Docs!
+
+:::
+
+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, borderColor: "#6c69a0", overflow: "hidden"}}
+        allow={
+            "geolocation; microphone; camera; midi; vr; accelerometer; gyroscope; payment; ambient-light-sensor; encrypted-media; usb"
+        }
+        sandbox={
+            "allow-modals allow-forms allow-popups allow-scripts allow-same-origin"
+        }
+    />
+);
+
+## 😎 First State
+
+<CodeSandBoxEmbed uri={"agilets-first-state-f12cz"}/>
+
+
+## 📝 Multieditor
+
+<CodeSandBoxEmbed uri={"multieditor-yxt4x"} height={800}/>

docs/examples/react/All.md

@@ -7,35 +7,23 @@ slug: /installation
 
 AgileTs is essentially a set of npm [packages](https://github.com/agile-ts/agile/tree/master/packages) that can be installed over [npm](https://www.npmjs.com/).
 
-## 🔑 Requirements
+### 🔑 Requirements
 
 - [Node.js](https://nodejs.org/en/) version >= 10.15.1 or above (which can be checked by running `node -v`)
 
-<br />
-
----
-
-<br />
-
-## 🚀 Quick Start
+### 🚀 Quick Start
 
 To make your start as easy as possible, we have created some quick guides.
-You can follow these guides to get AgileTs up and running in your environment 
-without wasting time.
+You can follow these to get AgileTs up and running in your environment 
+without wasting any time.
 
 - [React](../quick_start/React.md)
 - Vue (coming soon)
 - Angular (coming soon)
 
-<br />
-
----
-
-<br />
-
-## 🗂 Packages
+### 🗂 Packages
 
-Here are links to the separate installation guides for all AgileTs packages.
+Here are links to separate installation guides for all AgileTs packages.
 
 - [Core](../packages/core/Installation.md)
 - [React](../packages/react/Installation.md)

docs/examples/react/All.mdx

@@ -37,11 +37,11 @@ The philosophy behind AgileTs is simple:
 Write minimalistic, boilerplate free code that captures your intent.
 
 **Some straightforward syntax examples:**
-- Store State in the Local Storage
+- Store State in any Storage, like [Local Storage](https://www.w3schools.com/html/html5_webstorage.asp)
   ```ts
   MY_STATE.persist("storage-key")
   ```
-- Create reactive Collection of States
+- Create reactive Array of States
   ```ts
   const MY_COLLECTION = App.Collection();
   MY_COLLECTION.collect({id: 1, name: "Frank"});
@@ -60,8 +60,8 @@ Write minimalistic, boilerplate free code that captures your intent.
 - Has **no** external dependencies
 
 ### 🌌 Centralize
-Manage your Application Logic in a central place outside any UI-Framework.
-This makes your code more decoupled, portable, and above all, easily testable.
+Manage your Application Logic in a central place outside of any UI-Framework.
+This makes your code more decoupled, portable, and above all easy testable.
 
 ### 🎯 Easy to Use
 Learn the powerful tools of AgileTs in a short amount of time.

docs/main/Installation.md

@@ -7,23 +7,23 @@ slug: /style-guide
 
 :::note
 
-**AgileTs isn't bound to any specific Style-Guide**, but there are some you may get inspiration from.
+**AgileTs isn't bound to any specific Style-Guide**, but there are some you may get inspired from.
 
 :::
 
-To give you an idea of possible structures of applications using AgileTs as a state management framework,
-we have prepared some inspirations for you.
-Feel free to pick and tweak one to your needs.
+To give you an idea of possible structures for applications using AgileTs as a state management framework,
+we have prepared some inspiration guides for you.
+Feel free to choose one of them and adapt it to your needs.
 
 ## 🚀 Inspiration 1
 
-In this Style-Guide, we have a so-called `core` at the top level of our `src` folder beside our UI-Components.
-This `core` is thought to be the brain of our application and should contain all business logic
-and logic, in general, that isn't specifically bound to a Component.
-This outsourcing of our Logic makes our code more decoupled,
-portable, and above all, easily testable.
+In this Style-Guide, we have a so-called `core` at the top-level of our `src` folder beside our UI-Components.
+The `core` is thought to be the brain of our application and should contain all business logic
+and logic in general, that isn't specifically bound to a Component.
+This outsourcing of our logic makes our code more decoupled,
+portable, and above all easy testable.
 
-Below you can see where our `core` might be located.
+Below you can see where our `core` should be located.
 
 ```js {3} title="MyApp"
 my-app
@@ -33,9 +33,9 @@ my-app
 .
 ```
 
-To represent the `core` visually, I use one of a simple **TODO-Application**.
-Which has two main [Entities](#📁-entities), that can be handled by AgileTs.
-The **User** and of course the **TODO**-Item. These two parts are mapped in our `core`.
+To represent the `core` for a better understanding visual, I use one of a TODO application.
+This application has two main [Entities](#📁-entities), that can be handled by AgileTs.
+The **User** and of course the **TODO-Item**. These two parts are mapped in our `core`.
 
 ```js title="TodoList-Core"
 core
@@ -58,6 +58,7 @@ core
 |── index.ts
 .
 ```
+Each property that you can find in the above shown graph, is described in detail below ⬇️.
 
 ## 📁 api
 
@@ -95,7 +96,7 @@ A _User Entity_ should only treat the whole logic of the User and shouldn't do r
 ### 📝 index.ts
 
 Here we just export all [actions](#📝-.action.ts), [routes](#📝-.routes.ts), [interfaces](#📝-.interface.ts) and
-the [controller](#📝-.controller.ts). To properly import them in the UI-Layer later.
+the [controller](#📝-.controller.ts). To properly import them in our UI-Layer later.
 
 ```ts title="index.ts in 📁todo"
 import * as actions from "./todo.actions";
@@ -167,7 +168,7 @@ If you are a [Typescript](https://www.typescriptlang.org/) user, you properly wa
 These interfaces belonging to this entity should be defined here.
 
 **For instance** <br />
-In case of the TODO-Entity, it should contain a _TodoInterface_.
+In case of the TODO-Entity, it contains a _TodoInterface_.
 
 ```ts title="todo.interface.ts in 📁todo"
 export interface TodoInterface {
@@ -181,9 +182,9 @@ export interface TodoInterface {
 ### 📝 .routes.ts
 
 To communicate to our server, we have to create [rest calls](https://en.wikipedia.org/wiki/Representational_state_transfer).
-For better maintainability, the rest calls should be provided here in function form.
-These function shaped rest calls should only be used in [actions](#📝-.action.ts).
-It's not recommended calling them from outside the Entity.
+For better maintainability, these rest calls are provided here in function shape
+and should only be used in [actions](#📝-.action.ts) of the Entity.
+It's not recommended calling them from outside the corresponding Entity.
 
 ```ts title="todo.routes.ts in 📁todo"
 import {TodoInterface} from "./todo.interface";
@@ -207,8 +208,8 @@ export const ADD_TODO = async (payload: AddTodoPayloadInterface): Promise<TodoIn
 
 In this file, we create our main `Agile Instance` and configure it to meet our needs.
 For example, we determine here with which UI framework AgileTs works together.
-States, Collections, etc. can then be created from this `Agile Instance`.
-**It's not recommended having multiple main Agile Instances in one Application.**
+States, Collections, etc. then can be created with help of this Instance.
+**It's not recommended having multiple `Agile Instances` in one Application!!**
 
 ```ts title="app.ts"
 import {Agile} from "@agile-ts/core";
@@ -219,8 +220,9 @@ export const App = new Agile({logJobs: true}).use(reactIntegration);
 
 ## 📝 index.ts
 
-Here we export our `core` entities so that we can reach each entity without any problems.
-Now we are able to just import our `core` and mutate each entity from it like `core.todo.addTodo(/**/)`.
+Here we export our `core` entities so that each entity can be reached without any detours.
+For instance, we might import the `core` in our UI-Layer. 
+There we than just import our `core` and mutate each entity from it like `core.todo.addTodo(/* */)`.
 
 ```ts title="index.ts"
 import todo from "./controllers/todo";
@@ -236,4 +238,23 @@ const core = {
 globalBind("__core__", core);
 
 export default core;
-```
+```
+
+
+
+<br />
+
+---
+
+<br />
+
+
+
+## 🚀 Inspiration 2
+
+:::note
+
+Feel free to share your own structure here.
+Every contribution is welcome. :D
+
+:::

docs/main/Introduction.md

@@ -23,7 +23,7 @@ slug: /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,
+It includes the main Instance of AgileTs,
 the `Agile Class` here called `App`.
 ```ts
 const App = new Agile();
@@ -32,10 +32,11 @@ 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)
+- Store values in any [Storage](./features/storage/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).
+this package and instantiate such an `Agile Class`.
+To get some inspiration where to instantiate the `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`.
 
@@ -57,7 +58,7 @@ MY_COLLECTION.remove(1).everywhere(); // Remove Data at primary Key '1' from Col
 ```
 
 ### 🤖 [Computed](./features/state/Introduction.md)
-A Computed is an extension of the State Class, it does auto compute its value depending on other Instances.
+A Computed is an extension of the `State Class`, it does automatically compute its value depending on other Instances.
 ```ts
  const MY_COMPUTED = App.createComputed(() => (MY_STATE_1.value + MY_STATE_2.value));
 ```

docs/main/StyleGuide.md

@@ -11,16 +11,14 @@ WIP docs!
 
 :::
 
-The `Agile Class` is the foundation of AgileTs,
-nearly everything related to AgileTs depends in some kind on it.
+The `Agile Class` is the foundation of AgileTs, everything related to AgileTs depends on this class in different ways.
 ```ts
 const App = new Agile();
 ```
-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.
+It can be seen as the store of your application, because each `Agile Sub Instance` (ASI) gets stored and manged by it.
+The `Agile Class` doesn't contain these ASI's internally, but each ASI contains a reference to the main `Agile Class`.
+Here are some examples of Agile Sub Instances (ASI):
+
 - [State](../state/Introduction.md)
   ```ts
    const MY_STATE = App.createState("Hello there");
@@ -37,10 +35,19 @@ Such Instances can be created with help of the Agile Instance and get automatica
    ```ts
    const MY_EVENT = App.createEvent();
    ```
+  
+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](../state/Introduction.md), ..)
+- ingest changes into the Runtime
+- 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`.
 
 ## 📭 Props
 
-`Agile` takes an optional configuration object as its only parameter.
+The `Agile Class` takes an optional configuration object as its only parameter.
 ```ts
 const App = new Agile({
     logConfig: {
@@ -64,8 +71,6 @@ export interface CreateAgileConfigInterface {
 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: {
@@ -79,8 +84,8 @@ To find out more about possible configuration options, checkout the [CreateLogge
 
 ### `localStorage`
 
-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
+Defines whether AgileTs should create an interface to the `localStorage` for us or not.
+If we have decided to use the [Local Storage](https://www.w3schools.com/html/html5_webstorage.asp), each Agile Sub Instance we
 persist, gets stored into the `localStorage` by default.
 ```ts
 const App = new Agile({
@@ -89,14 +94,14 @@ const App = new Agile({
 ```
 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).
+For instance is this necessary in a Mobile Environment, 
+because there the `localStorage` doesn't exists. With `App.registerStorage()` we can register our own [Storage](../storage/Introduction.md).
 
 ### `waitForMount`
 
-With this flag we can determine 
-whether AgileTs should wait until unmounted 
-components are mounted before rerendering them.
+With this flag we can determine, 
+if AgileTs should wait until unmounted 
+components get mounted before rerendering them.
 ```ts
 const App = new Agile({
   waitForMount: false // default true
@@ -108,9 +113,10 @@ const App = new Agile({
 
 The `Agile Class` is almost 100% typesafe.
 
+
 ## 🗺 Where to instantiate?
 
-We can instantiate the Agile Instance of our application where ever we want.
+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.