forgeframe 1.0.0

package/dist/core/child.d.ts

@@ -0,0 +1,223 @@
+/**
+ * @packageDocumentation
+ * Child component implementation module.
+ *
+ * @remarks
+ * This module contains the ChildComponent class which runs inside the iframe
+ * or popup and handles communication with the parent window. It also provides
+ * utilities for detecting child context and accessing xprops.
+ */
+import type { ChildProps, WindowNamePayload, PropsDefinition } from '../types';
+import { EventEmitter } from '../events/emitter';
+/**
+ * Child-side component implementation.
+ *
+ * @remarks
+ * This class runs inside the iframe or popup window and manages communication
+ * with the parent component. It provides the xprops object with props and
+ * control methods.
+ *
+ * @typeParam P - The props type passed from the parent
+ *
+ * @example
+ * ```typescript
+ * // In child window
+ * const { email, onLogin, close } = window.xprops;
+ * console.log('Email:', email);
+ * onLogin({ id: 1, name: 'John' });
+ * close();
+ * ```
+ *
+ * @public
+ */
+export declare class ChildComponent<P extends Record<string, unknown>> {
+    private propDefinitions;
+    /** The xprops object containing props and control methods. */
+    xprops: ChildProps<P>;
+    /** Event emitter for lifecycle events. */
+    event: EventEmitter;
+    /** @internal */
+    private uid;
+    /** @internal */
+    private tag;
+    /** @internal */
+    private parentWindow;
+    /** @internal */
+    private parentDomain;
+    /** @internal */
+    private messenger;
+    /** @internal */
+    private bridge;
+    /** @internal */
+    private propsHandlers;
+    /** @internal */
+    private parentProps;
+    /** @internal */
+    private initError;
+    /**
+     * Creates a new ChildComponent instance.
+     *
+     * @param payload - The payload parsed from window.name
+     * @param propDefinitions - Optional prop definitions for deserialization
+     */
+    constructor(payload: WindowNamePayload<P>, propDefinitions?: PropsDefinition<P>);
+    /**
+     * Returns the xprops object.
+     *
+     * @returns The xprops object with props and control methods
+     */
+    getProps(): ChildProps<P>;
+    /**
+     * Resolves the parent window reference (iframe parent or popup opener).
+     * @internal
+     */
+    private resolveParentWindow;
+    /**
+     * Builds the xprops object with deserialized props and control methods.
+     * @internal
+     */
+    private buildXProps;
+    /**
+     * Sends initialization message to the parent.
+     * @internal
+     */
+    private sendInit;
+    /**
+     * Returns the initialization error if one occurred.
+     *
+     * @returns The initialization error or null if successful
+     */
+    getInitError(): Error | null;
+    /**
+     * Requests the parent to close this component.
+     * @internal
+     */
+    private close;
+    /**
+     * Focuses this window and notifies the parent.
+     * @internal
+     */
+    private focus;
+    /**
+     * Requests the parent to resize this component.
+     * @internal
+     */
+    private resize;
+    /**
+     * Requests the parent to show this component.
+     * @internal
+     */
+    private show;
+    /**
+     * Requests the parent to hide this component.
+     * @internal
+     */
+    private hide;
+    /**
+     * Subscribes to prop updates from the parent.
+     * @internal
+     */
+    private onProps;
+    /**
+     * Reports an error to the parent.
+     * @internal
+     */
+    private onError;
+    /**
+     * Exports data or methods to the parent.
+     * @internal
+     */
+    private exportData;
+    /**
+     * Exports data to the parent for bidirectional communication.
+     * @internal
+     */
+    private parentExport;
+    /**
+     * Gets information about sibling component instances.
+     * @internal
+     */
+    private getSiblings;
+    /**
+     * Builds child component factories from refs passed by the parent.
+     * @internal
+     */
+    private buildChildComponents;
+    /**
+     * Sets up message handlers for parent communication.
+     * @internal
+     */
+    private setupMessageHandlers;
+    /**
+     * Destroys the child component and cleans up resources.
+     */
+    destroy(): void;
+}
+/**
+ * Initializes the child component if running in a ForgeFrame window.
+ *
+ * @remarks
+ * This function detects if the current window was created by ForgeFrame
+ * and sets up the child component with xprops. Returns null if not in
+ * a ForgeFrame child context.
+ *
+ * @typeParam P - The props type passed from the parent
+ * @param propDefinitions - Optional prop definitions for deserialization
+ * @returns The child component instance or null if not in a child window
+ *
+ * @example
+ * ```typescript
+ * const child = initChild();
+ * if (child) {
+ *   console.log('Running in ForgeFrame child context');
+ *   console.log('Props:', child.xprops);
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function initChild<P extends Record<string, unknown>>(propDefinitions?: PropsDefinition<P>): ChildComponent<P> | null;
+/**
+ * Gets the current child component instance.
+ *
+ * @typeParam P - The props type passed from the parent
+ * @returns The child component instance or null if not initialized
+ *
+ * @public
+ */
+export declare function getChild<P extends Record<string, unknown>>(): ChildComponent<P> | null;
+/**
+ * Checks if the current window is a ForgeFrame child context.
+ *
+ * @returns True if running inside a ForgeFrame iframe or popup
+ *
+ * @example
+ * ```typescript
+ * if (isChild()) {
+ *   console.log('Running in ForgeFrame child');
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function isChild(): boolean;
+/**
+ * Gets the xprops object from the window.
+ *
+ * @remarks
+ * This is a convenience function to access `window.xprops`.
+ *
+ * @typeParam P - The props type passed from the parent
+ * @returns The xprops object or undefined if not in a child context
+ *
+ * @example
+ * ```typescript
+ * const xprops = getXProps();
+ * if (xprops) {
+ *   xprops.onLogin({ id: 1, name: 'John' });
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function getXProps<P extends Record<string, unknown>>(): ChildProps<P> | undefined;

package/dist/core/component.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @packageDocumentation
+ * Component factory and registry module.
+ *
+ * @remarks
+ * This module provides the main entry point for creating ForgeFrame components.
+ * It manages a global registry of all defined components and handles component
+ * creation, validation, and lifecycle management.
+ */
+import type { ComponentOptions, ForgeFrameComponent, ForgeFrameComponentInstance } from '../types';
+/**
+ * Creates a new ForgeFrame component definition.
+ *
+ * @remarks
+ * This is the main entry point for defining components. It creates a factory
+ * function that can be called with props to create component instances.
+ * Equivalent to zoid.create() for migration purposes.
+ *
+ * @typeParam P - The props type for the component
+ * @typeParam X - The exports type that the child can expose
+ * @param options - Component configuration options
+ * @returns A component factory function
+ *
+ * @example
+ * ```typescript
+ * const LoginComponent = create({
+ *   tag: 'login-component',
+ *   url: 'https://auth.example.com/login',
+ *   props: {
+ *     email: { type: PROP_TYPE.STRING },
+ *     onLogin: { type: PROP_TYPE.FUNCTION },
+ *   },
+ * });
+ *
+ * const instance = LoginComponent({ email: 'user@example.com' });
+ * await instance.render('#container');
+ * ```
+ *
+ * @public
+ */
+export declare function create<P extends Record<string, unknown> = Record<string, unknown>, X = unknown>(options: ComponentOptions<P>): ForgeFrameComponent<P, X>;
+/**
+ * Retrieves a registered component by its tag name.
+ *
+ * @typeParam P - The props type for the component
+ * @typeParam X - The exports type that the child can expose
+ * @param tag - The unique tag identifier of the component
+ * @returns The component factory function, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const LoginComponent = getComponent('login-component');
+ * if (LoginComponent) {
+ *   LoginComponent({ email: 'user@example.com' }).render('#container');
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function getComponent<P extends Record<string, unknown> = Record<string, unknown>, X = unknown>(tag: string): ForgeFrameComponent<P, X> | undefined;
+/**
+ * Destroys a single component instance.
+ *
+ * @remarks
+ * This closes the component and cleans up all associated resources.
+ *
+ * @typeParam P - The props type for the component
+ * @param instance - The component instance to destroy
+ *
+ * @example
+ * ```typescript
+ * const instance = MyComponent({ prop: 'value' });
+ * await instance.render('#container');
+ * // Later...
+ * await destroy(instance);
+ * ```
+ *
+ * @public
+ */
+export declare function destroy<P extends Record<string, unknown>>(instance: ForgeFrameComponentInstance<P>): Promise<void>;
+/**
+ * Destroys all instances of a specific component.
+ *
+ * @remarks
+ * Useful for cleanup when a component type is no longer needed.
+ *
+ * @param tag - The component tag name to destroy all instances of
+ *
+ * @example
+ * ```typescript
+ * // Destroy all login component instances
+ * await destroyComponents('login-component');
+ * ```
+ *
+ * @public
+ */
+export declare function destroyComponents(tag: string): Promise<void>;
+/**
+ * Destroys all ForgeFrame component instances.
+ *
+ * @remarks
+ * This is a global cleanup function that destroys every component
+ * instance across all component types.
+ *
+ * @example
+ * ```typescript
+ * // Clean up everything on page unload
+ * window.addEventListener('beforeunload', () => {
+ *   destroyAll();
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function destroyAll(): Promise<void>;
+/**
+ * Removes a component from the registry.
+ *
+ * @remarks
+ * Primarily used for testing and cleanup. Does not destroy active instances.
+ *
+ * @param tag - The component tag to unregister
+ * @internal
+ */
+export declare function unregisterComponent(tag: string): void;
+/**
+ * Clears all components from the registry.
+ *
+ * @remarks
+ * Primarily used for testing and cleanup. Does not destroy active instances.
+ *
+ * @internal
+ */
+export declare function clearComponents(): void;
+export { isChild, getXProps } from './child';

package/dist/core/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @packageDocumentation
+ * Core module for ForgeFrame component creation and lifecycle management.
+ *
+ * @remarks
+ * This module provides the primary API for creating, managing, and destroying
+ * cross-domain components. It includes both parent-side (host page) and
+ * child-side (embedded page) functionality.
+ */
+export { create, getComponent, destroy, destroyComponents, destroyAll, unregisterComponent, clearComponents, isChild, getXProps, } from './component';
+export { ParentComponent } from './parent';
+export { ChildComponent, initChild, getChild } from './child';

package/dist/core/parent.d.ts

@@ -0,0 +1,262 @@
+/**
+ * @packageDocumentation
+ * Parent component implementation module.
+ *
+ * @remarks
+ * This module contains the ParentComponent class which handles the host-side
+ * rendering and communication with child components embedded in iframes or popups.
+ */
+import type { ComponentOptions, ForgeFrameComponentInstance, Dimensions } from '../types';
+import type { ContextType } from '../constants';
+import { EventEmitter } from '../events/emitter';
+/**
+ * Parent-side component implementation.
+ *
+ * @remarks
+ * This class manages the lifecycle of a component from the host page perspective.
+ * It handles rendering the component into iframes or popups, communicating with
+ * the child window via postMessage, and managing component state.
+ *
+ * @typeParam P - The props type passed to the component
+ * @typeParam X - The exports type that the child can expose to the parent
+ *
+ * @example
+ * ```typescript
+ * const instance = new ParentComponent(options, { email: 'user@example.com' });
+ * await instance.render('#container');
+ * ```
+ *
+ * @public
+ */
+export declare class ParentComponent<P extends Record<string, unknown>, X = unknown> implements ForgeFrameComponentInstance<P, X> {
+    /** Event emitter for lifecycle events. */
+    event: EventEmitter;
+    /** Arbitrary state storage for the component instance. */
+    state: Record<string, unknown>;
+    /** Data exported by the child component. */
+    exports?: X;
+    /** Data exported from the parent by the child. */
+    parentExports?: unknown;
+    /** @internal */
+    private _uid;
+    /**
+     * Unique instance identifier.
+     * @readonly
+     */
+    get uid(): string;
+    /** @internal */
+    private options;
+    /** @internal */
+    private props;
+    /** @internal */
+    private context;
+    /** @internal */
+    private messenger;
+    /** @internal */
+    private bridge;
+    /** @internal */
+    private cleanup;
+    /** @internal */
+    private childWindow;
+    /** @internal */
+    private iframe;
+    /** @internal */
+    private container;
+    /** @internal */
+    private prerenderElement;
+    /** @internal */
+    private initPromise;
+    /** @internal */
+    private rendered;
+    /** @internal */
+    private destroyed;
+    /**
+     * Creates a new ParentComponent instance.
+     *
+     * @param options - Component configuration options
+     * @param props - Initial props to pass to the component
+     */
+    constructor(options: ComponentOptions<P>, props?: Partial<P>);
+    /**
+     * Builds the list of trusted domains for messenger communication.
+     * @internal
+     */
+    private buildTrustedDomains;
+    /**
+     * Renders the component into a DOM container.
+     *
+     * @remarks
+     * This is the primary method for displaying the component. It creates
+     * an iframe or popup, establishes communication with the child, and
+     * handles the prerender/render lifecycle.
+     *
+     * @param container - CSS selector or HTMLElement to render into
+     * @param context - Override the default rendering context (iframe or popup)
+     * @throws Error if component was already destroyed or rendered
+     *
+     * @example
+     * ```typescript
+     * await instance.render('#container');
+     * await instance.render(document.getElementById('target'), 'popup');
+     * ```
+     */
+    render(container?: string | HTMLElement, context?: ContextType): Promise<void>;
+    /**
+     * Renders the component into a container in a different window.
+     *
+     * @remarks
+     * Currently delegates to regular render. Full cross-window rendering
+     * would require additional complexity.
+     *
+     * @param _win - Target window (currently unused)
+     * @param container - CSS selector or HTMLElement to render into
+     * @param context - Override the default rendering context
+     */
+    renderTo(_win: Window, container?: string | HTMLElement, context?: ContextType): Promise<void>;
+    /**
+     * Closes and destroys the component.
+     *
+     * @remarks
+     * Emits the 'close' event before destruction. Safe to call multiple times.
+     */
+    close(): Promise<void>;
+    /**
+     * Focuses the component window.
+     *
+     * @remarks
+     * For iframes, focuses the iframe element. For popups, brings the window to front.
+     */
+    focus(): Promise<void>;
+    /**
+     * Resizes the component to the specified dimensions.
+     *
+     * @param dimensions - New width and height for the component
+     */
+    resize(dimensions: Dimensions): Promise<void>;
+    /**
+     * Shows the component if hidden.
+     *
+     * @remarks
+     * Only applicable to iframe context.
+     */
+    show(): Promise<void>;
+    /**
+     * Hides the component.
+     *
+     * @remarks
+     * Only applicable to iframe context.
+     */
+    hide(): Promise<void>;
+    /**
+     * Updates the component props and sends them to the child.
+     *
+     * @remarks
+     * Props are normalized and serialized before being sent to the child window.
+     *
+     * @param newProps - Partial props object to merge with existing props
+     */
+    updateProps(newProps: Partial<P>): Promise<void>;
+    /**
+     * Creates a clone of this instance with the same props.
+     *
+     * @returns A new unrendered component instance with identical configuration
+     */
+    clone(): ForgeFrameComponentInstance<P, X>;
+    /**
+     * Checks if the component is eligible to render based on the eligible option.
+     *
+     * @returns True if eligible or no eligibility check defined
+     */
+    isEligible(): boolean;
+    /**
+     * Normalizes component options with default values.
+     * @internal
+     */
+    private normalizeOptions;
+    /**
+     * Creates the prop context passed to prop callbacks and validators.
+     * @internal
+     */
+    private createPropContext;
+    /**
+     * Resolves a container selector or element to an HTMLElement.
+     * @internal
+     */
+    private resolveContainer;
+    /**
+     * Checks eligibility and throws if component cannot render.
+     * @internal
+     */
+    private checkEligibility;
+    /**
+     * Creates and displays the prerender (loading) content.
+     * @internal
+     */
+    private prerender;
+    /**
+     * Creates an iframe element without setting src (for prerender phase).
+     * The window name is set immediately as it carries the payload for the child.
+     * @internal
+     */
+    private createIframeElement;
+    /**
+     * Opens the child window (iframe or popup).
+     * @internal
+     */
+    private open;
+    /**
+     * Builds the URL for the child window including query parameters.
+     * @internal
+     */
+    private buildUrl;
+    /**
+     * Builds the window.name payload for the child window.
+     * @internal
+     */
+    private buildWindowName;
+    /**
+     * Builds component references for nested child components.
+     * @internal
+     */
+    private buildChildrenRefs;
+    /**
+     * Creates the exports object sent to the child.
+     * @internal
+     */
+    private createParentExports;
+    /**
+     * Extracts the origin domain from the component URL.
+     * @internal
+     */
+    private getChildDomain;
+    /**
+     * Waits for the child to send the init message.
+     * @internal
+     */
+    private waitForChild;
+    /**
+     * Sets up message handlers for child communication.
+     * @internal
+     */
+    private setupMessageHandlers;
+    /**
+     * Registers cleanup handlers for the instance.
+     * @internal
+     */
+    private setupCleanup;
+    /**
+     * Handles errors by emitting events and calling callbacks.
+     * @internal
+     */
+    private handleError;
+    /**
+     * Calls a prop callback if it exists.
+     * @internal
+     */
+    private callPropCallback;
+    /**
+     * Destroys the component and cleans up all resources.
+     * @internal
+     */
+    private destroy;
+}

package/dist/drivers/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ForgeFrame Driver Module
+ *
+ * @remarks
+ * This module provides framework-specific drivers for integrating ForgeFrame
+ * components with popular UI frameworks like React. Drivers handle the lifecycle
+ * management, prop synchronization, and rendering of cross-domain components
+ * within the target framework's component model.
+ *
+ * @example
+ * ```typescript
+ * import { createReactDriver, withReactDriver } from 'forgeframe/drivers';
+ * import type { ReactDriverOptions, ReactComponentProps } from 'forgeframe/drivers';
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { createReactDriver, withReactDriver, type ReactDriverOptions, type ReactComponentProps, type ReactComponentType, } from './react';