@moldable-ai/ui 0.2.22 → 0.2.25

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.

package/src/lib/host-file-dialog.md

@@ -0,0 +1,76 @@
+# Host file dialog
+
+`useHostFileDialog()`, `openFileDialogWithHost()`, and
+`saveFileDialogWithHost()` opt a call site into the host-owned macOS open/save
+sheet when Moldable advertises `fileDialog`.
+
+The fallback is intentionally only a routing signal:
+
+```tsx
+const fileDialog = useHostFileDialog()
+
+async function chooseFiles() {
+  const result = await fileDialog.open({
+    title: 'Import notes',
+    filters: [{ name: 'Text', extensions: ['txt', 'md'] }],
+    defaultLocation: 'documents',
+    properties: { multiple: true },
+  })
+
+  if (result.status === 'fallback') {
+    portableFileInputRef.current?.click()
+    return
+  }
+  if (result.status === 'completed') {
+    await importSelectedPaths(result.paths)
+  }
+}
+
+return (
+  <>
+    <Button onClick={chooseFiles}>Import</Button>
+    <input ref={portableFileInputRef} type="file" multiple hidden />
+  </>
+)
+```
+
+This SDK does not build or trigger the portable `<input type="file">` flow.
+Callers own that cross-platform UI and route to it when the result is
+`{ status: "fallback" }`.
+
+## Result representation
+
+For v1, completed native results contain absolute path strings. This preserves
+parity with Moldable's legacy app-facing `moldable:select-folder` API; there is
+currently no external-file asset or opaque-handle scheme. A selected path is
+not additional filesystem authority: this service only selects a location and
+adds no read or write API.
+
+## Defined v1 behavior
+
+- `filters` accepts at most 32 named filters. Each filter has 1–64 extensions,
+  written without a leading dot. On macOS the validated names describe the
+  filter groups, while AppKit receives the deduplicated union of their
+  extensions as its allowed file types.
+- `defaultLocation` maps `documents`, `downloads`, and `desktop` to those
+  conventional folders under the user's home directory; `home` maps to the
+  home directory; `appData` maps to the requesting app's
+  `workspaces/{workspaceId}/apps/{appId}/data` directory.
+- Open `multiple` defaults to `false`.
+- Open `directories` defaults to `false`; when true the panel chooses
+  directories instead of files.
+- Open and save `createDirectories` default to `false`; when true AppKit shows
+  its New Folder control.
+- Open `showHidden` defaults to `false`; when true hidden entries are initially
+  visible. The user may still use AppKit's standard hidden-file shortcut.
+- Save `defaultName` initializes the filename field and must be a filename, not
+  a path.
+- `title` and `buttonLabel` set AppKit's panel title and confirmation prompt.
+  AppKit sheets may not visibly render a titlebar, but the value is still
+  applied to the panel.
+- Unknown and mode-inappropriate properties are rejected before presentation.
+
+The panel is presented as a sheet owned by the requesting embedded or dedicated
+host window. User cancellation resolves with `{ status: "cancelled" }`. An
+`AbortSignal` abort rejects with `AbortError` and asks the host to cancel the
+request-ID-keyed AppKit panel.

package/src/lib/host-native-menu.md

@@ -0,0 +1,67 @@
+# Host native menu
+
+`useHostNativeMenu()` and `openNativeMenuWithHost()` opt a call site into a
+host-owned AppKit menu when the Moldable host advertises `nativeMenu`. The
+portable Radix `ContextMenu` remains the cross-platform implementation and is
+owned by the caller.
+
+The intended integration shape is to try the native menu from the same pointer
+handler that would open the portable menu, then leave or restore the portable
+path when the host is unavailable:
+
+```tsx
+const nativeMenu = useHostNativeMenu()
+const [portableOpen, setPortableOpen] = useState(false)
+
+async function handleContextMenu(event: React.MouseEvent) {
+  if (!nativeMenu.available) {
+    // Do not prevent the event. ContextMenuTrigger opens the portable menu.
+    return
+  }
+
+  event.preventDefault()
+  const result = await nativeMenu.open(menuItems, {
+    position: { x: event.clientX, y: event.clientY },
+  })
+
+  if (result.status === 'completed') {
+    runCommand(result.selectedId)
+  } else if (result.status === 'fallback') {
+    setPortableOpen(true)
+  }
+}
+
+return (
+  <ContextMenu open={portableOpen} onOpenChange={setPortableOpen}>
+    <ContextMenuTrigger asChild>
+      <div onContextMenu={handleContextMenu}>{children}</div>
+    </ContextMenuTrigger>
+    <ContextMenuContent>{/* existing portable items */}</ContextMenuContent>
+  </ContextMenu>
+)
+```
+
+The request requires exactly one app-viewport placement: an `anchor` element or
+rect, or a pointer `position`. Item depth is capped at 3 and the whole tree at
+200 items. Selectable item IDs are non-empty and unique across the tree.
+Checkboxes support `true`, `false`, and `"mixed"`; radio items reject
+`"mixed"`.
+
+`destructive` is reserved in v1. It is validated and carried through the
+service but is deliberately not rendered with native destructive styling. The
+portable menu may continue to render its destructive variant.
+
+Shortcuts use AppKit's
+[`NSMenuItem.keyEquivalent`](https://developer.apple.com/documentation/appkit/nsmenuitem/keyequivalent)
+and modifier mask so AppKit draws the conventional shortcut label. The menu is
+a transient popup attached to the requesting host window and is never installed
+as the application's main menu, so these values do not register global app
+shortcuts. AppKit may still match the equivalent while that popup is actively
+tracking; callers must treat the field as display metadata and keep command
+handling keyed by the returned `selectedId`.
+
+Click-away and Escape resolve with `{ status: "cancelled" }`. An explicit
+`AbortSignal` abort rejects with `AbortError` and asks the host to call
+`cancelTracking()` on the request-ID-keyed open menu. When native menus are not
+advertised, the helper resolves with `{ status: "fallback" }` without opening
+renderer UI.

package/src/lib/host-share.md

@@ -0,0 +1,36 @@
+# Host share
+
+`useHostShare()` and `shareWithHost()` provide one share API across Moldable
+hosts and ordinary browsers.
+
+```tsx
+const share = useHostShare()
+const buttonRef = useRef<HTMLButtonElement>(null)
+
+await share.share(
+  [
+    { kind: 'text', text: 'A useful note' },
+    { kind: 'url', url: 'https://example.com/note' },
+  ],
+  { anchor: buttonRef.current ?? undefined },
+)
+```
+
+The decision flow is:
+
+1. When the host advertises `share`, the SDK sends a host-service request. The
+   host translates the supplied element or rect from app-viewport coordinates
+   and presents the native picker.
+2. Without that advertisement, text and URL items use `navigator.share` when
+   Web Share is available.
+3. Otherwise the promise resolves with `status: "fallback"` and returns the
+   original items. The caller can then expose its own copy or download UI.
+   File references always take this path outside a native Moldable host because
+   a browser cannot dereference a workspace-local path.
+
+Native dismissal is represented by the envelope's terminal `cancelled` status;
+the SDK maps it to `{ status: "cancelled", method: "native" }`. Web Share
+dismissal resolves with the equivalent `web` result. An explicit `AbortSignal`
+abort rejects with `AbortError`; on the native path the envelope also asks the
+host to dismiss the open picker. `timeoutMs` can lower the host's default
+timeout.

package/src/lib/host-web-surface.md

@@ -0,0 +1,66 @@
+# Host web surface
+
+`useHostWebSurface()` controls a native child webview supplied by the Moldable
+desktop host. It is progressive enhancement: `available` is `true` only in a
+dedicated app window whose manifest declares:
+
+```json
+{
+  "nativeCapabilities": ["webSurface"]
+}
+```
+
+Embedded app views, older hosts, and apps without the declaration receive
+`available: false`. Keep an iframe or reader implementation for those cases.
+
+```tsx
+import { useEffect } from 'react'
+import { useHostWebSurface } from '@moldable-ai/ui'
+
+function LivePage({
+  url,
+  bounds,
+}: {
+  url: string
+  bounds: { x: number; y: number; width: number; height: number }
+}) {
+  const { available, create, destroy, onNavState, setBounds } =
+    useHostWebSurface()
+
+  useEffect(() => {
+    if (!available) return
+
+    void create('active-tab', url, bounds)
+    const unsubscribe = onNavState((state) => {
+      if (state.surfaceId === 'active-tab') {
+        console.log(state.url, state.canGoBack, state.canGoForward)
+      }
+    })
+
+    return () => {
+      unsubscribe()
+      void destroy('active-tab')
+    }
+  }, [available, create, destroy, onNavState, url])
+
+  useEffect(() => {
+    if (available) {
+      void setBounds('active-tab', bounds)
+    }
+  }, [available, bounds, setBounds])
+
+  return available ? null : <iframe title="Live page" src={url} />
+}
+```
+
+Bounds are logical pixels relative to the app content viewport. Re-send them
+when a `ResizeObserver` reports a layout change. The host also re-clamps the
+last requested bounds after native window resizes.
+
+Native child webviews paint above app DOM. Call `setVisible(surfaceId, false)`
+before showing a renderer-owned dialog or overlay, then restore visibility
+when it closes. Host-native menus already paint above the surface.
+
+All methods accept the standard host-service `{ signal, timeoutMs }` options.
+Invalid input throws a `TypeError`; cancellation, timeout, and host failures
+reject with the same errors as other host-service adapters.