@cxtms/cx-schema 1.9.258 → 1.9.260

package/schemas/components/planner.json

@@ -1 +1,369 @@
-{"$schema":"http://json-schema.org/draft-07/schema#","title":"Planner Component","type":"object","required":["component","props"],"properties":{"component":{"const":"planner"},"name":{"type":"string"},"props":{"type":"object","required":["queries","rows","columns","itemTemplate"],"properties":{"height":{},"refreshHandler":{"type":"string"},"debug":{"type":"boolean"},"options":{"type":"object","properties":{"enableVirtualization":{"type":"boolean"},"virtualizeThreshold":{"type":"number"},"estimatedRowHeight":{"type":"number"}},"additionalProperties":true},"queries":{"type":"array","minItems":1,"items":{"type":"object","required":["name","query"],"properties":{"name":{"type":"string"},"query":{"type":"object"},"itemsPath":{"type":"string"},"parentAs":{"type":"string"},"mapping":{"type":"object"}},"additionalProperties":true}},"rows":{"type":"object","required":["groupBy","headerWidth"],"properties":{"groupBy":{"type":"string"},"fromQuery":{"type":"string"},"key":{"type":"string"},"label":{},"orderBy":{"type":"array"},"unassigned":{"type":"object"},"headerWidth":{"type":"number"}},"additionalProperties":true},"columns":{"type":"object","required":["width"],"properties":{"orderBy":{"type":"array"},"appendEmpty":{"type":"boolean","description":"Keep one trailing empty slot beyond the largest group."},"label":{},"width":{"type":"number"}},"additionalProperties":true},"rowHeaderTemplate":{"$ref":"../schemas.json#/definitions/component"},"itemTemplate":{"$ref":"../schemas.json#/definitions/component"},"emptyCellTemplate":{"$ref":"../schemas.json#/definitions/component"},"summaryComponent":{"$ref":"../schemas.json#/definitions/component"},"emptyStateTemplate":{"$ref":"../schemas.json#/definitions/component"},"itemAccent":{},"itemGroups":{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"headerTemplate":{"$ref":"../schemas.json#/definitions/component"},"accent":{},"dotsMenu":{"type":"object"}},"additionalProperties":false},"dragSource":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"data":{},"canDrag":{}},"additionalProperties":false},"events":{"type":"object","additionalProperties":{"$ref":"../schemas.json#/definitions/actionsList"}}},"additionalProperties":true}},"additionalProperties":true}
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Planner Component",
+  "type": "object",
+  "required": [
+    "component",
+    "props"
+  ],
+  "properties": {
+    "component": {
+      "const": "planner"
+    },
+    "name": {
+      "type": "string",
+      "description": "Component instance name for referencing in actions/variables"
+    },
+    "props": {
+      "type": "object",
+      "required": [
+        "queries",
+        "rows",
+        "columns",
+        "itemTemplate"
+      ],
+      "properties": {
+        "height": {
+          "default": 700,
+          "description": "Board height; drives the vertical scroll viewport"
+        },
+        "refreshHandler": {
+          "type": "string",
+          "description": "Named refresh channel: `- refresh: <this name>` re-runs the queries and rebuilds the board even when no query variable changed (e.g. after a mutation from an item template). Defaults to the component name.",
+          "x-example": "driverPlannerData"
+        },
+        "debug": {
+          "type": "boolean",
+          "default": false,
+          "description": "Log per-stage pipeline counts (extracted N -> M rows -> K columns, orphan count, resolved paths) through logger"
+        },
+        "options": {
+          "type": "object",
+          "properties": {
+            "enableVirtualization": {
+              "type": "boolean",
+              "default": true,
+              "description": "false forces plain (non-virtualised) rendering"
+            },
+            "virtualizeThreshold": {
+              "type": "number",
+              "default": 50,
+              "description": "Row count above which rows virtualise (TanStack Virtual, measured heights)"
+            },
+            "estimatedRowHeight": {
+              "type": "number",
+              "default": 220,
+              "description": "Initial row height estimate; real heights are measured after mount"
+            }
+          },
+          "additionalProperties": true
+        },
+        "queries": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "query"
+            ],
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "Query name; rows.fromQuery references the rows source by this name"
+              },
+              "query": {
+                "type": "object",
+                "description": "GraphQL query configuration",
+                "properties": {
+                  "command": {
+                    "description": "GraphQL document string"
+                  },
+                  "variables": {
+                    "description": "Query variables (template expressions supported). Changing any referenced variable re-runs the query and rebuilds the board."
+                  },
+                  "path": {
+                    "description": "Plain dot-path into the response (getObj; no [] segments here)"
+                  }
+                }
+              },
+              "itemsPath": {
+                "type": "string",
+                "description": "Items sources only. Path relative to the query.path result, resolved with expandPath: every array-valued segment flat-maps automatically (no leading []; explicit [] segments are accepted no-ops). Missing/null segments yield []. Omitted -> the path result itself, normalized to an array.",
+                "x-example": "orderMoves"
+              },
+              "parentAs": {
+                "type": "string",
+                "description": "Items sources only. Attaches the direct owner of the final flattened collection to every item under this key (e.g. item.order).",
+                "x-example": "order"
+              },
+              "mapping": {
+                "type": "object",
+                "description": "Items sources only. Optional per-item template, context { ...variables, item } (item already carries the parent); result is merged over the raw item. Supply mapping.id when the entity has no id field."
+              }
+            },
+            "additionalProperties": true
+          },
+          "description": "All data sources, in the useComponentQueries convention. Every query NOT referenced by rows.fromQuery is an items source; items from all items sources concatenate. The pipeline runs once after all queries resolve."
+        },
+        "rows": {
+          "type": "object",
+          "required": [
+            "groupBy",
+            "headerWidth"
+          ],
+          "properties": {
+            "groupBy": {
+              "type": "string",
+              "description": "Dot-path ON the item -> row key (string-coerced). null/undefined/'' -> Unassigned.",
+              "x-example": "driver.contactId"
+            },
+            "fromQuery": {
+              "type": "string",
+              "description": "Name of the rows-source query. Rows come from it including rows with zero items. Omitted -> rows derived from distinct groupBy values in first-seen order."
+            },
+            "key": {
+              "type": "string",
+              "description": "Dot-path on the row record -> row key (string-coerced, must match groupBy values). Required with fromQuery.",
+              "x-example": "contactId"
+            },
+            "label": {
+              "description": "Row label template; context: item = the row record. Default: the row key.",
+              "x-example": "{{ item.firstName }} {{ item.lastName }}"
+            },
+            "orderBy": {
+              "type": "array",
+              "description": "Row sort over row fields (key, label, record.*). Default: rows-query order / first-seen order. Each entry is { field: dot-path to the sort value, direction: asc|desc (default asc) }. Multi-key and stable; null/undefined always sort last regardless of direction; ISO dates compare as dates, numbers numerically, strings locale-aware with numeric collation (natural sort, so numeric strings such as customValues sort by value)."
+            },
+            "unassigned": {
+              "type": "object",
+              "description": "Synthetic row collecting orphan items (group key matches no row). Always renders last.",
+              "properties": {
+                "show": {
+                  "default": true,
+                  "description": "false hides the row AND logs a warning with the dropped count — items are never silently dropped"
+                },
+                "label": {
+                  "default": "Unassigned"
+                }
+              }
+            },
+            "headerWidth": {
+              "type": "number",
+              "description": "Row-header column width in px. Required: the column is sticky and virtualised rows need explicit widths to stay aligned."
+            },
+            "headerPadding": {
+              "default": 1,
+              "description": "Row-header cell padding in theme spacing units (1 = 4px), same idea as the top-level cellPadding but for the first column.",
+              "x-example": 2.5
+            }
+          },
+          "additionalProperties": true,
+          "description": "Row model: grouping key on the item plus an optional dedicated rows source (visible empty rows)"
+        },
+        "columns": {
+          "type": "object",
+          "required": [
+            "width"
+          ],
+          "properties": {
+            "orderBy": {
+              "type": "array",
+              "description": "Sort WITHIN each row -> slot order. Item at sorted index i renders in column i. Runs after ALL sources resolve. Each entry is { field: dot-path to the sort value, direction: asc|desc (default asc) }. Multi-key and stable; null/undefined always sort last regardless of direction; ISO dates compare as dates, numbers numerically, strings locale-aware with numeric collation (natural sort, so numeric strings such as customValues sort by value)."
+            },
+            "appendEmpty": {
+              "type": "boolean",
+              "description": "Always append one empty trailing slot: column count = largest group + 1 (1 when there are no items), so every lane keeps an empty cell for emptyCellTemplate / add-move affordances.",
+              "default": false
+            },
+            "label": {
+              "default": "{{ index }}",
+              "description": "Column header template; variables: index (1-based), columnIndex (0-based)",
+              "x-example": "Move {{ index }}"
+            },
+            "width": {
+              "type": "number",
+              "description": "Column width in px. Required: every virtualised row applies the same explicit gridTemplateColumns."
+            }
+          },
+          "additionalProperties": true,
+          "description": "Column model: ordinal slots. Column count = size of the largest group (+1 with appendEmpty); horizontal scroll, no cap."
+        },
+        "rowHeaderTemplate": {
+          "$ref": "../schemas.json#/definitions/component",
+          "description": "Row header cell; receives row { key, label, record, items, isUnassigned }, rowIndex, itemCount. Default: row.label as plain text."
+        },
+        "itemTemplate": {
+          "$ref": "../schemas.json#/definitions/component",
+          "description": "Item cell; receives item (incl. item.<parentAs> and intact nested collections — iterate them with `collection`), row, column { index, columnIndex, label }, rowIndex, columnIndex"
+        },
+        "emptyCellTemplate": {
+          "$ref": "../schemas.json#/definitions/component",
+          "description": "Optional; receives row, column, rowIndex, columnIndex. Default: empty cell."
+        },
+        "summaryComponent": {
+          "$ref": "../schemas.json#/definitions/component",
+          "description": "Optional per-column footer (sticky below the viewport); receives column, columnIndex, items (that column across all rows), totalCount"
+        },
+        "emptyStateTemplate": {
+          "$ref": "../schemas.json#/definitions/component",
+          "description": "Optional; shown when the pipeline yields zero items (rows from the rows query still render)"
+        },
+        "itemAccent": {
+          "description": "Optional per-item color template (same context as itemTemplate), usually a status color. Paints a bar down the card's left edge and a low-alpha wash of the same color over the card background. Accepts hex/rgb()/hsl() or a theme palette path ('warning.main'); anything unparseable renders the plain card.",
+          "x-example": "{{ item.orderMove.orderMoveStatus.color }}"
+        },
+        "itemGroups": {
+          "type": "object",
+          "required": [
+            "key"
+          ],
+          "properties": {
+            "key": {
+              "type": "string"
+            },
+            "headerTemplate": {
+              "$ref": "../schemas.json#/definitions/component"
+            },
+            "accent": {},
+            "dotsMenu": {
+              "type": "object"
+            }
+          },
+          "additionalProperties": false
+        },
+        "dragSource": {
+          "type": "object",
+          "required": [
+            "type"
+          ],
+          "properties": {
+            "type": {
+              "type": "string"
+            },
+            "data": {},
+            "canDrag": {}
+          },
+          "additionalProperties": false
+        },
+        "events": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "../schemas.json#/definitions/actionsList"
+          },
+          "description": "Interaction handlers; payloads merge last over variables + store",
+          "properties": {
+            "onItemClick": {
+              "$ref": "../schemas.json#/definitions/actionsList",
+              "description": "Click on an item (propagation stopped); payload: item, row, column, rowIndex, columnIndex"
+            },
+            "onCellClick": {
+              "$ref": "../schemas.json#/definitions/actionsList",
+              "description": "Click on cell background — never fires from inside an item; payload: row, column, rowIndex, columnIndex"
+            },
+            "onRowClick": {
+              "$ref": "../schemas.json#/definitions/actionsList",
+              "description": "Click on the row header; payload: row, rowIndex"
+            },
+            "onItemsLoaded": {
+              "$ref": "../schemas.json#/definitions/actionsList",
+              "description": "Fires once per completed pipeline; payload: items, itemCount, rowCount, columnCount"
+            }
+          }
+        },
+        "cellPadding": {
+          "default": 0.5,
+          "description": "Gap between the card (or empty-cell content) and the cell separators, in theme spacing units (1 = 4px). Inner card padding is the item template's own business (options.p).",
+          "x-example": 2.5
+        }
+      },
+      "additionalProperties": true
+    },
+    "isHidden": {
+      "description": "Boolean template expression for conditional rendering"
+    }
+  },
+  "additionalProperties": true,
+  "description": "Generic grouped & ordered planning grid: each resource (driver, truck, dock, crew...) is a row, its work items appear as ordinal slots across the columns (slot 1, slot 2...). Columns are positional — the item's index in its sorted group — not dates; for date/time columns use timeline-grid. Fully YAML-driven four-stage pipeline: Extract (queries + itemsPath) -> Group (rows.groupBy) -> Sort (columns.orderBy) -> Place.",
+  "x-examples": [
+    {
+      "component": "planner",
+      "name": "driverPlanner",
+      "props": {
+        "height": 700,
+        "queries": [
+          {
+            "name": "moves",
+            "query": {
+              "command": "query GetOrderMovesForPlanner($date: DateTime!, $branchId: Int) { orders(filter: { orderMoves: { date: $date } }) { items { orderId orderNumber orderMoves { orderMoveId startDate driver { contactId firstName lastName } orderMoveLegs { legType location } } } } }",
+              "variables": {
+                "date": "{{ plannerDate }}",
+                "branchId": "{{ branchId }}"
+              },
+              "path": "orders.items"
+            },
+            "itemsPath": "orderMoves",
+            "parentAs": "order",
+            "mapping": {
+              "id": "{{ item.orderMoveId }}"
+            }
+          },
+          {
+            "name": "drivers",
+            "query": {
+              "command": "query GetPlannerDrivers($branchId: Int) { contacts(filter: { branchId: $branchId }) { items { contactId firstName lastName } } }",
+              "variables": {
+                "branchId": "{{ branchId }}"
+              },
+              "path": "contacts.items"
+            }
+          }
+        ],
+        "rows": {
+          "groupBy": "driver.contactId",
+          "fromQuery": "drivers",
+          "key": "contactId",
+          "label": "{{ item.firstName }} {{ item.lastName }}",
+          "orderBy": [
+            {
+              "field": "label",
+              "direction": "asc"
+            }
+          ],
+          "unassigned": {
+            "show": true,
+            "label": "Unassigned"
+          },
+          "headerWidth": 260
+        },
+        "columns": {
+          "orderBy": [
+            {
+              "field": "startDate",
+              "direction": "asc"
+            },
+            {
+              "field": "orderMoveId",
+              "direction": "asc"
+            }
+          ],
+          "label": "Move {{ index }}",
+          "width": 420
+        },
+        "itemTemplate": {
+          "component": "card",
+          "props": {
+            "title": "{{ item.order.orderNumber }}"
+          }
+        },
+        "events": {
+          "onItemClick": [
+            {
+              "navigate": "orders/{{ item.order.orderId }}"
+            }
+          ]
+        }
+      }
+    }
+  ]
+}

package/schemas/components/progressBar.json

@@ -1 +1,115 @@
-{"$schema":"http://json-schema.org/draft-07/schema#","title":"ProgressBar Component","type":"object","required":["component"],"properties":{"component":{"const":"progressBar"},"name":{"type":"string"},"props":{"type":"object","properties":{"value":{},"max":{},"items":{},"completedPath":{"type":"string"},"completedValue":{},"label":{},"showValue":{"type":"boolean"},"valueFormat":{"enum":["count","percent"]},"variant":{"enum":["linear","circular","segmented"]},"height":{},"size":{},"color":{},"activeColor":{"type":"string","description":"Mobile segmented variant color for completed segments"},"trackColor":{"type":"string","description":"Track or incomplete-segment color"},"tooltip":{},"testID":{"type":"string"}},"additionalProperties":true}},"additionalProperties":true}
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ProgressBar Component",
+  "type": "object",
+  "required": [
+    "component"
+  ],
+  "properties": {
+    "component": {
+      "const": "progressBar"
+    },
+    "name": {
+      "type": "string",
+      "description": "Unique name identifier for the progress bar"
+    },
+    "props": {
+      "type": "object",
+      "properties": {
+        "value": {
+          "description": "Completed amount. Overrides the derived count when items/completedPath are also set"
+        },
+        "max": {
+          "description": "Total amount. Defaults to items.length when items is set. max 0 or missing → nothing renders"
+        },
+        "items": {
+          "description": "Single-chunk template resolving to an array, e.g. '{{ row.items }}'. Sets max = length; combined with completedPath sets value = matched count"
+        },
+        "completedPath": {
+          "type": "string",
+          "description": "Dot path inside each item to test, e.g. orderMove.orderMoveStatus.statusStage"
+        },
+        "completedValue": {
+          "description": "Value at completedPath that counts as completed, e.g. Completed. Omitted → any truthy value counts"
+        },
+        "label": {
+          "description": "Caption on the left above the bar, e.g. Moves"
+        },
+        "showValue": {
+          "type": "boolean",
+          "description": "Show the value caption (right-aligned for linear, centered for circular). Default true"
+        },
+        "valueFormat": {
+          "enum": [
+            "count",
+            "percent"
+          ],
+          "description": "count → '2/5' (default), percent → '40%'"
+        },
+        "variant": {
+          "enum": [
+            "linear",
+            "circular",
+            "segmented"
+          ],
+          "description": "Bar shape: linear (default), circular or segmented"
+        },
+        "height": {
+          "description": "Linear bar thickness in px. Default 6"
+        },
+        "size": {
+          "description": "Circular variant diameter in px. Default 40"
+        },
+        "color": {
+          "description": "Theme color (primary, success, warning, info, error, secondary) or CSS color. Default: primary, flipping to success at 100%"
+        },
+        "activeColor": {
+          "type": "string",
+          "description": "Mobile segmented variant color for completed segments"
+        },
+        "trackColor": {
+          "type": "string",
+          "description": "Track or incomplete-segment color"
+        },
+        "tooltip": {
+          "description": "Tooltip on hover"
+        },
+        "testID": {
+          "type": "string"
+        },
+        "isHidden": {
+          "description": "Conditionally hide the bar"
+        },
+        "permission": {
+          "description": "Permission(s) required to render the component: a permission string or an array of permission strings"
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true,
+  "description": "Abstract progress bar. Feed it value/max directly, or an items array with a declarative completed predicate — what the numbers mean (moves, stops, hours…) is the module's business. Renders nothing when max is 0, so it can be declared unconditionally.",
+  "x-examples": [
+    {
+      "component": "progressBar",
+      "name": "laneMovesProgress",
+      "props": {
+        "label": "Moves",
+        "items": "{{ row.items }}",
+        "completedPath": "orderMove.orderMoveStatus.statusStage",
+        "completedValue": "Completed"
+      }
+    },
+    {
+      "component": "progressBar",
+      "name": "hoursOfService",
+      "props": {
+        "label": "Hours",
+        "value": "{{ row.record.customValues.hoursUsed }}",
+        "max": 11,
+        "valueFormat": "percent",
+        "color": "warning"
+      }
+    }
+  ]
+}

package/schemas/components/timeline.json

@@ -115,6 +115,30 @@
           "$ref": "../schemas.json#/definitions/component",
           "description": "Mobile-only component used for normal-mode events whose mapped status is 'active'; receives 'item' bound to the event"
         },
+        "itemGroups": {
+          "type": "object",
+          "description": "Mobile normal-mode visual grouping for adjacent events whose templated key resolves to the same non-empty value",
+          "properties": {
+            "key": {
+              "$ref": "../schemas.json#/definitions/templateExpression",
+              "description": "Resolved per event with item, index, and collection"
+            },
+            "accent": {
+              "$ref": "../schemas.json#/definitions/templateExpression",
+              "description": "Frame color resolved with group and collection"
+            },
+            "background": {
+              "$ref": "../schemas.json#/definitions/templateExpression",
+              "description": "Frame fill resolved with group and collection"
+            },
+            "headerTemplate": {
+              "$ref": "../schemas.json#/definitions/component",
+              "description": "Rendered once above the grouped members; receives group and collection"
+            }
+          },
+          "required": ["key"],
+          "additionalProperties": false
+        },
         "eventSources": {
           "type": "array",
           "description": "Data providers executed for the current visible range or tracking milestone source",

package/schemas/fields/attachment.json

@@ -84,13 +84,37 @@
           "items": { "type": "string" }
         },
         "parentId": {
-          "oneOf": [{ "type": "string" }, { "type": "integer" }, { "$ref": "../schemas.json#/definitions/templateExpression" }],
+          "anyOf": [{ "type": "string" }, { "type": "integer" }, { "$ref": "../schemas.json#/definitions/templateExpression" }],
           "description": "Parent entity ID for linking attachment"
         },
         "parentType": {
-          "oneOf": [{ "type": "string" }, { "$ref": "../schemas.json#/definitions/templateExpression" }],
+          "anyOf": [{ "type": "string" }, { "$ref": "../schemas.json#/definitions/templateExpression" }],
           "description": "Logical parent type/entity for the attachment (e.g., Order, Contact)"
         },
+        "links": {
+          "oneOf": [
+            {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "entityType": {
+                    "type": "string",
+                    "description": "Linked entity type: Order, Contact, Job or TrackingEvent"
+                  },
+                  "entityId": {
+                    "type": ["string", "integer"],
+                    "description": "Linked entity id (int, or UUID for jobs); templates allowed"
+                  }
+                },
+                "required": ["entityType", "entityId"],
+                "additionalProperties": false
+              }
+            },
+            { "$ref": "../schemas.json#/definitions/templateExpression" }
+          ],
+          "description": "More entities to link the uploaded attachment to, besides parentId/parentType. Entries whose entityType or entityId resolves empty are skipped."
+        },
         "onUploaded": {
           "oneOf": [{ "type": "string" }, { "$ref": "../schemas.json#/definitions/actions" }],
           "description": "Actions to execute after successful upload"
@@ -151,6 +175,15 @@
         "parentId": "{{ orderId }}",
         "parentType": "Order"
       }
+    },
+    {
+      "type": "attachment",
+      "label": { "en-US": "Event Photo" },
+      "options": {
+        "parentId": "{{ orderId }}",
+        "parentType": "Order",
+        "links": [{ "entityType": "TrackingEvent", "entityId": "{{ trackingEventId }}" }]
+      }
     }
   ]
 }