@sincpro/web-ui 1.5.0 → 1.7.0

package/dist/primitives/field/mask.d.ts

@@ -0,0 +1,33 @@
+import { type RefObject } from "react";
+export type MaskedChange = {
+    next: string;
+    caret: number;
+};
+/**
+ * What a keystroke did to a masked value.
+ *
+ *     raw      the input's text right after the keystroke
+ *     at       the caret in `raw`
+ *     current  the significant characters before it
+ *     drawn    how `current` was drawn
+ *     clean    the significant characters of any text
+ *     max      the most of them the value takes
+ */
+export declare function maskedChange({ raw, at, current, drawn, clean, max, }: {
+    raw: string;
+    at: number;
+    current: string;
+    drawn: string;
+    clean: (text: string) => string;
+    max: number;
+}): MaskedChange;
+/** Where, in the drawn text, the caret goes to sit after `count` significant characters. */
+export declare function caretAfter(drawn: string, count: number, significant: (char: string) => boolean): number;
+/**
+ * The input's ref, and `keep(count)` to call in `onChange`: once the new text is drawn, the
+ * caret goes back after `count` significant characters.
+ */
+export declare function useMaskCaret(drawn: string, significant: (char: string) => boolean): {
+    input: RefObject<HTMLInputElement | null>;
+    keep: (count: number) => void;
+};

package/dist/primitives/field/mask.js

@@ -0,0 +1,56 @@
+"use client";
+import { useLayoutEffect, useRef } from "react";
+/**
+ * What a keystroke did to a masked value.
+ *
+ *     raw      the input's text right after the keystroke
+ *     at       the caret in `raw`
+ *     current  the significant characters before it
+ *     drawn    how `current` was drawn
+ *     clean    the significant characters of any text
+ *     max      the most of them the value takes
+ */
+export function maskedChange({ raw, at, current, drawn, clean, max, }) {
+    let next = clean(raw);
+    let before = clean(raw.slice(0, at)).length;
+    if (next === current && raw.length < drawn.length && before > 0) {
+        next = next.slice(0, before - 1) + next.slice(before);
+        before -= 1;
+    }
+    next = next.slice(0, max);
+    return { next, caret: Math.min(before, next.length) };
+}
+/** Where, in the drawn text, the caret goes to sit after `count` significant characters. */
+export function caretAfter(drawn, count, significant) {
+    let seen = 0;
+    let at = 0;
+    while (at < drawn.length && seen < count) {
+        if (significant(drawn[at] ?? ""))
+            seen++;
+        at++;
+    }
+    return at;
+}
+/**
+ * The input's ref, and `keep(count)` to call in `onChange`: once the new text is drawn, the
+ * caret goes back after `count` significant characters.
+ */
+export function useMaskCaret(drawn, significant) {
+    const input = useRef(null);
+    const pending = useRef(null);
+    useLayoutEffect(() => {
+        const element = input.current;
+        const want = pending.current;
+        if (element === null || want === null)
+            return;
+        pending.current = null;
+        const at = caretAfter(drawn, want, significant);
+        element.setSelectionRange(at, at);
+    }, [drawn, significant]);
+    return {
+        input,
+        keep: (count) => {
+            pending.current = count;
+        },
+    };
+}

package/dist/primitives/field/media.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The arithmetic behind the two media controls — the crop of `ImageInput` and the strokes of
+ * `SignatureInput` — kept apart from the canvas so it can be checked without a browser.
+ *
+ * Context: a crop that is off by half a pixel, or a pan that lets the frame slide past the
+ * edge of the photo, is invisible in a story and obvious on the avatar a hundred screens
+ * later. Here the rules are plain functions over sizes and points; the components only
+ * read the pointer and the keys, ask these where things go, and paint.
+ */
+export type Size = {
+    width: number;
+    height: number;
+};
+export type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type Point = {
+    x: number;
+    y: number;
+};
+/** Where the frame sits on the image: how much it is zoomed in (1 = the image just covers
+ *  the frame) and the CENTRE of the frame, as a fraction of the image's width and height.
+ *  Fractions and not pixels so the same crop holds whatever size the image is drawn at. */
+export type Crop = {
+    zoom: number;
+    x: number;
+    y: number;
+};
+/** Past four times the photo is mostly blur: the limit is about what is worth keeping. */
+export declare const CROP_MAX_ZOOM = 4;
+export declare const CROP_CENTERED: Crop;
+/** The crop made valid: zoom within `[1, CROP_MAX_ZOOM]`, and the centre held far enough
+ *  from the edges that the frame never shows past the image. */
+export declare function clampCrop(image: Size, aspect: number, crop: Crop): Crop;
+/** The part of the image the frame shows, in image pixels — what `drawImage` reads from. */
+export declare function cropRegion(image: Size, aspect: number, crop: Crop): Rect;
+/**
+ * Moves the IMAGE under the frame by a fraction of the frame — the way a drag does: dragging
+ * right by a quarter of the frame slides the photo right by a quarter, so the frame now shows
+ * more of its left side. The arrow keys move it the same way, so the hand and the keyboard
+ * never disagree about which way is which.
+ */
+export declare function panCrop(image: Size, aspect: number, crop: Crop, dx: number, dy: number): Crop;
+/** Zooms by `factor` about the frame's centre (the point the person is looking at). */
+export declare function zoomCrop(image: Size, aspect: number, crop: Crop, factor: number): Crop;
+/** The size the cropped image is written at: the region's own pixels, never upscaled (a
+ *  bigger file of the same blur), and at most `maxSide` on its longer side. */
+export declare function outputSize(region: Size, maxSide: number): Size;
+/** Whether a file is an image the browser can draw. A dropped file is not filtered by
+ *  `accept`, so the type is checked here — and by its extension when the system did not
+ *  say its type, which happens for a file dragged from some file managers. */
+export declare function isImageFile(file: {
+    type: string;
+    name: string;
+}): boolean;
+/** The type a crop is written in: JPEG and WebP stay what they were (a photo as PNG is five
+ *  times heavier for nothing); everything else becomes PNG, which keeps transparency. */
+export declare function croppedType(type: string): "image/png" | "image/jpeg" | "image/webp";
+/** The file's name with the extension of the type it was written in: «logo.gif» cropped to
+ *  a PNG is «logo.png», so the server does not trust a name that lies about its content. */
+export declare function croppedName(name: string, type: string): string;
+/** One instruction of a stroke's path, in the canvas's terms. */
+export type PathStep = {
+    kind: "dot";
+    at: Point;
+} | {
+    kind: "move";
+    to: Point;
+} | {
+    kind: "quad";
+    control: Point;
+    to: Point;
+} | {
+    kind: "line";
+    to: Point;
+};
+/**
+ * The path of one stroke, smoothed: each sampled point becomes the CONTROL of a quadratic
+ * curve that runs between the midpoints around it.
+ *
+ * Context: joining the pointer's samples with straight lines draws a polygon — at the speed
+ * a signature is written the samples are far apart, and every corner shows. Curving through
+ * the midpoints passes near every sample without a corner at any of them, and costs nothing:
+ * no pressure, no velocity, no library. A single sample is a tap — a dot, the one over an i.
+ */
+export declare function strokeSteps(points: readonly Point[]): PathStep[];
+/** The font size a typed name is written at so it fits `maxWidth`: `size` when it fits, and
+ *  smaller in proportion when it does not — a long name is still one line, never cut. */
+export declare function fitFontSize(widthAtSize: number, size: number, maxWidth: number, min?: number): number;
+/** Keeps a pointer's moves on the element that started a drag, even when it leaves it — a
+ *  stroke that runs off the pad is still one stroke. A pointer the browser no longer tracks
+ *  (a synthetic one, or one already lifted) cannot be captured, and the drag works without. */
+export declare function capturePointer(event: {
+    currentTarget: Element;
+    pointerId: number;
+}): void;

package/dist/primitives/field/media.js

@@ -0,0 +1,136 @@
+/**
+ * The arithmetic behind the two media controls — the crop of `ImageInput` and the strokes of
+ * `SignatureInput` — kept apart from the canvas so it can be checked without a browser.
+ *
+ * Context: a crop that is off by half a pixel, or a pan that lets the frame slide past the
+ * edge of the photo, is invisible in a story and obvious on the avatar a hundred screens
+ * later. Here the rules are plain functions over sizes and points; the components only
+ * read the pointer and the keys, ask these where things go, and paint.
+ */
+/** Past four times the photo is mostly blur: the limit is about what is worth keeping. */
+export const CROP_MAX_ZOOM = 4;
+export const CROP_CENTERED = { zoom: 1, x: 0.5, y: 0.5 };
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+/** The width of the frame, in image pixels, at zoom 1: the largest box of `aspect` that fits
+ *  inside the image. «Cover», never «contain» — a crop never adds empty bands. */
+function coverWidth(image, aspect) {
+    return Math.min(image.width, image.height * aspect);
+}
+/** The crop made valid: zoom within `[1, CROP_MAX_ZOOM]`, and the centre held far enough
+ *  from the edges that the frame never shows past the image. */
+export function clampCrop(image, aspect, crop) {
+    const zoom = clamp(Number.isFinite(crop.zoom) ? crop.zoom : 1, 1, CROP_MAX_ZOOM);
+    const width = coverWidth(image, aspect) / zoom;
+    const height = width / aspect;
+    const halfX = width / 2 / image.width;
+    const halfY = height / 2 / image.height;
+    return {
+        zoom,
+        x: clamp(crop.x, halfX, 1 - halfX),
+        y: clamp(crop.y, halfY, 1 - halfY),
+    };
+}
+/** The part of the image the frame shows, in image pixels — what `drawImage` reads from. */
+export function cropRegion(image, aspect, crop) {
+    const valid = clampCrop(image, aspect, crop);
+    const width = coverWidth(image, aspect) / valid.zoom;
+    const height = width / aspect;
+    return {
+        x: valid.x * image.width - width / 2,
+        y: valid.y * image.height - height / 2,
+        width,
+        height,
+    };
+}
+/**
+ * Moves the IMAGE under the frame by a fraction of the frame — the way a drag does: dragging
+ * right by a quarter of the frame slides the photo right by a quarter, so the frame now shows
+ * more of its left side. The arrow keys move it the same way, so the hand and the keyboard
+ * never disagree about which way is which.
+ */
+export function panCrop(image, aspect, crop, dx, dy) {
+    const region = cropRegion(image, aspect, crop);
+    return clampCrop(image, aspect, {
+        ...crop,
+        x: crop.x - (dx * region.width) / image.width,
+        y: crop.y - (dy * region.height) / image.height,
+    });
+}
+/** Zooms by `factor` about the frame's centre (the point the person is looking at). */
+export function zoomCrop(image, aspect, crop, factor) {
+    return clampCrop(image, aspect, { ...crop, zoom: crop.zoom * factor });
+}
+/** The size the cropped image is written at: the region's own pixels, never upscaled (a
+ *  bigger file of the same blur), and at most `maxSide` on its longer side. */
+export function outputSize(region, maxSide) {
+    const scale = Math.min(1, maxSide / Math.max(region.width, region.height));
+    return {
+        width: Math.max(1, Math.round(region.width * scale)),
+        height: Math.max(1, Math.round(region.height * scale)),
+    };
+}
+/** Whether a file is an image the browser can draw. A dropped file is not filtered by
+ *  `accept`, so the type is checked here — and by its extension when the system did not
+ *  say its type, which happens for a file dragged from some file managers. */
+export function isImageFile(file) {
+    if (file.type !== "")
+        return file.type.startsWith("image/");
+    return /\.(?:png|jpe?g|gif|webp|avif|bmp|svg)$/i.test(file.name);
+}
+/** The type a crop is written in: JPEG and WebP stay what they were (a photo as PNG is five
+ *  times heavier for nothing); everything else becomes PNG, which keeps transparency. */
+export function croppedType(type) {
+    return type === "image/jpeg" || type === "image/webp" ? type : "image/png";
+}
+/** The file's name with the extension of the type it was written in: «logo.gif» cropped to
+ *  a PNG is «logo.png», so the server does not trust a name that lies about its content. */
+export function croppedName(name, type) {
+    const extension = type === "image/jpeg" ? "jpg" : type === "image/webp" ? "webp" : "png";
+    const base = name.replace(/\.[^./]+$/, "");
+    return `${base === "" ? "imagen" : base}.${extension}`;
+}
+const midpoint = (a, b) => ({ x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 });
+/**
+ * The path of one stroke, smoothed: each sampled point becomes the CONTROL of a quadratic
+ * curve that runs between the midpoints around it.
+ *
+ * Context: joining the pointer's samples with straight lines draws a polygon — at the speed
+ * a signature is written the samples are far apart, and every corner shows. Curving through
+ * the midpoints passes near every sample without a corner at any of them, and costs nothing:
+ * no pressure, no velocity, no library. A single sample is a tap — a dot, the one over an i.
+ */
+export function strokeSteps(points) {
+    const first = points[0];
+    if (first === undefined)
+        return [];
+    if (points.length === 1)
+        return [{ kind: "dot", at: first }];
+    const steps = [{ kind: "move", to: first }];
+    for (let i = 1; i < points.length - 1; i += 1) {
+        steps.push({
+            kind: "quad",
+            control: points[i],
+            to: midpoint(points[i], points[i + 1]),
+        });
+    }
+    steps.push({ kind: "line", to: points[points.length - 1] });
+    return steps;
+}
+/** The font size a typed name is written at so it fits `maxWidth`: `size` when it fits, and
+ *  smaller in proportion when it does not — a long name is still one line, never cut. */
+export function fitFontSize(widthAtSize, size, maxWidth, min = 12) {
+    if (widthAtSize <= maxWidth || widthAtSize <= 0)
+        return size;
+    return Math.max(min, Math.floor((size * maxWidth) / widthAtSize));
+}
+/** Keeps a pointer's moves on the element that started a drag, even when it leaves it — a
+ *  stroke that runs off the pad is still one stroke. A pointer the browser no longer tracks
+ *  (a synthetic one, or one already lifted) cannot be captured, and the drag works without. */
+export function capturePointer(event) {
+    try {
+        event.currentTarget.setPointerCapture(event.pointerId);
+    }
+    catch {
+        /* Not capturable: the moves still arrive while the pointer stays over the element. */
+    }
+}

package/dist/primitives/field/pattern.d.ts

@@ -0,0 +1,10 @@
+/** What of a text fills the pattern's slots, in order — a character a slot does not take is
+ *  dropped, letters go to capitals. «1020304-5» on «###-#######» is «10203045». */
+export declare function patternValue(text: string, pattern: string): string;
+/** The value drawn on the pattern, up to its last character: a separator is drawn only once
+ *  something comes after it, so deleting never leaves a dangling «-». */
+export declare function formatPattern(value: string, pattern: string): string;
+/** Every slot is filled. */
+export declare function isPatternComplete(value: string, pattern: string): boolean;
+/** How many characters the pattern takes. */
+export declare function patternLength(pattern: string): number;

package/dist/primitives/field/pattern.js

@@ -0,0 +1,68 @@
+/* ==================================================================== *
+ *  A PATTERN — where each character of an identifier goes.
+ *
+ *      #   a digit
+ *      A   a letter, written in capitals
+ *      *   a letter or a digit
+ *
+ *  Anything else is a separator drawn between them: «###-#######» for a
+ *  reference, «AA## #### #### #### #### ####» for an IBAN. Separators are never
+ *  letters or digits — those always mean a slot.
+ *
+ *  The value is only what fills the slots («BO12345…»); the separators are
+ *  drawn. Pure: `PatternInput` types with it and a form checks with it.
+ * ==================================================================== */
+const SLOT = /[#A*]/;
+function fits(slot, char) {
+    if (slot === "#")
+        return /\d/.test(char);
+    if (slot === "A")
+        return /[a-z]/i.test(char);
+    return /[a-z\d]/i.test(char);
+}
+/** The slots of a pattern, in order. */
+function slotsOf(pattern) {
+    return [...pattern].filter((char) => SLOT.test(char));
+}
+/** What of a text fills the pattern's slots, in order — a character a slot does not take is
+ *  dropped, letters go to capitals. «1020304-5» on «###-#######» is «10203045». */
+export function patternValue(text, pattern) {
+    const slots = slotsOf(pattern);
+    let value = "";
+    for (const char of text) {
+        const slot = slots[value.length];
+        if (slot === undefined)
+            break;
+        if (fits(slot, char))
+            value += char.toUpperCase();
+    }
+    return value;
+}
+/** The value drawn on the pattern, up to its last character: a separator is drawn only once
+ *  something comes after it, so deleting never leaves a dangling «-». */
+export function formatPattern(value, pattern) {
+    let out = "";
+    let pending = "";
+    let at = 0;
+    for (const char of pattern) {
+        if (at >= value.length)
+            break;
+        if (SLOT.test(char)) {
+            out += pending + (value[at] ?? "");
+            pending = "";
+            at++;
+        }
+        else {
+            pending += char;
+        }
+    }
+    return out;
+}
+/** Every slot is filled. */
+export function isPatternComplete(value, pattern) {
+    return patternValue(value, pattern).length === slotsOf(pattern).length;
+}
+/** How many characters the pattern takes. */
+export function patternLength(pattern) {
+    return slotsOf(pattern).length;
+}

package/dist/primitives/menu/Menu.d.ts

@@ -65,6 +65,22 @@ declare const WIDTH: {
 /** Every option of the tree by id, children included: a submenu is a separate React Aria
  *  menu with its own `onAction`, and both have to reach the same handlers. */
 export declare function indexOptions(options: readonly MenuOption[], into?: Map<string, MenuOption>): Map<string, MenuOption>;
+/**
+ * The look of a list control's trigger — «Filtros ▾», «Columnas ▾», «Ordenar ▾» — without
+ * the menu.
+ *
+ * Context: a control of the bar that opens a PANEL and not a list of options (the sort
+ * criteria) still has to look like its neighbours; copying these classes is how the third
+ * trigger ends up one pixel off. Same reason `buttonClasses` exists.
+ */
+export declare function menuTriggerClasses({ variant, surface, active, open, focusVisible, iconOnly, }: {
+    variant?: "button" | "text";
+    surface?: "canvas" | "chrome";
+    active?: boolean;
+    open?: boolean;
+    focusVisible?: boolean;
+    iconOnly?: boolean;
+}): string;
 export declare function Menu({ label, groups, onSelect, surface, align, icon: Trigger, 
 /** The menu as a control of a list ("filters ▾") carries the chevron; the
  *  actions `⋯` does not, because the icon already says there is more. */

package/dist/primitives/menu/Menu.js

@@ -26,24 +26,35 @@ export function indexOptions(options, into = new Map()) {
     }
     return into;
 }
-export function Menu({ label, groups, onSelect, surface = "canvas", align = "start", icon: Trigger, 
-/** The menu as a control of a list ("filters ▾") carries the chevron; the
- *  actions `⋯` does not, because the icon already says there is more. */
-chevron = true, active = false, iconOnly = false, variant = "button", searchPlaceholder, emptyText, width = "md", role, size = "md", title, closeOnSelect = true, }) {
-    const copy = useUiCopy();
-    const { contains } = useFilter({ sensitivity: "base" });
+/**
+ * The look of a list control's trigger — «Filtros ▾», «Columnas ▾», «Ordenar ▾» — without
+ * the menu.
+ *
+ * Context: a control of the bar that opens a PANEL and not a list of options (the sort
+ * criteria) still has to look like its neighbours; copying these classes is how the third
+ * trigger ends up one pixel off. Same reason `buttonClasses` exists.
+ */
+export function menuTriggerClasses({ variant = "button", surface = "canvas", active = false, open = false, focusVisible = false, iconOnly = false, }) {
     /* `text` is the menu of a BAR: no frame and no background, just the highlight
        on hover. Five bordered menus on top of an application are five buttons
        competing with the ones in the view, and the bar stops reading as an index.
        `button` is the menu of a CONTROL —"filters ▾", "group ▾"—, and there the
        frame is what says it can be pressed. */
-    const triggerClass = (open) => variant === "text"
+    const tone = variant === "text"
         ? surface === "chrome"
             ? `border-transparent text-chrome-muted hover:bg-chrome-ink/12 hover:text-chrome-ink ${active || open ? "bg-chrome-ink/12 text-chrome-ink" : ""}`
             : `border-transparent text-muted hover:bg-ink/6 hover:text-ink ${active || open ? "bg-ink/6 text-ink" : ""}`
         : surface === "chrome"
             ? `border-chrome-muted/35 bg-chrome-raised text-chrome-ink hover:border-chrome-accent/45 ${active ? "border-chrome-accent/60" : ""}`
             : `border-line-strong bg-surface hover:border-primary/45 hover:bg-primary/5 ${active ? "border-primary/60 text-primary" : "text-ink"}`;
+    return `inline-flex h-(--size-control-sm) shrink-0 cursor-default items-center gap-1.5 border text-micro font-medium whitespace-nowrap outline-0 transition-colors duration-(--duration-instant) ${focusVisible ? "outline-2 outline-offset-2 outline-primary" : ""} ${iconOnly ? "w-(--size-control-sm) justify-center rounded-pill" : "rounded-control px-2.5"} ${tone}`;
+}
+export function Menu({ label, groups, onSelect, surface = "canvas", align = "start", icon: Trigger, 
+/** The menu as a control of a list ("filters ▾") carries the chevron; the
+ *  actions `⋯` does not, because the icon already says there is more. */
+chevron = true, active = false, iconOnly = false, variant = "button", searchPlaceholder, emptyText, width = "md", role, size = "md", title, closeOnSelect = true, }) {
+    const copy = useUiCopy();
+    const { contains } = useFilter({ sensitivity: "base" });
     const byId = indexOptions(groups.flatMap((g) => g.options));
     const menu = (_jsx(MenuList, { label: label, groups: groups, width: width, closeOnSelect: closeOnSelect, onAction: (key) => {
             const option = byId.get(String(key));
@@ -51,7 +62,14 @@ chevron = true, active = false, iconOnly = false, variant = "button", searchPlac
             onSelect?.(String(key));
         }, emptyText: emptyText ?? copy.menu.empty }));
     return (_jsxs(MenuTrigger, { children: [_jsx(AriaButton, { "aria-label": iconOnly ? label : undefined, ...(role === undefined ? {} : { "data-emphasis": role }), className: ({ isPressed, isFocusVisible }) => role === undefined
-                    ? `inline-flex h-(--size-control-sm) shrink-0 cursor-default items-center gap-1.5 border text-micro font-medium whitespace-nowrap outline-0 transition-colors duration-(--duration-instant) ${isFocusVisible ? "outline-2 outline-offset-2 outline-primary" : ""} ${iconOnly ? "w-(--size-control-sm) justify-center rounded-pill" : "rounded-control px-2.5"} ${triggerClass(isPressed)}`
+                    ? menuTriggerClasses({
+                        variant,
+                        surface,
+                        active,
+                        open: isPressed,
+                        focusVisible: isFocusVisible,
+                        iconOnly,
+                    })
                     : `${buttonClasses(role, size, surface)} gap-1.5`, children: _jsxs("span", { className: "contents", title: title ?? (iconOnly ? label : undefined), children: [Trigger === undefined ? (iconOnly ? (_jsx(ChevronDown, { className: "size-(--size-icon-sm)", strokeWidth: 2, "aria-hidden": true })) : null) : (_jsx(Trigger, { className: "size-(--size-icon-sm)", strokeWidth: 2, "aria-hidden": true })), iconOnly ? null : label, chevron && !iconOnly ? (_jsx(ChevronDown, { className: "size-(--size-icon-sm)", strokeWidth: 2, "aria-hidden": true })) : null] }) }), _jsx(Popover, { placement: align === "end" ? "bottom end" : "bottom start", className: WIDTH[width], children: searchPlaceholder === undefined ? (menu) : (
                 /* The search box stays at the top: in a menu of twenty-five entries,
                    scrolling loses exactly the control that explains why only three are

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

@@ -1 +1 @@
-export { Menu, type MenuGroup, type MenuOption } from "./Menu.js";
+export { Menu, type MenuGroup, type MenuOption, menuTriggerClasses, } from "./Menu.js";

package/dist/primitives/menu/index.js

@@ -1,2 +1,2 @@
 /* A data-driven dropdown: the actions `⋯` and "+ Create". */
-export { Menu } from "./Menu.js";
+export { Menu, menuTriggerClasses, } from "./Menu.js";

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

@@ -1,7 +1,7 @@
 import { type Pile } from "../../foundations/grouping.js";
 import type { Tone } from "../../foundations/types.js";
 import { type RowAction } from "./RowActions.js";
-import { type SortState } from "./Table.js";
+import type { SortState } from "./sorting.js";
 import { type ReactNode } from "react";
 /** How a column is aggregated when its rows are pulled together into a group.
  *
@@ -153,8 +153,10 @@ export declare function DataTable<T extends object>({ data, columns, getRowId, s
     data: readonly T[];
     columns: readonly DataColumn<T>[];
     getRowId: (row: T) => string;
-    sort?: SortState | null;
-    onSortChange?: (next: SortState | null) => void;
+    /** The order, outermost first: the second criterion decides only between rows the first
+     *  leaves equal. Empty or absent is «as they came». */
+    sort?: readonly SortState[];
+    onSortChange?: (next: SortState[]) => void;
     /**
      * Los NIVELES por los que se parte, de afuera hacia adentro. Vacío o ausente
      * es «sin agrupar».

package/dist/primitives/table/DataTable.js

@@ -8,7 +8,7 @@ import { EditRow, firstControl } from "./EditableTable.js";
 import { PileFootLine } from "./PileFootLine.js";
 import { RowActions } from "./RowActions.js";
 import { useRowWindow } from "./rowWindow.js";
-import { SelectBox, Table, Td, Th, THead, Tr, } from "./Table.js";
+import { SelectBox, Table, Td, Th, THead, Tr } from "./Table.js";
 import { aggregationFns, columnGroupingFeature, createColumnHelper, createExpandedRowModel, createGroupedRowModel, createSortedRowModel, rowAggregationFeature, rowExpandingFeature, rowSortingFeature, sortFns, tableFeatures, useTable, } from "@tanstack/react-table";
 import { ChevronRight, Plus } from "lucide-react";
 import { useEffect, useMemo, useRef, useState } from "react";
@@ -247,9 +247,7 @@ export function DataTable({ data, columns, getRowId, sort, onSortChange, levels,
         columns: defs,
         getRowId: (row) => getRowId(row),
         state: {
-            sorting: sort === null || sort === undefined
-                ? []
-                : [{ id: sort.key, desc: sort.direction === "desc" }],
+            sorting: (sort ?? []).map((one) => ({ id: one.key, desc: one.direction === "desc" })),
             /* Counted elsewhere, the tree comes made: grouping the page again would undo it. */
             grouping: piles === undefined ? (levels ?? []).map((level) => level.id) : [],
         },

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

@@ -1,5 +1,6 @@
 import { type Grouping } from "../../foundations/grouping.js";
 import { type FlagProps } from "../notice/Flag.js";
+import { type WindowedRow } from "./rowWindow.js";
 import { type ReactNode } from "react";
 /** Where a column goes when the row is drawn as a stacked card (a narrow box).
  *  `trail` sits at the top right, beside the title — a state, the row's buttons. */
@@ -46,6 +47,37 @@ export type EditBands<T> = {
      *  column does not add up. The lines are the ones under it until the next section. */
     total?: (column: EditColumn<T>, lines: readonly T[]) => ReactNode | null;
 };
+/** A warning drawn as a `Flag`: on a row (`flag`) or on one cell (`EditCellState.flag`). */
+export type EditFlag = Omit<FlagProps, "children"> & {
+    detail?: ReactNode;
+    owner?: string;
+};
+/**
+ * What ONE cell of one row is right now — said by whoever knows the record: the states the
+ * backend sends per line and field. Every key left out keeps the column as declared.
+ *
+ * Context: a column declares what it is for every row (`edit`), but an ERP line decides
+ * per row — a delivered line keeps its quantity, a service line has no lot, a discount is
+ * required only past a threshold. The table does not know why; it is told, cell by cell.
+ */
+export type EditCellState = {
+    /** Not written in on this row: the cell reads while the row is edited. */
+    readonly?: boolean;
+    /** Has to have a value: marked while the row is edited, and said to its control. */
+    required?: boolean;
+    /** Not there on this row (Odoo's per-row `invisible`): the cell is drawn empty. */
+    hidden?: boolean;
+    /** What is wrong with this value, said as what to put — under the value, with an icon,
+     *  and the control is `aria-invalid` and described by it. `null` when nothing is. */
+    error?: string | null;
+    /** A warning about THIS value — «precio bajo el costo» on the price, not on the line. */
+    flag?: EditFlag | null;
+};
+/** What a whole row is right now. A row that should not be seen is not passed at all. */
+export type EditRowState = {
+    /** Read, not written: walked with the arrows, never opened to edit. */
+    readonly?: boolean;
+};
 /** One more way to add, beside «add a line»: a section, a note. */
 export type EditAdd = {
     label: string;
@@ -97,7 +129,7 @@ export type RowKey = "ArrowDown" | "ArrowUp" | "Home" | "End";
  * of a new record in `DataTable`: one keyboard model, three shapes. Exported for that
  * family sibling only; it is not in the barrel.
  */
-export declare function EditRow({ as, rowId, rowRef, editable, editing, tabbable, className, onStart, onCommit, onCancel, onMove, onFocusRow, onTabOut, children, }: {
+export declare function EditRow({ as, rowId, rowRef, editable, editing, tabbable, className, onStart, onCommit, onCancel, onMove, onFocusRow, onTabOut, windowed, children, }: {
     as: "tr" | "li";
     rowId: string;
     rowRef: (node: HTMLElement | null) => void;
@@ -113,6 +145,9 @@ export declare function EditRow({ as, rowId, rowRef, editable, editing, tabbable
     /** `Tab` left the row by one of its edges. `true` = the table took it (opened another
      *  row, added one); `false` = the browser moves the focus as usual. */
     onTabOut: (direction: "next" | "prev") => boolean;
+    /** Past a few hundred rows the table draws only the ones in view (`rowWindow`): this row's
+     *  measure, its index, and the focus that keeps it drawn. */
+    windowed?: WindowedRow | undefined;
     children: ReactNode;
 }): import("react").JSX.Element;
 /**
@@ -135,15 +170,19 @@ totals, empty, grouping,
 /** El total de una columna DENTRO de un montón, ya formateado. Lo calcula quien
  *  compone, por el mismo motivo que `totals`: sumar significa cosas distintas
  *  según el dominio, y un porcentaje se promedia, no se suma. */
-groupTotal, height, layout, onOpen, onDiscard, bands, adds, flag, onReorder, }: {
+groupTotal, height, layout, onOpen, onDiscard, bands, adds, flag, onReorder, cellState, rowState, }: {
     rows: readonly T[];
     columns: readonly EditColumn<T>[];
+    /** The row's key on this screen, stable for as long as the row is drawn — a local key for
+     *  a row the backend has not made yet, kept after it is saved. A key that changes is a new
+     *  row to React: the row being written is unmounted and loses the focus. */
     getRowId: (row: T) => string;
     onChange?: (id: string, next: T) => void;
     onRemove?: (id: string) => void;
     /** «Add a line». Return the new row's id —or a promise of it, when the backend makes
      *  the record— and the table opens that row with the focus on its first control.
-     *  Return nothing and the row just appears, closed. */
+     *  Return nothing and the row just appears, closed. The id is the row's KEY (`getRowId`):
+     *  give a line the backend has not made a local one, and keep it after the save. */
     onAdd?: () => string | void | Promise<string | void>;
     addLabel?: string;
     totals?: readonly (ReactNode | null)[];
@@ -184,10 +223,13 @@ groupTotal, height, layout, onOpen, onDiscard, bands, adds, flag, onReorder, }:
      *  `null` for the rows with nothing to say, which should be most of them. `owner` is what
      *  the record's activity says it belongs to («Línea 3 · Impresora…»); without it, the
      *  row's first value. */
-    flag?: (row: T) => (Omit<FlagProps, "children"> & {
-        detail?: ReactNode;
-        owner?: string;
-    }) | null;
+    flag?: (row: T) => EditFlag | null;
+    /** What each cell is on each row — readonly, required, hidden, its error, its warning —
+     *  as the backend says it per line. `null` keeps the column as declared. See
+     *  `EditCellState`. */
+    cellState?: (row: T, columnId: string) => EditCellState | null;
+    /** What a whole row is: `readonly` is read, not opened. See `EditRowState`. */
+    rowState?: (row: T) => EditRowState | null;
     /** The rows have an order of their own — the lines of an order, Odoo's `sequence` — and it
      *  is changed by dragging the grip at the start of a row, or with Alt + ↑ / ↓ on it. `before`
      *  is the row it lands in front of; `null`, the end. Off while grouped (the piles decide the