@moldable-ai/ui 0.2.29 → 0.2.32

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,30 +32,37 @@ keeping app toolbars visually consistent.
       ]}
       onSelectItem={handleMoreAction}
     />
-    <ToolbarButton variant="default">Present</ToolbarButton>
+    <ToolbarButton variant="prominent">Present</ToolbarButton>
   </ToolbarActions>
 </Toolbar>
 ```
 
 ## Components
 
-- `ToolbarButton` — text or mixed-content action. Defaults to 36px native
-  chrome; use `variant="default"` for the one primary action.
+- `ToolbarButton` — text or mixed-content action. Standalone chrome is a real
+  adaptive material surface: `material="regular"` by default and
+  `material="thick"` for `variant="prominent"`. Set `material="none"` or
+  `appearance="quiet"` to remove it.
 - `ToolbarIconButton` — required accessible label and optional tooltip.
 - `ToolbarBackButton` — single chevron Back affordance for root-to-detail
   navigation.
 - `ToolbarSidebarToggle` — controlled sidebar visibility button with accurate
   pressed state and dynamic label.
 - `ToolbarOverflowMenu` — an ellipsis button backed by Moldable's declarative
-  menu API, including the native host menu when available.
+  portable menu API. Set `nativeMenu` to opt into the native host menu.
 - `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:
+standalone action should not have raised chrome. `ToolbarButton` uses the
+shared adaptive `Material` layer; `ToolbarIconButton` uses the compact toolbar
+control treatment. `ToolbarControlGroup` also accepts `appearance="quiet"`
+when related controls should not share a raised surface. Grouped buttons do
+not add a nested material layer. Raised compact controls use these semantic
+tokens:
 
 - `--toolbar-control-background`
 - `--toolbar-control-hover`
@@ -66,6 +76,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