@cxtms/cx-schema 1.9.256 → 1.9.258

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cxtms/cx-schema",
-  "version": "1.9.256",
+  "version": "1.9.258",
   "description": "Schema validation package for CXTMS YAML modules",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/schemas/components/field-collection.json

@@ -316,6 +316,25 @@
             ]
           }
         },
+        "itemGroups": {
+          "type": "object",
+          "required": ["key"],
+          "properties": {
+            "key": {
+              "type": "string",
+              "description": "Template resolved per visible row. Consecutive rows with the same non-empty key form a visual group."
+            },
+            "headerTemplate": {
+              "type": "object",
+              "description": "Component rendered once above the grouped accordion rows. Receives group and collection variables."
+            },
+            "accent": {
+              "description": "Templated group-frame color: CSS color, palette path, or palette name."
+            }
+          },
+          "additionalProperties": false,
+          "description": "Visually joins adjacent accordion rows with matching keys without reordering or bucketing them."
+        },
         "layout": {
           "type": "string",
           "enum": ["list", "grid", "accordion"],

package/schemas/components/planner.json

@@ -1 +1 @@
-{"$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":{},"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"},"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}

package/schemas/schema.graphql

@@ -11084,6 +11084,7 @@ type orderMoveLeg {
   orderMoveLegStatus: orderMoveLegStatus
   startDate: DateTime
   endDate: DateTime
+  getAddress(idPropertyName: String!): contactAddress
   trackingEvents: [trackingEvent!]
   customValues: MapOfObject
   isDeleted: Boolean!

package/skills/cxtms-developer/ref-entity-dispatch-routing.md

@@ -162,6 +162,7 @@ Vertical-specific routing details belong in `customValues`.
 | `startDate` | `DateTime?` | UTC start |
 | `endDate` | `DateTime?` | UTC end |
 | `customValues` | `Dictionary` | Location, event, appointment, and metric data |
+| `getAddress(idPropertyName)` | `ContactAddress?` | Resolves a contact-address ID from the named `customValues` property; tenant-scoped through the parent move |
 | `trackingEvents` | `[TrackingEvent]` | Leg-level milestones |
 
 Entity-trigger payloads load the status navigation before mapping when necessary. This
@@ -184,6 +185,7 @@ are appended and omitted existing records are not deleted.
 
 - Queries: `dispatchRouteStatus`, `dispatchRouteStatuses`, `dispatchRouteStopStatus`, `dispatchRouteStopStatuses`, `dispatchRouteTemplate`, `dispatchRouteTemplates`, `dispatchRoute`, `dispatchRoutes`.
 - Order move queries: `orderMove`, `orderMoves`, `orderMoveStatus`, `orderMoveStatuses`, `orderMoveLegStatus`, and `orderMoveLegStatuses`.
+- Order-move legs expose `getAddress(idPropertyName: String!)` to resolve an integer contact-address ID from the named `customValues` property. Missing or invalid values return `null`, and cross-organization addresses are never returned.
 - Nested order resolvers: `getOrderMoves(filter, orderBy)` returns pending or statusless moves (defaulted to sequence order), while `getOrderMove(filter, orderBy)` returns the first matching pending or statusless move. Moves whose status stage is no longer `Pending` are excluded.
 - Order move mutations create, sparse-update, and soft-delete moves; create/update accepts nested `orderMoveLegs`, reconciled by ID and array order. Omitted or `isDeleted: true` legs are soft-deleted, new already-deleted legs are ignored, and only active legs consume sequence positions.
 - `createOrderMoveLeg`, `updateOrderMoveLeg`, and `deleteOrderMoveLeg` manage one leg without resending the parent move. Create requires `orderMoveId`, appends after the last active leg when `sequence` is omitted, and accepts name, status, dates, and custom values. Update takes a sparse values map; delete is soft. Each operation is organization-scoped through the parent move.

package/skills/cxtms-module-builder/ref-components-forms.md

@@ -605,6 +605,7 @@ When `options.allowRemove` is enabled and the item count is above `minItems`, re
 | `groupMode` | `boolean` | `false` | Enable grouping |
 | `groupBy` | `string` | — | Field path to group by |
 | `groups` | `{key, label, icon?}[]` | — | Group definitions |
+| `itemGroups` | `{key, headerTemplate?, accent?}` | — | In accordion layout, join consecutive rows whose templated key is equal and non-empty |
 | `showIndex` | `boolean` | `false` | Show item index |
 | `showDragHandle` | `boolean` | `false` | Show drag handles |
 | `showMoveButtons` | `boolean` | `false` | Show up/down move buttons for accessible reordering; requires `options.allowReorder` |
@@ -685,6 +686,8 @@ Grouped collections can render groups in multiple columns. Use a fixed `groupCol
 
 Accordion collections support `itemHeaderFields` for interactive fields that remain visible while a row is collapsed. The header fields share `item`, `index`, `collection`, and field-name prefixing with `itemTemplate`; wrap them in a `layout` for grid sizing. Use `rowVariant: flat` and `nestedVariant: rail` or `none` to reduce card chrome in nested collections.
 
+`itemGroups` is separate from `groupMode`: it preserves order and frames only adjacent runs of two or more matching keys. Its header and accent templates receive `group = { key, items, size, startIndex, endIndex }` and `collection`; grouped row templates additionally receive `groupPosition` and `groupOffset`.
+
 For `datetime`, `time`, and `select-async` fields, `displayMode: readEdit` renders the current value as text until clicked. Date/time fields stay in edit mode while their calendar popup is open and return to text when it closes; other fields return on blur.
 
 ```yaml
@@ -729,7 +732,9 @@ Headless barcode/keyboard scanner listener. Captures rapid keystrokes and fires
 | `maxBarcodes` | `number` | — | Mobile: maximum accepted scans in continuous mode |
 | `onScan` | `action[]` | — | **Required.** Action on scan detection |
 
-**Renders:** Nothing (empty fragment). Web listens on `document` keypress. Mobile supports
+**Renders:** Nothing (empty fragment). Web listens on `document` keydown, ignores form controls
+and non-printable keys, and derives letters, unshifted digits, minus, and period from physical
+key codes to avoid keyboard-layout transformations. Other printable keys use `event.key`. Mobile supports
 native HID scanners with a hidden-input fallback and shares camera-scanner deduplication rules.
 
 **Scan data:** `result: { data: string, format: 'input' }`

package/skills/cxtms-module-builder/ref-components-specialized.md

@@ -473,6 +473,8 @@ Set `columns.appendEmpty: true` to render one trailing empty ordinal slot beyond
 
 Set `props.dragSource` to make planner cards draggable between lanes. It uses the shared `type`, optional `data`, and optional templated `canDrag` contract; target cells receive the payload through `dragItem` and `dragType`. Native dragging is desktop-only, so keep a click-driven equivalent.
 
+Use `props.itemGroups` to join consecutive cards with the same non-empty templated `key` into one framed block. Optional `headerTemplate`, `accent`, and `dotsMenu` render at group level. Group templates receive `{ key, items, size, startIndex, endIndex }`; card templates receive `group`, `groupPosition`, and `groupOffset`. A grouped drag exposes the complete group to the drop action as `dragGroup` while preserving the individual `dragItem`.
+
 ## timeline-grid
 
 CSS Grid-based timeline with swim lanes, drill-down, and virtual scrolling.