@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/lib/use-hotkeys.js

@@ -0,0 +1,221 @@
+import * as React from "react";
+import { useLatest } from "./use-controllable-state.js";
+const KEY_ALIASES = {
+    esc: "escape",
+    return: "enter",
+    space: " ",
+    spacebar: " ",
+    del: "delete",
+    up: "arrowup",
+    down: "arrowdown",
+    left: "arrowleft",
+    right: "arrowright",
+    plus: "+",
+    comma: ",",
+    period: ".",
+    slash: "/",
+    cmd: "meta",
+    command: "meta",
+    option: "alt",
+    opt: "alt",
+    control: "ctrl",
+};
+/** `true` on macOS, iOS and iPadOS. Always `false` on the server. */
+export function isApplePlatform() {
+    if (typeof navigator === "undefined")
+        return false;
+    const nav = navigator;
+    const platform = nav.userAgentData?.platform || nav.platform || nav.userAgent || "";
+    return /mac|iphone|ipad|ipod/i.test(platform);
+}
+const noopSubscribe = () => () => { };
+/**
+ * Platform check that is safe for SSR: renders as non-Apple ("Ctrl") on the server and during
+ * hydration, then switches to "⌘" on Apple devices without a hydration mismatch.
+ */
+export function useIsMac() {
+    return React.useSyncExternalStore(noopSubscribe, isApplePlatform, () => false);
+}
+/** Parses `"mod+shift+k"` into its parts. */
+export function parseShortcut(shortcut) {
+    const parts = shortcut
+        .toLowerCase()
+        .split(/\+(?!$)/) // keep a trailing "+" as the key ("mod++")
+        .map((p) => p.trim())
+        .filter(Boolean);
+    const out = { key: "", mod: false, ctrl: false, meta: false, alt: false, shift: false };
+    for (const raw of parts) {
+        const p = KEY_ALIASES[raw] ?? raw;
+        if (p === "mod")
+            out.mod = true;
+        else if (p === "ctrl")
+            out.ctrl = true;
+        else if (p === "meta")
+            out.meta = true;
+        else if (p === "alt")
+            out.alt = true;
+        else if (p === "shift")
+            out.shift = true;
+        else
+            out.key = p;
+    }
+    return out;
+}
+const isLetterOrDigit = (k) => /^[a-z0-9]$/.test(k);
+/** Does this keyboard event match the shortcut? */
+export function matchesShortcut(event, shortcut, isMac = isApplePlatform()) {
+    const s = typeof shortcut === "string" ? parseShortcut(shortcut) : shortcut;
+    if (!s.key)
+        return false;
+    const wantMeta = s.meta || (s.mod && isMac);
+    const wantCtrl = s.ctrl || (s.mod && !isMac);
+    if (event.metaKey !== wantMeta || event.ctrlKey !== wantCtrl || event.altKey !== s.alt)
+        return false;
+    const key = (event.key ?? "").toLowerCase();
+    const code = event.code ?? "";
+    // Shift is implied for symbols ("?" is shift+/ on US layouts) — only enforce it for letters, digits and named keys.
+    const symbol = s.key.length === 1 && !isLetterOrDigit(s.key);
+    if (!symbol && event.shiftKey !== s.shift)
+        return false;
+    if (key === s.key)
+        return true;
+    // Layout-independent fallback (Option on macOS changes event.key: alt+k → "˚").
+    if (isLetterOrDigit(s.key))
+        return code === `Key${s.key.toUpperCase()}` || code === `Digit${s.key}`;
+    return false;
+}
+const MAC_SYMBOLS = {
+    mod: "⌘",
+    meta: "⌘",
+    ctrl: "⌃",
+    alt: "⌥",
+    shift: "⇧",
+    enter: "↩",
+    backspace: "⌫",
+    delete: "⌦",
+    escape: "Esc",
+    tab: "⇥",
+    arrowup: "↑",
+    arrowdown: "↓",
+    arrowleft: "←",
+    arrowright: "→",
+    " ": "Space",
+    pageup: "PgUp",
+    pagedown: "PgDn",
+};
+const PC_NAMES = {
+    mod: "Ctrl",
+    meta: "Win",
+    ctrl: "Ctrl",
+    alt: "Alt",
+    shift: "Shift",
+    enter: "Enter",
+    backspace: "Backspace",
+    delete: "Del",
+    escape: "Esc",
+    tab: "Tab",
+    arrowup: "↑",
+    arrowdown: "↓",
+    arrowleft: "←",
+    arrowright: "→",
+    " ": "Space",
+    pageup: "PgUp",
+    pagedown: "PgDn",
+};
+/**
+ * Canonical key tokens of a shortcut in display order, e.g. `"mod+shift+k"` → `["mod", "shift", "k"]`
+ * (Apple order is ⌃ ⌥ ⇧ ⌘; elsewhere Ctrl, Alt, Shift). Kbd uses this to render one keycap per key.
+ */
+export function shortcutKeys(shortcut, isMac = false) {
+    const s = parseShortcut(shortcut);
+    const mods = [];
+    const push = (cond, k) => cond && mods.push(k);
+    if (isMac) {
+        push(s.ctrl, "ctrl");
+        push(s.alt, "alt");
+        push(s.shift, "shift");
+        push(s.meta || s.mod, "mod");
+    }
+    else {
+        push(s.ctrl || s.mod, "ctrl");
+        push(s.meta, "meta");
+        push(s.alt, "alt");
+        push(s.shift, "shift");
+    }
+    return s.key ? [...mods, s.key] : mods;
+}
+/** Display text for one key token (`"mod"` → `"⌘"` / `"Ctrl"`, `"k"` → `"K"`). */
+export function formatKey(key, isMac = false) {
+    const k = KEY_ALIASES[key.toLowerCase()] ?? key.toLowerCase();
+    const table = isMac ? MAC_SYMBOLS : PC_NAMES;
+    if (table[k])
+        return table[k];
+    if (/^f\d{1,2}$/.test(k))
+        return k.toUpperCase();
+    return k.length === 1 ? k.toUpperCase() : k.charAt(0).toUpperCase() + k.slice(1);
+}
+/**
+ * Human-readable shortcut: `"mod+k"` → `"⌘K"` on Apple platforms, `"Ctrl+K"` elsewhere.
+ * Pass `isMac` explicitly in render code (from `useIsMac()`) so SSR and client agree.
+ */
+export function formatShortcut(shortcut, options = {}) {
+    const isMac = options.isMac ?? isApplePlatform();
+    const keys = shortcutKeys(shortcut, isMac).map((k) => formatKey(k, isMac));
+    return keys.join(options.separator ?? (isMac ? "" : "+"));
+}
+function isTypingTarget(el) {
+    if (!el || !el.tagName)
+        return false;
+    const t = el;
+    const tag = t.tagName;
+    if (tag === "TEXTAREA" || tag === "SELECT")
+        return true;
+    if (tag === "INPUT") {
+        const type = t.type;
+        return !["checkbox", "radio", "button", "submit", "reset", "range", "color", "file"].includes(type);
+    }
+    return t.isContentEditable;
+}
+/**
+ * Registers global (or element-scoped) keyboard shortcuts.
+ *
+ * ```ts
+ * useHotkeys("mod+k", () => setOpen(true));
+ * useHotkeys(["j", "down"], next, { enabled: listFocused });
+ * ```
+ *
+ * IME composition is ignored. The kit itself only registers `mod+k`, `mod+\` and opt-in layout
+ * shortcuts; everything else belongs to the app (avoid clashing with browsers and rich-text editors).
+ */
+export function useHotkeys(shortcuts, handler, options = {}) {
+    const { enabled = true, preventDefault = true, enableOnFormFields, target, event = "keydown", ignoreRepeat = false } = options;
+    const handlerRef = useLatest(handler);
+    const list = Array.isArray(shortcuts) ? shortcuts : [shortcuts];
+    const key = list.join("|");
+    React.useEffect(() => {
+        if (!enabled || typeof document === "undefined")
+            return;
+        const parsed = key.split("|").map(parseShortcut);
+        const el = target && "current" in target ? target.current : target;
+        const node = el ?? document;
+        const mac = isApplePlatform();
+        const listener = (e) => {
+            const ke = e;
+            if (ke.isComposing || ke.key === "Process" || (ignoreRepeat && ke.repeat))
+                return;
+            for (const s of parsed) {
+                if (!matchesShortcut(ke, s, mac))
+                    continue;
+                const withModifier = s.mod || s.ctrl || s.meta || s.alt;
+                if (isTypingTarget(ke.target) && !(enableOnFormFields ?? withModifier))
+                    return;
+                if (preventDefault)
+                    ke.preventDefault();
+                handlerRef.current(ke);
+                return;
+            }
+        };
+        node.addEventListener(event, listener);
+        return () => node.removeEventListener(event, listener);
+    }, [key, enabled, preventDefault, enableOnFormFields, target, event, ignoreRepeat, handlerRef]);
+}

package/dist/lib/use-hover-intent.d.ts

@@ -0,0 +1,44 @@
+import * as React from "react";
+export interface UseHoverIntentOptions {
+    /** Controlled open state. */
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** ms the pointer must rest on the trigger before opening. Default 150. */
+    openDelay?: number;
+    /** ms after leaving before closing. Default 200. */
+    closeDelay?: number;
+    /** Keep open while the pointer travels from the trigger towards the content ("safe triangle"). Default `true`. */
+    safeTriangle?: boolean;
+    /** Also open on keyboard focus. Default `true`. */
+    openOnFocus?: boolean;
+    disabled?: boolean;
+}
+/**
+ * Hover-to-open with delays and a safe triangle — for sidebar flyouts, hover cards and
+ * navigation menus. Touch pointers are ignored (tap the trigger instead).
+ *
+ * ```tsx
+ * const hover = useHoverIntent({ openDelay: 120 });
+ * <button {...hover.triggerProps}>Posts</button>
+ * {hover.open && <div ref={hover.contentRef} {...hover.contentProps}>…</div>}
+ * ```
+ */
+export declare function useHoverIntent(options?: UseHoverIntentOptions): {
+    open: boolean;
+    setOpen: (next: boolean | ((prev: boolean) => boolean)) => void;
+    /** Cancel any pending open/close. */
+    cancel: () => void;
+    /** Attach to the floating element so the safe triangle can be computed. */
+    contentRef: (node: HTMLElement | null) => void;
+    triggerProps: {
+        onPointerEnter: (e: React.PointerEvent) => void;
+        onPointerLeave: (e: React.PointerEvent) => void;
+        onFocus: () => void;
+        onBlur: (e: React.FocusEvent) => void;
+    };
+    contentProps: {
+        onPointerEnter: () => void;
+        onPointerLeave: (e: React.PointerEvent) => void;
+    };
+};

package/dist/lib/use-hover-intent.js

@@ -0,0 +1,119 @@
+import * as React from "react";
+import { useControllableState, useLatest } from "./use-controllable-state.js";
+function insideTriangle(p, a, b, c) {
+    const s = (p1, p2, p3) => (p1.x - p3.x) * (p2.y - p3.y) - (p2.x - p3.x) * (p1.y - p3.y);
+    const d1 = s(p, a, b);
+    const d2 = s(p, b, c);
+    const d3 = s(p, c, a);
+    const neg = d1 < 0 || d2 < 0 || d3 < 0;
+    const pos = d1 > 0 || d2 > 0 || d3 > 0;
+    return !(neg && pos);
+}
+/** The two corners of `rect` that face `from`, forming a triangle with it. */
+function facingCorners(from, r) {
+    if (from.x <= r.left)
+        return [{ x: r.left, y: r.top }, { x: r.left, y: r.bottom }];
+    if (from.x >= r.right)
+        return [{ x: r.right, y: r.top }, { x: r.right, y: r.bottom }];
+    if (from.y <= r.top)
+        return [{ x: r.left, y: r.top }, { x: r.right, y: r.top }];
+    return [{ x: r.left, y: r.bottom }, { x: r.right, y: r.bottom }];
+}
+/**
+ * Hover-to-open with delays and a safe triangle — for sidebar flyouts, hover cards and
+ * navigation menus. Touch pointers are ignored (tap the trigger instead).
+ *
+ * ```tsx
+ * const hover = useHoverIntent({ openDelay: 120 });
+ * <button {...hover.triggerProps}>Posts</button>
+ * {hover.open && <div ref={hover.contentRef} {...hover.contentProps}>…</div>}
+ * ```
+ */
+export function useHoverIntent(options = {}) {
+    const { openDelay = 150, closeDelay = 200, safeTriangle = true, openOnFocus = true, disabled = false } = options;
+    const [open, setOpen] = useControllableState({ value: options.open, defaultValue: options.defaultOpen ?? false, onChange: options.onOpenChange, name: "useHoverIntent" });
+    const timer = React.useRef(undefined);
+    const contentEl = React.useRef(null);
+    const moveCleanup = React.useRef(null);
+    const setOpenRef = useLatest(setOpen);
+    const clear = React.useCallback(() => {
+        if (timer.current)
+            clearTimeout(timer.current);
+        timer.current = undefined;
+    }, []);
+    const stopTracking = React.useCallback(() => {
+        moveCleanup.current?.();
+        moveCleanup.current = null;
+    }, []);
+    const schedule = React.useCallback((next, delay) => {
+        clear();
+        if (delay <= 0)
+            setOpenRef.current(next);
+        else
+            timer.current = setTimeout(() => setOpenRef.current(next), delay);
+    }, [clear, setOpenRef]);
+    React.useEffect(() => () => (clear(), stopTracking()), [clear, stopTracking]);
+    const isMouse = (e) => e.pointerType === "mouse" || e.pointerType === "pen";
+    const onTriggerLeave = (e) => {
+        if (!isMouse(e) || disabled)
+            return;
+        const el = contentEl.current;
+        if (!safeTriangle || !el || !open)
+            return schedule(false, closeDelay);
+        const exit = { x: e.clientX, y: e.clientY };
+        const [b, c] = facingCorners(exit, el.getBoundingClientRect());
+        stopTracking();
+        const onMove = (ev) => {
+            const p = { x: ev.clientX, y: ev.clientY };
+            if (insideTriangle(p, exit, b, c))
+                schedule(false, closeDelay * 2);
+            else {
+                stopTracking();
+                schedule(false, closeDelay);
+            }
+        };
+        document.addEventListener("pointermove", onMove);
+        moveCleanup.current = () => document.removeEventListener("pointermove", onMove);
+        schedule(false, closeDelay * 2);
+    };
+    return {
+        open,
+        setOpen,
+        /** Cancel any pending open/close. */
+        cancel: clear,
+        /** Attach to the floating element so the safe triangle can be computed. */
+        contentRef: React.useCallback((node) => {
+            contentEl.current = node;
+        }, []),
+        triggerProps: {
+            onPointerEnter: (e) => {
+                if (!isMouse(e) || disabled)
+                    return;
+                stopTracking();
+                schedule(true, open ? 0 : openDelay);
+            },
+            onPointerLeave: onTriggerLeave,
+            onFocus: () => {
+                if (openOnFocus && !disabled)
+                    schedule(true, 0);
+            },
+            onBlur: (e) => {
+                if (!openOnFocus)
+                    return;
+                if (contentEl.current?.contains(e.relatedTarget))
+                    return;
+                schedule(false, closeDelay);
+            },
+        },
+        contentProps: {
+            onPointerEnter: () => {
+                stopTracking();
+                clear();
+            },
+            onPointerLeave: (e) => {
+                if (isMouse(e))
+                    schedule(false, closeDelay);
+            },
+        },
+    };
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Subscribes to a CSS media query.
+ *
+ * Returns `undefined` during server rendering and hydration, so CSS decides the first paint
+ * and there is no hydration mismatch. Render a CSS-only fallback while it is `undefined`.
+ *
+ * ```ts
+ * const isDesktop = useMediaQuery("(min-width: 1024px)"); // undefined | boolean
+ * ```
+ */
+export declare function useMediaQuery(query: string): boolean | undefined;
+/** Tailwind's default breakpoints, for `useBreakpoint`. */
+export declare const breakpoints: {
+    readonly sm: 640;
+    readonly md: 768;
+    readonly lg: 1024;
+    readonly xl: 1280;
+    readonly "2xl": 1536;
+};
+/** `true` when the viewport is at least the given Tailwind breakpoint; `undefined` during SSR. */
+export declare function useBreakpoint(bp: keyof typeof breakpoints): boolean | undefined;

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

@@ -0,0 +1,28 @@
+import * as React from "react";
+/**
+ * Subscribes to a CSS media query.
+ *
+ * Returns `undefined` during server rendering and hydration, so CSS decides the first paint
+ * and there is no hydration mismatch. Render a CSS-only fallback while it is `undefined`.
+ *
+ * ```ts
+ * const isDesktop = useMediaQuery("(min-width: 1024px)"); // undefined | boolean
+ * ```
+ */
+export function useMediaQuery(query) {
+    const subscribe = React.useCallback((notify) => {
+        if (typeof window === "undefined" || !window.matchMedia)
+            return () => { };
+        const mql = window.matchMedia(query);
+        mql.addEventListener?.("change", notify);
+        return () => mql.removeEventListener?.("change", notify);
+    }, [query]);
+    const getSnapshot = () => (typeof window !== "undefined" && window.matchMedia ? window.matchMedia(query).matches : undefined);
+    return React.useSyncExternalStore(subscribe, getSnapshot, () => undefined);
+}
+/** Tailwind's default breakpoints, for `useBreakpoint`. */
+export const breakpoints = { sm: 640, md: 768, lg: 1024, xl: 1280, "2xl": 1536 };
+/** `true` when the viewport is at least the given Tailwind breakpoint; `undefined` during SSR. */
+export function useBreakpoint(bp) {
+    return useMediaQuery(`(min-width: ${breakpoints[bp]}px)`);
+}

package/dist/lib/use-reduced-motion.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `true` when the user asked the OS to reduce motion. `false` during SSR (animations are
+ * CSS-driven and already respect the media query; use this only for JS-driven motion such as
+ * carousels, chart transitions or `scrollIntoView({ behavior })`).
+ */
+export declare function useReducedMotion(): boolean;
+/** `true` when the user asked the OS to reduce transparency (glass falls back to opaque). */
+export declare function useReducedTransparency(): boolean;

package/dist/lib/use-reduced-motion.js

@@ -0,0 +1,13 @@
+import { useMediaQuery } from "./use-media-query.js";
+/**
+ * `true` when the user asked the OS to reduce motion. `false` during SSR (animations are
+ * CSS-driven and already respect the media query; use this only for JS-driven motion such as
+ * carousels, chart transitions or `scrollIntoView({ behavior })`).
+ */
+export function useReducedMotion() {
+    return useMediaQuery("(prefers-reduced-motion: reduce)") ?? false;
+}
+/** `true` when the user asked the OS to reduce transparency (glass falls back to opaque). */
+export function useReducedTransparency() {
+    return useMediaQuery("(prefers-reduced-transparency: reduce)") ?? false;
+}

package/dist/lib/use-tree.d.ts

@@ -0,0 +1,153 @@
+import * as React from "react";
+/**
+ * One node of a hierarchy: a category, a department, a folder, a page. Shared by Tree view,
+ * Tree select and (later) Sortable tree.
+ */
+export interface TreeNode {
+    id: string;
+    label: string;
+    /** Known children. Leave out and set `hasChildren` to load them lazily. */
+    children?: TreeNode[];
+    /** Children exist but are loaded on first expand (`loadChildren`). */
+    hasChildren?: boolean;
+    disabled?: boolean;
+    icon?: React.ReactNode;
+    /** Trailing count or badge (Tree view). */
+    badge?: React.ReactNode;
+    /** Secondary text, searchable too ("12 products", a code). */
+    description?: string;
+    /** Extra search terms (SKU, slug, cost centre code). */
+    keywords?: string[];
+}
+/** What a fully-checked branch yields as the checked value. */
+export type TreeCheckValueMode = "all" | "parent" | "leaf";
+export type TreeCheckedState = boolean | "mixed";
+/** One visible row of the flattened tree. */
+export interface TreeItemState {
+    node: TreeNode;
+    id: string;
+    /** 1-based depth (`aria-level`). */
+    level: number;
+    parentId: string | null;
+    /** 1-based position among its siblings (`aria-posinset`). */
+    posinset: number;
+    /** Number of siblings (`aria-setsize`). */
+    setsize: number;
+    /** Has (or may lazily have) children. */
+    hasChildren: boolean;
+    expanded: boolean;
+    loading: boolean;
+    /** Load error message (lazy children). */
+    error: string | null;
+    checked: TreeCheckedState;
+    selected: boolean;
+    disabled: boolean;
+    /** Label matches the current filter (rows kept only as ancestors are `false`). */
+    match: boolean;
+    /** Is the last of its siblings (indent guides stop here). */
+    last: boolean;
+    /** For each ancestor level (1…level-1): does that ancestor have a following sibling? Draws guides. */
+    guides: boolean[];
+}
+export interface UseTreeOptions {
+    nodes: TreeNode[];
+    /** Expanded ids (controlled). */
+    expanded?: string[];
+    defaultExpanded?: string[];
+    onExpandedChange?: (ids: string[]) => void;
+    /** Loads the children of a node with `hasChildren` on first expand. Abortable. */
+    loadChildren?: (node: TreeNode, signal: AbortSignal) => Promise<TreeNode[]>;
+    /** Keeps matches and their ancestors, auto-expanding the ancestors. Locale-folded (İ/ı, accents). */
+    filter?: string;
+    locale?: string;
+    /** `"single"` / `"multiple"` selection (`aria-selected`). Default `"none"`. */
+    selectionMode?: "none" | "single" | "multiple";
+    selected?: string[];
+    defaultSelected?: string[];
+    onSelectedChange?: (ids: string[]) => void;
+    /** Can this node be selected? (e.g. leaves only). Default: any enabled node. */
+    isSelectable?: (node: TreeNode, hasChildren: boolean) => boolean;
+    /** Turns on checkboxes (`aria-checked`). */
+    checkable?: boolean;
+    checked?: string[];
+    defaultChecked?: string[];
+    onCheckedChange?: (ids: string[]) => void;
+    /** Checking a parent checks its descendants; a parent is checked when all children are (tri-state). Default `true`. */
+    cascade?: boolean;
+    /** With `cascade`: which ids the checked value lists. Default `"all"`. */
+    checkValueMode?: TreeCheckValueMode;
+    /** Enter / double click on a row. */
+    onAction?: (node: TreeNode) => void;
+    /** Swaps ←/→. */
+    dir?: "ltr" | "rtl";
+    /** Called before focusing a row that may not be rendered yet (virtual lists scroll it into view). */
+    scrollToIndex?: (index: number) => void;
+}
+export interface UseTreeReturn {
+    /** Visible rows in order — render them flat, inside one `role="tree"` element. */
+    items: TreeItemState[];
+    /** Every known node by id (including loaded children). */
+    getNode: (id: string) => TreeNode | undefined;
+    getParentId: (id: string) => string | null;
+    /** Ancestors + the node, root first. */
+    getPath: (id: string) => TreeNode[];
+    getChildren: (node: TreeNode) => TreeNode[] | undefined;
+    isExpanded: (id: string) => boolean;
+    toggleExpanded: (id: string, open?: boolean) => void;
+    expandAll: () => void;
+    collapseAll: () => void;
+    expandedIds: string[];
+    selectedIds: string[];
+    select: (id: string) => void;
+    checkedIds: string[];
+    getChecked: (id: string) => TreeCheckedState;
+    toggleChecked: (id: string, next?: boolean) => void;
+    /** Retry a failed lazy load. */
+    reload: (id: string) => void;
+    focusedId: string | null;
+    setFocusedId: (id: string | null) => void;
+    /** Focus a row (scrolling it into view first in virtual lists). */
+    focusItem: (id: string) => void;
+    /** Spread on the `role="tree"` element (ref, role, keyboard). */
+    getTreeProps: () => {
+        ref: React.RefCallback<HTMLElement>;
+        role: "tree";
+        "aria-multiselectable"?: boolean;
+        onKeyDown: (e: React.KeyboardEvent<HTMLElement>) => void;
+    };
+    /** Spread on each row. */
+    getItemProps: (item: TreeItemState) => {
+        role: "treeitem";
+        id?: string;
+        tabIndex: number;
+        "aria-level": number;
+        "aria-posinset": number;
+        "aria-setsize": number;
+        "aria-expanded"?: boolean;
+        "aria-selected"?: boolean;
+        "aria-checked"?: boolean | "mixed";
+        "aria-disabled"?: boolean;
+        "aria-busy"?: boolean;
+        "data-tree-id": string;
+        "data-state"?: "open" | "closed";
+        onFocus: (e: React.FocusEvent<HTMLElement>) => void;
+    };
+    /** Number of filter matches (for "N results" announcements). */
+    matchCount: number;
+    /** Is a filter active? */
+    filtering: boolean;
+}
+/**
+ * The shared tree model behind Tree view and Tree select: flattened visible rows, expand state,
+ * single/multiple selection, tri-state checks with cascade, lazy children (with abort and retry),
+ * locale-folded filtering that keeps ancestors, and the full WAI-ARIA treeview keyboard
+ * (↑ ↓ → ← Home End `*`, type-ahead, Space, Enter) with a roving tabindex.
+ *
+ * ```tsx
+ * const tree = useTree({ nodes, defaultExpanded: ["clothing"], checkable: true });
+ * <div {...tree.getTreeProps()} aria-label="Categories">
+ *   {tree.items.map((item) => <div key={item.id} {...tree.getItemProps(item)}>{item.node.label}</div>)}
+ * </div>
+ * ```
+ */
+export declare function useTree(options: UseTreeOptions): UseTreeReturn;