@eifi1/ui-kit 0.11.0 → 0.13.0

package/dist/rhf/fields.d.ts

@@ -0,0 +1,283 @@
+import * as react from 'react';
+import { ReactNode, ReactElement } from 'react';
+import { FieldValues, FieldPath, ControllerProps, ControllerRenderProps, ControllerFieldState } from 'react-hook-form';
+import { aJ as SelectProps, ay as InputProps, aS as TextareaProps } from '../kit-labels-Mz8zZHIF.js';
+import { NumberFieldProps } from '../components/number-field.js';
+import { DatePickerProps } from '../components/date-picker.js';
+import { CheckboxProps } from '../components/checkbox.js';
+import { EntityComboboxProps } from '../components/entity-combobox.js';
+import { ComboboxProps } from '../components/combobox.js';
+import { ComboClearValue } from '../components/combobox-core.js';
+import '../components/data-table-labels.js';
+import '../components/mini-calendar.js';
+import '../components/calendar-heatmap.js';
+import '../components/popover.js';
+import '../components/chip.js';
+import 'lucide-react';
+import '../components/field-sync.js';
+import '../components/tooltip.js';
+import '../hooks/use-anchored-rect.js';
+import '../lib/clipping.js';
+import '../wizard/types.js';
+import '../tour/tour.js';
+import '../search/command-palette.js';
+import '../search/global-search.js';
+import '../search/search-index.js';
+import '../components/month-picker.js';
+import '../components/page-contents.js';
+import '../components/series-chart-labels.js';
+import '../components/pie-chart-labels.js';
+import '../components/sparkline.js';
+import '../components/stat-tile.js';
+import '../components/signature-pad.js';
+import '../components/password-strength.js';
+import '../components/danger-confirm.js';
+import '../components/swatch-picker.js';
+import '../components/tile-radio.js';
+import '../components/icon-picker.js';
+import '../components/dialog-frame.js';
+import '../components/modal.js';
+import '../hooks/use-search-param-state.js';
+import '../components/measured-grid.js';
+import '../feedback/feedback-attachment.js';
+import '../feedback/feedback-dialog.js';
+import '../feedback/feedback-thread.js';
+import '../feedback/feedback-inbox.js';
+import '../components/account-settings-labels.js';
+import '../components/confirm-dialog.js';
+import '../components/floating-panel.js';
+import '../components/bulk-action-bar.js';
+import '../components/list.js';
+import '../components/breadcrumbs.js';
+import '../components/toast.js';
+import '../components/description-list.js';
+import '../components/line-items.js';
+import '../components/progress-bar.js';
+import '../components/signed-amount.js';
+import '../components/error-boundary.js';
+import '../components/authed-image.js';
+import '../hooks/use-authed-src.js';
+import '../components/image-grid.js';
+import '../components/lightbox.js';
+import '../components/number-input.js';
+import '../components/calculator.js';
+import '../components/numpad-sheet.js';
+import '../hooks/use-anchored-panel.js';
+
+/** What every bound field takes. */
+interface RhfFieldBaseProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues> {
+    name: TName;
+    /** `form.control`. Optional under `<Form {...form}>`; pass it to type-check `name`. */
+    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
+     *  an `aria-label` instead. */
+    label?: ReactNode;
+    /** Standing advice under the field ("As printed on the card"), attached to the
+     *  control with `aria-describedby`. */
+    hint?: 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;
+    /** Disables the control and KEEPS the value: a field locked to a preset (a lease's
+     *  preselected unit, a fixed period) still submits it, and `rules` still run.
+     *  react-hook-form's own Controller `disabled` drops the value from `handleSubmit`'s
+     *  data instead, which a locked preset must never do (kastlan, 0.12). To get that,
+     *  add `excludeWhenDisabled`. A form-wide `useForm({ disabled })` still disables
+     *  every field the RHF way. */
+    disabled?: boolean;
+    /** With `disabled`: disable through react-hook-form, so the value is left out of
+     *  the submitted data and validation skips it, like a disabled native input in a
+     *  plain form post. Default `false`. */
+    excludeWhenDisabled?: boolean;
+    /** Classes for the item's box (a `grid gap-1`). */
+    className?: string;
+}
+/** What {@link RhfField}'s `render` receives. */
+interface RhfFieldRenderContext<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> {
+    field: ControllerRenderProps<TFieldValues, TName>;
+    fieldState: ControllerFieldState;
+    /** The field has an error: pass it to the control's `invalid` so it paints. */
+    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. */
+    id: string;
+    /** The label's id, for a control that is named with `aria-labelledby`. */
+    labelId: string;
+    /** The ids of the rendered hint and message, if any. */
+    describedBy: string | undefined;
+}
+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. */
+    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
+     *  `error` prop). Default `true`. */
+    message?: boolean;
+    /** `false`: no {@link FormLabel}, for a control that carries its label itself (a
+     *  checkbox). Default `true`. */
+    showLabel?: boolean;
+}
+/**
+ * The shell every bound field is built on: label, control, hint and message around
+ * a `render` of your own.
+ *
+ * ```tsx
+ * <RhfField name="address" label="Address" render={({ field, invalid }) => (
+ *   <AddressAutocomplete value={field.value ?? ""} onChange={field.onChange} invalid={invalid} />
+ * )} />
+ * ```
+ */
+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>): 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
+     * `font-mono` IBAN, a `tabular-nums` reference number). {@link RhfTextarea} and
+     * {@link RhfNumberField} had it; this one only reached `Input`'s prop of the same
+     * name by accident of the rest-spread, undocumented and one refactor from being
+     * dropped. Declared, it is part of the contract the three share.
+     */
+    inputClassName?: string;
+};
+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. */
+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>): 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;
+};
+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. */
+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>): react.JSX.Element;
+type RhfNumberFieldProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> & Pick<NumberFieldProps, "digits" | "min" | "max" | "step" | "calculator" | "unit" | "unitPlacement" | "placeholder" | "inputClassName" | "locale" | "ariaLabel" | "autoFocus"> & {
+    /** What an emptied field stores. Default `null`; `""` for a schema written
+     *  against a native number input (`z.coerce.number()` over `""`). */
+    emptyValue?: null | "";
+    /** `false`: an emptied field snaps back to its last number instead of storing
+     *  `emptyValue`. Default `true`. */
+    nullable?: boolean;
+};
+/**
+ * The kit's {@link NumberField}: a parsed, rounded (`digits`) and clamped (`min` /
+ * `max`) number, committed on blur or Enter in the locale's decimal mark. Stores a
+ * number, or `emptyValue` when emptied.
+ */
+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>): react.JSX.Element;
+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
+ * notice period in months. Every such call site in kastlan (item 41) spelled out the
+ * same three props, `digits={0} calculator={false} emptyValue=""`, and a preset
+ * written thirty times is one that is eventually written wrong once:
+ *
+ *  - `digits={0}`: rounds on commit, so "2.5" rooms settles to 3 instead of reaching
+ *    an `Integer` column and failing server-side;
+ *  - `calculator={false}`: a count is typed, not worked out — the trigger is noise
+ *    beside a two-digit field;
+ *  - `emptyValue=""`: kastlan's integer schemas are `z.coerce.number()` over `""`,
+ *    written against the native number inputs these fields replaced.
+ *
+ * Each is only a default: pass the prop to override it (`emptyValue={null}` for a
+ * nullable column). Everything else is {@link RhfNumberField}'s.
+ */
+declare function RhfIntegerField<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>(props: RhfIntegerFieldProps<TFieldValues, TName, TTransformed>): react.JSX.Element;
+type RhfMoneyFieldProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> & {
+    placeholder?: string;
+    /** The currency chip's code ("CHF"). */
+    currency?: string;
+    /** Makes the chip a currency picker. Bind it to another field with
+     *  `useController`, or to state. */
+    onCurrencyChange?: (code: string) => void;
+    /** Colours the figure for the direction of money. */
+    tone?: "neutral" | "outflow" | "inflow";
+    align?: "start" | "center";
+    ariaLabel?: string;
+    autoFocus?: boolean;
+    /**
+     * What the form stores: `"number"` (default) — `12.5`, or `emptyValue` while the
+     * field is empty — or `"string"`, the field's own text ("12.50") for a schema that
+     * parses it itself. A half-typed sum ("12+") leaves the stored number as it was
+     * until it resolves.
+     */
+    valueAs?: "number" | "string";
+    /** What an emptied field stores when `valueAs` is `"number"`. Default `null`. */
+    emptyValue?: null | "";
+    /** Decimals the amount settles to on blur, Enter or a calculator result. Default:
+     *  the currency's minor unit (CHF 2, JPY 0). See {@link AmountInput}'s `digits`. */
+    digits?: number;
+    /** Clamp the settled amount (a release capped at the deposit's balance). Validate
+     *  with `rules` as well if a clamp needs explaining. */
+    min?: number;
+    max?: number;
+};
+/**
+ * The kit's {@link AmountInput}: a money figure with its currency chip and the
+ * calculator ("1200+80" resolves on blur or Enter). Stores a number by default — see
+ * `valueAs`.
+ */
+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>): react.JSX.Element;
+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"> & {
+    /** Classes for the picker. Default `w-full`. */
+    inputClassName?: string;
+    /** What a cleared date stores. Default `""`, the empty ISO string; `null` for a
+     *  nullable schema. */
+    emptyValue?: "" | null;
+};
+/** The kit's {@link DatePicker}, holding an ISO `"YYYY-MM-DD"` string. */
+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>): react.JSX.Element;
+interface RhfSelectOption {
+    value: string | number;
+    label: ReactNode;
+    disabled?: boolean;
+}
+type RhfSelectProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> & Pick<SelectProps, "size" | "autoFocus" | "aria-label"> & {
+    /** The options, as data. Or pass `<option>` children. */
+    options?: readonly RhfSelectOption[];
+    children?: ReactNode;
+    /** A first, empty option ("Choose…"), selected while the value is empty. */
+    placeholder?: string;
+    /** Store `Number(value)` rather than the option's string. An empty choice still
+     *  stores `""`. */
+    valueAsNumber?: boolean;
+    /** Classes for the select. Default `w-full`. */
+    selectClassName?: string;
+};
+/** A native {@link Select}, from `options` or `<option>` children. */
+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>): react.JSX.Element;
+type RhfCheckboxProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> & Pick<CheckboxProps, "inputClassName" | "autoFocus" | "aria-label">;
+/**
+ * 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
+ * — see Checkbox — so a `<form>` refuses to submit it unticked.
+ */
+declare function RhfCheckbox<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues>({ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className, ...boxProps }: RhfCheckboxProps<TFieldValues, TName, TTransformed>): react.JSX.Element;
+type RhfComboboxProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, V extends string | number = string | number, TTransformed = TFieldValues> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> & Pick<EntityComboboxProps<V>, "options" | "loadOptions" | "loading" | "placeholder" | "searchPlaceholder" | "emptyLabel" | "clearable" | "clearLabel" | "onCreate" | "createLabel" | "filter" | "minChars" | "debounceMs"> & {
+    /** What a clear stores — the picker's `clearValue`. Default `null`; `""` for a
+     *  schema that spells "no choice" as an empty string. */
+    clearValue?: ComboClearValue;
+    /** Classes for the picker. */
+    comboClassName?: string;
+};
+/**
+ * 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`).
+ */
+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>): react.JSX.Element;
+type RhfTextComboboxProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>, TTransformed = TFieldValues> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> & Pick<ComboboxProps, "options" | "placeholder" | "groupBy" | "maxSuggestions" | "searchPlaceholder" | "createLabel" | "optionAdornment" | "autoFocus" | "aria-label"> & {
+    /** Classes for the combobox. */
+    comboClassName?: string;
+};
+/**
+ * The kit's free-text {@link Combobox}: type anything, or pick one of `options`.
+ * Stores the string.
+ */
+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>): react.JSX.Element;
+
+export { RhfCheckbox, type RhfCheckboxProps, RhfCombobox, type RhfComboboxProps, RhfDateField, type RhfDateFieldProps, RhfField, type RhfFieldBaseProps, type RhfFieldProps, type RhfFieldRenderContext, RhfIntegerField, type RhfIntegerFieldProps, RhfMoneyField, type RhfMoneyFieldProps, RhfNumberField, type RhfNumberFieldProps, RhfSelect, type RhfSelectOption, type RhfSelectProps, RhfTextCombobox, type RhfTextComboboxProps, RhfTextField, type RhfTextFieldProps, RhfTextarea, type RhfTextareaProps };