@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/lib/use-async-list.js

@@ -0,0 +1,119 @@
+"use client";
+import * as React from "react";
+import { useLatest } from "./use-controllable-state.js";
+const normalize = (r) => (Array.isArray(r) ? { items: r, cursor: null } : { items: r.items, cursor: r.cursor ?? null });
+const isAbort = (e) => (e instanceof DOMException || e instanceof Error) && e.name === "AbortError";
+/**
+ * Debounced, abortable, paged loading for search lists: Combobox, Tag input suggestions,
+ * record and user pickers.
+ *
+ * ```tsx
+ * const list = useAsyncList({
+ *   query,
+ *   load: async (q, signal, cursor) => {
+ *     const res = await fetch(`/api/contacts?q=${encodeURIComponent(q)}&after=${cursor ?? ""}`, { signal });
+ *     return res.json(); // { items, cursor }
+ *   },
+ * });
+ * list.items; list.loading; list.loadMore();
+ * ```
+ *
+ * - Typing fast only sends the last query; a new query aborts the request in flight.
+ * - Results are cached per query, so deleting a character shows the earlier list instantly.
+ */
+export function useAsyncList({ load, query, debounce = 200, enabled = true, cache = true, minQueryLength = 0 }) {
+    const loadRef = useLatest(load);
+    const cacheRef = React.useRef(new Map());
+    const firstRef = React.useRef(true);
+    const moreRef = React.useRef(null);
+    const [reloadToken, setReloadToken] = React.useState(0);
+    const [state, setState] = React.useState({ items: [], cursor: null, loading: Boolean(load && enabled), loadingMore: false, error: null, loadedQuery: null });
+    const hasLoader = Boolean(load);
+    const active = hasLoader && enabled && query.length >= minQueryLength;
+    React.useEffect(() => {
+        if (!active) {
+            setState((s) => (s.loading || s.loadingMore ? { ...s, loading: false, loadingMore: false } : s));
+            return;
+        }
+        const cached = cache ? cacheRef.current.get(query) : undefined;
+        if (cached) {
+            setState({ items: cached.items, cursor: cached.cursor, loading: false, loadingMore: false, error: null, loadedQuery: query });
+            return;
+        }
+        moreRef.current?.abort();
+        setState((s) => ({ ...s, loading: true, loadingMore: false }));
+        const controller = new AbortController();
+        const delay = firstRef.current ? 0 : debounce;
+        firstRef.current = false;
+        const timer = setTimeout(() => {
+            const fn = loadRef.current;
+            if (!fn)
+                return;
+            fn(query, controller.signal)
+                .then((res) => {
+                if (controller.signal.aborted)
+                    return;
+                const entry = normalize(res);
+                if (cache)
+                    cacheRef.current.set(query, entry);
+                setState({ items: entry.items, cursor: entry.cursor, loading: false, loadingMore: false, error: null, loadedQuery: query });
+            })
+                .catch((error) => {
+                if (controller.signal.aborted || isAbort(error))
+                    return;
+                setState((s) => ({ ...s, loading: false, error }));
+            });
+        }, delay);
+        return () => {
+            clearTimeout(timer);
+            controller.abort();
+        };
+    }, [active, query, debounce, cache, reloadToken, loadRef]);
+    const stateRef = useLatest(state);
+    const loadMore = React.useCallback(() => {
+        const s = stateRef.current;
+        const fn = loadRef.current;
+        if (!fn || !s.cursor || s.loading || s.loadingMore || s.loadedQuery === null)
+            return;
+        const q = s.loadedQuery;
+        const cursor = s.cursor;
+        const controller = new AbortController();
+        moreRef.current = controller;
+        setState((prev) => ({ ...prev, loadingMore: true }));
+        fn(q, controller.signal, cursor)
+            .then((res) => {
+            if (controller.signal.aborted)
+                return;
+            const page = normalize(res);
+            setState((prev) => {
+                if (prev.loadedQuery !== q)
+                    return prev;
+                const next = { items: [...prev.items, ...page.items], cursor: page.cursor };
+                if (cache)
+                    cacheRef.current.set(q, next);
+                return { ...prev, ...next, loadingMore: false, error: null };
+            });
+        })
+            .catch((error) => {
+            if (controller.signal.aborted || isAbort(error))
+                return;
+            setState((prev) => ({ ...prev, loadingMore: false, error }));
+        });
+    }, [cache, loadRef, stateRef]);
+    const reload = React.useCallback(() => {
+        cacheRef.current.delete(query);
+        firstRef.current = true;
+        setReloadToken((n) => n + 1);
+    }, [query]);
+    React.useEffect(() => () => moreRef.current?.abort(), []);
+    return {
+        items: active ? state.items : [],
+        loading: active && state.loading,
+        loadingMore: active && state.loadingMore,
+        error: active ? state.error : null,
+        hasMore: active && state.cursor !== null,
+        loadedQuery: active ? state.loadedQuery : null,
+        loadMore,
+        reload,
+    };
+}

package/dist/lib/use-container-width.d.ts

@@ -0,0 +1,19 @@
+export interface ContainerSize {
+    width: number | undefined;
+    height: number | undefined;
+}
+/**
+ * Measures an element with `ResizeObserver` (content box, rAF-throttled).
+ * Width is `undefined` until the first measurement — render the CSS layout (`@container`) first
+ * and use this only where JS needs the number (charts, virtualised lists, overflow menus).
+ *
+ * ```tsx
+ * const { ref, width } = useContainerWidth<HTMLDivElement>();
+ * <div ref={ref}>{width && width < 480 ? <Compact /> : <Full />}</div>
+ * ```
+ */
+export declare function useContainerWidth<T extends Element = HTMLDivElement>(): {
+    ref: (node: T | null) => void;
+    width: number | undefined;
+    height: number | undefined;
+};

package/dist/lib/use-container-width.js

@@ -0,0 +1,39 @@
+import * as React from "react";
+/**
+ * Measures an element with `ResizeObserver` (content box, rAF-throttled).
+ * Width is `undefined` until the first measurement — render the CSS layout (`@container`) first
+ * and use this only where JS needs the number (charts, virtualised lists, overflow menus).
+ *
+ * ```tsx
+ * const { ref, width } = useContainerWidth<HTMLDivElement>();
+ * <div ref={ref}>{width && width < 480 ? <Compact /> : <Full />}</div>
+ * ```
+ */
+export function useContainerWidth() {
+    const [size, setSize] = React.useState({ width: undefined, height: undefined });
+    const observer = React.useRef(null);
+    const frame = React.useRef(0);
+    const ref = React.useCallback((node) => {
+        observer.current?.disconnect();
+        cancelAnimationFrame(frame.current);
+        if (!node || typeof ResizeObserver === "undefined")
+            return;
+        const ro = new ResizeObserver((entries) => {
+            const entry = entries[0];
+            if (!entry)
+                return;
+            const box = entry.contentBoxSize?.[0];
+            const width = box ? box.inlineSize : entry.contentRect.width;
+            const height = box ? box.blockSize : entry.contentRect.height;
+            cancelAnimationFrame(frame.current);
+            frame.current = requestAnimationFrame(() => setSize((prev) => (prev.width === width && prev.height === height ? prev : { width, height })));
+        });
+        ro.observe(node);
+        observer.current = ro;
+    }, []);
+    React.useEffect(() => () => {
+        observer.current?.disconnect();
+        cancelAnimationFrame(frame.current);
+    }, []);
+    return { ref, width: size.width, height: size.height };
+}

package/dist/lib/use-controllable-state.d.ts

@@ -0,0 +1,33 @@
+import * as React from "react";
+/** `useLayoutEffect` on the client, a no-op on the server (no SSR warning). */
+export declare const useIsomorphicLayoutEffect: typeof React.useLayoutEffect;
+/**
+ * Keeps a ref pointing at the latest value. Use it to call the newest callback from an
+ * effect or event handler without re-subscribing.
+ */
+export declare function useLatest<T>(value: T): React.RefObject<T>;
+/** A stable function identity that always calls the latest `fn`. */
+export declare function useEventCallback<A extends unknown[], R>(fn: ((...args: A) => R) | undefined): (...args: A) => R | undefined;
+export interface UseControllableStateOptions<T> {
+    /** Controlled value. The state is controlled whenever this is not `undefined`. */
+    value?: T;
+    /** Initial value for the uncontrolled case. */
+    defaultValue: T | (() => T);
+    /** Called with the next value whenever it changes (controlled and uncontrolled). */
+    onChange?: (value: T) => void;
+    /** Component name used in the dev warning when switching controlled ↔ uncontrolled. */
+    name?: string;
+}
+/**
+ * State that can be controlled (`value` + `onChange`) or uncontrolled (`defaultValue`).
+ * The kit's single implementation of the Radix contract (`value` / `defaultValue` / `onValueChange`).
+ *
+ * ```ts
+ * const [open, setOpen] = useControllableState({ value: props.open, defaultValue: props.defaultOpen ?? false, onChange: props.onOpenChange });
+ * ```
+ *
+ * - Empty controlled value is `null` (single) or `[]` (multi) — never `undefined`, which means "uncontrolled".
+ * - `onChange` fires only when the value actually changes (`Object.is`).
+ * - The setter accepts an updater function. If `T` itself is a function type, wrap it: `set(() => fn)`.
+ */
+export declare function useControllableState<T>({ value, defaultValue, onChange, name }: UseControllableStateOptions<T>): readonly [T, (next: T | ((prev: T) => T)) => void];

package/dist/lib/use-controllable-state.js

@@ -0,0 +1,56 @@
+import * as React from "react";
+/** `useLayoutEffect` on the client, a no-op on the server (no SSR warning). */
+export const useIsomorphicLayoutEffect = typeof window !== "undefined" ? React.useLayoutEffect : React.useEffect;
+/**
+ * Keeps a ref pointing at the latest value. Use it to call the newest callback from an
+ * effect or event handler without re-subscribing.
+ */
+export function useLatest(value) {
+    const ref = React.useRef(value);
+    useIsomorphicLayoutEffect(() => {
+        ref.current = value;
+    });
+    return ref;
+}
+/** A stable function identity that always calls the latest `fn`. */
+export function useEventCallback(fn) {
+    const ref = useLatest(fn);
+    return React.useCallback((...args) => ref.current?.(...args), [ref]);
+}
+/**
+ * State that can be controlled (`value` + `onChange`) or uncontrolled (`defaultValue`).
+ * The kit's single implementation of the Radix contract (`value` / `defaultValue` / `onValueChange`).
+ *
+ * ```ts
+ * const [open, setOpen] = useControllableState({ value: props.open, defaultValue: props.defaultOpen ?? false, onChange: props.onOpenChange });
+ * ```
+ *
+ * - Empty controlled value is `null` (single) or `[]` (multi) — never `undefined`, which means "uncontrolled".
+ * - `onChange` fires only when the value actually changes (`Object.is`).
+ * - The setter accepts an updater function. If `T` itself is a function type, wrap it: `set(() => fn)`.
+ */
+export function useControllableState({ value, defaultValue, onChange, name = "Component" }) {
+    const isControlled = value !== undefined;
+    const [internal, setInternal] = React.useState(defaultValue);
+    const current = (isControlled ? value : internal);
+    const currentRef = React.useRef(current);
+    const controlledRef = React.useRef(isControlled);
+    const onChangeRef = useLatest(onChange);
+    currentRef.current = current;
+    if (process.env.NODE_ENV !== "production" && controlledRef.current !== isControlled) {
+        console.warn(`${name} is changing from ${controlledRef.current ? "controlled" : "uncontrolled"} to ${isControlled ? "controlled" : "uncontrolled"}. ` +
+            "Decide between using a controlled or uncontrolled value for the lifetime of the component.");
+    }
+    controlledRef.current = isControlled;
+    const setValue = React.useCallback((next) => {
+        const resolved = typeof next === "function" ? next(currentRef.current) : next;
+        if (Object.is(resolved, currentRef.current))
+            return;
+        if (!controlledRef.current) {
+            currentRef.current = resolved;
+            setInternal(resolved);
+        }
+        onChangeRef.current?.(resolved);
+    }, [onChangeRef]);
+    return [current, setValue];
+}

package/dist/lib/use-edge-fade.d.ts

@@ -0,0 +1,13 @@
+import * as React from "react";
+/**
+ * Keeps `data-fade-start` / `data-fade-end` on a scrolling element while content is hidden on that
+ * side. Pair with `data-edge-fade="x" | "y"` (styles/navigation.css) for a cheap mask-image fade —
+ * no blur, no extra DOM. Works in RTL (`scrollLeft` is negative there).
+ *
+ * ```tsx
+ * const ref = React.useRef<HTMLDivElement>(null);
+ * useEdgeFade(ref, "x");
+ * <div ref={ref} data-edge-fade="x" className="overflow-x-auto">…</div>
+ * ```
+ */
+export declare function useEdgeFade(ref: React.RefObject<HTMLElement | null>, axis: "x" | "y", enabled?: boolean): void;

package/dist/lib/use-edge-fade.js

@@ -0,0 +1,43 @@
+import { useIsomorphicLayoutEffect } from "./use-controllable-state.js";
+/**
+ * Keeps `data-fade-start` / `data-fade-end` on a scrolling element while content is hidden on that
+ * side. Pair with `data-edge-fade="x" | "y"` (styles/navigation.css) for a cheap mask-image fade —
+ * no blur, no extra DOM. Works in RTL (`scrollLeft` is negative there).
+ *
+ * ```tsx
+ * const ref = React.useRef<HTMLDivElement>(null);
+ * useEdgeFade(ref, "x");
+ * <div ref={ref} data-edge-fade="x" className="overflow-x-auto">…</div>
+ * ```
+ */
+export function useEdgeFade(ref, axis, enabled = true) {
+    useIsomorphicLayoutEffect(() => {
+        const el = ref.current;
+        if (!el || !enabled)
+            return;
+        const update = () => {
+            const pos = Math.abs(axis === "x" ? el.scrollLeft : el.scrollTop);
+            const max = axis === "x" ? el.scrollWidth - el.clientWidth : el.scrollHeight - el.clientHeight;
+            toggle(el, "data-fade-start", pos > 1);
+            toggle(el, "data-fade-end", max - pos > 1);
+        };
+        update();
+        el.addEventListener("scroll", update, { passive: true });
+        const ro = typeof ResizeObserver !== "undefined" ? new ResizeObserver(update) : undefined;
+        ro?.observe(el);
+        if (el.firstElementChild)
+            ro?.observe(el.firstElementChild);
+        return () => {
+            el.removeEventListener("scroll", update);
+            ro?.disconnect();
+            el.removeAttribute("data-fade-start");
+            el.removeAttribute("data-fade-end");
+        };
+    }, [ref, axis, enabled]);
+}
+function toggle(el, attr, on) {
+    if (on)
+        el.setAttribute(attr, "");
+    else
+        el.removeAttribute(attr);
+}

package/dist/lib/use-formatted-input.d.ts

@@ -0,0 +1,69 @@
+import * as React from "react";
+/**
+ * Caret-preserving formatting engine behind CurrencyInput, PhoneInput, IbanInput, IdInput and
+ * FormattedInput.
+ *
+ * The model: a **display** string (what the `<input>` shows, with separators and grouping) and a
+ * locale-free **raw** value (decimal string, E.164, compact IBAN). Formatting may add or remove
+ * literal characters (spaces, group separators, brackets), so the caret is mapped by counting
+ * *significant* characters (`accept`) before it: if the caret sat after the 7th digit before
+ * formatting, it sits after the 7th digit after formatting. Backspace / Delete on a literal skip
+ * over it and remove the significant character next to it, so separators never "trap" the caret.
+ *
+ * ```ts
+ * const f = useFormattedInput({
+ *   value, defaultValue, onValueChange,
+ *   accept: (ch) => /\d/.test(ch),
+ *   format: (typed) => typed.replace(/\D/g, "").replace(/(\d{4})(?=\d)/g, "$1 "),
+ *   parse: (display) => display.replace(/\D/g, "") || null,
+ *   toDisplay: (raw) => raw ?? "",
+ * });
+ * <input ref={f.ref} {...f.inputProps} />
+ * ```
+ */
+export interface UseFormattedInputOptions {
+    /** Controlled raw value (`null` = empty). `undefined` = uncontrolled. */
+    value?: string | null;
+    defaultValue?: string | null;
+    /** Called with the new raw value whenever it changes. */
+    onValueChange?: (raw: string | null, display: string) => void;
+    /** Significant characters (kept by `format`, counted for the caret). */
+    accept: (ch: string) => boolean;
+    /** Typed text → display text. Must keep the order of accepted characters; may drop extras. */
+    format: (typed: string) => string;
+    /** Display text → raw value (`null` when empty / not a value yet). */
+    parse: (display: string) => string | null;
+    /** Raw value → display text (initial value, controlled updates). */
+    toDisplay: (raw: string | null) => string;
+    /** Final polish on blur (pad decimals, full international format…). Default: none. */
+    formatOnBlur?: (display: string) => string;
+    /** Raw values compare equal (avoid resetting the display for "1250.5" vs "1250.50"). Default `===`. */
+    isSameValue?: (a: string | null, b: string | null) => boolean;
+}
+export interface FormattedInputState {
+    /** Attach to the `<input>`. */
+    ref: React.RefObject<HTMLInputElement | null>;
+    display: string;
+    raw: string | null;
+    /** Spread on the `<input>` (compose your own handlers around them if needed). */
+    inputProps: {
+        value: string;
+        onChange: React.ChangeEventHandler<HTMLInputElement>;
+        onKeyDown: React.KeyboardEventHandler<HTMLInputElement>;
+        onBlur: React.FocusEventHandler<HTMLInputElement>;
+    };
+    /** Replaces the current selection with `text` and formats (custom key handling, paste parsing). */
+    insert: (text: string) => void;
+    /** Sets the display directly (formatted with `format`), keeping the caret at the end. */
+    setDisplay: (display: string) => void;
+    /** Formats `typed` as if the user produced it with the caret at `caret`. */
+    update: (typed: string, caret: number) => void;
+}
+/** Number of characters accepted by `accept` in `s`. */
+export declare function countAccepted(s: string, accept: (ch: string) => boolean): number;
+/**
+ * Index just after the `n`-th accepted character of `s` (0 when `n` is 0; the end when `s`
+ * has fewer). Works on UTF-16 indexes (all masks in the kit are BMP characters).
+ */
+export declare function caretAfterAccepted(s: string, n: number, accept: (ch: string) => boolean): number;
+export declare function useFormattedInput(options: UseFormattedInputOptions): FormattedInputState;

package/dist/lib/use-formatted-input.js

@@ -0,0 +1,152 @@
+"use client";
+import * as React from "react";
+import { useIsomorphicLayoutEffect, useLatest } from "./use-controllable-state.js";
+/** Number of characters accepted by `accept` in `s`. */
+export function countAccepted(s, accept) {
+    let n = 0;
+    for (const ch of s)
+        if (accept(ch))
+            n++;
+    return n;
+}
+/**
+ * Index just after the `n`-th accepted character of `s` (0 when `n` is 0; the end when `s`
+ * has fewer). Works on UTF-16 indexes (all masks in the kit are BMP characters).
+ */
+export function caretAfterAccepted(s, n, accept) {
+    if (n <= 0)
+        return 0;
+    let seen = 0;
+    for (let i = 0; i < s.length; i++) {
+        if (accept(s[i])) {
+            seen++;
+            if (seen === n)
+                return i + 1;
+        }
+    }
+    return s.length;
+}
+export function useFormattedInput(options) {
+    const opts = useLatest(options);
+    const { value } = options;
+    const controlled = value !== undefined;
+    const ref = React.useRef(null);
+    const [display, setDisplayState] = React.useState(() => options.toDisplay(controlled ? value ?? null : options.defaultValue ?? null));
+    const displayRef = React.useRef(display);
+    displayRef.current = display;
+    const lastRaw = React.useRef(controlled ? value ?? null : options.defaultValue ?? null);
+    const pendingCaret = React.useRef(null);
+    // Controlled value changed from outside → re-derive the display.
+    const same = options.isSameValue ?? ((a, b) => a === b);
+    if (controlled && !same(value ?? null, lastRaw.current)) {
+        lastRaw.current = value ?? null;
+        const next = options.toDisplay(value ?? null);
+        if (next !== display) {
+            displayRef.current = next;
+            setDisplayState(next);
+        }
+    }
+    useIsomorphicLayoutEffect(() => {
+        const el = ref.current;
+        const caret = pendingCaret.current;
+        if (el && caret != null && el.ownerDocument.activeElement === el) {
+            el.setSelectionRange(caret, caret);
+        }
+        pendingCaret.current = null;
+    });
+    const commit = React.useCallback((next, caret) => {
+        const o = opts.current;
+        const el = ref.current;
+        if (el) {
+            // Write synchronously so React's controlled-value restore never moves the caret.
+            if (el.value !== next)
+                el.value = next;
+            if (caret != null && el.ownerDocument.activeElement === el)
+                el.setSelectionRange(caret, caret);
+        }
+        pendingCaret.current = caret;
+        displayRef.current = next;
+        setDisplayState(next);
+        const raw = o.parse(next);
+        if (!(o.isSameValue ?? ((a, b) => a === b))(raw, lastRaw.current)) {
+            lastRaw.current = raw;
+            o.onValueChange?.(raw, next);
+        }
+    }, [opts]);
+    const apply = React.useCallback((typed, caret) => {
+        const o = opts.current;
+        const n = countAccepted(typed.slice(0, caret), o.accept);
+        const next = o.format(typed);
+        commit(next, caretAfterAccepted(next, n, o.accept));
+    }, [opts, commit]);
+    const onChange = React.useCallback((e) => {
+        const el = e.currentTarget;
+        apply(el.value, el.selectionStart ?? el.value.length);
+    }, [apply]);
+    const onKeyDown = React.useCallback((e) => {
+        if (e.defaultPrevented || e.altKey || e.metaKey || e.ctrlKey)
+            return;
+        if (e.key !== "Backspace" && e.key !== "Delete")
+            return;
+        const el = e.currentTarget;
+        const start = el.selectionStart ?? 0;
+        const end = el.selectionEnd ?? start;
+        if (start !== end)
+            return;
+        const s = el.value;
+        const accept = opts.current.accept;
+        if (e.key === "Backspace") {
+            if (start === 0 || accept(s[start - 1]))
+                return;
+            // A literal before the caret: delete the significant character before it instead.
+            let j = start - 1;
+            while (j >= 0 && !accept(s[j]))
+                j--;
+            e.preventDefault();
+            if (j < 0) {
+                el.setSelectionRange(0, 0);
+                return;
+            }
+            apply(s.slice(0, j) + s.slice(j + 1), j);
+        }
+        else {
+            if (start >= s.length || accept(s[start]))
+                return;
+            let k = start;
+            while (k < s.length && !accept(s[k]))
+                k++;
+            e.preventDefault();
+            if (k >= s.length)
+                return;
+            apply(s.slice(0, k) + s.slice(k + 1), start);
+        }
+    }, [opts, apply]);
+    const onBlur = React.useCallback(() => {
+        const o = opts.current;
+        if (!o.formatOnBlur)
+            return;
+        const next = o.formatOnBlur(displayRef.current);
+        if (next !== displayRef.current)
+            commit(next, null);
+    }, [opts, commit]);
+    const insert = React.useCallback((text) => {
+        const el = ref.current;
+        const s = el?.value ?? displayRef.current;
+        const start = el?.selectionStart ?? s.length;
+        const end = el?.selectionEnd ?? start;
+        apply(s.slice(0, start) + text + s.slice(end), start + text.length);
+    }, [apply]);
+    const setDisplay = React.useCallback((d) => {
+        const next = opts.current.format(d);
+        commit(next, next.length);
+    }, [opts, commit]);
+    return {
+        ref,
+        display,
+        raw: lastRaw.current,
+        inputProps: { value: display, onChange, onKeyDown, onBlur },
+        insert,
+        setDisplay,
+        update: apply,
+    };
+}

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

@@ -0,0 +1,80 @@
+import * as React from "react";
+/**
+ * Shortcut strings are `+`-separated, case-insensitive: `"mod+k"`, `"shift+?"`, `"esc"`, `"mod+shift+p"`.
+ * `mod` is ⌘ on Apple platforms and Ctrl elsewhere. Several shortcuts: pass an array.
+ *
+ * Key aliases: `esc`, `enter`/`return`, `space`, `tab`, `backspace`, `delete`/`del`, `up`, `down`, `left`, `right`,
+ * `pageup`, `pagedown`, `home`, `end`, `plus`, `comma`, `period`, `slash`, `f1`…`f12`. Any other single character
+ * matches `event.key`.
+ */
+export type Shortcut = string;
+export interface ParsedShortcut {
+    key: string;
+    mod: boolean;
+    ctrl: boolean;
+    meta: boolean;
+    alt: boolean;
+    shift: boolean;
+}
+/** `true` on macOS, iOS and iPadOS. Always `false` on the server. */
+export declare function isApplePlatform(): boolean;
+/**
+ * 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 declare function useIsMac(): boolean;
+/** Parses `"mod+shift+k"` into its parts. */
+export declare function parseShortcut(shortcut: Shortcut): ParsedShortcut;
+/** Does this keyboard event match the shortcut? */
+export declare function matchesShortcut(event: KeyboardEvent | React.KeyboardEvent, shortcut: Shortcut | ParsedShortcut, isMac?: boolean): boolean;
+export interface ShortcutKeyLabels {
+    mod?: string;
+    ctrl?: string;
+    alt?: string;
+    shift?: string;
+    meta?: string;
+}
+/**
+ * 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 declare function shortcutKeys(shortcut: Shortcut, isMac?: boolean): string[];
+/** Display text for one key token (`"mod"` → `"⌘"` / `"Ctrl"`, `"k"` → `"K"`). */
+export declare function formatKey(key: string, isMac?: boolean): string;
+/**
+ * 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 declare function formatShortcut(shortcut: Shortcut, options?: {
+    isMac?: boolean;
+    separator?: string;
+}): string;
+export interface UseHotkeysOptions {
+    /** Default `true`. */
+    enabled?: boolean;
+    /** Call `preventDefault()` on match. Default `true`. */
+    preventDefault?: boolean;
+    /**
+     * Fire while focus is in an input, textarea, select or contenteditable.
+     * Default: `true` for shortcuts with Ctrl/⌘/Alt (e.g. `mod+k`), `false` for plain keys (e.g. `/`, `?`, `j`).
+     */
+    enableOnFormFields?: boolean;
+    /** Element to listen on. Default `document`. */
+    target?: React.RefObject<HTMLElement | null> | HTMLElement | Document | null;
+    /** Default `"keydown"`. */
+    event?: "keydown" | "keyup";
+    /** Ignore auto-repeat while the key is held. Default `false`. */
+    ignoreRepeat?: boolean;
+}
+/**
+ * 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 declare function useHotkeys(shortcuts: Shortcut | Shortcut[], handler: (event: KeyboardEvent) => void, options?: UseHotkeysOptions): void;