forgeframe 1.0.0

package/dist/drivers/react.d.ts

@@ -0,0 +1,225 @@
+import type { ForgeFrameComponent } from '../types';
+import type { ContextType } from '../constants';
+/**
+ * Minimal React-like interface for driver compatibility.
+ *
+ * @remarks
+ * These are minimal type definitions to avoid requiring `@types/react` as a dependency.
+ * The driver only uses a subset of React's API, so any React-compatible library
+ * (such as Preact with compat) can be used as long as it implements these methods.
+ *
+ * @internal
+ */
+interface ReactLike {
+    createElement: (type: unknown, props?: Record<string, unknown> | null, ...children: unknown[]) => unknown;
+    useRef: <T>(initial: T | null) => {
+        current: T | null;
+    };
+    useEffect: (effect: () => void | (() => void), deps?: unknown[]) => void;
+    useState: <T>(initial: T) => [T, (v: T) => void];
+    forwardRef: <T, P>(render: (props: P, ref: {
+        current: T | null;
+    } | null) => unknown) => unknown;
+}
+/**
+ * Props for the generated React component wrapper.
+ *
+ * @remarks
+ * These props are available on all React components created by the driver,
+ * in addition to the component-specific props defined in the ForgeFrame component.
+ *
+ * @typeParam _P - The component-specific props type (unused in base interface)
+ *
+ * @public
+ */
+export interface ReactComponentProps<_P = unknown> {
+    /**
+     * Callback invoked when the component has finished rendering.
+     *
+     * @remarks
+     * This is called once the cross-domain component has been fully mounted
+     * and is visible to the user.
+     */
+    onRendered?: () => void;
+    /**
+     * Callback invoked when the component encounters an error.
+     *
+     * @param error - The error that occurred during rendering or operation
+     *
+     * @remarks
+     * Errors can occur during initial render, prop updates, or cross-domain communication.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Callback invoked when the component is closed.
+     *
+     * @remarks
+     * This is triggered when the cross-domain component is programmatically closed
+     * or when the user closes a popup window.
+     */
+    onClose?: () => void;
+    /**
+     * The rendering context for the component.
+     *
+     * @remarks
+     * Determines whether the component renders in an iframe or popup window.
+     * Defaults to the component's configured default context.
+     */
+    context?: ContextType;
+    /**
+     * CSS class name applied to the container element.
+     *
+     * @remarks
+     * The container is a `div` element that wraps the iframe or serves as
+     * the anchor point for popup positioning.
+     */
+    className?: string;
+    /**
+     * Inline styles applied to the container element.
+     *
+     * @remarks
+     * These styles are merged with the default container styles.
+     * The container defaults to `display: inline-block`.
+     */
+    style?: Record<string, string | number>;
+}
+/**
+ * Full props type combining driver props with component-specific props.
+ *
+ * @typeParam P - The component-specific props type from the ForgeFrame component
+ *
+ * @remarks
+ * This type merges {@link ReactComponentProps} with the component's own props,
+ * making all component props optional since they can have defaults.
+ *
+ * @internal
+ */
+type FullReactComponentProps<P> = ReactComponentProps<P> & Partial<P>;
+/**
+ * Configuration options for creating a React driver.
+ *
+ * @remarks
+ * The React instance must be provided to avoid bundling React with the driver.
+ * This allows the driver to work with any version of React that implements
+ * the required hooks and methods.
+ *
+ * @public
+ */
+export interface ReactDriverOptions {
+    /**
+     * The React library instance to use for component creation.
+     *
+     * @remarks
+     * Must provide `createElement`, `useRef`, `useEffect`, `useState`, and `forwardRef`.
+     * Compatible with React 16.8+ and Preact with compat.
+     */
+    React: ReactLike;
+}
+/**
+ * Type definition for a React component created by the driver.
+ *
+ * @typeParam P - The props type for the component
+ *
+ * @remarks
+ * This interface represents the callable component function returned by
+ * {@link createReactDriver}. It includes an optional `displayName` for
+ * React DevTools integration.
+ *
+ * @public
+ */
+export interface ReactComponentType<P> {
+    /**
+     * Renders the component with the given props.
+     *
+     * @param props - The component props
+     * @returns A React element (type varies by React version)
+     */
+    (props: P): unknown;
+    /**
+     * Display name shown in React DevTools.
+     *
+     * @remarks
+     * Automatically set to `ForgeFrame(ComponentName)` by the driver.
+     */
+    displayName?: string;
+}
+/**
+ * Creates a React component wrapper for a ForgeFrame cross-domain component.
+ *
+ * @typeParam P - The props type defined in the ForgeFrame component
+ * @typeParam X - The export type for data shared from the child component
+ *
+ * @param Component - The ForgeFrame component to wrap
+ * @param options - Configuration options including the React instance
+ *
+ * @returns A React component that renders the ForgeFrame component
+ *
+ * @remarks
+ * This function bridges ForgeFrame's cross-domain component system with React's
+ * component model. The returned component handles:
+ * - Mounting and unmounting lifecycle
+ * - Prop synchronization with the cross-domain component
+ * - Error boundary integration via the `onError` callback
+ * - Ref forwarding to the container element
+ *
+ * The component automatically cleans up the cross-domain connection when unmounted.
+ *
+ * @example
+ * ```tsx
+ * import React from 'react';
+ * import ForgeFrame from 'forgeframe';
+ * import { createReactDriver } from 'forgeframe/drivers/react';
+ *
+ * const LoginComponent = ForgeFrame.create({
+ *   tag: 'login-component',
+ *   url: 'https://example.com/login',
+ *   props: {
+ *     onLogin: { type: ForgeFrame.PROP_TYPE.FUNCTION },
+ *   },
+ * });
+ *
+ * const LoginReact = createReactDriver(LoginComponent, { React });
+ *
+ * // Usage in JSX:
+ * <LoginReact onLogin={(user) => console.log(user)} />
+ * ```
+ *
+ * @public
+ */
+export declare function createReactDriver<P extends Record<string, unknown>, X = unknown>(Component: ForgeFrameComponent<P, X>, options: ReactDriverOptions): ReactComponentType<FullReactComponentProps<P>>;
+/**
+ * Creates a curried React driver factory with a pre-configured React instance.
+ *
+ * @param React - The React library instance to use for all created components
+ *
+ * @returns A function that creates React wrappers for ForgeFrame components
+ *
+ * @remarks
+ * This is a higher-order function that simplifies creating multiple React drivers
+ * with the same React instance. It returns a driver factory that can be reused
+ * across multiple ForgeFrame components.
+ *
+ * This pattern is useful when you have many ForgeFrame components and want to
+ * avoid passing the React instance repeatedly.
+ *
+ * @example
+ * ```tsx
+ * import React from 'react';
+ * import ForgeFrame from 'forgeframe';
+ * import { withReactDriver } from 'forgeframe/drivers/react';
+ *
+ * // Create a reusable driver factory
+ * const createDriver = withReactDriver(React);
+ *
+ * // Create multiple React components using the same factory
+ * const LoginComponent = ForgeFrame.create({ tag: 'login', url: '...' });
+ * const ProfileComponent = ForgeFrame.create({ tag: 'profile', url: '...' });
+ *
+ * const LoginReact = createDriver(LoginComponent);
+ * const ProfileReact = createDriver(ProfileComponent);
+ * ```
+ *
+ * @public
+ */
+export declare function withReactDriver(React: ReactLike): <P extends Record<string, unknown>, X = unknown>(Component: ForgeFrameComponent<P, X>) => ReactComponentType<FullReactComponentProps<P>>;
+export default createReactDriver;

package/dist/events/emitter.d.ts

@@ -0,0 +1,150 @@
+import type { EventHandler, EventEmitterInterface } from '../types';
+/**
+ * A simple typed event emitter for component lifecycle events.
+ *
+ * @remarks
+ * This class provides a lightweight publish-subscribe pattern implementation
+ * with support for typed events, one-time subscriptions, and automatic cleanup.
+ * It is used internally by ForgeFrame components for lifecycle event management.
+ *
+ * @example
+ * ```typescript
+ * const emitter = new EventEmitter();
+ *
+ * // Subscribe to an event
+ * const unsubscribe = emitter.on<string>('message', (data) => {
+ *   console.log('Received:', data);
+ * });
+ *
+ * // Emit an event
+ * emitter.emit('message', 'Hello, World!');
+ *
+ * // Unsubscribe when done
+ * unsubscribe();
+ * ```
+ *
+ * @public
+ */
+export declare class EventEmitter implements EventEmitterInterface {
+    /**
+     * Internal storage for event listeners mapped by event name.
+     * @internal
+     */
+    private listeners;
+    /**
+     * Subscribes a handler to a specific event.
+     *
+     * @typeParam T - The type of data expected by the event handler
+     * @param event - The name of the event to subscribe to
+     * @param handler - The callback function to invoke when the event is emitted
+     * @returns A function that, when called, unsubscribes the handler from the event
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = emitter.on<{ userId: string }>('login', (data) => {
+     *   console.log('User logged in:', data.userId);
+     * });
+     * ```
+     *
+     * @public
+     */
+    on<T = unknown>(event: string, handler: EventHandler<T>): () => void;
+    /**
+     * Subscribes a handler to an event that will automatically unsubscribe after the first invocation.
+     *
+     * @typeParam T - The type of data expected by the event handler
+     * @param event - The name of the event to subscribe to
+     * @param handler - The callback function to invoke once when the event is emitted
+     * @returns A function that, when called, unsubscribes the handler before it fires
+     *
+     * @remarks
+     * This is useful for one-time event handling, such as waiting for an initialization
+     * event or a single response.
+     *
+     * @example
+     * ```typescript
+     * emitter.once('ready', () => {
+     *   console.log('Component is ready!');
+     * });
+     * ```
+     *
+     * @public
+     */
+    once<T = unknown>(event: string, handler: EventHandler<T>): () => void;
+    /**
+     * Emits an event, invoking all registered handlers with the provided data.
+     *
+     * @typeParam T - The type of data to pass to event handlers
+     * @param event - The name of the event to emit
+     * @param data - Optional data to pass to all registered handlers
+     *
+     * @remarks
+     * Handlers are invoked synchronously in the order they were registered.
+     * If a handler throws an error, it is caught and logged to the console,
+     * allowing subsequent handlers to still execute.
+     *
+     * @example
+     * ```typescript
+     * emitter.emit('userAction', { action: 'click', target: 'button' });
+     * ```
+     *
+     * @public
+     */
+    emit<T = unknown>(event: string, data?: T): void;
+    /**
+     * Unsubscribes a handler from an event, or removes all handlers for the event.
+     *
+     * @param event - The name of the event to unsubscribe from
+     * @param handler - The specific handler to remove. If not provided, all handlers for the event are removed.
+     *
+     * @remarks
+     * When a specific handler is removed and it was the last handler for that event,
+     * the event entry is cleaned up from the internal map.
+     *
+     * @example
+     * ```typescript
+     * // Remove a specific handler
+     * emitter.off('message', myHandler);
+     *
+     * // Remove all handlers for an event
+     * emitter.off('message');
+     * ```
+     *
+     * @public
+     */
+    off(event: string, handler?: EventHandler): void;
+    /**
+     * Removes all event listeners from the emitter.
+     *
+     * @remarks
+     * This method is typically called during component cleanup or disposal
+     * to ensure no memory leaks from lingering event subscriptions.
+     *
+     * @example
+     * ```typescript
+     * // Clean up all listeners when component is destroyed
+     * emitter.removeAllListeners();
+     * ```
+     *
+     * @public
+     */
+    removeAllListeners(): void;
+    /**
+     * Returns the number of listeners registered for a specific event.
+     *
+     * @param event - The name of the event to check
+     * @returns The number of handlers currently subscribed to the event
+     *
+     * @remarks
+     * This method is primarily useful for debugging and testing purposes
+     * to verify that subscriptions are being properly managed.
+     *
+     * @example
+     * ```typescript
+     * console.log(`Active listeners: ${emitter.listenerCount('message')}`);
+     * ```
+     *
+     * @public
+     */
+    listenerCount(event: string): number;
+}