@softr/sdk 0.0.74 → 0.0.75-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/options.d.ts

@@ -1,7 +1,22 @@
-import { DatasourceAction, ReadShape } from "../action.js";
+import { ActionShape, DatasourceAction, ReadShape } from "../action.js";
 import "@tanstack/react-start/server-only";
 
 //#region src/core/options.d.ts
+/** One choice of a SELECT field, as the field holds it now. */
+type FieldChoice = {
+  id: string;
+  label: string;
+  color: string | null;
+};
+/**
+ * The choices a SELECT field holds right now, read from Softr on every call. A choice the
+ * builder adds or renames later shows up without a new build. The field must be one the
+ * action declares. Any query or mutation over the table works.
+ *
+ * @example
+ * const loadStatuses = createServerFn().handler(() => ds.choices(listProjects, 'status'))
+ */
+declare function listChoices<TShape extends ActionShape>(action: DatasourceAction<TShape>, field: keyof TShape["fields"] & string): Promise<Array<FieldChoice>>;
 /** One row a linked-record picker offers. */
 type RecordOption = {
   id: string;
@@ -33,4 +48,4 @@ declare function listOptions<TShape extends ReadShape>(query: DatasourceAction<T
   limit?: number;
 }): Promise<RecordOptions>;
 //#endregion
-export { RecordOption, RecordOptions, listOptions };
+export { FieldChoice, RecordOption, RecordOptions, listChoices, listOptions };

package/dist/core/options.js

@@ -1,9 +1,37 @@
+import { assert } from "../assertions.js";
+import { fetch } from "../fetch.js";
+import { readSessionToken } from "../auth/session.js";
 import { makeChain } from "../datasource/fields.js";
-import { listRecords } from "../datasource/record.js";
+import { describeFailure, dsUrl, listRecords, refererHeader, resolveTarget } from "../datasource/record.js";
 import "@tanstack/react-start/server-only";
 
 //#region src/core/options.ts
 /**
+* The choices a SELECT field holds right now, read from Softr on every call. A choice the
+* builder adds or renames later shows up without a new build. The field must be one the
+* action declares. Any query or mutation over the table works.
+*
+* @example
+* const loadStatuses = createServerFn().handler(() => ds.choices(listProjects, 'status'))
+*/
+async function listChoices(action, field) {
+	const { actionId, select } = resolveTarget(action, action.resource.operation);
+	const fieldId = select[field];
+	assert(fieldId, () => `action "${actionId}" declares no field "${field}"`);
+	const res = await fetch(`${dsUrl(actionId)}/metadata`, { headers: {
+		Authorization: `Bearer ${readSessionToken()}`,
+		...refererHeader()
+	} });
+	if (!res.ok) throw new Error(`datasource metadata failed for "${actionId}": ${await describeFailure(res)}`);
+	const metadataField = (await res.json()).fields.find(({ id }) => id === fieldId);
+	assert(metadataField?.type === "SELECT", () => `"${field}" on action "${actionId}" is not a SELECT field`);
+	return (metadataField.options?.choices ?? []).map(({ id, label, color }) => ({
+		id,
+		label,
+		color: color ?? null
+	}));
+}
+/**
 * The rows a linked field can point at, for a picker: each record of the query as its id and the text
 * of one field, searched on that field when a term is given, a page at a time.
 *
@@ -36,4 +64,4 @@ function labelOf(value) {
 }
 
 //#endregion
-export { listOptions };
+export { listChoices, listOptions };

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/datasource/datasource.d.ts

@@ -1,5 +1,5 @@
 import { createRecord, deleteRecord, getRecord, listRecords, updateRecord } from "./record.js";
-import { listOptions } from "../core/options.js";
+import { listChoices, listOptions } from "../core/options.js";
 import { chart, metric } from "./chart.js";
 import "@tanstack/react-start/server-only";
 
@@ -13,6 +13,7 @@ declare const ds: {
   metric: typeof metric;
   chart: typeof chart;
   options: typeof listOptions;
+  choices: typeof listChoices;
 };
 //#endregion
 export { ds };

package/dist/datasource/datasource.js

@@ -1,6 +1,6 @@
 import { createRecord, deleteRecord, getRecord, listRecords, updateRecord } from "./record.js";
 import { chart, metric } from "./chart.js";
-import { listOptions } from "../core/options.js";
+import { listChoices, listOptions } from "../core/options.js";
 import "@tanstack/react-start/server-only";
 
 //#region src/datasource/datasource.ts
@@ -12,7 +12,8 @@ const ds = {
 	delete: deleteRecord,
 	metric,
 	chart,
-	options: listOptions
+	options: listOptions,
+	choices: listChoices
 };
 
 //#endregion

package/dist/datasource/fields.d.ts

@@ -19,17 +19,21 @@ type NumberChain = EmptyChain & {
   lte(value: number): ConstructableFilter;
   between(start: number, end: number): ConstructableFilter;
 };
-type ArrayChain<TMember$1 extends string> = EmptyChain & {
-  is(values: Array<TMember$1>): ConstructableFilter;
-  isOneOf(values: Array<TMember$1>): ConstructableFilter;
-  isNoneOf(values: Array<TMember$1>): ConstructableFilter;
-  hasAllOf(values: Array<TMember$1>): ConstructableFilter;
+type ArrayChain = EmptyChain & {
+  is(values: Array<string>): ConstructableFilter;
+  isOneOf(values: Array<string>): ConstructableFilter;
+  isNoneOf(values: Array<string>): ConstructableFilter;
+  hasAllOf(values: Array<string>): ConstructableFilter;
 };
-type ChoiceChain<TId$1 extends string> = EmptyChain & {
-  is(value: TId$1): ConstructableFilter;
-  isNot(value: TId$1): ConstructableFilter;
-  isOneOf(values: Array<TId$1>): ConstructableFilter;
-  isNoneOf(values: Array<TId$1>): ConstructableFilter;
+/**
+ * Compares choice ids as plain strings. A select's choices change in Studio after the build,
+ * and an id read at runtime from ds.choices has to be a valid filter value.
+ */
+type ChoiceChain = EmptyChain & {
+  is(value: string): ConstructableFilter;
+  isNot(value: string): ConstructableFilter;
+  isOneOf(values: Array<string>): ConstructableFilter;
+  isNoneOf(values: Array<string>): ConstructableFilter;
 };
 /** What DSv2 filters generically: matched whole or scanned, never against a set. */
 type GenericChain = EmptyChain & {
@@ -73,32 +77,20 @@ type AnyChain = EmptyChain & {
   between(start: number | string, end: number | string): ConstructableFilter;
   isNotBetween(start: number | string, end: number | string): ConstructableFilter;
 };
-type IdOf<TValue> = TValue extends {
-  id: infer TId extends string;
-} ? TId : string;
-/**
- * What a choice-shaped field compares against: its own ids where codegen read the choice
- * list, and any string where it did not. A linked record is the open case, and it is the
- * only thing distinguishing one from a select at the type level.
- */
-type ChoiceIds<TValue> = string extends IdOf<TValue> ? string : IdOf<TValue>;
 type TextFieldType = 'SINGLE_LINE_TEXT' | 'LONG_TEXT' | 'URL' | 'EMAIL' | 'PHONE' | 'ADDRESS' | 'RECORD_ID' | 'LOCATION' | 'TIME' | 'BUTTON';
 type NumberFieldType = 'NUMBER' | 'PERCENT' | 'CURRENCY' | 'PROGRESS' | 'RATING' | 'DURATION' | 'COUNT' | 'AUTONUMBER';
 type DateFieldType = 'DATE' | 'DATETIME' | 'CREATED_AT' | 'UPDATED_AT';
 type ChoiceFieldType = 'SELECT' | 'LINKED_RECORD' | 'CREATED_BY' | 'UPDATED_BY';
 /** The types with no single value to compare: only whether the field holds one. */
 type EmptyFieldType = 'ATTACHMENT' | 'DATE_RANGE';
-type ElementOf<TValue> = TValue extends Array<infer TMember> ? TMember : TValue;
 /**
  * The operators one alias offers, chosen from the type codegen declared for the field rather
  * than from what it reads as: a `DATETIME` and a text field both read as `string`, and only
  * the declared type tells them apart.
  *
- * `TValue` is still needed for the literal choice ids, which live on the read type and
- * nowhere else. A field with no declared type lands on the permissive chain rather than on
- * none.
+ * A field with no declared type lands on the permissive chain rather than on none.
  */
-type ChainFor<TFieldType, TValue> = [TFieldType] extends [never] ? AnyChain : TFieldType extends `${infer TBase}[]` ? TBase extends EmptyFieldType ? EmptyChain : ArrayChain<ChoiceIds<ElementOf<TValue>>> : TFieldType extends TextFieldType ? TextChain<TValue & string> : TFieldType extends NumberFieldType ? NumberChain : TFieldType extends 'USER' ? GenericChain : TFieldType extends 'CHECKBOX' ? BooleanChain : TFieldType extends DateFieldType ? DateChain : TFieldType extends ChoiceFieldType ? ChoiceChain<ChoiceIds<TValue>> : TFieldType extends EmptyFieldType ? EmptyChain : AnyChain;
+type ChainFor<TFieldType, TValue> = [TFieldType] extends [never] ? AnyChain : TFieldType extends `${infer TBase}[]` ? TBase extends EmptyFieldType ? EmptyChain : ArrayChain : TFieldType extends TextFieldType ? TextChain<TValue & string> : TFieldType extends NumberFieldType ? NumberChain : TFieldType extends 'USER' ? GenericChain : TFieldType extends 'CHECKBOX' ? BooleanChain : TFieldType extends DateFieldType ? DateChain : TFieldType extends ChoiceFieldType ? ChoiceChain : TFieldType extends EmptyFieldType ? EmptyChain : AnyChain;
 type Combinators = {
   $and(...members: Array<AnyConstructable>): ConstructableFilterGroup;
   $or(...members: Array<AnyConstructable>): ConstructableFilterGroup;

package/dist/default-error-overlay.d.ts

@@ -1,4 +1,4 @@
-import * as react6 from "react";
+import * as react4 from "react";
 
 //#region src/default-error-overlay.d.ts
 type Props = {
@@ -8,6 +8,6 @@ type Props = {
 declare function DefaultErrorOverlay({
   error,
   reset
-}: Props): react6.JSX.Element;
+}: Props): react4.JSX.Element;
 //#endregion
 export { DefaultErrorOverlay };

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 { AuthSettings } from "./auth/platform.js";
@@ -17,4 +18,4 @@ import { useUserTimezone } from "./timezone.js";
 import { PwaInstall, PwaPlatform, SoftrPwaHead, usePwaInstall } from "./pwa.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./route/audience.js";
-export { type ActionPermissions, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FieldShape, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type Page, type PageSettings, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, type SoftrFieldRegistry, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type User, type WeekDay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };
+export { type ActionPermissions, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type CommentAttachmentInput, type CommentMention, type CommentThread, type CommentView, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FieldShape, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type Page, type PageSettings, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, type SoftrFieldRegistry, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type User, type WeekDay, assertRouteAccess, checkAccess, defineComments, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, 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 "./route/visibility.js";
 import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./route/route.js";
 import { definePage, pageHead } from "./route/page.js";
@@ -14,4 +14,4 @@ import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./route/audience.js";
 
-export { Audience, AuthSettingsProvider, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };
+export { Audience, AuthSettingsProvider, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineComments, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };

package/dist/package.js

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

package/dist/pwa.d.ts

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

package/dist/server.d.ts

@@ -1,8 +1,9 @@
 import { upload } from "./core/file-upload.js";
+import { comments } from "./comments/comments.js";
 import { auth } from "./auth/server.js";
-import { RecordOption, RecordOptions } from "./core/options.js";
+import { FieldChoice, RecordOption, RecordOptions } from "./core/options.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 { type RecordOption, type RecordOptions, auth, ds, integration, upload, workflow };
+export { type FieldChoice, type RecordOption, type RecordOptions, 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.74",
+  "version": "0.0.75-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

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.74
+  library_version: 0.0.75
 ---
 
 # Softr SDK core
@@ -30,9 +30,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`, `formatValue`, `formatField`, `fieldShape`, `registerSoftrFields`, `useOverrides`, `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`, `formatValue`, `formatField`, `fieldShape`, `registerSoftrFields`, `useOverrides`, `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 | `useFileUpload`, `useCommentComposer` |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
 
 ## Sub-Skills
@@ -51,6 +51,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
 
@@ -91,6 +92,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

@@ -18,7 +18,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.74
+  library_version: 0.0.75
 ---
 
 **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.74
+  library_version: 0.0.75
 ---
 
 **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.