@moldable-ai/ui 0.2.29 → 0.2.32

package/src/components/ui/breadcrumb.md

@@ -0,0 +1,52 @@
+# Breadcrumb
+
+## Purpose
+
+`Breadcrumb` shows the current location within a hierarchy and lets users
+return to ancestor levels. Use it for nested app content, not as a substitute
+for browser history or primary navigation.
+
+## Usage
+
+```tsx
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from '@moldable-ai/ui'
+
+;<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/projects">Projects</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Launch plan</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+## API
+
+- `Breadcrumb` renders a `nav` with `aria-label="breadcrumb"`.
+- `BreadcrumbList` and `BreadcrumbItem` render an `ol` and `li`.
+- `BreadcrumbLink` renders an anchor; `asChild` applies its behavior to a
+  caller-provided link component.
+- `BreadcrumbPage` marks the current page with `aria-current="page"` and
+  disabled link semantics.
+- `BreadcrumbSeparator` is hidden from assistive technology and uses a right
+  chevron unless children are provided.
+- `BreadcrumbEllipsis` renders a presentation-only overflow marker.
+
+## Quality bar
+
+- End with exactly one current page and do not make it navigable.
+- Represent omitted middle levels with `BreadcrumbEllipsis`; keep the root and
+  current location visible.
+- Keep labels concise and preserve their hierarchy on narrow layouts.
+- Do not add slash characters in text; use `BreadcrumbSeparator`.

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

@@ -0,0 +1,43 @@
+# ButtonGroup
+
+## Purpose
+
+`ButtonGroup` joins closely related controls into one compact visual group. Use
+it for adjacent actions or a control assembled from buttons, inputs, and select
+triggers.
+
+## Usage
+
+```tsx
+import { Button, ButtonGroup, ButtonGroupSeparator } from '@moldable-ai/ui'
+
+;<ButtonGroup aria-label="Text alignment">
+  <Button variant="outline">Left</Button>
+  <Button variant="outline">Center</Button>
+  <Button variant="outline">Right</Button>
+  <ButtonGroupSeparator />
+  <Button variant="outline">Justify</Button>
+</ButtonGroup>
+```
+
+## API
+
+- `ButtonGroup` accepts native `div` props and
+  `orientation="horizontal" | "vertical"`; visual orientation defaults to
+  `horizontal`. It renders `role="group"`.
+- Direct children share adjoining corners and borders. Focused children rise
+  above neighboring borders.
+- `ButtonGroupText` accepts native `div` props and `asChild`; use it for
+  non-interactive text or an icon beside the controls.
+- `ButtonGroupSeparator` accepts `Separator` props and defaults to
+  `orientation="vertical"`. Set it to `horizontal` inside a vertical group.
+- `buttonGroupVariants` is exported for composing the group layout.
+
+## Quality bar
+
+- Add an accessible label when the group’s purpose is not already named.
+- Keep every action independently focusable and labeled.
+- Use semantic button variants and shared controls so theme and density tokens
+  remain consistent.
+- Do not group unrelated actions merely to save space.
+- Do not use `ButtonGroupText` for an action.

package/src/components/ui/button.md

@@ -2,7 +2,9 @@
 
 ## Purpose
 
-`Button` starts an immediate action or, with `asChild`, gives button styling and behavior to another interactive element. Use it for commands such as save, run, refresh, connect, archive, and open.
+`Button` starts an immediate action or, with `asChild`, gives button styling to
+another interactive element. Use it for commands such as save, run, refresh,
+connect, archive, and open.
 
 Use a link for navigation. Use `Toggle` when the control represents an on/off view state, and `ToggleGroup` when the user chooses among a small set of modes.
 
@@ -31,7 +33,13 @@ import { RefreshCw } from 'lucide-react'
 </Button>
 ```
 
-Keep toolbar actions compact (`xs`, `sm`, `icon-xs`, or `icon-sm`). Reserve `default` or `lg` for the primary action in a form, setup state, or focused control dock. Set `loading` while that button's async action is in flight. The button blocks pointer and keyboard activation, exposes `aria-busy`, keeps its accessible label mounted, and centers a width-stable spinner.
+Keep ordinary pane-toolbar actions compact (`xs`, `sm`, `icon-xs`, or
+`icon-sm`). In an app-owned native titlebar, use the 36px controls provided by
+`ToolbarButton` and `ToolbarIconButton`. Reserve `default` or `lg` for the
+primary action in a form, setup state, or focused control dock. Set `loading`
+while that button's async action is in flight. The button blocks pointer and
+keyboard activation, exposes `aria-busy`, keeps its accessible label mounted,
+and centers a width-stable spinner.
 
 Use `loading` for the action that started the request. Disable the whole form only when editing during the request would be unsafe or would invalidate the submitted payload; do not disable unrelated controls merely to communicate progress.
 
@@ -45,8 +53,17 @@ For links that should look like buttons:
 
 ## API summary
 
-- `variant`: `default`, `destructive`, `outline`, `secondary`, `ghost`, or `link`. Defaults to `default`.
-- `size`: `default`, `xs`, `sm`, `lg`, `icon`, `icon-xs`, `icon-sm`, or `icon-lg`. Defaults to `default`.
+- `variant`: `default`, `prominent`, `bordered`, `borderless`, `tinted`,
+  `toolbar`, `destructive`, `destructive-tinted`, `outline`, `secondary`,
+  `ghost`, or `link`. Defaults to `default`; `default` and `prominent` share
+  the prominent recipe. `borderless` uses the neutral foreground color without
+  a border or fill, then dims slightly on hover and press. Prefer the
+  toolbar-control wrappers instead of applying `toolbar` directly.
+- `size`: `default`, `xs`, `sm`, `lg`, `xl`, `mini`, `small`, `medium`,
+  `large`, `icon`, `icon-xs`, `icon-sm`, `icon-lg`, or `icon-xl`. Defaults to
+  `default`.
+- `controlSize`: overrides the platform control-size token resolved from
+  `size`; accepts `mini`, `small`, `medium`, `large`, or `xl`.
 - `asChild`: renders a Radix `Slot` so the child owns the element and semantics.
 - `loading`: blocks activation, applies disabled behavior and `aria-busy`, and overlays the shared `Spinner` without unmounting or resizing the label. Defaults to `false`.
 - Accepts native button props, including `type`, `disabled`, `aria-*`, and event handlers.

package/src/components/ui/calendar.md

@@ -0,0 +1,42 @@
+# Calendar
+
+An always-visible `react-day-picker` calendar for single dates, ranges,
+multiple dates, and custom month layouts. Use `DatePicker` when the calendar
+should open from a compact date-only field.
+
+```tsx
+import { Calendar } from '@moldable-ai/ui'
+
+;<Calendar
+  aria-label="Choose a due date"
+  mode="single"
+  selected={date}
+  onSelect={setDate}
+  disabled={{ before: new Date() }}
+/>
+```
+
+## API
+
+- Accepts the current `DayPicker` props, including `mode`, `selected`,
+  `onSelect`, `month`, `locale`, `disabled`, and `showWeekNumber`.
+- `showOutsideDays` defaults to `true`.
+- `captionLayout` defaults to `label`.
+- `buttonVariant` sets the shared `Button` variant used by previous and next
+  month controls; it defaults to `ghost`.
+- `formatters` and `components` extend or replace the wrapper defaults. The
+  default month-dropdown formatter uses abbreviated month names.
+- `className` styles the root. Entries in `classNames` replace the
+  corresponding wrapper class entry.
+- `CalendarDayButton` is exported for advanced `DayPicker` composition; the
+  built-in calendar already installs it.
+
+## Keyboard and quality
+
+Day buttons use native button activation. Arrow keys move by day or week;
+Shift+Left/Right moves by month, Shift+Up/Down by year, Page Up/Down by month,
+Shift+Page Up/Down by year, and Home/End to the week boundary.
+
+Provide a visible label or accessible name, pass the intended locale, and keep
+disabled dates explainable outside the grid. Store a date-only selection
+without converting it through UTC unless the domain is truly time-based.

package/src/components/ui/card.md

@@ -0,0 +1,43 @@
+# Card
+
+`Card` groups related content on one bounded surface. Its optional anatomy
+keeps a title, description, trailing action, content, and footer aligned.
+
+```tsx
+import {
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@moldable-ai/ui'
+
+;<Card surface="raised">
+  <CardHeader>
+    <CardTitle>Project brief</CardTitle>
+    <CardDescription>Updated five minutes ago</CardDescription>
+    <CardAction>{/* compact action */}</CardAction>
+  </CardHeader>
+  <CardContent>{/* related content */}</CardContent>
+</Card>
+```
+
+## API
+
+- `Card` accepts native `div` props and `surface`: `default`, `raised`,
+  `recessed`, or `plain`. The default is `default`.
+- `default` uses the card fill, border, and shadow; `raised` uses the raised
+  surface; `recessed` uses the inset surface; `plain` provides structure
+  without chrome.
+- `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`,
+  and `CardFooter` accept native `div` props.
+- `CardProps` and `CardSurface` are exported.
+- Adding `border-b` to the header or `border-t` to the footer also enables
+  their matching separator spacing.
+
+Cards do not add region, heading, or button semantics. Use a real heading
+inside `CardTitle` when the title participates in the document outline, and
+keep actions as separate buttons or links. Do not make a whole card clickable
+by attaching button behavior to its `div`; use an explicit interactive element
+with a visible focus state.

package/src/components/ui/carousel.md

@@ -0,0 +1,47 @@
+# Carousel
+
+An Embla-backed sequence of peer slides with optional previous and next
+controls.
+
+```tsx
+import {
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+  CarouselNext,
+  CarouselPrevious,
+} from '@moldable-ai/ui'
+
+;<Carousel aria-label="Recent projects" className="mx-auto w-full max-w-lg">
+  <CarouselContent>
+    {projects.map((project) => (
+      <CarouselItem key={project.id}>{project.name}</CarouselItem>
+    ))}
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+</Carousel>
+```
+
+## API
+
+- `Carousel` accepts native `div` props plus `orientation`, `opts`, `plugins`,
+  and `setApi`. `orientation` defaults to `horizontal` and determines Embla's
+  axis, overriding `opts.axis`.
+- `setApi` receives the initialized `CarouselApi`, which is also exported.
+- `CarouselContent` owns the clipped viewport and flex track.
+- `CarouselItem` is one full-basis slide by default. Override its basis through
+  `className` to show multiple slides.
+- `CarouselPrevious` and `CarouselNext` accept shared `Button` props. They
+  default to `variant="outline"` and `size="icon"` and disable themselves at
+  their respective scroll boundary.
+
+The root exposes carousel region semantics and each item exposes slide group
+semantics; provide the root with `aria-label` or `aria-labelledby`. Left and
+Right Arrow scroll from anywhere inside the root in both orientations. Up and
+Down Arrow handling is not implemented, so prefer a horizontal carousel when
+keyboard direction must match its visual axis.
+
+Keep slide order stable, make important content available without hover, and
+avoid placing text-editing controls inside the carousel because captured
+Left/Right Arrow keys scroll the sequence.

package/src/components/ui/chart.md

@@ -0,0 +1,52 @@
+# Chart
+
+Theme-aware wrappers for Recharts. `ChartContainer` supplies responsive sizing,
+semantic chart styling, and config-driven labels, icons, and CSS color
+variables.
+
+```tsx
+import {
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+  type ChartConfig,
+} from '@moldable-ai/ui'
+import { Bar, BarChart, XAxis } from 'recharts'
+
+const config = {
+  completed: { label: 'Completed', color: 'var(--chart-1)' },
+} satisfies ChartConfig
+
+<ChartContainer config={config} className="h-64 w-full">
+  <BarChart accessibilityLayer data={data}>
+    <XAxis dataKey="day" />
+    <ChartTooltip content={<ChartTooltipContent />} />
+    <Bar dataKey="completed" fill="var(--color-completed)" />
+  </BarChart>
+</ChartContainer>
+```
+
+## API
+
+- `ChartConfig` maps each series key to an optional `label` and `icon`, plus
+  either one `color` or both `theme.light` and `theme.dark` colors.
+- `ChartContainer` accepts native `div` props, required `config`, one Recharts
+  chart child, and an optional chart-scoping `id`. That `id` seeds the
+  generated `data-chart` value; it is not forwarded as the element's HTML
+  `id`. The container wraps its child in `ResponsiveContainer`, so give it a
+  definite width and height.
+- Configured colors become `--color-{series}` variables scoped to that chart.
+- `ChartTooltip` and `ChartLegend` are the Recharts primitives.
+- `ChartTooltipContent` supports `indicator="dot" | "line" | "dashed"`,
+  `hideLabel`, `hideIndicator`, `nameKey`, and `labelKey`. It consumes the
+  Recharts `active`, `payload`, `label`, `labelFormatter`, `formatter`, and
+  `color` inputs supplied by `ChartTooltip`.
+- `ChartLegendContent` supports `hideIcon`, `nameKey`, `payload`, and
+  `verticalAlign`.
+- `ChartStyle` is exported for advanced composition; `ChartContainer` already
+  renders it.
+
+Enable Recharts' `accessibilityLayer` on the chart primitive. Use literal
+series labels, semantic color variables, and another cue when color carries
+meaning. For charts whose exact values matter, provide a nearby textual
+summary or table rather than relying on a pointer tooltip.

package/src/components/ui/checkbox.md

@@ -0,0 +1,36 @@
+# Checkbox
+
+A binary or mixed-state form control built on Radix Checkbox.
+
+```tsx
+import { Checkbox } from '@moldable-ai/ui'
+
+;<label className="flex items-center gap-2">
+  <Checkbox
+    checked={enabled}
+    onCheckedChange={(checked) => setEnabled(checked === true)}
+  />
+  Enable notifications
+</label>
+```
+
+## API and behavior
+
+- Accepts Radix Checkbox root props, including controlled `checked` and
+  `onCheckedChange`, uncontrolled `defaultChecked`, `disabled`, `required`,
+  `name`, `value`, and `form`.
+- `checked` and `defaultChecked` support `true`, `false`, or
+  `'indeterminate'`. Activating an indeterminate checkbox moves it to checked.
+- `controlSize` is optional and accepts `mini`, `small`, `medium`, `large`, or
+  `xl`; when omitted, theme defaults determine its dimensions.
+- The check and indeterminate dash indicators are included.
+
+Associate every checkbox with visible label text through a wrapping `label` or
+matching `htmlFor` and `id`. Space toggles the focused control; Enter is
+intentionally prevented. Radix exposes the mixed value as
+`aria-checked="mixed"` and preserves native form participation.
+
+Use a checkbox for an independently selectable choice. Use `RadioGroup` for
+one choice from a set and `Switch` for a settings-style state that takes effect
+immediately. Do not rely on the checkmark or accent color as the only
+explanation of the choice.

package/src/components/ui/collapsible.md

@@ -41,9 +41,8 @@ Radix. Space and Enter toggle it. The chevron is decorative.
 
 ## Motion
 
-Motion is brief and uses the shared reduced-motion behavior. Set
-`motion="none"` for content where movement would distract or when a parent owns
-the transition.
+The section content animates by default. Set `motion="none"` when movement
+would distract or when a parent owns the transition.
 
 ## Don't
 

package/src/components/ui/color-well.md

@@ -1,11 +1,21 @@
 # ColorWell
 
-Compact color selection or read-only swatch.
+Compact native color selection or a read-only swatch.
 
 ```tsx
 <ColorWell aria-label="Project color" value={color} onValueChange={setColor} />
 ```
 
-Use the browser color input as the renderer fallback. `readOnly` presents the
-value without implying interactivity. Never make color the only representation
-of a status or category.
+## API
+
+- `value` accepts a native color-input value (normally `#rrggbb`) or `null`; an
+  empty value displays a checkerboard swatch.
+- `onValueChange` receives the native color input value.
+- `size` is `sm`, `default`, or `lg` and defaults to `default`.
+- `readOnly` defaults to `false`. When true, the component renders a
+  non-interactive image role instead of an input.
+- The accessible label defaults to “Choose color”; provide a specific label in
+  app UI.
+
+The interactive form uses the browser's native color input. Never make color
+the only representation of a status or category.

package/src/components/ui/combobox.md

@@ -4,9 +4,9 @@ Searchable single- or multi-value selection for longer option sets.
 
 ## When to use
 
-Use `Combobox` when users need to filter options, create values, or manage
-multiple selections. Use `Select` for a short fixed list, `Command` for actions,
-and `Input` for unconstrained text.
+Use `Combobox` when users need to filter a longer option set or manage multiple
+selections. Use `Select` for a short fixed list, `Command` for actions, and
+`Input` for unconstrained text.
 
 ## Anatomy
 

package/src/components/ui/confirm-dialog.md

@@ -71,10 +71,11 @@ colors or custom dialog elevation.
 ## Keyboard and accessibility
 
 The component inherits alert-dialog semantics and focus containment. The
-dialog content receives initial focus; Enter activates the marked primary
-action when appropriate, and pending state prevents dismissal. Write a
-specific title and describe the consequence, not merely “Are you sure?”.
-Error copy is announced with `role="alert"`.
+dialog content receives initial focus. Command+Enter activates the confirm
+action on macOS and iOS-family runtimes; Control+Enter does so elsewhere.
+Plain Enter keeps the focused control's native behavior, and pending state
+prevents dismissal. Write a specific title and describe the consequence, not
+merely “Are you sure?”. Error copy is announced with `role="alert"`.
 
 ## Do
 

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

@@ -119,10 +119,11 @@ command palette as well as the context menu.
 
 ## Platform behavior
 
-With `items`, a user-initiated context-menu gesture automatically opens the
+With `items`, a `contextmenu` event such as a secondary click opens the
 host-native menu when `nativeMenu` is advertised. The pointer position is its
 anchor, `selectedId` is delivered to `onSelectItem`, and dismissal is a no-op.
-No portable menu is rendered while that native request is open.
+No portable menu is rendered while that native request is open. Radix's
+touch/pen long press opens the portable menu directly.
 
 When the service is not advertised, including web and iOS, the same items
 automatically render through the existing Radix anatomy. If advertised

package/src/components/ui/date-field.md

@@ -29,4 +29,9 @@ Values use the native timezone-free `YYYY-MM-DD` form. Use `value`/`onValueChang
 - Use a calendar popover only for workflows that require richer range, availability, or event selection.
 - Do not replace the native picker to imitate a desktop control.
 
-A host may later provide a native date capability. Keep that behind an explicit cross-client contract and preserve this web implementation as the portable fallback.
+`DateField` itself is renderer-owned and does not call the host. A call site
+that deliberately prefers the host picker can use `useHostDateTimePicker()` or
+`pickDateTimeWithHost('date', ...)`, then keep `DateField` as its portable
+fallback. A `status: 'fallback'` result does not open renderer UI for the
+caller. See
+[`host-date-time-picker.md`](../../lib/host-date-time-picker.md).

package/src/components/ui/date-picker.md

@@ -44,9 +44,12 @@ focus returns to the trigger.
 
 ## Platform behavior
 
-This component is portable and uses no host API. A future native date or time
-control must be introduced through a shared host capability with this
-renderer-owned control as its fallback.
+This component is renderer-owned and does not call the host. A call site that
+deliberately prefers the host picker can use `useHostDateTimePicker()` or
+`pickDateTimeWithHost('date', ...)`, then keep `DatePicker` as its portable
+fallback. A `status: 'fallback'` result does not open renderer UI for the
+caller. See
+[`host-date-time-picker.md`](../../lib/host-date-time-picker.md).
 
 ## Don't
 

package/src/components/ui/dialog.md

@@ -41,19 +41,21 @@ temporary control overlays where seeing the underlying context is useful.
 Use `DialogAction` for footer commands that need the standard async and keyboard
 contracts. Its `loading` prop forwards to `Button`, preventing duplicate
 activation while retaining the label width and accessible name. Keep the dialog
-controlled, show inline field errors, and close only after success. Disable the
-whole form only when edits during submission would be unsafe. Use
-`ConfirmDialog` when confirmation is the entire workflow.
+controlled when an async result must own closure, show inline field errors, and
+close only after success. Disable the whole form only when edits during
+submission would be unsafe. Use `ConfirmDialog` when confirmation is the entire
+workflow.
 
 Set `primary` on at most one `DialogAction` to opt into the default-action
-shortcut. Command+Enter activates it on macOS; Control+Enter does so on other
-platforms. The shortcut works from anywhere in the dialog unless a focused
-control consumes the key event with `preventDefault()`, or the primary action is
-loading or disabled. Plain Enter keeps the focused control's native behavior.
-Use `Kbd` to show the shortcut when it improves discovery; render the
-platform-appropriate modifier in app code.
+shortcut. Command+Enter activates it on macOS and iOS-family runtimes;
+Control+Enter does so elsewhere. The shortcut works from anywhere in the dialog
+unless a focused control consumes the key event with `preventDefault()`, or the
+primary action is loading or disabled. Plain Enter keeps the focused control's
+native behavior. Use `Kbd` to show the shortcut when it improves discovery;
+render the platform-appropriate modifier in app code.
 
 Every dialog needs a `DialogTitle`. Add `DialogDescription` when the outcome or
-scope is not obvious. Escape, outside dismissal, initial focus, and focus return
-come from the Radix primitive; do not replace them with manual document event
-handlers.
+scope is not obvious. `DialogContent` focuses its own container on open by
+default; pass `onOpenAutoFocus` for a deliberate alternative. Escape, outside
+dismissal, and focus return come from the Radix primitive; do not replace them
+with manual document event handlers.

package/src/components/ui/drawer.md

@@ -0,0 +1,58 @@
+# Drawer
+
+## Purpose
+
+`Drawer` presents a modal surface that enters from a screen edge and can be
+dismissed by dragging, pressing Escape, or using a close action. It wraps Vaul
+and defaults to the bottom edge.
+
+## Usage
+
+```tsx
+import {
+  Button,
+  Drawer,
+  DrawerClose,
+  DrawerContent,
+  DrawerDescription,
+  DrawerFooter,
+  DrawerHeader,
+  DrawerTitle,
+  DrawerTrigger,
+} from '@moldable-ai/ui'
+
+;<Drawer>
+  <DrawerTrigger asChild>
+    <Button>Open upload queue</Button>
+  </DrawerTrigger>
+  <DrawerContent>
+    <DrawerHeader>
+      <DrawerTitle>Upload queue</DrawerTitle>
+      <DrawerDescription>Two files are ready to sync.</DrawerDescription>
+    </DrawerHeader>
+    <DrawerFooter>
+      <Button>Upload all</Button>
+      <DrawerClose asChild>
+        <Button variant="outline">Cancel</Button>
+      </DrawerClose>
+    </DrawerFooter>
+  </DrawerContent>
+</Drawer>
+```
+
+`Drawer` accepts the Vaul root props, including controlled `open` and
+`onOpenChange`, `direction="top" | "bottom" | "left" | "right"`, snap points,
+and dismissal options. `DrawerContent` supplies the portal and overlay. Bottom
+drawers also show the built-in drag indicator.
+
+## Quality bar
+
+- Always include `DrawerTitle`; add `DrawerDescription` when the title does not
+  fully explain the task.
+- Keep the primary action and an explicit close action in `DrawerFooter`.
+- Use `asChild` when a shared button should be the trigger or close control.
+- Keep long drawer bodies independently scrollable and preserve focus
+  management from the primitive.
+- Use `Dialog` for a centered decision and `Sheet` for a persistent side panel.
+- Do not disable outside-click or Escape dismissal without another obvious way
+  to close the drawer.

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

@@ -4,7 +4,8 @@
 
 `DropdownMenu` presents a compact list of commands from a visible trigger. Use
 it for overflow actions, view commands, and small command groups. Its
-declarative item API automatically adopts the host-native menu when available.
+declarative item API uses the portable menu by default and can opt into the
+host-native menu when needed.
 
 Use `Select` for a form value, `Combobox` for searchable selection,
 `ContextMenu` for commands attached to the pointer target, and `Popover` when
@@ -91,9 +92,9 @@ shortcuts, and submenus are available when the command set needs structure.
 
 ## API summary
 
-- `DropdownMenu` supports `items?: MenuItems[]`,
-  `onSelectItem?: (id: string) => void`, `open`, `defaultOpen`,
-  `onOpenChange`, `dir`, and `modal`.
+- `DropdownMenu` supports `items?: MenuItems[]`, `nativeMenu?: boolean`,
+  `onSelectItem?: (id: string) => void`, `open`, `defaultOpen`, `onOpenChange`,
+  `dir`, and `modal`.
 - A `MenuItems` value supports `id`, `kind`, `label`, portable `icon`, reserved
   `sfSymbol`, `enabled`, `checked`, `shortcut`, `destructive`, and `submenu`.
 - Do not provide `DropdownMenuContent` together with `items`. In development
@@ -128,16 +129,17 @@ menu item; use `Popover` or `Dialog`.
 
 ## Platform behavior
 
-With `items`, pointer and keyboard trigger activation automatically opens the
-host-native menu when `nativeMenu` is advertised. The trigger rectangle is its
-anchor, `selectedId` is delivered to `onSelectItem`, and dismissal is a no-op.
-No portable menu is rendered while that native request is open.
-
-Without the advertisement, including web and iOS, the same items automatically
-render through the existing Radix anatomy. A stale advertisement that returns
-fallback opens the portable menu as well. Icons and destructive styling are
-portable in v1; `sfSymbol` is reserved and is not posted to or rendered by the
-native service.
+With `items`, pointer and keyboard trigger activation opens the portable Radix
+menu by default, including when the host advertises `nativeMenu`.
+
+Set `nativeMenu` explicitly on `DropdownMenu` to opt into the host-native menu.
+The trigger rectangle is its anchor, `selectedId` is delivered to
+`onSelectItem`, and dismissal is a no-op. No portable menu is rendered while
+that native request is open. Without the host advertisement, including web and
+iOS, the same items render through the existing Radix anatomy. A stale
+advertisement that returns fallback opens the portable menu as well. Icons and
+destructive styling are portable in v1; `sfSymbol` is reserved and is not
+posted to or rendered by the native service.
 
 Shortcuts are display metadata only. They do not register keyboard handlers;
 keep command execution keyed by `onSelectItem`. See

package/src/components/ui/error-boundary-view.md

@@ -25,7 +25,7 @@ nested cards.
 ## Usage
 
 ```tsx
-import { ErrorBoundaryView } from '@moldable-ai/ui'
+import { Button, ErrorBoundaryView } from '@moldable-ai/ui'
 
 function PaneError() {
   return (

package/src/components/ui/field.md

@@ -58,7 +58,8 @@ Use `orientation="horizontal"` for compact checkbox/radio rows and `orientation=
 - Give every control a visible label or an accessible name.
 - Connect labels and descriptions with `htmlFor`, `id`, and `aria-describedby`.
 - Set both `data-invalid` on `Field` and `aria-invalid` on the control.
-- Use real `disabled` state and reflect it on the field group when styling needs it.
+- Use real `disabled` state and set `data-disabled="true"` on `Field` when its
+  label or title should also appear disabled.
 - Place validation directly after the affected control.
 - Group related checkbox or radio controls in `FieldSet` with `FieldLegend`.