@cxtms/cx-schema 1.9.67 → 1.9.241

package/schemas/components/timeline.json

@@ -18,26 +18,32 @@
     "props": {
       "type": "object",
       "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["normal", "tracking"],
+          "default": "normal",
+          "description": "Timeline behavior. Tracking mode joins events to milestone definitions and hides date-range navigation."
+        },
         "orientation": {
           "type": "string",
           "enum": ["horizontal", "vertical"],
           "default": "horizontal",
-          "description": "Timeline axis direction"
+          "description": "Timeline axis direction. Tracking mode renders vertically."
         },
         "view": {
           "type": "string",
           "enum": ["day", "week", "month", "year"],
-          "default": "day",
-          "description": "Zoom level controlling granularity and visible window"
+          "default": "week",
+          "description": "Zoom level controlling granularity and visible window in normal mode"
         },
         "startDate": {
           "$ref": "../schemas.json#/definitions/templateExpression",
-          "description": "Initial lower bound for the visible date range (ISO or expression)",
+          "description": "Initial lower bound for the visible date range in normal mode (ISO or expression)",
           "x-example": "{{ today() }}"
         },
         "endDate": {
           "$ref": "../schemas.json#/definitions/templateExpression",
-          "description": "Initial upper bound for the visible date range",
+          "description": "Initial upper bound for the visible date range in normal mode",
           "x-example": "{{ addDays today 7 }}"
         },
         "defaultDate": {
@@ -52,87 +58,186 @@
             "height": {
               "oneOf": [
                 { "type": "number", "description": "Height in pixels" },
-                { "type": "string", "description": "CSS size (e.g., '400px', '50vh')" }
+                { "type": "string", "description": "CSS size (e.g., '400px', '50vh', 'auto')" }
               ],
-              "default": "400px",
+              "default": 400,
               "description": "Timeline container height"
+            },
+            "showTodayMarker": {
+              "type": "boolean",
+              "default": true,
+              "description": "Show a marker for today's date in normal mode"
+            },
+            "enableZoom": {
+              "type": "boolean",
+              "default": true,
+              "description": "Show day/week/month/year view switcher in normal mode"
+            },
+            "enableNavigation": {
+              "type": "boolean",
+              "default": true,
+              "description": "Show previous/next/today navigation in normal mode"
+            },
+            "alternateSides": {
+              "type": "boolean",
+              "default": true,
+              "description": "Alternate events left/right in vertical mode"
+            },
+            "showTwoColumns": {
+              "type": "boolean",
+              "default": true,
+              "description": "Show date/status content opposite the main event content in vertical mode"
+            },
+            "dateFormat": {
+              "type": "string",
+              "default": "MMM DD",
+              "description": "Moment.js date format"
+            },
+            "timeFormat": {
+              "type": "string",
+              "default": "h:mm A",
+              "description": "Moment.js time format"
+            },
+            "extraEvents": {
+              "type": "string",
+              "enum": ["show", "hide"],
+              "default": "hide",
+              "description": "Whether tracking mode shows events whose mapped key does not match a milestone"
             }
-          }
+          },
+          "additionalProperties": true
         },
         "eventTemplate": {
           "$ref": "../schemas.json#/definitions/component",
-          "description": "Component used to render each event; receives 'item' bound to mapped fields"
+          "description": "Component used to render each event in normal mode; receives 'item' bound to mapped fields"
+        },
+        "activeTemplate": {
+          "$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"
         },
         "eventSources": {
           "type": "array",
-          "description": "Data providers executed for the current visible range",
-          "items": {
-            "type": "object",
-            "properties": {
-              "query": {
-                "type": "object",
-                "description": "GraphQL source executed when the visible range changes",
-                "properties": {
-                  "command": {
-                    "type": "string",
-                    "description": "GraphQL document string"
-                  },
-                  "variables": {
-                    "type": "object",
-                    "description": "Variables for the GraphQL command (template expressions supported)",
-                    "additionalProperties": true
-                  }
-                },
-                "required": ["command"]
-              },
-              "path": {
-                "type": "string",
-                "description": "Dot path to the array of items in the result (e.g., 'orders.items')"
-              },
-              "mapping": {
-                "type": "object",
-                "description": "Maps source fields to timeline event fields",
-                "properties": {
-                  "date": { "type": "string", "description": "ISO date/time for the event" },
-                  "title": { "type": "string", "description": "Display title" },
-                  "id": {
-                    "oneOf": [{ "type": "string" }, { "type": "number" }],
-                    "description": "Stable identifier"
-                  },
-                  "endDate": { "type": "string", "description": "ISO end date/time for ranged spans" },
-                  "description": { "type": "string" },
-                  "backgroundColor": { "type": "string" },
-                  "textColor": { "type": "string" },
-                  "icon": { "type": "string" },
-                  "iconColor": { "type": "string" },
-                  "iconSize": { "oneOf": [{ "type": "string" }, { "type": "number" }] }
-                },
-                "required": ["date", "title"],
-                "additionalProperties": true,
-                "x-example": {
-                  "id": "{{ item.orderId }}",
-                  "date": "{{ item.orderDate }}",
-                  "endDate": "{{ item.orderEnd }}",
-                  "title": "{{ item.orderNumber }}",
-                  "description": "Order created on {{ item.orderDate }}",
-                  "icon": "package"
-                }
-              }
-            },
-            "required": ["query", "path", "mapping"]
-          }
+          "description": "Data providers executed for the current visible range or tracking milestone source",
+          "items": { "$ref": "#/definitions/eventSource" }
+        },
+        "milestones": {
+          "type": "array",
+          "description": "Tracking mode milestone definitions matched against mapped event key values",
+          "items": { "$ref": "#/definitions/milestone" }
         },
         "isHidden": {
           "$ref": "../schemas.json#/definitions/templateExpression",
           "description": "Boolean expression for conditional rendering"
         }
-      }
+      },
+      "additionalProperties": true
     },
     "children": {
       "$ref": "../schemas.json#/definitions/componentChildren"
     }
   },
   "required": ["component", "props"],
+  "definitions": {
+    "eventSource": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "object",
+          "description": "GraphQL source executed for timeline events",
+          "properties": {
+            "command": {
+              "type": "string",
+              "description": "GraphQL document string"
+            },
+            "variables": {
+              "type": "object",
+              "description": "Variables for the GraphQL command (template expressions supported)",
+              "additionalProperties": true
+            },
+            "path": {
+              "type": "string",
+              "description": "Dot path to the array of items in the GraphQL result (e.g., 'data.events.items' or 'order.trackingEvents')"
+            },
+            "mapping": {
+              "$ref": "#/definitions/eventMapping"
+            }
+          },
+          "required": ["command"],
+          "additionalProperties": true
+        },
+        "events": {
+          "description": "Static event array or template expression fallback/primary source"
+        },
+        "color": { "type": "string", "description": "Legacy source color" },
+        "backgroundColor": { "type": "string", "description": "Default background color for events from this source" },
+        "textColor": { "type": "string", "description": "Default text color for events from this source" },
+        "borderColor": { "type": "string", "description": "Default border color for outlined dots" }
+      },
+      "anyOf": [
+        { "required": ["query"] },
+        { "required": ["events"] }
+      ],
+      "additionalProperties": true
+    },
+    "eventMapping": {
+      "type": "object",
+      "description": "Maps source fields to timeline event fields. Tracking mode uses key for milestone matching.",
+      "properties": {
+        "key": { "type": "string", "description": "Tracking milestone match key" },
+        "id": {
+          "oneOf": [{ "type": "string" }, { "type": "number" }],
+          "description": "Stable identifier"
+        },
+        "date": { "type": "string", "description": "ISO date/time for the event. Required for completed/extra events." },
+        "endDate": { "type": "string", "description": "ISO end date/time for ranged spans" },
+        "title": { "type": "string", "description": "Display title" },
+        "description": { "type": "string" },
+        "includeInTracking": { "description": "Source flag available to mapping/templates. The timeline component does not filter by this field." },
+        "isInactive": { "description": "Source flag available to mapping/templates. The timeline component does not filter by this field." },
+        "status": { "type": "string", "enum": ["active", "completed", "pending", "extra"] },
+        "backgroundColor": { "type": "string" },
+        "textColor": { "type": "string" },
+        "borderColor": { "type": "string" },
+        "icon": { "type": "string" },
+        "iconColor": { "type": "string" },
+        "iconSize": { "oneOf": [{ "type": "string" }, { "type": "number" }] }
+      },
+      "additionalProperties": true,
+      "x-example": {
+        "key": "{{ item.eventDefinition.eventName }}",
+        "id": "{{ item.trackingEventId }}",
+        "date": "{{ item.eventDate }}",
+        "title": "{{ item.eventDefinition.eventName }}",
+        "description": "{{ item.description }}"
+      }
+    },
+    "milestone": {
+      "type": "object",
+      "properties": {
+        "key": {
+          "type": "string",
+          "description": "Match key compared to mapped event key"
+        },
+        "label": {
+          "description": "Localized display label. Falls back to key.",
+          "oneOf": [
+            { "type": "string" },
+            { "type": "object", "additionalProperties": { "type": "string" } }
+          ]
+        },
+        "description": {
+          "type": "string",
+          "description": "Description shown for pending milestones or fallback for completed milestones"
+        },
+        "icon": {
+          "type": "string",
+          "description": "Icon name rendered inside the milestone dot"
+        }
+      },
+      "required": ["key"],
+      "additionalProperties": true
+    }
+  },
   "x-examples": [
     {
       "component": "timeline",
@@ -151,20 +256,57 @@
         "eventSources": [
           {
             "query": {
-              "command": "query GetOrders($organizationId: Int!, $filter: String) { orders(organizationId: $organizationId, take: 500, filter: $filter) { items { orderId orderDate orderNumber } } }",
+              "command": "query GetOrders($organizationId: Int!, $filter: String) { orders(organizationId: $organizationId, take: 500, filter: $filter) { items { orderId orderDate orderNumber includeInTracking isInactive } } }",
               "variables": {
                 "organizationId": "{{ number organizationId }}",
                 "filter": "orderDate:[{{startDate}} TO {{endDate}}]"
+              },
+              "path": "data.orders.items",
+              "mapping": {
+                "id": "{{ item.orderId }}",
+                "date": "{{ item.orderDate }}",
+                "title": "{{ item.orderNumber }}",
+                "description": "Order created on {{ item.orderDate }}"
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "component": "timeline",
+      "name": "orderTracking",
+      "props": {
+        "mode": "tracking",
+        "orientation": "vertical",
+        "options": {
+          "showTwoColumns": true,
+          "alternateSides": false,
+          "extraEvents": "hide"
+        },
+        "eventSources": [
+          {
+            "query": {
+              "command": "query($organizationId: Int!, $orderId: Int!) { order(organizationId: $organizationId, orderId: $orderId) { trackingEvents { trackingEventId eventDate description includeInTracking isInactive eventDefinition { eventName } } } }",
+              "variables": {
+                "organizationId": "{{ number organizationId }}",
+                "orderId": "{{ number orderId }}"
+              },
+              "path": "order.trackingEvents",
+              "mapping": {
+                "key": "{{ item.eventDefinition.eventName }}",
+                "id": "{{ item.trackingEventId }}",
+                "date": "{{ item.eventDate }}",
+                "title": "{{ item.eventDefinition.eventName }}",
+                "description": "{{ item.description }}"
               }
-            },
-            "path": "orders.items",
-            "mapping": {
-              "id": "{{ item.orderId }}",
-              "date": "{{ item.orderDate }}",
-              "title": "{{ item.orderNumber }}",
-              "description": "Order created on {{ item.orderDate }}"
             }
           }
+        ],
+        "milestones": [
+          { "key": "Shipment Created", "label": { "en-US": "Shipment Created" } },
+          { "key": "In Transit", "label": { "en-US": "In Transit" }, "icon": "truck" },
+          { "key": "Delivered", "label": { "en-US": "Delivered" }, "icon": "check-circle" }
         ]
       }
     }

package/schemas/components/timelineGrid.json

@@ -252,6 +252,10 @@
         "onItemResize": { "$ref": "../schemas.json#/definitions/actionsList" },
         "onItemReassign": { "$ref": "../schemas.json#/definitions/actionsList" },
         "onRangeChange": { "$ref": "../schemas.json#/definitions/actionsList" },
+        "onCellClick": {
+          "$ref": "../schemas.json#/definitions/actionsList",
+          "description": "Cell click handler. Context includes column, row, date, view; column exposes UTC startDate/endDate and local wall-clock startDateLocal/endDateLocal."
+        },
         "onEmptySlotClick": { "$ref": "../schemas.json#/definitions/actionsList" },
         "onLoading": { "$ref": "../schemas.json#/definitions/actionsList" }
       }
@@ -263,7 +267,7 @@
   "required": ["component", "props", "rowSources", "itemSources"],
   "x-examples": [
     {
-      "component": "timelineGrid",
+      "component": "timeline-grid",
       "name": "vehicleScheduler",
       "props": {
         "view": "day",

package/schemas/fields/autocomplete-googleplaces.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Autocomplete Google Places Field Type",
-  "description": "Schema for autocomplete-googleplaces field type with Google Places API integration",
+  "description": "Schema for autocomplete-googleplaces field type with Google Places API integration. The Google Maps SDK API key is loaded from organization config (apps.google.googleMapsApiKey), not from module YAML.",
   "type": "object",
   "properties": {
     "type": {
@@ -127,4 +127,4 @@
     }
   },
   "required": ["type", "options"]
-}
+}

package/schemas/fields/datetime.json

@@ -37,12 +37,12 @@
         "useTimezone": { "type": "boolean", "description": "Enable timezone-aware date handling", "x-example": false },
         "storeAsUTC": {
           "type": "boolean",
-          "description": "When useTimezone is true, store date/time in UTC",
+          "description": "When useTimezone is true, store date/time in UTC. With a fixed timezone, selected wall-clock values are interpreted in that timezone before UTC conversion.",
           "x-example": true
         },
         "timezone": {
           "type": "string",
-          "description": "Fixed timezone for display (e.g., America/New_York)",
+          "description": "Fixed IANA timezone for display and wall-clock interpretation when storing as UTC (e.g., America/New_York)",
           "x-example": "America/New_York"
         },
         "format": { "type": "string", "description": "Custom storage format; if omitted, inferred by options" }

package/schemas/fields/index.json

@@ -7,6 +7,7 @@
       "oneOf": [
         { "$ref": "./text.json" },
         { "$ref": "./number.json" },
+        { "$ref": "./number-select.json" },
         { "$ref": "./email.json" },
         { "$ref": "./password.json" },
         { "$ref": "./tel.json" },
@@ -20,6 +21,7 @@
         { "$ref": "./autocomplete-googleplaces.json" },
         { "$ref": "./checkbox.json" },
         { "$ref": "./radio.json" },
+        { "$ref": "./toggle.json" },
         { "$ref": "./textarea.json" },
         { "$ref": "./attachment.json" }
       ]
@@ -28,6 +30,7 @@
   "fieldTypes": {
     "text": { "description": "Basic text input field", "schema": "./text.json" },
     "number": { "description": "Numeric input field with validation", "schema": "./number.json" },
+    "number-select": { "description": "Numeric input field with increment/decrement controls", "schema": "./number-select.json" },
     "email": { "description": "Email input field with validation", "schema": "./email.json" },
     "password": { "description": "Password input field with security features", "schema": "./password.json" },
     "tel": { "description": "Telephone number input field", "schema": "./tel.json" },
@@ -47,6 +50,7 @@
     },
     "checkbox": { "description": "Checkbox input field", "schema": "./checkbox.json" },
     "radio": { "description": "Radio button group field", "schema": "./radio.json" },
+    "toggle": { "description": "Segmented toggle button group field", "schema": "./toggle.json" },
     "textarea": { "description": "Multi-line text input field", "schema": "./textarea.json" },
     "attachment": { "description": "Attachment picker/uploader field (images or files)", "schema": "./attachment.json" }
   }

package/schemas/fields/number-select.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Number Select Field Type",
+  "description": "Schema for number input field with increment/decrement controls",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "number-select"
+    },
+    "label": {
+      "oneOf": [
+        { "type": "string" },
+        { "$ref": "../schemas.json#/definitions/localized" }
+      ],
+      "description": "Field label",
+      "x-example": {
+        "en-US": "Pieces"
+      }
+    },
+    "placeholder": {
+      "oneOf": [
+        { "type": "string" },
+        { "$ref": "../schemas.json#/definitions/localized" }
+      ],
+      "description": "Field placeholder text",
+      "x-example": "Enter pieces"
+    },
+    "required": {
+      "type": "boolean",
+      "description": "Whether field is required",
+      "x-example": true
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Whether field is disabled",
+      "x-example": false
+    },
+    "min": {
+      "type": "number",
+      "description": "Minimum allowed value. Defaults to 0.",
+      "x-example": 0
+    },
+    "max": {
+      "type": "number",
+      "description": "Maximum allowed value. Defaults to Number.MAX_VALUE in the UI.",
+      "x-example": 9999
+    },
+    "step": {
+      "type": "number",
+      "description": "Amount added or subtracted by each arrow click/long-press tick. Defaults to 1.",
+      "x-example": 1
+    },
+    "options": {
+      "type": "object",
+      "description": "Numeric formatting options passed to react-number-format",
+      "properties": {
+        "fixedDecimalScale": {
+          "type": "boolean",
+          "description": "Always show decimal places up to decimalScale"
+        },
+        "allowNegative": {
+          "type": "boolean",
+          "description": "Allow negative values. Defaults to true when min is below 0."
+        },
+        "decimalScale": {
+          "type": "number",
+          "description": "Maximum number of decimal places. Defaults to 2.",
+          "x-example": 2
+        }
+      },
+      "additionalProperties": true
+    },
+    "onChange": {
+      "$ref": "../schemas.json#/definitions/actionsList",
+      "description": "Actions to execute when field value changes"
+    },
+    "onBlur": {
+      "$ref": "../schemas.json#/definitions/actionsList",
+      "description": "Actions to execute when field loses focus"
+    },
+    "onFocus": {
+      "$ref": "../schemas.json#/definitions/actionsList",
+      "description": "Actions to execute when field gains focus"
+    }
+  },
+  "required": ["type"]
+}

package/schemas/fields/rangedatetime.json

@@ -23,8 +23,16 @@
         "timeIntervals": { "type": "number", "description": "Time intervals in minutes", "x-example": 60 },
         "timeCaption": { "type": "string", "description": "Time caption label", "x-example": "Time" },
         "useTimezone": { "type": "boolean", "description": "Enable timezone-aware handling", "x-example": false },
-        "storeAsUTC": { "type": "boolean", "description": "When useTimezone is true, store in UTC", "x-example": true },
-        "timezone": { "type": "string", "description": "Fixed timezone for display", "x-example": "America/New_York" },
+        "storeAsUTC": {
+          "type": "boolean",
+          "description": "When useTimezone is true, store in UTC. With a fixed timezone, selected wall-clock values are interpreted in that timezone before UTC conversion.",
+          "x-example": true
+        },
+        "timezone": {
+          "type": "string",
+          "description": "Fixed IANA timezone for display and wall-clock interpretation when storing as UTC",
+          "x-example": "America/New_York"
+        },
         "format": { "type": "string", "description": "Custom storage format" },
         "isClearable": { "type": "boolean", "description": "Show clear button", "x-example": true }
       },

package/schemas/fields/select-async.json

@@ -84,7 +84,7 @@
         },
         "valueQuery": {
           "type": "object",
-          "description": "Query configuration for fetching selected value details",
+          "description": "Optional query configuration for fetching selected value details. Omit for inline-create-only fields; with allowCreate enabled, stored primitive values are rendered directly, including as chips in multiple mode.",
           "properties": {
             "name": {
               "type": "string",
@@ -141,7 +141,7 @@
         },
         "allowCreate": {
           "type": "boolean",
-          "description": "Allow creating new items inline",
+          "description": "Allow creating new items inline. When valueQuery is omitted, existing primitive values are mapped directly to options and rendered without a lookup.",
           "x-example": true
         },
         "transformValue": {

package/schemas/fields/toggle.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Toggle Field Type",
+  "description": "Schema for toggle button group field type",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "toggle"
+    },
+    "label": {
+      "oneOf": [
+        { "type": "string" },
+        { "$ref": "../schemas.json#/definitions/localized" }
+      ],
+      "description": "Field label"
+    },
+    "required": {
+      "type": "boolean",
+      "description": "Whether field is required"
+    },
+    "disabled": {
+      "oneOf": [{ "type": "boolean" }, { "type": "string" }],
+      "description": "Whether field is disabled"
+    },
+    "allowMultiple": {
+      "type": "boolean",
+      "default": false,
+      "description": "Enable multi-select mode. When true the value is an array."
+    },
+    "exclusive": {
+      "type": "boolean",
+      "description": "Legacy single-select flag. Prefer allowMultiple; allowMultiple takes precedence."
+    },
+    "enforceValue": {
+      "type": "boolean",
+      "default": false,
+      "description": "In single-select mode, prevent deselecting the current value."
+    },
+    "defaultValue": {
+      "oneOf": [{ "type": "string" }, { "type": "number" }, { "type": "boolean" }],
+      "description": "Initial selected value."
+    },
+    "items": {
+      "type": "array",
+      "description": "Toggle button options",
+      "items": {
+        "type": "object",
+        "properties": {
+          "label": {
+            "oneOf": [
+              { "type": "string" },
+              { "$ref": "../schemas.json#/definitions/localized" }
+            ]
+          },
+          "value": {
+            "oneOf": [{ "type": "string" }, { "type": "number" }, { "type": "boolean" }]
+          },
+          "icon": { "type": "string" },
+          "disabled": { "type": "boolean" }
+        },
+        "required": ["label", "value"],
+        "additionalProperties": true
+      }
+    },
+    "options": {
+      "type": "object",
+      "description": "Props passed to the underlying MUI ToggleButtonGroup",
+      "properties": {
+        "size": { "type": "string", "enum": ["small", "medium", "large"] },
+        "color": { "type": "string", "enum": ["standard", "primary", "secondary", "error", "info", "success", "warning"] },
+        "orientation": { "type": "string", "enum": ["horizontal", "vertical"] }
+      },
+      "additionalProperties": true
+    },
+    "onChange": {
+      "$ref": "../schemas.json#/definitions/actionsList",
+      "description": "Actions to execute when field value changes"
+    },
+    "onBlur": {
+      "$ref": "../schemas.json#/definitions/actionsList",
+      "description": "Actions to execute when field loses focus"
+    },
+    "onFocus": {
+      "$ref": "../schemas.json#/definitions/actionsList",
+      "description": "Actions to execute when field gains focus"
+    }
+  },
+  "required": ["type", "items"],
+  "additionalProperties": true
+}