softr-vibe-coding 1.1.0

package/datasources/airtable.md

@@ -0,0 +1,91 @@
+# Airtable
+
+## Overview
+Popular spreadsheet-database hybrid used as a data source for Softr. Requires a Basic plan or higher in Softr.
+
+## Connection Setup
+1. In Softr admin, go to Data Sources and select Airtable.
+2. Authenticate via OAuth or paste a Personal Access Token (PAT).
+3. Select the base and table to connect.
+4. Optionally connect to a specific View to inherit that view's filters and sort order.
+
+**Always recommend PAT over OAuth.** OAuth connections are limited to 5 requests/second. PAT connections allow up to 50 requests/second.
+
+## Vibe Coding Field IDs
+q.select() uses **human-readable Airtable column names**, NOT internal `fld...` IDs.
+
+```jsx
+// CORRECT - use the column name exactly as it appears in Airtable
+q.select({ name: "First Name" })
+q.select({ name: "Email Address" })
+
+// WRONG - internal field IDs do not work
+q.select({ name: "fldqSabBeD6RkpTtp" })
+```
+
+Column names are case-sensitive and must match the Airtable header exactly.
+
+**Verified by direct experiment, May 2026:** aliases mapped to `fld...` IDs are silently omitted from the record's `fields` object -- only column-name aliases populate. Airtable's native API supports both formats; Softr's wrapper restricts to names.
+
+### Maintainability gotcha
+
+Renaming a column in Airtable breaks the block **silently**. The alias just stops resolving -- no error, no warning, the field becomes `undefined`. Three mitigations, in order of effort:
+
+1. **Document the field ID alongside the name** in `q.select()` comments. A grep for the field ID then finds every block affected by a rename:
+
+   ```jsx
+   var select = q.select({
+     firstName: "First Name",  // fld6vaQi4ZHxxwP0y
+     lastName: "Last Name",    // fldIQDfFXwBvtSCQp
+   });
+   ```
+
+2. **Centralize `q.select()` mappings** in a single helper block (see [references/helper-blocks.md](../references/helper-blocks.md)). One rename then touches one file rather than every block that reads the table.
+
+3. **Avoid renaming columns mid-project** -- use Airtable's Description field for clarification instead.
+
+## Supported Fields
+
+| Field Type           | Writable  | Notes |
+|----------------------|-----------|-------|
+| Text                 | Yes       | |
+| Long Text            | Yes       | |
+| Number               | Yes       | |
+| Date                 | Yes       | |
+| Checkbox             | Yes       | |
+| Single Select        | Yes       | Returns as `{ label, id }` object. Use `getFieldValue()` helper to extract the label. |
+| Multiple Select      | Yes       | Array of `{ label, id }` objects |
+| Attachment           | Yes       | Array of `{ filename, id, type, url }` objects |
+| URL                  | Yes       | |
+| Email                | Yes       | |
+| Phone                | Yes       | |
+| Linked Record        | Read/Write | Returns as `{ label, id }` objects |
+| Rollup               | Read-only | |
+| Formula              | Read-only | |
+| Lookup               | Read-only | |
+| Computed             | Read-only | |
+| Created Time         | Read-only | |
+| Modified Time        | Read-only | |
+| Created By           | Read-only | |
+| Last Modified By     | Read-only | |
+
+## Rate Limits
+- **Airtable Free plan:** 1,000 API calls/month
+- **Airtable Team plan:** 100,000 API calls/month
+- **Airtable Business plan:** Unlimited API calls
+- **OAuth connections:** 5 requests/second
+- **PAT connections:** 50 requests/second
+
+Mitigation: Use PAT authentication. Cache data where possible. Avoid unnecessary re-fetches.
+
+## Gotchas
+- **Single Select returns an object**, not a string. `record.fields["Status"]` gives `{ label: "Active", id: "sel..." }`, not `"Active"`. Use `getFieldValue()` or access `.label` directly.
+- **Attachments are arrays**, even for a single file. Always index into the array: `record.fields["Photo"][0].url`.
+- **Linked records are objects** with `{ label, id }` structure, not plain text.
+- **View connections** apply Airtable-side filters and sorts before data reaches Softr. This is useful for pre-filtering but means the Softr block only sees the view's subset.
+- **Column names are case-sensitive.** `"First name"` and `"First Name"` are different.
+
+## Best For
+- Teams already managing data in Airtable
+- Apps with moderate traffic (under 200-300 concurrent users)
+- Projects needing a flexible schema with rich field types

package/datasources/bigquery.md

@@ -0,0 +1,36 @@
+# BigQuery
+
+## Overview
+BigQuery is Google's serverless data warehouse for large-scale analytics. Available on Business and Enterprise plans only.
+
+## Connection Setup
+1. In Google Cloud Platform (GCP), ensure you have a project with the BigQuery API enabled and at least one dataset created.
+2. Create a **service account** in GCP with BigQuery read permissions (e.g., BigQuery Data Viewer role).
+3. Generate and download a JSON key for the service account.
+4. In the Softr admin, go to your data source settings and select BigQuery.
+5. Upload or paste the GCP service account credentials.
+
+## Vibe Coding Field IDs
+Use the Field Inspector block to determine exact field IDs for this data source.
+
+## Supported Fields
+BigQuery is **primarily read-only** in Softr. You can query and display data but cannot submit forms or edit records through the Softr interface.
+
+Standard BigQuery column types (STRING, INTEGER, FLOAT, BOOLEAN, TIMESTAMP, DATE, RECORD, etc.) are readable.
+
+## Rate Limits
+Subject to BigQuery API quotas set in GCP. Standard limits include concurrent query slots and daily query volume. Monitor usage in the GCP console.
+
+## Gotchas
+- **Read-only.** BigQuery in Softr is not designed for form submissions or record editing. Use it for display, dashboards, and reporting only.
+- **No 2-way user sync.** Unlike most other data sources, BigQuery does not support Softr's user sync feature.
+- **Custom SQL queries are supported.** Use the built-in query editor in the Softr admin to write SQL SELECT statements for advanced data retrieval and joins.
+- **"Access Denied" errors** are common when working with external tables or cross-project datasets. Check that the service account has the correct GCP permissions on the specific dataset and tables.
+- **GCP prerequisite.** You must have a GCP project with BigQuery enabled and a dataset created before connecting to Softr. Softr cannot create GCP resources.
+- **Query costs.** BigQuery charges by data scanned. Poorly optimized queries on large datasets can incur significant costs. Use column selection and filters to limit scanned data.
+
+## Best For
+- Analytics dashboards displaying warehouse data
+- Executive reporting portals with aggregated metrics
+- Partner insights portals with filtered views of shared data
+- Any scenario where large-scale read-only data needs a no-code frontend

package/datasources/clickup.md

@@ -0,0 +1,82 @@
+# ClickUp
+
+## Overview
+ClickUp is a project and task management platform. Available on Professional plans and above.
+
+## Connection Setup
+1. In the Softr admin, go to your data source settings and select ClickUp.
+2. Authenticate via OAuth -- you will be redirected to ClickUp to authorize your workspace.
+3. Navigate to the desired Space > Folder > List. Each block connects to one List at a time.
+
+## Vibe Coding Field IDs
+Use the Field Inspector block to determine exact field IDs for this data source.
+
+## Supported Fields
+
+**Writable fields:**
+
+| Field Type     | Notes |
+|----------------|-------|
+| Number         | |
+| Text           | |
+| Long Text      | |
+| Dropdown       | |
+| Date           | |
+| Money          | |
+| Website        | |
+| Rating         | |
+| Status         | ClickUp-native status field |
+| Priority       | ClickUp-native priority field |
+| Checkbox       | |
+| Relationship   | Linked tasks |
+| Email          | |
+| Phone          | |
+| Label          | |
+| Short Text     | |
+
+**Read-only fields:**
+
+| Field Type           | Notes |
+|----------------------|-------|
+| Formula              | |
+| People               | |
+| Tasks                | |
+| Voting               | |
+| Users                | |
+| Date Created         | Auto-set by ClickUp |
+| Date Updated         | Auto-set by ClickUp |
+| Assignees            | |
+| Signature            | |
+| Files                | |
+| Automatic Progress   | |
+| Location             | |
+
+**Not supported:**
+
+| Field Type | Reason |
+|------------|--------|
+| Rollup     | Not exposed by the ClickUp API |
+
+## Rate Limits
+Rate limits vary by ClickUp plan:
+
+| ClickUp Plan   | Limit          |
+|----------------|----------------|
+| Free / Business | 100 req/min   |
+| Business Plus  | 1,000 req/min  |
+| Enterprise     | 10,000 req/min |
+
+For Free/Business plans, paginate aggressively and avoid loading large datasets on page load.
+
+## Gotchas
+- **One List per block.** Each Softr block connects to a single ClickUp List. To display data from multiple Lists, use separate blocks.
+- **Sub-tasks are not natively supported** in the block connection. Sub-tasks will not appear unless they exist as top-level tasks in the connected List.
+- **Multi-list tasks** are supported -- a task that belongs to multiple Lists can appear when any of those Lists is connected.
+- **Rollup fields are not available** because the ClickUp API does not expose them.
+- **Low-tier rate limits** (100 req/min on Free/Business) can cause issues with high-traffic pages. Consider caching strategies or upgrading the ClickUp plan.
+
+## Best For
+- Client portals showing project/task status
+- Status dashboards for team visibility
+- Internal team apps built around ClickUp workflows
+- Task management interfaces with rich field support

package/datasources/coda.md

@@ -0,0 +1,44 @@
+# Coda
+
+## Overview
+Document, table, and automation platform used as a data source for Softr. Requires a Basic plan or higher in Softr. Connects via API token (not OAuth).
+
+## Connection Setup
+1. In Coda, go to Account Settings > API Settings and generate an API token.
+2. In Softr admin, go to Data Sources and select Coda.
+3. Paste the API token to authenticate.
+4. Select the Coda document and table to connect.
+
+## Vibe Coding Field IDs
+Use the Field Inspector block to determine exact field IDs for your Coda tables. Column names in Coda are typically used as field identifiers.
+
+## Supported Fields
+
+| Field Type           | Writable  | Notes |
+|----------------------|-----------|-------|
+| Text                 | Yes       | |
+| Number               | Yes       | |
+| Date                 | Yes       | |
+| Select List          | Yes       | |
+| Attachment           | Yes       | Large attachments may slow block rendering |
+| Checkbox             | Yes       | |
+| URL                  | Yes       | |
+| Email                | Yes       | |
+| People               | Limited   | Depends on Coda's API exposure |
+| Formula              | Read-only | |
+| Button               | Read-only | Not actionable in Softr |
+
+## Rate Limits
+Coda enforces its own API rate limits based on your Coda plan. Softr requests count against your Coda API quota. Suitable for moderate traffic. Refer to Coda's API documentation for current limits on your plan.
+
+## Gotchas
+- **API token authentication only.** Coda does not use OAuth for Softr. The token is generated manually in Coda's account settings.
+- **Embedded Coda docs are not supported** in Vibe Coding blocks. You cannot render a full Coda document inside a Softr block; only table data is accessible.
+- **Advanced Coda automations** (buttons, automations, Packs) do not execute through Softr. Only raw table data is read and written.
+- **Large attachments** stored in Coda may cause slow rendering in Softr blocks. Optimize file sizes where possible.
+- **Coda formulas** are read-only. Calculated columns cannot be written to from Softr.
+
+## Best For
+- Teams using Coda for internal workflows who want an external-facing portal
+- Building portals without requiring Coda seat licenses for every end user
+- Projects where Coda's table and automation features are already in use as the backend

package/datasources/fields.md

@@ -0,0 +1,203 @@
+# Field Types & Debug Utilities
+
+The `getFieldValue()` helper, field type shapes, record structure, and diagnostic blocks.
+
+## Table of Contents
+
+- [getFieldValue -- Never Render Raw Fields](#getfieldvalue----never-render-raw-fields)
+- [Debugging Error #31](#debugging-error-31)
+- [Common Field Type Shapes](#common-field-type-shapes)
+- [Record Structure](#record-structure)
+- [Debug Utilities](#debug-utilities)
+
+## getFieldValue -- Never Render Raw Fields
+
+**Every field value rendered in JSX must pass through `getFieldValue()`** before rendering, parsing, or comparing. Softr returns many field types as `{label, ...}` objects, not strings. Rendering them raw crashes React with error #31 ("Objects are not valid as a React child"). The cost of unnecessary `getFieldValue()` calls is zero; the cost of debugging error #31 is 30 minutes.
+
+```jsx
+var getFieldValue = function(f) {
+  if (f == null) return "";
+  if (Array.isArray(f)) {
+    return f.map(function(x) {
+      if (x && typeof x === "object") return x.label || x.name || x.title || "";
+      return String(x);
+    }).filter(Boolean).join(", ");
+  }
+  if (typeof f === "object") return f.label || f.name || f.title || "";
+  return String(f);
+};
+```
+
+Property priority: `label` first (most common in Softr formatted fields), then `name`, then `title`.
+
+Apply `getFieldValue()` everywhere you read fields:
+- Table cells, badges, tooltips: `<td>{getFieldValue(f.subject)}</td>`
+- Date parsing: `new Date(getFieldValue(f.dueDate))` -- raw value might be `{label: "2025-12-01"}`
+- Number parsing: `parseInt(getFieldValue(f.count), 10)` -- formula numbers come back as objects
+- String methods: `getFieldValue(f.status).toLowerCase()`
+- Inside `useMemo` normalizers, BEFORE storing into state -- prevents the object from propagating
+
+For companion helpers (`getLinkedNames`, `getLinkedItems`) used in helper block consumers, see [../references/helper-blocks.md](../references/helper-blocks.md).
+
+## Debugging Error #31
+
+If React crashes with error #31 ("Objects are not valid as a React child"), open console on the first record that crashes and run:
+
+```js
+JSON.stringify(record.fields, null, 2).slice(0, 1000)
+```
+
+You'll see exactly which field is an object. Add `getFieldValue()` around it.
+
+## Common Field Type Shapes
+
+| Field type | Value shape |
+|---|---|
+| Text, Email, URL, Phone, Address | `string` |
+| Number, Currency, Percent, Progress, Autonumber | `number or null` |
+| Checkbox | `string or boolean` |
+| Date, DateTime, Time, Created At, Updated At | `string` (ISO) |
+| Date Range | `{ from: string, to: string }` |
+| Rating, Duration | `string or number or null` |
+| Select | `{ label: string, id: string }` |
+| Linked Record (via useRecord/useRecords) | `{ label: string, id: string }` |
+| Linked Record (via useLinkedRecords) | `{ id: string, title: string }` -- different! |
+| User, Created By, Updated By | `{ avatarUrl, id, name, email }` |
+| Attachment | `{ filename, id, type, url }` |
+| Formula | `string or number` |
+
+## Record Structure
+
+Records returned by `useRecords` have: `{ id: "recXXX", fields: { alias1: value, alias2: value } }`. Keys inside `fields` are the **aliases from `q.select()`**, NOT the original field names.
+
+```jsx
+var rawRecord = items && items[0];
+var f = rawRecord ? rawRecord.fields || {} : {};
+var name = f.firstName || "";
+```
+
+## Debug Utilities
+
+Two throwaway diagnostic blocks you can drop into a page to diagnose data problems. Neither is meant for production -- delete or hide them once the issue is resolved. During development, drop them on a `/debug` page that's only visible to admins, or on a hidden page you navigate to manually.
+
+### Field Inspector Block
+
+Use when records load but fields come back empty, or when you're not sure which Field IDs exist on a table.
+
+**Important caveat for Softr Database:** `q.select({})` returns record IDs with empty `fields: {}` -- it does NOT dump all fields. Verified by direct experiment, April 2026. Use one of the alternatives below for Softr DB. The empty-select pattern still works for Airtable and other sources where field IDs come back automatically.
+
+For Airtable and other non-Softr-DB sources:
+
+```jsx
+import { useRecords, q } from "@/lib/datasource";
+var select = q.select({});
+export default function Block() {
+  var result = useRecords({ select: select, count: 3 });
+  if (result.status === "pending") return <div className="container py-6"><div className="content"><p>Loading...</p></div></div>;
+  var records = (result.data && result.data.pages) ? result.data.pages.flatMap(function(p) { return p.items; }) : [];
+  return (
+    <div className="container py-6">
+      <div className="content">
+        <pre style={{ fontSize: 12, whiteSpace: "pre-wrap", wordBreak: "break-all" }}>
+          {JSON.stringify(records.slice(0, 2), null, 2)}
+        </pre>
+      </div>
+    </div>
+  );
+}
+```
+
+**For Softr Database, find field IDs via:**
+
+1. **Inline in Studio (one field at a time)** -- in the Data tab, click a field's name to open its edit drawer. The field ID appears next to the "Field name" label (e.g. `ID: 37fts`). Fastest for spot-checking a single field.
+
+2. **Network inspector (full schema in one shot)** -- in Studio's Data tab with browser DevTools open, filter Network requests by `tablespace-with-tables`. The Response JSON contains every table's complete schema, including:
+   - Each field's `id`, `name`, `type`, and `options`
+   - For dropdown / SELECT fields: the full `choices` array with every option's `id` (UUID), `label`, and `color`
+
+   Use this when scaffolding a block that needs many field IDs at once, or to look up dropdown option UUIDs needed for write payloads.
+
+   **Recommended for AI-assisted workflows:** when collaborating with an AI assistant (Claude, Cursor, ChatGPT, etc.) to write a Vibe Coding block, paste this JSON response into the chat. It is the most reliable way to share accurate field IDs and dropdown UUIDs -- it eliminates transcription errors and gives the AI everything it needs in one shot (field IDs, types, options, dropdown choices). Always prefer this over verbally describing fields or naming them by display label.
+
+3. **Softr Database REST API with `fieldNames=true`** -- runtime inspection from inside a Vibe Coding block (internal-portal blocks only, since this exposes a PAT in client code):
+
+```jsx
+import { useEffect, useState } from "react";
+export default function Block() {
+  var [data, setData] = useState(null);
+  useEffect(function() {
+    var url = "https://tables-api.softr.io/api/v1/databases/<DB_ID>/tables/<TABLE_ID>/records?limit=3&fieldNames=true";
+    fetch(url, { headers: { "Softr-Api-Key": "<PAT>" } })
+      .then(function(res) { return res.json(); })
+      .then(function(json) { setData(json); });
+  }, []);
+  if (!data) return <div className="container py-6"><div className="content"><p>Loading...</p></div></div>;
+  return (
+    <div className="container py-6">
+      <div className="content">
+        <pre style={{ fontSize: 12, whiteSpace: "pre-wrap", wordBreak: "break-all" }}>
+          {JSON.stringify(data, null, 2)}
+        </pre>
+      </div>
+    </div>
+  );
+}
+```
+
+This calls the Softr Database REST API with `?fieldNames=true`, which returns records keyed by human-readable field names so you can map them back to IDs. See [writing.md Cross-Table Operations](writing.md#cross-table-operations) for more on this REST API.
+
+### API Response Inspector Block
+
+For REST API data sources, use `useProxyFetch` instead (see [rest-api.md](rest-api.md)):
+
+```jsx
+import { useProxyFetch } from "@/lib/datasource";
+import { useQuery } from "@tanstack/react-query";
+export default function Block() {
+  var proxyFetch = useProxyFetch();
+  var result = useQuery({
+    queryKey: ["api-inspect"],
+    queryFn: function() {
+      return proxyFetch("YOUR_FULL_API_URL_HERE")
+        .then(function(res) { return res.json(); });
+    },
+  });
+  if (result.status === "pending") return <div className="container py-6"><div className="content"><p>Loading...</p></div></div>;
+  if (result.status === "error") return <div className="container py-6"><div className="content"><p className="text-red-500">Error: {result.error && result.error.message}</p></div></div>;
+  return (
+    <div className="container py-6">
+      <div className="content">
+        <pre style={{ fontSize: 12, whiteSpace: "pre-wrap", wordBreak: "break-all", background: "#f9fafb", padding: 16, borderRadius: 8 }}>
+          {JSON.stringify(result.data, null, 2)}
+        </pre>
+      </div>
+    </div>
+  );
+}
+```
+
+### User Inspector Block
+
+Use when debugging permissions, user groups, or the `useCurrentUser()` vs `window.__softr_current_user` distinction. Renders both side-by-side as JSON. This catches a common surprise: `userGroups` only lives on the `window.__softr_current_user` object, not on `useCurrentUser()`.
+
+```jsx
+import { useCurrentUser } from "@/lib/user";
+export default function Block() {
+  var currentUser = useCurrentUser();
+  var softrUser = window.__softr_current_user || {};
+  return (
+    <div className="container py-6">
+      <div className="content">
+        <h3>useCurrentUser():</h3>
+        <pre style={{ fontSize: 12, whiteSpace: "pre-wrap", wordBreak: "break-all" }}>
+          {JSON.stringify(currentUser, null, 2)}
+        </pre>
+        <h3 style={{ marginTop: 16 }}>window.__softr_current_user:</h3>
+        <pre style={{ fontSize: 12, whiteSpace: "pre-wrap", wordBreak: "break-all" }}>
+          {JSON.stringify(softrUser, null, 2)}
+        </pre>
+      </div>
+    </div>
+  );
+}
+```

package/datasources/google-sheets.md

@@ -0,0 +1,46 @@
+# Google Sheets
+
+## Overview
+Cloud spreadsheet used as a simple data source for Softr. Requires a Basic plan or higher in Softr. Connects via Google OAuth.
+
+## Connection Setup
+1. In Softr admin, go to Data Sources and select Google Sheets.
+2. Authenticate with your Google account via OAuth.
+3. Select the spreadsheet and sheet (tab) to connect.
+4. Ensure the first row contains column headers. Softr uses these as field names.
+5. Softr will automatically add a "Softr Record ID" column to the sheet.
+
+## Vibe Coding Field IDs
+q.select() uses the column header names from the first row of the sheet. Use the Field Inspector block to confirm exact field IDs if headers have been renamed or modified.
+
+## Supported Fields
+Google Sheets has no native field typing. All data is text. Softr interprets values based on formatting conventions:
+
+| Data Type      | How to Format in the Sheet | Notes |
+|----------------|----------------------------|-------|
+| Text           | Plain text                 | |
+| Number         | Numeric value              | |
+| Date           | English date formats only  | Wide range of patterns accepted (e.g., MM/DD/YYYY, YYYY-MM-DD, Month DD, YYYY) |
+| Image          | URL to the image           | Must be a direct image URL |
+| Multiple Images| Comma-separated URLs       | Each URL on its own, separated by commas |
+| Checkbox       | `"true"` or `"false"`      | String values, not native booleans |
+| Tags           | Comma-separated values     | e.g., `"Design, Marketing, Sales"` |
+| Rating         | Integer 1-5                | |
+
+## Rate Limits
+Google Sheets is not designed for high-concurrency database use. Recommended maximum: **50-100 concurrent users**. Beyond that, expect slow responses and potential errors from Google's API quotas.
+
+## Gotchas
+- **No native field types.** Everything is a string. You must format data exactly as Softr expects (see table above).
+- **Softr adds a "Softr Record ID" column** automatically. Do not delete or modify this column.
+- **First row must be headers.** Data starts from the second row. Empty or merged header cells cause issues.
+- **Date formats must be in English.** Localized date formats (e.g., DD.MM.YYYY in German locale) may not parse correctly.
+- **Checkbox values are strings.** Use `"true"` and `"false"`, not `TRUE` / `FALSE` (the Google Sheets boolean formula values).
+- **Low security classification.** Google Sheets lacks row-level permissions. Any user with sheet access can see all data. Not suitable for sensitive data without additional access controls in Softr.
+- **Images require direct URLs.** Google Drive sharing links do not work as image sources unless converted to direct download URLs.
+
+## Best For
+- Simple apps with straightforward data
+- Teams already using Google Workspace
+- Low-traffic internal portals (under 50-100 concurrent users)
+- Quick prototypes where setup speed matters more than performance

package/datasources/hubspot.md

@@ -0,0 +1,51 @@
+# HubSpot
+
+## Overview
+CRM platform used as a data source for Softr. Requires a Business or Enterprise plan in Softr. Connects via OAuth.
+
+## Connection Setup
+1. In Softr admin, go to Data Sources and select HubSpot.
+2. Authenticate via OAuth with your HubSpot account.
+3. Select the HubSpot object type to connect (Contacts, Companies, Deals, etc.).
+4. If accessing sensitive fields, ensure Sensitive Data Scopes are enabled in your HubSpot app settings.
+
+## Vibe Coding Field IDs
+Use the Field Inspector block to determine exact field IDs for HubSpot properties. Default HubSpot properties use their internal API names (e.g., `"firstname"`, `"dealstage"`, `"company"`). Custom properties use the internal name assigned by HubSpot when created.
+
+## Supported Fields
+
+**Supported HubSpot Objects:**
+- Contacts
+- Companies
+- Deals
+- Tickets
+- Notes
+- Tasks
+- Custom Objects
+
+| Field Type           | Writable  | Notes |
+|----------------------|-----------|-------|
+| Default Properties   | Yes       | All standard HubSpot properties for the connected object |
+| Custom Properties    | Yes       | Custom properties created in HubSpot |
+| Associations         | Read-only | Relational data between objects. Displayed via Linked List Blocks in Softr. |
+| Calculation          | Read-only | |
+| Rollup               | Read-only | |
+| Count                | Read-only | |
+| Formula              | Read-only | |
+
+## Rate Limits
+HubSpot enforces its own API rate limits based on your HubSpot plan tier. Softr requests count against your HubSpot API quota. Refer to HubSpot's documentation for current limits on your plan.
+
+## Gotchas
+- **Business or Enterprise Softr plan required.** HubSpot is not available on Free or Basic plans.
+- **Sensitive Data Scopes** must be explicitly enabled in HubSpot for certain fields (e.g., email content, certain contact properties). Without this, those fields return empty.
+- **Associations are read-only** in Vibe Coding blocks. Use Linked List Blocks to display related records (e.g., Deals associated with a Contact).
+- **Custom Objects** require that the object is properly configured in HubSpot with the necessary scopes granted during OAuth.
+- **Deal stages and pipeline data** use internal IDs, not display labels. Map these in your block logic if you need human-readable values.
+
+## Best For
+- Sales portals and deal rooms
+- CRM dashboards for teams or clients
+- Support ticket portals
+- Partner portals with HubSpot-managed contacts
+- Any app where HubSpot is the system of record

package/datasources/monday.md

@@ -0,0 +1,52 @@
+# monday.com
+
+## Overview
+Project management platform used as a data source for Softr. Requires a Professional plan or higher in Softr. Connects via API token.
+
+## Connection Setup
+1. In monday.com, go to Administration > API > Personal API Token and copy the token.
+2. In Softr admin, go to Data Sources and select monday.com.
+3. Paste the API token to authenticate.
+4. Select the monday.com board and group to connect.
+
+## Vibe Coding Field IDs
+Use the Field Inspector block to determine exact field IDs for your monday.com board columns. Column names or internal IDs assigned by monday.com are used as field identifiers.
+
+## Supported Fields
+
+| Field Type           | Writable  | Notes |
+|----------------------|-----------|-------|
+| Text                 | Yes       | |
+| Number               | Yes       | |
+| Date                 | Yes       | |
+| Status               | Yes       | |
+| Dropdown             | Yes       | |
+| Checkbox             | Yes       | |
+| Email                | Yes       | |
+| Phone                | Yes       | |
+| Link                 | Yes       | |
+| People               | Yes       | |
+| File                 | Yes       | |
+| Connected Boards     | Limited   | Linked records between boards are supported |
+| Mirror               | Read-only | Reflects data from connected boards |
+| Created By           | Read-only | |
+| Created At           | Read-only | |
+| Last Updated         | Read-only | |
+| Item ID              | Read-only | |
+
+## Rate Limits
+monday.com enforces API rate limits based on your monday.com plan tier. Softr requests count against your monday.com API quota. Recommended maximum: **50-100 concurrent users**. Beyond that, API throttling may cause slow or failed requests.
+
+## Gotchas
+- **Professional+ Softr plan required.** monday.com is not available on Free or Basic Softr plans.
+- **API token authentication only.** Uses a Personal API Token from monday.com's admin settings, not OAuth.
+- **Connected Boards** (linked records between boards) are supported but may have limitations depending on the board configuration.
+- **Mirror columns are read-only.** These reflect data from connected boards and cannot be written to from Softr.
+- **Status columns** use monday.com's internal label/index system. Map these appropriately in your block logic for display purposes.
+- **Subitems** may require additional configuration to surface correctly in Softr blocks.
+
+## Best For
+- Client-facing project portals without giving clients direct monday.com access
+- Status dashboards for stakeholders
+- Task management interfaces for external collaborators
+- Teams using monday.com as their project management backbone

package/datasources/notion.md

@@ -0,0 +1,56 @@
+# Notion
+
+## Overview
+Document and database platform used as a data source for Softr. Requires a Basic plan or higher in Softr. Connects via OAuth.
+
+## Connection Setup
+1. In Softr admin, go to Data Sources and select Notion.
+2. Authenticate via OAuth with your Notion account.
+3. Select the Notion database to connect.
+4. If a database does not appear in the list: open Notion, click the ellipsis menu (...) on the database page, go to Connections, find Softr, and click Allow.
+5. Multiple Notion workspaces can be connected to a single Softr app.
+
+## Vibe Coding Field IDs
+Use the Field Inspector block to determine exact field IDs for Notion database properties. Property names in Notion are typically used as field IDs.
+
+## Supported Fields
+
+| Field Type           | Writable  | Notes |
+|----------------------|-----------|-------|
+| Title                | Yes       | |
+| Text (Rich Text)     | Yes       | |
+| Number               | Yes       | |
+| Select               | Yes       | |
+| Multi-select         | Yes       | |
+| Date                 | Yes       | |
+| Checkbox             | Yes       | |
+| URL                  | Yes       | |
+| Email                | Yes       | |
+| Phone                | Yes       | |
+| Files & Media        | Yes       | |
+| Relation             | Limited   | Cannot be displayed in List blocks. Use Rollup workaround (see Gotchas). |
+| Rollup               | Read-only | |
+| Formula              | Read-only | |
+| People               | Read-only | |
+| Last Edited Time     | Read-only | |
+| Last Edited By       | Read-only | |
+| Created Time         | Read-only | |
+| Created By           | Read-only | |
+| ID (auto-increment)  | Read-only | |
+| Button               | Read-only | |
+
+## Rate Limits
+Notion enforces its own API rate limits. Softr requests count against your Notion API quota. Performance is generally adequate for moderate traffic but is not suited for very high concurrency.
+
+## Gotchas
+- **Only database pages work.** Regular Notion pages (without a database) cannot be used as a Softr data source. The page must contain or be a Notion database.
+- **Missing database in connection list:** The Notion database must explicitly grant access to the Softr integration. In Notion: ellipsis (...) > Connections > Softr > Allow.
+- **Relation properties cannot be displayed in List blocks.** Workaround: create a Rollup property in Notion that pulls the desired field from the related database, then display the Rollup instead.
+- **Sub-items support:** Use conditional filters to separate parent and child items. Filter by "Parent item is empty" for top-level items, "Parent item is not empty" for sub-items.
+- **Formula date timezone quirk:** Formula properties that return dates may display one day off due to UTC handling differences between Notion and Softr. Test date formulas carefully.
+- **Multiple workspaces:** You can connect databases from different Notion workspaces to the same Softr app.
+
+## Best For
+- Teams using Notion for project management or knowledge bases
+- Internal tools and dashboards backed by Notion databases
+- Content management portals where Notion is the editorial system