@moldable-ai/ui 0.2.20 → 0.2.21

package/src/components/ui/list.md

@@ -17,7 +17,7 @@ import {
   ListItemTitle,
 } from '@moldable-ai/ui'
 
-<List
+;<List
   aria-label="Documents"
   selectionMode="single"
   defaultSelectedValues={['brief']}
@@ -38,6 +38,28 @@ import {
 </List>
 ```
 
+## Sections
+
+Group related options with `ListSection` and give every section an accessible
+name. `ListSectionHeader` automatically labels its containing section:
+
+```tsx
+<List aria-label="Documents" selectionMode="single">
+  <ListSection>
+    <ListSectionHeader>Recent</ListSectionHeader>
+    <ListItem value="brief">Project brief</ListItem>
+    <ListItem value="notes">Research notes</ListItem>
+  </ListSection>
+  <ListSection aria-label="Archived documents">
+    <ListItem value="archive">Archive</ListItem>
+  </ListSection>
+</List>
+```
+
+Use either `ListSectionHeader`, `aria-label`, or an explicit
+`aria-labelledby` value for each section. Keyboard movement follows the
+rendered DOM order across section boundaries.
+
 For controlled selection, pass an iterable to `selectedValues` and replace it when `onSelectionChange` fires:
 
 ```tsx
@@ -63,8 +85,9 @@ const [selected, setSelected] = useState<ReadonlySet<string>>(
 - 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.
+- Interactive descendants such as buttons and links keep their own pointer 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.
+- When the list first mounts, the first selected, enabled item receives the roving tab stop. If nothing is selected, the first enabled item receives it.
 
 ## API summary
 
@@ -86,9 +109,16 @@ const [selected, setSelected] = useState<ReadonlySet<string>>(
 
 `ListItemContent`, `ListItemTitle`, `ListItemDescription`, and `ListItemActions` provide compact row layout without changing semantics.
 
+### `ListSection`
+
+- Groups related items with `role="group"`.
+- Use `ListSectionHeader` for an automatically connected visible label.
+- Alternatively, provide `aria-label` or `aria-labelledby`.
+
 ## Do
 
 - Give every collection a visible label or `aria-label`.
+- Give every section an accessible 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.
@@ -98,6 +128,9 @@ const [selected, setSelected] = useState<ReadonlySet<string>>(
 
 - Do not put a `List` inside another list item.
 - Do not use array indexes as values when rows can reorder.
+- Do not put buttons, links, or other interactive controls inside selectable
+  listbox items. Put independent actions outside the listbox or use a pattern
+  whose child-interaction model supports them.
 - 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.

package/src/components/ui/material.md

@@ -0,0 +1,51 @@
+# Material
+
+Adaptive material for navigation and control chrome.
+
+```tsx
+<Material asChild variant="regular" elevation="none">
+  <Toolbar>{/* context and actions */}</Toolbar>
+</Material>
+
+<MaterialGroup variant="regular" shape="capsule" spacing="compact">
+  <IconButton label="Previous" variant="ghost">
+    <ChevronLeft />
+  </IconButton>
+  <IconButton label="Next" variant="ghost">
+    <ChevronRight />
+  </IconButton>
+</MaterialGroup>
+```
+
+## Variants
+
+- `regular` provides a frosted, legible control or navigation layer.
+- `clear` is less frosted and is only for compact controls floating over
+  photos, maps, video, or another richly colored canvas.
+
+Both variants start with an opaque fallback. Backdrop sampling is enabled only
+when the renderer supports it. Reduced transparency and forced colors keep the
+fallback opaque.
+
+## Grouping
+
+`MaterialGroup` creates one sampled layer for a related cluster. Put ordinary
+ghost or transparent controls inside it. Do not wrap each child in another
+`Material`; nested sampling creates muddy, inconsistent results.
+
+Use separate `Material` instances only when controls are spatially detached and
+do not read as one group.
+
+## Rules
+
+- Use material for toolbars, compact floating controls, menus, and other
+  temporary control layers.
+- Keep documents, calendars, tables, forms, cards, sheets, and primary content
+  canvases opaque.
+- Prefer `regular`. A `clear` surface needs stable contrast across every part
+  of the media behind it.
+- Use `interactive` only when the material surface itself is the control.
+- Do not animate blur or saturation. Shared motion tokens provide restrained
+  press feedback and remove it when reduced motion is requested.
+- CSS material samples content inside the renderer. Native behind-window
+  material remains owned by the host.

package/src/components/ui/navigation-button-group.md

@@ -0,0 +1,46 @@
+# NavigationButtonGroup
+
+`NavigationButtonGroup` presents paired back and forward actions with one
+consistent compact treatment.
+
+```tsx
+<NavigationButtonGroup
+  canGoBack={historyIndex > 0}
+  canGoForward={historyIndex < history.length - 1}
+  onBack={goBack}
+  onForward={goForward}
+/>
+```
+
+## API
+
+- `canGoBack` and `canGoForward` disable unavailable directions.
+- `onBack` and `onForward` perform caller-owned navigation.
+- `backLabel` and `forwardLabel` customize accessible names.
+- `size` accepts the `IconButton` size scale.
+- `variant` is `ghost` or `outline`.
+- Native `ButtonGroup` props apply to the group.
+
+## Keyboard and accessibility
+
+The root has `role="group"` and the default accessible name “Navigation”.
+Each icon button has a stable accessible name and participates in normal Tab
+order. The component does not install global keyboard shortcuts.
+
+## Platform behavior
+
+This component is portable. It does not own browser history, Moldable
+navigation state, or native window history. Connect it to the navigation owner
+for the current surface.
+
+## Do
+
+- Put it in a leading toolbar group.
+- Disable unavailable directions.
+- Keep back and forward behavior scoped to the visible pane or app.
+
+## Don't
+
+- Do not render a fake forward action when no forward history exists.
+- Do not use it for undo and redo.
+- Do not add a second tooltip around its buttons.

package/src/components/ui/popover.md

@@ -0,0 +1,31 @@
+# Popover
+
+Use `Popover` for a small, interactive surface anchored to a control. Use
+`Tooltip` for terse non-interactive help, `HoverCard` for a preview, and
+`Dialog` for a blocking task.
+
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline">View options</Button>
+  </PopoverTrigger>
+  <PopoverContent size="sm" material="regular">
+    <PopoverHeader>
+      <PopoverTitle>View options</PopoverTitle>
+      <PopoverDescription>Choose what appears in the list.</PopoverDescription>
+    </PopoverHeader>
+    {/* interactive controls */}
+  </PopoverContent>
+</Popover>
+```
+
+Sizes are `content`, `sm`, `default`, and `lg`. Content is capped to the
+collision-aware available width and height and scrolls when necessary.
+`material="regular"` is the standard temporary overlay. Use `clear` only above
+media or a richly colored canvas where the stronger sampled effect has a clear
+layering purpose.
+
+`PopoverClose`, `PopoverPortal`, and `PopoverArrow` are available when the
+composition needs them. Provide an accessible name on an icon-only close
+action. Keep required instructions and critical actions discoverable without
+hover.

package/src/components/ui/scroll-area.md

@@ -11,10 +11,8 @@ For simple content, a native `overflow-y-auto` region is often sufficient. The i
 ```tsx
 import { ScrollArea } from '@moldable-ai/ui'
 
-;<ScrollArea className="h-full min-h-0">
-  <div className="px-3 pb-[calc(var(--chat-safe-padding,0px)+1rem)] pt-3">
-    {/* Long list */}
-  </div>
+;<ScrollArea className="h-full min-h-0" safeBottom>
+  <div className="px-3 pt-3">{/* Long list */}</div>
 </ScrollArea>
 ```
 
@@ -28,12 +26,17 @@ For a grouped list:
 </ScrollArea>
 ```
 
-The current `ScrollArea` composition installs a vertical scrollbar automatically.
+The current `ScrollArea` composition installs a vertical scrollbar by default.
+Set `scrollbars` to `horizontal`, `both`, or `none` for another explicit
+configuration.
 
 ## API summary
 
 - `ScrollArea`: Radix Scroll Area root with a full-size viewport, vertical `ScrollBar`, and corner.
 - Accepts Radix root props, forwarded `ref`, and `className`.
+- `scrollbars`: `vertical`, `horizontal`, `both`, or `none`.
+- `viewportClassName`: styles the actual scrolling viewport.
+- `safeBottom`: adds the shared chat-safe padding to the viewport exactly once.
 - `ScrollBar`: exported scrollbar primitive with `orientation="vertical" | "horizontal"`; defaults to vertical.
 - The root’s direct children are rendered inside the viewport.
 - The viewport supplies focus-visible outline and ring treatment.
@@ -43,7 +46,7 @@ The current `ScrollArea` composition installs a vertical scrollbar automatically
 - Give the scroll area a definite height through its own class and full-height ancestors.
 - Put padding on an inner content wrapper when it should scroll with the content.
 - Add `min-h-0` to flex or grid ancestors.
-- Add bottom chat-safe padding inside every scroll region that reaches the webview bottom.
+- Enable `safeBottom` on every owning scroll region that reaches the webview bottom.
 - Keep sticky headers inside the same scrolling context as their content.
 - Test keyboard, wheel, trackpad, and scrollbar-thumb interaction.
 
@@ -54,7 +57,8 @@ The current `ScrollArea` composition installs a vertical scrollbar automatically
 - Do not put fixed controls inside the moving content when they must remain reachable.
 - Do not hide focus outlines.
 - Do not assume padding on a sibling pane protects this viewport from desktop chat.
-- Do not assume adding `ScrollBar` as a child of `ScrollArea` creates a second root scrollbar; children belong to the viewport in the current composition.
+- Do not add `ScrollBar` as a child of `ScrollArea`; children belong to its
+  viewport. Use the `scrollbars` prop.
 
 ## Moldable considerations
 

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

@@ -9,7 +9,7 @@
 ```tsx
 import { SearchField } from '@moldable-ai/ui'
 
-<SearchField
+;<SearchField
   aria-label="Search projects"
   value={query}
   onValueChange={setQuery}

package/src/components/ui/segmented-control.md

@@ -9,12 +9,9 @@ Use it for choices such as list/grid, week/month, or preview/edit. Use `Tabs` wh
 ## Usage
 
 ```tsx
-import {
-  SegmentedControl,
-  SegmentedControlItem,
-} from '@moldable-ai/ui'
+import { SegmentedControl, SegmentedControlItem } from '@moldable-ai/ui'
 
-<SegmentedControl
+;<SegmentedControl
   aria-label="Calendar view"
   value={view}
   onValueChange={setView}

package/src/components/ui/sheet.md

@@ -0,0 +1,30 @@
+# Sheet
+
+`Sheet` presents a secondary region from an edge while preserving the current
+workspace. It is appropriate for narrow-window navigation, filters, or an
+inspector that cannot remain beside the canvas.
+
+```tsx
+<Sheet>
+  <SheetTrigger asChild>
+    <Button variant="outline">Filters</Button>
+  </SheetTrigger>
+  <SheetContent side="right" size="default">
+    <SheetHeader>
+      <SheetTitle>Filters</SheetTitle>
+      <SheetDescription>Limit the visible results.</SheetDescription>
+    </SheetHeader>
+    <SheetBody>{/* scrolling controls */}</SheetBody>
+    <SheetFooter>{/* persistent actions */}</SheetFooter>
+  </SheetContent>
+</Sheet>
+```
+
+Side sheets support `sm`, `default`, and `lg`. All sides respect host window
+insets; their bottom edge also clears the embedded chat safe area. `SheetBody`
+is the only flexing scroll owner, leaving its header, close action, and footer
+reachable.
+
+Use `Dialog` when the task is centered and blocking, `Drawer` for touch-first
+presentation, and `Inspector` when contextual properties should remain visible
+beside the canvas. Do not use a sheet as permanent desktop navigation.

package/src/components/ui/table.md

@@ -29,7 +29,9 @@ Use `compact` for inspector-like datasets, `default` for general work, and
 `comfortable` where scanning matters more than density.
 
 When a row is selectable, selection is controlled by the caller and can be
-toggled with pointer, Enter, or Space. Put independent actions inside buttons
-and call `event.stopPropagation()` if activating them must not select the row.
+toggled with pointer, Enter, or Space. Independent buttons, links, form
+controls, and editable descendants keep their own pointer and keyboard
+behavior without toggling the containing row. Call `event.preventDefault()` in
+a row event handler only when an app needs to cancel the built-in row response.
 For rich grid navigation, column sorting, or cell editing, use a dedicated data
 grid rather than layering those interactions onto a basic table.

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

@@ -0,0 +1,48 @@
+# ToggleButton
+
+`ToggleButton` is a single pressed/unpressed action. It is a semantic facade
+over `Toggle`, so both share one Radix interaction model and one style source.
+
+```tsx
+<ToggleButton pressed={showGrid} onPressedChange={setShowGrid}>
+  Show grid
+</ToggleButton>
+```
+
+For an icon-only toggle, opt in explicitly and provide its accessible name:
+
+```tsx
+<ToggleButton
+  iconOnly
+  aria-label="Pin inspector"
+  pressed={pinned}
+  onPressedChange={setPinned}
+>
+  <PinIcon />
+</ToggleButton>
+```
+
+## Variants and sizes
+
+- `variant`: `default`, `outline`, or `filled`.
+- `size`: `xs`, `sm`, `default`, or `lg`.
+- `iconOnly` makes the control square and requires `aria-label`.
+
+## Choosing the right control
+
+- Use `Button` for a momentary action.
+- Use `ToggleButton` for one independent visible mode or tool.
+- Use `SegmentedControl` for exactly one choice from a small set.
+- Use `Switch` for a persistent setting that takes effect immediately.
+
+## Keyboard and accessibility
+
+Radix supplies button and `aria-pressed` semantics. Space and Enter toggle the
+state. A visible text label or `aria-label` must identify the action; state
+must not be communicated through color alone.
+
+## Don't
+
+- Do not use a toggle for a one-time command.
+- Do not group unrelated toggles into a segmented control.
+- Do not put a checkbox inside a toggle button.

package/src/components/ui/toolbar.md

@@ -19,3 +19,8 @@ Compact pane chrome for context and actions.
 Use one toolbar per pane. Put the current context before actions and keep one
 clear primary action. Toolbars are not marketing headers. Icon-only actions
 need labels and tooltips.
+
+The default toolbar uses `material="regular"`. The `plain` and `panel` variants
+default to `material="none"`; pass a material explicitly only when the toolbar
+actually floats over content. Reserve `material="clear"` for compact controls
+over media or a richly colored canvas.

package/src/components/ui/tooltip.md

@@ -0,0 +1,31 @@
+# Tooltip
+
+Tooltips provide short, non-interactive clarification for an already named
+control. They are not a replacement for an accessible name or visible
+instructions.
+
+`ThemeProvider` installs one shared `TooltipProvider`, giving neighboring
+tooltips a consistent delay and grace period:
+
+```tsx
+<Tooltip>
+  <TooltipTrigger asChild>
+    <IconButton label="Search" variant="ghost">
+      <Search />
+    </IconButton>
+  </TooltipTrigger>
+  <TooltipContent>
+    Search
+    <TooltipShortcut>⌘F</TooltipShortcut>
+  </TooltipContent>
+</Tooltip>
+```
+
+Use a local `TooltipProvider` only when a bounded region needs a deliberate
+delay override. Do not put links, buttons, forms, or paragraphs of help inside
+a tooltip; use `Popover` instead.
+
+A disabled button does not emit pointer events. When it needs an explanation,
+wrap it in a focusable neutral element and use that wrapper as the trigger.
+Give the wrapper an accessible description without making the tooltip its only
+name.