@moldable-ai/ui 0.2.18 → 0.2.20

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,21 @@
+# 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.