@blocksdiy/react-common 1.70.1 → 1.71.0

package/dist/comments/anchor.d.ts

@@ -0,0 +1,74 @@
+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;
+/**
+ * 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.
+ */
+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;AAsED,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,cAcrD,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;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,aAAa,KAAG,MAMnD,CAAC"}

package/dist/comments/anchor.js

@@ -0,0 +1,279 @@
+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;
+};
+/** 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 element = findElement(anchor, root) ?? (anchor.item ? root : null);
+    if (!element) {
+        return MISSING;
+    }
+    return checkText(anchor, element);
+};
+/** 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);
+/**
+ * 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.
+ */
+export const anchorLabel = (anchor) => {
+    const text = anchorQuote(anchor) ?? anchor.element?.textSnapshot;
+    if (text) {
+        return text.length > LABEL_MAX ? `${text.slice(0, LABEL_MAX - 1)}…` : text;
+    }
+    return anchorComponentName(anchor) ?? 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]);
+};

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

@@ -0,0 +1,97 @@
+/**
+ * Comment mode: whether the app shows its comments right now. The platform turns it on and off
+ * (its Comment button, over the iframe bridge: app-render calls `setCommentMode`); the app's
+ * comments surface (the registry `comments` item) reads it and can turn it off itself (Esc), which
+ * the platform hears through `onCommentModeExit`. Host and app share this module: it is a UMD
+ * external app-render provides, so no window global is needed.
+ *
+ * Turning it on is a handshake: it resolves `true` once a surface is mounted, waiting a little for
+ * one (the bundle may still be loading). An app without the comments component never answers, so
+ * the platform learns it can't show comments and the mode stays off.
+ *
+ * The app can also open one thread itself (a comment's link in the agent chat): `openCommentThread`
+ * asks the host for comment mode, as its Comment button would, and the surface goes to the thread.
+ */
+/**
+ * What the app's comments show, as the platform's Comment button sets it. `mentionableAgents`: the
+ * block names of the agents this person may mention (their roles' agent mini-apps); all of the
+ * app's agents when absent (the platform hasn't sent its options).
+ */
+export interface CommentOptions {
+    /** Pins of resolved threads and outdated ones (their text changed) show too. */
+    showResolved: boolean;
+    mentionableAgents?: readonly string[];
+}
+export declare const DEFAULT_COMMENT_OPTIONS: CommentOptions;
+/** A thread to open in the app: on its page, scrolled to, open. */
+export interface CommentThreadOpenRequest {
+    threadId: number;
+    /** The page the thread is on (`CommentThreadSummaryDto.routePath`). */
+    routePath: string;
+}
+/** How long turning comment mode on waits for a comments surface to mount. */
+export declare const COMMENT_MODE_CLAIM_TIMEOUT_MS = 5000;
+export interface CommentModeTimers {
+    setTimeout(callback: () => void, ms: number): ReturnType<typeof setTimeout>;
+    clearTimeout(id: ReturnType<typeof setTimeout>): void;
+}
+export interface CommentModeStore {
+    /** The host: turn comment mode on or off. On resolves false when no surface mounted in time. */
+    set(isOn: boolean): Promise<boolean>;
+    isOn(): boolean;
+    subscribe(listener: () => void): () => void;
+    /** The app: a comments surface is mounted while the returned function hasn't been called. */
+    registerSurface(): () => void;
+    /** The app: the surface turned comment mode off itself (Esc). The host hears it. */
+    exit(): void;
+    /** The host: hears when the app turned comment mode off itself. */
+    onExit(listener: () => void): () => void;
+    /** The host: what the comments show (resolved and outdated pins, the agents to mention). */
+    setOptions(options: CommentOptions): void;
+    options(): CommentOptions;
+    /** The app's surface: opens the threads asked for while the returned function hasn't been called. */
+    handleOpenThread(handler: (request: CommentThreadOpenRequest) => void): () => void;
+    /** The host: hears the app ask for comment mode (to show a thread it opens). */
+    onRequestOn(listener: () => void): () => void;
+    /** Whether a thread can be opened from inside the app: a host listens and a surface opens it. */
+    canOpenThread(): boolean;
+    /** The app: asks the host for comment mode and the surface for the thread. False when it can't here. */
+    openThread(request: CommentThreadOpenRequest): boolean;
+}
+export declare const createCommentModeStore: (timers?: CommentModeTimers) => CommentModeStore;
+/** The one store the host and the app share. */
+export declare const commentMode: CommentModeStore;
+/** The host: turn comment mode on or off (resolves false when the app has no comments surface). */
+export declare const setCommentMode: (isOn: boolean) => Promise<boolean>;
+/** The host: hears when the app turned comment mode off itself. Returns the unsubscribe. */
+export declare const onCommentModeExit: (listener: () => void) => (() => void);
+/** The host: what the app's comments show (the Comment button's options). */
+export declare const setCommentOptions: (next: CommentOptions) => void;
+/** The host: hears the app ask for comment mode. Returns the unsubscribe. */
+export declare const onCommentModeRequest: (listener: () => void) => (() => void);
+/**
+ * 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 declare const openCommentThread: (request: CommentThreadOpenRequest, store?: CommentModeStore) => boolean;
+/** Whether `openCommentThread` can open a thread here: the link back to it shows only then. */
+export declare const canOpenCommentThread: (store?: CommentModeStore) => boolean;
+export interface UseCommentsSurfaceOptions {
+    /**
+     * Opens a thread `openCommentThread` asked for: navigate to its page with the thread's link
+     * (`?comment=<id>`), which the comments then open.
+     */
+    onOpenThread?: (request: CommentThreadOpenRequest) => void;
+    store?: CommentModeStore;
+}
+/**
+ * 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 declare const useCommentsSurface: ({ onOpenThread, store }?: UseCommentsSurfaceOptions) => {
+    isCommentMode: boolean;
+    options: CommentOptions;
+    exit: () => void;
+};
+//# sourceMappingURL=comment-mode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"comment-mode.d.ts","sourceRoot":"","sources":["../../src/comments/comment-mode.ts"],"names":[],"mappings":"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"}