tailor-platform
diff --git a/‎.changeset/date-picker.md‎
Lines changed: 24 additions & 0 deletions b/‎.changeset/date-picker.md‎
Lines changed: 24 additions & 0 deletions
diff --git a/‎docs/components/data-table.md‎
Lines changed: 14 additions & 1 deletion b/‎docs/components/data-table.md‎
Lines changed: 14 additions & 1 deletion
diff --git a/‎docs/components/date-picker.md‎
Lines changed: 182 additions & 0 deletions b/‎docs/components/date-picker.md‎
Lines changed: 182 additions & 0 deletions
@@ -0,0 +1,24 @@
+---
+"@tailor-platform/app-shell": minor
+---
+
+Add DateField, DatePicker, and Calendar components (@internationalized/date + Base UI implementation)
+
+Introduces three accessible date-input components, implemented on `@internationalized/date` (value layer) and Base UI (`Popover`) with hand-rolled segmented-input and calendar-grid behaviour:
+
+- `DateField` — segmented date/time input with label, description, and error message
+- `DatePicker` — date field with a popover calendar
+- `Calendar` — standalone calendar grid
+
+All three accept `LocalizedString` labels/descriptions and resolve locale + timezone from the AppShell context. The `@internationalized/date` value types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`, …) and helpers (`today`, `parseDate`, `getLocalTimeZone`, …) are re-exported from `@tailor-platform/app-shell`.
+
+New AppShell context hooks:
+
+- `useResolvedLocale()` — full BCP-47 locale (e.g. `"en-GB"`) plus the language code
+- `useTimeZone()` — the configured IANA timezone, falling back to the user's local timezone
+
+AppShell now accepts an optional `timeZone` prop.
+
+> This is the **`@internationalized/date` + Base UI** variant — the lighter foundation tracked in the design proposal (§9). Net-new dependency is just `@internationalized/date` (~11 KB gz); Base UI is already in the bundle. Public API and accessibility contract are identical to the react-aria variant.
+>
+> **Known limitation:** the segmented input is built from `role="spinbutton"` elements that aren't `contentEditable`, so on-screen-keyboard typing on touch devices is limited — the calendar popover is the touch-friendly path (desktop keyboard entry works fully). The APG behaviour is unit-tested but not yet screen-reader-audited.
@@ -492,14 +492,27 @@ The `filter` property on a column accepts a `FilterConfig` object. When set, the
 | `string`   | Text           | `eq`, `ne`, `contains`, `notContains`, `hasPrefix`, `hasSuffix`, `notHasPrefix`, `notHasSuffix`, `in`, `nin` |
 | `number`   | Number         | `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, **`between`**, `in`, `nin`                                             |
 | `datetime` | Datetime-local | `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, **`between`**, `in`, `nin`                                             |
-| `date`     | Date           | `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, **`between`**, `in`, `nin`                                             |
+| `date`     | **DatePicker** | `eq` (_exact date_), `gte` (_after_), `lte` (_before_), **`between`**                                        |
 | `time`     | Time           | `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, **`between`**, `in`, `nin`                                             |
 | `enum`     | Dropdown       | `eq`, `ne`, `in`, `nin`                                                                                      |
 | `boolean`  | Toggle         | `eq`, `ne`                                                                                                   |
 | `uuid`     | Text           | `eq`, `ne`, `in`, `nin`                                                                                      |
 
 When the user selects the `between` operator on a `number`, `datetime`, `date`, or `time` column, the filter chip renders a range input with **min** and **max** bounds.
 
+### Date Filters
+
+`date` columns use the app-shell [`DatePicker`](./date-picker.md) as the filter input (single value and `between` ranges) and present a friendlier, slimmer operator set:
+
+| Operator  | Label        | Meaning                    |
+| --------- | ------------ | -------------------------- |
+| `eq`      | _exact date_ | matches that calendar date |
+| `gte`     | _after_      | on or after (inclusive)    |
+| `lte`     | _before_     | on or before (inclusive)   |
+| `between` | _between_    | inclusive min–max range    |
+
+`gt` / `lt` / `ne` are intentionally dropped — the inclusive _after_ / _before_ cover the intent. The filter chip shows the value as a locale-formatted date (e.g. `15 Jun 2026`), and the picker resolves its locale/timezone from the AppShell context. (Only `date` is remapped this way; `datetime` and `time` keep the full numeric operator set and native inputs.)
+
 ### String Filter Case Sensitivity
 
 String filters are **case-insensitive by default** — they use the Tailor Platform `regex` operator with an `(?i)` prefix. The filter chip renders a **"Case sensitive"** checkbox that lets users opt into exact-case matching.
 
@@ -0,0 +1,182 @@
+---
+title: DatePicker
+description: Accessible date input components (@internationalized/date + Base UI)
+---
+
+# DatePicker
+
+Three related components for date input — a segmented field, a field with a calendar popover, and a standalone calendar grid. Built on [`@internationalized/date`](https://react-spectrum.adobe.com/internationalized/date/) (the value layer) and Base UI (`Popover`), with the segmented input and calendar grid implemented to the [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/) date-picker/grid patterns. They integrate automatically with AppShell's locale and timezone context.
+
+> **Implementation note.** This is the `@internationalized/date` + Base UI variant. The public API and accessibility contract are identical to the react-aria variant; only the internals differ. See `docs/proposals/date-picker-impl-comparison.md`.
+
+## Import
+
+```tsx
+import {
+  DateField,
+  DatePicker,
+  Calendar,
+  // Date value helpers (re-exported from @internationalized/date)
+  today,
+  parseDate,
+  getLocalTimeZone,
+  type CalendarDate,
+  type DateValue,
+} from "@tailor-platform/app-shell";
+```
+
+No separate `@internationalized/date` install needed — the value types and helpers are re-exported from `@tailor-platform/app-shell`.
+
+## DateField
+
+A segmented input that lets users type dates digit-by-digit, with per-segment Up/Down, type-to-fill auto-advance, and full keyboard support.
+
+```tsx
+<DateField label="Invoice date" />
+```
+
+### With description and error
+
+```tsx
+<DateField
+  label="Start date"
+  description="Format follows your locale"
+  errorMessage="A start date is required"
+/>
+```
+
+### Controlled
+
+```tsx
+const [date, setDate] = useState<CalendarDate | null>(null);
+<DateField label="Invoice date" value={date} onChange={setDate} />;
+```
+
+## DatePicker
+
+A `DateField` with a calendar popover.
+
+```tsx
+<DatePicker label="Ship date" />
+```
+
+### Constrained + unavailable dates
+
+```tsx
+<DatePicker
+  label="Delivery date"
+  minValue={today(getLocalTimeZone())}
+  isDateUnavailable={(date) => {
+    const dow = date.toDate(getLocalTimeZone()).getDay();
+    return dow === 0 || dow === 6; // weekends
+  }}
+/>
+```
+
+### Week start
+
+```tsx
+<DatePicker label="Date" firstDayOfWeek="mon" />
+```
+
+## Calendar
+
+A standalone calendar grid for custom date-selection UIs (e.g. reporting filters).
+
+```tsx
+<Calendar aria-label="Select date" onChange={(date) => console.log(date)} />
+```
+
+## Localization
+
+Locale and timezone come from AppShell automatically. Override per field with `locale` / `timeZone`:
+
+```tsx
+<DatePicker label="Date" locale="ja-JP" />
+```
+
+Segment order, first-day-of-week, and month/weekday names all follow the resolved locale.
+
+## Keyboard
+
+- **Segments:** `↑`/`↓` increment/decrement, digits type-to-fill (auto-advance), `←`/`→` move between segments, `Backspace` clears.
+- **Calendar grid:** arrows move by day/week, `Home`/`End` to week start/end, `PageUp`/`PageDown` by month, `Shift`+`PageUp`/`PageDown` by year, `Enter`/`Space` selects.
+
+## Accessibility
+
+- The segmented field is a labelled `role="group"` of `role="spinbutton"` segments with `aria-valuemin`/`max`/`now`/`text`.
+- The calendar is a `role="grid"`; each day is a button with a full-date `aria-label`; disabled/unavailable days are announced via `aria-disabled`.
+- The popover is a labelled `role="dialog"`.
+
+> **Known limitations (this variant).** The segments are `<div role="spinbutton">` that aren't `contentEditable`, so a touch device's on-screen keyboard doesn't open for typing — on mobile, use the calendar popover to pick a date (desktop keyboard entry and the calendar both work fully). The APG patterns are implemented and unit-tested but **not yet screen-reader-audited**, and RTL arrow-key flipping isn't handled. See [the implementation comparison](../proposals/date-picker-impl-comparison.md) ("Known gaps vs react-aria") for the full list.
+
+## Props
+
+The tables below list props this variant **actually implements** for v1 (date granularity). A few props are part of the type surface — kept identical to the react-aria variant so a later swap is source-compatible — but aren't acted on yet; those are called out under [Proposed / not yet implemented](#proposed--not-yet-implemented).
+
+### DateFieldProps
+
+| Prop                                      | Type                             | Description                                                             |
+| ----------------------------------------- | -------------------------------- | ----------------------------------------------------------------------- |
+| `label`                                   | `LocalizedString`                | Field label                                                             |
+| `description`                             | `LocalizedString`                | Helper text below the field                                             |
+| `errorMessage`                            | `LocalizedString`                | Error text; also sets the invalid state                                 |
+| `value` / `defaultValue`                  | `DateValue \| null`              | Controlled / uncontrolled value (`CalendarDate` at date granularity)    |
+| `onChange`                                | `(v: DateValue \| null) => void` | Fires on a complete, valid value; `null` when cleared                   |
+| `isDisabled` / `isReadOnly` / `isInvalid` | `boolean`                        | State flags                                                             |
+| `isRequired`                              | `boolean`                        | Sets `aria-required` on the segments (no visual required indicator yet) |
+| `placeholderValue`                        | `DateValue`                      | Seeds unset segments (increment start + segment order)                  |
+| `autoFocus`                               | `boolean`                        | Focus the first segment on mount                                        |
+| `locale`                                  | `string`                         | BCP-47 locale override (defaults to the AppShell formatting locale)     |
+| `name`                                    | `string`                         | Emits a hidden `<input>` with the ISO value for form submission         |
+| `aria-label`                              | `string`                         | Accessible name when there's no visible `label` (e.g. compact filters)  |
+| `className`                               | `string`                         | Root element class                                                      |
+
+> `DateField` has no calendar, so `minValue` / `maxValue` / `isDateUnavailable` don't apply to it — they're honoured by `DatePicker` and `Calendar` below.
+
+### DatePickerProps
+
+All `DateFieldProps`, plus:
+
+| Prop                    | Type                                                          | Description                                                          |
+| ----------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `minValue` / `maxValue` | `DateValue`                                                   | Earliest / latest selectable date in the calendar                    |
+| `isDateUnavailable`     | `(date: DateValue) => boolean`                                | Mark individual dates unselectable (still keyboard-navigable)        |
+| `firstDayOfWeek`        | `"sun" \| "mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat"` | Force the calendar's first column; omit to follow the locale         |
+| `timeZone`              | `string`                                                      | IANA timezone for resolving "today"; defaults to AppShell `timeZone` |
+
+### CalendarProps
+
+The standalone calendar grid. It has no segmented input, so its surface is listed in full:
+
+| Prop                                   | Type                           | Description                                                   |
+| -------------------------------------- | ------------------------------ | ------------------------------------------------------------- |
+| `value` / `defaultValue`               | `DateValue \| null`            | Controlled / uncontrolled selected date                       |
+| `onChange`                             | `(v: DateValue) => void`       | Fires when a date is selected                                 |
+| `minValue` / `maxValue`                | `DateValue`                    | Earliest / latest selectable date                             |
+| `isDateUnavailable`                    | `(date: DateValue) => boolean` | Mark individual dates unselectable (still keyboard-navigable) |
+| `focusedValue` / `defaultFocusedValue` | `DateValue`                    | Controlled / initial focused (visible) date                   |
+| `onFocusChange`                        | `(date: CalendarDate) => void` | Fires when the focused date changes (arrows, month paging)    |
+| `firstDayOfWeek`                       | `"sun" \| "mon" \| …`          | Force the first column; omit to follow the locale             |
+| `isDisabled` / `isReadOnly`            | `boolean`                      | Disable the grid / prevent selection changes                  |
+| `timeZone`                             | `string`                       | IANA timezone for "today"; defaults to AppShell `timeZone`    |
+| `locale`                               | `string`                       | BCP-47 locale override                                        |
+| `aria-label` / `aria-labelledby`       | `string`                       | Accessible name for the grid                                  |
+| `className`                            | `string`                       | Root element class                                            |
+
+### Proposed / not yet implemented
+
+Accepted by the prop types (for parity with the react-aria variant) but **not acted on** in this variant yet:
+
+| Prop           | Type                                      | Status                                                                                                                                                                                                             |
+| -------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `granularity`  | `"day" \| "hour" \| "minute" \| "second"` | Only `"day"` is supported (the default). Time granularities — and the `CalendarDateTime` / `ZonedDateTime` values they produce — are the tracked **DateTime fast-follow**; the calendar has no time selection yet. |
+| `hourCycle`    | `12 \| 24`                                | No effect until time granularity lands (12h/24h only matters with an hour segment).                                                                                                                                |
+| `hideTimeZone` | `boolean`                                 | Unused; only relevant to `ZonedDateTime` display (time granularity).                                                                                                                                               |
+
+See the proposal's [Post-v1 fast-follows](../proposals/date-picker.md) for the DateTime plan.
+
+## Related
+
+- [Form](./form.md) — wrap date fields with validation
+- [Input](./input.md) — plain text input