@lostgradient/cinder 0.8.0 → 0.9.0

package/src/components/chat/input/chat-input.svelte

@@ -40,7 +40,7 @@ const attachmentIdFactory = createIdFactory('attachment');
 // Tracks hash-derived IDs used in this instance so collisions (same name/size/mtime)
 // get a unique suffix rather than a duplicate DOM ID.
 const usedAttachmentIds = new Set();
-let { id, value = $bindable(''), placeholder = 'Type a message...', composerLabel = 'Message', disabled = false, sending = false, error, class: className, action, name = 'content', clearOnSubmit = true, allowAttachments = true, maxFileSize = 10 * 1024 * 1024, // 10MB
+let { id, value = $bindable(''), placeholder = 'Type a message...', composerLabel = 'Message', composerRole, composerAriaExpanded, composerAriaControls, composerAriaActiveDescendant, composerAriaAutocomplete, disabled = false, sending = false, error, class: className, action, name = 'content', clearOnSubmit = true, allowAttachments = true, maxFileSize = 10 * 1024 * 1024, // 10MB
 acceptedTypes = [
     'image/*',
     'text/*',
@@ -55,7 +55,7 @@ acceptedTypes = [
     'application/x-sh',
     'application/sql',
     'application/toml',
-], onsubmit, onstop, oncomposerinput, onattachmentadd, onattachmentremove, onattachmentfailure, actions, ...rest } = $props();
+], onsubmit, onstop, oncomposerinput, oncomposerkeydown, oncomposerselectionchange, oncomposerblur, onattachmentadd, onattachmentremove, onattachmentfailure, actions, ...rest } = $props();
 const resolvedComposerLabel = $derived(composerLabel.trim() || 'Message');
 // Derived: show stop button when sending and onstop is provided
 const showStopButton = $derived(sending && onstop !== undefined);
@@ -266,6 +266,12 @@ function handleKeyDown(event) {
     if (event.isComposing || isComposing) {
         return;
     }
+    if (event.target === editorElement) {
+        oncomposerkeydown?.(event);
+        if (event.defaultPrevented) {
+            return;
+        }
+    }
     // Shift+Enter: Newline (let editor handle it)
     if (event.key === 'Enter' && event.shiftKey) {
         return;
@@ -287,8 +293,8 @@ function handleCompositionEnd() {
 // Fires after `bind:value` has already applied the textarea's new value
 // (Svelte merges the binding's own input listener with this handler on the
 // same event), so `value` here is always current — never one keystroke stale.
-function handleInput() {
-    oncomposerinput?.(value);
+function handleInput(event) {
+    oncomposerinput?.(value, event);
 }
 // =========================================================================
 // Imperative API
@@ -307,6 +313,9 @@ export function getAttachments() {
 export function getValue() {
     return value;
 }
+export function getEditorElement() {
+    return editorElement;
+}
 export function addFiles(files) {
     if (!allowAttachments)
         return;
@@ -326,7 +335,6 @@ onDestroy(() => {
   method="POST"
   {action}
   onsubmit={handleSubmit}
-  onkeydown={handleKeyDown}
   onpaste={handlePaste}
   ondrop={handleDrop}
   ondragover={handleDragOver}
@@ -367,9 +375,18 @@ onDestroy(() => {
       bind:this={editorElement}
       id={`${id}-editor`}
       bind:value
+      onkeydown={handleKeyDown}
       oninput={handleInput}
+      onpointerup={oncomposerselectionchange}
+      onselect={oncomposerselectionchange}
+      onblur={oncomposerblur}
       {placeholder}
+      role={composerRole}
       aria-label={resolvedComposerLabel}
+      aria-expanded={composerAriaExpanded}
+      aria-controls={composerAriaControls}
+      aria-activedescendant={composerAriaActiveDescendant}
+      aria-autocomplete={composerAriaAutocomplete}
       {disabled}
       readonly={sending}
       class="chat-input-editor"

package/src/components/chat/input/index.ts

@@ -1,4 +1,9 @@
 export { deriveAttachmentKind, type AttachmentKind } from './attachment-kind.js';
 export { default as ChatAttachmentPreview } from './chat-attachment-preview.svelte';
+export {
+  serializeChatAttachment,
+  serializeChatAttachments,
+  type SerializedChatAttachment,
+} from './chat-attachment-serialization.ts';
 export type { ChatAttachment } from './chat-attachment.ts';
 export { default as ChatInput } from './chat-input.svelte';

package/src/components/chat-composer-popover/chat-composer-popover-filter.ts

@@ -0,0 +1,68 @@
+export type FuzzyFilterItem = {
+  value: string;
+  label: string;
+  keywords?: readonly string[] | undefined;
+};
+
+export type FuzzyFilterResult<TItem extends FuzzyFilterItem> = {
+  item: TItem;
+  score: number;
+};
+
+function normalize(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+export function fuzzySubsequenceScore(candidate: string, query: string): number | null {
+  const normalizedCandidate = normalize(candidate);
+  const normalizedQuery = normalize(query);
+
+  if (normalizedQuery.length === 0) return 0;
+  if (normalizedCandidate.length === 0) return null;
+
+  let score = 0;
+  let searchIndex = 0;
+  let previousMatchIndex = -1;
+
+  for (const character of normalizedQuery) {
+    const matchIndex = normalizedCandidate.indexOf(character, searchIndex);
+    if (matchIndex === -1) return null;
+
+    score += matchIndex === previousMatchIndex + 1 ? 4 : 1;
+    if (matchIndex === 0) score += 2;
+    if (/[\s/_-]/u.test(normalizedCandidate[matchIndex - 1] ?? '')) score += 2;
+
+    previousMatchIndex = matchIndex;
+    searchIndex = matchIndex + 1;
+  }
+
+  return score - normalizedCandidate.length * 0.01;
+}
+
+export function filterFuzzySubsequence<TItem extends FuzzyFilterItem>(
+  items: readonly TItem[],
+  query: string,
+): TItem[] {
+  const normalizedQuery = normalize(query);
+  if (normalizedQuery.length === 0) return [...items];
+
+  const matchedItems = items
+    .map((item, index) => {
+      const candidates = [item.label, item.value, ...(item.keywords ?? [])];
+      let bestScore: number | null = null;
+
+      for (const candidate of candidates) {
+        const score = fuzzySubsequenceScore(candidate, normalizedQuery);
+        if (score !== null && (bestScore === null || score > bestScore)) {
+          bestScore = score;
+        }
+      }
+
+      return bestScore === null ? null : { item, index, score: bestScore };
+    })
+    .filter((result) => result !== null);
+
+  matchedItems.sort((a, b) => b.score - a.score || a.index - b.index);
+
+  return matchedItems.map((result) => result.item);
+}

package/src/components/chat-composer-popover/chat-composer-popover.css

@@ -0,0 +1,7 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+/* ChatComposerPopover renders CommandMenu and CommandItem internally. Pull in
+ * the command menu family so the wrapper is styled through its own styles path. */
+@import '../command-menu/command-menu.css';
+
+@layer cinder.components {
+}

package/src/components/chat-composer-popover/chat-composer-popover.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "chat-composer-popover",
+  "import": "@lostgradient/cinder/chat-composer-popover",
+  "examples": [
+    {
+      "id": "slash-commands",
+      "title": "Slash commands in ChatInput",
+      "description": "Wires ChatComposerPopover to ChatInput with consumer-owned command definitions.",
+      "code": "<script lang=\"ts\">\n  import ChatComposerPopover, {\n    type ChatComposerPopoverSelection,\n  } from '@lostgradient/cinder/chat-composer-popover';\n  import { ChatInput } from '@lostgradient/cinder/chat';\n\n  type SlashCommand = {\n    value: string;\n    label: string;\n    description: string;\n    insert: string;\n    keywords?: string[];\n  };\n\n  const commands: SlashCommand[] = [\n    {\n      value: 'help',\n      label: 'Help',\n      description: 'Show available assistant commands',\n      insert: '/help ',\n      keywords: ['docs', 'support'],\n    },\n    {\n      value: 'new',\n      label: 'New conversation',\n      description: 'Start a fresh thread',\n      insert: '/new ',\n      keywords: ['reset', 'fresh'],\n    },\n    {\n      value: 'tools',\n      label: 'Tools',\n      description: 'Open tool controls',\n      insert: '/tools ',\n      keywords: ['integrations', 'actions'],\n    },\n    {\n      value: 'stop',\n      label: 'Stop',\n      description: 'Stop the current response',\n      insert: '/stop',\n      keywords: ['cancel', 'halt'],\n    },\n  ];\n\n  let value = $state('');\n  let selectedCommand = $state('None');\n\n  function handleSelect(selection: ChatComposerPopoverSelection<SlashCommand>) {\n    value = `${value.slice(0, selection.range.start)}${selection.item.insert}${value.slice(\n      selection.range.end,\n    )}`;\n    selectedCommand = selection.item.label;\n  }\n</script>\n\n<ChatComposerPopover id=\"slash-command\" bind:value items={commands} onselect={handleSelect}>\n  {#snippet composer(composerProps)}\n    <ChatInput\n      id=\"chat\"\n      bind:value\n      allowAttachments={false}\n      placeholder=\"Type / for commands\"\n      composerRole={composerProps.composerRole}\n      composerAriaExpanded={composerProps.composerAriaExpanded}\n      composerAriaControls={composerProps.composerAriaControls}\n      composerAriaActiveDescendant={composerProps.composerAriaActiveDescendant}\n      composerAriaAutocomplete={composerProps.composerAriaAutocomplete}\n      oncomposerinput={composerProps.oncomposerinput}\n      oncomposerkeydown={composerProps.oncomposerkeydown}\n      oncomposerselectionchange={composerProps.oncomposerselectionchange}\n      oncomposerblur={composerProps.oncomposerblur}\n    />\n  {/snippet}\n</ChatComposerPopover>\n\n<p>Selected: {selectedCommand}</p>\n"
+    }
+  ]
+}

package/src/components/chat-composer-popover/chat-composer-popover.schema.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique identifier used for the listbox and item ids."
+    },
+    "value": {
+      "type": "string",
+      "description": "Current composer value. Bind this to the same value as ChatInput."
+    },
+    "triggers": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Trigger characters that open the popover. Default `['/', '@']`."
+    },
+    "label": {
+      "type": "string",
+      "description": "Accessible listbox label. Default `'Composer suggestions'`."
+    },
+    "placement": {
+      "enum": [
+        "top",
+        "bottom",
+        "left",
+        "right",
+        "top-start",
+        "top-end",
+        "bottom-start",
+        "bottom-end"
+      ],
+      "description": "Caret-relative placement. Default `'bottom-start'`."
+    },
+    "offset": {
+      "type": "number",
+      "description": "Distance in px between the caret and popover. Default `6`."
+    }
+  },
+  "additionalProperties": false,
+  "required": ["id"],
+  "metadata": {
+    "unsupportedProps": [
+      {
+        "name": "composer",
+        "reason": "function-or-snippet",
+        "required": true,
+        "description": "Render the ChatInput or compatible composer with the provided overlay props."
+      },
+      {
+        "name": "detectTrigger",
+        "reason": "function-or-snippet",
+        "description": "Override trigger detection."
+      },
+      {
+        "name": "empty",
+        "reason": "function-or-snippet",
+        "description": "Optional empty state rendered when filtering produces no matching rows."
+      },
+      {
+        "name": "filter",
+        "reason": "function-or-snippet",
+        "description": "Override filtering."
+      },
+      {
+        "name": "item",
+        "reason": "function-or-snippet",
+        "description": "Optional custom row contents. Defaults to the item label and description."
+      },
+      {
+        "name": "items",
+        "reason": "generic-type-parameter",
+        "required": true,
+        "description": "Consumer-owned command or mention definitions."
+      },
+      {
+        "name": "ondismiss",
+        "reason": "function-or-snippet",
+        "description": "Invoked when Escape, trigger loss, or outside pointerdown dismisses the popover."
+      },
+      {
+        "name": "onselect",
+        "reason": "function-or-snippet",
+        "description": "Invoked when an enabled item is selected by keyboard or pointer."
+      }
+    ]
+  }
+}

package/src/components/chat-composer-popover/chat-composer-popover.schema.ts

@@ -0,0 +1,95 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Unique identifier used for the listbox and item ids.',
+    },
+    value: {
+      type: 'string',
+      description: 'Current composer value. Bind this to the same value as ChatInput.',
+    },
+    triggers: {
+      type: 'array',
+      items: {
+        type: 'string',
+      },
+      description: "Trigger characters that open the popover. Default `['/', '@']`.",
+    },
+    label: {
+      type: 'string',
+      description: "Accessible listbox label. Default `'Composer suggestions'`.",
+    },
+    placement: {
+      enum: [
+        'top',
+        'bottom',
+        'left',
+        'right',
+        'top-start',
+        'top-end',
+        'bottom-start',
+        'bottom-end',
+      ],
+      description: "Caret-relative placement. Default `'bottom-start'`.",
+    },
+    offset: {
+      type: 'number',
+      description: 'Distance in px between the caret and popover. Default `6`.',
+    },
+  },
+  additionalProperties: false,
+  required: ['id'],
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'composer',
+        reason: 'function-or-snippet',
+        required: true,
+        description: 'Render the ChatInput or compatible composer with the provided overlay props.',
+      },
+      {
+        name: 'detectTrigger',
+        reason: 'function-or-snippet',
+        description: 'Override trigger detection.',
+      },
+      {
+        name: 'empty',
+        reason: 'function-or-snippet',
+        description: 'Optional empty state rendered when filtering produces no matching rows.',
+      },
+      {
+        name: 'filter',
+        reason: 'function-or-snippet',
+        description: 'Override filtering.',
+      },
+      {
+        name: 'item',
+        reason: 'function-or-snippet',
+        description: 'Optional custom row contents. Defaults to the item label and description.',
+      },
+      {
+        name: 'items',
+        reason: 'generic-type-parameter',
+        required: true,
+        description: 'Consumer-owned command or mention definitions.',
+      },
+      {
+        name: 'ondismiss',
+        reason: 'function-or-snippet',
+        description:
+          'Invoked when Escape, trigger loss, or outside pointerdown dismisses the popover.',
+      },
+      {
+        name: 'onselect',
+        reason: 'function-or-snippet',
+        description: 'Invoked when an enabled item is selected by keyboard or pointer.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/chat-composer-popover/chat-composer-popover.svelte

@@ -0,0 +1,234 @@
+<script lang="ts" module>
+export { filterFuzzySubsequence, fuzzySubsequenceScore, } from './chat-composer-popover-filter.ts';
+</script>
+
+<script lang="ts" generics="TItem extends ChatComposerPopoverItem">
+import CommandItem from '../command-item/command-item.svelte';
+import CommandMenu from '../command-menu/command-menu.svelte';
+import { onDestroy } from 'svelte';
+import { detectTrigger as detectCommandTrigger } from '../command-menu/command-menu-trigger.ts';
+import { filterFuzzySubsequence } from './chat-composer-popover-filter.ts';
+let { id, value = $bindable(''), items, triggers = ['/', '@'], label = 'Composer suggestions', placement = 'bottom-start', offset = 6, composer, item, empty, detectTrigger, filter = filterFuzzySubsequence, onselect, ondismiss, } = $props();
+let open = $state(false);
+let anchor = $state(null);
+let caretIndex = $state(0);
+const listboxId = $derived(`${id}-listbox`);
+let activeItemId = $state(null);
+let activeMatch = $state(null);
+let composerSyncTimer = null;
+let lastSyncedValue = $state(value);
+let suppressNextValueSync = false;
+const emptyContent = $derived(empty);
+const query = $derived(activeMatch?.query ?? '');
+const trigger = $derived(activeMatch?.trigger ?? triggers[0] ?? '/');
+const filteredItems = $derived.by(() => {
+    if (!activeMatch)
+        return [];
+    return [...filter(items, activeMatch.query, activeMatch.trigger)];
+});
+const composerProps = $derived({
+    composerRole: 'combobox',
+    composerAriaExpanded: open,
+    composerAriaControls: open ? listboxId : undefined,
+    composerAriaActiveDescendant: open ? (activeItemId ?? undefined) : undefined,
+    composerAriaAutocomplete: 'list',
+    oncomposerinput: handleComposerInput,
+    oncomposerkeydown: handleComposerKeydown,
+    oncomposerselectionchange: handleComposerSelectionChange,
+    oncomposerblur: handleComposerBlur,
+});
+function getComposerElement(event) {
+    const target = event.currentTarget ?? event.target;
+    if (target instanceof HTMLTextAreaElement || target instanceof HTMLInputElement) {
+        return target;
+    }
+    return null;
+}
+function findTriggerMatch(text, selectionStart, selectionEnd) {
+    if (detectTrigger)
+        return detectTrigger(text, selectionStart, selectionEnd);
+    for (const triggerChar of triggers) {
+        const match = detectCommandTrigger({ text, selectionStart, selectionEnd, triggerChar });
+        if (match) {
+            return { ...match, trigger: triggerChar };
+        }
+    }
+    return null;
+}
+function updateFromComposer(composerElement, nextValue) {
+    if (composerElement)
+        anchor = composerElement;
+    const selectionStart = composerElement?.selectionStart ?? nextValue.length;
+    const selectionEnd = composerElement?.selectionEnd ?? selectionStart;
+    lastSyncedValue = nextValue;
+    value = nextValue;
+    caretIndex = selectionEnd;
+    activeMatch = findTriggerMatch(nextValue, selectionStart, selectionEnd);
+    const wasOpen = open;
+    open = activeMatch !== null && anchor !== null;
+    if (!open) {
+        activeItemId = null;
+        if (wasOpen)
+            ondismiss?.();
+    }
+}
+function dismiss({ restoreFocus = true } = {}) {
+    if (!open && !activeMatch && !activeItemId)
+        return;
+    clearComposerSyncTimer();
+    open = false;
+    activeItemId = null;
+    activeMatch = null;
+    if (restoreFocus)
+        anchor?.focus();
+    ondismiss?.();
+}
+function handleComposerInput(nextValue, event) {
+    suppressNextValueSync = false;
+    updateFromComposer(event ? getComposerElement(event) : anchor, nextValue);
+}
+function handleComposerSelectionChange(event) {
+    suppressNextValueSync = false;
+    const composerElement = getComposerElement(event);
+    if (!composerElement)
+        return;
+    syncComposerSelectionAfterNativeNavigation(composerElement);
+}
+function handleComposerBlur(event) {
+    if (event.currentTarget === anchor) {
+        dismiss({ restoreFocus: false });
+    }
+}
+function syncComposerSelectionAfterNativeNavigation(composerElement) {
+    clearComposerSyncTimer();
+    composerSyncTimer = setTimeout(() => {
+        composerSyncTimer = null;
+        updateFromComposer(composerElement, composerElement.value);
+    }, 0);
+}
+function clearComposerSyncTimer() {
+    if (composerSyncTimer === null)
+        return;
+    clearTimeout(composerSyncTimer);
+    composerSyncTimer = null;
+}
+function handleComposerKeydown(event) {
+    const composerElement = event.currentTarget instanceof HTMLTextAreaElement ||
+        event.currentTarget instanceof HTMLInputElement
+        ? event.currentTarget
+        : null;
+    if (composerElement) {
+        anchor = composerElement;
+        caretIndex = composerElement.selectionEnd ?? value.length;
+    }
+    if (!open || event.isComposing || event.keyCode === 229)
+        return;
+    if (event.key === 'Escape') {
+        event.preventDefault();
+        event.stopPropagation();
+        dismiss();
+        return;
+    }
+    const isNavigationKey = event.key === 'ArrowDown' ||
+        event.key === 'ArrowUp' ||
+        event.key === 'ArrowLeft' ||
+        event.key === 'ArrowRight' ||
+        event.key === 'Home' ||
+        event.key === 'End';
+    const isMenuNavigationKey = event.key === 'ArrowDown' ||
+        event.key === 'ArrowUp' ||
+        event.key === 'Home' ||
+        event.key === 'End';
+    const isModifiedNavigation = isNavigationKey && (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey);
+    if ((isMenuNavigationKey && !isModifiedNavigation) || (event.key === 'Enter' && activeItemId)) {
+        event.preventDefault();
+    }
+    if (composerElement && isNavigationKey && (isModifiedNavigation || !isMenuNavigationKey)) {
+        syncComposerSelectionAfterNativeNavigation(composerElement);
+    }
+}
+onDestroy(() => {
+    clearComposerSyncTimer();
+});
+$effect(() => {
+    if (value === lastSyncedValue)
+        return;
+    if (suppressNextValueSync) {
+        suppressNextValueSync = false;
+        lastSyncedValue = value;
+        return;
+    }
+    updateFromComposer(anchor, value);
+});
+function handleStateChange(state) {
+    activeItemId = state.activeItemId;
+}
+function handleSelect(selection) {
+    const selectedItem = filteredItems.find((candidate) => candidate.value === selection.value);
+    if (!selectedItem || !activeMatch)
+        return;
+    const detail = {
+        item: selectedItem,
+        value: selection.value,
+        query: activeMatch.query,
+        trigger: activeMatch.trigger,
+        range: {
+            start: activeMatch.start,
+            end: activeMatch.end,
+        },
+    };
+    open = false;
+    activeItemId = null;
+    activeMatch = null;
+    anchor?.focus();
+    suppressNextValueSync = true;
+    queueMicrotask(() => {
+        suppressNextValueSync = false;
+    });
+    onselect?.(detail);
+}
+</script>
+
+{@render composer(composerProps)}
+
+<CommandMenu
+  bind:open
+  {anchor}
+  {caretIndex}
+  {query}
+  {placement}
+  {offset}
+  {label}
+  {listboxId}
+  onselect={handleSelect}
+  ondismiss={() => dismiss({ restoreFocus: false })}
+  onstatechange={handleStateChange}
+>
+  {#snippet items()}
+    {#each filteredItems as command (command.value)}
+      <CommandItem
+        value={command.value}
+        disabled={command.disabled === true}
+        description={item ? '' : (command.description ?? '')}
+        accessibleLabel={command.description
+          ? `${command.label}, ${command.description}`
+          : command.label}
+        selectionMode="parent"
+      >
+        {#if item}
+          {@render item({ item: command, query, trigger })}
+        {:else}
+          {command.label}
+        {/if}
+      </CommandItem>
+    {/each}
+  {/snippet}
+
+  {#snippet empty()}
+    {#if emptyContent}
+      {@render emptyContent()}
+    {:else}
+      No suggestions
+    {/if}
+  {/snippet}
+</CommandMenu>

package/src/components/chat-composer-popover/chat-composer-popover.types.ts

@@ -0,0 +1,88 @@
+import type { Snippet } from 'svelte';
+
+import type { PopoverPlacement } from '../popover/popover.types.ts';
+
+export type ChatComposerPopoverItem = {
+  /** Stable submitted value surfaced through onselect. */
+  value: string;
+  /** Default visible and accessible label for the command row. */
+  label: string;
+  /** Optional secondary text for the command row. */
+  description?: string | undefined;
+  /** Optional fuzzy-search aliases. */
+  keywords?: readonly string[] | undefined;
+  /** Whether this row is skipped by keyboard navigation and activation. */
+  disabled?: boolean | undefined;
+};
+
+export type ChatComposerPopoverTriggerMatch = {
+  active: true;
+  trigger: string;
+  query: string;
+  start: number;
+  end: number;
+};
+
+export type ChatComposerPopoverSelection<TItem extends ChatComposerPopoverItem> = {
+  item: TItem;
+  value: string;
+  query: string;
+  trigger: string;
+  range: {
+    start: number;
+    end: number;
+  };
+};
+
+export type ChatComposerPopoverComposerProps = {
+  composerRole: 'combobox';
+  composerAriaExpanded: boolean;
+  composerAriaControls: string | undefined;
+  composerAriaActiveDescendant: string | undefined;
+  composerAriaAutocomplete: 'list';
+  oncomposerinput: (value: string, event?: Event) => void;
+  oncomposerkeydown: (event: KeyboardEvent) => void;
+  oncomposerselectionchange: (event: Event) => void;
+  oncomposerblur: (event: FocusEvent) => void;
+};
+
+export type ChatComposerPopoverItemSnippetContext<TItem extends ChatComposerPopoverItem> = {
+  item: TItem;
+  query: string;
+  trigger: string;
+};
+
+export type ChatComposerPopoverProps<TItem extends ChatComposerPopoverItem> = {
+  /** Unique identifier used for the listbox and item ids. */
+  id: string;
+  /** Current composer value. Bind this to the same value as ChatInput. */
+  value?: string;
+  /** Consumer-owned command or mention definitions. */
+  items: readonly TItem[];
+  /** Trigger characters that open the popover. Default `['/', '@']`. */
+  triggers?: readonly string[];
+  /** Accessible listbox label. Default `'Composer suggestions'`. */
+  label?: string;
+  /** Caret-relative placement. Default `'bottom-start'`. */
+  placement?: PopoverPlacement;
+  /** Distance in px between the caret and popover. Default `6`. */
+  offset?: number;
+  /** Render the ChatInput or compatible composer with the provided overlay props. */
+  composer: Snippet<[ChatComposerPopoverComposerProps]>;
+  /** Optional custom row contents. Defaults to the item label and description. */
+  item?: Snippet<[ChatComposerPopoverItemSnippetContext<TItem>]>;
+  /** Optional empty state rendered when filtering produces no matching rows. */
+  empty?: Snippet;
+  /** Override trigger detection. */
+  detectTrigger?: (
+    value: string,
+    selectionStart: number,
+    selectionEnd: number,
+  ) => ChatComposerPopoverTriggerMatch | null;
+  /** Override filtering. */
+  filter?: (items: readonly TItem[], query: string, trigger: string) => readonly TItem[];
+  /** Invoked when an enabled item is selected by keyboard or pointer. */
+  onselect?: (selection: ChatComposerPopoverSelection<TItem>) => void;
+  /** Invoked when Escape, trigger loss, or outside pointerdown dismisses the popover. */
+  ondismiss?: () => void;
+};