@blocksdiy/react-common 1.70.2 → 1.71.1

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,19 @@
+export * from "./types.js";
+export { ITEM_ATTRIBUTE, FIELD_ATTRIBUTE, PICK_IGNORE_ATTRIBUTE, anchorQuote, anchorComponentName, anchorSubject, type AnchorElementKind, type AnchorState, type AnchorSubject, } from "./anchor.js";
+export { initials, type Mention, type MentionNames } from "./mentions.js";
+export { toRect, type Rect } from "./layout.js";
+export { COMMENTS_LAYER_ATTRIBUTE, pinPoint, pickPlacement, groupPins, useCommentPins, type PinPoint, type PinGroup, type ThreadLayout, } from "./pins.js";
+export { participantKey, pinParticipants, pinWidth, panelPosition, cornerPoint, panelSide, type PanelSide, type PanelPositionOptions, type PlacementViewport, } from "./pin-view.js";
+export { menuKeyTarget, type MenuPosition } from "./menu.js";
+export { COMMENT_MENU_ATTRIBUTE, useCommentMenu, type CommentMenuState, type UseCommentMenuOptions, } from "./use-comment-menu.js";
+export { isOnScreen, openCommentResponse, type OpenCommentResponse } from "./open-comment.js";
+export { useHeld } from "./use-held.js";
+export { useThreadScroll } from "./use-thread-scroll.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, useCanOpenCommentThread, 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,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,aAAa,GACnB,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,aAAa,EACb,SAAS,EACT,cAAc,EACd,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,YAAY,GAClB,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,cAAc,EACd,eAAe,EACf,QAAQ,EACR,aAAa,EACb,WAAW,EACX,SAAS,EACT,KAAK,SAAS,EACd,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,QAAQ,CAAC;AAC1D,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,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,uBAAuB,EACvB,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,23 @@
+// 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, anchorSubject, } from "./anchor.js";
+export { initials } from "./mentions.js";
+export { toRect } from "./layout.js";
+export { COMMENTS_LAYER_ATTRIBUTE, pinPoint, pickPlacement, groupPins, useCommentPins, } from "./pins.js";
+export { participantKey, pinParticipants, pinWidth, panelPosition, cornerPoint, panelSide, } from "./pin-view.js";
+export { menuKeyTarget } from "./menu.js";
+export { COMMENT_MENU_ATTRIBUTE, useCommentMenu, } from "./use-comment-menu.js";
+export { isOnScreen, openCommentResponse } from "./open-comment.js";
+export { useHeld } from "./use-held.js";
+export { useThreadScroll } from "./use-thread-scroll.js";
+export { usePagePick } from "./page-pick.js";
+export { createCommentsApi } from "./api.js";
+export { setCommentMode, onCommentModeExit, setCommentOptions, onCommentModeRequest, openCommentThread, canOpenCommentThread, useCanOpenCommentThread, 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"}

package/dist/comments/layout.js

@@ -0,0 +1,83 @@
+import { useEffect, useState } from "react";
+import { isPickIgnored } from "./anchor.js";
+/**
+ * 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 const usePageLayoutTick = (isActive) => {
+    const [tick, setTick] = useState(0);
+    useEffect(() => {
+        if (!isActive || typeof window === "undefined") {
+            return;
+        }
+        let frame = 0;
+        const schedule = () => {
+            if (!frame) {
+                frame = window.requestAnimationFrame(() => {
+                    frame = 0;
+                    setTick((value) => value + 1);
+                });
+            }
+        };
+        const mutations = new MutationObserver((records) => {
+            if (records.some((record) => !isPickIgnored(record.target))) {
+                schedule();
+            }
+        });
+        mutations.observe(document.body, { subtree: true, childList: true, characterData: true });
+        const resizes = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(schedule);
+        resizes?.observe(document.body);
+        document.addEventListener("scroll", schedule, true);
+        window.addEventListener("resize", schedule);
+        return () => {
+            window.cancelAnimationFrame(frame);
+            mutations.disconnect();
+            resizes?.disconnect();
+            document.removeEventListener("scroll", schedule, true);
+            window.removeEventListener("resize", schedule);
+        };
+    }, [isActive]);
+    return tick;
+};
+export const toRect = (rect) => ({
+    top: rect.top,
+    left: rect.left,
+    right: rect.right,
+    bottom: rect.bottom,
+});
+/** The overlap of two rects, or null when they don't overlap. */
+export const intersectRects = (a, b) => {
+    const top = Math.max(a.top, b.top);
+    const left = Math.max(a.left, b.left);
+    const right = Math.min(a.right, b.right);
+    const bottom = Math.min(a.bottom, b.bottom);
+    return right > left && bottom > top ? { top, left, right, bottom } : null;
+};
+/** The part of `rect` inside every clip (the viewport, each scrolling ancestor), or null. */
+export const visiblePart = (rect, clips) => {
+    let visible = rect.right > rect.left && rect.bottom > rect.top ? rect : null;
+    for (const clip of clips) {
+        if (!visible) {
+            return null;
+        }
+        visible = intersectRects(visible, clip);
+    }
+    return visible;
+};
+const clipsOverflow = (style) => /(auto|scroll|hidden|clip)/.test(`${style.overflow}${style.overflowX}${style.overflowY}`);
+/** The boxes that clip `element`: the viewport and every ancestor that clips its overflow. */
+export const clipRectsOf = (element) => {
+    const clips = [{ top: 0, left: 0, right: window.innerWidth, bottom: window.innerHeight }];
+    for (let ancestor = element.parentElement; ancestor && ancestor !== document.body; ancestor = ancestor.parentElement) {
+        if (clipsOverflow(window.getComputedStyle(ancestor))) {
+            clips.push(toRect(ancestor.getBoundingClientRect()));
+        }
+    }
+    return clips;
+};

package/dist/comments/mentions.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Mentions in a comment body. Stored, a person is `@[42]` and an agent `@[agent:SupportAgent]`;
+ * in the composer both read as `@Name`. The server parses the stored tokens and never trusts a list
+ * the client sends.
+ */
+export type Mention = {
+    kind: "user";
+    userId: number;
+    name: string;
+} | {
+    kind: "agent";
+    agentId: string;
+    name: string;
+};
+/** Names for the ids a body mentions: the thread's people, the app's agents. */
+export interface MentionNames {
+    users: ReadonlyMap<number, string>;
+    agents: ReadonlyMap<string, string>;
+}
+export declare const mentionToken: (mention: Mention) => string;
+/** The `@query` being typed at the caret, if any: an `@` at a word start, no line break after it. */
+export declare const mentionQueryAt: (text: string, caret: number) => {
+    start: number;
+    query: string;
+} | null;
+/** Whether a mention candidate matches what was typed after `@`: its name contains it, or its email starts with it. */
+export declare const matchesMentionQuery: (candidate: {
+    name: string;
+    email?: string | null;
+}, query: string) => boolean;
+export declare const initials: (name: string) => string;
+//# sourceMappingURL=mentions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mentions.d.ts","sourceRoot":"","sources":["../../src/comments/mentions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,OAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAExH,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,eAAO,MAAM,YAAY,GAAI,SAAS,OAAO,KAAG,MACkC,CAAC;AAEnF,qGAAqG;AACrG,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,EAAE,OAAO,MAAM,KAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAW/F,CAAC;AAEF,uHAAuH;AACvH,eAAO,MAAM,mBAAmB,GAAI,WAAW;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAAE,OAAO,MAAM,KAAG,OAKvG,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,KAAG,MAMpB,CAAC"}

package/dist/comments/mentions.js

@@ -0,0 +1,30 @@
+/**
+ * Mentions in a comment body. Stored, a person is `@[42]` and an agent `@[agent:SupportAgent]`;
+ * in the composer both read as `@Name`. The server parses the stored tokens and never trusts a list
+ * the client sends.
+ */
+export const mentionToken = (mention) => mention.kind === "user" ? `@[${mention.userId}]` : `@[agent:${mention.agentId}]`;
+/** The `@query` being typed at the caret, if any: an `@` at a word start, no line break after it. */
+export const mentionQueryAt = (text, caret) => {
+    const before = text.slice(0, caret);
+    const at = before.lastIndexOf("@");
+    if (at < 0 || (at > 0 && !/\s/.test(before[at - 1]))) {
+        return null;
+    }
+    const query = before.slice(at + 1);
+    if (query.length > 30 || /[\n@]/.test(query) || /\s{2}/.test(query)) {
+        return null;
+    }
+    return { start: at, query };
+};
+/** Whether a mention candidate matches what was typed after `@`: its name contains it, or its email starts with it. */
+export const matchesMentionQuery = (candidate, query) => {
+    const needle = query.trim().toLowerCase();
+    return (!needle || candidate.name.toLowerCase().includes(needle) || (candidate.email ?? "").toLowerCase().startsWith(needle));
+};
+export const initials = (name) => name
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map((part) => part[0].toUpperCase())
+    .join("") || "?";

package/dist/comments/menu.d.ts

@@ -0,0 +1,33 @@
+import type { Rect } from "./layout.js";
+/**
+ * The item a key moves focus to in a menu of `count` items whose item `index` has focus (-1: none):
+ * ↓ and ↑ the next and the previous, wrapping round, Home and End the first and the last; null for
+ * any other key, which the menu leaves alone.
+ */
+export declare const menuKeyTarget: (key: string, index: number, count: number) => number | null;
+/** Where a menu fixed in the window goes: one of `left`/`right`, one of `top`/`bottom`, and its tallest. */
+export interface MenuPosition {
+    side: "bottom" | "top";
+    /** From the window's top (`bottom`) or its bottom (`top`). */
+    top?: number;
+    bottom?: number;
+    left?: number;
+    right?: number;
+    /** The room it has on that side: taller than this, it scrolls. */
+    maxHeight: number;
+}
+/**
+ * Where a menu `height` tall opens beside its trigger (in window coordinates): below it when it
+ * fits there, else above when it fits there or there is more room above (a composer at the bottom
+ * of the window, a sheet on a phone), else below; never taller than the room on its side. Its start
+ * edge lines up with the trigger's start (a picker) or its end edge with the trigger's end (a ⋯),
+ * as the page reads (`isRtl`), from the window's own edges.
+ */
+export declare const menuPosition: (trigger: Rect, { height, align, isRtl, viewportWidth, viewportHeight, }: {
+    height: number;
+    align: "start" | "end";
+    isRtl: boolean;
+    viewportWidth: number;
+    viewportHeight: number;
+}) => MenuPosition;
+//# sourceMappingURL=menu.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"menu.d.ts","sourceRoot":"","sources":["../../src/comments/menu.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAQrC;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,EAAE,OAAO,MAAM,EAAE,OAAO,MAAM,KAAG,MAAM,GAAG,IAgBlF,CAAC;AAMF,4GAA4G;AAC5G,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,QAAQ,GAAG,KAAK,CAAC;IACvB,8DAA8D;IAC9D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GACvB,SAAS,IAAI,EACb,0DAMG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,KAC3G,YAUF,CAAC"}

package/dist/comments/menu.js

@@ -0,0 +1,47 @@
+/*
+ * What the comments' own menus share: which item a key moves to (a comment's ⋯, the composer's
+ * agent picker, a grouped pin's chooser), and where a menu button's menu opens beside its trigger
+ * (the ⋯ and the picker). Pure: the caller passes the window. `useCommentMenu` puts them to work.
+ */
+/**
+ * The item a key moves focus to in a menu of `count` items whose item `index` has focus (-1: none):
+ * ↓ and ↑ the next and the previous, wrapping round, Home and End the first and the last; null for
+ * any other key, which the menu leaves alone.
+ */
+export const menuKeyTarget = (key, index, count) => {
+    if (count <= 0) {
+        return null;
+    }
+    switch (key) {
+        case "ArrowDown":
+            return (index + 1) % count;
+        case "ArrowUp":
+            return index < 0 ? count - 1 : (index - 1 + count) % count;
+        case "Home":
+            return 0;
+        case "End":
+            return count - 1;
+        default:
+            return null;
+    }
+};
+/** The gap between a menu and its trigger, and how far a menu keeps from the window's edge. */
+const MENU_GAP = 4;
+const MENU_EDGE = 8;
+/**
+ * Where a menu `height` tall opens beside its trigger (in window coordinates): below it when it
+ * fits there, else above when it fits there or there is more room above (a composer at the bottom
+ * of the window, a sheet on a phone), else below; never taller than the room on its side. Its start
+ * edge lines up with the trigger's start (a picker) or its end edge with the trigger's end (a ⋯),
+ * as the page reads (`isRtl`), from the window's own edges.
+ */
+export const menuPosition = (trigger, { height, align, isRtl, viewportWidth, viewportHeight, }) => {
+    const roomBelow = viewportHeight - trigger.bottom - MENU_GAP;
+    const roomAbove = trigger.top - MENU_GAP;
+    const vertical = height < roomBelow || (height > roomAbove && roomBelow >= roomAbove)
+        ? { side: "bottom", top: trigger.bottom + MENU_GAP, maxHeight: Math.max(0, roomBelow - MENU_EDGE) }
+        : { side: "top", bottom: viewportHeight - trigger.top + MENU_GAP, maxHeight: Math.max(0, roomAbove - MENU_EDGE) };
+    return (align === "start") !== isRtl
+        ? { ...vertical, left: trigger.left }
+        : { ...vertical, right: viewportWidth - trigger.right };
+};

package/dist/comments/open-comment.d.ts

@@ -0,0 +1,28 @@
+import { type Rect } from "./layout.js";
+/**
+ * - `close`: close it.
+ * - `refocus`: keep it, with focus back in its composer (a click while it holds something unsent).
+ * - `return`: take the page back to it and focus its composer; it is out of sight with something
+ *   unsent. Tried once: when a return has had its chance (its scroll has ended) and the panel is
+ *   still out of sight (its element has no box, or scrolling can't reveal it), the click or Esc
+ *   closes it instead, as Esc does in sight, so nobody is held by a panel they can't see. While the
+ *   return is still under way, another click or Esc answers `return` again: nothing is lost.
+ * - `pass`: it is out of sight with nothing unsent: the click or Esc acts as if nothing were open
+ *   (a click starts a new comment, Esc ends comment mode), and it closes with that.
+ */
+export type OpenCommentResponse = "close" | "refocus" | "return" | "pass";
+export declare const openCommentResponse: ({ input, isOnScreen, hasUnsent, hasReturnFailed, }: {
+    input: "click" | "escape";
+    /** Whether any of its panel is in the window and drawn (`isOnScreen`). */
+    isOnScreen: boolean;
+    /** Whether its composer holds something that would be sent. */
+    hasUnsent: boolean;
+    /** A `return` was answered, its scroll has had time to end, and the panel hasn't been in sight since. */
+    hasReturnFailed?: boolean;
+}) => OpenCommentResponse;
+/** Whether any of `rect` (null: not drawn) is in the window; an empty box is not. */
+export declare const isOnScreen: (rect: Rect | null, viewport: {
+    width: number;
+    height: number;
+}) => boolean;
+//# sourceMappingURL=open-comment.d.ts.map

package/dist/comments/open-comment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-comment.d.ts","sourceRoot":"","sources":["../../src/comments/open-comment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,IAAI,EAAE,MAAM,UAAU,CAAC;AASrD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE1E,eAAO,MAAM,mBAAmB,GAAI,oDAKjC;IACD,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC1B,0EAA0E;IAC1E,UAAU,EAAE,OAAO,CAAC;IACpB,+DAA+D;IAC/D,SAAS,EAAE,OAAO,CAAC;IACnB,yGAAyG;IACzG,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,KAAG,mBAKH,CAAC;AAEF,qFAAqF;AACrF,eAAO,MAAM,UAAU,GAAI,MAAM,IAAI,GAAG,IAAI,EAAE,UAAU;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,KAAG,OACW,CAAC"}

package/dist/comments/open-comment.js

@@ -0,0 +1,9 @@
+import { intersectRects } from "./layout.js";
+export const openCommentResponse = ({ input, isOnScreen, hasUnsent, hasReturnFailed = false, }) => {
+    if (!isOnScreen) {
+        return !hasUnsent ? "pass" : hasReturnFailed ? "close" : "return";
+    }
+    return input === "click" && hasUnsent ? "refocus" : "close";
+};
+/** Whether any of `rect` (null: not drawn) is in the window; an empty box is not. */
+export const isOnScreen = (rect, viewport) => !!rect && !!intersectRects(rect, { top: 0, left: 0, right: viewport.width, bottom: viewport.height });