@scalewing/react 1.8.0 → 1.9.0

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/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,70 @@
 '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, useState } from 'react';
+import { resolveDateFieldLabels, } from '../date-field-labels.js';
+import { dateEntryPattern, dateEntryPlaceholder } from '../date-entry.js';
+import { dateEntryValidity } from '../date-entry-validity.js';
+import { assertDateBounds, isOutsideDateRange, todayDateOnly, } from '../date-only.js';
+import { CalendarDialog } from './date-field/CalendarDialog.js';
+import { DateFieldGlyph } from './date-field/DateFieldGlyph.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);
+    if (weekStartsOn !== 0 && weekStartsOn !== 1)
+        throw new RangeError('weekStartsOn must be 0 or 1');
+    const words = resolveDateFieldLabels(labels);
+    const rootRef = useRef(null);
+    const controlRef = useRef(null);
+    const buttonRef = 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 [open, setOpen] = useState(false);
+    // Disabling the field closes its calendar for good, not just while disabled.
+    if (disabled && open)
+        setOpen(false);
+    const shown = open && !disabled;
     const inputId = useId();
+    const labelId = useId();
+    const dialogId = 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);
+    function close(restoreFocus) {
+        setOpen(false);
+        if (restoreFocus)
+            buttonRef.current?.focus();
+    }
+    function select(next) {
+        entry.reset();
+        close(true);
+        if (next !== value)
+            onChange(next);
+    }
+    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", { "aria-controls": shown ? dialogId : undefined, "aria-expanded": shown, "aria-haspopup": "dialog", "aria-describedby": labelId, className: "sw-date-field-button", disabled: disabled, onClick: () => (shown ? close(true) : setOpen(true)), 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, { anchorRef: controlRef, buttonRef: buttonRef, id: dialogId, labelId: labelId, labels: words, locale: resolvedLocale, max: max, min: min, onClose: close, onSelect: select, required: required, today: todayDateOnly(), 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;

package/dist/components/Grid.js

@@ -5,7 +5,7 @@ import { gridColumnsBelowClass, gridColumnsClass, } from '../css/css-grid.js';
 import { spacingClass } from '../css/spacing-classes.js';
 import { assertGridCount } from '../grid-counts.js';
 import { Box } from './Box.js';
-export function Grid({ className, columns = 1, columnsBelow, gap = 0, ...rest }) {
+export function Grid({ align, className, columns = 1, columnsBelow, gap = 0, ...rest }) {
     assertGridCount('columns', columns);
     const belowClasses = breakpoints.flatMap((breakpoint) => {
         const count = columnsBelow?.[breakpoint];
@@ -14,5 +14,5 @@ export function Grid({ className, columns = 1, columnsBelow, gap = 0, ...rest })
         assertGridCount('columnsBelow', count);
         return [gridColumnsBelowClass(breakpoint, count)];
     });
-    return (_jsx(Box, { className: cx('sw-grid', gridColumnsClass(columns), ...belowClasses, spacingClass('gap', 'all', gap), className), ...rest }));
+    return (_jsx(Box, { className: cx('sw-grid', gridColumnsClass(columns), ...belowClasses, spacingClass('gap', 'all', gap), align && `sw-align-${align}`, className), ...rest }));
 }

package/dist/components/Progress.d.ts

@@ -4,5 +4,7 @@ export type ProgressProps = {
     value: number;
     max: number;
     tone?: ProgressTone;
+    /** Shows the muted "value / max" count beside the label. Turn it off when the page shows its own count. */
+    showCount?: boolean;
 };
-export declare function Progress({ label, value, max, tone, }: ProgressProps): import("react").JSX.Element;
+export declare function Progress({ label, value, max, tone, showCount, }: ProgressProps): import("react").JSX.Element;

package/dist/components/Progress.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId } from 'react';
-export function Progress({ label, value, max, tone = 'accent', }) {
+export function Progress({ label, value, max, tone = 'accent', showCount = true, }) {
     if (!label.trim())
         throw new RangeError('label must not be empty');
     if (!Number.isFinite(max) || max <= 0)
@@ -9,5 +9,5 @@ export function Progress({ label, value, max, tone = 'accent', }) {
     if (!Number.isFinite(value) || value < 0 || value > max)
         throw new RangeError('value must be finite and within 0..max');
     const labelId = useId();
-    return (_jsxs("div", { className: `sw-progress sw-progress-${tone}`, children: [_jsxs("div", { className: "sw-progress-heading", children: [_jsx("span", { className: "sw-progress-label", id: labelId, children: label }), _jsxs("span", { "aria-hidden": "true", className: "sw-progress-count", children: [value, " / ", max] })] }), _jsx("progress", { "aria-labelledby": labelId, className: "sw-progress-bar", max: max, value: value })] }));
+    return (_jsxs("div", { className: `sw-progress sw-progress-${tone}`, children: [_jsxs("div", { className: "sw-progress-heading", children: [_jsx("span", { className: "sw-progress-label", id: labelId, children: label }), showCount ? (_jsxs("span", { "aria-hidden": "true", className: "sw-progress-count", children: [value, " / ", max] })) : null] }), _jsx("progress", { "aria-labelledby": labelId, className: "sw-progress-bar", max: max, value: value })] }));
 }

package/dist/components/date-field/CalendarDialog.d.ts

@@ -0,0 +1,26 @@
+import { type RefObject } from 'react';
+import { type WeekStart } from '../../calendar-month.js';
+import { type DateFieldLabels } from '../../date-field-labels.js';
+export type CalendarDialogProps = {
+    anchorRef: RefObject<HTMLElement | null>;
+    buttonRef: RefObject<HTMLElement | null>;
+    id: string;
+    labelId: string;
+    labels: DateFieldLabels;
+    locale: string;
+    max?: string;
+    min?: string;
+    /** `true` returns focus to the calendar button. */
+    onClose: (restoreFocus: boolean) => void;
+    onSelect: (value: string) => void;
+    required: boolean;
+    today: string;
+    value: string;
+    weekStartsOn: WeekStart;
+};
+/**
+ * The calendar popover: a labelled modal dialog anchored under the field,
+ * following the WAI-ARIA date picker dialog pattern. It opens on the
+ * selected day, or today, kept inside `[min, max]`.
+ */
+export declare function CalendarDialog({ anchorRef, buttonRef, id, labelId, labels, locale, max, min, onClose, onSelect, required, today, value, weekStartsOn, }: CalendarDialogProps): import("react").JSX.Element;

package/dist/components/date-field/CalendarDialog.js

@@ -0,0 +1,93 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useLayoutEffect, useRef, useState, } from 'react';
+import { monthOf, } from '../../calendar-month.js';
+import { clampDateOnly, daysInMonth, formatDateOnly, isOutsideDateRange, parseDateOnly, } from '../../date-only.js';
+import { Button } from '../Button.js';
+import { CalendarGrid } from './CalendarGrid.js';
+import { CalendarHeader } from './CalendarHeader.js';
+import { useAnchoredPopover } from './use-anchored-popover.js';
+/** The dialog's tab stops: enabled buttons and the grid's roving day. */
+function isTabStop(node) {
+    if (node instanceof HTMLButtonElement)
+        return !node.disabled;
+    return node.getAttribute('tabindex') === '0';
+}
+/** Keeps Tab and Shift+Tab inside the dialog, as a modal dialog does. */
+function wrapTab(event) {
+    // One universal selector keeps document order in every DOM implementation.
+    const items = [
+        ...event.currentTarget.querySelectorAll('*'),
+    ].filter(isTabStop);
+    const first = items[0];
+    const last = items[items.length - 1];
+    if (!first || !last)
+        return;
+    if (event.shiftKey && document.activeElement === first) {
+        event.preventDefault();
+        last.focus();
+    }
+    else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault();
+        first.focus();
+    }
+}
+function sameDayIn(month, focused) {
+    const day = parseDateOnly(focused)?.day ?? 1;
+    return formatDateOnly({
+        ...month,
+        day: Math.min(day, daysInMonth(month.year, month.month)),
+    });
+}
+/**
+ * The calendar popover: a labelled modal dialog anchored under the field,
+ * following the WAI-ARIA date picker dialog pattern. It opens on the
+ * selected day, or today, kept inside `[min, max]`.
+ */
+export function CalendarDialog({ anchorRef, buttonRef, id, labelId, labels, locale, max, min, onClose, onSelect, required, today, value, weekStartsOn, }) {
+    const titleId = useId();
+    const dialogRef = useRef(null);
+    const [rawFocusDate, setFocusDate] = useState(value || today);
+    // A new value while open moves the calendar to it.
+    const [shownValue, setShownValue] = useState(value);
+    if (value !== shownValue) {
+        setShownValue(value);
+        if (value !== '')
+            setFocusDate(value);
+    }
+    // Clamped on every render, so new bounds while open move it inside.
+    const focusDate = clampDateOnly(rawFocusDate, min, max);
+    const month = monthOf(focusDate);
+    // Opening and grid keys move DOM focus to the focus date; header controls
+    // and presses change the date without taking focus from where it is.
+    const focusGrid = useRef(true);
+    useAnchoredPopover(dialogRef, anchorRef, buttonRef, () => onClose(false));
+    // Whether a day holds DOM focus. Removing that day fires no blur, so this
+    // stays true when a new value or bounds move the grid out from under it.
+    const gridFocused = useRef(false);
+    useLayoutEffect(() => {
+        if (!focusGrid.current && !gridFocused.current)
+            return;
+        focusGrid.current = false;
+        dialogRef.current
+            ?.querySelector(`[role="grid"] [data-date="${focusDate}"]`)
+            ?.focus({ preventScroll: true });
+    }, [focusDate]);
+    function onKeyDown(event) {
+        if (event.key === 'Escape') {
+            event.preventDefault();
+            event.stopPropagation();
+            onClose(true);
+        }
+        else if (event.key === 'Tab')
+            wrapTab(event);
+    }
+    const todayUnavailable = isOutsideDateRange(today, min, max);
+    return (_jsxs("div", { "aria-labelledby": labelId, "aria-modal": "true", className: "sw-date-field-calendar", id: id, onBlur: () => {
+            gridFocused.current = false;
+        }, onFocus: (event) => {
+            gridFocused.current = event.target.closest('[role="grid"]') !== null;
+        }, onKeyDown: onKeyDown, ref: dialogRef, role: "dialog", children: [_jsx(CalendarHeader, { labels: labels, locale: locale, max: max, min: min, month: month, onMonthChange: (next) => setFocusDate(sameDayIn(next, focusDate)), titleId: titleId, todayYear: monthOf(today).year }), _jsx(CalendarGrid, { focusDate: focusDate, locale: locale, max: max, min: min, month: month, onFocusDate: setFocusDate, onMoveFocus: (next) => {
+                    focusGrid.current = true;
+                    setFocusDate(next);
+                }, onSelect: onSelect, selected: value, titleId: titleId, today: today, weekStartsOn: weekStartsOn }), _jsxs("div", { className: "sw-date-field-footer", children: [required ? null : (_jsx(Button, { disabled: value === '', onPress: () => onSelect(''), size: "sm", variant: "ghost", children: labels.clear })), _jsx(Button, { disabled: todayUnavailable, onPress: () => onSelect(today), size: "sm", variant: "ghost", children: labels.today })] })] }));
+}

package/dist/components/date-field/CalendarGrid.d.ts

@@ -0,0 +1,23 @@
+import { type CalendarMonth, type WeekStart } from '../../calendar-month.js';
+export type CalendarGridProps = {
+    focusDate: string;
+    locale: string;
+    max?: string;
+    min?: string;
+    month: CalendarMonth;
+    /** A cell took focus: follow it without moving focus. */
+    onFocusDate: (value: string) => void;
+    /** A grid key chose a day: focus it. */
+    onMoveFocus: (value: string) => void;
+    onSelect: (value: string) => void;
+    selected: string;
+    titleId: string;
+    today: string;
+    weekStartsOn: WeekStart;
+};
+/**
+ * The month as a WAI-ARIA grid with one roving tab stop. Days outside
+ * `[min, max]` stay focusable for orientation but are `aria-disabled`;
+ * padding past the four-digit years is blank and inert.
+ */
+export declare function CalendarGrid({ focusDate, locale, max, min, month, onFocusDate, onMoveFocus, onSelect, selected, titleId, today, weekStartsOn, }: CalendarGridProps): import("react").JSX.Element;

package/dist/components/date-field/CalendarGrid.js

@@ -0,0 +1,36 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../../class-names.js';
+import { calendarKeyTarget } from '../../calendar-keys.js';
+import { formatDateLabel, weekdayLabels } from '../../calendar-labels.js';
+import { monthGrid, } from '../../calendar-month.js';
+import { isOutsideDateRange } from '../../date-only.js';
+/**
+ * The month as a WAI-ARIA grid with one roving tab stop. Days outside
+ * `[min, max]` stay focusable for orientation but are `aria-disabled`;
+ * padding past the four-digit years is blank and inert.
+ */
+export function CalendarGrid({ focusDate, locale, max, min, month, onFocusDate, onMoveFocus, onSelect, selected, titleId, today, weekStartsOn, }) {
+    function choose(value) {
+        if (!isOutsideDateRange(value, min, max))
+            onSelect(value);
+    }
+    function onKeyDown(event) {
+        if (event.key === 'Enter' || event.key === ' ') {
+            event.preventDefault();
+            choose(focusDate);
+            return;
+        }
+        const rtl = getComputedStyle(event.currentTarget).direction === 'rtl';
+        const target = calendarKeyTarget({ key: event.key, shiftKey: event.shiftKey }, focusDate, { weekStartsOn, min, max, rtl });
+        if (target === null)
+            return;
+        event.preventDefault();
+        onMoveFocus(target);
+    }
+    return (_jsxs("table", { "aria-labelledby": titleId, className: "sw-date-field-grid", onKeyDown: onKeyDown, role: "grid", children: [_jsx("thead", { children: _jsx("tr", { children: weekdayLabels(locale, weekStartsOn).map((weekday) => (_jsx("th", { abbr: weekday.long, scope: "col", children: weekday.short }, weekday.long))) }) }), _jsx("tbody", { children: monthGrid(month, weekStartsOn).map((row, rowIndex) => (_jsx("tr", { children: row.map((cell, column) => cell === null ? (_jsx("td", { "aria-disabled": "true", className: "sw-date-field-day sw-date-field-day-outside", role: "gridcell" }, `blank-${column}`)) : (_jsx("td", { "aria-current": cell.value === today ? 'date' : undefined, "aria-disabled": isOutsideDateRange(cell.value, min, max) || undefined, "aria-label": formatDateLabel(cell.value, locale), "aria-selected": cell.value === selected, className: cx('sw-date-field-day', !cell.inMonth && 'sw-date-field-day-outside'), "data-date": cell.value, onClick: () => choose(cell.value), onFocus: () => {
+                            // A press on a neighboring month's day selects it; moving
+                            // the grid first would pull the day out from under it.
+                            if (cell.inMonth && cell.value !== focusDate)
+                                onFocusDate(cell.value);
+                        }, role: "gridcell", tabIndex: cell.value === focusDate ? 0 : -1, children: cell.day }, cell.value))) }, rowIndex))) })] }));
+}

package/dist/components/date-field/CalendarHeader.d.ts

@@ -0,0 +1,18 @@
+import { type CalendarMonth } from '../../calendar-month.js';
+import { type DateFieldLabels } from '../../date-field-labels.js';
+export type CalendarHeaderProps = {
+    labels: DateFieldLabels;
+    locale: string;
+    max?: string;
+    min?: string;
+    month: CalendarMonth;
+    onMonthChange: (month: CalendarMonth) => void;
+    titleId: string;
+    todayYear: number;
+};
+/**
+ * Month stepping plus month and year selectors for jumping far, both cut to
+ * `min` and `max`, over a visually hidden title that announces the shown
+ * month when it changes.
+ */
+export declare function CalendarHeader({ labels, locale, max, min, month, onMonthChange, titleId, todayYear, }: CalendarHeaderProps): import("react").JSX.Element;

package/dist/components/date-field/CalendarHeader.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { monthNames, monthTitle } from '../../calendar-labels.js';
+import { monthInRange, monthsInRange, shiftMonth, } from '../../calendar-month.js';
+import { calendarYearRange, yearsIn } from '../../calendar-years.js';
+import { Select } from '../Select.js';
+import { DateFieldGlyph } from './DateFieldGlyph.js';
+function MonthStep({ delta, label, max, min, month, onMonthChange, }) {
+    const target = shiftMonth(month, delta);
+    const unavailable = target.year < 1 || target.year > 9999 || !monthInRange(target, min, max);
+    return (_jsx("button", { "aria-disabled": unavailable || undefined, "aria-label": label, className: "sw-date-field-step", onClick: () => {
+            if (!unavailable)
+                onMonthChange(target);
+        }, type: "button", children: _jsx(DateFieldGlyph, { name: delta < 0 ? 'previous' : 'next' }) }));
+}
+/**
+ * Month stepping plus month and year selectors for jumping far, both cut to
+ * `min` and `max`, over a visually hidden title that announces the shown
+ * month when it changes.
+ */
+export function CalendarHeader({ labels, locale, max, min, month, onMonthChange, titleId, todayYear, }) {
+    const range = calendarYearRange(month.year, todayYear, min, max);
+    const names = monthNames(locale);
+    const stepProps = { max, min, month, onMonthChange };
+    return (_jsxs("div", { className: "sw-date-field-header", children: [_jsx("h2", { "aria-live": "polite", className: "sw-sr-only", id: titleId, children: monthTitle(month, locale) }), _jsx(MonthStep, { ...stepProps, delta: -1, label: labels.previousMonth }), _jsxs("div", { className: "sw-date-field-jump", children: [_jsx(Select, { label: labels.month, labelVisuallyHidden: true, onChange: (next) => onMonthChange({ ...month, month: Number(next) }), 
+                        // Only months with a day inside the bounds; the shown one always is.
+                        options: monthsInRange(month.year, min, max).map((number) => ({
+                            value: String(number),
+                            label: names[number - 1] ?? String(number),
+                        })), size: "xs", value: String(month.month) }), _jsx(Select, { label: labels.year, labelVisuallyHidden: true, onChange: (next) => onMonthChange({ ...month, year: Number(next) }), options: yearsIn(range).map((year) => ({
+                            value: String(year),
+                            label: String(year),
+                        })), size: "xs", value: String(month.year) })] }), _jsx(MonthStep, { ...stepProps, delta: 1, label: labels.nextMonth })] }));
+}