@assistant-ui/mcp-docs-server 0.1.29 → 0.1.30

package/.docs/raw/docs/(docs)/guides/slash-commands.mdx

@@ -3,63 +3,68 @@ title: Slash Commands
 description: Let users type / in the composer to trigger predefined actions from a popover picker.
 ---
 
-Slash commands let users type `/` in the composer to open a popover, browse available commands, and execute one. Unlike [mentions](/docs/guides/mentions) (which insert text into the message), slash commands trigger **actions** — the `/command` text is removed from the composer and a callback fires.
+Slash commands let users type `/` in the composer to open a popover, browse available commands, and execute one. Unlike [mentions](/docs/guides/mentions) (which only insert a directive into the message), slash commands additionally fire an **action callback** at the moment of selection.
 
 ## How It Works
 
 ```
 User types "/"  →  Trigger detected  →  Adapter provides commands
                                               ↓
-              Command executed  ←  User selects command from popover
+              Callback fired  ←  User selects command from popover
                    ↓
-        "/command" text removed from composer
+       Directive chip left in composer (or removed if removeOnExecute)
 ```
 
-The slash command system is built on the same [trigger popover architecture](#trigger-popover-architecture) as mentions. It has two layers:
+The slash command system is built on the same [trigger popover architecture](#trigger-popover-architecture) as mentions. A slash command declares its behavior with a `<TriggerPopover.Action>` sub-primitive whose `onExecute` callback fires when an item is chosen.
 
-1. **Adapter** — provides the list of available commands (flat list by default, or categorized for advanced use)
-2. **SlashCommandRoot** — a convenience wrapper that pre-configures the trigger character (`/`) and action-based select behavior
+By default `Action` leaves a directive chip in the composer — giving the user (and the LLM) an audit trail of which commands were invoked. Pass `removeOnExecute` to strip the `/command` text entirely.
 
 ## Quick Start
 
-### 1. Define Commands
+### 1. Define Commands with `unstable_useSlashCommandAdapter`
+
+Declare commands (data + `execute` bundled together, like `useAssistantTool`). The hook returns `{ adapter, action }` — wire both into a single `<TriggerPopover>`:
 
 ```tsx
 import {
-  unstable_useSlashCommandAdapter,
   ComposerPrimitive,
+  unstable_useSlashCommandAdapter,
+  type Unstable_SlashCommand,
 } from "@assistant-ui/react";
 
-// Define commands outside the component for a stable reference
-const COMMANDS = [
+const SLASH_COMMANDS: readonly Unstable_SlashCommand[] = [
   {
-    name: "summarize",
+    id: "summarize",
     description: "Summarize the conversation",
     execute: () => console.log("Summarize!"),
   },
   {
-    name: "translate",
+    id: "translate",
     description: "Translate text to another language",
     execute: () => console.log("Translate!"),
   },
   {
-    name: "help",
+    id: "help",
     description: "List all available commands",
+    execute: () => console.log("Help!"),
   },
 ];
 
 function MyComposer() {
-  const slashAdapter = unstable_useSlashCommandAdapter({
-    commands: COMMANDS,
-  });
+  const slash = unstable_useSlashCommandAdapter({ commands: SLASH_COMMANDS });
 
   return (
-    <ComposerPrimitive.Unstable_SlashCommandRoot adapter={slashAdapter}>
+    <ComposerPrimitive.Unstable_TriggerPopoverRoot>
       <ComposerPrimitive.Root>
         <ComposerPrimitive.Input placeholder="Type / for commands..." />
         <ComposerPrimitive.Send>Send</ComposerPrimitive.Send>
 
-        <ComposerPrimitive.Unstable_TriggerPopoverPopover className="popover">
+        <ComposerPrimitive.Unstable_TriggerPopover
+          char="/"
+          adapter={slash.adapter}
+          className="popover"
+        >
+          <ComposerPrimitive.Unstable_TriggerPopover.Action {...slash.action} />
           <ComposerPrimitive.Unstable_TriggerPopoverItems>
             {(items) =>
               items.map((item, index) => (
@@ -75,49 +80,49 @@ function MyComposer() {
               ))
             }
           </ComposerPrimitive.Unstable_TriggerPopoverItems>
-        </ComposerPrimitive.Unstable_TriggerPopoverPopover>
+        </ComposerPrimitive.Unstable_TriggerPopover>
       </ComposerPrimitive.Root>
-    </ComposerPrimitive.Unstable_SlashCommandRoot>
+    </ComposerPrimitive.Unstable_TriggerPopoverRoot>
   );
 }
 ```
 
-### 2. Handle Command Selection
+The label defaults to `/${id}`; override via `label` on the command. Icons are strings that your `iconMap` on the picker UI resolves to components (see [ComposerTriggerPopover](/docs/ui/composer-trigger-popover)).
 
-There are two ways to handle command execution:
+### 2. Controlling the Chip
 
-**Via `execute` on each item** — define the action inline in the command definition:
+By default, a selected `/summarize` is converted into a directive chip (`:command[/summarize]{name=summarize}`) in the composer text and the command's `execute` fires. This keeps an audit trail of which commands were invoked.
 
-```ts
-{ name: "summarize", execute: () => runSummarize() }
+To strip the trigger text entirely — useful for purely transient commands — pass `removeOnExecute` on the hook options:
+
+```tsx
+const slash = unstable_useSlashCommandAdapter({
+  commands: SLASH_COMMANDS,
+  removeOnExecute: true,
+});
 ```
 
-**Via `onSelect` prop** — handle all commands in one place:
+### 3. Custom Dispatch
+
+For side effects on top of `execute` (logging, analytics, intercept), wrap the hook's `onExecute`:
 
 ```tsx
-<ComposerPrimitive.Unstable_SlashCommandRoot
-  adapter={slashAdapter}
-  onSelect={(item) => {
-    switch (item.id) {
-      case "summarize": runSummarize(); break;
-      case "translate": runTranslate(); break;
-    }
+<ComposerPrimitive.Unstable_TriggerPopover.Action
+  onExecute={(item) => {
+    logCommandUsed(item.id);
+    slash.action.onExecute(item);
   }}
->
+/>
 ```
 
-Both `execute` and `onSelect` fire when a command is selected. Use whichever pattern fits your code.
-
-## Custom Adapter
-
-The `unstable_useSlashCommandAdapter` hook uses a **flat list** — all commands show immediately when `/` is typed, with search filtering as the user types. This is the recommended UX for most cases.
+## Categorized Commands
 
-For **categorized navigation** (drill-down into groups), build the adapter manually. Return categories from `categories()` and items from `categoryItems()`. The popover will show categories first, then items within the selected category:
+For **categorized navigation** (drill-down into groups), return categories from `categories()` and items from `categoryItems()`. The popover shows categories first, then items within the selected category:
 
 ```ts
-import type { Unstable_SlashCommandAdapter } from "@assistant-ui/core";
+import type { Unstable_TriggerAdapter } from "@assistant-ui/core";
 
-const adapter: Unstable_SlashCommandAdapter = {
+const adapter: Unstable_TriggerAdapter = {
   categories() {
     return [
       { id: "actions", label: "Actions" },
@@ -155,7 +160,19 @@ const adapter: Unstable_SlashCommandAdapter = {
 When using a categorized adapter, add `TriggerPopoverCategories` to your popover UI:
 
 ```tsx
-<ComposerPrimitive.Unstable_TriggerPopoverPopover>
+const commandHandlers: Record<string, () => void> = {
+  summarize: () => {/* ... */},
+  pdf: () => {/* ... */},
+};
+
+<ComposerPrimitive.Unstable_TriggerPopover
+  char="/"
+  adapter={adapter}
+>
+  <ComposerPrimitive.Unstable_TriggerPopover.Action
+    formatter={unstable_defaultDirectiveFormatter}
+    onExecute={(item) => commandHandlers[item.id]?.()}
+  />
   <ComposerPrimitive.Unstable_TriggerPopoverBack>← Back</ComposerPrimitive.Unstable_TriggerPopoverBack>
   <ComposerPrimitive.Unstable_TriggerPopoverCategories>
     {(categories) => categories.map((cat) => (
@@ -171,54 +188,53 @@ When using a categorized adapter, add `TriggerPopoverCategories` to your popover
       </ComposerPrimitive.Unstable_TriggerPopoverItem>
     ))}
   </ComposerPrimitive.Unstable_TriggerPopoverItems>
-</ComposerPrimitive.Unstable_TriggerPopoverPopover>
+</ComposerPrimitive.Unstable_TriggerPopover>
 ```
 
 ## Combining with Mentions
 
-Slash commands and mentions can coexist on the same composer. Nest both roots — the [plugin protocol](#trigger-popover-architecture) ensures they don't conflict:
+Slash commands and mentions live under the same `TriggerPopoverRoot`. Declare one `TriggerPopover` per trigger — each with its own behavior sub-primitive:
 
 ```tsx
-<ComposerPrimitive.Unstable_MentionRoot adapter={mentionAdapter}>
-  <ComposerPrimitive.Unstable_SlashCommandRoot adapter={slashAdapter}>
-    <ComposerPrimitive.Root>
-      <ComposerPrimitive.Input placeholder="Type @ to mention, / for commands..." />
-      <ComposerPrimitive.Send>Send</ComposerPrimitive.Send>
-
-      {/* Mention popover — shows when @ is typed */}
-      <ComposerPrimitive.Unstable_MentionPopover>
-        <ComposerPrimitive.Unstable_MentionCategories>
-          {(categories) => categories.map((cat) => (
-            <ComposerPrimitive.Unstable_MentionCategoryItem key={cat.id} categoryId={cat.id}>
-              {cat.label}
-            </ComposerPrimitive.Unstable_MentionCategoryItem>
-          ))}
-        </ComposerPrimitive.Unstable_MentionCategories>
-        <ComposerPrimitive.Unstable_MentionItems>
-          {(items) => items.map((item) => (
-            <ComposerPrimitive.Unstable_MentionItem key={item.id} item={item}>
-              {item.label}
-            </ComposerPrimitive.Unstable_MentionItem>
-          ))}
-        </ComposerPrimitive.Unstable_MentionItems>
-      </ComposerPrimitive.Unstable_MentionPopover>
-
-      {/* Slash command popover — shows when / is typed */}
-      <ComposerPrimitive.Unstable_TriggerPopoverPopover>
-        <ComposerPrimitive.Unstable_TriggerPopoverItems>
-          {(items) => items.map((item, index) => (
-            <ComposerPrimitive.Unstable_TriggerPopoverItem key={item.id} item={item} index={index}>
-              {item.label}
-            </ComposerPrimitive.Unstable_TriggerPopoverItem>
-          ))}
-        </ComposerPrimitive.Unstable_TriggerPopoverItems>
-      </ComposerPrimitive.Unstable_TriggerPopoverPopover>
-    </ComposerPrimitive.Root>
-  </ComposerPrimitive.Unstable_SlashCommandRoot>
-</ComposerPrimitive.Unstable_MentionRoot>
+<ComposerPrimitive.Unstable_TriggerPopoverRoot>
+  <ComposerPrimitive.Root>
+    <ComposerPrimitive.Input placeholder="Type @ to mention, / for commands..." />
+    <ComposerPrimitive.Send>Send</ComposerPrimitive.Send>
+
+    {/* @ mention popover */}
+    <ComposerPrimitive.Unstable_TriggerPopover
+      char="@"
+      adapter={mention.adapter}
+    >
+      <ComposerPrimitive.Unstable_TriggerPopover.Directive {...mention.directive} />
+      <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_TriggerPopover>
+
+    {/* / slash command popover */}
+    <ComposerPrimitive.Unstable_TriggerPopover
+      char="/"
+      adapter={slash.adapter}
+    >
+      <ComposerPrimitive.Unstable_TriggerPopover.Action {...slash.action} />
+      <ComposerPrimitive.Unstable_TriggerPopoverItems>
+        {(items) => items.map((item, index) => (
+          <ComposerPrimitive.Unstable_TriggerPopoverItem key={item.id} item={item} index={index}>
+            {item.label}
+          </ComposerPrimitive.Unstable_TriggerPopoverItem>
+        ))}
+      </ComposerPrimitive.Unstable_TriggerPopoverItems>
+    </ComposerPrimitive.Unstable_TriggerPopover>
+  </ComposerPrimitive.Root>
+</ComposerPrimitive.Unstable_TriggerPopoverRoot>
 ```
 
-Each root provides its own `TriggerPopoverContext`. When the user types `@`, the mention popover opens. When they type `/`, the slash command popover opens. Keyboard events route to whichever popover is active.
+Each `TriggerPopover` is its own scope — the `@` popover and the `/` popover read state from their own declaration and never collide. Keyboard events route to whichever popover is currently active.
 
 ## Keyboard Navigation
 
@@ -236,15 +252,18 @@ Same keyboard bindings as mentions:
 
 Both mentions and slash commands are built on a generic **trigger popover** system:
 
-- `ComposerPrimitive.Unstable_TriggerPopoverRoot` — the generic root, parameterized by trigger character and select behavior
-- `ComposerPrimitive.Unstable_MentionRoot` — preset with `trigger="@"` and `onSelect: insertDirective`
-- `ComposerPrimitive.Unstable_SlashCommandRoot` — preset with `trigger="/"` and `onSelect: action`
+- `ComposerPrimitive.Unstable_TriggerPopoverRoot` — root provider that groups triggers and owns the input plugin registry
+- `ComposerPrimitive.Unstable_TriggerPopover` — declares one trigger (id, char, adapter) and renders its popover container
+- Behavior sub-primitives — exactly one per `TriggerPopover`:
+  - `Unstable_TriggerPopover.Directive` — writes a formatted directive on selection ("mention" path)
+  - `Unstable_TriggerPopover.Action` — fires a callback on selection ("slash" path); inserts a chip by default, strip with `removeOnExecute`
+- Shared sub-primitives (`TriggerPopoverCategories`, `TriggerPopoverItems`, `TriggerPopoverBack`) live inside a `TriggerPopover`
 
-The trigger popover primitives (`TriggerPopoverPopover`, `TriggerPopoverItems`, etc.) are shared across both. You can also use `TriggerPopoverRoot` directly to build custom trigger systems with other characters (e.g. `:` for emoji).
+You can declare any number of triggers under one root and mix behavior types.
 
 ### ComposerInput Plugin Protocol
 
-Under the hood, each trigger root registers a **ComposerInputPlugin** with the composer input. This is a generic protocol that decouples the input from any specific trigger:
+Under the hood, each `TriggerPopover` registers a **ComposerInputPlugin** with the composer input. This is a generic protocol that decouples the input from any specific trigger:
 
 ```ts
 type ComposerInputPlugin = {
@@ -253,15 +272,16 @@ type ComposerInputPlugin = {
 };
 ```
 
-The input iterates over registered plugins for keyboard events and cursor changes. This is what enables multiple trigger roots to coexist without conflict.
+The input iterates over registered plugins for keyboard events and cursor changes. This is what enables multiple triggers to coexist without conflict.
 
 ## Primitives Reference
 
 | Primitive | Description |
 | --- | --- |
-| `Unstable_SlashCommandRoot` | Convenience wrapper — `TriggerPopoverRoot` with `trigger="/"` and action behavior |
-| `Unstable_TriggerPopoverRoot` | Generic root — configurable trigger character and select behavior |
-| `Unstable_TriggerPopoverPopover` | Container — only renders when a trigger is active (`role="listbox"`) |
+| `Unstable_TriggerPopoverRoot` | Root — groups triggers, provides input plugin registry |
+| `Unstable_TriggerPopover` | Declares a trigger and renders its popover container |
+| `Unstable_TriggerPopover.Directive` | Behavior sub-primitive — inserts a formatted directive on selection |
+| `Unstable_TriggerPopover.Action` | Behavior sub-primitive — runs `onExecute` on selection; chip-by-default |
 | `Unstable_TriggerPopoverCategories` | Render-function for the top-level category list |
 | `Unstable_TriggerPopoverCategoryItem` | Button that drills into a category (`role="option"`, auto `data-highlighted`) |
 | `Unstable_TriggerPopoverItems` | Render-function for items within the active category or search results |

package/.docs/raw/docs/(docs)/rtl.mdx

@@ -0,0 +1,79 @@
+---
+title: RTL Support
+description: Use assistant-ui with right-to-left languages like Arabic, Hebrew, and Persian.
+---
+
+Components shipped through `@assistant-ui/ui` (npm) and the shadcn registry (`npx shadcn@latest add https://r.assistant-ui.com/...`) use logical Tailwind classes (`ms-*`, `pe-*`, `text-start`, `end-*`, `border-s`, ...). They flip automatically under `dir="rtl"` and render byte-identically under `dir="ltr"` (the default) — there is nothing to opt out of.
+
+If you scaffolded from one of our templates (e.g. `npx assistant-ui@latest create -t default`), the generated `components/` folder still uses physical classes (`ml-*`, `text-left`, ...). Run shadcn's built-in migration **once** to convert both the shadcn primitives and assistant-ui's wrappers:
+
+```sh
+# shadcn primitives under components/ui/
+npx shadcn@latest migrate rtl
+
+# assistant-ui wrappers (pass a custom glob)
+npx shadcn@latest migrate rtl 'components/assistant-ui/**/*.tsx'
+```
+
+Commit the diff and do not re-run. The upstream migration is not fully idempotent on repeat runs ([#9891](https://github.com/shadcn-ui/ui/pull/9891)); you may end up with duplicated `rtl:translate-x-*` classes.
+
+After migrating, follow the setup below.
+
+## Setup
+
+### 1. Install the `direction` component
+
+```sh
+npx shadcn@latest add https://r.assistant-ui.com/direction.json
+```
+
+This adds `components/ui/direction.tsx`, a thin re-export of Radix UI's `DirectionProvider` and `useDirection`. It ensures Radix popovers, dropdowns, and menus pick up the current direction.
+
+### 2. Set `dir` on your root element
+
+```tsx title="app/layout.tsx"
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="ar" dir="rtl">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+### 3. Wrap your app with `DirectionProvider`
+
+```tsx title="app/providers.tsx"
+"use client";
+
+import { DirectionProvider } from "@/components/ui/direction";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <DirectionProvider dir="rtl">{children}</DirectionProvider>;
+}
+```
+
+For apps that need to switch direction at runtime, drive `dir` from state and also update `document.documentElement.dir` to keep Tailwind's `[dir=rtl]` selector in sync.
+
+## How it works
+
+Every physical class (`ml-4`, `text-left`, `right-3`, `border-l`, ...) in `@assistant-ui/ui` is authored in logical form (`ms-4`, `text-start`, `end-3`, `border-s`, ...). Logical properties resolve to the matching physical side based on the ancestor with a `dir` attribute:
+
+| Class | `dir="ltr"` | `dir="rtl"` |
+| ----- | ----------- | ----------- |
+| `ms-4` | `margin-left: 1rem` | `margin-right: 1rem` |
+| `pe-2` | `padding-right: 0.5rem` | `padding-left: 0.5rem` |
+| `end-3` | `right: 0.75rem` | `left: 0.75rem` |
+| `text-start` | `text-align: left` | `text-align: right` |
+| `border-s` | `border-left` | `border-right` |
+
+A handful of Tailwind utilities have no logical equivalent, so we ship both the LTR value and an `rtl:` override:
+
+- `translate-x-*`: emits `-translate-x-*` plus `rtl:translate-x-*` (sign-flipped).
+- `space-x-*` / `divide-x-*`: emits the original plus `rtl:space-x-reverse` / `rtl:divide-x-reverse`.
+
+## Known edges
+
+- **Radix `data-[side=left|right]:slide-in-from-*`** animations are intentionally preserved as physical. Radix's `DirectionProvider` already flips the emitted `data-side` value, so no rewrite is needed.
+- **Third-party components and template scaffolds** may still use physical classes. Run `npx shadcn@latest migrate rtl` once per project (optionally with a path glob) to convert them. Do not re-run — see the note about upstream idempotency in the intro.
+- **Text that mixes LTR and RTL content** (e.g., English code inside Arabic prose) relies on the browser's bidi algorithm. Wrap unambiguous spans with `<bdi>` or `dir="ltr"` if you need to pin direction locally.