@colixsystems/widget-sdk 0.234.0 → 0.235.0

package/README.md

@@ -84,7 +84,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.234.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.235.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.235.0 (contract 1.190.0)
+
+**`<DateTimePicker>` is a themed field with its own calendar on the web.** The web build rendered the browser's `<input type="date">`, whose popup cannot be styled: it ignored the workspace theme and looked out of place in every app. Both hosts now render one shared field — a calendar (or clock) icon, the value in the app user's language (`1 okt. 2026`, `Oct 1, 2026, 2:30 PM`) and a clear button. On the web it opens a calendar sheet in `<Overlay>`, painted from the theme: a month grid with the chosen day in `colors.primary` and today ringed, weeks starting on the locale's first day, a month and year jump for far dates, hour and minute columns for `time` and `datetime`, and a Today / Now button. The grid is keyboard-driven (arrows, Home/End, PageUp/PageDown, Space/Enter) and `minimumDate` / `maximumDate` disable what lies outside them. Native keeps the operating system's picker behind the same field. The value contract is unchanged; new optional props: `placeholder`, `clearLabel`, `doneLabel`, `closeAccessibilityLabel` and `testID`. `formatDateTimeLabel` from `/host` takes an optional `locale` and now returns that localised label.
 
 ### What's new in 0.234.0 (contract 1.189.0)
 

package/dist/contract.cjs

@@ -3123,7 +3123,7 @@ const PRIMITIVES = [
   {
     name: "DateTimePicker",
     description:
-      'Cross-platform date / time / datetime picker. `<DateTimePicker value={iso} onChange={iso => …} mode="date" | "time" | "datetime" />`. The value prop and the onChange callback both speak ISO 8601 strings (the datastore wire format) — authors never round-trip through `new Date()`. Web renders the browser\'s native `<input type="date|time|datetime-local">` directly (react-native-web has no mapping for the RN datetimepicker library); native uses @react-native-community/datetimepicker. The field themes itself from the workspace theme — text uses `colors.onSurface`, the border `colors.border`, and on web `color-scheme` follows the theme so the browser\'s built-in date UI stays legible on a dark surface; never style it with raw CSS or `document`.',
+      'Cross-platform date / time / datetime field. `<DateTimePicker value={iso} onChange={iso => …} mode="date" | "time" | "datetime" accessibilityLabel="Due" />`. The value prop and the onChange callback both speak ISO 8601 strings (the datastore wire format): `YYYY-MM-DD` for date, `HH:mm` for time, a full UTC instant for datetime — authors never round-trip through `new Date()`. Clearing emits "". The field shows the value in the app user\'s language beside a calendar (or clock) icon, with a clear button once it holds a value. Web opens a themed calendar sheet in `<Overlay>`: a month grid (keyboard: arrows, Home/End, PageUp/PageDown), a month and year jump, hour and minute columns for time, and a Today / Now button. Native opens the operating system\'s own picker (@react-native-community/datetimepicker). `minimumDate` / `maximumDate` (ISO, `HH:mm` in time mode) bound what can be picked; `disabled` locks the field. Optional copy: `placeholder`, `clearLabel` (default "Clear"), `doneLabel` (default "Done", closes the web time sheet), `closeAccessibilityLabel`; `testID` names the field. Colours come from the workspace theme — the field from the text-field tokens, the sheet from the popover scope, the chosen day from `colors.primary`; never style it with raw CSS or `document`.',
     rnComponent: "@react-native-community/datetimepicker",
     docsUrl: "https://github.com/react-native-datetimepicker/datetimepicker",
   },
@@ -6049,7 +6049,11 @@ const CONTRACT = deepFreeze({
   // 1.189.0: additive (sc-11703) — `resolveFooterTokens` gains `padding`,
   //    the space around a bottom bar's tabs (0–12, default 4); `FOOTER_SIZES`
   //    gains its bound.
-  version: "1.189.0",
+  // 1.190.0: additive (sc-11777) — `<DateTimePicker>` on web opens a themed
+  //    calendar sheet instead of the browser's date popup; both hosts show
+  //    the value in the app's language with a clear button. New optional
+  //    props: placeholder, clearLabel, doneLabel, closeAccessibilityLabel, testID.
+  version: "1.190.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -3123,7 +3123,7 @@ const PRIMITIVES = [
   {
     name: "DateTimePicker",
     description:
-      'Cross-platform date / time / datetime picker. `<DateTimePicker value={iso} onChange={iso => …} mode="date" | "time" | "datetime" />`. The value prop and the onChange callback both speak ISO 8601 strings (the datastore wire format) — authors never round-trip through `new Date()`. Web renders the browser\'s native `<input type="date|time|datetime-local">` directly (react-native-web has no mapping for the RN datetimepicker library); native uses @react-native-community/datetimepicker. The field themes itself from the workspace theme — text uses `colors.onSurface`, the border `colors.border`, and on web `color-scheme` follows the theme so the browser\'s built-in date UI stays legible on a dark surface; never style it with raw CSS or `document`.',
+      'Cross-platform date / time / datetime field. `<DateTimePicker value={iso} onChange={iso => …} mode="date" | "time" | "datetime" accessibilityLabel="Due" />`. The value prop and the onChange callback both speak ISO 8601 strings (the datastore wire format): `YYYY-MM-DD` for date, `HH:mm` for time, a full UTC instant for datetime — authors never round-trip through `new Date()`. Clearing emits "". The field shows the value in the app user\'s language beside a calendar (or clock) icon, with a clear button once it holds a value. Web opens a themed calendar sheet in `<Overlay>`: a month grid (keyboard: arrows, Home/End, PageUp/PageDown), a month and year jump, hour and minute columns for time, and a Today / Now button. Native opens the operating system\'s own picker (@react-native-community/datetimepicker). `minimumDate` / `maximumDate` (ISO, `HH:mm` in time mode) bound what can be picked; `disabled` locks the field. Optional copy: `placeholder`, `clearLabel` (default "Clear"), `doneLabel` (default "Done", closes the web time sheet), `closeAccessibilityLabel`; `testID` names the field. Colours come from the workspace theme — the field from the text-field tokens, the sheet from the popover scope, the chosen day from `colors.primary`; never style it with raw CSS or `document`.',
     rnComponent: "@react-native-community/datetimepicker",
     docsUrl: "https://github.com/react-native-datetimepicker/datetimepicker",
   },
@@ -6045,7 +6045,11 @@ const CONTRACT = deepFreeze({
   // 1.189.0: additive (sc-11703) — `resolveFooterTokens` gains `padding`,
   //    the space around a bottom bar's tabs (0–12, default 4); `FOOTER_SIZES`
   //    gains its bound.
-  version: "1.189.0",
+  // 1.190.0: additive (sc-11777) — `<DateTimePicker>` on web opens a themed
+  //    calendar sheet instead of the browser's date popup; both hosts show
+  //    the value in the app's language with a clear button. New optional
+  //    props: placeholder, clearLabel, doneLabel, closeAccessibilityLabel, testID.
+  version: "1.190.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/datetimepicker-calendar.js

@@ -0,0 +1,225 @@
+// REQ-WSDK-PLATFORM §6 — the calendar behind the `<DateTimePicker>`: which
+// days a month shows, which may be picked, and where the keyboard moves.
+// Pure, so it is unit-tested without a renderer. Names live in
+// ./datetimepicker-names.js.
+
+import { normaliseMode, valueToParts } from "./datetimepicker-format.js";
+
+export const WEEK_LENGTH = 7;
+// Six rows hold every month, so the sheet never changes height while paging.
+export const GRID_ROWS = 6;
+export const YEARS_PER_PAGE = 12;
+// `Date` reads years 0–99 as 1900–1999, so the calendar stops before them.
+export const MIN_YEAR = 1000;
+
+// CLDR regions whose week starts on Sunday; Monday is the default elsewhere.
+const SUNDAY_FIRST_REGIONS = new Set([
+  "AG", "AS", "BD", "BR", "BS", "BT", "BW", "BZ", "CA", "CO", "DM", "DO", "ET",
+  "GT", "GU", "HK", "HN", "ID", "IL", "IN", "JM", "JP", "KE", "KH", "KR", "LA",
+  "MH", "MM", "MO", "MT", "MX", "MZ", "NI", "NP", "PA", "PE", "PH", "PK", "PR",
+  "PT", "PY", "SA", "SG", "SV", "TH", "TT", "TW", "UM", "US", "VE", "VI", "WS",
+  "YE", "ZA", "ZW",
+]);
+const SATURDAY_FIRST_REGIONS = new Set(["AE", "AF", "BH", "DJ", "DZ", "EG", "IQ", "IR", "JO", "KW", "LY", "OM", "QA", "SD", "SY"]);
+
+function deviceLocale() {
+  try {
+    return new Intl.DateTimeFormat().resolvedOptions().locale;
+  } catch {
+    return undefined;
+  }
+}
+
+function localeRegion(locale) {
+  try {
+    const resolved = new Intl.Locale(locale || deviceLocale());
+    const maximised = typeof resolved.maximize === "function" ? resolved.maximize() : resolved;
+    return maximised.region || null;
+  } catch {
+    return null;
+  }
+}
+
+/** The weekday a week starts on in this locale: 0 Sunday … 6 Saturday. */
+export function firstDayOfWeek(locale) {
+  try {
+    const intlLocale = new Intl.Locale(locale || deviceLocale());
+    const info =
+      typeof intlLocale.getWeekInfo === "function" ? intlLocale.getWeekInfo() : intlLocale.weekInfo;
+    // Intl counts Monday 1 … Sunday 7.
+    if (info && Number.isInteger(info.firstDay)) return info.firstDay % WEEK_LENGTH;
+  } catch {
+    // An engine without Intl.Locale falls through to the region table.
+  }
+  const region = localeRegion(locale);
+  if (region && SUNDAY_FIRST_REGIONS.has(region)) return 0;
+  if (region && SATURDAY_FIRST_REGIONS.has(region)) return 6;
+  return 1;
+}
+
+/**
+ * The locale the picker names dates in: the app's language, refined by the
+ * device's region when they share a language (`sv` + `sv-FI` → `sv-FI`), so
+ * a week starts where the viewer expects it to.
+ */
+export function resolvePickerLocale(appLocale) {
+  const device = deviceLocale();
+  if (!appLocale) return device;
+  const language = (tag) => String(tag || "").split("-")[0].toLowerCase();
+  if (!String(appLocale).includes("-") && device && language(device) === language(appLocale)) return device;
+  return appLocale;
+}
+
+export function dayKey({ year, month, day }) {
+  return year * 10000 + (month + 1) * 100 + day;
+}
+
+function minuteKey(parts) {
+  return dayKey(parts) * 10000 + parts.hours * 100 + parts.minutes;
+}
+
+export function daysInMonth(year, month) {
+  return new Date(year, month + 1, 0).getDate();
+}
+
+/**
+ * The days a month's grid shows, as `GRID_ROWS` weeks of `WEEK_LENGTH` days.
+ * Days of the neighbouring months fill the edges, flagged `outside`.
+ */
+export function monthGrid(year, month, weekStart) {
+  const leading = (new Date(year, month, 1).getDay() - weekStart + WEEK_LENGTH) % WEEK_LENGTH;
+  const weeks = [];
+  for (let row = 0; row < GRID_ROWS; row += 1) {
+    const week = [];
+    for (let column = 0; column < WEEK_LENGTH; column += 1) {
+      const date = new Date(year, month, row * WEEK_LENGTH + column - leading + 1);
+      week.push({
+        year: date.getFullYear(),
+        month: date.getMonth(),
+        day: date.getDate(),
+        outside: date.getMonth() !== month,
+      });
+    }
+    weeks.push(week);
+  }
+  return weeks;
+}
+
+/**
+ * The picker's `minimumDate` / `maximumDate` as comparable local bounds.
+ * In time mode they bound the time of day; otherwise the moment.
+ */
+export function resolveBounds(minimumDate, maximumDate, mode) {
+  const effectiveMode = normaliseMode(mode);
+  const read = (value) => (value == null || value === "" ? null : valueToParts(value, effectiveMode));
+  return { mode: effectiveMode, min: read(minimumDate), max: read(maximumDate) };
+}
+
+export function isYearAllowed(year, bounds) {
+  if (bounds.mode === "time") return true;
+  if (year < MIN_YEAR) return false;
+  if (bounds.min && year < bounds.min.year) return false;
+  if (bounds.max && year > bounds.max.year) return false;
+  return true;
+}
+
+export function isMonthAllowed(year, month, bounds) {
+  if (!isYearAllowed(year, bounds)) return false;
+  if (bounds.mode === "time") return true;
+  const first = { year, month, day: 1 };
+  const last = { year, month, day: daysInMonth(year, month) };
+  if (bounds.min && dayKey(last) < dayKey(bounds.min)) return false;
+  if (bounds.max && dayKey(first) > dayKey(bounds.max)) return false;
+  return true;
+}
+
+export function isDayAllowed(day, bounds) {
+  if (bounds.mode === "time") return true;
+  if (!isYearAllowed(day.year, bounds)) return false;
+  const key = dayKey(day);
+  if (bounds.min && key < dayKey(bounds.min)) return false;
+  if (bounds.max && key > dayKey(bounds.max)) return false;
+  return true;
+}
+
+// A time of day as one comparable number; in datetime mode, on `day`.
+function timeKey(day, hours, minutes, bounds) {
+  return bounds.mode === "time" ? hours * 100 + minutes : minuteKey({ ...day, hours, minutes });
+}
+
+function edgeKey(edge, bounds) {
+  if (!edge) return null;
+  return bounds.mode === "time" ? edge.hours * 100 + edge.minutes : minuteKey(edge);
+}
+
+// Whether any moment between `from` and `to` ([hours, minutes]) is in bounds.
+function spanAllowed(day, from, to, bounds) {
+  if (bounds.mode === "date" || (bounds.mode === "datetime" && !day)) return true;
+  const min = edgeKey(bounds.min, bounds);
+  const max = edgeKey(bounds.max, bounds);
+  if (min != null && timeKey(day, to[0], to[1], bounds) < min) return false;
+  if (max != null && timeKey(day, from[0], from[1], bounds) > max) return false;
+  return true;
+}
+
+/** Whether `hours:minutes` may be picked on `day` (ignored in time mode). */
+export function isTimeAllowed(day, hours, minutes, bounds) {
+  return spanAllowed(day, [hours, minutes], [hours, minutes], bounds);
+}
+
+/** Whether any minute of `hours` may be picked, so the hour is worth offering. */
+export function isHourAllowed(day, hours, bounds) {
+  return spanAllowed(day, [hours, 0], [hours, 59], bounds);
+}
+
+/** Pull a candidate inside the picker's bounds, so a pick never leaves them. */
+export function clampToBounds(parts, bounds) {
+  const key = bounds.mode === "time" ? parts.hours * 100 + parts.minutes : minuteKey(parts);
+  const min = edgeKey(bounds.min, bounds);
+  const max = edgeKey(bounds.max, bounds);
+  const edge = min != null && key < min ? bounds.min : max != null && key > max ? bounds.max : null;
+  if (!edge) return parts;
+  if (bounds.mode === "time") return { ...parts, hours: edge.hours, minutes: edge.minutes };
+  return { ...edge };
+}
+
+/** The allowed day of a month nearest to `preferred`, so focus has a home. */
+export function nearestAllowedDay({ year, month }, preferred, bounds) {
+  const last = daysInMonth(year, month);
+  const start = Math.min(preferred, last);
+  for (let offset = 0; offset < last; offset += 1) {
+    for (const day of [start - offset, start + offset]) {
+      if (day >= 1 && day <= last && isDayAllowed({ year, month, day }, bounds)) return { year, month, day };
+    }
+  }
+  return { year, month, day: start };
+}
+
+export function shiftMonth({ year, month }, delta) {
+  const d = new Date(year, month + delta, 1);
+  return { year: d.getFullYear(), month: d.getMonth() };
+}
+
+/** The day a calendar key moves focus to, or null for a key it ignores. */
+export function moveDay(day, key, { shiftKey = false, weekStart = 1 } = {}) {
+  const date = new Date(day.year, day.month, day.day);
+  const weekday = (date.getDay() - weekStart + WEEK_LENGTH) % WEEK_LENGTH;
+  const byDays = {
+    ArrowLeft: -1,
+    ArrowRight: 1,
+    ArrowUp: -WEEK_LENGTH,
+    ArrowDown: WEEK_LENGTH,
+    Home: -weekday,
+    End: WEEK_LENGTH - 1 - weekday,
+  };
+  if (key in byDays) {
+    date.setDate(date.getDate() + byDays[key]);
+  } else if (key === "PageUp" || key === "PageDown") {
+    const months = (key === "PageUp" ? -1 : 1) * (shiftKey ? 12 : 1);
+    const target = shiftMonth(day, months);
+    return { ...target, day: Math.min(day.day, daysInMonth(target.year, target.month)) };
+  } else {
+    return null;
+  }
+  return { year: date.getFullYear(), month: date.getMonth(), day: date.getDate() };
+}

package/dist/datetimepicker-cells.js

@@ -0,0 +1,71 @@
+// REQ-WSDK-PLATFORM §6 — what every pickable cell of the web
+// `<DateTimePicker>` sheet shares: its look, and how keyboard focus reaches it.
+
+import React from "react";
+
+// Seven of them fit a 360px phone inside the sheet's padding.
+export const CELL_SIZE = 40;
+
+/**
+ * The look of one pickable cell: the accent fills the chosen one, a ring
+ * marks today, and the pointer and keyboard each get a visible state.
+ */
+export function cellStyle(t, { selected, current, disabled, width, height, round }) {
+  return ({ pressed, hovered, focused }) => [
+    {
+      width,
+      height,
+      alignItems: "center",
+      justifyContent: "center",
+      borderRadius: round ? height / 2 : t.radius,
+      borderWidth: 1,
+      borderColor: current && !selected ? t.accent : "transparent",
+      backgroundColor: selected ? t.accent : hovered && !disabled ? t.background : "transparent",
+      outlineColor: "transparent",
+    },
+    focused ? { boxShadow: `0 0 0 2px ${t.focusColor}` } : null,
+    pressed && !disabled ? { opacity: 0.75 } : null,
+    disabled ? { opacity: t.disabledOpacity } : null,
+  ];
+}
+
+export function cellText(t, { selected, current, muted }) {
+  return {
+    fontFamily: t.fontFamily,
+    fontSize: t.labelSize,
+    fontVariant: ["tabular-nums"],
+    fontWeight: selected || current ? "600" : "400",
+    color: selected ? t.onAccent : current ? t.accent : muted ? t.helperColor : t.popover.textColor,
+  };
+}
+
+/** Keyboard focus helpers, bound to one platform. Focus is a web concern. */
+export function makeFocus(Platform) {
+  function focusNode(node) {
+    if (Platform.OS === "web" && node && typeof node.focus === "function") node.focus();
+  }
+
+  // Moves DOM focus whenever the sheet bumps `request`, and once on mount.
+  function useFocusOn(request, nodes, key) {
+    React.useEffect(() => {
+      if (request > 0) focusNode(nodes.current.get(key));
+    }, [request]); // eslint-disable-line react-hooks/exhaustive-deps
+  }
+
+  /**
+   * One tab stop for a set of cells, following the arrow keys: `fallback`
+   * holds it until the keyboard moves it, and again once it leaves `keys`.
+   */
+  function useRovingStop(fallback, keys) {
+    const [moved, setMoved] = React.useState(null);
+    const stop = moved != null && keys.includes(moved) ? moved : fallback;
+    return [stop, setMoved];
+  }
+
+  return { focusNode, useFocusOn, useRovingStop };
+}
+
+/** A ref callback that files each mounted cell under `key`. */
+export function register(nodes, key) {
+  return (node) => (node ? nodes.current.set(key, node) : nodes.current.delete(key));
+}

package/dist/datetimepicker-format.js

@@ -1,28 +1,17 @@
 // REQ-WSDK-PLATFORM §6 — pure, RN-free helpers for the `<DateTimePicker>`.
 //
-// Split out of the primitive so the formatting + theming contract can be
-// unit-tested without importing react-native / the RN datetimepicker library
-// (neither is installed in this package's node tree). No React, no RN here —
-// just Date math, string shaping, and a colour-luminance test.
+// Split out of the primitive so the ISO and label contract can be unit-tested
+// without a renderer. No React, no RN here — just Date math and Intl.
 
-export function parseToDate(value) {
-  if (value == null || value === "") return new Date();
-  if (value instanceof Date) return Number.isNaN(value.getTime()) ? new Date() : value;
-  if (typeof value === "string") {
-    const d = new Date(value);
-    return Number.isNaN(d.getTime()) ? new Date() : d;
-  }
-  return new Date();
-}
-
-const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+const DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})/;
+const TIME_ONLY = /^(\d{2}):(\d{2})/;
 
 // A stored DATETIME instant → `<input type="datetime-local">`'s
 // `YYYY-MM-DDTHH:mm` on the viewer's local clock. A bare calendar date is
 // local midnight, not UTC midnight, so it never slips a day west of Greenwich.
 export function isoToDateTimeLocalInput(value) {
   if (value == null || value === "") return "";
-  if (typeof value === "string" && DATE_ONLY.test(value)) return `${value}T00:00`;
+  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value)) return `${value}T00:00`;
   const d = new Date(value);
   if (Number.isNaN(d.getTime())) return "";
   return `${formatToIso(d, "date")}T${formatToIso(d, "time")}`;
@@ -39,15 +28,13 @@ export function dateTimeLocalInputToIso(raw) {
 export function formatToIso(date, mode) {
   if (!(date instanceof Date) || Number.isNaN(date.getTime())) return null;
   if (mode === "date") {
-    // Local-date ISO (yyyy-mm-dd) — calendar dates are timezone-free so a
-    // "May 28" picked in Stockholm doesn't read as "May 27" in NYC.
+    // Calendar dates are timezone-free: May 28 in Stockholm stays May 28 in NYC.
     const y = String(date.getFullYear()).padStart(4, "0");
     const m = String(date.getMonth() + 1).padStart(2, "0");
     const d = String(date.getDate()).padStart(2, "0");
     return `${y}-${m}-${d}`;
   }
   if (mode === "time") {
-    // Local-time ISO (hh:mm) — time-of-day is timezone-free for the same reason.
     const h = String(date.getHours()).padStart(2, "0");
     const mm = String(date.getMinutes()).padStart(2, "0");
     return `${h}:${mm}`;
@@ -56,36 +43,111 @@ export function formatToIso(date, mode) {
   return date.toISOString();
 }
 
-// The label shown on the tappable trigger. Empty value → a mode-specific
-// placeholder so the field reads as "tap to pick" rather than blank.
-export function formatDisplayLabel(value, mode) {
-  const effectiveMode = mode === "time" || mode === "datetime" ? mode : "date";
+export function normaliseMode(mode) {
+  return mode === "time" || mode === "datetime" ? mode : "date";
+}
+
+/**
+ * A stored value as the local wall-clock parts the picker edits, or null when
+ * it is empty or unreadable. `month` is 0-based, as `Date` counts it.
+ *
+ * @returns {{year: number, month: number, day: number, hours: number, minutes: number} | null}
+ */
+export function valueToParts(value, mode) {
+  if (value == null || value === "") return null;
+  const text = String(value);
+  const effectiveMode = normaliseMode(mode);
+  if (effectiveMode === "time") {
+    const match = TIME_ONLY.exec(text);
+    if (!match) return null;
+    const hours = Number(match[1]);
+    const minutes = Number(match[2]);
+    if (hours > 23 || minutes > 59) return null;
+    return { year: null, month: null, day: null, hours, minutes };
+  }
+  // A date column holds a calendar date, never an instant: read its head as is.
+  const dateOnly = DATE_ONLY.exec(text);
+  if (effectiveMode === "date" || (dateOnly && text.length === 10)) {
+    if (!dateOnly) return null;
+    return checkedParts(Number(dateOnly[1]), Number(dateOnly[2]) - 1, Number(dateOnly[3]), 0, 0);
+  }
+  const d = new Date(text);
+  if (Number.isNaN(d.getTime())) return null;
+  return {
+    year: d.getFullYear(),
+    month: d.getMonth(),
+    day: d.getDate(),
+    hours: d.getHours(),
+    minutes: d.getMinutes(),
+  };
+}
+
+function checkedParts(year, month, day, hours, minutes) {
+  const d = new Date(year, month, day, hours, minutes);
+  if (d.getFullYear() !== year || d.getMonth() !== month || d.getDate() !== day) return null;
+  return { year, month, day, hours, minutes };
+}
+
+export function partsToDate(parts) {
+  return new Date(parts.year, parts.month, parts.day, parts.hours || 0, parts.minutes || 0);
+}
+
+/** The ISO string the picker emits for local parts, in its mode's wire shape. */
+export function partsToIso(parts, mode) {
+  const effectiveMode = normaliseMode(mode);
+  if (!parts) return "";
+  if (effectiveMode === "time") {
+    return formatToIso(new Date(2000, 0, 1, parts.hours, parts.minutes), "time");
+  }
+  return formatToIso(partsToDate(parts), effectiveMode) || "";
+}
+
+export function nowParts(now = new Date()) {
+  return {
+    year: now.getFullYear(),
+    month: now.getMonth(),
+    day: now.getDate(),
+    hours: now.getHours(),
+    minutes: now.getMinutes(),
+  };
+}
+
+// Hermes ships a partial Intl; any refusal falls back to the ISO shape.
+function intlFormat(locale, options, date) {
+  try {
+    return new Intl.DateTimeFormat(locale || undefined, options).format(date);
+  } catch {
+    return null;
+  }
+}
+
+const DATE_LABEL = { year: "numeric", month: "short", day: "numeric" };
+const TIME_LABEL = { hour: "2-digit", minute: "2-digit" };
+
+/**
+ * The text on the picker's field: the value in the viewer's language
+ * (`28 maj 2026`, `May 28, 2026, 2:30 PM`), or a mode-specific placeholder
+ * when empty. An unreadable value is shown as stored rather than hidden.
+ */
+export function formatDisplayLabel(value, mode, locale) {
+  const effectiveMode = normaliseMode(mode);
   if (value == null || value === "") {
     if (effectiveMode === "time") return "Select time";
     if (effectiveMode === "datetime") return "Select date & time";
     return "Select date";
   }
-  if (effectiveMode === "date") return String(value).slice(0, 10);
-  if (effectiveMode === "time") return String(value).slice(0, 5);
-  const local = isoToDateTimeLocalInput(value);
-  return local ? local.replace("T", " ") : String(value);
-}
-
-// Perceived-luminance test for a hex colour (`#rgb` or `#rrggbb`). The web
-// picker uses it to choose a matching `color-scheme` so the browser's built-in
-// date UI (edit segments + calendar icon) stays legible on a dark themed
-// surface. Anything unparseable is treated as light so a light theme is never
-// darkened.
-export function isDarkColor(hex) {
-  if (typeof hex !== "string") return false;
-  let h = hex.trim().replace(/^#/, "");
-  if (h.length === 3) {
-    h = h.split("").map((c) => c + c).join("");
+  const parts = valueToParts(value, effectiveMode);
+  if (!parts) return String(value);
+  if (effectiveMode === "time") {
+    const date = new Date(2000, 0, 1, parts.hours, parts.minutes);
+    return intlFormat(locale, TIME_LABEL, date) || formatToIso(date, "time");
+  }
+  const date = partsToDate(parts);
+  if (effectiveMode === "date") {
+    return intlFormat(locale, DATE_LABEL, date) || formatToIso(date, "date");
   }
-  if (h.length !== 6 || /[^0-9a-fA-F]/.test(h)) return false;
-  const r = parseInt(h.slice(0, 2), 16);
-  const g = parseInt(h.slice(2, 4), 16);
-  const b = parseInt(h.slice(4, 6), 16);
-  const luminance = (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
-  return luminance < 0.5;
+  return (
+    intlFormat(locale, { ...DATE_LABEL, ...TIME_LABEL }, date) ||
+    `${formatToIso(date, "date")} ${formatToIso(date, "time")}`
+  );
 }

package/dist/datetimepicker-names.js

@@ -0,0 +1,99 @@
+// REQ-WSDK-PLATFORM §6 — the names the web `<DateTimePicker>` sheet shows,
+// in the viewer's language through Intl, with English when an engine refuses.
+
+import { normaliseMode, partsToDate } from "./datetimepicker-format.js";
+import { WEEK_LENGTH } from "./datetimepicker-calendar.js";
+
+const ENGLISH_MONTHS = [
+  "January", "February", "March", "April", "May", "June",
+  "July", "August", "September", "October", "November", "December",
+];
+const ENGLISH_WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+// Latin, Greek and Cyrillic: short weekdays vary in length (`Mån`, `Tors`), so
+// they read evenly as two letters. Ranges, as Hermes lacks `\p{Script}`.
+const ALPHABETIC = /^[A-Za-zÀ-ɏͰ-ϿЀ-ӿ]/;
+
+function intlFormat(locale, options, date) {
+  try {
+    return new Intl.DateTimeFormat(locale || undefined, options).format(date);
+  } catch {
+    return null;
+  }
+}
+
+function capitalise(text, locale) {
+  if (!text) return text;
+  try {
+    return text.charAt(0).toLocaleUpperCase(locale || undefined) + text.slice(1);
+  } catch {
+    return text.charAt(0).toUpperCase() + text.slice(1);
+  }
+}
+
+/** `October 2026` / `Oktober 2026` — the heading over a month's days. */
+export function monthTitle(year, month, locale) {
+  const text = intlFormat(locale, { month: "long", year: "numeric" }, new Date(year, month, 1));
+  return capitalise(text, locale) || `${ENGLISH_MONTHS[month]} ${year}`;
+}
+
+/** The twelve month names, short (`Jan`) or long (`January`). */
+export function monthNames(locale, width = "short") {
+  return ENGLISH_MONTHS.map((english, month) => {
+    const text = intlFormat(locale, { month: width }, new Date(2000, month, 1));
+    if (!text) return width === "short" ? english.slice(0, 3) : english;
+    return capitalise(text.replace(/\.$/, ""), locale);
+  });
+}
+
+/** Column headings in week order, short (`Mo`) with the long name to speak. */
+export function weekdayHeadings(locale, weekStart) {
+  const headings = [];
+  for (let index = 0; index < WEEK_LENGTH; index += 1) {
+    const weekday = (weekStart + index) % WEEK_LENGTH;
+    // 2023-01-01 was a Sunday.
+    const date = new Date(2023, 0, 1 + weekday);
+    const short = capitalise(intlFormat(locale, { weekday: "short" }, date), locale) || ENGLISH_WEEKDAYS[weekday];
+    headings.push({
+      short: ALPHABETIC.test(short) ? short.slice(0, 2) : short,
+      long: intlFormat(locale, { weekday: "long" }, date) || ENGLISH_WEEKDAYS[weekday],
+    });
+  }
+  return headings;
+}
+
+/** A day's full spoken name: `Thursday, October 1, 2026`. */
+export function dayLabel(day, locale) {
+  return (
+    intlFormat(
+      locale,
+      { weekday: "long", year: "numeric", month: "long", day: "numeric" },
+      partsToDate({ ...day, hours: 0, minutes: 0 }),
+    ) || `${day.year}-${twoDigits(day.month + 1)}-${twoDigits(day.day)}`
+  );
+}
+
+/** `Today` / `I dag`, or `Now` / `Nu` for a time, in the viewer's language. */
+export function relativeNowLabel(locale, mode) {
+  const unit = normaliseMode(mode) === "date" ? "day" : "second";
+  try {
+    const text = new Intl.RelativeTimeFormat(locale || undefined, { numeric: "auto" }).format(0, unit);
+    return capitalise(text, locale);
+  } catch {
+    return unit === "day" ? "Today" : "Now";
+  }
+}
+
+/** A date field's name in the viewer's language: `Hour` / `Timme`. */
+export function fieldName(locale, field) {
+  try {
+    const name = new Intl.DisplayNames(locale || undefined, { type: "dateTimeField" }).of(field);
+    if (name) return capitalise(name, locale);
+  } catch {
+    // Older engines lack `dateTimeField`; the English name stands in.
+  }
+  return field === "hour" ? "Hour" : "Minute";
+}
+
+export function twoDigits(value) {
+  return String(value).padStart(2, "0");
+}