@pickle-ui/react-native 1.0.0-beta.0 → 1.0.0-beta.2

package/src/components/form/Checkbox.tsx

@@ -0,0 +1,141 @@
+import { Pressable, Text, View } from 'react-native';
+
+import { cn } from '../../lib/cn';
+import { useControllableState } from '../_internal/useControllableState';
+
+// Same box sizes as `Checkbox` in @pickle-ui/react. `hitSlop` stretches the
+// box to a 44pt touch target, vertically only when a label already widens it.
+const boxClasses = { md: 'size-4.5', sm: 'size-3.5' } as const;
+const boxHitSlop = { md: 13, sm: 15 } as const;
+const fieldHitSlop = {
+  md: { bottom: 13, top: 13 },
+  sm: { bottom: 15, top: 15 },
+} as const;
+
+// The web draws Tabler's check and minus icons. Without SVG, the check is the
+// bottom and right borders of a rotated box, and the minus a bar.
+const checkClasses = {
+  md: 'h-[9px] w-[5px] border-b-[1.5px] border-r-[1.5px]',
+  sm: 'h-[7px] w-[4px] border-b-[1.25px] border-r-[1.25px]',
+} as const;
+const minusClasses = { md: 'h-[1.5px] w-2', sm: 'h-[1.25px] w-1.5' } as const;
+
+export type CheckboxProps = Omit<
+  React.ComponentProps<typeof Pressable>,
+  'children' | 'disabled'
+> & {
+  checked?: boolean;
+  /** Class overrides for the row around the box and label, the check and the label. */
+  classNames?: { field?: string; indicator?: string; label?: string };
+  defaultChecked?: boolean;
+  disabled?: boolean;
+  /** Shows a minus instead of the check, for a partly selected group. */
+  indeterminate?: boolean;
+  /** Marks the value as invalid, like the web's `aria-invalid`. */
+  invalid?: boolean;
+  /** Text next to the box; pressing it toggles the checkbox and names it. */
+  label?: React.ReactNode;
+  onCheckedChange?: (checked: boolean) => void;
+  size?: 'md' | 'sm';
+};
+
+/**
+ * A checkbox, like `Checkbox` in @pickle-ui/react. Give it a `label`, or an
+ * `accessibilityLabel` when visible text elsewhere names it.
+ */
+export function Checkbox({
+  accessibilityState,
+  checked: checkedProp,
+  className,
+  classNames,
+  defaultChecked = false,
+  disabled = false,
+  indeterminate = false,
+  invalid = false,
+  label,
+  onCheckedChange,
+  size = 'md',
+  ...props
+}: CheckboxProps) {
+  const [checked, setChecked] = useControllableState(
+    checkedProp,
+    defaultChecked,
+    onCheckedChange,
+  );
+  const filled = checked && !indeterminate;
+
+  const box = (
+    <View
+      className={cn(
+        'items-center justify-center rounded-[4px] border shadow-xs shadow-black/5',
+        boxClasses[size],
+        // A checked box is filled in both themes, so the dark input
+        // background must not apply to it.
+        filled
+          ? 'border-primary bg-primary'
+          : cn(
+              'border-input bg-background dark:bg-input/32',
+              invalid && 'border-destructive/36',
+            ),
+        (checked || indeterminate || invalid || disabled) && 'shadow-none',
+        disabled && 'opacity-64',
+        className,
+      )}
+    >
+      {indeterminate ? (
+        <View
+          className={cn(
+            'bg-foreground rounded-full',
+            minusClasses[size],
+            classNames?.indicator,
+          )}
+        />
+      ) : checked ? (
+        <View
+          className={cn(
+            'border-primary-foreground -mt-px rotate-45',
+            checkClasses[size],
+            classNames?.indicator,
+          )}
+        />
+      ) : null}
+    </View>
+  );
+
+  return (
+    // `role` and `aria-*` are React Native's current accessibility props;
+    // `accessibilityState` keeps any extra state the caller passes.
+    <Pressable
+      accessibilityState={{
+        ...accessibilityState,
+        checked: indeterminate ? 'mixed' : checked,
+        disabled,
+      }}
+      aria-checked={indeterminate ? 'mixed' : checked}
+      aria-disabled={disabled}
+      className={
+        label
+          ? cn('flex-row items-center gap-2', classNames?.field)
+          : 'self-start'
+      }
+      disabled={disabled}
+      hitSlop={label ? fieldHitSlop[size] : boxHitSlop[size]}
+      onPress={() => setChecked(!checked)}
+      role="checkbox"
+      {...props}
+    >
+      {box}
+      {label ? (
+        <Text
+          className={cn(
+            'text-foreground text-sm leading-none font-medium',
+            disabled && 'opacity-50',
+            classNames?.label,
+          )}
+        >
+          {label}
+        </Text>
+      ) : null}
+    </Pressable>
+  );
+}

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

@@ -0,0 +1,91 @@
+import { createContext, isValidElement, type ReactNode, use } from 'react';
+import {
+  useFormContext,
+  type UseFormReturn,
+  useFormState,
+} from 'react-hook-form';
+
+export type FormFieldContextValue = {
+  /** The field's label, used as its control's accessibility label when it is text. */
+  label?: ReactNode;
+  /** The `nativeID` of the field's label, for `aria-labelledby`. */
+  labelId?: string;
+  name?: string;
+  /** Registers the control the label focuses when pressed. */
+  setControl: (control: FocusTarget | null) => void;
+};
+
+type FocusTarget = { focus: () => void };
+
+export const FormFieldContext = createContext<FormFieldContextValue | null>(
+  null,
+);
+
+/** True inside `Form.InputGroup`, where `Form.Input` renders `InputGroup.Input`. */
+export const FormInputGroupContext = createContext(false);
+
+/** Submits the form, like pressing a submit button or Enter on the web. */
+export const FormSubmitContext = createContext<() => void>(() => {});
+
+export function getErrorMessage(error: unknown): ReactNode {
+  if (!error || typeof error !== 'object') return undefined;
+
+  const message = (error as { message?: unknown }).message;
+
+  return isValidElement(message) ||
+    typeof message === 'string' ||
+    typeof message === 'number'
+    ? message
+    : undefined;
+}
+
+/**
+ * React Hook Form tracks field state but has no DOM to label: this maps the
+ * current `Form.Field` onto its control, naming it by the field's label and
+ * marking it `invalid` while the field has an error.
+ */
+export function useFormControlProps() {
+  const field = use(FormFieldContext);
+  const { control, getFieldState } = useFormMethods();
+  const name = field?.name;
+  const formState = useFormState({
+    control,
+    disabled: !name,
+    exact: true,
+    name,
+  });
+
+  return {
+    accessibilityLabel:
+      typeof field?.label === 'string' ? field.label : undefined,
+    'aria-labelledby': field?.labelId,
+    invalid: name ? getFieldState(name, formState).invalid : false,
+  };
+}
+
+export function useFormMethods() {
+  const methods = useFormContext() as null | UseFormReturn;
+
+  if (!methods) {
+    throw new Error(
+      'Form components must be rendered inside <Form form={form}>.',
+    );
+  }
+
+  return methods;
+}
+
+export function useRequiredFieldName(
+  name: string | undefined,
+  componentName: string,
+) {
+  const fieldName = name ?? use(FormFieldContext)?.name;
+
+  if (!fieldName) {
+    throw new Error(
+      `${componentName} requires a name prop or a parent <Form.Field name="...">.`,
+    );
+  }
+
+  return fieldName;
+}

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 text-sm', className)}
+      {...props}
+    />
+  );
+}