@sincpro/web-ui 0.0.0-stage → 0.1.0

package/dist/components/listing/pages.js

@@ -0,0 +1,135 @@
+"use client";
+import { useEffect, useState } from "react";
+/**
+ * How many records a list shows until someone asks for another size.
+ *
+ * 80 is the product default: enough to scan a catalog without paging every
+ * twenty-five rows, still small enough that a table stays a table. 25 / 80 / 100
+ * are the presets; any other positive integer is valid and is kept.
+ */
+export const DEFAULT_PAGE_SIZE = 80;
+export const PAGE_SIZES = [25, 80, 100];
+function clampSize(next) {
+    if (!Number.isFinite(next))
+        return DEFAULT_PAGE_SIZE;
+    return Math.max(1, Math.floor(next));
+}
+/**
+ * Cut an in-memory set into pages.
+ *
+ * `pageSize` is controlled when `onPageSizeChange` is passed — that is how a
+ * view context keeps the size across filters. Without it the hook owns the
+ * size, defaulting to 80.
+ *
+ * The current page is clamped in the calculation, not in an effect: if a
+ * filter leaves fewer pages than the current one, the next read already
+ * lands on the last page that exists.
+ */
+export function usePagination(items, options = {}) {
+    const controlled = options.pageSize !== undefined && options.onPageSizeChange !== undefined;
+    const [ownedSize, setOwnedSize] = useState(options.pageSize ?? DEFAULT_PAGE_SIZE);
+    const [page, setPage] = useState(1);
+    const pageSize = clampSize(controlled ? (options.pageSize ?? DEFAULT_PAGE_SIZE) : ownedSize);
+    const setPageSize = controlled ? options.onPageSizeChange : setOwnedSize;
+    const total = items.length;
+    const pages = Math.max(1, Math.ceil(total / pageSize));
+    const current = Math.min(page, pages);
+    const from = total === 0 ? 0 : (current - 1) * pageSize + 1;
+    const to = Math.min(current * pageSize, total);
+    return {
+        pageItems: items.slice(from > 0 ? from - 1 : 0, to),
+        bridge: {
+            from,
+            to,
+            total,
+            pageSize,
+            onPageSizeChange: (next) => {
+                setPageSize(clampSize(next));
+                setPage(1);
+            },
+            /* Se mueve desde `current` y no desde `page`, que es el que puede haber
+               quedado alto: si estabas en la 3 y un filtro dejó dos páginas, `page`
+               sigue en 3 mientras se muestra la 2, y `p - 1` volvía a 2 — o sea que
+               «anterior» no hacía nada hasta el segundo clic. */
+            ...(current > 1 ? { onPrev: () => setPage(current - 1) } : {}),
+            ...(current < pages ? { onNext: () => setPage(current + 1) } : {}),
+        },
+    };
+}
+/**
+ * Cut a *server-side* set into pages, by cursor.
+ *
+ * `usePagination` slices an array that is already in hand; this one never holds the whole set.
+ * Same `bridge`, so `Pagination` draws it identically — the difference is invisible to a view.
+ *
+ * **Going back is a walk, not a jump.** A keyset cursor names the last row seen, so it points
+ * forward and nothing points back. Rather than fake it with an offset — which would reintroduce
+ * exactly the incoherence the cursor exists to avoid — the cursors already walked are kept, and
+ * `onPrev` re-fetches with the one before. That is one request, not a re-walk from the start.
+ *
+ * **Changing the size starts over**, and that is not a limitation: a cursor belongs to the page
+ * size it was minted under, so keeping it would land somewhere nobody asked for.
+ */
+export function useCursorPagination(source, options = {}) {
+    const controlled = options.pageSize !== undefined && options.onPageSizeChange !== undefined;
+    const [ownedSize, setOwnedSize] = useState(options.pageSize ?? DEFAULT_PAGE_SIZE);
+    const pageSize = clampSize(controlled ? options.pageSize : ownedSize);
+    /* The cursor that opened each page walked so far. `[undefined]` is the first page, which
+       opens with no cursor — so `walked.length` is the page number. */
+    const [walked, setWalked] = useState([undefined]);
+    const [page, setPage] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const at = walked[walked.length - 1];
+    /* Starting over is keyed on what changes the reading — the filter, the ordering, the size.
+       Without this an `onPrev` after a filter change would re-fetch a cursor minted for the
+       previous reading, and the server would refuse it. */
+    useEffect(() => {
+        setWalked([undefined]);
+    }, [source.resetKey, pageSize]);
+    useEffect(() => {
+        let current = true;
+        setLoading(true);
+        source
+            .fetch(at, pageSize)
+            .then((answer) => {
+            if (!current)
+                return;
+            setPage(answer);
+            setError(null);
+        })
+            .catch((failure) => current && setError(failure))
+            .finally(() => current && setLoading(false));
+        return () => {
+            current = false;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [at, pageSize, source.resetKey]);
+    const items = page?.items ?? [];
+    const total = page?.count?.value ?? items.length;
+    const from = items.length === 0 ? 0 : (walked.length - 1) * pageSize + 1;
+    const to = from === 0 ? 0 : from + items.length - 1;
+    return {
+        pageItems: [...items],
+        loading,
+        error,
+        bridge: {
+            from,
+            to,
+            total,
+            pageSize,
+            onPageSizeChange: (next) => {
+                const size = clampSize(next);
+                if (controlled)
+                    options.onPageSizeChange(size);
+                else
+                    setOwnedSize(size);
+                setWalked([undefined]);
+            },
+            ...(walked.length > 1 ? { onPrev: () => setWalked((so) => so.slice(0, -1)) } : {}),
+            ...(page?.cursor != null
+                ? { onNext: () => setWalked((so) => [...so, page.cursor ?? undefined]) }
+                : {}),
+        },
+    };
+}

package/dist/components/listing/selection.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Choosing rows of a SET. Lives next to pagination because both are how N
+ * records are controlled, not how they are drawn.
+ *
+ * «All» means the ones ON SCREEN: with a filter on, select-all cannot take
+ * what the filter hid. Chosen ids survive filtering — the Set stores ids,
+ * not positions — so you can choose, filter again, choose more, and act on
+ * both batches.
+ */
+export interface Selection {
+    chosen: ReadonlySet<string>;
+    count: number;
+    has: (id: string) => boolean;
+    toggle: (id: string) => void;
+    toggleAll: () => void;
+    /** `true` all, `false` none, `"some"` part — the third state is the half
+     *  checkbox, and without it the header lies when three of ten are chosen. */
+    allState: boolean | "some";
+    clear: () => void;
+}
+export declare function useSelection(visible: readonly string[]): Selection;

package/dist/components/listing/selection.js

@@ -0,0 +1,43 @@
+"use client";
+import { useCallback, useMemo, useState } from "react";
+export function useSelection(visible) {
+    const [chosen, setChosen] = useState(new Set());
+    const allState = useMemo(() => {
+        if (visible.length === 0)
+            return false;
+        const inside = visible.filter((id) => chosen.has(id)).length;
+        if (inside === 0)
+            return false;
+        return inside === visible.length ? true : "some";
+    }, [visible, chosen]);
+    const toggle = useCallback((id) => {
+        setChosen((current) => {
+            const next = new Set(current);
+            if (next.has(id))
+                next.delete(id);
+            else
+                next.add(id);
+            return next;
+        });
+    }, []);
+    const toggleAll = useCallback(() => {
+        setChosen((current) => {
+            const inside = visible.filter((id) => current.has(id)).length;
+            const next = new Set(current);
+            if (inside === visible.length)
+                visible.forEach((id) => next.delete(id));
+            else
+                visible.forEach((id) => next.add(id));
+            return next;
+        });
+    }, [visible]);
+    return {
+        chosen,
+        count: chosen.size,
+        has: (id) => chosen.has(id),
+        toggle,
+        toggleAll,
+        allState,
+        clear: () => setChosen(new Set()),
+    };
+}

package/dist/components/listing/set.d.ts

@@ -0,0 +1,48 @@
+import { type Pages } from "./pages.js";
+/**
+ * How a SET is looked at: which presentation, how many fit on a page.
+ *
+ * ListView and every catalog-like screen were inventing these two pieces of
+ * state on their own. They belong together because they answer the same
+ * question — «how do I look at N?» — whether N is domain records or the
+ * page of a frame.
+ *
+ * `Present` is generic so a list (`ListPresent`) and a frame (`table` |
+ * `chart`) share the hook without importing each other's unions.
+ *
+ * Controlled when the view context keeps them (catalog filters must not
+ * reset the page size). Uncontrolled when the screen is the only owner.
+ */
+/**
+ * Las maneras de mirar un conjunto. **Vive acá y no en el arquetipo** porque
+ * son dos los que preguntan lo mismo —una lista y un marco— y la definición
+ * tiene que ser una sola.
+ *
+ * Era dos: `ListPresent` en `archetype/ListView.tsx` y esta copia. Mientras las
+ * dos decían `rows | table | board` nadie lo notaba; agregar `sheet` a una dejó
+ * cuatro vistas sin compilar, que es exactamente lo que pasa cuando la misma
+ * idea está escrita dos veces.
+ *
+ *     rows / board   no hay columnas: nombre, fichas y meta.
+ *     table          las columnas las DECLARA el código.
+ *     sheet          las columnas salen del ARCHIVO — puede haber cuarenta y un
+ *                    millón de filas, así que va virtualizada.
+ *     report         columnas de período y filas en JERARQUÍA que termina en
+ *                    totales. No se ordena: el orden ES el informe.
+ *     pivot          dos EJES a la vez. Una fila es un montón y una columna
+ *                    también; lo que se lee está en el cruce. Tampoco se
+ *                    ordena: el orden de cada eje es el de sus claves.
+ */
+export type ListPresent = "rows" | "table" | "board" | "sheet" | "report" | "pivot";
+export interface SetControl<Row, Present extends string = ListPresent> extends Pages<Row> {
+    present: Present;
+    setPresent: (next: Present) => void;
+    pageSize: number;
+    setPageSize: (next: number) => void;
+}
+export declare function useSetControl<Row, Present extends string = ListPresent>(items: readonly Row[], options?: {
+    present?: Present;
+    onPresentChange?: (next: Present) => void;
+    pageSize?: number;
+    onPageSizeChange?: (next: number) => void;
+}): SetControl<Row, Present>;

package/dist/components/listing/set.js

@@ -0,0 +1,24 @@
+"use client";
+import { DEFAULT_PAGE_SIZE, usePagination, } from "./pages.js";
+import { useState } from "react";
+export function useSetControl(items, options = {}) {
+    const initialPresent = (options.present ?? "table");
+    const [ownedPresent, setOwnedPresent] = useState(initialPresent);
+    const [ownedSize, setOwnedSize] = useState(options.pageSize ?? DEFAULT_PAGE_SIZE);
+    const presentControlled = options.onPresentChange !== undefined;
+    const present = presentControlled
+        ? (options.present ?? "table")
+        : ownedPresent;
+    const setPresent = presentControlled ? options.onPresentChange : setOwnedPresent;
+    const sizeControlled = options.onPageSizeChange !== undefined;
+    const pageSize = sizeControlled ? (options.pageSize ?? DEFAULT_PAGE_SIZE) : ownedSize;
+    const setPageSize = sizeControlled ? options.onPageSizeChange : setOwnedSize;
+    const pages = usePagination(items, { pageSize, onPageSizeChange: setPageSize });
+    return {
+        ...pages,
+        present,
+        setPresent,
+        pageSize,
+        setPageSize,
+    };
+}

package/dist/components/listing/tree.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Which BRANCHES of a set are closed.
+ *
+ * Grouping is the tree: a list split by customer, a table with expandable
+ * group rows, a board with the same headers. The collapsed keys belong to the
+ * SET, not to one presentation — switching from rows to table must not reopen
+ * what the user just closed.
+ *
+ * **A key here is a pile's PATH**, serialized with `pathKey()`. With one level a
+ * plain key was enough, because no two piles could be called the same. With N
+ * levels they can: «2026-09» is one month inside «Ferretería Sur» and another inside
+ * «Distribuidora Andina», and folding one must not fold the other. What tells them apart is
+ * the route that leads to each, so that is what is stored.
+ *
+ * A hierarchical parent/child present would use the same keys. There is no
+ * fourth archetype for «tree»: collapse is how N is folded, the same way
+ * pagination is how N is cut.
+ */
+export type TreeControl = {
+    collapsed: readonly string[];
+    isOpen: (key: string) => boolean;
+    toggle: (key: string) => void;
+};
+export declare function toggleCollapsed(collapsed: readonly string[], key: string): string[];
+export declare function useTreeControl(options?: {
+    collapsed?: readonly string[];
+    onCollapsedChange?: (keys: readonly string[]) => void;
+}): TreeControl;

package/dist/components/listing/tree.js

@@ -0,0 +1,23 @@
+"use client";
+import { useCallback, useState } from "react";
+export function toggleCollapsed(collapsed, key) {
+    return collapsed.includes(key)
+        ? collapsed.filter((one) => one !== key)
+        : [...collapsed, key];
+}
+// One empty array for every render: a fresh `[]` would change `toggle` each time.
+const NONE_COLLAPSED = [];
+export function useTreeControl(options = {}) {
+    const [owned, setOwned] = useState(options.collapsed ?? NONE_COLLAPSED);
+    const controlled = options.onCollapsedChange !== undefined;
+    const collapsed = controlled ? (options.collapsed ?? NONE_COLLAPSED) : owned;
+    const setCollapsed = controlled ? options.onCollapsedChange : setOwned;
+    const toggle = useCallback((key) => {
+        setCollapsed(toggleCollapsed(collapsed, key));
+    }, [collapsed, setCollapsed]);
+    return {
+        collapsed,
+        isOpen: (key) => collapsed.includes(key) !== true,
+        toggle,
+    };
+}

package/dist/components/navigation/CommandPalette.d.ts

@@ -0,0 +1,40 @@
+import { type PaletteCommand } from "./commands.js";
+/**
+ * The search box and the list, without the modal around them.
+ *
+ * Context: split out so the filtering can be rendered on its own — in a test, with a query
+ * already typed — since the modal is a portal that only exists in a browser.
+ */
+export declare function CommandSearch({ commands, onRun, query, onQueryChange, placeholder, }: {
+    commands: readonly PaletteCommand[];
+    onRun: (id: string) => void;
+    query?: string;
+    onQueryChange?: (next: string) => void;
+    placeholder?: string;
+}): import("react").JSX.Element;
+/**
+ * A modal search over everything the app can do — go to a screen, create a record — opened
+ * with ⌘K (Ctrl+K) and run with Enter.
+ *
+ * Context: it is controlled (`open`, `onOpenChange`) and does not bind the shortcut itself,
+ * because an app has ONE palette and many screens: the key is bound once, where the palette
+ * lives, with `useCommandPaletteShortcut`. Running a command closes it — the palette is a
+ * path, not a place to stay.
+ */
+export declare function CommandPalette({ open, onOpenChange, commands, onRun, placeholder, }: {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    commands: readonly PaletteCommand[];
+    /** A command was chosen. The palette closes on its own. */
+    onRun: (id: string) => void;
+    /** The search box's prompt and its accessible name. By default, the copy table's. */
+    placeholder?: string;
+}): import("react").JSX.Element;
+/**
+ * Binds ⌘K (Ctrl+K on Windows and Linux) to open the palette, anywhere in the page.
+ *
+ * Context: both modifiers are accepted on every platform. Telling them apart by the user
+ * agent guesses wrong on a Mac with a PC keyboard, and the cost of accepting both is that
+ * Ctrl+K on a Mac — «delete to the end of the line» in a text box — opens the palette.
+ */
+export declare function useCommandPaletteShortcut(setOpen: (open: boolean) => void): void;

package/dist/components/navigation/CommandPalette.js

@@ -0,0 +1,114 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { commandMatches, groupCommands, } from "./commands.js";
+import { AriaLocale } from "../../foundations/aria.js";
+import { useUiCopy } from "../../foundations/copy.js";
+import { tv } from "../../foundations/variants.js";
+import { Search, X } from "lucide-react";
+import { useEffect, useMemo } from "react";
+import { Autocomplete, Button as AriaButton, Dialog, Header, Input, Keyboard, Menu, MenuItem, MenuSection, Modal, ModalOverlay, SearchField, useFilter, } from "react-aria-components";
+/* ==================================================================== *
+ *  COMMAND PALETTE — ⌘K, type three letters, Enter.
+ *
+ *  An ERP has a hundred screens and twenty «new» buttons, and the people who
+ *  use it all day stop wanting to look for any of them: they know the name of
+ *  what they want. The palette is the shortest path from knowing the name to
+ *  being there — one key to open, a few letters, Enter — without leaving the
+ *  keyboard and without knowing in which menu of which module it lives.
+ *
+ *      ┌──────────────────────────────────────────────┐
+ *      │ 🔍 fact                                    ✕ │
+ *      ├──────────────────────────────────────────────┤
+ *      │ IR A…                                        │
+ *      │ ▌🧾 Facturas                                 │  ← Enter runs it
+ *      │ CREAR…                                       │
+ *      │   ＋ Nueva factura                       ⌘N  │
+ *      └──────────────────────────────────────────────┘
+ *
+ *  React Aria's `Autocomplete` drives it: focus stays in the search box while
+ *  the arrows walk the list (virtual focus), the first match is highlighted as
+ *  you type so Enter always does something, and the modal traps focus, closes
+ *  on Escape and on a click outside, and gives the focus back.
+ *
+ *  The match is the locale's (`useFilter` inside `AriaLocale`): «facturacion»
+ *  finds «Facturación» because nobody types the accent when they are in a hurry.
+ * ==================================================================== */
+const overlay = tv({
+    base: "fixed inset-0 z-50 flex items-start justify-center overflow-y-auto bg-scrim/40 px-4 pt-24 transition-opacity duration-(--duration-quick) ease-(--ease-out)",
+    variants: {
+        isEntering: { true: "opacity-0" },
+        isExiting: { true: "opacity-0" },
+    },
+});
+const surface = tv({
+    base: "w-full max-w-xl overflow-hidden rounded-panel border border-line-strong bg-surface text-ink shadow-window outline-0 transition-[opacity,translate] duration-(--duration-quick) ease-(--ease-out) forced-colors:bg-[Canvas]",
+    variants: {
+        isEntering: { true: "-translate-y-1 opacity-0" },
+        isExiting: { true: "opacity-0" },
+    },
+});
+const item = tv({
+    base: "flex cursor-default items-center gap-2 rounded-control px-2 py-1.5 text-meta text-ink outline-0 select-none",
+    variants: {
+        isFocused: {
+            true: "bg-primary/8 forced-colors:bg-[Highlight] forced-colors:text-[HighlightText]",
+        },
+        isPressed: { true: "bg-primary/12" },
+        isDisabled: { true: "text-muted forced-colors:text-[GrayText]" },
+    },
+});
+/**
+ * The search box and the list, without the modal around them.
+ *
+ * Context: split out so the filtering can be rendered on its own — in a test, with a query
+ * already typed — since the modal is a portal that only exists in a browser.
+ */
+export function CommandSearch({ commands, onRun, query, onQueryChange, placeholder, }) {
+    const copy = useUiCopy();
+    const { contains } = useFilter({ sensitivity: "base" });
+    const byId = useMemo(() => new Map(commands.map((c) => [c.id, c])), [commands]);
+    const groups = useMemo(() => groupCommands(commands), [commands]);
+    const hint = placeholder ?? copy.search.placeholder;
+    return (_jsxs(Autocomplete, { ...(query === undefined ? {} : { inputValue: query }), ...(onQueryChange === undefined ? {} : { onInputChange: onQueryChange }), filter: (_text, input, node) => {
+            const command = byId.get(String(node.key));
+            return command === undefined || commandMatches(command, input, contains);
+        }, children: [_jsxs(SearchField, { "aria-label": hint, autoFocus: true, className: "group flex items-center gap-2 border-b border-line px-3", children: [_jsx(Search, { className: "size-(--size-icon-md) shrink-0 text-muted", strokeWidth: 2, "aria-hidden": true }), _jsx(Input, { placeholder: hint, className: "h-(--size-control-lg) min-w-0 flex-1 bg-transparent text-body text-ink outline-0 placeholder:text-muted [&::-webkit-search-cancel-button]:hidden" }), _jsx(AriaButton, { className: "inline-flex shrink-0 items-center justify-center rounded-mark p-1 text-muted transition-colors duration-(--duration-instant) group-empty:invisible hover:bg-ink/6 hover:text-ink pressed:bg-ink/10", children: _jsx(X, { className: "size-(--size-icon-md)", strokeWidth: 2, "aria-hidden": true }) })] }), _jsx(Menu, { "aria-label": hint, onAction: (key) => onRun(String(key)), renderEmptyState: () => (_jsx("p", { className: "px-3 py-6 text-center text-meta text-muted italic", children: copy.menu.empty })), className: "max-h-96 overflow-y-auto p-1 outline-0", children: groups.map((group) => (_jsxs(MenuSection, { id: group.section ?? "-", className: "not-first:mt-1", children: [group.section === undefined ? null : (_jsx(Header, { className: "px-2 pt-2 pb-1 text-micro font-medium text-muted", children: group.section })), group.commands.map((command) => {
+                            const Icon = command.icon;
+                            return (_jsxs(MenuItem, { id: command.id, textValue: command.label, className: item, children: [_jsx("span", { className: "flex size-(--size-icon-md) shrink-0 items-center justify-center text-muted", children: Icon === undefined ? null : (_jsx(Icon, { className: "size-(--size-icon-md)", strokeWidth: 2, "aria-hidden": true })) }), _jsx("span", { className: "min-w-0 flex-1 truncate", children: command.label }), command.shortcut === undefined ? null : (_jsx(Keyboard, { className: "shrink-0 rounded-mark border border-line px-1.5 font-sans text-micro text-muted tabular-nums", children: command.shortcut }))] }, command.id));
+                        })] }, group.section ?? ""))) })] }));
+}
+/**
+ * A modal search over everything the app can do — go to a screen, create a record — opened
+ * with ⌘K (Ctrl+K) and run with Enter.
+ *
+ * Context: it is controlled (`open`, `onOpenChange`) and does not bind the shortcut itself,
+ * because an app has ONE palette and many screens: the key is bound once, where the palette
+ * lives, with `useCommandPaletteShortcut`. Running a command closes it — the palette is a
+ * path, not a place to stay.
+ */
+export function CommandPalette({ open, onOpenChange, commands, onRun, placeholder, }) {
+    const copy = useUiCopy();
+    return (_jsx(AriaLocale, { children: _jsx(ModalOverlay, { isOpen: open, onOpenChange: onOpenChange, isDismissable: true, className: overlay, children: _jsx(Modal, { className: surface, children: _jsx(Dialog, { "aria-label": placeholder ?? copy.search.placeholder, className: "outline-0", children: _jsx(CommandSearch, { commands: commands, onRun: (id) => {
+                            onOpenChange(false);
+                            onRun(id);
+                        }, ...(placeholder === undefined ? {} : { placeholder }) }) }) }) }) }));
+}
+/**
+ * Binds ⌘K (Ctrl+K on Windows and Linux) to open the palette, anywhere in the page.
+ *
+ * Context: both modifiers are accepted on every platform. Telling them apart by the user
+ * agent guesses wrong on a Mac with a PC keyboard, and the cost of accepting both is that
+ * Ctrl+K on a Mac — «delete to the end of the line» in a text box — opens the palette.
+ */
+export function useCommandPaletteShortcut(setOpen) {
+    useEffect(() => {
+        const onKey = (e) => {
+            if (e.key.toLowerCase() !== "k" || !(e.metaKey || e.ctrlKey) || e.altKey)
+                return;
+            e.preventDefault();
+            setOpen(true);
+        };
+        document.addEventListener("keydown", onKey);
+        return () => document.removeEventListener("keydown", onKey);
+    }, [setOpen]);
+}

package/dist/components/navigation/NavigationTree.d.ts

@@ -0,0 +1,31 @@
+import { type LucideIcon } from "lucide-react";
+/** One entry of the sidebar. With `children` it is a module that opens and closes; without,
+ *  it is a screen you go to. */
+export interface NavItem {
+    id: string;
+    label: string;
+    icon?: LucideIcon;
+    /** What is waiting there: drafts, overdue, to approve. Zero is not drawn — a «0» beside
+     *  every quiet screen is a column of noise the eye has to read to learn nothing. */
+    count?: number;
+    children?: readonly NavItem[];
+}
+/**
+ * The sidebar of an ERP module: modules that open and close, the screens inside them with
+ * an icon and what is waiting there, and the row you are on marked.
+ *
+ * Context: the modules on the way to `current` start open even when `defaultExpanded` does
+ * not name them. A sidebar that loads with the current screen folded away answers «where am
+ * I» with a closed module, and that is the whole question it exists for.
+ */
+export declare function NavigationTree({ items, current, onNavigate, defaultExpanded, label, }: {
+    items: readonly NavItem[];
+    /** The id of the screen on view. */
+    current?: string;
+    /** A screen was chosen — by click, Enter, or the keyboard. Modules only open and close. */
+    onNavigate?: (id: string) => void;
+    /** The modules that start open. The path to `current` is always added. */
+    defaultExpanded?: readonly string[];
+    /** The accessible name of the tree. By default, the copy table's name for a module's menus. */
+    label?: string;
+}): import("react").JSX.Element;

package/dist/components/navigation/NavigationTree.js

@@ -0,0 +1,79 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { AriaLocale } from "../../foundations/aria.js";
+import { useUiCopy } from "../../foundations/copy.js";
+import { focusRing, tv } from "../../foundations/variants.js";
+import { ChevronRight } from "lucide-react";
+import { useMemo } from "react";
+import { Button as AriaButton, Link, NavigationTree as AriaNavigationTree, NavigationTreeItem as AriaNavigationTreeItem, NavigationTreeItemContent, RouterProvider, } from "react-aria-components";
+const row = tv({
+    extend: focusRing,
+    base: "group relative flex min-w-0 items-center rounded-control text-meta text-ink outline-offset-0 select-none",
+    variants: {
+        isCurrent: {
+            true: "bg-primary/10 font-medium text-primary forced-colors:bg-[Highlight] forced-colors:text-[HighlightText]",
+            false: "hover:bg-ink/6",
+        },
+    },
+});
+const link = tv({
+    base: "flex h-(--size-control-sm) min-w-0 flex-1 cursor-pointer items-center gap-2 px-2 text-current no-underline outline-0",
+    variants: {
+        isModule: { true: "font-medium" },
+    },
+});
+const chevronButton = tv({
+    extend: focusRing,
+    base: "mr-1 inline-flex shrink-0 items-center justify-center rounded-mark p-1 text-muted transition-colors duration-(--duration-instant) hover:bg-ink/6 hover:text-ink pressed:bg-ink/10",
+});
+/** The marker of the current row: a bar on the leading edge, so the spot reads in the
+ *  margin before the label is read. */
+const marker = "absolute inset-y-1 start-0 w-0.5 rounded-pill bg-primary forced-colors:bg-[HighlightText]";
+/** The ids of every module on the way to `id`, so the row you are on is never folded away. */
+function pathTo(items, id) {
+    if (id === undefined)
+        return [];
+    for (const item of items) {
+        if (item.id === id)
+            return [];
+        if (item.children === undefined)
+            continue;
+        const below = pathTo(item.children, id);
+        if (below.length > 0 || item.children.some((c) => c.id === id))
+            return [item.id, ...below];
+    }
+    return [];
+}
+/**
+ * The sidebar of an ERP module: modules that open and close, the screens inside them with
+ * an icon and what is waiting there, and the row you are on marked.
+ *
+ * Context: the modules on the way to `current` start open even when `defaultExpanded` does
+ * not name them. A sidebar that loads with the current screen folded away answers «where am
+ * I» with a closed module, and that is the whole question it exists for.
+ */
+export function NavigationTree({ items, current, onNavigate, defaultExpanded = [], label, }) {
+    const copy = useUiCopy();
+    const number = useMemo(() => new Intl.NumberFormat(copy.locale), [copy.locale]);
+    const expanded = useMemo(() => [...new Set([...defaultExpanded, ...pathTo(items, current)])], 
+    // The initial state only: React Aria owns the expansion after the first render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []);
+    const render = (item, level) => {
+        const children = item.children ?? [];
+        const module = children.length > 0;
+        const Icon = item.icon;
+        /* The first step in puts a screen's label on the vertical of its module's label —
+           past the module's icon column — so a module and its screens read as one list of
+           words. Every step deeper is the system's nesting step. */
+        const indent = level > 1
+            ? {
+                paddingInlineStart: `calc(var(--spacing) * 4 + var(--size-icon-md) + var(--spacing-indent) * ${level - 2})`,
+            }
+            : undefined;
+        return (_jsxs(AriaNavigationTreeItem, { id: item.id, textValue: item.label, ...(module ? {} : { href: item.id }), className: ({ isCurrent, isFocusVisible }) => row({ isCurrent, isFocusVisible }), children: [_jsx(NavigationTreeItemContent, { children: ({ isCurrent, isCurrentAncestor, isExpanded }) => (_jsxs(_Fragment, { children: [isCurrent ? _jsx("span", { "aria-hidden": true, className: marker }) : null, _jsxs(Link, { className: link({ isModule: module }), style: indent, children: [Icon === undefined ? null : (_jsx(Icon, { className: `size-(--size-icon-md) shrink-0 ${isCurrent || (isCurrentAncestor && !isExpanded)
+                                            ? "text-primary"
+                                            : "text-muted"}`, strokeWidth: 2, "aria-hidden": true })), _jsx("span", { className: `min-w-0 flex-1 truncate ${isCurrentAncestor && !isExpanded ? "text-primary" : ""}`, children: item.label }), item.count === undefined || item.count <= 0 ? null : (_jsx("span", { className: `shrink-0 rounded-pill px-1.5 text-micro leading-normal font-medium tabular-nums ${isCurrent ? "bg-primary/12 text-primary" : "bg-ink/6 text-muted"}`, children: number.format(item.count) }))] }), module ? (_jsx(AriaButton, { slot: "chevron", className: ({ isFocusVisible }) => chevronButton({ isFocusVisible }), children: _jsx(ChevronRight, { className: `size-(--size-icon-sm) transition-transform duration-(--duration-quick) ease-(--ease-out) ${isExpanded ? "rotate-90" : ""}`, strokeWidth: 2, "aria-hidden": true }) })) : null] })) }), children.map((child) => render(child, level + 1))] }, item.id));
+    };
+    return (_jsx(AriaLocale, { children: _jsx(RouterProvider, { navigate: (id) => onNavigate?.(id), useHref: (id) => `#${id}`, children: _jsx(AriaNavigationTree, { "aria-label": label ?? copy.shell.menus, selectedRoute: current ?? null, defaultExpandedKeys: expanded, className: "flex w-full min-w-0 flex-col gap-px p-2 outline-0", children: items.map((item) => render(item, 1)) }) }) }));
+}

package/dist/components/navigation/commands.d.ts

@@ -0,0 +1,30 @@
+import type { LucideIcon } from "lucide-react";
+/** Something the palette can run: go to a screen, create a record, open a report. */
+export interface PaletteCommand {
+    id: string;
+    label: string;
+    /** The heading it is listed under: «Ir a…», «Crear…». Commands without one go first,
+     *  without a heading. */
+    section?: string;
+    icon?: LucideIcon;
+    /** The key that runs it without the palette, as it should be read: «⌘N», «Alt+F». It is
+     *  only drawn — the palette is where the shortcut gets learned, not where it is bound. */
+    shortcut?: string;
+    /** Other words that should find it: «factura» finds «Nueva venta» when the people who use
+     *  it call it that. */
+    keywords?: readonly string[];
+}
+/** The commands under each heading, headings in the order they first appear. */
+export declare function groupCommands(commands: readonly PaletteCommand[]): {
+    section: string | undefined;
+    commands: PaletteCommand[];
+}[];
+/**
+ * Whether a command answers a query. `contains` is the locale's comparison — React Aria's
+ * `useFilter` in the palette — so «facturacion» finds «Facturación» and an uppercase query
+ * finds a lowercase label.
+ *
+ * Every word of the query has to appear, in any order, in the label or the keywords:
+ * «nueva fac» finds «Nueva factura», and so does «factura nueva».
+ */
+export declare function commandMatches(command: PaletteCommand, query: string, contains: (text: string, part: string) => boolean): boolean;