@rovula/ui 0.1.7 → 0.1.8

package/src/components/Form/Form.tsx

@@ -1,99 +1,197 @@
-// src/Form.tsx
-import React, { useState } from "react";
+import React, { FormHTMLAttributes, ReactNode } from "react";
+import {
+  DefaultValues,
+  FieldValues,
+  FormProvider,
+  Mode,
+  Resolver,
+  SubmitErrorHandler,
+  SubmitHandler,
+  useForm,
+  UseFormReturn,
+} from "react-hook-form";
+import { yupResolver } from "@hookform/resolvers/yup";
 import * as yup from "yup";
 
-interface FormValues {
-  name: string;
-  email: string;
-  password: string;
-}
-
-interface FormProps {
-  onSubmit: (values: FormValues) => void;
-  className?: string;
-}
-
-const schema = yup.object().shape({
-  name: yup.string().required("Name is required"),
-  email: yup.string().email("Invalid email").required("Email is required"),
-  password: yup
-    .string()
-    .min(6, "Password must be at least 6 characters")
-    .required("Password is required"),
-});
-
-const Form: React.FC<FormProps> = ({ onSubmit, className = "" }) => {
-  const [values, setValues] = useState<FormValues>({
-    name: "",
-    email: "",
-    password: "",
+type FormChildren<TFieldValues extends FieldValues> =
+  | ReactNode
+  | ((methods: UseFormReturn<TFieldValues>) => ReactNode);
+
+export type FormController<TFieldValues extends FieldValues> = {
+  submit: () => Promise<void>;
+  getValues: () => TFieldValues;
+  setValue: UseFormReturn<TFieldValues>["setValue"];
+  trigger: UseFormReturn<TFieldValues>["trigger"];
+  reset: UseFormReturn<TFieldValues>["reset"];
+};
+
+export type FormProps<TFieldValues extends FieldValues> = Omit<
+  FormHTMLAttributes<HTMLFormElement>,
+  "children" | "onSubmit"
+> & {
+  children: FormChildren<TFieldValues>;
+  defaultValues: DefaultValues<TFieldValues>;
+  methods?: UseFormReturn<TFieldValues>;
+  controllerRef?: React.MutableRefObject<FormController<TFieldValues> | null>;
+  onSubmit: SubmitHandler<TFieldValues>;
+  onInvalidSubmit?: SubmitErrorHandler<TFieldValues>;
+  resolver?: Resolver<TFieldValues>;
+  validationSchema?: yup.ObjectSchema<any>;
+  mode?: Mode;
+  // RHF does not export this type in all versions.
+  // Keep compatibility with allowed re-validate modes.
+  reValidateMode?: Exclude<Mode, "onTouched" | "all">;
+};
+
+export const createYupResolver = <TFieldValues extends FieldValues>(
+  schema: yup.ObjectSchema<any>
+) => yupResolver(schema) as Resolver<TFieldValues>;
+
+export type ControlledFormFactoryOptions<TFieldValues extends FieldValues> = {
+  methods: UseFormReturn<TFieldValues>;
+  defaultValues: DefaultValues<TFieldValues>;
+  controllerRef?: React.MutableRefObject<FormController<TFieldValues> | null>;
+};
+
+export type UseControlledFormOptions<TFieldValues extends FieldValues> = {
+  defaultValues: DefaultValues<TFieldValues>;
+  controllerRef?: React.MutableRefObject<FormController<TFieldValues> | null>;
+  resolver?: Resolver<TFieldValues>;
+  validationSchema?: yup.ObjectSchema<any>;
+  mode?: Mode;
+  reValidateMode?: Exclude<Mode, "onTouched" | "all">;
+};
+
+export const createControlledForm = <TFieldValues extends FieldValues>({
+  methods,
+  defaultValues,
+  controllerRef,
+}: ControlledFormFactoryOptions<TFieldValues>) => {
+  const FormRoot = React.forwardRef<
+    FormController<TFieldValues>,
+    Omit<FormProps<TFieldValues>, "methods" | "defaultValues" | "controllerRef">
+  >(({ children, ...props }, ref) => (
+    <Form<TFieldValues>
+      {...props}
+      ref={ref}
+      methods={methods}
+      defaultValues={defaultValues}
+      controllerRef={controllerRef}
+    >
+      {children}
+    </Form>
+  ));
+  FormRoot.displayName = "ControlledFormRoot";
+
+  return {
+    methods,
+    FormRoot,
+  };
+};
+
+export const useControlledForm = <TFieldValues extends FieldValues>({
+  defaultValues,
+  controllerRef,
+  resolver,
+  validationSchema,
+  mode = "onSubmit",
+  reValidateMode = "onChange",
+}: UseControlledFormOptions<TFieldValues>) => {
+  const resolvedResolver =
+    resolver ??
+    (validationSchema
+      ? createYupResolver<TFieldValues>(validationSchema)
+      : undefined);
+
+  const methods = useForm<TFieldValues>({
+    defaultValues,
+    resolver: resolvedResolver,
+    mode,
+    reValidateMode,
+  });
+
+  return createControlledForm<TFieldValues>({
+    methods,
+    defaultValues,
+    controllerRef,
+  });
+};
+
+const FormInner = <TFieldValues extends FieldValues>(
+  {
+    children,
+    defaultValues,
+    methods: externalMethods,
+    controllerRef,
+    onSubmit,
+    onInvalidSubmit,
+    resolver,
+    validationSchema,
+    mode = "onSubmit",
+    reValidateMode = "onChange",
+    noValidate = true,
+    ...formProps
+  }: FormProps<TFieldValues>,
+  ref: React.ForwardedRef<FormController<TFieldValues>>
+) => {
+  const resolvedResolver =
+    resolver ??
+    (validationSchema
+      ? createYupResolver<TFieldValues>(validationSchema)
+      : undefined);
+
+  const internalMethods = useForm<TFieldValues>({
+    defaultValues,
+    resolver: resolvedResolver,
+    mode,
+    reValidateMode,
   });
-  const [errors, setErrors] = useState<{ [key in keyof FormValues]?: string }>(
-    {}
+  const methods = externalMethods ?? internalMethods;
+
+  const controller = React.useMemo<FormController<TFieldValues>>(
+    () => ({
+      submit: async () => {
+        await methods.handleSubmit(onSubmit, onInvalidSubmit)();
+      },
+      getValues: () => methods.getValues(),
+      setValue: methods.setValue,
+      trigger: methods.trigger,
+      reset: methods.reset,
+    }),
+    [methods, onSubmit, onInvalidSubmit]
   );
 
-  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-    const { name, value } = e.target;
-    setValues({ ...values, [name]: value });
-  };
+  React.useImperativeHandle(ref, () => controller, [controller]);
 
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    try {
-      await schema.validate(values, { abortEarly: false });
-      setErrors({});
-      onSubmit(values);
-    } catch (err) {
-      if (err instanceof yup.ValidationError) {
-        const validationErrors: { [key in keyof FormValues]?: string } = {};
-        err.inner.forEach((error) => {
-          if (error.path) {
-            validationErrors[error.path as keyof FormValues] = error.message;
-          }
-        });
-        setErrors(validationErrors);
-      }
-    }
-  };
+  React.useEffect(() => {
+    if (!controllerRef) return;
+
+    controllerRef.current = controller;
+
+    return () => {
+      controllerRef.current = null;
+    };
+  }, [controllerRef, controller]);
 
   return (
-    <form className={`form ${className}`} onSubmit={handleSubmit}>
-      <div className="form-group">
-        <label htmlFor="name">Name</label>
-        <input
-          id="name"
-          name="name"
-          type="text"
-          value={values.name}
-          onChange={handleChange}
-        />
-        {errors.name && <span className="error">{errors.name}</span>}
-      </div>
-      <div className="form-group">
-        <label htmlFor="email">Email</label>
-        <input
-          id="email"
-          name="email"
-          type="email"
-          value={values.email}
-          onChange={handleChange}
-        />
-        {errors.email && <span className="error">{errors.email}</span>}
-      </div>
-      <div className="form-group">
-        <label htmlFor="password">Password</label>
-        <input
-          id="password"
-          name="password"
-          type="password"
-          value={values.password}
-          onChange={handleChange}
-        />
-        {errors.password && <span className="error">{errors.password}</span>}
-      </div>
-      <button type="submit">Submit</button>
-    </form>
+    <FormProvider {...methods}>
+      <form
+        {...formProps}
+        noValidate={noValidate}
+        onSubmit={methods.handleSubmit(onSubmit, onInvalidSubmit)}
+      >
+        {typeof children === "function" ? children(methods) : children}
+      </form>
+    </FormProvider>
   );
 };
 
+type FormComponent = <TFieldValues extends FieldValues>(
+  props: FormProps<TFieldValues> & {
+    ref?: React.Ref<FormController<TFieldValues>>;
+  }
+) => React.ReactElement;
+
+export const Form = React.forwardRef(FormInner) as FormComponent;
+
 export default Form;

package/src/components/Form/README.md

@@ -0,0 +1,284 @@
+# Form Component Guide
+
+This guide explains how to use the `Form` system in this UI package:
+
+- `Form` (react-hook-form wrapper)
+- `Field` (adapter for UI components)
+- `FieldMessage` (error message renderer)
+- `ValidationHintList` (rule checklist UI)
+- `useControlledForm` / `createControlledForm` (control form from parent layer)
+- `useOptionBridge` (map `id <-> option` for async dropdown use cases)
+
+---
+
+## Quick Start
+
+```tsx
+import * as yup from "yup";
+import { Form, Field } from "@/components/Form";
+import TextInput from "@/components/TextInput/TextInput";
+import Button from "@/components/Button/Button";
+
+type LoginFormValues = {
+  email: string;
+  password: string;
+};
+
+const schema = yup.object({
+  email: yup.string().email("Invalid email").required("Email is required"),
+  password: yup.string().min(6, "At least 6 characters").required("Password is required"),
+});
+
+<Form<LoginFormValues>
+  defaultValues={{ email: "", password: "" }}
+  validationSchema={schema}
+  onSubmit={(values) => {
+    console.log(values);
+  }}
+>
+  <Field<LoginFormValues, "email">
+    name="email"
+    component={TextInput}
+    componentProps={{ label: "Email", required: true }}
+  />
+  <Field<LoginFormValues, "password">
+    name="password"
+    component={TextInput}
+    componentProps={{ label: "Password", type: "password", required: true }}
+  />
+  <Button type="submit">Sign in</Button>
+</Form>;
+```
+
+---
+
+## Core Concepts
+
+### 1) `defaultValues` is the source of truth
+
+Set initial values at `Form.defaultValues` whenever possible.
+
+```tsx
+<Form defaultValues={{ role: "dev" }} ... />
+```
+
+You can also use `Field.defaultValue` for specific cases, but the primary pattern is form-level defaults.
+
+### 2) `Field` injects value/change/blur/ref
+
+`Field` internally uses `useController` and injects controlled props into your component.
+
+By default:
+
+- value prop name: `value`
+- change prop name: `onChange`
+- blur prop name: `onBlur`
+- ref prop name: `ref`
+
+If your component uses different prop names, map them with `valuePropName`, `changePropName`, etc.
+
+### 3) Validation modes are RHF modes
+
+`Form.mode` and `Form.reValidateMode` pass through to react-hook-form.
+
+Examples:
+
+- `mode="onSubmit"` (default)
+- `mode="onChange"`
+- `mode="onTouched"`
+
+Important: `onTouched` requires your input path to call `onBlur` correctly.
+
+---
+
+## `Field` Props You Will Use Most
+
+### `component` and `componentProps`
+
+Use `component` for the render target, and `componentProps` for static/custom props.
+
+```tsx
+<Field
+  name="email"
+  component={TextInput}
+  componentProps={{ label: "Email", helperText: "Use your work email" }}
+/>
+```
+
+### Mapping non-standard component APIs
+
+If a component does not use `value` + `onChange`, map them:
+
+```tsx
+<Field
+  name="role"
+  component={Dropdown}
+  valuePropName="value"
+  changePropName="onSelect"
+/>
+```
+
+### Transform value in/out (`formatValue` and `parseValue`)
+
+- `formatValue`: form state -> component value
+- `parseValue`: component payload -> form state
+
+```tsx
+<Field
+  name="roleId"
+  component={Dropdown}
+  valuePropName="value"
+  changePropName="onSelect"
+  formatValue={(roleId) => options.find((item) => item.value === roleId)}
+  parseValue={(option) => (option as Options | undefined)?.value ?? ""}
+/>
+```
+
+### Optional passthrough toggles
+
+Disable specific injected props when a component should not receive them:
+
+- `blurPropName={false}`
+- `refPropName={false}`
+- `errorMessagePropName={false}`
+- `invalidPropName={false}`
+
+---
+
+## Showing Error Messages
+
+### A) Through component props (default behavior)
+
+`Field` sends:
+
+- `errorMessage` (from RHF field error)
+- `error` (boolean invalid state)
+
+You can rename these with:
+
+- `errorMessagePropName`
+- `invalidPropName`
+
+### B) Via `FieldMessage`
+
+Use when your input component does not render its own message:
+
+```tsx
+<Field name="email" component={TextInput} />
+<FieldMessage name="email" />
+```
+
+---
+
+## Async Dropdown Pattern (`id` in form, option object in UI)
+
+Most projects store only primitive IDs in form state (`string`/`number`) and map to option objects for UI rendering.
+
+Use `useOptionBridge` to avoid repeated mapping code.
+
+```tsx
+import { useOptionBridge } from "@/components/Form";
+
+const { toOption, toValue } = useOptionBridge({
+  options, // [{ value: "dev", label: "Developer" }]
+  loading,
+});
+
+<Field<FormValues, "roleId", DropdownProps>
+  name="roleId"
+  component={Dropdown}
+  componentProps={{ options, disabled: loading }}
+  valuePropName="value"
+  changePropName="onSelect"
+  formatValue={(id) => toOption(id)}
+  parseValue={(option) => toValue(option as Option | undefined) ?? ""}
+/>;
+```
+
+If options can be delayed, use `toOptionWithFallback` and provide `buildFallbackOption` when needed.
+
+---
+
+## Controlled Form From Parent Layer
+
+Use `useControlledForm` when a parent (outside form JSX) needs to:
+
+- submit
+- read values
+- set values
+- trigger validation
+- reset
+
+```tsx
+const { methods, FormRoot } = useControlledForm<FormValues>({
+  defaultValues,
+  validationSchema: schema,
+  mode: "onChange",
+});
+
+<Button type="button" onClick={() => methods.handleSubmit(onSubmit)()}>
+  Submit outside form
+</Button>
+
+<FormRoot onSubmit={onSubmit}>
+  <Field name="title" component={TextInput} />
+</FormRoot>;
+```
+
+You can also use `controllerRef` / forwarded ref with `FormController`.
+
+### Ref API (`FormController`)
+
+When using `ref` or `controllerRef`, available methods are:
+
+- `submit()`
+- `getValues()`
+- `setValue()`
+- `trigger()`
+- `reset()`
+
+```tsx
+const formRef = React.useRef<FormController<FormValues> | null>(null);
+
+await formRef.current?.submit();
+formRef.current?.setValue("title", "New title", { shouldValidate: true });
+const values = formRef.current?.getValues();
+```
+
+---
+
+## Best Practices
+
+- Keep form state as primitives (`id`, `code`) unless you truly need full objects.
+- Prefer `Form.defaultValues` over per-field defaults.
+- Keep input components controlled and ensure they call `onChange` and `onBlur`.
+- Use `formatValue`/`parseValue` only when API shape differs.
+- For `mode="onTouched"`, make sure focus leaving the field triggers `onBlur` once.
+- Avoid inline anonymous components in `Field.component` for stable rendering.
+
+---
+
+## Common Pitfalls
+
+- **Validation not running on touched**: custom input does not call `onBlur`.
+- **Dropdown not showing selected label**: options not loaded yet, or `formatValue` missing.
+- **Submitted payload too heavy**: storing full option objects instead of IDs.
+- **State mismatch**: setting local component default separately from RHF default values.
+
+---
+
+## Export Surface
+
+From `@/components/Form`:
+
+- `Form`
+- `Field`
+- `FieldMessage`
+- `ValidationHintList`
+- `useControlledForm`
+- `createControlledForm`
+- `createYupResolver`
+- `useOptionBridge`
+
+Related types are exported alongside these utilities.
+

package/src/components/Form/ValidationHintList.stories.tsx

@@ -0,0 +1,118 @@
+import React, { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import PasswordInput from "@/components/PasswordInput";
+import { ValidationHintList, ValidationHintRule } from "./ValidationHintList";
+
+type PasswordValues = {
+  password: string;
+  confirmPassword: string;
+};
+
+const rules: ValidationHintRule<PasswordValues>[] = [
+  {
+    id: "min-length",
+    label: "Minimum 12 characters",
+    validate: (values) => values.password.length >= 12,
+    when: (values) => Boolean(values.password),
+  },
+  {
+    id: "upper-lower",
+    label: "At least one upper and lower case",
+    validate: (values) =>
+      /[a-z]/.test(values.password) && /[A-Z]/.test(values.password),
+    when: (values) => Boolean(values.password),
+  },
+  {
+    id: "match",
+    label: "Password and confirmation are matching",
+    validate: (values) =>
+      Boolean(values.password) && values.password === values.confirmPassword,
+    when: (values) =>
+      Boolean(values.password) && Boolean(values.confirmPassword),
+  },
+];
+
+const meta: Meta = {
+  title: "Components/Form/ValidationHintList",
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const ThreeState = {
+  render: () => {
+    const [values, setValues] = useState<PasswordValues>({
+      password: "",
+      confirmPassword: "",
+    });
+
+    return (
+      <div className="w-[420px] max-w-full rounded-md bg-bg-bg2 p-4">
+        <div className="flex flex-col gap-3">
+          <PasswordInput
+            label="Password"
+            value={values.password}
+            onChange={(event) =>
+              setValues((prev) => ({ ...prev, password: event.target.value }))
+            }
+          />
+          <PasswordInput
+            label="Confirm password"
+            value={values.confirmPassword}
+            onChange={(event) =>
+              setValues((prev) => ({
+                ...prev,
+                confirmPassword: event.target.value,
+              }))
+            }
+          />
+        </div>
+
+        <ValidationHintList values={values} rules={rules} />
+      </div>
+    );
+  },
+} satisfies Story;
+
+export const TwoState = {
+  render: () => {
+    const [values, setValues] = useState<PasswordValues>({
+      password: "",
+      confirmPassword: "",
+    });
+
+    return (
+      <div className="w-[420px] max-w-full rounded-md bg-bg-bg2 p-4">
+        <div className="flex flex-col gap-3">
+          <PasswordInput
+            label="Password"
+            value={values.password}
+            onChange={(event) =>
+              setValues((prev) => ({ ...prev, password: event.target.value }))
+            }
+          />
+          <PasswordInput
+            label="Confirm password"
+            value={values.confirmPassword}
+            onChange={(event) =>
+              setValues((prev) => ({
+                ...prev,
+                confirmPassword: event.target.value,
+              }))
+            }
+          />
+        </div>
+
+        <ValidationHintList
+          values={values}
+          rules={rules}
+          mode={["pending", "valid"]}
+        />
+      </div>
+    );
+  },
+} satisfies Story;