softr-vibe-coding 2.5.2 → 2.7.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.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
+
 ## [2.5.2] - 2026-09-09
 - Permission finding is advisory, not a veto — report severity and leave the call to the builder
 

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.5.2",
+  "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/anti-patterns.md

@@ -68,6 +68,7 @@ Run through this catalog before delivering any block. Every row is a violation o
 | Hardcoded domain in navigation | Relative paths: `/task-details?recordId=...` |
 | Placing a `<NavigationAction navigation={{ action: "OPEN_CHAT" }}>` Ask-AI button on a block that has no data source connected | Connect the block to the data source the AI should read from in Studio's Source tab. Softr's AI pulls context from the **block that triggered the chat**, not from the page — a button-only helper block with no data source causes `chat/prepare` → HTTP 500 ("Failed to prepare AI assistant") even though the chat UI opens fine. The block doesn't need to read or write records itself; the connection is purely for AI context. Verified by direct experiment, May 2026 |
 | Emojis in UI | lucide-react icons only |
+| `document.elementFromPoint(x, y)` to hit-test during a drag or custom pointer interaction | It returns the block's shadow **host**, not the element under the cursor — same boundary that stops `getElementById` and URL-fragment lookup. Either call it on the shadow root (`ref.current.getRootNode().elementFromPoint(x, y)`) or, better, keep refs to the candidate elements and compare `getBoundingClientRect()` yourself: rects need no shadow-root plumbing and work identically when the block is later reused elsewhere |
 | Positioning repeated page chrome (back button, title, primary action) per-block, without checking the pages that already have it | Chrome the user meets on more than one screen is a cross-page contract. Copy the exact offset from the blocks that already ship it, and change every page in one edit. Let the wrapper's padding be the only thing positioning it — `mb-4` and NO top margin on a back button — so one number per page governs it. Verified 2026-09-09: an extra `mt-6` sat one detail page's back button 24px lower than another's, and **each block looked correct in isolation**. See SKILL.md's Block Placement section |
 | A loading skeleton carrying a different border / offset from the component it stands in for | The skeleton must track the component's REST state (border colour, padding, chrome offsets), never its hover state. If they disagree the layout visibly re-draws the instant data lands — the exact thing a skeleton exists to prevent. Verified 2026-09-09 twice in one session: a card grid re-outlined itself on load, and a back button jumped 24px. See [ui-ux-guidelines.md](../ui-ux-guidelines.md) §12 |
 | `focus-visible:` on a card or row that only *contains* buttons | The container is a plain `<div>` and never takes focus, so it is dead CSS. Use `focus-within:` on the container (pairs with its `hover:` treatment) and keep `focus-visible:ring-2` on the button/link itself |

package/references/common-patterns.md

@@ -14,6 +14,7 @@ Small reusable patterns that come up across Vibe Coding blocks but don't warrant
 - [Edge-Fade Image Mask (Editorial Hero)](#edge-fade-image-mask-editorial-hero)
 - [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)
 
 ## Cross-Page State with localStorage + URL Parameters
 
@@ -292,3 +293,102 @@ Certifications, feature tags, meta rows: `GMP Manufacturing ● ISO 22716 ● Lo
 - **Keep `gap-y-*`** on the container for multi-line rhythm when the list wraps.
 - **If the list is expected to wrap often**, drop the dots and let the gap carry the rhythm — any inline separator looks orphaned at a line break.
 - `aria-hidden="true"` on the glyph — screen readers announce `●` as "black circle" otherwise.
+
+
+## Drag-to-Reorder Rows
+
+Reordering a list by dragging, written against a Softr block's constraints. Four of the five decisions
+below are non-obvious, and each one is a bug if you get it wrong.
+
+```jsx
+var [drag, setDrag] = useState(null);            // { from, over } while dragging, else null
+var [optimisticOrder, setOptimisticOrder] = useState(null);  // ids, post-drop, pre-refetch
+var rowElsRef = useRef([]);
+
+/* The pointer is CAPTURED, so no other element receives enter/leave — rects are the only
+   thing that can answer "what is under the cursor". Compare against each row's MIDPOINT so
+   the row you are over is the one that yields. */
+function dropIndex(count, clientY) {
+  for (var i = 0; i < count; i++) {
+    var el = rowElsRef.current[i];
+    if (!el) continue;
+    var r = el.getBoundingClientRect();
+    if (clientY < r.top + r.height / 2) return i;
+  }
+  return count - 1;
+}
+```
+
+The handle — never the whole row, so text selection and the row's own buttons keep working:
+
+```jsx
+<span
+  role="button"
+  aria-label={"Drag to reorder " + row.name}
+  className="touch-none select-none"          // or the browser scrolls instead of dragging
+  style={{ cursor: "grab" }}
+  onPointerDown={function (e) {
+    e.preventDefault();
+    try { e.currentTarget.setPointerCapture(e.pointerId); } catch (err) {}
+    setDrag({ from: index, over: index });
+  }}
+  onPointerMove={function (e) {
+    if (!drag) return;
+    var over = dropIndex(rows.length, e.clientY);
+    if (over !== drag.over) setDrag({ from: drag.from, over: over });
+  }}
+  onPointerUp={function () {
+    if (!drag) return;
+    var from = drag.from, to = drag.over;
+    setDrag(null);
+    if (from !== to) {
+      var next = rows.slice();
+      next.splice(to, 0, next.splice(from, 1)[0]);
+      applyOrder(next);
+    }
+  }}
+  onPointerCancel={function () { setDrag(null); }}
+>
+  <GripVertical className="h-3.5 w-3.5" />
+</span>
+```
+
+**Pointer capture, not mouse events.** Capture makes the handle the target of every move and of the up
+*wherever the pointer travels*, and obliges the browser to send `pointercancel` if it takes the pointer
+away. Without it, a drag released over another application never delivers its up and the row stays
+stuck mid-drag until a reload.
+
+**Measure rects, don't listen for `onPointerEnter` on each row.** While the pointer is captured, no
+other element gets enter/leave at all, so per-row handlers silently never fire. And
+`document.elementFromPoint` is not the escape hatch — inside a block it returns the shadow host (see
+[anti-patterns.md](anti-patterns.md#layout--styling)).
+
+**Draw the insertion line with an INSET box-shadow, never a border.** A real 2px border grows the row
+by 2px and shoves every row below it down a notch, so the list crawls under the pointer as the target
+changes:
+
+```jsx
+style={Object.assign({}, ROW_STYLE, isTarget
+  ? (drag.over < drag.from
+      ? { boxShadow: "inset 0 2px 0 0 " + ACCENT }     // landing above
+      : { boxShadow: "inset 0 -2px 0 0 " + ACCENT })   // landing below
+  : null)}
+```
+
+**Renumber the whole run — never swap a pair.** A swap cannot express "drop three rows up", and on a
+nullable order field it corrupts the sort: positions start null, so numbering only the two rows that
+moved leaves the rest null, and any "nulls last" comparator then throws every untouched row to the
+bottom the moment the user switches to that sort. Write `position = i + 1` for every row whose slot
+actually changed. The first reorder on a fresh list costs N writes; later ones cost the distance
+travelled.
+
+**Hold an optimistic order until the refetch lands.** The position writes are in flight while the
+records still carry their OLD numbers, so re-sorting on those throws the row back to where it was
+dragged from for a beat — which reads as the drag having failed. Apply `optimisticOrder` ahead of both
+sorts and clear it when the refetch resolves. Writes stay sequential (`await mutateAsync` per row, in
+order, stop on first failure — see [../datasources/writing.md](../datasources/writing.md#sequential-multi-row-writes-mutateasync));
+on failure, clear the override and refetch, because a half-applied renumber is worse than none.
+
+**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).

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

package/ui-ux-guidelines.md

@@ -719,6 +719,8 @@ Actively check for and reject these fingerprints of generic AI-generated interfa
 - **Relative timestamps:** "2 hours ago" via `date-fns/formatDistanceToNow`
 - **Truncate long text** with `truncate` or `line-clamp-2`, full value in `Tooltip`
 - **Sticky headers** for long tables
+- **Never render an affordance you have not wired.** A grip glyph that does not drag, a chevron that does not sort, a card that looks clickable and is not — the signifier IS the promise, and an unfulfilled one reads as a broken feature, not a missing one. Either wire it or delete it. (Observed 2026-09-09: a `GripVertical` shipped as decoration on every row of a reorderable list; users reported the list as "can't be reordered", not as "missing drag".)
+- **A control that is disabled by default is indistinguishable from a broken one.** If the only explanation lives in a `title` tooltip, nobody reads it — they file a bug. When a control depends on a mode the user has not chosen yet, prefer making the action *switch the mode and proceed* over greying it out. Disable only for genuine impossibility (permissions, first row can't move up), and when you do, say why in visible text rather than on hover. (Same 2026-09-09 report: reorder arrows were disabled until you switched the sort to Manual, which nothing on screen told you.)
 
 ---