@formspec/dsl 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/dsl.d.ts

@@ -0,0 +1,665 @@
+/**
+ * `@formspec/dsl` - DSL functions for defining FormSpec forms
+ *
+ * This package provides the builder functions for creating form specifications:
+ * - `field.*` - Field builders (text, number, boolean, enum, dynamicEnum)
+ * - `group()` - Visual grouping
+ * - `when()` + `is()` - Conditional visibility
+ * - `formspec()` - Top-level form definition
+ *
+ * @example
+ * ```typescript
+ * import { formspec, field, group, when, is } from "@formspec/dsl";
+ *
+ * const InvoiceForm = formspec(
+ *   group("Customer",
+ *     field.text("customerName", { label: "Customer Name" }),
+ *     field.dynamicEnum("country", "fetch_countries", { label: "Country" }),
+ *   ),
+ *   group("Invoice Details",
+ *     field.number("amount", { label: "Amount", min: 0 }),
+ *     field.enum("status", ["draft", "sent", "paid"] as const),
+ *     when(is("status", "draft"),
+ *       field.text("internalNotes", { label: "Internal Notes" }),
+ *     ),
+ *   ),
+ * );
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import type { AnyField } from '@formspec/core';
+import type { ArrayField } from '@formspec/core';
+import type { BooleanField } from '@formspec/core';
+import type { Conditional } from '@formspec/core';
+import type { DataSourceValueType } from '@formspec/core';
+import type { DynamicEnumField } from '@formspec/core';
+import type { DynamicSchemaField } from '@formspec/core';
+import { EnumOption } from '@formspec/core';
+import { EnumOptionValue } from '@formspec/core';
+import type { EqualsPredicate } from '@formspec/core';
+import type { FormElement } from '@formspec/core';
+import type { FormSpec } from '@formspec/core';
+import type { Group } from '@formspec/core';
+import type { NumberField } from '@formspec/core';
+import type { ObjectField } from '@formspec/core';
+import type { Predicate } from '@formspec/core';
+import type { StaticEnumField } from '@formspec/core';
+import type { TextField } from '@formspec/core';
+
+/**
+ * Builds a schema type from extracted fields.
+ *
+ * Maps field names to their inferred value types.
+ *
+ * @public
+ */
+export declare type BuildSchema<Fields> = {
+    [F in Fields as F extends {
+        name: infer N extends string;
+    } ? N : never]: F extends AnyField ? InferFieldValue<F> : never;
+};
+
+export { EnumOption }
+
+export { EnumOptionValue }
+
+/**
+ * Extracts fields that ARE inside conditionals.
+ * These fields may or may not be visible and should be optional in the inferred schema.
+ *
+ * @example
+ * ```typescript
+ * // Given a form with conditional fields:
+ * const form = formspec(
+ *   field.text("name"),           // non-conditional (skipped)
+ *   when(is("type", "business"),
+ *     field.text("company"),      // conditional (extracted)
+ *     field.text("taxId"),        // conditional (extracted)
+ *   ),
+ * );
+ *
+ * // ExtractConditionalFields extracts: TextField<"company"> | TextField<"taxId">
+ * ```
+ *
+ * @public
+ */
+export declare type ExtractConditionalFields<E> = E extends AnyField ? never : E extends Group<infer Elements> ? ExtractConditionalFieldsFromArray<Elements> : E extends Conditional<string, unknown, infer Elements> ? ExtractFieldsFromArray<Elements> : never;
+
+/**
+ * Extracts conditional fields from an array of elements.
+ *
+ * @example
+ * ```typescript
+ * type Elements = readonly [
+ *   TextField<"name">,
+ *   Conditional<"type", "business", readonly [TextField<"company">]>
+ * ];
+ * type Fields = ExtractConditionalFieldsFromArray<Elements>;
+ * // TextField<"company">
+ * ```
+ *
+ * @public
+ */
+export declare type ExtractConditionalFieldsFromArray<Elements> = Elements extends readonly [
+infer First,
+...infer Rest
+] ? ExtractConditionalFields<First> | ExtractConditionalFieldsFromArray<Rest> : never;
+
+/**
+ * Extracts all fields from a single element (recursively).
+ *
+ * - Field elements return themselves
+ * - Groups extract fields from all child elements
+ * - Conditionals extract fields from all child elements
+ *
+ * @public
+ */
+export declare type ExtractFields<E> = E extends AnyField ? E : E extends Group<infer Elements> ? ExtractFieldsFromArray<Elements> : E extends Conditional<string, unknown, infer Elements> ? ExtractFieldsFromArray<Elements> : never;
+
+/**
+ * Extracts fields from an array of elements.
+ *
+ * Recursively processes each element and unions the results.
+ *
+ * @public
+ */
+export declare type ExtractFieldsFromArray<Elements> = Elements extends readonly [
+infer First,
+...infer Rest
+] ? ExtractFields<First> | ExtractFieldsFromArray<Rest> : never;
+
+/**
+ * Extracts fields that are NOT inside conditionals.
+ * These fields are always visible and should be required in the inferred schema.
+ *
+ * @example
+ * ```typescript
+ * // Given a form with conditional and non-conditional fields:
+ * const form = formspec(
+ *   field.text("name"),           // non-conditional
+ *   field.number("age"),          // non-conditional
+ *   when(is("type", "business"),
+ *     field.text("company"),      // conditional (skipped)
+ *   ),
+ * );
+ *
+ * // ExtractNonConditionalFields extracts: TextField<"name"> | NumberField<"age">
+ * ```
+ *
+ * @public
+ */
+export declare type ExtractNonConditionalFields<E> = E extends AnyField ? E : E extends Group<infer Elements> ? ExtractNonConditionalFieldsFromArray<Elements> : E extends Conditional<string, unknown, infer _Elements> ? never : never;
+
+/**
+ * Extracts non-conditional fields from an array of elements.
+ *
+ * @example
+ * ```typescript
+ * type Elements = readonly [TextField<"name">, NumberField<"age">];
+ * type Fields = ExtractNonConditionalFieldsFromArray<Elements>;
+ * // TextField<"name"> | NumberField<"age">
+ * ```
+ *
+ * @public
+ */
+export declare type ExtractNonConditionalFieldsFromArray<Elements> = Elements extends readonly [
+infer First,
+...infer Rest
+] ? ExtractNonConditionalFields<First> | ExtractNonConditionalFieldsFromArray<Rest> : never;
+
+/**
+ * Field builder namespace containing functions to create each field type.
+ *
+ * @example
+ * ```typescript
+ * import { field } from "@formspec/dsl";
+ *
+ * field.text("name", { label: "Full Name" });
+ * field.number("age", { min: 0, max: 150 });
+ * field.enum("status", ["draft", "sent", "paid"]);
+ * field.dynamicEnum("country", "countries", { label: "Country" });
+ * ```
+ *
+ * @public
+ */
+export declare const field: {
+    /**
+     * Creates a text input field.
+     *
+     * @param name - The field name (used as the schema key)
+     * @param config - Optional configuration for label, placeholder, etc.
+     * @returns A TextField descriptor
+     */
+    text: <const N extends string>(name: N, config?: Omit<TextField<N>, "_type" | "_field" | "name">) => TextField<N>;
+    /**
+     * Creates a numeric input field.
+     *
+     * @param name - The field name (used as the schema key)
+     * @param config - Optional configuration for label, min, max, etc.
+     * @returns A NumberField descriptor
+     */
+    number: <const N extends string>(name: N, config?: Omit<NumberField<N>, "_type" | "_field" | "name">) => NumberField<N>;
+    /**
+     * Creates a boolean checkbox field.
+     *
+     * @param name - The field name (used as the schema key)
+     * @param config - Optional configuration for label, etc.
+     * @returns A BooleanField descriptor
+     */
+    boolean: <const N extends string>(name: N, config?: Omit<BooleanField<N>, "_type" | "_field" | "name">) => BooleanField<N>;
+    /**
+     * Creates a field with static enum options (known at compile time).
+     *
+     * Literal types are automatically inferred - no `as const` needed:
+     * ```typescript
+     * field.enum("status", ["draft", "sent", "paid"])
+     * // Schema type: "draft" | "sent" | "paid"
+     * ```
+     *
+     * Options can be strings or objects with `id` and `label`:
+     * ```typescript
+     * field.enum("priority", [
+     *   { id: "low", label: "Low Priority" },
+     *   { id: "high", label: "High Priority" },
+     * ])
+     * ```
+     *
+     * **Note:** All options must be of the same type (all strings OR all objects).
+     * Mixing strings and objects will throw a runtime error.
+     *
+     * @param name - The field name (used as the schema key)
+     * @param options - Array of allowed string values or objects with `id` and `label` properties
+     * @param config - Optional configuration for label, etc.
+     * @returns A StaticEnumField descriptor
+     * @throws Error if options array contains mixed types (strings and objects)
+     */
+    enum: <const N extends string, const O extends readonly EnumOptionValue[]>(name: N, options: O, config?: Omit<StaticEnumField<N, O>, "_type" | "_field" | "name" | "options">) => StaticEnumField<N, O>;
+    /**
+     * Creates a field with dynamic enum options (fetched from a data source at runtime).
+     *
+     * The data source must be registered in DataSourceRegistry via module augmentation:
+     * ```typescript
+     * declare module "@formspec/core" {
+     *   interface DataSourceRegistry {
+     *     countries: { id: string; code: string; name: string };
+     *   }
+     * }
+     *
+     * field.dynamicEnum("country", "countries", { label: "Country" })
+     * ```
+     *
+     * @param name - The field name (used as the schema key)
+     * @param source - The data source key (must be in DataSourceRegistry)
+     * @param config - Optional configuration for label, params, etc.
+     * @returns A DynamicEnumField descriptor
+     */
+    dynamicEnum: <const N extends string, const Source extends string>(name: N, source: Source, config?: Omit<DynamicEnumField<N, Source>, "_type" | "_field" | "name" | "source">) => DynamicEnumField<N, Source>;
+    /**
+     * Creates a field that loads its schema dynamically (e.g., from an extension).
+     *
+     * @param name - The field name (used as the schema key)
+     * @param schemaSource - Identifier for the schema source
+     * @param config - Optional configuration for label, etc.
+     * @returns A DynamicSchemaField descriptor
+     */
+    dynamicSchema: <const N extends string>(name: N, schemaSource: string, config?: Omit<DynamicSchemaField<N>, "_type" | "_field" | "name" | "schemaSource">) => DynamicSchemaField<N>;
+    /**
+     * Creates an array field containing repeating items.
+     *
+     * Use this for lists of values (e.g., multiple addresses, line items).
+     *
+     * @example
+     * ```typescript
+     * field.array("addresses",
+     *   field.text("street", { label: "Street" }),
+     *   field.text("city", { label: "City" }),
+     *   field.text("zip", { label: "ZIP Code" }),
+     * )
+     * ```
+     *
+     * @param name - The field name (used as the schema key)
+     * @param items - The form elements that define each array item
+     * @returns An ArrayField descriptor
+     */
+    array: <const N extends string, const Items extends readonly FormElement[]>(name: N, ...items: Items) => ArrayField<N, Items>;
+    /**
+     * Creates an array field with additional configuration options.
+     *
+     * @example
+     * ```typescript
+     * field.arrayWithConfig("lineItems", {
+     *   label: "Line Items",
+     *   minItems: 1,
+     *   maxItems: 10,
+     * },
+     *   field.text("description"),
+     *   field.number("quantity"),
+     * )
+     * ```
+     *
+     * @param name - The field name (used as the schema key)
+     * @param config - Configuration for label, minItems, maxItems, etc.
+     * @param items - The form elements that define each array item
+     * @returns An ArrayField descriptor
+     */
+    arrayWithConfig: <const N extends string, const Items extends readonly FormElement[]>(name: N, config: Omit<ArrayField<N, Items>, "_type" | "_field" | "name" | "items">, ...items: Items) => ArrayField<N, Items>;
+    /**
+     * Creates an object field containing nested properties.
+     *
+     * Use this for grouping related fields under a single key in the schema.
+     *
+     * @example
+     * ```typescript
+     * field.object("address",
+     *   field.text("street", { label: "Street" }),
+     *   field.text("city", { label: "City" }),
+     *   field.text("zip", { label: "ZIP Code" }),
+     * )
+     * ```
+     *
+     * @param name - The field name (used as the schema key)
+     * @param properties - The form elements that define the object's properties
+     * @returns An ObjectField descriptor
+     */
+    object: <const N extends string, const Properties extends readonly FormElement[]>(name: N, ...properties: Properties) => ObjectField<N, Properties>;
+    /**
+     * Creates an object field with additional configuration options.
+     *
+     * @example
+     * ```typescript
+     * field.objectWithConfig("billingAddress", { label: "Billing Address", required: true },
+     *   field.text("street"),
+     *   field.text("city"),
+     * )
+     * ```
+     *
+     * @param name - The field name (used as the schema key)
+     * @param config - Configuration for label, required, etc.
+     * @param properties - The form elements that define the object's properties
+     * @returns An ObjectField descriptor
+     */
+    objectWithConfig: <const N extends string, const Properties extends readonly FormElement[]>(name: N, config: Omit<ObjectField<N, Properties>, "_type" | "_field" | "name" | "properties">, ...properties: Properties) => ObjectField<N, Properties>;
+};
+
+/**
+ * Utility type that flattens intersection types into a single object type.
+ *
+ * This improves TypeScript's display of inferred types and ensures
+ * structural equality checks work correctly.
+ *
+ * @example
+ * ```typescript
+ * // Without FlattenIntersection:
+ * type Messy = { a: string } & { b: number };
+ * // Displays as: { a: string } & { b: number }
+ *
+ * // With FlattenIntersection:
+ * type Clean = FlattenIntersection<{ a: string } & { b: number }>;
+ * // Displays as: { a: string; b: number }
+ * ```
+ *
+ * @public
+ */
+export declare type FlattenIntersection<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+/**
+ * Creates a complete form specification.
+ *
+ * The structure IS the definition:
+ * - Nesting with `group()` defines visual layout
+ * - Nesting with `when()` defines conditional visibility
+ * - Field type implies control type (text field → text input)
+ * - Array position implies field ordering
+ *
+ * Schema is automatically inferred from all fields in the structure.
+ *
+ * @example
+ * ```typescript
+ * const InvoiceForm = formspec(
+ *   group("Customer",
+ *     field.text("customerName", { label: "Customer Name" }),
+ *     field.dynamicEnum("country", "fetch_countries", { label: "Country" }),
+ *   ),
+ *   group("Invoice Details",
+ *     field.number("amount", { label: "Amount", min: 0 }),
+ *     field.enum("status", ["draft", "sent", "paid"] as const),
+ *     when(is("status", "draft"),
+ *       field.text("internalNotes", { label: "Internal Notes" }),
+ *     ),
+ *   ),
+ * );
+ * ```
+ *
+ * @param elements - The top-level form elements
+ * @returns A FormSpec descriptor
+ *
+ * @public
+ */
+export declare function formspec<const Elements extends readonly FormElement[]>(...elements: Elements): FormSpec<Elements>;
+
+/**
+ * Options for creating a form specification.
+ *
+ * @public
+ */
+export declare interface FormSpecOptions {
+    /**
+     * Whether to validate the form structure.
+     * - `true` or `"warn"`: Validate and log warnings/errors to console
+     * - `"throw"`: Validate and throw an error if validation fails
+     * - `false`: Skip validation (default in production for performance)
+     *
+     * @defaultValue false
+     */
+    validate?: boolean | "warn" | "throw";
+    /**
+     * Optional name for the form (used in validation messages).
+     */
+    name?: string;
+}
+
+/**
+ * Creates a complete form specification with validation options.
+ *
+ * @example
+ * ```typescript
+ * const form = formspecWithValidation(
+ *   { validate: true, name: "MyForm" },
+ *   field.text("name"),
+ *   field.enum("status", ["draft", "sent"] as const),
+ *   when(is("status", "draft"),
+ *     field.text("notes"),
+ *   ),
+ * );
+ * ```
+ *
+ * @param options - Validation options
+ * @param elements - The top-level form elements
+ * @returns A FormSpec descriptor
+ *
+ * @public
+ */
+export declare function formspecWithValidation<const Elements extends readonly FormElement[]>(options: FormSpecOptions, ...elements: Elements): FormSpec<Elements>;
+
+/**
+ * Creates a visual group of form elements.
+ *
+ * Groups provide visual organization and can be rendered as fieldsets or sections.
+ * The nesting of groups defines the visual hierarchy of the form.
+ *
+ * @example
+ * ```typescript
+ * group("Customer Information",
+ *   field.text("name", { label: "Name" }),
+ *   field.text("email", { label: "Email" }),
+ * )
+ * ```
+ *
+ * @param label - The group's display label
+ * @param elements - The form elements contained in this group
+ * @returns A Group descriptor
+ *
+ * @public
+ */
+export declare function group<const Elements extends readonly FormElement[]>(label: string, ...elements: Elements): Group<Elements>;
+
+/**
+ * Infers the value type from a single field.
+ *
+ * - TextField returns string
+ * - NumberField returns number
+ * - BooleanField returns boolean
+ * - StaticEnumField returns union of option literals
+ * - DynamicEnumField returns DataSourceValueType (usually string)
+ * - DynamicSchemaField returns Record of string to unknown
+ * - ArrayField returns array of inferred item schema
+ * - ObjectField returns object of inferred property schema
+ *
+ * @example
+ * ```typescript
+ * // Simple fields
+ * type T1 = InferFieldValue<TextField<"name">>; // string
+ * type T2 = InferFieldValue<NumberField<"age">>; // number
+ *
+ * // Enum fields
+ * type T3 = InferFieldValue<StaticEnumField<"status", ["draft", "sent"]>>; // "draft" | "sent"
+ *
+ * // Nested fields
+ * type T4 = InferFieldValue<ArrayField<"items", [TextField<"name">]>>; // { name: string }[]
+ * type T5 = InferFieldValue<ObjectField<"address", [TextField<"city">]>>; // { city: string }
+ * ```
+ *
+ * @public
+ */
+export declare type InferFieldValue<F> = F extends TextField<string> ? string : F extends NumberField<string> ? number : F extends BooleanField<string> ? boolean : F extends StaticEnumField<string, infer O extends readonly EnumOptionValue[]> ? O extends readonly EnumOption[] ? O[number]["id"] : O extends readonly string[] ? O[number] : never : F extends DynamicEnumField<string, infer Source> ? DataSourceValueType<Source> : F extends DynamicSchemaField<string> ? Record<string, unknown> : F extends ArrayField<string, infer Items extends readonly FormElement[]> ? InferSchema<Items>[] : F extends ObjectField<string, infer Properties extends readonly FormElement[]> ? InferSchema<Properties> : never;
+
+/**
+ * Infers the schema type from a FormSpec.
+ *
+ * Convenience type that extracts elements and infers the schema.
+ *
+ * @example
+ * ```typescript
+ * const form = formspec(...);
+ * type Schema = InferFormSchema<typeof form>;
+ * ```
+ *
+ * @public
+ */
+export declare type InferFormSchema<F extends FormSpec<readonly FormElement[]>> = F extends FormSpec<infer Elements> ? InferSchema<Elements> : never;
+
+/**
+ * Infers the complete schema type from a form's elements.
+ *
+ * This is the main inference type that converts a form structure
+ * into its corresponding TypeScript schema type.
+ *
+ * Non-conditional fields are required, conditional fields are optional.
+ *
+ * @example
+ * ```typescript
+ * const form = formspec(
+ *   field.text("name"),
+ *   field.number("age"),
+ *   field.enum("status", ["active", "inactive"] as const),
+ * );
+ *
+ * type Schema = InferSchema<typeof form.elements>;
+ * // { name: string; age: number; status: "active" | "inactive" }
+ *
+ * // Conditional fields become optional:
+ * const formWithConditional = formspec(
+ *   field.enum("type", ["a", "b"] as const),
+ *   when(is("type", "a"), field.text("aField")),
+ * );
+ * type ConditionalSchema = InferSchema<typeof formWithConditional.elements>;
+ * // { type: "a" | "b"; aField?: string }
+ * ```
+ *
+ * @public
+ */
+export declare type InferSchema<Elements extends readonly FormElement[]> = FlattenIntersection<BuildSchema<ExtractNonConditionalFieldsFromArray<Elements>> & Partial<BuildSchema<ExtractConditionalFieldsFromArray<Elements>>>>;
+
+/**
+ * Creates an equality predicate that checks if a field equals a specific value.
+ *
+ * Use this with `when()` to create readable conditional expressions:
+ *
+ * @example
+ * ```typescript
+ * // Show cardNumber field when paymentMethod is "card"
+ * when(is("paymentMethod", "card"),
+ *   field.text("cardNumber", { label: "Card Number" }),
+ * )
+ * ```
+ *
+ * @typeParam K - The field name (inferred as string literal)
+ * @typeParam V - The value type (inferred as literal)
+ * @param field - The name of the field to check
+ * @param value - The value the field must equal
+ * @returns An EqualsPredicate for use with `when()`
+ * @public
+ */
+export declare function is<const K extends string, const V>(field: K, value: V): EqualsPredicate<K, V>;
+
+/**
+ * Logs validation issues to the console.
+ *
+ * @param result - The validation result to log
+ * @param formName - Optional name for the form (for better error messages)
+ *
+ * @public
+ */
+export declare function logValidationIssues(result: ValidationResult, formName?: string): void;
+
+/**
+ * Validates a form specification for common issues.
+ *
+ * Checks for:
+ * - Duplicate field names at the root level (warning)
+ * - References to non-existent fields in conditionals (error)
+ *
+ * @example
+ * ```typescript
+ * const form = formspec(
+ *   field.text("name"),
+ *   field.text("name"), // Duplicate!
+ *   when("nonExistent", "value", // Reference to non-existent field!
+ *     field.text("extra"),
+ *   ),
+ * );
+ *
+ * const result = validateForm(form.elements);
+ * // result.valid === false
+ * // result.issues contains duplicate and reference errors
+ * ```
+ *
+ * @param elements - The form elements to validate
+ * @returns Validation result with any issues found
+ *
+ * @public
+ */
+export declare function validateForm(elements: readonly FormElement[]): ValidationResult;
+
+/**
+ * A validation issue found in a form specification.
+ *
+ * @public
+ */
+export declare interface ValidationIssue {
+    /** Severity of the issue */
+    severity: ValidationSeverity;
+    /** Human-readable message describing the issue */
+    message: string;
+    /** Path to the element with the issue (e.g., "group.fieldName") */
+    path: string;
+}
+
+/**
+ * Result of validating a form specification.
+ *
+ * @public
+ */
+export declare interface ValidationResult {
+    /** Whether the form is valid (no errors, warnings are ok) */
+    valid: boolean;
+    /** List of validation issues found */
+    issues: ValidationIssue[];
+}
+
+/**
+ * Validation issue severity levels.
+ *
+ * @public
+ */
+export declare type ValidationSeverity = "error" | "warning";
+
+/**
+ * Creates a conditional wrapper that shows elements based on a predicate.
+ *
+ * When the predicate evaluates to true, the contained elements are shown.
+ * Otherwise, they are hidden (but still part of the schema).
+ *
+ * @example
+ * ```typescript
+ * import { is } from "@formspec/dsl";
+ *
+ * field.enum("status", ["draft", "sent", "paid"] as const),
+ * when(is("status", "draft"),
+ *   field.text("internalNotes", { label: "Internal Notes" }),
+ * )
+ * ```
+ *
+ * @param predicate - The condition to evaluate (use `is()` to create)
+ * @param elements - The form elements to show when condition is met
+ * @returns A Conditional descriptor
+ *
+ * @public
+ */
+export declare function when<const K extends string, const V, const Elements extends readonly FormElement[]>(predicate: Predicate<K, V>, ...elements: Elements): Conditional<K, V, Elements>;
+
+export { }

package/dist/field.d.ts

@@ -17,6 +17,8 @@ import type { TextField, NumberField, BooleanField, StaticEnumField, EnumOptionV
  * field.enum("status", ["draft", "sent", "paid"]);
  * field.dynamicEnum("country", "countries", { label: "Country" });
  * ```
+ *
+ * @public
  */
 export declare const field: {
     /**
@@ -52,10 +54,22 @@ export declare const field: {
      * // Schema type: "draft" | "sent" | "paid"
      * ```
      *
+     * Options can be strings or objects with `id` and `label`:
+     * ```typescript
+     * field.enum("priority", [
+     *   { id: "low", label: "Low Priority" },
+     *   { id: "high", label: "High Priority" },
+     * ])
+     * ```
+     *
+     * **Note:** All options must be of the same type (all strings OR all objects).
+     * Mixing strings and objects will throw a runtime error.
+     *
      * @param name - The field name (used as the schema key)
-     * @param options - Array of allowed string values
+     * @param options - Array of allowed string values or objects with `id` and `label` properties
      * @param config - Optional configuration for label, etc.
      * @returns A StaticEnumField descriptor
+     * @throws Error if options array contains mixed types (strings and objects)
      */
     enum: <const N extends string, const O extends readonly EnumOptionValue[]>(name: N, options: O, config?: Omit<StaticEnumField<N, O>, "_type" | "_field" | "name" | "options">) => StaticEnumField<N, O>;
     /**