@eifi1/ui-kit 0.20.1 → 0.22.0

package/dist/components/money-field.d.ts

@@ -2,8 +2,10 @@ import * as react from 'react';
 import { ComponentProps, Ref } from 'react';
 import { AmountInput } from './amount-input.js';
 import './calculator.js';
-import '../kit-labels-D1J2_jyD.js';
-import './data-table-labels.js';
+import '../kit-labels-R8mIAc9N.js';
+import '../data-table-labels-B7OdnM0S.js';
+import './data-table-sort.js';
+import './swipeable-row.js';
 import './mini-calendar.js';
 import './calendar-heatmap.js';
 import './popover.js';
@@ -26,7 +28,6 @@ import './sparkline.js';
 import './stat-tile.js';
 import './signature-pad.js';
 import './password-strength.js';
-import './danger-confirm.js';
 import './swatch-picker.js';
 import './tile-radio.js';
 import './icon-picker.js';
@@ -34,11 +35,10 @@ import './dialog-frame.js';
 import './modal.js';
 import '../hooks/use-search-param-state.js';
 import './measured-grid.js';
-import '../feedback-attachment-WFiXJ8We.js';
+import '../feedback-attachment-NhUm7Zga.js';
 import '../feedback/feedback-thread.js';
 import '../feedback/feedback-inbox.js';
 import './account-settings-labels.js';
-import './confirm-dialog.js';
 import './floating-panel.js';
 import './bulk-action-bar.js';
 import './list.js';
@@ -57,14 +57,16 @@ import './write-lock.js';
 import './legal.js';
 import './account-chips.js';
 import '../lib/format.js';
-import '../data-table-3mi2R3so.js';
-import './data-table-sort.js';
-import './swipeable-row.js';
 import './reauth-dialog.js';
 import './server-wake.js';
 import '../lib/server-wake.js';
 import './translation-review-labels.js';
 import '../lib/translation-review.js';
+import './country-select.js';
+import './inline-edit-field.js';
+import '../lib/iban.js';
+import '../lib/phone.js';
+import './sign-chip.js';
 import './numpad-sheet.js';
 
 type AmountInputProps = ComponentProps<typeof AmountInput>;
@@ -93,6 +95,16 @@ interface MoneyFieldProps extends Omit<AmountInputProps, "value" | "onChange" |
  * rounding to the currency's minor unit and `min` / `max` are AmountInput's. A caller-
  * owned sign (`negative`) is not offered: the figure here carries its own minus.
  *
+ * So are two props a table cell needs (keksdose K4, K6): `error`, the message under the
+ * field that paints and describes it like {@link Input}'s, and `calculator={false}`,
+ * for an amount in a close-on-blur inline editor, where a click on the calculator icon
+ * blurs the field and tears the editor down before the popover can open (typed
+ * calculations still evaluate).
+ *
+ * This, not a `NumberField` with `digits={2}`, is the number-valued field for money:
+ * it settles to the CURRENCY's minor unit (JPY 0, CHF 2) and `digits` takes a unit
+ * price's finer scale (kastlan 5).
+ *
  * ```tsx
  * <MoneyField ariaLabel="Amount" currency="CHF" value={row.amount}
  *   onCommit={(amount) => updateRow(row.id, { amount })} />

package/dist/components/money-field.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/money-field.tsx"],"sourcesContent":["import { useState, type ComponentProps, type Ref } from \"react\";\nimport { AmountInput } from \"./amount-input\";\n\ntype AmountInputProps = ComponentProps<typeof AmountInput>;\n\nexport interface MoneyFieldProps\n  extends Omit<AmountInputProps, \"value\" | \"onChange\" | \"onCommit\" | \"negative\" | \"onNegativeChange\" | \"ref\"> {\n  /** The amount, or `null` for an empty field. */\n  value: number | null;\n  /**\n   * The settled amount — on blur, on Enter, on the numpad's \"=\" and on a calculator\n   * result; never a half-typed \"1200+\". Rounded to the currency's minor unit (or\n   * `digits`) and clamped to `min` / `max`, like {@link AmountInput}. `null` when the\n   * field was emptied. Not fired when the settled amount equals `value`, so an\n   * Enter-then-blur saves once.\n   */\n  onCommit: (value: number | null) => void;\n  ref?: Ref<HTMLInputElement>;\n}\n\n/** The number a settled text reads as: `null` for empty, `undefined` for no number\n *  (a lone \"-\" or \".\"). */\nfunction parseSettled(text: string): number | null | undefined {\n  const t = text.trim();\n  if (t === \"\") return null;\n  const n = Number(t);\n  return Number.isFinite(n) ? n : undefined;\n}\n\n/**\n * {@link AmountInput} with a NUMBER in and a number out, for money edited outside a\n * form — a budget row, a table cell (kastlan 52: new-budget-page edited a CHF amount per\n * row with `NumberField` because AmountInput is string-valued and reports every\n * keystroke, \"1200+\" included, so a number-state row needed its own parse-and-settle\n * glue). This is that glue, the same one `RhfMoneyField` has: the text being typed\n * lives here, and only a settled figure reaches `onCommit`.\n *\n * The currency chip, the calculator, the numpad, the locale's decimal mark, the\n * rounding to the currency's minor unit and `min` / `max` are AmountInput's. A caller-\n * owned sign (`negative`) is not offered: the figure here carries its own minus.\n *\n * ```tsx\n * <MoneyField ariaLabel=\"Amount\" currency=\"CHF\" value={row.amount}\n *   onCommit={(amount) => updateRow(row.id, { amount })} />\n * ```\n */\nexport function MoneyField({ value, onCommit, ref, ...props }: MoneyFieldProps) {\n  const external = value === null ? \"\" : String(value);\n  // The draft is re-read from `value` only when `value` moves away from what the draft\n  // already says (a reset, another row's save), so a commit's own echo keeps the\n  // typist's spelling (\"12.50\" stays \"12.50\" when 12.5 comes back).\n  const [draft, setDraft] = useState(external);\n  const [seen, setSeen] = useState(value);\n  if (seen !== value) {\n    setSeen(value);\n    if (parseSettled(draft) !== value) setDraft(external);\n  }\n  return (\n    <AmountInput\n      {...props}\n      ref={ref}\n      value={draft}\n      onChange={setDraft}\n      onCommit={(text) => {\n        const next = parseSettled(text);\n        // No number (\"-\" alone): back to the stored amount rather than a guess.\n        if (next === undefined) {\n          setDraft(external);\n          return;\n        }\n        if (next !== value) onCommit(next);\n      }}\n    />\n  );\n}\n"],"mappings":";AA0DI;AA1DJ,SAAS,gBAA+C;AACxD,SAAS,mBAAmB;AAqB5B,SAAS,aAAa,MAAyC;AAC7D,QAAM,IAAI,KAAK,KAAK;AACpB,MAAI,MAAM,GAAI,QAAO;AACrB,QAAM,IAAI,OAAO,CAAC;AAClB,SAAO,OAAO,SAAS,CAAC,IAAI,IAAI;AAClC;AAmBO,SAAS,WAAW,EAAE,OAAO,UAAU,KAAK,GAAG,MAAM,GAAoB;AAC9E,QAAM,WAAW,UAAU,OAAO,KAAK,OAAO,KAAK;AAInD,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAS,QAAQ;AAC3C,QAAM,CAAC,MAAM,OAAO,IAAI,SAAS,KAAK;AACtC,MAAI,SAAS,OAAO;AAClB,YAAQ,KAAK;AACb,QAAI,aAAa,KAAK,MAAM,MAAO,UAAS,QAAQ;AAAA,EACtD;AACA,SACE;AAAA,IAAC;AAAA;AAAA,MACE,GAAG;AAAA,MACJ;AAAA,MACA,OAAO;AAAA,MACP,UAAU;AAAA,MACV,UAAU,CAAC,SAAS;AAClB,cAAM,OAAO,aAAa,IAAI;AAE9B,YAAI,SAAS,QAAW;AACtB,mBAAS,QAAQ;AACjB;AAAA,QACF;AACA,YAAI,SAAS,MAAO,UAAS,IAAI;AAAA,MACnC;AAAA;AAAA,EACF;AAEJ;","names":[]}
+{"version":3,"sources":["../../src/components/money-field.tsx"],"sourcesContent":["import { useState, type ComponentProps, type Ref } from \"react\";\nimport { AmountInput } from \"./amount-input\";\n\ntype AmountInputProps = ComponentProps<typeof AmountInput>;\n\nexport interface MoneyFieldProps\n  extends Omit<AmountInputProps, \"value\" | \"onChange\" | \"onCommit\" | \"negative\" | \"onNegativeChange\" | \"ref\"> {\n  /** The amount, or `null` for an empty field. */\n  value: number | null;\n  /**\n   * The settled amount — on blur, on Enter, on the numpad's \"=\" and on a calculator\n   * result; never a half-typed \"1200+\". Rounded to the currency's minor unit (or\n   * `digits`) and clamped to `min` / `max`, like {@link AmountInput}. `null` when the\n   * field was emptied. Not fired when the settled amount equals `value`, so an\n   * Enter-then-blur saves once.\n   */\n  onCommit: (value: number | null) => void;\n  ref?: Ref<HTMLInputElement>;\n}\n\n/** The number a settled text reads as: `null` for empty, `undefined` for no number\n *  (a lone \"-\" or \".\"). */\nfunction parseSettled(text: string): number | null | undefined {\n  const t = text.trim();\n  if (t === \"\") return null;\n  const n = Number(t);\n  return Number.isFinite(n) ? n : undefined;\n}\n\n/**\n * {@link AmountInput} with a NUMBER in and a number out, for money edited outside a\n * form — a budget row, a table cell (kastlan 52: new-budget-page edited a CHF amount per\n * row with `NumberField` because AmountInput is string-valued and reports every\n * keystroke, \"1200+\" included, so a number-state row needed its own parse-and-settle\n * glue). This is that glue, the same one `RhfMoneyField` has: the text being typed\n * lives here, and only a settled figure reaches `onCommit`.\n *\n * The currency chip, the calculator, the numpad, the locale's decimal mark, the\n * rounding to the currency's minor unit and `min` / `max` are AmountInput's. A caller-\n * owned sign (`negative`) is not offered: the figure here carries its own minus.\n *\n * So are two props a table cell needs (keksdose K4, K6): `error`, the message under the\n * field that paints and describes it like {@link Input}'s, and `calculator={false}`,\n * for an amount in a close-on-blur inline editor, where a click on the calculator icon\n * blurs the field and tears the editor down before the popover can open (typed\n * calculations still evaluate).\n *\n * This, not a `NumberField` with `digits={2}`, is the number-valued field for money:\n * it settles to the CURRENCY's minor unit (JPY 0, CHF 2) and `digits` takes a unit\n * price's finer scale (kastlan 5).\n *\n * ```tsx\n * <MoneyField ariaLabel=\"Amount\" currency=\"CHF\" value={row.amount}\n *   onCommit={(amount) => updateRow(row.id, { amount })} />\n * ```\n */\nexport function MoneyField({ value, onCommit, ref, ...props }: MoneyFieldProps) {\n  const external = value === null ? \"\" : String(value);\n  // The draft is re-read from `value` only when `value` moves away from what the draft\n  // already says (a reset, another row's save), so a commit's own echo keeps the\n  // typist's spelling (\"12.50\" stays \"12.50\" when 12.5 comes back).\n  const [draft, setDraft] = useState(external);\n  const [seen, setSeen] = useState(value);\n  if (seen !== value) {\n    setSeen(value);\n    if (parseSettled(draft) !== value) setDraft(external);\n  }\n  return (\n    <AmountInput\n      {...props}\n      ref={ref}\n      value={draft}\n      onChange={setDraft}\n      onCommit={(text) => {\n        const next = parseSettled(text);\n        // No number (\"-\" alone): back to the stored amount rather than a guess.\n        if (next === undefined) {\n          setDraft(external);\n          return;\n        }\n        if (next !== value) onCommit(next);\n      }}\n    />\n  );\n}\n"],"mappings":";AAoEI;AApEJ,SAAS,gBAA+C;AACxD,SAAS,mBAAmB;AAqB5B,SAAS,aAAa,MAAyC;AAC7D,QAAM,IAAI,KAAK,KAAK;AACpB,MAAI,MAAM,GAAI,QAAO;AACrB,QAAM,IAAI,OAAO,CAAC;AAClB,SAAO,OAAO,SAAS,CAAC,IAAI,IAAI;AAClC;AA6BO,SAAS,WAAW,EAAE,OAAO,UAAU,KAAK,GAAG,MAAM,GAAoB;AAC9E,QAAM,WAAW,UAAU,OAAO,KAAK,OAAO,KAAK;AAInD,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAS,QAAQ;AAC3C,QAAM,CAAC,MAAM,OAAO,IAAI,SAAS,KAAK;AACtC,MAAI,SAAS,OAAO;AAClB,YAAQ,KAAK;AACb,QAAI,aAAa,KAAK,MAAM,MAAO,UAAS,QAAQ;AAAA,EACtD;AACA,SACE;AAAA,IAAC;AAAA;AAAA,MACE,GAAG;AAAA,MACJ;AAAA,MACA,OAAO;AAAA,MACP,UAAU;AAAA,MACV,UAAU,CAAC,SAAS;AAClB,cAAM,OAAO,aAAa,IAAI;AAE9B,YAAI,SAAS,QAAW;AACtB,mBAAS,QAAQ;AACjB;AAAA,QACF;AACA,YAAI,SAAS,MAAO,UAAS,IAAI;AAAA,MACnC;AAAA;AAAA,EACF;AAEJ;","names":[]}

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

@@ -23,6 +23,15 @@ 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
  *  calendar's) because it is asked for by name: a host building its own translation
@@ -64,7 +73,45 @@ interface MonthPickerProps extends Omit<ComponentPropsWithoutRef<"div">, "onChan
     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
@@ -84,8 +131,9 @@ interface MonthPickerProps extends Omit<ComponentPropsWithoutRef<"div">, "onChan
      * `"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
@@ -94,6 +142,6 @@ interface MonthPickerProps extends Omit<ComponentPropsWithoutRef<"div">, "onChan
     /** `variant="stepper"`: draw the Today button. Default `true`. */
     showToday?: boolean;
 }
-declare function MonthPicker({ value, onChange, locale: localeProp, min, max, label, placeholder, disabled, invalid, formatOptions, currentMonth, labels: labelsProp, className, triggerClassName, variant, headingLevel, showToday, ...rest }: MonthPickerProps): react.JSX.Element;
+declare function MonthPicker(props: MonthPickerProps): react.JSX.Element;
 
 export { DEFAULT_MONTH_PICKER_LABELS, MonthPicker, type MonthPickerLabels, type MonthPickerProps };

package/dist/components/month-picker.js

@@ -5,10 +5,11 @@ import { Calendar, ChevronDown, ChevronLeft, ChevronRight } from "lucide-react";
 import { cn } from "../lib/cn.js";
 import { dirOf, horizontalStep } from "../lib/direction.js";
 import { monthKey, pad } from "../lib/dates.js";
-import { Button, FieldLabel, FIELD_FLOATING_PAD, FIELD_INVALID, FIELD_TRIGGER, IconButton } from "./ui.js";
+import { Button, FIELD_FLOATING_PAD, FIELD_INVALID, FIELD_TRIGGER, IconButton } from "./ui.js";
 import { Popover } from "./popover.js";
 import { splitTriggerAria } from "./trigger-aria.js";
-import { useKitLabels, useKitLocale } from "../i18n/kit-labels.js";
+import { useKitDateFormatter, useKitLabels, useKitLocale } from "../i18n/kit-labels.js";
+import { FieldBox, FieldLabelLine, hasContent, useFieldMessages } from "./field-anatomy.js";
 const DEFAULT_MONTH_PICKER_LABELS = {
   previousYear: "Previous year",
   nextYear: "Next year",
@@ -16,7 +17,11 @@ const DEFAULT_MONTH_PICKER_LABELS = {
   month: (monthYear) => monthYear,
   previousMonth: "Previous month",
   nextMonth: "Next month",
-  today: "Today"
+  today: "Today",
+  yearPanel: "Choose a year",
+  earlierYears: "Earlier years",
+  laterYears: "Later years",
+  thisYear: "This year"
 };
 function useMonthPickerLabels(partial) {
   return useKitLabels("monthPicker", DEFAULT_MONTH_PICKER_LABELS, partial);
@@ -44,6 +49,12 @@ function firstOf({ year, month }) {
 }
 const DEFAULT_TRIGGER_FORMAT = { month: "long", year: "numeric" };
 const MONTH_NAME_FORMAT = { month: "long", year: "numeric" };
+const YEAR_FORMAT = { year: "numeric" };
+const YEAR = /^(\d{4})/;
+function parseYear(key) {
+  const m = key ? YEAR.exec(key) : null;
+  return m ? Number(m[1]) : null;
+}
 function useFocusBackOnClose(open, triggerRef) {
   const wasOpen = useRef(false);
   useEffect(() => {
@@ -100,6 +111,7 @@ function MonthFieldTrigger({
   valueId,
   panelId,
   padded,
+  small,
   disabled,
   invalid,
   className,
@@ -126,6 +138,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
@@ -291,50 +307,212 @@ function MonthGrid({
     }) }, row)) })
   ] });
 }
+const YEAR_PAGE = 12;
+function YearGrid({
+  value,
+  onPick,
+  locale,
+  minYear,
+  maxYear,
+  currentYear,
+  labels
+}) {
+  const clamp = (y) => Math.min(maxYear ?? y, Math.max(minYear ?? y, y));
+  const whole = minYear !== null && maxYear !== null && maxYear >= minYear && maxYear - minYear < YEAR_PAGE ? { first: minYear, count: maxYear - minYear + 1 } : null;
+  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) => minYear !== null && y < minYear || maxYear !== null && y > maxYear;
+  const gridRef = useRef(null);
+  const captionId = `${useId()}-years`;
+  const yearFormat = useMemo(() => new Intl.DateTimeFormat(locale, YEAR_FORMAT), [locale]);
+  const caption = yearFormat.formatRange(new Date(first, 0, 1), new Date(first + count - 1, 0, 1));
+  const pendingFocus = useRef(null);
+  useEffect(() => {
+    const year = pendingFocus.current;
+    if (year === null) return;
+    pendingFocus.current = null;
+    gridRef.current?.querySelector(`[data-year="${year}"]`)?.focus();
+  });
+  useEffect(() => {
+    gridRef.current?.querySelector('[tabindex="0"]')?.focus();
+  }, []);
+  const moveTo = (next, focus) => {
+    const year = clamp(next);
+    if (focus) pendingFocus.current = year;
+    setActive(year);
+  };
+  const onCellKeyDown = (e) => {
+    const step = horizontalStep(e.key, e.currentTarget);
+    const col = (active - first) % COLUMNS;
+    let delta;
+    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 /* @__PURE__ */ jsxs("div", { className: "select-none", children: [
+    /* @__PURE__ */ jsxs("div", { className: cn("mb-1 flex items-center", whole ? "h-7 justify-center" : "justify-between"), children: [
+      !whole && /* @__PURE__ */ jsx(
+        "button",
+        {
+          type: "button",
+          "aria-label": labels.earlierYears,
+          disabled: prevBlocked,
+          onClick: () => moveTo(active - YEAR_PAGE, false),
+          className: arrow,
+          children: /* @__PURE__ */ jsx(ChevronLeft, { className: "size-4 rtl:-scale-x-100" })
+        }
+      ),
+      /* @__PURE__ */ jsx("div", { id: captionId, "aria-live": "polite", className: "text-sm font-semibold tabular-nums text-[var(--text-primary)]", children: caption }),
+      !whole && /* @__PURE__ */ jsx(
+        "button",
+        {
+          type: "button",
+          "aria-label": labels.laterYears,
+          disabled: nextBlocked,
+          onClick: () => moveTo(active + YEAR_PAGE, false),
+          className: arrow,
+          children: /* @__PURE__ */ jsx(ChevronRight, { className: "size-4 rtl:-scale-x-100" })
+        }
+      )
+    ] }),
+    /* @__PURE__ */ jsx("div", { ref: gridRef, role: "grid", "aria-labelledby": captionId, className: "grid gap-1", children: Array.from({ length: Math.ceil(count / COLUMNS) }, (_, row) => /* @__PURE__ */ jsx("div", { role: "row", className: "grid grid-cols-3 gap-1", children: years.slice(row * COLUMNS, row * COLUMNS + COLUMNS).map((year) => {
+      const disabled = outOfBounds(year);
+      const selected = year === value;
+      const current = year === currentYear;
+      return /* @__PURE__ */ jsx(
+        "button",
+        {
+          type: "button",
+          role: "gridcell",
+          "data-year": year,
+          tabIndex: year === active ? 0 : -1,
+          "aria-selected": selected,
+          "aria-disabled": disabled || void 0,
+          "aria-current": current ? "date" : void 0,
+          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)]"
+          ),
+          children: yearFormat.format(new Date(year, 0, 1))
+        },
+        year
+      );
+    }) }, row)) })
+  ] });
+}
 function upperFirst(text, locale) {
   return text.charAt(0).toLocaleUpperCase(locale) + text.slice(1);
 }
-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
-}) {
+function MonthPicker(props) {
+  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(/* @__PURE__ */ new Date());
-  const triggerText = selected ? upperFirst(
-    new Intl.DateTimeFormat(locale, formatOptions ?? DEFAULT_TRIGGER_FORMAT).format(
-      firstOf(selected)
+  const currentYear = parseYear(currentKey);
+  const shownKey = years ? selectedYear !== null ? String(selectedYear) : null : selected ? toKey(selected) : null;
+  const triggerText = shownKey ? formatOptions === void 0 && 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);
+  const messages = useFieldMessages({ hint, error, describedBy: rest["aria-describedby"] });
+  const [ownAria, wrapperRest] = splitTriggerAria(rest);
+  const aria = { ...ownAria, "aria-describedby": messages.describedBy };
   const labelId = `${id}-label`;
   const valueId = `${id}-value`;
   const panelId = `${id}-panel`;
   const named = typeof label === "string";
+  const small = size === "sm" && label === void 0;
   const rootRef = useRef(null);
   const [dir, setDir] = useState("ltr");
-  const grid = (close) => /* @__PURE__ */ jsx(
+  const panelLabel = years ? labels.yearPanel : labels.panel;
+  const grid = (close) => years ? /* @__PURE__ */ jsx(
+    YearGrid,
+    {
+      value: selectedYear,
+      locale,
+      minYear,
+      maxYear,
+      currentYear,
+      labels,
+      onPick: (key) => {
+        onChange(key);
+        close();
+      }
+    }
+  ) : /* @__PURE__ */ jsx(
     MonthGrid,
     {
       value: selected,
@@ -350,17 +528,33 @@ function MonthPicker({
     }
   );
   if (variant === "stepper") {
-    const base = selected ?? parseMonth(currentKey);
-    const prevKey = toKey(shiftMonth(base, -1));
-    const nextKey = toKey(shiftMonth(base, 1));
-    const outside = (key) => Boolean(minKey && key < minKey || maxKey && key > maxKey);
+    let prevKey;
+    let nextKey;
+    let nowKey;
+    let outside;
+    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}` : null;
     const trigger = /* @__PURE__ */ jsx(
       Popover,
       {
         width: 256,
         panelId,
-        labels: { panel: labels.panel },
+        labels: { panel: panelLabel },
         dir,
         trigger: ({ open, toggle, ref }) => /* @__PURE__ */ jsx(
           MonthHeadingTrigger,
@@ -374,7 +568,7 @@ function MonthPicker({
             text: triggerText,
             panelId,
             disabled,
-            aria
+            aria: ownAria
           }
         ),
         children: grid
@@ -388,17 +582,17 @@ function MonthPicker({
           {
             variant: "secondary",
             size: "sm",
-            disabled: disabled || outside(currentKey),
+            disabled: disabled || outside(nowKey),
             onClick: () => {
-              if (currentKey !== value) onChange(currentKey);
+              if (nowKey !== shownKey) onChange(nowKey);
             },
-            children: labels.today
+            children: years ? labels.thisYear : labels.today
           }
         ),
         /* @__PURE__ */ jsx(
           IconButton,
           {
-            "aria-label": labels.previousMonth,
+            "aria-label": years ? labels.previousYear : labels.previousMonth,
             disabled: disabled || outside(prevKey),
             onClick: () => onChange(prevKey),
             children: /* @__PURE__ */ jsx(ChevronLeft, { className: "rtl:-scale-x-100" })
@@ -407,7 +601,7 @@ function MonthPicker({
         /* @__PURE__ */ jsx(
           IconButton,
           {
-            "aria-label": labels.nextMonth,
+            "aria-label": years ? labels.nextYear : labels.nextMonth,
             disabled: disabled || outside(nextKey),
             onClick: () => onChange(nextKey),
             children: /* @__PURE__ */ jsx(ChevronRight, { className: "rtl:-scale-x-100" })
@@ -416,52 +610,62 @@ function MonthPicker({
       ] })
     ] });
   }
-  return /* @__PURE__ */ jsxs("div", { ...wrapperRest, ref: rootRef, className: cn("relative", className), children: [
-    label !== void 0 && /* @__PURE__ */ jsx(FieldLabel, { children: label }),
-    named && /* @__PURE__ */ jsx("span", { id: labelId, "aria-hidden": true, className: "sr-only-fixed", children: label }),
-    /* @__PURE__ */ jsx(
-      Popover,
-      {
-        width: 256,
-        panelId,
-        labels: { panel: labels.panel },
-        dir,
-        trigger: ({ open, toggle, ref }) => /* @__PURE__ */ jsx(
-          MonthFieldTrigger,
-          {
-            open,
-            toggle: () => {
-              setDir(dirOf(rootRef.current));
-              toggle();
-            },
-            triggerRef: ref,
-            triggerText,
-            hasValue: selected != null,
-            labelledBy: [
-              aria["aria-labelledby"],
-              named ? labelId : !aria["aria-labelledby"] && aria.id ? aria.id : void 0,
-              valueId
-            ].filter(Boolean).join(" "),
-            aria,
-            valueId,
-            panelId,
-            padded: label !== void 0,
-            disabled,
-            invalid,
-            className: triggerClassName
-          }
-        ),
-        children: grid
-      }
-    ),
-    /* @__PURE__ */ jsx(
-      Calendar,
-      {
-        "aria-hidden": true,
-        className: "pointer-events-none absolute end-2.5 top-1/2 size-4 -translate-y-1/2 text-[var(--text-placeholder)]"
-      }
-    )
-  ] });
+  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.
+    /* @__PURE__ */ jsxs("div", { ...wrapperRest, ref: rootRef, className: cn("relative", small && "w-fit max-w-full", className), children: [
+      label !== void 0 && /* @__PURE__ */ jsx(FieldLabelLine, { label, hint: messages.labelHint }),
+      named && /* @__PURE__ */ jsx("span", { id: labelId, "aria-hidden": true, className: "sr-only-fixed", children: label }),
+      /* @__PURE__ */ jsx(
+        Popover,
+        {
+          width: 256,
+          panelId,
+          labels: { panel: panelLabel },
+          dir,
+          trigger: ({ open, toggle, ref }) => /* @__PURE__ */ jsx(
+            MonthFieldTrigger,
+            {
+              open,
+              toggle: () => {
+                setDir(dirOf(rootRef.current));
+                toggle();
+              },
+              triggerRef: ref,
+              triggerText,
+              hasValue: shownKey !== null,
+              labelledBy: [
+                aria["aria-labelledby"],
+                named ? labelId : !aria["aria-labelledby"] && aria.id ? aria.id : void 0,
+                valueId
+              ].filter(Boolean).join(" "),
+              aria,
+              valueId,
+              panelId,
+              padded: label !== void 0,
+              small,
+              disabled,
+              invalid: invalid || hasContent(error),
+              className: triggerClassName
+            }
+          ),
+          children: grid
+        }
+      ),
+      /* @__PURE__ */ jsx(
+        Calendar,
+        {
+          "aria-hidden": true,
+          className: "pointer-events-none absolute end-2.5 top-1/2 size-4 -translate-y-1/2 text-[var(--text-placeholder)]"
+        }
+      )
+    ] })
+  );
+  const endHint = label === void 0 ? messages.labelHint : void 0;
+  return /* @__PURE__ */ jsx(FieldBox, { below: messages.below, reserve: "error" in props || "hint" in props, children: endHint === void 0 ? field : /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-1.5", children: [
+    /* @__PURE__ */ jsx("div", { className: cn("min-w-0", !small && "flex-1"), children: field }),
+    /* @__PURE__ */ jsx("span", { className: "flex shrink-0 items-center", children: endHint })
+  ] }) });
 }
 export {
   DEFAULT_MONTH_PICKER_LABELS,