form-building

# Form Building ## Creating a Form Use the `create-form` script to create forms from natural language: ```bash pnpm action create-form --title "Contact Form" --fields '[...]' ``` The script generates a unique ID, creates a URL slug, and stores the form in SQL as `draft` status. ### One request, one form Every form the user describes is its own form. Use `create-form` for each new form request even when a form is already open on screen or you created one earlier in the same conversation — the open form is context, not a default target. Reach for `update-form` / `patch-form-fields` only when the user is changing that specific form. | The user says | Call | | --- | --- | | "Create a customer feedback form..." | `create-form` | | "Now build an event registration form..." | `create-form` (a second form) | | "Add a phone field to it" | `patch-form-fields` | | "Rename this form / publish it" | `update-form` | | "Rewrite this form as a signup form" | `update-form` with `confirmReplaceFields: true` | `update-form` rejects a `fields` replacement that drops most of the form's existing questions with `unconfirmed_field_loss`. That error means the call was about to overwrite a form the user still wants: create the new form instead, unless they explicitly asked to rewrite this one in place. ## Field Types | Type | Description | Options needed | Example use | | ------------- | ------------------------------ | -------------- | --------------------- | | `text` | Single-line text input | No | Name, company | | `email` | Email input with validation | No | Contact email | | `number` | Numeric input | No | Age, quantity | | `textarea` | Multi-line text | No | Message, comments | | `select` | Single-choice dropdown | Yes | Country, department | | `multiselect` | Multi-choice dropdown | Yes | Skills, interests | | `checkbox` | Boolean toggle | No | Consent, opt-in | | `radio` | Single-choice radio buttons | Yes | Gender, preference | | `date` | Date picker | No | Birthday, deadline | | `rating` | Star rating (1-5) | No | Satisfaction, quality | | `scale` | Numeric scale (e.g., 1-10) | No | NPS, likelihood | | `file` | File upload | No | Resume, attachment | ## Field JSON Schema Each field is a JSON object: ```json { "id": "field_name", "type": "text", "label": "Your Name", "placeholder": "Enter your name", "description": "Help text shown below the field", "required": true, "options": ["Option A", "Option B"], "validation": { "min": 1, "max": 100, "pattern": "^[a-zA-Z]+$", "message": "Custom error message" }, "conditional": { "fieldId": "other_field_id", "operator": "equals", "value": "show_this_field" }, "width": "full" } ``` ### Required properties - `id` — unique identifier (snake_case recommended) - `type` — one of the types above - `label` — display label - `required` — boolean Always pass fields as these complete objects. Never encode a field as shorthand text such as `text: Enter a name`; `patch-form-fields` upserts also require the field `id` so they cannot be ambiguous. ### Optional properties - `placeholder` — input placeholder text - `description` — help text below the field - `options` — array of strings (required for select, multiselect, radio) - `validation` — min/max/pattern/message for custom validation - `conditional` — show field only when another field matches a condition - `width` — `"full"` (default) or `"half"` for side-by-side layout - `multiple`, `accept`, `maxSizeBytes`, `maxFiles` — file upload settings for `file` fields ## Updating a Form Use `update-form` to modify any form property: ```bash # Change title pnpm action update-form --id <id> --title "New Title" # Update fields pnpm action update-form --id <id> --fields '[...]' # Change status pnpm action update-form --id <id> --status published ``` ## Common Form Templates When a user asks for a common form type, use these field patterns: **Contact form:** ```json [ {"id":"name","type":"text","label":"Name","required":true}, {"id":"email","type":"email","label":"Email","required":true}, {"id":"message","type":"textarea","label":"Message","required":true} ] ``` **Survey/feedback:** ```json [ {"id":"rating","type":"rating","label":"Overall satisfaction","required":true}, {"id":"recommend","type":"scale","label":"How likely to recommend? (1-10)","required":true}, {"id":"feedback","type":"textarea","label":"Additional feedback","required":false} ] ``` **Registration/signup:** ```json [ {"id":"first_name","type":"text","label":"First Name","required":true,"width":"half"}, {"id":"last_name","type":"text","label":"Last Name","required":true,"width":"half"}, {"id":"email","type":"email","label":"Email","required":true}, {"id":"role","type":"select","label":"Role","options":["Student","Professional","Other"],"required":true} ] ``` ## Workflow 1. `create-form` with title and fields 2. Preview in the GUI (agent + user iterate) 3. `update-form --status published` to go live 4. Share the public URL: `/f/<slug>` ## Related Skills - **form-responses** — Viewing and analyzing submitted data - **form-publishing** — Form lifecycle (draft -> published -> closed) - **scripts** — All form operations go through scripts