@moldable-ai/ui 0.2.21 → 0.2.24

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

@@ -0,0 +1,158 @@
+# Context menu
+
+## Purpose
+
+`ContextMenu` presents commands for the object or region under the pointer. Its
+declarative item API automatically adopts the host-native menu when available
+and renders the same commands portably everywhere else.
+
+Context menus are shortcuts, not the only route to essential actions. Use
+`DropdownMenu` when a visible button should advertise the command list.
+
+## Usage patterns
+
+Use `items` for standard command menus that should automatically adopt the
+native host menu:
+
+```tsx
+import { FolderOpen } from 'lucide-react'
+import {
+  ContextMenu,
+  ContextMenuTrigger,
+  type MenuItems,
+} from '@moldable-ai/ui'
+
+const items: MenuItems[] = [
+  {
+    id: 'open',
+    label: 'Open',
+    icon: FolderOpen,
+    sfSymbol: 'folder',
+    shortcut: { key: 'o', modifiers: ['cmd'] },
+  },
+  { id: 'divider', kind: 'separator' },
+  { id: 'trash', label: 'Move to trash', destructive: true },
+]
+
+function ProjectContextMenu() {
+  return (
+    <ContextMenu items={items} onSelectItem={runCommand}>
+      <ContextMenuTrigger asChild>
+        <article>{project.name}</article>
+      </ContextMenuTrigger>
+    </ContextMenu>
+  )
+}
+```
+
+Use children for custom portable-only content or per-row handlers:
+
+```tsx
+import {
+  ContextMenu,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuSeparator,
+  ContextMenuShortcut,
+  ContextMenuTrigger,
+} from '@moldable-ai/ui'
+
+function ProjectContextMenu() {
+  return (
+    <ContextMenu onOpenChange={setMenuOpen}>
+      <ContextMenuTrigger asChild>
+        <article>{project.name}</article>
+      </ContextMenuTrigger>
+      <ContextMenuContent>
+        <ContextMenuItem onSelect={openProject}>
+          Open
+          <ContextMenuShortcut>⌘O</ContextMenuShortcut>
+        </ContextMenuItem>
+        <ContextMenuSeparator />
+        <ContextMenuItem variant="destructive" onSelect={moveToTrash}>
+          Move to trash
+        </ContextMenuItem>
+      </ContextMenuContent>
+    </ContextMenu>
+  )
+}
+```
+
+## Anatomy
+
+Use `ContextMenuTrigger` around the target and place commands in
+`ContextMenuContent`. Groups, labels, separators, checkbox items, radio groups,
+shortcuts, and submenus are available for structured command sets.
+
+## API summary
+
+- `ContextMenu` supports `items?: MenuItems[]`,
+  `onSelectItem?: (id: string) => void`, `onOpenChange`, `dir`, and `modal`.
+- A `MenuItems` value supports `id`, `kind`, `label`, portable `icon`, reserved
+  `sfSymbol`, `enabled`, `checked`, `shortcut`, `destructive`, and `submenu`.
+- Do not provide `ContextMenuContent` together with `items`. In development this
+  reports an error, and `items` wins.
+- `ContextMenuTrigger` supports `asChild` and `disabled`.
+- `ContextMenuItem` supports menu item props such as `onSelect` and `disabled`,
+  plus `inset` and `variant="default" | "destructive"`.
+- `ContextMenuCheckboxItem` supports `checked`; radio items belong inside
+  `ContextMenuRadioGroup`, whose `value` and `onValueChange` manage the group.
+- `ContextMenuSub` supports `open`, `defaultOpen`, and `onOpenChange`.
+- `ContextMenuLabel` and `ContextMenuSubTrigger` support `inset`.
+
+## States and interaction
+
+Keep command order and wording stable across openings. Disable temporarily
+unavailable commands, but omit commands the target can never support. Check and
+radio state represent durable settings; focus highlighting is transient.
+
+Menu surfaces use `bg-popover`, `text-popover-foreground`,
+`rounded-overlay`, and `shadow-overlay`. Focused rows use the accent roles;
+destructive rows use `text-destructive` and the destructive focus layer.
+
+## Keyboard and accessibility
+
+Radix supplies menu roles, roving focus, typeahead, Escape dismissal, and
+submenu keyboard behavior. Do not put arbitrary controls inside an item. Make
+every essential command available from a visible button, menu, toolbar, or
+command palette as well as the context menu.
+
+## Platform behavior
+
+With `items`, a user-initiated context-menu gesture automatically 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.
+
+When the service is not advertised, including web and iOS, the same items
+automatically render through the existing Radix anatomy. If advertised
+availability becomes stale and the host returns fallback, the original gesture
+is replayed into that portable implementation. 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
+[`host-native-menu.md`](../../lib/host-native-menu.md) for host limits and
+cancellation behavior.
+
+## Do
+
+- Name items with short, verb-led labels.
+- Put JSX shortcuts at the end with `ContextMenuShortcut`, or declare shortcut
+  display metadata in `items`.
+- Separate destructive commands from routine commands.
+- Keep submenu depth shallow.
+
+## Don't
+
+- Do not make a context menu the only way to complete a task.
+- Do not mix `items` with `ContextMenuContent` children.
+- Do not treat shortcut metadata as a registered keyboard command.
+- Do not use raw colors, shadows, or radii for menu states.
+
+## Testing
+
+Exercise secondary click, long press where supported, keyboard navigation,
+Escape, disabled items, checkbox/radio state, submenus, native selection and
+dismissal, service availability changes, and portable fallback.

package/src/components/ui/dialog.md

@@ -18,7 +18,15 @@ spatial context.
       <DialogDescription>Update the selected record.</DialogDescription>
     </DialogHeader>
     <DialogBody>{/* the only scrolling region */}</DialogBody>
-    <DialogFooter>{/* actions remain reachable */}</DialogFooter>
+    <DialogFooter>
+      <span className="text-muted-foreground mr-auto inline-flex items-center gap-1 text-xs">
+        Save <Kbd>⌘</Kbd>
+        <Kbd>Enter</Kbd>
+      </span>
+      <DialogAction primary loading={isSaving} onClick={saveChanges}>
+        Save changes
+      </DialogAction>
+    </DialogFooter>
   </DialogContent>
 </Dialog>
 ```
@@ -30,9 +38,20 @@ scrolling; do not put overflow on both the content and body.
 Keep dialogs opaque and visually stable. Translucent material belongs on small
 temporary control overlays where seeing the underlying context is useful.
 
-For async actions, keep the dialog controlled, disable duplicate submission,
-preserve the action label width, show inline field errors, and close only after
-success. Use `ConfirmDialog` when that is the entire workflow.
+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.
+
+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.
 
 Every dialog needs a `DialogTitle`. Add `DialogDescription` when the outcome or
 scope is not obvious. Escape, outside dismissal, initial focus, and focus return

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

@@ -0,0 +1,165 @@
+# Dropdown menu
+
+## Purpose
+
+`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.
+
+Use `Select` for a form value, `Combobox` for searchable selection,
+`ContextMenu` for commands attached to the pointer target, and `Popover` when
+the surface needs arbitrary interactive content rather than menu items.
+
+## Usage patterns
+
+Use `items` for standard command menus:
+
+```tsx
+import { Copy } from 'lucide-react'
+import {
+  Button,
+  DropdownMenu,
+  DropdownMenuTrigger,
+  type MenuItems,
+} from '@moldable-ai/ui'
+
+const items: MenuItems[] = [
+  {
+    id: 'duplicate',
+    label: 'Duplicate',
+    icon: Copy,
+    shortcut: { key: 'd', modifiers: ['cmd'] },
+  },
+  { id: 'divider', kind: 'separator' },
+  { id: 'trash', label: 'Move to trash', destructive: true },
+]
+
+function ProjectActionsMenu() {
+  return (
+    <DropdownMenu items={items} onSelectItem={runCommand}>
+      <DropdownMenuTrigger asChild>
+        <Button type="button" variant="outline" size="sm">
+          Actions
+        </Button>
+      </DropdownMenuTrigger>
+    </DropdownMenu>
+  )
+}
+```
+
+Use children for custom portable-only content or per-row handlers:
+
+```tsx
+import {
+  Button,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuTrigger,
+} from '@moldable-ai/ui'
+
+function ProjectActionsMenu() {
+  return (
+    <DropdownMenu open={open} onOpenChange={setOpen}>
+      <DropdownMenuTrigger asChild>
+        <Button type="button" variant="outline" size="sm">
+          Actions
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent sideOffset={4} align="end">
+        <DropdownMenuItem onSelect={duplicate}>
+          Duplicate
+          <DropdownMenuShortcut>⌘D</DropdownMenuShortcut>
+        </DropdownMenuItem>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem variant="destructive" onSelect={moveToTrash}>
+          Move to trash
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+```
+
+## Anatomy
+
+`DropdownMenuTrigger` advertises the menu and `DropdownMenuContent` contains
+the commands. Groups, labels, separators, checkbox items, radio groups,
+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`.
+- 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
+  this reports an error, and `items` wins.
+- `DropdownMenuTrigger` accepts button props and `asChild`.
+- `DropdownMenuContent` accepts positioning props including `side`, `align`,
+  and `sideOffset`; this wrapper defaults `sideOffset` to `4`.
+- `DropdownMenuItem` supports menu item props such as `onSelect` and
+  `disabled`, plus `inset` and `variant="default" | "destructive"`.
+- `DropdownMenuCheckboxItem` supports `checked`; radio items belong inside
+  `DropdownMenuRadioGroup`, whose `value` and `onValueChange` manage the group.
+- `DropdownMenuSub` supports `open`, `defaultOpen`, and `onOpenChange`.
+- `DropdownMenuLabel` and `DropdownMenuSubTrigger` support `inset`.
+
+## States and interaction
+
+Use controlled `open` when another surface, including a native-menu fallback,
+must open the portable menu. Checkbox and radio items retain menu semantics and
+should represent durable state. Keep command order stable and place destructive
+commands last or in a separated group.
+
+Menu surfaces use `bg-popover`, `text-popover-foreground`,
+`rounded-overlay`, and `shadow-overlay`. Focused and open submenu rows use the
+accent roles; destructive rows use the semantic destructive roles.
+
+## Keyboard and accessibility
+
+Radix supplies menu roles, trigger semantics, roving focus, typeahead, Escape
+dismissal, and submenu navigation. Give icon-only triggers an accessible name
+and a tooltip. Do not place form fields or arbitrary focusable content inside a
+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.
+
+Shortcuts are display metadata only. They do not register keyboard handlers;
+keep command execution keyed by `onSelectItem`. See
+[`host-native-menu.md`](../../lib/host-native-menu.md) for host limits and
+cancellation behavior.
+
+## Do
+
+- Use a visible trigger that communicates the menu's scope.
+- Keep labels concise and verb-led.
+- Use checkbox and radio items for menu-owned state.
+- Keep submenus shallow and provide shortcuts only for real commands.
+
+## Don't
+
+- Do not use a command menu as a form-value selector.
+- Do not hide a single primary action behind an overflow trigger.
+- Do not mix `items` with `DropdownMenuContent` children.
+- Do not treat shortcut metadata as a registered keyboard command.
+
+## Testing
+
+Exercise pointer and keyboard opening, focus movement, typeahead, Escape,
+disabled items, checkbox/radio state, submenus, native selection and dismissal,
+service availability changes, and portable fallback.

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

@@ -0,0 +1,98 @@
+# ErrorBoundaryView
+
+`ErrorBoundaryView` presents a compact recovery state without owning error
+catching, reporting, or host policy.
+
+## When to use
+
+Use it as the renderer for a React error boundary, route-level failure, or
+host-provided pane error. Supply `actions` when the host owns reporting,
+navigation, or chat recovery.
+
+## When not to use
+
+Do not use it for inline field validation, routine empty states, or transient
+request failures that can stay beside the initiating control. It does not catch
+errors itself; use `AppErrorBoundary` when the package should own catching and
+Moldable reporting.
+
+## Anatomy
+
+The view contains one compact surface with a title, optional message, optional
+error-details disclosure, and one action row. It does not add illustrations or
+nested cards.
+
+## Usage
+
+```tsx
+import { ErrorBoundaryView } from '@moldable-ai/ui'
+
+function PaneError() {
+  return (
+    <ErrorBoundaryView
+      title="Could not load this pane"
+      message="Retry the request or report the captured error."
+      details={error.stack}
+      onRetry={retry}
+      actions={
+        <Button type="button" variant="secondary" onClick={reportError}>
+          Report error
+        </Button>
+      }
+    />
+  )
+}
+```
+
+## Variants and sizes
+
+The renderer has one responsive layout. It uses the available height in a pane
+and can fill a window when its parent gives it full height. The content remains
+bounded to a readable width.
+
+## API
+
+- `title`: heading content. Defaults to `"Something went wrong"`.
+- `message`: optional supporting copy.
+- `details`: optional string shown in a collapsed disclosure with a bounded,
+  scrollable monospace region.
+- `onRetry`: when supplied, renders a `Retry` button and calls the handler once
+  per activation.
+- `actions`: optional host-provided action content rendered after Retry.
+- `className`: optional classes merged onto the outer renderer.
+
+## States and interaction
+
+Omit `details` when there is no safe diagnostic text to show. Omit both
+`onRetry` and `actions` for a read-only failure. Keep retry state in the caller
+and pass `loading` to a custom action when retrying is asynchronous.
+
+## Keyboard and accessibility
+
+The details use native `details` and `summary` semantics. The title is the
+surface heading, the Retry control keeps native button behavior, and diagnostic
+text remains selectable.
+
+## Platform behavior
+
+The component has no host calls or platform branches. `AppErrorBoundary`
+supplies Moldable-specific reload and chat-prefill actions.
+
+## Do
+
+- Keep the title calm and literal.
+- Give the message a concrete recovery path.
+- Redact secrets before passing diagnostic details.
+- Use semantic theme tokens in custom actions.
+
+## Don't
+
+- Do not add decorative error art or nested cards.
+- Do not put binary data or unbounded logs in `details`.
+- Do not make this presentational component report or reload implicitly.
+
+## Testing
+
+Contract tests should verify copy, disclosure behavior, Retry activation, and
+host action rendering. Error-catching and reporting tests belong to the owning
+boundary.

package/src/components/ui/hover-card.md

@@ -0,0 +1,90 @@
+# Hover card
+
+## Purpose
+
+`HoverCard` reveals a richer, non-essential preview for a referenced object,
+usually a link. It helps users decide whether to open a person, file, project,
+or other destination without leaving the current view.
+
+Use `Tooltip` for a terse, non-interactive clarification of an already named
+control. Use `HoverCard` for preview content with several lines or pieces of
+metadata. Use `Popover` when the surface contains actions, fields, settings, or
+other interactive content.
+
+## Usage patterns
+
+```tsx
+import { HoverCard, HoverCardContent, HoverCardTrigger } from '@moldable-ai/ui'
+
+function ProjectPreview() {
+  return (
+    <HoverCard openDelay={400} closeDelay={150}>
+      <HoverCardTrigger href="/projects/atlas">
+        Atlas migration
+      </HoverCardTrigger>
+      <HoverCardContent side="right" align="start">
+        <p className="text-ui-label font-medium">Atlas migration</p>
+        <p className="text-text-secondary text-ui-body">
+          Infrastructure move · updated 12 minutes ago
+        </p>
+      </HoverCardContent>
+    </HoverCard>
+  )
+}
+```
+
+The trigger is link-based by default and accepts anchor props. Keep the
+destination usable without opening the preview.
+
+## Anatomy
+
+`HoverCard` owns timing and open state. `HoverCardTrigger` references the
+previewed object. `HoverCardContent` is portalled and collision-aware; this
+wrapper defaults to `align="center"`, `sideOffset={4}`, and a `w-64` preview.
+
+## API summary
+
+- `HoverCard` supports `open`, `defaultOpen`, `onOpenChange`, `openDelay`, and
+  `closeDelay`.
+- `HoverCardTrigger` accepts anchor props, including `href`.
+- `HoverCardContent` accepts positioning props including `side`, `align`, and
+  `sideOffset`, plus `forceMount` and outside-interaction handlers.
+
+## States and interaction
+
+The preview must remain supplementary. Touch users and users who never hover
+must still be able to understand and activate the trigger. Keep delay changes
+local and deliberate so neighboring previews do not flicker while the pointer
+moves through a collection.
+
+Content uses `bg-popover`, `text-popover-foreground`, `rounded-overlay`, and
+`shadow-overlay`. Use `text-text-secondary` for supporting preview metadata;
+do not invent a preview-only palette or elevation.
+
+## Keyboard and accessibility
+
+The trigger must retain its own accessible name and destination. Do not put
+required instructions only in the card. If content must receive focus or
+contain controls, switch to `Popover`, whose explicit trigger and dismissal
+model fit interactive content.
+
+## Do
+
+- Preview the same object the trigger names.
+- Keep content concise enough to scan without scrolling.
+- Include metadata that helps a navigation decision.
+- Preserve a working link or other primary path on the trigger.
+
+## Don't
+
+- Do not repeat a one-line label that belongs in `Tooltip`.
+- Do not place buttons, links, form fields, or required actions in the card;
+  use `Popover`.
+- Do not make hover the only way to discover important information.
+- Do not use a hover card as a delayed dialog.
+
+## Moldable considerations
+
+Hover cards are portable webview overlays. Keep them within collision-aware
+viewport bounds and avoid previews that cover the fixed desktop chat or a
+primary action for prolonged periods.

package/src/components/ui/select.md

@@ -0,0 +1,111 @@
+# Select
+
+## Purpose
+
+`Select` chooses one value from a short, fixed set. Use it when every option is
+known before the menu opens and scanning the list is faster than typing.
+
+Use `Combobox` when users need to filter a longer list, create a value, fetch
+remote results, or select multiple values. Use `RadioGroup` when a small set of
+important choices should remain visible, and `DropdownMenu` for commands rather
+than form values.
+
+## Usage patterns
+
+```tsx
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectTrigger,
+  SelectValue,
+} from '@moldable-ai/ui'
+
+function SortSelect() {
+  return (
+    <>
+      <label htmlFor="sort-order">Sort</label>
+      <Select defaultValue="updated">
+        <SelectTrigger id="sort-order" size="sm">
+          <SelectValue placeholder="Choose an order" />
+        </SelectTrigger>
+        <SelectContent position="popper" align="start">
+          <SelectGroup>
+            <SelectLabel>Sort by</SelectLabel>
+            <SelectItem value="updated">Recently updated</SelectItem>
+            <SelectItem value="created">Date created</SelectItem>
+            <SelectItem value="name">Name</SelectItem>
+          </SelectGroup>
+        </SelectContent>
+      </Select>
+    </>
+  )
+}
+```
+
+Give the trigger a visible external label or an accessible name. Placeholder
+text describes the missing value; it does not replace a label.
+
+## Anatomy
+
+Compose `Select` with `SelectTrigger`, `SelectValue`, `SelectContent`, and one
+or more `SelectItem` children. `SelectGroup`, `SelectLabel`, and
+`SelectSeparator` organize a longer fixed list. Scroll buttons are included by
+`SelectContent`.
+
+## API summary
+
+- `Select` supports `value`, `defaultValue`, `onValueChange`, `open`,
+  `defaultOpen`, `onOpenChange`, `disabled`, `required`, `name`,
+  `autoComplete`, `form`, and `dir`.
+- `SelectTrigger` accepts button props and `size="sm" | "default"`.
+- `SelectValue` accepts `placeholder`.
+- `SelectContent` accepts `position="item-aligned" | "popper"` and Radix
+  positioning props such as `align`. This wrapper defaults `align` to `center`.
+- `SelectItem` requires a string `value` and supports `disabled` and
+  `textValue`.
+
+## States and interaction
+
+Use controlled `value` when selection affects other state immediately; use
+`defaultValue` for an isolated uncontrolled field. Disable only unavailable
+items rather than the entire select when some choices remain valid. Keep item
+labels stable while the menu is open.
+
+The trigger uses the control shape and body-text roles. The menu uses
+`bg-popover`, `text-popover-foreground`, `rounded-overlay`, and
+`shadow-overlay`; focused options use the semantic accent roles. Preserve those
+roles instead of adding raw fills, radii, or shadows.
+
+## Keyboard and accessibility
+
+Radix supplies listbox keyboard navigation, typeahead, focus management, and
+selection semantics. Do not replace `SelectItem` with buttons or add nested
+interactive controls. Associate a visible label with the trigger, and make
+disabled state apparent without relying on color alone.
+
+## Do
+
+- Use concise, mutually exclusive option labels.
+- Put the current value in `value` or `defaultValue`, not in placeholder text.
+- Use `position="popper"` when the menu should align to the trigger rather than
+  the selected item.
+- Use `SelectLabel` when groups need names.
+
+## Don't
+
+- Do not use `Select` for searchable, creatable, remote, or multi-value data;
+  use `Combobox`.
+- Do not put actions, links, checkboxes, or explanatory paragraphs in the
+  option list.
+- Do not use it for two or three choices that users must compare at a glance;
+  use `RadioGroup`.
+- Do not deep-import the implementation; import from `@moldable-ai/ui`.
+
+## Moldable considerations
+
+`Select` is the portable renderer-owned control in app webviews. Keep required
+choices available through keyboard and pointer input, and do not replace it
+with a host-native command menu.

package/src/lib/host-date-time-picker.md

@@ -0,0 +1,29 @@
+# Host date/time picker
+
+`useHostDateTimePicker()` and `pickDateTimeWithHost()` opt a call site into the
+host-owned system picker when the Moldable host advertises it.
+
+```tsx
+const picker = useHostDateTimePicker()
+const buttonRef = useRef<HTMLButtonElement>(null)
+
+const result = await picker.pick('datetime', {
+  value: '2026-07-26T14:30:00',
+  min: '2026-01-01T00:00:00',
+  anchor: buttonRef.current ?? undefined,
+})
+```
+
+`mode` is `"date"`, `"time"`, or `"datetime"`. `value`, `min`, and `max` use
+the matching timezone-free ISO form: `YYYY-MM-DD`, `HH:mm[:ss]`, or
+`YYYY-MM-DDTHH:mm[:ss]`. This matches portable form controls and avoids
+converting a calendar date through UTC. Native confirmation returns the same
+mode-specific form. Click-away or close resolves with `status: "cancelled"`.
+
+Native presentation is per-call-site opt-in. When the service is unavailable,
+the helper returns `status: "fallback"` together with the mode and range. It
+does not open renderer UI: the caller should keep using the portable
+`DatePicker`, `DateField`, or calendar popover as its default experience.
+
+An explicit `AbortSignal` abort rejects with `AbortError` and asks the host to
+dismiss an open native popover. `timeoutMs` can lower the host default timeout.