softr-vibe-coding 2.14.3 → 2.14.4

package/CHANGELOG.md

@@ -4,6 +4,10 @@ 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.14.4] - 2026-10-07
+- Release 2.14.4
+- Add the Safari focus rule to the Combo reference
+
 ## [2.14.3] - 2026-10-07
 - Release 2.14.3
 - Document that the REST API proxy is not access control

package/SKILL.md

@@ -94,7 +94,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)
+   - **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). Opening a Combo moves focus into it (the search box, or the trigger on a click-only list), because Safari does not focus a clicked button. Escape on an open list closes only the list ([Move focus into the Combo when it opens](references/searchable-dropdown.md#move-focus-into-the-combo-when-it-opens))
    - App page with Softr navigation: **no shadcn `<Dialog>` / `<Sheet>`** — its overlay is z-50, under Softr's top bar (z-index 800), and it portals out of the shadow root. Use the in-block modal (`fixed inset-0 z-[1000]`, rendered as a sibling of the block's `@container` wrapper, with its own Escape, focus trap, scroll lock and focus return) in [references/common-patterns.md → A modal above Softr's bars](references/common-patterns.md#a-modal-above-softrs-bars) (measured live 2026-10-06)
    - No clipping class (`overflow-hidden`, `overflow-*-auto`, `truncate`, `line-clamp-*`) on any element that contains a `Combo` — its panel is absolutely positioned in local DOM, so a clipping `<td>` cuts the menu to the row's height; bound an over-wide chip at the chip (`min-w-0 truncate`), and never `scrollIntoView` inside the panel. See [references/searchable-dropdown.md](references/searchable-dropdown.md#the-four-things-that-will-bite-you), item 4
    - Any **Print** control opens a **new window with its own document** — `window.open` straight from the click, an escaped standalone HTML printout written into it, `print()` once its stylesheets, fonts and images are in, the button disabled until the data has fully loaded. No `window.print()` on the Softr page, no in-page print view (Hard Constraint 28). See [references/printing.md](references/printing.md)
@@ -183,7 +183,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, Softr navigation variables (`--nav-height` etc.), container-query syntax | [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) |
+| 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, focus moved into the Combo on open (Safari does not focus a clicked button) and Escape that closes only the list | [references/searchable-dropdown.md](references/searchable-dropdown.md) |
 | **Printing** anything from a block — always a new window/tab holding its own document, never `window.print()` on the page or an in-page print view: the escaped HTML builder, pop-up-safe opening from the click, print-when-ready (stylesheets, fonts and images, capped), Print disabled until the data has loaded, the `?print=1` deep link from another page, paper layout (shared `<colgroup>`, `vertical-align: middle`, tick boxes) | [references/printing.md](references/printing.md) |
 | Small reusable patterns — `localStorage` cross-page state, clipboard copy button, measuring the block's own width (not the window's), clearing Softr's sticky top bar and phone tab bar, an in-block modal above Softr's bars (instead of shadcn `Dialog`) | [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) |

package/package.json

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

@@ -329,6 +329,58 @@ the optional *create* row — so arrow-key navigation has one index to walk. Cla
 index (`Math.min(active, rows.length - 1)`): filtering shrinks the list under the highlight.
 Keep the highlighted row in view by scrolling the list only (rule 3 of item 4 above).
 
+## Move focus into the Combo when it opens
+
+When the panel opens, the Combo moves focus into itself: to the search box if it has one,
+otherwise to the trigger. Do not count on the click to do it. **Safari (macOS and iPadOS) and
+Firefox on macOS do not focus a `<button>` when it is clicked** (Chrome does), so on a click-only
+Combo focus stays in whatever field had it, usually the text input above it in a form. Two things then
+break at once: the keys the user types land in that input, and Escape goes past the Combo to the
+next listener. Inside the [in-block modal](common-patterns.md#a-modal-above-softrs-bars), that
+listener closes the modal or asks to discard the typed input, with the list still open.
+
+```jsx
+useEffect(
+  function () {
+    if (!open) return;
+    if (searchable) {
+      if (inputRef.current) inputRef.current.focus({ preventScroll: true });
+    } else if (triggerRef.current) {
+      triggerRef.current.focus({ preventScroll: true });
+    }
+  },
+  [open, searchable]
+);
+```
+
+A click-only list is then driven from the trigger: ↑ ↓ move the highlight, Enter picks, Escape
+closes. Give that trigger `role="combobox"` with `aria-activedescendant` pointing at the
+highlighted row, because `aria-activedescendant` is not valid on a plain button.
+`preventScroll` is there for the same reason as on the search box (rule 3 of item 4).
+
+**Escape closes the list and nothing else.** While the list is open, the Combo's keydown
+handler calls `e.preventDefault()` and `e.stopPropagation()`, closes the list and puts focus
+back on the trigger. React's handler on the Combo root runs inside the shadow root, before the
+event reaches `document`. The in-block modal's document listener returns early on
+`e.defaultPrevented`, so the modal stays open and clean. Either guard alone covers that modal,
+but keep both: another document-level listener may not check `defaultPrevented`.
+
+**To reproduce Safari in any browser,** focus the text field before the Combo, call `.click()`
+on the trigger from the console (a synthetic click does not move focus either), and read
+`activeElement` on the block's shadow root. It must be the search box or the trigger. Test
+typing with real key events. A browser-automation "type" action that inserts text without key
+events drops it into the last focused text field, which makes a correct Combo look broken.
+
+**The incident: Lane County Diaper Bank, 2026-10-07.** A browser check reported that in B4's New
+partner modal, letters typed after opening the click-only "Partner type" list went into
+Organization name, and Escape then showed the modal's "Discard your changes?" strip while the
+list stayed open. Part of that report came from the test tool, whose "type" action wrote into the
+last focused text field. But the code audit it prompted found the real gap: every copy of the
+component moved focus on open only when the list was searchable. On Safari, where a click leaves
+focus where it was, a click-only list never got the keyboard. Eight of the fifteen blocks had
+it. Chrome hid it, because there the click itself focuses the trigger. The effect above fixed
+all eight, rechecked on every page with a synthetic click and real key presses.
+
 ## Variants worth having
 
 - **`bare`** — inline-editor mode. No border, no fill; `triggerContent` (a status chip, a
@@ -375,7 +427,12 @@ Everything else — the trigger, the card, the rows — stays flat.
       on app pages inside Softr's top bar and phone tab bar
 - [ ] Keyboard: ↑ ↓ Enter Esc Tab; the active row kept visible by scrolling the list only
       (never `scrollIntoView`), and the search box focused with `preventScroll`
+- [ ] Opening moves focus into the Combo: the search box, or the trigger on a click-only
+      list, because Safari does not focus a clicked button. Escape on an open list calls
+      `preventDefault` + `stopPropagation` and closes only the list
+      ([Move focus into the Combo when it opens](#move-focus-into-the-combo-when-it-opens))
 - [ ] `aria-haspopup="listbox"`, `aria-expanded`, `role="listbox"` / `role="option"`,
-      `aria-selected`, and an `aria-label` on the trigger
+      `aria-selected`, and an `aria-label` on the trigger; a click-only trigger that carries
+      `aria-activedescendant` also gets `role="combobox"`
 - [ ] Loading and empty states (`"Nothing matches that."`)
 - [ ] No `@/components/ui/select` import anywhere in the file