@eifi1/ui-kit 0.21.0 → 0.23.0

package/src/components/date-picker.tsx

@@ -1,22 +1,26 @@
 import { useEffect, useId, useMemo, useRef, useState } from "react";
-import type { ComponentPropsWithoutRef, ComponentType, ReactNode, RefObject } from "react";
-import { Calendar, CalendarClock, ChevronLeft, ChevronRight, X } from "lucide-react";
+import type { ComponentPropsWithoutRef, ComponentType, KeyboardEvent, ReactNode, RefObject } from "react";
+import { Calendar, CalendarClock, ChevronDown, ChevronLeft, ChevronRight, X } from "lucide-react";
 import { cn } from "../lib/cn";
-import { dirOf, type Direction } from "../lib/direction";
-import { addDaysIso, parseIsoDate } from "../lib/dates";
+import { dirOf, horizontalStep, type Direction } from "../lib/direction";
+import { addDaysIso, monthKey, pad, parseIsoDate } from "../lib/dates";
 import {
   DEFAULT_DATE_PICKER_LABELS,
   DEFAULT_PICKER_SHEET_LABELS,
+  useKitDateFormatter,
   useKitLabels,
   useKitLocale,
   type DatePickerLabels,
+  type KitDateFormatContext,
 } from "../i18n/kit-labels";
 import { splitTriggerAria } from "./trigger-aria";
 import type { TriggerAria } from "./trigger-aria";
-import { Button, FieldLabel, FIELD_BASE, FIELD_TRIGGER, FIELD_FLOATING_PAD, FIELD_INVALID, PHONE_QUERY } from "./ui";
+import { Button, FIELD_BASE, FIELD_TRIGGER, FIELD_FLOATING_PAD, FIELD_INVALID, PHONE_QUERY } from "./ui";
+import { FieldBox, FieldLabelLine, useFieldMessages } from "./field-parts";
 import { FullBleedDialog } from "./full-bleed-dialog";
 import { useMediaQuery } from "../hooks/use-media-query";
-import { MiniCalendar, type MiniCalendarProps } from "./mini-calendar";
+import { DEFAULT_MINI_CALENDAR_LABELS, MiniCalendar, type MiniCalendarProps } from "./mini-calendar";
+import { DEFAULT_MONTH_PICKER_LABELS } from "./month-picker";
 import { Popover } from "./popover";
 import { Tooltip } from "./tooltip";
 
@@ -47,19 +51,80 @@ interface DatePickerBaseProps extends Omit<ComponentPropsWithoutRef<"div">, "onC
   disabled?: boolean;
   /** Required and unanswered — {@link FIELD_INVALID}. See {@link Input}'s `invalid`. */
   invalid?: boolean;
+  /**
+   * Standing advice for the field (keksdose K4, "uniform field anatomy"), as on a
+   * {@link Select}: plain TEXT is a caption under the field, attached with
+   * `aria-describedby`; a {@link FieldHint} rides the label line (or, unlabelled, sits
+   * at the field's end, outside the box).
+   */
+  hint?: ReactNode;
+  /**
+   * What is wrong with the date, in the caller's words ("The due date is before the
+   * invoice date") — {@link Input}'s `error` (keksdose K4: DateField errors had no slot).
+   * Rendered under the field (under the whole row, with `step` / `today`), attached to
+   * the trigger with `aria-describedby` — merged with any the caller passed, after the
+   * caption — and implies `invalid`. Passing the key at all keeps the field's box while
+   * there is no message, so the trigger is never remounted as one comes and goes.
+   */
+  error?: ReactNode;
   className?: string;
-  /** Intl options for the trigger's formatted date (default: locale short date). */
+  /** Intl options for the trigger's formatted date (default: locale short date). Win
+   *  over the provider's `formatDate`. */
   formatOptions?: Intl.DateTimeFormatOptions;
-  /** Render the trigger's text for an ISO date yourself; wins over `formatOptions`.
+  /** Render the trigger's text for an ISO date yourself; wins over `formatOptions` and
+   *  over the provider's `formatDate`.
    *  For a host whose date rendering is more than one `Intl` call can say — Keksdose
    *  puts the weekday's name in the UI language beside digits ordered by a separate
-   *  format preference, two locales in one string. `locale` still drives the calendar. */
+   *  format preference, two locales in one string. `locale` still drives the calendar.
+   *  Set that rendering once with `<UiKitProvider formatDate>` (keksdose K12) and this
+   *  is for the one field that differs. */
   formatValue?: (iso: string) => string;
   /** Passed through to the {@link MiniCalendar} this opens. Its month arrows are
    *  icon-only, so their `aria-label` is the only name they have — and the package
    *  ships English defaults, which a translating host has to be able to replace.
    *  Usually unnecessary now: the calendar reads `miniCalendar` from the provider. */
   calendarLabels?: MiniCalendarProps["labels"];
+  /**
+   * Make the panel's caption ("July 2026") a button that opens the year's twelve
+   * months, with ‹ › stepping a year; picking a month returns to its days. Far dates
+   * stop being a march of month arrows.
+   *
+   * kastlan is why: its service-charge period runs July to June, and with one month on
+   * screen and ‹ › the only way across, the end of the period was eleven clicks past
+   * the start — so kastlan kept two date fields instead of `RhfDateRangePicker`. With
+   * the jump the whole period is open, caption, Jul, 1, caption, next year, Jun, 30.
+   *
+   * What it adds, for the keyboard and a screen reader:
+   *  - the caption is a disclosure button (`aria-expanded`). Its name is the month it
+   *    shows, so speech input can say what it sees; it is `aria-live`, as the
+   *    calendar's caption was, so paging months still says where you landed; and it is
+   *    described by `monthPicker.panel` ("Choose a month").
+   *  - the month grid is `MonthPicker`'s grid: one tab stop, arrows walk the months
+   *    (across the year's edge), Home/End the row, PageUp/PageDown a year, Enter or a
+   *    click picks. Focus opens on the month on show and comes back on its days — the
+   *    selected day if it is in that month, else the 1st. Months outside `min`/`max`
+   *    are `aria-disabled`, and a year arrow is once the whole year beyond is.
+   *  - Escape in the month grid goes back to the days without closing the panel (focus
+   *    on the caption); in the days, Escape closes the panel as before.
+   *
+   * No new strings: the month arrows keep `miniCalendar.previousMonth` / `nextMonth`
+   * (`calendarLabels`), and the month grid speaks with `MonthPicker`'s words —
+   * `monthPicker.previousYear` / `nextYear` / `month` / `panel` — because it is that
+   * grid, and a host that translated it once should not have to again.
+   *
+   * Off by default: the caption becomes one more stop in the panel's tab order, which a
+   * 0.x minor does not spring on a form. Works in the popover and in
+   * `DateRangePicker`'s phone sheet alike, beside presets and in `commit="apply"`
+   * (a preset picked while the months are open goes back to the days, on its start).
+   *
+   * Why not a two-month panel (`months={2}`) instead, or beside it: for a twelve-month
+   * period it still pages six times where this takes one year step, and two
+   * `MiniCalendar`s side by side each follow the value on their own — picking the end
+   * in the right-hand month would pull the left one onto it — so the calendar would
+   * have to learn to share a month first. Not worth that for a saving of one arrow on a
+   * range across a single month boundary.
+   */
+  monthJump?: boolean;
 }
 
 /** Format an ISO date for the trigger. `lib/dates`' `formatIsoDate` insists on a
@@ -69,6 +134,30 @@ function formatDate(iso: string, locale: string | undefined, options?: Intl.Date
   return parseIsoDate(iso)?.toLocaleDateString(locale, options) ?? "";
 }
 
+/**
+ * The trigger's date renderer, in the kit's order of precedence: the picker's own
+ * `formatValue`, then its `formatOptions` (an explicit `Intl` look for this field),
+ * then the provider's `formatDate` (keksdose K12), then the locale's short date. A
+ * provider formatter that answers `""` falls through to the default for that date.
+ */
+function useTriggerFormat(
+  source: KitDateFormatContext["source"],
+  locale: string | undefined,
+  formatOptions: Intl.DateTimeFormatOptions | undefined,
+  formatValue: ((iso: string) => string) | undefined,
+): (iso: string) => string {
+  const fromProvider = useKitDateFormatter();
+  if (formatValue) return formatValue;
+  return (iso) => {
+    if (formatOptions === undefined && fromProvider) {
+      // A single date stands alone, where the weekday helps; a range's two ends do not.
+      const text = fromProvider(iso, { unit: "day", source, locale, weekday: source === "datePicker" });
+      if (text) return text;
+    }
+    return formatDate(iso, locale, formatOptions);
+  };
+}
+
 /**
  * Everything the kit's own trigger button carries, handed to a custom one
  * ({@link DateRangePickerProps.renderTrigger}) to spread onto its `<button>`. Spread
@@ -285,6 +374,7 @@ function DateField({
   sheet = false,
   sheetBackCloses = true,
   renderTrigger,
+  labelHint,
   children,
   // The trigger's, not the wrapper's: `Field`'s render-prop spreads it with the id
   // pair, and a required date read as optional while it sat on the role-less div.
@@ -295,6 +385,8 @@ function DateField({
   triggerText: string;
   hasValue: boolean;
   label?: ReactNode;
+  /** A `FieldHint` for the label line, beside the label. */
+  labelHint?: ReactNode;
   disabled?: boolean;
   clearable?: boolean;
   /** Already resolved by the picker (prop > provider > English). */
@@ -412,7 +504,7 @@ function DateField({
     // The caller's attributes land here, on the field's own box — the trigger inside is
     // named by `aria-labelledby` and must keep the id pair it is given.
     <div {...wrapperRest} ref={rootRef} className={cn("relative", className)}>
-      {label !== undefined && <FieldLabel>{label}</FieldLabel>}
+      {label !== undefined && <FieldLabelLine label={label} hint={labelHint} />}
       {/* The visible FieldLabel is a plain span, not a `<label htmlFor>`, so it names
           nothing on its own — this hidden twin is what the trigger is named by.
           `aria-hidden` because a name reference reads a hidden element deliberately
@@ -511,6 +603,374 @@ function StepButton({
   );
 }
 
+// ── Month jump (`monthJump`, kastlan) ─────────────────────────────────────
+
+/** A "YYYY-MM" key as a count of months, and back: month arithmetic with no `Date`
+ *  rollover to step around. */
+const monthIndex = (key: string) => Number(key.slice(0, 4)) * 12 + Number(key.slice(5, 7)) - 1;
+const keyOfIndex = (index: number) =>
+  `${String(Math.floor(index / 12)).padStart(4, "0")}-${pad((index % 12) + 1)}`;
+const shiftKey = (key: string, delta: number) => keyOfIndex(monthIndex(key) + delta);
+/** The 1st of a "YYYY-MM" month, for `Intl` to name. */
+const firstOfKey = (key: string) => new Date(Number(key.slice(0, 4)), Number(key.slice(5, 7)) - 1, 1);
+
+/** Upper-case the first letter only, as `MonthPicker` does: "julio de 2026" heads a
+ *  panel as "Julio de 2026" — not "Julio De 2026", which CSS `capitalize` would write. */
+const upperFirst = (text: string, locale: string | undefined) =>
+  text.charAt(0).toLocaleUpperCase(locale) + text.slice(1);
+
+/** Months per row of the month grid — `MonthPicker`'s 4×3. */
+const MONTH_COLUMNS = 3;
+
+/**
+ * The month `MiniCalendar` opens on — the selection, or today, pulled inside the
+ * bounds — worked out the way it does, so the caption drawn over a calendar that was
+ * given no `month` names the month that calendar is showing.
+ */
+function openingMonth(from: string, to: string, lo: Date | null, hi: Date | null): string {
+  const start = parseIsoDate(from) ?? parseIsoDate(to) ?? new Date();
+  if (lo && start < lo) return monthKey(lo);
+  if (hi && start > hi) return monthKey(hi);
+  return monthKey(start);
+}
+
+type PanelCalendarProps = Pick<
+  MiniCalendarProps,
+  "mode" | "from" | "to" | "locale" | "min" | "max" | "labels" | "onSelect" | "focusOnOpen"
+> & {
+  /** See {@link DatePickerBaseProps.monthJump}. */
+  monthJump?: boolean;
+};
+
+/** The panel's calendar: the plain {@link MiniCalendar}, exactly as before — or, with
+ *  `monthJump`, the same calendar under a caption that opens a month grid. */
+function PanelCalendar({ monthJump, ...calendar }: PanelCalendarProps) {
+  return monthJump ? <JumpCalendar {...calendar} /> : <MiniCalendar {...calendar} />;
+}
+
+/** How the day grid is mounted: `key` remounts it, `month` is the month it follows
+ *  (left out until the panel first moves, so it opens exactly where it always has), and
+ *  `focus` is its `focusOnOpen`. */
+interface DayGridMount {
+  key: number;
+  month?: string;
+  focus: boolean;
+}
+
+/**
+ * {@link MiniCalendar} with its navigation drawn here — ‹ caption › — so the caption can
+ * be a button that swaps the days for a month grid ({@link DatePickerBaseProps.monthJump}).
+ *
+ * Built on the calendar's own `hideNavigation` / `month` / `onMonthChange`, not a fork
+ * of it: the days, their keys, the range band and every announcement stay the
+ * calendar's. What this keeps is `shown`, the month on screen, for the caption — fed by
+ * the arrows here, by the calendar's `onMonthChange` (PageUp, arrowing off the edge),
+ * and by the value, whose changes the calendar follows WITHOUT reporting them (a preset
+ * in `commit="apply"` moves the grid to its start). That last one is mirrored below with
+ * the calendar's own rule, and when it lands in another month the day grid is remounted
+ * there rather than steered by `month`: a `month` that changes in the same render as the
+ * value would win over the value's day, and the grid's tab stop would land on the
+ * month's same-numbered day instead of the preset's start.
+ *
+ * The month grid is `MonthPicker`'s, redrawn here because that one is internal to its
+ * file; same roles, keys and words (`monthPicker` labels).
+ */
+function JumpCalendar({
+  from = "",
+  to = "",
+  mode = "range",
+  locale,
+  min,
+  max,
+  labels,
+  onSelect,
+  focusOnOpen,
+}: Omit<PanelCalendarProps, "monthJump">) {
+  // The month arrows say what they said when the calendar drew them; the month grid
+  // says what `MonthPicker`'s says.
+  const calendarText = useKitLabels("miniCalendar", DEFAULT_MINI_CALENDAR_LABELS, labels);
+  const monthText = useKitLabels("monthPicker", DEFAULT_MONTH_PICKER_LABELS);
+  const id = useId();
+  const captionId = `${id}-caption`;
+  const hintId = `${id}-hint`;
+  const captionRef = useRef<HTMLButtonElement>(null);
+  const monthsRef = useRef<HTMLDivElement>(null);
+
+  const lo = min ? parseIsoDate(min) : null;
+  const hi = max ? parseIsoDate(max) : null;
+  const minKey = lo ? monthKey(lo) : null;
+  const maxKey = hi ? monthKey(hi) : null;
+  const outOfBounds = (key: string) => Boolean((minKey && key < minKey) || (maxKey && key > maxKey));
+  const clampKey = (key: string) => (minKey && key < minKey ? minKey : maxKey && key > maxKey ? maxKey : key);
+
+  const [view, setView] = useState<"days" | "months">("days");
+  const [shown, setShown] = useState(() => openingMonth(from, to, lo, hi));
+  const [dayGrid, setDayGrid] = useState<DayGridMount>(() => ({ key: 0, focus: Boolean(focusOnOpen) }));
+  // The month holding the month grid's tab stop — and with it the year on show.
+  const [active, setActive] = useState(shown);
+
+  // The value moved from outside the day grid (a preset, a reset): follow the end that
+  // changed, by the calendar's own rule, and remount the days there — see above. Also
+  // what takes an open month grid back to the days when a preset is picked beside it.
+  const [lastValue, setLastValue] = useState({ from, to });
+  if (lastValue.from !== from || lastValue.to !== to) {
+    const changed = lastValue.from !== from ? from : to;
+    setLastValue({ from, to });
+    const next = parseIsoDate(changed) ?? parseIsoDate(from) ?? parseIsoDate(to);
+    const key = next ? monthKey(next) : null;
+    if (key && (key !== shown || view === "months")) {
+      setShown(key);
+      setView("days");
+      setDayGrid((d) => ({ key: d.key + 1, month: key, focus: false }));
+    }
+  }
+
+  // A month cell that has to take focus once it exists: opening the grid, and arrowing
+  // across a year's edge, which relabels the same twelve buttons.
+  const pendingFocus = useRef<string | null>(null);
+  useEffect(() => {
+    const key = pendingFocus.current;
+    if (!key) return;
+    pendingFocus.current = null;
+    monthsRef.current?.querySelector<HTMLElement>(`[data-month="${key}"]`)?.focus();
+  });
+
+  const showMonth = (key: string) => {
+    setShown(key);
+    // Follows by `month`: the calendar keeps the day of the month (clamped), and the
+    // focus stays on the arrow being pressed.
+    setDayGrid((d) => ({ ...d, month: key }));
+  };
+  const openMonths = () => {
+    const start = clampKey(shown);
+    pendingFocus.current = start;
+    setActive(start);
+    setView("months");
+  };
+  const closeMonths = (focusCaption: boolean) => {
+    setView("days");
+    setDayGrid((d) => ({ ...d, month: shown, focus: false }));
+    if (focusCaption) captionRef.current?.focus();
+  };
+  const pick = (key: string) => {
+    setShown(key);
+    setView("days");
+    // Picked to go there: the focus goes with it, onto the days.
+    setDayGrid((d) => ({ key: d.key + 1, month: key, focus: true }));
+  };
+  const moveActive = (key: string, focus: boolean) => {
+    if (focus) pendingFocus.current = key;
+    setActive(key);
+  };
+
+  const inDays = view === "days";
+  // Escape in the month grid is "back", not "close": the month grid is a step INSIDE the
+  // panel, and losing the half-made range to a key meant to undo that step would be the
+  // worse surprise. Stopped here, so neither the popover nor the phone sheet sees it.
+  const escapeToDays = (e: KeyboardEvent<HTMLElement>) => {
+    if (e.key !== "Escape" || inDays) return;
+    e.preventDefault();
+    e.stopPropagation();
+    closeMonths(true);
+  };
+
+  const onMonthKeyDown = (e: KeyboardEvent<HTMLButtonElement>) => {
+    if (e.key === "Escape") return escapeToDays(e);
+    // Left and right are visual: the grid runs the other way in a right-to-left panel.
+    const step = horizontalStep(e.key, e.currentTarget);
+    const col = (monthIndex(active) % 12) % MONTH_COLUMNS;
+    let delta: number;
+    switch (step ? "horizontal" : e.key) {
+      case "horizontal":
+        delta = step;
+        break;
+      case "ArrowUp":
+        delta = -MONTH_COLUMNS;
+        break;
+      case "ArrowDown":
+        delta = MONTH_COLUMNS;
+        break;
+      case "Home":
+        delta = -col;
+        break;
+      case "End":
+        delta = MONTH_COLUMNS - 1 - col;
+        break;
+      case "PageUp":
+        delta = -12;
+        break;
+      case "PageDown":
+        delta = 12;
+        break;
+      default:
+        return;
+    }
+    // Before the no-op check: these keys also scroll the panel.
+    e.preventDefault();
+    if (delta !== 0) moveActive(shiftKey(active, delta), true);
+  };
+
+  const year = Number(active.slice(0, 4));
+  // A year arrow is dead once every month of the year it leads to is out of bounds.
+  const prevYearBlocked = Boolean(minKey && year - 1 < Number(minKey.slice(0, 4)));
+  const nextYearBlocked = Boolean(maxKey && year + 1 > Number(maxKey.slice(0, 4)));
+  const prevBlocked = !inDays && prevYearBlocked;
+  const nextBlocked = !inDays && nextYearBlocked;
+
+  const longName = useMemo(() => new Intl.DateTimeFormat(locale, { month: "long", year: "numeric" }), [locale]);
+  const shortNames = useMemo(() => {
+    const fmt = new Intl.DateTimeFormat(locale, { month: "short" });
+    return Array.from({ length: 12 }, (_, i) => upperFirst(fmt.format(new Date(2000, i, 1)), locale));
+  }, [locale]);
+  const caption = inDays
+    ? upperFirst(longName.format(firstOfKey(shown)), locale)
+    : new Intl.DateTimeFormat(locale, { year: "numeric" }).format(new Date(year, 0, 1));
+
+  // The selection, as months: both ends, and the months between (a range's band).
+  const fromDate = parseIsoDate(from);
+  const toDate = parseIsoDate(to);
+  const fromKey = fromDate ? monthKey(fromDate) : null;
+  const toKey = toDate ? monthKey(toDate) : null;
+  const low = fromKey ?? toKey;
+  const high = toKey ?? fromKey;
+  const currentKey = monthKey(new Date());
+
+  // Aria-disabled rather than disabled, like the day cells: a focused button that
+  // turns `disabled` drops the focus to <body>, mid-panel.
+  const arrow =
+    "rounded p-1 text-[var(--text-muted)] hover:bg-[var(--bg-hover)] aria-disabled:cursor-not-allowed aria-disabled:opacity-30 aria-disabled:hover:bg-transparent";
+
+  return (
+    <div className="select-none">
+      {/* The calendar's own row, redrawn: the same arrows in the same places. Each
+          button stays mounted across the two views and changes what it steps, so a
+          press never pulls the element out from under the pointer or the focus. */}
+      <div className="flex items-center justify-between gap-1 pb-1">
+        <button
+          type="button"
+          aria-label={inDays ? calendarText.previousMonth : monthText.previousYear}
+          aria-disabled={prevBlocked || undefined}
+          onClick={() => {
+            if (inDays) showMonth(shiftKey(shown, -1));
+            else if (!prevBlocked) moveActive(shiftKey(active, -12), false);
+          }}
+          onKeyDown={escapeToDays}
+          className={arrow}
+        >
+          {/* Mirrored in RTL: "previous" points to the reading START, which is right. */}
+          <ChevronLeft className="size-4 rtl:-scale-x-100" aria-hidden />
+        </button>
+        <button
+          ref={captionRef}
+          type="button"
+          aria-expanded={!inDays}
+          aria-describedby={inDays ? hintId : undefined}
+          onClick={inDays ? openMonths : () => closeMonths(false)}
+          onKeyDown={escapeToDays}
+          className="inline-flex min-w-0 items-center gap-1 rounded px-1.5 py-0.5 text-xs font-medium text-[var(--text-secondary)] hover:bg-[var(--bg-hover)]"
+        >
+          {/* The name is the text, so it says what is on screen; `aria-live` because
+              pressing an arrow leaves focus ON the arrow, and this is the only thing
+              that says where it went. It also names the month grid. */}
+          <span id={captionId} aria-live="polite" className="truncate">
+            {caption}
+          </span>
+          <ChevronDown
+            aria-hidden
+            className={cn("size-3.5 shrink-0 text-[var(--text-muted)]", !inDays && "rotate-180")}
+          />
+        </button>
+        <button
+          type="button"
+          aria-label={inDays ? calendarText.nextMonth : monthText.nextYear}
+          aria-disabled={nextBlocked || undefined}
+          onClick={() => {
+            if (inDays) showMonth(shiftKey(shown, 1));
+            else if (!nextBlocked) moveActive(shiftKey(active, 12), false);
+          }}
+          onKeyDown={escapeToDays}
+          className={arrow}
+        >
+          <ChevronRight className="size-4 rtl:-scale-x-100" aria-hidden />
+        </button>
+      </div>
+      {/* The caption's description — read through the reference, never on its own. */}
+      <span id={hintId} hidden>
+        {monthText.panel}
+      </span>
+      {inDays ? (
+        <MiniCalendar
+          key={dayGrid.key}
+          mode={mode}
+          from={from}
+          to={to}
+          locale={locale}
+          min={min}
+          max={max}
+          labels={labels}
+          onSelect={onSelect}
+          focusOnOpen={dayGrid.focus}
+          hideNavigation
+          month={dayGrid.month}
+          onMonthChange={showMonth}
+        />
+      ) : (
+        <div ref={monthsRef} role="grid" aria-labelledby={captionId} className="grid gap-1">
+          {Array.from({ length: 12 / MONTH_COLUMNS }, (_, row) => (
+            <div key={row} role="row" className="grid grid-cols-3 gap-1">
+              {Array.from({ length: MONTH_COLUMNS }, (_, c) => {
+                const index = row * MONTH_COLUMNS + c;
+                const key = keyOfIndex(year * 12 + index);
+                const disabled = outOfBounds(key);
+                const selected = low !== null && high !== null && key >= low && key <= high;
+                const end = key === fromKey || key === toKey;
+                const current = key === currentKey;
+                return (
+                  <button
+                    key={c}
+                    type="button"
+                    role="gridcell"
+                    data-month={key}
+                    tabIndex={key === active ? 0 : -1}
+                    aria-label={monthText.month(longName.format(firstOfKey(key)))}
+                    aria-selected={selected}
+                    aria-disabled={disabled || undefined}
+                    aria-current={current ? "date" : undefined}
+                    onClick={() => {
+                      // The guard `disabled` would have been: out-of-bounds months stay
+                      // focusable, so the roving tab stop never falls into a hole.
+                      if (!disabled) pick(key);
+                    }}
+                    onKeyDown={onMonthKeyDown}
+                    className={cn(
+                      // 44px rows: the touch-target size, and four of them stand as tall
+                      // as a month of days, so the panel does not jump as the views swap.
+                      "h-11 rounded px-1 text-sm tabular-nums transition-colors",
+                      "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset",
+                      // A --brand ring on a --brand fill exists only in the DOM.
+                      end && !disabled ? "focus-visible:ring-[var(--brand-contrast)]" : "focus-visible:ring-[var(--brand)]",
+                      disabled
+                        ? "cursor-not-allowed text-[var(--text-placeholder)]"
+                        : end
+                          ? "bg-[var(--brand)] text-[var(--brand-contrast)] hover:bg-[var(--brand-hover)]"
+                          : selected
+                            ? "bg-[var(--brand-bg)] font-medium text-[var(--brand-muted)] hover:bg-[var(--brand-bg-hover)]"
+                            : "text-[var(--text-primary)] hover:bg-[var(--bg-hover)]",
+                      current && !selected && !disabled && "ring-1 ring-inset ring-[var(--border-strong)]",
+                    )}
+                  >
+                    {shortNames[index]}
+                  </button>
+                );
+              })}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
 export interface DatePickerProps extends DatePickerBaseProps {
   /** ISO "YYYY-MM-DD", or "" for empty. */
   value: string;
@@ -568,35 +1028,62 @@ function useDatePickerLabels(
   return useKitLabels("datePicker", DEFAULT_DATE_PICKER_LABELS, fromProps);
 }
 
+/**
+ * The caller's `hint` when it has no label line to ride: at the end of the field,
+ * outside the box, as an unlabelled {@link Select} places its FieldHint (0.15.5 P8).
+ */
+function withEndHint(field: ReactNode, hint: ReactNode): ReactNode {
+  if (hint === undefined) return field;
+  return (
+    <div className="flex items-center gap-1.5">
+      <div className="min-w-0 flex-1">{field}</div>
+      <span className="flex shrink-0 items-center">{hint}</span>
+    </div>
+  );
+}
+
 /** Single-date picker: a field showing the formatted date, opening a calendar. */
-export function DatePicker({
-  value,
-  onChange,
-  locale: localeProp,
-  placeholder,
-  min,
-  max,
-  formatOptions,
-  formatValue,
-  step,
-  stepLabels,
-  today,
-  todayLabel,
-  className,
-  calendarLabels,
-  label,
-  clearable,
-  clearLabel,
-  disabled,
-  invalid,
-  // Named so it reaches the field (and so its trigger) when a step/today row is the
-  // root and takes the rest of the caller's props.
-  "aria-required": ariaRequired,
-  ...rest
-}: DatePickerProps) {
+export function DatePicker(props: DatePickerProps) {
+  const {
+    value,
+    onChange,
+    locale: localeProp,
+    placeholder,
+    min,
+    max,
+    formatOptions,
+    formatValue,
+    step,
+    stepLabels,
+    today,
+    todayLabel,
+    className,
+    calendarLabels,
+    monthJump,
+    label,
+    clearable,
+    clearLabel,
+    disabled,
+    invalid,
+    hint,
+    error,
+    // Named so it reaches the field (and so its trigger) when a step/today row is the
+    // root and takes the rest of the caller's props.
+    "aria-required": ariaRequired,
+    ...rest
+  } = props;
   const locale = useKitLocale(localeProp);
   const text = useDatePickerLabels(clearLabel, stepLabels, todayLabel);
-  const render = formatValue ?? ((iso: string) => formatDate(iso, locale, formatOptions));
+  const render = useTriggerFormat("datePicker", locale, formatOptions, formatValue);
+  // keksdose K4: the caption and the error under the field, attached to the TRIGGER
+  // (the element a screen reader is on) after any description of the caller's own.
+  const messages = useFieldMessages({
+    hint,
+    error,
+    invalid,
+    describedBy: rest["aria-describedby"],
+    ariaInvalid: rest["aria-invalid"],
+  });
   // With a step or a today button beside it the field is no longer the outermost
   // element — the flex row at the bottom is, and a caller's attributes belong on
   // whichever of the two is actually the root. Naming the shared props rather than
@@ -608,20 +1095,23 @@ export function DatePicker({
       // With step/today buttons the flex row is the root and takes the caller's props —
       // except the ones that name the field, which still belong on its trigger.
       {...(wrapped ? triggerAria : rest)}
+      aria-describedby={messages.describedBy}
       aria-required={ariaRequired}
       label={label}
+      labelHint={messages.labelHint}
       clearable={clearable}
       clearLabel={text.clear}
       panelLabel={text.panel}
       disabled={disabled}
-      invalid={invalid}
+      invalid={messages.isInvalid}
       className={step ? "min-w-0 flex-1" : className}
       hasValue={Boolean(value)}
       triggerText={value ? render(value) : (placeholder ?? "")}
       onClear={() => onChange("")}
     >
       {(close) => (
-        <MiniCalendar
+        <PanelCalendar
+          monthJump={monthJump}
           mode="single"
           focusOnOpen
           from={value}
@@ -638,7 +1128,16 @@ export function DatePicker({
       )}
     </DateField>
   );
-  if (!wrapped) return field;
+  // Passed at all — even as `undefined` — the field keeps its box; see FieldBox.
+  const reserve = "error" in props || "hint" in props;
+  const endHint = label === undefined ? messages.labelHint : undefined;
+  if (!wrapped) {
+    return (
+      <FieldBox below={messages.below} reserve={reserve}>
+        {withEndHint(field, endHint)}
+      </FieldBox>
+    );
+  }
 
   // An empty field has nothing to step from, so both buttons are dead until a date
   // is picked. Bounds are compared as strings: "YYYY-MM-DD" sorts chronologically.
@@ -649,7 +1148,7 @@ export function DatePicker({
     if (!next || disabled) return true;
     return outOfBounds(next);
   };
-  return (
+  const row = (
     // ONE joined control, not three boxes in a row: the buttons and the field share
     // their borders (each piece overlaps the previous by a pixel) and only the outer
     // ends are rounded — the button-group shape, so ‹ date › reads as one field with
@@ -701,6 +1200,13 @@ export function DatePicker({
       )}
     </div>
   );
+  // Under the whole row, not under the field between the buttons: the message is about
+  // the date, and the steppers are part of how it is entered.
+  return (
+    <FieldBox below={messages.below} reserve={reserve}>
+      {withEndHint(row, endHint)}
+    </FieldBox>
+  );
 }
 
 export interface DateRangePickerPreset {
@@ -939,7 +1445,7 @@ function RangePanel({
   frame: PanelFrame;
   sheet: boolean;
   commitRange: (from: string, to: string, presetId: string | undefined) => void;
-  calendarProps: Pick<MiniCalendarProps, "locale" | "min" | "max" | "labels">;
+  calendarProps: Pick<PanelCalendarProps, "locale" | "min" | "max" | "labels" | "monthJump">;
   labels: DatePickerLabels;
   renderDraftSummary?: DateRangePickerProps["renderDraftSummary"];
 }) {
@@ -962,7 +1468,7 @@ function RangePanel({
       : null;
 
   const picker = (
-    <MiniCalendar
+    <PanelCalendar
       {...calendarProps}
       focusOnOpen
       from={shown.from}
@@ -1052,34 +1558,45 @@ function RangePanel({
 /** Two-date range picker: click a start then an end; closes once both are set.
  *  With `presets`, a column of named ranges is shown beside the calendar; with
  *  `commit="apply"` the panel drafts and commits on Apply (see {@link DateRangeCommit}). */
-export function DateRangePicker({
-  from,
-  to,
-  onChange,
-  locale: localeProp,
-  placeholder,
-  min,
-  max,
-  formatOptions,
-  formatValue,
-  separator = " – ",
-  presets,
-  preset,
-  commit = "immediate",
-  renderTrigger,
-  sheetBackCloses,
-  renderDraftSummary,
-  calendarLabels,
-  label,
-  clearable,
-  clearLabel,
-  disabled,
-  invalid,
-  ...rest
-}: DateRangePickerProps) {
+export function DateRangePicker(props: DateRangePickerProps) {
+  const {
+    from,
+    to,
+    onChange,
+    locale: localeProp,
+    placeholder,
+    min,
+    max,
+    formatOptions,
+    formatValue,
+    separator = " – ",
+    presets,
+    preset,
+    commit = "immediate",
+    renderTrigger,
+    sheetBackCloses,
+    renderDraftSummary,
+    calendarLabels,
+    monthJump,
+    label,
+    clearable,
+    clearLabel,
+    disabled,
+    invalid,
+    hint,
+    error,
+    ...rest
+  } = props;
   const locale = useKitLocale(localeProp);
   const text = useDatePickerLabels(clearLabel, undefined, undefined);
-  const render = formatValue ?? ((iso: string) => formatDate(iso, locale, formatOptions));
+  const render = useTriggerFormat("dateRangePicker", locale, formatOptions, formatValue);
+  const messages = useFieldMessages({
+    hint,
+    error,
+    invalid,
+    describedBy: rest["aria-describedby"],
+    ariaInvalid: rest["aria-invalid"],
+  });
   // The preset this picker committed itself, for a caller that does not control
   // `preset`. Cleared by a hand-picked range or a clear.
   const [ownPreset, setOwnPreset] = useState<string | undefined>(undefined);
@@ -1101,15 +1618,17 @@ export function DateRangePicker({
     if (presetId === undefined) onChange(f, t);
     else onChange(f, t, presetId);
   };
-  return (
+  const field = (
     <DateField
       {...rest}
+      aria-describedby={messages.describedBy}
       label={label}
+      labelHint={messages.labelHint}
       clearable={clearable}
       clearLabel={text.clear}
       panelLabel={text.rangePanel}
       disabled={disabled}
-      invalid={invalid}
+      invalid={messages.isInvalid}
       // Widen so the preset column sits beside the calendar (default otherwise).
       width={hasPresets ? 440 : undefined}
       hasValue={Boolean(from || to)}
@@ -1143,11 +1662,16 @@ export function DateRangePicker({
           frame={frame}
           sheet={sheet}
           commitRange={commitRange}
-          calendarProps={{ locale, min, max, labels: calendarLabels }}
+          calendarProps={{ locale, min, max, labels: calendarLabels, monthJump }}
           labels={text}
           renderDraftSummary={renderDraftSummary}
         />
       )}
     </DateField>
   );
+  return (
+    <FieldBox below={messages.below} reserve={"error" in props || "hint" in props}>
+      {withEndHint(field, label === undefined ? messages.labelHint : undefined)}
+    </FieldBox>
+  );
 }