@genesislcap/foundation-layout 13.6.0 → 13.7.0

package/README.md

@@ -255,6 +255,11 @@ To enable you to add multiple items from the same `registration`, the layout sys
 This is the case both when items are added with `.addItem()`, and when they are added using the declarative API. Under the hood, this uses the Node [cloneNode](https://developer.mozilla.org/en-US/docs/Web/API/Node/cloneNode) api.
 There are certain limitations to this function, especially when using custom elements with the shadow DOM. [See troubleshooting example](#binding-events-inline-in-the-declarative-api).
 
+:::tip
+As a general rule, if you need to have elements with FAST bindings inside of the layout, wrap them in custom elements.
+:::
+
+If you are writing your own custom element which needs to work inside of the layout follow these steps.
 In the `@genesislcap/foundation-utils` package, there is a mix-in class `LifecycleMixin` which overrides the `cloneNode` API.
 
 ```typescript
@@ -944,6 +949,8 @@ You can then use the custom component in the layout:
 </foundation-layout>
 ```
 
+See [here](#custom-components-to-handle-bindings-and-event-listeners) for a thorough technical explanation.
+
 ### New layout item not displaying
 Say you have the following layout, [the simple example](#simple-example), with autosave enabled.
 ```html
@@ -979,6 +986,30 @@ The user of your layout will move things around and this will cache the layout.
 You and the user will only see the first two items like before. This is because the cached layout is being loaded, which does not contain the
 new item. To fix this you must [invalidate the cache](#invalidating-the-cache).
 
+## Supplementary information
+
+### Custom components to handle bindings and event listeners
+As shown in [this example](#binding-events-inline-in-the-declarative-api) you need to wrap html that uses fast bindings and event listeners into their own custom
+components. This section is a technical explanation for why this is the case. It is required we make use of `cloneNode` to allow the layout to add multiple instances
+of a registered component.
+
+Consider the following which is the order of events of loading the layout when using html that includes bindings.
+
+1. As the DOM is parsed the elements inside of the layout are created. At this point the bindings are attached and the event listeners are created, and the `connectedCallback` lifecycle method executes.
+2. Once all of the layout’s contained elements are created, the layout itself initialises\*.
+3. As part of the initialisation process it moves the element from the DOM and puts it internally into a document fragment as part of the layout registration cache.
+4. We then load golden layout with the layout config and the registered items, where the registered items create a clone of the items in the document fragment.
+
+The issue occurs during step four - the clone from `cloneNode` doesn't have the event listeners, so the new copy (which is the one you see on the layout) has no event listeners. Compare this with the similar but different process if you've wrapped up the html into its own custom component.
+
+1. As the DOM is parsed the elements inside of the layout are created. At this point the bindings are attached and the event listeners are created, and the `connectedCallback` lifecycle method executes.
+2. Once all of the layout’s contained elements are created, the layout itself initialises\*.
+3. As part of the initialisation process it moves the element from the DOM and puts it internally into a document fragment as part of the layout registration cache. This is just a tag such as `<filtered-chart></filtered-chart>` instead of a definition that includes bindings or event listeners.
+4. We then load golden layout with the layout config and the registered items, where the registered items create a clone of the items in the document fragment.
+5. When that clone is put on the DOM, because it is a custom element it calls the lifecycle method again `connectedCallback` as well as other initialisation methods which include attaching the event listener to the component as required.
+
+>>\* It initialises after the timeout specified by the `reload-buffer` attribute if using the declarative HTML API, or steps `3` and `4` occur during calls to `registerItem` and `addItem` respectively.
+
 ## License
 
 Note: this project provides front end dependencies and uses licensed components listed in the next section, thus licenses for those components are required during development. Contact [Genesis Global](https://genesis.global/contact-us/) for more details.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/foundation-layout",
   "description": "Genesis Foundation UI App Layout",
-  "version": "13.6.0",
+  "version": "13.7.0",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/foundation-layout.d.ts",
@@ -37,7 +37,7 @@
     "test:unit:watch": "watchlist src test -- npm run test:unit"
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "^13.6.0",
+    "@genesislcap/foundation-testing": "^13.7.0",
     "@module-federation/dashboard-plugin": "2.3.0",
     "@pixability-ui/federated-types": "^0.2.0",
     "@playwright/test": "^1.18.1",
@@ -77,8 +77,8 @@
   },
   "dependencies": {
     "@genesis-community/golden-layout": "^2.9.3",
-    "@genesislcap/foundation-comms": "^13.6.0",
-    "@genesislcap/foundation-utils": "^13.6.0",
+    "@genesislcap/foundation-comms": "^13.7.0",
+    "@genesislcap/foundation-utils": "^13.7.0",
     "@microsoft/fast-components": "^2.21.3",
     "@microsoft/fast-element": "^1.7.0",
     "@microsoft/fast-foundation": "^2.33.2",
@@ -88,5 +88,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "402177e1b790f32912a0ae57301efe8724f3b92b"
+  "gitHead": "0d725fd8628d9e35f7ac36f15f1e65aac897ddae"
 }