@zestl/zvolv-widgets 0.0.0 → 0.0.1

package/README.md

@@ -709,6 +709,8 @@ precision, prefix, suffix, accept, maxSizeKB, maxCount, childIds, pages, html, s
 | `section` `container` `tabs` `steps` `matrix` `table` | GROUP_VIEW subtypes, STEPPER, TAB, MATRIX, TABLE_START | `form.childrenOf(field)` + `<FormFields>` |
 | `sheet` | INPUT_SHEET, NESTED_FORM, INPUT_CHILD_WIDGET | `useSheetField` (rows are posted before the parent) |
 | `action` | ACTION_BUTTON, TRIGGER_AUTOMATION, CASCADED_ACTIONS | `form.runAction(field)` |
+| `trials` | INPUT_PERCENT_CORRECT, INPUT_TIME_SAMPLING, INPUT_TASK_ANALYSIS (ABA trial widgets) | `useTrialField` (response / prompt buttons, trials, timer, steps, % correct, log) |
+| `onbehalf` | ON_BEHALF_OF | read-only; `field.displayText` is the user's name |
 | `comments` `system` | COMMENTS, ON_BEHALF_OF, INPUT_IP, INPUT_DEVICE_INFO | system fields are filled automatically and never shown |
 
 **Dependent lookups.** A `FETCH_OPTIONS_FILTERS` rule sits on the lookup it filters, as in
@@ -719,19 +721,39 @@ value, clears the selection when the source changes, and auto-selects when exact
 (rule on a non-lookup driver, `elementId` = the lookup) is still read. `cascade(source, target, masterField)` writes
 the platform shape.
 
+**Type coverage.** Every element type ZAI-Dashboard's FormFieldRouter and zvolv-web's z-form-widgets render has a kind. Aliases: `SCAN` → `INPUT_SCAN`, `HTML_TEXT` → `TEXT_VIEW`, `TRIGGER_AUTOMATION` → an action button, `ACTION_DROPDOWN` → an action with `field.variant === "dropdown"` whose `field.options` are its actions (`form.runAction(field, label)` runs only the picked one, as in zvolv-web). `INPUT_CARD_CONTAINER` is commented out in zvolv-web and is not supported. Like zvolv-web, any `attributes.subType` that is a known type replaces `type` — so an element saved as `INPUT_SHORT_TEXT` with subType `INPUT_PERCENT_CORRECT` (and `dataType: "OBJECT"`) is a trial widget. `DOWNLOAD_FILE` / `PRINT_PREVIEW` fall back to `properties.url` when the button has no value.
+
+**Trial widgets** (`useTrialField(form, field)`): the configuration comes from the stored value's `conf` (ZAI) over `element.properties` (zvolv-web): `ResponseButtons` (with `PromptButtons`), `maximumNumberOfTrials`, `minimumNumberOfTrials`, `LinkedTimerField`, `timeLimit` / `timeInterval`, `steps` and `type` (forward / backward / whole). Values match ZAI: `{ conf, buttonResp, lastStatus? , currentStatus? }`. `minimumNumberOfTrials` is checked on submit for percent correct and time sampling.
+
 **Field parity with ZAI-Dashboard / zvolv-web.**
 
 - **Options load on focus.** Call `o.onFocus()` from your control's focus/open handler. Lookups and people search fetch nothing until then, as in zvolv-web (`nzFocus → onFocus`) and ZAI (`handleFocus`). Lookups re-fetch on later focuses (throttled to 2 s); people search re-fetches only when it has nothing loaded. Dependency-filtered lookups still load as soon as their source is set. Pass `useFieldOptions(form, field, { loadOn: "mount" })` for the old behaviour.
 - **Single vs multi** comes from `properties.maxResults` for FORM_SEARCH, INPUT_TAG and AUTO_COMPLETE (1 = single). `toggle` refuses picks past the limit; `o.maxCount` and `o.atLimit` tell the control.
 - **INPUT_TAG** can store a value that isn't in the list: `o.addFreeTag(text)` stores `{ view, select, extraLabels: [] }`.
 - **ExtraLabels auto-fill is off by default.** Neither platform copies a picked row's ExtraLabels into other fields; use a `FETCH_OPTIONS_FILTERS` dependent lookup. Opt in with `{ autofillExtraLabels: true }`.
+- **Signed-in user is decrypted** like ZAI-Dashboard `getStoredUser()`: the host's `readUser`, else the SDK's `readUserFromStorage()`, else `client.auth.userInstance` through `decryptAuthObject`. Values still `enc::…` are dropped, and forms re-read the user on the SDK's `zvAuthCryptReady` event. Pass `createZvolvRuntime({ client, readUser: readUserFromStorage })` to be explicit.
 - **ON_BEHALF_OF** has kind `"onbehalf"`. It is shown read-only, stores the signed-in user's id (never a role id), shows `field.displayText` (the user's name), and isn't overwritten by automation `formData`.
 - **CHECK_BOX** with `attributes.showAsSwitch` gets `field.variant === "switch"`. `"1"` is read as true.
 - **DATE_PICKER** `dynamicDefault` supports `ADD` and `SUB`, any unit (`days`, `weeks`, `months`, `years`, `hours`), a bare number of days, and the `DynamicDefault` key. `field.dateFormat` is `properties.format` converted to dayjs tokens (default `DD/MM/YYYY`).
 - **RICH_TEXT_EDITOR**: markup with no text (`<p><br></p>`, `&nbsp;`) counts as empty and is sent as `null`. `field.maxLength` also reads `attributes.charactersCount`.
 - **FILE_UPLOAD_V2**: the count limit also reads `allowedFileMaxCount` and `properties.max` (1 for `ShowAsProfileImagePicker`). Blocked extensions (`.exe`, `.bat`, `.js`, … — `BLOCKED_FILE_EXTENSIONS`) are refused.
 - **INPUT_SHEET**: `useSheetField` returns `canAdd` / `canDelete` (from `allowedAddActions`, `allowedDeleteActions` or `allowedActions`), `maxRows` and `limitMessage`. Saved rows load without marking the form dirty. Row validation skips hidden, disabled and non-input columns and untouched saved rows.
-- **Action buttons** (`form.runAction`): `actionType` comes from `properties.actionType` or `subType`. `OPEN_URL` (default; falls back to `defaultValue`), `SUBMIT`, `TRIGGER_AUTOMATION` (also treats `code` 400/500 as an error), and `UPDATE` / `UPDATE_SUBMISSION` / `UPDATE_OPEN_NEW_FORM` / unknown types (set the button `true`, then save). `SAVE_SUBMISSION`, `CREATE_SUBMISSION`, `EDIT_SUBMISSION`, `OPEN_TASK`, `PRINT_PREVIEW`, `INVOKE_AGENT` and the like open other UI, so they go to your `onAction`; the library no longer submits the current form for `SAVE_SUBMISSION`.
+- **Action buttons** (`form.runAction`) handle every actionType ZAI-Dashboard and zvolv-web do. `actionType` = `properties.actionType` ?? `attributes.subType` ?? `properties.subType` ?? `OPEN_URL`.
+
+  | actionType | What runs |
+  | --- | --- |
+  | `OPEN_URL` / `URL` | opens `properties.url`, the button's value, or `defaultValue` |
+  | `TRIGGER_AUTOMATION` | `invokeTriggers(triggerID)`; `automationType: "ZENO"` uses `invokeNuclioAutomation(automationUuid)`. `formData` is written back; `code` 400/500 or `error` is a failure; `refreshForm` / `refreshFormDelay` reloads a saved record |
+  | `INVOKE_AGENT` | `invokeAgent({ content: { query } }, flowId, agentId)` with a label-keyed body; the reply's `formData` is written back |
+  | `DOWNLOAD_FILE` | downloads the button's value (a URL), `properties.fileName` |
+  | `PRINT_PREVIEW` | loads the PDF at the button's value and opens the print dialog |
+  | `UPLOAD_FILE` | file picker → upload (card upload when `cardID` is set) → stores the file URL in the button |
+  | `UPDATE`, `UPDATE_SUBMISSION`, `UPDATE_OPEN_NEW_FORM`, `EDIT_OPEN_NEW_FORM`, unknown | sets the button `true`, then saves |
+  | `SUBMIT` | saves the form |
+  | `CREATE_SUBMISSION`, `EDIT_SUBMISSION`, `SAVE_SUBMISSION`, `OPEN_TASK`, `OPEN_PROJECT` | open other screens: handle in `onAction`; `openFormRequest(field, form)` gives `{ formId, submissionId, mode, defaultValues (inputMap) }` |
+  | `CASCADED_ACTIONS` | runs `actionEleIds` in order, stops at the first failure, then saves when `submit` is true |
+
+  `successMessage`, `errorMessage` and `hideSuccessMessage` shape the returned message; `form.reload()` re-fetches the record.
 
 **Show / hide / mandatory rules (triage).** These match ZAI-Dashboard's `applyDependencies`:
 
@@ -745,6 +767,24 @@ the platform shape.
 `formData` back into the form). Pass `onAction` to `<ZvolvForm>` for host actions such as
 "open another form".
 
+### Inspector (validation, rules, filters, formulas, payload)
+
+`useFormInspector(form)` (or the pure `inspectForm(form)`) explains what the engine is doing for the current values. Every verdict comes from the same functions the form uses, so a host can draw an inspector panel without re-implementing anything:
+
+| Key | What it holds |
+| --- | --- |
+| `rules` | each dependency / triage rule: source value, expected value, effect (show / hide / required / optional / editable / read-only), target, `matched` |
+| `filters` | each lookup filter (FETCH_OPTIONS_FILTERS, DynamicFilters, StaticFilters) with the feeding value and `active` |
+| `validation` | each input field and sheet cell: checks, current `error` from `validateField`, the error shown to the user |
+| `formulas` | each form and sheet-row formula: inputs, `expected`, `current`, `inSync`, `serverSafe`, `serverFormula` |
+| `defaults` | dynamic and fixed defaults and the value they produced |
+| `payload` | the exact submission body — sheet rows (posted first) and the parent |
+| `summary` | counts for tiles |
+
+**Formulas must use `{Label}` references.** The submission API re-evaluates every INPUT_FORMULA and rejects a mismatch (`Evaluated value "0" and existing value "8000" … do not match`). It resolves only `{Label}`; bare labels (`MUL(Qty, Price)`) evaluate to 0 on the server even though the library computes them. `isServerSafeFormula(formula, labels)` detects this and `toBraceFormula` gives the fix; the inspector flags it per formula.
+
+Sheet row formulas are recalculated by `useSheetField().updateRow` / `addRow` (`computeRowFormulas`), and again before rows are posted.
+
 ### Headless
 
 `useZvolvForm({ formId, mode, submissionId, defaultValues, hiddenFields, skipTypes, onSubmitted })`

package/SKILL.md

@@ -222,7 +222,10 @@ Forms work like widgets: Zvolv owns the behaviour and you own the look.
 
 - Render with `<ZvolvForm formId … />`, or let a `FORM` / `FORM_WIDGET` dashboard widget do it.
 - Style every field once with `<FormKitSlot.Provider value={{ field, form, status, grid }}>`. Switch on `field.kind`, and use `useFieldOptions`, `useFileField`, `useSheetField` and `form.runAction` for behaviour. Never re-implement rules, formulas, lookups or the submit body.
+- Sheet row formulas: call `useSheetField().updateRow` — it recalculates formula cells. For a debug/inspector panel use `useFormInspector(form)` (rules, filters, validation, formulas, defaults, payload).
+- Write formulas with `{Label}` references (`MUL({Qty}, {Price})`). The submission API re-evaluates formulas and reads bare labels as 0, so `MUL(Qty, Price)` is rejected with "Evaluated value \"0\" … do not match". Check with `isServerSafeFormula`.
 - Nested layout: for `section`, `tabs` and `steps` kinds, render `<FormFields form={form} fields={form.childrenOf(field)} />`.
+- Kind `"trials"` (ABA widgets) → draw with `useTrialField`; action `variant === "dropdown"` (ACTION_DROPDOWN) → a select of `field.options`, call `form.runAction(field, label)`.
 - Lookup / people controls must call `o.onFocus()` on focus — options load on focus (zvolv-web / ZAI parity). Single vs multi is `maxResults`; respect `o.atLimit`; INPUT_TAG free text via `o.addFreeTag`. ExtraLabels auto-fill is opt-in (`autofillExtraLabels`); prefer FETCH_OPTIONS_FILTERS. Draw kind `"onbehalf"` read-only with `field.displayText`; checkbox `variant === "switch"`; sheets honour `canAdd` / `canDelete` / `limitMessage`. SAVE_SUBMISSION and other open-UI actions need `onAction`.
 - Triage / show-hide-mandatory rules follow ZAI-Dashboard: `properties.triage` overrides `dependencies`; array values must match the selection exactly; a matching rule beats a non-matching one; hiding keeps the value; `field.error` appears only after submit and clears when the field changes. Don't add reset-on-hide or live "touched" errors in the app.
 - Dependent lookups (`FETCH_OPTIONS_FILTERS`) use the platform shape: the rule sits **on the dependent lookup** — `{ type: "FETCH_OPTIONS_FILTERS", elementId: <source field>, masterField: <label on its source form> }`. `useFieldOptions` filters by the source's value, reports `waitingFor` until it is set, clears the selection when it changes, and auto-selects when exactly one row matches. Build it with `cascade(source, target, masterField)`.