@softr/sdk 0.0.63-alpha.0 → 0.0.63

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