@genesislcap/foundation-layout 14.84.1 → 14.85.0-alpha.1360cc6.1

package/README.md

@@ -189,11 +189,13 @@ To enable autosaving the layout see [here](#autosaving-layout).
 
 #### [Get Layout](./docs/api/foundation-layout.foundationlayout.getlayout.md)
 
-Get an object describing the current layout so that it can be restored at a later date. This does not save any data internally to the layout. It is up to the client to store this state where appropriate for later recall (browser local storage, persistence layer, etc.)
+Get an object describing the current layout so that it can be restored at a later date. This does not save any data internally to the layout. It is up to the client to store this state where appropriate for later recall (browser local storage, persistence layer, etc.). Use the [autosaving layout](#autosaving-layout) feature to get the layout to do this for you with local storage.
+
+You can store state for an instance of an item, and that will be saved inline. See [managing state](#managing-state).
 
 #### [Load Layout](./docs/api/foundation-layout.foundationlayout.loadlayout.md)
 
-Loads a serialised layout. All items that are described in the config to load must already be registered with the layout system - using either the declarative or JavaScript API. If there are items missing (could be due either to missing items or to a mismatch of registered names) then a `LayoutUsageError` will be thrown containing the names of the missing items.
+Loads a serialised layout. All items that are described in the config to load must already be registered with the layout system - using either the declarative or JavaScript API. If there are items missing (could be due either to missing items or to a mismatch of registered names) then a `LayoutUsageError` will be thrown containing the names of the missing items. Alternatively, you can request placeholder items to be added.
 
 ## Events
 
@@ -300,6 +302,22 @@ Throughout Foundation UI, there is no need to de-register a component that is re
 
 - Once the component is actually initialised in the layout on the DOM, then `shouldRunConnect` will be true, and you can then perform all the required initialisation.
 
+### Managing state
+
+Items inside of the layout can save and restore state using various methods, but it can become difficult to manage state if you're adding the same item to the layout multiple times (multiple instances of the same web component).
+
+You can implement the [LayoutComponentWithState](./docs/api/foundation-layout.layoutcomponentwithstate.md) interface which will allow you to save and load state *per instance* of your components. See the linked interface and the associated functions API documentation for examples and explanations of usage.
+
+Usage of this interface is optional, if you do not need to manage state for your components in this way then simply do not implement the interface.
+
+:::warning
+The layout system is only interacting with the immediately contained items - so if you have components that contain other components, the top level components will need to interact with the contained components to manage their state.
+:::
+
+:::danger
+Each layout item can contain multiple components, and most of the time there are no extra considerations when doing this. However, the state of each component in an instance is saved in order of the components on the DOM, so if the serialised state is manually changed to have the items out of order with their state, then the incorrect states will be passed into each item. This should not occur during defined behaviour, but is possible if the end-user is able to change the state passed into `loadLayout()` manually.
+:::
+
 ### Element cloning
 
 To enable you to add multiple items from the same `registration`, the layout system clones elements to add to the layout.

package/dist/custom-elements.json

@@ -45,6 +45,14 @@
             "module": "./utils"
           }
         },
+        {
+          "kind": "js",
+          "name": "LayoutComponentWithState",
+          "declaration": {
+            "name": "LayoutComponentWithState",
+            "module": "./utils"
+          }
+        },
         {
           "kind": "js",
           "name": "LayoutEmitEvents",
@@ -1224,10 +1232,10 @@
           "kind": "variable",
           "name": "LayoutReceiveEvents",
           "type": {
-            "text": "{\n  changeTitle: 'change-title',\n}"
+            "text": "{\n  changeTitle: 'change-title',\n  autosave: 'autosave',\n}"
           },
-          "default": "{\n  changeTitle: 'change-title',\n}",
-          "description": "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.",
+          "default": "{\n  changeTitle: 'change-title',\n  autosave: 'autosave',\n}",
+          "description": "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'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.",
           "privacy": "public"
         }
       ],

package/dist/dts/index.d.ts

@@ -1,4 +1,4 @@
 export * from './main';
 export { LAYOUT_ICONS } from './styles';
-export { CustomButton, DEFAULT_RELOAD_BUFFER, LayoutEmitEvents, LayoutReceiveEvents, LayoutReceiveEventsDetail, LayoutRegionType, LayoutRegistrationError, LayoutUsageError, Placement, RegisteredElementConfig, RegistrationConfig, SerialisedLayout, } from './utils';
+export { CustomButton, DEFAULT_RELOAD_BUFFER, LayoutComponentWithState, LayoutEmitEvents, LayoutReceiveEvents, LayoutReceiveEventsDetail, LayoutRegionType, LayoutRegistrationError, LayoutUsageError, Placement, RegisteredElementConfig, RegistrationConfig, SerialisedLayout, } from './utils';
 //# sourceMappingURL=index.d.ts.map

package/dist/dts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,EACzB,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,SAAS,EACT,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,wBAAwB,EACxB,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,EACzB,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,SAAS,EACT,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,SAAS,CAAC"}

package/dist/dts/main/layout-main.d.ts

@@ -102,6 +102,8 @@ export declare class FoundationLayout extends FoundationElement implements Layou
     private onPostItemRemoved;
     /** @internal */
     private onPostItemResized;
+    /** @internal */
+    private onAutosaveRequest;
     /**
      * JS API, public
      */
@@ -130,6 +132,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;
@@ -271,6 +275,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;
 }
 /**
  * `ViewTemplate` which defines the html for {@link FoundationLayout}.

package/dist/dts/main/layout-main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layout-main.d.ts","sourceRoot":"","sources":["../../../src/main/layout-main.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"layout-main.d.ts","sourceRoot":"","sources":["../../../src/main/layout-main.ts"],"names":[],"mappings":"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"}

package/dist/dts/utils/constants.d.ts

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

package/dist/dts/utils/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/utils/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,aAAa,eAA2B,CAAC;AAEtD;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,YAAY,+BAA+B,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/utils/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,aAAa,eAA2B,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,eAA+B,CAAC;AAE9D;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,YAAY,+BAA+B,CAAC"}

package/dist/dts/utils/events.d.ts

@@ -21,15 +21,18 @@ 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 type LayoutReceiveEventsDetail = {
@@ -37,5 +40,6 @@ export type LayoutReceiveEventsDetail = {
         title: string;
         mode: 'replace' | 'suffix';
     };
+    autosave: void;
 };
 //# sourceMappingURL=events.d.ts.map

package/dist/dts/utils/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/utils/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB;;;;;CAKnB,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;CAEtB,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,WAAW,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAA;KAAE,CAAC;CAC5D,CAAC"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/utils/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB;;;;;CAKnB,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB;;;CAGtB,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,WAAW,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAA;KAAE,CAAC;IAC3D,QAAQ,EAAE,IAAI,CAAC;CAChB,CAAC"}

package/dist/dts/utils/types.d.ts

@@ -1,5 +1,5 @@
-import { ResolvedLayoutConfig } from '@genesis-community/golden-layout';
-import { componentType } from './constants';
+import { ComponentContainer, ResolvedLayoutConfig } from '@genesis-community/golden-layout';
+import { componentType, instanceContainer } from './constants';
 /**
  * Definition of a custom button which will be added to all layout items.
  * @remarks
@@ -26,6 +26,69 @@ export type SerialisedLayout = {
     v: '1';
     c: ResolvedLayoutConfig;
 };
+/**
+ * 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 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;
+}
 /**
  * @public
  * The parameters that can be set on a new item when being added by the {@link FoundationLayout.addItem} API
@@ -61,6 +124,15 @@ export type Placement = {
     };
 };
 /** @internal */
+export type InstanceContainer = {
+    container: ComponentContainer;
+    instance: string;
+};
+/** @internal */
+export type LayoutComponentItem<T> = Element & Partial<LayoutComponentWithState<T>> & {
+    [instanceContainer]?: InstanceContainer;
+};
+/** @internal */
 export interface RegistrationConfig {
     elements: Element[];
     id?: string;

package/dist/dts/utils/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/utils/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;CAC9D,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,CAAC,EAAE,GAAG,CAAC;IACP,CAAC,EAAE,oBAAoB,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC1C,QAAQ,CAAC,EAAE;QACT,IAAI,EAAE,gBAAgB,CAAC;QACvB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH,CAAC;AAEF,gBAAgB;AAChB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,gBAAgB;AAChB,eAAO,MAAM,iBAAiB,6CAA8C,CAAC;AAC7E;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAClE,gBAAgB;AAChB,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhE,gBAAgB;AAChB,MAAM,WAAW,eAAe;IAC9B,CAAC,aAAa,CAAC,EAAE,cAAc,CAAC;IAChC,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAAC;IAC7D,mBAAmB,IAAI,IAAI,CAAC;CAC7B;AAED,gBAAgB;AAChB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACrB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/utils/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAC5F,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE/D;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;CAC9D,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,CAAC,EAAE,GAAG,CAAC;IACP,CAAC,EAAE,oBAAoB,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAoDK;AACL,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC;;OAEG;IACH,eAAe,IAAI,CAAC,CAAC;IACrB;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC1C,QAAQ,CAAC,EAAE;QACT,IAAI,EAAE,gBAAgB,CAAC;QACvB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH,CAAC;AAEF,gBAAgB;AAChB,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,kBAAkB,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,gBAAgB;AAChB,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,OAAO,GAC1C,OAAO,CAAC,wBAAwB,CAAC,CAAC,CAAC,CAAC,GAAG;IACrC,CAAC,iBAAiB,CAAC,CAAC,EAAE,iBAAiB,CAAC;CACzC,CAAC;AAEJ,gBAAgB;AAChB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,gBAAgB;AAChB,eAAO,MAAM,iBAAiB,6CAA8C,CAAC;AAC7E;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAClE,gBAAgB;AAChB,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhE,gBAAgB;AAChB,MAAM,WAAW,eAAe;IAC9B,CAAC,aAAa,CAAC,EAAE,cAAc,CAAC;IAChC,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAAC;IAC7D,mBAAmB,IAAI,IAAI,CAAC;CAC7B;AAED,gBAAgB;AAChB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACrB,CAAC"}

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. |

package/docs/api-report.md

@@ -130,6 +130,12 @@ export const LAYOUT_ICONS: {
     readonly tabDropdownSVG: "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NDggNTEyIj48IS0tISBGb250IEF3ZXNvbWUgUHJvIDYuMi4wIGJ5IEBmb250YXdlc29tZSAtIGh0dHBzOi8vZm9udGF3ZXNvbWUuY29tIExpY2Vuc2UgLSBodHRwczovL2ZvbnRhd2Vzb21lLmNvbS9saWNlbnNlIChDb21tZXJjaWFsIExpY2Vuc2UpIENvcHlyaWdodCAyMDIyIEZvbnRpY29ucywgSW5jLiAtLT48cGF0aCBkPSJNNC4yNTEgMTgxLjFDNy4zOTIgMTc3LjcgMTEuNjkgMTc1LjEgMTYgMTc1LjFjMy44OTEgMCA3Ljc4MSAxLjQwNiAxMC44NiA0LjI1bDE5Ny4xIDE4MS4xbDE5Ny4xLTE4MS4xYzYuNS02IDE2LjY0LTUuNjI1IDIyLjYxIC45MDYyYzYgNi41IDUuNTk0IDE2LjU5LS44OTA2IDIyLjU5bC0yMDggMTkyYy02LjE1NiA1LjY4OC0xNS41NiA1LjY4OC0yMS43MiAwbC0yMDgtMTkyQy0xLjM0MyAxOTcuNy0xLjc0OSAxODcuNiA0LjI1MSAxODEuMXoiIGZpbGw9IiM4NzliYTYiLz48L3N2Zz4=";
 };
 
+// @public
+export interface LayoutComponentWithState<T> {
+    applyState(state: T | null): void;
+    getCurrentState(): T;
+}
+
 // @public
 export const LayoutEmitEvents: {
     readonly firstLoaded: "first-loaded";
@@ -141,6 +147,7 @@ export const LayoutEmitEvents: {
 // @public
 export const LayoutReceiveEvents: {
     readonly changeTitle: "change-title";
+    readonly autosave: "autosave";
 };
 
 // @public
@@ -149,6 +156,7 @@ export type LayoutReceiveEventsDetail = {
         title: string;
         mode: 'replace' | 'suffix';
     };
+    autosave: void;
 };
 
 // Warning: (ae-forgotten-export) The symbol "layoutRegionValue" needs to be exported by the entry point index.d.ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/foundation-layout",
   "description": "Genesis Foundation UI App Layout",
-  "version": "14.84.1",
+  "version": "14.85.0-alpha.1360cc6.1",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/foundation-layout.d.ts",
@@ -27,15 +27,15 @@
     "test:debug": "genx test --debug"
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "14.84.1",
-    "@genesislcap/genx": "14.84.1",
+    "@genesislcap/foundation-testing": "14.85.0-alpha.1360cc6.1",
+    "@genesislcap/genx": "14.85.0-alpha.1360cc6.1",
     "rimraf": "^3.0.2"
   },
   "dependencies": {
     "@genesis-community/golden-layout": "^2.10.1",
-    "@genesislcap/foundation-comms": "14.84.1",
-    "@genesislcap/foundation-logger": "14.84.1",
-    "@genesislcap/foundation-utils": "14.84.1",
+    "@genesislcap/foundation-comms": "14.85.0-alpha.1360cc6.1",
+    "@genesislcap/foundation-logger": "14.85.0-alpha.1360cc6.1",
+    "@genesislcap/foundation-utils": "14.85.0-alpha.1360cc6.1",
     "@microsoft/fast-components": "^2.21.3",
     "@microsoft/fast-element": "^1.7.0",
     "@microsoft/fast-foundation": "^2.33.2",
@@ -50,5 +50,5 @@
     "access": "public"
   },
   "customElements": "dist/custom-elements.json",
-  "gitHead": "e623522eeb3e9562298432687cd0fb1a4dfb62a7"
+  "gitHead": "3a5181814b5e3ac8189717c909f64ac0eb133e6b"
 }