@sincpro/web-ui 1.6.0 → 1.7.0

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/Table.d.ts

@@ -1,11 +1,7 @@
 import type { Tone } from "../../foundations/types.js";
 import type { WindowedRow } from "./rowWindow.js";
+import { type SortState } from "./sorting.js";
 import { type ReactNode } from "react";
-export type SortDirection = "asc" | "desc";
-export interface SortState {
-    key: string;
-    direction: SortDirection;
-}
 export declare 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. */
@@ -29,14 +25,15 @@ export declare function THead({ children, rowIndex, }: {
 }): import("react").JSX.Element;
 /** 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 declare function Th({ children, sortKey, sort, onSort, numeric, align, width, }: {
     children: ReactNode;
     sortKey?: string;
-    sort?: SortState | null;
-    onSort?: (next: SortState | null) => void;
+    /** The order of the set, outermost first. Empty is «as they came». */
+    sort?: readonly SortState[];
+    onSort?: (next: SortState[]) => void;
     /** Numbers align to the right: that is what lets you compare orders of
      *  magnitude without reading the figures. */
     numeric?: boolean;

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

@@ -5,4 +5,5 @@ 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/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;