formspec 0.1.0-alpha.27 → 0.1.0-alpha.29

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike North
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -65,7 +65,6 @@ const resolvers = defineResolvers(OrderForm, {});
 - `generateJsonSchema`
 - `generateUiSchema`
 - `writeSchemas`
-- `buildMixedAuthoringSchemas`
 
 ### Runtime
 
@@ -76,14 +75,21 @@ const resolvers = defineResolvers(OrderForm, {});
 - `InferSchema`
 - `InferFormSchema`
 - core field, layout, and state types
+- resolver and validation helper types
+
+### Utilities
+
+- `createInitialFieldState`
+- `validateForm`
+- `logValidationIssues`
 
 ## When To Use Individual Packages
 
-- Use `@formspec/build` directly for `generateSchemas()` and static TypeScript analysis.
+- Use `@formspec/build` directly for `generateSchemas()`, `generateSchemasFromClass()`, `generateSchemasFromProgram()`, `buildMixedAuthoringSchemas()`, and static TypeScript analysis.
 - Use `@formspec/eslint-plugin` for lint rules.
 - Use `@formspec/cli` for build-time artifact generation from files.
 - Use `@formspec/validator` for runtime JSON Schema validation.
 
 ## License
 
-UNLICENSED
+This package is part of the FormSpec monorepo and is released under the MIT License. See [LICENSE](./LICENSE) for details.

package/dist/formspec-alpha.d.ts

@@ -80,6 +80,10 @@ export declare interface ArrayField<N extends string, Items extends readonly For
     readonly items: Items;
     /** Display label for the field */
     readonly label?: string;
+    /** Canonical display name for the field. Alias of `label` in the chain DSL. */
+    readonly displayName?: string;
+    /** JSON-facing serialized name for the field. */
+    readonly apiName?: string;
     /** Whether this field is required for form submission */
     readonly required?: boolean;
     /** Minimum number of items required */
@@ -104,6 +108,10 @@ export declare interface BooleanField<N extends string> {
     readonly name: N;
     /** Display label for the field */
     readonly label?: string;
+    /** Canonical display name for the field. Alias of `label` in the chain DSL. */
+    readonly displayName?: string;
+    /** JSON-facing serialized name for the field. */
+    readonly apiName?: string;
     /** Whether this field is required for form submission */
     readonly required?: boolean;
 }
@@ -123,7 +131,8 @@ export declare function buildFormSchemas<E extends readonly FormElement[]>(form:
  *
  * @public
  */
-export declare type BuildFormSchemasOptions = GenerateJsonSchemaOptions;
+export declare interface BuildFormSchemasOptions extends GenerateJsonSchemaOptions, GenerateUiSchemaOptions {
+}
 
 /**
  * Result of building form schemas.
@@ -283,6 +292,18 @@ export declare type DataSourceValueType<Source extends string> = Source extends
     id: infer ID;
 } ? ID : string : string;
 
+/**
+ * Per-declaration metadata policy input.
+ *
+ * @public
+ */
+export declare interface DeclarationMetadataPolicyInput {
+    /** Policy for JSON-facing serialized names. */
+    readonly apiName?: MetadataValuePolicyInput | undefined;
+    /** Policy for human-facing labels and titles. */
+    readonly displayName?: MetadataValuePolicyInput | undefined;
+}
+
 /**
  * Defines resolvers for a form's dynamic data sources.
  *
@@ -309,6 +330,10 @@ export declare interface DynamicEnumField<N extends string, Source extends strin
     readonly source: Source;
     /** Display label for the field */
     readonly label?: string;
+    /** Canonical display name for the field. Alias of `label` in the chain DSL. */
+    readonly displayName?: string;
+    /** JSON-facing serialized name for the field. */
+    readonly apiName?: string;
     /** Whether this field is required for form submission */
     readonly required?: boolean;
     /** Field names whose values are needed to fetch options */
@@ -333,6 +358,10 @@ export declare interface DynamicSchemaField<N extends string> {
     readonly schemaSource: string;
     /** Display label for the field */
     readonly label?: string;
+    /** Canonical display name for the field. Alias of `label` in the chain DSL. */
+    readonly displayName?: string;
+    /** JSON-facing serialized name for the field. */
+    readonly apiName?: string;
     /** Whether this field is required for form submission */
     readonly required?: boolean;
     /** Field names whose values are needed to configure the schema */
@@ -611,6 +640,8 @@ export declare interface GenerateJsonSchemaOptions {
      * @defaultValue "x-formspec"
      */
     readonly vendorPrefix?: string | undefined;
+    /** Metadata resolution policy for chain DSL generation. */
+    readonly metadata?: MetadataPolicyInput | undefined;
 }
 
 /**
@@ -618,7 +649,17 @@ export declare interface GenerateJsonSchemaOptions {
  *
  * @public
  */
-export declare function generateUiSchema<E extends readonly FormElement[]>(form: FormSpec<E>): UISchema;
+export declare function generateUiSchema<E extends readonly FormElement[]>(form: FormSpec<E>, options?: GenerateUiSchemaOptions): UISchema;
+
+/**
+ * Options for generating a UI Schema from a Chain DSL form.
+ *
+ * @public
+ */
+export declare interface GenerateUiSchemaOptions {
+    /** Metadata resolution policy for chain DSL UI generation. */
+    readonly metadata?: MetadataPolicyInput | undefined;
+}
 
 /**
  * A visual grouping of form elements.
@@ -887,6 +928,180 @@ export declare interface LabelElement {
  */
 export declare function logValidationIssues(result: ValidationResult, formName?: string): void;
 
+/**
+ * Authoring surfaces that can contribute metadata.
+ *
+ * @public
+ */
+export declare type MetadataAuthoringSurface = "tsdoc" | "chain-dsl";
+
+/**
+ * Declaration categories that metadata policy can target.
+ *
+ * @public
+ */
+export declare type MetadataDeclarationKind = "type" | "field" | "method";
+
+/**
+ * Build-facing context passed to metadata inference callbacks.
+ *
+ * `buildContext` is intentionally opaque so browser/runtime packages do not
+ * need to depend on TypeScript compiler types.
+ *
+ * @public
+ */
+export declare interface MetadataInferenceContext {
+    /** Authoring surface the metadata is being resolved for. */
+    readonly surface: MetadataAuthoringSurface;
+    /** Declaration kind currently being resolved. */
+    readonly declarationKind: MetadataDeclarationKind;
+    /** Logical identifier before any metadata policy is applied. */
+    readonly logicalName: string;
+    /** Optional build-only context supplied by the resolver. */
+    readonly buildContext?: unknown;
+}
+
+/**
+ * Callback used to infer a scalar metadata value.
+ *
+ * @public
+ */
+export declare type MetadataInferenceFn = (context: MetadataInferenceContext) => string;
+
+/**
+ * Context passed to pluralization callbacks.
+ *
+ * @public
+ */
+export declare interface MetadataPluralizationContext extends MetadataInferenceContext {
+    /** Singular value that pluralization should derive from. */
+    readonly singular: string;
+}
+
+/**
+ * Pluralization disabled.
+ *
+ * @public
+ */
+export declare interface MetadataPluralizationDisabledPolicyInput {
+    /** Disables automatic plural-value generation. */
+    readonly mode?: "disabled" | undefined;
+}
+
+/**
+ * Callback used to derive plural metadata from a singular value.
+ *
+ * @public
+ */
+export declare type MetadataPluralizationFn = (context: MetadataPluralizationContext) => string;
+
+/**
+ * Pluralization may be inferred when absent.
+ *
+ * @public
+ */
+export declare interface MetadataPluralizationInferIfMissingPolicyInput {
+    /** Infers plural values whenever no explicit plural is present. */
+    readonly mode: "infer-if-missing";
+    /** Callback that derives a plural form from the resolved singular value. */
+    readonly inflect: MetadataPluralizationFn;
+}
+
+/**
+ * Pluralization policy input.
+ *
+ * @public
+ */
+export declare type MetadataPluralizationPolicyInput = MetadataPluralizationDisabledPolicyInput | MetadataPluralizationRequireExplicitPolicyInput | MetadataPluralizationInferIfMissingPolicyInput;
+
+/**
+ * Pluralization must be authored explicitly.
+ *
+ * @public
+ */
+export declare interface MetadataPluralizationRequireExplicitPolicyInput {
+    /** Requires plural values to be authored directly. */
+    readonly mode: "require-explicit";
+}
+
+/**
+ * User-facing metadata policy configuration.
+ *
+ * @public
+ */
+export declare interface MetadataPolicyInput {
+    /** Policy applied to named types and the analyzed root declaration. */
+    readonly type?: DeclarationMetadataPolicyInput | undefined;
+    /** Policy applied to fields and object properties. */
+    readonly field?: DeclarationMetadataPolicyInput | undefined;
+    /** Policy applied to callable/method declarations. */
+    readonly method?: DeclarationMetadataPolicyInput | undefined;
+}
+
+/**
+ * Scalar metadata resolution modes.
+ *
+ * @public
+ */
+export declare type MetadataResolutionMode = "disabled" | "require-explicit" | "infer-if-missing";
+
+/**
+ * Shared metadata model and policy types.
+ *
+ * @public
+ */
+/**
+ * Whether a resolved metadata value was authored directly or inferred by policy.
+ *
+ * @public
+ */
+export declare type MetadataSource = "explicit" | "inferred";
+
+/**
+ * Scalar metadata disabled unless provided explicitly elsewhere.
+ *
+ * @public
+ */
+export declare interface MetadataValueDisabledPolicyInput {
+    /** Disables inference for this scalar metadata value. */
+    readonly mode?: "disabled" | undefined;
+    /** Optional policy controlling plural forms of this scalar value. */
+    readonly pluralization?: MetadataPluralizationPolicyInput | undefined;
+}
+
+/**
+ * Scalar metadata may be inferred when missing.
+ *
+ * @public
+ */
+export declare interface MetadataValueInferIfMissingPolicyInput {
+    /** Infers this scalar metadata value when it is not authored explicitly. */
+    readonly mode: "infer-if-missing";
+    /** Callback used to infer the missing singular value. */
+    readonly infer: MetadataInferenceFn;
+    /** Optional policy controlling plural forms of this scalar value. */
+    readonly pluralization?: MetadataPluralizationPolicyInput | undefined;
+}
+
+/**
+ * Scalar metadata policy input.
+ *
+ * @public
+ */
+export declare type MetadataValuePolicyInput = MetadataValueDisabledPolicyInput | MetadataValueRequireExplicitPolicyInput | MetadataValueInferIfMissingPolicyInput;
+
+/**
+ * Scalar metadata must be authored explicitly.
+ *
+ * @public
+ */
+export declare interface MetadataValueRequireExplicitPolicyInput {
+    /** Requires this scalar metadata value to be authored directly. */
+    readonly mode: "require-explicit";
+    /** Optional policy controlling plural forms of this scalar value. */
+    readonly pluralization?: MetadataPluralizationPolicyInput | undefined;
+}
+
 /**
  * A numeric input field.
  *
@@ -903,6 +1118,10 @@ export declare interface NumberField<N extends string> {
     readonly name: N;
     /** Display label for the field */
     readonly label?: string;
+    /** Canonical display name for the field. Alias of `label` in the chain DSL. */
+    readonly displayName?: string;
+    /** JSON-facing serialized name for the field. */
+    readonly apiName?: string;
     /** Minimum allowed value */
     readonly min?: number;
     /** Maximum allowed value */
@@ -934,6 +1153,10 @@ export declare interface ObjectField<N extends string, Properties extends readon
     readonly properties: Properties;
     /** Display label for the field */
     readonly label?: string;
+    /** Canonical display name for the field. Alias of `label` in the chain DSL. */
+    readonly displayName?: string;
+    /** JSON-facing serialized name for the field. */
+    readonly apiName?: string;
     /** Whether this field is required for form submission */
     readonly required?: boolean;
 }
@@ -950,6 +1173,35 @@ export declare interface ObjectField<N extends string, Properties extends readon
  */
 export declare type Predicate<K extends string = string, V = unknown> = EqualsPredicate<K, V>;
 
+/**
+ * Shared resolved metadata model carried through canonicalization and
+ * generation.
+ *
+ * @public
+ */
+export declare interface ResolvedMetadata {
+    /** Effective JSON-facing singular name. */
+    readonly apiName?: ResolvedScalarMetadata;
+    /** Effective human-facing singular label. */
+    readonly displayName?: ResolvedScalarMetadata;
+    /** Effective JSON-facing plural name, where applicable. */
+    readonly apiNamePlural?: ResolvedScalarMetadata;
+    /** Effective human-facing plural label, where applicable. */
+    readonly displayNamePlural?: ResolvedScalarMetadata;
+}
+
+/**
+ * A single resolved scalar metadata value plus its provenance.
+ *
+ * @public
+ */
+export declare interface ResolvedScalarMetadata {
+    /** Effective metadata value after policy resolution. */
+    readonly value: string;
+    /** Whether the value came from author intent or inference. */
+    readonly source: MetadataSource;
+}
+
 /**
  * A resolver function that fetches options for a data source.
  *
@@ -1088,6 +1340,10 @@ export declare interface StaticEnumField<N extends string, O extends readonly En
     readonly options: O;
     /** Display label for the field */
     readonly label?: string;
+    /** Canonical display name for the field. Alias of `label` in the chain DSL. */
+    readonly displayName?: string;
+    /** JSON-facing serialized name for the field. */
+    readonly apiName?: string;
     /** Whether this field is required for form submission */
     readonly required?: boolean;
 }
@@ -1114,6 +1370,10 @@ export declare interface TextField<N extends string> {
     readonly name: N;
     /** Display label for the field */
     readonly label?: string;
+    /** Canonical display name for the field. Alias of `label` in the chain DSL. */
+    readonly displayName?: string;
+    /** JSON-facing serialized name for the field. */
+    readonly apiName?: string;
     /** Placeholder text shown when field is empty */
     readonly placeholder?: string;
     /** Whether this field is required for form submission */