softr-vibe-coding 2.5.2 → 2.6.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.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softr-vibe-coding",
-  "version": "2.5.2",
+  "version": "2.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/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/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.)
 
 ---