@softr/sdk 0.0.56-alpha.0 → 0.0.56-alpha.2

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

@@ -1,182 +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.56-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
-
-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, 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 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 for this page, 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. The first page is the newest comments; each further page, fetched by passing `nextOffset` back as `offset`, goes further back in time. `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`. Each reaction is `{ emoji, label, count, isSelected }`.
-
-- `allowAttachments` (on the thread): whether the composer may attach files.
-- `attachments[].type` (per attachment): the file's content type, or `null` when the platform does not know it.
-- `notificationsEnabled` (on the thread): whether to show the notifications switch at all. Hide it when false, even for a visitor who may post.
-- `canEdit` (per comment): whether this visitor may edit it. Show Edit only then.
-- `edited` (per comment): whether it was changed since it was posted. Show "(edited)" beside its date.
-- `source` (per comment): `{ text, mentions }` to fill an edit box, or `null` when `canEdit` is false. It is the body as the visitor typed it, with each mention as its own `@name` and range, the same shape the composer works with.
-
-`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>
-      attachments?: Array<CommentAttachmentInput>
-    }) => 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.
-
-`attachments` are the files the visitor uploaded with the post, from `useFileUpload(orderComments).files.filter((f) => f.status === 'done')`. Send them only when the thread's `allowAttachments` is true.
-
-`useFileUpload` takes the comments declaration as it takes a mutation. No extra declaration.
-
-## 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.
-
-## Editing a comment
-
-Offer Edit only where the comment's `canEdit` is true.
-
-- Fill the edit box with `useCommentComposer({ initial: comment.source })`, mounted only while editing.
-- Seed the edit's `useFileUpload` with the comment's kept files: `useFileUpload(orderComments, { initialAttachments: comment.attachments.map((a) => ({ ...a, id: a.url })) })`. A comment's attachment has no `id` of its own, so the url stands in for one.
-- Pass `comment.attachments` (the files kept) plus any new uploads to `comments.update` as `attachments`.
-- Re-read the thread after the write. `update` answers nothing.
-
-## 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, 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 inside its own server function, like `list`.
-
-- Offer delete only where `canDelete` is true.
-- `update` saves an edit; see "Editing a comment" above for `attachments`.
-- `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. It needs a
-  signed-in visitor. Posting subscribes the author, and a mention subscribes the person mentioned.
-- Mails go out a few minutes after a comment, never to its own author, and only while notifications are
-  on in Settings → Comments.
-
-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