@duro-app/ui 0.20.1 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "0.20.1",
+  "version": "0.21.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -52,7 +52,7 @@
     }
   },
   "dependencies": {
-    "@duro-app/tokens": "^0.20.1"
+    "@duro-app/tokens": "^0.21.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/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/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/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/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/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,