@atom-learning/components 2.28.0-beta.0 → 2.28.0

package/dist/docs/Accordion.mdx

@@ -5,29 +5,23 @@ description: A vertically stacked group of interactive headings that reveal an a
 category: Layout
 ---
 
-Functionality based on the [`Accordion`](https://radix-ui.com/primitives/docs/components/accordion) radix component.
-
-Implements experimental ColorScheme component to allow multiple colour setups.
-
 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>Accordion Header 1</Accordion.Trigger>
-    <Accordion.Content css={{ p: '$3' }}>
-      <Text>Accordion content 1</Text>
-    </Accordion.Content>
+    <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: '$3' }}>
-      <Text>Accordion content 2</Text>
-    </Accordion.Content>
+    <Accordion.Content css={{ p: '$4' }}>Accordion content 2</Accordion.Content>
   </Accordion.Item>
 </Accordion>
 ```
@@ -46,49 +40,6 @@ Accordions can have `type` as either `single` or `multiple`. This changes how ma
 
 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']}`
 
-## Disabled
+## Themes
 
-An `Accordion.Item` component can take a `disabled` prop, which would make it untoggleable.
-The corresponding `Accordion.Content` component's content will be, in this case, permanently in its original state.
-
-```tsx preview live
-<Accordion type="single" defaultValue="1">
-  <Accordion.Item value="1" disabled>
-    <Accordion.Trigger>Accordion Header 1</Accordion.Trigger>
-    <Accordion.Content css={{ p: '$3' }}>
-      <Text>Accordion content 1</Text>
-    </Accordion.Content>
-  </Accordion.Item>
-  <Accordion.Item value="2">
-    <Accordion.Trigger>Accordion Header 2</Accordion.Trigger>
-    <Accordion.Content css={{ p: '$3' }}>
-      <Text>Accordion content 2</Text>
-    </Accordion.Content>
-  </Accordion.Item>
-</Accordion>
-```
-
-## Color Scheme
-
-You can pass in a `colorScheme` object to the Accordion.Trigger to customise the colours of the component.
-Defaults to `{ accent: "slate", interactive: "loContrast1"}`
-ColorScheme is experimental and has been implemented only locally but you can read more about how it
-currently works and available options [on the repository's github](https://github.com/Atom-Learning/components/tree/main/color-scheme#readme).
-
-```tsx preview live
-<Accordion type="single" defaultValue="1">
-  <Accordion.Item value="1">
-    <Accordion.Trigger
-      colorScheme={{
-        accent: 'blue',
-        interactive: 'hiContrast2'
-      }}
-    >
-      Accordion Header 1
-    </Accordion.Trigger>
-    <Accordion.Content css={{ p: '$3' }}>
-      <Text>Accordion content 1</Text>
-    </Accordion.Content>
-  </Accordion.Item>
-</Accordion>
-```
+`Accordion.Trigger` can have a `theme` property. Possible values are `primaryDark` and `light`. The default is `primaryDark`.

package/dist/docs/DataTable.mdx

@@ -15,7 +15,7 @@ The root `DataTable` component manages the table's state and exposes it via the
 
 Other `DataTable` components call `useDataTable` and provide useful default implementations for common patterns. For example, `DataTable.Head` will render a header for every column defined in the parent `DataTable`. `DataTable.Body` will render a row for every data item. `DataTable.Table` combines both `DataTable.Head` and `DataTable.Body`.
 
-### Using defaults vs using rolling your own
+### Using defaults vs rolling your own
 
 Here's a simple config for some table data and columns.
 
@@ -241,3 +241,39 @@ If `DataTable`'s `isSortable` state is `true`, then `DataTable.Header` will be c
 ### Pagination
 
 `DataTable.Pagination` can be passed as a child to `DataTable` to render the pagination UI and configure the parent `DataTable` to paginate its data. Note: there is currently a bug where `DataTable` will render all rows on the initial render, even when paginated. There is no visible effect, but it can cause performance issues on large tables. The workaround for this is to pass an `initialState` prop to `DataTable`. E.g. `initialState={pagination: {pageSize: 5, pageIndex: 0}}`. This will force pagination to apply properly on the initial render. Make sure the `pagination` prop matches the config you use in `DataTable.Pagination`, as the latter will take precedence after the initial render.
+
+### Drag and drop
+
+The `DataTable.DragAndDropTable` can be rendered in place of `DataTable.Table` to allow users to reorder table rows via drag and drop. It takes an optional `onDragAndDrop` prop which is a function that fires when rows have been re-ordered via drag-and-drop. Use this to sync those changes with external data sources.
+
+Note that column sorting conflicts with drag and drop behaviour. In any context where you allow drag and drop reordering, you probably want to disable column sorting (see User Sorting above). Similarly, you should probably disable pagination because users won't be able to drag rows across page boundaries.
+
+#### Row IDs
+
+Drag-and-drop functionality relies on each table row having a unique ID. `DataTable.DragAndDropContainer` will throw an error if your don't provide unique IDs for each row in the `data` provided to `DataTable`, so you should consider wrapping your table in an `ErrorBoundary` to reduce the impact on your user if there is a problem with your data. By default, `DataTable.DragAndDropContainer` will look for this id in an `id` property on each object in `data`. You can use the `idColumn` prop to provide the name of a different property, e.g. `userId`, that already exists on your data so that you don't have to generate new IDs just for the table. For example, you could provide data like this with no additional configuration:
+
+```tsx
+const data = [
+  { name: 'chrissy', hobby: 'bare-knuckle boxing', id: 1 },
+  { name: 'agatha', hobby: 'crossfit', id: 2 },
+  { name: 'betty', hobby: 'acting', id: 3 }
+]`
+
+<DataTable data={data} columns={columns}>
+  <DataTable.DragAndDropTable onDragAndDrop={(oldIndex, newIndex, newData) => console.log(oldIndex, newIndex, newData)}/>
+</DataTable>
+```
+
+Or you could provide this data and specify the id column accordingly:
+
+```tsx
+const data = [
+  { name: 'chrissy', hobby: 'bare-knuckle boxing', userId: 1 },
+  { name: 'agatha', hobby: 'crossfit', userId: 2 },
+  { name: 'betty', hobby: 'acting', userId: 3 }
+]`
+
+<DataTable data={data} columns={columns}>
+  <DataTable.DragAndDropTable idColumn="userId" onDragAndDrop={(oldIndex, newIndex, newData) => console.log(oldIndex, newIndex, newData)} />
+</DataTable>
+```

package/dist/docs/Tabs.mdx

@@ -5,12 +5,10 @@ description: Tabs is a component that provides different sections of content tha
 category: Layout
 ---
 
-Functionality based on the [`Tab`](https://www.radix-ui.com/docs/primitives/components/tabs) radix component, which already allows for: controlled/uncontrolled tabbing, disabling or partly disabling options, adds keyboard navigation and orientation and more.
-
-Implements experimental ColorScheme component to allow multiple colour setups.
+The component provides a set of default styles, which can be overwritten by using the `css` prop. It is composed by combining smaller components, such as `Tabs.TriggerList`, `Tabs.Trigger`, and `Tabs.Content`.
 
 ```tsx preview
-<Tabs defaultValue="tab2">
+<Tabs defaultValue="tab1" css={{ height: '100px' }}>
   <Tabs.TriggerList>
     <Tabs.Trigger value="tab1">
       Nested component under the Tabs.Trigger component
@@ -29,48 +27,76 @@ Implements experimental ColorScheme component to allow multiple colour setups.
 </Tabs>
 ```
 
-## Disabled
+It takes a `defaultValue` prop that should match one of the triggers' `value` prop.
+
+```tsx
+<Tabs defaultValue="tab1">
+```
+
+It also takes a `theme` prop that should either be "light" or "dark".
+
+```tsx
+<Tabs theme="light"></Tabs>
+<Tabs theme="dark"></Tabs>
+```
+
+## Tabs.TriggerList
+
+The `Tabs.TriggerList` component simply holds the individual `Tabs.Trigger` components. It can also get custom styling via the `css` prop.
+`Tabs.TriggerList` will automatically show `<` & `>` buttons in case the content is overshooting the available space.
 
-A `Tabs.Trigger` component can take a `disabled` prop, which would make it unselectable.
-The corresponding `Tabs.Content` component's content will be, in this case, permanently hidden.
+The default scroll amount for the scroll buttons on the `Tabs.TriggerList` is 10% of the content width. You can set this to any percentage by setting, for example, `scrollPercentage={25}`.
+
+## Tabs.Trigger
+
+The `Tabs.Trigger` component holds the content that will be displayed inside the button that the user would click in order to switch tabs. In can hold either a string, or some other component. It needs to be passed a `value` prop, that would be identical to the `value` prop passed to its corresponding `Tabs.Content` component.
+
+## Tabs.Content
+
+The `Tabs.Content` component, as the name suggests, holds the content for that particular section of the tabs component. It takes a `value` prop that needs to match the `value` prop passed to its corresponding trigger. Its content can be any text or valid component.
+
+## Disabled tab
+
+A `Tabs.Trigger` component can take a `disabled` prop, which would make it unselectable. The corresponding `Tabs.Content` component's content will be, in this case, permanently hidden.
 
 ```tsx preview
-<Tabs defaultValue="tab1">
+<Tabs>
   <Tabs.TriggerList>
     <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
-    <Tabs.Trigger value="tab2" disabled>
+    <Tabs.Trigger disabled value="tab2">
       Tab 2
     </Tabs.Trigger>
   </Tabs.TriggerList>
-  <Tabs.Content css={{ p: '$3' }} value="tab1">
-    <Text>Content for tab1.</Text>
-  </Tabs.Content>
-  <Tabs.Content css={{ p: '$3' }} value="tab2">
-    <Text>Content for tab2.</Text>
-  </Tabs.Content>
+  <Tabs.Content value="tab1">Content for tab 1</Tabs.Content>
+  <Tabs.Content value="tab2">Content for the second tab.</Tabs.Content>
 </Tabs>
 ```
 
-## Color Scheme
+## Styling the `Tabs.TriggerList`
 
-You can pass in a `colorScheme` object to the TriggerList to customise the colours of the component.
-Defaults to `{ base: "slate", accent: "blue", interactive: "hiContrast1"}`
-ColorScheme is experimental and has been implemented only locally but you can read more about how it
-currently works and available options [on the repository's github](https://github.com/Atom-Learning/components/tree/main/color-scheme#readme).
+The trigger list accepts an appearance property to apply uppercase to all tabs. Simply pass `appearance='uppercase'`.
 
-```tsx preview live
-<Tabs defaultValue="tab2">
-  <Tabs.TriggerList
-    colorScheme={{ base: 'slate', accent: 'slate', interactive: 'hiContrast2' }}
-  >
+```tsx preview
+<Tabs>
+  <Tabs.TriggerList appearance="uppercase">
     <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
     <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
   </Tabs.TriggerList>
-  <Tabs.Content css={{ p: '$3' }} value="tab1">
-    <Text>Content for tab1.</Text>
-  </Tabs.Content>
-  <Tabs.Content css={{ p: '$3' }} value="tab2">
-    <Text>Content for tab2.</Text>
-  </Tabs.Content>
+  <Tabs.Content value="tab1">Content for tab 1</Tabs.Content>
+  <Tabs.Content value="tab2">Content for the second tab.</Tabs.Content>
 </Tabs>
 ```
+
+## Styling the `Tabs.Trigger`
+
+In order to style the different states of a trigger, the following CSS selectors need to be used when passed to the `css` prop:
+
+`&:hover` to style the hover state of the trigger.
+
+`&[data-disabled]` to style a disabled trigger.
+
+`&[data-disabled]:hover` to style a disabled trigger's hover state.
+
+`&[data-state="active"]` to style an active trigger.
+
+If the content of the trigger is, say, a `<Text>` component instead of a string, you can append the `*` symbol or any other child/sibling selectors, to make sure that any nested content is styled accordingly. You can also simply style the nested child component directly via its own `css` prop.