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

package/LICENSE

@@ -0,0 +1,90 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             PhiMajor Solutions
+Licensed Work:        @pwfabric/runtime 1.0.0
+                      The Licensed Work is (c) 2026 PhiMajor Solutions.
+Additional Use Grant: You may make production use of the Licensed Work,
+                      including building applications with it and hosting
+                      those applications for yourself or for your own
+                      customers, provided you do not offer the Licensed Work
+                      to third parties as a hosted or managed service where
+                      the service gives them substantially the functionality
+                      of the Licensed Work.
+Change Date:          2030-08-21
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact licensing@phimajor.com.
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License
+   can be included in a program with software provided under GPL Version 2.0
+   or a later version. Licensor may specify additional Change Licenses
+   without limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @pwfabric/runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The engine that renders a surface: the React surface and block renderers, data binding,
+forms, entities, connectors, routing, SEO, state and the capability kernel. It
+re-exports `@pwfabric/contracts`.
+
+## Install
+
+```bash
+pnpm add @pwfabric/runtime@rc zod@3 react react-dom
+```
+
+ESM only: import it from an ES module (`"type": "module"` or `.mjs`). Node 22+. Peers: `react` and `react-dom` 18 or 19; `next` 14–16 only if you use the
+Next.js image adapter.
+
+## Main exports
+
+| Export | What it is |
+|--------|------------|
+| everything from `@pwfabric/contracts` | Re-exported |
+| `BlockSurfaceRenderer`, `DataBoundSurfaceRenderer`, `BlockRenderer`, `BlockErrorBoundary` | Render a surface and its blocks |
+| `createFabric`, `FabricKernel`, `createRegistry`, `createEventBus` | The capability kernel |
+| `useSurfaceEvents`, `useSurfaceId`, `useSurfaceConnections`, `useEntitlements` | Hooks for block components |
+| binding, forms, entity, connector, routing, SEO, state and cache APIs | Re-exported from their modules |
+| `DefaultImageAdapter`, `NextImageAdapter` | Image adapters |
+
+## Entry points
+
+| Import | Contents |
+|--------|----------|
+| `@pwfabric/runtime` | Everything above |
+| `@pwfabric/runtime/adapters` | Image adapters (`DefaultImageAdapter`, `NextImageAdapter`) |
+| `@pwfabric/runtime/capability` | The platform capability catalogue and lookups |
+| `@pwfabric/runtime/blocks` | Block registry, component types, composition rules |
+| `@pwfabric/runtime/auth` | Auth providers (`createAuthProvider`, `ApiKeyAuthProvider`, `MsalAuthProvider`) |
+| `@pwfabric/runtime/data` | `DataService`, `createDataService` and the data capability provider |
+| `@pwfabric/runtime/blocks/*` | One module of `blocks/`, e.g. `@pwfabric/runtime/blocks/hooks` |
+| `@pwfabric/runtime/render/*` | One module of `render/`, e.g. `@pwfabric/runtime/render/renderer` |
+
+## Licence
+
+Business Source License 1.1 — see `LICENSE`. Use it, change it, and host what you build with it, for yourself or your own customers; do not offer PWFabric itself as a service. Each version becomes Apache-2.0 on the Change Date in `LICENSE`. See [licensing](https://pwfabric.com/licence).
+
+Part of [PWFabric](https://pwfabric.com) — the engine that renders an app. Source: [github.com/pwfabric/pwfabric](https://github.com/pwfabric/pwfabric).

package/dist/a11y/announcer.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Screen Reader Live Region Announcer
+ *
+ * Manages ARIA live regions for dynamic screen reader announcements.
+ * Works in both browser and SSR environments (SSR is a safe no-op).
+ *
+ * @module @pwfabric/runtime/a11y/announcer
+ */
+/** Politeness level for ARIA live region announcements */
+export type AnnouncementLevel = 'polite' | 'assertive';
+/** Configuration for a live region */
+export interface LiveRegionConfig {
+    /** Politeness level of the announcement */
+    level: AnnouncementLevel;
+    /** Milliseconds before the announcement is cleared (default 5000) */
+    timeout?: number;
+}
+/**
+ * Manages ARIA live regions for screen reader announcements.
+ *
+ * Creates visually hidden DOM elements with `aria-live` attributes
+ * that screen readers monitor for content changes. Supports both
+ * `polite` (waits for idle) and `assertive` (interrupts) modes.
+ *
+ * In SSR environments, all operations are safe no-ops.
+ */
+export declare class LiveRegionAnnouncer {
+    private regions;
+    constructor();
+    /**
+     * Create a live region DOM element for the given politeness level.
+     * In SSR environments this is a no-op.
+     *
+     * @param level - The ARIA live politeness level
+     */
+    createRegion(level: AnnouncementLevel): void;
+    /**
+     * Announce a message to screen readers via the specified live region.
+     *
+     * If the region has not been created yet, it will be created automatically.
+     * The message is cleared after the configured timeout (default 5000ms).
+     *
+     * @param message - The text to announce
+     * @param level - The politeness level (default 'polite')
+     * @param timeout - Milliseconds before clearing (default 5000)
+     */
+    announce(message: string, level?: AnnouncementLevel, timeout?: number): void;
+    /**
+     * Clear the announced message for a specific level or all levels.
+     *
+     * @param level - The level to clear, or undefined to clear all
+     */
+    clear(level?: AnnouncementLevel): void;
+    /**
+     * Remove all live region DOM elements and clear timers.
+     * Call this when the announcer is no longer needed.
+     */
+    dispose(): void;
+}
+/**
+ * Create a new LiveRegionAnnouncer instance.
+ *
+ * @returns A new LiveRegionAnnouncer
+ */
+export declare function createAnnouncer(): LiveRegionAnnouncer;

package/dist/a11y/announcer.js

@@ -0,0 +1,140 @@
+/**
+ * Screen Reader Live Region Announcer
+ *
+ * Manages ARIA live regions for dynamic screen reader announcements.
+ * Works in both browser and SSR environments (SSR is a safe no-op).
+ *
+ * @module @pwfabric/runtime/a11y/announcer
+ */
+// ============================================================
+// CONSTANTS
+// ============================================================
+const DEFAULT_TIMEOUT = 5000;
+const LIVE_REGION_STYLES = 'position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;';
+// ============================================================
+// LIVE REGION ANNOUNCER
+// ============================================================
+/**
+ * Manages ARIA live regions for screen reader announcements.
+ *
+ * Creates visually hidden DOM elements with `aria-live` attributes
+ * that screen readers monitor for content changes. Supports both
+ * `polite` (waits for idle) and `assertive` (interrupts) modes.
+ *
+ * In SSR environments, all operations are safe no-ops.
+ */
+export class LiveRegionAnnouncer {
+    regions;
+    constructor() {
+        this.regions = new Map();
+    }
+    /**
+     * Create a live region DOM element for the given politeness level.
+     * In SSR environments this is a no-op.
+     *
+     * @param level - The ARIA live politeness level
+     */
+    createRegion(level) {
+        if (typeof document === 'undefined')
+            return;
+        if (this.regions.has(level))
+            return;
+        const element = document.createElement('div');
+        element.setAttribute('aria-live', level);
+        element.setAttribute('aria-atomic', 'true');
+        element.setAttribute('role', 'status');
+        element.setAttribute('style', LIVE_REGION_STYLES);
+        element.setAttribute('data-pw-a11y-announcer', level);
+        document.body.appendChild(element);
+        this.regions.set(level, { element });
+    }
+    /**
+     * Announce a message to screen readers via the specified live region.
+     *
+     * If the region has not been created yet, it will be created automatically.
+     * The message is cleared after the configured timeout (default 5000ms).
+     *
+     * @param message - The text to announce
+     * @param level - The politeness level (default 'polite')
+     * @param timeout - Milliseconds before clearing (default 5000)
+     */
+    announce(message, level = 'polite', timeout = DEFAULT_TIMEOUT) {
+        if (typeof document === 'undefined')
+            return;
+        if (!this.regions.has(level)) {
+            this.createRegion(level);
+        }
+        const region = this.regions.get(level);
+        if (!region?.element)
+            return;
+        // Clear any pending timer
+        if (region.timer !== undefined) {
+            clearTimeout(region.timer);
+        }
+        // Clear and re-set to force screen reader re-announcement
+        region.element.textContent = '';
+        // Use a microtask to ensure the empty state is processed before the new content
+        requestAnimationFrame(() => {
+            if (region.element) {
+                region.element.textContent = message;
+            }
+        });
+        // Auto-clear after timeout
+        region.timer = setTimeout(() => {
+            this.clear(level);
+        }, timeout);
+    }
+    /**
+     * Clear the announced message for a specific level or all levels.
+     *
+     * @param level - The level to clear, or undefined to clear all
+     */
+    clear(level) {
+        if (typeof document === 'undefined')
+            return;
+        if (level !== undefined) {
+            const region = this.regions.get(level);
+            if (region) {
+                if (region.timer !== undefined) {
+                    clearTimeout(region.timer);
+                    region.timer = undefined;
+                }
+                if (region.element) {
+                    region.element.textContent = '';
+                }
+            }
+        }
+        else {
+            for (const regionLevel of this.regions.keys()) {
+                this.clear(regionLevel);
+            }
+        }
+    }
+    /**
+     * Remove all live region DOM elements and clear timers.
+     * Call this when the announcer is no longer needed.
+     */
+    dispose() {
+        for (const [, region] of this.regions) {
+            if (region.timer !== undefined) {
+                clearTimeout(region.timer);
+            }
+            if (region.element && typeof document !== 'undefined') {
+                region.element.remove();
+            }
+        }
+        this.regions.clear();
+    }
+}
+// ============================================================
+// FACTORY FUNCTION
+// ============================================================
+/**
+ * Create a new LiveRegionAnnouncer instance.
+ *
+ * @returns A new LiveRegionAnnouncer
+ */
+export function createAnnouncer() {
+    return new LiveRegionAnnouncer();
+}
+//# sourceMappingURL=announcer.js.map

package/dist/a11y/announcer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"announcer.js","sourceRoot":"","sources":["../../src/a11y/announcer.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Screen Reader Live Region Announcer\n *\n * Manages ARIA live regions for dynamic screen reader announcements.\n * Works in both browser and SSR environments (SSR is a safe no-op).\n *\n * @module @pwfabric/runtime/a11y/announcer\n */\n\n// ============================================================\n// TYPES\n// ============================================================\n\n/** Politeness level for ARIA live region announcements */\nexport type AnnouncementLevel = 'polite' | 'assertive'\n\n/** Configuration for a live region */\nexport interface LiveRegionConfig {\n  /** Politeness level of the announcement */\n  level: AnnouncementLevel\n  /** Milliseconds before the announcement is cleared (default 5000) */\n  timeout?: number\n}\n\n// ============================================================\n// CONSTANTS\n// ============================================================\n\nconst DEFAULT_TIMEOUT = 5000\nconst LIVE_REGION_STYLES =\n  'position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;'\n\n// ============================================================\n// LIVE REGION STATE\n// ============================================================\n\ninterface LiveRegionState {\n  element: HTMLElement | null\n  timer?: ReturnType<typeof setTimeout> | undefined\n}\n\n// ============================================================\n// LIVE REGION ANNOUNCER\n// ============================================================\n\n/**\n * Manages ARIA live regions for screen reader announcements.\n *\n * Creates visually hidden DOM elements with `aria-live` attributes\n * that screen readers monitor for content changes. Supports both\n * `polite` (waits for idle) and `assertive` (interrupts) modes.\n *\n * In SSR environments, all operations are safe no-ops.\n */\nexport class LiveRegionAnnouncer {\n  private regions: Map<AnnouncementLevel, LiveRegionState>\n\n  constructor() {\n    this.regions = new Map()\n  }\n\n  /**\n   * Create a live region DOM element for the given politeness level.\n   * In SSR environments this is a no-op.\n   *\n   * @param level - The ARIA live politeness level\n   */\n  createRegion(level: AnnouncementLevel): void {\n    if (typeof document === 'undefined') return\n    if (this.regions.has(level)) return\n\n    const element = document.createElement('div')\n    element.setAttribute('aria-live', level)\n    element.setAttribute('aria-atomic', 'true')\n    element.setAttribute('role', 'status')\n    element.setAttribute('style', LIVE_REGION_STYLES)\n    element.setAttribute('data-pw-a11y-announcer', level)\n\n    document.body.appendChild(element)\n\n    this.regions.set(level, { element })\n  }\n\n  /**\n   * Announce a message to screen readers via the specified live region.\n   *\n   * If the region has not been created yet, it will be created automatically.\n   * The message is cleared after the configured timeout (default 5000ms).\n   *\n   * @param message - The text to announce\n   * @param level - The politeness level (default 'polite')\n   * @param timeout - Milliseconds before clearing (default 5000)\n   */\n  announce(\n    message: string,\n    level: AnnouncementLevel = 'polite',\n    timeout: number = DEFAULT_TIMEOUT\n  ): void {\n    if (typeof document === 'undefined') return\n\n    if (!this.regions.has(level)) {\n      this.createRegion(level)\n    }\n\n    const region = this.regions.get(level)\n    if (!region?.element) return\n\n    // Clear any pending timer\n    if (region.timer !== undefined) {\n      clearTimeout(region.timer)\n    }\n\n    // Clear and re-set to force screen reader re-announcement\n    region.element.textContent = ''\n\n    // Use a microtask to ensure the empty state is processed before the new content\n    requestAnimationFrame(() => {\n      if (region.element) {\n        region.element.textContent = message\n      }\n    })\n\n    // Auto-clear after timeout\n    region.timer = setTimeout(() => {\n      this.clear(level)\n    }, timeout)\n  }\n\n  /**\n   * Clear the announced message for a specific level or all levels.\n   *\n   * @param level - The level to clear, or undefined to clear all\n   */\n  clear(level?: AnnouncementLevel): void {\n    if (typeof document === 'undefined') return\n\n    if (level !== undefined) {\n      const region = this.regions.get(level)\n      if (region) {\n        if (region.timer !== undefined) {\n          clearTimeout(region.timer)\n          region.timer = undefined\n        }\n        if (region.element) {\n          region.element.textContent = ''\n        }\n      }\n    } else {\n      for (const regionLevel of this.regions.keys()) {\n        this.clear(regionLevel)\n      }\n    }\n  }\n\n  /**\n   * Remove all live region DOM elements and clear timers.\n   * Call this when the announcer is no longer needed.\n   */\n  dispose(): void {\n    for (const [, region] of this.regions) {\n      if (region.timer !== undefined) {\n        clearTimeout(region.timer)\n      }\n      if (region.element && typeof document !== 'undefined') {\n        region.element.remove()\n      }\n    }\n    this.regions.clear()\n  }\n}\n\n// ============================================================\n// FACTORY FUNCTION\n// ============================================================\n\n/**\n * Create a new LiveRegionAnnouncer instance.\n *\n * @returns A new LiveRegionAnnouncer\n */\nexport function createAnnouncer(): LiveRegionAnnouncer {\n  return new LiveRegionAnnouncer()\n}\n"]}

package/dist/a11y/contrast.d.ts

@@ -0,0 +1,54 @@
+/**
+ * WCAG Color Contrast Checking
+ *
+ * Implements the WCAG 2.0 contrast ratio algorithm for verifying
+ * text and UI component color accessibility. Supports AA and AAA
+ * conformance levels for both normal and large text.
+ *
+ * @see https://www.w3.org/TR/WCAG20/#contrast-ratiodef
+ * @module @pwfabric/runtime/a11y/contrast
+ */
+/** Result of a WCAG contrast check */
+export interface ContrastResult {
+    /** The calculated contrast ratio (e.g. 4.5) */
+    ratio: number;
+    /** Meets WCAG AA for normal text (>= 4.5:1) */
+    meetsAA: boolean;
+    /** Meets WCAG AAA for normal text (>= 7:1) */
+    meetsAAA: boolean;
+    /** Meets WCAG AA for large text (>= 3:1) */
+    meetsAALarge: boolean;
+    /** Meets WCAG AAA for large text (>= 4.5:1) */
+    meetsAAALarge: boolean;
+}
+import { hexToRgb, relativeLuminance } from '@pwfabric/contracts';
+export { hexToRgb, relativeLuminance };
+/**
+ * Calculate the contrast ratio between two hex colors.
+ *
+ * The ratio is always >= 1, with 1 meaning identical colors
+ * and 21 being the maximum (black vs white).
+ *
+ * @param color1 - First hex color string
+ * @param color2 - Second hex color string
+ * @returns Contrast ratio, or 0 if either color is invalid
+ */
+export declare function contrastRatio(color1: string, color2: string): number;
+/**
+ * Check a foreground/background color pair against all WCAG contrast levels.
+ *
+ * @param foreground - Foreground (text) hex color
+ * @param background - Background hex color
+ * @returns ContrastResult with ratio and pass/fail for each WCAG level
+ */
+export declare function checkContrast(foreground: string, background: string): ContrastResult;
+/**
+ * Quick check whether a color pair meets a specific WCAG conformance level.
+ *
+ * @param foreground - Foreground (text) hex color
+ * @param background - Background hex color
+ * @param level - WCAG conformance level ('AA' or 'AAA')
+ * @param large - Whether the text is "large" (>= 18pt or >= 14pt bold) (default false)
+ * @returns `true` if the contrast ratio meets the specified level
+ */
+export declare function meetsWCAG(foreground: string, background: string, level: 'AA' | 'AAA', large?: boolean): boolean;

package/dist/a11y/contrast.js

@@ -0,0 +1,93 @@
+/**
+ * WCAG Color Contrast Checking
+ *
+ * Implements the WCAG 2.0 contrast ratio algorithm for verifying
+ * text and UI component color accessibility. Supports AA and AAA
+ * conformance levels for both normal and large text.
+ *
+ * @see https://www.w3.org/TR/WCAG20/#contrast-ratiodef
+ * @module @pwfabric/runtime/a11y/contrast
+ */
+// ============================================================
+// CONSTANTS
+// ============================================================
+/** WCAG 2.0 contrast ratio thresholds */
+const THRESHOLDS = {
+    AA_NORMAL: 4.5,
+    AAA_NORMAL: 7,
+    AA_LARGE: 3,
+    AAA_LARGE: 4.5,
+};
+// ============================================================
+// COLOR PRIMITIVES
+// ============================================================
+// `hexToRgb` / `relativeLuminance` MOVED to
+// `@pwfabric/contracts` (`fabric/appearance-cascade`) in the
+// the appearance cascade derives on-card ink from luminance
+// and the dark variant from HSL, and it now lives in `contracts` so runtime,
+// the exporter and the composer share ONE implementation. Re-exported here so the a11y
+// module keeps its full public surface and existing imports keep working.
+import { hexToRgb, relativeLuminance } from '@pwfabric/contracts';
+export { hexToRgb, relativeLuminance };
+// ============================================================
+// CONTRAST RATIO
+// ============================================================
+/**
+ * Calculate the contrast ratio between two hex colors.
+ *
+ * The ratio is always >= 1, with 1 meaning identical colors
+ * and 21 being the maximum (black vs white).
+ *
+ * @param color1 - First hex color string
+ * @param color2 - Second hex color string
+ * @returns Contrast ratio, or 0 if either color is invalid
+ */
+export function contrastRatio(color1, color2) {
+    const rgb1 = hexToRgb(color1);
+    const rgb2 = hexToRgb(color2);
+    if (!rgb1 || !rgb2)
+        return 0;
+    const lum1 = relativeLuminance(rgb1.r, rgb1.g, rgb1.b);
+    const lum2 = relativeLuminance(rgb2.r, rgb2.g, rgb2.b);
+    const lighter = Math.max(lum1, lum2);
+    const darker = Math.min(lum1, lum2);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+// ============================================================
+// WCAG CHECKS
+// ============================================================
+/**
+ * Check a foreground/background color pair against all WCAG contrast levels.
+ *
+ * @param foreground - Foreground (text) hex color
+ * @param background - Background hex color
+ * @returns ContrastResult with ratio and pass/fail for each WCAG level
+ */
+export function checkContrast(foreground, background) {
+    const ratio = contrastRatio(foreground, background);
+    return {
+        ratio,
+        meetsAA: ratio >= THRESHOLDS.AA_NORMAL,
+        meetsAAA: ratio >= THRESHOLDS.AAA_NORMAL,
+        meetsAALarge: ratio >= THRESHOLDS.AA_LARGE,
+        meetsAAALarge: ratio >= THRESHOLDS.AAA_LARGE,
+    };
+}
+/**
+ * Quick check whether a color pair meets a specific WCAG conformance level.
+ *
+ * @param foreground - Foreground (text) hex color
+ * @param background - Background hex color
+ * @param level - WCAG conformance level ('AA' or 'AAA')
+ * @param large - Whether the text is "large" (>= 18pt or >= 14pt bold) (default false)
+ * @returns `true` if the contrast ratio meets the specified level
+ */
+export function meetsWCAG(foreground, background, level, large = false) {
+    const ratio = contrastRatio(foreground, background);
+    if (level === 'AA') {
+        return large ? ratio >= THRESHOLDS.AA_LARGE : ratio >= THRESHOLDS.AA_NORMAL;
+    }
+    // AAA
+    return large ? ratio >= THRESHOLDS.AAA_LARGE : ratio >= THRESHOLDS.AAA_NORMAL;
+}
+//# sourceMappingURL=contrast.js.map

package/dist/a11y/contrast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contrast.js","sourceRoot":"","sources":["../../src/a11y/contrast.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAoBH,+DAA+D;AAC/D,YAAY;AACZ,+DAA+D;AAE/D,yCAAyC;AACzC,MAAM,UAAU,GAAG;IACjB,SAAS,EAAE,GAAG;IACd,UAAU,EAAE,CAAC;IACb,QAAQ,EAAE,CAAC;IACX,SAAS,EAAE,GAAG;CACN,CAAA;AAEV,+DAA+D;AAC/D,mBAAmB;AACnB,+DAA+D;AAE/D,4CAA4C;AAC5C,6DAA6D;AAC7D,4DAA4D;AAC5D,6EAA6E;AAC7E,uFAAuF;AACvF,0EAA0E;AAC1E,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAEjE,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAA;AAEtC,+DAA+D;AAC/D,iBAAiB;AACjB,+DAA+D;AAE/D;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,MAAc;IAC1D,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAA;IAC7B,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAA;IAE7B,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAA;IAE5B,MAAM,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;IACtD,MAAM,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;IAEtD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IACpC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IAEnC,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;AAC3C,CAAC;AAED,+DAA+D;AAC/D,cAAc;AACd,+DAA+D;AAE/D;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,UAAkB,EAAE,UAAkB;IAClE,MAAM,KAAK,GAAG,aAAa,CAAC,UAAU,EAAE,UAAU,CAAC,CAAA;IAEnD,OAAO;QACL,KAAK;QACL,OAAO,EAAE,KAAK,IAAI,UAAU,CAAC,SAAS;QACtC,QAAQ,EAAE,KAAK,IAAI,UAAU,CAAC,UAAU;QACxC,YAAY,EAAE,KAAK,IAAI,UAAU,CAAC,QAAQ;QAC1C,aAAa,EAAE,KAAK,IAAI,UAAU,CAAC,SAAS;KAC7C,CAAA;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CACvB,UAAkB,EAClB,UAAkB,EAClB,KAAmB,EACnB,KAAK,GAAG,KAAK;IAEb,MAAM,KAAK,GAAG,aAAa,CAAC,UAAU,EAAE,UAAU,CAAC,CAAA;IAEnD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI,UAAU,CAAC,SAAS,CAAA;IAC7E,CAAC;IAED,MAAM;IACN,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,UAAU,CAAC,UAAU,CAAA;AAC/E,CAAC","sourcesContent":["/**\n * WCAG Color Contrast Checking\n *\n * Implements the WCAG 2.0 contrast ratio algorithm for verifying\n * text and UI component color accessibility. Supports AA and AAA\n * conformance levels for both normal and large text.\n *\n * @see https://www.w3.org/TR/WCAG20/#contrast-ratiodef\n * @module @pwfabric/runtime/a11y/contrast\n */\n\n// ============================================================\n// TYPES\n// ============================================================\n\n/** Result of a WCAG contrast check */\nexport interface ContrastResult {\n  /** The calculated contrast ratio (e.g. 4.5) */\n  ratio: number\n  /** Meets WCAG AA for normal text (>= 4.5:1) */\n  meetsAA: boolean\n  /** Meets WCAG AAA for normal text (>= 7:1) */\n  meetsAAA: boolean\n  /** Meets WCAG AA for large text (>= 3:1) */\n  meetsAALarge: boolean\n  /** Meets WCAG AAA for large text (>= 4.5:1) */\n  meetsAAALarge: boolean\n}\n\n// ============================================================\n// CONSTANTS\n// ============================================================\n\n/** WCAG 2.0 contrast ratio thresholds */\nconst THRESHOLDS = {\n  AA_NORMAL: 4.5,\n  AAA_NORMAL: 7,\n  AA_LARGE: 3,\n  AAA_LARGE: 4.5,\n} as const\n\n// ============================================================\n// COLOR PRIMITIVES\n// ============================================================\n\n// `hexToRgb` / `relativeLuminance` MOVED to\n// `@pwfabric/contracts` (`fabric/appearance-cascade`) in the\n// the appearance cascade derives on-card ink from luminance\n// and the dark variant from HSL, and it now lives in `contracts` so runtime,\n// the exporter and the composer share ONE implementation. Re-exported here so the a11y\n// module keeps its full public surface and existing imports keep working.\nimport { hexToRgb, relativeLuminance } from '@pwfabric/contracts'\n\nexport { hexToRgb, relativeLuminance }\n\n// ============================================================\n// CONTRAST RATIO\n// ============================================================\n\n/**\n * Calculate the contrast ratio between two hex colors.\n *\n * The ratio is always >= 1, with 1 meaning identical colors\n * and 21 being the maximum (black vs white).\n *\n * @param color1 - First hex color string\n * @param color2 - Second hex color string\n * @returns Contrast ratio, or 0 if either color is invalid\n */\nexport function contrastRatio(color1: string, color2: string): number {\n  const rgb1 = hexToRgb(color1)\n  const rgb2 = hexToRgb(color2)\n\n  if (!rgb1 || !rgb2) return 0\n\n  const lum1 = relativeLuminance(rgb1.r, rgb1.g, rgb1.b)\n  const lum2 = relativeLuminance(rgb2.r, rgb2.g, rgb2.b)\n\n  const lighter = Math.max(lum1, lum2)\n  const darker = Math.min(lum1, lum2)\n\n  return (lighter + 0.05) / (darker + 0.05)\n}\n\n// ============================================================\n// WCAG CHECKS\n// ============================================================\n\n/**\n * Check a foreground/background color pair against all WCAG contrast levels.\n *\n * @param foreground - Foreground (text) hex color\n * @param background - Background hex color\n * @returns ContrastResult with ratio and pass/fail for each WCAG level\n */\nexport function checkContrast(foreground: string, background: string): ContrastResult {\n  const ratio = contrastRatio(foreground, background)\n\n  return {\n    ratio,\n    meetsAA: ratio >= THRESHOLDS.AA_NORMAL,\n    meetsAAA: ratio >= THRESHOLDS.AAA_NORMAL,\n    meetsAALarge: ratio >= THRESHOLDS.AA_LARGE,\n    meetsAAALarge: ratio >= THRESHOLDS.AAA_LARGE,\n  }\n}\n\n/**\n * Quick check whether a color pair meets a specific WCAG conformance level.\n *\n * @param foreground - Foreground (text) hex color\n * @param background - Background hex color\n * @param level - WCAG conformance level ('AA' or 'AAA')\n * @param large - Whether the text is \"large\" (>= 18pt or >= 14pt bold) (default false)\n * @returns `true` if the contrast ratio meets the specified level\n */\nexport function meetsWCAG(\n  foreground: string,\n  background: string,\n  level: 'AA' | 'AAA',\n  large = false\n): boolean {\n  const ratio = contrastRatio(foreground, background)\n\n  if (level === 'AA') {\n    return large ? ratio >= THRESHOLDS.AA_LARGE : ratio >= THRESHOLDS.AA_NORMAL\n  }\n\n  // AAA\n  return large ? ratio >= THRESHOLDS.AAA_LARGE : ratio >= THRESHOLDS.AAA_NORMAL\n}\n"]}

package/dist/a11y/focus.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Focus Management Utilities
+ *
+ * Provides focus trapping, focus restoration, and skip-link helpers
+ * for accessible modal dialogs, drawers, and navigation patterns.
+ * All DOM operations are SSR-safe.
+ *
+ * @module @pwfabric/runtime/a11y/focus
+ */
+/** Configuration for a focus trap */
+export interface FocusTrapConfig {
+    /** The container element to trap focus within */
+    container: HTMLElement | null;
+    /** Initial element to focus, or a CSS selector to find it */
+    initialFocus?: HTMLElement | string;
+    /** Whether to return focus to the previously focused element on deactivate (default true) */
+    returnFocus?: boolean;
+    /** Whether pressing Escape deactivates the trap (default true) */
+    escapeDeactivates?: boolean;
+}
+/**
+ * Manages focus trapping within a container element.
+ *
+ * When activated, Tab and Shift+Tab keypresses are intercepted to
+ * keep focus cycling within the container's focusable elements.
+ * Optionally deactivates on Escape key press.
+ *
+ * Used for modal dialogs, slide-over panels, and other overlay patterns
+ * that require focus to remain within the component for accessibility.
+ */
+export declare class FocusTrapManager {
+    private active;
+    private config;
+    private previousFocus;
+    private readonly boundHandleKeyDown;
+    constructor();
+    /**
+     * Activate the focus trap with the given configuration.
+     *
+     * Saves the currently focused element, attaches a keydown listener,
+     * and moves focus to the initial focus target (if specified) or the
+     * first focusable element in the container.
+     *
+     * @param config - Focus trap configuration
+     */
+    activate(config: FocusTrapConfig): void;
+    /**
+     * Deactivate the focus trap and optionally return focus to the
+     * previously focused element.
+     */
+    deactivate(): void;
+    /**
+     * Check whether the focus trap is currently active.
+     *
+     * @returns `true` if the trap is active
+     */
+    isActive(): boolean;
+    /**
+     * Dispose of the focus trap, deactivating it and cleaning up resources.
+     */
+    dispose(): void;
+    /**
+     * Resolve the initial focus target from the config.
+     * Handles both HTMLElement references and CSS selector strings.
+     */
+    private resolveInitialFocus;
+    /**
+     * Get all focusable elements within the trap container, sorted in DOM order.
+     *
+     * @returns Array of focusable HTMLElements
+     */
+    private getFocusableElements;
+    /**
+     * Handle keydown events to trap Tab focus and optionally deactivate on Escape.
+     */
+    private handleKeyDown;
+}
+/**
+ * Manages a stack of focus positions for nested focus contexts.
+ *
+ * Useful when opening nested dialogs or panels where each level
+ * needs to save and restore the previous focus target.
+ */
+export declare class FocusRestorer {
+    private stack;
+    constructor();
+    /**
+     * Save the currently focused element onto the stack.
+     */
+    save(): void;
+    /**
+     * Pop the most recently saved element from the stack and restore focus to it.
+     */
+    restore(): void;
+}
+/**
+ * Create a skip-to-content link configuration.
+ *
+ * Returns the href, label, and click handler for a skip link that
+ * jumps focus to the element with the specified ID. The target element
+ * is given a `tabindex` of `-1` if it does not already have one so
+ * it can receive programmatic focus.
+ *
+ * @param targetId - The ID of the element to skip to
+ * @returns Skip link configuration object
+ */
+export declare function createSkipLink(targetId: string): {
+    href: string;
+    label: string;
+    handleClick: (e: Event) => void;
+};
+/**
+ * Create a new FocusTrapManager instance.
+ *
+ * @returns A new FocusTrapManager
+ */
+export declare function createFocusTrap(): FocusTrapManager;
+/**
+ * Create a new FocusRestorer instance.
+ *
+ * @returns A new FocusRestorer
+ */
+export declare function createFocusRestorer(): FocusRestorer;