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

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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"}

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

@@ -0,0 +1,26 @@
+/**
+ * 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;
+//# sourceMappingURL=default-image.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"default-image.d.ts","sourceRoot":"","sources":["../../src/adapters/default-image.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAqB,MAAM,YAAY,CAAA;AAWjE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,EAAE,YAiCjC,CAAA"}

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"}

package/dist/adapters/index.d.ts

@@ -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}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export type { ImageAdapter, ImageAdapterProps } from './types.js';
+export { DefaultImageAdapter } from './default-image.js';
+export { NextImageAdapter } from './next-image.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAGjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA"}

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"}

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

@@ -0,0 +1,39 @@
+/**
+ * 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;
+//# sourceMappingURL=next-image.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"next-image.d.ts","sourceRoot":"","sources":["../../src/adapters/next-image.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAqB,MAAM,YAAY,CAAA;AAkDjE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,gBAAgB,EAAE,YAqF9B,CAAA"}

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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"}