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

package/dist/docs/Accordion.mdx

@@ -0,0 +1,45 @@
+---
+title: Accordion
+component: Accordion,Accordion.Item,Accordion.Trigger,Accordion.Content
+description: A vertically stacked group of interactive headings that reveal an associated section of content when clicked
+category: Layout
+---
+
+The Accordion exports 4 components that combine to make the `Accordion`. The parent Accordion contains `Accordion.Item` components, which themselves must contain `Accordion.Trigger` and `Accordion.Content`.
+
+The `Accordion.Trigger` has been simplified to include a chevron icon. Generally, you would only want to render text inside the rest.
+
+Default styling has been applied to `Accordion.Trigger`, but `Accordion.Content` is an empty container without styling. Should only text be placed inside, it is highly advisable to apply spacing to align with the styling of the rest of the Accordion. This can be done with either the `css` property, or by placing any other components inside the `Accordion.Content`.
+
+You can Read more about the underlying UI component on the [Radix UI documentation site](https://radix-ui.com/primitives/docs/components/accordion).
+
+```tsx preview
+<Accordion type="single" defaultValue="1">
+  <Accordion.Item value="1">
+    <Accordion.Trigger theme="light">Accordion Header 1</Accordion.Trigger>
+    <Accordion.Content css={{ p: '$4' }}>Accordion content 1</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="2">
+    <Accordion.Trigger>Accordion Header 2</Accordion.Trigger>
+    <Accordion.Content css={{ p: '$4' }}>Accordion content 2</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+## Values
+
+Each `Accordion.Item` must have a value, which can either be used as a `defaultValue` on the Accordion, or by setting the `value` of the Accordion so it is a controlled component. If value is set, it must also contain an `onValueChange` function that sets the value to a new value.
+
+## Collapsible
+
+Accordions can be given the property `collapsible`, which allows all items to be collapsed. Without passing this at least one item must be open.
+
+## Type
+
+Accordions can have `type` as either `single` or `multiple`. This changes how many items can be expanded at once. The default is `single`.
+
+Note: if `multiple`, `value` and `defaultValue` must be in an array. Even if you want just one item to be visible initially, you must pass something like `defaultValue={['name']}`
+
+## Themes
+
+`Accordion.Trigger` can have a `theme` property. Possible values are `primaryDark` and `light`. The default is `primaryDark`.

package/dist/docs/ActionIcon.mdx

@@ -0,0 +1,87 @@
+---
+title: Action Icon
+component: ActionIcon
+description: An accessible interactive wrapper around Icon
+category: Navigation
+---
+
+`ActionIcon` should be used alongside `Icon` when you require a user interaction.
+
+```tsx preview
+<>
+  <ActionIcon label="Attach a file" appearance="simple">
+    <Icon is={Clip} />
+  </ActionIcon>
+  <ActionIcon label="Attach a file" appearance="outline">
+    <Icon is={Clip} />
+  </ActionIcon>
+  <ActionIcon label="Attach a file" appearance="solid">
+    <Icon is={Clip} />
+  </ActionIcon>
+</>
+```
+
+## Rounded Variant
+
+Setting `isRounded` makes the Action circular when paired with the options "outline" and "solid" for the `appearance` prop
+
+```tsx preview
+<>
+  <ActionIcon label="Attach a file" appearance="outline" isRounded>
+    <Icon is={Bell} />
+  </ActionIcon>
+  <ActionIcon label="Attach a file" appearance="solid" isRounded>
+    <Icon is={Bell} />
+  </ActionIcon>
+</>
+```
+
+## Disabled state
+
+Passing `disabled` makes the Action Icon take a disabled appearance, where any cursor interaction with the component will not render any changes in its UI.
+
+```tsx preview
+<>
+  <ActionIcon label="Attach a file" appearance="simple" disabled>
+    <Icon is={Bell} />
+  </ActionIcon>
+  <ActionIcon label="Attach a file" appearance="outline" disabled>
+    <Icon is={Bell} />
+  </ActionIcon>
+  <ActionIcon label="Attach a file" appearance="solid" disabled>
+    <Icon is={Bell} />
+  </ActionIcon>
+</>
+```
+
+It is recommended to pair `ActionIcon` with `Tooltip` to provide a clear visual description of the action the user is about to perform.
+
+```tsx preview
+// `Tooltip.Provider` is included here to enable the example `Tooltip`, but you should generally place it at the root of your application
+<Tooltip.Provider>
+  <Tooltip>
+    <Tooltip.Trigger asChild>
+      <ActionIcon size="lg" label="Add to basket">
+        <Icon is={Basket} size="md" />
+      </ActionIcon>
+    </Tooltip.Trigger>
+    <Tooltip.Content>Add to basket</Tooltip.Content>
+  </Tooltip>
+</Tooltip.Provider>
+```
+
+## Polymorphism
+
+The `ActionIcon` component supports polymorphism, therefore depending on whether it receives an `onClick`/`href` as a prop, it will produce a `button` or `link` respectively
+
+```tsx preview
+<ActionIcon label="Shuffle selection" onClick={() => console.log('clicked')}>
+  <Icon is={Shuffle} />
+</ActionIcon>
+```
+
+```tsx preview
+<ActionIcon label="Add a new folder" href="/directory/add">
+  <Icon is={FolderAdd} />
+</ActionIcon>
+```

package/dist/docs/AlertDialog.mdx

@@ -0,0 +1,40 @@
+---
+title: Alert Dialog
+component: AlertDialog,AlertDialog.Trigger,AlertDialog.Content
+description: A modal dialog that interrupts the user with important content and expects a response
+category: Feedback
+---
+
+`AlertDialog` exports a number of components that can be composed together to create a modal pop up that expects a response from the user. `AlertDialog` also exports a custom hook that can be used to dynamically render an alert based on some content and a callback; you can see an example of this below.
+
+```tsx
+import { AlertProvider, Button, useAlert } from '@atom-learning/components'
+
+const Component = () => {
+  const { showAlert } = useAlert()
+
+  const handleClick = () => {
+    showAlert({
+      title: 'Are you sure you want to delete this school?',
+      description: 'This will remove all restrictions from your school',
+      confirmActionText: 'Delete school',
+      cancelActionText: 'Cancel',
+      onAction: (result) => {
+        if (result) console.log('Confirmation')
+      }
+    })
+  }
+
+  return <Button onClick={handleClick}>Delete school</Button>
+}
+
+const App = () => (
+  <AlertProvider>
+    <Component />
+  </AlertProvider>
+)
+```
+
+### Accessibility
+
+Consider pairing the `onAction` function with a method that can announce a message to the user. In the above example a message of "School has been deleted" would be appropriate for screen reader users. [Radix UI Announce](https://radix-ui.com/primitives/docs/utilities/announce) would be a good candidate for this.

package/dist/docs/Avatar.mdx

@@ -0,0 +1,129 @@
+---
+title: Avatar
+component: Avatar,Avatar.Image,Avatar.Initial,Avatar.Placeholder,Avatar.Icon
+description: Show a thumbnail representation of an individual or entity.
+category: Media
+---
+
+The `Avatar` component can be used to show a visual representation of a user or entity. It helps to quickly identify users or objects.
+
+```jsx preview
+<Avatar name="Alice Smith">
+  <Avatar.Image
+    alt="Alice Smith's avatar"
+    src="https://thispersondoesnotexist.com/image"
+  />
+</Avatar>
+```
+
+Instead of an image, the initial of the name or a placeholder icon can be used
+
+```jsx preview
+<>
+  <Avatar name="Alice Smith">
+    <Avatar.Initial />
+  </Avatar>
+  <Avatar>
+    <Avatar.Placeholder />
+  </Avatar>
+</>
+```
+
+When an image src is missing it will fallback to the initial of the name.
+
+```jsx preview
+<Avatar name="Alice Smith">
+  <Avatar.Image alt="" src="" />
+</Avatar>
+```
+
+When the name is also missing it will fallback to the placeholder icon.
+
+```jsx preview
+<Avatar name="">
+  <Avatar.Image alt="Alice Smith's avatar" src="" />
+</Avatar>
+```
+
+When `<Avatar.Initial />` is used but the name is missing, it will fallback to the placeholder icon.
+
+```jsx preview
+<Avatar name="">
+  <Avatar.Initial />
+</Avatar>
+```
+
+An `onClick` prop can be used, this will make the component focusable using the keyboard, as it uses a `<button>` under the hood.
+
+```jsx preview
+<Avatar name="Alice Smith" onClick={() => alert('Thanks for clicking')}>
+  <Avatar.Initial />
+</Avatar>
+```
+
+When disabled, the onClick won't work.
+
+```jsx preview
+<Avatar
+  name="Alice Smith"
+  disabled
+  onClick={() => alert('This message will not appear')}
+>
+  <Avatar.Initial />
+</Avatar>
+```
+
+Instead of an image, an icon can be passed.
+
+```jsx preview
+<>
+  <Avatar>
+    <Avatar.Icon is={BatteryMedium} />
+  </Avatar>
+</>
+```
+
+## Size
+
+The available `size`s for this component are: `xs`, `sm`, `md`, `lg`, `xl` and `xxl`. The default is `lg`.
+
+```jsx live
+<>
+  <Avatar size="xs" name="Alice Smith">
+    <Avatar.Image
+      alt="Alice Smith's avatar"
+      src="https://thispersondoesnotexist.com/image"
+    />
+  </Avatar>
+  <Avatar size="sm" name="Alice Smith">
+    <Avatar.Image
+      alt="Alice Smith's avatar"
+      src="https://thispersondoesnotexist.com/image"
+    />
+  </Avatar>
+  <Avatar size="md" name="Alice Smith">
+    <Avatar.Image
+      alt="Alice Smith's avatar"
+      src="https://thispersondoesnotexist.com/image"
+    />
+  </Avatar>
+  <Avatar size="lg" name="Alice Smith">
+    <Avatar.Image
+      alt="Alice Smith's avatar"
+      src="https://thispersondoesnotexist.com/image"
+    />
+  </Avatar>
+  <Avatar size="xl" name="Alice Smith">
+    <Avatar.Image
+      alt="Alice Smith's avatar"
+      src="https://thispersondoesnotexist.com/image"
+    />
+  </Avatar>
+  <Avatar size="xxl" name="Alice Smith">
+    <Avatar.Image
+      alt="Alice Smith's avatar"
+      src="https://thispersondoesnotexist.com/image"
+    />
+  </Avatar>
+</>
+```

package/dist/docs/Badge.mdx

@@ -0,0 +1,55 @@
+---
+title: Badge
+component: Badge
+description: Highlights a small piece of information
+category: Feedback
+---
+
+The `Badge` component can be used to highlight a short piece of information, like a status.
+
+```tsx preview
+<Badge>New Data</Badge>
+```
+
+## Theme
+
+These are the available `theme`s for this component: `success`, `warning`, `danger`, `neutral` and `info`. The default is `info`
+
+```tsx preview
+<>
+  <Badge>Info</Badge>
+  <Badge theme="neutral">Neutral</Badge>
+  <Badge theme="success">Success</Badge>
+  <Badge theme="warning">Warning</Badge>
+  <Badge theme="danger">Danger</Badge>
+</>
+```
+
+## Size
+
+These are the available `size`s for this component: `xs`, `sm` and `md`. The default is `sm`
+
+```tsx preview
+<>
+  <Badge size="xs">extra small</Badge>
+  <Badge size="sm">small</Badge>
+  <Badge size="md">medium</Badge>
+</>
+```
+
+## With icons
+
+An `<Icon />` can be passed as a child to show alongside text.
+
+```tsx preview
+<>
+  <Badge>
+    <Icon is={Wifi} />
+    Info with icon
+  </Badge>
+  <Badge theme="neutral">
+    Info with icon
+    <Icon is={Wifi} />
+  </Badge>
+</>
+```

package/dist/docs/Box.mdx

@@ -0,0 +1,52 @@
+---
+title: Box
+component: Box
+description: Box is our most fundamental layout component
+category: Layout
+---
+
+`Box` can largely be seen as an abstraction over the `div` element. It is most useful when used as a generic containing component, and when paired with `as` and `css` allows a high degree of composition and flexibility.
+
+`Box` falls back to rendering a `div`, but we should use it to render more sematically relevant container elements e.g. `<Box as="section">`. As an example, a card component could use `Box` to render a `section`, `header` and `footer`.
+
+Avoid rendering any of these elements directly in our components — `Box` has all the same flexibility, but with the addition of the powerful `css` prop and various styling utilities based on our themes.
+
+## Example
+
+To show an example of the benefits of using `Box`, the card below is composed together using `Box` alongside other relevant components:
+
+```tsx live
+<Box
+  as="article"
+  css={{
+    border: '1px solid $tonal100',
+    borderRadius: '$1',
+    overflow: 'hidden',
+    width: '320px'
+  }}
+>
+  <Box as="figure" css={{ m: 0, position: 'relative' }}>
+    <Image src="http://placekitten.com/320/200" alt="Cats having a nice time" />
+    <Text
+      as="figcaption"
+      size="sm"
+      css={{
+        bottom: '$3',
+        color: 'white',
+        position: 'absolute',
+        right: '$3'
+      }}
+    >
+      Here is a cute cat
+    </Text>
+  </Box>
+  <Stack gap="4" css={{ px: '$3', py: '$4' }}>
+    <Heading as="h2" size="sm">
+      Cat
+    </Heading>
+    <Text>
+      The cat (Felis catus) is a domestic species of small carnivorous mammal.
+    </Text>
+  </Stack>
+</Box>
+```

package/dist/docs/Button.mdx

@@ -0,0 +1,76 @@
+---
+title: Button
+component: Button
+description: The Button component is a light wrapper around an HTML button element
+category: Navigation
+---
+
+It adds default styling and the `css` prop. By default `primary` theme is displayed with a `solid` appearance.
+
+```tsx live
+<Button>Hello world</Button>
+```
+
+## Themes
+
+These are the available `themes` for the `Button` component: `primary` (default), `secondary`, `success`, `warning`, `danger`, and `neutral`.
+
+```tsx preview
+<>
+  <Button>Primary</Button>
+  <Button theme="secondary">Secondary</Button>
+  <Button theme="success">Success</Button>
+  <Button theme="warning">Warning</Button>
+  <Button theme="danger">Danger</Button>
+  <Button theme="neutral">Neutral</Button>
+</>
+```
+
+## Appearance
+
+There are two options for the `appearance` property: `solid` and `outline`. There are the available `outline` variations for the `primary`, `secondary` and `neutral` themes.
+
+```tsx preview
+<Button appearance="outline">Primary</Button>
+```
+
+## Disabled state
+
+Each variation has an `disabled` stated, by setting the `disabled` property.
+
+```tsx preview
+<>
+  <Button disabled>Disabled button</Button>
+  <Button theme="success" disabled>
+    Disabled button
+  </Button>
+</>
+```
+
+## Loading state
+
+When using a button to request data or fire an action that has a potential delay, including a loading state to the button can be a useful indicator that stuff is happening. The `isLoading` prop must be a boolean value to activate the loading state.
+
+```tsx live
+<Button isLoading> Hello world</Button>
+```
+
+## Rounded Variant
+
+Setting `isRounded` creates a rounded button
+
+```tsx live
+<Button isRounded>Rounded Button</Button>
+```
+
+## Polymorphism
+
+The `Button` component supports polymorphism, therefore depending on whether it receives an `onClick`/`href` as a prop, it will produce a `button` or `link` respectively
+
+```tsx preview
+<Button href="http://example.com/">I'm a link</Button>
+```
+
+```tsx preview
+<Button onClick={() => console.log('clicked')}>I'm a button</Button>
+```