softr-vibe-coding 1.5.1 → 1.6.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.
 
+## [1.6.0] - 2026-06-03
+- Document useNavigationBlocker for form-dirty navigation guards in Softr SPA mode
+
+## [1.5.2] - 2026-05-27
+- Document BLANK-guard convention for Airtable formulas — Airtable surfaces #ERROR! / #NaN! when arithmetic, date, or string operations touch a blank field and propagates the error through every downstream formula; add a quick-rule bullet calling out the failure modes (multiply/divide-by-blank, DATEADD on blank date), show the IF({field}, <expr>, BLANK()) and AND()-guarded shapes, note why explicit guards beat catch-all IFERROR (don't mask typos), and re-render the common-patterns block with guards applied to the date examples; bump to 1.5.2
+
 ## [1.5.1] - 2026-05-21
 - Expand the "formulas in create/update" anti-pattern to cover every read-only field type (rollup / aiText / lookup / createdTime / lastModifiedTime / autoNumber, not just formulas), document the silent all-or-nothing parser failure (Actions tab empty, enabled stays false, every other writable field in the same q.select is lost), cite the verified 2026-05-22 wig-details-page.jsx case (Wig Tag ID formula + Total client/worker rollups + Instrucciones aiText all shared with useRecordUpdate), and point at the bisection diagnostic; bump to 1.5.1
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softr-vibe-coding",
-  "version": "1.5.1",
+  "version": "1.6.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/airtable-automations.md

@@ -321,22 +321,31 @@ For Automation Scripts, your ONLY user-visible surfaces are `console.log()` (run
 For formula fields inside Airtable itself (NOT scripts). Quick rules:
 
 - **NEVER add comments inside Airtable formulas.** Airtable's formula engine doesn't have a comment syntax — anything that looks like a comment will fail to compile.
+- **Guard against blank inputs by default.** Airtable surfaces `#ERROR!` (or `#NaN!` for divide-by-blank) when arithmetic, date, or many string operations touch a blank field — `{A} * {B}` errors when either is blank, `{A} / {B}` errors when `{B}` is blank, `DATEADD({Start At}, 20, 'minutes')` errors when `{Start At}` is blank, and one upstream `#ERROR!` propagates through every downstream formula that references it. Wrap any formula whose inputs could be empty with an `IF()` guard returning `BLANK()` in the empty branch. Prefer explicit `IF()` / `AND()` guards over a catch-all `IFERROR(<expr>, BLANK())` — explicit guards keep intent readable and don't mask unrelated bugs (a typo'd field name silently returns blank instead of failing loudly). Reach for `IFERROR()` only when inputs come from genuinely uncontrolled sources.
+
+  ```
+  IF({Start At}, DATEADD({Start At}, 20, 'minutes'), BLANK())
+  IF(AND({Quantity}, {Price}), {Quantity} * {Price}, BLANK())
+  IF({Divisor}, {Numerator} / {Divisor}, BLANK())
+  ```
 - Reference fields by name with curly braces: `{Field Name}` (single field) or `{Other Table}` is not valid — formulas are scoped to the current table only.
 - Functions are case-insensitive (`IF` = `if`) but field names ARE case-sensitive.
 - Use `&` for concatenation, NOT `+` (the latter is numeric).
 - For conditional logic, prefer `IF()` nested or `SWITCH()` for many branches.
 
-Common patterns:
+Common patterns (blank-guards applied where inputs could be empty):
 
 ```
 IF({Status} = "Paid", "✓", "")
 
 CONCATENATE({First Name}, " ", {Last Name})
 
-DATETIME_FORMAT({Created}, 'YYYY-MM-DD')
+IF({Created}, DATETIME_FORMAT({Created}, 'YYYY-MM-DD'), BLANK())
 
 IF(AND({Amount} > 100, {Paid} = TRUE()), "VIP", "Standard")
 
+IF({Start At}, DATEADD({Start At}, 20, 'minutes'), BLANK())
+
 SWITCH({Tier},
   "gold", "Premium",
   "silver", "Standard",

package/references/anti-patterns.md

@@ -62,6 +62,7 @@ Run through this catalog before delivering any block. Every row is a violation o
 | Relying on `custom-code-header.html` (Softr → Settings → Custom Code → Code inside header) to apply brand fonts/colors INSIDE a Vibe Coding block | Vibe Coding blocks render inside a shadow DOM. CSS custom properties (`--brand-*`) pierce that boundary, but `html, body { font-family: ... !important }` rules **do not** — `<html>` and `<body>` don't exist inside the shadow root. Apply brand fonts/colors at the block's **own outermost wrapper** via inline style: `style={{ fontFamily: "'Manrope', system-ui, sans-serif", color: BRAND_INK }}` on the outer `<div>` so every descendant inherits brand defaults. Override per-element with explicit inline `fontFamily` (e.g., `"'Fraunces', Georgia, serif"` on h1/h2). Google `<link>` tags in the page head DO load `@font-face` globally — the fonts are available inside shadow DOM, they just need to be applied. |
 | Painting `backgroundColor: BRAND_CANVAS` on a Vibe Coding block's outer wrapper when `custom-code-header.html` already sets `body { background-color: var(--brand-canvas) !important }` | Don't double-paint. If the body bg is already the brand canvas, the block leaves its own backgroundColor unset and the page bg shows through. Painting the same color twice produces a visible seam — Softr's content wrapper sits between `<body>` and the Vibe Coding block, and the two backgrounds composite slightly differently due to sub-pixel rendering, transparency stacking, or wrapper paddings. Set fontFamily and color on the block's wrapper (those don't inherit cleanly through shadow DOM), but **leave backgroundColor unset** — let the page bg flow through. The exception: if the block needs a brand-tinted *section* (e.g., a card-style admin shell that's different from the page bg), paint that bg explicitly on its specific container, not on the outer wrapper. |
 | `document.getElementById(...)` / `document.querySelector(...)` to find an element inside the block — for example, a hidden `<input type="file">` triggered by a visible "Upload" button via `getElementById('myInput').click()` | Vibe Coding blocks render inside a shadow DOM. The global `document` traversal stops at the shadow boundary, so id/selector lookups for elements inside the block return `null`. The user-visible symptom is a control that does nothing — no error, no file picker, no focus, no scroll — because the chained `.click()` / `.focus()` / `.scrollIntoView()` was called on `null`. Use a **React `useRef`** instead: `var inputRef = useRef(null)`, then `<input ref={inputRef} />` and `<button onClick={function() { if (inputRef.current) inputRef.current.click(); }}>`. Refs hold direct node references and don't depend on DOM traversal, so they work regardless of which DOM tree the node lives in. This applies to every "trigger a hidden element" pattern: hidden file inputs, programmatic focus, scroll-into-view, `.click()` on a non-visible button. |
+| Using `window.addEventListener("beforeunload", ...)` as the only unsaved-changes guard in a form block | Softr is a SPA. Internal nav (Softr's nav bar, sidebar links, `<NavigationAction>`) changes the route via the client-side router — `beforeunload` only fires on full page unload (tab close, refresh, external link), so the warning silently misses every in-app navigation. Use `useNavigationBlocker(isDirty)` from `@/lib/use-navigation-blocker` instead; it covers SPA nav AND browser unload with one API. Softr's Vibe Coding bundler often wires this automatically when a form is detected as dirty — you only need to add it manually for advanced cases (multi-step forms, custom dirty tracking, blocking on non-form state). See [common-patterns.md](common-patterns.md#navigation-blocker-for-unsaved-changes). |
 
 ## Permissions
 

package/references/common-patterns.md

@@ -6,6 +6,7 @@ Small reusable patterns that come up across Vibe Coding blocks but don't warrant
 
 - [Cross-Page State with localStorage + URL Parameters](#cross-page-state-with-localstorage--url-parameters)
 - [Clipboard Copy Button](#clipboard-copy-button)
+- [Navigation Blocker for Unsaved Changes](#navigation-blocker-for-unsaved-changes)
 
 ## Cross-Page State with localStorage + URL Parameters
 
@@ -100,3 +101,63 @@ Usage:
 ```
 
 The `aria-label` is required because the button has no visible text, only an icon. Without it the button is not screen-reader accessible.
+
+## Navigation Blocker for Unsaved Changes
+
+Softr apps use SPA-mode client-side navigation — when a user clicks a link in Softr's nav bar, sidebar, or any `<NavigationAction>`, the route changes without a full page reload. The browser's standard `beforeunload` event only fires for tab close / refresh / browser back-forward / external nav, so the classic dirty-form warning misses every internal Softr click.
+
+Softr's `useNavigationBlocker` hook intercepts BOTH internal SPA navigation AND browser-level unload with a single API. Import it from `@/lib/use-navigation-blocker`.
+
+**Boolean form — simplest case:**
+
+```jsx
+import { useState } from "react";
+import { useNavigationBlocker } from "@/lib/use-navigation-blocker";
+
+export default function Block() {
+  var [isDirty, setIsDirty] = useState(false);
+
+  useNavigationBlocker(isDirty);
+
+  function handleFieldChange(newValue) {
+    setIsDirty(true);
+    /* ... update form state ... */
+  }
+
+  /* ... form rendering ... */
+}
+```
+
+**Callback form — when you need to read a ref without re-running on every render:**
+
+```jsx
+import { useRef } from "react";
+import { useNavigationBlocker } from "@/lib/use-navigation-blocker";
+
+export default function Block() {
+  var dirtyRef = useRef(false);
+
+  useNavigationBlocker(function() { return dirtyRef.current; });
+
+  function handleFieldChange() {
+    dirtyRef.current = true;
+    /* ... update local state without re-rendering the hook ... */
+  }
+
+  /* ... rest ... */
+}
+```
+
+The hook automatically handles:
+
+- Browser's "Leave site?" dialog on tab close / refresh / external nav.
+- Softr's in-app confirmation modal when the user clicks an internal Softr link or `<NavigationAction>`.
+- Letting navigation through if the user confirms; cancelling if they decline.
+
+**Most form blocks don't need to wire this manually** — Softr's Vibe Coding bundler often adds the blocker automatically when it detects form dirty state. You only need to add it explicitly for advanced cases:
+
+- Multi-step forms where the dirty state spans several panels.
+- Manual dirty tracking that doesn't go through standard form-state hooks.
+- Blocks where you want to block on something other than form dirtiness (e.g., a pending background upload).
+
+**Asking Softr to add the blocker automatically:** when generating or refining a form block in the Vibe Coding editor, you can prompt with "Block the navigation when the form is dirty" and Softr will wire `useNavigationBlocker` for you — useful when you don't want to write the import + hook call yourself.

package/references/quick-reference.md

@@ -18,6 +18,9 @@ import { useTextSetting, useImageSetting, useVideoSetting, useArraySetting,
          useVibeCodingBlockIconSetting, useNavigationSetting,
          useBooleanSetting } from "@/lib/editable-settings";
 
+// NAVIGATION GUARD (form unsaved-changes warning that also works on Softr's SPA nav)
+import { useNavigationBlocker } from "@/lib/use-navigation-blocker";
+
 // REACT
 import { useState, useEffect, useMemo, useCallback, useRef } from "react";
 
@@ -185,6 +188,18 @@ useEffect(function() {
 }, [result.hasNextPage, result.isFetchingNextPage, result.status, result.fetchNextPage]);
 ```
 
+## Navigation Blocker (unsaved-changes warning)
+
+```jsx
+// Boolean form: simplest case
+useNavigationBlocker(isDirty);
+
+// Callback form: reads from a ref without re-running on every render
+useNavigationBlocker(function() { return dirtyRef.current; });
+```
+
+Catches BOTH Softr's in-app SPA navigation (nav bar, sidebar, `<NavigationAction>`) AND browser unload (tab close, refresh, external links). A plain `window.addEventListener("beforeunload", ...)` does NOT catch Softr's in-app nav. See [common-patterns.md](common-patterns.md#navigation-blocker-for-unsaved-changes).
+
 ## Component Skeleton
 
 ```jsx