@blocksdiy/react-common 1.70.2 → 1.71.1

package/dist/comments/anchor.d.ts

@@ -0,0 +1,96 @@
+import { type CommentAnchor, type CommentAnchorItem } from "./types.js";
+/**
+ * Where a comment (or a pick from the chat) points, and finding that place again on the page as it
+ * is now. An anchor keeps several signals — the row, the source location, its position among the
+ * same source's elements, a DOM path and the text itself — because none of them alone survives an
+ * edit to the app or a re-sorted list.
+ */
+/** An app marks the element that shows one row with `data-blocks-item="<table>:<rowId>"`. */
+export declare const ITEM_ATTRIBUTE = "data-blocks-item";
+/** What `fieldAnchorProps` (blocks-client-sdk) tags a column's element with. */
+export declare const FIELD_ATTRIBUTE = "data-blocks-field";
+/**
+ * Inside an element with this attribute nothing is picked, and the picker blocks no click: the
+ * comments' own UI, the agent chat (the registry's `pagePickIgnoreProps` writes it).
+ */
+export declare const PICK_IGNORE_ATTRIBUTE = "data-blocks-pick-ignore";
+/** An element's text as it reads, whitespace collapsed. */
+export declare const textOf: (element: HTMLElement) => string;
+/**
+ * `"<table>:<rowId>"` as a row. Split on the last colon: the table part is what the app's code
+ * calls the table (generated code uses its title), and row ids are digits.
+ */
+export declare const parseItemAttribute: (value: string | null | undefined) => CommentAnchorItem | undefined;
+/** True when `node` is inside UI the picker leaves alone. */
+export declare const isPickIgnored: (node: Node | null) => boolean;
+/**
+ * The element a click or selection is about: the nearest one the app's own markup tagged, else the
+ * element itself. Null inside ignored UI.
+ */
+export declare const pickTarget: (node: Node | null) => HTMLElement | null;
+/**
+ * Describes where a comment points, from the element picked and, when text was highlighted inside
+ * it, the selection. `clientX`/`clientY` (the click) keep where in the element it was dropped.
+ */
+export declare const captureAnchor: (options: {
+    routePath: string;
+    element: HTMLElement;
+    range?: Range | null;
+    clientX?: number;
+    clientY?: number;
+}) => CommentAnchor;
+export type AnchorState = "anchored" | "outdated" | "missing";
+export interface ResolvedAnchor {
+    state: AnchorState;
+    element: HTMLElement | null;
+    /** The highlighted text, found again: where a quote's pin and highlight go. */
+    range: Range | null;
+    /** What the anchored text says now, when it changed. */
+    currentText?: string;
+}
+/** The row's element an anchor names, or null when it has none or the row is not on the page. */
+export declare const findAnchorItemElement: (anchor: CommentAnchor, root?: ParentNode) => Element | null;
+/**
+ * Finds an anchor on the page as it is now. `outdated`: the element is there but the text the
+ * comment was about changed, so the thread shows what it said.
+ */
+export declare const resolveAnchor: (anchor: CommentAnchor) => ResolvedAnchor;
+/** Whether `element` still says what the anchor was about. */
+export declare const checkText: (anchor: CommentAnchor, element: HTMLElement) => ResolvedAnchor;
+/** The words the thread is about: the highlighted text, else the element's text when short. */
+export declare const anchorQuote: (anchor: CommentAnchor) => string | undefined;
+/**
+ * A component's name as the app's code gives it (`TaskCard`): a `devName` that starts with a
+ * capital. A plain element's `devName` is its tag (`div`), jargon to the app's people: none then.
+ */
+export declare const componentNameOf: (devName: string | null | undefined) => string | undefined;
+/** The component an anchor's element is (`componentNameOf`), when it has a name. */
+export declare const anchorComponentName: (anchor: CommentAnchor) => string | undefined;
+/** The kinds of text-less element a thread can name in plain words (the words are the UI's). */
+export type AnchorElementKind = "image" | "icon" | "video" | "field" | "button" | "link";
+/** What a thread is about, as its header names it; see `anchorSubject`. */
+export type AnchorSubject = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "component";
+    name: string;
+} | {
+    kind: "element";
+    element: AnchorElementKind;
+} | {
+    kind: "page";
+    routePath: string;
+};
+/**
+ * What an anchor is about, never a tag: its words (the highlighted text, else the element's text,
+ * however long: the UI cuts it), else its component's name, else the kind of a common text-less
+ * element (an image, an icon, a video, a field, a button, a link), else its page.
+ */
+export declare const anchorSubject: (anchor: CommentAnchor) => AnchorSubject;
+/**
+ * A short name for what an anchor points at, never a tag: its quote, else its element's text,
+ * clipped, else its component's name, else its page (`anchorSubject`, an element's kind aside).
+ */
+export declare const anchorLabel: (anchor: CommentAnchor) => string;
+//# sourceMappingURL=anchor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../../src/comments/anchor.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,aAAa,EAElB,KAAK,iBAAiB,EACvB,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AAEH,6FAA6F;AAC7F,eAAO,MAAM,cAAc,qBAAqB,CAAC;AACjD,gFAAgF;AAChF,eAAO,MAAM,eAAe,sBAAsB,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAQ/D,2DAA2D;AAC3D,eAAO,MAAM,MAAM,GAAI,SAAS,WAAW,WAA8D,CAAC;AAO1G;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,iBAAiB,GAAG,SAMzF,CAAC;AAyBF,6DAA6D;AAC7D,eAAO,MAAM,aAAa,GAAI,MAAM,IAAI,GAAG,IAAI,KAAG,OAGjD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,IAAI,GAAG,IAAI,KAAG,WAAW,GAAG,IAS5D,CAAC;AAmCF;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,WAAW,CAAC;IACrB,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,KAAG,aAgDH,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,+EAA+E;IAC/E,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA6ED,iGAAiG;AACjG,eAAO,MAAM,qBAAqB,GAAI,QAAQ,aAAa,EAAE,OAAM,UAAqB,KAAG,OAAO,GAAG,IACjC,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,aAAa,KAAG,cA2CrD,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,SAAS,GAAI,QAAQ,aAAa,EAAE,SAAS,WAAW,KAAG,cAavE,CAAC;AAEF,+FAA+F;AAC/F,eAAO,MAAM,WAAW,GAAI,QAAQ,aAAa,KAAG,MAAM,GAAG,SAM5D,CAAC;AAIF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,MAAM,GAAG,SACrB,CAAC;AAE1D,oFAAoF;AACpF,eAAO,MAAM,mBAAmB,GAAI,QAAQ,aAAa,KAAG,MAAM,GAAG,SAC3B,CAAC;AAE3C,gGAAgG;AAChG,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAgBzF,2EAA2E;AAC3E,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,iBAAiB,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,aAAa,KAAG,aAYrD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,aAAa,KAAG,MAOnD,CAAC"}

package/dist/comments/anchor.js

@@ -0,0 +1,346 @@
+import { COMMENT_ANCHOR_CONTEXT_MAX_LENGTH, COMMENT_ANCHOR_FIELD_MAX_LENGTH, COMMENT_ANCHOR_TEXT_MAX_LENGTH, } from "./types.js";
+/**
+ * Where a comment (or a pick from the chat) points, and finding that place again on the page as it
+ * is now. An anchor keeps several signals — the row, the source location, its position among the
+ * same source's elements, a DOM path and the text itself — because none of them alone survives an
+ * edit to the app or a re-sorted list.
+ */
+/** An app marks the element that shows one row with `data-blocks-item="<table>:<rowId>"`. */
+export const ITEM_ATTRIBUTE = "data-blocks-item";
+/** What `fieldAnchorProps` (blocks-client-sdk) tags a column's element with. */
+export const FIELD_ATTRIBUTE = "data-blocks-field";
+/**
+ * Inside an element with this attribute nothing is picked, and the picker blocks no click: the
+ * comments' own UI, the agent chat (the registry's `pagePickIgnoreProps` writes it).
+ */
+export const PICK_IGNORE_ATTRIBUTE = "data-blocks-pick-ignore";
+/** An element comment shows "was …" when its text changed, if the text was this short. */
+const SHORT_TEXT_MAX = 200;
+const DOM_PATH_MAX_DEPTH = 12;
+const normalize = (text) => text.replace(/\s+/g, " ").trim();
+/** An element's text as it reads, whitespace collapsed. */
+export const textOf = (element) => normalize(element.innerText ?? element.textContent ?? "");
+const escape = (value) => typeof CSS !== "undefined" && typeof CSS.escape === "function"
+    ? CSS.escape(value)
+    : value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+/**
+ * `"<table>:<rowId>"` as a row. Split on the last colon: the table part is what the app's code
+ * calls the table (generated code uses its title), and row ids are digits.
+ */
+export const parseItemAttribute = (value) => {
+    const separator = value?.lastIndexOf(":") ?? -1;
+    if (!value || separator <= 0 || separator === value.length - 1) {
+        return undefined;
+    }
+    return { tableBlockId: value.slice(0, separator), itemId: value.slice(separator + 1) };
+};
+const itemSelector = (item) => `[${ITEM_ATTRIBUTE}="${escape(`${item.tableBlockId}:${item.itemId}`)}"]`;
+const sameSourceSelector = (devPath, devName) => `[data-dev-path="${escape(devPath)}"][data-dev-name="${escape(devName)}"]`;
+/** `:scope > div:nth-of-type(2) > span:nth-of-type(1)` from `root` down to `element`. */
+const domPathFrom = (root, element) => {
+    const parts = [];
+    let current = element;
+    while (current && current !== root && parts.length < DOM_PATH_MAX_DEPTH) {
+        const parent = current.parentElement;
+        if (!parent) {
+            return undefined;
+        }
+        const tag = current.tagName;
+        const sameTag = Array.from(parent.children).filter((child) => child.tagName === tag);
+        parts.unshift(`${tag.toLowerCase()}:nth-of-type(${sameTag.indexOf(current) + 1})`);
+        current = parent;
+    }
+    return current === root && parts.length > 0 ? `:scope > ${parts.join(" > ")}` : undefined;
+};
+/** True when `node` is inside UI the picker leaves alone. */
+export const isPickIgnored = (node) => {
+    const element = node instanceof Element ? node : (node?.parentElement ?? null);
+    return !!element?.closest(`[${PICK_IGNORE_ATTRIBUTE}]`);
+};
+/**
+ * The element a click or selection is about: the nearest one the app's own markup tagged, else the
+ * element itself. Null inside ignored UI.
+ */
+export const pickTarget = (node) => {
+    if (!node || isPickIgnored(node)) {
+        return null;
+    }
+    const element = node instanceof HTMLElement ? node : node.parentElement;
+    if (!element) {
+        return null;
+    }
+    return element.closest("[data-dev-id]") ?? element;
+};
+/** The text of a selection inside `element`, with context on both sides; undefined when none. */
+const selectedText = (element, range) => {
+    if (!range || range.collapsed || !element.contains(range.commonAncestorContainer)) {
+        return undefined;
+    }
+    const selected = range.toString();
+    const trimmed = selected.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    // A double or triple click selects the space or line break around the words too: that whitespace
+    // goes to the context, so prefix + exact + suffix is still the element's text.
+    const leading = selected.slice(0, selected.length - selected.trimStart().length);
+    const exact = trimmed.slice(0, COMMENT_ANCHOR_TEXT_MAX_LENGTH);
+    const trailing = trimmed.slice(exact.length) + selected.slice(selected.trimEnd().length);
+    const before = document.createRange();
+    before.selectNodeContents(element);
+    before.setEnd(range.startContainer, range.startOffset);
+    const after = document.createRange();
+    after.selectNodeContents(element);
+    after.setStart(range.endContainer, range.endOffset);
+    return {
+        exact,
+        prefix: (before.toString() + leading).slice(-COMMENT_ANCHOR_CONTEXT_MAX_LENGTH),
+        suffix: (trailing + after.toString()).slice(0, COMMENT_ANCHOR_CONTEXT_MAX_LENGTH),
+    };
+};
+const clamp01 = (value) => Math.min(1, Math.max(0, Number.isFinite(value) ? value : 0));
+const stripUndefined = (value) => Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+/**
+ * Describes where a comment points, from the element picked and, when text was highlighted inside
+ * it, the selection. `clientX`/`clientY` (the click) keep where in the element it was dropped.
+ */
+export const captureAnchor = (options) => {
+    const { element } = options;
+    const itemElement = element.closest(`[${ITEM_ATTRIBUTE}]`);
+    const item = parseItemAttribute(itemElement?.getAttribute(ITEM_ATTRIBUTE));
+    const root = (item && itemElement) || document.body;
+    const devPath = element.getAttribute("data-dev-path") ?? undefined;
+    const devName = element.getAttribute("data-dev-name") ?? undefined;
+    const anchorElement = {
+        devId: element.getAttribute("data-dev-id") ?? undefined,
+        devPath,
+        devName,
+        tagName: element.tagName,
+        domPath: domPathFrom(root, element),
+    };
+    if (devPath && devName) {
+        const ordinal = Array.from(root.querySelectorAll(sameSourceSelector(devPath, devName))).indexOf(element);
+        if (ordinal >= 0) {
+            anchorElement.ordinal = ordinal;
+        }
+    }
+    const text = textOf(element);
+    if (text) {
+        anchorElement.textSnapshot = text.slice(0, COMMENT_ANCHOR_TEXT_MAX_LENGTH);
+    }
+    const anchor = { v: 1, routePath: options.routePath, element: stripUndefined(anchorElement) };
+    if (item) {
+        // The column the element shows: the nearest tag at or above it, inside the row's element.
+        const fieldElement = element.closest(`[${FIELD_ATTRIBUTE}]`);
+        const field = fieldElement && itemElement?.contains(fieldElement) ? fieldElement.getAttribute(FIELD_ATTRIBUTE) : null;
+        anchor.item = field ? { ...item, field: field.slice(0, COMMENT_ANCHOR_FIELD_MAX_LENGTH) } : item;
+    }
+    const quote = selectedText(element, options.range);
+    if (quote) {
+        anchor.text = quote;
+    }
+    if (options.clientX !== undefined && options.clientY !== undefined) {
+        const rect = element.getBoundingClientRect();
+        if (rect.width > 0 && rect.height > 0) {
+            anchor.point = {
+                x: clamp01((options.clientX - rect.left) / rect.width),
+                y: clamp01((options.clientY - rect.top) / rect.height),
+            };
+        }
+    }
+    return anchor;
+};
+const MISSING = { state: "missing", element: null, range: null };
+const findElement = (anchor, root) => {
+    const element = anchor.element;
+    if (!element) {
+        return null;
+    }
+    if (element.devPath && element.devName && element.ordinal !== undefined) {
+        // No ordinal: the element was the row's own element, which its descendants never match.
+        const byOrdinal = root.querySelectorAll(sameSourceSelector(element.devPath, element.devName))[element.ordinal];
+        if (byOrdinal) {
+            return byOrdinal;
+        }
+    }
+    if (element.devId) {
+        const byId = root.querySelector(`[data-dev-id="${escape(element.devId)}"]`);
+        if (byId) {
+            return byId;
+        }
+    }
+    if (element.domPath) {
+        try {
+            const byPath = root.querySelector(element.domPath);
+            if (byPath && (!element.tagName || byPath.tagName === element.tagName)) {
+                return byPath;
+            }
+        }
+        catch {
+            // A path the current DOM can't parse: no match.
+        }
+    }
+    return null;
+};
+/** A Range over the first occurrence of `exact` in `element`'s text, preferring one in context. */
+const findTextRange = (element, text) => {
+    const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
+    const nodes = [];
+    let content = "";
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+        nodes.push(node);
+        content += node.data;
+    }
+    const inContext = content.indexOf(text.prefix + text.exact + text.suffix);
+    const start = inContext >= 0 ? inContext + text.prefix.length : content.indexOf(text.exact);
+    if (start < 0) {
+        return null;
+    }
+    const end = start + text.exact.length;
+    const range = document.createRange();
+    let offset = 0;
+    let startSet = false;
+    for (const node of nodes) {
+        const next = offset + node.data.length;
+        if (!startSet && start < next) {
+            range.setStart(node, start - offset);
+            startSet = true;
+        }
+        if (startSet && end <= next) {
+            range.setEnd(node, end - offset);
+            return range;
+        }
+        offset = next;
+    }
+    return null;
+};
+/** Whether `element` is inside the row's tag of a column other than `field` (untagged: unknown, so no). */
+const showsAnotherField = (element, row, field) => {
+    const tagged = element.closest(`[${FIELD_ATTRIBUTE}]`);
+    const shown = tagged && row.contains(tagged) ? tagged.getAttribute(FIELD_ATTRIBUTE) : null;
+    return !!shown && shown.slice(0, COMMENT_ANCHOR_FIELD_MAX_LENGTH) !== field;
+};
+/** The row's element an anchor names, or null when it has none or the row is not on the page. */
+export const findAnchorItemElement = (anchor, root = document) => anchor.item ? root.querySelector(itemSelector(anchor.item)) : null;
+/**
+ * Finds an anchor on the page as it is now. `outdated`: the element is there but the text the
+ * comment was about changed, so the thread shows what it said.
+ */
+export const resolveAnchor = (anchor) => {
+    let root = document.body;
+    if (anchor.item) {
+        const itemElement = findAnchorItemElement(anchor);
+        if (!itemElement) {
+            return MISSING;
+        }
+        root = itemElement;
+    }
+    const found = findElement(anchor, root);
+    // Another view of the row can have an element from the same source at the same place that
+    // shows another column: not the one the comment was on.
+    const element = found && anchor.item?.field && showsAnotherField(found, root, anchor.item.field) ? null : found;
+    if (element) {
+        return checkText(anchor, element);
+    }
+    if (!anchor.item) {
+        return MISSING;
+    }
+    // The row is on the page without the element the comment was on: the row's own element, or
+    // another view of the same rows (a board's card, a list's line). The thread stays with its row.
+    const row = root;
+    const inner = anchor.element;
+    if (inner?.ordinal === undefined && !inner?.domPath) {
+        return checkText(anchor, row);
+    }
+    // On the column it was about, when this view tags it; else on the part of the row that says
+    // what the comment was about (the innermost such element); else on the row, out of date.
+    const field = anchor.item.field
+        ? row.querySelector(`[${FIELD_ATTRIBUTE}="${escape(anchor.item.field)}"]`)
+        : null;
+    if (field) {
+        return checkText(anchor, field);
+    }
+    const snapshot = inner?.textSnapshot;
+    if (!anchor.text && snapshot) {
+        const saying = Array.from(row.querySelectorAll("*")).filter((part) => textOf(part) === snapshot);
+        const innermost = saying[saying.length - 1];
+        if (innermost) {
+            return { state: "anchored", element: innermost, range: null };
+        }
+    }
+    return checkText(anchor, row);
+};
+/** Whether `element` still says what the anchor was about. */
+export const checkText = (anchor, element) => {
+    const current = textOf(element);
+    if (anchor.text) {
+        const range = findTextRange(element, anchor.text);
+        return range
+            ? { state: "anchored", element, range }
+            : { state: "outdated", element, range: null, currentText: current.slice(0, SHORT_TEXT_MAX) };
+    }
+    const snapshot = anchor.element?.textSnapshot;
+    if (snapshot && snapshot.length <= SHORT_TEXT_MAX && current !== snapshot) {
+        return { state: "outdated", element, range: null, currentText: current.slice(0, SHORT_TEXT_MAX) };
+    }
+    return { state: "anchored", element, range: null };
+};
+/** The words the thread is about: the highlighted text, else the element's text when short. */
+export const anchorQuote = (anchor) => {
+    if (anchor.text) {
+        return anchor.text.exact;
+    }
+    const snapshot = anchor.element?.textSnapshot;
+    return snapshot && snapshot.length <= SHORT_TEXT_MAX ? snapshot : undefined;
+};
+const LABEL_MAX = 40;
+/**
+ * A component's name as the app's code gives it (`TaskCard`): a `devName` that starts with a
+ * capital. A plain element's `devName` is its tag (`div`), jargon to the app's people: none then.
+ */
+export const componentNameOf = (devName) => devName && /^[A-Z]/.test(devName) ? devName : undefined;
+/** The component an anchor's element is (`componentNameOf`), when it has a name. */
+export const anchorComponentName = (anchor) => componentNameOf(anchor.element?.devName);
+/** Tags (HTML ones stored in capitals, SVG ones as written, so compared in capitals) by kind. */
+const ELEMENT_KINDS = new Map([
+    ["IMG", "image"],
+    ["PICTURE", "image"],
+    ["CANVAS", "image"],
+    ["SVG", "icon"],
+    ["VIDEO", "video"],
+    ["INPUT", "field"],
+    ["TEXTAREA", "field"],
+    ["SELECT", "field"],
+    ["BUTTON", "button"],
+    ["A", "link"],
+]);
+/**
+ * What an anchor is about, never a tag: its words (the highlighted text, else the element's text,
+ * however long: the UI cuts it), else its component's name, else the kind of a common text-less
+ * element (an image, an icon, a video, a field, a button, a link), else its page.
+ */
+export const anchorSubject = (anchor) => {
+    const text = anchorQuote(anchor) ?? anchor.element?.textSnapshot;
+    if (text) {
+        return { kind: "text", text };
+    }
+    const name = anchorComponentName(anchor);
+    if (name) {
+        return { kind: "component", name };
+    }
+    const tag = anchor.element?.tagName?.toUpperCase();
+    const element = tag ? ELEMENT_KINDS.get(tag) : undefined;
+    return element ? { kind: "element", element } : { kind: "page", routePath: anchor.routePath };
+};
+/**
+ * A short name for what an anchor points at, never a tag: its quote, else its element's text,
+ * clipped, else its component's name, else its page (`anchorSubject`, an element's kind aside).
+ */
+export const anchorLabel = (anchor) => {
+    const subject = anchorSubject(anchor);
+    if (subject.kind === "text") {
+        const { text } = subject;
+        return text.length > LABEL_MAX ? `${text.slice(0, LABEL_MAX - 1)}…` : text;
+    }
+    return subject.kind === "component" ? subject.name : anchor.routePath;
+};

package/dist/comments/api.d.ts

@@ -0,0 +1,38 @@
+import type { CommentAnchor, CommentThreadDto, CommentThreadsPageDto, MentionableUsersDto } from "./types.js";
+/**
+ * The in-app comments API, through the platform's proxy (`/data-api/apps/:appId/comments/**`), as
+ * the signed-in app user. The token is read at call time, so a refreshed token needs no new client.
+ */
+/** A non-2xx answer, with its status: a 404 means "not there, or not yours to see". */
+export declare class CommentsRequestError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}
+export interface CommentsApi {
+    /** One page of a page's threads, newest activity first. */
+    listThreads(routePath: string, options?: {
+        cursor?: string;
+    }): Promise<CommentThreadsPageDto>;
+    getThread(threadId: number): Promise<CommentThreadDto>;
+    createThread(request: {
+        anchor: CommentAnchor;
+        body: string;
+    }): Promise<CommentThreadDto>;
+    addComment(threadId: number, body: string): Promise<CommentThreadDto>;
+    updateComment(commentId: number, body: string): Promise<CommentThreadDto>;
+    /** The thread without the comment; null when it was the thread's last: the thread is gone. */
+    deleteComment(commentId: number): Promise<CommentThreadDto | null>;
+    resolveThread(threadId: number): Promise<CommentThreadDto>;
+    reopenThread(threadId: number): Promise<CommentThreadDto>;
+    mentionableUsers(): Promise<MentionableUsersDto>;
+}
+export interface CreateCommentsApiOptions {
+    appId: string;
+    /** The app user's token, read on every call. */
+    getToken: () => string | undefined;
+    /** Defaults to the platform host (`getApiHost`). */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+export declare const createCommentsApi: ({ appId, getToken, baseUrl, fetch: fetchImpl, }: CreateCommentsApiOptions) => CommentsApi;
+//# sourceMappingURL=api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/comments/api.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE3G;;;GAGG;AAEH,uFAAuF;AACvF,qBAAa,oBAAqB,SAAQ,KAAK;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAIpC;AAED,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC9F,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACvD,YAAY,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,aAAa,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC1F,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACtE,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC1E,8FAA8F;IAC9F,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACnE,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC3D,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC1D,gBAAgB,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,QAAQ,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACnC,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,eAAO,MAAM,iBAAiB,GAAI,iDAK/B,wBAAwB,KAAG,WAiD7B,CAAC"}

package/dist/comments/api.js

@@ -0,0 +1,62 @@
+import { getBuilderContextHeaders } from "@blocksdiy/blocks-client-api";
+import { getApiHost } from "@blocksdiy/blocks-client-api/envService";
+import { websocketsService } from "@blocksdiy/blocks-client-api/websocketService";
+/**
+ * The in-app comments API, through the platform's proxy (`/data-api/apps/:appId/comments/**`), as
+ * the signed-in app user. The token is read at call time, so a refreshed token needs no new client.
+ */
+/** A non-2xx answer, with its status: a 404 means "not there, or not yours to see". */
+export class CommentsRequestError extends Error {
+    status;
+    constructor(status) {
+        super(`Comments request failed with status ${status}`);
+        this.status = status;
+        this.name = "CommentsRequestError";
+    }
+}
+export const createCommentsApi = ({ appId, getToken, baseUrl, fetch: fetchImpl = (...args) => fetch(...args), }) => {
+    const request = async (path, init = {}) => {
+        const token = getToken();
+        const socketId = websocketsService.getSocketId();
+        const response = await fetchImpl(`${baseUrl ?? getApiHost()}/data-api/apps/${encodeURIComponent(appId)}/comments/${path}`, {
+            method: init.method ?? "GET",
+            headers: {
+                ...(token ? { Authorization: `Bearer ${token}` } : {}),
+                ...(init.body === undefined ? {} : { "Content-Type": "application/json" }),
+                // A person's change pings every tab but theirs: their write returned it. An agent's
+                // events (picking a mention up, its progress, its answer) reach every tab.
+                ...(socketId ? { "x-socket-id": socketId } : {}),
+                "x-app-id": appId,
+                ...getBuilderContextHeaders(appId),
+            },
+            body: init.body === undefined ? undefined : JSON.stringify(init.body),
+        });
+        if (!response.ok) {
+            throw new CommentsRequestError(response.status);
+        }
+        // No content: what was asked for is gone (a thread whose last comment was deleted).
+        if (response.status === 204) {
+            return null;
+        }
+        return (await response.json());
+    };
+    const post = (path, body = {}) => request(path, { method: "POST", body });
+    return {
+        listThreads: (routePath, options = {}) => {
+            const query = new URLSearchParams({ routePath });
+            if (options.cursor) {
+                query.set("cursor", options.cursor);
+            }
+            return request(`threads?${query}`);
+        },
+        getThread: (threadId) => request(`threads/${threadId}`),
+        createThread: (body) => post("threads", body),
+        addComment: (threadId, body) => post(`threads/${threadId}/comments`, { body }),
+        // POST only: the platform answers an app cross-origin, and its CORS allows GET and POST.
+        updateComment: (commentId, body) => post(`${commentId}/edit`, { body }),
+        deleteComment: (commentId) => post(`${commentId}/delete`),
+        resolveThread: (threadId) => post(`threads/${threadId}/resolve`),
+        reopenThread: (threadId) => post(`threads/${threadId}/reopen`),
+        mentionableUsers: () => request("mentionable-users"),
+    };
+};

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

@@ -0,0 +1,28 @@
+/**
+ * The agents a comment can mention: the app's floating-chat agents (one per agent mini-app), as
+ * the floating chat's provider registers them while it is mounted, with the way to open one's
+ * conversation in its panel. The comments surface reads them; it never imports the chat itself. An
+ * app without the floating chat offers people only.
+ */
+export interface CommentAgent {
+    /** The agent block's name, what a mention stores (`@[agent:<id>]`). */
+    id: string;
+    /** The persona's name. */
+    title: string;
+    photoUrl?: string;
+}
+/** Opens the floating chat on an agent's conversation (`chatThreadId`). */
+export type OpenCommentAgentThread = (agentId: string, chatThreadId: string) => void;
+export interface CommentAgentsSnapshot {
+    agents: readonly CommentAgent[];
+    openThread: OpenCommentAgentThread | null;
+}
+/** Registers the app's agents; returns the unregister. The latest registration wins. */
+export declare const registerCommentAgents: (agents: readonly CommentAgent[], openThread: OpenCommentAgentThread) => (() => void);
+/** The agents registered now (what `useCommentAgents` reads). */
+export declare const readCommentAgents: () => CommentAgentsSnapshot;
+/** The agents comments can mention, and how to open one's conversation. */
+export declare const useCommentAgents: () => CommentAgentsSnapshot;
+/** Registers `agents` while the calling component is mounted (the floating chat's provider). */
+export declare const useRegisterCommentAgents: (agents: readonly CommentAgent[], openThread: OpenCommentAgentThread) => void;
+//# sourceMappingURL=comment-agents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"comment-agents.d.ts","sourceRoot":"","sources":["../../src/comments/comment-agents.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,2EAA2E;AAC3E,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;AAErF,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IAChC,UAAU,EAAE,sBAAsB,GAAG,IAAI,CAAC;CAC3C;AASD,wFAAwF;AACxF,eAAO,MAAM,qBAAqB,GAChC,QAAQ,SAAS,YAAY,EAAE,EAC/B,YAAY,sBAAsB,KACjC,CAAC,MAAM,IAAI,CAUb,CAAC;AAQF,iEAAiE;AACjE,eAAO,MAAM,iBAAiB,QAAO,qBAAgC,CAAC;AAEtE,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,QAAO,qBACmC,CAAC;AAExE,gGAAgG;AAChG,eAAO,MAAM,wBAAwB,GAAI,QAAQ,SAAS,YAAY,EAAE,EAAE,YAAY,sBAAsB,KAAG,IAE9G,CAAC"}

package/dist/comments/comment-agents.js

@@ -0,0 +1,32 @@
+import { useEffect, useSyncExternalStore } from "react";
+const NONE = { agents: [], openThread: null };
+let current = NONE;
+let registration = 0;
+const listeners = new Set();
+const emit = () => listeners.forEach((listener) => listener());
+/** Registers the app's agents; returns the unregister. The latest registration wins. */
+export const registerCommentAgents = (agents, openThread) => {
+    const id = ++registration;
+    current = { agents, openThread };
+    emit();
+    return () => {
+        if (registration === id) {
+            current = NONE;
+            emit();
+        }
+    };
+};
+const subscribe = (listener) => {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+};
+/** The agents registered now (what `useCommentAgents` reads). */
+export const readCommentAgents = () => current;
+/** The agents comments can mention, and how to open one's conversation. */
+export const useCommentAgents = () => useSyncExternalStore(subscribe, readCommentAgents, readCommentAgents);
+/** Registers `agents` while the calling component is mounted (the floating chat's provider). */
+export const useRegisterCommentAgents = (agents, openThread) => {
+    useEffect(() => registerCommentAgents(agents, openThread), [agents, openThread]);
+};