forgeframe 1.0.0

package/dist/render/popup.d.ts

@@ -0,0 +1,215 @@
+import type { Dimensions } from '../types';
+/**
+ * Configuration options for opening a popup window.
+ *
+ * @public
+ */
+export interface PopupOptions {
+    /**
+     * The URL to load in the popup window.
+     */
+    url: string;
+    /**
+     * The name/target for the popup window.
+     *
+     * @remarks
+     * This is used as the window name for `window.open()`. If a window with
+     * this name already exists, the URL will be loaded in that window.
+     */
+    name: string;
+    /**
+     * The dimensions for the popup window.
+     *
+     * @remarks
+     * String dimension values will be parsed as integers (e.g., `'500px'` becomes `500`).
+     * If a dimension cannot be parsed, a default of 500 pixels is used.
+     */
+    dimensions: Dimensions;
+}
+/**
+ * Error thrown when a popup window is blocked by the browser.
+ *
+ * @remarks
+ * Modern browsers block popup windows that are not triggered by direct user
+ * interaction (e.g., click events). This error is thrown by {@link openPopup}
+ * when the browser prevents the popup from opening.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const popup = openPopup({ ... });
+ * } catch (error) {
+ *   if (error instanceof PopupOpenError) {
+ *     alert('Please allow popups for this site');
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare class PopupOpenError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Opens a popup window centered on the screen with the specified options.
+ *
+ * @remarks
+ * This function creates a popup window using `window.open()` with sensible
+ * defaults for security and usability:
+ * - The popup is centered relative to the parent window
+ * - The location bar is always shown (required for security)
+ * - The popup is resizable and has scrollbars
+ * - Menu bar, toolbar, and status bar are hidden
+ *
+ * If the popup is blocked by the browser (e.g., due to popup blockers or
+ * lack of user interaction), a {@link PopupOpenError} is thrown.
+ *
+ * @param options - Configuration options for the popup
+ * @returns The opened Window object
+ * @throws {@link PopupOpenError} If the popup is blocked by the browser
+ *
+ * @example
+ * ```typescript
+ * // Open a popup for authentication
+ * try {
+ *   const authPopup = openPopup({
+ *     url: 'https://auth.example.com/login',
+ *     name: 'auth-popup',
+ *     dimensions: { width: 500, height: 600 }
+ *   });
+ *
+ *   // Watch for the popup to close
+ *   watchPopupClose(authPopup, () => {
+ *     console.log('Authentication completed');
+ *   });
+ * } catch (error) {
+ *   if (error instanceof PopupOpenError) {
+ *     // Handle blocked popup
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function openPopup(options: PopupOptions): Window;
+/**
+ * Closes a popup window if it is still open.
+ *
+ * @remarks
+ * This function safely closes a popup window by first checking if it is
+ * already closed. Any errors during the close operation (e.g., due to
+ * cross-origin restrictions) are silently ignored.
+ *
+ * @param win - The popup Window object to close
+ *
+ * @example
+ * ```typescript
+ * const popup = openPopup({ ... });
+ * // Later, when done:
+ * closePopup(popup);
+ * ```
+ *
+ * @public
+ */
+export declare function closePopup(win: Window): void;
+/**
+ * Brings a popup window to the foreground by focusing it.
+ *
+ * @remarks
+ * This function attempts to focus a popup window if it is still open.
+ * Any errors during the focus operation are silently ignored, as some
+ * browsers may restrict focusing windows in certain contexts.
+ *
+ * @param win - The popup Window object to focus
+ *
+ * @example
+ * ```typescript
+ * // Refocus the popup when user clicks a button
+ * button.addEventListener('click', () => {
+ *   focusPopup(popup);
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function focusPopup(win: Window): void;
+/**
+ * Checks if a popup window was blocked by the browser.
+ *
+ * @remarks
+ * This function uses multiple heuristics to detect blocked popups:
+ * - `null` window reference indicates the popup was blocked
+ * - Attempting to access properties on a blocked popup throws an error
+ * - Some browsers return a window with zero dimensions when blocked
+ *
+ * @param win - The Window object to check, or `null` if the popup failed to open
+ * @returns `true` if the popup appears to be blocked, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * const win = window.open(url, name, features);
+ * if (isPopupBlocked(win)) {
+ *   console.error('Popup was blocked by the browser');
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function isPopupBlocked(win: Window | null): boolean;
+/**
+ * Watches a popup window and invokes a callback when it closes.
+ *
+ * @remarks
+ * This function polls the popup window's `closed` property using exponential
+ * backoff - starting with fast checks and slowing down over time. This approach
+ * catches quick closes immediately while reducing CPU usage for long-running popups.
+ *
+ * If the window becomes inaccessible (e.g., due to navigation to a different
+ * origin), the callback is also invoked and polling stops.
+ *
+ * @param win - The popup Window object to watch
+ * @param callback - Function to call when the popup closes
+ * @param options - Optional configuration for polling intervals
+ * @returns A cleanup function that stops watching when called
+ *
+ * @example
+ * ```typescript
+ * const popup = openPopup({ ... });
+ *
+ * const stopWatching = watchPopupClose(popup, () => {
+ *   console.log('Popup was closed');
+ *   // Handle post-close logic (e.g., check authentication state)
+ * });
+ *
+ * // Optionally stop watching early
+ * stopWatching();
+ * ```
+ *
+ * @public
+ */
+export declare function watchPopupClose(win: Window, callback: () => void, options?: {
+    initialInterval?: number;
+    maxInterval?: number;
+    multiplier?: number;
+}): () => void;
+/**
+ * Resizes a popup window to the specified dimensions.
+ *
+ * @remarks
+ * This function attempts to resize the popup window using `window.resizeTo()`.
+ * Some browsers may restrict window resizing for security reasons, in which
+ * case errors are silently ignored.
+ *
+ * If a dimension is not specified, the current window dimension is preserved.
+ *
+ * @param win - The popup Window object to resize
+ * @param dimensions - The new dimensions for the popup
+ *
+ * @example
+ * ```typescript
+ * resizePopup(popup, { width: 800, height: 600 });
+ * ```
+ *
+ * @public
+ */
+export declare function resizePopup(win: Window, dimensions: Dimensions): void;

package/dist/render/templates.d.ts

@@ -0,0 +1,202 @@
+import type { TemplateContext, Dimensions } from '../types';
+/**
+ * Creates the default container element for ForgeFrame components.
+ *
+ * @remarks
+ * This template creates a wrapper `<div>` element that holds the iframe or
+ * popup content. The container is styled as an inline-block with relative
+ * positioning to support absolute positioning of child elements like
+ * prerender overlays.
+ *
+ * The container includes:
+ * - A unique ID based on the component's UID
+ * - A `data-forgeframe-tag` attribute for identification
+ * - Base styles for dimensions and overflow handling
+ *
+ * @typeParam P - The props type for the component
+ * @param ctx - The template context containing document, dimensions, and metadata
+ * @returns The created container HTMLElement
+ *
+ * @example
+ * ```typescript
+ * const container = defaultContainerTemplate({
+ *   doc: document,
+ *   dimensions: { width: 400, height: 300 },
+ *   uid: 'abc123',
+ *   tag: 'payment-button',
+ *   props: {}
+ * });
+ * document.body.appendChild(container);
+ * ```
+ *
+ * @public
+ */
+export declare function defaultContainerTemplate<P>(ctx: TemplateContext<P>): HTMLElement;
+/**
+ * Creates the default prerender template showing a loading spinner.
+ *
+ * @remarks
+ * This template creates an overlay element displayed while the actual
+ * component content is loading. It includes:
+ * - A centered wrapper with a light gray background
+ * - An animated spinning loader
+ * - CSS keyframes for the spin animation
+ *
+ * The overlay uses absolute positioning to cover the container and
+ * a high z-index to appear above other content.
+ *
+ * If a CSP (Content Security Policy) nonce is provided, it will be
+ * applied to the inline style element to comply with security policies.
+ *
+ * @typeParam P - The props type for the component
+ * @param ctx - The template context with optional CSP nonce
+ * @returns The created prerender overlay HTMLElement
+ *
+ * @example
+ * ```typescript
+ * const prerender = defaultPrerenderTemplate({
+ *   doc: document,
+ *   dimensions: { width: 400, height: 300 },
+ *   uid: 'abc123',
+ *   tag: 'payment-button',
+ *   props: {},
+ *   cspNonce: 'abc123xyz'
+ * });
+ * container.appendChild(prerender);
+ * ```
+ *
+ * @public
+ */
+export declare function defaultPrerenderTemplate<P>(ctx: TemplateContext<P> & {
+    cspNonce?: string;
+}): HTMLElement;
+/**
+ * Applies width and height dimensions to an HTML element.
+ *
+ * @remarks
+ * Only dimensions that are defined will be applied. Numeric values are
+ * automatically converted to pixel strings. This function can be used
+ * to resize any HTML element, not just iframes.
+ *
+ * @param element - The HTML element to apply dimensions to
+ * @param dimensions - The dimensions object containing width and/or height
+ *
+ * @example
+ * ```typescript
+ * const div = document.createElement('div');
+ * applyDimensions(div, { width: 400, height: 300 });
+ * applyDimensions(div, { width: '100%' }); // Only width, height unchanged
+ * ```
+ *
+ * @public
+ */
+export declare function applyDimensions(element: HTMLElement, dimensions: Dimensions): void;
+/**
+ * Creates a `<style>` element with the provided CSS content.
+ *
+ * @remarks
+ * This utility function creates an inline style element that can be appended
+ * to the document. If a CSP (Content Security Policy) nonce is provided,
+ * it will be set on the style element to allow the styles to be applied
+ * in environments with strict CSP rules.
+ *
+ * @param doc - The Document object to create the element in
+ * @param css - The CSS content to include in the style element
+ * @param nonce - Optional CSP nonce for security compliance
+ * @returns The created HTMLStyleElement
+ *
+ * @example
+ * ```typescript
+ * const style = createStyleElement(
+ *   document,
+ *   '.my-class { color: red; }',
+ *   'abc123xyz'
+ * );
+ * document.head.appendChild(style);
+ * ```
+ *
+ * @public
+ */
+export declare function createStyleElement(doc: Document, css: string, nonce?: string): HTMLStyleElement;
+/**
+ * Animates an element fading in from transparent to fully opaque.
+ *
+ * @remarks
+ * This function applies a CSS opacity transition to create a smooth fade-in
+ * effect. It sets the initial opacity to 0, triggers a reflow to ensure the
+ * transition applies, then sets opacity to 1.
+ *
+ * The returned Promise resolves after the animation duration completes.
+ * Note that the Promise uses `setTimeout` rather than `transitionend` events
+ * for more predictable behavior across browsers.
+ *
+ * @param element - The HTML element to fade in
+ * @param duration - Animation duration in milliseconds (default: 200)
+ * @returns A Promise that resolves when the animation completes
+ *
+ * @example
+ * ```typescript
+ * const element = document.getElementById('my-element')!;
+ * await fadeIn(element, 300);
+ * console.log('Fade in complete');
+ * ```
+ *
+ * @public
+ */
+export declare function fadeIn(element: HTMLElement, duration?: number): Promise<void>;
+/**
+ * Animates an element fading out from its current opacity to transparent.
+ *
+ * @remarks
+ * This function applies a CSS opacity transition to create a smooth fade-out
+ * effect. Unlike {@link fadeIn}, it does not force a reflow since the element
+ * is already visible and the transition can begin immediately.
+ *
+ * The returned Promise resolves after the animation duration completes.
+ * Note that this function only changes opacity; the element remains in the
+ * DOM and may need to be removed or hidden separately after fading out.
+ *
+ * @param element - The HTML element to fade out
+ * @param duration - Animation duration in milliseconds (default: 200)
+ * @returns A Promise that resolves when the animation completes
+ *
+ * @example
+ * ```typescript
+ * const element = document.getElementById('my-element')!;
+ * await fadeOut(element, 300);
+ * element.remove(); // Remove after fade completes
+ * ```
+ *
+ * @public
+ */
+export declare function fadeOut(element: HTMLElement, duration?: number): Promise<void>;
+/**
+ * Swaps the prerender placeholder with the actual content using fade animations.
+ *
+ * @remarks
+ * This function performs a smooth transition from the prerender loading state
+ * to the actual content. The process:
+ * 1. If a prerender element exists, fade it out and remove it from the DOM
+ * 2. Set the actual content's initial opacity to 0
+ * 3. Append the actual content to the container
+ * 4. Fade in the actual content
+ *
+ * Both fade animations use a 150ms duration for a quick but smooth transition.
+ *
+ * @param container - The parent container element
+ * @param prerenderElement - The prerender placeholder element, or `null` if none exists
+ * @param actualElement - The actual content element to display
+ * @returns A Promise that resolves when the swap animation completes
+ *
+ * @example
+ * ```typescript
+ * const container = document.getElementById('widget-container')!;
+ * const prerender = container.querySelector('.prerender');
+ * const iframe = createIframe({ ... });
+ *
+ * await swapPrerenderContent(container, prerender, iframe);
+ * ```
+ *
+ * @public
+ */
+export declare function swapPrerenderContent(_container: HTMLElement, prerenderElement: HTMLElement | null, actualElement: HTMLElement): Promise<void>;