@atom-learning/components 1.3.1 → 1.6.0

package/dist/docs/Button.mdx

@@ -13,7 +13,7 @@ It adds default styling and the `css` prop. By default `primary` theme is displa
 
 ## Themes
 
-These are the available `themes` for the `Button` component: `primary` (default), `success`, `warning`, `danger`
+These are the available `themes` for the `Button` component: `primary` (default), `success`, `warning`, `danger`, and `neutral`.
 
 ```tsx preview
 <>
@@ -21,12 +21,13 @@ These are the available `themes` for the `Button` component: `primary` (default)
   <Button theme="success">Success</Button>
   <Button theme="warning">Warning</Button>
   <Button theme="danger">Danger</Button>
+  <Button theme="neutral">Danger</Button>
 </>
 ```
 
 ## Appearance
 
-There two options for the `appearance` property: `solid` and `outline`. These are the available `outline` variations for the `primary` theme.
+There two options for the `appearance` property: `solid` and `outline`. There are the available `outline` variations for the `primary` and `neutral` themes.
 
 ```tsx preview
 <Button appearance="outline">Primary</Button>

package/dist/docs/DateField.mdx

@@ -0,0 +1,20 @@
+---
+title: Date Field
+component: DateField
+description: DateField renders a field composed of an DateInput, a Label and a ValidationError
+category: Form fields
+---
+
+`DateField` is the preferred way to render a form field for dates.
+
+In addition to text `Label` (required) and a validation error (optional), `DateField` accepts all the same props as `DateInput` and will pass them on to the `DateInput` it renders. However, as with all our composed components,
+`DateField`’s `css` prop will be applied to a containing `Box`—the styling of the individual components inside `DateField` cannot be altered.
+
+Err on the side of using consistent form fields, but if you really need something with different styling then consider composing your own field from the
+`DateInput`, `Label` and `ValidationError` components.
+
+```tsx preview
+<Form>
+  <DateField name="exam-date" label="Exam date" initialDate={new Date()} />
+</Form>
+```

package/dist/docs/DateInput.mdx

@@ -0,0 +1,87 @@
+---
+title: Date Input
+component: DateInput
+description: A form component that provides a styled date selector without a label
+category: Form primitives
+---
+
+Date Inputs should be accompanied by labels, so rather than using `DateInput` directly in a UI,
+it’s normally best to the `DateField` component, which combines a `DateInput` with a `Label` and
+displays validation errors. Alternatively, use this `DateInput` component to compose other field components
+with more specific requirements.
+
+`DateInput` is composed from [Dayzed](https://github.com/deseretdigital/dayzed), so further reading on the API can be found there. Some options from Dayzed are set by default in order to provide a uniform experience. For example, the prop `showOutsideDays`, which shows days outside the current calendar month that would appear on the grid, defaults to true in order to avoid extra whitespace.
+
+```tsx preview
+<DateInput />
+```
+
+## Initial Date
+
+The `DateInput` component allows passing of an initial date, which will be selected by default. If you wish this to be the current date, you can use `new Date()` as per the preview below. Strings are also accepted and default to the `DD/MM/YYYY` format. It is recommended to use standard constructors for the date object as per MDN specifications.
+
+```tsx preview
+<DateInput initialDate={new Date()} />
+```
+
+## Date Format
+
+Any combination of date formats can be passed in as a string, such as `DD/MM/YY` or `YYYY/MM/DD`. The default is `DD/MM/YYYY`. A full list of possible formats can be found [here](https://day.js.org/docs/en/parse/string-format#list-of-all-available-parsing-tokens).
+
+```tsx
+<DateInput dateFormat="YYYY/MM/DD" />
+```
+
+## Dayzed customisation
+
+### First Day of Week
+
+The calendar that is rendered by this component can have its first day of the week customised for different locales. The default is 1 (Monday), but for locales such as the US, pass in `firstDayOfWeek={0}` to set it to Sunday.
+
+```tsx
+<DateInput firstDayOfWeek={0} />
+```
+
+## Translations
+
+The weekday and month names can be changed to anything you wish by passing in an array of strings to `weekdayNames` and `monthNames`.
+
+> NOTE: It is very important that you keep these labels in the right order. Weekdays must be `Sun -> Sat` and months must be `Jan -> Dec`.
+
+```tsx preview
+<DateInput
+  weekdayNames={['D', 'L', 'M', 'X', 'J', 'V', 'S']}
+  monthNames={[
+    'Enero',
+    'Febrero',
+    'Marzo',
+    'Abril',
+    'Mayo',
+    'Junio',
+    'Julio',
+    'Agosto',
+    'Septiembre',
+    'Octubre',
+    'Noviembre',
+    'Diciembre'
+  ]}
+/>
+```
+
+You can also translate the internal labels for accessibility purposes. The `labels` prop accepts an object containing three keys, `open`, `next`, and `previous`. These should all be strings.
+
+```tsx
+<DateInput
+  labels={{
+    open: 'Open label',
+    next: 'Next month label',
+    previous: 'Previous month label'
+  }}
+/>
+```
+
+If you need even finer control over what happens with the selected date, you can pass `onChange`, which takes a `Date` type as input.
+
+```tsx
+<DateInput onChange={(date) => doSomethingWith(date)} />
+```

package/dist/docs/Dialog.mdx

@@ -14,7 +14,7 @@ Read more about the underlying UI component on the [Radix UI documentation site]
 ```tsx preview
 <Dialog>
   <Dialog.Trigger asChild>
-    <Button>Click me</Button>
+    <Button>Open Dialog</Button>
   </Dialog.Trigger>
   <Dialog.Content>
     <Heading size="sm" css={{ mb: '$3' }}>
@@ -31,4 +31,19 @@ Read more about the underlying UI component on the [Radix UI documentation site]
 </Dialog>
 ```
 
+`Dialog` may be rendered without a close button. It's important to note that in case the default close button is hidden, one would need to provide an action button explicitly, to close the dialog.
+
+```tsx
+<Dialog>
+  <Dialog.Trigger>Open Dialog</Dialog.Trigger>
+  <Dialog.Content showCloseButton={false}>
+    <Text>
+      Dialog.Close is used below to retain the correct accessible roles and
+      related logic
+    </Text>
+    <Button as={Dialog.Close}>Close</Button>
+  </Dialog.Content>
+</Dialog>
+```
+
 For any modifications of the default `Dialog` visuals, for example bypassing the panel design entirely, we recommend utilising the Radix UI Dialog component directly. You will need to wrap each exported component within a `styled()` function to enable `css` and `as`, and compose together `Dialog.Overlay` and `Dialog.Close` within `Dialog.Content` to mimic the behaviour of this modal.

package/dist/docs/NotificationBadge.mdx

@@ -0,0 +1,33 @@
+---
+title: Notification Badge
+component: NotificationBadge
+description: A badge that wraps content and displays a notification
+category: Feedback
+---
+
+The NotificationBadge component is a lightweight wrapper for content such as ActionIcons, but can be wrapped around any block-level element.
+
+It displays a badge in top right of the content it is wrapping, which displays a `value` passed in as a prop. This could be, for example, the number of filters selected on a select filters badge.
+
+```tsx preview
+<NotificationBadge value={3}>
+  <ActionIcon appearance="outline" size="lg" isRounded>
+    <Icon is={Controls} />
+  </ActionIcon>
+</NotificationBadge>
+```
+
+## Value
+
+Whilst you would normally want to display a number, the `value` prop also supports strings. Here are some usage examples:
+
+```tsx preview
+<NotificationBadge value={88}>
+  <ActionIcon appearance="outline" size="lg">
+    <Icon is={Controls} />
+  </ActionIcon>
+</NotificationBadge>
+<NotificationBadge value="hi">
+  <Button theme="warning">I'm a button!</Button>
+</NotificationBadge>
+```

package/dist/docs/RadioButton.mdx

@@ -1,5 +1,5 @@
 ---
-title: Radio button
+title: Radio Button
 component: RadioButtonGroup,RadioButton
 description: The RadioButton component implements the Radio component from Radix with default styling and the css prop
 category: Form primitives

package/dist/docs/SearchInput.mdx

@@ -5,7 +5,8 @@ description: A search input with matching search icon
 category: Form primitives
 ---
 
-`SearchInput` wraps `Input` and adds an icon to visualise the specific input type, it's recommended to use this component when the user is performing a search query. It is functionally identical to the standard `Input` aside from a more specific "type" but makes it clear to the user what the action is and what potential feedback they might receive.
+`SearchInput` wraps `Input` and adds an icon to visualise the specific input type, it's recommended to use this component when the user is performing a search query.
+When the user types into the `SearchInput` the component renders a clear button that clears the typed value.
 
 ```tsx preview
 <SearchInput name="search" css={{ width: 320 }} placeholder="Search" />

package/dist/docs/Slider.mdx

@@ -0,0 +1,117 @@
+---
+title: Slider
+component: Slider, Slider.Value, Slider.Steps
+description: The slider component implements the Slider component from Radix, with default styling and the CSS prop.
+category: Form primitives
+---
+
+The `Slider` is a simple component that renders a form slider.
+
+The `Slider` component should be rendered with a label for accesibility reasons. Rather than using the `Slider` component directly, it is best to use the `SliderField` component, which provides a field label, a value label, and easily integrates with the `Form` component.
+
+Should you wish to create a more complex UI with `Field` components, you should use this base component.
+
+Please note: the `value` or `defaultValue` passed in should always be an array.
+
+```tsx preview
+<Slider defaultValue={[50]} css={{ width: '320px' }} />
+```
+
+## Multiple Values
+
+Should you wish to have more than one control on the slider, you can pass those values in the array.
+
+```tsx preview
+<Slider defaultValue={[25, 75]} css={{ width: '320px' }} />
+```
+
+## Slider.Steps
+
+A separate component exists to output an array of labels which appear at given value points along the slider. These are passed in to the `steps` property using an array objects that contain a label and a value.
+
+This is most commonly used within the `SliderField`, but is here in case you need to compose your own complex component.
+
+Note: it is likely better to create steps as a constant and pass in with `steps={steps}` or similar, but this preview code cannot see values outside of JSX.
+
+```tsx preview
+<Slider defaultValue={[50]} css={{ width: '320px' }}>
+  <Slider.Steps
+    min={0}
+    max={100}
+    steps={[
+      { value: 0, label: 'min' },
+      { value: 50, label: 'mid' },
+      { value: 100, label: 'max' }
+    ]}
+  />
+</Slider>
+```
+
+The component requires min and max values, these should be the same as the optional values that are passed to the Slider component.
+
+`Slider.Steps` work well with the built in `step` property, which defaults to 1 and changes the size of each movement. For example, this would limit the slider to three values only.
+
+```tsx
+<Slider defaultValue={[50]} min={10} max={20} step={5}>
+  <Slider.Steps
+    min={10}
+    max={20}
+    steps={[
+      { value: 10, label: 'min' },
+      { value: 15, label: 'mid' },
+      { value: 20, label: 'max' }
+    ]}
+  />
+</Slider>
+```
+
+## Slider.Value
+
+A separate component exists to output the value from a slider. This is most commonly used within the `SliderField`, but is here in case you need to compose your own complex component.
+
+```tsx preview
+<Slider defaultValue={[50]} css={{ width: '320px' }}>
+  {/**
+   * The Slider.Value value must be manually controlled using onValueChange
+   * from Slider. This is a visual example of how would render Slider.Value
+   * and will not update when changed.
+   */}
+  <Slider.Value value={[50]} />
+</Slider>
+```
+
+By default this simply outputs the value, however, this can be customised in a number of ways. The property `outputLabel` accepts a function that passes the value selected in the slider and expects a string returned for the label.
+
+You can also use this is in more complex ways, for example to set empty states and pluralisation, like below.
+
+```tsx
+<Slider defaultValue={[50]} css={{ width: '320px' }}>
+  <Slider.Value
+    value={[50]}
+    outputLabel={(value) =>
+      value === 0
+        ? 'You have no geese'
+        : `You have ${value} ${value === 1 ? 'goose' : 'geese'}`
+    }
+  />
+</Slider>
+```
+
+Should you wish to use the label with multiple values, you can use `Array.join()` like below.
+
+```tsx
+<Slider.Value
+  value={[25, 75]}
+  outputLabel={(value) => `You have between ${value.join(' and ')} geese`}
+/>
+```
+
+## Styling
+
+Depending on the background of your page, you can change the theme of the track to be either light or tonal using `theme="light"`. Default is `theme="tonal"`.
+
+```tsx preview
+<Box css={{ p: '$5', bg: '$tonal100' }}>
+  <Slider theme="light" defaultValue={[50]} css={{ width: '320px' }} />
+</Box>
+```

package/dist/docs/SliderField.mdx

@@ -0,0 +1,35 @@
+---
+title: Slider Field
+component: SliderField
+description: Combines a Slider with a label and form integration.
+category: Form fields
+---
+
+`SliderField` renders a `Slider` with a label, and easy implementation with `Form`. It also renders a `Slider.Value` label underneath the slider, and a `Slider.Steps` component should steps be passed in.
+
+In it's most simple form, a slider allows one value to be set between two given values (default 0 and 100).
+
+Please note: the `value` or `defaultValue` passed in should always be an array.
+
+```tsx preview
+<Form>
+  <SliderField name="slider" label="Select a value" defaultValue={[50]} />
+</Form>
+```
+
+With optional `Slider.Steps`:
+
+```tsx preview
+<Form>
+  <SliderField
+    name="slider"
+    label="Select a value (now with steps)"
+    defaultValue={[50]}
+    steps={[
+      { value: 0, label: 'min' },
+      { value: 50, label: 'mid' },
+      { value: 100, label: 'max' }
+    ]}
+  />
+</Form>
+```

package/dist/docs/Stepper.mdx

@@ -0,0 +1,45 @@
+---
+title: Stepper
+component: Stepper, Stepper.StepBack, Stepper.StepForward
+description: Stepper provides a bullet list of steps and forward/backwards navigation buttons.
+category: Navigation
+---
+
+`Stepper` exports multiple components that combine to create a stepped progress view.
+
+`Stepper.StepBack` represents the backwards navigation element. It can receive either a child text node or a `label` prop as a function that receives `activeStep` as an argument in order to possibly render different labels based on the current step the user is on. It is automatically disabled while the user is viewing the first step.
+
+`Stepper.StepForward` represents the forward navigation element. It can receive either a child text node or a `label` prop as a function that receives `activeStep` as an argument in order to possibly render different labels based on the current step the user is on.
+
+`Stepper.Steps` holds the actual bullet list.
+
+The root `Stepper` component must be passed `stepCount` as a number in order to display the desired number of bullet steps. It also takes `onStepChange` as a function that takes `activeStep` as an argument. This can be used to determine what content to display, based on the current step. It can also take `onComplete` as a function that gets called when the user clicks the `StepForward` button while on the last step.
+
+```tsx preview
+<Stepper stepCount={3}>
+  <Stepper.StepBack>Back</Stepper.StepBack>
+  <Stepper.Steps />
+  <Stepper.StepForward>Next</Stepper.StepForward>
+</Stepper>
+```
+
+The root `Stepper` component can also take an `allowSkip` prop that allows the user to navigate by clicking the actual bullets.
+
+Below is a more complex example that shows how to dynamically render the button labels, get the activeStep in order to potentially use it to determine what content to render based on the current position, and use an `onComplete` function to trigger custom behaviour when the user reaches the final step.
+
+```tsx preview
+<Stepper
+  stepCount={3}
+  allowSkip
+  onComplete={() => console.log('Finished')}
+  onStepChange={(activeStep) =>
+    console.log('Do something with the active step')
+  }
+>
+  <Stepper.StepBack label={(activeStep) => 'Back'} />
+  <Stepper.Steps />
+  <Stepper.StepForward
+    label={(activeStep) => (activeStep === 2 ? 'Finish' : 'Next')}
+  />
+</Stepper>
+```

package/dist/docs/Tabs.mdx

@@ -45,6 +45,8 @@ It also takes a `theme` prop that should either be "light" or "dark".
 The `Tabs.TriggerList` component simply holds the individual `Tabs.Trigger` components. It can also get custom styling via the `css` prop.
 `Tabs.TriggerList` will automatically show `<` & `>` buttons in case the content is overshooting the available space.
 
+The default scroll amount for the scroll buttons on the `Tabs.TriggerList` is 10% of the content width. You can set this to any percentage by setting, for example, `scrollPercentage={25}`.
+
 ## Tabs.Trigger
 
 The `Tabs.Trigger` component holds the content that will be displayed inside the button that the user would click in order to switch tabs. In can hold either a string, or some other component. It needs to be passed a `value` prop, that would be identical to the `value` prop passed to its corresponding `Tabs.Content` component.
@@ -70,6 +72,21 @@ A `Tabs.Trigger` component can take a `disabled` prop, which would make it unsel
 </Tabs>
 ```
 
+## Styling the `Tabs.TriggerList`
+
+The trigger list accepts an appearance property to apply uppercase to all tabs. Simply pass `appearance='uppercase'`.
+
+```tsx preview
+<Tabs>
+  <Tabs.TriggerList appearance="uppercase">
+    <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+    <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
+  </Tabs.TriggerList>
+  <Tabs.Content value="tab1">Content for tab 1</Tabs.Content>
+  <Tabs.Content value="tab2">Content for the second tab.</Tabs.Content>
+</Tabs>
+```
+
 ## Styling the `Tabs.Trigger`
 
 In order to style the different states of a trigger, the following CSS selectors need to be used when passed to the `css` prop: