@nanisoft/prism-ui 0.13.0 → 0.16.0

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

@@ -0,0 +1,188 @@
+/**
+ * One panel on the inner axis of a section, and the panel it holds.
+ *
+ * The axis is nested rather than parallel because the inner axis belongs to the
+ * section it sits in: a reader who has chosen a section and then an inner panel is
+ * in one place, and the two are announced as two axes inside it rather than as two
+ * sets of tabs on a page.
+ */
+export type NestedTabPanel = {
+    /** The panel's stable key. */
+    value: string;
+    /** The tab's visible name. */
+    label: React.ReactNode;
+    /** The panel's own content. */
+    content?: React.ReactNode;
+};
+/**
+ * One section on the outer axis, and the inner axis inside it.
+ *
+ * `panels` is required and may be empty, because a section with no inner axis is a
+ * real shape: it is a page-level switch between subjects where one of them has
+ * nothing to subdivide, and a type that required an inner axis would force that
+ * caller to invent one. An empty `panels` draws the section as a plain panel and no
+ * inner tab list at all, which is the honest drawing rather than an empty strip of
+ * tabs.
+ */
+export type NestedTabSection = {
+    /** The section's stable key. */
+    value: string;
+    /** The tab's visible name. */
+    label: React.ReactNode;
+    /** One line under the section's name, for a reader who has arrived at it. */
+    description?: React.ReactNode;
+    /** The inner axis, in the order a reader should meet it. */
+    panels?: readonly NestedTabPanel[];
+    /**
+     * The inner panel shown when the reader first arrives at this section.
+     *
+     * Optional and defaulted to the first panel rather than required, because the
+     * ordinary case is the first panel and a caller who has to write it is a caller
+     * writing the same value twice. The cost of the default is that a caller who
+     * reorders `panels` has changed what a reader sees on arrival, which is the same
+     * property `Tabs` has and is not this Component's to fix.
+     */
+    defaultPanel?: string;
+};
+/**
+ * The props a NestedTabs accepts.
+ *
+ * Two axes, two controlled values and two callbacks, and no state of its own beyond
+ * what it has to hold to make the two agree. The reason there is no combined value
+ * is that the two axes change for different reasons and at different times: a reader
+ * who changes the inner panel has not chosen a different section, and a Component
+ * that reported the pair as one thing would call that a section change and reset a
+ * rail for a reader who only moved a tab.
+ */
+export interface NestedTabsProps {
+    /**
+     * The sections, in the order a reader should meet them.
+     *
+     * Required, and the order is a claim rather than a layout: these are peer views of
+     * one subject, which is what makes them tabs and not steps. A caller with a
+     * *sequence* here wants `Tabs` for a single axis and `FormWizard` for the other,
+     * and a nested tab list whose sections must be visited in order is a wizard with
+     * the gating left out.
+     */
+    sections: readonly NestedTabSection[];
+    /**
+     * The section being shown.
+     *
+     * Controlled and required rather than defaulted, for the reason every axis in this
+     * package is: the caller owns where the reader is, because the caller's own
+     * navigation, its address and its analytics all need to know, and a Component that
+     * kept its own copy would be a second source of truth about a position.
+     */
+    value: string;
+    /** Called when the reader moves to another section. */
+    onValueChange: (value: string) => void;
+    /**
+     * The inner panel being shown, within the current section.
+     *
+     * Controlled and required on the same terms as `value`, and required even though a
+     * section may have no panels because the answer has to be about the section the
+     * reader is in rather than about the page: a single `panel` prop that the
+     * Component reset whenever the section changed would silently discard a reader's
+     * choice of inner panel every time they came back to a section, and a control that
+     * forgets is worse than one that never offered the choice. Pass the current
+     * section's `defaultPanel` when the caller has none.
+     */
+    panel: string;
+    /** Called when the reader moves to another inner panel. */
+    onPanelChange: (value: string) => void;
+    /**
+     * The accessible name of the outer axis.
+     *
+     * Required, and the subject's noun rather than this Component's: a page with two
+     * nested tab sets is a page where a reader cannot tell which one they are in, and
+     * a tab list with no name is announced as "tab list" and nothing else.
+     */
+    label: string;
+    /**
+     * The accessible name of the inner axis.
+     *
+     * Required, and required even where a section has no panels, because the name is
+     * the difference between a reader being told "General, tab 1 of 3" and being told
+     * "tab 1 of 3". The word is the caller's, and it is usually the section's own noun
+     * followed by what the axis divides: "Deployment, files".
+     */
+    panelLabel: string;
+    /**
+     * The words shown where a section's inner axis would be, for a section that has
+     * no panels.
+     *
+     * Optional rather than required, because a section with no inner axis draws its own
+     * content and a section that needs a line saying so passes one; the omission is
+     * not a gap, it is the section having nothing to say.
+     */
+    fallback?: React.ReactNode;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+}
+/**
+ * Two tab axes, one inside the other, with a roving tab stop each.
+ *
+ * **The whole cost of this Component is two tab stops that look like one.** Both
+ * axes draw `TabsList`, both are a single Tab stop, both respond to the arrow keys,
+ * and they sit on the same screen a few centimetres apart. A reader who tabs onto
+ * the outer axis, presses the down arrow and lands in what looks like the same kind
+ * of control has to work out from the announcement which axis they are on, and there
+ * is no visual cue that tells them: two identically drawn tab lists are two
+ * identically drawn tab lists. So both axes are named, and the names are the whole
+ * mitigation. That is an honest cost rather than a solved problem, and a caller who
+ * finds it confusing in a particular page is being told the truth about their page,
+ * not about this Component.
+ *
+ * **The inner axis moves; the outer axis does not. That is the rule everything else
+ * follows from.** Changing the inner panel is a reader refining what they are
+ * looking at within a subject they have already chosen, so the outer value is
+ * untouched: no callback fires, no rail moves, and a reader who is on "Deployment,
+ * files" and switches to "logs" is still on Deployment. The alternative, where the
+ * outer axis follows the inner one, is what a naive composition of two `Tabs` roots
+ * produces when a caller puts the inner list outside the outer panel, and it is
+ * wrong in a way a reader cannot correct: the section they are in changes under
+ * them, so the panel they chose is no longer the panel they are reading.
+ *
+ * **Coming back to a section restores the panel they were on, and that is why
+ * `panel` is a single controlled value rather than one per section.** A Component
+ * that remembered a panel per section would need a record keyed by section, which is
+ * a second piece of state the caller cannot see and cannot put in an address. Here
+ * the caller holds one `panel` value and it survives a trip to another section and
+ * back, because nothing in this module resets it. The cost is real and stated: if
+ * the caller changes `panel` while the reader is on a different section, the value
+ * belongs to the section they are on and not the one they left, so a caller driving
+ * both axes from one store has to keep them in step. That is one value they already
+ * hold, not a new one.
+ *
+ * **A section with no panels draws no inner axis at all.** An empty tab list is a
+ * row of nothing that a reader tabs onto and cannot move within, and a section whose
+ * content does not subdivide should look like a section that does not subdivide.
+ * `panels` is therefore optional and an empty array is a real shape, which is the
+ * reason this is not a type that requires at least one panel: a caller with one
+ * subject that happens to have no sub-views would otherwise invent a panel to
+ * satisfy it.
+ *
+ * **`Tabs` is composed twice and redrawn nowhere.** Both axes are the same
+ * Component with the same keyboard model, the same roving tab stop and the same
+ * announcement behaviour, and a second implementation of a tab axis inside this
+ * module would be a third place for the same rule to disagree in. The composition is
+ * the outer `Tabs` with the inner one inside its panel, so the inner axis inherits
+ * the outer one's DOM position and the two nest the way the reader's understanding
+ * nests.
+ *
+ * **The two axes are announced as two axes, which is the accessibility half of the
+ * cost above.** `label` names the outer list and `panelLabel` names the inner one,
+ * both through `aria-label` on each `TabsList`, so the reader is told which axis
+ * every arrow key and every Tab is currently about. That is the mitigation and it is
+ * a mitigation rather than a fix: two names in sequence do not make two identical
+ * shapes distinguishable at a glance for a reader scanning rather than listening.
+ *
+ * **It is a client Component**, because both axes move after the reader acts, and
+ * because every one of its value props is a function the caller hands it, which is a
+ * client-to-client boundary wherever it is written. What that costs is the price of
+ * every client control: a server Component may render one section with its panel
+ * already chosen, and what it may not do is let the reader move on either axis.
+ */
+declare function NestedTabs({ sections, value, onValueChange, panel, onPanelChange, label, panelLabel, fallback, className, }: NestedTabsProps): import("react").JSX.Element;
+export { NestedTabs };
+//# sourceMappingURL=nested-tabs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nested-tabs.d.ts","sourceRoot":"","sources":["../../../src/components/ui/nested-tabs.tsx"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,8BAA8B;IAC9B,KAAK,EAAE,KAAK,CAAC,SAAS,CAAA;IACtB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,8BAA8B;IAC9B,KAAK,EAAE,KAAK,CAAC,SAAS,CAAA;IACtB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC7B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,SAAS,cAAc,EAAE,CAAA;IAClC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;OAQG;IACH,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAA;IACrC;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACtC;;;;;;;;;;OAUG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,2DAA2D;IAC3D,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACtC;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,iBAAS,UAAU,CAAC,EAClB,QAAQ,EACR,KAAK,EACL,aAAa,EACb,KAAK,EACL,aAAa,EACb,KAAK,EACL,UAAU,EACV,QAAQ,EACR,SAAS,GACV,EAAE,eAAe,+BAsEjB;AAED,OAAO,EAAE,UAAU,EAAE,CAAA"}

package/dist/components/ui/nested-tabs.js

@@ -0,0 +1,75 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from './tabs.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * Two tab axes, one inside the other, with a roving tab stop each.
+ *
+ * **The whole cost of this Component is two tab stops that look like one.** Both
+ * axes draw `TabsList`, both are a single Tab stop, both respond to the arrow keys,
+ * and they sit on the same screen a few centimetres apart. A reader who tabs onto
+ * the outer axis, presses the down arrow and lands in what looks like the same kind
+ * of control has to work out from the announcement which axis they are on, and there
+ * is no visual cue that tells them: two identically drawn tab lists are two
+ * identically drawn tab lists. So both axes are named, and the names are the whole
+ * mitigation. That is an honest cost rather than a solved problem, and a caller who
+ * finds it confusing in a particular page is being told the truth about their page,
+ * not about this Component.
+ *
+ * **The inner axis moves; the outer axis does not. That is the rule everything else
+ * follows from.** Changing the inner panel is a reader refining what they are
+ * looking at within a subject they have already chosen, so the outer value is
+ * untouched: no callback fires, no rail moves, and a reader who is on "Deployment,
+ * files" and switches to "logs" is still on Deployment. The alternative, where the
+ * outer axis follows the inner one, is what a naive composition of two `Tabs` roots
+ * produces when a caller puts the inner list outside the outer panel, and it is
+ * wrong in a way a reader cannot correct: the section they are in changes under
+ * them, so the panel they chose is no longer the panel they are reading.
+ *
+ * **Coming back to a section restores the panel they were on, and that is why
+ * `panel` is a single controlled value rather than one per section.** A Component
+ * that remembered a panel per section would need a record keyed by section, which is
+ * a second piece of state the caller cannot see and cannot put in an address. Here
+ * the caller holds one `panel` value and it survives a trip to another section and
+ * back, because nothing in this module resets it. The cost is real and stated: if
+ * the caller changes `panel` while the reader is on a different section, the value
+ * belongs to the section they are on and not the one they left, so a caller driving
+ * both axes from one store has to keep them in step. That is one value they already
+ * hold, not a new one.
+ *
+ * **A section with no panels draws no inner axis at all.** An empty tab list is a
+ * row of nothing that a reader tabs onto and cannot move within, and a section whose
+ * content does not subdivide should look like a section that does not subdivide.
+ * `panels` is therefore optional and an empty array is a real shape, which is the
+ * reason this is not a type that requires at least one panel: a caller with one
+ * subject that happens to have no sub-views would otherwise invent a panel to
+ * satisfy it.
+ *
+ * **`Tabs` is composed twice and redrawn nowhere.** Both axes are the same
+ * Component with the same keyboard model, the same roving tab stop and the same
+ * announcement behaviour, and a second implementation of a tab axis inside this
+ * module would be a third place for the same rule to disagree in. The composition is
+ * the outer `Tabs` with the inner one inside its panel, so the inner axis inherits
+ * the outer one's DOM position and the two nest the way the reader's understanding
+ * nests.
+ *
+ * **The two axes are announced as two axes, which is the accessibility half of the
+ * cost above.** `label` names the outer list and `panelLabel` names the inner one,
+ * both through `aria-label` on each `TabsList`, so the reader is told which axis
+ * every arrow key and every Tab is currently about. That is the mitigation and it is
+ * a mitigation rather than a fix: two names in sequence do not make two identical
+ * shapes distinguishable at a glance for a reader scanning rather than listening.
+ *
+ * **It is a client Component**, because both axes move after the reader acts, and
+ * because every one of its value props is a function the caller hands it, which is a
+ * client-to-client boundary wherever it is written. What that costs is the price of
+ * every client control: a server Component may render one section with its panel
+ * already chosen, and what it may not do is let the reader move on either axis.
+ */
+function NestedTabs({ sections, value, onValueChange, panel, onPanelChange, label, panelLabel, fallback, className, }) {
+    const section = sections.find((candidate) => candidate.value === value) ?? sections[0];
+    const panels = section?.panels ?? [];
+    const active = panels.some((candidate) => candidate.value === panel) ? panel : undefined;
+    return (_jsx("div", { "data-slot": "nested-tabs", className: cn('flex w-full flex-col gap-4', className), children: _jsxs(Tabs, { value: section?.value, onValueChange: onValueChange, className: "w-full", children: [_jsx(TabsList, { "aria-label": label, children: sections.map((candidate) => (_jsx(TabsTrigger, { value: candidate.value, children: candidate.label }, candidate.value))) }), sections.map((candidate) => (_jsx(TabsContent, { value: candidate.value, children: _jsxs("div", { "data-slot": "nested-tabs-section", className: "flex flex-col gap-4 pt-2", children: [candidate.description === undefined ? null : (_jsx("p", { "data-slot": "nested-tabs-description", className: "text-muted-foreground text-sm", children: candidate.description })), panels.length === 0 ? (fallback) : (_jsxs(Tabs, { value: active ?? candidate.defaultPanel ?? panels[0]?.value, onValueChange: onPanelChange, className: "w-full", children: [_jsx(TabsList, { "aria-label": panelLabel, className: "max-w-full overflow-x-auto", children: panels.map((inner) => (_jsx(TabsTrigger, { value: inner.value, children: inner.label }, inner.value))) }), panels.map((inner) => (_jsx(TabsContent, { value: inner.value, children: inner.content }, inner.value)))] }))] }) }, candidate.value)))] }) }));
+}
+export { NestedTabs };

package/dist/components/ui/number-field.d.ts

@@ -14,6 +14,16 @@ export interface NumberFieldProps {
     };
     /** The accessible name of the field, when no visible label is used. */
     'aria-label'?: string;
+    /**
+     * Identifies the element that describes the field, which is where a unit goes.
+     *
+     * Required whenever `unit` is passed, and the reason is in the JSDoc below: the
+     * unit is drawn `aria-hidden`, so this prop is the only route by which "kg" or
+     * "ms" reaches a reader at all. It was documented as the answer and not carried,
+     * so a caller following the documentation had nowhere to put the sentence and the
+     * value was announced as a bare figure.
+     */
+    'aria-describedby'?: string;
     /** The current value, when the field is controlled. */
     value?: number | null;
     /** The value the field starts at, for an uncontrolled field. */
@@ -38,8 +48,9 @@ export interface NumberFieldProps {
      *
      * A unit is a word in the reader's language and it is hidden from the
      * accessibility tree, because a screen reader already says the unit when the
-     * caller puts it in the field's description. It is a prop because the Component
-     * does not know whether the reader measures in kilograms, pounds or seconds.
+     * caller points `aria-describedby` at a sentence that carries it. It is a prop
+     * because the Component does not know whether the reader measures in kilograms,
+     * pounds or seconds.
      */
     unit?: string;
     /** How the value is written for display: grouping, decimals, and so on. */
@@ -93,19 +104,41 @@ export interface NumberFieldProps {
  * second stop, so they are put back: three stops for one value, and the arrow keys
  * still work for a reader who is typing through the form.
  *
+ * **A coarse pointer turns the two steppers side by side, and this is the one place
+ * the floor changes an arrangement rather than a size.** Two 44px targets stacked in
+ * the split column need an 88px field, and an 88px text field is not a text field;
+ * a band is not available either, because two 44px bands centred on two 18px rows
+ * overlap by more than half of each and the lower row would take the boundary, so a
+ * press aimed at increment would step down. Side by side, each stepper is 44 by 44
+ * inside a field that stays 44 tall, which is the arrangement every mobile platform
+ * draws and the only one where the two targets do not compete. On a mouse and a
+ * trackpad the column is 36 tall and stacked, exactly as before.
+ *
  * **Empty is a value.** The field reports `null` when it is cleared, rather than
  * zero, because zero is a number a reader may have meant and an empty field is
  * not. A consumer that treats `null` as zero has made a decision this Component
  * refuses to make for it.
  *
- * **The unit is decoration.** It is hidden from the accessibility tree and the
- * caller describes the field once, in words, where a screen reader will reach it.
- * Two announcements of the same unit is one too many, and the visible one is the
- * one that was written in the reader's language by the reader's own product.
+ * **The unit is decoration, and the description is where a reader hears it.** The
+ * drawn span is `aria-hidden` and the field takes an `aria-describedby` the caller
+ * points at their own sentence. Three reasons, and they are the reason rather than
+ * the decoration. The unit belongs to the value and not to the field's identity, so
+ * putting it in `aria-label` would make the name "Parcel weight, kg" against a
+ * visible label reading "Parcel weight", which is exactly what WCAG 2.5.3 forbids
+ * and what voice control cannot activate. The `aria-label` is optional, so a field
+ * with a real `<label>` has no name to put it in at all. And two announcements of
+ * the same unit is one too many: the visible one was written in the reader's
+ * language by the reader's own product, and this Component does not know that word.
+ *
+ * The cost was that the prop was described here and not carried, so a caller who
+ * followed the documentation had no route and a value of 1,250 was announced as
+ * 1,250. `aria-describedby` is now on the props for the same reason `Combobox` and
+ * `MultiCombobox` carry it: the sentence is the caller's and the reference is the
+ * only honest way to hand it over.
  *
  * Reachable by Tab, moved by the arrow keys and by its two steppers, and the whole
  * field reads as one surface: one frame, one border, one focus colour.
  */
-declare function NumberField({ labels, 'aria-label': ariaLabel, value, defaultValue, onValueChange, min, max, step, unit, format, required, disabled, readOnly, name, form, id, className, }: NumberFieldProps): import("react").JSX.Element;
+declare function NumberField({ labels, 'aria-label': ariaLabel, 'aria-describedby': describedBy, value, defaultValue, onValueChange, min, max, step, unit, format, required, disabled, readOnly, name, form, id, className, }: NumberFieldProps): import("react").JSX.Element;
 export { NumberField };
 //# sourceMappingURL=number-field.d.ts.map

package/dist/components/ui/number-field.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"number-field.d.ts","sourceRoot":"","sources":["../../../src/components/ui/number-field.tsx"],"names":[],"mappings":"AAOA,0CAA0C;AAC1C,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAChD,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,kEAAkE;IAClE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IAC9C;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,2EAA2E;IAC3E,MAAM,CAAC,EAAE,IAAI,CAAC,mBAAmB,CAAA;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gEAAgE;IAChE,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAwBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,iBAAS,WAAW,CAAC,EACnB,MAAM,EACN,YAAY,EAAE,SAAS,EACvB,KAAK,EACL,YAAmB,EACnB,aAAa,EACb,GAAG,EACH,GAAG,EACH,IAAQ,EACR,IAAI,EACJ,MAAM,EACN,QAAgB,EAChB,QAAgB,EAChB,QAAgB,EAChB,IAAI,EACJ,IAAI,EACJ,EAAE,EACF,SAAS,GACV,EAAE,gBAAgB,+BAsFlB;AAED,OAAO,EAAE,WAAW,EAAE,CAAA"}
+{"version":3,"file":"number-field.d.ts","sourceRoot":"","sources":["../../../src/components/ui/number-field.tsx"],"names":[],"mappings":"AAOA,0CAA0C;AAC1C,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAChD,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,kEAAkE;IAClE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IAC9C;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,2EAA2E;IAC3E,MAAM,CAAC,EAAE,IAAI,CAAC,mBAAmB,CAAA;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gEAAgE;IAChE,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAwBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,iBAAS,WAAW,CAAC,EACnB,MAAM,EACN,YAAY,EAAE,SAAS,EACvB,kBAAkB,EAAE,WAAW,EAC/B,KAAK,EACL,YAAmB,EACnB,aAAa,EACb,GAAG,EACH,GAAG,EACH,IAAQ,EACR,IAAI,EACJ,MAAM,EACN,QAAgB,EAChB,QAAgB,EAChB,QAAgB,EAChB,IAAI,EACJ,IAAI,EACJ,EAAE,EACF,SAAS,GACV,EAAE,gBAAgB,+BAkHlB;AAED,OAAO,EAAE,WAAW,EAAE,CAAA"}

package/dist/components/ui/number-field.js

@@ -57,28 +57,58 @@ function clamp(value, min, max) {
  * second stop, so they are put back: three stops for one value, and the arrow keys
  * still work for a reader who is typing through the form.
  *
+ * **A coarse pointer turns the two steppers side by side, and this is the one place
+ * the floor changes an arrangement rather than a size.** Two 44px targets stacked in
+ * the split column need an 88px field, and an 88px text field is not a text field;
+ * a band is not available either, because two 44px bands centred on two 18px rows
+ * overlap by more than half of each and the lower row would take the boundary, so a
+ * press aimed at increment would step down. Side by side, each stepper is 44 by 44
+ * inside a field that stays 44 tall, which is the arrangement every mobile platform
+ * draws and the only one where the two targets do not compete. On a mouse and a
+ * trackpad the column is 36 tall and stacked, exactly as before.
+ *
  * **Empty is a value.** The field reports `null` when it is cleared, rather than
  * zero, because zero is a number a reader may have meant and an empty field is
  * not. A consumer that treats `null` as zero has made a decision this Component
  * refuses to make for it.
  *
- * **The unit is decoration.** It is hidden from the accessibility tree and the
- * caller describes the field once, in words, where a screen reader will reach it.
- * Two announcements of the same unit is one too many, and the visible one is the
- * one that was written in the reader's language by the reader's own product.
+ * **The unit is decoration, and the description is where a reader hears it.** The
+ * drawn span is `aria-hidden` and the field takes an `aria-describedby` the caller
+ * points at their own sentence. Three reasons, and they are the reason rather than
+ * the decoration. The unit belongs to the value and not to the field's identity, so
+ * putting it in `aria-label` would make the name "Parcel weight, kg" against a
+ * visible label reading "Parcel weight", which is exactly what WCAG 2.5.3 forbids
+ * and what voice control cannot activate. The `aria-label` is optional, so a field
+ * with a real `<label>` has no name to put it in at all. And two announcements of
+ * the same unit is one too many: the visible one was written in the reader's
+ * language by the reader's own product, and this Component does not know that word.
+ *
+ * The cost was that the prop was described here and not carried, so a caller who
+ * followed the documentation had no route and a value of 1,250 was announced as
+ * 1,250. `aria-describedby` is now on the props for the same reason `Combobox` and
+ * `MultiCombobox` carry it: the sentence is the caller's and the reference is the
+ * only honest way to hand it over.
  *
  * Reachable by Tab, moved by the arrow keys and by its two steppers, and the whole
  * field reads as one surface: one frame, one border, one focus colour.
  */
-function NumberField({ labels, 'aria-label': ariaLabel, value, defaultValue = null, onValueChange, min, max, step = 1, unit, format, required = false, disabled = false, readOnly = false, name, form, id, className, }) {
+function NumberField({ labels, 'aria-label': ariaLabel, 'aria-describedby': describedBy, value, defaultValue = null, onValueChange, min, max, step = 1, unit, format, required = false, disabled = false, readOnly = false, name, form, id, className, }) {
     return (_jsx(NumberFieldPrimitive.Root, { "data-slot": "number-field", className: cn('w-full', className), ...(value === undefined
             ? { defaultValue: clamp(defaultValue, min, max) ?? undefined }
             : { value: clamp(value, min, max) }), onValueChange: (next) => onValueChange?.(next), 
         // The id belongs to the root, not to the input, because Base UI's steppers
         // point their `aria-controls` at it and a dangling reference is a violation
         // that reads, in a screen reader, as a control pointing at nothing.
-        id: id, min: min, max: max, step: step, required: required, disabled: disabled, readOnly: readOnly, name: name, ...(form === undefined ? null : { form }), ...(format === undefined ? null : { format }), children: _jsxs("div", { "data-slot": "number-field-group", className: cn('border-input bg-background focus-within:border-ring flex w-full items-stretch rounded-md border shadow-xs', 'transition-[color,box-shadow] duration-fast ease-out', 'has-[input:disabled]:opacity-50'), children: [_jsx(NumberFieldPrimitive.Input, { "data-slot": "number-field-input", "aria-label": ariaLabel, className: cn('placeholder:text-muted-foreground flex h-9 min-w-0 flex-1 border-0 bg-transparent px-3 py-1 text-base shadow-none outline-none md:text-sm', 'focus-visible:border-0 focus-visible:ring-ring focus-visible:ring-[3px]') }), unit === undefined ? null : (_jsx("span", { "data-slot": "number-field-unit", "aria-hidden": "true", className: "text-muted-foreground flex shrink-0 items-center pr-2 text-sm", children: unit })), _jsxs("div", { "data-slot": "number-field-stepper", className: "border-input flex shrink-0 flex-col border-s", children: [_jsx(NumberFieldPrimitive.Increment, { "data-slot": "number-field-increment", "aria-label": labels.increment, 
+        id: id, min: min, max: max, step: step, required: required, disabled: disabled, readOnly: readOnly, name: name, ...(form === undefined ? null : { form }), ...(format === undefined ? null : { format }), children: _jsxs("div", { "data-slot": "number-field-group", className: cn('border-input bg-background focus-within:border-ring flex w-full items-stretch rounded-md border shadow-xs', 'transition-[color,box-shadow] duration-fast ease-out', 'has-[input:disabled]:opacity-50', 
+            // 44px on a coarse pointer, because the steppers beside it are 44px on a
+            // coarse pointer and a 36px field cannot hold two 44px targets without
+            // becoming an 88px field. See the JSDoc.
+            'pointer-coarse:h-11'), children: [_jsx(NumberFieldPrimitive.Input, { "data-slot": "number-field-input", "aria-label": ariaLabel, ...(describedBy === undefined ? null : { 'aria-describedby': describedBy }), className: cn('placeholder:text-muted-foreground flex h-9 min-w-0 flex-1 border-0 bg-transparent px-3 py-1 text-base shadow-none outline-none md:text-sm', 'focus-visible:border-0 focus-visible:ring-ring focus-visible:ring-[3px]', 
+                    // `items-stretch` on the group only sizes a child whose own height is
+                    // `auto`, and this one states `h-9`, so the field's coarse-pointer height
+                    // has to be stated here rather than inherited from the group.
+                    'pointer-coarse:h-11') }), unit === undefined ? null : (_jsx("span", { "data-slot": "number-field-unit", "aria-hidden": "true", className: "text-muted-foreground flex shrink-0 items-center pr-2 text-sm", children: unit })), _jsxs("div", { "data-slot": "number-field-stepper", className: cn('border-input flex shrink-0 flex-col border-s', 'pointer-coarse:flex-row'), children: [_jsx(NumberFieldPrimitive.Increment, { "data-slot": "number-field-increment", "aria-label": labels.increment, 
                             // Put back into the tab order on purpose; see the JSDoc.
-                            tabIndex: 0, className: cn('text-muted-foreground hover:bg-accent hover:text-accent-foreground flex h-1/2 items-center justify-center border-b px-2 outline-none', 'transition-colors duration-fast ease-out focus-visible:ring-ring focus-visible:ring-[3px]', 'data-[disabled]:pointer-events-none data-[disabled]:opacity-40'), children: _jsx(ChevronUpIcon, { className: "size-3.5" }) }), _jsx(NumberFieldPrimitive.Decrement, { "data-slot": "number-field-decrement", "aria-label": labels.decrement, tabIndex: 0, className: cn('text-muted-foreground hover:bg-accent hover:text-accent-foreground flex h-1/2 items-center justify-center px-2 outline-none', 'transition-colors duration-fast ease-out focus-visible:ring-ring focus-visible:ring-[3px]', 'data-[disabled]:pointer-events-none data-[disabled]:opacity-40'), children: _jsx(ChevronDownIcon, { className: "size-3.5" }) })] })] }) }));
+                            tabIndex: 0, className: cn('text-muted-foreground hover:bg-accent hover:text-accent-foreground flex h-1/2 items-center justify-center border-b px-2 outline-none', 'transition-colors duration-fast ease-out focus-visible:ring-ring focus-visible:ring-[3px]', 'data-[disabled]:pointer-events-none data-[disabled]:opacity-40', 'pointer-coarse:h-auto pointer-coarse:min-w-11 pointer-coarse:border-b-0 pointer-coarse:border-r'), children: _jsx(ChevronUpIcon, { className: "size-3.5" }) }), _jsx(NumberFieldPrimitive.Decrement, { "data-slot": "number-field-decrement", "aria-label": labels.decrement, tabIndex: 0, className: cn('text-muted-foreground hover:bg-accent hover:text-accent-foreground flex h-1/2 items-center justify-center px-2 outline-none', 'transition-colors duration-fast ease-out focus-visible:ring-ring focus-visible:ring-[3px]', 'data-[disabled]:pointer-events-none data-[disabled]:opacity-40', 'pointer-coarse:h-auto pointer-coarse:min-w-11'), children: _jsx(ChevronDownIcon, { className: "size-3.5" }) })] })] }) }));
 }
 export { NumberField };

package/dist/components/ui/overflow-actions.d.ts

@@ -0,0 +1,169 @@
+import { type ReactNode } from 'react';
+/**
+ * One action in the row, whether it is drawn as a button or as a menu row.
+ *
+ * The same shape either way, which is the point: an action that moves into the
+ * menu keeps its label, its mark and its unavailable state, so a reader who finds
+ * it there is looking at the same thing they were looking at in the row.
+ */
+export type OverflowAction = {
+    /**
+     * The caller's own identity for the action.
+     *
+     * Required and stable, because it is what the React key is and what
+     * `onOverflowChange` reports, and a caller keyed on a localised label remounts
+     * the row the moment the reader changes language.
+     */
+    id: string;
+    /**
+     * The action's label.
+     *
+     * A `ReactNode`, so a caller can put an emphasis inside it. It is also the
+     * measurement: this Component reads each drawn button's own width, so a label
+     * made of markup is measured as it is drawn rather than as its text.
+     */
+    label: ReactNode;
+    /**
+     * The mark for the action.
+     *
+     * A `ReactNode` and not an icon name, because the vocabulary a product uses for
+     * its own rows is its own. Keep it `aria-hidden`, because `label` names the
+     * control.
+     */
+    icon?: ReactNode;
+    /**
+     * How the menu row reads when the action has collapsed into it.
+     *
+     * `danger` and not `destructive` so a consumer's tone and this Component's tone
+     * stay two vocabularies. It has no effect on the drawn button, which wears
+     * `outline` because the overflow trigger wears that same frame and the row is
+     * not allowed to disagree with its own cap.
+     */
+    tone?: 'default' | 'danger';
+    /** Whether the action refuses the press, in the row and in the menu alike. */
+    disabled?: boolean;
+};
+/**
+ * The props the Overflow actions accept.
+ *
+ * A declared interface rather than a forwarded native one: the row is measured
+ * and laid out by this Component, so there is no native element whose props could
+ * be forwarded without also forwarding a `className` that would break the
+ * measurement the whole Component exists to make.
+ */
+export interface OverflowActionsProps {
+    /**
+     * The actions, in the order a reader meets them.
+     *
+     * Required, and the order is the caller's because it is a claim about how often
+     * each is used: a row where Archive sits between Open and Delete is one every
+     * reader has to learn again. **The order is also what collapses.** Trailing
+     * actions move, because the leading ones are the ones a wide row already fits
+     * and a narrow one must keep: the actions that survive are the ones that were
+     * reachable first.
+     */
+    actions: readonly OverflowAction[];
+    /**
+     * The accessible name of the overflow trigger.
+     *
+     * Required, and the reason is the one `Toast` states for its close control. The
+     * trigger is an icon, it appears without the reader asking for it, and an
+     * icon-only control they reach towards has to say what it is before they press
+     * it. "More actions for this row", "Remaining actions". It is a name and not a
+     * visible label because the trigger is three dots and three dots are not a word.
+     */
+    overflowLabel: string;
+    /**
+     * Called with the ids of the actions currently inside the menu.
+     *
+     * Optional, and it is here for the caller whose row means something different
+     * once the actions are hidden: a tooltip that described them, a measurement,
+     * an analytics event. It fires on the change and never on the first render, so
+     * a caller does not receive an empty list it already knows is empty. **The cost
+     * is that this Component cannot tell a caller *why* an action moved**, only
+     * that it did, so a caller whose UI depends on the reason is measuring its own
+     * container as well.
+     */
+    onOverflowChange?: (ids: readonly string[]) => void;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+}
+/**
+ * A row of actions that gives up its trailing actions when it runs out of room.
+ *
+ * **It observes itself, and that is the reason it is a Component.** A row of five
+ * actions inside a table cell is a layout problem no prop describes, because the
+ * answer depends on a width Prism cannot see: the cell, the sidebar, the zoom
+ * level, the font the reader has chosen and the strings the caller localised last
+ * week. So the Component holds a measurement, keeps it current, and moves the
+ * trailing actions into a menu when the row can no longer hold them beside their
+ * cap. No prop combination expresses this, because every prop is a decision taken
+ * before the width is known and this is a decision taken after it.
+ *
+ * **What the first frame draws, and why it is not a guess.** A server render has
+ * no width to measure, so the first frame draws every action the caller passed and
+ * **no cap**, which is the row the caller described rather than the row this
+ * Component would have guessed at. The correction is made in a layout effect,
+ * which runs after the DOM is mutated and before the browser paints, so a reader
+ * with scripting sees the corrected row as the first frame they ever see and
+ * never sees the un-collapsed one at all. What is therefore visible to a reader
+ * without scripting, to a crawler and in a print stylesheet is the full row, which
+ * is the correct answer for all three: a cap that cannot open is a control that
+ * lies, and a row of actions is readable without them.
+ *
+ * **The cap is always in the document and is taken out of the flow rather than
+ * unmounted, and the reason is the measurement.** A trigger that is not rendered
+ * has no width to read, and a row that changed width when the cap appeared would
+ * move its actions on every resize, so the cap stays in the DOM, keeps its width,
+ * and when nothing has collapsed it is `visibility: hidden`, out of flow, out of
+ * the tab order and out of the accessibility tree. That is what lets the first
+ * decision account for a cap that will need to appear.
+ *
+ * **Each action's width is read from the action, and it is remembered when the
+ * action is hidden.** A button sizes to its own content, so a width measured on
+ * the pass where the action was drawn is still its width on the pass where it is
+ * not, which is the only reason a hidden action can still be counted. The cost is
+ * real and it is this: **a row that shrinks to fit its content has no room to run
+ * out of, so nothing collapses.** `className` must give the row a bounded width,
+ * and the consequence of ignoring that is not a row that overflows its container
+ * but a row that empties itself into a cap.
+ *
+ * **A pass runs when the measurement could have changed, and not on every render.**
+ * Every read a pass makes is a read the browser cannot answer without settling
+ * layout first, so a row that measures on every render spends a forced layout on
+ * every render, and a table of them spends one per row for every keystroke in a
+ * filter box somewhere above it. So a pass runs on mount, when the actions' ids or
+ * their labels change, when `className` changes, when the row's own box changes, and
+ * when the page's fonts have finished loading. That last one earns its place: a
+ * self-hosted face swaps in after the first paint and changes the width of every
+ * drawn action without changing the row's width, so nothing else reports it, and a
+ * row measured in the fallback face is a row whose widths were never true of the page
+ * the reader is looking at. A caller who re-renders a row for a reason of its own
+ * pays nothing, which is the whole of the claim: the read happens on the frames
+ * where the answer could have been different, and on no others.
+ *
+ * **The determinate part of the motion budget is not spent here at all.** The row
+ * changes membership rather than animating: an action leaves, the cap arrives, and
+ * both are one layout pass with no transition on either. That is deliberate. A
+ * row that slid its actions sideways would be a movement a reader did not ask for
+ * on a control they did not press, and the first motion law in this system is
+ * that feedback answers something the reader did; here the reader resized a window
+ * or changed a sidebar, and the answer is that the row is still complete.
+ *
+ * **It composes `Button` and `DropdownMenu` and redraws neither.** The drawn
+ * actions are `Button`s at the `outline` step, which is the same frame
+ * `DropdownMenuTrigger` draws, so the cap is not a different-looking control
+ * sitting in the middle of the row. The menu, its typeahead, its arrow keys and
+ * its Escape handling are `DropdownMenu`'s, and the only thing this Component
+ * decides is which actions go where.
+ *
+ * **It is a client Component**, because it reads a width, because it holds the
+ * membership of the menu, and because it takes the one callback. What that costs
+ * is the price of the whole idea: a server-rendered row of actions is drawn whole
+ * and never collapses, so a page that is read without scripting gets a row rather
+ * than a menu. That is the same trade `DataToolbar` makes for the opposite
+ * problem, and it is the reason this one is a Component and `DataToolbar` is not.
+ */
+declare function OverflowActions({ actions, overflowLabel, onOverflowChange, className, }: OverflowActionsProps): import("react").JSX.Element;
+export { OverflowActions };
+//# sourceMappingURL=overflow-actions.d.ts.map

package/dist/components/ui/overflow-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overflow-actions.d.ts","sourceRoot":"","sources":["../../../src/components/ui/overflow-actions.tsx"],"names":[],"mappings":"AAGA,OAAO,EAQL,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AAWd;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;;OAMG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;;;;;OAMG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAA;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;OASG;IACH,OAAO,EAAE,SAAS,cAAc,EAAE,CAAA;IAClC;;;;;;;;OAQG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAA;IACnD,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AA8CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,iBAAS,eAAe,CAAC,EACvB,OAAO,EACP,aAAa,EACb,gBAAgB,EAChB,SAAS,GACV,EAAE,oBAAoB,+BAmMtB;AAED,OAAO,EAAE,eAAe,EAAE,CAAA"}