@atom-learning/components 2.29.0-beta.2 → 2.29.0-beta.3

package/dist/docs/RadioCard.mdx

@@ -0,0 +1,62 @@
+---
+title: Radio Card
+component: RadioCardGroup,RadioCard
+description: A Radio Button that enables extra emphasis and descriptive capability
+category: Form primitives
+---
+
+A set of `RadioCard`s should be wrapped with a `RadioCardGroup` component to provide the correct HTML structure for our radio buttons. Any text within the card will be used as the label for the radio button, so ensure that you test this content and use `aria-hidden` to remove any unnecessary content from the announced text.
+
+```tsx preview
+<RadioCardGroup>
+  <RadioCard value="1">
+    <Text css={{ mb: '$2' }}>This is a radio card option</Text>
+    <Text size="sm" css={{ color: '$tonal300' }}>
+      With some additional text
+    </Text>
+  </RadioCard>
+  <RadioCard value="2">
+    <Text css={{ mb: '$2' }}>This is another radio card option</Text>
+    <Text size="sm" css={{ color: '$tonal300' }}>
+      With some additional text
+    </Text>
+  </RadioCard>
+  <RadioCard value="3">
+    <Text css={{ mb: '$2' }}>And a further radio card option</Text>
+    <Text size="sm" css={{ color: '$tonal300' }}>
+      With some additional text
+    </Text>
+  </RadioCard>
+</RadioCardGroup>
+```
+
+You can pass props to `RadioCardGroup` to control the styling of every `RadioCard` within. Change the radio button alignment within the card, toggle between two sizes, and render each card at full width.
+
+```tsx preview
+<RadioCardGroup align="right" size="lg" isFullWidth defaultValue="1">
+  <RadioCard value="1">
+    <Flex css={{ flexDirection: 'row', alignContent: 'center' }}>
+      <Text css={{ mr: '$4' }} size="sm">
+        £99
+      </Text>
+      <Heading size="xs">This is a radio card option</Heading>
+    </Flex>
+  </RadioCard>
+  <RadioCard value="2">
+    <Flex css={{ flexDirection: 'row', alignContent: 'center' }}>
+      <Text css={{ mr: '$4' }} size="sm">
+        £109
+      </Text>
+      <Heading size="xs">This is another radio card option</Heading>
+    </Flex>
+  </RadioCard>
+  <RadioCard value="3">
+    <Flex css={{ flexDirection: 'row', alignContent: 'center' }}>
+      <Text css={{ mr: '$4' }} size="sm">
+        £149
+      </Text>
+      <Heading size="xs">And a further additional radio card option</Heading>
+    </Flex>
+  </RadioCard>
+</RadioCardGroup>
+```

package/dist/docs/SearchField.mdx

@@ -0,0 +1,26 @@
+---
+title: Search Field
+component: SearchField
+description: SearchField renders a field composed of an SearchInput, a Label and a InlineMessage
+category: Form fields
+---
+
+`SearchField` is the preferred way to render a form field for search inputs.
+
+In addition to text `Label` (required) and a validation error (optional), `SearchField` accepts all the same props as `SearchInput` and will pass them on to the `SearchInput` it renders. However, as with all our composed components,
+`SearchField`’s `css` prop will be applied to a containing `Box`—the styling of the individual components inside `SearchField` 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
+`SearchInput`, `Label` and `InlineMessage` components.
+
+```tsx preview
+<Form>
+  <SearchField
+    name="Email address"
+    label="Email address"
+    placeholder="your.name@example.com"
+    type="email"
+    css={{ width: 320 }}
+  />
+</Form>
+```

package/dist/docs/SearchInput.mdx

@@ -0,0 +1,13 @@
+---
+title: Search Input
+component: SearchInput
+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.
+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/Select.mdx

@@ -0,0 +1,56 @@
+---
+title: Select
+component: Select
+description: Select is a light wrapper around the HTML select element
+category: Form primitives
+---
+
+It adds default styling and the `css` prop.
+
+A `Select` needs to be associated with a label for accessibility purposes, so rather than using the `Select` component directly in a UI, consider using a `SelectField`, which provides a `Label` and displays validation errors. Use this `Select` to compose more complex `Field` type components.
+
+```tsx preview
+<Select css={{ width: 300 }}>
+  <option value="apples">Apples</option>
+  <option value="bananas">Bananas</option>
+</Select>
+```
+
+## Accessibility
+
+For accessibility purposes the component needs to have the `id` prop set, to link it to the label it is associated with. If a label is not available, please add an `aria-label` to ensure that the component remains accessible
+
+## Placeholder
+
+The component can display a placeholder without a value by passing the `placeholder` property.
+
+```tsx preview
+<Select placeholder="Please select a fruit" css={{ width: 300 }}>
+  <option value="apples">Apples</option>
+  <option value="bananas">Bananas</option>
+</Select>
+```
+
+## Disabled select
+
+The component has a `disabled` state, by setting the `disabled` property.
+
+```tsx preview
+<Select disabled placeholder="Please select a fruit" css={{ width: 300 }}>
+  <option value="apples">Apples</option>
+  <option value="bananas">Bananas</option>
+</Select>
+```
+
+## Disabled Option
+
+The component can show an option as `disabled`, by setting the `disabled` property on the option.
+
+```tsx preview
+<Select placeholder="Please select a fruit" css={{ width: 300 }}>
+  <option value="apples">Apples</option>
+  <option value="bananas" disabled>
+    Bananas
+  </option>
+</Select>
+```

package/dist/docs/SelectField.mdx

@@ -0,0 +1,17 @@
+---
+title: Select Field
+component: SelectField
+description: Wraps a Select with a Label and InlineMessage
+category: Form fields
+---
+
+`SelectField` wraps a `Select` with a `Label` and a `InlineMessage` to provide consistent behaviour and layout.
+
+```tsx preview
+<Form>
+  <SelectField name="options" label="Options" css={{ width: 320 }}>
+    <option value="apples">Apples</option>
+    <option value="bananas">Bananas</option>
+  </SelectField>
+</Form>
+```

package/dist/docs/Sidedrawer.mdx

@@ -0,0 +1,155 @@
+---
+title: Sidedrawer
+component: Sidedrawer,Sidedrawer.Accordion,Sidedrawer.AccordionContent,Sidedrawer.AccordionTrigger,Sidedrawer.Body,Sidedrawer.Close,Sidedrawer.Content,Sidedrawer.Footer,Sidedrawer.Header,Sidedrawer.Item,Sidedrawer.Trigger
+description: A collection of items to build flexible sidedrawer
+category: Navigation
+---
+
+`Sidedrawer` exports components that combine to build complex side navigation.
+
+## The `Sidedrawer` root
+
+Sidedrawer exposes few main elements to build foundations.
+The core element is a `Sidedrawer` which wraps entire components composition.
+`Sidedrawer` has build-in state, but also allows you to pass props to control if from the outside.
+The Sidedrawer root is made in top of the [radix dialog](https://www.radix-ui.com/docs/primitives/components/dialog)
+
+Optional `Sidedrawer` props
+
+- `isOpen` property determines if the whole `Sidedrawer` is visible or not.
+- `onOpenChange` prop should be a function which updates `isOpen` state. This function is triggered automatically when click on `Sidedrawer.Overlay`, `Sidedrawer.Close` or press `Escape` key.
+
+### Fundamental root componenents
+
+- `Sidedrawer.Trigger` - It's the main `trigger element` responsible for opening the whole `Sidedrawer.Content`. This component is build on top of [radix dialog trigger](https://www.radix-ui.com/docs/primitives/components/dialog#trigger)
+- `Sidedrawer.Content` - This is whe wrapper for whole content (`Sidedrawer.Header`, `Sidedrawer.Body`, `Sidedrawer.Footer` and other nested elements). This component is build on top of [radix dialog content](https://www.radix-ui.com/docs/primitives/components/dialog#content)
+
+```tsx
+<Sidedrawer>
+  <Sidedrawer.Trigger asChild>
+    <Button>Open the navigation</Button>
+  </Sidedrawer.Trigger>
+  <Sidedrawer.Content>the sidedrawer content</Sidedrawer.Content>
+</Sidedrawer>
+```
+
+### The `Sidedrawer.Content` children building blocks
+
+- `Sidedrawer.Header` - It's based on `TopBar` component, so it plays really well with all `TopBar` subcomponents. This component is flexible, so you can render anything you need inside of it (for example app logo, Sidedrawer.Close etc.)
+- `Sidedrawer.Close` - It's an `"close" ActionIcon` which triggers `Sidedrawer.Content` closing.
+- `Sidedrawer.Body` - This is the wrapper for all `Sidedrawer.Item` items. The content is scrollable.
+- `Sidedrawer.Footer` - Optional part of the `Sidedrawer`. It's fixed to the botton. You can pass whatever you need as it's children.
+
+```tsx
+<Sidedrawer>
+  <Sidedrawer.Trigger asChild>
+    <Button>Open the navigation</Button>
+  </Sidedrawer.Trigger>
+  <Sidedrawer.Content>
+    <Sidedrawer.Header>
+      <Sidedrawer.Close />
+    </Sidedrawer.Header>
+    <Sidedrawer.Body>Sidedrawer items and Accordions here</Sidedrawer.Body>
+    <Sidedrawer.Footer>Footer items here</Sidedrawer.Footer>
+  </Sidedrawer.Content>
+</Sidedrawer>
+```
+
+## Sidedrawer.Body children
+
+You most likely want to use `Sidedrawer.Item` or `Sidedrawer.Accordion` inside of `Sidedrawer.Body`
+
+### Sidedrawer.Item
+
+Sidedrawer exposes `Item` component to build a navigation elements.
+`Sidedrawer.Item` is renderes as a `link` or a `button` depends on passed props.
+
+- `href` prop determine a link render
+- `onClick` prop determines a button render
+
+**Link item:**
+
+```tsx
+<Sidedrawer.Item href={'/'}>
+  <Icon is={Apps} css={{ mr: '$2' }} />
+  Dashboard
+</Sidedrawer.Item>
+```
+
+**Button item:**
+
+```tsx
+<Sidedrawer.Item onClick={logout}>
+  <Icon is={Exit} css={{ mr: '$2' }} />
+  Log out
+</Sidedrawer.Item>
+```
+
+### Sidedrawer.Accordion
+
+**Accordion item:**
+
+Accordion item requires few elements to work properly:
+
+- `value` property is a unique identifier needed to expand accordion content. [read more](https://www.radix-ui.com/docs/primitives/components/accordion#item)
+- `Sidedrawer.AccordionTrigger` - This component is a trigger which expand/collapse Accordion content. You can pass a text or components composition as its children.
+- `Sidedrawer.AccordionContent` - This component contains whole accorion content. Most likely you would like to pass few another `Sidedrawer.Item` items inside. Accordion content is collapsed until you click the `Sidedrawer.AccordionTrigger` to expand it.
+
+```tsx
+<Sidedrawer.Accordion value="your_unique_identifier">
+  <Sidedrawer.AccordionTrigger>
+    <Icon is={New} css={{ mr: '$2' }} />
+    Set work
+  </Sidedrawer.AccordionTrigger>
+  <Sidedrawer.AccordionContent>
+    <Sidedrawer.Item href={'/practice'}>
+      <Icon is={Feed} css={{ mr: '$2' }} />
+      Practice
+    </Sidedrawer.Item>
+    <Sidedrawer.Item href={'/test'}>
+      <Icon is={Inbox} css={{ mr: '$2' }} />
+      Test
+    </Sidedrawer.Item>
+  </Sidedrawer.AccordionContent>
+</Sidedrawer.Accordion>
+```
+
+## Whole Sidedrawer components composition
+
+```tsx preview
+<Sidedrawer>
+  <Sidedrawer.Trigger asChild>
+    <Button>Open the Sidedrawer</Button>
+  </Sidedrawer.Trigger>
+  <Sidedrawer.Content>
+    <Sidedrawer.Header>
+      <Sidedrawer.Close />
+      <TopBar.BrandLogo
+        src={'https://atomlearning.co.uk/_next/static/media/logo.e9276284.svg'}
+      />
+    </Sidedrawer.Header>
+    <Sidedrawer.Body>
+      <Sidedrawer.Item href={'/'} active>
+        Dashboard
+      </Sidedrawer.Item>
+      <Sidedrawer.Accordion value="1" disabled>
+        <Sidedrawer.AccordionTrigger>Set work</Sidedrawer.AccordionTrigger>
+        <Sidedrawer.AccordionContent>
+          <Sidedrawer.Item href={'/'}>Set Practice</Sidedrawer.Item>
+          <Sidedrawer.Item href={'/'}>Mock Tests</Sidedrawer.Item>
+        </Sidedrawer.AccordionContent>
+      </Sidedrawer.Accordion>
+      <Sidedrawer.Accordion value="2">
+        <Sidedrawer.AccordionTrigger>Resources</Sidedrawer.AccordionTrigger>
+        <Sidedrawer.AccordionContent>
+          <Sidedrawer.Item onClick={() => console.log('clicked!')}>
+            I am a button
+          </Sidedrawer.Item>
+          <Sidedrawer.Item href="/">I am a link</Sidedrawer.Item>
+        </Sidedrawer.AccordionContent>
+      </Sidedrawer.Accordion>
+    </Sidedrawer.Body>
+    <Sidedrawer.Footer>The footer content</Sidedrawer.Footer>
+  </Sidedrawer.Content>
+</Sidedrawer>
+```

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

@@ -0,0 +1,24 @@
+---
+title: Stack
+component: Stack
+description: Stack is a layout component that provides an abstraction over the flexbox gap property
+category: Layout
+---
+
+`Stack` is a single axis layout component enabling you to space items evenly within it using the `gap` prop and change the direction of content with `direction`. In an ideal world this component would be redundant as `gap` would be widely supported when used with `display: flex`; unfortunately browser support [isn’t great](https://caniuse.com/flexbox-gap) with Safari being the last major browser yet to implement it. `@supports()` would usually enable us to progressively enable this property but there’s no way to test when it’s used alongside flexbox, as `gap` is also used in `display: grid`. Until we gain greater browser support, this `Stack` component should provide a similar output.
+
+```tsx preview
+<Stack gap="2" direction="column">
+  <Box css={{ bg: '$primary', size: '$5' }} />
+  <Box css={{ bg: '$primary', size: '$5' }} />
+  <Box css={{ bg: '$primary', size: '$5' }} />
+</Stack>
+```
+
+```tsx preview
+<Stack gap="2" direction="row">
+  <Box css={{ bg: '$primary', size: '$5' }} />
+  <Box css={{ bg: '$primary', size: '$5' }} />
+  <Box css={{ bg: '$primary', size: '$5' }} />
+</Stack>
+```

package/dist/docs/StackContent.mdx

@@ -0,0 +1,32 @@
+---
+title: Stack Content
+component: StackContent
+description: A layout component to provide internal spacing between content components
+category: Layout
+---
+
+`StackContent` applies an opinionated set of spacing rules around our content components, `Heading`, `Text`, `List`, `Divider` and `Image`. It also applies a maximum width to `Heading`, `Text` and `List` to ensure optimal line length is preserved for readability.
+
+```tsx preview
+<StackContent>
+  <Heading size="sm">This is an example of how the content is spaced</Heading>
+  <Text>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+    tempor incididunt ut labore et dolore magna aliqua.
+  </Text>
+  <List>
+    <List.Item>
+      Ullamco laboris nisi ut aliquip ex ea commodo consequat.
+    </List.Item>
+    <List.Item>
+      Duis aute irure dolor in reprehenderit in voluptate velit esse cillum
+      dolore eu fugiat nulla pariatur.
+    </List.Item>
+  </List>
+  <Divider />
+  <Text>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+    tempor incididunt ut labore et dolore magna aliqua.
+  </Text>
+</StackContent>
+```