forgeframe 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,169 @@
+/**
+ * @packageDocumentation
+ * ForgeFrame - Modern cross-domain component framework.
+ *
+ * @remarks
+ * A minimal, TypeScript-first alternative to zoid with zero runtime dependencies.
+ * Enables rendering components in iframes or popups across domains while
+ * seamlessly passing props (including functions) between parent and child.
+ *
+ * @example
+ * ```typescript
+ * import ForgeFrame from 'forgeframe';
+ *
+ * // Define a component
+ * const LoginComponent = ForgeFrame.create({
+ *   tag: 'login-component',
+ *   url: 'https://auth.example.com/login',
+ *   props: {
+ *     email: { type: ForgeFrame.PROP_TYPE.STRING },
+ *     onLogin: { type: ForgeFrame.PROP_TYPE.FUNCTION },
+ *   },
+ * });
+ *
+ * // Render the component
+ * LoginComponent({
+ *   email: 'user@example.com',
+ *   onLogin: (user) => console.log('Logged in:', user),
+ * }).render('#container');
+ * ```
+ */
+import { create, destroy, destroyComponents, destroyAll, isChild, getXProps } from './core';
+import { PopupOpenError } from './render/popup';
+/**
+ * Main ForgeFrame API object.
+ *
+ * @remarks
+ * Provides a zoid-compatible interface for creating and managing
+ * cross-domain components. All methods and constants are accessible
+ * through this object.
+ *
+ * @example
+ * ```typescript
+ * import ForgeFrame from 'forgeframe';
+ *
+ * const Component = ForgeFrame.create({
+ *   tag: 'my-component',
+ *   url: '/component.html',
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare const ForgeFrame: {
+    /**
+     * Create a new component definition.
+     *
+     * @remarks
+     * This is the main entry point for defining components. Returns a
+     * component factory function that can be called to create instances.
+     *
+     * @example
+     * ```typescript
+     * const MyComponent = ForgeFrame.create({
+     *   tag: 'my-component',
+     *   url: 'https://example.com/component',
+     *   props: {
+     *     onLogin: { type: ForgeFrame.PROP_TYPE.FUNCTION },
+     *   },
+     * });
+     *
+     * const instance = MyComponent({ onLogin: (user) => {} });
+     * await instance.render('#container');
+     * ```
+     */
+    readonly create: typeof create;
+    /**
+     * Destroy a single component instance.
+     *
+     * @param instance - The component instance to destroy
+     */
+    readonly destroy: typeof destroy;
+    /**
+     * Destroy all instances of a specific component by tag.
+     *
+     * @param tag - The component tag name
+     */
+    readonly destroyComponents: typeof destroyComponents;
+    /**
+     * Destroy all ForgeFrame component instances.
+     */
+    readonly destroyAll: typeof destroyAll;
+    /**
+     * Check if the current window is a child component context.
+     *
+     * @returns True if running inside a ForgeFrame iframe/popup
+     */
+    readonly isChild: typeof isChild;
+    /**
+     * Get xprops from the current child window.
+     *
+     * @returns The xprops object if in child context, undefined otherwise
+     */
+    readonly getXProps: typeof getXProps;
+    /**
+     * Prop type constants for defining component props.
+     * @see {@link PROP_TYPE}
+     */
+    readonly PROP_TYPE: {
+        readonly STRING: "string";
+        readonly OBJECT: "object";
+        readonly FUNCTION: "function";
+        readonly BOOLEAN: "boolean";
+        readonly NUMBER: "number";
+        readonly ARRAY: "array";
+    };
+    /**
+     * Serialization strategy constants.
+     * @see {@link PROP_SERIALIZATION}
+     */
+    readonly PROP_SERIALIZATION: {
+        readonly JSON: "json";
+        readonly BASE64: "base64";
+        readonly DOTIFY: "dotify";
+    };
+    /**
+     * Rendering context constants (IFRAME, POPUP).
+     * @see {@link CONTEXT}
+     */
+    readonly CONTEXT: {
+        readonly IFRAME: "iframe";
+        readonly POPUP: "popup";
+    };
+    /**
+     * Lifecycle event name constants.
+     * @see {@link EVENT}
+     */
+    readonly EVENT: {
+        readonly RENDER: "render";
+        readonly RENDERED: "rendered";
+        readonly PRERENDER: "prerender";
+        readonly PRERENDERED: "prerendered";
+        readonly DISPLAY: "display";
+        readonly ERROR: "error";
+        readonly CLOSE: "close";
+        readonly DESTROY: "destroy";
+        readonly PROPS: "props";
+        readonly RESIZE: "resize";
+        readonly FOCUS: "focus";
+    };
+    /**
+     * Error thrown when popup window fails to open.
+     */
+    readonly PopupOpenError: typeof PopupOpenError;
+    /**
+     * Current library version.
+     */
+    readonly VERSION: "1.0.0";
+};
+/**
+ * Default export of the ForgeFrame API object.
+ * @public
+ */
+export default ForgeFrame;
+export { create, destroy, destroyComponents, destroyAll, isChild, getXProps, } from './core';
+export { PROP_TYPE, PROP_SERIALIZATION, CONTEXT, EVENT, VERSION, } from './constants';
+export { PopupOpenError } from './render/popup';
+export type { ComponentOptions, ForgeFrameComponent, ForgeFrameComponentInstance, ChildProps, PropDefinition, PropsDefinition, PropContext, TemplateContext, ContainerTemplate, PrerenderTemplate, Dimensions, DomainMatcher, AutoResizeOptions, IframeAttributes, IframeStyles, EligibilityResult, EventHandler, EventEmitterInterface, } from './types';
+export type { PropType, ContextType, EventType, SerializationType, } from './constants';
+export { createReactDriver, withReactDriver, type ReactDriverOptions, type ReactComponentProps, type ReactComponentType, } from './drivers/react';

package/dist/props/definitions.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @packageDocumentation
+ * Built-in prop definitions for ForgeFrame components.
+ *
+ * @remarks
+ * This module defines the standard props that are automatically available
+ * to all ForgeFrame components, including identifiers, dimensions, and
+ * lifecycle callbacks.
+ */
+import type { PropDefinition, Dimensions } from '../types';
+/**
+ * Built-in props that are automatically provided to all components.
+ *
+ * @remarks
+ * These props are always available regardless of the component's prop definitions.
+ * They include component identifiers, dimensions, timeouts, and lifecycle callbacks.
+ *
+ * @public
+ */
+export interface BuiltinProps {
+    /** Unique component instance identifier. */
+    uid: string;
+    /** Component tag name. */
+    tag: string;
+    /** Component dimensions. */
+    dimensions: Dimensions;
+    /** Initialization timeout in milliseconds. */
+    timeout: number;
+    /** CSP nonce for inline scripts/styles. */
+    cspNonce?: string;
+    /** Called when component becomes visible. */
+    onDisplay?: () => void;
+    /** Called when component is fully rendered. */
+    onRendered?: () => void;
+    /** Called when rendering starts. */
+    onRender?: () => void;
+    /** Called when prerender phase completes. */
+    onPrerendered?: () => void;
+    /** Called when prerender phase starts. */
+    onPrerender?: () => void;
+    /** Called when component is closing. */
+    onClose?: () => void;
+    /** Called when component is destroyed. */
+    onDestroy?: () => void;
+    /** Called when component is resized. */
+    onResize?: (dimensions: Dimensions) => void;
+    /** Called when component receives focus. */
+    onFocus?: () => void;
+    /** Called when an error occurs. */
+    onError?: (err: Error) => void;
+    /** Called when props are updated. */
+    onProps?: (props: Record<string, unknown>) => void;
+}
+/**
+ * Default prop definitions for all built-in props.
+ *
+ * @remarks
+ * These definitions specify the type, required status, and default values
+ * for built-in props.
+ *
+ * @public
+ */
+export declare const BUILTIN_PROP_DEFINITIONS: Record<string, PropDefinition>;
+/**
+ * Gets the default value for a prop type.
+ *
+ * @param type - The prop type string
+ * @returns The default value for that type
+ *
+ * @public
+ */
+export declare function getDefaultForType(type: string): unknown;

package/dist/props/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @packageDocumentation
+ * Props handling module for ForgeFrame.
+ *
+ * @remarks
+ * This module handles prop normalization, validation, serialization, and
+ * deserialization for cross-domain component communication.
+ */
+export { BUILTIN_PROP_DEFINITIONS, getDefaultForType, type BuiltinProps, } from './definitions';
+export { normalizeProps, validateProps, getPropsForChild, propsToQueryParams, } from './normalize';
+export { serializeProps, deserializeProps, cloneProps, } from './serialize';

package/dist/props/normalize.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @packageDocumentation
+ * Props normalization and validation module.
+ *
+ * @remarks
+ * This module handles merging user props with defaults, validating prop
+ * types, and filtering props for sending to child components.
+ */
+import type { PropsDefinition, PropContext } from '../types';
+/**
+ * Merges user props with defaults and computes derived values.
+ *
+ * @typeParam P - The props type
+ * @param userProps - Props provided by the user
+ * @param definitions - Prop definitions from component config
+ * @param context - Context for computed props
+ * @returns Normalized props object
+ *
+ * @public
+ */
+export declare function normalizeProps<P extends Record<string, unknown>>(userProps: Partial<P>, definitions: PropsDefinition<P>, context: PropContext<P>): P;
+/**
+ * Validates props against their definitions.
+ *
+ * @typeParam P - The props type
+ * @param props - Props to validate
+ * @param definitions - Prop definitions to validate against
+ * @throws Error if a required prop is missing or type is invalid
+ *
+ * @public
+ */
+export declare function validateProps<P extends Record<string, unknown>>(props: P, definitions: PropsDefinition<P>): void;
+/**
+ * Filters props for sending to the child component.
+ *
+ * @remarks
+ * Respects sendToChild, sameDomain, and trustedDomains settings.
+ *
+ * @typeParam P - The props type
+ * @param props - All props
+ * @param definitions - Prop definitions
+ * @param childDomain - The child's domain
+ * @param isSameDomain - Whether child is same domain as parent
+ * @returns Filtered props for the child
+ *
+ * @public
+ */
+export declare function getPropsForChild<P extends Record<string, unknown>>(props: P, definitions: PropsDefinition<P>, childDomain: string, isSameDomain: boolean): Partial<P>;
+/**
+ * Builds URL query parameters from props with queryParam option.
+ *
+ * @typeParam P - The props type
+ * @param props - Props to convert
+ * @param definitions - Prop definitions
+ * @returns URLSearchParams with query parameters
+ *
+ * @public
+ */
+export declare function propsToQueryParams<P extends Record<string, unknown>>(props: P, definitions: PropsDefinition<P>): URLSearchParams;

package/dist/props/serialize.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @packageDocumentation
+ * Props serialization module for cross-domain transfer.
+ *
+ * @remarks
+ * This module handles serializing and deserializing props for transfer
+ * between parent and child windows across domain boundaries.
+ */
+import type { PropsDefinition, SerializedProps } from '../types';
+import { FunctionBridge } from '../communication/bridge';
+import type { Messenger } from '../communication/messenger';
+/**
+ * Serializes props for cross-domain transfer.
+ *
+ * @remarks
+ * Functions are converted to references, objects are JSON/base64/dotify encoded
+ * based on the prop definition's serialization setting.
+ *
+ * @typeParam P - The props type
+ * @param props - Props to serialize
+ * @param definitions - Prop definitions
+ * @param bridge - Function bridge for serializing functions
+ * @returns Serialized props ready for postMessage
+ *
+ * @public
+ */
+export declare function serializeProps<P extends Record<string, unknown>>(props: P, definitions: PropsDefinition<P>, bridge: FunctionBridge): SerializedProps;
+/**
+ * Deserializes props received from the parent.
+ *
+ * @remarks
+ * Function references are converted back to callable functions that
+ * invoke the original via postMessage.
+ *
+ * @typeParam P - The props type
+ * @param serialized - Serialized props from parent
+ * @param definitions - Prop definitions
+ * @param messenger - Messenger for function calls
+ * @param bridge - Function bridge for deserializing functions
+ * @param parentWin - Parent window reference
+ * @param parentDomain - Parent origin domain
+ * @returns Deserialized props
+ *
+ * @public
+ */
+export declare function deserializeProps<P extends Record<string, unknown>>(serialized: SerializedProps, definitions: PropsDefinition<P>, messenger: Messenger, bridge: FunctionBridge, parentWin: Window, parentDomain: string): P;
+/**
+ * Creates a deep clone of props.
+ *
+ * @remarks
+ * Functions are passed by reference, objects are deep cloned using
+ * structuredClone, and primitives are copied directly.
+ *
+ * @typeParam P - The props type
+ * @param props - Props to clone
+ * @returns Cloned props
+ *
+ * @public
+ */
+export declare function cloneProps<P extends Record<string, unknown>>(props: P): P;

package/dist/render/iframe.d.ts

@@ -0,0 +1,213 @@
+import type { Dimensions, IframeAttributes, IframeStyles } from '../types';
+/**
+ * Configuration options for creating an iframe.
+ *
+ * @public
+ */
+export interface IframeOptions {
+    /**
+     * The URL to load in the iframe.
+     */
+    url: string;
+    /**
+     * The name attribute for the iframe, used for targeting.
+     */
+    name: string;
+    /**
+     * The parent HTML element that will contain the iframe.
+     */
+    container: HTMLElement;
+    /**
+     * The width and height dimensions for the iframe.
+     */
+    dimensions: Dimensions;
+    /**
+     * Optional additional HTML attributes to set on the iframe element.
+     */
+    attributes?: IframeAttributes;
+    /**
+     * Optional CSS styles to apply to the iframe element.
+     */
+    style?: IframeStyles;
+}
+/**
+ * Creates an iframe element with the specified options and appends it to a container.
+ *
+ * @remarks
+ * This function creates a fully configured iframe with sensible defaults for
+ * security and appearance. It sets up sandbox restrictions, removes borders,
+ * and ensures cross-browser compatibility.
+ *
+ * The iframe is appended to the container before setting the `src` attribute,
+ * as some browsers require the iframe to be in the DOM before loading content.
+ *
+ * If no sandbox attribute is provided, a default secure sandbox policy is applied:
+ * `allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox`
+ *
+ * @param options - Configuration options for the iframe
+ * @returns The created HTMLIFrameElement, already appended to the container
+ *
+ * @example
+ * ```typescript
+ * const iframe = createIframe({
+ *   url: 'https://example.com/widget',
+ *   name: 'my-widget',
+ *   container: document.getElementById('widget-container')!,
+ *   dimensions: { width: 400, height: 300 },
+ *   attributes: { allow: 'payment' }
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function createIframe(options: IframeOptions): HTMLIFrameElement;
+/**
+ * Creates an iframe for displaying a prerender/loading state.
+ *
+ * @remarks
+ * This function creates a lightweight iframe intended to show a loading
+ * placeholder while the actual content iframe is being prepared. The iframe
+ * uses `srcdoc` with an empty HTML document, avoiding any external network requests.
+ *
+ * The prerender iframe uses a special reserved name `__forgeframe_prerender__`
+ * to distinguish it from content iframes.
+ *
+ * @param container - The parent HTML element to append the iframe to
+ * @param dimensions - The width and height for the prerender iframe
+ * @returns The created prerender HTMLIFrameElement
+ *
+ * @example
+ * ```typescript
+ * const prerenderIframe = createPrerenderIframe(
+ *   document.getElementById('container')!,
+ *   { width: 400, height: 300 }
+ * );
+ * ```
+ *
+ * @public
+ */
+export declare function createPrerenderIframe(container: HTMLElement, dimensions: Dimensions): HTMLIFrameElement;
+/**
+ * Destroys an iframe by clearing its source and removing it from the DOM.
+ *
+ * @remarks
+ * This function performs a clean teardown of an iframe by first navigating
+ * it to `about:blank` to stop any ongoing loading or scripts, then removing
+ * it from its parent node. Any errors during cleanup are silently ignored
+ * to ensure the cleanup process completes without throwing.
+ *
+ * @param iframe - The iframe element to destroy
+ *
+ * @example
+ * ```typescript
+ * const iframe = createIframe({ ... });
+ * // Later, when done with the iframe:
+ * destroyIframe(iframe);
+ * ```
+ *
+ * @public
+ */
+export declare function destroyIframe(iframe: HTMLIFrameElement): void;
+/**
+ * Resizes an iframe to the specified dimensions.
+ *
+ * @param iframe - The iframe element to resize
+ * @param dimensions - The new width and height to apply
+ *
+ * @example
+ * ```typescript
+ * resizeIframe(iframe, { width: 600, height: 400 });
+ * resizeIframe(iframe, { width: '100%', height: 'auto' });
+ * ```
+ *
+ * @public
+ */
+export declare function resizeIframe(iframe: HTMLIFrameElement, dimensions: Dimensions): void;
+/**
+ * Makes an iframe visible by resetting its display and visibility styles.
+ *
+ * @remarks
+ * This function clears the `display` style (reverting to default) and sets
+ * `visibility` to `'visible'`. Use this in conjunction with {@link hideIframe}
+ * to toggle iframe visibility.
+ *
+ * @param iframe - The iframe element to show
+ *
+ * @example
+ * ```typescript
+ * hideIframe(iframe);
+ * // Later:
+ * showIframe(iframe);
+ * ```
+ *
+ * @public
+ */
+export declare function showIframe(iframe: HTMLIFrameElement): void;
+/**
+ * Hides an iframe by setting display to none and visibility to hidden.
+ *
+ * @remarks
+ * This function sets both `display: none` and `visibility: hidden` to ensure
+ * the iframe is completely hidden and does not affect layout. Use
+ * {@link showIframe} to make the iframe visible again.
+ *
+ * @param iframe - The iframe element to hide
+ *
+ * @example
+ * ```typescript
+ * showIframe(iframe);
+ * // Later:
+ * hideIframe(iframe);
+ * ```
+ *
+ * @public
+ */
+export declare function hideIframe(iframe: HTMLIFrameElement): void;
+/**
+ * Attempts to focus an iframe and its content window.
+ *
+ * @remarks
+ * This function tries to focus both the iframe element itself and its
+ * `contentWindow`. Cross-origin restrictions may prevent focusing the
+ * content window, in which case errors are silently caught and ignored.
+ *
+ * @param iframe - The iframe element to focus
+ *
+ * @example
+ * ```typescript
+ * // Focus the iframe after user interaction
+ * button.addEventListener('click', () => {
+ *   focusIframe(iframe);
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function focusIframe(iframe: HTMLIFrameElement): void;
+/**
+ * Retrieves the content dimensions from an iframe for auto-resize functionality.
+ *
+ * @remarks
+ * This function attempts to read the actual content dimensions from the iframe's
+ * document. It calculates the maximum of various dimension properties (`scrollWidth`,
+ * `offsetWidth`, `clientWidth`, etc.) from both the body and documentElement to
+ * ensure accurate measurements across different browsers.
+ *
+ * This function will return `null` if:
+ * - The iframe's content document is not accessible (cross-origin restrictions)
+ * - Any error occurs while reading dimensions
+ *
+ * @param iframe - The iframe element to measure
+ * @returns The content dimensions, or `null` if dimensions cannot be determined
+ *
+ * @example
+ * ```typescript
+ * const dimensions = getIframeContentDimensions(iframe);
+ * if (dimensions) {
+ *   resizeIframe(iframe, dimensions);
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function getIframeContentDimensions(iframe: HTMLIFrameElement): Dimensions | null;

package/dist/render/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @packageDocumentation
+ *
+ * Rendering utilities for ForgeFrame.
+ *
+ * This module provides functions for creating and managing iframes, popups,
+ * and their associated templates. It handles the visual rendering layer
+ * of ForgeFrame components.
+ *
+ * @remarks
+ * The render module is divided into three main areas:
+ * - **Iframe management** - Creating, destroying, and manipulating iframes
+ * - **Popup management** - Opening, closing, and monitoring popup windows
+ * - **Templates** - Default templates and styling utilities for containers
+ *
+ * @example
+ * ```typescript
+ * import { createIframe, openPopup, defaultContainerTemplate } from '@forgeframe/render';
+ *
+ * // Create an iframe
+ * const iframe = createIframe({
+ *   url: 'https://example.com',
+ *   name: 'my-iframe',
+ *   container: document.body,
+ *   dimensions: { width: 400, height: 300 }
+ * });
+ *
+ * // Open a popup
+ * const popup = openPopup({
+ *   url: 'https://example.com',
+ *   name: 'my-popup',
+ *   dimensions: { width: 600, height: 400 }
+ * });
+ * ```
+ */
+export { createIframe, createPrerenderIframe, destroyIframe, resizeIframe, showIframe, hideIframe, focusIframe, getIframeContentDimensions, type IframeOptions, } from './iframe';
+export { openPopup, closePopup, focusPopup, isPopupBlocked, watchPopupClose, resizePopup, PopupOpenError, type PopupOptions, } from './popup';
+export { defaultContainerTemplate, defaultPrerenderTemplate, applyDimensions, createStyleElement, fadeIn, fadeOut, swapPrerenderContent, } from './templates';