@softr/sdk 0.0.62 → 0.0.63-alpha.0

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

@@ -0,0 +1,46 @@
+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.
+ *
+ * To edit a comment, pass its source as initial, in a composer mounted only while editing.
+ * `initial` is read once, on mount.
+ *
+ * @example
+ * const composer = useCommentComposer()
+ * <textarea {...composer.textareaProps} />
+ * {composer.query !== null && <MentionMenu query={composer.query} onPick={composer.pick} />}
+ */
+declare function useCommentComposer(options?: {
+  /** Fills the box to edit a comment: pass its `source`. */
+  initial?: {
+    text: string;
+    mentions: ReadonlyArray<CommentMention>;
+  };
+}): {
+  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,134 @@
+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.
+*
+* To edit a comment, pass its source as initial, in a composer mounted only while editing.
+* `initial` is read once, on mount.
+*
+* @example
+* const composer = useCommentComposer()
+* <textarea {...composer.textareaProps} />
+* {composer.query !== null && <MentionMenu query={composer.query} onPick={composer.pick} />}
+*/
+function useCommentComposer(options) {
+	const [state, setState] = useState(() => options?.initial === void 0 ? EMPTY : {
+		text: options.initial.text,
+		mentions: [...options.initial.mentions],
+		caret: options.initial.text.length
+	});
+	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/core/file-upload.d.ts

@@ -1,4 +1,4 @@
-import { DatasourceAction } from "../action.js";
+import { CommentsAction, DatasourceAction } from "../action.js";
 
 //#region src/core/file-upload.d.ts
 
@@ -10,7 +10,12 @@ type FileAttachment = {
   url: string;
   filename: string;
   id: string;
+  type?: string | null;
 };
-declare function upload(action: DatasourceAction, file: File): Promise<FileAttachment>;
+/**
+ * A COMMENTS action uploads a comment attachment.
+ * The platform checks the comment settings.
+ */
+declare function upload(action: DatasourceAction | CommentsAction, file: File): Promise<FileAttachment>;
 //#endregion
 export { FileAttachment, upload };

package/dist/core/file-upload.js

@@ -5,6 +5,10 @@ import { platformApiUrl } from "../auth/platform.js";
 import { randomUUID } from "node:crypto";
 
 //#region src/core/file-upload.ts
+/**
+* A COMMENTS action uploads a comment attachment.
+* The platform checks the comment settings.
+*/
 async function upload(action, file) {
 	const { applicationId } = sessionConfig();
 	const baseUrl = await platformApiUrl();
@@ -23,7 +27,8 @@ async function upload(action, file) {
 	return {
 		url: resultJSON.url,
 		filename: resultJSON.filename || "Untitled file",
-		id: resultJSON.id || randomUUID()
+		id: resultJSON.id || randomUUID(),
+		type: resultJSON.type ?? null
 	};
 }
 

package/dist/core/use-file-upload.d.ts

@@ -1,4 +1,4 @@
-import { DatasourceAction } from "../action.js";
+import { CommentsAction, DatasourceAction } from "../action.js";
 import { FileAttachment } from "./file-upload.js";
 
 //#region src/core/use-file-upload.d.ts
@@ -16,7 +16,7 @@ type FileItem = {
   filename: string;
   error: Error;
 };
-declare function useFileUpload(action: DatasourceAction, options?: {
+declare function useFileUpload(action: DatasourceAction | CommentsAction, options?: {
   initialAttachments?: FileAttachment[];
 }): {
   files: FileItem[];

package/dist/formatting.d.ts

@@ -1,4 +1,4 @@
-import * as react0 from "react";
+import * as react1 from "react";
 import { ReactNode } from "react";
 import { z } from "zod";
 
@@ -94,7 +94,7 @@ declare function FormattingScope({
   /** A BCP 47 locale, such as `de-DE`. It drops the app's fixed date format inside the scope. */
   locale?: string;
   children?: ReactNode;
-}): react0.FunctionComponentElement<react0.ProviderProps<Scope>>;
+}): react1.FunctionComponentElement<react1.ProviderProps<Scope>>;
 /**
  * A date in the app's format, safe to render on the server. A timestamp whose
  * zone is not known yet renders `fallback` until the browser supplies it, so
@@ -115,6 +115,6 @@ declare function FormattedDate({
   time?: boolean;
   /** What renders while the visitor's zone is unknown. */
   fallback?: ReactNode;
-}): react0.FunctionComponentElement<react0.FragmentProps>;
+}): react1.FunctionComponentElement<react1.FragmentProps>;
 //#endregion
 export { DateOptions, DateParts, DateSeparator, DateValue, FixedDateFormat, FormattedDate, Formatting, FormattingScope, WeekDay, formatDate, formatDateTime, formatNumber, useFormatting };

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 { CommentAttachmentInput, CommentMention, CommentThread, CommentView } from "./comments/comments.js";
 import { DateOptions, DateParts, DateSeparator, DateValue, FixedDateFormat, FormattedDate, Formatting, FormattingScope, WeekDay, formatDate, formatDateTime, formatNumber, useFormatting } from "./formatting.js";
 import { SoftrContext } from "./auth/context.js";
 import { checkAccess, defineVisibility, isAuthorized } from "./visibility/visibility.js";
@@ -12,4 +13,4 @@ import { useUserTimezone } from "./timezone.js";
 import { PwaInstall, PwaPlatform, SoftrPwaHead, usePwaInstall } from "./pwa.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./visibility/audience.js";
-export { type ActionPermissions, Audience, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type User, type WeekDay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, formatDate, formatDateTime, formatNumber, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useFormatting, usePwaInstall, useUserTimezone };
+export { type ActionPermissions, Audience, type CommentAttachmentInput, type CommentMention, type CommentThread, type CommentView, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type User, type WeekDay, assertRouteAccess, checkAccess, defineComments, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, formatDate, formatDateTime, formatNumber, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useFormatting, usePwaInstall, 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 { FormattedDate, FormattingScope, formatDate, formatDateTime, formatNumber, useFormatting } from "./formatting.js";
@@ -10,4 +10,4 @@ import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./visibility/audience.js";
 
-export { Audience, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, formatDate, formatDateTime, formatNumber, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useFormatting, usePwaInstall, useUserTimezone };
+export { Audience, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineComments, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, formatDate, formatDateTime, formatNumber, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useFormatting, usePwaInstall, useUserTimezone };

package/dist/package.js

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

package/dist/pwa.d.ts

@@ -1,4 +1,4 @@
-import * as react3 from "react";
+import * as react0 from "react";
 import "@tanstack/react-start";
 
 //#region src/pwa.d.ts
@@ -23,7 +23,7 @@ import "@tanstack/react-start";
  *   )
  * }
  */
-declare function SoftrPwaHead(): react3.FunctionComponentElement<react3.FragmentProps>;
+declare function SoftrPwaHead(): react0.FunctionComponentElement<react0.FragmentProps>;
 type PwaPlatform = "ios" | "android" | "desktop";
 type PwaInstall = {
   available: false;

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.62",
+  "version": "0.0.63-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

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.61
+  library_version: 0.0.63-alpha.0
 ---
 
 # Softr SDK core
@@ -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`, `FormattedDate`, `FormattingScope`, `useFormatting`, `formatDate`, `formatDateTime`, `formatNumber`, `SoftrPwaHead`, `usePwaInstall`, `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`, `FormattedDate`, `FormattingScope`, `useFormatting`, `formatDate`, `formatDateTime`, `formatNumber`, `SoftrPwaHead`, `usePwaInstall`, `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
@@ -50,6 +50,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Open the app to AI assistants over MCP | [mcp/SKILL.md](./mcp/SKILL.md) |
 | Let visitors install the app on their home screen | [pwa/SKILL.md](./pwa/SKILL.md) |
 | Show a date, a time or a number | [formatting/SKILL.md](./formatting/SKILL.md) |
+| Add comments to a record | [comments/SKILL.md](./comments/SKILL.md) |
 
 ## Quick Decision Tree
 
@@ -90,6 +91,9 @@ Adding an install button, or making the app installable?
 Showing a date, a time or a number on a page?
   load softr-sdk/formatting
 
+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/auth/SKILL.md

@@ -16,7 +16,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.61
+  library_version: 0.0.63-alpha.0
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.

package/skills/softr-sdk/charts-and-metrics/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.61
+  library_version: 0.0.63-alpha.0
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.

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

@@ -0,0 +1,181 @@
+---
+name: comments
+description: >-
+  Comment threads on records: defineComments from @softr/sdk declares which
+  datasource has comments; comments.list, create, update, delete, react,
+  subscription, setSubscription and searchMentions from @softr/sdk/server read
+  and write one record's thread inside a server function; useCommentComposer
+  and useFileUpload from @softr/sdk/client keep a textarea's text, its
+  @mentions and its attachments 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.63-alpha.0
+---
+
+**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
+
+Each record of a commented datasource has one thread. The SDK reads and writes it. The app owns what you see: layout, copy, order, dates.
+
+## Setup
+
+```ts
+import { createServerFn } from '@tanstack/react-start'
+import { defineComments, type CommentMention, type CommentAttachmentInput } from '@softr/sdk'
+import { comments } from '@softr/sdk/server'
+import { useCommentComposer, useFileUpload } from '@softr/sdk/client'
+```
+
+## Declare the comments action
+
+```ts
+export const orderComments = defineComments({
+  id: 'orderComments',
+  datasourceId: '8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77',
+})
+```
+
+- `id` is your name for it, unique in the app. `datasourceId` is the table that gets threads.
+- No `permissions`. Who can read, post and delete is set in Settings → Comments, shared with native blocks.
+- A viewer sees a thread only if a `read` action (`defineQuery`) on the same table lets them read it. Without one, `list` returns `null` for them.
+- One declaration per datasource. Two on the same table are the **same** threads, so "internal notes" plus "customer comments" on one table isn't possible.
+- Write the object inline. 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` returns `null` when this visitor can't see comments on the record (comments are off, the table isn't set up, or their group can't read). Render nothing for `null`, not an error.
+
+Otherwise it returns:
+
+| Field | What it is |
+| --- | --- |
+| `items` | This page's comments, newest first. Each is a `CommentView` |
+| `canPost` | Whether the visitor can post. Hide the composer when false |
+| `allowMentions` | Whether `@` opens a mention menu. Don't call `searchMentions` when false |
+| `allowAttachments` | Whether the composer can attach files |
+| `notificationsEnabled` | Whether to show the notifications switch at all |
+| `quickReactions` | The five `{ emoji, label }` reactions. There are no others |
+| `total`, `nextOffset` | Paging. Pass `nextOffset` back as `offset` to get the next, older page. `null` on the last page |
+
+A `CommentView` is `{ id, bodyHtml, attachments, author: { name, avatar, isDeactivated }, createdAt, canDelete, canEdit, edited, source, reactions }`.
+
+- `createdAt` is ISO 8601. Format it with `useUserTimezone`.
+- `attachments` are `{ url, filename, type }`. `type` is `null` when unknown.
+- `edited` is true once the comment changed after posting.
+- `source` is `{ text, mentions }` for the edit box, or `null` when `canEdit` is false.
+- 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 mentions (`span[data-type="mention"]`). Links open in a new tab. Style these tags under the body's class: the reset strips bullets, link colour and spacing.
+
+## Post a comment
+
+```ts
+const postComment = createServerFn({ method: 'POST' })
+  .validator(
+    (data: {
+      recordId: string
+      body: string
+      mentions: Array<CommentMention>
+      attachments?: Array<CommentAttachmentInput>
+    }) => data,
+  )
+  .handler(({ data }) => comments.create(orderComments, data))
+```
+
+Pass the composer's `text` and `mentions` as they are. Mentioned people get an email. A mention whose `@name` was edited posts as plain text.
+
+`attachments` are the finished uploads: `useFileUpload(orderComments).files.filter((f) => f.status === 'done')`. `useFileUpload` takes the comments declaration like a mutation. Send files only when `allowAttachments` is true. A comment needs text or at least one file.
+
+## The composer
+
+```tsx
+const composer = useCommentComposer()
+const { files, isUploading, upload, remove } = useFileUpload(orderComments)
+const done = files.filter((f) => f.status === 'done')
+
+<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() === '' && done.length === 0) || isUploading}
+  onClick={async () => {
+    await postComment({ data: { recordId, body: composer.text, mentions: composer.mentions, attachments: done } })
+    composer.reset()
+    done.forEach((f) => remove(f.id))
+  }}
+>
+  Post
+</button>
+```
+
+- Spread `textareaProps` onto the `<textarea>` and don't override its handlers.
+- `query` is the text after `@` before the caret, or `null`. It's `""` right after `@` is typed.
+- `pick({ name, email })` writes `@name`, records the mention and moves the caret after it.
+- `reset()` empties the box. Call it only after the post succeeds.
+
+## Editing a comment
+
+Offer Edit only where `canEdit` is true. Mount the edit box only while editing.
+
+- Text: `useCommentComposer({ initial: comment.source })`.
+- Files: `useFileUpload(orderComments, { initialAttachments: comment.attachments.map((a) => ({ ...a, id: a.url })) })`. Attachments have no `id`, so the url stands in.
+- Save with `comments.update`, passing the full file list: the kept files plus new uploads. With `allowAttachments` false the server keeps the old files whatever you send.
+
+## Mentions
+
+```ts
+const findPeople = createServerFn({ method: 'GET' })
+  .validator((data: { query: string }) => data)
+  .handler(({ data }) => comments.searchMentions(orderComments, data))
+```
+
+It returns `[{ name, email, avatar }]`: people the visitor can mention whose name or email matches. Who's mentionable is set per user group in Settings → Comments.
+
+## Delete, update, react, subscribe
+
+```ts
+await comments.delete(orderComments, { recordId, commentId })
+await comments.update(orderComments, { recordId, commentId, body, mentions, attachments })
+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 in its own server function, like `list`. Writes return nothing, so re-read the thread after each one.
+
+- Offer delete only where `canDelete` is true.
+- `react` adds the reaction when `selected` is true and removes it when false. `emoji` must be one of `quickReactions`.
+- A subscription means the visitor gets an email about new comments on the record. It needs a signed-in visitor. Posting subscribes the author; a mention subscribes the person mentioned.
+- Mails go out a few minutes after a comment, never to its author, and only while notifications are on in Settings → Comments.
+
+## Failure modes
+
+**Keying the thread on the URL.** Pass the fetched `record.id`, never a route or search param. A param can be a slug or stale, and the thread shows another record's comments.
+
+**Treating `null` as an error.** Render nothing. An error box 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; a second sanitiser strips the mentions.
+
+**Inventing reactions.** Only `quickReactions` can be stored. `react` throws for anything else.
+
+**Sending only new files on edit.** `update` replaces the whole list, so kept files you leave out get deleted.
+
+**Calling `comments.*` from a component.** It's 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

package/skills/softr-sdk/current-user/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.61
+  library_version: 0.0.63-alpha.0
 ---
 
 # The current user

package/skills/softr-sdk/file-uploads/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.61
+  library_version: 0.0.63-alpha.0
 ---
 
 **Boundary.** `upload` lives on `@softr/sdk/server` and runs inside server functions. `useFileUpload` and `FileItem` live on `@softr/sdk` and run in components. `FileAttachment` comes from `@softr/sdk` and can be imported anywhere.
@@ -75,9 +75,10 @@ function ApplicationForm() {
 
 ```ts
 type FileAttachment = {
-  url: string      // clean URL, no internal query params
-  filename: string // original filename
-  id: string       // file id extracted from the upload response
+  url: string             // clean URL, no internal query params
+  filename: string        // original filename
+  id: string              // file id extracted from the upload response
+  type?: string | null    // content type from the upload response, or null when the platform doesn't know it
 }
 ```
 

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.61
+  library_version: 0.0.63-alpha.0
 ---
 
 # Dates, times and numbers

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.61
+  library_version: 0.0.63-alpha.0
 ---
 
 **Boundary.** `integration` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineIntegration` and every type come from `@softr/sdk` and can be imported anywhere.