@persona/design-system 0.3.0 → 0.3.1

package/skills/ui-authoring/COMPONENTS.md

@@ -1,212 +1,73 @@
-# Component Patterns & Props Reference
+# Components
+
+Which PDS component to use, and for what. For usage guidance and additional code examples, see
+that component's `.mdx` beside its source under `front-end/design-system/components/` when one
+exists. If there is no `.mdx`, use the published type declarations
+(`dist/components/<Name>/index.d.mts`).
+
+
+| Component | Use for | Import |
+| --------- | ------- | ------ |
+| `Attribute` | Labeling a data value (`<dl>`/`<dt>`/`<dd>`). Use `AttributeGrid` for a grid of them | `@persona/design-system/components/Attribute` |
+| `Badge` | Count badge — a count or notification number | `@persona/design-system/components/Badge` |
+| `Banner` | Alert / notification — important in-context info, success, warning, or danger. Optionally dismissable | `@persona/design-system/components/Banner` |
+| `Breadcrumbs` | Showing where the user is in a hierarchy and navigating to ancestors | `@persona/design-system/components/Breadcrumbs` |
+| `Button` | Triggering an action. Use `IconButton` when there is no label | `@persona/design-system/components/Button` |
+| `ButtonGroup` | Choosing among related modes in a compact connected button set (often icons, e.g. alignment). Use `Toggle` for a single on/off setting; `RadioGroup` for a visible list of labeled choices | `@persona/design-system/components/ButtonGroup` |
+| `Card` + `Card.Section` | Grouping related content and actions so they're easier to scan. Collapsible sections on long settings pages | `@persona/design-system/components/CardV2` |
+| `Checkbox` | Selecting one or more options from a visible list | `@persona/design-system/components/Checkbox` |
+| `Combobox` | Picking from a long list that needs search (single or multi). Use `RadioGroup` when every choice should stay visible (one); `Checkbox` when every choice should stay visible (several); `Select` for a short closed list with no search | `@persona/design-system/components/Combobox` |
+| `ConfigFormGroup` | Form fields — spacing a group of config fields and setting `configField` via context. Pair with `TextField` / `TextAreaField` | `@persona/design-system/components/ConfigFormGroup` |
+| `Container`, `Section`, `Backdrop` | Page shell | `@persona/design-system/patterns/PageLayout` |
+| `DataTable` | Data table — browsing tabular data with filtering, bulk actions, search, pagination, and sorting | `@persona/design-system/components/DataTable` |
+| `DatePicker` | Picking a date or date range from a calendar | `@persona/design-system/components/DatePicker` |
+| `DropdownButton` | Opening a menu of related actions from a button | `@persona/design-system/components/DropdownButton` |
+| `DropdownMenu` | Showing a temporary action list on a custom trigger | `@persona/design-system/components/DropdownMenu` |
+| `FormControl` | Building a custom labeled field (label + helper/error/warning) when `FormField` is too rigid | `@persona/design-system/components/FormControl` |
+| `FormField` | Giving an input a label, helper, and error/warning. Use this or a `*Field` wrapper (`TextField`, `TextAreaField`) for form fields — unlabeled controls (search, toolbars) can stay as `Input` | `@persona/design-system/components/FormField` |
+| `HoverCopyableField` | Letting the user copy a value on hover. Optional `onCopySuccess` skips Copied so the host owns post-copy UX | `@persona/design-system/components/HoverCopyableField` |
+| `HStack` | Flex row — laying out children horizontally with token spacing | `@persona/design-system/components/Stack` |
+| `ImageTile` | Showing a thumbnail in a gallery or grid | `@persona/design-system/components/ImageTile` |
+| `IconButton` | Icon-only button — triggering an icon-only action | `@persona/design-system/components/Button` |
+| `Input` | Text input — a single line of text without a form label. In forms, use `TextField` | `@persona/design-system/components/Input` |
+| `Link` | Navigating to another page or resource. External links need the external-link icon | `@persona/design-system/components/Link` |
+| `ListBox` | Dynamic list — a visible, always-open list of items (select, add, delete, reorder). Unlike `Combobox`, it is not a collapsed search field — the list stays on the page | `@persona/design-system/components/ListBox` |
+| `LoadingShimmer` | Filling space while content loads | `@persona/design-system/components/LoadingShimmer` |
+| `MaskedInput` | Entering structured text (phone, SSN, etc.) | `@persona/design-system/components/MaskedInput` |
+| `MatchHighlight` | Highlighting how strongly children match | `@persona/design-system/components/MatchHighlight` |
+| `Menu` | Rendering a vertical list of actions (styled only). Use `DropdownMenu` when it needs a trigger | `@persona/design-system/components/Menu` |
+| `Modal` | Focusing the user on a task or confirmation behind a page overlay (e.g. delete confirm, short form submit) | `@persona/design-system/components/Modal` |
+| `PageHeader` | Page title bar — optional subtitle, breadcrumbs, and actions | `@persona/design-system/components/PageHeader` |
+| `Pagination` | Moving between pages and changing page size | `@persona/design-system/components/Pagination` |
+| `Pii` | Showing a value, or a “Redacted” sticker when PII is hidden | `@persona/design-system/components/Pii` |
+| `Popover` | Floating panel — extra content or controls anchored to a trigger, without leaving the page | `@persona/design-system/components/Popover` |
+| `ProgressBar` | Showing linear progress (determinate or indeterminate) | `@persona/design-system/components/ProgressBar` |
+| `ProgressIndicator` | Showing progress through a sequence of steps | `@persona/design-system/components/ProgressIndicator` |
+| `Radio` | Picking one visible option. Prefer `RadioGroup` to manage the set | `@persona/design-system/components/Radio` |
+| `RadioGroup` | Grouping two or more mutually exclusive `Radio`s and owning the selected value | `@persona/design-system/components/RadioGroup` |
+| `SegmentedControl` | Picking one option from a compact set of mutually exclusive choices | `@persona/design-system/components/SegmentedControl` |
+| `Select` | Dropdown — picking one value from a short, known list with no search. Use `Combobox` when the list needs search | `@persona/design-system/components/Select` |
+| `Slider` | Picking a numeric value or range along a scale | `@persona/design-system/components/Slider` |
+| `Spacer` | Prefer `Stack` — leftover gap helper | `@persona/design-system/components/Spacer` |
+| `Spinner` | Showing that something is loading | `@persona/design-system/components/Spinner` |
+| `Stack` | Flex column — laying out children vertically with token spacing | `@persona/design-system/components/Stack` |
+| `StatusIndicator` | Showing a named status (open, pending, completed, failed, …) | `@persona/design-system/components/StatusIndicator` |
+| `Sticker` | Status badge — tagging nearby content with status or label metadata | `@persona/design-system/components/Sticker` |
+| `SwatchPicker` | Picking a color from a swatch list. Wrap with `FormField` | `@persona/design-system/components/SwatchPicker` |
+| `TabBar`, `Tab` | Tabs — switching between related views or content sections | `@persona/design-system/components/TabBar` |
+| `Table` | Displaying rows and columns with sticky headers, sort, and checkbox selection. Use `DataTable` when you need filtering, bulk actions, or search | `@persona/design-system/components/Table` |
+| `TableBox` | Editable / form table — a small form-adjacent table (inline edit, add/delete, reorder) | `@persona/design-system/components/TableBox` |
+| `TableLayout` | Table with loading/empty states; compose rows from `Table` primitives (`TableRow`, `TableCell`, `TableHeaderCell`) | `@persona/design-system/components/Table` |
+| `TechnicalSticker` | Displaying a monospace ID or field key (middle-truncated) | `@persona/design-system/components/TechnicalSticker` |
+| `Heading`, `Paragraph`, `Label` | Heading text, body text, and form labels (`Display`, `Span`, `TabularNumber` too). There is no `<Text>` component | `@persona/design-system/components/Text` |
+| `TextArea` | Text input — multiple lines without a form label. In forms, use `TextAreaField` | `@persona/design-system/components/TextArea` |
+| `TextField` | Entering a labeled single line of text in a form. Prefer over bare `Input` | `@persona/design-system/components/FormField` |
+| `TextUnderlineTooltip` | Tooltip on a label — dashed underline. Never put an info icon next to the label | `@persona/design-system/components/Tooltip` |
+| `Tile` | Showing a labeled metric, with optional sticker and metadata | `@persona/design-system/components/Tile` |
+| `Toast` | Confirming a system event or action result that can auto-dismiss | `@persona/design-system/components/Toast` |
+| `Toggle` | Turning a setting on or off with no extra confirmation | `@persona/design-system/components/Toggle` |
+| `Tooltip` | Standalone tooltip — explaining an icon or control on hover or focus | `@persona/design-system/components/Tooltip` |
 
-## Form Configuration
-
-```tsx
-import ConfigFormGroup from '@persona/design-system/components/ConfigFormGroup';
-import { TextField, TextAreaField } from '@persona/design-system/components/FormField';
-
-const [config, setConfig] = useState({ name: '', description: '', prompt: '' });
-
-<ConfigFormGroup>
-  <TextField
-    label="Name"
-    value={config.name}
-    onChange={(e) => setConfig({ ...config, name: e.target.value })}
-    configField={true}       // helperText becomes a tooltip
-    helperText="Unique identifier"
-    errorText={errors.name}
-    rightActions={<Button size="sm" variant="basic">Generate</Button>}
-  />
-  <TextAreaField
-    label="Prompt"
-    value={config.prompt}
-    onChange={(e) => setConfig({ ...config, prompt: e.target.value })}
-    configField={true}
-    warningText={warnings.prompt}
-  />
-</ConfigFormGroup>
-```
-
-- `configField={true}` → helper text becomes a tooltip instead of inline text
-- `ConfigFormGroup` provides consistent 20px spacing between fields
-- Use controlled inputs; clear `errorText` on change via `updateField` in form state hook
-
-## Form State Hook
-
-```tsx
-const useFormState = (initialConfig) => {
-  const [config, setConfig] = useState(initialConfig);
-  const [errors, setErrors] = useState({});
-
-  const updateField = useCallback((field, value) => {
-    setConfig(prev => ({ ...prev, [field]: value }));
-    setErrors(prev => { const next = { ...prev }; delete next[field]; return next; });
-  }, []);
-
-  const validate = useCallback(() => {
-    const newErrors = {};
-    if (!config.name) newErrors.name = 'Required';
-    setErrors(newErrors);
-    return Object.keys(newErrors).length === 0;
-  }, [config]);
-
-  return { config, errors, updateField, validate };
-};
-```
-
-## Dynamic List (ListBox)
-
-```tsx
-import { ListBox } from '@persona/design-system/components/ListBox';
-
-<ListBox
-  items={items}
-  selectedKeys={selectedKeys}
-  onSelectionChange={setSelectedKeys}
-  onAdd={() => setItems([...items, { id: uuid(), name: 'New' }])}
-  onDelete={(keys) => setItems(items.filter(i => !keys.has(i.id)))}
-  selectionMode="multiple"
-  emptyText="No items"
->
-  {items.map(item => (
-    <ListBox.Item key={item.id}>{item.name}</ListBox.Item>
-  ))}
-</ListBox>
-```
-
-Drag-drop reordering: add `reorderConfig={{ onReorder: (items) => void, dragIcon: ReactNode }}`.
-
-## Editable Table (TableBox)
-
-Use `TableBox` for **small, form-adjacent tables** — config editors, field mappings, inline-editable row lists. Use `DataTable` for **data views** with pagination, sorting, and server-side data.
-
-```tsx
-import TableBox from '@persona/design-system/components/TableBox';
-
-const columns = [
-  { key: 'name', title: 'Name' },
-  { key: 'type', title: 'Type' },
-];
-
-<TableBox columns={columns} aria-label='File list' selectionMode='none'>
-  {items.map((item) => (
-    <TableBox.Row key={item.id} id={item.id} onDelete={() => removeItem(item.id)}>
-      <TableBox.Cell>{item.name}</TableBox.Cell>
-      <TableBox.Cell>{item.type}</TableBox.Cell>
-    </TableBox.Row>
-  ))}
-</TableBox>
-```
-
-- `aria-label` is **required**
-- Rows are composed via `TableBox.Row` + `TableBox.Cell` children (not an `items` prop)
-- Row actions: pass `actions={[{ label, onClick }]}` or `onDelete` on `TableBox.Row`
-- Drag-drop reordering: `reorderConfig={{ items, itemKeyPath: 'id', onReorder }}`
-- Empty state: `emptyText`; pass `onCreateNewRow` to make the message a clickable "add row" button
-- `onCreateNewRow` also fires after Enter on the **last cell of the last row** (single-line text inline edit only)
-
-### Inline editing
-
-Declare `inlineEditConfig` on column definitions; pass `columnKey`, `itemId`, and `value` on each cell:
-
-```tsx
-const columns = [
-  {
-    key: 'name',
-    title: 'Name',
-    inlineEditConfig: { type: 'text', onChange: (id, value) => updateField(id, 'name', value) },
-  },
-  {
-    key: 'role',
-    title: 'Role',
-    inlineEditConfig: {
-      type: 'combobox',
-      options: roleOptions,
-      onChange: (id, value) => updateField(id, 'role', value),
-    },
-  },
-];
-
-<TableBox columns={columns} aria-label='Editable users'>
-  {users.map((user) => (
-    <TableBox.Row key={user.id} id={user.id}>
-      <TableBox.Cell columnKey='name' itemId={user.id} value={user.name} errorText={errors[user.id]?.name}>
-        {user.name}
-      </TableBox.Cell>
-      <TableBox.Cell columnKey='role' itemId={user.id} value={user.role}>
-        {roleLabel(user.role)}
-      </TableBox.Cell>
-    </TableBox.Row>
-  ))}
-</TableBox>
-```
-
-- Inline editing forces fixed-width layout (no horizontal scroll) automatically
-- Cell/row validation: pass `errorText` on `TableBox.Cell` or `TableBox.Row`
-- For adding rows from a form field, prefer `TableBoxField` (below) over bare `onCreateNewRow`
-
-### Form field wrapper (TableBoxField)
-
-Use inside `ConfigFormGroup` when the table needs a label, add/delete toolbar, and row creation:
-
-```tsx
-import { TableBoxField } from '@persona/design-system/components/FormField';
-
-<TableBoxField
-  label='Case actions'
-  labelProps={{ size: 'md' }}   // defaults to 'sm'; match sibling ControlPanel labels
-  columns={columns}
-  createNewRow={() => addRow()}
-  onDelete={(selectedKey) => removeRow(selectedKey)}
-  selectionMode='single'
->
-  {rows.map((row) => (
-    <TableBoxField.Row key={row.id} id={row.id}>
-      <TableBoxField.Cell columnKey='key' itemId={row.id} value={row.key}>
-        {row.key}
-      </TableBoxField.Cell>
-    </TableBoxField.Row>
-  ))}
-</TableBoxField>
-```
-
-`TableBoxField.Row` and `TableBoxField.Cell` are aliases for `TableBox.Row` / `TableBox.Cell`.
-
-## Collapsible Sections (Card)
-
-```tsx
-import { Card } from '@persona/design-system/components/CardV2';
-
-<Card>
-  <Card.Section header="Basic Settings" collapsible={true} defaultCollapsed={false}>
-    {/* Content */}
-  </Card.Section>
-  <Card.Section header="Advanced" collapsible={true}>
-    {/* Content */}
-  </Card.Section>
-</Card>
-```
-
-## Modal
-
-```tsx
-import { Modal } from '@persona/design-system/components/Modal';
-
-<Modal
-  isOpen={isOpen}
-  onClose={() => setIsOpen(false)}
-  title="Add Tools"
-  footer={
-    <>
-      <Button variant="basic" onClick={() => setIsOpen(false)}>Cancel</Button>
-      <Button variant="primary" onClick={handleSave}>Save</Button>
-    </>
-  }
->
-  {/* Content */}
-</Modal>
-```
 
 ## Testing
 
@@ -232,100 +93,3 @@ it('shows validation errors', async () => {
 - Prefer `userEvent.type()` over `fireEvent.change()`
 - Use `waitFor()` for async state updates
 - Prefer `getByRole`, `getByLabelText`, `getByText` over `getByTestId`
-
-## Props Reference
-
-### TextField / TextAreaField
-- `label` — field label
-- `value` / `onChange` — controlled input
-- `helperText` — help text (tooltip if `configField={true}`)
-- `errorText` — error message (red)
-- `warningText` — warning message (yellow)
-- `configField` — boolean, renders helper as tooltip
-- `rightActions` — ReactNode for buttons/icons next to label
-- `disabled` — boolean
-
-### ListBox
-- `items` — array of items
-- `selectedKeys` / `onSelectionChange` — controlled selection (`Set<string>`)
-- `selectionMode` — `"single"` | `"multiple"` | `"none"`
-- `onAdd` — add button callback
-- `onDelete` — delete callback (receives `Set<string>` of keys)
-- `reorderConfig` — `{ onReorder: (items) => void, dragIcon: ReactNode }`
-- `emptyText` — shown when no items
-
-### TableBox
-- `columns` — `{ key, title, inlineEditConfig? }[]` (required)
-- `aria-label` — accessible table name (required)
-- `emptyText` — shown when no rows
-- `selectionMode` — `"single"` | `"none"` (default `"none"`)
-- `selectedKey` / `onSelectionChange` / `defaultSelectedKey` — row selection
-- `onCreateNewRow` — makes empty state clickable; fires after Enter on last cell of last row (single-line text)
-- `newRowId` — auto-opens inline edit on the first column of the new row
-- `disabled` — view-only; blocks edits, delete, and reorder
-- `reorderConfig` — `{ items, itemKeyPath, onReorder }` for drag-drop row reorder
-- `disableHorizontalScroll` — fixed-width/truncating layout (auto when any column has `inlineEditConfig`)
-- `hideHeader` — hide column headers (e.g. single-column tables under a `FormField` label)
-
-#### TableBox.Row
-- `id` — row identifier (required)
-- `actions` — `[{ label, onClick }]` dropdown menu items
-- `onDelete` — renders row delete button
-- `errorText` — row-wide validation error (shown in first cell)
-- `dropdownFormFields` / `dropdownContent` / `dropdownHeadingText` / `dropdownFooter` — expandable row popover (requires `selectionMode='single'`; opens when row is selected)
-
-#### TableBox.Cell
-- `columnKey` / `itemId` / `value` — required for inline editing
-- `errorText` — cell validation error
-- `inlineEditConfigOverride` — per-cell override of column `inlineEditConfig`
-
-#### TableBoxField (extends TableBox + FormField)
-- `label`, `helperText`, `errorText`, `warningText`, `configField` — standard form field props
-- `createNewRow` — returns new row id; wires add button and empty state
-- `onAdd` — alternative add handler (when not using `createNewRow`)
-- `onDelete` — deletes the currently selected row
-- `actions` — toolbar dropdown actions (receives `selectedKey`)
-- `addDropdownConfig` — `{ options, onSelection }` for add-menu instead of direct add
-
-### Card / Card.Section
-- `collapsible` — boolean
-- `defaultCollapsed` — boolean
-- `header` — section header text
-- `loading` — boolean
-- `empty` — boolean
-
-### Stack / HStack
-- `spacing` — spacing value (default: `Spacing[2]`)
-- `align` — `"start"` | `"center"` | `"end"` | `"stretch"`
-- `justify` — `"start"` | `"center"` | `"end"` | `"space-between"`
-- `wrap` — boolean
-- `fullWidth` — boolean
-
-### Modal
-- `isOpen` / `onClose` — controlled open state
-- `title` — modal title
-- `footer` — footer content (ReactNode)
-
-### Sticker
-- `variant` — `"blue"` | `"teal"` | `"green"` | `"yellow"` | `"orange"` | `"red"` | `"purple"` | `"darkGrey"` | `"white"` | `"success"` | `"danger"` | `"caution"` | `"basic"` | `"grey"`
-- `icon` — optional icon component (use 12px icons)
-- `onDismiss` — dismiss button callback
-- `required` — boolean, shows asterisk
-
-## Key File Paths
-
-- `@persona/design-system/components/ConfigFormGroup/ConfigFormGroup.tsx`
-- `@persona/design-system/components/FormField/FormField.tsx`
-- `@persona/design-system/components/Input/Input.tsx`
-- `@persona/design-system/components/TextArea/TextArea.tsx`
-- `@persona/design-system/components/ListBox/ListBox.tsx`
-- `@persona/design-system/components/TableBox/TableBox.tsx`
-- `@persona/design-system/components/FormField/TableBoxField.tsx`
-- `@persona/design-system/components/CardV2/Card.tsx`
-- `@persona/design-system/components/Stack/Stack.tsx`
-- `@persona/design-system/components/Text/` (Heading, Paragraph, Label)
-- `@persona/design-system/components/Sticker/Sticker.tsx`
-- `@persona/design-system/components/Modal/Modal.tsx`
-- `@persona/design-system/components/Popover/Popover.tsx`
-- `@persona/design-system/utils/testing.tsx`
-- `@persona/design-system/components/DataTable/`