@eifi1/ui-kit 0.34.0 → 0.36.0

package/dist/rhf/fields.d.ts

@@ -27,7 +27,7 @@
  *  - **The red border.** Every field gets `invalid` from the field state, so an errored
  *    field PAINTS as well as announces. kastlan's number, money, date and entity fields
  *    passed only `aria-invalid` through `FormControl`, or nothing, and `Input`, `Select`
- *    and `Textarea` paint only from the prop (see the note in ./form).
+ *    and `Textarea` paint only from the prop (see the note in ./form-core).
  *  - **Focus on error.** `field.ref` reaches the focusable element itself — the input,
  *    a picker's trigger, a toggle group whose `focus()` lands on its option (since 0.34
  *    every kit field takes a ref; the number field and the pickers were reached by an id
@@ -37,7 +37,7 @@
  *    through react-hook-form's context. Pass it for the field's value types
  *    (`control={form.control}` checks `name` against the form's values).
  *
- * The common props: `name`, `control`, `label` (a {@link FormLabel} above the field;
+ * The common props: `name`, `control`, `label` (the label above the field;
  * omitted, none — then give the field an `aria-label`), `hint` (standing advice under
  * the field, attached to it with `aria-describedby`), `required` (the label's mark,
  * and `aria-required` where the control takes it — validation is `rules`' or the
@@ -73,13 +73,19 @@ export interface RhfFieldBaseProps<TFieldValues extends FieldValues = FieldValue
     control?: ControllerProps<TFieldValues, TName, TTransformed>["control"];
     /** react-hook-form's `rules` (`required`, `min`, `validate` …). */
     rules?: ControllerProps<TFieldValues, TName, TTransformed>["rules"];
-    /** A {@link FormLabel} above the field. Omitted: no label — name the control with
+    /** The label above the field. Omitted: no label — name the control with
      *  an `aria-label` instead. */
     label?: ReactNode;
     /** Standing advice under the field ("As printed on the card"), attached to the
      *  control with `aria-describedby`. A `FieldHint` is its words at Large and on a
-     *  touch screen (§4, DUP-2), not a lone "?"; a `HelpPopover` stays a "?". */
+     *  touch screen (§4, DUP-2), not a lone "?"; a `HelpPopover` stays a "?". Beside a
+     *  `help` it is that caption at every size. */
     hint?: ReactNode;
+    /** Help the field is usable without — why, how to choose — behind the field's one
+     *  "?" after the label: a `HelpPopover` named "About <label>" (round 0.36,
+     *  docs/text-size-harmonization.md §4); pass a `HelpPopover` to name it yourself.
+     *  `hint` stays the visible fact under the field. */
+    help?: ReactNode;
     /** Draws the label's required mark and sets `aria-required` where the control
      *  takes it. Whether the field IS required is `rules`' or the resolver's to say. */
     required?: boolean;
@@ -105,8 +111,8 @@ export interface RhfFieldRenderContext<TFieldValues extends FieldValues = FieldV
     invalid: boolean;
     /** The error's message, if any. */
     error: string | undefined;
-    /** The control's id, which the label points at. `FormControl` sets it on the
-     *  rendered element already; this is for a control that routes it elsewhere. */
+    /** The control's id, which the label points at. The rendered element has it already
+     *  (unless `asControl` is false); this is for a control that routes it elsewhere. */
     id: string;
     /** The label's id, for a control that is named with `aria-labelledby`. */
     labelId: string;
@@ -114,16 +120,16 @@ export interface RhfFieldRenderContext<TFieldValues extends FieldValues = FieldV
     describedBy: string | undefined;
 }
 export interface RhfFieldProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues> extends RhfFieldBaseProps<TFieldValues, TName, TTransformed> {
-    /** The control. Wrapped in {@link FormControl} (its `id`, `aria-describedby` and
-     *  `aria-invalid`) unless `asControl` is false. */
+    /** The control. Given the field's `id`, `aria-describedby` and `aria-invalid` unless
+     *  `asControl` is false. */
     render: (ctx: RhfFieldRenderContext<TFieldValues, TName>) => ReactElement;
     /** `false`: render the control as is, for one that wires its own ids from the
      *  context. Default `true`. */
     asControl?: boolean;
-    /** `false`: no {@link FormMessage}, for a control that renders its own error (its
+    /** `false`: no error message under the field, for a control that renders its own (its
      *  `error` prop). Default `true`. */
     message?: boolean;
-    /** `false`: no {@link FormLabel}, for a control that carries its label itself (a
+    /** `false`: no label above the field, for a control that carries its label itself (a
      *  checkbox). Default `true`. */
     showLabel?: boolean;
 }
@@ -137,7 +143,7 @@ export interface RhfFieldProps<TFieldValues extends FieldValues = FieldValues, T
  * )} />
  * ```
  */
-export declare function RhfField<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className, render, asControl, message, showLabel, }: RhfFieldProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
+export declare function RhfField<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className, render, asControl, message, showLabel, }: RhfFieldProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
 type OwnInputProps = Omit<InputProps, "name" | "value" | "defaultValue" | "onChange" | "onBlur" | "ref" | "label" | "error" | "invalid" | "className" | "disabled" | "required" | "inputClassName"> & {
     /**
      * Classes for the `<input>` — `className` is the item's box (kastlan 42: a
@@ -150,14 +156,14 @@ type OwnInputProps = Omit<InputProps, "name" | "value" | "defaultValue" | "onCha
 };
 export type RhfTextFieldProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> & OwnInputProps;
 /** A text {@link Input} — `type` for email, tel, password, url. Stores the string. */
-export declare function RhfTextField<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className, ...inputProps }: RhfTextFieldProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
+export declare function RhfTextField<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className, ...inputProps }: RhfTextFieldProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
 type OwnTextareaProps = Omit<TextareaProps, "name" | "value" | "defaultValue" | "onChange" | "onBlur" | "ref" | "label" | "error" | "invalid" | "className" | "disabled" | "required"> & {
     /** Classes for the `<textarea>`. */
     inputClassName?: string;
 };
 export type RhfTextareaProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> & OwnTextareaProps;
 /** A multi-line {@link Textarea}; takes `rows`. Stores the string. */
-export declare function RhfTextarea<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className, inputClassName, ...areaProps }: RhfTextareaProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
+export declare function RhfTextarea<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className, inputClassName, ...areaProps }: RhfTextareaProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
 /** What a twin sets on its field itself — the value and its change, what the form
  *  decides (`disabled`, `invalid`, the error, the ids) and what the shell draws (the
  *  label, the hint, the item's `className`). Everything else of the field's passes
@@ -177,7 +183,7 @@ export type RhfNumberFieldProps<TFieldValues extends FieldValues = FieldValues,
  * `max`) number, committed on blur or Enter in the locale's decimal mark. Stores a
  * number, or `emptyValue` when emptied.
  */
-export declare function RhfNumberField<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className, emptyValue, nullable, ...numberProps }: RhfNumberFieldProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
+export declare function RhfNumberField<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className, emptyValue, nullable, ...numberProps }: RhfNumberFieldProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
 export type RhfIntegerFieldProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues> = RhfNumberFieldProps<TFieldValues, TName, TTransformed>;
 /**
  * {@link RhfNumberField} for a whole number — a floor, a room count, a year, a
@@ -212,7 +218,7 @@ export type RhfMoneyFieldProps<TFieldValues extends FieldValues = FieldValues, T
  * calculator ("1200+80" resolves on blur or Enter). Stores a number by default — see
  * `valueAs`.
  */
-export declare function RhfMoneyField<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className, ...amountProps }: RhfMoneyFieldProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
+export declare function RhfMoneyField<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className, ...amountProps }: RhfMoneyFieldProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
 export type RhfDateFieldProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> & Omit<DatePickerProps, "value" | "onChange" | "label" | "invalid" | "disabled" | "className" | "id" | "error"> & {
     /** Classes for the picker. Default `w-full`. */
     inputClassName?: string;
@@ -221,7 +227,7 @@ export type RhfDateFieldProps<TFieldValues extends FieldValues = FieldValues, TN
     emptyValue?: "" | null;
 };
 /** The kit's {@link DatePicker}, holding an ISO `"YYYY-MM-DD"` string. */
-export declare function RhfDateField<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className, inputClassName, emptyValue, ...pickerProps }: RhfDateFieldProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
+export declare function RhfDateField<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className, inputClassName, emptyValue, ...pickerProps }: RhfDateFieldProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
 type OwnDateRangeProps = Omit<DateRangePickerProps, "from" | "to" | "onChange" | "label" | "invalid" | "disabled" | "className" | "id" | "error">;
 export type RhfDateRangePickerProps<TFieldValues extends FieldValues = FieldValues, TFromName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TToName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues> = Omit<RhfFieldBaseProps<TFieldValues, TFromName, TTransformed>, "name" | "rules"> & OwnDateRangeProps & {
     /** The form field holding the range's first day, an ISO `"YYYY-MM-DD"`. */
@@ -277,7 +283,7 @@ export type RhfDateRangePickerProps<TFieldValues extends FieldValues = FieldValu
  * The common props (`label`, `hint`, `required`, `disabled`, `excludeWhenDisabled`,
  * `control`, `className`) apply to the pair; `rules` are per field.
  */
-export declare function RhfDateRangePicker<TFieldValues extends FieldValues = FieldValues, TFromName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TToName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ fromName, toName, control, fromRules, toRules, label, hint, required, disabled, excludeWhenDisabled, className, inputClassName, emptyValue, ...pickerProps }: RhfDateRangePickerProps<TFieldValues, TFromName, TToName, TTransformed>): import("react").JSX.Element;
+export declare function RhfDateRangePicker<TFieldValues extends FieldValues = FieldValues, TFromName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TToName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ fromName, toName, control, fromRules, toRules, label, hint, help, required, disabled, excludeWhenDisabled, className, inputClassName, emptyValue, ...pickerProps }: RhfDateRangePickerProps<TFieldValues, TFromName, TToName, TTransformed>): import("react").JSX.Element;
 export type RhfTimeInputProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> & Omit<TimeInputProps, "name" | "value" | "defaultValue" | "onChange" | "onValueChange" | "onBlur" | "label" | "error" | "invalid" | "className" | "disabled" | "required"> & {
     /** What a cleared time stores. Default `""`; `null` for a nullable schema. */
     emptyValue?: "" | null;
@@ -294,7 +300,7 @@ export type RhfTimeInputProps<TFieldValues extends FieldValues = FieldValues, TN
  * validation stays the schema's or `rules`'. `rules={{ validate: (v) =>
  * isTimeInRange(v, min, max) || "…" }}` says it with the same window.
  */
-export declare function RhfTimeInput<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className, emptyValue, ...timeProps }: RhfTimeInputProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
+export declare function RhfTimeInput<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className, emptyValue, ...timeProps }: RhfTimeInputProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
 type OwnTextishProps<P> = Omit<P, "name" | "value" | "defaultValue" | "onChange" | "onValueChange" | "onBlur" | "label" | "error" | "invalid" | "className" | "disabled" | "required">;
 export type RhfIbanInputProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> & OwnTextishProps<IbanInputProps>;
 /**
@@ -304,7 +310,7 @@ export type RhfIbanInputProps<TFieldValues extends FieldValues = FieldValues, TN
  * or `rules`') replaces them, as a caller's `error` does on the bare field. kastlan
  * asked for the field; it binds everything through react-hook-form.
  */
-export declare function RhfIbanInput<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className, ...ibanProps }: RhfIbanInputProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
+export declare function RhfIbanInput<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className, ...ibanProps }: RhfIbanInputProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
 export type RhfPhoneInputProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> & OwnTextishProps<PhoneInputProps>;
 /**
  * {@link PhoneInput} bound to one field, which stores E.164 when the number reads as
@@ -312,7 +318,7 @@ export type RhfPhoneInputProps<TFieldValues extends FieldValues = FieldValues, T
  * text until someone edits it. Validation (required, a pattern for E.164 only) is the
  * schema's or `rules`'.
  */
-export declare function RhfPhoneInput<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className, ...phoneProps }: RhfPhoneInputProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
+export declare function RhfPhoneInput<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className, ...phoneProps }: RhfPhoneInputProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
 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
@@ -346,7 +352,7 @@ export type RhfCountrySelectProps<TFieldValues extends FieldValues = FieldValues
  *   preferred={["CH", "LI", "DE", "AT", "FR", "IT"]} rules={{ required: "Choose a country" }} />
  * ```
  */
-export declare 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, selectClassName, labels, ...countryProps }: RhfCountrySelectProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
+export declare function RhfCountrySelect<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className, clearable, clearValue, selectClassName, labels, ...countryProps }: RhfCountrySelectProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
 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 = {
@@ -383,7 +389,7 @@ export type RhfMonthPickerProps<TFieldValues extends FieldValues = FieldValues,
  *   min="2020" max="2029" rules={{ required: "Choose a year" }} />
  * ```
  */
-export declare 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>): import("react").JSX.Element;
+export declare function RhfMonthPicker<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className, inputClassName, mode, valueAsNumber, ...pickerProps }: RhfMonthPickerProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
 export interface RhfSelectOption {
     value: string | number;
     label: ReactNode;
@@ -402,8 +408,9 @@ export type RhfSelectProps<TFieldValues extends FieldValues = FieldValues, TName
     selectClassName?: string;
 };
 /** A native {@link Select}, from `options` or `<option>` children. */
-export declare function RhfSelect<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className, options, children, placeholder, valueAsNumber, selectClassName, ...selectProps }: RhfSelectProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
-export type RhfCheckboxProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> & Omit<CheckboxProps, BoundByForm | "checked" | "defaultChecked" | "onCheckedChange" | "description">;
+export declare function RhfSelect<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className, options, children, placeholder, valueAsNumber, selectClassName, ...selectProps }: RhfSelectProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
+export type RhfCheckboxProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues> = // No `help` (0.36): a box has no label line — its label sits beside it, inside the
+Omit<RhfFieldBaseProps<TFieldValues, TName, TTransformed>, "help"> & Omit<CheckboxProps, BoundByForm | "checked" | "defaultChecked" | "onCheckedChange" | "description">;
 /**
  * The kit's {@link Checkbox}, label beside the box and `hint` under it (the
  * checkbox's own `description`). Stores a boolean. `required` is the native one here
@@ -438,7 +445,7 @@ export type RhfToggleGroupProps<TFieldValues extends FieldValues = FieldValues,
  * asked for it with {@link RhfTimeInput} and {@link RhfDateRangePicker}: the controls
  * its forms still had to wire by hand through {@link RhfField}'s render.
  *
- * The label is the form's {@link FormLabel} above the bare group, as on every other
+ * The label is the field's own label above the bare group, as on every other
  * bound field — the `labelPlacement="above"` shape, not the group's own field chrome —
  * and it names the group (`aria-labelledby`); the hint and the message describe it,
  * and an error paints the group's border. Focus on error goes to the option a
@@ -451,7 +458,7 @@ export type RhfToggleGroupProps<TFieldValues extends FieldValues = FieldValues,
  * value that matches no option (an empty default) leaves nothing pressed; that the
  * field still needs answering is the schema's or `rules`' to say.
  */
-export declare function RhfToggleGroup<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, T extends string = string, TTransformed = TFieldValues>({ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className, ...groupProps }: RhfToggleGroupProps<TFieldValues, TName, T, TTransformed>): import("react").JSX.Element;
+export declare function RhfToggleGroup<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, T extends string = string, TTransformed = TFieldValues>({ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className, ...groupProps }: RhfToggleGroupProps<TFieldValues, TName, T, TTransformed>): import("react").JSX.Element;
 export type RhfComboboxProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, V extends string | number = string | number, TTransformed = TFieldValues> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> & Omit<EntityComboboxProps<V>, BoundByForm | "id" | "clearValue"> & {
     /** What a clear stores — the picker's `clearValue`. Default `null`; `""` for a
      *  schema that spells "no choice" as an empty string. */
@@ -472,7 +479,7 @@ export type RhfComboboxProps<TFieldValues extends FieldValues = FieldValues, TNa
  * placeholder. For the INLINE picker — a text input, the account field typed into —
  * see {@link RhfInlineEntityCombobox}.
  */
-export declare function RhfCombobox<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, comboClassName, ...comboProps }: RhfComboboxProps<TFieldValues, TName, V, TTransformed>): import("react").JSX.Element;
+export declare function RhfCombobox<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, V extends string | number = string | number, TTransformed = TFieldValues>({ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className, clearValue, comboClassName, ...comboProps }: RhfComboboxProps<TFieldValues, TName, V, TTransformed>): import("react").JSX.Element;
 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
@@ -517,7 +524,7 @@ export type RhfInlineEntityComboboxProps<TFieldValues extends FieldValues = Fiel
  *
  * For the button-shaped picker with an async `loadOptions`, see {@link RhfCombobox}.
  */
-export declare 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, comboClassName, ...comboProps }: RhfInlineEntityComboboxProps<TFieldValues, TName, V, TTransformed>): import("react").JSX.Element;
+export declare 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, help, required, disabled, excludeWhenDisabled, className, clearValue, comboClassName, ...comboProps }: RhfInlineEntityComboboxProps<TFieldValues, TName, V, TTransformed>): import("react").JSX.Element;
 export type RhfTextComboboxProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> & Omit<ComboboxProps, BoundByForm | "id"> & {
     /** Classes for the combobox. */
     comboClassName?: string;
@@ -526,5 +533,5 @@ export type RhfTextComboboxProps<TFieldValues extends FieldValues = FieldValues,
  * The kit's free-text {@link Combobox}: type anything, or pick one of `options`.
  * Stores the string.
  */
-export declare function RhfTextCombobox<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className, comboClassName, ...comboProps }: RhfTextComboboxProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
+export declare function RhfTextCombobox<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className, comboClassName, ...comboProps }: RhfTextComboboxProps<TFieldValues, TName, TTransformed>): import("react").JSX.Element;
 export {};

package/dist/rhf/fields.js

@@ -29,7 +29,7 @@ import {
   Combobox,
   InlineEntityCombobox
 } from "../components/combobox.js";
-import { mergeRefs, useInlineHint } from "../components/field-parts.js";
+import { fieldHelpMark, mergeRefs, useInlineHint } from "../components/field-parts.js";
 import { useKitLocale } from "../i18n/kit-labels.js";
 import { cn } from "../lib/cn.js";
 import { decimalMark, readTyped } from "../lib/decimal-marks.js";
@@ -62,6 +62,7 @@ function RhfField({
   rules,
   label,
   hint,
+  help,
   required,
   disabled,
   excludeWhenDisabled,
@@ -71,7 +72,9 @@ function RhfField({
   message = true,
   showLabel = true
 }) {
-  const shownHint = useInlineHint(hint);
+  const helpMark = fieldHelpMark(help, label);
+  const shownHint = useInlineHint(hint, helpMark !== void 0);
+  const labelEl = showLabel && hasContent(label) && /* @__PURE__ */ jsx(RhfLabel, { required, children: label });
   return /* @__PURE__ */ jsx(
     FormField,
     {
@@ -80,7 +83,10 @@ function RhfField({
       rules,
       disabled: excludeWhenDisabled ? disabled : void 0,
       render: ({ field, fieldState }) => /* @__PURE__ */ jsxs(FormItem, { className, children: [
-        showLabel && hasContent(label) && /* @__PURE__ */ jsx(RhfLabel, { required, children: label }),
+        helpMark === void 0 ? labelEl : /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-1", children: [
+          labelEl,
+          /* @__PURE__ */ jsx("span", { className: "flex shrink-0 items-center", children: helpMark })
+        ] }),
         /* @__PURE__ */ jsx(
           ControlSlot,
           {
@@ -102,6 +108,7 @@ function RhfTextField({
   rules,
   label,
   hint,
+  help,
   required,
   disabled,
   excludeWhenDisabled,
@@ -111,7 +118,7 @@ function RhfTextField({
   return /* @__PURE__ */ jsx(
     RhfField,
     {
-      ...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className },
+      ...{ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className },
       render: ({ field, invalid }) => /* @__PURE__ */ jsx(
         Input,
         {
@@ -135,6 +142,7 @@ function RhfTextarea({
   rules,
   label,
   hint,
+  help,
   required,
   disabled,
   excludeWhenDisabled,
@@ -145,7 +153,7 @@ function RhfTextarea({
   return /* @__PURE__ */ jsx(
     RhfField,
     {
-      ...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className },
+      ...{ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className },
       render: ({ field, invalid }) => /* @__PURE__ */ jsx(
         Textarea,
         {
@@ -179,6 +187,7 @@ function RhfNumberField({
   rules,
   label,
   hint,
+  help,
   required,
   disabled,
   excludeWhenDisabled,
@@ -190,7 +199,7 @@ function RhfNumberField({
   return /* @__PURE__ */ jsx(
     RhfField,
     {
-      ...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className },
+      ...{ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className },
       render: ({ field, invalid, id }) => (
         // FormControl clones this element with `id` / `aria-describedby` /
         // `aria-invalid`, which NumberControl hands on to the field.
@@ -305,6 +314,7 @@ function RhfMoneyField({
   rules,
   label,
   hint,
+  help,
   required,
   disabled,
   excludeWhenDisabled,
@@ -314,7 +324,7 @@ function RhfMoneyField({
   return /* @__PURE__ */ jsx(
     RhfField,
     {
-      ...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className },
+      ...{ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className },
       asControl: false,
       render: ({ field, invalid, id, describedBy }) => /* @__PURE__ */ jsx(
         MoneyControl,
@@ -367,6 +377,7 @@ function RhfDateField({
   rules,
   label,
   hint,
+  help,
   required,
   disabled,
   excludeWhenDisabled,
@@ -378,7 +389,7 @@ function RhfDateField({
   return /* @__PURE__ */ jsx(
     RhfField,
     {
-      ...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className },
+      ...{ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className },
       render: ({ field, invalid, id }) => (
         // FormControl clones this element with `aria-describedby` / `aria-invalid`,
         // which DateControl hands on to the picker's trigger.
@@ -407,6 +418,7 @@ function RhfDateRangePicker({
   toRules,
   label,
   hint,
+  help,
   required,
   disabled,
   excludeWhenDisabled,
@@ -438,6 +450,7 @@ function RhfDateRangePicker({
           toState: to.fieldState,
           label,
           hint,
+          help,
           required,
           disabled: Boolean(disabled),
           emptyValue,
@@ -455,6 +468,7 @@ function RangeBody({
   toState,
   label,
   hint,
+  help,
   required,
   disabled,
   emptyValue,
@@ -462,7 +476,8 @@ function RangeBody({
   pickerProps
 }) {
   const { id, formItemId, formMessageId, describedBy } = useFormField();
-  const shownHint = useInlineHint(hint);
+  const helpMark = fieldHelpMark(help, label);
+  const shownHint = useInlineHint(hint, helpMark !== void 0);
   const triggerRef = useMemo(() => mergeRefs(from.ref, to.ref), [from.ref, to.ref]);
   const invalid = fromState.invalid || toState.invalid;
   const messages = [fromState.error?.message, toState.error?.message].filter(
@@ -471,10 +486,14 @@ function RangeBody({
   const messageIds = messages.map((_, i) => `${formMessageId}-${i}`);
   const fromValue = from.value;
   const toValue = to.value;
+  const labelEl = hasContent(label) && // FormLabel colours from the START's error alone (its context is that field); the
+  // pair's state says it here.
+  /* @__PURE__ */ jsx(FormLabel, { id: `${id}-label`, required, "data-error": invalid || void 0, children: label });
   return /* @__PURE__ */ jsxs(Fragment, { children: [
-    hasContent(label) && // FormLabel colours from the START's error alone (its context is that field);
-    // the pair's state says it here.
-    /* @__PURE__ */ jsx(FormLabel, { id: `${id}-label`, required, "data-error": invalid || void 0, children: label }),
+    helpMark === void 0 ? labelEl : /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-1", children: [
+      labelEl,
+      /* @__PURE__ */ jsx("span", { className: "flex shrink-0 items-center", children: helpMark })
+    ] }),
     /* @__PURE__ */ jsx(
       DateRangePicker,
       {
@@ -522,6 +541,7 @@ function RhfTimeInput({
   rules,
   label,
   hint,
+  help,
   required,
   disabled,
   excludeWhenDisabled,
@@ -532,7 +552,7 @@ function RhfTimeInput({
   return /* @__PURE__ */ jsx(
     RhfField,
     {
-      ...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className },
+      ...{ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className },
       render: ({ field, invalid }) => {
         const value = field.value;
         return /* @__PURE__ */ jsx(
@@ -559,6 +579,7 @@ function RhfIbanInput({
   rules,
   label,
   hint,
+  help,
   required,
   disabled,
   excludeWhenDisabled,
@@ -568,7 +589,7 @@ function RhfIbanInput({
   return /* @__PURE__ */ jsx(
     RhfField,
     {
-      ...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className },
+      ...{ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className },
       render: ({ field, invalid }) => {
         const value = field.value;
         return /* @__PURE__ */ jsx(
@@ -595,6 +616,7 @@ function RhfPhoneInput({
   rules,
   label,
   hint,
+  help,
   required,
   disabled,
   excludeWhenDisabled,
@@ -604,7 +626,7 @@ function RhfPhoneInput({
   return /* @__PURE__ */ jsx(
     RhfField,
     {
-      ...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className },
+      ...{ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className },
       render: ({ field, invalid }) => {
         const value = field.value;
         return /* @__PURE__ */ jsx(
@@ -631,6 +653,7 @@ function RhfCountrySelect({
   rules,
   label,
   hint,
+  help,
   required,
   disabled,
   excludeWhenDisabled,
@@ -646,7 +669,7 @@ function RhfCountrySelect({
   return /* @__PURE__ */ jsx(
     RhfField,
     {
-      ...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className },
+      ...{ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className },
       render: ({ field, invalid, labelId }) => {
         const value = field.value;
         return (
@@ -713,6 +736,7 @@ function RhfMonthPicker({
   rules,
   label,
   hint,
+  help,
   required,
   disabled,
   excludeWhenDisabled,
@@ -725,7 +749,7 @@ function RhfMonthPicker({
   return /* @__PURE__ */ jsx(
     RhfField,
     {
-      ...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className },
+      ...{ name, control, rules, label, hint, help, 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.
@@ -753,6 +777,7 @@ function RhfSelect({
   rules,
   label,
   hint,
+  help,
   required,
   disabled,
   excludeWhenDisabled,
@@ -767,7 +792,7 @@ function RhfSelect({
   return /* @__PURE__ */ jsx(
     RhfField,
     {
-      ...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className },
+      ...{ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className },
       render: ({ field, invalid }) => /* @__PURE__ */ jsxs(
         Select,
         {
@@ -836,6 +861,7 @@ function RhfToggleGroup({
   rules,
   label,
   hint,
+  help,
   required,
   disabled,
   excludeWhenDisabled,
@@ -846,7 +872,7 @@ function RhfToggleGroup({
   return /* @__PURE__ */ jsx(
     RhfField,
     {
-      ...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className },
+      ...{ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className },
       asControl: false,
       render: ({ field, invalid, id, labelId, describedBy }) => /* @__PURE__ */ jsx(
         ToggleControl,
@@ -964,6 +990,7 @@ function RhfCombobox({
   rules,
   label,
   hint,
+  help,
   required,
   disabled,
   excludeWhenDisabled,
@@ -975,7 +1002,7 @@ function RhfCombobox({
   return /* @__PURE__ */ jsx(
     RhfField,
     {
-      ...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className },
+      ...{ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className },
       asControl: false,
       message: false,
       render: ({ field, invalid, error, id, describedBy }) => /* @__PURE__ */ jsx(
@@ -1003,6 +1030,7 @@ function RhfInlineEntityCombobox({
   rules,
   label,
   hint,
+  help,
   required,
   disabled,
   excludeWhenDisabled,
@@ -1014,7 +1042,7 @@ function RhfInlineEntityCombobox({
   return /* @__PURE__ */ jsx(
     RhfField,
     {
-      ...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className },
+      ...{ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className },
       render: ({ field, invalid }) => {
         const value = field.value;
         return (
@@ -1047,6 +1075,7 @@ function RhfTextCombobox({
   rules,
   label,
   hint,
+  help,
   required,
   disabled,
   excludeWhenDisabled,
@@ -1057,7 +1086,7 @@ function RhfTextCombobox({
   return /* @__PURE__ */ jsx(
     RhfField,
     {
-      ...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className },
+      ...{ name, control, rules, label, hint, help, required, disabled, excludeWhenDisabled, className },
       asControl: false,
       message: false,
       render: ({ field, invalid, error, id, describedBy }) => /* @__PURE__ */ jsx(