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

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

@@ -0,0 +1,77 @@
+---
+name: pwa
+description: >-
+  Let visitors install the app on their home screen: SoftrPwaHead for the
+  manifest and icon links, usePwaInstall to decide whether to show an install
+  button and which platform's steps to show, the PwaInstall and PwaPlatform
+  types, and how to check that the app is installable. The manifest and icon
+  are already served; never write them.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.55
+---
+
+# Installing the app
+
+The builder turns installing on in Studio, under Settings → Mobile app, and sets the name, colour and icon there. The app already answers with its manifest and icon once they do. What the app adds is two things: the links that point the browser at them, and a button that tells visitors how to install.
+
+> **CRITICAL**: Never write a web app manifest, icon files, a service worker, or `manifest` / `apple-touch-icon` links of your own, in `public/` or in `head()`. The app already serves them from Studio's settings, and a file of your own shadows those settings.
+> **CRITICAL**: Render an install button only while `usePwaInstall()` returns `available: true`. Never show it unconditionally, never cache the answer, never replace the check with your own. Softr can switch installing off for an app, and this check is the only way that reaches the button.
+
+## Setup
+
+```ts
+import { SoftrPwaHead, usePwaInstall } from '@softr/sdk'
+import type { PwaInstall, PwaPlatform } from '@softr/sdk'
+```
+
+```ts
+type PwaPlatform = 'ios' | 'android' | 'desktop'
+
+type PwaInstall =
+  | { available: false }
+  | {
+      available: true
+      platform: PwaPlatform   // which steps install the app on this device
+      name: string            // what the home screen will show
+      iconUrl: string         // the icon the home screen will show
+    }
+```
+
+## Is the app installable?
+
+The builder switches installing on in Studio, and `usePwaInstall()` reads that switch at runtime. To check it before writing any code, ask the running app for `/_softr/pwa.json`: `200` means installable, `404` means installing is off or there is no icon yet. Do not build an install button against a `404`: installing has to be turned on first. A change in Studio can take up to two minutes to reach the app.
+
+## Core Patterns
+
+### The links: `<SoftrPwaHead />`
+
+Render it once, in `<head>` next to `<HeadContent />`, in `RootDocument` in `src/routes/__root.tsx`.
+
+```tsx
+function RootDocument({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <HeadContent />
+        <SoftrPwaHead />
+      </head>
+      <body>
+        {children}
+        <Scripts />
+      </body>
+    </html>
+  )
+}
+```
+
+### Whether to show a button: `usePwaInstall()`
+
+It fetches after mount, so the first render, the server render included, always says `available: false`. It stays unavailable when the app is not installable, when the request fails, and when the app already runs installed from the home screen. Inside the Studio preview it says available, so the builder can see the button; installing itself only works on the published app.
+
+There is no `install()` to call. No browser opens its install dialog for this app on request, so the button opens steps for `platform` instead: Share, then Add to Home Screen on iOS; the browser menu's Install app on Android and desktop. `name` and `iconUrl` tell the visitor what they are adding.
+
+## References
+
+- [SKILL.md](../SKILL.md): the entrypoints and which one each export lives on

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

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.56-alpha.0
+  library_version: 0.0.55
 ---
 
 **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.

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

@@ -13,10 +13,10 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.56-alpha.0
+  library_version: 0.0.55
 ---
 
-**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. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.
+**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.
 
 # Reading records
 

package/skills/softr-sdk/record-queries/references/field-types.md

@@ -56,7 +56,7 @@ Every scalar above is `| null` on the record unless the field allows multiple en
 <td>{record.fields.status}</td>
 ```
 
-**DURATION** is seconds, whatever format the field displays in.
+**DURATION** is milliseconds, whatever format the field displays in: `3600000` is one hour.
 
 **DATETIME at date precision** is generated as a `DATE` field and holds `'2026-03-14'`, not a timestamp.
 

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.56-alpha.0
+  library_version: 0.0.55
 ---
 
 **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.56-alpha.0
+  library_version: 0.0.55
 ---
 
 **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.56-alpha.0
+  library_version: 0.0.55
 ---
 
 **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.

package/dist/comments/comments.d.ts

@@ -1,168 +0,0 @@
-import { CommentsAction } from "../action.js";
-
-//#region src/comments/comments.d.ts
-/** A person picked in the composer, and where their `@name` sits in the text. */
-type CommentMention = {
-  name: string;
-  email: string;
-  start: number;
-  end: number;
-};
-type CommentAttachmentInput = {
-  url: string;
-  filename: string;
-  type?: string | null;
-};
-type CommentView = {
-  id: string;
-  /** The body as safe HTML. Render it with `dangerouslySetInnerHTML`, never as text. */
-  bodyHtml: string;
-  attachments: Array<{
-    url: string;
-    filename: string;
-    type: string | null;
-  }>;
-  author: {
-    name: string;
-    avatar: string | null;
-    isDeactivated: boolean;
-  };
-  /** ISO 8601. */
-  createdAt: string;
-  canDelete: boolean;
-  canEdit: boolean;
-  edited: boolean;
-  /** The body as the visitor typed it, to fill an edit box. `null` unless `canEdit`. */
-  source: {
-    text: string;
-    mentions: Array<CommentMention>;
-  } | null;
-  reactions: Array<{
-    emoji: string;
-    label: string;
-    count: number;
-    isSelected: boolean;
-  }>;
-};
-type CommentThread = {
-  canPost: boolean;
-  allowMentions: boolean;
-  allowAttachments: boolean;
-  notificationsEnabled: boolean;
-  quickReactions: ReadonlyArray<{
-    emoji: string;
-    label: string;
-  }>;
-  total: number;
-  /** Pass it back as `offset` for the next page. `null` on the last page. */
-  nextOffset: number | null;
-  items: Array<CommentView>;
-};
-/**
- * The thread on one record, or `null` when this visitor cannot see comments on it. Render nothing
- * for `null`.
- *
- * @example
- * const thread = await comments.list(orderComments, { recordId: order.id })
- */
-declare function listComments(action: CommentsAction, options: {
-  recordId: string;
-  offset?: number | null;
-  limit?: number;
-}): Promise<CommentThread | null>;
-/**
- * Posts a comment. `body` is the text the visitor typed. `mentions` are the people they picked,
- * each with the range of its `@name` in `body`. A range that no longer reads as `@name` is posted as
- * plain text. `attachments` are the files `useFileUpload` finished uploading.
- *
- * @example
- * await comments.create(orderComments, { recordId, body: "Hey @Ann", mentions, attachments })
- */
-declare function createComment(action: CommentsAction, options: {
-  recordId: string;
-  body: string;
-  mentions: ReadonlyArray<CommentMention>;
-  attachments?: ReadonlyArray<CommentAttachmentInput>;
-}): Promise<void>;
-/**
- * Saves an edit. Offer it only where the comment's `canEdit` is true, and fill the edit box from its
- * `source`. `attachments` is the full list after the edit: the files kept plus any new ones.
- *
- * @example
- * await comments.update(orderComments, { recordId, commentId, body, mentions, attachments })
- */
-declare function updateComment(action: CommentsAction, options: {
-  recordId: string;
-  commentId: string;
-  body: string;
-  mentions: ReadonlyArray<CommentMention>;
-  attachments: ReadonlyArray<CommentAttachmentInput>;
-}): Promise<void>;
-/**
- * Deletes a comment. Offer it only where the comment's `canDelete` is true.
- *
- * @example
- * await comments.delete(orderComments, { recordId, commentId })
- */
-declare function deleteComment(action: CommentsAction, options: {
-  recordId: string;
-  commentId: string;
-}): Promise<void>;
-/**
- * Adds the visitor's reaction when `selected` is true, and removes it when false. Pass the
- * reaction's current `isSelected` negated.
- *
- * @example
- * await comments.react(orderComments, { recordId, commentId, emoji: "👍", selected: true })
- */
-declare function reactToComment(action: CommentsAction, options: {
-  recordId: string;
-  commentId: string;
-  emoji: string;
-  selected: boolean;
-}): Promise<void>;
-/**
- * Whether the visitor gets an email when someone comments on this record.
- *
- * @example
- * const subscribed = await comments.subscription(orderComments, { recordId })
- */
-declare function readSubscription(action: CommentsAction, options: {
-  recordId: string;
-}): Promise<boolean>;
-/**
- * Turns the visitor's emails about this record's comments on or off.
- *
- * @example
- * await comments.setSubscription(orderComments, { recordId, subscribed: false })
- */
-declare function setSubscription(action: CommentsAction, options: {
-  recordId: string;
-  subscribed: boolean;
-}): Promise<void>;
-/**
- * The people the visitor may mention whose name or email matches `query`. Only call it when the
- * thread's `allowMentions` is true.
- *
- * @example
- * const people = await comments.searchMentions(orderComments, { query: "an" })
- */
-declare function searchMentions(action: CommentsAction, options: {
-  query: string;
-}): Promise<Array<{
-  name: string;
-  email: string;
-  avatar: string | null;
-}>>;
-declare const comments: {
-  list: typeof listComments;
-  create: typeof createComment;
-  update: typeof updateComment;
-  delete: typeof deleteComment;
-  react: typeof reactToComment;
-  subscription: typeof readSubscription;
-  setSubscription: typeof setSubscription;
-  searchMentions: typeof searchMentions;
-};
-//#endregion
-export { CommentAttachmentInput, CommentMention, CommentThread, CommentView, comments };