@cere/cere-design-system 0.0.35 → 0.0.37

package/.specify/memory/components-reference.md

@@ -598,7 +598,7 @@ import { Dialog, Button } from '@cere/cere-design-system';
 - `fullScreen?: boolean`
 
 ### Drawer
-Side drawer panel.
+Side drawer panel with optional header, tabs, and footer.
 
 ```typescript
 import { Drawer } from '@cere/cere-design-system';
@@ -607,6 +607,8 @@ import { Drawer } from '@cere/cere-design-system';
   open={open}
   onClose={() => setOpen(false)}
   anchor="right"
+  title="Run details"
+  width={{ xs: '100vw', sm: '80vw', md: '70vw', lg: '60vw', xl: 1200 }}
 >
   <div>Drawer content</div>
 </Drawer>
@@ -617,6 +619,17 @@ import { Drawer } from '@cere/cere-design-system';
 - `onClose?: () => void` - Close handler
 - `anchor?: 'left' | 'right' | 'top' | 'bottom'`
 - `variant?: 'permanent' | 'persistent' | 'temporary'`
+- `width?: number | string | { xs?, sm?, md?, lg?, xl? }` - Either a single
+  width or a mobile-first per-breakpoint object (values can be numbers or CSS
+  strings like `'100vw'`). Defaults: 400 for temporary/persistent, 240 for permanent
+- `miniWidth?: number` - Collapsed width when `collapsed` is true (default 72)
+- `collapsed?: boolean` - Render the mini-rail variant
+- `title?: ReactNode` - Shown in the header; close button appears automatically
+- `header?: ReactNode` - Fully custom header (replaces `title`)
+- `showCloseButton?: boolean` - Override default (on for temporary/persistent)
+- `tabs?: string[]` + `activeTab`, `onTabChange` - Tabbed header content
+- `footer?: ReactNode` - Sticky footer section
+- `topOffset?: number` - Offset from the viewport top in px (e.g., for a fixed app bar)
 
 ### List & ListItem
 Lists with items.
@@ -862,6 +875,44 @@ import { Logo } from '@cere/cere-design-system';
 - `size?: 'small' | 'medium' | 'large'` | number
 - `variant?: 'full' | 'icon'`
 
+### MetaField
+Compact label-over-value column for metadata lists. Uppercase eyebrow label,
+single-line value that truncates with an ellipsis and shows the full text on
+hover (for string values by default).
+
+```typescript
+import { MetaField } from '@cere/cere-design-system';
+
+<MetaField label="Run ID" value="run_abc123" mono />
+<MetaField label="Status" value={<Chip label="Running" variant="info" />} />
+```
+
+**Props:**
+- `label: string` - Uppercase eyebrow label
+- `value: ReactNode` - Value to display
+- `mono?: boolean` - Render the value in a monospace font
+- `title?: string` - Override the auto-generated hover tooltip
+
+### ScrollableRow
+Horizontally-scrolling container. Chevron buttons appear at the edges only
+when content overflows, driven by a ResizeObserver and MutationObserver so
+they stay in sync when children change.
+
+```typescript
+import { ScrollableRow, Chip } from '@cere/cere-design-system';
+
+<ScrollableRow>
+  {activities.map(a => <Chip key={a.id} label={a.name} />)}
+</ScrollableRow>
+```
+
+**Props:**
+- `children: ReactNode` - Row content (any children, not just chips)
+- `leftLabel?: string` - Aria-label for the left chevron (default 'Scroll left')
+- `rightLabel?: string` - Aria-label for the right chevron (default 'Scroll right')
+- `minNudge?: number` - Minimum scroll distance per chevron click (default 160)
+- `nudgeFraction?: number` - Fraction of viewport scrolled per click (default 0.6)
+
 ---
 
 ## FEEDBACK
@@ -920,23 +971,25 @@ import { Badge } from '@cere/cere-design-system';
 - `invisible?: boolean`
 
 ### Chip
-Compact element representing an input, attribute, or action.
+Compact element representing an input, attribute, status, or action. Colors
+come entirely from the `variant` prop — don't pass MUI's `color` directly.
 
 ```typescript
 import { Chip } from '@cere/cere-design-system';
 
-<Chip
-  label="Tag"
-  onDelete={handleDelete}
-  color="primary"
-  icon={<Icon />}
-/>
+<Chip label="Tag" />
+<Chip label="Selected" variant="active" />
+<Chip label="Succeeded" variant="success" />
+<Chip label="Failed" variant="error" onDelete={handleDelete} />
 ```
 
 **Props:**
 - `label: string` - Chip text
-- `variant?: 'filled' | 'outlined'`
-- `color?: 'default' | 'primary' | 'secondary' | 'error' | 'info' | 'success' | 'warning'`
+- `variant?: 'default' | 'active' | 'success' | 'error' | 'warning' | 'info'`
+  - `default` - grey surface, text-primary color
+  - `active` - brand-selected background, primary text
+  - `success/error/warning/info` - solid pill using `theme.palette.<status>.main`
+    surface + `.contrastText` (typically white); hover uses `.dark`
 - `size?: 'small' | 'medium'`
 - `icon?: ReactNode` - Icon before label
 - `avatar?: ReactNode` - Avatar before label
@@ -945,6 +998,11 @@ import { Chip } from '@cere/cere-design-system';
 - `disabled?: boolean`
 - `clickable?: boolean`
 
+The pure `getChipVariantStyles(variant, theme)` helper is also exported so
+domain-layer wrappers (e.g., a `RunStatusChip` that maps an app enum to a
+variant) can reuse the same color resolution without re-rendering a styled
+component.
+
 ### Tooltip
 Informative tooltip on hover.
 
@@ -1042,6 +1100,47 @@ import { AppLoading } from '@cere/cere-design-system';
 **Props:**
 - Minimal props - displays animated Cere logo
 
+### StatusDot
+Small colored circle indicating entity status. Pair with a text label for a
+labeled status, or pass `aria-label` to promote the dot into a standalone
+accessible indicator.
+
+```typescript
+import { StatusDot } from '@cere/cere-design-system';
+
+<StatusDot status="success" />
+<StatusDot status="info" pulse aria-label="Running" />
+```
+
+**Props:**
+- `status: 'success' | 'error' | 'warning' | 'info' | 'primary' | 'neutral'`
+- `size?: number` - Diameter in px (default 8)
+- `pulse?: boolean` - Animate for in-progress states (respects `prefers-reduced-motion`)
+- `aria-label?: string` - Presentational by default; setting this sets `role="img"`
+
+### CopyChip
+Compact inline copy-to-clipboard control. Monospace text + an icon that
+toggles to a check mark for a moment after a successful copy. Use in dense
+metadata rows where `IDBlock` is too heavy.
+
+```typescript
+import { CopyChip } from '@cere/cere-design-system';
+
+<CopyChip text="run_abc123" />
+<CopyChip text={longHexId} aria-label="Copy workspace ID" onCopy={track} />
+```
+
+**Props:**
+- `text: string` - Text to display and copy
+- `maxWidth?: number` - Ellipsize threshold for the label (default 260px)
+- `aria-label?: string` - Override the default `Copy <text>` label
+- `tooltipLabel?: string` / `tooltipCopiedLabel?: string` - Tooltip copy
+- `onCopy?: () => void` - Fires after the clipboard write
+
+**CopyChip vs IDBlock:**
+- Use `CopyChip` for inline, dense metadata (quiet icon-swap feedback, no snackbar)
+- Use `IDBlock` when the ID is the primary affordance on the surface (boxed, labeled, snackbar feedback)
+
 ---
 
 ## UTILITIES