@eifi1/ui-kit 0.21.0 → 0.23.0

package/src/components/month-picker.tsx

@@ -4,11 +4,12 @@ import { Calendar, ChevronDown, ChevronLeft, ChevronRight } from "lucide-react";
 import { cn } from "../lib/cn";
 import { dirOf, horizontalStep, type Direction } from "../lib/direction";
 import { monthKey, pad } from "../lib/dates";
-import { Button, FieldLabel, FIELD_FLOATING_PAD, FIELD_INVALID, FIELD_TRIGGER, IconButton } from "./ui";
+import { Button, FIELD_FLOATING_PAD, FIELD_INVALID, FIELD_TRIGGER, IconButton } from "./ui";
 import { Popover } from "./popover";
 import { splitTriggerAria } from "./trigger-aria";
 import type { TriggerAria } from "./trigger-aria";
-import { useKitLabels, useKitLocale } from "../i18n/kit-labels";
+import { useKitDateFormatter, useKitLabels, useKitLocale } from "../i18n/kit-labels";
+import { FieldBox, FieldLabelLine, hasContent, useFieldMessages } from "./field-parts";
 
 /**
  * Every string the month picker can speak. The month and year names are NOT here —
@@ -32,6 +33,15 @@ export interface MonthPickerLabels {
   nextMonth: string;
   /** `variant="stepper"`: the button that jumps to the current month. Visible text. */
   today: string;
+  /** `mode="year"`: the popover's accessible name. */
+  yearPanel: string;
+  /** `mode="year"`: the icon-only arrows that page the year grid back and forward by a
+   *  page of twelve years. */
+  earlierYears: string;
+  laterYears: string;
+  /** `mode="year"`, `variant="stepper"`: the button that jumps to the current year.
+   *  Visible text. */
+  thisYear: string;
 }
 
 /** The English starting point every override is merged onto. Exported (unlike the
@@ -45,6 +55,10 @@ export const DEFAULT_MONTH_PICKER_LABELS: MonthPickerLabels = {
   previousMonth: "Previous month",
   nextMonth: "Next month",
   today: "Today",
+  yearPanel: "Choose a year",
+  earlierYears: "Earlier years",
+  laterYears: "Later years",
+  thisYear: "This year",
 };
 
 /** Merge caller overrides onto the English defaults. */
@@ -89,7 +103,45 @@ export interface MonthPickerProps extends Omit<ComponentPropsWithoutRef<"div">,
   disabled?: boolean;
   /** Required and unanswered — {@link FIELD_INVALID}. See {@link Input}'s `invalid`. */
   invalid?: boolean;
-  /** Intl options for the trigger's text (default: long month + numeric year). */
+  /**
+   * What is wrong with the month, in the caller's words — {@link Input}'s `error`
+   * (keksdose K4): under the field, attached to the trigger with `aria-describedby`
+   * (merged, after any caption), and implies `invalid`. Passing the key keeps the
+   * field's box while there is no message, so the trigger is never remounted.
+   */
+  error?: ReactNode;
+  /** Standing advice, as on a {@link Select}: text is a caption under the field; a
+   *  {@link FieldHint} rides the label line. */
+  hint?: ReactNode;
+  /**
+   * `"md"` (default): the form field. `"sm"`: the toolbar trigger — 36px tall (an
+   * `IconButton`'s height) and as wide as the month it shows, for a picker that sits
+   * between two icon buttons in a page header (keksdose K13: the budget header wrote
+   * `triggerClassName="h-9 w-auto … py-0"` by hand, live #260 — 34px between two 36px
+   * buttons, *"the kind of 2px that reads as sloppy"*). Unlabelled pickers only, as on
+   * {@link Select}: a floating label needs the tall box to float in. The width follows
+   * the month's name; add a `min-w-*` in `triggerClassName` if the buttons beside it
+   * must not move as it changes.
+   */
+  size?: "sm" | "md";
+  /**
+   * `"month"` (default): the value is a month, `"YYYY-MM"`.
+   *
+   * `"year"`: the value is a YEAR, `"YYYY"`, and the panel is a grid of years — kastlan's
+   * budget fiscal year (a `Select` of 2020 to three years ahead) and keksdose's tax tab
+   * ("this year and four before", tax-tab.tsx:33). `min` / `max` are read as their year
+   * (`"2022"`, or any longer key). A bounded span of twelve years or fewer is shown
+   * whole, with no paging; otherwise the grid pages twelve years at a time (PageUp /
+   * PageDown, or the arrows), starting from `min` when there is one. The stepper
+   * variant steps a year, and its Today button reads "This year".
+   *
+   * A string rather than a number, for the reason the month key is one: it is the
+   * same type across both modes, it crosses a URL as is, and it sorts. A numeric
+   * caller converts with `String(year)` and `Number(key)`.
+   */
+  mode?: "month" | "year";
+  /** Intl options for the trigger's text (default: long month + numeric year, or the
+   *  numeric year in `mode="year"`). Win over the provider's `formatDate`. */
   formatOptions?: Intl.DateTimeFormatOptions;
   /**
    * The month to ring as "now", as `"YYYY-MM"`. Defaults to the local calendar's
@@ -109,8 +161,9 @@ export interface MonthPickerProps extends Omit<ComponentPropsWithoutRef<"div">,
    * `"stepper"`: the header of a month PAGE — the month as a heading that opens the
    * grid, then Today and ‹ › stepping the value by one month. What a calendar page
    * assembled by hand around the field (overriding its trigger to look like a
-   * heading). `label`, `placeholder`, `invalid` and `triggerClassName` are the field's
-   * and are not drawn here; with no `value` the arrows step from the current month.
+   * heading). `label`, `placeholder`, `invalid`, `hint`, `error`, `size` and
+   * `triggerClassName` are the field's and are not drawn here; with no `value` the
+   * arrows step from the current month (or year).
    */
   variant?: "field" | "stepper";
   /** `variant="stepper"`: the heading level the month is set in (`<h2>` by default), or
@@ -160,6 +213,17 @@ function firstOf({ year, month }: YearMonth): Date {
 
 const DEFAULT_TRIGGER_FORMAT: Intl.DateTimeFormatOptions = { month: "long", year: "numeric" };
 const MONTH_NAME_FORMAT: Intl.DateTimeFormatOptions = { month: "long", year: "numeric" };
+const YEAR_FORMAT: Intl.DateTimeFormatOptions = { year: "numeric" };
+
+// ── Year keys ─────────────────────────────────────────────────────────────
+
+const YEAR = /^(\d{4})/;
+
+/** The year of `"YYYY"`, `"YYYY-MM"` or `"YYYY-MM-DD"`, or null. */
+function parseYear(key: string | undefined): number | null {
+  const m = key ? YEAR.exec(key) : null;
+  return m ? Number(m[1]) : null;
+}
 
 // ── Trigger ───────────────────────────────────────────────────────────────
 
@@ -247,6 +311,7 @@ function MonthFieldTrigger({
   valueId,
   panelId,
   padded,
+  small,
   disabled,
   invalid,
   className,
@@ -263,6 +328,8 @@ function MonthFieldTrigger({
   valueId: string;
   panelId: string;
   padded: boolean;
+  /** `size="sm"`: the 36px, content-wide toolbar trigger. */
+  small: boolean;
   disabled?: boolean;
   invalid?: boolean;
   className?: string;
@@ -281,6 +348,7 @@ function MonthFieldTrigger({
       aria-expanded={open}
       id={aria.id}
       aria-invalid={invalid || aria["aria-invalid"] === true || aria["aria-invalid"] === "true" || undefined}
+      aria-required={aria["aria-required"]}
       aria-labelledby={aria["aria-label"] && !aria["aria-labelledby"] ? undefined : labelledBy}
       aria-label={aria["aria-label"]}
       aria-describedby={aria["aria-describedby"]}
@@ -288,6 +356,10 @@ function MonthFieldTrigger({
         FIELD_TRIGGER,
         "pe-9",
         padded && FIELD_FLOATING_PAD,
+        // keksdose K13 (live #260): an IconButton's 36px, and only as wide as the
+        // month — `py-0` with a fixed height so the box is 36px whatever the type's
+        // line height. `pe-9` stays: the calendar glyph still sits at the end.
+        small && "h-9 w-auto py-0",
         disabled && "cursor-not-allowed opacity-50",
         invalid && FIELD_INVALID,
         className,
@@ -522,6 +594,196 @@ function MonthGrid({
   );
 }
 
+/** Years on one page of the year grid: the month grid's 4×3. */
+const YEAR_PAGE = 12;
+
+/**
+ * `mode="year"`'s panel: a page of years between ‹ › arrows — {@link MonthGrid}'s shape
+ * and keyboard, one level up (kastlan 7, keksdose tax-tab.tsx:33).
+ *
+ * Which years a page holds:
+ *  - Bounded on both sides by twelve years or fewer: exactly those years, and no
+ *    arrows — keksdose's "this year and four before" is five cells, not a page of
+ *    twelve with seven greyed out.
+ *  - Otherwise twelve at a time, starting from `min` when there is one (so the first
+ *    page opens on it), else ending at `max`, else on multiples of twelve.
+ *
+ * The arrow keys walk the years (up/down by a row of three), PageUp / PageDown a page,
+ * Home / End the row; walking off a page turns it. Focus stops at the bounds rather
+ * than walking into years that refuse selection: a page has no "next year" past the
+ * last selectable one worth landing on.
+ */
+function YearGrid({
+  value,
+  onPick,
+  locale,
+  minYear,
+  maxYear,
+  currentYear,
+  labels,
+}: {
+  value: number | null;
+  onPick: (key: string) => void;
+  locale: string | undefined;
+  minYear: number | null;
+  maxYear: number | null;
+  currentYear: number;
+  labels: MonthPickerLabels;
+}) {
+  const clamp = (y: number) => Math.min(maxYear ?? y, Math.max(minYear ?? y, y));
+  // A bounded span that fits one page is shown whole.
+  const whole =
+    minYear !== null && maxYear !== null && maxYear >= minYear && maxYear - minYear < YEAR_PAGE
+      ? { first: minYear, count: maxYear - minYear + 1 }
+      : null;
+  // The year holding the tab order, and with it the page on screen — one piece of
+  // state, as in MonthGrid. Opens on the value, or on this year, inside the bounds.
+  const [active, setActive] = useState(() => clamp(value ?? currentYear));
+  const anchor = minYear ?? (maxYear !== null ? maxYear - (YEAR_PAGE - 1) : 0);
+  const first = whole ? whole.first : anchor + Math.floor((active - anchor) / YEAR_PAGE) * YEAR_PAGE;
+  const count = whole ? whole.count : YEAR_PAGE;
+  const years = Array.from({ length: count }, (_, i) => first + i);
+  const outOfBounds = (y: number) => (minYear !== null && y < minYear) || (maxYear !== null && y > maxYear);
+
+  const gridRef = useRef<HTMLDivElement>(null);
+  const captionId = `${useId()}-years`;
+  const yearFormat = useMemo(() => new Intl.DateTimeFormat(locale, YEAR_FORMAT), [locale]);
+  // "2016–2027" in the locale's own range punctuation and digits.
+  const caption = yearFormat.formatRange(new Date(first, 0, 1), new Date(first + count - 1, 0, 1));
+
+  const pendingFocus = useRef<number | null>(null);
+  useEffect(() => {
+    const year = pendingFocus.current;
+    if (year === null) return;
+    pendingFocus.current = null;
+    gridRef.current?.querySelector<HTMLElement>(`[data-year="${year}"]`)?.focus();
+  });
+  // Opened to pick a year: land on it (before the popover's trap, which keeps it).
+  useEffect(() => {
+    gridRef.current?.querySelector<HTMLElement>('[tabindex="0"]')?.focus();
+  }, []);
+
+  const moveTo = (next: number, focus: boolean) => {
+    const year = clamp(next);
+    if (focus) pendingFocus.current = year;
+    setActive(year);
+  };
+
+  const onCellKeyDown = (e: KeyboardEvent<HTMLButtonElement>) => {
+    const step = horizontalStep(e.key, e.currentTarget);
+    const col = (active - first) % COLUMNS;
+    let delta: number;
+    switch (step ? "horizontal" : e.key) {
+      case "horizontal":
+        delta = step;
+        break;
+      case "ArrowUp":
+        delta = -COLUMNS;
+        break;
+      case "ArrowDown":
+        delta = COLUMNS;
+        break;
+      case "Home":
+        delta = -col;
+        break;
+      case "End":
+        delta = Math.min(COLUMNS - 1 - col, first + count - 1 - active);
+        break;
+      case "PageUp":
+        delta = -YEAR_PAGE;
+        break;
+      case "PageDown":
+        delta = YEAR_PAGE;
+        break;
+      default:
+        return;
+    }
+    e.preventDefault();
+    if (delta !== 0) moveTo(active + delta, true);
+  };
+
+  const prevBlocked = minYear !== null && first - 1 < minYear;
+  const nextBlocked = maxYear !== null && first + count > maxYear;
+  const arrow =
+    "flex size-7 items-center justify-center rounded text-[var(--text-muted)] hover:bg-[var(--bg-hover)] disabled:cursor-not-allowed disabled:opacity-30 disabled:hover:bg-transparent";
+
+  return (
+    <div className="select-none">
+      <div className={cn("mb-1 flex items-center", whole ? "h-7 justify-center" : "justify-between")}>
+        {!whole && (
+          <button
+            type="button"
+            aria-label={labels.earlierYears}
+            disabled={prevBlocked}
+            onClick={() => moveTo(active - YEAR_PAGE, false)}
+            className={arrow}
+          >
+            <ChevronLeft className="size-4 rtl:-scale-x-100" />
+          </button>
+        )}
+        <div id={captionId} aria-live="polite" className="text-sm font-semibold tabular-nums text-[var(--text-primary)]">
+          {caption}
+        </div>
+        {!whole && (
+          <button
+            type="button"
+            aria-label={labels.laterYears}
+            disabled={nextBlocked}
+            onClick={() => moveTo(active + YEAR_PAGE, false)}
+            className={arrow}
+          >
+            <ChevronRight className="size-4 rtl:-scale-x-100" />
+          </button>
+        )}
+      </div>
+      <div ref={gridRef} role="grid" aria-labelledby={captionId} className="grid gap-1">
+        {Array.from({ length: Math.ceil(count / COLUMNS) }, (_, row) => (
+          <div key={row} role="row" className="grid grid-cols-3 gap-1">
+            {years.slice(row * COLUMNS, row * COLUMNS + COLUMNS).map((year) => {
+              const disabled = outOfBounds(year);
+              const selected = year === value;
+              const current = year === currentYear;
+              return (
+                <button
+                  key={year}
+                  type="button"
+                  role="gridcell"
+                  data-year={year}
+                  tabIndex={year === active ? 0 : -1}
+                  aria-selected={selected}
+                  aria-disabled={disabled || undefined}
+                  aria-current={current ? "date" : undefined}
+                  onClick={() => {
+                    if (disabled) return;
+                    setActive(year);
+                    onPick(String(year));
+                  }}
+                  onKeyDown={onCellKeyDown}
+                  className={cn(
+                    "rounded px-2 py-1.5 text-sm tabular-nums transition-colors",
+                    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset",
+                    selected && !disabled
+                      ? "focus-visible:ring-[var(--brand-contrast)]"
+                      : "focus-visible:ring-[var(--brand)]",
+                    disabled
+                      ? "cursor-not-allowed text-[var(--text-placeholder)]"
+                      : selected
+                        ? "bg-[var(--brand)] text-[var(--brand-contrast)] hover:bg-[var(--brand-hover)]"
+                        : "text-[var(--text-primary)] hover:bg-[var(--bg-hover)]",
+                    current && !selected && !disabled && "ring-1 ring-inset ring-[var(--border-strong)]",
+                  )}
+                >
+                  {yearFormat.format(new Date(year, 0, 1))}
+                </button>
+              );
+            })}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
 // ── Field ─────────────────────────────────────────────────────────────────
 
 /**
@@ -542,83 +804,140 @@ function upperFirst(text: string, locale: string | undefined): string {
   return text.charAt(0).toLocaleUpperCase(locale) + text.slice(1);
 }
 
-export function MonthPicker({
-  value,
-  onChange,
-  locale: localeProp,
-  min,
-  max,
-  label,
-  placeholder,
-  disabled,
-  invalid,
-  formatOptions,
-  currentMonth,
-  labels: labelsProp,
-  className,
-  triggerClassName,
-  variant = "field",
-  headingLevel = 2,
-  showToday = true,
-  ...rest
-}: MonthPickerProps) {
+export function MonthPicker(props: MonthPickerProps) {
+  const {
+    value,
+    onChange,
+    locale: localeProp,
+    min,
+    max,
+    label,
+    placeholder,
+    disabled,
+    invalid,
+    error,
+    hint,
+    size = "md",
+    mode = "month",
+    formatOptions,
+    currentMonth,
+    labels: labelsProp,
+    className,
+    triggerClassName,
+    variant = "field",
+    headingLevel = 2,
+    showToday = true,
+    ...rest
+  } = props;
   const labels = useMonthPickerLabels(labelsProp);
   const locale = useKitLocale(localeProp);
-  const selected = parseMonth(value);
+  const fromProvider = useKitDateFormatter();
+  const years = mode === "year";
+  const selected = years ? null : parseMonth(value);
+  const selectedYear = years ? parseYear(value) : null;
   const minKey = boundKey(min);
   const maxKey = boundKey(max);
+  const minYear = parseYear(min);
+  const maxYear = parseYear(max);
   const currentKey = boundKey(currentMonth) ?? monthKey(new Date());
+  const currentYear = parseYear(currentKey)!;
+  // The key the trigger shows, in the mode's own shape: "YYYY-MM" or "YYYY".
+  const shownKey = years ? (selectedYear !== null ? String(selectedYear) : null) : selected ? toKey(selected) : null;
 
-  const triggerText = selected
-    ? upperFirst(
-        new Intl.DateTimeFormat(locale, formatOptions ?? DEFAULT_TRIGGER_FORMAT).format(
-          firstOf(selected),
+  // The kit's order: `formatOptions` (this field's own Intl look), then the provider's
+  // `formatDate` (keksdose K12 — the app's one way of writing a month), then the default.
+  const triggerText = shownKey
+    ? (formatOptions === undefined &&
+        fromProvider?.(shownKey, { unit: years ? "year" : "month", source: "monthPicker", locale, weekday: false })) ||
+      upperFirst(
+        new Intl.DateTimeFormat(locale, formatOptions ?? (years ? YEAR_FORMAT : DEFAULT_TRIGGER_FORMAT)).format(
+          years ? new Date(selectedYear!, 0, 1) : firstOf(selected!),
         ),
         locale,
       )
     : (placeholder ?? "");
 
   const id = useId();
-  const [aria, wrapperRest] = splitTriggerAria(rest);
+  // keksdose K4: the caption and the error, on the trigger after the caller's own
+  // description. Painted for `invalid` and a message — not for a bare `aria-invalid`,
+  // which this field has never painted for.
+  const messages = useFieldMessages({ hint, error, describedBy: rest["aria-describedby"] });
+  const [ownAria, wrapperRest] = splitTriggerAria(rest);
+  // The field's trigger is described by the caption and the error too; the stepper
+  // draws neither, so its heading keeps the caller's own description.
+  const aria: TriggerAria = { ...ownAria, "aria-describedby": messages.describedBy };
   const labelId = `${id}-label`;
   const valueId = `${id}-value`;
   const panelId = `${id}-panel`;
   // Only a STRING label can double as a name; a ReactNode may hold its own controls.
   const named = typeof label === "string";
+  // `sm` is the toolbar trigger, for an unlabelled picker only (see `size`).
+  const small = size === "sm" && label === undefined;
   // The panel is portalled to <body>, out of the subtree whose `dir` it inherited — an
   // RTL form got an LTR grid. Read when opening (`toggle` is the popover's only way
   // open) and put back on the panel. Also what the arrow keys above read.
   const rootRef = useRef<HTMLDivElement>(null);
   const [dir, setDir] = useState<Direction>("ltr");
+  const panelLabel = years ? labels.yearPanel : labels.panel;
 
-  const grid = (close: () => void) => (
-    <MonthGrid
-      value={selected}
-      locale={locale}
-      minKey={minKey}
-      maxKey={maxKey}
-      currentKey={currentKey}
-      labels={labels}
-      onPick={(key) => {
-        onChange(key);
-        close();
-      }}
-    />
-  );
+  const grid = (close: () => void) =>
+    years ? (
+      <YearGrid
+        value={selectedYear}
+        locale={locale}
+        minYear={minYear}
+        maxYear={maxYear}
+        currentYear={currentYear}
+        labels={labels}
+        onPick={(key) => {
+          onChange(key);
+          close();
+        }}
+      />
+    ) : (
+      <MonthGrid
+        value={selected}
+        locale={locale}
+        minKey={minKey}
+        maxKey={maxKey}
+        currentKey={currentKey}
+        labels={labels}
+        onPick={(key) => {
+          onChange(key);
+          close();
+        }}
+      />
+    );
 
   if (variant === "stepper") {
     // The arrows step from the value, or from "now" when there is none; each is dead
-    // once the month it leads to is out of bounds, and Today once "now" is.
-    const base = selected ?? parseMonth(currentKey)!;
-    const prevKey = toKey(shiftMonth(base, -1));
-    const nextKey = toKey(shiftMonth(base, 1));
-    const outside = (key: string) => Boolean((minKey && key < minKey) || (maxKey && key > maxKey));
+    // once the month (or year) it leads to is out of bounds, and Today once "now" is.
+    let prevKey: string;
+    let nextKey: string;
+    let nowKey: string;
+    let outside: (key: string) => boolean;
+    if (years) {
+      const base = selectedYear ?? currentYear;
+      prevKey = String(base - 1);
+      nextKey = String(base + 1);
+      nowKey = String(currentYear);
+      outside = (key) => {
+        const y = Number(key);
+        return (minYear !== null && y < minYear) || (maxYear !== null && y > maxYear);
+      };
+    } else {
+      const base = selected ?? parseMonth(currentKey)!;
+      prevKey = toKey(shiftMonth(base, -1));
+      nextKey = toKey(shiftMonth(base, 1));
+      nowKey = currentKey;
+      outside = (key) => Boolean((minKey && key < minKey) || (maxKey && key > maxKey));
+    }
     const Heading = headingLevel ? (`h${headingLevel}` as const) : null;
     const trigger = (
       <Popover
         width={256}
         panelId={panelId}
-        labels={{ panel: labels.panel }}
+        labels={{ panel: panelLabel }}
         dir={dir}
         trigger={({ open, toggle, ref }) => (
           <MonthHeadingTrigger
@@ -631,7 +950,7 @@ export function MonthPicker({
             text={triggerText}
             panelId={panelId}
             disabled={disabled}
-            aria={aria}
+            aria={ownAria}
           />
         )}
       >
@@ -646,16 +965,16 @@ export function MonthPicker({
             <Button
               variant="secondary"
               size="sm"
-              disabled={disabled || outside(currentKey)}
+              disabled={disabled || outside(nowKey)}
               onClick={() => {
-                if (currentKey !== value) onChange(currentKey);
+                if (nowKey !== shownKey) onChange(nowKey);
               }}
             >
-              {labels.today}
+              {years ? labels.thisYear : labels.today}
             </Button>
           )}
           <IconButton
-            aria-label={labels.previousMonth}
+            aria-label={years ? labels.previousYear : labels.previousMonth}
             disabled={disabled || outside(prevKey)}
             onClick={() => onChange(prevKey)}
           >
@@ -663,7 +982,7 @@ export function MonthPicker({
             <ChevronLeft className="rtl:-scale-x-100" />
           </IconButton>
           <IconButton
-            aria-label={labels.nextMonth}
+            aria-label={years ? labels.nextYear : labels.nextMonth}
             disabled={disabled || outside(nextKey)}
             onClick={() => onChange(nextKey)}
           >
@@ -674,9 +993,11 @@ export function MonthPicker({
     );
   }
 
-  return (
-    <div {...wrapperRest} ref={rootRef} className={cn("relative", className)}>
-      {label !== undefined && <FieldLabel>{label}</FieldLabel>}
+  const field = (
+    // `w-fit` for the toolbar size: the calendar glyph is placed against this box, and a
+    // full-width box would park it at the far end of the row, away from its trigger.
+    <div {...wrapperRest} ref={rootRef} className={cn("relative", small && "w-fit max-w-full", className)}>
+      {label !== undefined && <FieldLabelLine label={label} hint={messages.labelHint} />}
       {/* The hidden twin the trigger is named by — see DateField. `sr-only-fixed`,
           and inside this `relative` root either way. */}
       {named && (
@@ -687,7 +1008,7 @@ export function MonthPicker({
       <Popover
         width={256}
         panelId={panelId}
-        labels={{ panel: labels.panel }}
+        labels={{ panel: panelLabel }}
         dir={dir}
         trigger={({ open, toggle, ref }) => (
           <MonthFieldTrigger
@@ -698,7 +1019,7 @@ export function MonthPicker({
             }}
             triggerRef={ref}
             triggerText={triggerText}
-            hasValue={selected != null}
+            hasValue={shownKey !== null}
             // As DatePicker: a caller's reference first; an `id` without a label of our
             // own references the trigger itself, so an external <label htmlFor> names it.
             labelledBy={[
@@ -712,8 +1033,9 @@ export function MonthPicker({
             valueId={valueId}
             panelId={panelId}
             padded={label !== undefined}
+            small={small}
             disabled={disabled}
-            invalid={invalid}
+            invalid={invalid || hasContent(error)}
             className={triggerClassName}
           />
         )}
@@ -726,4 +1048,19 @@ export function MonthPicker({
       />
     </div>
   );
+  // An unlabelled picker has no label line: a FieldHint goes at its end, outside the
+  // box, as on an unlabelled Select.
+  const endHint = label === undefined ? messages.labelHint : undefined;
+  return (
+    <FieldBox below={messages.below} reserve={"error" in props || "hint" in props}>
+      {endHint === undefined ? (
+        field
+      ) : (
+        <div className="flex items-center gap-1.5">
+          <div className={cn("min-w-0", !small && "flex-1")}>{field}</div>
+          <span className="flex shrink-0 items-center">{endHint}</span>
+        </div>
+      )}
+    </FieldBox>
+  );
 }