@eifi1/ui-kit 0.22.0 → 0.24.0

package/src/rhf/fields.tsx

@@ -9,10 +9,13 @@
  *   <RhfDateField name="start" label="Start" />
  *   <RhfSelect name="type" label="Type" options={TYPES} />
  *   <RhfCombobox name="tenantId" label="Tenant" options={tenants} clearable />
+ *   <RhfInlineEntityCombobox name="accountId" label="Account" options={accounts} />
  *   <RhfCheckbox name="isDefault" label="Default account" />
  *   <RhfTimeInput name="meetingTime" label="Time" />
  *   <RhfDateRangePicker fromName="periodFrom" toName="periodTo" label="Period" />
  *   <RhfToggleGroup name="interval" label="Interval" options={INTERVALS} />
+ *   <RhfCountrySelect name="country" label="Country" preferred={["CH", "DE"]} />
+ *   <RhfMonthPicker name="fiscalYear" label="Fiscal year" mode="year" valueAsNumber />
  * </Form>
  * ```
  *
@@ -66,6 +69,8 @@ import {
 import { TimeInput, type TimeInputProps } from "../components/time-input";
 import { IbanInput, type IbanInputProps } from "../components/iban-input";
 import { PhoneInput, type PhoneInputProps } from "../components/phone-input";
+import { CountrySelect, type CountrySelectProps } from "../components/country-select";
+import { MonthPicker, type MonthPickerProps } from "../components/month-picker";
 import {
   ToggleGroup,
   type ToggleGroupBaseProps,
@@ -74,7 +79,12 @@ import {
 } from "../components/toggle-group";
 import { Checkbox, type CheckboxProps } from "../components/checkbox";
 import { EntityCombobox, type EntityComboboxProps } from "../components/entity-combobox";
-import { Combobox, type ComboboxProps } from "../components/combobox";
+import {
+  Combobox,
+  InlineEntityCombobox,
+  type ComboboxProps,
+  type InlineEntityComboboxProps,
+} from "../components/combobox";
 import type { ComboClearValue } from "../components/combobox-core";
 import { cn } from "../lib/cn";
 
@@ -571,6 +581,10 @@ export type RhfMoneyFieldProps<
    *  with `rules` as well if a clamp needs explaining. */
   min?: number;
   max?: number;
+  /** Classes for the `<input>` — `className` is the item's box. {@link RhfTextField},
+   *  {@link RhfTextarea} and {@link RhfNumberField} take it; since 0.23 AmountInput
+   *  does too (keksdose G7: `text-end` for a money column). */
+  inputClassName?: string;
 };
 
 /** The amount a text reads as, or `undefined` for a draft that is not one yet. */
@@ -1197,6 +1211,252 @@ export function RhfPhoneInput<
   );
 }
 
+// ── country and month (0.23) ─────────────────────────────────────────────────
+
+type OwnCountrySelectProps = Omit<
+  CountrySelectProps<boolean>,
+  | "value"
+  | "onChange"
+  | "onBlur"
+  | "label"
+  | "hint"
+  | "error"
+  | "invalid"
+  | "disabled"
+  | "className"
+  | "id"
+  | "ref"
+  | "clearable"
+>;
+
+export type RhfCountrySelectProps<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+  TTransformed = TFieldValues,
+> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> &
+  OwnCountrySelectProps & {
+    /** Offer the picker's clear "×" (and Delete on the trigger) while a country is
+     *  chosen. A clear stores `clearValue`. */
+    clearable?: boolean;
+    /** What a clear stores. Default `null`; `""` for a schema that spells "no
+     *  country" as an empty string (a zod `z.string().max(2)`, kastlan's). The picker
+     *  reads either back as empty. */
+    clearValue?: ComboClearValue;
+    /** Classes for the picker — `className` is the item's box. */
+    selectClassName?: string;
+  };
+
+/**
+ * {@link CountrySelect} bound to one field, which stores the ISO 3166-1 alpha-2 code
+ * ("CH", always upper-case), or `clearValue` once cleared (`clearable`). kastlan asked
+ * for it (0.22 adoption): its address form wired a `CountrySelect` through
+ * {@link RhfField}'s render, and with no ref on the picker react-hook-form's
+ * focus-on-error had nothing to focus — the one field on the form a failed submit
+ * could not take you to.
+ *
+ * Bound the way {@link RhfIbanInput} and {@link RhfPhoneInput} are: `field.ref` reaches
+ * the trigger (the picker's `ref`, 0.23), the form's error paints the trigger and is
+ * the shell's message under it, the hint is the shell's description — so neither is
+ * ever handed to the picker, and its box never changes when one comes or goes. The
+ * form's label names the trigger together with the chosen country, and is the phone
+ * sheet's title. `commit` and `disabledReason` are the picker's own: a country that
+ * saves itself stays focusable under a lock and says why.
+ *
+ * ```tsx
+ * <RhfCountrySelect name="country" label="Country" required
+ *   preferred={["CH", "LI", "DE", "AT", "FR", "IT"]} rules={{ required: "Choose a country" }} />
+ * ```
+ */
+export function RhfCountrySelect<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+  TTransformed = TFieldValues,
+>({
+  name,
+  control,
+  rules,
+  label,
+  hint,
+  required,
+  disabled,
+  excludeWhenDisabled,
+  className,
+  clearable,
+  clearValue = null,
+  selectClassName,
+  labels,
+  ...countryProps
+}: RhfCountrySelectProps<TFieldValues, TName, TTransformed>) {
+  const labelled = hasContent(label);
+  // A string label is also what the field IS — the picker's `country` word, which
+  // titles the phone sheet. A caller's own `labels.country` still wins.
+  const ownLabels = typeof label === "string" ? { country: label, ...labels } : labels;
+  return (
+    <RhfField
+      {...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className }}
+      render={({ field, invalid, labelId }) => {
+        const value: unknown = field.value;
+        return (
+          // FormControl clones this element with `id` / `aria-describedby` /
+          // `aria-invalid`, which the picker routes to its trigger.
+          <CountrySelect<boolean>
+            aria-required={required || undefined}
+            // The form's label, then the country (see the picker's `aria-labelledby`).
+            aria-labelledby={labelled ? labelId : undefined}
+            {...countryProps}
+            labels={ownLabels}
+            className={selectClassName}
+            ref={field.ref}
+            value={typeof value === "string" ? value : null}
+            clearable={clearable}
+            onChange={(code) => field.onChange(code ?? clearValue)}
+            // Focus leaving the picker (the wrapper's focusout) marks the field touched.
+            onBlur={field.onBlur}
+            disabled={field.disabled}
+            invalid={invalid}
+          />
+        );
+      }}
+    />
+  );
+}
+
+type OwnMonthPickerProps = Omit<
+  MonthPickerProps,
+  "value" | "onChange" | "onBlur" | "label" | "hint" | "error" | "invalid" | "disabled" | "className" | "id" | "mode"
+>;
+
+/** `mode` picks what the form stores, and `valueAsNumber` is only offered for a year. */
+type RhfMonthPickerMode =
+  | {
+      /** A month, stored as `"YYYY-MM"` (the default). */
+      mode?: "month";
+      valueAsNumber?: undefined;
+    }
+  | {
+      /** A year, stored as `"YYYY"` — or as a number with `valueAsNumber`. */
+      mode: "year";
+      /** Store the year as a number (`2026`) rather than `"2026"` — kastlan's budget
+       *  `fiscal_year` is an integer column. A number in the form reads back as its
+       *  year. */
+      valueAsNumber?: boolean;
+    };
+
+export type RhfMonthPickerProps<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+  TTransformed = TFieldValues,
+> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> &
+  OwnMonthPickerProps & {
+    /** Classes for the picker — `className` is the item's box. As {@link RhfDateField}'s. */
+    inputClassName?: string;
+  } & RhfMonthPickerMode;
+
+function MonthControl({
+  field,
+  invalid,
+  id,
+  valueAsNumber,
+  mode,
+  inputClassName,
+  pickerProps,
+  required,
+  ...aria
+}: {
+  field: ControllerRenderProps;
+  invalid: boolean;
+  id: string;
+  valueAsNumber?: boolean;
+  mode?: "month" | "year";
+  inputClassName?: string;
+  pickerProps: OwnMonthPickerProps;
+  required?: boolean;
+  "aria-describedby"?: string;
+  "aria-invalid"?: MonthPickerProps["aria-invalid"];
+}) {
+  // MonthPicker forwards no ref; it routes `id` to its trigger, where the handle finds
+  // it — RhfDateField's way.
+  useFocusHandle(field.ref, () => document.getElementById(id));
+  const value: unknown = field.value;
+  return (
+    <MonthPicker
+      {...pickerProps}
+      {...aria}
+      // MonthPicker routes `aria-required` to its trigger since 0.23.0.
+      aria-required={required || undefined}
+      id={id}
+      mode={mode}
+      value={value === null || value === undefined ? "" : String(value)}
+      onChange={(key) => {
+        field.onChange(mode === "year" && valueAsNumber ? Number(key) : key);
+        // A pick is the whole interaction — there is no text to leave — so it touches.
+        field.onBlur();
+      }}
+      disabled={field.disabled}
+      invalid={invalid}
+      className={inputClassName}
+    />
+  );
+}
+
+/**
+ * {@link MonthPicker} bound to one field: a month as `"YYYY-MM"`, or with `mode="year"` a
+ * year as `"YYYY"` (`valueAsNumber` stores `2026`). kastlan asked for it with
+ * {@link RhfCountrySelect}: its budget wizard's fiscal year was a `MonthPicker
+ * mode="year"` inside {@link RhfField}'s render — the `String()` in, the `Number()`
+ * out, `invalid` by hand — and a failed submit could not focus it, because the picker
+ * forwards no ref.
+ *
+ * Bound as {@link RhfDateField} is: a focus handle finds the trigger by its id, so
+ * focus-on-error lands there; the form's error paints the trigger and is the shell's
+ * message; the hint is the shell's description; neither is handed to the picker, so
+ * its box never changes. Picking marks the field touched.
+ *
+ * ```tsx
+ * <RhfMonthPicker name="fiscalYear" label="Fiscal year" mode="year" valueAsNumber
+ *   min="2020" max="2029" rules={{ required: "Choose a year" }} />
+ * ```
+ */
+export function RhfMonthPicker<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+  TTransformed = TFieldValues,
+>({
+  name,
+  control,
+  rules,
+  label,
+  hint,
+  required,
+  disabled,
+  excludeWhenDisabled,
+  className,
+  inputClassName,
+  mode,
+  valueAsNumber,
+  ...pickerProps
+}: RhfMonthPickerProps<TFieldValues, TName, TTransformed>) {
+  return (
+    <RhfField
+      {...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className }}
+      render={({ field, invalid, id }) => (
+        // FormControl clones this element with `aria-describedby` / `aria-invalid`,
+        // which MonthControl hands on to the picker's trigger.
+        <MonthControl
+          field={field as unknown as ControllerRenderProps}
+          invalid={invalid}
+          id={id}
+          mode={mode}
+          valueAsNumber={valueAsNumber}
+          inputClassName={inputClassName}
+          pickerProps={pickerProps}
+          required={required}
+        />
+      )}
+    />
+  );
+}
+
 // ── select ───────────────────────────────────────────────────────────────────
 
 export interface RhfSelectOption {
@@ -1515,11 +1775,17 @@ export type RhfComboboxProps<
     | "emptyLabel"
     | "clearable"
     | "clearLabel"
+    | "closeLabel"
     | "onCreate"
     | "createLabel"
+    | "createEmptyLabel"
+    | "createCommit"
+    | "commit"
+    | "disabledReason"
     | "filter"
     | "minChars"
     | "debounceMs"
+    | "aria-label"
   > & {
     /** What a clear stores — the picker's `clearValue`. Default `null`; `""` for a
      *  schema that spells "no choice" as an empty string. */
@@ -1537,6 +1803,8 @@ function EntityControl<V extends string | number>({
   describedBy,
   clearValue,
   comboClassName,
+  sheetTitle,
+  focusRef,
   comboProps,
 }: {
   field: ControllerRenderProps;
@@ -1547,12 +1815,15 @@ function EntityControl<V extends string | number>({
   describedBy: string | undefined;
   clearValue: ComboClearValue;
   comboClassName?: string;
+  sheetTitle: ReactNode;
+  /** `field.ref`, handed over on its own so the compiler reads `field` as data. */
+  focusRef: ControllerRenderProps["ref"];
   comboProps: Omit<RhfComboboxProps<FieldValues, string, V>, keyof RhfFieldBaseProps | "clearValue" | "comboClassName">;
 }) {
   const box = useRef<HTMLDivElement>(null);
   // EntityCombobox puts `id` and the ARIA below on its trigger, so the label's
-  // `htmlFor` names it, the hint describes it and the focus handle finds it by id.
-  useFocusHandle(field.ref, () => document.getElementById(id));
+  // `htmlFor` names it and the hint describes it; `field.ref` reaches the trigger
+  // through the picker's own `ref` (0.24), as RhfCountrySelect's does.
   // EntityCombobox reports no blur: focus leaving the picker marks the field touched.
   const onBlur = field.onBlur;
   useLayoutEffect(() => {
@@ -1565,7 +1836,11 @@ function EntityControl<V extends string | number>({
   return (
     <div ref={box}>
       <EntityCombobox<V, ComboClearValue>
+        // The form's label titles the phone sheet: the picker is not handed `label`,
+        // which the FormLabel above already draws.
+        sheetTitle={sheetTitle}
         {...comboProps}
+        ref={focusRef}
         className={comboClassName}
         id={id}
         aria-describedby={describedBy}
@@ -1587,6 +1862,14 @@ function EntityControl<V extends string | number>({
  * The kit's {@link EntityCombobox}: an id-keyed pick from `options` or `loadOptions`.
  * Stores the option's `value`, or `clearValue` on a clear (only offered with
  * `clearable`).
+ *
+ * 0.24: `field.ref` goes through the picker's own `ref` to its trigger (it used to be
+ * a focus handle that found the trigger by id — the same element, now by the route
+ * every other binding takes); the write lock (`commit`, `disabledReason`), the create
+ * row's `createEmptyLabel` / `createCommit`, `closeLabel` and `aria-label` pass
+ * through; and the form's label titles the phone sheet, which fell back to the
+ * placeholder. For the INLINE picker — a text input, the account field typed into —
+ * see {@link RhfInlineEntityCombobox}.
  */
 export function RhfCombobox<
   TFieldValues extends FieldValues = FieldValues,
@@ -1622,6 +1905,8 @@ export function RhfCombobox<
           describedBy={describedBy}
           clearValue={clearValue}
           comboClassName={comboClassName}
+          sheetTitle={hasContent(label) ? label : undefined}
+          focusRef={field.ref}
           comboProps={comboProps}
         />
       )}
@@ -1629,6 +1914,123 @@ export function RhfCombobox<
   );
 }
 
+type OwnInlineEntityComboboxProps<V extends string | number> = Omit<
+  InlineEntityComboboxProps<V, ComboClearValue>,
+  | "value"
+  | "defaultValue"
+  | "onChange"
+  | "onBlur"
+  | "label"
+  | "hint"
+  | "error"
+  | "invalid"
+  | "disabled"
+  | "className"
+  | "id"
+  | "ref"
+  | "clearValue"
+>;
+
+export type RhfInlineEntityComboboxProps<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+  V extends string | number = string | number,
+  TTransformed = TFieldValues,
+> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> &
+  OwnInlineEntityComboboxProps<V> & {
+    /** What a clear stores — emptying the text, or the "×" with `clearable`. Default
+     *  `null`; `""` for a schema that spells "no choice" as an empty string. The
+     *  picker reads either back as empty. */
+    clearValue?: ComboClearValue;
+    /** Classes for the picker — `className` is the item's box. As {@link RhfCombobox}'s. */
+    comboClassName?: string;
+  };
+
+/**
+ * {@link InlineEntityCombobox} bound to one field, which stores the chosen option's
+ * `value` (an id), or `clearValue` once the text is emptied or the "×" pressed.
+ *
+ * kastlan asked for it (0.24): its account picker IS an `InlineEntityCombobox` — the
+ * account number is typed straight into the field — and the budget line-item form
+ * wired it through {@link RhfField}'s render. The picker took no `ref`, so react-hook-
+ * form's focus-on-error had nothing to focus: a line item saved without an account
+ * failed its submit and left the caret where it was, the one field on the form a
+ * failed submit could not take you to. (The same gap {@link RhfCountrySelect} closed
+ * for the address form's country in 0.23.)
+ *
+ * Bound the way {@link RhfCountrySelect} is: `field.ref` reaches the `<input>` (the
+ * picker's `ref`, 0.24), the form's error paints the input and is the shell's message
+ * under it, and the hint is the shell's description — so neither is ever handed to the
+ * picker, and its box never changes when one comes or goes. The form's label names
+ * the input through `<label for>` and titles the phone sheet (`sheetTitle`); the picker
+ * draws no floating label of its own. Focus leaving the picker marks the field
+ * touched.
+ *
+ * Everything else is the picker's and passes through: `commit` and `disabledReason`
+ * (a picker whose choice saves stays focusable under a lock and says why), `clearable`,
+ * `autoFocus`, `aria-label` for an unlabelled cell, and the create row — `onCreate`,
+ * `createLabel`, `createEmptyLabel`, `createCommit`. Making the record is the
+ * caller's, and so is storing its id once it exists:
+ *
+ * ```tsx
+ * <RhfInlineEntityCombobox<LineItem, "account_id", number>
+ *   name="account_id" label="Account" required options={accounts}
+ *   rules={{ required: "Choose an account" }}
+ *   onCreate={async (name) => form.setValue("account_id", (await createAccount(name)).id)} />
+ * ```
+ *
+ * For the button-shaped picker with an async `loadOptions`, see {@link RhfCombobox}.
+ */
+export function RhfInlineEntityCombobox<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+  V extends string | number = string | number,
+  TTransformed = TFieldValues,
+>({
+  name,
+  control,
+  rules,
+  label,
+  hint,
+  required,
+  disabled,
+  excludeWhenDisabled,
+  className,
+  clearValue = null,
+  comboClassName,
+  ...comboProps
+}: RhfInlineEntityComboboxProps<TFieldValues, TName, V, TTransformed>) {
+  return (
+    <RhfField
+      {...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className }}
+      render={({ field, invalid }) => {
+        const value: unknown = field.value;
+        return (
+          // FormControl clones this element with `id` / `aria-describedby` /
+          // `aria-invalid`, which the picker routes to its <input>.
+          <InlineEntityCombobox<V, ComboClearValue>
+            aria-required={required || undefined}
+            // The form's label is the phone sheet's heading — the picker is not handed
+            // `label`, which the FormLabel above already draws. A caller's own wins.
+            sheetTitle={hasContent(label) ? label : undefined}
+            {...comboProps}
+            className={comboClassName}
+            ref={field.ref}
+            value={(value ?? null) as V | ComboClearValue | null}
+            clearValue={clearValue}
+            onChange={(v) => field.onChange(v)}
+            // The wrapper's blur, which the <input>'s bubbles to after the picker has
+            // judged any loose text — so the value is in before the field is touched.
+            onBlur={field.onBlur}
+            disabled={field.disabled}
+            invalid={invalid}
+          />
+        );
+      }}
+    />
+  );
+}
+
 export type RhfTextComboboxProps<
   TFieldValues extends FieldValues = FieldValues,
   TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
@@ -1645,6 +2047,9 @@ export type RhfTextComboboxProps<
     | "optionAdornment"
     | "autoFocus"
     | "aria-label"
+    | "closeLabel"
+    | "commit"
+    | "disabledReason"
   > & {
     /** Classes for the combobox. */
     comboClassName?: string;
@@ -1685,6 +2090,8 @@ export function RhfTextCombobox<
           id={id}
           describedBy={describedBy}
           className={comboClassName}
+          sheetTitle={hasContent(label) ? label : undefined}
+          focusRef={field.ref}
           comboProps={comboProps}
         />
       )}
@@ -1700,6 +2107,8 @@ function TextComboControl({
   id,
   describedBy,
   className,
+  sheetTitle,
+  focusRef,
   comboProps,
 }: {
   field: ControllerRenderProps;
@@ -1709,16 +2118,22 @@ function TextComboControl({
   id: string;
   describedBy: string | undefined;
   className?: string;
+  sheetTitle: ReactNode;
+  /** `field.ref` — see EntityControl. */
+  focusRef: ControllerRenderProps["ref"];
   comboProps: Omit<RhfTextComboboxProps, keyof RhfFieldBaseProps | "comboClassName">;
 }) {
   // The combobox routes `id` and its ARIA to its <input>, so the label's `htmlFor`
-  // names it, the hint describes it and the focus handle finds it; the error is its
-  // own `error` prop, which it merges in after the hint.
-  useFocusHandle(field.ref, () => document.getElementById(id));
+  // names it and the hint describes it; `field.ref` reaches the <input> through the
+  // combobox's own `ref` (0.24). The error is its own `error` prop, which it merges
+  // in after the hint.
   const value: unknown = field.value;
   return (
     <Combobox
+      // The form's label titles the phone sheet (see EntityControl).
+      sheetTitle={sheetTitle}
       {...comboProps}
+      ref={focusRef}
       id={id}
       aria-describedby={describedBy}
       aria-required={required || undefined}

package/src/rhf.ts

@@ -11,7 +11,8 @@ export * from "./rhf/form";
 export * from "./rhf/use-rhf-wizard-step";
 // Bound fields — one line per field (RhfTextField, RhfNumberField, RhfIntegerField, RhfMoneyField,
 // RhfDateField, RhfTextarea, RhfSelect, RhfCheckbox, RhfCombobox, RhfTextCombobox; 0.22: RhfTimeInput,
-// RhfDateRangePicker, RhfToggleGroup, RhfIbanInput, RhfPhoneInput)
+// RhfDateRangePicker, RhfToggleGroup, RhfIbanInput, RhfPhoneInput; 0.23: RhfCountrySelect,
+// RhfMonthPicker; 0.24: RhfInlineEntityCombobox)
 // and RhfField, the shell they are built on.
 export * from "./rhf/fields";
 // LineItems over useFieldArray.