@scalewing/react 1.30.0 → 1.32.0

package/dist/components/DateField.d.ts

@@ -1,5 +1,6 @@
 import { type WeekStart } from '../calendar-month.js';
 import { type DateFieldLabels } from '../date-field-labels.js';
+import { type RequiredMark } from './FieldLabelText.js';
 export type { DateFieldLabels, WeekStart };
 export type DateFieldProps = {
     label: string;
@@ -18,6 +19,13 @@ export type DateFieldProps = {
     today?: string;
     disabled?: 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;
     description?: string;
     error?: string;
     /**
@@ -30,4 +38,4 @@ export type DateFieldProps = {
     /** The control's own words; English by default. */
     labels?: Partial<DateFieldLabels>;
 };
-export declare function DateField({ label, value, onChange, min, max, today, disabled, required, description, error, locale, weekStartsOn, labels, }: DateFieldProps): import("react").JSX.Element;
+export declare function DateField({ label, value, onChange, min, max, today, disabled, required, requiredMark, description, error, locale, weekStartsOn, labels, }: DateFieldProps): import("react").JSX.Element;

package/dist/components/DateField.js

@@ -7,13 +7,14 @@ import { dateEntryPattern, dateEntryPlaceholder } from '../date-entry.js';
 import { dateEntryValidity } from '../date-entry-validity.js';
 import { assertDateBounds, isOutsideDateRange } from '../date-only.js';
 import { FieldErrorRegion } from './FieldErrorRegion.js';
-import { FieldLabelText } from './FieldLabelText.js';
+import { assertRequiredMark, FieldLabelText, } from './FieldLabelText.js';
 import { CalendarDialog } from './date-field/CalendarDialog.js';
 import { DateFieldGlyph } from './date-field/DateFieldGlyph.js';
 import { useCalendarPopup } from './date-field/use-calendar-popup.js';
 import { useDateEntry } from './date-field/use-date-entry.js';
 import { useLangLocale } from './date-field/use-lang-locale.js';
-export function DateField({ label, value, onChange, min, max, today, disabled = false, required = false, description, error, locale, weekStartsOn = 0, labels, }) {
+export function DateField({ label, value, onChange, min, max, today, disabled = false, required = false, requiredMark = 'visible', description, error, locale, weekStartsOn = 0, labels, }) {
+    assertRequiredMark(requiredMark);
     assertDateBounds(value, min, max);
     assertWeekStart(weekStartsOn);
     const words = resolveDateFieldLabels(labels);
@@ -51,7 +52,7 @@ export function DateField({ label, value, onChange, min, max, today, disabled =
         .filter((id) => id !== null)
         .join(' ');
     const invalid = Boolean(error) || entry.invalid || isOutsideDateRange(value, min, max);
-    return (_jsxs("div", { className: "sw-date-field", ref: rootRef, children: [_jsx("label", { className: "sw-date-field-label", htmlFor: inputId, id: labelId, children: _jsx(FieldLabelText, { label: label, required: required }) }), _jsxs("div", { className: "sw-date-field-control", ref: controlRef, children: [_jsx("input", { "aria-describedby": describedBy || undefined, "aria-invalid": invalid, autoComplete: "off", className: "sw-date-field-input", disabled: disabled, id: inputId, onBlur: entry.check, onChange: (event) => entry.change(event.currentTarget.value), onKeyDown: (event) => {
+    return (_jsxs("div", { className: "sw-date-field", ref: rootRef, children: [_jsx("label", { className: "sw-date-field-label", htmlFor: inputId, id: labelId, children: _jsx(FieldLabelText, { label: label, required: required, requiredMark: requiredMark }) }), _jsxs("div", { className: "sw-date-field-control", ref: controlRef, children: [_jsx("input", { "aria-describedby": describedBy || undefined, "aria-invalid": invalid, autoComplete: "off", className: "sw-date-field-input", disabled: disabled, id: inputId, onBlur: entry.check, onChange: (event) => entry.change(event.currentTarget.value), onKeyDown: (event) => {
                             if (event.key === 'Enter')
                                 entry.check();
                         }, placeholder: dateEntryPlaceholder(pattern, {

package/dist/components/DenominationGrid.d.ts

@@ -1,6 +1,8 @@
+import { denominationGridFrames, denominationTotalEmphases } from '../css/css-denomination-appearance.js';
+import { denominationCellToneAppearances } from '../css/css-denomination-cell-tones.js';
 import { denominationLabelAppearances } from '../css/css-denomination-label.js';
 import { type DenominationGridProps } from './denomination-grid/types.js';
-export type { DenominationGridColumn, DenominationGridEntry, DenominationGridLayout, DenominationGridProps, DenominationGridRow, DenominationGridRowEmphasis, DenominationGridRowRole, DenominationGridTone, DenominationLabelWidth, } from './denomination-grid/types.js';
+export type { DenominationCellToneAppearance, DenominationGridColumn, DenominationGridEntry, DenominationGridFrame, DenominationGridLayout, DenominationGridProps, DenominationGridRow, DenominationGridRowEmphasis, DenominationGridRowRole, DenominationGridTone, DenominationLabelWidth, DenominationTotalEmphasis, } from './denomination-grid/types.js';
 export type { DenominationLabelAppearance } from '../css/css-denomination-label.js';
-export { denominationLabelAppearances };
-export declare function DenominationGrid({ label, columns, rows, layout, subtotal, zeroLabel, totalLabel, rowRole, labelWidth, labelAppearance, }: DenominationGridProps): import("react").JSX.Element;
+export { denominationCellToneAppearances, denominationGridFrames, denominationLabelAppearances, denominationTotalEmphases, };
+export declare function DenominationGrid({ label, columns, rows, layout, subtotal, zeroLabel, totalLabel, rowRole, labelWidth, labelAppearance, frame, totalEmphasis, cellToneAppearance, }: DenominationGridProps): import("react").JSX.Element;

package/dist/components/DenominationGrid.js

@@ -1,27 +1,37 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { cx } from '../class-names.js';
 import { denominationLabelWidths } from '../css/css-denomination-aligned.js';
+import { denominationGridFrames, denominationTotalEmphases, denominationTotalsStrongClass, } from '../css/css-denomination-appearance.js';
+import { denominationCellToneAppearances, denominationCellTonesPillClass, } from '../css/css-denomination-cell-tones.js';
 import { denominationLabelAppearances, denominationLabelsPlainClass, } from '../css/css-denomination-label.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 { denominationLabelAppearances };
-export function DenominationGrid({ label, columns, rows, layout = 'strip', subtotal, zeroLabel = '—', totalLabel, rowRole = 'region', labelWidth, labelAppearance = 'tone', }) {
+export { denominationCellToneAppearances, denominationGridFrames, denominationLabelAppearances, denominationTotalEmphases, };
+/** Fails closed on a value outside a closed set, naming the prop. */
+function assertOneOf(values, value, prop) {
+    if (!values.includes(value))
+        throw new RangeError(`Unknown ${prop}: ${String(value)}`);
+}
+export function DenominationGrid({ label, columns, rows, layout = 'strip', subtotal, zeroLabel = '—', totalLabel, rowRole = 'region', labelWidth, labelAppearance = 'tone', frame = 'none', totalEmphasis = 'default', cellToneAppearance = 'text', }) {
     assertDenominationGrid(label, columns, rows);
     assertDenominationExtras(layout, columns, rows);
     assertDenominationEntries(layout, columns, rows);
-    if (!zeroLabel)
-        throw new RangeError('zeroLabel must not be empty');
+    if (typeof zeroLabel !== 'string')
+        throw new RangeError('zeroLabel must be a string');
     if (totalLabel !== undefined && !totalLabel.trim())
         throw new RangeError('totalLabel must not be empty');
     if (rowRole !== 'region' && rowRole !== 'group')
         throw new RangeError("rowRole must be 'region' or 'group'");
-    if (labelWidth !== undefined && !denominationLabelWidths.includes(labelWidth))
-        throw new RangeError(`Unknown labelWidth: ${String(labelWidth)}`);
-    if (!denominationLabelAppearances.includes(labelAppearance))
-        throw new RangeError(`Unknown labelAppearance: ${String(labelAppearance)}`);
-    const labelClass = labelAppearance === 'plain' ? denominationLabelsPlainClass : undefined;
+    if (labelWidth !== undefined)
+        assertOneOf(denominationLabelWidths, labelWidth, 'labelWidth');
+    assertOneOf(denominationLabelAppearances, labelAppearance, 'labelAppearance');
+    assertOneOf(denominationGridFrames, frame, 'frame');
+    assertOneOf(denominationTotalEmphases, totalEmphasis, 'totalEmphasis');
+    assertOneOf(denominationCellToneAppearances, cellToneAppearance, 'cellToneAppearance');
+    const appearanceClass = cx(labelAppearance === 'plain' && denominationLabelsPlainClass, totalEmphasis === 'strong' && denominationTotalsStrongClass, cellToneAppearance === 'pill' && denominationCellTonesPillClass);
     if (layout === 'tiles')
-        return (_jsx(DenominationTiles, { className: labelClass, columns: columns, label: label, rowRole: rowRole, rows: rows, subtotal: subtotal, zeroLabel: zeroLabel }));
-    return (_jsx(DenominationStrip, { className: labelClass, columns: columns, label: label, labelWidth: labelWidth, rows: rows, totalLabel: totalLabel, zeroLabel: zeroLabel }));
+        return (_jsx(DenominationTiles, { className: appearanceClass || undefined, columns: columns, label: label, rowRole: rowRole, rows: rows, subtotal: subtotal, zeroLabel: zeroLabel }));
+    return (_jsx(DenominationStrip, { className: appearanceClass || undefined, columns: columns, framed: frame === 'table', label: label, labelWidth: labelWidth, rows: rows, totalLabel: totalLabel, zeroLabel: zeroLabel }));
 }

package/dist/components/Dialog.d.ts

@@ -1,6 +1,8 @@
 import { type DialogHTMLAttributes, type ReactNode } from 'react';
 import { type Breakpoint } from '../css/breakpoints.js';
+import { type DialogAppearance, dialogAppearances } from '../css/css-dialog-banded.js';
 import { type ActionBarSummary } from './action-bar/ActionBarSummary.js';
+export { dialogAppearances, type DialogAppearance };
 export declare const dialogSizes: readonly ["md", "lg", "xl"];
 /**
  * `md` is the reading width (32rem) for a message or a short form; `lg`
@@ -74,6 +76,12 @@ export type DialogProps = Omit<DialogHTMLAttributes<HTMLDialogElement>, 'onClose
     summary?: ActionBarSummary;
     /** `alertdialog` for a warning that interrupts. Default `dialog`. */
     role?: DialogRole;
+    /**
+     * `banded` draws the dialog on the solid surface with its title row and
+     * footer as full-width bands over hairlines, and the close button on a
+     * quiet round fill; `glass` (the default) is one frosted panel.
+     */
+    appearance?: DialogAppearance;
     children: ReactNode;
 };
-export declare function Dialog({ 'aria-describedby': describedBy, children, className, closeLabel, description, footer, icon, role, summary, onCancel, onClose, onKeyDown, onPointerDown, onSubmit, open, sheetBelow, size, title, titleLevel, ...rest }: DialogProps): import("react").JSX.Element;
+export declare function Dialog({ 'aria-describedby': describedBy, appearance, children, className, closeLabel, description, footer, icon, role, summary, onCancel, onClose, onKeyDown, onPointerDown, onSubmit, open, sheetBelow, size, title, titleLevel, ...rest }: DialogProps): import("react").JSX.Element;

package/dist/components/Dialog.js

@@ -3,17 +3,21 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId } from 'react';
 import { cx } from '../class-names.js';
 import { dialogSheetClass } from '../css/css-dialog.js';
+import { dialogAppearances, dialogBandedClass, } from '../css/css-dialog-banded.js';
 import { spacingClassNames } from '../spacing-classes.js';
 import { useDialogCloseRequests } from './dialog-close-requests.js';
 import { assertActionBarSummary, } from './action-bar/ActionBarSummary.js';
 import { DialogFooter } from './dialog/DialogFooter.js';
 import { DialogTitle } from './dialog/DialogTitle.js';
 import { Stack } from './Stack.js';
+export { dialogAppearances };
 export const dialogSizes = ['md', 'lg', 'xl'];
 const dialogRoles = ['dialog', 'alertdialog'];
-function assertDialogProps(size, role, description, summary) {
+function assertDialogProps(size, role, description, summary, appearance) {
     if (!dialogSizes.includes(size))
         throw new RangeError(`Unknown Dialog size: ${String(size)}`);
+    if (!dialogAppearances.includes(appearance))
+        throw new RangeError(`Unknown Dialog appearance: ${String(appearance)}`);
     if (role !== undefined && !dialogRoles.includes(role))
         throw new RangeError(`Unknown Dialog role: ${String(role)}`);
     if (description !== undefined &&
@@ -22,8 +26,8 @@ function assertDialogProps(size, role, description, summary) {
     if (summary)
         assertActionBarSummary(summary);
 }
-export function Dialog({ 'aria-describedby': describedBy, children, className, closeLabel, description, footer, icon, role, summary, onCancel, onClose, onKeyDown, onPointerDown, onSubmit, open, sheetBelow, size = 'md', title, titleLevel = 3, ...rest }) {
-    assertDialogProps(size, role, description, summary);
+export function Dialog({ 'aria-describedby': describedBy, appearance = 'glass', children, className, closeLabel, description, footer, icon, role, summary, onCancel, onClose, onKeyDown, onPointerDown, onSubmit, open, sheetBelow, size = 'md', title, titleLevel = 3, ...rest }) {
+    assertDialogProps(size, role, description, summary, appearance);
     const titleId = useId();
     const descriptionId = useId();
     const hasFooter = Boolean(footer) || Boolean(summary);
@@ -35,5 +39,5 @@ export function Dialog({ 'aria-describedby': describedBy, children, className, c
         onPointerDown,
         onSubmit,
     });
-    return (_jsx("dialog", { ...rest, ref: nodeRef, "aria-describedby": describedBy ?? (description ? descriptionId : undefined), "aria-labelledby": titleId, className: cx('sw-dialog', size !== 'md' && `sw-dialog-${size}`, sheetBelow && dialogSheetClass(sheetBelow), ...spacingClassNames({ padding: 5 }), className), role: role === 'alertdialog' ? 'alertdialog' : undefined, ...handlers, children: _jsxs(Stack, { gap: 4, children: [_jsx(DialogTitle, { closeLabel: closeLabel, description: description, descriptionId: descriptionId, icon: icon, id: titleId, level: titleLevel === 2 ? 2 : 3, onClose: onClose, title: title }), children, hasFooter ? (_jsx(DialogFooter, { summary: summary, children: footer })) : null] }) }));
+    return (_jsx("dialog", { ...rest, ref: nodeRef, "aria-describedby": describedBy ?? (description ? descriptionId : undefined), "aria-labelledby": titleId, className: cx('sw-dialog', size !== 'md' && `sw-dialog-${size}`, sheetBelow && dialogSheetClass(sheetBelow), appearance === 'banded' && dialogBandedClass, ...spacingClassNames({ padding: 5 }), className), role: role === 'alertdialog' ? 'alertdialog' : undefined, ...handlers, children: _jsxs(Stack, { gap: 4, children: [_jsx(DialogTitle, { banded: appearance === 'banded', closeLabel: closeLabel, description: description, descriptionId: descriptionId, icon: icon, id: titleId, level: titleLevel === 2 ? 2 : 3, onClose: onClose, title: title }), children, hasFooter ? (_jsx(DialogFooter, { summary: summary, children: footer })) : null] }) }));
 }

package/dist/components/Field.d.ts

@@ -1,6 +1,9 @@
 import { type SpacingStep } from '@scalewing/tokens';
 import { type ReactNode } from 'react';
+import { type RequiredMark } from './FieldLabelText.js';
 export type FieldSize = 'xs' | 'md';
+export declare const fieldVariants: readonly ["outlined", "search"];
+export type FieldVariant = (typeof fieldVariants)[number];
 export type FieldProps = {
     children: ReactNode;
     gap?: SpacingStep;
@@ -31,9 +34,31 @@ export type FieldProps = {
      */
     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;
 };
 export declare function Field(props: FieldProps): import("react").JSX.Element;

package/dist/components/Field.js

@@ -1,10 +1,34 @@
 '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 { FieldLabelText } from './FieldLabelText.js';
+import { assertRequiredMark, FieldLabelText, } from './FieldLabelText.js';
+import { SearchFrame } from './field/SearchFrame.js';
 import { Stack } from './Stack.js';
+export const fieldVariants = ['outlined', 'search'];
+function assertSearch(props, child) {
+    const { variant = 'outlined' } = props;
+    if (!fieldVariants.includes(variant))
+        throw new RangeError(`Unknown Field variant: ${String(variant)}`);
+    if (variant !== 'search') {
+        if (props.leading !== undefined ||
+            props.clearLabel !== undefined ||
+            props.onClear !== undefined)
+            throw new TypeError('Field leading, clearLabel and onClear are for variant="search"');
+        return;
+    }
+    if (!props.clearLabel?.trim())
+        throw new RangeError('A search Field needs a nonempty clearLabel');
+    if (typeof props.onClear !== 'function')
+        throw new TypeError('A search Field needs onClear');
+    if (props.prefix || props.suffix)
+        throw new TypeError('A search Field takes leading, not prefix or suffix');
+    if (!isValidElement(child) || child.type !== 'input')
+        throw new TypeError('A search Field needs one native input child');
+    if (child.props.value === undefined)
+        throw new TypeError('A search Field needs a controlled input: pass value (and onChange)');
+}
 /**
  * `invalid` was passed, even as `false`, but not as `undefined` (a wrapper
  * forwarding an optional prop passes nothing): such a field needs one native
@@ -17,13 +41,16 @@ function passesInvalid(props) {
     return props.invalid !== undefined || props.changed !== undefined;
 }
 export function Field(props) {
-    const { children, gap = 1, label, labelVisuallyHidden = false, size = 'md', description, error, invalid = false, changed = false, required = false, prefix, suffix, } = 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, } = props;
+    assertSearch(props, children);
+    const search = variant === 'search';
     const controlId = useId();
     const descriptionId = useId();
     const errorId = useId();
     const labelId = useId();
     const prefixId = useId();
     const suffixId = useId();
+    assertRequiredMark(requiredMark);
     const message = error || description;
     const marksInvalid = Boolean(error) || invalid;
     const adorned = Boolean(prefix || suffix);
@@ -32,17 +59,20 @@ export function Field(props) {
         'sw-field',
         size === 'xs' && 'sw-field-xs',
         marksInvalid && 'sw-field-invalid',
+        search && 'sw-field-search-field',
         changed && !marksInvalid && 'sw-field-changed',
     ]
         .filter(Boolean)
         .join(' ');
-    const labelText = (_jsx(FieldLabelText, { label: label, required: required, size: size, visuallyHidden: labelVisuallyHidden }));
+    // A search field hides its whole label element instead (see below).
+    const labelHidden = labelVisuallyHidden && !search;
+    const labelText = (_jsx(FieldLabelText, { label: label, required: required, requiredMark: requiredMark, size: size, visuallyHidden: labelHidden }));
     if (!isValidElement(children) ||
         typeof children.type !== 'string' ||
         !['input', 'select', 'textarea'].includes(children.type)) {
         if (needsControl)
             throw new TypeError('Field validation and adornments require one native input, select, or textarea child');
-        return (_jsxs(Stack, { as: "label", className: className, gap: labelVisuallyHidden ? 0 : gap, children: [labelText, children] }));
+        return (_jsxs(Stack, { as: "label", className: className, gap: labelHidden ? 0 : gap, children: [labelText, children] }));
     }
     if (adorned && children.type !== 'input')
         throw new TypeError('Field prefix and suffix require a native input child');
@@ -63,6 +93,26 @@ export function Field(props) {
         'aria-invalid': marksInvalid ? true : children.props['aria-invalid'],
         'aria-labelledby': adornment.labelledBy,
         required: required || children.props.required,
+        ...(search
+            ? {
+                type: 'search',
+                enterKeyHint: children.props.enterKeyHint ?? 'search',
+                // Escape empties the box through onClear, the one clearing path
+                // (WebKit and Blink would otherwise clear it themselves).
+                onKeyDown: (event) => {
+                    children.props.onKeyDown?.(event);
+                    if (event.key === 'Escape' &&
+                        !event.defaultPrevented &&
+                        !event.currentTarget.readOnly &&
+                        event.currentTarget.value !== '') {
+                        event.preventDefault();
+                        onClear?.();
+                    }
+                },
+            }
+            : {}),
     });
-    return (_jsxs(Stack, { as: "div", className: className, gap: labelVisuallyHidden ? 0 : gap, children: [_jsx("label", { htmlFor: children.props.id || controlId, id: labelId, children: labelText }), 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 })] }));
+    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 })] }));
 }

package/dist/components/FieldLabelText.d.ts

@@ -1,13 +1,31 @@
+export declare const requiredMarks: readonly ["visible", "hidden"];
+/**
+ * Whether a required control's label shows the required mark: `visible`
+ * (the default) draws " *" after the label; `hidden` leaves it out, for a
+ * form that marks nothing as required (or marks what is optional instead).
+ * The control stays required either way, so assistive technology still
+ * hears it. When hidden, say in visible text which fields must be filled
+ * (a form-level note, or "Required" in the description); a placeholder
+ * alone is not enough (WCAG 3.3.2).
+ */
+export type RequiredMark = (typeof requiredMarks)[number];
+/** Fails closed on a value that is not a known required mark. */
+export declare function assertRequiredMark(value: unknown): void;
+/** Whether the mark is drawn: a required control whose mark is visible. */
+export declare function showsRequiredMark(required: boolean, requiredMark: RequiredMark): boolean;
 /**
  * A form control's label words and its required mark, as `Field` draws
  * them. The `<label>` around it inherits the canvas's body type, so its
  * line box, and the gap to the control below, is the same for every field
- * that uses it (`Field`, `DateField` and `Select`). The mark is `aria-hidden`: the
- * control's own required state is what assistive technology reads.
+ * that uses it (`Field`, `DateField` and `Select`; `Combobox` through
+ * `Field`, and `FilterChips` shares `showsRequiredMark` for its legend). The mark is `aria-hidden`: the
+ * control's own required state is what assistive technology reads, and
+ * `requiredMark="hidden"` leaves it out.
  */
-export declare function FieldLabelText({ label, required, size, visuallyHidden, }: {
+export declare function FieldLabelText({ label, required, requiredMark, size, visuallyHidden, }: {
     label: string;
     required?: boolean;
+    requiredMark?: RequiredMark;
     size?: 'xs' | 'md';
     visuallyHidden?: boolean;
 }): import("react").JSX.Element;

package/dist/components/FieldLabelText.js

@@ -1,12 +1,24 @@
 import { jsxs as _jsxs } from "react/jsx-runtime";
 import { Text } from './Text.js';
+export const requiredMarks = ['visible', 'hidden'];
+/** Fails closed on a value that is not a known required mark. */
+export function assertRequiredMark(value) {
+    if (!requiredMarks.includes(value))
+        throw new RangeError(`Unknown requiredMark: ${String(value)}`);
+}
+/** Whether the mark is drawn: a required control whose mark is visible. */
+export function showsRequiredMark(required, requiredMark) {
+    return required && requiredMark === 'visible';
+}
 /**
  * A form control's label words and its required mark, as `Field` draws
  * them. The `<label>` around it inherits the canvas's body type, so its
  * line box, and the gap to the control below, is the same for every field
- * that uses it (`Field`, `DateField` and `Select`). The mark is `aria-hidden`: the
- * control's own required state is what assistive technology reads.
+ * that uses it (`Field`, `DateField` and `Select`; `Combobox` through
+ * `Field`, and `FilterChips` shares `showsRequiredMark` for its legend). The mark is `aria-hidden`: the
+ * control's own required state is what assistive technology reads, and
+ * `requiredMark="hidden"` leaves it out.
  */
-export function FieldLabelText({ label, required = false, size = 'md', visuallyHidden = false, }) {
-    return (_jsxs(Text, { as: "span", className: visuallyHidden ? 'sw-sr-only' : undefined, variant: size === 'xs' ? 'caption' : 'label', children: [label, required ? (_jsxs("span", { "aria-hidden": "true", className: "sw-field-required", children: [' ', "*"] })) : null] }));
+export function FieldLabelText({ label, required = false, requiredMark = 'visible', size = 'md', visuallyHidden = false, }) {
+    return (_jsxs(Text, { as: "span", className: visuallyHidden ? 'sw-sr-only' : undefined, variant: size === 'xs' ? 'caption' : 'label', children: [label, showsRequiredMark(required, requiredMark) ? (_jsxs("span", { "aria-hidden": "true", className: "sw-field-required", children: [' ', "*"] })) : null] }));
 }

package/dist/components/FilterChips.d.ts

@@ -1,3 +1,4 @@
+import { type RequiredMark } from './FieldLabelText.js';
 export type FilterChipOption = {
     value: string;
     label: string;
@@ -16,6 +17,13 @@ export type FilterChipsProps = {
      * which reads the radios' own state).
      */
     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;
     /**
      * A message under the chips, such as "Pick a reason": a polite live
      * region linked to the group by `aria-describedby`; the group is marked
@@ -26,4 +34,4 @@ export type FilterChipsProps = {
     /** More ids that describe the group, such as a hint beside it. */
     'aria-describedby'?: string;
 };
-export declare function FilterChips({ label, value, onChange, options, required, error, 'aria-describedby': describedByProp, }: FilterChipsProps): import("react").JSX.Element;
+export declare function FilterChips({ label, value, onChange, options, required, requiredMark, error, 'aria-describedby': describedByProp, }: FilterChipsProps): import("react").JSX.Element;

package/dist/components/FilterChips.js

@@ -3,10 +3,11 @@ import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-run
 import { useId } from 'react';
 import { cx } from '../class-names.js';
 import { FieldErrorRegion } from './FieldErrorRegion.js';
+import { assertRequiredMark, showsRequiredMark, } from './FieldLabelText.js';
 function isCount(count) {
     return count === undefined || (Number.isInteger(count) && count >= 0);
 }
-export function FilterChips({ label, value, onChange, options, required = false, error, 'aria-describedby': describedByProp, }) {
+export function FilterChips({ label, value, onChange, options, required = false, requiredMark = 'visible', error, 'aria-describedby': describedByProp, }) {
     const name = useId();
     const errorId = useId();
     const describedBy = [describedByProp?.trim() || null, error ? errorId : null]
@@ -15,6 +16,7 @@ export function FilterChips({ label, value, onChange, options, required = false,
     const values = options.map((option) => option.value);
     if (!label.trim())
         throw new RangeError('label must not be empty');
+    assertRequiredMark(requiredMark);
     if (options.length === 0 ||
         options.some((option) => !option.value.trim() || !option.label.trim()))
         throw new RangeError('options must have nonempty values and labels');
@@ -24,7 +26,7 @@ export function FilterChips({ label, value, onChange, options, required = false,
         throw new RangeError('value must match an option or be empty');
     if (options.some((option) => !isCount(option.count)))
         throw new RangeError('count must be a non-negative integer');
-    return (_jsxs("fieldset", { "aria-describedby": describedBy || undefined, "aria-invalid": error ? true : undefined, className: "sw-filter-chips", children: [_jsxs("legend", { className: "sw-filter-chips-legend", children: [label, required ? (_jsxs("span", { "aria-hidden": "true", className: "sw-field-required", children: [' ', "*"] })) : null] }), _jsx("span", { className: "sw-filter-chips-options", children: options.map((option) => (_jsxs("label", { className: cx('sw-filter-chip', option.count === 0 && 'sw-filter-chip-quiet'), children: [_jsx("input", { checked: option.value === value, className: "sw-filter-chip-input", disabled: option.disabled, name: name, onChange: (event) => {
+    return (_jsxs("fieldset", { "aria-describedby": describedBy || undefined, "aria-invalid": error ? true : undefined, className: "sw-filter-chips", children: [_jsxs("legend", { className: "sw-filter-chips-legend", children: [label, showsRequiredMark(required, requiredMark) ? (_jsxs("span", { "aria-hidden": "true", className: "sw-field-required", children: [' ', "*"] })) : null] }), _jsx("span", { className: "sw-filter-chips-options", children: options.map((option) => (_jsxs("label", { className: cx('sw-filter-chip', option.count === 0 && 'sw-filter-chip-quiet'), children: [_jsx("input", { checked: option.value === value, className: "sw-filter-chip-input", disabled: option.disabled, name: name, onChange: (event) => {
                                 if (event.currentTarget.checked && !option.disabled)
                                     onChange(option.value);
                             }, required: required, type: "radio", value: option.value }), _jsxs("span", { className: "sw-filter-chip-face", children: [option.label, option.count === undefined ? null : (_jsxs(_Fragment, { children: [' ', _jsx("span", { className: "sw-filter-chip-count", children: option.count })] }))] })] }, option.value))) }), _jsx(FieldErrorRegion, { className: "sw-filter-chips-error", id: errorId, message: error })] }));

package/dist/components/Nav.d.ts

@@ -1,3 +1,15 @@
+import { type NavAppearance, navAppearances } from '../css/css-nav-words.js';
 import { type BoxProps } from './Box.js';
-export type NavProps = Omit<BoxProps, 'as'>;
-export declare function Nav({ className, ...rest }: NavProps): import("react").JSX.Element;
+export { navAppearances, type NavAppearance };
+export type NavProps = Omit<BoxProps, 'as'> & {
+    /**
+     * `words` draws every destination (a link or a Button) as plain words:
+     * the current one (`aria-current`) in the text color at label weight,
+     * the others muted, with no fill or underline. The words must be visible:
+     * a glyph-only destination has no weight to change, so its current mark
+     * would be color alone (keep `default` there). `default` keeps each
+     * destination's own look.
+     */
+    appearance?: NavAppearance;
+};
+export declare function Nav({ appearance, className, ...rest }: NavProps): import("react").JSX.Element;

package/dist/components/Nav.js

@@ -1,7 +1,11 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cx } from '../class-names.js';
+import { navAppearances, navWordsClass, } from '../css/css-nav-words.js';
 import { Box } from './Box.js';
-export function Nav({ className, ...rest }) {
-    return _jsx(Box, { as: "nav", className: cx('sw-nav', className), ...rest });
+export { navAppearances };
+export function Nav({ appearance = 'default', className, ...rest }) {
+    if (!navAppearances.includes(appearance))
+        throw new RangeError(`Unknown Nav appearance: ${String(appearance)}`);
+    return (_jsx(Box, { as: "nav", className: cx('sw-nav', appearance === 'words' && navWordsClass, className), ...rest }));
 }

package/dist/components/SegmentedControl.d.ts

@@ -22,9 +22,12 @@ type SegmentedLabel = {
  * `compact` is the quiet chip track for a section switch; `filled` gives every
  * segment the same width and paints the selected one in the accent, for a
  * choice that decides what a form does. It sizes to its container: the full
- * width in a Stack, the width of its widest label in an Inline.
+ * width in a Stack, the width of its widest label in an Inline. `raised` is
+ * a grey track whose selected segment is the surface raised by a small
+ * shadow, every segment at the md control height with its words in the
+ * text color, sized to its segments even in a Stack (unlike `compact`).
  */
-export type SegmentedControlVariant = 'compact' | 'filled';
+export type SegmentedControlVariant = 'compact' | 'filled' | 'raised';
 /**
  * A disabled control can never report a change, so it needs no `onChange`;
  * a live one must have it.

package/dist/components/SegmentedControl.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef, useId } from 'react';
 import { cx } from '../class-names.js';
+import { segmentedRaisedClass } from '../css/css-segmented-raised.js';
 import { FieldErrorRegion } from './FieldErrorRegion.js';
 export const SegmentedControl = forwardRef(function SegmentedControl({ disabled = false, error, items, onChange, required = false, value, variant = 'compact', ...labelProps }, ref) {
     const errorId = useId();
@@ -23,7 +24,7 @@ export const SegmentedControl = forwardRef(function SegmentedControl({ disabled
     }
     // The wrapper is always rendered, so an error that appears later swaps
     // text into a live region that already exists and the group keeps focus.
-    return (_jsxs("div", { className: cx('sw-segmented-field', variant === 'filled' && 'sw-segmented-field-filled'), children: [_jsx("div", { ref: ref, "aria-describedby": error ? errorId : undefined, "aria-disabled": disabled || undefined, "aria-invalid": error ? true : undefined, "aria-required": required || undefined, className: cx('sw-segmented', variant === 'filled' && 'sw-segmented-filled', withIcons && 'sw-segmented-with-icons', disabled && 'sw-segmented-disabled'), onKeyDown: onKeyDown, role: "radiogroup", ...labelProps, children: items.map((item) => {
+    return (_jsxs("div", { className: cx('sw-segmented-field', variant === 'filled' && 'sw-segmented-field-filled'), children: [_jsx("div", { ref: ref, "aria-describedby": error ? errorId : undefined, "aria-disabled": disabled || undefined, "aria-invalid": error ? true : undefined, "aria-required": required || undefined, className: cx('sw-segmented', variant === 'filled' && 'sw-segmented-filled', variant === 'raised' && segmentedRaisedClass, withIcons && 'sw-segmented-with-icons', disabled && 'sw-segmented-disabled'), onKeyDown: onKeyDown, role: "radiogroup", ...labelProps, children: items.map((item) => {
                     const selected = item.id === value;
                     return (_jsxs("button", { "aria-checked": selected, className: cx('sw-segmented-item', selected && 'sw-segmented-item-selected'), disabled: disabled, onClick: () => {
                             if (!selected) {

package/dist/components/Select.d.ts

@@ -1,5 +1,6 @@
 import { type SelectOption } from '../select-list.js';
 import { type FieldSize } from './Field.js';
+import { type RequiredMark } from './FieldLabelText.js';
 export type { SelectOption };
 /**
  * `content` (the default) sizes the field to its longest option, as a native
@@ -26,6 +27,13 @@ export type SelectProps = {
     placeholder?: string;
     /** Marks the label as Field does and sets `aria-required`. */
     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;
     /** A validation message under the control, wired as Field's error is. */
     error?: string;
     /**
@@ -35,4 +43,4 @@ export type SelectProps = {
      */
     width?: SelectWidth;
 };
-export declare function Select({ action, label, labelVisuallyHidden, onChange, options, size, value, placeholder, required, error, width, }: SelectProps): import("react").JSX.Element;
+export declare function Select({ action, label, labelVisuallyHidden, onChange, options, size, value, placeholder, required, requiredMark, error, width, }: SelectProps): import("react").JSX.Element;

package/dist/components/Select.js

@@ -4,12 +4,13 @@ import { useId, useRef } from 'react';
 import { cx } from '../class-names.js';
 import { selectedSelectIndex } from '../select-list.js';
 import { FieldErrorRegion } from './FieldErrorRegion.js';
-import { FieldLabelText } from './FieldLabelText.js';
+import { assertRequiredMark, FieldLabelText, } from './FieldLabelText.js';
 import { SelectListbox } from './select/SelectListbox.js';
 import { SelectValue } from './select/SelectValue.js';
 import { useSelectList } from './select/use-select-list.js';
 import { Stack } from './Stack.js';
-export function Select({ action, label, labelVisuallyHidden = false, onChange, options, size = 'md', value, placeholder, required = false, error, width = 'content', }) {
+export function Select({ action, label, labelVisuallyHidden = false, onChange, options, size = 'md', value, placeholder, required = false, requiredMark = 'visible', error, width = 'content', }) {
+    assertRequiredMark(requiredMark);
     if (placeholder !== undefined && !placeholder.trim())
         throw new RangeError('placeholder must not be empty');
     const labelId = useId();
@@ -22,7 +23,7 @@ export function Select({ action, label, labelVisuallyHidden = false, onChange, o
     const showsPlaceholder = placeholder !== undefined &&
         !options.some((option) => option.value === value);
     const { commit, highlight, onTriggerKeyDown, open, openList, setHighlight, setOpen, } = useSelectList({ action, onChange, options, rootRef, value });
-    return (_jsx("div", { ref: rootRef, className: cx('sw-select', size === 'xs' && 'sw-select-xs', width === 'full' && 'sw-select-full', error && 'sw-select-invalid'), children: _jsxs(Stack, { gap: labelVisuallyHidden ? 0 : 1, children: [_jsx("label", { htmlFor: triggerId, id: labelId, children: _jsx(FieldLabelText, { label: label, required: required, size: size, visuallyHidden: labelVisuallyHidden }) }), _jsxs("div", { className: "sw-select-control", children: [_jsx("button", { "aria-activedescendant": open ? `${optionIdPrefix}-${highlight}` : undefined, "aria-controls": open ? listId : undefined, "aria-describedby": error ? errorId : undefined, "aria-expanded": open, "aria-haspopup": "listbox", "aria-invalid": error ? true : undefined, "aria-labelledby": labelId, "aria-required": required || undefined, className: "sw-select-trigger", id: triggerId, onBlur: (event) => {
+    return (_jsx("div", { ref: rootRef, className: cx('sw-select', size === 'xs' && 'sw-select-xs', width === 'full' && 'sw-select-full', error && 'sw-select-invalid'), children: _jsxs(Stack, { gap: labelVisuallyHidden ? 0 : 1, children: [_jsx("label", { htmlFor: triggerId, id: labelId, children: _jsx(FieldLabelText, { label: label, required: required, requiredMark: requiredMark, size: size, visuallyHidden: labelVisuallyHidden }) }), _jsxs("div", { className: "sw-select-control", children: [_jsx("button", { "aria-activedescendant": open ? `${optionIdPrefix}-${highlight}` : undefined, "aria-controls": open ? listId : undefined, "aria-describedby": error ? errorId : undefined, "aria-expanded": open, "aria-haspopup": "listbox", "aria-invalid": error ? true : undefined, "aria-labelledby": labelId, "aria-required": required || undefined, className: "sw-select-trigger", id: triggerId, onBlur: (event) => {
                                 const next = event.relatedTarget;
                                 if (next instanceof Node && rootRef.current?.contains(next)) {
                                     return;

package/dist/components/Stepper.d.ts

@@ -1,5 +1,12 @@
 /** `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;
@@ -35,6 +42,12 @@ export type StepperProps = {
     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;
 };
 /**
  * A whole-number count between − and + buttons that can also be typed: one