{ "$schema": "https://loui.dev/schemas/manifest.schema.json", "schemaVersion": 1, "package": { "name": "loui-ds", "version": "0.7.4" }, "generator": "scripts/manifest/build.ts", "entryPoints": [ { "path": ".", "importPath": "loui-ds", "description": "Core components, hooks, i18n and utilities." }, { "path": "./patterns", "importPath": "loui-ds/patterns", "description": "Domain patterns (generic names). Empty until patterns land." }, { "path": "./styles.css", "importPath": "loui-ds/styles.css", "description": "Layered CSS: tokens (--ds-*), base and every component." } ], "counts": { "components": 120, "hooks": 11, "utilities": 46, "icons": 40, "recipes": 13 }, "components": [ { "name": "Accordion", "kind": "component", "entryPoint": "loui-ds", "importStatement": "import { Accordion } from 'loui-ds';", "folder": "src/components/Accordion", "sourceFile": "src/components/Accordion/Accordion.tsx", "status": "experimental", "statusSource": "doc", "description": "A stack of sections that expand and collapse. Each header is a heading that wraps a real\nbutton (`aria-expanded`, `aria-controls`), so it appears in the page outline and works with\n`Enter` and `Space`. Built on React Aria `DisclosureGroup`.\n\nUse it to shorten a long page of related, optional content (FAQs, settings groups). Do not\nhide content people need to finish their task.", "props": [ { "name": "items", "type": "readonly AccordionItem[]", "required": true, "description": "The sections, in order." }, { "name": "multiple", "type": "boolean", "required": false, "default": "false", "description": "Allow several sections open at once. By default opening one section closes the others\n(single expansion)." }, { "name": "value", "type": "readonly string[]", "required": false, "description": "Values of the expanded items (controlled)." }, { "name": "defaultValue", "type": "readonly string[]", "required": false, "default": "[]", "description": "Values of the items expanded at first (uncontrolled)." }, { "name": "onChange", "type": "(value: string[]) => void", "required": false, "description": "Called with the values of all expanded items after the user toggles one." }, { "name": "variant", "type": "'bordered' | 'plain'", "required": false, "default": "'bordered'", "description": "`bordered` (default) draws a card around the sections; `plain` only draws dividers.", "values": ["bordered", "plain"] }, { "name": "headingLevel", "type": "2 | 3 | 4 | 5 | 6", "required": false, "default": "3", "description": "Level of the heading that wraps each trigger, `3` by default. Use the level that follows\nthe heading above the accordion in the page outline.", "values": ["2", "3", "4", "5", "6"] }, { "name": "isDisabled", "type": "boolean", "required": false, "default": "false", "description": "Disables every section." }, { "name": "className", "type": "string", "required": false, "description": "" }, { "name": "ref", "type": "Ref", "required": false, "description": "Ref to the root element." } ], "inheritedProps": [ { "source": "@react-types/shared", "interface": "DOMProps", "domGeneric": false, "count": 1, "props": [ { "name": "id", "type": "string", "required": false } ] }, { "source": "@react-types/shared", "interface": "GlobalDOMAttributes", "domGeneric": true, "count": 6 }, { "source": "@react-types/shared", "interface": "GlobalDOMEvents", "domGeneric": true, "count": 64 } ], "variants": { "variant": ["bordered", "plain"] }, "cssVariables": [ "--ds-accent", "--ds-accordion-padding-inline", "--ds-duration", "--ds-ease", "--ds-font-mono", "--ds-font-sans", "--ds-fs-caption", "--ds-fs-small", "--ds-icon-sm", "--ds-lh-caption", "--ds-lh-small", "--ds-line", "--ds-line-subtle", "--ds-opacity-disabled", "--ds-radius-lg", "--ds-row-h", "--ds-space-3", "--ds-space-4", "--ds-surface", "--ds-surface-row-hover", "--ds-text", "--ds-text-2", "--ds-text-3", "--ds-weight-medium", "--ds-weight-regular" ], "stories": { "title": "Components/Accordion", "tags": ["autodocs"], "items": [ { "name": "Default", "id": "components-accordion--default", "hasPlay": true }, { "name": "Plain", "id": "components-accordion--plain", "hasPlay": false }, { "name": "InitiallyExpanded", "id": "components-accordion--initially-expanded", "hasPlay": true }, { "name": "KeyboardSingle", "id": "components-accordion--keyboard-single", "description": "Enter and Space toggle the focused header; opening one closes the others.", "hasPlay": true }, { "name": "Multiple", "id": "components-accordion--multiple", "hasPlay": true }, { "name": "DisabledItem", "id": "components-accordion--disabled-item", "hasPlay": true }, { "name": "HeadingLevel2", "id": "components-accordion--heading-level2", "hasPlay": true }, { "name": "Controlled", "id": "components-accordion--controlled", "hasPlay": true }, { "name": "LongText", "id": "components-accordion--long-text", "hasPlay": false }, { "name": "RightToLeft", "id": "components-accordion--right-to-left", "hasPlay": false }, { "name": "Focused", "id": "components-accordion--focused", "hasPlay": true } ] }, "docs": { "path": "src/components/Accordion/Accordion.md", "summary": "A stack of sections that expand and collapse. Each header is a heading that wraps a real button. Built on React Aria `DisclosureGroup`, `Disclosure` and `DisclosurePanel`.\n\n- Handoff source: `components/layout/Accordion.jsx` (TODO `CMP-LAY-04`).", "whenToUse": [ "FAQs, grouped settings, long optional detail on a record.", "To shorten a page whose sections people read one at a time." ], "whenNotToUse": [ "For content people must see to finish the task.", "For switching between views: use `Tabs`.", "For a single show/hide of one block: a plain disclosure is enough." ], "keyboard": [ "Keys: `Tab` moves between triggers; `Enter` and `Space` toggle. Optional arrow-key movement between headers (APG) is not added: each trigger is a tab stop." ], "examples": [ "\n\n" ], "sections": [ { "id": "when-to-use", "heading": "When to use", "content": "- FAQs, grouped settings, long optional detail on a record.\n- To shorten a page whose sections people read one at a time." }, { "id": "when-not-to-use", "heading": "When not to use", "content": "- For content people must see to finish the task.\n- For switching between views: use `Tabs`.\n- For a single show/hide of one block: a plain disclosure is enough." }, { "id": "props", "heading": "Props", "content": "| Prop | Type | Default | Notes |\n| ------------------------ | --------------------------- | ------------ | ----------------------------------------------------------------------- |\n| `items` | `AccordionItem[]` | required | `{ value, title, meta?, content, isDisabled? }`. |\n| `multiple` | `boolean` | `false` | Several sections open at once. Otherwise opening one closes the others. |\n| `value` / `defaultValue` | `string[]` | `[]` | Expanded values, controlled / uncontrolled. |\n| `onChange` | `(value: string[]) => void` | none | All expanded values after a toggle. |\n| `variant` | `'bordered' \\| 'plain'` | `'bordered'` | `bordered`: card border and surface. `plain`: dividers only. |\n| `headingLevel` | `2`-`6` | `3` | Level of the heading around each trigger; follow the page outline. |\n| `isDisabled` | `boolean` | `false` | Disables every section. |\n\n`ref` points to the root; `className` and other attributes pass through." }, { "id": "accessibility", "heading": "Accessibility", "content": "- Each header is `h3` (configurable) containing a `button` with `aria-expanded` and `aria-controls`; the panel is a `group` labelled by the button. Headings appear in the page outline and in screen reader heading lists.\n- Keys: `Tab` moves between triggers; `Enter` and `Space` toggle. Optional arrow-key movement between headers (APG) is not added: each trigger is a tab stop.\n- Collapsed panels are hidden (`hidden=\"until-found\"`), so find-in-page can open them, and they take no space.\n- The chevron rotates 180 degrees to show the state; the state itself is `aria-expanded`, not the icon. Under `prefers-reduced-motion` the rotation is instant.\n- The focus indicator is an inset accent outline because the group clips overflow. Forced colors use `Highlight`.\n- Disabled items are not focusable.\n- Meta text is read after the title; keep it short." }, { "id": "content-rules", "heading": "Content rules", "content": "- Titles are short phrases or questions in sentence case, and say what is inside.\n- Do not put the only copy of important information in a collapsed panel." }, { "id": "examples", "heading": "Examples", "content": "```tsx\n\n\n\n```" }, { "id": "differences-from-the-handoff", "heading": "Differences from the handoff", "content": "- The trigger is wrapped in a heading and linked to its panel (`aria-controls`, labelled panel); the handoff had a bare `button` and no panel relationship.\n- `multiple` and controlled `value` / `onChange` replace the internal-only `defaultValue` array.\n- `variant=\"plain\"` replaces `bordered={false}`. The chevron is the shared `ChevronDownIcon` that rotates (down collapsed, up expanded), instead of a custom right-pointing SVG.\n- Not included yet: height animation of the panel (the chevron animates; the panel appears instantly) and arrow-key movement between headers." } ] }, "related": { "alternatives": [ { "name": "Tabs", "reason": "For switching between views: use `Tabs`." } ], "uses": ["Icon"], "usedBy": [] } }, { "name": "ActionList", "kind": "component", "entryPoint": "loui-ds", "importStatement": "import { ActionList } from 'loui-ds';", "folder": "src/components/ActionList", "sourceFile": "src/components/ActionList/ActionList.tsx", "status": "experimental", "statusSource": "doc", "description": "A vertical list of records, each with a title, optional description, a mono meta value and a\n\"more actions\" menu, with optional row checkboxes (`selectionMode=\"multiple\"`). Built on React Aria `GridList`: rows are reached with the arrow keys\n(one tab stop for the list), `Enter` runs `onAction`, and `Tab` or the right arrow moves\nfrom a row to its menu button.", "props": [ { "name": "items", "type": "readonly ActionListItem[]", "required": true, "description": "The rows, in the order given. The list never sorts: lists are alphabetical by default in\nthis design system, so sort with `sortByText` before passing them (tasks by urgency and\ndated records newest first are the exceptions)." }, { "name": "className", "type": "string", "required": false, "description": "Class name for the list root." }, { "name": "ref", "type": "Ref", "required": false, "description": "Ref to the list root element." }, { "name": "onAction", "type": "(item: ActionListItem) => void", "required": false, "description": "Called when the user activates a row (click, or Enter on the focused row). Makes the whole\nrow a press target with hover and pointer cursor. The menu button does not trigger it." }, { "name": "selectionMode", "type": "'none' | 'multiple'", "required": false, "default": "'none'", "description": "Adds a checkbox at the start of every row. `'multiple'` toggles rows independently (the\ncheckbox toggles, the row still runs `onAction`). Default `'none'`.", "values": ["none", "multiple"] }, { "name": "selectedKeys", "type": "\"all\" | Iterable", "required": false, "description": "Controlled selected row ids. Use together with `onSelectionChange`." }, { "name": "defaultSelectedKeys", "type": "\"all\" | Iterable", "required": false, "description": "Initially selected row ids (uncontrolled)." }, { "name": "onSelectionChange", "type": "(keys: Selection) => void", "required": false, "description": "Called when the checkbox of a row is toggled (click, or `Space` on the focused row or\ncheckbox). The list never shows an Undo toast itself: update your state, then call\n`toastWithUndo` (reversible toggles never ask for confirmation)." }, { "name": "bordered", "type": "boolean", "required": false, "default": "true", "description": "Draws the border, surface and radius around the list. Turn off inside a `Card`. Default `true`." }, { "name": "emptyState", "type": "ReactNode", "required": false, "description": "Content when `items` is empty. Default: an `EmptyState` with built-in text." }, { "name": "messages", "type": "Partial<{ moreActions: (title: string) => string; select: string; done: string; emptyTitle: string; emptyDescription: string; }>", "required": false, "description": "Per-instance overrides of the built-in messages." }, { "name": "aria-label", "type": "string", "required": false, "description": "Accessible name of the list. Required unless `aria-labelledby` is set." }, { "name": "aria-labelledby", "type": "string", "required": false, "description": "Id of the element that names the list (a visible heading)." } ], "inheritedProps": [ { "source": "react-aria", "interface": "AriaGridListProps", "domGeneric": false, "count": 2, "props": [ { "name": "escapeKeyBehavior", "type": "'none' | 'clearSelection'", "required": false }, { "name": "keyboardNavigationBehavior", "type": "'arrow' | 'tab'", "required": false } ] }, { "source": "@react-types/shared", "interface": "AriaLabelingProps", "domGeneric": false, "count": 2, "props": [ { "name": "aria-describedby", "type": "string", "required": false }, { "name": "aria-details", "type": "string", "required": false } ] }, { "source": "@react-types/shared", "interface": "DOMProps", "domGeneric": false, "count": 1, "props": [ { "name": "id", "type": "string", "required": false } ] }, { "source": "react-aria", "interface": "GridListProps", "domGeneric": false, "count": 3, "props": [ { "name": "autoFocus", "type": "boolean | FocusStrategy", "required": false }, { "name": "disabledBehavior", "type": "'all' | 'selection'", "required": false }, { "name": "shouldSelectOnPressUp", "type": "boolean", "required": false } ] }, { "source": "react-aria-components", "interface": "GridListProps", "domGeneric": false, "count": 1, "props": [ { "name": "disallowTypeAhead", "type": "boolean", "required": false } ] }, { "source": "react-aria-components", "interface": "SlotProps", "domGeneric": false, "count": 1, "props": [ { "name": "slot", "type": "string | null", "required": false } ] }, { "source": "@react-types/shared", "interface": "GlobalDOMAttributes", "domGeneric": true, "count": 6 }, { "source": "@react-types/shared", "interface": "GlobalDOMEvents", "domGeneric": true, "count": 64 } ], "variants": {}, "messages": { "providerKey": "ActionList", "locales": ["en", "pt-BR"], "keys": [ { "key": "moreActions", "kind": "function", "default": "More actions for {title}", "signature": "(title: string)", "description": "Accessible name of the row actions button. `title` is the text of the row (\"More actions for Price list\")." }, { "key": "select", "kind": "string", "default": "Select", "description": "Start of the accessible name of a row checkbox. React Aria appends the text of the row\n(\"Select\" + \"Price list 2026\"), so keep it a bare verb." }, { "key": "done", "kind": "string", "default": "Done", "description": "Visually hidden text added to a row marked `isDone`, read after the title." }, { "key": "emptyTitle", "kind": "string", "default": "No items found", "description": "Title of the default empty state." }, { "key": "emptyDescription", "kind": "string", "default": "Try another filter or search term.", "description": "Description of the default empty state." } ] }, "cssVariables": [ "--ds-accent", "--ds-font-mono", "--ds-fs-label", "--ds-fs-small", "--ds-lh-label", "--ds-line", "--ds-line-subtle", "--ds-radius-lg", "--ds-row-h", "--ds-space-1", "--ds-space-2", "--ds-space-3", "--ds-surface", "--ds-surface-row-hover", "--ds-text", "--ds-text-2", "--ds-text-3", "--ds-weight-medium" ], "stories": { "title": "Components/ActionList", "tags": ["autodocs"], "items": [ { "name": "Default", "id": "components-action-list--default", "description": "Rows are listed in the order given; sort with `sortByText` for the alphabetical default.", "hasPlay": true }, { "name": "Actionable", "id": "components-action-list--actionable", "description": "With `onAction` the whole row is a press target; the menu button does not trigger it.", "hasPlay": true }, { "name": "KeyboardNavigation", "id": "components-action-list--keyboard-navigation", "description": "The arrow keys, Home and End move between rows; the right arrow reaches the row menu.", "hasPlay": true }, { "name": "RowMenu", "id": "components-action-list--row-menu", "description": "Enter opens the row menu, Escape closes it and returns focus to the button.", "hasPlay": true }, { "name": "Borderless", "id": "components-action-list--borderless", "hasPlay": false }, { "name": "WithLeadingAndLongText", "id": "components-action-list--with-leading-and-long-text", "hasPlay": false }, { "name": "DisabledRow", "id": "components-action-list--disabled-row", "hasPlay": false }, { "name": "Empty", "id": "components-action-list--empty", "hasPlay": true }, { "name": "CustomEmpty", "id": "components-action-list--custom-empty", "hasPlay": false }, { "name": "PortugueseBrazil", "id": "components-action-list--portuguese-brazil", "description": "Row action button names, the empty state and numbers follow the provider locale.", "hasPlay": true }, { "name": "WithCheckboxes", "id": "components-action-list--with-checkboxes", "description": "`selectionMode=\"multiple\"` adds a named checkbox to each row; `Space` toggles it.", "hasPlay": true }, { "name": "CheckboxWithRowActionAndMenu", "id": "components-action-list--checkbox-with-row-action-and-menu", "description": "Checkbox, row action and menu together: the checkbox toggles, `Enter` or a click runs the action.", "hasPlay": true }, { "name": "TaskRows", "id": "components-action-list--task-rows", "description": "Task rows: control on the left, module label and due chip in `meta`, menu on the right.", "hasPlay": false }, { "name": "DoneRows", "id": "components-action-list--done-rows", "description": "`isDone` strikes the title through and adds a hidden \"Done\" for screen readers.", "hasPlay": true }, { "name": "CheckboxesLongText", "id": "components-action-list--checkboxes-long-text", "hasPlay": false }, { "name": "CheckboxesDisabledRow", "id": "components-action-list--checkboxes-disabled-row", "hasPlay": false }, { "name": "ToggleWithUndo", "id": "components-action-list--toggle-with-undo", "description": "Consumer pattern for reversible toggles: update the state, then `toastWithUndo`. The list never\nasks for confirmation and never toggles silently.", "hasPlay": true } ] }, "docs": { "path": "src/components/ActionList/ActionList.md", "summary": "A vertical list of records. Each row has an optional leading node, a title, an optional description, a mono meta value and an optional \"more actions\" menu. Built on React Aria `GridList`, so rows are reachable with the arrow keys and can run an action.", "whenToUse": [ "Short lists of things with a few actions each: files, saved filters, members, recent items.", "One main line of text per record, with secondary detail." ], "whenNotToUse": [ "Many comparable columns or sorting: use `DataTable`.", "Navigation between pages: use `NavItem` or `Tabs`.", "Choosing options in a form: use `RadioGroup`, `CheckboxGroup` or `Select`." ], "keyboard": [ "Keyboard: `Tab` enters the list on one row (one tab stop); Arrow Up/Down, Home and End move between rows; Arrow Right moves from the row to its menu button (Arrow Left back); `Enter` on a row runs `onAction`; the menu button follows the Menu contract (`Enter`/`Space`/`Arrow Down` opens, `Escape` closes and focus returns to the button).", "With `selectionMode=\"multiple\"`: `Space` on the focused row (or on its checkbox) toggles it, `Enter` and a click on the row content run `onAction`, a click on the checkbox toggles. Each checkbox is named \"Select {title}\" (React Aria composes the message `select` with the row text). `Tab`/`ArrowRight` moves from the row to its checkbox and menu button." ], "examples": [ " f.name, locale).map((file) => ({\n id: file.id,\n title: file.name,\n description: `Updated by ${file.author}`,\n meta: formatBytes(file.size),\n actions: (\n <>\n download(file)}>Download file\n \n askToDelete(file)}>\n Delete file\n \n \n ),\n }))}\n onAction={(item) => openFile(item.id)}\n/>" ], "sections": [ { "id": "when-to-use", "heading": "When to use", "content": "- Short lists of things with a few actions each: files, saved filters, members, recent items.\n- One main line of text per record, with secondary detail." }, { "id": "when-not-to-use", "heading": "When not to use", "content": "- Many comparable columns or sorting: use `DataTable`.\n- Navigation between pages: use `NavItem` or `Tabs`.\n- Choosing options in a form: use `RadioGroup`, `CheckboxGroup` or `Select`." }, { "id": "anatomy", "heading": "Anatomy", "content": "```\ndiv[role=grid] named by aria-label / aria-labelledby\n div[role=row] one tab stop for the whole list; arrow keys move between rows\n Checkbox selection optional (selectionMode=\"multiple\"), named \"Select {title}\"\n span leading optional (Avatar, Icon)\n span title / description\n span meta mono, text-2; a node: a module label plus a Badge / DueIndicator\n MoreActionsMenu IconButton \"More actions for {title}\" + Menu (optional)\n```\n\nIn a list 480 px wide or narrower (a container query on the list, not the viewport), `meta` moves under the title and description, so a long title keeps its width instead of shrinking to a few characters next to a due chip." }, { "id": "props-key-ones", "heading": "Props (key ones)", "content": "| Prop | Type | Default | Notes |\n| -------------------------------------- | --------------------------- | -------- | ----------------------------------------------------------------------------------------------- |\n| `items` | `ActionListItem[]` | - | `id`, `title`, `textValue`, `description`, `meta`, `leading`, `actions`, `isDisabled`, `isDone` |\n| `aria-label` | `string` | - | Required (or `aria-labelledby`) |\n| `onAction` | `(item) => void` | | Row click or Enter. Makes the row a press target |\n| `selectionMode` | `'none' \\| 'multiple'` | `'none'` | `'multiple'` adds a checkbox to every row (toggle behavior) |\n| `selectedKeys` / `defaultSelectedKeys` | `'all' \\| Iterable` | | Controlled / initial selected row ids |\n| `onSelectionChange` | `(keys: Selection) => void` | | Called when a checkbox is toggled. The consumer owns Undo |\n| `bordered` | `boolean` | `true` | Border, surface and radius. Turn off inside a `Card` |\n| `emptyState` | `ReactNode` | | Default: compact `EmptyState` with built-in text |\n| `messages` | `Partial` | | `moreActions(title)`, `select`, `done`, `emptyTitle`, `emptyDescription` |\n\n`actions` is a node: `MenuItem`, `MenuSection` and `MenuSeparator` elements from `Menu`. Put the handler on the item (``). Destructive items use `tone=\"danger\"` and still ask for confirmation in a dialog.\n\nThe list renders `items` in the order given. Lists are alphabetical by default in this design system: pass them through `sortByText` first (exceptions: tasks by urgency, dated records newest first)." }, { "id": "checkbox-rows-and-done-state", "heading": "Checkbox rows and done state", "content": "```tsx\nconst [done, setDone] = useState>(new Set());\n\n {\n if (keys === 'all') return;\n const before = done;\n setDone(new Set([...keys].map(String)));\n toastWithUndo('Task updated', { onUndo: () => setDone(before) });\n }}\n onAction={(task) => openTask(task.id)}\n items={tasks.map((task) => ({\n id: task.id,\n title: task.name,\n isDone: done.has(task.id),\n meta: (\n <>\n {task.module}\n \n \n ),\n actions: edit(task)}>Edit task,\n }))}\n/>;\n```\n\n- `isDone` and the checkbox are independent: the list does not derive one from the other. A to-do usually passes `isDone: selected` as above.\n- `isDone` sets the title to `text-3` with a line-through (also in forced colors) and adds a visually hidden \"Done\" after the title (`messages.done`), so the state is never color or decoration alone.\n- Toggling is reversible, so it never asks for confirmation. The list does not toggle silently with undo built in: show `toastWithUndo` from `onSelectionChange` as above." }, { "id": "design-note-gap-017-gap-015", "heading": "Design note (GAP-017, GAP-015)", "content": "Decision: extend `ActionList`; no separate `CheckList`. A checkbox list is the same anatomy (title, description, meta, menu) plus a leading control, and consumers need both the checkbox and the row action, which is what `GridList` models. Only `selectionMode: 'none' | 'multiple'` is exposed with `selectionBehavior=\"toggle\"` fixed; `single` is a different pattern (`RadioGroup`, `ListBox`). The \"control, module label, due chip, actions\" row is built with the existing slots: the checkbox is the selection control, `meta` accepts nodes (module label plus `Badge` or `DueIndicator`), `actions` is the menu. No new slot was needed.\n\nReact Aria turns a row into a pure selection toggle as soon as one row is selected, which would silence `onAction`. With `selectionMode=\"multiple\"` the list therefore handles the row action itself (click on the row content, `Enter` on the focused row), so it works whether or not rows are selected. Only the checkbox and `Space` toggle selection." }, { "id": "accessibility", "heading": "Accessibility", "content": "- `GridList` gives `role=\"grid\"` with `row` and `gridcell` roles; rows are not a `list`/`listitem` pair because they are focusable and actionable.\n- Each selection checkbox is named \"Select {title}\" (pt-BR \"Selecionar {title}\"): the `select` message plus the row's plain-text name, never the meta. A `title` that is not a string needs `textValue`; without it the name falls back to the row `id` and a development warning says so.\n- Keyboard: `Tab` enters the list on one row (one tab stop); Arrow Up/Down, Home and End move between rows; Arrow Right moves from the row to its menu button (Arrow Left back); `Enter` on a row runs `onAction`; the menu button follows the Menu contract (`Enter`/`Space`/`Arrow Down` opens, `Escape` closes and focus returns to the button).\n- With `selectionMode=\"multiple\"`: `Space` on the focused row (or on its checkbox) toggles it, `Enter` and a click on the row content run `onAction`, a click on the checkbox toggles. Each checkbox is named \"Select {title}\" (React Aria composes the message `select` with the row text). `Tab`/`ArrowRight` moves from the row to its checkbox and menu button.\n- Every menu button has its own name (\"More actions for Price list 2026\") so a screen reader user can tell them apart.\n- Row actions never rely on color; the meta value is text. Disabled rows are dimmed and skipped.\n- Known quirk: React Aria moves focus to the row after an overlay inside a row closes. The component hands focus back to the button that was pressed." }, { "id": "content-rules", "heading": "Content rules", "content": "- Titles are the record name, not a sentence. Descriptions say who or when (\"Updated by Ana\").\n- Menu items are verb + object (\"Download file\", \"Delete file\")." }, { "id": "examples", "heading": "Examples", "content": "```tsx\n f.name, locale).map((file) => ({\n id: file.id,\n title: file.name,\n description: `Updated by ${file.author}`,\n meta: formatBytes(file.size),\n actions: (\n <>\n download(file)}>Download file\n \n askToDelete(file)}>\n Delete file\n \n \n ),\n }))}\n onAction={(item) => openFile(item.id)}\n/>\n```" }, { "id": "differences-from-the-handoff", "heading": "Differences from the handoff", "content": "- Real list semantics and keyboard support (`GridList`) instead of clickable `div`s; rows can be activated with `Enter`.\n- The `···` button is the shared `MoreActionsMenu` (label from messages, names the row, `Menu` keyboard model) instead of a hand-made popover.\n- `actions` is a `MenuItem` node (composition) instead of an array of `{ label, danger, separator }`; `onItemClick` is `onAction`; `title`/`description`/`meta` accept nodes.\n- Text uses `text-2` for descriptions (contrast stays above 4.5:1 on hover and raised surfaces).\n- Empty state and disabled rows added. Drag handle is not included." } ] }, "related": { "alternatives": [ { "name": "DataTable", "reason": "Many comparable columns or sorting: use `DataTable`." }, { "name": "NavItem", "reason": "Navigation between pages: use `NavItem` or `Tabs`." }, { "name": "Tabs", "reason": "Navigation between pages: use `NavItem` or `Tabs`." }, { "name": "RadioGroup", "reason": "Choosing options in a form: use `RadioGroup`, `CheckboxGroup` or `Select`." }, { "name": "CheckboxGroup", "reason": "Choosing options in a form: use `RadioGroup`, `CheckboxGroup` or `Select`." }, { "name": "Select", "reason": "Choosing options in a form: use `RadioGroup`, `CheckboxGroup` or `Select`." } ], "uses": ["Checkbox", "EmptyState", "MoreActionsMenu", "VisuallyHidden"], "usedBy": [] } }, { "name": "AddCard", "kind": "component", "entryPoint": "loui-ds", "importStatement": "import { AddCard } from 'loui-ds';", "folder": "src/components/AddCard", "sourceFile": "src/components/AddCard/AddCard.tsx", "status": "experimental", "statusSource": "doc", "description": "A dashed \"create new\" tile that sits in a grid next to cards. The whole tile is one link\n(`href`) or button (`onPress`) with a centred plus icon and a verb-plus-object label. It\nstretches to the height of its row.", "props": [ { "name": "children", "type": "ReactNode", "required": true, "description": "Label: a short verb plus object in sentence case (\"Create agent\"). It is the accessible name." }, { "name": "href", "type": "string", "required": false, "description": "Destination of the create flow. Renders a real ``." }, { "name": "target", "type": "string", "required": false, "description": "Link target. `_blank` adds `rel=\"noopener noreferrer\"` and a hidden \"opens in a new tab\" note." }, { "name": "rel", "type": "string", "required": false, "description": "Link relationship, merged with `noopener noreferrer` for `_blank`." }, { "name": "onPress", "type": "((event: PressEvent) => void) | ((event: PressEvent) => void)", "required": false, "description": "Fired when the link is pressed, before navigation.\nAction run when the tile is pressed (usually opens a dialog). Renders a real `}>\n \n \n }\n detail={selected ? : undefined}\n>\n \n" ], "sections": [ { "id": "when-to-use", "heading": "When to use", "content": "- The frame of every screen of an app: `Sidebar` + `TopBar` + content (+ optional detail pane)." }, { "id": "when-not-to-use", "heading": "When not to use", "content": "- A marketing page or a single-column document: use `Container` and let the page scroll.\n- Inside another AppShell." }, { "id": "anatomy", "heading": "Anatomy", "content": "```\ndiv.root (container, fills the parent, no page scroll)\n SkipLink first focusable element\n div.nav wraps the Sidebar (aside); off-canvas below md\n div.scrim only when the panel is open\n div.column\n TopBar header\n div.body\n main#main scrolls on its own\n aside \"Details\" optional, 360px, scrolls on its own\n```" }, { "id": "props", "heading": "Props", "content": "| Prop | Type | Default | Notes |\n| ------------------------------------------------ | --------------------------------- | --------- | ------------------------------------------------------------------- |\n| `sidebar` | `ReactNode` | | A `Sidebar` |\n| `topBar` | `ReactNode` | | A `TopBar`; put `` in its `children` |\n| `children` | `ReactNode` | | The page, inside the one `main` |\n| `detail`, `detailLabel` | `ReactNode`, `string` | \"Details\" | Optional aside at the inline end (`--ds-app-shell-detail-w`, 360px) |\n| `mainId` | `string` | `'main'` | `id` of `main` and the skip link target |\n| `padded` | `boolean` | `true` | Pads `main` (24px); turn off for content with its own padding |\n| `skipLink` | `boolean` | `true` | |\n| `isNavOpen`, `defaultNavOpen`, `onNavOpenChange` | | `false` | Off-canvas sidebar state (below md) |\n| `messages` | `{ navToggle, navClose, detail }` | | Per-instance overrides |\n\nThe shell is `100dvh` tall (capped by its parent's height): give the parent a height to embed it." }, { "id": "responsive-decision-tok-010", "heading": "Responsive decision (TOK-010)", "content": "**The DS guarantees every component works from 320px wide, and AppShell collapses its sidebar into an off-canvas panel below `--ds-breakpoint-md` (768px).**\n\nWhy built in rather than left to apps: a sidebar hidden by an app without a way back strands keyboard and touch users, and every product would build the same panel. It is kept simple: it reuses the same `Sidebar` element (no second copy, no lost state) and CSS does the layout.\n\n- The shell measures **its own width** with a container query, so it behaves the same in a frame, a preview or a test. The 768px in the CSS is `--ds-breakpoint-md`; CSS cannot read variables inside a query, so `AppShell.test.tsx` asserts the two agree at 767/768px.\n- From md up the sidebar sits in the flow. Below, it leaves the flow; `AppShellNavToggle` (visible only below md) opens it as a panel over a scrim.\n- While open: focus moves into the panel, the rest of the page is `inert`, `Escape`, the scrim or the \"Close menu\" button close it, and focus returns to the toggle. It is not a `Dialog`: it keeps the sidebar's own landmarks.\n- An empty detail leaves nothing behind: `detail` set to `null`, `undefined` or `false` renders no aside, and a component that renders `null` leaves an empty aside that is hidden (`:empty`), so no landmark and no 360px column stay. Prefer `detail={selected ? : undefined}`.\n- The detail pane moves **under** the main content (half the height at most, own scroll) below md.\n- Breakpoint tokens: `--ds-breakpoint-sm|md|lg|xl` (480 / 768 / 1024 / 1280 px); content: `--ds-content-max`, `--ds-content-gutter`; `--ds-container-sm|md|lg`." }, { "id": "accessibility", "heading": "Accessibility", "content": "- Landmarks: `aside` (Sidebar, \"Sidebar\"), `header` (TopBar), **one** `main`, optional `aside` (\"Details\"). Each `nav` in the sidebar is named by its caption.\n- The skip link is the first stop and moves focus to `main`.\n- `main` and the detail aside scroll independently. While they overflow they become keyboard stops (`tabindex=\"0\"`) so the arrow keys scroll them; with nothing to scroll there is no extra tab stop.\n- The closed panel is `visibility: hidden` and `inert`, so it is out of the tab order and the accessibility tree.\n- The panel slide respects `prefers-reduced-motion`; the layout mirrors in RTL.\n- `AppShellNavToggle` reports `aria-expanded` and `aria-controls`. It is an `IconButton` (menu icon) named \"Menu\" (`pt-BR` \"Menu\"; pass a string child to rename it); the close button is an `IconButton` (x icon) named \"Close menu\" / \"Fechar menu\", which sits on the scrim beside the panel and never wraps." }, { "id": "content-rules", "heading": "Content rules", "content": "- One `h1` per page: `TopBar` renders it from `title`.\n- One primary action per screen, at the end of the top bar." }, { "id": "examples", "heading": "Examples", "content": "```tsx\n}\n topBar={\n New order}>\n \n \n }\n detail={selected ? : undefined}\n>\n \n\n```" }, { "id": "differences-from-the-handoff", "heading": "Differences from the handoff", "content": "- The handoff assumed a 1180px minimum width and a fixed 240px sidebar. The shell now works from 320px, and the sidebar width stays a token.\n- The skip link, the single `main` and the independent scrolling were left to each screen; the shell provides them." } ] }, "related": { "alternatives": [ { "name": "Container", "reason": "A marketing page or a single-column document: use `Container` and let the page scroll." } ], "uses": ["IconButton", "SkipLink"], "usedBy": [] } }, { "name": "AppShellNavToggle", "kind": "component", "entryPoint": "loui-ds", "importStatement": "import { AppShellNavToggle } from 'loui-ds';", "folder": "src/components/AppShell", "sourceFile": "src/components/AppShell/AppShell.tsx", "status": "experimental", "statusSource": "doc", "description": "The icon button (menu icon) that opens the off-canvas sidebar. Put it in the `TopBar` (as its `children`).\nIt is only visible below the md breakpoint, and reports `aria-expanded`. It must be rendered\ninside `AppShell`.", "props": [ { "name": "children", "type": "string", "required": false, "description": "Accessible name of the icon button. Default \"Menu\" from the message catalog." }, { "name": "className", "type": "string", "required": false, "description": "Class name for the wrapper." } ], "inheritedProps": [], "variants": {}, "cssVariables": [ "--ds-accent", "--ds-app-shell-detail-w", "--ds-app-shell-main-padding", "--ds-app-shell-nav-z-index", "--ds-bg", "--ds-duration", "--ds-ease", "--ds-font-sans", "--ds-line-control", "--ds-line-subtle", "--ds-scrim", "--ds-shadow-dialog", "--ds-space-1", "--ds-space-12", "--ds-space-2", "--ds-space-3", "--ds-text", "--ds-toast-clearance" ], "stories": { "title": "Layout/AppShell", "tags": ["autodocs"], "items": [ { "name": "Default", "id": "layout-app-shell--default", "description": "Sidebar on the left, top bar and scrolling content on the right. The sidebar and the content scroll apart.", "hasPlay": true }, { "name": "WithDetail", "id": "layout-app-shell--with-detail", "description": "The detail aside (360px) holds the record selected in the content.", "hasPlay": false }, { "name": "WithoutSidebar", "id": "layout-app-shell--without-sidebar", "description": "Without a sidebar the shell is a header and content.", "hasPlay": false }, { "name": "Unpadded", "id": "layout-app-shell--unpadded", "description": "Content without padding, for a table or a page that brings its own container.", "hasPlay": false }, { "name": "LongContent", "id": "layout-app-shell--long-content", "description": "Content taller than the viewport scrolls inside `main`; the top bar stays put.", "hasPlay": false }, { "name": "NarrowClosed", "id": "layout-app-shell--narrow-closed", "description": "Narrow screens: the sidebar leaves the flow; the Menu button opens it as a panel.", "hasPlay": true }, { "name": "NarrowOpen", "id": "layout-app-shell--narrow-open", "description": "Open: focus moves into the panel, the content is inert, Escape or the scrim closes it.", "hasPlay": true }, { "name": "Narrow320", "id": "layout-app-shell--narrow320", "description": "The smallest supported width.", "hasPlay": false }, { "name": "RightToLeft", "id": "layout-app-shell--right-to-left", "hasPlay": false } ] }, "docs": { "path": "src/components/AppShell/AppShell.md", "summary": "The application layout: a sidebar, and a main column with a top bar above a scrollable content region. It includes the skip link and the landmarks.", "whenToUse": [ "The frame of every screen of an app: `Sidebar` + `TopBar` + content (+ optional detail pane)." ], "whenNotToUse": [ "A marketing page or a single-column document: use `Container` and let the page scroll.", "Inside another AppShell." ], "keyboard": [], "examples": [ "}\n topBar={\n New order}>\n \n \n }\n detail={selected ? : undefined}\n>\n \n" ], "sections": [ { "id": "when-to-use", "heading": "When to use", "content": "- The frame of every screen of an app: `Sidebar` + `TopBar` + content (+ optional detail pane)." }, { "id": "when-not-to-use", "heading": "When not to use", "content": "- A marketing page or a single-column document: use `Container` and let the page scroll.\n- Inside another AppShell." }, { "id": "anatomy", "heading": "Anatomy", "content": "```\ndiv.root (container, fills the parent, no page scroll)\n SkipLink first focusable element\n div.nav wraps the Sidebar (aside); off-canvas below md\n div.scrim only when the panel is open\n div.column\n TopBar header\n div.body\n main#main scrolls on its own\n aside \"Details\" optional, 360px, scrolls on its own\n```" }, { "id": "props", "heading": "Props", "content": "| Prop | Type | Default | Notes |\n| ------------------------------------------------ | --------------------------------- | --------- | ------------------------------------------------------------------- |\n| `sidebar` | `ReactNode` | | A `Sidebar` |\n| `topBar` | `ReactNode` | | A `TopBar`; put `` in its `children` |\n| `children` | `ReactNode` | | The page, inside the one `main` |\n| `detail`, `detailLabel` | `ReactNode`, `string` | \"Details\" | Optional aside at the inline end (`--ds-app-shell-detail-w`, 360px) |\n| `mainId` | `string` | `'main'` | `id` of `main` and the skip link target |\n| `padded` | `boolean` | `true` | Pads `main` (24px); turn off for content with its own padding |\n| `skipLink` | `boolean` | `true` | |\n| `isNavOpen`, `defaultNavOpen`, `onNavOpenChange` | | `false` | Off-canvas sidebar state (below md) |\n| `messages` | `{ navToggle, navClose, detail }` | | Per-instance overrides |\n\nThe shell is `100dvh` tall (capped by its parent's height): give the parent a height to embed it." }, { "id": "responsive-decision-tok-010", "heading": "Responsive decision (TOK-010)", "content": "**The DS guarantees every component works from 320px wide, and AppShell collapses its sidebar into an off-canvas panel below `--ds-breakpoint-md` (768px).**\n\nWhy built in rather than left to apps: a sidebar hidden by an app without a way back strands keyboard and touch users, and every product would build the same panel. It is kept simple: it reuses the same `Sidebar` element (no second copy, no lost state) and CSS does the layout.\n\n- The shell measures **its own width** with a container query, so it behaves the same in a frame, a preview or a test. The 768px in the CSS is `--ds-breakpoint-md`; CSS cannot read variables inside a query, so `AppShell.test.tsx` asserts the two agree at 767/768px.\n- From md up the sidebar sits in the flow. Below, it leaves the flow; `AppShellNavToggle` (visible only below md) opens it as a panel over a scrim.\n- While open: focus moves into the panel, the rest of the page is `inert`, `Escape`, the scrim or the \"Close menu\" button close it, and focus returns to the toggle. It is not a `Dialog`: it keeps the sidebar's own landmarks.\n- An empty detail leaves nothing behind: `detail` set to `null`, `undefined` or `false` renders no aside, and a component that renders `null` leaves an empty aside that is hidden (`:empty`), so no landmark and no 360px column stay. Prefer `detail={selected ? : undefined}`.\n- The detail pane moves **under** the main content (half the height at most, own scroll) below md.\n- Breakpoint tokens: `--ds-breakpoint-sm|md|lg|xl` (480 / 768 / 1024 / 1280 px); content: `--ds-content-max`, `--ds-content-gutter`; `--ds-container-sm|md|lg`." }, { "id": "accessibility", "heading": "Accessibility", "content": "- Landmarks: `aside` (Sidebar, \"Sidebar\"), `header` (TopBar), **one** `main`, optional `aside` (\"Details\"). Each `nav` in the sidebar is named by its caption.\n- The skip link is the first stop and moves focus to `main`.\n- `main` and the detail aside scroll independently. While they overflow they become keyboard stops (`tabindex=\"0\"`) so the arrow keys scroll them; with nothing to scroll there is no extra tab stop.\n- The closed panel is `visibility: hidden` and `inert`, so it is out of the tab order and the accessibility tree.\n- The panel slide respects `prefers-reduced-motion`; the layout mirrors in RTL.\n- `AppShellNavToggle` reports `aria-expanded` and `aria-controls`. It is an `IconButton` (menu icon) named \"Menu\" (`pt-BR` \"Menu\"; pass a string child to rename it); the close button is an `IconButton` (x icon) named \"Close menu\" / \"Fechar menu\", which sits on the scrim beside the panel and never wraps." }, { "id": "content-rules", "heading": "Content rules", "content": "- One `h1` per page: `TopBar` renders it from `title`.\n- One primary action per screen, at the end of the top bar." }, { "id": "examples", "heading": "Examples", "content": "```tsx\n}\n topBar={\n New order}>\n \n \n }\n detail={selected ? : undefined}\n>\n \n\n```" }, { "id": "differences-from-the-handoff", "heading": "Differences from the handoff", "content": "- The handoff assumed a 1180px minimum width and a fixed 240px sidebar. The shell now works from 320px, and the sidebar width stays a token.\n- The skip link, the single `main` and the independent scrolling were left to each screen; the shell provides them." } ] }, "related": { "alternatives": [ { "name": "Container", "reason": "A marketing page or a single-column document: use `Container` and let the page scroll." } ], "uses": ["IconButton", "SkipLink"], "usedBy": [] } }, { "name": "Avatar", "kind": "component", "entryPoint": "loui-ds", "importStatement": "import { Avatar } from 'loui-ds';", "folder": "src/components/Avatar", "sourceFile": "src/components/Avatar/Avatar.tsx", "status": "experimental", "statusSource": "doc", "description": "A circular photo or initials of a person, in grays (never a color per person). The `name`\ndrives the initials and the accessible name; a photo that fails to load falls back to the\ninitials.", "props": [ { "name": "name", "type": "string", "required": false, "description": "The person's full name. Drives the initials and the accessible name (`alt` of the photo).\nOptional: still used to compute the initials." }, { "name": "decorative", "type": "boolean", "required": false, "default": "false", "description": "Hides the avatar from assistive technology (`alt=\"\"`). Use it when the name is shown next to it." }, { "name": "src", "type": "string", "required": false, "description": "URL of the photo. If it fails to load, the initials are shown instead." }, { "name": "size", "type": "'sm' | 'md' | 'lg'", "required": false, "default": "'md'", "description": "`sm` 24px, `md` 28px (default), `lg` 40px.", "values": ["sm", "md", "lg"] }, { "name": "ring", "type": "boolean", "required": false, "default": "false", "description": "Draws a 2px ring in the surface color, to separate overlapping avatars. Default `false`." } ], "inheritedProps": [ { "source": "@types/react", "interface": "AriaAttributes", "domGeneric": true, "count": 53 }, { "source": "@types/react", "interface": "Attributes", "domGeneric": true, "count": 1 }, { "source": "@types/react", "interface": "DOMAttributes", "domGeneric": true, "count": 169 }, { "source": "@types/react", "interface": "HTMLAttributes", "domGeneric": true, "count": 55 }, { "source": "@types/react", "interface": "RefAttributes", "domGeneric": true, "count": 1 } ], "variants": { "size": ["sm", "md", "lg"] }, "cssVariables": [ "--ds-avatar-initials-ratio", "--ds-avatar-ring-width", "--ds-avatar-size-lg", "--ds-avatar-size-md", "--ds-avatar-size-sm", "--ds-font-sans", "--ds-line", "--ds-line-strong", "--ds-radius-pill", "--ds-surface", "--ds-surface-hover", "--ds-text", "--ds-weight-semibold" ], "stories": { "title": "Components/Avatar", "tags": ["autodocs"], "items": [ { "name": "Default", "id": "components-avatar--default", "hasPlay": false }, { "name": "Sizes", "id": "components-avatar--sizes", "hasPlay": false }, { "name": "WithPhoto", "id": "components-avatar--with-photo", "hasPlay": false }, { "name": "BrokenPhoto", "id": "components-avatar--broken-photo", "hasPlay": false }, { "name": "Decorative", "id": "components-avatar--decorative", "hasPlay": false }, { "name": "Shades", "id": "components-avatar--shades", "hasPlay": false }, { "name": "Stacked", "id": "components-avatar--stacked", "hasPlay": false }, { "name": "LongName", "id": "components-avatar--long-name", "hasPlay": false }, { "name": "RightToLeft", "id": "components-avatar--right-to-left", "hasPlay": false } ] }, "docs": { "path": "src/components/Avatar/Avatar.md", "summary": "A circular photo or the initials of a person, in grays. There is no color per person.", "whenToUse": [ "Identify who owns, created or is assigned to something.", "Next to a name in a list, a comment or a menu." ], "whenNotToUse": [ "For a company logo or a product thumbnail: use an image.", "For a status: use `Badge`." ], "keyboard": [], "examples": [ "\n\n Ada Lovelace" ], "sections": [ { "id": "when-to-use", "heading": "When to use", "content": "- Identify who owns, created or is assigned to something.\n- Next to a name in a list, a comment or a menu." }, { "id": "when-not-to-use", "heading": "When not to use", "content": "- For a company logo or a product thumbnail: use an image.\n- For a status: use `Badge`." }, { "id": "anatomy", "heading": "Anatomy", "content": "```\nspan.root (circle, role=\"img\" + aria-label when it initials)\n img | span[aria-hidden] initials\n```" }, { "id": "props", "heading": "Props", "content": "| Prop | Type | Default | Notes |\n| ------------ | ---------------------- | ------- | -------------------------------------------------------------------------------------- |\n| `name` | `string` | - | Required unless `decorative`. Drives the initials and the accessible name |\n| `src` | `string` | | Photo URL. A load error falls back to the initials |\n| `size` | `'sm' \\| 'md' \\| 'lg'` | `'md'` | 24, 28 and 40 px (`--ds-avatar-size-*`) |\n| `ring` | `boolean` | `false` | 2px surface-colored ring, to separate overlapping avatars |\n| `decorative` | `boolean` | `false` | Hides the avatar from assistive technology (`alt=\"\"`). Use it next to the visible name |\n\nThe type makes `name` required when the avatar is not decorative. Other `span` attributes and `ref` go to the root." }, { "id": "initials", "heading": "Initials", "content": "`getInitials(name, locale)` (also exported) takes the first letter of the first and of the last word: \"Ana Maria da Silva\" is `AS`; a single word gives one letter. It uses `Intl.Segmenter` (combined characters stay whole) and `toLocaleUpperCase` with the `DSProvider` locale (`i` becomes `İ` in Turkish). The gray shade is derived from the name, so one person always looks the same." }, { "id": "accessibility", "heading": "Accessibility", "content": "- With initials the root is `role=\"img\"` named by `name`; the letters are `aria-hidden` so they are not read twice.\n- With a photo the `` has `alt={name}`. A decorative avatar has `alt=\"\"` and no role.\n- The handoff set `alt` to the initials (\"AL\"), which is meaningless to a screen reader; the full name is used now.\n- If the image cannot be loaded the initials appear and the accessible name stays the same.\n- Avatars are not interactive. Put one inside a button or link that has its own name and mark it `decorative`." }, { "id": "content-rules", "heading": "Content rules", "content": "- Pass the full display name, not the initials.\n- Never pass an email or an id as `name`." }, { "id": "examples", "heading": "Examples", "content": "```tsx\n\n\n Ada Lovelace\n```\n\nStacked avatars: wrap them in a flex container with `role=\"group\"` and an `aria-label`, give each `ring`, and overlap with a negative inline margin. A dedicated `AvatarGroup` is not part of this version." }, { "id": "differences-from-the-handoff", "heading": "Differences from the handoff", "content": "- `name` replaces `initials`; initials are computed and locale-aware.\n- `alt` is the person's name, or empty when `decorative`.\n- Image error fallback.\n- `size` is `sm | md | lg` (tokens) instead of a number; `tone` and `ring` color props are gone (shade is derived from the name, ring is a boolean).\n- No `style` prop." } ] }, "related": { "alternatives": [ { "name": "Badge", "reason": "For a status: use `Badge`." } ], "uses": [], "usedBy": ["Sidebar"] } }, { "name": "Badge", "kind": "component", "entryPoint": "loui-ds", "importStatement": "import { Badge } from 'loui-ds';", "folder": "src/components/Badge", "sourceFile": "src/components/Badge/Badge.tsx", "status": "experimental", "statusSource": "doc", "description": "A pill with a short status label. The text always states the status; the tone and the\ndot only reinforce it.", "props": [ { "name": "children", "type": "ReactNode", "required": true, "description": "The status text. Required: color and the dot never carry the meaning alone." }, { "name": "tone", "type": "'neutral' | 'accent' | 'success' | 'warning' | 'danger'", "required": false, "default": "'neutral'", "description": "Meaning of the badge: `accent` open or in progress, `success` done, `warning` pending,\n`danger` failed, `neutral` everything else (default).", "values": ["neutral", "accent", "success", "warning", "danger"] }, { "name": "dot", "type": "boolean", "required": false, "default": "true", "description": "Shows the small decorative dot before the text. It is hidden from assistive technology. Default `true`." } ], "inheritedProps": [ { "source": "@types/react", "interface": "AriaAttributes", "domGeneric": true, "count": 53 }, { "source": "@types/react", "interface": "Attributes", "domGeneric": true, "count": 1 }, { "source": "@types/react", "interface": "DOMAttributes", "domGeneric": true, "count": 169 }, { "source": "@types/react", "interface": "HTMLAttributes", "domGeneric": true, "count": 55 }, { "source": "@types/react", "interface": "RefAttributes", "domGeneric": true, "count": 1 } ], "variants": { "tone": ["neutral", "accent", "success", "warning", "danger"] }, "cssVariables": [ "--ds-accent", "--ds-accent-soft", "--ds-badge-dot-size", "--ds-badge-height", "--ds-badge-padding-inline", "--ds-danger", "--ds-danger-soft", "--ds-font-sans", "--ds-fs-label", "--ds-lh-label", "--ds-radius-pill", "--ds-space-2", "--ds-success", "--ds-success-soft", "--ds-surface-hover", "--ds-text-2", "--ds-text-3", "--ds-warning", "--ds-warning-soft", "--ds-weight-medium" ], "stories": { "title": "Components/Badge", "tags": ["autodocs"], "items": [ { "name": "Default", "id": "components-badge--default", "hasPlay": false }, { "name": "Accent", "id": "components-badge--accent", "hasPlay": false }, { "name": "Success", "id": "components-badge--success", "hasPlay": false }, { "name": "Warning", "id": "components-badge--warning", "hasPlay": false }, { "name": "Danger", "id": "components-badge--danger", "hasPlay": false }, { "name": "WithoutDot", "id": "components-badge--without-dot", "hasPlay": false }, { "name": "AllTones", "id": "components-badge--all-tones", "hasPlay": false }, { "name": "LongText", "id": "components-badge--long-text", "hasPlay": false }, { "name": "RightToLeft", "id": "components-badge--right-to-left", "hasPlay": false } ] }, "docs": { "path": "src/components/Badge/Badge.md", "summary": "A pill with a short status label. The text always states the status; the tone and the dot only reinforce it.", "whenToUse": [ "Show the state of a record in a list, a table row or a card header: Draft, In progress, Shipped, Failed.", "Keep the text short (one to three words, sentence case)." ], "whenNotToUse": [ "For a count or a filter value: use `Tag`.", "For a message the user must read or act on: use `Alert`.", "For an action: use `Button`. A Badge is never interactive." ], "keyboard": [], "examples": [ "Shipped\nFailed\nDraft" ], "sections": [ { "id": "when-to-use", "heading": "When to use", "content": "- Show the state of a record in a list, a table row or a card header: Draft, In progress, Shipped, Failed.\n- Keep the text short (one to three words, sentence case)." }, { "id": "when-not-to-use", "heading": "When not to use", "content": "- For a count or a filter value: use `Tag`.\n- For a message the user must read or act on: use `Alert`.\n- For an action: use `Button`. A Badge is never interactive." }, { "id": "anatomy", "heading": "Anatomy", "content": "```\n[ dot ] Text\n```\n\n- `dot` (optional, decorative, `aria-hidden`).\n- `text`: required, the status." }, { "id": "props", "heading": "Props", "content": "| Prop | Type | Default | Notes |\n| ----------- | ------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------- |\n| `tone` | `'neutral' \\| 'accent' \\| 'success' \\| 'warning' \\| 'danger'` | `'neutral'` | `accent` open or in progress, `success` done, `warning` pending, `danger` failed |\n| `dot` | `boolean` | `true` | Decorative dot before the text |\n| `children` | `ReactNode` | required | The status text |\n| `className` | `string` | | Merged with the component class |\n\nOther `span` attributes and `ref` are passed to the root element." }, { "id": "accessibility", "heading": "Accessibility", "content": "- A Badge is plain text in a `span`: there is no role and no keyboard behavior.\n- The dot is `aria-hidden`; the tone is never the only carrier of meaning, because the text names the status (WCAG 1.4.1).\n- Text on every soft tint keeps at least 4.5:1 contrast (checked in the browser test by compositing the real computed colors).\n- In forced-colors mode the Badge gets a border and the dot takes the text color." }, { "id": "content-rules", "heading": "Content rules", "content": "- Sentence case, no punctuation, no emoji: \"In progress\", not \"IN PROGRESS!\".\n- Name the state, not the action: \"Shipped\", not \"Ship\".\n- If the status can be unknown, say so with text (\"Unknown\"), do not omit the Badge." }, { "id": "examples", "heading": "Examples", "content": "```tsx\nShipped\nFailed\nDraft\n```" }, { "id": "differences-from-the-handoff", "heading": "Differences from the handoff", "content": "- Tones use only the semantic tokens (`--ds-*-soft`). The handoff built the danger tint with a different `color-mix` (14%) than the token (10%); the token is now the single source.\n- Height, dot size and padding are component tokens (`--ds-badge-*`).\n- The dot is explicitly decorative; `children` is required.\n- No `style` prop." } ] }, "related": { "alternatives": [ { "name": "Tag", "reason": "For a count or a filter value: use `Tag`." }, { "name": "Alert", "reason": "For a message the user must read or act on: use `Alert`." }, { "name": "Button", "reason": "For an action: use `Button`. A Badge is never interactive." } ], "uses": [], "usedBy": ["AgentCard", "ApprovalCard"] } }, { "name": "Banner", "kind": "component", "entryPoint": "loui-ds", "importStatement": "import { Banner } from 'loui-ds';", "folder": "src/components/Banner", "sourceFile": "src/components/Banner/Banner.tsx", "status": "experimental", "statusSource": "doc", "description": "A persistent, full-width message for a whole page or section: maintenance, a limited account,\nan offline mode. It stays until the condition ends or the user dismisses it.\nThe icon is decorative and a visually hidden prefix names the tone for screen readers.", "props": [ { "name": "tone", "type": "'info' | 'success' | 'warning' | 'danger'", "required": false, "default": "'info'", "description": "Kind of message: `info` (neutral, default), `success`, `warning` or `danger`.", "values": ["info", "success", "warning", "danger"] }, { "name": "title", "type": "ReactNode", "required": false, "description": "Short heading in one line: what is going on. Plain text, not a document heading." }, { "name": "children", "type": "ReactNode", "required": false, "description": "The detail: why, and what to do. Keep it to one or two sentences." }, { "name": "action", "type": "ReactNode", "required": false, "description": "A single action next to the text, usually a link or a small `Button` (\"Update card\")." }, { "name": "onDismiss", "type": "() => void", "required": false, "description": "Shows a dismiss button that calls this. The banner is removed by the parent." }, { "name": "urgent", "type": "boolean", "required": false, "default": "false", "description": "The banner appears while the user is working and interrupts the task, so it must be announced\nimmediately (`role=\"alert\"`, assertive). Only for a failure the user must know about right\nnow. A banner that is on the page from the start never needs it." }, { "name": "announce", "type": "boolean", "required": false, "default": "false", "description": "Whether the banner is a live region (`role=\"status\"`, polite). Default `false`, because a\nbanner is usually part of the page when it loads and a live region that never changes is\nnoise. Set `true` when the banner is added to the page after load (a lost connection that\nis restored, a session that is about to expire). Ignored when `urgent`." }, { "name": "messages", "type": "Partial<{ dismiss: string; info: string; success: string; warning: string; danger: string; }>", "required": false, "description": "Per-instance overrides of the built-in messages." } ], "inheritedProps": [ { "source": "@types/react", "interface": "AriaAttributes", "domGeneric": true, "count": 53 }, { "source": "@types/react", "interface": "Attributes", "domGeneric": true, "count": 1 }, { "source": "@types/react", "interface": "DOMAttributes", "domGeneric": true, "count": 169 }, { "source": "@types/react", "interface": "HTMLAttributes", "domGeneric": true, "count": 53 }, { "source": "@types/react", "interface": "RefAttributes", "domGeneric": true, "count": 1 } ], "variants": { "tone": ["info", "success", "warning", "danger"] }, "messages": { "providerKey": "Banner", "locales": ["en", "pt-BR"], "keys": [ { "key": "dismiss", "kind": "string", "default": "Dismiss banner", "description": "Name of the dismiss button." }, { "key": "info", "kind": "string", "default": "Information", "description": "Visually hidden prefix that tells screen reader users the kind of banner; color and icon alone cannot." }, { "key": "success", "kind": "string", "default": "Success" }, { "key": "warning", "kind": "string", "default": "Warning" }, { "key": "danger", "kind": "string", "default": "Error" } ] }, "cssVariables": [ "--ds-accent", "--ds-banner-content-basis", "--ds-banner-danger-bg", "--ds-banner-danger-border", "--ds-banner-success-bg", "--ds-banner-success-border", "--ds-banner-warning-bg", "--ds-banner-warning-border", "--ds-bg", "--ds-danger", "--ds-fs-small", "--ds-lh-small", "--ds-line", "--ds-space-2", "--ds-space-3", "--ds-space-4", "--ds-success", "--ds-text", "--ds-text-2", "--ds-warning", "--ds-weight-medium" ], "stories": { "title": "Components/Banner", "tags": ["autodocs"], "items": [ { "name": "Default", "id": "components-banner--default", "hasPlay": false }, { "name": "Success", "id": "components-banner--success", "hasPlay": false }, { "name": "Warning", "id": "components-banner--warning", "hasPlay": false }, { "name": "Danger", "id": "components-banner--danger", "hasPlay": false }, { "name": "Urgent", "id": "components-banner--urgent", "description": "Urgent banners use `role=\"alert\"` and interrupt screen readers. Use them only when they appear while the user is working.", "hasPlay": false }, { "name": "Announced", "id": "components-banner--announced", "description": "A banner added after the page loaded is a polite live region.", "hasPlay": false }, { "name": "TitleOnly", "id": "components-banner--title-only", "hasPlay": false }, { "name": "TextOnly", "id": "components-banner--text-only", "hasPlay": false }, { "name": "Dismissible", "id": "components-banner--dismissible", "description": "Tab to the dismiss button, press Enter.", "hasPlay": true }, { "name": "LongText", "id": "components-banner--long-text", "hasPlay": false }, { "name": "AllTones", "id": "components-banner--all-tones", "hasPlay": false }, { "name": "RightToLeft", "id": "components-banner--right-to-left", "hasPlay": false } ] }, "docs": { "path": "src/components/Banner/Banner.md", "summary": "A persistent, full-width message for a whole page or section: maintenance, a limited account, an offline mode. It has a tone, an icon, an optional title, one action and an optional dismiss button.", "whenToUse": [ "A condition that affects the whole page or area and lasts until it is resolved or dismissed: scheduled maintenance, a trial ending, a read-only mode.", "Place it at the top of the page or section it applies to, above the content." ], "whenNotToUse": [ "Feedback about something that just happened and goes away by itself (\"Order #1051 created\"): use `Toast`.", "A message about one piece of content, inside it (a form, a card): use `Alert`.", "A field error: use the field's error message.", "A confirmation that needs a decision: use `Dialog`.", "The status of a record: use `Badge`." ], "keyboard": [], "examples": [ "Sunday, 02:00 to 03:00 UTC.\n\nChoose plan}\n onDismiss={() => setHidden(true)}\n>\n Choose a plan to keep your data.\n\n\n\n Changes are not being saved.\n" ], "sections": [ { "id": "when-to-use", "heading": "When to use", "content": "- A condition that affects the whole page or area and lasts until it is resolved or dismissed: scheduled maintenance, a trial ending, a read-only mode.\n- Place it at the top of the page or section it applies to, above the content." }, { "id": "when-not-to-use", "heading": "When not to use", "content": "- Feedback about something that just happened and goes away by itself (\"Order #1051 created\"): use `Toast`.\n- A message about one piece of content, inside it (a form, a card): use `Alert`.\n- A field error: use the field's error message.\n- A confirmation that needs a decision: use `Dialog`.\n- The status of a record: use `Badge`.\n\n### Banner, Alert and Toast\n\n| | Banner | Alert | Toast |\n| ----------- | -------------------------------------------------- | --------------------------------------- | ------------------------------------ |\n| Scope | Page or section | Inline, next to the content it explains | The app, in a corner |\n| Lifetime | Persistent, until resolved or dismissed | Persistent while relevant | Transient, auto-dismisses (pausable) |\n| Shape | Full width, flat, top and bottom border only | Rounded card | Elevated overlay |\n| Live region | None by default (it is on the page from the start) | Polite status by default | Always announced |" }, { "id": "anatomy", "heading": "Anatomy", "content": "```\ndiv[role=alert | status | none] (tinted surface, 1px tinted top and bottom border, full width)\n Icon (decorative) info | success | warning (triangle) | danger\n content\n VisuallyHidden \"Information\" | \"Success\" | \"Warning\" | \"Error\"\n title optional, 14/22, weight 500\n children text-2, on the same line as the title when it fits\n actions action slot · dismiss IconButton\n```" }, { "id": "props", "heading": "Props", "content": "| Prop | Type | Default | Notes |\n| ----------- | ---------------------------------------------- | -------- | --------------------------------------------------------------------- |\n| `tone` | `'info' \\| 'success' \\| 'warning' \\| 'danger'` | `'info'` | `info` is neutral; the others tint border and background |\n| `title` | `ReactNode` | | What is going on, one line |\n| `children` | `ReactNode` | | Why, and what to do |\n| `action` | `ReactNode` | | One link or small `Button` |\n| `onDismiss` | `() => void` | | Shows the dismiss button; the parent removes the banner |\n| `urgent` | `boolean` | `false` | `role=\"alert\"` (assertive). Only when it appears while the user works |\n| `announce` | `boolean` | `false` | `role=\"status\"` (polite), for a banner added after the page loaded |\n| `messages` | `{ dismiss, info, success, warning, danger }` | | Per-instance overrides |\n\nOther `div` attributes and `ref` go to the root." }, { "id": "accessibility-role-decisions", "heading": "Accessibility: role decisions", "content": "- **No role by default.** A banner is normally part of the page when it loads; screen readers read it in page order. A live region that never changes is noise.\n- **`announce` gives `role=\"status\"` (polite).** Use it when the banner is inserted after load (connection restored, session about to expire). Render the banner when the event happens and keep it mounted; do not render it hidden and unhide it.\n- **`urgent` gives `role=\"alert\"` (assertive).** Use it only for a `danger` or `warning` banner that appears dynamically and needs attention now (connection lost, session expired). A `danger` or `warning` banner that is on the page from the start must not be `urgent`: the tone does not imply urgency.\n- **The tone is not only color and icon.** The icon is `aria-hidden`; a visually hidden prefix (\"Error\", \"Warning\", \"Success\", \"Information\", from messages) names the kind of banner.\n- The **dismiss button** is an `IconButton` named \"Dismiss banner\" (messages), reachable by Tab and operated with Enter or Space. After dismissing, move focus somewhere sensible if the banner held it.\n- Text contrast on the tinted backgrounds is at least 4.5:1 (checked in the browser test with the real computed colors). The tints are component tokens (`--ds-banner-*`).\n- Reflow: the text and the actions wrap; at 320 px the action moves below the text." }, { "id": "content-rules", "heading": "Content rules", "content": "- Title: what is going on, sentence case, no exclamation marks (\"Trial ends in 3 days\").\n- Text: why and what to do, one or two sentences.\n- The action is a verb plus object (\"Choose plan\"), not \"Click here\".\n- Do not stack more than one banner per page area." }, { "id": "examples", "heading": "Examples", "content": "```tsx\nSunday, 02:00 to 03:00 UTC.\n\nChoose plan}\n onDismiss={() => setHidden(true)}\n>\n Choose a plan to keep your data.\n\n\n\n Changes are not being saved.\n\n```" } ] }, "related": { "alternatives": [ { "name": "Alert", "reason": "A message about one piece of content, inside it (a form, a card): use `Alert`." }, { "name": "Dialog", "reason": "A confirmation that needs a decision: use `Dialog`." }, { "name": "Badge", "reason": "The status of a record: use `Badge`." } ], "uses": ["Icon", "IconButton", "VisuallyHidden"], "usedBy": [] } }, { "name": "Breadcrumb", "kind": "component", "entryPoint": "loui-ds", "importStatement": "import { Breadcrumb } from 'loui-ds';", "folder": "src/components/Breadcrumb", "sourceFile": "src/components/Breadcrumb/Breadcrumb.tsx", "status": "experimental", "statusSource": "doc", "description": "The path to the current page as an ordered list of links inside a `nav` landmark. The\nseparators are decorative (`aria-hidden`), so a screen reader hears a list of N items. Long\nlabels are truncated with an ellipsis (the current page keeps the most room); collapsing the\nmiddle of a long trail into a menu is not supported yet.", "props": [ { "name": "items", "type": "readonly BreadcrumbItem[]", "required": true, "description": "The trail from the root to the current page. The last item is the current page: it gets\n`aria-current=\"page\"` and is not a link." }, { "name": "messages", "type": "Partial<{ label: string; }>", "required": false, "description": "Per-instance overrides of the built-in messages." } ], "inheritedProps": [ { "source": "@types/react", "interface": "AriaAttributes", "domGeneric": true, "count": 53 }, { "source": "@types/react", "interface": "Attributes", "domGeneric": true, "count": 1 }, { "source": "@types/react", "interface": "DOMAttributes", "domGeneric": true, "count": 169 }, { "source": "@types/react", "interface": "HTMLAttributes", "domGeneric": true, "count": 55 }, { "source": "@types/react", "interface": "RefAttributes", "domGeneric": true, "count": 1 } ], "variants": {}, "messages": { "providerKey": "Breadcrumb", "locales": ["en", "pt-BR"], "keys": [ { "key": "label", "kind": "string", "default": "Breadcrumb", "description": "Accessible name of the breadcrumb navigation landmark." } ] }, "cssVariables": [ "--ds-duration", "--ds-ease", "--ds-focus-ring", "--ds-font-sans", "--ds-fs-small", "--ds-lh-small", "--ds-radius-sm", "--ds-space-2", "--ds-text", "--ds-text-2", "--ds-text-3", "--ds-weight-medium" ], "stories": { "title": "Components/Breadcrumb", "tags": ["autodocs"], "items": [ { "name": "Default", "id": "components-breadcrumb--default", "hasPlay": true }, { "name": "SingleItem", "id": "components-breadcrumb--single-item", "hasPlay": true }, { "name": "KeyboardNavigation", "id": "components-breadcrumb--keyboard-navigation", "description": "Tab visits each ancestor link in order; the current page is plain text.", "hasPlay": true }, { "name": "LongTrail", "id": "components-breadcrumb--long-trail", "hasPlay": false }, { "name": "RouterNavigation", "id": "components-breadcrumb--router-navigation", "hasPlay": true }, { "name": "Portuguese", "id": "components-breadcrumb--portuguese", "hasPlay": true }, { "name": "RightToLeft", "id": "components-breadcrumb--right-to-left", "hasPlay": false }, { "name": "Focused", "id": "components-breadcrumb--focused", "hasPlay": true } ] }, "docs": { "path": "src/components/Breadcrumb/Breadcrumb.md", "summary": "The path from the root to the current page, as an ordered list of links inside a `nav` landmark. Built on React Aria `Breadcrumbs` and `Breadcrumb`.\n\n- Handoff source: `components/layout/Breadcrumb.jsx` (TODO `CMP-LAY-03`).", "whenToUse": [ "Deep hierarchies (Orders > Northwind Traders > ORD-1048) where people need to go up a level.", "Inside the `TopBar` instead of a title." ], "whenNotToUse": [ "For the steps of a process: use a stepper (`StatusSteps`).", "For the main navigation: use `Sidebar` and `NavItem`.", "For a flat app with two levels: a page title and a \"Back\" link are enough." ], "keyboard": [], "examples": [ "" ], "sections": [ { "id": "when-to-use", "heading": "When to use", "content": "- Deep hierarchies (Orders > Northwind Traders > ORD-1048) where people need to go up a level.\n- Inside the `TopBar` instead of a title." }, { "id": "when-not-to-use", "heading": "When not to use", "content": "- For the steps of a process: use a stepper (`StatusSteps`).\n- For the main navigation: use `Sidebar` and `NavItem`.\n- For a flat app with two levels: a page title and a \"Back\" link are enough." }, { "id": "props", "heading": "Props", "content": "| Prop | Type | Notes |\n| ------------ | ------------------------------------ | -------------------------------------------------------------------------- |\n| `items` | `{ label: string; href?: string }[]` | Root first. The last item is the current page: plain text, `href` ignored. |\n| `aria-label` | `string` | Overrides the landmark name (\"Breadcrumb\" from the catalog). |\n| `messages` | `{ label?: string }` | Per-instance message override (ADR-0005). |\n\n`ref` points to the `