procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/dto/form/description.md

@@ -0,0 +1,346 @@
+# Form Template sub-tool
+
+Create/edit/publish a PROCESIO **form**. The layout is a tree of controls in
+`Data.elements`. **Proven live (2026-06-24):** the runtime renders from `elements`
+— the encrypted `Data.code` blob is NOT needed (a form with `code:""` rendered
+fine), so forms are fully buildable server-side.
+
+## Config
+
+```json
+{
+  "name": "Registration",
+  "type": "general",
+  "browserTitle": "Register",
+  "elements": [
+    {"type": "heading",  "label": "Registration Form"},
+    {"type": "paragraph","label": "<p>Please fill in your details.</p>"},
+    {"type": "input",    "label": "Full Name", "name": "fullName", "required": true, "placeholder": "John Doe"},
+    {"type": "number-input", "label": "Age", "name": "age"},
+    {"type": "select",   "label": "Country", "name": "country", "options": ["Romania", "USA"]},
+    {"type": "radiobox", "label": "Plan", "name": "plan", "options": ["Free", "Pro"]},
+    {"type": "checkbox", "label": "Subscribe", "name": "subscribe"},
+    {"type": "textarea", "label": "Comments", "name": "comments"},
+    {"type": "section",  "label": "Group", "children": [ {"type": "input", "label": "Nested"} ]},
+    {"type": "button",   "label": "Submit", "submit": true}
+  ]
+}
+```
+
+- **elements** — each control: `type` + common props (`label`, `name`, `required`,
+  `placeholder`, `tooltip`, `readonly`, `visible`, `default`). `options` for
+  select/radiobox/dropdown (strings or `{name,value}`). `children` for containers
+  (section/columns/column/tabs/tab). `configs` (object) sets any raw config key.
+- **control types** (from harvested goldens): heading, paragraph, input, textarea,
+  number-input, datetime-input, select, dropdown, radiobox, checkbox, button,
+  divider, section, columns, column, tabs, tab, table, image, file-upload,
+  file-viewer, icon, list, approval, … (see `dto/form/elements/`).
+- **type** — `general` (1) or `usertask` (0). When omitted, a form whose controls carry an
+  assignee or approver (or that has an `assignee` control) is built as `usertask`, like the
+  designer saves it; otherwise `general`. **publish** — Status PUBLISHED(1)/DRAFT(0).
+- **data model** — the builder writes the same form data model the designer writes for a NEW
+  form: top-level `instance, flow, fields, preventFormSubmit, browserTitle` and
+  `dataModelAttributeFormatVersion: "1"` (field attributes named exactly as the element name).
+  Captured from a designer save on QA, 2026-09-25.
+
+## Events, triggers, tasks, themes (Phase 2)
+
+- **events** — per control: `"events":[{"on":"click","do":"js","code":"alert(1)"}]`.
+  `on` ∈ click/input/change/focus/blur/hover/ready/open/close/tabchange/rowadded/
+  rowdeleted/paginated/stepchange/nextstep/previousstep/beforeapprove/afterapprove/
+  beforereject/afterreject/beforeapprovalsubmit/afterapprovalsubmit/messagesfetch/
+  messagesent (each fires on a control that has that slot; type/key verified vs
+  ui-builder trigger.ts + EventType enum).
+  `do` ∈ **map** (`mapping:[{to,value|from}]`), **process** (`processId,syncRun,
+  inputs:[{to,from}],outputs`), **js** (`code`), **form** → EventAction.TRIGGER_FORM
+  (`formId`,`mapping`).
+- **tasks/assignees** — `assignee`/`assigneeReplacement` on section/tabs/table;
+  `approver`/`approverReplacement` on the `approval` control. The form's top-level
+  **`Assignees`** list is what the designer shows as the task routing: rows
+  `{StepId, OrderId, Type, Users:[{UserId}]}`, `StepId` = the element id (or a dynamic table
+  row's approval-step id), `Type 1` = assignee, `Type 2` = approver. It is DERIVED from those
+  configs the way the designer's save does (`builder.derive_assignees`): one ASSIGNEE step per
+  control with assignee users, then one APPROVER step per approval control and per visible
+  dynamic-row approval step, `OrderId` 1, 2, 3… within each list, users as `{userId}` (the
+  platform adds the names). `form-create` / `form-edit` write it; `form-add-element`,
+  `form-delete-element` and `form-set-element-config` re-derive it when the change touches who
+  works or approves a step, and report the before/after. A config-level `assignees` list still
+  wins verbatim. Checked against 19 designer-saved forms on QA (2026-10-05): identical lists.
+  (Until 2026-10-05 the builder left the list empty and the workaround was to PUT the GET echo
+  with `Assignees` added; that is no longer needed.)
+- **theme** — `"theme":{"--c-primary":"#0039e3","--p-form":"24px"}` overrides the
+  form theme variables (colors, fonts, spacing, per-control styling). ~190 vars in 18
+  groups (see `data_shell.json` / `docs_info/form-theme.ts`).
+- **form CSS / JavaScript** — the designer's "Switch to code" editor:
+  `"css":"...", "javascript":"..."` (or `"code":{"css","javascript"}`). Encrypted into
+  `Data.code` (CryptoJS AES; key in Credential Manager, one per environment:
+  `procesio/form-code-key@<environment>`). Empty →
+  `code:""`. See `code_cipher.py` + `FORM-STYLING-NOTES.md`.
+- **per-component style** — on any field/container control:
+  `"style":{"--h-input":"50px","--c-input-background":"--c-neutral--50"}`. Only the
+  control's CSS-group vars are valid (input/number/datetime/textarea/select → Input group);
+  color vars take a theme color variable, not a hex. Stored as enabled CSSProperty[] in the
+  element's `style` config.
+- **all properties** — any control config is settable via the named convenience
+  keys (label, placeholder, required, options, src, width, …) or the raw `configs`
+  passthrough; containers nest via `children` (built FLAT with `parentId`, the
+  structure PROCESIO renders).
+- **table** — `{"type":"table","label":"Items","columns":[{"key":"product","label":"Product","cell":{"type":"input"}},{"key":"qty","label":"Qty","cell":{"type":"number-input"}}]}`
+  builds the table + a row + the cell controls (wired via `childrenIdPerColumn`).
+  Also `section`/`columns`(+`column`)/`tabs`(+`tab`) containers with `children`.
+
+## Submit / status messages (`Data.messages`, verified live 2026-09-30)
+
+The screen shown after submit comes from `Data.messages`, a list of
+`{type, title, text, customizable}` seeded from `data_shell.json` in ENGLISH
+(`SUBMIT_SUCCESS` = "Your message has been sent. Thank you for filling out our form!").
+Types: SUBMIT_SUCCESS, SUBMIT_FOR_APPROVAL_SUCCESS, APPROVE_SUCCESS, REJECT_SUCCESS,
+SUBMIT_FAILED, FILES_UPLOAD_FAILED, NOT_FOUND, NOT_ALLOWED, NOT_AUTHORIZED
+(`ui-builder-main/src/js/model/index.ts`). For a non-English form, localize at least
+SUBMIT_SUCCESS and SUBMIT_FAILED: `form-get`, edit the entries, then
+`form-update --data-file` with `{"messages":[...the FULL list...]}` (send the whole list).
+
+**Readable public URL.** Besides `forms.procesio.app/{tinyUrl}`, a form's CustomUrl slug is
+served at `forms.procesio.app/{masterSlug}/{workspaceSlug}/{formSlug}`; read the two parent
+slugs with `get-customurl-workspace-master` and `get-customurl-workspace`.
+
+## Form JavaScript: fields are keyed LOWERCASE (critical, 2026-07-27)
+
+> **Cause found (2026-09-25, confirmed 2026-10-05).** The re-key below comes from the data
+> model's `dataModelAttributeFormatVersion`. The designer reads a form with no version as the
+> legacy format `"0"` (user-playground `Builder.component.vue`), and under `"0"` its save
+> renames every field attribute to camelCase-of-lowercase (`Form.model.ts::
+> generateFormDataModel`; measured: `RequestText` → `requesttext`, and the 2026-10-01
+> measurements below). Under `"1"` it keeps the name as written. Designer-made forms carry
+> `"1"`; this builder wrote no version until 2026-10-05, which is why API-built forms were
+> re-keyed on their first designer save. **It now writes `"1"`**: measured on QA 2026-10-05,
+> `orderList`, `order_id` and `Customer_First_Name` survived a designer re-publish and form JS
+> read them as written. So `formlint.lint_field_names` warns only for a form WITHOUT the
+> version. Forms already saved as `"0"` keep their re-keyed names, so the case-insensitive
+> lookup below is still the safe way to read fields in a script that may run on such a form.
+
+**`ProcesioForm.data.fields` keys are the field name LOWERCASED** (and a UI save re-derives them). JS is case-sensitive, so a camelCase reference like `ProcesioForm.data.fields.locuiesteDetalii` (or `.zonaFormular`, `.actProprietate`) is `undefined` — the event fires but silently does NOTHING (this cost days on Uranus 100: a UI save lowercased the keys and every camelCase visibility/hide/file-wrap toggle broke, while the config still looked perfect). **ALWAYS reference form fields case-insensitively** in any control/FORM_LOAD RUN_JAVASCRIPT. Prelude, then use `fld(name)`:
+
+**Corrected 2026-10-01, measured: a designer save re-keys the fields.** A form built through
+the API (`form-create`) keeps its names exactly as written. One save and Publish in the
+designer changed them: a camelCase name came back all lowercase, and a snake_case one came
+back camelCase (`orderList` to `orderlist`, `order_id` to `orderId`). Both fit one rule: split the name on underscores, lowercase the parts, join
+them in camelCase. A name with no separator therefore comes out all lowercase, which is
+what the note above saw. (Two names measured; hyphens and spaces were not tested.) So the
+trap springs late, the first time anyone saves an API-built form in the designer, and a
+lowercase snake_case name is not safe either. Only a single lowercase word survives
+unchanged. Read everything else through a lookup that ignores case AND separators, as
+below. The same save also adds a select's `sourceType` and `sourceValue` to the data
+model. `form-create` left them out until 2026-10-01 and now writes them for a static
+option list (`todo/procesio-form-create-select-source-in-data-model.md`). When a config gives no `name`, the builder now derives a single lowercase word from the label (`Company Name` becomes `companyname`), so an auto-named field survives a designer save unchanged; an explicit name is kept verbatim, and `form-create` / `form-edit` return a `warnings` entry when a name is not a single lowercase word. (Since 2026-10-05 the builder writes `dataModelAttributeFormatVersion: "1"`, under which a designer save keeps names as written, so that warning now fires only for a form without the version; see the note at the top of this section.)
+
+```js
+var F=ProcesioForm.data.fields;var _fl={};for(var _k in F){_fl[_k.toLowerCase().replace(/[_-]/g,'')]=F[_k];}
+function fld(n){return _fl[String(n).toLowerCase().replace(/[_-]/g,'')];}
+var x=fld("locuiesteDetalii"); if(x){ x.visible=need; x.required=need; }
+```
+
+Applies to EVERY field reference: visibility toggles, submit-button hide/show, file-value wrapping, reading another field’s `.value`, etc. (`f.locuieste` only “works” because it has no uppercase letter to lose.)
+
+## Control wiring cookbook (verified live 2026-06-29)
+
+- **image** — `src` must be a LIVE url (a 404 shows the alt text as broken "brand"). Use
+  `{"type":"image","src":"https://…","alt":"…","width":200}`.
+- **dropdown** — it is an action MENU, not a value field. Populate via
+  `configs:{items:[{id:<guid>,icon:"content_copy",label:"Duplicate",type:"BUTTON"},{type:"DIVIDER"}]}`.
+- **file-viewer** — `src` is `URL_OR_FILE` → accepts a plain URL. Preview a doc with
+  `{"type":"file-viewer","src":"https://…/x.pdf","configs":{"viewerType":"INLINE","allowedFileTypes":["pdf"],"viewerHeadline":"…"}}`.
+  Empty src renders "Field source not set".
+- **multiple file-upload / array-valued controls** — a `file-upload` (or `select`) with `multiple:true`, plus `list`/`table`/`dynamic-table-row`, are ARRAY-valued: the builder types their `value` config **`isList:true` + default `[]`** (helper `_value_is_list`) AND the DM `value` attribute `isList:true`. REQUIRED — else the runtime emits a SINGLE object for one uploaded file and a `List<File>` process input fails AT LAUNCH: `Error generating fileId … item is not an array: StartObject` (statusCode 373). Confirmed by Liza; locked by `test_form_events.py`.
+- **conditional field visibility (show/hide one field based on another's value)** — verified live
+  2026-07-24 (confirmed by Liza). A `RUN_JAVASCRIPT` **INPUT** event on the trigger control that
+  toggles the target field's `.visible` AND `.required` together. TWO things that MUST be right,
+  or it silently fails:
+  1. **The target field must start REGISTERED.** Set the field `visible:true` in the config so
+     PROCESIO instantiates it, then hide it on load with a **form-level `FORM_LOAD`
+     `RUN_JAVASCRIPT`** (`ProcesioForm.data.fields.<field>.visible=false; …required=false;`). A
+     field that starts `visible:false` is NEVER instantiated → `ProcesioForm.data.fields.<field>`
+     is `undefined` → the toggle throws `Cannot set properties of undefined (setting 'visible')`
+     and the field can never appear. (This is the whole bug — NOT that hiding "destroys" the
+     element; a registered field toggles both ways fine.)
+  2. **A radio/select `.value` is a plain STRING** (the selected option's text, e.g.
+     `"Nu, e închiriat…"`), NOT an object — compare it directly, no `typeof v==='object'` /
+     `v.value` / `v.label` handling.
+  Event code: `var f=ProcesioForm.data.fields; var v=(f.locuieste.value||''); var need=(v.indexOf('Nu')===0); var x=f.locuiesteDetalii; if(x){x.visible=need; x.required=need;}`.
+  Guard the read (`var x=…; if(x){…}`). Toggling `.required` with `.visible` keeps a hidden field
+  from blocking submit. NOTE: PROCESIO's `rules-visibility` config ("Visibility:" panel) is NOT a
+  field-condition rule — it's only user-access (`all`/`task-assignees`/`custom`); use the JS event
+  above for value-driven visibility.
+- **chart** — types `bar`/`line`/`combo`/`pie` (+ flags `donut`/`stacked`/`horizontal`/`smooth`).
+  Data via `configs`: `categoriesSourceType:"JSON"` + `categoriesSourceValue` = a JSON STRING of
+  labels; `seriesSourceType:"JSON"` + `seriesSourceValue` = a JSON STRING. Cartesian series =
+  `[{name,data:[..],type?,smooth?,yAxisIndex?}]` (combo sets per-series `type`+`yAxisIndex` for
+  dual-axis); pie/donut series = flat `[{name,value}]`. `colors` is a JSON-string array. Canonical
+  examples: `docs_info/Exports/charts.procesio`.
+- **side-panel** — set `configs:{buttonText:"…",sidePanelTitle:"…"}`; its `children` render a
+  full mini-form inside the slide-over. AVOID `select`/`dropdown` inside a side-panel: their
+  pop-up overlay mis-positions and offsets the panel layout (the panel is a fixed/transformed
+  container). Use `radiobox`/`checkbox`/`input` (inline) for choices in a side panel.
+- **chat (reply via a process)** — verified live 2026-06-29. The chat renders from its `value`
+  array (`Chat.component.vue`: `messages = JSON.stringify(attrs.value)`); a static mount `value`
+  does NOT render, but a reactive value-write does. Wire the reply on **`messagesent`**:
+  `events:[{"on":"messagesent","do":"process","processId":…,"syncRun":true,"inputs":[{"to":"history","from":"<chatName>"}],"outputs":[{"to":"<chatName>","from":"<msgsVar>"}]}]`.
+  On send the chat appends the user message to `value` then fires the event, so `history`
+  (<- chat value) already includes it; the process returns the FULL updated array -> written back
+  to chat value -> re-renders. The chat value attr is auto-typed json+isList (builder `_VALUE_LIST`).
+  Produce the array with a **Node** action (`return msgs;` -> bind `List Result` = a clean array;
+  JS `setOutput` wraps `{result}` and won't map cleanly — see process `description.md` Scripting).
+  Message schema (team-confirmed): required `_id, content, senderId, roomId, timestamp`(string).
+  A bot reply's **`senderId` = `"procesio"`** (baked-in bot user → renders on the other side; user
+  messages use the live currentUserId); **`roomId` MUST equal `rooms[0].roomId`** or it's filtered
+  out → "No messages"; **do NOT set a `date` field** (it created empty date-separator badges — use
+  `timestamp`). The component creates USER messages with `timestamp:""` (empty), so user bubbles
+  show no time — since the process returns the whole list, **backfill any empty `timestamp`** (e.g.
+  `for (m of msgs) if(!m.timestamp) m.timestamp="HH:MM"`) before returning. **Local time:** the Node
+  action runs server-side in UTC, so a raw `new Date()` shows SERVER time, not the user's. Pass the
+  browser UTC offset into the process and compute local time: a hidden `input` field set by form JS
+  (`-new Date().getTimezoneOffset()` minutes), added to the chat's RUN_PROCESS `inputs` (e.g.
+  `{to:"tzOffset", from:"tzoffset"}`), then in Node `const d=new Date(Date.now()+off*60000)` and read
+  `d.getUTCHours()/getUTCMinutes()` (correct regardless of server TZ). Optional: `username,
+  date, system, avatar, seen`. `onMessagesFetch` fires ONCE on
+  mount to load history; `onMessageSent` → process returns the ENTIRE list. Wire the reply on
+  `messagesent` only (reusing the reply process on `messagesfetch` stuck the chat on "loading" in
+  testing). Set `configs:{userId, rooms:[{roomId,roomName,users}]}`.
+- **CSS stacking gotcha:** never put `animation`/`transform`/`opacity<1`/`filter` on the
+  control wrapper `.form-builder--element` — each becomes its own stacking context that traps
+  a select/dropdown overlay (the `.multiselect__content-wrapper`, z-index 50) UNDER the later
+  sibling controls (it renders transparent / behind, e.g. behind a button). Verify overlay
+  stacking with `document.elementFromPoint` (web tool `eval` step).
+- **interactive widgets (5-star rating, char counter, live greeting)** — done in form-level
+  JavaScript, NOT a control. The JS runs inside `iframe.trigger-sandbox`, so the form doc is
+  `window.parent.document`; build into a control wrapper by id (e.g. `#starIcon`) and keep it
+  alive with a small `setInterval` (tabs render lazily). DON'T force a font on `#app *` — it
+  turns Material-Icons ligatures (info/close) into literal text; scope fonts to text elements.
+- **The `trigger-sandbox` iframe is TRANSIENT — never leave a listener or timer inside it
+  (proven live 2026-08-05).** Form-level JS is executed by injecting it into an
+  `iframe.trigger-sandbox` whose `srcdoc` the platform rewrites per run, and the iframe is
+  REMOVED from the DOM afterwards. Removing an iframe destroys its JS realm, so every
+  `addEventListener` and `setInterval` registered from that code dies with it — while any DOM
+  node the code created in the parent document REMAINS. The failure is therefore silent and
+  deeply misleading: the widget renders correctly at form load, then freezes at whatever value it
+  last showed, with no console error and the node still on screen. It looks like "the widget
+  broke on <some user action>" when in truth the action merely coincided with the teardown.
+  Confirmed by a controlled A/B: an interval registered inside a transient iframe advanced 0
+  ticks after removal, while one injected into the parent kept ticking.
+  **The fix — hoist the code into the parent realm.** From the sandbox, append a `<script>` to
+  `window.parent.document` whose body is the widget, so the closure, its listeners and its timer
+  all belong to the parent window, which outlives the sandbox:
+  ```js
+  var D = window.parent.document;
+  if (D.getElementById("my-widget")) return;      // idempotent: the sandbox may re-run
+  function widget() { /* runs in the parent; `document` IS the form document */ }
+  var s = D.createElement("script");
+  s.id = "my-widget";
+  s.textContent = "(" + widget.toString() + ")();";
+  D.body.appendChild(s);
+  ```
+  Use `Function.prototype.toString()` rather than a hand-escaped string literal — the widget stays
+  readable and there is no quote-escaping to get wrong. Give the injected `<script>` a stable `id`
+  and bail out when it already exists, or a sandbox re-run installs a second copy with a second
+  interval. Anything that must merely RUN ONCE at load (seeding a value, a one-shot toggle) is
+  fine directly in the sandbox; only continuous behaviour needs hoisting.
+  The installer pattern itself — parent realm, stable id guard, `fn.toString()` — is
+  documented in full in [`../../FORM-DEV-GUIDE/02-CODE-INJECTION.md`](../../FORM-DEV-GUIDE/02-CODE-INJECTION.md)
+  sections 3 and 4. What this entry adds is the controlled A/B that MEASURES the
+  teardown: 0 ticks after removal inside the sandbox, versus an interval injected into
+  the parent that kept running.
+- **The form UI is styled with Vue SCOPED CSS — a hand-built node renders UNSTYLED (2026-08-05).**
+  Every platform-rendered element carries a `data-v-<hash>` attribute and the stylesheet is written
+  as `.pds-c-message[data-v-<hash>] { display:flex; … }`. A node built with `createElement` has no
+  such attribute, so the scoped rules never match it: copying the platform's class list alone is
+  NOT enough. The symptom is a widget that works but looks wrong — in the observed case the message
+  container fell back to `display:block`, stacking the icon above the text instead of beside it,
+  while the identical-looking native node next to it was `flex`. **Never hardcode the hash** (it
+  changes on every frontend rebuild). Instead **clone an existing native node of the same kind**
+  and overwrite its text — `cloneNode(true)` carries the scope attributes, the exact inner markup
+  and the theme, for free:
+  ```js
+  var tpl = document.querySelector(".pds-c-message-info:not(.my-widget)");
+  var node = tpl ? tpl.cloneNode(true) : buildFallback();   // fallback: also set inline display:flex
+  node.classList.add("my-widget");
+  ```
+  Exclude your own node from the template query or the second render clones the clone. Also mirror
+  the native inner structure when hand-building: the icon is a `<div class="pds-c-message--icon">`
+  WRAPPING an `<i class="material-icons …">`, and the text is a `<div class="pds-c-message--text">`
+  — not `<i>`/`<span>` carrying those classes directly.
+  **Prefer avoiding the whole problem:** when a control has a config that renders the node natively
+  (e.g. a non-empty `info-text`), set it in the designer and have the widget merely rewrite that
+  node's text. Two forms that differ only by such a config will otherwise diverge visually while
+  running byte-identical JS — which reads as "the same script broke on the other form".
+- **`info-text` is NOT writable from `ProcesioForm.data.fields` (verified live 2026-08-05).**
+  The runtime renders it from the element's STATIC config array
+  (`Element.component.vue`: `v-if="getConfigValueByKey(element.configs,'info-text')"`), not from
+  the reactive field-value object. The field object exposes only `value`, `visible`, `required`,
+  `readonly` — so `…fields.<name>.infoText = …` is a silent no-op, and there is no
+  `setConfigValue`-style API exposed to form JS. Two consequences: (a) drive any live text
+  (character counters, running totals, remaining-quota hints) by writing the **DOM node**, not a
+  config; (b) when `info-text` is EMPTY the message component is never rendered at all (`v-if` on
+  a truthy value), so there is no node to write into — either set a non-empty `info-text` in the
+  designer so the platform renders `.pds-c-message-info`, or create that node yourself. A robust
+  widget does both: reuse `host.querySelector('.pds-c-message-info')` if present, else append a
+  node carrying the platform's own classes
+  (`pds-c-message pds-c-message-info pds-c-message-small pds-c-message-ghost pds-u-m--t--8`)
+  so it inherits the theme. **The control's DOM `id` equals its `name` config** and sits on the
+  `.pds-c-input-group` wrapper, not on the `<input>`/`<textarea>` — so `getElementById(<name>)`
+  then `.querySelector('textarea')` is the reliable way in, and renaming the field breaks the
+  selector. Bind updates with a capturing `input` listener filtered to that element (cheap: it
+  only acts on the one field) plus a small `setInterval` for lazy/re-rendered containers; guard
+  the write with an `if (node.textContent !== next)` so the interval costs nothing when idle.
+  A DOM-injected node survives the element's normal re-renders (validation state changes), but it
+  is invisible to the designer — it lives only in the form JS.
+- **form JS that handles dropdown/menu item clicks** — use ONE document click listener (clicks
+  aren't continuous → no layout thrash/flicker; never a document-wide `input` listener or
+  `setInterval` poll). **CRITICAL gotcha (verified 2026-06-29):** to detect WHICH menu item was
+  clicked, do NOT substring-match `textContent` up the ancestor chain — an ancestor holds the
+  WHOLE menu, so every label (incl. "Clear form") is present and a click ANYWHERE outside the open
+  dropdown fires the first-matched action (this CLEARED the form on outside-click). Match only an
+  element whose own text contains **exactly one** known label (a single item); ignore any node
+  holding >1 (the menu container / page wrapper). Framework inputs are controlled — clear/set via
+  the native value setter + `input`+`change` events (`HTMLInputElement.prototype` value setter),
+  not `el.value=`. Verify by reproducing: set fields, open the menu, click OUTSIDE → fields must be
+  UNCHANGED; then click the real item → it acts.
+- **responsive table (no horizontal scroll)** — default cell inputs are ~fixed-width and the table
+  is `table-layout:auto`, so >3 columns overflow. Force fluid equal columns:
+  `#app .pds-c-table{width:100%!important;table-layout:fixed}`, `th,td{min-width:0!important;overflow:hidden}`,
+  `.pds-c-input-group--field/--wrapper{width:100%!important;min-width:0!important}`,
+  `[class*=table][class*=scroll], .form-builder--table{overflow-x:visible!important}`.
+
+## API contract (verified live 2026-06-24)
+
+- **Create:** `POST /api/FormTemplate` (`FormTemplateDto`) — client supplies `Id`, returns it.
+- **Get:** `GET /api/FormTemplate/{id}`. **Edit:** `PUT /api/FormTemplate`. **Delete:** `DELETE /api/FormTemplate/{id}`.
+- **Publish:** `Status=1` + `State=true` on the body (or `PATCH /api/FormTemplate/{id}?state=true`).
+- **Public vs private:** DTO field `IsPrivate` (config key `isPrivate`, default false; designer
+  "Make form public" toggle = `!isPrivate`). **`isPrivate:false` is necessary but NOT sufficient:**
+  a form that **contains an approval control** — or has assignees/approvers — can ONLY be private;
+  the platform disables the toggle and keeps it private regardless of the config value (the
+  presence of the approval control, not a configured approver, triggers this). To truly make a form
+  public, remove any approval control / assignees / approvers. Verify the actual toggle state in
+  the designer, not just the DTO field.
+- **Render:** create a CustomUrl — `POST /api/CustomUrl/FormTemplate {Type:3, EntityType:1, EntityId, Url}`
+  → `tinyUrl`; open **`https://forms.procesio.app/{tinyUrl}`**. (A bare `/forms/{id}`
+  has no workspace context and 404s — the CustomUrl carries the workspace.)
+- **Query-param pre-fill (VALIDATED live, undocumented by PROCESIO):** the public form
+  reads URL query parameters and pre-fills any control whose **binding `name`** equals
+  the query key. Open `…/{tinyUrl}?<controlName>=<value>` and the control renders with
+  that value. Verified 2026-07-22: a form with controls `name:"cod"` + `name:"apartament"`
+  opened at `?cod=TEST123&apartament=27` rendered both inputs pre-filled. The match is on
+  the control's config `name` (the field/binding name), NOT the DOM `id`/`name` (which are
+  empty on the rendered `<input>`). Use this to seed a form from a link (e.g. a per-record
+  token). Unmatched params are ignored.
+  **Also works on a PRIVATE form** (one with an approval control) opened by a signed-in user: measured
+  2026-10, six `?name=value` params pre-filled their inputs with no console or network errors. Use it
+  to hand an approver a link that carries the record's data when the triggering action cannot.
+
+## How it builds (template-merge)
+
+Each control clones a captured golden element (`dto/form/elements/<type>.json`) so
+every config field stays valid; the builder assigns fresh ids, pins a clean
+`section`/`parentId` (golden elements were harvested from arbitrary containers),
+forces `visible:true`, resets `required`/placeholders, and overrides the semantic
+configs. theme/messages/dataModel/variables come from `data_shell.json`.

procesio_cli/tools/procesio/dto/form/elements/approval.json

@@ -0,0 +1,259 @@
+{
+ "id": "dc5057d1-7bac-5f57-b464-57089ffa4a36",
+ "category": "fields",
+ "type": "approval",
+ "configs": [
+  {
+   "id": "09f55d0d-e541-5f56-892f-18c0931f5ec3",
+   "key": "label",
+   "label": "Label",
+   "placeholder": "Add label here",
+   "category": "content",
+   "subCategory": "general",
+   "type": "input",
+   "value": "Approval step",
+   "exposed": true
+  },
+  {
+   "id": "a38f2e9f-cbe1-5c48-ba9d-6229558ddee7",
+   "key": "tooltip",
+   "label": "Tooltip",
+   "placeholder": "Add tooltip here",
+   "tooltip": "Tooltip can only be displayed with Label",
+   "category": "content",
+   "subCategory": "general",
+   "type": "input",
+   "value": "",
+   "exposed": true
+  },
+  {
+   "id": "7e5c5930-1c7d-54d5-8314-ab28390a9e1c",
+   "key": "description",
+   "label": "Description",
+   "placeholder": "Add text here",
+   "category": "content",
+   "subCategory": "general",
+   "type": "input",
+   "value": "Please review this submission and approve/reject.",
+   "exposed": true
+  },
+  {
+   "id": "a25cc026-4324-512c-9f16-81773fa820dc",
+   "key": "info-text",
+   "label": "Info text",
+   "placeholder": "Add info text here",
+   "category": "content",
+   "subCategory": "general",
+   "type": "input",
+   "value": "",
+   "exposed": true
+  },
+  {
+   "id": "1701612b-4ee5-5a15-a17e-ee414514c2c1",
+   "key": "visible",
+   "label": "Visible",
+   "category": "content",
+   "subCategory": "general",
+   "type": "toggle",
+   "value": true,
+   "exposed": true
+  },
+  {
+   "id": "59e20081-ac77-5378-9a83-ad3099302807",
+   "key": "comment",
+   "label": "Comment",
+   "placeholder": "",
+   "category": "content",
+   "subCategory": "general",
+   "type": "hidden",
+   "value": "",
+   "exposed": true
+  },
+  {
+   "id": "e32a20e7-5e43-50df-95e3-6b21a10ab948",
+   "key": "responseDate",
+   "label": "Response date",
+   "placeholder": "",
+   "category": "content",
+   "subCategory": "general",
+   "type": "hidden",
+   "value": null,
+   "exposed": true
+  },
+  {
+   "id": "c3038a05-34b7-5232-8f41-f09f18b8d99b",
+   "key": "responseUser",
+   "label": "Response user",
+   "placeholder": "",
+   "category": "content",
+   "subCategory": "general",
+   "type": "hidden",
+   "value": null,
+   "exposed": true
+  },
+  {
+   "id": "b9a25636-e5cd-57f9-9bf6-c4100369a34a",
+   "key": "response",
+   "label": "Response",
+   "placeholder": "",
+   "category": "content",
+   "subCategory": "general",
+   "type": "hidden",
+   "value": null,
+   "exposed": true
+  },
+  {
+   "id": "70a2a842-0f88-5396-85cc-e632f265ada7",
+   "key": "name",
+   "label": "Name",
+   "category": "content",
+   "subCategory": "general",
+   "type": "copyable-input",
+   "value": "Approval",
+   "hasTopDivider": true,
+   "exposed": true,
+   "events": [
+    "EMIT_ELEMENTS_UPDATE"
+   ]
+  },
+  {
+   "id": "c321b7b1-1f06-5adc-8bf4-0515020392ff",
+   "key": "id",
+   "label": "ID",
+   "placeholder": "Add ID here",
+   "category": "content",
+   "subCategory": "general",
+   "type": "copyable-input",
+   "value": "approval",
+   "exposed": true
+  },
+  {
+   "id": "e2c20d67-d165-57cc-b234-b9edccee8c32",
+   "key": "approver",
+   "label": "Approver",
+   "placeholder": "Select name",
+   "category": "content",
+   "subCategory": "approvals",
+   "type": "user-select",
+   "value": ""
+  },
+  {
+   "id": "1092181b-d9bc-55c5-8614-a49350321c8c",
+   "key": "approverReplacement",
+   "label": "Approver replacement",
+   "category": "content",
+   "subCategory": "approvals",
+   "type": "approver-replacement",
+   "value": null
+  },
+  {
+   "id": "83a53e18-ff68-524c-bb53-905c74792658",
+   "key": "additionalApprovers",
+   "label": "",
+   "category": "content",
+   "subCategory": "task-assignee",
+   "type": "hidden",
+   "value": []
+  },
+  {
+   "id": "1e45aa83-3f52-5fd0-903a-5b74c226af2d",
+   "key": "commentRequiredOnApprove",
+   "label": "Is comment required on approve",
+   "category": "content",
+   "subCategory": "validation",
+   "type": "required-comment",
+   "value": false,
+   "exposed": true
+  },
+  {
+   "id": "8c015e51-ef4d-5679-8c17-6d5a1159509f",
+   "key": "commentRequiredOnReject",
+   "label": "Is comment required on reject",
+   "category": "content",
+   "subCategory": "validation",
+   "type": "hidden",
+   "value": false,
+   "exposed": true
+  },
+  {
+   "id": "6f2c9b03-c4ae-548c-a5e2-141fe1ff3268",
+   "key": "onInputEvents",
+   "label": "onInput",
+   "category": "content",
+   "subCategory": "events",
+   "type": "field-events",
+   "value": null
+  },
+  {
+   "id": "9e30bc34-e3dd-5ba2-9a1b-d20a7321fb9e",
+   "key": "onBeforeApproveEvents",
+   "label": "onBeforeApprove",
+   "tooltip": "Triggered once Approve button is clicked but before the form is submitted",
+   "category": "content",
+   "subCategory": "events",
+   "type": "field-events",
+   "value": null
+  },
+  {
+   "id": "08142bb8-6e86-52fa-91fc-75921e8aa04e",
+   "key": "onBeforeRejectEvents",
+   "label": "onBeforeReject",
+   "tooltip": "Triggered once Reject button is clicked but before the form is submitted",
+   "category": "content",
+   "subCategory": "events",
+   "type": "field-events",
+   "value": null
+  },
+  {
+   "id": "06444609-2c4d-5210-b49e-92389213381e",
+   "key": "onBeforeApprovalSubmitEvents",
+   "label": "onBeforeSubmit",
+   "tooltip": "Triggered once any Approval's button is clicked but before the form is submitted",
+   "category": "content",
+   "subCategory": "events",
+   "type": "field-events",
+   "value": null
+  },
+  {
+   "id": "fef86e40-fc6c-520c-bd07-6aaab9345173",
+   "key": "onAfterApproveEvents",
+   "label": "onAfterApprove",
+   "tooltip": "Triggered once Approve button is clicked but after the form is submitted",
+   "category": "content",
+   "subCategory": "events",
+   "type": "field-events",
+   "value": null
+  },
+  {
+   "id": "772caf56-471e-5c4f-97c0-83da94299e23",
+   "key": "onAfterRejectEvents",
+   "label": "onAfterReject",
+   "tooltip": "Triggered once Reject button is clicked but after the form is submitted",
+   "category": "content",
+   "subCategory": "events",
+   "type": "field-events",
+   "value": null
+  },
+  {
+   "id": "2339b4a5-d535-5d8c-9fdd-a2cef89031d7",
+   "key": "onAfterApprovalSubmitEvents",
+   "label": "onAfterSubmit",
+   "tooltip": "Triggered once any Approval's button is clicked but after the form is submitted",
+   "category": "content",
+   "subCategory": "events",
+   "type": "field-events",
+   "value": null
+  },
+  {
+   "id": "56060b99-bbd1-54a7-ad23-1ec50d184bfa",
+   "key": "style",
+   "label": "Style",
+   "category": "styling",
+   "subCategory": "general",
+   "type": "hidden",
+   "value": []
+  }
+ ],
+ "parentId": null,
+ "section": "body"
+}