@objectstack/spec 0.3.2 → 0.4.1

package/dist/ui/widget.zod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"widget.zod.d.ts","sourceRoot":"","sources":["../../src/ui/widget.zod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB;IACjC;;;OAGG;;IAGH;;;;;OAKG;;IAMH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAGH;;;OAGG;;IAGH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEH,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}
+{"version":3,"file":"widget.zod.d.ts","sourceRoot":"","sources":["../../src/ui/widget.zod.ts"],"names":[],"mappings":"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"}

package/dist/ui/widget.zod.js

@@ -1,8 +1,301 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FieldWidgetPropsSchema = void 0;
+exports.FieldWidgetPropsSchema = exports.WidgetManifestSchema = exports.WidgetPropertySchema = exports.WidgetEventSchema = exports.WidgetLifecycleSchema = void 0;
 const zod_1 = require("zod");
 const field_zod_1 = require("../data/field.zod");
+/**
+ * Widget Lifecycle Hooks Schema
+ *
+ * Defines lifecycle callbacks for custom widgets inspired by Web Components and React.
+ * These hooks allow widgets to perform initialization, cleanup, and respond to changes.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Web_components
+ * @see https://react.dev/reference/react/Component#component-lifecycle
+ *
+ * @example
+ * ```typescript
+ * const widget = {
+ *   lifecycle: {
+ *     onMount: "console.log('Widget mounted')",
+ *     onUpdate: "if (prevProps.value !== props.value) { updateUI() }",
+ *     onUnmount: "cleanup()",
+ *     onValidate: "return value.length > 0 ? null : 'Required field'"
+ *   }
+ * }
+ * ```
+ */
+exports.WidgetLifecycleSchema = zod_1.z.object({
+    /**
+     * Called when widget is mounted/rendered for the first time
+     * Use for initialization, setting up event listeners, loading data, etc.
+     *
+     * @example "initializeDatePicker(); loadOptions();"
+     */
+    onMount: zod_1.z.string().optional().describe('Initialization code when widget mounts'),
+    /**
+     * Called when widget props change
+     * Receives previous props for comparison
+     *
+     * @example "if (prevProps.value !== props.value) { updateDisplay() }"
+     */
+    onUpdate: zod_1.z.string().optional().describe('Code to run when props change'),
+    /**
+     * Called when widget is about to be removed from DOM
+     * Use for cleanup, removing event listeners, canceling timers, etc.
+     *
+     * @example "destroyDatePicker(); cancelPendingRequests();"
+     */
+    onUnmount: zod_1.z.string().optional().describe('Cleanup code when widget unmounts'),
+    /**
+     * Custom validation logic for this widget
+     * Should return error message string if invalid, null/undefined if valid
+     *
+     * @example "return value && value.length >= 10 ? null : 'Minimum 10 characters'"
+     */
+    onValidate: zod_1.z.string().optional().describe('Custom validation logic'),
+    /**
+     * Called when widget receives focus
+     *
+     * @example "highlightField(); logFocusEvent();"
+     */
+    onFocus: zod_1.z.string().optional().describe('Code to run on focus'),
+    /**
+     * Called when widget loses focus
+     *
+     * @example "validateField(); saveFieldState();"
+     */
+    onBlur: zod_1.z.string().optional().describe('Code to run on blur'),
+    /**
+     * Called on any error in the widget
+     *
+     * @example "logError(error); showErrorNotification();"
+     */
+    onError: zod_1.z.string().optional().describe('Error handling code'),
+});
+/**
+ * Widget Event Schema
+ *
+ * Defines custom events that widgets can emit, inspired by DOM Events and Lightning Web Components.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/Events/Creating_and_triggering_events
+ * @see https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.events
+ *
+ * @example
+ * ```typescript
+ * const searchEvent = {
+ *   name: 'search',
+ *   bubbles: true,
+ *   cancelable: false,
+ *   payload: {
+ *     query: 'string',
+ *     filters: 'object'
+ *   }
+ * }
+ * ```
+ */
+exports.WidgetEventSchema = zod_1.z.object({
+    /**
+     * Event name
+     * Should be lowercase, dash-separated for consistency
+     *
+     * @example "value-change", "item-selected", "search-complete"
+     */
+    name: zod_1.z.string().describe('Event name'),
+    /**
+     * Event label for documentation
+     */
+    label: zod_1.z.string().optional().describe('Human-readable event label'),
+    /**
+     * Event description
+     */
+    description: zod_1.z.string().optional().describe('Event description and usage'),
+    /**
+     * Whether event bubbles up through the DOM hierarchy
+     *
+     * @default false
+     */
+    bubbles: zod_1.z.boolean().default(false).describe('Whether event bubbles'),
+    /**
+     * Whether event can be cancelled
+     *
+     * @default false
+     */
+    cancelable: zod_1.z.boolean().default(false).describe('Whether event is cancelable'),
+    /**
+     * Event payload schema
+     * Defines the data structure sent with the event
+     *
+     * @example { userId: 'string', timestamp: 'number' }
+     */
+    payload: zod_1.z.record(zod_1.z.any()).optional().describe('Event payload schema'),
+});
+/**
+ * Widget Property Definition Schema
+ *
+ * Defines the contract for widget configuration properties.
+ * Inspired by React PropTypes and Web Component attributes.
+ *
+ * @see https://react.dev/reference/react/Component#static-proptypes
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements
+ *
+ * @example
+ * ```typescript
+ * const widgetProps = {
+ *   maxLength: {
+ *     type: 'number',
+ *     required: false,
+ *     default: 100,
+ *     description: 'Maximum input length'
+ *   }
+ * }
+ * ```
+ */
+exports.WidgetPropertySchema = zod_1.z.object({
+    /**
+     * Property name
+     * Should be camelCase following ObjectStack conventions
+     */
+    name: zod_1.z.string().describe('Property name (camelCase)'),
+    /**
+     * Property label for UI
+     */
+    label: zod_1.z.string().optional().describe('Human-readable label'),
+    /**
+     * Property data type
+     *
+     * @example "string", "number", "boolean", "array", "object", "function"
+     */
+    type: zod_1.z.enum(['string', 'number', 'boolean', 'array', 'object', 'function', 'any'])
+        .describe('TypeScript type'),
+    /**
+     * Whether property is required
+     *
+     * @default false
+     */
+    required: zod_1.z.boolean().default(false).describe('Whether property is required'),
+    /**
+     * Default value for the property
+     */
+    default: zod_1.z.any().optional().describe('Default value'),
+    /**
+     * Property description
+     */
+    description: zod_1.z.string().optional().describe('Property description'),
+    /**
+     * Property validation schema
+     * Can include min/max, regex, enum values, etc.
+     */
+    validation: zod_1.z.record(zod_1.z.any()).optional().describe('Validation rules'),
+    /**
+     * Property category for grouping in UI
+     */
+    category: zod_1.z.string().optional().describe('Property category'),
+});
+/**
+ * Widget Manifest Schema
+ *
+ * Complete definition for a custom widget including metadata, lifecycle, events, and props.
+ * This is used for widget registration and discovery.
+ *
+ * @example
+ * ```typescript
+ * const customWidget = {
+ *   name: 'custom_date_picker',
+ *   label: 'Custom Date Picker',
+ *   version: '1.0.0',
+ *   author: 'Company Name',
+ *   fieldTypes: ['date', 'datetime'],
+ *   lifecycle: { ... },
+ *   events: [ ... ],
+ *   properties: [ ... ]
+ * }
+ * ```
+ */
+exports.WidgetManifestSchema = zod_1.z.object({
+    /**
+     * Widget identifier (snake_case)
+     */
+    name: zod_1.z.string()
+        .regex(/^[a-z_][a-z0-9_]*$/)
+        .describe('Widget identifier (snake_case)'),
+    /**
+     * Human-readable widget name
+     */
+    label: zod_1.z.string().describe('Widget display name'),
+    /**
+     * Widget description
+     */
+    description: zod_1.z.string().optional().describe('Widget description'),
+    /**
+     * Widget version (semver)
+     */
+    version: zod_1.z.string().optional().describe('Widget version (semver)'),
+    /**
+     * Widget author/organization
+     */
+    author: zod_1.z.string().optional().describe('Widget author'),
+    /**
+     * Icon name or URL
+     */
+    icon: zod_1.z.string().optional().describe('Widget icon'),
+    /**
+     * Field types this widget supports
+     *
+     * @example ["text", "email", "url"]
+     */
+    fieldTypes: zod_1.z.array(zod_1.z.string()).optional().describe('Supported field types'),
+    /**
+     * Widget category for organization
+     */
+    category: zod_1.z.enum(['input', 'display', 'picker', 'editor', 'custom'])
+        .default('custom')
+        .describe('Widget category'),
+    /**
+     * Widget lifecycle hooks
+     */
+    lifecycle: exports.WidgetLifecycleSchema.optional().describe('Lifecycle hooks'),
+    /**
+     * Custom events this widget emits
+     */
+    events: zod_1.z.array(exports.WidgetEventSchema).optional().describe('Custom events'),
+    /**
+     * Widget configuration properties
+     */
+    properties: zod_1.z.array(exports.WidgetPropertySchema).optional().describe('Configuration properties'),
+    /**
+     * Widget implementation
+     * URL to component or inline code
+     */
+    implementation: zod_1.z.object({
+        type: zod_1.z.enum(['url', 'inline', 'module']).describe('Implementation type'),
+        source: zod_1.z.string().describe('Source URL, inline code, or module path'),
+    }).optional().describe('Widget implementation'),
+    /**
+     * Widget dependencies
+     * External libraries or scripts needed
+     */
+    dependencies: zod_1.z.array(zod_1.z.object({
+        name: zod_1.z.string(),
+        version: zod_1.z.string().optional(),
+        url: zod_1.z.string().url().optional(),
+    })).optional().describe('Widget dependencies'),
+    /**
+     * Widget screenshots for showcase
+     */
+    screenshots: zod_1.z.array(zod_1.z.string().url()).optional().describe('Screenshot URLs'),
+    /**
+     * Widget documentation URL
+     */
+    documentation: zod_1.z.string().url().optional().describe('Documentation URL'),
+    /**
+     * License information
+     */
+    license: zod_1.z.string().optional().describe('License (SPDX identifier)'),
+    /**
+     * Tags for discovery
+     */
+    tags: zod_1.z.array(zod_1.z.string()).optional().describe('Tags for categorization'),
+});
 /**
  * Field Widget Props Schema
  *

package/json-schema/ai/{AIWorkflowAutomation.json → AIOrchestration.json}

@@ -1,24 +1,24 @@
 {
-  "$ref": "#/definitions/AIWorkflowAutomation",
+  "$ref": "#/definitions/AIOrchestration",
   "definitions": {
-    "AIWorkflowAutomation": {
+    "AIOrchestration": {
       "type": "object",
       "properties": {
         "name": {
           "type": "string",
           "pattern": "^[a-z_][a-z0-9_]*$",
-          "description": "Workflow unique identifier (snake_case)"
+          "description": "Orchestration unique identifier (snake_case)"
         },
         "label": {
           "type": "string",
-          "description": "Workflow display name"
+          "description": "Display name"
         },
         "description": {
           "type": "string"
         },
         "objectName": {
           "type": "string",
-          "description": "Target object for this workflow"
+          "description": "Target object for this orchestration"
         },
         "trigger": {
           "type": "string",

package/json-schema/ai/{AIWorkflowExecutionResult.json → AIOrchestrationExecutionResult.json}

@@ -1,7 +1,7 @@
 {
-  "$ref": "#/definitions/AIWorkflowExecutionResult",
+  "$ref": "#/definitions/AIOrchestrationExecutionResult",
   "definitions": {
-    "AIWorkflowExecutionResult": {
+    "AIOrchestrationExecutionResult": {
       "type": "object",
       "properties": {
         "workflowName": {

package/json-schema/ai/{AIWorkflowTrigger.json → AIOrchestrationTrigger.json}

@@ -1,7 +1,7 @@
 {
-  "$ref": "#/definitions/AIWorkflowTrigger",
+  "$ref": "#/definitions/AIOrchestrationTrigger",
   "definitions": {
-    "AIWorkflowTrigger": {
+    "AIOrchestrationTrigger": {
       "type": "string",
       "enum": [
         "record_created",

package/json-schema/ai/{BatchAIWorkflowExecution.json → BatchAIOrchestrationExecution.json}

@@ -1,12 +1,12 @@
 {
-  "$ref": "#/definitions/BatchAIWorkflowExecution",
+  "$ref": "#/definitions/BatchAIOrchestrationExecution",
   "definitions": {
-    "BatchAIWorkflowExecution": {
+    "BatchAIOrchestrationExecution": {
       "type": "object",
       "properties": {
         "workflowName": {
           "type": "string",
-          "description": "Workflow to execute"
+          "description": "Orchestration to execute"
         },
         "recordIds": {
           "type": "array",

package/json-schema/{system → api}/ApiEndpoint.json

@@ -21,7 +21,9 @@
             "POST",
             "PUT",
             "DELETE",
-            "PATCH"
+            "PATCH",
+            "HEAD",
+            "OPTIONS"
           ],
           "description": "HTTP Method"
         },

package/json-schema/{system → api}/ApiRoutes.json

@@ -6,27 +6,27 @@
       "properties": {
         "data": {
           "type": "string",
-          "description": "e.g. /api/v1/data"
+          "description": "e.g. /api/data"
         },
         "metadata": {
           "type": "string",
-          "description": "e.g. /api/v1/meta"
+          "description": "e.g. /api/meta"
         },
         "auth": {
           "type": "string",
-          "description": "e.g. /api/v1/auth"
+          "description": "e.g. /api/auth"
         },
-        "actions": {
+        "automation": {
           "type": "string",
-          "description": "e.g. /api/v1/p"
+          "description": "e.g. /api/automation"
         },
         "storage": {
           "type": "string",
-          "description": "e.g. /api/v1/storage"
+          "description": "e.g. /api/storage"
         },
         "graphql": {
           "type": "string",
-          "description": "e.g. /api/v1/graphql"
+          "description": "e.g. /graphql"
         }
       },
       "required": [

package/json-schema/{system → api}/Discovery.json

@@ -23,27 +23,27 @@
           "properties": {
             "data": {
               "type": "string",
-              "description": "e.g. /api/v1/data"
+              "description": "e.g. /api/data"
             },
             "metadata": {
               "type": "string",
-              "description": "e.g. /api/v1/meta"
+              "description": "e.g. /api/meta"
             },
             "auth": {
               "type": "string",
-              "description": "e.g. /api/v1/auth"
+              "description": "e.g. /api/auth"
             },
-            "actions": {
+            "automation": {
               "type": "string",
-              "description": "e.g. /api/v1/p"
+              "description": "e.g. /api/automation"
             },
             "storage": {
               "type": "string",
-              "description": "e.g. /api/v1/storage"
+              "description": "e.g. /api/storage"
             },
             "graphql": {
               "type": "string",
-              "description": "e.g. /api/v1/graphql"
+              "description": "e.g. /graphql"
             }
           },
           "required": [