@acronis-platform/ui-react 3.0.0 → 4.1.0

package/dist/llms/calendar-panel.md

@@ -0,0 +1,733 @@
+# CalendarPanel
+
+> The Figma "Calendar" panel: a bordered, elevated day-picker panel built on react-day-picker and themed by the dedicated `--ui-calendar-*` token tier. A single `variant` prop selects one of the three selection modes, and each one changes the panel's structure — `single` is one month column with no footer, `multiple` adds a Cancel/Apply footer, and `range` shows two month columns side by side (divided by a vertical rule) sharing one footer. Months are navigated through two `InputSelect` dropdowns in each month's header; there are no prev/next chevrons. `variant` is a plain string union, not a `cva` axis.
+
+**Status:** draft · **Category:** forms · **Since:** v0.62.0
+
+## Import
+
+```tsx
+import { CalendarPanel } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+{/* single — commits on click, no footer */}
+<CalendarPanel
+  variant="single"
+  selected={date}
+  onSelect={setDate}
+/>
+
+{/* multiple — a bounded set of dates, committed via Apply */}
+<CalendarPanel
+  variant="multiple"
+  max={5}
+  selected={dates}
+  onSelect={setDates}
+  onCancel={close}
+  onApply={() => { commit(dates); close(); }}
+/>
+
+{/* range — two months, one footer */}
+<CalendarPanel
+  variant="range"
+  selected={range}
+  onSelect={setRange}
+  disabled={{ before: new Date() }}
+  onApply={close}
+/>
+
+{/* localized labels + a narrower year window */}
+<CalendarPanel
+  variant="single"
+  monthLabel="Mois"
+  yearLabel="Année"
+  formatMonthLabel={(d) => d.toLocaleString('fr', { month: 'long' })}
+  fromYear={2020}
+  toYear={2030}
+/>
+```
+
+A self-contained date-picker panel: a bordered, elevated day-picker built on
+`react-day-picker` and themed by the dedicated `--ui-calendar-*` token tier. One
+`variant` prop selects the selection mode _and_ the panel's structure — the
+number of month columns and whether a Cancel/Apply footer exists.
+
+Months are navigated through two `InputSelect` dropdowns in each month's header.
+There are no prev/next chevrons: that is the design, not an omission.
+
+## When to Use
+
+- A date, a set of dates, or a date range needs to be picked from a **panel with
+  its own chrome** — border, rounded corners, shadow.
+- The panel is dropped inside a `Popover` or `Dialog` opened from a trigger (a
+  date field, a filter button, a "custom range" menu item).
+- The picker needs a **commit step** — `multiple` / `range` build a selection
+  over several clicks, and the footer gives the user an explicit Apply/Cancel.
+- Long-jump navigation matters (e.g. a birthdate 40 years back): the year
+  dropdown reaches any year in the `fromYear`…`toYear` window in one interaction.
+
+## When NOT to Use
+
+- **An always-visible embedded calendar** with no panel chrome — a month grid
+  sitting flush in a page or card. This component always draws the panel border,
+  radius and shadow; use a plain calendar grid for that (see `Calendar`).
+- **A text-entry date field.** Use `InputDatePicker`, which owns the field, the
+  trigger and its popover.
+- **A range date field.** Use `DateRangePicker`, which owns the trigger, the
+  popover and the draft/commit/revert cycle around this panel. (A preset list —
+  "Last 7 days", "This month", … — is not currently implemented by any
+  component in this repo; neither this panel nor `DateRangePicker` renders
+  presets.)
+- **Modal semantics** (focus trap, Escape to close, `role="dialog"`). This is a
+  plain panel — wrap it in `Dialog`/`Popover` and let the wrapper own them.
+
+## Variants
+
+| Variant    | Months | Footer | Selection                                                          |
+| ---------- | ------ | ------ | ------------------------------------------------------------------ |
+| `single`   | 1      | no     | One `Date`; commits on the click itself                            |
+| `multiple` | 1      | yes    | A `Date[]`; clicking toggles a day, bounded by `min` / `max`       |
+| `range`    | 2      | yes    | A `{ from, to }` range; first click sets the start, second the end |
+
+The two `range` month columns are divided by a vertical rule drawn as the first
+column's **inline-end** border, so it mirrors under `dir="rtl"`.
+
+Every cell — idle, hover, in-range, endpoint — is a flat square. This design has
+no corner-radius differentiation, so range endpoints deliberately get no "pill"
+rounding.
+
+## Parts
+
+| Part            | Element                              | Role                                                                        |
+| --------------- | ------------------------------------ | --------------------------------------------------------------------------- |
+| `root`          | `<div data-slot="calendar-panel">`   | The bordered, elevated panel; carries `data-variant`                        |
+| `month-column`  | `<div>`                              | One 248px month (caption + grid); twice for `range`, and owns the divider   |
+| `month-caption` | `<header>`                           | Header bar of one column, holding both dropdowns                            |
+| `month-select`  | `InputSelect`                        | Month dropdown, named by `monthLabel`                                       |
+| `year-select`   | `InputSelect`                        | Year dropdown over `fromYear`…`toYear`, named by `yearLabel`                |
+| `weekdays`      | `<tr>`                               | Weekday abbreviation row, starting at `weekStartsOn`                        |
+| `day-grid`      | `<table role="grid">`                | The month's day table                                                       |
+| `day`           | `<button>`                           | One date cell (Figma's "CalendarItem"); `data-active` / `data-range-middle` |
+| `footer`        | `DialogFooterDefault` + two `Button` | Cancel / Apply; **only** for `multiple` / `range`                           |
+
+## Quick Examples
+
+### Single date
+
+```tsx
+import { CalendarPanel } from '@acronis-platform/ui-react';
+
+function DueDate() {
+  const [date, setDate] = React.useState<Date | undefined>();
+
+  return (
+    <CalendarPanel
+      variant="single"
+      selected={date}
+      onSelect={(next) => setDate(next)}
+    />
+  );
+}
+```
+
+### Multiple dates, committed via Apply
+
+```tsx
+import { CalendarPanel } from '@acronis-platform/ui-react';
+
+function BackupDays({ onClose }: { onClose: () => void }) {
+  const [dates, setDates] = React.useState<Date[] | undefined>();
+
+  return (
+    <CalendarPanel
+      variant="multiple"
+      max={5}
+      selected={dates}
+      onSelect={(next) => setDates(next)}
+      onCancel={onClose}
+      onApply={onClose}
+    />
+  );
+}
+```
+
+### Range, inside a popover
+
+```tsx
+import {
+  CalendarPanel,
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  Button,
+} from '@acronis-platform/ui-react';
+import type { DateRange } from 'react-day-picker';
+
+function ReportRange() {
+  const [open, setOpen] = React.useState(false);
+  const [range, setRange] = React.useState<DateRange | undefined>();
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger
+        render={<Button variant="secondary">Pick a range</Button>}
+      />
+      <PopoverContent>
+        <CalendarPanel
+          variant="range"
+          selected={range}
+          onSelect={(next) => setRange(next)}
+          disabled={{ after: new Date() }}
+          onCancel={() => setOpen(false)}
+          onApply={() => setOpen(false)}
+        />
+      </PopoverContent>
+    </Popover>
+  );
+}
+```
+
+### Localized labels
+
+```tsx
+<CalendarPanel
+  variant="single"
+  monthLabel="Mois"
+  yearLabel="Année"
+  cancelLabel="Annuler"
+  applyLabel="Appliquer"
+  formatMonthLabel={(d) => d.toLocaleString('fr', { month: 'long' })}
+/>
+```
+
+## Notes
+
+- **Controlled vs uncontrolled.** Passing `selected` alone seeds the panel, which
+  then manages the selection itself; adding `onSelect` makes `selected` the
+  single source of truth (react-day-picker's own contract). The same split
+  applies to `defaultMonth` vs `month` + `onMonthChange`.
+- **The footer never closes anything.** `onCancel` / `onApply` just report the
+  press — the caller reverts, commits and dismisses the surrounding surface.
+- **Every rendered string is a prop.** `monthLabel`, `yearLabel`, `cancelLabel`,
+  `applyLabel` and `formatMonthLabel` carry their literals only as defaults, so
+  consumers localize at their layer.
+
+## Spec Files
+
+| File               | Contents                                                          |
+| ------------------ | ----------------------------------------------------------------- |
+| `index.yaml`       | Identity, status, category, dependencies, Figma link              |
+| `anatomy.yaml`     | Root, parts, layout, internal state, transitions, states          |
+| `api.yaml`         | Framework-agnostic contract + framework adapters                  |
+| `tokens.yaml`      | `--ui-calendar-*` token references                                |
+| `behavior.md`      | Given/When/Then behavior scenarios                                |
+| `accessibility.md` | ARIA roles, keyboard map, screen-reader and contrast requirements |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'single' | 'multiple' | 'range'` | `'single'` | no | Selection mode *and* panel structure. `single` selects one date and renders one month with no footer. `multiple` selects a set of dates and adds the Cancel/Apply footer. `range` selects a start/end pair, renders two months side by side (divided by a vertical rule) and shares one footer. Also reflected on the root as `data-variant`. |
+| `selected` | `Date | Date[] | DateRange | undefined` | `undefined` | no | The selected value, shaped by `variant` — a `Date` for `single`, a `Date[]` for `multiple`, a `{ from, to }` range for `range`. Uncontrolled (a starting value the panel then manages itself) when no select handler is given; supplying the handler makes this the single source of truth, per react-day-picker's own controlled/uncontrolled contract. |
+| `onSelect` | `(selected: Date | Date[] | DateRange | undefined, triggerDate: Date) => void` | `undefined` | no | Called when the selection changes, with the next value and the date that was clicked. Providing it makes `selected` controlled. Neutral event name: `select`. |
+| `defaultMonth` | `Date` | `the current month` | no | The month shown initially, when the displayed month is uncontrolled. Ignored once `month` is supplied. |
+| `month` | `Date` | `undefined` | no | Controlled displayed month — the first month for `range`. Pair with the month-change event. |
+| `onMonthChange` | `(month: Date) => void` | `undefined` | no | Called when the displayed month changes (i.e. from the header's month or year dropdown). Neutral event name: `month-change`. |
+| `disabled` | `Matcher | Matcher[]` | `undefined` | no | Days that cannot be selected, as a react-day-picker matcher (a date, a date range, a `{ before }`/`{ after }` bound, a day-of-week set, or a predicate) or an array of them. Matched days render in the disabled value color and take no pointer events. |
+| `min` | `number` | `undefined` | no | Minimum count, semantics depending on `variant`: for `multiple`, the number of selected dates; for `range`, the number of nights between the range's start and end (`differenceInCalendarDays(to, from)`). Applies to `multiple` and `range` only; ignored for `single`. |
+| `max` | `number` | `undefined` | no | Maximum count, semantics depending on `variant`: for `multiple`, the number of selected dates; for `range`, the number of nights between the range's start and end (`differenceInCalendarDays(to, from)`). Applies to `multiple` and `range` only; ignored for `single`. |
+| `showOutsideDays` | `boolean` | `true` | no | Render the leading/trailing days of the adjacent months to fill the first and last week rows. Outside days use the disabled value color. |
+| `weekStartsOn` | `0 | 1 | 2 | 3 | 4 | 5 | 6` | `the `locale`'s week start, else 1` | no | First day of the week (0 = Sunday). Defaults to `locale`'s own week start when `locale` is set; falls back to Monday, per the design, when neither is given. |
+| `fromYear` | `number` | `the current year − 50` | no | First year offered by the year dropdown (inclusive) and the earliest month the grid can navigate to — via the dropdown, a controlled `month`, or Shift+PageUp/PageDown. |
+| `toYear` | `number` | `the current year + 50` | no | Last year offered by the year dropdown (inclusive) and the latest month the grid can navigate to — via the dropdown, a controlled `month`, or Shift+PageUp/PageDown. |
+| `locale` | `Locale` | `date-fns `enUS`` | no | Localizes weekday names and the day grid's default accessible labels (e.g. `import { es } from 'react-day-picker/locale'`). Also supplies the fallback week start when `weekStartsOn` is unset. Does not translate `monthLabel`/`yearLabel`/`cancelLabel`/`applyLabel`/ `formatMonthLabel` — those are separate props the consumer must localize themselves. |
+| `dir` | `'ltr' | 'rtl'` | `undefined` | no | Text direction, forwarded to the day grid explicitly. An ancestor's `dir` already mirrors the panel's own layout via logical CSS properties, but the day grid only flips its Arrow Left/Right keyboard roaming when `dir` reaches it directly, so it must also be set here. |
+| `monthLabel` | `string` | `'Month'` | no | Accessible name of the month dropdown. The dropdown has no visible label in the design, so the component supplies one — override it to localize. |
+| `yearLabel` | `string` | `'Year'` | no | Accessible name of the year dropdown. The dropdown has no visible label in the design, so the component supplies one — override it to localize. |
+| `formatMonthLabel` | `(date: Date) => string` | `date-fns `format(date, 'MMMM')`` | no | Formats a month's name for the month dropdown's items and value — the hook for localized or abbreviated month names. |
+| `cancelLabel` | `string` | `'Cancel'` | no | Footer secondary button label. Only rendered for `multiple` / `range`. |
+| `applyLabel` | `string` | `'Apply'` | no | Footer primary button label. Only rendered for `multiple` / `range`. |
+| `onCancel` | `() => void` | `undefined` | no | Called when the footer's Cancel button is pressed. The panel neither reverts the selection nor closes itself — the caller decides. Neutral event name: `cancel`. |
+| `onApply` | `() => void` | `undefined` | no | Called when the footer's Apply button is pressed. The panel does not close itself — the caller commits the selection and dismisses whatever surface holds the panel. Neutral event name: `apply`. Apply is never disabled by the panel, so this can fire with an empty or partial selection (e.g. a `range` with only `from` set) — gate on selection completeness in the handler if that matters to the consumer. |
+| `className` | `string` | `undefined` | no | Extra classes merged onto the root panel — e.g. to override the shadow or the width when the panel is embedded in a popover. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `select` | `(Date | Date[] | DateRange | undefined, Date)` | Fired when the selection changes (React: `onSelect`). Payload is the next selection plus the date that was clicked. |
+| `month-change` | `Date` | Fired when the displayed month changes via the header dropdowns (React: `onMonthChange`). |
+| `cancel` | `void` | Fired when the footer's Cancel button is pressed (React: `onCancel`). Never fired for `single`, which has no footer. |
+| `apply` | `void` | Fired when the footer's Apply button is pressed (React: `onApply`). Never fired for `single`, which has no footer. Not gated on selection completeness — can fire with an empty or partial selection. |
+
+## Behavior
+
+Selection, month navigation and day-grid keyboard roaming are
+`react-day-picker`'s; this component supplies the panel chrome, the
+`InputSelect`-backed month/year header, and the Cancel/Apply footer.
+
+### Structure
+
+#### Renders the bordered panel
+
+**Given** a CalendarPanel with no props
+**When** it renders
+**Then** the root is a `<div data-slot="calendar-panel">` with
+`data-variant="single"`
+**And** it draws the `--ui-calendar-container-*` border, radius and surface plus a
+shadow
+
+#### `single` renders one month and no footer
+
+**Given** `variant="single"`
+**When** the panel renders
+**Then** exactly one month column is shown
+**And** no footer is rendered — there is no Cancel or Apply button anywhere in
+the panel
+
+#### `multiple` renders one month and the footer
+
+**Given** `variant="multiple"`
+**When** the panel renders
+**Then** exactly one month column is shown
+**And** a footer with a secondary Cancel button and a primary Apply button is
+rendered below the grid
+
+#### `range` renders two months sharing one footer
+
+**Given** `variant="range"`
+**When** the panel renders
+**Then** two month columns are shown side by side, the second showing the month
+after the first
+**And** each column has its own month/year header
+**And** the first column draws the vertical divider as its inline-end border, so
+the rule sits between the columns and mirrors under `dir="rtl"`
+**And** a single footer spans the whole panel below both columns
+
+---
+
+### Single-date selection
+
+#### Selects a date
+
+**Given** `variant="single"`
+**When** a day cell is clicked
+**Then** that day gets `data-active="true"` and takes the active cell
+background + active value color
+**And** the select event fires with the clicked `Date` and the trigger date
+
+#### Replaces the previous date
+
+**Given** `variant="single"` with a day already selected
+**When** a different day is clicked
+**Then** only the newly clicked day carries `data-active="true"`
+**And** the select event fires with the new `Date`
+
+#### Commits immediately
+
+**Given** `variant="single"`
+**When** a day is clicked
+**Then** the selection is final — there is no footer to confirm it with
+
+---
+
+### Multi-date selection
+
+#### Adds and removes dates
+
+**Given** `variant="multiple"`
+**When** several day cells are clicked in turn
+**Then** each clicked day carries `data-active="true"`
+**And** the select event fires each time with the full `Date[]`
+**And** clicking an already-selected day removes it from the array
+
+#### Honors `max`
+
+**Given** `variant="multiple"` with `max={3}` and three dates already selected
+**When** a fourth day is clicked
+**Then** the selection does not grow past three dates
+**And** removing one of the selected days frees a slot again
+
+#### Honors `min`
+
+**Given** `variant="multiple"` with `min={2}` and exactly two dates selected
+**When** one of the selected days is clicked to deselect it
+**Then** the selection is not reduced below two dates
+
+---
+
+### Range selection
+
+#### Picks a start, then an end
+
+**Given** `variant="range"` with nothing selected
+**When** a day is clicked
+**Then** it becomes the range start and carries `data-active="true"`
+**And** the select event fires with `{ from }` only
+**When** a later day is then clicked
+**Then** it becomes the range end and also carries `data-active="true"`
+**And** the select event fires with `{ from, to }`
+
+#### Highlights the days between the endpoints
+
+**Given** a completed range
+**When** the grid renders
+**Then** every day strictly between the endpoints carries
+`data-range-middle="true"` and takes the hover-tier fill with the primary value
+color
+**And** those days do **not** carry `data-active` — the two attributes are
+mutually exclusive, so the endpoint and in-range backgrounds never compete
+**And** no cell is rounded: endpoints get no "pill" treatment in this design
+
+#### Spans both months
+
+**Given** `variant="range"`
+**When** the start is picked in the first month column and the end in the second
+**Then** the in-range highlighting continues across both grids
+
+#### Honors `min` / `max`
+
+**Given** `variant="range"` with `max={7}`
+**When** an end date more than seven days after the start is clicked
+**Then** the range is not accepted beyond the allowed length
+
+---
+
+### Month / year navigation
+
+#### Navigates by month
+
+**Given** `variant="single"` or `variant="multiple"`, or the **first** column
+of `variant="range"`
+**When** a month is chosen in that column's month dropdown
+**Then** the grid re-renders on that month of the same year
+**And** the month-change event fires with the new month
+
+**Given** the **second** column of `variant="range"`
+**When** a month is chosen in that column's month dropdown
+**Then** both columns re-render, the second showing the chosen month
+**And** the month-change event fires with the month **one before** the chosen
+one — `month` is always the first displayed month, so choosing month M in the
+second column reports M − 1
+
+#### Navigates by year
+
+**Given** `variant="single"` or `variant="multiple"`, or the **first** column
+of `variant="range"`
+**When** a year is chosen in that column's year dropdown
+**Then** the grid re-renders on the same month of that year
+**And** the month-change event fires with the new month
+
+**Given** the **second** column of `variant="range"`
+**When** a year is chosen in that column's year dropdown
+**Then** both columns re-render, the second showing the chosen year
+**And** the month-change event fires with the month one before the chosen
+column's month, in the chosen year (same asymmetry as month navigation above)
+
+#### There are no prev/next chevrons
+
+**Given** any variant
+**When** the panel renders
+**Then** no previous/next month buttons exist — the two dropdowns are the only
+navigation affordance, per the design
+
+#### Year window is configurable
+
+**Given** `fromYear={2020}` and `toYear={2030}`
+**When** the year dropdown is opened
+**Then** it lists exactly 2020 through 2030
+**And** with neither prop it spans the current year ±50
+
+#### Year window also clamps grid navigation
+
+**Given** `fromYear={2020}` and `toYear={2030}`
+**When** the grid is navigated past that window — a controlled `month`
+outside the range, or Shift+PageUp/PageDown repeated past an edge
+**Then** the displayed month does not move past January 2020 or December 2030
+**And** this clamp applies even though the year dropdown's option list is a
+separate concern from grid navigation
+
+#### Month names are formattable
+
+**Given** a `formatMonthLabel` returning abbreviated or localized names
+**When** the month dropdown renders
+**Then** its items and its displayed value use those strings
+
+#### Uncontrolled vs controlled month
+
+**Given** `defaultMonth` set and no `month`
+**When** the panel renders and a dropdown is used
+**Then** the panel starts on `defaultMonth` and then manages the displayed month
+itself
+
+**Given** `month` supplied
+**When** a dropdown is used
+**Then** the month-change event fires but the grid only moves once the consumer
+passes a new `month` back
+
+---
+
+### Footer actions
+
+#### Cancel
+
+**Given** `variant="multiple"` or `"range"`
+**When** the Cancel button is pressed
+**Then** the cancel event fires
+**And** the panel neither reverts the selection nor closes itself — the caller
+decides what "cancel" means
+
+#### Apply
+
+**Given** `variant="multiple"` or `"range"`
+**When** the Apply button is pressed
+**Then** the apply event fires
+**And** the panel stays mounted and keeps its selection — the caller commits and
+dismisses the surrounding surface
+
+#### Apply is never disabled
+
+**Given** `variant="multiple"` or `"range"` with an empty or partial selection
+(e.g. `range` with only `from` set, or nothing selected at all)
+**When** the Apply button is pressed
+**Then** the apply event still fires — the panel does not gate Apply on
+selection completeness or on the selection having changed
+**And** it is the caller's responsibility to disable/hide Apply or otherwise
+guard `onApply` if committing an empty or half-open selection is undesirable
+
+#### No footer events for `single`
+
+**Given** `variant="single"` with cancel and apply handlers supplied
+**When** the user interacts with the panel
+**Then** neither handler can ever fire — no footer is rendered
+
+#### Footer labels are overridable
+
+**Given** `cancelLabel` and `applyLabel`
+**When** the footer renders
+**Then** the buttons use those strings as their visible (and accessible) names
+
+---
+
+### Disabled and outside days
+
+#### Disabled days cannot be selected
+
+**Given** `disabled={{ before: today }}`
+**When** the grid renders
+**Then** every day before today renders in the disabled value color and takes no
+pointer events
+**And** clicking one changes nothing and fires no select event
+
+#### Outside days
+
+**Given** `showOutsideDays` left at its default
+**When** the grid renders
+**Then** the leading/trailing days of the adjacent months fill the first and last
+week rows, in the disabled value color
+**And** they stay clickable and selectable — unlike a `disabled` day, they are
+only visually de-emphasized, not blocked from pointer interaction; they are
+excluded only from keyboard focus (Tab / arrow-key roaming can never land on
+one)
+
+**Given** `showOutsideDays={false}`
+**When** the grid renders
+**Then** those cells are empty instead
+
+---
+
+### Controlled vs uncontrolled selection
+
+#### Uncontrolled
+
+**Given** `selected` supplied without a select handler
+**When** days are clicked
+**Then** the panel starts from `selected` and then manages the selection itself
+
+#### Controlled
+
+**Given** both `selected` and the select handler supplied
+**When** a day is clicked
+**Then** the event fires with the next value
+**And** the highlighting only changes once the consumer passes the new `selected`
+back — a handler that ignores the value leaves the grid unchanged
+
+---
+
+### Week start
+
+#### Starts on Monday by default
+
+**Given** neither `weekStartsOn` nor `locale`
+**When** the grid renders
+**Then** the weekday row begins with Monday, per the design
+
+**Given** `weekStartsOn={0}`
+**When** the grid renders
+**Then** the weekday row and every week begin with Sunday
+
+#### Follows the locale when `weekStartsOn` is unset
+
+**Given** a `locale` with its own week start (e.g. `enUS` → Sunday) and no
+`weekStartsOn`
+**When** the grid renders
+**Then** the weekday row begins on that locale's first day, not Monday
+
+**Given** both `locale` and `weekStartsOn`
+**When** the grid renders
+**Then** the explicit `weekStartsOn` wins over the locale
+
+---
+
+### Text direction
+
+#### `dir` mirrors keyboard roaming, not just layout
+
+**Given** `dir="rtl"` passed to the panel
+**When** the day grid renders
+**Then** the `range` divider and the panel's own layout already mirror via
+logical CSS properties, regardless of `dir`
+**And**, additionally, Arrow Left/Right roaming direction flips — because
+`dir` is forwarded to the underlying day grid explicitly, which only mirrors
+its own keyboard handling when `dir` reaches it directly
+
+**Given** an ancestor sets `dir="rtl"` but the panel's own `dir` prop is left
+unset
+**When** the day grid renders
+**Then** the panel's layout still mirrors (inherited via logical properties)
+**But** Arrow Left/Right roaming direction does **not** flip
+
+## Accessibility
+
+The day grid's roles, keyboard model and selection semantics are **inherited from
+`react-day-picker`** — none of it is custom. This component replaces two of the
+library's rendered parts (`MonthCaption` → the `InputSelect` header,
+`DayButton` → the styled day cell) and adds the footer; everything else, the
+grid semantics included, is the library's.
+
+## Roles & semantics (inherited from react-day-picker)
+
+- Each month's grid is a `<table role="grid">`, with a weekday header row of
+  column headers and one row per week.
+- Each day cell is a `gridcell` containing a focusable `<button>`; the selected
+  state is exposed via `aria-selected` on the cell.
+- `multiple` and `range` grids additionally carry `aria-multiselectable` on the
+  grid — the only announced difference between the variants' grids.
+- Days matched by `disabled` render as disabled buttons — out of the tab order
+  and not activatable.
+- Outside days (the adjacent months' filler days) are rendered but only
+  visually de-emphasized — react-day-picker exposes them via a `data-outside`
+  hook on the cell with no additional ARIA state (no `aria-hidden`, no
+  `aria-disabled`). They stay mouse-clickable and selectable, but
+  react-day-picker excludes them from the roving-tabindex focus target, so
+  they can never be reached via Tab or arrow-key roaming — pointer-only, not
+  "ordinary" day buttons.
+- The day button additionally carries `data-day`, `data-active` (a selected day
+  or either range endpoint) and `data-range-middle` (a day between the
+  endpoints). These are styling hooks, not a11y state — `aria-selected` remains
+  the announced source of truth.
+
+## The month / year dropdowns
+
+- The header is **not** react-day-picker's `captionLayout="dropdown"` native
+  `<select>` pair — it is two real `InputSelect` instances, so they inherit
+  `InputSelect`'s listbox semantics, typeahead and keyboard model.
+- Neither dropdown has a visible label in the design, so the component supplies
+  the accessible name itself: `monthLabel` (default `'Month'`) and `yearLabel`
+  (default `'Year'`) are applied as the trigger's `aria-label`. Both are props —
+  override them to localize.
+- The month dropdown's option text comes from `formatMonthLabel`, so the
+  announced month names localize with it.
+
+## Keyboard
+
+| Key                            | Element               | Action                                                                                                                                     |
+| ------------------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| Tab / Shift+Tab                | panel                 | Moves between the month dropdown, the year dropdown, the grid, and the footer buttons                                                      |
+| Arrow Left / Right             | day grid              | Moves focus one day back / forward; mirrors under `dir="rtl"` (inherited, but only when `dir` is passed to the panel — see the `dir` prop) |
+| Arrow Up / Down                | day grid              | Moves focus one week back / forward (inherited)                                                                                            |
+| Home / End                     | day grid              | Moves focus to the first / last day of the week (inherited)                                                                                |
+| Page Up / Page Down            | day grid              | Moves focus to the previous / next month (inherited)                                                                                       |
+| Shift+Arrow Left / Right       | day grid              | Moves focus to the same weekday in the previous / next month (inherited)                                                                   |
+| Shift+Arrow Up / Down          | day grid              | Moves focus to the same date in the previous / next year (inherited)                                                                       |
+| Shift+Page Up / Page Down      | day grid              | Moves focus to the previous / next year (inherited)                                                                                        |
+| Enter / Space                  | focused day           | Selects the focused day (inherited)                                                                                                        |
+| Enter / Space, Arrow Up / Down | month / year dropdown | Opens the dropdown and moves through options (InputSelect)                                                                                 |
+| Escape                         | open dropdown         | Closes the dropdown without changing the month (InputSelect)                                                                               |
+| Enter / Space                  | Cancel / Apply        | Activates the footer action                                                                                                                |
+
+The grid is a single tab stop with arrow-key roaming (the roving-tabindex
+day-grid model), so Tab does not walk 28–42 individual day buttons. When
+react-day-picker marks a day as focused, the day button pulls DOM focus to
+itself so the roaming stays in sync.
+
+`CalendarPanel` renders a **panel**, not a modal dialog — it has no
+`role="dialog"`, no focus trap and no Escape-to-close. Wrap it in a `Popover`
+or `Dialog` when those semantics are wanted; that wrapper owns them.
+
+## Focus indication
+
+- The focused day cell shows a 3px focus ring in `--ui-focus-primary`, raised
+  above its neighbours (`z-index`) so the ring is not clipped by the adjacent
+  flat cells.
+- The dropdowns and footer buttons use their own components' focus rings, which
+  resolve to the same `--ui-focus-primary` token.
+
+## Screen reader
+
+1. Moving into the grid announces the focused date and, when selected, its
+   selected state.
+2. Disabled days are announced as unavailable.
+3. Choosing a month or year re-renders the grid; the newly focused date is
+   announced on the next arrow-key move.
+4. The footer buttons announce their visible labels (`cancelLabel` /
+   `applyLabel`).
+
+## Color and contrast
+
+| Element                                 | Minimum ratio | Standard               |
+| --------------------------------------- | ------------- | ---------------------- |
+| Day number vs cell background           | 4.5:1         | WCAG 1.4.3 (AA)        |
+| Selected day number vs active cell fill | 4.5:1         | WCAG 1.4.3 (AA)        |
+| Weekday abbreviation vs panel surface   | 4.5:1         | WCAG 1.4.3 (AA)        |
+| Panel / divider borders vs surface      | 3:1           | WCAG 1.4.11 (non-text) |
+| Focus indicator                         | 3:1           | WCAG 1.4.11            |
+
+Disabled days use `--ui-calendar-value-color-disabled` and are exempt from the
+text-contrast minimum (WCAG 1.4.3 excludes inactive controls).
+
+Outside days (the adjacent months' filler days — see above) share that same
+`--ui-calendar-value-color-disabled` token even though they remain
+mouse-clickable and selectable, not inactive controls in the ARIA sense —
+they are simply unreachable by keyboard (see "Roles & semantics" above).
+Measured against `--ui-calendar-container-color`, this renders at 2.13:1
+(light) / 2.31:1 (dark) — below the 4.5:1 minimum this table requires
+elsewhere. This is a known, accepted design trade-off (visual de-emphasis of
+adjacent-month days takes priority over AA contrast for that one element),
+not a WCAG exemption — unlike disabled days, no exclusion in the standard
+actually applies to them.
+
+Regardless of contrast, selection is never conveyed by color alone —
+`aria-selected` carries it for assistive tech.
+
+## Testing checklist
+
+- [ ] Each month renders a `role="grid"` table with a weekday header row
+- [ ] Day cells are `gridcell`s and expose `aria-selected`
+- [ ] Arrow keys roam the grid; Tab does not enter every day button
+- [ ] Enter/Space on the focused day selects it
+- [ ] The month and year dropdowns have accessible names from `monthLabel` /
+      `yearLabel`, and both are overridable
+- [ ] The focused day shows the `--ui-focus-primary` ring, unclipped
+- [ ] Disabled days are not focusable or selectable
+- [ ] Outside days are not focusable via Tab or arrow-key roaming, but remain
+      mouse-clickable and selectable
+- [ ] Cancel / Apply announce `cancelLabel` / `applyLabel`, and are absent for
+      `variant="single"`
+- [ ] The panel renders correctly under `dir="rtl"`, including the `range`
+      divider (an inline-end border, so it mirrors)
+- [ ] With `dir="rtl"` passed to the panel, Arrow Left/Right roaming direction
+      also mirrors (it only flips when `dir` reaches the day grid directly)