@scalewing/react 1.8.0 → 1.10.0

package/dist/css/css-field.js

@@ -1,5 +1,58 @@
 import { typographyVariants } from '@scalewing/tokens';
+import { controlSurface } from './css-document.js';
 const caption = typographyVariants.caption;
+/*
+ * A prefix or suffix sits inside the control frame: the wrapper draws the
+ * canvas control surface and the focus ring, and the native input inside it
+ * drops its own frame so the text and the value read as one control.
+ */
+function adornmentRules() {
+    return `.sw-field-adorned {
+  ${controlSurface}
+  align-items: center;
+  box-sizing: border-box;
+  cursor: text;
+  display: flex;
+  gap: var(--sw-space-1);
+  min-height: var(--sw-control-md-min-height);
+}
+
+[data-theme] .sw-field-adorned > input {
+  align-self: stretch;
+  background: transparent;
+  border: 0;
+  border-radius: 0;
+  flex: 1 1 auto;
+  min-height: 0;
+  min-width: 0;
+  padding-inline: 0;
+}
+
+[data-theme] .sw-field-adorned > input:focus-visible { outline: none; }
+
+.sw-field-adorned:focus-within {
+  outline: var(--sw-focus-ring-width) solid var(--sw-color-accent);
+  outline-offset: var(--sw-focus-ring-offset);
+}
+
+.sw-field-prefix,
+.sw-field-suffix {
+  color: var(--sw-color-muted);
+  flex: none;
+  user-select: none;
+  white-space: nowrap;
+}
+
+.sw-field-xs .sw-field-adorned {
+  font-size: ${caption.fontSize}px;
+  letter-spacing: ${caption.letterSpacing}px;
+  line-height: ${caption.lineHeight}px;
+  min-height: var(--sw-control-xs-min-height);
+  padding-inline: var(--sw-control-xs-padding-inline);
+}
+
+.sw-field-invalid .sw-field-adorned { border-color: var(--sw-color-danger); }`;
+}
 export function cssFieldClasses() {
     return `.sw-field-required { color: var(--sw-color-danger); }
 
@@ -17,8 +70,12 @@ export function cssFieldClasses() {
   border-color: var(--sw-color-danger);
 }
 
+${adornmentRules()}
+
 @media (forced-colors: active) {
-  [data-theme] .sw-field-invalid :is(input, select, textarea) { border-color: Mark; }
+  [data-theme] .sw-field-invalid :is(input, select, textarea),
+  .sw-field-invalid .sw-field-adorned { border-color: Mark; }
+  .sw-field-prefix, .sw-field-suffix { color: CanvasText; }
   .sw-field-error, .sw-field-required { color: Mark; }
 }`;
 }
@@ -29,5 +86,8 @@ export function fieldClassCatalog() {
         'sw-field-description',
         'sw-field-error',
         'sw-field-invalid',
+        'sw-field-adorned',
+        'sw-field-prefix',
+        'sw-field-suffix',
     ];
 }

package/dist/css/css-select.js

@@ -1,4 +1,5 @@
 import { typographyVariants } from '@scalewing/tokens';
+import { zIndex } from './stacking.js';
 const caption = typographyVariants.caption;
 const label = typographyVariants.label;
 const chevronImage = `background-image:
@@ -88,7 +89,7 @@ export function cssSelectClasses() {
   padding: var(--sw-space-1);
   position: absolute;
   width: max-content;
-  z-index: 3;
+  ${zIndex('popup')}
 }
 
 .sw-select-option {

package/dist/css/css-tooltip.js

@@ -1,4 +1,5 @@
 import { typographyVariants } from '@scalewing/tokens';
+import { zIndex } from './stacking.js';
 const caption = typographyVariants.caption;
 export function cssTooltipClasses() {
     return `.sw-tooltip-anchor {
@@ -21,7 +22,7 @@ export function cssTooltipClasses() {
   padding: var(--sw-space-2);
   position: absolute;
   width: max-content;
-  z-index: 10;
+  ${zIndex('popup')}
 }
 
 .sw-tooltip[hidden] { display: none; }

package/dist/css/stacking.d.ts

@@ -0,0 +1,10 @@
+export declare const stackingOrder: {
+    readonly stickyCell: 1;
+    readonly bottomChrome: 2;
+    readonly popupHost: 3;
+    readonly topChrome: 4;
+    readonly popup: 10;
+};
+export type StackingLayer = keyof typeof stackingOrder;
+export declare function zIndex(layer: StackingLayer): string;
+export declare function cssPopupHostRules(): string;

package/dist/css/stacking.js

@@ -0,0 +1,49 @@
+/*
+ * The one stacking order of the generated stylesheet. Every generated
+ * `z-index` reads a layer from here, lowest first:
+ *
+ * 1. `stickyCell`: a sticky table header cell or row label over the cells
+ *    that scroll under it.
+ * 2. `bottomChrome`: the sticky ActionBar over the page flow it follows.
+ * 3. `popupHost`: a glass surface (glass Card, Accordion) while it holds an
+ *    open popup. Backdrop blur makes that surface its own stacking context, so
+ *    its popup can only paint as high as the surface does; lifting the surface
+ *    over the ActionBar keeps an open list tappable where the bar would cover
+ *    it, and over the next surface in the flow.
+ * 4. `topChrome`: the sticky AppHeader, over a lifted surface that scrolls up
+ *    under it (the header is the page's way back, and a popup opens downward).
+ * 5. `popup`: a popup outside any lifted surface (Select list, ActionMenu
+ *    list, Tooltip, the DateField and CalendarButton calendar) over
+ *    everything in the page.
+ *
+ * Dialog and Toast sit on the browser's top layer, above all of these.
+ */
+export const stackingOrder = {
+    stickyCell: 1,
+    bottomChrome: 2,
+    popupHost: 3,
+    topChrome: 4,
+    popup: 10,
+};
+export function zIndex(layer) {
+    return `z-index: ${stackingOrder[layer]};`;
+}
+const openPopups = [
+    '.sw-select-list',
+    '.sw-action-menu-list:not([hidden])',
+    '.sw-tooltip:not([hidden])',
+    // DateField and CalendarButton share it. Rendered only while open; on the
+    // top layer where the popover API exists.
+    '.sw-date-field-calendar',
+].join(', ');
+const popupHosts = ['.sw-card-glass', '.sw-accordion'];
+export function cssPopupHostRules() {
+    const selectors = popupHosts
+        .map((host) => `${host}:has(${openPopups})`)
+        .join(',\n');
+    return `/* Backdrop blur makes a glass surface its own stacking context, so it lifts while it holds an open popup (see stacking.ts). */
+${selectors} {
+  position: relative;
+  ${zIndex('popupHost')}
+}`;
+}

package/dist/css/stylesheet.js

@@ -1,8 +1,10 @@
 import { cardVariants, darkTheme, lightTheme, typographyVariants, } from '@scalewing/tokens';
+import { actionBarClassCatalog } from './css-action-bar.js';
 import { actionMenuClassCatalog } from './css-action-menu.js';
 import { accordionClassCatalog } from './css-accordion.js';
 import { switchClassCatalog } from './css-switch.js';
 import { dateFieldClassCatalog } from './css-date-field.js';
+import { calendarButtonClassCatalog } from './css-calendar-button.js';
 import { checkboxClassCatalog } from './css-checkbox.js';
 import { radioGroupClassCatalog } from './css-radio-group.js';
 import { spinnerClassCatalog } from './css-spinner.js';
@@ -17,6 +19,7 @@ import { gridClassCatalog } from './css-grid.js';
 import { gridSpanClassCatalog } from './css-grid-span.js';
 import { denominationGridClassCatalog } from './css-denomination-grid.js';
 import { fieldClassCatalog } from './css-field.js';
+import { boxBorderClassCatalog } from './css-box-border.js';
 import { cssComponentClasses } from './css-components.js';
 import { buttonClassCatalog } from './css-button.js';
 import { chartClassCatalog } from './css-chart.js';
@@ -52,8 +55,10 @@ export function utilityClassCatalog() {
         ...accordionClassCatalog(),
         ...selectClassCatalog(),
         ...actionMenuClassCatalog(),
+        ...actionBarClassCatalog(),
         ...switchClassCatalog(),
         ...dateFieldClassCatalog(),
+        ...calendarButtonClassCatalog(),
         ...checkboxClassCatalog(),
         ...radioGroupClassCatalog(),
         ...spinnerClassCatalog(),
@@ -70,6 +75,7 @@ export function utilityClassCatalog() {
         ...splitClassCatalog(),
         ...toastClassCatalog(),
         ...responsiveClassCatalog(),
+        ...boxBorderClassCatalog(),
     ];
 }
 export { generatePaletteStylesheet, paletteStylesheetIds, } from './css-palettes.js';

package/dist/date-entry-validity.d.ts

@@ -0,0 +1,10 @@
+import { type DateFieldLabels } from './date-field-labels.js';
+/**
+ * The message a date entry reports through `setCustomValidity`, so a form
+ * will not submit while it shows something other than an allowed date, as
+ * a native date input's `badInput`, `rangeUnderflow` and `rangeOverflow`
+ * would block it. `parsed` is the date the text forms, '' when blank, or
+ * null when the text is not a date. Empty means valid; `required` covers a
+ * blank entry.
+ */
+export declare function dateEntryValidity(parsed: string | null, labels: Pick<DateFieldLabels, 'invalidEntry' | 'outOfRange'>, min?: string, max?: string): string;

package/dist/date-entry-validity.js

@@ -0,0 +1,16 @@
+import { isOutsideDateRange } from './date-only.js';
+/**
+ * The message a date entry reports through `setCustomValidity`, so a form
+ * will not submit while it shows something other than an allowed date, as
+ * a native date input's `badInput`, `rangeUnderflow` and `rangeOverflow`
+ * would block it. `parsed` is the date the text forms, '' when blank, or
+ * null when the text is not a date. Empty means valid; `required` covers a
+ * blank entry.
+ */
+export function dateEntryValidity(parsed, labels, min, max) {
+    if (parsed === null)
+        return labels.invalidEntry;
+    if (isOutsideDateRange(parsed, min, max))
+        return labels.outOfRange;
+    return '';
+}

package/dist/date-entry.d.ts

@@ -0,0 +1,32 @@
+export type DateEntryPart = 'day' | 'month' | 'year';
+/** How a locale writes a numeric date: field order and the separator. */
+export type DateEntryPattern = {
+    order: readonly [DateEntryPart, DateEntryPart, DateEntryPart];
+    separator: string;
+};
+/**
+ * Reads the numeric field order and separator from `Intl` for `locale`, for
+ * example month/day/year with "/" for en-US and day.month.year for de.
+ */
+export declare function dateEntryPattern(locale: string): DateEntryPattern;
+/** Zero-padded, Latin digits in the pattern's order; empty for no date. */
+export declare function formatDateEntry(value: string, pattern: DateEntryPattern): string;
+/** A hint such as "MM/DD/YYYY" from the consumer's per-part letters. */
+export declare function dateEntryPlaceholder(pattern: DateEntryPattern, letters: Record<DateEntryPart, string>): string;
+/**
+ * Whether typed text is finished, so a date it forms can be committed while
+ * the person is still typing: eight bare digits, or three fields whose last
+ * one is at full width (four year digits, two for a trailing day or month).
+ * A shorter last field may still grow, as "2024-03-1" on the way to
+ * "2024-03-10", so it waits for blur or Enter instead.
+ */
+export declare function isCompleteDateEntry(text: string, pattern: DateEntryPattern): boolean;
+/**
+ * Parses typed text in the pattern's order. Day and month take one or two
+ * digits, the year exactly four, and any non-digit run separates fields.
+ * Eight bare digits split by field width in the same order (MMDDYYYY for
+ * en-US). A four-digit first field reads as ISO year-month-day in every
+ * locale, since no locale starts a day or month with four digits. Returns
+ * the YYYY-MM-DD value, '' for blank text, or null when it is not a date.
+ */
+export declare function parseDateEntry(text: string, pattern: DateEntryPattern): string | null;

package/dist/date-entry.js

@@ -0,0 +1,106 @@
+import { dateFormatter, formatterDate } from './date-formatters.js';
+import { formatDateOnly, isValidDateParts, parseDateOnly, } from './date-only.js';
+const FALLBACK = {
+    order: ['month', 'day', 'year'],
+    separator: '/',
+};
+function isEntryPart(type) {
+    return type === 'day' || type === 'month' || type === 'year';
+}
+/**
+ * Reads the numeric field order and separator from `Intl` for `locale`, for
+ * example month/day/year with "/" for en-US and day.month.year for de.
+ */
+export function dateEntryPattern(locale) {
+    const parts = dateFormatter(locale, {
+        day: '2-digit',
+        month: '2-digit',
+        year: 'numeric',
+    }).formatToParts(formatterDate({ year: 2023, month: 12, day: 31 }));
+    const order = parts.map((part) => part.type).filter(isEntryPart);
+    const separator = parts.find((part) => part.type === 'literal')?.value;
+    if (order.length !== 3 || new Set(order).size !== 3 || !separator?.trim())
+        return FALLBACK;
+    return {
+        order: [order[0], order[1], order[2]],
+        separator: separator.trim(),
+    };
+}
+const WIDTH = { day: 2, month: 2, year: 4 };
+/** Zero-padded, Latin digits in the pattern's order; empty for no date. */
+export function formatDateEntry(value, pattern) {
+    const parts = parseDateOnly(value);
+    if (!parts)
+        return '';
+    return pattern.order
+        .map((part) => String(parts[part]).padStart(WIDTH[part], '0'))
+        .join(pattern.separator);
+}
+/** A hint such as "MM/DD/YYYY" from the consumer's per-part letters. */
+export function dateEntryPlaceholder(pattern, letters) {
+    return pattern.order.map((part) => letters[part]).join(pattern.separator);
+}
+function splitDigits(text, pattern) {
+    const groups = text.match(/\d+/g) ?? [];
+    if (groups.length === 3)
+        return groups;
+    // Eight digits with no separators, as typed on a numeric keypad.
+    const digits = groups[0];
+    if (groups.length !== 1 || digits?.length !== 8)
+        return null;
+    let start = 0;
+    return pattern.order.map((part) => {
+        const group = digits.slice(start, start + WIDTH[part]);
+        start += WIDTH[part];
+        return group;
+    });
+}
+const ISO_ORDER = ['year', 'month', 'day'];
+/** The field order typed text uses: ISO when it starts with four digits. */
+function typedOrder(groups, pattern) {
+    return groups[0]?.length === 4 ? ISO_ORDER : pattern.order;
+}
+/**
+ * Whether typed text is finished, so a date it forms can be committed while
+ * the person is still typing: eight bare digits, or three fields whose last
+ * one is at full width (four year digits, two for a trailing day or month).
+ * A shorter last field may still grow, as "2024-03-1" on the way to
+ * "2024-03-10", so it waits for blur or Enter instead.
+ */
+export function isCompleteDateEntry(text, pattern) {
+    const groups = text.match(/\d+/g) ?? [];
+    if (groups.length === 1)
+        return groups[0]?.length === 8;
+    if (groups.length !== 3)
+        return false;
+    const last = typedOrder(groups, pattern)[2];
+    return groups[2]?.length === WIDTH[last];
+}
+/**
+ * Parses typed text in the pattern's order. Day and month take one or two
+ * digits, the year exactly four, and any non-digit run separates fields.
+ * Eight bare digits split by field width in the same order (MMDDYYYY for
+ * en-US). A four-digit first field reads as ISO year-month-day in every
+ * locale, since no locale starts a day or month with four digits. Returns
+ * the YYYY-MM-DD value, '' for blank text, or null when it is not a date.
+ */
+export function parseDateEntry(text, pattern) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return '';
+    if (/\p{L}/u.test(trimmed))
+        return null;
+    const groups = splitDigits(trimmed, pattern);
+    if (!groups)
+        return null;
+    const order = typedOrder(groups, pattern);
+    const date = { year: 0, month: 0, day: 0 };
+    for (const [index, part] of order.entries()) {
+        const digits = groups[index] ?? '';
+        const width = part === 'year' ? digits.length === 4 : digits.length <= 2;
+        if (!width)
+            return null;
+        date[part] = Number(digits);
+    }
+    return isValidDateParts(date) ? formatDateOnly(date) : null;
+}

package/dist/date-field-labels.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Words the DateField control speaks or shows on its own. Products pass
+ * their translations; month and weekday names come from `Intl` instead.
+ */
+export type DateFieldLabels = {
+    /**
+     * Calendar button name; the field label describes the button. A page with
+     * several date fields may pass a distinct name per field.
+     */
+    chooseDate: string;
+    previousMonth: string;
+    nextMonth: string;
+    /** Month selector name in the calendar header. */
+    month: string;
+    /** Year selector name in the calendar header. */
+    year: string;
+    /** Selects today's date and closes the calendar. */
+    today: string;
+    /** Empties an optional field and closes the calendar. */
+    clear: string;
+    /**
+     * Shown when typed text is not a date; also the entry's form validation
+     * message while its text is not a date.
+     */
+    invalidEntry: string;
+    /**
+     * The entry's form validation message while its date, typed or given, is
+     * outside `min` and `max`.
+     */
+    outOfRange: string;
+    /** Placeholder letters, arranged in the locale's field order. */
+    dayPlaceholder: string;
+    monthPlaceholder: string;
+    yearPlaceholder: string;
+};
+export declare const defaultDateFieldLabels: DateFieldLabels;
+/** Consumer labels over the English defaults; empty strings fail closed. */
+export declare function resolveDateFieldLabels(labels?: Partial<DateFieldLabels>): DateFieldLabels;

package/dist/date-field-labels.js

@@ -0,0 +1,22 @@
+export const defaultDateFieldLabels = {
+    chooseDate: 'Choose date',
+    previousMonth: 'Previous month',
+    nextMonth: 'Next month',
+    month: 'Month',
+    year: 'Year',
+    today: 'Today',
+    clear: 'Clear',
+    invalidEntry: 'Enter a valid date.',
+    outOfRange: 'Choose a date in the allowed range.',
+    dayPlaceholder: 'DD',
+    monthPlaceholder: 'MM',
+    yearPlaceholder: 'YYYY',
+};
+/** Consumer labels over the English defaults; empty strings fail closed. */
+export function resolveDateFieldLabels(labels = {}) {
+    const resolved = { ...defaultDateFieldLabels, ...labels };
+    for (const [key, text] of Object.entries(resolved))
+        if (typeof text !== 'string' || text.trim() === '')
+            throw new RangeError(`labels.${key} must be non-empty text`);
+    return resolved;
+}

package/dist/date-field-locale.d.ts

@@ -0,0 +1,8 @@
+/** Used when neither the `locale` prop nor an ancestor `lang` names one. */
+export declare const DEFAULT_DATE_LOCALE = "en-US";
+/**
+ * The locale a date control formats with. An explicit `locale` must be a
+ * valid BCP 47 tag, or this throws. Otherwise the nearest `lang` attribute
+ * is used when the runtime supports it, then en-US.
+ */
+export declare function resolveDateLocale(locale: string | undefined, documentLang: string | null | undefined): string;

package/dist/date-field-locale.js

@@ -0,0 +1,27 @@
+/** Used when neither the `locale` prop nor an ancestor `lang` names one. */
+export const DEFAULT_DATE_LOCALE = 'en-US';
+function supported(tag) {
+    try {
+        return Intl.DateTimeFormat.supportedLocalesOf([tag]).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The locale a date control formats with. An explicit `locale` must be a
+ * valid BCP 47 tag, or this throws. Otherwise the nearest `lang` attribute
+ * is used when the runtime supports it, then en-US.
+ */
+export function resolveDateLocale(locale, documentLang) {
+    if (locale !== undefined) {
+        try {
+            return Intl.getCanonicalLocales(locale)[0] ?? DEFAULT_DATE_LOCALE;
+        }
+        catch {
+            throw new RangeError('locale must be a BCP 47 language tag');
+        }
+    }
+    const lang = documentLang?.trim();
+    return lang && supported(lang) ? lang : DEFAULT_DATE_LOCALE;
+}

package/dist/date-formatters.d.ts

@@ -0,0 +1,13 @@
+import { type DateParts } from './date-only.js';
+/**
+ * One shared `Intl.DateTimeFormat` per locale and options, since building
+ * one is slow and a calendar formats dozens of dates per render. Every
+ * formatter reads UTC, so a cached one never meets a changed device time
+ * zone; pair it with `formatterDate`.
+ */
+export declare function dateFormatter(locale: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat;
+/**
+ * Noon UTC on a calendar date, for `dateFormatter` only. `setUTCFullYear`
+ * keeps years below 100 literal instead of mapping them to the 1900s.
+ */
+export declare function formatterDate({ year, month, day }: DateParts): Date;

package/dist/date-formatters.js

@@ -0,0 +1,28 @@
+const formatters = new Map();
+/**
+ * One shared `Intl.DateTimeFormat` per locale and options, since building
+ * one is slow and a calendar formats dozens of dates per render. Every
+ * formatter reads UTC, so a cached one never meets a changed device time
+ * zone; pair it with `formatterDate`.
+ */
+export function dateFormatter(locale, options) {
+    const key = `${locale}|${JSON.stringify(options)}`;
+    let formatter = formatters.get(key);
+    if (formatter === undefined) {
+        formatter = new Intl.DateTimeFormat(locale, {
+            ...options,
+            timeZone: 'UTC',
+        });
+        formatters.set(key, formatter);
+    }
+    return formatter;
+}
+/**
+ * Noon UTC on a calendar date, for `dateFormatter` only. `setUTCFullYear`
+ * keeps years below 100 literal instead of mapping them to the 1900s.
+ */
+export function formatterDate({ year, month, day }) {
+    const date = new Date(Date.UTC(2000, 0, 1, 12));
+    date.setUTCFullYear(year, month - 1, day);
+    return date;
+}

package/dist/date-only.d.ts

@@ -1,3 +1,26 @@
+/** A calendar date with no time and no zone. `month` is 1–12. */
+export type DateParts = {
+    year: number;
+    month: number;
+    day: number;
+};
+/** The first and last dates a four-digit YYYY-MM-DD value can hold. */
+export declare const EARLIEST_DATE_ONLY = "0001-01-01";
+export declare const LATEST_DATE_ONLY = "9999-12-31";
+export declare function daysInMonth(year: number, month: number): number;
+export declare function isValidDateParts({ year, month, day }: DateParts): boolean;
+export declare function parseDateOnly(value: string): DateParts | null;
 export declare function isDateOnly(value: string): boolean;
+export declare function formatDateOnly({ year, month, day }: DateParts): string;
 export declare function assertDateOnly(name: string, value: string, empty?: boolean): void;
+/** Validates a picker's value and bounds; an empty value means no selection. */
+export declare function assertDateBounds(value: string, min?: string, max?: string): void;
+/** Valid date-only strings compare lexicographically. */
 export declare function isOutsideDateRange(value: string, min?: string, max?: string): boolean;
+/**
+ * Moves a date-only value into `[min, max]` and into the four-digit years.
+ * Also accepts a zero-padded year 0 or 10000 string from day arithmetic.
+ */
+export declare function clampDateOnly(value: string, min?: string, max?: string): string;
+/** The date on the device's local wall calendar, never converted through UTC. */
+export declare function todayDateOnly(now?: Date): string;

package/dist/date-only.js

@@ -1,31 +1,85 @@
 const DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
-function daysInMonth(year, month) {
+/** The first and last dates a four-digit YYYY-MM-DD value can hold. */
+export const EARLIEST_DATE_ONLY = '0001-01-01';
+export const LATEST_DATE_ONLY = '9999-12-31';
+export function daysInMonth(year, month) {
     if (month === 2) {
         const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
         return leap ? 29 : 28;
     }
     return [4, 6, 9, 11].includes(month) ? 30 : 31;
 }
-export function isDateOnly(value) {
-    const parts = DATE_ONLY.exec(value);
-    if (!parts)
-        return false;
-    const year = Number(parts[1]);
-    const month = Number(parts[2]);
-    const day = Number(parts[3]);
-    return (year >= 1 &&
+export function isValidDateParts({ year, month, day }) {
+    return (Number.isInteger(year) &&
+        Number.isInteger(month) &&
+        Number.isInteger(day) &&
+        year >= 1 &&
+        year <= 9999 &&
         month >= 1 &&
         month <= 12 &&
         day >= 1 &&
         day <= daysInMonth(year, month));
 }
+export function parseDateOnly(value) {
+    const parts = DATE_ONLY.exec(value);
+    if (!parts)
+        return null;
+    const date = {
+        year: Number(parts[1]),
+        month: Number(parts[2]),
+        day: Number(parts[3]),
+    };
+    return isValidDateParts(date) ? date : null;
+}
+export function isDateOnly(value) {
+    return parseDateOnly(value) !== null;
+}
+export function formatDateOnly({ year, month, day }) {
+    const yyyy = String(year).padStart(4, '0');
+    const mm = String(month).padStart(2, '0');
+    const dd = String(day).padStart(2, '0');
+    return `${yyyy}-${mm}-${dd}`;
+}
 export function assertDateOnly(name, value, empty = false) {
     if (empty && value === '')
         return;
     if (!isDateOnly(value))
         throw new RangeError(`${name} must be a valid YYYY-MM-DD date`);
 }
+/** Validates a picker's value and bounds; an empty value means no selection. */
+export function assertDateBounds(value, min, max) {
+    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');
+}
+/** Valid date-only strings compare lexicographically. */
 export function isOutsideDateRange(value, min, max) {
     return (value !== '' &&
         ((min !== undefined && value < min) || (max !== undefined && value > max)));
 }
+/**
+ * Moves a date-only value into `[min, max]` and into the four-digit years.
+ * Also accepts a zero-padded year 0 or 10000 string from day arithmetic.
+ */
+export function clampDateOnly(value, min = EARLIEST_DATE_ONLY, max = LATEST_DATE_ONLY) {
+    const low = min > EARLIEST_DATE_ONLY ? min : EARLIEST_DATE_ONLY;
+    const high = max < LATEST_DATE_ONLY ? max : LATEST_DATE_ONLY;
+    // A five-digit year sorts before '9999' as text, so length decides first.
+    if (value.length > 10 || value > high)
+        return high;
+    if (value < low)
+        return low;
+    return value;
+}
+/** The date on the device's local wall calendar, never converted through UTC. */
+export function todayDateOnly(now = new Date()) {
+    return formatDateOnly({
+        year: now.getFullYear(),
+        month: now.getMonth() + 1,
+        day: now.getDate(),
+    });
+}