@softr/sdk 0.0.52 → 0.0.54-alpha.0

package/dist/action.d.ts

@@ -234,5 +234,35 @@ type IntegrationDefinition<TId extends string> = {
  * const res = await listEvents({ query: { timeMin: now, singleEvents: "true" } })
  */
 declare function defineIntegration<const TId extends string>(definition: IntegrationDefinition<TId>): IntegrationAction<TId>;
+type CommentsResource = {
+  type: "COMMENTS";
+  datasourceId: SoftrDatasourceId;
+};
+/** Comment threads on the records of one datasource. It has no `permissions`. */
+type CommentsAction<TId extends string = string> = {
+  id: TId;
+  resource: CommentsResource;
+};
+type CommentsDefinition<TId extends string> = {
+  id: TId;
+  datasourceId: SoftrDatasourceId;
+};
+/**
+ * Declares comment threads on the records of a datasource. Each record has one thread.
+ *
+ * Who may read, post and delete comes from the app's comment settings in Softr, not from code. Two
+ * declarations on the same datasource share the same threads.
+ *
+ * Pass the returned object to `comments.*` from `@softr/sdk/server`.
+ *
+ * @example
+ * const orderComments = defineComments({
+ *   id: "orderComments",
+ *   datasourceId: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
+ * })
+ *
+ * const thread = await comments.list(orderComments, { recordId })
+ */
+declare function defineComments<const TId extends string>(definition: CommentsDefinition<TId>): CommentsAction<TId>;
 //#endregion
-export { ActionData, ActionPermissions, ActionRecord, ActionShape, DatasourceAction, FieldTypeOf, IntegrationAction, ReadOf, ReadShape, SoftrDatasources, WorkflowAction, defineIntegration, defineMutation, defineQuery, defineWorkflow };
+export { ActionData, ActionPermissions, ActionRecord, ActionShape, CommentsAction, DatasourceAction, FieldTypeOf, IntegrationAction, ReadOf, ReadShape, SoftrDatasources, WorkflowAction, defineComments, defineIntegration, defineMutation, defineQuery, defineWorkflow };

package/dist/action.js

@@ -50,6 +50,31 @@ function defineIntegration(definition) {
 		permissions
 	};
 }
+/**
+* Declares comment threads on the records of a datasource. Each record has one thread.
+*
+* Who may read, post and delete comes from the app's comment settings in Softr, not from code. Two
+* declarations on the same datasource share the same threads.
+*
+* Pass the returned object to `comments.*` from `@softr/sdk/server`.
+*
+* @example
+* const orderComments = defineComments({
+*   id: "orderComments",
+*   datasourceId: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
+* })
+*
+* const thread = await comments.list(orderComments, { recordId })
+*/
+function defineComments(definition) {
+	return {
+		id: definition.id,
+		resource: {
+			type: "COMMENTS",
+			datasourceId: definition.datasourceId
+		}
+	};
+}
 function isDatasourceAction(value) {
 	if (typeof value !== "object" || value === null) return false;
 	const candidate = value;
@@ -58,4 +83,4 @@ function isDatasourceAction(value) {
 }
 
 //#endregion
-export { defineIntegration, defineMutation, defineQuery, defineWorkflow, isDatasourceAction };
+export { defineComments, defineIntegration, defineMutation, defineQuery, defineWorkflow, isDatasourceAction };

package/dist/client.d.ts

@@ -1,3 +1,4 @@
 import { FileItem, useFileUpload } from "./core/use-file-upload.js";
+import { useCommentComposer } from "./comments/use-comment-composer.js";
 import "@tanstack/react-start/client-only";
-export { type FileItem, useFileUpload };
+export { type FileItem, useCommentComposer, useFileUpload };

package/dist/client.js

@@ -1,4 +1,5 @@
 import { useFileUpload } from "./core/use-file-upload.js";
+import { useCommentComposer } from "./comments/use-comment-composer.js";
 import "@tanstack/react-start/client-only";
 
-export { useFileUpload };
+export { useCommentComposer, useFileUpload };

package/dist/comments/comments.d.ts

@@ -0,0 +1,137 @@
+import { CommentsAction } from "../action.js";
+
+//#region src/comments/comments.d.ts
+/** A person picked in the composer, and where their `@name` sits in the text. */
+type CommentMention = {
+  name: string;
+  email: string;
+  start: number;
+  end: number;
+};
+type CommentView = {
+  id: string;
+  /** The body as safe HTML. Render it with `dangerouslySetInnerHTML`, never as text. */
+  bodyHtml: string;
+  attachments: Array<{
+    url: string;
+    filename: string;
+  }>;
+  author: {
+    name: string;
+    avatar: string | null;
+    isDeactivated: boolean;
+  };
+  /** ISO 8601. */
+  createdAt: string;
+  canDelete: boolean;
+  reactions: Array<{
+    emoji: string;
+    label: string;
+    count: number;
+    isSelected: boolean;
+  }>;
+};
+type CommentThread = {
+  canPost: boolean;
+  allowMentions: boolean;
+  quickReactions: ReadonlyArray<{
+    emoji: string;
+    label: string;
+  }>;
+  total: number;
+  /** Pass it back as `offset` for the next page. `null` on the last page. */
+  nextOffset: number | null;
+  items: Array<CommentView>;
+};
+/**
+ * The thread on one record, newest first, or `null` when this visitor cannot see comments on it.
+ * Render nothing for `null`.
+ *
+ * @example
+ * const thread = await comments.list(orderComments, { recordId: order.id })
+ */
+declare function listComments(action: CommentsAction, options: {
+  recordId: string;
+  offset?: number | null;
+  limit?: number;
+}): Promise<CommentThread | null>;
+/**
+ * Posts a comment. `body` is the text the visitor typed. `mentions` are the people they picked,
+ * each with the range of its `@name` in `body`. A range that no longer reads as `@name` is posted as
+ * plain text.
+ *
+ * @example
+ * await comments.create(orderComments, { recordId, body: "Hey @Ann", mentions })
+ */
+declare function createComment(action: CommentsAction, options: {
+  recordId: string;
+  body: string;
+  mentions: ReadonlyArray<CommentMention>;
+}): Promise<void>;
+/**
+ * Deletes a comment. Offer it only where the comment's `canDelete` is true.
+ *
+ * @example
+ * await comments.delete(orderComments, { recordId, commentId })
+ */
+declare function deleteComment(action: CommentsAction, options: {
+  recordId: string;
+  commentId: string;
+}): Promise<void>;
+/**
+ * Adds the visitor's reaction when `selected` is true, and removes it when false. Pass the
+ * reaction's current `isSelected` negated.
+ *
+ * @example
+ * await comments.react(orderComments, { recordId, commentId, emoji: "👍", selected: true })
+ */
+declare function reactToComment(action: CommentsAction, options: {
+  recordId: string;
+  commentId: string;
+  emoji: string;
+  selected: boolean;
+}): Promise<void>;
+/**
+ * Whether the visitor gets an email when someone comments on this record.
+ *
+ * @example
+ * const subscribed = await comments.subscription(orderComments, { recordId })
+ */
+declare function readSubscription(action: CommentsAction, options: {
+  recordId: string;
+}): Promise<boolean>;
+/**
+ * Turns the visitor's emails about this record's comments on or off.
+ *
+ * @example
+ * await comments.setSubscription(orderComments, { recordId, subscribed: false })
+ */
+declare function setSubscription(action: CommentsAction, options: {
+  recordId: string;
+  subscribed: boolean;
+}): Promise<void>;
+/**
+ * The people the visitor may mention whose name or email matches `query`. Only call it when the
+ * thread's `allowMentions` is true.
+ *
+ * @example
+ * const people = await comments.searchMentions(orderComments, { query: "an" })
+ */
+declare function searchMentions(action: CommentsAction, options: {
+  query: string;
+}): Promise<Array<{
+  name: string;
+  email: string;
+  avatar: string | null;
+}>>;
+declare const comments: {
+  list: typeof listComments;
+  create: typeof createComment;
+  delete: typeof deleteComment;
+  react: typeof reactToComment;
+  subscription: typeof readSubscription;
+  setSubscription: typeof setSubscription;
+  searchMentions: typeof searchMentions;
+};
+//#endregion
+export { CommentMention, CommentThread, CommentView, comments };

package/dist/comments/comments.js

@@ -0,0 +1,329 @@
+import { assert } from "../assertions.js";
+import { fetch } from "../fetch.js";
+import { sessionConfig } from "../auth/config.js";
+import { readSessionToken } from "../auth/session.js";
+import { platformApiUrl } from "../auth/platform.js";
+import { describeFailure } from "../datasource/record.js";
+import { z } from "zod";
+import { Marked } from "marked";
+import { FilterXSS } from "xss";
+
+//#region src/comments/comments.ts
+/**
+* The emoji a comment can be reacted with. The app has no other set: an emoji outside it has no
+* label to store, and native blocks would show it without a name.
+*/
+const QUICK_REACTIONS = [
+	{
+		emoji: "👍",
+		label: "Thumbs Up"
+	},
+	{
+		emoji: "🙌",
+		label: "Raised Hands"
+	},
+	{
+		emoji: "✅",
+		label: "Check Mark"
+	},
+	{
+		emoji: "🔥",
+		label: "Fire"
+	},
+	{
+		emoji: "👀",
+		label: "Eyes"
+	}
+];
+const threadSchema = z.object({
+	items: z.array(z.object({
+		id: z.string(),
+		comment: z.string(),
+		attachments: z.array(z.object({
+			url: z.string(),
+			filename: z.string()
+		})),
+		author: z.object({
+			name: z.string(),
+			avatar: z.string().nullable(),
+			deactivated: z.boolean()
+		}),
+		createdAt: z.number(),
+		canDelete: z.boolean(),
+		reactions: z.array(z.object({
+			emoji: z.string(),
+			label: z.string(),
+			count: z.number(),
+			selected: z.boolean()
+		}))
+	})),
+	total: z.number(),
+	offset: z.number(),
+	canPost: z.boolean(),
+	allowMentions: z.boolean()
+});
+const subscriptionSchema = z.object({ subscribed: z.boolean() });
+const mentionCandidatesSchema = z.array(z.object({
+	name: z.string(),
+	email: z.string(),
+	avatar: z.string().nullable()
+}));
+async function request(action, path, init) {
+	const token = readSessionToken();
+	const headers = {};
+	if (token !== null) headers.Authorization = `Bearer ${token}`;
+	if (init.body !== void 0) headers["Content-Type"] = "application/json";
+	return fetch(`${await platformApiUrl()}/v1/vibe/applications/${sessionConfig().applicationId}/actions/${encodeURIComponent(action.id)}/comments${path}`, {
+		method: init.method,
+		headers,
+		body: init.body === void 0 ? void 0 : JSON.stringify(init.body)
+	});
+}
+async function failure(action, what, res) {
+	return /* @__PURE__ */ new Error(`comments ${what} failed for "${action.id}": ${await describeFailure(res)}`);
+}
+function recordPath(recordId) {
+	assert(recordId, "a record id must not be empty");
+	return `/records/${encodeURIComponent(recordId)}`;
+}
+/**
+* The thread on one record, newest first, or `null` when this visitor cannot see comments on it.
+* Render nothing for `null`.
+*
+* @example
+* const thread = await comments.list(orderComments, { recordId: order.id })
+*/
+async function listComments(action, options) {
+	const query = new URLSearchParams();
+	if (options.offset !== void 0 && options.offset !== null) query.set("offset", String(options.offset));
+	if (options.limit !== void 0) query.set("limit", String(options.limit));
+	const search = query.size > 0 ? `?${query}` : "";
+	const res = await request(action, `${recordPath(options.recordId)}${search}`, { method: "GET" });
+	if (res.status === 403) return null;
+	if (!res.ok) throw await failure(action, "list", res);
+	const payload = threadSchema.parse(await res.json());
+	const next = payload.offset + payload.items.length;
+	return {
+		canPost: payload.canPost,
+		allowMentions: payload.allowMentions,
+		quickReactions: QUICK_REACTIONS,
+		total: payload.total,
+		nextOffset: next < payload.total ? next : null,
+		items: payload.items.map((item) => ({
+			id: item.id,
+			bodyHtml: renderCommentBody(item.comment),
+			attachments: item.attachments,
+			author: {
+				name: item.author.name,
+				avatar: item.author.avatar,
+				isDeactivated: item.author.deactivated
+			},
+			createdAt: new Date(item.createdAt).toISOString(),
+			canDelete: item.canDelete,
+			reactions: item.reactions.map(({ selected,...reaction }) => ({
+				...reaction,
+				isSelected: selected
+			}))
+		}))
+	};
+}
+/**
+* Posts a comment. `body` is the text the visitor typed. `mentions` are the people they picked,
+* each with the range of its `@name` in `body`. A range that no longer reads as `@name` is posted as
+* plain text.
+*
+* @example
+* await comments.create(orderComments, { recordId, body: "Hey @Ann", mentions })
+*/
+async function createComment(action, options) {
+	assert(options.body.trim(), "a comment must not be empty");
+	const res = await request(action, recordPath(options.recordId), {
+		method: "POST",
+		body: { comment: encodeCommentBody(options.body, options.mentions) }
+	});
+	if (!res.ok) throw await failure(action, "create", res);
+}
+/**
+* Deletes a comment. Offer it only where the comment's `canDelete` is true.
+*
+* @example
+* await comments.delete(orderComments, { recordId, commentId })
+*/
+async function deleteComment(action, options) {
+	const res = await request(action, `${recordPath(options.recordId)}/${encodeURIComponent(options.commentId)}`, { method: "DELETE" });
+	if (!res.ok) throw await failure(action, "delete", res);
+}
+/**
+* Adds the visitor's reaction when `selected` is true, and removes it when false. Pass the
+* reaction's current `isSelected` negated.
+*
+* @example
+* await comments.react(orderComments, { recordId, commentId, emoji: "👍", selected: true })
+*/
+async function reactToComment(action, options) {
+	const reaction = QUICK_REACTIONS.find(({ emoji }) => emoji === options.emoji);
+	assert(reaction, `"${options.emoji}" is not one of the quick reactions`);
+	const path = `${recordPath(options.recordId)}/${encodeURIComponent(options.commentId)}/react`;
+	const res = options.selected ? await request(action, path, {
+		method: "PUT",
+		body: reaction
+	}) : await request(action, `${path}?${new URLSearchParams({ emoji: reaction.emoji })}`, { method: "DELETE" });
+	if (!res.ok) throw await failure(action, "react", res);
+}
+/**
+* Whether the visitor gets an email when someone comments on this record.
+*
+* @example
+* const subscribed = await comments.subscription(orderComments, { recordId })
+*/
+async function readSubscription(action, options) {
+	const res = await request(action, `${recordPath(options.recordId)}/subscription`, { method: "GET" });
+	if (!res.ok) throw await failure(action, "subscription", res);
+	return subscriptionSchema.parse(await res.json()).subscribed;
+}
+/**
+* Turns the visitor's emails about this record's comments on or off.
+*
+* @example
+* await comments.setSubscription(orderComments, { recordId, subscribed: false })
+*/
+async function setSubscription(action, options) {
+	const res = await request(action, `${recordPath(options.recordId)}/subscription`, {
+		method: "PUT",
+		body: { subscribed: options.subscribed }
+	});
+	if (!res.ok) throw await failure(action, "set subscription", res);
+}
+/**
+* The people the visitor may mention whose name or email matches `query`. Only call it when the
+* thread's `allowMentions` is true.
+*
+* @example
+* const people = await comments.searchMentions(orderComments, { query: "an" })
+*/
+async function searchMentions(action, options) {
+	const res = await request(action, `/mentions?${new URLSearchParams({ query: options.query })}`, { method: "GET" });
+	if (!res.ok) throw await failure(action, "mention search", res);
+	return mentionCandidatesSchema.parse(await res.json());
+}
+const comments = {
+	list: listComments,
+	create: createComment,
+	delete: deleteComment,
+	react: reactToComment,
+	subscription: readSubscription,
+	setSubscription,
+	searchMentions
+};
+/**
+* Splices each mention into the body as JSON. A range that does not read as its own `@name` is
+* left as text, so a composer that fell out of step never puts an email on the wrong words.
+*/
+function encodeCommentBody(body, mentions) {
+	const ordered = mentions.filter(({ name, start, end }) => body.slice(start, end) === `@${name}`).toSorted((a, b) => a.start - b.start);
+	let encoded = "";
+	let cursor = 0;
+	for (const { name, email, start, end } of ordered) {
+		if (start < cursor) continue;
+		encoded += body.slice(cursor, start) + JSON.stringify({
+			name,
+			email
+		});
+		cursor = end;
+	}
+	return encoded + body.slice(cursor);
+}
+const MENTION = /^\{\s*(?:"name"\s*:\s*"(?:[^"\\]|\\.)*"\s*,\s*"email"\s*:\s*"(?:[^"\\]|\\.)*"|"email"\s*:\s*"(?:[^"\\]|\\.)*"\s*,\s*"name"\s*:\s*"(?:[^"\\]|\\.)*")\s*\}/;
+const mentionSchema = z.object({
+	name: z.string(),
+	email: z.string()
+});
+/** The mention's fields, or `undefined` when the match is not valid JSON, e.g. a stray `\q`. */
+function parseMention(raw) {
+	try {
+		return mentionSchema.parse(JSON.parse(raw));
+	} catch {
+		return;
+	}
+}
+const markdown = new Marked({
+	gfm: true,
+	breaks: true,
+	async: false,
+	extensions: [{
+		name: "mention",
+		level: "inline",
+		start: (src) => src.indexOf("{"),
+		tokenizer(src) {
+			const match = MENTION.exec(src);
+			if (match === null) return void 0;
+			const mention = parseMention(match[0]);
+			if (mention === void 0) return void 0;
+			return {
+				type: "mention",
+				raw: match[0],
+				...mention
+			};
+		},
+		renderer(token) {
+			const label = String(token.name || token.email);
+			return `<span data-type="mention" data-name="${escapeHtml(label)}">@${escapeHtml(label)}</span>`;
+		}
+	}]
+});
+const sanitizer = new FilterXSS({
+	whiteList: Object.fromEntries([
+		"p",
+		"br",
+		"strong",
+		"em",
+		"u",
+		"s",
+		"a",
+		"ul",
+		"ol",
+		"li",
+		"code",
+		"pre",
+		"blockquote",
+		"h1",
+		"h2",
+		"h3",
+		"span",
+		"del"
+	].map((tag) => [tag, tag === "a" ? ["href", "title"] : []])),
+	stripIgnoreTag: true,
+	stripIgnoreTagBody: ["script", "style"],
+	onTagAttr(tag, name, value) {
+		if (tag !== "a") return void 0;
+		if (name === "target" || name === "rel") return "";
+		if (name !== "href") return void 0;
+		const href = linkify(value);
+		if (!SAFE_HREF.test(href)) return "";
+		return `href="${escapeAttribute(href)}" target="_blank" rel="noopener noreferrer"`;
+	},
+	onIgnoreTagAttr(_tag, name, value) {
+		if (!name.startsWith("data-")) return void 0;
+		return `${name}="${escapeAttribute(value)}"`;
+	}
+});
+const SAFE_HREF = /^(?:https?:\/\/|mailto:|tel:|#|\/)/i;
+/** A bare domain like `example.com` becomes an https link, as native blocks do. */
+function linkify(href) {
+	const trimmed = href.trim();
+	if (/^(?:[a-z][a-z0-9+.-]*:|#|\/)/i.test(trimmed)) return trimmed;
+	return trimmed.includes(".") ? `https://${trimmed}` : "";
+}
+function escapeHtml(text) {
+	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function escapeAttribute(value) {
+	return value.replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function renderCommentBody(comment) {
+	const trimmed = comment.replace(/^(?:\s*<br\s*\/?>\s*)+/i, "").replace(/(?:\s*<br\s*\/?>\s*)+$/i, "");
+	return sanitizer.process(markdown.parse(trimmed, { async: false }));
+}
+
+//#endregion
+export { comments };

package/dist/comments/use-comment-composer.d.ts

@@ -0,0 +1,37 @@
+import { CommentMention } from "./comments.js";
+import { ChangeEvent, RefObject, SyntheticEvent } from "react";
+
+//#region src/comments/use-comment-composer.d.ts
+
+/**
+ * The state of a comment box: the text, the people mentioned in it, and the `@` fragment being
+ * typed. Spread `textareaProps` onto a `<textarea>`. Show a mention menu while `query` is not
+ * `null`, and call `pick` with the person chosen from it.
+ *
+ * Post `text` and `mentions` as they are, then call `reset` once the post succeeds.
+ *
+ * @example
+ * const composer = useCommentComposer()
+ * <textarea {...composer.textareaProps} />
+ * {composer.query !== null && <MentionMenu query={composer.query} onPick={composer.pick} />}
+ */
+declare function useCommentComposer(): {
+  text: string;
+  mentions: Array<CommentMention>;
+  /** What follows the `@` before the caret, or `null` when the caret is not in a mention. */
+  query: string | null;
+  textareaProps: {
+    ref: RefObject<HTMLTextAreaElement | null>;
+    value: string;
+    onChange: (event: ChangeEvent<HTMLTextAreaElement>) => void;
+    onSelect: (event: SyntheticEvent<HTMLTextAreaElement>) => void;
+  };
+  /** Replaces the `@` fragment with the person's `@name`, and puts the caret after it. */
+  pick: (person: {
+    name: string;
+    email: string;
+  }) => void;
+  reset: () => void;
+};
+//#endregion
+export { useCommentComposer };

package/dist/comments/use-comment-composer.js

@@ -0,0 +1,127 @@
+import { assert } from "../assertions.js";
+import { useLayoutEffect, useRef, useState } from "react";
+
+//#region src/comments/use-comment-composer.ts
+const EMPTY = {
+	text: "",
+	mentions: [],
+	caret: 0
+};
+/**
+* The state of a comment box: the text, the people mentioned in it, and the `@` fragment being
+* typed. Spread `textareaProps` onto a `<textarea>`. Show a mention menu while `query` is not
+* `null`, and call `pick` with the person chosen from it.
+*
+* Post `text` and `mentions` as they are, then call `reset` once the post succeeds.
+*
+* @example
+* const composer = useCommentComposer()
+* <textarea {...composer.textareaProps} />
+* {composer.query !== null && <MentionMenu query={composer.query} onPick={composer.pick} />}
+*/
+function useCommentComposer() {
+	const [state, setState] = useState(EMPTY);
+	const ref = useRef(null);
+	const pendingCaret = useRef(null);
+	useLayoutEffect(() => {
+		const caret = pendingCaret.current;
+		if (caret === null || ref.current === null) return;
+		pendingCaret.current = null;
+		ref.current.focus();
+		ref.current.setSelectionRange(caret, caret);
+	});
+	const fragment = findMentionQuery(state.text, state.caret, state.mentions);
+	return {
+		text: state.text,
+		mentions: state.mentions,
+		query: fragment?.query ?? null,
+		textareaProps: {
+			ref,
+			value: state.text,
+			onChange(event) {
+				const next = event.currentTarget.value;
+				const caret = event.currentTarget.selectionStart;
+				setState((previous) => ({
+					text: next,
+					mentions: remapMentions(previous.text, next, previous.mentions),
+					caret
+				}));
+			},
+			onSelect(event) {
+				const caret = event.currentTarget.selectionStart;
+				setState((previous) => previous.caret === caret ? previous : {
+					...previous,
+					caret
+				});
+			}
+		},
+		pick(person) {
+			assert(fragment, "pick needs an @ fragment under the caret");
+			const label = `@${person.name}`;
+			const text = `${state.text.slice(0, fragment.start)}${label} ${state.text.slice(state.caret)}`;
+			const added = {
+				...person,
+				start: fragment.start,
+				end: fragment.start + label.length
+			};
+			const caret = added.end + 1;
+			pendingCaret.current = caret;
+			setState({
+				text,
+				mentions: [...remapMentions(state.text, text, state.mentions), added],
+				caret
+			});
+		},
+		reset() {
+			setState(EMPTY);
+		}
+	};
+}
+/** A fragment longer than this is prose, not a name being typed. */
+const MENTION_QUERY_MAX_LENGTH = 32;
+/**
+* Moves mention ranges through an edit. A textarea reports only its new value, so the edit is the
+* span between the longest common prefix and suffix. Ranges after it shift. Ranges it reached into
+* are dropped, which is how deleting part of a name un-mentions that person.
+*/
+function remapMentions(previous, next, mentions) {
+	if (previous === next) return mentions;
+	let prefix = 0;
+	while (prefix < previous.length && prefix < next.length && previous[prefix] === next[prefix]) prefix += 1;
+	let suffix = 0;
+	while (suffix < previous.length - prefix && suffix < next.length - prefix && previous[previous.length - 1 - suffix] === next[next.length - 1 - suffix]) suffix += 1;
+	const editStart = prefix;
+	const editEnd = previous.length - suffix;
+	const delta = next.length - previous.length;
+	return mentions.flatMap((mention) => {
+		if (mention.end <= editStart) return [mention];
+		if (mention.start >= editEnd) return [{
+			...mention,
+			start: mention.start + delta,
+			end: mention.end + delta
+		}];
+		return [];
+	});
+}
+/**
+* The `@` fragment the caret sits in, or `null`. An `@` does not count when:
+* - it does not start a word, so an email address opens no menu;
+* - it belongs to a mention already made;
+* - the fragment ran past a newline or is long enough to be prose. Spaces are fine, names have them.
+*/
+function findMentionQuery(text, caret, mentions) {
+	const before = text.slice(0, caret);
+	const at = before.lastIndexOf("@");
+	if (at === -1) return null;
+	if (at > 0 && !/\s/.test(before.charAt(at - 1))) return null;
+	if (mentions.some((mention) => at >= mention.start && at < mention.end)) return null;
+	const query = before.slice(at + 1);
+	if (query.includes("\n") || query.length > MENTION_QUERY_MAX_LENGTH) return null;
+	return {
+		query,
+		start: at
+	};
+}
+
+//#endregion
+export { useCommentComposer };

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import { SoftrUserGroupId, SoftrUserGroups, User } from "./auth/user.js";
-import { ActionPermissions, SoftrDatasources, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
+import { ActionPermissions, SoftrDatasources, defineComments, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
 import { FileAttachment } from "./core/file-upload.js";
 import { FileItem, useFileUpload } from "./core/use-file-upload.js";
+import { CommentMention, CommentThread, CommentView } from "./comments/comments.js";
 import { SoftrContext } from "./auth/context.js";
 import { checkAccess, defineVisibility, isAuthorized } from "./visibility/visibility.js";
 import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./visibility/route.js";
@@ -10,4 +11,4 @@ import { softrMcpMiddleware } from "./mcp.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./visibility/audience.js";
-export { type ActionPermissions, Audience, DefaultErrorOverlay, type FileAttachment, type FileItem, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useUserTimezone };
+export { type ActionPermissions, Audience, type CommentMention, type CommentThread, type CommentView, DefaultErrorOverlay, type FileAttachment, type FileItem, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, assertRouteAccess, checkAccess, defineComments, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useUserTimezone };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { useFileUpload } from "./core/use-file-upload.js";
-import { defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
+import { defineComments, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
 import { checkAccess, defineVisibility, isAuthorized } from "./visibility/visibility.js";
 import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./visibility/route.js";
 import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser } from "./auth/isomorphic.js";
@@ -8,4 +8,4 @@ import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./visibility/audience.js";
 
-export { Audience, DefaultErrorOverlay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useUserTimezone };
+export { Audience, DefaultErrorOverlay, assertRouteAccess, checkAccess, defineComments, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useUserTimezone };

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.52";
+var version = "0.0.54-alpha.0";
 
 //#endregion
 export { version };

package/dist/server.d.ts

@@ -1,7 +1,8 @@
 import { upload } from "./core/file-upload.js";
+import { comments } from "./comments/comments.js";
 import { auth } from "./auth/server.js";
 import { ds } from "./datasource/datasource.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
 import "@tanstack/react-start/server-only";
-export { auth, ds, integration, upload, workflow };
+export { auth, comments, ds, integration, upload, workflow };

package/dist/server.js

@@ -3,6 +3,7 @@ import { ds } from "./datasource/datasource.js";
 import { auth } from "./auth/server.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
+import { comments } from "./comments/comments.js";
 import "@tanstack/react-start/server-only";
 
-export { auth, ds, integration, upload, workflow };
+export { auth, comments, ds, integration, upload, workflow };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.52",
+  "version": "0.0.54-alpha.0",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
@@ -17,6 +17,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "marked": "^18.0.14",
+    "xss": "^1.0.15",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/skills/softr-sdk/SKILL.md

@@ -29,9 +29,9 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 
 | Import | Runs | Holds |
 | --- | --- | --- |
-| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
-| `@softr/sdk/server` | Server only | `ds`, `auth`, `workflow`, `integration` |
-| `@softr/sdk/client` | Browser only | Nothing yet, reserved for browser-only utilities |
+| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineComments`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
+| `@softr/sdk/server` | Server only | `ds`, `auth`, `workflow`, `integration`, `comments` |
+| `@softr/sdk/client` | Browser only | `useCommentComposer` |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
 
 ## Sub-Skills
@@ -48,6 +48,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Sign a visitor in, out, or up | [auth/SKILL.md](./auth/SKILL.md) |
 | Call a connected third-party API (Slack, Stripe, Gmail, …) | [integrations/SKILL.md](./integrations/SKILL.md) |
 | Open the app to AI assistants over MCP | [mcp/SKILL.md](./mcp/SKILL.md) |
+| Add comments to a record | [comments/SKILL.md](./comments/SKILL.md) |
 
 ## Quick Decision Tree
 
@@ -82,6 +83,9 @@ Calling a connected third-party API (Slack, Stripe, Gmail, Google Calendar, …)
 Opening the app to an AI assistant over MCP?
   load softr-sdk/mcp
 
+Letting visitors comment on a record?
+  load softr-sdk/comments
+
 Writing a server function, loader, or middleware in general?
   not a Softr concern. Use the TanStack Start skills.
 ```

package/skills/softr-sdk/comments/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: comments
+description: >-
+  Comment threads on records: defineComments from @softr/sdk declares which
+  datasource has comments; comments.list, create, delete, react, subscription,
+  setSubscription and searchMentions from @softr/sdk/server read and write one
+  record's thread inside a server function; useCommentComposer from
+  @softr/sdk/client keeps a textarea's text and @mentions in step. Bodies come
+  back as sanitised bodyHtml. A null thread means render nothing.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.52
+---
+
+**Boundary.** `comments` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler. Importing it into a component fails the build. `useCommentComposer` lives on `@softr/sdk/client` and runs in components. `defineComments` comes from `@softr/sdk` and can be imported anywhere.
+
+# Comments on records
+
+Every record of a commented datasource has one thread. The SDK reads and writes it. The app owns everything you see: layout, copy, sort order, dates.
+
+## Setup
+
+```ts
+import { createServerFn } from '@tanstack/react-start'
+import { defineComments, type CommentMention } from '@softr/sdk'
+import { comments } from '@softr/sdk/server'
+import { useCommentComposer } from '@softr/sdk/client'
+```
+
+## Declare the comments action
+
+```ts
+export const orderComments = defineComments({
+  id: 'orderComments',
+  datasourceId: '8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77',
+})
+```
+
+- `id` is a name you choose, unique across the app. `datasourceId` is the table whose records get threads.
+- There is no `permissions`. Who may read, post and delete is set in Softr under Settings → Comments, the same settings native comment blocks use.
+- Declare it once per datasource. Two declarations on the same datasource are the **same** threads, so "internal notes" next to "customer comments" on one table is not possible.
+- Write the object inline. Passing it through a variable hides it from the build.
+
+## Read a thread
+
+```ts
+const getThread = createServerFn({ method: 'GET' })
+  .validator((data: { recordId: string; offset?: number | null }) => data)
+  .handler(({ data }) => comments.list(orderComments, { recordId: data.recordId, offset: data.offset }))
+```
+
+`comments.list` answers `null` when this visitor cannot see comments on the record: comments are off for the app, the table is not set up yet, or the visitor's group may not read them. Render nothing for `null`, not an error.
+
+Otherwise it answers:
+
+| Field | What it is |
+| --- | --- |
+| `items` | The comments, newest first. Each is a `CommentView` |
+| `canPost` | Whether this visitor may post. Hide the composer when false |
+| `allowMentions` | Whether `@` opens a mention menu. Do not call `searchMentions` when false |
+| `quickReactions` | The five `{ emoji, label }` a comment can be reacted with. There are no others |
+| `total`, `nextOffset` | Paging. Pass `nextOffset` back as `offset` for older comments. `null` on the last page |
+
+A `CommentView` is `{ id, bodyHtml, attachments, author: { name, avatar, isDeactivated }, createdAt, canDelete, reactions }`. `createdAt` is ISO 8601. Format it with `useUserTimezone`. Each reaction is `{ emoji, label, count, isSelected }`.
+
+`bodyHtml` is already sanitised. Render it with `dangerouslySetInnerHTML` and nothing else:
+
+```tsx
+<div className="comment-body" dangerouslySetInnerHTML={{ __html: comment.bodyHtml }} />
+```
+
+It holds `p`, `br`, `strong`, `em`, `u`, `s`, `del`, `a`, `ul`, `ol`, `li`, `code`, `pre`, `blockquote`, `h1`–`h3` and mention `span[data-type="mention"]`. Links open in a new tab. Style those tags under the body's class, because the reset strips list bullets, link colour and spacing.
+
+## Post a comment
+
+```ts
+const postComment = createServerFn({ method: 'POST' })
+  .validator((data: { recordId: string; body: string; mentions: Array<CommentMention> }) => data)
+  .handler(({ data }) => comments.create(orderComments, data))
+```
+
+Pass the composer's `text` as `body` and its `mentions` as they are. The SDK stores the mentions in the format native blocks read, and the people mentioned get an email. A mention whose `@name` was edited is posted as plain text. There is no editing a posted comment and no attachment upload.
+
+## The composer
+
+```tsx
+const composer = useCommentComposer()
+
+<textarea {...composer.textareaProps} placeholder="Write a comment" />
+{/* While composer.query is not null, list findPeople's answer for it. Picking a person calls composer.pick(person). */}
+<button
+  disabled={composer.text.trim() === ''}
+  onClick={async () => {
+    await postComment({ data: { recordId, body: composer.text, mentions: composer.mentions } })
+    composer.reset()
+  }}
+>
+  Post
+</button>
+```
+
+- Spread `textareaProps` onto the `<textarea>`. It carries the `ref`, `value`, `onChange` and `onSelect` the composer needs, so do not replace them.
+- `query` is what follows `@` before the caret, or `null`. It is `""` the moment `@` is typed.
+- `pick({ name, email })` writes `@name`, records the mention and puts the caret after it.
+- `reset()` empties the box. Call it after the post succeeds, never before.
+
+## Mentions
+
+```ts
+const findPeople = createServerFn({ method: 'GET' })
+  .validator((data: { query: string }) => data)
+  .handler(({ data }) => comments.searchMentions(orderComments, data))
+```
+
+It answers `[{ name, email, avatar }]`, the people this visitor may mention whose name or email matches. Who is mentionable is set in Settings → Comments, per user group.
+
+## Delete, react, subscribe
+
+```ts
+await comments.delete(orderComments, { recordId, commentId })
+await comments.react(orderComments, { recordId, commentId, emoji: '👍', selected: !reaction.isSelected })
+const subscribed = await comments.subscription(orderComments, { recordId })
+await comments.setSubscription(orderComments, { recordId, subscribed: !subscribed })
+```
+
+Each runs inside its own server function, like `list`.
+
+- Offer delete only where `canDelete` is true.
+- `react` adds the visitor's reaction when `selected` is true and removes it when false. `emoji` must be one of `quickReactions`.
+- A subscription is whether the visitor gets an email when someone comments on this record.
+
+Re-read the thread after each write. The writes answer nothing.
+
+## Failure modes
+
+**Keying the thread on the URL instead of the record.** Pass the fetched `record.id` as `recordId`, never a route param or a search param. A param can be a slug, stale, or a different record's id, and the thread then shows another record's comments.
+
+**Treating `null` as an error.** A visitor who may not read comments gets `null`. Render nothing. An error box for it shows every such visitor a broken page.
+
+**Rendering a body as text, or sanitising it again.** Use `bodyHtml` with `dangerouslySetInnerHTML`. As text it shows raw tags, and a second sanitiser strips the mention markup.
+
+**Inventing reactions.** Only the five in `quickReactions` can be stored. `react` throws for any other emoji.
+
+**Calling `comments.*` from a component.** It is server only. Wrap each call in a `createServerFn`.
+
+## References
+
+- [record-queries/SKILL.md](../record-queries/SKILL.md): fetching the record whose `id` keys the thread