@moldable-ai/ui 0.2.19 → 0.2.20

package/src/components/ui/button.md

@@ -0,0 +1,76 @@
+# Button
+
+## Purpose
+
+`Button` starts an immediate action or, with `asChild`, gives button styling and behavior to another interactive element. Use it for commands such as save, run, refresh, connect, archive, and open.
+
+Use a link for navigation. Use `Toggle` when the control represents an on/off view state, and `ToggleGroup` when the user chooses among a small set of modes.
+
+## Usage patterns
+
+```tsx
+import { Button } from '@moldable-ai/ui'
+import { RefreshCw } from 'lucide-react'
+
+<Button type="button" size="sm" className="cursor-pointer">
+  Save changes
+</Button>
+
+<Button
+  type="button"
+  variant="ghost"
+  size="icon-sm"
+  className="cursor-pointer"
+  aria-label="Refresh results"
+>
+  <RefreshCw />
+</Button>
+```
+
+Keep toolbar actions compact (`xs`, `sm`, `icon-xs`, or `icon-sm`). Reserve `default` or `lg` for the primary action in a form, setup state, or focused control dock. While an async action is running, disable the button, preserve its width, and show a small spinner beside a short status label.
+
+For links that should look like buttons:
+
+```tsx
+<Button asChild variant="outline" size="sm">
+  <a href="/settings">Open settings</a>
+</Button>
+```
+
+## API summary
+
+- `variant`: `default`, `destructive`, `outline`, `secondary`, `ghost`, or `link`. Defaults to `default`.
+- `size`: `default`, `xs`, `sm`, `lg`, `icon`, `icon-xs`, `icon-sm`, or `icon-lg`. Defaults to `default`.
+- `asChild`: renders a Radix `Slot` so the child owns the element and semantics.
+- Accepts native button props, including `type`, `disabled`, `aria-*`, and event handlers.
+- `buttonVariants` is exported for cases that need the same visual treatment on another component.
+
+## Do
+
+- Set `type="button"` unless the control intentionally submits a form.
+- Add `cursor-pointer`; use the real `disabled` attribute for unavailable or busy actions.
+- Give icon-only buttons an `aria-label` and a tooltip.
+- Use a specific Lucide icon that names the action.
+- Put one visually primary action in a local action group.
+- Keep labels literal and verb-led: “Save query”, “Connect account”, “Move to trash”.
+
+## Don't
+
+- Do not use a button for ordinary navigation without link semantics.
+- Do not rely on color alone to explain a destructive or selected action.
+- Do not use raw color classes, decorative gradients, or oversized call-to-action styling.
+- Do not use `Sparkles` as a generic AI marker.
+- Do not leave a busy button clickable or allow repeated submission.
+- Do not hide essential actions behind hover-only icon buttons.
+
+## Moldable considerations
+
+Buttons in a fixed bottom dock must remain above the desktop chat:
+
+```tsx
+<div style={{ bottom: 'calc(var(--chat-safe-padding, 0px) + 1.5rem)' }}>
+  <Button className="cursor-pointer">Apply changes</Button>
+</div>
+```
+
+Keep fixed groups within `max-w-[calc(100vw-2rem)]`. Toolbar buttons should normally fit an `h-8` or `h-9` bar. Important actions should also be exposed through app commands when useful. Do not add an app-local prompt or chat button when the action belongs to Moldable’s desktop chat.

package/src/components/ui/color-well.md

@@ -0,0 +1,11 @@
+# ColorWell
+
+Compact color selection or read-only swatch.
+
+```tsx
+<ColorWell aria-label="Project color" value={color} onValueChange={setColor} />
+```
+
+Use the browser color input as the renderer fallback. `readOnly` presents the
+value without implying interactivity. Never make color the only representation
+of a status or category.

package/src/components/ui/combobox.md

@@ -0,0 +1,43 @@
+# Combobox
+
+Searchable single- or multi-value selection for longer option sets.
+
+## When to use
+
+Use `Combobox` when users need to filter options, create values, or manage
+multiple selections. Use `Select` for a short fixed list, `Command` for actions,
+and `Input` for unconstrained text.
+
+## Anatomy
+
+Compose the root with `ComboboxInput`, `ComboboxContent`, `ComboboxList`, and
+`ComboboxItem`. Optional parts include groups, labels, separators, an empty
+state, clear/trigger controls, and the chips family for multi-value input.
+
+```tsx
+<Combobox items={projects}>
+  <ComboboxInput placeholder="Choose a project" />
+  <ComboboxContent>
+    <ComboboxEmpty>No matching projects.</ComboboxEmpty>
+    <ComboboxList>
+      {(project) => (
+        <ComboboxItem key={project.id} value={project}>
+          {project.name}
+        </ComboboxItem>
+      )}
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>
+```
+
+## Design and behavior
+
+- Keep option labels concise and place distinguishing metadata after the name.
+- Show a real loading state for remote results; “no matches” is not a loading
+  state.
+- Preserve Base UI keyboard navigation, focus, active-descendant, and
+  selection behavior.
+- Label the input visibly or with an accessible name.
+- Do not deep-import the implementation; `Combobox` is exported from the
+  package root.
+

package/src/components/ui/date-field.md

@@ -0,0 +1,32 @@
+# Date Field
+
+## Purpose
+
+`DateField` provides a styled native HTML date input. It keeps platform parsing, keyboard entry, validation, locale-aware presentation, and the browser’s native picker rather than implementing a look-alike calendar.
+
+## Usage
+
+```tsx
+import { DateField } from '@moldable-ai/ui'
+
+<DateField
+  aria-label="Due date"
+  value={dueDate}
+  min="2026-01-01"
+  onValueChange={setDueDate}
+  clearable
+/>
+```
+
+Values use the native timezone-free `YYYY-MM-DD` form. Use `value`/`onValueChange` for a controlled field or `defaultValue` for an uncontrolled field. Native attributes such as `min`, `max`, `step`, `required`, `disabled`, and `aria-invalid` pass through. `variant` is `default` or `filled`; `density` is `compact`, `default`, or `comfortable`.
+
+## Quality bar
+
+- Associate the input with a visible label or an accessible `aria-label`.
+- Store the returned value as a calendar date; do not pass it through a UTC timestamp just to format it.
+- Use native constraints and show validation text close to the field.
+- Allow clearing only when an empty date is valid.
+- Use a calendar popover only for workflows that require richer range, availability, or event selection.
+- Do not replace the native picker to imitate a desktop control.
+
+A host may later provide a native date capability. Keep that behind an explicit cross-client contract and preserve this web implementation as the portable fallback.

package/src/components/ui/edge-fade.md

@@ -0,0 +1,7 @@
+# EdgeFade
+
+A non-interactive gradient cue that content continues beneath an edge.
+
+Place it inside a relatively positioned scroll container and select the
+matching `edge`. It never replaces a visible scrollbar or keyboard scrolling.
+Keep the fade subtle and omit it when content boundaries are already obvious.

package/src/components/ui/empty.md

@@ -0,0 +1,82 @@
+# Empty
+
+## Purpose
+
+`Empty` describes a normal absence of content or a blocked first-run state. It gives the user a quiet explanation and, when needed, one clear next action.
+
+Use `Alert` when an operation failed. Use `Skeleton` or `Spinner` while data is still loading. Do not render an empty state before the initial query has resolved.
+
+## Usage patterns
+
+```tsx
+import { Database } from 'lucide-react'
+import {
+  Button,
+  Empty,
+  EmptyContent,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from '@moldable-ai/ui'
+
+;<Empty className="pb-[calc(var(--chat-safe-padding,0px)+2rem)]">
+  <EmptyHeader>
+    <EmptyMedia variant="icon">
+      <Database />
+    </EmptyMedia>
+    <EmptyTitle>Choose a connection</EmptyTitle>
+    <EmptyDescription>
+      Select a saved connection to browse its tables.
+    </EmptyDescription>
+  </EmptyHeader>
+  <EmptyContent>
+    <Button type="button" size="sm" className="cursor-pointer">
+      Add connection
+    </Button>
+  </EmptyContent>
+</Empty>
+```
+
+For a successful zero state, omit the action when there is nothing useful to do:
+
+```tsx
+<Empty>
+  <EmptyHeader>
+    <EmptyTitle>Inbox clear</EmptyTitle>
+    <EmptyDescription>No messages need your attention.</EmptyDescription>
+  </EmptyHeader>
+</Empty>
+```
+
+## API summary
+
+- `Empty`: centered flex container for the complete state.
+- `EmptyHeader`: groups media, title, and description.
+- `EmptyMedia`: `variant="default"` or `variant="icon"`.
+- `EmptyTitle`: primary label.
+- `EmptyDescription`: supporting text with styled inline links.
+- `EmptyContent`: optional actions or secondary controls.
+- All parts accept native props for their rendered element and a `className`.
+
+## Do
+
+- Use a one-to-four-word title and at most one sentence of description.
+- Show one primary setup action when the state is blocked.
+- Distinguish first-run, filtered-zero, permission, and successful-zero states.
+- Keep the app’s normal shell or pane structure visible.
+- Add chat-safe padding when the empty state occupies a pane that reaches the bottom.
+
+## Don't
+
+- Do not use welcome-page copy, feature grids, or marketing language.
+- Do not explain obvious controls.
+- Do not add an illustration only to fill space.
+- Do not show a creation action when silence or completion is the correct state.
+- Do not make the empty state a giant nested card.
+
+## Moldable considerations
+
+An empty state should feel like part of a local instrument, not a landing page. Keep it visually small even when centered. If the desktop chat can resolve the state, provide specific app context or an explicit “Ask Moldable about this” affordance that prefills desktop chat; do not add another chat box.
+
+For scrollable panes, use enough bottom padding to remain visible above chat, commonly `pb-[calc(var(--chat-safe-padding,0px)+1rem)]` or more when a fixed dock is present.

package/src/components/ui/field.md

@@ -0,0 +1,77 @@
+# Field
+
+## Purpose
+
+The field primitives compose accessible, consistent form rows. Use them to connect labels, controls, descriptions, validation messages, and related groups without wrapping every input in a card.
+
+## Usage patterns
+
+```tsx
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+  Input,
+} from '@moldable-ai/ui'
+
+;<FieldGroup>
+  <Field data-invalid={Boolean(error)}>
+    <FieldLabel htmlFor="connection-name">Connection name</FieldLabel>
+    <Input
+      id="connection-name"
+      aria-invalid={Boolean(error)}
+      aria-describedby={
+        error ? 'connection-name-error' : 'connection-name-help'
+      }
+    />
+    <FieldDescription id="connection-name-help">
+      Used only to identify this connection.
+    </FieldDescription>
+    <FieldError
+      id="connection-name-error"
+      errors={error ? [{ message: error }] : []}
+    />
+  </Field>
+</FieldGroup>
+```
+
+Use `orientation="horizontal"` for compact checkbox/radio rows and `orientation="responsive"` when the label and control should align horizontally only when the field-group container is wide enough.
+
+## API summary
+
+- `FieldSet`: semantic `fieldset` for related controls.
+- `FieldLegend`: `variant="legend"` or `"label"` for fieldset headings.
+- `FieldGroup`: container-query-aware vertical group.
+- `Field`: `role="group"` with `orientation="vertical"`, `"horizontal"`, or `"responsive"`.
+- `FieldLabel`: wraps `Label`; supports `htmlFor`.
+- `FieldTitle`: non-label heading for composite controls.
+- `FieldContent`: groups a control with its description and error.
+- `FieldDescription`: supporting text with styled inline links.
+- `FieldError`: accepts `children` or `errors?: Array<{ message?: string } | undefined>`; duplicate messages are removed and multiple messages render as a list.
+- `FieldSeparator`: divider with optional centered text.
+- Each part accepts its native element props and `className`.
+
+## Do
+
+- Give every control a visible label or an accessible name.
+- Connect labels and descriptions with `htmlFor`, `id`, and `aria-describedby`.
+- Set both `data-invalid` on `Field` and `aria-invalid` on the control.
+- Use real `disabled` state and reflect it on the field group when styling needs it.
+- Place validation directly after the affected control.
+- Group related checkbox or radio controls in `FieldSet` with `FieldLegend`.
+
+## Don't
+
+- Do not use placeholder text as the only label.
+- Do not show validation only by changing border color.
+- Do not wait until submission to reveal formatting requirements the user needs beforehand.
+- Do not use horizontal fields when labels or values will be cramped.
+- Do not store secrets in ordinary app state when they belong in aivault.
+
+## Moldable considerations
+
+Forms should be compact and bounded. Use dialogs for small setup or edit workflows, with their body scrolling internally above `--chat-safe-padding`. Put advanced options behind a secondary disclosure.
+
+Use plain `Input` or `Textarea` for short values only. Use `MarkdownEditor` for structured prose and Monaco for code, SQL, JSON, or configuration. Async validation and save states should stay local to the field or submit button and must prevent duplicate actions.

package/src/components/ui/grid.md

@@ -0,0 +1,105 @@
+# Grid
+
+## Purpose
+
+`Grid` is a keyboard-aware, selectable tile collection for artifacts, projects, media, templates, and other visual libraries. It provides two-dimensional arrow navigation, selection, activation, disabled-item behavior, and ARIA grid structure.
+
+Use `List` when rows are primarily textual or the container is narrow. Use CSS Grid directly for non-interactive page layout.
+
+## Basic usage
+
+```tsx
+import {
+  Grid,
+  GridItem,
+  GridItemContent,
+  GridItemDescription,
+  GridItemMedia,
+  GridItemTitle,
+} from '@moldable-ai/ui'
+
+<Grid
+  aria-label="Artifacts"
+  columns={3}
+  selectionMode="single"
+  onAction={(value) => openArtifact(value)}
+>
+  {artifacts.map((artifact) => (
+    <GridItem key={artifact.id} value={artifact.id}>
+      <GridItemMedia>
+        <img src={artifact.previewUrl} alt="" />
+      </GridItemMedia>
+      <GridItemContent>
+        <GridItemTitle>{artifact.title}</GridItemTitle>
+        <GridItemDescription>{artifact.summary}</GridItemDescription>
+      </GridItemContent>
+    </GridItem>
+  ))}
+</Grid>
+```
+
+`GridItem` elements must be direct children. `Grid` groups them into semantic rows according to `columns`.
+
+## Responsive columns
+
+Keep the `columns` value aligned with the rendered column count because it drives both layout and keyboard movement:
+
+```tsx
+const columns = useCompactWindow() ? 1 : 3
+
+<Grid columns={columns} aria-label="Projects">
+  {/* direct GridItem children */}
+</Grid>
+```
+
+Prefer changing this value at deliberate window breakpoints. A smaller window should normally reduce the number of columns before shrinking card content below its useful size.
+
+## Interaction contract
+
+- Arrow Left/Right moves one tile.
+- Arrow Up/Down moves by `columns`.
+- Home and End move to the first and last available tile.
+- Space changes selection.
+- Enter changes selection and invokes `onAction`.
+- A single pointer click changes selection. A double click invokes `onAction`.
+- Disabled tiles are skipped.
+- Buttons and links inside a tile preserve their own pointer behavior.
+
+## API summary
+
+### `Grid`
+
+- `columns`: positive integer used for layout, row semantics, and vertical navigation. Defaults to `1`.
+- `selectionMode`: `none`, `single`, or `multiple`. Defaults to `none`.
+- `selectedValues` / `defaultSelectedValues`: controlled or initial selected keys.
+- `onSelectionChange(values)`: receives a new read-only `Set`.
+- `onAction(value)`: invoked by Enter or a double click.
+- `loop`: wraps directional navigation. Defaults to `false`.
+- `disabled`: disables the entire collection.
+
+### `GridItem`
+
+- `value`: stable application key.
+- `disabled`: removes the tile from focus, selection, and activation.
+
+`GridItemMedia`, `GridItemContent`, `GridItemTitle`, and `GridItemDescription` provide a consistent preview-card anatomy.
+
+## Do
+
+- Provide a collection label.
+- Keep every preview at a consistent aspect ratio within one grid.
+- Preserve titles and essential state at narrow widths; remove decorative metadata first.
+- Use an empty state outside the grid when there are no items.
+- Lazy-load large preview images and provide useful image alternative text when the image conveys information not already in the title.
+
+## Don't
+
+- Do not use `Grid` as a general page-layout primitive.
+- Do not hide essential actions behind hover alone.
+- Do not make every tile independently tabbable.
+- Do not let visual CSS columns disagree with the `columns` prop.
+- Do not nest interactive tiles.
+
+## Window and canvas guidance
+
+Give visual grids room to breathe in a primary canvas, but keep their controls in a compact toolbar. Prefer one to three columns in narrow app windows and denser layouts only when previews remain legible. A standalone app window should own its loading, empty, selection, and error states; do not assume a surrounding desktop shell supplies them.

package/src/components/ui/icon-button.md

@@ -0,0 +1,36 @@
+# Icon Button
+
+## Purpose
+
+`IconButton` is the shared recipe for a compact action represented by one icon. It builds on `Button`, requires an accessible `label`, and standardizes icon sizing, busy state, shape, and density.
+
+## Usage
+
+```tsx
+import { IconButton } from '@moldable-ai/ui'
+import { RefreshCw } from 'lucide-react'
+
+<IconButton
+  label="Refresh events"
+  tooltip
+  size="sm"
+  variant="ghost"
+  loading={refreshing}
+  onClick={refresh}
+>
+  <RefreshCw />
+</IconButton>
+```
+
+`size` is `xs`, `sm`, `default`, or `lg`. `shape` is `rounded` or `circle`. `loading` disables the control, exposes `aria-busy`, and replaces the icon with a progress indicator. `tooltip` may be `true` to reuse the label as a native hint or a specific string.
+
+## Quality bar
+
+- Use an explicit verb-led label, even when the icon seems obvious.
+- Prefer `xs` or `sm` in compact toolbars and inspectors.
+- Use the same icon for the same action throughout an app.
+- Pair unfamiliar actions with the shared `Tooltip`; a native title is only a lightweight fallback.
+- Keep destructive actions visually and textually clear.
+- Do not place text inside `IconButton`, suppress its accessible name, or make an unavailable action appear enabled.
+
+The component represents an app action only. Window close, minimize, zoom, sharing, and host menus remain host-owned capabilities.

package/src/components/ui/inspector.md

@@ -0,0 +1,11 @@
+# Inspector
+
+Secondary property controls for the current selection.
+
+Compose `Inspector`, `InspectorHeader`, `InspectorContent`,
+`InspectorSection`, and aligned `InspectorRow` pairs. Controls should usually
+use compact sizes.
+
+The inspector must remain subordinate to the primary pane. Collapse it when
+width is constrained, group related properties, and avoid placing primary
+workflow actions inside it.

package/src/components/ui/item.md

@@ -0,0 +1,87 @@
+# Item
+
+## Purpose
+
+The item primitives compose dense, scannable object rows with optional media, metadata, actions, and secondary regions. Use them for messages, files, meetings, tasks, records, and settings rows.
+
+Use `Table` for strongly tabular data and `Card` only when each object genuinely needs independent framing.
+
+## Usage patterns
+
+```tsx
+import { FileText, MoreHorizontal } from 'lucide-react'
+import {
+  Button,
+  Item,
+  ItemActions,
+  ItemContent,
+  ItemDescription,
+  ItemGroup,
+  ItemMedia,
+  ItemSeparator,
+  ItemTitle,
+} from '@moldable-ai/ui'
+
+;<ItemGroup>
+  <Item size="sm">
+    <ItemMedia variant="icon">
+      <FileText />
+    </ItemMedia>
+    <ItemContent className="min-w-0">
+      <ItemTitle className="max-w-full truncate">Project notes.md</ItemTitle>
+      <ItemDescription className="truncate">
+        Edited 8 minutes ago
+      </ItemDescription>
+    </ItemContent>
+    <ItemActions>
+      <Button
+        type="button"
+        variant="ghost"
+        size="icon-xs"
+        className="cursor-pointer"
+        aria-label="More actions"
+      >
+        <MoreHorizontal />
+      </Button>
+    </ItemActions>
+  </Item>
+  <ItemSeparator />
+</ItemGroup>
+```
+
+Use `asChild` when the whole item is a link or another interactive primitive. Avoid putting nested interactive controls inside an item whose entire surface is already a link.
+
+## API summary
+
+- `ItemGroup`: `role="list"` container.
+- `Item`: `variant="default"`, `"outline"`, or `"muted"`; `size="default"` or `"sm"`; optional `asChild`.
+- `ItemMedia`: `variant="default"`, `"icon"`, or `"image"`.
+- `ItemContent`: flexible title/description column.
+- `ItemTitle`, `ItemDescription`: primary and secondary text.
+- `ItemActions`: trailing controls.
+- `ItemHeader`, `ItemFooter`: full-width secondary rows.
+- `ItemSeparator`: horizontal `Separator`.
+- All components accept native props for their rendered element and `className`.
+
+## Do
+
+- Keep a stable left-middle-right scan order.
+- Add `min-w-0` to flexible content and truncate or line-clamp unpredictable text.
+- Keep times, counts, and status controls `shrink-0`.
+- Make selected state visible with more than color when practical.
+- Expose hover actions on focus and through a menu or app command.
+- Use separators or a shared group surface for rhythm instead of one floating card per row.
+
+## Don't
+
+- Do not nest links or buttons inside a whole-row link.
+- Do not let badges and actions push the primary label out of view.
+- Do not make every row tall enough to look like a marketing card.
+- Do not hide the only route to an action behind hover.
+- Do not place unbounded text in a fixed-height row.
+
+## Moldable considerations
+
+For repeated object browsers, `size="sm"` is the useful baseline; tune row height toward the app archetype rather than adding padding for decoration. A scrolling item group should clear chat with `pb-[calc(var(--chat-safe-padding,0px)+1rem)]`, or more when a bottom dock is present.
+
+Use the selected item to update desktop chat instructions with specific object context. Important row actions should be available through Cmd+K or a contextual menu, especially when the visual action is compact or hover-revealed.

package/src/components/ui/list.md

@@ -0,0 +1,107 @@
+# List
+
+## Purpose
+
+`List` is a keyboard-aware collection for compact rows such as files, sessions, workspaces, commands, and inspector results. It owns roving focus, optional selection, disabled-item behavior, and activation without forcing an app-specific data model.
+
+Use `ItemGroup` for a static group that does not need collection interaction. Use `Command` for filtering and executing a command palette.
+
+## Basic usage
+
+```tsx
+import {
+  List,
+  ListItem,
+  ListItemContent,
+  ListItemDescription,
+  ListItemTitle,
+} from '@moldable-ai/ui'
+
+<List
+  aria-label="Documents"
+  selectionMode="single"
+  defaultSelectedValues={['brief']}
+  onAction={(value) => openDocument(value)}
+>
+  <ListItem value="brief">
+    <ListItemContent>
+      <ListItemTitle>Project brief</ListItemTitle>
+      <ListItemDescription>Edited 8 minutes ago</ListItemDescription>
+    </ListItemContent>
+  </ListItem>
+  <ListItem value="archive" disabled>
+    <ListItemContent>
+      <ListItemTitle>Archive</ListItemTitle>
+      <ListItemDescription>Unavailable offline</ListItemDescription>
+    </ListItemContent>
+  </ListItem>
+</List>
+```
+
+For controlled selection, pass an iterable to `selectedValues` and replace it when `onSelectionChange` fires:
+
+```tsx
+const [selected, setSelected] = useState<ReadonlySet<string>>(
+  () => new Set(['inbox']),
+)
+
+<List
+  aria-label="Mailboxes"
+  selectionMode="multiple"
+  selectedValues={selected}
+  onSelectionChange={setSelected}
+>
+  {/* ListItem children */}
+</List>
+```
+
+## Interaction contract
+
+- Arrow Up/Down moves through a vertical list; Arrow Left/Right moves through a horizontal list.
+- Home and End move to the first and last available item.
+- Space changes selection.
+- Enter changes selection and invokes `onAction`.
+- A single pointer click changes selection. A double click invokes `onAction`.
+- Disabled items are skipped during keyboard navigation and cannot be selected or activated.
+- Interactive descendants such as buttons and links keep their own click behavior. They do not select or activate the containing item.
+- Focus uses a roving `tabIndex`, so the collection contributes one stop to the tab order.
+
+## API summary
+
+### `List`
+
+- `selectionMode`: `none`, `single`, or `multiple`. Defaults to `none`.
+- `selectedValues` / `defaultSelectedValues`: controlled or initial selected keys.
+- `onSelectionChange(values)`: receives a new read-only `Set`.
+- `onAction(value)`: invoked by Enter or a double click.
+- `orientation`: `vertical` or `horizontal`. Defaults to `vertical`.
+- `loop`: wraps arrow navigation at collection boundaries. Defaults to `false`.
+- `disabled`: disables the entire collection.
+
+### `ListItem`
+
+- `value`: stable application key; required and independent of React's `key`.
+- `disabled`: removes the row from focus, selection, and activation.
+- Native `div` props and event handlers are composed before collection behavior. Call `event.preventDefault()` to cancel the built-in response.
+
+`ListItemContent`, `ListItemTitle`, `ListItemDescription`, and `ListItemActions` provide compact row layout without changing semantics.
+
+## Do
+
+- Give every collection a visible label or `aria-label`.
+- Keep values stable when filtering or reordering.
+- Put the primary row identity in `ListItemTitle` and secondary metadata in `ListItemDescription`.
+- Use selection to represent durable collection state and action to open or execute.
+- Keep row actions keyboard reachable; label icon-only controls.
+
+## Don't
+
+- Do not put a `List` inside another list item.
+- Do not use array indexes as values when rows can reorder.
+- Do not rely on double click as the only way to perform an important action.
+- Do not add a second manual arrow-key handler to the same collection.
+- Do not visually mark focus and selection as if they were the same state.
+
+## Window and pane guidance
+
+Lists should stay compact in sidebars and inspectors. Let the surrounding pane own its border and material; add a list background only when the list is itself a distinct surface. In narrow windows, preserve the row title and move secondary actions into a menu before truncating the primary label.