@atom-learning/components 2.32.3-beta.0 → 2.34.0

package/dist/docs/FieldWrapper.mdx

@@ -1,30 +0,0 @@
----
-title: Field Wrapper
-component: FieldWrapper,InlineFieldWrapper
-description: A utility component to help with composing consistent form fields
-category: Form primitives
----
-
-`FieldWrapper` renders a `Label` and (when applicable) a `InlineMessage`. Use it to wrap any type of input to create a consistent set of form fields.
-
-```tsx preview
-<FieldWrapper label="Example Field" fieldId="example">
-  <Input name="example" id="example" />
-</FieldWrapper>
-```
-
-`InlineFieldWrapper` does the same but renders the label inline with the input, for example:`Checkbox`es and `Radio`s.
-
-```tsx preview
-<InlineFieldWrapper label="Example Checkbox">
-  <Checkbox name="example2" id="example2" />
-</InlineFieldWrapper>
-```
-
-It can also be used alongside components like `Input`, `Select` or `Switch` when you may require some condensed inline fields. You can use the `direction` and `align` props to handle how the label is positioned relative to the component, in this case the label is placed on the right with `direction="reverse"` and it's aligned centrally with the switch.
-
-```tsx preview
-<InlineFieldWrapper direction="reverse" align="center" label="Toggle a field">
-  <Switch />
-</InlineFieldWrapper>
-```

package/dist/docs/FileInput.mdx

@@ -1,45 +0,0 @@
----
-title: File Input
-component: FileInput
-description: FileInput is the lowest-level input component for the file type
-category: Form primitives
----
-
-`FileInput` is a specialised input that allows file uploads.
-
-```jsx preview
-<FileInput>Upload</FileInput>
-```
-
-## Required props
-
-The required props `FileInput` needs are: `onSelect` and `children`.
-
-`onSelect` is a callback that accepts the file selection (as a `FileList`), when the user interacts with the file browser interface. The file selection can then be used by the parent, for example: to be passed in a `POST` API call to be saved.
-
-**Note:** The action of uploading the file to a backend is the parent's responsibility.
-
-`children` is used to add text to the visible button.
-
-## Multiple files
-
-The input can also accept multiple files at once, via the `multiple` prop.
-
-```jsx preview
-<FileInput onSelect={(fileSelection) => console.log(fileSelection)} multiple>
-  Upload
-</FileInput>
-```
-
-## Restricting the MIME type
-
-The `accept` prop makes the input filter out unwanted file types and prevent the user from selecting them.
-
-```jsx preview
-<FileInput
-  onSelect={(fileSelection) => console.log(fileSelection)}
-  accept="application/pdf"
->
-  Upload
-</FileInput>
-```

package/dist/docs/Flex.mdx

@@ -1,16 +0,0 @@
----
-title: Flex
-component: Flex
-description: The Flex component is a light abstraction over Box that sets its rendering context to flex
-category: Layout
----
-
-`Flex` shares the same API as `Box`, so you can access `as` and `css` to apply the correct semantic element and contextually relevant styles.
-
-```tsx preview
-<Flex css={{ justifyContent: 'space-between', width: '100%' }}>
-  <Box css={{ bg: '$primary', size: '$6' }} />
-  <Box css={{ bg: '$primary', size: '$6' }} />
-  <Box css={{ bg: '$primary', size: '$6' }} />
-</Flex>
-```

package/dist/docs/Form.mdx

@@ -1,411 +0,0 @@
----
-title: Form
-component: Form
-description: Form abstracts form validation logic away from the view code
-category: Form fields
-priority: 1
----
-
-## General
-
-`Form` is a wrapper around an HTML `form` element and the `react-hook-form` library. It manages the call to `useForm()`, renders a `<FormProvider>` and manages validation. When validation happens depends on the `validationMode` prop, which accepts `"onBlur" | "onSubmit"` and defaults to `"onBlur"`.
-
-`Form` is compatible with all our field components (i.e. `InputField`, not `Input`) and is also compatible with custom fields so long as they call `useFormContext()` and use:
-
-- `register` or `control` to register with the form per `react-hook-form`’s docs
-- `errors` to display any errors for the relevant field
-
-Custom field components should also accept a `validation` prop of type `ValidationOptions` and apply it to the field when present.
-
-Here’s an example using a simplified version of our `InputField`:
-
-```tsx
-const InputField = ({ label, name, validation }) => {
-  const { register, errors } = useFormContext()
-  const ref = validation ? register(validation) : register
-
-  const error = errors[name]?.message
-
-  return (
-    <FieldWrapper label={label} error={error} fieldId={name}>
-      <Input id={name} name={name} ref={ref} />
-    </FieldWrapper>
-  )
-}
-```
-
-## Form submission
-
-To handle form submission, `onSubmit` and optional `onError` callback props can be passed to Form. If there are any validation errors present `onError` will be called, in case of no errors the `onSubmit` will be called instead.
-
-## ValidationOptions
-
-The `ValidationOptions` type provides preset logic for common validation and processing patterns. You can also define your own custom logic.
-
-### Basic validation
-
-The `required` property accepts a `message` and a `value`. `value` is a boolean that represents whether the field is required. That pattern is only necessary when
-deciding dynamically whether to make a field required. If it will always be required, you can pass a `string` containing the error message instead. The following two inputs are equivalent:
-
-```tsx
-<Form>
-  <InputField
-    name="name"
-    label="Name"
-    validation={{
-      required: {
-        value: true,
-        message: 'You must have a name'
-      }
-    }}
-  />
-  <InputField
-    name="name"
-    label="Name"
-    validation={{
-      required: 'You must have a name'
-    }}
-  />
-  <Button>Submit</Button>
-</Form>
-```
-
-The following properties take a `message` and a `value`:
-
-- `min`
-- `max`
-- `minLength`
-- `maxLength`
-- `pattern`
-
-For example:
-
-```tsx
-<Form>
-  <InputField
-    type="number"
-    name="numCats"
-    label="Number of cats"
-    validation={{
-      min: {
-        value: 3,
-        message: 'You must have at least 3 cats!'
-      }
-    }}
-  />
-  <InputField
-    name="faveName"
-    label="Favourite cat name"
-    validation={{
-      maxLength: {
-        value: 20,
-        message: 'Cats hate long names!'
-      }
-    }}
-  />
-  <Button>Submit</Button>
-</Form>
-```
-
-Note that when specifying a `pattern`, the `value` is a `RegExp`. For the other basic properties listed here, `value` is a `number`.
-
-### Custom validation
-
-The `validate` property accepts a function of type `(value: any) => boolean | string`. Its single argument is the current value of the field. It should return `true` if the value passes validation and a `string` containing an error if not.
-
-```tsx
-<Form>
-  <InputField
-    name="faveVowel"
-    label="Favourite vowel"
-    validation={{
-      validate: (value) => {
-        return (
-          ['A', 'E', 'I', 'O', 'U'].contains(value) || 'That’s not a vowel!'
-        )
-      }
-    }}
-  />
-  <Button>Submit</Button>
-</Form>
-```
-
-### Basic processing
-
-The following properties accept boolean values:
-
-- `valueAsNumber`
-- `valueAsDate`
-
-These properties only apply to text inputs. If `true`, the value will be converted to the relevant type after validation.
-
-### Custom processing
-
-The `process` property accepts a function of type `(value: any) => any`. It can be used to process the value after validation.
-
-## Persisting form data
-
-`Form` is integrated with `react-hook-form-persist`'s package to save form data into session storage:
-
-- send `persist` prop to Form component to persist form data in sessionStorage
-- `persist` object has a required `id`, an optional `storage` prop and optional `include` or `exclude` arrays with reference to the input's names
-- `include` will only save the listed inputs to session storage and `exclude` will exclude the listed inputs
-- if both `include` and `exclude` are sent it will ignore `include` and use only `exclude`
-- if no `storage` prop is sent, it will default to use sessionStorage, however you can override this by sending `local` to use localStorage
-- persisted form data in sessionStorage or localStorage will populate form with `defaultValues` on refresh
-
-Here's an example using the `persist` prop:
-
-```tsx
-<Form persist={{ id: 'nameAndSecret', exclude: ['secret'], storage: 'local' }}>
-  <InputField
-    name="name"
-    label="Name"
-    validation={{ required: 'Name is required' }}
-  />
-  <InputField
-    name="secret"
-    label="Secret"
-    validation={{ required: 'Secret is required' }}
-  />
-  <Button type="submit">Submit</Button>
-</Form>
-```
-
-## Composing form field components
-
-It’s easy to compose your own custom form fields from the low-level components in this library (`Input`, `Label`, `InlineMessage` etc) but there are some requirements that your new
-field must meet in order to be fully compatible with our `Form`.
-
-### Props
-
-Your custom form field component must take the props specified in [General](#General)
-
-#### error
-
-`error` should be displayed in a `InlineMessage` when present. You don’t need to pass `error` to your component manually; the `Form` will pass it in automatically when appropriate.
-
-To properly retrieve the error in both static and dynamic fields it is necessary to use the `useFieldError` hook stored in the form directory, that accepts a field name parameter.
-
-#### validation
-
-`validation` allows users of your component to add custom validation rules to it as specified above
-
-#### register
-
-If you don’t need to add any default validation to your component, then pass `register?.(validation)` down to the `Input` (or `Select`, etc) component’s `ref` prop.
-If you do want to add default validation, pass something like this:
-
-```ts
-register?.({
-  maxLength: { value: 2, message: 'short data only!' },
-  ...validation
-})
-```
-
-(but check that validation is truthy first, or default it to an empty object!). Note that optional chaining is important here to protect from runtime errors if your field gets rendered outside of a `Form`.
-
-### Examples
-
-Here are two email input field examples. The first is a wrapper around an `InputField` and the second is manually composed from lower-level components. If wrapping `InputField` is an option then you should take it,
-but for more complex use cases you can use the manual composition here as a guide.
-
-```tsx
-const EmailField = ({ name, register, error, validation = {}, ...rest }) => (
-  <InputField
-    name={name}
-    css={{ mb: '$3' }}
-    autoComplete="email"
-    label="Email address"
-    type="email"
-    register={register}
-    validation={{
-      required: 'email address is required',
-      pattern: {
-        value: /.+@.+\..+/,
-        message: 'please enter a valid email address'
-      },
-      ...validation
-    }}
-    error={error}
-    {...rest}
-  />
-)
-```
-
-```tsx
-const EmailField = ({ css, name, validation, required, ...rest }) => {
-  const { errors, register } = useFormContext()
-
-  const ref = validation ? register(validation) : register
-  const error = errors[name]?.message
-
-  return (
-    <FieldWrapper css={css} label="Email address" fieldId={name}>
-      <Input
-        name={name}
-        id={name}
-        type="email"
-        autoComplete="email"
-        ref={register?.({
-          required: 'email address is required',
-          pattern: {
-            value: /.+@.+\..+/,
-            message: 'please enter a valid email address'
-          },
-          ...validation
-        })}
-        error={error}
-        {...rest}
-      />
-      {error && <InlineMessage css={{ mt: '$1' }}>{error}</InlineMessage>}
-    </FieldWrapper>
-  )
-}
-```
-
-## Accessing form data outside of fields
-
-The same object that `useFormContext` returns is available in an optional render prop function, making it easy to use the current form state to determine whether a button should be disabled or read the current value of a specific field. Note that if `render` is provided, `Form` should not be given any children. An error will be thrown if both are provided.
-
-```tsx
-<Form
-  onSubmit={console.log}
-  render={({ formState }) => (
-    <>
-      <InputField
-        label="Name"
-        name="name"
-        validation={{ required: 'This field is required!' }}
-      />
-      <Button type="submit" disabled={!formState.isValid}>
-        Submit
-      </Button>
-    </>
-  )}
-/>
-```
-
-To access field value, another render prop that can be used is `watch(fieldName: string)`. If there were no default values provided for the form, on the first render, the `watch` function will return undefined.
-
-```tsx
-<Form
-  onSubmit={console.log}
-  render={({ watch }) => {
-    const currentFieldValue = watch('name')
-
-    return (
-      <>
-        <InputField
-          label="Name"
-          name="name"
-          validation={{ required: 'This field is required!' }}
-        />
-        <Button type="submit" disabled={!formState.isValid}>
-          Submit
-        </Button>
-      </>
-    )
-  }}
-/>
-```
-
-You can also name your `render` function:
-
-```tsx
-const SomeFormContent = ({ formState }) => (
-  <>
-    <InputField
-      label="Name"
-      name="name"
-      validation={{ required: 'This field is required!' }}
-    />
-    <Button type="submit" disabled={!formState.isValid}>
-      Submit
-    </Button>
-  </>
-)
-
-const SomeForm = () => <Form onSubmit={console.log} render={SomeFormContent} />
-```
-
-## Dynamic fields - useFieldArray()
-
-[React-hook-form docs v6](https://react-hook-form.com/v6/api/#useFieldArray)
-
-To work with dynamically created fields `Form` exposes another render prop, `useFieldArray`. It exposes the following methods and objects:
-
-- `fields`: fields is an object keeping all the dynamic fields stored in the field array. Each entry in the field array can have multiple values (e.g { field: 'test', field2: true, field3: [ 'item1', 'item2' ] }, for example for input, checkbox and select)
-- `append` and `prepend` are used to insert dynamic fields at the start and end of the array
-- `remove` and `insert` add or remove items at specified index
-- `move` and `swap` are used to reposition items in the array
-
-There are a few rules that need to be followed to make the dynamic fields work correctly in the context of the form:
-
-- For the mapping to work correctly, instead of using the index from a `map()` or some other id, it is required to pass ids generated by the `useFieldArray` hook.
-- Each dynamic field needs to take a default value from the fields object
-- Each field name needs to be in a specific format `fieldArrayName[index].fieldName`, where index is the second arg of `map` function
-- To initialize the useFieldArray hook a control object either from `useFormContext` or a Form render prop needs to be used.
-
-```tsx
-const { fields } = useFieldArray({
-  control,
-  name: 'testArray'
-})
-
-//////
-
-{
-  fields.map((field, index) => (
-    <CheckboxField
-      defaultChecked={field.checkbox}
-      label="Label"
-      name={`testArray[${index}].field2`}
-      key={field.id}
-    />
-  ))
-}
-```
-
-Example:
-
-```tsx
-<Form
-  defaultValues={{
-    testArray: [
-      { field1: 'test', field2: true },
-      { field1: 'test2', field2: true }
-    ]
-  }}
-  render={({ control }) => {
-    const { fields, append, remove } = useFieldArray({
-      control,
-      name: 'testArray'
-    })
-
-    return (
-      <>
-        {fields.map((field, index) => (
-          <div key={field.id}>
-            <InputField
-              label="Input"
-              name={`testArray[${index}].field1`}
-              defaultValue={field.field1}
-            />
-            <CheckboxField
-              label="Checkbox"
-              name={`testArray[${index}].field2`}
-              defaultChecked={field.field2}
-            />
-          </div>
-        ))}
-
-        <button onClick={() => append({ field1: 'test', field2: false })}>
-          Add Item
-        </button>
-        <button onClick={() => remove(0)}>Remove first item</button>
-      </>
-    )
-  }}
-/>
-```

package/dist/docs/Grid.mdx

@@ -1,28 +0,0 @@
----
-title: Grid
-component: Grid
-description: The Grid component implements a simple CSS grid with auto-fit columns
-category: Layout
----
-
-The `gap` prop specifies the distance between items in the grid using the theme's `space` scale and the `minItemSize` prop specifies, in any valid CSS units, the minimum size of each grid item.
-
-**Note:** Passing percentage values into `minItemSize` will result in unintuitive behaviour. E.g. `minItemSize="50%"` will result in only one item per row because `50%` `width` + any `gap` between the items means the total width of the row will be `50%` + `50%` + `gap` which will wrap the second item onto the next line.
-
-```tsx preview
-<Grid minItemSize="10em" gap="3" css={{ width: '100%' }}>
-  {Array.from(Array(6)).map((_, i) => (
-    <Box key={i} css={{ bg: '$primary', height: '10em' }} />
-  ))}
-</Grid>
-```
-
-Should you need further control of the size of grid items, you can pass `maxItemSize`, which accepts the same value types as `minItemSize`. This is useful when you wish to control the width of items that may or may not fill the container width based on content, so they do not stretch to fill the width.
-
-```tsx
-<Grid minItemSize="10em" maxItemSize="10em" gap="3" css={{ width: '100%' }}>
-  {Array.from(Array(3)).map((_, i) => (
-    <Box key={i} css={{ bg: '$primary', height: '10em' }} />
-  ))}
-</Grid>
-```

package/dist/docs/Heading.mdx

@@ -1,30 +0,0 @@
----
-title: Heading
-component: Heading
-description: Use Heading to define a semantically relevant title to a component, section or page
-category: Content
----
-
-It should be used for all headings, whether it’s for a page, `section`, card, etc.
-
-`Heading`’s `as` prop defaults to `h2` but also accepts `h1`, `h3`, `h4`, `h5`, `h6`. Follow [semantic HTML guidelines](https://webaim.org/techniques/semanticstructure/) when deciding which element to use. Also note that the size of a heading is controlled separately to which element is used.
-
-## Sizes
-
-```tsx preview
-<Heading size="xs">The lowest level heading</Heading>
-```
-
-```tsx preview
-<Heading size="sm">
-  A heading for an individual block of content, e.g. a card
-</Heading>
-```
-
-```tsx preview
-<Heading>A subheading in a page. This is the default size.</Heading>
-```
-
-```tsx preview
-<Heading size="lg">A page heading.</Heading>
-```

package/dist/docs/Icon.mdx

@@ -1,30 +0,0 @@
----
-title: Icon
-component: Icon
-description: A standardised way to render icons, ensuring that only the icons you use are included in your output
-category: Content
----
-
-`Icon` is a light wrapper component that provides a standardised set of styles to the icon in use. It requires an SVG from our icon library to be passed into the `is` prop.
-
-```tsx preview
-<Stack gap="4">
-  <Icon is={BatteryMedium} />
-  <Icon is={Crossing} />
-  <Icon is={EyeCrossed} />
-  <Icon is={Paperclip} />
-  <Icon is={Sun} />
-  <Icon is={Wheelchair} />
-</Stack>
-```
-
-Ensure that you pair the imported icon (in this case `Brightness`) with the `Icon` component to render in a consistent and reliable way. Review the available icons on the [icon listing page](/theme/icons)
-
-```tsx
-import { Icon } from '@atom-learning/components'
-import { Brightness } from '@atom-learning/icons'
-
-const Component = () => (
-  <Icon is={Brightness} size="md" css={{ color: '$primary' }} />
-)
-```

package/dist/docs/Image.mdx

@@ -1,14 +0,0 @@
----
-title: Image
-component: Image
-category: Media
----
-
-The `Image` component renders an `img` element with basic styling to stop it from overflowing its parent element or expanding beyond its natural size and distorting.
-
-```tsx preview
-<Image
-  src="https://atomlearning.co.uk/images/key-img.png"
-  alt="An Atom Learning user riding a pencil rocket"
-/>
-```

package/dist/docs/InlineMessage.mdx

@@ -1,52 +0,0 @@
----
-title: Inline Message
-component: InlineMessage
-description: Inline feedback message with an optional icon
-category: Feedback
----
-
-Inline messages consist of an inline feedback message in the form of simple text that inform the user of relevant information, revealed in context.
-
-```tsx preview
-<InlineMessage>This is an Inline Message</InlineMessage>
-```
-
-## Theme
-
-These are the available `theme`s for this component: `success`, `warning`, `error`, `neutral` and `info`. The default is `error` (due to most frequent context).
-
-```tsx preview
-<>
-  <InlineMessage theme="error">This is an error Inline Message</InlineMessage>
-  <InlineMessage theme="warning">
-    This is a warning Inline Message
-  </InlineMessage>
-  <InlineMessage theme="success">
-    This is a success Inline Message
-  </InlineMessage>
-  <InlineMessage theme="info">This is an info Inline Message</InlineMessage>
-  <InlineMessage theme="neutral">
-    This is a neutral Inline Message
-  </InlineMessage>
-</>
-```
-
-## Size
-
-These are the available `size`s for this component: `xs`, `sm` and `md`. The default is `sm`
-
-```tsx preview
-<>
-  <InlineMessage size="xs">This is an xs Inline Message</InlineMessage>
-  <InlineMessage size="sm">This is a sm Inline Message</InlineMessage>
-  <InlineMessage size="md">This is a md Inline Message</InlineMessage>
-</>
-```
-
-## Icon
-
-Each theme has a specific icon it should export, so showing or hiding an icon is simply done using the `showIcon` prop. Default is `true`.
-
-```tsx preview
-<InlineMessage showIcon={false}>This is an Inline Message</InlineMessage>
-```

package/dist/docs/Input.mdx

@@ -1,24 +0,0 @@
----
-title: Input
-component: Input
-description: Input is the lowest-level input component for text and number types
-category: Form primitives
----
-
-Inputs should be accompanied by labels, so rather than using `Input` directly in a UI,
-it’s normally best to use a field component, which combines an `Input` with a `Label` and
-displays validation errors. If none of the existing field components suit your needs,
-it might be worth adding a new one.
-
-`Input` accepts a subset of the `types` that an HTML `input` element because we have more specialised
-components for the others (e.g. `Checkbox`, `Radio`).
-
-```tsx live
-<Input placeholder="Placeholder text" css={{ width: 300 }} />
-```
-
-## Accessibility
-
-While `Input` accepts `"number"` for its `type` prop, this does not render `<input type="number"/>`. Instead,
-it renders `<input type="text" inputmode="numeric" pattern=[0-9]*/>` to tell browsers to show a numeric keyboard
-while avoiding the [UX and accessibility problems associated with `type="number"`](https://technology.blog.gov.uk/2020/02/24/why-the-gov-uk-design-system-team-changed-the-input-type-for-numbers/).