@sincpro/web-ui 0.0.0-stage → 0.2.0

package/dist/components/listing/Pagination.js

@@ -0,0 +1,69 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { PAGE_SIZES } from "./pages.js";
+import { fillCopy, useUiCopy } from "../../foundations/copy.js";
+import { byDensity, useDensity } from "../../foundations/density.js";
+import { bySurface, useSurface } from "../../foundations/surface.js";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import { useId, useState } from "react";
+/* ---------------------------------------------------------------- *
+ *  THE FOOTER AND ITS PAGINATION
+ * ---------------------------------------------------------------- */
+/** How many of how many, and how I move to the next page.
+ *
+ *  **It lives ONCE and it is mounted in two places.** The normal destination is
+ *  the search bar: you search, you narrow down and you paginate on the same
+ *  line, without looking down to the footer to discover there are another
+ *  hundred and sixty. The footer (`ListingFooter`) existed only for the lists
+ *  that do NOT have a search box — there is no narrowing line there to put it on.
+ *
+ *  Two implementations of one pagination diverge at the first fix, so this is
+ *  the only one and both places receive it.
+ *
+ *  ── The range, not the page number ──────────────────────────────────
+ *
+ *  «1–25 de 187» answers three questions —where I am, how much I see, how much
+ *  there is— and «page 1 of 8» answers a single one, in units that depend on a
+ *  page size the user did not choose.
+ *
+ *  ── Why the page size is visible ────────────────────────────────────
+ *
+ *  Because it is the difference between scrolling eight times and scrolling
+ *  once. In a tool where somebody compares a hundred and eighty invoices,
+ *  leaving it fixed at 25 forces paginating over something that is not a
+ *  product decision. */
+export function Pagination({ from, to, total, pageSize, pageSizes = PAGE_SIZES, onPageSizeChange, onPrev, onNext, surface, }) {
+    const d = useDensity();
+    const copy = useUiCopy();
+    const activeSurface = useSurface(surface);
+    const [editing, setEditing] = useState(false);
+    const [draft, setDraft] = useState("");
+    const listId = useId();
+    const faint = bySurface(activeSurface, "text-muted", "text-chrome-muted");
+    const strong = bySurface(activeSurface, "text-ink", "text-chrome-ink");
+    const arrow = `inline-flex size-(--size-control-sm) items-center justify-center rounded-pill transition-colors duration-(--duration-instant) disabled:opacity-30 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary ${bySurface(activeSurface, "text-muted not-disabled:hover:bg-ink/6 not-disabled:hover:text-ink", "text-chrome-muted not-disabled:hover:bg-chrome-ink/12 not-disabled:hover:text-chrome-ink")}`;
+    const canEdit = pageSize !== undefined && onPageSizeChange !== undefined && d === "comfortable";
+    const sizes = pageSize !== undefined && !pageSizes.includes(pageSize)
+        ? [...pageSizes, pageSize]
+        : pageSizes;
+    function commitSize(raw) {
+        const next = Number(raw);
+        if (!Number.isFinite(next) || next < 1) {
+            setEditing(false);
+            return;
+        }
+        onPageSizeChange?.(Math.floor(next));
+        setEditing(false);
+    }
+    return (_jsxs("div", { className: `flex shrink-0 items-center ${byDensity(d, "gap-1", "gap-0.5")}`, children: [editing && canEdit ? (_jsxs(_Fragment, { children: [_jsx("input", { autoFocus: true, type: "number", min: 1, step: 1, list: listId, value: draft, onChange: (e) => setDraft(e.target.value), onBlur: () => commitSize(draft), onKeyDown: (e) => {
+                            if (e.key === "Enter") {
+                                e.preventDefault();
+                                commitSize(draft);
+                            }
+                            if (e.key === "Escape")
+                                setEditing(false);
+                        }, "aria-label": copy.pager.size, className: `h-(--size-control-sm) w-24 rounded-control border px-1.5 text-micro tabular-nums focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary ${bySurface(activeSurface, "border-line-strong bg-surface text-ink", "border-chrome-ink/45 bg-chrome-ink/8 text-chrome-ink")}` }), _jsx("datalist", { id: listId, children: sizes.map((n) => (_jsx("option", { value: n }, n))) })] })) : (_jsxs("span", { className: `text-micro tabular-nums whitespace-nowrap ${faint}`, children: [canEdit ? (_jsxs("button", { type: "button", onClick: () => {
+                            setDraft(String(pageSize));
+                            setEditing(true);
+                        }, title: fillCopy(copy.pager.sizeHint, { size: pageSize ?? 0 }), className: `rounded-control underline decoration-dotted underline-offset-4 transition-colors duration-(--duration-instant) ${strong} ${bySurface(activeSurface, "decoration-line-strong hover:decoration-primary", "decoration-chrome-ink/40 hover:decoration-chrome-link")} focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary`, children: [from.toLocaleString(copy.locale), "\u2013", to.toLocaleString(copy.locale)] })) : (_jsxs("span", { className: strong, children: [from.toLocaleString(copy.locale), "\u2013", to.toLocaleString(copy.locale)] })), _jsx("span", { className: "mx-1", children: "/" }), total.toLocaleString(copy.locale)] })), _jsxs("span", { className: "flex items-center", children: [_jsx("button", { type: "button", onClick: onPrev, disabled: from <= 1, "aria-label": copy.pager.prev, title: copy.pager.prev, className: arrow, children: _jsx(ChevronLeft, { className: "size-(--size-icon-md)", strokeWidth: 2 }) }), _jsx("button", { type: "button", onClick: onNext, disabled: to >= total, "aria-label": copy.pager.next, title: copy.pager.next, className: arrow, children: _jsx(ChevronRight, { className: "size-(--size-icon-md)", strokeWidth: 2 }) })] })] }));
+}

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

@@ -0,0 +1,33 @@
+import type { LucideIcon } from "lucide-react";
+import type { ReactNode } from "react";
+/**
+ * One record as a card — the board presentation of a list.
+ *
+ * Context: the board drew this card inline, and a list that wanted its own card wrote its
+ * own `div` — which looked the same and could not be opened: the default card was a button
+ * with `onOpen`, the custom one was not. A card is the record's door in the board the way a
+ * row is in the table, so it is a component and it is always pressable when there is
+ * somewhere to go.
+ *
+ * Its hierarchy is the row's: the state first (what it is), the name as the entry point,
+ * the facts below in the quiet size.
+ */
+export declare function RecordCard({ title, tags, meta, figure, media, onOpen, }: {
+    /** The record's name — the entry point of the card. */
+    title: ReactNode;
+    /** The state, as a `Tag`: read before the name, the way a board is scanned. */
+    tags?: ReactNode;
+    /** The facts that tell two cards apart — a number, a date. */
+    meta?: ReactNode;
+    /** The record's key figure, on the right of the name — an amount. */
+    figure?: ReactNode;
+    /** The record's picture — a product photo, a customer's logo — or its icon. A board of
+     *  products is recognised by the pictures before a single name is read. */
+    media?: {
+        src?: string;
+        alt?: string;
+        icon?: LucideIcon;
+    };
+    /** Opens the record. Without it the card is not pressable. */
+    onOpen?: () => void;
+}): import("react").JSX.Element;

package/dist/components/listing/RecordCard.js

@@ -0,0 +1,22 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Thumb } from "../../primitives/cell/CellStack.js";
+/**
+ * One record as a card — the board presentation of a list.
+ *
+ * Context: the board drew this card inline, and a list that wanted its own card wrote its
+ * own `div` — which looked the same and could not be opened: the default card was a button
+ * with `onOpen`, the custom one was not. A card is the record's door in the board the way a
+ * row is in the table, so it is a component and it is always pressable when there is
+ * somewhere to go.
+ *
+ * Its hierarchy is the row's: the state first (what it is), the name as the entry point,
+ * the facts below in the quiet size.
+ */
+export function RecordCard({ title, tags, meta, figure, media, onOpen, }) {
+    const body = (_jsxs(_Fragment, { children: [media === undefined ? null : (_jsx(Thumb, { size: "lg", ...(media.src === undefined ? {} : { src: media.src }), ...(media.alt === undefined ? {} : { alt: media.alt }), ...(media.icon === undefined ? {} : { icon: media.icon }) })), tags, _jsxs("div", { className: "flex min-w-0 items-baseline justify-between gap-3", children: [_jsx("p", { className: "min-w-0 truncate text-lead font-medium text-ink", children: title }), figure === undefined ? null : (_jsx("p", { className: "shrink-0 text-lead font-semibold tabular-nums text-ink", children: figure }))] }), meta === undefined ? null : (_jsx("p", { className: "text-micro tabular-nums text-muted", children: meta }))] }));
+    const box = "flex min-w-0 flex-col gap-2 rounded-box border border-line bg-surface p-4 text-left";
+    if (onOpen === undefined)
+        return _jsx("div", { className: box, children: body });
+    return (_jsx("button", { type: "button", onClick: onOpen, className: `${box} transition-colors duration-(--duration-instant) hover:border-line-strong focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary`, children: body }));
+}

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

@@ -0,0 +1,7 @@
+import type { ReactNode } from "react";
+export declare function RecordLink({ children, onClick, title, }: {
+    children: ReactNode;
+    onClick?: () => void;
+    /** The whole name, when the cell shows only what fits. */
+    title?: string;
+}): import("react").JSX.Element;

package/dist/components/listing/RecordLink.js

@@ -0,0 +1,22 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+/* ==================================================================== *
+ *  THE NAME THAT OPENS THE RECORD.
+ *
+ *  Every list was drawing this button by hand, and each one picked a
+ *  different cutoff: 28ch, 32ch, 42ch. The name is a link — blue, because
+ *  it goes somewhere — and it truncates at the cell, not at a number
+ *  somebody guessed. The click does not also open the row: the name and
+ *  the row are two gestures, and both have to arrive.
+ * ==================================================================== */
+export function RecordLink({ children, onClick, title, }) {
+    /* With nowhere to go it is the record's name, not a button: a control that looks pressable
+       and does nothing is a dead end. */
+    if (onClick === undefined) {
+        return (_jsx("span", { ...(title === undefined ? {} : { title }), className: "block min-w-0 max-w-full truncate text-meta font-medium text-ink", children: children }));
+    }
+    return (_jsx("button", { type: "button", ...(title === undefined ? {} : { title }), onClick: (event) => {
+            event.stopPropagation();
+            onClick?.();
+        }, className: "block min-w-0 max-w-full truncate rounded-control text-left text-meta font-medium text-primary transition-colors duration-(--duration-instant) hover:underline hover:underline-offset-4 focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary", children: children }));
+}

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

@@ -0,0 +1,110 @@
+import { type MenuGroup } from "../../primitives/menu/Menu.js";
+import type { LucideIcon } from "lucide-react";
+import type { ReactNode } from "react";
+/** A record in two lines: big name on top, metadata below.
+ *
+ *  ── The name opens, the body peeks ──────────────────────────────────
+ *
+ *  Two different targets and zero waiting. The name is a LINK and opens with
+ *  one click; the rest of the row does a preview. It used to open with a double
+ *  click, and to be able to tell it apart from the single one ALL clicks had to
+ *  be delayed by 220 ms — a name painted as a link discovers itself, «try
+ *  double clicking» is written nowhere.
+ *
+ *  The gesture is invisible if nothing says so, so on hover `⇱ abrir` appears:
+ *  it is learned in one hover and never has to be explained.
+ *
+ *  ── The metadata is in plain sight ──────────────────────────────────
+ *
+ *  «some metadata that might help is not visible» — and it was literal: to know
+ *  whether `FAC/2026/0118` was paid or overdue you had to open it. */
+export declare function Row({ icon: Icon, name, onOpen, onPeek, tags, meta, selected, onSelectedChange, actions, more, onMoreSelect, openHint, children, copy: copyAs, }: {
+    icon?: LucideIcon;
+    name: string;
+    /** The copy button among the row's actions: on by default, copying the row's name — the
+     *  number of an invoice, a customer — without opening it. A string copies that instead;
+     *  `false` removes it. */
+    copy?: string | false;
+    onOpen?: () => void;
+    onPeek?: () => void;
+    tags?: ReactNode;
+    /** The secondary data, already formatted. In mono: it aligns across rows. */
+    meta?: string;
+    selected?: boolean;
+    onSelectedChange?: (next: boolean) => void;
+    actions?: ReactNode;
+    /** The `⋯` menu. **Without this the button is not drawn**: there used to be a
+     *  fixed one that opened nothing — a control that exists and does nothing
+     *  teaches people not to press it, and after that nobody presses the one that
+     *  does work. */
+    more?: readonly MenuGroup[];
+    onMoreSelect?: (id: string) => void;
+    /** What happens on open, when «as a panel» is not true: «open the order that
+     *  produced it». It is the `title` and the accessible name. */
+    openHint?: string;
+    /** What the resource PRODUCED, hanging below. Context: the indent and the
+     *  rule are put there by the system and not by the view, because the
+     *  relationship «this came out of that» has to look the same in the four
+     *  lists that need it. */
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * EL ENCABEZADO DE LA PRESENTACIÓN DE FILAS.
+ *
+ * Context: la tabla y la planilla dicen qué es cada columna; la lista de filas
+ * no decía nada. Ochenta renglones con «Ferretería Sur · 13 sept · Bs 12.480» a la
+ * derecha y una ficha al final, y había que deducir qué era cada número — o
+ * cambiar a la tabla para averiguarlo, que es cambiar de presentación para leer
+ * la misma pantalla.
+ *
+ * **No son columnas: son las ZONAS de la fila, rotuladas.** Una fila tiene un
+ * nombre que se estira, un `meta` que es UNA cadena ya formateada, y una
+ * columna de fichas de ancho fijo. Rotularlas como si fueran tres columnas
+ * alineadas sería mentir sobre lo que hay debajo: el `meta` de una fila puede
+ * decir tres cosas y el de otra dos.
+ *
+ * Por eso calca la caja de `Row` —mismo padding, mismos huecos, mismos
+ * espaciadores de casilla, ícono y acciones— en vez de declarar un ancho
+ * propio. Si `Row` cambia su geometría, esto la sigue.
+ */
+export declare function RowHeader({ name, meta, tags, withSelection, withIcon, withActions, }: {
+    name: string;
+    meta?: string;
+    tags?: string;
+    /** Los espaciadores de la izquierda. Los pone quien dibuja las filas, porque
+     *  es el único que sabe si esta lista elige y si sus filas tienen ícono. */
+    withSelection?: boolean;
+    withIcon?: boolean;
+    /** La zona de acciones de la derecha ocupa su lugar aunque esté invisible
+     *  —así nada se corre al pasar el puntero—, así que el rótulo de las fichas
+     *  queda desalineado si acá no se reserva lo mismo. */
+    withActions?: boolean;
+}): import("react").JSX.Element;
+/**
+ * The header of a group inside a list.
+ *
+ * Context: grouping existed ONLY inside `DataTable`, so changing presentation
+ * —from table to rows— lost the grouping. Grouping belongs to the SET and not
+ * to the presentation; that is why it lives here.
+ *
+ * **`field` is drawn, and it is not decoration.** With one level nobody needed
+ * it: there was a single axis and everyone knew what it was. With several,
+ * «2026-09» does not say whether it is when the thing was registered or when it
+ * ran, and two consecutive headers can read as siblings when one is inside the
+ * other. The field names the cut; the indent says how deep it is.
+ */
+export declare function GroupHeader({ field, label, count, detail, depth, open, onToggle, }: {
+    /** By which field this pile was cut. Without it a value is ambiguous as soon
+     *  as there is more than one level. */
+    field?: string;
+    label: string;
+    count?: number;
+    /** What the pile ADDS UP TO, already written: «412 facturas · Bs 1.204.933». A
+     *  folded pile that only says how many there are hides the answer instead of
+     *  summarising it. */
+    detail?: string;
+    /** How deep the pile is. `0` is the first level. */
+    depth?: number;
+    open?: boolean;
+    onToggle?: () => void;
+}): import("react").JSX.Element;

package/dist/components/listing/Row.js

@@ -0,0 +1,123 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { RecordLink } from "./RecordLink.js";
+import { fillCopy, useUiCopy } from "../../foundations/copy.js";
+import { byDensity, useDensity } from "../../foundations/density.js";
+import { stickyTop } from "../../foundations/sticky.js";
+import { Menu } from "../../primitives/menu/Menu.js";
+import { CopyButton } from "../../primitives/value/Copyable.js";
+import { ChevronRight, MoreHorizontal, SquareArrowOutUpRight } from "lucide-react";
+/* ---------------------------------------------------------------- *
+ *  THE RICH ROW — the other density
+ * ---------------------------------------------------------------- */
+/** A record in two lines: big name on top, metadata below.
+ *
+ *  ── The name opens, the body peeks ──────────────────────────────────
+ *
+ *  Two different targets and zero waiting. The name is a LINK and opens with
+ *  one click; the rest of the row does a preview. It used to open with a double
+ *  click, and to be able to tell it apart from the single one ALL clicks had to
+ *  be delayed by 220 ms — a name painted as a link discovers itself, «try
+ *  double clicking» is written nowhere.
+ *
+ *  The gesture is invisible if nothing says so, so on hover `⇱ abrir` appears:
+ *  it is learned in one hover and never has to be explained.
+ *
+ *  ── The metadata is in plain sight ──────────────────────────────────
+ *
+ *  «some metadata that might help is not visible» — and it was literal: to know
+ *  whether `FAC/2026/0118` was paid or overdue you had to open it. */
+export function Row({ icon: Icon, name, onOpen, onPeek, tags, meta, selected, onSelectedChange, actions, more, onMoreSelect, openHint, children, copy: copyAs, }) {
+    const d = useDensity();
+    const copy = useUiCopy();
+    const openAs = openHint ?? copy.shell.openAsPanel;
+    const row = (
+    /* A `div` and not an `li`: whoever composes decides whether this is a list,
+       a table or a branch of a tree. And the zone that peeks is a `div` with
+       `onClick` and not a `button` — the actions are buttons too, and a button
+       inside another one is invalid HTML: the browser takes it apart and the
+       clicks get lost. */
+    _jsx("div", { className: "border-b border-line px-1 py-0.5 last:border-b-0", children: _jsxs("div", { "data-slot": "row", 
+            /* The hairline stays on the shell, full width: eighty similar names with
+             no rule between them read as a paragraph. The wash is the inner row,
+             inset and rounded, so the hover is a mark and not a stripe. The inner
+             padding is shorter by exactly that inset, so the text does not move. */
+            className: `group/row flex min-w-0 items-center rounded-control transition-colors duration-(--duration-instant) hover:bg-ink/4 ${byDensity(d, "gap-3 px-2 py-2", "gap-2 px-1.5 py-1")}`, 
+            /* `onPeek` con `onOpen` de reserva: quien sólo declara `onOpen` —lo
+             natural si nunca oyó hablar de la vista previa— tiene que poder abrir
+             igual haciendo click en cualquier parte de la fila, no sólo en el
+             nombre. Con la vista previa apagada (`PeekLayer.tsx`) esto es hoy el
+             caso de todos: un click en la fila abre, sin más. */
+            onClick: onPeek ?? onOpen, role: "presentation", children: [onSelectedChange === undefined ? null : (_jsx("input", { type: "checkbox", checked: selected ?? false, "aria-label": fillCopy(copy.selection.named, { name }), onChange: (e) => onSelectedChange(e.target.checked), onClick: (e) => e.stopPropagation(), className: "size-3.5 shrink-0 cursor-pointer accent-primary" })), Icon === undefined ? null : (_jsx(Icon, { className: "size-(--size-icon-md) shrink-0 text-muted", strokeWidth: 1.75, "aria-hidden": true })), _jsxs("div", { className: `flex min-w-0 shrink grow basis-(--container-name) flex-wrap items-center gap-y-0 ${byDensity(d, "gap-x-3", "gap-x-2")}`, children: [_jsx("span", { className: "min-w-0 grow basis-(--container-name)", children: _jsx(RecordLink, { ...((onOpen ?? onPeek) === undefined ? {} : { onClick: (onOpen ?? onPeek) }), title: name, children: name }) }), meta === undefined ? null : (
+                        /* Wrapped or not, the metadata is still there —it is what saves
+                         having to open a set to know whether it is a thousand rows or a
+                         million— and it truncates instead of wrapping into itself: three
+                         lines per row in a 480 px drawer means three rows fit on screen. */
+                        _jsx("span", { className: "min-w-0 truncate text-micro tabular-nums text-muted", children: meta }))] }), tags === undefined ? null : (_jsx("span", { className: "flex min-w-fit shrink basis-(--container-tags) items-center justify-end gap-1.5", children: tags })), _jsxs("span", { className: "flex shrink-0 items-center gap-1 opacity-0 transition-opacity duration-(--duration-instant) group-hover/row:opacity-100 focus-within:opacity-100 pointer-coarse:opacity-100", children: [actions, copyAs === false ? null : (_jsx(CopyButton, { value: copyAs ?? name, label: fillCopy(copy.copyable.field, { label: name }) })), onOpen === undefined ? null : (_jsx("button", { type: "button", onClick: (e) => {
+                                e.stopPropagation();
+                                onOpen();
+                            }, title: openAs, "aria-label": `${openAs}: ${name}`, className: "inline-flex size-(--size-control-sm) items-center justify-center rounded-pill text-muted transition-colors duration-(--duration-instant) hover:bg-ink/6 hover:text-ink focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary", children: _jsx(SquareArrowOutUpRight, { className: "size-(--size-icon-sm)", strokeWidth: 2 }) })), more === undefined || more.length === 0 ? null : (_jsx("span", { onClick: (e) => e.stopPropagation(), role: "presentation", children: _jsx(Menu, { label: fillCopy(copy.selection.moreOf, { name }), groups: more, icon: MoreHorizontal, iconOnly: true, chevron: false, align: "end", width: "sm", variant: "text", ...(onMoreSelect === undefined ? {} : { onSelect: onMoreSelect }) }) }))] })] }) }));
+    if (children === undefined)
+        return row;
+    /* What the resource produced, hanging below. The indent reaches up to where
+       the name starts —not up to the edge— so the rule falls exactly below the
+       icon and the relationship reads without reading: this came out of that.
+  
+       The child is NOT another `Row`: an invoice line does not open, does not get
+       selected and has no actions of its own. Treating it as a row would make it promise
+       all of that. */
+    return (_jsxs("div", { "data-slot": "branch", className: "flex min-w-0 flex-col", children: [row, _jsx("div", { className: `flex min-w-0 flex-col gap-1 border-l border-line-strong ${byDensity(d, "mb-2 ml-8 pb-0.5 pl-3 pr-3", "mb-1.5 ml-6 pl-2.5 pr-2.5")}`, children: children })] }));
+}
+/**
+ * EL ENCABEZADO DE LA PRESENTACIÓN DE FILAS.
+ *
+ * Context: la tabla y la planilla dicen qué es cada columna; la lista de filas
+ * no decía nada. Ochenta renglones con «Ferretería Sur · 13 sept · Bs 12.480» a la
+ * derecha y una ficha al final, y había que deducir qué era cada número — o
+ * cambiar a la tabla para averiguarlo, que es cambiar de presentación para leer
+ * la misma pantalla.
+ *
+ * **No son columnas: son las ZONAS de la fila, rotuladas.** Una fila tiene un
+ * nombre que se estira, un `meta` que es UNA cadena ya formateada, y una
+ * columna de fichas de ancho fijo. Rotularlas como si fueran tres columnas
+ * alineadas sería mentir sobre lo que hay debajo: el `meta` de una fila puede
+ * decir tres cosas y el de otra dos.
+ *
+ * Por eso calca la caja de `Row` —mismo padding, mismos huecos, mismos
+ * espaciadores de casilla, ícono y acciones— en vez de declarar un ancho
+ * propio. Si `Row` cambia su geometría, esto la sigue.
+ */
+export function RowHeader({ name, meta, tags, withSelection = false, withIcon = false, withActions = false, }) {
+    const d = useDensity();
+    const rotulo = "truncate text-micro font-medium text-muted";
+    return (_jsxs("div", { "data-slot": "row-header", 
+        /* Se pega debajo de la barra de la lista, como el encabezado de la tabla
+           y el de la planilla. Ver `system/sticky.tsx`. */
+        className: `sticky z-10 flex min-w-0 items-center border-b border-line-strong bg-ground ${byDensity(d, "gap-3 px-3 py-2", "gap-2 px-2.5 py-1.5")}`, style: stickyTop, role: "presentation", children: [!withSelection ? null : _jsx("span", { className: "size-3.5 shrink-0", "aria-hidden": true }), !withIcon ? null : _jsx("span", { className: "size-(--size-icon-md) shrink-0", "aria-hidden": true }), _jsxs("div", { className: `flex min-w-0 shrink grow basis-(--container-name) flex-wrap items-center gap-y-0 ${byDensity(d, "gap-x-3", "gap-x-2")}`, children: [_jsx("span", { className: `min-w-0 grow basis-(--container-name) ${rotulo}`, children: name }), meta === undefined ? null : _jsx("span", { className: `min-w-0 ${rotulo}`, children: meta })] }), tags === undefined ? null : (_jsx("span", { className: "flex min-w-fit shrink basis-(--container-tags) items-center justify-end", children: _jsx("span", { className: rotulo, children: tags }) })), !withActions ? null : (_jsx("span", { className: "size-(--size-control-sm) shrink-0", "aria-hidden": true }))] }));
+}
+/**
+ * The header of a group inside a list.
+ *
+ * Context: grouping existed ONLY inside `DataTable`, so changing presentation
+ * —from table to rows— lost the grouping. Grouping belongs to the SET and not
+ * to the presentation; that is why it lives here.
+ *
+ * **`field` is drawn, and it is not decoration.** With one level nobody needed
+ * it: there was a single axis and everyone knew what it was. With several,
+ * «2026-09» does not say whether it is when the thing was registered or when it
+ * ran, and two consecutive headers can read as siblings when one is inside the
+ * other. The field names the cut; the indent says how deep it is.
+ */
+export function GroupHeader({ field, label, count, detail, depth = 0, open = true, onToggle, }) {
+    const d = useDensity();
+    const copy = useUiCopy();
+    const content = (_jsxs(_Fragment, { children: [onToggle === undefined ? null : (_jsx(ChevronRight, { className: `size-(--size-icon-sm) shrink-0 text-muted transition-transform duration-(--duration-instant) ${open ? "rotate-90" : ""}`, strokeWidth: 2, "aria-hidden": true })), field === undefined ? null : (_jsx("span", { className: "shrink-0 text-micro text-muted/70", children: field })), _jsx("span", { className: "truncate text-micro font-medium text-ink", children: label }), count === undefined ? null : (_jsx("span", { className: "inline-flex shrink-0 items-center rounded-pill border border-line-strong bg-ink/5 px-2 py-0.5 text-micro tabular-nums text-muted", children: count.toLocaleString(copy.locale) })), detail === undefined ? null : (_jsx("span", { className: "shrink-0 text-micro tabular-nums text-muted", children: detail }))] }));
+    /* La sangría va en el relleno de la izquierda y no en un margen: el
+       encabezado tiene fondo y borde inferior, y un margen los cortaría antes del
+       borde de la lista — la banda dejaría de leerse como una franja. El hover
+       no reemplaza ese fondo: es una marca metida adentro, redondeada. */
+    const box = `flex min-w-0 items-center gap-2 border-b border-line bg-ground ${byDensity(d, "px-3 py-1.5", "px-2.5 py-1")}`;
+    const indent = depth === 0 ? undefined : { paddingLeft: `calc(var(--spacing-indent) * ${depth})` };
+    const mark = (_jsx("span", { "aria-hidden": true, className: "pointer-events-none absolute inset-x-1 inset-y-0.5 rounded-control group-hover/head:bg-ink/4" }));
+    return onToggle === undefined ? (_jsx("div", { className: box, style: indent, children: content })) : (_jsxs("button", { type: "button", onClick: onToggle, "aria-expanded": open, style: indent, className: `group/head relative ${box} w-full text-left focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-primary`, children: [mark, content] }));
+}

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

@@ -0,0 +1,62 @@
+import type { Surface } from "../../foundations/types.js";
+import type { SortState } from "../../primitives/table/Table.js";
+/**
+ * ORDENAR, cuando no hay encabezados donde hacer clic.
+ *
+ * Context: ordenar era una capacidad de `DataTable` y de nadie más. Se hacía
+ * clic en el encabezado de la columna, que es la forma correcta **cuando hay
+ * encabezados**. En filas, en tablero y en la planilla no los hay, así que
+ * cambiar de presentación no perdía sólo el orden puesto: perdía la posibilidad
+ * de ordenar. Es exactamente el mismo drift que tenía la agrupación.
+ *
+ * El orden es del CONJUNTO y no de la presentación, igual que los niveles y que
+ * lo plegado. Por eso el control vive en la barra y no adentro de la tabla, y
+ * por eso la tabla sigue teniendo además sus encabezados: son dos puertas a lo
+ * mismo, y la de los encabezados es más rápida cuando existe.
+ *
+ * ── Por qué es un `Menu` y el agrupador no ──────────────────────────
+ *
+ * Porque ordenar SÍ es elegir una opción: un campo y una dirección. No hay orden
+ * ni jerarquía que expresar —ordenar por dos campos a la vez es un desempate,
+ * que es otra pregunta y la hace el motor— así que una lista de tildes alcanza y
+ * no hace falta un editor.
+ */
+export type SortField<T = unknown> = {
+    field: string;
+    label: string;
+    /**
+     * Por qué valor se ordena, cuando ordena el NAVEGADOR.
+     *
+     * Ausente = ya viene ordenado de donde salió. Es la misma división que tiene
+     * el agrupado con `piles`: un conjunto que el servidor pagina no se puede
+     * ordenar acá —ordenar doce filas de ciento ochenta y siete da un orden
+     * falso— así que ahí el orden viaja en la lectura y esto sólo lo refleja.
+     */
+    value?: (item: T) => string | number | null | undefined;
+    /** Qué quiere decir «ascendente» para este campo. Sin esto, «A → Z».
+     *  Una fecha asciende de vieja a nueva y un importe de chico a grande, y
+     *  decirlo evita el clic de prueba. */
+    ascLabel?: string;
+    descLabel?: string;
+};
+export type SortMenuProps = {
+    /** Por qué campos se puede ordenar. Sin ninguno, el control no se dibuja. */
+    fields: readonly SortField<never>[];
+    sort: SortState | null;
+    onSortChange: (next: SortState | null) => void;
+    surface?: Surface;
+};
+/**
+ * Las filas, ordenadas acá.
+ *
+ * Sólo cuando el campo activo declara `value`; si no, se devuelven tal cual —
+ * ordenar una página de un conjunto que se pagina afuera produce un orden que es
+ * mentira, porque ordena las doce que llegaron y no las ciento ochenta y siete.
+ *
+ * Los faltantes van SIEMPRE al final, suba o baje el orden. Es lo que hace
+ * cualquier planilla, y la razón es que un vacío no es «el más chico»: es la
+ * ausencia de respuesta, y ponerlo primero al invertir el orden llena la primera
+ * pantalla con las filas que menos dicen.
+ */
+export declare function sortItems<T>(items: readonly T[], fields: readonly SortField<T>[], sort: SortState | null | undefined): readonly T[];
+export declare function SortMenu({ fields, sort, onSortChange, surface }: SortMenuProps): import("react").JSX.Element | null;

package/dist/components/listing/SortMenu.js

@@ -0,0 +1,105 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useUiCopy } from "../../foundations/copy.js";
+import { Menu } from "../../primitives/menu/Menu.js";
+import { ArrowDownUp, ArrowDownWideNarrow, ArrowUpNarrowWide } from "lucide-react";
+/**
+ * Las filas, ordenadas acá.
+ *
+ * Sólo cuando el campo activo declara `value`; si no, se devuelven tal cual —
+ * ordenar una página de un conjunto que se pagina afuera produce un orden que es
+ * mentira, porque ordena las doce que llegaron y no las ciento ochenta y siete.
+ *
+ * Los faltantes van SIEMPRE al final, suba o baje el orden. Es lo que hace
+ * cualquier planilla, y la razón es que un vacío no es «el más chico»: es la
+ * ausencia de respuesta, y ponerlo primero al invertir el orden llena la primera
+ * pantalla con las filas que menos dicen.
+ */
+export function sortItems(items, fields, sort) {
+    if (sort === null || sort === undefined)
+        return items;
+    const field = fields.find((one) => one.field === sort.key);
+    if (field?.value === undefined)
+        return items;
+    const read = field.value;
+    const sign = sort.direction === "asc" ? 1 : -1;
+    return [...items].sort((a, b) => {
+        const left = read(a);
+        const right = read(b);
+        const leftMissing = left === null || left === undefined || left === "";
+        const rightMissing = right === null || right === undefined || right === "";
+        if (leftMissing && rightMissing)
+            return 0;
+        if (leftMissing)
+            return 1;
+        if (rightMissing)
+            return -1;
+        if (typeof left === "number" && typeof right === "number")
+            return (left - right) * sign;
+        return String(left).localeCompare(String(right)) * sign;
+    });
+}
+export function SortMenu({ fields, sort, onSortChange, surface }) {
+    const copy = useUiCopy();
+    if (fields.length === 0)
+        return null;
+    const current = fields.find((one) => one.field === sort?.key);
+    const groups = [
+        {
+            label: copy.sorting.by,
+            options: fields.map((one) => ({
+                id: one.field,
+                label: one.label,
+                checked: one.field === sort?.key,
+            })),
+        },
+        /* La dirección sólo cuando hay algo ordenado: «descendente» sin campo no
+           ordena nada, y una opción que no hace nada es una opción que se prueba. */
+        ...(current === undefined
+            ? []
+            : [
+                {
+                    options: [
+                        {
+                            id: "__asc__",
+                            label: current.ascLabel ?? copy.sorting.asc,
+                            icon: ArrowUpNarrowWide,
+                            checked: sort?.direction === "asc",
+                        },
+                        {
+                            id: "__desc__",
+                            label: current.descLabel ?? copy.sorting.desc,
+                            icon: ArrowDownWideNarrow,
+                            checked: sort?.direction === "desc",
+                        },
+                    ],
+                },
+                { options: [{ id: "__none__", label: copy.sorting.clear }] },
+            ]),
+    ];
+    return (_jsx(Menu, { label: current === undefined ? copy.sorting.label : current.label, icon: sort === null || sort === undefined
+            ? ArrowDownUp
+            : sort.direction === "asc"
+                ? ArrowUpNarrowWide
+                : ArrowDownWideNarrow, groups: groups, active: sort !== null && sort !== undefined, size: "sm", width: "sm", closeOnSelect: false, ...(surface === undefined ? {} : { surface }), onSelect: (id) => {
+            if (id === "__none__")
+                return onSortChange(null);
+            if (id === "__asc__") {
+                return onSortChange(sort === null ? null : { ...sort, direction: "asc" });
+            }
+            if (id === "__desc__") {
+                return onSortChange(sort === null ? null : { ...sort, direction: "desc" });
+            }
+            /* Volver a elegir el campo que ya está puesto DA VUELTA la dirección, que
+               es lo que hace el clic en un encabezado. Sin eso, invertir el orden son
+               dos gestos en un menú y uno en la tabla — la misma capacidad costando
+               distinto según la presentación. */
+            if (sort?.key === id) {
+                return onSortChange({
+                    key: id,
+                    direction: sort.direction === "asc" ? "desc" : "asc",
+                });
+            }
+            onSortChange({ key: id, direction: "asc" });
+        } }));
+}

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

@@ -0,0 +1,24 @@
+import type { Surface } from "../../foundations/types.js";
+import type { LucideIcon } from "lucide-react";
+/** How the same list is shown: table, board, timeline.
+ *
+ *  The icons go together and touching —a segmented group and not three loose
+ *  buttons— because they are MUTUALLY EXCLUSIVE options of a single question.
+ *  Three separate buttons read as three different actions, and then it is not
+ *  understood that choosing one turns the other off.
+ *
+ *  The label goes in the `title` and in the `aria-label`, never drawn: they are
+ *  three silhouettes that are learned once and recognized afterwards without
+ *  reading, and writing them out would burn the width the search box needs. */
+export interface ViewOption {
+    id: string;
+    label: string;
+    icon: LucideIcon;
+}
+export declare function ViewSwitcher({ options, current, onSelect, surface, }: {
+    options: readonly ViewOption[];
+    current: string;
+    onSelect?: (id: string) => void;
+    /** By default it inherits it from the surface that wraps it. */
+    surface?: Surface;
+}): import("react").JSX.Element;

package/dist/components/listing/ViewSwitcher.js

@@ -0,0 +1,16 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useUiCopy } from "../../foundations/copy.js";
+import { bySurface, useSurface } from "../../foundations/surface.js";
+export function ViewSwitcher({ options, current, onSelect, surface, }) {
+    const activeSurface = useSurface(surface);
+    const copy = useUiCopy();
+    const rule = bySurface(activeSurface, "border-line-strong", "border-chrome-ink/45");
+    return (_jsx("div", { role: "group", "aria-label": copy.present.group, className: `flex shrink-0 items-center overflow-hidden rounded-control border ${rule}`, children: options.map((o, i) => {
+            const here = o.id === current;
+            const Icon = o.icon;
+            return (_jsx("button", { type: "button", onClick: () => onSelect?.(o.id), "aria-pressed": here, title: o.label, "aria-label": o.label, className: `inline-flex size-(--size-control-sm) items-center justify-center transition-colors duration-(--duration-instant) focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-primary ${i === 0 ? "" : `border-l ${rule}`} ${here
+                    ? bySurface(activeSurface, "bg-ink/8 text-ink", "bg-chrome-link/20 text-chrome-link")
+                    : bySurface(activeSurface, "bg-surface text-muted hover:bg-ink/5 hover:text-ink", "bg-chrome-ink/6 text-chrome-muted hover:bg-chrome-ink/14 hover:text-chrome-ink")}`, children: _jsx(Icon, { className: "size-(--size-icon-md)", strokeWidth: 1.75 }) }, o.id));
+        }) }));
+}