procesio-cli 0.1.1__py3-none-any.whl

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

@@ -0,0 +1,213 @@
+{
+ "id": "692c2088-9097-5ffc-a64d-47f858663f4d",
+ "category": "fields",
+ "type": "textarea",
+ "configs": [
+  {
+   "id": "ea4a2e0e-136e-5910-ac19-23cefe045fa4",
+   "key": "label",
+   "label": "Label",
+   "placeholder": "Add label here",
+   "category": "content",
+   "subCategory": "general",
+   "type": "input",
+   "value": "Textarea",
+   "exposed": true
+  },
+  {
+   "id": "4add7686-6c85-5267-bc84-c040077eaea5",
+   "key": "placeholder",
+   "label": "Placeholder",
+   "category": "content",
+   "subCategory": "general",
+   "type": "input",
+   "value": "Single line or multi line text area",
+   "exposed": true
+  },
+  {
+   "id": "7fa7fc91-25c0-5a9b-bde9-111902d10620",
+   "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": "3f18ce1e-899c-579f-bf8f-78a959ab2cc3",
+   "key": "info-text",
+   "label": "Info text",
+   "placeholder": "Add info text here",
+   "category": "content",
+   "subCategory": "general",
+   "type": "input",
+   "value": "",
+   "exposed": true
+  },
+  {
+   "id": "c29906d5-2ea0-5da4-9d42-891655a4823d",
+   "key": "rows",
+   "label": "Rows",
+   "placeholder": "Add textarea rows here",
+   "category": "content",
+   "subCategory": "general",
+   "type": "number-input",
+   "value": 4,
+   "exposed": true
+  },
+  {
+   "id": "a2eb7693-ac0a-5329-9914-879768399f30",
+   "key": "defaultValue",
+   "label": "Default value",
+   "placeholder": "Add default value here",
+   "category": "content",
+   "subCategory": "general",
+   "type": "textarea",
+   "value": "",
+   "exposed": true,
+   "events": [
+    "REMAP"
+   ]
+  },
+  {
+   "id": "dd7d6dea-ef63-53fd-a690-9f64b69c2ef1",
+   "key": "value",
+   "label": "Value",
+   "category": "content",
+   "subCategory": "general",
+   "type": "hidden",
+   "value": "",
+   "exposed": true,
+   "events": [
+    "EMIT_INPUT"
+   ]
+  },
+  {
+   "id": "6b9e8f09-f0ef-5854-9fd2-d513527427c6",
+   "key": "readonly",
+   "label": "Readonly",
+   "category": "content",
+   "subCategory": "general",
+   "type": "readonly-or-disabled",
+   "value": false,
+   "exposed": true
+  },
+  {
+   "id": "629cdeaf-7967-5e9f-80e5-81640dbecc79",
+   "key": "disabled",
+   "label": "Disabled",
+   "category": "content",
+   "subCategory": "general",
+   "type": "hidden",
+   "value": false,
+   "exposed": true
+  },
+  {
+   "id": "5d77b1d9-b07d-5cf4-aa0b-750046773bc8",
+   "key": "visible",
+   "label": "Visible",
+   "category": "content",
+   "subCategory": "general",
+   "type": "toggle",
+   "value": true,
+   "exposed": true
+  },
+  {
+   "id": "6a2a1890-1363-5d87-ad8f-bbc12e5f5621",
+   "key": "name",
+   "label": "Name",
+   "category": "content",
+   "subCategory": "general",
+   "type": "input",
+   "value": "Textarea",
+   "hasTopDivider": true,
+   "exposed": true,
+   "events": [
+    "REMAP",
+    "EMIT_ELEMENTS_UPDATE"
+   ]
+  },
+  {
+   "id": "828dce18-ea46-5c35-98eb-336f99c9914c",
+   "key": "id",
+   "label": "ID",
+   "placeholder": "Add ID here",
+   "category": "content",
+   "subCategory": "general",
+   "type": "copyable-input",
+   "value": "textarea",
+   "exposed": true
+  },
+  {
+   "id": "898ff157-0e88-5c37-941d-8c55d4e2c220",
+   "key": "required",
+   "label": "Required",
+   "category": "content",
+   "subCategory": "validation",
+   "type": "toggle",
+   "value": false,
+   "exposed": true
+  },
+  {
+   "id": "807e7681-87f0-525e-b522-12d217e80764",
+   "key": "regex",
+   "label": "Regex",
+   "placeholder": "Add regex for validation here",
+   "category": "content",
+   "subCategory": "validation",
+   "type": "input",
+   "value": "",
+   "exposed": true
+  },
+  {
+   "id": "7bae3a4b-f69a-5977-bc39-f4ecd935d6e7",
+   "key": "type",
+   "label": "",
+   "category": "content",
+   "subCategory": "general",
+   "type": "hidden",
+   "value": "textarea"
+  },
+  {
+   "id": "e69b9858-b9c2-57f9-977a-ed2ad0e2794e",
+   "key": "onInputEvents",
+   "label": "onInput",
+   "category": "content",
+   "subCategory": "events",
+   "type": "field-events",
+   "value": null
+  },
+  {
+   "id": "4a947b5f-af98-52b7-afe8-00162f29685a",
+   "key": "onFocusEvents",
+   "label": "onFocus",
+   "category": "content",
+   "subCategory": "events",
+   "type": "field-events",
+   "value": null
+  },
+  {
+   "id": "1aa29a1b-bda4-5b4d-b7ee-00a0a6441388",
+   "key": "onBlurEvents",
+   "label": "onBlur",
+   "category": "content",
+   "subCategory": "events",
+   "type": "field-events",
+   "value": null
+  },
+  {
+   "id": "4ae8796c-47d4-581e-ae4b-9696c5bb1991",
+   "key": "style",
+   "label": "Style",
+   "category": "styling",
+   "subCategory": "general",
+   "type": "hidden",
+   "value": []
+  }
+ ],
+ "parentId": null,
+ "section": "body"
+}

procesio_cli/tools/procesio/dto/form/enum_map.json

@@ -0,0 +1,68 @@
+{
+  "_README": "FALLBACK enum -> string-value map for sync_from_mock.py. The AUTHORITATIVE source is docs_info/form-config-enums.ts (the frontend's real enums, parsed directly); this file is used only if that TS file is absent, and as a manual override for members not in it. ElementType and ElementCategory are NOT here: they are defined inside FormBuilder mock.ts and parsed from it directly (authoritative). The four ElementConfig* enums are imported by the mock from '../config' (not shipped), so their values are resolved here. Members listed below are AUTHORITATIVE (verified against real goldens, or known exceptions). Any member used by the mock but NOT listed here is resolved by the fallback rule and reported as UNVERIFIED -- get the real value from the frontend (see UNVERIFIED-ENUMS-QUESTION.md) and paste it here, then re-run.",
+  "_fallback_rule": "MEMBER_NAME.lower().replace('_','-')  e.g. SOURCE_TYPE -> source-type",
+  "_exceptions_proving_the_rule_is_not_enough": {
+    "READONLY_OR_DISABLED_TOGGLE": "value is 'readonly-or-disabled' (the _TOGGLE suffix is dropped)",
+    "CONTOLS": "frontend enum identifier is misspelled; value is correctly 'controls'"
+  },
+  "ElementConfigCategory": {
+    "CONTENT": "content",
+    "STYLING": "styling"
+  },
+  "ElementConfigEvent": {
+    "REMAP": "REMAP",
+    "EMIT_INPUT": "EMIT_INPUT",
+    "EMIT_ELEMENTS_UPDATE": "EMIT_ELEMENTS_UPDATE"
+  },
+  "ElementConfigSubCategory": {
+    "GENERAL": "general",
+    "VALIDATION": "validation",
+    "EVENTS": "events",
+    "ACTION": "action",
+    "APPROVALS": "approvals",
+    "DATA_SOURCE": "data-source",
+    "TASK_ASSIGNEE": "task-assignee",
+    "CONTOLS": "controls",
+    "RULES": "rules"
+  },
+  "ElementConfigType": {
+    "INPUT": "input",
+    "NUMBER_INPUT": "number-input",
+    "TEXTAREA": "textarea",
+    "SELECT": "select",
+    "TOGGLE": "toggle",
+    "HIDDEN": "hidden",
+    "COPYABLE_INPUT": "copyable-input",
+    "INPUT_TYPE_SELECT": "input-type-select",
+    "READONLY_OR_DISABLED_TOGGLE": "readonly-or-disabled",
+    "FIELD_EVENTS": "field-events",
+    "TEMPLATE_ONLY": "template-only",
+    "BUTTON_SUBMIT_TOGGLE": "button-submit-toggle",
+    "CLEARABLE_SELECT": "clearable-select",
+    "SOURCE_TYPE": "source-type",
+    "SOURCE_VALUE": "source-value",
+    "DATETIME_DEFAULT_VALUE": "datetime-default-value",
+    "DATE_TIME_MODE_SELECT": "date-time-mode-select",
+    "ICON_PICKER": "icon-picker",
+    "DROPDOWN_ITEMS": "dropdown-items",
+    "USER_SELECT": "user-select",
+    "APPROVER_REPLACEMENT": "approver-replacement",
+    "ASSIGNEE_REPLACEMENT": "assignee-replacement",
+    "UPLOAD_FILE_TYPE_SELECT": "upload-file-type-select",
+    "VIEW_FILE_TYPE_SELECT": "view-file-type-select",
+    "VIEWER_TYPE_RADIO": "viewer-type-radio",
+    "URL_OR_FILE": "url-or-file",
+    "URL_TARGET_SELECT": "url-target-select",
+    "OPEN_SIDE_PANEL_BUTTON": "open-side-panel-button",
+    "FUNCTION": "function",
+    "HTML_CODE_EDITOR": "html-code-editor",
+    "COLUMN_LIST": "column-list",
+    "ROW_LIST": "row-list",
+    "TAB_LIST": "tab-list",
+    "ROW_CELL_APPROVALS": "row-cell-approvals",
+    "RULES_VISIBILITY": "rules-visibility",
+    "TABLE_COLUMNS_SOURCE_TYPE": "table-columns-source-type",
+    "TABLE_COLUMNS_SOURCE_VALUE": "table-columns-source-value",
+    "TABLE_PAGINATION": "table-pagination"
+  }
+}

procesio_cli/tools/procesio/dto/form/fieldpath.py

@@ -0,0 +1,284 @@
+"""The one definition of a form FIELD VALUE PATH — how it is built, and what makes one valid.
+
+A process addresses a form field by a four-segment path:
+
+    {formDataModelRootId}.{FIELDS_NS}.{elementId}.{valueConfigId}
+
+Two places produce such a path and they must not drift: the DTO builder writes them while
+BUILDING a form from a config (it knows every id it just minted), and `form-set-element-event`
+has to check or produce them against a LIVE form it fetched. The builder's rule lived only in
+its own build pass, so the surgical action could not reuse it and simply passed whatever the
+caller sent straight through.
+
+Why a wrong path is worth this much code: nothing rejects it. The API accepts the row and
+answers `updated: true`, the designer renders the mapping, and the control silently launches
+nothing — measured across five autonomous builds, every one of which wrote
+`root.fields.<elementId>.value`, substituting the NAMES from the guide's tree diagram for the
+ids printed beside them. There is no error to read, so the only place the mistake can be caught
+is before the write.
+"""
+from __future__ import annotations
+
+from tools.procesio.errors import UsageError
+
+# The platform's "fields" container id. Constant across every form (verified against real
+# production forms); it is not read from the form and must not be.
+FIELDS_NS = "11223344-5566-7788-99aa-aabbccddeeff"
+
+# The config key that carries a control's value, where it is not `value`. A `file-viewer` has
+# no `value` config at all — its content lives in `src` (type url-or-file).
+VALUE_CONFIG_KEY = {"file-viewer": "src"}
+
+SEGMENTS = 4
+
+
+def value_key(el_type) -> str:
+    """The config key holding this control's field value."""
+    return VALUE_CONFIG_KEY.get(el_type, "value")
+
+
+def build(root_id: str, element_id: str, value_config_id: str) -> str:
+    return f"{root_id}.{FIELDS_NS}.{element_id}.{value_config_id}"
+
+
+def looks_like_path(value) -> bool:
+    """A caller that sent a path rather than a field name — right or wrong.
+
+    Deliberately shape-only: this asks WHICH branch to take, never whether the path is
+    correct. Treating "has dots" as "is valid" is exactly the hole that let the invented
+    `root.fields.<id>.value` through untouched.
+    """
+    return isinstance(value, str) and value.count(".") == SEGMENTS - 1
+
+
+def _config_id(element: dict, key: str):
+    for c in element.get("configs") or []:
+        if c.get("key") == key:
+            return c.get("id")
+    return None
+
+
+def _name_of(element: dict):
+    for c in element.get("configs") or []:
+        if c.get("key") == "name":
+            v = str(c.get("value") or "").strip()
+            return v or None
+    return None
+
+
+class LiveForm:
+    """The field index of a form as it exists on the server: what its root is, which
+    elements it has, and each one's value-config id."""
+
+    def __init__(self, form: dict):
+        data = (form or {}).get("data") or {}
+        self.root_id = str(((data.get("dataModel") or {}).get("id")) or "")
+        self.elements = data.get("elements") or []
+        self.by_id: dict[str, dict] = {}
+        self.by_name: dict[str, list[dict]] = {}
+        for el in self.elements:
+            eid = el.get("id")
+            if not eid:
+                continue
+            self.by_id[str(eid)] = el
+            name = _name_of(el)
+            if name:
+                self.by_name.setdefault(name, []).append(el)
+        # Form variables (Offer_ID, isConfirmed…) are mapped by their own id, and the form's
+        # data model also carries the platform's `instance` tree (instance.currentUser.email…),
+        # addressed as root.<attr id>.<attr id>…; both are as valid on a map row as a field.
+        self.variables: dict[str, dict] = {}
+        self.variable_ids: dict[str, dict] = {}
+        for v in data.get("variables") or []:
+            if not v.get("id") or not v.get("name") or v.get("name") == "form":
+                continue                      # `form` is the data-model handle, not a value
+            self.variables[str(v["name"])] = v
+            self.variable_ids[str(v["id"])] = v
+        self.model = data.get("dataModel") or {}
+
+    def is_variable(self, value) -> bool:
+        return isinstance(value, str) and value in self.variable_ids
+
+    def variable_for(self, value):
+        """`@Name`, or a bare name no field carries, or the variable's id -> the variable."""
+        if not isinstance(value, str):
+            return None
+        if value.startswith("@"):
+            return self.variables.get(value[1:])
+        if value in self.variable_ids:
+            return self.variable_ids[value]
+        if value not in self.by_name:
+            return self.variables.get(value)
+        return None
+
+    def model_path(self, value):
+        """A dotted NAME path into the form's data model (instance.currentUser.email) -> its
+        id path, or None when the first name is not a top-level attribute of the model."""
+        if not isinstance(value, str) or "." not in value or not self.root_id:
+            return None
+        names = value.split(".")
+        attrs, ids = self.model.get("attributes") or [], []
+        for i, nm in enumerate(names):
+            hit = next((a for a in attrs if a.get("name") == nm), None)
+            if hit is None:
+                if i == 0:
+                    return None
+                known = ", ".join(sorted(a.get("name", "") for a in attrs)) or "(none)"
+                raise UsageError(f"{value!r}: {nm!r} is not an attribute of "
+                                 f"{'.'.join(names[:i])!r}; it has: {known}")
+            ids.append(str(hit["id"]))
+            attrs = hit.get("attributes") or []
+        return ".".join([self.root_id] + ids)
+
+    def _model_ids_ok(self, path: str) -> bool:
+        parts = str(path).split(".")
+        if len(parts) < 2 or parts[0] != self.root_id or parts[1] == FIELDS_NS:
+            return False
+        attrs = self.model.get("attributes") or []
+        for pid in parts[1:]:
+            hit = next((a for a in attrs if str(a.get("id")) == pid), None)
+            if hit is None:
+                return False
+            attrs = hit.get("attributes") or []
+        return True
+
+    def value_config_id(self, element: dict):
+        return _config_id(element, value_key(element.get("type")))
+
+    def field_names(self) -> list[str]:
+        """Names of the elements that can actually carry a value — the only ones a map row
+        may point at, so an error message must not offer the others."""
+        return sorted(n for n, els in self.by_name.items()
+                      if any(self.value_config_id(e) for e in els))
+
+    def path_for_name(self, name: str) -> str:
+        els = self.by_name.get(name) or []
+        if not els:
+            raise UsageError(
+                f"{name!r} is not a field on this form. Fields that can carry a value: "
+                f"{', '.join(self.field_names()) or '(none)'}")
+        if len(els) > 1:
+            raise UsageError(
+                f"{len(els)} elements are named {name!r}; pass the element id or the full "
+                f"value path instead")
+        el = els[0]
+        vcid = self.value_config_id(el)
+        if not vcid:
+            raise UsageError(
+                f"element {name!r} (type {el.get('type')!r}) has no "
+                f"{value_key(el.get('type'))!r} config, so it holds no value and cannot be "
+                f"mapped")
+        return build(self.root_id, str(el["id"]), str(vcid))
+
+    def element(self, ref: str) -> dict:
+        """One element by id, else by its unique `name` config."""
+        if ref in self.by_id:
+            return self.by_id[ref]
+        els = self.by_name.get(ref) or []
+        if len(els) == 1:
+            return els[0]
+        if not els:
+            raise UsageError(f"{ref!r} is not an element on this form (by id or name)")
+        raise UsageError(f"{len(els)} elements are named {ref!r}; pass the element id instead")
+
+    def config_path(self, ref: str, key: str) -> str:
+        """The path of ANY config of an element (`disabled`, `visible`, `label`…), not only its
+        value. A MAP_FORM_DATA row and a condition address a config the same way a process
+        addresses the value: the fourth segment is that config's own id, which the data model
+        reuses as the attribute id. Same failure mode as a wrong value path, so same refusal."""
+        el = self.element(ref)
+        cid = _config_id(el, key)
+        if not cid:
+            keys = ", ".join(c.get("key", "") for c in el.get("configs") or []
+                             if not str(c.get("key", "")).startswith("on"))
+            raise UsageError(f"element {ref!r} (type {el.get('type')!r}) has no {key!r} config; "
+                             f"it has: {keys}")
+        return build(self.root_id, str(el["id"]), str(cid))
+
+    def check(self, path: str, where: str) -> None:
+        """Raise unless `path` addresses a real value-bearing field of THIS form.
+
+        Every segment is checked against the live form and the message names the right
+        answer: a caller that guessed the shape has no other way to learn it, because the
+        platform accepts the wrong one without complaint.
+        """
+        parts = str(path).split(".")
+        problems: list[str] = []
+        if len(parts) != SEGMENTS:
+            raise UsageError(
+                f"{where}: {path!r} is not a form value path. It must have {SEGMENTS} "
+                f"segments: {{formDataModelRootId}}.{{FIELDS_NS}}.{{elementId}}."
+                f"{{valueConfigId}} — or pass the field NAME instead and it will be "
+                f"resolved for you. Fields: {', '.join(self.field_names()) or '(none)'}")
+
+        root, ns, element_id, value_id = parts
+        if root != self.root_id:
+            problems.append(f"segment 1 {root!r} must be this form's data-model root "
+                            f"{self.root_id!r}")
+        if ns != FIELDS_NS:
+            problems.append(f"segment 2 {ns!r} must be the fields container id {FIELDS_NS!r}")
+
+        element = self.by_id.get(element_id)
+        if element is None:
+            problems.append(f"segment 3 {element_id!r} is not an element on this form")
+        else:
+            expected = self.value_config_id(element)
+            own_configs = {str(c.get("id")) for c in element.get("configs") or [] if c.get("id")}
+            if value_id in own_configs and value_id != str(expected):
+                pass                          # a config of THIS element (label, visible, src…)
+            elif not expected:
+                problems.append(
+                    f"segment 3 {element_id!r} is a {element.get('type')!r}, which has no "
+                    f"{value_key(element.get('type'))!r} config and holds no value")
+            elif value_id != str(expected):
+                # The subtle one: four guid-shaped segments, but the value id belongs to a
+                # different element. Nothing downstream notices.
+                problems.append(f"segment 4 {value_id!r} must be that element's own "
+                                f"{value_key(element.get('type'))!r} config id {expected!r}")
+
+        if not problems:
+            return
+
+        hint = ""
+        if element is not None and self.value_config_id(element):
+            correct = build(self.root_id, element_id, str(self.value_config_id(element)))
+            name = _name_of(element)
+            hint = f"\n  correct path: {correct}"
+            if name:
+                hint += f"\n  or just pass the field name: {name}"
+        else:
+            hint = ("\n  pass the field NAME instead and it will be resolved: "
+                    + (", ".join(self.field_names()) or "(no value-bearing fields)"))
+
+        raise UsageError(f"{where}: {path!r} is not a valid value path on this form.\n  "
+                         + "\n  ".join(problems) + hint)
+
+    def resolve(self, value, where: str) -> str:
+        """A map row's form side -> a validated value path.
+
+        Three inputs, three outcomes: a known field NAME is built into its path; a path is
+        checked and passed through; anything else is refused with the field list. The middle
+        case is the one that matters — it is what every observed failure sent.
+        """
+        if isinstance(value, str) and value in self.by_name and not value.startswith("@"):
+            return self.path_for_name(value)
+        var = self.variable_for(value)
+        if var is not None:
+            return str(var["id"])
+        if isinstance(value, str) and self._model_ids_ok(value):
+            return value                      # an id path into the instance tree, already valid
+        if isinstance(value, str) and value.count(".") == 1:
+            ref, key = value.split(".")
+            if ref in self.by_id or ref in self.by_name:   # Paragraph9.label, Section3.visible
+                return self.config_path(ref, key)
+        mp = self.model_path(value)
+        if mp is not None:
+            return mp
+        if looks_like_path(value):
+            self.check(value, where)
+            return value
+        raise UsageError(
+            f"{where}: {value!r} is neither a field on this form, a form variable (@name), a "
+            f"data-model path (instance.currentUser.email) nor a full value path. "
+            f"Fields that can carry a value: {', '.join(self.field_names()) or '(none)'}; "
+            f"variables: {', '.join(sorted(self.variables)) or '(none)'}")

procesio_cli/tools/procesio/dto/form/fixtures/reg.config.json

@@ -0,0 +1,32 @@
+{
+  "name": "Reg",
+  "browserTitle": "Register",
+  "type": "general",
+  "elements": [
+    {
+      "type": "heading",
+      "label": "Title"
+    },
+    {
+      "type": "input",
+      "label": "Full Name",
+      "name": "fullName",
+      "required": true,
+      "placeholder": "John"
+    },
+    {
+      "type": "select",
+      "label": "Country",
+      "name": "country",
+      "options": [
+        "RO",
+        "US"
+      ]
+    },
+    {
+      "type": "button",
+      "label": "Submit",
+      "submit": true
+    }
+  ]
+}