@pickle-ui/react 0.0.0-stage → 1.0.0-beta.3

package/src/components/form/Form.context.ts

@@ -0,0 +1,114 @@
+import * as React from 'react';
+import {
+  useFormContext,
+  type UseFormReturn,
+  useFormState,
+} from 'react-hook-form';
+
+type FormControlProps = {
+  id?: string;
+};
+type FormFieldContextValue = {
+  controlId?: string;
+  name?: string;
+};
+type UseFormControlPropsOptions = {
+  enabled?: boolean;
+};
+type WithoutAriaInvalid<Props> = Omit<Props, 'aria-invalid'> & {
+  'aria-invalid'?: never;
+};
+
+const FormFieldContext = React.createContext<FormFieldContextValue | null>(
+  null,
+);
+const FormInputGroupContext = React.createContext(false);
+
+function getErrorMessage(error: unknown): React.ReactNode {
+  if (!error || typeof error !== 'object') {
+    return undefined;
+  }
+
+  const message = (error as { message?: unknown }).message;
+
+  if (
+    React.isValidElement(message) ||
+    typeof message === 'string' ||
+    typeof message === 'number'
+  ) {
+    return message;
+  }
+
+  return undefined;
+}
+
+function useFieldName(name: string | undefined) {
+  const field = React.useContext(FormFieldContext);
+
+  return name ?? field?.name;
+}
+
+// React Hook Form exposes field state, but it does not attach DOM aria/id
+// props to custom controls. This maps the current Form.Field onto the actual
+// visible control.
+function useFormControlProps(
+  props: FormControlProps = {},
+  { enabled = true }: UseFormControlPropsOptions = {},
+) {
+  const field = React.useContext(FormFieldContext);
+  const { control, getFieldState } = useFormMethods();
+  const name = enabled ? field?.name : undefined;
+  const formState = useFormState({
+    control,
+    disabled: !name,
+    exact: true,
+    name,
+  });
+  const controlId = enabled ? field?.controlId : undefined;
+  const invalid = name ? getFieldState(name, formState).invalid : false;
+
+  return {
+    'aria-invalid': controlId && invalid ? true : undefined,
+    id: controlId ?? props.id,
+  };
+}
+
+function useFormMethods() {
+  const methods = useFormContext() as null | UseFormReturn;
+
+  if (!methods) {
+    throw new Error(
+      'Form components must be rendered inside <Form form={form}>.',
+    );
+  }
+
+  return methods;
+}
+
+function useRequiredFieldName(name: string | undefined, componentName: string) {
+  const fieldName = useFieldName(name);
+
+  if (!fieldName) {
+    throw new Error(
+      `${componentName} requires a name prop or a parent <Form.Field name="...">.`,
+    );
+  }
+
+  return fieldName;
+}
+
+export {
+  FormFieldContext,
+  FormInputGroupContext,
+  getErrorMessage,
+  useFieldName,
+  useFormControlProps,
+  useFormMethods,
+  useRequiredFieldName,
+};
+export type {
+  FormControlProps,
+  FormFieldContextValue,
+  UseFormControlPropsOptions,
+  WithoutAriaInvalid,
+};

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

@@ -0,0 +1,226 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { zodResolver } from '@hookform/resolvers/zod';
+import * as React from 'react';
+import { useForm } from 'react-hook-form';
+import { z } from 'zod/v4';
+
+import { Story } from '../_internal/Story';
+import { Form } from './Form';
+
+const meta = {
+  args: {},
+  component: Form,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  title: 'components/Form',
+} satisfies Meta<typeof Form>;
+
+export default meta;
+
+type StoryDefinition = StoryObj;
+
+const roles = [
+  { label: 'Designer', value: 'designer' },
+  { label: 'Engineer', value: 'engineer' },
+  { label: 'Manager', value: 'manager' },
+] as const;
+
+const notificationChannels: {
+  disabled?: boolean;
+  label: string;
+  value: string;
+}[] = [
+  { label: 'Email', value: 'email' },
+  { label: 'SMS', value: 'sms' },
+  { disabled: true, label: 'Push (coming soon)', value: 'push' },
+];
+
+const defaultInterests = [
+  { label: 'Design systems', value: 'design-systems' },
+  { label: 'Accessibility', value: 'accessibility' },
+  { label: 'Performance', value: 'performance' },
+];
+
+type Interest = (typeof defaultInterests)[number];
+
+const signUpSchema = z.object({
+  bio: z.string().max(160, 'Keep it under 160 characters.'),
+  email: z.email('Enter a valid email address.'),
+  firstName: z.string().trim().min(1, 'Enter your first name.'),
+  interests: z
+    .array(z.object({ label: z.string(), value: z.string() }))
+    .min(1, 'Pick at least one interest.'),
+  lastName: z.string().trim().min(1, 'Enter your last name.'),
+  notificationChannel: z.enum(['email', 'sms']),
+  password: z.string().min(8, 'Use at least 8 characters.'),
+  productUpdates: z.boolean(),
+  role: z.enum(['designer', 'engineer', 'manager']),
+  terms: z.boolean().refine(Boolean, 'Accept the terms to continue.'),
+  username: z.string().trim().min(1, 'Enter a username.'),
+});
+
+type SignUpValues = z.infer<typeof signUpSchema>;
+
+function SignUpForm() {
+  const form = useForm<SignUpValues>({
+    defaultValues: {
+      bio: '',
+      email: '',
+      firstName: '',
+      interests: [],
+      lastName: '',
+      notificationChannel: 'email',
+      password: '',
+      productUpdates: true,
+      role: 'designer',
+      terms: false,
+      username: '',
+    },
+    resolver: zodResolver(signUpSchema),
+  });
+  const [interests, setInterests] = React.useState(defaultInterests);
+
+  return (
+    <Form className="max-w-md" form={form} onSubmit={() => form.clearErrors()}>
+      <Form.Field
+        description="We'll send a confirmation link to this address."
+        label="Email"
+        name="email"
+      >
+        <Form.Input autoComplete="email" inputMode="email" />
+      </Form.Field>
+
+      <Form.Field label="Username" name="username">
+        <Form.Input autoComplete="username" />
+      </Form.Field>
+
+      <Form.Field
+        description="At least 8 characters."
+        label="Password"
+        name="password"
+      >
+        <Form.Input autoComplete="new-password" type="password" />
+      </Form.Field>
+
+      <Form.Field controlId="full-name" label="Full name">
+        <Form.InputGroup>
+          <Form.Input
+            aria-label="First name"
+            name="firstName"
+            placeholder="First"
+          />
+          <Form.Input
+            aria-label="Last name"
+            name="lastName"
+            placeholder="Last"
+          />
+        </Form.InputGroup>
+      </Form.Field>
+
+      <Form.Field label="Role" name="role">
+        <Form.Select>
+          <Form.Select.Trigger className="w-full">
+            <Form.Select.Value placeholder="Select a role" />
+          </Form.Select.Trigger>
+          <Form.Select.Content>
+            {roles.map((role) => (
+              <Form.Select.Item key={role.value} value={role.value}>
+                {role.label}
+              </Form.Select.Item>
+            ))}
+          </Form.Select.Content>
+        </Form.Select>
+      </Form.Field>
+
+      <Form.Field
+        description="Pick from the list or type to add your own."
+        label="Interests"
+        name="interests"
+      >
+        <Form.Combobox
+          items={interests}
+          multiple
+          onCreate={(label) => {
+            const interest = { label, value: label.toLowerCase() };
+            setInterests((current) => [...current, interest]);
+
+            return interest;
+          }}
+        >
+          <Form.Combobox.Chips>
+            <Form.Combobox.Value>
+              {(value: Interest[]) => (
+                <>
+                  {value.map((interest) => (
+                    <Form.Combobox.Chip key={interest.value}>
+                      {interest.label}
+                    </Form.Combobox.Chip>
+                  ))}
+                  <Form.Combobox.ChipsInput
+                    placeholder={value.length > 0 ? '' : 'Add interests…'}
+                  />
+                </>
+              )}
+            </Form.Combobox.Value>
+          </Form.Combobox.Chips>
+          <Form.Combobox.Content>
+            <Form.Combobox.List>
+              {(interest: Interest) => (
+                <Form.Combobox.Item key={interest.value} value={interest}>
+                  {interest.label}
+                </Form.Combobox.Item>
+              )}
+            </Form.Combobox.List>
+          </Form.Combobox.Content>
+        </Form.Combobox>
+      </Form.Field>
+
+      <Form.Field
+        description="A sentence or two for your public profile."
+        label="Bio"
+        name="bio"
+      >
+        <Form.Textarea placeholder="Tell us about yourself" />
+      </Form.Field>
+
+      <Form.Field name="productUpdates">
+        <Form.Switch label="Email me about new features and releases" />
+      </Form.Field>
+
+      <Form.Field
+        description="How should we reach you for account alerts?"
+        label="Notification channel"
+        name="notificationChannel"
+      >
+        <Form.RadioGroup>
+          {notificationChannels.map((channel) => (
+            <Form.RadioGroup.Item
+              disabled={channel.disabled}
+              key={channel.value}
+              label={channel.label}
+              value={channel.value}
+            />
+          ))}
+        </Form.RadioGroup>
+      </Form.Field>
+
+      <Form.Field name="terms">
+        <Form.Checkbox label="I agree to the terms of service and privacy policy" />
+      </Form.Field>
+
+      <Form.Button type="submit">Create account</Form.Button>
+    </Form>
+  );
+}
+
+export const SignUp: StoryDefinition = {
+  render: () => (
+    <Story.Layout className="max-w-lg" title="Form">
+      <Story.Section title="Sign up">
+        <SignUpForm />
+      </Story.Section>
+    </Story.Layout>
+  ),
+};

package/src/components/form/Form.test.tsx

@@ -0,0 +1,293 @@
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import * as React from 'react';
+import { useForm } from 'react-hook-form';
+import { describe, expect, it, vi } from 'vitest';
+
+import { Form } from './Form';
+
+type TestFormValues = {
+  channel: string;
+  email: string;
+  message: string;
+  productUpdates: boolean;
+  role: string;
+  terms: boolean;
+};
+
+const defaultValues: TestFormValues = {
+  channel: 'email',
+  email: '',
+  message: '',
+  productUpdates: false,
+  role: 'designer',
+  terms: false,
+};
+
+function TestForm({
+  fieldErrors,
+  onSubmit,
+  withEmailError,
+}: {
+  fieldErrors?: Partial<Record<keyof TestFormValues, string>>;
+  onSubmit: (values: TestFormValues) => void;
+  withEmailError?: boolean;
+}) {
+  const form = useForm<TestFormValues>({ defaultValues });
+
+  React.useEffect(() => {
+    if (withEmailError) {
+      form.setError('email', {
+        message: 'Enter a valid email address.',
+        type: 'manual',
+      });
+    }
+
+    for (const [name, message] of Object.entries(fieldErrors ?? {}) as [
+      keyof TestFormValues,
+      string,
+    ][]) {
+      form.setError(name, {
+        message,
+        type: 'manual',
+      });
+    }
+  }, [fieldErrors, form, withEmailError]);
+
+  return (
+    <Form form={form} onSubmit={onSubmit}>
+      <Form.Field label="Email" name="email">
+        <Form.Input autoComplete="email" />
+      </Form.Field>
+
+      <Form.Field label="Message" name="message">
+        <Form.Textarea />
+      </Form.Field>
+
+      <Form.Field label="Role" name="role">
+        <Form.Select>
+          <Form.Select.Trigger>
+            <Form.Select.Value placeholder="Select a role" />
+          </Form.Select.Trigger>
+          <Form.Select.Content>
+            <Form.Select.Item value="designer">Designer</Form.Select.Item>
+            <Form.Select.Item value="engineer">Engineer</Form.Select.Item>
+          </Form.Select.Content>
+        </Form.Select>
+      </Form.Field>
+
+      <Form.Field label="Notification channel" name="channel">
+        <Form.RadioGroup>
+          <Form.RadioGroup.Item label="Email" value="email" />
+          <Form.RadioGroup.Item label="SMS" value="sms" />
+        </Form.RadioGroup>
+      </Form.Field>
+
+      <Form.Field name="productUpdates">
+        <Form.Switch label="Product updates" />
+      </Form.Field>
+
+      <Form.Field name="terms">
+        <Form.Checkbox label="Accept terms" />
+      </Form.Field>
+
+      <Form.Button type="submit">Submit</Form.Button>
+    </Form>
+  );
+}
+
+describe('Form', () => {
+  it('registers fields and submits React Hook Form values', async () => {
+    const handleSubmit = vi.fn();
+    render(<TestForm onSubmit={handleSubmit} />);
+
+    fireEvent.change(screen.getByRole('textbox', { name: 'Email' }), {
+      target: { value: 'ugo@example.com' },
+    });
+    fireEvent.change(screen.getByRole('textbox', { name: 'Message' }), {
+      target: { value: 'Hello' },
+    });
+    fireEvent.click(screen.getByRole('switch', { name: 'Product updates' }));
+    fireEvent.click(screen.getByRole('checkbox', { name: 'Accept terms' }));
+    fireEvent.click(screen.getByRole('radio', { name: 'SMS' }));
+    fireEvent.click(screen.getByRole('button', { name: 'Submit' }));
+
+    await waitFor(() => {
+      expect(handleSubmit).toHaveBeenCalledWith(
+        {
+          channel: 'sms',
+          email: 'ugo@example.com',
+          message: 'Hello',
+          productUpdates: true,
+          role: 'designer',
+          terms: true,
+        },
+        expect.anything(),
+      );
+    });
+  });
+
+  it('displays field errors from React Hook Form state', async () => {
+    render(<TestForm onSubmit={vi.fn()} withEmailError />);
+
+    expect(
+      await screen.findByText('Enter a valid email address.'),
+    ).toBeInTheDocument();
+    expect(screen.getByRole('textbox', { name: 'Email' })).toHaveAttribute(
+      'aria-invalid',
+      'true',
+    );
+  });
+
+  it('marks controlled boolean fields invalid from React Hook Form state', async () => {
+    render(
+      <TestForm
+        fieldErrors={{
+          productUpdates: 'Choose a product update preference.',
+          terms: 'Accept the terms to continue.',
+        }}
+        onSubmit={vi.fn()}
+      />,
+    );
+
+    expect(
+      await screen.findByText('Choose a product update preference.'),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('switch', { name: 'Product updates' }),
+    ).toHaveAttribute('aria-invalid', 'true');
+    expect(
+      screen.getByRole('checkbox', { name: 'Accept terms' }),
+    ).toHaveAttribute('aria-invalid', 'true');
+  });
+
+  describe('Form.Combobox', () => {
+    type Fruit = { label: string; value: string };
+    type FruitFormValues = { fruit: Fruit | null; tags: Fruit[] };
+
+    const FRUITS: Fruit[] = [
+      { label: 'Apple', value: 'apple' },
+      { label: 'Banana', value: 'banana' },
+    ];
+
+    function FruitForm({
+      fruitError,
+      onSubmit,
+    }: {
+      fruitError?: string;
+      onSubmit: (values: FruitFormValues) => void;
+    }) {
+      const form = useForm<FruitFormValues>({
+        defaultValues: { fruit: null, tags: [] },
+      });
+      const [tags, setTags] = React.useState(FRUITS);
+
+      React.useEffect(() => {
+        if (fruitError) {
+          form.setError('fruit', { message: fruitError, type: 'manual' });
+        }
+      }, [form, fruitError]);
+
+      return (
+        <Form form={form} onSubmit={onSubmit}>
+          <Form.Field label="Fruit" name="fruit">
+            <Form.Combobox items={FRUITS}>
+              <Form.Combobox.Input />
+              <Form.Combobox.Content>
+                <Form.Combobox.List>
+                  {(fruit: Fruit) => (
+                    <Form.Combobox.Item key={fruit.value} value={fruit}>
+                      {fruit.label}
+                    </Form.Combobox.Item>
+                  )}
+                </Form.Combobox.List>
+              </Form.Combobox.Content>
+            </Form.Combobox>
+          </Form.Field>
+
+          <Form.Field label="Tags" name="tags">
+            <Form.Combobox
+              items={tags}
+              multiple
+              onCreate={(label) => {
+                const tag = { label, value: label.toLowerCase() };
+                setTags((current) => [...current, tag]);
+
+                return tag;
+              }}
+            >
+              <Form.Combobox.Chips>
+                <Form.Combobox.Value>
+                  {(value: Fruit[]) => (
+                    <>
+                      {value.map((tag) => (
+                        <Form.Combobox.Chip key={tag.value}>
+                          {tag.label}
+                        </Form.Combobox.Chip>
+                      ))}
+                      <Form.Combobox.ChipsInput />
+                    </>
+                  )}
+                </Form.Combobox.Value>
+              </Form.Combobox.Chips>
+              <Form.Combobox.Content>
+                <Form.Combobox.List>
+                  {(tag: Fruit) => (
+                    <Form.Combobox.Item key={tag.value} value={tag}>
+                      {tag.label}
+                    </Form.Combobox.Item>
+                  )}
+                </Form.Combobox.List>
+              </Form.Combobox.Content>
+            </Form.Combobox>
+          </Form.Field>
+
+          <Form.Button type="submit">Submit</Form.Button>
+        </Form>
+      );
+    }
+
+    function type(name: string, text: string) {
+      const input = screen.getByRole('combobox', { name });
+      fireEvent.focus(input);
+      fireEvent.input(input, {
+        inputType: 'insertText',
+        target: { value: text },
+      });
+    }
+
+    it('submits selected and created items', async () => {
+      const handleSubmit = vi.fn();
+      render(<FruitForm onSubmit={handleSubmit} />);
+
+      type('Fruit', 'Ban');
+      fireEvent.click(await screen.findByRole('option', { name: 'Banana' }));
+
+      type('Tags', 'Kiwi');
+      fireEvent.click(
+        await screen.findByRole('option', { name: 'Create "Kiwi"' }),
+      );
+
+      fireEvent.click(screen.getByRole('button', { name: 'Submit' }));
+
+      await waitFor(() => {
+        expect(handleSubmit).toHaveBeenCalledWith(
+          {
+            fruit: FRUITS[1],
+            tags: [{ label: 'Kiwi', value: 'kiwi' }],
+          },
+          expect.anything(),
+        );
+      });
+    });
+
+    it('marks the input invalid from React Hook Form state', async () => {
+      render(<FruitForm fruitError="Pick a fruit." onSubmit={vi.fn()} />);
+
+      expect(await screen.findByText('Pick a fruit.')).toBeInTheDocument();
+      expect(screen.getByRole('combobox', { name: 'Fruit' })).toHaveAttribute(
+        'aria-invalid',
+        'true',
+      );
+    });
+  });
+});

package/src/components/form/Form.tsx

@@ -0,0 +1,50 @@
+'use client';
+
+import { Button } from '@/components/Button';
+
+import { FormCheckbox, type FormCheckboxProps } from './FormCheckbox';
+import { FormCombobox, type FormComboboxProps } from './FormCombobox';
+import { FormDescription, type FormDescriptionProps } from './FormDescription';
+import { FormError, type FormErrorProps } from './FormError';
+import { FormField, type FormFieldProps } from './FormField';
+import { FormInput, type FormInputProps } from './FormInput';
+import { FormInputGroup, type FormInputGroupProps } from './FormInputGroup';
+import { FormLabel, type FormLabelProps } from './FormLabel';
+import { FormRadioGroup, type FormRadioGroupProps } from './FormRadioGroup';
+import { type FormProps, FormRoot } from './FormRoot';
+import { FormSelect, type FormSelectProps } from './FormSelect';
+import { FormSwitch, type FormSwitchProps } from './FormSwitch';
+import { FormTextarea, type FormTextareaProps } from './FormTextarea';
+
+const Form = Object.assign(FormRoot, {
+  Button,
+  Checkbox: FormCheckbox,
+  Combobox: FormCombobox,
+  Description: FormDescription,
+  Error: FormError,
+  Field: FormField,
+  Input: FormInput,
+  InputGroup: FormInputGroup,
+  Label: FormLabel,
+  RadioGroup: FormRadioGroup,
+  Select: FormSelect,
+  Switch: FormSwitch,
+  Textarea: FormTextarea,
+});
+
+export { Form };
+export type {
+  FormCheckboxProps,
+  FormComboboxProps,
+  FormDescriptionProps,
+  FormErrorProps,
+  FormFieldProps,
+  FormInputGroupProps,
+  FormInputProps,
+  FormLabelProps,
+  FormProps,
+  FormRadioGroupProps,
+  FormSelectProps,
+  FormSwitchProps,
+  FormTextareaProps,
+};