@toptal/picasso-forms 6.0.4 → 6.0.5

package/src/Form/story/ValidateOnSubmit.example.tsx

@@ -0,0 +1,85 @@
+import React, { useCallback } from 'react'
+import { useField } from 'react-final-form'
+import { Container } from '@toptal/picasso'
+import { Form } from '@toptal/picasso-forms'
+
+type FormType = {
+  hide: boolean
+  name: {
+    first: string
+    last: string
+  }
+  dob: string
+}
+
+const FormContent = () => {
+  const {
+    input: { value: hide }
+  } = useField('hide')
+
+  return (
+    <>
+      <Form.Checkbox name='hide' label='Check to hide fields below' />
+
+      {!hide && (
+        <>
+          <Form.Input
+            enableReset
+            required
+            name='name.first'
+            label='Your first name'
+            placeholder='e.g. Bruce'
+          />
+          <Form.Input
+            enableReset
+            required
+            name='name.last'
+            label='Your last name'
+            placeholder='e.g. Wayne'
+          />
+          <Form.DatePicker required name='dob' label='DOB' />
+        </>
+      )}
+    </>
+  )
+}
+
+const Example = () => {
+  const handleSubmit = useCallback((values: FormType) => api.submit(values), [])
+
+  return (
+    <Form.ConfigProvider value={{ validateOnSubmit: true }}>
+      <Form<FormType>
+        onSubmit={handleSubmit}
+        successSubmitMessage='Success!'
+        failedSubmitMessage='Failure!'
+      >
+        <FormContent />
+
+        <Container top='small'>
+          <Form.SubmitButton>Submit</Form.SubmitButton>
+        </Container>
+      </Form>
+    </Form.ConfigProvider>
+  )
+}
+
+// the emulation of the api call
+const responseWithDelay = async (response: any) =>
+  new Promise(resolve => setTimeout(() => resolve(response), 2000))
+
+const api = {
+  submit: async (values: FormType) => {
+    if (values.hide || values.name?.first.toLowerCase() === 'bruce') {
+      return responseWithDelay(undefined)
+    }
+
+    return responseWithDelay({
+      name: {
+        first: 'Unknown first name'
+      }
+    })
+  }
+}
+
+export default Example

package/src/Form/story/index.jsx

@@ -0,0 +1,203 @@
+import Form from '../Form'
+import formFieldStory from '../../FieldWrapper/story'
+import PicassoBook from '~/.storybook/components/PicassoBook'
+
+const page = PicassoBook.section('Picasso Forms').createPage('Form', 'Form')
+
+page
+  .createTabChapter('Props')
+  .addComponentDocs({
+    component: Form,
+    name: 'Form',
+    additionalDocs: {
+      autoComplete: {
+        name: 'autoComplete',
+        type: {
+          name: 'string',
+          enums: ['on', 'off']
+        },
+        description: `HTML Form autocomplete attribute.\n
+The autocomplete attribute specifies whether a form should have autocomplete 'on' or 'off'.
+When autocomplete is 'on', the browser automatically complete values based on values that the user has entered before.\n
+Tip: It is possible to have autocomplete 'on' for the form, and 'off' for specific input fields, or vice versa.`
+      },
+      debug: {
+        name: 'debug',
+        type: {
+          name: 'function',
+          description:
+            '(state: FormState, fieldStates: { [string]: FieldState }) => void'
+        },
+        description:
+          'A callback for debugging that receives the form state and the states of all the fields'
+      },
+      decorators: {
+        name: 'decorators',
+        type: 'Decorator[]',
+        description: 'An array of decorators to apply to the form'
+      },
+      initialValues: {
+        name: 'initialValues',
+        type: 'FormValues | Object',
+        description: 'The initial values of the form'
+      },
+      initialValuesEqual: {
+        name: 'initialValuesEqual',
+        type: {
+          name: 'function',
+          description: '(Object | undefined, Object | undefined) => boolean'
+        },
+        description:
+          'A predicate to determine whether or not the initialValues prop has changed'
+      },
+      keepDirtyOnReinitialize: {
+        name: 'keepDirtyOnReinitialize',
+        type: 'boolean',
+        description:
+          'If true, only pristine values will be overwritten when initialize(newValues) is called'
+      },
+      mutators: {
+        name: 'mutators',
+        type: {
+          name: 'object',
+          description: '{ [string]: Mutator }'
+        },
+        description: 'Named mutator functions'
+      },
+      onSubmit: {
+        name: 'onSubmit',
+        type: {
+          name: 'function',
+          description:
+            '(values: FormValues, form: FormApi, callback: ?(errors: ?Object) => void) => ?Object | Promise<?Object> | void'
+        },
+        description: 'Function to call when the form is submitted',
+        required: true
+      },
+      subscription: {
+        name: 'subscription',
+        type: {
+          name: 'object',
+          description: '{ [string]: boolean }'
+        },
+        description:
+          'An object of the parts of FormState (final-form) to subscribe to'
+      },
+      validate: {
+        name: 'validate',
+        type: {
+          name: 'function',
+          description: '(values: FormValues) => Object | Promise<Object>'
+        },
+        description:
+          'A whole-record validation function that takes all the values of the form and returns any validation errors'
+      },
+      validateOnBlur: {
+        name: 'validateOnBlur',
+        type: 'boolean',
+        description:
+          'If true, validation will happen on blur. If false, validation will happen on change',
+        defaultValue: false
+      },
+      successSubmitMessage: {
+        name: 'successSubmitMessage',
+        type: 'ReactNode',
+        description:
+          'Message to display in a tooltip when form submitted successfully'
+      },
+      failedSubmitMessage: {
+        name: 'failedSubmitMessage',
+        type: 'ReactNode',
+        description:
+          'Message to display in a tooltip when form submission failed'
+      },
+      scrollOffsetTop: {
+        name: 'scrollOffsetTop',
+        type: 'number',
+        description:
+          'Offset from the viewport for inputs to focus on, defaults to the center of the window (deprecated, will not have any effect)'
+      }
+    }
+  })
+  .addComponentDocs(formFieldStory.componentDocs)
+
+page
+  .createChapter()
+  .addTextSection(
+    `
+Form is a wrapper for 'react-final-form' Form component. It also
+provides inside all the necessary input components types.
+    `
+  )
+  .addExample(
+    'Form/story/Default.example.tsx',
+    {
+      title: 'Default',
+      description: `
+A general look of the form includes the examples of all the input
+types supported by picasso-forms.
+`
+    },
+    'picasso-form'
+  )
+  .addExample(
+    'Form/story/CustomValidator.example.tsx',
+    {
+      title: 'Custom validator',
+      description: `
+We have a 'required' validator included by default to each input type,
+however, you may need custom validators for more complex types of fields.
+`
+    },
+    'picasso-form'
+  ) // picasso-skip-visuals
+  .addExample(
+    'Form/story/ParseInput.example.tsx',
+    {
+      title: 'Change form input value',
+      description: `
+      When you use picasso-forms your form input components are no longer
+      completely controlled and they are controlled by final-form, which
+      gives you the opportunity to rely on it with displaying errors,
+      validations, etc.
+      
+      However, sometimes you may need to be able to modify the form input
+      value.
+      `
+    },
+    'picasso-form'
+  ) // picasso-skip-visuals
+  .addExample(
+    'Form/story/BackendCommunication.example.tsx',
+    {
+      title: 'Backend communication',
+      description: `
+        The form usually need to send data to backend, so we need to have
+        backend communication and display the process of submission and
+        the results. The form-level results are represented by notifications.
+        `
+    },
+    'picasso-form'
+  ) // picasso-skip-visuals
+  .addExample(
+    'Form/story/CustomFormLevelConfiguration.example.tsx',
+    'Form Level Configurations'
+  )
+  .addExample(
+    'Form/story/ValidateOnSubmit.example.tsx',
+    {
+      title: 'Validate only on submit',
+      description: `
+            All fields should not show any validation error messages until submission is made.
+            `
+    },
+    'picasso-form'
+  ) // picasso-skip-visuals
+  .addExample('Form/story/FileInput.example.tsx', {
+    title: 'File input on a Form',
+    description: 'Showcase how to upload files on the form submission'
+  }) // picasso-skip-visuals
+  .addExample('Form/story/TitleCase.example.tsx', {
+    title: 'Title case',
+    description: "Display the field's label in title case."
+  }) // picasso-skip-visuals

package/src/Form/test.tsx

@@ -0,0 +1,27 @@
+import React from 'react'
+import { render } from '@toptal/picasso/test-utils'
+import { OmitInternalProps } from '@toptal/picasso-shared'
+import { Button } from '@toptal/picasso'
+
+import Form, { Props } from './Form'
+
+const renderForm = (props: OmitInternalProps<Props>) => {
+  const { onSubmit } = props
+
+  return render(
+    <Form onSubmit={onSubmit}>
+      <Form.Input name='test' placeholder='test input' />
+      <Button type='submit'>Submit</Button>
+    </Form>
+  )
+}
+
+describe('Form', () => {
+  it('renders', () => {
+    const { container } = renderForm({
+      onSubmit: () => {}
+    })
+
+    expect(container).toMatchSnapshot()
+  })
+})

package/src/FormConfig/FormConfig.ts

@@ -0,0 +1,12 @@
+import { createContext, useContext } from 'react'
+
+export type RequiredVariant = 'default' | 'asterisk'
+
+export interface FormConfigProps {
+  validateOnSubmit?: boolean
+  requiredVariant?: RequiredVariant
+}
+
+export const FormConfigContext = createContext<FormConfigProps>({})
+
+export const useFormConfig = () => useContext(FormConfigContext)

package/src/FormConfig/index.ts

@@ -0,0 +1 @@
+export * from './FormConfig'

package/src/FormConfig/test.tsx

@@ -0,0 +1,44 @@
+import React from 'react'
+import { screen, render, fireEvent } from '@toptal/picasso/test-utils'
+
+import Form from '../Form'
+import { FormConfigProps } from './FormConfig'
+
+const TEXT_INPUT_LABEL = 'Test text field'
+
+const renderForm = (configProps: FormConfigProps) => {
+  return render(
+    <Form.ConfigProvider value={configProps}>
+      <Form onSubmit={() => {}}>
+        <Form.Input label={TEXT_INPUT_LABEL} required name='test' />
+        <Form.SubmitButton>Submit</Form.SubmitButton>
+      </Form>
+    </Form.ConfigProvider>
+  )
+}
+
+describe('Form.ConfigProvider', () => {
+  it('validate only on submit', async () => {
+    renderForm({ validateOnSubmit: true })
+
+    fireEvent.blur(screen.getByLabelText(TEXT_INPUT_LABEL))
+
+    expect(
+      screen.queryByText('Please complete this field.')
+    ).not.toBeInTheDocument()
+
+    fireEvent.click(screen.getByRole('button', { name: 'Submit' }))
+
+    expect(
+      await screen.findByText('Please complete this field.')
+    ).toBeInTheDocument()
+  })
+
+  it('validate normally on blur / change', async () => {
+    renderForm({ validateOnSubmit: false })
+
+    fireEvent.blur(screen.getByLabelText(TEXT_INPUT_LABEL))
+
+    expect(screen.getByText('Please complete this field.')).toBeInTheDocument()
+  })
+})

package/src/Input/Input.tsx

@@ -0,0 +1,27 @@
+import React from 'react'
+import { Input as PicassoInput, InputProps } from '@toptal/picasso'
+
+import FieldWrapper, { FieldProps } from '../FieldWrapper'
+import getInputName from './utils/get-input-name'
+
+export type FormInputProps = Omit<InputProps, 'onResetClick'> & {
+  /** Callback invoked when reset button was clicked */
+  onResetClick?: (set: (value: string) => void) => void
+}
+export type Props = FormInputProps & FieldProps<InputProps['value']>
+
+export const Input = React.forwardRef<HTMLInputElement, Props>((props, ref) => (
+  <FieldWrapper<FormInputProps> {...props}>
+    {({ name, ...inputProps }: InputProps) => (
+      // TODO: remove getInputName completely when Chrome fixes autocomplete issue
+      // Link to the issue: https://bugs.chromium.org/p/chromium/issues/detail?id=1255609
+      <PicassoInput name={getInputName(name)} {...inputProps} ref={ref} />
+    )}
+  </FieldWrapper>
+))
+
+Input.defaultProps = {}
+
+Input.displayName = 'Input'
+
+export default Input

package/src/Input/index.ts

@@ -0,0 +1 @@
+export { default } from './Input'

package/src/Input/test.tsx

@@ -0,0 +1,34 @@
+import React from 'react'
+import { render, fireEvent } from '@toptal/picasso/test-utils'
+import { Button } from '@toptal/picasso'
+
+import Form, { Props as FormProps } from '../Form/Form'
+import { Props as InputProps } from './Input'
+
+type TestFormProps = Pick<FormProps, 'onSubmit'> & Pick<InputProps, 'onFocus'>
+
+const renderForm = (props: TestFormProps) => {
+  const { onFocus, onSubmit } = props
+
+  return render(
+    <Form onSubmit={onSubmit}>
+      <Form.Input onFocus={onFocus} name='test' placeholder='test input' />
+      <Button type='submit'>Submit</Button>
+    </Form>
+  )
+}
+
+describe('Input', () => {
+  it('fires the onFocus callback after focusing the input', () => {
+    const handleFocus = jest.fn()
+
+    const { getByPlaceholderText } = renderForm({
+      onSubmit: () => {},
+      onFocus: handleFocus
+    })
+
+    fireEvent.focus(getByPlaceholderText('test input'))
+
+    expect(handleFocus).toHaveBeenCalled()
+  })
+})

package/src/Input/utils/get-input-name.test.ts

@@ -0,0 +1,16 @@
+import getInputName from './get-input-name'
+
+describe('#getInputName', () => {
+  it.each(['title', 'field', 'input'] as const)(
+    'adds postfix to "%s"',
+    name => {
+      expect(getInputName(name)).toBe(`${name}-picasso`)
+    }
+  )
+
+  it('returns all other names', () => {
+    expect(getInputName('name')).toBe('name')
+    expect(getInputName('email')).toBe('email')
+    expect(getInputName(undefined)).toBeUndefined()
+  })
+})

package/src/Input/utils/get-input-name.ts

@@ -0,0 +1,11 @@
+const NAMES_NEED_POSTFIX = ['field', 'input', 'title']
+
+const getInputName = (name?: string) => {
+  if (name && NAMES_NEED_POSTFIX.includes(name)) {
+    return `${name}-picasso`
+  }
+
+  return name
+}
+
+export default getInputName

package/src/NumberInput/NumberInput.tsx

@@ -0,0 +1,45 @@
+import React from 'react'
+import {
+  NumberInput as PicassoNumberInput,
+  NumberInputProps
+} from '@toptal/picasso'
+import { FieldValidator } from 'final-form'
+
+import { validators } from '../utils'
+import FieldWrapper, { FieldProps } from '../FieldWrapper'
+
+export type Props = NumberInputProps & FieldProps<NumberInputProps['value']>
+
+const MIN = -2147483648
+const MAX = 2147483647
+
+const { composeValidators } = validators
+
+export const NumberInput = (props: Props) => {
+  const { min = MIN, max = MAX, validate } = props
+  const validateNumberLimits: FieldValidator<NumberInputProps['value']> = value => {
+    if (Number(value) > max) {
+      return `Must be less than or equal to ${max}.`
+    }
+    if (Number(value) < min) {
+      return `Must be greater than or equal to ${min}.`
+    }
+  }
+
+  return (
+    <FieldWrapper<NumberInputProps>
+      {...props}
+      validate={composeValidators([validateNumberLimits, validate])}
+    >
+      {(inputProps: NumberInputProps) => {
+        return <PicassoNumberInput {...inputProps} />
+      }}
+    </FieldWrapper>
+  )
+}
+
+NumberInput.defaultProps = {}
+
+NumberInput.displayName = 'NumberInput'
+
+export default NumberInput

package/src/NumberInput/index.ts

@@ -0,0 +1 @@
+export { default } from './NumberInput'

package/src/Radio/Radio.tsx

@@ -0,0 +1,24 @@
+import React, { useContext } from 'react'
+import { Radio as PicassoRadio, RadioProps } from '@toptal/picasso'
+import { Field } from 'react-final-form'
+
+import { RadioGroupContext } from '../RadioGroup'
+
+// Intersection with the type { name?: string } is needed here because of
+// TS compiler issue https://github.com/microsoft/TypeScript/issues/34793
+export type Props = RadioProps & {
+  name?: string
+}
+
+const Radio = ({ name, ...rest }: Props) => {
+  const groupName = useContext(RadioGroupContext)
+
+  return (
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    <Field name={name || groupName!} type='radio' value={rest.value}>
+      {({ input }) => <PicassoRadio checked={input.checked} {...rest} />}
+    </Field>
+  )
+}
+
+export default Radio