Merge pull request #355 from better-stack-ai/feat/issue-338-after-v6

feat(form-builder): add conditional fields, uploads and CSV exports

Author: olliethedev

docs/content/docs/plugins/form-builder.mdx

@@ -216,6 +216,7 @@ The form builder provides a drag-and-drop interface with:
 | Date Picker | Date selection | `type: "string", format: "date-time"` |
 | Phone | Phone number input | `type: "string", fieldType: "phone"` |
 | URL | Website URL input | `type: "string", format: "uri"` |
+| File Upload | Standalone upload using your callback | `type: "string", fieldType: "file"` |
 
 ### Field Properties
 
@@ -231,6 +232,73 @@ Each field can be configured with:
 | Min/Max | Minimum and maximum values (numbers) or length (strings) |
 | Options | For select, radio, and checkbox groups |
 | Default Value | Pre-filled value for the field |
+| Visibility | One `showIf` condition against another field |
+
+### Conditional fields and steps
+
+In a field's edit dialog, use **Visibility** to choose a source field, operator,
+and comparison value. For a multi-step form, use the active step's visibility
+editor below its tabs. Step conditions can use fields from earlier steps.
+Choose **Always show** to remove a condition.
+
+`showIf` is stored on a property or step as `{ field, operator, value }`.
+`field` names a sibling field (a top-level field for step rules).
+
+| Operator | Comparison |
+|----------|------------|
+| `equals` | Strict equality; `1` differs from `"1"` |
+| `notEquals` | Strict inequality |
+| `in` | Source value is an element of the `value` array |
+| `isTruthy` | JavaScript truthiness; no comparison value is needed |
+
+The editor accepts text, numbers, and booleans. Quote a number or boolean to
+compare it as text. For `in`, enter one comparison value per line.
+
+```ts
+import { z } from "zod"
+import { zodToFormSchema } from "@btst/plugin-form-builder/client"
+
+const schema = z.object({
+  business: z.boolean(),
+  company: z.string().min(1).meta({
+    showIf: { field: "business", operator: "isTruthy" },
+  }),
+})
+const jsonSchema = zodToFormSchema(schema)
+```
+
+Both `FormRenderer` and `SteppedAutoForm` hide non-matching fields and skip hidden
+steps. The shared `formSchemaToZod` validator bypasses their required constraints
+and removes stale values, including nested object and array-item fields, before
+persistence. Visible fields retain their normal validation. Submission hooks
+receive validated data; any replacement data is validated again before storage.
+
+### Standalone file uploads
+
+Drag **File Upload** from the palette. Configure an upload callback on
+`FormRenderer`, or set `overrides.formBuilder.onUpload` on `StackProvider`:
+
+```tsx
+<FormRenderer
+  slug="application"
+  onUpload={async (file) => {
+    const body = new FormData()
+    body.append("file", file)
+    const response = await fetch("/api/files", { method: "POST", body })
+    if (!response.ok) throw new Error("Upload failed")
+    const result = await response.json()
+    return result.url
+  }}
+/>
+```
+
+The callback receives a `File` and returns a non-empty URL string, including
+relative URLs. Only that string is submitted. Your endpoint owns file validation,
+storage, access control, and cleanup; the Media plugin is optional. The renderer
+disables submission during upload and displays upload failures with a retry path.
+Without a callback, the file control is disabled with a configuration message.
+For standalone AutoForm, use `fieldConfig.attachment.onUpload`. Builder previews
+can use `fieldComponents.file` to provide an uploader.
 
 ## Public Form Rendering
 
@@ -276,6 +344,7 @@ export default function FormDemoPage({ params }: { params: { slug: string } }) {
 | `slug` | `string` | Form slug to fetch and render |
 | `onSuccess` | `(submission) => void` | Callback after successful submission (submission.form has success info) |
 | `onError` | `(error) => void` | Callback when submission fails |
+| `onUpload` | `(file: File) => Promise<string>` | Standalone file uploader; overrides the provider callback |
 | `LoadingComponent` | `ComponentType` | Custom loading state |
 | `ErrorComponent` | `ComponentType<{ error: Error }>` | Custom error state |
 | `submitButtonText` | `string` | Custom submit button text |
@@ -306,6 +375,7 @@ Access form data in your frontend using the provided hooks:
 | `useSubmissions(formId)` | List non-sensitive submission metadata and authoritative form facts | `{ form, submissions, total, isLoading }` |
 | `useSubmission(formId, submissionId)` | Get one record-authorized submission with its data, IP address, and user agent | `{ submission, isLoading, error }` |
 | `useDeleteSubmission(formId)` | Delete submission | React Query mutation |
+| `useExportSubmissions()` | Export all submissions for a form ID | Mutation returning `{ csv, filename }` |
 
 `useSubmissions` returns `form` as the intentionally minimal
 `SubmissionListFormContext`: `{ id, name, createdBy? }`. Submission access does
@@ -387,6 +457,10 @@ export const authorization = defineAuthorization({
       identity?.role === "admin" || identity?.id === facts.ownerId,
     ),
     forms.submission.create.allow(),
+    forms.submission.export.when(({ identity, facts }) =>
+      identity !== null &&
+      (identity.role === "admin" || identity.id === facts.ownerId),
+    ),
     forms.submission.read.when(({ identity, facts }) =>
       identity?.role === "admin" || identity?.id === facts.ownerId,
     ),
@@ -468,6 +542,30 @@ transactional database adapter. The CLI supports Form Builder with Prisma,
 Drizzle, and Kysely and rejects its current memory and MongoDB scaffold
 configurations.
 
+## CSV export
+
+The submissions page offers **Export CSV** when `submission.export` is granted.
+This is a separate permission for all payloads of the selected form; permission
+to read one submission or collection metadata does not grant export access.
+Facts include the server-resolved `formId`, `formExists`, and `ownerId`.
+
+The operation exports every submission, independent of admin pagination. Columns
+contain `id`, `submittedAt`, and `data.<field>` values. Deleted fields remain in
+the export when older submissions contain them. Nested values are JSON strings;
+cells are quoted and formula-like values are prefixed with an apostrophe for
+spreadsheet safety. Source reads are paged and CSV rows are serialized without
+building a full cell matrix. An export supports up to 10,000 submissions,
+1,000 distinct data columns, one million data cells, and 10 MiB each of stored
+JSON and CSV output. Larger exports fail with HTTP 413 and
+`FORM_EXPORT_TOO_LARGE`; they require an application-managed streaming or
+offline export. No partial CSV is downloaded when a limit is exceeded.
+
+```ts
+const result = await stack.forRequest(request).operations.formBuilder
+  .exportSubmissions({ formId })
+// { csv: string, filename: string }
+```
+
 ## Backend Hooks
 
 Authorization runs before lifecycle hooks. Use hooks for domain behavior such
@@ -516,6 +614,7 @@ The Form Builder plugin exposes these REST endpoints:
 | `/form-builder/forms/:id` | DELETE | Delete a form |
 | `/form-builder/forms/:slug/submit` | POST | Submit form data |
 | `/form-builder/forms/:formId/submissions` | GET | List non-sensitive submission metadata for a form |
+| `/form-builder/forms/:formId/submissions/export` | POST | Export all submissions as `{ csv, filename }`; requires `submission.export` |
 | `/form-builder/forms/:formId/submissions/:subId` | GET | Get a record-authorized submission and its contents |
 | `/form-builder/forms/:formId/submissions/:subId` | DELETE | Delete a submission |
 
@@ -555,20 +654,17 @@ The Form Builder supports multi-step forms through JSON Schema's `allOf` structu
 ```json
 {
   "type": "object",
-  "allOf": [
-    {
-      "title": "Step 1: Personal Info",
-      "properties": {
-        "name": { "type": "string", "label": "Full Name" },
-        "email": { "type": "string", "format": "email" }
-      }
-    },
+  "properties": {
+    "business": { "type": "boolean", "stepGroup": 0 },
+    "company": { "type": "string", "stepGroup": 1 }
+  },
+  "required": ["business", "company"],
+  "steps": [
+    { "id": "personal", "title": "Personal Info" },
     {
-      "title": "Step 2: Details",
-      "properties": {
-        "company": { "type": "string" },
-        "message": { "type": "string", "fieldType": "textarea" }
-      }
+      "id": "company",
+      "title": "Company Details",
+      "showIf": { "field": "business", "operator": "isTruthy" }
     }
   ]
 }

e2e/tests/smoke.form-builder.spec.ts

@@ -771,3 +771,174 @@ test.describe("Form Builder - Public Form Submission", () => {
 		);
 	});
 });
+
+test.describe("Conditional Form Builder", () => {
+	test.use({ extraHTTPHeaders: mockAuthHeaders() });
+	test.beforeEach(async ({ context }) => {
+		await setMockAuthCookie(context);
+	});
+
+	async function createConditionalForm(
+		request: import("@playwright/test").APIRequestContext,
+	) {
+		const slug = `conditional-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+		const response = await request.post("/api/data/forms", {
+			data: {
+				name: "Conditional application",
+				slug,
+				status: "active",
+				schema: JSON.stringify({
+					type: "object",
+					properties: {
+						business: {
+							type: "boolean",
+							label: "Business applicant",
+							default: false,
+							stepGroup: 0,
+						},
+						company: {
+							type: "string",
+							label: "Company name",
+							minLength: 1,
+							stepGroup: 0,
+							showIf: { field: "business", operator: "isTruthy" },
+						},
+						attachment: {
+							type: "string",
+							label: "Attachment",
+							fieldType: "file",
+							stepGroup: 1,
+						},
+						notes: { type: "string", label: "Notes", stepGroup: 2 },
+					},
+					required: ["business", "company", "attachment"],
+					steps: [
+						{ id: "basics", title: "Basics" },
+						{
+							id: "documents",
+							title: "Documents",
+							showIf: { field: "business", operator: "isTruthy" },
+						},
+						{ id: "review", title: "Review" },
+					],
+				}),
+			},
+		});
+		expect(response.ok()).toBe(true);
+		return { ...(await response.json()), slug };
+	}
+
+	test("hides fields, skips steps, strips stale values and exports a CSV download", async ({
+		page,
+		request,
+	}) => {
+		const form = await createConditionalForm(request);
+		try {
+			await page.goto(`/form-demo/${form.slug}`);
+			await expect(page.getByTestId("form-renderer")).toBeVisible();
+			await expect(
+				page.getByRole("textbox", { name: "Company name" }),
+			).toHaveCount(0);
+			await expect(page.getByText("Documents", { exact: true })).toHaveCount(0);
+			await page.getByRole("checkbox", { name: "Business applicant" }).check();
+			await expect(
+				page.getByRole("textbox", { name: "Company name" }),
+			).toBeVisible();
+			await page
+				.getByRole("checkbox", { name: "Business applicant" })
+				.uncheck();
+			await page.getByRole("button", { name: "Next", exact: true }).click();
+			await expect(
+				page.getByRole("heading", { name: "Review", exact: true }),
+			).toBeVisible();
+			await page.getByRole("button", { name: "Submit", exact: true }).click();
+			await expect(
+				page.getByRole("heading", { name: "Form Submitted" }),
+			).toBeVisible();
+			const stale = await request.post(`/api/data/forms/${form.slug}/submit`, {
+				data: {
+					data: {
+						business: false,
+						company: { invalid: true },
+						attachment: "stale-file",
+					},
+				},
+			});
+			expect(stale.ok()).toBe(true);
+			expect(JSON.parse((await stale.json()).data)).toEqual({
+				business: false,
+			});
+			await page.goto(`/pages/forms/${form.id}/submissions`);
+			const downloadPromise = page.waitForEvent("download");
+			await page
+				.getByRole("button", { name: "Export CSV", exact: true })
+				.click();
+			const download = await downloadPromise;
+			expect(download.suggestedFilename()).toBe(`${form.slug}-submissions.csv`);
+			const exported = await request.post(
+				`/api/data/forms/${form.id}/submissions/export`,
+			);
+			expect(exported.ok()).toBe(true);
+			const { csv } = await exported.json();
+			expect(csv).toContain(
+				'"data.business","data.company","data.attachment","data.notes"',
+			);
+			expect(csv).not.toContain("stale-file");
+		} finally {
+			await request.delete(`/api/data/forms/${form.id}`);
+		}
+	});
+
+	test("edits field and step visibility in the visual builder and retains file fields", async ({
+		page,
+		request,
+	}) => {
+		const form = await createConditionalForm(request);
+		try {
+			await page.goto(`/pages/forms/${form.id}/edit`);
+			await expect(
+				getPalette(page).getByText("File Upload", { exact: true }),
+			).toBeVisible();
+			const company = getCanvas(page)
+				.locator('[class*="rounded-lg"]')
+				.filter({ hasText: "Company name" })
+				.first();
+			await company.hover();
+			await company.locator("button").first().click();
+			const dialog = page.getByRole("dialog");
+			await expect(
+				dialog.getByText("Visibility", { exact: true }),
+			).toBeVisible();
+			await dialog.getByLabel("Condition", { exact: true }).click();
+			await page.getByRole("option", { name: "Equals", exact: true }).click();
+			await dialog.getByLabel("Value", { exact: true }).fill("true");
+			await dialog
+				.getByRole("button", { name: "Save Changes", exact: true })
+				.click();
+			await page
+				.getByRole("button", { name: "Documents", exact: true })
+				.click();
+			await expect(
+				page.getByText("Documents visibility", { exact: true }),
+			).toBeVisible();
+			await page.getByRole("button", { name: "Save", exact: true }).click();
+			await expect(
+				page.getByText("Form updated successfully", { exact: true }),
+			).toBeVisible();
+			const saved = await request.get(`/api/data/forms/id/${form.id}`);
+			const schema = JSON.parse((await saved.json()).schema);
+			expect(schema.properties.company.showIf).toEqual({
+				field: "business",
+				operator: "equals",
+				value: true,
+			});
+			expect(schema.steps[1].showIf).toEqual({
+				field: "business",
+				operator: "isTruthy",
+			});
+			expect(schema.properties.attachment.fieldType).toBe("file");
+		} finally {
+			await request.delete(`/api/data/forms/${form.id}`);
+		}
+	});
+});