@ngrok/mantle 0.82.1 → 0.83.1

package/dist/command.d.ts

@@ -1,19 +1,153 @@
-import { a as Root } from "./dialog-BM4wPCft.js";
-import { ComponentProps, ComponentPropsWithoutRef, ReactNode, Ref } from "react";
+import { t as WithDataSlot } from "./data-slot-CChfb_cv.js";
+import { t as Dialog } from "./dialog-B6h1BCDL.js";
+import { t as Slot } from "./slot-DdgxmuI5.js";
+import { ComponentProps, ComponentPropsWithoutRef, ReactElement, ReactNode, Ref } from "react";
 import { Command as Command$1, useCommandState } from "cmdk";
+//#region src/components/command/search-trigger.d.ts
+/**
+ * The props for `Command.SearchTrigger`.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/command#commandsearchtrigger
+ */
+type CommandSearchTriggerProps = Omit<ComponentProps<typeof Slot>, "children"> & {
+  /**
+   * The control that opens the palette — the row or button a user sees.
+   *
+   * A single element, required: this part renders no DOM of its own and
+   * clones what it is given, so text renders nothing to click and no children
+   * renders no trigger at all. In a sidebar this is a
+   * [`Sidebar.SearchTrigger`](https://mantle.ngrok.com/components/navigation/sidebar#sidebarsearchtrigger);
+   * anywhere else it is whatever your design calls for.
+   */
+  children: ReactElement;
+};
+/**
+ * Makes any control behave like a search field that opens the command palette.
+ * It renders no DOM of its own — it clones its child and gives it the wiring,
+ * so **presentation belongs entirely to the child** and this part never has an
+ * opinion about how the trigger looks or how it behaves in a collapsed sidebar
+ * rail.
+ *
+ * The child stays a `<button>`, not a text field, even when it looks like one:
+ * it opens a modal palette, so a screen reader hears "has popup dialog,
+ * collapsed" while a sighted user sees a field. A real `<input>` with results
+ * in a popover is a combobox, and
+ * [Combobox](https://mantle.ngrok.com/components/forms/combobox) is the
+ * component for that intent.
+ *
+ * Because a search-shaped control invites typing, the wiring makes typing work:
+ * a printable keystroke or a paste while the trigger has focus opens the
+ * palette with that text already in `Command.Input`, so no character is lost
+ * between the trigger and the field. `Enter`, `Space`, and a click open it
+ * empty. See
+ * [`searchActionFromKeyDown`](https://mantle.ngrok.com/components/navigation/command#searchactionfromkeydown)
+ * for the exact policy, including IME composition.
+ *
+ * What it contributes to the child:
+ *
+ * - `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`, and focus
+ *   restoration on close, from the `Dialog.Trigger` it composes.
+ * - `data-state="open" | "closed"`, stamped from the palette's own state so it
+ *   survives being wrapped in another cloning trigger — a `Sidebar.Tooltip`
+ *   passes its own `data-state` down, and Radix's prop merge would otherwise
+ *   let it win.
+ * - `aria-keyshortcuts`, so the `⌘K` binding is announced rather than only
+ *   drawn — present only when `Command.DialogRoot` owns the shortcut, so it can
+ *   never advertise a binding that is not bound. Pass your own value to
+ *   announce a chord you bound yourself.
+ * - `onKeyDown` and `onPaste`, composed with the child's own handlers.
+ * - `data-slot="command-search-trigger"`, joined ahead of the child's own slot.
+ *
+ * Every other prop it receives passes through to the child, so composing it
+ * inside another cloning trigger works: `Sidebar.Tooltip` → `Command.SearchTrigger`
+ * → `Sidebar.SearchTrigger` routes the tooltip's handlers all the way down.
+ *
+ * It adds no accessible name: the child's visible label is the name, so the two
+ * cannot drift apart. A visible `⌘K` hint belongs to the child and should be
+ * `aria-hidden` there, since `aria-keyshortcuts` already announces the chord —
+ * `Sidebar.SearchTrigger`'s `shortcut` prop does that for you.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/command#commandsearchtrigger
+ *
+ * @example
+ * ```tsx
+ * <Command.DialogRoot>
+ *   <Command.SearchTrigger>
+ *     <button type="button">
+ *       <MagnifyingGlassIcon />
+ *       <span>Search…</span>
+ *     </button>
+ *   </Command.SearchTrigger>
+ *   <Command.DialogContent>
+ *     <Command.Input placeholder="Type a command or search..." />
+ *     <Command.List>
+ *       <Command.Empty>No results found.</Command.Empty>
+ *       <Command.Group heading="Suggestions">
+ *         <Command.Item>
+ *           <span>Calendar</span>
+ *         </Command.Item>
+ *       </Command.Group>
+ *       <Command.Separator />
+ *       <Command.Group heading="Settings">
+ *         <Command.Item>
+ *           <span>Profile</span>
+ *           <Command.Shortcut>⌘,</Command.Shortcut>
+ *         </Command.Item>
+ *       </Command.Group>
+ *     </Command.List>
+ *   </Command.DialogContent>
+ * </Command.DialogRoot>
+ * ```
+ *
+ * @example
+ * In a sidebar, where `Sidebar.SearchTrigger` owns the row's appearance in both
+ * panel states — including its hover-revealed shortcut hint — and
+ * `Sidebar.Tooltip` labels it in the collapsed rail:
+ * ```tsx
+ * <Sidebar.Body>
+ *   <Command.DialogRoot>
+ *     <Sidebar.Tooltip label="Search">
+ *       <Command.SearchTrigger>
+ *         <Sidebar.SearchTrigger
+ *           shortcut={
+ *             <>
+ *               <MetaKey />
+ *               <Kbd>K</Kbd>
+ *             </>
+ *           }
+ *         >
+ *           <MagnifyingGlassIcon />
+ *           <span className="min-w-0 flex-1 truncate">Search</span>
+ *         </Sidebar.SearchTrigger>
+ *       </Command.SearchTrigger>
+ *     </Sidebar.Tooltip>
+ *     <Command.DialogContent>
+ *       <Command.Input placeholder="Search endpoints, agents, and settings..." />
+ *       <Command.List>
+ *         <Command.Empty>No results found.</Command.Empty>
+ *       </Command.List>
+ *     </Command.DialogContent>
+ *   </Command.DialogRoot>
+ * </Sidebar.Body>
+ * ```
+ */
+declare const CommandSearchTrigger: ({ "aria-keyshortcuts": ariaKeyshortcuts, children, "data-slot": dataSlot, onKeyDown, onPaste, ...props }: CommandSearchTriggerProps) => import("react").JSX.Element;
+//#endregion
 //#region src/components/command/command.d.ts
 type CommandRootProps = ComponentProps<typeof Command$1>;
 /**
- * The root component for the Command. It provides the context for all other command sub-components.
+ * The inline palette, wrapping `Command.Input` and `Command.List`. It owns the
+ * filtering and the active item for every part below it — `Command.DialogContent`
+ * renders one itself, so a modal palette does not add it.
  *
  * @see https://mantle.ngrok.com/components/navigation/command#commandroot
  *
  * @example
  * ```tsx
- * <Command.DialogRoot open={open} onOpenChange={setOpen}>
- *   <Command.DialogTrigger asChild>
- *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
- *   </Command.DialogTrigger>
+ * <Command.DialogRoot>
+ *   <Command.SearchTrigger>
+ *     <button type="button">Search…</button>
+ *   </Command.SearchTrigger>
  *   <Command.DialogContent>
  *     <Command.Input placeholder="Type a command or search..." />
  *     <Command.List>
@@ -36,6 +170,112 @@ type CommandRootProps = ComponentProps<typeof Command$1>;
  * ```
  */
 declare const CommandRoot: ({ className, ...props }: CommandRootProps) => import("react").JSX.Element;
+/**
+ * The props for `Command.DialogRoot`. `Dialog.Root`'s props — so `modal` still
+ * reaches the underlying dialog — with the open state and the keyboard shortcut
+ * redeclared here, because this part owns them.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/command#commanddialogroot
+ */
+type CommandDialogRootProps = Omit<ComponentProps<typeof Dialog.Root>, "children" | "defaultOpen" | "onOpenChange" | "open"> & {
+  /**
+   * The palette's parts — a `Command.DialogContent`, and any trigger or
+   * consumer of `useCommandDialog()`. `DialogRoot` renders no DOM of its own.
+   */
+  children?: ReactNode;
+  /**
+   * The initial open state for the uncontrolled case.
+   *
+   * @default false
+   */
+  defaultOpen?: boolean;
+  /**
+   * Bind `⌘K` (macOS) / `Ctrl+K` (Windows/Linux) to toggle the palette. The
+   * shortcut requires exactly the platform modifier + `k`, resolved per host —
+   * the two never substitute for each other, so macOS's native `Ctrl+K` ("kill
+   * to end of line") is left alone. `Shift`/`Alt` combinations pass through.
+   *
+   * It lives here rather than on `Command.SearchTrigger` because the trigger
+   * may be unmounted while the shortcut must still work — a sidebar rendered
+   * as a mobile sheet unmounts its whole tree when the sheet is closed.
+   *
+   * The shortcut is ignored while focus is in a rich-text or code editor
+   * (`contenteditable`, or a `<textarea>`, which is what Monaco attaches to),
+   * where `⌘K` is already bound to "insert link" or a chord prefix. It
+   * deliberately still fires from a plain `<input>`, including the palette's
+   * own `Command.Input` — so the chord closes what it opened.
+   *
+   * Exactly one root per window owns the shortcut: the first mounted root that
+   * wants it. Additional roots queue and take over when the owner unmounts, so
+   * a second palette never opens alongside the first.
+   *
+   * Set `false` to bind the chord yourself with `useCommandDialog()`.
+   * `Command.SearchTrigger` then adds no `aria-keyshortcuts` of its own — pass
+   * one to announce the chord you bound — and `useCommandDialog().keyboardShortcut`
+   * reports the same flag. The *visible* hint always belongs to the trigger's
+   * child, so gating that on the flag is the child's job.
+   *
+   * @default true
+   */
+  keyboardShortcut?: boolean;
+  /**
+   * Called with the next open state whenever it changes.
+   */
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * Controlled open state. Pair with `onOpenChange`.
+   */
+  open?: boolean;
+};
+/**
+ * The state owner for a command palette. Renders no DOM of its own — it owns
+ * the open state, the query text, and the `⌘K` shortcut, and carries them to
+ * every part below through `useCommandDialog()`.
+ *
+ * Owning the query is what makes typing into `Command.SearchTrigger` work: the
+ * seed and the open state land in one state update, so `Command.Input` mounts
+ * with the character already in it and no keystroke races the dialog's mount.
+ *
+ * **Opening always starts from a known query** — the seed, or empty. That
+ * happens at open time rather than by clearing on close, because
+ * `Dialog.Content` animates out and clearing on close would swap the visible
+ * list mid-animation. So dismissing and reopening never resurrects the previous
+ * search.
+ *
+ * Pass `open`/`onOpenChange` to control the open state; the query stays
+ * internal either way. To own the query too, pass `value`/`onValueChange` to
+ * `Command.Input` — see that part for the trade-off.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/command#commanddialogroot
+ *
+ * @example
+ * ```tsx
+ * <Command.DialogRoot>
+ *   <Command.SearchTrigger>
+ *     <button type="button">Search…</button>
+ *   </Command.SearchTrigger>
+ *   <Command.DialogContent>
+ *     <Command.Input placeholder="Type a command or search..." />
+ *     <Command.List>
+ *       <Command.Empty>No results found.</Command.Empty>
+ *       <Command.Group heading="Suggestions">
+ *         <Command.Item>
+ *           <span>Calendar</span>
+ *         </Command.Item>
+ *       </Command.Group>
+ *       <Command.Separator />
+ *       <Command.Group heading="Settings">
+ *         <Command.Item>
+ *           <span>Profile</span>
+ *           <Command.Shortcut>⌘,</Command.Shortcut>
+ *         </Command.Item>
+ *       </Command.Group>
+ *     </Command.List>
+ *   </Command.DialogContent>
+ * </Command.DialogRoot>
+ * ```
+ */
+declare const CommandDialogRoot: ({ children, defaultOpen, keyboardShortcut, onOpenChange, open: openProp, ...props }: CommandDialogRootProps) => import("react").JSX.Element;
 /**
  * The props for the CommandDialog.Content component.
  *
@@ -89,10 +329,10 @@ type CommandDialogContentProps = {
  *
  * @example
  * ```tsx
- * <Command.DialogRoot open={open} onOpenChange={setOpen}>
- *   <Command.DialogTrigger asChild>
- *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
- *   </Command.DialogTrigger>
+ * <Command.DialogRoot>
+ *   <Command.SearchTrigger>
+ *     <button type="button">Search…</button>
+ *   </Command.SearchTrigger>
  *   <Command.DialogContent>
  *     <Command.Input placeholder="Type a command or search..." />
  *     <Command.List>
@@ -116,16 +356,37 @@ type CommandDialogContentProps = {
  */
 declare const CommandDialogContent: ({ children, className, description, filter, shouldFilter, showCloseButton, title }: CommandDialogContentProps) => import("react").JSX.Element;
 /**
- * The input component for the Command. It provides the input for the command palette.
+ * The palette's query field.
+ *
+ * Inside a `Command.DialogRoot` the palette owns the query by default, which is
+ * what lets `Command.SearchTrigger` open with a seeded value and what
+ * `useCommandDialog().query` reads. Under a bare `Command.Root` (an inline
+ * palette, no dialog) it stays uncontrolled and cmdk owns the text.
+ *
+ * Passing `value` takes the query over completely: your value wins, this stops
+ * reporting to `useCommandDialog()`, and **seeding becomes yours to apply** —
+ * read `useCommandDialog().query` and mirror it, or drop
+ * `Command.SearchTrigger` for a plain `Command.DialogTrigger`. Prefer leaving
+ * it uncontrolled and reading the query from the hook.
+ *
+ * `className`, `ref`, and rest props land on the parts they belong to: `ref` on
+ * the wrapper, everything else on the `<input>`.
+ *
+ * **Data attributes:**
+ *
+ * | Data Attribute | Value | Description |
+ * | --- | --- | --- |
+ * | `data-slot` | `"command-input-wrapper"` | The row holding the magnifier and the field. |
+ * | `data-slot` | `"command-input"` | The `<input>` itself, joined after any `data-slot` you forward. Load-bearing beyond styling: `Command.DialogContent` finds the field by this slot when the palette opens, to place the caret after a seeded query instead of over it, so this part of the chain is never replaced. |
  *
  * @see https://mantle.ngrok.com/components/navigation/command#commandinput
  *
  * @example
  * ```tsx
- * <Command.DialogRoot open={open} onOpenChange={setOpen}>
- *   <Command.DialogTrigger asChild>
- *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
- *   </Command.DialogTrigger>
+ * <Command.DialogRoot>
+ *   <Command.SearchTrigger>
+ *     <button type="button">Search…</button>
+ *   </Command.SearchTrigger>
  *   <Command.DialogContent>
  *     <Command.Input placeholder="Type a command or search..." />
  *     <Command.List>
@@ -147,20 +408,20 @@ declare const CommandDialogContent: ({ children, className, description, filter,
  * </Command.DialogRoot>
  * ```
  */
-declare const CommandInput: ({ className, ref, ...props }: ComponentPropsWithoutRef<typeof Command$1.Input> & {
+declare const CommandInput: ({ className, "data-slot": dataSlot, onValueChange, ref, value, ...props }: ComponentPropsWithoutRef<typeof Command$1.Input> & WithDataSlot & {
   ref?: Ref<HTMLDivElement>;
 }) => import("react").JSX.Element;
 /**
- * The list component for the Command. It provides the list for the command palette.
+ * The scrolling container for the palette's groups and items.
  *
  * @see https://mantle.ngrok.com/components/navigation/command#commandlist
  *
  * @example
  * ```tsx
- * <Command.DialogRoot open={open} onOpenChange={setOpen}>
- *   <Command.DialogTrigger asChild>
- *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
- *   </Command.DialogTrigger>
+ * <Command.DialogRoot>
+ *   <Command.SearchTrigger>
+ *     <button type="button">Search…</button>
+ *   </Command.SearchTrigger>
  *   <Command.DialogContent>
  *     <Command.Input placeholder="Type a command or search..." />
  *     <Command.List>
@@ -184,16 +445,16 @@ declare const CommandInput: ({ className, ref, ...props }: ComponentPropsWithout
  */
 declare const CommandList: ({ className, ...props }: ComponentProps<typeof Command$1.List>) => import("react").JSX.Element;
 /**
- * The empty component for the Command. It provides the empty state for the command palette.
+ * The empty-state message; it renders only when no item matches the query.
  *
  * @see https://mantle.ngrok.com/components/navigation/command#commandempty
  *
  * @example
  * ```tsx
- * <Command.DialogRoot open={open} onOpenChange={setOpen}>
- *   <Command.DialogTrigger asChild>
- *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
- *   </Command.DialogTrigger>
+ * <Command.DialogRoot>
+ *   <Command.SearchTrigger>
+ *     <button type="button">Search…</button>
+ *   </Command.SearchTrigger>
  *   <Command.DialogContent>
  *     <Command.Input placeholder="Type a command or search..." />
  *     <Command.List>
@@ -217,16 +478,16 @@ declare const CommandList: ({ className, ...props }: ComponentProps<typeof Comma
  */
 declare const CommandEmpty: ({ className, ...props }: ComponentProps<typeof Command$1.Empty>) => import("react").JSX.Element;
 /**
- * The group component for the Command. It provides the group for the command palette.
+ * A labeled section of items; the `heading` prop names it.
  *
  * @see https://mantle.ngrok.com/components/navigation/command#commandgroup
  *
  * @example
  * ```tsx
- * <Command.DialogRoot open={open} onOpenChange={setOpen}>
- *   <Command.DialogTrigger asChild>
- *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
- *   </Command.DialogTrigger>
+ * <Command.DialogRoot>
+ *   <Command.SearchTrigger>
+ *     <button type="button">Search…</button>
+ *   </Command.SearchTrigger>
  *   <Command.DialogContent>
  *     <Command.Input placeholder="Type a command or search..." />
  *     <Command.List>
@@ -250,16 +511,16 @@ declare const CommandEmpty: ({ className, ...props }: ComponentProps<typeof Comm
  */
 declare const CommandGroup: ({ className, ...props }: ComponentProps<typeof Command$1.Group>) => import("react").JSX.Element;
 /**
- * The separator component for the Command. It provides the separator for the command palette.
+ * A horizontal rule between two groups of items.
  *
  * @see https://mantle.ngrok.com/components/navigation/command#commandseparator
  *
  * @example
  * ```tsx
- * <Command.DialogRoot open={open} onOpenChange={setOpen}>
- *   <Command.DialogTrigger asChild>
- *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
- *   </Command.DialogTrigger>
+ * <Command.DialogRoot>
+ *   <Command.SearchTrigger>
+ *     <button type="button">Search…</button>
+ *   </Command.SearchTrigger>
  *   <Command.DialogContent>
  *     <Command.Input placeholder="Type a command or search..." />
  *     <Command.List>
@@ -283,16 +544,16 @@ declare const CommandGroup: ({ className, ...props }: ComponentProps<typeof Comm
  */
 declare const CommandSeparator: ({ className, ...props }: ComponentProps<typeof Command$1.Separator>) => import("react").JSX.Element;
 /**
- * The item component for the Command. It provides the item for the command palette.
+ * One selectable row in the palette's list.
  *
  * @see https://mantle.ngrok.com/components/navigation/command#commanditem
  *
  * @example
  * ```tsx
- * <Command.DialogRoot open={open} onOpenChange={setOpen}>
- *   <Command.DialogTrigger asChild>
- *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
- *   </Command.DialogTrigger>
+ * <Command.DialogRoot>
+ *   <Command.SearchTrigger>
+ *     <button type="button">Search…</button>
+ *   </Command.SearchTrigger>
  *   <Command.DialogContent>
  *     <Command.Input placeholder="Type a command or search..." />
  *     <Command.List>
@@ -316,16 +577,16 @@ declare const CommandSeparator: ({ className, ...props }: ComponentProps<typeof
  */
 declare const CommandItem: ({ className, ...props }: ComponentProps<typeof Command$1.Item>) => import("react").JSX.Element;
 /**
- * The shortcut component for the Command. It provides the shortcut for the command palette.
+ * The keyboard hint for a `Command.Item`, aligned to the end of the row.
  *
  * @see https://mantle.ngrok.com/components/navigation/command#commandshortcut
  *
  * @example
  * ```tsx
- * <Command.DialogRoot open={open} onOpenChange={setOpen}>
- *   <Command.DialogTrigger asChild>
- *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
- *   </Command.DialogTrigger>
+ * <Command.DialogRoot>
+ *   <Command.SearchTrigger>
+ *     <button type="button">Search…</button>
+ *   </Command.SearchTrigger>
  *   <Command.DialogContent>
  *     <Command.Input placeholder="Type a command or search..." />
  *     <Command.List>
@@ -349,7 +610,16 @@ declare const CommandItem: ({ className, ...props }: ComponentProps<typeof Comma
  */
 declare const CommandShortcut: ({ className, ...props }: ComponentProps<"span">) => import("react").JSX.Element;
 /**
- * The command component for the Command. It provides the command for the command palette.
+ * A command palette: a modal search field over a filtered, keyboard-navigable
+ * list of items. `Command.SearchTrigger` is the field-shaped button that opens
+ * it, `Command.DialogRoot` owns the open state, the query, and the `⌘K`
+ * shortcut, and `Command.DialogTrigger` is the escape hatch for a trigger of
+ * your own.
+ *
+ * Use `Command.Root` instead of `Command.DialogRoot` for an inline palette that
+ * is always visible. For a text field that filters options in place rather than
+ * opening a modal, the component is
+ * [Combobox](https://mantle.ngrok.com/components/forms/combobox).
  *
  * @see https://mantle.ngrok.com/components/navigation/command
  *
@@ -357,6 +627,7 @@ declare const CommandShortcut: ({ className, ...props }: ComponentProps<"span">)
  * Composition:
  * ```
  * Command.DialogRoot
+ * ├── Command.SearchTrigger
  * ├── Command.DialogTrigger
  * └── Command.DialogContent
  *     ├── Command.Input
@@ -370,10 +641,10 @@ declare const CommandShortcut: ({ className, ...props }: ComponentProps<"span">)
  *
  * @example
  * ```tsx
- * <Command.DialogRoot open={open} onOpenChange={setOpen}>
- *   <Command.DialogTrigger asChild>
- *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
- *   </Command.DialogTrigger>
+ * <Command.DialogRoot>
+ *   <Command.SearchTrigger>
+ *     <button type="button">Search…</button>
+ *   </Command.SearchTrigger>
  *   <Command.DialogContent>
  *     <Command.Input placeholder="Type a command or search..." />
  *     <Command.List>
@@ -397,16 +668,18 @@ declare const CommandShortcut: ({ className, ...props }: ComponentProps<"span">)
  */
 declare const Command: {
   /**
-   * The root component for the Command component.
+   * The inline palette, wrapping `Command.Input` and `Command.List`. It owns the
+   * filtering and the active item for every part below it — `Command.DialogContent`
+   * renders one itself, so a modal palette does not add it.
    *
    * @see https://mantle.ngrok.com/components/navigation/command#commandroot
    *
    * @example
    * ```tsx
-   * <Command.DialogRoot open={open} onOpenChange={setOpen}>
-   *   <Command.DialogTrigger asChild>
-   *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
-   *   </Command.DialogTrigger>
+   * <Command.DialogRoot>
+   *   <Command.SearchTrigger>
+   *     <button type="button">Search…</button>
+   *   </Command.SearchTrigger>
    *   <Command.DialogContent>
    *     <Command.Input placeholder="Type a command or search..." />
    *     <Command.List>
@@ -430,16 +703,51 @@ declare const Command: {
    */
   readonly Root: typeof CommandRoot;
   /**
-   * The root stateful component for the Command dialog. Manages open/closed state.
+   * The state owner for the Command dialog. Owns the open state, the query
+   * text, and the `⌘K` shortcut, and renders no DOM of its own.
    *
    * @see https://mantle.ngrok.com/components/navigation/command#commanddialogroot
    *
    * @example
    * ```tsx
-   * <Command.DialogRoot open={open} onOpenChange={setOpen}>
-   *   <Command.DialogTrigger asChild>
-   *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
-   *   </Command.DialogTrigger>
+   * <Command.DialogRoot>
+   *   <Command.SearchTrigger>
+   *     <button type="button">Search…</button>
+   *   </Command.SearchTrigger>
+   *   <Command.DialogContent>
+   *     <Command.Input placeholder="Type a command or search..." />
+   *     <Command.List>
+   *       <Command.Empty>No results found.</Command.Empty>
+   *       <Command.Group heading="Suggestions">
+   *         <Command.Item>
+   *           <span>Calendar</span>
+   *         </Command.Item>
+   *       </Command.Group>
+   *       <Command.Separator />
+   *       <Command.Group heading="Settings">
+   *         <Command.Item>
+   *           <span>Profile</span>
+   *           <Command.Shortcut>⌘,</Command.Shortcut>
+   *         </Command.Item>
+   *       </Command.Group>
+   *     </Command.List>
+   *   </Command.DialogContent>
+   * </Command.DialogRoot>
+   * ```
+   */
+  readonly DialogRoot: typeof CommandDialogRoot;
+  /**
+   * A button shaped like an `Input` that opens the palette, with the `⌘K` hint
+   * and keystroke/paste forwarding.
+   *
+   * @see https://mantle.ngrok.com/components/navigation/command#commandsearchtrigger
+   *
+   * @example
+   * ```tsx
+   * <Command.DialogRoot>
+   *   <Command.SearchTrigger>
+   *     <button type="button">Search…</button>
+   *   </Command.SearchTrigger>
    *   <Command.DialogContent>
    *     <Command.Input placeholder="Type a command or search..." />
    *     <Command.List>
@@ -461,15 +769,22 @@ declare const Command: {
    * </Command.DialogRoot>
    * ```
    */
-  readonly DialogRoot: typeof Root;
+  readonly SearchTrigger: typeof CommandSearchTrigger;
   /**
-   * A button that opens the Command dialog when clicked.
+   * A bare button that opens the Command dialog when clicked — the escape hatch
+   * for a trigger that should not look like a search field. Wrap your own
+   * element with `asChild`.
+   *
+   * It carries none of `Command.SearchTrigger`'s behavior: no `⌘K` hint, no
+   * `aria-keyshortcuts`, and typing or pasting into it does nothing. Rebuild
+   * that with `useCommandDialog()` and `searchActionFromKeyDown` /
+   * `searchActionFromPaste` if you need it.
    *
    * @see https://mantle.ngrok.com/components/navigation/command#commanddialogtrigger
    *
    * @example
    * ```tsx
-   * <Command.DialogRoot open={open} onOpenChange={setOpen}>
+   * <Command.DialogRoot>
    *   <Command.DialogTrigger asChild>
    *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
    *   </Command.DialogTrigger>
@@ -502,10 +817,10 @@ declare const Command: {
    *
    * @example
    * ```tsx
-   * <Command.DialogRoot open={open} onOpenChange={setOpen}>
-   *   <Command.DialogTrigger asChild>
-   *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
-   *   </Command.DialogTrigger>
+   * <Command.DialogRoot>
+   *   <Command.SearchTrigger>
+   *     <button type="button">Search…</button>
+   *   </Command.SearchTrigger>
    *   <Command.DialogContent>
    *     <Command.Input placeholder="Type a command or search..." />
    *     <Command.List>
@@ -529,16 +844,16 @@ declare const Command: {
    */
   readonly DialogContent: typeof CommandDialogContent;
   /**
-   * The input component for the Command component.
+   * The palette's query field.
    *
    * @see https://mantle.ngrok.com/components/navigation/command#commandinput
    *
    * @example
    * ```tsx
-   * <Command.DialogRoot open={open} onOpenChange={setOpen}>
-   *   <Command.DialogTrigger asChild>
-   *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
-   *   </Command.DialogTrigger>
+   * <Command.DialogRoot>
+   *   <Command.SearchTrigger>
+   *     <button type="button">Search…</button>
+   *   </Command.SearchTrigger>
    *   <Command.DialogContent>
    *     <Command.Input placeholder="Type a command or search..." />
    *     <Command.List>
@@ -562,16 +877,16 @@ declare const Command: {
    */
   readonly Input: typeof CommandInput;
   /**
-   * The list component for the Command component.
+   * The scrolling container for the palette's groups and items.
    *
    * @see https://mantle.ngrok.com/components/navigation/command#commandlist
    *
    * @example
    * ```tsx
-   * <Command.DialogRoot open={open} onOpenChange={setOpen}>
-   *   <Command.DialogTrigger asChild>
-   *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
-   *   </Command.DialogTrigger>
+   * <Command.DialogRoot>
+   *   <Command.SearchTrigger>
+   *     <button type="button">Search…</button>
+   *   </Command.SearchTrigger>
    *   <Command.DialogContent>
    *     <Command.Input placeholder="Type a command or search..." />
    *     <Command.List>
@@ -595,16 +910,16 @@ declare const Command: {
    */
   readonly List: typeof CommandList;
   /**
-   * The empty component for the Command component.
+   * The empty-state message; it renders only when no item matches the query.
    *
    * @see https://mantle.ngrok.com/components/navigation/command#commandempty
    *
    * @example
    * ```tsx
-   * <Command.DialogRoot open={open} onOpenChange={setOpen}>
-   *   <Command.DialogTrigger asChild>
-   *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
-   *   </Command.DialogTrigger>
+   * <Command.DialogRoot>
+   *   <Command.SearchTrigger>
+   *     <button type="button">Search…</button>
+   *   </Command.SearchTrigger>
    *   <Command.DialogContent>
    *     <Command.Input placeholder="Type a command or search..." />
    *     <Command.List>
@@ -628,16 +943,16 @@ declare const Command: {
    */
   readonly Empty: typeof CommandEmpty;
   /**
-   * The group component for the Command component.
+   * A labeled section of items; the `heading` prop names it.
    *
    * @see https://mantle.ngrok.com/components/navigation/command#commandgroup
    *
    * @example
    * ```tsx
-   * <Command.DialogRoot open={open} onOpenChange={setOpen}>
-   *   <Command.DialogTrigger asChild>
-   *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
-   *   </Command.DialogTrigger>
+   * <Command.DialogRoot>
+   *   <Command.SearchTrigger>
+   *     <button type="button">Search…</button>
+   *   </Command.SearchTrigger>
    *   <Command.DialogContent>
    *     <Command.Input placeholder="Type a command or search..." />
    *     <Command.List>
@@ -661,16 +976,16 @@ declare const Command: {
    */
   readonly Group: typeof CommandGroup;
   /**
-   * The item component for the Command component.
+   * One selectable row in the palette's list.
    *
    * @see https://mantle.ngrok.com/components/navigation/command#commanditem
    *
    * @example
    * ```tsx
-   * <Command.DialogRoot open={open} onOpenChange={setOpen}>
-   *   <Command.DialogTrigger asChild>
-   *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
-   *   </Command.DialogTrigger>
+   * <Command.DialogRoot>
+   *   <Command.SearchTrigger>
+   *     <button type="button">Search…</button>
+   *   </Command.SearchTrigger>
    *   <Command.DialogContent>
    *     <Command.Input placeholder="Type a command or search..." />
    *     <Command.List>
@@ -694,16 +1009,16 @@ declare const Command: {
    */
   readonly Item: typeof CommandItem;
   /**
-   * The shortcut component for the Command component.
+   * The keyboard hint for a `Command.Item`, aligned to the end of the row.
    *
    * @see https://mantle.ngrok.com/components/navigation/command#commandshortcut
    *
    * @example
    * ```tsx
-   * <Command.DialogRoot open={open} onOpenChange={setOpen}>
-   *   <Command.DialogTrigger asChild>
-   *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
-   *   </Command.DialogTrigger>
+   * <Command.DialogRoot>
+   *   <Command.SearchTrigger>
+   *     <button type="button">Search…</button>
+   *   </Command.SearchTrigger>
    *   <Command.DialogContent>
    *     <Command.Input placeholder="Type a command or search..." />
    *     <Command.List>
@@ -727,16 +1042,16 @@ declare const Command: {
    */
   readonly Shortcut: typeof CommandShortcut;
   /**
-   * The separator component for the Command component.
+   * A horizontal rule between two groups of items.
    *
    * @see https://mantle.ngrok.com/components/navigation/command#commandseparator
    *
    * @example
    * ```tsx
-   * <Command.DialogRoot open={open} onOpenChange={setOpen}>
-   *   <Command.DialogTrigger asChild>
-   *     <Button type="button" appearance="outlined" intent="neutral">Open Command Palette</Button>
-   *   </Command.DialogTrigger>
+   * <Command.DialogRoot>
+   *   <Command.SearchTrigger>
+   *     <button type="button">Search…</button>
+   *   </Command.SearchTrigger>
    *   <Command.DialogContent>
    *     <Command.Input placeholder="Type a command or search..." />
    *     <Command.List>
@@ -761,13 +1076,106 @@ declare const Command: {
   readonly Separator: typeof CommandSeparator;
 };
 //#endregion
+//#region src/components/command/dialog-context.d.ts
+/**
+ * The state and actions every part under a `Command.DialogRoot` shares,
+ * returned by {@link useCommandDialog}. Use it to open the palette from
+ * anywhere in the app, to build a custom search trigger, or to read the query
+ * a `shouldFilter={false}` palette needs to do its own matching.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/command#usecommanddialog
+ *
+ * @example
+ * ```tsx
+ * function EmptyStateSearchLink() {
+ *   const { openWithQuery } = useCommandDialog();
+ *   return (
+ *     <button type="button" onClick={() => openWithQuery("endpoints")}>
+ *       Search endpoints
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+type CommandDialogState = {
+  /**
+   * Whether the palette is open. Mirrored as `data-state="open" | "closed"` on
+   * `Command.SearchTrigger` and paired with its `aria-expanded`.
+   */
+  open: boolean;
+  /**
+   * Set the open state. **Opening through this resets the query to empty** —
+   * use {@link CommandDialogState.openWithQuery} to open with text in the
+   * field. Calls `onOpenChange` and, when uncontrolled, updates the internal
+   * state.
+   */
+  setOpen: (open: boolean) => void;
+  /**
+   * Open the palette with `query` already in `Command.Input`, or with an empty
+   * query when called with no argument. This is what `Command.SearchTrigger`
+   * calls when a keystroke or paste reaches it.
+   */
+  openWithQuery: (query?: string) => void;
+  /**
+   * Toggle the palette. Opening resets the query to empty, closing leaves it
+   * alone (the content animates out, so clearing it mid-animation would swap
+   * the visible list). This is what the `⌘K` shortcut calls.
+   */
+  toggle: () => void;
+  /**
+   * The current text of `Command.Input`. Read it to drive your own filtering
+   * or a server-side search when the palette runs with `shouldFilter={false}`.
+   *
+   * Only meaningful while `Command.Input` is uncontrolled — passing it a
+   * `value` takes ownership of the query, and this stops tracking the field.
+   */
+  query: string;
+  /**
+   * Set the query without touching the open state. `Command.Input` calls this
+   * as the user types.
+   */
+  setQuery: (query: string) => void;
+  /**
+   * Whether this root owns the `⌘K` / `Ctrl+K` shortcut. `Command.SearchTrigger`
+   * reads it to decide whether to stamp `aria-keyshortcuts`; read it yourself
+   * in the trigger's child to gate its *visible* hint, so neither can advertise
+   * a binding that is not there.
+   */
+  keyboardShortcut: boolean;
+};
+/**
+ * Read the nearest `Command.DialogRoot` state. Throws when called outside one
+ * so misuse fails loudly rather than rendering a trigger that opens nothing.
+ *
+ * Reach for it to open the palette from somewhere other than its trigger — a
+ * sidebar row, an empty state, a "no results, search everything" link — or to
+ * build a custom trigger, pairing it with
+ * [`searchActionFromKeyDown`](https://mantle.ngrok.com/components/navigation/command#searchactionfromkeydown)
+ * so typing into your trigger behaves like typing into `Command.SearchTrigger`.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/command#usecommanddialog
+ *
+ * @example
+ * ```tsx
+ * function SearchEverythingItem({ query }: { query: string }) {
+ *   const { openWithQuery } = useCommandDialog();
+ *   return (
+ *     <Command.Item onSelect={() => openWithQuery(query)}>
+ *       Search everything for “{query}”
+ *     </Command.Item>
+ *   );
+ * }
+ * ```
+ */
+declare function useCommandDialog(): CommandDialogState;
+//#endregion
 //#region src/components/command/meta-key.d.ts
 type Props = Omit<ComponentProps<"kbd">, "children">;
 /**
  * Renders the platform-appropriate meta key kbd (⌘ or ⌃).
  *
  * - Initializes to `"⌃"` to avoid SSR mismatch.
- * - Updates on mount using `detectMetaKey()`.
+ * - Updates on mount, once {@link useIsApplePlatform} has resolved the host.
  *
  * @see https://mantle.ngrok.com/components/navigation/command#metakey
  *
@@ -780,4 +1188,158 @@ type Props = Omit<ComponentProps<"kbd">, "children">;
  */
 declare function MetaKey({ className, ...props }: Props): import("react").JSX.Element;
 //#endregion
-export { Command, MetaKey, useCommandState };
+//#region src/components/command/search-action.d.ts
+/**
+ * What a keystroke or paste on a search trigger should do to the command
+ * palette. A search trigger looks like a text field but is a `<button>` — it
+ * has no editable value — so every input event it receives has to be
+ * classified before it can mean anything.
+ *
+ * Three outcomes, because "type into the trigger" has three honest answers:
+ *
+ * - `"seed"` — the event carried text. Open the palette with `query` already
+ *   in `Command.Input`.
+ * - `"open"` — the event was text *intent* that cannot be replayed (an IME
+ *   composition belongs to the element that started it). Open the palette with
+ *   an empty query so the next keystroke has a real text field to land in.
+ * - `"ignore"` — the event was navigation, a modifier chord, or the button's
+ *   own activation keys. Leave the palette alone.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/command#searchactionfromkeydown
+ *
+ * @example
+ * ```tsx
+ * const { openWithQuery } = useCommandDialog();
+ *
+ * const applyAction = (action: SearchAction) => {
+ *   switch (action.type) {
+ *     case "seed":
+ *       openWithQuery(action.query);
+ *       break;
+ *     case "open":
+ *       openWithQuery();
+ *       break;
+ *     case "ignore":
+ *       break;
+ *   }
+ * };
+ * ```
+ */
+type SearchAction = {
+  type: "seed";
+  /**
+   * The text to open the palette with. A single character for a keystroke,
+   * the pasted text (collapsed to one line) for a paste.
+   */
+  query: string;
+} | {
+  type: "open";
+} | {
+  type: "ignore";
+};
+/**
+ * The properties {@link searchActionFromKeyDown} reads. Satisfied by a native
+ * `KeyboardEvent` — pass `event.nativeEvent` from a React handler, since
+ * React's synthetic keyboard event does not carry `isComposing`.
+ */
+type SearchKeyDownEvent = {
+  altKey: boolean;
+  ctrlKey: boolean;
+  isComposing: boolean;
+  key: string;
+  /**
+   * Optional so a hand-built test event can omit it.
+   *
+   * Why a deprecated property: `229` is the only reliable marker for the
+   * keydown that *starts* an IME composition, where `isComposing` is still
+   * `false` and `key` varies by engine. There is no non-deprecated
+   * replacement — cmdk reads it for the same reason.
+   */
+  keyCode?: number;
+  metaKey: boolean;
+};
+/**
+ * The properties {@link searchActionFromPaste} reads. Satisfied by both a
+ * native `ClipboardEvent` and React's synthetic one.
+ */
+type SearchPasteEvent = {
+  clipboardData: Pick<DataTransfer, "getData"> | null;
+};
+/**
+ * Classifies a `keydown` on a search trigger. Pure, so the whole policy is
+ * testable without a DOM: see the {@link SearchAction} cases for what each
+ * outcome means.
+ *
+ * The policy, and why:
+ *
+ * - **IME composition → `"open"`.** A composition session is bound to the
+ *   element that started it and cannot be forwarded, so seeding is impossible;
+ *   opening empty at least lands the user in a real text field instead of
+ *   swallowing the keystroke. This is the case the blog's original trigger got
+ *   wrong — it silently did nothing for CJK input. Engines that route dead keys
+ *   through the IME path report them the same way (Chrome on macOS sends
+ *   `key: "Dead"` with `keyCode: 229` for `⌥e`), so those open empty too rather
+ *   than falling through to the named-key case below.
+ * - **Any of `⌘` / `Ctrl` / `Alt` held → `"ignore"`.** Those are shortcuts, not
+ *   text: the palette's own `⌘K`, `⌘V` (the paste path handles it), and the
+ *   browser/OS accelerators. `Alt` is excluded even though macOS `⌥` produces
+ *   real characters, because seeding one means calling `preventDefault()` on
+ *   Windows `Alt` accelerators (`Alt+D`, `Alt+Home`) — the worse trade.
+ *   `Shift` is not a modifier here; it is already reflected in `key`.
+ * - **`Enter` / `Space` → `"ignore"`.** The button's own activation keys.
+ * - **A single code point → `"seed"`.** Counted by spreading rather than
+ *   `.length`, so astral characters (emoji, less common CJK) count as one
+ *   instead of two and are not dropped. Every named key (`"Tab"`,
+ *   `"ArrowDown"`, `"Dead"`, `"Unidentified"`) is longer and falls through —
+ *   except when the engine also flags it as IME processing, which the case
+ *   above claims first.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/command#searchactionfromkeydown
+ *
+ * @example
+ * ```tsx
+ * <button
+ *   type="button"
+ *   onKeyDown={(event) => {
+ *     const action = searchActionFromKeyDown(event.nativeEvent);
+ *     if (action.type === "seed") {
+ *       event.preventDefault();
+ *       openWithQuery(action.query);
+ *     } else if (action.type === "open") {
+ *       openWithQuery();
+ *     }
+ *   }}
+ * >
+ *   Search…
+ * </button>
+ * ```
+ */
+declare function searchActionFromKeyDown(event: SearchKeyDownEvent): SearchAction;
+/**
+ * Classifies a `paste` on a search trigger. A paste is unambiguous search
+ * intent — the user pasted into a control that looks like a text field — so it
+ * always opens the palette, and seeds it whenever the clipboard holds text.
+ * Never returns `"ignore"`.
+ *
+ * The text is collapsed to a single space-separated line because the palette's
+ * query is a one-line field: pasting a multi-line selection should search for
+ * its words, not embed newlines that no item can match.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/command#searchactionfrompaste
+ *
+ * @example
+ * ```tsx
+ * <button
+ *   type="button"
+ *   onPaste={(event) => {
+ *     const action = searchActionFromPaste(event.nativeEvent);
+ *     openWithQuery(action.type === "seed" ? action.query : undefined);
+ *   }}
+ * >
+ *   Search…
+ * </button>
+ * ```
+ */
+declare function searchActionFromPaste(event: SearchPasteEvent): SearchAction;
+//#endregion
+export { Command, type CommandDialogRootProps, type CommandDialogState, type CommandSearchTriggerProps, MetaKey, type SearchAction, type SearchKeyDownEvent, type SearchPasteEvent, searchActionFromKeyDown, searchActionFromPaste, useCommandDialog, useCommandState };