@cxtms/cx-schema 1.9.257 → 1.9.259

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cxtms/cx-schema",
-  "version": "1.9.257",
+  "version": "1.9.259",
   "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/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/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

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

@@ -347,6 +347,7 @@ MUI Lab Timeline for chronological events or milestone-based tracking progress.
 | `startDate` / `endDate` | `string` | current week | Initial date range for normal mode |
 | `eventSources` | `EventSource[]` | — | GraphQL/static event sources |
 | `eventTemplate` | `ComponentProps` | — | Custom event template for normal mode |
+| `itemGroups` | `{key, accent?, background?, headerTemplate?}` | — | Mobile normal-mode grouping for consecutive events with the same non-empty key |
 | `milestones` | `Milestone[]` | `[]` | Tracking milestones |
 | `options.height` | `string \| number` | `400`/`auto` | Component height |
 | `options.showTodayMarker` | `boolean` | `true` | Today marker in normal mode |
@@ -364,6 +365,8 @@ MUI Lab Timeline for chronological events or milestone-based tracking progress.
 
 **Events:** `onEventClick` (data: `event`)
 
+On mobile vertical timelines, `itemGroups` frames adjacent runs of two or more events whose templated `key` resolves equally. Runs are order-sensitive; isolated or empty keys remain ungrouped. `headerTemplate`, `accent`, and `background` resolve with `group = { key, items, size, startIndex, endIndex }` and `collection`. Grouped event templates also receive `groupPosition` and `groupOffset`. Tracking mode ignores grouping.
+
 ```yaml
 component: timeline
 name: orderTimeline
@@ -473,6 +476,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.