From b1aec8cd472a027452d52e59b0b6d7a95c343460 Mon Sep 17 00:00:00 2001
From: HerbertJulio <herbert.julio@azion.com>
Date: Tue, 30 Jun 2026 20:17:26 -0300
Subject: [PATCH] [ENG-46317] feat(webkit): evolve Calendar into a date-range
 picker

Replace the inline month grid with a full date-range picker (composition, spec_version 3): a trigger that opens a CSS-positioned popover with a multi-month grid, Start/End date + time fields, a timezone selector, an Apply action, a presets rail, a clearable/split trigger, size variants, a horizontal layout, and a Select Period relative-time mode (parses 45m, last month, 1/1 - 1/2). Native Date + Intl only; no positioning or date libraries.
---
 .specs/calendar.md                            | 161 +++-
 .../inputs/calendar/Calendar.stories.js       | 366 +++++++--
 packages/webkit/package.json                  |   5 +-
 .../calendar-clear/calendar-clear.vue         |  50 ++
 .../calendar-fields/calendar-fields.vue       | 158 ++++
 .../calendar/calendar-grid/calendar-grid.vue  | 390 +++++++++
 .../calendar-period/calendar-period.vue       | 101 +++
 .../calendar-preset/calendar-preset.vue       |  81 ++
 .../calendar-timezone/calendar-timezone.vue   |  58 ++
 .../components/inputs/calendar/calendar.vue   | 770 ++++++++++--------
 .../src/components/inputs/calendar/format.ts  | 171 ++++
 .../src/components/inputs/calendar/index.ts   |  34 +
 .../inputs/calendar/injection-key.ts          |  75 ++
 .../inputs/calendar/parse-period.ts           | 215 +++++
 14 files changed, 2205 insertions(+), 430 deletions(-)
 create mode 100644 packages/webkit/src/components/inputs/calendar/calendar-clear/calendar-clear.vue
 create mode 100644 packages/webkit/src/components/inputs/calendar/calendar-fields/calendar-fields.vue
 create mode 100644 packages/webkit/src/components/inputs/calendar/calendar-grid/calendar-grid.vue
 create mode 100644 packages/webkit/src/components/inputs/calendar/calendar-period/calendar-period.vue
 create mode 100644 packages/webkit/src/components/inputs/calendar/calendar-preset/calendar-preset.vue
 create mode 100644 packages/webkit/src/components/inputs/calendar/calendar-timezone/calendar-timezone.vue
 create mode 100644 packages/webkit/src/components/inputs/calendar/format.ts
 create mode 100644 packages/webkit/src/components/inputs/calendar/index.ts
 create mode 100644 packages/webkit/src/components/inputs/calendar/injection-key.ts
 create mode 100644 packages/webkit/src/components/inputs/calendar/parse-period.ts

diff --git a/.specs/calendar.md b/.specs/calendar.md
index 70b19ad38..2e69045a1 100644
--- a/.specs/calendar.md
+++ b/.specs/calendar.md
@@ -1,22 +1,22 @@
 ---
 name: calendar
 category: inputs
-structure: monolithic
+structure: composition
 status: approved
-spec_version: 1
+spec_version: 3
 figma:
   url: https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=5087-17336
   node_id: 5087:17336
-checksum: b12599fa9619bc2e9b19e5e6011c7620099b2be7d92b9ff60e2ce8771bc425b1
+checksum: b1d756030feb2361958413f5d39fbddfebb9a8f652a8e5a98e7074eaf06d2894
 created: 2026-06-25
-last_updated: 2026-06-25
+last_updated: 2026-06-30
 ---
 
 # Calendar — Component Spec
 
 ## Purpose
 
-Inline date picker that renders a month grid for selecting a single date or a date range. Unlike a popover-anchored datepicker, Calendar is always-visible (no overlay, no positioning) and is the standalone surface a consumer embeds in a form, panel, or popover body. Date math uses the native `Date` API only — no date library.
+Date-range picker. A trigger button opens a popover that holds a one-click presets rail, one or more month grids, Start/End date + time fields, an optional timezone selector, and an Apply action; it also offers a "Select Period" mode whose text input parses relative spans (`45m`, `12 hours`, `last month`, `yesterday`, `1/1 - 1/2`). Selection is staged in a draft inside the popover and committed to `v-model` only on Apply (or immediately when `show-apply` is false). Date math uses the native `Date` API only — no date library; timezone is a selectable IANA label used for display formatting via `Intl` (the picker does not re-interpret `Date` objects across zones).
 
 ## Usage
 
@@ -26,73 +26,149 @@ import { ref } from 'vue'
 
 import Calendar from '@aziontech/webkit/calendar'
 
-const selected = ref(new Date(2026, 9, 8))
+const range = ref({ start: new Date(2026, 9, 8), end: new Date(2026, 9, 19) })
+
+const presets = [
+  { label: 'Last 7 days', value: { start: new Date(2026, 9, 13), end: new Date(2026, 9, 19) } },
+  { label: 'Last 30 days', value: { start: new Date(2026, 8, 20), end: new Date(2026, 9, 19) } }
+]
+</script>
+
+<template>
+  <Calendar
+    v-model="range"
+    mode="range"
+    :number-of-months="2"
+    :presets="presets"
+    show-time
+    show-timezone
+    clearable
+  />
+</template>
+```
+
+The root renders the complete picker from props. For custom presets you may compose `<Calendar.Preset>` in the `presets` slot and a `<Calendar.Clear>` in the `footer` slot:
+
+```vue
+<script setup>
+import Calendar from '@aziontech/webkit/calendar'
 </script>
 
 <template>
-  <Calendar v-model="selected" />
+  <Calendar v-model="range" mode="range">
+    <template #presets>
+      <Calendar.Preset :value="{ start: new Date(2026, 9, 13), end: new Date(2026, 9, 19) }">Last 7 days</Calendar.Preset>
+    </template>
+    <template #footer>
+      <Calendar.Clear>Clear</Calendar.Clear>
+    </template>
+  </Calendar>
 </template>
 ```
 
+Tree-shaking alternative — the standalone root + each sub-component from its own entry (no `Object.assign` compound pulled in):
+
+```vue
+<script setup>
+import Calendar from '@aziontech/webkit/calendar-root'
+import CalendarPreset from '@aziontech/webkit/calendar-preset'
+import CalendarClear from '@aziontech/webkit/calendar-clear'
+</script>
+```
+
+## Sub-components
+
+- `calendar-preset/calendar-preset.vue` — context-aware shortcut button; applies its `value` (a `Date` in single mode or a `{ start, end }` range) to the popover's draft selection through injected context and reflects a `data-selected` state when its value matches. Placed in the `presets` slot.
+- `calendar-clear/calendar-clear.vue` — context-aware button that clears the draft selection through injected context; disabled when there is no selection. Placed in the `footer` slot.
+
 ## Props
 
 | Prop | Type | Default | Required | JSDoc |
 |---|---|---|---|---|
-| `modelValue` | `Date \| null \| CalendarRange` | `null` | no | Selected value for v-model. A `Date` (or null) in single mode; a `{ start, end }` range object in range mode. |
-| `mode` | `'single' \| 'range'` | `'single'` | no | Selection mode. Single picks one date; range picks a start and end date. |
+| `modelValue` | `Date \| null \| CalendarRange` | `null` | no | Committed selection for v-model. A `Date` (or null) in single mode; a `{ start, end }` range in range mode. Only updated on Apply (or immediately when `showApply` is false). |
+| `mode` | `'single' \| 'range'` | `'range'` | no | Selection mode. Single picks one date; range picks a start and end date. |
+| `numberOfMonths` | `number` | `1` | no | Number of month grids rendered side-by-side; one shared previous/next pair pages the whole view by a month. |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | no | Size token; affects the trigger, day-cell hit-area, and typography. |
 | `min` | `Date \| undefined` | `undefined` | no | Earliest selectable date; earlier days render disabled. |
 | `max` | `Date \| undefined` | `undefined` | no | Latest selectable date; later days render disabled. |
-| `disabled` | `boolean` | `false` | no | Disables the whole grid and navigation, applying disabled tokens. |
-| `showHeader` | `boolean` | `true` | no | Shows the month/year label and previous/next month navigation. |
+| `disabled` | `boolean` | `false` | no | Disables the trigger, grid, and all controls, applying disabled tokens. |
+| `open` | `boolean \| undefined` | `undefined` | no | Controlled open state of the popover. Use with v-model:open; omit for uncontrolled. |
+| `placeholder` | `string` | `'Select a Date Range'` | no | Trigger text shown when there is no selection. |
+| `presets` | `CalendarPresetItem[]` | `[]` | no | Data-driven shortcuts rendered in the presets rail; each is `{ label, value }` where value is a `Date` or range. |
+| `showTime` | `boolean` | `false` | no | Shows Start/End time fields alongside the date fields. |
+| `showTimezone` | `boolean` | `false` | no | Shows the timezone selector below the fields. |
+| `timezone` | `string` | `''` | no | Selected IANA timezone for display formatting (v-model:timezone). Empty resolves to the local zone. |
+| `timezones` | `string[]` | `[]` | no | Timezone options for the selector; empty falls back to a curated list derived from `Intl`. |
+| `horizontal` | `boolean` | `false` | no | Lays the fields/apply column beside the calendar instead of below it. |
+| `clearable` | `boolean` | `false` | no | Shows a clear control on the trigger that empties the committed selection. |
+| `showApply` | `boolean` | `true` | no | Stages edits in a draft and requires Apply to commit; when false, every edit commits immediately. |
+| `period` | `boolean` | `false` | no | Enables the "Select Period" relative-time mode: a relative-preset list plus a text input that parses spans like `45m` or `last month`. |
+| `split` | `boolean` | `false` | no | Renders the trigger as a split control with a separate chevron affordance. |
 
 ## Events
 
 | Event | Payload | Notes |
 |---|---|---|
-| `update:modelValue` | `Date \| null \| CalendarRange` | v-model. The selected `Date` (single) or `{ start, end }` (range). |
-| `month-change` | `CalendarMonth` | Emitted when the visible month changes via navigation or keyboard paging. Payload is `{ year, month }` (month is 0-indexed). |
+| `update:modelValue` | `Date \| null \| CalendarRange` | v-model. The committed `Date` (single) or `{ start, end }` (range); empty value on clear. |
+| `update:open` | `boolean` | v-model:open. Emitted when the popover opens or closes. |
+| `update:timezone` | `string` | v-model:timezone. Emitted when the timezone selection changes. |
+| `month-change` | `CalendarMonth` | Emitted when the first visible month changes via navigation or keyboard paging. Payload is `{ year, month }` (month is 0-indexed). |
+| `apply` | `Date \| null \| CalendarRange` | Emitted when the draft selection is committed via Apply. |
 
 ## Slots
 
-| _none_ | — | — |
+| Slot | Scope | Notes |
+|---|---|---|
+| `trigger` | `{ open, value, displayValue }` | Replaces the default trigger button; scope exposes the open state, raw value, and formatted label. |
+| `presets` | — | Custom presets rail content (e.g. `<Calendar.Preset>`); overrides the `presets` prop rendering. |
+| `footer` | — | Custom footer/action-bar content (e.g. `<Calendar.Clear>`) alongside Apply. |
 
 ## States
 
-- Visual states: `default`, `hover`, `focus-visible`, `selected`, `in-range`, `disabled`, `today`, `outside` (adjacent-month)
-- `data-selected` mirrors a fully-selected day cell (single value, or a range endpoint)
-- `data-band` on each day cell drives the connected range highlight: `none` | `single` | `start` | `middle` | `end` (endpoints round the outer edge; `middle` paints the in-range band edge-to-edge)
-- `data-today` marks the current date
-- `data-outside` marks an adjacent-month day cell
-- `data-disabled` mirrors the `disabled` prop on the root and unselectable day cells
+- Visual states: `default`, `hover`, `focus-visible`, `selected`, `in-range`, `disabled`, `today`, `outside` (adjacent-month), popover `open` / `closed`
+- `data-state` on the root and trigger mirrors the popover open state (`open` | `closed`)
+- `data-size` mirrors the `size` prop on the root, trigger, and each day cell (`small` | `medium` | `large`)
+- `data-selected` mirrors a fully-selected day cell (single value, or a range endpoint) and an active preset
+- `data-band` on each day cell drives the connected range highlight: `none` | `single` | `start` | `middle` | `end`
+- `data-today` marks the current date; `data-outside` marks an adjacent-month day cell
+- `data-disabled` mirrors the `disabled` prop on the root, unselectable day cells, and the clear control when there is no selection
 
 ## Motion & Animations
 
 | Trigger | Animation / Transition | Token (see `.claude/docs/DESIGN.md` § Animations) | Reduced-motion fallback |
 |---|---|---|---|
+| popover open | `animate-popup-scale-in` | semantic (150ms · cubic-bezier) | `motion-reduce:animate-none` (instant) |
+| popover close | `animate-popup-scale-out` | semantic (110ms · cubic-bezier) | `motion-reduce:animate-none` (instant) |
 | hover/focus state change | `transition-colors duration-150 ease-out` | inline (matches catalog) | `motion-reduce:transition-none` |
 
 ## Tokens
 
 | Region | Token (DESIGN.md) |
 |---|---|
-| panel surface | `var(--bg-surface-raised)` |
-| panel border | `var(--border-default)` |
-| panel shape | `var(--shape-button)` |
-| day cell shape | `var(--shape-elements)` |
-| header typography | `.text-body-sm` |
+| popover surface | `var(--bg-surface-raised)` |
+| popover border | `var(--border-default)` |
+| popover shape | `var(--shape-card)` |
+| popover elevation | `var(--shadow-md)` |
+| trigger / field surface | `var(--bg-surface)` |
+| trigger / field border | `var(--border-default)` |
+| trigger / field shape | `var(--shape-elements)` |
+| section divider | `var(--border-default)` |
+| label typography | `.text-label-sm` |
 | weekday typography | `.text-label-sm` |
-| day typography | `.text-body-sm` |
-| header text | `var(--text-default)` |
-| weekday text | `var(--text-muted)` |
-| day text (current month) | `var(--text-default)` |
-| day text (adjacent month / disabled) | `var(--text-disabled)` |
+| day typography (small) | `.text-body-xs` |
+| day typography (medium) | `.text-body-sm` |
+| day typography (large) | `.text-body-md` |
+| body / value typography | `.text-body-sm` |
+| header / muted text | `var(--text-muted)` |
+| default text | `var(--text-default)` |
+| disabled text | `var(--text-disabled)` |
 | selected day surface | `var(--secondary)` |
 | selected day text | `var(--secondary-contrast)` |
 | in-range band | `var(--bg-mask)` |
 | hover surface | `var(--bg-hover)` |
-| nav button hover surface | `var(--bg-hover)` |
 | spacing (padding) | `var(--spacing-sm)` |
 | spacing (gap) | `var(--spacing-xxs)` |
+| spacing (sections) | `var(--spacing-md)` |
 | ring | `var(--ring-color)` |
 
 ## Theme gaps
@@ -103,17 +179,25 @@ const selected = ref(new Date(2026, 9, 8))
 
 ## Accessibility (WCAG 2.1 AA)
 
-- Visible focus: `focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-surface-raised)]`
-- Keyboard map: `Tab` enters the grid at the focused day; `Arrow` keys move focus one day (left/right) or one week (up/down) with roving tabindex; `Enter`/`Space` selects the focused day; `PageUp`/`PageDown` navigate to the previous/next month; previous/next nav buttons are reachable by `Tab`.
-- ARIA: grid uses `role="grid"` with `role="row"` and `role="gridcell"` descendants; selected cells set `aria-selected="true"`; the current date sets `aria-current="date"`; navigation buttons carry `aria-label` (previous month / next month); decorative chevron icons are `aria-hidden="true"`.
+- Visible focus: `focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-canvas)]` on the trigger and `focus-visible:ring-offset-[var(--bg-surface-raised)]` inside the popover.
+- Keyboard map: the trigger toggles the popover with `Enter`/`Space` and exposes `aria-haspopup`/`aria-expanded`; `Escape` and click-outside close it and return focus to the trigger; focus is trapped in the open popover. In the grid, `Tab` enters at the focused day, `Arrow` keys move focus (paging the visible window when crossing its first/last month), `Enter`/`Space` selects, `PageUp`/`PageDown` change month. Apply, Clear, presets, fields, and the timezone control are all reachable by `Tab`.
+- ARIA: each month grid uses `role="grid"` with `role="row"` and `role="gridcell"` descendants; selected cells set `aria-selected="true"`; the current date sets `aria-current="date"`; navigation buttons carry `aria-label`; the popover is labelled by the trigger; decorative icons are `aria-hidden="true"`.
 - Contrast ≥4.5:1 (text) / ≥3:1 (large + icons), including the disabled state.
-- `motion-reduce:transition-none` on animated states.
-- Touch target ≥40×40 px (or justified deviation): day cells use a 36×36 px hit area matching the Figma `--size-9` token; this is a justified deviation for dense month-grid layouts.
+- `motion-reduce:animate-none` on the popover and `motion-reduce:transition-none` on animated states.
+- Touch target ≥40×40 px (or justified deviation): day cells use a 32×32 px (`small`), 36×36 px (`medium`), or 40×40 px (`large`) hit area; `small`/`medium` are a justified deviation for dense month-grid layouts, `large` meets the 40 px target.
 
 ## Stories (Storybook)
 
-- Default — single mode with a preselected date.
-- Range — range mode showing a selected start/end with the in-range band. Justified: range selection is a distinct, mutually-exclusive mode (`mode="range"`) with its own visual state (`data-band`) that the Default single-mode story cannot demonstrate.
+- Default — range picker with a preselected range (trigger + popover). Justified: shows the baseline trigger→popover→grid flow.
+- Sizes — composite story rendering every `size` value side-by-side (canonical, the component declares a `size` prop).
+- Single — single-date mode (`mode="single"`). Justified: single is a distinct, mutually-exclusive mode the range default cannot show.
+- MultiMonth — two months side-by-side (`number-of-months="2"`). Justified: a structural layout axis (shared nav, band across a month boundary) no other story exercises.
+- Horizontal — `horizontal` layout with fields beside the calendar. Justified: a distinct layout the default vertical story cannot show.
+- WithPresets — a `presets` rail of shortcuts. Justified: the data-driven preset behavior (one-click range + active state) cannot be shown without it.
+- WithTime — `show-time` Start/End time fields. Justified: the time-field round-trip is a distinct capability.
+- WithTimezone — `show-timezone` selector. Justified: the timezone control is a distinct capability.
+- SelectPeriod — `period` relative-time mode (preset list + parsed text input). Justified: the relative-time parsing mode is mutually exclusive with the absolute calendar flow.
+- Clearable — `clearable` trigger that empties the committed selection. Justified: the clear affordance and disabled-when-empty behavior cannot be shown without it.
 
 ## Constraints — DO NOT
 
@@ -134,6 +218,7 @@ const selected = ref(new Date(2026, 9, 8))
 - Do not duplicate the `## Usage` block from the spec inside the Storybook story body. The block is injected once into `parameters.docs.description.component` by the storybook-write skill; copy it nowhere else.
 - Do not edit `.claude/docs/DESIGN.md`, `.claude/docs/COMPONENT_REQUIREMENTS.md`, or `.claude/docs/PRIMEVUE_ABSTRACTION.md`.
 - Do not edit the root `package.json` or `.github/workflows/*`.
+- Do not export composition sub-components without attaching them to the root compound (`index.ts` via `Object.assign`; vue-tsc generates `index.d.ts` — never hand-write it); the root export points at `index.ts`, and a standalone `./<name>-root` export points at the root `.vue` (tree-shaking). Do not invent overlay part names (`Trigger` / `Content`) on a component with no `data-state=open|closed`, and do not collapse a slot-shaped concern into a config-array prop. See `.claude/rules/compound-api.md`.
 - Do not change `structure` after `status: approved`. To change structure, bump `spec_version` and re-author the spec.
 - Do not create files outside the paths declared by your task (the orchestrator tells you exactly which files to write).
 - Do not run `git` commands, `pnpm install`, or any command that changes the lockfile.
diff --git a/apps/storybook/src/stories/components/inputs/calendar/Calendar.stories.js b/apps/storybook/src/stories/components/inputs/calendar/Calendar.stories.js
index 593213412..be5b62dbd 100644
--- a/apps/storybook/src/stories/components/inputs/calendar/Calendar.stories.js
+++ b/apps/storybook/src/stories/components/inputs/calendar/Calendar.stories.js
@@ -2,33 +2,29 @@ import { ref } from 'vue'
 
 import Calendar from '@aziontech/webkit/calendar'
 
-const SINGLE_SOURCE = [
-  '<script setup>',
-  "import { ref } from 'vue'",
-  '',
-  "import Calendar from '@aziontech/webkit/calendar'",
-  '',
-  'const selected = ref(new Date(2026, 9, 8))',
-  '</script>',
-  '',
-  '<template>',
-  '  <Calendar v-model="selected" />',
-  '</template>'
-].join('\n')
-
-const RANGE_SOURCE = [
-  '<script setup>',
-  "import { ref } from 'vue'",
-  '',
-  "import Calendar from '@aziontech/webkit/calendar'",
-  '',
-  'const selected = ref({ start: new Date(2026, 9, 8), end: new Date(2026, 9, 19) })',
-  '</script>',
-  '',
-  '<template>',
-  '  <Calendar v-model="selected" mode="range" />',
-  '</template>'
-].join('\n')
+const sfc = (body) =>
+  ['<script setup>', "import Calendar from '@aziontech/webkit/calendar'", '</script>', '', '<template>', body, '</template>'].join(
+    '\n'
+  )
+
+const DEFAULT_SOURCE = sfc('  <Calendar v-model="range" mode="range" />')
+const SIZES_SOURCE = sfc(
+  [
+    '  <div class="flex items-start gap-4">',
+    '    <Calendar v-model="range" mode="range" size="small" />',
+    '    <Calendar v-model="range" mode="range" size="medium" />',
+    '    <Calendar v-model="range" mode="range" size="large" />',
+    '  </div>'
+  ].join('\n')
+)
+const SINGLE_SOURCE = sfc('  <Calendar v-model="date" mode="single" placeholder="Select date" />')
+const MULTI_MONTH_SOURCE = sfc('  <Calendar v-model="range" mode="range" :number-of-months="2" />')
+const HORIZONTAL_SOURCE = sfc('  <Calendar v-model="range" mode="range" horizontal show-time />')
+const PRESETS_SOURCE = sfc('  <Calendar v-model="range" mode="range" :presets="presets" />')
+const TIME_SOURCE = sfc('  <Calendar v-model="range" mode="range" show-time />')
+const TIMEZONE_SOURCE = sfc('  <Calendar v-model="range" mode="range" show-time show-timezone />')
+const PERIOD_SOURCE = sfc('  <Calendar v-model="range" mode="range" period placeholder="Select period" />')
+const CLEARABLE_SOURCE = sfc('  <Calendar v-model="range" mode="range" clearable />')
 
 /** @type {import('@storybook/vue3').Meta<typeof Calendar>} */
 const meta = {
@@ -49,7 +45,7 @@ const meta = {
     docs: {
       description: {
         component:
-          'Inline date picker that renders a month grid for selecting a single date or a date range. Unlike a popover-anchored datepicker, Calendar is always-visible (no overlay, no positioning) and is the standalone surface a consumer embeds in a form, panel, or popover body. Date math uses the native `Date` API only — no date library.'
+          'Date-range picker. A trigger button opens a popover that holds a one-click presets rail, one or more month grids, Start/End date + time fields, an optional timezone selector, and an Apply action; it also offers a "Select Period" mode whose text input parses relative spans (`45m`, `12 hours`, `last month`, `yesterday`, `1/1 - 1/2`). Selection is staged in a draft inside the popover and committed to `v-model` only on Apply (or immediately when `show-apply` is false). Date math uses the native `Date` API only — no date library.'
       },
       canvas: {
         sourceState: 'shown'
@@ -59,100 +55,360 @@ const meta = {
   argTypes: {
     modelValue: {
       control: false,
-      description:
-        'Selected value for v-model. A Date (or null) in single mode; a range object in range mode.',
+      description: 'Committed selection for v-model (Date or range).',
       table: { category: 'props', type: { summary: 'Date | null | CalendarRange' } }
     },
     mode: {
       control: 'inline-radio',
       options: ['single', 'range'],
-      description: 'Selection mode. Single picks one date; range picks a start and end date.',
+      description: 'Selection mode.',
       table: {
         category: 'props',
         type: { summary: "'single' | 'range'" },
-        defaultValue: { summary: "'single'" }
+        defaultValue: { summary: "'range'" }
+      }
+    },
+    numberOfMonths: {
+      control: { type: 'number', min: 1, max: 3 },
+      description: 'Number of month grids rendered side-by-side.',
+      table: { category: 'props', type: { summary: 'number' }, defaultValue: { summary: '1' } }
+    },
+    size: {
+      control: 'inline-radio',
+      options: ['small', 'medium', 'large'],
+      description: 'Size token; affects the trigger, day-cell hit-area, and typography.',
+      table: {
+        category: 'props',
+        type: { summary: "'small' | 'medium' | 'large'" },
+        defaultValue: { summary: "'medium'" }
       }
     },
     min: {
       control: false,
-      description: 'Earliest selectable date; earlier days render disabled.',
+      description: 'Earliest selectable date.',
       table: { category: 'props', type: { summary: 'Date' } }
     },
     max: {
       control: false,
-      description: 'Latest selectable date; later days render disabled.',
+      description: 'Latest selectable date.',
       table: { category: 'props', type: { summary: 'Date' } }
     },
     disabled: {
       control: 'boolean',
-      description: 'Disables the whole grid and navigation, applying disabled tokens.',
+      description: 'Disables the trigger, grid, and all controls.',
+      table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
+    },
+    open: {
+      control: false,
+      description: 'Controlled open state of the popover (v-model:open).',
+      table: { category: 'props', type: { summary: 'boolean' } }
+    },
+    placeholder: {
+      control: 'text',
+      description: 'Trigger text shown when there is no selection.',
+      table: {
+        category: 'props',
+        type: { summary: 'string' },
+        defaultValue: { summary: "'Select date range'" }
+      }
+    },
+    presets: {
+      control: false,
+      description: 'Data-driven shortcuts rendered in the presets rail.',
+      table: { category: 'props', type: { summary: 'CalendarPresetItem[]' } }
+    },
+    showTime: {
+      control: 'boolean',
+      description: 'Shows Start/End time fields alongside the date fields.',
       table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
     },
-    showHeader: {
+    showTimezone: {
       control: 'boolean',
-      description: 'Shows the month/year label and previous/next month navigation.',
+      description: 'Shows the timezone selector below the fields.',
+      table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
+    },
+    timezone: {
+      control: 'text',
+      description: 'Selected IANA timezone for display formatting (v-model:timezone).',
+      table: { category: 'props', type: { summary: 'string' }, defaultValue: { summary: "''" } }
+    },
+    timezones: {
+      control: false,
+      description: 'Timezone options for the selector.',
+      table: { category: 'props', type: { summary: 'string[]' } }
+    },
+    horizontal: {
+      control: 'boolean',
+      description: 'Lays the fields/apply column beside the calendar instead of below it.',
+      table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
+    },
+    clearable: {
+      control: 'boolean',
+      description: 'Shows a clear control on the trigger that empties the committed selection.',
+      table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
+    },
+    showApply: {
+      control: 'boolean',
+      description: 'Stages edits in a draft and requires Apply to commit; when false, commits immediately.',
       table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'true' } }
     },
+    period: {
+      control: 'boolean',
+      description: 'Enables the Select Period relative-time mode.',
+      table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
+    },
+    split: {
+      control: 'boolean',
+      description: 'Renders the trigger as a split control with a separate chevron affordance.',
+      table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
+    },
     'onUpdate:modelValue': {
       action: 'update:modelValue',
-      description: 'Emitted when the selection changes.',
+      description: 'Emitted when the selection is committed.',
       table: { category: 'events', type: { summary: 'Date | null | CalendarRange' } }
     },
+    'onUpdate:open': {
+      action: 'update:open',
+      description: 'Emitted when the popover opens or closes.',
+      table: { category: 'events', type: { summary: 'boolean' } }
+    },
+    'onUpdate:timezone': {
+      action: 'update:timezone',
+      description: 'Emitted when the timezone selection changes.',
+      table: { category: 'events', type: { summary: 'string' } }
+    },
     onMonthChange: {
       action: 'month-change',
-      description: 'Emitted when the visible month changes via navigation or keyboard paging.',
+      description: 'Emitted when the first visible month changes.',
       table: { category: 'events', type: { summary: 'CalendarMonth' } }
+    },
+    onApply: {
+      action: 'apply',
+      description: 'Emitted when the draft selection is committed via Apply.',
+      table: { category: 'events', type: { summary: 'Date | null | CalendarRange' } }
     }
   },
   args: {
-    mode: 'single',
+    mode: 'range',
+    numberOfMonths: 1,
+    size: 'medium',
     disabled: false,
-    showHeader: true
+    showTime: false,
+    showTimezone: false,
+    horizontal: false,
+    clearable: false,
+    showApply: true,
+    period: false,
+    split: false
   }
 }
 
 export default meta
 
+const handlers = (args) => {
+  const { onUpdateModelValue, onUpdateOpen, onUpdateTimezone, onMonthChange, onApply, ...props } =
+    args
+  return { props, onUpdateModelValue, onUpdateOpen, onUpdateTimezone, onMonthChange, onApply }
+}
+
+const LISTENERS =
+  '@update:modelValue="onUpdateModelValue" @update:open="onUpdateOpen" @update:timezone="onUpdateTimezone" @month-change="onMonthChange" @apply="onApply"'
+
 /** @type {import('@storybook/vue3').StoryObj<typeof Calendar>} */
 export const Default = {
   render: (args) => ({
     components: { Calendar },
     setup() {
-      const { onUpdateModelValue, onMonthChange, ...props } = args
-      const selected = ref(new Date(2026, 9, 8))
+      const range = ref({ start: new Date(2026, 9, 8), end: new Date(2026, 9, 19) })
+      return { ...handlers(args), range }
+    },
+    template: `<Calendar v-model="range" v-bind="props" ${LISTENERS} />`
+  }),
+  parameters: {
+    docs: {
+      source: { code: DEFAULT_SOURCE },
+      description: { story: 'Range picker — the trigger opens a popover with the calendar grid and Apply.' }
+    }
+  }
+}
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Calendar>} */
+export const Sizes = {
+  render: () => ({
+    components: { Calendar },
+    setup() {
+      const range = ref({ start: new Date(2026, 9, 8), end: new Date(2026, 9, 19) })
+      return { range }
+    },
+    template: `<div class="flex items-start gap-4">
+      <Calendar v-model="range" mode="range" size="small" />
+      <Calendar v-model="range" mode="range" size="medium" />
+      <Calendar v-model="range" mode="range" size="large" />
+    </div>`
+  }),
+  parameters: {
+    docs: {
+      controls: { disable: true },
+      source: { code: SIZES_SOURCE },
+      description: { story: 'The three trigger sizes — `small`, `medium`, and `large`.' }
+    }
+  }
+}
 
-      return { props, selected, onUpdateModelValue, onMonthChange }
+/** @type {import('@storybook/vue3').StoryObj<typeof Calendar>} */
+export const Single = {
+  render: (args) => ({
+    components: { Calendar },
+    setup() {
+      const date = ref(new Date(2026, 9, 8))
+      return { ...handlers(args), date }
     },
-    template:
-      '<Calendar v-model="selected" v-bind="props" @update:modelValue="onUpdateModelValue" @month-change="onMonthChange" />'
+    template: `<Calendar v-model="date" v-bind="props" mode="single" placeholder="Select date" ${LISTENERS} />`
   }),
   parameters: {
     docs: {
       source: { code: SINGLE_SOURCE },
-      description: { story: 'Single-mode calendar with a preselected date.' }
+      description: { story: 'Single-date mode picks one day instead of a range.' }
+    }
+  }
+}
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Calendar>} */
+export const MultiMonth = {
+  render: (args) => ({
+    components: { Calendar },
+    setup() {
+      const range = ref({ start: new Date(2026, 9, 26), end: new Date(2026, 10, 8) })
+      return { ...handlers(args), range }
+    },
+    template: `<Calendar v-model="range" v-bind="props" mode="range" :number-of-months="2" ${LISTENERS} />`
+  }),
+  parameters: {
+    docs: {
+      source: { code: MULTI_MONTH_SOURCE },
+      description: {
+        story: 'Two months side-by-side; one shared nav pages both and the range band spans the boundary.'
+      }
     }
   }
 }
 
 /** @type {import('@storybook/vue3').StoryObj<typeof Calendar>} */
-export const Range = {
+export const Horizontal = {
   render: (args) => ({
     components: { Calendar },
     setup() {
-      const { onUpdateModelValue, onMonthChange, ...props } = args
-      const selected = ref({ start: new Date(2026, 9, 8), end: new Date(2026, 9, 19) })
+      const range = ref({ start: new Date(2026, 9, 8), end: new Date(2026, 9, 19) })
+      return { ...handlers(args), range }
+    },
+    template: `<Calendar v-model="range" v-bind="props" mode="range" horizontal show-time ${LISTENERS} />`
+  }),
+  parameters: {
+    docs: {
+      source: { code: HORIZONTAL_SOURCE },
+      description: { story: 'Horizontal layout places the Start/End fields and Apply beside the calendar.' }
+    }
+  }
+}
 
-      return { props, selected, onUpdateModelValue, onMonthChange }
+/** @type {import('@storybook/vue3').StoryObj<typeof Calendar>} */
+export const WithPresets = {
+  render: (args) => ({
+    components: { Calendar },
+    setup() {
+      const range = ref({ start: new Date(2026, 9, 13), end: new Date(2026, 9, 19) })
+      const presets = [
+        { label: 'Last 7 days', value: { start: new Date(2026, 9, 13), end: new Date(2026, 9, 19) } },
+        { label: 'Last 30 days', value: { start: new Date(2026, 8, 20), end: new Date(2026, 9, 19) } }
+      ]
+      return { ...handlers(args), range, presets }
     },
-    template:
-      '<Calendar v-model="selected" v-bind="props" mode="range" @update:modelValue="onUpdateModelValue" @month-change="onMonthChange" />'
+    template: `<Calendar v-model="range" v-bind="props" mode="range" :presets="presets" ${LISTENERS} />`
   }),
   parameters: {
     docs: {
-      source: { code: RANGE_SOURCE },
+      source: { code: PRESETS_SOURCE },
+      description: { story: 'A presets rail of one-click shortcuts that stage the range in the draft.' }
+    }
+  }
+}
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Calendar>} */
+export const WithTime = {
+  render: (args) => ({
+    components: { Calendar },
+    setup() {
+      const range = ref({
+        start: new Date(2026, 9, 8, 0, 0),
+        end: new Date(2026, 9, 19, 23, 59)
+      })
+      return { ...handlers(args), range }
+    },
+    template: `<Calendar v-model="range" v-bind="props" mode="range" show-time ${LISTENERS} />`
+  }),
+  parameters: {
+    docs: {
+      source: { code: TIME_SOURCE },
+      description: { story: 'Start/End time fields round-trip the hours and minutes of each endpoint.' }
+    }
+  }
+}
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Calendar>} */
+export const WithTimezone = {
+  render: (args) => ({
+    components: { Calendar },
+    setup() {
+      const range = ref({
+        start: new Date(2026, 9, 8, 0, 0),
+        end: new Date(2026, 9, 19, 23, 59)
+      })
+      return { ...handlers(args), range }
+    },
+    template: `<Calendar v-model="range" v-bind="props" mode="range" show-time show-timezone ${LISTENERS} />`
+  }),
+  parameters: {
+    docs: {
+      source: { code: TIMEZONE_SOURCE },
+      description: { story: 'A timezone selector (IANA zones) labels the selection; defaults to the local zone.' }
+    }
+  }
+}
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Calendar>} */
+export const SelectPeriod = {
+  render: (args) => ({
+    components: { Calendar },
+    setup() {
+      const range = ref(null)
+      return { ...handlers(args), range }
+    },
+    template: `<Calendar v-model="range" v-bind="props" mode="range" period placeholder="Select period" ${LISTENERS} />`
+  }),
+  parameters: {
+    docs: {
+      source: { code: PERIOD_SOURCE },
       description: {
-        story: 'Range mode showing a selected start and end date with the in-range band between them.'
+        story: 'Select Period mode: a relative-preset list plus a text input that parses spans like `45m` or `last month`.'
       }
     }
   }
 }
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Calendar>} */
+export const Clearable = {
+  render: (args) => ({
+    components: { Calendar },
+    setup() {
+      const range = ref({ start: new Date(2026, 9, 8), end: new Date(2026, 9, 19) })
+      return { ...handlers(args), range }
+    },
+    template: `<Calendar v-model="range" v-bind="props" mode="range" clearable ${LISTENERS} />`
+  }),
+  parameters: {
+    docs: {
+      source: { code: CLEARABLE_SOURCE },
+      description: { story: 'A clear control on the trigger empties the committed selection when present.' }
+    }
+  }
+}
diff --git a/packages/webkit/package.json b/packages/webkit/package.json
index 070759875..2c63cd863 100644
--- a/packages/webkit/package.json
+++ b/packages/webkit/package.json
@@ -100,7 +100,10 @@
     "./toast-close": "./src/components/feedback/toast/toast-close/toast-close.vue",
     "./skeleton": "./src/components/feedback/skeleton/skeleton.vue",
     "./progress-bar": "./src/components/feedback/progress-bar/progress-bar.vue",
-    "./calendar": "./src/components/inputs/calendar/calendar.vue",
+    "./calendar": "./src/components/inputs/calendar/index.ts",
+    "./calendar-root": "./src/components/inputs/calendar/calendar.vue",
+    "./calendar-preset": "./src/components/inputs/calendar/calendar-preset/calendar-preset.vue",
+    "./calendar-clear": "./src/components/inputs/calendar/calendar-clear/calendar-clear.vue",
     "./input-text": "./src/components/inputs/input-text/input-text.vue",
     "./input-number": "./src/components/inputs/input-number/input-number.vue",
     "./field-text": "./src/components/inputs/field-text/field-text.vue",
diff --git a/packages/webkit/src/components/inputs/calendar/calendar-clear/calendar-clear.vue b/packages/webkit/src/components/inputs/calendar/calendar-clear/calendar-clear.vue
new file mode 100644
index 000000000..d4d6c9e69
--- /dev/null
+++ b/packages/webkit/src/components/inputs/calendar/calendar-clear/calendar-clear.vue
@@ -0,0 +1,50 @@
+<script setup lang="ts">
+  import { computed, inject, useAttrs } from 'vue'
+
+  import { CalendarInjectionKey } from '../injection-key'
+
+  defineOptions({
+    name: 'CalendarClear',
+    inheritAttrs: false
+  })
+
+  defineSlots<{
+    default(): unknown
+  }>()
+
+  const attrs = useAttrs()
+  const ctx = inject(CalendarInjectionKey, null)
+
+  const testId = computed<string>(
+    () =>
+      (attrs['data-testid'] as string | undefined) ??
+      (ctx ? `${ctx.testId}__clear` : 'input-calendar__clear')
+  )
+
+  // Context-aware: disabled while the calendar is disabled or nothing is selected.
+  const disabled = computed<boolean>(
+    () => (ctx?.disabled.value ?? false) || !(ctx?.hasSelection.value ?? false)
+  )
+
+  const onClick = () => {
+    if (disabled.value) {
+      return
+    }
+
+    ctx?.clear()
+  }
+</script>
+
+<template>
+  <button
+    v-bind="$attrs"
+    type="button"
+    :disabled="disabled"
+    :data-testid="testId"
+    :data-disabled="disabled || null"
+    class="text-body-sm inline-flex items-center justify-center whitespace-nowrap rounded-[var(--shape-elements)] px-[var(--spacing-xs)] py-[var(--spacing-xxs)] text-[var(--text-default)] transition-colors duration-150 ease-out hover:bg-[var(--bg-hover)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-surface-raised)] data-[disabled]:cursor-not-allowed data-[disabled]:text-[var(--text-disabled)] motion-reduce:transition-none"
+    @click="onClick"
+  >
+    <slot />
+  </button>
+</template>
diff --git a/packages/webkit/src/components/inputs/calendar/calendar-fields/calendar-fields.vue b/packages/webkit/src/components/inputs/calendar/calendar-fields/calendar-fields.vue
new file mode 100644
index 000000000..8f5d7644c
--- /dev/null
+++ b/packages/webkit/src/components/inputs/calendar/calendar-fields/calendar-fields.vue
@@ -0,0 +1,158 @@
+<script setup lang="ts">
+  import { computed, inject, ref, watch } from 'vue'
+
+  import InputText from '../../input-text/input-text.vue'
+  import { asRange, asSingle, formatDate, formatTime } from '../format'
+  import { CalendarInjectionKey } from '../injection-key'
+  import { parseFixedDate } from '../parse-period'
+
+  defineOptions({
+    name: 'CalendarFields',
+    inheritAttrs: false
+  })
+
+  const ctx = inject(CalendarInjectionKey, null)
+
+  const mode = computed(() => ctx?.mode.value ?? 'single')
+  const showTime = computed(() => ctx?.showTime.value ?? false)
+  const size = computed(() => ctx?.size.value ?? 'medium')
+  const disabled = computed(() => ctx?.disabled.value ?? false)
+
+  const startDate = computed<Date | null>(() =>
+    mode.value === 'range'
+      ? asRange(ctx?.draft.value ?? null).start
+      : asSingle(ctx?.draft.value ?? null)
+  )
+  const endDate = computed<Date | null>(() => asRange(ctx?.draft.value ?? null).end)
+
+  const startDateText = ref('')
+  const startTimeText = ref('')
+  const endDateText = ref('')
+  const endTimeText = ref('')
+
+  const syncFromDraft = () => {
+    startDateText.value = startDate.value ? formatDate(startDate.value) : ''
+    startTimeText.value = startDate.value ? formatTime(startDate.value) : ''
+    endDateText.value = endDate.value ? formatDate(endDate.value) : ''
+    endTimeText.value = endDate.value ? formatTime(endDate.value) : ''
+  }
+
+  watch(() => ctx?.draft.value, syncFromDraft, { immediate: true, deep: true })
+
+  const parseTime = (text: string): { hours: number; minutes: number } | null => {
+    const match = text.trim().match(/^(\d{1,2}):(\d{2})\s*(am|pm)?$/i)
+    if (!match) {
+      return null
+    }
+    let hours = Number(match[1])
+    const minutes = Number(match[2])
+    const meridiem = match[3]?.toLowerCase()
+    if (minutes > 59) {
+      return null
+    }
+    if (meridiem) {
+      if (hours < 1 || hours > 12) {
+        return null
+      }
+      if (meridiem === 'pm' && hours !== 12) {
+        hours += 12
+      }
+      if (meridiem === 'am' && hours === 12) {
+        hours = 0
+      }
+    } else if (hours > 23) {
+      return null
+    }
+    return { hours, minutes }
+  }
+
+  const commitDate = (which: 'start' | 'end', text: string) => {
+    const parsed = parseFixedDate(text)
+    if (!parsed) {
+      syncFromDraft()
+      return
+    }
+    const existing = which === 'start' ? startDate.value : endDate.value
+    const hours = existing ? existing.getHours() : which === 'end' ? 23 : 0
+    const minutes = existing ? existing.getMinutes() : which === 'end' ? 59 : 0
+    ctx?.setEndpoint(
+      which,
+      new Date(parsed.getFullYear(), parsed.getMonth(), parsed.getDate(), hours, minutes)
+    )
+  }
+
+  const commitTime = (which: 'start' | 'end', text: string) => {
+    const time = parseTime(text)
+    const base = which === 'start' ? startDate.value : endDate.value
+    if (!time || !base) {
+      syncFromDraft()
+      return
+    }
+    ctx?.setEndpoint(
+      which,
+      new Date(base.getFullYear(), base.getMonth(), base.getDate(), time.hours, time.minutes)
+    )
+  }
+</script>
+
+<template>
+  <div
+    class="flex flex-col gap-[var(--spacing-sm)]"
+    data-testid="input-calendar__fields"
+  >
+    <div class="flex flex-col gap-[var(--spacing-xxs)]">
+      <span class="text-label-sm text-[var(--text-muted)]">
+        {{ mode === 'range' ? 'Start' : 'Date' }}
+      </span>
+      <div class="flex items-center gap-[var(--spacing-xs)]">
+        <InputText
+          :model-value="startDateText"
+          :size="size"
+          :disabled="disabled"
+          placeholder="Jun 1, 2026"
+          class="flex-1"
+          @update:model-value="startDateText = $event"
+          @change="commitDate('start', startDateText)"
+        />
+        <InputText
+          v-if="showTime"
+          :model-value="startTimeText"
+          :size="size"
+          :disabled="disabled"
+          placeholder="09:00 AM"
+          class="w-24 shrink-0"
+          @update:model-value="startTimeText = $event"
+          @change="commitTime('start', startTimeText)"
+        />
+      </div>
+    </div>
+
+    <div
+      v-if="mode === 'range'"
+      class="flex flex-col gap-[var(--spacing-xxs)]"
+    >
+      <span class="text-label-sm text-[var(--text-muted)]"> End </span>
+      <div class="flex items-center gap-[var(--spacing-xs)]">
+        <InputText
+          :model-value="endDateText"
+          :size="size"
+          :disabled="disabled"
+          placeholder="Jun 30, 2026"
+          class="flex-1"
+          @update:model-value="endDateText = $event"
+          @change="commitDate('end', endDateText)"
+        />
+        <InputText
+          v-if="showTime"
+          :model-value="endTimeText"
+          :size="size"
+          :disabled="disabled"
+          placeholder="05:00 PM"
+          class="w-24 shrink-0"
+          @update:model-value="endTimeText = $event"
+          @change="commitTime('end', endTimeText)"
+        />
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/packages/webkit/src/components/inputs/calendar/calendar-grid/calendar-grid.vue b/packages/webkit/src/components/inputs/calendar/calendar-grid/calendar-grid.vue
new file mode 100644
index 000000000..9a2389c0a
--- /dev/null
+++ b/packages/webkit/src/components/inputs/calendar/calendar-grid/calendar-grid.vue
@@ -0,0 +1,390 @@
+<script setup lang="ts">
+  import { computed, inject, nextTick, ref, watch } from 'vue'
+
+  import { asRange, asSingle, sameDay, startOfDay } from '../format'
+  import { CalendarInjectionKey } from '../injection-key'
+
+  defineOptions({
+    name: 'CalendarGrid',
+    inheritAttrs: false
+  })
+
+  const ctx = inject(CalendarInjectionKey, null)
+
+  const WEEKDAY_LABELS = ['S', 'M', 'T', 'W', 'T', 'F', 'S'] as const
+  const MS_PER_DAY = 86_400_000
+
+  const mode = computed(() => ctx?.mode.value ?? 'single')
+  const size = computed(() => ctx?.size.value ?? 'medium')
+  const disabledAll = computed(() => ctx?.disabled.value ?? false)
+  const monthCount = computed(() => Math.max(1, Math.floor(ctx?.numberOfMonths.value ?? 1)))
+  const draft = computed(() => ctx?.draft.value ?? null)
+
+  const seedDate = (): Date => {
+    if (mode.value === 'range') {
+      const range = asRange(draft.value)
+      if (range.start) {
+        return range.start
+      }
+    } else {
+      const single = asSingle(draft.value)
+      if (single) {
+        return single
+      }
+    }
+    return new Date()
+  }
+
+  const seed = seedDate()
+  const viewDate = ref<Date>(new Date(seed.getFullYear(), seed.getMonth(), 1))
+
+  const viewYear = computed(() => viewDate.value.getFullYear())
+  const viewMonth = computed(() => viewDate.value.getMonth())
+
+  const isMonthVisible = (date: Date): boolean => {
+    const first = new Date(viewYear.value, viewMonth.value, 1)
+    const afterLast = new Date(viewYear.value, viewMonth.value + monthCount.value, 1)
+    const target = new Date(date.getFullYear(), date.getMonth(), 1)
+    return target >= first && target < afterLast
+  }
+
+  watch(
+    () => ctx?.draft.value,
+    () => {
+      const next = seedDate()
+      if (!isMonthVisible(next)) {
+        viewDate.value = new Date(next.getFullYear(), next.getMonth(), 1)
+      }
+    }
+  )
+
+  const today = startOfDay(new Date())
+
+  const isBeforeMin = (date: Date): boolean => {
+    const min = ctx?.min.value
+    return Boolean(min && date < startOfDay(min))
+  }
+  const isAfterMax = (date: Date): boolean => {
+    const max = ctx?.max.value
+    return Boolean(max && date > startOfDay(max))
+  }
+  const isOutOfBounds = (date: Date): boolean => isBeforeMin(date) || isAfterMax(date)
+
+  type CalendarDayBand = 'none' | 'single' | 'start' | 'middle' | 'end'
+
+  interface CalendarDay {
+    date: Date
+    time: number
+    label: number
+    outside: boolean
+    disabled: boolean
+    today: boolean
+    selected: boolean
+    band: CalendarDayBand
+  }
+
+  interface CalendarMonthGrid {
+    key: string
+    year: number
+    month: number
+    label: string
+    weeks: CalendarDay[][]
+  }
+
+  const dayBand = (date: Date): CalendarDayBand => {
+    if (mode.value !== 'range') {
+      return sameDay(date, asSingle(draft.value)) ? 'single' : 'none'
+    }
+
+    const range = asRange(draft.value)
+    const time = startOfDay(date).getTime()
+    const start = range.start ? startOfDay(range.start).getTime() : null
+    const end = range.end ? startOfDay(range.end).getTime() : null
+
+    if (start !== null && end !== null) {
+      const lo = Math.min(start, end)
+      const hi = Math.max(start, end)
+      if (lo === hi) {
+        return time === lo ? 'single' : 'none'
+      }
+      if (time === lo) {
+        return 'start'
+      }
+      if (time === hi) {
+        return 'end'
+      }
+      return time > lo && time < hi ? 'middle' : 'none'
+    }
+
+    if ((start !== null && time === start) || (end !== null && time === end)) {
+      return 'single'
+    }
+
+    return 'none'
+  }
+
+  const buildWeeks = (year: number, month: number): CalendarDay[][] => {
+    const firstOfMonth = new Date(year, month, 1)
+    const gridStart = new Date(year, month, 1 - firstOfMonth.getDay())
+    const rows: CalendarDay[][] = []
+
+    for (let row = 0; row < 6; row += 1) {
+      const cells: CalendarDay[] = []
+      for (let col = 0; col < 7; col += 1) {
+        const date = new Date(
+          gridStart.getFullYear(),
+          gridStart.getMonth(),
+          gridStart.getDate() + row * 7 + col
+        )
+        const outside = date.getMonth() !== month
+        const band = dayBand(date)
+        cells.push({
+          date,
+          time: date.getTime(),
+          label: date.getDate(),
+          outside,
+          disabled: disabledAll.value || isOutOfBounds(date),
+          today: sameDay(date, today),
+          selected: band === 'single' || band === 'start' || band === 'end',
+          band
+        })
+      }
+      rows.push(cells)
+    }
+
+    return rows
+  }
+
+  const monthGrids = computed<CalendarMonthGrid[]>(() =>
+    Array.from({ length: monthCount.value }, (_, index) => {
+      const date = new Date(viewYear.value, viewMonth.value + index, 1)
+      const year = date.getFullYear()
+      const month = date.getMonth()
+      return {
+        key: `${year}-${month}`,
+        year,
+        month,
+        label: date.toLocaleDateString('en-US', { month: 'long', year: 'numeric' }),
+        weeks: buildWeeks(year, month)
+      }
+    })
+  )
+
+  const focusedTime = ref<number | null>(null)
+
+  const inMonthDays = computed<CalendarDay[]>(() =>
+    monthGrids.value.flatMap((grid) => grid.weeks.flat()).filter((day) => !day.outside)
+  )
+
+  const activeTime = computed<number | null>(() => {
+    const flat = inMonthDays.value
+    if (
+      focusedTime.value !== null &&
+      flat.some((day) => day.time === focusedTime.value && !day.disabled)
+    ) {
+      return focusedTime.value
+    }
+    const selected = flat.find((day) => day.selected && !day.disabled)
+    if (selected) {
+      return selected.time
+    }
+    const current = flat.find((day) => day.today && !day.disabled)
+    if (current) {
+      return current.time
+    }
+    const firstEnabled = flat.find((day) => !day.disabled)
+    return firstEnabled ? firstEnabled.time : null
+  })
+
+  const gridRef = ref<globalThis.HTMLElement | null>(null)
+
+  const focusActiveCell = () => {
+    nextTick(() => {
+      gridRef.value?.querySelector<globalThis.HTMLButtonElement>('button[tabindex="0"]')?.focus()
+    })
+  }
+
+  const goToMonth = (year: number, month: number) => {
+    viewDate.value = new Date(year, month, 1)
+    ctx?.changeMonth({ year: viewDate.value.getFullYear(), month: viewDate.value.getMonth() })
+  }
+
+  const goToPreviousMonth = () => {
+    if (disabledAll.value) {
+      return
+    }
+    goToMonth(viewYear.value, viewMonth.value - 1)
+  }
+
+  const goToNextMonth = () => {
+    if (disabledAll.value) {
+      return
+    }
+    goToMonth(viewYear.value, viewMonth.value + 1)
+  }
+
+  const selectDay = (day: CalendarDay) => {
+    if (day.disabled) {
+      return
+    }
+    focusedTime.value = day.time
+    if (!isMonthVisible(day.date)) {
+      goToMonth(day.date.getFullYear(), day.date.getMonth())
+    }
+    ctx?.selectDay(day.date)
+  }
+
+  const moveFocus = (fromTime: number, deltaDays: number) => {
+    const normalized = startOfDay(new Date(fromTime + deltaDays * MS_PER_DAY))
+    focusedTime.value = normalized.getTime()
+    if (!isMonthVisible(normalized)) {
+      const firstMonthOffset = deltaDays < 0 ? 0 : monthCount.value - 1
+      goToMonth(normalized.getFullYear(), normalized.getMonth() - firstMonthOffset)
+    }
+    focusActiveCell()
+  }
+
+  const onDayKeydown = (event: globalThis.KeyboardEvent, day: CalendarDay) => {
+    switch (event.key) {
+      case 'ArrowLeft':
+        event.preventDefault()
+        moveFocus(day.time, -1)
+        break
+      case 'ArrowRight':
+        event.preventDefault()
+        moveFocus(day.time, 1)
+        break
+      case 'ArrowUp':
+        event.preventDefault()
+        moveFocus(day.time, -7)
+        break
+      case 'ArrowDown':
+        event.preventDefault()
+        moveFocus(day.time, 7)
+        break
+      case 'PageUp':
+        event.preventDefault()
+        goToPreviousMonth()
+        focusActiveCell()
+        break
+      case 'PageDown':
+        event.preventDefault()
+        goToNextMonth()
+        focusActiveCell()
+        break
+      case 'Enter':
+      case ' ':
+        event.preventDefault()
+        selectDay(day)
+        break
+      default:
+        break
+    }
+  }
+</script>
+
+<template>
+  <div
+    ref="gridRef"
+    class="flex items-start gap-[var(--spacing-md)]"
+    data-testid="input-calendar__grid"
+  >
+    <div
+      v-for="(monthGrid, monthIndex) in monthGrids"
+      :key="monthGrid.key"
+      class="flex flex-col items-start gap-[var(--spacing-md)]"
+    >
+      <div class="flex w-full items-center justify-between gap-[var(--spacing-xs)]">
+        <span class="text-body-sm text-[var(--text-default)]">
+          {{ monthGrid.label }}
+        </span>
+
+        <div class="flex shrink-0 items-center gap-[var(--spacing-xxs)]">
+          <button
+            v-if="monthIndex === 0"
+            type="button"
+            :disabled="disabledAll"
+            aria-label="Previous month"
+            class="inline-flex size-7 shrink-0 items-center justify-center rounded-[var(--shape-elements)] text-[var(--text-muted)] transition-colors duration-150 ease-out hover:bg-[var(--bg-hover)] hover:text-[var(--text-default)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-surface-raised)] disabled:cursor-not-allowed disabled:text-[var(--text-disabled)] motion-reduce:transition-none"
+            @click="goToPreviousMonth"
+          >
+            <i
+              class="pi pi-chevron-left text-[length:inherit] leading-none"
+              aria-hidden="true"
+            />
+          </button>
+
+          <button
+            v-if="monthIndex === monthGrids.length - 1"
+            type="button"
+            :disabled="disabledAll"
+            aria-label="Next month"
+            class="inline-flex size-7 shrink-0 items-center justify-center rounded-[var(--shape-elements)] text-[var(--text-muted)] transition-colors duration-150 ease-out hover:bg-[var(--bg-hover)] hover:text-[var(--text-default)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-surface-raised)] disabled:cursor-not-allowed disabled:text-[var(--text-disabled)] motion-reduce:transition-none"
+            @click="goToNextMonth"
+          >
+            <i
+              class="pi pi-chevron-right text-[length:inherit] leading-none"
+              aria-hidden="true"
+            />
+          </button>
+        </div>
+      </div>
+
+      <div
+        role="grid"
+        :aria-label="monthGrid.label"
+      >
+        <div
+          role="row"
+          class="flex items-start"
+        >
+          <span
+            v-for="(weekday, index) in WEEKDAY_LABELS"
+            :key="`weekday-${index}`"
+            role="columnheader"
+            :data-size="size"
+            class="text-label-sm flex items-start justify-center text-[var(--text-muted)] data-[size=small]:w-8 data-[size=medium]:w-9 data-[size=large]:w-10"
+          >
+            {{ weekday }}
+          </span>
+        </div>
+
+        <div class="flex flex-col items-start gap-[var(--spacing-xxs)]">
+          <div
+            v-for="(week, weekIndex) in monthGrid.weeks"
+            :key="`week-${weekIndex}`"
+            role="row"
+            class="flex items-start"
+          >
+            <div
+              v-for="day in week"
+              :key="day.time"
+              role="gridcell"
+              :aria-selected="day.selected || undefined"
+              :aria-current="day.today ? 'date' : undefined"
+              class="leading-none"
+            >
+              <button
+                type="button"
+                :disabled="day.disabled"
+                :data-size="size"
+                :data-band="day.band"
+                :data-selected="day.selected || null"
+                :data-today="day.today || null"
+                :data-outside="day.outside || null"
+                :data-disabled="day.disabled || null"
+                data-testid="input-calendar__day"
+                :tabindex="!day.outside && day.time === activeTime ? 0 : -1"
+                class="flex items-center justify-center text-[var(--text-default)] transition-colors duration-150 ease-out focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-surface-raised)] data-[size=small]:size-8 data-[size=small]:text-body-xs data-[size=medium]:size-9 data-[size=medium]:text-body-sm data-[size=large]:size-10 data-[size=large]:text-body-md data-[band=none]:rounded-[var(--shape-elements)] data-[band=none]:hover:bg-[var(--bg-hover)] data-[band=single]:rounded-[var(--shape-elements)] data-[band=single]:bg-[var(--secondary-selected)] data-[band=single]:text-[var(--secondary-contrast)] data-[band=start]:rounded-l-[var(--shape-elements)] data-[band=start]:bg-[var(--secondary-selected)] data-[band=start]:text-[var(--secondary-contrast)] data-[band=end]:rounded-r-[var(--shape-elements)] data-[band=end]:bg-[var(--secondary-selected)] data-[band=end]:text-[var(--secondary-contrast)] data-[band=middle]:bg-[var(--bg-selected)] data-[outside]:text-[var(--text-disabled)] data-[disabled]:cursor-not-allowed data-[disabled]:text-[var(--text-disabled)] motion-reduce:transition-none"
+                @click="selectDay(day)"
+                @keydown="onDayKeydown($event, day)"
+              >
+                {{ day.label }}
+              </button>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/packages/webkit/src/components/inputs/calendar/calendar-period/calendar-period.vue b/packages/webkit/src/components/inputs/calendar/calendar-period/calendar-period.vue
new file mode 100644
index 000000000..8610e6b68
--- /dev/null
+++ b/packages/webkit/src/components/inputs/calendar/calendar-period/calendar-period.vue
@@ -0,0 +1,101 @@
+<script setup lang="ts">
+  import { computed, inject, ref } from 'vue'
+
+  import { CalendarInjectionKey } from '../injection-key'
+  import { parsePeriod } from '../parse-period'
+
+  defineOptions({
+    name: 'CalendarPeriod',
+    inheritAttrs: false
+  })
+
+  const ctx = inject(CalendarInjectionKey, null)
+
+  const disabled = computed(() => ctx?.disabled.value ?? false)
+  const horizontal = computed(() => ctx?.horizontal.value ?? false)
+
+  const PRESETS = [
+    { label: 'Last 3 Days', expr: '3d' },
+    { label: 'Last Week', expr: 'last week' },
+    { label: 'Last Month', expr: 'last month' },
+    { label: 'Last Quarter', expr: '3mo' },
+    { label: 'Last Year', expr: 'last year' }
+  ] as const
+
+  const RELATIVE_HINTS = ['45m', '12 hours', '10d', '2 weeks', 'last month', 'yesterday', 'today']
+  const FIXED_HINTS = ['Jan 1', '1/1 - 1/2', '36 hours', '48 hours']
+
+  const activeExpr = ref('')
+
+  const apply = (expr: string) => {
+    const range = parsePeriod(expr)
+    if (range) {
+      activeExpr.value = expr
+      ctx?.selectValue(range)
+    }
+  }
+</script>
+
+<template>
+  <div
+    class="flex gap-[var(--spacing-md)]"
+    :class="horizontal ? 'flex-row items-start' : 'flex-col items-stretch'"
+    data-testid="input-calendar__period"
+  >
+    <div
+      class="flex min-w-[var(--container-4xs)] flex-col gap-[var(--spacing-xxs)]"
+      :class="horizontal ? '' : 'border-b border-[var(--border-default)] pb-[var(--spacing-sm)]'"
+    >
+      <button
+        v-for="preset in PRESETS"
+        :key="preset.expr"
+        type="button"
+        :disabled="disabled"
+        :data-active="activeExpr === preset.expr || null"
+        class="text-body-sm inline-flex w-full items-center justify-between gap-[var(--spacing-xs)] rounded-[var(--shape-elements)] px-[var(--spacing-xs)] py-[var(--spacing-xxs)] text-left text-[var(--text-default)] transition-colors duration-150 ease-out hover:bg-[var(--bg-hover)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-surface-raised)] data-[active]:bg-[var(--bg-selected)] disabled:cursor-not-allowed disabled:text-[var(--text-disabled)] motion-reduce:transition-none"
+        @click="apply(preset.expr)"
+      >
+        <span>{{ preset.label }}</span>
+        <i
+          v-if="activeExpr === preset.expr"
+          class="pi pi-check shrink-0 text-[length:inherit] leading-none text-[var(--text-muted)]"
+          aria-hidden="true"
+        />
+      </button>
+    </div>
+
+    <div class="flex flex-col gap-[var(--spacing-sm)]">
+      <div class="flex flex-col gap-[var(--spacing-xxs)]">
+        <span class="text-label-sm text-[var(--text-muted)]"> Type relative times </span>
+        <div class="flex max-w-[var(--container-2xs)] flex-wrap gap-[var(--spacing-xxs)]">
+          <button
+            v-for="hint in RELATIVE_HINTS"
+            :key="hint"
+            type="button"
+            :disabled="disabled"
+            class="text-label-sm inline-flex items-center rounded-[var(--shape-elements)] border border-[var(--border-default)] px-[var(--spacing-xs)] py-[var(--spacing-xxs)] text-[var(--text-default)] transition-colors duration-150 ease-out hover:bg-[var(--bg-hover)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-surface-raised)] disabled:cursor-not-allowed disabled:text-[var(--text-disabled)] motion-reduce:transition-none"
+            @click="apply(hint)"
+          >
+            {{ hint }}
+          </button>
+        </div>
+      </div>
+
+      <div class="flex flex-col gap-[var(--spacing-xxs)]">
+        <span class="text-label-sm text-[var(--text-muted)]"> Type fixed times </span>
+        <div class="flex max-w-[var(--container-2xs)] flex-wrap gap-[var(--spacing-xxs)]">
+          <button
+            v-for="hint in FIXED_HINTS"
+            :key="hint"
+            type="button"
+            :disabled="disabled"
+            class="text-label-sm inline-flex items-center rounded-[var(--shape-elements)] border border-[var(--border-default)] px-[var(--spacing-xs)] py-[var(--spacing-xxs)] text-[var(--text-default)] transition-colors duration-150 ease-out hover:bg-[var(--bg-hover)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-surface-raised)] disabled:cursor-not-allowed disabled:text-[var(--text-disabled)] motion-reduce:transition-none"
+            @click="apply(hint)"
+          >
+            {{ hint }}
+          </button>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/packages/webkit/src/components/inputs/calendar/calendar-preset/calendar-preset.vue b/packages/webkit/src/components/inputs/calendar/calendar-preset/calendar-preset.vue
new file mode 100644
index 000000000..ac339956a
--- /dev/null
+++ b/packages/webkit/src/components/inputs/calendar/calendar-preset/calendar-preset.vue
@@ -0,0 +1,81 @@
+<script setup lang="ts">
+  import { computed, inject, useAttrs } from 'vue'
+
+  import { CalendarInjectionKey, type CalendarRange } from '../injection-key'
+
+  defineOptions({
+    name: 'CalendarPreset',
+    inheritAttrs: false
+  })
+
+  const props = defineProps<{
+    /** Date (single mode) or range applied to the calendar selection when clicked. */
+    value: Date | CalendarRange
+  }>()
+
+  defineSlots<{
+    default(): unknown
+  }>()
+
+  const attrs = useAttrs()
+  const ctx = inject(CalendarInjectionKey, null)
+
+  const testId = computed<string>(
+    () =>
+      (attrs['data-testid'] as string | undefined) ??
+      (ctx ? `${ctx.testId}__preset` : 'input-calendar__preset')
+  )
+
+  const disabled = computed<boolean>(() => ctx?.disabled.value ?? false)
+
+  const sameDay = (a: Date | null | undefined, b: Date | null | undefined): boolean => {
+    if (!a || !b) {
+      return false
+    }
+
+    return (
+      a.getFullYear() === b.getFullYear() &&
+      a.getMonth() === b.getMonth() &&
+      a.getDate() === b.getDate()
+    )
+  }
+
+  // Context-aware: reflects a selected state when its value matches the draft selection.
+  const selected = computed<boolean>(() => {
+    const current = ctx?.draft.value ?? null
+    const target = props.value
+
+    if (target instanceof Date) {
+      return current instanceof Date && sameDay(current, target)
+    }
+
+    if (current && !(current instanceof Date)) {
+      return sameDay(current.start, target.start) && sameDay(current.end, target.end)
+    }
+
+    return false
+  })
+
+  const onClick = () => {
+    if (disabled.value) {
+      return
+    }
+
+    ctx?.selectValue(props.value)
+  }
+</script>
+
+<template>
+  <button
+    v-bind="$attrs"
+    type="button"
+    :disabled="disabled"
+    :data-testid="testId"
+    :data-selected="selected || null"
+    :data-disabled="disabled || null"
+    class="text-body-sm inline-flex w-full items-center whitespace-nowrap rounded-[var(--shape-elements)] px-[var(--spacing-xs)] py-[var(--spacing-xxs)] text-left text-[var(--text-default)] transition-colors duration-150 ease-out hover:bg-[var(--bg-hover)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-surface-raised)] data-[selected]:bg-[var(--secondary-selected)] data-[selected]:text-[var(--secondary-contrast)] data-[disabled]:cursor-not-allowed data-[disabled]:text-[var(--text-disabled)] motion-reduce:transition-none"
+    @click="onClick"
+  >
+    <slot />
+  </button>
+</template>
diff --git a/packages/webkit/src/components/inputs/calendar/calendar-timezone/calendar-timezone.vue b/packages/webkit/src/components/inputs/calendar/calendar-timezone/calendar-timezone.vue
new file mode 100644
index 000000000..5e5a688b7
--- /dev/null
+++ b/packages/webkit/src/components/inputs/calendar/calendar-timezone/calendar-timezone.vue
@@ -0,0 +1,58 @@
+<script setup lang="ts">
+  import { computed, inject } from 'vue'
+
+  import { defaultTimezones, formatTimezoneLabel, localTimezone } from '../format'
+  import { CalendarInjectionKey } from '../injection-key'
+
+  defineOptions({
+    name: 'CalendarTimezone',
+    inheritAttrs: false
+  })
+
+  const ctx = inject(CalendarInjectionKey, null)
+
+  const size = computed(() => ctx?.size.value ?? 'medium')
+  const disabled = computed(() => ctx?.disabled.value ?? false)
+
+  const options = computed<string[]>(() => {
+    const provided = ctx?.timezones.value ?? []
+    return provided.length > 0 ? provided : defaultTimezones()
+  })
+
+  const value = computed<string>(() => ctx?.timezone.value || localTimezone())
+
+  const onChange = (event: globalThis.Event) => {
+    const target = event.target as globalThis.HTMLSelectElement
+    ctx?.setTimezone(target.value)
+  }
+</script>
+
+<template>
+  <label
+    class="flex flex-col gap-[var(--spacing-xxs)]"
+    data-testid="input-calendar__timezone"
+  >
+    <span class="text-label-sm text-[var(--text-muted)]"> Timezone </span>
+    <span class="relative inline-flex w-full items-center">
+      <select
+        :value="value"
+        :disabled="disabled"
+        :data-size="size"
+        class="text-body-sm w-full appearance-none rounded-[var(--shape-elements)] border border-[var(--border-default)] bg-[var(--bg-surface)] pl-[var(--spacing-sm)] pr-[var(--spacing-lg)] text-[var(--text-default)] transition-colors duration-150 ease-out hover:border-[var(--border-strong)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-surface-raised)] disabled:cursor-not-allowed disabled:bg-[var(--bg-disabled)] disabled:text-[var(--text-disabled)] data-[size=small]:h-7 data-[size=medium]:h-8 data-[size=large]:h-10 motion-reduce:transition-none"
+        @change="onChange"
+      >
+        <option
+          v-for="zone in options"
+          :key="zone"
+          :value="zone"
+        >
+          {{ formatTimezoneLabel(zone) }}
+        </option>
+      </select>
+      <i
+        class="pi pi-chevron-down pointer-events-none absolute right-[var(--spacing-sm)] text-[length:inherit] leading-none text-[var(--text-muted)]"
+        aria-hidden="true"
+      />
+    </span>
+  </label>
+</template>
diff --git a/packages/webkit/src/components/inputs/calendar/calendar.vue b/packages/webkit/src/components/inputs/calendar/calendar.vue
index 6353596ec..a08299253 100644
--- a/packages/webkit/src/components/inputs/calendar/calendar.vue
+++ b/packages/webkit/src/components/inputs/calendar/calendar.vue
@@ -1,449 +1,547 @@
 <script setup lang="ts">
-  import { computed, ref, useAttrs, watch } from 'vue'
+  import {
+    computed,
+    onBeforeUnmount,
+    onMounted,
+    provide,
+    ref,
+    useAttrs,
+    useSlots,
+    watch
+  } from 'vue'
+
+  import { useFocusTrap } from '../../../composables/use-focus-trap'
+  import { usePlacement } from '../../../composables/use-placement'
+  import Button from '../../actions/button/button.vue'
+  import CalendarFields from './calendar-fields/calendar-fields.vue'
+  import CalendarGrid from './calendar-grid/calendar-grid.vue'
+  import CalendarPeriod from './calendar-period/calendar-period.vue'
+  import CalendarPreset from './calendar-preset/calendar-preset.vue'
+  import CalendarTimezone from './calendar-timezone/calendar-timezone.vue'
+  import { asRange, asSingle, formatValueLabel, startOfDay, withTime } from './format'
+  import {
+    CalendarInjectionKey,
+    type CalendarMode,
+    type CalendarMonth,
+    type CalendarPresetItem,
+    type CalendarRange,
+    type CalendarSize,
+    type CalendarValue
+  } from './injection-key'
 
   defineOptions({
     name: 'Calendar',
     inheritAttrs: false
   })
 
-  /** Selection mode for the calendar grid. */
-  export type CalendarMode = 'single' | 'range'
-
-  /** Range value emitted and accepted in range mode. */
-  export interface CalendarRange {
-    start: Date | null
-    end: Date | null
-  }
-
-  /** Visible month payload emitted on navigation. month is 0-indexed. */
-  export interface CalendarMonth {
-    year: number
-    month: number
-  }
-
-  /** v-model value: a Date (or null) in single mode, a range object in range mode. */
-  export type CalendarValue = Date | null | CalendarRange
-
   interface Props {
-    /** Selected value for v-model. A Date (or null) in single mode; a range object in range mode. */
+    /** Committed selection for v-model. A Date (or null) in single mode; a range in range mode. Only updated on Apply (or immediately when showApply is false). */
     modelValue?: CalendarValue
     /** Selection mode. Single picks one date; range picks a start and end date. */
     mode?: CalendarMode
+    /** Number of month grids rendered side-by-side; one shared prev/next pages the whole view by a month. */
+    numberOfMonths?: number
+    /** Size token; affects the trigger, day-cell hit-area, and typography. */
+    size?: CalendarSize
     /** Earliest selectable date; earlier days render disabled. */
     min?: Date
     /** Latest selectable date; later days render disabled. */
     max?: Date
-    /** Disables the whole grid and navigation, applying disabled tokens. */
+    /** Disables the trigger, grid, and all controls, applying disabled tokens. */
     disabled?: boolean
-    /** Shows the month/year label and previous/next month navigation. */
-    showHeader?: boolean
+    /** Controlled open state of the popover (v-model:open); omit for uncontrolled. */
+    open?: boolean
+    /** Trigger text shown when there is no selection. */
+    placeholder?: string
+    /** Data-driven shortcuts rendered in the presets rail; each is { label, value }. */
+    presets?: CalendarPresetItem[]
+    /** Shows Start/End time fields alongside the date fields. */
+    showTime?: boolean
+    /** Shows the timezone selector below the fields. */
+    showTimezone?: boolean
+    /** Selected IANA timezone for display formatting (v-model:timezone). Empty resolves to the local zone. */
+    timezone?: string
+    /** Timezone options for the selector; empty falls back to a curated list derived from Intl. */
+    timezones?: string[]
+    /** Lays the fields/apply column beside the calendar instead of below it. */
+    horizontal?: boolean
+    /** Shows a clear control on the trigger that empties the committed selection. */
+    clearable?: boolean
+    /** Stages edits in a draft and requires Apply to commit; when false, every edit commits immediately. */
+    showApply?: boolean
+    /** Enables the Select Period relative-time mode (relative-preset list + parsed text input). */
+    period?: boolean
+    /** Renders the trigger as a split control with a separate chevron affordance. */
+    split?: boolean
   }
 
   const props = withDefaults(defineProps<Props>(), {
     modelValue: null,
-    mode: 'single',
+    mode: 'range',
+    numberOfMonths: 1,
+    size: 'medium',
     min: undefined,
     max: undefined,
     disabled: false,
-    showHeader: true
+    open: undefined,
+    placeholder: 'Select a Date Range',
+    presets: () => [],
+    showTime: false,
+    showTimezone: false,
+    timezone: '',
+    timezones: () => [],
+    horizontal: false,
+    clearable: false,
+    showApply: true,
+    period: false,
+    split: false
   })
 
   const emit = defineEmits<{
     'update:modelValue': [value: CalendarValue]
+    'update:open': [value: boolean]
+    'update:timezone': [value: string]
     'month-change': [value: CalendarMonth]
+    apply: [value: CalendarValue]
+  }>()
+
+  defineSlots<{
+    trigger(props: { open: boolean; value: CalendarValue; displayValue: string }): unknown
+    presets(): unknown
+    footer(): unknown
   }>()
 
   const attrs = useAttrs()
+  const slots = useSlots()
 
   const testId = computed(() => (attrs['data-testid'] as string | undefined) ?? 'input-calendar')
 
-  const WEEKDAY_LABELS = ['S', 'M', 'T', 'W', 'T', 'F', 'S'] as const
-  const MS_PER_DAY = 86_400_000
+  const triggerRef = ref<globalThis.HTMLElement | null>(null)
+  const panelRef = ref<globalThis.HTMLElement | null>(null)
 
-  const startOfDay = (date: Date): Date =>
-    new Date(date.getFullYear(), date.getMonth(), date.getDate())
+  /* ---- open state (controlled / uncontrolled) ---- */
+  const internalOpen = ref(false)
+  const isOpen = computed(() => (props.open !== undefined ? props.open : internalOpen.value))
+  const isOpenRef = computed(() => isOpen.value)
 
-  const sameDay = (a: Date | null | undefined, b: Date | null | undefined): boolean => {
-    if (!a || !b) {
-      return false
+  const setOpen = (value: boolean) => {
+    if (value && props.disabled) {
+      return
     }
-
-    return (
-      a.getFullYear() === b.getFullYear() &&
-      a.getMonth() === b.getMonth() &&
-      a.getDate() === b.getDate()
-    )
-  }
-
-  const asRange = (value: CalendarValue): CalendarRange => {
-    if (value && !(value instanceof Date)) {
-      return value
+    if (props.open === undefined) {
+      internalOpen.value = value
     }
-
-    return { start: null, end: null }
+    emit('update:open', value)
   }
 
-  const asSingle = (value: CalendarValue): Date | null => (value instanceof Date ? value : null)
-
-  /** Anchor date that drives the visible month; seeded from the model value or today. */
-  const seedDate = (): Date => {
-    if (props.mode === 'range') {
-      const range = asRange(props.modelValue)
-
-      if (range.start) {
-        return range.start
-      }
-    } else {
-      const single = asSingle(props.modelValue)
-
-      if (single) {
-        return single
-      }
-    }
+  const toggleOpen = () => setOpen(!isOpen.value)
 
-    return new Date()
+  /* ---- timezone state (controlled / uncontrolled) ---- */
+  const internalTimezone = ref(props.timezone)
+  const timezoneValue = computed(() => props.timezone || internalTimezone.value)
+  const setTimezone = (value: string) => {
+    internalTimezone.value = value
+    emit('update:timezone', value)
   }
-
-  const viewDate = ref<Date>(startOfDay(seedDate()))
-
   watch(
-    () => props.modelValue,
-    () => {
-      viewDate.value = startOfDay(seedDate())
+    () => props.timezone,
+    (value) => {
+      if (value) {
+        internalTimezone.value = value
+      }
     }
   )
 
-  const viewYear = computed(() => viewDate.value.getFullYear())
-  const viewMonth = computed(() => viewDate.value.getMonth())
-
-  const monthLabel = computed(() =>
-    viewDate.value.toLocaleDateString('en-US', { month: 'long', year: 'numeric' })
-  )
-
-  const focusedTime = ref<number | null>(null)
-
-  const today = startOfDay(new Date())
-
-  const isBeforeMin = (date: Date): boolean => Boolean(props.min && date < startOfDay(props.min))
-  const isAfterMax = (date: Date): boolean => Boolean(props.max && date > startOfDay(props.max))
-  const isOutOfBounds = (date: Date): boolean => isBeforeMin(date) || isAfterMax(date)
-
-  /** Range-band classification used to render the connected range highlight. */
-  type CalendarDayBand = 'none' | 'single' | 'start' | 'middle' | 'end'
+  /* ---- draft (staged selection) ---- */
+  const emptyValue = (): CalendarValue =>
+    props.mode === 'range' ? { start: null, end: null } : null
 
-  interface CalendarDay {
-    date: Date
-    time: number
-    label: number
-    outside: boolean
-    disabled: boolean
-    today: boolean
-    selected: boolean
-    band: CalendarDayBand
-  }
-
-  /** Classifies a day for the range band: the lone selection (`single`), a range
-      endpoint (`start`/`end`), an in-between day (`middle`), or `none`. */
-  const dayBand = (date: Date): CalendarDayBand => {
-    if (props.mode !== 'range') {
-      return sameDay(date, asSingle(props.modelValue)) ? 'single' : 'none'
+  const cloneValue = (value: CalendarValue): CalendarValue => {
+    if (value instanceof Date) {
+      return new Date(value.getTime())
     }
-
-    const range = asRange(props.modelValue)
-    const time = startOfDay(date).getTime()
-    const start = range.start ? startOfDay(range.start).getTime() : null
-    const end = range.end ? startOfDay(range.end).getTime() : null
-
-    if (start !== null && end !== null) {
-      const lo = Math.min(start, end)
-      const hi = Math.max(start, end)
-
-      if (lo === hi) {
-        return time === lo ? 'single' : 'none'
-      }
-      if (time === lo) {
-        return 'start'
+    if (value && typeof value === 'object') {
+      return {
+        start: value.start ? new Date(value.start.getTime()) : null,
+        end: value.end ? new Date(value.end.getTime()) : null
       }
-      if (time === hi) {
-        return 'end'
-      }
-
-      return time > lo && time < hi ? 'middle' : 'none'
     }
+    return emptyValue()
+  }
 
-    if ((start !== null && time === start) || (end !== null && time === end)) {
-      return 'single'
-    }
+  const draft = ref<CalendarValue>(cloneValue(props.modelValue))
+  const draftRef = computed(() => draft.value)
 
-    return 'none'
+  const resetDraft = () => {
+    draft.value = cloneValue(props.modelValue)
   }
 
-  /** 6 rows of 7 days, leading/trailing adjacent-month cells, week starting Sunday. */
-  const weeks = computed<CalendarDay[][]>(() => {
-    const firstOfMonth = new Date(viewYear.value, viewMonth.value, 1)
-    const gridStart = new Date(viewYear.value, viewMonth.value, 1 - firstOfMonth.getDay())
-    const rows: CalendarDay[][] = []
-
-    for (let row = 0; row < 6; row += 1) {
-      const cells: CalendarDay[] = []
-
-      for (let col = 0; col < 7; col += 1) {
-        const date = new Date(
-          gridStart.getFullYear(),
-          gridStart.getMonth(),
-          gridStart.getDate() + row * 7 + col
-        )
-        const outside = date.getMonth() !== viewMonth.value
-
-        const band = dayBand(date)
-
-        cells.push({
-          date,
-          time: date.getTime(),
-          label: date.getDate(),
-          outside,
-          disabled: props.disabled || isOutOfBounds(date),
-          today: sameDay(date, today),
-          selected: band === 'single' || band === 'start' || band === 'end',
-          band
-        })
-      }
-
-      rows.push(cells)
+  watch(isOpen, (open) => {
+    if (open) {
+      resetDraft()
     }
-
-    return rows
   })
 
-  /** Day that owns the roving tabindex: tracked focus, else selection, else today, else first enabled. */
-  const activeTime = computed<number | null>(() => {
-    const flat: CalendarDay[] = weeks.value.flat()
-
-    if (focusedTime.value !== null && flat.some((day) => day.time === focusedTime.value)) {
-      return focusedTime.value
+  const isComplete = (value: CalendarValue): boolean => {
+    if (props.mode === 'range') {
+      const range = asRange(value)
+      return Boolean(range.start && range.end)
     }
+    return asSingle(value) !== null
+  }
 
-    const selected = flat.find((day) => day.selected && !day.disabled)
-
-    if (selected) {
-      return selected.time
+  const commitIfImmediate = () => {
+    if (props.showApply) {
+      return
     }
-
-    const current = flat.find((day) => day.today && !day.outside && !day.disabled)
-
-    if (current) {
-      return current.time
+    emit('update:modelValue', cloneValue(draft.value))
+    if (isComplete(draft.value)) {
+      setOpen(false)
     }
-
-    const firstEnabled = flat.find((day) => !day.outside && !day.disabled)
-
-    return firstEnabled ? firstEnabled.time : null
-  })
-
-  const goToMonth = (year: number, month: number) => {
-    viewDate.value = new Date(year, month, 1)
-    emit('month-change', { year: viewDate.value.getFullYear(), month: viewDate.value.getMonth() })
   }
 
-  const goToPreviousMonth = () => {
+  const selectDay = (date: Date) => {
     if (props.disabled) {
       return
     }
-
-    goToMonth(viewYear.value, viewMonth.value - 1)
+    if (props.mode === 'range') {
+      const range = asRange(draft.value)
+      if (!range.start || range.end) {
+        draft.value = { start: withTime(date, null, false), end: null }
+      } else if (startOfDay(date) < startOfDay(range.start)) {
+        draft.value = {
+          start: withTime(date, null, false),
+          end: withTime(range.start, range.start, true)
+        }
+      } else {
+        draft.value = { start: range.start, end: withTime(date, null, true) }
+      }
+    } else {
+      draft.value = withTime(date, asSingle(draft.value), false)
+    }
+    commitIfImmediate()
   }
 
-  const goToNextMonth = () => {
+  const selectValue = (value: Date | CalendarRange) => {
     if (props.disabled) {
       return
     }
-
-    goToMonth(viewYear.value, viewMonth.value + 1)
+    if (props.mode === 'range') {
+      const range = value instanceof Date ? { start: value, end: value } : value
+      draft.value = {
+        start: range.start ? new Date(range.start.getTime()) : null,
+        end: range.end ? new Date(range.end.getTime()) : null
+      }
+    } else {
+      const date = value instanceof Date ? value : (value.start ?? value.end ?? null)
+      draft.value = date ? new Date(date.getTime()) : null
+    }
+    // Period selections are complete ranges — commit and close immediately.
+    if (props.period) {
+      emit('update:modelValue', cloneValue(draft.value))
+      emit('apply', cloneValue(draft.value))
+      setOpen(false)
+      return
+    }
+    commitIfImmediate()
   }
 
-  const selectDay = (day: CalendarDay) => {
-    if (day.disabled) {
+  const setEndpoint = (which: 'start' | 'end', date: Date | null) => {
+    if (props.disabled) {
       return
     }
+    if (props.mode === 'range') {
+      const range = asRange(draft.value)
+      draft.value =
+        which === 'start' ? { start: date, end: range.end } : { start: range.start, end: date }
+    } else {
+      draft.value = date
+    }
+    commitIfImmediate()
+  }
 
-    focusedTime.value = day.time
-
-    if (day.outside) {
-      viewDate.value = new Date(day.date.getFullYear(), day.date.getMonth(), 1)
-      emit('month-change', { year: day.date.getFullYear(), month: day.date.getMonth() })
+  const clearDraft = () => {
+    if (props.disabled) {
+      return
     }
+    draft.value = emptyValue()
+    commitIfImmediate()
+  }
 
-    if (props.mode === 'range') {
-      const range = asRange(props.modelValue)
+  const changeMonth = (month: CalendarMonth) => {
+    emit('month-change', month)
+  }
 
-      if (!range.start || range.end) {
-        emit('update:modelValue', { start: day.date, end: null })
-        return
-      }
+  const hasSelection = computed<boolean>(
+    () => isComplete(draft.value) || hasAnyEndpoint(draft.value)
+  )
 
-      if (day.date < range.start) {
-        emit('update:modelValue', { start: day.date, end: range.start })
-        return
-      }
+  function hasAnyEndpoint(value: CalendarValue): boolean {
+    if (props.mode === 'range') {
+      const range = asRange(value)
+      return Boolean(range.start || range.end)
+    }
+    return asSingle(value) !== null
+  }
 
-      emit('update:modelValue', { start: range.start, end: day.date })
+  const applySelection = () => {
+    if (props.disabled) {
       return
     }
+    emit('update:modelValue', cloneValue(draft.value))
+    emit('apply', cloneValue(draft.value))
+    setOpen(false)
+  }
 
-    emit('update:modelValue', day.date)
+  const clearCommitted = () => {
+    if (props.disabled) {
+      return
+    }
+    emit('update:modelValue', emptyValue())
+    draft.value = emptyValue()
   }
 
-  const moveFocus = (fromTime: number, deltaDays: number) => {
-    const next = new Date(fromTime + deltaDays * MS_PER_DAY)
-    const normalized = startOfDay(next)
-    focusedTime.value = normalized.getTime()
+  /* ---- trigger display ---- */
+  const displayValue = computed(() =>
+    formatValueLabel(props.modelValue, props.mode, timezoneValue.value)
+  )
+  const hasCommitted = computed(() => displayValue.value !== '')
+  const triggerIcon = computed(() => (props.period ? 'pi pi-clock' : 'pi pi-calendar'))
+  const triggerText = computed(
+    () => displayValue.value || (props.period ? 'Period' : props.placeholder)
+  )
+
+  const hasPresets = computed(() => props.presets.length > 0 || Boolean(slots['presets']))
+
+  /* ---- positioning + focus + dismissal ---- */
+  const { resolvedPlacement, panelStyle } = usePlacement({
+    triggerRef,
+    panelRef,
+    isOpen: isOpenRef,
+    placement: 'bottom-start',
+    offset: 6,
+    autoPlacements: ['bottom-start', 'bottom-end', 'top-start', 'top-end']
+  })
+
+  useFocusTrap(panelRef, isOpenRef)
 
-    if (normalized.getMonth() !== viewMonth.value || normalized.getFullYear() !== viewYear.value) {
-      goToMonth(normalized.getFullYear(), normalized.getMonth())
+  const onDocumentMousedown = (event: globalThis.MouseEvent) => {
+    if (!isOpen.value) {
+      return
     }
+    const target = event.target as globalThis.Node | null
+    if (!target) {
+      return
+    }
+    if (triggerRef.value?.contains(target)) {
+      return
+    }
+    if (panelRef.value?.contains(target)) {
+      return
+    }
+    setOpen(false)
   }
 
-  const onDayKeydown = (event: globalThis.KeyboardEvent, day: CalendarDay) => {
-    switch (event.key) {
-      case 'ArrowLeft':
-        event.preventDefault()
-        moveFocus(day.time, -1)
-        break
-      case 'ArrowRight':
-        event.preventDefault()
-        moveFocus(day.time, 1)
-        break
-      case 'ArrowUp':
-        event.preventDefault()
-        moveFocus(day.time, -7)
-        break
-      case 'ArrowDown':
-        event.preventDefault()
-        moveFocus(day.time, 7)
-        break
-      case 'PageUp':
-        event.preventDefault()
-        goToPreviousMonth()
-        break
-      case 'PageDown':
-        event.preventDefault()
-        goToNextMonth()
-        break
-      case 'Enter':
-      case ' ':
-        event.preventDefault()
-        selectDay(day)
-        break
-      default:
-        break
+  const onPanelKeydown = (event: globalThis.KeyboardEvent) => {
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      setOpen(false)
+      triggerRef.value?.querySelector<globalThis.HTMLElement>('button')?.focus()
     }
   }
+
+  onMounted(() => {
+    globalThis.document?.addEventListener('mousedown', onDocumentMousedown)
+  })
+
+  onBeforeUnmount(() => {
+    globalThis.document?.removeEventListener('mousedown', onDocumentMousedown)
+  })
+
+  provide(CalendarInjectionKey, {
+    testId: testId.value,
+    mode: computed(() => props.mode),
+    size: computed(() => props.size),
+    disabled: computed(() => props.disabled),
+    numberOfMonths: computed(() => props.numberOfMonths),
+    min: computed(() => props.min),
+    max: computed(() => props.max),
+    showTime: computed(() => props.showTime),
+    horizontal: computed(() => props.horizontal),
+    draft: draftRef,
+    hasSelection,
+    timezone: timezoneValue,
+    timezones: computed(() => props.timezones),
+    selectDay,
+    selectValue,
+    setEndpoint,
+    clear: clearDraft,
+    setTimezone,
+    changeMonth
+  })
 </script>
 
 <template>
   <div
     v-bind="$attrs"
     :data-testid="testId"
+    :data-state="isOpen ? 'open' : 'closed'"
+    :data-size="size"
     :data-disabled="disabled || null"
-    class="inline-flex max-w-full flex-col items-start overflow-hidden rounded-[var(--shape-button)] border border-[var(--border-default)] bg-[var(--bg-surface-raised)] data-[disabled]:opacity-60"
+    class="inline-flex"
   >
-    <div
-      v-if="showHeader"
-      class="flex w-full items-center justify-between py-[var(--spacing-xs)] pl-[var(--spacing-md)] pr-[var(--spacing-sm)]"
-      :data-testid="`${testId}__header`"
-    >
-      <span
-        class="text-body-sm text-[var(--text-default)]"
-        :data-testid="`${testId}__label`"
-      >
-        {{ monthLabel }}
-      </span>
-
-      <div class="flex items-center gap-[var(--spacing-xxs)]">
-        <button
-          type="button"
-          :disabled="disabled"
-          aria-label="Previous month"
-          :data-testid="`${testId}__prev`"
-          class="inline-flex size-7 items-center justify-center rounded-[var(--shape-elements)] text-[var(--text-default)] transition-colors duration-150 ease-out hover:bg-[var(--bg-hover)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-canvas)] disabled:cursor-not-allowed disabled:text-[var(--text-disabled)] motion-reduce:transition-none"
-          @click="goToPreviousMonth"
-        >
-          <i
-            class="pi pi-chevron-left text-[length:inherit] leading-none"
-            aria-hidden="true"
-          />
-        </button>
-
-        <button
-          type="button"
-          :disabled="disabled"
-          aria-label="Next month"
-          :data-testid="`${testId}__next`"
-          class="inline-flex size-7 items-center justify-center rounded-[var(--shape-elements)] text-[var(--text-default)] transition-colors duration-150 ease-out hover:bg-[var(--bg-hover)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-canvas)] disabled:cursor-not-allowed disabled:text-[var(--text-disabled)] motion-reduce:transition-none"
-          @click="goToNextMonth"
-        >
-          <i
-            class="pi pi-chevron-right text-[length:inherit] leading-none"
-            aria-hidden="true"
-          />
-        </button>
-      </div>
-    </div>
-
-    <div
-      class="flex flex-col items-start gap-[var(--spacing-md)] p-[var(--spacing-sm)]"
-      role="grid"
-      :aria-label="monthLabel"
-      :data-testid="`${testId}__grid`"
+    <span
+      ref="triggerRef"
+      class="inline-flex max-w-full"
     >
-      <div
-        role="row"
-        class="flex items-start"
+      <slot
+        name="trigger"
+        :open="isOpen"
+        :value="modelValue"
+        :display-value="displayValue"
       >
         <span
-          v-for="(weekday, index) in WEEKDAY_LABELS"
-          :key="`weekday-${index}`"
-          role="columnheader"
-          class="text-label-sm flex w-9 items-start justify-center text-[var(--text-muted)]"
+          :data-size="size"
+          :data-state="isOpen ? 'open' : 'closed'"
+          :data-disabled="disabled || null"
+          class="inline-flex max-w-full items-stretch overflow-hidden rounded-[var(--shape-elements)] border border-[var(--border-default)] bg-[var(--bg-surface)] data-[disabled]:opacity-60"
         >
-          {{ weekday }}
+          <button
+            type="button"
+            :disabled="disabled"
+            :data-size="size"
+            :data-empty="!hasCommitted || null"
+            :data-testid="`${testId}__trigger`"
+            aria-haspopup="dialog"
+            :aria-expanded="isOpen"
+            class="text-body-sm inline-flex min-w-0 flex-1 items-center gap-[var(--spacing-xs)] px-[var(--spacing-sm)] text-[var(--text-default)] transition-colors duration-150 ease-out hover:bg-[var(--bg-hover)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-canvas)] disabled:cursor-not-allowed disabled:text-[var(--text-disabled)] data-[size=small]:h-7 data-[size=medium]:h-8 data-[size=large]:h-10 data-[empty]:text-[var(--text-muted)] motion-reduce:transition-none"
+            @click="toggleOpen"
+          >
+            <i
+              :class="triggerIcon"
+              class="shrink-0 text-[length:inherit] leading-none text-[var(--text-muted)]"
+              aria-hidden="true"
+            />
+            <span class="min-w-0 flex-1 truncate text-left">{{ triggerText }}</span>
+            <i
+              v-if="!split && !(clearable && hasCommitted)"
+              class="pi pi-chevron-down shrink-0 text-[length:inherit] leading-none text-[var(--text-muted)]"
+              aria-hidden="true"
+            />
+          </button>
+
+          <button
+            v-if="clearable && hasCommitted"
+            type="button"
+            :disabled="disabled"
+            aria-label="Clear selection"
+            :data-testid="`${testId}__clear-trigger`"
+            class="inline-flex shrink-0 items-center justify-center px-[var(--spacing-xs)] text-[var(--text-muted)] transition-colors duration-150 ease-out hover:bg-[var(--bg-hover)] hover:text-[var(--text-default)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] motion-reduce:transition-none"
+            @click="clearCommitted"
+          >
+            <i
+              class="pi pi-times text-[length:inherit] leading-none"
+              aria-hidden="true"
+            />
+          </button>
+
+          <button
+            v-if="split"
+            type="button"
+            :disabled="disabled"
+            aria-label="Open calendar"
+            :aria-expanded="isOpen"
+            :data-testid="`${testId}__split`"
+            class="inline-flex shrink-0 items-center justify-center border-l border-[var(--border-default)] px-[var(--spacing-xs)] text-[var(--text-muted)] transition-colors duration-150 ease-out hover:bg-[var(--bg-hover)] hover:text-[var(--text-default)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] motion-reduce:transition-none"
+            @click="toggleOpen"
+          >
+            <i
+              class="pi pi-chevron-down text-[length:inherit] leading-none"
+              aria-hidden="true"
+            />
+          </button>
         </span>
-      </div>
+      </slot>
+    </span>
 
-      <div class="flex flex-col items-start gap-[var(--spacing-xxs)]">
+    <Teleport to="body">
+      <Transition
+        enter-active-class="animate-popup-scale-in motion-reduce:animate-none"
+        leave-active-class="animate-popup-scale-out motion-reduce:animate-none"
+      >
         <div
-          v-for="(week, weekIndex) in weeks"
-          :key="`week-${weekIndex}`"
-          role="row"
-          class="flex items-start"
+          v-if="isOpen"
+          ref="panelRef"
+          role="dialog"
+          aria-label="Choose date"
+          :data-testid="`${testId}__popover`"
+          :data-state="isOpen ? 'open' : 'closed'"
+          :data-placement="resolvedPlacement"
+          :style="panelStyle"
+          class="flex flex-col overflow-hidden rounded-[var(--shape-card)] border border-[var(--border-default)] bg-[var(--bg-surface-raised)] shadow-[var(--shadow-sm)] outline-none [transform-origin:var(--popup-origin,top_left)]"
+          @keydown="onPanelKeydown"
         >
-          <div
-            v-for="day in week"
-            :key="day.time"
-            role="gridcell"
-            :aria-selected="day.selected || undefined"
-            :aria-current="day.today ? 'date' : undefined"
-            class="size-9"
-          >
-            <button
-              type="button"
-              :disabled="day.disabled"
-              :data-band="day.band"
-              :data-selected="day.selected || null"
-              :data-today="day.today || null"
-              :data-outside="day.outside || null"
-              :data-disabled="day.disabled || null"
-              :data-testid="`${testId}__day`"
-              :tabindex="day.time === activeTime ? 0 : -1"
-              class="text-body-sm flex size-full items-center justify-center text-[var(--text-default)] transition-colors duration-150 ease-out focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-surface-raised)] data-[band=none]:rounded-[var(--shape-elements)] data-[band=none]:hover:bg-[var(--bg-hover)] data-[band=single]:rounded-[var(--shape-elements)] data-[band=single]:bg-[var(--secondary)] data-[band=single]:text-[var(--secondary-contrast)] data-[band=start]:rounded-l-[var(--shape-elements)] data-[band=start]:bg-[var(--secondary)] data-[band=start]:text-[var(--secondary-contrast)] data-[band=end]:rounded-r-[var(--shape-elements)] data-[band=end]:bg-[var(--secondary)] data-[band=end]:text-[var(--secondary-contrast)] data-[band=middle]:bg-[var(--bg-mask)] data-[outside]:text-[var(--text-disabled)] data-[disabled]:cursor-not-allowed data-[disabled]:text-[var(--text-disabled)] motion-reduce:transition-none"
-              @click="selectDay(day)"
-              @keydown="onDayKeydown($event, day)"
+          <div class="flex items-stretch">
+            <div
+              v-if="hasPresets && !period"
+              :data-testid="`${testId}__presets`"
+              class="flex min-w-[var(--container-4xs)] flex-col gap-[var(--spacing-xxs)] border-r border-[var(--border-default)] p-[var(--spacing-sm)]"
+            >
+              <slot name="presets">
+                <CalendarPreset
+                  v-for="preset in presets"
+                  :key="preset.label"
+                  :value="preset.value"
+                >
+                  {{ preset.label }}
+                </CalendarPreset>
+              </slot>
+            </div>
+
+            <div
+              class="flex gap-[var(--spacing-md)] p-[var(--spacing-sm)]"
+              :data-horizontal="horizontal || null"
+              :class="horizontal ? 'flex-row items-start' : 'flex-col items-stretch'"
             >
-              {{ day.label }}
-            </button>
+              <CalendarPeriod v-if="period" />
+              <CalendarGrid v-else />
+
+              <div
+                v-if="!period"
+                class="flex flex-col gap-[var(--spacing-sm)]"
+                :class="
+                  horizontal
+                    ? 'min-w-[var(--container-3xs)] border-l border-[var(--border-default)] pl-[var(--spacing-md)]'
+                    : 'border-t border-[var(--border-default)] pt-[var(--spacing-sm)]'
+                "
+              >
+                <CalendarFields />
+
+                <span
+                  v-if="$slots['footer']"
+                  class="inline-flex items-center gap-[var(--spacing-xs)]"
+                >
+                  <slot name="footer" />
+                </span>
+
+                <Button
+                  v-if="showApply"
+                  label="Apply Range"
+                  kind="outlined"
+                  :size="size"
+                  :disabled="disabled"
+                  icon="pi pi-arrow-down-left"
+                  class="w-full justify-center"
+                  :data-testid="`${testId}__apply`"
+                  @click="applySelection"
+                />
+
+                <CalendarTimezone v-if="showTimezone" />
+              </div>
+            </div>
           </div>
         </div>
-      </div>
-    </div>
+      </Transition>
+    </Teleport>
   </div>
 </template>
diff --git a/packages/webkit/src/components/inputs/calendar/format.ts b/packages/webkit/src/components/inputs/calendar/format.ts
new file mode 100644
index 000000000..665d0c843
--- /dev/null
+++ b/packages/webkit/src/components/inputs/calendar/format.ts
@@ -0,0 +1,171 @@
+import type { CalendarMode, CalendarRange, CalendarValue } from './injection-key'
+
+/** Midnight of the given date (local). */
+export const startOfDay = (date: Date): Date =>
+  new Date(date.getFullYear(), date.getMonth(), date.getDate())
+
+/** Last representable minute of the given date (local), used as a range end default. */
+export const endOfDay = (date: Date): Date =>
+  new Date(date.getFullYear(), date.getMonth(), date.getDate(), 23, 59)
+
+/** Same calendar day (ignores time). */
+export const sameDay = (a: Date | null | undefined, b: Date | null | undefined): boolean => {
+  if (!a || !b) {
+    return false
+  }
+
+  return (
+    a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate()
+  )
+}
+
+/** Narrow a model value to a range object (empty range when it is a Date or null). */
+export const asRange = (value: CalendarValue): CalendarRange => {
+  if (value && !(value instanceof Date)) {
+    return value
+  }
+
+  return { start: null, end: null }
+}
+
+/** Narrow a model value to a single Date (null when it is a range or null). */
+export const asSingle = (value: CalendarValue): Date | null =>
+  value instanceof Date ? value : null
+
+/** Merge a day (Y/M/D) with a source time, defaulting to 00:00 (start) or 23:59 (end). */
+export const withTime = (date: Date, source: Date | null, isEnd: boolean): Date => {
+  const hours = source ? source.getHours() : isEnd ? 23 : 0
+  const minutes = source ? source.getMinutes() : isEnd ? 59 : 0
+
+  return new Date(date.getFullYear(), date.getMonth(), date.getDate(), hours, minutes)
+}
+
+const tzOption = (timezone: string): string | undefined => timezone || undefined
+
+/** `Jun 30, 2026`. */
+export const formatDate = (date: Date, timezone = ''): string =>
+  new Intl.DateTimeFormat('en-US', {
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+    timeZone: tzOption(timezone)
+  }).format(date)
+
+/** `09:00 AM` (12h). */
+export const formatTime = (date: Date, timezone = ''): string =>
+  new Intl.DateTimeFormat('en-US', {
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: true,
+    timeZone: tzOption(timezone)
+  }).format(date)
+
+const monthDay = (date: Date, timezone = ''): string =>
+  new Intl.DateTimeFormat('en-US', {
+    month: 'short',
+    day: 'numeric',
+    timeZone: tzOption(timezone)
+  }).format(date)
+
+/**
+ * Trigger label: a single date, a compact range (`Jun 9 – 26`, `Jun 9 – Jul 2`,
+ * `Dec 30, 2026 – Jan 2, 2027`), or `''` when there is no selection.
+ */
+export const formatValueLabel = (
+  value: CalendarValue,
+  mode: CalendarMode,
+  timezone = ''
+): string => {
+  if (mode !== 'range') {
+    const single = asSingle(value)
+    return single ? formatDate(single, timezone) : ''
+  }
+
+  const { start, end } = asRange(value)
+
+  if (!start && !end) {
+    return ''
+  }
+  if (start && !end) {
+    return `${formatDate(start, timezone)} –`
+  }
+  if (!start && end) {
+    return `– ${formatDate(end, timezone)}`
+  }
+
+  const s = start as Date
+  const e = end as Date
+  const sameYear = s.getFullYear() === e.getFullYear()
+  const sameMonth = sameYear && s.getMonth() === e.getMonth()
+
+  if (sameMonth) {
+    return `${monthDay(s, timezone)} – ${e.getDate()}`
+  }
+  if (sameYear) {
+    return `${monthDay(s, timezone)} – ${monthDay(e, timezone)}`
+  }
+
+  return `${formatDate(s, timezone)} – ${formatDate(e, timezone)}`
+}
+
+/** The host's local IANA timezone (e.g. `America/Sao_Paulo`). */
+export const localTimezone = (): string => {
+  try {
+    return new Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC'
+  } catch {
+    return 'UTC'
+  }
+}
+
+const cityName = (timezone: string): string =>
+  timezone.split('/').pop()?.replace(/_/g, ' ') ?? timezone
+
+/** `UTC -05:00 (EST)` — the zone's UTC offset plus its abbreviation when alphabetic. */
+const offsetAndAbbr = (timezone: string): string => {
+  const reference = new Date()
+  const zone = tzOption(timezone)
+  const offsetRaw =
+    new Intl.DateTimeFormat('en-US', { timeZone: zone, timeZoneName: 'longOffset' })
+      .formatToParts(reference)
+      .find((part) => part.type === 'timeZoneName')?.value ?? ''
+  const offset = offsetRaw.replace('GMT', 'UTC ').trim() || 'UTC'
+  const abbr =
+    new Intl.DateTimeFormat('en-US', { timeZone: zone, timeZoneName: 'short' })
+      .formatToParts(reference)
+      .find((part) => part.type === 'timeZoneName')?.value ?? ''
+  const hasAbbr = /[a-z]/i.test(abbr) && !abbr.startsWith('GMT') && !abbr.startsWith('UTC')
+
+  return hasAbbr ? `${offset} (${abbr})` : offset
+}
+
+/** `Local (UTC -05:00 (EST))` for the local zone, otherwise `City (UTC ±hh:mm (ABBR))`. */
+export const formatTimezoneLabel = (timezone: string): string => {
+  const resolved = timezone || localTimezone()
+  const prefix = resolved === localTimezone() ? 'Local' : cityName(resolved)
+
+  return `${prefix} (${offsetAndAbbr(resolved)})`
+}
+
+/** A curated timezone list (local first), derived from `Intl` when available. */
+export const defaultTimezones = (): string[] => {
+  const local = localTimezone()
+  const supported = (Intl as unknown as { supportedValuesOf?: (key: string) => string[] })
+    .supportedValuesOf
+
+  const base = typeof supported === 'function' ? supported('timeZone') : []
+  const curated = [
+    local,
+    'UTC',
+    'America/New_York',
+    'America/Sao_Paulo',
+    'Europe/London',
+    'Europe/Paris',
+    'Asia/Tokyo'
+  ]
+
+  const list = base.length > 0 ? [local, ...base] : curated
+
+  return [...new Set(list)]
+}
diff --git a/packages/webkit/src/components/inputs/calendar/index.ts b/packages/webkit/src/components/inputs/calendar/index.ts
new file mode 100644
index 000000000..ea3eaebbd
--- /dev/null
+++ b/packages/webkit/src/components/inputs/calendar/index.ts
@@ -0,0 +1,34 @@
+/**
+ * Compound API — each sub-component stays available as its own import
+ * (`@aziontech/webkit/calendar-preset`, `@aziontech/webkit/calendar-clear`) and is
+ * also attached to the root for dot-notation usage: `<Calendar.Preset>`, `<Calendar.Clear>`.
+ *
+ * This is a `.ts` file so vue-tsc generates the adjacent `index.d.ts`, giving
+ * `<Calendar.Preset>` full type-checking. `Object.assign` keeps one source of truth;
+ * the explicit `CompoundCalendar` annotation lets declaration emit reference the
+ * sub-component types instead of expanding the root's private `Props`.
+ * See `.claude/rules/compound-api.md`.
+ */
+import Calendar from './calendar.vue'
+import CalendarClear from './calendar-clear/calendar-clear.vue'
+import CalendarPreset from './calendar-preset/calendar-preset.vue'
+
+type CompoundCalendar = typeof Calendar & {
+  Preset: typeof CalendarPreset
+  Clear: typeof CalendarClear
+}
+
+const CalendarRoot = Object.assign(Calendar, {
+  Preset: CalendarPreset,
+  Clear: CalendarClear
+}) as CompoundCalendar
+
+export type {
+  CalendarMode,
+  CalendarMonth,
+  CalendarRange,
+  CalendarSize,
+  CalendarValue
+} from './injection-key'
+
+export default CalendarRoot
diff --git a/packages/webkit/src/components/inputs/calendar/injection-key.ts b/packages/webkit/src/components/inputs/calendar/injection-key.ts
new file mode 100644
index 000000000..4e8d656f6
--- /dev/null
+++ b/packages/webkit/src/components/inputs/calendar/injection-key.ts
@@ -0,0 +1,75 @@
+import type { ComputedRef, InjectionKey } from 'vue'
+
+/** Selection mode for the calendar grid. */
+export type CalendarMode = 'single' | 'range'
+
+/** Size token; affects the trigger, day-cell hit-area, and typography. */
+export type CalendarSize = 'small' | 'medium' | 'large'
+
+/** Range value emitted and accepted in range mode. */
+export interface CalendarRange {
+  start: Date | null
+  end: Date | null
+}
+
+/** Visible month payload emitted on navigation. month is 0-indexed. */
+export interface CalendarMonth {
+  year: number
+  month: number
+}
+
+/** v-model value: a Date (or null) in single mode, a range object in range mode. */
+export type CalendarValue = Date | null | CalendarRange
+
+/** A data-driven preset shortcut rendered in the presets rail. */
+export interface CalendarPresetItem {
+  label: string
+  value: Date | CalendarRange
+}
+
+/**
+ * Shared state the root picker provides. Sub-components inject it and drive the
+ * popover's DRAFT selection (staged until Apply) so the consumer wires nothing.
+ */
+export interface CalendarContext {
+  /** Root data-testid; sub-components derive BEM-suffixed ids from it. */
+  testId: string
+  /** Selection mode. */
+  mode: ComputedRef<CalendarMode>
+  /** Active size token. */
+  size: ComputedRef<CalendarSize>
+  /** Whether the whole picker is disabled. */
+  disabled: ComputedRef<boolean>
+  /** Number of month grids rendered side-by-side. */
+  numberOfMonths: ComputedRef<number>
+  /** Earliest selectable date (or undefined). */
+  min: ComputedRef<Date | undefined>
+  /** Latest selectable date (or undefined). */
+  max: ComputedRef<Date | undefined>
+  /** Whether Start/End time fields are shown. */
+  showTime: ComputedRef<boolean>
+  /** Whether the popover uses the horizontal (side-by-side) layout. */
+  horizontal: ComputedRef<boolean>
+  /** Staged (pre-Apply) selection the popover edits. */
+  draft: ComputedRef<CalendarValue>
+  /** Whether the draft has any selection (drives the clear control). */
+  hasSelection: ComputedRef<boolean>
+  /** Selected IANA timezone (display only). */
+  timezone: ComputedRef<string>
+  /** Timezone options for the selector. */
+  timezones: ComputedRef<string[]>
+  /** Grid day click — range-building / single select on the draft. */
+  selectDay: (date: Date) => void
+  /** Apply a full value (preset / period) to the draft. */
+  selectValue: (value: Date | CalendarRange) => void
+  /** Set a range endpoint (or the single value) from the date/time fields. */
+  setEndpoint: (which: 'start' | 'end', date: Date | null) => void
+  /** Clear the draft selection. */
+  clear: () => void
+  /** Update the selected timezone. */
+  setTimezone: (timezone: string) => void
+  /** Notify the root that the first visible month changed. */
+  changeMonth: (month: CalendarMonth) => void
+}
+
+export const CalendarInjectionKey: InjectionKey<CalendarContext> = Symbol('CalendarContext')
diff --git a/packages/webkit/src/components/inputs/calendar/parse-period.ts b/packages/webkit/src/components/inputs/calendar/parse-period.ts
new file mode 100644
index 000000000..cfa65b88b
--- /dev/null
+++ b/packages/webkit/src/components/inputs/calendar/parse-period.ts
@@ -0,0 +1,215 @@
+import { endOfDay, startOfDay } from './format'
+import type { CalendarRange } from './injection-key'
+
+/**
+ * Parses a relative or fixed period expression into a `{ start, end }` range, or
+ * `null` when it cannot be understood. Pure native-`Date` math, no date library.
+ *
+ * Accepted forms (case-insensitive):
+ *   - relative spans: `45m`, `12 hours`, `10d`, `2 weeks`, `3 months`, `1y` → [now − span, now]
+ *   - keywords: `today`, `yesterday`, `last week`, `last month`, `last year`, `this month`
+ *   - fixed single dates: `1/1`, `1/1/2026`, `Jan 1`, `Jan 1, 2026` → that whole day
+ *   - fixed ranges: `1/1 - 1/2`, `Jan 1 - Jan 2` (separators `-`, `–`, `to`)
+ */
+export function parsePeriod(input: string, now: Date = new Date()): CalendarRange | null {
+  const text = input.trim().toLowerCase()
+
+  if (!text) {
+    return null
+  }
+
+  const keyword = parseKeyword(text, now)
+  if (keyword) {
+    return keyword
+  }
+
+  const relative = parseRelative(text, now)
+  if (relative) {
+    return relative
+  }
+
+  const rangeParts = splitRange(text)
+  if (rangeParts) {
+    const start = parseFixedDate(rangeParts[0], now)
+    const end = parseFixedDate(rangeParts[1], now)
+    if (start && end) {
+      return { start: startOfDay(start), end: endOfDay(end) }
+    }
+    return null
+  }
+
+  const single = parseFixedDate(text, now)
+  if (single) {
+    return { start: startOfDay(single), end: endOfDay(single) }
+  }
+
+  return null
+}
+
+const MS_PER_MINUTE = 60_000
+const MS_PER_HOUR = 3_600_000
+const MS_PER_DAY = 86_400_000
+
+const UNIT_MS: Record<string, number> = {
+  m: MS_PER_MINUTE,
+  min: MS_PER_MINUTE,
+  mins: MS_PER_MINUTE,
+  minute: MS_PER_MINUTE,
+  minutes: MS_PER_MINUTE,
+  h: MS_PER_HOUR,
+  hr: MS_PER_HOUR,
+  hrs: MS_PER_HOUR,
+  hour: MS_PER_HOUR,
+  hours: MS_PER_HOUR,
+  d: MS_PER_DAY,
+  day: MS_PER_DAY,
+  days: MS_PER_DAY,
+  w: MS_PER_DAY * 7,
+  wk: MS_PER_DAY * 7,
+  week: MS_PER_DAY * 7,
+  weeks: MS_PER_DAY * 7
+}
+
+const CALENDAR_UNITS: Record<string, 'month' | 'year'> = {
+  mo: 'month',
+  month: 'month',
+  months: 'month',
+  y: 'year',
+  yr: 'year',
+  year: 'year',
+  years: 'year'
+}
+
+function parseRelative(text: string, now: Date): CalendarRange | null {
+  const match = text.match(/^(\d+)\s*([a-z]+)$/)
+  if (!match) {
+    return null
+  }
+
+  const amount = Number(match[1])
+  const unit = match[2]
+
+  if (unit in UNIT_MS) {
+    return { start: new Date(now.getTime() - amount * UNIT_MS[unit]), end: new Date(now.getTime()) }
+  }
+
+  if (unit in CALENDAR_UNITS) {
+    const start = new Date(now)
+    if (CALENDAR_UNITS[unit] === 'month') {
+      start.setMonth(start.getMonth() - amount)
+    } else {
+      start.setFullYear(start.getFullYear() - amount)
+    }
+    return { start, end: new Date(now.getTime()) }
+  }
+
+  return null
+}
+
+function parseKeyword(text: string, now: Date): CalendarRange | null {
+  switch (text) {
+    case 'today':
+      return { start: startOfDay(now), end: endOfDay(now) }
+    case 'yesterday': {
+      const y = new Date(now.getTime() - MS_PER_DAY)
+      return { start: startOfDay(y), end: endOfDay(y) }
+    }
+    case 'last week':
+      return { start: new Date(now.getTime() - 7 * MS_PER_DAY), end: new Date(now.getTime()) }
+    case 'last month': {
+      const start = new Date(now)
+      start.setMonth(start.getMonth() - 1)
+      return { start, end: new Date(now.getTime()) }
+    }
+    case 'last year': {
+      const start = new Date(now)
+      start.setFullYear(start.getFullYear() - 1)
+      return { start, end: new Date(now.getTime()) }
+    }
+    case 'this month':
+      return {
+        start: new Date(now.getFullYear(), now.getMonth(), 1),
+        end: endOfDay(new Date(now.getFullYear(), now.getMonth() + 1, 0))
+      }
+    default:
+      return null
+  }
+}
+
+function splitRange(text: string): [string, string] | null {
+  const match = text.split(/\s*(?:-|–|to)\s+|\s+(?:-|–|to)\s*/)
+  if (match.length === 2 && match[0] && match[1]) {
+    return [match[0].trim(), match[1].trim()]
+  }
+  return null
+}
+
+const MONTHS: Record<string, number> = {
+  jan: 0,
+  january: 0,
+  feb: 1,
+  february: 1,
+  mar: 2,
+  march: 2,
+  apr: 3,
+  april: 3,
+  may: 4,
+  jun: 5,
+  june: 5,
+  jul: 6,
+  july: 6,
+  aug: 7,
+  august: 7,
+  sep: 8,
+  sept: 8,
+  september: 8,
+  oct: 9,
+  october: 9,
+  nov: 10,
+  november: 10,
+  dec: 11,
+  december: 11
+}
+
+/** Parses a single date token (`M/D`, `M/D/Y`, `Jan 1`, `Jan 1, 2026`) to a Date, or null. */
+export function parseFixedDate(token: string, now: Date = new Date()): Date | null {
+  const text = token.trim().toLowerCase()
+  if (!text) {
+    return null
+  }
+
+  // M/D or M/D/Y
+  const slash = text.match(/^(\d{1,2})\/(\d{1,2})(?:\/(\d{2,4}))?$/)
+  if (slash) {
+    const month = Number(slash[1]) - 1
+    const day = Number(slash[2])
+    const year = slash[3] ? normalizeYear(Number(slash[3])) : now.getFullYear()
+    return validDate(year, month, day)
+  }
+
+  // "Jan 1" or "Jan 1, 2026" or "January 1 2026"
+  const named = text.match(/^([a-z]+)\.?\s+(\d{1,2})(?:,?\s*(\d{2,4}))?$/)
+  if (named && named[1] in MONTHS) {
+    const month = MONTHS[named[1]]
+    const day = Number(named[2])
+    const year = named[3] ? normalizeYear(Number(named[3])) : now.getFullYear()
+    return validDate(year, month, day)
+  }
+
+  return null
+}
+
+function normalizeYear(year: number): number {
+  return year < 100 ? 2000 + year : year
+}
+
+function validDate(year: number, month: number, day: number): Date | null {
+  if (month < 0 || month > 11 || day < 1 || day > 31) {
+    return null
+  }
+  const date = new Date(year, month, day)
+  if (date.getMonth() !== month || date.getDate() !== day) {
+    return null
+  }
+  return date
+}