@cxtms/cx-schema 1.0.0

package/schemas/components/timelineGrid.json

@@ -0,0 +1,324 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Timeline Grid Component",
+  "type": "object",
+  "properties": {
+    "component": {
+      "type": "string",
+      "const": "timeline-grid"
+    },
+    "name": {
+      "type": "string",
+      "description": "Component instance name for referencing in actions/variables"
+    },
+    "inputs": {
+      "type": "object",
+      "description": "Input parameters for the timeline grid"
+    },
+    "props": {
+      "type": "object",
+      "properties": {
+        "view": {
+          "type": "string",
+          "enum": ["hour", "day", "week", "month"],
+          "default": "day",
+          "description": "Zoom level preset. Works with timescale."
+        },
+        "startDate": {
+          "$ref": "../schemas.json#/definitions/templateExpression",
+          "description": "Initial lower bound for visible window (ISO or expression)",
+          "x-example": "{{ today() }}"
+        },
+        "endDate": {
+          "$ref": "../schemas.json#/definitions/templateExpression",
+          "description": "Initial upper bound for visible window",
+          "x-example": "{{ addDays today 7 }}"
+        },
+        "defaultDate": {
+          "$ref": "../schemas.json#/definitions/templateExpression",
+          "description": "Initial focal date when range not provided",
+          "x-example": "{{ today() }}"
+        },
+        "options": {
+          "type": "object",
+          "description": "Visual/behavioral options",
+          "properties": {
+            "height": {
+              "oneOf": [
+                { "type": "number", "description": "Height in pixels" },
+                { "type": "string", "description": "CSS size (e.g., '600px', '50vh')" }
+              ],
+              "default": "600px",
+              "description": "Grid height"
+            },
+            "rowHeight": {
+              "type": "number",
+              "default": 44,
+              "description": "Row height in pixels"
+            },
+            "timescale": {
+              "type": "string",
+              "enum": ["hour", "day", "week", "month"],
+              "default": "hour",
+              "description": "Time unit on X-axis"
+            },
+            "timeStepMinutes": {
+              "type": "number",
+              "default": 30,
+              "description": "Cell width resolution when timescale=hour"
+            },
+            "snapToMinutes": {
+              "type": "number",
+              "default": 15,
+              "description": "Drag/resize snap step"
+            },
+            "showNowMarker": {
+              "type": "boolean",
+              "default": true,
+              "description": "Displays current time marker line"
+            },
+            "showNonWorking": {
+              "type": "boolean",
+              "default": true,
+              "description": "Shades non-working periods"
+            },
+            "workingHours": {
+              "type": "array",
+              "description": "Daily working window [startHH:mm, endHH:mm]",
+              "items": { "type": "string" },
+              "minItems": 2,
+              "maxItems": 2,
+              "x-example": ["06:00", "22:00"]
+            },
+            "weekendDays": {
+              "type": "array",
+              "description": "Weekend day numbers (1=Mon..7=Sun)",
+              "items": { "type": "number", "minimum": 1, "maximum": 7 },
+              "x-example": [6, 7]
+            },
+            "allowOverlap": {
+              "type": "boolean",
+              "default": false,
+              "description": "Allow overlaps within the same row"
+            },
+            "editable": {
+              "type": "object",
+              "properties": {
+                "move": { "type": "boolean", "default": true },
+                "resize": { "type": "boolean", "default": true },
+                "reassign": { "type": "boolean", "default": true }
+              },
+              "description": "Enable editing interactions"
+            },
+            "virtualization": {
+              "type": "boolean",
+              "default": true,
+              "description": "Virtualize rows for performance"
+            },
+            "stickyHeaders": {
+              "type": "boolean",
+              "default": true,
+              "description": "Keep time header and row headers sticky"
+            }
+          }
+        },
+        "rowTemplate": {
+          "$ref": "../schemas.json#/definitions/component",
+          "description": "Custom render for row header cell; receives 'row' context"
+        },
+        "itemTemplate": {
+          "$ref": "../schemas.json#/definitions/component",
+          "description": "Template for items; receives 'item' context"
+        },
+        "isHidden": {
+          "$ref": "../schemas.json#/definitions/templateExpression",
+          "description": "Boolean expression for conditional rendering"
+        }
+      },
+      "required": ["options"]
+    },
+    "rowSources": {
+      "type": "array",
+      "description": "Data providers for resources (rows)",
+      "items": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "object",
+            "description": "GraphQL query configuration",
+            "properties": {
+              "command": { "type": "string", "description": "GraphQL document string" },
+              "variables": {
+                "type": "object",
+                "description": "Variables for the query (template expressions supported)",
+                "additionalProperties": true
+              }
+            },
+            "required": ["command"]
+          },
+          "path": { "type": "string", "description": "Dot path to array of rows in response" },
+          "mapping": {
+            "description": "Mapping from source item to row fields",
+            "oneOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "rows": {
+                    "type": "string",
+                    "description": "Template expression resolving to an array of rows objects"
+                  }
+                },
+                "required": ["rows"],
+                "additionalProperties": true,
+                "x-example": {
+                  "rows": "{{ eval item.lanes.map(l=>({ rowId:l.id, label:l.name, group:item.name })) }}"
+                }
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "rowId": {
+                    "oneOf": [{ "type": "string" }, { "type": "number" }],
+                    "description": "Unique row identifier"
+                  },
+                  "label": { "type": "string", "description": "Row display label" },
+                  "group": { "type": "string", "description": "Group name for collapsible grouping" },
+                  "status": { "type": "string" },
+                  "type": { "type": "string" },
+                  "color": { "type": "string" }
+                },
+                "required": ["rowId", "label"],
+                "additionalProperties": true
+              }
+            ]
+          }
+        },
+        "required": ["query", "path", "mapping"]
+      }
+    },
+    "itemSources": {
+      "type": "array",
+      "description": "Data providers for time spans (items) for the visible window",
+      "items": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "object",
+            "description": "GraphQL query configuration",
+            "properties": {
+              "command": { "type": "string", "description": "GraphQL document string" },
+              "variables": {
+                "type": "object",
+                "description": "Variables for the query; should include start and end",
+                "additionalProperties": true
+              }
+            },
+            "required": ["command"]
+          },
+          "path": { "type": "string", "description": "Dot path to array of items in response" },
+          "mapping": {
+            "type": "object",
+            "description": "Mapping from source item to grid item fields",
+            "properties": {
+              "id": { "oneOf": [{ "type": "string" }, { "type": "number" }], "description": "Unique item identifier" },
+              "rowId": { "oneOf": [{ "type": "string" }, { "type": "number" }], "description": "Row association" },
+              "start": { "type": "string", "description": "Start datetime (ISO)" },
+              "end": { "type": "string", "description": "End datetime (ISO)" },
+              "title": { "type": "string", "description": "Display title" },
+              "description": { "type": "string" },
+              "status": { "type": "string" },
+              "priority": { "oneOf": [{ "type": "string" }, { "type": "number" }] },
+              "color": { "type": "string" },
+              "textColor": { "type": "string" },
+              "className": { "type": "string" }
+            },
+            "required": ["id", "rowId", "start", "end", "title"],
+            "additionalProperties": true
+          }
+        },
+        "required": ["query", "path", "mapping"]
+      }
+    },
+    "events": {
+      "type": "object",
+      "description": "Interaction handlers",
+      "properties": {
+        "onItemClick": { "$ref": "../schemas.json#/definitions/actionsList" },
+        "onItemMove": { "$ref": "../schemas.json#/definitions/actionsList" },
+        "onItemResize": { "$ref": "../schemas.json#/definitions/actionsList" },
+        "onItemReassign": { "$ref": "../schemas.json#/definitions/actionsList" },
+        "onRangeChange": { "$ref": "../schemas.json#/definitions/actionsList" },
+        "onEmptySlotClick": { "$ref": "../schemas.json#/definitions/actionsList" },
+        "onLoading": { "$ref": "../schemas.json#/definitions/actionsList" }
+      }
+    },
+    "children": {
+      "$ref": "../schemas.json#/definitions/componentChildren"
+    }
+  },
+  "required": ["component", "props", "rowSources", "itemSources"],
+  "x-examples": [
+    {
+      "component": "timelineGrid",
+      "name": "vehicleScheduler",
+      "props": {
+        "view": "day",
+        "options": {
+          "height": "600px",
+          "timescale": "hour",
+          "timeStepMinutes": 30,
+          "snapToMinutes": 15,
+          "showNowMarker": true,
+          "editable": { "move": true, "resize": true, "reassign": true }
+        },
+        "itemTemplate": {
+          "component": "card",
+          "props": {
+            "title": "{{ item.title }}",
+            "description": "{{ item.description }}",
+            "backgroundColor": "{{ item.color || '#3788d8' }}",
+            "textColor": "white"
+          }
+        }
+      },
+      "rowSources": [
+        {
+          "query": {
+            "command": "query GetVehicles($organizationId: Int!) { vehicles(organizationId: $organizationId) { id code status type } }",
+            "variables": { "organizationId": "{{ number organizationId }}" }
+          },
+          "path": "vehicles",
+          "mapping": {
+            "rowId": "{{ item.id }}",
+            "label": "{{ item.code }}",
+            "status": "{{ item.status }}",
+            "type": "{{ item.type }}"
+          }
+        }
+      ],
+      "itemSources": [
+        {
+          "query": {
+            "command": "query VehicleAssignments($organizationId: Int!, $start: String!, $end: String!) { vehicleAssignments(organizationId: $organizationId, start: $start, end: $end) { id vehicleId start end shipmentId status priority } }",
+            "variables": {
+              "organizationId": "{{ number organizationId }}",
+              "start": "{{ startDate }}",
+              "end": "{{ endDate }}"
+            }
+          },
+          "path": "vehicleAssignments",
+          "mapping": {
+            "id": "{{ item.id }}",
+            "rowId": "{{ item.vehicleId }}",
+            "start": "{{ item.start }}",
+            "end": "{{ item.end }}",
+            "title": "Shipment {{ item.shipmentId }}",
+            "status": "{{ item.status }}",
+            "priority": "{{ item.priority }}",
+            "color": "{{ eval item.status === 'delayed' ? '#e53e3e' : (item.priority === 'high' ? '#ffa726' : '#4ecdc4') }}"
+          }
+        }
+      ]
+    }
+  ]
+}

package/schemas/fields/README.md

@@ -0,0 +1,66 @@
+# Field Type Schemas
+
+This directory contains separate JSON schema files for each field type supported by the CargoXplorer TMS system.
+
+## Available Field Types
+
+### Basic Input Fields
+
+- **text.json** - Basic text input field
+- **number.json** - Numeric input field with validation and formatting
+- **email.json** - Email input field with validation
+- **password.json** - Password input field with security features
+- **tel.json** - Telephone number input field with formatting
+- **url.json** - URL input field with validation
+
+### Date/Time Fields
+
+- **date.json** - Date picker field
+- **datetime.json** - Date/time picker field (timezone-aware options)
+- **rangedatetime.json** - Date/time range picker field
+- **time.json** - Time picker field
+
+### Selection Fields
+
+- **select.json** - Dropdown select field with static options
+- **select-async.json** - Async dropdown select field with GraphQL queries
+- **autocomplete-googleplaces.json** - Google Places autocomplete field for addresses
+- **checkbox.json** - Checkbox input field
+- **radio.json** - Radio button group field
+
+### Text Area
+
+- **textarea.json** - Multi-line text input field
+
+## Schema Structure
+
+Each field type schema includes:
+
+- Field-specific properties and validation
+- Event handlers (onChange, onBlur, onFocus, onSelectValue)
+- Transformation configurations
+- Real-world examples from the CargoXplorer modules
+- Complete type safety and validation rules
+
+## Usage
+
+These schemas are referenced by the main `schemas.json` file using conditional validation based on the field `type` property. This modular approach makes it easier to:
+
+1. **Maintain** - Each field type is self-contained
+2. **Extend** - Add new field types without modifying the main schema
+3. **Validate** - Specific validation rules for each field type
+4. **Document** - Clear examples and descriptions for each type
+
+## Integration
+
+The field schemas integrate with:
+
+- **GraphQL queries** - For select-async and autocomplete fields
+- **Actions system** - For event handlers and value selection
+- **Template expressions** - For dynamic values and transformations
+- **Localization** - For multi-language support
+- **Permissions** - For role-based field access
+
+## Examples
+
+Each schema includes comprehensive examples derived from real usage patterns in the CargoXplorer TMS modules, ensuring practical applicability and correct implementation.

package/schemas/fields/attachment.json

@@ -0,0 +1,156 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Attachment Field Type",
+  "description": "Schema for attachment field type supporting images and files",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "attachment"
+    },
+    "label": {
+      "oneOf": [{ "type": "string" }, { "$ref": "../schemas.json#/definitions/localized" }],
+      "description": "Field label",
+      "x-example": { "en-US": "File Attachment" }
+    },
+    "placeholder": {
+      "type": "string",
+      "description": "Field placeholder text",
+      "x-example": "Add Attachment / Take Photo"
+    },
+    "required": {
+      "type": "boolean",
+      "description": "Whether field is required",
+      "x-example": false
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Whether field is disabled",
+      "x-example": false
+    },
+    "options": {
+      "type": "object",
+      "description": "Attachment field options",
+      "properties": {
+        "allowMultiple": {
+          "type": "boolean",
+          "description": "Allow selecting or uploading multiple attachments"
+        },
+        "allowClear": {
+          "type": "boolean",
+          "description": "Allow clearing the current selection"
+        },
+        "allowCamera": {
+          "type": "boolean",
+          "description": "Show camera capture button",
+          "default": true
+        },
+        "cameraQuality": {
+          "type": "string",
+          "enum": ["low", "medium", "high", "maximum"],
+          "description": "Camera capture quality setting",
+          "default": "high"
+        },
+        "captureFormat": {
+          "type": "string",
+          "enum": ["jpeg", "png"],
+          "description": "Camera capture image format",
+          "default": "jpeg"
+        },
+        "instantCamera": {
+          "type": "boolean",
+          "description": "Instant capture mode - auto-upload after capture"
+        },
+        "displayAs": {
+          "type": "string",
+          "enum": ["image", "file"],
+          "description": "Preferred display mode for attachments"
+        },
+        "previewWidth": {
+          "oneOf": [{ "type": "integer" }, { "type": "string" }],
+          "description": "Preview thumbnail width (pixels or CSS value)"
+        },
+        "previewHeight": {
+          "oneOf": [{ "type": "integer" }, { "type": "string" }],
+          "description": "Preview thumbnail height (pixels or CSS value)"
+        },
+        "maxSize": {
+          "type": "integer",
+          "description": "Maximum file size in bytes"
+        },
+        "allowedExtensions": {
+          "type": "array",
+          "description": "Allowed MIME types or extensions",
+          "items": { "type": "string" }
+        },
+        "parentId": {
+          "oneOf": [{ "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" }],
+          "description": "Logical parent type/entity for the attachment (e.g., Order, Contact)"
+        },
+        "onUploaded": {
+          "oneOf": [{ "type": "string" }, { "$ref": "../schemas.json#/definitions/actions" }],
+          "description": "Actions to execute after successful upload"
+        },
+        "clearAfterUpload": {
+          "type": "boolean",
+          "description": "Clear field after upload, showing success message briefly. Use for drop zone mode."
+        }
+      }
+    }
+  },
+  "required": ["type"],
+  "x-examples": [
+    {
+      "type": "attachment",
+      "label": "File Attachment",
+      "options": {
+        "allowMultiple": true,
+        "allowClear": true,
+        "displayAs": "image",
+        "previewWidth": 100,
+        "previewHeight": 100,
+        "maxSize": 10485760,
+        "allowedExtensions": ["image/*", "application/pdf"]
+      }
+    },
+    {
+      "type": "attachment",
+      "label": { "en-US": "Logo" },
+      "options": {
+        "allowMultiple": false,
+        "allowClear": true,
+        "displayAs": "image",
+        "previewWidth": 100,
+        "previewHeight": 100,
+        "maxSize": 1048576,
+        "allowedExtensions": ["image/*"]
+      }
+    },
+    {
+      "type": "attachment",
+      "label": { "en-US": "Upload Document" },
+      "options": {
+        "allowMultiple": false,
+        "allowClear": true,
+        "displayAs": "file",
+        "maxSize": 10485760,
+        "parentType": "Order"
+      }
+    },
+    {
+      "type": "attachment",
+      "label": { "en-US": "Upload to Order" },
+      "options": {
+        "allowMultiple": true,
+        "allowCamera": true,
+        "clearAfterUpload": true,
+        "parentId": "{{ orderId }}",
+        "parentType": "Order"
+      }
+    }
+  ]
+}

package/schemas/fields/autocomplete-googleplaces.json

@@ -0,0 +1,130 @@
+{
+  "$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",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "autocomplete-googleplaces"
+    },
+    "label": {
+      "oneOf": [
+        { "type": "string" },
+        { "$ref": "../schemas.json#/definitions/localized" }
+      ],
+      "description": "Field label",
+      "x-example": {
+        "en-US": "Address"
+      }
+    },
+    "placeholder": {
+      "type": "string",
+      "description": "Field placeholder text",
+      "x-example": "Enter address"
+    },
+    "required": {
+      "type": "boolean",
+      "description": "Whether field is required",
+      "x-example": false
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Whether field is disabled",
+      "x-example": false
+    },
+    "options": {
+      "type": "object",
+      "description": "Google Places specific options",
+      "properties": {
+        "itemLabelTemplate": {
+          "type": "string",
+          "description": "Template expression for displaying items",
+          "x-example": "{{ description }}"
+        },
+        "searchQuery": {
+          "type": "object",
+          "description": "Google Places search parameters",
+          "properties": {
+            "params": {
+              "type": "object",
+              "properties": {
+                "input": {
+                  "type": "string",
+                  "description": "Search input template",
+                  "x-example": "{{ string search }}"
+                },
+                "types": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Place types to search for",
+                  "x-example": ["address"]
+                },
+                "language": {
+                  "type": "string",
+                  "description": "Language code for results",
+                  "x-example": "en"
+                }
+              },
+              "required": ["input"]
+            }
+          },
+          "required": ["params"]
+        },
+        "valueQuery": {
+          "type": "object",
+          "description": "Parameters for place details query",
+          "properties": {
+            "params": {
+              "type": "object",
+              "properties": {
+                "fields": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Fields to retrieve from place details",
+                  "x-example": ["name", "address_components", "formatted_address", "geometry", "business_status"]
+                }
+              },
+              "required": ["fields"]
+            }
+          },
+          "required": ["params"]
+        },
+        "prefix": {
+          "type": "string",
+          "description": "Field name prefix for form fields",
+          "x-example": "orderEntityPickups[{{shipperIndex}}]."
+        }
+      },
+      "required": ["searchQuery", "valueQuery"]
+    },
+    "onSelectValue": {
+      "$ref": "../schemas.json#/definitions/actionsList",
+      "description": "Actions to execute when a place is selected",
+      "x-example": [
+        {
+          "setFields": {
+            "{{prefix}}countryCode": "{{ selectedItem.countryCode }}",
+            "{{prefix}}stateCode": "{{ selectedItem.stateCode }}",
+            "{{prefix}}cityName": "{{ selectedItem.city }}",
+            "{{prefix}}postalCode": "{{ selectedItem.postalCode }}",
+            "{{prefix}}customValues.address": "{{eval [selectedItem.name, selectedItem.addressLine].filter(Boolean).join(\", \") }}"
+          }
+        }
+      ]
+    },
+    "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", "options"]
+}