softr-vibe-coding 1.10.0 → 1.10.2

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this skill are documented here. Versions follow [Semantic
 
 Entries from 1.3.1 onward are generated automatically from git commit subjects between version bumps (see `.github/workflows/publish.yml`). Entries before 1.3.1 were backfilled by hand from the existing commit history.
 
+## [1.10.2] - 2026-06-12
+- Document the autoNumber-formula blank-read gotcha — a formula that references an Airtable autoNumber field frequently reads back empty through Softr's data layer even though Airtable shows the value and a data re-sync doesn't fix it (sibling formulas without an autoNumber dependency read fine). Add to datasources/airtable.md Gotchas + the Formula row of the field table, with the JS rebuild-from-autoNumber fix and the plain-text-stamped-by-automation alternative; bump to 1.10.2
+
+## [1.10.1] - 2026-06-12
+- Document useFieldOptions companion-useRecords requirement — the hook only populates once an active useRecords in the same block has loaded the table schema; without it options settles to [] with isLoading false (bites write-only/helper blocks hardest). Add the required companion query to the example, correct the return shape to { options, isLoading } with options { id, label, color }, note the cross-table helper-block pattern, and add a prefer-live-fall-back-to-hardcoded recommendation; bump to 1.10.1
+
 ## [1.10.0] - 2026-06-04
 - Bundle get-airtable-base CLI script for full base metadata export; document in SKILL.md, airtable.md, fields.md
 

package/datasources/airtable.md

@@ -128,7 +128,7 @@ This script reads only **metadata**, never records. To inspect record contents i
 | Phone                | Yes       | |
 | Linked Record        | Read/Write | Returns as `{ label, id }` objects |
 | Rollup               | Read-only | |
-| Formula              | Read-only | |
+| Formula              | Read-only | Reads fine for most formulas — BUT a formula that references an **autoNumber** field often comes back blank through Softr's data layer. See Gotchas → "Formulas depending on autoNumber". |
 | Lookup               | Read-only | |
 | Computed             | Read-only | |
 | Created Time         | Read-only | |
@@ -151,6 +151,21 @@ Mitigation: Use PAT authentication. Cache data where possible. Avoid unnecessary
 - **Linked records are objects** with `{ label, id }` structure, not plain text.
 - **View connections** apply Airtable-side filters and sorts before data reaches Softr. This is useful for pre-filtering but means the Softr block only sees the view's subset.
 - **Column names are case-sensitive.** `"First name"` and `"First Name"` are different.
+- **Formulas that depend on an `autoNumber` field can read back blank** (verified 2026-06-12). Softr serves most formulas fine — a `CONCATENATE` of text fields reads correctly — but a formula like `"WIG-" & RIGHT("0000" & {Autonumber}, 4)` frequently comes through as `""`, even though Airtable shows the value and a data re-sync doesn't fix it. The autoNumber dependency is the differentiator: a sibling formula on the same record (no autoNumber) reads fine.
+  - **Symptom:** one computed field is empty in `record.fields` while the rest populate; re-syncing the Softr data source doesn't help.
+  - **Fix:** don't read the formula — read the raw `autoNumber` field and rebuild the value in JS:
+    ```jsx
+    // q.select({ tag: "Wig Tag ID", auto: "Autonumber", ... })
+    function buildTag(f) {
+      var raw = getFieldValue(f.tag);
+      if (raw) return raw;                       // formula populated — use it
+      var n = f.auto;
+      if (n != null && typeof n === "object") n = (n.value != null) ? n.value : "";
+      var s = (n == null) ? "" : String(n).trim();
+      return s ? "WIG-" + ("0000" + s).slice(-4) : "";  // mirror the Airtable formula in JS
+    }
+    ```
+  - **Alternative (most robust):** add a plain single-line-text field and stamp the value into it with an Airtable automation on record create. Softr reads plain text 100% reliably, with no formula/autoNumber dependency.
 
 ## Best For
 - Teams already managing data in Airtable

package/datasources/reading.md

@@ -108,23 +108,43 @@ var options = (result.data && result.data.pages) ? result.data.pages.flatMap(fun
 Returns the current option list for any `singleSelect` / `multipleSelects` field — without hardcoding option IDs in your block. Useful when the schema's option list changes (renames, additions, reorders) and you don't want to redeploy the block every time.
 
 ```jsx
-import { useFieldOptions, q } from "@/lib/datasource";
+import { useFieldOptions, useRecords, q } from "@/lib/datasource";
+
+var specSelect = q.select({ status: "Status" });
+
+// REQUIRED: a companion records query in the SAME block loads the table schema that
+// useFieldOptions reads from. Without it, useFieldOptions settles to `{ options: [] }`
+// (isLoading false, length 0) even though the field has choices. count: 1 is enough.
+useRecords({ select: specSelect, count: 1 });
 
 var statusOptions = useFieldOptions({
-  select: q.select({ status: "Status" }),
+  select: specSelect,
   field: "status",   // the ALIAS from q.select(), NOT the raw field ID
 });
 
-// statusOptions.options → [{ id: "sel...", label: "Active" }, { id: "sel...", label: "Inactive" }]
-// Each item has `id` (the option's UUID, used in mutate payloads) and `label` (display string).
+// statusOptions → { options: [...], isLoading: bool }
+// statusOptions.options → [{ id: "sel...", label: "Active", color: "greenLight1" }, ...]
+//   id    — the option's UUID, used in mutate payloads
+//   label — display string
+//   color — Airtable swatch color name (optional; handy for tinting chips)
 ```
 
+**⚠️ Gotcha — requires a companion `useRecords` (verified 2026-06-12).** `useFieldOptions`
+only populates once an active `useRecords` in the same block has loaded that table's schema.
+This bites hardest in **write-only / invisible helper blocks** (the natural home for an
+option-publishing helper) because they otherwise never query records — so `options` stays
+`[]` forever with `isLoading: false`, which looks like "the field has no choices." The fix is
+a throwaway `useRecords({ select, count: 1 })` alongside the `useFieldOptions` call(s); the
+same `select` object can be shared by both. Reuse one `select` for many fields and call
+`useFieldOptions` once per field (alias). Symptom to recognise: hook returns
+`{ options: [], isLoading: false }` while the block is correctly bound to the data source.
+
 **When to use this vs. hardcoding:**
 
-- **Use `useFieldOptions`** when option IDs / labels could change post-deploy — selects with rapidly-evolving lists, user-editable choices, or any case where re-pasting blocks for an option rename is annoying.
-- **Hardcode** when the option set is stable and frequently referenced (e.g. a status enum that drives a state machine), so the IDs live in source and rename-safety is enforced by greppable constants.
+- **Use `useFieldOptions`** when option IDs / labels could change post-deploy — selects with rapidly-evolving lists, user-editable choices, or any case where re-pasting blocks for an option rename is annoying. Cross-table case: to render a select field from table B inside a block bound to table A (e.g. an intake form bound to Jobs that needs the Wigs `Color` options), put the `useRecords` + `useFieldOptions` in a hidden helper block bound to table B and publish the options to a `window` global (see [helper-blocks.md](../references/helper-blocks.md)).
+- **Hardcode** when the option set is stable and frequently referenced (e.g. a status enum that drives a state machine), so the IDs live in source and rename-safety is enforced by greppable constants. A robust middle ground: prefer the live options, fall back to a hardcoded list per field so the UI still renders if the helper hasn't published yet.
 
-`useFieldOptions` is the read-side equivalent of using `useLinkedRecords` for foreign records — it abstracts away the field's option store. Items are shaped `{ id, label }` (note: `label`, not `title` like `useLinkedRecords`).
+`useFieldOptions` is the read-side equivalent of using `useLinkedRecords` for foreign records — it abstracts away the field's option store. Items are shaped `{ id, label, color }` (note: `label`, not `title` like `useLinkedRecords`).
 
 ## Filtering
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softr-vibe-coding",
-  "version": "1.10.0",
+  "version": "1.10.2",
   "description": "Claude Code skill for generating production-ready Softr Vibe Coding blocks (JSX). Installs into ~/.claude/skills/ and auto-updates on each Claude Code session.",
   "bin": {
     "softr-vibe-coding": "./bin/cli.js"