@typeroll/mcp-server 0.33.2 → 0.35.0

package/skills/tr-forms.md

@@ -1,312 +1,145 @@
 ---
 name: tr-forms
-description: Use when the user wants to add a contact form, booking form, or any web form to their Typeroll site. Triggers on "lägg till formulär", "contact form", "add a form", "let visitors message us", "booking form", "formulär", or similar. Covers both creating the form definition and embedding the HTML widget on a page.
+description: Use when the user wants to add a contact form, newsletter signup, booking form, or other web form to a Typeroll site.
 ---
 
 # Add a form to a Typeroll site
 
-Typeroll forms are server-backed: submissions go to
-`/api/forms/submit` (HMAC-signed, rate-limited, honeypot-protected)
-and are stored in Firestore. The user sees them in the portal's
-Submissions inbox. No third-party service needed.
+Typeroll forms are server-backed. The platform renders the form shell, accepts
+signed submissions, validates declared fields, stores submissions, and can run
+admin-configured email or webhook actions.
 
-## Preconditions
+## Choose the placement
 
-- Site exists and MCP is configured.
-- You know what fields the form needs.
+- Block-mode page: add `{ type: 'core/form', data: { form_id } }`.
+- HTML-mode page: add `<x-form id="form-id" />` to `html_content`.
 
-## Forms 2.0 — steps mode (template_capabilities_version ≥ 0.18.0)
+Both are authoring references to the same renderer. Preview and static
+generation expand them to the complete form HTML, signed token, honeypot,
+initial step state, styles, and shared runtime. Never hand-write the `<form>`
+shell or paste a token into page HTML.
 
-Prefer this over the hand-built core/html embed when the portal supports
-it. A form's `steps[]` are Block[] trees of `form/*` field blocks mixed
-with content blocks; place `{ type: 'core/form', data: { form_id } }` on
-the page and the build renders everything (token, honeypot, runtime,
-proof-of-work) — you never hand-write the <form> markup.
+## Create a simple form
 
-```
-update_form form_id=ansokan patch={ steps: [
-  { id: 'steg1', title: 'Om företaget', blocks: [
-    { type: 'form/text',  data: { name: 'foretag', label: 'Företag', required: true } },
-    { type: 'form/email', data: { name: 'epost', label: 'E-post', required: true } } ] },
-  { id: 'steg2', title: 'Detaljer', blocks: [
-    { type: 'form/textarea', data: { name: 'meddelande', label: 'Meddelande' } },
-    { type: 'form/consent',  data: { name: 'gdpr', text: '<p>Jag godkänner …</p>' } } ] } ] }
-add_block target={kind:'page', id:'kontakt'} block={ type: 'core/form', data: { form_id: 'ansokan' } }
-```
-
-Validation derives from the field blocks (required/pattern/min/max) —
-there is no separate field list to maintain. Partial submissions persist
-per step (TTL `partial_ttl_days`, default 30). Form-scoped CSS goes in
-`styles`; field look is themable via `--form-field-*` tokens in the
-site's custom_css. On older portals, use the legacy recipe below.
-
-**Simple forms don't need hand-built steps** (template_capabilities_version
-≥ 0.29.0, `forms_steps_only` capability): steps are the ONLY stored model,
-and a plain `create_form` with `fields[]` is authoring sugar — the server
-converts the list to a single static step (read_form shows the resulting
-steps). Every form renders through the `core/form` block (styled inputs,
-client validation, token + honeypot all handled). So for any single-step
-form: `create_form` with `fields`, then
-`add_block { type: 'core/form', data: { form_id } }`. Reach for the
-raw-HTML embed (below) only on older portals or HTML-mode pages — and note
-it supports single-step forms only.
+`fields[]` is authoring sugar for one static step:
 
-## Recipe
-
-### 1. Create the form definition
-
-```
-create_form {
-  "id": "kontakt",
-  "name": "Kontaktformulär",
+```json
+{
+  "id": "newsletter",
+  "name": "Newsletter",
   "fields": [
-    {"name":"name",    "label":"Namn",          "type":"text",     "required":true},
-    {"name":"email",   "label":"E-post",         "type":"email",    "required":true},
-    {"name":"phone",   "label":"Telefon",        "type":"text"},
-    {"name":"message", "label":"Meddelande",     "type":"textarea", "required":true},
-    {"name":"subject", "label":"Ämne",           "type":"select",
-     "options":["Prisförfrågan","Samarbete","Övrigt"]}
+    {"name":"email", "type":"email", "label":"E-postadress", "required":true}
   ],
-  "success_message": "Tack! Vi återkommer inom 24 timmar."
+  "submit_text": "Prenumerera",
+  "success_message": "Tack! Du är anmäld."
 }
 ```
 
-There is no `recipient_email` field — submissions land in the portal's
-Submissions inbox (`/app/sites/{siteId}/forms/{formId}/submissions`).
-Email notification is a form *action* (not yet wired platform-side);
-tell the customer to check the inbox.
+Field names must match `[a-z][a-z0-9_-]*`. Labels may be localized. Supported
+simple types include `text`, `email`, `tel`, `url`, `number`, `textarea`,
+`select`, `radio`, `checkbox`, `hidden`, and `gdpr_consent`.
 
-**Field types:** `text`, `email`, `tel`, `url`, `number`, `textarea`,
-`select`, `radio`, `checkbox`.
+## Place the form
 
-**Field name rules:** Lowercase ASCII only: `[a-z][a-z0-9_-]*`.
-- `besokt` not `besökt` (`ö→o`)
-- `foretag` not `företag` (`ö→o`, `ä→a`)
-- `meddelande` not `Meddelande` (the `name` must be lowercase; `label` can be anything)
-
-### 2. Get the signed embed token
-
-The submit endpoint only accepts requests carrying a platform-signed
-HMAC token. `create_form` returns it directly; you can also fetch it any
-time with:
+On a block-mode page:
 
 ```
-read_form form_id="kontakt"
+add_block target={kind:'page', id:'start'}
+  block={type:'core/form', data:{form_id:'newsletter'}}
 ```
 
-The response includes `submit_token` (put it in the hidden `_token`
-input) and `submit_url` (use it as the form's `action`). The token is
-stable — it only stops working if the platform rotates its signing
-secret — so baking it into static page HTML is correct. If
-`submit_token` comes back `null`, the server has no signing secret
-configured (dev setups); the form cannot accept submissions until that's
-fixed — tell the user instead of embedding a broken form.
-
-### 3. Embed the form on a page
-
-A plain HTML form POST is the default and needs **no JavaScript**: the
-endpoint answers a normal form-encoded POST with a small confirmation
-page (the form's `success_message` + a link back to the page the
-visitor came from). Validation errors get the same treatment. The HTML:
+On an HTML-mode page:
 
 ```html
-<section class="contact-section">
-  <div class="contact-container">
-    <h2>Kontakta oss</h2>
-    <p>Fyll i formuläret så återkommer vi inom 24 timmar.</p>
-
-    <form class="contact-form"
-          action="SUBMIT_URL"
-          method="POST">
-      <!-- The signed token is the only hidden field the platform needs;
-           it encodes org + site + form identity. -->
-      <input type="hidden" name="_token"    value="SIGNED_TOKEN">
-      <!-- Honeypot — must stay empty, bots fill it -->
-      <input type="text"   name="_hp"       style="display:none" tabindex="-1" autocomplete="off">
-
-      <div class="form-group">
-        <label for="name">Namn *</label>
-        <input type="text" id="name" name="name" required>
-      </div>
-
-      <div class="form-group">
-        <label for="email">E-post *</label>
-        <input type="email" id="email" name="email" required>
-      </div>
-
-      <div class="form-group">
-        <label for="message">Meddelande *</label>
-        <textarea id="message" name="message" rows="5" required></textarea>
-      </div>
-
-      <div class="form-group">
-        <label for="subject">Ämne</label>
-        <select id="subject" name="subject">
-          <option value="Prisförfrågan">Prisförfrågan</option>
-          <option value="Samarbete">Samarbete</option>
-          <option value="Övrigt">Övrigt</option>
-        </select>
-      </div>
-
-      <button type="submit" class="btn-primary">Skicka meddelande</button>
-    </form>
-  </div>
+<section class="newsletter-signup">
+  <h2>Få våra nyheter</h2>
+  <x-form id="newsletter" />
 </section>
-
-<style>
-.contact-section{padding:4rem 2rem}
-.contact-container{max-width:600px;margin:0 auto}
-.form-group{margin-bottom:1.5rem}
-.form-group label{display:block;font-weight:600;margin-bottom:0.4rem;font-size:0.9rem}
-.form-group input,.form-group textarea,.form-group select{
-  width:100%;padding:0.75rem 1rem;border:1px solid var(--color-surface);
-  border-radius:0.375rem;font-family:inherit;font-size:1rem;
-  background:var(--color-surface);color:var(--color-text)
-}
-.form-group textarea{resize:vertical}
-.btn-primary{
-  background:var(--color-primary);color:#fff;border:none;
-  padding:0.875rem 2rem;border-radius:0.375rem;font-size:1rem;
-  font-weight:600;cursor:pointer;width:100%
-}
-.btn-primary:hover{opacity:0.9}
-</style>
 ```
 
-**Replace:**
-- `SUBMIT_URL` → `submit_url` from `read_form` / `create_form`
-- `SIGNED_TOKEN` → `submit_token` from the same response
+`<x-form>` is not a browser-side shortcode. It is replaced during server
+preview/build, so it also supports multi-step forms and never needs inline JS.
 
-### 4. Inline feedback (optional — requires user action)
+## Multi-step form
 
-**The page sanitizer strips inline `<script>` from page and partial
-HTML**, so you cannot ship fetch-based submit handling yourself — a
-`<script>` you put in `html_content` is silently removed. The plain
-POST above is the reliable path; use it.
+For a funnel, write `steps[]` directly. Each step is a block tree containing
+`form/*` field blocks and optional content blocks:
 
-If the customer wants inline feedback without a page reload, the script
-must go into the site's `scripts_body_end` setting, which only a human
-can edit (Settings → Custom code — it's deliberately excluded from the
-AI tool surface). Hand them this snippet for that box; it intercepts the
-form and POSTs the JSON shape `{ token, data }`:
-
-```html
-<script>
-(function(){
-  const form = document.querySelector('.contact-form');
-  if(!form) return;
-  form.addEventListener('submit', async (e) => {
-    e.preventDefault();
-    const btn = form.querySelector('[type=submit]');
-    btn.disabled = true;
-    btn.textContent = 'Skickar…';
-    // The endpoint's fetch contract is JSON: { token, data }.
-    const fd = new FormData(form);
-    const token = fd.get('_token');
-    const data = {};
-    fd.forEach((v, k) => { if (k !== '_token') data[k] = v; });
-    try {
-      const res = await fetch(form.action, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ token, data }),
-      });
-      const json = await res.json();
-      if (res.ok && json.success) {
-        form.innerHTML = '<p class="form-success">' + (json.message || 'Tack!') + '</p>';
-      } else {
-        btn.disabled = false;
-        btn.textContent = 'Skicka meddelande';
-        alert('Något gick fel: ' + ((json.errors && json.errors.join(', ')) || json.error || 'okänt fel'));
-      }
-    } catch {
-      btn.disabled = false;
-      btn.textContent = 'Skicka meddelande';
-      alert('Nätverksfel — försök igen.');
-    }
-  });
-})();
-</script>
+```
+update_form form_id=ansokan patch={steps:[
+  {id:'company', title:'Företag', blocks:[
+    {type:'form/text', data:{name:'company', label:'Företag', required:true}},
+    {type:'form/email', data:{name:'email', label:'E-post', required:true}}
+  ]},
+  {id:'details', title:'Detaljer', blocks:[
+    {type:'form/textarea', data:{name:'message', label:'Meddelande'}},
+    {type:'form/consent', data:{name:'consent', text:'<p>Jag godkänner …</p>'}}
+  ]}
+]}
 ```
 
-### 5. Update the contact page with the form HTML
+Submissions accumulate in one partial record and become complete on the final
+step. Abandoned partials use `partial_ttl_days` (default 30).
 
-```
-update_page page_id="kontakt" patch={
-  "html_content": "<full page HTML including the form section>"
-}
-```
+## Storage and integrations
 
-### 6. Verify
+Completed submissions appear in Forms → Submissions. Admins can configure
+actions in the form editor:
 
-```
-read_form form_id="kontakt"
-list_forms
-```
+- Email notification or autoresponder through the site's email connector.
+- Generic webhook to a public HTTPS endpoint. The admin chooses an explicit
+  field allowlist and signing secret. Typeroll signs the exact request body in
+  `X-Typeroll-Signature`, sends an idempotency key, retries transient failures,
+  and stores delivery status.
 
-Confirm the form appears and fields match what you embedded.
+Actions are deliberately excluded from MCP/API-key writes and reads because
+they can exfiltrate submitted data. Direct the user to the portal form editor
+to configure them.
 
-### 7. Deploy
+## Verify
 
-```
-trigger_deploy
-get_deploy_status job_id=<id>
-```
+1. `read_form form_id="newsletter"` and confirm the steps/fields.
+2. Preview the page and confirm the authoring reference has expanded to a form
+   with `data-tr-form-el`, a signed token, and the platform runtime.
+3. Submit a test entry and confirm it appears in Forms → Submissions.
+4. If a webhook is configured, confirm its delivery status and the receiving
+   system's idempotency key before deploying.
 
-After deploy, test by submitting the live form. Submissions appear in the
-portal at `/app/sites/{siteId}/forms/kontakt/submissions`.
+## Common patterns
 
-## Common form patterns
+Newsletter:
 
-### Booking / appointment request
 ```json
-{"fields": [
-  {"name":"name",  "type":"text",  "label":"Namn",   "required":true},
-  {"name":"email", "type":"email", "label":"E-post",  "required":true},
-  {"name":"date",  "type":"text",  "label":"Önskat datum (YYYY-MM-DD)"},
-  {"name":"time",  "type":"select","label":"Tid",    "options":["09:00","10:00","11:00","14:00","15:00"]},
-  {"name":"notes", "type":"textarea","label":"Kommentar"}
-]}
+{"fields":[{"name":"email","type":"email","label":"E-postadress","required":true}]}
 ```
 
-### Newsletter signup (minimal)
+Contact:
+
 ```json
-{"fields": [
-  {"name":"email", "type":"email", "label":"E-postadress", "required":true}
+{"fields":[
+  {"name":"name","type":"text","label":"Namn","required":true},
+  {"name":"email","type":"email","label":"E-post","required":true},
+  {"name":"message","type":"textarea","label":"Meddelande","required":true}
 ]}
 ```
 
-### Job application
+Booking request:
+
 ```json
-{"fields": [
-  {"name":"name",       "type":"text",  "label":"Namn",      "required":true},
-  {"name":"email",      "type":"email", "label":"E-post",     "required":true},
-  {"name":"role",       "type":"select","label":"Roll",       "options":["Designer","Projektledare","Övrigt"]},
-  {"name":"experience", "type":"textarea","label":"Berätta om dig själv"},
-  {"name":"portfolio",  "type":"url",   "label":"Portfolio-URL"}
+{"fields":[
+  {"name":"name","type":"text","label":"Namn","required":true},
+  {"name":"email","type":"email","label":"E-post","required":true},
+  {"name":"time","type":"select","label":"Tid","options":["09:00","10:00","14:00"]},
+  {"name":"notes","type":"textarea","label":"Kommentar"}
 ]}
 ```
 
 ## Pitfalls
 
-- **Tokens are stable, not expiring.** The `submit_token` stays valid
-  until the platform rotates its signing secret (rare, operator-driven).
-  Bake it into the static HTML; no refresh logic needed. If submissions
-  suddenly 403 after working, re-fetch via `read_form` and republish.
-- **Inline `<script>` does not survive.** The page sanitizer strips it
-  from `html_content` — never rely on client JS you embed yourself. The
-  plain form POST works without it (section 3).
-- **Field names must be lowercase ASCII** (`[a-z][a-z0-9_-]*`):
-  `foretag` not `företag`, `amne` not `ämne`. Labels can be anything.
-- **Don't use the same form_id on two different forms.** IDs must be
-  unique per site — use descriptive names: `kontakt`, `boka`, `nyhetsbrev`.
-- **Honeypot must be invisible.** `_hp` field must have `display:none`.
-  If it's visible and a real user fills it, their submission is rejected.
-- **Email notifications are admin-only — not settable via MCP.** Submissions
-  are stored and visible in the portal's Forms → Submissions inbox. A site
-  admin can also configure post-submission emails (admin notification +
-  autoresponder) under **Forms → <form> → Email**, after setting up an email
-  connector under **Settings → Email & notifications**. These carry recipient
-  addresses + templates over submission data, so they're deliberately off the
-  agent surface (`create_form`/`update_form` ignore `actions`). Point the
-  customer at those screens; you can't set them up for them.
+- Do not hand-write a form, token, honeypot, or submit script.
+- Do not put a raw `<script>` in page HTML; the sanitizer removes it.
+- Do not expose action configuration through agent surfaces.
+- Do not send every submitted field to a webhook by default; choose the
+  smallest allowlist the external register needs.
+- `submit_token` is stable until the platform rotates its form-signing secret;
+  a rebuild refreshes it after rotation.