softr-vibe-coding 1.1.0

package/datasources/writing.md

@@ -0,0 +1,256 @@
+# Writing Data
+
+Record mutations, file uploads, linked record format, and cross-table operations.
+
+## Table of Contents
+
+- [How Actions Work (Studio's Actions Tab)](#how-actions-work-studios-actions-tab)
+- [Record Mutations](#record-mutations)
+- [File Uploads](#file-uploads)
+- [Linked Record Format for Mutations](#linked-record-format-for-mutations)
+- [Writing to Field Types](#writing-to-field-types)
+- [Cross-Table Operations](#cross-table-operations)
+
+## How Actions Work (Studio's Actions Tab)
+
+Every Vibe Coding block in Softr Studio has an **Actions tab** alongside Chat / Source / Content / Visibility. The Actions tab is a **read-only inspector** of the Create / Update / Delete operations the platform inferred from your code.
+
+Each Action's "FIELDS USED" list mirrors the aliases in your `q.select()` mapping. Actions are not a separately-managed system:
+
+- The platform parses your block's source on every save
+- For each `useRecordCreate` / `useRecordUpdate` / `useRecordDelete` hook, it auto-derives a corresponding Action
+- The fields list comes from your `q.select` aliases used in the mutation payload
+- Cosmetic AND structural code edits both update the Action automatically -- you do NOT need to re-prompt the AI assistant after editing code
+- There is no manual delete control; to remove an Action, remove the mutation hook from the code
+
+The `enabled` boolean on a mutation hook is a combined signal — it's `true` only when BOTH conditions are met:
+
+1. **The Action was successfully derived from the code** (parser side). Causes of failure here:
+   - The hook is declared after a conditional `return`, so it doesn't run on every render
+   - `q.select` is built dynamically rather than from string-literal mappings
+   - The block hasn't been connected to a data source yet
+   - `useRecordUpdate.mutate()` is called with a flat payload (`{ recordId, status: ... }`) instead of the nested shape (`{ recordId, fields: { status: ... } }`) -- the parser ignores flat field references, so no Action gets created
+
+2. **The currently logged-in (or previewed-as) user has permission to perform the action on the data source** (permissions side). Per the official Softr docs, "`enabled` reflects user permissions." So even with a perfectly-derived Action, `enabled` will be `false` if the previewed user's group lacks write access to the connected table.
+
+**Critical debugging implication:** when `enabled` stays `false` and Studio's Actions tab DOES show the action listed (parser succeeded), the cause is permissions — not code. Three places to check, in order:
+
+- **Block's Visibility tab** (right panel) — confirm the previewed user's group is allowed to see / interact with this block.
+- **Studio → Users → Data Restrictions → Global data restrictions** — an app-wide layer that limits what data users can interact with across the whole app, applied on top of block-level settings. Easy to miss because it's under Users (not on the block). If a Global restriction exists on the target table for the user's group, every mutation against that table in every block silently fails — no error, just `enabled: false`. Open this tab and either confirm there are no restrictions or that the worker / target group has the access they need.
+- **Data-source connection PAT scope** — if the PAT was granted with read-only scope, every write fails regardless of UI permissions. Reconnect with write scope if needed.
+
+Verified by direct experiment (April 2026): adding a new field to `q.select` + `mutate()` payload and saving the code propagates to the Actions tab automatically and writes successfully to the database with no manual configuration.
+
+Because the parser only inspects your hooks and `q.select` mappings (not the JSX tree), inputs rendered conditionally inside `<Dialog>`, `<Sheet>`, or any subtree gated by state are still bound to the Action correctly. Verified by direct experiment, May 2026.
+
+## Record Mutations
+
+All mutation hooks expose an `enabled` boolean. You must check it before rendering any mutation UI or calling the mutate function.
+
+### useRecordCreate
+
+```jsx
+import { useRecordCreate, q } from "@/lib/datasource";
+import { toast } from "sonner";
+
+var createRecord = useRecordCreate({
+  fields: q.select({ name: "FIELD_ID1", email: "FIELD_ID2" }),
+  onSuccess: function(newRecord) { toast.success("Created!"); },
+  onError: function(error) { toast.error(error.message); },
+});
+
+// Usage (gate on enabled):
+if (createRecord.enabled) {
+  createRecord.mutate({ name: "Jane", email: "jane@example.com" });
+}
+```
+
+### useRecordUpdate
+
+```jsx
+import { useRecordUpdate, q } from "@/lib/datasource";
+
+var updateRecord = useRecordUpdate({
+  fields: q.select({ status: "FIELD_ID1" }),
+  onSuccess: function(updatedRecord) {
+    refetch().then(function() { toast.success("Updated!"); });
+  },
+  onError: function(error) { toast.error(error.message); },
+});
+
+// Usage -- MUST use recordId, NOT id, AND fields MUST be nested:
+updateRecord.mutate({
+  recordId: "RECORD_ID",
+  fields: { status: "active" },
+});
+```
+
+#### CRITICAL: Two parser requirements for `useRecordUpdate`
+
+Softr's Action parser is strict about both the **method name** and the **payload shape**. Get either wrong and the Action is never derived, `enabled` stays `false`, and any UI gated on it silently does nothing — no error, no warning, console just shows `enabled: false, error: null, status: "idle"`.
+
+**Requirement 1 — Call `.mutate()`, NOT `.mutateAsync()`.** The parser scans for the literal `.mutate(` token to detect mutation call sites. `.mutateAsync()` runs fine at runtime (it's just a Promise wrapper), but the parser ignores it and no Update Action gets created. Pass per-call success/error handlers as the second argument (react-query convention):
+
+```jsx
+// CORRECT — parser sees `.mutate(`, derives the Action
+updateRecord.mutate(
+  { recordId: id, fields: { status: optionId } },
+  {
+    onSuccess: function() { toast.success("Saved"); },
+    onError: function(err) { toast.error(err.message); },
+  }
+);
+
+// WRONG — parser ignores `.mutateAsync(`, Action never created
+updateRecord.mutateAsync({ recordId: id, fields: { status: optionId } })
+  .then(function() { toast.success("Saved"); });
+```
+
+**Requirement 2 — Payload must be `{ recordId, fields: {...} }` — not flat.** Field values must be nested inside a `fields: {...}` object. The flat form (`mutate({ recordId, status: "active" })`) can succeed at runtime, but the parser doesn't see field references inside it, so no Action is derived:
+
+```jsx
+// CORRECT
+updateRecord.mutate({ recordId: id, fields: { status: optionId } }, { onSuccess, onError });
+
+// WRONG — Action parser ignores this, hook stays disabled
+updateRecord.mutate({ recordId: id, status: optionId }, { onSuccess, onError });
+```
+
+Verified by direct experiment (May 2026): Softr's Studio AI assistant emits both `.mutate()` AND the nested payload shape — and that combination is what produces a derived Update Action. Switching either back to its alternative form (`.mutateAsync()` or flat payload) disables the hook.
+
+### useRecordDelete
+
+```jsx
+import { useRecordDelete } from "@/lib/datasource";
+
+var deleteRecord = useRecordDelete({
+  onSuccess: function(result) {
+    refetch().then(function() { toast.success("Deleted!"); });
+  },
+  onError: function(error) { toast.error(error.message); },
+});
+
+// Usage -- pass just the string, NOT an object:
+deleteRecord.mutate("RECORD_ID");
+```
+
+### Three q.select() Mappings Pattern
+
+For blocks that read, create, and update, use separate mappings:
+
+```jsx
+// 1. READ -- includes everything (formulas, lookups, linked records)
+var select = q.select({
+  name: "FIELD_1", email: "FIELD_2",
+  score: "FORMULA_FIELD",       // read-only OK here
+  department: "LOOKUP_FIELD",   // read-only OK here
+});
+
+// 2. CREATE -- only writable fields
+var createFields = q.select({ name: "FIELD_1", email: "FIELD_2" });
+
+// 3. UPDATE -- only writable fields that can be edited
+var updateFields = q.select({ name: "FIELD_1", email: "FIELD_2" });
+```
+
+## File Uploads
+
+```jsx
+import { useUpload } from "@/lib/datasource";
+
+var upload = useUpload();
+
+// Single file:
+upload.uploadAsync(file).then(function(results) {
+  var result = results[0];
+  if (result.status === "completed") {
+    // result.url = uploaded file URL, result.file.name = original filename
+  }
+});
+
+// Combine with record creation:
+upload.uploadAsync(file).then(function(results) {
+  var result = results[0];
+  if (result.status === "completed") {
+    createRecord.mutate({
+      name: "Document",
+      attachment: { filename: result.file.name, url: result.url },
+    });
+  }
+});
+```
+
+## Linked Record Format for Mutations
+
+```jsx
+// CORRECT -- Array of { id } objects
+createRecord.mutate({
+  parentAccount: [{ id: "RECORD_ID_1" }],
+  teamMembers: [{ id: "MEMBER_1" }, { id: "MEMBER_2" }],
+});
+
+// WRONG -- Plain string or array of strings
+parentAccount: "RECORD_ID_1"           // Won't work
+teamMembers: ["MEMBER_1"]              // Won't work
+```
+
+## Writing to Field Types
+
+Different Softr field types accept different value shapes in mutation payloads. The shape returned when you READ a field is often different from the shape you must SEND when you WRITE.
+
+### Dropdown / Single Select (Softr Database)
+
+Write the option's UUID as a **plain string**, not an object:
+
+```jsx
+// CORRECT -- plain string UUID
+createRecord.mutate({
+  status: "822b8d69-3af4-47b4-90eb-3a80c5d1b85c",
+});
+
+// WRONG -- object form (returned on read, but rejected on write)
+createRecord.mutate({
+  status: { id: "822b8d69-3af4-47b4-90eb-3a80c5d1b85c", label: "Active" },
+});
+
+// WRONG -- display label
+createRecord.mutate({
+  status: "Active",
+});
+```
+
+Option UUIDs are stable. Three ways to retrieve them:
+
+- **AI scaffolding** -- Softr's AI assistant in Studio inlines them automatically into `<SelectItem value="...">` when generating a form
+- **Network inspector** -- DevTools -> Network -> filter `tablespace-with-tables` returns the full `choices` array for any SELECT field (see [fields.md](fields.md#field-inspector-block) for the full technique). Pasting this JSON into an AI assistant chat is the most reliable way to share UUIDs without transcription errors.
+- **Runtime scan** -- learn them at runtime from already-loaded records (useful when the block must work in environments where UUIDs are not known at code time)
+
+Verified by direct experiment (April 2026) for `useRecordCreate`. The same pattern is expected to apply to `useRecordUpdate` but has not been independently verified.
+
+### Linked Record
+
+Array of `{ id }` objects. See "Linked Record Format for Mutations" above.
+
+### Text / Email / URL / Phone
+
+Plain string. To clear a value, both `null` and `""` work for Softr Database text fields (verified by direct experiment, May 2026, for `useRecordUpdate`). Behavior on other data sources has not been independently verified.
+
+## Cross-Table Operations
+
+`useRecordCreate`, `useRecordUpdate`, and `useRecordDelete` only work with the block's configured datasource. To write to a different table, use the **Softr Database REST API** via `fetch()`:
+
+**Base URL:** `https://tables-api.softr.io/api/v1/databases/{databaseId}/tables/{tableId}/records`
+
+**Authentication:** `Softr-Api-Key` header with a Personal Access Token.
+
+**Create:** POST with `{ fields: { fieldId1: "value1" } }`
+**Read:** GET with `?limit=200&fieldNames=true`
+**Update:** PATCH `/{recordId}` with `{ fields: { fieldId1: "newValue" } }`
+
+Notes:
+- API key is exposed in client-side code -- acceptable for internal portals only
+- When updating linked records or multi-selects, read existing values first, merge, then write
+- Use `fieldNames=true` on GET for human-readable field names
+- Rate limits: Reads 40 req/s, Writes 30 req/s
+
+Verified by direct experiment (May 2026): POST to this endpoint with field IDs as keys writes successfully, returning HTTP 200 and the full record JSON. The endpoint uses the same field-ID format and the same value shapes as `useRecordCreate` -- plain string UUID for dropdown writes; the response returns the dropdown value as a `{id, label}` object (matching the read shape).

package/datasources/xano.md

@@ -0,0 +1,37 @@
+# Xano
+
+## Overview
+Xano is a no-code backend-as-a-service (BaaS) built on PostgreSQL. Available on Professional plans and above.
+
+## Connection Setup
+1. In your Xano workspace, enable the **Database Connector** add-on.
+2. Note the public IP address and credentials (Host, User, Password) from the Database Connector settings.
+3. In the Softr admin, go to your data source settings and select Xano.
+4. Enter the credentials: Host, User, and Password.
+5. Use **Full Access** credentials (recommended) for read/write, or **Read-Only** for display-only apps.
+6. **Whitelist Softr IP addresses** in your Xano firewall settings:
+   - `3.120.79.212`
+   - `3.123.159.186`
+   - `52.58.246.121`
+7. Once connected, all workspaces and tables in that Xano instance are available.
+
+## Vibe Coding Field IDs
+Use the Field Inspector block to determine exact field IDs for this data source.
+
+## Supported Fields
+Field support follows PostgreSQL column types since Softr connects via direct database access. Standard column types (text, integer, boolean, timestamp, etc.) are writable. Computed/generated columns are read-only.
+
+## Rate Limits
+No Softr-imposed rate limits. Xano handles concurrency at the database level. Unlimited records and unlimited concurrent users.
+
+## Gotchas
+- **Direct database access, not API.** Softr connects to Xano's PostgreSQL database directly via the Database Connector. It does NOT go through Xano's custom API endpoints. Business logic in Xano API stacks will not execute on Softr reads/writes.
+- **Database Connector must be enabled.** This is a separate add-on in Xano -- the connection will fail without it.
+- **IP whitelisting is required.** If you skip whitelisting the three Softr IPs, connections will be refused.
+- **Full Access vs Read-Only credentials** determine whether Softr can write data. Choose based on your use case.
+
+## Best For
+- Scalable applications with complex backend logic in Xano
+- Apps that need unlimited records and concurrent users
+- Projects where Xano handles business logic via API stacks and Softr provides the frontend
+- Teams wanting a dedicated backend with PostgreSQL power and a no-code UI layer

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "softr-vibe-coding",
+  "version": "1.1.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"
+  },
+  "files": [
+    "bin/",
+    "SKILL.md",
+    "ui-ux-guidelines.md",
+    "references/",
+    "datasources/",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "claude-skill",
+    "softr",
+    "vibe-coding",
+    "no-code",
+    "jsx",
+    "react"
+  ],
+  "homepage": "https://github.com/leo-softr/Softr-Vibe-Coding-Block-Claude-Skill#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leo-softr/Softr-Vibe-Coding-Block-Claude-Skill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/leo-softr/Softr-Vibe-Coding-Block-Claude-Skill/issues"
+  },
+  "author": "leo-softr <leo@softr.io>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/references/advanced-integrations.md

@@ -0,0 +1,69 @@
+# Advanced Integrations
+
+Patterns for embedding third-party libraries that ship their own global CSS inside a Softr Vibe Coding block without style bleed.
+
+## CSS Isolation via Shadow DOM
+
+**Problem:** Third-party libraries ship CSS with generic selectors like `.marker`, `.editor`, `.btn`. Inside a Softr page, those selectors bleed into the rest of the page or get clobbered by Softr's own styles. Scoping manually is impractical.
+
+**Solution:** Mount the library inside a **Shadow DOM** attached to a host element. The shadow root is a fully isolated DOM subtree -- the library's CSS cannot leak out, and Softr's styles cannot leak in. React renders the host wrapper; the library lives inside the shadow.
+
+```jsx
+import { useEffect, useRef } from "react";
+
+export default function Block() {
+  var hostRef = useRef(null);
+
+  useEffect(function() {
+    var host = hostRef.current;
+    if (!host || host.shadowRoot) return; /* already initialized */
+
+    var shadow = host.attachShadow({ mode: "open" });
+
+    /* Inject the library's CSS inside the shadow */
+
+    /* Option A: external stylesheet from CDN */
+    var link = document.createElement("link");
+    link.rel = "stylesheet";
+    link.href = "https://cdn.example.com/somelib/style.css";
+    shadow.appendChild(link);
+
+    /* Option B: inline <style> for custom overrides */
+    var style = document.createElement("style");
+    style.textContent = ".marker { color: red; }";
+    shadow.appendChild(style);
+
+    /* Create the container where the library mounts */
+    var innerDiv = document.createElement("div");
+    innerDiv.id = "lib-root";
+    innerDiv.style.width = "100%";
+    innerDiv.style.height = "500px";
+    shadow.appendChild(innerDiv);
+
+    /* Initialize the library against innerDiv */
+    // var map = L.map(innerDiv).setView([0, 0], 2);
+    // var editor = new TinyMCE({ target: innerDiv });
+  }, []);
+
+  /* To query elements inside the shadow later: */
+  // var el = hostRef.current.shadowRoot.getElementById("lib-root");
+
+  return <div ref={hostRef} style={{ width: "100%" }} />;
+}
+```
+
+## Key Points
+
+- Use `attachShadow({ mode: "open" })`. The `open` mode lets you access the shadow later via `host.shadowRoot`. Always use `open`.
+- **Guard against double-initialization.** React re-renders (and StrictMode) can fire the effect twice. Check `if (host.shadowRoot) return;` before calling `attachShadow` -- it throws if called on an element that already has a shadow root.
+- **Query inside the shadow** via `host.shadowRoot.getElementById(...)` or `.querySelector(...)`. `document.getElementById` will NOT find elements inside a shadow root.
+- **CSS is fully isolated in both directions.** Softr's fonts, resets, and utility classes do not reach inside. If you need Softr's font inside the shadow, redeclare it in the injected `<style>`.
+- **Events bubble out** of the shadow root normally (click, input, etc.), so React event handling on the host still works for most libraries.
+
+## When NOT to Use Shadow DOM
+
+If the library is React-native (shadcn, Recharts, lucide-react) and uses inline styles or scoped classes, skip the shadow -- it adds complexity for no benefit. Reserve this pattern for libraries that inject global CSS.
+
+## Libraries Where This Pattern Saves Hours
+
+Leaflet, Mapbox GL, TinyMCE, Quill, CKEditor, FullCalendar, Grapesjs, Froala, and any CDN-distributed widget from a non-React world.