@pickle-ui/react-native 1.0.0-beta.1 → 1.0.0-beta.3

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

@@ -0,0 +1,152 @@
+import type { Meta, StoryObj } from '@storybook/react-native-web-vite';
+
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useState } from 'react';
+import { useForm } from 'react-hook-form';
+import { z } from 'zod/v4';
+
+import { Story } from '../_internal/Story';
+import { Text } from '../Text';
+import { Form } from './Form';
+import { InputGroup } from './InputGroup';
+
+const meta = {
+  component: Form,
+  parameters: { layout: 'fullscreen' },
+  title: 'components/Form',
+} satisfies Meta<typeof Form>;
+
+export default meta;
+
+type StoryDefinition = StoryObj;
+
+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 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.'),
+  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.'),
+  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: '',
+      lastName: '',
+      notificationChannel: 'email',
+      password: '',
+      terms: false,
+      username: '',
+    },
+    resolver: zodResolver(signUpSchema),
+  });
+  const [submitted, setSubmitted] = useState<null | SignUpValues>(null);
+
+  return (
+    <Form className="max-w-md" form={form} onSubmit={setSubmitted}>
+      <Form.Field
+        description="We'll send a confirmation link to this address."
+        label="Email"
+        name="email"
+      >
+        <Form.Input
+          autoCapitalize="none"
+          autoComplete="email"
+          inputMode="email"
+        />
+      </Form.Field>
+
+      <Form.Field label="Username" name="username">
+        <Form.InputGroup>
+          <InputGroup.Addon>@</InputGroup.Addon>
+          <Form.Input autoCapitalize="none" autoComplete="username" />
+        </Form.InputGroup>
+      </Form.Field>
+
+      <Form.Field
+        description="At least 8 characters."
+        label="Password"
+        name="password"
+      >
+        <Form.Input autoComplete="new-password" secureTextEntry />
+      </Form.Field>
+
+      <Form.Field label="Full name">
+        <Form.InputGroup>
+          <Form.Input
+            accessibilityLabel="First name"
+            name="firstName"
+            placeholder="First"
+          />
+          <Form.Input
+            accessibilityLabel="Last name"
+            name="lastName"
+            placeholder="Last"
+          />
+        </Form.InputGroup>
+      </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
+        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>Create account</Form.Button>
+
+      {submitted ? (
+        <Text tone="muted">Account created for {submitted.email}.</Text>
+      ) : null}
+    </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,195 @@
+import {
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react-native';
+import { useEffect } from 'react';
+import { useForm } from 'react-hook-form';
+
+import { Form } from './Form';
+import { InputGroup } from './InputGroup';
+
+type TestFormValues = {
+  channel: string;
+  email: string;
+  message: string;
+  terms: boolean;
+  username: string;
+};
+
+const defaultValues: TestFormValues = {
+  channel: 'email',
+  email: '',
+  message: '',
+  terms: false,
+  username: '',
+};
+
+function TestForm({
+  fieldErrors,
+  onSubmit,
+}: {
+  fieldErrors?: Partial<Record<keyof TestFormValues, string>>;
+  onSubmit: (values: TestFormValues) => void;
+}) {
+  const form = useForm<TestFormValues>({ defaultValues });
+
+  useEffect(() => {
+    for (const [name, message] of Object.entries(fieldErrors ?? {}) as [
+      keyof TestFormValues,
+      string,
+    ][]) {
+      form.setError(name, { message, type: 'manual' });
+    }
+  }, [fieldErrors, form]);
+
+  return (
+    <Form form={form} onSubmit={onSubmit}>
+      <Form.Field
+        description="We'll send a confirmation link."
+        label="Email"
+        name="email"
+      >
+        <Form.Input autoComplete="email" />
+      </Form.Field>
+
+      <Form.Field label="Username" name="username">
+        <Form.InputGroup testID="username-group">
+          <InputGroup.Addon>@</InputGroup.Addon>
+          <Form.Input />
+        </Form.InputGroup>
+      </Form.Field>
+
+      <Form.Field label="Message" name="message">
+        <Form.Textarea />
+      </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="terms">
+        <Form.Checkbox label="Accept terms" />
+      </Form.Field>
+
+      <Form.Button>Submit</Form.Button>
+    </Form>
+  );
+}
+
+describe('Form', () => {
+  it('binds fields and submits React Hook Form values', async () => {
+    const handleSubmit = jest.fn();
+    await render(<TestForm onSubmit={handleSubmit} />);
+
+    await fireEvent.changeText(
+      screen.getByLabelText('Email'),
+      'ugo@example.com',
+    );
+    await fireEvent.changeText(screen.getByLabelText('Username'), 'ugo');
+    await fireEvent.changeText(screen.getByLabelText('Message'), 'Hello');
+    await fireEvent.press(
+      screen.getByRole('checkbox', { name: 'Accept terms' }),
+    );
+    await fireEvent.press(screen.getByRole('radio', { name: 'SMS' }));
+    await fireEvent.press(screen.getByRole('button', { name: 'Submit' }));
+
+    await waitFor(() => {
+      expect(handleSubmit).toHaveBeenCalledWith(
+        {
+          channel: 'sms',
+          email: 'ugo@example.com',
+          message: 'Hello',
+          terms: true,
+          username: 'ugo',
+        },
+        undefined,
+      );
+    });
+  });
+
+  it('submits from the return key, like Enter on the web', async () => {
+    const handleSubmit = jest.fn();
+    await render(<TestForm onSubmit={handleSubmit} />);
+
+    await fireEvent(screen.getByLabelText('Email'), 'submitEditing');
+
+    await waitFor(() => expect(handleSubmit).toHaveBeenCalledTimes(1));
+  });
+
+  it('shows the description until the field has an error', async () => {
+    await render(
+      <TestForm
+        fieldErrors={{ email: 'Enter a valid email address.' }}
+        onSubmit={jest.fn()}
+      />,
+    );
+
+    expect(
+      await screen.findByText('Enter a valid email address.'),
+    ).toBeOnTheScreen();
+    expect(screen.queryByText("We'll send a confirmation link.")).toBeNull();
+    expect(screen.getByLabelText('Email').parent).toHaveProp(
+      'className',
+      expect.stringContaining('border-destructive/36'),
+    );
+  });
+
+  it('frames an input group as invalid from the field', async () => {
+    await render(
+      <TestForm
+        fieldErrors={{ username: 'Pick another username.' }}
+        onSubmit={jest.fn()}
+      />,
+    );
+
+    expect(await screen.findByText('Pick another username.')).toBeOnTheScreen();
+    expect(screen.getByTestId('username-group')).toHaveProp(
+      'className',
+      expect.stringContaining('border-destructive/36'),
+    );
+  });
+
+  it('marks a checkbox invalid from React Hook Form state', async () => {
+    await render(
+      <TestForm
+        fieldErrors={{ terms: 'Accept the terms to continue.' }}
+        onSubmit={jest.fn()}
+      />,
+    );
+
+    expect(
+      await screen.findByText('Accept the terms to continue.'),
+    ).toBeOnTheScreen();
+  });
+
+  it('names the radio group by the field label', async () => {
+    await render(<TestForm onSubmit={jest.fn()} />);
+
+    expect(screen.getByLabelText('Notification channel')).toHaveProp(
+      'role',
+      'radiogroup',
+    );
+  });
+
+  it('throws when a binding has no field name', async () => {
+    jest.spyOn(console, 'error').mockImplementation(() => {});
+
+    function Unnamed() {
+      const form = useForm();
+      return (
+        <Form form={form}>
+          <Form.Input />
+        </Form>
+      );
+    }
+
+    await expect(render(<Unnamed />)).rejects.toThrow(
+      'Form.Input requires a name prop or a parent <Form.Field name="...">.',
+    );
+  });
+});

package/src/components/form/Form.tsx

@@ -0,0 +1,51 @@
+import { use } from 'react';
+
+import { Button, type ButtonProps } from '../Button';
+import { FormSubmitContext } from './Form.context';
+import { FormCheckbox, type FormCheckboxProps } from './FormCheckbox';
+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 { FormTextarea, type FormTextareaProps } from './FormTextarea';
+
+/**
+ * A `Button` that submits the form when pressed, like the web's submit
+ * button. Pass `onPress` to give it another action.
+ */
+function FormButton({ onPress, ...props }: ButtonProps) {
+  const submit = use(FormSubmitContext);
+
+  return <Button onPress={onPress ?? submit} {...props} />;
+}
+
+const Form = Object.assign(FormRoot, {
+  Button: FormButton,
+  Checkbox: FormCheckbox,
+  Description: FormDescription,
+  Error: FormError,
+  Field: FormField,
+  Input: FormInput,
+  InputGroup: FormInputGroup,
+  Label: FormLabel,
+  RadioGroup: FormRadioGroup,
+  Textarea: FormTextarea,
+});
+
+export { Form };
+export type {
+  FormCheckboxProps,
+  FormDescriptionProps,
+  FormErrorProps,
+  FormFieldProps,
+  FormInputGroupProps,
+  FormInputProps,
+  FormLabelProps,
+  FormProps,
+  FormRadioGroupProps,
+  FormTextareaProps,
+};

package/src/components/form/FormCheckbox.tsx

@@ -0,0 +1,42 @@
+import { useController } from 'react-hook-form';
+
+import { Checkbox, type CheckboxProps } from './Checkbox';
+import {
+  useFormControlProps,
+  useFormMethods,
+  useRequiredFieldName,
+} from './Form.context';
+
+export type FormCheckboxProps = Omit<CheckboxProps, 'checked' | 'invalid'> & {
+  name?: string;
+};
+
+/** A `Checkbox` bound to the field's boolean value. */
+export function FormCheckbox({
+  name: nameProp,
+  onCheckedChange,
+  ...props
+}: FormCheckboxProps) {
+  const name = useRequiredFieldName(nameProp, 'Form.Checkbox');
+  const { control } = useFormMethods();
+  const { field } = useController({
+    control,
+    defaultValue: props.defaultChecked ?? false,
+    name,
+  });
+  const { accessibilityLabel, invalid } = useFormControlProps();
+
+  return (
+    <Checkbox
+      // A `label` already names the checkbox.
+      accessibilityLabel={props.label ? undefined : accessibilityLabel}
+      {...props}
+      checked={Boolean(field.value)}
+      invalid={invalid}
+      onCheckedChange={(checked) => {
+        field.onChange(checked);
+        onCheckedChange?.(checked);
+      }}
+    />
+  );
+}

package/src/components/form/FormDescription.tsx

@@ -0,0 +1,14 @@
+import { Text } from 'react-native';
+
+import { cn } from '../../lib/cn';
+
+export type FormDescriptionProps = React.ComponentProps<typeof Text>;
+
+export function FormDescription({ className, ...props }: FormDescriptionProps) {
+  return (
+    <Text
+      className={cn('text-muted-foreground font-sans text-sm', className)}
+      {...props}
+    />
+  );
+}

package/src/components/form/FormError.tsx

@@ -0,0 +1,20 @@
+import { Text } from 'react-native';
+
+import { cn } from '../../lib/cn';
+
+export type FormErrorProps = React.ComponentProps<typeof Text>;
+
+/** Announced by screen readers when it appears, like the web's live error. */
+export function FormError({ className, ...props }: FormErrorProps) {
+  return (
+    <Text
+      accessibilityLiveRegion="polite"
+      className={cn(
+        'text-destructive font-sans text-sm font-medium',
+        className,
+      )}
+      role="alert"
+      {...props}
+    />
+  );
+}

package/src/components/form/FormField.tsx

@@ -0,0 +1,82 @@
+import { type ReactNode, useId, useMemo, useRef } from 'react';
+import { useFormState } from 'react-hook-form';
+import { View } from 'react-native';
+
+import { cn } from '../../lib/cn';
+import {
+  FormFieldContext,
+  getErrorMessage,
+  useFormMethods,
+} from './Form.context';
+import { FormDescription } from './FormDescription';
+import { FormError } from './FormError';
+import { FormLabel } from './FormLabel';
+
+export type FormFieldProps = Omit<
+  React.ComponentProps<typeof View>,
+  'children'
+> & {
+  children: ReactNode;
+  description?: ReactNode;
+  /** Replaces the error message React Hook Form holds for the field. */
+  error?: ReactNode;
+  /** Names the control and focuses it when pressed, like the web's `<label>`. */
+  label?: ReactNode;
+  name?: string;
+};
+
+/**
+ * A labelled field bound to `name`, like `Form.Field` in @pickle-ui/react:
+ * the label, the control, then the field's error or its description.
+ */
+export function FormField({
+  children,
+  className,
+  description,
+  error,
+  label,
+  name,
+  ...props
+}: FormFieldProps) {
+  const { control, getFieldState } = useFormMethods();
+  const formState = useFormState({
+    control,
+    disabled: !name,
+    exact: true,
+    name,
+  });
+  const fieldError = name ? getFieldState(name, formState).error : undefined;
+  const errorMessage = error ?? getErrorMessage(fieldError);
+  const labelId = useId();
+  const controlRef = useRef<null | { focus: () => void }>(null);
+  const context = useMemo(
+    () => ({
+      label,
+      labelId: label ? labelId : undefined,
+      name,
+      setControl: (target: null | { focus: () => void }) => {
+        controlRef.current = target;
+      },
+    }),
+    [label, labelId, name],
+  );
+
+  return (
+    <View className={cn('gap-2.5', className)} {...props}>
+      {label ? (
+        <FormLabel
+          nativeID={labelId}
+          onPress={() => controlRef.current?.focus()}
+        >
+          {label}
+        </FormLabel>
+      ) : null}
+      <FormFieldContext value={context}>{children}</FormFieldContext>
+      {errorMessage ? (
+        <FormError>{errorMessage}</FormError>
+      ) : description ? (
+        <FormDescription>{description}</FormDescription>
+      ) : null}
+    </View>
+  );
+}

package/src/components/form/FormInput.tsx

@@ -0,0 +1,70 @@
+import { use, useImperativeHandle, useRef } from 'react';
+import { useController } from 'react-hook-form';
+import { type TextInput } from 'react-native';
+
+import {
+  FormFieldContext,
+  FormInputGroupContext,
+  FormSubmitContext,
+  useFormControlProps,
+  useFormMethods,
+  useRequiredFieldName,
+} from './Form.context';
+import { Input, type InputProps } from './Input';
+import { InputGroup } from './InputGroup';
+
+export type FormInputProps = Omit<
+  InputProps,
+  'defaultValue' | 'invalid' | 'value'
+> & { name?: string };
+
+type TextInputInstance = React.ComponentRef<typeof TextInput>;
+
+/**
+ * An `Input` bound to the field's value. The return key submits the form,
+ * like Enter on the web, unless `onSubmitEditing` is set.
+ */
+export function FormInput({
+  name: nameProp,
+  onBlur,
+  onChangeText,
+  onSubmitEditing,
+  ref,
+  ...props
+}: FormInputProps) {
+  const name = useRequiredFieldName(nameProp, 'Form.Input');
+  const { control } = useFormMethods();
+  const { field } = useController({ control, name });
+  const controlProps = useFormControlProps();
+  const fieldContext = use(FormFieldContext);
+  const isInsideInputGroup = use(FormInputGroupContext);
+  const submit = use(FormSubmitContext);
+  const inputRef = useRef<null | TextInputInstance>(null);
+  useImperativeHandle(ref, () => inputRef.current as TextInputInstance);
+
+  const InputComponent = isInsideInputGroup ? InputGroup.Input : Input;
+
+  return (
+    <InputComponent
+      {...controlProps}
+      {...props}
+      onBlur={(event) => {
+        field.onBlur();
+        onBlur?.(event);
+      }}
+      onChangeText={(text) => {
+        field.onChange(text);
+        onChangeText?.(text);
+      }}
+      onSubmitEditing={onSubmitEditing ?? submit}
+      ref={(node: null | TextInputInstance) => {
+        inputRef.current = node;
+        // React Hook Form focuses the first invalid field after a submit,
+        // and the field's label focuses its input when pressed.
+        field.ref(node);
+        fieldContext?.setControl(node);
+      }}
+      value={field.value ?? ''}
+    />
+  );
+}

package/src/components/form/FormInputGroup.tsx

@@ -0,0 +1,30 @@
+import { Children, isValidElement } from 'react';
+
+import { FormInputGroupContext, useFormControlProps } from './Form.context';
+import { FormInput, type FormInputProps } from './FormInput';
+import { InputGroup } from './InputGroup';
+import { InputGroupStateContext } from './InputGroup.context';
+
+export type FormInputGroupProps = React.ComponentProps<typeof InputGroup>;
+
+/**
+ * An `InputGroup` whose `Form.Input` renders `InputGroup.Input`, framed as
+ * invalid while the field has an error.
+ */
+export function FormInputGroup({ children, ...props }: FormInputGroupProps) {
+  const { invalid } = useFormControlProps();
+  const disabled = Children.toArray(children).some(
+    (child) =>
+      isValidElement<FormInputProps>(child) &&
+      child.type === FormInput &&
+      Boolean(child.props.disabled),
+  );
+
+  return (
+    <FormInputGroupContext value>
+      <InputGroupStateContext value={{ disabled, invalid }}>
+        <InputGroup {...props}>{children}</InputGroup>
+      </InputGroupStateContext>
+    </FormInputGroupContext>
+  );
+}

package/src/components/form/FormLabel.tsx

@@ -0,0 +1,17 @@
+import { Text } from 'react-native';
+
+import { cn } from '../../lib/cn';
+
+export type FormLabelProps = React.ComponentProps<typeof Text>;
+
+export function FormLabel({ className, ...props }: FormLabelProps) {
+  return (
+    <Text
+      className={cn(
+        'text-foreground font-sans text-sm leading-none font-medium',
+        className,
+      )}
+      {...props}
+    />
+  );
+}