@softr/sdk 0.0.63-alpha.0 → 0.0.64-alpha.0

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

@@ -1,134 +0,0 @@
-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/skills/softr-sdk/comments/SKILL.md

@@ -1,181 +0,0 @@
----
-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