@softr/sdk 0.0.74 → 0.0.75-alpha.0

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

@@ -0,0 +1,181 @@
+---
+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.75
+---
+
+**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. Show it with `<FormattedDate value={comment.createdAt} time />`, or `useFormatting` for a title; see the `formatting` guidance.
+- `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

package/skills/softr-sdk/current-user/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.74
+  library_version: 0.0.75
 ---
 
 # The current user

package/skills/softr-sdk/file-uploads/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.74
+  library_version: 0.0.75
 ---
 
 **Boundary.** `upload` lives on `@softr/sdk/server` and runs inside server functions. `useFileUpload` and `FileItem` live on `@softr/sdk` and run in components. `FileAttachment` comes from `@softr/sdk` and can be imported anywhere.
@@ -75,9 +75,10 @@ function ApplicationForm() {
 
 ```ts
 type FileAttachment = {
-  url: string      // clean URL, no internal query params
-  filename: string // original filename
-  id: string       // file id extracted from the upload response
+  url: string             // clean URL, no internal query params
+  filename: string        // original filename
+  id: string              // file id extracted from the upload response
+  type?: string | null    // content type from the upload response, or null when the platform doesn't know it
 }
 ```
 

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.74
+  library_version: 0.0.75
 ---
 
 # Dates, times and numbers

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.74
+  library_version: 0.0.75
 ---
 
 **Boundary.** `integration` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineIntegration` and every type come from `@softr/sdk` and can be imported anywhere.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.74
+  library_version: 0.0.75
 ---
 
 **Boundary.** `softrMcpMiddleware` lives on `@softr/sdk` and is registered once, in `src/start.ts`. The actions you hand it are the same `defineQuery` / `defineMutation` values the app's own pages use — declared wherever they already live, not duplicated for MCP.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.74
+  library_version: 0.0.75
 ---
 
 # Installing the app

package/skills/softr-sdk/record-mutations/SKILL.md

@@ -11,7 +11,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 — importing it into a component fails the build. `defineMutation` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -155,7 +155,7 @@ A form select for a `LINKED_RECORD` field needs its options from the linked tabl
 
 Each key of `data` accepts exactly what its field takes (see [record-queries](../record-queries/SKILL.md#typing)):
 
-- SELECT and LINKED_RECORD take `{ id }`. Not a bare string, and not the `{ id, label }` a read returns; the label is display data and a write does not accept it. A generated SELECT narrows the id to the field's own choices.
+- SELECT and LINKED_RECORD take `{ id }`. Not a bare string, and not the `{ id, label }` a read returns; the label is display data and a write does not accept it. For a form select that should follow the field's choices in Studio, read them with `ds.choices` (see [record-queries](../record-queries/SKILL.md)).
 - CHECKBOX takes a boolean. Dates take ISO strings, never `Date` instances.
 - ATTACHMENT takes `{ url }`, optionally with `filename`, `id` and `type`.
 - A multi-entry field takes an array of the value.

package/skills/softr-sdk/record-queries/SKILL.md

@@ -13,7 +13,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. The same holds for any helper that calls `ds`: declare it inside the handler. A function at module level that calls `ds` keeps the server-only import in the browser bundle, and every page stops loading until it moves. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -200,6 +200,12 @@ const loadProductStatuses = createServerFn()
 
 Skip this request when the options are predefined and fixed — hardcode them instead.
 
+A `SELECT` field's options are its choices, and the builder can add and rename them in Studio after the app is built. When a dropdown should follow those changes, read them with `ds.choices`. When the app means a fixed choice, such as a "Done" tab, use its id directly. A mistyped id is not caught at compile time, and a write with an id the field lacks adds it as a new choice. `ds.choices` takes any query or mutation that declares the field and answers `[{ id, label, color }]` as the field holds them now. Each `id` is what a `where` and a write take, for a filter dropdown and a form select alike:
+
+```ts
+const loadStatuses = createServerFn().handler(() => ds.choices(listProjects, 'status'))
+```
+
 A read the datasource turns down throws rather than coming back empty, and it throws a plain `Error` carrying the status, followed by the reason the datasource gives when it sends one. There is no typed predicate to narrow it with. Handle it where you would handle any other failed fetch: an `errorComponent` on the route, or a check in the handler.
 
 ## Typing

package/skills/softr-sdk/record-queries/references/filters-and-sorting.md

@@ -83,7 +83,7 @@ Every value is an ISO date string, either `'2026-01-31'` or a full timestamp. A
 | `.isOneOf(values)` / `.isNoneOf(values)` | Any of / none of |
 | `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
 
-Values are choice ids, never labels. A generated SELECT narrows the argument to the field's own choice ids, so a label or a typo is a type error. A LINKED_RECORD compares against the linked record's id.
+Values are choice ids, never labels. A SELECT takes any choice id as a string, so a filter dropdown can pass the ids `ds.choices` returns. A label still matches nothing. A LINKED_RECORD compares against the linked record's id.
 
 ### Multi-value fields
 

package/skills/softr-sdk/region-visibility/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.74
+  library_version: 0.0.75
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.

package/skills/softr-sdk/routes-and-visibility/SKILL.md

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.74
+  library_version: 0.0.75
 ---
 
 **Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.74
+  library_version: 0.0.75
 ---
 
 **Boundary.** `workflow` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineWorkflow` and every type come from `@softr/sdk` and can be imported anywhere.