@sincpro/web-ui 0.1.0 → 0.2.0

package/dist/primitives/tree/Tree.js

@@ -0,0 +1,74 @@
+"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 { byDensity, useDensity } from "../../foundations/density.js";
+import { cn, focusRing, tv } from "../../foundations/variants.js";
+import { Check, ChevronRight } from "lucide-react";
+import { Button as AriaButton, Checkbox as AriaCheckbox, Tree as AriaTree, TreeItem as AriaTreeItem, TreeItemContent, } from "react-aria-components";
+const row = tv({
+    extend: focusRing,
+    base: "group relative flex min-w-0 cursor-default items-center rounded-control text-meta text-ink -outline-offset-2 select-none forced-color-adjust-none",
+    variants: {
+        isSelected: {
+            true: "bg-primary/10 forced-colors:bg-[Highlight] forced-colors:text-[HighlightText]",
+        },
+        isHovered: { true: "" },
+    },
+    compoundVariants: [{ isSelected: false, isHovered: true, class: "bg-ink/4" }],
+});
+/* The chevron column is exactly one indent step wide, so a child's chevron lands under its
+   parent's name and the levels read as columns, not as a ragged edge. */
+const chevronButton = tv({
+    extend: focusRing,
+    base: "inline-flex size-(--spacing-indent) shrink-0 items-center justify-center rounded-mark text-muted transition-colors duration-(--duration-instant) hover:bg-ink/6 hover:text-ink pressed:bg-ink/10",
+});
+/** Every id of the hierarchy that can be chosen — what «select all» means here. */
+function choosable(items) {
+    return items.flatMap((item) => [
+        ...(item.disabled === true ? [] : [item.id]),
+        ...choosable(item.children ?? []),
+    ]);
+}
+/**
+ * A hierarchy of records — the chart of accounts, product categories, warehouse locations —
+ * with its groups that fold, a figure per row, and one or many rows to choose.
+ *
+ * Context: the keyboard is React Aria's `Tree`: arrows walk the visible rows, → opens a group
+ * and ← folds it (or goes up to the parent), Home and End jump, and typing a name moves to it.
+ * Escape does NOT clear the selection: the tree often lives in a dialog or a popover, and
+ * Escape there means «close» — clearing the choice on the way out would lose it without a word.
+ */
+export function Tree({ items, label, labelledBy, expanded, defaultExpanded, onExpandedChange, selectionMode = "none", selected, defaultSelected, onSelectedChange, onAction, empty, }) {
+    const copy = useUiCopy();
+    const density = useDensity();
+    const pad = byDensity(density, "py-1.5 pe-2", "py-0.5 pe-1.5");
+    const many = selectionMode === "multiple";
+    const onSelectionChange = (keys) => onSelectedChange?.(keys === "all" ? choosable(items) : [...keys].map(String));
+    const render = (node, level) => {
+        const children = node.children ?? [];
+        const group = children.length > 0;
+        const Icon = node.icon;
+        /* Each level is one indent step; the first one keeps a sliver of the row's own padding so
+           the chevron is not glued to the edge of its tint. */
+        const indent = {
+            paddingInlineStart: `calc(var(--spacing) * 1 + var(--spacing-indent) * ${level - 1})`,
+        };
+        return (_jsxs(AriaTreeItem, { id: node.id, textValue: node.label, isDisabled: node.disabled === true, className: ({ isSelected, isHovered, isFocusVisible }) => cn(row({ isSelected, isHovered, isFocusVisible }), pad), style: indent, children: [_jsx(TreeItemContent, { children: ({ isExpanded, isSelected }) => (_jsxs(_Fragment, { children: [group ? (_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 }) })) : (_jsx("span", { "aria-hidden": true, className: "size-(--spacing-indent) shrink-0" })), _jsxs("span", { className: "flex min-w-0 flex-1 items-center gap-1.5", children: [many ? _jsx(SelectionCheck, {}) : null, Icon === undefined ? null : (_jsx(Icon, { className: "size-(--size-icon-md) shrink-0 text-muted", strokeWidth: 2, "aria-hidden": true })), _jsx("span", { className: cn("min-w-0 flex-1 truncate", group ? "font-medium" : "", isSelected ? "font-medium" : "", node.disabled === true && selectionMode !== "none" ? "text-muted" : ""), children: node.label }), node.meta === undefined ? null : (_jsx("span", { className: "shrink-0 ps-3 text-right tabular-nums whitespace-nowrap text-muted", children: node.meta })), selectionMode === "single" && isSelected ? (_jsx(Check, { className: "size-(--size-icon-sm) shrink-0 text-primary forced-colors:text-[HighlightText]", strokeWidth: 2.5, "aria-hidden": true })) : null] })] })) }), children.map((child) => render(child, level + 1))] }, node.id));
+    };
+    return (_jsx(AriaLocale, { children: _jsx(AriaTree, { ...(labelledBy === undefined
+                ? { "aria-label": label }
+                : { "aria-labelledby": labelledBy }), selectionMode: selectionMode, 
+            /* One to choose: a click chooses and a double click opens. Many: the click opens and
+               the check chooses. See the header. */
+            selectionBehavior: selectionMode === "single" ? "replace" : "toggle", disabledBehavior: "selection", escapeKeyBehavior: "none", ...(selected === undefined ? {} : { selectedKeys: selected }), ...(defaultSelected === undefined ? {} : { defaultSelectedKeys: defaultSelected }), ...(expanded === undefined ? {} : { expandedKeys: expanded }), ...(defaultExpanded === undefined ? {} : { defaultExpandedKeys: defaultExpanded }), ...(onExpandedChange === undefined
+                ? {}
+                : { onExpandedChange: (keys) => onExpandedChange([...keys].map(String)) }), ...(onSelectedChange === undefined ? {} : { onSelectionChange }), ...(onAction === undefined ? {} : { onAction: (key) => onAction(String(key)) }), renderEmptyState: () => (_jsx("p", { className: "px-2 py-3 text-meta text-muted", children: empty ?? copy.tree.empty })), className: "flex w-full min-w-0 flex-col gap-px outline-0", children: items.map((item) => render(item, 1)) }) }));
+}
+/* The check of a row when many can be chosen. It is React Aria's `selection` slot: it toggles
+   the row and never opens it. Drawn like `Checkbox`'s box so a check reads as one thing. */
+function SelectionCheck() {
+    return (_jsx(AriaCheckbox, { slot: "selection", className: "group/check inline-flex shrink-0 outline-0", children: ({ isSelected, isFocusVisible }) => (_jsx("span", { "aria-hidden": true, className: cn("inline-flex size-4 items-center justify-center rounded-mark border transition-colors duration-(--duration-instant) forced-color-adjust-none", isSelected
+                ? "border-primary bg-primary text-surface forced-colors:border-[Highlight] forced-colors:bg-[Highlight] forced-colors:text-[HighlightText]"
+                : "border-line-strong bg-surface text-transparent forced-colors:border-[ButtonBorder]", focusRing({ isFocusVisible })), children: _jsx(Check, { className: "size-3", strokeWidth: 2.5 }) })) }));
+}

package/dist/primitives/tree/index.d.ts

@@ -0,0 +1 @@
+export { Tree, type TreeItem, type TreeProps } from "./Tree.js";

package/dist/primitives/tree/index.js

@@ -0,0 +1,3 @@
+/* A hierarchy of records — the chart of accounts, categories, locations: read, folded and
+   chosen from. Not the app's menu: that is `NavigationTree`. */
+export { Tree } from "./Tree.js";

package/dist/primitives/value/Copyable.d.ts

@@ -34,4 +34,15 @@ export type CopyableProps = {
      *  el valor ya está dibujado. */
     bare?: boolean;
 };
+/**
+ * The button alone, for a value that is only known when it is pressed — what a field shows
+ * at that moment (`Field`'s copy button reads it from the screen). `Copyable` is this
+ * button next to its value.
+ */
+export declare function CopyButton({ value, label, }: {
+    /** The text, or how to get it at the moment of the press. */
+    value: string | (() => string);
+    /** Its name at rest. Defaults to the copy table's «Copiar». */
+    label?: string;
+}): import("react").JSX.Element;
 export declare function Copyable({ value, children, mono, bare }: CopyableProps): import("react").JSX.Element;

package/dist/primitives/value/Copyable.js

@@ -6,7 +6,12 @@ import { useEffect, useRef, useState } from "react";
 /** Cuánto dura el tilde. Dos segundos: alcanza para verlo sin que el botón se
  *  quede en un estado que ya no es cierto. */
 const CONFIRMED_FOR = 2000;
-export function Copyable({ value, children, mono = false, bare = false }) {
+/**
+ * The button alone, for a value that is only known when it is pressed — what a field shows
+ * at that moment (`Field`'s copy button reads it from the screen). `Copyable` is this
+ * button next to its value.
+ */
+export function CopyButton({ value, label, }) {
     const copy = useUiCopy();
     const [state, setState] = useState("idle");
     const timer = useRef(null);
@@ -19,8 +24,15 @@ export function Copyable({ value, children, mono = false, bare = false }) {
     async function run() {
         if (timer.current !== null)
             clearTimeout(timer.current);
+        const text = typeof value === "function" ? value() : value;
+        if (text.trim() === "") {
+            /* Nothing on screen to copy: said, not a check mark over an empty clipboard. */
+            setState("empty");
+            timer.current = setTimeout(() => setState("idle"), CONFIRMED_FOR);
+            return;
+        }
         try {
-            await navigator.clipboard.writeText(value);
+            await navigator.clipboard.writeText(text);
             setState("done");
         }
         catch {
@@ -30,16 +42,25 @@ export function Copyable({ value, children, mono = false, bare = false }) {
         }
         timer.current = setTimeout(() => setState("idle"), CONFIRMED_FOR);
     }
-    const label = state === "done"
+    const said = state === "done"
         ? copy.copyable.done
         : state === "failed"
             ? copy.copyable.failed
-            : copy.copyable.label;
-    const button = (_jsx("button", { type: "button", onClick: run, "aria-label": label, title: label, className: `inline-flex shrink-0 items-center justify-center rounded-control p-0.5 transition-colors duration-(--duration-instant) ${state === "done"
+            : state === "empty"
+                ? copy.copyable.empty
+                : (label ?? copy.copyable.label);
+    return (_jsx("button", { type: "button", onClick: (e) => {
+            /* Inside a row that opens or a link: copying is not opening. */
+            e.stopPropagation();
+            void run();
+        }, "aria-label": said, title: said, className: `inline-flex shrink-0 items-center justify-center rounded-control p-0.5 transition-colors duration-(--duration-instant) ${state === "done"
             ? "text-good"
-            : state === "failed"
+            : state === "failed" || state === "empty"
                 ? "text-bad"
                 : "text-muted hover:bg-ink/6 hover:text-ink"}`, children: state === "done" ? (_jsx(Check, { className: "size-(--size-icon-sm)", strokeWidth: 2.5 })) : (_jsx(Copy, { className: "size-(--size-icon-sm)", strokeWidth: 2 })) }));
+}
+export function Copyable({ value, children, mono = false, bare = false }) {
+    const button = _jsx(CopyButton, { value: value });
     if (bare)
         return button;
     return (

package/dist/primitives/value/Fecha.js

@@ -61,12 +61,21 @@ export function formatDateTime(when) {
     const locale = currentCopyLocale();
     return `${dateFormat(locale).format(when)} ${timeFormat(locale).format(when)}`;
 }
+/** A day written as `YYYY-MM-DD` (what a date field stores) is that day HERE. `new Date()`
+ *  reads it as midnight in UTC, and west of Greenwich that is the evening before: a due date
+ *  of the 15th was drawn as the 14th in La Paz. Anything else goes through `Date` as is. */
+function toDate(when) {
+    const day = typeof when === "string" ? /^(\d{4})-(\d{2})-(\d{2})$/.exec(when) : null;
+    if (day === null)
+        return new Date(when);
+    return new Date(Number(day[1]), Number(day[2]) - 1, Number(day[3]));
+}
 export function DateValue({ when, format = "relative", 
 /** So it can be tested: without this, a story with «hace 2 min» changes its
  *  text every minute and no snapshot works as a reference. */
 now, }) {
     const copy = useUiCopy();
-    const d = when instanceof Date ? when : new Date(when);
+    const d = when instanceof Date ? when : toDate(when);
     if (Number.isNaN(d.getTime())) {
         return (_jsx("span", { className: "text-meta text-muted italic", title: copy.time.invalid, children: copy.time.noDate }));
     }

package/dist/primitives/value/ProgressBar.d.ts

@@ -0,0 +1,31 @@
+import type { Tone } from "../../foundations/types.js";
+import type { ReactNode } from "react";
+export type ProgressBarProps = {
+    /** Where the task is, from `minValue` to `maxValue`. Absent = under way and it cannot say
+     *  how far: the bar sweeps and draws no figure. */
+    value?: number;
+    /** What is running: «Importación de clientes», «Cierre de octubre». Always its accessible
+     *  name; drawn above the bar only with `showLabel`. */
+    label: string;
+    minValue?: number;
+    /** The size of the task — 4000 for an import of 4.000 rows. 100 by default, so a plain
+     *  percentage needs nothing else. */
+    maxValue?: number;
+    /** How the figure is written. Absent: the percentage of the task. */
+    formatOptions?: Intl.NumberFormatOptions;
+    /** The figure written by hand, when a percentage does not say it: «1.240 de 4.000 filas».
+     *  It is also what a screen reader reads. Indeterminate, it is the only figure drawn —
+     *  «leyendo el archivo…». */
+    valueLabel?: ReactNode;
+    /** Draws the label above the bar: the bar a screen is about (an import, the closing of
+     *  the month). Off in a cell or a row, where the column or the line already says it. */
+    showLabel?: boolean;
+    /** Off when the figure is already beside it — a cell with its column. */
+    showValue?: boolean;
+    /** The width of the track (inline) or of the whole piece (with `showLabel`). A bar in a
+     *  list row is shorter than the bar of an import. */
+    width?: string;
+    /** The state of the task. `brand` — the gradient — is the long bar of a live process. */
+    tone?: Tone | "brand";
+};
+export declare function ProgressBar({ value, label, minValue, maxValue, formatOptions, valueLabel, showLabel, showValue, width, tone, }: ProgressBarProps): import("react").JSX.Element;

package/dist/primitives/value/ProgressBar.js

@@ -0,0 +1,53 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { AriaLocale } from "../../foundations/aria.js";
+import { cn } from "../../foundations/variants.js";
+import { ProgressBar as AriaProgressBar } from "react-aria-components";
+/**
+ * A task under way: the import of 4.000 rows, the closing of the month, a file going up. A
+ * real bar, never a spinner — a spinner says «wait» and does not say how much; a bar says both.
+ *
+ * Context: it looks like `Meter` and it is the opposite thing. A meter is a QUANTITY in a
+ * range that just is — the stock against the warehouse, the credit used — and full is often
+ * the alarm. A progress bar is something HAPPENING, moving toward done, and full is the good
+ * news. That is why their color comes from different places: the meter's is the reading of
+ * its value; this one's is the state of the task, said by whoever runs it — `good` finished,
+ * `warn` is running slow, `bad` failed — and `brand` by default, the blue→gold gradient of
+ * the long bar of a live import. (At 6 px and 62 % in a list row a gradient reads as a
+ * broken bar, so a short bar there asks for a flat tone.)
+ *
+ * ── Determinate and indeterminate ─────────────────────────────────────
+ *
+ * With a `value` it fills to it, and the figure next to it is in tabular figures so a column
+ * of bars keeps its digits aligned. Without one the task is under way and cannot say how far
+ * — the server has not counted the rows yet — and the bar SAYS so instead of inventing a
+ * number: a segment sweeps along the track and no figure is drawn. That sweep is the only
+ * loop of the system (`--animate-progress-sweep`), and it runs behind `motion-safe:`: with
+ * `prefers-reduced-motion` the segment stands still, the whole track faded — «busy» without
+ * movement, and without a fill that could be read as a percentage.
+ *
+ * React Aria writes `role="progressbar"` and the `aria-value*` — no `aria-valuenow` while it
+ * is indeterminate, which is how a screen reader tells the two apart — and formats the figure
+ * in the copy table's locale (`AriaLocale`).
+ *
+ * The track is the system's `--size-track`: at 3 px it was a line that could not be told
+ * from a separator; two bars of different thickness on one screen read as two things.
+ */
+const FILL = {
+    neutral: "bg-muted",
+    info: "bg-info",
+    good: "bg-good",
+    warn: "bg-warn",
+    bad: "bg-bad",
+    accent: "bg-accent",
+};
+export function ProgressBar({ value, label, minValue = 0, maxValue = 100, formatOptions, valueLabel, showLabel = false, showValue = true, width = "w-24", tone = "brand", }) {
+    const fill = tone === "brand" ? "bar-brand" : FILL[tone];
+    return (_jsx(AriaLocale, { children: _jsx(AriaProgressBar, { "aria-label": label, ...(value === undefined ? {} : { value }), isIndeterminate: value === undefined, minValue: minValue, maxValue: maxValue, formatOptions: formatOptions, valueLabel: valueLabel, className: showLabel
+                ? `flex max-w-full flex-col gap-1.5 ${width}`
+                : "flex min-w-0 items-center gap-2", children: ({ percentage, valueText, isIndeterminate }) => {
+                const figure = showValue && valueText !== undefined ? (_jsx("span", { className: "shrink-0 text-meta tabular-nums text-muted", children: valueText })) : null;
+                const track = (_jsx("span", { className: cn("relative block h-(--size-track) overflow-hidden rounded-pill bg-ink/10 forced-colors:outline forced-colors:outline-[ButtonBorder]", showLabel ? "w-full" : width), children: isIndeterminate ? (_jsx("span", { "data-indeterminate": true, className: cn("absolute inset-y-0 left-0 w-2/5 rounded-pill forced-colors:bg-[Highlight]", "motion-safe:animate-progress-sweep motion-reduce:w-full motion-reduce:opacity-40", fill) })) : (_jsx("span", { className: cn("block h-full rounded-pill transition-[width] duration-(--duration-panel) ease-(--ease-out) forced-colors:bg-[Highlight]", fill), style: { width: `${percentage ?? 0}%` } })) }));
+                return showLabel ? (_jsxs(_Fragment, { children: [_jsxs("span", { className: "flex items-baseline justify-between gap-2", children: [_jsx("span", { className: "truncate text-meta text-ink", children: label }), figure] }), track] })) : (_jsxs(_Fragment, { children: [track, figure] }));
+            } }) }));
+}

package/dist/primitives/value/Relation.d.ts

@@ -55,6 +55,11 @@ export type RelationValueProps = {
     href?: string;
     /** Present = an info button next to the name opens the `RelationCard`. */
     summary?: RelationSummary;
+    /** Floats the summary from the NAME on hover, focus or long press, instead of from the
+     *  info button. `true` = the `RelationCard` (with `summary` when given); a node = that
+     *  content instead — the product of a line, a consumer's own card. Needs the name to be a
+     *  link (`href` or `onOpen`); without one the content opens from the info button. */
+    preview?: boolean | ReactNode;
     /** The control that EDITS this relation — a `Picker` — drawn instead in edit mode. */
     editor?: ReactNode;
     /** Forces the mode; by default the form's. Only matters with `editor`. */
@@ -65,5 +70,5 @@ export type RelationValueProps = {
  * picture, and its summary one press away. Works in a table cell, a list row, a `Record.Facts`
  * value and a form field (read mode; pass the `Picker` as `editor` for edit mode).
  */
-export declare function RelationValue({ name, secondary, media, onOpen, href, summary, editor, mode, }: RelationValueProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
+export declare function RelationValue({ name, secondary, media, onOpen, href, summary, preview, editor, mode, }: RelationValueProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
 export {};

package/dist/primitives/value/Relation.js

@@ -7,6 +7,7 @@ import { CellStack, Thumb } from "../cell/CellStack.js";
 import { FieldIdsContext } from "../field/context.js";
 import { useFormMode } from "../field/mode.js";
 import { PopoverTrigger } from "../overlay/PopoverTrigger.js";
+import { Preview } from "../overlay/Preview.js";
 import { Tag } from "../tag/Tag.js";
 import { ArrowRight, Info } from "lucide-react";
 import { useContext } from "react";
@@ -32,7 +33,7 @@ export function RelationCard({ name, secondary, media, summary = {}, onOpen, hre
  * picture, and its summary one press away. Works in a table cell, a list row, a `Record.Facts`
  * value and a form field (read mode; pass the `Picker` as `editor` for edit mode).
  */
-export function RelationValue({ name, secondary, media, onOpen, href, summary, editor, mode, }) {
+export function RelationValue({ name, secondary, media, onOpen, href, summary, preview, editor, mode, }) {
     const copy = useUiCopy();
     const formMode = useFormMode(mode);
     /* Inside a `Field` the value takes the control's height, so a form that goes from
@@ -45,13 +46,29 @@ export function RelationValue({ name, secondary, media, onOpen, href, summary, e
         return frame(_jsx("span", { className: "text-meta text-muted italic", children: copy.relation.none }));
     }
     const goes = href !== undefined || onOpen !== undefined;
-    const primary = goes ? (_jsx(Link, { ...(href === undefined ? {} : { href }), ...(onOpen === undefined ? {} : { onPress: onOpen }), className: ({ isFocusVisible }) => cn("cursor-pointer rounded-mark text-primary no-underline underline-offset-2 hover:underline", focusRing({ isFocusVisible })), children: name })) : (name);
-    return frame(_jsxs("span", { className: "inline-flex max-w-full min-w-0 items-center gap-1", children: [_jsx(CellStack, { primary: primary, ...(secondary === undefined ? {} : { secondary }), ...(media === undefined ? {} : { media }) }), summary === undefined ? null : (_jsx(PopoverTrigger, { label: fillCopy(copy.relationCard.summary, { name }), trigger: _jsx(IconButton, { icon: Info, label: fillCopy(copy.relationCard.summary, { name }), size: "sm" }), children: (close) => (_jsx(RelationCard, { name: name, summary: summary, ...(secondary === undefined ? {} : { secondary }), ...(media === undefined ? {} : { media }), ...(href === undefined ? {} : { href }), ...(onOpen === undefined
-                        ? {}
-                        : {
-                            onOpen: () => {
-                                close();
-                                onOpen();
-                            },
-                        }) })) }))] }));
+    const summaryLabel = fillCopy(copy.relationCard.summary, { name });
+    const card = (open) => (_jsx(RelationCard, { name: name, ...(summary === undefined ? {} : { summary }), ...(secondary === undefined ? {} : { secondary }), ...(media === undefined ? {} : { media }), ...(href === undefined ? {} : { href }), ...(open === undefined ? {} : { onOpen: open }) }));
+    /* What floats from the name: the card, or the consumer's own content. */
+    const previewed = preview === undefined || preview === null || preview === false
+        ? undefined
+        : preview === true
+            ? card(onOpen)
+            : preview;
+    const link = goes ? (_jsx(Link, { ...(href === undefined ? {} : { href }), ...(onOpen === undefined ? {} : { onPress: onOpen }), className: ({ isFocusVisible }) => cn("cursor-pointer rounded-mark text-primary no-underline underline-offset-2 hover:underline", focusRing({ isFocusVisible })), children: name })) : undefined;
+    const primary = link === undefined ? (name) : previewed === undefined ? (link) : (_jsx(Preview, { trigger: link, label: summaryLabel, children: previewed }));
+    /* The `i`: the summary when there is no preview on the name; the preview's content when
+       there is no link for it to ride on. */
+    const info = previewed !== undefined
+        ? goes
+            ? undefined
+            : () => previewed
+        : summary === undefined
+            ? undefined
+            : (close) => card(onOpen === undefined
+                ? undefined
+                : () => {
+                    close();
+                    onOpen();
+                });
+    return frame(_jsxs("span", { className: "inline-flex max-w-full min-w-0 items-center gap-1", children: [_jsx(CellStack, { primary: primary, ...(secondary === undefined ? {} : { secondary }), ...(media === undefined ? {} : { media }) }), info === undefined ? null : (_jsx(PopoverTrigger, { label: summaryLabel, trigger: _jsx(IconButton, { icon: Info, label: summaryLabel, size: "sm" }), children: info }))] }));
 }

package/dist/primitives/value/Totals.d.ts

@@ -1,7 +1,8 @@
-import type { ReactNode } from "react";
+import { type ReactNode } from "react";
 /**
  * The money summary of a document — subtotal, taxes, discounts and the TOTAL — under its
- * lines, aligned to the right.
+ * lines, aligned to the right. And, once the document starts being settled, what was already
+ * taken off it, what is still owed, and what could still be taken off.
  *
  * Context: written as two more rows of the lines table, «IVA» and «Total» were the same size
  * and weight as a product line, and the one number the document exists for had to be found.
@@ -10,17 +11,111 @@ import type { ReactNode } from "react";
  * read (Jakob's law).
  *
  * Labels left and figures right of a narrow column, both in tabular figures, so the amounts
- * line up digit by digit. The `total` row closes the block: a rule above it, and the figure
- * at the title size.
+ * line up digit by digit. The `total` row closes the breakdown: a rule above it.
+ *
+ * ── Deductions, balance and credits: one block, not three ────────────
+ *
+ * A posted invoice is read as one sum: the total, minus each payment, gives what is owed. Drawn
+ * as a second component under this one, the payments would be a second column of figures that
+ * the screen has to line up with the first by hand — which a template cannot do without
+ * styling — and the decision below, WHICH figure leads, needs to see the three at once. So it
+ * is this block, extended, and a block with only `rows` draws exactly what it drew before.
+ *
+ * It still does not know what an invoice is. It speaks of `deductions` (a payment, a credit
+ * note, a retention: anything already applied against the total), a `balance` (what remains
+ * after them), `settled` (the word for «nothing remains»: «Pagada», «Conciliado») and
+ * `credits` (what could still be applied). The domain formats the money and owns the actions;
+ * this only lays them out and names them.
+ *
+ * ── The figure that leads moves with the state ───────────────────────
+ *
+ * There is ONE figure at the title size, and which one it is depends on where the document is:
+ *
+ *      nothing applied yet (a draft, a posted invoice)   the total
+ *      something applied, something owed                 the balance — the total steps down
+ *      settled                                           the total, with the `settled` mark
+ *
+ * Once a payment is in, the question the person brings is «how much is left?», and a total
+ * at the title size next to a balance at the body size answers the wrong question first.
+ * That is the default; `lead` says it explicitly when the screen knows better.
+ *
+ * ── A deduction is HEARD as one: «Pagado el 12/10/2026, menos Bs. 1.000,00» ──
+ *
+ * The amount arrives formatted and WITHOUT a sign; the block writes the minus. The visible
+ * «−» is hidden from assistive technology — screen readers skip it or say «dash» — and a
+ * visually hidden «menos» (`copy.totals.less`) is read in its place, so the label and the
+ * figure are one sentence and not two loose numbers.
+ *
+ * ── The detail of a deduction: an `i`, asked for ─────────────────────
+ *
+ * Where it came from (journal, reference, method), going to it, and unlinking it open from an
+ * `i` before the label — `PopoverTrigger`, the same `i` a `RelationValue` uses for its
+ * summary. Not a `Preview` on hover: the card holds an action that changes the document
+ * («Desvincular»), and that is asked for with a press, which the mouse, the keyboard and the
+ * finger all have. The `i` sits BEFORE the label so the label and its amount stay together
+ * in the reading order.
+ *
+ * ── None of these actions is the primary ─────────────────────────────
+ *
+ * The screen's one primary is somewhere else («Registrar pago», «Confirmar»). Unlinking is
+ * `secondary` and not `danger`: it does not destroy — the payment comes back as a credit and
+ * is applied again with one press, which is the undo. «Aplicar» and «Abrir» are `ghost`.
  */
 export type TotalsRow = {
     label: ReactNode;
     value: ReactNode;
     /** A note under the label — «incluido en el precio», «sobre Bs. 3.601,80». */
     detail?: ReactNode;
-    /** The row the block exists for. Usually one, and last. */
+    /** The row that closes the breakdown. Usually one, and last. */
     total?: boolean;
 };
-export declare function Totals({ rows }: {
+/** A fact of a deduction's detail: «Diario · Banco BNB», «Referencia · TRF-88213». */
+export type TotalsFact = {
+    label: string;
+    value: ReactNode;
+};
+/** Something already applied against the total: a payment, a credit note, a retention. */
+export type TotalsDeduction = {
+    /** What it is, as one phrase — «Pagado el 12/10/2026». A string: it also names the `i`
+     *  and the floating detail. */
+    label: string;
+    /** The amount taken off, formatted and WITHOUT a sign: the block writes the minus. */
+    value: ReactNode;
+    /** A quiet note under the label — «Transferencia · Banco BNB». */
+    detail?: ReactNode;
+    /** What the `i` shows: two to five facts — journal, reference, method. */
+    facts?: readonly TotalsFact[];
+    /** Go to the applied record. The detail shows «Abrir». */
+    onOpen?: () => void;
+    /** Undo the application — «Desvincular». Present = allowed; absent = not offered. */
+    onRemove?: () => void;
+};
+/** Something that COULD be applied and is not yet: an unused credit of the same party. */
+export type TotalsCredit = {
+    /** What it is — «NC/2026/0012». A string: it also names its «Aplicar». */
+    label: string;
+    /** The amount available, formatted. */
+    value: ReactNode;
+    /** A quiet note — «del 02/10/2026», «anticipo». */
+    detail?: ReactNode;
+    onApply: () => void;
+};
+export type TotalsProps = {
+    /** The breakdown and its `total`: subtotal, each tax group, discounts, TOTAL. */
     rows: readonly TotalsRow[];
-}): import("react").JSX.Element;
+    /** What was already applied against the total, one row each, after it. */
+    deductions?: readonly TotalsDeduction[];
+    /** What remains once the deductions are taken off — «Importe adeudado». */
+    balance?: Omit<TotalsRow, "total">;
+    /** Nothing remains: the word for it, drawn as a mark next to the leading figure —
+     *  «Pagada». */
+    settled?: string;
+    /** Which figure leads, at the title size. By default the balance when something was
+     *  deducted and the document is not settled; otherwise the total. */
+    lead?: "total" | "balance";
+    /** What could still be applied, apart and under the sum: it is not part of it. */
+    credits?: readonly TotalsCredit[];
+    /** The title of the credits. `copy.totals.credits` by default. */
+    creditsLabel?: string;
+};
+export declare function Totals({ rows, deductions, balance, settled, lead, credits, creditsLabel, }: TotalsProps): import("react").JSX.Element;

package/dist/primitives/value/Totals.js

@@ -1,4 +1,54 @@
+"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-export function Totals({ rows }) {
-    return (_jsx("dl", { className: "ml-auto flex w-full max-w-(--container-search) flex-col gap-1.5", children: rows.map((row, i) => row.total === true ? (_jsxs("div", { className: "mt-1 flex items-baseline justify-between gap-4 border-t border-line-strong pt-2.5", children: [_jsx("dt", { className: "text-body font-semibold text-ink", children: row.label }), _jsx("dd", { className: "text-title font-semibold tabular-nums text-ink", children: row.value })] }, i)) : (_jsxs("div", { className: "flex items-baseline justify-between gap-4", children: [_jsxs("dt", { className: "flex flex-col text-meta text-muted", children: [row.label, row.detail === undefined ? null : (_jsx("span", { className: "text-micro text-muted", children: row.detail }))] }), _jsx("dd", { className: "text-meta tabular-nums text-ink", children: row.value })] }, i))) }));
+import { fillCopy, useUiCopy } from "../../foundations/copy.js";
+import { Button, IconButton } from "../button/Button.js";
+import { PopoverTrigger } from "../overlay/PopoverTrigger.js";
+import { Tag } from "../tag/Tag.js";
+import { ArrowRight, Info, Plus, Unlink } from "lucide-react";
+import { useId } from "react";
+/** The figure the block exists for: a rule above it and the figure at the title size. The
+ *  `data-lead` marks it for the tests and for whoever reads the DOM. */
+function LeadRow({ row, mark }) {
+    return (_jsxs("div", { "data-lead": "", className: "mt-1 flex flex-wrap items-baseline justify-between gap-x-4 border-t border-line-strong pt-2.5", children: [_jsxs("dt", { className: "flex min-w-0 flex-col", children: [_jsxs("span", { className: "flex flex-wrap items-center gap-2 text-body font-semibold text-ink", children: [row.label, mark === undefined ? null : _jsx(Tag, { tone: "good", children: mark })] }), row.detail === undefined ? null : (_jsx("span", { className: "text-micro text-muted", children: row.detail }))] }), _jsx("dd", { className: "ml-auto text-title font-semibold whitespace-nowrap tabular-nums text-ink", children: row.value })] }));
+}
+/** A figure that closes a part of the sum without leading it: the total once the balance
+ *  leads, or the balance while the total does. Ruled, in the body size. */
+function ClosingRow({ row }) {
+    return (_jsxs("div", { className: "mt-1 flex flex-wrap items-baseline justify-between gap-x-4 border-t border-line pt-2", children: [_jsxs("dt", { className: "flex min-w-0 flex-col", children: [_jsx("span", { className: "text-body font-semibold text-ink", children: row.label }), row.detail === undefined ? null : (_jsx("span", { className: "text-micro text-muted", children: row.detail }))] }), _jsx("dd", { className: "ml-auto text-body font-semibold whitespace-nowrap tabular-nums text-ink", children: row.value })] }));
+}
+function PlainRow({ row }) {
+    return (_jsxs("div", { className: "flex items-baseline justify-between gap-4", children: [_jsxs("dt", { className: "flex min-w-0 flex-col text-meta text-muted", children: [row.label, row.detail === undefined ? null : (_jsx("span", { className: "text-micro text-muted", children: row.detail }))] }), _jsx("dd", { className: "text-meta whitespace-nowrap tabular-nums text-ink", children: row.value })] }));
+}
+/** What floats from a deduction's `i`: its facts and, when allowed, «Desvincular» and
+ *  «Abrir». Both close the card first — the row may be gone once the action runs. */
+function DeductionDetail({ item, close }) {
+    const copy = useUiCopy();
+    const facts = item.facts ?? [];
+    const run = (action) => () => {
+        close();
+        action();
+    };
+    return (_jsxs("div", { className: "flex w-64 max-w-full flex-col gap-3", children: [facts.length === 0 ? null : (_jsx("dl", { className: "grid grid-cols-2 gap-x-4 gap-y-2", children: facts.map((fact) => (_jsxs("div", { className: "flex min-w-0 flex-col", children: [_jsx("dt", { className: "truncate text-micro text-muted", children: fact.label }), _jsx("dd", { className: "text-meta tabular-nums break-words text-ink", children: fact.value })] }, fact.label))) })), item.onRemove === undefined && item.onOpen === undefined ? null : (_jsxs("div", { className: "flex flex-wrap justify-end gap-2 border-t border-line pt-2", children: [item.onRemove === undefined ? null : (_jsx(Button, { role: "secondary", size: "sm", icon: Unlink, onClick: run(item.onRemove), children: copy.totals.unlink })), item.onOpen === undefined ? null : (_jsx(Button, { role: "ghost", size: "sm", icon: ArrowRight, onClick: run(item.onOpen), children: copy.totals.open }))] }))] }));
+}
+function DeductionRow({ item }) {
+    const copy = useUiCopy();
+    const asks = (item.facts !== undefined && item.facts.length > 0) ||
+        item.onRemove !== undefined ||
+        item.onOpen !== undefined;
+    return (_jsxs("div", { className: "flex items-baseline justify-between gap-4", children: [_jsxs("dt", { className: "flex min-w-0 items-baseline gap-1 text-meta text-muted", children: [asks ? (_jsx(PopoverTrigger, { title: item.label, placement: "bottom end", trigger: _jsx(IconButton, { icon: Info, label: fillCopy(copy.totals.details, { label: item.label }) }), children: (close) => _jsx(DeductionDetail, { item: item, close: close }) })) : null, _jsxs("span", { className: "flex min-w-0 flex-col", children: [item.label, item.detail === undefined ? null : (_jsx("span", { className: "text-micro text-muted", children: item.detail }))] })] }), _jsxs("dd", { className: "text-meta whitespace-nowrap tabular-nums text-ink", children: [_jsx("span", { "aria-hidden": true, children: "− " }), _jsxs("span", { className: "sr-only", children: [copy.totals.less, " "] }), item.value] })] }));
+}
+function Credits({ items, label }) {
+    const copy = useUiCopy();
+    const id = useId();
+    return (_jsxs("div", { className: "flex flex-col gap-1.5 border-t border-line pt-3", children: [_jsx("p", { id: id, className: "text-micro font-semibold text-muted", children: label }), _jsx("ul", { "aria-labelledby": id, className: "flex flex-col gap-1", children: items.map((credit, i) => (_jsxs("li", { className: "flex flex-wrap items-center justify-between gap-x-3 gap-y-1", children: [_jsxs("span", { className: "flex min-w-0 flex-col", children: [_jsx("span", { className: "text-meta text-ink", children: credit.label }), credit.detail === undefined ? null : (_jsx("span", { className: "text-micro text-muted", children: credit.detail }))] }), _jsxs("span", { className: "ml-auto flex shrink-0 items-center gap-2", children: [_jsx("span", { className: "text-meta whitespace-nowrap tabular-nums text-ink", children: credit.value }), _jsx(Button, { role: "ghost", size: "sm", icon: Plus, "aria-label": fillCopy(copy.totals.applyCredit, { label: credit.label }), onClick: credit.onApply, children: copy.totals.apply })] })] }, i))) })] }));
+}
+export function Totals({ rows, deductions = [], balance, settled, lead, credits = [], creditsLabel, }) {
+    const copy = useUiCopy();
+    const leads = lead ??
+        (balance !== undefined && deductions.length > 0 && settled === undefined
+            ? "balance"
+            : "total");
+    /* With nothing to lead it, the balance cannot lead: the total keeps the title size. */
+    const balanceLeads = leads === "balance" && balance !== undefined;
+    return (_jsxs("div", { className: "ml-auto flex w-full max-w-(--container-search) flex-col gap-3", children: [_jsxs("dl", { className: "flex flex-col gap-1.5", children: [rows.map((row, i) => row.total === true ? (balanceLeads ? (_jsx(ClosingRow, { row: row }, i)) : (_jsx(LeadRow, { row: row, ...(settled === undefined ? {} : { mark: settled }) }, i))) : (_jsx(PlainRow, { row: row }, i))), deductions.map((item, i) => (_jsx(DeductionRow, { item: item }, i))), balance === undefined ? null : balanceLeads ? (_jsx(LeadRow, { row: balance, ...(settled === undefined ? {} : { mark: settled }) })) : (_jsx(ClosingRow, { row: balance }))] }), credits.length === 0 ? null : (_jsx(Credits, { items: credits, label: creditsLabel ?? copy.totals.credits }))] }));
 }

package/dist/primitives/value/Value.d.ts

@@ -1,4 +1,3 @@
-import type { Tone } from "../../foundations/types.js";
 import type { ReactNode } from "react";
 export declare const formatCount: (value: number, locale?: string) => string;
 export declare const formatNumber: (value: number, locale?: string) => string;
@@ -21,42 +20,6 @@ export declare function Numeric({ value, unit, format, }: {
     unit?: string;
     format?: "integer" | "decimal" | "distance";
 }): import("react").JSX.Element;
-/**
- * A real bar, never a spinner.
- *
- * Context: a spinner says «wait» and doesn't say how much; a bar says both
- * things.
- *
- * ── Why the fill is FLAT and the gradient is asked for ──────────────
- *
- * The bar always lived with `bar-brand`, the blue→gold gradient. At 3 px and at
- * 62 % that doesn't read as a brand: it reads as a blue bar with a broken tip.
- * A gradient needs length to be a gradient, and a bar inside a list row doesn't
- * have it.
- *
- * Now the fill is a flat tone —and the tone SAYS something: `good` finished,
- * `warn` is running slow, `bad` failed— and the gradient is asked for with
- * `tone="brand"`, which is the long bar of a live import: there it does have room
- * to be read.
- *
- * And it got fatter, from 3 px to 6 px. At 3 px it isn't a bar, it's a line: it
- * can't be told apart from a separator and the fill isn't visible unless it goes
- * past 20 %.
- */
-export declare function ProgressBar({ value, label, width, tone, 
-/** The percentage next to it. It is turned off when the bar lives inside
- *  something that already says the figure —a cell with its column— and it
- *  would only mean reading it twice. */
-showValue, }: {
-    /** 0 to 100. */
-    value: number;
-    label: string;
-    /** The activity bar wants to be longer than a list row; there is no reason for
-     *  it to be the same number on both sides. */
-    width?: string;
-    tone?: Tone | "brand";
-    showValue?: boolean;
-}): import("react").JSX.Element;
 /**
  * The content of a data cell, with what the system decides and the view does not.
  *