@softr/sdk 0.0.75 → 0.0.77

package/dist/codegen/datasource-types.js

@@ -161,7 +161,7 @@ function writeValue(shape, context) {
 		case "UPDATED_AT": return "IsoDateTime";
 		case "TIME": return "IsoTime";
 		case "DATE_RANGE": return "{ from: IsoDate; to: IsoDate }";
-		case "SELECT": return selectInput(shape.options);
+		case "SELECT": return "SelectChoiceInput";
 		case "ATTACHMENT": return "AttachmentInput";
 		case "LINKED_RECORD": return "LinkedRecordInput";
 		case "USER": return "WorkspaceUser";
@@ -208,19 +208,6 @@ function selectValue(options) {
 	if (choices === null) return "SelectChoice";
 	return union(choices.map(({ id, label }) => `{ id: ${quote(id)}; label: ${quote(label)} }`));
 }
-/**
-* A write carries the id alone. The API resolves it against the choice list and writes that
-* choice's own label, so a label sent alongside is dropped.
-*
-* The API also takes `{ label }` with no id, and a label matching nothing creates a choice.
-* The union omits that: it would make every misspelling type-check, and the cost of one is a
-* new choice in the field rather than an error.
-*/
-function selectInput(options) {
-	const choices = choiceEntries(options);
-	if (choices === null) return "SelectChoiceInput";
-	return union(choices.map(({ id }) => `{ id: ${quote(id)} }`));
-}
 function datePrecision(options) {
 	const precision = option(options, "precision");
 	return typeof precision === "string" ? precision : null;

package/dist/core/options.d.ts

@@ -1,7 +1,22 @@
-import { DatasourceAction, ReadShape } from "../action.js";
+import { ActionShape, DatasourceAction, ReadShape } from "../action.js";
 import "@tanstack/react-start/server-only";
 
 //#region src/core/options.d.ts
+/** One choice of a SELECT field, as the field holds it now. */
+type FieldChoice = {
+  id: string;
+  label: string;
+  color: string | null;
+};
+/**
+ * The choices a SELECT field holds right now, read from Softr on every call. A choice the
+ * builder adds or renames later shows up without a new build. The field must be one the
+ * action declares. Any query or mutation over the table works.
+ *
+ * @example
+ * const loadCategories = createServerFn().handler(() => ds.choices(products, 'category'))
+ */
+declare function listChoices<TShape extends ActionShape>(action: DatasourceAction<TShape>, field: keyof TShape["fields"] & string): Promise<Array<FieldChoice>>;
 /** One row a linked-record picker offers. */
 type RecordOption = {
   id: string;
@@ -33,4 +48,4 @@ declare function listOptions<TShape extends ReadShape>(query: DatasourceAction<T
   limit?: number;
 }): Promise<RecordOptions>;
 //#endregion
-export { RecordOption, RecordOptions, listOptions };
+export { FieldChoice, RecordOption, RecordOptions, listChoices, listOptions };

package/dist/core/options.js

@@ -1,9 +1,37 @@
+import { assert } from "../assertions.js";
+import { fetch } from "../fetch.js";
+import { readSessionToken } from "../auth/session.js";
 import { makeChain } from "../datasource/fields.js";
-import { listRecords } from "../datasource/record.js";
+import { describeFailure, dsUrl, listRecords, refererHeader, resolveTarget } from "../datasource/record.js";
 import "@tanstack/react-start/server-only";
 
 //#region src/core/options.ts
 /**
+* The choices a SELECT field holds right now, read from Softr on every call. A choice the
+* builder adds or renames later shows up without a new build. The field must be one the
+* action declares. Any query or mutation over the table works.
+*
+* @example
+* const loadCategories = createServerFn().handler(() => ds.choices(products, 'category'))
+*/
+async function listChoices(action, field) {
+	const { actionId, select } = resolveTarget(action, action.resource.operation);
+	const fieldId = select[field];
+	assert(fieldId, () => `action "${actionId}" declares no field "${field}"`);
+	const res = await fetch(`${dsUrl(actionId)}/metadata`, { headers: {
+		Authorization: `Bearer ${readSessionToken()}`,
+		...refererHeader()
+	} });
+	if (!res.ok) throw new Error(`datasource metadata failed for "${actionId}": ${await describeFailure(res)}`);
+	const metadataField = (await res.json()).fields.find(({ id }) => id === fieldId);
+	assert(metadataField?.type === "SELECT", () => `"${field}" on action "${actionId}" is not a SELECT field`);
+	return (metadataField.options?.choices ?? []).map(({ id, label, color }) => ({
+		id,
+		label,
+		color: color ?? null
+	}));
+}
+/**
 * The rows a linked field can point at, for a picker: each record of the query as its id and the text
 * of one field, searched on that field when a term is given, a page at a time.
 *
@@ -36,4 +64,4 @@ function labelOf(value) {
 }
 
 //#endregion
-export { listOptions };
+export { listChoices, listOptions };

package/dist/datasource/datasource.d.ts

@@ -1,5 +1,5 @@
 import { createRecord, deleteRecord, getRecord, listRecords, updateRecord } from "./record.js";
-import { listOptions } from "../core/options.js";
+import { listChoices, listOptions } from "../core/options.js";
 import { chart, metric } from "./chart.js";
 import "@tanstack/react-start/server-only";
 
@@ -13,6 +13,7 @@ declare const ds: {
   metric: typeof metric;
   chart: typeof chart;
   options: typeof listOptions;
+  choices: typeof listChoices;
 };
 //#endregion
 export { ds };

package/dist/datasource/datasource.js

@@ -1,6 +1,6 @@
 import { createRecord, deleteRecord, getRecord, listRecords, updateRecord } from "./record.js";
 import { chart, metric } from "./chart.js";
-import { listOptions } from "../core/options.js";
+import { listChoices, listOptions } from "../core/options.js";
 import "@tanstack/react-start/server-only";
 
 //#region src/datasource/datasource.ts
@@ -12,7 +12,8 @@ const ds = {
 	delete: deleteRecord,
 	metric,
 	chart,
-	options: listOptions
+	options: listOptions,
+	choices: listChoices
 };
 
 //#endregion

package/dist/datasource/fields.d.ts

@@ -19,17 +19,21 @@ type NumberChain = EmptyChain & {
   lte(value: number): ConstructableFilter;
   between(start: number, end: number): ConstructableFilter;
 };
-type ArrayChain<TMember$1 extends string> = EmptyChain & {
-  is(values: Array<TMember$1>): ConstructableFilter;
-  isOneOf(values: Array<TMember$1>): ConstructableFilter;
-  isNoneOf(values: Array<TMember$1>): ConstructableFilter;
-  hasAllOf(values: Array<TMember$1>): ConstructableFilter;
+type ArrayChain = EmptyChain & {
+  is(values: Array<string>): ConstructableFilter;
+  isOneOf(values: Array<string>): ConstructableFilter;
+  isNoneOf(values: Array<string>): ConstructableFilter;
+  hasAllOf(values: Array<string>): ConstructableFilter;
 };
-type ChoiceChain<TId$1 extends string> = EmptyChain & {
-  is(value: TId$1): ConstructableFilter;
-  isNot(value: TId$1): ConstructableFilter;
-  isOneOf(values: Array<TId$1>): ConstructableFilter;
-  isNoneOf(values: Array<TId$1>): ConstructableFilter;
+/**
+ * Compares choice ids as plain strings. A select's choices change in Studio after the build,
+ * and an id read at runtime from ds.choices has to be a valid filter value.
+ */
+type ChoiceChain = EmptyChain & {
+  is(value: string): ConstructableFilter;
+  isNot(value: string): ConstructableFilter;
+  isOneOf(values: Array<string>): ConstructableFilter;
+  isNoneOf(values: Array<string>): ConstructableFilter;
 };
 /** What DSv2 filters generically: matched whole or scanned, never against a set. */
 type GenericChain = EmptyChain & {
@@ -73,32 +77,20 @@ type AnyChain = EmptyChain & {
   between(start: number | string, end: number | string): ConstructableFilter;
   isNotBetween(start: number | string, end: number | string): ConstructableFilter;
 };
-type IdOf<TValue> = TValue extends {
-  id: infer TId extends string;
-} ? TId : string;
-/**
- * What a choice-shaped field compares against: its own ids where codegen read the choice
- * list, and any string where it did not. A linked record is the open case, and it is the
- * only thing distinguishing one from a select at the type level.
- */
-type ChoiceIds<TValue> = string extends IdOf<TValue> ? string : IdOf<TValue>;
 type TextFieldType = 'SINGLE_LINE_TEXT' | 'LONG_TEXT' | 'URL' | 'EMAIL' | 'PHONE' | 'ADDRESS' | 'RECORD_ID' | 'LOCATION' | 'TIME' | 'BUTTON';
 type NumberFieldType = 'NUMBER' | 'PERCENT' | 'CURRENCY' | 'PROGRESS' | 'RATING' | 'DURATION' | 'COUNT' | 'AUTONUMBER';
 type DateFieldType = 'DATE' | 'DATETIME' | 'CREATED_AT' | 'UPDATED_AT';
 type ChoiceFieldType = 'SELECT' | 'LINKED_RECORD' | 'CREATED_BY' | 'UPDATED_BY';
 /** The types with no single value to compare: only whether the field holds one. */
 type EmptyFieldType = 'ATTACHMENT' | 'DATE_RANGE';
-type ElementOf<TValue> = TValue extends Array<infer TMember> ? TMember : TValue;
 /**
  * The operators one alias offers, chosen from the type codegen declared for the field rather
  * than from what it reads as: a `DATETIME` and a text field both read as `string`, and only
  * the declared type tells them apart.
  *
- * `TValue` is still needed for the literal choice ids, which live on the read type and
- * nowhere else. A field with no declared type lands on the permissive chain rather than on
- * none.
+ * A field with no declared type lands on the permissive chain rather than on none.
  */
-type ChainFor<TFieldType, TValue> = [TFieldType] extends [never] ? AnyChain : TFieldType extends `${infer TBase}[]` ? TBase extends EmptyFieldType ? EmptyChain : ArrayChain<ChoiceIds<ElementOf<TValue>>> : TFieldType extends TextFieldType ? TextChain<TValue & string> : TFieldType extends NumberFieldType ? NumberChain : TFieldType extends 'USER' ? GenericChain : TFieldType extends 'CHECKBOX' ? BooleanChain : TFieldType extends DateFieldType ? DateChain : TFieldType extends ChoiceFieldType ? ChoiceChain<ChoiceIds<TValue>> : TFieldType extends EmptyFieldType ? EmptyChain : AnyChain;
+type ChainFor<TFieldType, TValue> = [TFieldType] extends [never] ? AnyChain : TFieldType extends `${infer TBase}[]` ? TBase extends EmptyFieldType ? EmptyChain : ArrayChain : TFieldType extends TextFieldType ? TextChain<TValue & string> : TFieldType extends NumberFieldType ? NumberChain : TFieldType extends 'USER' ? GenericChain : TFieldType extends 'CHECKBOX' ? BooleanChain : TFieldType extends DateFieldType ? DateChain : TFieldType extends ChoiceFieldType ? ChoiceChain : TFieldType extends EmptyFieldType ? EmptyChain : AnyChain;
 type Combinators = {
   $and(...members: Array<AnyConstructable>): ConstructableFilterGroup;
   $or(...members: Array<AnyConstructable>): ConstructableFilterGroup;

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.75";
+var version = "0.0.77";
 
 //#endregion
 export { version };

package/dist/server.d.ts

@@ -1,9 +1,9 @@
 import { upload } from "./core/file-upload.js";
 import { comments } from "./comments/comments.js";
 import { auth } from "./auth/server.js";
-import { RecordOption, RecordOptions } from "./core/options.js";
+import { FieldChoice, RecordOption, RecordOptions } from "./core/options.js";
 import { ds } from "./datasource/datasource.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
 import "@tanstack/react-start/server-only";
-export { type RecordOption, type RecordOptions, auth, comments, ds, integration, upload, workflow };
+export { type FieldChoice, type RecordOption, type RecordOptions, auth, comments, ds, integration, upload, workflow };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.75",
+  "version": "0.0.77",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },

package/skills/softr-sdk/SKILL.md

@@ -1,18 +1,14 @@
 ---
 name: softr-sdk
 description: >-
-  Entry point for @softr/sdk, the layer a Softr app uses to reach Softr: the
-  four entrypoints (@softr/sdk, /server, /client, /vite) and the client-server
-  boundary between them, softrAuthMiddleware, getSoftrContext,
-  initialSoftrContext, SoftrContext, and which sub-skill to load for route
-  visibility, the current user, reading records, charts and metrics, writing
-  records, auth, or showing dates and numbers. Load this when unsure which
-  sub-skill applies, or when touching the wiring; each sub-skill stands alone
-  for its own task.
+  Entry point for @softr/sdk: its four entrypoints (@softr/sdk, /server,
+  /client, /vite) and their client-server boundary, softrAuthMiddleware and the
+  Softr context, and which sub-skill covers each task. Load it when unsure which
+  sub-skill applies, or when touching the wiring.
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.75
+  library_version: 0.0.77
 ---
 
 # Softr SDK core

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

@@ -1,24 +1,15 @@
 ---
 name: auth
 description: >-
-  Sign a Softr visitor in, out or up from a server function: auth.signIn,
-  signInWithCode, signInWithGoogle, signInWithMagicLink, signUp, confirmSignUp
-  and signOut from @softr/sdk/server, the authenticator-app calls that finish a
-  sign-in (verifyAuthenticator, startAuthenticatorSetup,
-  confirmAuthenticatorSetup, skipAuthenticatorSetup) and the ones that change an
-  authenticator from a settings page (sendAuthenticatorResetCode,
-  resetAuthenticator, removeAuthenticator), updateProfile for the visitor's own
-  name and photo, the emailed password links (requestPasswordReset,
-  checkPasswordLink, setPasswordWithLink), and getAuthSettings,
-  AuthSettingsProvider and useAuthSettings for which sign-in and sign-up methods
-  the app has enabled. Covers the Result shape they answer with and its error
-  codes (invalidCredentials, emailTaken, notAuthenticated, notAnImage and the
-  rest), the two-step sign-up, why a successful sign-in does not always mean the
-  visitor is signed in, and toReturnPath for where to land after signing in.
+  Sign a visitor in, out or up from a server function with auth from
+  @softr/sdk/server: password, code, Google and magic link, sign-up and its
+  confirmation, the authenticator-app steps, password reset links,
+  updateProfile, and getAuthSettings and useAuthSettings for the methods the app
+  enables. Covers the Result shape, its error codes, and toReturnPath.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.75
+  library_version: 0.0.77
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.

package/skills/softr-sdk/charts-and-metrics/SKILL.md

@@ -1,18 +1,15 @@
 ---
 name: charts-and-metrics
 description: >-
-  Aggregate Softr datasource records inside a server function: ds.chart with
-  groupBy, metrics, where and orderBy for chart rows, ds.metric for a single
-  headline number, date bucket intervals, which aggregations each kind of field
-  offers, the two-group-column ceiling, and distinct values for filter controls.
-  Use when drawing a chart, a stat tile or any counted, summed or averaged
-  number, when filling a dropdown from a real column, or when a chart comes back
-  scrambled or with the wrong rows. Aggregation only: fetching individual
-  records is record-queries, and changing them is record-mutations.
+  Aggregate records in a server function: ds.chart with groupBy, metrics, where,
+  orderBy and date buckets for chart rows, ds.metric for one number, and
+  distinct values for filter controls. Use for a chart, a stat tile or any
+  counted, summed or averaged number, or when a chart comes back wrong. Single
+  records are record-queries.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.75
+  library_version: 0.0.77
 ---
 
 **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.

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

@@ -1,17 +1,14 @@
 ---
 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.
+  Comment threads on records: defineComments, the comments calls from
+  @softr/sdk/server to list, write, react to and mention in one record's thread,
+  and useCommentComposer and useFileUpload from @softr/sdk/client for the
+  composer. Bodies come back as sanitised bodyHtml.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.75
+  library_version: 0.0.77
 ---
 
 **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.

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

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

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

@@ -1,16 +1,13 @@
 ---
 name: file-uploads
 description: >-
-  Upload files from a form or edit view: useFileUpload(action) from @softr/sdk
-  does everything — XHR upload with real progress, per-upload cancel, and
-  isUploading to block form submission. No route registration needed; the SDK
-  ships its own server function. For server-side uploads or plain forms, use
-  upload(actionId, file) from @softr/sdk/server. For edit forms pass
-  initialAttachments to pre-load existing attachments.
+  Upload files from a form or edit view: useFileUpload from @softr/sdk, with
+  progress, cancel and isUploading to hold the submit, and initialAttachments
+  for an edit form; upload from @softr/sdk/server for a server-side upload.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.75
+  library_version: 0.0.77
 ---
 
 **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.

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

@@ -2,15 +2,13 @@
 name: formatting
 description: >-
   Show dates, times and numbers in the app's format without hydration
-  mismatches: FormattedDate in JSX, useFormatting with formatDate,
-  formatDateTime and formatNumber in code, FormattingScope and the timeZone
-  option for a zone or locale the user names, parts for a partial date, and why
-  toLocaleDateString, toLocaleString and Intl formatters with the runtime's
-  defaults must never run in render.
+  mismatches: FormattedDate, useFormatting with formatDate, formatDateTime and
+  formatNumber, FormattingScope and timeZone, and why toLocaleDateString and
+  Intl defaults must never run in render.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.75
+  library_version: 0.0.77
 ---
 
 # Dates, times and numbers

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

@@ -1,16 +1,13 @@
 ---
 name: integrations
 description: >-
-  Call a third-party service connected to the app as an integration:
-  defineIntegration from @softr/sdk declares the action with its integrationId,
-  the one HTTP method and endpoint url it allows, and permissions;
-  integration.createFetcher from @softr/sdk/server binds it and returns a
-  fetcher function you call with optional params, query, headers, and body.
-  Check res.ok before res.json().
+  Call a third-party service connected as an integration: defineIntegration from
+  @softr/sdk declares the one method and endpoint it allows, and
+  integration.createFetcher from @softr/sdk/server calls it.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.75
+  library_version: 0.0.77
 ---
 
 **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.75
+  library_version: 0.0.77
 ---
 
 **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.75
+  library_version: 0.0.77
 ---
 
 # Installing the app

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

@@ -1,17 +1,14 @@
 ---
 name: record-mutations
 description: >-
-  Create, update and delete records in a Softr datasource with defineMutation,
-  ds.create, ds.update and ds.delete: one declaration per operation, the data
-  payload keyed by your own field names, what each field type accepts on a
-  write, and the record each call returns. Use when submitting a form, saving an
-  edit or deleting a record, or when a write throws, writes the wrong field or
-  silently changes nothing. Writes only: fetching records is record-queries, and
-  aggregating them is charts-and-metrics.
+  Create, update and delete records with defineMutation, ds.create, ds.update
+  and ds.delete: the payload keyed by your own field names and what each field
+  type accepts. Use when submitting a form, saving an edit or deleting a record,
+  or when a write fails or changes nothing. Reads are record-queries.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.75
+  library_version: 0.0.77
 ---
 
 **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 +152,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

@@ -1,19 +1,15 @@
 ---
 name: record-queries
 description: >-
-  Fetch records from a Softr datasource with defineQuery, ds.list and ds.get:
-  the where and orderBy callbacks, field names of your own choosing, the
-  20-record default and 100-record cap, nextOffset pagination, and scoping a
-  read to the signed-in visitor. Use when putting datasource records on a page,
-  in a table, a list or a detail view, when filtering or sorting them, when
-  filling a filter or form dropdown with all options from a linked table, or
-  when a read comes back empty, unsorted or missing a field. Reads only:
-  creating, updating and deleting records is record-mutations, and aggregating
-  them into totals or chart rows is charts-and-metrics.
+  Fetch records with defineQuery, ds.list and ds.get: where and orderBy, field
+  names of your own choosing, pagination and its limits, and scoping a read to
+  the signed-in visitor. Use to put records on a page or fill a dropdown, or
+  when a read comes back empty, unsorted or missing a field. Writes are
+  record-mutations; totals and chart rows are charts-and-metrics.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.75
+  library_version: 0.0.77
 ---
 
 **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 +196,13 @@ 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
+// `products` declares `category`, a SELECT field
+const loadCategories = createServerFn().handler(() => ds.choices(products, 'category'))
+```
+
 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.75
+  library_version: 0.0.77
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.

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

@@ -1,19 +1,14 @@
 ---
 name: routes-and-visibility
 description: >-
-  Add a route file to a Softr app and declare who may see it: defineVisibility
-  with a userGroupTypes set naming LOGGED_IN_USERS and/or NON_LOGGED_IN_USERS,
-  customGroups, and the ways to apply a rule: guardRoute and assertRouteAccess
-  in a route, isAuthorized and checkAccess anywhere. Covers per-reason
-  overrides, the redirect and throw strategies, rendering an access error with
-  isAccessError, isUnauthenticatedError, isForbiddenError and
-  isAlreadyAuthenticatedError, guarding a layout, and the lint rule that
-  requires a declaration alongside the rules that reject a duplicate, computed
-  or root-level one.
+  Add a route file and declare who may see it: defineVisibility with
+  LOGGED_IN_USERS, NON_LOGGED_IN_USERS and customGroups, guardRoute and
+  assertRouteAccess in a route, isAuthorized and checkAccess anywhere, rendering
+  an access error, and the lint rule that requires the declaration.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.75
+  library_version: 0.0.77
 ---
 
 **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.75
+  library_version: 0.0.77
 ---
 
 **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.