aidos-ui 4.0.0 → 4.0.2

package/src/pages/ListHeader.mdx

@@ -2,30 +2,56 @@ import { List } from "../List";
 import { Icon } from "../Icon";
 import { ListItem } from "../ListItem";
 import { ListHeaderItem } from "../ListHeaderItem";
+import { Column } from "../Column";
+import { Span } from "../Text";
 
-# List headers
+# ListHeaderItem
 
-`ListHeaders` have a variety of styles and support both regular and bare styling. They can be used to give contextual information about what a list contains or to visually separate a subgroup of elements.
+A specialized list item for section headers. Use to organize and visually separate groups within a list.
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `headline` | `string` | Required | Header text |
+| `body` | `string` | - | Optional secondary text |
+| `highlight` | `boolean` | `false` | Use accent background color |
+| `addOn` | `ReactNode` | - | Icon or element to display |
+| `addOnPosition` | `Position` | - | Position of the add-on |
+| `withDivider` | `boolean` | - | Show divider below header |
+
+---
+
+## Basic usage
 
 <List ariaLabel="example">
-  <ListHeaderItem headline="Header" />
-  <ListItem headline="Headline 1" body="Body 1" />
-  <ListHeaderItem
-    headline="Header"
-    addOn={<Icon icon="fa-chain-broken" size="medium" color="primary" />}
-  />
-  <ListItem headline="Headline 2" body="Body 2" />
-  <ListHeaderItem highlight headline="Header" />
-  <ListItem headline="Headline 3" body="Body 3" />
-  <ListHeaderItem
-    highlight
-    headline="Header"
-    addOn={<Icon icon="fa-chain-broken" size="medium" color="light" />}
-  />
-  <ListItem withDivider={false} headline="Headline 4" body="Body 3" />
+  <ListHeaderItem headline="Section A" />
+  <ListItem headline="Item 1" body="Description" />
+  <ListItem headline="Item 2" body="Description" />
+  <ListHeaderItem headline="Section B" />
+  <ListItem headline="Item 3" body="Description" />
+  <ListItem withDivider={false} headline="Item 4" body="Description" />
 </List>
 
 ```js
+<List ariaLabel="example">
+  <ListHeaderItem headline="Section A" />
+  <ListItem headline="Item 1" body="Description" />
+  <ListItem headline="Item 2" body="Description" />
+  <ListHeaderItem headline="Section B" />
+  <ListItem headline="Item 3" body="Description" />
+  <ListItem headline="Item 4" body="Description" />
+</List>
+```
+
+---
+
+## Styles
+
+### Standard headers
+
 <List ariaLabel="example">
   <ListHeaderItem headline="Header" />
   <ListItem headline="Headline 1" body="Body 1" />
@@ -43,12 +69,34 @@ import { ListHeaderItem } from "../ListHeaderItem";
   />
   <ListItem withDivider={false} headline="Headline 4" body="Body 3" />
 </List>
+
+```js
+// Plain header
+<ListHeaderItem headline="Header" />
+
+// With icon
+<ListHeaderItem
+  headline="Header"
+  addOn={<Icon icon="fa-chain-broken" size="medium" color="primary" />}
+/>
+
+// Highlighted (accent background)
+<ListHeaderItem highlight headline="Header" />
+
+// Highlighted with icon
+<ListHeaderItem
+  highlight
+  headline="Header"
+  addOn={<Icon icon="fa-chain-broken" size="medium" color="light" />}
+/>
 ```
 
 ---
 
 ## Bare list headers
 
+In bare lists, headers have no background:
+
 <List bare ariaLabel="example">
   <ListHeaderItem headline="Header" />
   <ListItem headline="Headline 1" body="Body 1" />
@@ -70,21 +118,103 @@ import { ListHeaderItem } from "../ListHeaderItem";
 ```js
 <List bare ariaLabel="example">
   <ListHeaderItem headline="Header" />
-  <ListItem headline="Headline 1" body="Body 1" />
+  <ListItem headline="Item" body="Description" />
+
+  {/* Highlighted in bare mode uses highlight text color instead */}
+  <ListHeaderItem highlight headline="Header" />
+  <ListItem headline="Item" body="Description" />
+</List>
+```
+
+---
+
+## With icons
+
+Add context with icons:
+
+```js
+// Category header
+<ListHeaderItem
+  headline="Documents"
+  addOn={<Icon icon="fa-folder" size="medium" color="primary" />}
+/>
+
+// Status header
+<ListHeaderItem
+  headline="Pending"
+  addOn={<Icon icon="fa-clock-o" size="medium" color="warning" />}
+/>
+
+// Alert header (highlighted)
+<ListHeaderItem
+  highlight
+  headline="Urgent"
+  addOn={<Icon icon="fa-exclamation" size="medium" color="light" />}
+/>
+```
+
+---
+
+## Common patterns
+
+### Grouped settings
+
+```js
+<List ariaLabel="Settings">
+  <ListHeaderItem headline="Account" />
+  <ListButtonItem headline="Profile" onClick={() => {}} />
+  <ListButtonItem headline="Password" onClick={() => {}} />
+
+  <ListHeaderItem headline="Preferences" />
+  <ListButtonItem headline="Theme" onClick={() => {}} />
+  <ListButtonItem headline="Language" onClick={() => {}} />
+
+  <ListHeaderItem headline="Danger Zone" highlight />
+  <ListButtonItem headline="Delete Account" color="negative" onClick={() => {}} />
+</List>
+```
+
+### Alphabetical grouping
+
+```js
+<List ariaLabel="Contacts">
+  <ListHeaderItem headline="A" />
+  <ListItem headline="Alice Anderson" />
+  <ListItem headline="Andrew Adams" />
+
+  <ListHeaderItem headline="B" />
+  <ListItem headline="Bob Brown" />
+  <ListItem headline="Betty Baker" />
+</List>
+```
+
+### Category browser
+
+```js
+<List ariaLabel="Categories">
   <ListHeaderItem
-    headline="Header"
-    addOn={<Icon icon="fa-chain-broken" size="medium" color="primary" />}
+    headline="Popular"
+    addOn={<Icon icon="fa-fire" color="warning" />}
   />
-  <ListItem headline="Headline 2" body="Body 2" />
-  <ListHeaderItem highlight headline="Header" />
-  <ListItem headline="Headline 3" body="Body 3" />
+  <ListButtonItem headline="Technology" onClick={() => {}} />
+  <ListButtonItem headline="Design" onClick={() => {}} />
+
   <ListHeaderItem
-    highlight
-    headline="Header"
-    addOn={<Icon icon="fa-chain-broken" size="medium" color="light" />}
+    headline="Recent"
+    addOn={<Icon icon="fa-clock-o" color="secondary" />}
   />
-  <ListItem withDivider={false} headline="Headline 4" body="Body 3" />
+  <ListButtonItem headline="Science" onClick={() => {}} />
+  <ListButtonItem headline="Art" onClick={() => {}} />
 </List>
 ```
 
 ---
+
+## Styling behavior
+
+| Context | Standard Header | Highlighted Header |
+|---------|----------------|-------------------|
+| Regular list | Gray background | Accent background |
+| Bare list | No background | Accent text color |
+
+The component automatically adapts based on the parent list's `bare` prop.

package/src/pages/Popover.mdx

@@ -3,99 +3,221 @@ import { Icon } from "../Icon";
 import { Button } from "../Button";
 import { List } from "../List";
 import { ListButtonItem } from "../ListButtonItem";
+import { Row } from "../Row";
+import { Column } from "../Column";
 
 # Popover
 
-The `Popover` component can be used in conjunction with the `PopoverTrigger` component to create modal experiences:
+A floating panel that appears next to a trigger element. Unlike tooltips, popovers can contain interactive content like menus, forms, or action lists.
 
+---
+
+## Props
+
+### PopoverTrigger
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `PopoverComponent` | `(props: { close: () => void } & Input) => JSX.Element` | Yes | Component to render in the popover |
+| `children` | `(props: { toggle: (input: Input) => void }) => JSX.Element` | Yes | Render function for the trigger element |
+| `jss` | `JSS` | No | Custom styles for the wrapper |
+| `jssDialog` | `JSS` | No | Custom styles for the popover dialog |
+| `grow` | `boolean` | No | Allow wrapper to grow |
+| `shrink` | `boolean` | No | Allow wrapper to shrink |
+| `tag` | `keyof HTMLElementTagNameMap` | No | HTML tag for the wrapper |
+
+### Popover
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `ReactNode` | Yes | Popover content |
+| `close` | `() => void` | Yes | Function to close the popover |
+
+---
+
+## Basic usage
+
+Use `PopoverTrigger` to create a button that opens a popover with interactive options:
+
+<Row padding="large">
+  <PopoverTrigger
+    PopoverComponent={({ close }) => (
+      <Popover close={close}>
+        <List bare ariaLabel="Options">
+          <ListButtonItem bare headline="Edit" onClick={() => close()} color="secondary" />
+          <ListButtonItem bare headline="Duplicate" onClick={() => close()} color="secondary" />
+          <ListButtonItem bare headline="Delete" onClick={() => close()} color="negative" withDivider={false} />
+        </List>
+      </Popover>
+    )}
+  >
+    {({ toggle }) => (
+      <Button color="positive" onClick={() => toggle(undefined)}>
+        Show Options
+      </Button>
+    )}
+  </PopoverTrigger>
+</Row>
+
+```js
 <PopoverTrigger
   PopoverComponent={({ close }) => (
     <Popover close={close}>
-      <List bare ariaLabel="Popover" autofocus>
+      <List bare ariaLabel="Options">
         <ListButtonItem
           bare
-          headline="Option 1"
-          onClick={() => {
-            close();
-          }}
+          headline="Edit"
+          onClick={() => close()}
           color="secondary"
         />
         <ListButtonItem
           bare
-          headline="Option 2"
-          onClick={() => {
-            close();
-          }}
+          headline="Duplicate"
+          onClick={() => close()}
           color="secondary"
         />
         <ListButtonItem
           bare
-          headline="Option 3"
-          onClick={() => {
-            close();
-          }}
-          color="secondary"
+          headline="Delete"
+          onClick={() => close()}
+          color="negative"
           withDivider={false}
         />
       </List>
     </Popover>
   )}
+>
+  {({ toggle }) => (
+    <Button color="positive" onClick={() => toggle(undefined)}>
+      Show Options
+    </Button>
+  )}
+</PopoverTrigger>
+```
+
+---
+
+## Passing data to popover
+
+Use TypeScript generics to pass data when opening the popover:
+
+```js
+interface Item {
+  id: string;
+  name: string;
+}
+
+<PopoverTrigger<Item>
+  PopoverComponent={({ close, id, name }) => (
+    <Popover close={close}>
+      <Column padding="medium" gap="small">
+        <P>Edit: {name}</P>
+        <Button color="positive" onClick={() => {
+          saveItem(id);
+          close();
+        }}>
+          Save
+        </Button>
+      </Column>
+    </Popover>
+  )}
 >
   {({ toggle }) => (
     <Button
-      style={{ position: "relative" }}
-      label="Popover trigger"
-      color="positive"
-      onClick={() => {
-        toggle(undefined);
-      }}
-    />
+      color="primary"
+      onClick={() => toggle({ id: "123", name: "My Item" })}
+    >
+      Edit Item
+    </Button>
   )}
 </PopoverTrigger>
+```
+
+---
+
+## Behavior
+
+- **Toggle on click**: Clicking the trigger opens/closes the popover
+- **Focus management**: Focus moves into the popover when opened
+- **Focus trap**: Tab cycles through focusable elements within the popover
+- **Escape to close**: Pressing Escape closes the popover
+- **Outside click**: Clicking outside closes the popover
+- **Focus restoration**: Focus returns to the trigger when closed
+
+---
+
+## Common patterns
+
+### Dropdown menu
 
 ```js
 <PopoverTrigger
   PopoverComponent={({ close }) => (
     <Popover close={close}>
-      <List bare ariaLabel="Popover" autofocus>
-        <ListButtonItem
-          bare
-          headline="Option 1"
-          onClick={() => {
-            close();
-          }}
-          color="secondary"
-        />
-        <ListButtonItem
-          bare
-          headline="Option 2"
-          onClick={() => {
-            close();
-          }}
-          color="secondary"
-        />
-        <ListButtonItem
-          bare
-          headline="Option 3"
-          onClick={() => {
-            close();
-          }}
-          color="secondary"
-          withDivider={false}
-        />
+      <List bare ariaLabel="Menu">
+        <ListButtonItem bare headline="Profile" onClick={() => close()} />
+        <ListButtonItem bare headline="Settings" onClick={() => close()} />
+        <ListButtonItem bare headline="Logout" onClick={() => close()} color="negative" />
       </List>
     </Popover>
   )}
 >
   {({ toggle }) => (
-    <Button
-      style={{ position: "relative" }}
-      label="Popover trigger"
-      color="positive"
-      onClick={() => {
-        toggle(undefined);
-      }}
+    <IconButton
+      bare
+      icon="fa-ellipsis-v"
+      size="medium"
+      color="secondary"
+      onClick={() => toggle(undefined)}
     />
   )}
 </PopoverTrigger>
 ```
+
+### Action confirmation
+
+```js
+<PopoverTrigger
+  PopoverComponent={({ close }) => (
+    <Popover close={close}>
+      <Column padding="medium" gap="medium">
+        <P>Are you sure you want to delete?</P>
+        <Row gap="small" justify="end">
+          <Button bare color="primary" onClick={close}>Cancel</Button>
+          <Button color="negative" onClick={() => {
+            deleteItem();
+            close();
+          }}>Delete</Button>
+        </Row>
+      </Column>
+    </Popover>
+  )}
+>
+  {({ toggle }) => (
+    <Button color="negative" onClick={() => toggle(undefined)}>
+      Delete
+    </Button>
+  )}
+</PopoverTrigger>
+```
+
+---
+
+## Accessibility
+
+- Uses `<dialog>` element with `.show()` for proper popover behavior
+- Focus is trapped within the popover
+- Escape key closes the popover
+- Focus returns to the trigger when closed
+- Tab navigation cycles through focusable elements
+
+---
+
+## Popover vs Dialog vs Tooltip
+
+| Popover | Dialog | Tooltip |
+|---------|--------|---------|
+| Positioned near trigger | Centered on screen | Positioned near trigger |
+| Light interactions | Complex workflows | Text only |
+| Partial page blocking | Full page blocking | No blocking |
+| Menus, quick actions | Forms, confirmations | Hints, labels |