@cxtms/cx-schema 1.0.0

package/schemas/actions/navigate.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "navigate Action",
+  "type": "object",
+  "properties": {
+    "navigate": {
+      "type": "string",
+      "description": "Navigation path",
+      "x-examples": [
+        "~/team-calendars/view/{{ calendarId }}",
+        "warehouseReceipts/{{ orderId }}",
+        "receiving/{{ encodedTrackingNumber }}",
+        "vessels/{{ vesselId }}"
+      ]
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/actions/navigateBack.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "navigateBack Action",
+  "type": "object",
+  "properties": {
+    "navigateBack": {
+      "type": "object",
+      "properties": {
+        "fallback": {
+          "type": "string",
+          "description": "Fallback path if no previous page",
+          "x-examples": ["~/delivery-schedules"]
+        },
+        "result": {
+          "description": "Result to return when navigating back"
+        }
+      },
+      "x-examples": [{ "fallback": "~/delivery-schedules" }]
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/actions/navigateBackOrClose.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "navigateBackOrClose Action",
+  "type": "object",
+  "properties": {
+    "navigateBackOrClose": {
+      "type": "object",
+      "properties": {
+        "fallback": {
+          "type": "string",
+          "description": "Fallback path if no previous page; used when navigation history is empty"
+        },
+        "result": {
+          "description": "Result payload to supply when navigating back or closing"
+        }
+      },
+      "x-examples": [{ "fallback": "~/delivery-schedules" }, { "fallback": "users" }, { "result": { "saved": true } }]
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/actions/notification.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "notification Action",
+  "type": "object",
+  "properties": {
+    "notification": {
+      "type": "object",
+      "properties": {
+        "message": { "oneOf": [{ "type": "string" }, { "$ref": "../schemas.json#/definitions/localized" }] },
+        "type": { "type": "string", "enum": ["success", "error", "warning", "info"] }
+      },
+      "x-examples": [
+        { "message": { "en-US": "Selected Route Legs were added to the Route successfully" }, "type": "success" },
+        { "message": "Scanner closed" }
+      ]
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/actions/openBarcodeScanner.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "openBarcodeScanner Action",
+  "type": "object",
+  "properties": {
+    "openBarcodeScanner": {
+      "type": "object",
+      "properties": {
+        "title": {
+          "oneOf": [{ "type": "string" }, { "$ref": "../schemas.json#/definitions/localized" }],
+          "description": "Optional title text for the scanner UI"
+        },
+        "minBarcodeLength": {
+          "type": "integer",
+          "description": "Minimum length for recognized barcodes",
+          "default": 1
+        },
+        "allowMultiple": {
+          "type": "boolean",
+          "description": "Allow scanning multiple barcodes before closing",
+          "default": false
+        },
+        "maxBarcodes": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum number of barcodes to collect in multi-scan mode"
+        },
+        "onScan": {
+          "$ref": "../schemas.json#/definitions/actionsList",
+          "description": "Actions to execute after each successful scan"
+        },
+        "onComplete": {
+          "$ref": "../schemas.json#/definitions/actionsList",
+          "description": "Actions to execute when the scanner UI finishes multi-scan and closes"
+        },
+        "onClose": {
+          "$ref": "../schemas.json#/definitions/actionsList",
+          "description": "Actions to execute when the scanner UI is closed without completing"
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "allowMultiple": { "const": false } }, "required": ["allowMultiple"] },
+          "then": { "not": { "required": ["maxBarcodes"] } }
+        }
+      ],
+      "x-examples": [
+        {
+          "title": "Scan Item",
+          "minBarcodeLength": 8,
+          "onScan": [
+            { "setStore": { "scannedBarcode": "{{ result.data }}" } },
+            { "notification": { "message": "Scanned: {{ result.data }}" } }
+          ],
+          "onClose": [{ "notification": { "message": "Scanner closed" } }]
+        },
+        {
+          "title": "Scan multiple items",
+          "allowMultiple": true,
+          "minBarcodeLength": 8,
+          "onScan": [{ "notification": { "message": "Captured: {{ result.data }}" } }],
+          "onComplete": [
+            { "setStore": { "scannedBarcodes": "{{ result.barcodes }}" } },
+            { "notification": { "message": "Collected {{ result.barcodes.length }} barcodes" } }
+          ]
+        },
+        {
+          "title": "Scan up to 5 items",
+          "allowMultiple": true,
+          "maxBarcodes": 5,
+          "minBarcodeLength": 8,
+          "onScan": [{ "notification": { "message": "Added: {{ result.data }}" } }],
+          "onComplete": [
+            { "setStore": { "scannedBarcodes": "{{ result.barcodes }}" } },
+            { "notification": { "message": "Scanning completed ({{ result.barcodes.length }} items)" } }
+          ]
+        },
+        {
+          "title": "Scan or log",
+          "minBarcodeLength": 10,
+          "allowMultiple": true,
+          "maxBarcodes": 3,
+          "onScan": [
+            {
+              "if": "{{ eval result.format === 'QR_CODE' }}",
+              "then": [{ "navigate": "~/qr-details" }],
+              "else": [
+                {
+                  "mutation": {
+                    "command": "logBarcodeScan",
+                    "variables": { "barcodeData": "{{ result.data }}", "format": "{{ result.format }}" }
+                  }
+                },
+                { "notification": { "message": "Barcode logged" } }
+              ]
+            }
+          ],
+          "onComplete": [{ "notification": { "message": "Finished scanning" } }]
+        }
+      ]
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/actions/query.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "query Action",
+  "type": "object",
+  "properties": {
+    "query": {
+      "type": "object",
+      "properties": {
+        "command": { "type": "string", "description": "GraphQL query string" },
+        "variables": { "type": "object", "description": "Query variables" },
+        "onSuccess": { "$ref": "../schemas.json#/definitions/actionsList" },
+        "onError": { "$ref": "../schemas.json#/definitions/actionsList" }
+      },
+      "x-example": {
+        "command": "query ($organizationId: Int!, $filter: String!) { attachments(organizationId: $organizationId, filter: $filter) { items { attachmentId } } }",
+        "variables": {
+          "organizationId": "{{ number organizationId }}",
+          "filter": "parentId:{{ orderId }}"
+        },
+        "onSuccess": [
+          {
+            "setFields": {
+              "attachmentIds": "{{ eval attachments.items.map(x => x.attachmentId) }}"
+            }
+          }
+        ],
+        "onError": [{ "notification": { "message": "Failed to load attachments", "type": "error" } }]
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/actions/refresh.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "refresh Action",
+  "type": "object",
+  "properties": {
+    "refresh": {
+      "type": "string",
+      "description": "Component or data source to refresh",
+      "x-examples": ["calendars", "calendarAvailability", "chargesGrid", "users", "routeLegsGrid"]
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/actions/resetDirtyState.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "resetDirtyState Action",
+  "type": "object",
+  "properties": {
+    "resetDirtyState": {
+      "type": "object",
+      "description": "Resets the dirty state of a form to false, indicating the form no longer has unsaved changes",
+      "properties": {
+        "formName": {
+          "type": "string",
+          "description": "The name of the form to reset (optional, defaults to the current form context)"
+        }
+      },
+      "x-examples": [
+        { "formName": "myForm" },
+        {}
+      ]
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/actions/setFields.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "setFields Action",
+  "type": "object",
+  "properties": {
+    "setFields": {
+      "type": "object",
+      "description": "Fields to set in form or store",
+      "x-examples": [
+        {
+          "orderSummary.totalWeight": "{{ format order.orderSummary.totalWeight 0.00}}",
+          "orderSummary.weightUnit": "{{ order.orderSummary.weightUnit }}",
+          "orderSummary.totalVolume": "{{ format order.orderSummary.totalVolume 0.00}}",
+          "orderSummary.volumeUnit": "{{ order.orderSummary.volumeUnit }}",
+          "orderSummary.totalQuantity": "{{ order.orderSummary.totalQuantity }}"
+        }
+      ]
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/actions/setStore.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "setStore Action",
+  "type": "object",
+  "properties": {
+    "setStore": {
+      "type": "object",
+      "description": "Store values to set",
+      "x-examples": [{ "scannedBarcode": "{{ result.data }}" }, { "scannedBarcodes": "{{ result.barcodes }}" }]
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/actions/validateForm.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "validateForm Action",
+  "type": "object",
+  "properties": {
+    "validateForm": {
+      "type": "object",
+      "properties": {
+        "validationSchema": { "type": "object", "description": "Form validation schema" }
+      },
+      "x-examples": [{ "validationSchema": { "fieldName": { "type": "string", "required": true } } }]
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/actions/workflow.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "workflow Action",
+  "type": "object",
+  "properties": {
+    "workflow": {
+      "type": "object",
+      "properties": {
+        "workflowId": { "type": "string", "description": "Workflow identifier" },
+        "inputs": { "type": "object", "description": "Workflow inputs" },
+        "onSuccess": { "$ref": "../schemas.json#/definitions/actionsList" },
+        "onError": { "$ref": "../schemas.json#/definitions/actionsList" }
+      },
+      "x-examples": [
+        {
+          "workflowId": "b7c4ffa9-bf7e-4e2c-8e57-8f24f4a2b8a8",
+          "inputs": { "request": { "message": "Hello, World!" } },
+          "onSuccess": [{ "notification": { "message": "Echo executed successfully. {{ response.echo.message }}" } }]
+        }
+      ]
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/components/README.md

@@ -0,0 +1,147 @@
+# Component Schemas
+
+This directory contains individual JSON schema files for each CargoXplorer component type. Breaking down component schemas into separate files improves maintainability, organization, and reusability.
+
+## Directory Structure
+
+```
+schema/
+├── components/
+│   ├── appComponent.json     # Base app component schema
+│   ├── navbar.json          # Navigation bar component
+│   ├── navbarItem.json      # Navigation item component
+│   ├── navDropdown.json     # Navigation dropdown component
+│   ├── navbarLink.json      # Navigation link component
+│   ├── collection.json      # Collection/iteration component
+│   ├── row.json             # Row layout component
+│   ├── dataGrid.json        # Data grid component
+│   ├── button.json          # Button component
+│   ├── form.json            # Form component
+│   ├── layout.json          # Layout container component
+│   ├── tabs.json            # Tabs container component
+│   ├── tab.json             # Individual tab component
+│   ├── field.json           # Form field component
+│   ├── dropdown.json        # Dropdown menu component
+│   ├── datasource.json      # Data source component
+│   ├── calendar.json        # Calendar component
+│   ├── module.json          # Module component
+│   ├── index.json           # Component schema index
+│   └── README.md            # This documentation file
+├── fields/                  # Field type schemas
+│   ├── text.json
+│   ├── select-async.json
+│   └── ...
+└── schemas.json             # Main schema file with references
+```
+
+## Benefits of Separate Component Schemas
+
+### 1. **Maintainability**
+
+- Each component schema is in its own file
+- Easier to find and update specific component definitions
+- Reduces the size of the main schemas.json file
+
+### 2. **Reusability**
+
+- Component schemas can be referenced from multiple locations
+- Enables better modular schema design
+- Facilitates schema composition and inheritance
+
+### 3. **Organization**
+
+- Clear separation between different component types
+- Logical file structure mirrors component hierarchy
+- Better developer experience when working with schemas
+
+### 4. **Collaboration**
+
+- Multiple developers can work on different component schemas simultaneously
+- Reduces merge conflicts in the main schema file
+- Easier code reviews for component-specific changes
+
+## Usage
+
+The main `schemas.json` file now references these separate component files:
+
+```json
+{
+  "components": {
+    "schemas": {
+      "button": {
+        "$ref": "components/button.json"
+      },
+      "dataGrid": {
+        "$ref": "components/dataGrid.json"
+      },
+      "form": {
+        "$ref": "components/form.json"
+      }
+      // ... other components
+    }
+  }
+}
+```
+
+## Schema References
+
+Each component schema file uses relative references to the main schemas.json file for shared definitions:
+
+```json
+{
+  "properties": {
+    "onClick": {
+      "$ref": "../schemas.json#/definitions/actionsList"
+    },
+    "isHidden": {
+      "$ref": "../schemas.json#/definitions/templateExpression"
+    }
+  }
+}
+```
+
+## Adding New Components
+
+To add a new component schema:
+
+1. Create a new JSON file in this directory (e.g., `myComponent.json`)
+2. Define the component schema following the existing patterns
+3. Add a reference to the component in the main `schemas.json` file
+4. Update the `index.json` file if needed
+5. Update this README.md file
+
+## Component Schema Structure
+
+Each component schema should follow this general structure:
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Component Name",
+  "type": "object",
+  "properties": {
+    "component": {
+      "type": "string",
+      "const": "componentName"
+    },
+    "name": {
+      "type": "string",
+      "description": "Component name identifier"
+    },
+    "props": {
+      "type": "object",
+      "properties": {
+        // Component-specific properties
+      }
+    },
+    "children": {
+      "$ref": "../schemas.json#/definitions/componentChildren"
+    }
+  },
+  "required": ["component"]
+}
+```
+
+## Validation
+
+All component schemas are validated against JSON Schema Draft 07 specification. Ensure your schemas are valid JSON and follow the established patterns for consistency.

package/schemas/components/appComponent.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Generic CargoXplorer App Component",
+  "type": "object",
+  "description": "Base schema for any CargoXplorer component that can be used within the application",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Component name in format 'ModuleName/ComponentName'",
+      "pattern": "^[A-Za-z0-9]+/[A-Za-z0-9]+$"
+    },
+    "permissions": {
+      "$ref": "../schemas.json#/definitions/permissions"
+    },
+    "priority": {
+      "type": "integer",
+      "default": 0,
+      "description": "Component priority (higher number = higher priority)"
+    },
+    "displayName": {
+      "$ref": "../schemas.json#/definitions/localized"
+    },
+    "props": {
+      "oneOf": [
+        {
+          "type": "object",
+          "description": "Properties passed to the component when targeting a slot",
+          "properties": {
+            "targetSlot": {
+              "type": "string",
+              "description": "Name of the slot this component targets"
+            },
+            "order": {
+              "type": "integer",
+              "description": "Order of the component in the target slot"
+            }
+          },
+          "additionalProperties": true
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "layout": {
+      "$ref": "../schemas.json#/definitions/component"
+    }
+  },
+  "required": ["name", "layout"]
+}

package/schemas/components/barcodeScanner.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Barcode Scanner Component",
+  "type": "object",
+  "properties": {
+    "component": {
+      "type": "string",
+      "const": "barcodeScanner"
+    },
+    "name": {
+      "type": "string",
+      "description": "Component name identifier"
+    },
+    "props": {
+      "type": "object",
+      "properties": {
+        "minBarcodeLength": {
+          "type": "integer",
+          "description": "Minimum length for recognized barcodes"
+        },
+        "onScan": {
+          "$ref": "../schemas.json#/definitions/actionsList",
+          "description": "Actions to execute when a barcode is successfully scanned"
+        },
+        "isHidden": {
+          "$ref": "../schemas.json#/definitions/templateExpression",
+          "description": "Boolean expression for conditional rendering"
+        }
+      }
+    }
+  },
+  "required": ["component"],
+  "x-examples": [
+    {
+      "component": "barcodeScanner",
+      "props": {
+        "minBarcodeLength": 8,
+        "onScan": [
+          { "setStore": { "scannedBarcode": "{{ result.data }}" } },
+          { "notification": { "message": "Barcode scanned: {{ result.data }}" } }
+        ]
+      }
+    },
+    {
+      "component": "barcodeScanner",
+      "props": {
+        "minBarcodeLength": 10,
+        "onScan": [
+          {
+            "if": "{{ eval result.format === 'QR_CODE' }}",
+            "then": [{ "setStore": { "qrCodeData": "{{ result.data }}" } }, { "navigate": "/qr-details" }],
+            "else": [
+              {
+                "mutation": {
+                  "command": "logBarcodeScan",
+                  "variables": {
+                    "barcodeData": "{{ result.data }}",
+                    "format": "{{ result.format }}"
+                  }
+                }
+              },
+              { "notification": { "message": "Barcode logged: {{ result.data }}" } }
+            ]
+          }
+        ]
+      }
+    }
+  ]
+}