@scalewing/react 1.8.0 → 1.10.0

package/dist/calendar-month.js

@@ -0,0 +1,116 @@
+import { daysInMonth, formatDateOnly, isValidDateParts, parseDateOnly, } from './date-only.js';
+/** Fails closed on a first weekday other than Sunday or Monday. */
+export function assertWeekStart(weekStartsOn) {
+    if (weekStartsOn !== 0 && weekStartsOn !== 1)
+        throw new RangeError('weekStartsOn must be 0 or 1');
+}
+/*
+ * Day arithmetic runs on a proleptic Gregorian day count, so it never passes
+ * through a Date, a time zone, or a daylight-saving jump.
+ * Algorithm: Howard Hinnant, "chrono-compatible low-level date algorithms".
+ */
+function toDayNumber({ year, month, day }) {
+    const y = month <= 2 ? year - 1 : year;
+    const era = Math.floor(y / 400);
+    const yearOfEra = y - era * 400;
+    const monthIndex = (month + 9) % 12;
+    const dayOfYear = Math.floor((153 * monthIndex + 2) / 5) + day - 1;
+    const dayOfEra = yearOfEra * 365 +
+        Math.floor(yearOfEra / 4) -
+        Math.floor(yearOfEra / 100) +
+        dayOfYear;
+    return era * 146097 + dayOfEra - 719468;
+}
+function fromDayNumber(dayNumber) {
+    const z = dayNumber + 719468;
+    const era = Math.floor(z / 146097);
+    const dayOfEra = z - era * 146097;
+    const yearOfEra = Math.floor((dayOfEra -
+        Math.floor(dayOfEra / 1460) +
+        Math.floor(dayOfEra / 36524) -
+        Math.floor(dayOfEra / 146096)) /
+        365);
+    const dayOfYear = dayOfEra -
+        (365 * yearOfEra + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100));
+    const monthIndex = Math.floor((5 * dayOfYear + 2) / 153);
+    const day = dayOfYear - Math.floor((153 * monthIndex + 2) / 5) + 1;
+    const month = monthIndex < 10 ? monthIndex + 3 : monthIndex - 9;
+    const year = yearOfEra + era * 400 + (month <= 2 ? 1 : 0);
+    return { year, month, day };
+}
+function requireDate(value) {
+    const parts = parseDateOnly(value);
+    if (!parts)
+        throw new RangeError('expected a valid YYYY-MM-DD date');
+    return parts;
+}
+/** 0 is Sunday. */
+export function weekdayOf(value) {
+    // Day 0 of the count is 1970-01-01, a Thursday.
+    return (((toDayNumber(requireDate(value)) + 4) % 7) + 7) % 7;
+}
+export function addDays(value, delta) {
+    return formatDateOnly(fromDayNumber(toDayNumber(requireDate(value)) + delta));
+}
+/** Same day of the month `delta` months away, capped at that month's length. */
+export function addMonths(value, delta) {
+    const parts = requireDate(value);
+    const month = shiftMonth(parts, delta);
+    return formatDateOnly({
+        ...month,
+        day: Math.min(parts.day, daysInMonth(month.year, month.month)),
+    });
+}
+export function monthOf(value) {
+    const parts = requireDate(value);
+    return { year: parts.year, month: parts.month };
+}
+export function shiftMonth(month, delta) {
+    const index = month.year * 12 + (month.month - 1) + delta;
+    return { year: Math.floor(index / 12), month: (index % 12) + 1 };
+}
+export function firstOfMonth(month) {
+    return formatDateOnly({ ...month, day: 1 });
+}
+export function lastOfMonth(month) {
+    return formatDateOnly({
+        ...month,
+        day: daysInMonth(month.year, month.month),
+    });
+}
+/** Whether any day of the month falls inside `[min, max]`. */
+export function monthInRange(month, min, max) {
+    return ((min === undefined || lastOfMonth(month) >= min) &&
+        (max === undefined || firstOfMonth(month) <= max));
+}
+/**
+ * The months of `year` with any day inside `[min, max]`, 1–12, for a month
+ * selector that only offers months a person can open.
+ */
+export function monthsInRange(year, min, max) {
+    return Array.from({ length: 12 }, (_, index) => index + 1).filter((month) => monthInRange({ year, month }, min, max));
+}
+/**
+ * Six rows of seven cells covering the month, padded with the neighboring
+ * months so the grid never changes height. Padding before 0001-01-01 or
+ * after 9999-12-31 is `null`: no four-digit date exists there.
+ */
+export function monthGrid(month, weekStartsOn) {
+    const first = firstOfMonth(month);
+    const leading = (weekdayOf(first) - weekStartsOn + 7) % 7;
+    const start = toDayNumber(requireDate(first)) - leading;
+    return Array.from({ length: 6 }, (_, row) => Array.from({ length: 7 }, (_, column) => {
+        const parts = fromDayNumber(start + row * 7 + column);
+        if (!isValidDateParts(parts))
+            return null;
+        return {
+            value: formatDateOnly(parts),
+            day: parts.day,
+            inMonth: parts.year === month.year && parts.month === month.month,
+        };
+    }));
+}
+/** Weekday indexes in display order for the given week start. */
+export function weekdayOrder(weekStartsOn) {
+    return Array.from({ length: 7 }, (_, index) => (index + weekStartsOn) % 7);
+}

package/dist/calendar-years.d.ts

@@ -0,0 +1,14 @@
+/** How far the year list reaches past today and the shown month by default. */
+export declare const YEARS_BACK = 120;
+export declare const YEARS_AHEAD = 20;
+export type YearRange = {
+    first: number;
+    last: number;
+};
+/**
+ * The years a calendar's year selector offers: 120 years before and 20
+ * after both today and the shown year, cut to `min` and `max`. The shown
+ * year is always inside, so the selector can display it.
+ */
+export declare function calendarYearRange(shownYear: number, todayYear: number, min?: string, max?: string): YearRange;
+export declare function yearsIn({ first, last }: YearRange): number[];

package/dist/calendar-years.js

@@ -0,0 +1,20 @@
+import { parseDateOnly } from './date-only.js';
+/** How far the year list reaches past today and the shown month by default. */
+export const YEARS_BACK = 120;
+export const YEARS_AHEAD = 20;
+/**
+ * The years a calendar's year selector offers: 120 years before and 20
+ * after both today and the shown year, cut to `min` and `max`. The shown
+ * year is always inside, so the selector can display it.
+ */
+export function calendarYearRange(shownYear, todayYear, min, max) {
+    const minYear = min === undefined ? 1 : (parseDateOnly(min)?.year ?? 1);
+    const maxYear = max === undefined ? 9999 : (parseDateOnly(max)?.year ?? 9999);
+    return {
+        first: Math.max(minYear, 1, Math.min(shownYear, todayYear) - YEARS_BACK),
+        last: Math.min(maxYear, 9999, Math.max(shownYear, todayYear) + YEARS_AHEAD),
+    };
+}
+export function yearsIn({ first, last }) {
+    return Array.from({ length: last - first + 1 }, (_, index) => first + index);
+}

package/dist/components/Accordion.d.ts

@@ -1,8 +1,13 @@
 import { type DetailsHTMLAttributes, type ReactNode } from 'react';
+export type AccordionSize = 'sm' | 'md';
 export type AccordionProps = Omit<DetailsHTMLAttributes<HTMLDetailsElement>, 'onToggle' | 'open' | 'title' | 'children'> & {
     open: boolean;
     onOpenChange: (open: boolean) => void;
     title: string;
+    /** One muted line under the title, such as a summary of the content. */
+    subtitle?: string;
+    /** `sm` is a quieter disclosure nested inside other content. */
+    size?: AccordionSize;
     children: ReactNode;
 };
-export declare function Accordion({ children, className, onOpenChange, open, title, ...rest }: AccordionProps): import("react").JSX.Element;
+export declare function Accordion({ children, className, onOpenChange, open, size, subtitle, title, ...rest }: AccordionProps): import("react").JSX.Element;

package/dist/components/Accordion.js

@@ -4,11 +4,20 @@ import { cx } from '../class-names.js';
 import { spacingClassNames } from '../spacing-classes.js';
 import { Stack } from './Stack.js';
 import { Text } from './Text.js';
-export function Accordion({ children, className, onOpenChange, open, title, ...rest }) {
-    return (_jsxs("details", { ...rest, className: cx('sw-accordion', className), open: open, onToggle: (event) => {
+const spaceBySize = { sm: 3, md: 4 };
+/* The sm header is an sm control: a step of block padding over its generated
+   min-height instead of the full inset, so it sits lower than a section. */
+const summarySpacingBySize = {
+    sm: { paddingX: 3, paddingY: 1 },
+    md: { padding: 4 },
+};
+const titleVariantBySize = { sm: 'label', md: 'title' };
+export function Accordion({ children, className, onOpenChange, open, size = 'md', subtitle, title, ...rest }) {
+    const space = spaceBySize[size];
+    return (_jsxs("details", { ...rest, className: cx('sw-accordion', size === 'sm' && 'sw-accordion-sm', className), open: open, onToggle: (event) => {
             const next = event.currentTarget.open;
             if (next !== open) {
                 onOpenChange(next);
             }
-        }, children: [_jsx("summary", { className: cx('sw-accordion-summary', ...spacingClassNames({ padding: 4 })), children: _jsx(Text, { as: "span", variant: "title", children: title }) }), _jsx(Stack, { gap: 4, padding: 4, paddingTop: 0, children: children })] }));
+        }, children: [_jsxs("summary", { className: cx('sw-accordion-summary', ...spacingClassNames(summarySpacingBySize[size])), children: [_jsxs("span", { className: "sw-accordion-heading", children: [_jsx(Text, { as: "span", variant: titleVariantBySize[size], children: title }), ' ', subtitle ? (_jsx(Text, { as: "span", color: "muted", variant: "caption", children: subtitle })) : null] }), _jsx("span", { "aria-hidden": "true", className: "sw-accordion-marker" })] }), _jsx(Stack, { gap: space, padding: space, paddingTop: 0, children: children })] }));
 }

package/dist/components/ActionBar.d.ts

@@ -0,0 +1,30 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+import { type Breakpoint } from '../css/breakpoints.js';
+export type ActionBarProps = Omit<HTMLAttributes<HTMLDivElement>, 'children'> & {
+    /** The actions, usually two or three `Button`s. */
+    children: ReactNode;
+    /**
+     * One short line about the work, such as when it was last saved. It is a
+     * polite live region, so a new status is announced without moving focus.
+     */
+    status?: string;
+    /** Sticky only below this breakpoint; from it up the bar sits in page flow. */
+    stickyBelow?: Breakpoint;
+};
+/**
+ * The actions for a long page on a glass bar that sticks to the bottom of
+ * the viewport while the content it follows scrolls by. Place it last in
+ * that content: it stays stuck while its parent is on screen and then rests
+ * in its own place at the end.
+ */
+export declare const ActionBar: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** The actions, usually two or three `Button`s. */
+    children: ReactNode;
+    /**
+     * One short line about the work, such as when it was last saved. It is a
+     * polite live region, so a new status is announced without moving focus.
+     */
+    status?: string;
+    /** Sticky only below this breakpoint; from it up the bar sits in page flow. */
+    stickyBelow?: Breakpoint;
+} & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/ActionBar.js

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

package/dist/components/Box.d.ts

@@ -1,5 +1,6 @@
 import { type RadiusStep, type SemanticColorKey } from '@scalewing/tokens';
 import { type AnchorHTMLAttributes, type HTMLAttributes } from 'react';
+import { type BoxBorderValue } from '../css/css-box-border.js';
 import { type ColumnSpanProps } from '../column-span-classes.js';
 import { type SpacingProps } from '../spacing-classes.js';
 import { type VisibilityProps } from '../visibility-classes.js';
@@ -8,11 +9,14 @@ export type BoxProps = SpacingProps & VisibilityProps & ColumnSpanProps & HTMLAt
     as?: BoxElement;
     background?: Extract<SemanticColorKey, 'background' | 'surface'>;
     radius?: RadiusStep;
-    border?: boolean;
+    /** A hairline token border: `true` is solid, `'dashed'` marks a space to fill in by hand. */
+    border?: BoxBorder;
 };
-export declare const Box: import("react").ForwardRefExoticComponent<SpacingProps & VisibilityProps & ColumnSpanProps & HTMLAttributes<HTMLElement> & Pick<AnchorHTMLAttributes<HTMLAnchorElement>, "download" | "href" | "rel" | "target"> & {
+export type BoxBorder = BoxBorderValue;
+export declare const Box: import("react").ForwardRefExoticComponent<SpacingProps & VisibilityProps & ColumnSpanProps & HTMLAttributes<HTMLElement> & Pick<AnchorHTMLAttributes<HTMLAnchorElement>, "rel" | "download" | "href" | "target"> & {
     as?: BoxElement;
     background?: Extract<SemanticColorKey, "background" | "surface">;
     radius?: RadiusStep;
-    border?: boolean;
+    /** A hairline token border: `true` is solid, `'dashed'` marks a space to fill in by hand. */
+    border?: BoxBorder;
 } & import("react").RefAttributes<HTMLElement>>;

package/dist/components/Box.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef, } from 'react';
 import { cx } from '../class-names.js';
+import { boxBorderClass } from '../css/css-box-border.js';
 import { columnSpanClassNames, } from '../column-span-classes.js';
 import { spacingClassNames } from '../spacing-classes.js';
 import { visibilityClassNames, } from '../visibility-classes.js';
@@ -14,11 +15,10 @@ export const Box = forwardRef(function Box({ as = 'div', background, border, cla
             paddingTop,
             paddingX,
             paddingY,
-        }), ...visibilityClassNames({ hideBelow, hideFrom }), ...columnSpanClassNames({ columnSpan }), className), style: {
+        }), ...visibilityClassNames({ hideBelow, hideFrom }), ...columnSpanClassNames({ columnSpan }), boxBorderClass(border), className), style: {
             backgroundColor: background
                 ? `var(--sw-color-${background})`
                 : undefined,
-            border: border ? '1px solid var(--sw-color-border)' : undefined,
             borderRadius: radius ? `var(--sw-radius-${radius})` : undefined,
             ...style,
         }, ...rest }));

package/dist/components/CalendarButton.d.ts

@@ -0,0 +1,43 @@
+import { type CalendarButtonLabels } from '../calendar-button-labels.js';
+import { type WeekStart } from '../calendar-month.js';
+import { type ButtonSize, type ButtonVariant } from './Button.js';
+export type { CalendarButtonLabels };
+export type CalendarButtonProps = {
+    /**
+     * What pressing it does, such as "Choose survey day". The button's name
+     * is this label, `labels.nameSeparator`, then `value` spoken in full; the
+     * calendar is named by the label.
+     */
+    label: string;
+    /**
+     * Calendar date `YYYY-MM-DD`. The button always holds a date. A value
+     * outside `min`/`max` stays the value, as on DateField; the calendar then
+     * opens on the nearest allowed day.
+     */
+    value: string;
+    /** Receives the chosen `YYYY-MM-DD`, never converted through UTC. */
+    onChange: (value: string) => void;
+    min?: string;
+    max?: string;
+    disabled?: boolean;
+    /** The `<button>` element's id. */
+    id?: string;
+    /**
+     * BCP 47 tag for the spoken date and the calendar's month and weekday
+     * names. Defaults to the nearest `lang` attribute, then en-US.
+     */
+    locale?: string;
+    /** First column of the calendar: 0 Sunday (default) or 1 Monday. */
+    weekStartsOn?: WeekStart;
+    /** The calendar's words and the name separator; English by default. */
+    labels?: Partial<CalendarButtonLabels>;
+    /** A Button size; a coarse pointer always gets a 44 px target. */
+    size?: ButtonSize;
+    variant?: ButtonVariant;
+};
+/**
+ * An icon-only button that opens DateField's calendar dialog to pick a
+ * date for something the page already shows, such as a day heading. It has
+ * no text entry and no empty value. The ref reaches the `<button>`.
+ */
+export declare const CalendarButton: import("react").ForwardRefExoticComponent<CalendarButtonProps & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/components/CalendarButton.js

@@ -0,0 +1,47 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { forwardRef, useCallback, useId } from 'react';
+import { resolveCalendarButtonLabels, } from '../calendar-button-labels.js';
+import { calendarTriggerName } from '../calendar-labels.js';
+import { assertWeekStart } from '../calendar-month.js';
+import { assertDateBounds, assertDateOnly } from '../date-only.js';
+import { Button } from './Button.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 { useLangLocale } from './date-field/use-lang-locale.js';
+function assertLabel(label) {
+    if (typeof label !== 'string' || label.trim() === '')
+        throw new RangeError('label must be non-empty text');
+}
+/** Sets a forwarded ref, callback or object, to the same node. */
+function setForwardedRef(ref, node) {
+    if (typeof ref === 'function')
+        ref(node);
+    else if (ref)
+        ref.current = node;
+}
+/**
+ * An icon-only button that opens DateField's calendar dialog to pick a
+ * date for something the page already shows, such as a day heading. It has
+ * no text entry and no empty value. The ref reaches the `<button>`.
+ */
+export const CalendarButton = forwardRef(function CalendarButton({ label, value, onChange, min, max, disabled = false, id, locale, weekStartsOn = 0, labels, size = 'md', variant = 'ghost', }, ref) {
+    assertLabel(label);
+    assertDateOnly('value', value);
+    assertDateBounds(value, min, max);
+    assertWeekStart(weekStartsOn);
+    const words = resolveCalendarButtonLabels(labels);
+    const { buttonRef, shown, toggle, trigger, dialog } = useCalendarPopup({
+        value,
+        disabled,
+        onChange,
+    });
+    const resolvedLocale = useLangLocale(locale, buttonRef);
+    const labelId = useId();
+    const setButton = useCallback((node) => {
+        buttonRef.current = node;
+        setForwardedRef(ref, node);
+    }, [buttonRef, ref]);
+    return (_jsxs(_Fragment, { children: [_jsxs(Button, { ...trigger, className: "sw-calendar-button", disabled: disabled, id: id, onPress: toggle, ref: setButton, size: size, variant: variant, children: [_jsx("span", { className: "sw-sr-only", children: calendarTriggerName(label, value, resolvedLocale, words.nameSeparator) }), _jsx(DateFieldGlyph, { name: "calendar" })] }), shown ? (_jsxs(_Fragment, { children: [_jsx("span", { hidden: true, id: labelId, children: label }), _jsx(CalendarDialog, { ...dialog, anchorRef: buttonRef, buttonRef: buttonRef, labelId: labelId, labels: words.calendar, locale: resolvedLocale, max: max, min: min, required: true, value: value, weekStartsOn: weekStartsOn })] })) : null] }));
+});

package/dist/components/DateField.d.ts

@@ -1,6 +1,11 @@
+import { type WeekStart } from '../calendar-month.js';
+import { type DateFieldLabels } from '../date-field-labels.js';
+export type { DateFieldLabels, WeekStart };
 export type DateFieldProps = {
     label: string;
+    /** Calendar date `YYYY-MM-DD`, or '' for no date. */
     value: string;
+    /** Receives `YYYY-MM-DD` or '', never converted through UTC. */
     onChange: (value: string) => void;
     min?: string;
     max?: string;
@@ -8,5 +13,14 @@ export type DateFieldProps = {
     required?: boolean;
     description?: string;
     error?: string;
+    /**
+     * BCP 47 tag for month and weekday names, spoken dates, and the typed
+     * field order. Defaults to the nearest `lang` attribute, then en-US.
+     */
+    locale?: string;
+    /** First column of the calendar: 0 Sunday (default) or 1 Monday. */
+    weekStartsOn?: WeekStart;
+    /** The control's own words; English by default. */
+    labels?: Partial<DateFieldLabels>;
 };
-export declare function DateField({ label, value, onChange, min, max, disabled, required, description, error, }: DateFieldProps): import("react").JSX.Element;
+export declare function DateField({ label, value, onChange, min, max, disabled, required, description, error, locale, weekStartsOn, labels, }: DateFieldProps): import("react").JSX.Element;

package/dist/components/DateField.js

@@ -1,30 +1,59 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useId } from 'react';
-import { assertDateOnly, isDateOnly, isOutsideDateRange, } from '../date-only.js';
-export function DateField({ label, value, onChange, min, max, disabled = false, required = false, description, error, }) {
-    assertDateOnly('value', value, true);
-    if (min !== undefined)
-        assertDateOnly('min', min);
-    if (max !== undefined)
-        assertDateOnly('max', max);
-    if (min !== undefined && max !== undefined && min > max)
-        throw new RangeError('min must not be after max');
+import { useEffect, useId, useMemo, useRef } from 'react';
+import { assertWeekStart } from '../calendar-month.js';
+import { resolveDateFieldLabels, } from '../date-field-labels.js';
+import { dateEntryPattern, dateEntryPlaceholder } from '../date-entry.js';
+import { dateEntryValidity } from '../date-entry-validity.js';
+import { assertDateBounds, isOutsideDateRange } from '../date-only.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, disabled = false, required = false, description, error, locale, weekStartsOn = 0, labels, }) {
+    assertDateBounds(value, min, max);
+    assertWeekStart(weekStartsOn);
+    const words = resolveDateFieldLabels(labels);
+    const rootRef = useRef(null);
+    const controlRef = useRef(null);
+    const inputRef = useRef(null);
+    const resolvedLocale = useLangLocale(locale, rootRef);
+    const pattern = useMemo(() => dateEntryPattern(resolvedLocale), [resolvedLocale]);
+    const entry = useDateEntry(value, pattern, (next) => {
+        if (!disabled)
+            onChange(next);
+    });
+    const validity = dateEntryValidity(entry.parsed, words, min, max);
+    // Blocks form submission as the native date input's validity did.
+    useEffect(() => {
+        inputRef.current?.setCustomValidity(validity);
+    }, [validity]);
+    const { buttonRef, shown, toggle, trigger, dialog } = useCalendarPopup({
+        value,
+        disabled,
+        onChange,
+        beforeSelect: entry.reset,
+    });
     const inputId = useId();
+    const labelId = useId();
     const descriptionId = useId();
+    const entryErrorId = useId();
     const errorId = useId();
     const describedBy = [
         description ? descriptionId : null,
+        entry.invalid ? entryErrorId : null,
         error ? errorId : null,
     ]
         .filter((id) => id !== null)
         .join(' ');
-    const invalid = Boolean(error) || isOutsideDateRange(value, min, max);
-    return (_jsxs("div", { className: "sw-date-field", children: [_jsx("label", { className: "sw-date-field-label", htmlFor: inputId, children: label }), _jsx("input", { "aria-describedby": describedBy || undefined, "aria-invalid": invalid, className: "sw-date-field-input", disabled: disabled, id: inputId, max: max, min: min, onChange: (event) => {
-                    const next = event.currentTarget.value;
-                    if (!disabled &&
-                        !event.currentTarget.validity.badInput &&
-                        (next === '' || isDateOnly(next)))
-                        onChange(next);
-                }, required: required, type: "date", value: value }), description ? (_jsx("span", { className: "sw-date-field-description", id: descriptionId, children: description })) : null, error ? (_jsx("span", { className: "sw-date-field-error", id: errorId, children: error })) : null] }));
+    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: label }), _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, {
+                            day: words.dayPlaceholder,
+                            month: words.monthPlaceholder,
+                            year: words.yearPlaceholder,
+                        }), ref: inputRef, required: required, spellCheck: false, type: "text", value: entry.text }), _jsxs("button", { ...trigger, "aria-describedby": labelId, className: "sw-date-field-button", disabled: disabled, onClick: toggle, ref: buttonRef, type: "button", children: [_jsx("span", { className: "sw-sr-only", children: words.chooseDate }), _jsx(DateFieldGlyph, { name: "calendar" })] })] }), description ? (_jsx("span", { className: "sw-date-field-description", id: descriptionId, children: description })) : null, entry.invalid ? (_jsx("span", { className: "sw-date-field-error", id: entryErrorId, children: words.invalidEntry })) : null, error ? (_jsx("span", { className: "sw-date-field-error", id: errorId, children: error })) : null, shown ? (_jsx(CalendarDialog, { ...dialog, buttonRef: buttonRef, anchorRef: controlRef, labelId: labelId, labels: words, locale: resolvedLocale, max: max, min: min, required: required, value: value, weekStartsOn: weekStartsOn })) : null] }));
 }

package/dist/components/Field.d.ts

@@ -10,5 +10,9 @@ export type FieldProps = {
     description?: string;
     error?: string;
     required?: boolean;
+    /** 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;
 };
-export declare function Field({ children, gap, label, labelVisuallyHidden, size, description, error, required, }: FieldProps): import("react").JSX.Element;
+export declare function Field({ children, gap, label, labelVisuallyHidden, size, description, error, required, prefix, suffix, }: FieldProps): import("react").JSX.Element;

package/dist/components/Field.js

@@ -1,13 +1,18 @@
 'use client';
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { cloneElement, isValidElement, useId } from 'react';
+import { adornedControlAria, FieldAdornment, } from './FieldAdornment.js';
 import { Stack } from './Stack.js';
 import { Text } from './Text.js';
-export function Field({ children, gap = 1, label, labelVisuallyHidden = false, size = 'md', description, error, required = false, }) {
+export function Field({ children, gap = 1, label, labelVisuallyHidden = false, size = 'md', description, error, required = false, prefix, suffix, }) {
     const controlId = useId();
     const messageId = useId();
+    const labelId = useId();
+    const prefixId = useId();
+    const suffixId = useId();
     const message = error || description;
-    const needsControl = Boolean(message || required);
+    const adorned = Boolean(prefix || suffix);
+    const needsControl = Boolean(message || required || adorned);
     const className = [
         'sw-field',
         size === 'xs' && 'sw-field-xs',
@@ -20,11 +25,17 @@ export function Field({ children, gap = 1, label, labelVisuallyHidden = false, s
         typeof children.type !== 'string' ||
         !['input', 'select', 'textarea'].includes(children.type)) {
         if (needsControl)
-            throw new TypeError('Field validation requires one native input, select, or textarea child');
+            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] }));
     }
+    if (adorned && children.type !== 'input')
+        throw new TypeError('Field prefix and suffix require a native input child');
+    const adornment = adorned
+        ? adornedControlAria(children.props, labelId, prefix ? prefixId : undefined, suffix ? suffixId : undefined)
+        : { labelledBy: children.props['aria-labelledby'] };
     const describedBy = [
         children.props['aria-describedby'],
+        adornment.describedBy,
         message ? messageId : null,
     ]
         .filter(Boolean)
@@ -33,7 +44,8 @@ export function Field({ children, gap = 1, label, labelVisuallyHidden = false, s
         id: children.props.id || controlId,
         'aria-describedby': describedBy || undefined,
         'aria-invalid': error ? true : children.props['aria-invalid'],
+        'aria-labelledby': adornment.labelledBy,
         required: required || children.props.required,
     });
-    return (_jsxs(Stack, { as: "div", className: className, gap: labelVisuallyHidden ? 0 : gap, children: [_jsx("label", { htmlFor: children.props.id || controlId, children: labelText }), control, message ? (_jsx("span", { className: error ? 'sw-field-error' : 'sw-field-description', id: messageId, role: error ? 'alert' : undefined, children: message })) : null] }));
+    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), message ? (_jsx("span", { className: error ? 'sw-field-error' : 'sw-field-description', id: messageId, role: error ? 'alert' : undefined, children: message })) : null] }));
 }

package/dist/components/FieldAdornment.d.ts

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react';
+export type FieldAdornmentProps = {
+    children: ReactNode;
+    prefix?: string;
+    prefixId: string;
+    suffix?: string;
+    suffixId: string;
+};
+export declare function FieldAdornment({ children, prefix, prefixId, suffix, suffixId, }: FieldAdornmentProps): import("react").JSX.Element;
+export type AdornedControlNaming = {
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+};
+export type AdornedControlAria = {
+    /** The input's `aria-labelledby`; undefined keeps the input's own name. */
+    labelledBy?: string;
+    /** Adornment ids to add to the input's `aria-describedby`, if any. */
+    describedBy?: string;
+};
+export declare function adornedControlAria(own: AdornedControlNaming, labelId: string, prefixId: string | undefined, suffixId: string | undefined): AdornedControlAria;

package/dist/components/FieldAdornment.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * A press on the frame's own chrome (the prefix, the suffix or the padding)
+ * focuses the input, as the text cursor over the frame promises. A press on
+ * the input itself keeps the browser's own caret placement and selection.
+ */
+function focusAdornedInput(event) {
+    const input = event.currentTarget.querySelector('input');
+    if (!input || input.disabled || event.target === input)
+        return;
+    event.preventDefault();
+    input.focus();
+}
+/*
+ * Draws the control frame around a native input with short text before or
+ * after it. The text is hidden from the reading order so it is not read twice:
+ * the input names or describes itself with this text by id (see
+ * `adornedControlAria`), which still reads a hidden node it references directly.
+ */
+export function FieldAdornment({ children, prefix, prefixId, suffix, suffixId, }) {
+    return (_jsxs("span", { className: "sw-field-adorned", onMouseDown: focusAdornedInput, children: [prefix ? (_jsx("span", { "aria-hidden": "true", className: "sw-field-prefix", id: prefixId, children: prefix })) : null, children, suffix ? (_jsx("span", { "aria-hidden": "true", className: "sw-field-suffix", id: suffixId, children: suffix })) : null] }));
+}
+/*
+ * An adorned input is named by its label plus the adornment ("Drop amount $").
+ * When the input already names itself with `aria-label` or `aria-labelledby`,
+ * that name stands and the adornment describes the input instead, so the unit
+ * is still read.
+ */
+export function adornedControlAria(own, labelId, prefixId, suffixId) {
+    const adornment = [prefixId, suffixId].filter(Boolean).join(' ');
+    if (own['aria-label'] || own['aria-labelledby'])
+        return { labelledBy: own['aria-labelledby'], describedBy: adornment };
+    return { labelledBy: [labelId, adornment].join(' ') };
+}

package/dist/components/Grid.d.ts

@@ -2,10 +2,13 @@ import { type SpacingStep } from '@scalewing/tokens';
 import { type Breakpoint } from '../css/breakpoints.js';
 import { type GridColumns } from '../css/css-grid.js';
 import { type BoxProps } from './Box.js';
+import { type Align } from './Stack.js';
 export type { GridColumns };
 export type GridProps = BoxProps & {
+    /** Where each child sits in the height of its row; unset, children stretch. */
+    align?: Align;
     columns?: GridColumns;
     columnsBelow?: Partial<Record<Breakpoint, GridColumns>>;
     gap?: SpacingStep;
 };
-export declare function Grid({ className, columns, columnsBelow, gap, ...rest }: GridProps): import("react").JSX.Element;
+export declare function Grid({ align, className, columns, columnsBelow, gap, ...rest }: GridProps): import("react").JSX.Element;