@intentface/ui 0.0.0 → 0.7.0

package/dist/composer/prefix-detection.js

@@ -0,0 +1,67 @@
+// Prefix detection — the engine-agnostic kernel of the command system: the
+// active-token state shape and the pure scan that derives it from the text
+// around the caret. Sticky range tracking and dismissal memory live one layer
+// up, in trigger-tracker.ts.
+// ---------------------------------------------------------------------------
+// Types & constants
+// ---------------------------------------------------------------------------
+// Non-global: `.test` on a global regex advances lastIndex between calls.
+const WHITESPACE = /\s/;
+export const CLOSED_COMMAND_STATE = {
+    isOpen: false,
+    trigger: null,
+    query: "",
+    triggerStartPosition: 0,
+    triggerEndPosition: 0,
+    dismissedAt: null,
+};
+// ---------------------------------------------------------------------------
+// Prefix detection — scan the block around the caret for a registered trigger
+// and derive the active-token state (pure; engine integrations call it).
+// ---------------------------------------------------------------------------
+export const detectActivePrefix = (args) => {
+    const { registered, blockStart, blockEnd, cursorPosition, textBeforeCursor, textAfterCursor, fullDocText, } = args;
+    for (const entry of registered) {
+        if (entry.triggerRule === "doc-start") {
+            if (fullDocText.startsWith(entry.prefix)) {
+                return {
+                    isOpen: true,
+                    trigger: entry.prefix,
+                    query: fullDocText.slice(entry.prefix.length),
+                    triggerStartPosition: blockStart,
+                    triggerEndPosition: blockEnd,
+                    dismissedAt: null,
+                };
+            }
+            continue;
+        }
+        // The token is the contiguous non-whitespace run the caret sits inside,
+        // taken from both sides of the caret so it stays whole as the caret moves
+        // within it. Text chars map 1:1 to positions and an atomic chip can never
+        // sit inside a run, so the run length is the position delta on each side.
+        // Scanned backwards, not /\S*$/ — that backtracks quadratically when the
+        // text ends in whitespace, on a path that runs per keystroke.
+        let runStart = textBeforeCursor.length;
+        while (runStart > 0 && !WHITESPACE.test(textBeforeCursor[runStart - 1]))
+            runStart--;
+        const leftRun = textBeforeCursor.slice(runStart);
+        // Start-anchored, so this one cannot backtrack.
+        const rightRun = textAfterCursor.match(/^\S*/)?.[0] ?? "";
+        const runText = leftRun + rightRun;
+        if (!runText.startsWith(entry.prefix))
+            continue;
+        // The prefix must sit at a word boundary: line start or after whitespace.
+        const charBeforeRun = runStart > 0 ? textBeforeCursor[runStart - 1] : undefined;
+        if (charBeforeRun !== undefined && !WHITESPACE.test(charBeforeRun))
+            continue;
+        return {
+            isOpen: true,
+            trigger: entry.prefix,
+            query: runText.slice(entry.prefix.length),
+            triggerStartPosition: cursorPosition - leftRun.length,
+            triggerEndPosition: cursorPosition + rightRun.length,
+            dismissedAt: null,
+        };
+    }
+    return CLOSED_COMMAND_STATE;
+};

package/dist/composer/root.d.ts

@@ -0,0 +1,21 @@
+import type { PrimitiveProps } from "../internal/primitive-props.js";
+import { type ComposerStore } from "./store.js";
+import type { AskUserQuestion, ComposerCommandsMap, ComposerSnapshot, ComposerSubmitData } from "./types.js";
+export type ComposerRootState = {
+    /** Present as data-submitting while a submission is in flight. */
+    submitting: boolean;
+    /** Present as data-dragging while files are dragged over the drop scope. */
+    dragging: boolean;
+};
+export type ComposerRootProps = Omit<PrimitiveProps<"form", ComposerRootState>, "onSubmit"> & {
+    onSubmit?: (data: ComposerSubmitData) => void | Promise<void>;
+    isSubmitting?: boolean;
+    commands?: ComposerCommandsMap;
+    questions?: AskUserQuestion[];
+    defaultValue?: ComposerSnapshot;
+    value?: ComposerSnapshot;
+    onValueChange?: (snapshot: ComposerSnapshot) => void;
+    /** Explicit Composer.createStore() handle; defaults to a per-mount instance. */
+    store?: ComposerStore;
+};
+export declare const ComposerRoot: ({ onSubmit, isSubmitting, commands, questions, defaultValue, value, onValueChange, store: storeProp, className, render, style, ...elementProps }: ComposerRootProps) => import("react").JSX.Element;

package/dist/composer/root.js

@@ -0,0 +1,124 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+// Composer.Root — the form element that owns the submit flow, prop→store
+// bridges, drag-drop scope, and the per-instance store resolution: an explicit
+// Composer.createStore() handle via the store prop, or an instance created for
+// this mount. Every bare <Composer> is fully isolated.
+import { useEffect, useId, useMemo, useRef, useSyncExternalStore } from "react";
+import { useRefWithInit } from "../internal/render/useRefWithInit.js";
+import { useRenderElement } from "../internal/render/useRenderElement.js";
+import { ComposerInternalsContext, useAsRef, useCommandRegistry, useComposerSnapshot, useDragDropFiles, } from "./internals.js";
+import { ComposerStoreContext, createComposerStore } from "./store.js";
+const EMPTY_COMMANDS = {};
+export const ComposerRoot = ({ onSubmit, isSubmitting = false, commands = EMPTY_COMMANDS, questions, defaultValue, value, onValueChange, store: storeProp, className, render, style, ...elementProps }) => {
+    // SSR-stable per-mount id for the command listbox (aria-controls target +
+    // option-id root). Assigned onto the store in init below — the factory
+    // can't mint it because explicit handles are created outside React.
+    const listboxId = useId();
+    // Resolved once at mount (lazy-init ref, not reactive state): an explicit
+    // handle, or an instance this mount creates and owns. Swapping the store
+    // prop after mount is not supported.
+    const { store, ownsStore } = useRefWithInit(() => {
+        const resolved = storeProp ?? createComposerStore();
+        resolved.listboxId = listboxId;
+        return { store: resolved, ownsStore: !storeProp };
+    }).current;
+    const formRef = useRef(null);
+    const onSubmitRef = useAsRef(onSubmit);
+    // Register this mount on the store: answers submit through this mount's
+    // onSubmit. React also runs the cleanup without a real unmount (StrictMode,
+    // a hidden <Activity>), where the state lives on, so it only resets an owned
+    // store once React has removed the form — that happens on a real unmount only.
+    useEffect(() => {
+        const form = formRef.current;
+        store.submitAnswersRef.current = (answers) => onSubmitRef.current?.({ kind: "answers", answers });
+        return () => {
+            store.submitAnswersRef.current = null;
+            if (ownsStore && form && !form.isConnected)
+                store.reset();
+        };
+    }, [store, ownsStore]);
+    // Prop → store bridges. Actions and refs on the snapshot are identity-stable,
+    // so reading them here without subscribing is safe.
+    const { add: addAttachments, globalDropRef } = store.getSnapshot().attachments;
+    // Subscribed on the resolved store (not through useComposer — a `store` prop
+    // may differ from the nearest context) to surface drag state as data-dragging.
+    const getIsDragging = () => store.getSnapshot().attachments.isDragging;
+    const isDragging = useSyncExternalStore(store.subscribe, getIsDragging, getIsDragging);
+    useEffect(() => {
+        store.setIsSubmitting(isSubmitting);
+    }, [store, isSubmitting]);
+    // Sync the questions prop into the store and arm ask-user mode (editor blur
+    // + document-level keyboard handling) while questions are active.
+    useEffect(() => {
+        store.setQuestions(questions ?? null);
+        if (!questions?.length)
+            return;
+        return store.activateAskUser();
+    }, [store, questions]);
+    const { getRegisteredPrefixes } = useCommandRegistry(commands);
+    useDragDropFiles({
+        rootRef: formRef,
+        globalDropRef,
+        onFiles: addAttachments,
+        setDragging: store.setDragging,
+    });
+    const { reportEditorUpdate } = useComposerSnapshot({
+        editorRef: store.editorRef,
+        defaultValue,
+        value,
+        onValueChange,
+    });
+    const handleFormSubmit = async (event) => {
+        event.preventDefault();
+        const { askUser, attachments } = store.getSnapshot();
+        if (askUser.questions?.length) {
+            askUser.continueStep(store.controller.getText());
+            return;
+        }
+        if (isSubmitting)
+            return;
+        const serialized = store.controller.serialize();
+        const trimmedText = serialized.text.trim();
+        if (!trimmedText && !attachments.items.length)
+            return;
+        // Emit the generic attachment descriptors; the consumer's onSubmit adapts
+        // them to its wire format (e.g. FilePart via prepareAttachmentsForSend).
+        // Text may be empty on an attachments-only submit — any placeholder copy
+        // is the consumer's.
+        const files = attachments.items;
+        store.resetAttachments();
+        store.controller.clear();
+        await onSubmitRef.current?.({
+            kind: "message",
+            text: trimmedText,
+            files,
+        });
+    };
+    // Escape stops generating. React bubbles keys from portaled parts (a positioned
+    // Panel) here too; a consumer's onKeyDown can skip it with preventPrimitiveHandler().
+    const handleKeyDown = (event) => {
+        const stopGenerating = store.stopGeneratingRef.current;
+        if (event.key !== "Escape" || event.defaultPrevented || !stopGenerating)
+            return;
+        // While a question is open, Escape dismisses its step instead.
+        if (store.getSnapshot().askUser.questions?.length)
+            return;
+        event.preventDefault();
+        stopGenerating();
+    };
+    const internalsValue = useMemo(() => ({
+        commands,
+        getRegisteredPrefixes,
+        reportEditorUpdate,
+    }), [commands, getRegisteredPrefixes, reportEditorUpdate]);
+    const formElement = useRenderElement("form", { className, render, style }, {
+        state: { submitting: isSubmitting, dragging: isDragging },
+        ref: formRef,
+        props: [
+            { "data-composer-root": "", onSubmit: handleFormSubmit, onKeyDown: handleKeyDown },
+            elementProps,
+        ],
+    });
+    return (_jsx(ComposerStoreContext, { value: store, children: _jsx(ComposerInternalsContext, { value: internalsValue, children: formElement }) }));
+};

package/dist/composer/segments.d.ts

@@ -0,0 +1,108 @@
+import { type ChipData, type ChipSegment } from "../chip-markdown.js";
+export type Segment = {
+    type: "text";
+    text: string;
+} | {
+    type: "chip";
+    id: string;
+    chip: ChipData;
+};
+export type SegmentDoc = Segment[];
+export type TextChange = {
+    rangeStart: number;
+    rangeEnd: number;
+    insertedLength: number;
+};
+export declare const nextChipId: () => string;
+export declare const documentLength: (doc: SegmentDoc) => number;
+/** Chips contribute nothing — the getText()/onValueChange contract. */
+export declare const getPlainText: (doc: SegmentDoc) => string;
+/** Chips as the sentinel char — positions stay 1:1 for diffing. */
+export declare const toFlatText: (doc: SegmentDoc) => string;
+/**
+ * Chips as a single space — positions stay 1:1 for prefix detection, and the
+ * whitespace guarantees an active token can never span a chip.
+ */
+export declare const toScanText: (doc: SegmentDoc) => string;
+export declare const chipRangesOf: (doc: SegmentDoc) => Array<{
+    id: string;
+    start: number;
+    end: number;
+}>;
+/** The "\n"-delimited line around a position in scan text. */
+export declare const lineBoundsAt: (scanText: string, position: number) => {
+    lineStart: number;
+    lineEnd: number;
+};
+export declare const segmentsFromText: (text: string) => SegmentDoc;
+export declare const segmentsFromChipSegments: (segments: readonly ChipSegment[], makeId?: () => string) => SegmentDoc;
+/**
+ * The {text} submit payload — text as-is, chips as chip-markdown tokens.
+ * Byte-identical to the legacy serializeDocument for equivalent content.
+ */
+export declare const serializeSegments: (doc: SegmentDoc) => {
+    text: string;
+};
+/**
+ * Replace the logical range [from, to) with the inserted segments. A chip is
+ * atomic: it is removed iff its position falls inside the range (range edges
+ * never split it).
+ */
+export declare const spliceSegments: (doc: SegmentDoc, from: number, to: number, insert: SegmentDoc) => SegmentDoc;
+/** Extract [from, to) as a sub-document. Chips are included iff fully inside. */
+export declare const sliceSegments: (doc: SegmentDoc, from: number, to: number) => SegmentDoc;
+/**
+ * Fit segments into `room` logical units for maxLength: text is sliced at the
+ * boundary; a chip that doesn't fit whole is dropped entirely.
+ */
+export declare const truncateToFit: (insert: SegmentDoc, room: number) => SegmentDoc;
+export declare const mapPositionResult: (position: number, change: TextChange, bias: -1 | 1) => {
+    position: number;
+    deleted: boolean;
+};
+export declare const mapPosition: (position: number, change: TextChange, bias: -1 | 1) => number;
+export declare const diffFlatText: (oldFlat: string, newFlat: string, caretHint?: number) => TextChange | null;
+export type BeforeInputPlan = {
+    kind: "native";
+} | {
+    kind: "block";
+} | {
+    kind: "splice";
+    from: number;
+    to: number;
+    insert: SegmentDoc;
+    caret: number;
+};
+export declare const planBeforeInput: (args: {
+    inputType: string;
+    data: string | null;
+    /** The event's first target range in logical positions; null when unavailable. */
+    targetRange: {
+        start: number;
+        end: number;
+    } | null;
+    doc: SegmentDoc;
+    caret: {
+        start: number;
+        end: number;
+    };
+    maxLength?: number;
+}) => BeforeInputPlan;
+export type SnapshotInlineNode = {
+    type: "text";
+    text: string;
+} | {
+    type: "mentionChip";
+    attrs: {
+        prefix: string;
+        value: string;
+        label: string;
+        icon?: string;
+    };
+};
+export type SnapshotParagraphNode = {
+    type: "paragraph";
+    content?: SnapshotInlineNode[];
+};
+export declare const segmentsToParagraphJSON: (doc: SegmentDoc) => SnapshotParagraphNode[];
+export declare const segmentsFromParagraphJSON: (paragraphs: readonly SnapshotParagraphNode[], makeId?: () => string) => SegmentDoc;