@craftzbay/ui 0.9.0 → 0.11.0

package/dist-lib/components/ui/TopNav.d.ts

@@ -1,4 +1,4 @@
-import { HTMLAttributes, ReactNode } from 'react';
+import { AnchorHTMLAttributes, HTMLAttributes, ReactNode } from 'react';
 export interface TopNavProps extends HTMLAttributes<HTMLElement> {
     /** Logo / wordmark slot. Shown on the far left. */
     logo: ReactNode;
@@ -8,6 +8,8 @@ export interface TopNavProps extends HTMLAttributes<HTMLElement> {
     search?: ReactNode;
     /** Right-aligned cluster — notifications, theme toggle, user menu. */
     actions?: ReactNode;
+    /** Accessible name of the inner `<nav>` landmark. Default "Primary". */
+    navLabel?: string;
 }
 /**
  * App-level top bar. Layout: `logo · nav · search · actions`. Search and nav
@@ -26,8 +28,10 @@ export interface TopNavProps extends HTMLAttributes<HTMLElement> {
  *       put them below the bar inside the page content.
  */
 export declare const TopNav: import('react').ForwardRefExoticComponent<TopNavProps & import('react').RefAttributes<HTMLElement>>;
-export interface TopNavLinkProps extends HTMLAttributes<HTMLAnchorElement> {
-    href: string;
+export interface TopNavLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+    href?: string;
     active?: boolean;
+    /** Render the child (e.g. router `<Link>`) instead of an `<a>`. */
+    asChild?: boolean;
 }
 export declare const TopNavLink: import('react').ForwardRefExoticComponent<TopNavLinkProps & import('react').RefAttributes<HTMLAnchorElement>>;

package/dist-lib/components/ui/TopNav.js

@@ -0,0 +1,62 @@
+"use client";
+import { jsxs as l, jsx as i } from "react/jsx-runtime";
+import { forwardRef as d } from "react";
+import { Slot as u } from "@radix-ui/react-slot";
+import { useStrings as g } from "../../hooks/use-strings.js";
+import { cn as c } from "../../lib/utils.js";
+const v = d(function({ logo: n, nav: e, search: r, actions: o, navLabel: t, className: s, ...a }, m) {
+  const p = g();
+  return /* @__PURE__ */ l(
+    "header",
+    {
+      ref: m,
+      className: c(
+        "sticky top-0 z-[var(--z-sticky)] flex h-14 w-full items-center gap-4",
+        "border-border bg-background border-b px-4",
+        s
+      ),
+      ...a,
+      children: [
+        /* @__PURE__ */ l("div", { className: "flex min-w-0 items-center gap-6", children: [
+          n,
+          e && /* @__PURE__ */ i(
+            "nav",
+            {
+              "aria-label": t ?? p.topNav.label,
+              className: "hidden items-center gap-1 md:flex",
+              children: e
+            }
+          )
+        ] }),
+        r && /* @__PURE__ */ i("div", { className: "mx-auto max-w-md flex-1", children: r }),
+        o && /* @__PURE__ */ i("div", { className: "ml-auto flex shrink-0 items-center gap-2", children: o })
+      ]
+    }
+  );
+});
+v.displayName = "TopNav";
+const x = d(function({ href: n, active: e, asChild: r, className: o, children: t, ...s }, a) {
+  return /* @__PURE__ */ i(
+    r ? u : "a",
+    {
+      ref: a,
+      href: n,
+      "aria-current": e ? "page" : void 0,
+      className: c(
+        "inline-flex h-9 items-center rounded-md px-3 text-sm font-medium outline-none",
+        "transition-colors duration-[var(--duration-fast)]",
+        e ? "text-foreground" : "text-foreground-muted hover:text-foreground",
+        "focus-visible:ring-ring focus-visible:ring-offset-background focus-visible:ring-2 focus-visible:ring-offset-2",
+        o
+      ),
+      ...s,
+      children: t
+    }
+  );
+});
+x.displayName = "TopNavLink";
+export {
+  v as TopNav,
+  x as TopNavLink
+};
+//# sourceMappingURL=TopNav.js.map

package/dist-lib/components/ui/TopNav.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TopNav.js","sources":["../../../src/components/ui/TopNav.tsx"],"sourcesContent":["'use client';\n\nimport { forwardRef, type AnchorHTMLAttributes, type HTMLAttributes, type ReactNode } from 'react';\nimport { Slot } from '@radix-ui/react-slot';\nimport { useStrings } from '@/hooks/use-strings';\nimport { cn } from '@/lib/utils';\n\nexport interface TopNavProps extends HTMLAttributes<HTMLElement> {\n  /** Logo / wordmark slot. Shown on the far left. */\n  logo: ReactNode;\n  /** Primary navigation links — typically a list of `<TopNavLink>`. */\n  nav?: ReactNode;\n  /** Search / command bar slot — fills the centre on wide screens. */\n  search?: ReactNode;\n  /** Right-aligned cluster — notifications, theme toggle, user menu. */\n  actions?: ReactNode;\n  /** Accessible name of the inner `<nav>` landmark. Default \"Primary\". */\n  navLabel?: string;\n}\n\n/**\n * App-level top bar. Layout: `logo · nav · search · actions`. Search and nav\n * are optional.\n *\n * @example\n *   <TopNav\n *     logo={<Logo />}\n *     nav={<><TopNavLink href=\"/\" active>Home</TopNavLink>…</>}\n *     search={<Input type=\"search\" placeholder=\"Search…\" />}\n *     actions={<><Bell /><Avatar /></>}\n *   />\n *\n * @do Pick one primary nav style — links here or in the Sidebar, not both.\n * @dont Stack two rows of navigation in the TopNav. If you need tabs as well,\n *       put them below the bar inside the page content.\n */\nexport const TopNav = forwardRef<HTMLElement, TopNavProps>(function TopNav(\n  { logo, nav, search, actions, navLabel, className, ...props },\n  ref,\n) {\n  const strings = useStrings();\n  return (\n    <header\n      ref={ref}\n      className={cn(\n        'sticky top-0 z-[var(--z-sticky)] flex h-14 w-full items-center gap-4',\n        'border-border bg-background border-b px-4',\n        className,\n      )}\n      {...props}\n    >\n      <div className=\"flex min-w-0 items-center gap-6\">\n        {logo}\n        {nav && (\n          <nav\n            aria-label={navLabel ?? strings.topNav.label}\n            className=\"hidden items-center gap-1 md:flex\"\n          >\n            {nav}\n          </nav>\n        )}\n      </div>\n      {search && <div className=\"mx-auto max-w-md flex-1\">{search}</div>}\n      {actions && <div className=\"ml-auto flex shrink-0 items-center gap-2\">{actions}</div>}\n    </header>\n  );\n});\nTopNav.displayName = 'TopNav';\n\nexport interface TopNavLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {\n  href?: string;\n  active?: boolean;\n  /** Render the child (e.g. router `<Link>`) instead of an `<a>`. */\n  asChild?: boolean;\n}\n\nexport const TopNavLink = forwardRef<HTMLAnchorElement, TopNavLinkProps>(function TopNavLink(\n  { href, active, asChild, className, children, ...props },\n  ref,\n) {\n  const Comp = asChild ? Slot : 'a';\n  return (\n    <Comp\n      ref={ref}\n      href={href}\n      aria-current={active ? 'page' : undefined}\n      className={cn(\n        'inline-flex h-9 items-center rounded-md px-3 text-sm font-medium outline-none',\n        'transition-colors duration-[var(--duration-fast)]',\n        active ? 'text-foreground' : 'text-foreground-muted hover:text-foreground',\n        'focus-visible:ring-ring focus-visible:ring-offset-background focus-visible:ring-2 focus-visible:ring-offset-2',\n        className,\n      )}\n      {...props}\n    >\n      {children}\n    </Comp>\n  );\n});\nTopNavLink.displayName = 'TopNavLink';\n"],"names":["TopNav","forwardRef","logo","nav","search","actions","navLabel","className","props","ref","strings","useStrings","jsxs","cn","jsx","TopNavLink","href","active","asChild","children","Slot"],"mappings":";;;;;;AAoCO,MAAMA,IAASC,EAAqC,SACzD,EAAE,MAAAC,GAAM,KAAAC,GAAK,QAAAC,GAAQ,SAAAC,GAAS,UAAAC,GAAU,WAAAC,GAAW,GAAGC,EAAA,GACtDC,GACA;AACA,QAAMC,IAAUC,EAAA;AAChB,SACE,gBAAAC;AAAA,IAAC;AAAA,IAAA;AAAA,MACC,KAAAH;AAAA,MACA,WAAWI;AAAA,QACT;AAAA,QACA;AAAA,QACAN;AAAA,MAAA;AAAA,MAED,GAAGC;AAAA,MAEJ,UAAA;AAAA,QAAA,gBAAAI,EAAC,OAAA,EAAI,WAAU,mCACZ,UAAA;AAAA,UAAAV;AAAA,UACAC,KACC,gBAAAW;AAAA,YAAC;AAAA,YAAA;AAAA,cACC,cAAYR,KAAYI,EAAQ,OAAO;AAAA,cACvC,WAAU;AAAA,cAET,UAAAP;AAAA,YAAA;AAAA,UAAA;AAAA,QACH,GAEJ;AAAA,QACCC,KAAU,gBAAAU,EAAC,OAAA,EAAI,WAAU,2BAA2B,UAAAV,GAAO;AAAA,QAC3DC,KAAW,gBAAAS,EAAC,OAAA,EAAI,WAAU,4CAA4C,UAAAT,EAAA,CAAQ;AAAA,MAAA;AAAA,IAAA;AAAA,EAAA;AAGrF,CAAC;AACDL,EAAO,cAAc;AASd,MAAMe,IAAad,EAA+C,SACvE,EAAE,MAAAe,GAAM,QAAAC,GAAQ,SAAAC,GAAS,WAAAX,GAAW,UAAAY,GAAU,GAAGX,EAAA,GACjDC,GACA;AAEA,SACE,gBAAAK;AAAA,IAFWI,IAAUE,IAAO;AAAA,IAE3B;AAAA,MACC,KAAAX;AAAA,MACA,MAAAO;AAAA,MACA,gBAAcC,IAAS,SAAS;AAAA,MAChC,WAAWJ;AAAA,QACT;AAAA,QACA;AAAA,QACAI,IAAS,oBAAoB;AAAA,QAC7B;AAAA,QACAV;AAAA,MAAA;AAAA,MAED,GAAGC;AAAA,MAEH,UAAAW;AAAA,IAAA;AAAA,EAAA;AAGP,CAAC;AACDJ,EAAW,cAAc;"}

package/dist-lib/components/ui/Tree.d.ts

@@ -1,4 +1,4 @@
-import { ReactNode } from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
 export interface TreeNode {
     id: string;
     label: ReactNode;
@@ -7,18 +7,45 @@ export interface TreeNode {
     /** Optional custom icon (overrides default file/folder icons). */
     icon?: ReactNode;
 }
-export interface TreeProps {
+export interface TreeProps extends Omit<HTMLAttributes<HTMLUListElement>, 'onSelect'> {
     /** The root nodes. */
     data: TreeNode[];
-    /** Ids to expand by default. */
+    /** Ids to expand by default (uncontrolled). */
     defaultExpanded?: string[];
-    /** Currently selected node id. */
+    /** Controlled set of expanded ids. */
+    expanded?: string[];
+    /** Called with the full next set of expanded ids. */
+    onExpandedChange?: (next: string[]) => void;
+    /**
+     * @deprecated Use `selected` + `onSelectedChange`. Kept for backward
+     * compatibility; ignored when `selected` is present.
+     */
     selectedId?: string;
+    /**
+     * Controlled selected id. The component is controlled whenever this key is
+     * present in props (even as `undefined`), mirroring React inputs.
+     */
+    selected?: string;
+    /** Default selected id (uncontrolled). */
+    defaultSelected?: string;
+    /**
+     * @deprecated Use `onSelectedChange`. Still called on every activation.
+     */
     onSelect?: (id: string) => void;
+    /** Called when a node is activated (click / Enter / Space). */
+    onSelectedChange?: (id: string) => void;
+    /** Accessible name for the tree. */
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
     className?: string;
 }
 /**
- * Expandable file-tree style list. Single selection. Keyboard a11y is
- * handled at the row level (`tabIndex`, Enter, ArrowRight/Left to toggle).
+ * Expandable file-tree style list following the WAI-ARIA tree pattern.
+ * Single selection, roving tabindex (one tab stop), and full arrow-key
+ * navigation: Up/Down move, Right expands or moves into a folder, Left
+ * collapses or moves to the parent, Home/End jump, Enter/Space select.
+ *
+ * Expansion and selection are uncontrolled by default; pass
+ * `expanded`/`onExpandedChange` and `selected`/`onSelectedChange` to control.
  */
-export declare function Tree({ data, defaultExpanded, selectedId, onSelect, className }: TreeProps): import("react/jsx-runtime").JSX.Element;
+export declare const Tree: import('react').ForwardRefExoticComponent<TreeProps & import('react').RefAttributes<HTMLUListElement>>;

package/dist-lib/components/ui/Tree.js

@@ -0,0 +1,170 @@
+"use client";
+import { jsx as f, jsxs as j } from "react/jsx-runtime";
+import { forwardRef as _, useState as F, useMemo as K, useRef as ee, useCallback as R } from "react";
+import { ChevronRight as te, FolderOpen as re, Folder as ie, File as se } from "../../icons/index.js";
+import { cn as T } from "../../lib/utils.js";
+import { useStrings as ae } from "../../hooks/use-strings.js";
+const ne = _(function(I, M) {
+  var P;
+  const {
+    data: m,
+    defaultExpanded: H = [],
+    expanded: u,
+    onExpandedChange: h,
+    selectedId: U,
+    selected: $,
+    defaultSelected: q,
+    onSelect: b,
+    onSelectedChange: g,
+    className: B,
+    "aria-label": G,
+    "aria-labelledby": z,
+    ...J
+  } = I, D = "selected" in I || "selectedId" in I, Q = ae(), [A, V] = F(
+    () => new Set(H)
+  ), c = K(
+    () => u ? new Set(u) : A,
+    [u, A]
+  ), [W, X] = F(q), x = D ? $ ?? U : W, [N, y] = F(void 0), S = ee(/* @__PURE__ */ new Map()), C = R(
+    (e) => {
+      u === void 0 && V(e), h == null || h([...e]);
+    },
+    [u, h]
+  ), v = R(
+    (e, t) => {
+      if (c.has(e) === t) return;
+      const r = new Set(c);
+      t ? r.add(e) : r.delete(e), C(r);
+    },
+    [c, C]
+  ), L = R(
+    (e) => {
+      D || X(e), b == null || b(e), g == null || g(e);
+    },
+    [b, g, D]
+  ), n = K(() => {
+    const e = [], t = (r, l, d) => {
+      r.forEach((s, a) => {
+        e.push({ node: s, level: l, setSize: r.length, posInSet: a + 1, parentId: d }), s.children && c.has(s.id) && t(s.children, l + 1, s.id);
+      });
+    };
+    return t(m, 1, null), e;
+  }, [m, c]), Y = N && n.some((e) => e.node.id === N) && N || x && n.some((e) => e.node.id === x) && x || ((P = n[0]) == null ? void 0 : P.node.id), o = (e) => {
+    var t;
+    e && (y(e), (t = S.current.get(e)) == null || t.focus());
+  }, Z = (e, t) => {
+    var a, p, k, w, i;
+    const { node: r } = t, l = !!r.children, d = c.has(r.id), s = n.findIndex((E) => E.node.id === r.id);
+    switch (e.key) {
+      case "ArrowDown":
+        e.preventDefault(), o((a = n[s + 1]) == null ? void 0 : a.node.id);
+        break;
+      case "ArrowUp":
+        e.preventDefault(), o((p = n[s - 1]) == null ? void 0 : p.node.id);
+        break;
+      case "ArrowRight":
+        e.preventDefault(), l && !d ? v(r.id, !0) : l && d && o((k = r.children[0]) == null ? void 0 : k.id);
+        break;
+      case "ArrowLeft":
+        e.preventDefault(), l && d ? v(r.id, !1) : t.parentId && o(t.parentId);
+        break;
+      case "Home":
+        e.preventDefault(), o((w = n[0]) == null ? void 0 : w.node.id);
+        break;
+      case "End":
+        e.preventDefault(), o((i = n[n.length - 1]) == null ? void 0 : i.node.id);
+        break;
+      case "Enter":
+      case " ":
+        e.preventDefault(), L(r.id), l && v(r.id, !d);
+        break;
+      default:
+        return;
+    }
+    e.stopPropagation();
+  };
+  function O(e, t, r, l, d) {
+    const s = !!e.children, a = c.has(e.id), p = x === e.id, k = s ? a ? re : ie : se, w = { node: e, parentId: d };
+    return /* @__PURE__ */ j(
+      "li",
+      {
+        ref: (i) => {
+          i ? S.current.set(e.id, i) : S.current.delete(e.id);
+        },
+        role: "treeitem",
+        "aria-expanded": s ? a : void 0,
+        "aria-selected": p,
+        "aria-level": t,
+        "aria-setsize": r,
+        "aria-posinset": l,
+        tabIndex: Y === e.id ? 0 : -1,
+        onFocus: (i) => {
+          i.target === i.currentTarget && y(e.id);
+        },
+        onKeyDown: (i) => {
+          i.target === i.currentTarget && Z(i, w);
+        },
+        onClick: (i) => {
+          i.stopPropagation(), y(e.id), L(e.id), s && v(e.id, !a);
+        },
+        className: "outline-none",
+        children: [
+          /* @__PURE__ */ j(
+            "div",
+            {
+              style: { paddingLeft: `${t - 1 + 0.5}rem` },
+              className: T(
+                "flex w-full cursor-default items-center gap-1.5 rounded-md py-1 pr-2 text-left text-sm",
+                "hover:bg-background-muted",
+                "[li:focus-visible>&]:ring-ring [li:focus-visible>&]:ring-offset-background [li:focus-visible>&]:ring-2 [li:focus-visible>&]:ring-offset-1",
+                p && "bg-accent-soft text-foreground"
+              ),
+              children: [
+                s ? /* @__PURE__ */ f(
+                  te,
+                  {
+                    className: T(
+                      "text-foreground-subtle size-3.5 shrink-0 transition-transform",
+                      a && "rotate-90"
+                    ),
+                    "aria-hidden": !0
+                  }
+                ) : /* @__PURE__ */ f("span", { className: "w-3.5 shrink-0", "aria-hidden": !0 }),
+                e.icon ?? /* @__PURE__ */ f(k, { className: "text-foreground-muted size-4 shrink-0", "aria-hidden": !0 }),
+                /* @__PURE__ */ f(
+                  "span",
+                  {
+                    className: "truncate",
+                    title: typeof e.label == "string" ? e.label : void 0,
+                    children: e.label
+                  }
+                )
+              ]
+            }
+          ),
+          s && a && /* @__PURE__ */ f("ul", { role: "group", className: "mt-0.5", children: e.children.map(
+            (i, E) => O(i, t + 1, e.children.length, E + 1, e.id)
+          ) })
+        ]
+      },
+      e.id
+    );
+  }
+  return /* @__PURE__ */ f(
+    "ul",
+    {
+      ref: M,
+      role: "tree",
+      "aria-label": G ?? (z ? void 0 : Q.tree.label),
+      "aria-labelledby": z,
+      className: T("flex flex-col gap-0.5", B),
+      ...J,
+      children: m.map((e, t) => O(e, 1, m.length, t + 1, null))
+    }
+  );
+});
+ne.displayName = "Tree";
+export {
+  ne as Tree
+};
+//# sourceMappingURL=Tree.js.map

package/dist-lib/components/ui/Tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tree.js","sources":["../../../src/components/ui/Tree.tsx"],"sourcesContent":["'use client';\n\nimport {\n  forwardRef,\n  useCallback,\n  useMemo,\n  useRef,\n  useState,\n  type HTMLAttributes,\n  type KeyboardEvent,\n  type ReactNode,\n} from 'react';\nimport { ChevronRight, File as FileIcon, Folder, FolderOpen } from '@/icons';\nimport { cn } from '@/lib/utils';\nimport { useStrings } from '@/hooks/use-strings';\n\nexport interface TreeNode {\n  id: string;\n  label: ReactNode;\n  /** If undefined the node is a leaf; if empty array it is an empty folder. */\n  children?: TreeNode[];\n  /** Optional custom icon (overrides default file/folder icons). */\n  icon?: ReactNode;\n}\n\nexport interface TreeProps extends Omit<HTMLAttributes<HTMLUListElement>, 'onSelect'> {\n  /** The root nodes. */\n  data: TreeNode[];\n  /** Ids to expand by default (uncontrolled). */\n  defaultExpanded?: string[];\n  /** Controlled set of expanded ids. */\n  expanded?: string[];\n  /** Called with the full next set of expanded ids. */\n  onExpandedChange?: (next: string[]) => void;\n  /**\n   * @deprecated Use `selected` + `onSelectedChange`. Kept for backward\n   * compatibility; ignored when `selected` is present.\n   */\n  selectedId?: string;\n  /**\n   * Controlled selected id. The component is controlled whenever this key is\n   * present in props (even as `undefined`), mirroring React inputs.\n   */\n  selected?: string;\n  /** Default selected id (uncontrolled). */\n  defaultSelected?: string;\n  /**\n   * @deprecated Use `onSelectedChange`. Still called on every activation.\n   */\n  onSelect?: (id: string) => void;\n  /** Called when a node is activated (click / Enter / Space). */\n  onSelectedChange?: (id: string) => void;\n  /** Accessible name for the tree. */\n  'aria-label'?: string;\n  'aria-labelledby'?: string;\n  className?: string;\n}\n\ninterface FlatNode {\n  node: TreeNode;\n  level: number;\n  setSize: number;\n  posInSet: number;\n  parentId: string | null;\n}\n\n/**\n * Expandable file-tree style list following the WAI-ARIA tree pattern.\n * Single selection, roving tabindex (one tab stop), and full arrow-key\n * navigation: Up/Down move, Right expands or moves into a folder, Left\n * collapses or moves to the parent, Home/End jump, Enter/Space select.\n *\n * Expansion and selection are uncontrolled by default; pass\n * `expanded`/`onExpandedChange` and `selected`/`onSelectedChange` to control.\n */\nexport const Tree = forwardRef<HTMLUListElement, TreeProps>(function Tree(props, ref) {\n  const {\n    data,\n    defaultExpanded = [],\n    expanded: expandedProp,\n    onExpandedChange,\n    selectedId,\n    selected: selectedProp,\n    defaultSelected,\n    onSelect,\n    onSelectedChange,\n    className,\n    'aria-label': ariaLabel,\n    'aria-labelledby': ariaLabelledby,\n    ...rest\n  } = props;\n  const isControlled = 'selected' in props || 'selectedId' in props;\n  const strings = useStrings();\n  const [internalExpanded, setInternalExpanded] = useState<Set<string>>(\n    () => new Set(defaultExpanded),\n  );\n  const expanded = useMemo(\n    () => (expandedProp ? new Set(expandedProp) : internalExpanded),\n    [expandedProp, internalExpanded],\n  );\n\n  const [internalSelected, setInternalSelected] = useState<string | undefined>(defaultSelected);\n  const selected = isControlled ? (selectedProp ?? selectedId) : internalSelected;\n\n  const [focusedId, setFocusedId] = useState<string | undefined>(undefined);\n  const itemRefs = useRef(new Map<string, HTMLLIElement>());\n\n  const setExpanded = useCallback(\n    (next: Set<string>) => {\n      if (expandedProp === undefined) setInternalExpanded(next);\n      onExpandedChange?.([...next]);\n    },\n    [expandedProp, onExpandedChange],\n  );\n\n  const setOpen = useCallback(\n    (id: string, open: boolean) => {\n      if (expanded.has(id) === open) return;\n      const next = new Set(expanded);\n      if (open) next.add(id);\n      else next.delete(id);\n      setExpanded(next);\n    },\n    [expanded, setExpanded],\n  );\n\n  const select = useCallback(\n    (id: string) => {\n      if (!isControlled) setInternalSelected(id);\n      onSelect?.(id);\n      onSelectedChange?.(id);\n    },\n    [onSelect, onSelectedChange, isControlled],\n  );\n\n  // Flatten the *visible* nodes in DOM order — this is what arrow keys walk.\n  const visible = useMemo(() => {\n    const out: FlatNode[] = [];\n    const walk = (nodes: TreeNode[], level: number, parentId: string | null) => {\n      nodes.forEach((node, i) => {\n        out.push({ node, level, setSize: nodes.length, posInSet: i + 1, parentId });\n        if (node.children && expanded.has(node.id)) walk(node.children, level + 1, node.id);\n      });\n    };\n    walk(data, 1, null);\n    return out;\n  }, [data, expanded]);\n\n  // The single tab stop: focused item if still visible, else selected, else first.\n  const tabStopId =\n    (focusedId && visible.some((v) => v.node.id === focusedId) && focusedId) ||\n    (selected && visible.some((v) => v.node.id === selected) && selected) ||\n    visible[0]?.node.id;\n\n  const focusItem = (id: string | undefined) => {\n    if (!id) return;\n    setFocusedId(id);\n    itemRefs.current.get(id)?.focus();\n  };\n\n  const handleKeyDown = (e: KeyboardEvent<HTMLLIElement>, flat: FlatNode) => {\n    const { node } = flat;\n    const hasChildren = !!node.children;\n    const isOpen = expanded.has(node.id);\n    const index = visible.findIndex((v) => v.node.id === node.id);\n\n    switch (e.key) {\n      case 'ArrowDown':\n        e.preventDefault();\n        focusItem(visible[index + 1]?.node.id);\n        break;\n      case 'ArrowUp':\n        e.preventDefault();\n        focusItem(visible[index - 1]?.node.id);\n        break;\n      case 'ArrowRight':\n        e.preventDefault();\n        if (hasChildren && !isOpen) setOpen(node.id, true);\n        else if (hasChildren && isOpen) focusItem(node.children![0]?.id);\n        break;\n      case 'ArrowLeft':\n        e.preventDefault();\n        if (hasChildren && isOpen) setOpen(node.id, false);\n        else if (flat.parentId) focusItem(flat.parentId);\n        break;\n      case 'Home':\n        e.preventDefault();\n        focusItem(visible[0]?.node.id);\n        break;\n      case 'End':\n        e.preventDefault();\n        focusItem(visible[visible.length - 1]?.node.id);\n        break;\n      case 'Enter':\n      case ' ':\n        e.preventDefault();\n        select(node.id);\n        if (hasChildren) setOpen(node.id, !isOpen);\n        break;\n      default:\n        return;\n    }\n    e.stopPropagation();\n  };\n\n  function renderNode(\n    node: TreeNode,\n    level: number,\n    setSize: number,\n    posInSet: number,\n    parentId: string | null,\n  ): ReactNode {\n    const hasChildren = !!node.children;\n    const isOpen = expanded.has(node.id);\n    const isSelected = selected === node.id;\n    const DefaultIcon = hasChildren ? (isOpen ? FolderOpen : Folder) : FileIcon;\n    const flat: FlatNode = { node, level, setSize, posInSet, parentId };\n\n    return (\n      <li\n        key={node.id}\n        ref={(el) => {\n          if (el) itemRefs.current.set(node.id, el);\n          else itemRefs.current.delete(node.id);\n        }}\n        role=\"treeitem\"\n        aria-expanded={hasChildren ? isOpen : undefined}\n        aria-selected={isSelected}\n        aria-level={level}\n        aria-setsize={setSize}\n        aria-posinset={posInSet}\n        tabIndex={tabStopId === node.id ? 0 : -1}\n        onFocus={(e) => {\n          if (e.target === e.currentTarget) setFocusedId(node.id);\n        }}\n        onKeyDown={(e) => {\n          if (e.target === e.currentTarget) handleKeyDown(e, flat);\n        }}\n        onClick={(e) => {\n          e.stopPropagation();\n          setFocusedId(node.id);\n          select(node.id);\n          if (hasChildren) setOpen(node.id, !isOpen);\n        }}\n        className=\"outline-none\"\n      >\n        <div\n          style={{ paddingLeft: `${level - 1 + 0.5}rem` }}\n          className={cn(\n            'flex w-full cursor-default items-center gap-1.5 rounded-md py-1 pr-2 text-left text-sm',\n            'hover:bg-background-muted',\n            '[li:focus-visible>&]:ring-ring [li:focus-visible>&]:ring-offset-background [li:focus-visible>&]:ring-2 [li:focus-visible>&]:ring-offset-1',\n            isSelected && 'bg-accent-soft text-foreground',\n          )}\n        >\n          {hasChildren ? (\n            <ChevronRight\n              className={cn(\n                'text-foreground-subtle size-3.5 shrink-0 transition-transform',\n                isOpen && 'rotate-90',\n              )}\n              aria-hidden\n            />\n          ) : (\n            <span className=\"w-3.5 shrink-0\" aria-hidden />\n          )}\n          {node.icon ?? (\n            <DefaultIcon className=\"text-foreground-muted size-4 shrink-0\" aria-hidden />\n          )}\n          <span\n            className=\"truncate\"\n            title={typeof node.label === 'string' ? node.label : undefined}\n          >\n            {node.label}\n          </span>\n        </div>\n        {hasChildren && isOpen && (\n          <ul role=\"group\" className=\"mt-0.5\">\n            {node.children!.map((c, i) =>\n              renderNode(c, level + 1, node.children!.length, i + 1, node.id),\n            )}\n          </ul>\n        )}\n      </li>\n    );\n  }\n\n  return (\n    <ul\n      ref={ref}\n      role=\"tree\"\n      aria-label={ariaLabel ?? (ariaLabelledby ? undefined : strings.tree.label)}\n      aria-labelledby={ariaLabelledby}\n      className={cn('flex flex-col gap-0.5', className)}\n      {...rest}\n    >\n      {data.map((n, i) => renderNode(n, 1, data.length, i + 1, null))}\n    </ul>\n  );\n});\nTree.displayName = 'Tree';\n"],"names":["Tree","forwardRef","props","ref","data","defaultExpanded","expandedProp","onExpandedChange","selectedId","selectedProp","defaultSelected","onSelect","onSelectedChange","className","ariaLabel","ariaLabelledby","rest","isControlled","strings","useStrings","internalExpanded","setInternalExpanded","useState","expanded","useMemo","internalSelected","setInternalSelected","selected","focusedId","setFocusedId","itemRefs","useRef","setExpanded","useCallback","next","setOpen","id","open","select","visible","out","walk","nodes","level","parentId","node","i","tabStopId","v","_a","focusItem","handleKeyDown","flat","hasChildren","isOpen","index","_b","_c","_d","_e","renderNode","setSize","posInSet","isSelected","DefaultIcon","FolderOpen","Folder","FileIcon","jsxs","el","e","cn","jsx","ChevronRight","c","n"],"mappings":"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"}

package/dist-lib/hooks/use-debounce.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Returns `value` after it has stopped changing for `delay` ms. Use for
+ * search inputs that drive a query (URL or fetch) without firing per keystroke.
+ *
+ * @example
+ *   const [q, setQ] = useState('');
+ *   const debouncedQ = useDebounce(q); // 300ms
+ *   useEffect(() => { fetchRows(debouncedQ); }, [debouncedQ]);
+ */
+export declare function useDebounce<T>(value: T, delay?: number): T;
+/**
+ * Stable callback that runs `fn` once `delay` ms have passed since the last
+ * call. Always invokes the latest `fn`; pending calls are dropped on unmount.
+ *
+ * @example
+ *   const save = useDebouncedCallback((draft: string) => api.save(draft), 500);
+ *   <Textarea onChange={(e) => save(e.target.value)} />
+ */
+export declare function useDebouncedCallback<A extends unknown[]>(fn: (...args: A) => void, delay?: number): (...args: A) => void;

package/dist-lib/hooks/use-debounce.js

@@ -0,0 +1,36 @@
+"use client";
+import { useState as i, useEffect as c, useRef as o, useCallback as s } from "react";
+function w(t, n = 300) {
+  const [r, e] = i(t);
+  return c(() => {
+    if (n <= 0) {
+      e(t);
+      return;
+    }
+    const u = window.setTimeout(() => e(t), n);
+    return () => window.clearTimeout(u);
+  }, [t, n]), r;
+}
+function f(t, n = 300) {
+  const r = o(t), e = o(null);
+  return c(() => {
+    r.current = t;
+  }, [t]), c(
+    () => () => {
+      e.current !== null && window.clearTimeout(e.current);
+    },
+    []
+  ), s(
+    (...u) => {
+      e.current !== null && window.clearTimeout(e.current), e.current = window.setTimeout(() => {
+        e.current = null, r.current(...u);
+      }, n);
+    },
+    [n]
+  );
+}
+export {
+  w as useDebounce,
+  f as useDebouncedCallback
+};
+//# sourceMappingURL=use-debounce.js.map

package/dist-lib/hooks/use-debounce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-debounce.js","sources":["../../src/hooks/use-debounce.ts"],"sourcesContent":["'use client';\n\nimport { useCallback, useEffect, useRef, useState } from 'react';\n\n/**\n * Returns `value` after it has stopped changing for `delay` ms. Use for\n * search inputs that drive a query (URL or fetch) without firing per keystroke.\n *\n * @example\n *   const [q, setQ] = useState('');\n *   const debouncedQ = useDebounce(q); // 300ms\n *   useEffect(() => { fetchRows(debouncedQ); }, [debouncedQ]);\n */\nexport function useDebounce<T>(value: T, delay = 300): T {\n  const [debounced, setDebounced] = useState(value);\n  useEffect(() => {\n    if (delay <= 0) {\n      setDebounced(value);\n      return;\n    }\n    const t = window.setTimeout(() => setDebounced(value), delay);\n    return () => window.clearTimeout(t);\n  }, [value, delay]);\n  return debounced;\n}\n\n/**\n * Stable callback that runs `fn` once `delay` ms have passed since the last\n * call. Always invokes the latest `fn`; pending calls are dropped on unmount.\n *\n * @example\n *   const save = useDebouncedCallback((draft: string) => api.save(draft), 500);\n *   <Textarea onChange={(e) => save(e.target.value)} />\n */\nexport function useDebouncedCallback<A extends unknown[]>(\n  fn: (...args: A) => void,\n  delay = 300,\n): (...args: A) => void {\n  const fnRef = useRef(fn);\n  const timer = useRef<number | null>(null);\n  useEffect(() => {\n    fnRef.current = fn;\n  }, [fn]);\n  useEffect(\n    () => () => {\n      if (timer.current !== null) window.clearTimeout(timer.current);\n    },\n    [],\n  );\n  return useCallback(\n    (...args: A) => {\n      if (timer.current !== null) window.clearTimeout(timer.current);\n      timer.current = window.setTimeout(() => {\n        timer.current = null;\n        fnRef.current(...args);\n      }, delay);\n    },\n    [delay],\n  );\n}\n"],"names":["useDebounce","value","delay","debounced","setDebounced","useState","useEffect","t","useDebouncedCallback","fn","fnRef","useRef","timer","useCallback","args"],"mappings":";;AAaO,SAASA,EAAeC,GAAUC,IAAQ,KAAQ;AACvD,QAAM,CAACC,GAAWC,CAAY,IAAIC,EAASJ,CAAK;AAChD,SAAAK,EAAU,MAAM;AACd,QAAIJ,KAAS,GAAG;AACd,MAAAE,EAAaH,CAAK;AAClB;AAAA,IACF;AACA,UAAMM,IAAI,OAAO,WAAW,MAAMH,EAAaH,CAAK,GAAGC,CAAK;AAC5D,WAAO,MAAM,OAAO,aAAaK,CAAC;AAAA,EACpC,GAAG,CAACN,GAAOC,CAAK,CAAC,GACVC;AACT;AAUO,SAASK,EACdC,GACAP,IAAQ,KACc;AACtB,QAAMQ,IAAQC,EAAOF,CAAE,GACjBG,IAAQD,EAAsB,IAAI;AACxC,SAAAL,EAAU,MAAM;AACd,IAAAI,EAAM,UAAUD;AAAA,EAClB,GAAG,CAACA,CAAE,CAAC,GACPH;AAAA,IACE,MAAM,MAAM;AACV,MAAIM,EAAM,YAAY,QAAM,OAAO,aAAaA,EAAM,OAAO;AAAA,IAC/D;AAAA,IACA,CAAA;AAAA,EAAC,GAEIC;AAAA,IACL,IAAIC,MAAY;AACd,MAAIF,EAAM,YAAY,QAAM,OAAO,aAAaA,EAAM,OAAO,GAC7DA,EAAM,UAAU,OAAO,WAAW,MAAM;AACtC,QAAAA,EAAM,UAAU,MAChBF,EAAM,QAAQ,GAAGI,CAAI;AAAA,MACvB,GAAGZ,CAAK;AAAA,IACV;AAAA,IACA,CAACA,CAAK;AAAA,EAAA;AAEV;"}

package/dist-lib/hooks/use-delayed-loading.d.ts

@@ -0,0 +1,21 @@
+export interface DelayedLoadingOptions {
+    /**
+     * Once `true`, the value holds for at least this many ms even if `ms`
+     * changes, so a placeholder that did appear never flickers away. Default 500.
+     */
+    minVisible?: number;
+}
+/**
+ * Returns `false` until `ms` has elapsed, then `true`. Gate skeletons and
+ * spinners behind it so sub-300ms loads never flash a placeholder.
+ * `ms <= 0` returns `true` immediately (and synchronously on first render).
+ *
+ * Once shown, the value stays `true` for `minVisible` ms (default 500). Keep
+ * the gated component mounted for that window on the consumer side too —
+ * unmounting it early defeats the hold.
+ *
+ * @example
+ *   const showSkeleton = useDelayedLoading(300);
+ *   if (isLoading) return showSkeleton ? <Skeleton /> : null;
+ */
+export declare function useDelayedLoading(ms: number, { minVisible }?: DelayedLoadingOptions): boolean;

package/dist-lib/hooks/use-delayed-loading.js

@@ -0,0 +1,20 @@
+"use client";
+import { useState as f, useRef as i, useEffect as l } from "react";
+function d(t, { minVisible: u = 500 } = {}) {
+  const [a, n] = f(t <= 0), e = i(t <= 0 ? Date.now() : null);
+  return l(() => {
+    const c = () => {
+      e.current = Date.now(), n(!0);
+    };
+    if (t <= 0) {
+      e.current ?? (e.current = Date.now()), n(!0);
+      return;
+    }
+    const r = e.current === null ? 0 : Math.max(0, u - (Date.now() - e.current)), o = [];
+    return r > 0 ? o.push(window.setTimeout(() => n(!1), r)) : n(!1), o.push(window.setTimeout(c, r + t)), () => o.forEach((s) => window.clearTimeout(s));
+  }, [t, u]), a;
+}
+export {
+  d as useDelayedLoading
+};
+//# sourceMappingURL=use-delayed-loading.js.map

package/dist-lib/hooks/use-delayed-loading.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-delayed-loading.js","sources":["../../src/hooks/use-delayed-loading.ts"],"sourcesContent":["'use client';\n\nimport { useEffect, useRef, useState } from 'react';\n\nexport interface DelayedLoadingOptions {\n  /**\n   * Once `true`, the value holds for at least this many ms even if `ms`\n   * changes, so a placeholder that did appear never flickers away. Default 500.\n   */\n  minVisible?: number;\n}\n\n/**\n * Returns `false` until `ms` has elapsed, then `true`. Gate skeletons and\n * spinners behind it so sub-300ms loads never flash a placeholder.\n * `ms <= 0` returns `true` immediately (and synchronously on first render).\n *\n * Once shown, the value stays `true` for `minVisible` ms (default 500). Keep\n * the gated component mounted for that window on the consumer side too —\n * unmounting it early defeats the hold.\n *\n * @example\n *   const showSkeleton = useDelayedLoading(300);\n *   if (isLoading) return showSkeleton ? <Skeleton /> : null;\n */\nexport function useDelayedLoading(\n  ms: number,\n  { minVisible = 500 }: DelayedLoadingOptions = {},\n): boolean {\n  const [ready, setReady] = useState(ms <= 0);\n  const shownAt = useRef<number | null>(ms <= 0 ? Date.now() : null);\n\n  useEffect(() => {\n    const show = () => {\n      shownAt.current = Date.now();\n      setReady(true);\n    };\n    if (ms <= 0) {\n      shownAt.current ??= Date.now();\n      setReady(true);\n      return;\n    }\n    // Respect the minimum-visible window before hiding again.\n    const hold =\n      shownAt.current === null ? 0 : Math.max(0, minVisible - (Date.now() - shownAt.current));\n    const timers: number[] = [];\n    if (hold > 0) {\n      timers.push(window.setTimeout(() => setReady(false), hold));\n    } else {\n      setReady(false);\n    }\n    timers.push(window.setTimeout(show, hold + ms));\n    return () => timers.forEach((t) => window.clearTimeout(t));\n  }, [ms, minVisible]);\n\n  return ready;\n}\n"],"names":["useDelayedLoading","ms","minVisible","ready","setReady","useState","shownAt","useRef","useEffect","show","hold","timers","t"],"mappings":";;AAyBO,SAASA,EACdC,GACA,EAAE,YAAAC,IAAa,IAAA,IAA+B,CAAA,GACrC;AACT,QAAM,CAACC,GAAOC,CAAQ,IAAIC,EAASJ,KAAM,CAAC,GACpCK,IAAUC,EAAsBN,KAAM,IAAI,KAAK,IAAA,IAAQ,IAAI;AAEjE,SAAAO,EAAU,MAAM;AACd,UAAMC,IAAO,MAAM;AACjB,MAAAH,EAAQ,UAAU,KAAK,IAAA,GACvBF,EAAS,EAAI;AAAA,IACf;AACA,QAAIH,KAAM,GAAG;AACX,MAAAK,EAAQ,YAARA,EAAQ,UAAY,KAAK,IAAA,IACzBF,EAAS,EAAI;AACb;AAAA,IACF;AAEA,UAAMM,IACJJ,EAAQ,YAAY,OAAO,IAAI,KAAK,IAAI,GAAGJ,KAAc,KAAK,IAAA,IAAQI,EAAQ,QAAQ,GAClFK,IAAmB,CAAA;AACzB,WAAID,IAAO,IACTC,EAAO,KAAK,OAAO,WAAW,MAAMP,EAAS,EAAK,GAAGM,CAAI,CAAC,IAE1DN,EAAS,EAAK,GAEhBO,EAAO,KAAK,OAAO,WAAWF,GAAMC,IAAOT,CAAE,CAAC,GACvC,MAAMU,EAAO,QAAQ,CAACC,MAAM,OAAO,aAAaA,CAAC,CAAC;AAAA,EAC3D,GAAG,CAACX,GAAIC,CAAU,CAAC,GAEZC;AACT;"}

package/dist-lib/hooks/use-field-ids.d.ts

@@ -0,0 +1,30 @@
+export interface FieldIds {
+    /** Id for the control itself (`<input id>` / `<label htmlFor>`). */
+    fieldId: string;
+    /** Id for the description / helper text element (`<fieldId>-desc`). */
+    helperId: string;
+    /** Id for the validation message element. */
+    errorId: string;
+    /**
+     * `aria-describedby` value computed from what actually renders — the error
+     * wins over the helper; `undefined` when neither is present.
+     */
+    describedBy: string | undefined;
+}
+/**
+ * Shared id wiring for form fields: one stable id for the control plus
+ * derived helper / error ids, and an `aria-describedby` that only references
+ * elements that exist. Pass a consumer `id` to keep `<label htmlFor>` in sync.
+ *
+ * @example
+ *   const { fieldId, helperId, errorId, describedBy } = useFieldIds(id, {
+ *     hasHelper: Boolean(helperText),
+ *     hasError: Boolean(error),
+ *   });
+ */
+export declare function useFieldIds(id?: string, present?: {
+    hasHelper?: boolean;
+    hasError?: boolean;
+    /** Consumer-supplied `aria-describedby` ids, appended after the helper / error id. */
+    extra?: string;
+}): FieldIds;

package/dist-lib/hooks/use-field-ids.js

@@ -0,0 +1,18 @@
+"use client";
+import { useId as n } from "react";
+function l(s, o = {}) {
+  const i = n(), r = s ?? i, e = `${r}-desc`, d = `${r}-error`, t = [
+    o.hasError ? d : o.hasHelper ? e : void 0,
+    o.extra
+  ].filter(Boolean);
+  return {
+    fieldId: r,
+    helperId: e,
+    errorId: d,
+    describedBy: t.length ? t.join(" ") : void 0
+  };
+}
+export {
+  l as useFieldIds
+};
+//# sourceMappingURL=use-field-ids.js.map

package/dist-lib/hooks/use-field-ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-field-ids.js","sources":["../../src/hooks/use-field-ids.ts"],"sourcesContent":["'use client';\n\nimport { useId } from 'react';\n\nexport interface FieldIds {\n  /** Id for the control itself (`<input id>` / `<label htmlFor>`). */\n  fieldId: string;\n  /** Id for the description / helper text element (`<fieldId>-desc`). */\n  helperId: string;\n  /** Id for the validation message element. */\n  errorId: string;\n  /**\n   * `aria-describedby` value computed from what actually renders — the error\n   * wins over the helper; `undefined` when neither is present.\n   */\n  describedBy: string | undefined;\n}\n\n/**\n * Shared id wiring for form fields: one stable id for the control plus\n * derived helper / error ids, and an `aria-describedby` that only references\n * elements that exist. Pass a consumer `id` to keep `<label htmlFor>` in sync.\n *\n * @example\n *   const { fieldId, helperId, errorId, describedBy } = useFieldIds(id, {\n *     hasHelper: Boolean(helperText),\n *     hasError: Boolean(error),\n *   });\n */\nexport function useFieldIds(\n  id?: string,\n  present: {\n    hasHelper?: boolean;\n    hasError?: boolean;\n    /** Consumer-supplied `aria-describedby` ids, appended after the helper / error id. */\n    extra?: string;\n  } = {},\n): FieldIds {\n  const autoId = useId();\n  const fieldId = id ?? autoId;\n  const helperId = `${fieldId}-desc`;\n  const errorId = `${fieldId}-error`;\n  const parts = [\n    present.hasError ? errorId : present.hasHelper ? helperId : undefined,\n    present.extra,\n  ].filter(Boolean);\n  return {\n    fieldId,\n    helperId,\n    errorId,\n    describedBy: parts.length ? parts.join(' ') : undefined,\n  };\n}\n"],"names":["useFieldIds","id","present","autoId","useId","fieldId","helperId","errorId","parts"],"mappings":";;AA6BO,SAASA,EACdC,GACAC,IAKI,IACM;AACV,QAAMC,IAASC,EAAA,GACTC,IAAUJ,KAAME,GAChBG,IAAW,GAAGD,CAAO,SACrBE,IAAU,GAAGF,CAAO,UACpBG,IAAQ;AAAA,IACZN,EAAQ,WAAWK,IAAUL,EAAQ,YAAYI,IAAW;AAAA,IAC5DJ,EAAQ;AAAA,EAAA,EACR,OAAO,OAAO;AAChB,SAAO;AAAA,IACL,SAAAG;AAAA,IACA,UAAAC;AAAA,IACA,SAAAC;AAAA,IACA,aAAaC,EAAM,SAASA,EAAM,KAAK,GAAG,IAAI;AAAA,EAAA;AAElD;"}

package/dist-lib/hooks/use-media-query.d.ts

@@ -1,5 +1,7 @@
 /**
- * Subscribe to a CSS media query. SSR-safe — returns `false` on the server.
+ * Subscribe to a CSS media query. SSR- and hydration-safe: the server snapshot
+ * is always `false`, and the client re-renders with the real value after
+ * hydration instead of producing a markup mismatch.
  *
  * @example
  *   const isDesktop = useMediaQuery('(min-width: 1024px)');

package/dist-lib/hooks/use-media-query.js

@@ -0,0 +1,22 @@
+"use client";
+import { useCallback as o, useSyncExternalStore as d } from "react";
+function r(e) {
+  const i = o(
+    (n) => {
+      if (typeof window > "u" || !window.matchMedia) return () => {
+      };
+      const t = window.matchMedia(e);
+      return t.addEventListener("change", n), () => t.removeEventListener("change", n);
+    },
+    [e]
+  );
+  return d(i, () => typeof window < "u" && window.matchMedia ? window.matchMedia(e).matches : !1, () => !1);
+}
+function c() {
+  return r("(prefers-reduced-motion: reduce)");
+}
+export {
+  r as useMediaQuery,
+  c as usePrefersReducedMotion
+};
+//# sourceMappingURL=use-media-query.js.map

package/dist-lib/hooks/use-media-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-media-query.js","sources":["../../src/hooks/use-media-query.ts"],"sourcesContent":["'use client';\n\nimport { useCallback, useSyncExternalStore } from 'react';\n\n/**\n * Subscribe to a CSS media query. SSR- and hydration-safe: the server snapshot\n * is always `false`, and the client re-renders with the real value after\n * hydration instead of producing a markup mismatch.\n *\n * @example\n *   const isDesktop = useMediaQuery('(min-width: 1024px)');\n */\nexport function useMediaQuery(query: string): boolean {\n  const subscribe = useCallback(\n    (onChange: () => void) => {\n      if (typeof window === 'undefined' || !window.matchMedia) return () => {};\n      const list = window.matchMedia(query);\n      list.addEventListener('change', onChange);\n      return () => list.removeEventListener('change', onChange);\n    },\n    [query],\n  );\n  const getSnapshot = () =>\n    typeof window !== 'undefined' && window.matchMedia ? window.matchMedia(query).matches : false;\n  return useSyncExternalStore(subscribe, getSnapshot, () => false);\n}\n\n/** Convenience: respect `prefers-reduced-motion`. */\nexport function usePrefersReducedMotion(): boolean {\n  return useMediaQuery('(prefers-reduced-motion: reduce)');\n}\n"],"names":["useMediaQuery","query","subscribe","useCallback","onChange","list","useSyncExternalStore","usePrefersReducedMotion"],"mappings":";;AAYO,SAASA,EAAcC,GAAwB;AACpD,QAAMC,IAAYC;AAAA,IAChB,CAACC,MAAyB;AACxB,UAAI,OAAO,SAAW,OAAe,CAAC,OAAO,mBAAmB,MAAM;AAAA,MAAC;AACvE,YAAMC,IAAO,OAAO,WAAWJ,CAAK;AACpC,aAAAI,EAAK,iBAAiB,UAAUD,CAAQ,GACjC,MAAMC,EAAK,oBAAoB,UAAUD,CAAQ;AAAA,IAC1D;AAAA,IACA,CAACH,CAAK;AAAA,EAAA;AAIR,SAAOK,EAAqBJ,GAFR,MAClB,OAAO,SAAW,OAAe,OAAO,aAAa,OAAO,WAAWD,CAAK,EAAE,UAAU,IACtC,MAAM,EAAK;AACjE;AAGO,SAASM,IAAmC;AACjD,SAAOP,EAAc,kCAAkC;AACzD;"}

package/dist-lib/hooks/use-modifier-key.d.ts

@@ -0,0 +1,13 @@
+/** True on macOS / iOS / iPadOS, where the command modifier is ⌘. */
+export declare function isApplePlatform(): boolean;
+export interface ModifierKey {
+    /** Glyph for `<Kbd>`: `⌘` on Apple platforms, `Ctrl` elsewhere. */
+    symbol: '⌘' | 'Ctrl';
+    /** Spoken/long form for aria-labels and tooltips: `Cmd` / `Ctrl`. */
+    label: 'Cmd' | 'Ctrl';
+}
+/**
+ * Platform-correct command modifier for shortcut hints (⌘K vs Ctrl K).
+ * Defaults to Ctrl until mounted so server output is deterministic.
+ */
+export declare function useModifierKey(): ModifierKey;

package/dist-lib/hooks/use-modifier-key.js

@@ -0,0 +1,19 @@
+"use client";
+import { useState as o, useEffect as r } from "react";
+function n() {
+  var a;
+  if (typeof navigator > "u") return !1;
+  const e = navigator, t = ((a = e.userAgentData) == null ? void 0 : a.platform) ?? e.platform ?? "";
+  return /mac|iphone|ipad|ipod/i.test(t) || /Mac OS X/i.test(e.userAgent ?? "");
+}
+function s() {
+  const [e, t] = o(!1);
+  return r(() => {
+    t(n());
+  }, []), e ? { symbol: "⌘", label: "Cmd" } : { symbol: "Ctrl", label: "Ctrl" };
+}
+export {
+  n as isApplePlatform,
+  s as useModifierKey
+};
+//# sourceMappingURL=use-modifier-key.js.map

package/dist-lib/hooks/use-modifier-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-modifier-key.js","sources":["../../src/hooks/use-modifier-key.ts"],"sourcesContent":["'use client';\n\nimport { useEffect, useState } from 'react';\n\n/** True on macOS / iOS / iPadOS, where the command modifier is ⌘. */\nexport function isApplePlatform(): boolean {\n  if (typeof navigator === 'undefined') return false;\n  const nav = navigator as Navigator & { userAgentData?: { platform?: string } };\n  const platform = nav.userAgentData?.platform ?? nav.platform ?? '';\n  return /mac|iphone|ipad|ipod/i.test(platform) || /Mac OS X/i.test(nav.userAgent ?? '');\n}\n\nexport interface ModifierKey {\n  /** Glyph for `<Kbd>`: `⌘` on Apple platforms, `Ctrl` elsewhere. */\n  symbol: '⌘' | 'Ctrl';\n  /** Spoken/long form for aria-labels and tooltips: `Cmd` / `Ctrl`. */\n  label: 'Cmd' | 'Ctrl';\n}\n\n/**\n * Platform-correct command modifier for shortcut hints (⌘K vs Ctrl K).\n * Defaults to Ctrl until mounted so server output is deterministic.\n */\nexport function useModifierKey(): ModifierKey {\n  const [apple, setApple] = useState(false);\n  useEffect(() => {\n    setApple(isApplePlatform());\n  }, []);\n  return apple ? { symbol: '⌘', label: 'Cmd' } : { symbol: 'Ctrl', label: 'Ctrl' };\n}\n"],"names":["isApplePlatform","nav","platform","_a","useModifierKey","apple","setApple","useState","useEffect"],"mappings":";;AAKO,SAASA,IAA2B;;AACzC,MAAI,OAAO,YAAc,IAAa,QAAO;AAC7C,QAAMC,IAAM,WACNC,MAAWC,IAAAF,EAAI,kBAAJ,gBAAAE,EAAmB,aAAYF,EAAI,YAAY;AAChE,SAAO,wBAAwB,KAAKC,CAAQ,KAAK,YAAY,KAAKD,EAAI,aAAa,EAAE;AACvF;AAaO,SAASG,IAA8B;AAC5C,QAAM,CAACC,GAAOC,CAAQ,IAAIC,EAAS,EAAK;AACxC,SAAAC,EAAU,MAAM;AACd,IAAAF,EAASN,GAAiB;AAAA,EAC5B,GAAG,CAAA,CAAE,GACEK,IAAQ,EAAE,QAAQ,KAAK,OAAO,MAAA,IAAU,EAAE,QAAQ,QAAQ,OAAO,OAAA;AAC1E;"}

package/dist-lib/hooks/use-strings.d.ts

@@ -0,0 +1,5 @@
+import { UiStrings } from '../lib/strings.js';
+/** Resolved (complete) strings for the current subtree. */
+export declare const StringsContext: import('react').Context<UiStrings>;
+/** Read the library strings — falls back to the English defaults without a provider. */
+export declare function useStrings(): UiStrings;