@scalewing/react 1.53.0 → 1.54.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @scalewing/react
 
+## 1.54.0
+
+### Minor Changes
+
+- 4c2d7cd: `Box` `external` and `newTabLabel` (opt-in, `as="a"` only): a link that opens in a new tab, `target="_blank"` with `noopener noreferrer` added to `rel`, a decorative arrow (↗) after its words drawn with borders in the link's colour, and `newTabLabel` (your words, such as "(opens in a new tab)", required with `external`) read after its name. New class `sw-link-external-mark`. `Stepper` `onCommit` and `commitDelay` (opt-in): the finished count once per entry, on blur, on Enter and `commitDelay` ms (default 600) after the last − / + press or step key, never per typed digit and never for an unchanged count; `onChange` is unchanged. Requests: `docs/requests/futmas-external-link.md`, `docs/requests/futmas-stepper-commit.md`.
+
 ## 1.53.0
 
 ### Minor Changes

package/README.md

@@ -106,7 +106,7 @@ Import the CSS once at the application entry. Do not copy it into your source tr
 
 `AppHeader` is the page's top chrome, sticky by default (`sticky={false}` leaves it in flow). Its default `appearance="glass"` is a rounded frosted card. `appearance="bar"` (`AppHeaderAppearance`, `appHeaderAppearances`) is a full-width band of the solid surface with the border hairline under it: no blur, no rounding, no side or top border, the same under Reduce Transparency, and the hairline kept in forced colors. Set it against the page's edges (no side gutter round it) and put the gutter inside it. A `ref` reaches its `header` element. An unknown `appearance` throws a `RangeError`.
 
-`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. `Box as="a" link="quiet"` (opt-in; `link="accent"`, the default, is the canvas link) is a title that opens something, such as a table row's title: it keeps the surrounding text's colour at weight 600 (`sw-link-quiet`) and is underlined on hover and keyboard focus. Its weight is the non-colour cue WCAG 1.4.1 asks for (axe's `link-in-text-block` passes it on colour, the same colour and background as its text, or on its weight; the weight is what keeps it visibly a link), so use it in text lighter than 600. In text already at 600 the quiet look has no cue: an accent link there needs at least 3:1 contrast against the text. `link` on a box that is not `as="a"` throws a `TypeError`, an unknown value a `RangeError`. `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): its name is one visually hidden line, the title, a comma and the word ("The site, Done"), and the drawn title is `aria-hidden`, because a browser lays a hidden box out as a block and would put a space before the comma ("The site , Done"). The step's region and its Edit button are still named by the drawn title. A current step, and a skipped step showing its reason, draw and read their words as they are. The heading's text content now holds the title twice (drawn, then in the spoken line), so a test reading a folded heading's `textContent` or finding its title with a pattern (`getByText(/The site/)`) finds both: query headings by role and name (`getByRole('heading', { name: 'The site, Done' })`). Copying a folded heading, or finding its title in the page, meets the words twice too. The comma after the title is Scalewing's, as before; the word is yours. 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. `Steps open` (off by default) keeps every step open at once, for a form whose sections are all filled on one page: each step shows its `children` whatever its status, inside a `section` named by its title (a region, class `sw-steps-region`), every title at the open size; the marker still follows the status (a number to fill, a check when done, "!" in error, a grey ring and muted title when greyed, such as after a blocking step), no step is `aria-current`, and no step takes focus when its status changes. `titleDetail` (opt-in) is muted words after an open step's title, on its line, such as "Optional" on a step a person may skip, or "Wetlands done · Woodlands empty" on a step with a part per habitat: the label size at the body's weight in the muted colour, a space-2 after the title on its baseline, or on a line of their own under the title where they do not fit beside it (a long title on a phone), never past the panel (a long word breaks). They are drawn while the step is open (current or error, or every step of an open list, with fields or without) and stay as the step turns done in an open list; a folded step draws its summary or reason instead. They sit outside the heading, so the heading's name stays the title (and its status word) and a heading list reads the titles alone; an open list's region keeps the title as its name and is described by the words, read as a person enters it, and in a stepped list they follow the heading in reading order. Write your own separators inside the words; Scalewing draws only the gap after the title. The words share a skipped step's reason's muted colour, not its size: a reason is part of the title, these are a note beside it. Give a step its `titleDetail` from its first render: setting or clearing it later moves the heading into or out of the title line, which remounts it (and drops its focus if it has it). A blank `titleDetail` throws a `RangeError`. 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`.
+`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. `Box as="a" link="quiet"` (opt-in; `link="accent"`, the default, is the canvas link) is a title that opens something, such as a table row's title: it keeps the surrounding text's colour at weight 600 (`sw-link-quiet`) and is underlined on hover and keyboard focus. Its weight is the non-colour cue WCAG 1.4.1 asks for (axe's `link-in-text-block` passes it on colour, the same colour and background as its text, or on its weight; the weight is what keeps it visibly a link), so use it in text lighter than 600. In text already at 600 the quiet look has no cue: an accent link there needs at least 3:1 contrast against the text. `link` on a box that is not `as="a"` throws a `TypeError`, an unknown value a `RangeError`. `Box as="a" external` (opt-in) opens the address in a new tab: it sets `target="_blank"` (always), adds `noopener noreferrer` to your `rel` words (each once), draws a decorative arrow (↗, `sw-link-external-mark`, `aria-hidden`) right after the words with no space, so it never wraps alone, and reads `newTabLabel` after the link's name from a visually hidden span ("Check the marsh map (opens in a new tab)"). The arrow is drawn with borders in the link's colour (accent, the hover colour, a quiet link's), so forced colours keep it, and is mirrored in right-to-left text. `newTabLabel` is your words in your language; it is required with `external` (blank throws a `RangeError`) and refused without it (`TypeError`); `external` on a box that is not `as="a"` throws a `TypeError`. `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): its name is one visually hidden line, the title, a comma and the word ("The site, Done"), and the drawn title is `aria-hidden`, because a browser lays a hidden box out as a block and would put a space before the comma ("The site , Done"). The step's region and its Edit button are still named by the drawn title. A current step, and a skipped step showing its reason, draw and read their words as they are. The heading's text content now holds the title twice (drawn, then in the spoken line), so a test reading a folded heading's `textContent` or finding its title with a pattern (`getByText(/The site/)`) finds both: query headings by role and name (`getByRole('heading', { name: 'The site, Done' })`). Copying a folded heading, or finding its title in the page, meets the words twice too. The comma after the title is Scalewing's, as before; the word is yours. 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. `Steps open` (off by default) keeps every step open at once, for a form whose sections are all filled on one page: each step shows its `children` whatever its status, inside a `section` named by its title (a region, class `sw-steps-region`), every title at the open size; the marker still follows the status (a number to fill, a check when done, "!" in error, a grey ring and muted title when greyed, such as after a blocking step), no step is `aria-current`, and no step takes focus when its status changes. `titleDetail` (opt-in) is muted words after an open step's title, on its line, such as "Optional" on a step a person may skip, or "Wetlands done · Woodlands empty" on a step with a part per habitat: the label size at the body's weight in the muted colour, a space-2 after the title on its baseline, or on a line of their own under the title where they do not fit beside it (a long title on a phone), never past the panel (a long word breaks). They are drawn while the step is open (current or error, or every step of an open list, with fields or without) and stay as the step turns done in an open list; a folded step draws its summary or reason instead. They sit outside the heading, so the heading's name stays the title (and its status word) and a heading list reads the titles alone; an open list's region keeps the title as its name and is described by the words, read as a person enters it, and in a stepped list they follow the heading in reading order. Write your own separators inside the words; Scalewing draws only the gap after the title. The words share a skipped step's reason's muted colour, not its size: a reason is part of the title, these are a note beside it. Give a step its `titleDetail` from its first render: setting or clearing it later moves the heading into or out of the title line, which remounts it (and drops its focus if it has it). A blank `titleDetail` throws a `RangeError`. 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">
@@ -257,6 +257,8 @@ A chosen photo can show itself: `value.preview` is the address of a small image
 
 `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. `aria-describedby` takes ids of elements that describe the count, such as the value it adds up to, read before an `error`'s message. `changed` takes `Field`'s changed look; `readOnly` keeps the count focusable and hides the buttons in their own room; `disabled` stops all three. `limitAppearance="plain"` (default `"faded"`) keeps − at `min` and + at `max` in their usual look instead of faded, for a count sheet where a faded − reads as broken; they are still disabled, a disabled or read-only Stepper is unchanged, forced colors still grey them, and an unknown value throws a `RangeError`. The count is a few digits wide and keeps that width (`width="fixed"`), or fills its container (`width="full"`, for a table cell). `unit` (opt-in) is a short muted word after the count inside its frame, such as "min" or "players": the frame (`sw-stepper-count`) draws the control surface, focus ring and the invalid, changed and disabled states, a press on the word focuses the count, and the count keeps its few-digit width with its digits against the word, so the frame never follows it. The word (`sw-stepper-unit`) is hidden from assistive technology; the count is read with it (`aria-valuetext` "90 min", none while the box is empty), and a `valueText` you pass wins. The default joins the count and the word as given, so a word that changes with the count ("players") reads "1 players": pass `valueText` in your language's right form ("1 player", "11 players"). A blank `unit` throws a `RangeError`. Bounds that are not whole numbers, `min` above `max`, or a `step` that is not above zero throw a `RangeError`.
 
+`Stepper` `onCommit` (opt-in) is the finished count once per entry, for a page that saves as you go: it fires on blur, on Enter (a form round the count still submits), and `commitDelay` ms (default 600) after the last − / + press or step key (ArrowUp, ArrowDown, Home, End), each press restarting the wait; blur or Enter while it waits commits at once. Typed digits never commit by themselves. It gives the count you hold at that moment, `null` or outside the bounds included as `onChange` reports them, so check it before saving. It does not fire when that count is the one last committed, or, before the first commit, the one held before the first edit; a count you set while nothing waits (a server's answer) becomes the new baseline. A commit still waiting when the Stepper unmounts is made then. `onChange` is unchanged. A `commitDelay` that is negative or not finite throws a `RangeError`.
+
 ```tsx
 <Stepper
   label="Herons"

package/dist/components/Box.d.ts

@@ -24,6 +24,19 @@ export type BoxProps = SpacingProps & VisibilityProps & ColumnSpanProps & HTMLAt
      * text lighter than 600. Only for `as="a"`; an unknown value throws.
      */
     link?: BoxLink;
+    /**
+     * A `Box as="a"` that opens in a new tab: it sets `target="_blank"`,
+     * adds `noopener noreferrer` to `rel`, draws a decorative arrow (↗)
+     * after its words and reads `newTabLabel` after its name. Only for
+     * `as="a"`; it needs `newTabLabel`.
+     */
+    external?: boolean;
+    /**
+     * The hidden words read after an external link's name, in your
+     * language, such as "(opens in a new tab)". Required with `external`,
+     * refused without it.
+     */
+    newTabLabel?: string;
 };
 export type BoxBorder = BoxBorderValue;
 export type BoxLink = BoxLinkAppearance;
@@ -45,4 +58,17 @@ export declare const Box: import("react").ForwardRefExoticComponent<SpacingProps
      * text lighter than 600. Only for `as="a"`; an unknown value throws.
      */
     link?: BoxLink;
+    /**
+     * A `Box as="a"` that opens in a new tab: it sets `target="_blank"`,
+     * adds `noopener noreferrer` to `rel`, draws a decorative arrow (↗)
+     * after its words and reads `newTabLabel` after its name. Only for
+     * `as="a"`; it needs `newTabLabel`.
+     */
+    external?: boolean;
+    /**
+     * The hidden words read after an external link's name, in your
+     * language, such as "(opens in a new tab)". Required with `external`,
+     * refused without it.
+     */
+    newTabLabel?: string;
 } & import("react").RefAttributes<HTMLElement>>;

package/dist/components/Box.js

@@ -5,10 +5,14 @@ import { boxBorderClass } from '../css/css-box-border.js';
 import { assertBoxLink, boxLinkClass, } from '../css/css-box-link.js';
 import { columnSpanClassNames, } from '../column-span-classes.js';
 import { spacingClassNames } from '../spacing-classes.js';
+import { assertBoxExternal, externalLinkContent, externalLinkRel, } from './box/external-link.js';
 import { tabStop } from '../tab-stop.js';
 import { visibilityClassNames, } from '../visibility-classes.js';
-export const Box = forwardRef(function Box({ as = 'div', background, border, className, columnSpan, hideBelow, hideFrom, link, padding, paddingBottom, paddingLeft, paddingRight, paddingTop, paddingX, paddingY, radius, style, tabIndex, ...rest }, ref) {
+export const Box = forwardRef(function Box({ as = 'div', background, border, children, className, columnSpan, external, hideBelow, hideFrom, link, newTabLabel, padding, paddingBottom, paddingLeft, paddingRight, paddingTop, paddingX, paddingY, radius, rel, style, tabIndex, target, ...rest }, ref) {
     assertBoxLink(link, as);
+    assertBoxExternal({ as, external, newTabLabel });
+    // assertBoxExternal has made sure an external link has its words.
+    const opensNewTab = external === true && newTabLabel !== undefined;
     const Component = as;
     // A link with a destination is a tab stop in Safari too (see tabStop).
     const linkTabStop = as === 'a' && rest.href !== undefined ? tabStop : undefined;
@@ -26,5 +30,5 @@ export const Box = forwardRef(function Box({ as = 'div', background, border, cla
                 : undefined,
             borderRadius: radius ? `var(--sw-radius-${radius})` : undefined,
             ...style,
-        }, tabIndex: tabIndex ?? linkTabStop, ...rest }));
+        }, tabIndex: tabIndex ?? linkTabStop, ...rest, rel: opensNewTab ? externalLinkRel(rel) : rel, target: opensNewTab ? '_blank' : target, children: opensNewTab ? externalLinkContent(children, newTabLabel) : children }));
 });

package/dist/components/Stepper.d.ts

@@ -1,69 +1,5 @@
-/** `fixed` sizes the count for a few digits; `full` fills its container, such as a table cell. */
-export type StepperWidth = 'fixed' | 'full';
-export declare const stepperLimitAppearances: readonly ["faded", "plain"];
-/**
- * How − looks at `min` and + at `max`, where a press cannot move the count:
- * `faded` (the default) fades the button as any disabled control; `plain`
- * keeps its usual look. Either way the button is disabled.
- */
-export type StepperLimitAppearance = (typeof stepperLimitAppearances)[number];
-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". It wins over the count and `unit` read together.
-     */
-    valueText?: string;
-    /**
-     * A short muted word after the count, inside its frame, such as "min".
-     * Without `valueText` the count is read with it ("90 min"), word for
-     * word: a unit that changes with the count ("players") reads "1 players",
-     * so pass `valueText` with the right form ("1 player"). Not blank.
-     */
-    unit?: string;
-    /**
-     * Ids of elements that describe the count, such as the value it adds up
-     * to; read before an `error`'s message.
-     */
-    'aria-describedby'?: string;
-    /** Shown in an empty box, such as "0". */
-    placeholder?: string;
-    name?: string;
-    width?: StepperWidth;
-    /**
-     * `plain` keeps − at `min` and + at `max` in their usual look instead of
-     * fading them (`faded`, the default). The button is still disabled, and a
-     * disabled or read-only Stepper is unchanged.
-     */
-    limitAppearance?: StepperLimitAppearance;
-};
+import { type StepperProps } from './stepper/stepper-props.js';
+export { stepperLimitAppearances, type StepperLimitAppearance, type StepperProps, type StepperWidth, } from './stepper/stepper-props.js';
 /**
  * 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

package/dist/components/Stepper.js

@@ -6,7 +6,9 @@ import { assertStepperBounds, assertStepperUnit, readStepperEntry, stepperMoves,
 import { FieldErrorRegion } from './FieldErrorRegion.js';
 import { FieldLabelText } from './FieldLabelText.js';
 import { StepperCountFrame } from './stepper/StepperCountFrame.js';
-export const stepperLimitAppearances = ['faded', 'plain'];
+import { stepperLimitAppearances, } from './stepper/stepper-props.js';
+import { assertStepperCommitDelay, defaultStepperCommitDelay, useStepperCommit, } from './stepper/use-stepper-commit.js';
+export { stepperLimitAppearances, } from './stepper/stepper-props.js';
 /** Keeps focus where it was (the count, or nowhere) when a button is pressed. */
 function keepFocus(event) {
     event.preventDefault();
@@ -16,10 +18,11 @@ function keepFocus(event) {
  * 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, unit, 'aria-describedby': describedBy, placeholder, name, width = 'fixed', limitAppearance = 'faded', }, ref) {
+export const Stepper = forwardRef(function Stepper({ label, labelVisuallyHidden = false, value, onChange, onCommit, commitDelay = defaultStepperCommitDelay, min = 0, max = Number.POSITIVE_INFINITY, step = 1, decrementLabel, incrementLabel, error, changed = false, disabled = false, readOnly = false, valueText, unit, 'aria-describedby': describedBy, placeholder, name, width = 'fixed', limitAppearance = 'faded', }, ref) {
     const bounds = { min, max, step };
     assertStepperBounds(bounds);
     assertStepperUnit(unit);
+    assertStepperCommitDelay(commitDelay);
     if (!stepperLimitAppearances.includes(limitAppearance))
         throw new RangeError(`Unknown Stepper limitAppearance: ${String(limitAppearance)}`);
     if (value !== null && !Number.isSafeInteger(value))
@@ -28,6 +31,7 @@ export const Stepper = forwardRef(function Stepper({ label, labelVisuallyHidden
     const labelId = useId();
     const errorId = useId();
     const [draft, setDraft] = useState(null);
+    const commit = useStepperCommit(value, onCommit, commitDelay);
     const allowsNegative = min < 0;
     const moves = stepperMoves(value, bounds, disabled || readOnly);
     // The typed text stays while it means the count the consumer holds, so
@@ -42,6 +46,7 @@ export const Stepper = forwardRef(function Stepper({ label, labelVisuallyHidden
         if (next === null)
             return;
         setDraft(null);
+        commit.stepped();
         onChange(next);
     }
     function onType(event) {
@@ -52,8 +57,10 @@ export const Stepper = forwardRef(function Stepper({ label, labelVisuallyHidden
             return;
         setDraft(next);
         const count = entry.kind === 'count' ? entry.value : null;
-        if (count !== value)
-            onChange(count);
+        if (count === value)
+            return;
+        commit.edited();
+        onChange(count);
     }
     /** ArrowUp and ArrowDown step; Home and End go to min and a finite max. */
     function keyTarget(key) {
@@ -68,6 +75,9 @@ export const Stepper = forwardRef(function Stepper({ label, labelVisuallyHidden
         return undefined;
     }
     function onKeyDown(event) {
+        // Enter finishes the entry; a form round the count still submits.
+        if (event.key === 'Enter')
+            commit.finish();
         const target = keyTarget(event.key);
         if (target === undefined)
             return;
@@ -83,5 +93,8 @@ export const Stepper = forwardRef(function Stepper({ label, labelVisuallyHidden
                                 .join(' ') || undefined, "aria-invalid": invalid || undefined, "aria-valuemax": Number.isFinite(max) ? max : undefined, "aria-valuemin": min, "aria-valuenow": value ?? undefined, "aria-valuetext": stepperValueText(value, unit, 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 })] }));
+                            inputMode: allowsNegative ? 'text' : 'numeric', name: name, onBlur: () => {
+                                setDraft(null);
+                                commit.finish();
+                            }, 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/box/external-link.d.ts

@@ -0,0 +1,20 @@
+import { type ReactNode } from 'react';
+/** What a `Box` passes to check and draw its external link. */
+export type BoxExternalOptions = {
+    as: string;
+    external: boolean | undefined;
+    newTabLabel: string | undefined;
+};
+/**
+ * Refuses an external box that is not a link or has no words for its new
+ * tab, and new-tab words on a box that is not external.
+ */
+export declare function assertBoxExternal({ as, external, newTabLabel, }: BoxExternalOptions): void;
+/** The consumer's `rel` words with `noopener noreferrer`, each once. */
+export declare function externalLinkRel(rel: string | undefined): string;
+/**
+ * An external link's content: its words, the decorative new-tab mark
+ * right after them (no space, so it never wraps alone) and the hidden
+ * words read after the name, such as "(opens in a new tab)".
+ */
+export declare function externalLinkContent(children: ReactNode, newTabLabel: string): ReactNode;

package/dist/components/box/external-link.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { externalLinkMarkClass } from '../../css/css-box-link.js';
+/** The `rel` words a link that opens a new tab always carries. */
+const newTabRelWords = ['noopener', 'noreferrer'];
+/**
+ * Refuses an external box that is not a link or has no words for its new
+ * tab, and new-tab words on a box that is not external.
+ */
+export function assertBoxExternal({ as, external, newTabLabel, }) {
+    if (external === undefined || external === false) {
+        if (newTabLabel !== undefined)
+            throw new TypeError('Box newTabLabel is for an external link');
+        return;
+    }
+    if (external !== true)
+        throw new RangeError('Box external must be a boolean');
+    if (as !== 'a')
+        throw new TypeError('Box external is for a link (as="a")');
+    if (typeof newTabLabel !== 'string' || newTabLabel.trim() === '')
+        throw new RangeError('Box external needs a non-empty newTabLabel');
+}
+/** The consumer's `rel` words with `noopener noreferrer`, each once. */
+export function externalLinkRel(rel) {
+    const words = (rel ?? '').split(/\s+/).filter((word) => word !== '');
+    for (const word of newTabRelWords)
+        if (!words.includes(word))
+            words.push(word);
+    return words.join(' ');
+}
+/**
+ * An external link's content: its words, the decorative new-tab mark
+ * right after them (no space, so it never wraps alone) and the hidden
+ * words read after the name, such as "(opens in a new tab)".
+ */
+export function externalLinkContent(children, newTabLabel) {
+    return (_jsxs(_Fragment, { children: [children, _jsx("span", { "aria-hidden": "true", className: externalLinkMarkClass }), _jsxs("span", { className: "sw-sr-only", children: [" ", newTabLabel] })] }));
+}

package/dist/components/stepper/stepper-props.d.ts

@@ -0,0 +1,78 @@
+/** `fixed` sizes the count for a few digits; `full` fills its container, such as a table cell. */
+export type StepperWidth = 'fixed' | 'full';
+export declare const stepperLimitAppearances: readonly ["faded", "plain"];
+/**
+ * How − looks at `min` and + at `max`, where a press cannot move the count:
+ * `faded` (the default) fades the button as any disabled control; `plain`
+ * keeps its usual look. Either way the button is disabled.
+ */
+export type StepperLimitAppearance = (typeof stepperLimitAppearances)[number];
+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 finished count, once per entry, for a page that saves as you go:
+     * on blur, on Enter, and `commitDelay` ms after the last − / + press or
+     * step key (ArrowUp, ArrowDown, Home, End). Never per typed digit, and
+     * never when the count is the one last committed (or held before the
+     * first edit). It gives the count you hold then, `null` or outside the
+     * bounds included, as `onChange` reports typed counts. `onChange` is
+     * unchanged.
+     */
+    onCommit?: (value: number | null) => void;
+    /** How long − / + presses and step keys settle before `onCommit`, in ms; defaults to 600. */
+    commitDelay?: number;
+    /** 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". It wins over the count and `unit` read together.
+     */
+    valueText?: string;
+    /**
+     * A short muted word after the count, inside its frame, such as "min".
+     * Without `valueText` the count is read with it ("90 min"), word for
+     * word: a unit that changes with the count ("players") reads "1 players",
+     * so pass `valueText` with the right form ("1 player"). Not blank.
+     */
+    unit?: string;
+    /**
+     * Ids of elements that describe the count, such as the value it adds up
+     * to; read before an `error`'s message.
+     */
+    'aria-describedby'?: string;
+    /** Shown in an empty box, such as "0". */
+    placeholder?: string;
+    name?: string;
+    width?: StepperWidth;
+    /**
+     * `plain` keeps − at `min` and + at `max` in their usual look instead of
+     * fading them (`faded`, the default). The button is still disabled, and a
+     * disabled or read-only Stepper is unchanged.
+     */
+    limitAppearance?: StepperLimitAppearance;
+};

package/dist/components/stepper/stepper-props.js

@@ -0,0 +1 @@
+export const stepperLimitAppearances = ['faded', 'plain'];

package/dist/components/stepper/use-stepper-commit.d.ts

@@ -0,0 +1,22 @@
+/** How long after the last − / + press or arrow key a count commits, in ms. */
+export declare const defaultStepperCommitDelay = 600;
+/** Refuses a commit delay that is not a finite number of zero or more ms. */
+export declare function assertStepperCommitDelay(delay: number): void;
+/** What a Stepper calls as its count is edited and finished. */
+export type StepperCommit = {
+    /** A typed change: it waits for blur or Enter. */
+    edited: () => void;
+    /** A − / + press or a step key: it commits once the presses settle. */
+    stepped: () => void;
+    /** Blur or Enter: commits now. */
+    finish: () => void;
+};
+/**
+ * Turns a Stepper's edits into one `onCommit` per finished entry: on blur,
+ * on Enter, and `delay` ms after the last − / + press or step key. A
+ * commit gives the count the consumer holds then, and only when it differs
+ * from the last committed count (or the count before the first edit). A
+ * count the consumer changes while nothing is waiting becomes the new
+ * baseline. A commit still waiting when the Stepper unmounts is made then.
+ */
+export declare function useStepperCommit(value: number | null, onCommit: ((value: number | null) => void) | undefined, delay: number): StepperCommit;

package/dist/components/stepper/use-stepper-commit.js

@@ -0,0 +1,66 @@
+import { useEffect, useRef } from 'react';
+/** How long after the last − / + press or arrow key a count commits, in ms. */
+export const defaultStepperCommitDelay = 600;
+/** Refuses a commit delay that is not a finite number of zero or more ms. */
+export function assertStepperCommitDelay(delay) {
+    if (!Number.isFinite(delay) || delay < 0)
+        throw new RangeError('Stepper commitDelay must be a finite number of zero or more');
+}
+/**
+ * Turns a Stepper's edits into one `onCommit` per finished entry: on blur,
+ * on Enter, and `delay` ms after the last − / + press or step key. A
+ * commit gives the count the consumer holds then, and only when it differs
+ * from the last committed count (or the count before the first edit). A
+ * count the consumer changes while nothing is waiting becomes the new
+ * baseline. A commit still waiting when the Stepper unmounts is made then.
+ */
+export function useStepperCommit(value, onCommit, delay) {
+    const latest = useRef({ value, onCommit });
+    const baseline = useRef(value);
+    const pending = useRef(false);
+    const timer = useRef(null);
+    useEffect(() => {
+        latest.current = { value, onCommit };
+        if (!pending.current)
+            baseline.current = value;
+    }, [value, onCommit]);
+    function clearTimer() {
+        if (timer.current === null)
+            return;
+        clearTimeout(timer.current);
+        timer.current = null;
+    }
+    function finish() {
+        clearTimer();
+        if (!pending.current)
+            return;
+        pending.current = false;
+        const { value: current, onCommit: commit } = latest.current;
+        if (current === baseline.current)
+            return;
+        baseline.current = current;
+        commit?.(current);
+    }
+    // The latest finish, for the timer and the unmount to call.
+    const finishRef = useRef(finish);
+    useEffect(() => {
+        finishRef.current = finish;
+    });
+    useEffect(() => () => finishRef.current(), []);
+    function edited() {
+        if (latest.current.onCommit === undefined)
+            return;
+        pending.current = true;
+    }
+    function stepped() {
+        if (latest.current.onCommit === undefined)
+            return;
+        pending.current = true;
+        clearTimer();
+        timer.current = setTimeout(() => {
+            timer.current = null;
+            finishRef.current();
+        }, delay);
+    }
+    return { edited, stepped, finish };
+}

package/dist/css/css-box-link.d.ts

@@ -6,8 +6,11 @@
  */
 export declare const boxLinkAppearances: readonly ["accent", "quiet"];
 export type BoxLinkAppearance = (typeof boxLinkAppearances)[number];
+/** The decorative new-tab mark after an external link's words. */
+export declare const externalLinkMarkClass = "sw-link-external-mark";
 export declare function assertBoxLink(link: unknown, as: string): void;
 /** The generated class for a Box `link` prop, or none for the canvas link. */
 export declare function boxLinkClass(link: BoxLinkAppearance | undefined): string | undefined;
 export declare function cssBoxLinkClasses(): string;
+export declare function cssExternalLinkMarkClasses(): string;
 export declare function boxLinkClassCatalog(): string[];

package/dist/css/css-box-link.js

@@ -7,6 +7,8 @@ import { typographyVariants } from '@scalewing/tokens';
  */
 export const boxLinkAppearances = ['accent', 'quiet'];
 const quietLinkClass = 'sw-link-quiet';
+/** The decorative new-tab mark after an external link's words. */
+export const externalLinkMarkClass = 'sw-link-external-mark';
 export function assertBoxLink(link, as) {
     if (link === undefined)
         return;
@@ -43,8 +45,45 @@ ${quiet}:hover,
 ${quiet}:focus-visible {
   color: inherit;
   text-decoration-line: underline;
-}`;
+}
+
+${cssExternalLinkMarkClasses()}`;
+}
+/*
+ * An external link's new-tab mark: an arrow to the inline end and up (↗),
+ * drawn with borders in the link's colour so forced colours keep it as the
+ * system link colour. Its head is the top and inline-end borders of a
+ * space-2 square; its shaft is one border on the square's diagonal. It
+ * follows the link's colour (accent, the hover text colour, a quiet link's
+ * inherited one) and is mirrored in right-to-left text. It sits a space-1
+ * after the last word with no space between them, so it never wraps alone.
+ */
+export function cssExternalLinkMarkClasses() {
+    const mark = `.${externalLinkMarkClass}`;
+    return `${mark} {
+  border-right: 2px solid currentColor;
+  border-top: 2px solid currentColor;
+  box-sizing: border-box;
+  display: inline-block;
+  height: var(--sw-space-2);
+  margin-inline-start: var(--sw-space-1);
+  position: relative;
+  vertical-align: middle;
+  width: var(--sw-space-2);
+}
+
+${mark}::after {
+  border-left: 2px solid currentColor;
+  content: '';
+  height: calc(var(--sw-space-2) * 1.25);
+  left: 50%;
+  position: absolute;
+  top: 50%;
+  transform: translate(-50%, -50%) rotate(45deg);
+}
+
+${mark}:dir(rtl) { transform: scaleX(-1); }`;
 }
 export function boxLinkClassCatalog() {
-    return [quietLinkClass];
+    return [quietLinkClass, externalLinkMarkClass];
 }

package/dist/styles.css

@@ -666,6 +666,30 @@ body {
   text-decoration-line: underline;
 }
 
+.sw-link-external-mark {
+  border-right: 2px solid currentColor;
+  border-top: 2px solid currentColor;
+  box-sizing: border-box;
+  display: inline-block;
+  height: var(--sw-space-2);
+  margin-inline-start: var(--sw-space-1);
+  position: relative;
+  vertical-align: middle;
+  width: var(--sw-space-2);
+}
+
+.sw-link-external-mark::after {
+  border-left: 2px solid currentColor;
+  content: '';
+  height: calc(var(--sw-space-2) * 1.25);
+  left: 50%;
+  position: absolute;
+  top: 50%;
+  transform: translate(-50%, -50%) rotate(45deg);
+}
+
+.sw-link-external-mark:dir(rtl) { transform: scaleX(-1); }
+
 /*
  * A programmatic focus target (tabindex="-1": a notice, a card or a heading
  * that a script focuses after a save) takes the accent ring past the ring

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalewing/react",
-  "version": "1.53.0",
+  "version": "1.54.0",
   "description": "Scalewing DOM components and package-owned CSS utilities.",
   "type": "module",
   "license": "MIT",