Skip to content
This repository was archived by the owner on Feb 15, 2025. It is now read-only.

Commit c8779ac

Browse files
bennobuilderbennobuilder
committed
fixed typos
1 parent 7b46454 commit c8779ac

File tree

2 files changed

+51
-37
lines changed

2 files changed

+51
-37
lines changed

‎docs/packages/react/Introduction.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ This ensures that AgileTs will re-render the Component when the bound State chan
2828
It also provides some other valuable functionalities
2929
that optimize the workflow with AgileTs in a React project.
3030

31-
A distinction is made between `Functional` and `Class` React Components.
31+
A distinction is made between `Functional` and `Class` Components.
3232
As we prefer to use [`React Hooks`](https://reactjs.org/docs/hooks-intro.html) in Functional Components,
3333
however, Hooks aren't supported in Class Components.
3434
Therefore, we have created alternatives for Class Components
@@ -67,5 +67,8 @@ take a look at the [AgileHOC documentation](api/AgileHoc.md).
6767
- [Installation](./Installation.md)
6868
- [React Hook](api/Hooks.md)
6969
- [useAgile](api/Hooks.md#useagile)
70+
- [useProxy](api/Hooks.md#useproxy)
71+
- [useSelector](api/Hooks.md#useselector)
72+
- [useValue](api/Hooks.md#usevalue)
7073
- [useWatcher](api/Hooks.md#usewatcher)
7174
- [AgileHOC](api/AgileHoc.md)

‎docs/packages/react/api/Hooks.md

Lines changed: 47 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ const myCoolState = useAgile(MY_COOL_STATE);
2323
```
2424
The `useAgile()` Hook returns the current `value` of the provided State
2525
and **not** the State Instance itself.
26-
```ts {5}
26+
```ts {7}
2727
// -- core.js --------------------------------------------------
2828

2929
const MY_STATE = createState('jeff');
@@ -42,7 +42,7 @@ useAgile([MY_COOL_STATE1, MY_COOL_STATE2]);
4242
```
4343
Then `useAgile()` returns an array of State `values` matching the specified State Instances.
4444
This array can be destructured in order to easily access the individual State values
45-
```ts {6}
45+
```ts {8}
4646
// -- core.js --------------------------------------------------
4747

4848
const MY_STATE = App.createState('jeff');
@@ -58,14 +58,14 @@ Binding multiple States to a React Component using a single `useAgile()` Hook ha
5858
It can reduce the number of triggered re-render events by batching re-render jobs.
5959
Thereby, simultaneously triggered re-render events of different State Instances
6060
are combined into one single (combined) re-render event
61-
if these States share the same `SubscriptionContainer`.
61+
if these States share the same `Subscription Container`.
6262
Each `useAgile()` Hook creates its own `Subscription Container` and registers it with AgileTs.
6363
Simply put `Subscription Container` serve as an interface to React-Components for AgileTs.
6464

6565
### 👀 Subscribable Instances
6666

6767
Not only AgileTs States can be bound to React Components via `useAgile()`,
68-
but also all [Agile Sub Instances](../../../main/Introduction.md#agile-sub-instance)
68+
but also all other [Agile Sub Instances](../../../main/Introduction.md#agile-sub-instance)
6969
that contain an [`Observer`](../../../main/Introduction.md#observer).
7070
```ts
7171
const [myCollection, myGroup, myState] = useAgile([MY_COLLECTION, MY_GROUP, MY_STATE]);
@@ -184,7 +184,7 @@ render(<RandomComponent/>);
184184
### 🟦 Typescript
185185

186186
The `useAgile()` Hook is almost 100% typesafe.
187-
```ts
187+
```ts {8}
188188
// -- core.js --------------------------------------------------
189189

190190
const NUMBER_STATE = createState(0);
@@ -201,7 +201,7 @@ console.log(typeof stringState); // Returns 'string'
201201

202202
| Prop | Type | Description | Required |
203203
| ----------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------|
204-
| `deps` | Array<SubscribableAgileInstancesType\> \| SubscribableAgileInstancesType | Agile Instances to be bound to the Functional Component. | Yes |
204+
| `deps` | Array<SubscribableAgileInstancesType\> \| SubscribableAgileInstancesType | Agile Sub Instances to be bound to the Functional Component. | Yes |
205205
| `config` | [AgileHookConfigInterface](../../../Interfaces.md#agilehookconfiginterface) | Configuration | No |
206206

207207
#### SubscribableAgileInstancesType
@@ -212,9 +212,9 @@ type SubscribableAgileInstancesType = State | Collection | Observer | undefined;
212212
### 📄 Return
213213

214214
The `useAgile()` Hook returns the current `output`
215-
or if the Instance has no `output` the `value`
215+
or if the Instance has no `output` the current `value`
216216
of the specified [Agile Sub Instance](../../../main/Introduction.md#agile-sub-instance).
217-
```ts {5}
217+
```ts {7}
218218
// -- core.js -------------------------------------------------
219219

220220
const MY_STATE = createState('jeff');
@@ -226,7 +226,7 @@ console.log(myState); // Returns 'jeff'
226226
```
227227
When passing multiple Agile Sub Instances,
228228
an array of `outputs`/`values` matching the passed Instances is returned.
229-
```ts {6}
229+
```ts {8}
230230
// -- core.js --------------------------------------------------
231231

232232
const MY_STATE = createState('jeff');
@@ -262,7 +262,7 @@ It binds/subscribes AgileTs States to a Functional React Component for reactivit
262262
However, it has one advantage in terms of performance.
263263
Because it only re-renders the React Component when an actual accessed property changes.
264264
This is accomplished by warping a [Proxy()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)
265-
around the returned State value/s.
265+
around the returned State value object/s.
266266
Through this Proxy, AgileTs is able to exactly track accessed properties in the React Component
267267
and can construct paths to these. Based on these paths, it can select the particular accessed properties.
268268

@@ -272,7 +272,7 @@ regardless of whether the changed property value was accessed in the Component o
272272
### 👀 Subscribable Instances
273273

274274
Not only AgileTs States can be bound to React Components via `useProxy()`,
275-
but also all [Agile Sub Instances](../../../main/Introduction.md#agile-sub-instance)
275+
but also all other [Agile Sub Instances](../../../main/Introduction.md#agile-sub-instance)
276276
that contain an [`Observer`](../../../main/Introduction.md#observer).
277277
```ts
278278
const [myCollection, myGroup, myState] = useProxy([MY_COLLECTION, MY_GROUP, MY_STATE]);
@@ -328,7 +328,7 @@ The `useProxy()` Hook is almost 100% typesafe.
328328

329329
| Prop | Type | Description | Required |
330330
| ----------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------|
331-
| `deps` | Array<SubscribableAgileInstancesType\> \| SubscribableAgileInstancesType | Agile Sub Instances that are bound to the Component in which the useProxy Hook is located | Yes |
331+
| `deps` | Array<SubscribableAgileInstancesType\> \| SubscribableAgileInstancesType | Agile Sub Instances to be bound to the Functional Component. | Yes |
332332
| `config` | [AgileHookConfigInterface](../../../Interfaces.md#agilehookconfiginterface) | Configuration | No |
333333

334334
#### SubscribableAgileInstancesType
@@ -339,9 +339,9 @@ type SubscribableAgileInstancesType = State | Collection | Observer | undefined;
339339
### 📄 Return
340340

341341
The `useProxy()` Hook returns the current `output`
342-
or if the Instance has no `output` the `value`
342+
or if the Instance has no `output` the current `value`
343343
of the specified [Agile Sub Instance](../../../main/Introduction.md#agile-sub-instance).
344-
```ts {5}
344+
```ts {7}
345345
// -- core.js -------------------------------------------------
346346

347347
const MY_STATE = createState('jeff');
@@ -353,16 +353,16 @@ console.log(myState); // Returns 'jeff'
353353
```
354354
When passing multiple Agile Sub Instances,
355355
an array of `outputs`/`values` matching the passed Instances is returned.
356-
```ts {6}
356+
```ts {8}
357357
// -- core.js --------------------------------------------------
358358

359-
const MY_STATE = createState('jeff');
359+
const MY_STATE = createState({id: 1: name: 'jeff'});
360360
const MY_STATE_2 = createState('frank');
361361

362362
// -- MyComponent.jsx ------------------------------------------
363363

364364
const [myState, myState2] = useProxy([MY_STATE, MY_STATE_2]);
365-
console.log(myState); // Returns 'jeff'
365+
console.log(myState); // Returns '{id: 1: name: 'jeff'}'
366366
console.log(myState2); // Returns 'frank'
367367
```
368368

@@ -378,9 +378,9 @@ console.log(myState2); // Returns 'frank'
378378

379379
## `useSelector()`
380380

381-
The `useSelector()` React Hook binds/subscribes a part
381+
The `useSelector()` React Hook binds/subscribes a **part**
382382
of an AgileTs State to a Functional React Component for reactivity.
383-
This binding ensures that the Component re-renders whenever the bound State part/property changes.
383+
This binding ensures that the Component re-renders whenever the bound State **part/property** changes.
384384
The to bind part is selected via a selector function specified as second parameter.
385385
```ts
386386
const myName = useAgile(MY_USER, (v) => v.name);
@@ -389,7 +389,7 @@ const myName = useAgile(MY_USER, (v) => v.name);
389389
### 👀 Subscribable Instances
390390

391391
Not only parts of AgileTs States can be bound to React Components via `useSelector()`,
392-
but also parts of all [Agile Sub Instances](../../../main/Introduction.md#agile-sub-instance)
392+
but also parts of all other [Agile Sub Instances](../../../main/Introduction.md#agile-sub-instance)
393393
that contain an [`Observer`](../../../main/Introduction.md#observer).
394394
```ts
395395
const myItem1 = useSelector(MY_COLLECTION, (v) => v['item1']);
@@ -436,18 +436,28 @@ render(<RandomComponent/>);
436436

437437
### 🟦 Typescript
438438

439-
The `useSelector()` Hook isn't typesafe.
439+
The `useSelector()` Hook isn't completely typesafe yet.
440+
```ts
441+
const selectedValue = useSelector(MY_STATE, (v) => v.name);
442+
```
443+
We are still figuring out how to automatically detect and return the selected property type.
444+
As an override, you can also specify the individual types as generics.
440445
```ts
441-
const selectedValue = useSelector(MY_STATE, (v) => v.name) as string;
446+
useSelector<typeof MY_STATE.value, string>(MY_STATE, (v) => v.name);
442447
```
448+
Or explicitly assign the desired type to the return value with the `as` keyword.
449+
```ts
450+
useSelector(MY_STATE, (v) => v.name) as string;
451+
```
452+
443453

444454
### 📭 Props
445455

446-
| Prop | Type | Description | Required |
447-
| ----------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------|
448-
| `dep` | SubscribableAgileInstancesType | Agile Sub Instance to be passed into the selector method | Yes |
449-
| `selector` | SelectorMethodType | Selector method to select the part/property to be bound to the Component in which the useSelector Hook is located | Yes |
450-
| `config` | [AgileHookConfigInterface](../../../Interfaces.md#agilehookconfiginterface) | Configuration | No |
456+
| Prop | Type | Description | Required |
457+
| ----------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------|
458+
| `dep` | SubscribableAgileInstancesType | Agile Sub Instance to be passed into the specified selector method. | Yes |
459+
| `selector` | SelectorMethodType | Selector method to select the part/property of the specified Agile Sub Instance value to be bound to the Functional Component. | Yes |
460+
| `config` | [AgileHookConfigInterface](../../../Interfaces.md#agilehookconfiginterface) | Configuration | No |
451461

452462
#### SubscribableAgileInstancesType
453463
```ts
@@ -461,9 +471,9 @@ type SelectorMethodType<T = any> = (value: T) => any;
461471

462472
### 📄 Return
463473

464-
The `useSelector()` Hook returns the selected property
474+
The `useSelector()` Hook returns the selected property (based on the selector method)
465475
of the specified [Agile Sub Instance](../../../main/Introduction.md#agile-sub-instance).
466-
```ts {5}
476+
```ts {7}
467477
// -- core.js -------------------------------------------------
468478

469479
const MY_STATE = createState({id: 10, name: 'jeff', age: 10});
@@ -489,14 +499,14 @@ console.log(myName); // Returns 'jeff'
489499
The `useValue()` is in its basic functionality equivalent to the [`useAgile()`](#useagile) Hook.
490500
It binds/subscribes AgileTs States to a Functional React Component for reactivity.
491501
However, it differs in on key area,
492-
because it explicitly binds the `value` of a State or other [Agile Sub Instance](../../../main/Introduction.md#agile-sub-instance)
493-
to the Component. With the `useAgile()` Hook,
502+
because it explicitly binds the `value` of a State or other [Agile Sub Instances](../../../main/Introduction.md#agile-sub-instance)
503+
to the Component instead of preferring the `ouptut`. Normally (like in the `useAgile()` Hook),
494504
the `output` of an Agile Sub Instance has a higher weight than the `value`.
495505

496506
For example if we bind a Collection with the `useAgile()` Hook to a React Component,
497507
the `output` of the Collection is bound to the Component.
498508
When we use the `useValue()` Hook instead, the `value` of the Collection is bound to the Component.
499-
```ts
509+
```ts {9,12}
500510
// -- core.js -------------------------------------------------
501511

502512
const MY_COLLECTION = createCollection({
@@ -516,7 +526,7 @@ console.log(collectionOutput); // Returns (see below)
516526
### 👀 Subscribable Instances
517527

518528
Not only AgileTs States can be bound to React Components via `useValue()`,
519-
but also all [Agile Sub Instances](../../../main/Introduction.md#agile-sub-instance)
529+
but also all other [Agile Sub Instances](../../../main/Introduction.md#agile-sub-instance)
520530
that contain an [`Observer`](../../../main/Introduction.md#observer).
521531
```ts
522532
const [myCollection, myGroup, myState] = useValue([MY_COLLECTION, MY_GROUP, MY_STATE]);
@@ -562,7 +572,7 @@ The `useValue()` Hook is almost 100% typesafe.
562572

563573
| Prop | Type | Description | Required |
564574
| ----------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------|
565-
| `deps` | Array<SubscribableAgileInstancesType\> \| SubscribableAgileInstancesType | Agile Sub Instances that are bound to the Component in which the useProxy Hook is located | Yes |
575+
| `deps` | Array<SubscribableAgileInstancesType\> \| SubscribableAgileInstancesType | Agile Sub Instances to be bound to the Functional Component. | Yes |
566576
| `config` | [AgileHookConfigInterface](../../../Interfaces.md#agilehookconfiginterface) | Configuration | No |
567577

568578
#### SubscribableAgileInstancesType
@@ -574,7 +584,7 @@ type SubscribableAgileInstancesType = State | Collection | Observer | undefined;
574584

575585
The `useValue()` Hook returns the current `value`
576586
of the specified [Agile Sub Instance](../../../main/Introduction.md#agile-sub-instance).
577-
```ts {5}
587+
```ts {9}
578588
// -- core.js -------------------------------------------------
579589

580590
const MY_COLLECTION = createCollection({initialData: [
@@ -588,7 +598,7 @@ console.log(myValue); // Returns '[1, 2]'
588598
```
589599
When passing multiple Agile Sub Instances,
590600
an array of `values` matching the passed Instances is returned.
591-
```ts {6}
601+
```ts {10}
592602
// -- core.js --------------------------------------------------
593603

594604
const MY_COLLECTION = createCollection({initialData: [
@@ -614,6 +624,7 @@ console.log(myState2); // Returns 'frank'
614624

615625

616626
## `useWatcher()`
627+
617628
Creates a `callback` that observes the State on changes.
618629
The provided `callback` function will be fired on every State `value` mutation.
619630
For instance if we update the State value from 'jeff' to 'hans'.

0 commit comments

Comments
 (0)