@scalewing/react 1.25.0 → 1.27.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @scalewing/react
 
+## 1.27.0
+
+### Minor Changes
+
+- 495d542: `ActionBar` `summary` (with `ActionBarSummary` and `ActionBarSummaryTone`): a labelled figure first in the bar's polite status region (`docs/requests/teisoro-action-bar-summary.md`, Teisoro F-011 release R1).
+
+  - `summary: { label, value, detail?, tone?: 'default' | 'danger' | 'success' }`: the label and detail in muted label-size words, the value in the `heading` variant at tabular figures, on one baseline; `tone` colors the value only. Any `status` follows it in the same live region.
+  - A blank `label`, `value` or `detail`, or an unknown `tone`, throws a `RangeError`.
+  - New generated classes `sw-action-bar-summary`, `sw-action-bar-summary-label`, `sw-action-bar-summary-value`, `sw-action-bar-summary-detail`, `sw-action-bar-summary-danger` and `sw-action-bar-summary-success`. No new tokens or dependencies.
+
+- db1d77b: `DenominationGrid` count entry (`docs/requests/teisoro-denomination-grid-entry.md`, Teisoro F-011 release R1), with the new types `DenominationGridEntry` and `DenominationGridRowEmphasis`:
+
+  - `DenominationGridRow.entry` (`onChange(columnKey, value)`, `decrementLabel`, `incrementLabel`, `max?`, `errors?`, `placeholder?`) makes a strip row's `cells` editable, one full-width `Stepper` per column named by the row label and the column's label and caption. Entry counts are zero or more and unsigned, and every count's name is its own. A strip with an entry row centres its heads and read-only counts; a `cellTones` tone draws an entry count's border (`accent` is the `Stepper`'s changed look).
+  - `DenominationGridRow.caption` (a muted line under the label), `emphasis` (`'default' | 'quiet'`, the subtle fill) and `disabled` (faded, entry disabled, `aria-disabled`), both strip only.
+  - `DenominationGridColumn.caption`: a muted note after the column label, such as "× 100".
+  - Entry rows need the strip layout; bad caps, messages, button names, captions or emphasis throw a `RangeError`.
+  - `Stepper` is now `position: relative`, so its hidden label and empty error region never widen a scroll region's page.
+  - New generated classes `sw-denomination-entry`, `sw-denomination-strip-entry`, `sw-denomination-label-words`, `sw-denomination-label-caption`, `sw-denomination-head-caption`, `sw-denomination-row-quiet` and `sw-denomination-row-disabled`. No new tokens or dependencies.
+
+- 92357d4: `Steps` and `Step` (with `StepsProps`, `StepProps`, `StepStatus`, `StepHeadingLevel` and `StepsLabels`): a one-page vertical stepper (`docs/requests/teisoro-steps.md`, Teisoro F-011 release R1).
+
+  - `Steps`: an `ol` of steps numbered by their place, with `headingLevel` (2 by default) and `labels` (the status words assistive technology hears; English by default).
+  - `Step`: `status` (`'upcoming' | 'current' | 'done' | 'error' | 'skipped'`), `title`, `summary`, `onEdit` and `editLabel`, `skippedReason`, `headingLevel`, `children`. The current and error steps are open with their fields; a done step folds to a check, its title, a truncated summary and a ghost Edit named by its title; steps ahead and skipped ones are greyed. A line joins each marker to the next.
+  - The current step has `aria-current="step"`; focus moves to a step's heading when it becomes current from a folded state (the first such step in an update).
+  - New generated classes `sw-steps`, `sw-steps-item`, `sw-steps-item-<status>`, `sw-steps-header`, `sw-steps-marker`, `sw-steps-title`, `sw-steps-reason`, `sw-steps-summary`, `sw-steps-edit` and `sw-steps-body`, from tokens (the `xs` control height marker, the `title` and body type). No new tokens or dependencies.
+
+- 35934e1: `Stepper` (with `StepperProps` and `StepperWidth`): a whole-number count changed with − and + or typed, the web counterpart of the react-native `Stepper` (`docs/requests/teisoro-stepper.md`, Teisoro F-011 release R1).
+
+  - `label`, `labelVisuallyHidden`, `value` (`number | null`), `onChange`, `min` (default 0), `max` (open when left out), `step` (default 1), `decrementLabel`, `incrementLabel`, `error`, `changed`, `disabled`, `readOnly`, `valueText`, `placeholder`, `name`, `width` (`'fixed' | 'full'`), and a ref to the input.
+  - The count is a native text input with `role="spinbutton"` and the one tab stop (ArrowUp and ArrowDown step it, Home and End go to `min` and a finite `max`); the − and + buttons are named pointer targets outside the tab order that keep focus where it was, all three in a `group` named by the label. − stops at `min`, + at `max`; an empty box counts as `min`.
+  - Typed text other than digits (and a leading minus when `min` is below zero) is refused; a typed count is reported as typed, even outside the bounds, for the consumer's `error`.
+  - New generated classes `sw-stepper`, `sw-stepper-full`, `sw-stepper-track`, `sw-stepper-button`, `sw-stepper-input`, `sw-stepper-invalid`, `sw-stepper-changed` and `sw-stepper-readonly`, sized from the `md` control height and spacing step 6. No new tokens or dependencies.
+
+## 1.26.0
+
+### Minor Changes
+
+- e484799: `DescriptionList` and `DescriptionItem` (with `DescriptionListProps` and `DescriptionItemProps`): terms paired with what each says, one per row (`docs/requests/teisoro-description-list.md`, Teisoro F-006-S03).
+
+  - A `dl` of items, each a `div` grouping a `dt` (`term`) with its `dd` (`children`); the list and each item take their own HTML attributes and `className`.
+  - From `md` up the items share the list's two columns (`subgrid`): the term column as wide as the widest term, up to 40% of the list, then the detail. Every row aligns to its top, a hairline (`--sw-color-border`, `CanvasText` in forced colors) divides the rows, and the list is flush above its first row and below its last.
+  - Below `md` each term sits over its detail.
+  - A term and a detail are columns of lines: each child is its own line with its own line height, so a caption term starts level with a caption detail; each is as wide as its content unless it sets its own width (a `Progress` fills the detail), and long unbreakable words wrap. Wrap inline content in one element.
+  - New generated classes `sw-description-list`, `sw-description-item`, `sw-description-term` and `sw-description-detail`. No new tokens or dependencies.
+
 ## 1.25.0
 
 ### Minor Changes

package/README.md

@@ -22,11 +22,16 @@ import {
   Tooltip,
   InfoTip,
   Separator,
+  DescriptionList,
+  DescriptionItem,
   DenominationGrid,
   FilterChips,
   Grid,
   DateField,
   Field,
+  Stepper,
+  Steps,
+  Step,
   Select,
   Switch,
   Split,
@@ -50,7 +55,25 @@ Import the CSS once at the application entry. Do not copy it into your source tr
 
 `Box` `border` draws a hairline in the `border` color token: `border` (or `border={true}`) is solid, and `border="dashed"` is dashed (the generated `sw-border` and `sw-border-dashed` classes; a `style` you pass still wins), for a space to fill in by hand such as a blank on a printed form. It does not make the box look or act like an input. Every `Box`-based component takes it.
 
-`Box hideBelow="md"` hides a region under 48rem and `hideFrom="md"` hides it at 48rem and wider, so a product can swap a wide layout for a narrow one without its own stylesheet. They also take `lg` (64rem), for content that fits only from a laptop up, such as a row of labelled destinations that a tablet shows as glyphs (name each glyph-only control, for example with `Tooltip relationship="label"`); the layout props keep `md`. `breakpointQuery('below', 'lg')` returns the query a hide class uses (`not all and (min-width: 64rem)`), for an app whose script must follow the same width. An unknown breakpoint throws a `RangeError`. Hidden regions leave the accessibility tree; do not use this to protect data. `Box as="a"` is a layout link. Use `Button` for press actions. `Field` associates a native `<input>` or `<select>` with a label and token gap; native text controls inherit the generated document canvas. `Select` is a labeled listbox menu when the open list must match the canvas.
+`Box hideBelow="md"` hides a region under 48rem and `hideFrom="md"` hides it at 48rem and wider, so a product can swap a wide layout for a narrow one without its own stylesheet. They also take `lg` (64rem), for content that fits only from a laptop up, such as a row of labelled destinations that a tablet shows as glyphs (name each glyph-only control, for example with `Tooltip relationship="label"`); the layout props keep `md`. `breakpointQuery('below', 'lg')` returns the query a hide class uses (`not all and (min-width: 64rem)`), for an app whose script must follow the same width. An unknown breakpoint throws a `RangeError`. Hidden regions leave the accessibility tree; do not use this to protect data. `Box as="a"` is a layout link. Use `Button` for press actions. `Field` associates a native `<input>` or `<select>` with a label and token gap; native text controls inherit the generated document canvas. `Steps` is a one-page vertical stepper: an `ol` of `Step` panels in order, numbered by their place, a line joining each marker to the next (in the success color below a done step). A `Step` takes `status` (`'upcoming' | 'current' | 'done' | 'error' | 'skipped'`) and `title` (a heading at the list's `headingLevel`, 2 by default, or the step's own). The current step is open with its `children` and has `aria-current="step"`; an error step stays open with a "!" marker. A done step folds to one line: a check, the title, its `summary` (truncated) and, with `onEdit` and `editLabel`, a ghost small `Button` at the end named by its label and the title ("Edit The site"). A step ahead is greyed with its number in a ring; a skipped step is greyed with its `skippedReason` after the title (pass your own separator, such as "· not needed"). A folded step's heading ends in its status word for assistive technology (visually hidden; English by default, `labels` on `Steps` takes your words). When a step becomes current from a folded state (upcoming, done or skipped), focus moves to its heading, a programmatic focus target; if several do in one update, the first in the list takes it. A first render, a move between current and error, and a step that turns to error leave focus alone: after a refused submit, move focus to the first invalid field yourself, as with `Field`. An error step has no `aria-current`; its heading's status word says it needs attention. Scalewing holds no order rules: the consumer sets each step's status. Pass the `Step`s as direct children (a Fragment around several would share one number). A `Step` outside `Steps`, a Fragment child, a blank title or reason, an unknown status or heading level, `onEdit` without `editLabel`, or a blank status word throws a `RangeError`.
+
+```tsx
+<Steps aria-label="Heron survey">
+  <Step
+    status="done"
+    title="The site"
+    summary="North marsh"
+    editLabel="Edit"
+    onEdit={() => setCurrent(0)}
+  />
+  <Step status="current" title="The count">
+    {fields}
+  </Step>
+  <Step status="upcoming" title="Review" />
+</Steps>
+```
+
+`Select` is a labeled listbox menu when the open list must match the canvas.
 
 `Field` supports optional `description`, `error`, and `required` on one native input, select, or textarea child. It preserves an existing `aria-describedby` and appends a stable ID for the hint, or for the error, which replaces the hint on screen while it is supplied. `error` sets `aria-invalid` and token-owned invalid styling. The error sits in a polite live region (`aria-live="polite"`) that is always rendered, empty while there is no error, so an error that appears while the person types, or after a submit, is announced once, politely, when its text is swapped in; it is never `role="alert"`, so a submit that finds several errors does not fire several assertive alerts at once. Empty, the region takes no room in the layout. The consumer owns validation and localized messages, and after a refused submit it moves focus to the first invalid control (or to one form-level summary). `Checkbox`, `RadioGroup` and `DateField` expose their `error` the same way. `invalid` marks the control invalid the same way (`aria-invalid` and the danger border, `Mark` in forced colors) without a message of its own, for fields whose one error is shown elsewhere, such as a count that adds up to nothing under a group of count fields: point each control's `aria-describedby` at that message so it is read with the field. The field's own polite region stays empty and its `description` stays on screen; `error` implies `invalid`. Passing `invalid`, even `invalid={false}` but not `invalid={undefined}`, needs one native control child and throws a `TypeError` on the first render otherwise, so a form learns it while the fields are valid, not on its first failed submit. `error` keeps its rule: it needs the native control only while it holds a message. `invalid` is `Field`'s only: `DateField`, `Select` and the other controls with `error` do not have it yet.
 
@@ -82,6 +105,21 @@ A disabled native text control (`<input>`, `<select>` or `<textarea>` on the can
 </Field>
 ```
 
+`Stepper` is a whole-number count changed with − and + or typed. The count is a native text input with `role="spinbutton"` and `inputmode="numeric"`, named by `label` (visible above it, or `labelVisuallyHidden` where table headers say it) and the one tab stop: ArrowUp and ArrowDown step it by `step` (default 1), Home goes to `min` and End to a finite `max` (a range below zero takes `inputmode="text"`, since a phone's numeric pad has no minus key). The − and + buttons are pointer targets outside the tab order, named by `decrementLabel` and `incrementLabel` (your copy), and a press on one leaves focus where it was; the count and both buttons sit in a `group` named by the label. − is disabled at `min` (default 0) and + at `max` (no upper bound when left out). `value` is a count or `null` for an empty box, which the buttons treat as `min` and `placeholder` can fill. Typed text is refused unless it is digits (with a leading minus when `min` is below zero), so `onChange` only receives a whole number or `null`; a typed count is reported as typed even outside the bounds, so say why in `error` (a polite message, `aria-invalid` and the danger border, as `Field`'s), and the buttons then move it back inside them. `changed` takes `Field`'s changed look; `readOnly` keeps the count focusable and hides the buttons in their own room; `disabled` stops all three. The count is a few digits wide and keeps that width (`width="fixed"`), or fills its container (`width="full"`, for a table cell). Bounds that are not whole numbers, `min` above `max`, or a `step` that is not above zero throw a `RangeError`.
+
+```tsx
+<Stepper
+  label="Herons"
+  value={count}
+  onChange={setCount}
+  max={40}
+  decrementLabel="One less"
+  incrementLabel="One more"
+  placeholder="0"
+  error={count !== null && count > nests ? `Only ${nests} nests.` : undefined}
+/>
+```
+
 `Select` is a labeled listbox menu: supply `label`, `options` (`value` and `label`), a controlled `value` and `onChange`; `size="xs"` and `labelVisuallyHidden` are for toolbar chrome, and `action` is a last listbox command that never becomes the value. The closed trigger matches `Field`: its text is centred in the control, it ends in the `Accordion` chevron, and it is as wide as its longest option (as a native select is), so it keeps its width when the value changes; past the available width the label ellipsizes. The option labels that size it are drawn by CSS from `data-label`, so the trigger's text content and accessible value are only the current label. Its label is drawn as `Field`'s (the same label words and mark inside a `<label>` that keeps the canvas type), so a `Select` beside a `Field` lines up at the label and the control.
 
 `Select` `placeholder` shows in the closed trigger, in the muted color, while `value` matches no option (such as `''`); it is not an option, is never selected in the list and never becomes the value, and it counts toward the trigger's width. `required` marks the label with `Field`'s `aria-hidden` asterisk and sets `aria-required` on the trigger. `error` renders a message under the control (`sw-field-error`), links it by `aria-describedby`, sets `aria-invalid` and the danger border; like `Field`'s it is announced politely from a live region that is always there, never as an alert, and an empty string is no error. A blank `placeholder` throws a `RangeError`.
@@ -132,6 +170,26 @@ A disabled native text control (`<input>`, `<select>` or `<textarea>` on the can
 
 `ActionBar` keeps the actions of a long page on a glass bar stuck to the bottom of the viewport, with an optional short `status` (such as when the work was last saved): a string, or a node such as a `Badge` and then a short line. Put it last in the content it acts on: it stays stuck while that content scrolls by and then rests in its own place at the end. `stickyBelow="md"` sticks only on a phone and leaves the bar in page flow from `md` up. The bar clears `env(safe-area-inset-bottom)` (set `viewport-fit=cover` in the page's viewport meta for the inset to apply). Its children are the actions: on a phone they share one row under the status. The status is a polite live region (`role="status"`, kept in the page even while empty), so a new status such as "Draft saved at 5:00 PM" is announced; do not announce the same save a second time with your own notice. The status is a `div` whose children sit on one row a `space-2` gap apart and wrap under one another when the row is full, so a line that does not fit beside its badge drops under it on a phone; put a phrase that mixes text and elements in one `span` so it wraps as a sentence. `undefined`, `null` or `false` leaves the status empty. An open `Select`, `ActionMenu` or `Tooltip` paints over the bar, including inside a glass `Card` or `Accordion`.
 
+`ActionBar` `summary` (`{ label, value, detail?, tone? }`, type `ActionBarSummary`) puts a labelled figure first in the same polite status region, before any `status`: the label and the detail in muted label-size words, the value between them in the `heading` variant (24 below `md`) at tabular figures, all on one baseline and wrapping as one phrase, such as "Counted **$33,790.00** short $4,000.00". `tone` (`'default' | 'danger' | 'success'`, such as danger while short or over and success once it matches) colors the value only, so say why in the detail. Format the value yourself; each new figure is announced politely. For a guided form, the actions are a secondary Cancel and one primary that stays `disabled` until the form is valid. A blank `label`, `value` or `detail`, or an unknown `tone`, throws a `RangeError`.
+
+```tsx
+<ActionBar
+  summary={{
+    label: 'Counted',
+    value: '14 nests',
+    detail: 'short 2',
+    tone: 'danger',
+  }}
+>
+  <Button variant="secondary" onPress={cancel}>
+    Cancel
+  </Button>
+  <Button disabled={!matches} onPress={save}>
+    Save count
+  </Button>
+</ActionBar>
+```
+
 ```tsx
 <Stack gap={4}>
   {longForm}
@@ -310,6 +368,27 @@ A header `TableCell` (`as="th"`) with `sort` (`'ascending'`, `'descending'` or `
 
 `Separator` divides sections with a token-colored line. It is horizontal by default; use `orientation="vertical"` in a flex row. Set `decorative` when the line only supports layout so assistive technology ignores it.
 
+`DescriptionList` pairs terms with what each says, one `DescriptionItem` per row: a `dl` whose items each group a `dt` (`term`) with its `dd` (`children`). From `md` up the term sits in a start column as wide as the widest term, up to 40% of the list, and the detail beside it; every row aligns to its top, so a term and its detail's first line start level, and a hairline divides the rows, with no space above the first row or below the last. Below `md` each term sits over its detail. The list sets only the layout: pass your own `Text` for the term and the detail. Each child of a term or a detail is its own line with its own line height (a column), as wide as its content unless it sets its own width (a `Progress` fills the detail; a `Field` keeps its input's width): wrap inline content, such as words and a link on one line, in one element such as an `Inline`. Long unbreakable words wrap inside their column. A `dl` has no ARIA role, so name a list with a visible heading, and `aria-labelledby` on the `section` around it, rather than an `aria-label` on the list.
+
+```tsx
+<DescriptionList>
+  <DescriptionItem
+    term={
+      <Text variant="caption" color="muted">
+        Wetland
+      </Text>
+    }
+  >
+    <Inline align="start" gap={2} wrap>
+      <Text variant="data">12 herons</Text>
+      <Text variant="caption" color="muted">
+        Recounted
+      </Text>
+    </Inline>
+  </DescriptionItem>
+</DescriptionList>
+```
+
 `Card` defaults to `glass`; `outlined` and `elevated` are solid surfaces, and `filled` is a quiet `--sw-color-subtle` fill with no border for plain information apart from pressable rows.
 
 `--sw-color-accentSubtle` is the accent tint from `@scalewing/tokens`: a quiet fill behind accent text or glyphs that keeps 4.5:1. The stylesheet and every palette file set it, and a palette that moves the accent or surface retints it.
@@ -346,6 +425,36 @@ Values outside the catalog throw a `RangeError`. There is no per-breakpoint span
 
 `DenominationGrid` shows integer counts per unit across a fixed set of columns. The `strip` layout is a captioned table: each row has a toned label with an icon slot, muted zero cells, optional signed deltas toned by sign, and an optional consumer-formatted `total` that shows under the label on a phone. Pass `totalLabel` (for example "Total") to name the total column: it renders a `th scope="col"` shown over the totals from `md` up and visually hidden below it, and without it the corner stays an empty cell as before (either way the column takes no width on a phone). `labelWidth` (`xs` to `xl`, the `Table` column sizes) lines a strip's columns up with every other strip of the same columns in a container of the same width, such as the cards of a feed: the row labels take that width and the count columns share the rest of the region equally, so no content moves a column. On a phone the total cell stays in the table, visually hidden, so a screen reader still reads each total in its row; the copy under the label is `aria-hidden`. A strip wider than its container scrolls sideways inside its own keyboard-focusable region, named after `label`, with the row labels pinned at the start and the same edge shade as `Table` while counts are scrolled out of view (the start shade is cast from the pinned labels' edge, since they cover the region's own); the page never scrolls sideways. The `tiles` layout stacks the column label, the count, and an optional `subtotal` string per column. Each tiles row shows its label line (icon, label and `total`) when the grid has several rows, or when a lone row has an icon or a `total`; a lone plain row is named by the grid's `label` alone. Every row is a region named by its `label`, except a lone plain row whose `label` is the grid's own: it has no name of its own, so assistive technology hears the grid's group once rather than a region repeating it. `rowRole="group"` (default `"region"`) keeps every named row's name but makes it a `group` instead of a landmark region, for a page with many grids (one per order card, say) whose rows would otherwise fill the landmark list; the strip ignores it, since its rows are table rows, and an unknown `rowRole` throws a `RangeError` in either layout. A row's icon and its label words stay on one line in both layouts (`sw-denomination-label-line`): a long label wraps its words beside the icon, never under it, and on a phone the strip's total goes on its own line under them. A row's `cellTones` (one Badge tone or `null` per column) tones a single count in place: the count is set in the tone over its signed or zero look, and in the tiles layout its tile's border takes the tone too, so a short bill turns red without leaving its row; `neutral` or `null` leaves a count as it is, a row's `tone` still colors only its label, and a `cellTones` that is not one known tone or `null` per column throws. The tone never says why on its own; put that in words beside the grid. Every negative count, signed or not and in either layout, is written with the typographic minus ("−1"), never a hyphen. The primitive does no arithmetic and no currency formatting; tones reuse the Badge vocabulary. Invalid columns, rows, or cells throw.
 
+A strip row with `entry` makes its counts editable: each column holds a `Stepper` (`width="full"`, its label hidden and named by the row label and the column's label and caption as its header reads, such as "Received $20" or "Counted $1 × 100") whose count is the row's `cells` entry (`null` is an empty box). `entry.onChange(columnKey, value)` reports a change; `entry.decrementLabel` and `entry.incrementLabel` name the buttons; `entry.max` caps each column (`null` for none), `entry.errors` puts a message under a column's count (`null` for none), and `entry.placeholder` fills an empty box. The minimum is 0. The grid still does no arithmetic, so recompute the row's `total` in `onChange`. A strip with an entry row centres its heads and read-only counts over the steppers, and each count keeps spacing step 8 of room, so a narrow strip scrolls in its region instead of crushing it. A `cellTones` tone on an entry count draws its border in the tone (danger for a difference); an `accent` tone, for a suggestion or a change, is the `Stepper`'s `changed` look (border and tint); a message in `entry.errors` wins. A row `caption` is a muted line under its label ("from the customer"), and a column `caption` a muted note after its label ("× 100"). Captions show in both layouts. In the strip, `emphasis="quiet"` sets a row on the subtle fill, for a row to compare against, and `disabled` fades a row that does not apply, disables its entry and marks it `aria-disabled`. Entry rows, quiet rows and disabled rows need the `strip` layout. An entry row's counts are zero or more and it is not `signed`; its label is its own among the entry rows, as each column's label and caption are, so every count has its own name. Breaking any of these, a cap or message list that is not one per column, a cap that is not a whole count of zero or more, blank button names or captions, an unknown `emphasis`, or a `disabled` that is not a boolean throws a `RangeError`.
+
+```tsx
+<DenominationGrid
+  label="Tag packs"
+  columns={[
+    { key: 's', label: 'S', caption: '× 10' },
+    { key: 'm', label: 'M' },
+  ]}
+  totalLabel="Total"
+  rows={[
+    {
+      id: 'fitted',
+      label: 'Fitted',
+      caption: 'this morning',
+      cells: fitted,
+      total: `${tags(fitted)} tags`,
+      entry: {
+        onChange: (key, value) => setCount(key, value),
+        decrementLabel: 'One less',
+        incrementLabel: 'One more',
+        max: [6, 4],
+        placeholder: '0',
+      },
+    },
+    { id: 'stock', label: 'In stock', emphasis: 'quiet', cells: [6, 4] },
+  ]}
+/>
+```
+
 `FilterChips` presents a long, wrapping single-choice filter set. Provide a localized group `label`, controlled `value`, `onChange`, and options with stable values and localized labels. An optional non-negative integer `count` renders as a tabular chicklet after the label and is part of the option's accessible name; a zero count quiets the chip until it is selected: it drops its glass fill and sets its label in the muted color (4.5:1 in every palette), without fading, since it can still be chosen. Native radios provide arrow and Space navigation; disabled options are skipped.
 
 `DateField` is a controlled date-only field that draws its own calendar. Supply `value`, `min`, and `max` as valid `YYYY-MM-DD` dates; use an empty `value` for a blank field. Its callback returns a date-only string or an empty string, without timezone conversion. Invalid serialized dates and inverted bounds throw; a value outside the bounds remains visible with invalid styling. `required` marks the label with the same `aria-hidden` asterisk as `Field` and sets the entry's native `required`. Its label is drawn as `Field`'s (the same label words and mark inside a `<label>` that keeps the canvas type), so its label row and its gap to the entry match a `Field` beside it. For a blank required field, supply `error` when form validation runs to show the message and invalid styling.

package/dist/components/ActionBar.d.ts

@@ -1,5 +1,7 @@
 import { type HTMLAttributes, type ReactNode } from 'react';
 import { type Breakpoint } from '../css/breakpoints.js';
+import { type ActionBarSummary } from './action-bar/ActionBarSummary.js';
+export type { ActionBarSummary, ActionBarSummaryTone, } from './action-bar/ActionBarSummary.js';
 export type ActionBarProps = Omit<HTMLAttributes<HTMLDivElement>, 'children'> & {
     /** The actions, usually two or three `Button`s. */
     children: ReactNode;
@@ -13,6 +15,12 @@ export type ActionBarProps = Omit<HTMLAttributes<HTMLDivElement>, 'children'> &
      * and elements in one `span` to keep it wrapping as a sentence.
      */
     status?: ReactNode;
+    /**
+     * A labelled figure before the status, in the same polite live region:
+     * the label, the value large at tabular figures, and a detail, such as
+     * "Counted $33,790.00 short $4,000.00". `tone` colors the value.
+     */
+    summary?: ActionBarSummary;
     /** Sticky only below this breakpoint; from it up the bar sits in page flow. */
     stickyBelow?: Breakpoint;
 };
@@ -35,6 +43,12 @@ export declare const ActionBar: import("react").ForwardRefExoticComponent<Omit<H
      * and elements in one `span` to keep it wrapping as a sentence.
      */
     status?: ReactNode;
+    /**
+     * A labelled figure before the status, in the same polite live region:
+     * the label, the value large at tabular figures, and a detail, such as
+     * "Counted $33,790.00 short $4,000.00". `tone` colors the value.
+     */
+    summary?: ActionBarSummary;
     /** Sticky only below this breakpoint; from it up the bar sits in page flow. */
     stickyBelow?: Breakpoint;
 } & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/ActionBar.js

@@ -2,12 +2,15 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef } from 'react';
 import { cx } from '../class-names.js';
 import { actionBarStickyClass } from '../css/css-action-bar.js';
+import { ActionBarSummaryLine, assertActionBarSummary, } from './action-bar/ActionBarSummary.js';
 /**
  * The actions for a long page on a glass bar that sticks to the bottom of
  * the viewport while the content it follows scrolls by. Place it last in
  * that content: it stays stuck while its parent is on screen and then rests
  * in its own place at the end.
  */
-export const ActionBar = forwardRef(function ActionBar({ children, className, status, stickyBelow, ...rest }, ref) {
-    return (_jsxs("div", { ref: ref, className: cx('sw-action-bar', actionBarStickyClass(stickyBelow), className), ...rest, children: [_jsx("div", { className: "sw-action-bar-status", role: "status", children: status }), _jsx("div", { className: "sw-action-bar-actions", children: children })] }));
+export const ActionBar = forwardRef(function ActionBar({ children, className, status, stickyBelow, summary, ...rest }, ref) {
+    if (summary)
+        assertActionBarSummary(summary);
+    return (_jsxs("div", { ref: ref, className: cx('sw-action-bar', actionBarStickyClass(stickyBelow), className), ...rest, children: [_jsxs("div", { className: "sw-action-bar-status", role: "status", children: [summary ? _jsx(ActionBarSummaryLine, { summary: summary }) : null, status] }), _jsx("div", { className: "sw-action-bar-actions", children: children })] }));
 });

package/dist/components/DenominationGrid.d.ts

@@ -1,3 +1,3 @@
 import { type DenominationGridProps } from './denomination-grid/types.js';
-export type { DenominationGridColumn, DenominationGridLayout, DenominationGridProps, DenominationGridRow, DenominationGridRowRole, DenominationGridTone, DenominationLabelWidth, } from './denomination-grid/types.js';
+export type { DenominationGridColumn, DenominationGridEntry, DenominationGridLayout, DenominationGridProps, DenominationGridRow, DenominationGridRowEmphasis, DenominationGridRowRole, DenominationGridTone, DenominationLabelWidth, } from './denomination-grid/types.js';
 export declare function DenominationGrid({ label, columns, rows, layout, subtotal, zeroLabel, totalLabel, rowRole, labelWidth, }: DenominationGridProps): import("react").JSX.Element;

package/dist/components/DenominationGrid.js

@@ -3,8 +3,11 @@ import { denominationLabelWidths } from '../css/css-denomination-aligned.js';
 import { DenominationStrip } from './denomination-grid/DenominationStrip.js';
 import { DenominationTiles } from './denomination-grid/DenominationTiles.js';
 import { assertDenominationGrid } from './denomination-grid/validate.js';
+import { assertDenominationEntries, assertDenominationExtras, } from './denomination-grid/validate-entry.js';
 export function DenominationGrid({ label, columns, rows, layout = 'strip', subtotal, zeroLabel = '—', totalLabel, rowRole = 'region', labelWidth, }) {
     assertDenominationGrid(label, columns, rows);
+    assertDenominationExtras(layout, columns, rows);
+    assertDenominationEntries(layout, columns, rows);
     if (!zeroLabel)
         throw new RangeError('zeroLabel must not be empty');
     if (totalLabel !== undefined && !totalLabel.trim())

package/dist/components/DescriptionList.d.ts

@@ -0,0 +1,28 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+export type DescriptionListProps = Omit<HTMLAttributes<HTMLDListElement>, 'children'> & {
+    /** The list's `DescriptionItem`s. */
+    children: ReactNode;
+};
+/**
+ * Terms and what each one says, one item per row: the term in a start
+ * column as wide as the widest term (up to 40% of the list), the detail
+ * beside it, a hairline between rows, every row aligned to its top. Below
+ * the layout breakpoint (`md`) each term sits over its detail.
+ */
+export declare function DescriptionList({ children, className, ...rest }: DescriptionListProps): import("react").JSX.Element;
+export type DescriptionItemProps = Omit<HTMLAttributes<HTMLDivElement>, 'children'> & {
+    /**
+     * What the row describes, such as a name; the consumer's own `Text`. Each
+     * child of the term, and of the detail, is its own line.
+     */
+    term: ReactNode;
+    /**
+     * What the term says: text, a link, or several lines. Each child is its
+     * own line, as wide as its content unless it sets its own width (a
+     * `Progress` fills the detail); wrap words and a link that share a line
+     * in one element such as `Inline`.
+     */
+    children: ReactNode;
+};
+/** One row of a `DescriptionList`: a `dt` and its `dd` in one group. */
+export declare function DescriptionItem({ term, children, className, ...rest }: DescriptionItemProps): import("react").JSX.Element;

package/dist/components/DescriptionList.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../class-names.js';
+/**
+ * Terms and what each one says, one item per row: the term in a start
+ * column as wide as the widest term (up to 40% of the list), the detail
+ * beside it, a hairline between rows, every row aligned to its top. Below
+ * the layout breakpoint (`md`) each term sits over its detail.
+ */
+export function DescriptionList({ children, className, ...rest }) {
+    return (_jsx("dl", { className: cx('sw-description-list', className), ...rest, children: children }));
+}
+/** One row of a `DescriptionList`: a `dt` and its `dd` in one group. */
+export function DescriptionItem({ term, children, className, ...rest }) {
+    return (_jsxs("div", { className: cx('sw-description-item', className), ...rest, children: [_jsx("dt", { className: "sw-description-term", children: term }), _jsx("dd", { className: "sw-description-detail", children: children })] }));
+}

package/dist/components/Stepper.d.ts

@@ -0,0 +1,44 @@
+/** `fixed` sizes the count for a few digits; `full` fills its container, such as a table cell. */
+export type StepperWidth = 'fixed' | 'full';
+export type StepperProps = {
+    /** Names the count. Keep it visible unless headers around it say it (`labelVisuallyHidden`). */
+    label: string;
+    labelVisuallyHidden?: boolean;
+    /** The count, or `null` for an empty box (none). */
+    value: number | null;
+    /** A whole count, or `null` when the box is emptied. Typed counts are reported as typed, even outside the bounds. */
+    onChange: (value: number | null) => void;
+    /** The lowest count − reaches; defaults to 0. */
+    min?: number;
+    /** The highest count + reaches; no upper bound when left out. */
+    max?: number;
+    /** How much one press, or one arrow key, moves the count; defaults to 1. */
+    step?: number;
+    /** The − button's name, such as "One less". */
+    decrementLabel: string;
+    /** The + button's name, such as "One more". */
+    incrementLabel: string;
+    /**
+     * A message under the control, as `Field`'s: a polite live region linked by
+     * `aria-describedby`, with `aria-invalid` and the danger border. An empty
+     * string is no error.
+     */
+    error?: string;
+    /** `Field`'s changed look (the accent border and tint) for a count someone changed, or a suggestion. `error` wins. */
+    changed?: boolean;
+    disabled?: boolean;
+    /** Readable and focusable, never changed: the buttons are hidden and keep their room. */
+    readOnly?: boolean;
+    /** Says the count in words for assistive technology (`aria-valuetext`), such as "12 straps". */
+    valueText?: string;
+    /** Shown in an empty box, such as "0". */
+    placeholder?: string;
+    name?: string;
+    width?: StepperWidth;
+};
+/**
+ * A whole-number count between − and + buttons that can also be typed: one
+ * tab stop (the count, a spin button that ArrowUp and ArrowDown step), with
+ * the buttons as pointer targets beside it. − stops at `min`, + at `max`.
+ */
+export declare const Stepper: import("react").ForwardRefExoticComponent<StepperProps & import("react").RefAttributes<HTMLInputElement>>;

package/dist/components/Stepper.js

@@ -0,0 +1,77 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useId, useState, } from 'react';
+import { cx } from '../class-names.js';
+import { assertStepperBounds, readStepperEntry, stepperMoves, stepperText, } from '../stepper-count.js';
+import { FieldErrorRegion } from './FieldErrorRegion.js';
+import { FieldLabelText } from './FieldLabelText.js';
+/** Keeps focus where it was (the count, or nowhere) when a button is pressed. */
+function keepFocus(event) {
+    event.preventDefault();
+}
+/**
+ * A whole-number count between − and + buttons that can also be typed: one
+ * tab stop (the count, a spin button that ArrowUp and ArrowDown step), with
+ * the buttons as pointer targets beside it. − stops at `min`, + at `max`.
+ */
+export const Stepper = forwardRef(function Stepper({ label, labelVisuallyHidden = false, value, onChange, min = 0, max = Number.POSITIVE_INFINITY, step = 1, decrementLabel, incrementLabel, error, changed = false, disabled = false, readOnly = false, valueText, placeholder, name, width = 'fixed', }, ref) {
+    const bounds = { min, max, step };
+    assertStepperBounds(bounds);
+    if (value !== null && !Number.isSafeInteger(value))
+        throw new RangeError('Stepper value must be a whole number or null');
+    const inputId = useId();
+    const labelId = useId();
+    const errorId = useId();
+    const [draft, setDraft] = useState(null);
+    const allowsNegative = min < 0;
+    const moves = stepperMoves(value, bounds, disabled || readOnly);
+    // The typed text stays while it means the count the consumer holds, so
+    // "007" or a lone minus survives a render; otherwise the count's text.
+    const draftEntry = draft === null ? null : readStepperEntry(draft, allowsNegative);
+    const draftShowsValue = draftEntry !== null &&
+        (draftEntry.kind === 'empty'
+            ? value === null
+            : draftEntry.kind === 'count' && draftEntry.value === value);
+    const text = draft !== null && draftShowsValue ? draft : stepperText(value);
+    function move(next) {
+        if (next === null)
+            return;
+        setDraft(null);
+        onChange(next);
+    }
+    function onType(event) {
+        const next = event.target.value;
+        const entry = readStepperEntry(next, allowsNegative);
+        // A refused keystroke changes nothing: the controlled box keeps its text.
+        if (entry.kind === 'refused')
+            return;
+        setDraft(next);
+        const count = entry.kind === 'count' ? entry.value : null;
+        if (count !== value)
+            onChange(count);
+    }
+    /** ArrowUp and ArrowDown step; Home and End go to min and a finite max. */
+    function keyTarget(key) {
+        if (key === 'ArrowUp')
+            return moves.up;
+        if (key === 'ArrowDown')
+            return moves.down;
+        if (key === 'Home')
+            return moves.down === null ? null : min;
+        if (key === 'End' && Number.isFinite(max))
+            return moves.up === null ? null : max;
+        return undefined;
+    }
+    function onKeyDown(event) {
+        const target = keyTarget(event.key);
+        if (target === undefined)
+            return;
+        event.preventDefault();
+        move(target);
+    }
+    const invalid = Boolean(error);
+    return (_jsxs("div", { className: cx('sw-stepper', width === 'full' && 'sw-stepper-full', invalid && 'sw-stepper-invalid', changed && !invalid && 'sw-stepper-changed', readOnly && 'sw-stepper-readonly'), children: [_jsx("label", { className: labelVisuallyHidden ? 'sw-sr-only' : undefined, htmlFor: inputId, id: labelId, children: _jsx(FieldLabelText, { label: label }) }), _jsxs("div", { "aria-labelledby": labelId, className: "sw-stepper-track", role: "group", children: [_jsx("button", { "aria-controls": inputId, "aria-label": decrementLabel, className: "sw-stepper-button", disabled: moves.down === null, onClick: () => move(moves.down), onMouseDown: keepFocus, tabIndex: -1, type: "button", children: _jsx("span", { "aria-hidden": "true", children: '−' }) }), _jsx("input", { ref: ref, "aria-describedby": invalid ? errorId : undefined, "aria-invalid": invalid || undefined, "aria-valuemax": Number.isFinite(max) ? max : undefined, "aria-valuemin": min, "aria-valuenow": value ?? undefined, "aria-valuetext": valueText, autoComplete: "off", className: "sw-stepper-input", disabled: disabled, id: inputId, 
+                        // iOS's numeric pad has no minus key, so a range below zero takes
+                        // the text keyboard.
+                        inputMode: allowsNegative ? 'text' : 'numeric', name: name, onBlur: () => setDraft(null), onChange: onType, onKeyDown: onKeyDown, placeholder: placeholder, readOnly: readOnly, role: "spinbutton", type: "text", value: text }), _jsx("button", { "aria-controls": inputId, "aria-label": incrementLabel, className: "sw-stepper-button", disabled: moves.up === null, onClick: () => move(moves.up), onMouseDown: keepFocus, tabIndex: -1, type: "button", children: _jsx("span", { "aria-hidden": "true", children: "+" }) })] }), _jsx(FieldErrorRegion, { className: "sw-field-error", id: errorId, message: error })] }));
+});

package/dist/components/Steps.d.ts

@@ -0,0 +1,18 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+import { type StepHeadingLevel, type StepsLabels } from './steps/step-status.js';
+export { Step, type StepProps } from './steps/Step.js';
+export type { StepHeadingLevel, StepsLabels, StepStatus, } from './steps/step-status.js';
+export type StepsProps = Omit<HTMLAttributes<HTMLOListElement>, 'children'> & {
+    /** The `Step`s, in order; each is numbered by its place. */
+    children: ReactNode;
+    /** Each step title's heading level; defaults to 2. */
+    headingLevel?: StepHeadingLevel;
+    /** The status words assistive technology hears after a folded step's title. English by default. */
+    labels?: Partial<StepsLabels>;
+};
+/**
+ * A one-page vertical stepper: a form's steps in order, the current one
+ * open, the done ones folded to a line with their summary and Edit, the
+ * ones ahead greyed, a line joining each marker to the next.
+ */
+export declare function Steps({ children, className, headingLevel, labels, ...rest }: StepsProps): import("react").JSX.Element;

package/dist/components/Steps.js

@@ -0,0 +1,34 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Children, Fragment, isValidElement, useRef, } from 'react';
+import { cx } from '../class-names.js';
+import { defaultStepsLabels, stepHeadingLevels, } from './steps/step-status.js';
+import { StepPlaceContext } from './steps/steps-context.js';
+export { Step } from './steps/Step.js';
+function assertSteps(labels, level) {
+    if (Object.values(labels).some((word) => typeof word !== 'string' || !word.trim()))
+        throw new RangeError('Steps labels must not be empty');
+    if (!stepHeadingLevels.includes(level))
+        throw new RangeError('Steps headingLevel must be 2, 3 or 4');
+}
+/**
+ * A one-page vertical stepper: a form's steps in order, the current one
+ * open, the done ones folded to a line with their summary and Edit, the
+ * ones ahead greyed, a line joining each marker to the next.
+ */
+export function Steps({ children, className, headingLevel = 2, labels, ...rest }) {
+    const words = { ...defaultStepsLabels, ...labels };
+    assertSteps(words, headingLevel);
+    const steps = Children.toArray(children).filter(isValidElement);
+    // A Fragment would share one number among its steps: pass them directly.
+    if (steps.some((step) => step.type === Fragment))
+        throw new RangeError('Steps children must be Steps, not a Fragment');
+    // The first step to open in a commit claims focus (see Step).
+    const focusClaimRef = useRef(false);
+    return (_jsx("ol", { className: cx('sw-steps', className), ...rest, children: steps.map((step, index) => (_jsx(StepPlaceContext.Provider, { value: {
+                number: index + 1,
+                headingLevel,
+                labels: words,
+                focusClaimRef,
+            }, children: step }, step.key))) }));
+}

package/dist/components/action-bar/ActionBarSummary.d.ts

@@ -0,0 +1,22 @@
+export declare const actionBarSummaryTones: readonly ["default", "danger", "success"];
+/** The value's color: the text color, or danger (short) or success (matched). */
+export type ActionBarSummaryTone = (typeof actionBarSummaryTones)[number];
+/** A labelled figure for the bar, such as "Counted $33,790.00 short $4,000.00". */
+export type ActionBarSummary = {
+    /** What the figure is, such as "Counted". */
+    label: string;
+    /** The figure, formatted by the consumer, such as "$33,790.00". */
+    value: string;
+    /** A short line after the figure, such as "short $4,000.00". */
+    detail?: string;
+    /** Colors the value only; the words say why. Defaults to `default`. */
+    tone?: ActionBarSummaryTone;
+};
+export declare function assertActionBarSummary(summary: ActionBarSummary): void;
+/**
+ * The bar's figure: its label, the value in the heading variant at tabular
+ * figures, and its detail, on one baseline, wrapping as one phrase.
+ */
+export declare function ActionBarSummaryLine({ summary, }: {
+    summary: ActionBarSummary;
+}): import("react").JSX.Element;

package/dist/components/action-bar/ActionBarSummary.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../../class-names.js';
+export const actionBarSummaryTones = ['default', 'danger', 'success'];
+function isBlank(text) {
+    return typeof text !== 'string' || !text.trim();
+}
+export function assertActionBarSummary(summary) {
+    if (isBlank(summary.label) || isBlank(summary.value))
+        throw new RangeError('ActionBar summary needs a label and a value');
+    if (summary.detail !== undefined && isBlank(summary.detail))
+        throw new RangeError('ActionBar summary detail must not be empty');
+    if (summary.tone !== undefined &&
+        !actionBarSummaryTones.includes(summary.tone))
+        throw new RangeError(`Unknown ActionBar summary tone: ${String(summary.tone)}`);
+}
+/**
+ * The bar's figure: its label, the value in the heading variant at tabular
+ * figures, and its detail, on one baseline, wrapping as one phrase.
+ */
+export function ActionBarSummaryLine({ summary, }) {
+    const tone = summary.tone ?? 'default';
+    return (_jsxs("span", { className: cx('sw-action-bar-summary', tone !== 'default' && `sw-action-bar-summary-${tone}`), children: [_jsx("span", { className: "sw-action-bar-summary-label", children: summary.label }), ' ', _jsx("span", { className: "sw-action-bar-summary-value sw-text-heading sw-tabular", children: summary.value }), summary.detail ? (_jsxs(_Fragment, { children: [' ', _jsx("span", { className: "sw-action-bar-summary-detail", children: summary.detail })] })) : null] }));
+}

package/dist/components/denomination-grid/ColumnHeadText.d.ts

@@ -0,0 +1,7 @@
+import { type DenominationGridColumn } from './types.js';
+/** A column's name as its header reads: the label, then its caption ("$1 × 100"). */
+export declare function columnName(column: DenominationGridColumn): string;
+/** A column's label and, after it, its muted caption ("$1 × 100"). */
+export declare function ColumnHeadText({ column }: {
+    column: DenominationGridColumn;
+}): import("react").JSX.Element;

package/dist/components/denomination-grid/ColumnHeadText.js

@@ -0,0 +1,13 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** A column's name as its header reads: the label, then its caption ("$1 × 100"). */
+export function columnName(column) {
+    return column.caption === undefined
+        ? column.label
+        : `${column.label} ${column.caption}`;
+}
+/** A column's label and, after it, its muted caption ("$1 × 100"). */
+export function ColumnHeadText({ column }) {
+    if (column.caption === undefined)
+        return _jsx(_Fragment, { children: column.label });
+    return (_jsxs(_Fragment, { children: [column.label, ' ', _jsx("span", { className: "sw-denomination-head-caption", children: column.caption })] }));
+}