@moldable-ai/ui 0.2.29 → 0.2.32

package/src/components/ui/form.md

@@ -0,0 +1,71 @@
+# Form
+
+## Purpose
+
+The form adapter connects React Hook Form state to labels, controls,
+descriptions, and validation messages. `Form` is `FormProvider`; the native
+`form` element remains part of the composition.
+
+## Usage
+
+```tsx
+import { useForm } from 'react-hook-form'
+import {
+  Button,
+  Form,
+  FormControl,
+  FormDescription,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+  Input,
+} from '@moldable-ai/ui'
+
+type Values = { project: string }
+
+function ProjectForm() {
+  const form = useForm<Values>({ defaultValues: { project: '' } })
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(saveProject)}>
+        <FormField
+          control={form.control}
+          name="project"
+          rules={{ required: 'Enter a project name.' }}
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Project name</FormLabel>
+              <FormControl>
+                <Input {...field} />
+              </FormControl>
+              <FormDescription>Shown in the app titlebar.</FormDescription>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <Button type="submit">Save</Button>
+      </form>
+    </Form>
+  )
+}
+```
+
+`FormField` forwards React Hook Form `Controller` props. Within its
+`FormItem`, `FormLabel` targets the slotted `FormControl`; the control receives
+`id`, `aria-invalid`, and description/message references. `FormMessage` shows
+the current field error message, falls back to its children, and renders
+nothing when both are absent. `useFormField` exposes the generated IDs and
+field state to custom parts.
+
+## Quality bar
+
+- Put `FormControl`, `FormLabel`, `FormDescription`, and `FormMessage` inside
+  the same `FormField` and `FormItem`.
+- Give `FormControl` one interactive child that can accept the injected
+  accessibility props.
+- Keep validation messages specific and place them beside the affected field.
+- Use a native `form` with `onSubmit`; `Form` alone does not submit anything.
+- Prefer the simpler `Field` primitives when React Hook Form state is not
+  needed.

package/src/components/ui/grid.md

@@ -61,9 +61,10 @@ Prefer changing this value at deliberate window breakpoints. A smaller window sh
 - Home and End move to the first and last available tile in the current row.
 - Control/Command + Home and End move to the first and last available tile in
   the entire grid.
-- Space changes selection.
-- Enter changes selection and invokes `onAction`.
-- A single pointer click changes selection. A double click invokes `onAction`.
+- Space changes selection when selection is enabled.
+- Enter changes selection when enabled and invokes `onAction`.
+- A single pointer click changes selection when selection is enabled. A double
+  click invokes `onAction`.
 - Disabled tiles are skipped.
 - Buttons and links inside a tile preserve their own pointer behavior.
 - When the grid first mounts, the first selected, enabled tile receives the

package/src/components/ui/icon-button.md

@@ -22,7 +22,10 @@ import { IconButton } from '@moldable-ai/ui'
 </IconButton>
 ```
 
-`size` is `xs`, `sm`, `default`, or `lg`. `shape` is `rounded` or `circle`. `loading` disables the control, exposes `aria-busy`, and replaces the icon with a progress indicator. `tooltip` may be `true` to reuse the label as a native hint or a specific string.
+`size` is `xs`, `sm`, `default`, `lg`, or `xl`. `shape` is `rounded` or
+`circle`. `loading` disables the control, exposes `aria-busy`, and replaces the
+icon with a progress indicator. `tooltip` may be `true` to reuse the label as
+a native hint or a specific string.
 
 ## Quality bar
 

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

@@ -0,0 +1,49 @@
+# Input Group
+
+## Purpose
+
+`InputGroup` combines one text control with inline or stacked context and
+actions inside a single bordered surface.
+
+## Usage
+
+```tsx
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+  InputGroupText,
+} from '@moldable-ai/ui'
+
+;<InputGroup>
+  <InputGroupAddon>
+    <InputGroupText>https://</InputGroupText>
+  </InputGroupAddon>
+  <InputGroupInput aria-label="Workspace address" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupButton aria-label="Copy address">Copy</InputGroupButton>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+Use `InputGroupInput` for a native input or `InputGroupTextarea` for multiline
+text. `InputGroupAddon` defaults to `inline-start` and also supports
+`inline-end`, `block-start`, and `block-end`. Clicking a non-button inline
+addon focuses the contained input. `InputGroupButton` defaults to
+`type="button"`, `variant="ghost"`, and `size="xs"`; its sizes are `xs`, `sm`,
+`icon-xs`, and `icon-sm`.
+
+## Quality bar
+
+- Label the actual input or textarea; the group and its adornments do not
+  provide its accessible name.
+- Mark decorative icons `aria-hidden` and give icon-only buttons an
+  `aria-label`.
+- Put interactive controls in `InputGroupButton`, not in a clickable addon.
+- Set `aria-invalid` on the input or textarea so the group shows its error
+  state.
+- When disabling the control, add `data-disabled="true"` to `InputGroup` if
+  its addons should also appear disabled.
+- Keep addons short. Use `block-start` or `block-end` for context that cannot
+  fit inline.

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

@@ -0,0 +1,56 @@
+# Input OTP
+
+## Purpose
+
+`InputOTP` presents a one-time code as visual slots while retaining one
+keyboard- and paste-friendly input through the `input-otp` primitive.
+
+## Usage
+
+```tsx
+import {
+  InputOTP,
+  InputOTPGroup,
+  InputOTPSeparator,
+  InputOTPSlot,
+} from '@moldable-ai/ui'
+
+;<InputOTP
+  aria-label="Verification code"
+  maxLength={6}
+  value={code}
+  onChange={setCode}
+>
+  <InputOTPGroup>
+    {[0, 1, 2].map((index) => (
+      <InputOTPSlot key={index} index={index} />
+    ))}
+  </InputOTPGroup>
+  <InputOTPSeparator />
+  <InputOTPGroup>
+    {[3, 4, 5].map((index) => (
+      <InputOTPSlot key={index} index={index} />
+    ))}
+  </InputOTPGroup>
+</InputOTP>
+```
+
+`maxLength` defines the code length and the rendered slot indexes must match
+it. Native input props and `input-otp` options such as `pattern`,
+`pasteTransformer`, `onComplete`, and `pushPasswordManagerStrategy` pass
+through. `containerClassName` styles the visible slot container; `className`
+targets the underlying input. `InputOTPSeparator` renders a separator role
+with the shared minus icon.
+
+## Quality bar
+
+- Give the root a visible label or an accessible name.
+- Match every `InputOTPSlot` index to a valid position below `maxLength`.
+- Use `pattern` when the code format is restricted; do not reject valid pasted
+  codes silently.
+- Let users paste and use password managers or system code autofill; add an
+  appropriate `autoComplete` value for the workflow.
+- Report expiration, resend status, and server errors outside the slots in
+  text, not by color alone.
+- Do not submit solely because the last character was entered unless the
+  result is safe, reversible, and clearly communicated.

package/src/components/ui/input.md

@@ -0,0 +1,40 @@
+# Input
+
+## Purpose
+
+`Input` is the shared styled native input. It preserves native input types,
+editing behavior, constraints, and form participation while applying semantic
+control tokens.
+
+## Usage
+
+```tsx
+import { Input, Label } from '@moldable-ai/ui'
+
+;<div className="grid gap-2">
+  <Label htmlFor="workspace-name">Workspace name</Label>
+  <Input
+    id="workspace-name"
+    name="workspaceName"
+    autoComplete="organization"
+    required
+  />
+</div>
+```
+
+All native input props pass through. `controlSize` accepts `mini`, `small`,
+`medium`, `large`, or `xl`; when omitted, the input inherits the active theme
+size. File inputs receive matching typography and file-button treatment.
+
+## Quality bar
+
+- Associate every input with a visible label or an accessible name.
+- Choose the correct native `type`, `name`, `autoComplete`, `inputMode`, and
+  constraints for the data.
+- Set `aria-invalid` when invalid and connect supporting or error text with
+  `aria-describedby`.
+- Use `disabled` only for unavailable controls; use `readOnly` for values that
+  should remain selectable.
+- Keep placeholder text as a short hint, never as the only label.
+- Use `Textarea`, `SearchField`, `DateField`, or `InputGroup` when their
+  behavior matches the task more closely.

package/src/components/ui/inspector.md

@@ -1,11 +1,51 @@
 # Inspector
 
-Secondary property controls for the current selection.
+## Purpose
 
-Compose `Inspector`, `InspectorHeader`, `InspectorContent`,
-`InspectorSection`, and aligned `InspectorRow` pairs. Controls should usually
-use compact sizes.
+The inspector primitives compose a secondary property pane for the current
+selection. The root is an `aside`; its header stays fixed while
+`InspectorContent` scrolls and includes bottom chat clearance.
 
-The inspector must remain subordinate to the primary pane. Collapse it when
-width is constrained, group related properties, and avoid placing primary
-workflow actions inside it.
+## Usage
+
+```tsx
+import {
+  Input,
+  Inspector,
+  InspectorContent,
+  InspectorHeader,
+  InspectorLabel,
+  InspectorRow,
+  InspectorSection,
+  InspectorValue,
+} from '@moldable-ai/ui'
+
+;<Inspector>
+  <InspectorHeader>Inspector</InspectorHeader>
+  <InspectorContent>
+    <InspectorSection title="Appearance">
+      <InspectorRow>
+        <InspectorLabel htmlFor="document-title">Title</InspectorLabel>
+        <InspectorValue>
+          <Input id="document-title" controlSize="small" />
+        </InspectorValue>
+      </InspectorRow>
+    </InspectorSection>
+  </InspectorContent>
+</Inspector>
+```
+
+`InspectorSection` accepts optional `title` and `actions`; it omits its header
+when neither is present. `InspectorRow` aligns a label and value in two
+columns. `InspectorLabel` renders a compact native label, and
+`InspectorValue` contains the control or read-only value.
+
+## Quality bar
+
+- Keep the inspector subordinate to the primary pane and collapse it when
+  width is constrained.
+- Group related properties into short sections and use section actions only
+  for local operations.
+- Connect each `InspectorLabel` to its control with `htmlFor` and `id`.
+- Use compact control sizes and keep unpredictable values truncatable.
+- Keep primary workflow actions out of the inspector.

package/src/components/ui/item.md

@@ -23,7 +23,7 @@ import {
 } from '@moldable-ai/ui'
 
 ;<ItemGroup>
-  <Item size="sm">
+  <Item role="listitem" size="sm">
     <ItemMedia variant="icon">
       <FileText />
     </ItemMedia>
@@ -53,8 +53,10 @@ Use `asChild` when the whole item is a link or another interactive primitive. Av
 
 ## API summary
 
-- `ItemGroup`: `role="list"` container.
-- `Item`: `variant="default"`, `"outline"`, or `"muted"`; `size="default"` or `"sm"`; optional `asChild`.
+- `ItemGroup`: `role="list"` container. Give each direct `Item`
+  `role="listitem"`.
+- `Item`: `variant="default"`, `"outline"`, or `"muted"`;
+  `size="default"` or `"sm"`; optional `asChild`.
 - `ItemMedia`: `variant="default"`, `"icon"`, or `"image"`.
 - `ItemContent`: flexible title/description column.
 - `ItemTitle`, `ItemDescription`: primary and secondary text.

package/src/components/ui/kbd.md

@@ -0,0 +1,30 @@
+# Kbd
+
+## Purpose
+
+`Kbd` displays a keyboard key or shortcut hint. `KbdGroup` lays out several
+keys as one shortcut. These components are visual labels only; they do not
+register keyboard handlers.
+
+## Usage
+
+```tsx
+import { Kbd, KbdGroup } from '@moldable-ai/ui'
+
+;<KbdGroup aria-label="Command K">
+  <Kbd>⌘</Kbd>
+  <Kbd>K</Kbd>
+</KbdGroup>
+```
+
+Both components accept native `<kbd>` props and `className`. `Kbd` applies the
+keycap treatment and sizes unclassified SVG children; `KbdGroup` supplies only
+an inline flex layout.
+
+## Guidance
+
+- Show shortcuts only when the command really supports them.
+- Keep key names brief and use the same notation throughout the app.
+- Add an accessible label when modifier glyphs may not be announced clearly.
+- Keep `Kbd` non-interactive; place click behavior on a real button or link.
+- Do not use shortcut hints as the only way to discover an action.

package/src/components/ui/label.md

@@ -0,0 +1,29 @@
+# Label
+
+## Purpose
+
+`Label` gives a form control a visible, clickable name. It wraps the Radix
+label primitive and accepts its props.
+
+## Usage
+
+```tsx
+import { Input, Label } from '@moldable-ai/ui'
+
+;<div className="space-y-2">
+  <Label htmlFor="project-name">Project name</Label>
+  <Input id="project-name" name="projectName" />
+</div>
+```
+
+## Guidance
+
+- Pair `htmlFor` with a unique control `id`, or nest the control when that is
+  the clearer native relationship.
+- Use a short noun phrase and keep instructions or validation outside the
+  label.
+- Keep a visible label for text fields; a placeholder is not a replacement.
+- Mark optional or required state consistently and expose it to assistive
+  technology on the control.
+- The built-in styles respond to disabled peer or group state; set the actual
+  control's `disabled` attribute as well.

package/src/components/ui/list.md

@@ -81,8 +81,8 @@ const [selected, setSelected] = useState<ReadonlySet<string>>(
 
 - Arrow Up/Down moves through a vertical list; Arrow Left/Right moves through a horizontal list.
 - Home and End move to the first and last available item.
-- Space changes selection.
-- Enter changes selection and invokes `onAction`.
+- Space changes selection when selection is enabled.
+- Enter changes selection when enabled and invokes `onAction`.
 - A single pointer click changes selection. A double click invokes `onAction`.
 - Disabled items are skipped during keyboard navigation and cannot be selected or activated.
 - Interactive descendants such as buttons and links keep their own pointer behavior. They do not select or activate the containing item.

package/src/components/ui/material.md

@@ -1,13 +1,14 @@
 # Material
 
-Adaptive material for navigation and control chrome.
+`Material` provides an adaptive sampled layer for navigation and control
+chrome. `MaterialGroup` gives a related control cluster one shared layer.
 
 ```tsx
-<Material asChild variant="regular" elevation="none">
+<Material asChild variant="medium" elevation="none">
   <Toolbar>{/* context and actions */}</Toolbar>
 </Material>
 
-<MaterialGroup variant="regular" shape="capsule" spacing="compact">
+<MaterialGroup variant="thin" shape="capsule" spacing="compact">
   <IconButton label="Previous" variant="ghost">
     <ChevronLeft />
   </IconButton>
@@ -19,15 +20,25 @@ Adaptive material for navigation and control chrome.
 
 ## Variants
 
-- `regular` provides a frosted, legible control or navigation layer.
-- `clear` is less frosted and is only for compact controls floating over
-  photos, maps, video, or another richly colored canvas.
+- Standard thicknesses are `ultra-thick`, `thick`, `medium`, `thin`, and
+  `ultra-thin`, ordered from most filled to most transparent. They all use the
+  standard material blur; thickness controls translucency.
+- `regular` is a compatibility alias for `medium` and remains the default.
+- `clear` is a compatibility alias for `ultra-thin`.
 
-Both variants start with an opaque fallback. Backdrop sampling is enabled only
-when the renderer supports it. Reduced transparency and forced colors keep the
-fallback opaque.
+Every variant starts with an opaque fallback. Backdrop sampling is enabled only
+when the renderer supports it.
 
-## Grouping
+## Shape, elevation, and grouping
+
+- `shape` is `rounded`, `capsule`, or `circle`; it defaults to `rounded`.
+- `elevation` is `none`, `panel`, or `overlay`; it defaults to `none` and
+  controls shadow independently of thickness.
+- `interactive` adds hover and press feedback when the material surface itself
+  is the control.
+- `asChild` applies `Material` to its single child through a Radix slot.
+- `MaterialGroup` supports `spacing="compact" | "default" | "comfortable"`
+  and defaults to `default`.
 
 `MaterialGroup` creates one sampled layer for a related cluster. Put ordinary
 ghost or transparent controls inside it. Do not wrap each child in another
@@ -42,8 +53,10 @@ do not read as one group.
   temporary control layers.
 - Keep documents, calendars, tables, forms, cards, sheets, and primary content
   canvases opaque.
-- Prefer `regular`. A `clear` surface needs stable contrast across every part
-  of the media behind it.
+- Prefer a named standard thickness when the hierarchy is known. Use the
+  compatibility aliases only where their existing semantics are intentional.
+- Thin and ultra-thin surfaces need stable contrast across every part of the
+  content behind them.
 - Use `interactive` only when the material surface itself is the control.
 - Do not animate blur or saturation. Shared motion tokens provide restrained
   press feedback and remove it when reduced motion is requested.

package/src/components/ui/menu-items.md

@@ -0,0 +1,62 @@
+# Menu Items
+
+## Purpose
+
+`menu-items.tsx` is the internal adapter shared by `DropdownMenu` and
+`ContextMenu` when their declarative `items` API is used. It coordinates the
+host-native request and portable fallback, formats shortcut labels, renders
+portable row contents, and removes conflicting authored content.
+
+App code should use `DropdownMenu` or `ContextMenu`, not import these helpers
+directly.
+
+## Declarative usage
+
+```tsx
+import { Button, DropdownMenu, DropdownMenuTrigger } from '@moldable-ai/ui'
+
+;<DropdownMenu
+  items={[
+    {
+      id: 'rename',
+      label: 'Rename',
+      shortcut: { key: 'r', modifiers: ['cmd'] },
+    },
+    { id: 'divider', kind: 'separator' },
+    { id: 'delete', label: 'Move to trash', destructive: true },
+  ]}
+  onSelectItem={(id) => runCommand(id)}
+>
+  <DropdownMenuTrigger asChild>
+    <Button
+      type="button"
+      variant="outline"
+      size="sm"
+      className="cursor-pointer"
+    >
+      Actions
+    </Button>
+  </DropdownMenuTrigger>
+</DropdownMenu>
+```
+
+## Internal contract
+
+- `useDeclarativeMenuState` supports controlled or uncontrolled portable-open
+  state. While a native request is active, `nativeOpen` is true and
+  `portableOpen` is forced false.
+- Native requests are gated by an explicit component policy. `DropdownMenu`
+  exposes that policy as its opt-in `nativeMenu` prop.
+- A completed native request passes `selectedId` to `onSelectItem`.
+  Cancellation does nothing. A fallback result or request failure opens the
+  portable menu unless the caller supplies its own `onFallback`.
+- `formatMenuShortcut` renders modifiers in array order as `⌘`, `⇧`, `⌥`, and
+  `⌃`, then uppercases a one-character key. It is display metadata only.
+- `MenuItemContents` renders an optional Lucide icon, the label, and a `Kbd`
+  shortcut. Separators are handled by the owning menu.
+- Content detection and removal recurse through fragments. When declarative
+  items and authored content are both provided, the owning menu reports the
+  conflict in development and declarative items win.
+
+Keep item IDs stable and labels concise. Do not execute a command from shortcut
+metadata, and do not mix declarative items with authored menu content.

package/src/components/ui/menubar.md

@@ -0,0 +1,58 @@
+# Menubar
+
+## Purpose
+
+`Menubar` presents a persistent row of related command menus, such as File,
+Edit, and View. Use it for command families that benefit from repeated
+keyboard access; use `DropdownMenu` for a single contextual action menu.
+
+## Usage
+
+```tsx
+import {
+  Menubar,
+  MenubarContent,
+  MenubarItem,
+  MenubarMenu,
+  MenubarShortcut,
+  MenubarTrigger,
+} from '@moldable-ai/ui'
+
+;<Menubar>
+  <MenubarMenu>
+    <MenubarTrigger className="cursor-pointer">File</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem onSelect={createDocument}>
+        New document
+        <MenubarShortcut>⌘N</MenubarShortcut>
+      </MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+</Menubar>
+```
+
+## API summary
+
+- `Menubar`, `MenubarMenu`, and `MenubarTrigger` form the required shell.
+- `MenubarContent` is portalled and defaults to `align="start"`,
+  `alignOffset={-4}`, and `sideOffset={8}`.
+- `MenubarItem` supports `inset` and
+  `variant="default" | "destructive"`.
+- Checkbox items, radio groups/items, groups, labels, separators, shortcuts,
+  and submenus are exported for structured command sets.
+- `MenubarLabel` and `MenubarSubTrigger` support `inset`.
+- Components otherwise accept the corresponding Radix menubar props.
+
+## Guidance
+
+- Keep top-level trigger labels short and conventional.
+- Use checkbox and radio items for menu-owned state, and `onSelect` for
+  commands.
+- Put destructive commands last or in a separated group; do not rely on color
+  alone to communicate risk.
+- `MenubarShortcut` is display text only and does not register a handler.
+- Radix supplies menu roles, focus movement, typeahead, Escape dismissal, and
+  submenu navigation. Preserve those semantics and give icon-only content an
+  accessible name.
+- Keep submenus shallow and use `Popover` or `Dialog` for arbitrary form
+  controls.

package/src/components/ui/message-scroller-primitive.md

@@ -0,0 +1,70 @@
+# Message Scroller Primitive
+
+## Purpose
+
+`message-scroller-primitive.tsx` is the unstyled React wiring for the
+in-repository transcript controller and scroll-ownership policy. The public
+`MessageScroller*` components wrap this module with layout, button, and
+animation styles; app code should use those wrappers.
+
+## Anatomy
+
+```tsx
+<MessageScroller.Provider autoScroll>
+  <MessageScroller.Root>
+    <MessageScroller.Viewport>
+      <MessageScroller.Content>
+        <MessageScroller.Item messageId="turn-1" scrollAnchor>
+          {/* message */}
+        </MessageScroller.Item>
+      </MessageScroller.Content>
+    </MessageScroller.Viewport>
+    <MessageScroller.Button direction="end" />
+  </MessageScroller.Root>
+</MessageScroller.Provider>
+```
+
+This local-only example uses the `MessageScroller` object exported by the
+primitive module. `Provider` must wrap every root, item, button, and hook.
+
+## Primitive contract
+
+- Provider defaults: `autoScroll={false}`, `defaultScrollPosition="end"`,
+  `scrollEdgeThreshold={8}`, `scrollPreviousItemPeek={64}`, and
+  `scrollMargin={0}`. Changing `defaultScrollPosition` resets the one-time
+  initial-position decision for the next content mutation.
+- `Viewport` forwards scroll, wheel, touch, and scroll-key events after
+  notifying the controller. It defaults to a focusable messages region and
+  observes viewport size changes.
+- `Content` defaults to an additions-only live log, observes direct child
+  mutations and size changes, and appends a hidden internal spacer.
+- `Item` registers `messageId` elements and writes anchor data used for
+  initial placement, new-turn anchoring, targeted scrolling, and visibility.
+- `Button` supports `direction="start" | "end"`, `behavior`, and a `render`
+  element or render function. Defaults are end, smooth, and `type="button"`.
+  Inactive buttons are inert with `tabIndex={-1}`; preventing the click event's
+  default also prevents the scroll command.
+
+## Controller and policy behavior
+
+The controller is the sole owner of programmatic transcript movement. The
+policy distinguishes following the end, free reading, an anchored turn, and a
+settling commanded jump. Wheel, touch, scroll-key, scrollbar, or other motion
+away from a declared target gives control to the reader immediately.
+
+It also:
+
+- keeps a followed end pinned during growth;
+- reanchors a streaming turn after resize;
+- preserves the first visible row when older items are prepended;
+- restores a stable visible leaf when content above collapses;
+- grows the internal spacer so late items can reach the requested alignment;
+- exposes edge state as `data-scrollable` and active programmatic movement as
+  `data-autoscrolling` on root and viewport;
+- observes visibility only while `useMessageScrollerVisibility` has
+  subscribers.
+
+For finer reading-position stability inside a complex item, mark stable
+descendants with `data-message-scroll-anchor`. Do not manipulate the
+controller, spacer, data attributes, or scroll position from a competing
+effect; extend the wrapper API when new behavior is required.