forgeframe 0.0.1

package/dist/props/schema.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Standard Schema V1 type definitions and validation utilities.
+ *
+ * @remarks
+ * These types enable integration with Standard Schema-compliant validation
+ * libraries such as Zod, Valibot, ArkType, and others. Types are copied from
+ * the official @standard-schema/spec package to maintain zero dependencies.
+ *
+ * @see https://standardschema.dev/
+ *
+ * @packageDocumentation
+ */
+/**
+ * The Standard Schema V1 interface.
+ *
+ * @remarks
+ * Any schema library implementing this interface can be used with ForgeFrame's
+ * prop validation system. The `~standard` property contains the schema metadata
+ * and validation function.
+ *
+ * @typeParam Input - The input type the schema accepts
+ * @typeParam Output - The output type after validation/transformation
+ *
+ * @example
+ * ```typescript
+ * // Zod schemas implement StandardSchemaV1
+ * import { z } from 'zod';
+ * const schema: StandardSchemaV1<string, string> = z.string().email();
+ * ```
+ *
+ * @public
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': StandardSchemaV1Props<Input, Output>;
+}
+/**
+ * The properties of the `~standard` key on a Standard Schema.
+ *
+ * @typeParam Input - The input type the schema accepts
+ * @typeParam Output - The output type after validation/transformation
+ *
+ * @public
+ */
+export interface StandardSchemaV1Props<Input = unknown, Output = Input> {
+    /** The version of the Standard Schema specification (always 1) */
+    readonly version: 1;
+    /** The name of the schema library (e.g., "zod", "valibot", "arktype") */
+    readonly vendor: string;
+    /** Optional type metadata for input and output types */
+    readonly types?: StandardSchemaV1Types<Input, Output>;
+    /** Validates an unknown value and returns a result */
+    readonly validate: (value: unknown) => StandardSchemaV1Result<Output> | Promise<StandardSchemaV1Result<Output>>;
+}
+/**
+ * Type metadata for Standard Schema input and output types.
+ *
+ * @remarks
+ * This is optional metadata used for type inference. The actual values
+ * are typically `undefined` at runtime - they exist purely for TypeScript.
+ *
+ * @typeParam Input - The input type
+ * @typeParam Output - The output type
+ *
+ * @public
+ */
+export interface StandardSchemaV1Types<Input = unknown, Output = Input> {
+    /** The input type (for type inference only) */
+    readonly input: Input;
+    /** The output type (for type inference only) */
+    readonly output: Output;
+}
+/**
+ * The result of a Standard Schema validation.
+ *
+ * @typeParam Output - The output type on success
+ *
+ * @public
+ */
+export type StandardSchemaV1Result<Output> = StandardSchemaV1SuccessResult<Output> | StandardSchemaV1FailureResult;
+/**
+ * A successful validation result containing the validated/transformed value.
+ *
+ * @typeParam Output - The output type
+ *
+ * @public
+ */
+export interface StandardSchemaV1SuccessResult<Output> {
+    /** The validated and potentially transformed value */
+    readonly value: Output;
+    /** Undefined on success */
+    readonly issues?: undefined;
+}
+/**
+ * A failed validation result containing validation issues.
+ *
+ * @public
+ */
+export interface StandardSchemaV1FailureResult {
+    /** Array of validation issues */
+    readonly issues: ReadonlyArray<StandardSchemaV1Issue>;
+}
+/**
+ * A validation issue from a Standard Schema.
+ *
+ * @public
+ */
+export interface StandardSchemaV1Issue {
+    /** Human-readable error message */
+    readonly message: string;
+    /** Path to the invalid value (for nested objects/arrays) */
+    readonly path?: ReadonlyArray<PropertyKey | StandardSchemaV1PathSegment>;
+}
+/**
+ * A path segment for nested validation issues.
+ *
+ * @public
+ */
+export interface StandardSchemaV1PathSegment {
+    /** The property key or array index */
+    readonly key: PropertyKey;
+}
+/**
+ * Infers the input type from a Standard Schema.
+ *
+ * @typeParam Schema - The Standard Schema type
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * const schema = z.string().email();
+ * type Input = InferInput<typeof schema>; // string
+ * ```
+ *
+ * @public
+ */
+export type InferInput<Schema extends StandardSchemaV1> = Schema extends StandardSchemaV1<infer I, unknown> ? I : never;
+/**
+ * Infers the output type from a Standard Schema.
+ *
+ * @typeParam Schema - The Standard Schema type
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * const schema = z.string().transform(s => s.length);
+ * type Output = InferOutput<typeof schema>; // number
+ * ```
+ *
+ * @public
+ */
+export type InferOutput<Schema extends StandardSchemaV1> = Schema extends StandardSchemaV1<unknown, infer O> ? O : never;
+/**
+ * Type guard to check if a value is a Standard Schema.
+ *
+ * @param value - The value to check
+ * @returns True if the value implements StandardSchemaV1
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * const schema = z.string();
+ * if (isStandardSchema(schema)) {
+ *   // schema is StandardSchemaV1
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
+/**
+ * Validates a value using a Standard Schema (synchronous only).
+ *
+ * @remarks
+ * This function only supports synchronous validation. If the schema returns
+ * a Promise, an error is thrown with instructions to use a sync schema.
+ *
+ * @typeParam T - The expected output type
+ * @param schema - The Standard Schema to validate with
+ * @param value - The value to validate
+ * @param propName - The prop name (for error messages)
+ * @returns The validated and potentially transformed value
+ * @throws Error if validation fails or schema is async
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * const schema = z.string().email();
+ * const email = validateWithSchema(schema, 'user@example.com', 'email');
+ * // email is typed as string
+ * ```
+ *
+ * @internal
+ */
+export declare function validateWithSchema<T>(schema: StandardSchemaV1<unknown, T>, value: unknown, propName: string): T;

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 consumer and host 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 consumer.
+ *
+ * @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 consumer
+ * @param definitions - Prop definitions
+ * @param messenger - Messenger for function calls
+ * @param bridge - Function bridge for deserializing functions
+ * @param consumerWin - Consumer window reference
+ * @param consumerDomain - Consumer origin domain
+ * @returns Deserialized props
+ *
+ * @public
+ */
+export declare function deserializeProps<P extends Record<string, unknown>>(serialized: SerializedProps, definitions: PropsDefinition<P>, messenger: Messenger, bridge: FunctionBridge, consumerWin: Window, consumerDomain: 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';