@juspay/svelte-ui-components 4.33.3 → 4.34.1

package/dist/ChatComposer/ChatComposer.svelte

@@ -6,8 +6,14 @@
   import stopSvg from '../assets/stop.svg?raw';
   import micSvg from '../assets/mic.svg?raw';
   import attachSvg from '../assets/attach.svg?raw';
+  import { tick } from 'svelte';
   import type { Action } from 'svelte/action';
-  import type { ChatComposerProperties } from './properties';
+  import { registerDismissible } from '../_interaction/dismissal';
+  import type {
+    ChatComposerProperties,
+    ChatComposerSlashCommand,
+    ChatComposerSlashCommandChoice
+  } from './properties';
   import { resolveControlDisabled } from './controlDisabled';
   import { shouldApplyClear } from './submitResult';
   import { normalizeDictationState } from './dictationState';
@@ -54,6 +60,13 @@
     leading,
     statusText,
     statusTestId,
+    slashCommands = null,
+    slashMenuAriaLabel = 'slash commands',
+    slashMenuHint = '↑↓ move · tab complete · ↵ select · esc dismiss',
+    slashMenuClasses,
+    slashItemClasses,
+    slashSelectedItemClasses,
+    slashItem,
     onsubmit,
     oninput,
     onkeydown,
@@ -103,10 +116,159 @@
       (sendable ?? (value.trim().length > 0 || attachments.length > 0 || hasRichAttachments))
   );
 
+  // ---- slash-command menu (off unless `slashCommands` is set) ----
+  // Stage one: "/co" lists the commands that match. Stage two: "/model son"
+  // lists the /model command's choices that start with "son". A free-text
+  // argument dismisses the menu at the space instead.
+  let slashDismissed = $state(false);
+  let slashSelected = $state(0);
+  let slashList: HTMLUListElement | null = $state(null);
+
+  const slashMatches = $derived.by((): ChatComposerSlashCommand[] => {
+    if (slashCommands === null || slashDismissed || !/^\/\S*$/.test(value)) {
+      return [];
+    }
+    const query = value.toLowerCase();
+    return slashCommands.filter(
+      (command) =>
+        command.name.toLowerCase().startsWith(query) ||
+        (query.length > 1 && (command.description ?? '').toLowerCase().includes(query.slice(1)))
+    );
+  });
+  const slashArg = $derived.by(
+    (): { command: ChatComposerSlashCommand; choices: ChatComposerSlashCommandChoice[] } | null => {
+      if (slashCommands === null || slashDismissed) {
+        return null;
+      }
+      const parsed = /^(\/\S+)\s(\S*)$/.exec(value);
+      if (parsed === null) {
+        return null;
+      }
+      const name = (parsed[1] ?? '').toLowerCase();
+      const command = slashCommands.find(
+        (entry) => entry.name.toLowerCase() === name && (entry.choices?.length ?? 0) > 0
+      );
+      if (typeof command !== 'object') {
+        return null;
+      }
+      const partial = (parsed[2] ?? '').toLowerCase();
+      return {
+        command,
+        choices: (command.choices ?? []).filter((choice) =>
+          choice.value.toLowerCase().startsWith(partial)
+        )
+      };
+    }
+  );
+  // One list, two stages: stage two shows the choices as rows.
+  const slashItems = $derived.by((): ChatComposerSlashCommand[] =>
+    slashArg === null
+      ? slashMatches
+      : slashArg.choices.map((choice) =>
+          typeof choice.description === 'string'
+            ? { name: choice.value, description: choice.description }
+            : { name: choice.value }
+        )
+  );
+  const slashOpen = $derived(slashItems.length > 0);
+  // The highlight stays inside the list as typing narrows it.
+  const slashActive = $derived(Math.min(slashSelected, Math.max(0, slashItems.length - 1)));
+
+  // Combobox wiring for the textarea, same pattern as CommandMenu's input: the menu's own id
+  // for aria-controls, and the highlighted row's id for aria-activedescendant. Both ids --
+  // and the role/aria-expanded/aria-autocomplete below -- are applied to the textarea only
+  // while slashCommands is set, so a consumer not using slash commands keeps the plain
+  // <textarea> role it always had.
+  const uid = $props.id();
+  const slashListboxId = `chat-composer-slash-listbox-${uid}`;
+  const slashActiveId = $derived(
+    slashOpen ? `chat-composer-slash-option-${uid}-${slashActive}` : null
+  );
+
+  // What the highlighted row completes the input to, stage-aware.
+  function slashCompletion(index: number): string | null {
+    if (slashArg !== null) {
+      const choice = slashArg.choices.at(index);
+      return typeof choice === 'object' ? `${slashArg.command.name} ${choice.value}` : null;
+    }
+    return slashItems.at(index)?.name ?? null;
+  }
+
+  function pickSlash(index: number): void {
+    if (slashArg !== null) {
+      const choice = slashArg.choices.at(index);
+      if (typeof choice === 'object') {
+        value = `${slashArg.command.name} ${choice.value}`;
+        slashSelected = 0;
+      }
+      return;
+    }
+    const command = slashMatches.at(index);
+    if (typeof command !== 'object') {
+      return;
+    }
+    // A command that takes arguments gets a trailing space and waits for
+    // them; with enumerable choices the menu stays open for stage two.
+    value = `${command.name} `;
+    slashDismissed = (command.choices?.length ?? 0) === 0;
+    slashSelected = 0;
+  }
+
+  // Keeps the highlighted row in view while the list scrolls.
+  function revealSlash(): void {
+    void tick().then(() => {
+      const row = slashList?.children.item(slashActive);
+      row?.scrollIntoView({ block: 'nearest' });
+    });
+  }
+
+  // Arrows, Tab and Enter while the menu is open. Escape is the dismissible
+  // stack's (registered while the menu is open), so an overlay stacked above
+  // the composer takes it first.
+  function handleSlashKey(event: KeyboardEvent): boolean {
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault();
+      slashSelected =
+        event.key === 'ArrowDown'
+          ? Math.min(slashActive + 1, slashItems.length - 1)
+          : Math.max(slashActive - 1, 0);
+      revealSlash();
+      return true;
+    }
+    if (event.key === 'Tab' && !event.shiftKey) {
+      event.preventDefault();
+      pickSlash(slashActive);
+      return true;
+    }
+    if (event.key === 'Enter' && !event.shiftKey && !event.isComposing) {
+      event.preventDefault();
+      // Enter on a complete match submits it; otherwise it completes and
+      // the next Enter submits.
+      if (value.trim() === slashCompletion(slashActive)) {
+        submit();
+      } else {
+        pickSlash(slashActive);
+      }
+      return true;
+    }
+    return false;
+  }
+
+  function slashDismissal(_node: HTMLDivElement) {
+    const release = registerDismissible({
+      element: () => _node,
+      onEscape: () => {
+        slashDismissed = true;
+      }
+    });
+    return { destroy: release };
+  }
+
   function submit(): void {
     if (!canSend) {
       return;
     }
+    slashDismissed = false;
     const submitted = { value, attachments };
     const result = onsubmit?.(submitted.value, submitted.attachments);
     if (result instanceof Promise) {
@@ -132,7 +294,9 @@
   }
 
   function handleKeydown(event: KeyboardEvent): void {
+    const slashHandled = slashOpen && handleSlashKey(event);
     if (
+      !slashHandled &&
       submitOnEnter &&
       event.key === 'Enter' &&
       !event.shiftKey &&
@@ -153,6 +317,9 @@
   }
 
   function handleInput(event: Event & { currentTarget: HTMLTextAreaElement }): void {
+    // A fresh edit un-dismisses the slash menu and resets its highlight.
+    slashDismissed = false;
+    slashSelected = 0;
     oninput?.(event.currentTarget.value, event);
   }
 
@@ -182,9 +349,62 @@
 <div
   class="chat-composer {classes ?? ''}"
   class:disabled
+  data-has-slash={slashCommands !== null ? '' : null}
   data-pw={typeof testId === 'string' ? testId : null}
   testID={typeof testId === 'string' ? testId : null}
 >
+  {#if slashOpen}
+    <div
+      class="slash-menu {slashMenuClasses ?? ''}"
+      role="listbox"
+      id={slashListboxId}
+      aria-label={slashMenuAriaLabel}
+      use:slashDismissal
+    >
+      <!-- role="presentation": a listbox's accessible children must be its own role=option
+           rows. Left as a plain <ul>, this list's implicit role=list would sit between the
+           listbox and its options in the accessibility tree, breaking that ownership chain
+           for assistive tech that computes it strictly from the DOM. -->
+      <ul class="slash-list" role="presentation" bind:this={slashList}>
+        {#each slashItems as command, index (command.name)}
+          <!-- The row, not the Button, takes the hover: Button has no
+               mouseenter, and it fills the row, so it is the same gesture. -->
+          <li
+            id={`chat-composer-slash-option-${uid}-${index}`}
+            role="option"
+            aria-selected={index === slashActive}
+            onmouseenter={() => (slashSelected = index)}
+            class:slash-item-selected-default={index === slashActive &&
+              typeof slashSelectedItemClasses !== 'string'}
+          >
+            <Button
+              type="button"
+              classes={[slashItemClasses, index === slashActive ? slashSelectedItemClasses : '']
+                .filter((value) => typeof value === 'string' && value.length > 0)
+                .join(' ')}
+              onclick={() => pickSlash(index)}
+            >
+              {#if typeof slashItem === 'function'}
+                {@render slashItem(command, index === slashActive)}
+              {:else}
+                <span class="slash-name">{command.name}</span>
+                {#if typeof command.argumentHint === 'string'}
+                  <span class="slash-hint">{command.argumentHint}</span>
+                {/if}
+                {#if typeof command.description === 'string'}
+                  <span class="slash-desc">{command.description}</span>
+                {/if}
+                {#if typeof command.badge === 'string'}
+                  <span class="slash-badge">{command.badge}</span>
+                {/if}
+              {/if}
+            </Button>
+          </li>
+        {/each}
+      </ul>
+      <div class="slash-foot">{slashMenuHint}</div>
+    </div>
+  {/if}
   {#if typeof statusText === 'string'}
     <!-- Generic region, role and politeness only -- the sentence is
          whatever the caller passed in `statusText`, never hardcoded here. -->
@@ -268,6 +488,11 @@
       disabled={resolvedTextDisabled}
       rows="1"
       aria-label={inputAriaLabel ?? (placeholder.length > 0 ? placeholder : 'Message')}
+      role={slashCommands !== null ? 'combobox' : null}
+      aria-expanded={slashCommands !== null ? slashOpen : null}
+      aria-controls={slashOpen ? slashListboxId : null}
+      aria-autocomplete={slashCommands !== null ? 'list' : null}
+      aria-activedescendant={slashActiveId}
       maxlength={maxLength > 0 ? maxLength : null}
       oninput={handleInput}
       onkeydown={handleKeydown}
@@ -463,6 +688,94 @@
     --button-text-color: var(--chat-composer-stop-color, #ffffff);
   }
 
+  /* Positioned only when slash commands are on, so their menu can sit
+     above the composer; a consumer without them is unchanged. A data attribute,
+     not a class, and the menu rules below are written down the structure they live in
+     (.chat-composer > .slash-menu ...): a class directive would strip a `has-slash` class a
+     consumer already passes through `classes`, and a class of one of these names passed
+     there would match rules meant for the menu. */
+  .chat-composer[data-has-slash] {
+    position: relative;
+  }
+
+  /* Positioned from the composer's padding box; the outset (e.g. the
+     composer's border width) lines it up with the outer edge instead. */
+  .chat-composer > .slash-menu {
+    position: absolute;
+    bottom: calc(100% + var(--chat-composer-slash-menu-outset, 0px));
+    left: calc(-1 * var(--chat-composer-slash-menu-outset, 0px));
+    right: calc(-1 * var(--chat-composer-slash-menu-outset, 0px));
+    margin-bottom: var(--chat-composer-slash-menu-gap, 8px);
+    overflow: hidden;
+    z-index: var(--chat-composer-slash-menu-z-index, 30);
+    background: var(--chat-composer-slash-menu-background, #ffffff);
+    border: var(--chat-composer-slash-menu-border, 1px solid #e4e4e7);
+    border-radius: var(--chat-composer-slash-menu-border-radius, 12px);
+    box-shadow: var(--chat-composer-slash-menu-box-shadow, 0 8px 24px rgb(0 0 0 / 12%));
+  }
+
+  .slash-menu > .slash-list {
+    list-style: none;
+    margin: 0;
+    padding: var(--chat-composer-slash-list-padding, 4px);
+    max-height: var(--chat-composer-slash-list-max-height, 280px);
+    overflow-y: auto;
+    display: grid;
+    gap: var(--chat-composer-slash-list-gap, 2px);
+  }
+
+  .slash-menu .slash-list li {
+    min-width: 0;
+  }
+
+  .slash-menu > .slash-foot {
+    padding: var(--chat-composer-slash-foot-padding, 4px 12px);
+    border-top: var(--chat-composer-slash-foot-border, 1px solid #e4e4e7);
+    font-family: var(--chat-composer-slash-foot-font-family, inherit);
+    font-variant-ligatures: var(--chat-composer-slash-foot-font-variant-ligatures, inherit);
+    font-size: var(--chat-composer-slash-foot-font-size, 12px);
+    color: var(--chat-composer-slash-foot-color, #71717a);
+  }
+
+  /* The default row content (a consumer's slashItem snippet replaces it). */
+  .slash-menu .slash-name {
+    flex-shrink: 0;
+    font-family: var(--chat-composer-slash-name-font-family, monospace);
+    color: var(--chat-composer-slash-name-color, #2563eb);
+  }
+
+  .slash-menu .slash-hint {
+    flex-shrink: 0;
+    font-size: var(--chat-composer-slash-hint-font-size, 12px);
+    color: var(--chat-composer-slash-hint-color, #71717a);
+  }
+
+  .slash-menu .slash-desc {
+    flex: 1;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    color: var(--chat-composer-slash-desc-color, #52525b);
+  }
+
+  /* Default visual for the arrow-key-highlighted row when a consumer hasn't
+     opted into their own selected-state look via slashSelectedItemClasses --
+     without this, the only signal was aria-selected, screen-reader-only.
+     Scoped so a consumer's own class stays authoritative the moment it's
+     supplied: this rule simply never applies then. */
+  .slash-menu .slash-item-selected-default {
+    background: var(--chat-composer-slash-item-selected-background, #f4f4f5);
+  }
+
+  .slash-menu .slash-badge {
+    padding: var(--chat-composer-slash-badge-padding, 2px 8px);
+    border-radius: var(--chat-composer-slash-badge-border-radius, 999px);
+    font-size: var(--chat-composer-slash-badge-font-size, 12px);
+    background: var(--chat-composer-slash-badge-background, #eff6ff);
+    color: var(--chat-composer-slash-badge-color, #2563eb);
+  }
+
   /* Visually hidden but still read by assistive technology -- same pattern
      Table's caption and Label's required marker use. */
   .sr-only {

package/dist/ChatComposer/properties.d.ts

@@ -92,6 +92,31 @@ export type OptionalChatComposerProperties = {
     statusText?: string;
     /** Test id on the status region (see `statusText`). */
     statusTestId?: string;
+    /**
+     * Opt-in slash-command menu. With commands passed, typing "/" opens a
+     * listbox of the ones that match (name prefix, or the text after "/" found
+     * in a description); arrows move, Tab completes, Enter picks (Enter on a
+     * complete match submits), Escape dismisses -- through the shared
+     * dismissible stack, so an overlay above the composer closes first. A
+     * command with `choices` keeps the menu open past the space for a second
+     * stage listing them. `null` (the default) turns the whole feature off.
+     */
+    slashCommands?: ChatComposerSlashCommand[] | null;
+    /** Accessible name of the slash-command listbox. Defaults to 'slash commands'. */
+    slashMenuAriaLabel?: string;
+    /** Key-hint line under the slash-command list. */
+    slashMenuHint?: string;
+    /** Class(es) on the slash-command panel (e.g. the consumer's own panel look). */
+    slashMenuClasses?: string;
+    /** Class(es) on every slash-command row's Button. */
+    slashItemClasses?: string;
+    /** Class(es) added to the highlighted slash-command row's Button. */
+    slashSelectedItemClasses?: string;
+    /**
+     * Renders a slash-command row's content (the command, whether it is
+     * highlighted). Omitted: name, argument hint, description and badge.
+     */
+    slashItem?: Snippet<[ChatComposerSlashCommand, boolean]>;
     testId?: string;
     /** Test id emitted as `data-pw` on the textarea itself (none by default). */
     inputTestId?: string;
@@ -156,3 +181,20 @@ export type ChatComposerEventProperties = {
      */
     onaction?: () => void;
 };
+/** A value a slash command's argument can take (its second menu stage). */
+export type ChatComposerSlashCommandChoice = {
+    value: string;
+    description?: string;
+};
+/** One entry of ChatComposer's slash-command menu. */
+export type ChatComposerSlashCommand = {
+    /** Including the slash, e.g. "/model". */
+    name: string;
+    description?: string;
+    /** Shown after the name, e.g. "[model]". */
+    argumentHint?: string;
+    /** Enumerable argument values: picking the command lists these next. */
+    choices?: ChatComposerSlashCommandChoice[];
+    /** A short tag on the row, e.g. where the command comes from. */
+    badge?: string;
+};

package/dist/ChatMessageList/ChatMessageList.svelte

@@ -85,10 +85,30 @@
     reportScrollState(event.currentTarget);
   }
 
-  export function scrollToBottom(): void {
+  /**
+   * `behavior`, when supplied, sets the list's inline `scroll-behavior` for
+   * just this call (outranking, not changing, its custom-property default),
+   * then clears it on the next frame so it cannot linger onto a later scroll
+   * this function did not cause. The CSS property has no `instant` keyword --
+   * the browser silently drops it -- so `'instant'` is written as `auto`, and
+   * reduced-motion turns `'smooth'` into `auto` as well.
+   */
+  export function scrollToBottom(behavior?: 'smooth' | 'instant'): void {
     if (listEl !== null) {
+      const hasBehavior = typeof behavior === 'string';
+      if (hasBehavior) {
+        const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+        listEl.style.scrollBehavior =
+          behavior === 'smooth' && !prefersReducedMotion ? 'smooth' : 'auto';
+      }
       listEl.scrollTop = listEl.scrollHeight;
       reportScrollState(listEl);
+      if (hasBehavior) {
+        const node = listEl;
+        requestAnimationFrame(() => {
+          node.style.scrollBehavior = '';
+        });
+      }
     }
   }
 
@@ -316,7 +336,7 @@
 
     {#if showJump && jump}
       <div class="jump">
-        <Button onclick={scrollToBottom} ariaLabel={jumpLabel}>
+        <Button onclick={() => scrollToBottom()} ariaLabel={jumpLabel}>
           {#if typeof jumpIcon === 'function'}
             {@render jumpIcon()}
           {:else}

package/dist/ChatMessageList/ChatMessageList.svelte.d.ts

@@ -1,6 +1,6 @@
 import type { ChatMessageListProperties } from './properties';
 declare const ChatMessageList: import("svelte").Component<ChatMessageListProperties, {
-    scrollToBottom: () => void;
+    scrollToBottom: (behavior?: "smooth" | "instant") => void;
 }, "">;
 type ChatMessageList = ReturnType<typeof ChatMessageList>;
 export default ChatMessageList;

package/dist/CommandMenu/CommandMenu.svelte

@@ -9,6 +9,10 @@
   import Img from '../Img/Img.svelte';
   import searchSvg from '../assets/search.svg?raw';
 
+  function defaultFilter(item: CommandItem, needle: string): boolean {
+    return item.label.toLowerCase().includes(needle.toLowerCase());
+  }
+
   let {
     items,
     open = $bindable(false),
@@ -16,10 +20,15 @@
     emptyText = 'No results found.',
     testId,
     itemIcon,
+    itemSnippet,
     searchIcon,
+    enableHotkey = true,
+    filterFn = defaultFilter,
     onselect,
     onclose,
-    classes
+    classes,
+    ariaLabel = 'Command menu',
+    clearStateOnClose = false
   }: CommandMenuProperties = $props();
 
   // Stable per-instance ids keep ARIA references distinct across menus.
@@ -61,8 +70,7 @@
     if (query.trim() === '') {
       return items;
     }
-    const lower = query.toLowerCase();
-    return items.filter((item) => item.label.toLowerCase().includes(lower));
+    return items.filter((item) => filterFn(item, query));
   });
 
   let groupedItems = $derived.by(() => {
@@ -231,7 +239,17 @@
     }
   }
 
+  // No focus or typing guard: this listener fires from anywhere, including inside a text
+  // field or a terminal. A consumer whose hotkey character can legitimately be typed
+  // (Ctrl+K in a shell is kill-line) sets enableHotkey={false} and drives `open` itself from
+  // a listener that knows what is focused. The listener stays the plain window listener it
+  // always was, added in onMount and removed in onDestroy, so its timing and its order
+  // against other listeners are unchanged; the opt-out is read per event, which also makes
+  // toggling enableHotkey after mount take effect immediately.
   function handleGlobalKeyDown(event: KeyboardEvent) {
+    if (!enableHotkey) {
+      return;
+    }
     if ((event.metaKey || event.ctrlKey) && event.key === 'k') {
       event.preventDefault();
       if (open) {
@@ -293,6 +311,17 @@
       destroy() {
         releaseDismissible();
         unlockBodyScroll();
+        // Opt-in only (clearStateOnClose): a controlled parent can set
+        // `open = false` without calling close(), and the overlay action still
+        // unmounts on every close path either way -- this is the lifecycle
+        // backstop that clears stale search state on reopen, for a consumer
+        // who asked for it. Off by default so an existing consumer's typed
+        // query/highlight keep surviving an externally-controlled close
+        // exactly as before this prop existed.
+        if (clearStateOnClose) {
+          query = '';
+          activeIndex = 0;
+        }
         if (openerElement !== null) {
           openerElement.focus();
           openerElement = null;
@@ -337,7 +366,7 @@
     onkeydown={handleKeyDown}
     role="dialog"
     aria-modal="true"
-    aria-label="Command menu"
+    aria-label={ariaLabel}
     tabindex="-1"
     inert={!open}
     data-pw={typeof testId === 'string' ? testId : null}
@@ -412,22 +441,26 @@
                 data-pw={typeof testId === 'string' ? `${testId}-item-${item.value}` : null}
                 testID={typeof testId === 'string' ? `${testId}-item-${item.value}` : null}
               >
-                {#if typeof itemIcon === 'function'}
-                  <span class="command-menu-item-icon">
-                    {@render itemIcon(item)}
-                  </span>
-                {:else if typeof item.icon === 'string' && item.icon.length > 0}
-                  <div class="command-menu-item-icon-img-wrapper">
-                    <Img inlineSvg src={item.icon} alt="" />
-                  </div>
-                {/if}
-                <span class="command-menu-item-label">{item.label}</span>
-                {#if typeof item.shortcut === 'string' && item.shortcut.length > 0}
-                  <span class="command-menu-item-shortcut">
-                    {#each item.shortcut.split('+') as key, i (i)}
-                      <kbd class="command-menu-kbd">{key.trim()}</kbd>
-                    {/each}
-                  </span>
+                {#if typeof itemSnippet === 'function'}
+                  {@render itemSnippet(item, index === activeIndex)}
+                {:else}
+                  {#if typeof itemIcon === 'function'}
+                    <span class="command-menu-item-icon">
+                      {@render itemIcon(item)}
+                    </span>
+                  {:else if typeof item.icon === 'string' && item.icon.length > 0}
+                    <div class="command-menu-item-icon-img-wrapper">
+                      <Img inlineSvg src={item.icon} alt="" />
+                    </div>
+                  {/if}
+                  <span class="command-menu-item-label">{item.label}</span>
+                  {#if typeof item.shortcut === 'string' && item.shortcut.length > 0}
+                    <span class="command-menu-item-shortcut">
+                      {#each item.shortcut.split('+') as key, i (i)}
+                        <kbd class="command-menu-kbd">{key.trim()}</kbd>
+                      {/each}
+                    </span>
+                  {/if}
                 {/if}
               </button>
             {/each}

package/dist/CommandMenu/properties.d.ts

@@ -17,8 +17,32 @@ export type OptionalCommandMenuProperties = {
     emptyText?: string;
     testId?: string;
     itemIcon?: Snippet<[CommandItem]>;
+    /** Replaces the default icon/label/shortcut row entirely. Receives the item and whether it is the active (arrow-key-highlighted) row. */
+    itemSnippet?: Snippet<[CommandItem, boolean]>;
     searchIcon?: Snippet;
+    /**
+     * Attaches the built-in `Cmd/Ctrl+K` window listener. Default `true`. This
+     * listener has no focus or typing guard — it fires from inside a text
+     * field or a terminal exactly as it does anywhere else. Set `false` when
+     * the hotkey character can legitimately be typed (Ctrl+K is kill-line in
+     * a shell) and drive `open` from the consumer's own guarded listener
+     * instead; the bindable `open` prop is then the sole control.
+     */
+    enableHotkey?: boolean;
+    /** Mirrors Combobox's filterFn. Default matches `item.label` case-insensitively; a consumer with more than a label to search on (a hint, a path) supplies its own. */
+    filterFn?: (item: CommandItem, query: string) => boolean;
     classes?: string;
+    /** Accessible name of the dialog. Default `'Command menu'`. */
+    ariaLabel?: string;
+    /**
+     * Default `false`. A controlled parent can set `open = false` without
+     * calling the component's own `close()` -- the overlay still unmounts on
+     * every close path either way, so `true` clears the typed search query and
+     * highlighted index on that unmount too, not only on an internal close.
+     * Left off by default so an existing consumer's typed state keeps
+     * surviving an externally-controlled close exactly as before.
+     */
+    clearStateOnClose?: boolean;
 };
 export type CommandMenuEventProperties = {
     onselect?: (item: CommandItem) => void;