@pmate/chat-sdk 0.12.0-next.70 → 0.12.0-next.71

package/README.md

@@ -289,3 +289,21 @@ The persistent group cache is capped at 64 groups / 1MiB, with 128KiB records,
 identities are stored separately without rosters; repeated registrations share
 one write, concurrent lookups use bulk reads, and a concurrent memory-hit burst
 shares one fresh authority read without retaining authorization across bursts. Scope withdrawal retires both.
+
+
+## Slash command suggestions
+
+### Background
+
+Host applications know which commands are available in a conversation. The shared desktop/mobile inputs now display that catalog while typing a leading `/`, without coupling the SDK to a particular bot or executing commands from the picker.
+
+```tsx
+<ChatInputDesktop commands={{ commands: [
+  { name: "review", description: "Review code", usage: "PR URL or branch" },
+  { name: "qa", description: "Run independent tests", usage: "PR URL" },
+] }} mentions={groupMembers} onSend={sendMessage} />
+```
+
+The same prop is supported by `ChatInputMobile`. Names omit the leading slash. Arrow keys navigate, Enter/Tab inserts a command and a space, Escape closes; touch selection edits the draft only. Command arguments and existing member mentions are preserved. IME composition, URLs and slashes in ordinary body text do not trigger command execution. Omit `commands` for unsupported conversations.
+
+Host-owned textareas can use `useComposerSuggestions({ value, onChange, mentions, commands, disabled })`, spread `inputProps`, render `MentionMenu` with `menuProps` and `CommandMenu` with `commandMenuProps`, and send `getMentions()` with the untrimmed value.

package/lib/commands.d.ts

@@ -0,0 +1,20 @@
+/** Host-owned command catalog. Selecting a suggestion edits the draft only. */
+export type ChatCommand = {
+    name: string;
+    description: string;
+    usage?: string;
+};
+export type ChatCommandConfig = {
+    commands: ChatCommand[];
+    label?: string;
+    emptyText?: string;
+};
+export declare function commandQuery(value: string, caret: number): {
+    query: string;
+    end: number;
+} | null;
+export declare function filterCommands(commands: ChatCommand[], query: string): ChatCommand[];
+export declare function completeCommand(value: string, end: number, command: ChatCommand): {
+    text: string;
+    caret: number;
+};

package/lib/commands.js

@@ -0,0 +1,12 @@
+export function commandQuery(value, caret) {
+    const match = /^\/([^\s/]*)(?=\s|$)/.exec(value);
+    return match && caret >= 1 && caret <= match[0].length ? { query: value.slice(1, caret).toLowerCase(), end: match[0].length } : null;
+}
+export function filterCommands(commands, query) {
+    return commands.filter(c => /^[a-z][a-z0-9-]*$/.test(c.name) && c.name.toLowerCase().startsWith(query));
+}
+export function completeCommand(value, end, command) {
+    const prefix = `/${command.name}`, suffix = value.slice(end);
+    const text = prefix + (suffix || " ");
+    return { text, caret: prefix.length + 1 };
+}

package/lib/components/ChatInputDesktop.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { handleImagePaste } from "../ux/imagePaste";
-import { useMentions } from "../hooks/useMentions";
+import { useComposerSuggestions } from "../hooks/useComposerSuggestions";
+import { CommandMenu } from "./CommandMenu";
 import { MentionMenu } from "./MentionMenu";
 import React from "react";
 import { Provider, createStore } from "jotai";
@@ -25,8 +26,8 @@ function DesktopInner(props) {
     const tokens = mergeChatInputTokens(props.tokens);
     const state = useChatInputState();
     const attachments = useAttachmentState();
-    const mentions = useMentions({
-        value: state.text, config: props.mentions, disabled: props.disabled || state.status === "sending" || state.mode === "voice",
+    const mentions = useComposerSuggestions({
+        value: state.text, mentions: props.mentions, commands: props.commands, disabled: props.disabled || state.status === "sending" || state.mode === "voice",
         onChange(value) { state.setText(value); state.setStatus(value.trim() ? "typing" : "idle"); props.onChange?.(value); },
     });
     const [isEmojiOpen, setIsEmojiOpen] = useState(false);
@@ -186,7 +187,7 @@ function DesktopInner(props) {
         alignSelf: "center",
         transition: `color ${tokens.motion.stateTransition}, transform ${tokens.motion.pressFeedback}`,
     };
-    return (_jsxs("div", { style: { position: "relative", width: "100%" }, children: [_jsx(MentionMenu, { ...mentions.menuProps, tokens: tokens }), _jsxs("div", { className: "grid gap-3", style: { position: "relative", width: "100%" }, children: [_jsx("input", { ref: imageInputRef, type: "file", accept: props.image?.accept ?? "image/*", style: { display: "none" }, onChange: (event) => {
+    return (_jsxs("div", { style: { position: "relative", width: "100%" }, children: [_jsx(MentionMenu, { ...mentions.menuProps, tokens: tokens }), _jsx(CommandMenu, { ...mentions.commandMenuProps, tokens: tokens }), _jsxs("div", { className: "grid gap-3", style: { position: "relative", width: "100%" }, children: [_jsx("input", { ref: imageInputRef, type: "file", accept: props.image?.accept ?? "image/*", style: { display: "none" }, onChange: (event) => {
                             const file = event.target.files?.[0];
                             if (file) {
                                 void handleImageFile(file);

package/lib/components/ChatInputMobile.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { handleImagePaste } from "../ux/imagePaste";
-import { useMentions } from "../hooks/useMentions";
+import { useComposerSuggestions } from "../hooks/useComposerSuggestions";
+import { CommandMenu } from "./CommandMenu";
 import { MentionMenu } from "./MentionMenu";
 import React from "react";
 import { Provider, createStore } from "jotai";
@@ -26,8 +27,8 @@ function MobileInner(props) {
     const tokens = mergeChatInputTokens(props.tokens);
     const state = useChatInputState();
     const attachments = useAttachmentState();
-    const mentions = useMentions({
-        value: state.text, config: props.mentions, disabled: props.disabled || state.status === "sending" || state.mode === "voice",
+    const mentions = useComposerSuggestions({
+        value: state.text, mentions: props.mentions, commands: props.commands, disabled: props.disabled || state.status === "sending" || state.mode === "voice",
         onChange(value) { state.setText(value); state.setStatus(value.trim() ? "typing" : "idle"); props.onChange?.(value); },
     });
     const [recordingChoice, setRecordingChoice] = useState("send");
@@ -267,7 +268,7 @@ function MobileInner(props) {
             userSelect: "none",
             WebkitUserSelect: "none",
             WebkitTouchCallout: "none",
-        }, children: [_jsx(MentionMenu, { ...mentions.menuProps, tokens: tokens }), isRecordingOverlayVisible ? (_jsxs("div", { style: {
+        }, children: [_jsx(MentionMenu, { ...mentions.menuProps, tokens: tokens }), _jsx(CommandMenu, { ...mentions.commandMenuProps, tokens: tokens }), isRecordingOverlayVisible ? (_jsxs("div", { style: {
                     position: "fixed",
                     left: "50%",
                     bottom: "calc(72px + env(safe-area-inset-bottom, 0px))",

package/lib/components/CommandMenu.d.ts

@@ -0,0 +1,15 @@
+import type { RefObject } from "react";
+import type { ChatCommand } from "../commands";
+import type { ChatInputTokens, DeepPartial } from "../types/chatInput";
+export declare function CommandMenu({ id, open, candidates, activeIndex, onSelect, onActiveIndex, menuRef, label, emptyText, tokens: overrides }: {
+    id: string;
+    open: boolean;
+    candidates: ChatCommand[];
+    activeIndex: number;
+    onSelect: (c: ChatCommand) => void;
+    onActiveIndex: (i: number) => void;
+    menuRef: RefObject<HTMLDivElement | null>;
+    label: string;
+    emptyText: string;
+    tokens?: DeepPartial<ChatInputTokens>;
+}): import("react/jsx-runtime").JSX.Element | null;

package/lib/components/CommandMenu.js

@@ -0,0 +1,10 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import React, { useEffect } from "react";
+import { mergeChatInputTokens } from "../tokens/defaultTokens";
+export function CommandMenu({ id, open, candidates, activeIndex, onSelect, onActiveIndex, menuRef, label, emptyText, tokens: overrides }) {
+    const tokens = mergeChatInputTokens(overrides);
+    useEffect(() => { menuRef.current?.querySelector('[aria-selected="true"]')?.scrollIntoView({ block: "nearest" }); }, [activeIndex, open]);
+    if (!open)
+        return null;
+    return _jsx("div", { id: id, ref: menuRef, role: "listbox", "aria-label": label, style: { position: "absolute", bottom: "calc(100% + 8px)", left: 0, width: "min(420px, 100%)", maxHeight: "min(320px, 40dvh)", overflowY: "auto", overscrollBehavior: "contain", zIndex: 20, boxSizing: "border-box", padding: 6, borderRadius: tokens.radius.inputSurface, border: `1px solid ${tokens.color.borderDefault}`, background: tokens.color.surfaceInputFocus, color: tokens.color.textPrimary, boxShadow: tokens.shadow.inputElevated, fontFamily: tokens.typography.familyBase }, children: candidates.length ? candidates.map((c, i) => _jsxs("button", { id: `${id}-${i}`, type: "button", role: "option", "aria-selected": i === activeIndex, tabIndex: -1, onMouseDown: e => e.preventDefault(), onMouseMove: () => onActiveIndex(i), onClick: () => onSelect(c), style: { display: "block", width: "100%", minHeight: 48, padding: "9px 12px", border: 0, borderRadius: 8, textAlign: "left", cursor: "pointer", color: "inherit", background: i === activeIndex ? `color-mix(in srgb, ${tokens.color.brandPrimary} 14%, ${tokens.color.surfaceInputFocus})` : "transparent" }, children: [_jsxs("span", { style: { display: "block", overflowWrap: "anywhere", fontSize: tokens.typography.inputText.size }, children: [_jsxs("strong", { style: { color: tokens.color.brandPrimary }, children: ["/", c.name] }), c.usage ? _jsx("span", { style: { marginLeft: 8, fontSize: 12, color: tokens.color.textSecondary }, children: c.usage }) : null] }), _jsx("small", { style: { display: "block", marginTop: 3, color: tokens.color.textSecondary }, children: c.description })] }, c.name)) : _jsx("div", { role: "status", style: { padding: 12, color: tokens.color.textSecondary }, children: emptyText }) });
+}

package/lib/hooks/useComposerSuggestions.d.ts

@@ -0,0 +1,50 @@
+import type { ChangeEvent, KeyboardEvent, SyntheticEvent } from "react";
+import { type ChatCommand, type ChatCommandConfig } from "../commands";
+import type { MentionConfig } from "../mentions/model";
+/** One input contract for host-owned composers, SDK inputs, @ mentions and / commands. */
+export declare function useComposerSuggestions({ value, onChange, mentions: config, commands, disabled }: {
+    value: string;
+    onChange: (value: string) => void;
+    mentions?: MentionConfig;
+    commands?: ChatCommandConfig;
+    disabled?: boolean;
+}): {
+    getMentions: () => import("..").ChatMention[];
+    menuProps: {
+        open: boolean;
+        id: string;
+        candidates: import("..").MentionCandidate[];
+        activeIndex: number;
+        onSelect: (candidate: import("..").MentionCandidate) => void;
+        onActiveIndex: import("react").Dispatch<import("react").SetStateAction<number>>;
+        menuRef: import("react").RefObject<HTMLDivElement | null>;
+        label: string;
+        emptyText: string;
+    };
+    commandMenuProps: {
+        id: string;
+        open: boolean;
+        candidates: ChatCommand[];
+        activeIndex: number;
+        onSelect: (command: ChatCommand) => void;
+        onActiveIndex: import("react").Dispatch<import("react").SetStateAction<number>>;
+        menuRef: import("react").RefObject<HTMLDivElement | null>;
+        label: string;
+        emptyText: string;
+    };
+    inputProps: {
+        onChange(event: ChangeEvent<HTMLTextAreaElement>): void;
+        onSelect(event: SyntheticEvent<HTMLTextAreaElement>): void;
+        onFocus(event: SyntheticEvent<HTMLTextAreaElement>): void;
+        onBlur(event: React.FocusEvent<HTMLTextAreaElement>): void;
+        onCompositionStart(): void;
+        onCompositionEnd(event: SyntheticEvent<HTMLTextAreaElement>): void;
+        onKeyDown(event: KeyboardEvent<HTMLTextAreaElement>): void;
+        role?: "combobox" | undefined;
+        "aria-autocomplete"?: "list" | undefined;
+        "aria-haspopup"?: "listbox" | undefined;
+        "aria-expanded"?: boolean | undefined;
+        "aria-controls"?: string | undefined;
+        "aria-activedescendant"?: string | undefined;
+    };
+};

package/lib/hooks/useComposerSuggestions.js

@@ -0,0 +1,70 @@
+import { useId, useLayoutEffect, useRef, useState } from "react";
+import { useMentions } from "./useMentions";
+import { commandQuery, completeCommand, filterCommands } from "../commands";
+/** One input contract for host-owned composers, SDK inputs, @ mentions and / commands. */
+export function useComposerSuggestions({ value, onChange, mentions: config, commands, disabled = false }) {
+    const mentions = useMentions({ value, onChange, config, disabled });
+    const id = useId(), inputRef = useRef(null), menuRef = useRef(null);
+    const pending = useRef(null);
+    const [caret, setCaret] = useState(0), [focused, setFocused] = useState(false), [composing, setComposing] = useState(false);
+    const [dismissed, setDismissed] = useState(false), [selected, setSelected] = useState(0), [collapsed, setCollapsed] = useState(true);
+    const query = commands?.commands.length && focused && collapsed && !composing && !disabled && !dismissed ? commandQuery(value, caret) : null;
+    const candidates = query ? filterCommands(commands.commands, query.query) : [];
+    const index = Math.min(selected, Math.max(0, candidates.length - 1));
+    useLayoutEffect(() => {
+        if (pending.current?.text !== value)
+            return;
+        const position = pending.current.caret;
+        pending.current = null;
+        inputRef.current?.focus({ preventScroll: true });
+        inputRef.current?.setSelectionRange(position, position);
+        setCaret(position);
+    }, [value]);
+    function observe(event) {
+        inputRef.current = event.currentTarget;
+        setCaret(event.currentTarget.selectionStart);
+        setCollapsed(event.currentTarget.selectionStart === event.currentTarget.selectionEnd);
+    }
+    function select(command) {
+        if (!query)
+            return;
+        const next = completeCommand(value, query.end, command);
+        pending.current = next;
+        setDismissed(true);
+        onChange(next.text);
+    }
+    return {
+        getMentions: mentions.getMentions,
+        menuProps: { ...mentions.menuProps, open: mentions.menuProps.open && !query },
+        commandMenuProps: { id, open: Boolean(query), candidates, activeIndex: index, onSelect: select, onActiveIndex: setSelected, menuRef, label: commands?.label ?? "选择命令", emptyText: commands?.emptyText ?? "没有匹配的命令" },
+        inputProps: {
+            ...mentions.inputProps,
+            ...(commands ? { role: "combobox", "aria-autocomplete": "list", "aria-haspopup": "listbox", "aria-expanded": Boolean(query || mentions.menuProps.open), "aria-controls": query ? id : mentions.inputProps["aria-controls"], "aria-activedescendant": query && candidates[index] ? `${id}-${index}` : mentions.inputProps["aria-activedescendant"] } : {}),
+            onChange(event) { observe(event); setDismissed(false); setSelected(0); mentions.inputProps.onChange(event); },
+            onSelect(event) { observe(event); mentions.inputProps.onSelect(event); },
+            onFocus(event) { observe(event); setFocused(true); mentions.inputProps.onFocus(event); },
+            onBlur(event) { if (!menuRef.current?.contains(event.relatedTarget))
+                setFocused(false); mentions.inputProps.onBlur(event); },
+            onCompositionStart() { setComposing(true); mentions.inputProps.onCompositionStart(); },
+            onCompositionEnd(event) { setComposing(false); setDismissed(false); observe(event); mentions.inputProps.onCompositionEnd(event); },
+            onKeyDown(event) {
+                if (query && !event.nativeEvent.isComposing && event.keyCode !== 229) {
+                    if (event.key === "Escape") {
+                        event.preventDefault();
+                        setDismissed(true);
+                    }
+                    else if (candidates.length && ["ArrowDown", "ArrowUp"].includes(event.key)) {
+                        event.preventDefault();
+                        setSelected((index + (event.key === "ArrowDown" ? 1 : candidates.length - 1)) % candidates.length);
+                    }
+                    else if (candidates[index] && ["Enter", "Tab"].includes(event.key) && !event.shiftKey && !event.metaKey && !event.ctrlKey && !event.altKey) {
+                        event.preventDefault();
+                        select(candidates[index]);
+                    }
+                }
+                if (!event.defaultPrevented)
+                    mentions.inputProps.onKeyDown(event);
+            },
+        },
+    };
+}

package/lib/index.d.ts

@@ -43,3 +43,6 @@ export * from "./hooks/useImageAttachments";
 export * from "./components/ImageAttachmentTray";
 export { createChat, type Chat, ChatError, type ChatThreadSnapshot, type ChatMessage as MessageView, type ChatErrorCode, type ConversationTarget, type OutgoingContent, type CreateChatOptions, type ChatSnapshot, type SentMessage, type ReadOptions, type ReadersQuery, type GroupChanges } from "./chat.js";
 export { useChatSnapshot } from "./hooks/useChatSnapshot.js";
+export * from "./commands";
+export * from "./components/CommandMenu";
+export * from "./hooks/useComposerSuggestions";

package/lib/index.js

@@ -43,3 +43,6 @@ export * from "./hooks/useImageAttachments";
 export * from "./components/ImageAttachmentTray";
 export { createChat, ChatError } from "./chat.js";
 export { useChatSnapshot } from "./hooks/useChatSnapshot.js";
+export * from "./commands";
+export * from "./components/CommandMenu";
+export * from "./hooks/useComposerSuggestions";

package/lib/types/chatInput.d.ts

@@ -1,3 +1,4 @@
+import type { ChatCommandConfig } from "../commands";
 import type { MentionConfig, ChatMention } from "../mentions/model";
 import type { ClipboardEventHandler, ComponentType, DragEventHandler, ReactNode } from "react";
 import type { ChatAttachment } from "./attachment";
@@ -121,6 +122,8 @@ export type ChatImageConfig = {
     uploadImage?: (file: File) => Promise<ChatImageUploadResult>;
 };
 export type ChatInputBaseProps = {
+    /** Host-provided slash commands; omit to disable command suggestions. Selection never sends. */
+    commands?: ChatCommandConfig;
     /** Group members supplied by the host; omit for ordinary text input. */
     mentions?: MentionConfig;
     /** Use a taller composer with actions in a bottom toolbar. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/chat-sdk",
-  "version": "0.12.0-next.70",
+  "version": "0.12.0-next.71",
   "description": "Local-first chat SDK, message subscriptions, reading state, and shared chat UI primitives",
   "type": "module",
   "main": "./lib/index.js",