@formspec/decorators 0.1.0-alpha.3

package/dist/index.js

@@ -0,0 +1,694 @@
+/**
+ * @formspec/decorators
+ *
+ * Decorators for FormSpec form definitions.
+ *
+ * These decorators work in two modes:
+ *
+ * 1. **Build-time (CLI generate)**: The FormSpec CLI reads decorators through
+ *    static analysis and generates JSON Schema + UI Schema files directly.
+ *
+ * 2. **Runtime (with CLI codegen)**: Run `formspec codegen` to generate a type
+ *    metadata file, then use `toFormSpec()` to generate specs at runtime.
+ *
+ * @example
+ * ```typescript
+ * import { Label, Min, Max, EnumOptions, toFormSpec } from '@formspec/decorators';
+ *
+ * class UserForm {
+ *   @Label("Full Name")
+ *   name!: string;
+ *
+ *   @Label("Age")
+ *   @Min(18)
+ *   @Max(120)
+ *   age?: number;
+ *
+ *   @Label("Country")
+ *   @EnumOptions([
+ *     { id: "us", label: "United States" },
+ *     { id: "ca", label: "Canada" }
+ *   ])
+ *   country!: "us" | "ca";
+ * }
+ *
+ * // After running: formspec codegen ./forms.ts -o ./__formspec_types__.ts
+ * // Import the generated file and use toFormSpec:
+ * import './__formspec_types__';
+ * const spec = toFormSpec(UserForm);
+ * ```
+ */
+// =============================================================================
+// Runtime Metadata Storage
+// =============================================================================
+/**
+ * Storage for decorator metadata, keyed by constructor.
+ * This is a regular Map (not WeakMap) since class constructors
+ * live for the lifetime of the application.
+ */
+const decoratorMetadata = new Map();
+/**
+ * Gets or creates the metadata map for a class constructor.
+ */
+function getFieldMetadata(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+ctor, propertyKey) {
+    if (!decoratorMetadata.has(ctor)) {
+        decoratorMetadata.set(ctor, new Map());
+    }
+    const classMetadata = decoratorMetadata.get(ctor);
+    if (!classMetadata.has(propertyKey)) {
+        classMetadata.set(propertyKey, {});
+    }
+    return classMetadata.get(propertyKey);
+}
+// =============================================================================
+// Field Metadata Decorators
+// =============================================================================
+/**
+ * Sets the display label for a field.
+ *
+ * @param text - The label text to display
+ * @example
+ * ```typescript
+ * @Label("Email Address")
+ * email!: string;
+ * ```
+ */
+export function Label(text) {
+    return function (target, propertyKey) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ctor = target.constructor;
+        getFieldMetadata(ctor, propertyKey).label = text;
+    };
+}
+/**
+ * Sets placeholder text for input fields.
+ *
+ * @param text - The placeholder text
+ * @example
+ * ```typescript
+ * @Placeholder("Enter your email...")
+ * email!: string;
+ * ```
+ */
+export function Placeholder(text) {
+    return function (target, propertyKey) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ctor = target.constructor;
+        getFieldMetadata(ctor, propertyKey).placeholder = text;
+    };
+}
+/**
+ * Sets a description or help text for a field.
+ *
+ * @param text - The description text
+ * @example
+ * ```typescript
+ * @Description("We'll never share your email with anyone")
+ * email!: string;
+ * ```
+ */
+export function Description(text) {
+    return function (target, propertyKey) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ctor = target.constructor;
+        getFieldMetadata(ctor, propertyKey).description = text;
+    };
+}
+// =============================================================================
+// Numeric Constraint Decorators
+// =============================================================================
+/**
+ * Sets the minimum allowed value for a numeric field.
+ *
+ * @param value - The minimum value
+ * @example
+ * ```typescript
+ * @Min(0)
+ * quantity!: number;
+ * ```
+ */
+export function Min(value) {
+    return function (target, propertyKey) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ctor = target.constructor;
+        getFieldMetadata(ctor, propertyKey).min = value;
+    };
+}
+/**
+ * Sets the maximum allowed value for a numeric field.
+ *
+ * @param value - The maximum value
+ * @example
+ * ```typescript
+ * @Max(100)
+ * percentage!: number;
+ * ```
+ */
+export function Max(value) {
+    return function (target, propertyKey) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ctor = target.constructor;
+        getFieldMetadata(ctor, propertyKey).max = value;
+    };
+}
+/**
+ * Sets the step increment for a numeric field.
+ *
+ * @param value - The step value
+ * @example
+ * ```typescript
+ * @Step(0.01)
+ * price!: number;
+ * ```
+ */
+export function Step(value) {
+    return function (target, propertyKey) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ctor = target.constructor;
+        getFieldMetadata(ctor, propertyKey).step = value;
+    };
+}
+// =============================================================================
+// String Constraint Decorators
+// =============================================================================
+/**
+ * Sets the minimum length for a string field.
+ *
+ * @param value - The minimum character count
+ * @example
+ * ```typescript
+ * @MinLength(1)
+ * name!: string;
+ * ```
+ */
+export function MinLength(value) {
+    return function (target, propertyKey) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ctor = target.constructor;
+        getFieldMetadata(ctor, propertyKey).minLength = value;
+    };
+}
+/**
+ * Sets the maximum length for a string field.
+ *
+ * @param value - The maximum character count
+ * @example
+ * ```typescript
+ * @MaxLength(255)
+ * bio!: string;
+ * ```
+ */
+export function MaxLength(value) {
+    return function (target, propertyKey) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ctor = target.constructor;
+        getFieldMetadata(ctor, propertyKey).maxLength = value;
+    };
+}
+/**
+ * Sets a regex pattern for string validation.
+ *
+ * @param regex - The regex pattern as a string
+ * @example
+ * ```typescript
+ * @Pattern("^[a-z]+$")
+ * username!: string;
+ * ```
+ */
+export function Pattern(regex) {
+    return function (target, propertyKey) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ctor = target.constructor;
+        getFieldMetadata(ctor, propertyKey).pattern = regex;
+    };
+}
+// =============================================================================
+// Array Constraint Decorators
+// =============================================================================
+/**
+ * Sets the minimum number of items for an array field.
+ *
+ * @param value - The minimum item count
+ * @example
+ * ```typescript
+ * @MinItems(1)
+ * tags!: string[];
+ * ```
+ */
+export function MinItems(value) {
+    return function (target, propertyKey) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ctor = target.constructor;
+        getFieldMetadata(ctor, propertyKey).minItems = value;
+    };
+}
+/**
+ * Sets the maximum number of items for an array field.
+ *
+ * @param value - The maximum item count
+ * @example
+ * ```typescript
+ * @MaxItems(10)
+ * tags!: string[];
+ * ```
+ */
+export function MaxItems(value) {
+    return function (target, propertyKey) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ctor = target.constructor;
+        getFieldMetadata(ctor, propertyKey).maxItems = value;
+    };
+}
+// =============================================================================
+// Enum and Options Decorators
+// =============================================================================
+/**
+ * Provides custom options for enum fields with labels.
+ *
+ * Use this to provide human-readable labels for enum values,
+ * or to customize the order and display of options.
+ *
+ * @param options - Array of option values or {id, label} objects
+ * @example
+ * ```typescript
+ * @EnumOptions([
+ *   { id: "us", label: "United States" },
+ *   { id: "ca", label: "Canada" },
+ *   { id: "uk", label: "United Kingdom" }
+ * ])
+ * country!: "us" | "ca" | "uk";
+ * ```
+ */
+export function EnumOptions(options) {
+    return function (target, propertyKey) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ctor = target.constructor;
+        getFieldMetadata(ctor, propertyKey).options = options;
+    };
+}
+// =============================================================================
+// Conditional and Layout Decorators
+// =============================================================================
+/**
+ * Makes a field conditionally visible based on another field's value.
+ *
+ * @param condition - Object specifying the field and value to match
+ * @example
+ * ```typescript
+ * @ShowWhen({ field: "contactMethod", value: "email" })
+ * emailAddress!: string;
+ *
+ * @ShowWhen({ field: "contactMethod", value: "phone" })
+ * phoneNumber!: string;
+ * ```
+ */
+export function ShowWhen(condition) {
+    return function (target, propertyKey) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ctor = target.constructor;
+        getFieldMetadata(ctor, propertyKey).showWhen = condition;
+    };
+}
+/**
+ * Groups fields together under a named section.
+ *
+ * @param name - The group name
+ * @example
+ * ```typescript
+ * @Group("Personal Information")
+ * @Label("First Name")
+ * firstName!: string;
+ *
+ * @Group("Personal Information")
+ * @Label("Last Name")
+ * lastName!: string;
+ *
+ * @Group("Contact Details")
+ * @Label("Email")
+ * email!: string;
+ * ```
+ */
+export function Group(name) {
+    return function (target, propertyKey) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ctor = target.constructor;
+        getFieldMetadata(ctor, propertyKey).group = name;
+    };
+}
+// =============================================================================
+// Runtime API
+// =============================================================================
+/**
+ * The name of the static property containing type metadata.
+ * This is set by the `formspec codegen` command at build time.
+ */
+const FORMSPEC_TYPES_KEY = "__formspec_types__";
+/**
+ * Maps type metadata type to FormSpec field type.
+ */
+function mapTypeToFieldType(type) {
+    switch (type) {
+        case "string":
+            return "text";
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "enum":
+            return "enum";
+        case "array":
+            return "array";
+        case "object":
+            return "object";
+        default:
+            return "text";
+    }
+}
+/**
+ * Creates a FormSpec field from type and decorator metadata.
+ */
+function createField(fieldName, typeInfo, decoratorInfo) {
+    const field = {
+        _field: mapTypeToFieldType(typeInfo.type),
+        id: fieldName,
+    };
+    // Required if not optional and not nullable
+    if (!typeInfo.optional && !typeInfo.nullable) {
+        field.required = true;
+    }
+    // Apply decorator metadata
+    if (decoratorInfo.label)
+        field.label = decoratorInfo.label;
+    if (decoratorInfo.placeholder)
+        field.placeholder = decoratorInfo.placeholder;
+    if (decoratorInfo.description)
+        field.description = decoratorInfo.description;
+    if (decoratorInfo.min !== undefined)
+        field.min = decoratorInfo.min;
+    if (decoratorInfo.max !== undefined)
+        field.max = decoratorInfo.max;
+    if (decoratorInfo.step !== undefined)
+        field.step = decoratorInfo.step;
+    if (decoratorInfo.minLength !== undefined)
+        field.minLength = decoratorInfo.minLength;
+    if (decoratorInfo.maxLength !== undefined)
+        field.maxLength = decoratorInfo.maxLength;
+    if (decoratorInfo.minItems !== undefined)
+        field.minItems = decoratorInfo.minItems;
+    if (decoratorInfo.maxItems !== undefined)
+        field.maxItems = decoratorInfo.maxItems;
+    if (decoratorInfo.pattern)
+        field.pattern = decoratorInfo.pattern;
+    if (decoratorInfo.showWhen)
+        field.showWhen = decoratorInfo.showWhen;
+    if (decoratorInfo.group)
+        field.group = decoratorInfo.group;
+    // Options: prefer decorator options, fall back to type values
+    if (decoratorInfo.options) {
+        field.options = decoratorInfo.options;
+    }
+    else if (typeInfo.values) {
+        // Convert simple values to strings
+        field.options = typeInfo.values.map((v) => String(v));
+    }
+    // Handle nested object properties
+    if (typeInfo.type === "object" && typeInfo.properties) {
+        field.fields = Object.entries(typeInfo.properties).map(([propName, propType]) => createField(propName, propType, {}));
+    }
+    return field;
+}
+/**
+ * Generates a UI Schema from a decorated class at runtime.
+ *
+ * **Requirements:**
+ * - Run `formspec codegen` to generate type metadata for the class
+ * - Decorators must be applied to store field metadata
+ *
+ * @param ctor - The class constructor
+ * @returns FormSpec output with elements array
+ *
+ * @example
+ * ```typescript
+ * import { Label, toFormSpec } from '@formspec/decorators';
+ *
+ * class MyForm {
+ *   @Label("Name")
+ *   name!: string;
+ *
+ *   @Label("Country")
+ *   country!: "us" | "ca";
+ * }
+ *
+ * const spec = toFormSpec(MyForm);
+ * // { elements: [{ _field: "text", id: "name", label: "Name", required: true }, ...] }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function toFormSpec(ctor) {
+    // Get type metadata from codegen (if available)
+    const typeMetadata = 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ctor[FORMSPEC_TYPES_KEY] ?? {};
+    // Get decorator metadata
+    const classDecoratorMeta = decoratorMetadata.get(ctor) ?? new Map();
+    // Combine to create elements
+    const elements = [];
+    // Process all fields from type metadata
+    for (const [fieldName, typeInfo] of Object.entries(typeMetadata)) {
+        const decoratorInfo = classDecoratorMeta.get(fieldName) ?? {};
+        elements.push(createField(fieldName, typeInfo, decoratorInfo));
+    }
+    // If no type metadata, fall back to decorator metadata only
+    // (limited functionality - no type information)
+    if (Object.keys(typeMetadata).length === 0) {
+        for (const [fieldName, decoratorInfo] of classDecoratorMeta.entries()) {
+            elements.push(createField(fieldName, { type: "unknown" }, decoratorInfo));
+        }
+    }
+    return { elements };
+}
+/**
+ * Gets the raw decorator metadata for a class.
+ *
+ * Useful for debugging or custom processing.
+ *
+ * @param ctor - The class constructor
+ * @returns Map of field names to decorator metadata
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function getDecoratorMetadata(ctor) {
+    return decoratorMetadata.get(ctor) ?? new Map();
+}
+/**
+ * Gets the raw type metadata for a class.
+ *
+ * Useful for debugging or custom processing.
+ *
+ * @param ctor - The class constructor
+ * @returns Record of field names to type metadata, or empty object if not transformed
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function getTypeMetadata(ctor) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return ctor[FORMSPEC_TYPES_KEY] ?? {};
+}
+// =============================================================================
+// Schema Generation
+// =============================================================================
+/**
+ * Maps FormSpecField type to JSON Schema type.
+ */
+function fieldTypeToJsonSchemaType(fieldType) {
+    switch (fieldType) {
+        case "text":
+            return "string";
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "enum":
+            return "string";
+        case "array":
+            return "array";
+        case "object":
+            return "object";
+        default:
+            return "string";
+    }
+}
+/**
+ * Converts a FormSpecField to JSON Schema.
+ */
+function fieldToJsonSchema(field) {
+    const schema = {};
+    if (field.label) {
+        schema.title = field.label;
+    }
+    const jsonType = fieldTypeToJsonSchemaType(field._field);
+    schema.type = jsonType;
+    // Number constraints
+    if (field.min !== undefined)
+        schema.minimum = field.min;
+    if (field.max !== undefined)
+        schema.maximum = field.max;
+    // String constraints
+    if (field.minLength !== undefined)
+        schema.minLength = field.minLength;
+    if (field.maxLength !== undefined)
+        schema.maxLength = field.maxLength;
+    if (field.pattern)
+        schema.pattern = field.pattern;
+    // Enum options
+    if (field._field === "enum" && field.options) {
+        const hasLabels = field.options.some((opt) => typeof opt === "object" && opt !== null && "id" in opt);
+        if (hasLabels) {
+            schema.oneOf = field.options.map((opt) => {
+                if (typeof opt === "object" && "id" in opt) {
+                    return { const: opt.id, title: opt.label };
+                }
+                return { const: opt, title: String(opt) };
+            });
+        }
+        else {
+            schema.enum = field.options.map((opt) => typeof opt === "string" ? opt : opt.id);
+        }
+    }
+    // Array items
+    if (field._field === "array" && field.fields) {
+        const itemProperties = {};
+        const itemRequired = [];
+        for (const nested of field.fields) {
+            itemProperties[nested.id] = fieldToJsonSchema(nested);
+            if (nested.required)
+                itemRequired.push(nested.id);
+        }
+        schema.items = {
+            type: "object",
+            properties: itemProperties,
+            ...(itemRequired.length > 0 && { required: itemRequired }),
+        };
+        if (field.minItems !== undefined)
+            schema.minItems = field.minItems;
+        if (field.maxItems !== undefined)
+            schema.maxItems = field.maxItems;
+    }
+    // Object properties
+    if (field._field === "object" && field.fields) {
+        const objProperties = {};
+        const objRequired = [];
+        for (const nested of field.fields) {
+            objProperties[nested.id] = fieldToJsonSchema(nested);
+            if (nested.required)
+                objRequired.push(nested.id);
+        }
+        schema.properties = objProperties;
+        if (objRequired.length > 0)
+            schema.required = objRequired;
+    }
+    return schema;
+}
+/**
+ * Generates JSON Schema from FormSpecField elements.
+ */
+function generateJsonSchemaFromElements(elements) {
+    const properties = {};
+    const required = [];
+    for (const element of elements) {
+        properties[element.id] = fieldToJsonSchema(element);
+        if (element.required) {
+            required.push(element.id);
+        }
+    }
+    return {
+        $schema: "https://json-schema.org/draft-07/schema#",
+        type: "object",
+        properties,
+        ...(required.length > 0 && { required }),
+    };
+}
+/**
+ * Converts a field name to a JSON Pointer scope.
+ */
+function fieldToScope(fieldName) {
+    return `#/properties/${fieldName}`;
+}
+/**
+ * Converts FormSpecField elements to UI Schema elements.
+ */
+function elementsToUiSchema(elements) {
+    const result = [];
+    for (const element of elements) {
+        const control = {
+            type: "Control",
+            scope: fieldToScope(element.id),
+        };
+        if (element.label) {
+            control.label = element.label;
+        }
+        // Add conditional visibility rule
+        if (element.showWhen) {
+            control.rule = {
+                effect: "SHOW",
+                condition: {
+                    scope: fieldToScope(element.showWhen.field),
+                    schema: { const: element.showWhen.value },
+                },
+            };
+        }
+        result.push(control);
+    }
+    return result;
+}
+/**
+ * Generates UI Schema from FormSpecField elements.
+ */
+function generateUiSchemaFromElements(elements) {
+    return {
+        type: "VerticalLayout",
+        elements: elementsToUiSchema(elements),
+    };
+}
+/**
+ * Builds both JSON Schema and UI Schema from a decorated class at runtime.
+ *
+ * This function provides the same API as `buildFormSchemas` from `@formspec/build`,
+ * allowing consistent usage across both Chain DSL and Decorator DSL.
+ *
+ * **Requirements:**
+ * - Run `formspec codegen` to generate type metadata for the class
+ * - Decorators must be applied to store field metadata
+ *
+ * @param ctor - The class constructor
+ * @returns Object containing both jsonSchema and uiSchema
+ *
+ * @example
+ * ```typescript
+ * import { Label, buildFormSchemas } from '@formspec/decorators';
+ *
+ * class MyForm {
+ *   @Label("Name")
+ *   name!: string;
+ *
+ *   @Label("Country")
+ *   country!: "us" | "ca";
+ * }
+ *
+ * // After running: formspec codegen ./forms.ts -o ./__formspec_types__.ts
+ * // And importing: import './__formspec_types__';
+ *
+ * const { jsonSchema, uiSchema } = buildFormSchemas(MyForm);
+ * // jsonSchema: { $schema: "...", type: "object", properties: {...}, required: [...] }
+ * // uiSchema: { type: "VerticalLayout", elements: [...] }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function buildFormSchemas(ctor) {
+    const { elements } = toFormSpec(ctor);
+    return {
+        jsonSchema: generateJsonSchemaFromElements(elements),
+        uiSchema: generateUiSchemaFromElements(elements),
+    };
+}
+//# sourceMappingURL=index.js.map