@genesislcap/foundation-layout 14.368.0 → 14.369.0

package/docs/FRAMEWORK_COMPONENTS.md

@@ -0,0 +1,568 @@
+# Framework Components in Foundation Layout
+
+## Overview
+
+This document discusses patterns and future enhancements for using framework-rendered components (React, Angular, Vue, etc.) within the foundation-layout system.
+
+## Current State (JavaScript API)
+
+The layout system now supports **factory functions** for registering components. This is the recommended approach for framework-rendered components because it allows each layout instance to create a fresh component rather than cloning existing DOM elements (which loses event listeners).
+
+### Factory Function Pattern
+
+The factory function pattern is **framework-agnostic** and works with any framework:
+
+#### React
+```typescript
+layout.registerItem('my-component', (container) => {
+  const root = createRoot(container);
+  root.render(
+    <Provider store={store}>
+      <MyComponent />
+    </Provider>
+  );
+  
+  // Optional: return cleanup function
+  return () => root.unmount();
+});
+```
+
+#### Angular
+```typescript
+layout.registerItem('my-component', (container) => {
+  const componentRef = createComponent(MyComponent, {
+    environmentInjector: this.injector,
+    hostElement: container
+  });
+  componentRef.changeDetectorRef.detectChanges();
+  
+  return () => componentRef.destroy();
+});
+```
+
+#### Vue
+```typescript
+layout.registerItem('my-component', (container) => {
+  const app = createApp(MyComponent);
+  app.mount(container);
+  
+  return () => app.unmount();
+});
+```
+
+### Why Factory Functions?
+
+The layout system needs to create multiple instances of registered components (e.g., when loading saved layouts, adding items multiple times, or handling popout windows). The original implementation used `cloneNode(true)`, which:
+
+1. ✅ Works great for native HTML elements
+2. ❌ **Loses JavaScript event listeners** (limitation of `cloneNode` API)
+3. ❌ **Loses framework bindings** (React event handlers, Angular directives, Vue reactivity)
+
+Factory functions solve this by letting frameworks create fresh, fully-functional component instances.
+
+## Known Limitations
+
+### Component State Serialization
+
+**Current Limitation:** Factory-based components do not support the `LayoutComponentWithState<T>` interface for saving and restoring component-specific state.
+
+#### Why This Limitation Exists
+
+The layout system's state management works by calling `getCurrentState()` and `applyState()` methods on DOM elements. For factory-based components:
+
+1. The factory creates a wrapper `div` that gets added to the layout
+2. Framework components (React/Angular/Vue) render **inside** this wrapper
+3. The wrapper is a plain `HTMLDivElement` without `getCurrentState()` or `applyState()` methods
+4. The framework components inside have no mechanism to expose these methods to the layout system
+
+#### What Works vs What Doesn't
+
+✅ **Works:**
+- Event listeners (click, input, change, etc.)
+- Multiple instances of the same component
+- Basic layout save/load (positions, sizes, tab order)
+- Component cleanup via factory return value
+
+❌ **Doesn't Work:**
+- Saving component-specific state (form values, scroll position, selected items, etc.)
+- Restoring component state when loading a saved layout
+- Using `LayoutComponentWithState<T>` interface with factory components
+
+#### Workarounds
+
+Until state management is implemented for factory components, use these approaches:
+
+**1. External State Management (Recommended)**
+Use your framework's state management solution:
+- React: Redux, Context API, Zustand, Jotai
+- Angular: Services with RxJS
+- Vue: Vuex, Pinia
+
+```typescript
+// React example with Redux
+layout.registerItem('my-form', (container) => {
+  const root = createRoot(container);
+  root.render(
+    <Provider store={reduxStore}>
+      <MyFormComponent />  {/* State persisted in Redux */}
+    </Provider>
+  );
+  return () => root.unmount();
+});
+```
+
+**2. URL Parameters or Query Strings**
+Store state in the URL for shareable/bookmarkable states:
+```typescript
+// React example
+const searchParams = new URLSearchParams(window.location.search);
+const initialState = searchParams.get('formData');
+```
+
+**3. LocalStorage/SessionStorage**
+Manually persist state outside the layout system:
+```typescript
+// React example with useEffect
+useEffect(() => {
+  localStorage.setItem('myComponentState', JSON.stringify(state));
+}, [state]);
+```
+
+**4. Use Element-Based Registration**
+If state management is critical and external solutions don't work, use element-based registration for those specific components (though you'll lose event listeners).
+
+#### Proposed Solutions for Future Implementation
+
+**Option 1: Extended Factory Return Type** (Recommended)
+```typescript
+type ComponentFactory = (container: HTMLElement) => {
+  cleanup?: () => void;
+  getCurrentState?: () => unknown;
+  applyState?: (state: unknown) => void;
+} | void | (() => void);
+```
+
+Factory functions could return an object with state handlers:
+```typescript
+layout.registerItem('my-component', (container) => {
+  const root = createRoot(container);
+  let componentState = null;
+  
+  root.render(<MyComponent onStateChange={(s) => componentState = s} />);
+  
+  return {
+    cleanup: () => root.unmount(),
+    getCurrentState: () => componentState,
+    applyState: (state) => componentState = state
+  };
+});
+```
+
+**Option 2: State Manager Callback**
+```typescript
+type ComponentFactory = (
+  container: HTMLElement,
+  stateManager?: {
+    registerStateHandlers: (handlers: {
+      getCurrentState: () => unknown;
+      applyState: (state: unknown) => void;
+    }) => void;
+  }
+) => void | (() => void);
+```
+
+Factory receives a callback to register state handlers:
+```typescript
+layout.registerItem('my-component', (container, stateManager) => {
+  const root = createRoot(container);
+  let componentState = null;
+  
+  root.render(<MyComponent onStateChange={(s) => componentState = s} />);
+  
+  stateManager?.registerStateHandlers({
+    getCurrentState: () => componentState,
+    applyState: (state) => componentState = state
+  });
+  
+  return () => root.unmount();
+});
+```
+
+**Option 3: Framework-Specific Wrappers**
+Create helper functions that handle state automatically:
+```typescript
+// React helper
+function createReactLayoutComponent(Component, getStateFromProps, applyStateToProps) {
+  return (container) => {
+    const root = createRoot(container);
+    // ... state management logic
+    return { cleanup, getCurrentState, applyState };
+  };
+}
+```
+
+## Declarative HTML API with Factory Functions
+
+The `foundation-layout-item` component supports factory functions for the declarative HTML API, enabling framework components to work properly while preserving event listeners and lifecycle management.
+
+### Recommended Approach: Factory Registry Pattern
+
+The factory registry uses the `registration` attribute as the lookup key for pre-registered factory functions. This provides a clean, unified API where the same name identifies the component in both the registry and the layout.
+
+#### How It Works
+
+1. Register factory functions using `registerFactory(key, factory)`
+2. Use the same key as the `registration` attribute in your layout item
+3. The layout automatically looks up the factory when the item connects
+
+```typescript
+// Simple and unified API:
+registerFactory('my-component', factoryFunction);
+
+// Then in HTML/JSX:
+<rapid-layout-item registration="my-component" title="My Component" />
+```
+
+**Priority order when layout item connects:**
+1. Factory from registry (using registration name) ✅
+2. Slotted content (backward compatible) ✅
+
+### React Example (Recommended)
+
+Register factories **before** rendering using the same names as your layout item registrations:
+
+```tsx
+import { registerFactory } from '@genesislcap/foundation-layout';
+import { reactFactory, reactFactoryWithProvider } from './utils/react-layout-factory';
+import { Provider } from 'react-redux';
+import { TableComponent, TextFieldComponent } from './components';
+
+// Register factories at module level using the same names as registrations
+registerFactory('table', reactFactory(TableComponent));
+registerFactory('table-with-redux', reactFactoryWithProvider(
+  TableComponent,
+  Provider,
+  { store: reduxStore }
+));
+registerFactory('textfield', reactFactoryWithProvider(
+  TextFieldComponent,
+  Provider,
+  { store: reduxStore }
+));
+
+function MyLayout() {
+  return (
+    <rapid-layout>
+      <rapid-layout-region>
+        {/* Simple component - registration name matches factory key */}
+        <rapid-layout-item
+          registration="table"
+          title="Table"
+          closable
+        />
+
+        {/* Component with Redux provider */}
+        <rapid-layout-item
+          registration="table-with-redux"
+          title="Table (with Redux)"
+          closable
+        />
+
+        {/* Component with custom size */}
+        <rapid-layout-item
+          registration="textfield"
+          title="Text Field"
+          size="33%"
+        />
+      </rapid-layout-region>
+    </rapid-layout>
+  );
+}
+```
+
+**Helper utility (`react-layout-factory.tsx`):**
+
+```typescript
+import { ComponentFactory } from '@genesislcap/foundation-layout';
+import { createRoot, Root } from 'react-dom/client';
+import type { ComponentType, ReactElement } from 'react';
+
+export function reactFactory<P = {}>(
+  Component: ComponentType<P>,
+  props?: P
+): ComponentFactory {
+  return (container: HTMLElement) => {
+    const root: Root = createRoot(container);
+    root.render(<Component {...(props || ({} as P))} />);
+    return () => root.unmount(); // Cleanup
+  };
+}
+
+export function reactFactoryWithProvider<CP = {}, WP = {}>(
+  Component: ComponentType<CP>,
+  Wrapper: ComponentType<WP & { children: ReactElement }>,
+  wrapperProps: WP,
+  componentProps?: CP
+): ComponentFactory {
+  return (container: HTMLElement) => {
+    const root: Root = createRoot(container);
+    root.render(
+      <Wrapper {...wrapperProps}>
+        <Component {...(componentProps || ({} as CP))} />
+      </Wrapper>
+    );
+    return () => root.unmount();
+  };
+}
+```
+
+### Angular Example
+
+Register factories in your component setup using the same names as registrations:
+
+```typescript
+import { Component, OnInit, Injector } from '@angular/core';
+import { registerFactory, ComponentFactory } from '@genesislcap/foundation-layout';
+import { createComponent } from '@angular/core';
+import { MyAngularComponent } from './my-angular.component';
+
+@Component({
+  selector: 'app-layout',
+  template: `
+    <rapid-layout>
+      <rapid-layout-region>
+        <rapid-layout-item
+          registration="angular-comp"
+          title="Angular Component">
+        </rapid-layout-item>
+      </rapid-layout-region>
+    </rapid-layout>
+  `
+})
+export class LayoutComponent implements OnInit {
+  constructor(private injector: Injector) {}
+
+  ngOnInit() {
+    // Register factory using the same name as the registration
+    registerFactory('angular-comp', (container: HTMLElement) => {
+      const componentRef = createComponent(MyAngularComponent, {
+        environmentInjector: this.injector,
+        hostElement: container
+      });
+      componentRef.changeDetectorRef.detectChanges();
+      
+      return () => componentRef.destroy();
+    });
+  }
+}
+```
+
+### Vue 3 Example
+
+Register factories before mounting using the same names as registrations:
+
+```typescript
+import { createApp } from 'vue';
+import { registerFactory } from '@genesislcap/foundation-layout';
+import MyVueComponent from './MyVueComponent.vue';
+
+// Register factory using the same name as the registration
+registerFactory('vue-comp', (container: HTMLElement) => {
+  const app = createApp(MyVueComponent);
+  app.mount(container);
+  
+  return () => app.unmount();
+});
+```
+
+Then in your template:
+
+```html
+<rapid-layout>
+  <rapid-layout-region>
+    <rapid-layout-item
+      registration="vue-comp"
+      title="Vue Component">
+    </rapid-layout-item>
+  </rapid-layout-region>
+</rapid-layout>
+```
+
+### FAST Bindings Example
+
+Register factories in your setup code using the same names as registrations:
+
+```typescript
+import { registerFactory } from '@genesislcap/foundation-layout';
+
+registerFactory('grid', (container: HTMLElement) => {
+  const grid = document.createElement('rapid-grid');
+  // Configure grid...
+  container.appendChild(grid);
+  
+  return () => grid.remove();
+});
+```
+
+Then use in your FAST template:
+
+```html
+<rapid-layout>
+  <rapid-layout-region>
+    <rapid-layout-item
+      registration="grid"
+      title="Data Grid">
+    </rapid-layout-item>
+  </rapid-layout-region>
+</rapid-layout>
+```
+
+### Factory Registry API
+
+**`registerFactory(key: string, factory: ComponentFactory): void`**
+- Registers a factory function with a unique key
+- Key should be descriptive and unique across your application
+- Logs a warning if key is already registered (will overwrite)
+
+**`getFactory(key: string): ComponentFactory | undefined`**
+- Retrieves a factory by its key
+- Returns `undefined` if key not found
+- Primarily for internal use by the layout system
+
+**`unregisterFactory(key: string): boolean`**
+- Removes a factory from the registry
+- Returns `true` if factory was found and removed
+- Useful for cleanup when components are unmounted
+
+**Example:**
+```typescript
+import { registerFactory, unregisterFactory } from '@genesislcap/foundation-layout';
+
+// Register
+registerFactory('my-component', myFactoryFunction);
+
+// Later, cleanup
+unregisterFactory('my-component');
+```
+
+### Validation Rules
+
+The layout system enforces two important validation rules to prevent conflicts:
+
+**Rule 1: Cannot register via JavaScript API if factory exists**
+```typescript
+registerFactory('my-component', myFactory);
+layout.registerItem('my-component', elements); // ❌ ERROR!
+// LayoutRegistrationError: Registration "my-component" already has a factory registered
+```
+
+**Rule 2: Cannot mix factory and slotted content**
+```typescript
+registerFactory('my-component', myFactory);
+// ❌ ERROR - Has both factory AND slotted content
+<rapid-layout-item registration="my-component">
+  <div>Content</div>
+</rapid-layout-item>
+// LayoutUsageError: Cannot use both factory registration and slotted content
+```
+
+**Valid Usage Patterns:**
+```typescript
+// ✅ Declarative with factory
+registerFactory('comp-1', myFactory);
+<rapid-layout-item registration="comp-1" />
+
+// ✅ Declarative with slotted content (no factory)
+<rapid-layout-item registration="comp-2">
+  <div>Content</div>
+</rapid-layout-item>
+
+// ✅ JavaScript API (no factory in registry)
+layout.registerItem('comp-3', elements);
+```
+
+### Key Points
+
+✅ **Unified API:**
+- Use the `registration` attribute as both the component identifier and factory key
+- Register factories with `registerFactory(name, factory)` before rendering
+- Simpler API with no duplication between registration and factory-key
+- Guarantees factory availability when custom element connects
+
+✅ **What Works:**
+- Event listeners are preserved
+- Framework lifecycle methods work correctly
+- Multiple instances can be created
+- Cleanup is handled automatically
+- Works with React, Angular, Vue, FAST, and any other framework
+
+✅ **Backward Compatibility:**
+- Slotted content still works when no factory is registered
+- No breaking changes to existing code using slotted elements
+- Priority order: factory (using registration name) → slotted content
+
+✅ **Validation:**
+- Cannot register via JavaScript API if a factory exists with that name
+- Cannot mix factory registration with slotted content
+- Clear error messages guide proper usage
+
+### Comparison: JavaScript API vs Declarative API
+
+| Aspect | JavaScript API | Declarative API (with factory registry) |
+|--------|----------------|-------------------------------|
+| **Usage** | Programmatic registration | HTML/JSX markup |
+| **Setup** | Requires `useEffect` or lifecycle hooks | Register factories, then use in template |
+| **Dynamic Items** | Easy to add/remove items | Static structure |
+| **Type Safety** | Full TypeScript support | Depends on framework bindings |
+| **Factory Approach** | Direct function passing | Registry with registration name as key |
+| **When to Use** | Complex layouts with dynamic items | Simple, static layouts |
+
+**Recommendation:** Use the JavaScript API for dynamic layouts where items are added/removed programmatically. Use the declarative API with factory registration for simpler layouts with a fixed set of items.
+
+## Best Practices
+
+### When to Use Factory Functions
+
+Use factory functions when:
+- Components have JavaScript event listeners
+- Components use framework-specific features (React hooks, Angular services, Vue composition API)
+- Components need to be instantiated multiple times
+- Components need cleanup logic
+
+### When Element Arrays Are OK
+
+Element arrays still work great for:
+- Static HTML content
+- Native web components without event listeners
+- FAST components using FAST's binding system (these handle cloning correctly)
+
+### Example: Mixed Approach
+
+```typescript
+// Factory for React component with events
+layout.registerItem('interactive-form', (container) => {
+  const root = createRoot(container);
+  root.render(<FormComponent />);
+  return () => root.unmount();
+});
+
+// Element array for static content
+const staticDiv = document.createElement('div');
+staticDiv.innerHTML = '<h1>Static Content</h1>';
+layout.registerItem('static-content', [staticDiv]);
+```
+
+## Questions or Issues?
+
+If you encounter problems with framework components in the layout:
+1. Check if you're using the factory function pattern
+2. Verify cleanup functions are properly implemented
+3. Check browser console for React/Angular/Vue warnings
+4. File an issue with reproduction steps
+
+## Related Documentation
+
+- [Layout README](../README.md)
+- [API Documentation](./api/foundation-layout.foundationlayout.md)
+- [Element Cloning Limitations](../README.md#binding-events-inline-in-the-declarative-api)
+

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

@@ -0,0 +1,46 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-layout](./foundation-layout.md) &gt; [ComponentFactory](./foundation-layout.componentfactory.md)
+
+## ComponentFactory type
+
+Factory function for creating component instances in the layout.
+
+**Signature:**
+
+```typescript
+export type ComponentFactory = (container: HTMLElement) => void | (() => void);
+```
+
+## Remarks
+
+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 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.
+
+## Example 1
+
+React example:
+
+```typescript
+layout.registerItem('my-component', (container) => {
+  const root = createRoot(container);
+  root.render(<MyComponent />);
+  return () => root.unmount();
+});
+```
+
+## Example 2
+
+Angular example:
+
+```typescript
+layout.registerItem('my-component', (container) => {
+  const componentRef = createComponent(MyComponent, {
+    environmentInjector: this.injector,
+    hostElement: container
+  });
+  return () => componentRef.destroy();
+});
+```
+

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

@@ -342,7 +342,7 @@ Gets all of the currently registered names
 </td></tr>
 <tr><td>
 
-[registerItem(registration, elements)](./foundation-layout.foundationlayout.registeritem.md)
+[registerItem(registration, elementsOrFactory)](./foundation-layout.foundationlayout.registeritem.md)
 
 
 </td><td>
@@ -350,7 +350,7 @@ Gets all of the currently registered names
 
 </td><td>
 
-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.
 
 
 </td></tr>

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

@@ -4,12 +4,12 @@
 
 ## FoundationLayout.registerItem() method
 
-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.
 
 **Signature:**
 
 ```typescript
-registerItem(registration: string, elements: Element[]): string;
+registerItem(registration: string, elementsOrFactory: Element[] | ComponentFactory): string;
 ```
 
 ## Parameters
@@ -48,17 +48,17 @@ string of the registration ID
 </td></tr>
 <tr><td>
 
-elements
+elementsOrFactory
 
 
 </td><td>
 
-Element\[\]
+Element\[\] \| [ComponentFactory](./foundation-layout.componentfactory.md)
 
 
 </td><td>
 
-Elements\[\] containing the reference to the elements to register for later usage
+Either Elements\[\] containing the reference to the elements to register, or a ComponentFactory function
 
 
 </td></tr>
@@ -78,7 +78,31 @@ string
 
 ## Remarks
 
-You would use this to register elements that you later want to load when using [FoundationLayout.loadLayout()](./foundation-layout.foundationlayout.loadlayout.md)<!-- -->. Use [FoundationLayout.layoutRequiredRegistrations()](./foundation-layout.foundationlayout.layoutrequiredregistrations.md) to see what components need to be registered for a certain config and then register them using this function before calling [FoundationLayout.loadLayout()](./foundation-layout.foundationlayout.loadlayout.md)<!-- -->.
+You can register either an array of elements or a factory function.
 
-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)`<!-- -->.
+\*\*Element registration\*\*: Use this to register elements that you later want to load when using [FoundationLayout.loadLayout()](./foundation-layout.foundationlayout.loadlayout.md)<!-- -->. Use [FoundationLayout.layoutRequiredRegistrations()](./foundation-layout.foundationlayout.layoutrequiredregistrations.md) to see what components need to be registered for a certain config and then register them using this function before calling [FoundationLayout.loadLayout()](./foundation-layout.foundationlayout.loadlayout.md)<!-- -->. 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.
+
+## Example 1
+
+Element registration:
+
+```typescript
+const div = document.createElement('div');
+div.innerHTML = '<h1>Hello</h1>';
+layout.registerItem('my-element', [div]);
+```
+
+## Example 2
+
+Factory registration (React):
+
+```typescript
+layout.registerItem('text-field', (container) => {
+  const root = createRoot(container);
+  root.render(<TextFieldComponent />);
+  return () => root.unmount();
+});
+```