@atom-learning/components 2.32.2 → 2.33.0

package/dist/docs/Label.mdx

@@ -1,32 +0,0 @@
----
-title: Label
-component: Label
-description: Label is a light wrapper around the basic HTML label element
-category: Form primitives
----
-
-It adds default styling and the `css` prop.
-
-Labels are associated with controls like `input` or `checkbox`, however before using this component consider using one of the provided `Field` components that are available. Use this `Label` to compose more complex `Field` type components.
-
-## Accessibility
-
-For accessibility purposes the component needs either to have the `htmlFor` prop set to link it to the control it is associated with or to wrap around the component that it is labelling.
-
-## Sizes
-
-```tsx preview
-<Label size="sm">A small label</Label>
-```
-
-```tsx preview
-<Label>A normal label</Label>
-```
-
-## Required
-
-To denote a required field, the `required` prop will add an `*` suffix to the label text.
-
-```tsx preview
-<Label required>A normal label</Label>
-```

package/dist/docs/Link.mdx

@@ -1,53 +0,0 @@
----
-title: Link
-component: Link
-description: Link is a light wrapper around the HTML anchor element
-category: Navigation
----
-
-It adds default styling and the `css` prop.
-
-## Sizes
-
-```tsx preview
-<Link href="http://example.com/" size="sm">
-  I'm a link
-</Link>
-```
-
-```tsx preview
-<Link href="http://example.com/">I'm a link</Link>
-```
-
-```tsx preview
-<Link href="http://example.com/" size="lg">
-  I'm a link
-</Link>
-```
-
----
-
-[Capsize](https://seek-oss.github.io/capsize/) is used to size the text to the height of its capital letters, trimming the space above capital letters and below the baseline. This is removed when `Link` is nested within either `Text`, `Heading` or `List` components to ensure that it renders correctly.
-
-```tsx preview
-<Text size="lg">
-  <Link href="http://example.com/">Adaptive online learning</Link> for ages
-  7-12+. Prepare your child for secondary school entry and beyond.
-</Text>
-```
-
-## Polymorphism
-
-The `Link` 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
-<Link href="http://example.com/">
-  I'm a link
-</Link>
-```
-
-```tsx preview
-<Link onClick={() => console.log('clicked')}>
-  I'm a button
-</Link>
-```

package/dist/docs/List.mdx

@@ -1,38 +0,0 @@
----
-title: List
-component: List
-description: List renders an unordered or ordered list
-category: Content
----
-
-`List` renders a `ul` or `ol` based on the `type` prop and accepts a `theme` prop to change the color of the bullets and allows varying sizes.
-
-```tsx preview
-<List>
-  <List.Item>Personalised learning journey</List.Item>
-  <List.Item>Adaptive learning to maximise engagement</List.Item>
-  <List.Item>Comprehensive, teacher-approved content</List.Item>
-  <List.Item>Unlimited, adaptive mock tests</List.Item>
-  <List.Item>Detailed performance analytics</List.Item>
-</List>
-```
-
-```tsx preview
-<List ordered>
-  <List.Item>Personalised learning journey</List.Item>
-  <List.Item>Adaptive learning to maximise engagement</List.Item>
-  <List.Item>Comprehensive, teacher-approved content</List.Item>
-  <List.Item>Unlimited, adaptive mock tests</List.Item>
-  <List.Item>Detailed performance analytics</List.Item>
-</List>
-```
-
-```tsx preview
-<List theme="primary" size="sm">
-  <List.Item>Personalised learning journey</List.Item>
-  <List.Item>Adaptive learning to maximise engagement</List.Item>
-  <List.Item>Comprehensive, teacher-approved content</List.Item>
-  <List.Item>Unlimited, adaptive mock tests</List.Item>
-  <List.Item>Detailed performance analytics</List.Item>
-</List>
-```

package/dist/docs/Loader.mdx

@@ -1,16 +0,0 @@
----
-title: Loader
-component: Loader
-description: Loader provides feedback that an action is in progress
-category: Feedback
----
-
-Render a `Loader` to show that content is loading or that a user’s action is in progress.
-
-```tsx preview
-<>
-  <Loader size="sm" />
-  <Loader />
-  <Loader size="lg" />
-</>
-```

package/dist/docs/MarkdownContent.mdx

@@ -1,77 +0,0 @@
----
-title: Markdown Content
-component: MarkdownContent
-description: MarkdownContent is a content component that will transform a Markdown string into Atom Learning design system components.
-category: Content
----
-
-Currently it suppports converts the following Markdown elements into components:
-
-| Type               | Component           | Default component implemented |
-| :----------------- | :------------------ | :---------------------------- |
-| blockquote         |                     | ⛔                            |
-| code               | `<Box as="pre" />`  | ✅                            |
-| containerDirective |                     | ⛔                            |
-| emphasis           | `<em />`            | ✅                            |
-| heading            | `<Heading />`       | ✅                            |
-| image              | `<Image />`         | ✅                            |
-| inlineCode         | `<Box as="code" />` | ✅                            |
-| leafDirective      |                     | ⛔                            |
-| link               | `<Link />`          | ✅                            |
-| list               | `<List />`          | ✅                            |
-| listItem           | `<List.Item />`     | ✅                            |
-| paragraph          | `<Text />`          | ✅                            |
-| strong             | `<strong />`        | ✅                            |
-| text               | `{value}`           | ✅                            |
-| textDirective      |                     | ⛔                            |
-| thematicBreak      | `<Divider />`       | ✅                            |
-
-```tsx live
-<MarkdownContent
-  content={`
-## This is a heading 2
-
-This will be a paragraph
-
-[And this will  be a link](https://atomlearning.co.uk)
-`}
-/>
-```
-
-## Override with custom components
-
-You can override the component `MarkdownContent` will render for each type by passing an object to the `customComponents` prop where each key is the name of a Markdown Type (see the table above) and the value is a reference to the component you want to render:
-
-```tsx preview
-<MarkdownContent
-  content="This paragraph will have a red color"
-  customComponents={{
-    paragraph: ({ node, handleNode }) => (
-      <Text css={{ color: 'red' }}>{node.children.map(handleNode)}</Text>
-    )
-  }}
-/>
-```
-
-## Markdown directives
-
-The `MarkdownContent` component supports [Markdown directives](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444). There are no directives built in by default, but you can define your own directives by using the `customComponents` prop.
-
-See the following example that transform the following directive into a `Button` component:
-
-```tsx preview
-<MarkdownContent
-  content=":button[This is a button]{href=https://atomlearning.co.uk isRounded=true}"
-  customComponents={{
-    textDirective: ({ node, handleNode }) => {
-      const { name, attributes, children } = node
-
-      if (name === 'button') {
-        return <Button {...attributes}>{children.map(handleNode)}</Button>
-      }
-
-      return null
-    }
-  }}
-/>
-```

package/dist/docs/NavigationMenu.mdx

@@ -1,144 +0,0 @@
----
-title: NavigationMenu
-component: NavigationMenu,NavigationMenu.Link,NavigationMenu.Dropdown,NavigationMenu.DropdownContent,NavigationMenu.DropdownItem
-description: A collection of links for navigating apps.
-category: Navigation
----
-
-`NavigationMenu` exports many components that combine to form a navigation menu.
-
-```tsx preview
-<NavigationMenu>
-  <NavigationMenu.Link href="/overview/introduction">
-    Introduction
-  </NavigationMenu.Link>
-  <NavigationMenu.Dropdown id="1">
-    <NavigationMenu.DropdownTrigger>Theme</NavigationMenu.DropdownTrigger>
-    <NavigationMenu.DropdownContent>
-      <NavigationMenu.DropdownItem href="/theme/colours">
-        Colours
-      </NavigationMenu.DropdownItem>
-      <NavigationMenu.DropdownItem href="/theme/effects">
-        Effects
-      </NavigationMenu.DropdownItem>
-      <NavigationMenu.DropdownItem href="/theme/icons">
-        Icons
-      </NavigationMenu.DropdownItem>
-    </NavigationMenu.DropdownContent>
-  </NavigationMenu.Dropdown>
-</NavigationMenu>
-```
-
-## With client side routing
-
-`NavigationMenu.Dropdown`, `NavigationMenu.DropdownItem` and `NavigationMenu.Link` can be passed an `active` prop for instances when you want to highlight the currently active route. See below for examples using client side routing with the `NavigationMenu.Link` component. The same method can be applied to `NavigationMenu.Dropdown` and `NavigationMenu.DropdownItem`.
-
-#### Example using React Router
-
-```tsx
-const Link = ({ href, ...props }) => {
-  const { pathname } = useLocation()
-  const isActive = path === href
-
-  return (
-    <NavigationMenu.Link active={isActive} {...props}>
-      Introduction
-    </NavigationMenu.Link>
-  )
-}
-```
-
-#### Example using Next JS
-
-```tsx
-const Link = ({ href, ...props }) => {
-  const router = useRouter()
-  const isActive = router.asPath === href
-
-  return (
-    <NavigationMenu.Link active={isActive} {...props}>
-      Introduction
-    </NavigationMenu.Link>
-  )
-}
-```
-
-## Changing the layout of the dropdown content
-
-By default, dropdown items inside of `NavigationMenu.DropdownContent` will stack.
-
-If you want to change the way items are displayed, you can add custom styling to `NavigationMenu.DropdownContent`.
-
-In the below example the styling of `NavigationMenu.DropdownContent` has been changed to allow a grid layout.
-
-```tsx preview
-<NavigationMenu>
-  <NavigationMenu.Link href="/overview/introduction">
-    Introduction
-  </NavigationMenu.Link>
-  <NavigationMenu.Dropdown id="1">
-    <NavigationMenu.DropdownTrigger>Theme</NavigationMenu.DropdownTrigger>
-    <NavigationMenu.DropdownContent
-      css={{
-        display: 'grid',
-        gap: '$1',
-        gridAutoFlow: 'column',
-        width: 500,
-        gridTemplateRows: 'repeat(2, 1fr)'
-      }}
-    >
-      {['colours', 'icons', 'effects', 'typography'].map((item) => (
-        <NavigationMenu.DropdownItem href={`/theme/${item}`}>
-          <NavigationMenu.DropdownItemTitle>
-            {item}
-          </NavigationMenu.DropdownItemTitle>
-          <Text>This is some example text about {item}</Text>
-        </NavigationMenu.DropdownItem>
-      ))}
-    </NavigationMenu.DropdownContent>
-  </NavigationMenu.Dropdown>
-</NavigationMenu>
-```
-
-## DropdownItem composition example
-
-DropdownItem gives a lot of flexibility. It's an easy to compose it for own purposes.
-
-```tsx
-<NavigationMenu.DropdownItem href="/" active>
-  <Grid
-    css={{
-      gridTemplateColumns: '1fr 7fr'
-    }}
-  >
-    <Icon is={Feed} size={'md'} />
-    <Flex css={{ flexDirection: 'column' }}>
-      <NavigationMenu.DropdownItemTitle bold css={{ mb: '$3' }}>
-        Example title
-      </NavigationMenu.DropdownItemTitle>
-      <Text>This is example subtitle</Text>
-    </Flex>
-  </Grid>
-</NavigationMenu.DropdownItem>
-```
-
-## Dropdown Trigger
-
-NavigationMenu.Dropdown gives you the way to pass your own trigger component inside the `NavigationMenu.DropdownTrigger`.
-The children of NavigationMenu.DropdownTrigger can be a plain text or more complex component.
-
-```tsx
-<NavigationMenu.Dropdown id="1">
-  <NavigationMenu.DropdownTrigger>
-    <Avatar />
-  </NavigationMenu.DropdownTrigger>
-  <NavigationMenu.DropdownContent>// content</NavigationMenu.DropdownContent>
-</NavigationMenu.Dropdown>
-
-<NavigationMenu.Dropdown id="2">
-  <NavigationMenu.DropdownTrigger>
-    Plain text
-  </NavigationMenu.DropdownTrigger>
-  <NavigationMenu.DropdownContent>// content</NavigationMenu.DropdownContent>
-</NavigationMenu.Dropdown>
-```

package/dist/docs/NotificationBadge.mdx

@@ -1,35 +0,0 @@
----
-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/NumberInput.mdx

@@ -1,37 +0,0 @@
----
-title: Number Input
-component: NumberInput
-description: The NumberInput component is similar to the Input component, but it has controls for incrementing or decrementing numeric values.
-category: Form primitives
----
-
-`NumberInput` wraps `Input` set to a numeric value, along with two `ActionIcon` buttons for decrementing and incrementing the value.
-
-```tsx preview
-<NumberInput name="age" />
-```
-
-When min or max values are set, the corresponding decrement or increment button will become disabled when the min/max values are reached. By default, min is set to 0.
-
-A tooltip will display on hover of a disabled button, providing information on why the button is disabled. To override the default tooltip content, pass in a `disabledTooltipContent` object.
-
-Note: A `<ToolTipProvider />` must be rendered at the root of the app for this to work.
-
-```tsx preview
-<NumberInput
-  name="age"
-  max={11}
-  disabledTooltipContent={{ increment: 'Ages over 11 are not allowed' }}
-/>
-```
-
-## Keyboard interactions
-
-A negative `tabindex` has been added to the increment and decrement buttons to remove them from the default tabbing order. Instead, users can use the below keys to interact with the component.
-
-- When you hit the ⬆️ or ➡️ key, the input value will be increased by step.
-- When you hit the ⬅️ or ⬇️ key, the input value will be decreased by step.
-- When you hit the Home button, the value will jump to the min value.
-- When you hit the End button, the value will jump to the max value.
-
-See [MDN docs](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role#keyboard_interactions) for more information on accessibility.

package/dist/docs/NumberInputField.mdx

@@ -1,26 +0,0 @@
----
-title: Number Input Field
-component: NumberInputField
-description: NumberInputField renders a field composed of an NumberInput, a Label and a InlineMessage
-category: Form fields
----
-
-`NumberInputField` is the preferred way to render a form field for a number input.
-
-In addition to text `Label` (required) and a validation error (optional), `NumberInputField` accepts all the same props as `NumberInput` and will pass them on to the `NumberInput` it renders.
-
-```tsx preview
-<Form>
-  <NumberInputField
-    label="Number of cats"
-    name="cats"
-    min={3}
-    validation={{
-      min: {
-        value: 3,
-        message: 'You must have at least 3 cats!'
-      }
-    }}
-  />
-</Form>
-```

package/dist/docs/PasswordField.mdx

@@ -1,23 +0,0 @@
----
-title: Password Field
-component: PasswordField
-description: PasswordField is a specialised field for password input
-category: Form fields
----
-
-`PasswordField` is the preferred way to render a form field for a current password (not necessarily for creating a new password).
-
-`PasswordField` accepts the same props as `InputField` but provides default values for some of them (e.g. `label` defaults to `"Password"` and `name` defaults to `password`).
-
-In addition to the regular `InputField` props and functionality, `PasswordField` accepts an optional `forgotPasswordURL` prop which will be used to render a link to a password reset page. It also provides the ability for the user to toggle visibility of their password.
-
-```tsx preview
-<Form>
-  <PasswordField
-    name="password"
-    prompt={{ link: '/forgot-password', label: 'Forgotten your password?' }}
-    placeholder="Your password"
-    css={{ width: 320 }}
-  />
-</Form>
-```

package/dist/docs/PasswordInput.mdx

@@ -1,15 +0,0 @@
----
-title: Password Input
-component: PasswordInput
-description: An input for passwords with visibility toggle functionality
-category: Form primitives
----
-
-`PasswordInput` wraps `Input` with a content visibility toggle, triggered by interaction with an eye Icon.
-
-For most use cases it is better to use `PasswordField`, which includes a label, hooks into our `Form` component and shows validation errors where appropriate.
-Only use `PasswordInput` if you need to compose something that behaves differently to the `PasswordField` and be sure to include a label manually.
-
-```jsx preview
-<PasswordInput name="password" />
-```

package/dist/docs/Popover.mdx

@@ -1,29 +0,0 @@
----
-title: Popover
-component: Popover,Popover.Trigger,Popover.Content,Popover.Portal
-description: Popover provides a styled actionable popup
-category: Surfaces
----
-
-`Popover` exports 3 components that combine to create our popover. The `Popover.Trigger` renders a `<button>` by default, but this can be overridden with the `asChild` prop, which will instead add all the functional and accessibility requirements to the child component instead (see the below example).
-
-Also, note that the component must accept a `ref`.
-
-Read more about the underlying UI component on the [Radix UI documentation site](https://radix-ui.com/primitives/docs/components/popover).
-
-```tsx preview
-<Popover>
-  <Popover.Trigger asChild>
-    <Button>Click me</Button>
-  </Popover.Trigger>
-  <Popover.Content>
-    <Heading size="xs" css={{ mb: '$3' }}>
-      Popover
-    </Heading>
-    <Text size="sm">
-      The `Popover` can display any type of element as a trigger and has the
-      content hidden by default
-    </Text>
-  </Popover.Content>
-</Popover>
-```

package/dist/docs/ProgressBar.mdx

@@ -1,56 +0,0 @@
----
-title: Progress Bar
-component: ProgressBar
-description: ProgressBar provides a styled progress bar
-category: Feedback
----
-
-## Accessibility
-
-A `ProgressBar` needs to be associated with a label for accessibility purposes, therefore the component `id` needs to be set. If a label is not available, please add an `aria-label` to ensure that the component remains accessible.
-For more examples, please read [aria-progressbar-name](https://dequeuniversity.com/rules/axe/4.1/aria-progressbar-name?application=axeAPI)
-
-```tsx live
-<ProgressBar value={20} aria-label="Completion rate" />
-```
-
-## Themes
-
-These are the available `themes` for this component: `Primary` (default), `Success`, `Warning`, `Danger`
-
-```tsx preview
-<>
-  <ProgressBar value={20} />
-  <ProgressBar theme="success" value={20} aria-label="Completion rate" />
-  <ProgressBar theme="warning" value={20} aria-label="Completion rate" />
-  <ProgressBar theme="danger" value={20} aria-label="Completion rate" />
-</>
-```
-
-## Appearance
-
-There two options for the `appearance` property: `solid` and `outline(default)`. These are the available `outline` variations for all the `themes`.
-
-```tsx preview
-<>
-  <ProgressBar appearance="solid" value={20} aria-label="Completion rate" />
-  <ProgressBar
-    appearance="solid"
-    theme="success"
-    value={20}
-    aria-label="Completion rate"
-  />
-  <ProgressBar
-    appearance="solid"
-    theme="warning"
-    value={20}
-    aria-label="Completion rate"
-  />
-  <ProgressBar
-    appearance="solid"
-    theme="danger"
-    value={20}
-    aria-label="Completion rate"
-  />
-</>
-```

package/dist/docs/README.mdx

@@ -1,79 +0,0 @@
-## Color Schemes (v.ALPHA)
-
-`color-scheme/`, is an **internal** component in an alpha stage (usable but not finalised) which introduces a `ColorScheme` component. It has been worked on heavily in terms of considering the required options and logic from dev but is **not finished and needs more design input**.
-
-The problem that this component was introduced to solve is the difficult way we have approached theming so far in our components.
-In the past we have heavily relied on props drilling and passing down theme related stitches variants to children, which means _(1)_ the colours can easily break when the expected children are nested further than directly under the 'theme providing' parent (The component which has a `theme` prop and tries to prop-drill theme). Moreover, _(2)_ we have inconsistent naming for our themes and _(3)_ inconsistent implementations on active components since _(4)_ the theming need to be documented and coded separately for each new component.
-
-This `<ColorScheme />` component allows for `base` (`var(--baseX)`) and `accent` (`var(--accentX)`) theme property, as well as an `interactive` contrast mode to affect all interactable components.
-
-The props are:
-
-- `base` is used for the base colours of the wrapped component: different tones of background and text. It currently only supports the `slate` (grey) colour but can be extended for different base colors.
-- `accent` is used for highlighted elements and interactive elements of the color scheme. It can be used directly but should be used with an interactive theme for interactive elements - see `<Button />`, `Accordion.Trigger` etc. Currently allowed accents are `slate` and `blue`.
-- `interactive` supports 4 versions `loContrast1` and `loContrast2` which on light color schemes are lighter and on a dark mode they would be darker (so low contrast in comparison to the background), and `hiContrast1`, `hiContrast2` which are used for the opposite.
-
-All the color scheme configurations setup used in the component can be found in `color-scheme/src/stitches.colorscheme.config.ts`
-
-The ColorScheme itself works by re-declaring the needed CSS variables any time it's used. It is heavily inpired by both [stitches theming guidelines](https://stitches.dev/docs/theming) and particularly by [the radix colors project](https://www.radix-ui.com/colors) of which it's almost a copy of but with our own colours defined and some aliasing to match the current design use requirements.
-
-Currently in use by a couple of components in library and the full documentation site. This component is subject to change when the Atom Learning colour theming patterns are properly established and we can make final decisions on the colours and API. **There will be changes to this code in the future.**
-
-### Examples
-
-```jsx
-<ColorScheme base="slate" accent="blue" interactive="hiContrast1">
-  <Box css={{ background: '$background', color: '$foreground' }}>
-    Off-black text over a white background
-  </Box>
-  <Box css={{ background: '$base1', color: '$foreground' }}>
-    Off-black text over very slightly grey background
-  </Box>
-  <Box css={{ background: '$base7', color: '$foreground6plus' }}>
-    White text over darker grey background
-  </Box>
-  <Box css={{ background: '$accent1', color: '$foreground' }}>
-    Off-black text over a slightly blue background
-  </Box>
-  <Box css={{ background: '$accent7', color: '$foreground6plus' }}>
-    White text over darker blue background
-  </Box>
-  <Box css={{ background: '$accent9', color: '$foreground6plus' }}>
-    White text over much darker blue background
-  </Box>
-  <Button
-    css={{
-      background: '$interactive1',
-      color: '$interactiveForeground',
-      ['&:hover']: { background: '$interactive2' },
-      ['&:active']: { background: '$interactive3' }
-    }}
-  >
-    Blue button with white text
-  </Button>
-  <ColorScheme
-    interactive="hiContrast2"
-    as={Button}
-    css={{
-      background: '$interactive1',
-      color: '$interactiveForeground',
-      ['&:hover']: { background: '$interactive2' },
-      ['&:active']: { background: '$interactive3' }
-    }}
-  >
-    Darker blue button with white text
-  </ColorScheme>
-  <ColorScheme
-    interactive="loContrast2"
-    as={Button}
-    css={{
-      background: '$interactive1',
-      color: '$interactiveForeground',
-      ['&:hover']: { background: '$interactive2' },
-      ['&:active']: { background: '$interactive3' }
-    }}
-  >
-    Light blue button with off-black text
-  </ColorScheme>
-</ColorScheme>
-```