@stonecrop/schema 0.13.14 → 0.15.0

package/dist/schema.d.ts

@@ -9,11 +9,12 @@ import { z } from 'zod';
  */
 export declare const ActionDefinition: z.ZodObject<{
     label: z.ZodString;
-    handler: z.ZodString;
     requiredFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
     allowedStates: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    confirm: z.ZodOptional<z.ZodBoolean>;
-    args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    nextState: z.ZodOptional<z.ZodString>;
+    stateless: z.ZodOptional<z.ZodBoolean>;
+    selfTransition: z.ZodOptional<z.ZodBoolean>;
+    clientHandler: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 
 /**
@@ -32,20 +33,6 @@ export declare type ActionDefinition = z.infer<typeof ActionDefinition>;
  */
 export declare function buildScalarMap(customScalars?: Record<string, Partial<FieldTemplate>>): Record<string, FieldTemplate>;
 
-/**
- * The complete list of field types built into Stonecrop.
- * User apps can use any string as a fieldtype; this const is the exhaustive set of types
- * that Stonecrop provides default components for.
- * @public
- */
-export declare const BUILTIN_FIELD_TYPES: readonly ["Data", "Text", "Int", "Float", "Decimal", "Check", "Date", "Time", "Datetime", "Duration", "DateRange", "JSON", "Code", "Link", "Attach", "Currency", "Quantity", "Select", "PrimaryKey", "Fieldset", "Display"];
-
-/**
- * Union of all builtin fieldtype string literals.
- * @public
- */
-export declare type BuiltinFieldType = (typeof BUILTIN_FIELD_TYPES)[number];
-
 /**
  * Converts camelCase to Title Case label
  * @param camelCase - Camel case string
@@ -72,6 +59,22 @@ export declare function camelToLabel(camelCase: string): string;
  */
 export declare function camelToSnake(camelCase: string): string;
 
+/**
+ * Every component Stonecrop ships with that can render a value field, sorted by name.
+ *
+ * The union of the two maps above is the definition, not a copy of it: a shipped component either
+ * categorises a value ({@link COMPONENT_CATEGORY}) or is one of the link containers that has no
+ * value of its own ({@link COMPONENT_LINK_EXPANSION}'s `AForm`/`ATable`). `AFieldset` is absent by
+ * the same rule — it is a `kind: 'fieldset'` container, so it is never a value field's component.
+ *
+ * `component` is an **open** axis: any string is valid, and naming a custom component is how an app
+ * renders a field Stonecrop ships no widget for. This list is therefore the set to *suggest* to an
+ * author, and to check first-party data against — never a set to validate arbitrary input against.
+ *
+ * @public
+ */
+export declare const CANONICAL_COMPONENTS: readonly string[];
+
 /**
  * Cardinality for relationship links.
  * @public
@@ -131,11 +134,19 @@ export declare interface ColumnSchema {
     /** Unique identifier for the field within its doctype. Maps to `name` on `TableColumn`. */
     fieldname: string;
     /**
-     * Semantic field type (e.g. `'Data'`, `'Int'`, `'Date'`, `'Check'`). Fields without a
-     * `fieldtype` are treated as non-scalar (nested table or fieldset) and excluded by
-     * `schemaToColumns`.
+     * Rendering component (e.g. `'ATextInput'`, `'ANumericInput'`, `'ADate'`). Default cell
+     * formatting and filter widgets derive from its {@link ComponentCategory}.
+     *
+     * Optional here, unlike `ValueField.component`: absence is what marks an entry as non-scalar
+     * (a nested table or fieldset), which `schemaToColumns` excludes — it has no column equivalent.
+     */
+    component?: string;
+    /**
+     * Target doctype slug — marks this column as a link. When set and no `cellComponent` is given,
+     * `schemaToColumns` copies it to `TableColumn.linkDoctype`, which ACell uses to resolve a bare
+     * id to display text.
      */
-    fieldtype?: string;
+    doctype?: string;
     /**
      * Human-readable column header. When absent, ATable assigns labels alphabetically
      * (A, B, C, …).
@@ -146,7 +157,7 @@ export declare interface ColumnSchema {
     /**
      * Horizontal text alignment for the column cell and header.
      *
-     * @defaultValue 'left'
+     * @defaultValue 'center'
      */
     align?: 'left' | 'right' | 'center' | 'start' | 'end';
     /**
@@ -186,9 +197,10 @@ export declare interface ColumnSchema {
      */
     filterable?: boolean;
     /**
-     * The type of filter control to render. When absent, a default is derived from `fieldtype`
-     * (`Check` → `checkbox`, `Date` → `date`, `Datetime` → `dateRange`, `Select` → `select`,
-     * numeric types → `number`, everything else → `text`).
+     * The type of filter control to render. When absent, a default is derived from the
+     * `component`'s {@link ComponentCategory} (`boolean` → `checkbox`, `date` → `date`,
+     * `datetime` → `dateRange`, `select` → `select`, `number` → `number`, everything else
+     * — including an unknown component — → `text`).
      */
     filterType?: 'text' | 'select' | 'number' | 'date' | 'dateRange' | 'checkbox' | 'component';
     /**
@@ -257,6 +269,47 @@ export declare interface ColumnSchema {
     colspan?: number;
 }
 
+/**
+ * Canonical component → semantic category. Only the components Stonecrop ships with appear here;
+ * custom/unknown component names have no category and consumers fall back to their default.
+ * @public
+ */
+export declare const COMPONENT_CATEGORY: Record<string, ComponentCategory>;
+
+/**
+ * Canonical link component → expansion. Only components Stonecrop ships with appear here; an
+ * unmapped (custom) component has none, and callers treat that as `expand` — the behaviour that
+ * predates this map, so a custom component can never silently collapse a link to a picker.
+ * @public
+ */
+export declare const COMPONENT_LINK_EXPANSION: Record<string, LinkExpansion>;
+
+/**
+ * Semantic category for a rendering component.
+ *
+ * `component` is the primary field axis, so the runtime consumers that need to know what a field
+ * *means* (atable cell formatting / filter widgets, record-default init) derive it from here. This
+ * is the single source of "what kind of value does this component render", keyed by the canonical
+ * registered component names — each consumer maps the category to its own concern (filter widget,
+ * default value, …).
+ *
+ * @public
+ */
+export declare type ComponentCategory = 'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'select' | 'code' | 'link' | 'attach';
+
+/**
+ * Resolve a component's semantic category, or `undefined` for an unknown (custom) component —
+ * callers treat that as "no opinion" and use their own default.
+ * @public
+ */
+export declare function componentCategory(component?: string): ComponentCategory | undefined;
+
+/**
+ * Resolve a component's link expansion, or `undefined` for an absent/unmapped component.
+ * @public
+ */
+export declare function componentLinkExpansion(component?: string): LinkExpansion | undefined;
+
 /**
  * Output of GraphQL schema conversion — one per entity type.
  *
@@ -293,7 +346,7 @@ export declare interface ConvertedGraphQLDoctype extends Omit<DoctypeMeta, 'fiel
  * // With PostGraphile custom scalars
  * const doctypes = convertGraphQLSchema(introspection, {
  *   customScalars: {
- *     BigFloat: { component: 'ADecimalInput', fieldtype: 'Decimal' }
+ *     BigFloat: { component: 'ANumericInput' }
  *   }
  * })
  * ```
@@ -459,11 +512,35 @@ export declare const DoctypeMeta: z.ZodObject<{
         states: z.ZodOptional<z.ZodArray<z.ZodString>>;
         actions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
             label: z.ZodString;
-            handler: z.ZodString;
             requiredFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
             allowedStates: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            confirm: z.ZodOptional<z.ZodBoolean>;
-            args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            nextState: z.ZodOptional<z.ZodString>;
+            stateless: z.ZodOptional<z.ZodBoolean>;
+            selfTransition: z.ZodOptional<z.ZodBoolean>;
+            clientHandler: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        triggers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            label: z.ZodOptional<z.ZodString>;
+            on: z.ZodArray<z.ZodString>;
+            clientHandler: z.ZodString;
+        }, z.core.$strip>>>;
+        layout: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            position: z.ZodOptional<z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strip>>;
+            targetPosition: z.ZodOptional<z.ZodEnum<{
+                left: "left";
+                right: "right";
+                top: "top";
+                bottom: "bottom";
+            }>>;
+            sourcePosition: z.ZodOptional<z.ZodEnum<{
+                left: "left";
+                right: "right";
+                top: "top";
+                bottom: "bottom";
+            }>>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
     inherits: z.ZodOptional<z.ZodString>;
@@ -513,15 +590,18 @@ export declare type FetchStrategy = z.infer<typeof FetchStrategy>;
 /**
  * Field options - flexible bag for type-specific configuration.
  *
- * Usage by fieldtype:
- * - Link/Doctype: target doctype slug as string ("customer", "sales-order-item")
+ * Usage:
  * - Select: array of choices (["Draft", "Submitted", "Cancelled"])
  * - Decimal: config object (\{ precision: 10, scale: 2 \})
  * - Code: config object (\{ language: "python" \})
  *
+ * Deliberately *not* a bare string: a string once meant "link target", which made the value's
+ * shape encode its meaning. That job belongs to `ValueField.doctype`, leaving this a plain
+ * choices-or-config bag.
+ *
  * @public
  */
-export declare const FieldOptions: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const FieldOptions: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
 
 /**
  * Field options type inferred from Zod schema
@@ -570,19 +650,16 @@ export declare const FieldsetFieldSchema: z.ZodObject<{
 }, z.core.$strip>;
 
 /**
- * Field template for TYPE_MAP entries.
- * Defines the default component and semantic field type for a field.
+ * The component a GraphQL scalar maps to.
+ *
+ * A one-property interface rather than a bare string so `customScalars` stays extensible: an
+ * override is a `Partial<FieldTemplate>`, and widening this later does not change that signature.
+ *
  * @public
  */
-export declare interface FieldTemplate {
-    /**
-     * The Vue component name to render this field (e.g., 'ATextInput', 'ADropdown')
-     */
+declare interface FieldTemplate {
+    /** The Vue component name to render fields of this scalar type (e.g. `'ATextInput'`). */
     component: string;
-    /**
-     * The semantic field type (e.g., 'Data', 'Int', 'Select')
-     */
-    fieldtype: BuiltinFieldType;
 }
 
 /**
@@ -600,15 +677,6 @@ export declare const FieldValidation: z.ZodObject<{
  */
 export declare type FieldValidation = z.infer<typeof FieldValidation>;
 
-/**
- * Get the default component for a builtin field type.
- * For an open-string fieldtype that may be custom, use {@link resolveComponent} instead.
- * @param fieldtype - A builtin field type
- * @returns The default component name
- * @public
- */
-export declare function getDefaultComponent(fieldtype: BuiltinFieldType): string;
-
 /**
  * Options for fetching a single record
  * @public
@@ -666,9 +734,7 @@ export declare const GQL_SCALAR_MAP: Record<string, FieldTemplate>;
  *
  * @public
  */
-export declare interface GraphQLConversionFieldMeta extends Omit<ValueField, 'fieldtype'> {
-    /** Semantic field type - optional for link fields which don't have a fieldtype */
-    fieldtype?: string;
+export declare interface GraphQLConversionFieldMeta extends ValueField {
     /** Original GraphQL type name (for debugging/reference) */
     _graphqlType?: string;
     /** Marks fields that couldn't be automatically mapped */
@@ -702,22 +768,22 @@ export declare interface GraphQLConversionOptions {
      * ```typescript
      * {
      *   SalesOrder: {
-     *     totalAmount: { fieldtype: 'Currency', component: 'ACurrencyInput' }
+     *     totalAmount: { component: 'ANumericInput', align: 'right' }
      *   }
      * }
      * ```
      */
     typeOverrides?: Record<string, Record<string, Omit<Partial<ValueField>, 'kind'>>>;
     /**
-     * Map custom or non-standard GraphQL scalar types to Stonecrop field types.
+     * Map custom or non-standard GraphQL scalar types to the component that renders them.
      * Merged with the built-in scalar maps (GQL_SCALAR_MAP + WELL_KNOWN_SCALARS).
      * User-provided entries take highest precedence.
      *
      * @example
      * ```typescript
      * {
-     *   MyCustomMoney: { component: 'ACurrencyInput', fieldtype: 'Currency' },
-     *   PostGISPoint: { component: 'ATextInput', fieldtype: 'Data' }
+     *   MyCustomMoney: { component: 'ANumericInput' },
+     *   PostGISPoint: { component: 'ATextInput' }
      * }
      * ```
      */
@@ -804,10 +870,19 @@ export declare const INTERNAL_SCALARS: Set<string>;
 export declare type IntrospectionSource = IntrospectionQuery | string;
 
 /**
- * Returns `true` when `fieldtype` is one of the builtin types Stonecrop ships with.
+ * Whether a workflow action may run from `currentState`.
+ *
+ * Single source of truth for the "is this action available here" rule, shared by
+ * the frontend (`getAvailableTransitions`) and the server-side dispatch guard so
+ * the two can never disagree. Empty or absent `allowedStates` means the action is
+ * available in ALL states — a plain `allowedStates.includes(currentState)` would
+ * wrongly block such actions everywhere.
+ *
  * @public
  */
-export declare function isBuiltinFieldType(fieldtype: string): fieldtype is BuiltinFieldType;
+export declare function isActionAllowedInState(action: {
+    allowedStates?: string[] | null;
+}, currentState: string): boolean;
 
 /**
  * Lazy fetch strategy - data is fetched on demand in a separate query.
@@ -856,6 +931,49 @@ export declare const LinkDeclaration: z.ZodObject<{
  */
 export declare type LinkDeclaration = z.infer<typeof LinkDeclaration>;
 
+/**
+ * Whether a link component expands its target doctype, or renders the link inline.
+ *
+ * This is the *only* axis the component decides. It deliberately does not choose between an
+ * embedded record and an embedded table: `cardinality` states whether the value is a scalar or
+ * an array, which is a fact about the data rather than a rendering preference, so a component
+ * must not be able to override it (an `AForm` over a `noneOrMany` link would be handed an array
+ * it cannot render). Component names encode both axes — `AFormLink`/`ATableLink` are the inline
+ * pair, `AForm`/`ATable` the expanding pair — but only the inline/expand half is authoritative.
+ *
+ * @public
+ */
+export declare type LinkExpansion = 'inline' | 'expand';
+
+/**
+ * How a link field renders.
+ *
+ * - `inline` — a scalar id-picker; the target is *not* expanded (the field keeps its own value
+ *   and carries a `doctype` prop for async display-text resolution and navigation).
+ * - `record` — the target doctype is resolved and embedded as a nested form.
+ * - `table` — the target doctype is resolved and embedded as a child table.
+ *
+ * @public
+ */
+export declare type LinkRenderMode = 'inline' | 'record' | 'table';
+
+/**
+ * Recursively injects the `kind` discriminant into a raw field object and, for fieldsets,
+ * into each of its nested `schema` children — mirroring exactly what Zod's `preprocess`
+ * does at every level of the discriminated union.
+ *
+ * Table `columns` are {@link ColumnSchema} entries, not `DoctypeField`s, so they are left
+ * untouched — the Zod table schema validates them with a plain passthrough and never injects
+ * `kind` there either.
+ *
+ * Needed because `Doctype.fromObject` constructs a Doctype without running Zod, yet the
+ * registry's `resolveFields` gates link and fieldset handling on `field.kind`. Without this,
+ * a JSON-authored link resolves to a flat scalar and a fieldset's children are dropped.
+ *
+ * @public
+ */
+export declare function normalizeFieldKind(field: unknown): unknown;
+
 /**
  * Parse and validate a doctype, throwing on failure
  * @param data - Data to parse
@@ -888,13 +1006,25 @@ export declare function parseField(data: unknown): DoctypeField;
 export declare function pascalToSnake(pascal: string): string;
 
 /**
- * Resolve the component name for any fieldtype string, falling back to `'ATextInput'`
- * for unknown custom types.
- * @param fieldtype - Any fieldtype string (builtin or custom)
- * @returns The component name to use for rendering
+ * Decide how a *declared* link (one with a `LinkDeclaration`) renders.
+ *
+ * Two independent axes: the **component** picks inline vs expand, and when expanding the
+ * **cardinality** picks record vs table (many → table). The declaration's component wins over the
+ * field's, matching the precedence the resolver already uses for the rendered component.
+ *
+ * This is the single definition of "does this link expand" — it is consumed by both the client
+ * resolver (which builds the nested schema) and the server column builder (which must still
+ * SELECT an `inline` link's FK column). Call it; never re-derive the rule at the call site, or
+ * the two will drift and the client will render a table for a column the server never selected.
+ *
+ * @param link - the link declaration (only `component` and `cardinality` are consulted)
+ * @param fieldComponent - the linked field's own `component`, used when the declaration names none
  * @public
  */
-export declare function resolveComponent(fieldtype: string): string;
+export declare function resolveLinkRenderMode(link: {
+    component?: string;
+    cardinality?: string;
+}, fieldComponent?: string): LinkRenderMode;
 
 /**
  * Serialized function type - a function serialized to a string.
@@ -929,14 +1059,6 @@ export declare function snakeToCamel(snakeCase: string): string;
  */
 export declare function snakeToLabel(snakeCase: string): string;
 
-/**
- * Stonecrop field type — any non-empty string is valid; Stonecrop provides default components
- * for the builtin types listed in {@link BUILTIN_FIELD_TYPES}. Custom fieldtypes are supported
- * by supplying an explicit `component` on the field definition.
- * @public
- */
-export declare const StonecropFieldType: z.ZodString;
-
 /**
  * Sync fetch strategy - data is fetched in the initial query.
  * @public
@@ -1060,11 +1182,29 @@ export declare function toPascalCase(tableName: string): string;
 export declare function toSlug(name: string): string;
 
 /**
- * Mapping from builtin fieldtypes to their default Vue component.
- * Components can be overridden in the field definition.
+ * Reactive field-validation trigger — advisory, client-side only.
+ *
+ * A Trigger is a docbuilder-authored validator: when any field in `on` is edited, its
+ * `clientHandler` runs (client-side, no rollback) and may flag a field inline to block save
+ * in the UI. It is deliberately a **sibling** to {@link (ActionDefinition:type)}, not a member of it —
+ * a reactive validator is not a user-invoked action, so it lives in the `triggers` map on
+ * {@link (WorkflowMeta:type)} and never appears to action readers (transition/command dropdowns, the FSM graph).
+ *
+ * The two bindings are independent: `on` is the fire-set (which fields' edits run it), while the
+ * `setError(field, msg)` call inside `clientHandler` chooses which field displays the error.
+ * @public
+ */
+export declare const TriggerDefinition: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    on: z.ZodArray<z.ZodString>;
+    clientHandler: z.ZodString;
+}, z.core.$strip>;
+
+/**
+ * Trigger definition type inferred from Zod schema
  * @public
  */
-export declare const TYPE_MAP: Record<BuiltinFieldType, FieldTemplate>;
+export declare type TriggerDefinition = z.infer<typeof TriggerDefinition>;
 
 /**
  * Validate a doctype definition
@@ -1106,7 +1246,8 @@ export declare interface ValidationResult {
 
 /**
  * A field that holds a scalar value, a link to another record, or a select choice.
- * The most common kind of field. `fieldtype` determines the default component and behavior.
+ * The most common kind of field. `component` determines how it renders; the attributes below
+ * carry everything else that is not a rendering concern.
  * @public
  */
 export declare interface ValueField {
@@ -1114,10 +1255,29 @@ export declare interface ValueField {
     kind: 'field';
     /** Unique identifier for this field within its doctype */
     fieldname: string;
-    /** Semantic field type — determines behavior and default rendering component */
-    fieldtype: string;
-    /** Vue component to render this field. Derived from `fieldtype` when absent. */
-    component?: string;
+    /**
+     * Vue component that renders this field — the primary (and only) rendering axis. Required:
+     * there is nothing left to derive it from, and a field without one has nothing to render it.
+     * Any string is valid; naming a custom component is how an app renders a field Stonecrop
+     * ships no widget for. See `CANONICAL_COMPONENTS` for the set Stonecrop provides.
+     */
+    component: string;
+    /** True for the field that identifies the record's primary-key column. */
+    primaryKey?: boolean;
+    /** True for a computed/display field with no backing DB column — excluded from SQL SELECT. */
+    computed?: boolean;
+    /** Editor language for code fields (e.g. `'json'`, `'typescript'`) — the only thing distinguishing
+     *  a JSON editor from a code editor, since both render with `ACodeEditor`. */
+    language?: string;
+    /**
+     * Target doctype slug. Presence is what makes a field a link.
+     *
+     * How it renders is decided by `component`, not by this: `AFormLink` renders an
+     * inline id-picker, while `AForm`/`ATable` expand the target (see `linkRenderMode`). Expansion
+     * metadata — backlink, fetch strategy, authoritative cardinality — lives in the doctype's
+     * `links` map, which is additive and never required for a plain foreign key.
+     */
+    doctype?: string;
     /** Human-readable label */
     label?: string;
     /** CSS width (e.g. `"40ch"`, `"200px"`) */
@@ -1128,9 +1288,14 @@ export declare interface ValueField {
     edit?: boolean;
     /** Input mask pattern or serialized function */
     mask?: string;
+    /** Serialized `(value) => string` function for display formatting — distinct from `mask` (input).
+     *  Spreads through `schemaToColumns` to `ColumnSchema.format`; deserialized at render time by
+     *  ATable's `getFormattedValue`. */
+    format?: string;
     /** Per-field interaction mode override */
     mode?: InteractionMode;
-    /** Type-specific options: Link target slug, Select choices, Decimal precision config, etc. */
+    /** Type-specific options: Select choices, Decimal precision config, etc. A link's target is not
+     *  here — it is `doctype`. */
     options?: FieldOptions;
     /** Whether the field is required */
     required?: boolean;
@@ -1144,6 +1309,14 @@ export declare interface ValueField {
     validation?: FieldValidation;
     /** Cardinality for Link fields — authoritative value on LinkDeclaration takes precedence */
     cardinality?: 'atMostOne' | 'one' | 'noneOrMany' | 'atLeastOne';
+    /**
+     * Provenance marker — stamped only by the GraphQL converter; absence means hand-authored.
+     * When present, the docbuilder freezes the field's identity set (`fieldname`, `primaryKey`,
+     * `required`, `options`, `cardinality`, `doctype`), since `fieldname` is the GraphQL/column
+     * binding and `doctype` is the FK's target. `component` is deliberately **not** frozen: it
+     * chooses the widget, which is an authoring decision the database has no opinion about.
+     */
+    source?: 'introspected';
 }
 
 /**
@@ -1153,8 +1326,11 @@ export declare interface ValueField {
 export declare const ValueFieldSchema: z.ZodObject<{
     kind: z.ZodLiteral<"field">;
     fieldname: z.ZodString;
-    fieldtype: z.ZodString;
-    component: z.ZodOptional<z.ZodString>;
+    component: z.ZodString;
+    primaryKey: z.ZodOptional<z.ZodBoolean>;
+    computed: z.ZodOptional<z.ZodBoolean>;
+    language: z.ZodOptional<z.ZodString>;
+    doctype: z.ZodOptional<z.ZodString>;
     label: z.ZodOptional<z.ZodString>;
     width: z.ZodOptional<z.ZodString>;
     align: z.ZodOptional<z.ZodEnum<{
@@ -1166,12 +1342,13 @@ export declare const ValueFieldSchema: z.ZodObject<{
     }>>;
     edit: z.ZodOptional<z.ZodBoolean>;
     mask: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
     mode: z.ZodOptional<z.ZodEnum<{
         edit: "edit";
         read: "read";
         display: "display";
     }>>;
-    options: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    options: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
     required: z.ZodOptional<z.ZodBoolean>;
     readOnly: z.ZodOptional<z.ZodBoolean>;
     hidden: z.ZodOptional<z.ZodBoolean>;
@@ -1186,6 +1363,7 @@ export declare const ValueFieldSchema: z.ZodObject<{
         noneOrMany: "noneOrMany";
         atLeastOne: "atLeastOne";
     }>>;
+    source: z.ZodOptional<z.ZodLiteral<"introspected">>;
 }, z.core.$strip>;
 
 /**
@@ -1200,6 +1378,40 @@ export declare const ValueFieldSchema: z.ZodObject<{
  */
 export declare const WELL_KNOWN_SCALARS: Record<string, FieldTemplate>;
 
+/**
+ * DocBuilder graph layout — node positions for the workflow-state graph, keyed by state name.
+ * Pure authoring view-state: persisted in the doctype JSON so an author's manual arrangement
+ * survives reloads, but — exactly like {@link (WorkflowMeta:type)}'s `triggers` — it is client-only
+ * and never mirrored into the runtime GraphQL SDL (see the WorkflowMeta type in the host SDLs, which
+ * expose only `states`/`actions`). The shape mirrors VueFlow's node fields; `position` is the node's
+ * canvas coordinate and `targetPosition`/`sourcePosition` are the handle sides.
+ * @public
+ */
+export declare const WorkflowLayout: z.ZodRecord<z.ZodString, z.ZodObject<{
+    position: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>>;
+    targetPosition: z.ZodOptional<z.ZodEnum<{
+        left: "left";
+        right: "right";
+        top: "top";
+        bottom: "bottom";
+    }>>;
+    sourcePosition: z.ZodOptional<z.ZodEnum<{
+        left: "left";
+        right: "right";
+        top: "top";
+        bottom: "bottom";
+    }>>;
+}, z.core.$strip>>;
+
+/**
+ * Workflow layout type inferred from Zod schema
+ * @public
+ */
+export declare type WorkflowLayout = z.infer<typeof WorkflowLayout>;
+
 /**
  * Workflow metadata - states and actions for a doctype
  * @public
@@ -1208,11 +1420,35 @@ export declare const WorkflowMeta: z.ZodObject<{
     states: z.ZodOptional<z.ZodArray<z.ZodString>>;
     actions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         label: z.ZodString;
-        handler: z.ZodString;
         requiredFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
         allowedStates: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        confirm: z.ZodOptional<z.ZodBoolean>;
-        args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        nextState: z.ZodOptional<z.ZodString>;
+        stateless: z.ZodOptional<z.ZodBoolean>;
+        selfTransition: z.ZodOptional<z.ZodBoolean>;
+        clientHandler: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    triggers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        label: z.ZodOptional<z.ZodString>;
+        on: z.ZodArray<z.ZodString>;
+        clientHandler: z.ZodString;
+    }, z.core.$strip>>>;
+    layout: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        position: z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>>;
+        targetPosition: z.ZodOptional<z.ZodEnum<{
+            left: "left";
+            right: "right";
+            top: "top";
+            bottom: "bottom";
+        }>>;
+        sourcePosition: z.ZodOptional<z.ZodEnum<{
+            left: "left";
+            right: "right";
+            top: "top";
+            bottom: "bottom";
+        }>>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;