@duro-app/ui 0.20.1 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "0.20.1",
+  "version": "0.22.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -52,7 +52,7 @@
     }
   },
   "dependencies": {
-    "@duro-app/tokens": "^0.20.1"
+    "@duro-app/tokens": "^0.22.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/ActionBar/ActionBar.meta.ts

@@ -0,0 +1,20 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Floating toolbar that appears at the bottom of the viewport when items are selected. Shows selection count and bulk actions. Animates in/out. Use with Table checkboxes for bulk operations.',
+  whenToUse: [
+    'Bulk actions on table selections (delete, revoke, export)',
+    'Multi-select workflows where actions apply to all selected items',
+  ],
+  whenNotToUse: [
+    'Single-item actions — use inline buttons or a Menu',
+    'Persistent toolbars — use Inline with buttons',
+  ],
+  relatedTo: [
+    {component: 'Table', relationship: 'Common pattern: Table checkboxes + ActionBar for bulk ops'},
+  ],
+  example: `<ActionBar selectedItemCount={selected.size} onClearSelection={() => setSelected(new Set())}>
+  <Button variant="danger" size="small" onClick={handleDelete}>Delete</Button>
+</ActionBar>`,
+}

package/src/components/ActionBar/ActionBar.stories.tsx

@@ -13,6 +13,16 @@ interface ActionBarStoryArgs {
 
 const meta: Meta<ActionBarStoryArgs> = {
   title: 'Components/ActionBar',
+  argTypes: {
+    selectedItemCount: {
+      control: 'number',
+      description: 'Number of selected items displayed in the action bar',
+    },
+    isEmphasized: {
+      control: 'boolean',
+      description: 'Whether the action bar uses the emphasized (inverse) style',
+    },
+  },
 }
 
 export default meta

package/src/components/Alert/Alert.meta.ts

@@ -0,0 +1,25 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Inline status message with icon. Compact, single-line feedback for form validation results, API responses, or status updates. For block-level prominent messages, use Callout instead.',
+  whenToUse: [
+    'Form submission feedback (success, error)',
+    'API response status messages',
+    'Inline warnings or info notices',
+  ],
+  whenNotToUse: [
+    'Block-level prominent messages — use Callout',
+    'Toast notifications — use a toast system',
+    'Form field errors — use Field.Error',
+  ],
+  relatedTo: [
+    {component: 'Callout', relationship: 'Callout for larger block-level messages; Alert for compact inline'},
+  ],
+  example: `<Stack gap="sm">
+  <Alert variant="success">Settings saved successfully.</Alert>
+  <Alert variant="error">Failed to connect. Please retry.</Alert>
+  <Alert variant="warning">Your session expires in 5 minutes.</Alert>
+  <Alert variant="info">New version available.</Alert>
+</Stack>`,
+}

package/src/components/Badge/Badge.meta.ts

@@ -0,0 +1,20 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Small label or tag for status indicators, counts, or categories. Renders inline. Use for metadata annotations next to text or in table cells.',
+  whenToUse: [
+    'Status indicators (active, expired, pending)',
+    'Category tags or labels',
+    'Count indicators next to items',
+  ],
+  whenNotToUse: [
+    'Interactive toggleable tags — use Toggle or ToggleGroup',
+    'Long descriptive messages — use Alert or Callout',
+  ],
+  example: `<Inline gap="xs">
+  <Badge variant="success">Active</Badge>
+  <Badge variant="error">Expired</Badge>
+  <Badge variant="default">Draft</Badge>
+</Inline>`,
+}

package/src/components/Callout/Callout.meta.ts

@@ -0,0 +1,22 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Block-level informational message with icon and colored background. More prominent than Alert. Use for important notices, onboarding tips, or contextual guidance that should stand out.',
+  whenToUse: [
+    'Important notices that need visual prominence',
+    'Onboarding tips or contextual guidance',
+    'Warning messages before destructive actions',
+  ],
+  whenNotToUse: [
+    'Compact inline feedback — use Alert',
+    'Form field errors — use Field.Error',
+    'Toast notifications — use a toast system',
+  ],
+  relatedTo: [
+    {component: 'Alert', relationship: 'Alert for compact inline; Callout for block-level prominent'},
+  ],
+  example: `<Callout variant="warning">
+  Your subscription expires in 3 days. Renew now to avoid service interruption.
+</Callout>`,
+}

package/src/components/Card/Card.meta.ts

@@ -0,0 +1,25 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Container with visual styling (elevation, border, or fill). Groups related content with consistent spacing and background. For structural containers with Header/Body/Footer slots, use Panel instead.',
+  whenToUse: [
+    'Grouping related content visually (settings sections, dashboard widgets)',
+    'Clickable content cards with hover state (interactive variant)',
+    'Content containers with elevation or borders',
+  ],
+  whenNotToUse: [
+    'Structural containers with Header/Body/Footer — use Panel',
+    'Page-level layout — use PageShell',
+    'Simple spacing — use Stack or Inline',
+  ],
+  relatedTo: [
+    {component: 'Panel', relationship: 'Panel for structural Header/Body/Footer; Card for visual container'},
+  ],
+  example: `<Card variant="elevated" size="md">
+  <Stack gap="md">
+    <Heading level={3}>Account</Heading>
+    <Text>Manage your account settings.</Text>
+  </Stack>
+</Card>`,
+}

package/src/components/DetailPanel/DetailPanel.meta.ts

@@ -18,7 +18,10 @@ export const meta: ComponentMeta = {
     optional: ['Title', 'Footer', 'Close'],
   },
   relatedTo: [
-    {component: 'Drawer', relationship: 'Drawer is modal with backdrop; DetailPanel is non-modal and in-flow'},
+    {
+      component: 'Drawer',
+      relationship: 'Drawer is modal with backdrop; DetailPanel is non-modal and in-flow',
+    },
     {component: 'Panel', relationship: 'DetailPanel uses Panel structure internally'},
     {component: 'Table', relationship: 'Common pattern: Table + DetailPanel for master-detail'},
   ],

package/src/components/DetailPanel/DetailPanel.stories.tsx

@@ -2,6 +2,7 @@ import type {Meta, StoryObj} from '@storybook/react'
 import {useState} from 'react'
 import {css, html} from 'react-strict-dom'
 import {DetailPanel} from './DetailPanel'
+import {Panel} from '../Panel/Panel'
 import {Button} from '../Button/Button'
 import {Text} from '../Text/Text'
 import {Heading} from '../Heading/Heading'
@@ -56,9 +57,8 @@ function DefaultDemo() {
           </DetailPanel.Header>
           <DetailPanel.Body>
             <Text>
-              This is a non-modal detail panel. The content behind it
-              remains interactive — you can still click, scroll, and
-              interact with the main area.
+              This is a non-modal detail panel. The content behind it remains interactive — you can
+              still click, scroll, and interact with the main area.
             </Text>
           </DetailPanel.Body>
           <DetailPanel.Footer>
@@ -137,9 +137,15 @@ function TableSelectionDemo() {
           <Heading level={3}>Users</Heading>
           <html.div>
             <html.div style={tableStyles.headerRow}>
-              <html.span style={tableStyles.cellText}><Text variant="label">Name</Text></html.span>
-              <html.span style={tableStyles.cellText}><Text variant="label">Role</Text></html.span>
-              <html.span style={tableStyles.cellText}><Text variant="label">Status</Text></html.span>
+              <html.span style={tableStyles.cellText}>
+                <Text variant="label">Name</Text>
+              </html.span>
+              <html.span style={tableStyles.cellText}>
+                <Text variant="label">Role</Text>
+              </html.span>
+              <html.span style={tableStyles.cellText}>
+                <Text variant="label">Status</Text>
+              </html.span>
             </html.div>
             {users.map((user) => (
               <html.div
@@ -147,9 +153,15 @@ function TableSelectionDemo() {
                 style={[tableStyles.row, selectedId === user.id && tableStyles.rowSelected]}
                 onClick={() => setSelectedId(selectedId === user.id ? null : user.id)}
               >
-                <html.span style={tableStyles.cellText}><Text>{user.name}</Text></html.span>
-                <html.span style={tableStyles.cellText}><Text>{user.role}</Text></html.span>
-                <html.span style={tableStyles.cellText}><Text>{user.status}</Text></html.span>
+                <html.span style={tableStyles.cellText}>
+                  <Text>{user.name}</Text>
+                </html.span>
+                <html.span style={tableStyles.cellText}>
+                  <Text>{user.role}</Text>
+                </html.span>
+                <html.span style={tableStyles.cellText}>
+                  <Text>{user.status}</Text>
+                </html.span>
               </html.div>
             ))}
           </html.div>
@@ -170,22 +182,37 @@ function TableSelectionDemo() {
           <DetailPanel.Body>
             {selectedUser && (
               <Stack gap="md">
-                <Stack gap="xs">
-                  <Text variant="label">Email</Text>
-                  <Text variant="bodySm">{selectedUser.email}</Text>
-                </Stack>
-                <Stack gap="xs">
-                  <Text variant="label">Role</Text>
-                  <Text variant="bodySm">{selectedUser.role}</Text>
-                </Stack>
-                <Stack gap="xs">
-                  <Text variant="label">Status</Text>
-                  <Inline gap="sm">
-                    <Badge variant={selectedUser.status === 'Active' ? 'success' : 'default'}>
-                      {selectedUser.status}
-                    </Badge>
-                  </Inline>
-                </Stack>
+                <Panel.Root>
+                  <Panel.Header>
+                    <Text variant="label">Contact</Text>
+                  </Panel.Header>
+                  <Panel.Body>
+                    <Stack gap="xs">
+                      <Text variant="caption">Email</Text>
+                      <Text variant="bodySm">{selectedUser.email}</Text>
+                    </Stack>
+                  </Panel.Body>
+                </Panel.Root>
+
+                <Panel.Root>
+                  <Panel.Header>
+                    <Text variant="label">Role &amp; Status</Text>
+                  </Panel.Header>
+                  <Panel.Body>
+                    <Stack gap="sm">
+                      <Inline gap="sm" align="center">
+                        <Text variant="caption">Role</Text>
+                        <Text variant="bodySm">{selectedUser.role}</Text>
+                      </Inline>
+                      <Inline gap="sm" align="center">
+                        <Text variant="caption">Status</Text>
+                        <Badge variant={selectedUser.status === 'Active' ? 'success' : 'default'}>
+                          {selectedUser.status}
+                        </Badge>
+                      </Inline>
+                    </Stack>
+                  </Panel.Body>
+                </Panel.Root>
               </Stack>
             )}
           </DetailPanel.Body>
@@ -225,8 +252,8 @@ function MediumSizeDemo() {
           </DetailPanel.Header>
           <DetailPanel.Body>
             <Text>
-              This panel is 480px wide, providing more room for complex
-              content like forms or detailed information.
+              This panel is 480px wide, providing more room for complex content like forms or
+              detailed information.
             </Text>
           </DetailPanel.Body>
         </DetailPanel.Content>

package/src/components/DetailPanel/DetailPanel.tsx

@@ -194,12 +194,7 @@ function Content({children, size = 'sm', label}: ContentProps) {
   if (!present) return null
 
   return (
-    <html.div
-      style={[
-        styles.wrapper,
-        closing ? wrapperCloseMap[size] : wrapperOpenMap[size],
-      ]}
-    >
+    <html.div style={[styles.wrapper, closing ? wrapperCloseMap[size] : wrapperOpenMap[size]]}>
       <html.div
         ref={panelRef}
         role="complementary"
@@ -250,11 +245,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 ---
@@ -282,11 +273,7 @@ function Close({children, 'aria-label': ariaLabel = 'Close'}: CloseProps) {
   }
 
   return (
-    <html.button
-      onClick={requestClose}
-      aria-label={ariaLabel}
-      style={styles.closeButton}
-    >
+    <html.button onClick={requestClose} aria-label={ariaLabel} style={styles.closeButton}>
       <svg width={16} height={16} viewBox="0 0 16 16" fill="none">
         <path
           d="M4 4l8 8M12 4l-8 8"

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

@@ -137,6 +137,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/Dialog/Dialog.meta.ts

@@ -20,8 +20,14 @@ export const meta: ComponentMeta = {
     optional: ['Trigger', 'Header', 'Title', 'Description', 'Body', 'Footer', 'Close'],
   },
   relatedTo: [
-    {component: 'Drawer', relationship: 'Drawer slides from an edge; Dialog is centered with scale animation'},
-    {component: 'DetailPanel', relationship: 'DetailPanel is non-modal and in-flow; Dialog is modal with backdrop'},
+    {
+      component: 'Drawer',
+      relationship: 'Drawer slides from an edge; Dialog is centered with scale animation',
+    },
+    {
+      component: 'DetailPanel',
+      relationship: 'DetailPanel is non-modal and in-flow; Dialog is modal with backdrop',
+    },
   ],
   example: `<Dialog.Root open={open} onOpenChange={setOpen}>
   <Dialog.Trigger>

package/src/components/Drawer/Drawer.meta.ts

@@ -21,7 +21,10 @@ export const meta: ComponentMeta = {
   },
   relatedTo: [
     {component: 'Dialog', relationship: 'Dialog is centered modal; Drawer slides from an edge'},
-    {component: 'DetailPanel', relationship: 'DetailPanel is non-modal and in-flow; Drawer is modal with backdrop'},
+    {
+      component: 'DetailPanel',
+      relationship: 'DetailPanel is non-modal and in-flow; Drawer is modal with backdrop',
+    },
   ],
   example: `<Drawer.Root anchor="right" open={open} onOpenChange={setOpen}>
   <Drawer.Trigger>

package/src/components/EmptyState/EmptyState.meta.ts

@@ -0,0 +1,22 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Placeholder for empty content areas. Shows an icon, message, and optional action button. Use when a list, table, or section has no data to display.',
+  whenToUse: [
+    'Empty tables or lists with no results',
+    'Search results with no matches',
+    'First-time use before any data exists',
+  ],
+  whenNotToUse: [
+    'Loading states — use Spinner',
+    'Error states — use Alert or Callout',
+  ],
+  example: `<Card>
+  <EmptyState
+    icon={<Icon name="info-circle" size={48} />}
+    message="No results found"
+    action={<Button variant="secondary">Clear filters</Button>}
+  />
+</Card>`,
+}

package/src/components/Field/Field.stories.tsx

@@ -6,6 +6,12 @@ import {Input} from '../Input/Input'
 
 const meta: Meta = {
   title: 'Components/Field',
+  argTypes: {
+    invalid: {
+      control: 'boolean',
+      description: 'Whether the field is in an invalid/error state',
+    },
+  },
 }
 
 export default meta

package/src/components/Heading/Heading.meta.ts

@@ -0,0 +1,24 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Semantic heading element (h1-h6) with typography presets. Always use the correct level for document hierarchy. Visual size can differ from semantic level via the variant prop.',
+  whenToUse: [
+    'Page titles (level 1)',
+    'Section headers (level 2-3)',
+    'Card or panel titles (level 3-4)',
+  ],
+  whenNotToUse: [
+    'Body text — use Text',
+    'Form labels — use Field.Label',
+    'Non-semantic bold text — use Text with weight',
+  ],
+  relatedTo: [
+    {component: 'Text', relationship: 'Text for body/label; Heading for semantic headings'},
+  ],
+  example: `<Stack gap="md">
+  <Heading level={1}>Page Title</Heading>
+  <Heading level={2} variant="headingMd">Section</Heading>
+  <Heading level={3}>Subsection</Heading>
+</Stack>`,
+}

package/src/components/Icon/Icon.meta.ts

@@ -0,0 +1,23 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'SVG icon component. Renders stroke or filled icons from the design system icon set. Size scales with the size prop. Use inside buttons, badges, or standalone.',
+  whenToUse: [
+    'Button icons (inside Button children)',
+    'Status indicators alongside text',
+    'Navigation or action indicators',
+  ],
+  whenNotToUse: [
+    'Decorative images — use img elements',
+    'Complex illustrations — use custom SVGs',
+  ],
+  relatedTo: [
+    {component: 'StatusIcon', relationship: 'StatusIcon wraps Icon with a colored background circle'},
+  ],
+  example: `<Inline gap="sm" align="center">
+  <Icon name="check-circle" size={20} />
+  <Icon name="alert-triangle" size={20} />
+  <Icon name="shield-filled" size={20} />
+</Inline>`,
+}

package/src/components/InputGroup/InputGroup.meta.ts

@@ -0,0 +1,28 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Wraps an Input with prefix and/or suffix addons (icons, text, buttons). Addons are visually attached to the input edges.',
+  whenToUse: [
+    'Inputs with units (e.g. "$" prefix, "kg" suffix)',
+    'Search inputs with an icon prefix',
+    'URL inputs with protocol prefix',
+  ],
+  whenNotToUse: [
+    'Standalone inputs without addons — use Input directly',
+    'Form field labels — use Field.Label',
+  ],
+  anatomy: {
+    required: ['Root'],
+    optional: ['Addon'],
+  },
+  relatedTo: [
+    {component: 'Input', relationship: 'InputGroup enhances Input with addons'},
+    {component: 'Field', relationship: 'Field provides label/error; InputGroup provides visual addons'},
+  ],
+  example: `<InputGroup.Root>
+  <InputGroup.Addon>$</InputGroup.Addon>
+  <Input type="number" placeholder="0.00" />
+  <InputGroup.Addon>USD</InputGroup.Addon>
+</InputGroup.Root>`,
+}

package/src/components/List/List.meta.ts

@@ -0,0 +1,39 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Vertical list of interactive items. Ideal for narrow spaces (detail panels, sidebars) where Table would truncate. Supports selection, descriptions, and action slots.',
+  whenToUse: [
+    'Displaying items in a narrow container (< 480px)',
+    'Detail panels, drawers, and sidebars',
+    'Lists needing selection (single or multiple) with compact layout',
+  ],
+  whenNotToUse: [
+    'Tabular data with many columns — use Table',
+    'Navigation menus — use SideNav or Menu',
+    'Simple text lists without interaction — use Stack with Text',
+  ],
+  anatomy: {
+    required: ['Root', 'Item', 'Content', 'Text'],
+    optional: ['Description', 'Actions', 'Empty'],
+  },
+  relatedTo: [
+    {component: 'Table', relationship: 'Table for wide multi-column data; List for narrow compact items'},
+    {component: 'DetailPanel', relationship: 'List fits naturally inside DetailPanel.Body'},
+    {component: 'Menu', relationship: 'Menu for action menus; List for data display with selection'},
+  ],
+  example: `<List.Root selectionMode="multiple" aria-label="Certificates">
+  <List.Item selected onClick={toggle}>
+    <Checkbox checked />
+    <List.Content>
+      <List.Text>web-server-prod-2024.pem</List.Text>
+      <List.Description>Issued: Jan 15, 2024 · Expires: Jan 15, 2025</List.Description>
+    </List.Content>
+    <List.Actions>
+      <Badge variant="success">Active</Badge>
+      <Button variant="danger" size="small">Revoke</Button>
+    </List.Actions>
+  </List.Item>
+  <List.Empty>No certificates found.</List.Empty>
+</List.Root>`,
+}