@nanisoft/prism-ui 0.10.2 → 0.15.0

package/dist/components/ui/steps.js

@@ -0,0 +1,128 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from '../../lib/utils.js';
+/**
+ * The disc a step's mark is drawn in, one per state.
+ *
+ * The three states differ by shape before they differ by colour: a filled disc
+ * for a step that is done, an outlined one for the step the reader is on, and a
+ * filled muted one for a step ahead. That is the whole discipline behind a
+ * component that is read as feedback, and it is why the state is not a colour
+ * here either: a filled mint disc and a mint outline are the same picture
+ * narrowed to one channel, and a reader who cannot separate them is being told
+ * the same thing about two different steps.
+ */
+const MARKER = {
+    complete: 'bg-primary text-primary-foreground border-primary',
+    current: 'bg-background text-foreground border-primary',
+    upcoming: 'bg-muted text-muted-foreground border-border',
+};
+/** An index held inside the sequence, so a `current` past either end lands on a real step. */
+function clamp(value, total) {
+    if (total <= 0)
+        return 0;
+    return Math.min(Math.max(Math.trunc(value), 0), total - 1);
+}
+/**
+ * An ordered indicator of where a reader is in a sequence.
+ *
+ * **The state is derived from the index and `current`, and the derivation is the
+ * answer that cannot disagree.** A caller's `current` is one number and the
+ * states before and after it are consequences of it, so the three can never
+ * drift: move `current` and every mark moves with it, and there is no
+ * combination of `current` and `state` a caller can pass that says step one is
+ * behind them and step two is also behind them. That is not a convenience. The
+ * failure is invisible in review and visible only in use, on the screen where
+ * the reader is looking at a rail that says they have finished the thing they
+ * are doing, and there is no way for a reader to tell which of the two marks is
+ * the one to believe.
+ *
+ * **The override exists for a sequence that is not the process.** A checkout
+ * where a reviewer approved a line out of band, a migration where one stage was
+ * completed by hand last night, a form where the reader has already answered
+ * the question that step two would have asked. In those cases the position and
+ * the state are two different facts, and a derived mark would draw a claim the
+ * data contradicts. So `state` is a prop, and the cost of it is named: it is a
+ * second source of truth about a position, which is the thing this package is
+ * organised to avoid, so it is an override per step rather than a mode, and the
+ * derivation still decides every step the caller said nothing about. A caller
+ * that overrides everything has replaced the rule with their own and gained
+ * nothing but the type.
+ *
+ * **Exactly one step is current, and it is enforced rather than described.** Two
+ * steps marked current is a rail with two answers to "where am I", and no step
+ * marked current is a rail with none, which is the state a reader cannot act on
+ * at all. Both are checked against the resolved list rather than against the
+ * declaration, because the interesting case is neither of them directly: a
+ * caller who marks the step `current` points at as something else has removed
+ * the only mark that said where they were, and no declaration in the data
+ * mentions a current step at all. So the resolved states are counted and a count
+ * that is not one is a thrown diagnostic rather than a drawing. A derivation
+ * alone can never produce that count, so the diagnostic only ever fires on a
+ * caller's own declarations, which is the arrangement that keeps it a real
+ * signal rather than a nuisance.
+ *
+ * **The rule between the steps is the honest indicator, and the reason is that
+ * the alternatives restate the same fact.** A filled bar under every completed
+ * step says "this one is done" once per step, so a reader looking at a
+ * six step rail is given the same sentence six times and has to combine them
+ * themselves to learn the one thing they came for, which is how much is behind
+ * them. The connector carries that fact once and carries something the bars
+ * cannot: it measures the space between two stages, so it is the only element
+ * that shows the sequence has a length at all. It is filled up to the step the
+ * reader is on and empty after it, which is also why it is the element that
+ * makes a long sequence readable at a glance. A bar per step was rejected on
+ * that ground, and a number per step was rejected earlier, because a number is
+ * a count of where the reader is and not a measure of how far they have come.
+ *
+ * **`aria-current` goes on the current step and nowhere else, because a colour
+ * is not a position in a sequence.** It is the only attribute on the rail that
+ * states the position to a reader who cannot see the rail, and putting it
+ * anywhere else is a claim about a step that is not the one the reader is on.
+ * The three states are not announced, and that is deliberate rather than an
+ * omission: they are consequences of the position, so a reader moving by list
+ * item is already told "item two of six" and then "current", and from those two
+ * the states of the other five follow. Announcing them would mean this
+ * Component shipping the words "complete" and "upcoming" into every consumer's
+ * product, which is the same defect the copy gate holds the close button of a
+ * dialog for. The ordinal on each disc is the one thing that is hidden, and for
+ * the mirror of that reason: the list semantics already say which item this is,
+ * and a spoken number in front of every label is noise to a reader who is
+ * reading the steps rather than counting them.
+ *
+ * **It is a server Component.** No hook, no state, no effect, and the rail is
+ * arithmetic over props, so it costs a consumer nothing in client JavaScript and
+ * renders identically with scripting off, in a print stylesheet and to a crawler.
+ */
+function Steps({ steps, current, label, className }) {
+    // An empty sequence is an empty list rather than a throw. The invariant below
+    // is about a rail with a position, and a caller with no steps has no position
+    // to disagree about; the cost is an empty rail, which is what was asked for.
+    if (steps.length === 0) {
+        return _jsx("ol", { "data-slot": "steps", "aria-label": label, className: cn('flex w-full', className) });
+    }
+    const at = clamp(current, steps.length);
+    const resolved = steps.map((step, index) => step.state ?? (index < at ? 'complete' : index === at ? 'current' : 'upcoming'));
+    const placed = resolved.filter((state) => state === 'current').length;
+    if (placed !== 1) {
+        // The message reaches a developer in a console and is never rendered, which
+        // is why it is a sentence and why the copy gate exempts it. It names both
+        // halves of the failure because they have different fixes: two currents is a
+        // caller who marked two steps, and none is a caller who marked the step
+        // `current` points at as something else.
+        throw new Error(`Steps: ${placed} step(s) resolved to the current state, and exactly one must. ` +
+            'Set `current` to the index of the step the reader is on, and pass `state` only ' +
+            'on a step that was reached out of band.');
+    }
+    const last = steps.length - 1;
+    return (_jsx("ol", { "data-slot": "steps", "data-current": at, "aria-label": label, className: cn('flex w-full flex-col gap-4 sm:flex-row sm:gap-0', className), children: steps.map((step, index) => {
+            const state = resolved[index];
+            const here = index === at;
+            return (_jsxs("li", { "data-slot": "step", "data-state": state, "aria-current": here ? 'step' : undefined, className: cn('flex items-start', index === last ? 'flex-none' : 'flex-1'), children: [_jsxs("div", { "data-slot": "step-marker-row", className: "flex w-full items-center gap-2", children: [_jsx("span", { "data-slot": "step-marker", className: cn('inline-flex size-8 shrink-0 items-center justify-center rounded-full border-2 text-sm font-medium tabular-nums', MARKER[state]), children: _jsx("span", { "aria-hidden": "true", children: index + 1 }) }), index === last ? null : (_jsx("span", { "data-slot": "step-rule", "data-filled": state === 'upcoming' ? undefined : 'true', "aria-hidden": "true", className: cn('h-0.5 flex-1 rounded-full', 
+                                // Filled up to the step the reader is on and empty after it,
+                                // which is the whole indicator: one element saying how far
+                                // through they are, where a filled bar per step says "done"
+                                // once per step and leaves the arithmetic to the reader.
+                                state === 'upcoming' ? 'bg-border' : 'bg-primary') }))] }), _jsxs("div", { "data-slot": "step-text", className: "mt-2 min-w-0 sm:pr-4", children: [_jsx("p", { "data-slot": "step-label", className: cn('text-sm font-medium', state === 'upcoming' ? 'text-muted-foreground' : 'text-foreground'), children: step.label }), step.description === undefined ? null : (_jsx("p", { "data-slot": "step-description", className: "text-muted-foreground mt-0.5 text-sm", children: step.description }))] })] }, index));
+        }) }));
+}
+export { Steps };

package/dist/components/ui/switch.d.ts

@@ -36,6 +36,14 @@ export interface SwitchProps extends Omit<ComponentProps<'span'>, 'onChange'> {
  * step: enabling notifications, turning a feature on. The control renders a
  * hidden native input, so it submits with a form, and Space toggles it while
  * focused. When the change needs an explicit save, use a Checkbox instead.
+ *
+ * **A coarse pointer gets the 44px floor as a band, and the pill is untouched.** The
+ * pill is 20 by 36 and the only control in this package whose shape does not suit a
+ * step: `h-11 w-11` would be a 44px switch, which is a switch nobody draws, and
+ * growing only the width would move the thumb's `translate-x-4` travel with the box.
+ * A band reaches the same 44px around the pill as drawn, and a switch sits alone in a
+ * settings row with empty space above and below it, so the fourteen pixels the band
+ * adds in each direction land on nothing a reader was aiming at.
  */
 declare function Switch({ className, ...props }: SwitchProps): import("react").JSX.Element;
 export { Switch };

package/dist/components/ui/switch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"switch.d.ts","sourceRoot":"","sources":["../../../src/components/ui/switch.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC3E,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mCAAmC;IACnC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,8DAA8D;IAC9D,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4CAA4C;IAC5C,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CAC7C;AAED;;;;;;;GAOG;AACH,iBAAS,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,WAAW,+BAyBnD;AAED,OAAO,EAAE,MAAM,EAAE,CAAA"}
+{"version":3,"file":"switch.d.ts","sourceRoot":"","sources":["../../../src/components/ui/switch.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC3E,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mCAAmC;IACnC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,8DAA8D;IAC9D,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4CAA4C;IAC5C,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CAC7C;AAED;;;;;;;;;;;;;;;GAeG;AACH,iBAAS,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,WAAW,+BA4BnD;AAED,OAAO,EAAE,MAAM,EAAE,CAAA"}

package/dist/components/ui/switch.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Switch as SwitchPrimitive } from '@base-ui/react/switch';
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
 /**
  * A binary control that takes effect immediately.
  *
@@ -9,8 +9,19 @@ import { cn } from '../../lib/utils';
  * step: enabling notifications, turning a feature on. The control renders a
  * hidden native input, so it submits with a form, and Space toggles it while
  * focused. When the change needs an explicit save, use a Checkbox instead.
+ *
+ * **A coarse pointer gets the 44px floor as a band, and the pill is untouched.** The
+ * pill is 20 by 36 and the only control in this package whose shape does not suit a
+ * step: `h-11 w-11` would be a 44px switch, which is a switch nobody draws, and
+ * growing only the width would move the thumb's `translate-x-4` travel with the box.
+ * A band reaches the same 44px around the pill as drawn, and a switch sits alone in a
+ * settings row with empty space above and below it, so the fourteen pixels the band
+ * adds in each direction land on nothing a reader was aiming at.
  */
 function Switch({ className, ...props }) {
-    return (_jsx(SwitchPrimitive.Root, { "data-slot": "switch", className: cn('border-transparent bg-input shadow-xs inline-flex h-5 w-9 shrink-0 items-center rounded-full border p-0.5 outline-none', 'transition-[color,box-shadow,background-color] duration-fast ease-out', 'data-[checked]:bg-primary data-[unchecked]:bg-input', 'focus-visible:border-ring focus-visible:ring-ring focus-visible:ring-[3px]', 'aria-invalid:border-destructive aria-invalid:ring-destructive/20', 'disabled:cursor-not-allowed disabled:opacity-50', className), ...props, children: _jsx(SwitchPrimitive.Thumb, { "data-slot": "switch-thumb", className: cn('bg-background pointer-events-none block size-4 rounded-full shadow-xs', 'transition-transform duration-base ease-out', 'data-[checked]:translate-x-4 data-[unchecked]:translate-x-0') }) }));
+    return (_jsx(SwitchPrimitive.Root, { "data-slot": "switch", className: cn('border-transparent bg-input shadow-xs relative inline-flex h-5 w-9 shrink-0 items-center rounded-full border p-0.5 outline-none', 'transition-[color,box-shadow,background-color] duration-fast ease-out', 'data-[checked]:bg-primary data-[unchecked]:bg-input', 'focus-visible:border-ring focus-visible:ring-ring focus-visible:ring-[3px]', 'aria-invalid:border-destructive aria-invalid:ring-destructive/20', 'disabled:cursor-not-allowed disabled:opacity-50', 
+        // `relative` is here only to give the band a containing block. The pill has no
+        // positioned ancestor and none of its own offsets, so this moves nothing.
+        'pointer-coarse:before:absolute pointer-coarse:before:left-1/2 pointer-coarse:before:top-1/2 pointer-coarse:before:h-11 pointer-coarse:before:w-11 pointer-coarse:before:-translate-x-1/2 pointer-coarse:before:-translate-y-1/2 pointer-coarse:before:content-[""]', className), ...props, children: _jsx(SwitchPrimitive.Thumb, { "data-slot": "switch-thumb", className: cn('bg-background pointer-events-none block size-4 rounded-full shadow-xs', 'transition-transform duration-base ease-out', 'data-[checked]:translate-x-4 data-[unchecked]:translate-x-0') }) }));
 }
 export { Switch };

package/dist/components/ui/table-sort.d.ts

@@ -0,0 +1,97 @@
+import { type ComponentProps, type ReactNode } from 'react';
+/** Which way a column is sorted, and `none` for a column that is not. */
+export type TableSortDirection = 'none' | 'ascending' | 'descending';
+/** What activating a header will do, given where the column is now. */
+export type TableSortAnnouncement = (direction: TableSortDirection) => string;
+/** The props the TableSort accepts. */
+export interface TableSortProps extends Omit<ComponentProps<'th'>, 'children'> {
+    /**
+     * The column's name, and the visible text of the header.
+     *
+     * It is a `th` with `scope="col"` rather than a `button` dressed as a header,
+     * because the header is what a screen reader announces while a reader is moving
+     * across the table, and a header that is not a header is a row of buttons above a
+     * grid with no column names in it.
+     */
+    children?: ReactNode;
+    /** The column this header sorts. */
+    column: string;
+    /** The direction the column is currently sorted in. @defaultValue 'none' */
+    direction?: TableSortDirection;
+    /**
+     * Called with the direction the column will be in after this activation.
+     *
+     * The caller owns the sort and the rows, because a Component cannot sort an
+     * arbitrary set of records: it does not know what the column means, whether it
+     * is a number or a date or a name, or what the original order was. So the
+     * header reports the direction and the caller's table reorders.
+     */
+    onDirectionChange?: (direction: TableSortDirection) => void;
+    /**
+     * The words read for what activating the header will do.
+     *
+     * Required, and required as a **function of the next direction** rather than as
+     * a string, because the announcement has to say what *will* happen, not what is.
+     * A header that announces "sorted ascending" when it is already ascending tells
+     * a reader nothing about the press they are about to make, and one that
+     * announces "sort" says nothing about which way. The words are the caller's for
+     * the reason every other reader-facing string in this package is: a shared
+     * library cannot know whether the word for this is "sort", "trier" or
+     * "sortieren", and a sentence it chose would be inherited by every consumer in
+     * a language they did not write.
+     */
+    announce: TableSortAnnouncement;
+    /** Whether this header ignores user interaction. */
+    disabled?: boolean;
+    /** Layout only. */
+    className?: string;
+}
+/**
+ * The sortable header affordance for a `Table`.
+ *
+ * **`aria-sort` belongs on the `th`, and this is a `th`.** Not a `button` inside a
+ * `th`, and not a `th` with a `role="button"` on it. A column header is what a
+ * screen reader announces while a reader is moving across a table, and the sort
+ * state is a property of that header rather than of a control inside it, so
+ * `aria-sort` sits on the cell where the reader is told about it. It is set on
+ * exactly one header at a time, which is the rule: two columns both reporting
+ * `aria-sort` is a table claiming to be ordered two ways at once, and a reader
+ * comparing the two hears a contradiction.
+ *
+ * **The announcement says what will happen, not what is.** That is the decision
+ * this Component is built around, and it is why `announce` is a function of the
+ * next direction rather than a string. A reader who is about to press a header
+ * needs to know what the press will do, and the honest way to say it depends on
+ * the column's current state: on an unsorted column the press sorts ascending, on
+ * an ascending one it reverses, on a descending one it returns the original
+ * order. One string cannot be right for all three, and a string chosen for one of
+ * them is wrong for the other two in a way the reader cannot detect.
+ *
+ * **Two clicks to descending, three back to unsorted, and the third is the point.**
+ * The cycle is `none`, `ascending`, `descending`, and back to `none`, and the last
+ * step is a decision rather than an omission. A reader who has sorted to find the
+ * largest value and no longer cares has to be able to get the original order back
+ * from the control they already know, because any other route is a second
+ * affordance this package would then have to document. The announcement prop
+ * exists so a caller can say what that third press does in their own words, which
+ * is the one sentence in the whole interaction Prism cannot write for them.
+ *
+ * **The sort is the caller's.** A Component cannot sort an arbitrary set of
+ * records: it does not know whether the column is a number, a date or a name, it
+ * does not know the locale a name sorts in, and it does not know the original
+ * order it would have to restore. So this header owns the state it displays and
+ * reports the direction, and the caller's table reorders the rows.
+ *
+ * **The mark is a shape as well as a colour.** An unsorted column carries the
+ * two-headed mark, an ascending one an up arrow and a descending one a down
+ * arrow, and the mark is `aria-hidden` because the state is already on the cell in
+ * `aria-sort` and a reader is not told twice. A reader who cannot separate the
+ * three marks still gets the state from the attribute, which is the same order the
+ * whole package keeps: the attribute is the fact and the drawing is the reminder.
+ *
+ * It is a client Component, because a header that reports a direction and holds
+ * the announcement is holding state and attaching a handler.
+ */
+declare function TableSort({ children, column, direction, onDirectionChange, announce, disabled, className, ...props }: TableSortProps): import("react").JSX.Element;
+export { TableSort };
+//# sourceMappingURL=table-sort.d.ts.map

package/dist/components/ui/table-sort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-sort.d.ts","sourceRoot":"","sources":["../../../src/components/ui/table-sort.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAmB,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAI5E,yEAAyE;AACzE,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,WAAW,GAAG,YAAY,CAAA;AAEpE,uEAAuE;AACvE,MAAM,MAAM,qBAAqB,GAAG,CAAC,SAAS,EAAE,kBAAkB,KAAK,MAAM,CAAA;AAE7E,uCAAuC;AACvC,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAC5E;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAA;IACd,4EAA4E;IAC5E,SAAS,CAAC,EAAE,kBAAkB,CAAA;IAC9B;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,kBAAkB,KAAK,IAAI,CAAA;IAC3D;;;;;;;;;;;;OAYG;IACH,QAAQ,EAAE,qBAAqB,CAAA;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,iBAAS,SAAS,CAAC,EACjB,QAAQ,EACR,MAAM,EACN,SAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,QAAgB,EAChB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,cAAc,+BAmFhB;AAED,OAAO,EAAE,SAAS,EAAE,CAAA"}

package/dist/components/ui/table-sort.js

@@ -0,0 +1,102 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ArrowDownIcon, ArrowUpIcon, ChevronsUpDownIcon } from 'lucide-react';
+import { useId, useState } from 'react';
+import { cn } from '../../lib/utils.js';
+/** The direction a click on a header in `from` produces. */
+function nextDirection(from) {
+    // Unsorted, then ascending, then descending, then unsorted again.
+    //
+    // Returning to `none` is the decision worth making, and it is why the cycle has
+    // three states rather than two. A reader who has sorted a column to find the
+    // extreme and no longer cares has to get the original order back, and the only
+    // route to it is a third click on the header they already know. A two-state
+    // control makes that order unreachable from the control, which means the caller
+    // has to invent a second affordance for it, and a second affordance is a second
+    // thing a reader has to find. So the cycle closes.
+    if (from === 'none')
+        return 'ascending';
+    if (from === 'ascending')
+        return 'descending';
+    return 'none';
+}
+/** The mark each state draws, which is a shape and not only a colour. */
+const MARK = {
+    // The unsorted mark is the two-headed one, because it says "this column can be
+    // ordered either way" rather than "this column is ordered". A single upward
+    // arrow on an unsorted column claims an order that is not in force.
+    none: _jsx(ChevronsUpDownIcon, { className: "size-3.5" }),
+    ascending: _jsx(ArrowUpIcon, { className: "size-3.5" }),
+    descending: _jsx(ArrowDownIcon, { className: "size-3.5" }),
+};
+/**
+ * The sortable header affordance for a `Table`.
+ *
+ * **`aria-sort` belongs on the `th`, and this is a `th`.** Not a `button` inside a
+ * `th`, and not a `th` with a `role="button"` on it. A column header is what a
+ * screen reader announces while a reader is moving across a table, and the sort
+ * state is a property of that header rather than of a control inside it, so
+ * `aria-sort` sits on the cell where the reader is told about it. It is set on
+ * exactly one header at a time, which is the rule: two columns both reporting
+ * `aria-sort` is a table claiming to be ordered two ways at once, and a reader
+ * comparing the two hears a contradiction.
+ *
+ * **The announcement says what will happen, not what is.** That is the decision
+ * this Component is built around, and it is why `announce` is a function of the
+ * next direction rather than a string. A reader who is about to press a header
+ * needs to know what the press will do, and the honest way to say it depends on
+ * the column's current state: on an unsorted column the press sorts ascending, on
+ * an ascending one it reverses, on a descending one it returns the original
+ * order. One string cannot be right for all three, and a string chosen for one of
+ * them is wrong for the other two in a way the reader cannot detect.
+ *
+ * **Two clicks to descending, three back to unsorted, and the third is the point.**
+ * The cycle is `none`, `ascending`, `descending`, and back to `none`, and the last
+ * step is a decision rather than an omission. A reader who has sorted to find the
+ * largest value and no longer cares has to be able to get the original order back
+ * from the control they already know, because any other route is a second
+ * affordance this package would then have to document. The announcement prop
+ * exists so a caller can say what that third press does in their own words, which
+ * is the one sentence in the whole interaction Prism cannot write for them.
+ *
+ * **The sort is the caller's.** A Component cannot sort an arbitrary set of
+ * records: it does not know whether the column is a number, a date or a name, it
+ * does not know the locale a name sorts in, and it does not know the original
+ * order it would have to restore. So this header owns the state it displays and
+ * reports the direction, and the caller's table reorders the rows.
+ *
+ * **The mark is a shape as well as a colour.** An unsorted column carries the
+ * two-headed mark, an ascending one an up arrow and a descending one a down
+ * arrow, and the mark is `aria-hidden` because the state is already on the cell in
+ * `aria-sort` and a reader is not told twice. A reader who cannot separate the
+ * three marks still gets the state from the attribute, which is the same order the
+ * whole package keeps: the attribute is the fact and the drawing is the reminder.
+ *
+ * It is a client Component, because a header that reports a direction and holds
+ * the announcement is holding state and attaching a handler.
+ */
+function TableSort({ children, column, direction = 'none', onDirectionChange, announce, disabled = false, className, ...props }) {
+    // Uncontrolled use is a state the header keeps for itself, so a caller who wants
+    // to read the sort back has a `direction` to pass. The two together are the
+    // usual React shape, and the state is a convenience rather than the contract:
+    // `onDirectionChange` is the contract.
+    const [uncontrolled, setUncontrolled] = useState('none');
+    const active = direction === 'none' && onDirectionChange === undefined ? uncontrolled : direction;
+    const next = nextDirection(active);
+    // The id that ties the announcement to the button. Generated rather than
+    // derived from the column, because two tables on a page may sort the same column
+    // and an id built from its name would collide, leaving both headers describing
+    // each other.
+    const descriptionId = useId();
+    return (_jsxs("th", { "data-slot": "table-sort", "data-column": column, "data-direction": active, scope: "col", "aria-sort": active === 'none' ? undefined : active, className: cn('p-0', className), ...props, children: [_jsx("span", { id: descriptionId, "data-slot": "table-sort-announcement", className: "sr-only", children: announce(next) }), _jsxs("button", { type: "button", "data-slot": "table-sort-button", "aria-describedby": descriptionId, disabled: disabled, onClick: () => {
+                    if (onDirectionChange === undefined)
+                        setUncontrolled(next);
+                    onDirectionChange?.(next);
+                }, className: cn('text-muted-foreground hover:text-foreground flex h-10 w-full items-center gap-1.5 px-2 text-left align-middle text-sm font-medium whitespace-nowrap outline-none', 'transition-colors duration-fast ease-out', 'focus-visible:ring-ring focus-visible:ring-[3px]', 'disabled:pointer-events-none disabled:opacity-50', 
+                // The sorted column says so in the foreground ink rather than the muted
+                // one, which is a second channel on top of the arrow and the attribute:
+                // a reader who can see neither the arrow nor the attribute still sees
+                // which column is ordered.
+                active === 'none' ? '' : 'text-foreground'), children: [_jsx("span", { "data-slot": "table-sort-label", className: "truncate", children: children }), _jsx("span", { "data-slot": "table-sort-mark", "aria-hidden": "true", className: "ml-auto inline-flex shrink-0 items-center", children: MARK[active] })] })] }));
+}
+export { TableSort };

package/dist/components/ui/table.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
 /**
  * The semantic table components for tabular data.
  *

package/dist/components/ui/tabs.d.ts

@@ -56,9 +56,28 @@ export interface TabsContentProps extends Omit<ComponentProps<'div'>, 'value'> {
  * process.
  */
 declare function Tabs({ className, ...props }: TabsProps): import("react").JSX.Element;
-/** The row or column of tab triggers. */
+/**
+ * The row or column of tab triggers.
+ *
+ * `pointer-coarse:h-13` is half of the coarse-pointer floor and it is the half that is
+ * easy to forget: the list is `h-9 p-1`, so its content box is 28 tall and a trigger
+ * grown to 44 would not fit inside it. `h-13` is 52, which is the trigger's 44 plus
+ * the list's own `p-1` on each side. The vertical orientation is exempt, because there
+ * the list is `h-fit flex-col` and each trigger sizes the row it is in. A band was
+ * rejected on condition 1 for the sharpest possible reason: the triggers sit a `gap-1`
+ * apart inside one list, so a band on one is a press aimed at its neighbour. See
+ * DESIGN.md, The coarse-pointer floor.
+ */
 declare function TabsList({ className, ...props }: TabsListProps): import("react").JSX.Element;
-/** One trigger in the tab list. */
+/**
+ * One trigger in the tab list.
+ *
+ * `pointer-coarse:h-11` is the other half of the floor. The trigger states its height
+ * through `py-1` and its content, so this states it outright rather than growing the
+ * padding to an implied 44: twelve pixels of padding either side of a twenty pixel
+ * line box is the floor reached by arithmetic, and an arithmetic floor is a number a
+ * later edit can change without noticing. See The coarse-pointer floor.
+ */
 declare function TabsTrigger({ className, ...props }: TabsTriggerProps): import("react").JSX.Element;
 /** The panel a trigger reveals. */
 declare function TabsContent({ className, ...props }: TabsContentProps): import("react").JSX.Element;

package/dist/components/ui/tabs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tabs.d.ts","sourceRoot":"","sources":["../../../src/components/ui/tabs.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,SAAU,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IACxE,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,iEAAiE;IACjE,WAAW,CAAC,EAAE,YAAY,GAAG,UAAU,CAAA;CACxC;AAED,8CAA8C;AAC9C,MAAM,WAAW,aAAc,SAAQ,cAAc,CAAC,KAAK,CAAC;IAC1D,0EAA0E;IAC1E,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC/E,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAA;IACb,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAC5E,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAA;IACb,2EAA2E;IAC3E,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED;;;;;;;;GAQG;AACH,iBAAS,IAAI,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,SAAS,+BAQ/C;AAED,yCAAyC;AACzC,iBAAS,QAAQ,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,aAAa,+BAYvD;AAED,mCAAmC;AACnC,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,gBAAgB,+BAgB7D;AAED,mCAAmC;AACnC,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,gBAAgB,+BAQ7D;AAED,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,CAAA"}
+{"version":3,"file":"tabs.d.ts","sourceRoot":"","sources":["../../../src/components/ui/tabs.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,SAAU,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IACxE,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,iEAAiE;IACjE,WAAW,CAAC,EAAE,YAAY,GAAG,UAAU,CAAA;CACxC;AAED,8CAA8C;AAC9C,MAAM,WAAW,aAAc,SAAQ,cAAc,CAAC,KAAK,CAAC;IAC1D,0EAA0E;IAC1E,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC/E,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAA;IACb,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAC5E,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAA;IACb,2EAA2E;IAC3E,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED;;;;;;;;GAQG;AACH,iBAAS,IAAI,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,SAAS,+BAQ/C;AAED;;;;;;;;;;;GAWG;AACH,iBAAS,QAAQ,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,aAAa,+BAavD;AAED;;;;;;;;GAQG;AACH,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,gBAAgB,+BAiB7D;AAED,mCAAmC;AACnC,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,gBAAgB,+BAQ7D;AAED,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,CAAA"}

package/dist/components/ui/tabs.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Tabs as TabsPrimitive } from '@base-ui/react/tabs';
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
 /**
  * A set of layered panels shown one at a time.
  *
@@ -14,13 +14,32 @@ import { cn } from '../../lib/utils';
 function Tabs({ className, ...props }) {
     return (_jsx(TabsPrimitive.Root, { "data-slot": "tabs", className: cn('flex flex-col gap-2', className), ...props }));
 }
-/** The row or column of tab triggers. */
+/**
+ * The row or column of tab triggers.
+ *
+ * `pointer-coarse:h-13` is half of the coarse-pointer floor and it is the half that is
+ * easy to forget: the list is `h-9 p-1`, so its content box is 28 tall and a trigger
+ * grown to 44 would not fit inside it. `h-13` is 52, which is the trigger's 44 plus
+ * the list's own `p-1` on each side. The vertical orientation is exempt, because there
+ * the list is `h-fit flex-col` and each trigger sizes the row it is in. A band was
+ * rejected on condition 1 for the sharpest possible reason: the triggers sit a `gap-1`
+ * apart inside one list, so a band on one is a press aimed at its neighbour. See
+ * DESIGN.md, The coarse-pointer floor.
+ */
 function TabsList({ className, ...props }) {
-    return (_jsx(TabsPrimitive.List, { "data-slot": "tabs-list", className: cn('bg-muted text-muted-foreground inline-flex h-9 w-fit items-center justify-center gap-1 rounded-lg p-1', 'data-[orientation=vertical]:h-fit data-[orientation=vertical]:flex-col', className), ...props }));
+    return (_jsx(TabsPrimitive.List, { "data-slot": "tabs-list", className: cn('bg-muted text-muted-foreground inline-flex h-9 w-fit items-center justify-center gap-1 rounded-lg p-1', 'data-[orientation=vertical]:h-fit data-[orientation=vertical]:flex-col', 'pointer-coarse:h-13', className), ...props }));
 }
-/** One trigger in the tab list. */
+/**
+ * One trigger in the tab list.
+ *
+ * `pointer-coarse:h-11` is the other half of the floor. The trigger states its height
+ * through `py-1` and its content, so this states it outright rather than growing the
+ * padding to an implied 44: twelve pixels of padding either side of a twenty pixel
+ * line box is the floor reached by arithmetic, and an arithmetic floor is a number a
+ * later edit can change without noticing. See The coarse-pointer floor.
+ */
 function TabsTrigger({ className, ...props }) {
-    return (_jsx(TabsPrimitive.Tab, { "data-slot": "tabs-trigger", className: cn('text-foreground inline-flex flex-1 items-center justify-center gap-1.5 rounded-md px-3 py-1 text-sm font-medium whitespace-nowrap outline-none', 'transition-[color,box-shadow,background-color] duration-fast ease-out', 'focus-visible:border-ring focus-visible:ring-ring focus-visible:ring-[3px]', 'data-[active]:bg-background data-[active]:shadow-xs', 'data-[disabled]:pointer-events-none data-[disabled]:opacity-50', "[&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 [&_svg]:shrink-0", className), ...props }));
+    return (_jsx(TabsPrimitive.Tab, { "data-slot": "tabs-trigger", className: cn('text-foreground inline-flex flex-1 items-center justify-center gap-1.5 rounded-md px-3 py-1 text-sm font-medium whitespace-nowrap outline-none', 'transition-[color,box-shadow,background-color] duration-fast ease-out', 'focus-visible:border-ring focus-visible:ring-ring focus-visible:ring-[3px]', 'data-[active]:bg-background data-[active]:shadow-xs', 'data-[disabled]:pointer-events-none data-[disabled]:opacity-50', "[&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 [&_svg]:shrink-0", 'pointer-coarse:h-11', className), ...props }));
 }
 /** The panel a trigger reveals. */
 function TabsContent({ className, ...props }) {