@intentface/chat 0.1.0

package/dist/composer/types.d.ts

@@ -0,0 +1,126 @@
+import type { AttachmentItem } from "../attachments/index.js";
+import type { ChipData, ChipIconKey } from "../chip-markdown.js";
+export type AskUserOption = {
+    label: string;
+    description?: string;
+};
+export type AskUserQuestion = {
+    question: string;
+    options: AskUserOption[];
+    multiSelect?: boolean;
+};
+export type CommandItemKind = "insert" | "execute";
+/**
+ * Where a prefix is allowed to open its command list.
+ *
+ * - `doc-start` — only when the prefix is the very first thing in the document
+ *   (the `/` slash-command convention).
+ * - `word-boundary` — at the start of a line or after whitespace, so `@` opens
+ *   a mention but the `@` in `user@example.com` does not.
+ */
+export type TriggerRule = "doc-start" | "word-boundary";
+export type { ChipData };
+export type ComposerEditorHandle = {
+    focus: () => void;
+    blur: () => void;
+    clear: () => void;
+    insertText: (text: string) => void;
+    insertChip: (chip: ChipData) => void;
+};
+export type RegisteredEditor = ComposerEditorHandle & {
+    getText: () => string;
+    setText: (text: string) => void;
+    serialize: () => {
+        text: string;
+    };
+    isFocused: () => boolean;
+    /** The editable root element — event scoping and badge queries anchor to it. */
+    getRootElement: () => HTMLElement | null;
+    getSnapshot: () => ComposerSnapshot;
+    applySnapshot: (snapshot: ComposerSnapshot) => void;
+    /** Replace the active trigger token with a chip, plus a trailing space unless one follows. */
+    insertChipAtTrigger: (chip: ChipData) => void;
+    /** Remove the active trigger token (execute-kind command selections). */
+    deleteTrigger: () => void;
+    /** Close the command popup state after a selection committed. */
+    closeCommands: () => void;
+    /** Refocus the editor and close the command popup — the Escape/Dismiss path. */
+    dismissCommands: () => void;
+};
+export type AttachmentsApi = {
+    add: (files: File[] | FileList) => void;
+    remove: (id: string) => void;
+    openFileDialog: () => void;
+};
+export type PrefixOnSelectContext = {
+    editor: ComposerEditorHandle;
+    attachments: AttachmentsApi;
+};
+export type CommandItemData = {
+    value: string;
+    label: string;
+    description?: string;
+    icon?: ChipIconKey;
+    keywords?: string;
+    /**
+     * Renders the row inert (aria-disabled / data-disabled) and removes it from
+     * keyboard navigation and selection. Disabled rows still match the filter.
+     */
+    disabled?: boolean;
+    onSelect?: (context: PrefixOnSelectContext) => void;
+};
+/**
+ * Opaque editor content for the controlled `value` / `defaultValue` API. Treat
+ * it as a token: persist and hand it back, but don't read into `__doc` — the
+ * payload shape is an implementation detail (currently paragraph JSON).
+ */
+export type ComposerSnapshot = {
+    readonly __doc: object;
+    readonly __brand: "ComposerSnapshot";
+};
+export type ComposerMessageSubmit = {
+    kind: "message";
+    text: string;
+    files: AttachmentItem[];
+};
+export type ComposerAnswerEntry = {
+    question: string;
+    option: string;
+} | {
+    question: string;
+    text: string;
+} | {
+    question: string;
+    options: string[];
+    text: string;
+} | {
+    question: string;
+};
+export type ComposerAnswersSubmit = {
+    kind: "answers";
+    answers: ComposerAnswerEntry[];
+};
+export type ComposerSubmitData = ComposerMessageSubmit | ComposerAnswersSubmit;
+export type ComposerCommandsItems = CommandItemData[] | ((query: string, options: {
+    signal: AbortSignal;
+}) => CommandItemData[] | Promise<CommandItemData[]>);
+export type ComposerCommandsConfig = {
+    kind: CommandItemKind;
+    trigger: TriggerRule;
+    items: ComposerCommandsItems;
+    /**
+     * Ghost-text completion of the highlighted item in the active token
+     * (data-command-suggestion). Defaults to true; turn off per prefix when the
+     * highlight is unstable (e.g. async sources re-ranking while typing).
+     */
+    suggestion?: boolean;
+    /**
+     * Per-prefix hint shown while the query is empty, rendered into the badge's
+     * hint element (span[data-command-hint]). Defaults to "Type to
+     * filter". Never shows alongside a suggestion — one hint slot, suggestion
+     * wins — so this is the resident hint for suggestion: false prefixes and
+     * the fallback when nothing can complete.
+     */
+    placeholder?: string;
+};
+export type ComposerCommandsMap = Record<string, ComposerCommandsConfig>;

package/dist/composer/types.js

@@ -0,0 +1,4 @@
+// Public composer types — the wire-level contracts consumers interact with:
+// command configs, submit payloads, the opaque editor snapshot, and the
+// imperative editor/attachments APIs.
+export {};

package/dist/composer/use-composer-editor.d.ts

@@ -0,0 +1,43 @@
+import { type ClipboardEventHandler, type FocusEventHandler, type KeyboardEventHandler, type ReactNode } from "react";
+import { type ChipData } from "../chip-markdown.js";
+import { type ComposerSubmitOn } from "./keyboard.js";
+export type UseComposerEditorOptions = {
+    disabled: boolean;
+    autoFocus: boolean;
+    maxLength?: number;
+    /** Which Enter chord sends; the other soft-breaks. Defaults to "enter". */
+    submitOn?: ComposerSubmitOn;
+    value?: string;
+    onValueChange?: (text: string) => void;
+    renderChip?: (chip: ChipData) => ReactNode;
+    onFocus?: FocusEventHandler<HTMLDivElement>;
+    onBlur?: FocusEventHandler<HTMLDivElement>;
+    onKeyDown?: KeyboardEventHandler<HTMLDivElement>;
+    onKeyUp?: KeyboardEventHandler<HTMLDivElement>;
+    onPaste?: ClipboardEventHandler<HTMLDivElement>;
+    onCopy?: ClipboardEventHandler<HTMLDivElement>;
+    onCut?: ClipboardEventHandler<HTMLDivElement>;
+};
+export type ComposerEditableProps = {
+    onFocus: FocusEventHandler<HTMLDivElement>;
+    onBlur: FocusEventHandler<HTMLDivElement>;
+    onKeyDown: KeyboardEventHandler<HTMLDivElement>;
+    onKeyUp: KeyboardEventHandler<HTMLDivElement>;
+    onPaste: ClipboardEventHandler<HTMLDivElement>;
+    onCopy: ClipboardEventHandler<HTMLDivElement>;
+    onCut: ClipboardEventHandler<HTMLDivElement>;
+};
+export type UseComposerEditorResult = {
+    /** Attach to the contenteditable element; returns a React 19 ref cleanup. */
+    attachRoot: (node: HTMLElement | null) => (() => void) | undefined;
+    /** Spread onto the editable: consumer-then-engine composed event handlers. */
+    editableProps: ComposerEditableProps;
+    /** Chip visuals, portaled into the engine-owned inline spans. */
+    chipPortals: ReactNode;
+    hasContent: boolean;
+    /** True while an IME composition is in progress — the placeholder overlay gates on it. */
+    isComposing: boolean;
+    /** The serialized submit text, for the hidden form-input mirror. */
+    serializedText: string;
+};
+export declare const useComposerEditor: (options: UseComposerEditorOptions) => UseComposerEditorResult;