@sincpro/web-ui 1.5.0 → 1.7.0

package/dist/primitives/table/Table.js

@@ -1,8 +1,46 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { fillCopy, useUiCopy } from "../../foundations/copy.js";
 import { stickyTop, useScrollBox } from "../../foundations/sticky.js";
+import { pressSort, sortPosition, } from "./sorting.js";
 import { ArrowDown, ArrowUp, ChevronRight, ChevronsUpDown } from "lucide-react";
 import { createContext, useContext, useId } from "react";
+/* ==================================================================== *
+ *  TABLE — the way this product shows N records.
+ *
+ *  Dense, but readable, and a single split is what makes that possible:
+ *
+ *      the header in PROPORTIONAL        is a word
+ *      a number in TABULAR FIGURES       is a value that lines up with the one below
+ *
+ *  That is what makes a table readable at a glance: the eye tells the frame
+ *  apart from the content without reading either of them. Everything in mono
+ *  —which is where this product came from— turned the header into just another
+ *  row of data, and the whole report into a terminal. Mono is now for codes
+ *  only, and only when a cell asks for it.
+ *
+ *  ── Three sort states, not two ──────────────────────────────────────
+ *
+ *  Ascending, descending and **unsorted**. The third one is not a luxury: the
+ *  natural order of a delivery queue is the order they arrived in, and a table that
+ *  only toggles asc/desc has no way back to it. Losing the original order and
+ *  not being able to get it back is the number one complaint about any
+ *  sortable table.
+ *
+ *  ── And more than one column ────────────────────────────────────────
+ *
+ *  Shift+click adds the column as a TIE-BREAKER instead of replacing the order:
+ *  «by date, then by customer». Each sorted header then carries its place (1,
+ *  2, 3) next to the arrow, because two arrows alone do not say which one
+ *  decides. The model is in `sorting.ts`.
+ *
+ *  ── The header stays pinned ─────────────────────────────────────────
+ *
+ *  It is the difference between a long table you can read and one where, by
+ *  row forty, nobody knows which column they are looking at any more. It needs
+ *  the box to have a height: without `height` there is no scroll of its own
+ *  and nothing to stick to.
+ * ==================================================================== */
 export function Table({ children, 
 /** With a height, the table scrolls on its own and the header sticks.
  *  Without a height, the page scrolls and the header goes away. */
@@ -28,25 +66,35 @@ export function THead({ children, rowIndex, }) {
 }
 /** A column. If it gets a `sortKey`, it can be sorted.
  *
- *  The icon is ALWAYS there, dimmed when the column is not the sorted one: an
+ *  The icon is ALWAYS there, dimmed when the column is not sorted: an
  *  indicator that only shows up once you sort does not say which columns are
  *  sortable, and then you have to try them one by one. */
 export function Th({ children, sortKey, sort, onSort, numeric = false, align, width, }) {
-    const active = sortKey !== undefined && sort?.key === sortKey;
-    const dir = active ? sort.direction : undefined;
-    function nextSort() {
-        if (sortKey === undefined || onSort === undefined)
-            return;
-        // asc → desc → unsorted. The third click puts the table back the way it was.
-        if (!active)
-            onSort({ key: sortKey, direction: "asc" });
-        else if (dir === "asc")
-            onSort({ key: sortKey, direction: "desc" });
-        else
-            onSort(null);
-    }
+    const copy = useUiCopy();
+    const at = sortKey === undefined ? null : sortPosition(sort, sortKey);
+    const dir = at?.direction;
+    /* The place is drawn only when there is more than one criterion: «1» alone says nothing
+       the arrow did not. */
+    const ranked = at !== null && (sort?.length ?? 0) > 1;
+    const right = (align ?? (numeric ? "right" : "left")) === "right";
     const Icon = dir === "asc" ? ArrowUp : dir === "desc" ? ArrowDown : ChevronsUpDown;
-    return (_jsx("th", { scope: "col", style: width === undefined ? undefined : { width }, "aria-sort": active ? (dir === "asc" ? "ascending" : "descending") : "none", className: `border-b border-line-strong px-3 py-2 ${HEADER_TEXT} ${(align ?? (numeric ? "right" : "left")) === "right" ? "text-right" : "text-left"}`, children: sortKey === undefined ? (children) : (_jsxs("button", { type: "button", onClick: nextSort, className: `inline-flex items-center gap-1 rounded-control transition-colors duration-(--duration-instant) hover:text-ink focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary ${(align ?? (numeric ? "right" : "left")) === "right" ? "flex-row-reverse" : ""} ${active ? "text-ink" : ""}`, children: [children, _jsx(Icon, { className: `size-(--size-icon-sm) shrink-0 ${active ? "text-primary" : "text-line-strong"}`, strokeWidth: 2, "aria-hidden": true })] })) }));
+    return (_jsx("th", { scope: "col", style: width === undefined ? undefined : { width }, "aria-sort": sortKey === undefined
+            ? undefined
+            : at === null
+                ? "none"
+                : at.index > 0
+                    ? undefined
+                    : dir === "asc"
+                        ? "ascending"
+                        : "descending", className: `border-b border-line-strong px-3 py-2 ${HEADER_TEXT} ${right ? "text-right" : "text-left"}`, children: sortKey === undefined ? (children) : (_jsxs("button", { type: "button", title: copy.sorting.addHint, 
+            /* Shift+click selects the header's text in some browsers before the click lands. */
+            onMouseDown: (event) => {
+                if (event.shiftKey)
+                    event.preventDefault();
+            }, onClick: (event) => onSort?.(pressSort(sort ?? [], sortKey, event.shiftKey)), className: `inline-flex items-center gap-1 rounded-control transition-colors duration-(--duration-instant) select-none hover:text-ink focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary ${right ? "flex-row-reverse" : ""} ${at === null ? "" : "text-ink"}`, children: [children, _jsxs("span", { className: "inline-flex shrink-0 items-center gap-px", children: [_jsx(Icon, { className: `size-(--size-icon-sm) shrink-0 ${at === null ? "text-line-strong" : "text-primary"}`, strokeWidth: 2, "aria-hidden": true }), ranked ? (_jsx("span", { "aria-hidden": true, className: "text-micro text-primary tabular-nums", children: at.index + 1 })) : null] }), ranked ? (_jsx("span", { className: "sr-only", children: fillCopy(copy.sorting.place, {
+                        place: String(at.index + 1),
+                        direction: dir === "asc" ? copy.sorting.asc : copy.sorting.desc,
+                    }) })) : null] })) }));
 }
 /** The wash of a row lives on the cells, not on the `<tr>`. A background on the
  *  row paints edge to edge; on the cells the ends can round and the table's

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

@@ -1,8 +1,9 @@
 export { type Aggregate, type DataColumn, DataTable, type DataTableCreate, type GroupColumn, } from "./DataTable.js";
-export { EditableTable, type EditAdd, type EditBands, type EditColumn, type EditLayout, sectionLines, type StackPlace, stackPlaces, type TabTarget, tabTarget, } from "./EditableTable.js";
+export { EditableTable, type EditAdd, type EditBands, type EditCellState, type EditColumn, type EditFlag, type EditLayout, type EditRowState, sectionLines, type StackPlace, stackPlaces, type TabTarget, tabTarget, } from "./EditableTable.js";
 export { PileFootLine } from "./PileFootLine.js";
 export { PivotTable, type PivotTableProps, } from "./PivotTable.js";
 export { type ReportColumn, type ReportRow, type ReportRowKind, ReportTable, } from "./ReportTable.js";
 export { type RowAction, RowActions } from "./RowActions.js";
 export { type SheetColumn, SheetTable } from "./SheetTable.js";
-export { CELL_TONE, type SortDirection, type SortState, Table, Td, Th, THead, Tr, } from "./Table.js";
+export { compareBy, flipSort, moveSort, pressSort, type SortDirection, sortPosition, type SortState, } from "./sorting.js";
+export { CELL_TONE, Table, Td, Th, THead, Tr } from "./Table.js";

package/dist/primitives/table/index.js

@@ -7,4 +7,5 @@ export { PivotTable, } from "./PivotTable.js";
 export { ReportTable, } from "./ReportTable.js";
 export { RowActions } from "./RowActions.js";
 export { SheetTable } from "./SheetTable.js";
-export { CELL_TONE, Table, Td, Th, THead, Tr, } from "./Table.js";
+export { compareBy, flipSort, moveSort, pressSort, sortPosition, } from "./sorting.js";
+export { CELL_TONE, Table, Td, Th, THead, Tr } from "./Table.js";

package/dist/primitives/table/rowWindow.d.ts

@@ -36,4 +36,7 @@ export declare function useRowWindow({ count, rowsBefore, getKey, }: {
     pad: (from: number, to: number, columns: number, key: string) => ReactNode;
     /** The spacer after the last drawn row. */
     tail: (columns: number) => ReactNode;
+    /** Scrolls row `index` into the window, so it gets drawn — for a jump past what is drawn
+     *  (`Home`, `End`, «take me to it»). Nothing when the window is off: every row is there. */
+    reveal: (index: number) => void;
 };

package/dist/primitives/table/rowWindow.js

@@ -173,5 +173,9 @@ export function useRowWindow({ count, rowsBefore = 1, getKey, }) {
             const end = rows.length === 0 ? 0 : rows[rows.length - 1].end;
             return spacer(total - end, columns, "\u0000tail");
         },
+        reveal: (index) => {
+            if (on && scroller !== null)
+                v.scrollToIndex(index, { align: "auto" });
+        },
     };
 }

package/dist/primitives/table/sorting.d.ts

@@ -0,0 +1,42 @@
+export type SortDirection = "asc" | "desc";
+/** One criterion: a field and its direction. */
+export interface SortState {
+    key: string;
+    direction: SortDirection;
+}
+/** Where a column stands in the order: its place (0 = the primary) and direction. */
+export declare function sortPosition(sort: readonly SortState[] | undefined, key: string): {
+    index: number;
+    direction: SortDirection;
+} | null;
+/**
+ * What a press on a column header does to the order.
+ *
+ * Plain press — the column ALONE:
+ *   - the only criterion: asc → desc → nothing. The third press gives the
+ *     natural order back (see `Table.tsx`).
+ *   - with others around it: the column alone, flipped if it was there, and
+ *     never «nothing» — a press that also wipes the tie-breakers someone built
+ *     in the panel would be a surprise, not a shortcut.
+ *
+ * `additive` (Shift) — one more tie-breaker, the others untouched:
+ *   - absent: appended, ascending.
+ *   - ascending: flipped in its place.
+ *   - descending: taken out.
+ */
+export declare function pressSort(sort: readonly SortState[], key: string, additive: boolean): SortState[];
+/** The criterion at `index` with its direction flipped. */
+export declare function flipSort(sort: readonly SortState[], index: number): SortState[];
+/** The criteria with the ones in `keys` moved to sit before `target` (or after it). The
+ *  shape React Aria's drag-and-drop hands over: a set of dragged keys and a drop target. */
+export declare function moveSort(sort: readonly SortState[], keys: ReadonlySet<string>, target: string, position: "before" | "after"): SortState[];
+/**
+ * Compares two rows by every criterion, in order: the second one speaks only when the first
+ * one ties. `read` gives each row's value for a field; `undefined` there means «this field
+ * cannot be sorted here» and the criterion is skipped.
+ *
+ * Missing values go LAST whatever the direction. A blank is not «the smallest»: it is the
+ * absence of an answer, and putting it first when the order is flipped fills the first
+ * screen with the rows that say the least.
+ */
+export declare function compareBy<T>(sort: readonly SortState[], read: (key: string) => ((row: T) => string | number | null | undefined) | undefined): (a: T, b: T) => number;

package/dist/primitives/table/sorting.js

@@ -0,0 +1,110 @@
+/* ==================================================================== *
+ *  SORTING — an ordered list of criteria, not one column.
+ *
+ *  Context: the order of a set was ONE field and a direction. That answers
+ *  «the newest first», and not the question people actually asked the list:
+ *  «by date, and within the same date by customer, and then by product». The
+ *  second and third fields are tie-breakers — they only decide between rows the
+ *  first one left equal — and the engine's criteria already takes them
+ *  (`order: [{ field, descending }, …]`). What could not say it was the screen.
+ *
+ *  So the order is a LIST, outermost first. Empty is «as they came»: the
+ *  third state of a header, which gives the natural order back.
+ *
+ *  The two doors to it write the same list:
+ *
+ *      header click        this column alone — the quick question
+ *      header Shift+click  this column as one more tie-breaker
+ *      the bar's panel     the whole list: add, flip, reorder, remove
+ *
+ *  Pure, and in the table family because the header (`Th`) is its first user;
+ *  the list's bar reads it from here.
+ * ==================================================================== */
+/** Where a column stands in the order: its place (0 = the primary) and direction. */
+export function sortPosition(sort, key) {
+    const index = sort?.findIndex((one) => one.key === key) ?? -1;
+    if (index === -1 || sort === undefined)
+        return null;
+    return { index, direction: sort[index]?.direction ?? "asc" };
+}
+/**
+ * What a press on a column header does to the order.
+ *
+ * Plain press — the column ALONE:
+ *   - the only criterion: asc → desc → nothing. The third press gives the
+ *     natural order back (see `Table.tsx`).
+ *   - with others around it: the column alone, flipped if it was there, and
+ *     never «nothing» — a press that also wipes the tie-breakers someone built
+ *     in the panel would be a surprise, not a shortcut.
+ *
+ * `additive` (Shift) — one more tie-breaker, the others untouched:
+ *   - absent: appended, ascending.
+ *   - ascending: flipped in its place.
+ *   - descending: taken out.
+ */
+export function pressSort(sort, key, additive) {
+    const at = sortPosition(sort, key);
+    if (additive) {
+        if (at === null)
+            return [...sort, { key, direction: "asc" }];
+        if (at.direction === "asc") {
+            return sort.map((one, i) => (i === at.index ? { key, direction: "desc" } : one));
+        }
+        return sort.filter((_, i) => i !== at.index);
+    }
+    if (at === null)
+        return [{ key, direction: "asc" }];
+    if (sort.length === 1)
+        return at.direction === "asc" ? [{ key, direction: "desc" }] : [];
+    return [{ key, direction: at.direction === "asc" ? "desc" : "asc" }];
+}
+/** The criterion at `index` with its direction flipped. */
+export function flipSort(sort, index) {
+    return sort.map((one, i) => i === index ? { ...one, direction: one.direction === "asc" ? "desc" : "asc" } : one);
+}
+/** The criteria with the ones in `keys` moved to sit before `target` (or after it). The
+ *  shape React Aria's drag-and-drop hands over: a set of dragged keys and a drop target. */
+export function moveSort(sort, keys, target, position) {
+    const moving = sort.filter((one) => keys.has(one.key));
+    const rest = sort.filter((one) => !keys.has(one.key));
+    const at = rest.findIndex((one) => one.key === target);
+    if (at === -1 || moving.length === 0)
+        return [...sort];
+    const cut = position === "before" ? at : at + 1;
+    return [...rest.slice(0, cut), ...moving, ...rest.slice(cut)];
+}
+/**
+ * Compares two rows by every criterion, in order: the second one speaks only when the first
+ * one ties. `read` gives each row's value for a field; `undefined` there means «this field
+ * cannot be sorted here» and the criterion is skipped.
+ *
+ * Missing values go LAST whatever the direction. A blank is not «the smallest»: it is the
+ * absence of an answer, and putting it first when the order is flipped fills the first
+ * screen with the rows that say the least.
+ */
+export function compareBy(sort, read) {
+    const criteria = sort.flatMap((one) => {
+        const value = read(one.key);
+        return value === undefined ? [] : [{ value, sign: one.direction === "asc" ? 1 : -1 }];
+    });
+    return (a, b) => {
+        for (const { value, sign } of criteria) {
+            const left = value(a);
+            const right = value(b);
+            const leftMissing = left === null || left === undefined || left === "";
+            const rightMissing = right === null || right === undefined || right === "";
+            if (leftMissing && rightMissing)
+                continue;
+            if (leftMissing)
+                return 1;
+            if (rightMissing)
+                return -1;
+            const order = typeof left === "number" && typeof right === "number"
+                ? left - right
+                : String(left).localeCompare(String(right));
+            if (order !== 0)
+                return order * sign;
+        }
+        return 0;
+    };
+}

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

@@ -0,0 +1,10 @@
+/** The HTML with everything that runs taken out, or `null` where there is no DOM to do it. */
+export declare function sanitizeRichText(html: string): string | null;
+/** The words of an HTML, without its tags: what is shown where it cannot be cleaned. */
+export declare function richTextPlain(html: string): string;
+/** Nothing written: no text and no image — «<p></p>» from an emptied editor counts as nothing. */
+export declare function isRichTextEmpty(html: string | null | undefined): boolean;
+/** The HTML of a note, read: cleaned, in the system's text style (`rich-text` in tokens.css). */
+export declare function RichTextValue({ value }: {
+    value: string | null | undefined;
+}): import("react").JSX.Element;

package/dist/primitives/value/RichText.js

@@ -0,0 +1,130 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useUiCopy } from "../../foundations/copy.js";
+import DOMPurify from "dompurify";
+import { useSyncExternalStore } from "react";
+/* ==================================================================== *
+ *  RICH TEXT, READ — the HTML of a note shown as what it says.
+ *
+ *  Context: this HTML comes from people (a description pasted from an email)
+ *  and from engines (an Odoo `html` field), and either can carry a script, an
+ *  `onerror`, a `javascript:` link. So it is never put on the page as it came:
+ *  DOMPurify keeps the text and its structure (paragraphs, headings, lists,
+ *  links, tables, a mention) and drops everything that runs. A link always
+ *  opens in another tab, without handing that tab our window.
+ *
+ *  ── On the server there is no DOM to clean with ─────────────────────
+ *
+ *  DOMPurify needs a document. Without one (server rendering, a Node test), the
+ *  safe answer is the TEXT, tags removed and escaped by React — never the HTML
+ *  unchecked. The browser then upgrades it to the cleaned HTML; the switch goes
+ *  through `useSyncExternalStore`, so hydration does not see two different trees.
+ * ==================================================================== */
+const ALLOWED_TAGS = [
+    "p",
+    "br",
+    "strong",
+    "b",
+    "em",
+    "i",
+    "u",
+    "s",
+    "strike",
+    "del",
+    "code",
+    "pre",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "ul",
+    "ol",
+    "li",
+    "blockquote",
+    "hr",
+    "a",
+    "span",
+    "table",
+    "thead",
+    "tbody",
+    "tr",
+    "th",
+    "td",
+    "colgroup",
+    "col",
+    "img",
+];
+const ALLOWED_ATTR = [
+    "href",
+    "title",
+    "colspan",
+    "rowspan",
+    "src",
+    "alt",
+    "data-type",
+    "data-id",
+    "data-label",
+];
+let hooked = false;
+/** The HTML with everything that runs taken out, or `null` where there is no DOM to do it. */
+export function sanitizeRichText(html) {
+    if (typeof window === "undefined" || !DOMPurify.isSupported)
+        return null;
+    if (!hooked) {
+        hooked = true;
+        DOMPurify.addHook("afterSanitizeAttributes", (node) => {
+            if (node.tagName === "A") {
+                node.setAttribute("target", "_blank");
+                node.setAttribute("rel", "noopener noreferrer");
+            }
+            if (node.tagName === "IMG") {
+                /* An image whose address was not allowed is a broken box: gone. One without a
+                   description is read as decoration (`alt=""`) instead of as its file name. */
+                if (!node.hasAttribute("src"))
+                    node.remove();
+                else if (!node.hasAttribute("alt"))
+                    node.setAttribute("alt", "");
+            }
+        });
+    }
+    return DOMPurify.sanitize(html, {
+        ALLOWED_TAGS,
+        ALLOWED_ATTR,
+        ALLOWED_URI_REGEXP: /^(?:https?:|mailto:|tel:|data:image\/(?:png|jpeg|gif|webp);)/i,
+    });
+}
+/** The words of an HTML, without its tags: what is shown where it cannot be cleaned. */
+export function richTextPlain(html) {
+    return html
+        .replace(/<(?:br|\/p|\/li|\/h[1-6]|\/tr)\s*\/?>/gi, " ")
+        .replace(/<[^>]*>/g, "")
+        .replace(/&nbsp;/g, " ")
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** Nothing written: no text and no image — «<p></p>» from an emptied editor counts as nothing. */
+export function isRichTextEmpty(html) {
+    if (html === null || html === undefined)
+        return true;
+    return richTextPlain(html) === "" && !/<(?:img|hr|table)\b/i.test(html);
+}
+const subscribe = () => () => { };
+/** The HTML of a note, read: cleaned, in the system's text style (`rich-text` in tokens.css). */
+export function RichTextValue({ value }) {
+    const unset = useUiCopy().field.unset;
+    const inBrowser = useSyncExternalStore(subscribe, () => true, () => false);
+    if (isRichTextEmpty(value)) {
+        return _jsx("span", { className: "text-meta text-muted italic", children: unset });
+    }
+    const html = value ?? "";
+    const clean = inBrowser ? sanitizeRichText(html) : null;
+    if (clean === null)
+        return _jsx("p", { className: "rich-text", children: richTextPlain(html) });
+    /* Cleaned by DOMPurify just above, with the tags and URLs listed there. */
+    return _jsx("div", { className: "rich-text min-w-0", dangerouslySetInnerHTML: { __html: clean } });
+}

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

@@ -1,3 +1,4 @@
+import { type Rounding } from "./rounding.js";
 import type { ReactNode } from "react";
 export declare const formatCount: (value: number, locale?: string) => string;
 export declare const formatNumber: (value: number, locale?: string) => string;
@@ -7,6 +8,10 @@ export declare function KeyValue({ label, value }: {
     label: string;
     value: ReactNode;
 }): import("react").JSX.Element;
+/** A number written with any `Intl.NumberFormatOptions` — a currency, a percentage, fixed
+ *  decimals — in the session locale. The same options `NumberInput` takes, so a value reads
+ *  the same in its form and in the cell or the figure that shows it elsewhere. */
+export declare const formatWith: (value: number, options: Intl.NumberFormatOptions, locale?: string) => string;
 /**
  * A number with its unit: right aligned, with tabular figures.
  *
@@ -14,11 +19,24 @@ export declare function KeyValue({ label, value }: {
  * the same width, so `32.561` lines up across rows exactly as it did in monospace — without
  * making a business report look like a terminal. The unit stays in the same face so the
  * digits keep their column.
+ *
+ * `format` is a preset or any `Intl.NumberFormatOptions`: `{ style: "currency", currency:
+ * "BOB" }` writes «Bs 1.234,50», `{ style: "percent" }` takes 0–1, `{ minimumFractionDigits:
+ * 2, maximumFractionDigits: 2 }` rounds to two. `align="left"` for a figure that is not in a
+ * column.
  */
-export declare function Numeric({ value, unit, format, }: {
+export declare function Numeric({ value, unit, format, align, rounding, signed, }: {
     value: number;
     unit?: string;
-    format?: "integer" | "decimal" | "distance";
+    format?: "integer" | "decimal" | "distance" | Intl.NumberFormatOptions;
+    align?: "right" | "left";
+    /** Round the VALUE before writing it — to 0,05 for cash, to the unit's precision. See
+     *  `rounding.ts`: the format alone only rounds what is drawn. */
+    rounding?: Rounding;
+    /** A figure whose sign is the point — a balance, a difference, a variation: it carries
+     *  «+» or «−» always, and a negative is drawn in the danger tone (the sign says it too, so
+     *  it never rests on the color alone). */
+    signed?: boolean;
 }): import("react").JSX.Element;
 /**
  * The content of a data cell, with what the system decides and the view does not.

package/dist/primitives/value/Value.js

@@ -1,6 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { currentCopyLocale, useUiCopy } from "../../foundations/copy.js";
+import { roundTo } from "./rounding.js";
 /**
  * Context: the mono/sans rule decides everything in here. The label goes in
  * PROPORTIONAL —«orígenes», «mediana» are words, not data— and the value in
@@ -31,6 +32,17 @@ export const formatDistance = (value, locale = currentCopyLocale()) => distanceF
 export function KeyValue({ label, value }) {
     return (_jsxs("div", { className: "min-w-0", children: [_jsx("dt", { className: "text-micro text-muted", children: label }), _jsx("dd", { className: "mt-0.5 truncate text-lead tabular-nums text-ink", children: value })] }));
 }
+/** The three presets, as the options they are — so `signed` and a custom format share one
+ *  path. Kept in step with `integerFormat`, `decimalFormat` and `distanceFormat` above. */
+const PRESET = {
+    integer: { maximumFractionDigits: 0 },
+    decimal: { maximumFractionDigits: 2 },
+    distance: { minimumFractionDigits: 4, maximumFractionDigits: 4 },
+};
+/** A number written with any `Intl.NumberFormatOptions` — a currency, a percentage, fixed
+ *  decimals — in the session locale. The same options `NumberInput` takes, so a value reads
+ *  the same in its form and in the cell or the figure that shows it elsewhere. */
+export const formatWith = (value, options, locale = currentCopyLocale()) => new Intl.NumberFormat(locale, options).format(value);
 /**
  * A number with its unit: right aligned, with tabular figures.
  *
@@ -38,14 +50,21 @@ export function KeyValue({ label, value }) {
  * the same width, so `32.561` lines up across rows exactly as it did in monospace — without
  * making a business report look like a terminal. The unit stays in the same face so the
  * digits keep their column.
+ *
+ * `format` is a preset or any `Intl.NumberFormatOptions`: `{ style: "currency", currency:
+ * "BOB" }` writes «Bs 1.234,50», `{ style: "percent" }` takes 0–1, `{ minimumFractionDigits:
+ * 2, maximumFractionDigits: 2 }` rounds to two. `align="left"` for a figure that is not in a
+ * column.
  */
-export function Numeric({ value, unit, format = "integer", }) {
-    const text = format === "distance"
-        ? formatDistance(value)
-        : format === "decimal"
-            ? formatNumber(value)
-            : formatCount(value);
-    return (_jsxs("span", { className: "block text-right text-body tabular-nums whitespace-nowrap text-ink", children: [_jsx("span", { className: "tabular-nums", children: text }), unit === undefined ? null : _jsx("span", { className: "ml-1 text-muted", children: unit })] }));
+export function Numeric({ value, unit, format = "integer", align = "right", rounding, signed = false, }) {
+    /* The locale of the copy in context, as `NumberInput` reads it — not only the installed
+       one: inside a `UiCopyProvider` the cell and the form next to it write the same digits. */
+    const { locale } = useUiCopy();
+    const shown = rounding === undefined ? value : roundTo(value, rounding.increment, rounding.method);
+    const options = typeof format === "object" ? format : PRESET[format];
+    const text = formatWith(shown, signed ? { ...options, signDisplay: "exceptZero" } : options, locale);
+    const negative = signed && shown < 0;
+    return (_jsxs("span", { className: `${align === "left" ? "inline-block text-left" : "block text-right"} text-body tabular-nums whitespace-nowrap ${negative ? "text-danger" : "text-ink"}`, children: [_jsx("span", { className: "tabular-nums", children: text }), unit === undefined ? null : _jsx("span", { className: "ml-1 text-muted", children: unit })] }));
 }
 /**
  * The content of a data cell, with what the system decides and the view does not.

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

@@ -5,5 +5,7 @@ export { Metric, type MetricProps, Metrics } from "./Metric.js";
 export { Avatar, type AvatarSize, type PersonContact, UserChip, type UserChipProps, UserStack, } from "./Person.js";
 export { ProgressBar, type ProgressBarProps, } from "./ProgressBar.js";
 export { RelationCard, type RelationCardProps, type RelationSummary, RelationValue, type RelationValueProps, } from "./Relation.js";
+export { isRichTextEmpty, richTextPlain, RichTextValue, sanitizeRichText, } from "./RichText.js";
+export { type Rounding, type RoundingMethod, roundTo, } from "./rounding.js";
 export { Totals, type TotalsCredit, type TotalsDeduction, type TotalsFact, type TotalsProps, type TotalsRow, } from "./Totals.js";
-export { Cell, formatCount, formatDistance, formatNumber, KeyValue, Numeric, } from "./Value.js";
+export { Cell, formatCount, formatDistance, formatNumber, formatWith, KeyValue, Numeric, } from "./Value.js";

package/dist/primitives/value/index.js

@@ -6,5 +6,8 @@ export { Metric, Metrics } from "./Metric.js";
 export { Avatar, UserChip, UserStack, } from "./Person.js";
 export { ProgressBar, } from "./ProgressBar.js";
 export { RelationCard, RelationValue, } from "./Relation.js";
+/* The HTML of a note, read — cleaned of anything that runs. */
+export { isRichTextEmpty, richTextPlain, RichTextValue, sanitizeRichText, } from "./RichText.js";
+export { roundTo, } from "./rounding.js";
 export { Totals, } from "./Totals.js";
-export { Cell, formatCount, formatDistance, formatNumber, KeyValue, Numeric, } from "./Value.js";
+export { Cell, formatCount, formatDistance, formatNumber, formatWith, KeyValue, Numeric, } from "./Value.js";

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

@@ -0,0 +1,9 @@
+export type RoundingMethod = "half-up" | "half-even" | "up" | "down";
+export type Rounding = {
+    /** The multiple: 0.05 rounds to five cents, 1 to a whole unit, 0.001 to grams. */
+    increment: number;
+    /** `half-up` by default — what a price expects. `up`/`down` are away from/towards zero. */
+    method?: RoundingMethod;
+};
+/** `value` rounded to a multiple of `increment`, by `method`. */
+export declare function roundTo(value: number, increment: number, method?: RoundingMethod): number;

package/dist/primitives/value/rounding.js

@@ -0,0 +1,48 @@
+/* ==================================================================== *
+ *  ROUNDING — to a multiple, and saying how.
+ *
+ *  Context: `maximumFractionDigits` rounds what is DRAWN; the value underneath
+ *  keeps its tail, and a total of drawn values then differs from the drawn
+ *  total by a cent. An ERP rounds the VALUE, and not always to a decimal: cash
+ *  to 0,05 (Bolivia has no 1-centavo coin in circulation), a unit of measure to
+ *  its precision (a box is 1, a kilo 0,001), a price to 0,10. And the method
+ *  is part of the rule: half up for a price, half even for statistics, up for
+ *  what is charged per started hour, down for what is paid.
+ *
+ *  Pure, in the display tier so a value that shows (`Numeric`) and a control
+ *  that asks (`NumberInput`) round with the same function.
+ * ==================================================================== */
+/** How many decimals a number is written with: 0.05 → 2. Used to cut the binary tail that
+ *  `0.1 + 0.2` leaves, so 1.15 rounded to 0.05 is 1.15 and not 1.1500000000000001. */
+function decimalsOf(value) {
+    const text = String(value);
+    if (text.includes("e-"))
+        return Number(text.split("e-")[1]);
+    return text.includes(".") ? (text.split(".")[1]?.length ?? 0) : 0;
+}
+/** `value` rounded to a multiple of `increment`, by `method`. */
+export function roundTo(value, increment, method = "half-up") {
+    if (!Number.isFinite(value) || !(increment > 0))
+        return value;
+    const decimals = decimalsOf(increment);
+    /* The quotient, cleaned of the float tail before deciding: 1.15 / 0.05 is 22.999999… */
+    const steps = Number((Math.abs(value) / increment).toFixed(9));
+    const whole = Math.floor(steps);
+    const fraction = Number((steps - whole).toFixed(9));
+    let rounded;
+    switch (method) {
+        case "up":
+            rounded = fraction > 0 ? whole + 1 : whole;
+            break;
+        case "down":
+            rounded = whole;
+            break;
+        case "half-even":
+            rounded = fraction > 0.5 || (fraction === 0.5 && whole % 2 === 1) ? whole + 1 : whole;
+            break;
+        default:
+            rounded = fraction >= 0.5 ? whole + 1 : whole;
+    }
+    const result = Number((rounded * increment).toFixed(decimals));
+    return value < 0 ? -result : result;
+}