@lekoala/date-picker 0.3.0 → 0.5.0

package/docs/DECISIONS.md

@@ -1,49 +1,68 @@
-# Decisions
-
-Frozen contracts for the `0.1.0` surface. A change to a decision below is a breaking change and needs a proposal, not an opportunistic edit.
-
-## D1 — Calendar events are flat, verb-named
-
-Never merged with the `value` concept (`dateactivate` is activation, not `value`).
-
-- `date-calendar`: `dateactivate`, `datechange`, `dateinvalid`, `displaychange`, `dateloadstart`, `dateloadend`, `dateloaderror`.
-- `date-picker`: `valuechange`, `open`, `close`.
-
-No `dp:` namespace prefix on element events, even though `@lekoala/combobox` namespaces its events (`combobox:*`).
-
-Rationale: the flat names describe a distinct concept (`dateactivate`), never collide with native input events, and are already wired through the docs, demos and tests. A namespace is not worth the churn for this package.
-
-## D2 — `selection="none"` is the final spelling
-
-The navigation-only calendar keeps `selection="none"`.
-
-`selection` remains a value attribute (`single` | `none`); it is how the mini calendar speaks the navigation contract: accepted activation dispatches `dateactivate`, `value` is untouched.
-
-## D3 — CSS: `--dp-*` is public, `.dp-*` is not
-
-> `--dp-*` is the public styling namespace. `.dp-*` identifies component-owned DOM but is not a public styling API unless explicitly documented.
-
-- The namespace prefix is `dp`, final. There are no `--lko-dp-*` or `.lko-dp-*` classes. A shared `--lko-*` token space is reserved for tokens actually shared between LeKoala packages, not as a per-component prefix.
-- The `--dp-*` custom properties (background, foreground, accent, border, radius, day-size, gap, …) are the **public customization surface**. They are listed in `custom-elements.json` and are stable.
-- Every `.dp-*` class is **internal DOM** and may change, move or disappear without a semver bump. This includes `.dp-day`, `.dp-grid`, `.dp-picker-panel` and the day-extra container.
-- `renderDay()` is a public extension seam, but the name of the container its output is placed into is **not** promised. Consumers style their own returned nodes and assign their own class names.
-- Demos, tests and internal code may reference `.dp-*` classes; their use there does not turn those classes into public API.
-
-Context: DOM-backed styling hooks become API the moment they are documented — every internal rename then breaks consumers. We prefer to expose hooks (`--dp-*`, `renderDay()`, events) and keep the rendered anatomy free to evolve.
-
-## D4 — `<date-picker>` opens on focus; `open` is read-only
-
-- The picker opens its popover when the input receives focus (`open-on-focus`, default `true`; set `open-on-focus="false"` to opt out).
-- Opening on focus **never steals keyboard focus**: the user can start typing immediately. The grid takes focus only on ArrowDown, on the calendar trigger, or after the user moves the pointer into the popup.
-- Closing returns focus to the control that opened the popover (field or trigger) — the usual popover convention. Range mode is the exception: focus follows the active bound, because a first pick moves the workflow to the other bound.
-- The calendar trigger is overlaid inside the field's own box, like the native `input[type=time]` indicator. The field reserves its place (`padding-inline-end`), keeps its border/background, and owns the focus ring for the pair; the trigger is a real button with an inner ring of its own. A range bound owns its own trigger; the two share one popup, calendar, source and state.
-- `show()` / `hide()` are the control surface. `open` is a **read-only getter** reflecting the popover. There is no `open` attribute: the popover element is the single machine of truth and a second state machine would only drift.
-- `readonly` mirrors native semantics: the field is non-editable, the value is still submitted, and the picker cannot change it — the calendar trigger is disabled. `disabled` additionally unsubmits the field. `readonly` is never used to mean "no typing, but calendar selection allowed".
-- Clearing the editable input clears the canonical value (the component renders no internal clear button). Form resets follow the native `defaultValue` contract. This matches the Open UI datepicker `clear` concept: clearing is a text-editing action, not a component-owned affordance.
-
-## D5 — Time is a native companion, not picker state
-
-- Time fields are authored native `input[type=time]` marked `[data-time-start]` / `[data-time-end]`; `name`, `value`, `required`, `min`, `max`, `step` and submission stay native. There is no hidden time input and no time field controller.
-- `picker.value` / `picker.range` remain date-only (`YYYY-MM-DD`); the picker never constructs a datetime, a timestamp or a timezone-bearing value.
-- The picker only coordinates from/to order (`start <= end`, equality allowed); duration rules stay application-owned.
-- Custom time UI and slot picking stay outside the package.
+# Decisions
+
+Frozen contracts for the public surface. A change to a decision below is a breaking change and needs a proposal, not an opportunistic edit.
+
+## D1 — Calendar events are flat, verb-named
+
+Never merged with the `value` concept (`dateactivate` is activation, not `value`).
+
+- `date-calendar`: `dateactivate`, `datefocus`, `datechange`, `dateinvalid`, `displaychange`, `dateloadstart`, `dateloadend`, `dateloaderror`.
+- `date-picker`: `valuechange`, `open`, `close`, plus `rangechange` in range mode.
+
+The observation verbs stay distinct: `datefocus` observes navigation, `dateactivate` requests an activation (and is cancelable), `datechange` observes a selection. `datefocus` is named after the user event rather than after the `focusedDate` setter, so a programmatic assignment that moves no DOM focus never announces one.
+
+No `dp:` namespace prefix on element events, even though `@lekoala/combobox` namespaces its events (`combobox:*`).
+
+Rationale: the flat names describe a distinct concept (`dateactivate`), never collide with native input events, and are already wired through the docs, demos and tests. A namespace is not worth the churn for this package.
+
+## D2 — `selection="none"` is the final spelling
+
+The navigation-only calendar keeps `selection="none"`.
+
+`selection` remains a value attribute (`single` | `none`); it is how the mini calendar speaks the navigation contract: accepted activation dispatches `dateactivate`, `value` is untouched.
+
+## D3 — CSS: `--dp-*` is public, `.dp-*` is not
+
+> `--dp-*` is the public styling namespace. `.dp-*` identifies component-owned DOM but is not a public styling API unless explicitly documented.
+
+- The namespace prefix is `dp`, final. There are no `--lko-dp-*` or `.lko-dp-*` classes. A shared `--lko-*` token space is reserved for tokens actually shared between LeKoala packages, not as a per-component prefix.
+- The `--dp-*` custom properties (background, foreground, accent, border, radius, day-size, gap, …) are the **public customization surface**. They are listed in `custom-elements.json` and are stable.
+- Every `.dp-*` class is **internal DOM** and may change, move or disappear without a semver bump. This includes `.dp-day`, `.dp-grid`, `.dp-picker-panel` and the day-extra container.
+- `renderDay()` is a public extension seam, but the name of the container its output is placed into is **not** promised. Consumers style their own returned nodes and assign their own class names.
+- Demos, tests and internal code may reference `.dp-*` classes; their use there does not turn those classes into public API.
+
+Context: DOM-backed styling hooks become API the moment they are documented — every internal rename then breaks consumers. We prefer to expose hooks (`--dp-*`, `renderDay()`, events) and keep the rendered anatomy free to evolve.
+
+## D4 — `<date-picker>` opens on focus; `open` is read-only
+
+- The picker opens its popover when the input receives focus (`open-on-focus`, default `true`; set `open-on-focus="false"` to opt out).
+- Opening on focus **never steals keyboard focus**: the user can start typing immediately. The grid takes focus only on ArrowDown, on the calendar trigger, or after the user moves the pointer into the popup.
+- Closing returns focus to the control that opened the popover (field or trigger) — the usual popover convention. Range mode is the exception: focus follows the active bound, because a first pick moves the workflow to the other bound.
+- The calendar trigger is overlaid inside the field's own box, like the native `input[type=time]` indicator. The field reserves its place (`padding-inline-end`), keeps its border/background, and owns the focus ring for the pair; the trigger is a real button with an inner ring of its own. A range bound owns its own trigger; the two share one popup, calendar, source and state.
+- `show()` / `hide()` are the control surface. `open` is a **read-only getter** reflecting the popover. There is no `open` attribute: the popover element is the single machine of truth and a second state machine would only drift.
+- `readonly` mirrors native semantics: the field is non-editable, the value is still submitted, and the picker cannot change it — the calendar trigger is disabled. `disabled` additionally unsubmits the field. `readonly` is never used to mean "no typing, but calendar selection allowed".
+- Clearing the editable input clears the canonical value (the component renders no internal clear button). Form resets follow the native `defaultValue` contract. This matches the Open UI datepicker `clear` concept: clearing is a text-editing action, not a component-owned affordance.
+
+## D5 — Time is a native companion, not picker state
+
+- Time fields are authored native `input[type=time]` marked `[data-time-start]` / `[data-time-end]`; `name`, `value`, `required`, `min`, `max`, `step` and submission stay native. There is no hidden time input and no time field controller.
+- `picker.value` / `picker.range` remain date-only (`YYYY-MM-DD`); the picker never constructs a datetime, a timestamp or a timezone-bearing value.
+- The picker only coordinates from/to order (`start <= end`, equality allowed); duration rules stay application-owned.
+- Custom time UI and slot picking stay outside the package.
+
+## D6 — Calendar interaction never produces an inverted range
+
+Pointing and typing are different contracts, deliberately.
+
+- **Interaction** (click, keyboard, endpoint drag) always yields an ordered range. While a range is being created, the second selection is sorted against the anchor: `10` then `5` commits `5 -> 10`, and `10` then `10` a one-day range. No `dateinvalid` is fired merely because the second point is earlier.
+- **Text entry** may be temporarily inverted. Typing `start` past `end` keeps both values and reports `rangeOrderStart` / `rangeOrderEnd` on the modified bound, because a half-typed pair is a normal editing state.
+- An explicit change to **one bound of an already complete pair** keeps that bound's identity: moving `end` before `start` is refused rather than silently rewriting the other field.
+- Because one interaction can move both bounds at once, a transition describes the whole resulting pair (`{ status, endpoint, changedEndpoints, range, activeEndpoint }`) and is applied in a single write: one `rangechange`, with synthetic `input` / `change` only on the bounds that actually moved.
+- Hover, keyboard focus and endpoint drag read the **same projection** (`previewRange()`) that the commit applies, so what the band promises is what the next selection commits. A preview writes nothing: no `rangechange`, no field write, no validation, no source request.
+- Click, keyboard and drop all end in that one range machine and in the same `ensureDate` plus cancelable `dateactivate` path, so an application veto cannot be bypassed by choosing another input device.
+
+## D7 — Author classes own header control styling
+
+`controlClasses` and `setDefaultControlClasses()` are the public hooks for styling the month, year and navigation roles with a host design system. A role with non-empty author classes receives no library skin, including in forced colors. Layout remains component-owned. Roles without author classes retain the default skin.
+
+The `.dp-*` namespace stays internal (D3); it is reserved and ignored in author class lists. Day grid cells and the picker trigger are outside this API. There is no HTML attribute.

package/docs/MIGRATION-FLATPICKR.md

@@ -1,6 +1,6 @@
 # Flatpickr / Formidable migration map
 
-This prototype was scoped against the existing `FlatpickrInput` wrapper rather than against Flatpickr's full feature list.
+This project was scoped against the existing `FlatpickrInput` wrapper rather than against Flatpickr's full feature list.
 
 ## Directly covered
 

package/docs/TESTING.md

@@ -68,6 +68,6 @@ Keep explicit tests for these regressions:
 
 ## CI
 
-The included workflow uses Bun 1.4.2 and runs static checks/unit tests before Playwright.
+The included workflow uses Bun 1.4.3 and runs static checks/unit tests before Playwright.
 
 `bun.lock` is committed. Keep installs frozen in CI (`bun install --frozen-lockfile`) so dependency resolution stays deterministic. Regenerate the lock with `bun install` when the manifest changes and commit it in the same change.

package/docs/USE_CASES.md

@@ -1,141 +1,156 @@
-# Use cases
-
-These cases define the product more strongly than a feature checklist. A proposed API change should be tested against them before being accepted.
-
-## U1 — Editable localized date field
-
-A user can type `06/09/2026` in `fr-BE`, open the calendar, select the same date visually, and submit `2026-09-06` to the server.
-
-Acceptance:
-
-- input remains editable;
-- label still targets the real input;
-- required/custom validity still works;
-- display formatting does not leak into submitted data.
-
-## U2 — Inline selector
-
-An inline calendar owns one selected date.
-
-Acceptance:
-
-- month/year navigation does not change the value;
-- arrow-key focus does not change the value;
-- click/Enter/Space activates and selects;
-- today, focused and selected are visually/semantically distinct.
-
-## U3 — Mini calendar navigator
-
-An inline `selection="none"` calendar navigates a separate agenda/calendar.
-
-Acceptance:
-
-- there may be no selected value at all;
-- changing month/year only changes what the mini calendar displays;
-- activating a date dispatches `dateactivate` and the application calls `calendarView.gotoDate(date)`;
-- outside-month days remain activatable;
-- six-row height is available as presentation, not baked into month math;
-- ISO week numbers are available;
-- a narrow/compact presentation can use short month names (`month-format="short"`).
-
-## U4 — Constrained dates
-
-Example: only the next 90 days, weekdays only.
-
-Acceptance:
-
-- min/max affect both activation and typed validation;
-- custom disabled days can still receive keyboard focus so the reason can be announced;
-- disabled activation never changes the value;
-- previous/next controls stop at bounded months.
-
-## U5 — Linked start/end dates
-
-Two fields represent a range.
-
-Acceptance:
-
-- end cannot validate before start;
-- start cannot validate after end;
-- changing one side revalidates the other;
-- the component never silently rewrites the sibling value;
-- each picker remains independently usable and replaceable.
-
-## U6 — Remote availability
-
-Changing the displayed month loads per-day state from a backend.
-
-Acceptance:
-
-- load receives the actual rendered range;
-- superseded navigation aborts the previous request;
-- state can disable a day or describe it;
-- loading logic is independent of URL/backend format;
-- a typed date can call `ensureDate()` before validation.
-
-## U7 — Morning / afternoon indicators
-
-A date can carry richer state such as morning/afternoon availability.
-
-Acceptance:
-
-- the business fields remain opaque to core logic;
-- visual badges/dots live inside the owned day cell;
-- accessible meaning is supplied through `description`;
-- custom rendering cannot replace focus/ARIA semantics.
-
-## U8 — Keyboard-only operation
-
-Everything above works without a pointing device.
-
-Acceptance:
-
-- one grid cell in the Tab sequence;
-- arrows, Home/End, PageUp/PageDown, Shift+PageUp/PageDown work;
-- changing display follows keyboard focus when focus crosses a month;
-- activation requires Enter/Space;
-- Escape closes the picker and restores a sensible focus target;
-- month/year selects remain normal native controls.
-
-## U9 — Two fields, one shared calendar
-
-A form has two editable date fields (arrival/departure) that share a single calendar surface inside one picker popup.
-
-Acceptance:
-
-- each field stays independently editable and localized, with its own hidden ISO value for submission;
-- opening from a bound targets that bound: selecting a first date commits it, moves the active endpoint to the other bound without closing, and a second selection commits and closes;
-- once an ordered range is complete, activating before it extends the start and activating after it extends the end, regardless of the opening field; the opposite bound stays unchanged and readonly/disabled bounds remain protected;
-- a preloaded range shows the band on open and is never reordered;
-- month/year navigation and arrow-key focus never mutate either bound;
-- an inverted range (start after end) keeps both entered values and surfaces an order error on the bound that was just modified; changing either side revalidates both;
-- form reset restores both fields in one resync;
-- a stale async availability response arriving after the active endpoint changed never commits a value or closes the popup;
-- only the bounds are validated; per-night availability stays application-owned.
-
-## U10 — Date with native time companions
-
-A form pairs a date with one or two native times (appointment at `09:30`, from/to on the same day).
-
-Acceptance:
-
-- times stay native `input[type=time]` fields with their own names and submission;
-- `value` stays a `YYYY-MM-DD` date;
-- an inverted from/to surfaces an order error on the modified bound;
-- a missing or disabled time lifts the order constraint;
-- calendar selection and form reset keep the entered times.
-
-## Not a use case for this package
-
-Do not grow the API to cover these without a separate design:
-
-- time slots;
-- duration picking;
-- timezone conversion;
-- appointment recurrence;
-- resource scheduling;
-- drag/drop;
-- event rendering;
-- multi-day scheduler views.
-
-Those belong to `@lekoala/calendar` or application logic.
+# Use cases
+
+These cases define the product more strongly than a feature checklist. A proposed API change should be tested against them before being accepted.
+
+## U1 — Editable localized date field
+
+A user can type `06/09/2026` in `fr-BE`, open the calendar, select the same date visually, and submit `2026-09-06` to the server.
+
+Acceptance:
+
+- input remains editable;
+- label still targets the real input;
+- required/custom validity still works;
+- display formatting does not leak into submitted data.
+
+## U2 — Inline selector
+
+An inline calendar owns one selected date.
+
+Acceptance:
+
+- month/year navigation does not change the value;
+- arrow-key focus does not change the value;
+- click/Enter/Space activates and selects;
+- today, focused and selected are visually/semantically distinct.
+
+## U3 — Mini calendar navigator
+
+An inline `selection="none"` calendar navigates a separate agenda/calendar.
+
+Acceptance:
+
+- there may be no selected value at all;
+- changing month/year only changes what the mini calendar displays;
+- activating a date dispatches `dateactivate` and the application calls `calendarView.gotoDate(date)`;
+- outside-month days remain activatable;
+- six-row height is available as presentation, not baked into month math;
+- ISO week numbers are available;
+- a narrow/compact presentation can use short month names (`month-format="short"`).
+
+## U4 — Constrained dates
+
+Example: only the next 90 days, weekdays only.
+
+Acceptance:
+
+- min/max affect both activation and typed validation;
+- custom disabled days can still receive keyboard focus so the reason can be announced;
+- disabled activation never changes the value;
+- previous/next controls stop at bounded months.
+
+## U5 — Linked start/end dates
+
+Two fields represent a range.
+
+Acceptance:
+
+- end cannot validate before start;
+- start cannot validate after end;
+- changing one side revalidates the other;
+- the component never silently rewrites the sibling value;
+- each picker remains independently usable and replaceable.
+
+## U6 — Remote availability
+
+Changing the displayed month loads per-day state from a backend.
+
+Acceptance:
+
+- load receives the actual rendered range;
+- superseded navigation aborts the previous request;
+- state can disable a day or describe it;
+- loading logic is independent of URL/backend format;
+- a typed date can call `ensureDate()` before validation.
+
+## U7 — Morning / afternoon indicators
+
+A date can carry richer state such as morning/afternoon availability.
+
+Acceptance:
+
+- the business fields remain opaque to core logic;
+- visual badges/dots live inside the owned day cell;
+- accessible meaning is supplied through `description`;
+- custom rendering cannot replace focus/ARIA semantics.
+
+## U8 — Keyboard-only operation
+
+Everything above works without a pointing device.
+
+Acceptance:
+
+- one grid cell in the Tab sequence;
+- arrows, Home/End, PageUp/PageDown, Shift+PageUp/PageDown work;
+- changing display follows keyboard focus when focus crosses a month;
+- activation requires Enter/Space;
+- Escape closes the picker and restores a sensible focus target;
+- month/year selects remain normal native controls.
+
+## U9 — Two fields, one shared calendar
+
+A form has two editable date fields (arrival/departure) that share a single calendar surface inside one picker popup.
+
+Acceptance:
+
+- each field stays independently editable and localized, with its own hidden ISO value for submission;
+- opening from a bound targets that bound: selecting a first date commits it, moves the active endpoint to the other bound without closing, and a second selection commits and closes;
+- once an ordered range is complete, activating before it extends the start and activating after it extends the end, regardless of the opening field; the opposite bound stays unchanged and readonly/disabled bounds remain protected;
+- a preloaded range shows the band on open and is never reordered;
+- month/year navigation and arrow-key focus never mutate either bound;
+- an inverted range (start after end) keeps both entered values and surfaces an order error on the bound that was just modified; changing either side revalidates both;
+- form reset restores both fields in one resync;
+- a stale async availability response arriving after the active endpoint changed never commits a value or closes the popup;
+- calendar interaction never produces an inverted range: while a range is being created, a second selection before the first is sorted (`10` then `5` commits `5 -> 10`) in one atomic update; an explicit change to one bound of an already complete pair keeps that bound's identity instead;
+- pointer hover and keyboard navigation project the range the next selection would commit onto the band, without changing any value, and a selection commits exactly what was projected;
+- the endpoints of a complete range can be dragged to adjust it, through the same projection, the same availability check and the same cancelable activation as a click;
+- only the bounds are validated; per-night availability stays application-owned.
+
+## U10 — Date with native time companions
+
+A form pairs a date with one or two native times (appointment at `09:30`, from/to on the same day).
+
+Acceptance:
+
+- times stay native `input[type=time]` fields with their own names and submission;
+- `value` stays a `YYYY-MM-DD` date;
+- an inverted from/to surfaces an order error on the modified bound;
+- a missing or disabled time lifts the order constraint;
+- calendar selection and form reset keep the entered times.
+
+## U11 — Host design system controls
+
+The calendar header uses application-owned control classes without styling internal `.dp-*` selectors.
+
+Acceptance:
+
+- author classes survive every render;
+- the library applies no border, background, caret, padding, hover, disabled or focus skin to a role with author classes;
+- controls stretch to equal heights, the year keeps its grid-track width and long month names truncate;
+- labels, keyboard navigation and focus restoration are unchanged;
+- controls without author classes keep the default skin.
+
+## Not a use case for this package
+
+Do not grow the API to cover these without a separate design:
+
+- time slots;
+- duration picking;
+- timezone conversion;
+- appointment recurrence;
+- resource scheduling;
+- drag/drop;
+- event rendering;
+- multi-day scheduler views.
+
+Those belong to `@lekoala/calendar` or application logic.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lekoala/date-picker",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Native-first date picker and inline calendar primitives",
   "type": "module",
   "sideEffects": [
@@ -20,7 +20,7 @@
   },
   "homepage": "https://github.com/lekoala/date-picker",
   "bugs": "https://github.com/lekoala/date-picker/issues",
-  "packageManager": "bun@1.4.2",
+  "packageManager": "bun@1.4.3",
   "keywords": [
     "date-picker",
     "calendar",
@@ -143,7 +143,7 @@
     "typecheck": "tsc -p jsconfig.json",
     "types": "tsc -p tsconfig.types.json",
     "test": "bun test test/unit",
-    "test:syntax": "node --check src/date.js && node --check src/intl.js && node --check src/calendar-model.js && node --check src/source.js && node --check src/messages.js && node --check src/date-calendar.js && node --check src/date-field.js && node --check src/date-picker.js && node --check src/date-range.js && node --check src/time.js && node --check src/index.js && node --check src/define.js",
+    "test:syntax": "node --check src/date.js && node --check src/intl.js && node --check src/calendar-model.js && node --check src/source.js && node --check src/messages.js && node --check src/control-classes.js && node --check src/date-calendar.js && node --check src/date-field.js && node --check src/date-picker.js && node --check src/date-range.js && node --check src/time.js && node --check src/index.js && node --check src/define.js",
     "test:types": "tsc -p test/types/tsconfig.json",
     "test:browser": "playwright test browser --project chromium",
     "test:browser:accessibility": "playwright test test/browser/picker.spec.js test/browser/focus.spec.js test/browser/calendar.spec.js test/browser/form-state.spec.js test/browser/surfaces.spec.js",
@@ -162,13 +162,13 @@
     "prepublishOnly": "bun run verify"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.13",
-    "@lekoala/calendar": "0.1.0",
-    "@playwright/test": "1.63.0",
-    "temporal-polyfill": "^1.0.4",
+    "@biomejs/biome": "2.5.15",
+    "@lekoala/calendar": "0.2.0",
+    "@playwright/test": "1.64.0",
+    "temporal-polyfill": "^1.0.5",
     "typescript": "7.0.2"
   },
   "dependencies": {
-    "@lekoala/floating": "^0.2.0"
+    "@lekoala/floating": "^0.3.1"
   }
 }

package/src/control-classes.js

@@ -0,0 +1,50 @@
+/** @typedef {{ month: string, year: string, nav: string }} ControlClasses */
+
+/**
+ * Normalize author class tokens. The dp-* namespace belongs to the component.
+ * @param {unknown} value
+ */
+export function normalizeControlClass(value) {
+  if (typeof value !== "string") return "";
+  return [
+    ...new Set(
+      value
+        .split(/\s+/)
+        .filter(
+          (token) =>
+            token &&
+            !token.startsWith("dp-") &&
+            ![...token].some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127),
+        ),
+    ),
+  ].join(" ");
+}
+
+/** @param {ControlClasses} a @param {ControlClasses} b */
+export function sameControlClasses(a, b) {
+  return a.month === b.month && a.year === b.year && a.nav === b.nav;
+}
+
+/** @type {ControlClasses} */
+let defaults = { month: "", year: "", nav: "" };
+
+export function getDefaultControlClasses() {
+  return { ...defaults };
+}
+
+/** @param {Partial<ControlClasses> | null} classes */
+export function resolveControlClasses(classes) {
+  const result = getDefaultControlClasses();
+  for (const role of /** @type {const} */ (["month", "year", "nav"])) {
+    if (classes && Object.hasOwn(classes, role)) result[role] = normalizeControlClass(classes[role]);
+  }
+  return result;
+}
+
+/**
+ * Set defaults for subsequently created elements (existing elements are unchanged).
+ * @param {Partial<ControlClasses>} classes
+ */
+export function setDefaultControlClasses(classes) {
+  defaults = resolveControlClasses(classes);
+}