softr-vibe-coding 2.6.0 → 2.8.0

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.
 
+## [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
+
 ## [2.6.0] - 2026-09-09
 - Drag-to-reorder: the pattern, the shadow-DOM hit-test trap, and two affordance rules
 

package/README.md

@@ -220,9 +220,16 @@ softr-vibe-coding/
 │   │                                 # MCP/CLI install (@latest npx + browser step),
 │   │                                 # extract → poll → findings → generate → write
 │   │                                 # flow, DESIGN.md anatomy, drift QA
-│   └── quick-reference.md            # Syntax cheat sheet
-│                                     # Imports, hook signatures, mutation shapes,
-│                                     # field mapping, component skeleton
+│   ├── quick-reference.md            # Syntax cheat sheet
+│   │                                 # Imports, hook signatures, mutation shapes,
+│   │                                 # field mapping, component skeleton
+│   └── searchable-dropdown.md        # THE dropdown pattern for blocks
+│                                     # why native <select> and shadcn <Select> both
+│                                     # break in the shadow DOM, composedPath()
+│                                     # click-outside, A-Z inside the component,
+│                                     # 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,6 +85,7 @@ 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) — **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}>`
@@ -167,6 +168,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, **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.6.0",
+  "version": "2.8.0",
   "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,123 @@ 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} … />
+```
+
+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

@@ -0,0 +1,179 @@
+# The searchable dropdown (`Combo`)
+
+**Use this instead of shadcn's `<Select>` and instead of a native `<select>`, always.**
+A Vibe Coding block renders inside a **shadow DOM**, and that one fact rules out both of
+the obvious choices:
+
+| Option | Why it fails in a block |
+|---|---|
+| Native `<select>` | Hands the list to the OS. No keyword filter, none of your styling, and on macOS it paints a grey slab over the page. Fine for 5 options, unusable at 90. |
+| shadcn `<Select>` / `<Command>` | **Portals to `document.body`, which is outside the block's shadow root**, so the styles arrive stripped. It also cannot be searched. |
+| `Combo` (below) | Local DOM, brand-styled, keyword filter, A→Z, keyboard, create-new, drop-up. |
+
+Copy the component into the block. A Vibe block is one self-contained file — there is no
+shared module to import, so each block carries its own copy. Keep one canonical copy in the
+project (e.g. `Assets/Softr App/Shared/combo.jsx`) and port changes from there.
+
+## The three things that will bite you
+
+**1. Click-outside must use `composedPath()`, not `contains()`.**
+By the time a click reaches `document`, the shadow DOM has *retargeted* its `target` to the
+shadow **host**. So the usual `root.contains(e.target)` test calls the panel's own rows
+"outside" and closes the panel before the click can land on one — the dropdown appears to
+ignore every selection.
+
+```jsx
+function onDown(e) {
+  var root = rootRef.current;
+  if (!root) return;
+  var path = e.composedPath ? e.composedPath() : [];
+  for (var i = 0; i < path.length; i++) {
+    if (path[i] === root) return;      // inside — leave it open
+  }
+  if (path.length === 0 && e.target && root.contains(e.target)) return;  // fallback
+  setOpen(false);
+}
+document.addEventListener("mousedown", onDown, true);
+```
+
+**2. Define it at MODULE scope, never inside `Block()`.**
+A component redefined inside `Block()` gets a fresh identity every render, so React unmounts
+and remounts the `<input>` and the search box loses focus after one keystroke. This is the
+single most common Vibe Coding bug and it looks like a platform fault.
+
+**3. `onMouseDown` on a row must `preventDefault()`.**
+Otherwise focus leaves the search input before the click resolves.
+
+## Sort A→Z *inside* the component
+
+Sorting at the call site gets forgotten. Do it in the component, with an opt-out:
+
+```jsx
+function comboSortLabels(a, b) {
+  return String(a.label || "").localeCompare(String(b.label || ""), undefined, {
+    sensitivity: "base",   // case-insensitive
+    numeric: true,         // "Item 2" before "Item 10" — a plain compare gets this backwards
+  });
+}
+```
+
+`autoSort` defaults to **true**. Pass `autoSort={false}` only where the given order *is* the
+meaning — a pipeline of statuses (Not ordered → Ordered → … → Delivered), a physical
+journey, a curated short list. Alphabetising a workflow puts "Damaged" first and buries the
+starting state in the middle, which is worse than not sorting at all.
+
+Grouped lists sort **within** a group and keep first-seen group order, so a "this project's
+rooms first, everyone else after" grouping survives being alphabetised.
+
+## Filter on every token, in any order
+
+```jsx
+var tokens = query.trim().toLowerCase().split(/\s+/).filter(Boolean);
+var filtered = options.filter(function (o) {
+  if (tokens.length === 0) return true;
+  var hay = String(o.label || "").toLowerCase();
+  for (var i = 0; i < tokens.length; i++) {
+    if (hay.indexOf(tokens[i]) === -1) return false;
+  }
+  return true;
+});
+```
+
+So `rural art` finds *The Rural Art Company*. A single `indexOf(query)` would not.
+
+## Searchable by default — not by option count
+
+```jsx
+var searchable = props.onCreate
+  ? true
+  : props.searchable === true || (props.searchable !== false && !props.bare);
+```
+
+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
+
+Build `rows` as a single array — the optional *clear* row, then the filtered options, then
+the optional *create* row — so arrow-key navigation has one index to walk. Clamp the active
+index (`Math.min(active, rows.length - 1)`): filtering shrinks the list under the highlight.
+
+## Drop up near the fold
+
+```jsx
+var r = rootRef.current.getBoundingClientRect();
+var below = window.innerHeight - r.bottom;
+setDropUp(below < 300 && r.top > below);
+```
+
+A filter row near the bottom of the viewport otherwise opens into nothing.
+
+## Variants worth having
+
+- **`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. 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.
+- **`triggerStyle`** — merged over the defaults, for a trigger that is part of the design
+  (a chip painted in its own status colour) rather than a plain field.
+- **`onCreate(text)`** — offers `Add "<typed>"` when nothing matches. If creating the record
+  and *linking* it happen at different times, say so in the toast: the two halves landing
+  separately is exactly what gets reported as "it didn't save".
+- **`emptyLabel`** — a row that clears the selection. Call sites that pass a leading
+  `{ value: "" }` "any / none" option should have it lifted into `emptyLabel` rather than
+  rendered twice.
+
+## The one shadow you are allowed
+
+DESIGN-system rules that ban shadows are about cards. A white panel floating over a white
+card with only a hairline between them reads as part of the card, so the menu gets a shadow:
+
+```js
+boxShadow: "0 10px 30px rgba(0, 0, 0, 0.16)"
+```
+
+Everything else — the trigger, the card, the rows — stays flat.
+
+## Checklist before shipping a dropdown
+
+- [ ] Defined at module scope
+- [ ] `composedPath()` click-outside
+- [ ] Sorted A→Z inside the component, with `autoSort={false}` only where order is meaning
+- [ ] Multi-token filter
+- [ ] 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
+- [ ] Loading and empty states (`"Nothing matches that."`)
+- [ ] No `@/components/ui/select` import anywhere in the file

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.")
 
 ---