@atom-learning/components 1.2.3 → 1.5.0

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,81 @@
+---
+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'
+  }}
+/>
+```

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/Table.mdx

@@ -122,3 +122,17 @@ The `Table` component has 2 size variants that control the row height. The two a
   </Table.Body>
 </Table>
 ```
+
+The `Table` component by default renders with a slight border radius. If you want to remove this, for example if you are rendering the `Table` inside another component that has border radius, you can remove this by setting `corners="square"`. The default is `corners="round"`.
+
+```tsx
+<Table corners="square">...</Table>
+```
+
+`Table.Header` accepts a theme prop, the current available options are `primary` and `primaryDark`. The default is `primaryDark`.
+
+```tsx
+<Table>
+  <Table.Header theme="primary">...</Table.Header>
+</Table>
+```

package/dist/docs/Tabs.mdx

@@ -27,15 +27,23 @@ The component provides a set of default styles, which can be overwritten by usin
 </Tabs>
 ```
 
-It also takes a `defaultValue` prop that should match one of the triggers' `value` prop.
+It takes a `defaultValue` prop that should match one of the triggers' `value` prop.
 
 ```tsx
 <Tabs defaultValue="tab1">
 ```
 
+It also takes a `theme` prop that should either be "light" or "dark".
+
+```tsx
+<Tabs theme="light"></Tabs>
+<Tabs theme="dark"></Tabs>
+```
+
 ## Tabs.TriggerList
 
 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.
 
 ## Tabs.Trigger
 
@@ -62,6 +70,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: