@pwfabric/runtime 0.0.0-stage → 1.0.0-rc.1

package/dist/a11y/keyboard.js

@@ -0,0 +1,317 @@
+/**
+ * Keyboard Navigation Manager
+ *
+ * Provides arrow-key navigation for composite widgets (tabs, menus,
+ * listboxes) and roving tabindex management. All DOM operations are
+ * SSR-safe.
+ *
+ * @module @pwfabric/runtime/a11y/keyboard
+ */
+// ============================================================
+// CONSTANTS
+// ============================================================
+const DEFAULT_SELECTOR = '[role="option"], [role="tab"], button, a';
+// ============================================================
+// KEYBOARD NAVIGATION MANAGER
+// ============================================================
+/**
+ * Manages keyboard navigation within a composite widget.
+ *
+ * Listens for arrow key events on a container and moves focus
+ * between child items matching a configurable selector. Supports
+ * horizontal, vertical, or both directional navigation with
+ * optional looping at boundaries.
+ */
+export class KeyboardNavigationManager {
+    config;
+    currentIndex;
+    boundHandleKeyDown;
+    constructor() {
+        this.config = null;
+        this.currentIndex = 0;
+        this.boundHandleKeyDown = this.handleKeyDown.bind(this);
+    }
+    /**
+     * Activate keyboard navigation on the given container.
+     *
+     * @param config - Keyboard navigation configuration
+     */
+    activate(config) {
+        if (typeof document === 'undefined')
+            return;
+        if (!config.container)
+            return;
+        if (this.config) {
+            this.deactivate();
+        }
+        this.config = {
+            ...config,
+            loop: config.loop ?? true,
+            selector: config.selector ?? DEFAULT_SELECTOR,
+        };
+        this.currentIndex = 0;
+        this.config.container?.addEventListener('keydown', this.boundHandleKeyDown);
+    }
+    /**
+     * Deactivate keyboard navigation and remove event listeners.
+     */
+    deactivate() {
+        if (!this.config?.container)
+            return;
+        this.config.container.removeEventListener('keydown', this.boundHandleKeyDown);
+        this.config = null;
+        this.currentIndex = 0;
+    }
+    /**
+     * Move focus to the next item in the navigation order.
+     */
+    focusNext() {
+        const items = this.getItems();
+        if (items.length === 0)
+            return;
+        const nextIndex = this.currentIndex + 1;
+        if (nextIndex >= items.length) {
+            if (this.config?.loop) {
+                this.currentIndex = 0;
+            }
+            else {
+                return;
+            }
+        }
+        else {
+            this.currentIndex = nextIndex;
+        }
+        items[this.currentIndex]?.focus();
+    }
+    /**
+     * Move focus to the previous item in the navigation order.
+     */
+    focusPrevious() {
+        const items = this.getItems();
+        if (items.length === 0)
+            return;
+        const prevIndex = this.currentIndex - 1;
+        if (prevIndex < 0) {
+            if (this.config?.loop) {
+                this.currentIndex = items.length - 1;
+            }
+            else {
+                return;
+            }
+        }
+        else {
+            this.currentIndex = prevIndex;
+        }
+        items[this.currentIndex]?.focus();
+    }
+    /**
+     * Move focus to the first item.
+     */
+    focusFirst() {
+        const items = this.getItems();
+        if (items.length === 0)
+            return;
+        this.currentIndex = 0;
+        items[0]?.focus();
+    }
+    /**
+     * Move focus to the last item.
+     */
+    focusLast() {
+        const items = this.getItems();
+        if (items.length === 0)
+            return;
+        this.currentIndex = items.length - 1;
+        items[this.currentIndex]?.focus();
+    }
+    /**
+     * Get the current focused item index.
+     *
+     * @returns The zero-based index of the currently focused item
+     */
+    getCurrentIndex() {
+        return this.currentIndex;
+    }
+    /**
+     * Dispose of the keyboard navigation manager, removing all listeners.
+     */
+    dispose() {
+        this.deactivate();
+    }
+    // ============================================================
+    // PRIVATE METHODS
+    // ============================================================
+    /**
+     * Handle keydown events for arrow key navigation and Home/End support.
+     */
+    handleKeyDown(event) {
+        if (!this.config)
+            return;
+        const { direction } = this.config;
+        let handled = false;
+        switch (event.key) {
+            case 'ArrowRight':
+                if (direction === 'horizontal' || direction === 'both') {
+                    this.focusNext();
+                    handled = true;
+                }
+                break;
+            case 'ArrowLeft':
+                if (direction === 'horizontal' || direction === 'both') {
+                    this.focusPrevious();
+                    handled = true;
+                }
+                break;
+            case 'ArrowDown':
+                if (direction === 'vertical' || direction === 'both') {
+                    this.focusNext();
+                    handled = true;
+                }
+                break;
+            case 'ArrowUp':
+                if (direction === 'vertical' || direction === 'both') {
+                    this.focusPrevious();
+                    handled = true;
+                }
+                break;
+            case 'Home':
+                this.focusFirst();
+                handled = true;
+                break;
+            case 'End':
+                this.focusLast();
+                handled = true;
+                break;
+        }
+        if (handled) {
+            event.preventDefault();
+        }
+    }
+    /**
+     * Query navigable items from the container, filtered to visible elements.
+     *
+     * @returns Array of focusable HTMLElements within the container
+     */
+    getItems() {
+        if (!this.config?.container)
+            return [];
+        const selector = this.config.selector ?? DEFAULT_SELECTOR;
+        const elements = this.config.container.querySelectorAll(selector);
+        return Array.from(elements).filter((el) => {
+            // Exclude disabled and hidden elements
+            if (el.hasAttribute('disabled'))
+                return false;
+            if (el.getAttribute('aria-hidden') === 'true')
+                return false;
+            return el.offsetParent !== null || el.offsetWidth > 0 || el.offsetHeight > 0;
+        });
+    }
+}
+// ============================================================
+// ROVING TABINDEX
+// ============================================================
+/**
+ * Manages roving tabindex for composite widgets.
+ *
+ * In the roving tabindex pattern, only one item within a group
+ * has `tabindex="0"` (making it tabbable), while all other items
+ * have `tabindex="-1"`. This allows the group to participate in
+ * the page tab order as a single stop, with arrow keys used to
+ * navigate between items within the group.
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex
+ */
+export class RovingTabIndex {
+    container;
+    selector;
+    /**
+     * @param selector - CSS selector for items managed by roving tabindex
+     */
+    constructor(selector) {
+        this.container = null;
+        this.selector = selector ?? DEFAULT_SELECTOR;
+    }
+    /**
+     * Attach roving tabindex management to a container.
+     *
+     * Sets `tabindex="-1"` on all matching items except the first,
+     * which gets `tabindex="0"`.
+     *
+     * @param container - The container element
+     */
+    attach(container) {
+        if (typeof document === 'undefined')
+            return;
+        this.container = container;
+        const items = this.getItems();
+        items.forEach((item, index) => {
+            item.setAttribute('tabindex', index === 0 ? '0' : '-1');
+        });
+    }
+    /**
+     * Detach roving tabindex management, restoring all items to `tabindex="0"`.
+     */
+    detach() {
+        if (!this.container)
+            return;
+        const items = this.getItems();
+        items.forEach((item) => {
+            item.setAttribute('tabindex', '0');
+        });
+        this.container = null;
+    }
+    /**
+     * Set a specific element as the active (tabbable) item.
+     *
+     * The target receives `tabindex="0"` and all sibling items
+     * receive `tabindex="-1"`.
+     *
+     * @param element - The element to make active
+     */
+    setActive(element) {
+        if (!this.container)
+            return;
+        const items = this.getItems();
+        for (const item of items) {
+            item.setAttribute('tabindex', item === element ? '0' : '-1');
+        }
+    }
+    /**
+     * Dispose of the roving tabindex manager.
+     */
+    dispose() {
+        this.detach();
+    }
+    // ============================================================
+    // PRIVATE METHODS
+    // ============================================================
+    /**
+     * Query managed items from the container.
+     */
+    getItems() {
+        if (!this.container)
+            return [];
+        return Array.from(this.container.querySelectorAll(this.selector));
+    }
+}
+// ============================================================
+// FACTORY FUNCTIONS
+// ============================================================
+/**
+ * Create a new KeyboardNavigationManager instance.
+ *
+ * @returns A new KeyboardNavigationManager
+ */
+export function createKeyboardNav() {
+    return new KeyboardNavigationManager();
+}
+/**
+ * Create a new RovingTabIndex instance.
+ *
+ * @param selector - CSS selector for managed items
+ * @returns A new RovingTabIndex
+ */
+export function createRovingTabIndex(selector) {
+    return new RovingTabIndex(selector);
+}
+//# sourceMappingURL=keyboard.js.map

package/dist/a11y/keyboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyboard.js","sourceRoot":"","sources":["../../src/a11y/keyboard.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Keyboard Navigation Manager\n *\n * Provides arrow-key navigation for composite widgets (tabs, menus,\n * listboxes) and roving tabindex management. All DOM operations are\n * SSR-safe.\n *\n * @module @pwfabric/runtime/a11y/keyboard\n */\n\n// ============================================================\n// TYPES\n// ============================================================\n\n/** Direction(s) in which arrow key navigation operates */\nexport type ArrowDirection = 'horizontal' | 'vertical' | 'both'\n\n/** Configuration for keyboard navigation */\nexport interface KeyboardNavConfig {\n  /** Container element holding navigable items */\n  container: HTMLElement | null\n  /** Direction of arrow key navigation */\n  direction: ArrowDirection\n  /** Whether navigation wraps around at boundaries (default true) */\n  loop?: boolean\n  /** CSS selector for navigable items (default '[role=\"option\"], [role=\"tab\"], button, a') */\n  selector?: string\n}\n\n// ============================================================\n// CONSTANTS\n// ============================================================\n\nconst DEFAULT_SELECTOR = '[role=\"option\"], [role=\"tab\"], button, a'\n\n// ============================================================\n// KEYBOARD NAVIGATION MANAGER\n// ============================================================\n\n/**\n * Manages keyboard navigation within a composite widget.\n *\n * Listens for arrow key events on a container and moves focus\n * between child items matching a configurable selector. Supports\n * horizontal, vertical, or both directional navigation with\n * optional looping at boundaries.\n */\nexport class KeyboardNavigationManager {\n  private config: KeyboardNavConfig | null\n  private currentIndex: number\n  private readonly boundHandleKeyDown: (event: KeyboardEvent) => void\n\n  constructor() {\n    this.config = null\n    this.currentIndex = 0\n    this.boundHandleKeyDown = this.handleKeyDown.bind(this)\n  }\n\n  /**\n   * Activate keyboard navigation on the given container.\n   *\n   * @param config - Keyboard navigation configuration\n   */\n  activate(config: KeyboardNavConfig): void {\n    if (typeof document === 'undefined') return\n    if (!config.container) return\n    if (this.config) {\n      this.deactivate()\n    }\n\n    this.config = {\n      ...config,\n      loop: config.loop ?? true,\n      selector: config.selector ?? DEFAULT_SELECTOR,\n    }\n    this.currentIndex = 0\n\n    this.config.container?.addEventListener('keydown', this.boundHandleKeyDown)\n  }\n\n  /**\n   * Deactivate keyboard navigation and remove event listeners.\n   */\n  deactivate(): void {\n    if (!this.config?.container) return\n\n    this.config.container.removeEventListener('keydown', this.boundHandleKeyDown)\n    this.config = null\n    this.currentIndex = 0\n  }\n\n  /**\n   * Move focus to the next item in the navigation order.\n   */\n  focusNext(): void {\n    const items = this.getItems()\n    if (items.length === 0) return\n\n    const nextIndex = this.currentIndex + 1\n\n    if (nextIndex >= items.length) {\n      if (this.config?.loop) {\n        this.currentIndex = 0\n      } else {\n        return\n      }\n    } else {\n      this.currentIndex = nextIndex\n    }\n\n    items[this.currentIndex]?.focus()\n  }\n\n  /**\n   * Move focus to the previous item in the navigation order.\n   */\n  focusPrevious(): void {\n    const items = this.getItems()\n    if (items.length === 0) return\n\n    const prevIndex = this.currentIndex - 1\n\n    if (prevIndex < 0) {\n      if (this.config?.loop) {\n        this.currentIndex = items.length - 1\n      } else {\n        return\n      }\n    } else {\n      this.currentIndex = prevIndex\n    }\n\n    items[this.currentIndex]?.focus()\n  }\n\n  /**\n   * Move focus to the first item.\n   */\n  focusFirst(): void {\n    const items = this.getItems()\n    if (items.length === 0) return\n\n    this.currentIndex = 0\n    items[0]?.focus()\n  }\n\n  /**\n   * Move focus to the last item.\n   */\n  focusLast(): void {\n    const items = this.getItems()\n    if (items.length === 0) return\n\n    this.currentIndex = items.length - 1\n    items[this.currentIndex]?.focus()\n  }\n\n  /**\n   * Get the current focused item index.\n   *\n   * @returns The zero-based index of the currently focused item\n   */\n  getCurrentIndex(): number {\n    return this.currentIndex\n  }\n\n  /**\n   * Dispose of the keyboard navigation manager, removing all listeners.\n   */\n  dispose(): void {\n    this.deactivate()\n  }\n\n  // ============================================================\n  // PRIVATE METHODS\n  // ============================================================\n\n  /**\n   * Handle keydown events for arrow key navigation and Home/End support.\n   */\n  private handleKeyDown(event: KeyboardEvent): void {\n    if (!this.config) return\n\n    const { direction } = this.config\n    let handled = false\n\n    switch (event.key) {\n      case 'ArrowRight':\n        if (direction === 'horizontal' || direction === 'both') {\n          this.focusNext()\n          handled = true\n        }\n        break\n\n      case 'ArrowLeft':\n        if (direction === 'horizontal' || direction === 'both') {\n          this.focusPrevious()\n          handled = true\n        }\n        break\n\n      case 'ArrowDown':\n        if (direction === 'vertical' || direction === 'both') {\n          this.focusNext()\n          handled = true\n        }\n        break\n\n      case 'ArrowUp':\n        if (direction === 'vertical' || direction === 'both') {\n          this.focusPrevious()\n          handled = true\n        }\n        break\n\n      case 'Home':\n        this.focusFirst()\n        handled = true\n        break\n\n      case 'End':\n        this.focusLast()\n        handled = true\n        break\n    }\n\n    if (handled) {\n      event.preventDefault()\n    }\n  }\n\n  /**\n   * Query navigable items from the container, filtered to visible elements.\n   *\n   * @returns Array of focusable HTMLElements within the container\n   */\n  private getItems(): HTMLElement[] {\n    if (!this.config?.container) return []\n\n    const selector = this.config.selector ?? DEFAULT_SELECTOR\n    const elements = this.config.container.querySelectorAll<HTMLElement>(selector)\n\n    return Array.from(elements).filter((el) => {\n      // Exclude disabled and hidden elements\n      if (el.hasAttribute('disabled')) return false\n      if (el.getAttribute('aria-hidden') === 'true') return false\n      return el.offsetParent !== null || el.offsetWidth > 0 || el.offsetHeight > 0\n    })\n  }\n}\n\n// ============================================================\n// ROVING TABINDEX\n// ============================================================\n\n/**\n * Manages roving tabindex for composite widgets.\n *\n * In the roving tabindex pattern, only one item within a group\n * has `tabindex=\"0\"` (making it tabbable), while all other items\n * have `tabindex=\"-1\"`. This allows the group to participate in\n * the page tab order as a single stop, with arrow keys used to\n * navigate between items within the group.\n *\n * @see https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex\n */\nexport class RovingTabIndex {\n  private container: HTMLElement | null\n  private selector: string\n\n  /**\n   * @param selector - CSS selector for items managed by roving tabindex\n   */\n  constructor(selector?: string) {\n    this.container = null\n    this.selector = selector ?? DEFAULT_SELECTOR\n  }\n\n  /**\n   * Attach roving tabindex management to a container.\n   *\n   * Sets `tabindex=\"-1\"` on all matching items except the first,\n   * which gets `tabindex=\"0\"`.\n   *\n   * @param container - The container element\n   */\n  attach(container: HTMLElement): void {\n    if (typeof document === 'undefined') return\n\n    this.container = container\n    const items = this.getItems()\n\n    items.forEach((item, index) => {\n      item.setAttribute('tabindex', index === 0 ? '0' : '-1')\n    })\n  }\n\n  /**\n   * Detach roving tabindex management, restoring all items to `tabindex=\"0\"`.\n   */\n  detach(): void {\n    if (!this.container) return\n\n    const items = this.getItems()\n    items.forEach((item) => {\n      item.setAttribute('tabindex', '0')\n    })\n\n    this.container = null\n  }\n\n  /**\n   * Set a specific element as the active (tabbable) item.\n   *\n   * The target receives `tabindex=\"0\"` and all sibling items\n   * receive `tabindex=\"-1\"`.\n   *\n   * @param element - The element to make active\n   */\n  setActive(element: HTMLElement): void {\n    if (!this.container) return\n\n    const items = this.getItems()\n    for (const item of items) {\n      item.setAttribute('tabindex', item === element ? '0' : '-1')\n    }\n  }\n\n  /**\n   * Dispose of the roving tabindex manager.\n   */\n  dispose(): void {\n    this.detach()\n  }\n\n  // ============================================================\n  // PRIVATE METHODS\n  // ============================================================\n\n  /**\n   * Query managed items from the container.\n   */\n  private getItems(): HTMLElement[] {\n    if (!this.container) return []\n    return Array.from(this.container.querySelectorAll<HTMLElement>(this.selector))\n  }\n}\n\n// ============================================================\n// FACTORY FUNCTIONS\n// ============================================================\n\n/**\n * Create a new KeyboardNavigationManager instance.\n *\n * @returns A new KeyboardNavigationManager\n */\nexport function createKeyboardNav(): KeyboardNavigationManager {\n  return new KeyboardNavigationManager()\n}\n\n/**\n * Create a new RovingTabIndex instance.\n *\n * @param selector - CSS selector for managed items\n * @returns A new RovingTabIndex\n */\nexport function createRovingTabIndex(selector?: string): RovingTabIndex {\n  return new RovingTabIndex(selector)\n}\n"]}

package/dist/adapters/default-image.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Default Image Adapter
+ *
+ * Renders images using native HTML img element.
+ * This is the fallback adapter used when no framework-specific
+ * adapter is provided.
+ *
+ * @module @pwfabric/runtime/adapters/default-image
+ */
+import type { ImageAdapter } from './types.js';
+/**
+ * Default image adapter using native img element
+ *
+ * Provides basic image rendering with CSS-based styling.
+ * Supports lazy loading via the native loading attribute.
+ *
+ * @example
+ * ```tsx
+ * <SurfaceRenderer
+ *   surface={mySurface}
+ *   imageAdapter={DefaultImageAdapter}
+ * />
+ * ```
+ */
+export declare const DefaultImageAdapter: ImageAdapter;

package/dist/adapters/default-image.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Convert CSS unit value to string
+ */
+function cssUnit(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'number')
+        return `${value}px`;
+    return value;
+}
+/**
+ * Default image adapter using native img element
+ *
+ * Provides basic image rendering with CSS-based styling.
+ * Supports lazy loading via the native loading attribute.
+ *
+ * @example
+ * ```tsx
+ * <SurfaceRenderer
+ *   surface={mySurface}
+ *   imageAdapter={DefaultImageAdapter}
+ * />
+ * ```
+ */
+export const DefaultImageAdapter = ({ src, alt, width, height, loading, objectFit, aspectRatio, borderRadius, className, style, blockId, }) => {
+    const computedStyle = {
+        width: cssUnit(width) ?? '100%',
+        height: cssUnit(height) ?? 'auto',
+        objectFit: objectFit ?? 'cover',
+        aspectRatio,
+        borderRadius: cssUnit(borderRadius),
+        ...style,
+    };
+    return (_jsx("img", { id: blockId, src: src || '/placeholder.png', alt: alt ?? '', style: computedStyle, className: className, loading: loading ?? 'lazy', "data-block-type": "image" }));
+};
+//# sourceMappingURL=default-image.js.map

package/dist/adapters/default-image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-image.js","sourceRoot":"","sources":["../../src/adapters/default-image.tsx"],"names":[],"mappings":";AAaA;;GAEG;AACH,SAAS,OAAO,CAAC,KAAkC;IACjD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IACzC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,GAAG,KAAK,IAAI,CAAA;IAClD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAiB,CAAC,EAChD,GAAG,EACH,GAAG,EACH,KAAK,EACL,MAAM,EACN,OAAO,EACP,SAAS,EACT,WAAW,EACX,YAAY,EACZ,SAAS,EACT,KAAK,EACL,OAAO,GACW,EAAsB,EAAE;IAC1C,MAAM,aAAa,GAAwB;QACzC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI,MAAM;QAC/B,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM;QACjC,SAAS,EAAE,SAAS,IAAI,OAAO;QAC/B,WAAW;QACX,YAAY,EAAE,OAAO,CAAC,YAAY,CAAC;QACnC,GAAG,KAAK;KACT,CAAA;IAED,OAAO,CACL,cACE,EAAE,EAAE,OAAO,EACX,GAAG,EAAE,GAAG,IAAI,kBAAkB,EAC9B,GAAG,EAAE,GAAG,IAAI,EAAE,EACd,KAAK,EAAE,aAAa,EACpB,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,OAAO,IAAI,MAAM,qBACV,OAAO,GACvB,CACH,CAAA;AACH,CAAC,CAAA","sourcesContent":["/**\n * Default Image Adapter\n *\n * Renders images using native HTML img element.\n * This is the fallback adapter used when no framework-specific\n * adapter is provided.\n *\n * @module @pwfabric/runtime/adapters/default-image\n */\n\nimport * as React from 'react'\nimport type { ImageAdapter, ImageAdapterProps } from './types.js'\n\n/**\n * Convert CSS unit value to string\n */\nfunction cssUnit(value: number | string | undefined): string | undefined {\n  if (value === undefined) return undefined\n  if (typeof value === 'number') return `${value}px`\n  return value\n}\n\n/**\n * Default image adapter using native img element\n *\n * Provides basic image rendering with CSS-based styling.\n * Supports lazy loading via the native loading attribute.\n *\n * @example\n * ```tsx\n * <SurfaceRenderer\n *   surface={mySurface}\n *   imageAdapter={DefaultImageAdapter}\n * />\n * ```\n */\nexport const DefaultImageAdapter: ImageAdapter = ({\n  src,\n  alt,\n  width,\n  height,\n  loading,\n  objectFit,\n  aspectRatio,\n  borderRadius,\n  className,\n  style,\n  blockId,\n}: ImageAdapterProps): React.ReactElement => {\n  const computedStyle: React.CSSProperties = {\n    width: cssUnit(width) ?? '100%',\n    height: cssUnit(height) ?? 'auto',\n    objectFit: objectFit ?? 'cover',\n    aspectRatio,\n    borderRadius: cssUnit(borderRadius),\n    ...style,\n  }\n\n  return (\n    <img\n      id={blockId}\n      src={src || '/placeholder.png'}\n      alt={alt ?? ''}\n      style={computedStyle}\n      className={className}\n      loading={loading ?? 'lazy'}\n      data-block-type=\"image\"\n    />\n  )\n}\n"]}

package/dist/adapters/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Image Adapters
+ *
+ * Framework-specific image optimization adapters for SurfaceRenderer.
+ * Enables Next.js Image, Astro Image, etc. while keeping surface
+ * definitions framework-agnostic.
+ *
+ * @module @pwfabric/runtime/adapters
+ *
+ * @example
+ * ```tsx
+ * import { SurfaceRenderer } from '@pwfabric/runtime'
+ * import { NextImageAdapter } from '@pwfabric/runtime/adapters'
+ *
+ * function MyPage() {
+ *   return (
+ *     <SurfaceRenderer
+ *       surface={mySurface}
+ *       imageAdapter={NextImageAdapter}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export type { ImageAdapter, ImageAdapterProps } from './types.js';
+export { DefaultImageAdapter } from './default-image.js';
+export { NextImageAdapter } from './next-image.js';

package/dist/adapters/index.js

@@ -0,0 +1,28 @@
+/**
+ * Image Adapters
+ *
+ * Framework-specific image optimization adapters for SurfaceRenderer.
+ * Enables Next.js Image, Astro Image, etc. while keeping surface
+ * definitions framework-agnostic.
+ *
+ * @module @pwfabric/runtime/adapters
+ *
+ * @example
+ * ```tsx
+ * import { SurfaceRenderer } from '@pwfabric/runtime'
+ * import { NextImageAdapter } from '@pwfabric/runtime/adapters'
+ *
+ * function MyPage() {
+ *   return (
+ *     <SurfaceRenderer
+ *       surface={mySurface}
+ *       imageAdapter={NextImageAdapter}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+// Adapters
+export { DefaultImageAdapter } from './default-image.js';
+export { NextImageAdapter } from './next-image.js';
+//# sourceMappingURL=index.js.map

package/dist/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,WAAW;AACX,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA","sourcesContent":["/**\n * Image Adapters\n *\n * Framework-specific image optimization adapters for SurfaceRenderer.\n * Enables Next.js Image, Astro Image, etc. while keeping surface\n * definitions framework-agnostic.\n *\n * @module @pwfabric/runtime/adapters\n *\n * @example\n * ```tsx\n * import { SurfaceRenderer } from '@pwfabric/runtime'\n * import { NextImageAdapter } from '@pwfabric/runtime/adapters'\n *\n * function MyPage() {\n *   return (\n *     <SurfaceRenderer\n *       surface={mySurface}\n *       imageAdapter={NextImageAdapter}\n *     />\n *   )\n * }\n * ```\n */\n\n// Types\nexport type { ImageAdapter, ImageAdapterProps } from './types.js'\n\n// Adapters\nexport { DefaultImageAdapter } from './default-image.js'\nexport { NextImageAdapter } from './next-image.js'\n"]}

package/dist/adapters/next-image.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Next.js Image Adapter
+ *
+ * Renders images using Next.js Image component for automatic
+ * optimization, responsive images, and modern image formats.
+ *
+ * NOTE: This adapter requires `next` as a peer dependency.
+ * Only import this adapter in Next.js applications.
+ *
+ * @module @pwfabric/runtime/adapters/next-image
+ */
+import type { ImageAdapter } from './types.js';
+/**
+ * Next.js Image adapter for optimized image delivery
+ *
+ * Leverages Next.js Image component features:
+ * - Automatic image optimization
+ * - Responsive image generation
+ * - Modern format support (WebP, AVIF)
+ * - Lazy loading with native browser support
+ * - Priority loading for LCP images
+ *
+ * @example
+ * ```tsx
+ * import { SurfaceRenderer } from '@pwfabric/runtime'
+ * import { NextImageAdapter } from '@pwfabric/runtime/adapters'
+ *
+ * function MyPage() {
+ *   return (
+ *     <SurfaceRenderer
+ *       surface={mySurface}
+ *       imageAdapter={NextImageAdapter}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export declare const NextImageAdapter: ImageAdapter;

package/dist/adapters/next-image.js

@@ -0,0 +1,124 @@
+/**
+ * Next.js Image Adapter
+ *
+ * Renders images using Next.js Image component for automatic
+ * optimization, responsive images, and modern image formats.
+ *
+ * NOTE: This adapter requires `next` as a peer dependency.
+ * Only import this adapter in Next.js applications.
+ *
+ * @module @pwfabric/runtime/adapters/next-image
+ */
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from 'react';
+// Lazy load next/image component to avoid SSG issues
+let NextImageComponent = null;
+function getNextImage() {
+    if (NextImageComponent === null) {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        NextImageComponent = require('next/image')
+            .default;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    return NextImageComponent;
+}
+/**
+ * Convert CSS unit value to number if possible
+ */
+function toNumericSize(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'number')
+        return value;
+    // Try to parse numeric strings (e.g., "100" or "100px")
+    const parsed = parseInt(value, 10);
+    return isNaN(parsed) ? undefined : parsed;
+}
+/**
+ * Convert CSS unit value to string
+ */
+function cssUnit(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'number')
+        return `${value}px`;
+    return value;
+}
+/**
+ * Next.js Image adapter for optimized image delivery
+ *
+ * Leverages Next.js Image component features:
+ * - Automatic image optimization
+ * - Responsive image generation
+ * - Modern format support (WebP, AVIF)
+ * - Lazy loading with native browser support
+ * - Priority loading for LCP images
+ *
+ * @example
+ * ```tsx
+ * import { SurfaceRenderer } from '@pwfabric/runtime'
+ * import { NextImageAdapter } from '@pwfabric/runtime/adapters'
+ *
+ * function MyPage() {
+ *   return (
+ *     <SurfaceRenderer
+ *       surface={mySurface}
+ *       imageAdapter={NextImageAdapter}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export const NextImageAdapter = ({ src, alt, width, height, loading, objectFit, aspectRatio, borderRadius, className, style, placeholder, blurDataURL, blockId, }) => {
+    const numericWidth = toNumericSize(width);
+    const numericHeight = toNumericSize(height);
+    // Use fill mode if no explicit dimensions provided
+    const useFillMode = numericWidth === undefined && numericHeight === undefined;
+    const computedStyle = {
+        objectFit: objectFit ?? 'cover',
+        aspectRatio,
+        borderRadius: cssUnit(borderRadius),
+        ...(numericWidth !== undefined && numericHeight !== undefined
+            ? { width: `${numericWidth}px`, height: `${numericHeight}px`, maxWidth: '100%' }
+            : {}),
+        ...style,
+    };
+    // Wrapper style for fill mode
+    const wrapperStyle = useFillMode
+        ? {
+            position: 'relative',
+            width: cssUnit(width) ?? '100%',
+            height: cssUnit(height) ?? 'auto',
+            aspectRatio: aspectRatio ?? (numericHeight && numericWidth ? undefined : '16/9'),
+        }
+        : undefined;
+    const nextImageProps = {
+        src: src || '/placeholder.png',
+        alt: alt ?? '',
+        fill: useFillMode,
+        priority: loading === 'eager',
+        style: computedStyle,
+    };
+    // Add optional props only if they have values
+    if (blockId !== undefined)
+        nextImageProps.id = blockId;
+    if (!useFillMode && numericWidth !== undefined)
+        nextImageProps.width = numericWidth;
+    if (!useFillMode && numericHeight !== undefined)
+        nextImageProps.height = numericHeight;
+    if (placeholder !== undefined)
+        nextImageProps.placeholder = placeholder;
+    if (blurDataURL !== undefined)
+        nextImageProps.blurDataURL = blurDataURL;
+    if (className !== undefined)
+        nextImageProps.className = className;
+    const NextImage = getNextImage();
+    const imageElement = React.createElement(NextImage, nextImageProps);
+    // Wrap in container for fill mode
+    if (useFillMode) {
+        return (_jsx("div", { style: wrapperStyle, "data-block-type": "image", children: imageElement }));
+    }
+    return imageElement;
+};
+//# sourceMappingURL=next-image.js.map

package/dist/adapters/next-image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next-image.js","sourceRoot":"","sources":["../../src/adapters/next-image.tsx"],"names":[],"mappings":"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","sourcesContent":["/**\n * Next.js Image Adapter\n *\n * Renders images using Next.js Image component for automatic\n * optimization, responsive images, and modern image formats.\n *\n * NOTE: This adapter requires `next` as a peer dependency.\n * Only import this adapter in Next.js applications.\n *\n * @module @pwfabric/runtime/adapters/next-image\n */\n\n'use client'\n\nimport * as React from 'react'\nimport type { ImageAdapter, ImageAdapterProps } from './types.js'\n\n// Interface for Next.js Image component props\ninterface NextImageComponentProps {\n  src: string\n  alt: string\n  width?: number\n  height?: number\n  fill?: boolean\n  priority?: boolean\n  placeholder?: 'blur' | 'empty'\n  blurDataURL?: string\n  style?: React.CSSProperties\n  className?: string\n  id?: string\n}\n\n// Lazy load next/image component to avoid SSG issues\nlet NextImageComponent: React.ComponentType<NextImageComponentProps> | null = null\n\nfunction getNextImage(): React.ComponentType<NextImageComponentProps> {\n  if (NextImageComponent === null) {\n    // eslint-disable-next-line @typescript-eslint/no-require-imports\n    NextImageComponent = require('next/image')\n      .default as React.ComponentType<NextImageComponentProps>\n  }\n  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion\n  return NextImageComponent!\n}\n\n/**\n * Convert CSS unit value to number if possible\n */\nfunction toNumericSize(value: number | string | undefined): number | undefined {\n  if (value === undefined) return undefined\n  if (typeof value === 'number') return value\n  // Try to parse numeric strings (e.g., \"100\" or \"100px\")\n  const parsed = parseInt(value, 10)\n  return isNaN(parsed) ? undefined : parsed\n}\n\n/**\n * Convert CSS unit value to string\n */\nfunction cssUnit(value: number | string | undefined): string | undefined {\n  if (value === undefined) return undefined\n  if (typeof value === 'number') return `${value}px`\n  return value\n}\n\n/**\n * Next.js Image adapter for optimized image delivery\n *\n * Leverages Next.js Image component features:\n * - Automatic image optimization\n * - Responsive image generation\n * - Modern format support (WebP, AVIF)\n * - Lazy loading with native browser support\n * - Priority loading for LCP images\n *\n * @example\n * ```tsx\n * import { SurfaceRenderer } from '@pwfabric/runtime'\n * import { NextImageAdapter } from '@pwfabric/runtime/adapters'\n *\n * function MyPage() {\n *   return (\n *     <SurfaceRenderer\n *       surface={mySurface}\n *       imageAdapter={NextImageAdapter}\n *     />\n *   )\n * }\n * ```\n */\nexport const NextImageAdapter: ImageAdapter = ({\n  src,\n  alt,\n  width,\n  height,\n  loading,\n  objectFit,\n  aspectRatio,\n  borderRadius,\n  className,\n  style,\n  placeholder,\n  blurDataURL,\n  blockId,\n}: ImageAdapterProps): React.ReactElement => {\n  const numericWidth = toNumericSize(width)\n  const numericHeight = toNumericSize(height)\n\n  // Use fill mode if no explicit dimensions provided\n  const useFillMode = numericWidth === undefined && numericHeight === undefined\n\n  const computedStyle: React.CSSProperties = {\n    objectFit: objectFit ?? 'cover',\n    aspectRatio,\n    borderRadius: cssUnit(borderRadius),\n    ...(numericWidth !== undefined && numericHeight !== undefined\n      ? { width: `${numericWidth}px`, height: `${numericHeight}px`, maxWidth: '100%' }\n      : {}),\n    ...style,\n  }\n\n  // Wrapper style for fill mode\n  const wrapperStyle: React.CSSProperties | undefined = useFillMode\n    ? {\n        position: 'relative',\n        width: cssUnit(width) ?? '100%',\n        height: cssUnit(height) ?? 'auto',\n        aspectRatio: aspectRatio ?? (numericHeight && numericWidth ? undefined : '16/9'),\n      }\n    : undefined\n\n  // Build NextImage props\n  interface NextImagePropsType {\n    src: string\n    alt: string\n    width?: number\n    height?: number\n    fill?: boolean\n    priority?: boolean\n    placeholder?: 'blur' | 'empty'\n    blurDataURL?: string\n    style?: React.CSSProperties\n    className?: string\n    id?: string\n  }\n\n  const nextImageProps: NextImagePropsType = {\n    src: src || '/placeholder.png',\n    alt: alt ?? '',\n    fill: useFillMode,\n    priority: loading === 'eager',\n    style: computedStyle,\n  }\n\n  // Add optional props only if they have values\n  if (blockId !== undefined) nextImageProps.id = blockId\n  if (!useFillMode && numericWidth !== undefined) nextImageProps.width = numericWidth\n  if (!useFillMode && numericHeight !== undefined) nextImageProps.height = numericHeight\n  if (placeholder !== undefined) nextImageProps.placeholder = placeholder\n  if (blurDataURL !== undefined) nextImageProps.blurDataURL = blurDataURL\n  if (className !== undefined) nextImageProps.className = className\n\n  const NextImage = getNextImage()\n  const imageElement = React.createElement(NextImage, nextImageProps)\n\n  // Wrap in container for fill mode\n  if (useFillMode) {\n    return (\n      <div style={wrapperStyle} data-block-type=\"image\">\n        {imageElement}\n      </div>\n    )\n  }\n\n  return imageElement\n}\n"]}