@fragments-sdk/ui 0.9.0 → 0.9.2

package/dist/utils/a11y.cjs

@@ -0,0 +1,233 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const jsxRuntime = require("react/jsx-runtime");
+const React = require("react");
+function _interopNamespaceDefault(e) {
+  const n = Object.create(null, { [Symbol.toStringTag]: { value: "Module" } });
+  if (e) {
+    for (const k in e) {
+      if (k !== "default") {
+        const d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: () => e[k]
+        });
+      }
+    }
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+const React__namespace = /* @__PURE__ */ _interopNamespaceDefault(React);
+let idCounter = 0;
+function useId(prefix) {
+  var _a;
+  const reactId = (_a = React__namespace.useId) == null ? void 0 : _a.call(React__namespace);
+  const [id] = React__namespace.useState(() => {
+    if (reactId) return reactId;
+    return `${prefix ? `${prefix}-` : "fui-"}${++idCounter}`;
+  });
+  return id;
+}
+function useAnnounce() {
+  const politeRef = React__namespace.useRef(null);
+  const assertiveRef = React__namespace.useRef(null);
+  React__namespace.useEffect(() => {
+    const polite = document.createElement("div");
+    polite.setAttribute("aria-live", "polite");
+    polite.setAttribute("aria-atomic", "true");
+    polite.setAttribute("role", "status");
+    Object.assign(polite.style, {
+      position: "absolute",
+      width: "1px",
+      height: "1px",
+      padding: "0",
+      margin: "-1px",
+      overflow: "hidden",
+      clip: "rect(0, 0, 0, 0)",
+      whiteSpace: "nowrap",
+      border: "0"
+    });
+    document.body.appendChild(polite);
+    politeRef.current = polite;
+    const assertive = document.createElement("div");
+    assertive.setAttribute("aria-live", "assertive");
+    assertive.setAttribute("aria-atomic", "true");
+    assertive.setAttribute("role", "alert");
+    Object.assign(assertive.style, {
+      position: "absolute",
+      width: "1px",
+      height: "1px",
+      padding: "0",
+      margin: "-1px",
+      overflow: "hidden",
+      clip: "rect(0, 0, 0, 0)",
+      whiteSpace: "nowrap",
+      border: "0"
+    });
+    document.body.appendChild(assertive);
+    assertiveRef.current = assertive;
+    return () => {
+      polite.remove();
+      assertive.remove();
+    };
+  }, []);
+  const announce = React__namespace.useCallback(
+    (message, priority = "polite") => {
+      const region = priority === "assertive" ? assertiveRef.current : politeRef.current;
+      if (region) {
+        region.textContent = "";
+        requestAnimationFrame(() => {
+          region.textContent = message;
+        });
+      }
+    },
+    []
+  );
+  return { announce };
+}
+function usePrefersReducedMotion() {
+  const [prefersReducedMotion, setPrefersReducedMotion] = React__namespace.useState(false);
+  React__namespace.useEffect(() => {
+    const mediaQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
+    const handleChange = (event) => {
+      setPrefersReducedMotion(event.matches);
+    };
+    mediaQuery.addEventListener("change", handleChange);
+    setPrefersReducedMotion(mediaQuery.matches);
+    return () => {
+      mediaQuery.removeEventListener("change", handleChange);
+    };
+  }, []);
+  return prefersReducedMotion;
+}
+function usePrefersContrast() {
+  const [prefersContrast, setPrefersContrast] = React__namespace.useState(false);
+  React__namespace.useEffect(() => {
+    const mediaQuery = window.matchMedia("(prefers-contrast: more)");
+    const handleChange = (event) => {
+      setPrefersContrast(event.matches);
+    };
+    mediaQuery.addEventListener("change", handleChange);
+    setPrefersContrast(mediaQuery.matches);
+    return () => {
+      mediaQuery.removeEventListener("change", handleChange);
+    };
+  }, []);
+  return prefersContrast;
+}
+function useFocusTrap(ref, active) {
+  const previousActiveElement = React__namespace.useRef(null);
+  React__namespace.useEffect(() => {
+    if (!active || !ref.current) return;
+    const container = ref.current;
+    previousActiveElement.current = document.activeElement;
+    const focusableElements = getFocusableElements(container);
+    if (focusableElements.length > 0) {
+      focusableElements[0].focus();
+    }
+    const handleKeyDown = (event) => {
+      if (event.key !== "Tab") return;
+      const focusable = getFocusableElements(container);
+      if (focusable.length === 0) return;
+      const firstFocusable = focusable[0];
+      const lastFocusable = focusable[focusable.length - 1];
+      if (event.shiftKey) {
+        if (document.activeElement === firstFocusable) {
+          event.preventDefault();
+          lastFocusable.focus();
+        }
+      } else {
+        if (document.activeElement === lastFocusable) {
+          event.preventDefault();
+          firstFocusable.focus();
+        }
+      }
+    };
+    container.addEventListener("keydown", handleKeyDown);
+    return () => {
+      container.removeEventListener("keydown", handleKeyDown);
+      if (previousActiveElement.current instanceof HTMLElement) {
+        previousActiveElement.current.focus();
+      }
+    };
+  }, [active, ref]);
+}
+function getFocusableElements(container) {
+  return container.querySelectorAll(
+    'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])'
+  );
+}
+function handleArrowNavigation(event, items, currentIndex, options = {}) {
+  const { orientation = "vertical", loop = true } = options;
+  const length = items.length;
+  if (length === 0) return void 0;
+  let newIndex;
+  switch (event.key) {
+    case "ArrowDown":
+      if (orientation === "horizontal") return void 0;
+      event.preventDefault();
+      newIndex = currentIndex + 1;
+      if (newIndex >= length) {
+        newIndex = loop ? 0 : length - 1;
+      }
+      break;
+    case "ArrowUp":
+      if (orientation === "horizontal") return void 0;
+      event.preventDefault();
+      newIndex = currentIndex - 1;
+      if (newIndex < 0) {
+        newIndex = loop ? length - 1 : 0;
+      }
+      break;
+    case "ArrowRight":
+      if (orientation === "vertical") return void 0;
+      event.preventDefault();
+      newIndex = currentIndex + 1;
+      if (newIndex >= length) {
+        newIndex = loop ? 0 : length - 1;
+      }
+      break;
+    case "ArrowLeft":
+      if (orientation === "vertical") return void 0;
+      event.preventDefault();
+      newIndex = currentIndex - 1;
+      if (newIndex < 0) {
+        newIndex = loop ? length - 1 : 0;
+      }
+      break;
+    case "Home":
+      event.preventDefault();
+      newIndex = 0;
+      break;
+    case "End":
+      event.preventDefault();
+      newIndex = length - 1;
+      break;
+    default:
+      return void 0;
+  }
+  return newIndex;
+}
+function VisuallyHidden({ children, focusable = false }) {
+  const style = focusable ? {} : {
+    position: "absolute",
+    width: "1px",
+    height: "1px",
+    padding: "0",
+    margin: "-1px",
+    overflow: "hidden",
+    clip: "rect(0, 0, 0, 0)",
+    whiteSpace: "nowrap",
+    border: "0"
+  };
+  return /* @__PURE__ */ jsxRuntime.jsx("span", { style, "data-visually-hidden": !focusable || void 0, children });
+}
+exports.VisuallyHidden = VisuallyHidden;
+exports.handleArrowNavigation = handleArrowNavigation;
+exports.useAnnounce = useAnnounce;
+exports.useFocusTrap = useFocusTrap;
+exports.useId = useId;
+exports.usePrefersContrast = usePrefersContrast;
+exports.usePrefersReducedMotion = usePrefersReducedMotion;
+//# sourceMappingURL=a11y.cjs.map

package/dist/utils/a11y.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"a11y.cjs","sources":["../../src/utils/a11y.tsx"],"sourcesContent":["'use client';\n\nimport * as React from 'react';\n\n// ============================================\n// Unique ID Generator\n// ============================================\n\nlet idCounter = 0;\n\n/**\n * Generates a unique ID for ARIA relationships (labelledby, describedby, etc.)\n * Falls back to React.useId if available (React 18+), otherwise uses a counter.\n *\n * @param prefix - Optional prefix for the ID\n * @returns A unique ID string\n *\n * @example\n * ```tsx\n * const id = useId('dialog-title');\n * // Returns: \"dialog-title-1\" or \":r0:\" (React 18)\n * ```\n */\nexport function useId(prefix?: string): string {\n  // Use React 18's useId if available\n  const reactId = React.useId?.();\n\n  const [id] = React.useState(() => {\n    if (reactId) return reactId;\n    return `${prefix ? `${prefix}-` : 'fui-'}${++idCounter}`;\n  });\n\n  return id;\n}\n\n// ============================================\n// Screen Reader Announcements\n// ============================================\n\n/**\n * Hook to announce messages to screen readers via a live region.\n * Creates an ARIA live region that persists for the component lifetime.\n *\n * @returns An object with an announce function\n *\n * @example\n * ```tsx\n * const { announce } = useAnnounce();\n *\n * // Polite announcement (waits for screen reader to finish)\n * announce('Item added to cart');\n *\n * // Assertive announcement (interrupts immediately)\n * announce('Error: Please fix the form', 'assertive');\n * ```\n */\nexport function useAnnounce(): {\n  announce: (message: string, priority?: 'polite' | 'assertive') => void;\n} {\n  const politeRef = React.useRef<HTMLDivElement | null>(null);\n  const assertiveRef = React.useRef<HTMLDivElement | null>(null);\n\n  React.useEffect(() => {\n    // Create live regions on mount\n    const polite = document.createElement('div');\n    polite.setAttribute('aria-live', 'polite');\n    polite.setAttribute('aria-atomic', 'true');\n    polite.setAttribute('role', 'status');\n    Object.assign(polite.style, {\n      position: 'absolute',\n      width: '1px',\n      height: '1px',\n      padding: '0',\n      margin: '-1px',\n      overflow: 'hidden',\n      clip: 'rect(0, 0, 0, 0)',\n      whiteSpace: 'nowrap',\n      border: '0',\n    });\n    document.body.appendChild(polite);\n    politeRef.current = polite;\n\n    const assertive = document.createElement('div');\n    assertive.setAttribute('aria-live', 'assertive');\n    assertive.setAttribute('aria-atomic', 'true');\n    assertive.setAttribute('role', 'alert');\n    Object.assign(assertive.style, {\n      position: 'absolute',\n      width: '1px',\n      height: '1px',\n      padding: '0',\n      margin: '-1px',\n      overflow: 'hidden',\n      clip: 'rect(0, 0, 0, 0)',\n      whiteSpace: 'nowrap',\n      border: '0',\n    });\n    document.body.appendChild(assertive);\n    assertiveRef.current = assertive;\n\n    // Cleanup on unmount\n    return () => {\n      polite.remove();\n      assertive.remove();\n    };\n  }, []);\n\n  const announce = React.useCallback(\n    (message: string, priority: 'polite' | 'assertive' = 'polite') => {\n      const region = priority === 'assertive' ? assertiveRef.current : politeRef.current;\n      if (region) {\n        // Clear and re-set to ensure announcement\n        region.textContent = '';\n        // Use requestAnimationFrame to ensure the clear is processed\n        requestAnimationFrame(() => {\n          region.textContent = message;\n        });\n      }\n    },\n    []\n  );\n\n  return { announce };\n}\n\n// ============================================\n// User Preference Detection\n// ============================================\n\n/**\n * Hook to detect if the user prefers reduced motion.\n * Respects the `prefers-reduced-motion` media query.\n *\n * @returns boolean - true if user prefers reduced motion\n *\n * @example\n * ```tsx\n * const prefersReducedMotion = usePrefersReducedMotion();\n *\n * <div style={{\n *   transition: prefersReducedMotion ? 'none' : 'transform 200ms'\n * }}>\n * ```\n */\nexport function usePrefersReducedMotion(): boolean {\n  const [prefersReducedMotion, setPrefersReducedMotion] = React.useState(false);\n\n  React.useEffect(() => {\n    const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');\n\n    const handleChange = (event: MediaQueryListEvent) => {\n      setPrefersReducedMotion(event.matches);\n    };\n\n    // Modern browsers\n    mediaQuery.addEventListener('change', handleChange);\n\n    // Set initial value\n    setPrefersReducedMotion(mediaQuery.matches);\n\n    return () => {\n      mediaQuery.removeEventListener('change', handleChange);\n    };\n  }, []);\n\n  return prefersReducedMotion;\n}\n\n/**\n * Hook to detect if the user prefers increased contrast.\n * Respects the `prefers-contrast: more` media query.\n *\n * @returns boolean - true if user prefers high contrast\n *\n * @example\n * ```tsx\n * const prefersContrast = usePrefersContrast();\n *\n * <div className={prefersContrast ? styles.highContrast : undefined}>\n * ```\n */\nexport function usePrefersContrast(): boolean {\n  const [prefersContrast, setPrefersContrast] = React.useState(false);\n\n  React.useEffect(() => {\n    const mediaQuery = window.matchMedia('(prefers-contrast: more)');\n\n    const handleChange = (event: MediaQueryListEvent) => {\n      setPrefersContrast(event.matches);\n    };\n\n    mediaQuery.addEventListener('change', handleChange);\n    setPrefersContrast(mediaQuery.matches);\n\n    return () => {\n      mediaQuery.removeEventListener('change', handleChange);\n    };\n  }, []);\n\n  return prefersContrast;\n}\n\n// ============================================\n// Focus Management\n// ============================================\n\n/**\n * Hook to trap focus within a container element.\n * Useful for modals, dialogs, and other overlays.\n *\n * @param ref - React ref to the container element\n * @param active - Whether focus trap is active\n *\n * @example\n * ```tsx\n * const dialogRef = useRef<HTMLDivElement>(null);\n * useFocusTrap(dialogRef, isOpen);\n *\n * return <div ref={dialogRef}>...</div>;\n * ```\n */\nexport function useFocusTrap(\n  ref: React.RefObject<HTMLElement | null>,\n  active: boolean\n): void {\n  const previousActiveElement = React.useRef<Element | null>(null);\n\n  React.useEffect(() => {\n    if (!active || !ref.current) return;\n\n    const container = ref.current;\n    previousActiveElement.current = document.activeElement;\n\n    // Focus the first focusable element\n    const focusableElements = getFocusableElements(container);\n    if (focusableElements.length > 0) {\n      (focusableElements[0] as HTMLElement).focus();\n    }\n\n    const handleKeyDown = (event: KeyboardEvent) => {\n      if (event.key !== 'Tab') return;\n\n      const focusable = getFocusableElements(container);\n      if (focusable.length === 0) return;\n\n      const firstFocusable = focusable[0] as HTMLElement;\n      const lastFocusable = focusable[focusable.length - 1] as HTMLElement;\n\n      if (event.shiftKey) {\n        // Shift + Tab: move focus backward\n        if (document.activeElement === firstFocusable) {\n          event.preventDefault();\n          lastFocusable.focus();\n        }\n      } else {\n        // Tab: move focus forward\n        if (document.activeElement === lastFocusable) {\n          event.preventDefault();\n          firstFocusable.focus();\n        }\n      }\n    };\n\n    container.addEventListener('keydown', handleKeyDown);\n\n    return () => {\n      container.removeEventListener('keydown', handleKeyDown);\n\n      // Restore focus when trap is deactivated\n      if (previousActiveElement.current instanceof HTMLElement) {\n        previousActiveElement.current.focus();\n      }\n    };\n  }, [active, ref]);\n}\n\n/**\n * Get all focusable elements within a container\n */\nfunction getFocusableElements(container: HTMLElement): NodeListOf<Element> {\n  return container.querySelectorAll(\n    'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex=\"-1\"])'\n  );\n}\n\n// ============================================\n// Keyboard Navigation Helpers\n// ============================================\n\n/**\n * Helper to handle keyboard navigation within a group of elements.\n * Supports arrow keys, Home, End, and optional type-ahead.\n *\n * @param event - Keyboard event\n * @param items - Array of focusable items\n * @param currentIndex - Current focused item index\n * @param options - Navigation options\n * @returns New index or undefined if no navigation occurred\n *\n * @example\n * ```tsx\n * const handleKeyDown = (event: KeyboardEvent) => {\n *   const newIndex = handleArrowNavigation(event, menuItems, currentIndex, {\n *     orientation: 'vertical',\n *     loop: true,\n *   });\n *   if (newIndex !== undefined) {\n *     setCurrentIndex(newIndex);\n *   }\n * };\n * ```\n */\nexport function handleArrowNavigation(\n  event: React.KeyboardEvent | KeyboardEvent,\n  items: readonly unknown[],\n  currentIndex: number,\n  options: {\n    orientation?: 'horizontal' | 'vertical' | 'both';\n    loop?: boolean;\n  } = {}\n): number | undefined {\n  const { orientation = 'vertical', loop = true } = options;\n  const length = items.length;\n\n  if (length === 0) return undefined;\n\n  let newIndex: number | undefined;\n\n  switch (event.key) {\n    case 'ArrowDown':\n      if (orientation === 'horizontal') return undefined;\n      event.preventDefault();\n      newIndex = currentIndex + 1;\n      if (newIndex >= length) {\n        newIndex = loop ? 0 : length - 1;\n      }\n      break;\n\n    case 'ArrowUp':\n      if (orientation === 'horizontal') return undefined;\n      event.preventDefault();\n      newIndex = currentIndex - 1;\n      if (newIndex < 0) {\n        newIndex = loop ? length - 1 : 0;\n      }\n      break;\n\n    case 'ArrowRight':\n      if (orientation === 'vertical') return undefined;\n      event.preventDefault();\n      newIndex = currentIndex + 1;\n      if (newIndex >= length) {\n        newIndex = loop ? 0 : length - 1;\n      }\n      break;\n\n    case 'ArrowLeft':\n      if (orientation === 'vertical') return undefined;\n      event.preventDefault();\n      newIndex = currentIndex - 1;\n      if (newIndex < 0) {\n        newIndex = loop ? length - 1 : 0;\n      }\n      break;\n\n    case 'Home':\n      event.preventDefault();\n      newIndex = 0;\n      break;\n\n    case 'End':\n      event.preventDefault();\n      newIndex = length - 1;\n      break;\n\n    default:\n      return undefined;\n  }\n\n  return newIndex;\n}\n\n// ============================================\n// Screen Reader Only Component\n// ============================================\n\nexport interface VisuallyHiddenProps {\n  children: React.ReactNode;\n  /** If true, becomes visible when focused (useful for skip links) */\n  focusable?: boolean;\n}\n\n/**\n * Visually hides content while keeping it accessible to screen readers.\n * Use for skip links, additional context, or off-screen labels.\n *\n * @example\n * ```tsx\n * // Hidden label for icon-only button\n * <button>\n *   <Icon name=\"search\" />\n *   <VisuallyHidden>Search</VisuallyHidden>\n * </button>\n *\n * // Skip link that shows on focus\n * <VisuallyHidden focusable>\n *   <a href=\"#main\">Skip to main content</a>\n * </VisuallyHidden>\n * ```\n */\nexport function VisuallyHidden({ children, focusable = false }: VisuallyHiddenProps): React.ReactElement {\n  const style: React.CSSProperties = focusable\n    ? {}\n    : {\n        position: 'absolute',\n        width: '1px',\n        height: '1px',\n        padding: '0',\n        margin: '-1px',\n        overflow: 'hidden',\n        clip: 'rect(0, 0, 0, 0)',\n        whiteSpace: 'nowrap',\n        border: '0',\n      };\n\n  return (\n    <span style={style} data-visually-hidden={!focusable || undefined}>\n      {children}\n    </span>\n  );\n}\n"],"names":["React"],"mappings":"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"}

package/dist/utils/a11y.d.ts

@@ -0,0 +1,133 @@
+import * as React from 'react';
+/**
+ * Generates a unique ID for ARIA relationships (labelledby, describedby, etc.)
+ * Falls back to React.useId if available (React 18+), otherwise uses a counter.
+ *
+ * @param prefix - Optional prefix for the ID
+ * @returns A unique ID string
+ *
+ * @example
+ * ```tsx
+ * const id = useId('dialog-title');
+ * // Returns: "dialog-title-1" or ":r0:" (React 18)
+ * ```
+ */
+export declare function useId(prefix?: string): string;
+/**
+ * Hook to announce messages to screen readers via a live region.
+ * Creates an ARIA live region that persists for the component lifetime.
+ *
+ * @returns An object with an announce function
+ *
+ * @example
+ * ```tsx
+ * const { announce } = useAnnounce();
+ *
+ * // Polite announcement (waits for screen reader to finish)
+ * announce('Item added to cart');
+ *
+ * // Assertive announcement (interrupts immediately)
+ * announce('Error: Please fix the form', 'assertive');
+ * ```
+ */
+export declare function useAnnounce(): {
+    announce: (message: string, priority?: 'polite' | 'assertive') => void;
+};
+/**
+ * Hook to detect if the user prefers reduced motion.
+ * Respects the `prefers-reduced-motion` media query.
+ *
+ * @returns boolean - true if user prefers reduced motion
+ *
+ * @example
+ * ```tsx
+ * const prefersReducedMotion = usePrefersReducedMotion();
+ *
+ * <div style={{
+ *   transition: prefersReducedMotion ? 'none' : 'transform 200ms'
+ * }}>
+ * ```
+ */
+export declare function usePrefersReducedMotion(): boolean;
+/**
+ * Hook to detect if the user prefers increased contrast.
+ * Respects the `prefers-contrast: more` media query.
+ *
+ * @returns boolean - true if user prefers high contrast
+ *
+ * @example
+ * ```tsx
+ * const prefersContrast = usePrefersContrast();
+ *
+ * <div className={prefersContrast ? styles.highContrast : undefined}>
+ * ```
+ */
+export declare function usePrefersContrast(): boolean;
+/**
+ * Hook to trap focus within a container element.
+ * Useful for modals, dialogs, and other overlays.
+ *
+ * @param ref - React ref to the container element
+ * @param active - Whether focus trap is active
+ *
+ * @example
+ * ```tsx
+ * const dialogRef = useRef<HTMLDivElement>(null);
+ * useFocusTrap(dialogRef, isOpen);
+ *
+ * return <div ref={dialogRef}>...</div>;
+ * ```
+ */
+export declare function useFocusTrap(ref: React.RefObject<HTMLElement | null>, active: boolean): void;
+/**
+ * Helper to handle keyboard navigation within a group of elements.
+ * Supports arrow keys, Home, End, and optional type-ahead.
+ *
+ * @param event - Keyboard event
+ * @param items - Array of focusable items
+ * @param currentIndex - Current focused item index
+ * @param options - Navigation options
+ * @returns New index or undefined if no navigation occurred
+ *
+ * @example
+ * ```tsx
+ * const handleKeyDown = (event: KeyboardEvent) => {
+ *   const newIndex = handleArrowNavigation(event, menuItems, currentIndex, {
+ *     orientation: 'vertical',
+ *     loop: true,
+ *   });
+ *   if (newIndex !== undefined) {
+ *     setCurrentIndex(newIndex);
+ *   }
+ * };
+ * ```
+ */
+export declare function handleArrowNavigation(event: React.KeyboardEvent | KeyboardEvent, items: readonly unknown[], currentIndex: number, options?: {
+    orientation?: 'horizontal' | 'vertical' | 'both';
+    loop?: boolean;
+}): number | undefined;
+export interface VisuallyHiddenProps {
+    children: React.ReactNode;
+    /** If true, becomes visible when focused (useful for skip links) */
+    focusable?: boolean;
+}
+/**
+ * Visually hides content while keeping it accessible to screen readers.
+ * Use for skip links, additional context, or off-screen labels.
+ *
+ * @example
+ * ```tsx
+ * // Hidden label for icon-only button
+ * <button>
+ *   <Icon name="search" />
+ *   <VisuallyHidden>Search</VisuallyHidden>
+ * </button>
+ *
+ * // Skip link that shows on focus
+ * <VisuallyHidden focusable>
+ *   <a href="#main">Skip to main content</a>
+ * </VisuallyHidden>
+ * ```
+ */
+export declare function VisuallyHidden({ children, focusable }: VisuallyHiddenProps): React.ReactElement;
+//# sourceMappingURL=a11y.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"a11y.d.ts","sourceRoot":"","sources":["../../src/utils/a11y.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAQ/B;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAU7C;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,IAAI;IAC7B,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,WAAW,KAAK,IAAI,CAAC;CACxE,CAiEA;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAsBjD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAmB5C;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EACxC,MAAM,EAAE,OAAO,GACd,IAAI,CAkDN;AAeD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,KAAK,CAAC,aAAa,GAAG,aAAa,EAC1C,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE;IACP,WAAW,CAAC,EAAE,YAAY,GAAG,UAAU,GAAG,MAAM,CAAC;IACjD,IAAI,CAAC,EAAE,OAAO,CAAC;CACX,GACL,MAAM,GAAG,SAAS,CA4DpB;AAMD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,oEAAoE;IACpE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,EAAE,QAAQ,EAAE,SAAiB,EAAE,EAAE,mBAAmB,GAAG,KAAK,CAAC,YAAY,CAoBvG"}

package/dist/utils/a11y.js

@@ -0,0 +1,216 @@
+import { jsx } from "react/jsx-runtime";
+import * as React from "react";
+let idCounter = 0;
+function useId(prefix) {
+  var _a;
+  const reactId = (_a = React.useId) == null ? void 0 : _a.call(React);
+  const [id] = React.useState(() => {
+    if (reactId) return reactId;
+    return `${prefix ? `${prefix}-` : "fui-"}${++idCounter}`;
+  });
+  return id;
+}
+function useAnnounce() {
+  const politeRef = React.useRef(null);
+  const assertiveRef = React.useRef(null);
+  React.useEffect(() => {
+    const polite = document.createElement("div");
+    polite.setAttribute("aria-live", "polite");
+    polite.setAttribute("aria-atomic", "true");
+    polite.setAttribute("role", "status");
+    Object.assign(polite.style, {
+      position: "absolute",
+      width: "1px",
+      height: "1px",
+      padding: "0",
+      margin: "-1px",
+      overflow: "hidden",
+      clip: "rect(0, 0, 0, 0)",
+      whiteSpace: "nowrap",
+      border: "0"
+    });
+    document.body.appendChild(polite);
+    politeRef.current = polite;
+    const assertive = document.createElement("div");
+    assertive.setAttribute("aria-live", "assertive");
+    assertive.setAttribute("aria-atomic", "true");
+    assertive.setAttribute("role", "alert");
+    Object.assign(assertive.style, {
+      position: "absolute",
+      width: "1px",
+      height: "1px",
+      padding: "0",
+      margin: "-1px",
+      overflow: "hidden",
+      clip: "rect(0, 0, 0, 0)",
+      whiteSpace: "nowrap",
+      border: "0"
+    });
+    document.body.appendChild(assertive);
+    assertiveRef.current = assertive;
+    return () => {
+      polite.remove();
+      assertive.remove();
+    };
+  }, []);
+  const announce = React.useCallback(
+    (message, priority = "polite") => {
+      const region = priority === "assertive" ? assertiveRef.current : politeRef.current;
+      if (region) {
+        region.textContent = "";
+        requestAnimationFrame(() => {
+          region.textContent = message;
+        });
+      }
+    },
+    []
+  );
+  return { announce };
+}
+function usePrefersReducedMotion() {
+  const [prefersReducedMotion, setPrefersReducedMotion] = React.useState(false);
+  React.useEffect(() => {
+    const mediaQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
+    const handleChange = (event) => {
+      setPrefersReducedMotion(event.matches);
+    };
+    mediaQuery.addEventListener("change", handleChange);
+    setPrefersReducedMotion(mediaQuery.matches);
+    return () => {
+      mediaQuery.removeEventListener("change", handleChange);
+    };
+  }, []);
+  return prefersReducedMotion;
+}
+function usePrefersContrast() {
+  const [prefersContrast, setPrefersContrast] = React.useState(false);
+  React.useEffect(() => {
+    const mediaQuery = window.matchMedia("(prefers-contrast: more)");
+    const handleChange = (event) => {
+      setPrefersContrast(event.matches);
+    };
+    mediaQuery.addEventListener("change", handleChange);
+    setPrefersContrast(mediaQuery.matches);
+    return () => {
+      mediaQuery.removeEventListener("change", handleChange);
+    };
+  }, []);
+  return prefersContrast;
+}
+function useFocusTrap(ref, active) {
+  const previousActiveElement = React.useRef(null);
+  React.useEffect(() => {
+    if (!active || !ref.current) return;
+    const container = ref.current;
+    previousActiveElement.current = document.activeElement;
+    const focusableElements = getFocusableElements(container);
+    if (focusableElements.length > 0) {
+      focusableElements[0].focus();
+    }
+    const handleKeyDown = (event) => {
+      if (event.key !== "Tab") return;
+      const focusable = getFocusableElements(container);
+      if (focusable.length === 0) return;
+      const firstFocusable = focusable[0];
+      const lastFocusable = focusable[focusable.length - 1];
+      if (event.shiftKey) {
+        if (document.activeElement === firstFocusable) {
+          event.preventDefault();
+          lastFocusable.focus();
+        }
+      } else {
+        if (document.activeElement === lastFocusable) {
+          event.preventDefault();
+          firstFocusable.focus();
+        }
+      }
+    };
+    container.addEventListener("keydown", handleKeyDown);
+    return () => {
+      container.removeEventListener("keydown", handleKeyDown);
+      if (previousActiveElement.current instanceof HTMLElement) {
+        previousActiveElement.current.focus();
+      }
+    };
+  }, [active, ref]);
+}
+function getFocusableElements(container) {
+  return container.querySelectorAll(
+    'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])'
+  );
+}
+function handleArrowNavigation(event, items, currentIndex, options = {}) {
+  const { orientation = "vertical", loop = true } = options;
+  const length = items.length;
+  if (length === 0) return void 0;
+  let newIndex;
+  switch (event.key) {
+    case "ArrowDown":
+      if (orientation === "horizontal") return void 0;
+      event.preventDefault();
+      newIndex = currentIndex + 1;
+      if (newIndex >= length) {
+        newIndex = loop ? 0 : length - 1;
+      }
+      break;
+    case "ArrowUp":
+      if (orientation === "horizontal") return void 0;
+      event.preventDefault();
+      newIndex = currentIndex - 1;
+      if (newIndex < 0) {
+        newIndex = loop ? length - 1 : 0;
+      }
+      break;
+    case "ArrowRight":
+      if (orientation === "vertical") return void 0;
+      event.preventDefault();
+      newIndex = currentIndex + 1;
+      if (newIndex >= length) {
+        newIndex = loop ? 0 : length - 1;
+      }
+      break;
+    case "ArrowLeft":
+      if (orientation === "vertical") return void 0;
+      event.preventDefault();
+      newIndex = currentIndex - 1;
+      if (newIndex < 0) {
+        newIndex = loop ? length - 1 : 0;
+      }
+      break;
+    case "Home":
+      event.preventDefault();
+      newIndex = 0;
+      break;
+    case "End":
+      event.preventDefault();
+      newIndex = length - 1;
+      break;
+    default:
+      return void 0;
+  }
+  return newIndex;
+}
+function VisuallyHidden({ children, focusable = false }) {
+  const style = focusable ? {} : {
+    position: "absolute",
+    width: "1px",
+    height: "1px",
+    padding: "0",
+    margin: "-1px",
+    overflow: "hidden",
+    clip: "rect(0, 0, 0, 0)",
+    whiteSpace: "nowrap",
+    border: "0"
+  };
+  return /* @__PURE__ */ jsx("span", { style, "data-visually-hidden": !focusable || void 0, children });
+}
+export {
+  VisuallyHidden,
+  handleArrowNavigation,
+  useAnnounce,
+  useFocusTrap,
+  useId,
+  usePrefersContrast,
+  usePrefersReducedMotion
+};
+//# sourceMappingURL=a11y.js.map

package/dist/utils/a11y.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a11y.js","sources":["../../src/utils/a11y.tsx"],"sourcesContent":["'use client';\n\nimport * as React from 'react';\n\n// ============================================\n// Unique ID Generator\n// ============================================\n\nlet idCounter = 0;\n\n/**\n * Generates a unique ID for ARIA relationships (labelledby, describedby, etc.)\n * Falls back to React.useId if available (React 18+), otherwise uses a counter.\n *\n * @param prefix - Optional prefix for the ID\n * @returns A unique ID string\n *\n * @example\n * ```tsx\n * const id = useId('dialog-title');\n * // Returns: \"dialog-title-1\" or \":r0:\" (React 18)\n * ```\n */\nexport function useId(prefix?: string): string {\n  // Use React 18's useId if available\n  const reactId = React.useId?.();\n\n  const [id] = React.useState(() => {\n    if (reactId) return reactId;\n    return `${prefix ? `${prefix}-` : 'fui-'}${++idCounter}`;\n  });\n\n  return id;\n}\n\n// ============================================\n// Screen Reader Announcements\n// ============================================\n\n/**\n * Hook to announce messages to screen readers via a live region.\n * Creates an ARIA live region that persists for the component lifetime.\n *\n * @returns An object with an announce function\n *\n * @example\n * ```tsx\n * const { announce } = useAnnounce();\n *\n * // Polite announcement (waits for screen reader to finish)\n * announce('Item added to cart');\n *\n * // Assertive announcement (interrupts immediately)\n * announce('Error: Please fix the form', 'assertive');\n * ```\n */\nexport function useAnnounce(): {\n  announce: (message: string, priority?: 'polite' | 'assertive') => void;\n} {\n  const politeRef = React.useRef<HTMLDivElement | null>(null);\n  const assertiveRef = React.useRef<HTMLDivElement | null>(null);\n\n  React.useEffect(() => {\n    // Create live regions on mount\n    const polite = document.createElement('div');\n    polite.setAttribute('aria-live', 'polite');\n    polite.setAttribute('aria-atomic', 'true');\n    polite.setAttribute('role', 'status');\n    Object.assign(polite.style, {\n      position: 'absolute',\n      width: '1px',\n      height: '1px',\n      padding: '0',\n      margin: '-1px',\n      overflow: 'hidden',\n      clip: 'rect(0, 0, 0, 0)',\n      whiteSpace: 'nowrap',\n      border: '0',\n    });\n    document.body.appendChild(polite);\n    politeRef.current = polite;\n\n    const assertive = document.createElement('div');\n    assertive.setAttribute('aria-live', 'assertive');\n    assertive.setAttribute('aria-atomic', 'true');\n    assertive.setAttribute('role', 'alert');\n    Object.assign(assertive.style, {\n      position: 'absolute',\n      width: '1px',\n      height: '1px',\n      padding: '0',\n      margin: '-1px',\n      overflow: 'hidden',\n      clip: 'rect(0, 0, 0, 0)',\n      whiteSpace: 'nowrap',\n      border: '0',\n    });\n    document.body.appendChild(assertive);\n    assertiveRef.current = assertive;\n\n    // Cleanup on unmount\n    return () => {\n      polite.remove();\n      assertive.remove();\n    };\n  }, []);\n\n  const announce = React.useCallback(\n    (message: string, priority: 'polite' | 'assertive' = 'polite') => {\n      const region = priority === 'assertive' ? assertiveRef.current : politeRef.current;\n      if (region) {\n        // Clear and re-set to ensure announcement\n        region.textContent = '';\n        // Use requestAnimationFrame to ensure the clear is processed\n        requestAnimationFrame(() => {\n          region.textContent = message;\n        });\n      }\n    },\n    []\n  );\n\n  return { announce };\n}\n\n// ============================================\n// User Preference Detection\n// ============================================\n\n/**\n * Hook to detect if the user prefers reduced motion.\n * Respects the `prefers-reduced-motion` media query.\n *\n * @returns boolean - true if user prefers reduced motion\n *\n * @example\n * ```tsx\n * const prefersReducedMotion = usePrefersReducedMotion();\n *\n * <div style={{\n *   transition: prefersReducedMotion ? 'none' : 'transform 200ms'\n * }}>\n * ```\n */\nexport function usePrefersReducedMotion(): boolean {\n  const [prefersReducedMotion, setPrefersReducedMotion] = React.useState(false);\n\n  React.useEffect(() => {\n    const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');\n\n    const handleChange = (event: MediaQueryListEvent) => {\n      setPrefersReducedMotion(event.matches);\n    };\n\n    // Modern browsers\n    mediaQuery.addEventListener('change', handleChange);\n\n    // Set initial value\n    setPrefersReducedMotion(mediaQuery.matches);\n\n    return () => {\n      mediaQuery.removeEventListener('change', handleChange);\n    };\n  }, []);\n\n  return prefersReducedMotion;\n}\n\n/**\n * Hook to detect if the user prefers increased contrast.\n * Respects the `prefers-contrast: more` media query.\n *\n * @returns boolean - true if user prefers high contrast\n *\n * @example\n * ```tsx\n * const prefersContrast = usePrefersContrast();\n *\n * <div className={prefersContrast ? styles.highContrast : undefined}>\n * ```\n */\nexport function usePrefersContrast(): boolean {\n  const [prefersContrast, setPrefersContrast] = React.useState(false);\n\n  React.useEffect(() => {\n    const mediaQuery = window.matchMedia('(prefers-contrast: more)');\n\n    const handleChange = (event: MediaQueryListEvent) => {\n      setPrefersContrast(event.matches);\n    };\n\n    mediaQuery.addEventListener('change', handleChange);\n    setPrefersContrast(mediaQuery.matches);\n\n    return () => {\n      mediaQuery.removeEventListener('change', handleChange);\n    };\n  }, []);\n\n  return prefersContrast;\n}\n\n// ============================================\n// Focus Management\n// ============================================\n\n/**\n * Hook to trap focus within a container element.\n * Useful for modals, dialogs, and other overlays.\n *\n * @param ref - React ref to the container element\n * @param active - Whether focus trap is active\n *\n * @example\n * ```tsx\n * const dialogRef = useRef<HTMLDivElement>(null);\n * useFocusTrap(dialogRef, isOpen);\n *\n * return <div ref={dialogRef}>...</div>;\n * ```\n */\nexport function useFocusTrap(\n  ref: React.RefObject<HTMLElement | null>,\n  active: boolean\n): void {\n  const previousActiveElement = React.useRef<Element | null>(null);\n\n  React.useEffect(() => {\n    if (!active || !ref.current) return;\n\n    const container = ref.current;\n    previousActiveElement.current = document.activeElement;\n\n    // Focus the first focusable element\n    const focusableElements = getFocusableElements(container);\n    if (focusableElements.length > 0) {\n      (focusableElements[0] as HTMLElement).focus();\n    }\n\n    const handleKeyDown = (event: KeyboardEvent) => {\n      if (event.key !== 'Tab') return;\n\n      const focusable = getFocusableElements(container);\n      if (focusable.length === 0) return;\n\n      const firstFocusable = focusable[0] as HTMLElement;\n      const lastFocusable = focusable[focusable.length - 1] as HTMLElement;\n\n      if (event.shiftKey) {\n        // Shift + Tab: move focus backward\n        if (document.activeElement === firstFocusable) {\n          event.preventDefault();\n          lastFocusable.focus();\n        }\n      } else {\n        // Tab: move focus forward\n        if (document.activeElement === lastFocusable) {\n          event.preventDefault();\n          firstFocusable.focus();\n        }\n      }\n    };\n\n    container.addEventListener('keydown', handleKeyDown);\n\n    return () => {\n      container.removeEventListener('keydown', handleKeyDown);\n\n      // Restore focus when trap is deactivated\n      if (previousActiveElement.current instanceof HTMLElement) {\n        previousActiveElement.current.focus();\n      }\n    };\n  }, [active, ref]);\n}\n\n/**\n * Get all focusable elements within a container\n */\nfunction getFocusableElements(container: HTMLElement): NodeListOf<Element> {\n  return container.querySelectorAll(\n    'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex=\"-1\"])'\n  );\n}\n\n// ============================================\n// Keyboard Navigation Helpers\n// ============================================\n\n/**\n * Helper to handle keyboard navigation within a group of elements.\n * Supports arrow keys, Home, End, and optional type-ahead.\n *\n * @param event - Keyboard event\n * @param items - Array of focusable items\n * @param currentIndex - Current focused item index\n * @param options - Navigation options\n * @returns New index or undefined if no navigation occurred\n *\n * @example\n * ```tsx\n * const handleKeyDown = (event: KeyboardEvent) => {\n *   const newIndex = handleArrowNavigation(event, menuItems, currentIndex, {\n *     orientation: 'vertical',\n *     loop: true,\n *   });\n *   if (newIndex !== undefined) {\n *     setCurrentIndex(newIndex);\n *   }\n * };\n * ```\n */\nexport function handleArrowNavigation(\n  event: React.KeyboardEvent | KeyboardEvent,\n  items: readonly unknown[],\n  currentIndex: number,\n  options: {\n    orientation?: 'horizontal' | 'vertical' | 'both';\n    loop?: boolean;\n  } = {}\n): number | undefined {\n  const { orientation = 'vertical', loop = true } = options;\n  const length = items.length;\n\n  if (length === 0) return undefined;\n\n  let newIndex: number | undefined;\n\n  switch (event.key) {\n    case 'ArrowDown':\n      if (orientation === 'horizontal') return undefined;\n      event.preventDefault();\n      newIndex = currentIndex + 1;\n      if (newIndex >= length) {\n        newIndex = loop ? 0 : length - 1;\n      }\n      break;\n\n    case 'ArrowUp':\n      if (orientation === 'horizontal') return undefined;\n      event.preventDefault();\n      newIndex = currentIndex - 1;\n      if (newIndex < 0) {\n        newIndex = loop ? length - 1 : 0;\n      }\n      break;\n\n    case 'ArrowRight':\n      if (orientation === 'vertical') return undefined;\n      event.preventDefault();\n      newIndex = currentIndex + 1;\n      if (newIndex >= length) {\n        newIndex = loop ? 0 : length - 1;\n      }\n      break;\n\n    case 'ArrowLeft':\n      if (orientation === 'vertical') return undefined;\n      event.preventDefault();\n      newIndex = currentIndex - 1;\n      if (newIndex < 0) {\n        newIndex = loop ? length - 1 : 0;\n      }\n      break;\n\n    case 'Home':\n      event.preventDefault();\n      newIndex = 0;\n      break;\n\n    case 'End':\n      event.preventDefault();\n      newIndex = length - 1;\n      break;\n\n    default:\n      return undefined;\n  }\n\n  return newIndex;\n}\n\n// ============================================\n// Screen Reader Only Component\n// ============================================\n\nexport interface VisuallyHiddenProps {\n  children: React.ReactNode;\n  /** If true, becomes visible when focused (useful for skip links) */\n  focusable?: boolean;\n}\n\n/**\n * Visually hides content while keeping it accessible to screen readers.\n * Use for skip links, additional context, or off-screen labels.\n *\n * @example\n * ```tsx\n * // Hidden label for icon-only button\n * <button>\n *   <Icon name=\"search\" />\n *   <VisuallyHidden>Search</VisuallyHidden>\n * </button>\n *\n * // Skip link that shows on focus\n * <VisuallyHidden focusable>\n *   <a href=\"#main\">Skip to main content</a>\n * </VisuallyHidden>\n * ```\n */\nexport function VisuallyHidden({ children, focusable = false }: VisuallyHiddenProps): React.ReactElement {\n  const style: React.CSSProperties = focusable\n    ? {}\n    : {\n        position: 'absolute',\n        width: '1px',\n        height: '1px',\n        padding: '0',\n        margin: '-1px',\n        overflow: 'hidden',\n        clip: 'rect(0, 0, 0, 0)',\n        whiteSpace: 'nowrap',\n        border: '0',\n      };\n\n  return (\n    <span style={style} data-visually-hidden={!focusable || undefined}>\n      {children}\n    </span>\n  );\n}\n"],"names":[],"mappings":"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"}