@atom-learning/components 2.1.0 → 2.3.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/NavigationMenu.mdx

@@ -0,0 +1,113 @@
+---
+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 title="Theme">
+    <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 title="Theme">
+    <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}`}>
+          <Text
+            css={{
+              mb: '0.75rem',
+              textTransform: 'capitalize'
+            }}
+          >
+            {item}
+          </Text>
+          <Text
+            css={{
+              color: 'inherit',
+              lineHeight: 1.5,
+              fontWeight: 400,
+              fontSize: 14
+            }}
+          >
+            This is some example text about {item}
+          </Text>
+        </NavigationMenu.DropdownItem>
+      ))}
+    </NavigationMenu.DropdownContent>
+  </NavigationMenu.Dropdown>
+</NavigationMenu>
+```

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.