@duro-app/ui 0.20.1 → 0.22.0

package/src/components/List/List.stories.tsx

@@ -0,0 +1,200 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {useState} from 'react'
+import {expect} from 'storybook/test'
+import {css, html} from 'react-strict-dom'
+import {List} from './List'
+import {Badge} from '../Badge/Badge'
+import {Button} from '../Button/Button'
+import {Checkbox} from '../Checkbox/Checkbox'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+
+const meta: Meta = {
+  title: 'Components/List',
+  argTypes: {
+    selectionMode: {
+      control: 'select',
+      options: ['none', 'single', 'multiple'],
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj
+
+// --- Default ---
+
+export const Default: Story = {
+  render: () => (
+    <List.Root aria-label="Services">
+      <List.Item>
+        <List.Content>
+          <List.Text>Traefik</List.Text>
+          <List.Description>Reverse proxy · Port 443</List.Description>
+        </List.Content>
+        <List.Actions>
+          <Badge variant="success" size="sm">Running</Badge>
+        </List.Actions>
+      </List.Item>
+      <List.Item>
+        <List.Content>
+          <List.Text>Nginx</List.Text>
+          <List.Description>Web server · Port 80</List.Description>
+        </List.Content>
+        <List.Actions>
+          <Badge variant="success" size="sm">Running</Badge>
+        </List.Actions>
+      </List.Item>
+      <List.Item>
+        <List.Content>
+          <List.Text>Pi-hole</List.Text>
+          <List.Description>DNS filter · Port 53</List.Description>
+        </List.Content>
+        <List.Actions>
+          <Badge variant="default" size="sm">Stopped</Badge>
+        </List.Actions>
+      </List.Item>
+    </List.Root>
+  ),
+  play: async ({canvas}) => {
+    const list = canvas.getByRole('list')
+    await expect(list).toBeInTheDocument()
+    await expect(canvas.getAllByRole('listitem').length).toBe(3)
+  },
+}
+
+// --- With Selection ---
+
+const narrowContainer = css.create({
+  box: {
+    maxWidth: 360,
+    borderWidth: 1,
+    borderStyle: 'solid',
+    borderColor: colors.border,
+    borderRadius: 8,
+    overflow: 'hidden',
+  },
+})
+
+function SelectionDemo() {
+  const certs = [
+    {id: 'c1', serial: 'aa:bb:cc:dd:01', issued: 'Mar 21, 2026', expires: 'Jun 19, 2026', status: 'active' as const},
+    {id: 'c2', serial: 'aa:bb:cc:dd:02', issued: 'Mar 21, 2026', expires: 'Jun 19, 2026', status: 'active' as const},
+    {id: 'c3', serial: 'ee:ff:00:11:03', issued: 'Jan 10, 2025', expires: 'Jan 10, 2026', status: 'expired' as const},
+  ]
+
+  const [selected, setSelected] = useState<Set<string>>(new Set())
+
+  const toggle = (id: string) => {
+    setSelected((prev) => {
+      const next = new Set(prev)
+      if (next.has(id)) next.delete(id)
+      else next.add(id)
+      return next
+    })
+  }
+
+  return (
+    <html.div style={narrowContainer.box}>
+      <List.Root selectionMode="multiple" aria-label="Certificates">
+        {certs.map((cert) => (
+          <List.Item
+            key={cert.id}
+            selected={selected.has(cert.id)}
+            onClick={() => cert.status === 'active' && toggle(cert.id)}
+            disabled={cert.status !== 'active'}
+          >
+            {cert.status === 'active' && (
+              <Checkbox
+                checked={selected.has(cert.id)}
+                onChange={() => toggle(cert.id)}
+                aria-label={cert.serial}
+              />
+            )}
+            <List.Content>
+              <List.Text>{cert.serial}</List.Text>
+              <List.Description>
+                Issued: {cert.issued} · Expires: {cert.expires}
+              </List.Description>
+            </List.Content>
+            <List.Actions>
+              <Badge
+                variant={cert.status === 'active' ? 'success' : 'default'}
+                size="sm"
+              >
+                {cert.status}
+              </Badge>
+              {cert.status === 'active' && (
+                <Button variant="danger" size="small">
+                  Revoke
+                </Button>
+              )}
+            </List.Actions>
+          </List.Item>
+        ))}
+      </List.Root>
+    </html.div>
+  )
+}
+
+export const WithSelection: Story = {
+  render: () => <SelectionDemo />,
+  play: async ({canvas}) => {
+    const checkboxes = canvas.getAllByRole('checkbox')
+    await expect(checkboxes.length).toBe(2)
+  },
+}
+
+// --- Empty State ---
+
+export const EmptyState: Story = {
+  render: () => (
+    <html.div style={narrowContainer.box}>
+      <List.Root aria-label="Empty list">
+        <List.Empty>No items found.</List.Empty>
+      </List.Root>
+    </html.div>
+  ),
+}
+
+// --- In Detail Panel context (360px) ---
+
+function DetailPanelDemo() {
+  const users = [
+    {id: '1', name: 'Alice Johnson', email: 'alice@example.com', role: 'Admin', status: 'Active'},
+    {id: '2', name: 'Bob Smith', email: 'bob@example.com', role: 'Editor', status: 'Active'},
+    {id: '3', name: 'Carol Davis', email: 'carol@example.com', role: 'Viewer', status: 'Inactive'},
+  ]
+
+  const [selectedId, setSelectedId] = useState<string | null>(null)
+
+  return (
+    <html.div style={narrowContainer.box}>
+      <List.Root selectionMode="single" aria-label="Users">
+        {users.map((user) => (
+          <List.Item
+            key={user.id}
+            selected={selectedId === user.id}
+            onClick={() => setSelectedId(selectedId === user.id ? null : user.id)}
+          >
+            <List.Content>
+              <List.Text>{user.name}</List.Text>
+              <List.Description>{user.email} · {user.role}</List.Description>
+            </List.Content>
+            <List.Actions>
+              <Badge
+                variant={user.status === 'Active' ? 'success' : 'default'}
+                size="sm"
+              >
+                {user.status}
+              </Badge>
+            </List.Actions>
+          </List.Item>
+        ))}
+      </List.Root>
+    </html.div>
+  )
+}
+
+export const SingleSelection: Story = {
+  render: () => <DetailPanelDemo />,
+}

package/src/components/List/List.tsx

@@ -0,0 +1,118 @@
+import {type ReactNode, createContext, useContext} from 'react'
+import {html} from 'react-strict-dom'
+import {styles} from './styles.css'
+
+// --- Types ---
+
+export type ListSelectionMode = 'none' | 'single' | 'multiple'
+
+// --- Context ---
+
+interface ListContextValue {
+  selectionMode: ListSelectionMode
+}
+
+const ListContext = createContext<ListContextValue>({selectionMode: 'none'})
+
+function useList() {
+  return useContext(ListContext)
+}
+
+// --- Root ---
+
+interface RootProps {
+  children: ReactNode
+  /** Selection mode: 'none' (default), 'single', or 'multiple' */
+  selectionMode?: ListSelectionMode
+  /** Accessible label for the list */
+  'aria-label'?: string
+}
+
+function Root({children, selectionMode = 'none', 'aria-label': ariaLabel}: RootProps) {
+  return (
+    <ListContext.Provider value={{selectionMode}}>
+      <html.div role="list" aria-label={ariaLabel} style={styles.root}>
+        {children}
+      </html.div>
+    </ListContext.Provider>
+  )
+}
+
+// --- Item ---
+
+interface ItemProps {
+  children: ReactNode
+  /** Whether this item is selected */
+  selected?: boolean
+  /** Whether this item is disabled */
+  disabled?: boolean
+  /** Click handler for the item */
+  onClick?: () => void
+}
+
+function Item({children, selected, disabled, onClick}: ItemProps) {
+  const {selectionMode} = useList()
+  const isSelectable = selectionMode !== 'none'
+
+  return (
+    <html.div
+      role="listitem"
+      aria-selected={isSelectable ? selected : undefined}
+      aria-disabled={disabled || undefined}
+      onClick={disabled ? undefined : onClick}
+      style={[
+        styles.item,
+        selected && styles.itemSelected,
+        disabled && styles.itemDisabled,
+      ]}
+    >
+      {children}
+    </html.div>
+  )
+}
+
+// --- Content: wraps primary text + description ---
+
+function Content({children}: {children: ReactNode}) {
+  return <html.div style={styles.content}>{children}</html.div>
+}
+
+// --- Text: primary label ---
+
+function ItemText({children}: {children: ReactNode}) {
+  return <html.p style={styles.text}>{children}</html.p>
+}
+
+// --- Description: secondary text ---
+
+function Description({children}: {children: ReactNode}) {
+  return <html.p style={styles.description}>{children}</html.p>
+}
+
+// --- Actions: slot for buttons, badges, etc. ---
+
+function Actions({children}: {children: ReactNode}) {
+  return <html.div style={styles.actions}>{children}</html.div>
+}
+
+// --- Empty: placeholder when list has no items ---
+
+function Empty({children}: {children: ReactNode}) {
+  return (
+    <html.div role="listitem" style={styles.empty}>
+      {children}
+    </html.div>
+  )
+}
+
+// --- Export ---
+
+export const List = {
+  Root,
+  Item,
+  Content,
+  Text: ItemText,
+  Description,
+  Actions,
+  Empty,
+}

package/src/components/List/styles.css.ts

@@ -0,0 +1,99 @@
+import {css} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {typography} from '@duro-app/tokens/tokens/typography.css'
+
+export const styles = css.create({
+  // --- Root ---
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    margin: 0,
+    padding: 0,
+  },
+
+  // --- Item ---
+  item: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacing.sm,
+    paddingTop: spacing.sm,
+    paddingBottom: spacing.sm,
+    paddingLeft: spacing.ms,
+    paddingRight: spacing.ms,
+    borderBottomWidth: 1,
+    borderBottomStyle: 'solid',
+    borderBottomColor: colors.border,
+    backgroundColor: {
+      default: 'transparent',
+      ':hover': colors.bgCardHover,
+    },
+    transitionProperty: 'background-color',
+    transitionDuration: '120ms',
+    cursor: 'default',
+  },
+  itemSelected: {
+    backgroundColor: {
+      default: colors.bgCardHover,
+      ':hover': colors.bgCardHover,
+    },
+  },
+  itemDisabled: {
+    opacity: 0.5,
+    pointerEvents: 'none',
+  },
+  itemLast: {
+    borderBottomWidth: 0,
+  },
+
+  // --- Item content area (text + description) ---
+  content: {
+    flex: 1,
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 2,
+    minWidth: 0,
+  },
+
+  // --- Primary text ---
+  text: {
+    fontSize: typography.fontSizeSm,
+    fontWeight: typography.fontWeightMedium,
+    lineHeight: typography.lineHeight,
+    color: colors.text,
+    margin: 0,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  },
+
+  // --- Description text ---
+  description: {
+    fontSize: typography.fontSizeXs,
+    lineHeight: typography.lineHeight,
+    color: colors.textMuted,
+    margin: 0,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  },
+
+  // --- Actions slot ---
+  actions: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacing.xs,
+    flexShrink: 0,
+  },
+
+  // --- Empty state ---
+  empty: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingTop: spacing.xl,
+    paddingBottom: spacing.xl,
+    color: colors.textMuted,
+    fontSize: typography.fontSizeSm,
+  },
+})

package/src/components/Panel/Panel.meta.ts

@@ -18,9 +18,18 @@ export const meta: ComponentMeta = {
     optional: ['Root', 'Header', 'Body', 'Footer'],
   },
   relatedTo: [
-    {component: 'Card', relationship: 'Card is for shallow, repeated items; Panel is for deep, organized content'},
-    {component: 'DetailPanel', relationship: 'DetailPanel uses Panel internally for its structural layout'},
-    {component: 'PageShell', relationship: 'PageShell is for page-level layout; Panel is for section-level'},
+    {
+      component: 'Card',
+      relationship: 'Card is for shallow, repeated items; Panel is for deep, organized content',
+    },
+    {
+      component: 'DetailPanel',
+      relationship: 'DetailPanel uses Panel internally for its structural layout',
+    },
+    {
+      component: 'PageShell',
+      relationship: 'PageShell is for page-level layout; Panel is for section-level',
+    },
   ],
   example: `<Panel.Root bordered>
   <Panel.Header>

package/src/components/Panel/Panel.stories.tsx

@@ -10,6 +10,12 @@ import {Input} from '../Input/Input'
 
 const meta: Meta = {
   title: 'Components/Panel',
+  argTypes: {
+    bordered: {
+      control: 'boolean',
+      description: 'Whether the panel has an outer border for visual separation',
+    },
+  },
 }
 
 export default meta
@@ -25,9 +31,8 @@ export const Default: Story = {
       </Panel.Header>
       <Panel.Body>
         <Text>
-          Panel is a structural primitive for grouping content with
-          header, body, and footer slots. It fills the gap between Card
-          and page-level layout.
+          Panel is a structural primitive for grouping content with header, body, and footer slots.
+          It fills the gap between Card and page-level layout.
         </Text>
       </Panel.Body>
       <Panel.Footer>
@@ -45,12 +50,14 @@ export const Bordered: Story = {
     <Panel.Root bordered>
       <Panel.Header>
         <Heading level={3}>Bordered Panel</Heading>
-        <Button variant="secondary" size="small">Action</Button>
+        <Button variant="secondary" size="small">
+          Action
+        </Button>
       </Panel.Header>
       <Panel.Body>
         <Text>
-          The bordered variant adds an outer border, useful when the panel
-          needs visual separation from its surroundings.
+          The bordered variant adds an outer border, useful when the panel needs visual separation
+          from its surroundings.
         </Text>
       </Panel.Body>
       <Panel.Footer>
@@ -67,8 +74,8 @@ export const BodyOnly: Story = {
     <Panel.Root bordered>
       <Panel.Body>
         <Text>
-          Panel sub-components can be used independently. This panel only
-          has a Body — no Header or Footer.
+          Panel sub-components can be used independently. This panel only has a Body — no Header or
+          Footer.
         </Text>
       </Panel.Body>
     </Panel.Root>
@@ -85,8 +92,8 @@ export const UnpaddedBody: Story = {
       </Panel.Header>
       <Panel.Body padded={false}>
         <Text>
-          Setting padded=false removes body padding, useful for content
-          that needs to extend edge-to-edge (tables, images, etc).
+          Setting padded=false removes body padding, useful for content that needs to extend
+          edge-to-edge (tables, images, etc).
         </Text>
       </Panel.Body>
     </Panel.Root>

package/src/components/Panel/Panel.tsx

@@ -11,11 +11,7 @@ interface RootProps {
 }
 
 function Root({children, bordered = false}: RootProps) {
-  return (
-    <html.div style={[styles.root, bordered && styles.bordered]}>
-      {children}
-    </html.div>
-  )
+  return <html.div style={[styles.root, bordered && styles.bordered]}>{children}</html.div>
 }
 
 // --- Header ---
@@ -33,11 +29,7 @@ interface BodyProps {
 }
 
 function Body({children, padded = true}: BodyProps) {
-  return (
-    <html.div style={[styles.body, padded && styles.bodyPadded]}>
-      {children}
-    </html.div>
-  )
+  return <html.div style={[styles.body, padded && styles.bodyPadded]}>{children}</html.div>
 }
 
 // --- Footer ---

package/src/components/Panel/styles.css.ts

@@ -31,6 +31,11 @@ export const styles = css.create({
   body: {
     flex: 1,
     overflowY: 'auto',
+    // Minimal inset prevents child borders from touching panel structural borders
+    paddingTop: spacing.sm,
+    paddingBottom: spacing.sm,
+    paddingLeft: spacing.sm,
+    paddingRight: spacing.sm,
   },
   bodyPadded: {
     paddingTop: spacing.lg,

package/src/components/Spinner/Spinner.meta.ts

@@ -0,0 +1,19 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Animated loading indicator. Use while content is being fetched or an action is processing. Always provide a label for accessibility.',
+  whenToUse: [
+    'Page or section loading states',
+    'Button loading states (inside a button)',
+    'Async operation feedback',
+  ],
+  whenNotToUse: [
+    'Skeleton loading — use placeholder skeleton patterns',
+    'Progress with known completion — use a progress bar',
+  ],
+  example: `<Stack gap="md" align="center">
+  <Spinner size="lg" label="Loading data..." />
+  <Button disabled><Spinner size="sm" /> Saving...</Button>
+</Stack>`,
+}

package/src/components/StatusIcon/StatusIcon.meta.ts

@@ -0,0 +1,24 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Icon with a colored background circle. Combines an Icon with a status-colored container for visual emphasis. Use for status indicators in dashboards or lists.',
+  whenToUse: [
+    'Dashboard status indicators',
+    'List item status icons with colored backgrounds',
+    'Feature or capability indicators',
+  ],
+  whenNotToUse: [
+    'Inline icons without background — use Icon',
+    'Status text labels — use Badge',
+  ],
+  relatedTo: [
+    {component: 'Icon', relationship: 'StatusIcon wraps Icon with background; Icon is bare SVG'},
+    {component: 'Badge', relationship: 'Badge for text status; StatusIcon for icon status'},
+  ],
+  example: `<Inline gap="md">
+  <StatusIcon name="check-circle" variant="success" size="md" />
+  <StatusIcon name="alert-triangle" variant="warning" size="md" />
+  <StatusIcon name="x-circle" variant="error" size="md" />
+</Inline>`,
+}

package/src/components/Table/Table.stories.tsx

@@ -11,6 +11,22 @@ import {colors} from '@duro-app/tokens/tokens/colors.css'
 
 const meta: Meta = {
   title: 'Components/Table',
+  argTypes: {
+    columns: {
+      control: 'number',
+      description: 'Number of columns in the table grid',
+    },
+    variant: {
+      control: 'select',
+      options: ['default', 'striped', 'bordered'],
+      description: 'Visual style variant of the table',
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+      description: 'Density/size of table rows',
+    },
+  },
 }
 
 export default meta

package/src/components/Tabs/Tabs.stories.tsx

@@ -4,6 +4,13 @@ import {Tabs} from './Tabs'
 
 const meta: Meta = {
   title: 'Components/Tabs',
+  argTypes: {
+    orientation: {
+      control: 'select',
+      options: ['horizontal', 'vertical'],
+      description: 'Layout orientation of the tab list',
+    },
+  },
 }
 
 export default meta

package/src/components/Text/Text.meta.ts

@@ -0,0 +1,23 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Body and label typography component. Renders a span or paragraph with design system typography presets. Use for all non-heading text content.',
+  whenToUse: [
+    'Body text (paragraphs, descriptions)',
+    'UI labels and metadata',
+    'Captions, code snippets, overlines',
+  ],
+  whenNotToUse: [
+    'Page or section titles — use Heading',
+    'Form field labels — use Field.Label (auto-binds to form)',
+  ],
+  relatedTo: [
+    {component: 'Heading', relationship: 'Heading for semantic h1-h6; Text for body/label'},
+  ],
+  example: `<Stack gap="xs">
+  <Text variant="label">Email</Text>
+  <Text variant="bodySm" color="muted">We will never share your email.</Text>
+  <Text variant="code">user@example.com</Text>
+</Stack>`,
+}

package/src/components/ThemeProvider/ThemeProvider.meta.ts

@@ -0,0 +1,16 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Theme context provider. Must wrap the entire app at the root level. Sets dark, light, or high-contrast theme for all child components via CSS custom properties.',
+  whenToUse: [
+    'App root — required for all Duro components to render correctly',
+    'Theme switching (dark/light mode toggle)',
+  ],
+  whenNotToUse: [
+    'Never omit — all Duro components require ThemeProvider',
+  ],
+  example: `<ThemeProvider theme="dark">
+  <App />
+</ThemeProvider>`,
+}

package/src/components/Toggle/styles.css.ts

@@ -57,7 +57,8 @@ export const styles = css.create({
     borderRadius: 0,
     borderRightWidth: 1,
     borderRightStyle: 'solid',
-    borderRightColor: colors.border,
+    // Override any borderColor set by pressed state — dividers always use border token
+    borderColor: colors.border,
   },
   disabled: {
     opacity: 0.5,