@agentero/design-system 0.28.0 → 0.29.0

package/src/form/form.d.ts

@@ -0,0 +1,60 @@
+import { ComponentPropsWithRef } from 'react';
+import { FieldValues, SubmitHandler, UseFormReturn } from 'react-hook-form';
+export type FormRootProps<TFieldValues extends FieldValues = FieldValues, TTransformedValues = TFieldValues> = Omit<ComponentPropsWithRef<'form'>, 'onSubmit' | 'noValidate'> & {
+    /**
+     * The object `useForm()` returns. `Form.Root` hands it to every form field
+     * inside through react-hook-form's `FormProvider`, so a `FormText` needs only
+     * its `name`. Create it in the component that owns the form and pass
+     * `defaultValues`: a field whose value is `undefined` on the first render
+     * starts uncontrolled. A form whose resolver transforms the values
+     * (`useForm<Input, Context, Output>`) is accepted as is.
+     */
+    methods: UseFormReturn<TFieldValues, any, TTransformedValues>;
+    /**
+     * Called with the validated values once validation passes: the resolver's
+     * output when it transforms them, the form's values otherwise. Wrapped in
+     * `methods.handleSubmit`, which prevents the native submit and focuses the
+     * first invalid field; when it is omitted the form validates and does nothing
+     * else.
+     */
+    onSubmit?: SubmitHandler<TTransformedValues>;
+    /**
+     * Accessible name of the form. A `<form>` only becomes a landmark when it is
+     * named, and screen readers list landmarks by name, so it is required.
+     */
+    'aria-label': string;
+};
+/**
+ * The `<form>` element of a react-hook-form form: it provides the `useForm()`
+ * instance to the form fields inside it (`FormText` and the other `Form<X>`
+ * components) and routes the submit through `handleSubmit`. It always renders
+ * `noValidate`, so the `required` attribute a field sets reaches assistive
+ * technology without the browser's own validation bubble getting in the way:
+ * validation is react-hook-form's, from `rules` or a resolver.
+ *
+ * Use it around any form built with the `Form<X>` fields. Without
+ * react-hook-form, render a plain `<form>` with the presentational primitives
+ * ([FieldText](?path=/docs/components-fieldtext--docs)) instead — this
+ * component is only the binding.
+ *
+ * `react-hook-form` is an optional peer dependency: the design system never
+ * bundles its own copy, because `FormProvider` and the fields must share one
+ * React context. Two copies in an app (a nested version under a workspace,
+ * say) make every field throw from `useController`; `yarn why react-hook-form`
+ * should list a single instance.
+ *
+ * @summary Form element bound to a react-hook-form instance, shared with its fields
+ *
+ * @example
+ * const methods = useForm<Values>({ defaultValues: { agencyName: '', email: '' } });
+ *
+ * <Form.Root methods={methods} onSubmit={saveAgency} aria-label="Agency profile">
+ *   <FormText name="agencyName" label="Agency name" required rules={{ required: 'Enter the agency name.' }} />
+ *   <FormText name="email" label="Email" inputProps={{ type: 'email' }} />
+ *   <Button type="submit">Save</Button>
+ * </Form.Root>
+ */
+export declare const Root: {
+    <TFieldValues extends FieldValues = FieldValues, TTransformedValues = TFieldValues>({ methods, onSubmit, ...props }: FormRootProps<TFieldValues, TTransformedValues>): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/src/form/form.js

@@ -0,0 +1,16 @@
+"use client";
+import { jsx as e } from "react/jsx-runtime";
+import { FormProvider as t } from "react-hook-form";
+//#region src/form/form.tsx
+var n = () => {}, r = ({ methods: r, onSubmit: i, ...a }) => /* @__PURE__ */ e(t, {
+	...r,
+	children: /* @__PURE__ */ e("form", {
+		"data-slot": "form",
+		onSubmit: r.handleSubmit(i ?? n),
+		...a,
+		noValidate: !0
+	})
+});
+r.displayName = "Form.Root";
+//#endregion
+export { r as Root };

package/src/form/index.d.ts

@@ -0,0 +1,7 @@
+export type { FormRootProps } from './form';
+export declare const Form: {
+    Root: {
+        <TFieldValues extends import('react-hook-form').FieldValues = import('react-hook-form').FieldValues, TTransformedValues = TFieldValues>({ methods, onSubmit, ...props }: import('./form').FormRootProps<TFieldValues, TTransformedValues>): import("react/jsx-runtime").JSX.Element;
+        displayName: string;
+    };
+};

package/src/form/index.js

@@ -0,0 +1,5 @@
+import { Root as e } from "./form.js";
+//#region src/form/index.ts
+var t = { Root: e };
+//#endregion
+export { t as Form };

package/src/form-text/form-text.d.ts

@@ -0,0 +1,136 @@
+import { ReactNode } from 'react';
+import { Control, FieldPathByValue, FieldValues, UseControllerProps } from 'react-hook-form';
+import { FieldLabelProps } from '../field';
+import { FieldTextProps } from '../field-text';
+import { InputProps } from '../input';
+/**
+ * Props `FormText` forwards to its `Input`. The field owns `id` (pass
+ * `controlId` on `FormText` to choose it) and react-hook-form owns `name`,
+ * `value` and `defaultValue` (set it in `useForm`'s `defaultValues`).
+ *
+ * The state is the field's as well: `disabled`, `required` and `readOnly` are
+ * props of `FormText` itself and `aria-invalid` follows its validation state.
+ * An `Input` takes its own props over the ones its context hands it, so
+ * setting them here would move the control without the label and the root
+ * following. `aria-describedby` stays open: its ids join the ones the field
+ * wires rather than replacing them.
+ */
+export type FormTextInputProps = Omit<InputProps, 'id' | 'name' | 'value' | 'defaultValue' | 'ref' | 'disabled' | 'required' | 'readOnly' | 'aria-invalid'>;
+/**
+ * The paths of a form's values a `FormText` can bind to: those holding a
+ * string, `null` and `undefined` included, since an input stores a string and
+ * an empty form often starts from either. A path to a number, a boolean or an
+ * object is rejected at compile time; it belongs to the `Form<X>` of that
+ * value type. Untyped forms (`FieldValues`) accept any path.
+ */
+export type FormTextPath<TFieldValues extends FieldValues> = FieldPathByValue<TFieldValues, string | null | undefined>;
+export type FormTextProps<TFieldValues extends FieldValues = FieldValues, TName extends FormTextPath<TFieldValues> = FormTextPath<TFieldValues>, TTransformedValues = TFieldValues> = Omit<FieldTextProps, 'invalid' | 'children'> & {
+    /**
+     * Path of the value in the form, nested paths included (`'agency.npn'`).
+     * Type it against the form's values with the generic
+     * (`<FormText<Values> name="agency.npn" />`) or by passing `control`: the
+     * path must then exist and hold a string (`FormTextPath`).
+     */
+    name: TName;
+    /**
+     * The form's `control`, from `useForm()`. Defaults to the one the
+     * surrounding `Form.Root` provides; pass it explicitly to get `name`
+     * inference without writing the generic, or when the field renders outside
+     * a `Form.Root`. A `control` whose resolver transforms the values is
+     * accepted as is.
+     */
+    control?: Control<TFieldValues, any, TTransformedValues>;
+    /**
+     * react-hook-form validation rules for this field (`required`, `pattern`,
+     * `validate`…), same as `register`'s. They only validate: `rules.required`
+     * does not mark the field `required` — that is a separate, visible decision.
+     */
+    rules?: UseControllerProps<TFieldValues, TName>['rules'];
+    /**
+     * Drops the value from the form when the field unmounts, react-hook-form's
+     * `shouldUnregister`. Defaults to `false`: a field revealed by another one
+     * keeps its value while hidden.
+     */
+    shouldUnregister?: boolean;
+    /** The caption, rendered as the field's label. Text in almost every case. */
+    label: ReactNode;
+    /**
+     * Helper text shown under the control and announced through its
+     * `aria-describedby`. Use it for guidance the user needs before typing; put
+     * details worth a click in `tooltip` instead.
+     */
+    description?: ReactNode;
+    /**
+     * Content of an info tooltip rendered beside the label, for details that
+     * would clutter the description. The trigger is a sibling of the label, so
+     * the field's accessible name stays the label text.
+     */
+    tooltip?: FieldLabelProps['tooltip'];
+    /** Preferred side of the tooltip. Defaults to `'top'`. */
+    tooltipSide?: FieldLabelProps['tooltipSide'];
+    /**
+     * Appends a muted " (optional)" to the label. The forms mark optional fields
+     * rather than required ones; ignored when `required` is set.
+     */
+    optional?: boolean;
+    /**
+     * Marks the field required: an asterisk on the label and the native
+     * `required` attribute on the input, which assistive technology announces.
+     * It does not validate — pair it with `rules.required` or a resolver — and it
+     * never triggers the browser bubble, since `Form.Root` renders `noValidate`.
+     */
+    required?: boolean;
+    /**
+     * Disables the input and marks the field. Unlike react-hook-form's own
+     * `disabled` option, the value stays in the submitted data: disabling a
+     * field is a presentation decision, not a change to the form's values.
+     */
+    disabled?: boolean;
+    /**
+     * Everything else the `Input` should receive: `type`, `placeholder`,
+     * `maxLength`, `autoComplete`, `size`, `className`… Handlers such as
+     * `onChange` and `onBlur` run after react-hook-form's, which are already
+     * wired.
+     */
+    inputProps?: FormTextInputProps;
+};
+/**
+ * A complete text field bound to one react-hook-form value: label, `Input`,
+ * helper text and validation error, laid out in the standard order and wired
+ * through `useController`. It renders inside a `Form.Root`, which provides the
+ * form, and needs only a `name`, which on a typed form must point at a string
+ * (`FormTextPath`). The `required`, `invalid` and error states
+ * reach the label, the input's `aria-*` attributes and the message with no
+ * ids written by hand.
+ *
+ * Use it for the common case: a labelled single-line input in a form. When
+ * the layout is different — an input with addons, another control, a
+ * message rendered elsewhere — compose the primitives yourself:
+ * `useController` with [FieldText](?path=/docs/components-fieldtext--docs),
+ * `Label`, `Input`, `Field.Description` and `Field.Error`. `FormText` adds no
+ * behaviour of its own over that composition.
+ *
+ * Errors come from `useController`'s per-field state, never from
+ * `formState.errors`, so the message stays fresh under the React Compiler.
+ * With `criteriaMode: 'all'` on the form the error carries every rule that
+ * failed and `Field.Error` lists them all. An error on an array or object path
+ * (`error.root`) is not this field's: render a `Field.Error` for it where the
+ * group lives.
+ *
+ * @summary Label, Input, description and error bound to one react-hook-form field
+ *
+ * @example
+ * <FormText
+ *   name="taxId"
+ *   label="Tax ID"
+ *   tooltip="The EIN the IRS issued to the agency."
+ *   description="Nine digits, with or without the dash."
+ *   required
+ *   rules={{ required: 'Enter the tax ID.', pattern: { value: /^\d{2}-?\d{7}$/, message: 'Nine digits.' } }}
+ *   inputProps={{ inputMode: 'numeric', autoComplete: 'off' }}
+ * />
+ */
+export declare const FormText: {
+    <TFieldValues extends FieldValues = FieldValues, TName extends FormTextPath<TFieldValues> = FormTextPath<TFieldValues>, TTransformedValues = TFieldValues>({ name, control, rules, shouldUnregister, disabled, label, description, tooltip, tooltipSide, optional, inputProps, ...root }: FormTextProps<TFieldValues, TName, TTransformedValues>): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/src/form-text/form-text.js

@@ -0,0 +1,40 @@
+"use client";
+import { mergeProps as e } from "../../lib/merge-props.js";
+import { Field as t } from "../field/index.js";
+import { Input as n } from "../input/input.js";
+import { FieldText as r } from "../field-text/field-text.js";
+import { jsx as i, jsxs as a } from "react/jsx-runtime";
+import { useController as o } from "react-hook-form";
+//#region src/form-text/form-text.tsx
+var s = ({ name: s, control: c, rules: l, shouldUnregister: u, disabled: d, label: f, description: p, tooltip: m, tooltipSide: h, optional: g, inputProps: _, ...v }) => {
+	let { field: y, fieldState: b } = o({
+		name: s,
+		control: c,
+		rules: l,
+		shouldUnregister: u
+	}), x = {
+		name: y.name,
+		value: y.value ?? "",
+		onChange: y.onChange,
+		onBlur: y.onBlur,
+		ref: y.ref
+	};
+	return /* @__PURE__ */ a(r, {
+		invalid: b.invalid,
+		disabled: d || y.disabled,
+		...v,
+		children: [/* @__PURE__ */ i(t.Label, {
+			tooltip: m,
+			tooltipSide: h,
+			optional: g,
+			children: f
+		}), /* @__PURE__ */ a(t.Content, { children: [
+			/* @__PURE__ */ i(n, { ...e(x, _ ?? {}) }),
+			p && /* @__PURE__ */ i(t.Description, { children: p }),
+			/* @__PURE__ */ i(t.Error, { errors: b.error ? [b.error] : void 0 })
+		] })]
+	});
+};
+s.displayName = "FormText";
+//#endregion
+export { s as FormText };

package/src/form-text/index.d.ts

@@ -0,0 +1,2 @@
+export { FormText } from './form-text';
+export type { FormTextInputProps, FormTextPath, FormTextProps } from './form-text';

package/src/form-text/index.js

@@ -0,0 +1,2 @@
+import { FormText as e } from "./form-text.js";
+export { e as FormText };