forgeframe 0.0.1

package/dist/core/consumer.d.ts

@@ -0,0 +1,263 @@
+/**
+ * @packageDocumentation
+ * Consumer component implementation module.
+ *
+ * @remarks
+ * This module contains the ConsumerComponent class which handles the consumer-side
+ * (the app embedding the component) rendering and communication with host components
+ * embedded in iframes or popups.
+ */
+import type { ComponentOptions, ForgeFrameComponentInstance, Dimensions } from '../types';
+import type { ContextType } from '../constants';
+import { EventEmitter } from '../events/emitter';
+/**
+ * Consumer-side component implementation.
+ *
+ * @remarks
+ * This class manages the lifecycle of a component from the consumer (embedding app) perspective.
+ * It handles rendering the component into iframes or popups, communicating with
+ * the host window via postMessage, and managing component state.
+ *
+ * @typeParam P - The props type passed to the component
+ * @typeParam X - The exports type that the host can expose to the consumer
+ *
+ * @example
+ * ```typescript
+ * const instance = new ConsumerComponent(options, { email: 'user@example.com' });
+ * await instance.render('#container');
+ * ```
+ *
+ * @public
+ */
+export declare class ConsumerComponent<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 host component. */
+    exports?: X;
+    /** Data exported from the consumer by the host. */
+    consumerExports?: 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 hostWindow;
+    /** @internal */
+    private iframe;
+    /** @internal */
+    private container;
+    /** @internal */
+    private prerenderElement;
+    /** @internal */
+    private initPromise;
+    /** @internal */
+    private rendered;
+    /** @internal */
+    private destroyed;
+    /**
+     * Creates a new ConsumerComponent 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 host, 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 host.
+     *
+     * @remarks
+     * Props are normalized and serialized before being sent to the host 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 host.
+     * @internal
+     */
+    private createIframeElement;
+    /**
+     * Opens the host window (iframe or popup).
+     * @internal
+     */
+    private open;
+    /**
+     * Builds the URL for the host window including query parameters.
+     * @internal
+     */
+    private buildUrl;
+    /**
+     * Builds the window.name payload for the host window.
+     * @internal
+     */
+    private buildWindowName;
+    /**
+     * Builds component references for nested host components.
+     * @internal
+     */
+    private buildNestedHostRefs;
+    /**
+     * Creates the exports object sent to the host.
+     * @internal
+     */
+    private createConsumerExports;
+    /**
+     * Extracts the origin domain from the component URL.
+     * @internal
+     */
+    private getHostDomain;
+    /**
+     * Waits for the host to send the init message.
+     * @internal
+     */
+    private waitForHost;
+    /**
+     * Sets up message handlers for host 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/core/host.d.ts

@@ -0,0 +1,249 @@
+/**
+ * @packageDocumentation
+ * Host component implementation module.
+ *
+ * @remarks
+ * This module contains the HostComponent class which runs inside the iframe
+ * or popup and handles communication with the consumer window. It also provides
+ * utilities for detecting host context and accessing hostProps.
+ */
+import type { HostProps, WindowNamePayload, PropsDefinition } from '../types';
+import { EventEmitter } from '../events/emitter';
+/**
+ * Host-side component implementation.
+ *
+ * @remarks
+ * This class runs inside the iframe or popup window and manages communication
+ * with the consumer component. It provides the hostProps object with props and
+ * control methods.
+ *
+ * @typeParam P - The props type passed from the consumer
+ *
+ * @example
+ * ```typescript
+ * // In host window
+ * const { email, onLogin, close } = window.hostProps;
+ * console.log('Email:', email);
+ * onLogin({ id: 1, name: 'John' });
+ * close();
+ * ```
+ *
+ * @public
+ */
+export declare class HostComponent<P extends Record<string, unknown>> {
+    private propDefinitions;
+    /** The hostProps object containing props and control methods passed from the consumer. */
+    hostProps: HostProps<P>;
+    /** Event emitter for lifecycle events. */
+    event: EventEmitter;
+    /** @internal */
+    private uid;
+    /** @internal */
+    private tag;
+    /** @internal */
+    private consumerWindow;
+    /** @internal */
+    private consumerDomain;
+    /** @internal */
+    private messenger;
+    /** @internal */
+    private bridge;
+    /** @internal */
+    private propsHandlers;
+    /** @internal */
+    private consumerProps;
+    /** @internal */
+    private initError;
+    /**
+     * Creates a new HostComponent 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 hostProps object.
+     *
+     * @returns The hostProps object with props and control methods
+     */
+    getProps(): HostProps<P>;
+    /**
+     * Resolves the consumer window reference (iframe parent or popup opener).
+     * @internal
+     */
+    private resolveConsumerWindow;
+    /**
+     * Builds the hostProps object with deserialized props and control methods.
+     * @internal
+     */
+    private buildHostProps;
+    /**
+     * Sends initialization message to the consumer.
+     * @internal
+     */
+    private sendInit;
+    /**
+     * Returns the initialization error if one occurred.
+     *
+     * @returns The initialization error or null if successful
+     */
+    getInitError(): Error | null;
+    /**
+     * Requests the consumer to close this component.
+     * @internal
+     */
+    private close;
+    /**
+     * Focuses this window and notifies the consumer.
+     * @internal
+     */
+    private focus;
+    /**
+     * Requests the consumer to resize this component.
+     * @internal
+     */
+    private resize;
+    /**
+     * Requests the consumer to show this component.
+     * @internal
+     */
+    private show;
+    /**
+     * Requests the consumer to hide this component.
+     * @internal
+     */
+    private hide;
+    /**
+     * Subscribes to prop updates from the consumer.
+     * @internal
+     */
+    private onProps;
+    /**
+     * Reports an error to the consumer.
+     * @internal
+     */
+    private onError;
+    /**
+     * Exports data or methods to the consumer.
+     * @internal
+     */
+    private exportData;
+    /**
+     * Exports data to the consumer for bidirectional communication.
+     * @internal
+     */
+    private consumerExport;
+    /**
+     * Gets information about peer component instances.
+     * @internal
+     */
+    private getPeerInstances;
+    /**
+     * Builds nested component factories from refs passed by the consumer.
+     * @internal
+     */
+    private buildNestedComponents;
+    /**
+     * Sets up message handlers for consumer communication.
+     * @internal
+     */
+    private setupMessageHandlers;
+    /**
+     * Destroys the host component and cleans up resources.
+     */
+    destroy(): void;
+}
+/**
+ * Initializes the host component if running in a ForgeFrame window.
+ *
+ * @remarks
+ * This function detects if the current window was created by ForgeFrame
+ * and sets up the host component with hostProps. Returns null if not in
+ * a ForgeFrame host context.
+ *
+ * @typeParam P - The props type passed from the consumer
+ * @param propDefinitions - Optional prop definitions for deserialization
+ * @returns The host component instance or null if not in a host window
+ *
+ * @example
+ * ```typescript
+ * const host = initHost();
+ * if (host) {
+ *   console.log('Running in ForgeFrame host context');
+ *   console.log('Props:', host.hostProps);
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function initHost<P extends Record<string, unknown>>(propDefinitions?: PropsDefinition<P>): HostComponent<P> | null;
+/**
+ * Gets the current host component instance.
+ *
+ * @typeParam P - The props type passed from the consumer
+ * @returns The host component instance or null if not initialized
+ *
+ * @public
+ */
+export declare function getHost<P extends Record<string, unknown>>(): HostComponent<P> | null;
+/**
+ * Checks if the current window is a ForgeFrame host context.
+ *
+ * @remarks
+ * A "host" in ForgeFrame terminology is the embedded iframe or popup window
+ * that receives props from the consumer (the embedding app).
+ *
+ * @returns True if running inside a ForgeFrame iframe or popup
+ *
+ * @example
+ * ```typescript
+ * if (isHost()) {
+ *   console.log('Running in ForgeFrame host');
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function isHost(): boolean;
+/**
+ * Checks if the current window is embedded by ForgeFrame.
+ *
+ * @remarks
+ * This is an alias for {@link isHost} that uses more intuitive terminology.
+ * "Embedded" means this window is running inside a ForgeFrame iframe or popup,
+ * receiving props from the consumer (the embedding app).
+ *
+ * @returns True if running inside a ForgeFrame iframe or popup
+ *
+ * @example
+ * ```typescript
+ * if (isEmbedded()) {
+ *   const { amount, onSuccess } = window.hostProps;
+ *   // Handle embedded context...
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function isEmbedded(): boolean;
+/**
+ * Gets the hostProps object from the window.
+ *
+ * @remarks
+ * This is a convenience function to access `window.hostProps`, which contains
+ * all props passed from the consumer plus built-in control methods.
+ *
+ * @typeParam P - The props type passed from the consumer
+ * @returns The hostProps object or undefined if not in a host context
+ *
+ * @example
+ * ```typescript
+ * const props = getHostProps();
+ * if (props) {
+ *   props.onLogin({ id: 1, name: 'John' });
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function getHostProps<P extends Record<string, unknown>>(): HostProps<P> | undefined;

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 consumer-side (embedding app) and
+ * host-side (embedded page) functionality.
+ */
+export { create, getComponent, destroy, destroyByTag, destroyAll, unregisterComponent, clearComponents, } from './component';
+export { ConsumerComponent } from './consumer';
+export { HostComponent, initHost, getHost, isHost, isEmbedded, getHostProps, } from './host';

package/dist/drivers/index.d.ts

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