@formspec/core 0.1.0-alpha.21 → 0.1.0-alpha.23

package/dist/internals.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types/field-state.ts","../src/types/constraint-definitions.ts","../src/types/ir.ts","../src/extensions/index.ts","../src/guards.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 *\n * @public\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 *\n * @public\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 *\n * Keys use camelCase matching JSON Schema property names.\n *\n * @internal\n */\nexport const _BUILTIN_CONSTRAINT_DEFINITIONS = {\n  minimum: \"number\",\n  maximum: \"number\",\n  exclusiveMinimum: \"number\",\n  exclusiveMaximum: \"number\",\n  multipleOf: \"number\",\n  minLength: \"number\",\n  maxLength: \"number\",\n  minItems: \"number\",\n  maxItems: \"number\",\n  uniqueItems: \"boolean\",\n  pattern: \"string\",\n  const: \"json\",\n  enumOptions: \"json\",\n} as const;\n\n/**\n * Type of a built-in constraint name.\n *\n * @public\n */\nexport type BuiltinConstraintName =\n  | \"minimum\"\n  | \"maximum\"\n  | \"exclusiveMinimum\"\n  | \"exclusiveMaximum\"\n  | \"multipleOf\"\n  | \"minLength\"\n  | \"maxLength\"\n  | \"minItems\"\n  | \"maxItems\"\n  | \"uniqueItems\"\n  | \"pattern\"\n  | \"const\"\n  | \"enumOptions\";\n\n/**\n * Normalizes a constraint tag name from PascalCase to camelCase.\n *\n * Lowercases the first character so that e.g. `\"Minimum\"` becomes `\"minimum\"`.\n * Callers must strip the `@` prefix before calling this function.\n *\n * @example\n * normalizeConstraintTagName(\"Minimum\")   // \"minimum\"\n * normalizeConstraintTagName(\"MinLength\") // \"minLength\"\n * normalizeConstraintTagName(\"minimum\")   // \"minimum\" (idempotent)\n *\n * @internal\n */\nexport function _normalizeConstraintTagName(tagName: string): string {\n  return tagName.charAt(0).toLowerCase() + tagName.slice(1);\n}\n\n/**\n * Type guard: checks whether a tag name is a known built-in constraint.\n *\n * Uses `Object.hasOwn()` rather than `in` to prevent prototype-chain\n * matches on names like `\"toString\"` or `\"constructor\"`.\n *\n * Callers should normalize with {@link _normalizeConstraintTagName} first\n * if the input may be PascalCase.\n *\n * @internal\n */\nexport function _isBuiltinConstraintName(tagName: string): tagName is BuiltinConstraintName {\n  return Object.hasOwn(_BUILTIN_CONSTRAINT_DEFINITIONS, tagName);\n}\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 *\n * @beta\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 *\n * @beta\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 *\n * @beta\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 *\n * @beta\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 *\n * @beta\n */\nexport type TypeNode =\n  | PrimitiveTypeNode\n  | EnumTypeNode\n  | ArrayTypeNode\n  | ObjectTypeNode\n  | RecordTypeNode\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 *\n * @beta\n */\nexport interface PrimitiveTypeNode {\n  readonly kind: \"primitive\";\n  readonly primitiveKind: \"string\" | \"number\" | \"integer\" | \"bigint\" | \"boolean\" | \"null\";\n}\n\n/**\n * A member of a static enum type.\n *\n * @beta\n */\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/**\n * Static enum type with members known at build time.\n *\n * @beta\n */\nexport interface EnumTypeNode {\n  readonly kind: \"enum\";\n  readonly members: readonly EnumMember[];\n}\n\n/**\n * Array type with a single items type.\n *\n * @beta\n */\nexport interface ArrayTypeNode {\n  readonly kind: \"array\";\n  readonly items: TypeNode;\n}\n\n/**\n * A named property within an object type.\n *\n * @beta\n */\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/**\n * Object type with named properties.\n *\n * @beta\n */\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   * Ordinary static object types default to true under the current spec.\n   * Explicitly closed-object modes may still set this to false.\n   */\n  readonly additionalProperties: boolean;\n}\n\n/**\n * Record (dictionary) type — an object with a string index signature and no\n * named properties. Corresponds to `Record<string, T>` or `{ [k: string]: T }`.\n *\n * Emitted as `{ \"type\": \"object\", \"additionalProperties\": <value schema> }` in\n * JSON Schema per spec 003 §2.5.\n *\n * @beta\n */\nexport interface RecordTypeNode {\n  readonly kind: \"record\";\n  /** The type of each value in the dictionary. */\n  readonly valueType: TypeNode;\n}\n\n/**\n * Union type for non-enum unions. Nullable types are represented as `T | null`.\n *\n * @beta\n */\nexport interface UnionTypeNode {\n  readonly kind: \"union\";\n  readonly members: readonly TypeNode[];\n}\n\n/**\n * Named type reference preserved for `$defs` and `$ref` emission.\n *\n * @beta\n */\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/**\n * Dynamic type whose schema is resolved at runtime from a named data source.\n *\n * @beta\n */\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/**\n * Custom type registered by an extension.\n *\n * @beta\n */\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 *\n * @beta\n */\nexport type ConstraintNode =\n  | NumericConstraintNode\n  | LengthConstraintNode\n  | PatternConstraintNode\n  | ArrayCardinalityConstraintNode\n  | EnumMemberConstraintNode\n  | ConstConstraintNode\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 *\n * @beta\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 *\n * @beta\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 *\n * @beta\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/**\n * Array uniqueness constraint.\n *\n * @beta\n */\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/**\n * Enum member subset constraint that only narrows the allowed member set.\n *\n * @beta\n */\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/**\n * Literal-value equality constraint.\n *\n * @beta\n */\nexport interface ConstConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"const\";\n  readonly value: JsonValue;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/**\n * Extension-registered custom constraint.\n *\n * @beta\n */\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 *\n * @beta\n */\nexport type AnnotationNode =\n  | DisplayNameAnnotationNode\n  | DescriptionAnnotationNode\n  | RemarksAnnotationNode\n  | FormatAnnotationNode\n  | PlaceholderAnnotationNode\n  | DefaultValueAnnotationNode\n  | DeprecatedAnnotationNode\n  | FormatHintAnnotationNode\n  | CustomAnnotationNode;\n\n/**\n * Display-name annotation.\n *\n * @beta\n */\nexport interface DisplayNameAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"displayName\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\n/**\n * Description annotation.\n *\n * @beta\n */\nexport interface DescriptionAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"description\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\n/**\n * Remarks annotation — programmatic-persona documentation carried via\n * the `x-<vendor>-remarks` JSON Schema extension keyword.\n *\n * Populated from `@remarks` TSDoc tag content. SDK codegen can include\n * this in doc comments; API Documenter renders the source `@remarks`\n * natively in a dedicated Remarks section.\n *\n * @beta\n */\nexport interface RemarksAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"remarks\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\n/**\n * Schema format annotation, for example `email`, `date`, or `uri`.\n *\n * @beta\n */\nexport interface FormatAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"format\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\n/**\n * Placeholder annotation.\n *\n * @beta\n */\nexport interface PlaceholderAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"placeholder\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\n/**\n * Default-value annotation.\n *\n * @beta\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\n/**\n * Deprecated annotation.\n *\n * @beta\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/**\n * UI rendering hint — does not affect schema validation.\n * Unlike FormatAnnotationNode, this never emits a JSON Schema `format`.\n *\n * @beta\n */\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/**\n * Extension-registered custom annotation.\n *\n * @beta\n */\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/**\n * A single form field after canonicalization.\n *\n * @beta\n */\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/**\n * Union of layout node types.\n *\n * @beta\n */\nexport type LayoutNode = GroupLayoutNode | ConditionalLayoutNode;\n\n/**\n * A visual grouping of form elements.\n *\n * @beta\n */\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/**\n * Conditional visibility based on another field's value.\n *\n * @beta\n */\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/**\n * Union of all IR element types.\n *\n * @beta\n */\nexport type FormIRElement = FieldNode | LayoutNode;\n\n// =============================================================================\n// TYPE REGISTRY\n// =============================================================================\n\n/**\n * A named type definition stored in the type registry.\n *\n * @beta\n */\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  /** Constraints declared on the named type itself. */\n  readonly constraints?: readonly ConstraintNode[];\n  /** Root-level value metadata for a named type definition. */\n  readonly annotations?: readonly AnnotationNode[];\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 *\n * @beta\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  /** Root-level annotations derived from the source declaration itself. */\n  readonly rootAnnotations?: readonly AnnotationNode[];\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  /** Root-level metadata for the form itself. */\n  readonly annotations?: readonly AnnotationNode[];\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 { BuiltinConstraintName } from \"../types/constraint-definitions.js\";\n\n// =============================================================================\n// REGISTRATION TYPES\n// =============================================================================\n\n/**\n * A JSON-serializable payload value used by extension registration hooks.\n *\n * @public\n */\nexport type ExtensionPayloadValue =\n  | null\n  | boolean\n  | number\n  | string\n  | readonly ExtensionPayloadValue[]\n  | { readonly [key: string]: ExtensionPayloadValue };\n\n/**\n * Top-level type kinds that extension applicability hooks may inspect.\n *\n * @public\n */\nexport type ExtensionTypeKind =\n  | \"primitive\"\n  | \"enum\"\n  | \"array\"\n  | \"object\"\n  | \"record\"\n  | \"union\"\n  | \"reference\"\n  | \"dynamic\"\n  | \"custom\";\n\n/**\n * A curated type shape exposed to extension applicability hooks.\n *\n * This intentionally exposes only the fields needed to determine tag/type\n * applicability without committing the entire canonical IR as public API.\n *\n * @public\n */\nexport type ExtensionApplicableType =\n  | {\n      readonly kind: \"primitive\";\n      readonly primitiveKind: \"string\" | \"number\" | \"integer\" | \"bigint\" | \"boolean\" | \"null\";\n    }\n  | {\n      readonly kind: \"custom\";\n      readonly typeId: string;\n      readonly payload: ExtensionPayloadValue;\n    }\n  | { readonly kind: Exclude<ExtensionTypeKind, \"primitive\" | \"custom\"> };\n\n/**\n * Registration for a custom type that maps to a JSON Schema representation.\n *\n * Custom types are referenced by FormSpec's internal custom-type IR nodes and\n * resolved to JSON Schema via `toJsonSchema` during generation.\n *\n * @public\n */\nexport interface CustomTypeRegistration {\n  /** The type name, unique within the extension. */\n  readonly typeName: string;\n  /**\n   * Optional TypeScript surface names that should resolve to this custom type\n   * during TSDoc/class analysis. Defaults to `typeName` when omitted.\n   */\n  readonly tsTypeNames?: readonly string[];\n  /**\n   * Converts the custom type's payload into a JSON Schema fragment.\n   *\n   * @param payload - The opaque JSON payload stored on the custom type node.\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: (\n    payload: ExtensionPayloadValue,\n    vendorPrefix: string\n  ) => Record<string, unknown>;\n  /**\n   * Optional broadening of built-in constraint tags so they can apply to this\n   * custom type without modifying the core built-in constraint tables.\n   */\n  readonly builtinConstraintBroadenings?: readonly BuiltinConstraintBroadeningRegistration[];\n}\n\n/**\n * Registration for a custom constraint that maps to JSON Schema keywords.\n *\n * Custom constraints are referenced by FormSpec's internal custom-constraint nodes.\n *\n * @public\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 ExtensionApplicableType[\"kind\"][] | null;\n  /**\n   * Optional precise type predicate used when kind-level applicability is too\n   * broad (for example, constraints that apply to integer-like primitives but\n   * not strings).\n   */\n  readonly isApplicableToType?: (type: ExtensionApplicableType) => boolean;\n  /**\n   * Optional comparator for payloads belonging to the same custom constraint.\n   * Return values follow the `Array.prototype.sort()` contract.\n   */\n  readonly comparePayloads?: (left: ExtensionPayloadValue, right: ExtensionPayloadValue) => number;\n  /**\n   * Optional semantic family metadata for generic contradiction/broadening\n   * handling across ordered constraints.\n   */\n  readonly semanticRole?: ConstraintSemanticRole;\n  /**\n   * Converts the custom constraint's payload into JSON Schema keywords.\n   *\n   * @param payload - The opaque JSON payload stored on the custom constraint node.\n   * @param vendorPrefix - The vendor prefix for extension keywords.\n   * @returns A JSON Schema fragment with the constraint keywords.\n   */\n  readonly toJsonSchema: (\n    payload: ExtensionPayloadValue,\n    vendorPrefix: string\n  ) => Record<string, unknown>;\n}\n\n/**\n * Registration for a custom annotation that may produce JSON Schema keywords.\n *\n * Custom annotations are referenced by FormSpec's internal custom-annotation nodes.\n * They describe or present a field but do not affect which values are valid.\n *\n * @public\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?: (\n    value: ExtensionPayloadValue,\n    vendorPrefix: string\n  ) => Record<string, unknown>;\n}\n\n/**\n * Registration for a vocabulary keyword to include in a JSON Schema `$vocabulary` declaration.\n *\n * @public\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: ExtensionPayloadValue;\n}\n\n/**\n * Declarative authoring-side registration for a custom TSDoc constraint tag.\n *\n * @public\n */\nexport interface ConstraintTagRegistration {\n  /** Tag name without the `@` prefix, e.g. `\"maxSigFig\"`. */\n  readonly tagName: string;\n  /** The custom constraint that this tag should produce. */\n  readonly constraintName: string;\n  /** Parser from raw TSDoc text to JSON-serializable payload. */\n  readonly parseValue: (raw: string) => ExtensionPayloadValue;\n  /**\n   * Optional precise applicability predicate for the field type being parsed.\n   * When omitted, the target custom constraint registration controls type\n   * applicability during validation.\n   */\n  readonly isApplicableToType?: (type: ExtensionApplicableType) => boolean;\n}\n\n/**\n * Registration for mapping a built-in TSDoc tag onto a custom constraint when\n * it is used on a particular custom type.\n *\n * @public\n */\nexport interface BuiltinConstraintBroadeningRegistration {\n  /** The built-in tag being broadened, without the `@` prefix. */\n  readonly tagName: BuiltinConstraintName;\n  /** The custom constraint to emit for this built-in tag. */\n  readonly constraintName: string;\n  /** Parser from raw TSDoc text to extension payload. */\n  readonly parseValue: (raw: string) => ExtensionPayloadValue;\n}\n\n/**\n * Semantic metadata for ordered custom constraints that should participate in\n * the generic contradiction/broadening logic.\n *\n * @public\n */\nexport interface ConstraintSemanticRole {\n  /**\n   * Logical family identifier shared by related constraints, for example\n   * `\"decimal-bound\"` or `\"date-bound\"`.\n   */\n  readonly family: string;\n  /** Whether this constraint acts as a lower or upper bound. */\n  readonly bound: \"lower\" | \"upper\" | \"exact\";\n  /** Whether equality is allowed when comparing against the bound. */\n  readonly inclusive: boolean;\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 *\n * @public\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  /** Authoring-side TSDoc tag registrations provided by this extension. */\n  readonly constraintTags?: readonly ConstraintTagRegistration[];\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 *\n * @public\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 *\n * @public\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 *\n * @public\n */\nexport function defineConstraint(reg: CustomConstraintRegistration): CustomConstraintRegistration {\n  return reg;\n}\n\n/**\n * Defines a custom TSDoc constraint tag registration.\n *\n * @param reg - The custom tag registration.\n * @returns The same registration, validated at the type level.\n *\n * @public\n */\nexport function defineConstraintTag(reg: ConstraintTagRegistration): ConstraintTagRegistration {\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 *\n * @public\n */\nexport function defineAnnotation(reg: CustomAnnotationRegistration): CustomAnnotationRegistration {\n  return reg;\n}\n","/**\n * Type guards for FormSpec form elements.\n *\n * Each guard narrows a {@link FormElement} to a specific field, group, or conditional type.\n */\n\nimport type {\n  FormElement,\n  AnyField,\n  TextField,\n  NumberField,\n  BooleanField,\n  StaticEnumField,\n  DynamicEnumField,\n  DynamicSchemaField,\n  ArrayField,\n  ObjectField,\n  Group,\n  Conditional,\n  EnumOptionValue,\n} from \"./types/elements.js\";\n\n/**\n * Narrows a `FormElement` to any field type.\n *\n * @public\n */\nexport function isField(element: FormElement): element is AnyField {\n  return element._type === \"field\";\n}\n\n/**\n * Narrows a `FormElement` to a text input field.\n *\n * @public\n */\nexport function isTextField(element: FormElement): element is TextField<string> {\n  return element._type === \"field\" && element._field === \"text\";\n}\n\n/**\n * Narrows a `FormElement` to a numeric input field.\n *\n * @public\n */\nexport function isNumberField(element: FormElement): element is NumberField<string> {\n  return element._type === \"field\" && element._field === \"number\";\n}\n\n/**\n * Narrows a `FormElement` to a boolean checkbox field.\n *\n * @public\n */\nexport function isBooleanField(element: FormElement): element is BooleanField<string> {\n  return element._type === \"field\" && element._field === \"boolean\";\n}\n\n/**\n * Narrows a `FormElement` to a static enum field.\n *\n * @public\n */\nexport function isStaticEnumField(\n  element: FormElement\n): element is StaticEnumField<string, readonly EnumOptionValue[]> {\n  return element._type === \"field\" && element._field === \"enum\";\n}\n\n/**\n * Narrows a `FormElement` to a dynamic enum field.\n *\n * @public\n */\nexport function isDynamicEnumField(\n  element: FormElement\n): element is DynamicEnumField<string, string> {\n  return element._type === \"field\" && element._field === \"dynamic_enum\";\n}\n\n/**\n * Narrows a `FormElement` to a dynamic schema field.\n *\n * @public\n */\nexport function isDynamicSchemaField(element: FormElement): element is DynamicSchemaField<string> {\n  return element._type === \"field\" && element._field === \"dynamic_schema\";\n}\n\n/**\n * Narrows a `FormElement` to an array field.\n *\n * @public\n */\nexport function isArrayField(\n  element: FormElement\n): element is ArrayField<string, readonly FormElement[]> {\n  return element._type === \"field\" && element._field === \"array\";\n}\n\n/**\n * Narrows a `FormElement` to an object field.\n *\n * @public\n */\nexport function isObjectField(\n  element: FormElement\n): element is ObjectField<string, readonly FormElement[]> {\n  return element._type === \"field\" && element._field === \"object\";\n}\n\n/**\n * Narrows a `FormElement` to a visual group.\n *\n * @public\n */\nexport function isGroup(element: FormElement): element is Group<readonly FormElement[]> {\n  return element._type === \"group\";\n}\n\n/**\n * Narrows a `FormElement` to a conditional wrapper.\n *\n * @public\n */\nexport function isConditional(\n  element: FormElement\n): element is Conditional<string, unknown, readonly FormElement[]> {\n  return element._type === \"conditional\";\n}\n"],"mappings":";AAmCO,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,kCAAkC;AAAA,EAC7C,SAAS;AAAA,EACT,SAAS;AAAA,EACT,kBAAkB;AAAA,EAClB,kBAAkB;AAAA,EAClB,YAAY;AAAA,EACZ,WAAW;AAAA,EACX,WAAW;AAAA,EACX,UAAU;AAAA,EACV,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO;AAAA,EACP,aAAa;AACf;AAmCO,SAAS,4BAA4B,SAAyB;AACnE,SAAO,QAAQ,OAAO,CAAC,EAAE,YAAY,IAAI,QAAQ,MAAM,CAAC;AAC1D;AAaO,SAAS,yBAAyB,SAAmD;AAC1F,SAAO,OAAO,OAAO,iCAAiC,OAAO;AAC/D;;;AC5DO,IAAM,aAAa;;;AC2QnB,SAAS,gBAAgB,KAA+C;AAC7E,SAAO;AACT;AAWO,SAAS,iBAAiB,KAAqD;AACpF,SAAO;AACT;AAWO,SAAS,iBAAiB,KAAiE;AAChG,SAAO;AACT;AAUO,SAAS,oBAAoB,KAA2D;AAC7F,SAAO;AACT;AAWO,SAAS,iBAAiB,KAAiE;AAChG,SAAO;AACT;;;AC5TO,SAAS,QAAQ,SAA2C;AACjE,SAAO,QAAQ,UAAU;AAC3B;AAOO,SAAS,YAAY,SAAoD;AAC9E,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAOO,SAAS,cAAc,SAAsD;AAClF,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAOO,SAAS,eAAe,SAAuD;AACpF,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAOO,SAAS,kBACd,SACgE;AAChE,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAOO,SAAS,mBACd,SAC6C;AAC7C,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAOO,SAAS,qBAAqB,SAA6D;AAChG,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAOO,SAAS,aACd,SACuD;AACvD,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAOO,SAAS,cACd,SACwD;AACxD,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAOO,SAAS,QAAQ,SAAgE;AACtF,SAAO,QAAQ,UAAU;AAC3B;AAOO,SAAS,cACd,SACiE;AACjE,SAAO,QAAQ,UAAU;AAC3B;","names":[]}

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

@@ -12,9 +12,9 @@
  *
  * Keys use camelCase matching JSON Schema property names.
  *
- * @public
+ * @internal
  */
-export declare const BUILTIN_CONSTRAINT_DEFINITIONS: {
+export declare const _BUILTIN_CONSTRAINT_DEFINITIONS: {
     readonly minimum: "number";
     readonly maximum: "number";
     readonly exclusiveMinimum: "number";
@@ -34,7 +34,7 @@ export declare const BUILTIN_CONSTRAINT_DEFINITIONS: {
  *
  * @public
  */
-export type BuiltinConstraintName = keyof typeof BUILTIN_CONSTRAINT_DEFINITIONS;
+export type BuiltinConstraintName = "minimum" | "maximum" | "exclusiveMinimum" | "exclusiveMaximum" | "multipleOf" | "minLength" | "maxLength" | "minItems" | "maxItems" | "uniqueItems" | "pattern" | "const" | "enumOptions";
 /**
  * Normalizes a constraint tag name from PascalCase to camelCase.
  *
@@ -46,19 +46,19 @@ export type BuiltinConstraintName = keyof typeof BUILTIN_CONSTRAINT_DEFINITIONS;
  * normalizeConstraintTagName("MinLength") // "minLength"
  * normalizeConstraintTagName("minimum")   // "minimum" (idempotent)
  *
- * @public
+ * @internal
  */
-export declare function normalizeConstraintTagName(tagName: string): string;
+export declare function _normalizeConstraintTagName(tagName: string): string;
 /**
  * Type guard: checks whether a tag name is a known built-in constraint.
  *
  * Uses `Object.hasOwn()` rather than `in` to prevent prototype-chain
  * matches on names like `"toString"` or `"constructor"`.
  *
- * Callers should normalize with {@link normalizeConstraintTagName} first
+ * Callers should normalize with {@link _normalizeConstraintTagName} first
  * if the input may be PascalCase.
  *
- * @public
+ * @internal
  */
-export declare function isBuiltinConstraintName(tagName: string): tagName is BuiltinConstraintName;
+export declare function _isBuiltinConstraintName(tagName: string): tagName is BuiltinConstraintName;
 //# sourceMappingURL=constraint-definitions.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"constraint-definitions.d.ts","sourceRoot":"","sources":["../../src/types/constraint-definitions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;CAcjC,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,OAAO,8BAA8B,CAAC;AAEhF;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,IAAI,qBAAqB,CAEzF"}
+{"version":3,"file":"constraint-definitions.d.ts","sourceRoot":"","sources":["../../src/types/constraint-definitions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;CAclC,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAC7B,SAAS,GACT,SAAS,GACT,kBAAkB,GAClB,kBAAkB,GAClB,YAAY,GACZ,WAAW,GACX,WAAW,GACX,UAAU,GACV,UAAU,GACV,aAAa,GACb,SAAS,GACT,OAAO,GACP,aAAa,CAAC;AAElB;;;;;;;;;;;;GAYG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,IAAI,qBAAqB,CAE1F"}

package/dist/types/index.d.ts

@@ -5,8 +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 { BUILTIN_CONSTRAINT_DEFINITIONS, normalizeConstraintTagName, isBuiltinConstraintName, } from "./constraint-definitions.js";
 export type { BuiltinConstraintName } from "./constraint-definitions.js";
+export { _BUILTIN_CONSTRAINT_DEFINITIONS, _normalizeConstraintTagName, _isBuiltinConstraintName, } from "./constraint-definitions.js";
 export { IR_VERSION } from "./ir.js";
 export type { JsonValue, Provenance, PathTarget, TypeNode, PrimitiveTypeNode, EnumMember, EnumTypeNode, ArrayTypeNode, ObjectProperty, ObjectTypeNode, RecordTypeNode, UnionTypeNode, ReferenceTypeNode, DynamicTypeNode, CustomTypeNode, ConstraintNode, NumericConstraintNode, LengthConstraintNode, PatternConstraintNode, ArrayCardinalityConstraintNode, EnumMemberConstraintNode, ConstConstraintNode, CustomConstraintNode, AnnotationNode, DisplayNameAnnotationNode, DescriptionAnnotationNode, RemarksAnnotationNode, FormatAnnotationNode, 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,EACL,8BAA8B,EAC9B,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,6BAA6B,CAAC;AACrC,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,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,8BAA8B,EAC9B,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,yBAAyB,EACzB,qBAAqB,EACrB,oBAAoB,EACpB,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"}
+{"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,YAAY,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EACL,+BAA+B,EAC/B,2BAA2B,EAC3B,wBAAwB,GACzB,MAAM,6BAA6B,CAAC;AAErC,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,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,8BAA8B,EAC9B,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,yBAAyB,EACzB,qBAAqB,EACrB,oBAAoB,EACpB,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"}

package/dist/types/ir.d.ts

@@ -14,13 +14,13 @@
  * The current IR format version. Centralized here so all canonicalizers
  * and consumers reference a single source of truth.
  *
- * @public
+ * @beta
  */
 export declare const IR_VERSION: "0.1.0";
 /**
  * A JSON-serializable value. All IR nodes must be representable as JSON.
  *
- * @public
+ * @beta
  */
 export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
@@ -29,7 +29,7 @@ export type JsonValue = null | boolean | number | string | readonly JsonValue[]
  * Describes the origin of an IR node.
  * Enables diagnostics that point to the source of a contradiction or error.
  *
- * @public
+ * @beta
  */
 export interface Provenance {
     /** The authoring surface that produced this node. */
@@ -52,7 +52,7 @@ export interface Provenance {
  * A path targeting a sub-field within a complex type.
  * Used by constraints and annotations to target nested properties.
  *
- * @public
+ * @beta
  */
 export interface PathTarget {
     /**
@@ -65,7 +65,7 @@ export interface PathTarget {
 /**
  * Discriminated union of all type representations in the IR.
  *
- * @public
+ * @beta
  */
 export type TypeNode = PrimitiveTypeNode | EnumTypeNode | ArrayTypeNode | ObjectTypeNode | RecordTypeNode | UnionTypeNode | ReferenceTypeNode | DynamicTypeNode | CustomTypeNode;
 /**
@@ -74,7 +74,7 @@ export type TypeNode = PrimitiveTypeNode | EnumTypeNode | ArrayTypeNode | Object
  * Note: integer is NOT a primitive kind — integer semantics are expressed
  * via a `multipleOf: 1` constraint on a number type.
  *
- * @public
+ * @beta
  */
 export interface PrimitiveTypeNode {
     readonly kind: "primitive";
@@ -83,7 +83,7 @@ export interface PrimitiveTypeNode {
 /**
  * A member of a static enum type.
  *
- * @public
+ * @beta
  */
 export interface EnumMember {
     /** The serialized value stored in data. */
@@ -94,7 +94,7 @@ export interface EnumMember {
 /**
  * Static enum type with members known at build time.
  *
- * @public
+ * @beta
  */
 export interface EnumTypeNode {
     readonly kind: "enum";
@@ -103,7 +103,7 @@ export interface EnumTypeNode {
 /**
  * Array type with a single items type.
  *
- * @public
+ * @beta
  */
 export interface ArrayTypeNode {
     readonly kind: "array";
@@ -112,7 +112,7 @@ export interface ArrayTypeNode {
 /**
  * A named property within an object type.
  *
- * @public
+ * @beta
  */
 export interface ObjectProperty {
     readonly name: string;
@@ -132,7 +132,7 @@ export interface ObjectProperty {
 /**
  * Object type with named properties.
  *
- * @public
+ * @beta
  */
 export interface ObjectTypeNode {
     readonly kind: "object";
@@ -155,7 +155,7 @@ export interface ObjectTypeNode {
  * Emitted as `{ "type": "object", "additionalProperties": <value schema> }` in
  * JSON Schema per spec 003 §2.5.
  *
- * @public
+ * @beta
  */
 export interface RecordTypeNode {
     readonly kind: "record";
@@ -165,7 +165,7 @@ export interface RecordTypeNode {
 /**
  * Union type for non-enum unions. Nullable types are represented as `T | null`.
  *
- * @public
+ * @beta
  */
 export interface UnionTypeNode {
     readonly kind: "union";
@@ -174,7 +174,7 @@ export interface UnionTypeNode {
 /**
  * Named type reference preserved for `$defs` and `$ref` emission.
  *
- * @public
+ * @beta
  */
 export interface ReferenceTypeNode {
     readonly kind: "reference";
@@ -193,7 +193,7 @@ export interface ReferenceTypeNode {
 /**
  * Dynamic type whose schema is resolved at runtime from a named data source.
  *
- * @public
+ * @beta
  */
 export interface DynamicTypeNode {
     readonly kind: "dynamic";
@@ -209,7 +209,7 @@ export interface DynamicTypeNode {
 /**
  * Custom type registered by an extension.
  *
- * @public
+ * @beta
  */
 export interface CustomTypeNode {
     readonly kind: "custom";
@@ -229,7 +229,7 @@ export interface CustomTypeNode {
  * Discriminated union of all constraint types.
  * Constraints are set-influencing: they narrow the set of valid values.
  *
- * @public
+ * @beta
  */
 export type ConstraintNode = NumericConstraintNode | LengthConstraintNode | PatternConstraintNode | ArrayCardinalityConstraintNode | EnumMemberConstraintNode | ConstConstraintNode | CustomConstraintNode;
 /**
@@ -242,7 +242,7 @@ export type ConstraintNode = NumericConstraintNode | LengthConstraintNode | Patt
  * Type applicability: may only attach to fields with `PrimitiveTypeNode("number")`
  * or a `ReferenceTypeNode` that resolves to one.
  *
- * @public
+ * @beta
  */
 export interface NumericConstraintNode {
     readonly kind: "constraint";
@@ -262,7 +262,7 @@ export interface NumericConstraintNode {
  * Type applicability: `minLength`/`maxLength` require `PrimitiveTypeNode("string")`;
  * `minItems`/`maxItems` require `ArrayTypeNode`.
  *
- * @public
+ * @beta
  */
 export interface LengthConstraintNode {
     readonly kind: "constraint";
@@ -279,7 +279,7 @@ export interface LengthConstraintNode {
  *
  * Type applicability: requires `PrimitiveTypeNode("string")`.
  *
- * @public
+ * @beta
  */
 export interface PatternConstraintNode {
     readonly kind: "constraint";
@@ -292,7 +292,7 @@ export interface PatternConstraintNode {
 /**
  * Array uniqueness constraint.
  *
- * @public
+ * @beta
  */
 export interface ArrayCardinalityConstraintNode {
     readonly kind: "constraint";
@@ -304,7 +304,7 @@ export interface ArrayCardinalityConstraintNode {
 /**
  * Enum member subset constraint that only narrows the allowed member set.
  *
- * @public
+ * @beta
  */
 export interface EnumMemberConstraintNode {
     readonly kind: "constraint";
@@ -316,7 +316,7 @@ export interface EnumMemberConstraintNode {
 /**
  * Literal-value equality constraint.
  *
- * @public
+ * @beta
  */
 export interface ConstConstraintNode {
     readonly kind: "constraint";
@@ -328,7 +328,7 @@ export interface ConstConstraintNode {
 /**
  * Extension-registered custom constraint.
  *
- * @public
+ * @beta
  */
 export interface CustomConstraintNode {
     readonly kind: "constraint";
@@ -347,13 +347,13 @@ export interface CustomConstraintNode {
  * Annotations are value-influencing: they describe or present a field
  * but do not affect which values are valid.
  *
- * @public
+ * @beta
  */
 export type AnnotationNode = DisplayNameAnnotationNode | DescriptionAnnotationNode | RemarksAnnotationNode | FormatAnnotationNode | PlaceholderAnnotationNode | DefaultValueAnnotationNode | DeprecatedAnnotationNode | FormatHintAnnotationNode | CustomAnnotationNode;
 /**
  * Display-name annotation.
  *
- * @public
+ * @beta
  */
 export interface DisplayNameAnnotationNode {
     readonly kind: "annotation";
@@ -364,7 +364,7 @@ export interface DisplayNameAnnotationNode {
 /**
  * Description annotation.
  *
- * @public
+ * @beta
  */
 export interface DescriptionAnnotationNode {
     readonly kind: "annotation";
@@ -380,7 +380,7 @@ export interface DescriptionAnnotationNode {
  * this in doc comments; API Documenter renders the source `@remarks`
  * natively in a dedicated Remarks section.
  *
- * @public
+ * @beta
  */
 export interface RemarksAnnotationNode {
     readonly kind: "annotation";
@@ -391,7 +391,7 @@ export interface RemarksAnnotationNode {
 /**
  * Schema format annotation, for example `email`, `date`, or `uri`.
  *
- * @public
+ * @beta
  */
 export interface FormatAnnotationNode {
     readonly kind: "annotation";
@@ -402,7 +402,7 @@ export interface FormatAnnotationNode {
 /**
  * Placeholder annotation.
  *
- * @public
+ * @beta
  */
 export interface PlaceholderAnnotationNode {
     readonly kind: "annotation";
@@ -413,7 +413,7 @@ export interface PlaceholderAnnotationNode {
 /**
  * Default-value annotation.
  *
- * @public
+ * @beta
  */
 export interface DefaultValueAnnotationNode {
     readonly kind: "annotation";
@@ -425,7 +425,7 @@ export interface DefaultValueAnnotationNode {
 /**
  * Deprecated annotation.
  *
- * @public
+ * @beta
  */
 export interface DeprecatedAnnotationNode {
     readonly kind: "annotation";
@@ -438,7 +438,7 @@ export interface DeprecatedAnnotationNode {
  * UI rendering hint — does not affect schema validation.
  * Unlike FormatAnnotationNode, this never emits a JSON Schema `format`.
  *
- * @public
+ * @beta
  */
 export interface FormatHintAnnotationNode {
     readonly kind: "annotation";
@@ -450,7 +450,7 @@ export interface FormatHintAnnotationNode {
 /**
  * Extension-registered custom annotation.
  *
- * @public
+ * @beta
  */
 export interface CustomAnnotationNode {
     readonly kind: "annotation";
@@ -463,7 +463,7 @@ export interface CustomAnnotationNode {
 /**
  * A single form field after canonicalization.
  *
- * @public
+ * @beta
  */
 export interface FieldNode {
     readonly kind: "field";
@@ -491,13 +491,13 @@ export interface FieldNode {
 /**
  * Union of layout node types.
  *
- * @public
+ * @beta
  */
 export type LayoutNode = GroupLayoutNode | ConditionalLayoutNode;
 /**
  * A visual grouping of form elements.
  *
- * @public
+ * @beta
  */
 export interface GroupLayoutNode {
     readonly kind: "group";
@@ -509,7 +509,7 @@ export interface GroupLayoutNode {
 /**
  * Conditional visibility based on another field's value.
  *
- * @public
+ * @beta
  */
 export interface ConditionalLayoutNode {
     readonly kind: "conditional";
@@ -524,13 +524,13 @@ export interface ConditionalLayoutNode {
 /**
  * Union of all IR element types.
  *
- * @public
+ * @beta
  */
 export type FormIRElement = FieldNode | LayoutNode;
 /**
  * A named type definition stored in the type registry.
  *
- * @public
+ * @beta
  */
 export interface TypeDefinition {
     /** The fully-qualified reference name (key in the registry). */
@@ -552,7 +552,7 @@ export interface TypeDefinition {
  *
  * Serializable to JSON — no live compiler objects.
  *
- * @public
+ * @beta
  */
 export interface FormIR {
     readonly kind: "form-ir";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formspec/core",
-  "version": "0.1.0-alpha.21",
+  "version": "0.1.0-alpha.23",
   "description": "Core utilities for formspec",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -11,6 +11,11 @@
       "types": "./dist/core.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./internals": {
+      "types": "./dist/internals.d.ts",
+      "import": "./dist/internals.js",
+      "require": "./dist/internals.cjs"
     }
   },
   "files": [
@@ -30,13 +35,13 @@
   "keywords": [],
   "license": "UNLICENSED",
   "scripts": {
-    "build": "tsup && tsc --emitDeclarationOnly && api-extractor run --local",
+    "build": "tsup && tsc --emitDeclarationOnly && pnpm run api-extractor:local",
     "clean": "rm -rf dist temp",
     "typecheck": "tsc --noEmit",
     "test": "vitest run && tsd",
     "test:types": "tsd",
-    "api-extractor": "api-extractor run",
-    "api-extractor:local": "api-extractor run --local",
-    "api-documenter": "api-documenter markdown -i temp -o docs"
+    "api-extractor": "api-extractor run && node ../../scripts/normalize-generated-markdown.mjs api-report",
+    "api-extractor:local": "api-extractor run --local && node ../../scripts/normalize-generated-markdown.mjs api-report",
+    "api-documenter": "api-documenter markdown -i temp -o docs && node ../../scripts/normalize-generated-markdown.mjs docs"
   }
 }