forgeframe 1.0.0

package/dist/window/helpers.d.ts

@@ -0,0 +1,316 @@
+import type { DomainMatcher } from '../types';
+/**
+ * Gets the domain (origin) of the specified window.
+ *
+ * @param win - The window to get the domain from. Defaults to the current window.
+ * @returns The origin string (e.g., "https://example.com") or an empty string if cross-origin access is denied.
+ *
+ * @remarks
+ * This function safely handles cross-origin windows by catching security exceptions
+ * and returning an empty string instead of throwing.
+ *
+ * @example
+ * ```typescript
+ * // Get current window's domain
+ * const domain = getDomain();
+ *
+ * // Get an iframe's domain
+ * const iframeDomain = getDomain(iframe.contentWindow);
+ * ```
+ *
+ * @public
+ */
+export declare function getDomain(win?: Window): string;
+/**
+ * Checks if a window is from the same domain as a reference window.
+ *
+ * @param win - The window to check.
+ * @param reference - The reference window to compare against. Defaults to the current window.
+ * @returns `true` if both windows share the same origin, `false` otherwise.
+ *
+ * @remarks
+ * This function compares the origin of both windows. If cross-origin access
+ * throws a security exception, it returns `false`.
+ *
+ * @example
+ * ```typescript
+ * // Check if an iframe is same-origin
+ * if (isSameDomain(iframe.contentWindow)) {
+ *   // Safe to access iframe's DOM directly
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function isSameDomain(win: Window, reference?: Window): boolean;
+/**
+ * Checks if a domain matches a given pattern.
+ *
+ * @param pattern - The pattern to match against. Can be a string (exact match or `"*"` wildcard),
+ *                  a RegExp, or an array of patterns.
+ * @param domain - The domain string to test.
+ * @returns `true` if the domain matches the pattern, `false` otherwise.
+ *
+ * @remarks
+ * Pattern matching rules:
+ * - `"*"` matches any domain
+ * - String patterns require exact match
+ * - RegExp patterns use `.test()` method
+ * - Array patterns return `true` if any element matches (OR logic)
+ *
+ * @example
+ * ```typescript
+ * // Wildcard - matches everything
+ * matchDomain('*', 'https://example.com'); // true
+ *
+ * // Exact match
+ * matchDomain('https://example.com', 'https://example.com'); // true
+ *
+ * // RegExp match
+ * matchDomain(/\.example\.com$/, 'https://sub.example.com'); // true
+ *
+ * // Array of patterns
+ * matchDomain(['https://a.com', 'https://b.com'], 'https://b.com'); // true
+ * ```
+ *
+ * @public
+ */
+export declare function matchDomain(pattern: DomainMatcher, domain: string): boolean;
+/**
+ * Checks if a window is closed or inaccessible.
+ *
+ * @param win - The window to check, or `null`.
+ * @returns `true` if the window is `null`, closed, or inaccessible; `false` otherwise.
+ *
+ * @remarks
+ * This function safely handles cross-origin errors. If accessing the window's
+ * `closed` property throws, the window is considered closed or inaccessible.
+ *
+ * @example
+ * ```typescript
+ * const popup = window.open('https://example.com');
+ * // Later...
+ * if (isWindowClosed(popup)) {
+ *   console.log('Popup was closed');
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function isWindowClosed(win: Window | null): boolean;
+/**
+ * Gets the opener window for a popup window.
+ *
+ * @param win - The popup window. Defaults to the current window.
+ * @returns The opener window, or `null` if not a popup or cross-origin access is denied.
+ *
+ * @remarks
+ * The opener is the window that called `window.open()` to create this popup.
+ * This function safely handles cross-origin errors.
+ *
+ * @example
+ * ```typescript
+ * // In a popup window
+ * const parent = getOpener();
+ * if (parent) {
+ *   // Communicate with opener
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function getOpener(win?: Window): Window | null;
+/**
+ * Gets the parent window for an iframe.
+ *
+ * @param win - The iframe window. Defaults to the current window.
+ * @returns The parent window, or `null` if not in an iframe or cross-origin access is denied.
+ *
+ * @remarks
+ * Returns `null` if the window is the top-level window (i.e., `parent === self`).
+ * This function safely handles cross-origin errors.
+ *
+ * @example
+ * ```typescript
+ * // In an iframe
+ * const parent = getParent();
+ * if (parent) {
+ *   // Communicate with parent frame
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function getParent(win?: Window): Window | null;
+/**
+ * Gets the top-level window in the frame hierarchy.
+ *
+ * @param win - The window to get the top from. Defaults to the current window.
+ * @returns The top-level window, or `null` if cross-origin access is denied.
+ *
+ * @remarks
+ * The top window is the outermost window in a nested iframe hierarchy.
+ * This function safely handles cross-origin errors.
+ *
+ * @example
+ * ```typescript
+ * const topWindow = getTop();
+ * if (topWindow === window) {
+ *   console.log('We are the top-level window');
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function getTop(win?: Window): Window | null;
+/**
+ * Checks if the specified window is running inside an iframe.
+ *
+ * @param win - The window to check. Defaults to the current window.
+ * @returns `true` if the window is in an iframe, `false` if it's the top-level window.
+ *
+ * @remarks
+ * A window is considered to be in an iframe if `parent !== self`.
+ * If cross-origin access throws an exception, returns `true` as a conservative assumption.
+ *
+ * @example
+ * ```typescript
+ * if (isIframe()) {
+ *   console.log('Running inside an iframe');
+ * } else {
+ *   console.log('Running as top-level window');
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function isIframe(win?: Window): boolean;
+/**
+ * Checks if the specified window is a popup (opened via `window.open()`).
+ *
+ * @param win - The window to check. Defaults to the current window.
+ * @returns `true` if the window has an opener (is a popup), `false` otherwise.
+ *
+ * @remarks
+ * A popup window is one that was opened using `window.open()` and has an `opener` reference.
+ * This function safely handles cross-origin errors by returning `false`.
+ *
+ * @example
+ * ```typescript
+ * if (isPopup()) {
+ *   console.log('This window was opened as a popup');
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function isPopup(win?: Window): boolean;
+/**
+ * Gets an ancestor window at a specific distance in the frame hierarchy.
+ *
+ * @param win - The starting window. Defaults to the current window.
+ * @param distance - The number of levels to traverse up. 1 = parent, 2 = grandparent, etc.
+ * @returns The ancestor window at the specified distance, or `null` if not found.
+ *
+ * @remarks
+ * This function traverses up the parent chain the specified number of times.
+ * Returns `null` if the chain ends before reaching the target distance.
+ *
+ * @example
+ * ```typescript
+ * // Get the grandparent window (2 levels up)
+ * const grandparent = getAncestor(window, 2);
+ *
+ * // Get the parent window (equivalent to getParent())
+ * const parent = getAncestor(window, 1);
+ * ```
+ *
+ * @public
+ */
+export declare function getAncestor(win: Window | undefined, distance: number): Window | null;
+/**
+ * Calculates the distance (number of levels) from a child window to a parent window.
+ *
+ * @param child - The child window to start from.
+ * @param parent - The target parent window.
+ * @returns The number of levels between child and parent, or `-1` if the parent is not an ancestor.
+ *
+ * @remarks
+ * This function traverses up the parent chain from the child window, counting levels
+ * until it finds the target parent. Has a safety limit of 100 levels to prevent infinite loops.
+ *
+ * @example
+ * ```typescript
+ * // If iframe is nested 2 levels deep
+ * const distance = getDistanceToParent(iframe.contentWindow, window.top);
+ * console.log(distance); // 2
+ *
+ * // If not an ancestor
+ * const notFound = getDistanceToParent(windowA, windowB);
+ * console.log(notFound); // -1
+ * ```
+ *
+ * @public
+ */
+export declare function getDistanceToParent(child: Window, parent: Window): number;
+/**
+ * Attempts to focus a window.
+ *
+ * @param win - The window to focus.
+ *
+ * @remarks
+ * This function safely attempts to focus the specified window.
+ * Focus may fail silently due to browser restrictions or cross-origin policies.
+ *
+ * @example
+ * ```typescript
+ * const popup = window.open('https://example.com');
+ * focusWindow(popup);
+ * ```
+ *
+ * @public
+ */
+export declare function focusWindow(win: Window): void;
+/**
+ * Attempts to close a window.
+ *
+ * @param win - The window to close.
+ *
+ * @remarks
+ * This function safely attempts to close the specified window.
+ * Close may fail silently due to browser restrictions (e.g., scripts can only
+ * close windows they opened).
+ *
+ * @example
+ * ```typescript
+ * const popup = window.open('https://example.com');
+ * // Later, close the popup
+ * closeWindow(popup);
+ * ```
+ *
+ * @public
+ */
+export declare function closeWindow(win: Window): void;
+/**
+ * Gets all child frames (iframes) within a window.
+ *
+ * @param win - The window to get frames from. Defaults to the current window.
+ * @returns An array of Window objects representing the child frames.
+ *
+ * @remarks
+ * This function iterates over the window's frames collection and returns them as an array.
+ * If cross-origin access is denied, returns an empty array.
+ *
+ * @example
+ * ```typescript
+ * const childFrames = getFrames();
+ * console.log(`Found ${childFrames.length} iframes`);
+ *
+ * childFrames.forEach((frame, index) => {
+ *   console.log(`Frame ${index}:`, getDomain(frame));
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function getFrames(win?: Window): Window[];

package/dist/window/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Window utilities for ForgeFrame cross-window communication.
+ *
+ * @remarks
+ * This module provides utilities for working with browser windows in cross-origin
+ * contexts. It includes helpers for domain matching, window hierarchy navigation,
+ * window name payload encoding/decoding, and window reference management.
+ *
+ * @packageDocumentation
+ */
+export { getDomain, isSameDomain, matchDomain, isWindowClosed, getOpener, getParent, getTop, isIframe, isPopup, getAncestor, getDistanceToParent, focusWindow, closeWindow, getFrames, } from './helpers';
+export { buildWindowName, parseWindowName, isForgeFrameWindow, isChildOfComponent, createWindowPayload, updateWindowName, getInitialPayload, } from './name-payload';
+export { registerWindow, unregisterWindow, getWindowByUID, createWindowRef, resolveWindowRef, serializeWindowRef, clearWindowRegistry, } from './proxy';

package/dist/window/name-payload.d.ts

@@ -0,0 +1,188 @@
+import type { WindowNamePayload, SerializedProps, ParentExports, ChildComponentRef } from '../types';
+import type { ContextType } from '../constants';
+/**
+ * Builds a window name string with an encoded payload.
+ *
+ * @typeParam P - The type of the props included in the payload.
+ * @param payload - The payload to encode into the window name.
+ * @returns A window name string with the ForgeFrame prefix and base64-encoded payload.
+ *
+ * @remarks
+ * This is the primary mechanism for passing initial props from a parent window
+ * to a child window (iframe or popup). The payload is JSON-serialized and base64-encoded
+ * to ensure safe transport via the window.name property.
+ *
+ * @example
+ * ```typescript
+ * const payload: WindowNamePayload<MyProps> = {
+ *   uid: 'child-123',
+ *   tag: 'my-component',
+ *   version: '1.0.0',
+ *   context: 'iframe',
+ *   parentDomain: 'https://parent.com',
+ *   props: { message: 'Hello' },
+ *   exports: {}
+ * };
+ *
+ * const windowName = buildWindowName(payload);
+ * // Use when creating iframe: iframe.name = windowName;
+ * ```
+ *
+ * @public
+ */
+export declare function buildWindowName<P>(payload: WindowNamePayload<P>): string;
+/**
+ * Parses a window name to extract the encoded payload.
+ *
+ * @typeParam P - The expected type of the props in the payload.
+ * @param name - The window name string to parse.
+ * @returns The decoded WindowNamePayload, or `null` if the name is not a valid ForgeFrame window name.
+ *
+ * @remarks
+ * This function checks if the window name starts with the ForgeFrame prefix,
+ * then decodes the base64-encoded payload. Returns `null` if the name doesn't
+ * have the expected format or if decoding fails.
+ *
+ * @example
+ * ```typescript
+ * // In a child window
+ * const payload = parseWindowName<MyProps>(window.name);
+ * if (payload) {
+ *   console.log('Received props:', payload.props);
+ *   console.log('Parent domain:', payload.parentDomain);
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function parseWindowName<P>(name: string): WindowNamePayload<P> | null;
+/**
+ * Checks if the specified window is a ForgeFrame child window.
+ *
+ * @param win - The window to check. Defaults to the current window.
+ * @returns `true` if the window's name starts with the ForgeFrame prefix, `false` otherwise.
+ *
+ * @remarks
+ * A ForgeFrame child window is identified by having a window name that starts
+ * with the ForgeFrame prefix. This function safely handles cross-origin errors.
+ *
+ * @example
+ * ```typescript
+ * if (isForgeFrameWindow()) {
+ *   // This window was created by ForgeFrame
+ *   const payload = getInitialPayload();
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function isForgeFrameWindow(win?: Window): boolean;
+/**
+ * Checks if the current window is a child of a specific component tag.
+ *
+ * @param tag - The component tag to check for.
+ * @param win - The window to check. Defaults to the current window.
+ * @returns `true` if the window's payload has the specified tag, `false` otherwise.
+ *
+ * @remarks
+ * This function parses the window name and checks if the tag in the payload
+ * matches the specified tag. Useful for component-specific initialization logic.
+ *
+ * @example
+ * ```typescript
+ * if (isChildOfComponent('payment-form')) {
+ *   // Initialize payment-specific features
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function isChildOfComponent(tag: string, win?: Window): boolean;
+/**
+ * Creates a window payload object for encoding into a window name.
+ *
+ * @typeParam P - The type of the props (used for type inference in the returned payload).
+ * @param options - The options for creating the payload.
+ * @param options.uid - Unique identifier for the child window.
+ * @param options.tag - Component tag name.
+ * @param options.context - The context type (e.g., 'iframe' or 'popup').
+ * @param options.parentDomain - The origin of the parent window.
+ * @param options.props - Serialized props to pass to the child.
+ * @param options.exports - Functions exported by the parent for the child to call.
+ * @param options.children - Optional map of child component references.
+ * @returns A WindowNamePayload object ready for encoding.
+ *
+ * @remarks
+ * This is a factory function that creates a properly structured payload with
+ * the current ForgeFrame version automatically included.
+ *
+ * @example
+ * ```typescript
+ * const payload = createWindowPayload<MyProps>({
+ *   uid: generateUID(),
+ *   tag: 'checkout-form',
+ *   context: 'iframe',
+ *   parentDomain: window.location.origin,
+ *   props: { amount: 100 },
+ *   exports: { onSuccess: true, onError: true }
+ * });
+ *
+ * const windowName = buildWindowName(payload);
+ * ```
+ *
+ * @public
+ */
+export declare function createWindowPayload<P>(options: {
+    uid: string;
+    tag: string;
+    context: ContextType;
+    parentDomain: string;
+    props: SerializedProps;
+    exports: ParentExports;
+    children?: Record<string, ChildComponentRef>;
+}): WindowNamePayload<P>;
+/**
+ * Updates a window's name with a new encoded payload.
+ *
+ * @typeParam P - The type of the props in the payload.
+ * @param win - The window whose name should be updated.
+ * @param payload - The new payload to encode into the window name.
+ *
+ * @remarks
+ * This function is used when the parent needs to update the child's reference
+ * or pass updated data. It safely handles cross-origin errors by silently failing.
+ *
+ * @example
+ * ```typescript
+ * // Update child window with new props
+ * const updatedPayload = { ...existingPayload, props: { newValue: 42 } };
+ * updateWindowName(childWindow, updatedPayload);
+ * ```
+ *
+ * @public
+ */
+export declare function updateWindowName<P>(win: Window, payload: WindowNamePayload<P>): void;
+/**
+ * Gets the initial payload from a window's name.
+ *
+ * @typeParam P - The expected type of the props in the payload.
+ * @param win - The window to read the payload from. Defaults to the current window.
+ * @returns The decoded WindowNamePayload, or `null` if not a ForgeFrame window.
+ *
+ * @remarks
+ * This is a convenience function typically used by child components during
+ * initialization to read the data passed by the parent window.
+ *
+ * @example
+ * ```typescript
+ * // In child window initialization
+ * const payload = getInitialPayload<MyProps>();
+ * if (payload) {
+ *   initializeComponent(payload.props);
+ *   setupParentCommunication(payload.parentDomain);
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function getInitialPayload<P>(win?: Window): WindowNamePayload<P> | null;

package/dist/window/proxy.d.ts

@@ -0,0 +1,168 @@
+import type { WindowRef } from '../types';
+/**
+ * Registers a window with a unique identifier for later retrieval.
+ *
+ * @param uid - The unique identifier for the window.
+ * @param win - The window to register.
+ *
+ * @remarks
+ * Registered windows can be retrieved later using {@link getWindowByUID}.
+ * This is useful for maintaining references to windows across different contexts.
+ *
+ * The registry automatically cleans up closed windows when new windows are
+ * registered to prevent memory leaks. A maximum of 100 windows can be
+ * registered at a time.
+ *
+ * @example
+ * ```typescript
+ * const popup = window.open('https://example.com');
+ * registerWindow('my-popup-123', popup);
+ *
+ * // Later, retrieve the window
+ * const retrievedPopup = getWindowByUID('my-popup-123');
+ * ```
+ *
+ * @public
+ */
+export declare function registerWindow(uid: string, win: Window): void;
+/**
+ * Unregisters a window from the registry.
+ *
+ * @param uid - The unique identifier of the window to unregister.
+ *
+ * @remarks
+ * Call this function when a window is closed or no longer needed to prevent memory leaks.
+ *
+ * @example
+ * ```typescript
+ * // When done with a popup
+ * unregisterWindow('my-popup-123');
+ * ```
+ *
+ * @public
+ */
+export declare function unregisterWindow(uid: string): void;
+/**
+ * Retrieves a registered window by its unique identifier.
+ *
+ * @param uid - The unique identifier of the window to retrieve.
+ * @returns The registered window, or `null` if not found.
+ *
+ * @remarks
+ * Windows must be registered using {@link registerWindow} before they can be retrieved.
+ *
+ * @example
+ * ```typescript
+ * const popup = getWindowByUID('my-popup-123');
+ * if (popup) {
+ *   popup.postMessage({ type: 'hello' }, '*');
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function getWindowByUID(uid: string): Window | null;
+/**
+ * Creates a serializable reference to a target window.
+ *
+ * @param targetWin - The window to create a reference for.
+ * @param sourceWin - The source window context. Defaults to the current window.
+ * @returns A WindowRef object that describes how to reach the target window.
+ *
+ * @remarks
+ * This function analyzes the relationship between the source and target windows
+ * and creates an appropriate reference type:
+ * - `opener`: Target is the source's opener (for popups)
+ * - `parent`: Target is an ancestor in the frame hierarchy
+ * - `direct`: Direct window reference (only works same-origin)
+ *
+ * The returned reference can be serialized for cross-window communication,
+ * except for `direct` type which contains an actual Window object.
+ *
+ * @example
+ * ```typescript
+ * // Create a reference to the parent window
+ * const parentRef = createWindowRef(window.parent);
+ * console.log(parentRef); // { type: 'parent', distance: 1 }
+ *
+ * // Create a reference to the opener
+ * const openerRef = createWindowRef(window.opener);
+ * console.log(openerRef); // { type: 'opener' }
+ * ```
+ *
+ * @public
+ */
+export declare function createWindowRef(targetWin: Window, sourceWin?: Window): WindowRef;
+/**
+ * Resolves a window reference to an actual Window object.
+ *
+ * @param ref - The window reference to resolve.
+ * @param sourceWin - The source window context. Defaults to the current window.
+ * @returns The resolved Window object, or `null` if resolution fails.
+ *
+ * @remarks
+ * This function is the inverse of {@link createWindowRef}. It takes a WindowRef
+ * and returns the actual Window object it references. Supports all reference types:
+ * - `opener`: Returns the opener window
+ * - `parent`: Returns the ancestor at the specified distance
+ * - `global`: Looks up the window in the registry by UID
+ * - `direct`: Returns the directly referenced window
+ *
+ * @example
+ * ```typescript
+ * // Resolve a parent reference
+ * const ref: WindowRef = { type: 'parent', distance: 1 };
+ * const parentWindow = resolveWindowRef(ref);
+ *
+ * // Resolve a global reference
+ * const globalRef: WindowRef = { type: 'global', uid: 'my-popup-123' };
+ * const popup = resolveWindowRef(globalRef);
+ * ```
+ *
+ * @public
+ */
+export declare function resolveWindowRef(ref: WindowRef, sourceWin?: Window): Window | null;
+/**
+ * Serializes a window reference for cross-domain transfer.
+ *
+ * @param ref - The window reference to serialize.
+ * @returns The serialized window reference.
+ * @throws Error if the reference is a `direct` type, which cannot be serialized.
+ *
+ * @remarks
+ * Direct window references contain actual Window objects which cannot be
+ * transferred via postMessage. Convert direct references to global references
+ * using {@link registerWindow} before serialization.
+ *
+ * @example
+ * ```typescript
+ * // This works - parent reference is serializable
+ * const parentRef: WindowRef = { type: 'parent', distance: 1 };
+ * const serialized = serializeWindowRef(parentRef);
+ *
+ * // This throws - direct references are not serializable
+ * const directRef: WindowRef = { type: 'direct', win: someWindow };
+ * serializeWindowRef(directRef); // Error!
+ * ```
+ *
+ * @public
+ */
+export declare function serializeWindowRef(ref: WindowRef): WindowRef;
+/**
+ * Clears all registered windows from the registry.
+ *
+ * @remarks
+ * This function removes all window entries from the global registry.
+ * Primarily useful for cleanup during testing or when resetting application state.
+ *
+ * @example
+ * ```typescript
+ * // In a test teardown
+ * afterEach(() => {
+ *   clearWindowRegistry();
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function clearWindowRegistry(): void;