@genesislcap/foundation-layout 14.84.0 → 14.85.0

package/dist/esm/main/layout-main.js

@@ -1,4 +1,4 @@
-var _FoundationLayout__boundPreDeletionListener, _FoundationLayout__boundDragListener, _a;
+var _FoundationLayout__boundDragListener, _a;
 import { __classPrivateFieldGet, __classPrivateFieldSet, __decorate } from "tslib";
 import { GoldenLayout, LayoutConfig, ResolvedLayoutConfig, } from '@genesis-community/golden-layout';
 import { Session } from '@genesislcap/foundation-comms';
@@ -6,7 +6,7 @@ import { layoutCacheDocument, UUID } from '@genesislcap/foundation-utils';
 import { html, attr, observable, when, ref } from '@microsoft/fast-element';
 import { FoundationElement } from '@microsoft/fast-foundation';
 import { globalDraggingStyles, glVisualConfig, layoutStyles } from '../styles';
-import { DEFAULT_RELOAD_BUFFER, LayoutEmitEvents, LayoutReceiveEvents, componentType, AUTOSAVE_KEY, regionConveter, } from '../utils/';
+import { DEFAULT_RELOAD_BUFFER, LayoutEmitEvents, LayoutReceiveEvents, componentType, AUTOSAVE_KEY, regionConveter, instanceContainer, } from '../utils/';
 import { getMissingArrayItems } from '../utils/';
 import { LayoutRegistrationError, LayoutUsageError } from '../utils/error';
 import { logger } from '../utils/logger';
@@ -88,14 +88,13 @@ export class FoundationLayout extends FoundationElement {
          */
         this.lifecycleUpdateToken = undefined;
         /** @internal */
-        _FoundationLayout__boundPreDeletionListener.set(this, undefined);
-        /** @internal */
         _FoundationLayout__boundDragListener.set(this, undefined);
         this.onDragStart = this.onDragStart.bind(this);
         this.onDragStop = this.onDragStop.bind(this);
         this.cacheAndSaveLayout = this.cacheAndSaveLayout.bind(this);
         this.onPostItemRemoved = this.onPostItemRemoved.bind(this);
         this.onPreItemRemoved = this.onPreItemRemoved.bind(this);
+        this.onAutosaveRequest = this.onAutosaveRequest.bind(this);
     }
     /** @internal */
     connectedCallback() {
@@ -111,18 +110,24 @@ export class FoundationLayout extends FoundationElement {
                 .catch((e) => console.error('Failed to replace styles:', e));
             appliedGlobalStyles = true;
         }
+        // golden layout events
         this.shadowRoot.addEventListener('dragStart', this.onDragStart, true);
         this.shadowRoot.addEventListener('dragStop', this.onDragStop, true);
         this.shadowRoot.addEventListener('closeButtonPre', this.onPreItemRemoved, true);
         this.shadowRoot.addEventListener('closeButtonPressed', this.onPostItemRemoved, true);
+        // events.ts events
+        this.shadowRoot.addEventListener(LayoutReceiveEvents.autosave, this.onAutosaveRequest, true);
         this.setupCustomButtons();
     }
     /** @internal */
     disconnectedCallback() {
+        // golden layout events
         this.shadowRoot.removeEventListener('dragStart', this.onDragStart);
         this.shadowRoot.removeEventListener('dragStop', this.onDragStop);
         this.shadowRoot.removeEventListener('closeButtonPre', this.onPreItemRemoved);
         this.shadowRoot.removeEventListener('closeButtonPressed', this.onPostItemRemoved);
+        // events.ts events
+        this.shadowRoot.addEventListener(LayoutReceiveEvents.autosave, this.onAutosaveRequest);
     }
     /** @internal */
     onDragStart() {
@@ -153,6 +158,10 @@ export class FoundationLayout extends FoundationElement {
         this.$emit(LayoutEmitEvents.itemResized);
         this.cacheAndSaveLayout();
     }
+    /** @internal */
+    onAutosaveRequest() {
+        this.cacheAndSaveLayout();
+    }
     /**
      * JS API, public
      */
@@ -194,9 +203,22 @@ export class FoundationLayout extends FoundationElement {
     /**
      * @public
      * Gets a minified string containing the config describing the current layout of the layout object to later restore in {@link FoundationLayout.loadLayout | function}
+     * @remarks
+     * Includes any state for a contained component exposed by the {@link LayoutComponentWithState} interface.
      * @returns - latest version of {@link SerialisedLayout} describing the layout
      */
     getLayout() {
+        const componentCollection = this.getLayoutComponents();
+        componentCollection.forEach((items) => {
+            if (!items.length)
+                return;
+            const orderedStates = [...items].map((item) => { var _b; return (_b = item.getCurrentState) === null || _b === void 0 ? void 0 : _b.call(item); });
+            const componentInstanceContainer = items[0][instanceContainer];
+            componentInstanceContainer.container.setState({
+                instance: componentInstanceContainer.instance,
+                orderedStates,
+            });
+        });
         return { v: '1', c: ResolvedLayoutConfig.minifyConfig(this.layout.saveLayout()) };
     }
     /**
@@ -413,6 +435,9 @@ export class FoundationLayout extends FoundationElement {
          *
          * This has the effect of allowing us to create multiple instances of the same registered item, and each
          * created instance is separate allowing it to implement its own serialise and cache of data.
+         *
+         * As part of creating each instance we attach a reference to the instance container which is used
+         * to be able to optionally save state, and any state which has been saved we apply to the component.
          */
         const registrationFunction = (() => {
             // Use appendChild to consume the elements and save them in the master copy
@@ -433,11 +458,25 @@ export class FoundationLayout extends FoundationElement {
                 // the key point is "cloneNode" which makes a copy at this point
                 if (!instances.has(state === null || state === void 0 ? void 0 : state['instance'])) {
                     const instanceCopy = document.createDocumentFragment();
-                    Array.from(masterCopy.children).forEach((e) => instanceCopy.appendChild(e.cloneNode(true)));
+                    Array.from(masterCopy.children).forEach((e) => {
+                        instanceCopy.appendChild(e.cloneNode(true));
+                    });
                     instances.set(state['instance'], [...instanceCopy.children]);
                 }
+                // provide each component with a reference to the instance container
+                // so they can optionally save and load their own state
+                const componentInstanceContainer = {
+                    container,
+                    instance: state['instance'],
+                };
+                const instanceOrderedStates = state['orderedStates'] || [];
                 // get the instance from the map and append it to the container
-                instances.get(state['instance']).forEach((e) => container.element.appendChild(e));
+                instances.get(state['instance']).forEach((component, i) => {
+                    var _b, _c;
+                    (_b = component.applyState) === null || _b === void 0 ? void 0 : _b.call(component, (_c = instanceOrderedStates[i]) !== null && _c !== void 0 ? _c : null);
+                    container.element.appendChild(component);
+                    component[instanceContainer] = componentInstanceContainer;
+                });
                 this.setupLayoutReceiveEvents(container, state);
             };
         })();
@@ -550,8 +589,17 @@ export class FoundationLayout extends FoundationElement {
             });
         });
     }
+    /**
+     * Return an array of each contained items in the layout.
+     * @internal
+     */
+    getLayoutComponents() {
+        return [...this.shadowRoot.querySelectorAll('div.lm_content')].map((container) => [
+            ...container.children,
+        ]);
+    }
 }
-_FoundationLayout__boundPreDeletionListener = new WeakMap(), _FoundationLayout__boundDragListener = new WeakMap(), _a = componentType;
+_FoundationLayout__boundDragListener = new WeakMap(), _a = componentType;
 __decorate([
     attr({ attribute: 'reload-buffer' })
 ], FoundationLayout.prototype, "reloadBuffer", void 0);

package/dist/esm/utils/constants.js

@@ -3,6 +3,11 @@
  * @internal
  */
 export const componentType = Symbol('component-type');
+/**
+ * Used to key a reference to the instance and golden layout container on a layout component.
+ * @internal
+ */
+export const instanceContainer = Symbol('component-instance');
 /**
  * Default time in milliseconds for the layout to buffer calls to reloading
  * the layout while the declarative API is loading.

package/dist/esm/utils/events.js

@@ -21,8 +21,10 @@ export const LayoutEmitEvents = {
  * Defines events that the layout system listens for
  *
  * 'changeTitle' - emit this from a contained item to update the title of the window that contains it.
+ * 'autosave' - emit this from a contained item to hint to the layout system that it should autosave the layout. A contained item should do this if it has just changed some state it would like to persist. See {@link LayoutComponentWithState}.
  * @public
  */
 export const LayoutReceiveEvents = {
     changeTitle: 'change-title',
+    autosave: 'autosave',
 };

package/dist/esm/utils/types.js

@@ -1,3 +1,3 @@
-import { componentType } from './constants';
+import { componentType, instanceContainer } from './constants';
 /** @internal */
 export const layoutRegionValue = ['horizontal', 'vertical', 'tabs'];

package/dist/foundation-layout.api.json

@@ -496,7 +496,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/foundation-layout!FoundationLayout#getLayout:member(1)",
-              "docComment": "/**\n * Gets a minified string containing the config describing the current layout of the layout object to later restore in {@link FoundationLayout.loadLayout | function}\n *\n * @returns - latest version of {@link SerialisedLayout} describing the layout\n *\n * @public\n */\n",
+              "docComment": "/**\n * Gets a minified string containing the config describing the current layout of the layout object to later restore in {@link FoundationLayout.loadLayout | function}\n *\n * @remarks\n *\n * Includes any state for a contained component exposed by the {@link LayoutComponentWithState} interface.\n *\n * @returns - latest version of {@link SerialisedLayout} describing the layout\n *\n * @public\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -1401,6 +1401,110 @@
             "endIndex": 2
           }
         },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@genesislcap/foundation-layout!LayoutComponentWithState:interface",
+          "docComment": "/**\n * Interface to implement on an item which is a component of the layout and you wish to serialise state with. This is saved separately for each instance of the component, which allows you to restore multiple instances of the same component with different state.\n *\n * @remarks\n *\n * When the layout is saved either via the autosave functionality or manually calling {@link FoundationLayout.getLayout}, all contained components will be requested to provide state if they wish.\n *\n * Any state which is provided will be saved as part of the layout config and will be passed back to the component when the layout is reloaded. Before an item is appended onto the layout DOM, the state will be applied to the component via `applyState`. You will likely want to cache this and then use it later in the lifecycle of the component. The state is `null` when the instance is first created.\n *\n * See the written documentation for some error scenarios to consider about when implementing this interface.\n *\n * @typeParam T - the type of the state object you wish to serialise with the component.\n *\n * @example\n * ```\n * type ComponentState = {\n *   foo: string;\n * }\n * \\@customElement({ name: 'my-component' })\n * export class MyComponent extends FASTElement implements LayoutComponentWithState<ComponentState> {\n *   \\@observable foo: string;\n *   private fooCache: ComponentState | null;\n *\n *   getCurrentState(): ComponentState {\n *     if (!this.foo) return null;\n *     return {\n *       foo: this.foo;\n *     }\n *   }\n *\n *   applyState(state: ComponentState | null) {\n *     this.fooCache = state;\n *   }\n *\n *   connectedCallback() {\n *     // do other required setup\n *     if (this.fooCache) {\n *       this.foo = this.fooCache.foo;\n *     }\n *   }\n * }\n * ```\n *\n * @example\n *\n * If you are using the autosave functionality you should inform the layout system when you update the state of a component, otherwise the state will only be updated when the user performs an action such as resizing an item. Use the {@link LayoutReceiveEvents} `autosave` event.\n * ```\n * // Same component as above\n * export class MyComponent extends FASTElement implements LayoutComponentWithState<ComponentState> {\n *  // can use xChanged pattern as `foo` was declared observable\n *  fooChanged() {\n *    this.$emit(LayoutReceiveEvents.autosave);\n *  }\n * }\n * ```\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface LayoutComponentWithState<T> "
+            }
+          ],
+          "fileUrlPath": "src/utils/types.ts",
+          "releaseTag": "Public",
+          "typeParameters": [
+            {
+              "typeParameterName": "T",
+              "constraintTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            }
+          ],
+          "name": "LayoutComponentWithState",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@genesislcap/foundation-layout!LayoutComponentWithState#applyState:member(1)",
+              "docComment": "/**\n * Handle any state that has been saved previously for this instance of this component. This will be called before the component is appended to the DOM. Due to the lifecycle events not running by this point, it is recommended you cache the state and then apply it in `connectedCallback`.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "applyState(state: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "T | null"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": false,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "releaseTag": "Public",
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "state",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                }
+              ],
+              "name": "applyState"
+            },
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@genesislcap/foundation-layout!LayoutComponentWithState#getCurrentState:member(1)",
+              "docComment": "/**\n * Provide the state you wish to save. It is recommended if the component which implements this interface has not fully initialised at the point this is called that you return `null` as the state, following the pattern of `null` being set as the initial state.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getCurrentState(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "T"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": false,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "overloadIndex": 1,
+              "parameters": [],
+              "name": "getCurrentState"
+            }
+          ],
+          "extendsTokenRanges": []
+        },
         {
           "kind": "Variable",
           "canonicalReference": "@genesislcap/foundation-layout!LayoutEmitEvents:var",
@@ -1427,7 +1531,7 @@
         {
           "kind": "Variable",
           "canonicalReference": "@genesislcap/foundation-layout!LayoutReceiveEvents:var",
-          "docComment": "/**\n * Defines events that the layout system listens for\n *\n * 'changeTitle' - emit this from a contained item to update the title of the window that contains it.\n *\n * @public\n */\n",
+          "docComment": "/**\n * Defines events that the layout system listens for\n *\n * 'changeTitle' - emit this from a contained item to update the title of the window that contains it. 'autosave' - emit this from a contained item to hint to the layout system that it should autosave the layout. A contained item should do this if it has just changed some state it would like to persist. See {@link LayoutComponentWithState}.\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -1435,7 +1539,7 @@
             },
             {
               "kind": "Content",
-              "text": "{\n    readonly changeTitle: \"change-title\";\n}"
+              "text": "{\n    readonly changeTitle: \"change-title\";\n    readonly autosave: \"autosave\";\n}"
             }
           ],
           "fileUrlPath": "src/utils/events.ts",
@@ -1450,7 +1554,7 @@
         {
           "kind": "TypeAlias",
           "canonicalReference": "@genesislcap/foundation-layout!LayoutReceiveEventsDetail:type",
-          "docComment": "/**\n * Defines the shape of the detail that the layout listens works with for events it listens on\n *\n * 'changeTitle' - `title` is the string you want to set. For `mode`: `replace` will set the title to be `title`, `suffix` will append `title` to the end of the existing title.\n *\n * @public\n */\n",
+          "docComment": "/**\n * Defines the shape of the detail that the layout listens works with for events it listens on\n *\n * 'changeTitle' - `title` is the string you want to set. For `mode`: `replace` will set the title to be `title`, `suffix` will append `title` to the end of the existing title. 'autosave' - no other parameters.\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -1458,7 +1562,7 @@
             },
             {
               "kind": "Content",
-              "text": "{\n    changeTitle: {\n        title: string;\n        mode: 'replace' | 'suffix';\n    };\n}"
+              "text": "{\n    changeTitle: {\n        title: string;\n        mode: 'replace' | 'suffix';\n    };\n    autosave: void;\n}"
             },
             {
               "kind": "Content",

package/dist/foundation-layout.d.ts

@@ -137,6 +137,8 @@ export declare class FoundationLayout extends FoundationElement implements Layou
     private onPostItemRemoved;
     /** @internal */
     private onPostItemResized;
+    /** @internal */
+    private onAutosaveRequest;
     /**
      * JS API, public
      */
@@ -165,6 +167,8 @@ export declare class FoundationLayout extends FoundationElement implements Layou
     /**
      * @public
      * Gets a minified string containing the config describing the current layout of the layout object to later restore in {@link FoundationLayout.loadLayout | function}
+     * @remarks
+     * Includes any state for a contained component exposed by the {@link LayoutComponentWithState} interface.
      * @returns - latest version of {@link SerialisedLayout} describing the layout
      */
     getLayout(): SerialisedLayout;
@@ -306,6 +310,11 @@ export declare class FoundationLayout extends FoundationElement implements Layou
      * @internal
      */
     private setupCustomButtons;
+    /**
+     * Return an array of each contained items in the layout.
+     * @internal
+     */
+    private getLayoutComponents;
 }
 
 /**
@@ -480,6 +489,70 @@ declare interface LayoutComponent {
     requestLayoutReload(): void;
 }
 
+/**
+ * Interface to implement on an item which is a component of the layout and you wish to serialise state with. This is saved separately for each instance of the component, which allows you to restore multiple instances of the same component with different state.
+ * @typeParam T - the type of the state object you wish to serialise with the component.
+ * @remarks
+ * When the layout is saved either via the autosave functionality or manually calling {@link FoundationLayout.getLayout}, all contained components will be requested to provide state if they wish.
+ *
+ * Any state which is provided will be saved as part of the layout config and will be passed back to the component when the layout is reloaded. Before an item is appended onto the layout DOM, the state will be applied to the component via `applyState`. You will likely want to cache this and then use it later in the lifecycle of the component. The state is `null` when the instance is first created.
+ *
+ * See the written documentation for some error scenarios to consider about when implementing this interface.
+ *
+ * @example
+ * ```
+ * type ComponentState = {
+ *   foo: string;
+ * }
+ * \@customElement({ name: 'my-component' })
+ * export class MyComponent extends FASTElement implements LayoutComponentWithState<ComponentState> {
+ *   \@observable foo: string;
+ *   private fooCache: ComponentState | null;
+ *
+ *   getCurrentState(): ComponentState {
+ *     if (!this.foo) return null;
+ *     return {
+ *       foo: this.foo;
+ *     }
+ *   }
+ *
+ *   applyState(state: ComponentState | null) {
+ *     this.fooCache = state;
+ *   }
+ *
+ *   connectedCallback() {
+ *     // do other required setup
+ *     if (this.fooCache) {
+ *       this.foo = this.fooCache.foo;
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * If you are using the autosave functionality you should inform the layout system when you update the state of a component, otherwise the state will only be updated when the user performs an action such as resizing an item. Use the {@link LayoutReceiveEvents} `autosave` event.
+ * ```
+ * // Same component as above
+ * export class MyComponent extends FASTElement implements LayoutComponentWithState<ComponentState> {
+ *  // can use xChanged pattern as `foo` was declared observable
+ *  fooChanged() {
+ *    this.$emit(LayoutReceiveEvents.autosave);
+ *  }
+ * }
+ * ```
+ * @public
+ * */
+export declare interface LayoutComponentWithState<T> {
+    /**
+     * Provide the state you wish to save. It is recommended if the component which implements this interface has not fully initialised at the point this is called that you return `null` as the state, following the pattern of `null` being set as the initial state.
+     */
+    getCurrentState(): T;
+    /**
+     * Handle any state that has been saved previously for this instance of this component. This will be called before the component is appended to the DOM. Due to the lifecycle events not running by this point, it is recommended you cache the state and then apply it in `connectedCallback`.
+     */
+    applyState(state: T | null): void;
+}
+
 /**
  * Defines events that the layout system emits
  *
@@ -504,16 +577,19 @@ export declare const LayoutEmitEvents: {
  * Defines events that the layout system listens for
  *
  * 'changeTitle' - emit this from a contained item to update the title of the window that contains it.
+ * 'autosave' - emit this from a contained item to hint to the layout system that it should autosave the layout. A contained item should do this if it has just changed some state it would like to persist. See {@link LayoutComponentWithState}.
  * @public
  */
 export declare const LayoutReceiveEvents: {
     readonly changeTitle: "change-title";
+    readonly autosave: "autosave";
 };
 
 /**
  * Defines the shape of the detail that the layout listens works with for events it listens on
  *
  * 'changeTitle' - `title` is the string you want to set. For `mode`: `replace` will set the title to be `title`, `suffix` will append `title` to the end of the existing title.
+ * 'autosave' - no other parameters.
  * @public
  */
 export declare type LayoutReceiveEventsDetail = {
@@ -521,6 +597,7 @@ export declare type LayoutReceiveEventsDetail = {
         title: string;
         mode: 'replace' | 'suffix';
     };
+    autosave: void;
 };
 
 /**

package/docs/api/foundation-layout.foundationlayout.getlayout.md

@@ -17,3 +17,7 @@ getLayout(): SerialisedLayout;
 
 - latest version of [SerialisedLayout](./foundation-layout.serialisedlayout.md) describing the layout
 
+## Remarks
+
+Includes any state for a contained component exposed by the [LayoutComponentWithState](./foundation-layout.layoutcomponentwithstate.md) interface.
+

package/docs/api/foundation-layout.layoutcomponentwithstate.applystate.md

@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-layout](./foundation-layout.md) &gt; [LayoutComponentWithState](./foundation-layout.layoutcomponentwithstate.md) &gt; [applyState](./foundation-layout.layoutcomponentwithstate.applystate.md)
+
+## LayoutComponentWithState.applyState() method
+
+Handle any state that has been saved previously for this instance of this component. This will be called before the component is appended to the DOM. Due to the lifecycle events not running by this point, it is recommended you cache the state and then apply it in `connectedCallback`<!-- -->.
+
+**Signature:**
+
+```typescript
+applyState(state: T | null): void;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  state | T \| null |  |
+
+**Returns:**
+
+void
+

package/docs/api/foundation-layout.layoutcomponentwithstate.getcurrentstate.md

@@ -0,0 +1,17 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-layout](./foundation-layout.md) &gt; [LayoutComponentWithState](./foundation-layout.layoutcomponentwithstate.md) &gt; [getCurrentState](./foundation-layout.layoutcomponentwithstate.getcurrentstate.md)
+
+## LayoutComponentWithState.getCurrentState() method
+
+Provide the state you wish to save. It is recommended if the component which implements this interface has not fully initialised at the point this is called that you return `null` as the state, following the pattern of `null` being set as the initial state.
+
+**Signature:**
+
+```typescript
+getCurrentState(): T;
+```
+**Returns:**
+
+T
+

package/docs/api/foundation-layout.layoutcomponentwithstate.md

@@ -0,0 +1,75 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-layout](./foundation-layout.md) &gt; [LayoutComponentWithState](./foundation-layout.layoutcomponentwithstate.md)
+
+## LayoutComponentWithState interface
+
+Interface to implement on an item which is a component of the layout and you wish to serialise state with. This is saved separately for each instance of the component, which allows you to restore multiple instances of the same component with different state.
+
+**Signature:**
+
+```typescript
+export interface LayoutComponentWithState<T> 
+```
+
+## Remarks
+
+When the layout is saved either via the autosave functionality or manually calling [FoundationLayout.getLayout()](./foundation-layout.foundationlayout.getlayout.md)<!-- -->, all contained components will be requested to provide state if they wish.
+
+Any state which is provided will be saved as part of the layout config and will be passed back to the component when the layout is reloaded. Before an item is appended onto the layout DOM, the state will be applied to the component via `applyState`<!-- -->. You will likely want to cache this and then use it later in the lifecycle of the component. The state is `null` when the instance is first created.
+
+See the written documentation for some error scenarios to consider about when implementing this interface.
+
+## Example 1
+
+
+```
+type ComponentState = {
+  foo: string;
+}
+\@customElement({ name: 'my-component' })
+export class MyComponent extends FASTElement implements LayoutComponentWithState<ComponentState> {
+  \@observable foo: string;
+  private fooCache: ComponentState | null;
+
+  getCurrentState(): ComponentState {
+    if (!this.foo) return null;
+    return {
+      foo: this.foo;
+    }
+  }
+
+  applyState(state: ComponentState | null) {
+    this.fooCache = state;
+  }
+
+  connectedCallback() {
+    // do other required setup
+    if (this.fooCache) {
+      this.foo = this.fooCache.foo;
+    }
+  }
+}
+```
+
+## Example 2
+
+If you are using the autosave functionality you should inform the layout system when you update the state of a component, otherwise the state will only be updated when the user performs an action such as resizing an item. Use the [LayoutReceiveEvents](./foundation-layout.layoutreceiveevents.md) `autosave` event.
+
+```
+// Same component as above
+export class MyComponent extends FASTElement implements LayoutComponentWithState<ComponentState> {
+ // can use xChanged pattern as `foo` was declared observable
+ fooChanged() {
+   this.$emit(LayoutReceiveEvents.autosave);
+ }
+}
+```
+
+## Methods
+
+|  Method | Description |
+|  --- | --- |
+|  [applyState(state)](./foundation-layout.layoutcomponentwithstate.applystate.md) | Handle any state that has been saved previously for this instance of this component. This will be called before the component is appended to the DOM. Due to the lifecycle events not running by this point, it is recommended you cache the state and then apply it in <code>connectedCallback</code>. |
+|  [getCurrentState()](./foundation-layout.layoutcomponentwithstate.getcurrentstate.md) | Provide the state you wish to save. It is recommended if the component which implements this interface has not fully initialised at the point this is called that you return <code>null</code> as the state, following the pattern of <code>null</code> being set as the initial state. |
+

package/docs/api/foundation-layout.layoutreceiveevents.md

@@ -6,12 +6,13 @@
 
 Defines events that the layout system listens for
 
-'changeTitle' - emit this from a contained item to update the title of the window that contains it.
+'changeTitle' - emit this from a contained item to update the title of the window that contains it. 'autosave' - emit this from a contained item to hint to the layout system that it should autosave the layout. A contained item should do this if it has just changed some state it would like to persist. See [LayoutComponentWithState](./foundation-layout.layoutcomponentwithstate.md)<!-- -->.
 
 **Signature:**
 
 ```typescript
 LayoutReceiveEvents: {
     readonly changeTitle: "change-title";
+    readonly autosave: "autosave";
 }
 ```

package/docs/api/foundation-layout.layoutreceiveeventsdetail.md

@@ -6,7 +6,7 @@
 
 Defines the shape of the detail that the layout listens works with for events it listens on
 
-'changeTitle' - `title` is the string you want to set. For `mode`<!-- -->: `replace` will set the title to be `title`<!-- -->, `suffix` will append `title` to the end of the existing title.
+'changeTitle' - `title` is the string you want to set. For `mode`<!-- -->: `replace` will set the title to be `title`<!-- -->, `suffix` will append `title` to the end of the existing title. 'autosave' - no other parameters.
 
 **Signature:**
 
@@ -16,5 +16,6 @@ export type LayoutReceiveEventsDetail = {
         title: string;
         mode: 'replace' | 'suffix';
     };
+    autosave: void;
 };
 ```

package/docs/api/foundation-layout.md

@@ -18,6 +18,7 @@
 
 |  Interface | Description |
 |  --- | --- |
+|  [LayoutComponentWithState](./foundation-layout.layoutcomponentwithstate.md) | Interface to implement on an item which is a component of the layout and you wish to serialise state with. This is saved separately for each instance of the component, which allows you to restore multiple instances of the same component with different state. |
 |  [RegisteredElementConfig](./foundation-layout.registeredelementconfig.md) | The parameters that can be set on a new item when being added by the [FoundationLayout.addItem()](./foundation-layout.foundationlayout.additem.md) API |
 
 ## Variables
@@ -28,7 +29,7 @@
 |  [foundationLayoutComponents](./foundation-layout.foundationlayoutcomponents.md) | Registration object to register the layout with your design system. |
 |  [LAYOUT\_ICONS](./foundation-layout.layout_icons.md) | A collection of SVG icons in base64 format. |
 |  [LayoutEmitEvents](./foundation-layout.layoutemitevents.md) | <p>Defines events that the layout system emits</p><p>'firstLoaded' - emitted when the layout has finished loading the first time using the declarative API after [DEFAULT\_RELOAD\_BUFFER](./foundation-layout.default_reload_buffer.md) ms. <br/> 'itemAdded' - emitted when an item is added to the layout' <br/> 'itemRemoved' - emitted when an item is removed from the layout' <br/> 'itemResized' - emitted when the user drags the divider to resize elements</p> |
-|  [LayoutReceiveEvents](./foundation-layout.layoutreceiveevents.md) | <p>Defines events that the layout system listens for</p><p>'changeTitle' - emit this from a contained item to update the title of the window that contains it.</p> |
+|  [LayoutReceiveEvents](./foundation-layout.layoutreceiveevents.md) | <p>Defines events that the layout system listens for</p><p>'changeTitle' - emit this from a contained item to update the title of the window that contains it. 'autosave' - emit this from a contained item to hint to the layout system that it should autosave the layout. A contained item should do this if it has just changed some state it would like to persist. See [LayoutComponentWithState](./foundation-layout.layoutcomponentwithstate.md)<!-- -->.</p> |
 |  [layoutStyles](./foundation-layout.layoutstyles.md) | <code>ElementStyles</code> which defines the css for [FoundationLayout](./foundation-layout.foundationlayout.md)<!-- -->. |
 |  [layoutTemplate](./foundation-layout.layouttemplate.md) | <code>ViewTemplate</code> which defines the html for [FoundationLayout](./foundation-layout.foundationlayout.md)<!-- -->. |
 
@@ -37,7 +38,7 @@
 |  Type Alias | Description |
 |  --- | --- |
 |  [CustomButton](./foundation-layout.custombutton.md) | Definition of a custom button which will be added to all layout items. |
-|  [LayoutReceiveEventsDetail](./foundation-layout.layoutreceiveeventsdetail.md) | <p>Defines the shape of the detail that the layout listens works with for events it listens on</p><p>'changeTitle' - <code>title</code> is the string you want to set. For <code>mode</code>: <code>replace</code> will set the title to be <code>title</code>, <code>suffix</code> will append <code>title</code> to the end of the existing title.</p> |
+|  [LayoutReceiveEventsDetail](./foundation-layout.layoutreceiveeventsdetail.md) | <p>Defines the shape of the detail that the layout listens works with for events it listens on</p><p>'changeTitle' - <code>title</code> is the string you want to set. For <code>mode</code>: <code>replace</code> will set the title to be <code>title</code>, <code>suffix</code> will append <code>title</code> to the end of the existing title. 'autosave' - no other parameters.</p> |
 |  [LayoutRegionType](./foundation-layout.layoutregiontype.md) | Union type describing the three different types of region splits. Set on the <code>type</code> attribute on [FoundationLayoutRegion](./foundation-layout.foundationlayoutregion.md)<!-- -->. |
 |  [Placement](./foundation-layout.placement.md) | Where to and how to add the new item(s) into the layout when using the [FoundationLayout.addItem()](./foundation-layout.foundationlayout.additem.md) API. |
 |  [SerialisedLayout](./foundation-layout.serialisedlayout.md) | Versioned layout config objects. <code>v</code> is the version and <code>c</code> contains the layout config. |