@blocksdiy/react-common 1.70.2 → 1.71.0

package/dist/comments/comment-mode.js

@@ -0,0 +1,159 @@
+import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+export const DEFAULT_COMMENT_OPTIONS = { showResolved: false };
+const sameOptions = (a, b) => a.showResolved === b.showResolved && a.mentionableAgents?.join("\n") === b.mentionableAgents?.join("\n");
+/** How long turning comment mode on waits for a comments surface to mount. */
+export const COMMENT_MODE_CLAIM_TIMEOUT_MS = 5000;
+const defaultTimers = {
+    setTimeout: (callback, ms) => setTimeout(callback, ms),
+    clearTimeout: (id) => clearTimeout(id),
+};
+export const createCommentModeStore = (timers = defaultTimers) => {
+    let on = false;
+    let surfaces = 0;
+    let pending = null;
+    const listeners = new Set();
+    const exitListeners = new Set();
+    let options = DEFAULT_COMMENT_OPTIONS;
+    let openThreadHandler = null;
+    const requestOnListeners = new Set();
+    const emit = () => listeners.forEach((listener) => listener());
+    const canOpenThread = () => requestOnListeners.size > 0 && openThreadHandler !== null;
+    const settlePending = (claimed) => {
+        if (pending) {
+            timers.clearTimeout(pending.timer);
+            pending.resolve(claimed);
+            pending = null;
+        }
+    };
+    const turnOn = () => {
+        if (!on) {
+            on = true;
+            emit();
+        }
+    };
+    const turnOff = () => {
+        if (on) {
+            on = false;
+            emit();
+        }
+    };
+    return {
+        set(isOn) {
+            // A newer request supersedes one still waiting for a surface.
+            settlePending(false);
+            if (!isOn) {
+                turnOff();
+                return Promise.resolve(true);
+            }
+            if (surfaces > 0) {
+                turnOn();
+                return Promise.resolve(true);
+            }
+            return new Promise((resolve) => {
+                pending = {
+                    resolve,
+                    timer: timers.setTimeout(() => {
+                        pending = null;
+                        resolve(false);
+                    }, COMMENT_MODE_CLAIM_TIMEOUT_MS),
+                };
+            });
+        },
+        isOn: () => on,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        registerSurface() {
+            surfaces += 1;
+            if (pending) {
+                turnOn();
+                settlePending(true);
+            }
+            let registered = true;
+            return () => {
+                if (!registered) {
+                    return;
+                }
+                registered = false;
+                surfaces -= 1;
+                if (surfaces === 0) {
+                    turnOff();
+                }
+            };
+        },
+        exit() {
+            if (on) {
+                turnOff();
+                exitListeners.forEach((listener) => listener());
+            }
+        },
+        onExit(listener) {
+            exitListeners.add(listener);
+            return () => exitListeners.delete(listener);
+        },
+        setOptions(next) {
+            if (!sameOptions(next, options)) {
+                options = next;
+                emit();
+            }
+        },
+        options: () => options,
+        handleOpenThread(handler) {
+            openThreadHandler = handler;
+            return () => {
+                if (openThreadHandler === handler) {
+                    openThreadHandler = null;
+                }
+            };
+        },
+        onRequestOn(listener) {
+            requestOnListeners.add(listener);
+            return () => requestOnListeners.delete(listener);
+        },
+        canOpenThread,
+        openThread(request) {
+            if (!canOpenThread()) {
+                return false;
+            }
+            requestOnListeners.forEach((listener) => listener());
+            openThreadHandler?.(request);
+            return true;
+        },
+    };
+};
+/** The one store the host and the app share. */
+export const commentMode = createCommentModeStore();
+/** The host: turn comment mode on or off (resolves false when the app has no comments surface). */
+export const setCommentMode = (isOn) => commentMode.set(isOn);
+/** The host: hears when the app turned comment mode off itself. Returns the unsubscribe. */
+export const onCommentModeExit = (listener) => commentMode.onExit(listener);
+/** The host: what the app's comments show (the Comment button's options). */
+export const setCommentOptions = (next) => commentMode.setOptions(next);
+/** The host: hears the app ask for comment mode. Returns the unsubscribe. */
+export const onCommentModeRequest = (listener) => commentMode.onRequestOn(listener);
+/**
+ * The app (the agent chat's comment message): opens a thread — its page, comment mode on, the
+ * thread open. False when it can't here: outside the platform, or without the comments component.
+ */
+export const openCommentThread = (request, store = commentMode) => store.openThread(request);
+/** Whether `openCommentThread` can open a thread here: the link back to it shows only then. */
+export const canOpenCommentThread = (store = commentMode) => store.canOpenThread();
+/**
+ * The app's comments surface: registers itself while mounted and reads the mode. `exit` turns it off
+ * from inside the app and tells the host. It opens the threads the app asks for (a comment's link in
+ * the agent chat) and reads the host's options.
+ */
+export const useCommentsSurface = ({ onOpenThread, store = commentMode } = {}) => {
+    useEffect(() => store.registerSurface(), [store]);
+    const latestOpenThread = useRef(onOpenThread);
+    useEffect(() => {
+        latestOpenThread.current = onOpenThread;
+    });
+    const isHandlingOpenThread = !!onOpenThread;
+    useEffect(() => (isHandlingOpenThread ? store.handleOpenThread((request) => latestOpenThread.current?.(request)) : undefined), [isHandlingOpenThread, store]);
+    const isCommentMode = useSyncExternalStore(store.subscribe, store.isOn, () => false);
+    const options = useSyncExternalStore(store.subscribe, store.options, () => DEFAULT_COMMENT_OPTIONS);
+    const exit = useCallback(() => store.exit(), [store]);
+    return { isCommentMode, options, exit };
+};

package/dist/comments/composer.d.ts

@@ -0,0 +1,133 @@
+import { type RefObject } from "react";
+import { type Mention } from "./mentions.js";
+import type { MentionableUserDto } from "./types.js";
+/**
+ * The comment composer's logic, headless: the text, the mentions in it, the `@` menu, the "Send to"
+ * agent line, and the body to store. The registry's composer only draws it.
+ *
+ * Each mention is a range of the text (`@Name`, exactly) tied to who it names, so two people with
+ * the same name stay apart and a typed `@Dana` is not a mention until picked. Every edit moves the
+ * ranges: an edit before one shifts it, an edit inside one turns it back into plain text, and
+ * Backspace right after one removes it whole.
+ */
+export interface ComposerMention {
+    start: number;
+    /** Exclusive: `text.slice(start, end)` is `@` + the mention's name. */
+    end: number;
+    mention: Mention;
+}
+export interface ComposerState {
+    text: string;
+    /** In text order, never overlapping. */
+    mentions: ComposerMention[];
+}
+export type ComposerSegment = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "mention";
+    text: string;
+    mention: Mention;
+};
+export declare const EMPTY_COMPOSER: ComposerState;
+/**
+ * The text after an edit, with its mentions moved. `caret` is where the caret is after the edit:
+ * what follows it is taken as unchanged, which places a typed or pasted run, or a deletion, exactly
+ * (a plain diff can't tell which of two equal letters was typed).
+ */
+export declare const applyEdit: (state: ComposerState, text: string, caret?: number) => ComposerState;
+/** Picks a mention for the `@query` typed at `[queryStart, caret)`: `@Name ` in its place. */
+export declare const insertMention: (state: ComposerState, queryStart: number, caret: number, mention: Mention) => {
+    state: ComposerState;
+    caret: number;
+};
+/** Backspace with the caret right after a mention: the whole mention goes. Null when it isn't one. */
+export declare const deleteMentionBefore: (state: ComposerState, caret: number) => {
+    state: ComposerState;
+    caret: number;
+} | null;
+/** Whether the text mentions this agent. */
+export declare const mentionsAgent: (state: ComposerState, agentId: string) => boolean;
+/** Mentions an agent at the start of the text (the "Send to" line), unless the text already does. */
+export declare const addAgentMention: (state: ComposerState, agent: {
+    agentId: string;
+    name: string;
+}) => ComposerState;
+/** Removes every mention of an agent, with the space after each. */
+export declare const removeAgentMention: (state: ComposerState, agentId: string) => ComposerState;
+/** The text in runs — plain text, and mentions — for the highlight drawn behind the text. */
+export declare const composerSegments: (state: ComposerState) => ComposerSegment[];
+/** The body to store: each mention as its token (`@[42]`, `@[agent:Name]`), the rest as typed. */
+export declare const composerBody: (state: ComposerState) => string;
+/** An agent the composer can mention: one of the app's floating-chat agents. */
+export interface ComposerAgent {
+    id: string;
+    name: string;
+    photoUrl?: string | null;
+}
+export type ComposerOption = Mention & {
+    photoUrl?: string | null;
+};
+/**
+ * How well a name matches what was typed after `@`: 0 when the name starts with it, 1 when one of
+ * its words does, 2 for any other match (inside a word, an email). The menu lists better matches
+ * first, so "@ol" puts Olive before Marina Sokolov.
+ */
+export declare const mentionRank: (name: string, query: string) => number;
+/**
+ * The `@` menu for what was typed: the app's agents first, then people (never yourself), each group
+ * ranked by `mentionRank` and capped (3 agents, 5 people). `separatorBefore` is the index of the
+ * first person when both groups have matches, where the menu draws its divider.
+ */
+export declare const mentionOptions: ({ people, agents, currentUserId, query, }: {
+    people: readonly MentionableUserDto[];
+    agents: readonly ComposerAgent[];
+    currentUserId: number | null;
+    query: string;
+}) => {
+    options: ComposerOption[];
+    separatorBefore: number | null;
+};
+export interface UseMentionComposerOptions {
+    people: readonly MentionableUserDto[];
+    agents: readonly ComposerAgent[];
+    /** Left out of the `@` menu: nobody mentions themselves. */
+    currentUserId: number | null;
+    textareaRef: RefObject<HTMLTextAreaElement | null>;
+}
+export interface MentionComposer {
+    text: string;
+    segments: ComposerSegment[];
+    /** What to store; empty when there's nothing to send. */
+    body: string;
+    /** The `@` menu's options (agents, then people), while an `@query` is being typed. */
+    options: ComposerOption[];
+    /** The index of the first person when agents and people both match: draw a divider before it. */
+    separatorBefore: number | null;
+    highlighted: number;
+    setHighlighted: (index: number) => void;
+    /** Arrow keys in the menu. */
+    moveHighlight: (step: 1 | -1) => void;
+    pick: (option: ComposerOption) => void;
+    /** Esc in the menu. */
+    closeMenu: () => void;
+    isMenuOpen: boolean;
+    /** The textarea's change: its new value and caret. */
+    onChange: (text: string, caret: number) => void;
+    /**
+     * Backspace, before the browser acts on it: right after a mention, selects the whole mention so
+     * the key deletes it (undoably). The caller lets the key go on.
+     */
+    onBackspace: (selectionStart: number, selectionEnd: number) => void;
+    /** The "Send to" line: the agent it shows — the first one mentioned, else the first agent. */
+    sendToAgent: ComposerAgent | null;
+    isSendingToAgent: boolean;
+    /** Checks or unchecks "Send to": mentions the agent, or removes its mentions. */
+    setSendingToAgent: (isOn: boolean) => void;
+    /** Swaps the "Send to" agent; a mention of the old one becomes one of the new one. */
+    chooseSendToAgent: (agentId: string) => void;
+    reset: () => void;
+}
+/** The composer's state and actions; see the module comment. */
+export declare const useMentionComposer: ({ people, agents, currentUserId, textareaRef, }: UseMentionComposerOptions) => MentionComposer;
+//# sourceMappingURL=composer.d.ts.map

package/dist/comments/composer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composer.d.ts","sourceRoot":"","sources":["../../src/comments/composer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAqD,MAAM,OAAO,CAAC;AAE1F,OAAO,EAAuB,KAAK,OAAO,EAAgC,MAAM,YAAY,CAAC;AAC7F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD;;;;;;;;GAQG;AAEH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED,MAAM,MAAM,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAEnH,eAAO,MAAM,cAAc,EAAE,aAA0C,CAAC;AAUxE;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,aAAa,EAAE,MAAM,MAAM,EAAE,QAAO,MAAoB,KAAG,aA+B3F,CAAC;AAkBF,8FAA8F;AAC9F,eAAO,MAAM,aAAa,GACxB,OAAO,aAAa,EACpB,YAAY,MAAM,EAClB,OAAO,MAAM,EACb,SAAS,OAAO,KACf;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAavC,CAAC;AAEF,sGAAsG;AACtG,eAAO,MAAM,mBAAmB,GAC9B,OAAO,aAAa,EACpB,OAAO,MAAM,KACZ;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAM5C,CAAC;AAIF,4CAA4C;AAC5C,eAAO,MAAM,aAAa,GAAI,OAAO,aAAa,EAAE,SAAS,MAAM,KAAG,OACH,CAAC;AAEpE,qGAAqG;AACrG,eAAO,MAAM,eAAe,GAAI,OAAO,aAAa,EAAE,OAAO;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,KAAG,aAUhG,CAAC;AAEF,oEAAoE;AACpE,eAAO,MAAM,kBAAkB,GAAI,OAAO,aAAa,EAAE,SAAS,MAAM,KAAG,aAO9D,CAAC;AAEd,6FAA6F;AAC7F,eAAO,MAAM,gBAAgB,GAAI,OAAO,aAAa,KAAG,eAAe,EActE,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,YAAY,GAAI,OAAO,aAAa,KAAG,MAIzC,CAAC;AAEZ,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,EAAE,OAAO,MAAM,KAAG,MAOzD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,2CAK5B;IACD,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACtC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IACjC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;CACf,KAAG;IAAE,OAAO,EAAE,cAAc,EAAE,CAAC;IAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;CA0B9D,CAAC;AAEF,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACtC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IACjC,4DAA4D;IAC5D,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,EAAE,SAAS,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,sFAAsF;IACtF,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,iGAAiG;IACjG,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,8BAA8B;IAC9B,aAAa,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC;IACtC,IAAI,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;IACvC,uBAAuB;IACvB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,sDAAsD;IACtD,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD;;;OAGG;IACH,WAAW,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;IACpE,8FAA8F;IAC9F,WAAW,EAAE,aAAa,GAAG,IAAI,CAAC;IAClC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,iFAAiF;IACjF,iBAAiB,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAC3C,sFAAsF;IACtF,iBAAiB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,gEAAgE;AAChE,eAAO,MAAM,kBAAkB,GAAI,iDAKhC,yBAAyB,KAAG,eA+I9B,CAAC"}

package/dist/comments/composer.js

@@ -0,0 +1,273 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { matchesMentionQuery, mentionQueryAt, mentionToken } from "./mentions.js";
+export const EMPTY_COMPOSER = { text: "", mentions: [] };
+const label = (mention) => `@${mention.name}`;
+/** Keeps only the ranges that still read exactly `@Name`, in order. */
+const valid = (text, mentions) => mentions
+    .filter((range) => range.start >= 0 && text.slice(range.start, range.end) === label(range.mention))
+    .sort((a, b) => a.start - b.start);
+/**
+ * The text after an edit, with its mentions moved. `caret` is where the caret is after the edit:
+ * what follows it is taken as unchanged, which places a typed or pasted run, or a deletion, exactly
+ * (a plain diff can't tell which of two equal letters was typed).
+ */
+export const applyEdit = (state, text, caret = text.length) => {
+    const before = state.text;
+    const delta = text.length - before.length;
+    // What follows the caret is unchanged: the edited span ends there in the new text. When it isn't
+    // (an undo can leave the caret elsewhere), the longest common ending stands in.
+    const afterCaret = Math.max(0, Math.min(text.length - caret, before.length));
+    let suffix = afterCaret;
+    if (!before.endsWith(text.slice(text.length - afterCaret))) {
+        suffix = 0;
+        const limit = Math.min(before.length, text.length);
+        while (suffix < limit && before[before.length - 1 - suffix] === text[text.length - 1 - suffix]) {
+            suffix += 1;
+        }
+    }
+    let prefix = 0;
+    const prefixLimit = Math.min(before.length - suffix, text.length - suffix);
+    while (prefix < prefixLimit && before[prefix] === text[prefix]) {
+        prefix += 1;
+    }
+    const oldEnd = before.length - suffix;
+    const mentions = state.mentions.flatMap((range) => {
+        if (range.end <= prefix) {
+            return [range];
+        }
+        if (range.start >= oldEnd && oldEnd >= prefix) {
+            return [{ ...range, start: range.start + delta, end: range.end + delta }];
+        }
+        // The edit touched it: it's plain text now.
+        return [];
+    });
+    return { text, mentions: valid(text, mentions) };
+};
+/** Replaces `[from, to)` with `insert`, moving the mentions after it. Mentions inside go. */
+const replaceRange = (state, from, to, insert) => {
+    const delta = insert.length - (to - from);
+    const text = state.text.slice(0, from) + insert + state.text.slice(to);
+    const mentions = state.mentions.flatMap((range) => {
+        if (range.end <= from) {
+            return [range];
+        }
+        if (range.start >= to) {
+            return [{ ...range, start: range.start + delta, end: range.end + delta }];
+        }
+        return [];
+    });
+    return { text, mentions: valid(text, mentions) };
+};
+/** Picks a mention for the `@query` typed at `[queryStart, caret)`: `@Name ` in its place. */
+export const insertMention = (state, queryStart, caret, mention) => {
+    const inserted = `${label(mention)} `;
+    const next = replaceRange(state, queryStart, caret, inserted);
+    return {
+        state: {
+            text: next.text,
+            mentions: valid(next.text, [
+                ...next.mentions,
+                { start: queryStart, end: queryStart + label(mention).length, mention },
+            ]),
+        },
+        caret: queryStart + inserted.length,
+    };
+};
+/** Backspace with the caret right after a mention: the whole mention goes. Null when it isn't one. */
+export const deleteMentionBefore = (state, caret) => {
+    const range = state.mentions.find((candidate) => candidate.end === caret);
+    if (!range) {
+        return null;
+    }
+    return { state: replaceRange(state, range.start, range.end, ""), caret: range.start };
+};
+const sameAgent = (mention, agentId) => mention.kind === "agent" && mention.agentId === agentId;
+/** Whether the text mentions this agent. */
+export const mentionsAgent = (state, agentId) => state.mentions.some((range) => sameAgent(range.mention, agentId));
+/** Mentions an agent at the start of the text (the "Send to" line), unless the text already does. */
+export const addAgentMention = (state, agent) => {
+    if (mentionsAgent(state, agent.agentId)) {
+        return state;
+    }
+    const mention = { kind: "agent", agentId: agent.agentId, name: agent.name };
+    const next = replaceRange(state, 0, 0, `${label(mention)} `);
+    return {
+        text: next.text,
+        mentions: valid(next.text, [...next.mentions, { start: 0, end: label(mention).length, mention }]),
+    };
+};
+/** Removes every mention of an agent, with the space after each. */
+export const removeAgentMention = (state, agentId) => [...state.mentions]
+    .reverse()
+    .filter((range) => sameAgent(range.mention, agentId))
+    .reduce((current, range) => {
+    const end = current.text[range.end] === " " ? range.end + 1 : range.end;
+    return replaceRange(current, range.start, end, "");
+}, state);
+/** The text in runs — plain text, and mentions — for the highlight drawn behind the text. */
+export const composerSegments = (state) => {
+    const segments = [];
+    let last = 0;
+    for (const range of state.mentions) {
+        if (range.start > last) {
+            segments.push({ kind: "text", text: state.text.slice(last, range.start) });
+        }
+        segments.push({ kind: "mention", text: state.text.slice(range.start, range.end), mention: range.mention });
+        last = range.end;
+    }
+    if (last < state.text.length) {
+        segments.push({ kind: "text", text: state.text.slice(last) });
+    }
+    return segments;
+};
+/** The body to store: each mention as its token (`@[42]`, `@[agent:Name]`), the rest as typed. */
+export const composerBody = (state) => composerSegments(state)
+    .map((segment) => (segment.kind === "mention" ? mentionToken(segment.mention) : segment.text))
+    .join("")
+    .trim();
+/**
+ * How well a name matches what was typed after `@`: 0 when the name starts with it, 1 when one of
+ * its words does, 2 for any other match (inside a word, an email). The menu lists better matches
+ * first, so "@ol" puts Olive before Marina Sokolov.
+ */
+export const mentionRank = (name, query) => {
+    const needle = query.trim().toLowerCase();
+    const haystack = name.toLowerCase();
+    if (!needle || haystack.startsWith(needle)) {
+        return 0;
+    }
+    return haystack.split(/\s+/).some((word) => word.startsWith(needle)) ? 1 : 2;
+};
+/**
+ * The `@` menu for what was typed: the app's agents first, then people (never yourself), each group
+ * ranked by `mentionRank` and capped (3 agents, 5 people). `separatorBefore` is the index of the
+ * first person when both groups have matches, where the menu draws its divider.
+ */
+export const mentionOptions = ({ people, agents, currentUserId, query, }) => {
+    const ranked = (items, cap) => items
+        .map((item, index) => ({ item, index, rank: mentionRank(item.name, query) }))
+        .sort((a, b) => a.rank - b.rank || a.index - b.index)
+        .slice(0, cap)
+        .map(({ item }) => item);
+    const matchingAgents = ranked(agents.filter((agent) => matchesMentionQuery({ name: agent.name }, query)), 3).map((agent) => ({ kind: "agent", agentId: agent.id, name: agent.name, photoUrl: agent.photoUrl }));
+    const matchingPeople = ranked(people.filter((person) => person.userId !== currentUserId && matchesMentionQuery(person, query)), 5).map((person) => ({
+        kind: "user",
+        userId: person.userId,
+        name: person.name,
+        photoUrl: person.profileImageUrl,
+    }));
+    return {
+        options: [...matchingAgents, ...matchingPeople],
+        separatorBefore: matchingAgents.length > 0 && matchingPeople.length > 0 ? matchingAgents.length : null,
+    };
+};
+/** The composer's state and actions; see the module comment. */
+export const useMentionComposer = ({ people, agents, currentUserId, textareaRef, }) => {
+    const [state, setState] = useState(EMPTY_COMPOSER);
+    const [query, setQuery] = useState(null);
+    const [highlighted, setHighlighted] = useState(0);
+    const [chosenAgentId, setChosenAgentId] = useState(null);
+    const latest = useRef(state);
+    useEffect(() => {
+        latest.current = state;
+    });
+    // After a change the composer made itself (a pick, a whole-mention delete), the caret goes where
+    // that change ends, once the textarea shows the new text.
+    const placeCaret = useCallback((caret) => requestAnimationFrame(() => {
+        const textarea = textareaRef.current;
+        if (textarea) {
+            textarea.focus();
+            textarea.setSelectionRange(caret, caret);
+        }
+    }), [textareaRef]);
+    const { options, separatorBefore } = useMemo(() => query
+        ? mentionOptions({ people, agents, currentUserId, query: query.query })
+        : { options: [], separatorBefore: null }, [agents, currentUserId, people, query]);
+    const onChange = useCallback((text, caret) => {
+        setState((current) => applyEdit(current, text, caret));
+        setQuery(mentionQueryAt(text, caret));
+        setHighlighted(0);
+    }, []);
+    const pick = useCallback((option) => {
+        if (!query) {
+            return;
+        }
+        const caret = textareaRef.current?.selectionStart ?? latest.current.text.length;
+        const mention = option.kind === "user"
+            ? { kind: "user", userId: option.userId, name: option.name }
+            : { kind: "agent", agentId: option.agentId, name: option.name };
+        const next = insertMention(latest.current, query.start, Math.max(caret, query.start), mention);
+        setState(next.state);
+        setQuery(null);
+        placeCaret(next.caret);
+    }, [placeCaret, query, textareaRef]);
+    const onBackspace = useCallback((selectionStart, selectionEnd) => {
+        const textarea = textareaRef.current;
+        const current = latest.current;
+        const range = current.mentions.find((candidate) => candidate.end === selectionStart);
+        if (!textarea || selectionStart !== selectionEnd || !range) {
+            return;
+        }
+        // Selects the whole mention (with the space after it, when that would leave two) and lets
+        // the key delete it: the browser's own edit, so Undo brings it back.
+        const before = current.text[range.start - 1];
+        const end = current.text[range.end] === " " && (range.start === 0 || before === " " || before === "\n")
+            ? range.end + 1
+            : range.end;
+        textarea.setSelectionRange(range.start, end);
+    }, [textareaRef]);
+    const firstMentionedAgent = state.mentions.find((range) => range.mention.kind === "agent")?.mention;
+    const sendToAgent = (firstMentionedAgent?.kind === "agent"
+        ? agents.find((agent) => agent.id === firstMentionedAgent.agentId)
+        : undefined) ??
+        agents.find((agent) => agent.id === chosenAgentId) ??
+        agents[0] ??
+        null;
+    const isSendingToAgent = !!sendToAgent && mentionsAgent(state, sendToAgent.id);
+    const setSendingToAgent = useCallback((isOn) => {
+        if (!sendToAgent) {
+            return;
+        }
+        const current = latest.current;
+        const next = isOn
+            ? addAgentMention(current, { agentId: sendToAgent.id, name: sendToAgent.name })
+            : removeAgentMention(current, sendToAgent.id);
+        setState(next);
+        // Back to typing: right after the mention and its space when it was added, else the end.
+        placeCaret(isOn ? sendToAgent.name.length + 2 : next.text.length);
+    }, [placeCaret, sendToAgent]);
+    const chooseSendToAgent = useCallback((agentId) => {
+        const next = agents.find((agent) => agent.id === agentId);
+        if (!next) {
+            return;
+        }
+        setChosenAgentId(agentId);
+        if (sendToAgent && isSendingToAgent && sendToAgent.id !== agentId) {
+            setState((current) => addAgentMention(removeAgentMention(current, sendToAgent.id), { agentId: next.id, name: next.name }));
+        }
+    }, [agents, isSendingToAgent, sendToAgent]);
+    const reset = useCallback(() => {
+        setState(EMPTY_COMPOSER);
+        setQuery(null);
+    }, []);
+    return {
+        text: state.text,
+        segments: composerSegments(state),
+        body: composerBody(state),
+        options,
+        highlighted,
+        setHighlighted,
+        moveHighlight: (step) => setHighlighted((current) => (options.length ? (current + step + options.length) % options.length : 0)),
+        pick,
+        closeMenu: () => setQuery(null),
+        separatorBefore,
+        isMenuOpen: options.length > 0,
+        onChange,
+        onBackspace,
+        sendToAgent,
+        isSendingToAgent,
+        setSendingToAgent,
+        chooseSendToAgent,
+        reset,
+    };
+};

package/dist/comments/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./types.js";
+export { ITEM_ATTRIBUTE, FIELD_ATTRIBUTE, PICK_IGNORE_ATTRIBUTE, anchorQuote, anchorComponentName, type AnchorState, } from "./anchor.js";
+export { initials, type Mention, type MentionNames } from "./mentions.js";
+export { toRect, type Rect } from "./layout.js";
+export { COMMENTS_LAYER_ATTRIBUTE, pinPoint, groupPins, useCommentPins, type PinPoint, type PinGroup, type ThreadLayout, } from "./pins.js";
+export { usePagePick, type PagePick, type PagePickHover, type UsePagePickOptions } from "./page-pick.js";
+export { createCommentsApi, type CommentsApi, type CreateCommentsApiOptions } from "./api.js";
+export { setCommentMode, onCommentModeExit, setCommentOptions, onCommentModeRequest, openCommentThread, canOpenCommentThread, useCommentsSurface, type CommentThreadOpenRequest, type CommentOptions, type UseCommentsSurfaceOptions, } from "./comment-mode.js";
+export { commentPingsFor, useCommentThreads, type CommentThreadsStore, type CommentThreadsSnapshot, type CommentThreadLoadState, type SubscribeToCommentPings, } from "./threads-store.js";
+export { useCommentAgents, useRegisterCommentAgents, type CommentAgent, type CommentAgentsSnapshot, type OpenCommentAgentThread, } from "./comment-agents.js";
+export { pagePickComposerMeta, parsePagePickPart, pagePickOf } from "./pick-message.js";
+export { useMentionComposer, type ComposerAgent, type ComposerOption, type ComposerSegment, type MentionComposer, type UseMentionComposerOptions, } from "./composer.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/comments/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/comments/index.ts"],"names":[],"mappings":"AAMA,cAAc,SAAS,CAAC;AACxB,OAAO,EACL,cAAc,EACd,eAAe,EACf,qBAAqB,EACrB,WAAW,EACX,mBAAmB,EACnB,KAAK,WAAW,GACjB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,QAAQ,EAAE,KAAK,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,MAAM,EAAE,KAAK,IAAI,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EACL,wBAAwB,EACxB,QAAQ,EACR,SAAS,EACT,cAAc,EACd,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,YAAY,GAClB,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,WAAW,EAAE,KAAK,QAAQ,EAAE,KAAK,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtG,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,KAAK,wBAAwB,EAAE,MAAM,OAAO,CAAC;AAC3F,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,yBAAyB,GAC/B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,GAC7B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACrF,OAAO,EACL,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,yBAAyB,GAC/B,MAAM,YAAY,CAAC"}

package/dist/comments/index.js

@@ -0,0 +1,17 @@
+// In-app comments, headless: what the registry `comments` item and the agent chat's pointer are
+// built on. Registry files are copied into each app and never update on their own, while this
+// module is shared at runtime (a UMD external app-render provides), so its exports only grow:
+// never remove, rename or change the meaning of one. It exports what the registry items and
+// app-render use (and the types their signatures show); add an export when an item needs one.
+export * from "./types.js";
+export { ITEM_ATTRIBUTE, FIELD_ATTRIBUTE, PICK_IGNORE_ATTRIBUTE, anchorQuote, anchorComponentName, } from "./anchor.js";
+export { initials } from "./mentions.js";
+export { toRect } from "./layout.js";
+export { COMMENTS_LAYER_ATTRIBUTE, pinPoint, groupPins, useCommentPins, } from "./pins.js";
+export { usePagePick } from "./page-pick.js";
+export { createCommentsApi } from "./api.js";
+export { setCommentMode, onCommentModeExit, setCommentOptions, onCommentModeRequest, openCommentThread, canOpenCommentThread, useCommentsSurface, } from "./comment-mode.js";
+export { commentPingsFor, useCommentThreads, } from "./threads-store.js";
+export { useCommentAgents, useRegisterCommentAgents, } from "./comment-agents.js";
+export { pagePickComposerMeta, parsePagePickPart, pagePickOf } from "./pick-message.js";
+export { useMentionComposer, } from "./composer.js";

package/dist/comments/layout.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A counter that moves at most once per animation frame whenever the page may have moved: a
+ * scroll anywhere (capture phase, so scroll containers count), a window resize, a change to the
+ * app's DOM, or a reflow of the body (a panel opening beside the app moves everything with no DOM
+ * change and no window resize). Changes inside the comments' own UI don't count, so drawing pins
+ * never feeds itself.
+ *
+ * Positions are read from the DOM, which is not a React input: pass the tick to whatever reads them
+ * so it recomputes.
+ */
+export declare const usePageLayoutTick: (isActive: boolean) => number;
+export interface Rect {
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+}
+export declare const toRect: (rect: Pick<DOMRect, "top" | "left" | "right" | "bottom">) => Rect;
+/** The overlap of two rects, or null when they don't overlap. */
+export declare const intersectRects: (a: Rect, b: Rect) => Rect | null;
+/** The part of `rect` inside every clip (the viewport, each scrolling ancestor), or null. */
+export declare const visiblePart: (rect: Rect, clips: readonly Rect[]) => Rect | null;
+/** The boxes that clip `element`: the viewport and every ancestor that clips its overflow. */
+export declare const clipRectsOf: (element: Element) => Rect[];
+//# sourceMappingURL=layout.d.ts.map

package/dist/comments/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../src/comments/layout.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,OAAO,KAAG,MAkCrD,CAAC;AAEF,MAAM,WAAW,IAAI;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,MAAM,GAAI,MAAM,IAAI,CAAC,OAAO,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC,KAAG,IAKhF,CAAC;AAEH,iEAAiE;AACjE,eAAO,MAAM,cAAc,GAAI,GAAG,IAAI,EAAE,GAAG,IAAI,KAAG,IAAI,GAAG,IAMxD,CAAC;AAEF,6FAA6F;AAC7F,eAAO,MAAM,WAAW,GAAI,MAAM,IAAI,EAAE,OAAO,SAAS,IAAI,EAAE,KAAG,IAAI,GAAG,IASvE,CAAC;AAKF,8FAA8F;AAC9F,eAAO,MAAM,WAAW,GAAI,SAAS,OAAO,KAAG,IAAI,EAYlD,CAAC"}