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

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,14 @@
-# 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 renderer. Turns a surface definition into a live page: blocks, bindings, capabilities, appearance.
+
+```bash
+pnpm add @pwfabric/runtime
+```
+
+Part of [PWFabric](https://github.com/pwfabric/pwfabric). Documentation, the
+other packages and the licensing model live in that repository.
+
+## Licence
+
+Business Source License 1.1 — see `LICENSE`. Use it, change it, host what you build with it; do not offer PWFabric itself as a service. Becomes Apache-2.0 on the Change Date.

package/dist/__tests__/dom-test-setup.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared jsdom polyfill setup for runtime component (DOM) tests.
+ *
+ * jsdom does not implement `window.matchMedia` (it is a browser-only API).
+ * The runtime's `useViewport` hook (`render/responsive.ts`) registers
+ * `matchMedia` listeners inside a `useEffect`, so any component test that
+ * mounts `SurfaceRenderer` needs a minimal `matchMedia` stub.
+ *
+ * Import this module for its side effect at the top of a `@vitest-environment
+ * jsdom` test file:
+ *
+ *   import '../../__tests__/dom-test-setup.js'
+ *
+ * The stub returns a non-matching `MediaQueryList` with no-op listener
+ * registration — enough for `useViewport` to fall back to its
+ * width-based detection without throwing.
+ *
+ * @module @pwfabric/runtime/__tests__/dom-test-setup
+ */
+export {};
+//# sourceMappingURL=dom-test-setup.d.ts.map

package/dist/__tests__/dom-test-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-test-setup.d.ts","sourceRoot":"","sources":["../../src/__tests__/dom-test-setup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/__tests__/dom-test-setup.js

@@ -0,0 +1,36 @@
+/**
+ * Shared jsdom polyfill setup for runtime component (DOM) tests.
+ *
+ * jsdom does not implement `window.matchMedia` (it is a browser-only API).
+ * The runtime's `useViewport` hook (`render/responsive.ts`) registers
+ * `matchMedia` listeners inside a `useEffect`, so any component test that
+ * mounts `SurfaceRenderer` needs a minimal `matchMedia` stub.
+ *
+ * Import this module for its side effect at the top of a `@vitest-environment
+ * jsdom` test file:
+ *
+ *   import '../../__tests__/dom-test-setup.js'
+ *
+ * The stub returns a non-matching `MediaQueryList` with no-op listener
+ * registration — enough for `useViewport` to fall back to its
+ * width-based detection without throwing.
+ *
+ * @module @pwfabric/runtime/__tests__/dom-test-setup
+ */
+if (typeof window !== 'undefined' && typeof window.matchMedia !== 'function') {
+    window.matchMedia = ((query) => {
+        const list = {
+            matches: false,
+            media: query,
+            onchange: null,
+            addListener: () => { },
+            removeListener: () => { },
+            addEventListener: () => { },
+            removeEventListener: () => { },
+            dispatchEvent: () => false,
+        };
+        return list;
+    });
+}
+export {};
+//# sourceMappingURL=dom-test-setup.js.map

package/dist/__tests__/dom-test-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-test-setup.js","sourceRoot":"","sources":["../../src/__tests__/dom-test-setup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;IAC7E,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC,KAAa,EAAkB,EAAE;QACrD,MAAM,IAAI,GAAmB;YAC3B,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,KAAK;YACZ,QAAQ,EAAE,IAAI;YACd,WAAW,EAAE,GAAG,EAAE,GAAE,CAAC;YACrB,cAAc,EAAE,GAAG,EAAE,GAAE,CAAC;YACxB,gBAAgB,EAAE,GAAG,EAAE,GAAE,CAAC;YAC1B,mBAAmB,EAAE,GAAG,EAAE,GAAE,CAAC;YAC7B,aAAa,EAAE,GAAG,EAAE,CAAC,KAAK;SAC3B,CAAA;QACD,OAAO,IAAI,CAAA;IACb,CAAC,CAA6B,CAAA;AAChC,CAAC"}

package/dist/a11y/announcer.d.ts

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

package/dist/a11y/announcer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"announcer.d.ts","sourceRoot":"","sources":["../../src/a11y/announcer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,0DAA0D;AAC1D,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,WAAW,CAAA;AAEtD,sCAAsC;AACtC,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,KAAK,EAAE,iBAAiB,CAAA;IACxB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAuBD;;;;;;;;GAQG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,OAAO,CAAyC;;IAMxD;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAgB5C;;;;;;;;;OASG;IACH,QAAQ,CACN,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,iBAA4B,EACnC,OAAO,GAAE,MAAwB,GAChC,IAAI;IA+BP;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,EAAE,iBAAiB,GAAG,IAAI;IAqBtC;;;OAGG;IACH,OAAO,IAAI,IAAI;CAWhB;AAMD;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,mBAAmB,CAErD"}

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

package/dist/a11y/contrast.d.ts

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

package/dist/a11y/contrast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contrast.d.ts","sourceRoot":"","sources":["../../src/a11y/contrast.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,sCAAsC;AACtC,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAA;IACb,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAA;IAChB,8CAA8C;IAC9C,QAAQ,EAAE,OAAO,CAAA;IACjB,4CAA4C;IAC5C,YAAY,EAAE,OAAO,CAAA;IACrB,+CAA+C;IAC/C,aAAa,EAAE,OAAO,CAAA;CACvB;AAwBD,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAEjE,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAA;AAMtC;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAapE;AAMD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,CAUpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACvB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,IAAI,GAAG,KAAK,EACnB,KAAK,UAAQ,GACZ,OAAO,CAST"}

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