softr-vibe-coding 2.6.0 → 2.7.0

package/CHANGELOG.md

@@ -4,6 +4,9 @@ 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.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,14 @@ 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, bare inline-editor variant
 │
 ├── 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)
    - 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, 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.7.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/searchable-dropdown.md

@@ -0,0 +1,149 @@
+# 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.
+
+## Show the search box only when it earns its place
+
+```jsx
+var searchable = props.onCreate
+  ? true
+  : props.searchable === true || (props.searchable !== false && options.length >= 8);
+```
+
+Under eight options a search box is noise — the picker should still read as a picker.
+
+## 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.
+  ⚠ 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
+- [ ] Search box hidden under 8 options
+- [ ] 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