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

package/dist/core-beta.d.ts

@@ -32,10 +32,15 @@ export declare type AnyField = TextField<string> | NumberField<string> | Boolean
  * @beta
  */
 export declare interface ArrayCardinalityConstraintNode {
+    /** Discriminator identifying this node as a constraint. */
     readonly kind: "constraint";
+    /** Specific array-cardinality constraint represented by this node. */
     readonly constraintKind: "uniqueItems";
+    /** Marker value used for boolean-style array uniqueness constraints. */
     readonly value: true;
+    /** Nested path target, when the constraint applies below the field root. */
     readonly path?: PathTarget;
+    /** Source location that produced this constraint. */
     readonly provenance: Provenance;
 }
 
@@ -74,7 +79,9 @@ export declare interface ArrayField<N extends string, Items extends readonly For
  * @beta
  */
 export declare interface ArrayTypeNode {
+    /** Discriminator identifying this node as an array type. */
     readonly kind: "array";
+    /** Item type for each array entry. */
     readonly items: TypeNode;
 }
 
@@ -146,6 +153,7 @@ export declare interface Conditional<FieldName extends string, Value, Elements e
  * @beta
  */
 export declare interface ConditionalLayoutNode {
+    /** Discriminator identifying this node as a conditional layout. */
     readonly kind: "conditional";
     /** The field whose value triggers visibility. */
     readonly fieldName: string;
@@ -153,6 +161,7 @@ export declare interface ConditionalLayoutNode {
     readonly value: JsonValue;
     /** Elements shown when the condition is met. */
     readonly elements: readonly FormIRElement[];
+    /** Source location that produced this layout node. */
     readonly provenance: Provenance;
 }
 
@@ -162,10 +171,15 @@ export declare interface ConditionalLayoutNode {
  * @beta
  */
 export declare interface ConstConstraintNode {
+    /** Discriminator identifying this node as a constraint. */
     readonly kind: "constraint";
+    /** Specific literal-equality constraint represented by this node. */
     readonly constraintKind: "const";
+    /** JSON-serializable literal value the field must equal. */
     readonly value: JsonValue;
+    /** Nested path target, when the constraint applies below the field root. */
     readonly path?: PathTarget;
+    /** Source location that produced this constraint. */
     readonly provenance: Provenance;
 }
 
@@ -232,11 +246,15 @@ export declare function createInitialFieldState<T>(value: T): FieldState<T>;
  * @beta
  */
 export declare interface CustomAnnotationNode {
+    /** Discriminator identifying this node as an annotation. */
     readonly kind: "annotation";
+    /** Specific annotation kind represented by this node. */
     readonly annotationKind: "custom";
     /** Extension-qualified ID: `"<vendor-prefix>/<extension-name>/<annotation-name>"` */
     readonly annotationId: string;
+    /** JSON-serializable extension payload carried by this annotation. */
     readonly value: JsonValue;
+    /** Source location that produced this annotation. */
     readonly provenance: Provenance;
 }
 
@@ -264,7 +282,9 @@ export declare interface CustomAnnotationRegistration {
  * @beta
  */
 export declare interface CustomConstraintNode {
+    /** Discriminator identifying this node as a constraint. */
     readonly kind: "constraint";
+    /** Specific custom-constraint marker used for extension nodes. */
     readonly constraintKind: "custom";
     /** Extension-qualified ID: `"<vendor-prefix>/<extension-name>/<constraint-name>"` */
     readonly constraintId: string;
@@ -272,7 +292,9 @@ export declare interface CustomConstraintNode {
     readonly payload: JsonValue;
     /** How this constraint composes with others of the same `constraintId`. */
     readonly compositionRule: "intersect" | "override";
+    /** Nested path target, when the constraint applies below the field root. */
     readonly path?: PathTarget;
+    /** Source location that produced this constraint. */
     readonly provenance: Provenance;
 }
 
@@ -329,6 +351,7 @@ export declare interface CustomConstraintRegistration {
  * @beta
  */
 export declare interface CustomTypeNode {
+    /** Discriminator identifying this node as an extension-provided type. */
     readonly kind: "custom";
     /**
      * The extension-qualified type identifier.
@@ -428,10 +451,13 @@ export declare type DataSourceValueType<Source extends string> = Source extends
  * @beta
  */
 export declare interface DefaultValueAnnotationNode {
+    /** Discriminator identifying this node as an annotation. */
     readonly kind: "annotation";
+    /** Specific annotation kind represented by this node. */
     readonly annotationKind: "defaultValue";
     /** Must be JSON-serializable and type-compatible (verified during Validate phase). */
     readonly value: JsonValue;
+    /** Source location that produced this annotation. */
     readonly provenance: Provenance;
 }
 
@@ -495,10 +521,13 @@ export declare function defineExtension(def: ExtensionDefinition): ExtensionDefi
  * @beta
  */
 export declare interface DeprecatedAnnotationNode {
+    /** Discriminator identifying this node as an annotation. */
     readonly kind: "annotation";
+    /** Specific annotation kind represented by this node. */
     readonly annotationKind: "deprecated";
     /** Optional deprecation message. */
     readonly message?: string;
+    /** Source location that produced this annotation. */
     readonly provenance: Provenance;
 }
 
@@ -508,9 +537,13 @@ export declare interface DeprecatedAnnotationNode {
  * @beta
  */
 export declare interface DescriptionAnnotationNode {
+    /** Discriminator identifying this node as an annotation. */
     readonly kind: "annotation";
+    /** Specific annotation kind represented by this node. */
     readonly annotationKind: "description";
+    /** Description text surfaced in generated schemas and tooling. */
     readonly value: string;
+    /** Source location that produced this annotation. */
     readonly provenance: Provenance;
 }
 
@@ -520,9 +553,13 @@ export declare interface DescriptionAnnotationNode {
  * @beta
  */
 export declare interface DisplayNameAnnotationNode {
+    /** Discriminator identifying this node as an annotation. */
     readonly kind: "annotation";
+    /** Specific annotation kind represented by this node. */
     readonly annotationKind: "displayName";
+    /** Human-readable display label for the field or type. */
     readonly value: string;
+    /** Source location that produced this annotation. */
     readonly provenance: Provenance;
 }
 
@@ -581,7 +618,9 @@ export declare interface DynamicSchemaField<N extends string> {
  * @beta
  */
 export declare interface DynamicTypeNode {
+    /** Discriminator identifying this node as a runtime-resolved type. */
     readonly kind: "dynamic";
+    /** Dynamic schema family resolved for this field. */
     readonly dynamicKind: "enum" | "schema";
     /** Key identifying the runtime data source or schema provider. */
     readonly sourceKey: string;
@@ -610,10 +649,15 @@ export declare interface EnumMember {
  * @beta
  */
 export declare interface EnumMemberConstraintNode {
+    /** Discriminator identifying this node as a constraint. */
     readonly kind: "constraint";
+    /** Specific enum-membership constraint represented by this node. */
     readonly constraintKind: "allowedMembers";
+    /** Subset of enum member values that remain valid. */
     readonly members: readonly (string | number)[];
+    /** Nested path target, when the constraint applies below the field root. */
     readonly path?: PathTarget;
+    /** Source location that produced this constraint. */
     readonly provenance: Provenance;
 }
 
@@ -625,7 +669,9 @@ export declare interface EnumMemberConstraintNode {
  * @public
  */
 export declare interface EnumOption {
+    /** Stored enum value written into submitted data. */
     readonly id: string;
+    /** Human-readable label shown to end users. */
     readonly label: string;
 }
 
@@ -642,7 +688,9 @@ export declare type EnumOptionValue = string | EnumOption;
  * @beta
  */
 export declare interface EnumTypeNode {
+    /** Discriminator identifying this node as an enum type. */
     readonly kind: "enum";
+    /** Allowed enum members in declaration order. */
     readonly members: readonly EnumMember[];
 }
 
@@ -762,6 +810,7 @@ export declare interface FetchOptionsResponse<T = unknown> {
  * @beta
  */
 export declare interface FieldNode {
+    /** Discriminator identifying this node as a field. */
     readonly kind: "field";
     /** The field's key in the data schema. */
     readonly name: string;
@@ -811,9 +860,13 @@ export declare interface FieldState<T> {
  * @beta
  */
 export declare interface FormatAnnotationNode {
+    /** Discriminator identifying this node as an annotation. */
     readonly kind: "annotation";
+    /** Specific annotation kind represented by this node. */
     readonly annotationKind: "format";
+    /** Schema format keyword value to emit downstream. */
     readonly value: string;
+    /** Source location that produced this annotation. */
     readonly provenance: Provenance;
 }
 
@@ -824,10 +877,13 @@ export declare interface FormatAnnotationNode {
  * @beta
  */
 export declare interface FormatHintAnnotationNode {
+    /** Discriminator identifying this node as an annotation. */
     readonly kind: "annotation";
+    /** Specific annotation kind represented by this node. */
     readonly annotationKind: "formatHint";
     /** Renderer-specific format identifier: "textarea", "radio", "date", "color", etc. */
     readonly format: string;
+    /** Source location that produced this annotation. */
     readonly provenance: Provenance;
 }
 
@@ -849,6 +905,7 @@ export declare type FormElement = AnyField | Group<readonly FormElement[]> | Con
  * @beta
  */
 export declare interface FormIR {
+    /** Discriminator identifying this document as a top-level FormIR payload. */
     readonly kind: "form-ir";
     /**
      * Schema version for the IR format itself.
@@ -933,10 +990,13 @@ export declare interface Group<Elements extends readonly FormElement[]> {
  * @beta
  */
 export declare interface GroupLayoutNode {
+    /** Discriminator identifying this node as a group layout. */
     readonly kind: "group";
+    /** Display label associated with the visual group. */
     readonly label: string;
     /** Elements contained in this group — may be fields or nested groups. */
     readonly elements: readonly FormIRElement[];
+    /** Source location that produced this layout node. */
     readonly provenance: Provenance;
 }
 
@@ -1054,10 +1114,15 @@ export declare type LayoutNode = GroupLayoutNode | ConditionalLayoutNode;
  * @beta
  */
 export declare interface LengthConstraintNode {
+    /** Discriminator identifying this node as a constraint. */
     readonly kind: "constraint";
+    /** Specific length or cardinality constraint represented by this node. */
     readonly constraintKind: "minLength" | "maxLength" | "minItems" | "maxItems";
+    /** Inclusive bound value carried by the constraint. */
     readonly value: number;
+    /** Nested path target, when the constraint applies below the field root. */
     readonly path?: PathTarget;
+    /** Source location that produced this constraint. */
     readonly provenance: Provenance;
 }
 
@@ -1100,11 +1165,15 @@ export declare interface NumberField<N extends string> {
  * @beta
  */
 export declare interface NumericConstraintNode {
+    /** Discriminator identifying this node as a constraint. */
     readonly kind: "constraint";
+    /** Specific numeric constraint represented by this node. */
     readonly constraintKind: "minimum" | "maximum" | "exclusiveMinimum" | "exclusiveMaximum" | "multipleOf";
+    /** Numeric value carried by the constraint. */
     readonly value: number;
     /** If present, targets a nested sub-field rather than the field itself. */
     readonly path?: PathTarget;
+    /** Source location that produced this constraint. */
     readonly provenance: Provenance;
 }
 
@@ -1139,8 +1208,11 @@ export declare interface ObjectField<N extends string, Properties extends readon
  * @beta
  */
 export declare interface ObjectProperty {
+    /** Property name as it appears in the containing object type. */
     readonly name: string;
+    /** Canonical IR type for this property. */
     readonly type: TypeNode;
+    /** Whether the property may be omitted from object values. */
     readonly optional: boolean;
     /**
      * Use-site constraints on this property.
@@ -1151,6 +1223,7 @@ export declare interface ObjectProperty {
     readonly constraints: readonly ConstraintNode[];
     /** Use-site annotations on this property. */
     readonly annotations: readonly AnnotationNode[];
+    /** Source location that produced this property entry. */
     readonly provenance: Provenance;
 }
 
@@ -1160,6 +1233,7 @@ export declare interface ObjectProperty {
  * @beta
  */
 export declare interface ObjectTypeNode {
+    /** Discriminator identifying this node as an object type. */
     readonly kind: "object";
     /**
      * Named properties of this object. Order is preserved from the source
@@ -1200,11 +1274,15 @@ export declare interface PathTarget {
  * @beta
  */
 export declare interface PatternConstraintNode {
+    /** Discriminator identifying this node as a constraint. */
     readonly kind: "constraint";
+    /** Specific pattern constraint represented by this node. */
     readonly constraintKind: "pattern";
     /** ECMA-262 regular expression, without delimiters. */
     readonly pattern: string;
+    /** Nested path target, when the constraint applies below the field root. */
     readonly path?: PathTarget;
+    /** Source location that produced this constraint. */
     readonly provenance: Provenance;
 }
 
@@ -1214,9 +1292,13 @@ export declare interface PatternConstraintNode {
  * @beta
  */
 export declare interface PlaceholderAnnotationNode {
+    /** Discriminator identifying this node as an annotation. */
     readonly kind: "annotation";
+    /** Specific annotation kind represented by this node. */
     readonly annotationKind: "placeholder";
+    /** Placeholder text intended for UI renderers. */
     readonly value: string;
+    /** Source location that produced this annotation. */
     readonly provenance: Provenance;
 }
 
@@ -1241,7 +1323,9 @@ export declare type Predicate<K extends string = string, V = unknown> = EqualsPr
  * @beta
  */
 export declare interface PrimitiveTypeNode {
+    /** Discriminator identifying this node as a primitive type. */
     readonly kind: "primitive";
+    /** Primitive value family represented by this node. */
     readonly primitiveKind: "string" | "number" | "integer" | "bigint" | "boolean" | "null";
 }
 
@@ -1279,6 +1363,7 @@ export declare interface Provenance {
  * @beta
  */
 export declare interface RecordTypeNode {
+    /** Discriminator identifying this node as a record type. */
     readonly kind: "record";
     /** The type of each value in the dictionary. */
     readonly valueType: TypeNode;
@@ -1290,6 +1375,7 @@ export declare interface RecordTypeNode {
  * @beta
  */
 export declare interface ReferenceTypeNode {
+    /** Discriminator identifying this node as a named reference type. */
     readonly kind: "reference";
     /**
      * The fully-qualified name of the referenced type.
@@ -1315,9 +1401,13 @@ export declare interface ReferenceTypeNode {
  * @beta
  */
 export declare interface RemarksAnnotationNode {
+    /** Discriminator identifying this node as an annotation. */
     readonly kind: "annotation";
+    /** Specific annotation kind represented by this node. */
     readonly annotationKind: "remarks";
+    /** Long-form remarks content carried through canonicalization. */
     readonly value: string;
+    /** Source location that produced this annotation. */
     readonly provenance: Provenance;
 }
 
@@ -1411,7 +1501,9 @@ export declare type TypeNode = PrimitiveTypeNode | EnumTypeNode | ArrayTypeNode
  * @beta
  */
 export declare interface UnionTypeNode {
+    /** Discriminator identifying this node as a union type. */
     readonly kind: "union";
+    /** Member types that participate in the union. */
     readonly members: readonly TypeNode[];
 }