softr-vibe-coding 2.7.0 → 2.8.1

package/CHANGELOG.md

@@ -4,6 +4,13 @@ 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.
 
+## [2.8.1] - 2026-09-10
+- Verifying a push: errors:null is not proof — fetch-back byte-compare, deployed==disk pre-check, two-block swaps (2.8.1)
+- Inventory + keyboard-picker snippet reconciled with the shipped projects-table shape
+
+## [2.8.0] - 2026-09-09
+- Dropdowns searchable by default, reset controls only when dirty, create → open the new record
+
 ## [2.7.0] - 2026-09-09
 - Add the searchable dropdown pattern (Combo) as a reference
 

package/README.md

@@ -185,7 +185,7 @@ softr-vibe-coding/
 │   │                                 # Scripting Extension, cross-table cascades,
 │   │                                 # batch update gotchas, field-ID discipline,
 │   │                                 # Airtable formulas
-│   ├── softr-mcp.md                  # Official Softr MCP server — vibe coding block
+│   ├── softr-mcp.md                  # Official Softr MCP server — vibe coding block (+ push verification protocol)
 │   │                                 # tools (create/edit/version/deploy), integrations
 │   │                                 # browsing (Airtable/Sheets/Notion/Supabase),
 │   │                                 # Softr DB schema + record tools incl. deletes,
@@ -204,7 +204,7 @@ softr-vibe-coding/
 │   ├── anti-patterns.md              # Categorized violation catalog
 │   │                                 # Data access, mutations, hooks, layout,
 │   │                                 # permissions, editable settings, helper blocks
-│   ├── common-patterns.md            # Small reusable patterns
+│   ├── common-patterns.md            # Small reusable patterns (localStorage state, clipboard, nav blocker, drag-to-reorder, create → open, clickable row + inner link, keyboard picker)
 │   │                                 # localStorage cross-page state, clipboard copy,
 │   │                                 # navigation blocker, scroll-condensing header,
 │   │                                 # auth-aware CTA, image masks, blobs, dot lists
@@ -227,7 +227,9 @@ softr-vibe-coding/
 │                                     # why native <select> and shadcn <Select> both
 │                                     # break in the shadow DOM, composedPath()
 │                                     # click-outside, A-Z inside the component,
-│                                     # multi-token filter, bare inline-editor variant
+│                                     # multi-token filter, searchable BY DEFAULT
+│                                     # (bare = click-only; searchable={false} only
+│                                     # for a fixed enum being set — Sep 10 2026)
 │
 ├── tools/                            # Bundled CLI scripts (run, not read)
 │   ├── get-airtable-base             # Full Airtable base schema export (bash + jq)

package/SKILL.md

@@ -85,10 +85,11 @@ You generate complete, production-ready Softr Vibe Coding blocks as TypeScript R
    - `useRecordUpdate` payload is `{ recordId, fields: { ... } }` — nested. `useRecordCreate` payload is **flat** (no `fields` wrapper). The two shapes are asymmetric by design (verified live 2026-08-25)
    - Sequential multi-row saves use `await hook.mutateAsync(...)` per row, in order, with stop-on-failure + retry state — `mutateAsync` is fully supported on the current platform (verified 2026-08-25; the old ".mutate() only" Action-parser rule is gone — see [datasources/writing.md](datasources/writing.md)). Independent writes to **different tables** may run in parallel via `Promise.all`; drag/reassign UIs should be optimistic with an Undo toast — see [writing.md → Parallel writes across tables](datasources/writing.md#parallel-writes-across-tables-the-one-sanctioned-parallelism)
    - No hardcoded domains in links -- use relative paths (`/page?recordId=...`); same-page anchors written relative too (`/#section`)
-   - **No `<select>` and no shadcn `<Select>`** — both break inside a block's shadow DOM (native hands the list to the OS; shadcn portals outside the shadow root and arrives unstyled). Use the `Combo` pattern in [references/searchable-dropdown.md](references/searchable-dropdown.md)
+   - **No `<select>` and no shadcn `<Select>`** — both break inside a block's shadow DOM (native hands the list to the OS; shadcn portals outside the shadow root and arrives unstyled). Use the `Combo` pattern in [references/searchable-dropdown.md](references/searchable-dropdown.md) — **searchable by default** for every framed filter or form field whatever the option count; `bare` inline editors are click-only; `searchable={false}` only on a short fixed enum the user is setting (a status, a location, a group-by)
    - Static block: no hardcoded user-visible copy — every string/image/link is an editable setting (see [references/editable-settings.md](references/editable-settings.md#granularity-doctrine-settings-first-static-blocks))
    - Array-setting rows keyed by **index**, never by a builder-editable field value
    - Media settings that may start empty (`src: ""`) gated with a conditional render or placeholder — never an unconditional `<img src={setting.src}>`
+   - **Deploying through the MCP:** `errors: null` on a push is not proof — fetch the block's `sourceCode` back and byte-compare it to the file you sent (trailing newline normalised, nothing else), and prove deployed == disk *before* editing so a Studio-side change is never overwritten. Protocol in [references/softr-mcp.md → Verifying a push](references/softr-mcp.md#verifying-a-push--the-deployed-source-is-the-only-proof)
 
 ## What to Clarify
 
@@ -168,7 +169,7 @@ For advanced patterns beyond data fetching, load the relevant reference when the
 | Embedding third-party libraries with their own CSS (Leaflet, Mapbox, TinyMCE, Quill, FullCalendar) | [references/advanced-integrations.md](references/advanced-integrations.md) |
 | Debugging a broken block, checking patterns before delivery, full violation catalog | [references/anti-patterns.md](references/anti-patterns.md) |
 | Quick syntax check — import paths, hook signatures, mutation call shapes, field mapping | [references/quick-reference.md](references/quick-reference.md) |
-| Any **dropdown / picker / combobox** in a block — why shadcn `<Select>` and native `<select>` both fail inside the shadow DOM, the `composedPath()` click-outside, sorting A→Z inside the component, multi-token filtering, the `bare` inline-editor variant | [references/searchable-dropdown.md](references/searchable-dropdown.md) |
+| Any **dropdown / picker / combobox** in a block — why shadcn `<Select>` and native `<select>` both fail inside the shadow DOM, the `composedPath()` click-outside, sorting A→Z inside the component, multi-token filtering, **searchable by default** regardless of option count (`bare` inline editors click-only; `searchable={false}` only for a short fixed enum being set), the `bare` inline-editor variant | [references/searchable-dropdown.md](references/searchable-dropdown.md) |
 | Small reusable patterns — `localStorage` cross-page state, clipboard copy button | [references/common-patterns.md](references/common-patterns.md) |
 | Writing Airtable Automation Scripts / Scripting Extension scripts / Airtable formulas — companion to Softr blocks for cross-table cascades and computed values | [references/airtable-automations.md](references/airtable-automations.md) |
 | The official **Softr MCP server** — Softr DB schema + full record/table/field/database CRUD (deletes included), field-level browsing of connected Airtable / Google Sheets / Notion / Supabase integrations, **creating, editing, versioning, and deploying Vibe Coding blocks directly** (`get_vibe_coding_docs`, `create_vibe_coding_block`, ...), app management/scaffolding, the **Softr Workflows** suite (26 tools, 418-node catalog), and **per-application MCP servers** | [references/softr-mcp.md](references/softr-mcp.md) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softr-vibe-coding",
-  "version": "2.7.0",
+  "version": "2.8.1",
   "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"

package/references/common-patterns.md

@@ -15,6 +15,8 @@ Small reusable patterns that come up across Vibe Coding blocks but don't warrant
 - [Decorative Background Blobs (Editorial Layering)](#decorative-background-blobs-editorial-layering)
 - [Dot-Separated Inline List](#dot-separated-inline-list)
 - [Drag-to-Reorder Rows](#drag-to-reorder-rows)
+- [Create → open](#create--open)
+- [Clickable Row with an Inner Link](#clickable-row-with-an-inner-link)
 
 ## Cross-Page State with localStorage + URL Parameters
 
@@ -392,3 +394,125 @@ on failure, clear the override and refetch, because a half-applied renumber is w
 **Only gate the drag on permissions, not on a sort mode.** If the list has an alternative sort, let the
 drag switch to manual order rather than disabling the handle — see the disabled-control note in
 [../ui-ux-guidelines.md](../ui-ux-guidelines.md#26-finishing-touches).
+
+## Create → open
+
+When the user creates a record they are about to work on — a new item, a new saved list — land them on it. They made it in order to fill it in, so closing the dialog back into the list and leaving them to find the row they just made is a step nobody asked for. Leo, 2026-09-10: "when you create a new item anywhere in the interface, once it's created, you need to open the item details page of the item you just created … when you create a new list, once it's created, you need to open this list details, as you'll likely want to fill the list straight after."
+
+`useRecordCreate`'s `onSuccess` receives the created record, but the wrapper around its id has moved before. Read it defensively — a miss is survivable, a crash is not:
+
+```jsx
+/* What useRecordCreate hands onSuccess is the created record. The exact wrapper has moved
+   before, so read the id defensively — a miss is survivable (the row still gets created and
+   the list still refetches, the user just picks it) but a crash is not. */
+function getCreatedId(created) {
+  if (!created) return "";
+  if (typeof created === "string") return created;
+  if (created.id) return String(created.id);
+  if (created.recordId) return String(created.recordId);
+  if (created.record && created.record.id) return String(created.record.id);
+  if (created.data && created.data.id) return String(created.data.id);
+  return "";
+}
+```
+
+Then navigate on success — and only when there is an id to navigate to:
+
+```jsx
+createItem.mutate(payload, {
+  onSuccess: function (created) {
+    setBusy(false);
+    var id = getCreatedId(created);
+    if (id) {
+      window.location.href = "/item?recordId=" + encodeURIComponent(id);
+      return;
+    }
+    // The record exists; we just can't address it. Stay put, refetch, say so.
+    setOpen(false);
+    itemsResult.refetch();
+    toast.success('"' + name + '" created — it is in the list below.');
+  },
+  onError: function () {
+    setBusy(false);
+  },
+});
+```
+
+**Never navigate with an empty id.** `/item?recordId=` would render the detail page's own "record not found" state, and the user would conclude the create failed when it did not. The fallback keeps them where the new row will appear once the refetch lands.
+
+**Keep the path relative.** `/item?recordId=…`, never the app's domain — the same block runs on the preview URL and on the custom domain (SKILL.md's no-hardcoded-domains rule).
+
+**Where the id comes from is not always where it goes.** For an `onCreate` inside a Combo — a vendor typed into a picker — the created id is patched into the form and the user keeps editing; there is nothing to open. See [searchable-dropdown.md](searchable-dropdown.md#variants-worth-having). Navigation is for records that have their own page and that the user will work on next.
+
+## Clickable Row with an Inner Link
+
+An index table exists to get the user into a record, so the hit area is the whole row. But a row is not a link: cmd-click, middle-click, right-click → "Copy link" and hover-to-see-the-URL all come from a real `<a>`. Keep both — the row handler for the plain click, an anchor on the name for everything the browser does with anchors — and make sure they do not fight:
+
+```jsx
+function ProjectRow(props) {
+  var row = props.row;
+  var href = "/project?recordId=" + encodeURIComponent(row.id);
+
+  // The row handler bows out the moment a modifier is held — those clicks belong to the
+  // anchor (new tab, new window, select).
+  function openRow(event) {
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+    if (typeof window !== "undefined") window.location.href = href;
+  }
+
+  return (
+    <TableRow className="cursor-pointer hover:bg-[#FFF7EF]" onClick={openRow}>
+      <TableCell>
+        <a
+          href={href}
+          className="hover:underline"
+          onClick={function (e) {
+            e.stopPropagation(); // the anchor navigates itself; without this the row handler ALSO fires
+          }}
+        >
+          {row.name}
+        </a>
+      </TableCell>
+      {/* … */}
+    </TableRow>
+  );
+}
+```
+
+Two things go wrong without the two guards. Without `stopPropagation` on the anchor, a cmd-click on the name opens the new tab AND navigates the current one, because the row handler runs too. Without the modifier check on the row, a cmd-click on the cell padding (next to the anchor, not on it) navigates the current tab — the opposite of what the user asked for.
+
+Any *other* control inside the row — an inline status chip, a checkbox, a menu — needs `stopPropagation` on its own handler as well, or every click on it opens the record. (The drag handle in [Drag-to-Reorder Rows](#drag-to-reorder-rows) already does this.)
+
+### Keyboard picker over the same rows
+
+Where a table has a quick-find box, wire it like a picker so the keyboard alone gets into a record: the box takes focus, ↑ ↓ move a highlight, Enter opens the highlighted row, Escape clears the query (and the highlight with it).
+
+```jsx
+var [active, setActive] = useState(0);
+// Filtering shrinks the list under the highlight, so clamp rather than index past the end.
+var activeIdx = rows.length === 0 ? 0 : Math.min(active, rows.length - 1);
+
+function onKeyDown(e) {
+  if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+    e.preventDefault();
+    var step = e.key === "ArrowDown" ? 1 : -1;
+    setActive(function (a) {
+      return Math.min(Math.max(a + step, 0), Math.max(rows.length - 1, 0));
+    });
+  } else if (e.key === "Enter") {
+    e.preventDefault();
+    var hit = rows[activeIdx];
+    if (hit) window.location.href = "/project?recordId=" + encodeURIComponent(hit.id);
+  } else if (e.key === "Escape") {
+    e.preventDefault();
+    setQuery("");
+    setActive(0);
+  }
+}
+
+<input autoFocus value={query} onChange={function (e) { setQuery(e.target.value); setActive(0); }} onKeyDown={onKeyDown} … />
+```
+
+Make the rows themselves focusable too (`tabIndex={0}`, an `onKeyDown` that opens on Enter only when `event.target === event.currentTarget`, so an Enter on the anchor inside the row is not handled twice), and let `onMouseEnter` *and* `onFocus` both move the highlight onto the row — the highlight is the single answer to "which record does Enter open", whichever device last touched it. That is the shape `projects-table.jsx` shipped on 2026-09-10.
+
+Paint the highlighted row with the same colour the mouse hover gets (`data-active="true"` + `bg-[#FFF7EF]`) and scroll it into view when it moves (`querySelector('[data-active="true"]').scrollIntoView({ block: "nearest" })` in a `useEffect` on `activeIdx`) — the Combo in [searchable-dropdown.md](searchable-dropdown.md#one-flat-row-list-for-the-keyboard) does the same. Reset `active` to 0 whenever the query changes: the old index points at a row that may no longer be in the list. `autoFocus` is right only when the block *is* the page's reason to exist — an index page whose first act is always a search; on a page with content above the table, a focus steal scrolls the page to the box.

package/references/searchable-dropdown.md

@@ -81,15 +81,44 @@ var filtered = options.filter(function (o) {
 
 So `rural art` finds *The Rural Art Company*. A single `indexOf(query)` would not.
 
-## Show the search box only when it earns its place
+## Searchable by default — not by option count
 
 ```jsx
 var searchable = props.onCreate
   ? true
-  : props.searchable === true || (props.searchable !== false && options.length >= 8);
+  : props.searchable === true || (props.searchable !== false && !props.bare);
 ```
 
-Under eight options a search box is noise — the picker should still read as a picker.
+Every **framed** dropdown — a table filter, a form field — gets the search box, whatever the
+option count. `bare` inline editors are click-only. `onCreate` forces the box on, because the
+typed text is what gets created.
+
+**Why not a threshold (changed 2026-09-10).** The first version of this component showed the
+search box at 8+ options. On one filter row that made "All projects" (2 options) a plain
+picker and "All vendors" (99) a type-to-filter, side by side, and the client read the
+difference as a bug — the project filter looked like the broken one. The count of options is
+*data*; whether a dropdown is searchable is *design*, and design must not change under the
+user's hands the day a third project is added. Leo, 2026-09-10: type-to-filter is the default
+for table filters, even a two-option one, so the desk never has to check whether *this*
+dropdown is the searchable kind. The other half of the same instruction: a status update in a
+table row is a click, not a search — which is what `bare` already is.
+
+### Which dropdowns get a search box
+
+| Dropdown | Search box | How |
+|---|---|---|
+| Table filter — project, vendor, status, room, any of them | yes | default |
+| Open-ended or data-driven picker in a form — vendor, project, room, item, purchase order, saved list | yes | default |
+| Short **fixed** enum the user is **setting** — a status, a location, a purpose, a group-by / sort-by | no | `searchable={false}` |
+| Inline `bare` editor in a table cell — a status chip, a location string | no | `bare` is click-only |
+| Anything with `onCreate` | yes, always | forced |
+
+The third row is the only place `searchable={false}` belongs: four fixed options the user is
+choosing *between*, where a search box is noise. A *filter* on that same status field still
+gets the box — filtering and setting are different jobs, and the filter row is exactly where
+the rule has to hold uniformly. If a wrapper sits between the call site and `Combo`
+(`ColumnFilter`, `SelectInput`, …), thread `searchable={props.searchable}` through it rather
+than reaching past the wrapper.
 
 ## One flat row list for the keyboard
 
@@ -111,7 +140,8 @@ A filter row near the bottom of the viewport otherwise opens into nothing.
 
 - **`bare`** — inline-editor mode. No border, no fill; `triggerContent` (a status chip, a
   cell's text) *is* the trigger. Lets a table cell become editable without every row growing
-  a form control.
+  a form control. Click-only: the search box is off in this variant, because a status update
+  in a row is a click, not a search (Leo, 2026-09-10).
   ⚠ If any column width in your table is derived from the trigger's chrome, keep the
   chevron the SAME size in both variants. Shrinking it in `bare` silently changes those
   widths in a different file.
@@ -141,7 +171,7 @@ Everything else — the trigger, the card, the rows — stays flat.
 - [ ] `composedPath()` click-outside
 - [ ] Sorted A→Z inside the component, with `autoSort={false}` only where order is meaning
 - [ ] Multi-token filter
-- [ ] Search box hidden under 8 options
+- [ ] Searchable by default; `bare` is click-only; `searchable={false}` only on a short fixed enum the user is setting
 - [ ] Keyboard: ↑ ↓ Enter Esc Tab, active row scrolled into view
 - [ ] `aria-haspopup="listbox"`, `aria-expanded`, `role="listbox"` / `role="option"`,
       `aria-selected`, and an `aria-label` on the trigger

package/references/softr-mcp.md

@@ -101,6 +101,57 @@ components, adding a hook — where being sure of "the exact current text" of a
 is harder than being sure of the whole file. Also use it when the local file is the source of truth and
 has drifted from the deployed block in ways you have not enumerated.
 
+### Verifying a push — the deployed source is the only proof
+
+`update_vibe_coding_block_code` returning `errors: null, warnings: null` proves the code **compiled**.
+It does not prove the block now holds the code you meant to send. Verified 2026-09-09: a push of a
+67KB block came back clean and had silently dropped one blank line at a read-chunk boundary — valid
+JavaScript, so the compiler had nothing to say. Only a byte comparison caught it. Treat every push as
+unverified until you have pulled the source back down and compared it.
+
+**The protocol, per block:**
+
+1. **Before editing, prove deployed == disk.** Call `get_vibe_coding_block_code`, extract
+   `sourceCode`, and compare it byte-for-byte to your local mirror. If they differ, someone changed
+   the block in Studio since your last push — stop and reconcile; do not overwrite work you have not
+   seen. (Large results are persisted to a file by most clients rather than returned inline; compare
+   from that file with a script, never by eye.)
+2. Edit the local file. Run a parser and `no-undef` lint on it first — `node --check` does **not**
+   accept a `.jsx` extension, so use esbuild (`esbuild file.jsx --loader:.jsx=jsx --jsx=automatic
+   --log-level=error --outfile=/dev/null`) plus eslint with `@babel/eslint-parser`. The bugs that
+   actually bite Softr blocks are semantic — `useRecordUpdate({ select: … })` instead of `fields:`,
+   an invented identifier — and the push is the first thing that reports them.
+3. Push the **entire** file.
+4. **Fetch it back and compare again.** Identical, or you are not done: diff, fix, re-push.
+
+**Tolerate exactly one difference: the trailing newline.** Softr sometimes strips the file's final
+`\n` on save and sometimes keeps it — stripped on every push on 2026-09-09, kept on every push on
+2026-09-10, same app, same tools. A comparison that demands byte equality will report a phantom
+mismatch on some days; one that ignores *all* whitespace will miss the dropped-blank-line case above.
+Compare with the trailing newline normalised and nothing else.
+
+**One file, two blocks, two datasource pairs.** When the same source is deployed to two pages, the
+local file holds ONE page's `datasource.define()` pair. Push it as-is to that block; for the other,
+build the swapped text in a scratch location, push that, and verify each block against its own
+expectation (disk for the first, disk-with-swap for the second). Never save the swapped copy over
+the local mirror — the mirror records which page it belongs to, and the block's header comment
+records the other page's pair. Search-replace would avoid the swap altogether
+([above](#which-edit-tool-full-replace-vs-targeted-search-replace)) — when the client can send its
+array argument ([below](#the-array-argument-serialization-quirk-and-why-it-is-a-security-issue)).
+
+**Do not read a 100KB block into a model's context to push it.** The full-replace tool takes the
+whole file as a string parameter, so the source has to pass through whatever is making the call. A
+large multi-block deploy is safer farmed out one file per subagent — a fresh context per file means
+no compaction can land mid-file — and the byte comparison is what makes that delegation safe, not
+trust in the agent. The steps that need judgement are the *edit* and the *review of the diff*; the
+fetch, the compare and the push itself are mechanical, and can run on the cheapest tier available
+without lowering the bar, because a wrong result fails loudly rather than plausibly.
+
+**What a push also resets.** Every code push puts the block's derived Actions back on Softr's
+default permissions (see the next section for why that can be a security problem and how to verify
+the restoration). If page-level visibility is the access control in your app, record that decision
+so nobody chases the reset after every round; if it is not, re-tighten and read back.
+
 ### The array-argument serialization quirk, and why it is a security issue
 
 **Several tools on this server take an array argument, and some MCP clients serialize it as a JSON

package/ui-ux-guidelines.md

@@ -342,6 +342,8 @@ Vestibular disorders affect ~35% of adults over 40. Always respect `prefers-redu
 - **Never disable without explaining why.** Show tooltip or helper text.
 - **Destructive buttons** must: use `variant="destructive"`, be positioned away from primary actions, trigger confirmation for irreversible actions.
 - **DO NOT make every button primary.** Use ghost, outline, and secondary styles for hierarchy.
+- **A reset / undo control renders only when there is something to reset.** "Reset column widths" appears the moment a column has been dragged and is gone again once the widths are back at their defaults — not disabled as a placeholder, not `visibility: hidden` holding its space. A reset for something nobody changed is a control that can only ever do nothing, and a greyed one reads as broken (see [§26](#26-finishing-touches)). Mount it in a slot whose appearance cannot reflow its neighbours — a right-aligned end slot of the toolbar row, never the middle of a wrapping flex row, where mounting it would re-wrap the line on the first drag and un-wrap it on reset. (Leo, 2026-09-10: "ANY reset column width should ONLY show when you change the column width.")
+- **After creating a record the user will work on next, open it.** A new item, a new saved list — the user made it in order to fill it in, so `onSuccess` navigates to that record's detail page instead of closing the dialog back into the list and leaving them to find the row they just made. Read the created id defensively with `getCreatedId()` ([common-patterns.md → Create → open](references/common-patterns.md#create--open)); when the id cannot be read, stay put, refetch and toast — never navigate to a URL with an empty id. (Leo, 2026-09-10: "when you create a new item anywhere in the interface, once it's created, you need to open the item details page of the item you just created … when you create a new list, once it's created, you need to open this list details, as you'll likely want to fill the list straight after.")
 
 ---