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

package/dist/a11y/focus.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"focus.d.ts","sourceRoot":"","sources":["../../src/a11y/focus.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,qCAAqC;AACrC,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,SAAS,EAAE,WAAW,GAAG,IAAI,CAAA;IAC7B,6DAA6D;IAC7D,YAAY,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;IACnC,6FAA6F;IAC7F,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,kEAAkE;IAClE,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B;AA4BD;;;;;;;;;GASG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAgC;;IASnE;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IA8BvC;;;OAGG;IACH,UAAU,IAAI,IAAI;IAelB;;;;OAIG;IACH,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACH,OAAO,IAAI,IAAI;IAQf;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAU3B;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAU5B;;OAEG;IACH,OAAO,CAAC,aAAa;CA0CtB;AAMD;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAAW;;IAMxB;;OAEG;IACH,IAAI,IAAI,IAAI;IASZ;;OAEG;IACH,OAAO,IAAI,IAAI;CAQhB;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG;IAChD,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,CAAA;CAChC,CAmBA;AAMD;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,gBAAgB,CAElD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CAEnD"}

package/dist/a11y/focus.js

@@ -0,0 +1,282 @@
+/**
+ * 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
+ */
+// ============================================================
+// CONSTANTS
+// ============================================================
+/**
+ * Selector for elements that can receive focus.
+ * Covers interactive HTML elements and elements with explicit tabindex.
+ */
+const FOCUSABLE_SELECTOR = [
+    'a[href]',
+    'area[href]',
+    'button:not([disabled])',
+    'input:not([disabled])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])',
+    '[contenteditable]',
+    'details > summary',
+    'audio[controls]',
+    'video[controls]',
+].join(', ');
+// ============================================================
+// FOCUS TRAP MANAGER
+// ============================================================
+/**
+ * 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 class FocusTrapManager {
+    active;
+    config;
+    previousFocus;
+    boundHandleKeyDown;
+    constructor() {
+        this.active = false;
+        this.config = null;
+        this.previousFocus = null;
+        this.boundHandleKeyDown = this.handleKeyDown.bind(this);
+    }
+    /**
+     * 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) {
+        if (typeof document === 'undefined')
+            return;
+        if (!config.container)
+            return;
+        if (this.active) {
+            this.deactivate();
+        }
+        this.config = {
+            ...config,
+            returnFocus: config.returnFocus ?? true,
+            escapeDeactivates: config.escapeDeactivates ?? true,
+        };
+        this.previousFocus = document.activeElement;
+        this.active = true;
+        document.addEventListener('keydown', this.boundHandleKeyDown);
+        // Determine and apply initial focus
+        const initialTarget = this.resolveInitialFocus();
+        if (initialTarget) {
+            initialTarget.focus();
+        }
+        else {
+            // Fall back to the first focusable element
+            const focusable = this.getFocusableElements();
+            if (focusable.length > 0) {
+                focusable[0]?.focus();
+            }
+        }
+    }
+    /**
+     * Deactivate the focus trap and optionally return focus to the
+     * previously focused element.
+     */
+    deactivate() {
+        if (typeof document === 'undefined')
+            return;
+        if (!this.active)
+            return;
+        this.active = false;
+        document.removeEventListener('keydown', this.boundHandleKeyDown);
+        if (this.config?.returnFocus && this.previousFocus instanceof HTMLElement) {
+            this.previousFocus.focus();
+        }
+        this.config = null;
+        this.previousFocus = null;
+    }
+    /**
+     * Check whether the focus trap is currently active.
+     *
+     * @returns `true` if the trap is active
+     */
+    isActive() {
+        return this.active;
+    }
+    /**
+     * Dispose of the focus trap, deactivating it and cleaning up resources.
+     */
+    dispose() {
+        this.deactivate();
+    }
+    // ============================================================
+    // PRIVATE METHODS
+    // ============================================================
+    /**
+     * Resolve the initial focus target from the config.
+     * Handles both HTMLElement references and CSS selector strings.
+     */
+    resolveInitialFocus() {
+        if (!this.config?.initialFocus || !this.config.container)
+            return null;
+        if (typeof this.config.initialFocus === 'string') {
+            return this.config.container.querySelector(this.config.initialFocus);
+        }
+        return this.config.initialFocus;
+    }
+    /**
+     * Get all focusable elements within the trap container, sorted in DOM order.
+     *
+     * @returns Array of focusable HTMLElements
+     */
+    getFocusableElements() {
+        if (!this.config?.container)
+            return [];
+        const elements = this.config.container.querySelectorAll(FOCUSABLE_SELECTOR);
+        return Array.from(elements).filter((el) => {
+            // Filter out elements that are not visible
+            return el.offsetParent !== null || el.offsetWidth > 0 || el.offsetHeight > 0;
+        });
+    }
+    /**
+     * Handle keydown events to trap Tab focus and optionally deactivate on Escape.
+     */
+    handleKeyDown(event) {
+        if (!this.active || !this.config)
+            return;
+        // Handle Escape
+        if (event.key === 'Escape' && this.config.escapeDeactivates) {
+            event.preventDefault();
+            this.deactivate();
+            return;
+        }
+        // Handle Tab / Shift+Tab
+        if (event.key !== 'Tab')
+            return;
+        const focusable = this.getFocusableElements();
+        if (focusable.length === 0) {
+            event.preventDefault();
+            return;
+        }
+        const firstElement = focusable[0];
+        const lastElement = focusable[focusable.length - 1];
+        if (event.shiftKey) {
+            // Shift+Tab: wrap from first to last
+            if (document.activeElement === firstElement ||
+                !this.config.container?.contains(document.activeElement)) {
+                event.preventDefault();
+                lastElement?.focus();
+            }
+        }
+        else {
+            // Tab: wrap from last to first
+            if (document.activeElement === lastElement ||
+                !this.config.container?.contains(document.activeElement)) {
+                event.preventDefault();
+                firstElement?.focus();
+            }
+        }
+    }
+}
+// ============================================================
+// FOCUS RESTORER
+// ============================================================
+/**
+ * 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 class FocusRestorer {
+    stack;
+    constructor() {
+        this.stack = [];
+    }
+    /**
+     * Save the currently focused element onto the stack.
+     */
+    save() {
+        if (typeof document === 'undefined')
+            return;
+        const activeElement = document.activeElement;
+        if (activeElement) {
+            this.stack.push(activeElement);
+        }
+    }
+    /**
+     * Pop the most recently saved element from the stack and restore focus to it.
+     */
+    restore() {
+        if (typeof document === 'undefined')
+            return;
+        const element = this.stack.pop();
+        if (element instanceof HTMLElement) {
+            element.focus();
+        }
+    }
+}
+// ============================================================
+// SKIP LINK HELPER
+// ============================================================
+/**
+ * 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 function createSkipLink(targetId) {
+    return {
+        href: `#${targetId}`,
+        label: 'Skip to content',
+        handleClick: (e) => {
+            if (typeof document === 'undefined')
+                return;
+            e.preventDefault();
+            const target = document.getElementById(targetId);
+            if (target) {
+                // Ensure the element can receive focus
+                if (!target.hasAttribute('tabindex')) {
+                    target.setAttribute('tabindex', '-1');
+                }
+                target.focus();
+                target.scrollIntoView({ behavior: 'smooth' });
+            }
+        },
+    };
+}
+// ============================================================
+// FACTORY FUNCTIONS
+// ============================================================
+/**
+ * Create a new FocusTrapManager instance.
+ *
+ * @returns A new FocusTrapManager
+ */
+export function createFocusTrap() {
+    return new FocusTrapManager();
+}
+/**
+ * Create a new FocusRestorer instance.
+ *
+ * @returns A new FocusRestorer
+ */
+export function createFocusRestorer() {
+    return new FocusRestorer();
+}
+//# sourceMappingURL=focus.js.map

package/dist/a11y/focus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus.js","sourceRoot":"","sources":["../../src/a11y/focus.ts"],"names":[],"mappings":"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"}

package/dist/a11y/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Accessibility (a11y) Module
+ *
+ * Provides runtime accessibility utilities for the PWFabric platform:
+ * - Screen reader announcements via ARIA live regions
+ * - Focus trapping, restoration, and skip links
+ * - Keyboard navigation for composite widgets
+ * - WCAG 2.0 color contrast checking
+ *
+ * All DOM operations are SSR-safe (no-op when `document` is unavailable).
+ *
+ * @module @pwfabric/runtime/a11y
+ */
+export type { AnnouncementLevel, LiveRegionConfig } from './announcer.js';
+export { LiveRegionAnnouncer, createAnnouncer } from './announcer.js';
+export type { FocusTrapConfig } from './focus.js';
+export { FocusTrapManager, FocusRestorer, createSkipLink, createFocusTrap, createFocusRestorer, } from './focus.js';
+export type { ArrowDirection, KeyboardNavConfig } from './keyboard.js';
+export { KeyboardNavigationManager, RovingTabIndex, createKeyboardNav, createRovingTabIndex, } from './keyboard.js';
+export type { ContrastResult } from './contrast.js';
+export { hexToRgb, relativeLuminance, contrastRatio, checkContrast, meetsWCAG } from './contrast.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/a11y/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACzE,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAGrE,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,eAAe,EACf,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAGnB,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACtE,OAAO,EACL,yBAAyB,EACzB,cAAc,EACd,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,eAAe,CAAA;AAGtB,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA"}

package/dist/a11y/index.js

@@ -0,0 +1,18 @@
+/**
+ * Accessibility (a11y) Module
+ *
+ * Provides runtime accessibility utilities for the PWFabric platform:
+ * - Screen reader announcements via ARIA live regions
+ * - Focus trapping, restoration, and skip links
+ * - Keyboard navigation for composite widgets
+ * - WCAG 2.0 color contrast checking
+ *
+ * All DOM operations are SSR-safe (no-op when `document` is unavailable).
+ *
+ * @module @pwfabric/runtime/a11y
+ */
+export { LiveRegionAnnouncer, createAnnouncer } from './announcer.js';
+export { FocusTrapManager, FocusRestorer, createSkipLink, createFocusTrap, createFocusRestorer, } from './focus.js';
+export { KeyboardNavigationManager, RovingTabIndex, createKeyboardNav, createRovingTabIndex, } from './keyboard.js';
+export { hexToRgb, relativeLuminance, contrastRatio, checkContrast, meetsWCAG } from './contrast.js';
+//# sourceMappingURL=index.js.map

package/dist/a11y/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/a11y/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAIrE,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,eAAe,EACf,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAInB,OAAO,EACL,yBAAyB,EACzB,cAAc,EACd,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,eAAe,CAAA;AAItB,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA"}

package/dist/a11y/keyboard.d.ts

@@ -0,0 +1,145 @@
+/**
+ * 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
+ */
+/** Direction(s) in which arrow key navigation operates */
+export type ArrowDirection = 'horizontal' | 'vertical' | 'both';
+/** Configuration for keyboard navigation */
+export interface KeyboardNavConfig {
+    /** Container element holding navigable items */
+    container: HTMLElement | null;
+    /** Direction of arrow key navigation */
+    direction: ArrowDirection;
+    /** Whether navigation wraps around at boundaries (default true) */
+    loop?: boolean;
+    /** CSS selector for navigable items (default '[role="option"], [role="tab"], button, a') */
+    selector?: string;
+}
+/**
+ * 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 declare class KeyboardNavigationManager {
+    private config;
+    private currentIndex;
+    private readonly boundHandleKeyDown;
+    constructor();
+    /**
+     * Activate keyboard navigation on the given container.
+     *
+     * @param config - Keyboard navigation configuration
+     */
+    activate(config: KeyboardNavConfig): void;
+    /**
+     * Deactivate keyboard navigation and remove event listeners.
+     */
+    deactivate(): void;
+    /**
+     * Move focus to the next item in the navigation order.
+     */
+    focusNext(): void;
+    /**
+     * Move focus to the previous item in the navigation order.
+     */
+    focusPrevious(): void;
+    /**
+     * Move focus to the first item.
+     */
+    focusFirst(): void;
+    /**
+     * Move focus to the last item.
+     */
+    focusLast(): void;
+    /**
+     * Get the current focused item index.
+     *
+     * @returns The zero-based index of the currently focused item
+     */
+    getCurrentIndex(): number;
+    /**
+     * Dispose of the keyboard navigation manager, removing all listeners.
+     */
+    dispose(): void;
+    /**
+     * Handle keydown events for arrow key navigation and Home/End support.
+     */
+    private handleKeyDown;
+    /**
+     * Query navigable items from the container, filtered to visible elements.
+     *
+     * @returns Array of focusable HTMLElements within the container
+     */
+    private getItems;
+}
+/**
+ * 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 declare class RovingTabIndex {
+    private container;
+    private selector;
+    /**
+     * @param selector - CSS selector for items managed by roving tabindex
+     */
+    constructor(selector?: string);
+    /**
+     * 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: HTMLElement): void;
+    /**
+     * Detach roving tabindex management, restoring all items to `tabindex="0"`.
+     */
+    detach(): void;
+    /**
+     * 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: HTMLElement): void;
+    /**
+     * Dispose of the roving tabindex manager.
+     */
+    dispose(): void;
+    /**
+     * Query managed items from the container.
+     */
+    private getItems;
+}
+/**
+ * Create a new KeyboardNavigationManager instance.
+ *
+ * @returns A new KeyboardNavigationManager
+ */
+export declare function createKeyboardNav(): KeyboardNavigationManager;
+/**
+ * Create a new RovingTabIndex instance.
+ *
+ * @param selector - CSS selector for managed items
+ * @returns A new RovingTabIndex
+ */
+export declare function createRovingTabIndex(selector?: string): RovingTabIndex;
+//# sourceMappingURL=keyboard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keyboard.d.ts","sourceRoot":"","sources":["../../src/a11y/keyboard.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,0DAA0D;AAC1D,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,CAAA;AAE/D,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,SAAS,EAAE,WAAW,GAAG,IAAI,CAAA;IAC7B,wCAAwC;IACxC,SAAS,EAAE,cAAc,CAAA;IACzB,mEAAmE;IACnE,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAYD;;;;;;;GAOG;AACH,qBAAa,yBAAyB;IACpC,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,YAAY,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAgC;;IAQnE;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAiBzC;;OAEG;IACH,UAAU,IAAI,IAAI;IAQlB;;OAEG;IACH,SAAS,IAAI,IAAI;IAmBjB;;OAEG;IACH,aAAa,IAAI,IAAI;IAmBrB;;OAEG;IACH,UAAU,IAAI,IAAI;IAQlB;;OAEG;IACH,SAAS,IAAI,IAAI;IAQjB;;;;OAIG;IACH,eAAe,IAAI,MAAM;IAIzB;;OAEG;IACH,OAAO,IAAI,IAAI;IAQf;;OAEG;IACH,OAAO,CAAC,aAAa;IAmDrB;;;;OAIG;IACH,OAAO,CAAC,QAAQ;CAajB;AAMD;;;;;;;;;;GAUG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,SAAS,CAAoB;IACrC,OAAO,CAAC,QAAQ,CAAQ;IAExB;;OAEG;gBACS,QAAQ,CAAC,EAAE,MAAM;IAK7B;;;;;;;OAOG;IACH,MAAM,CAAC,SAAS,EAAE,WAAW,GAAG,IAAI;IAWpC;;OAEG;IACH,MAAM,IAAI,IAAI;IAWd;;;;;;;OAOG;IACH,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IASrC;;OAEG;IACH,OAAO,IAAI,IAAI;IAQf;;OAEG;IACH,OAAO,CAAC,QAAQ;CAIjB;AAMD;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,yBAAyB,CAE7D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,cAAc,CAEtE"}