@softr/sdk 0.0.54-alpha.0 → 0.0.54

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

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

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