Merge pull request #1984 from genesiscommunitysuccess/mw/PTL-1507-fou…

…ndation-store

docs: foundation store written and API docs PTL-1507

docs/001_develop/03_client-capabilities/015_layout-management/layout_05_binding_events_store.mdx

@@ -64,7 +64,7 @@ This works because the bindings and events run _after_ the cloneNode() call, so
 
 The question you may ask with the above answer is how you access the properties which are represented in `${ ... }`. If they were statically defined functions or `const` values on the class, then you can move them onto the `ContainerElement` class. More likely though they are dynamically generated.
 
-This is where we'll want to use some formal state management. This section will rely on your knowledge of FoundationStore <!-- TODO link -->. The store is already set up out of the box with applications created from Genesis Create or using the Genesis CLI `genx`.
+This is where we'll want to use some formal state management. This section will rely on your knowledge of [`foundation-store`](../../state-management/). The store is already set up out of the box with applications created from Genesis Create or using the Genesis CLI `genx`.
 
 ### Pre-layout example
 
@@ -231,4 +231,4 @@ WrapperTwo;
 export class MyElement extends GenesisElement { }
 ```
 
-We've covered the pitfalls that occur when trying to add the layout to a group of elements that share state and bindings, and a way to solve that via the foundation store. <!-- TODO add link again to store -->
+We've covered the pitfalls that occur when trying to add the layout to a group of elements that share state and bindings, and a way to solve that via the [`foundation-store`](../../state-management/).

docs/001_develop/03_client-capabilities/017_state-management/docs/_category_.yml

@@ -0,0 +1 @@
+className: 'hidden'

docs/001_develop/03_client-capabilities/017_state-management/docs/api/foundation-store.abstractstore._constructor_.md

@@ -0,0 +1,23 @@
+---
+format: md
+---
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-store](./foundation-store.md) &gt; [AbstractStore](./foundation-store.abstractstore.md) &gt; [(constructor)](./foundation-store.abstractstore._constructor_.md)
+
+## AbstractStore.(constructor)
+
+Constructs a new instance of the `AbstractStore` class
+
+**Signature:**
+
+```typescript
+constructor(...storeFragments: Store[]);
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  storeFragments | [Store](./foundation-store.store.md)\[\] | The child store fragments this store fragment will manage. |
+

docs/001_develop/03_client-capabilities/017_state-management/docs/api/foundation-store.abstractstore.addstorefragments.md

@@ -0,0 +1,27 @@
+---
+format: md
+---
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-store](./foundation-store.md) &gt; [AbstractStore](./foundation-store.abstractstore.md) &gt; [addStoreFragments](./foundation-store.abstractstore.addstorefragments.md)
+
+## AbstractStore.addStoreFragments() method
+
+Lazily add store fragments.
+
+**Signature:**
+
+```typescript
+addStoreFragments(...storeFragments: Store[]): void;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  storeFragments | [Store](./foundation-store.store.md)\[\] | Store fragments to add. |
+
+**Returns:**
+
+void
+

docs/001_develop/03_client-capabilities/017_state-management/docs/api/foundation-store.abstractstore.binding.md

@@ -0,0 +1,32 @@
+---
+format: md
+---
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-store](./foundation-store.md) &gt; [AbstractStore](./foundation-store.abstractstore.md) &gt; [binding](./foundation-store.abstractstore.binding.md)
+
+## AbstractStore.binding() method
+
+An api to allow the observation of values and arbitrary bindings outside the template engine.
+
+**Signature:**
+
+```typescript
+binding<TReturn = any, TParent = any>(token: ((store: this) => TReturn) | keyof this, subscriberChangeCallback?: SubscriberChangeCallback<TReturn> | undefined, isVolatileBinding?: boolean, context?: ExecutionContext): BindingObserver<this, TReturn, TParent>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  token | ((store: this) =&gt; TReturn) \| keyof this | A store lookup token which can take various forms. |
+|  subscriberChangeCallback | [SubscriberChangeCallback](./foundation-store.subscriberchangecallback.md)&lt;TReturn&gt; \| undefined | _(Optional)_ [SubscriberChangeCallback](./foundation-store.subscriberchangecallback.md) |
+|  isVolatileBinding | boolean | _(Optional)_ Indicates the binding is volatile. |
+|  context | ExecutionContext | _(Optional)_  |
+
+**Returns:**
+
+BindingObserver&lt;this, TReturn, TParent&gt;
+
+An rxjs Observable
+

docs/001_develop/03_client-capabilities/017_state-management/docs/api/foundation-store.abstractstore.bindingasrx.md

@@ -0,0 +1,19 @@
+---
+format: md
+---
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-store](./foundation-store.md) &gt; [AbstractStore](./foundation-store.abstractstore.md) &gt; [bindingAsRx](./foundation-store.abstractstore.bindingasrx.md)
+
+## AbstractStore.bindingAsRx() method
+
+
+**Signature:**
+
+```typescript
+bindingAsRx(): RXObservable<this>;
+```
+**Returns:**
+
+RXObservable&lt;this&gt;
+

docs/001_develop/03_client-capabilities/017_state-management/docs/api/foundation-store.abstractstore.bindingasrx_1.md

@@ -0,0 +1,26 @@
+---
+format: md
+---
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-store](./foundation-store.md) &gt; [AbstractStore](./foundation-store.abstractstore.md) &gt; [bindingAsRx](./foundation-store.abstractstore.bindingasrx_1.md)
+
+## AbstractStore.bindingAsRx() method
+
+
+**Signature:**
+
+```typescript
+bindingAsRx<TKey extends keyof this>(key: TKey): RXObservable<this[TKey]>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  key | TKey |  |
+
+**Returns:**
+
+RXObservable&lt;this\[TKey\]&gt;
+

docs/001_develop/03_client-capabilities/017_state-management/docs/api/foundation-store.abstractstore.bindingasrx_2.md

@@ -0,0 +1,26 @@
+---
+format: md
+---
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-store](./foundation-store.md) &gt; [AbstractStore](./foundation-store.abstractstore.md) &gt; [bindingAsRx](./foundation-store.abstractstore.bindingasrx_2.md)
+
+## AbstractStore.bindingAsRx() method
+
+
+**Signature:**
+
+```typescript
+bindingAsRx<TReturn>(getter: (store: this) => TReturn): RXObservable<TReturn>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  getter | (store: this) =&gt; TReturn |  |
+
+**Returns:**
+
+RXObservable&lt;TReturn&gt;
+

docs/001_develop/03_client-capabilities/017_state-management/docs/api/foundation-store.abstractstore.commit.md

@@ -0,0 +1,31 @@
+---
+format: md
+---
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-store](./foundation-store.md) &gt; [AbstractStore](./foundation-store.abstractstore.md) &gt; [commit](./foundation-store.abstractstore.commit.md)
+
+## AbstractStore.commit property
+
+> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+The value commit proxy.
+
+**Signature:**
+
+```typescript
+protected readonly commit: this;
+```
+
+## Remarks
+
+this.commit has the same interface as the store itself, so props are strongly typed.
+
+## Example
+
+
+```ts
+this.commit.propX = value;
+```
+

docs/001_develop/03_client-capabilities/017_state-management/docs/api/foundation-store.abstractstore.commitvalue.md

@@ -0,0 +1,31 @@
+---
+format: md
+---
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-store](./foundation-store.md) &gt; [AbstractStore](./foundation-store.abstractstore.md) &gt; [commitValue](./foundation-store.abstractstore.commitvalue.md)
+
+## AbstractStore.commitValue() method
+
+> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Alternative value commit api.
+
+**Signature:**
+
+```typescript
+protected commitValue<K extends keyof TStore>(key: K, value: TStore[K]): void;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  key | K | The property key from the store's interface. |
+|  value | TStore\[K\] | The value to set. |
+
+**Returns:**
+
+void
+

docs/001_develop/03_client-capabilities/017_state-management/docs/api/foundation-store.abstractstore.connect.md

@@ -0,0 +1,27 @@
+---
+format: md
+---
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-store](./foundation-store.md) &gt; [AbstractStore](./foundation-store.abstractstore.md) &gt; [connect](./foundation-store.abstractstore.connect.md)
+
+## AbstractStore.connect() method
+
+Connects this store fragment.
+
+**Signature:**
+
+```typescript
+connect(root: TStoreRoot): void;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  root | TStoreRoot | The store root fragment. |
+
+**Returns:**
+
+void
+

docs/001_develop/03_client-capabilities/017_state-management/docs/api/foundation-store.abstractstore.createasynclistener.md

@@ -0,0 +1,55 @@
+---
+format: md
+---
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-store](./foundation-store.md) &gt; [AbstractStore](./foundation-store.abstractstore.md) &gt; [createAsyncListener](./foundation-store.abstractstore.createasynclistener.md)
+
+## AbstractStore.createAsyncListener property
+
+Creates an async event listener.
+
+**Signature:**
+
+```typescript
+protected createAsyncListener: <TDetail = void, TReturn = void>(keys: KeyOrKeys<TEventDetailMap & TInternalEventDetailMap>, token: (detail: TDetail, event?: CustomEvent<TDetail>) => Promise<TReturn>) => EventListener;
+```
+
+## Remarks
+
+You can think of this like an `effect` in the redux sense. You should not commit values to the store in these, instead raise subsequent events to be handled synchronously, where commits are allowed.
+
+## Example 1
+
+Creating an interface defined handler for a single event key.
+
+```ts
+onDomainAction = this.createAsyncListener<DomainActionDetail>(
+  'domain-action',
+  async ({ id, message }) =>
+    this.invokeAsyncAPI(
+      async () => this.domainService.action(id, message),
+      'domain-action-error',
+      'domain-action-success'
+    )
+);
+```
+
+## Example 2
+
+Creating an anonymous handler in the constructor for multiple event keys.
+
+```ts
+this.createAsyncListener(
+  [
+    'columns-changed',
+    'types-changed',
+    'max-rows-changed',
+    'max-view-changed',
+    'order-by-changed',
+    'reverse-changed',
+  ],
+  async (_, { type }) => this.emit('domain-load')
+);
+```
+

docs/001_develop/03_client-capabilities/017_state-management/docs/api/foundation-store.abstractstore.createerrorlistener.md

@@ -0,0 +1,21 @@
+---
+format: md
+---
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-store](./foundation-store.md) &gt; [AbstractStore](./foundation-store.abstractstore.md) &gt; [createErrorListener](./foundation-store.abstractstore.createerrorlistener.md)
+
+## AbstractStore.createErrorListener property
+
+Creates an error event listener.
+
+**Signature:**
+
+```typescript
+protected createErrorListener: <TDetail extends Error = Error>(keys: KeyOrKeys<TEventDetailMap & TInternalEventDetailMap>, token?: (detail: TDetail, event?: CustomEvent<TDetail>) => void) => EventListener;
+```
+
+## Remarks
+
+This logs and stores errors by event key in the store fragment's [ErrorMap](./foundation-store.errormap.md), allowing multiple errors to co-exist, and be presentable to the user via the UI for further action or dismissal.
+

docs/001_develop/03_client-capabilities/017_state-management/docs/api/foundation-store.abstractstore.createlistener.md

@@ -0,0 +1,21 @@
+---
+format: md
+---
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-store](./foundation-store.md) &gt; [AbstractStore](./foundation-store.abstractstore.md) &gt; [createListener](./foundation-store.abstractstore.createlistener.md)
+
+## AbstractStore.createListener property
+
+Creates an event listener.
+
+**Signature:**
+
+```typescript
+protected createListener: <TDetail = void>(keys: KeyOrKeys<TEventDetailMap & TInternalEventDetailMap>, token: (detail: TDetail, event?: CustomEvent<TDetail>) => void) => EventListener;
+```
+
+## Remarks
+
+You can think of this like a `reducer` in the redux sense. You are allowed to commit values to the store in these synchronous handlers.
+

docs/001_develop/03_client-capabilities/017_state-management/docs/api/foundation-store.abstractstore.disconnect.md

@@ -0,0 +1,27 @@
+---
+format: md
+---
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-store](./foundation-store.md) &gt; [AbstractStore](./foundation-store.abstractstore.md) &gt; [disconnect](./foundation-store.abstractstore.disconnect.md)
+
+## AbstractStore.disconnect() method
+
+Disconnects this store fragment.
+
+**Signature:**
+
+```typescript
+disconnect(root: TStoreRoot): void;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  root | TStoreRoot | The store root fragment. |
+
+**Returns:**
+
+void
+