@eifi1/ui-kit 0.21.0 → 0.23.0

package/dist/components/date-picker.d.ts

@@ -29,19 +29,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;
 }
 /**
  * Everything the kit's own trigger button carries, handed to a custom one
@@ -107,7 +168,7 @@ interface DatePickerProps extends DatePickerBaseProps {
     todayLabel?: string;
 }
 /** Single-date picker: a field showing the formatted date, opening a calendar. */
-declare function DatePicker({ value, onChange, locale: localeProp, placeholder, min, max, formatOptions, formatValue, step, stepLabels, today, todayLabel, className, calendarLabels, label, clearable, clearLabel, disabled, invalid, "aria-required": ariaRequired, ...rest }: DatePickerProps): react.JSX.Element;
+declare function DatePicker(props: DatePickerProps): react.JSX.Element;
 interface DateRangePickerPreset {
     /**
      * The preset's identity, independent of its dates — `"last_3_months"`, not two ISO
@@ -230,6 +291,6 @@ interface DateRangeTriggerRenderProps {
 /** 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}). */
-declare function DateRangePicker({ from, to, onChange, locale: localeProp, placeholder, min, max, formatOptions, formatValue, separator, presets, preset, commit, renderTrigger, sheetBackCloses, renderDraftSummary, calendarLabels, label, clearable, clearLabel, disabled, invalid, ...rest }: DateRangePickerProps): react.JSX.Element;
+declare function DateRangePicker(props: DateRangePickerProps): react.JSX.Element;
 
 export { DatePicker, type DatePickerProps, type DateRangeCommit, type DateRangeDraftSummary, DateRangePicker, type DateRangePickerPreset, type DateRangePickerProps, type DateRangeTriggerRenderProps, type DateTriggerAttributes };

package/dist/components/date-picker.js

@@ -1,26 +1,40 @@
 "use client";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useEffect, useId, useMemo, useRef, useState } from "react";
-import { Calendar, CalendarClock, ChevronLeft, ChevronRight, X } from "lucide-react";
+import { Calendar, CalendarClock, ChevronDown, ChevronLeft, ChevronRight, X } from "lucide-react";
 import { cn } from "../lib/cn.js";
-import { dirOf } from "../lib/direction.js";
-import { addDaysIso, parseIsoDate } from "../lib/dates.js";
+import { dirOf, horizontalStep } from "../lib/direction.js";
+import { addDaysIso, monthKey, pad, parseIsoDate } from "../lib/dates.js";
 import {
   DEFAULT_DATE_PICKER_LABELS,
   DEFAULT_PICKER_SHEET_LABELS,
+  useKitDateFormatter,
   useKitLabels,
   useKitLocale
 } from "../i18n/kit-labels.js";
 import { splitTriggerAria } from "./trigger-aria.js";
-import { Button, FieldLabel, FIELD_BASE, FIELD_TRIGGER, FIELD_FLOATING_PAD, FIELD_INVALID, PHONE_QUERY } from "./ui.js";
+import { Button, FIELD_BASE, FIELD_TRIGGER, FIELD_FLOATING_PAD, FIELD_INVALID, PHONE_QUERY } from "./ui.js";
+import { FieldBox, FieldLabelLine, useFieldMessages } from "./field-parts.js";
 import { FullBleedDialog } from "./full-bleed-dialog.js";
 import { useMediaQuery } from "../hooks/use-media-query.js";
-import { MiniCalendar } from "./mini-calendar.js";
+import { DEFAULT_MINI_CALENDAR_LABELS, MiniCalendar } from "./mini-calendar.js";
+import { DEFAULT_MONTH_PICKER_LABELS } from "./month-picker.js";
 import { Popover } from "./popover.js";
 import { Tooltip } from "./tooltip.js";
 function formatDate(iso, locale, options) {
   return parseIsoDate(iso)?.toLocaleDateString(locale, options) ?? "";
 }
+function useTriggerFormat(source, locale, formatOptions, formatValue) {
+  const fromProvider = useKitDateFormatter();
+  if (formatValue) return formatValue;
+  return (iso) => {
+    if (formatOptions === void 0 && fromProvider) {
+      const text = fromProvider(iso, { unit: "day", source, locale, weekday: source === "datePicker" });
+      if (text) return text;
+    }
+    return formatDate(iso, locale, formatOptions);
+  };
+}
 function CustomTrigger({
   render,
   attrs,
@@ -118,6 +132,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.
@@ -188,7 +203,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.
     /* @__PURE__ */ jsxs("div", { ...wrapperRest, ref: rootRef, className: cn("relative", className), children: [
-      label !== void 0 && /* @__PURE__ */ jsx(FieldLabel, { children: label }),
+      label !== void 0 && /* @__PURE__ */ jsx(FieldLabelLine, { label, hint: labelHint }),
       named && /* @__PURE__ */ jsx("span", { id: labelId, "aria-hidden": true, className: "sr-only-fixed", children: label }),
       sheet ? /* @__PURE__ */ jsxs(Fragment, { children: [
         fieldTrigger({ open: sheetOpen, toggle: () => setSheetOpen((v) => !v), ref: sheetTriggerRef }),
@@ -256,6 +271,263 @@ function StepButton({
     }
   ) });
 }
+const monthIndex = (key) => Number(key.slice(0, 4)) * 12 + Number(key.slice(5, 7)) - 1;
+const keyOfIndex = (index) => `${String(Math.floor(index / 12)).padStart(4, "0")}-${pad(index % 12 + 1)}`;
+const shiftKey = (key, delta) => keyOfIndex(monthIndex(key) + delta);
+const firstOfKey = (key) => new Date(Number(key.slice(0, 4)), Number(key.slice(5, 7)) - 1, 1);
+const upperFirst = (text, locale) => text.charAt(0).toLocaleUpperCase(locale) + text.slice(1);
+const MONTH_COLUMNS = 3;
+function openingMonth(from, to, lo, hi) {
+  const start = parseIsoDate(from) ?? parseIsoDate(to) ?? /* @__PURE__ */ new Date();
+  if (lo && start < lo) return monthKey(lo);
+  if (hi && start > hi) return monthKey(hi);
+  return monthKey(start);
+}
+function PanelCalendar({ monthJump, ...calendar }) {
+  return monthJump ? /* @__PURE__ */ jsx(JumpCalendar, { ...calendar }) : /* @__PURE__ */ jsx(MiniCalendar, { ...calendar });
+}
+function JumpCalendar({
+  from = "",
+  to = "",
+  mode = "range",
+  locale,
+  min,
+  max,
+  labels,
+  onSelect,
+  focusOnOpen
+}) {
+  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(null);
+  const monthsRef = useRef(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) => Boolean(minKey && key < minKey || maxKey && key > maxKey);
+  const clampKey = (key) => minKey && key < minKey ? minKey : maxKey && key > maxKey ? maxKey : key;
+  const [view, setView] = useState("days");
+  const [shown, setShown] = useState(() => openingMonth(from, to, lo, hi));
+  const [dayGrid, setDayGrid] = useState(() => ({ key: 0, focus: Boolean(focusOnOpen) }));
+  const [active, setActive] = useState(shown);
+  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 }));
+    }
+  }
+  const pendingFocus = useRef(null);
+  useEffect(() => {
+    const key = pendingFocus.current;
+    if (!key) return;
+    pendingFocus.current = null;
+    monthsRef.current?.querySelector(`[data-month="${key}"]`)?.focus();
+  });
+  const showMonth = (key) => {
+    setShown(key);
+    setDayGrid((d) => ({ ...d, month: key }));
+  };
+  const openMonths = () => {
+    const start = clampKey(shown);
+    pendingFocus.current = start;
+    setActive(start);
+    setView("months");
+  };
+  const closeMonths = (focusCaption) => {
+    setView("days");
+    setDayGrid((d) => ({ ...d, month: shown, focus: false }));
+    if (focusCaption) captionRef.current?.focus();
+  };
+  const pick = (key) => {
+    setShown(key);
+    setView("days");
+    setDayGrid((d) => ({ key: d.key + 1, month: key, focus: true }));
+  };
+  const moveActive = (key, focus) => {
+    if (focus) pendingFocus.current = key;
+    setActive(key);
+  };
+  const inDays = view === "days";
+  const escapeToDays = (e) => {
+    if (e.key !== "Escape" || inDays) return;
+    e.preventDefault();
+    e.stopPropagation();
+    closeMonths(true);
+  };
+  const onMonthKeyDown = (e) => {
+    if (e.key === "Escape") return escapeToDays(e);
+    const step = horizontalStep(e.key, e.currentTarget);
+    const col = monthIndex(active) % 12 % MONTH_COLUMNS;
+    let delta;
+    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;
+    }
+    e.preventDefault();
+    if (delta !== 0) moveActive(shiftKey(active, delta), true);
+  };
+  const year = Number(active.slice(0, 4));
+  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(2e3, 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));
+  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(/* @__PURE__ */ new Date());
+  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 /* @__PURE__ */ jsxs("div", { className: "select-none", children: [
+    /* @__PURE__ */ jsxs("div", { className: "flex items-center justify-between gap-1 pb-1", children: [
+      /* @__PURE__ */ jsx(
+        "button",
+        {
+          type: "button",
+          "aria-label": inDays ? calendarText.previousMonth : monthText.previousYear,
+          "aria-disabled": prevBlocked || void 0,
+          onClick: () => {
+            if (inDays) showMonth(shiftKey(shown, -1));
+            else if (!prevBlocked) moveActive(shiftKey(active, -12), false);
+          },
+          onKeyDown: escapeToDays,
+          className: arrow,
+          children: /* @__PURE__ */ jsx(ChevronLeft, { className: "size-4 rtl:-scale-x-100", "aria-hidden": true })
+        }
+      ),
+      /* @__PURE__ */ jsxs(
+        "button",
+        {
+          ref: captionRef,
+          type: "button",
+          "aria-expanded": !inDays,
+          "aria-describedby": inDays ? hintId : void 0,
+          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)]",
+          children: [
+            /* @__PURE__ */ jsx("span", { id: captionId, "aria-live": "polite", className: "truncate", children: caption }),
+            /* @__PURE__ */ jsx(
+              ChevronDown,
+              {
+                "aria-hidden": true,
+                className: cn("size-3.5 shrink-0 text-[var(--text-muted)]", !inDays && "rotate-180")
+              }
+            )
+          ]
+        }
+      ),
+      /* @__PURE__ */ jsx(
+        "button",
+        {
+          type: "button",
+          "aria-label": inDays ? calendarText.nextMonth : monthText.nextYear,
+          "aria-disabled": nextBlocked || void 0,
+          onClick: () => {
+            if (inDays) showMonth(shiftKey(shown, 1));
+            else if (!nextBlocked) moveActive(shiftKey(active, 12), false);
+          },
+          onKeyDown: escapeToDays,
+          className: arrow,
+          children: /* @__PURE__ */ jsx(ChevronRight, { className: "size-4 rtl:-scale-x-100", "aria-hidden": true })
+        }
+      )
+    ] }),
+    /* @__PURE__ */ jsx("span", { id: hintId, hidden: true, children: monthText.panel }),
+    inDays ? /* @__PURE__ */ jsx(
+      MiniCalendar,
+      {
+        mode,
+        from,
+        to,
+        locale,
+        min,
+        max,
+        labels,
+        onSelect,
+        focusOnOpen: dayGrid.focus,
+        hideNavigation: true,
+        month: dayGrid.month,
+        onMonthChange: showMonth
+      },
+      dayGrid.key
+    ) : /* @__PURE__ */ jsx("div", { ref: monthsRef, role: "grid", "aria-labelledby": captionId, className: "grid gap-1", children: Array.from({ length: 12 / MONTH_COLUMNS }, (_, row) => /* @__PURE__ */ jsx("div", { role: "row", className: "grid grid-cols-3 gap-1", children: Array.from({ length: MONTH_COLUMNS }, (_2, 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 /* @__PURE__ */ jsx(
+        "button",
+        {
+          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 || void 0,
+          "aria-current": current ? "date" : void 0,
+          onClick: () => {
+            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)]"
+          ),
+          children: shortNames[index]
+        },
+        c
+      );
+    }) }, row)) })
+  ] });
+}
 function useDatePickerLabels(clearLabel, stepLabels, todayLabel) {
   const prev = stepLabels?.prev;
   const next = stepLabels?.next;
@@ -269,54 +541,75 @@ function useDatePickerLabels(clearLabel, stepLabels, todayLabel) {
   }, [clearLabel, prev, next, todayLabel]);
   return useKitLabels("datePicker", DEFAULT_DATE_PICKER_LABELS, fromProps);
 }
-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
-}) {
+function withEndHint(field, hint) {
+  if (hint === void 0) return field;
+  return /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-1.5", children: [
+    /* @__PURE__ */ jsx("div", { className: "min-w-0 flex-1", children: field }),
+    /* @__PURE__ */ jsx("span", { className: "flex shrink-0 items-center", children: hint })
+  ] });
+}
+function DatePicker(props) {
+  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) => formatDate(iso, locale, formatOptions));
+  const render = useTriggerFormat("datePicker", locale, formatOptions, formatValue);
+  const messages = useFieldMessages({
+    hint,
+    error,
+    invalid,
+    describedBy: rest["aria-describedby"],
+    ariaInvalid: rest["aria-invalid"]
+  });
   const wrapped = Boolean(step || today);
   const [triggerAria, wrapperRest] = splitTriggerAria(rest);
   const field = /* @__PURE__ */ jsx(
     DateField,
     {
       ...wrapped ? triggerAria : rest,
+      "aria-describedby": messages.describedBy,
       "aria-required": ariaRequired,
       label,
+      labelHint: messages.labelHint,
       clearable,
       clearLabel: text.clear,
       panelLabel: text.panel,
       disabled,
-      invalid,
+      invalid: messages.isInvalid,
       className: step ? "min-w-0 flex-1" : className,
       hasValue: Boolean(value),
       triggerText: value ? render(value) : placeholder ?? "",
       onClear: () => onChange(""),
       children: (close) => /* @__PURE__ */ jsx(
-        MiniCalendar,
+        PanelCalendar,
         {
+          monthJump,
           mode: "single",
           focusOnOpen: true,
           from: value,
@@ -333,7 +626,11 @@ function DatePicker({
       )
     }
   );
-  if (!wrapped) return field;
+  const reserve = "error" in props || "hint" in props;
+  const endHint = label === void 0 ? messages.labelHint : void 0;
+  if (!wrapped) {
+    return /* @__PURE__ */ jsx(FieldBox, { below: messages.below, reserve, children: withEndHint(field, endHint) });
+  }
   const target = (days) => value ? addDaysIso(value, days) : "";
   const outOfBounds = (iso) => Boolean(min && iso < min || max && iso > max);
   const blocked = (days) => {
@@ -341,7 +638,7 @@ 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
@@ -400,6 +697,7 @@ function DatePicker({
       }
     )
   );
+  return /* @__PURE__ */ jsx(FieldBox, { below: messages.below, reserve, children: withEndHint(row, endHint) });
 }
 function markedPreset(presets, from, to, activeId, controlled) {
   const matches = (p) => p.from === from && p.to === to;
@@ -477,7 +775,7 @@ function RangePanel({
   const complete = Boolean(draft.from && draft.to);
   const summary = drafting && renderDraftSummary ? renderDraftSummary({ from: draft.from, to: draft.to, preset: presets?.[marked] }) : null;
   const picker = /* @__PURE__ */ jsx(
-    MiniCalendar,
+    PanelCalendar,
     {
       ...calendarProps,
       focusOnOpen: true,
@@ -539,34 +837,45 @@ function RangePanel({
     ] })
   );
 }
-function DateRangePicker({
-  from,
-  to,
-  onChange,
-  locale: localeProp,
-  placeholder,
-  min,
-  max,
-  formatOptions,
-  formatValue,
-  separator = " \u2013 ",
-  presets,
-  preset,
-  commit = "immediate",
-  renderTrigger,
-  sheetBackCloses,
-  renderDraftSummary,
-  calendarLabels,
-  label,
-  clearable,
-  clearLabel,
-  disabled,
-  invalid,
-  ...rest
-}) {
+function DateRangePicker(props) {
+  const {
+    from,
+    to,
+    onChange,
+    locale: localeProp,
+    placeholder,
+    min,
+    max,
+    formatOptions,
+    formatValue,
+    separator = " \u2013 ",
+    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, void 0, void 0);
-  const render = formatValue ?? ((iso) => 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"]
+  });
   const [ownPreset, setOwnPreset] = useState(void 0);
   const controlled = preset !== void 0;
   const activeId = controlled ? preset : ownPreset;
@@ -580,16 +889,18 @@ function DateRangePicker({
     if (presetId === void 0) onChange(f, t);
     else onChange(f, t, presetId);
   };
-  return /* @__PURE__ */ jsx(
+  const field = /* @__PURE__ */ jsx(
     DateField,
     {
       ...rest,
+      "aria-describedby": messages.describedBy,
       label,
+      labelHint: messages.labelHint,
       clearable,
       clearLabel: text.clear,
       panelLabel: text.rangePanel,
       disabled,
-      invalid,
+      invalid: messages.isInvalid,
       width: hasPresets ? 440 : void 0,
       hasValue: Boolean(from || to),
       triggerText,
@@ -618,13 +929,14 @@ function DateRangePicker({
           frame,
           sheet,
           commitRange,
-          calendarProps: { locale, min, max, labels: calendarLabels },
+          calendarProps: { locale, min, max, labels: calendarLabels, monthJump },
           labels: text,
           renderDraftSummary
         }
       )
     }
   );
+  return /* @__PURE__ */ jsx(FieldBox, { below: messages.below, reserve: "error" in props || "hint" in props, children: withEndHint(field, label === void 0 ? messages.labelHint : void 0) });
 }
 export {
   DatePicker,