@assistant-ui/mcp-docs-server 0.1.31 → 0.1.32

package/.docs/raw/docs/(reference)/api-reference/primitives/composer.mdx

@@ -1,17 +1,17 @@
 ---
 title: ComposerPrimitive
-description: Primitives for the text input, send button, and attachments.
+description: Composable input primitives for assistant-ui prompts, send controls, cancellation, attachments, and composer state.
 ---
 
-The user interface to add new messages or edit existing ones.
+import { ComposerPrimitiveAddAttachmentProps, ComposerPrimitiveAttachmentByIndexProps, ComposerPrimitiveAttachmentDropzoneProps, ComposerPrimitiveAttachmentsProps, ComposerPrimitiveCancelProps, ComposerPrimitiveDictateProps, ComposerPrimitiveDictationTranscriptProps, ComposerPrimitiveIfProps, ComposerPrimitiveInputProps, ComposerPrimitiveQueueProps, ComposerPrimitiveQuoteDismissProps, ComposerPrimitiveQuoteProps, ComposerPrimitiveQuoteTextProps, ComposerPrimitiveRootProps, ComposerPrimitiveSendProps, ComposerPrimitiveStopDictationProps, ComposerPrimitiveUnstable_TriggerPopoverBackProps, ComposerPrimitiveUnstable_TriggerPopoverCategoriesProps, ComposerPrimitiveUnstable_TriggerPopoverCategoryItemProps, ComposerPrimitiveUnstable_TriggerPopoverItemProps, ComposerPrimitiveUnstable_TriggerPopoverItemsProps, ComposerPrimitiveUnstable_TriggerPopoverProps, ComposerPrimitiveUnstable_TriggerPopoverRootProps } from "@/generated/typeDocs";
+import { ComposerPrimitive as ComposerPrimitiveDocs } from "@/generated/primitiveDocs";
 
+{/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
+{/* Do not edit manually. */}
 
+For examples and usage patterns, see [Composer](/docs/primitives/composer).
 
-<Callout>
-  **Dual Use!** A Composer placed directly inside a `Thread` will compose new
-  messages. A Composer placed inside a `Message` will edit that message.
-</Callout>
-
+{/* api-manual:start */}
 ## Anatomy
 
 ```tsx
@@ -56,81 +56,47 @@ const ComposerWithDictation = () => (
   </ComposerPrimitive.Root>
 );
 ```
+{/* api-manual:end */}
+
+{/* api-reference:start */}
+{/* AUTO-GENERATED by scripts/generate-api-reference.mts */}
+{/* Do not edit this block manually. */}
 
 ## API Reference
 
 ### Root
 
-Contains all parts of the composer.
+{ComposerPrimitiveDocs.Root?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.Root.deprecated}
+  </Callout>
+)}
 
-This primitive renders a `<form>` element unless `asChild` is set.
+{ComposerPrimitiveDocs.Root?.description}
 
-<ParametersTable
-  type="ComposerRootProps"
-  parameters={[
-    {
-      name: "asChild",
-    },
-  ]}
-/>
+{ComposerPrimitiveDocs.Root?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.Root?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
+
+<ParametersTable {...ComposerPrimitiveRootProps} />
 
 ### Input
 
-The text input field for the user to type a new message.
-
-This primitive renders a `<textarea>` element unless `asChild` is set.
-
-<ParametersTable
-  type="ComposerPrimitiveInputProps"
-  parameters={[
-    {
-      name: "asChild",
-    },
-    {
-      name: "submitMode",
-      type: '"enter" | "ctrlEnter" | "none"',
-      default: '"enter"',
-      description:
-        'Controls how the Enter key submits messages. "enter": plain Enter submits (Shift+Enter for newline). "ctrlEnter": Ctrl/Cmd+Enter submits (plain Enter for newline). "none": keyboard submission disabled.',
-    },
-    {
-      name: "cancelOnEscape",
-      type: "boolean",
-      default: "true",
-      description:
-        "Whether to cancel message composition when Escape is pressed.",
-    },
-    {
-      name: "unstable_focusOnRunStart",
-      type: "boolean",
-      default: "true",
-      description:
-        "Whether to automatically focus the input when a new run starts.",
-    },
-    {
-      name: "unstable_focusOnScrollToBottom",
-      type: "boolean",
-      default: "true",
-      description:
-        "Whether to automatically focus the input when scrolling to bottom.",
-    },
-    {
-      name: "unstable_focusOnThreadSwitched",
-      type: "boolean",
-      default: "true",
-      description:
-        "Whether to automatically focus the input when switching threads.",
-    },
-    {
-      name: "addAttachmentOnPaste",
-      type: "boolean",
-      default: "true",
-      description:
-        "Whether to automatically add pasted files as attachments.",
-    },
-  ]}
-/>
+{ComposerPrimitiveDocs.Input?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.Input.deprecated}
+  </Callout>
+)}
+
+{ComposerPrimitiveDocs.Input?.description}
 
+{ComposerPrimitiveDocs.Input?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.Input?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
+
+<ParametersTable {...ComposerPrimitiveInputProps} />
+
+{/* api-manual:ComposerPrimitive.Input:start */}
 #### Keyboard Shortcuts
 
 Default (`submitMode="enter"`):
@@ -149,506 +115,402 @@ With `submitMode="ctrlEnter"`:
 | <Kbd>Enter</Kbd> | Inserts a newline. |
 | <Kbd>Escape</Kbd> | Sends a cancel action. |
 
-### Send
+With `submitMode="none"`:
+
+| Key | Description |
+| --- | --- |
+| <Kbd>Enter</Kbd> | Inserts a newline (no keyboard submission). |
+| <Kbd>Escape</Kbd> | Sends a cancel action. |
 
-The button to send the message.
+#### Touch-primary devices
 
-This primitive renders a `<button>` element unless `asChild` is set.
+Pass `unstable_insertNewlineOnTouchEnter` to make plain Enter insert a newline on phones and tablets without a hardware keyboard, detected via the `(pointer: coarse) and (not (any-pointer: fine))` media query. Messages then dispatch only via the explicit Send button, matching the chat-input convention used by WhatsApp, Slack, Discord, iMessage, ChatGPT, and Claude.ai.
 
-<ParametersTable
-  type="ComposerPrimitiveSendProps"
-  parameters={[
-    {
-      name: "asChild",
-    },
-  ]}
+```tsx
+<ComposerPrimitive.Input
+  placeholder="Ask anything..."
+  unstable_insertNewlineOnTouchEnter
 />
+```
 
-### Cancel
+Only takes effect when `submitMode` resolves to `"enter"` (the default); `"ctrlEnter"` and `"none"` are unchanged, so a tablet paired with a hardware keyboard can still submit via Cmd/Ctrl+Enter.
+{/* api-manual:ComposerPrimitive.Input:end */}
 
-Sends a cancel action.
+### Send
 
-In edit composers, this action exits the edit mode.
-In thread composers, this action stops the current run.
+{ComposerPrimitiveDocs.Send?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.Send.deprecated}
+  </Callout>
+)}
 
-This primitive renders a `<button>` element unless `asChild` is set.
+{ComposerPrimitiveDocs.Send?.description}
 
-<ParametersTable
-  type="ComposerPrimitiveCancelProps"
-  parameters={[
-    {
-      name: "asChild",
-    },
-  ]}
-/>
+{ComposerPrimitiveDocs.Send?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.Send?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-### Attachments
+<ParametersTable {...ComposerPrimitiveSendProps} />
 
-Renders attachments. This primitive renders a separate component for each attachment.
-
-<ParametersTable
-  type="ComposerPrimitiveAttachmentsProps"
-  parameters={[
-    {
-      name: "components",
-      type: "ComposerAttachmentsComponents",
-      description: "The component to render for each attachment.",
-      children: [
-        {
-          type: "ComposerPrimitiveAttachmentsProps['components']",
-          parameters: [
-            {
-              name: "Image",
-              type: "ComponentType",
-              description: "The component to render for each image attachment.",
-            },
-            {
-              name: "Document",
-              type: "ComponentType",
-              description:
-                "The component to render for each document attachment.",
-            },
-            {
-              name: "File",
-              type: "ComponentType",
-              description: "The component to render for each file attachment.",
-            },
-            {
-              name: "Attachment",
-              type: "ComponentType",
-              description: "The fallback component to render for each attachment type.",
-            },
-          ],
-        },
-      ],
-    },
-  ]}
-/>
+### Cancel
 
-### AttachmentByIndex
+{ComposerPrimitiveDocs.Cancel?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.Cancel.deprecated}
+  </Callout>
+)}
 
-Renders a single attachment at the specified index within the composer.
+{ComposerPrimitiveDocs.Cancel?.description}
 
-```tsx
-<ComposerPrimitive.AttachmentByIndex
-  index={0}
-  components={{
-    Image: MyImageAttachment,
-    Document: MyDocumentAttachment
-  }}
-/>
-```
+{ComposerPrimitiveDocs.Cancel?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.Cancel?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-<ParametersTable
-  type="ComposerPrimitive.AttachmentByIndex.Props"
-  parameters={[
-    {
-      name: "index",
-      type: "number",
-      required: true,
-      description: "The index of the attachment to render.",
-    },
-    {
-      name: "components",
-      type: "ComposerAttachmentsComponents",
-      description: "The components to render for the attachment.",
-    },
-  ]}
-/>
+<ParametersTable {...ComposerPrimitiveCancelProps} />
 
 ### AddAttachment
 
-Renders a button to add an attachment.
-
-This primitive renders a `<button>` element unless `asChild` is set.
-
-<ParametersTable
-  type="ComposerPrimitiveAddAttachmentProps"
-  parameters={[
-    {
-      name: "asChild",
-    },
-    {
-      name: "multiple",
-      type: "boolean | undefined",
-      description: "Allow selecting multiple attachments at the same time.",
-      default: "true",
-    },
-  ]}
-/>
+{ComposerPrimitiveDocs.AddAttachment?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.AddAttachment.deprecated}
+  </Callout>
+)}
 
-### AttachmentDropzone
+{ComposerPrimitiveDocs.AddAttachment?.description}
 
-A drag-and-drop zone that accepts file drops and adds them as attachments to the composer.
+{ComposerPrimitiveDocs.AddAttachment?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.AddAttachment?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-When a file is dragged over the zone, a `data-dragging="true"` attribute is set on the element, which can be used for styling the active drag state.
+<ParametersTable {...ComposerPrimitiveAddAttachmentProps} />
 
-This primitive renders a `<div>` element unless `asChild` is set.
+### Attachments
 
-```tsx
-<ComposerPrimitive.AttachmentDropzone className="relative data-[dragging]:ring-2">
-  <ComposerPrimitive.Input />
-  <ComposerPrimitive.Send />
-</ComposerPrimitive.AttachmentDropzone>
-```
+{ComposerPrimitiveDocs.Attachments?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.Attachments.deprecated}
+  </Callout>
+)}
 
-<ParametersTable
-  type="ComposerPrimitiveAttachmentDropzoneProps"
-  parameters={[
-    {
-      name: "asChild",
-    },
-    {
-      name: "disabled",
-      type: "boolean | undefined",
-      description: "When true, drag-and-drop is disabled and files will not be added on drop.",
-    },
-  ]}
-/>
+{ComposerPrimitiveDocs.Attachments?.description}
 
-### Dictate
+{ComposerPrimitiveDocs.Attachments?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.Attachments?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-Renders a button to start dictation to convert voice to text.
+<ParametersTable {...ComposerPrimitiveAttachmentsProps} />
 
-Requires a `DictationAdapter` to be configured in the runtime.
+### AttachmentByIndex
 
-This primitive renders a `<button>` element unless `asChild` is set.
+{ComposerPrimitiveDocs.AttachmentByIndex?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.AttachmentByIndex.deprecated}
+  </Callout>
+)}
 
-<ParametersTable
-  type="ComposerPrimitiveDictateProps"
-  parameters={[
-    {
-      name: "asChild",
-    },
-  ]}
-/>
+{ComposerPrimitiveDocs.AttachmentByIndex?.description}
 
-### StopDictation
+{ComposerPrimitiveDocs.AttachmentByIndex?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.AttachmentByIndex?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-Renders a button to stop the current dictation session.
+<ParametersTable {...ComposerPrimitiveAttachmentByIndexProps} />
 
-Only rendered when dictation is active.
+### AttachmentDropzone
 
-This primitive renders a `<button>` element unless `asChild` is set.
+{ComposerPrimitiveDocs.AttachmentDropzone?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.AttachmentDropzone.deprecated}
+  </Callout>
+)}
 
-<ParametersTable
-  type="ComposerPrimitiveStopDictationProps"
-  parameters={[
-    {
-      name: "asChild",
-    },
-  ]}
-/>
+{ComposerPrimitiveDocs.AttachmentDropzone?.description}
 
-### DictationTranscript
+{ComposerPrimitiveDocs.AttachmentDropzone?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.AttachmentDropzone?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-Renders the current interim (partial) transcript while dictation is active.
+<ParametersTable {...ComposerPrimitiveAttachmentDropzoneProps} />
 
-<Callout type="info">
-**Note:** By default, interim transcripts are displayed directly in the composer input (like native dictation).
-This component is for **advanced customization** when you want to display the interim transcript separately (e.g., in a different style or location).
-</Callout>
+{/* api-manual:ComposerPrimitive.AttachmentDropzone:start */}
+| Data attribute | Values |
+| --- | --- |
+| `[data-dragging]` | Present while a file is being dragged over the dropzone. |
+{/* api-manual:ComposerPrimitive.AttachmentDropzone:end */}
 
-Only renders when there is an active interim transcript (returns `null` otherwise).
+### Dictate
 
-This primitive renders a `<span>` element.
+{ComposerPrimitiveDocs.Dictate?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.Dictate.deprecated}
+  </Callout>
+)}
 
-```tsx
-{/* Optional: Display interim transcript separately with custom styling */}
-<AuiIf condition={(s) => s.composer.dictation != null}>
-  <div className="dictation-preview">
-    <ComposerPrimitive.DictationTranscript className="italic text-muted" />
-  </div>
-</AuiIf>
-```
+{ComposerPrimitiveDocs.Dictate?.description}
 
-### Quote
+{ComposerPrimitiveDocs.Dictate?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.Dictate?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-A container for displaying a quote preview in the composer. Only renders when a quote is set via `composer.setQuote()`.
+<ParametersTable {...ComposerPrimitiveDictateProps} />
 
-This primitive renders a `<div>` element.
+### StopDictation
 
-```tsx
-<ComposerPrimitive.Quote className="flex items-start gap-2 bg-muted/60 px-3 py-2">
-  <ComposerPrimitive.QuoteText className="line-clamp-2 flex-1 text-sm" />
-  <ComposerPrimitive.QuoteDismiss>×</ComposerPrimitive.QuoteDismiss>
-</ComposerPrimitive.Quote>
-```
+{ComposerPrimitiveDocs.StopDictation?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.StopDictation.deprecated}
+  </Callout>
+)}
 
-### QuoteText
+{ComposerPrimitiveDocs.StopDictation?.description}
 
-Renders the quoted text content. Only renders when a quote is set.
+{ComposerPrimitiveDocs.StopDictation?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.StopDictation?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-This primitive renders a `<span>` element.
+<ParametersTable {...ComposerPrimitiveStopDictationProps} />
 
-### QuoteDismiss
+### DictationTranscript
 
-A button that clears the current quote from the composer by calling `setQuote(undefined)`.
+{ComposerPrimitiveDocs.DictationTranscript?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.DictationTranscript.deprecated}
+  </Callout>
+)}
 
-This primitive renders a `<button>` element unless `asChild` is set.
+{ComposerPrimitiveDocs.DictationTranscript?.description}
 
-<ParametersTable
-  type="ComposerPrimitiveQuoteDismissProps"
-  parameters={[
-    {
-      name: "asChild",
-    },
-  ]}
-/>
+{ComposerPrimitiveDocs.DictationTranscript?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.DictationTranscript?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-<Callout type="info">
-See the [Quoting guide](/docs/guides/quoting) for a complete walkthrough including the floating selection toolbar and backend handling.
-</Callout>
+<ParametersTable {...ComposerPrimitiveDictationTranscriptProps} />
 
-### Conditional Rendering
+### If
 
-Use `AuiIf` for conditional rendering based on composer state:
+{ComposerPrimitiveDocs.If?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.If.deprecated}
+  </Callout>
+)}
 
-```tsx
-import { AuiIf } from "@assistant-ui/react";
+{ComposerPrimitiveDocs.If?.description}
 
-<AuiIf condition={(s) => s.composer.isEditing}>
-  {/* rendered if message is being edited */}
-</AuiIf>
+{ComposerPrimitiveDocs.If?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.If?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-<AuiIf condition={(s) => s.composer.dictation != null}>
-  {/* rendered if dictation is active */}
-</AuiIf>
-```
+<ParametersTable {...ComposerPrimitiveIfProps} />
 
-## Trigger Popover Primitives (Unstable)
+### Quote
 
-<Callout type="warn">
-  These primitives are under the `Unstable_` prefix and may change without notice.
-</Callout>
+{ComposerPrimitiveDocs.Quote?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.Quote.deprecated}
+  </Callout>
+)}
 
-Unified primitives for any character-triggered popover (`@` mentions, `/` slash commands, `:` emoji, etc.). Multiple triggers coexist under a single `TriggerPopoverRoot`. See the [Mentions guide](/docs/guides/mentions) and [Slash Commands guide](/docs/guides/slash-commands) for full documentation and the [ComposerTriggerPopover component](/docs/ui/composer-trigger-popover) for a pre-built implementation.
+{ComposerPrimitiveDocs.Quote?.description}
 
-### Anatomy
+{ComposerPrimitiveDocs.Quote?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.Quote?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-```tsx
-import { ComposerPrimitive } from "@assistant-ui/react";
-import { unstable_defaultDirectiveFormatter } from "@assistant-ui/core";
+<ParametersTable {...ComposerPrimitiveQuoteProps} />
 
-const Composer = () => (
-  <ComposerPrimitive.Unstable_TriggerPopoverRoot>
-    <ComposerPrimitive.Root>
-      <ComposerPrimitive.Input />
+### QuoteText
 
-      <ComposerPrimitive.Unstable_TriggerPopover
-        char="@"
-        adapter={mention.adapter}
-      >
-        <ComposerPrimitive.Unstable_TriggerPopover.Directive
-          {...mention.directive}
-        />
-        <ComposerPrimitive.Unstable_TriggerPopoverCategories>
-          {(categories) =>
-            categories.map((cat) => (
-              <ComposerPrimitive.Unstable_TriggerPopoverCategoryItem
-                key={cat.id}
-                categoryId={cat.id}
-              >
-                {cat.label}
-              </ComposerPrimitive.Unstable_TriggerPopoverCategoryItem>
-            ))
-          }
-        </ComposerPrimitive.Unstable_TriggerPopoverCategories>
-        <ComposerPrimitive.Unstable_TriggerPopoverItems>
-          {(items) =>
-            items.map((item) => (
-              <ComposerPrimitive.Unstable_TriggerPopoverItem
-                key={item.id}
-                item={item}
-              >
-                {item.label}
-              </ComposerPrimitive.Unstable_TriggerPopoverItem>
-            ))
-          }
-        </ComposerPrimitive.Unstable_TriggerPopoverItems>
-        <ComposerPrimitive.Unstable_TriggerPopoverBack>
-          Back
-        </ComposerPrimitive.Unstable_TriggerPopoverBack>
-      </ComposerPrimitive.Unstable_TriggerPopover>
-    </ComposerPrimitive.Root>
-  </ComposerPrimitive.Unstable_TriggerPopoverRoot>
-);
-```
+{ComposerPrimitiveDocs.QuoteText?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.QuoteText.deprecated}
+  </Callout>
+)}
 
-### Unstable_TriggerPopoverRoot
+{ComposerPrimitiveDocs.QuoteText?.description}
 
-Root provider that groups one or more `TriggerPopover` declarations. Owns the shared `ComposerInputPluginRegistry` that routes cursor and keyboard events to each registered trigger.
+{ComposerPrimitiveDocs.QuoteText?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.QuoteText?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-No props.
+<ParametersTable {...ComposerPrimitiveQuoteTextProps} />
 
-### Unstable_TriggerPopover
+### QuoteDismiss
 
-Declares a trigger and renders its popover container. Only renders its DOM (and children) while this trigger is active in the composer input. Each declaration has an isolated scope — sub-primitives placed inside read state from this declaration only.
+{ComposerPrimitiveDocs.QuoteDismiss?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.QuoteDismiss.deprecated}
+  </Callout>
+)}
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `char` | `string` | — | Character(s) that activate the trigger (e.g. `"@"`, `"/"`) — unique within the root |
-| `adapter` | `Unstable_TriggerAdapter` | — | Provides categories, items, and search |
+{ComposerPrimitiveDocs.QuoteDismiss?.description}
 
-Selection behavior is declared by rendering **exactly one** behavior sub-primitive inside the `TriggerPopover`:
+{ComposerPrimitiveDocs.QuoteDismiss?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.QuoteDismiss?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-- [`Unstable_TriggerPopover.Directive`](#unstable_triggerpopoverdirective) — inserts `:type[label]{name=id}` into the composer on selection (mention behavior).
-- [`Unstable_TriggerPopover.Action`](#unstable_triggerpopoveraction) — fires `onExecute` on selection; leaves a directive chip as an audit trail by default.
+<ParametersTable {...ComposerPrimitiveQuoteDismissProps} />
 
-Renders a `<div>` with `role="listbox"` when open.
+### Queue
 
-### Unstable_TriggerPopover.Directive
+{ComposerPrimitiveDocs.Queue?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.Queue.deprecated}
+  </Callout>
+)}
 
-Behavior sub-primitive. Placed inside a `<Unstable_TriggerPopover>`. Renders nothing — registers an `"directive"` behavior with its parent. Exactly one behavior sub-primitive is allowed per `TriggerPopover`.
+{ComposerPrimitiveDocs.Queue?.description}
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `formatter` | `Unstable_DirectiveFormatter` | `unstable_defaultDirectiveFormatter` | Serializes the selected item into composer text (and parses it back). |
-| `onInserted` | `(item) => void` | — | Fires after the directive text has been inserted. |
+{ComposerPrimitiveDocs.Queue?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.Queue?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-### Unstable_TriggerPopover.Action
+<ParametersTable {...ComposerPrimitiveQueueProps} />
 
-Behavior sub-primitive. Placed inside a `<Unstable_TriggerPopover>`. Renders nothing — registers an `"action"` behavior with its parent. Exactly one behavior sub-primitive is allowed per `TriggerPopover`.
+### Unstable_TriggerPopover
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `formatter` | `Unstable_DirectiveFormatter` | `unstable_defaultDirectiveFormatter` | Serializes the audit-trail chip (unused when `removeOnExecute` is true). |
-| `onExecute` | `(item) => void` | — | Called the moment an item is selected — typically routes to a handler map. Required. |
-| `removeOnExecute` | `boolean` | `false` | When `true`, strips the trigger text from the composer instead of leaving a chip. |
+{ComposerPrimitiveDocs.Unstable_TriggerPopover?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.Unstable_TriggerPopover.deprecated}
+  </Callout>
+)}
 
-### Unstable_TriggerBehavior
+{ComposerPrimitiveDocs.Unstable_TriggerPopover?.description}
 
-Union type returned by the two behavior sub-primitives and consumed internally by the popover resources. Exported for advanced use cases (e.g. custom sub-primitives).
+{ComposerPrimitiveDocs.Unstable_TriggerPopover?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.Unstable_TriggerPopover?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-```ts
-import type { Unstable_TriggerBehavior } from "@assistant-ui/react";
+<ParametersTable {...ComposerPrimitiveUnstable_TriggerPopoverProps} />
 
-// Equivalent shape:
-// Unstable_TriggerBehavior =
-//   | { kind: "directive"; formatter: Unstable_DirectiveFormatter; onInserted?: (item) => void }
-//   | { kind: "action"; formatter: Unstable_DirectiveFormatter; onExecute: (item) => void; removeOnExecute?: boolean }
-```
+{/* api-manual:ComposerPrimitive.Unstable_TriggerPopover:start */}
+| Data attribute | Values |
+| --- | --- |
+| `[data-state]` | `"open"` when the trigger popover is open. |
+{/* api-manual:ComposerPrimitive.Unstable_TriggerPopover:end */}
+
+### Unstable_TriggerPopoverRoot
+
+{ComposerPrimitiveDocs.Unstable_TriggerPopoverRoot?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.Unstable_TriggerPopoverRoot.deprecated}
+  </Callout>
+)}
+
+{ComposerPrimitiveDocs.Unstable_TriggerPopoverRoot?.description}
+
+{ComposerPrimitiveDocs.Unstable_TriggerPopoverRoot?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.Unstable_TriggerPopoverRoot?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
+
+<ParametersTable {...ComposerPrimitiveUnstable_TriggerPopoverRootProps} />
 
 ### Unstable_TriggerPopoverCategories
 
-Renders the top-level category list. Accepts a render function `(categories) => ReactNode`. Hidden when a category is selected or when in search mode.
+{ComposerPrimitiveDocs.Unstable_TriggerPopoverCategories?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.Unstable_TriggerPopoverCategories.deprecated}
+  </Callout>
+)}
+
+{ComposerPrimitiveDocs.Unstable_TriggerPopoverCategories?.description}
+
+{ComposerPrimitiveDocs.Unstable_TriggerPopoverCategories?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.Unstable_TriggerPopoverCategories?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
+
+<ParametersTable {...ComposerPrimitiveUnstable_TriggerPopoverCategoriesProps} />
 
 ### Unstable_TriggerPopoverCategoryItem
 
-A button that drills into a category. Renders `role="option"` with automatic `data-highlighted` and `aria-selected` when keyboard-navigated.
+{ComposerPrimitiveDocs.Unstable_TriggerPopoverCategoryItem?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.Unstable_TriggerPopoverCategoryItem.deprecated}
+  </Callout>
+)}
 
-| Prop | Type | Description |
-| --- | --- | --- |
-| `categoryId` | `string` | The category to select on click |
+{ComposerPrimitiveDocs.Unstable_TriggerPopoverCategoryItem?.description}
 
-### Unstable_TriggerPopoverItems
+{ComposerPrimitiveDocs.Unstable_TriggerPopoverCategoryItem?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.Unstable_TriggerPopoverCategoryItem?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-Renders the item list for the active category or search results. Accepts a render function `(items) => ReactNode`. Hidden when no category is selected and not in search mode.
+<ParametersTable {...ComposerPrimitiveUnstable_TriggerPopoverCategoryItemProps} />
 
-### Unstable_TriggerPopoverItem
+{/* api-manual:ComposerPrimitive.Unstable_TriggerPopoverCategoryItem:start */}
+| Data attribute | Values |
+| --- | --- |
+| `[data-highlighted]` | Present when keyboard-highlighted. |
+{/* api-manual:ComposerPrimitive.Unstable_TriggerPopoverCategoryItem:end */}
 
-A button that selects an item. Renders `role="option"` with automatic `data-highlighted` and `aria-selected` when keyboard-navigated.
+### Unstable_TriggerPopoverItems
 
-| Prop | Type | Description |
-| --- | --- | --- |
-| `item` | `Unstable_TriggerItem` | The item to select on click |
-| `index` | `number` | Optional index override for highlight matching |
+{ComposerPrimitiveDocs.Unstable_TriggerPopoverItems?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.Unstable_TriggerPopoverItems.deprecated}
+  </Callout>
+)}
 
-### Unstable_TriggerPopoverBack
+{ComposerPrimitiveDocs.Unstable_TriggerPopoverItems?.description}
 
-A button that navigates back from items to the category list. Only renders when a category is active.
+{ComposerPrimitiveDocs.Unstable_TriggerPopoverItems?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.Unstable_TriggerPopoverItems?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-### unstable_useTriggerPopoverScopeContext
+<ParametersTable {...ComposerPrimitiveUnstable_TriggerPopoverItemsProps} />
 
-Hook to access the popover state and actions for the nearest enclosing `Unstable_TriggerPopover`.
+### Unstable_TriggerPopoverItem
 
-```tsx
-const {
-  open,           // boolean — whether popover is visible
-  query,          // string — text after the trigger character
-  isSearchMode,   // boolean — whether showing search results
-  highlightedIndex,
-  categories,
-  items,
-  activeCategoryId,
-  selectCategory,
-  selectItem,
-  goBack,
-  close,
-  handleKeyDown,
-} = unstable_useTriggerPopoverScopeContext();
-```
+{ComposerPrimitiveDocs.Unstable_TriggerPopoverItem?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.Unstable_TriggerPopoverItem.deprecated}
+  </Callout>
+)}
 
-### unstable_useTriggerPopoverTriggers
+{ComposerPrimitiveDocs.Unstable_TriggerPopoverItem?.description}
 
-Hook to iterate every trigger registered under the current `Unstable_TriggerPopoverRoot`. Intended for input-level integrations (e.g. Lexical `DirectivePlugin`). Returns `ReadonlyMap<string, Unstable_RegisteredTrigger>`.
+{ComposerPrimitiveDocs.Unstable_TriggerPopoverItem?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.Unstable_TriggerPopoverItem?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-### unstable_useMentionAdapter
+<ParametersTable {...ComposerPrimitiveUnstable_TriggerPopoverItemProps} />
 
-Returns a spreadable `{ adapter, directive }` bundle for `@` mentions. Reads tools registered via `useAssistantTool`, accepts explicit `items`, and supports multi-category drill-down.
+{/* api-manual:ComposerPrimitive.Unstable_TriggerPopoverItem:start */}
+| Data attribute | Values |
+| --- | --- |
+| `[data-highlighted]` | Present when keyboard-highlighted. |
+{/* api-manual:ComposerPrimitive.Unstable_TriggerPopoverItem:end */}
 
-```tsx
-import {
-  unstable_useMentionAdapter,
-  type Unstable_Mention,
-} from "@assistant-ui/react";
-
-function MyComposer() {
-  // Default: tools from model context as a single "Tools" category
-  const mention = unstable_useMentionAdapter();
-
-  return (
-    <ComposerTriggerPopover char="@" {...mention} />
-  );
-}
-```
+### Unstable_TriggerPopoverBack
 
-```tsx
-// Multi-category + tools appended as their own category
-const mention = unstable_useMentionAdapter({
-  categories: [
-    { id: "users", label: "Users", items: [/* ... */] },
-    { id: "files", label: "Files", items: [/* ... */] },
-  ],
-  includeModelContextTools: true,
-});
-```
+{ComposerPrimitiveDocs.Unstable_TriggerPopoverBack?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.Unstable_TriggerPopoverBack.deprecated}
+  </Callout>
+)}
 
-Options:
+{ComposerPrimitiveDocs.Unstable_TriggerPopoverBack?.description}
 
-| Option | Type | Description |
-| --- | --- | --- |
-| `items` | `Unstable_Mention[]` | Flat list; ignored when `categories` is set. |
-| `categories` | `{ id, label, items: Unstable_Mention[] }[]` | Drill-down groups. |
-| `includeModelContextTools` | `boolean \| { category?, formatLabel?, icon? }` | Tools integration. Defaults to `true` iff neither `items` nor `categories`. |
-| `formatter` | `Unstable_DirectiveFormatter` | Override directive serialization. |
-| `onInserted` | `(item) => void` | Fires after the directive is inserted. |
-| `iconMap` | `Record<string, Unstable_IconComponent>` | `metadata.icon` / category id → React component. |
-| `fallbackIcon` | `Unstable_IconComponent` | Fallback when no `iconMap` entry matches. |
+{ComposerPrimitiveDocs.Unstable_TriggerPopoverBack?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.Unstable_TriggerPopoverBack?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-Returns `{ adapter, directive, iconMap?, fallbackIcon? }`.
+<ParametersTable {...ComposerPrimitiveUnstable_TriggerPopoverBackProps} />
 
-### unstable_useSlashCommandAdapter
+### Unstable_RegisteredTrigger
 
-Returns a spreadable `{ adapter, action }` bundle for slash commands. Commands are declared as data + inline `execute` callbacks; `execute` lives in the hook closure and is never attached to the returned `Unstable_TriggerItem`, keeping items JSON-serializable.
+{ComposerPrimitiveDocs.Unstable_RegisteredTrigger?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.Unstable_RegisteredTrigger.deprecated}
+  </Callout>
+)}
 
-```tsx
-import {
-  unstable_useSlashCommandAdapter,
-  type Unstable_SlashCommand,
-} from "@assistant-ui/react";
-
-const SLASH_COMMANDS: readonly Unstable_SlashCommand[] = [
-  { id: "summarize", execute: () => runSummarize(), icon: "FileText" },
-  { id: "translate", execute: () => runTranslate(), icon: "Languages" },
-];
-
-function MyComposer() {
-  const slash = unstable_useSlashCommandAdapter({ commands: SLASH_COMMANDS });
-  return (
-    <ComposerTriggerPopover char="/" {...slash} />
-  );
-}
-```
+{ComposerPrimitiveDocs.Unstable_RegisteredTrigger?.description}
+
+{ComposerPrimitiveDocs.Unstable_RegisteredTrigger?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.Unstable_RegisteredTrigger?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
 
-Pass `removeOnExecute: true` on the hook options to strip the trigger text from the composer after executing. The hook also accepts `iconMap` / `fallbackIcon` options that flow into the returned bundle — `{...slash}` spreads them into `ComposerTriggerPopover`.
+{ComposerPrimitiveDocs.Unstable_RegisteredTrigger?.props && (
+  <ParametersTable type={ComposerPrimitiveDocs.Unstable_RegisteredTrigger?.element} parameters={ComposerPrimitiveDocs.Unstable_RegisteredTrigger.props} />
+)}
+{/* api-reference:end */}