@objectstack/spec 6.7.0 → 6.8.0

package/dist/data/index.js

@@ -693,6 +693,11 @@ var FieldType = zod.z.enum([
   "formula",
   "summary",
   "autonumber",
+  // Embedded structured values (stored as JSON on the parent row — no separate table / FK)
+  "composite",
+  // Single embedded sub-object with declared sub-fields  (≈ Strapi component / ACF group)
+  "repeater",
+  // Repeating embedded sub-object array with declared sub-fields  (≈ Strapi repeatable component / ACF repeater)
   // Enhanced Types
   "location",
   // GPS coordinates
@@ -701,7 +706,7 @@ var FieldType = zod.z.enum([
   "code",
   // Code editor (JSON/SQL/JS)
   "json",
-  // Structured JSON data
+  // Structured JSON data (untyped escape hatch)
   "color",
   // Color picker
   "rating",
@@ -1659,6 +1664,19 @@ var ViewDataSchema = lazySchema(() => zod.z.discriminatedUnion("provider", [
   zod.z.object({
     provider: zod.z.literal("value"),
     items: zod.z.array(zod.z.unknown()).describe("Static data array")
+  }),
+  /**
+   * Schema-bound data source — used by standalone forms whose data is
+   * shaped by a JSON Schema (or Zod-derived schema) rather than by an
+   * ObjectQL object. Powers the metadata editor, action input dialogs,
+   * and any Form that is not bound to a CRUD object.
+   */
+  zod.z.object({
+    provider: zod.z.literal("schema"),
+    /** Schema identifier (e.g. metadata type name "report"). Resolved at runtime against /meta entries. */
+    schemaId: zod.z.string().describe("Schema identifier \u2014 typically the metadata type name"),
+    /** Optional inline JSON Schema; when omitted the runtime resolves schemaId from the server. */
+    schema: zod.z.record(zod.z.string(), zod.z.unknown()).optional().describe("Inline JSON Schema (Draft 2020-12). Optional when schemaId is resolvable.")
   })
 ]));
 var ViewFilterRuleSchema = lazySchema(() => zod.z.object({
@@ -1953,29 +1971,63 @@ var ListViewSchema = lazySchema(() => zod.z.object({
   performance: PerformanceConfigSchema.optional().describe("Performance optimization settings")
 }));
 var FormFieldSchema = lazySchema(() => zod.z.object({
+  /** Field name (snake_case) */
   field: zod.z.string().describe("Field name (snake_case)"),
+  /** Field type — reuses Data.FieldType. When set, widget is auto-inferred (can be overridden). */
+  type: FieldType.optional().describe("Field type (auto-infers widget if omitted)"),
+  /** Select/multiselect options — only needed when type=select/multiselect/radio/checkboxes */
+  options: zod.z.array(SelectOptionSchema).optional().describe("Options for select/multiselect/radio/checkboxes fields"),
+  /** Reference object for lookup/master_detail fields */
+  reference: zod.z.string().optional().describe("Target object name for lookup/master_detail fields"),
+  /** Text constraints */
+  maxLength: zod.z.number().optional().describe("Maximum character length (for text/textarea/email/url/phone)"),
+  minLength: zod.z.number().optional().describe("Minimum character length"),
+  /** Number constraints */
+  min: zod.z.number().optional().describe("Minimum value (for number/currency/percent/slider)"),
+  max: zod.z.number().optional().describe("Maximum value"),
+  precision: zod.z.number().optional().describe("Total digits (for number/currency)"),
+  scale: zod.z.number().optional().describe("Decimal places"),
+  /** Multi-value flag */
+  multiple: zod.z.boolean().optional().describe("Allow multiple values (for select/lookup/file/image)"),
+  /** UI overrides */
   label: I18nLabelSchema.optional().describe("Display label override"),
   placeholder: I18nLabelSchema.optional().describe("Placeholder text"),
   helpText: I18nLabelSchema.optional().describe("Help/hint text"),
   readonly: zod.z.boolean().optional().describe("Read-only override"),
+  immutable: zod.z.boolean().optional().describe("Editable on create, locked once the record exists (e.g. machine names)."),
   required: zod.z.boolean().optional().describe("Required override"),
   hidden: zod.z.boolean().optional().describe("Hidden override"),
   colSpan: zod.z.number().int().min(1).max(4).optional().describe("Column span in grid layout (1-4)"),
-  widget: zod.z.string().optional().describe("Custom widget/component name"),
+  /** Custom widget override — only needed when auto-inference is insufficient */
+  widget: zod.z.string().optional().describe("Custom widget/component name (overrides type-based inference)"),
+  /** For `code` fields: source language (e.g. 'javascript', 'sql', 'json', 'typescript', 'expression', 'cel'). Drives syntax highlighting. */
+  language: zod.z.string().optional().describe("Code editor language (for type=code)"),
+  /**
+   * Sub-fields for `composite` / `repeater` types — declares the inner shape
+   * of an embedded sub-object (composite) or each row of an embedded
+   * sub-object array (repeater). Recursive: composite/repeater can nest.
+   * Ignored for all other field types.
+   *
+   * Use `lookup` / `master_detail` instead when the children are independent
+   * records with their own IDs in a separate object/table.
+   */
+  fields: zod.z.array(zod.z.lazy(() => FormFieldSchema)).optional().describe("Sub-fields for composite/repeater types"),
   dependsOn: zod.z.string().optional().describe("Parent field name for cascading"),
   visibleOn: ExpressionInputSchema.optional().describe("Visibility predicate (CEL).")
 }));
 var FormSectionSchema = lazySchema(() => zod.z.object({
   label: I18nLabelSchema.optional(),
+  description: zod.z.string().optional().describe("Optional description rendered under the section header."),
   collapsible: zod.z.boolean().default(false),
   collapsed: zod.z.boolean().default(false),
+  visibleOn: ExpressionInputSchema.optional().describe("Visibility predicate (CEL). Hides the whole section when false."),
   columns: zod.z.union([
     zod.z.enum(["1", "2", "3", "4"]),
     zod.z.literal(1),
     zod.z.literal(2),
     zod.z.literal(3),
     zod.z.literal(4)
-  ]).default(2).transform((val) => typeof val === "string" ? parseInt(val) : val),
+  ]).default(1).transform((val) => typeof val === "string" ? parseInt(val) : val),
   fields: zod.z.array(zod.z.union([
     zod.z.string(),
     // Legacy: simple field name
@@ -2044,6 +2096,13 @@ lazySchema(() => zod.z.object({
   listViews: zod.z.record(zod.z.string(), ListViewSchema).optional().describe("Additional named list views"),
   formViews: zod.z.record(zod.z.string(), FormViewSchema).optional().describe("Additional named form views")
 }));
+function defineForm(config) {
+  const { schemaId, ...rest } = config;
+  return FormViewSchema.parse({
+    ...rest,
+    data: { provider: "schema", schemaId }
+  });
+}
 
 // src/data/object.zod.ts
 var ApiMethod = zod.z.enum([
@@ -3915,6 +3974,226 @@ var DatasetSchema = lazySchema(() => zod.z.object({
 function defineDataset(objectDef, config) {
   return DatasetSchema.parse({ ...config, object: objectDef.name });
 }
+
+// src/data/object.form.ts
+var objectForm = defineForm({
+  schemaId: "object",
+  type: "simple",
+  sections: [
+    {
+      label: "Basics",
+      description: "Identity, labels, and taxonomy.",
+      columns: 2,
+      fields: [
+        { field: "name", type: "text", required: true, immutable: true, colSpan: 1, helpText: "snake_case unique identifier (immutable after creation)" },
+        { field: "label", type: "text", colSpan: 1, helpText: 'Singular display name (e.g. "Account")' },
+        { field: "pluralLabel", type: "text", colSpan: 1, helpText: 'Plural display name (e.g. "Accounts")' },
+        { field: "icon", type: "text", colSpan: 1, helpText: 'Lucide icon name (e.g. "building", "users")' },
+        { field: "description", type: "textarea", colSpan: 2, helpText: "Developer documentation" },
+        { field: "tags", type: "tags", colSpan: 2, helpText: 'Categorization tags (e.g. "sales", "system")' },
+        { field: "active", type: "boolean", colSpan: 1, helpText: "Is the object active and usable" },
+        { field: "isSystem", type: "boolean", colSpan: 1, helpText: "System object (protected from deletion)" },
+        { field: "abstract", type: "boolean", colSpan: 1, helpText: "Abstract base (cannot be instantiated)" }
+      ]
+    },
+    {
+      label: "Fields",
+      description: "Define the data model \u2014 each row becomes a column in the database table.",
+      fields: [
+        {
+          field: "fields",
+          type: "repeater",
+          widget: "grid",
+          required: true,
+          helpText: "Add the columns this object will store",
+          fields: [
+            { field: "name", type: "text", required: true, immutable: true, helpText: "snake_case identifier" },
+            { field: "label", type: "text", helpText: "Display label" },
+            { field: "type", type: "select", required: true, helpText: "Field type" },
+            { field: "required", type: "boolean" },
+            { field: "reference", type: "text", helpText: "Target object (for lookup/master_detail)" }
+          ]
+        }
+      ]
+    },
+    {
+      label: "Capabilities",
+      description: "System features and API exposure.",
+      collapsible: true,
+      collapsed: true,
+      fields: [
+        {
+          field: "capabilities",
+          type: "composite",
+          helpText: "Enable/disable system features",
+          fields: [
+            { field: "trackHistory", type: "boolean" },
+            { field: "searchable", type: "boolean" },
+            { field: "apiEnabled", type: "boolean" },
+            { field: "files", type: "boolean" },
+            { field: "feeds", type: "boolean" },
+            { field: "activities", type: "boolean" },
+            { field: "trash", type: "boolean" },
+            { field: "mru", type: "boolean" },
+            { field: "clone", type: "boolean" }
+          ]
+        }
+      ]
+    },
+    {
+      label: "Advanced",
+      description: "State machines, actions, and storage.",
+      collapsible: true,
+      collapsed: true,
+      fields: [
+        { field: "datasource", type: "text", helpText: 'Target datasource ID (default: "default")' }
+      ]
+    }
+  ]
+});
+
+// src/data/field.form.ts
+var fieldForm = defineForm({
+  schemaId: "field",
+  type: "simple",
+  sections: [
+    {
+      label: "Basics",
+      description: "Core field identity and constraints.",
+      columns: 2,
+      fields: [
+        { field: "name", required: true, immutable: true, colSpan: 1, helpText: "Unique identifier (snake_case, immutable after creation)" },
+        { field: "label", required: true, colSpan: 1, helpText: "Display name for users" },
+        { field: "type", required: true, colSpan: 1, helpText: "Data type of this field" },
+        { field: "group", colSpan: 1, helpText: "Group name for form layout" },
+        { field: "description", widget: "textarea", colSpan: 2, helpText: "Help text shown to users" },
+        { field: "required", colSpan: 1, helpText: "User must provide a value" },
+        { field: "unique", colSpan: 1, helpText: "No two records can have the same value" },
+        { field: "multiple", colSpan: 1, helpText: "Allow multiple values (for select/lookup)" }
+      ]
+    },
+    {
+      label: "Configuration",
+      description: "Field-type specific settings (visible blocks depend on the chosen type).",
+      fields: [
+        { field: "defaultValue", helpText: "Default value for new records" },
+        // Text field options
+        { field: "minLength", visibleOn: "data.type == 'text' || data.type == 'textarea' || data.type == 'email'", helpText: "Minimum character length" },
+        { field: "maxLength", visibleOn: "data.type == 'text' || data.type == 'textarea' || data.type == 'email'", helpText: "Maximum character length" },
+        // Number field options
+        { field: "min", visibleOn: "data.type == 'number' || data.type == 'currency'", helpText: "Minimum value" },
+        { field: "max", visibleOn: "data.type == 'number' || data.type == 'currency'", helpText: "Maximum value" },
+        { field: "precision", visibleOn: "data.type == 'currency' || data.type == 'number'", helpText: "Decimal places (e.g., 2 for $10.50)" },
+        { field: "scale", visibleOn: "data.type == 'number'", helpText: "Number of decimal digits" },
+        // Select field options
+        { field: "options", type: "repeater", visibleOn: "data.type == 'select' || data.type == 'multiselect'", helpText: "Available options (label/value pairs)" },
+        // Reference field options
+        { field: "reference", widget: "ref:object", visibleOn: "data.type == 'lookup' || data.type == 'master_detail'", helpText: "Referenced object name" },
+        { field: "referenceFilters", widget: "string-tags", visibleOn: "data.type == 'lookup' || data.type == 'master_detail'", helpText: 'Filter expressions (e.g., "active = true")' },
+        { field: "deleteBehavior", visibleOn: "data.type == 'lookup' || data.type == 'master_detail'", helpText: "What happens when referenced record is deleted" }
+      ]
+    },
+    {
+      label: "Formula & Computed",
+      description: "Calculated values and roll-up summaries.",
+      collapsible: true,
+      collapsed: true,
+      fields: [
+        { field: "expression", widget: "textarea", helpText: "CEL expression to calculate this field (makes it read-only)" },
+        { field: "summaryOperations", type: "composite", helpText: "Roll-up summary configuration (for parent-child relationships)" },
+        { field: "cached", type: "composite", helpText: "Caching configuration for computed fields" }
+      ]
+    },
+    {
+      label: "Advanced",
+      description: "Database, UI, audit, and security settings.",
+      collapsible: true,
+      collapsed: true,
+      columns: 2,
+      fields: [
+        // Database & Performance
+        { field: "columnName", colSpan: 2, helpText: "Physical column name in database (defaults to field name)" },
+        { field: "index", colSpan: 1, helpText: "Create database index for faster queries" },
+        { field: "externalId", colSpan: 1, helpText: "Mark as external ID for upsert operations" },
+        // UI & Visibility
+        { field: "readonly", colSpan: 1, helpText: "Field is read-only in forms" },
+        { field: "hidden", colSpan: 1, helpText: "Hide field from default UI views" },
+        { field: "searchable", colSpan: 1, helpText: "Include in global search results" },
+        { field: "sortable", colSpan: 1, helpText: "Allow sorting lists by this field" },
+        // Audit & History
+        { field: "auditTrail", colSpan: 1, helpText: "Track detailed changes with user and timestamp" },
+        { field: "trackFeedHistory", colSpan: 1, helpText: "Show changes in activity feed" },
+        // Security & Compliance
+        { field: "encryptionConfig", type: "composite", colSpan: 2, helpText: "Field-level encryption (GDPR/HIPAA/PCI-DSS)" },
+        { field: "maskingRule", type: "composite", colSpan: 2, helpText: "Data masking rules for PII protection" }
+      ]
+    }
+  ]
+});
+
+// src/data/hook.form.ts
+var hookForm = defineForm({
+  schemaId: "hook",
+  type: "simple",
+  sections: [
+    {
+      label: "Identity",
+      description: "What this hook is and when it fires.",
+      columns: 2,
+      fields: [
+        { field: "name", type: "text", required: true, immutable: true, colSpan: 1, helpText: "snake_case identifier (immutable after creation)" },
+        { field: "label", type: "text", colSpan: 1 },
+        { field: "description", type: "textarea", colSpan: 2 },
+        { field: "object", type: "text", required: true, colSpan: 1, helpText: 'Target object name (or "*" for global)' },
+        { field: "events", type: "tags", required: true, colSpan: 1, helpText: "Lifecycle events (e.g. beforeInsert, afterUpdate)" },
+        { field: "priority", type: "number", colSpan: 1, helpText: "Lower numbers run first" }
+      ]
+    },
+    {
+      label: "Body",
+      description: "Inline expression or sandboxed JavaScript executed when the hook fires.",
+      fields: [
+        {
+          field: "body",
+          type: "composite",
+          helpText: "Either an L1 expression or an L2 sandboxed JS body",
+          fields: [
+            { field: "language", type: "select", required: true, helpText: "expression = pure formula; js = sandboxed JavaScript", options: [
+              { label: "Expression (L1)", value: "expression" },
+              { label: "JavaScript (L2 sandboxed)", value: "js" }
+            ] },
+            { field: "source", type: "code", language: "javascript", required: true, helpText: "Function body source \u2014 no top-level imports" },
+            { field: "capabilities", type: "tags", helpText: "Allowed ctx APIs (api.read, api.write, crypto.uuid, log, \u2026)" },
+            { field: "timeoutMs", type: "number", helpText: "Per-invocation timeout (ms)" }
+          ]
+        }
+      ]
+    },
+    {
+      label: "Legacy handler",
+      description: "Function name reference \u2014 deprecated in favour of body.",
+      collapsible: true,
+      collapsed: true,
+      fields: [
+        { field: "handler", type: "text", helpText: "Handler function name (deprecated \u2014 prefer `body`)" }
+      ]
+    },
+    {
+      label: "Execution",
+      collapsible: true,
+      collapsed: true,
+      columns: 2,
+      fields: [
+        { field: "async", type: "boolean", colSpan: 1, helpText: "Run in background, do not block the transaction" },
+        { field: "onError", type: "select", colSpan: 1, options: [
+          { label: "Abort", value: "abort" },
+          { label: "Log", value: "log" }
+        ] },
+        { field: "condition", type: "code", language: "javascript", colSpan: 2, helpText: "Optional formula \u2014 skip the hook when this evaluates to false" }
+      ]
+    }
+  ]
+});
 var ReferenceResolutionSchema = lazySchema(() => zod.z.object({
   /** The field name on the source object (e.g., 'account_id') */
   field: zod.z.string().describe("Source field name containing the reference value"),
@@ -5155,8 +5434,11 @@ exports.WindowFunction = WindowFunction;
 exports.WindowFunctionNodeSchema = WindowFunctionNodeSchema;
 exports.WindowSpecSchema = WindowSpecSchema;
 exports.defineDataset = defineDataset;
+exports.fieldForm = fieldForm;
+exports.hookForm = hookForm;
 exports.isDateMacroToken = isDateMacroToken;
 exports.isFilterAST = isFilterAST;
+exports.objectForm = objectForm;
 exports.parseDateMacroParam = parseDateMacroParam;
 exports.parseFilterAST = parseFilterAST;
 exports.resolveCrudAffordances = resolveCrudAffordances;