@moldable-ai/ui 0.2.29 → 0.2.31

package/src/components/ui/accordion.md

@@ -0,0 +1,46 @@
+# Accordion
+
+## Purpose
+
+`Accordion` organizes related sections into independently expandable items. Use
+it when several peer sections should share one disclosure pattern; use
+`Collapsible` for a single disclosed region.
+
+## Usage
+
+```tsx
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from '@moldable-ai/ui'
+
+;<Accordion type="single" collapsible>
+  <AccordionItem value="storage">
+    <AccordionTrigger>Storage</AccordionTrigger>
+    <AccordionContent>
+      Files remain in the current Moldable workspace.
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+## API
+
+- `Accordion` exposes the Radix root props, including `type="single"` or
+  `type="multiple"`, controlled state, and orientation.
+- `AccordionItem` requires the Radix item `value` and adds a dividing border.
+- `AccordionTrigger` renders a full-width trigger with a state-aware chevron.
+- `AccordionContent` provides the open and close animation. Its `className`
+  styles the inner content wrapper; remaining props apply to the Radix content
+  element.
+- Radix manages trigger relationships, expanded state, and keyboard behavior.
+
+## Quality bar
+
+- Keep trigger labels short and make each section understandable when closed.
+- Choose single or multiple expansion based on the task, not visual density.
+- Do not put another interactive control inside a trigger.
+- Do not hide required validation errors or the only primary action in a closed
+  item.

package/src/components/ui/alert.md

@@ -11,8 +11,15 @@ Use `AlertDialog` when the user must confirm an action. Use `Empty` for the norm
 ## Usage patterns
 
 ```tsx
-import { CircleAlert } from 'lucide-react'
-import { Alert, AlertDescription, AlertTitle } from '@moldable-ai/ui'
+import { CircleAlert, InfoIcon } from 'lucide-react'
+import {
+  Alert,
+  AlertActions,
+  AlertDescription,
+  AlertDismiss,
+  AlertTitle,
+  Button,
+} from '@moldable-ai/ui'
 
 ;<Alert tone="danger">
   <CircleAlert />
@@ -40,8 +47,9 @@ owned by the caller:
 
 ## API summary
 
-- `tone`: `neutral`, `info`, `success`, `warning`, or `danger`.
-- `density`: `compact` or `default`.
+- `tone`: `neutral`, `info`, `success`, `warning`, or `danger`; defaults to
+  `neutral`.
+- `density`: `compact` or `default`; defaults to `default`.
 - Neutral through warning tones default to `role="status"`; danger defaults to
   `role="alert"`. The native `role` prop can override that choice.
 - `variant="default"` and `variant="destructive"` remain compatibility aliases.

package/src/components/ui/app-frame.md

@@ -4,7 +4,7 @@ The top-level shell for an app that can run in its own window or inside a host
 surface.
 
 ```tsx
-<AppFrame>
+<AppFrame nativeMaterial={{ background: true, sidebar: true }}>
   <Toolbar position="top">
     <ToolbarTitle>Today</ToolbarTitle>
     <ToolbarActions>{/* compact actions */}</ToolbarActions>
@@ -29,8 +29,11 @@ surface.
 - `AppFrameContent` applies the shared chat-safe padding by default. The value is
   zero in a standalone window and is updated by the embedded host lifecycle.
 - Use `mode="embedded"` or `mode="window"` only for deterministic previews and
-  tests. Runtime apps should normally use `mode="auto"`; a future host context
-  may set `data-moldable-display-mode` before render when a window still uses an
-  app iframe.
+  tests. Runtime apps should normally use `mode="auto"`; the host may set
+  `data-moldable-display-mode` when a window still uses an app iframe.
 - Material samples only renderer content. Native behind-window material remains
-  host-owned.
+  host-owned. `nativeMaterial={{ background: true }}` reveals the host's
+  frosted full-window material, while `nativeMaterial={{ sidebar: true }}`
+  allows a compatible sidebar to declare its region. Declare each matching
+  `window.nativeMaterial` option in `moldable.json`. Every option defaults off,
+  and portable semantic fills remain in unsupported environments.

package/src/components/ui/aspect-ratio.md

@@ -0,0 +1,37 @@
+# AspectRatio
+
+## Purpose
+
+`AspectRatio` reserves a stable rectangular area for media whose width and
+height should scale together. Use it for previews, thumbnails, video, and other
+content where layout shift would be distracting.
+
+## Usage
+
+```tsx
+import { AspectRatio } from '@moldable-ai/ui'
+
+;<AspectRatio ratio={16 / 9} className="rounded-control overflow-hidden">
+  <img
+    src={previewUrl}
+    alt="Workspace preview"
+    className="size-full object-cover"
+  />
+</AspectRatio>
+```
+
+## API
+
+- Accepts the Radix aspect-ratio root props.
+- `ratio` is the desired width divided by height, such as `16 / 9` or `1`.
+- The component adds `data-slot="aspect-ratio"` and otherwise leaves content
+  rendering to the caller.
+
+## Quality bar
+
+- Set an explicit ratio that matches the expected media.
+- Give images useful alternative text, or an empty `alt` when decorative.
+- Choose `object-cover` or `object-contain` deliberately; the component does
+  not crop or fit its child.
+- Do not use an aspect ratio wrapper when the content must determine its own
+  height.

package/src/components/ui/avatar.md

@@ -0,0 +1,48 @@
+# Avatar
+
+## Purpose
+
+`Avatar` presents a person, account, or other recognizable identity in a
+compact circular frame. It includes image, fallback, badge, and overlapping
+group primitives.
+
+## Usage
+
+```tsx
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarGroup,
+  AvatarGroupCount,
+  AvatarImage,
+} from '@moldable-ai/ui'
+
+;<AvatarGroup>
+  <Avatar size="sm">
+    <AvatarImage src={owner.photoUrl} alt={owner.name} />
+    <AvatarFallback>RM</AvatarFallback>
+  </Avatar>
+  <AvatarGroupCount>+3</AvatarGroupCount>
+</AvatarGroup>
+```
+
+## API
+
+- `Avatar`: Radix root props plus `size="sm"`, `"default"`, or `"lg"`;
+  defaults to `default`.
+- `AvatarImage`: Radix image props.
+- `AvatarFallback`: Radix fallback props, including delayed fallback behavior.
+- `AvatarBadge`: native `span` props for a compact corner marker.
+- `AvatarGroup` and `AvatarGroupCount`: native `div` props for an overlapping
+  group and its remaining count.
+
+## Quality bar
+
+- Provide a stable fallback, usually initials or a short recognizable mark.
+- Use meaningful image `alt` text, or empty `alt` when adjacent text already
+  names the same identity.
+- Keep one size across an avatar group.
+- Give a badge additional accessible context when its color or icon conveys
+  status.
+- Do not use an avatar as an unlabeled action; wrap it in the appropriate
+  button or link when interactive.

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,16 @@ 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. 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).