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

package/src/components/form/FormError.tsx

@@ -0,0 +1,17 @@
+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 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 text-sm leading-none font-medium',
+        className,
+      )}
+      {...props}
+    />
+  );
+}

package/src/components/form/FormRadioGroup.tsx

@@ -0,0 +1,48 @@
+import { useController } from 'react-hook-form';
+
+import {
+  useFormControlProps,
+  useFormMethods,
+  useRequiredFieldName,
+} from './Form.context';
+import { RadioGroup, type RadioGroupProps } from './RadioGroup';
+
+export type FormRadioGroupProps = Omit<RadioGroupProps, 'value'> & {
+  name?: string;
+};
+
+/** A `RadioGroup` bound to the field's value. */
+function FormRadioGroupRoot({
+  name: nameProp,
+  onValueChange,
+  ...props
+}: FormRadioGroupProps) {
+  const name = useRequiredFieldName(nameProp, 'Form.RadioGroup');
+  const { control } = useFormMethods();
+  const { field } = useController({
+    control,
+    defaultValue: props.defaultValue,
+    name,
+  });
+  const { accessibilityLabel, 'aria-labelledby': labelledBy } =
+    useFormControlProps();
+
+  return (
+    <RadioGroup
+      accessibilityLabel={accessibilityLabel}
+      aria-labelledby={labelledBy}
+      {...props}
+      onValueChange={(value) => {
+        field.onChange(value);
+        onValueChange?.(value);
+      }}
+      value={field.value}
+    />
+  );
+}
+
+const FormRadioGroup = Object.assign(FormRadioGroupRoot, {
+  Item: RadioGroup.Item,
+});
+
+export { FormRadioGroup };

package/src/components/form/FormRoot.tsx

@@ -0,0 +1,41 @@
+import { useCallback } from 'react';
+import {
+  type FieldValues,
+  FormProvider,
+  type SubmitHandler,
+  type UseFormReturn,
+} from 'react-hook-form';
+import { View } from 'react-native';
+
+import { cn } from '../../lib/cn';
+import { FormSubmitContext } from './Form.context';
+
+export type FormProps<FormValues extends FieldValues = FieldValues> =
+  React.ComponentProps<typeof View> & {
+    form: UseFormReturn<FormValues>;
+    onSubmit?: SubmitHandler<FormValues>;
+  };
+
+/**
+ * React Native has no `<form>`, so the root shares a submit action:
+ * `Form.Button` and the return key in `Form.Input` call it, like a submit
+ * button and Enter on the web.
+ */
+export function FormRoot<FormValues extends FieldValues = FieldValues>({
+  className,
+  form,
+  onSubmit,
+  ...props
+}: FormProps<FormValues>) {
+  const submit = useCallback(() => {
+    if (onSubmit) void form.handleSubmit(onSubmit)();
+  }, [form, onSubmit]);
+
+  return (
+    <FormProvider {...form}>
+      <FormSubmitContext value={submit}>
+        <View className={cn('gap-6', className)} {...props} />
+      </FormSubmitContext>
+    </FormProvider>
+  );
+}

package/src/components/form/FormTextarea.tsx

@@ -0,0 +1,56 @@
+import { use, useImperativeHandle, useRef } from 'react';
+import { useController } from 'react-hook-form';
+import { type TextInput } from 'react-native';
+
+import {
+  FormFieldContext,
+  useFormControlProps,
+  useFormMethods,
+  useRequiredFieldName,
+} from './Form.context';
+import { Textarea, type TextareaProps } from './Textarea';
+
+export type FormTextareaProps = Omit<
+  TextareaProps,
+  'defaultValue' | 'invalid' | 'value'
+> & { name?: string };
+
+type TextInputInstance = React.ComponentRef<typeof TextInput>;
+
+/** A `Textarea` bound to the field's value. */
+export function FormTextarea({
+  name: nameProp,
+  onBlur,
+  onChangeText,
+  ref,
+  ...props
+}: FormTextareaProps) {
+  const name = useRequiredFieldName(nameProp, 'Form.Textarea');
+  const { control } = useFormMethods();
+  const { field } = useController({ control, name });
+  const controlProps = useFormControlProps();
+  const fieldContext = use(FormFieldContext);
+  const inputRef = useRef<null | TextInputInstance>(null);
+  useImperativeHandle(ref, () => inputRef.current as TextInputInstance);
+
+  return (
+    <Textarea
+      {...controlProps}
+      {...props}
+      onBlur={(event) => {
+        field.onBlur();
+        onBlur?.(event);
+      }}
+      onChangeText={(text) => {
+        field.onChange(text);
+        onChangeText?.(text);
+      }}
+      ref={(node: null | TextInputInstance) => {
+        inputRef.current = node;
+        field.ref(node);
+        fieldContext?.setControl(node);
+      }}
+      value={field.value ?? ''}
+    />
+  );
+}

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

@@ -0,0 +1,105 @@
+import type { Meta, StoryObj } from '@storybook/react-native-web-vite';
+
+import { type ComponentMatrixCellProps, Story } from '../_internal/Story';
+import { Button } from '../Button';
+import { XStack } from '../XStack';
+import { Input } from './Input';
+
+const meta = {
+  component: Input,
+  parameters: { layout: 'fullscreen' },
+  title: 'components/form/Input',
+} satisfies Meta<typeof Input>;
+
+export default meta;
+type StoryDefinition = StoryObj<typeof meta>;
+
+// No focus column: React Native can't force a focus state. Tap a field.
+const STATE_COLUMNS = [
+  { key: 'empty', label: 'Empty' },
+  { key: 'filled', label: 'Filled' },
+  { key: 'disabled', label: 'Disabled' },
+  { key: 'invalid', label: 'Invalid' },
+];
+
+const TYPE_ROWS = [
+  { description: 'General text input', key: 'text', label: 'Text' },
+  { description: 'Keyboard for email', key: 'email', label: 'Email' },
+  { description: 'Masked text entry', key: 'password', label: 'Password' },
+];
+
+function InputMatrixCell({ column, row }: ComponentMatrixCellProps) {
+  const isInvalid = column.key === 'invalid';
+
+  return (
+    <Input
+      accessibilityLabel={`${row.label} ${column.label}`}
+      defaultValue={
+        column.key === 'filled'
+          ? row.key === 'email'
+            ? 'hello@pickle.dev'
+            : 'Pickle UI'
+          : undefined
+      }
+      disabled={column.key === 'disabled'}
+      invalid={isInvalid}
+      keyboardType={row.key === 'email' ? 'email-address' : 'default'}
+      placeholder={isInvalid ? 'Check this value' : row.label}
+      secureTextEntry={row.key === 'password'}
+    />
+  );
+}
+
+const SIZE_COLUMNS = [
+  { key: 'sm', label: 'Small' },
+  { key: 'md', label: 'Medium' },
+  { key: 'lg', label: 'Large' },
+];
+
+function InputSizeCell({ column }: ComponentMatrixCellProps) {
+  const size = column.key as 'lg' | 'md' | 'sm';
+
+  return (
+    <XStack gap={2}>
+      <Input
+        accessibilityLabel={`${column.label} email`}
+        className="flex-1"
+        placeholder="Email"
+        size={size}
+      />
+      <Button size={size} variant="outline">
+        Subscribe
+      </Button>
+    </XStack>
+  );
+}
+
+export const All: StoryDefinition = {
+  render: () => (
+    <Story.Layout className="max-w-6xl" title="Input">
+      <Story.Section title="Types and states">
+        <Story.Matrix
+          Cell={InputMatrixCell}
+          cellClassName="items-stretch"
+          columns={STATE_COLUMNS}
+          rows={TYPE_ROWS}
+        />
+      </Story.Section>
+
+      <Story.Section title="Sizes">
+        <Story.Matrix
+          Cell={InputSizeCell}
+          cellClassName="items-stretch"
+          columns={SIZE_COLUMNS}
+          rows={[
+            {
+              description: 'Matches the Button of the same size',
+              key: 'with-button',
+              label: 'With button',
+            },
+          ]}
+        />
+      </Story.Section>
+    </Story.Layout>
+  ),
+};

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

@@ -0,0 +1,76 @@
+import { fireEvent, render, screen } from '@testing-library/react-native';
+
+import { Input } from './Input';
+
+describe('Input', () => {
+  it('renders a text field named by its accessibility label', async () => {
+    await render(<Input accessibilityLabel="Email" />);
+
+    expect(screen.getByLabelText('Email')).toBeOnTheScreen();
+  });
+
+  it.each([
+    ['sm', 'h-7'],
+    ['md', 'h-8'],
+    ['lg', 'h-9'],
+  ] as const)('matches the Button height at size %s', async (size, height) => {
+    await render(<Input accessibilityLabel="Email" size={size} />);
+
+    expect(screen.getByLabelText('Email').parent).toHaveProp(
+      'className',
+      expect.stringContaining(height),
+    );
+  });
+
+  it('styles the control with className and the field with classNames.input', async () => {
+    await render(
+      <Input
+        accessibilityLabel="Email"
+        className="control-x"
+        classNames={{ input: 'input-x' }}
+      />,
+    );
+
+    const field = screen.getByLabelText('Email');
+    expect(field).toHaveProp('className', expect.stringContaining('input-x'));
+    expect(field.parent).toHaveProp(
+      'className',
+      expect.stringContaining('control-x'),
+    );
+  });
+
+  it('stops editing when disabled', async () => {
+    await render(<Input accessibilityLabel="Email" disabled />);
+
+    expect(screen.getByLabelText('Email')).toHaveProp('editable', false);
+    expect(screen.getByLabelText('Email')).toBeDisabled();
+  });
+
+  it('shows a focus ring while focused and still calls onFocus', async () => {
+    const onFocus = jest.fn();
+    await render(<Input accessibilityLabel="Email" onFocus={onFocus} />);
+
+    const control = () => screen.getByLabelText('Email').parent;
+    expect(control()).not.toHaveProp(
+      'className',
+      expect.stringContaining('border-ring'),
+    );
+
+    await fireEvent(screen.getByLabelText('Email'), 'focus');
+
+    expect(onFocus).toHaveBeenCalledTimes(1);
+    expect(control()).toHaveProp(
+      'className',
+      expect.stringContaining('border-ring'),
+    );
+  });
+
+  it('renders the bare field when unstyled', async () => {
+    await render(<Input accessibilityLabel="Search" className="x" unstyled />);
+
+    expect(screen.getByLabelText('Search')).toHaveProp(
+      'className',
+      expect.stringMatching(/h-8.*x$/),
+    );
+  });
+});

package/src/components/form/Input.tsx

@@ -0,0 +1,81 @@
+import { useState } from 'react';
+import { TextInput } from 'react-native';
+
+import { cn } from '../../lib/cn';
+import { InputFrame } from '../_internal/InputFrame';
+
+// Same heights as `Button` for the same size, so they line up side by side,
+// and the web's paddings minus the 1pt border.
+const heightClasses = { lg: 'h-9', md: 'h-8', sm: 'h-7' } as const;
+const paddingClasses = {
+  lg: 'px-[13px]',
+  md: 'px-[11px]',
+  sm: 'px-[9px]',
+} as const;
+
+export type InputProps = React.ComponentProps<typeof TextInput> & {
+  /** Class overrides for the inner `TextInput`; `className` styles the control around it. */
+  classNames?: { input?: string };
+  /** Dims the field and stops editing, like the web's `disabled`. */
+  disabled?: boolean;
+  /** Marks the value as invalid, like the web's `aria-invalid`. */
+  invalid?: boolean;
+  size?: 'lg' | 'md' | 'sm';
+  /** Renders the bare `TextInput`, without the border and background. */
+  unstyled?: boolean;
+};
+
+/** A single-line text field, like `Input` in @pickle-ui/react. */
+export function Input({
+  className,
+  classNames,
+  disabled = false,
+  editable = true,
+  invalid = false,
+  onBlur,
+  onFocus,
+  size = 'md',
+  unstyled = false,
+  ...props
+}: InputProps) {
+  const [focused, setFocused] = useState(false);
+  // The web's 14px from `sm` up: the 16px it uses on phones only stops iOS
+  // Safari zooming into a focused field, which native apps don't do.
+  // `text-[14px]` sets the size without `text-sm`'s line height, which
+  // pushes a single-line field's text off center on iOS.
+  const input = (
+    <TextInput
+      accessibilityState={{ disabled }}
+      className={cn(
+        'text-foreground flex-1 text-[14px] outline-none',
+        paddingClasses[size],
+        unstyled ? cn(heightClasses[size], disabled && 'opacity-64') : 'h-full',
+        unstyled ? className : classNames?.input,
+      )}
+      editable={editable && !disabled}
+      onBlur={(event) => {
+        setFocused(false);
+        onBlur?.(event);
+      }}
+      onFocus={(event) => {
+        setFocused(true);
+        onFocus?.(event);
+      }}
+      placeholderTextColorClassName="accent-muted-foreground/72"
+      {...props}
+    />
+  );
+
+  if (unstyled) return input;
+
+  return (
+    <InputFrame
+      className={cn(heightClasses[size], className)}
+      disabled={disabled}
+      focused={focused}
+      invalid={invalid}
+    >
+      {input}
+    </InputFrame>
+  );
+}

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

@@ -0,0 +1,11 @@
+import { createContext } from 'react';
+
+/**
+ * Lets a wrapper mark the frame `disabled` or `invalid` when its input isn't
+ * a direct `InputGroup.Input` child, like `Form.InputGroup` does with
+ * `Form.Input`, whose invalid state comes from the form.
+ */
+export const InputGroupStateContext = createContext<null | {
+  disabled?: boolean;
+  invalid?: boolean;
+}>(null);