@sincpro/web-ui 0.0.0-stage → 0.1.0

package/dist/components/listing/ListingBar.js

@@ -0,0 +1,105 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useUiCopy } from "../../foundations/copy.js";
+import { byDensity, useDensity } from "../../foundations/density.js";
+import { SurfaceProvider, useSurface } from "../../foundations/surface.js";
+import { Line } from "../../primitives/block/Line.js";
+import { X } from "lucide-react";
+/** THE BAR — two rows, two questions.
+ *
+ *      ┌──────────┬──────────────────────────────┬──────────────┐
+ *      │ crumbs   │ 🔍 search…  ⚙3               │ 1–8 of 187 ‹ › │
+ *      ├──────────┼──────────────────────────────┼──────────────┤
+ *      │ [New]    │ Facturas · 180 · 7 · 8       │ [columns] [▤][▦] │
+ *      └──────────┴──────────────────────────────┴──────────────┘
+ *        WHERE / HOW MUCH I SEE                    HOW I LOOK
+ *
+ *  Pagination answers how much of the filtered set is on screen, so it stays
+ *  with the search. Columns and the presentation switcher answer how the set
+ *  is looked at, so they sit with the actions — not next to the page range.
+ *  Putting the four of them on the search line is how the field and «1–80»
+ *  painted over each other the moment the window shrank.
+ *
+ *  ── Why it is two lines tall ────────────────────────────────────────
+ *
+ *  Because the three things that go on the left do not fit in one: a
+ *  comfortable button is 34 px tall, a list title may have to wrap onto two
+ *  lines, and below it goes a sentence saying what the list is made of. Forcing
+ *  it into a single line means shrinking the button —the defect we already
+ *  fixed— or truncating the title, which is worse: a list that cannot be named
+ *  in full is indistinguishable from the one next to it.
+ *
+ *  ── The selection transforms the bar, it does not add one ───────────
+ *
+ *  When rows get selected, the identity zone turns into «3 elegidas ✕» plus the
+ *  actions that apply. **In the same place and without pushing anything.** A
+ *  bar that appears shifts the list downwards right when somebody is ticking
+ *  checkboxes, and the row they were about to tick is no longer where it was.
+ *
+ *  The actions on the left do NOT go away: «Nuevo» stays available with three
+ *  rows selected, because selecting is not entering a mode. */
+export function ListingBar({ actions, title, description, counters, selection, search, pagination, views, crumbs, surface, }) {
+    const selecting = selection !== undefined && selection.count > 0;
+    const d = useDensity();
+    const copy = useUiCopy();
+    const activeSurface = useSurface(surface);
+    const isChrome = activeSurface === "chrome";
+    /* In compact the title and the description are NOT drawn, and it is not for
+       lack of room: in a preview or on a phone, the surface header already says
+       what I am looking at. Repeating it here burns the only line there is for
+       the search box — which is what is actually needed. */
+    const withIdentity = d === "comfortable";
+    /* Two rows, and the split is the same one as in a record:
+         1 · WHERE I AM and HOW MANY THERE ARE — crumbs, search, page range.
+         2 · WHAT I CAN DO and HOW I LOOK — actions, identity, columns / views.
+  
+       Views used to sit next to the pagination. On a narrow window the search
+       field and «1–80 / 211» painted over each other; columns and the switcher
+       were the extra weight on a line that only needed how MANY. */
+    const center = selecting ? (_jsxs("div", { className: "flex min-w-0 items-center gap-x-2", children: [_jsxs("span", { className: `inline-flex h-(--size-control-md) shrink-0 items-center gap-1.5 rounded-control pr-1 pl-2.5 text-meta font-medium ${isChrome ? "bg-chrome-ink/14 text-chrome-ink" : "bg-ink/8 text-ink"}`, children: [_jsx("span", { className: "tabular-nums", children: selection?.count.toLocaleString(copy.locale) }), copy.selection.chosen, _jsx("button", { type: "button", onClick: selection?.onClear, "aria-label": copy.selection.clear, title: copy.selection.clear, className: `inline-flex size-5 items-center justify-center rounded-pill transition-colors duration-(--duration-instant) ${isChrome ? "hover:bg-chrome-ink/20" : "hover:bg-primary/20"}`, children: _jsx(X, { className: "size-3", strokeWidth: 2.5 }) })] }), selection?.actions === undefined ? null : (_jsx("div", { className: "flex min-w-0 items-center gap-1.5", children: selection.actions }))] })) : search === undefined ? null : (
+    /* Selecting replaces the search box: what gets selected is over what is
+       ALREADY filtered, so searching there would change the set underneath the
+       selection. */
+    _jsx("div", { className: "w-full min-w-0", children: search }));
+    /* El campo de búsqueda va en el CENTRO de la línea, y centrado contra la
+       línea: pide `--container-search` y los dos lados se reparten lo que sobra
+       en mitades iguales. Antes tomaba el resto, así que un rastro largo a la
+       izquierda lo corría —y dos listas seguidas dibujaban su buscador en dos
+       lugares distintos—. Ver `primitives/block/Line.tsx`. */
+    const topRow = (_jsx(Line, { asks: "var(--container-crumb)", centerAsks: center === null ? "auto" : "var(--container-search)", gap: byDensity(d, "gap-x-4 gap-y-2", "gap-x-2 gap-y-1.5"), align: "items-start", start: crumbs, 
+        /* `overflow-x-clip` y NO `overflow-hidden`: lo que hay que recortar es el
+           ancho —que el campo no pinte encima de «1–80»—, y `hidden` en un eje
+           fuerza `auto` en el otro, así que también recortaba hacia ABAJO. El
+           panel de filtros del `SearchBar` cuelga con `absolute top-full`, o sea
+           justo afuera de esta caja: apretar el embudo abría un panel que nadie
+           veía. `clip` es el único valor que deja `visible` en el otro eje. */
+        center: center === null ? null : (_jsx("div", { className: "flex w-full min-w-0 items-center overflow-x-clip overflow-y-visible", children: center })), end: pagination }));
+    const bottomRow = actions === undefined && !withIdentity && views === undefined ? null : (
+    /* On a narrow list (a phone, a drawer) the name and its counters take the whole first
+       line and the action and the controls go below: squeezed between them, the
+       description wrapped one word per line. */
+    _jsxs("div", { className: `flex min-w-0 flex-wrap items-center gap-y-2 ${byDensity(d, "gap-x-4", "gap-x-2")}`, children: [actions === undefined ? null : (_jsx("div", { className: "flex shrink-0 items-center gap-1.5", children: actions })), !withIdentity ? null : (_jsxs("div", { className: "flex min-w-0 flex-1 flex-col @max-2xl:order-first @max-2xl:basis-full", children: [title === undefined ? null : (
+                    /* No `truncate`: the title may wrap onto two lines. A list that
+                       cannot be named in full is indistinguishable from the one next
+                       to it. */
+                    /* `title` and semibold: the name of the list is the entry point of the
+                       screen. At `lead` it was smaller than the metrics under it, so the
+                       largest thing on a list page was a number (measured: 1.46:1 over the
+                       body, below the ~1.5 an eye needs to find where to start). */
+                    _jsx("h2", { className: `text-title leading-tight font-semibold ${isChrome ? "text-chrome-ink" : "text-ink"}`, children: title })), description === undefined && counters === undefined ? null : (_jsxs("div", { className: "mt-0.5 flex min-w-0 flex-wrap items-baseline gap-x-3 gap-y-0.5", children: [counters?.map((c) => (_jsxs("span", { className: "flex items-baseline gap-1", children: [_jsx("span", { className: `text-meta font-medium tabular-nums ${isChrome ? "text-chrome-ink" : "text-ink"}`, children: typeof c.value === "number"
+                                            ? c.value.toLocaleString(copy.locale)
+                                            : c.value }), _jsx("span", { className: `text-micro ${isChrome ? "text-chrome-muted" : "text-muted"}`, children: c.label })] }, c.label))), description === undefined ? null : (_jsx("span", { className: `min-w-0 text-micro ${isChrome ? "text-chrome-muted" : "text-muted"}`, children: description }))] }))] })), views === undefined ? null : (_jsx("div", { className: "ml-auto flex shrink-0 items-center gap-2", children: views }))] }));
+    const bar = (_jsxs("div", { className: `flex min-w-0 flex-col ${byDensity(d, "gap-2", "gap-1.5")}`, children: [!isChrome && bottomRow !== null ? (_jsx("div", { className: "border-b border-line pb-2", children: topRow })) : (topRow), bottomRow] }));
+    /* On the canvas the bar is a light control band: white, a hairline below, the same
+       padding as the dark one — a list inside an application whose bar is already dark keeps
+       ONE dark band per screen. Without its own band the bar sat flush on the page and its
+       controls had nothing to belong to. */
+    if (!isChrome) {
+        return (_jsx(SurfaceProvider, { value: "canvas", children: _jsx("div", { className: `flex min-w-0 flex-col border-b border-line bg-surface ${byDensity(d, "px-3.5 py-2.5", "px-2.5 py-2")}`, children: bar }) }));
+    }
+    /* On the chrome the bar IS the band: the background reaches the edges and
+       everything inside inherits the surface, so there is no way to forget to
+       pass it — which is how the status bar ended up with the canvas palette on
+       top of the navy. */
+    return (_jsx(SurfaceProvider, { value: "chrome", children: _jsx("div", { className: `flex min-w-0 flex-col bg-chrome ${byDensity(d, "px-3.5 py-2.5", "px-2.5 py-2")}`, children: bar }) }));
+}

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

@@ -0,0 +1,36 @@
+import type { Surface } from "../../foundations/types.js";
+/** 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 declare function Pagination({ from, to, total, pageSize, pageSizes, onPageSizeChange, onPrev, onNext, surface, }: {
+    from: number;
+    to: number;
+    total: number;
+    pageSize?: number;
+    pageSizes?: readonly number[];
+    onPageSizeChange?: (next: number) => void;
+    onPrev?: () => void;
+    onNext?: () => void;
+    /** By default it inherits it from the surface that wraps it. */
+    surface?: Surface;
+}): import("react").JSX.Element;

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,106 @@
+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, }: {
+    icon?: LucideIcon;
+    name: string;
+    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,122 @@
+"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 { 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, }) {
+    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", children: [actions, 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;