@scalewing/react 1.20.0 → 1.21.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @scalewing/react
 
+## 1.21.0
+
+### Minor Changes
+
+- 2d54950: `DateField` and `CalendarButton` take an optional `today` (`YYYY-MM-DD`): the day the calendar marks as today (`aria-current="date"`), opens on when the field is empty, and picks with **Today**. It defaults to the device's local date, as before. Pass the business's own day when it keeps a time zone the device may not share, so a phone in UTC at 10 PM in New York no longer rings tomorrow while `max` disables it. An empty or malformed `today` throws a `RangeError`.
+
 ## 1.20.0
 
 ### Minor Changes

package/README.md

@@ -291,7 +291,7 @@ Values outside the catalog throw a `RangeError`. There is no per-breakpoint span
 
 `DateField` is a controlled date-only field that draws its own calendar. Supply `value`, `min`, and `max` as valid `YYYY-MM-DD` dates; use an empty `value` for a blank field. Its callback returns a date-only string or an empty string, without timezone conversion. Invalid serialized dates and inverted bounds throw; a value outside the bounds remains visible with invalid styling. `required` marks the label with the same `aria-hidden` asterisk as `Field` and sets the entry's native `required`. Its label is drawn as `Field`'s (the same label words and mark inside a `<label>` that keeps the canvas type), so its label row and its gap to the entry match a `Field` beside it. For a blank required field, supply `error` when form validation runs to show the message and invalid styling.
 
-People type the date into a text entry in the locale's numeric order (`MM/DD/YYYY` for en-US, `DD/MM/YYYY` for es), with any non-digit separator, eight bare digits, or ISO `YYYY-MM-DD`. A keystroke calls `onChange` once the entry is complete, meaning its last field is at full width (four year digits, or two digits for a trailing day or month, as in ISO); otherwise the date commits when the person leaves the field or presses Enter, so typing `2024-03-10` never sends `2024-03-01` on the way. If the parent keeps the old value, the typed text stays on screen; any other outside change replaces it. Text that is not a date keeps the last value and, once the person leaves the field, sets `aria-invalid` and shows `labels.invalidEntry`. Like the native date input, the entry blocks form submission through `setCustomValidity`: `labels.invalidEntry` while its text is not a date, and `labels.outOfRange` while its date, typed or given, is outside `min`/`max`. The calendar button beside it opens a WAI-ARIA date picker dialog anchored under the field on the popover layer: the month grid shows today, the selected day, and days outside `min`/`max` as `aria-disabled` (padding before `0001-01-01` or after `9999-12-31` is blank and inert); arrows move by day and week, Home and End to the week's edges, PageUp and PageDown by month, Shift with them by year, Enter or Space selects and closes, and Escape closes and returns focus to the button. Month and year selectors in the header jump decades (the year list spans 120 years back and 20 ahead of today and the shown month, cut to `min` and `max`; the month list offers only months with a day inside them). A new `value`, `min`, or `max` while the calendar is open moves it to the new value or back inside the bounds. **Today** selects today; **Clear** appears only when the field is not `required`.
+People type the date into a text entry in the locale's numeric order (`MM/DD/YYYY` for en-US, `DD/MM/YYYY` for es), with any non-digit separator, eight bare digits, or ISO `YYYY-MM-DD`. A keystroke calls `onChange` once the entry is complete, meaning its last field is at full width (four year digits, or two digits for a trailing day or month, as in ISO); otherwise the date commits when the person leaves the field or presses Enter, so typing `2024-03-10` never sends `2024-03-01` on the way. If the parent keeps the old value, the typed text stays on screen; any other outside change replaces it. Text that is not a date keeps the last value and, once the person leaves the field, sets `aria-invalid` and shows `labels.invalidEntry`. Like the native date input, the entry blocks form submission through `setCustomValidity`: `labels.invalidEntry` while its text is not a date, and `labels.outOfRange` while its date, typed or given, is outside `min`/`max`. The calendar button beside it opens a WAI-ARIA date picker dialog anchored under the field on the popover layer: the month grid shows today, the selected day, and days outside `min`/`max` as `aria-disabled` (padding before `0001-01-01` or after `9999-12-31` is blank and inert); arrows move by day and week, Home and End to the week's edges, PageUp and PageDown by month, Shift with them by year, Enter or Space selects and closes, and Escape closes and returns focus to the button. Month and year selectors in the header jump decades (the year list spans 120 years back and 20 ahead of today and the shown month, cut to `min` and `max`; the month list offers only months with a day inside them). A new `value`, `min`, or `max` while the calendar is open moves it to the new value or back inside the bounds. **Today** selects today; **Clear** appears only when the field is not `required`. Today is the device's local date unless `today` (a `YYYY-MM-DD` date) is given: pass the business's own day when it keeps a time zone the device may not share, so a phone in another zone after the business's midnight does not mark tomorrow as today, open on it, or pick it while `max` is the business's day. `today` moves the today mark, the empty field's starting day, **Today**, and the year list's span; it may lie outside `min`/`max`, where **Today** is disabled as before. An empty or malformed `today` throws a `RangeError`.
 
 `locale` (BCP 47) sets month and weekday names, spoken dates, and the typed order; it defaults to the nearest `lang` attribute when the field mounts, then `en-US`, and a malformed tag throws. `weekStartsOn` is `0` (Sunday, the default) or `1` (Monday). `labels` overrides the control's own words, English by default: `chooseDate`, `previousMonth`, `nextMonth`, `month`, `year`, `today`, `clear`, `invalidEntry`, `outOfRange`, and the placeholder letters `dayPlaceholder`, `monthPlaceholder`, `yearPlaceholder`. The field label names only the text entry; the calendar button is named `labels.chooseDate` and described by the field label, so tests find the entry with `getByLabel` or `getByRole('textbox', { name })`.
 
@@ -314,7 +314,7 @@ People type the date into a text entry in the locale's numeric order (`MM/DD/YYY
 />
 ```
 
-`CalendarButton` is an icon-only `Button` that opens the same calendar dialog for a date the page already shows, such as a day heading with its own previous and next steps: `‹ Tuesday, September 22, 2026 [calendar] ›`. It has no text entry and no empty value. Supply `label` (what pressing it does, such as "Choose survey day"), a `YYYY-MM-DD` `value`, and `onChange`; optional `min`, `max`, `disabled`, `locale`, and `weekStartsOn` behave as on `DateField`, and `id` and a `ref` reach the `<button>`. `labels` takes the calendar's words (`previousMonth`, `nextMonth`, `month`, `year`, `today`) and `nameSeparator`. The button's accessible name is `label`, `labels.nameSeparator` (default `", "`), then the spoken date (`"Choose survey day, Tuesday, September 22, 2026"`); pass the locale's own pause where a comma does not fit, such as `"、"` in Japanese. It comes with `aria-haspopup="dialog"`, `aria-expanded`, and `aria-controls` while open; the calendar dialog is named by `label`. Enter, Space, or a press opens it on `value`. As on `DateField`, a `value` outside `min`/`max` is kept rather than refused, and the calendar then opens on the nearest allowed day with `value` shown selected and disabled; a button has no invalid state, so the page that shows the date flags it if it must. Choosing a day or **Today** calls `onChange` with the new date only when it changed, closes, and returns focus to the button; Escape closes without a change and returns focus; a press outside closes without a change and leaves focus where it landed. An empty or malformed `value`, `min`, or `max`, inverted bounds, a bad `locale` or `weekStartsOn`, an empty `label`, or an empty label word throws a `RangeError`. `size` (`xs`, `sm`, `md`; default `md`) and `variant` (default `ghost`) follow `Button`; the button is square at every size, and on a coarse pointer it is at least 44 px at every size. Place it beside the heading, not inside it, so the heading's text stays only the date.
+`CalendarButton` is an icon-only `Button` that opens the same calendar dialog for a date the page already shows, such as a day heading with its own previous and next steps: `‹ Tuesday, September 22, 2026 [calendar] ›`. It has no text entry and no empty value. Supply `label` (what pressing it does, such as "Choose survey day"), a `YYYY-MM-DD` `value`, and `onChange`; optional `min`, `max`, `today`, `disabled`, `locale`, and `weekStartsOn` behave as on `DateField`, and `id` and a `ref` reach the `<button>`. `labels` takes the calendar's words (`previousMonth`, `nextMonth`, `month`, `year`, `today`) and `nameSeparator`. The button's accessible name is `label`, `labels.nameSeparator` (default `", "`), then the spoken date (`"Choose survey day, Tuesday, September 22, 2026"`); pass the locale's own pause where a comma does not fit, such as `"、"` in Japanese. It comes with `aria-haspopup="dialog"`, `aria-expanded`, and `aria-controls` while open; the calendar dialog is named by `label`. Enter, Space, or a press opens it on `value`. As on `DateField`, a `value` outside `min`/`max` is kept rather than refused, and the calendar then opens on the nearest allowed day with `value` shown selected and disabled; a button has no invalid state, so the page that shows the date flags it if it must. Choosing a day or **Today** calls `onChange` with the new date only when it changed, closes, and returns focus to the button; Escape closes without a change and returns focus; a press outside closes without a change and leaves focus where it landed. An empty or malformed `value`, `min`, `max`, or `today`, inverted bounds, a bad `locale` or `weekStartsOn`, an empty `label`, or an empty label word throws a `RangeError`. `size` (`xs`, `sm`, `md`; default `md`) and `variant` (default `ghost`) follow `Button`; the button is square at every size, and on a coarse pointer it is at least 44 px at every size. Place it beside the heading, not inside it, so the heading's text stays only the date.
 
 ```tsx
 <Inline gap={1}>

package/dist/components/CalendarButton.d.ts

@@ -19,6 +19,12 @@ export type CalendarButtonProps = {
     onChange: (value: string) => void;
     min?: string;
     max?: string;
+    /**
+     * The calendar's today `YYYY-MM-DD`: the day it marks as today and picks
+     * with **Today**. Defaults to the device's local date; pass the business's
+     * day when it keeps its own time zone.
+     */
+    today?: string;
     disabled?: boolean;
     /** The `<button>` element's id. */
     id?: string;

package/dist/components/CalendarButton.js

@@ -26,7 +26,7 @@ function setForwardedRef(ref, node) {
  * 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) {
+export const CalendarButton = forwardRef(function CalendarButton({ label, value, onChange, min, max, today, disabled = false, id, locale, weekStartsOn = 0, labels, size = 'md', variant = 'ghost', }, ref) {
     assertLabel(label);
     assertDateOnly('value', value);
     assertDateBounds(value, min, max);
@@ -36,6 +36,7 @@ export const CalendarButton = forwardRef(function CalendarButton({ label, value,
         value,
         disabled,
         onChange,
+        today,
     });
     const resolvedLocale = useLangLocale(locale, buttonRef);
     const labelId = useId();

package/dist/components/DateField.d.ts

@@ -9,6 +9,13 @@ export type DateFieldProps = {
     onChange: (value: string) => void;
     min?: string;
     max?: string;
+    /**
+     * The calendar's today `YYYY-MM-DD`: the day it marks as today, opens on
+     * when the field is empty, and picks with **Today**. Defaults to the
+     * device's local date; pass the business's day when it keeps its own
+     * time zone.
+     */
+    today?: string;
     disabled?: boolean;
     required?: boolean;
     description?: string;
@@ -23,4 +30,4 @@ export type DateFieldProps = {
     /** The control's own words; English by default. */
     labels?: Partial<DateFieldLabels>;
 };
-export declare function DateField({ label, value, onChange, min, max, disabled, required, description, error, locale, weekStartsOn, labels, }: DateFieldProps): import("react").JSX.Element;
+export declare function DateField({ label, value, onChange, min, max, today, disabled, required, description, error, locale, weekStartsOn, labels, }: DateFieldProps): import("react").JSX.Element;

package/dist/components/DateField.js

@@ -13,7 +13,7 @@ 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, }) {
+export function DateField({ label, value, onChange, min, max, today, disabled = false, required = false, description, error, locale, weekStartsOn = 0, labels, }) {
     assertDateBounds(value, min, max);
     assertWeekStart(weekStartsOn);
     const words = resolveDateFieldLabels(labels);
@@ -35,6 +35,7 @@ export function DateField({ label, value, onChange, min, max, disabled = false,
         value,
         disabled,
         onChange,
+        today,
         beforeSelect: entry.reset,
     });
     const inputId = useId();

package/dist/components/date-field/use-calendar-popup.d.ts

@@ -3,6 +3,11 @@ export type CalendarPopupOptions = {
     value: string;
     disabled: boolean;
     onChange: (value: string) => void;
+    /**
+     * The calendar's today (`YYYY-MM-DD`); the device's local date when left
+     * out. An empty or malformed date throws a RangeError.
+     */
+    today?: string;
     /** Runs before a chosen date closes the calendar, such as a text reset. */
     beforeSelect?: () => void;
 };
@@ -33,4 +38,4 @@ export type CalendarPopup = {
  * DateField and CalendarButton. Disabling closes it for good; choosing a
  * date closes it, returns focus to the button, and reports a changed date.
  */
-export declare function useCalendarPopup({ value, disabled, onChange, beforeSelect, }: CalendarPopupOptions): CalendarPopup;
+export declare function useCalendarPopup({ value, disabled, onChange, today, beforeSelect, }: CalendarPopupOptions): CalendarPopup;

package/dist/components/date-field/use-calendar-popup.js

@@ -1,11 +1,13 @@
 import { useId, useRef, useState } from 'react';
-import { todayDateOnly } from '../../date-only.js';
+import { assertDateOnly, todayDateOnly } from '../../date-only.js';
 /**
  * The open state of a calendar dialog toggled by one button, shared by
  * DateField and CalendarButton. Disabling closes it for good; choosing a
  * date closes it, returns focus to the button, and reports a changed date.
  */
-export function useCalendarPopup({ value, disabled, onChange, beforeSelect, }) {
+export function useCalendarPopup({ value, disabled, onChange, today, beforeSelect, }) {
+    if (today !== undefined)
+        assertDateOnly('today', today);
     const buttonRef = useRef(null);
     const [open, setOpen] = useState(false);
     // Disabling closes the calendar for good, not just while disabled.
@@ -37,7 +39,7 @@ export function useCalendarPopup({ value, disabled, onChange, beforeSelect, }) {
             id,
             onClose: close,
             onSelect: select,
-            today: todayDateOnly(),
+            today: today ?? todayDateOnly(),
         },
     };
 }

package/package.json

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