@scalewing/react 1.8.0 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,158 @@
 # @scalewing/react
 
+## 1.10.0
+
+### Minor Changes
+
+- 964e461: New `CalendarButton`: an icon-only `Button` that opens the `DateField` calendar dialog for a date the page already shows, such as a day heading with its own previous and next buttons (`docs/requests/teisoro-calendar-button.md`).
+
+  - Props: `label`, `value` (`YYYY-MM-DD`, never empty), `onChange`, and optional `min`, `max`, `disabled`, `locale`, `weekStartsOn`, `id`, `labels` (the calendar's words `previousMonth`, `nextMonth`, `month`, `year`, `today`, and `nameSeparator`), `size` (`xs`, `sm`, `md`; default `md`), and `variant` (a Button variant; default `ghost`). A `ref` reaches the `<button>`. New types `CalendarButtonProps` and `CalendarButtonLabels`.
+  - The accessible name is `label`, `labels.nameSeparator` (default `", "`, overridable per locale, such as `"、"` in Japanese), then the spoken date ("Choose survey day, Tuesday, September 22, 2026"), with `aria-haspopup="dialog"`, `aria-expanded`, and `aria-controls` while open. Enter, Space, or a press opens the calendar on `value` (a `value` outside `min`/`max` is kept, as on `DateField`, and the calendar opens on the nearest allowed day); choosing a day calls `onChange`, closes, and returns focus to the button; Escape and a press outside close without a change.
+  - An empty or invalid `value`, invalid bounds, locale, week start, or calendar words throw a `RangeError` with `DateField`'s messages. Two errors are new: `label must be non-empty text` and `labels.nameSeparator must be non-empty text`.
+  - New generated class `sw-calendar-button`: square at every Button size, and at least the 44 px md control height on a coarse pointer. The calendar reuses `sw-date-field-calendar` and its existing stacking layer.
+
+  No new dependencies.
+
+## 1.9.0
+
+### Minor Changes
+
+- a4a30e8: `DateField` draws its own calendar instead of using the browser's `<input type="date">`, so it looks the same in every browser, follows Scalewing's tokens, and shows up in screenshots. The props, the date-only `YYYY-MM-DD` contract, and the `RangeError` guards are unchanged.
+
+  - 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); ISO `YYYY-MM-DD` and eight bare digits also work. A keystroke commits once the entry's last field is at full width (a four-digit year, or two digits for a trailing day or month); a shorter last field commits on blur or Enter. Typed text stays when the parent keeps the old value. Text that is not a date keeps the last value and, after the person leaves the field, sets `aria-invalid` with a message. As with the native input, the entry blocks form submission while its text is not a date or its date is outside `min`/`max` (`setCustomValidity`).
+  - A calendar button opens a WAI-ARIA date picker dialog anchored under the field on the popover layer, with month and year selectors for jumping decades, Today, and Clear (only when not `required`). Arrows, Home/End, PageUp/PageDown, and Shift+PageUp/PageDown move focus; Enter or Space selects; Escape closes and returns focus to the button. Days outside `min`/`max` are `aria-disabled`, the month selector offers only months inside them, and padding past `0001-01-01` or `9999-12-31` is blank and inert.
+  - New optional props: `locale` (BCP 47; defaults to the nearest `lang` attribute, then `en-US`), `weekStartsOn` (`0` Sunday by default, or `1` Monday), and `labels` for the control's own words (English defaults), including `outOfRange`, the form validation message for a date outside `min`/`max`. New types `DateFieldLabels` and `WeekStart`. New generated `sw-date-field-*` classes for the control and calendar.
+  - Migration for tests: there is no `input[type=date]` any more. Find the entry by its label (`getByLabel('Hire date')` or `getByRole('textbox', { name: 'Hire date' })`) and `fill` it in the locale's order or in ISO, or open the calendar with the **Choose date** button. The input's value is now the locale's display text (`03/10/2024`), not `2024-03-10`; assert the serialized value from your own state.
+
+  No new dependencies.
+
+- 4548fc2: `Accordion` takes `subtitle`, one muted caption line under the title, and
+  `size="sm"` for a quieter disclosure nested inside other content (a
+  label-size title, spacing step 3, `md` corners, and a header that is an `sm`
+  control of at least 32px instead of 44px). The header now draws a
+  token chevron at its inline end in place of the browser's `details` triangle;
+  it turns when the disclosure opens and holds still under reduced motion. See
+  `docs/requests/teisoro-accordion-summary.md`.
+
+  ```tsx
+  <Accordion
+    open={open}
+    onOpenChange={setOpen}
+    subtitle="Twelve sightings · Two nests"
+    title="Wetlands"
+  >
+    {children}
+  </Accordion>
+  ```
+
+  New generated classes `sw-accordion-sm`, `sw-accordion-heading` and
+  `sw-accordion-marker`, and a new exported type `AccordionSize`. The summary is
+  now a flex row instead of `display: list-item`, so the native marker is gone;
+  an app that styled `.sw-accordion-summary::marker` has nothing left to style.
+  Additive for the public API.
+
+- 38e6f09: New `ActionBar`: a long page's actions and one short `status` line on a glass
+  bar that sticks to the bottom of the viewport while the content above it
+  scrolls, then rests in place after it (see
+  `docs/requests/teisoro-action-bar.md`). `stickyBelow="md"` sticks only below
+  the `md` breakpoint and keeps the bar in page flow from `md` up. The bar clears
+  the safe-area insets (with `viewport-fit=cover`), is solid under Reduce
+  Transparency, and on a phone puts the status on its own line with the actions
+  sharing the row under it. The status is a polite live region
+  (`role="status"`), always rendered so the first status is announced too; an
+  empty status takes no room.
+
+  ```tsx
+  <Stack gap={4}>
+    {longForm}
+    <ActionBar status="Draft saved at 5:00 PM" stickyBelow="md">
+      <Button variant="secondary" onPress={save}>
+        Save draft
+      </Button>
+      <Button onPress={finish}>Finish</Button>
+    </ActionBar>
+  </Stack>
+  ```
+
+  New generated classes `sw-action-bar`, `sw-action-bar-status`,
+  `sw-action-bar-actions`, `sw-action-bar-sticky` and
+  `sw-action-bar-sticky-below-md`; new exported types `ActionBarProps` and `Breakpoint` (the breakpoint names
+  `stickyBelow`, `hideBelow` and `columnsBelow` already take, today only
+  `'md'`). Additive.
+
+  Every generated `z-index` now comes from one stacking order
+  (`src/css/stacking.ts`): sticky table cells 1, the ActionBar 2, a glass `Card`
+  or `Accordion` holding an open popup 3 (was 1), the sticky `AppHeader` 4 (was
+  2), and popups 10 (the `Select` list was 3). An open `Select`, `ActionMenu`
+  or `Tooltip` inside a glass surface now paints over a stuck ActionBar, and
+  still under the AppHeader. An app that layered its own element between these
+  values should check it against the new numbers.
+
+- affd090: `Box` `border` accepts `'dashed'` as well as `true`: a hairline dashed border
+  in the `border` color token, for a space to fill in by hand such as a blank on
+  a printed form (see `docs/requests/teisoro-box-border-style.md`). Every
+  Box-based component takes it.
+
+  ```tsx
+  <Box border="dashed" padding={2} radius="sm">
+    {hint}
+  </Box>
+  ```
+
+  New generated classes `sw-border` and `sw-border-dashed` and a new exported
+  type `BoxBorder` (`boolean | 'dashed'`). `border` and `border={true}` look the
+  same as before, but the solid hairline is now the `sw-border` class instead of
+  an inline `style.border`; a consumer `style` still wins, and the prop still
+  wins over a Box-based component's own frame. A test that read
+  `element.style.border` should check the class instead. Additive for the
+  public API.
+
+- 6a4c4ab: `Field` takes `prefix` and `suffix`: short text inside the control's frame
+  before or after the value, such as a currency sign or a unit (see
+  `docs/requests/teisoro-field-adornment.md`).
+
+  ```tsx
+  <Field label="Drop amount" prefix="$">
+    <input inputMode="decimal" name="drop" />
+  </Field>
+  ```
+
+  The text is not part of the value. The generated `sw-field-adorned` wrapper
+  draws the control frame and focus ring, `sw-field-prefix` and
+  `sw-field-suffix` are muted, and the input is named by its label plus the
+  adornment ("Drop amount $") through `aria-labelledby`. An input that names
+  itself with its own `aria-label` or `aria-labelledby` keeps that name, and the
+  adornment joins its `aria-describedby` instead. A press on the prefix, the
+  suffix or the frame focuses the input. Adornments need one
+  native `<input>` child; anything else throws a `TypeError`. Additive; an
+  unadorned `Field` renders as before.
+
+- 988bd2c: `Grid` takes `align` (`start`, `center`, `end`, `stretch`): where each child
+  sits in the height of its row, through the same generated `sw-align-*` classes
+  and `Align` type as `Stack` and `Inline` (see the 2026-09-28 follow-up in
+  `docs/requests/teisoro-grid.md`). `align="end"` keeps a row of fields level
+  when one label wraps:
+
+  ```tsx
+  <Grid align="end" columns={2} gap={3}>
+    {fields}
+  </Grid>
+  ```
+
+  Additive; unset, no class is added and children stretch as before.
+
+- c3d04a8: `Progress` takes `showCount` (default `true`). `showCount={false}` hides the
+  visible `value / max` count beside the label when the page shows its own count
+  caption, so the count appears once (see the 2026-09-28 follow-up in
+  `docs/requests/teisoro-progress.md`). The progress bar still exposes its value
+  and maximum to assistive tech.
+
+  ```tsx
+  <Progress label="Registers closed" max={2} showCount={false} value={0} />
+  ```
+
+  Additive; the count shows as before when the prop is left out.
+
 ## 1.8.0
 
 ### Minor Changes

package/README.md

@@ -7,10 +7,12 @@ import '@scalewing/react/styles.css';
 import '@scalewing/react/palette/cerulean.css';
 import {
   Accordion,
+  ActionBar,
   ActionMenu,
   BarChart,
   Box,
   Button,
+  CalendarButton,
   Card,
   Checkbox,
   RadioGroup,
@@ -44,10 +46,54 @@ import {
 
 Import the CSS once at the application entry. Do not copy it into your source tree. Optional: import one `@scalewing/react/palette/<id>.css` file after it, or set `data-palette` on the `data-theme` node. React apps can set `palette` on `ThemeProvider` instead.
 
+`Box` `border` draws a hairline in the `border` color token: `border` (or `border={true}`) is solid, and `border="dashed"` is dashed (the generated `sw-border` and `sw-border-dashed` classes; a `style` you pass still wins), for a space to fill in by hand such as a blank on a printed form. It does not make the box look or act like an input. Every `Box`-based component takes it.
+
 `Box hideBelow="md"` hides a region under 48rem and `hideFrom="md"` hides it at 48rem and wider, so a product can swap a wide layout for a narrow one without its own stylesheet. Hidden regions leave the accessibility tree; do not use this to protect data. `Box as="a"` is a layout link. Use `Button` for press actions. `Field` associates a native `<input>` or `<select>` with a label and token gap; native text controls inherit the generated document canvas. `Select` is a labeled listbox menu when the open list must match the canvas.
 
 `Field` supports optional `description`, `error`, and `required` on one native input, select, or textarea child. It preserves an existing `aria-describedby`, appends a stable message ID, and replaces the hint with an alert when an error is supplied. `error` sets `aria-invalid` and token-owned invalid styling. The consumer owns validation and localized messages.
 
+`Field` `prefix` and `suffix` put short text such as `$` or `%` inside the frame of one native `<input>` child, before or after the value. The text is not part of the value; the input is named by its label plus the adornment (`"Drop amount $"`), unless it names itself with its own `aria-label` or `aria-labelledby`, in which case the adornment joins its description. A press anywhere on the frame focuses the input. Formatting the value stays with the consumer. Any other child throws a `TypeError`.
+
+```tsx
+<Field label="Drop amount" prefix="$">
+  <input inputMode="decimal" name="drop" />
+</Field>
+```
+
+`Accordion` is a native `<details>` disclosure controlled by `open` and `onOpenChange`. A token chevron at the end of the header replaces the browser triangle and turns when it opens (it holds still under reduced motion). `subtitle` adds one muted caption line under the title, such as a summary of what the section holds; it wraps rather than truncating and is read after the title. `size="sm"` is a quieter disclosure nested inside other content: a label-size title, tighter padding, smaller corners and a header that is an `sm` control (at least 32px).
+
+```tsx
+<Accordion
+  open={open}
+  onOpenChange={setOpen}
+  subtitle="Twelve sightings · Two nests"
+  title="Wetlands"
+>
+  <Accordion
+    open={methodOpen}
+    onOpenChange={setMethodOpen}
+    size="sm"
+    title="How the count is taken"
+  >
+    {method}
+  </Accordion>
+</Accordion>
+```
+
+`ActionBar` keeps the actions of a long page on a glass bar stuck to the bottom of the viewport, with an optional one-line `status` (such as when the work was last saved). Put it last in the content it acts on: it stays stuck while that content scrolls by and then rests in its own place at the end. `stickyBelow="md"` sticks only on a phone and leaves the bar in page flow from `md` up. The bar clears `env(safe-area-inset-bottom)` (set `viewport-fit=cover` in the page's viewport meta for the inset to apply). Its children are the actions: on a phone they share one row under the status. The status is a polite live region (`role="status"`, kept in the page even while empty), so a new status such as "Draft saved at 5:00 PM" is announced; do not announce the same save a second time with your own notice. An open `Select`, `ActionMenu` or `Tooltip` paints over the bar, including inside a glass `Card` or `Accordion`.
+
+```tsx
+<Stack gap={4}>
+  {longForm}
+  <ActionBar status="Draft saved at 5:00 PM" stickyBelow="md">
+    <Button variant="secondary" onPress={save}>
+      Save draft
+    </Button>
+    <Button onPress={finish}>Finish</Button>
+  </ActionBar>
+</Stack>
+```
+
 `ActionMenu` opens independent commands from a labelled button. Provide localized command labels and callbacks; use `disabled` for unavailable commands and `destructive` for a dangerous command's presentation. Escape and choosing a command both return focus to the trigger (before the command runs, so a `Dialog` it opens hands focus back to the trigger on close), and outside interaction dismisses the menu.
 
 `Dialog` is a modal `<dialog>` controlled by `open`. Escape, a backdrop press, a platform close request, and a `<form method="dialog">` submit (or a submitter with `formmethod="dialog"`) are each prevented and call `onClose`; none of them closes the dialog itself. A consumer `onKeyDown`, `onCancel`, `onSubmit` or `onPointerDown` that prevents the event vetoes that request. Escape in a search field that holds text clears the field first, and a descendant's own `cancel` (a dismissed file picker) is not a close request. Set `open` to false to close it, or keep it true (for example while a form is saving) and it stays shown. `onClose` is not called when `open` turns false, and it is required: a dialog that must not be dismissed passes a callback that keeps `open` true.
@@ -60,7 +106,7 @@ Import the CSS once at the application entry. Do not copy it into your source tr
 
 `Spinner` shows indeterminate loading in small, medium, or large sizes. Supply localized `label` for the one announced status in a loading region. Use `decorative` on additional indicators beside that status so screen readers do not hear the same message repeatedly. Reduced motion leaves a static accented ring.
 
-`Progress` shows a known value between zero and a positive maximum. It uses native progressbar semantics and displays the value and maximum beside the localized label. Invalid bounds throw instead of silently clamping. Optional `tone` is `accent`, `success`, or `danger`.
+`Progress` shows a known value between zero and a positive maximum. It uses native progressbar semantics and displays the value and maximum beside the localized label. Invalid bounds throw instead of silently clamping. Optional `tone` is `accent`, `success`, or `danger`. `showCount={false}` hides the visible `value / max` count when the page shows its own count caption, so the count appears once; the progress bar still exposes its value and maximum.
 
 `Tooltip` adds supplementary plain-text help to one labelled, focusable trigger. Supply localized `content` and an existing trigger element with its own accessible name. It opens on hover or focus, closes on pointer leave, blur, Escape, or outside touch, and toggles on touch. Keep required instructions visible outside the tooltip.
 
@@ -87,11 +133,24 @@ Every `Box`-based component (`Box`, `Stack`, `Inline`, `Card`, `Grid`, …) take
 
 Values outside the catalog throw a `RangeError`. There is no per-breakpoint span and no arbitrary column template.
 
+`Grid` `align` (`start`, `center`, `end`, `stretch`) sets where each child sits in the height of its row, with the same generated `sw-align-*` classes as `Stack` and `Inline`. Unset, children stretch. `align="end"` keeps a row of fields level when one label wraps:
+
+```tsx
+<Grid align="end" columns={2} gap={3}>
+  <Field label="Nest height above the waterline">{heightInput}</Field>
+  <Field label="Eggs">{eggsInput}</Field>
+</Grid>
+```
+
 `DenominationGrid` shows integer counts per unit across a fixed set of columns. The `strip` layout is a captioned table: each row has a toned label with an icon slot, muted zero cells, optional signed deltas toned by sign, and an optional consumer-formatted `total` that moves under the label on a phone. A strip wider than its container scrolls sideways inside its own keyboard-focusable region, named after `label`, with the row labels pinned at the start; the page never scrolls sideways. The `tiles` layout stacks the column label, the count, and an optional `subtotal` string per column. The primitive does no arithmetic and no currency formatting; tones reuse the Badge vocabulary. Invalid columns, rows, or cells throw.
 
 `FilterChips` presents a long, wrapping single-choice filter set. Provide a localized group `label`, controlled `value`, `onChange`, and options with stable values and localized labels. An optional non-negative integer `count` renders as a tabular chicklet after the label and is part of the option's accessible name; a zero count quiets the chip until it is selected. Native radios provide arrow and Space navigation; disabled options are skipped.
 
-`DateField` is a controlled native date input. 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. For a blank required field, supply `error` when form validation runs to show the message and invalid styling. The browser chooses the calendar and localized display.
+`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. 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`.
+
+`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 })`.
 
 ```tsx
 <DateField
@@ -101,6 +160,38 @@ Values outside the catalog throw a `RangeError`. There is no per-breakpoint span
   min="2024-01-01"
   max="2024-12-31"
 />
+
+<DateField
+  label="Fecha del avistamiento"
+  locale="es"
+  weekStartsOn={1}
+  labels={{ chooseDate: 'Elegir fecha', today: 'Hoy', clear: 'Borrar' }}
+  value={fecha}
+  onChange={setFecha}
+/>
+```
+
+`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.
+
+```tsx
+<Inline gap={1}>
+  <Button aria-label="Previous day" variant="ghost" onPress={previousDay}>
+    ‹
+  </Button>
+  <Text as="h2" variant="title">
+    {spokenSurveyDay}
+  </Text>
+  <CalendarButton
+    label="Choose survey day"
+    value={surveyDay}
+    onChange={setSurveyDay}
+    min="2026-09-01"
+    max="2026-09-30"
+  />
+  <Button aria-label="Next day" variant="ghost" onPress={nextDay}>
+    ›
+  </Button>
+</Inline>
 ```
 
 ```tsx

package/dist/anchored-position.d.ts

@@ -0,0 +1,28 @@
+export type AnchorRect = {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+};
+export type PopoverSize = {
+    width: number;
+    height: number;
+};
+export type Viewport = {
+    width: number;
+    height: number;
+};
+export type AnchoredPosition = {
+    left: number;
+    top: number;
+};
+/**
+ * Where a fixed popover goes beside its anchor: below and aligned to the
+ * anchor's inline start (its end in right-to-left), above when it does not
+ * fit below but does above, and always kept inside the viewport by `inset`.
+ */
+export declare function anchoredPosition(anchor: AnchorRect, size: PopoverSize, viewport: Viewport, { gap, inset, rtl }?: {
+    gap?: number | undefined;
+    inset?: number | undefined;
+    rtl?: boolean | undefined;
+}): AnchoredPosition;

package/dist/anchored-position.js

@@ -0,0 +1,17 @@
+/**
+ * Where a fixed popover goes beside its anchor: below and aligned to the
+ * anchor's inline start (its end in right-to-left), above when it does not
+ * fit below but does above, and always kept inside the viewport by `inset`.
+ */
+export function anchoredPosition(anchor, size, viewport, { gap = 0, inset = 0, rtl = false } = {}) {
+    const preferredLeft = rtl ? anchor.right - size.width : anchor.left;
+    const maxLeft = viewport.width - inset - size.width;
+    const left = Math.max(inset, Math.min(preferredLeft, maxLeft));
+    const below = anchor.bottom + gap;
+    const above = anchor.top - gap - size.height;
+    const fitsBelow = below + size.height <= viewport.height - inset;
+    const fitsAbove = above >= inset;
+    const top = fitsBelow || !fitsAbove ? below : above;
+    const maxTop = viewport.height - inset - size.height;
+    return { left, top: Math.max(inset, Math.min(top, maxTop)) };
+}

package/dist/calendar-button-labels.d.ts

@@ -0,0 +1,19 @@
+import { type DateFieldLabels } from './date-field-labels.js';
+/**
+ * CalendarButton's own words: the calendar's words from DateFieldLabels,
+ * plus the text between its label and the spoken date in its name.
+ */
+export type CalendarButtonLabels = Pick<DateFieldLabels, 'previousMonth' | 'nextMonth' | 'month' | 'year' | 'today'> & {
+    /**
+     * Joins the label and the spoken date in the button's name. Defaults to
+     * ", "; pass the locale's own pause, such as "、" in Japanese.
+     */
+    nameSeparator: string;
+};
+export declare const defaultNameSeparator = ", ";
+export type ResolvedCalendarButtonLabels = {
+    calendar: DateFieldLabels;
+    nameSeparator: string;
+};
+/** Consumer words over the English defaults; empty words fail closed. */
+export declare function resolveCalendarButtonLabels(labels?: Partial<CalendarButtonLabels>): ResolvedCalendarButtonLabels;

package/dist/calendar-button-labels.js

@@ -0,0 +1,10 @@
+import { resolveDateFieldLabels, } from './date-field-labels.js';
+export const defaultNameSeparator = ', ';
+/** Consumer words over the English defaults; empty words fail closed. */
+export function resolveCalendarButtonLabels(labels = {}) {
+    const { nameSeparator = defaultNameSeparator, ...calendar } = labels;
+    // Only an empty string is refused: a lone space is a valid separator.
+    if (typeof nameSeparator !== 'string' || nameSeparator === '')
+        throw new RangeError('labels.nameSeparator must be non-empty text');
+    return { calendar: resolveDateFieldLabels(calendar), nameSeparator };
+}

package/dist/calendar-keys.d.ts

@@ -0,0 +1,19 @@
+import { type WeekStart } from './calendar-month.js';
+export type CalendarKey = {
+    key: string;
+    shiftKey: boolean;
+};
+export type CalendarKeyContext = {
+    weekStartsOn: WeekStart;
+    min?: string;
+    max?: string;
+    /** Right-to-left grids swap the meaning of the horizontal arrows. */
+    rtl?: boolean;
+};
+/**
+ * The day a calendar grid key moves focus to, following the WAI-ARIA date
+ * picker dialog pattern: arrows by day and week, Home and End to the week's
+ * edges, PageUp and PageDown by month, and with Shift by year. The result
+ * stays inside `[min, max]`. Keys the grid does not own return null.
+ */
+export declare function calendarKeyTarget(key: CalendarKey, focused: string, context: CalendarKeyContext): string | null;

package/dist/calendar-keys.js

@@ -0,0 +1,39 @@
+import { addDays, addMonths, weekdayOf, } from './calendar-month.js';
+import { clampDateOnly } from './date-only.js';
+function unclampedTarget({ key, shiftKey }, focused, { weekStartsOn, rtl = false }) {
+    const forward = rtl ? 'ArrowLeft' : 'ArrowRight';
+    const back = rtl ? 'ArrowRight' : 'ArrowLeft';
+    const column = (weekdayOf(focused) - weekStartsOn + 7) % 7;
+    switch (key) {
+        case forward:
+            return addDays(focused, 1);
+        case back:
+            return addDays(focused, -1);
+        case 'ArrowDown':
+            return addDays(focused, 7);
+        case 'ArrowUp':
+            return addDays(focused, -7);
+        case 'Home':
+            return addDays(focused, -column);
+        case 'End':
+            return addDays(focused, 6 - column);
+        case 'PageUp':
+            return addMonths(focused, shiftKey ? -12 : -1);
+        case 'PageDown':
+            return addMonths(focused, shiftKey ? 12 : 1);
+        default:
+            return null;
+    }
+}
+/**
+ * The day a calendar grid key moves focus to, following the WAI-ARIA date
+ * picker dialog pattern: arrows by day and week, Home and End to the week's
+ * edges, PageUp and PageDown by month, and with Shift by year. The result
+ * stays inside `[min, max]`. Keys the grid does not own return null.
+ */
+export function calendarKeyTarget(key, focused, context) {
+    const target = unclampedTarget(key, focused, context);
+    return target === null
+        ? null
+        : clampDateOnly(target, context.min, context.max);
+}

package/dist/calendar-labels.d.ts

@@ -0,0 +1,19 @@
+import { type CalendarMonth, type WeekStart } from './calendar-month.js';
+export type WeekdayLabel = {
+    short: string;
+    long: string;
+};
+/** Weekday column headers in display order, named by `Intl` for `locale`. */
+export declare function weekdayLabels(locale: string, weekStartsOn: WeekStart): WeekdayLabel[];
+/** The twelve month names, January first, as `locale` writes them alone. */
+export declare function monthNames(locale: string): string[];
+export declare function monthTitle(month: CalendarMonth, locale: string): string;
+/** A spoken date such as "Sunday, March 10, 2024"; empty for no date. */
+export declare function formatDateLabel(value: string, locale: string): string;
+/**
+ * An icon-only calendar trigger's name: its purpose, a separator, then the
+ * date it holds spoken in full, such as "Choose survey day, Tuesday,
+ * September 22, 2026". `Intl.ListFormat` has no neutral join (Spanish unit
+ * lists add "y", Chinese adds nothing), so the separator is the caller's.
+ */
+export declare function calendarTriggerName(purpose: string, value: string, locale: string, separator: string): string;

package/dist/calendar-labels.js

@@ -0,0 +1,41 @@
+import { weekdayOrder, } from './calendar-month.js';
+import { dateFormatter, formatterDate } from './date-formatters.js';
+import { parseDateOnly } from './date-only.js';
+/** A Sunday; any week works because only the weekday names are read. */
+const REFERENCE_SUNDAY = { year: 2023, month: 1, day: 1 };
+/** Weekday column headers in display order, named by `Intl` for `locale`. */
+export function weekdayLabels(locale, weekStartsOn) {
+    const short = dateFormatter(locale, { weekday: 'short' });
+    const long = dateFormatter(locale, { weekday: 'long' });
+    return weekdayOrder(weekStartsOn).map((weekday) => {
+        const date = formatterDate({
+            ...REFERENCE_SUNDAY,
+            day: REFERENCE_SUNDAY.day + weekday,
+        });
+        return { short: short.format(date), long: long.format(date) };
+    });
+}
+/** The twelve month names, January first, as `locale` writes them alone. */
+export function monthNames(locale) {
+    const format = dateFormatter(locale, { month: 'long' });
+    return Array.from({ length: 12 }, (_, index) => format.format(formatterDate({ year: 2023, month: index + 1, day: 1 })));
+}
+export function monthTitle(month, locale) {
+    return dateFormatter(locale, { month: 'long', year: 'numeric' }).format(formatterDate({ ...month, day: 1 }));
+}
+/** A spoken date such as "Sunday, March 10, 2024"; empty for no date. */
+export function formatDateLabel(value, locale) {
+    const parts = parseDateOnly(value);
+    if (!parts)
+        return '';
+    return dateFormatter(locale, { dateStyle: 'full' }).format(formatterDate(parts));
+}
+/**
+ * An icon-only calendar trigger's name: its purpose, a separator, then the
+ * date it holds spoken in full, such as "Choose survey day, Tuesday,
+ * September 22, 2026". `Intl.ListFormat` has no neutral join (Spanish unit
+ * lists add "y", Chinese adds nothing), so the separator is the caller's.
+ */
+export function calendarTriggerName(purpose, value, locale, separator) {
+    return `${purpose}${separator}${formatDateLabel(value, locale)}`;
+}

package/dist/calendar-month.d.ts

@@ -0,0 +1,38 @@
+export type CalendarMonth = {
+    year: number;
+    /** 1–12. */
+    month: number;
+};
+/** 0 is Sunday, 1 is Monday, matching `Date.prototype.getDay`. */
+export type WeekStart = 0 | 1;
+/** Fails closed on a first weekday other than Sunday or Monday. */
+export declare function assertWeekStart(weekStartsOn: number): void;
+export type CalendarCell = {
+    value: string;
+    day: number;
+    inMonth: boolean;
+};
+/** 0 is Sunday. */
+export declare function weekdayOf(value: string): number;
+export declare function addDays(value: string, delta: number): string;
+/** Same day of the month `delta` months away, capped at that month's length. */
+export declare function addMonths(value: string, delta: number): string;
+export declare function monthOf(value: string): CalendarMonth;
+export declare function shiftMonth(month: CalendarMonth, delta: number): CalendarMonth;
+export declare function firstOfMonth(month: CalendarMonth): string;
+export declare function lastOfMonth(month: CalendarMonth): string;
+/** Whether any day of the month falls inside `[min, max]`. */
+export declare function monthInRange(month: CalendarMonth, min?: string, max?: string): boolean;
+/**
+ * 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 declare function monthsInRange(year: number, min?: string, max?: string): number[];
+/**
+ * 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 declare function monthGrid(month: CalendarMonth, weekStartsOn: WeekStart): (CalendarCell | null)[][];
+/** Weekday indexes in display order for the given week start. */
+export declare function weekdayOrder(weekStartsOn: WeekStart): number[];