@atom-learning/components 2.2.0 → 2.4.0

package/dist/docs/Chip.mdx

@@ -0,0 +1,118 @@
+---
+title: Chip
+component: Chip, ChipGroup
+description: A component in the shape of a pill providing visual cues to prompt users to enter information or filter content.
+category: Feedback
+---
+
+`Chip` itself is a primitive. It has no functional logic in itself, however, it is used to provide common styles for all the `Chip`-based components.
+
+```tsx preview
+<Chip>
+  <Chip.Content>Not the tasty kind</Chip.Content>
+</Chip>
+```
+
+## Gap
+
+`gap={ 1 | 2 | 3}`
+
+We provide three options for gap space between chips. `1` will be typically used within Input fields (multiselect) or when space is limited. `2` is the default option that provides a comfortable distance for the set.
+
+```tsx preview
+<ChipGroup gap={1}>
+  <Chip>
+    <Chip.Content>A</Chip.Content>
+  </Chip>
+  <Chip>
+    <Chip.Content>B</Chip.Content>
+  </Chip>
+  <Chip>
+    <Chip.Content>C</Chip.Content>
+  </Chip>
+</ChipGroup>
+```
+
+## Size
+
+`size="sm | md | lg"`
+
+```tsx preview
+<ChipGroup align="center">
+  <Chip size="sm">
+    <Chip.Content>
+      <Icon is={Upload} />A
+    </Chip.Content>
+  </Chip>
+  <Chip size="md">
+    <Chip.Content>
+      <Icon is={Upload} />B
+    </Chip.Content>
+  </Chip>
+  <Chip size="lg">
+    <Chip.Content>
+      <Icon is={Upload} />C
+    </Chip.Content>
+  </Chip>
+  <Chip
+    size={{
+      '@initial': 'lg',
+      '@md': 'md',
+      '@lg': 'sm'
+    }}
+  >
+    <Chip.Content>
+      <Icon is={Upload} />C
+    </Chip.Content>
+  </Chip>
+</ChipGroup>
+```
+
+## Icon
+
+When an `<Icon />` is used as an immediate child of `<Chip.Content />` we automatically transform it to
+a `<Chip.Icon />` which applies the correct styles and sizing to it.
+
+```tsx preview
+<ChipGroup>
+  <Chip>
+    <Chip.Content>
+      <Icon is={Upload} /> Icon
+    </Chip.Content>
+  </Chip>
+  <Chip>
+    <Chip.Content>
+      <Chip.Icon is={Upload} /> Chip.Icon
+    </Chip.Content>
+  </Chip>
+</ChipGroup>
+```
+
+If additional nesting is needed; you can use the `<Chip.Icon />` component directly.
+
+```tsx preview
+<ChipGroup>
+  <Chip>
+    <Chip.Content>
+      <div>
+        <Icon is={Upload} /> Icon (wrong sizing)
+      </div>
+    </Chip.Content>
+  </Chip>
+  <Chip>
+    <Chip.Content>
+      <div>
+        <Chip.Icon is={Upload} /> Chip.Icon
+      </div>
+    </Chip.Content>
+  </Chip>
+</ChipGroup>
+```
+
+## Disabled
+
+```tsx preview
+<Chip data-disabled>
+  <Chip.Content>Not the tasty kind</Chip.Content>
+</Chip>
+```

package/dist/docs/ChipDismissibleGroup.mdx

@@ -0,0 +1,33 @@
+---
+title: Chip Dismissible Group
+component: ChipDismissibleGroup
+description: Combines the DismissibleGroup logic together with the Chip primitive styling
+category: Feedback
+---
+
+Used to visualise groups of dismissible information, in fields such as an entity or different attributes. Can also be used to represent removable filtering criteria.
+
+```tsx preview
+<ChipDismissibleGroup
+  onDismiss={(value) => {
+    alert(`dismiss ${value}`)
+  }}
+>
+  <ChipDismissibleGroup.Item value="a" dismissActionLabel="Dismiss 'A'">
+    <Icon is={Person} />
+    Dismissible
+  </ChipDismissibleGroup.Item>
+  <ChipDismissibleGroup.Item value="b" dismissActionLabel="Dismiss 'B'">
+    <Icon is={Person} />
+    Dismissible
+  </ChipDismissibleGroup.Item>
+  <ChipDismissibleGroup.Item
+    value="c"
+    dismissActionLabel="Dismiss 'C'"
+    disabled
+  >
+    <Icon is={Person} />
+    Dismissible
+  </ChipDismissibleGroup.Item>
+</ChipDismissibleGroup>
+```

package/dist/docs/ChipToggleGroup.mdx

@@ -0,0 +1,27 @@
+---
+title: Chip Toggle Group
+component: ChipToggleGroup
+description: Combines the Toggle Group radix component with the Chip primitive styling
+category: Feedback
+---
+
+Used as a method for filtering a collection of data. Acts like multiple or single selection. Each chip toggles between selected and unselected. When selected, a checkmark appears as the leading icon.
+
+```tsx preview
+<ChipToggleGroup
+  type="multiple"
+  defaultValue={['a', 'b']}
+  onValueChange={(value) => {
+    console.log(value)
+  }}
+>
+  <ChipToggleGroup.Item value="a">A</ChipToggleGroup.Item>
+  <ChipToggleGroup.Item value="b" disabled>
+    B
+  </ChipToggleGroup.Item>
+  <ChipToggleGroup.Item value="c">C</ChipToggleGroup.Item>
+  <ChipToggleGroup.Item value="d" disabled>
+    D
+  </ChipToggleGroup.Item>
+</ChipToggleGroup>
+```

package/dist/docs/Dismissible.mdx

@@ -0,0 +1,48 @@
+---
+title: Dismissible
+component: Dismissible
+description: An element with a dismiss button which removes it from the view
+category: Primitives
+---
+
+`Dismissible` itself is a primitive. It has not been designed so it should not be used out-of-the-box as a user facing component.
+Test the component is accessible depending on each implementation use case.
+
+```tsx preview
+<Dismissible
+  value="a"
+  onDismiss={(value) => {
+    alert(`dismiss ${value}`)
+  }}
+>
+  Press the trigger to dismiss this ->
+  <Dismissible.Trigger aria-label="Dismiss 'a'" />
+</Dismissible>
+```
+
+```tsx preview
+<Dismissible
+  value="custom"
+  onDismiss={(value) => {
+    alert(`dismiss ${value}`)
+  }}
+  asChild
+>
+  <Box
+    css={{
+      width: '100%',
+      fontFamily: 'system-ui',
+      border: '1px solid',
+      borderRadius: 4,
+      display: 'flex',
+      justifyContent: 'space-between',
+      padding: 8
+    }}
+  >
+    Basic custom implementation example
+    <Dismissible.Trigger asChild>
+      <button type="button">Custom Dismiss Trigger</button>
+    </Dismissible.Trigger>
+  </Box>
+</Dismissible>
+```

package/dist/docs/DismissibleGroup.mdx

@@ -0,0 +1,29 @@
+---
+title: Dismissible Group
+component: DismissibleGroup
+description: A set of dismissible elements.
+category: Primitives
+---
+
+`DismissibleGroup` itself is a primitive. It has not been designed so it should not be used out-of-the-box as a user facing component.
+Test the component is accessible depending on each implementation use case.
+
+```tsx preview
+<DismissibleGroup
+  onDismiss={(value) => {
+    alert(`dismiss ${value}`)
+  }}
+>
+  <DismissibleGroup.Item value="a">
+    A
+    <DismissibleGroup.Trigger aria-label="Dismiss A" />
+  </DismissibleGroup.Item>
+  <DismissibleGroup.Item value="b" disabled>
+    B
+    <DismissibleGroup.Trigger />
+  </DismissibleGroup.Item>
+  <DismissibleGroup.Item value="c" disabled>
+    C
+  </DismissibleGroup.Item>
+</DismissibleGroup>
+```

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

@@ -0,0 +1,59 @@
+---
+title: TopBar
+component: TopBar,TopBar.Brand,TopBar.BrandLogo,TopBar.BrandText,TopBar.ActionIcon
+description: The top bar provides content and actions related to the current screen. It is used for branding, screen titles, navigation, and actions.
+category: Surfaces
+---
+
+`TopBar` exports components that combine to form the elements that you would expect to commonly see in a TopBar. However, the `TopBar` is not limited to these components, as any components may sit within the `TopBar` to create a flexible and custom UI.
+
+By default, `TopBar` uses a flex layout with flex items placed immediately after each other. To align flex items, an optional css prop with `justifyContent` can be passed.
+
+Alternatively, if you want to avoid wrapping groups of items with a `div` purely for alignment purposes, you could use a spacer. In this example, the styling of the `Flex` component has been extended so that it stretches to fill the available space.
+
+```tsx preview
+<TopBar>
+  <TopBar.Brand href="atomlearning.co.uk">
+    <TopBar.BrandName>Admin Panel</TopBar.BrandName>
+  </TopBar.Brand>
+  <Flex css={{ flex: 1, justifySelf: 'stretch', alignSelf: 'stretch' }} />
+  <Stack gap="2" direction="row">
+    <TopBar.ActionIcon icon={Search} label="Search" />
+    <TopBar.Divider />
+    <TopBar.ActionIcon icon={SwitchOff} label="Light/Dark mode" />
+  </Stack>
+</TopBar>
+```
+
+## TopBar.Brand
+
+`TopBar.Brand` renders a styled link.
+
+```tsx
+import logo from '@atom-learning/theme/lib/assets/logo.svg'
+
+const App = () => {
+  return (
+    <TopBar>
+      <TopBar.Brand href="atomlearning.co.uk">
+        <TopBar.BrandLogo src={logo} />
+        <TopBar.BrandName>Admin Panel</TopBar.BrandName>
+      </TopBar.Brand>
+    </TopBar>
+  )
+}
+```
+
+## TopBar.BrandLogo
+
+`TopBar.BrandLogo` renders an image with set styles and is primarily intended for the Atom logo.
+
+## TopBar.BrandName
+
+`TopBar.BrandName` renders a `Text` component with set styles and is primarily intended to display the name of the current app.
+
+## TopBar.ActionIcon
+
+`TopBar.ActionIcon` extends the base `ActionIcon` component with set props.
+
+Note that instead of needing to include a seperate `Icon` component as children, an icon can be passed directly to this component as a prop.