@corbits/react-ui 0.1.0

package/dist/blocks/login/auth-layout.js

@@ -0,0 +1,52 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../../lib/utils.js";
+/**
+ * The two-column sign-in shell: a form on the left, a decorative panel on the
+ * right.
+ *
+ * The panel is hidden below `lg` rather than stacked. On a phone the form is
+ * the entire task, and a full-height decorative band above it means scrolling
+ * past the artwork to reach the thing you came to do.
+ *
+ * The form column is the semantic `<main>` and comes first in the DOM, so a
+ * screen reader and a keyboard both arrive at the form immediately. The panel
+ * is an `aria-hidden` sibling — it holds no information a signed-out visitor
+ * needs, and the quote inside it is atmosphere.
+ *
+ * `min-h-svh`, not `min-h-screen`. On mobile browsers `100vh` is the viewport
+ * *without* the retracting toolbar, so a `100vh` sign-in page is reliably a
+ * little too tall and the button sits just under the fold.
+ */ export function AuthLayout({ brand, children, panel, aside, className }) {
+    return /*#__PURE__*/ _jsxs("div", {
+        className: cn("grid min-h-svh bg-background lg:grid-cols-2", className),
+        children: [
+            /*#__PURE__*/ _jsxs("main", {
+                className: "relative flex flex-col",
+                children: [
+                    brand === undefined ? null : /*#__PURE__*/ _jsx("div", {
+                        className: "flex items-center gap-2.5 p-6 text-base font-semibold tracking-tight md:p-8",
+                        children: brand
+                    }),
+                    /*#__PURE__*/ _jsx("div", {
+                        className: "flex flex-1 items-center justify-center px-6 pb-16 md:px-10",
+                        children: /*#__PURE__*/ _jsx("div", {
+                            className: "w-full max-w-sm",
+                            children: children
+                        })
+                    })
+                ]
+            }),
+            /*#__PURE__*/ _jsxs("div", {
+                "aria-hidden": true,
+                className: "relative hidden overflow-hidden bg-card lg:block",
+                children: [
+                    panel,
+                    aside === undefined ? null : /*#__PURE__*/ _jsx("div", {
+                        className: "absolute inset-0 flex items-center justify-center p-12",
+                        children: aside
+                    })
+                ]
+            })
+        ]
+    });
+}

package/dist/blocks/login/login-form.d.ts

@@ -0,0 +1,60 @@
+import type { ReactNode } from "react";
+export type AuthProvider = {
+    /** Passed straight back to `onProvider`. Yours to define. */
+    readonly id: string;
+    /** The whole button label: "Continue with Google". */
+    readonly label: string;
+    /**
+     * The provider's mark, if you have it.
+     *
+     * This registry ships no third-party logos — trademarks are not ours to
+     * redistribute, and any app that wants real marks already has a licensed
+     * source for them. The slot is here; the artwork is yours.
+     */
+    readonly icon?: ReactNode;
+};
+export type LoginFormMode = "sign-in" | "sign-up";
+export type LoginFormProps = {
+    /** "sign-in" (default) shows email/password. "sign-up" adds a name field. */
+    readonly mode?: LoginFormMode;
+    readonly heading?: string;
+    /** Social / SSO options. Empty renders none, and no divider either. */
+    readonly providers?: readonly AuthProvider[];
+    readonly onProvider?: (id: string) => void;
+    /** Omit to render an SSO-only page with no email fields at all. */
+    readonly onSubmit?: (credentials: {
+        readonly name?: string;
+        readonly email: string;
+        readonly password: string;
+    }) => void;
+    /** True while a sign-in or sign-up is in flight. Disables every control. */
+    readonly busy?: boolean;
+    /** A failure to show. Announced, not just drawn. */
+    readonly error?: string | null;
+    /** Below the form — a "forgot password" link, terms copy. */
+    readonly footer?: ReactNode;
+    readonly className?: string;
+};
+/**
+ * The sign-in form. It renders and reports; it never authenticates.
+ *
+ * Every outcome leaves through a callback and every state arrives as a prop, so
+ * the block has no idea what a session is. That is what makes it installable:
+ * an auth block that imports a client is a block you have to gut before you can
+ * use it with yours.
+ *
+ * The error is `role="alert"`. A sign-in failure that is only drawn is a
+ * sign-in failure some users never learn about — they submit, nothing appears
+ * to happen, and they submit again. It is `aria-live="assertive"` precisely
+ * because interrupting is correct here.
+ *
+ * `autoComplete="email"` and `"current-password"` (`"new-password"` in
+ * sign-up mode) are not decoration: they are what lets a password manager
+ * fill this form, and a form password managers cannot fill pushes people
+ * toward worse passwords.
+ *
+ * The submit button reads "Signing in…" / "Signing up…" while busy rather
+ * than swapping to a spinner. The label is the status, so it is announced by
+ * the same mechanism that announces the button.
+ */
+export declare function LoginForm({ mode, heading, providers, onProvider, onSubmit, busy, error, footer, className, }: LoginFormProps): import("react").JSX.Element;

package/dist/blocks/login/login-form.js

@@ -0,0 +1,151 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { cn } from "../../lib/utils.js";
+import { Button } from "../../ui/button.js";
+import { Input } from "../../ui/input.js";
+/**
+ * The sign-in form. It renders and reports; it never authenticates.
+ *
+ * Every outcome leaves through a callback and every state arrives as a prop, so
+ * the block has no idea what a session is. That is what makes it installable:
+ * an auth block that imports a client is a block you have to gut before you can
+ * use it with yours.
+ *
+ * The error is `role="alert"`. A sign-in failure that is only drawn is a
+ * sign-in failure some users never learn about — they submit, nothing appears
+ * to happen, and they submit again. It is `aria-live="assertive"` precisely
+ * because interrupting is correct here.
+ *
+ * `autoComplete="email"` and `"current-password"` (`"new-password"` in
+ * sign-up mode) are not decoration: they are what lets a password manager
+ * fill this form, and a form password managers cannot fill pushes people
+ * toward worse passwords.
+ *
+ * The submit button reads "Signing in…" / "Signing up…" while busy rather
+ * than swapping to a spinner. The label is the status, so it is announced by
+ * the same mechanism that announces the button.
+ */ export function LoginForm({ mode = "sign-in", heading = "Welcome back", providers = [], onProvider, onSubmit, busy = false, error = null, footer, className }) {
+    const [name, setName] = useState("");
+    const [email, setEmail] = useState("");
+    const [password, setPassword] = useState("");
+    const isSignUp = mode === "sign-up";
+    return /*#__PURE__*/ _jsxs("div", {
+        className: cn("flex flex-col gap-6", className),
+        children: [
+            /*#__PURE__*/ _jsx("h1", {
+                className: "text-3xl leading-none font-semibold tracking-tight text-balance",
+                children: heading
+            }),
+            error === null ? null : /*#__PURE__*/ _jsx("p", {
+                role: "alert",
+                "aria-live": "assertive",
+                className: "rounded-md border border-destructive px-3 py-2 text-sm text-destructive",
+                children: error
+            }),
+            onSubmit === undefined ? null : /*#__PURE__*/ _jsxs("form", {
+                className: "flex flex-col gap-4",
+                onSubmit: (event)=>{
+                    event.preventDefault();
+                    onSubmit(isSignUp ? {
+                        name,
+                        email,
+                        password
+                    } : {
+                        email,
+                        password
+                    });
+                },
+                children: [
+                    !isSignUp ? null : /*#__PURE__*/ _jsxs("label", {
+                        className: "flex flex-col gap-1.5 text-sm font-medium",
+                        children: [
+                            "Name",
+                            /*#__PURE__*/ _jsx(Input, {
+                                type: "text",
+                                name: "name",
+                                autoComplete: "name",
+                                placeholder: "Ada Lovelace",
+                                value: name,
+                                onChange: (event)=>setName(event.target.value),
+                                disabled: busy,
+                                required: true,
+                                className: "h-11"
+                            })
+                        ]
+                    }),
+                    /*#__PURE__*/ _jsxs("label", {
+                        className: "flex flex-col gap-1.5 text-sm font-medium",
+                        children: [
+                            "Email",
+                            /*#__PURE__*/ _jsx(Input, {
+                                type: "email",
+                                name: "email",
+                                autoComplete: "email",
+                                placeholder: "you@example.com",
+                                value: email,
+                                onChange: (event)=>setEmail(event.target.value),
+                                disabled: busy,
+                                required: true,
+                                className: "h-11"
+                            })
+                        ]
+                    }),
+                    /*#__PURE__*/ _jsxs("label", {
+                        className: "flex flex-col gap-1.5 text-sm font-medium",
+                        children: [
+                            "Password",
+                            /*#__PURE__*/ _jsx(Input, {
+                                type: "password",
+                                name: "password",
+                                autoComplete: isSignUp ? "new-password" : "current-password",
+                                value: password,
+                                onChange: (event)=>setPassword(event.target.value),
+                                disabled: busy,
+                                required: true,
+                                className: "h-11"
+                            })
+                        ]
+                    }),
+                    /*#__PURE__*/ _jsx(Button, {
+                        type: "submit",
+                        size: "lg",
+                        disabled: busy,
+                        children: busy ? isSignUp ? "Signing up…" : "Signing in…" : "Continue"
+                    })
+                ]
+            }),
+            onSubmit === undefined || providers.length === 0 ? null : /*#__PURE__*/ _jsxs("div", {
+                className: "flex items-center gap-3",
+                children: [
+                    /*#__PURE__*/ _jsx("span", {
+                        "aria-hidden": true,
+                        className: "h-px flex-1 bg-border"
+                    }),
+                    /*#__PURE__*/ _jsx("span", {
+                        className: "text-xs tracking-wider text-muted-foreground uppercase",
+                        children: "or"
+                    }),
+                    /*#__PURE__*/ _jsx("span", {
+                        "aria-hidden": true,
+                        className: "h-px flex-1 bg-border"
+                    })
+                ]
+            }),
+            providers.map((provider)=>/*#__PURE__*/ _jsxs(Button, {
+                    type: "button",
+                    variant: "outline",
+                    size: "lg",
+                    disabled: busy,
+                    onClick: ()=>onProvider?.(provider.id),
+                    children: [
+                        provider.icon,
+                        provider.label
+                    ]
+                }, provider.id)),
+            footer === undefined ? null : /*#__PURE__*/ _jsx("div", {
+                className: "text-sm text-muted-foreground",
+                children: footer
+            })
+        ]
+    });
+}

package/dist/hooks/use-command-palette-navigation.d.ts

@@ -0,0 +1,25 @@
+import type { KeyboardEvent as ReactKeyboardEvent } from "react";
+export type UseCommandPaletteNavigationOptions<TItem extends {
+    readonly id: string;
+}> = {
+    /** The flat, visible result order — grouping is a display concern only. */
+    readonly items: readonly TItem[];
+    readonly onSelect: (id: string) => void;
+    readonly onClose: () => void;
+};
+export type UseCommandPaletteNavigationResult = {
+    readonly activeId: string | undefined;
+    readonly setActiveId: (id: string) => void;
+    readonly onKeyDown: (event: ReactKeyboardEvent) => void;
+};
+/**
+ * Keyboard driver for a command palette: Up/Down move the selection and wrap
+ * at the ends, Enter activates it, Escape closes without selecting.
+ *
+ * Selection is held as an id rather than an index so it survives the list
+ * reordering that happens every keystroke (fresh search results land at
+ * different positions) — an index would silently point at the wrong row.
+ */
+export declare function useCommandPaletteNavigation<TItem extends {
+    readonly id: string;
+}>({ items, onSelect, onClose, }: UseCommandPaletteNavigationOptions<TItem>): UseCommandPaletteNavigationResult;

package/dist/hooks/use-command-palette-navigation.js

@@ -0,0 +1,52 @@
+import { useMemo, useState } from "react";
+/**
+ * Keyboard driver for a command palette: Up/Down move the selection and wrap
+ * at the ends, Enter activates it, Escape closes without selecting.
+ *
+ * Selection is held as an id rather than an index so it survives the list
+ * reordering that happens every keystroke (fresh search results land at
+ * different positions) — an index would silently point at the wrong row.
+ */ export function useCommandPaletteNavigation({ items, onSelect, onClose }) {
+    const [requestedId, setRequestedId] = useState(undefined);
+    const activeId = useMemo(()=>{
+        if (items.length === 0) return undefined;
+        if (requestedId !== undefined && items.some((item)=>item.id === requestedId)) return requestedId;
+        return items[0]?.id;
+    }, [
+        items,
+        requestedId
+    ]);
+    function moveBy(delta) {
+        if (items.length === 0) return;
+        const currentIndex = activeId === undefined ? -1 : items.findIndex((item)=>item.id === activeId);
+        const nextIndex = (currentIndex + delta + items.length) % items.length;
+        setRequestedId(items[nextIndex]?.id);
+    }
+    function onKeyDown(event) {
+        switch(event.key){
+            case "ArrowDown":
+                event.preventDefault();
+                moveBy(1);
+                return;
+            case "ArrowUp":
+                event.preventDefault();
+                moveBy(-1);
+                return;
+            case "Enter":
+                event.preventDefault();
+                if (activeId !== undefined) onSelect(activeId);
+                return;
+            case "Escape":
+                event.preventDefault();
+                onClose();
+                return;
+            default:
+                return;
+        }
+    }
+    return {
+        activeId,
+        setActiveId: setRequestedId,
+        onKeyDown
+    };
+}

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

@@ -0,0 +1,28 @@
+export type ControllableStateAction<T> = T | ((previous: T) => T);
+export type UseControllableStateOptions<T> = {
+    /** Controlled value. Supply this with `onChange` to lift state to a parent. */
+    readonly value?: T;
+    /** Seeds the hook's own state when `value` is not supplied. */
+    readonly defaultValue: T;
+    readonly onChange?: (value: T) => void;
+    /** Identifies the caller in the dev-mode controlled/uncontrolled warning below. */
+    readonly name: string;
+};
+/**
+ * The controlled-or-uncontrolled resolution every prop pair shaped like
+ * `open`/`onOpenChange` needs: track state internally, but defer to `value`
+ * whenever the caller supplies one. `useDismissablePopover`, `ToolBlock` and
+ * `ToolNarrative` each want exactly this and previously each wrote their own
+ * ternary for it; this is the one place it lives now.
+ *
+ * The returned setter accepts a value or a React-style updater
+ * (`setOpen((prev) => !prev)`), same as `useState`.
+ *
+ * Like a native `<input>`, a caller is expected to pick controlled or
+ * uncontrolled once and keep it for the component's lifetime. Switching
+ * between them — `value` present on one render, `undefined` on the next —
+ * logs a `console.error` in non-production builds, mirroring React's own
+ * controlled/uncontrolled `<input>` warning; it does not throw, and the
+ * production build is silent.
+ */
+export declare function useControllableState<T>(options: UseControllableStateOptions<T>): readonly [T, (action: ControllableStateAction<T>) => void];

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

@@ -0,0 +1,44 @@
+import { useCallback, useRef, useState } from "react";
+const isProduction = typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+/**
+ * The controlled-or-uncontrolled resolution every prop pair shaped like
+ * `open`/`onOpenChange` needs: track state internally, but defer to `value`
+ * whenever the caller supplies one. `useDismissablePopover`, `ToolBlock` and
+ * `ToolNarrative` each want exactly this and previously each wrote their own
+ * ternary for it; this is the one place it lives now.
+ *
+ * The returned setter accepts a value or a React-style updater
+ * (`setOpen((prev) => !prev)`), same as `useState`.
+ *
+ * Like a native `<input>`, a caller is expected to pick controlled or
+ * uncontrolled once and keep it for the component's lifetime. Switching
+ * between them — `value` present on one render, `undefined` on the next —
+ * logs a `console.error` in non-production builds, mirroring React's own
+ * controlled/uncontrolled `<input>` warning; it does not throw, and the
+ * production build is silent.
+ */ export function useControllableState(options) {
+    const { value: controlledValue, defaultValue, onChange, name } = options;
+    const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue);
+    const isControlled = controlledValue !== undefined;
+    const value = isControlled ? controlledValue : uncontrolledValue;
+    const wasControlledRef = useRef(isControlled);
+    if (!isProduction && wasControlledRef.current !== isControlled) {
+        const from = wasControlledRef.current ? "controlled" : "uncontrolled";
+        const to = isControlled ? "controlled" : "uncontrolled";
+        console.error(`${name} is changing from ${from} to ${to}. Components should not switch between controlled ` + "and uncontrolled across their lifetime. Decide between using a controlled or uncontrolled " + `value for the lifetime of the component (i.e. always pass a value to \`${name}\`, or never do).`);
+    }
+    wasControlledRef.current = isControlled;
+    const setValue = useCallback((action)=>{
+        const resolved = typeof action === "function" ? action(value) : action;
+        if (!isControlled) setUncontrolledValue(resolved);
+        onChange?.(resolved);
+    }, [
+        isControlled,
+        value,
+        onChange
+    ]);
+    return [
+        value,
+        setValue
+    ];
+}

package/dist/hooks/use-delayed-autofocus.d.ts

@@ -0,0 +1,9 @@
+import { type RefObject } from "react";
+/**
+ * Focuses the given element shortly after `active` turns true — the composer
+ * wants to autofocus once the dock has finished popping open, not while it is
+ * still mid-animation, so the delay is deliberate rather than a magic number.
+ * `delayMs` defaults to `CHAT_DOCK_AUTOFOCUS_DELAY_MS`, which is pinned `>=`
+ * the dock's own entrance duration so focus never lands mid-animation.
+ */
+export declare function useDelayedAutofocus<T extends HTMLElement>(ref: RefObject<T | null>, active: boolean, delayMs?: number): void;

package/dist/hooks/use-delayed-autofocus.js

@@ -0,0 +1,20 @@
+import { useEffect } from "react";
+import { CHAT_DOCK_AUTOFOCUS_DELAY_MS } from "../ui/chat-dock-timing.js";
+/**
+ * Focuses the given element shortly after `active` turns true — the composer
+ * wants to autofocus once the dock has finished popping open, not while it is
+ * still mid-animation, so the delay is deliberate rather than a magic number.
+ * `delayMs` defaults to `CHAT_DOCK_AUTOFOCUS_DELAY_MS`, which is pinned `>=`
+ * the dock's own entrance duration so focus never lands mid-animation.
+ */ export function useDelayedAutofocus(ref, active, delayMs = CHAT_DOCK_AUTOFOCUS_DELAY_MS) {
+    useEffect(()=>{
+        if (!active) return;
+        const timer = window.setTimeout(()=>ref.current?.focus(), delayMs);
+        return ()=>window.clearTimeout(timer);
+    // `ref` is intentionally excluded: it is a stable container, and including
+    // it would refocus on every render that happens to produce a new object.
+    }, [
+        active,
+        delayMs
+    ]);
+}

package/dist/hooks/use-dismissable-popover.d.ts

@@ -0,0 +1,37 @@
+import { type RefObject } from "react";
+import { type ControllableStateAction } from "./use-controllable-state.js";
+export type UseDismissablePopoverOptions = {
+    /** Controlled open flag. Supply this with `onOpenChange` to lift state to a parent. */
+    readonly open?: boolean;
+    readonly onOpenChange?: (open: boolean) => void;
+    /** Seeds the hook's own state when `open` is not supplied. */
+    readonly defaultOpen?: boolean;
+    /** Escape closes the popover and returns focus to the trigger. Default `true`. */
+    readonly closeOnEscape?: boolean;
+};
+export type UseDismissablePopoverResult<Root extends HTMLElement, Trigger extends HTMLElement> = {
+    readonly open: boolean;
+    readonly setOpen: (action: ControllableStateAction<boolean>) => void;
+    readonly rootRef: RefObject<Root | null>;
+    readonly triggerRef: RefObject<Trigger | null>;
+    /** Closes and returns focus to the trigger. */
+    readonly close: () => void;
+};
+/**
+ * The behavior every dismissable popover trigger shares: an open flag, a
+ * pointer-down outside `rootRef` that closes it, and (by default) Escape that
+ * closes it and returns focus to `triggerRef`. `NotificationsBell`,
+ * `TenantSelector` and `ThreadSwitcher` each hand-rolled this before it moved
+ * here — one hook now, not three near-identical `useEffect` pairs.
+ *
+ * Controlled when `open` is supplied (pair it with `onOpenChange`);
+ * uncontrolled otherwise, seeded from `defaultOpen`. A caller with its own
+ * Escape handling (a listbox that also closes on Tab, say) sets
+ * `closeOnEscape: false` and wires Escape itself.
+ *
+ * The controlled/uncontrolled resolution — including the dev-mode warning if
+ * a caller switches between them after mount — is `useControllableState`;
+ * this hook only adds the popover-specific dismissal behavior on top.
+ * `setOpen` takes a value or an updater, same as `useState`.
+ */
+export declare function useDismissablePopover<Root extends HTMLElement = HTMLElement, Trigger extends HTMLElement = HTMLElement>(options?: UseDismissablePopoverOptions): UseDismissablePopoverResult<Root, Trigger>;

package/dist/hooks/use-dismissable-popover.js

@@ -0,0 +1,64 @@
+import { useCallback, useEffect, useRef } from "react";
+import { useControllableState } from "./use-controllable-state.js";
+/**
+ * The behavior every dismissable popover trigger shares: an open flag, a
+ * pointer-down outside `rootRef` that closes it, and (by default) Escape that
+ * closes it and returns focus to `triggerRef`. `NotificationsBell`,
+ * `TenantSelector` and `ThreadSwitcher` each hand-rolled this before it moved
+ * here — one hook now, not three near-identical `useEffect` pairs.
+ *
+ * Controlled when `open` is supplied (pair it with `onOpenChange`);
+ * uncontrolled otherwise, seeded from `defaultOpen`. A caller with its own
+ * Escape handling (a listbox that also closes on Tab, say) sets
+ * `closeOnEscape: false` and wires Escape itself.
+ *
+ * The controlled/uncontrolled resolution — including the dev-mode warning if
+ * a caller switches between them after mount — is `useControllableState`;
+ * this hook only adds the popover-specific dismissal behavior on top.
+ * `setOpen` takes a value or an updater, same as `useState`.
+ */ export function useDismissablePopover(options = {}) {
+    const { open: controlledOpen, onOpenChange, defaultOpen = false, closeOnEscape = true } = options;
+    const [open, setOpen] = useControllableState({
+        value: controlledOpen,
+        defaultValue: defaultOpen,
+        onChange: onOpenChange,
+        name: "useDismissablePopover"
+    });
+    const rootRef = useRef(null);
+    const triggerRef = useRef(null);
+    const close = useCallback(()=>{
+        setOpen(false);
+        triggerRef.current?.focus();
+    }, [
+        setOpen
+    ]);
+    useEffect(()=>{
+        if (!open) return;
+        const onPointerDown = (event)=>{
+            if (!(event.target instanceof Node)) return;
+            if (rootRef.current?.contains(event.target) === false) setOpen(false);
+        };
+        const onKeyDown = (event)=>{
+            if (!closeOnEscape || event.key !== "Escape") return;
+            close();
+        };
+        document.addEventListener("pointerdown", onPointerDown);
+        document.addEventListener("keydown", onKeyDown);
+        return ()=>{
+            document.removeEventListener("pointerdown", onPointerDown);
+            document.removeEventListener("keydown", onKeyDown);
+        };
+    }, [
+        open,
+        close,
+        setOpen,
+        closeOnEscape
+    ]);
+    return {
+        open,
+        setOpen,
+        rootRef,
+        triggerRef,
+        close
+    };
+}

package/dist/hooks/use-list-selection.d.ts

@@ -0,0 +1,66 @@
+export type UseListSelectionOptions<TId extends PropertyKey> = {
+    /**
+     * The full, currently visible row order — range selection is anchored
+     * against this, and it is also what a stale selection gets reconciled
+     * against (see `selectedIds` below). Ids must be unique: a duplicate
+     * makes `indexOf` resolve to whichever occurrence comes first, so a
+     * shift-click range would sweep rows the person never actually crossed.
+     */
+    readonly ids: readonly TId[];
+};
+export type ToggleModifiers = {
+    /** Extends the anchored range through the clicked row, like a Finder/Sheets shift-click. */
+    readonly shiftKey?: boolean;
+};
+export type UseListSelectionResult<TId extends PropertyKey> = {
+    /**
+     * Selected ids, reconciled against the `ids` this call was given — an id
+     * a refetch or a filter change dropped from `ids` is filtered out here
+     * even though the hook still remembers it internally (see below), so
+     * this is always an honest subset of what is actually on screen.
+     */
+    readonly selectedIds: ReadonlySet<TId>;
+    readonly selectedCount: number;
+    readonly isSelected: (id: TId) => boolean;
+    /**
+     * Toggle one row. Plain click and cmd/ctrl-click both land here — the
+     * distinction between "replace selection" and "add to selection" is a
+     * caller-side concern this hook does not have an opinion on, since it
+     * never clears the rest of the selection on your behalf. Pass
+     * `shiftKey: true` to extend the last-toggled row's anchor through `id`
+     * instead of toggling `id` alone.
+     */
+    readonly toggle: (id: TId, modifiers?: ToggleModifiers) => void;
+    readonly selectAll: () => void;
+    readonly clear: () => void;
+};
+/**
+ * Headless selection state for a list/table: toggle-by-id, shift-click range
+ * selection anchored on the last row toggled outside a range, and
+ * select-all/clear. Renders nothing and owns no DOM — `SelectionCheckbox` and
+ * `BulkActionBar` are the rendered halves of this.
+ *
+ * The anchor is the last id passed to `toggle` *without* `shiftKey` — the
+ * same row a Finder/Sheets shift-click ranges from. A shift-click does not
+ * move the anchor, so a person can shift-click several times in a row (even
+ * in different directions) and each click re-ranges from the same start
+ * rather than from wherever they last landed.
+ *
+ * **Stale-id reconciliation.** The hook keeps whatever was selected even
+ * after a row drops out of `ids` (a refetch, a filter change) rather than
+ * pruning it immediately — pruning on every `ids` change would need an
+ * effect, and an extra render on top of whatever caused `ids` to change in
+ * the first place. Instead `selectedIds`/`selectedCount`/`isSelected` are
+ * reconciled against the current `ids` on every read, so a stale id can
+ * never inflate the count or reach the caller; it simply stops counting
+ * once its row is gone, and starts counting again if the same id reappears
+ * (e.g. a filter that got cleared) with no action needed from the caller.
+ *
+ * **Stable callbacks.** `toggle`/`selectAll`/`clear` read `ids` through a
+ * ref rather than closing over the `ids` array directly, so their identity
+ * stays stable across renders even when a caller passes a freshly allocated
+ * array each time (e.g. an inline `rows.map(row => row.id)`) — a memoized
+ * row downstream that depends on `toggle` does not re-render just because
+ * the caller didn't bother memoizing `ids`.
+ */
+export declare function useListSelection<TId extends PropertyKey>({ ids, }: UseListSelectionOptions<TId>): UseListSelectionResult<TId>;