@moldable-ai/ui 0.2.18 → 0.2.20

package/src/components/ui/notification-dot.md

@@ -0,0 +1,7 @@
+# NotificationDot
+
+A tiny, decorative unread or changed-state marker.
+
+Pair the dot with adjacent accessible text or an accessible label on its
+container. The dot is intentionally hidden from assistive technology.
+Use `Status` when the state needs a spoken label or semantic tone.

package/src/components/ui/number-input.md

@@ -0,0 +1,19 @@
+# NumberInput
+
+Compact numeric entry with optional unit and stepper actions.
+
+```tsx
+<NumberInput
+  aria-label="Opacity"
+  min={0}
+  max={100}
+  unit="%"
+  value={opacity}
+  onValueChange={setOpacity}
+/>
+```
+
+Use in inspectors and settings where the numeric value matters. Use `Slider`
+when relative adjustment matters more than exact entry. Always supply a visible
+label or `aria-label`. Treat `null` as empty input and validate domain-specific
+constraints outside the component.

package/src/components/ui/panel.md

@@ -0,0 +1,11 @@
+# Panel
+
+Semantic app panes with fixed chrome and independently scrolling content.
+
+`PanelGroup` lays out panes horizontally or vertically. `Panel` owns the
+surface; `PanelHeader`, `PanelContent`, and `PanelFooter` define its regions.
+Use `surface="sidebar"` for source/navigation panes and reserve `Card` for
+bounded content groups inside a pane.
+
+The group and its containing shell need a definite height. Long content belongs
+in `PanelContent`, and chat-safe padding belongs on that scrolling region.

package/src/components/ui/resizable.md

@@ -0,0 +1,66 @@
+# Resizable
+
+## Purpose
+
+The resizable primitives create user-adjustable panes for technical and object-heavy workspaces. Use them when two or more views need to stay visible, such as navigation/editor/inspector or query/results.
+
+Use a stable flex split when resizing does not materially help. Use `Sidebar` for application navigation that needs collapse and narrow-screen sheet behavior.
+
+## Usage patterns
+
+```tsx
+import {
+  ResizableHandle,
+  ResizablePanel,
+  ResizablePanelGroup,
+} from '@moldable-ai/ui'
+
+;<ResizablePanelGroup orientation="horizontal" className="h-full min-h-0">
+  <ResizablePanel defaultSize="24%" minSize="14%">
+    <nav className="h-full min-h-0 overflow-y-auto pb-[calc(var(--chat-safe-padding,0px)+1rem)]">
+      {/* Object browser */}
+    </nav>
+  </ResizablePanel>
+  <ResizableHandle withHandle />
+  <ResizablePanel minSize="35%">
+    <section className="h-full min-h-0 overflow-hidden">
+      {/* Workspace */}
+    </section>
+  </ResizablePanel>
+</ResizablePanelGroup>
+```
+
+Use `orientation="vertical"` for editor/results splits. Each panel should establish its own overflow behavior; the panel group itself should remain bounded by a full-height parent.
+
+## API summary
+
+- `ResizablePanelGroup`: wraps `react-resizable-panels` `Group`; `orientation` is `"horizontal"` or `"vertical"` and defaults upstream to horizontal.
+- `ResizablePanel`: wraps `Panel` and accepts its sizing, collapse, callback, id, and ref props.
+- `ResizablePanel` also accepts `groupResizeBehavior` for compatibility, but the current wrapper intentionally does not forward or act on it.
+- `ResizableHandle`: wraps `Separator`; `withHandle` adds a visible grip.
+- All parts accept `className` where supported by their underlying primitive.
+
+Refer to the installed `react-resizable-panels` version for precise size units and imperative ref APIs; keep all panels on the same convention.
+
+## Do
+
+- Give the group and all ancestors a stable `h-full min-h-0`.
+- Set sensible default and minimum sizes based on the content’s real scan width.
+- Use `withHandle` when a one-pixel divider would be difficult to discover.
+- Keep each pane’s toolbar fixed and its content intentionally scrollable.
+- Preserve keyboard focus indication on separators.
+- Collapse or replace secondary panes at narrow widths when necessary.
+
+## Don't
+
+- Do not make every surface resizable.
+- Do not allow a pane to shrink until labels, editors, or controls become unusable.
+- Do not put document scrolling on the panel group or `body`.
+- Do not animate pane size for decoration.
+- Do not assume resizable desktop panes automatically become a good narrow layout.
+
+## Moldable considerations
+
+Resizable layouts are the default fit for database, code, file, debugging, and inspector-style apps. Keep pane toolbars around `h-8` or `h-9`, use mono text for code/data, and avoid nested card shells.
+
+Every independently scrolling pane that reaches the bottom needs its own `--chat-safe-padding`. A bottom control dock may require additional space beyond the standard pane padding. When selection changes in any pane, keep the other panes, app commands, and desktop chat context synchronized.

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

@@ -0,0 +1,68 @@
+# Scroll Area
+
+## Purpose
+
+`ScrollArea` provides a styled vertical scrollbar while preserving a native-feeling scroll viewport. Use it for bounded lists, object browsers, menus, and panes where consistent scrollbar appearance is useful.
+
+For simple content, a native `overflow-y-auto` region is often sufficient. The important design decision is which pane scrolls, not whether every pane uses a custom scrollbar.
+
+## Usage patterns
+
+```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>
+```
+
+For a grouped list:
+
+```tsx
+<ScrollArea className="h-full px-5 pt-3">
+  <div className="mx-auto w-full max-w-[44rem] space-y-8 pb-[calc(var(--chat-safe-padding,0px)+6rem)]">
+    {/* Groups */}
+  </div>
+</ScrollArea>
+```
+
+The current `ScrollArea` composition installs a vertical scrollbar automatically.
+
+## API summary
+
+- `ScrollArea`: Radix Scroll Area root with a full-size viewport, vertical `ScrollBar`, and corner.
+- Accepts Radix root props, forwarded `ref`, and `className`.
+- `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.
+
+## Do
+
+- 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.
+- Keep sticky headers inside the same scrolling context as their content.
+- Test keyboard, wheel, trackpad, and scrollbar-thumb interaction.
+
+## Don't
+
+- Do not rely on document/body scrolling for a full Moldable app.
+- Do not nest scroll areas unless each axis or pane has a clear purpose.
+- 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.
+
+## Moldable considerations
+
+Choose padding based on the surface:
+
+- General full-view content: `pb-[calc(var(--chat-safe-padding,0px)+6rem)]`
+- Long document/editor content: `pb-[calc(var(--chat-safe-padding,0px)+8rem)]`
+- Tables and inspectors: `pb-[var(--chat-safe-padding,0px)]`
+- Side panes and object browsers: `pb-[calc(var(--chat-safe-padding,0px)+1rem)]`
+
+Increase it when a fixed action dock also occupies the bottom. Empty, error, and loading states rendered in a scroll area need the same clearance as normal content.

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

@@ -0,0 +1,33 @@
+# Search Field
+
+## Purpose
+
+`SearchField` is a native search input with consistent icon, density, loading, clear, invalid, disabled, and focus states. It supports controlled and uncontrolled values without replacing browser text-entry behavior.
+
+## Usage
+
+```tsx
+import { SearchField } from '@moldable-ai/ui'
+
+<SearchField
+  aria-label="Search projects"
+  value={query}
+  onValueChange={setQuery}
+  placeholder="Search projects"
+  density="compact"
+  loading={isSearching}
+/>
+```
+
+Use `value`/`onValueChange` for a controlled field or `defaultValue` for an uncontrolled field. `variant` is `default` or `filled`; `density` is `compact`, `default`, or `comfortable`. `clearable` defaults to true. Escape and the clear action empty a non-empty field, refocus it, and call `onClear`.
+
+## Quality bar
+
+- Provide a visible label or an accessible `aria-label`.
+- Keep placeholder text short; it is a hint, not the field’s name.
+- Debounce network-backed filtering outside the component and use `loading` while results update.
+- Keep keyboard focus in the field after clearing.
+- Announce result counts or no-results changes in the results region when that feedback matters.
+- Do not add a second clear button, bind Escape to close a parent view while the field contains text, or replace native editing shortcuts.
+
+Search fields in narrow toolbars should use compact density and a useful minimum width. A global app or command search may be surfaced by the host, but local collection filtering remains app-owned.

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

@@ -0,0 +1,39 @@
+# Segmented Control
+
+## Purpose
+
+`SegmentedControl` switches between a small set of mutually exclusive modes. It uses radio-group semantics, so one option is selected and arrow keys move selection without requiring custom keyboard code.
+
+Use it for choices such as list/grid, week/month, or preview/edit. Use `Tabs` when each option labels a corresponding content panel, and use `RadioGroup` for form choices that need longer supporting text.
+
+## Usage
+
+```tsx
+import {
+  SegmentedControl,
+  SegmentedControlItem,
+} from '@moldable-ai/ui'
+
+<SegmentedControl
+  aria-label="Calendar view"
+  value={view}
+  onValueChange={setView}
+  density="compact"
+>
+  <SegmentedControlItem value="week">Week</SegmentedControlItem>
+  <SegmentedControlItem value="month">Month</SegmentedControlItem>
+</SegmentedControl>
+```
+
+The root supports controlled `value`/`onValueChange` and uncontrolled `defaultValue`. `variant` is `muted` or `outline`; `density` is `compact`, `default`, or `comfortable`; `fullWidth` lets each item share the available width.
+
+## Quality bar
+
+- Keep two to five literal, parallel labels in one group.
+- Give the group an `aria-label` or `aria-labelledby`.
+- Keep icon-only items exceptional. When used, set `iconOnly` and give every item an `aria-label`.
+- Let the radio-group implementation own focus, arrow-key movement, and selected semantics.
+- Use `fullWidth` only when equal-width choices improve scanning in a narrow pane.
+- Do not use a segmented control for commands, independent toggles, or navigation between unrelated destinations.
+
+In a standalone app window, keep compact segments in a title toolbar or near the content they change. Do not imitate host window controls or place app actions inside a host-owned control inset.

package/src/components/ui/sidebar.md

@@ -0,0 +1,113 @@
+# Sidebar
+
+## Purpose
+
+The sidebar primitives build persistent app navigation or an object browser that can collapse on desktop and become a sheet on narrow screens. Use them when users need to switch repeatedly among sections, collections, or saved objects while keeping a working surface visible.
+
+Do not add a sidebar to a focused single-workflow app. A list-to-detail layout may need only a stable list pane, while technical workspaces may be better served by `ResizablePanelGroup`.
+
+## Usage patterns
+
+```tsx
+import { Inbox } from 'lucide-react'
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarInset,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarProvider,
+  SidebarTrigger,
+} from '@moldable-ai/ui'
+
+;<SidebarProvider className="h-full min-h-0">
+  <Sidebar collapsible="icon">
+    <SidebarContent className="pb-[calc(var(--chat-safe-padding,0px)+1rem)]">
+      <SidebarGroup>
+        <SidebarGroupLabel>Mailboxes</SidebarGroupLabel>
+        <SidebarGroupContent>
+          <SidebarMenu>
+            <SidebarMenuItem>
+              <SidebarMenuButton
+                isActive
+                tooltip="Inbox"
+                className="cursor-pointer"
+              >
+                <Inbox />
+                <span>Inbox</span>
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+          </SidebarMenu>
+        </SidebarGroupContent>
+      </SidebarGroup>
+    </SidebarContent>
+  </Sidebar>
+  <SidebarInset className="h-full min-h-0 overflow-hidden">
+    <header className="border-border/70 flex h-9 shrink-0 items-center border-b px-2">
+      <SidebarTrigger className="cursor-pointer" />
+    </header>
+    {/* Main pane */}
+  </SidebarInset>
+</SidebarProvider>
+```
+
+Keep each menu item’s icon and last text span direct children of `SidebarMenuButton`; the component uses that shape for icon sizing and text truncation.
+
+## API summary
+
+### State and shell
+
+- `SidebarProvider`: required context. Supports uncontrolled `defaultOpen`, controlled `open`/`onOpenChange`, and CSS variable overrides through `style`.
+- `useSidebar()`: returns `state`, `open`, `setOpen`, `openMobile`, `setOpenMobile`, `isMobile`, and `toggleSidebar`.
+- `Sidebar`: `side="left" | "right"`, `variant="sidebar" | "floating" | "inset"`, and `collapsible="offcanvas" | "icon" | "none"`.
+- `SidebarInset`: main content surface paired with the sidebar.
+- `SidebarTrigger`: compact toggle button.
+- `SidebarRail`: pointer target along the sidebar edge.
+
+### Structure
+
+- `SidebarHeader`, `SidebarFooter`, `SidebarContent`, and `SidebarSeparator` divide the vertical shell.
+- `SidebarInput` is a compact search/filter input.
+- `SidebarGroup`, `SidebarGroupLabel`, `SidebarGroupAction`, and `SidebarGroupContent` organize sections.
+
+### Menus
+
+- `SidebarMenu` and `SidebarMenuItem` provide list structure.
+- `SidebarMenuButton`: `isActive`, `variant="default" | "outline"`, `size="default" | "sm" | "lg"`, optional `asChild`, and `tooltip`.
+- `SidebarMenuAction`: optional `asChild` and `showOnHover`.
+- `SidebarMenuBadge`: compact trailing count.
+- `SidebarMenuSkeleton`: optional `showIcon`.
+- `SidebarMenuSub`, `SidebarMenuSubItem`, and `SidebarMenuSubButton`: one nested level; sub-button size is `sm` or `md`.
+
+The provider persists expanded state in the `sidebar_state` cookie and handles Command/Ctrl+B. Collapsed-menu tooltips are built into `SidebarMenuButton` when `tooltip` is provided.
+
+## Do
+
+- Put the provider around both sidebar and inset.
+- Use one clear active item and update it with navigation state.
+- Add tooltips to icon-collapsible menu buttons.
+- Give group and menu actions accessible names; make hover actions visible on focus.
+- Keep labels in a truncatable span and counts/actions in stable trailing positions.
+- Use `SidebarContent` as the intentional scrolling region.
+- Test expanded, collapsed, off-canvas, and narrow-sheet states.
+
+## Don't
+
+- Do not restate the app name as a large sidebar or content heading.
+- Do not add more than one meaningful nesting level.
+- Do not use the sidebar as a dumping ground for every command.
+- Do not place the only access to an action in a hover-only control.
+- Do not assume desktop width is always available inside a webview pane.
+- Do not add an app-local chat or assistant section.
+
+## Moldable considerations
+
+Override the shell for the embedded full-height environment with `h-full min-h-0` and keep the main inset `overflow-hidden`. Add chat-safe bottom padding to `SidebarContent`, because object browsers and navigation lists can extend behind desktop chat independently of the main pane.
+
+The built-in Command/Ctrl+B shortcut must not conflict with editor-local bold formatting or another essential command in the same context. If it does, control sidebar state elsewhere or revisit the shortcut at the package level.
+
+Use semantic `sidebar-*` tokens already provided by the component. In an object browser, post the active connection, collection, or selected object to desktop chat instructions and expose frequent switches through app commands.

package/src/components/ui/sonner.md

@@ -0,0 +1,37 @@
+# Toasts
+
+Mount one `Toaster` near the app root and call the shared `toast` API from
+actions, mutations, and background work.
+
+```tsx
+import { Toaster, toast } from '@moldable-ai/ui'
+
+function App() {
+  return (
+    <>
+      <Workspace />
+      <Toaster position="bottom-center" />
+    </>
+  )
+}
+
+async function save() {
+  await toast.promise(saveDocument(), {
+    loading: 'Saving…',
+    success: 'Saved',
+    error: 'Could not save',
+  })
+}
+```
+
+## Recipes
+
+- Use a success toast only when the result is not already obvious in the
+  canvas.
+- Keep loading, success, and error text stable for a single promise.
+- Put undo in the toast action for reversible destructive work.
+- Use an alert or inline field message when the user must resolve the problem
+  before continuing.
+- Keep one `Toaster` per app window. A host shell must not absorb app-owned
+  notifications.
+- Toast text must describe the result, not expose transport or server details.

package/src/components/ui/split-view.md

@@ -0,0 +1,15 @@
+# SplitView
+
+Semantic naming over resizable panel primitives.
+
+```tsx
+<SplitView orientation="horizontal">
+  <SplitViewPane defaultSize="30%">…</SplitViewPane>
+  <SplitViewHandle />
+  <SplitViewPane>…</SplitViewPane>
+</SplitView>
+```
+
+Use when pane resizing is part of the workflow. Provide sensible minimum and
+default sizes, preserve important content, and persist sizes only when that
+improves repeated work. Use `PanelGroup` for non-resizable layouts.

package/src/components/ui/status.md

@@ -0,0 +1,12 @@
+# Status
+
+Compact dot-and-label feedback for state.
+
+```tsx
+<Status variant="running" animated>Recording</Status>
+<Status variant="success">Synced</Status>
+```
+
+Use `running` or `pending` animation only for active work. Use `Badge` for
+categories and labels. Keep a text label when the meaning is important; color
+alone is insufficient.

package/src/components/ui/table.md

@@ -0,0 +1,35 @@
+# Table
+
+Structured, comparable data with shared density and row-selection behavior.
+
+```tsx
+<Table density="compact">
+  <TableHeader>
+    <TableRow>
+      <TableHead>Name</TableHead>
+      <TableHead>Status</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    {rows.map((row) => (
+      <TableRow
+        key={row.id}
+        selected={selection.has(row.id)}
+        onSelectionChange={(selected) => updateSelection(row.id, selected)}
+      >
+        <TableCell>{row.name}</TableCell>
+        <TableCell>{row.status}</TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+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.
+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/tabs.md

@@ -0,0 +1,66 @@
+# Tabs
+
+## Purpose
+
+Tabs switch between peer views of the same object or workspace without changing the overall context. Use them for compact modes such as Notes/Transcript, Query/Results, or Details/Activity.
+
+Use navigation when each destination is a distinct location. Use `ToggleGroup` for display controls that do not own tab panels.
+
+## Usage patterns
+
+```tsx
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@moldable-ai/ui'
+
+;<Tabs defaultValue="notes" className="h-full min-h-0">
+  <TabsList aria-label="Meeting view">
+    <TabsTrigger value="notes">Notes</TabsTrigger>
+    <TabsTrigger value="transcript">Transcript</TabsTrigger>
+  </TabsList>
+  <TabsContent value="notes" className="min-h-0 overflow-y-auto">
+    {/* Notes */}
+  </TabsContent>
+  <TabsContent value="transcript" className="min-h-0 overflow-y-auto">
+    {/* Transcript */}
+  </TabsContent>
+</Tabs>
+```
+
+Use the `line` variant in dense app chrome where a filled segmented control would be too prominent:
+
+```tsx
+<TabsList variant="line">
+  <TabsTrigger value="schema">Schema</TabsTrigger>
+  <TabsTrigger value="data">Data</TabsTrigger>
+</TabsList>
+```
+
+## API summary
+
+- `Tabs`: Radix Tabs root; supports controlled `value`/`onValueChange`, `defaultValue`, `orientation`, activation direction, and other root props. Orientation defaults to `horizontal`.
+- `TabsList`: `variant="default"` or `"line"`. Defaults to `default`.
+- `TabsTrigger`: requires a `value` matching a content panel; supports `disabled`.
+- `TabsContent`: requires a matching `value`.
+- `tabsListVariants` is exported for compatible composition.
+- Components accept the corresponding Radix primitive props and `className`.
+
+## Do
+
+- Use short, parallel labels.
+- Keep the number of tabs small enough to fit without ambiguous truncation.
+- Use controlled state when the active tab affects URL state, commands, or desktop chat context.
+- Put scrolling on the active content pane with `min-h-0`, not on the whole app.
+- Preserve keyboard navigation and focus states supplied by Radix.
+
+## Don't
+
+- Do not use tabs as a substitute for primary navigation or a command toolbar.
+- Do not mix actions such as “Add” or “Refresh” into the tab list.
+- Do not put unrelated workflows behind peer tabs.
+- Do not change tab labels or order unpredictably.
+- Do not rely on a subtle color change alone; retain the active background or line indicator.
+
+## Moldable considerations
+
+Tabs belong in compact chrome, not a large page header. In document and paneled layouts, keep their bar around `h-8` or `h-9`. When a tab panel scrolls to the bottom of the webview, add `pb-[calc(var(--chat-safe-padding,0px)+1rem)]` or the larger padding appropriate to an editor or dock.
+
+Changing tabs should update app commands and chat instructions when it materially changes the active object or mode. Do not create an “AI chat” tab; Moldable’s desktop chat is the conversational surface.

package/src/components/ui/text.md

@@ -0,0 +1,17 @@
+# Text
+
+Semantic typography for app content and chrome.
+
+## Usage
+
+```tsx
+<Text as="h1" variant="heading1">Library</Text>
+<Text variant="small" color="secondary">12 local items</Text>
+```
+
+Use the `as` prop for correct HTML semantics and `variant` for visual hierarchy.
+`truncate` is appropriate only when the full value remains available through
+context or a tooltip. Use mono variants for identifiers, code, and numeric
+readouts—not body copy.
+
+Do not recreate the type scale with arbitrary font sizes.

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

@@ -0,0 +1,80 @@
+# Toggle Group
+
+## Purpose
+
+`ToggleGroup` presents a compact set of related choices. Use it for a mutually exclusive view mode or a small set of independently pressed formatting options.
+
+Use `Tabs` when each choice owns a content panel. Use `RadioGroup` when a form choice needs visible labels and conventional form semantics.
+
+## Usage patterns
+
+Single selection:
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from '@moldable-ai/ui'
+
+;<ToggleGroup
+  type="single"
+  value={layout}
+  onValueChange={(value) => value && setLayout(value)}
+  variant="outline"
+  size="sm"
+  aria-label="Result layout"
+>
+  <ToggleGroupItem value="table" className="cursor-pointer">
+    Table
+  </ToggleGroupItem>
+  <ToggleGroupItem value="json" className="cursor-pointer">
+    JSON
+  </ToggleGroupItem>
+</ToggleGroup>
+```
+
+Multiple selection:
+
+```tsx
+<ToggleGroup type="multiple" spacing={1} aria-label="Text formatting">
+  <ToggleGroupItem value="bold" className="cursor-pointer" aria-label="Bold">
+    <Bold />
+  </ToggleGroupItem>
+  <ToggleGroupItem
+    value="italic"
+    className="cursor-pointer"
+    aria-label="Italic"
+  >
+    <Italic />
+  </ToggleGroupItem>
+</ToggleGroup>
+```
+
+## API summary
+
+- `ToggleGroup`: Radix Toggle Group root. `type="single"` uses a string value; `type="multiple"` uses a string array.
+- Supports controlled `value`/`onValueChange` and uncontrolled `defaultValue`.
+- `variant`: `default` or `outline`, shared with each item.
+- `size`: `default`, `sm`, or `lg`, shared with each item.
+- `spacing`: numeric Tailwind spacing multiplier; defaults to `0`. At zero, items join into one segmented shape.
+- `ToggleGroupItem`: requires `value`; may override `variant` or `size` when the group does not supply them.
+- Both parts accept corresponding Radix primitive props and `className`.
+
+## Do
+
+- Use `type="single"` for one active display mode and `type="multiple"` only when choices can coexist.
+- In a required single-choice group, ignore an empty `onValueChange` value so the active choice cannot be cleared.
+- Give the group and any icon-only item accessible names.
+- Use `spacing={0}` for a segmented control and positive spacing for separate toolbar toggles.
+- Keep labels short and the item count low.
+
+## Don't
+
+- Do not use the group for unrelated actions.
+- Do not assume `type="single"` always keeps one choice selected.
+- Do not mix text-heavy and icon-only choices without stable sizing.
+- Do not let the group overflow a narrow toolbar without an alternate layout.
+- Do not use color as the only selected-state cue.
+
+## Moldable considerations
+
+Use toggle groups in quiet `h-8` or `h-9` toolbars, inspectors, and result panes. Prefer a text label when an icon could be misread; when icons are familiar, pair each with a tooltip.
+
+If the selected mode changes the visible dataset or selected object, keep command state and desktop chat instructions in sync. Toggle groups near the bottom of the webview must remain above fixed docks and `--chat-safe-padding`.