@moldable-ai/ui 0.2.29 → 0.2.31

package/src/components/ui/slider.md

@@ -0,0 +1,58 @@
+# Slider
+
+## Purpose
+
+`Slider` selects one value or a bounded range along a horizontal or vertical
+track. Use it when relative adjustment is more useful than exact text entry.
+
+## Usage
+
+```tsx
+import { Slider } from '@moldable-ai/ui'
+
+;<Slider
+  defaultValue={[50]}
+  min={0}
+  max={100}
+  step={5}
+  thumbAriaLabels={['Volume']}
+/>
+```
+
+For a range, provide two values and a name for each thumb:
+
+```tsx
+<Slider
+  value={[minimum, maximum]}
+  onValueChange={([nextMinimum, nextMaximum]) => {
+    setMinimum(nextMinimum)
+    setMaximum(nextMaximum)
+  }}
+  thumbAriaLabels={['Minimum price', 'Maximum price']}
+/>
+```
+
+## API
+
+- Accepts Radix Slider root props, including `value`, `defaultValue`,
+  `onValueChange`, `min`, `max`, `step`, `orientation`, and `disabled`.
+- `min` defaults to `0`; `max` defaults to `100`.
+- The number of rendered thumbs follows the length of `value` or
+  `defaultValue`. If both are omitted, the component still renders two thumb
+  elements, so pass an explicit value array.
+- `thumbAriaLabels` assigns accessible names to thumbs in value order and is
+  required for a range.
+- `rangeContent` renders inside the filled range; `thumbContent` renders inside
+  every thumb.
+- Exports `Slider`.
+
+## Guidance
+
+- Pass an explicit one-element `value` or `defaultValue` for a single-value
+  slider and two elements for a range.
+- Show the current numeric value nearby when precision matters; pair the slider
+  with a number field when direct entry is important.
+- Give every thumb an accessible name, keep range labels distinct, and preserve
+  the supplied keyboard and focus behavior.
+- Do not use a slider for a small set of named choices; use a radio or segmented
+  control instead.

package/src/components/ui/spinner.md

@@ -0,0 +1,41 @@
+# Spinner
+
+## Purpose
+
+`Spinner` communicates indeterminate work when progress cannot be measured. It
+renders a compact rotating loading icon with status semantics.
+
+## Usage
+
+```tsx
+import { Spinner } from '@moldable-ai/ui'
+
+;<Spinner aria-label="Loading results" />
+```
+
+When visible text already announces the state, hide the duplicate icon from
+assistive technology:
+
+```tsx
+<div className="flex items-center gap-2" role="status">
+  <Spinner aria-hidden="true" />
+  Loading results…
+</div>
+```
+
+## API
+
+- Accepts native SVG props and `className`.
+- Defaults to `role="status"` and `aria-label="Loading"`; either may be
+  overridden by passed props.
+- Defaults to `size-4`, spins continuously, and disables the animation when the
+  user prefers reduced motion.
+- Exports `Spinner`.
+
+## Guidance
+
+- Use a specific accessible label when the spinner is the only status content.
+- Use `aria-hidden="true"` when adjacent status text already conveys the same
+  information.
+- Keep surrounding content stable while work is in progress.
+- Use `Progress` instead when a meaningful completion percentage is available.

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

@@ -1,6 +1,6 @@
 # SplitView
 
-Semantic naming over resizable panel primitives.
+`SplitView` composes the resizable panel primitives with pane-oriented names.
 
 ```tsx
 <SplitView orientation="horizontal">
@@ -10,6 +10,10 @@ Semantic naming over resizable panel primitives.
 </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.
+`orientation` defaults to `horizontal`. `SplitViewPane` accepts the underlying
+panel sizing and collapse props. `SplitViewHandle` accepts separator props and
+adds an optional visible grip with `withHandle`.
+
+Use it when pane resizing is part of the workflow. Provide sensible minimum
+and default sizes, keep a handle between every adjacent pane, and preserve
+important content. Use ordinary flex or grid for a non-resizable layout.

package/src/components/ui/switch.md

@@ -0,0 +1,44 @@
+# Switch
+
+## Purpose
+
+`Switch` changes a boolean setting that takes effect as soon as it is toggled.
+Use it for preferences such as notifications, syncing, or visibility.
+
+## Usage
+
+```tsx
+import { Label, Switch } from '@moldable-ai/ui'
+
+;<div className="flex items-center justify-between gap-3">
+  <Label htmlFor="sync-changes">Sync changes</Label>
+  <Switch
+    id="sync-changes"
+    checked={syncChanges}
+    onCheckedChange={setSyncChanges}
+  />
+</div>
+```
+
+## API
+
+- Accepts Radix Switch root props, including `checked`, `defaultChecked`,
+  `onCheckedChange`, `disabled`, `required`, `name`, and `value`.
+- `size` is `default` or `sm` and defaults to `default`.
+- `controlSize` accepts the shared `ControlSize` values (`mini`, `small`,
+  `medium`, `large`, or `xl`) and overrides the size-derived token setting.
+- Without `controlSize`, `size="sm"` resolves to `small`; the default resolves
+  to `medium`.
+- Supports checked, unchecked, active, focus-visible, and disabled states.
+- Exports `Switch`.
+
+## Guidance
+
+- Pair the switch with a visible `Label` using `htmlFor` and `id`, or provide an
+  `aria-label` when no visible label is possible.
+- Use controlled state when the value is persisted or shared with another
+  surface.
+- Write labels for the setting itself, such as “Sync changes,” rather than
+  “Enable” or “On.”
+- Use a checkbox for selections submitted as a group and a button for one-shot
+  actions.

package/src/components/ui/table.md

@@ -28,10 +28,10 @@ Structured, comparable data with shared density and row-selection behavior.
 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. 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.
+Pass `selected` and `onSelectionChange` together for a selectable row; either
+prop alone marks the row as selectable. Selection is controlled by the caller
+and toggles with pointer, Enter, or Space. Independent buttons, links, form
+controls, and editable descendants keep their own behavior without toggling
+the row. Call `event.preventDefault()` in a row event handler only when an app
+needs to cancel the built-in response. For rich grid navigation, column
+sorting, or cell editing, use a dedicated data grid.

package/src/components/ui/tabs.md

@@ -36,7 +36,9 @@ Use the `line` variant in dense app chrome where a filled segmented control woul
 
 ## API summary
 
-- `Tabs`: Radix Tabs root; supports controlled `value`/`onValueChange`, `defaultValue`, `orientation`, activation direction, and other root props. Orientation defaults to `horizontal`.
+- `Tabs`: Radix Tabs root; supports controlled `value`/`onValueChange`,
+  `defaultValue`, `orientation`, text direction, activation mode, 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`.

package/src/components/ui/textarea.md

@@ -0,0 +1,41 @@
+# Textarea
+
+## Purpose
+
+`Textarea` is a native multiline text field for notes, descriptions, comments,
+and other freeform input.
+
+## Usage
+
+```tsx
+import { Label, Textarea } from '@moldable-ai/ui'
+
+;<div className="grid gap-2">
+  <Label htmlFor="description">Description</Label>
+  <Textarea
+    id="description"
+    name="description"
+    placeholder="Describe this project"
+    maxLength={500}
+  />
+</div>
+```
+
+## API
+
+- Accepts native `textarea` props, event handlers, and `className`.
+- Supports controlled `value`/`onChange` and uncontrolled `defaultValue`.
+- Uses content-based field sizing with a minimum height of `4rem`.
+- Includes placeholder, focus-visible, disabled, and `aria-invalid` styling.
+- Exports `Textarea`.
+
+## Guidance
+
+- Always provide a visible label; use `aria-describedby` for help or validation
+  text.
+- Set `aria-invalid="true"` only when an error is present, and associate the
+  error message with the field.
+- Add `maxLength` and a visible character count when input length is constrained.
+- Preserve the native keyboard, selection, form, and resize behavior.
+- Use `Input` for a single line and a rich-text editor only when formatting is
+  genuinely required.

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

@@ -51,8 +51,8 @@ Multiple selection:
 
 - `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.
+- `variant`: `default`, `outline`, or `filled`, shared with each item.
+- `size`: `xs`, `sm`, `default`, 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`.

package/src/components/ui/toggle.md

@@ -9,8 +9,8 @@ Use `Button` for a one-shot command and `Switch` for a settings-style boolean th
 ## Usage patterns
 
 ```tsx
-import { WrapText } from 'lucide-react'
-import { Toggle } from '@moldable-ai/ui'
+import { Pin, WrapText } from 'lucide-react'
+import { Toggle, ToggleButton } from '@moldable-ai/ui'
 
 ;<Toggle
   pressed={wrap}
@@ -24,18 +24,18 @@ import { Toggle } from '@moldable-ai/ui'
 </Toggle>
 ```
 
-For an icon-only toolbar control:
+For an icon-only toolbar control, use the typed `ToggleButton` facade:
 
 ```tsx
-<Toggle
+<ToggleButton
+  iconOnly
   defaultPressed
   variant="outline"
   size="sm"
-  className="cursor-pointer px-0"
   aria-label="Pin inspector"
 >
   <Pin />
-</Toggle>
+</ToggleButton>
 ```
 
 Pair icon-only use with a tooltip.
@@ -45,8 +45,8 @@ Pair icon-only use with a tooltip.
 - 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`.
+- `variant`: `default`, `outline`, or `filled`.
+- `size`: `xs`, `sm`, `default`, or `lg`.
 - Supports native button accessibility props such as `aria-label` and `disabled`.
 - `toggleVariants` is exported and shared by `ToggleGroup`.
 
@@ -54,7 +54,7 @@ Pair icon-only use with a tooltip.
 
 - 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.
+- Give icon-only toggles an accessible name and a tooltip.
 - Keep toolbar toggles compact and aligned with adjacent controls.
 - Use a specific icon tied to the state.
 

package/src/components/ui/toolbar-controls.md

@@ -6,11 +6,14 @@ keeping app toolbars visually consistent.
 
 ```tsx
 <Toolbar position="top">
-  <ToolbarSidebarToggle
-    expanded={sidebarOpen}
-    onExpandedChange={setSidebarOpen}
-  />
-  <ToolbarBackButton onClick={goBack} />
+  <ToolbarControlGroup aria-label="Navigation">
+    <ToolbarSidebarToggle
+      expanded={sidebarOpen}
+      onExpandedChange={setSidebarOpen}
+    />
+    <ToolbarControlSeparator />
+    <ToolbarBackButton onClick={goBack} />
+  </ToolbarControlGroup>
   <ToolbarTitleField value={title} onChange={rename} />
   <ToolbarActions>
     <ToolbarControlGroup aria-label="History">
@@ -29,7 +32,7 @@ keeping app toolbars visually consistent.
       ]}
       onSelectItem={handleMoreAction}
     />
-    <ToolbarButton variant="default">Present</ToolbarButton>
+    <ToolbarButton variant="prominent">Present</ToolbarButton>
   </ToolbarActions>
 </Toolbar>
 ```
@@ -37,7 +40,7 @@ keeping app toolbars visually consistent.
 ## Components
 
 - `ToolbarButton` — text or mixed-content action. Defaults to 36px native
-  chrome; use `variant="default"` for the one primary action.
+  chrome; use `variant="prominent"` for the one primary action.
 - `ToolbarIconButton` — required accessible label and optional tooltip.
 - `ToolbarBackButton` — single chevron Back affordance for root-to-detail
   navigation.
@@ -46,13 +49,16 @@ keeping app toolbars visually consistent.
 - `ToolbarOverflowMenu` — an ellipsis button backed by Moldable's declarative
   menu API, including the native host menu when available.
 - `ToolbarControlGroup` — a shared surface for closely related actions such as
-  Undo/Redo. Children automatically become compact quiet controls.
+  Undo/Redo. It defaults to `size="xl"`, supports `size="medium"`, and makes
+  children compact quiet controls.
 - `ToolbarControlSeparator` — divider within a related action group.
 - `ToolbarTitleField` — an accessible, inline-editable contextual title.
 
 `ToolbarButton` and `ToolbarIconButton` accept `appearance="quiet"` when a
 standalone action should not have raised chrome. The default `chrome`
-appearance uses the `toolbar` Button variant and these semantic tokens:
+appearance uses the `toolbar` Button variant. `ToolbarControlGroup` also
+accepts `appearance="quiet"` when related controls should not share a raised
+surface. Raised controls use these semantic tokens:
 
 - `--toolbar-control-background`
 - `--toolbar-control-hover`
@@ -66,6 +72,8 @@ transparency.
 ## Composition rules
 
 - Keep the current document or view title leading and the primary action last.
+- Use fully rounded standalone controls and shared pill surfaces for related
+  controls. Avoid drawing a separate rounded rectangle around every icon.
 - Prefer icon-only secondary controls and a text-only primary action.
 - Put only genuinely related commands in `ToolbarControlGroup`.
 - Move low-frequency commands such as history, duplicate, export, and delete

package/src/components/ui/toolbar.md

@@ -12,9 +12,9 @@ embedded view.
     <ToolbarDescription>Local workspace</ToolbarDescription>
   </ToolbarContent>
   <ToolbarActions>
-    <Button size="icon-sm" aria-label="New note">
+    <ToolbarIconButton label="New note" tooltip>
       <Plus />
-    </Button>
+    </ToolbarIconButton>
   </ToolbarActions>
 </Toolbar>
 ```
@@ -28,10 +28,10 @@ when there is no useful view context; the remaining toolbar still provides a
 drag surface and a safe home for right-aligned actions.
 
 The `inset` prop defaults to `auto`. Use `none` for a top toolbar that is not
-window chrome, `windowControls` to force the standard control lane, or
-`windowControlsAndButton` when another leading control sits beside the native
-traffic lights. Set `draggable={false}` only for top toolbars that are nested
-inside app content.
+window chrome, `windowControls` to explicitly declare the standard control
+lane, or `windowControlsAndButton` when another leading control sits beside
+the native traffic lights. Set `draggable={false}` only for top toolbars that
+are nested inside app content.
 
 The default toolbar uses `material="regular"`. The `plain` and `panel` variants
 default to `material="none"`; pass a material explicitly only when the toolbar