@moldable-ai/ui 0.2.19 → 0.2.21

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`.

package/src/components/ui/toggle.md

@@ -0,0 +1,73 @@
+# Toggle
+
+## Purpose
+
+`Toggle` represents a persistent binary view or formatting state, such as showing a sidebar, pinning an inspector, enabling word wrap, or applying bold text.
+
+Use `Button` for a one-shot command and `Switch` for a settings-style boolean that is clearer as on/off.
+
+## Usage patterns
+
+```tsx
+import { WrapText } from 'lucide-react'
+import { Toggle } from '@moldable-ai/ui'
+
+;<Toggle
+  pressed={wrap}
+  onPressedChange={setWrap}
+  size="sm"
+  className="cursor-pointer"
+  aria-label="Wrap lines"
+>
+  <WrapText />
+  <span className="hidden sm:inline">Wrap</span>
+</Toggle>
+```
+
+For an icon-only toolbar control:
+
+```tsx
+<Toggle
+  defaultPressed
+  variant="outline"
+  size="sm"
+  className="cursor-pointer px-0"
+  aria-label="Pin inspector"
+>
+  <Pin />
+</Toggle>
+```
+
+Pair icon-only use with a tooltip.
+
+## API summary
+
+- Built on Radix Toggle and accepts its root props.
+- `pressed` and `onPressedChange`: controlled state.
+- `defaultPressed`: uncontrolled initial state.
+- `variant`: `default` or `outline`.
+- `size`: `default`, `sm`, or `lg`.
+- Supports native button accessibility props such as `aria-label` and `disabled`.
+- `toggleVariants` is exported and shared by `ToggleGroup`.
+
+## Do
+
+- Use controlled state when the preference affects another pane or persisted setting.
+- Make the pressed state legible through shape or icon treatment as well as color.
+- Add `cursor-pointer`, an accessible name, and a tooltip for icon-only toggles.
+- Keep toolbar toggles compact and aligned with adjacent controls.
+- Use a specific icon tied to the state.
+
+## Don't
+
+- Do not use a toggle for an action that immediately completes.
+- Do not label state ambiguously; prefer “Wrap lines” over “Mode”.
+- Do not use a disabled-looking style without the real `disabled` prop.
+- Do not put critical destructive or submit actions in a toggle.
+- Do not hide a primary workflow state solely in an unlabeled icon.
+
+## Moldable considerations
+
+Toggles are most useful in dense pane toolbars and editor chrome. Hide a secondary text label at narrow widths before hiding the control itself. If the state changes how the agent should interpret the current surface, update desktop chat instructions rather than adding explanatory UI.
+
+Avoid redundant controls: a sidebar controlled by `SidebarTrigger` does not need a second toggle, and app-level commands should mirror important view toggles when keyboard access matters.

package/src/components/ui/toolbar.md

@@ -0,0 +1,26 @@
+# Toolbar
+
+Compact pane chrome for context and actions.
+
+```tsx
+<Toolbar position="top">
+  <ToolbarContent>
+    <ToolbarTitle>Notes</ToolbarTitle>
+    <ToolbarDescription>Local workspace</ToolbarDescription>
+  </ToolbarContent>
+  <ToolbarActions>
+    <Button size="icon-sm" aria-label="New note">
+      <Plus />
+    </Button>
+  </ToolbarActions>
+</Toolbar>
+```
+
+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.