@genesislcap/foundation-layout 14.368.0 → 14.369.0

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

@@ -8,6 +8,7 @@ import { FoundationElement } from '@microsoft/fast-foundation';
 import { globalDraggingStyles, glVisualConfig, LAYOUT_ICONS, layoutStyles } from '../styles';
 import { AUTOSAVE_KEY, componentType, DEFAULT_RELOAD_BUFFER, getMissingArrayItems, instanceContainer, LAYOUT_POPOUT_CONTAINER_CLASS, LAYOUT_POPOUT_CONTROL_KEY, LayoutEmitEvents, LayoutReceiveEvents, regionConveter, } from '../utils/';
 import { LayoutRegistrationError, LayoutUsageError } from '../utils/error';
+import { getFactory } from '../utils/factory-registry';
 import { logger } from '../utils/logger';
 export { layoutStyles } from '../styles';
 /*
@@ -248,6 +249,13 @@ export class FoundationLayout extends FoundationElement {
                 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];
+            // TODO: Factory based components dont handle the LayoutWithState interface, so we need to handle this differently.
+            // For now we will just log a warning and return. We need to assess whether to deprecate that interface and handle it in TAM directly
+            // or whether adding support is needed
+            if (!componentInstanceContainer) {
+                logger.warn('Component instance container not found for items:', items);
+                return;
+            }
             // known use of deprecated API, but there is no other way of implementing it and we control
             // the underlying library anyway
             componentInstanceContainer.container.setState({
@@ -528,28 +536,70 @@ export class FoundationLayout extends FoundationElement {
     }
     /**
      * @public
-     * Register a collection of `Element` and associate them with an `ID` with the layout system for later use.
+     * Register a collection of `Element` or a factory function and associate them with an `ID` with the layout system for later use.
      * @remarks
-     * You would use this to register elements that you later want to load when using {@link FoundationLayout.loadLayout}.
+     * You can register either an array of elements or a factory function.
+     *
+     * **Element registration**: Use this to register elements that you later want to load when using {@link FoundationLayout.loadLayout}.
      * Use {@link FoundationLayout.layoutRequiredRegistrations} to see what components need to be registered for a certain config
      * and then register them using this function before calling {@link FoundationLayout.loadLayout}.
+     * When registering an element it is moved by reference into the internals of the layout, so if you pass elements already in the DOM then they will disappear.
+     * If you want to avoid this you can pass copies using `element.cloneNode(true)`.
      *
-     * When registering an element it is moved by reference into the internals of the layout, so if you pass elements already in the DOM then they will disappear. If you want to avoid this you can pass copies using `element.cloneNode(true)`.
+     * **Factory registration**: This is the recommended approach for framework-rendered components (React, Angular, Vue, etc.)
+     * because it allows each layout instance to create a fresh component rather than cloning existing
+     * DOM elements (which loses event listeners and framework bindings).
+     * The factory function will be called each time a new instance of the component is needed. It receives
+     * a container element and should render the component into it. Optionally, it can return a cleanup
+     * function that will be called when the component is removed from the layout.
      *
      * @param registration - string of the registration ID
-     * @param elements - Elements[] containing the reference to the elements to register for later usage
+     * @param elementsOrFactory - Either Elements[] containing the reference to the elements to register, or a ComponentFactory function
      * @throws {@link LayoutUsageError} if you attempt to add an item before the layout has been initialised.
      * @throws {@link LayoutRegistrationError} if you attempt to use a `registration` name which is already in use (declarative html API and JavaScript API registrations use the same "pool" of registration names).
      * @returns - string defining the name of the registered item with the layout system (config.id if set).
+     *
+     * @example
+     * Element registration:
+     * ```typescript
+     * const div = document.createElement('div');
+     * div.innerHTML = '<h1>Hello</h1>';
+     * layout.registerItem('my-element', [div]);
+     * ```
+     *
+     * @example
+     * Factory registration (React):
+     * ```typescript
+     * layout.registerItem('text-field', (container) => {
+     *   const root = createRoot(container);
+     *   root.render(<TextFieldComponent />);
+     *   return () => root.unmount();
+     * });
+     * ```
      */
-    registerItem(registration, elements) {
+    registerItem(registration, elementsOrFactory) {
         if (!this.layout.isInitialised) {
             throw new LayoutUsageError('Cannot add item via JS API until initialised');
         }
-        return this.cacheElementsAndRegister({
-            elements: elements,
-            id: registration,
-        });
+        // Check if a factory is already registered with this name
+        const existingFactory = getFactory(registration);
+        if (existingFactory) {
+            throw new LayoutRegistrationError(`Registration "${registration}" already has a factory registered via registerFactory(). ` +
+                `Cannot register the same name via the JavaScript API. ` +
+                `Use a different registration name or unregister the factory first.`);
+        }
+        if (typeof elementsOrFactory === 'function') {
+            return this.cacheElementsAndRegister({
+                factory: elementsOrFactory,
+                id: registration,
+            });
+        }
+        else {
+            return this.cacheElementsAndRegister({
+                elements: elementsOrFactory,
+                id: registration,
+            });
+        }
     }
     /**
      * Internal APIs
@@ -610,13 +660,14 @@ export class FoundationLayout extends FoundationElement {
     /**
      * Registers a function with golden layout to create a pane
      * @param elements - Elements[] to add to new new pane
+     * @param factory - ComponentFactory function to create component instances
      * @param id - optional string which is used to register the new function with golden layout. Defaults to sequentially setting the IDs for default items
      * @returns - string which is the registered ID
      * @throws - {@link LayoutRegistrationError} if the id is already in use
      * @internal
      */
-    cacheElementsAndRegister({ elements, id }) {
-        const reg = id || `${(this.registeredComponents += 1)}`;
+    cacheElementsAndRegister(config) {
+        const reg = config.id || `${(this.registeredComponents += 1)}`;
         if (this.layout.getRegisteredComponentTypeNames().includes(reg)) {
             throw new LayoutRegistrationError(`Cannot register item with already registered name: '${reg}'`);
         }
@@ -632,45 +683,117 @@ export class FoundationLayout extends FoundationElement {
          *
          * 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.
+         *
+         * For factory functions:
+         * The factory is called for each new instance instead of cloning. This preserves event listeners
+         * and framework bindings that would be lost during cloning.
          */
         const registrationFunction = (() => {
-            // Use appendChild to consume the elements and save them in the master copy
-            const masterCopy = document.createDocumentFragment();
-            masterCopy[layoutCacheDocument] = true;
-            elements.forEach((e) => masterCopy.appendChild(e));
-            const instances = new Map();
-            return (container, state) => {
-                var _b;
-                // If this is a new instance then assign it uuid instance
-                if (!(state === null || state === void 0 ? void 0 : state['instance'])) {
-                    state['instance'] = this.uuid.createId();
-                }
-                container.state['instance'] = state['instance'];
-                container.state['originalTitle'] = (_b = state['originalTitle']) !== null && _b !== void 0 ? _b : container.title;
-                // If this is a new instance then copy the master copy into the instances map
-                // this is then the instance that is recalled for this version each time
-                // 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));
+            if ('factory' in config) {
+                // Factory-based registration for framework components
+                const instances = new Map();
+                const cleanupFunctions = new Map();
+                const containerTracking = new Map();
+                return (container, state) => {
+                    var _b;
+                    // If this is a new instance then assign it uuid instance
+                    if (!(state === null || state === void 0 ? void 0 : state['instance'])) {
+                        state['instance'] = this.uuid.createId();
+                    }
+                    container.state['instance'] = state['instance'];
+                    container.state['originalTitle'] = (_b = state['originalTitle']) !== null && _b !== void 0 ? _b : container.title;
+                    // Store instance container reference for state management FIRST
+                    const componentInstanceContainer = {
+                        container,
+                        instance: state['instance'],
+                        registration: reg,
+                    };
+                    const instanceId = state['instance'];
+                    // Check if this instance was previously rendered in a different container
+                    const previousContainer = containerTracking.get(instanceId);
+                    const hasMoved = previousContainer && previousContainer !== container;
+                    // If moved to a different container (drag operation), cleanup and recreate to avoid stale state
+                    if (hasMoved) {
+                        logger.debug(`Recreating instance ${instanceId} for registration ${reg} due to container change`);
+                        // Call cleanup function if it exists
+                        const cleanup = cleanupFunctions.get(instanceId);
+                        if (cleanup && typeof cleanup === 'function') {
+                            try {
+                                cleanup();
+                            }
+                            catch (error) {
+                                logger.error(`Error calling cleanup for instance ${instanceId}:`, error);
+                            }
+                        }
+                        // Remove from maps to force recreation
+                        instances.delete(instanceId);
+                        cleanupFunctions.delete(instanceId);
+                    }
+                    // Create instance if it doesn't exist (new instance or recreated after move)
+                    if (!instances.has(instanceId)) {
+                        const componentContainer = document.createElement('div');
+                        componentContainer.style.width = '100%';
+                        componentContainer.style.height = '100%';
+                        componentContainer[instanceContainer] = componentInstanceContainer;
+                        const cleanup = config.factory(componentContainer);
+                        instances.set(instanceId, componentContainer);
+                        if (cleanup) {
+                            cleanupFunctions.set(instanceId, cleanup);
+                        }
+                    }
+                    // Append the instance container to the layout container
+                    const componentContainer = instances.get(instanceId);
+                    if (!componentContainer) {
+                        logger.error(`Failed to get component container for instance ${instanceId}`);
+                        return;
+                    }
+                    // Ensure the property is set (in case it was lost)
+                    componentContainer[instanceContainer] = componentInstanceContainer;
+                    container.element.appendChild(componentContainer);
+                    // Track which container this instance is now in
+                    containerTracking.set(instanceId, container);
+                    this.setupLayoutReceiveEvents(container, state);
+                };
+            }
+            else {
+                // Element-based registration (existing behavior)
+                const masterCopy = document.createDocumentFragment();
+                masterCopy[layoutCacheDocument] = true;
+                config.elements.forEach((e) => masterCopy.appendChild(e));
+                const instances = new Map();
+                return (container, state) => {
+                    var _b;
+                    // If this is a new instance then assign it uuid instance
+                    if (!(state === null || state === void 0 ? void 0 : state['instance'])) {
+                        state['instance'] = this.uuid.createId();
+                    }
+                    container.state['instance'] = state['instance'];
+                    container.state['originalTitle'] = (_b = state['originalTitle']) !== null && _b !== void 0 ? _b : container.title;
+                    // If this is a new instance then copy the master copy into the instances map
+                    // this is then the instance that is recalled for this version each time
+                    // 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));
+                        });
+                        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'],
+                        registration: reg,
+                    };
+                    // get the instance from the map and append it to the container
+                    instances.get(state['instance']).forEach((component) => {
+                        container.element.appendChild(component);
+                        component[instanceContainer] = componentInstanceContainer;
                     });
-                    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'],
-                    registration: reg,
+                    this.setupLayoutReceiveEvents(container, state);
                 };
-                // get the instance from the map and append it to the container
-                instances.get(state['instance']).forEach((component) => {
-                    container.element.appendChild(component);
-                    component[instanceContainer] = componentInstanceContainer;
-                });
-                this.setupLayoutReceiveEvents(container, state);
-            };
+            }
         })();
         this.layout.registerComponentFactoryFunction(reg, registrationFunction);
         return reg;

package/dist/esm/utils/factory-registry.js

@@ -0,0 +1,88 @@
+import { logger } from './logger';
+/**
+ * Global registry for component factories.
+ * Maps factory keys (strings) to factory functions.
+ * @internal
+ */
+const factoryRegistry = new Map();
+/**
+ * Registers a factory function with a unique key.
+ * This allows framework components to be used in the declarative layout API
+ * without needing to pass function references through HTML attributes.
+ *
+ * @param key - Unique identifier for the factory. Should be descriptive and unique across the application.
+ * @param factory - The factory function that creates the component.
+ * @throws {Error} If a factory with the same key is already registered.
+ *
+ * @example
+ * ```typescript
+ * // React example
+ * import { registerFactory } from '@genesislcap/foundation-layout';
+ * import { reactFactory } from './utils/react-layout-factory';
+ * import { MyComponent } from './components/MyComponent';
+ *
+ * registerFactory('my-component', reactFactory(MyComponent, { someProp: 'value' }));
+ * ```
+ *
+ * Then in your JSX:
+ * ```tsx
+ * <rapid-layout-item
+ *   registration="my-item"
+ *   title="My Component"
+ * />
+ * ```
+ *
+ * @public
+ */
+export function registerFactory(key, factory) {
+    if (factoryRegistry.has(key)) {
+        throw new Error(`Factory with key "${key}" is already registered. Cannot register duplicate factory.`);
+    }
+    factoryRegistry.set(key, factory);
+    logger.debug(`Factory registered with key: ${key}`);
+}
+/**
+ * Retrieves a factory function by its key.
+ *
+ * @param key - The unique identifier for the factory.
+ * @returns The factory function, or undefined if not found.
+ *
+ * @public
+ */
+export function getFactory(key) {
+    return factoryRegistry.get(key);
+}
+/**
+ * Removes a factory from the registry.
+ * This is useful for cleanup when a component is unmounted or no longer needed.
+ *
+ * @param key - The unique identifier for the factory to remove.
+ * @returns True if the factory was found and removed, false otherwise.
+ *
+ * @example
+ * ```typescript
+ * unregisterFactory('my-component');
+ * ```
+ *
+ * @public
+ */
+export function unregisterFactory(key) {
+    const deleted = factoryRegistry.delete(key);
+    if (deleted) {
+        logger.debug(`Factory unregistered with key: ${key}`);
+    }
+    else {
+        logger.warn(`Attempted to unregister factory with key "${key}", but it was not found.`);
+    }
+    return deleted;
+}
+/**
+ * Clears all registered factories from the registry.
+ * This is primarily useful for testing purposes.
+ *
+ * @internal
+ */
+export function clearFactoryRegistry() {
+    factoryRegistry.clear();
+    logger.debug('Factory registry cleared');
+}

package/dist/esm/utils/index.js

@@ -1,6 +1,7 @@
 export * from './constants';
 export * from './error';
 export * from './events';
+export * from './factory-registry';
 export * from './misc';
 export * from './templates';
 export * from './types';