softr-vibe-coding 2.14.3 → 2.14.5

package/CHANGELOG.md

@@ -4,6 +4,14 @@ 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.5] - 2026-10-07
+- Release 2.14.5
+- Document condition-based user groups over the MCP
+
+## [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/README.md

@@ -208,7 +208,12 @@ softr-vibe-coding/
 │   │                                 # alone, DATETIME create shape, offset paging;
 │   │                                 # OAuth grant per ticked workspace, email
 │   │                                 # senders, formulas fixed at creation, loop
-│   │                                 # counter, workflow time zone and publish state
+│   │                                 # counter, workflow time zone and publish state;
+│   │                                 # Oct 7 2026: condition-based user groups over
+│   │                                 # MCP (subject USER:<field id>, not USER:::),
+│   │                                 # list_users omits conditional membership,
+│   │                                 # reading userGroups in the preview iframe,
+│   │                                 # what __softr_current_user carries
 │   ├── browser-checks.md             # Checking a pushed block in a browser with
 │   │                                 # the agent-browser CLI (ask before installing):
 │   │                                 # preview cookie, shadow-DOM refs grepped in the

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/datasources/hubspot.md

@@ -452,7 +452,10 @@ page ([details](multi-datasource.md#one-connection--one-read-payload-the-union-o
   HubSpot: anyone who can edit that property there can grant the group's access.
 - **`application_list_users` is not a membership check.** It showed `userGroups: []` for every
   user, including members of condition groups that demonstrably applied (verified 2026-10-05).
-  Test membership by what the user can reach, e.g. preview as them against a group-gated block.
+  Test membership by what the user can reach, e.g. preview as them against a group-gated block, or
+  read their groups in the preview
+  ([how](../references/softr-mcp.md#testing-as-any-app-user-without-logins--the-preview-as-switcher);
+  same result on Softr Database, 2026-10-07).
 
 ## Audit trail
 

package/package.json

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

package/references/softr-mcp.md

@@ -19,7 +19,7 @@ The official Softr MCP server (`https://mcp.softr.io/mcp`) gives an AI assistant
 - [Vibe coding block tools](#vibe-coding-block-tools) — incl. [what the server enforces on a block's data endpoints](#what-the-server-enforces-on-a-blocks-data-endpoints)
 - [Adopting Studio-AI-generated code](#adopting-studio-ai-generated-code)
 - [Vibe coding gotchas (official)](#vibe-coding-gotchas-official)
-- [Application management tools](#application-management-tools) — incl. [testing as any user via "Preview as"](#testing-as-any-app-user-without-logins--the-preview-as-switcher)
+- [Application management tools](#application-management-tools) — incl. [condition-based user groups](#condition-based-user-groups) and [testing as any user via "Preview as"](#testing-as-any-app-user-without-logins--the-preview-as-switcher)
 - [Browsing integrations (external data sources)](#browsing-integrations-external-data-sources)
 - [Softr Database tools](#softr-database-tools)
 - [Workflows](#workflows)
@@ -536,14 +536,19 @@ verified on HubSpot on 2026-10-05, the same way.* There are two forms, and **the
   **It fails closed:** a user whose field is empty, or who has no record in the users' data source,
   gets 0 rows, and a by-id request for a record outside the condition returns 404 (on HubSpot;
   Softr Database answers HTTP 200 with an empty body).
+- **Do not confuse it with the user-group syntax.** A user group's condition names the user field
+  as its **subject**, `USER:<field id>`: one colon, no braces (verified 2026-10-07, see
+  [Condition-based user groups](#condition-based-user-groups)). A Source condition names it in the
+  **value**, `USER:::<field id>`: three colons. The user-group form returned HTTP 400 in a Source
+  condition (below); the Source-condition form has not been tried in a user group.
 - **Use AND between rules.** With one rule OR and AND behave the same, but a second rule added
   under OR widens access (2026-10-05).
 - **The braced user-field spellings fail.** On 2026-09-18, on Softr Database, eleven spellings were
   tried, including `{USER:::<fieldId>}`, `{USER:<fieldId>}` and `{USER:::FIELD:<fieldId>}`. Each
   silently matched nothing. All eleven had braces, so the braceless form is untested on Softr
   Database, not disproved. A subject of `USER:<fieldId>`, the syntax user-group rules use, returned
-  HTTP 400 "Field not found": the user field goes in the value, never the subject. No token for a
-  user group has been found.
+  HTTP 400 "Field not found": the user field goes in the value, never the subject. No token that
+  tests whether the user is in a group has been found.
 - Studio's conditional-filter UI offers the logged-in user's Email and Email-Domain, plus every
   users-table field once users sync from a data source (documented). For a value not listed here,
   pick it in a block's Source tab, save, and read `dataSources[].condition` back with
@@ -641,6 +646,37 @@ Combined with the database tools (`database_create` / `database_create_table` /
   no zone designator and nine fractional digits (`2026-09-09T22:34:11.157881061`). They were UTC, so
   read any older logged value as UTC, never as local time.
 
+### Condition-based user groups
+
+*Verified 2026-10-07 on Softr Database, with users synced from a Softr Database table and the user
+connection's field reference key set to `id`. The HubSpot version (2026-10-05) is in
+[../datasources/hubspot.md](../datasources/hubspot.md#user-sync).*
+
+- **`application_update_user_group` sets a group's condition.** It returned the condition exactly as
+  sent. This one, on a "Volunteer" group, tests two single-line text fields of the users table:
+
+  ```json
+  {
+    "logicalOperator": "AND",
+    "expressions": [
+      { "subject": { "field": "USER:YB2ot", "type": "TEXT" }, "operator": "IS_NOT_EMPTY", "value": [] },
+      { "subject": { "field": "USER:uo0TW", "type": "TEXT" }, "operator": "IS", "value": ["Active"] }
+    ]
+  }
+  ```
+
+- **The subject is `USER:<field id>`: one colon, no braces.** A block's Source condition uses a
+  different form, `USER:::<field id>` with three colons, and puts it in the value
+  ([Logged-in-user values in Source conditions](#logged-in-user-values-in-source-conditions)). Do not
+  copy one into the other.
+- **`application_list_users` does not show condition-based membership.** Right after the update, the
+  one user whose record matched (login email set, status Active) still listed `userGroups: []`. The
+  tool shows only manual memberships, such as a user added to Administrator through `userEmails`.
+  Softr evaluates conditions at runtime, so an empty `userGroups` there is not evidence that a
+  condition fails. HubSpot behaved the same way.
+- **Check membership by running the app as that user** and reading the groups the app gives them
+  ([how](#testing-as-any-app-user-without-logins--the-preview-as-switcher), below).
+
 ### Testing as any app user without logins — the "Preview as" switcher
 
 *Verified live 2026-09-18.* The `application_preview` link does not open the app directly: it opens a
@@ -666,6 +702,24 @@ passwords, no test accounts to create:
   `fetch('/studio/impersonate/<softrUserId>')` makes the preview run as that user. The id is the
   user's Softr id from `application_list_users`. It works from a fresh preview link, so it needs no
   Studio session in the browser.
+- **Read a user's groups from the app itself** (verified 2026-10-07, read-only). Mint a fresh
+  `application_preview` link and open it, run the impersonate call above, reload the app iframe,
+  then read `iframe.contentWindow.__softr_current_user.userGroups`.
+  - The link carries `?show-toolbar=true`, so the top document is the toolbar shell and the app runs
+    in `document.querySelector('iframe')` (the `#preview-iframe` of
+    [browser-checks.md](browser-checks.md)). `window.__softr_current_user` exists only in that
+    iframe's `contentWindow`. The top window has no user globals at all.
+  - To reload, set the iframe's `src` again with a fresh `t=<timestamp>` query parameter, after the
+    impersonate call.
+  - Observed group names: a user who matched the Volunteer condition above read
+    `["Logged in users", "All users", "Volunteer"]`; a user with no login email read
+    `["Logged in users", "All users"]`.
+- **`window.__softr_current_user` carries only `name`, `email`, `avatar` and `userGroups`**
+  (verified 2026-10-07). None of the users-table record's other fields were there, on a users table
+  with notes, phone and emergency-contact fields. For a privacy review: syncing a users table does
+  not by itself expose the record's other fields through this global. A block can still ask for
+  them with `useCurrentUser({ properties })`
+  ([../datasources/reading.md](../datasources/reading.md#current-user)).
 - **Press the preview's own `#refresh-button` after a push.** An open preview kept serving the old
   block version until it was pressed (verified 2026-10-05). Minting a fresh link does too (see the
   version note above).