@formspec/core 0.1.0-alpha.11 → 0.1.0-alpha.12

package/dist/extensions/index.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Extension API for registering custom types, constraints, annotations,
+ * and vocabulary keywords with FormSpec.
+ *
+ * Extensions allow third-party packages (e.g., "Decimal", "DateOnly") to
+ * plug into the FormSpec pipeline. The types and factory functions defined
+ * here are consumed by the FormSpec build pipeline.
+ *
+ * @packageDocumentation
+ */
+import type { JsonValue, TypeNode } from "../types/ir.js";
+/**
+ * Registration for a custom type that maps to a JSON Schema representation.
+ *
+ * Custom types are referenced via {@link CustomTypeNode} in the IR and
+ * resolved to JSON Schema via `toJsonSchema` during generation.
+ */
+export interface CustomTypeRegistration {
+    /** The type name, unique within the extension. */
+    readonly typeName: string;
+    /**
+     * Converts the custom type's payload into a JSON Schema fragment.
+     *
+     * @param payload - The opaque JSON payload from the {@link CustomTypeNode}.
+     * @param vendorPrefix - The vendor prefix for extension keywords (e.g., "x-stripe").
+     * @returns A JSON Schema fragment representing this type.
+     */
+    readonly toJsonSchema: (payload: JsonValue, vendorPrefix: string) => Record<string, unknown>;
+}
+/**
+ * Registration for a custom constraint that maps to JSON Schema keywords.
+ *
+ * Custom constraints are referenced via {@link CustomConstraintNode} in the IR.
+ */
+export interface CustomConstraintRegistration {
+    /** The constraint name, unique within the extension. */
+    readonly constraintName: string;
+    /**
+     * How this constraint composes with other constraints of the same kind.
+     * - "intersect": combine with logical AND (both must hold)
+     * - "override": last writer wins
+     */
+    readonly compositionRule: "intersect" | "override";
+    /**
+     * TypeNode kinds this constraint is applicable to, or `null` for any type.
+     * Used by the validator to emit TYPE_MISMATCH diagnostics.
+     */
+    readonly applicableTypes: readonly TypeNode["kind"][] | null;
+    /**
+     * Converts the custom constraint's payload into JSON Schema keywords.
+     *
+     * @param payload - The opaque JSON payload from the {@link CustomConstraintNode}.
+     * @param vendorPrefix - The vendor prefix for extension keywords.
+     * @returns A JSON Schema fragment with the constraint keywords.
+     */
+    readonly toJsonSchema: (payload: JsonValue, vendorPrefix: string) => Record<string, unknown>;
+}
+/**
+ * Registration for a custom annotation that may produce JSON Schema keywords.
+ *
+ * Custom annotations are referenced via {@link CustomAnnotationNode} in the IR.
+ * They describe or present a field but do not affect which values are valid.
+ */
+export interface CustomAnnotationRegistration {
+    /** The annotation name, unique within the extension. */
+    readonly annotationName: string;
+    /**
+     * Optionally converts the annotation value into JSON Schema keywords.
+     * If omitted, the annotation has no JSON Schema representation (UI-only).
+     */
+    readonly toJsonSchema?: (value: JsonValue, vendorPrefix: string) => Record<string, unknown>;
+}
+/**
+ * Registration for a vocabulary keyword to include in a JSON Schema `$vocabulary` declaration.
+ */
+export interface VocabularyKeywordRegistration {
+    /** The keyword name (without vendor prefix). */
+    readonly keyword: string;
+    /** JSON Schema that describes the valid values for this keyword. */
+    readonly schema: JsonValue;
+}
+/**
+ * A complete extension definition bundling types, constraints, annotations,
+ * and vocabulary keywords.
+ *
+ * @example
+ * ```typescript
+ * const monetaryExtension = defineExtension({
+ *   extensionId: "x-stripe/monetary",
+ *   types: [
+ *     defineCustomType({
+ *       typeName: "Decimal",
+ *       toJsonSchema: (_payload, prefix) => ({
+ *         type: "string",
+ *         [`${prefix}-decimal`]: true,
+ *       }),
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export interface ExtensionDefinition {
+    /** Globally unique extension identifier, e.g., "x-stripe/monetary". */
+    readonly extensionId: string;
+    /** Custom type registrations provided by this extension. */
+    readonly types?: readonly CustomTypeRegistration[];
+    /** Custom constraint registrations provided by this extension. */
+    readonly constraints?: readonly CustomConstraintRegistration[];
+    /** Custom annotation registrations provided by this extension. */
+    readonly annotations?: readonly CustomAnnotationRegistration[];
+    /** Vocabulary keyword registrations provided by this extension. */
+    readonly vocabularyKeywords?: readonly VocabularyKeywordRegistration[];
+}
+/**
+ * Defines a complete extension. Currently an identity function that provides
+ * type-checking and IDE autocompletion for the definition shape.
+ *
+ * @param def - The extension definition.
+ * @returns The same definition, validated at the type level.
+ */
+export declare function defineExtension(def: ExtensionDefinition): ExtensionDefinition;
+/**
+ * Defines a custom type registration. Currently an identity function that
+ * provides type-checking and IDE autocompletion.
+ *
+ * @param reg - The custom type registration.
+ * @returns The same registration, validated at the type level.
+ */
+export declare function defineCustomType(reg: CustomTypeRegistration): CustomTypeRegistration;
+/**
+ * Defines a custom constraint registration. Currently an identity function
+ * that provides type-checking and IDE autocompletion.
+ *
+ * @param reg - The custom constraint registration.
+ * @returns The same registration, validated at the type level.
+ */
+export declare function defineConstraint(reg: CustomConstraintRegistration): CustomConstraintRegistration;
+/**
+ * Defines a custom annotation registration. Currently an identity function
+ * that provides type-checking and IDE autocompletion.
+ *
+ * @param reg - The custom annotation registration.
+ * @returns The same registration, validated at the type level.
+ */
+export declare function defineAnnotation(reg: CustomAnnotationRegistration): CustomAnnotationRegistration;
+//# sourceMappingURL=index.d.ts.map

package/dist/extensions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/extensions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAM1D;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9F;AAED;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C,wDAAwD;IACxD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,WAAW,GAAG,UAAU,CAAC;IACnD;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,CAAC;IAC7D;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9F;AAED;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B;IAC3C,wDAAwD;IACxD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7F;AAED;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;CAC5B;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACnD,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,4BAA4B,EAAE,CAAC;IAC/D,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,4BAA4B,EAAE,CAAC;IAC/D,mEAAmE;IACnE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,6BAA6B,EAAE,CAAC;CACxE;AAMD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,mBAAmB,GAAG,mBAAmB,CAE7E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,sBAAsB,GAAG,sBAAsB,CAEpF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,4BAA4B,GAAG,4BAA4B,CAEhG;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,4BAA4B,GAAG,4BAA4B,CAEhG"}

package/dist/index.cjs

@@ -20,9 +20,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  CONSTRAINT_TAG_DEFINITIONS: () => CONSTRAINT_TAG_DEFINITIONS,
-  FORMSPEC_DECORATOR_NAMES: () => FORMSPEC_DECORATOR_NAMES,
-  createInitialFieldState: () => createInitialFieldState
+  BUILTIN_CONSTRAINT_DEFINITIONS: () => BUILTIN_CONSTRAINT_DEFINITIONS,
+  IR_VERSION: () => IR_VERSION,
+  createInitialFieldState: () => createInitialFieldState,
+  defineAnnotation: () => defineAnnotation,
+  defineConstraint: () => defineConstraint,
+  defineCustomType: () => defineCustomType,
+  defineExtension: () => defineExtension
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -37,21 +41,8 @@ function createInitialFieldState(value) {
   };
 }
 
-// src/types/decorators.ts
-var FORMSPEC_DECORATOR_NAMES = [
-  "Field",
-  "Group",
-  "ShowWhen",
-  "EnumOptions",
-  "Minimum",
-  "Maximum",
-  "ExclusiveMinimum",
-  "ExclusiveMaximum",
-  "MinLength",
-  "MaxLength",
-  "Pattern"
-];
-var CONSTRAINT_TAG_DEFINITIONS = {
+// src/types/constraint-definitions.ts
+var BUILTIN_CONSTRAINT_DEFINITIONS = {
   Minimum: "number",
   Maximum: "number",
   ExclusiveMinimum: "number",
@@ -61,10 +52,31 @@ var CONSTRAINT_TAG_DEFINITIONS = {
   Pattern: "string",
   EnumOptions: "json"
 };
+
+// src/types/ir.ts
+var IR_VERSION = "0.1.0";
+
+// src/extensions/index.ts
+function defineExtension(def) {
+  return def;
+}
+function defineCustomType(reg) {
+  return reg;
+}
+function defineConstraint(reg) {
+  return reg;
+}
+function defineAnnotation(reg) {
+  return reg;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  CONSTRAINT_TAG_DEFINITIONS,
-  FORMSPEC_DECORATOR_NAMES,
-  createInitialFieldState
+  BUILTIN_CONSTRAINT_DEFINITIONS,
+  IR_VERSION,
+  createInitialFieldState,
+  defineAnnotation,
+  defineConstraint,
+  defineCustomType,
+  defineExtension
 });
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/types/field-state.ts","../src/types/decorators.ts"],"sourcesContent":["/**\n * `@formspec/core` - Core type definitions for FormSpec\n *\n * This package provides the foundational types used throughout the FormSpec ecosystem:\n * - Form element types (fields, groups, conditionals)\n * - Field and form state types\n * - Data source registry for dynamic enums\n *\n * @packageDocumentation\n */\n\n// Re-export all types\nexport type {\n  // Validity\n  Validity,\n\n  // Field state\n  FieldState,\n\n  // Form state\n  FormState,\n\n  // Data sources\n  DataSourceRegistry,\n  DataSourceOption,\n  FetchOptionsResponse,\n  DataSourceValueType,\n\n  // Elements\n  TextField,\n  NumberField,\n  BooleanField,\n  EnumOption,\n  EnumOptionValue,\n  StaticEnumField,\n  DynamicEnumField,\n  DynamicSchemaField,\n  ArrayField,\n  ObjectField,\n  AnyField,\n  Group,\n  Conditional,\n  FormElement,\n  FormSpec,\n\n  // Predicates\n  EqualsPredicate,\n  Predicate,\n\n  // Decorators\n  FormSpecDecoratorName,\n  ConstraintTagName,\n} from \"./types/index.js\";\n\n// Re-export functions\nexport {\n  createInitialFieldState,\n  FORMSPEC_DECORATOR_NAMES,\n  CONSTRAINT_TAG_DEFINITIONS,\n} from \"./types/index.js\";\n","import type { Validity } from \"./validity.js\";\n\n/**\n * Represents the runtime state of a single form field.\n *\n * @typeParam T - The value type of the field\n */\nexport interface FieldState<T> {\n  /** Current value of the field */\n  readonly value: T;\n\n  /** Whether the field has been modified by the user */\n  readonly dirty: boolean;\n\n  /** Whether the field has been focused and blurred */\n  readonly touched: boolean;\n\n  /** Current validity state */\n  readonly validity: Validity;\n\n  /** Validation error messages, if any */\n  readonly errors: readonly string[];\n}\n\n/**\n * Creates initial field state with default values.\n *\n * @typeParam T - The value type of the field\n * @param value - The initial value for the field\n * @returns Initial field state\n */\nexport function createInitialFieldState<T>(value: T): FieldState<T> {\n  return {\n    value,\n    dirty: false,\n    touched: false,\n    validity: \"unknown\",\n    errors: [],\n  };\n}\n","/**\n * Canonical set of FormSpec decorator names.\n *\n * This is the single source of truth for which decorators FormSpec recognizes.\n * Both `@formspec/eslint-plugin` and `@formspec/build` import from here.\n */\n\n/** Names of all built-in FormSpec decorators. */\nexport const FORMSPEC_DECORATOR_NAMES = [\n  \"Field\",\n  \"Group\",\n  \"ShowWhen\",\n  \"EnumOptions\",\n  \"Minimum\",\n  \"Maximum\",\n  \"ExclusiveMinimum\",\n  \"ExclusiveMaximum\",\n  \"MinLength\",\n  \"MaxLength\",\n  \"Pattern\",\n] as const;\n\n/** Type of a FormSpec decorator name. */\nexport type FormSpecDecoratorName = (typeof FORMSPEC_DECORATOR_NAMES)[number];\n\n/**\n * Constraint decorator names that are valid as TSDoc tags, mapped to\n * their expected value type for parsing.\n *\n * Both `@formspec/build` (schema generation) and `@formspec/eslint-plugin`\n * (lint-time validation) import this to determine which JSDoc tags to\n * recognize and how to parse their values.\n */\nexport const CONSTRAINT_TAG_DEFINITIONS = {\n  Minimum: \"number\",\n  Maximum: \"number\",\n  ExclusiveMinimum: \"number\",\n  ExclusiveMaximum: \"number\",\n  MinLength: \"number\",\n  MaxLength: \"number\",\n  Pattern: \"string\",\n  EnumOptions: \"json\",\n} as const;\n\n/** Type of a constraint tag name. */\nexport type ConstraintTagName = keyof typeof CONSTRAINT_TAG_DEFINITIONS;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;AC+BO,SAAS,wBAA2B,OAAyB;AAClE,SAAO;AAAA,IACL;AAAA,IACA,OAAO;AAAA,IACP,SAAS;AAAA,IACT,UAAU;AAAA,IACV,QAAQ,CAAC;AAAA,EACX;AACF;;;AC/BO,IAAM,2BAA2B;AAAA,EACtC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAaO,IAAM,6BAA6B;AAAA,EACxC,SAAS;AAAA,EACT,SAAS;AAAA,EACT,kBAAkB;AAAA,EAClB,kBAAkB;AAAA,EAClB,WAAW;AAAA,EACX,WAAW;AAAA,EACX,SAAS;AAAA,EACT,aAAa;AACf;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/types/field-state.ts","../src/types/constraint-definitions.ts","../src/types/ir.ts","../src/extensions/index.ts"],"sourcesContent":["/**\n * `@formspec/core` - Core type definitions for FormSpec\n *\n * This package provides the foundational types used throughout the FormSpec ecosystem:\n * - Form element types (fields, groups, conditionals)\n * - Field and form state types\n * - Data source registry for dynamic enums\n * - Canonical IR types (FormIR, FieldNode, TypeNode, ConstraintNode, AnnotationNode, etc.)\n *\n * @packageDocumentation\n */\n\n// Re-export all types\nexport type {\n  // Validity\n  Validity,\n\n  // Field state\n  FieldState,\n\n  // Form state\n  FormState,\n\n  // Data sources\n  DataSourceRegistry,\n  DataSourceOption,\n  FetchOptionsResponse,\n  DataSourceValueType,\n\n  // Elements\n  TextField,\n  NumberField,\n  BooleanField,\n  EnumOption,\n  EnumOptionValue,\n  StaticEnumField,\n  DynamicEnumField,\n  DynamicSchemaField,\n  ArrayField,\n  ObjectField,\n  AnyField,\n  Group,\n  Conditional,\n  FormElement,\n  FormSpec,\n\n  // Predicates\n  EqualsPredicate,\n  Predicate,\n\n  // Built-in constraints\n  BuiltinConstraintName,\n\n  // Canonical IR\n  JsonValue,\n  Provenance,\n  PathTarget,\n  TypeNode,\n  PrimitiveTypeNode,\n  EnumMember,\n  EnumTypeNode,\n  ArrayTypeNode,\n  ObjectProperty,\n  ObjectTypeNode,\n  UnionTypeNode,\n  ReferenceTypeNode,\n  DynamicTypeNode,\n  CustomTypeNode,\n  ConstraintNode,\n  NumericConstraintNode,\n  LengthConstraintNode,\n  PatternConstraintNode,\n  ArrayCardinalityConstraintNode,\n  EnumMemberConstraintNode,\n  CustomConstraintNode,\n  AnnotationNode,\n  DisplayNameAnnotationNode,\n  DescriptionAnnotationNode,\n  PlaceholderAnnotationNode,\n  DefaultValueAnnotationNode,\n  DeprecatedAnnotationNode,\n  FormatHintAnnotationNode,\n  CustomAnnotationNode,\n  FieldNode,\n  LayoutNode,\n  GroupLayoutNode,\n  ConditionalLayoutNode,\n  FormIRElement,\n  TypeDefinition,\n  FormIR,\n} from \"./types/index.js\";\n\n// Re-export functions and constants\nexport {\n  createInitialFieldState,\n  BUILTIN_CONSTRAINT_DEFINITIONS,\n  IR_VERSION,\n} from \"./types/index.js\";\n\n// Extension API\nexport type {\n  ExtensionDefinition,\n  CustomTypeRegistration,\n  CustomConstraintRegistration,\n  CustomAnnotationRegistration,\n  VocabularyKeywordRegistration,\n} from \"./extensions/index.js\";\n\nexport {\n  defineExtension,\n  defineCustomType,\n  defineConstraint,\n  defineAnnotation,\n} from \"./extensions/index.js\";\n","import type { Validity } from \"./validity.js\";\n\n/**\n * Represents the runtime state of a single form field.\n *\n * @typeParam T - The value type of the field\n */\nexport interface FieldState<T> {\n  /** Current value of the field */\n  readonly value: T;\n\n  /** Whether the field has been modified by the user */\n  readonly dirty: boolean;\n\n  /** Whether the field has been focused and blurred */\n  readonly touched: boolean;\n\n  /** Current validity state */\n  readonly validity: Validity;\n\n  /** Validation error messages, if any */\n  readonly errors: readonly string[];\n}\n\n/**\n * Creates initial field state with default values.\n *\n * @typeParam T - The value type of the field\n * @param value - The initial value for the field\n * @returns Initial field state\n */\nexport function createInitialFieldState<T>(value: T): FieldState<T> {\n  return {\n    value,\n    dirty: false,\n    touched: false,\n    validity: \"unknown\",\n    errors: [],\n  };\n}\n","/**\n * Built-in constraint definitions for FormSpec constraint validation.\n *\n * This is the single source of truth for which constraints FormSpec\n * recognizes. Both `@formspec/build` (schema generation)\n * and `@formspec/eslint-plugin` (lint-time validation) import from here.\n */\n\n/**\n * Built-in constraint names mapped to their expected value type for parsing.\n * Constraints are surface-agnostic — they manifest as both TSDoc tags\n * (e.g., `@Minimum 0`) and chain DSL options (e.g., `{ minimum: 0 }`).\n */\nexport const BUILTIN_CONSTRAINT_DEFINITIONS = {\n  Minimum: \"number\",\n  Maximum: \"number\",\n  ExclusiveMinimum: \"number\",\n  ExclusiveMaximum: \"number\",\n  MinLength: \"number\",\n  MaxLength: \"number\",\n  Pattern: \"string\",\n  EnumOptions: \"json\",\n} as const;\n\n/** Type of a built-in constraint name. */\nexport type BuiltinConstraintName = keyof typeof BUILTIN_CONSTRAINT_DEFINITIONS;\n","/**\n * Canonical Intermediate Representation (IR) types for FormSpec.\n *\n * The IR is the shared intermediate structure that both authoring surfaces\n * (chain DSL and TSDoc-annotated types) compile to. All downstream operations\n * — JSON Schema generation, UI Schema generation, constraint validation,\n * diagnostics — consume the IR exclusively.\n *\n * All types are plain, serializable objects (no live compiler references).\n *\n * @see {@link https://github.com/stripe/formspec-workspace/blob/main/scratch/design/001-canonical-ir.md}\n */\n\n// =============================================================================\n// IR VERSION\n// =============================================================================\n\n/**\n * The current IR format version. Centralized here so all canonicalizers\n * and consumers reference a single source of truth.\n */\nexport const IR_VERSION = \"0.1.0\" as const;\n\n// =============================================================================\n// UTILITY TYPES\n// =============================================================================\n\n/**\n * A JSON-serializable value. All IR nodes must be representable as JSON.\n */\nexport type JsonValue =\n  | null\n  | boolean\n  | number\n  | string\n  | readonly JsonValue[]\n  | { readonly [key: string]: JsonValue };\n\n// =============================================================================\n// PROVENANCE\n// =============================================================================\n\n/**\n * Describes the origin of an IR node.\n * Enables diagnostics that point to the source of a contradiction or error.\n */\nexport interface Provenance {\n  /** The authoring surface that produced this node. */\n  readonly surface: \"tsdoc\" | \"chain-dsl\" | \"extension\" | \"inferred\";\n  /** Absolute path to the source file. */\n  readonly file: string;\n  /** 1-based line number in the source file. */\n  readonly line: number;\n  /** 0-based column number in the source file. */\n  readonly column: number;\n  /** Length of the source span in characters (for IDE underline ranges). */\n  readonly length?: number;\n  /**\n   * The specific tag, call, or construct that produced this node.\n   * Examples: `@minimum`, `field.number({ min: 0 })`, `optional`\n   */\n  readonly tagName?: string;\n}\n\n// =============================================================================\n// PATH TARGET\n// =============================================================================\n\n/**\n * A path targeting a sub-field within a complex type.\n * Used by constraints and annotations to target nested properties.\n */\nexport interface PathTarget {\n  /**\n   * Sequence of property names forming a path from the annotated field's type\n   * to the target sub-field.\n   * e.g., `[\"value\"]` or `[\"address\", \"zip\"]`\n   */\n  readonly segments: readonly string[];\n}\n\n// =============================================================================\n// TYPE NODES\n// =============================================================================\n\n/**\n * Discriminated union of all type representations in the IR.\n */\nexport type TypeNode =\n  | PrimitiveTypeNode\n  | EnumTypeNode\n  | ArrayTypeNode\n  | ObjectTypeNode\n  | UnionTypeNode\n  | ReferenceTypeNode\n  | DynamicTypeNode\n  | CustomTypeNode;\n\n/**\n * Primitive types mapping directly to JSON Schema primitives.\n *\n * Note: integer is NOT a primitive kind — integer semantics are expressed\n * via a `multipleOf: 1` constraint on a number type.\n */\nexport interface PrimitiveTypeNode {\n  readonly kind: \"primitive\";\n  readonly primitiveKind: \"string\" | \"number\" | \"boolean\" | \"null\";\n}\n\n/** A member of a static enum type. */\nexport interface EnumMember {\n  /** The serialized value stored in data. */\n  readonly value: string | number;\n  /** Optional per-member display name. */\n  readonly displayName?: string;\n}\n\n/** Static enum type — members known at build time. */\nexport interface EnumTypeNode {\n  readonly kind: \"enum\";\n  readonly members: readonly EnumMember[];\n}\n\n/** Array type with a single items type. */\nexport interface ArrayTypeNode {\n  readonly kind: \"array\";\n  readonly items: TypeNode;\n}\n\n/** A named property within an object type. */\nexport interface ObjectProperty {\n  readonly name: string;\n  readonly type: TypeNode;\n  readonly optional: boolean;\n  /**\n   * Use-site constraints on this property.\n   * Distinct from constraints on the property's type — these are\n   * use-site constraints (e.g., `@minimum :amount 0` targets the\n   * `amount` property of a `MonetaryAmount` field).\n   */\n  readonly constraints: readonly ConstraintNode[];\n  /** Use-site annotations on this property. */\n  readonly annotations: readonly AnnotationNode[];\n  readonly provenance: Provenance;\n}\n\n/** Object type with named properties. */\nexport interface ObjectTypeNode {\n  readonly kind: \"object\";\n  /**\n   * Named properties of this object. Order is preserved from the source\n   * declaration for deterministic output.\n   */\n  readonly properties: readonly ObjectProperty[];\n  /**\n   * Whether additional properties beyond those listed are permitted.\n   * Defaults to false — object types in FormSpec are closed.\n   */\n  readonly additionalProperties: boolean;\n}\n\n/** Union type for non-enum unions. Nullable types are `T | null` using this. */\nexport interface UnionTypeNode {\n  readonly kind: \"union\";\n  readonly members: readonly TypeNode[];\n}\n\n/** Named type reference — preserved as references for `$defs`/`$ref` emission. */\nexport interface ReferenceTypeNode {\n  readonly kind: \"reference\";\n  /**\n   * The fully-qualified name of the referenced type.\n   * For TypeScript interfaces/type aliases: `\"<module>#<TypeName>\"`.\n   * For built-in types: the primitive kind string.\n   */\n  readonly name: string;\n  /**\n   * Type arguments if this is a generic instantiation.\n   * e.g., `Array<string>` → `{ name: \"Array\", typeArguments: [PrimitiveTypeNode(\"string\")] }`\n   */\n  readonly typeArguments: readonly TypeNode[];\n}\n\n/** Dynamic type — schema resolved at runtime from a named data source. */\nexport interface DynamicTypeNode {\n  readonly kind: \"dynamic\";\n  readonly dynamicKind: \"enum\" | \"schema\";\n  /** Key identifying the runtime data source or schema provider. */\n  readonly sourceKey: string;\n  /**\n   * For dynamic enums: field names whose current values are passed as\n   * parameters to the data source resolver.\n   */\n  readonly parameterFields: readonly string[];\n}\n\n/** Custom type registered by an extension. */\nexport interface CustomTypeNode {\n  readonly kind: \"custom\";\n  /**\n   * The extension-qualified type identifier.\n   * Format: `\"<vendor-prefix>/<extension-name>/<type-name>\"`\n   * e.g., `\"x-stripe/monetary/MonetaryAmount\"`\n   */\n  readonly typeId: string;\n  /**\n   * Opaque payload serialized by the extension that registered this type.\n   * Must be JSON-serializable.\n   */\n  readonly payload: JsonValue;\n}\n\n// =============================================================================\n// CONSTRAINT NODES\n// =============================================================================\n\n/**\n * Discriminated union of all constraint types.\n * Constraints are set-influencing: they narrow the set of valid values.\n */\nexport type ConstraintNode =\n  | NumericConstraintNode\n  | LengthConstraintNode\n  | PatternConstraintNode\n  | ArrayCardinalityConstraintNode\n  | EnumMemberConstraintNode\n  | CustomConstraintNode;\n\n/**\n * Numeric constraints: bounds and multipleOf.\n *\n * `minimum` and `maximum` are inclusive; `exclusiveMinimum` and\n * `exclusiveMaximum` are exclusive bounds (matching JSON Schema 2020-12\n * semantics).\n *\n * Type applicability: may only attach to fields with `PrimitiveTypeNode(\"number\")`\n * or a `ReferenceTypeNode` that resolves to one.\n */\nexport interface NumericConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind:\n    | \"minimum\"\n    | \"maximum\"\n    | \"exclusiveMinimum\"\n    | \"exclusiveMaximum\"\n    | \"multipleOf\";\n  readonly value: number;\n  /** If present, targets a nested sub-field rather than the field itself. */\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/**\n * String length and array item count constraints.\n *\n * `minLength`/`maxLength` apply to strings; `minItems`/`maxItems` apply to\n * arrays. They share the same node shape because the composition rules are\n * identical.\n *\n * Type applicability: `minLength`/`maxLength` require `PrimitiveTypeNode(\"string\")`;\n * `minItems`/`maxItems` require `ArrayTypeNode`.\n */\nexport interface LengthConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"minLength\" | \"maxLength\" | \"minItems\" | \"maxItems\";\n  readonly value: number;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/**\n * String pattern constraint (ECMA-262 regex without delimiters).\n *\n * Multiple `pattern` constraints on the same field compose via intersection:\n * all patterns must match simultaneously.\n *\n * Type applicability: requires `PrimitiveTypeNode(\"string\")`.\n */\nexport interface PatternConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"pattern\";\n  /** ECMA-262 regular expression, without delimiters. */\n  readonly pattern: string;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Array uniqueness constraint. */\nexport interface ArrayCardinalityConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"uniqueItems\";\n  readonly value: true;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Enum member subset constraint (refinement — only narrows). */\nexport interface EnumMemberConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"allowedMembers\";\n  readonly members: readonly (string | number)[];\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Extension-registered custom constraint. */\nexport interface CustomConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"custom\";\n  /** Extension-qualified ID: `\"<vendor-prefix>/<extension-name>/<constraint-name>\"` */\n  readonly constraintId: string;\n  /** JSON-serializable payload defined by the extension. */\n  readonly payload: JsonValue;\n  /** How this constraint composes with others of the same `constraintId`. */\n  readonly compositionRule: \"intersect\" | \"override\";\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n// =============================================================================\n// ANNOTATION NODES\n// =============================================================================\n\n/**\n * Discriminated union of all annotation types.\n * Annotations are value-influencing: they describe or present a field\n * but do not affect which values are valid.\n */\nexport type AnnotationNode =\n  | DisplayNameAnnotationNode\n  | DescriptionAnnotationNode\n  | PlaceholderAnnotationNode\n  | DefaultValueAnnotationNode\n  | DeprecatedAnnotationNode\n  | FormatHintAnnotationNode\n  | CustomAnnotationNode;\n\nexport interface DisplayNameAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"displayName\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\nexport interface DescriptionAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"description\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\nexport interface PlaceholderAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"placeholder\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\nexport interface DefaultValueAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"defaultValue\";\n  /** Must be JSON-serializable and type-compatible (verified during Validate phase). */\n  readonly value: JsonValue;\n  readonly provenance: Provenance;\n}\n\nexport interface DeprecatedAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"deprecated\";\n  /** Optional deprecation message. */\n  readonly message?: string;\n  readonly provenance: Provenance;\n}\n\n/** UI rendering hint — does not affect schema validation. */\nexport interface FormatHintAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"formatHint\";\n  /** Renderer-specific format identifier: \"textarea\", \"radio\", \"date\", \"color\", etc. */\n  readonly format: string;\n  readonly provenance: Provenance;\n}\n\n/** Extension-registered custom annotation. */\nexport interface CustomAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"custom\";\n  /** Extension-qualified ID: `\"<vendor-prefix>/<extension-name>/<annotation-name>\"` */\n  readonly annotationId: string;\n  readonly value: JsonValue;\n  readonly provenance: Provenance;\n}\n\n// =============================================================================\n// FIELD NODE\n// =============================================================================\n\n/** A single form field after canonicalization. */\nexport interface FieldNode {\n  readonly kind: \"field\";\n  /** The field's key in the data schema. */\n  readonly name: string;\n  /** The resolved type of this field. */\n  readonly type: TypeNode;\n  /** Whether this field is required in the data schema. */\n  readonly required: boolean;\n  /** Set-influencing constraints, after merging. */\n  readonly constraints: readonly ConstraintNode[];\n  /** Value-influencing annotations, after merging. */\n  readonly annotations: readonly AnnotationNode[];\n  /** Where this field was declared. */\n  readonly provenance: Provenance;\n  /**\n   * Debug only — ordered list of constraint/annotation nodes that participated\n   * in merging, including dominated ones.\n   */\n  readonly mergeHistory?: readonly {\n    readonly node: ConstraintNode | AnnotationNode;\n    readonly dominated: boolean;\n  }[];\n}\n\n// =============================================================================\n// LAYOUT NODES\n// =============================================================================\n\n/** Union of layout node types. */\nexport type LayoutNode = GroupLayoutNode | ConditionalLayoutNode;\n\n/** A visual grouping of form elements. */\nexport interface GroupLayoutNode {\n  readonly kind: \"group\";\n  readonly label: string;\n  /** Elements contained in this group — may be fields or nested groups. */\n  readonly elements: readonly FormIRElement[];\n  readonly provenance: Provenance;\n}\n\n/** Conditional visibility based on another field's value. */\nexport interface ConditionalLayoutNode {\n  readonly kind: \"conditional\";\n  /** The field whose value triggers visibility. */\n  readonly fieldName: string;\n  /** The value that makes the condition true (SHOW). */\n  readonly value: JsonValue;\n  /** Elements shown when the condition is met. */\n  readonly elements: readonly FormIRElement[];\n  readonly provenance: Provenance;\n}\n\n/** Union of all IR element types. */\nexport type FormIRElement = FieldNode | LayoutNode;\n\n// =============================================================================\n// TYPE REGISTRY\n// =============================================================================\n\n/** A named type definition stored in the type registry. */\nexport interface TypeDefinition {\n  /** The fully-qualified reference name (key in the registry). */\n  readonly name: string;\n  /** The resolved type node. */\n  readonly type: TypeNode;\n  /** Where this type was declared. */\n  readonly provenance: Provenance;\n}\n\n// =============================================================================\n// FORM IR (TOP-LEVEL)\n// =============================================================================\n\n/**\n * The complete Canonical Intermediate Representation for a form.\n *\n * Output of the Canonicalize phase; input to Validate, Generate (JSON Schema),\n * and Generate (UI Schema) phases.\n *\n * Serializable to JSON — no live compiler objects.\n */\nexport interface FormIR {\n  readonly kind: \"form-ir\";\n  /**\n   * Schema version for the IR format itself.\n   * Should equal `IR_VERSION`.\n   */\n  readonly irVersion: string;\n  /** Top-level elements of the form: fields and layout nodes. */\n  readonly elements: readonly FormIRElement[];\n  /**\n   * Registry of named types referenced by fields in this form.\n   * Keys are fully-qualified type names matching `ReferenceTypeNode.name`.\n   */\n  readonly typeRegistry: Readonly<Record<string, TypeDefinition>>;\n  /** Provenance of the form definition itself. */\n  readonly provenance: Provenance;\n}\n","/**\n * Extension API for registering custom types, constraints, annotations,\n * and vocabulary keywords with FormSpec.\n *\n * Extensions allow third-party packages (e.g., \"Decimal\", \"DateOnly\") to\n * plug into the FormSpec pipeline. The types and factory functions defined\n * here are consumed by the FormSpec build pipeline.\n *\n * @packageDocumentation\n */\n\nimport type { JsonValue, TypeNode } from \"../types/ir.js\";\n\n// =============================================================================\n// REGISTRATION TYPES\n// =============================================================================\n\n/**\n * Registration for a custom type that maps to a JSON Schema representation.\n *\n * Custom types are referenced via {@link CustomTypeNode} in the IR and\n * resolved to JSON Schema via `toJsonSchema` during generation.\n */\nexport interface CustomTypeRegistration {\n  /** The type name, unique within the extension. */\n  readonly typeName: string;\n  /**\n   * Converts the custom type's payload into a JSON Schema fragment.\n   *\n   * @param payload - The opaque JSON payload from the {@link CustomTypeNode}.\n   * @param vendorPrefix - The vendor prefix for extension keywords (e.g., \"x-stripe\").\n   * @returns A JSON Schema fragment representing this type.\n   */\n  readonly toJsonSchema: (payload: JsonValue, vendorPrefix: string) => Record<string, unknown>;\n}\n\n/**\n * Registration for a custom constraint that maps to JSON Schema keywords.\n *\n * Custom constraints are referenced via {@link CustomConstraintNode} in the IR.\n */\nexport interface CustomConstraintRegistration {\n  /** The constraint name, unique within the extension. */\n  readonly constraintName: string;\n  /**\n   * How this constraint composes with other constraints of the same kind.\n   * - \"intersect\": combine with logical AND (both must hold)\n   * - \"override\": last writer wins\n   */\n  readonly compositionRule: \"intersect\" | \"override\";\n  /**\n   * TypeNode kinds this constraint is applicable to, or `null` for any type.\n   * Used by the validator to emit TYPE_MISMATCH diagnostics.\n   */\n  readonly applicableTypes: readonly TypeNode[\"kind\"][] | null;\n  /**\n   * Converts the custom constraint's payload into JSON Schema keywords.\n   *\n   * @param payload - The opaque JSON payload from the {@link CustomConstraintNode}.\n   * @param vendorPrefix - The vendor prefix for extension keywords.\n   * @returns A JSON Schema fragment with the constraint keywords.\n   */\n  readonly toJsonSchema: (payload: JsonValue, vendorPrefix: string) => Record<string, unknown>;\n}\n\n/**\n * Registration for a custom annotation that may produce JSON Schema keywords.\n *\n * Custom annotations are referenced via {@link CustomAnnotationNode} in the IR.\n * They describe or present a field but do not affect which values are valid.\n */\nexport interface CustomAnnotationRegistration {\n  /** The annotation name, unique within the extension. */\n  readonly annotationName: string;\n  /**\n   * Optionally converts the annotation value into JSON Schema keywords.\n   * If omitted, the annotation has no JSON Schema representation (UI-only).\n   */\n  readonly toJsonSchema?: (value: JsonValue, vendorPrefix: string) => Record<string, unknown>;\n}\n\n/**\n * Registration for a vocabulary keyword to include in a JSON Schema `$vocabulary` declaration.\n */\nexport interface VocabularyKeywordRegistration {\n  /** The keyword name (without vendor prefix). */\n  readonly keyword: string;\n  /** JSON Schema that describes the valid values for this keyword. */\n  readonly schema: JsonValue;\n}\n\n// =============================================================================\n// EXTENSION DEFINITION\n// =============================================================================\n\n/**\n * A complete extension definition bundling types, constraints, annotations,\n * and vocabulary keywords.\n *\n * @example\n * ```typescript\n * const monetaryExtension = defineExtension({\n *   extensionId: \"x-stripe/monetary\",\n *   types: [\n *     defineCustomType({\n *       typeName: \"Decimal\",\n *       toJsonSchema: (_payload, prefix) => ({\n *         type: \"string\",\n *         [`${prefix}-decimal`]: true,\n *       }),\n *     }),\n *   ],\n * });\n * ```\n */\nexport interface ExtensionDefinition {\n  /** Globally unique extension identifier, e.g., \"x-stripe/monetary\". */\n  readonly extensionId: string;\n  /** Custom type registrations provided by this extension. */\n  readonly types?: readonly CustomTypeRegistration[];\n  /** Custom constraint registrations provided by this extension. */\n  readonly constraints?: readonly CustomConstraintRegistration[];\n  /** Custom annotation registrations provided by this extension. */\n  readonly annotations?: readonly CustomAnnotationRegistration[];\n  /** Vocabulary keyword registrations provided by this extension. */\n  readonly vocabularyKeywords?: readonly VocabularyKeywordRegistration[];\n}\n\n// =============================================================================\n// FACTORY FUNCTIONS\n// =============================================================================\n\n/**\n * Defines a complete extension. Currently an identity function that provides\n * type-checking and IDE autocompletion for the definition shape.\n *\n * @param def - The extension definition.\n * @returns The same definition, validated at the type level.\n */\nexport function defineExtension(def: ExtensionDefinition): ExtensionDefinition {\n  return def;\n}\n\n/**\n * Defines a custom type registration. Currently an identity function that\n * provides type-checking and IDE autocompletion.\n *\n * @param reg - The custom type registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineCustomType(reg: CustomTypeRegistration): CustomTypeRegistration {\n  return reg;\n}\n\n/**\n * Defines a custom constraint registration. Currently an identity function\n * that provides type-checking and IDE autocompletion.\n *\n * @param reg - The custom constraint registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineConstraint(reg: CustomConstraintRegistration): CustomConstraintRegistration {\n  return reg;\n}\n\n/**\n * Defines a custom annotation registration. Currently an identity function\n * that provides type-checking and IDE autocompletion.\n *\n * @param reg - The custom annotation registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineAnnotation(reg: CustomAnnotationRegistration): CustomAnnotationRegistration {\n  return reg;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;AC+BO,SAAS,wBAA2B,OAAyB;AAClE,SAAO;AAAA,IACL;AAAA,IACA,OAAO;AAAA,IACP,SAAS;AAAA,IACT,UAAU;AAAA,IACV,QAAQ,CAAC;AAAA,EACX;AACF;;;AC1BO,IAAM,iCAAiC;AAAA,EAC5C,SAAS;AAAA,EACT,SAAS;AAAA,EACT,kBAAkB;AAAA,EAClB,kBAAkB;AAAA,EAClB,WAAW;AAAA,EACX,WAAW;AAAA,EACX,SAAS;AAAA,EACT,aAAa;AACf;;;ACDO,IAAM,aAAa;;;ACsHnB,SAAS,gBAAgB,KAA+C;AAC7E,SAAO;AACT;AASO,SAAS,iBAAiB,KAAqD;AACpF,SAAO;AACT;AASO,SAAS,iBAAiB,KAAiE;AAChG,SAAO;AACT;AASO,SAAS,iBAAiB,KAAiE;AAChG,SAAO;AACT;","names":[]}

package/dist/index.d.ts

@@ -5,9 +5,12 @@
  * - Form element types (fields, groups, conditionals)
  * - Field and form state types
  * - Data source registry for dynamic enums
+ * - Canonical IR types (FormIR, FieldNode, TypeNode, ConstraintNode, AnnotationNode, etc.)
  *
  * @packageDocumentation
  */
-export type { Validity, FieldState, FormState, DataSourceRegistry, DataSourceOption, FetchOptionsResponse, DataSourceValueType, TextField, NumberField, BooleanField, EnumOption, EnumOptionValue, StaticEnumField, DynamicEnumField, DynamicSchemaField, ArrayField, ObjectField, AnyField, Group, Conditional, FormElement, FormSpec, EqualsPredicate, Predicate, FormSpecDecoratorName, ConstraintTagName, } from "./types/index.js";
-export { createInitialFieldState, FORMSPEC_DECORATOR_NAMES, CONSTRAINT_TAG_DEFINITIONS, } from "./types/index.js";
+export type { Validity, FieldState, FormState, DataSourceRegistry, DataSourceOption, FetchOptionsResponse, DataSourceValueType, TextField, NumberField, BooleanField, EnumOption, EnumOptionValue, StaticEnumField, DynamicEnumField, DynamicSchemaField, ArrayField, ObjectField, AnyField, Group, Conditional, FormElement, FormSpec, EqualsPredicate, Predicate, BuiltinConstraintName, JsonValue, Provenance, PathTarget, TypeNode, PrimitiveTypeNode, EnumMember, EnumTypeNode, ArrayTypeNode, ObjectProperty, ObjectTypeNode, UnionTypeNode, ReferenceTypeNode, DynamicTypeNode, CustomTypeNode, ConstraintNode, NumericConstraintNode, LengthConstraintNode, PatternConstraintNode, ArrayCardinalityConstraintNode, EnumMemberConstraintNode, CustomConstraintNode, AnnotationNode, DisplayNameAnnotationNode, DescriptionAnnotationNode, PlaceholderAnnotationNode, DefaultValueAnnotationNode, DeprecatedAnnotationNode, FormatHintAnnotationNode, CustomAnnotationNode, FieldNode, LayoutNode, GroupLayoutNode, ConditionalLayoutNode, FormIRElement, TypeDefinition, FormIR, } from "./types/index.js";
+export { createInitialFieldState, BUILTIN_CONSTRAINT_DEFINITIONS, IR_VERSION, } from "./types/index.js";
+export type { ExtensionDefinition, CustomTypeRegistration, CustomConstraintRegistration, CustomAnnotationRegistration, VocabularyKeywordRegistration, } from "./extensions/index.js";
+export { defineExtension, defineCustomType, defineConstraint, defineAnnotation, } from "./extensions/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,YAAY,EAEV,QAAQ,EAGR,UAAU,EAGV,SAAS,EAGT,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EAGnB,SAAS,EACT,WAAW,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,QAAQ,EACR,KAAK,EACL,WAAW,EACX,WAAW,EACX,QAAQ,EAGR,eAAe,EACf,SAAS,EAGT,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,YAAY,EAEV,QAAQ,EAGR,UAAU,EAGV,SAAS,EAGT,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EAGnB,SAAS,EACT,WAAW,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,QAAQ,EACR,KAAK,EACL,WAAW,EACX,WAAW,EACX,QAAQ,EAGR,eAAe,EACf,SAAS,EAGT,qBAAqB,EAGrB,SAAS,EACT,UAAU,EACV,UAAU,EACV,QAAQ,EACR,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,aAAa,EACb,cAAc,EACd,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,8BAA8B,EAC9B,wBAAwB,EACxB,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,wBAAwB,EACxB,oBAAoB,EACpB,SAAS,EACT,UAAU,EACV,eAAe,EACf,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,MAAM,GACP,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,uBAAuB,EACvB,8BAA8B,EAC9B,UAAU,GACX,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EACV,mBAAmB,EACnB,sBAAsB,EACtB,4BAA4B,EAC5B,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -9,21 +9,8 @@ function createInitialFieldState(value) {
   };
 }
 
-// src/types/decorators.ts
-var FORMSPEC_DECORATOR_NAMES = [
-  "Field",
-  "Group",
-  "ShowWhen",
-  "EnumOptions",
-  "Minimum",
-  "Maximum",
-  "ExclusiveMinimum",
-  "ExclusiveMaximum",
-  "MinLength",
-  "MaxLength",
-  "Pattern"
-];
-var CONSTRAINT_TAG_DEFINITIONS = {
+// src/types/constraint-definitions.ts
+var BUILTIN_CONSTRAINT_DEFINITIONS = {
   Minimum: "number",
   Maximum: "number",
   ExclusiveMinimum: "number",
@@ -33,9 +20,30 @@ var CONSTRAINT_TAG_DEFINITIONS = {
   Pattern: "string",
   EnumOptions: "json"
 };
+
+// src/types/ir.ts
+var IR_VERSION = "0.1.0";
+
+// src/extensions/index.ts
+function defineExtension(def) {
+  return def;
+}
+function defineCustomType(reg) {
+  return reg;
+}
+function defineConstraint(reg) {
+  return reg;
+}
+function defineAnnotation(reg) {
+  return reg;
+}
 export {
-  CONSTRAINT_TAG_DEFINITIONS,
-  FORMSPEC_DECORATOR_NAMES,
-  createInitialFieldState
+  BUILTIN_CONSTRAINT_DEFINITIONS,
+  IR_VERSION,
+  createInitialFieldState,
+  defineAnnotation,
+  defineConstraint,
+  defineCustomType,
+  defineExtension
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types/field-state.ts","../src/types/decorators.ts"],"sourcesContent":["import type { Validity } from \"./validity.js\";\n\n/**\n * Represents the runtime state of a single form field.\n *\n * @typeParam T - The value type of the field\n */\nexport interface FieldState<T> {\n  /** Current value of the field */\n  readonly value: T;\n\n  /** Whether the field has been modified by the user */\n  readonly dirty: boolean;\n\n  /** Whether the field has been focused and blurred */\n  readonly touched: boolean;\n\n  /** Current validity state */\n  readonly validity: Validity;\n\n  /** Validation error messages, if any */\n  readonly errors: readonly string[];\n}\n\n/**\n * Creates initial field state with default values.\n *\n * @typeParam T - The value type of the field\n * @param value - The initial value for the field\n * @returns Initial field state\n */\nexport function createInitialFieldState<T>(value: T): FieldState<T> {\n  return {\n    value,\n    dirty: false,\n    touched: false,\n    validity: \"unknown\",\n    errors: [],\n  };\n}\n","/**\n * Canonical set of FormSpec decorator names.\n *\n * This is the single source of truth for which decorators FormSpec recognizes.\n * Both `@formspec/eslint-plugin` and `@formspec/build` import from here.\n */\n\n/** Names of all built-in FormSpec decorators. */\nexport const FORMSPEC_DECORATOR_NAMES = [\n  \"Field\",\n  \"Group\",\n  \"ShowWhen\",\n  \"EnumOptions\",\n  \"Minimum\",\n  \"Maximum\",\n  \"ExclusiveMinimum\",\n  \"ExclusiveMaximum\",\n  \"MinLength\",\n  \"MaxLength\",\n  \"Pattern\",\n] as const;\n\n/** Type of a FormSpec decorator name. */\nexport type FormSpecDecoratorName = (typeof FORMSPEC_DECORATOR_NAMES)[number];\n\n/**\n * Constraint decorator names that are valid as TSDoc tags, mapped to\n * their expected value type for parsing.\n *\n * Both `@formspec/build` (schema generation) and `@formspec/eslint-plugin`\n * (lint-time validation) import this to determine which JSDoc tags to\n * recognize and how to parse their values.\n */\nexport const CONSTRAINT_TAG_DEFINITIONS = {\n  Minimum: \"number\",\n  Maximum: \"number\",\n  ExclusiveMinimum: \"number\",\n  ExclusiveMaximum: \"number\",\n  MinLength: \"number\",\n  MaxLength: \"number\",\n  Pattern: \"string\",\n  EnumOptions: \"json\",\n} as const;\n\n/** Type of a constraint tag name. */\nexport type ConstraintTagName = keyof typeof CONSTRAINT_TAG_DEFINITIONS;\n"],"mappings":";AA+BO,SAAS,wBAA2B,OAAyB;AAClE,SAAO;AAAA,IACL;AAAA,IACA,OAAO;AAAA,IACP,SAAS;AAAA,IACT,UAAU;AAAA,IACV,QAAQ,CAAC;AAAA,EACX;AACF;;;AC/BO,IAAM,2BAA2B;AAAA,EACtC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAaO,IAAM,6BAA6B;AAAA,EACxC,SAAS;AAAA,EACT,SAAS;AAAA,EACT,kBAAkB;AAAA,EAClB,kBAAkB;AAAA,EAClB,WAAW;AAAA,EACX,WAAW;AAAA,EACX,SAAS;AAAA,EACT,aAAa;AACf;","names":[]}
+{"version":3,"sources":["../src/types/field-state.ts","../src/types/constraint-definitions.ts","../src/types/ir.ts","../src/extensions/index.ts"],"sourcesContent":["import type { Validity } from \"./validity.js\";\n\n/**\n * Represents the runtime state of a single form field.\n *\n * @typeParam T - The value type of the field\n */\nexport interface FieldState<T> {\n  /** Current value of the field */\n  readonly value: T;\n\n  /** Whether the field has been modified by the user */\n  readonly dirty: boolean;\n\n  /** Whether the field has been focused and blurred */\n  readonly touched: boolean;\n\n  /** Current validity state */\n  readonly validity: Validity;\n\n  /** Validation error messages, if any */\n  readonly errors: readonly string[];\n}\n\n/**\n * Creates initial field state with default values.\n *\n * @typeParam T - The value type of the field\n * @param value - The initial value for the field\n * @returns Initial field state\n */\nexport function createInitialFieldState<T>(value: T): FieldState<T> {\n  return {\n    value,\n    dirty: false,\n    touched: false,\n    validity: \"unknown\",\n    errors: [],\n  };\n}\n","/**\n * Built-in constraint definitions for FormSpec constraint validation.\n *\n * This is the single source of truth for which constraints FormSpec\n * recognizes. Both `@formspec/build` (schema generation)\n * and `@formspec/eslint-plugin` (lint-time validation) import from here.\n */\n\n/**\n * Built-in constraint names mapped to their expected value type for parsing.\n * Constraints are surface-agnostic — they manifest as both TSDoc tags\n * (e.g., `@Minimum 0`) and chain DSL options (e.g., `{ minimum: 0 }`).\n */\nexport const BUILTIN_CONSTRAINT_DEFINITIONS = {\n  Minimum: \"number\",\n  Maximum: \"number\",\n  ExclusiveMinimum: \"number\",\n  ExclusiveMaximum: \"number\",\n  MinLength: \"number\",\n  MaxLength: \"number\",\n  Pattern: \"string\",\n  EnumOptions: \"json\",\n} as const;\n\n/** Type of a built-in constraint name. */\nexport type BuiltinConstraintName = keyof typeof BUILTIN_CONSTRAINT_DEFINITIONS;\n","/**\n * Canonical Intermediate Representation (IR) types for FormSpec.\n *\n * The IR is the shared intermediate structure that both authoring surfaces\n * (chain DSL and TSDoc-annotated types) compile to. All downstream operations\n * — JSON Schema generation, UI Schema generation, constraint validation,\n * diagnostics — consume the IR exclusively.\n *\n * All types are plain, serializable objects (no live compiler references).\n *\n * @see {@link https://github.com/stripe/formspec-workspace/blob/main/scratch/design/001-canonical-ir.md}\n */\n\n// =============================================================================\n// IR VERSION\n// =============================================================================\n\n/**\n * The current IR format version. Centralized here so all canonicalizers\n * and consumers reference a single source of truth.\n */\nexport const IR_VERSION = \"0.1.0\" as const;\n\n// =============================================================================\n// UTILITY TYPES\n// =============================================================================\n\n/**\n * A JSON-serializable value. All IR nodes must be representable as JSON.\n */\nexport type JsonValue =\n  | null\n  | boolean\n  | number\n  | string\n  | readonly JsonValue[]\n  | { readonly [key: string]: JsonValue };\n\n// =============================================================================\n// PROVENANCE\n// =============================================================================\n\n/**\n * Describes the origin of an IR node.\n * Enables diagnostics that point to the source of a contradiction or error.\n */\nexport interface Provenance {\n  /** The authoring surface that produced this node. */\n  readonly surface: \"tsdoc\" | \"chain-dsl\" | \"extension\" | \"inferred\";\n  /** Absolute path to the source file. */\n  readonly file: string;\n  /** 1-based line number in the source file. */\n  readonly line: number;\n  /** 0-based column number in the source file. */\n  readonly column: number;\n  /** Length of the source span in characters (for IDE underline ranges). */\n  readonly length?: number;\n  /**\n   * The specific tag, call, or construct that produced this node.\n   * Examples: `@minimum`, `field.number({ min: 0 })`, `optional`\n   */\n  readonly tagName?: string;\n}\n\n// =============================================================================\n// PATH TARGET\n// =============================================================================\n\n/**\n * A path targeting a sub-field within a complex type.\n * Used by constraints and annotations to target nested properties.\n */\nexport interface PathTarget {\n  /**\n   * Sequence of property names forming a path from the annotated field's type\n   * to the target sub-field.\n   * e.g., `[\"value\"]` or `[\"address\", \"zip\"]`\n   */\n  readonly segments: readonly string[];\n}\n\n// =============================================================================\n// TYPE NODES\n// =============================================================================\n\n/**\n * Discriminated union of all type representations in the IR.\n */\nexport type TypeNode =\n  | PrimitiveTypeNode\n  | EnumTypeNode\n  | ArrayTypeNode\n  | ObjectTypeNode\n  | UnionTypeNode\n  | ReferenceTypeNode\n  | DynamicTypeNode\n  | CustomTypeNode;\n\n/**\n * Primitive types mapping directly to JSON Schema primitives.\n *\n * Note: integer is NOT a primitive kind — integer semantics are expressed\n * via a `multipleOf: 1` constraint on a number type.\n */\nexport interface PrimitiveTypeNode {\n  readonly kind: \"primitive\";\n  readonly primitiveKind: \"string\" | \"number\" | \"boolean\" | \"null\";\n}\n\n/** A member of a static enum type. */\nexport interface EnumMember {\n  /** The serialized value stored in data. */\n  readonly value: string | number;\n  /** Optional per-member display name. */\n  readonly displayName?: string;\n}\n\n/** Static enum type — members known at build time. */\nexport interface EnumTypeNode {\n  readonly kind: \"enum\";\n  readonly members: readonly EnumMember[];\n}\n\n/** Array type with a single items type. */\nexport interface ArrayTypeNode {\n  readonly kind: \"array\";\n  readonly items: TypeNode;\n}\n\n/** A named property within an object type. */\nexport interface ObjectProperty {\n  readonly name: string;\n  readonly type: TypeNode;\n  readonly optional: boolean;\n  /**\n   * Use-site constraints on this property.\n   * Distinct from constraints on the property's type — these are\n   * use-site constraints (e.g., `@minimum :amount 0` targets the\n   * `amount` property of a `MonetaryAmount` field).\n   */\n  readonly constraints: readonly ConstraintNode[];\n  /** Use-site annotations on this property. */\n  readonly annotations: readonly AnnotationNode[];\n  readonly provenance: Provenance;\n}\n\n/** Object type with named properties. */\nexport interface ObjectTypeNode {\n  readonly kind: \"object\";\n  /**\n   * Named properties of this object. Order is preserved from the source\n   * declaration for deterministic output.\n   */\n  readonly properties: readonly ObjectProperty[];\n  /**\n   * Whether additional properties beyond those listed are permitted.\n   * Defaults to false — object types in FormSpec are closed.\n   */\n  readonly additionalProperties: boolean;\n}\n\n/** Union type for non-enum unions. Nullable types are `T | null` using this. */\nexport interface UnionTypeNode {\n  readonly kind: \"union\";\n  readonly members: readonly TypeNode[];\n}\n\n/** Named type reference — preserved as references for `$defs`/`$ref` emission. */\nexport interface ReferenceTypeNode {\n  readonly kind: \"reference\";\n  /**\n   * The fully-qualified name of the referenced type.\n   * For TypeScript interfaces/type aliases: `\"<module>#<TypeName>\"`.\n   * For built-in types: the primitive kind string.\n   */\n  readonly name: string;\n  /**\n   * Type arguments if this is a generic instantiation.\n   * e.g., `Array<string>` → `{ name: \"Array\", typeArguments: [PrimitiveTypeNode(\"string\")] }`\n   */\n  readonly typeArguments: readonly TypeNode[];\n}\n\n/** Dynamic type — schema resolved at runtime from a named data source. */\nexport interface DynamicTypeNode {\n  readonly kind: \"dynamic\";\n  readonly dynamicKind: \"enum\" | \"schema\";\n  /** Key identifying the runtime data source or schema provider. */\n  readonly sourceKey: string;\n  /**\n   * For dynamic enums: field names whose current values are passed as\n   * parameters to the data source resolver.\n   */\n  readonly parameterFields: readonly string[];\n}\n\n/** Custom type registered by an extension. */\nexport interface CustomTypeNode {\n  readonly kind: \"custom\";\n  /**\n   * The extension-qualified type identifier.\n   * Format: `\"<vendor-prefix>/<extension-name>/<type-name>\"`\n   * e.g., `\"x-stripe/monetary/MonetaryAmount\"`\n   */\n  readonly typeId: string;\n  /**\n   * Opaque payload serialized by the extension that registered this type.\n   * Must be JSON-serializable.\n   */\n  readonly payload: JsonValue;\n}\n\n// =============================================================================\n// CONSTRAINT NODES\n// =============================================================================\n\n/**\n * Discriminated union of all constraint types.\n * Constraints are set-influencing: they narrow the set of valid values.\n */\nexport type ConstraintNode =\n  | NumericConstraintNode\n  | LengthConstraintNode\n  | PatternConstraintNode\n  | ArrayCardinalityConstraintNode\n  | EnumMemberConstraintNode\n  | CustomConstraintNode;\n\n/**\n * Numeric constraints: bounds and multipleOf.\n *\n * `minimum` and `maximum` are inclusive; `exclusiveMinimum` and\n * `exclusiveMaximum` are exclusive bounds (matching JSON Schema 2020-12\n * semantics).\n *\n * Type applicability: may only attach to fields with `PrimitiveTypeNode(\"number\")`\n * or a `ReferenceTypeNode` that resolves to one.\n */\nexport interface NumericConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind:\n    | \"minimum\"\n    | \"maximum\"\n    | \"exclusiveMinimum\"\n    | \"exclusiveMaximum\"\n    | \"multipleOf\";\n  readonly value: number;\n  /** If present, targets a nested sub-field rather than the field itself. */\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/**\n * String length and array item count constraints.\n *\n * `minLength`/`maxLength` apply to strings; `minItems`/`maxItems` apply to\n * arrays. They share the same node shape because the composition rules are\n * identical.\n *\n * Type applicability: `minLength`/`maxLength` require `PrimitiveTypeNode(\"string\")`;\n * `minItems`/`maxItems` require `ArrayTypeNode`.\n */\nexport interface LengthConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"minLength\" | \"maxLength\" | \"minItems\" | \"maxItems\";\n  readonly value: number;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/**\n * String pattern constraint (ECMA-262 regex without delimiters).\n *\n * Multiple `pattern` constraints on the same field compose via intersection:\n * all patterns must match simultaneously.\n *\n * Type applicability: requires `PrimitiveTypeNode(\"string\")`.\n */\nexport interface PatternConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"pattern\";\n  /** ECMA-262 regular expression, without delimiters. */\n  readonly pattern: string;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Array uniqueness constraint. */\nexport interface ArrayCardinalityConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"uniqueItems\";\n  readonly value: true;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Enum member subset constraint (refinement — only narrows). */\nexport interface EnumMemberConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"allowedMembers\";\n  readonly members: readonly (string | number)[];\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Extension-registered custom constraint. */\nexport interface CustomConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"custom\";\n  /** Extension-qualified ID: `\"<vendor-prefix>/<extension-name>/<constraint-name>\"` */\n  readonly constraintId: string;\n  /** JSON-serializable payload defined by the extension. */\n  readonly payload: JsonValue;\n  /** How this constraint composes with others of the same `constraintId`. */\n  readonly compositionRule: \"intersect\" | \"override\";\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n// =============================================================================\n// ANNOTATION NODES\n// =============================================================================\n\n/**\n * Discriminated union of all annotation types.\n * Annotations are value-influencing: they describe or present a field\n * but do not affect which values are valid.\n */\nexport type AnnotationNode =\n  | DisplayNameAnnotationNode\n  | DescriptionAnnotationNode\n  | PlaceholderAnnotationNode\n  | DefaultValueAnnotationNode\n  | DeprecatedAnnotationNode\n  | FormatHintAnnotationNode\n  | CustomAnnotationNode;\n\nexport interface DisplayNameAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"displayName\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\nexport interface DescriptionAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"description\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\nexport interface PlaceholderAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"placeholder\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\nexport interface DefaultValueAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"defaultValue\";\n  /** Must be JSON-serializable and type-compatible (verified during Validate phase). */\n  readonly value: JsonValue;\n  readonly provenance: Provenance;\n}\n\nexport interface DeprecatedAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"deprecated\";\n  /** Optional deprecation message. */\n  readonly message?: string;\n  readonly provenance: Provenance;\n}\n\n/** UI rendering hint — does not affect schema validation. */\nexport interface FormatHintAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"formatHint\";\n  /** Renderer-specific format identifier: \"textarea\", \"radio\", \"date\", \"color\", etc. */\n  readonly format: string;\n  readonly provenance: Provenance;\n}\n\n/** Extension-registered custom annotation. */\nexport interface CustomAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"custom\";\n  /** Extension-qualified ID: `\"<vendor-prefix>/<extension-name>/<annotation-name>\"` */\n  readonly annotationId: string;\n  readonly value: JsonValue;\n  readonly provenance: Provenance;\n}\n\n// =============================================================================\n// FIELD NODE\n// =============================================================================\n\n/** A single form field after canonicalization. */\nexport interface FieldNode {\n  readonly kind: \"field\";\n  /** The field's key in the data schema. */\n  readonly name: string;\n  /** The resolved type of this field. */\n  readonly type: TypeNode;\n  /** Whether this field is required in the data schema. */\n  readonly required: boolean;\n  /** Set-influencing constraints, after merging. */\n  readonly constraints: readonly ConstraintNode[];\n  /** Value-influencing annotations, after merging. */\n  readonly annotations: readonly AnnotationNode[];\n  /** Where this field was declared. */\n  readonly provenance: Provenance;\n  /**\n   * Debug only — ordered list of constraint/annotation nodes that participated\n   * in merging, including dominated ones.\n   */\n  readonly mergeHistory?: readonly {\n    readonly node: ConstraintNode | AnnotationNode;\n    readonly dominated: boolean;\n  }[];\n}\n\n// =============================================================================\n// LAYOUT NODES\n// =============================================================================\n\n/** Union of layout node types. */\nexport type LayoutNode = GroupLayoutNode | ConditionalLayoutNode;\n\n/** A visual grouping of form elements. */\nexport interface GroupLayoutNode {\n  readonly kind: \"group\";\n  readonly label: string;\n  /** Elements contained in this group — may be fields or nested groups. */\n  readonly elements: readonly FormIRElement[];\n  readonly provenance: Provenance;\n}\n\n/** Conditional visibility based on another field's value. */\nexport interface ConditionalLayoutNode {\n  readonly kind: \"conditional\";\n  /** The field whose value triggers visibility. */\n  readonly fieldName: string;\n  /** The value that makes the condition true (SHOW). */\n  readonly value: JsonValue;\n  /** Elements shown when the condition is met. */\n  readonly elements: readonly FormIRElement[];\n  readonly provenance: Provenance;\n}\n\n/** Union of all IR element types. */\nexport type FormIRElement = FieldNode | LayoutNode;\n\n// =============================================================================\n// TYPE REGISTRY\n// =============================================================================\n\n/** A named type definition stored in the type registry. */\nexport interface TypeDefinition {\n  /** The fully-qualified reference name (key in the registry). */\n  readonly name: string;\n  /** The resolved type node. */\n  readonly type: TypeNode;\n  /** Where this type was declared. */\n  readonly provenance: Provenance;\n}\n\n// =============================================================================\n// FORM IR (TOP-LEVEL)\n// =============================================================================\n\n/**\n * The complete Canonical Intermediate Representation for a form.\n *\n * Output of the Canonicalize phase; input to Validate, Generate (JSON Schema),\n * and Generate (UI Schema) phases.\n *\n * Serializable to JSON — no live compiler objects.\n */\nexport interface FormIR {\n  readonly kind: \"form-ir\";\n  /**\n   * Schema version for the IR format itself.\n   * Should equal `IR_VERSION`.\n   */\n  readonly irVersion: string;\n  /** Top-level elements of the form: fields and layout nodes. */\n  readonly elements: readonly FormIRElement[];\n  /**\n   * Registry of named types referenced by fields in this form.\n   * Keys are fully-qualified type names matching `ReferenceTypeNode.name`.\n   */\n  readonly typeRegistry: Readonly<Record<string, TypeDefinition>>;\n  /** Provenance of the form definition itself. */\n  readonly provenance: Provenance;\n}\n","/**\n * Extension API for registering custom types, constraints, annotations,\n * and vocabulary keywords with FormSpec.\n *\n * Extensions allow third-party packages (e.g., \"Decimal\", \"DateOnly\") to\n * plug into the FormSpec pipeline. The types and factory functions defined\n * here are consumed by the FormSpec build pipeline.\n *\n * @packageDocumentation\n */\n\nimport type { JsonValue, TypeNode } from \"../types/ir.js\";\n\n// =============================================================================\n// REGISTRATION TYPES\n// =============================================================================\n\n/**\n * Registration for a custom type that maps to a JSON Schema representation.\n *\n * Custom types are referenced via {@link CustomTypeNode} in the IR and\n * resolved to JSON Schema via `toJsonSchema` during generation.\n */\nexport interface CustomTypeRegistration {\n  /** The type name, unique within the extension. */\n  readonly typeName: string;\n  /**\n   * Converts the custom type's payload into a JSON Schema fragment.\n   *\n   * @param payload - The opaque JSON payload from the {@link CustomTypeNode}.\n   * @param vendorPrefix - The vendor prefix for extension keywords (e.g., \"x-stripe\").\n   * @returns A JSON Schema fragment representing this type.\n   */\n  readonly toJsonSchema: (payload: JsonValue, vendorPrefix: string) => Record<string, unknown>;\n}\n\n/**\n * Registration for a custom constraint that maps to JSON Schema keywords.\n *\n * Custom constraints are referenced via {@link CustomConstraintNode} in the IR.\n */\nexport interface CustomConstraintRegistration {\n  /** The constraint name, unique within the extension. */\n  readonly constraintName: string;\n  /**\n   * How this constraint composes with other constraints of the same kind.\n   * - \"intersect\": combine with logical AND (both must hold)\n   * - \"override\": last writer wins\n   */\n  readonly compositionRule: \"intersect\" | \"override\";\n  /**\n   * TypeNode kinds this constraint is applicable to, or `null` for any type.\n   * Used by the validator to emit TYPE_MISMATCH diagnostics.\n   */\n  readonly applicableTypes: readonly TypeNode[\"kind\"][] | null;\n  /**\n   * Converts the custom constraint's payload into JSON Schema keywords.\n   *\n   * @param payload - The opaque JSON payload from the {@link CustomConstraintNode}.\n   * @param vendorPrefix - The vendor prefix for extension keywords.\n   * @returns A JSON Schema fragment with the constraint keywords.\n   */\n  readonly toJsonSchema: (payload: JsonValue, vendorPrefix: string) => Record<string, unknown>;\n}\n\n/**\n * Registration for a custom annotation that may produce JSON Schema keywords.\n *\n * Custom annotations are referenced via {@link CustomAnnotationNode} in the IR.\n * They describe or present a field but do not affect which values are valid.\n */\nexport interface CustomAnnotationRegistration {\n  /** The annotation name, unique within the extension. */\n  readonly annotationName: string;\n  /**\n   * Optionally converts the annotation value into JSON Schema keywords.\n   * If omitted, the annotation has no JSON Schema representation (UI-only).\n   */\n  readonly toJsonSchema?: (value: JsonValue, vendorPrefix: string) => Record<string, unknown>;\n}\n\n/**\n * Registration for a vocabulary keyword to include in a JSON Schema `$vocabulary` declaration.\n */\nexport interface VocabularyKeywordRegistration {\n  /** The keyword name (without vendor prefix). */\n  readonly keyword: string;\n  /** JSON Schema that describes the valid values for this keyword. */\n  readonly schema: JsonValue;\n}\n\n// =============================================================================\n// EXTENSION DEFINITION\n// =============================================================================\n\n/**\n * A complete extension definition bundling types, constraints, annotations,\n * and vocabulary keywords.\n *\n * @example\n * ```typescript\n * const monetaryExtension = defineExtension({\n *   extensionId: \"x-stripe/monetary\",\n *   types: [\n *     defineCustomType({\n *       typeName: \"Decimal\",\n *       toJsonSchema: (_payload, prefix) => ({\n *         type: \"string\",\n *         [`${prefix}-decimal`]: true,\n *       }),\n *     }),\n *   ],\n * });\n * ```\n */\nexport interface ExtensionDefinition {\n  /** Globally unique extension identifier, e.g., \"x-stripe/monetary\". */\n  readonly extensionId: string;\n  /** Custom type registrations provided by this extension. */\n  readonly types?: readonly CustomTypeRegistration[];\n  /** Custom constraint registrations provided by this extension. */\n  readonly constraints?: readonly CustomConstraintRegistration[];\n  /** Custom annotation registrations provided by this extension. */\n  readonly annotations?: readonly CustomAnnotationRegistration[];\n  /** Vocabulary keyword registrations provided by this extension. */\n  readonly vocabularyKeywords?: readonly VocabularyKeywordRegistration[];\n}\n\n// =============================================================================\n// FACTORY FUNCTIONS\n// =============================================================================\n\n/**\n * Defines a complete extension. Currently an identity function that provides\n * type-checking and IDE autocompletion for the definition shape.\n *\n * @param def - The extension definition.\n * @returns The same definition, validated at the type level.\n */\nexport function defineExtension(def: ExtensionDefinition): ExtensionDefinition {\n  return def;\n}\n\n/**\n * Defines a custom type registration. Currently an identity function that\n * provides type-checking and IDE autocompletion.\n *\n * @param reg - The custom type registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineCustomType(reg: CustomTypeRegistration): CustomTypeRegistration {\n  return reg;\n}\n\n/**\n * Defines a custom constraint registration. Currently an identity function\n * that provides type-checking and IDE autocompletion.\n *\n * @param reg - The custom constraint registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineConstraint(reg: CustomConstraintRegistration): CustomConstraintRegistration {\n  return reg;\n}\n\n/**\n * Defines a custom annotation registration. Currently an identity function\n * that provides type-checking and IDE autocompletion.\n *\n * @param reg - The custom annotation registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineAnnotation(reg: CustomAnnotationRegistration): CustomAnnotationRegistration {\n  return reg;\n}\n"],"mappings":";AA+BO,SAAS,wBAA2B,OAAyB;AAClE,SAAO;AAAA,IACL;AAAA,IACA,OAAO;AAAA,IACP,SAAS;AAAA,IACT,UAAU;AAAA,IACV,QAAQ,CAAC;AAAA,EACX;AACF;;;AC1BO,IAAM,iCAAiC;AAAA,EAC5C,SAAS;AAAA,EACT,SAAS;AAAA,EACT,kBAAkB;AAAA,EAClB,kBAAkB;AAAA,EAClB,WAAW;AAAA,EACX,WAAW;AAAA,EACX,SAAS;AAAA,EACT,aAAa;AACf;;;ACDO,IAAM,aAAa;;;ACsHnB,SAAS,gBAAgB,KAA+C;AAC7E,SAAO;AACT;AASO,SAAS,iBAAiB,KAAqD;AACpF,SAAO;AACT;AASO,SAAS,iBAAiB,KAAiE;AAChG,SAAO;AACT;AASO,SAAS,iBAAiB,KAAiE;AAChG,SAAO;AACT;","names":[]}

package/dist/types/constraint-definitions.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Built-in constraint definitions for FormSpec constraint validation.
+ *
+ * This is the single source of truth for which constraints FormSpec
+ * recognizes. Both `@formspec/build` (schema generation)
+ * and `@formspec/eslint-plugin` (lint-time validation) import from here.
+ */
+/**
+ * Built-in constraint names mapped to their expected value type for parsing.
+ * Constraints are surface-agnostic — they manifest as both TSDoc tags
+ * (e.g., `@Minimum 0`) and chain DSL options (e.g., `{ minimum: 0 }`).
+ */
+export declare const BUILTIN_CONSTRAINT_DEFINITIONS: {
+    readonly Minimum: "number";
+    readonly Maximum: "number";
+    readonly ExclusiveMinimum: "number";
+    readonly ExclusiveMaximum: "number";
+    readonly MinLength: "number";
+    readonly MaxLength: "number";
+    readonly Pattern: "string";
+    readonly EnumOptions: "json";
+};
+/** Type of a built-in constraint name. */
+export type BuiltinConstraintName = keyof typeof BUILTIN_CONSTRAINT_DEFINITIONS;
+//# sourceMappingURL=constraint-definitions.d.ts.map

package/dist/types/constraint-definitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraint-definitions.d.ts","sourceRoot":"","sources":["../../src/types/constraint-definitions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;GAIG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;CASjC,CAAC;AAEX,0CAA0C;AAC1C,MAAM,MAAM,qBAAqB,GAAG,MAAM,OAAO,8BAA8B,CAAC"}

package/dist/types/index.d.ts

@@ -5,6 +5,8 @@ export type { FormState } from "./form-state.js";
 export type { DataSourceRegistry, DataSourceOption, FetchOptionsResponse, DataSourceValueType, } from "./data-source.js";
 export type { TextField, NumberField, BooleanField, EnumOption, EnumOptionValue, StaticEnumField, DynamicEnumField, DynamicSchemaField, ArrayField, ObjectField, AnyField, Group, Conditional, FormElement, FormSpec, } from "./elements.js";
 export type { EqualsPredicate, Predicate } from "./predicate.js";
-export { FORMSPEC_DECORATOR_NAMES, CONSTRAINT_TAG_DEFINITIONS } from "./decorators.js";
-export type { FormSpecDecoratorName, ConstraintTagName } from "./decorators.js";
+export { BUILTIN_CONSTRAINT_DEFINITIONS } from "./constraint-definitions.js";
+export type { BuiltinConstraintName } from "./constraint-definitions.js";
+export { IR_VERSION } from "./ir.js";
+export type { JsonValue, Provenance, PathTarget, TypeNode, PrimitiveTypeNode, EnumMember, EnumTypeNode, ArrayTypeNode, ObjectProperty, ObjectTypeNode, UnionTypeNode, ReferenceTypeNode, DynamicTypeNode, CustomTypeNode, ConstraintNode, NumericConstraintNode, LengthConstraintNode, PatternConstraintNode, ArrayCardinalityConstraintNode, EnumMemberConstraintNode, CustomConstraintNode, AnnotationNode, DisplayNameAnnotationNode, DescriptionAnnotationNode, PlaceholderAnnotationNode, DefaultValueAnnotationNode, DeprecatedAnnotationNode, FormatHintAnnotationNode, CustomAnnotationNode, FieldNode, LayoutNode, GroupLayoutNode, ConditionalLayoutNode, FormIRElement, TypeDefinition, FormIR, } from "./ir.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,SAAS,EACT,WAAW,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,QAAQ,EACR,KAAK,EACL,WAAW,EACX,WAAW,EACX,QAAQ,GACT,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEjE,OAAO,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AACvF,YAAY,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,SAAS,EACT,WAAW,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,QAAQ,EACR,KAAK,EACL,WAAW,EACX,WAAW,EACX,QAAQ,GACT,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEjE,OAAO,EAAE,8BAA8B,EAAE,MAAM,6BAA6B,CAAC;AAC7E,YAAY,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAEzE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,YAAY,EACV,SAAS,EACT,UAAU,EACV,UAAU,EACV,QAAQ,EACR,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,aAAa,EACb,cAAc,EACd,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,8BAA8B,EAC9B,wBAAwB,EACxB,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,wBAAwB,EACxB,oBAAoB,EACpB,SAAS,EACT,UAAU,EACV,eAAe,EACf,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,MAAM,GACP,MAAM,SAAS,CAAC"}