@scalewing/react 1.57.0 → 1.58.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @scalewing/react
 
+## 1.58.0
+
+### Minor Changes
+
+- cf53284: `Field` `descriptionTone` (opt-in, `FieldDescriptionTone`, `fieldDescriptionTones`: `'muted'` default, `'warning'`): a warning description in the warning colour after a small `aria-hidden` alert glyph, for a hint that needs the person but is not an error; it stays in the control's `aria-describedby`, sets no `aria-invalid` and no danger border, gives way to `error`, and takes `CanvasText` in forced colors. `FixtureGroup` `titleHidden` (opt-in): the title still names the list (`aria-labelledby`) but is not drawn, for a group whose heading is already on screen. `Text` `font` (opt-in, `TextFont`, `textFonts`: `'sans'` default, `'mono'`): the platform's monospace face through the generated `sw-font-mono` class at the variant's size, weight and colour, for a code read character by character. Unknown tones and fonts throw a `RangeError`. New classes `sw-field-description-warning`, `sw-field-description-glyph`. `FieldProps` now lives in `components/field/field-props.ts` and is still exported from the package root.
+
 ## 1.57.0
 
 ### Minor Changes

package/README.md

@@ -189,6 +189,21 @@ Import the CSS once at the application entry. Do not copy it into your source tr
 </Field>
 ```
 
+`Field` `descriptionTone="warning"` (default `"muted"`; `fieldDescriptionTones`, `FieldDescriptionTone`) draws the `description` in the warning colour (`--sw-color-warning`, 4.5:1 on the canvas in both schemes) after a small alert glyph a space-4 square (private chrome, `aria-hidden`, centred on its first line), for a hint that needs the person but is not an error, such as a number another row already has. It stays the control's description (`aria-describedby`, after any ids the control already lists) and sets no invalid state: no `aria-invalid`, no danger border, nothing announced. `error` still replaces it on screen, and is the only way to mark the field invalid. In forced colors the words and glyph take `CanvasText` (an error takes `Mark`), so the glyph is the cue. It works at every `size`, including `xs` in a table cell. An unknown tone throws a `RangeError`. New classes `sw-field-description-warning`, `sw-field-description-glyph`.
+
+```tsx
+<Field
+  description={twin ? `${twin} also wears ${band}` : undefined}
+  descriptionTone="warning"
+  label={`Band number for ${bird}`}
+  labelVisuallyHidden
+  size="xs"
+  width="xs"
+>
+  <input inputMode="numeric" value={band} onChange={setBand} />
+</Field>
+```
+
 Every press control and link takes an explicit `tabindex="0"`: `Button` (and the controls built on it, `CalendarButton` and `InfoTip`), `CommandPaletteTrigger`, `Box as="a"` with an `href`, `SectionNav` links, a link or button `FixtureRow`, `AppShell` links and its menu and close buttons, the `Select`, `MultiSelect`, `ActionMenu` and `ContextSwitcher` triggers, `CommandPaletteTrigger` (and a `ContextSwitcher`'s listbox while it holds focus), `SegmentedControl` items (every item, as outside Safari: its arrow keys change the value, not the focus, so it is not a roving group), `DateField`'s calendar button and month steps, a search `Field`'s clear button, a `Table`'s sort and `TableCell onPress` buttons, `Checkbox`, `Switch`, and the checked radio of a `RadioGroup` or `FilterChips` (the first enabled one while none is; the others keep no `tabindex`, so each browser's arrow-key group rule stands). Safari's default (its "Press Tab to highlight each item" setting off) leaves a button, a link, a checkbox and a radio out of the Tab order unless it carries one, so a Safari user would Tab past them; the explicit `0` gives them the order every other browser already does. A `tabIndex` you pass wins, and controls that are deliberately no tab stop keep their `-1`: a `Stepper`'s − and +, and a roving item (a `Tabs` tab, a menu item, a calendar day, a `DateToggleCalendar` day, a `ScheduleGrid` cell) other than the current one. A `<summary>` is already in Safari's order and takes none.
 
 An element a script focuses, such as a notice or a card announced after a save, takes the same accent focus ring as the canvas's links and native controls, 2 px past its edge (`--sw-focus-ring-width` and `--sw-focus-ring-offset`), instead of the browser's outline. Give it `tabIndex={-1}`, so it takes focus from a script but is no tab stop, and put the focus on the whole card rather than its text, so the ring goes round it clear of the words; a `Box` round the card with the card's `radius` makes the ring follow its corners. As with the browser's own outline, the ring shows only when focus is visible (`:focus-visible`): after a keyboard press, not after a mouse press. The rule has zero specificity, so a component's own ring always wins.
@@ -1241,6 +1256,15 @@ const { headings, omissions } = inspectMarkdown(page.body, {
 </FixtureGroup>
 ```
 
+`FixtureGroup` `titleHidden` (opt-in, default `false`) keeps `title` as the list's name (`aria-labelledby`) but does not draw the caption: it moves to a visually hidden element (`sw-sr-only`) out of the layout, so the first row starts where the caption would. Use it when the heading above already says what the caption would, such as one result in a sheet titled with the pairing and the day; the title is still required and still must be nonblank.
+
+```tsx
+<Text as="h3" variant="title">Heron Marsh vs Otter Pool</Text>
+<FixtureGroup title="Heron Marsh vs Otter Pool, Sunday 25 October" titleHidden>
+  <FixtureRow home={{ name: 'Heron Marsh' }} away={{ name: 'Otter Pool' }} center="14–9" centerKind="score" />
+</FixtureGroup>
+```
+
 `FixtureRow` `flag` (opt-in, `FixtureFlag`: `{ label, tone? }`) marks an issue at the row's start, such as a clash: a round mark a space-4 across with a "!", in the tone's tint and ink (`warning`, amber, the default, for something that needs the person; `danger`, red), its edge keeping 3:1 on the surface in every palette and the text colour in forced colors. The mark is `aria-hidden` with `label` as its `title` tooltip, and `label` is read first in the row from a visually hidden span ("Can't-play clash Heron Marsh 8:00 Otter Pool"); with `aria-label` it is put before your words with a comma ("Can't-play clash, Heron Marsh vs Otter Pool, 8:00"), so do not repeat it there. From `md` the mark sits on the first line at the row's start, the home side kept clear of it; below `md` it leads the second line, before the details, so it never squeezes the home name. A row with nothing on that line below `md` (no `status`, and no `meta` or one hidden below `md` by `metaHideBelow`) keeps the mark inline on its first line instead, as from `md` (class `sw-fixture-row-flag-inline`), rather than gaining a line that holds only the flag. A blank `label` or an unknown `tone` throws a `RangeError`. `action` (opt-in) is a control after the row, such as a small neutral `Button` ("Move", named in your words: `aria-label="Move Heron Marsh vs Otter Pool"`): it is the row's sibling in its list item, outside a link or button row's press area and after it in the Tab order, a press on it never opens the row, and it stays centred on the row's height in the run's last column at every width (from `md` the row's one line, below `md` both lines), so every row's action lines up. Where `:has` is supported the hover fill spans the row and its action. An empty slot draws nothing. The run has a column for it at the end, and one for `select` at the start (`sw-fixture-list` is `auto minmax(0, 1fr) auto minmax(0, 1fr) auto auto auto`, six below `md`); a row spans every column but those two (`grid-column: 2 / -2`), and an `auto` column no row uses takes no space. New classes `sw-fixture-row-flagged`, `sw-fixture-flag`, `sw-fixture-flag-mark`, `sw-fixture-flag-warning`, `sw-fixture-flag-danger`, `sw-fixture-item-action` and `sw-fixture-action`.
 
 ```tsx
@@ -1461,6 +1485,8 @@ A row can also carry three trailing parts. `unread` marks it new for the person,
 
 `Text` takes an optional `align` (`start`, `center`, `end`) mapped to generated `sw-text-align-*` classes, for a heading that must stay centered when it wraps.
 
+`Text` `font="mono"` (default `"sans"`; `textFonts`, `TextFont`) sets the words in the platform's monospace face through the generated `sw-font-mono` class (`ui-monospace, monospace`, the generic names only, so each platform draws its own), keeping the variant's size, weight, letter spacing and `color`, for a code read or typed character by character, such as a join code: `<Text variant="headline" font="mono">R8M 3TW</Text>`. The face is fixed-width, so figures and letters line up; the text stays selectable. An unknown font throws a `RangeError`.
+
 `Grid` places children in one to four (or six) equal-width columns with a token `gap` step. `columnsBelow={{ md: 2 }}` drops to fewer columns below the `md` breakpoint so tiles and stat cards stay readable on a phone. It accepts every `Box` prop.
 
 `fit` (`narrow` 15rem, `medium` 16.25rem, `wide` 18.75rem) fits the columns to the grid's width instead of a fixed count: as many columns as fit at that minimum, sharing the row, and one column when the grid is narrower than it, so a row of cards reflows on a tablet and stacks on a phone with no breakpoint. A fitted grid takes no `columns` or `columnsBelow` (either throws a `RangeError`, as an unknown `fit` does); keep `columnSpan` for fixed-column grids. `gridFits` lists the names.

package/dist/components/Field.d.ts

@@ -1,75 +1,6 @@
-import { type SpacingStep } from '@scalewing/tokens';
-import { type ReactNode } from 'react';
-import { type RequiredMark } from './FieldLabelText.js';
-import { type FieldWidth } from '../css/css-field-width.js';
+import { type FieldProps } from './field/field-props.js';
 import { fieldVariants, type FieldVariant } from './field/field-checks.js';
-export type FieldSize = 'xs' | 'md';
 export { fieldVariants, type FieldVariant };
-export type FieldProps = {
-    children: ReactNode;
-    gap?: SpacingStep;
-    label: string;
-    labelVisuallyHidden?: boolean;
-    size?: FieldSize;
-    description?: string;
-    error?: string;
-    /**
-     * Marks the control invalid (`aria-invalid` and the danger border) without
-     * a message of its own, for a field whose error is shown elsewhere, such
-     * as one message under a group of fields. Point the control's
-     * `aria-describedby` at that message. `error` implies it. Passing
-     * `invalid`, even `false` but not `undefined`, requires one native control
-     * child from the first render.
-     */
-    invalid?: boolean;
-    /**
-     * Marks a value the person changed from a saved one, such as a field in a
-     * correction: the control's border (or an adorned frame's) in the accent
-     * color, thicker than the plain hairline, and its fill tinted with 12 % of
-     * the accent, so a changed field reads apart from the focused one (focus
-     * draws a ring and never tints). The value keeps 4.5:1 on the tint; while
-     * a placeholder shows, the fill stays plain. It is a cue, not the record:
-     * say what it was in `description` ("Was 25"). `invalid` and `error`
-     * win. Like `invalid`, passing it, even `false` but not `undefined`,
-     * requires one native control child from the first render.
-     */
-    changed?: boolean;
-    required?: boolean;
-    /**
-     * `hidden` leaves out the label's " *" while the control stays required
-     * (and announced so); `visible` (default) draws it.
-     * When hidden, say in visible text which fields must be filled; a
-     * placeholder alone is not enough.
-     */
-    requiredMark?: RequiredMark;
-    /** Short text inside the control frame before the value, such as a currency sign. Not part of the value. */
-    prefix?: string;
-    /** Short text inside the control frame after the value, such as a unit. Not part of the value. */
-    suffix?: string;
-    /**
-     * `outlined` (default) is the labelled form field. `search` is a search
-     * box: the label is not drawn (it stays the input's name), a `leading`
-     * glyph sits at the frame's start, the input is `type="search"`, and a
-     * clear button named `clearLabel` shows while the input holds text and
-     * is enabled; it calls `onClear` (set the value to `''`) and puts focus
-     * back in the input. Needs one native `input` child with a `value`.
-     */
-    variant?: FieldVariant;
-    /** A search field's glyph at its start, such as a magnifier; hidden from assistive technology. */
-    leading?: ReactNode;
-    /** A search field's clear button name, such as "Clear search". */
-    clearLabel?: string;
-    /** Called by a search field's clear button; the consumer empties the value. */
-    onClear?: () => void;
-    /**
-     * Caps the control's width at a Table column size (`xs` 4rem, `sm` 6rem,
-     * `md` 8rem, `lg` 12rem, `xl` 16rem), at the start of the column and
-     * never wider than it, so a short value such as a rate or a count does
-     * not stretch across a form. The label and messages keep the column's
-     * width. Left out, the control fills the column. It needs one native
-     * text input, select or textarea child (a `TypeError` otherwise); an
-     * unknown width throws a `RangeError`.
-     */
-    width?: FieldWidth;
-};
+export type { FieldProps, FieldSize } from './field/field-props.js';
+export { fieldDescriptionTones, type FieldDescriptionTone, } from './field/FieldDescription.js';
 export declare function Field(props: FieldProps): import("react").JSX.Element;

package/dist/components/Field.js

@@ -1,16 +1,18 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { cloneElement, isValidElement, useId, } from 'react';
+import { cloneElement, isValidElement, useId } from 'react';
 import { adornedControlAria, FieldAdornment, } from './FieldAdornment.js';
 import { FieldErrorRegion } from './FieldErrorRegion.js';
-import { assertRequiredMark, FieldLabelText, } from './FieldLabelText.js';
+import { assertRequiredMark, FieldLabelText } from './FieldLabelText.js';
 import { fieldWidthClass } from '../css/css-field-width.js';
+import { FieldDescription } from './field/FieldDescription.js';
 import { SearchFrame } from './field/SearchFrame.js';
 import { assertFieldProps, fieldVariants, passesInvalid, } from './field/field-checks.js';
 import { Stack } from './Stack.js';
 export { fieldVariants };
+export { fieldDescriptionTones, } from './field/FieldDescription.js';
 export function Field(props) {
-    const { children, gap = 1, label, labelVisuallyHidden = false, size = 'md', description, error, invalid = false, changed = false, required = false, requiredMark = 'visible', prefix, suffix, variant = 'outlined', leading, clearLabel = '', onClear, width, } = props;
+    const { children, gap = 1, label, labelVisuallyHidden = false, size = 'md', description, descriptionTone = 'muted', error, invalid = false, changed = false, required = false, requiredMark = 'visible', prefix, suffix, variant = 'outlined', leading, clearLabel = '', onClear, width, } = props;
     assertFieldProps(props, children);
     const search = variant === 'search';
     const controlId = useId();
@@ -90,5 +92,5 @@ export function Field(props) {
     });
     const value = children.props.value;
     const hasText = value !== undefined && value !== null && String(value) !== '';
-    return (_jsxs(Stack, { as: "div", className: className, gap: labelHidden ? 0 : gap, children: [_jsx("label", { className: search ? 'sw-sr-only' : undefined, htmlFor: children.props.id || controlId, id: labelId, children: labelText }), search ? (_jsx(SearchFrame, { clearLabel: clearLabel, leading: leading, onClear: onClear, showClear: hasText && !children.props.disabled && !children.props.readOnly, children: control })) : adorned ? (_jsx(FieldAdornment, { prefix: prefix, prefixId: prefixId, suffix: suffix, suffixId: suffixId, children: control })) : (control), description && !error ? (_jsx("span", { className: "sw-field-description", id: descriptionId, children: description })) : null, _jsx(FieldErrorRegion, { className: "sw-field-error", id: errorId, message: error })] }));
+    return (_jsxs(Stack, { as: "div", className: className, gap: labelHidden ? 0 : gap, children: [_jsx("label", { className: search ? 'sw-sr-only' : undefined, htmlFor: children.props.id || controlId, id: labelId, children: labelText }), search ? (_jsx(SearchFrame, { clearLabel: clearLabel, leading: leading, onClear: onClear, showClear: hasText && !children.props.disabled && !children.props.readOnly, children: control })) : adorned ? (_jsx(FieldAdornment, { prefix: prefix, prefixId: prefixId, suffix: suffix, suffixId: suffixId, children: control })) : (control), description && !error ? (_jsx(FieldDescription, { id: descriptionId, tone: descriptionTone, children: description })) : null, _jsx(FieldErrorRegion, { className: "sw-field-error", id: errorId, message: error })] }));
 }

package/dist/components/FixtureGroup.d.ts

@@ -3,7 +3,8 @@ export type { FixtureGroupProps } from './fixture/types.js';
 /**
  * A run of fixtures under a caption, such as a match day at a venue: the
  * caption names a list of FixtureRows, whose columns line up across the
- * run (one grid, each row a subgrid of it). A blank title throws a
+ * run (one grid, each row a subgrid of it). `titleHidden` keeps the
+ * caption as the list's name without drawing it. A blank title throws a
  * `RangeError`.
  */
-export declare function FixtureGroup({ children, title }: FixtureGroupProps): import("react").JSX.Element;
+export declare function FixtureGroup({ children, title, titleHidden, }: FixtureGroupProps): import("react").JSX.Element;

package/dist/components/FixtureGroup.js

@@ -5,12 +5,13 @@ import { FixtureListContext } from './fixture/fixture-list-context.js';
 /**
  * A run of fixtures under a caption, such as a match day at a venue: the
  * caption names a list of FixtureRows, whose columns line up across the
- * run (one grid, each row a subgrid of it). A blank title throws a
+ * run (one grid, each row a subgrid of it). `titleHidden` keeps the
+ * caption as the list's name without drawing it. A blank title throws a
  * `RangeError`.
  */
-export function FixtureGroup({ children, title }) {
+export function FixtureGroup({ children, title, titleHidden = false, }) {
     if (typeof title !== 'string' || !title.trim())
         throw new RangeError('FixtureGroup title must be nonempty');
     const titleId = useId();
-    return (_jsxs("div", { className: "sw-fixture-group", children: [_jsx("div", { className: "sw-fixture-group-title", id: titleId, children: title }), _jsx("ul", { "aria-labelledby": titleId, className: "sw-fixture-list", role: "list", children: _jsx(FixtureListContext.Provider, { value: true, children: children }) })] }));
+    return (_jsxs("div", { className: "sw-fixture-group", children: [_jsx("div", { className: titleHidden ? 'sw-sr-only' : 'sw-fixture-group-title', id: titleId, children: title }), _jsx("ul", { "aria-labelledby": titleId, className: "sw-fixture-list", role: "list", children: _jsx(FixtureListContext.Provider, { value: true, children: children }) })] }));
 }

package/dist/components/Text.d.ts

@@ -2,10 +2,21 @@ import { type SemanticColorKey, type TypographyVariant } from '@scalewing/tokens
 import { type HTMLAttributes, type LabelHTMLAttributes } from 'react';
 export type TextElement = 'p' | 'span' | 'h1' | 'h2' | 'h3' | 'h4' | 'label' | 'strong';
 export type TextAlign = 'start' | 'center' | 'end';
+/** The faces Text sets its words in: the theme's sans or the platform's monospace. */
+export declare const textFonts: readonly ["sans", "mono"];
+export type TextFont = (typeof textFonts)[number];
 export type TextProps = HTMLAttributes<HTMLElement> & Pick<LabelHTMLAttributes<HTMLLabelElement>, 'htmlFor'> & {
     align?: TextAlign;
     as?: TextElement;
     color?: SemanticColorKey;
+    /**
+     * `mono` sets the words in the platform's monospace face (the generated
+     * `sw-font-mono` class) at the variant's size, weight and colour, for a
+     * code read or typed character by character, such as a join code. The
+     * face is fixed-width, so figures line up. Default `sans`; an unknown
+     * font throws a `RangeError`.
+     */
+    font?: TextFont;
     truncate?: boolean;
     variant?: TypographyVariant;
 };
@@ -13,6 +24,14 @@ export declare const Text: import("react").ForwardRefExoticComponent<HTMLAttribu
     align?: TextAlign;
     as?: TextElement;
     color?: SemanticColorKey;
+    /**
+     * `mono` sets the words in the platform's monospace face (the generated
+     * `sw-font-mono` class) at the variant's size, weight and colour, for a
+     * code read or typed character by character, such as a join code. The
+     * face is fixed-width, so figures line up. Default `sans`; an unknown
+     * font throws a `RangeError`.
+     */
+    font?: TextFont;
     truncate?: boolean;
     variant?: TypographyVariant;
 } & import("react").RefAttributes<HTMLElement>>;

package/dist/components/Text.js

@@ -1,6 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef, } from 'react';
 import { cx } from '../class-names.js';
+/** The faces Text sets its words in: the theme's sans or the platform's monospace. */
+export const textFonts = ['sans', 'mono'];
 const defaultElement = {
     body: 'p',
     caption: 'span',
@@ -13,7 +15,9 @@ const defaultElement = {
     lead: 'p',
     title: 'h3',
 };
-export const Text = forwardRef(function Text({ align, as, className, color = 'text', style, truncate = false, variant = 'body', ...rest }, ref) {
+export const Text = forwardRef(function Text({ align, as, className, color = 'text', font = 'sans', style, truncate = false, variant = 'body', ...rest }, ref) {
+    if (!textFonts.includes(font))
+        throw new RangeError(`Unknown Text font: ${String(font)}`);
     const Component = as ?? defaultElement[variant];
-    return (_jsx(Component, { ref: ref, className: cx(`sw-text-${variant}`, align && `sw-text-align-${align}`, truncate && 'sw-truncate', className), style: { color: `var(--sw-color-${color})`, ...style }, ...rest }));
+    return (_jsx(Component, { ref: ref, className: cx(`sw-text-${variant}`, align && `sw-text-align-${align}`, font === 'mono' && 'sw-font-mono', truncate && 'sw-truncate', className), style: { color: `var(--sw-color-${color})`, ...style }, ...rest }));
 });

package/dist/components/field/FieldDescription.d.ts

@@ -0,0 +1,15 @@
+/** How a Field's description reads: the quiet hint or a warning that is not an error. */
+export declare const fieldDescriptionTones: readonly ["muted", "warning"];
+export type FieldDescriptionTone = (typeof fieldDescriptionTones)[number];
+export declare function assertFieldDescriptionTone(tone: unknown): void;
+/**
+ * A Field's description under its control, the control's
+ * `aria-describedby` target. A warning one leads with a private alert
+ * glyph, hidden from assistive technology, so it reads apart from a muted
+ * hint without colour (and in forced colours, where both take CanvasText).
+ */
+export declare function FieldDescription({ children, id, tone, }: {
+    children: string;
+    id: string;
+    tone: FieldDescriptionTone;
+}): import("react").JSX.Element;

package/dist/components/field/FieldDescription.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** How a Field's description reads: the quiet hint or a warning that is not an error. */
+export const fieldDescriptionTones = ['muted', 'warning'];
+export function assertFieldDescriptionTone(tone) {
+    if (!fieldDescriptionTones.includes(tone))
+        throw new RangeError(`Unknown Field descriptionTone: ${String(tone)}`);
+}
+/** A triangle with an exclamation mark, drawn in the description's colour. */
+const alertPath = 'M12 3.5 21.5 20h-19zM12 9.75v4.5M12 17.25v.01';
+/**
+ * A Field's description under its control, the control's
+ * `aria-describedby` target. A warning one leads with a private alert
+ * glyph, hidden from assistive technology, so it reads apart from a muted
+ * hint without colour (and in forced colours, where both take CanvasText).
+ */
+export function FieldDescription({ children, id, tone, }) {
+    if (tone === 'muted')
+        return (_jsx("span", { className: "sw-field-description", id: id, children: children }));
+    return (_jsxs("span", { className: "sw-field-description sw-field-description-warning", id: id, children: [_jsx("svg", { "aria-hidden": "true", className: "sw-field-description-glyph", focusable: "false", viewBox: "0 0 24 24", children: _jsx("path", { d: alertPath }) }), _jsx("span", { children: children })] }));
+}

package/dist/components/field/field-checks.d.ts

@@ -1,5 +1,5 @@
 import { type KeyboardEvent } from 'react';
-import type { FieldProps } from '../Field.js';
+import type { FieldProps } from './field-props.js';
 export declare const fieldVariants: readonly ["outlined", "search"];
 export type FieldVariant = (typeof fieldVariants)[number];
 /** The props Field reads from, and sets on, its native control child. */
@@ -18,9 +18,9 @@ export type FieldControlProps = {
     onKeyDown?: (event: KeyboardEvent<HTMLInputElement>) => void;
 };
 /**
- * Fails closed on a Field it cannot draw: an unknown variant or width,
- * search props on an outlined field, and a search field without its clear
- * button, its handler or one controlled native input.
+ * Fails closed on a Field it cannot draw: an unknown variant, width or
+ * description tone, search props on an outlined field, and a search field
+ * without its clear button, its handler or one controlled native input.
  */
 export declare function assertFieldProps(props: FieldProps, child: unknown): void;
 /**

package/dist/components/field/field-checks.js

@@ -1,14 +1,16 @@
 import { isValidElement } from 'react';
 import { assertFieldWidth } from '../../css/css-field-width.js';
+import { assertFieldDescriptionTone } from './FieldDescription.js';
 export const fieldVariants = ['outlined', 'search'];
 /**
- * Fails closed on a Field it cannot draw: an unknown variant or width,
- * search props on an outlined field, and a search field without its clear
- * button, its handler or one controlled native input.
+ * Fails closed on a Field it cannot draw: an unknown variant, width or
+ * description tone, search props on an outlined field, and a search field
+ * without its clear button, its handler or one controlled native input.
  */
 export function assertFieldProps(props, child) {
-    const { variant = 'outlined' } = props;
+    const { variant = 'outlined', descriptionTone = 'muted' } = props;
     assertFieldWidth(props.width);
+    assertFieldDescriptionTone(descriptionTone);
     if (!fieldVariants.includes(variant))
         throw new RangeError(`Unknown Field variant: ${String(variant)}`);
     if (variant !== 'search') {

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

@@ -0,0 +1,82 @@
+import { type SpacingStep } from '@scalewing/tokens';
+import { type ReactNode } from 'react';
+import { type FieldWidth } from '../../css/css-field-width.js';
+import { type RequiredMark } from '../FieldLabelText.js';
+import { type FieldDescriptionTone } from './FieldDescription.js';
+import { type FieldVariant } from './field-checks.js';
+export type FieldSize = 'xs' | 'md';
+export type FieldProps = {
+    children: ReactNode;
+    gap?: SpacingStep;
+    label: string;
+    labelVisuallyHidden?: boolean;
+    size?: FieldSize;
+    description?: string;
+    /**
+     * `warning` draws `description` in the warning colour after a small alert
+     * glyph, for a hint that needs the person but is not an error, such as a
+     * value another row already has. It stays the control's description and
+     * sets no invalid state; `error` still replaces it. Default `muted`; an
+     * unknown tone throws a `RangeError`.
+     */
+    descriptionTone?: FieldDescriptionTone;
+    error?: string;
+    /**
+     * Marks the control invalid (`aria-invalid` and the danger border) without
+     * a message of its own, for a field whose error is shown elsewhere, such
+     * as one message under a group of fields. Point the control's
+     * `aria-describedby` at that message. `error` implies it. Passing
+     * `invalid`, even `false` but not `undefined`, requires one native control
+     * child from the first render.
+     */
+    invalid?: boolean;
+    /**
+     * Marks a value the person changed from a saved one, such as a field in a
+     * correction: the control's border (or an adorned frame's) in the accent
+     * color, thicker than the plain hairline, and its fill tinted with 12 % of
+     * the accent, so a changed field reads apart from the focused one (focus
+     * draws a ring and never tints). The value keeps 4.5:1 on the tint; while
+     * a placeholder shows, the fill stays plain. It is a cue, not the record:
+     * say what it was in `description` ("Was 25"). `invalid` and `error`
+     * win. Like `invalid`, passing it, even `false` but not `undefined`,
+     * requires one native control child from the first render.
+     */
+    changed?: boolean;
+    required?: boolean;
+    /**
+     * `hidden` leaves out the label's " *" while the control stays required
+     * (and announced so); `visible` (default) draws it.
+     * When hidden, say in visible text which fields must be filled; a
+     * placeholder alone is not enough.
+     */
+    requiredMark?: RequiredMark;
+    /** Short text inside the control frame before the value, such as a currency sign. Not part of the value. */
+    prefix?: string;
+    /** Short text inside the control frame after the value, such as a unit. Not part of the value. */
+    suffix?: string;
+    /**
+     * `outlined` (default) is the labelled form field. `search` is a search
+     * box: the label is not drawn (it stays the input's name), a `leading`
+     * glyph sits at the frame's start, the input is `type="search"`, and a
+     * clear button named `clearLabel` shows while the input holds text and
+     * is enabled; it calls `onClear` (set the value to `''`) and puts focus
+     * back in the input. Needs one native `input` child with a `value`.
+     */
+    variant?: FieldVariant;
+    /** A search field's glyph at its start, such as a magnifier; hidden from assistive technology. */
+    leading?: ReactNode;
+    /** A search field's clear button name, such as "Clear search". */
+    clearLabel?: string;
+    /** Called by a search field's clear button; the consumer empties the value. */
+    onClear?: () => void;
+    /**
+     * Caps the control's width at a Table column size (`xs` 4rem, `sm` 6rem,
+     * `md` 8rem, `lg` 12rem, `xl` 16rem), at the start of the column and
+     * never wider than it, so a short value such as a rate or a count does
+     * not stretch across a form. The label and messages keep the column's
+     * width. Left out, the control fills the column. It needs one native
+     * text input, select or textarea child (a `TypeError` otherwise); an
+     * unknown width throws a `RangeError`.
+     */
+    width?: FieldWidth;
+};

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

@@ -0,0 +1 @@
+export {};

package/dist/components/fixture/types.d.ts

@@ -140,6 +140,12 @@ export type FixtureRowProps = {
 export type FixtureGroupProps = {
     /** The run's caption, such as a date and a venue; it names the list. */
     title: string;
+    /**
+     * Keeps `title` as the list's name but does not draw it, for a run whose
+     * heading is already on screen, such as one row in a sheet titled with
+     * the game and its day. Default `false`.
+     */
+    titleHidden?: boolean;
     /** The run's FixtureRows. */
     children: ReactNode;
 };

package/dist/css/css-field-description.d.ts

@@ -0,0 +1,2 @@
+export declare function cssFieldDescriptionClasses(): string;
+export declare function fieldDescriptionClassCatalog(): string[];

package/dist/css/css-field-description.js

@@ -0,0 +1,39 @@
+import { spacingScale, typographyVariants } from '@scalewing/tokens';
+const caption = typographyVariants.caption;
+const glyphStep = 4;
+/*
+ * A warning description (`descriptionTone="warning"`): the description's
+ * caption type in the warning colour (4.5:1 on the canvas in both schemes),
+ * led by a space-4 alert glyph centred on its first line, so the hint reads
+ * apart from a muted one without colour too. It never touches the control:
+ * no invalid border, no ARIA state. In forced colours the words and the
+ * glyph take CanvasText, apart from an error's Mark.
+ */
+export function cssFieldDescriptionClasses() {
+    const glyphInset = (caption.lineHeight - spacingScale[glyphStep]) / 2;
+    return `.sw-field-description-warning {
+  align-items: flex-start;
+  color: var(--sw-color-warning);
+  display: flex;
+  gap: var(--sw-space-1);
+}
+
+.sw-field-description-glyph {
+  fill: none;
+  flex: none;
+  height: var(--sw-space-${glyphStep});
+  margin-block: ${glyphInset}px;
+  stroke: currentColor;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  stroke-width: 2;
+  width: var(--sw-space-${glyphStep});
+}
+
+@media (forced-colors: active) {
+  .sw-field-description-warning { color: CanvasText; }
+}`;
+}
+export function fieldDescriptionClassCatalog() {
+    return ['sw-field-description-warning', 'sw-field-description-glyph'];
+}

package/dist/css/css-field.js

@@ -1,6 +1,7 @@
 import { typographyVariants } from '@scalewing/tokens';
 import { controlSurface, disabledControlForcedColors, disabledControlSurface, } from './css-document.js';
 import { cssFieldChangedClasses } from './css-field-changed.js';
+import { cssFieldDescriptionClasses, fieldDescriptionClassCatalog, } from './css-field-description.js';
 import { cssFieldWidthClasses, fieldWidthClassCatalog, } from './css-field-width.js';
 import { cssFieldSearchClasses, fieldSearchClassCatalog, } from './css-field-search.js';
 const caption = typographyVariants.caption;
@@ -76,6 +77,8 @@ export function cssFieldClasses() {
 .sw-field-description { color: var(--sw-color-muted); }
 .sw-field-error { color: var(--sw-color-danger); }
 
+${cssFieldDescriptionClasses()}
+
 /* An error region is always rendered as a live region; empty, it leaves the layout (and its gap) but stays in the accessibility tree. */
 .sw-field-error:empty { position: absolute; }
 
@@ -106,6 +109,7 @@ export function fieldClassCatalog() {
         'sw-field',
         'sw-field-required',
         'sw-field-description',
+        ...fieldDescriptionClassCatalog(),
         'sw-field-error',
         'sw-field-invalid',
         'sw-field-changed',

package/dist/css/css-font-mono.js

@@ -8,7 +8,8 @@ import { typedInputs } from './css-document.js';
 export const monospaceFamilies = 'ui-monospace, monospace';
 /*
  * Monospace text, for words read as typed code or marks (a Markdown source
- * being written), at the size the text already has. It outranks the
+ * being written, or a code set with `Text font="mono"`), at the size the
+ * text already has; it outranks a Text variant's sans family. It outranks the
  * canvas's text controls, which take the page's family, so a `textarea` or
  * a text input can take it too.
  */

package/dist/index.d.ts

@@ -47,7 +47,7 @@ export { StatTile, type StatTileAppearance, statTileAppearances, type StatTileEm
 export { TabPanel, type TabItem, type TabPanelProps, Tabs, type TabsProps, tabId, tabPanelId, } from './components/Tabs.js';
 export { Toast, toastPlacements, toastTones, type ToastAction, type ToastPlacement, } from './components/Toast.js';
 export type { ToastProps, ToastTone } from './components/Toast.js';
-export { Field, fieldVariants, type FieldProps, type FieldSize, type FieldVariant, } from './components/Field.js';
+export { Field, fieldDescriptionTones, fieldVariants, type FieldDescriptionTone, type FieldProps, type FieldSize, type FieldVariant, } from './components/Field.js';
 export { fieldWidths, type FieldWidth } from './css/css-field-width.js';
 export { requiredMarks, type RequiredMark, } from './components/FieldLabelText.js';
 export { Step, type StepHeadingLevel, type StepProps, Steps, type StepsLabels, type StepsProps, type StepStatus, } from './components/Steps.js';
@@ -74,7 +74,7 @@ export type { SelectAction, SelectOption, SelectProps, SelectWidth, } from './co
 export { MultiSelect, type MultiSelectAlign, type MultiSelectOption, type MultiSelectProps, } from './components/MultiSelect.js';
 export { Stack, type Align, type Justify, type StackProps, } from './components/Stack.js';
 export { Table, TableBody, TableCell, TableFooter, TableHeader, TableRow, TableSelectCell, tableCellTones, tableRowRules, tableRowVariants, type TableBodyProps, type TableCellProps, type TableCellTone, type TableColumnWidth, type TableDensity, type TableFooterProps, type TableHeaderProps, type TableLayout, type TableMaxHeight, type TableProps, type TableRowProps, type TableRowRule, type TableRowVariant, type TableSelectCellProps, type TableSort, type TableStickyHeader, type TableVerticalAlign, } from './components/Table.js';
-export { Text, type TextAlign, type TextElement, type TextProps, } from './components/Text.js';
+export { Text, textFonts, type TextAlign, type TextElement, type TextFont, type TextProps, } from './components/Text.js';
 export { ThemeProvider, useTheme, type ThemeProviderProps, } from './theme/ThemeProvider.js';
 export { themeCanvases, type ThemeCanvas } from './css/css-canvas-grouped.js';
 export { themeFrames, type ThemeFrame } from './css/css-theme-frame.js';

package/dist/index.js

@@ -45,7 +45,7 @@ export { Dialog, dialogAppearances, dialogPlacements, dialogSizes, } from './com
 export { StatTile, statTileAppearances, statTileTones, } from './components/StatTile.js';
 export { TabPanel, Tabs, tabId, tabPanelId, } from './components/Tabs.js';
 export { Toast, toastPlacements, toastTones, } from './components/Toast.js';
-export { Field, fieldVariants, } from './components/Field.js';
+export { Field, fieldDescriptionTones, fieldVariants, } from './components/Field.js';
 export { fieldWidths } from './css/css-field-width.js';
 export { requiredMarks, } from './components/FieldLabelText.js';
 export { Step, Steps, } from './components/Steps.js';
@@ -70,7 +70,7 @@ export { Select } from './components/Select.js';
 export { MultiSelect, } from './components/MultiSelect.js';
 export { Stack, } from './components/Stack.js';
 export { Table, TableBody, TableCell, TableFooter, TableHeader, TableRow, TableSelectCell, tableCellTones, tableRowRules, tableRowVariants, } from './components/Table.js';
-export { Text, } from './components/Text.js';
+export { Text, textFonts, } from './components/Text.js';
 export { ThemeProvider, useTheme, } from './theme/ThemeProvider.js';
 export { themeCanvases } from './css/css-canvas-grouped.js';
 export { themeFrames } from './css/css-theme-frame.js';

package/dist/styles.css

@@ -9563,6 +9563,29 @@ html:has(.sw-site-header-sticky) {
 .sw-field-description { color: var(--sw-color-muted); }
 .sw-field-error { color: var(--sw-color-danger); }
 
+.sw-field-description-warning {
+  align-items: flex-start;
+  color: var(--sw-color-warning);
+  display: flex;
+  gap: var(--sw-space-1);
+}
+
+.sw-field-description-glyph {
+  fill: none;
+  flex: none;
+  height: var(--sw-space-4);
+  margin-block: 1px;
+  stroke: currentColor;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  stroke-width: 2;
+  width: var(--sw-space-4);
+}
+
+@media (forced-colors: active) {
+  .sw-field-description-warning { color: CanvasText; }
+}
+
 /* An error region is always rendered as a live region; empty, it leaves the layout (and its gap) but stays in the accessibility tree. */
 .sw-field-error:empty { position: absolute; }
 

package/package.json

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