@lekoala/date-picker 0.4.0 → 0.5.0

package/README.md

@@ -1,265 +1,281 @@
-# @lekoala/date-picker
-
-Small, native-first date picker and inline calendar primitives.
-
-> The interaction contract, event names, public styling tokens and the component API are frozen — see [docs/DECISIONS.md](docs/DECISIONS.md). Internal DOM and class names are `.dp-*` implementation details and stay private.
-
-This project fills the gap between a normal editable date field and a full scheduling calendar. A plain date input remains the right answer for simple CMS/editing forms. This component becomes useful when a date has context: availability, disabled days, annotations, remote state, start/end relationships, or a mini calendar that navigates another view.
-
-## The two primitives
-
-### `<date-calendar>`
-
-An inline calendar with real month/year navigation, keyboard support and three distinct pieces of state:
-
-- `display` — the month being rendered (`YYYY-MM`);
-- `focusedDate` — the roving keyboard target (`YYYY-MM-DD`);
-- `value` — the selected date (`YYYY-MM-DD`, optional).
-
-`display` and `focusedDate` are coupled during navigation/display: changing the displayed month re-clamps the focused day into that month, because the roving-tabbable grid cell must stay visible. `value` and activation stay independent of both.
-
-User activation is exposed separately as `dateactivate`. This is what makes the same calendar useful as a selector **and** as a mini navigator.
-
-```html
-<date-calendar value="2026-09-10" fixed-weeks></date-calendar>
-```
-
-For a navigator that should not own a selection:
-
-```html
-<date-calendar id="mini" selection="none" fixed-weeks show-week-numbers></date-calendar>
-<script type="module">
-  const mini = document.querySelector("#mini");
-  mini.addEventListener("dateactivate", (event) => {
-    agenda.gotoDate(event.detail.date);
-  });
-</script>
-```
-
-### `<date-picker>`
-
-A composition around a real editable text input. The user sees and edits a short locale-aware numeric date while form submission stays canonical ISO.
-
-**Use `<date-picker>` when choosing a date benefits from calendar context.** For a simple editable date field, a normal input with formatting and validation is the right tool instead.
-
-```html
-<date-picker value="2026-09-10" locale="fr-BE">
-  <input name="appointment_date" required>
-</date-picker>
-```
-
-With JavaScript enabled the input displays `10/09/2026`; the hidden submitted value remains `2026-09-10`. The visible input keeps the label, focus, required state and validation UI.
-
-By default the calendar opens when the field receives focus — without stealing the keyboard focus, so typing works immediately. `open-on-focus="false"` makes the calendar opt-in (trigger button or `ArrowDown`). Under `readonly` the value stays editable-by-calendar-off but is still submitted; under `disabled` the field is also unsubmitted.
-
-## Start/end ranges
-
-Two product shapes cover ranges.
-
-**One shared calendar surface** — two editable fields wired to a single picker popup:
-
-```html
-<date-picker range>
-  <input data-range-start name="arrival" aria-label="Arrival">
-  <input data-range-end name="departure" aria-label="Departure">
-</date-picker>
-```
-
-Opening from a field targets that bound; picking the first date moves the active endpoint to the other bound without closing, and the second pick completes and closes. `picker.range` is the atomic `{ start, end }` API (single `rangechange` event).
-
-**Two independent pickers** — a small external link for visually separate fields:
-
-```js
-import { linkDateRange } from "@lekoala/date-picker";
-
-const cleanup = linkDateRange(startPicker, endPicker);
-```
-
-The relationship applies `end >= start` and `start <= end` as effective bounds. Neither picker knows about its sibling.
-
-## Date + time
-
-A date pairs with one or two native time companions. The picker owns the civil date; the time inputs own their civil time values:
-
-```html
-<date-picker>
-  <input name="appointment[date]">
-  <input type="time" data-time-start name="appointment[time]">
-</date-picker>
-```
-
-```text
-appointment[date] = 2026-09-10
-appointment[time] = 09:30
-```
-
-The application/server combines these civil values and applies the relevant timezone when a datetime/instant is needed. The picker never constructs a combined datetime value.
-
-## Availability and per-day metadata
-
-The calendar accepts a source function or `{ load() }` object with the same abortable shape used elsewhere in LeKoala components:
-
-```js
-calendar.source = async ({ start, end }, { signal }) => {
-  const response = await fetch(`/availability?start=${start}&end=${end}`, { signal });
-  return response.json();
-};
-```
-
-Accepted payloads are deliberately simple:
-
-```js
-{
-  dates: {
-    "2026-09-10": {
-      enabled: true,
-      description: "Available morning and afternoon",
-      morning: true,
-      afternoon: true
-    }
-  }
-}
-```
-
-Business metadata is not interpreted by the core. Consumers can add visual content without replacing the grid cell or its accessibility semantics:
-
-```js
-calendar.renderDay = (_date, state) => {
-  if (!state.morning && !state.afternoon) return "";
-  return `${state.morning ? "●" : "○"}${state.afternoon ? "●" : "○"}`;
-};
-```
-
-## Date math
-
-The public value model is intentionally boring: canonical `YYYY-MM-DD` strings. There is no public `Date`, timestamp, timezone or `Temporal` dependency.
-
-Pure civil-date helpers are exported under `dates`:
-
-```js
-import { dates } from "@lekoala/date-picker";
-
-const weeks = dates.getMonthWeeks("2026-09-03", { firstDay: 1 });
-```
-
-`getMonthWeeks()` returns the true 4–6 full civil weeks covering the month. It never pads to six rows. `fixed-weeks` is a rendering choice made by `<date-calendar>`.
-
-## Accessibility baseline
-
-The calendar follows the WAI-ARIA date-picker/grid interaction model:
-
-- semantic `table[role="grid"]`;
-- one roving `tabindex="0"` grid cell;
-- arrow keys move by day/week;
-- Home/End move to week boundaries;
-- PageUp/PageDown move by month;
-- Shift+PageUp/PageDown move by year;
-- Enter/Space activate a date;
-- keyboard movement never implicitly selects;
-- `aria-selected` identifies the selected date;
-- `aria-current="date"` identifies today;
-- abbreviated weekday headers keep full `abbr` names.
-
-The picker popup uses native Popover for the top layer and `@lekoala/floating` for geometry. It has `role="dialog"`, but it is intentionally **not** marked `aria-modal` because the current implementation does not inert the rest of the document.
-
-The calendar trigger is a real button painted inside the field's own box (like the native `input[type=time]` indicator): the field reserves its place with `padding-inline-end`, keeps its own border and background, and its focus ring wraps the trigger too. The trigger draws no chrome of its own and shows a small inner ring when focused.
-
-Fields, header controls and days share an inner outline that survives forced colors. Customize its color with `--dp-focus` (default `var(--dp-accent)`) and thickness with `--dp-focus-width` (default `2px`) on `date-picker` and `date-calendar`. The trigger keeps a `-5px` inset around its icon; selected days and range endpoints use `--dp-accent-fg` for contrast. Fields and header controls now show this solid outline instead of the previous soft halo.
-
-When the popup opens on the field's focus, grid navigation is reachable via `ArrowDown` (or the trigger button) so the focus-restore/Escape flow stays predictable. Closing returns focus to the control that opened the popover: the field when it opened by focus, the trigger when it was activated. In range mode focus follows the active bound instead, because a first pick moves the workflow to the other bound.
-
-See [docs/ACCESSIBILITY.md](docs/ACCESSIBILITY.md).
-
-## Install / develop
-
-```bash
-bun install
-bun run dev
-```
-
-If a previous `bun run dev` is still holding port `4859`, clear it with `bun run dev:kill` (or restart in one go with `bun run dev:restart`).
-
-Tooling is aligned with the current LeKoala component repos:
-
-- Bun 1.4.3
-- TypeScript 7.0.2 (`checkJs` + declaration emit)
-- Biome 2.5.15
-- Playwright 1.64.0
-- `@lekoala/floating ^0.2.0`
-
-Useful commands:
-
-```bash
-bun run test
-bun run typecheck
-bun run lint
-bun run build
-bun run test:browser
-bun run test:browser:all
-bun run check:all
-```
-
-## Build outputs
-
-`bun run build` produces:
-
-```text
-dist/date-picker.js
-dist/date-picker.min.js
-dist/date-picker.css
-dist/date-picker.min.css
-dist/date-picker.standalone.min.js
-dist/types/**
-```
-
-The default ESM exports point at `src/`, matching the native-first development style of `@lekoala/combobox`. The classic build is file:// friendly; the standalone build additionally injects the component CSS.
-
-## Scope
-
-Included:
-
-- inline single-date selection;
-- mini-calendar/navigation-only use;
-- month and year selection;
-- previous/next navigation;
-- editable localized input + canonical submitted value;
-- min/max and custom disabled rules;
-- presentation-only range band (`highlightedRange`);
-- shared-calendar two-field range picker (`<date-picker range>`);
-- linked start/end pickers (`linkDateRange`);
-- native time companions (one or two `input[type=time]` beside the date);
-- `Intl` month/year control order + `month-format="short"`;
-- RTL through the inherited `dir` (no `isRTL` option);
-- readable keyboard focus on disabled/selected days;
-- compact-consumer CSS tokens (`--dp-header-control-size`, `--dp-day-radius`, …);
-- async per-day state with cancellation;
-- custom day decorations that cannot replace the accessible cell;
-- fixed six-row presentation as an opt-in;
-- ISO week numbers;
-- keyboard and focus contracts.
-
-Deliberately out of scope:
-
-- custom time-picker UI and combined datetime values (only native `input[type=time]` companions are supported);
-- timezones;
-- in-place single-calendar range *selection interaction* (use the two-field picker);
-- multi-date selection;
-- recurrence;
-- natural-language parsing;
-- plugin registry;
-- virtualized months;
-- scheduling/time slots.
-
-## Docs
-
-- [Changelog](CHANGELOG.md)
-- [Architecture](docs/ARCHITECTURE.md)
-- [Decisions](docs/DECISIONS.md)
-- [API](docs/API.md)
-- [Accessibility checklist](docs/AT-CHECKLIST.md)
-- [Use cases](docs/USE_CASES.md)
-- [Accessibility](docs/ACCESSIBILITY.md)
-- [Testing](docs/TESTING.md)
-- [Roadmap](docs/ROADMAP.md)
-- [Calendar integration](docs/CALENDAR-INTEGRATION.md)
-- [Flatpickr/Formidable migration](docs/MIGRATION-FLATPICKR.md)
+# @lekoala/date-picker
+
+Small, native-first date picker and inline calendar primitives.
+
+> The interaction contract, event names, public styling tokens and the component API are frozen — see [docs/DECISIONS.md](docs/DECISIONS.md). Internal DOM and class names are `.dp-*` implementation details and stay private.
+
+This project fills the gap between a normal editable date field and a full scheduling calendar. A plain date input remains the right answer for simple CMS/editing forms. This component becomes useful when a date has context: availability, disabled days, annotations, remote state, start/end relationships, or a mini calendar that navigates another view.
+
+## The two primitives
+
+### `<date-calendar>`
+
+An inline calendar with real month/year navigation, keyboard support and three distinct pieces of state:
+
+- `display` — the month being rendered (`YYYY-MM`);
+- `focusedDate` — the roving keyboard target (`YYYY-MM-DD`);
+- `value` — the selected date (`YYYY-MM-DD`, optional).
+
+`display` and `focusedDate` are coupled during navigation/display: changing the displayed month re-clamps the focused day into that month, because the roving-tabbable grid cell must stay visible. `value` and activation stay independent of both.
+
+User activation is exposed separately as `dateactivate`. This is what makes the same calendar useful as a selector **and** as a mini navigator.
+
+```html
+<date-calendar value="2026-09-10" fixed-weeks></date-calendar>
+```
+
+For a navigator that should not own a selection:
+
+```html
+<date-calendar id="mini" selection="none" fixed-weeks show-week-numbers></date-calendar>
+<script type="module">
+  const mini = document.querySelector("#mini");
+  mini.addEventListener("dateactivate", (event) => {
+    agenda.gotoDate(event.detail.date);
+  });
+</script>
+```
+
+### `<date-picker>`
+
+A composition around a real editable text input. The user sees and edits a short locale-aware numeric date while form submission stays canonical ISO.
+
+**Use `<date-picker>` when choosing a date benefits from calendar context.** For a simple editable date field, a normal input with formatting and validation is the right tool instead.
+
+```html
+<date-picker value="2026-09-10" locale="fr-BE">
+  <input name="appointment_date" required>
+</date-picker>
+```
+
+With JavaScript enabled the input displays `10/09/2026`; the hidden submitted value remains `2026-09-10`. The visible input keeps the label, focus, required state and validation UI.
+
+By default the calendar opens when the field receives focus — without stealing the keyboard focus, so typing works immediately. `open-on-focus="false"` makes the calendar opt-in (trigger button or `ArrowDown`). Under `readonly` the value stays editable-by-calendar-off but is still submitted; under `disabled` the field is also unsubmitted.
+
+## Start/end ranges
+
+Two product shapes cover ranges.
+
+**One shared calendar surface** — two editable fields wired to a single picker popup:
+
+```html
+<date-picker range>
+  <input data-range-start name="arrival" aria-label="Arrival">
+  <input data-range-end name="departure" aria-label="Departure">
+</date-picker>
+```
+
+Opening from a field targets that bound; picking the first date moves the active endpoint to the other bound without closing, and the second pick completes and closes. `picker.range` is the atomic `{ start, end }` API (single `rangechange` event).
+
+**Two independent pickers** — a small external link for visually separate fields:
+
+```js
+import { linkDateRange } from "@lekoala/date-picker";
+
+const cleanup = linkDateRange(startPicker, endPicker);
+```
+
+The relationship applies `end >= start` and `start <= end` as effective bounds. Neither picker knows about its sibling.
+
+## Date + time
+
+A date pairs with one or two native time companions. The picker owns the civil date; the time inputs own their civil time values:
+
+```html
+<date-picker>
+  <input name="appointment[date]">
+  <input type="time" data-time-start name="appointment[time]">
+</date-picker>
+```
+
+```text
+appointment[date] = 2026-09-10
+appointment[time] = 09:30
+```
+
+The application/server combines these civil values and applies the relevant timezone when a datetime/instant is needed. The picker never constructs a combined datetime value.
+
+## Availability and per-day metadata
+
+The calendar accepts a source function or `{ load() }` object with the same abortable shape used elsewhere in LeKoala components:
+
+```js
+calendar.source = async ({ start, end }, { signal }) => {
+  const response = await fetch(`/availability?start=${start}&end=${end}`, { signal });
+  return response.json();
+};
+```
+
+Accepted payloads are deliberately simple:
+
+```js
+{
+  dates: {
+    "2026-09-10": {
+      enabled: true,
+      description: "Available morning and afternoon",
+      morning: true,
+      afternoon: true
+    }
+  }
+}
+```
+
+Business metadata is not interpreted by the core. Consumers can add visual content without replacing the grid cell or its accessibility semantics:
+
+```js
+calendar.renderDay = (_date, state) => {
+  if (!state.morning && !state.afternoon) return "";
+  return `${state.morning ? "●" : "○"}${state.afternoon ? "●" : "○"}`;
+};
+```
+
+## Date math
+
+The public value model is intentionally boring: canonical `YYYY-MM-DD` strings. There is no public `Date`, timestamp, timezone or `Temporal` dependency.
+
+Pure civil-date helpers are exported under `dates`:
+
+```js
+import { dates } from "@lekoala/date-picker";
+
+const weeks = dates.getMonthWeeks("2026-09-03", { firstDay: 1 });
+```
+
+`getMonthWeeks()` returns the true 4–6 full civil weeks covering the month. It never pads to six rows. `fixed-weeks` is a rendering choice made by `<date-calendar>`.
+
+## Accessibility baseline
+
+The calendar follows the WAI-ARIA date-picker/grid interaction model:
+
+- semantic `table[role="grid"]`;
+- one roving `tabindex="0"` grid cell;
+- arrow keys move by day/week;
+- Home/End move to week boundaries;
+- PageUp/PageDown move by month;
+- Shift+PageUp/PageDown move by year;
+- Enter/Space activate a date;
+- keyboard movement never implicitly selects;
+- `aria-selected` identifies the selected date;
+- `aria-current="date"` identifies today;
+- abbreviated weekday headers keep full `abbr` names.
+
+The picker popup uses native Popover for the top layer and `@lekoala/floating` for geometry. It has `role="dialog"`, but it is intentionally **not** marked `aria-modal` because the current implementation does not inert the rest of the document.
+
+The calendar trigger is a real button painted inside the field's own box (like the native `input[type=time]` indicator): the field reserves its place with `padding-inline-end`, keeps its own border and background, and its focus ring wraps the trigger too. The trigger draws no chrome of its own and shows a small inner ring when focused.
+
+Fields, header controls and days share an inner outline that survives forced colors. Customize its color with `--dp-focus` (default `var(--dp-accent)`) and thickness with `--dp-focus-width` (default `2px`) on `date-picker` and `date-calendar`. The trigger keeps a `-5px` inset around its icon; selected days and range endpoints use `--dp-accent-fg` for contrast. Fields and header controls now show this solid outline instead of the previous soft halo.
+
+When the popup opens on the field's focus, grid navigation is reachable via `ArrowDown` (or the trigger button) so the focus-restore/Escape flow stays predictable. Closing returns focus to the control that opened the popover: the field when it opened by focus, the trigger when it was activated. In range mode focus follows the active bound instead, because a first pick moves the workflow to the other bound.
+
+See [docs/ACCESSIBILITY.md](docs/ACCESSIBILITY.md).
+
+## Install / develop
+
+```bash
+bun install
+bun run dev
+```
+
+If a previous `bun run dev` is still holding port `4859`, clear it with `bun run dev:kill` (or restart in one go with `bun run dev:restart`).
+
+Tooling is aligned with the current LeKoala component repos:
+
+- Bun 1.4.3
+- TypeScript 7.0.2 (`checkJs` + declaration emit)
+- Biome 2.5.15
+- Playwright 1.64.0
+- `@lekoala/floating ^0.2.0`
+
+Useful commands:
+
+```bash
+bun run test
+bun run typecheck
+bun run lint
+bun run build
+bun run test:browser
+bun run test:browser:all
+bun run check:all
+```
+
+## Build outputs
+
+`bun run build` produces:
+
+```text
+dist/date-picker.js
+dist/date-picker.min.js
+dist/date-picker.css
+dist/date-picker.min.css
+dist/date-picker.standalone.min.js
+dist/types/**
+```
+
+The default ESM exports point at `src/`, matching the native-first development style of `@lekoala/combobox`. The classic build is file:// friendly; the standalone build additionally injects the component CSS.
+
+## Scope
+
+Included:
+
+- inline single-date selection;
+- mini-calendar/navigation-only use;
+- month and year selection;
+- previous/next navigation;
+- editable localized input + canonical submitted value;
+- min/max and custom disabled rules;
+- presentation-only range band (`highlightedRange`);
+- shared-calendar two-field range picker (`<date-picker range>`);
+- linked start/end pickers (`linkDateRange`);
+- native time companions (one or two `input[type=time]` beside the date);
+- `Intl` month/year control order + `month-format="short"`;
+- RTL through the inherited `dir` (no `isRTL` option);
+- readable keyboard focus on disabled/selected days;
+- compact-consumer CSS tokens (`--dp-header-control-size`, `--dp-day-radius`, …);
+- async per-day state with cancellation;
+- custom day decorations that cannot replace the accessible cell;
+- fixed six-row presentation as an opt-in;
+- ISO week numbers;
+- keyboard and focus contracts.
+
+Deliberately out of scope:
+
+- custom time-picker UI and combined datetime values (only native `input[type=time]` companions are supported);
+- timezones;
+- in-place single-calendar range *selection interaction* (use the two-field picker);
+- multi-date selection;
+- recurrence;
+- natural-language parsing;
+- plugin registry;
+- virtualized months;
+- scheduling/time slots.
+
+## Docs
+
+- [Changelog](CHANGELOG.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Decisions](docs/DECISIONS.md)
+- [API](docs/API.md)
+- [Accessibility checklist](docs/AT-CHECKLIST.md)
+- [Use cases](docs/USE_CASES.md)
+- [Accessibility](docs/ACCESSIBILITY.md)
+- [Testing](docs/TESTING.md)
+- [Roadmap](docs/ROADMAP.md)
+- [Calendar integration](docs/CALENDAR-INTEGRATION.md)
+- [Flatpickr/Formidable migration](docs/MIGRATION-FLATPICKR.md)
+
+### Host control classes
+
+Set application-wide header styles before creating calendars or pickers:
+
+```js
+import { setDefaultControlClasses } from "@lekoala/date-picker";
+
+setDefaultControlClasses({
+  month: "form-select form-select-sm",
+  year: "form-control form-control-sm",
+  nav: "btn btn-outline-secondary btn-sm",
+});
+```
+
+Each role with author classes uses the host design system's skin. Override per element through `controlClasses`; roles without classes retain the default skin. Day cells and the field trigger are unchanged.

package/custom-elements.json

@@ -91,6 +91,11 @@
               "kind": "getter",
               "name": "showWeekNumbers"
             },
+            {
+              "kind": "getter",
+              "name": "controlClasses",
+              "description": "Author classes for header controls; merged with global defaults."
+            },
             {
               "kind": "getter",
               "name": "messages"
@@ -313,6 +318,11 @@
               "kind": "getter",
               "name": "open"
             },
+            {
+              "kind": "getter",
+              "name": "controlClasses",
+              "description": "Author classes for header controls; merged with global defaults."
+            },
             {
               "kind": "getter",
               "name": "messages"