feat(component): add phone input

packages/form/package.json

@@ -55,6 +55,7 @@
     "@ultraviolet/icons": "workspace:*",
     "@ultraviolet/themes": "workspace:*",
     "@ultraviolet/ui": "workspace:*",
+    "awesome-phonenumber": "7.8.0",
     "react-hook-form": "7.72.0"
   },
   "devDependencies": {

packages/form/src/components/PhoneInputField/__stories__/DefaultCountry.stories.tsx

@@ -0,0 +1,10 @@
+import { Template } from './Template.stories'
+
+export const WithDefaultCountry = Template.bind({})
+
+WithDefaultCountry.args = {
+  ...Template.args,
+  defaultCountry: 'US',
+  label: 'US Phone Number',
+  name: 'usPhone',
+}

packages/form/src/components/PhoneInputField/__stories__/Error.stories.tsx

@@ -0,0 +1,26 @@
+import { PhoneField } from '..'
+import { Form } from '../..'
+import { useForm } from '../../..'
+import { mockErrors } from '../../../mocks'
+
+import type { StoryFn } from '@storybook/react-vite'
+
+export const WithError: StoryFn<typeof PhoneField> = () => {
+  const methods = useForm({
+    defaultValues: {
+      phone: 'invalid',
+    },
+  })
+
+  return (
+    <Form errors={mockErrors} methods={methods} onSubmit={() => {}}>
+      <PhoneField
+        defaultCountry="FR"
+        label="Phone Number"
+        name="phone"
+        parseNumberErrorMessage="This doesn't appear to be a valid phone number."
+        required
+      />
+    </Form>
+  )
+}

packages/form/src/components/PhoneInputField/__stories__/Playground.stories.tsx

@@ -0,0 +1,9 @@
+import { Template } from './Template.stories'
+
+export const Playground = Template.bind({})
+
+Playground.args = {
+  label: 'Phone Number',
+  name: 'phone',
+  placeholder: 'Enter your phone number',
+}

packages/form/src/components/PhoneInputField/__stories__/Required.stories.tsx

@@ -0,0 +1,10 @@
+import { Template } from './Template.stories'
+
+export const Required = Template.bind({})
+
+Required.args = {
+  ...Template.args,
+  label: 'Phone Number',
+  name: 'phone',
+  required: true,
+}

packages/form/src/components/PhoneInputField/__stories__/Template.stories.tsx

@@ -0,0 +1,22 @@
+import { PhoneField } from '..'
+import { Form } from '../..'
+import { useForm } from '../../..'
+import { mockErrors } from '../../../mocks'
+
+import type { StoryFn } from '@storybook/react-vite'
+
+export const Template: StoryFn<typeof PhoneField> = ({ ...args }) => (
+  <Form errors={mockErrors} methods={useForm()} onSubmit={() => {}}>
+    <PhoneField
+      {...args}
+      parseNumberErrorMessage="This doesn't appear to be a valid phone number."
+    />
+  </Form>
+)
+
+Template.args = {
+  label: 'Phone Number',
+  name: 'phone',
+  placeholder: 'Enter your phone number',
+  defaultCountry: 'FR',
+}

packages/form/src/components/PhoneInputField/__stories__/index.stories.tsx

@@ -0,0 +1,76 @@
+import { Snippet, Stack, Text } from '@ultraviolet/ui'
+
+import { PhoneField } from '..'
+import { Form } from '../..'
+import { useForm } from '../../..'
+import { mockErrors } from '../../../mocks'
+
+import type { Meta } from '@storybook/react-vite'
+
+export default {
+  component: PhoneField,
+  decorators: [
+    ChildStory => {
+      const methods = useForm()
+      const {
+        errors,
+        isDirty,
+        isSubmitting,
+        touchedFields,
+        submitCount,
+        dirtyFields,
+        isValid,
+        isLoading,
+        isSubmitted,
+        isValidating,
+        isSubmitSuccessful,
+      } = methods.formState
+
+      return (
+        <Form errors={mockErrors} methods={methods} onSubmit={() => {}}>
+          <Stack gap={2}>
+            <ChildStory />
+            <Stack gap={1}>
+              <Text as="p" variant="bodyStrong">
+                Form input values:
+              </Text>
+              <Snippet initiallyExpanded prefix="lines">
+                {JSON.stringify(methods.watch(), null, 1)}
+              </Snippet>
+            </Stack>
+            <Stack gap={1}>
+              <Text as="p" variant="bodyStrong">
+                Form values:
+              </Text>
+              <Snippet prefix="lines">
+                {JSON.stringify(
+                  {
+                    errors,
+                    isDirty,
+                    isSubmitting,
+                    touchedFields,
+                    submitCount,
+                    dirtyFields,
+                    isValid,
+                    isLoading,
+                    isSubmitted,
+                    isValidating,
+                    isSubmitSuccessful,
+                  },
+                  null,
+                  1,
+                )}
+              </Snippet>
+            </Stack>
+          </Stack>
+        </Form>
+      )
+    },
+  ],
+  title: 'Form/Components/Fields/PhoneField',
+} as Meta<typeof PhoneField>
+
+export { Playground } from './Playground.stories'
+export { Required } from './Required.stories'
+export { WithDefaultCountry } from './DefaultCountry.stories'
+export { WithError } from './Error.stories'

packages/form/src/components/PhoneInputField/__tests__/index.test.tsx

@@ -0,0 +1,129 @@
+import { renderHook, screen, waitFor } from '@testing-library/react'
+import { userEvent } from '@testing-library/user-event'
+import { mockFormErrors, renderWithForm } from '@utils/test'
+import { useForm } from 'react-hook-form'
+import { describe, expect, test, vi } from 'vitest'
+
+import { PhoneField } from '..'
+import { Submit } from '../..'
+import { Form } from '../../Form'
+
+describe('form - PhoneField', () => {
+  test('should render correctly', () => {
+    const { asFragment } = renderWithForm(
+      <PhoneField
+        label="Phone Number"
+        name="phone"
+        parseNumberErrorMessage="Invalid phone number"
+      />,
+    )
+    expect(asFragment()).toMatchSnapshot()
+  })
+
+  test('should validate phone number', async () => {
+    const onSubmit = vi.fn()
+    const { result } = renderHook(() => useForm<{ phone: string }>())
+
+    renderWithForm(
+      <Form
+        errors={mockFormErrors}
+        methods={result.current}
+        onSubmit={onSubmit}
+      >
+        <PhoneField
+          label="Phone Number"
+          name="phone"
+          parseNumberErrorMessage="Invalid phone number"
+          required
+        />
+        <Submit>Submit</Submit>
+      </Form>,
+    )
+
+    await userEvent.click(screen.getByText('Submit'))
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledTimes(0)
+    })
+
+    const phoneInput = screen.getByRole('textbox')
+    await userEvent.type(phoneInput, '+33612345678')
+    await userEvent.click(screen.getByText('Submit'))
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledOnce()
+    })
+  })
+
+  test('should work with default country', async () => {
+    const onSubmit = vi.fn()
+    const { result } = renderHook(() => useForm<{ phone: string }>())
+
+    const { asFragment } = renderWithForm(
+      <Form
+        errors={mockFormErrors}
+        methods={result.current}
+        onSubmit={onSubmit}
+      >
+        <PhoneField
+          defaultCountry="US"
+          label="Phone Number"
+          name="phone"
+          parseNumberErrorMessage="Invalid phone number"
+        />
+        <Submit>Submit</Submit>
+      </Form>,
+    )
+
+    const phoneInput = screen.getByRole('textbox')
+    await userEvent.type(phoneInput, '+12025551234')
+    await userEvent.click(screen.getByText('Submit'))
+    await waitFor(() => {
+      expect(onSubmit.mock.calls[0][0]).toEqual({
+        phone: '+12025551234',
+      })
+    })
+    expect(asFragment()).toMatchSnapshot()
+  })
+
+  test('should show error for invalid phone number', async () => {
+    const onSubmit = vi.fn()
+    const { result } = renderHook(() => useForm<{ phone: string }>())
+
+    renderWithForm(
+      <Form
+        errors={mockFormErrors}
+        methods={result.current}
+        onSubmit={onSubmit}
+      >
+        <PhoneField
+          label="Phone Number"
+          name="phone"
+          parseNumberErrorMessage="This doesn't appear to be a valid phone number."
+          required
+        />
+        <Submit>Submit</Submit>
+      </Form>,
+    )
+
+    const phoneInput = screen.getByRole('textbox')
+    await userEvent.type(phoneInput, 'invalid')
+    await userEvent.click(screen.getByText('Submit'))
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledTimes(0)
+    })
+    expect(
+      screen.getByText("This doesn't appear to be a valid phone number."),
+    ).toBeDefined()
+  })
+
+  test('should be disabled when disabled prop is true', () => {
+    const { asFragment } = renderWithForm(
+      <PhoneField
+        disabled
+        label="Phone Number"
+        name="phone"
+        parseNumberErrorMessage="Invalid phone number"
+      />,
+    )
+    expect(asFragment()).toMatchSnapshot()
+  })
+})

packages/form/src/components/PhoneInputField/index.tsx

@@ -0,0 +1,99 @@
+'use client'
+
+import { PhoneInput } from '@ultraviolet/ui'
+import { parsePhoneNumber } from 'awesome-phonenumber'
+import { useController } from 'react-hook-form'
+
+import { useErrors } from '../../providers'
+
+import type { BaseFieldProps, FieldPath, FieldValues } from '@ultraviolet/form'
+import type { ComponentProps } from 'react'
+
+type PhoneInputValue = NonNullable<ComponentProps<typeof PhoneInput>['value']>
+
+type PhoneFieldProps<
+  TFieldValues extends FieldValues,
+  TName extends FieldPath<TFieldValues>,
+> = BaseFieldProps<TFieldValues, TName> &
+  ComponentProps<typeof PhoneInput> & {
+    /**
+     * message show to the user when the number is not a correct phone number
+     */
+    parseNumberErrorMessage: string
+  }
+
+export const PhoneField = <
+  TFieldValues extends FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+>({
+  className,
+  disabled,
+  id,
+  label,
+  name,
+  onBlur,
+  onChange,
+  onFocus,
+  required,
+  defaultCountry,
+  placeholder,
+  'data-testid': dataTestId,
+  parseNumberErrorMessage = "This doesn't appear to be a valid phone number.",
+  onParsingError,
+}: PhoneFieldProps<TFieldValues, TName>) => {
+  const { getError } = useErrors()
+  const {
+    field,
+    fieldState: { error: fieldError },
+  } = useController<TFieldValues>({
+    name,
+    rules: {
+      required,
+      validate: (phoneNumber: PhoneInputValue) => {
+        try {
+          return !!phoneNumber && !parsePhoneNumber(phoneNumber).valid
+            ? parseNumberErrorMessage
+            : undefined
+        } catch (error: unknown) {
+          if (error instanceof Error) {
+            onParsingError?.({
+              error,
+              inputValue: phoneNumber,
+            })
+          }
+
+          return phoneNumber
+        }
+      },
+    },
+  })
+
+  return (
+    <PhoneInput
+      className={className}
+      data-testid={dataTestId}
+      defaultCountry={defaultCountry}
+      disabled={disabled}
+      error={getError({ label: label ?? '' }, fieldError)}
+      id={id}
+      label={label}
+      name={field.name}
+      onBlur={event => {
+        field.onBlur()
+        onBlur?.(event)
+      }}
+      onChange={event => {
+        field.onChange(event)
+        onChange?.(event)
+      }}
+      onFocus={event => {
+        onFocus?.(event)
+      }}
+      onParsingError={onParsingError}
+      placeholder={placeholder}
+      ref={field.ref}
+      required={required}
+      value={field.value}
+    />
+  )
+}