@formspec/decorators 0.1.0-alpha.3

package/README.md

@@ -0,0 +1,179 @@
+# @formspec/decorators
+
+Decorator stubs for FormSpec CLI static analysis.
+
+## Installation
+
+```bash
+npm install @formspec/decorators
+# or
+pnpm add @formspec/decorators
+```
+
+## Usage
+
+```typescript
+import { Label, Min, Max, EnumOptions, ShowWhen, Group } from '@formspec/decorators';
+
+class UserRegistration {
+  @Group("Personal Info")
+  @Label("Full Name")
+  name!: string;
+
+  @Group("Personal Info")
+  @Label("Age")
+  @Min(18)
+  @Max(120)
+  age?: number;
+
+  @Group("Preferences")
+  @Label("Country")
+  @EnumOptions([
+    { id: "us", label: "United States" },
+    { id: "ca", label: "Canada" },
+    { id: "uk", label: "United Kingdom" }
+  ])
+  country!: "us" | "ca" | "uk";
+
+  @Group("Preferences")
+  @Label("Contact Method")
+  contactMethod!: "email" | "phone";
+
+  @ShowWhen({ field: "contactMethod", value: "email" })
+  @Label("Email Address")
+  email?: string;
+
+  @ShowWhen({ field: "contactMethod", value: "phone" })
+  @Label("Phone Number")
+  phone?: string;
+}
+```
+
+## Generating Schemas
+
+### Build-Time Only
+
+Generate JSON Schema and UI Schema files at build time:
+
+```bash
+formspec generate ./src/user-registration.ts UserRegistration -o ./generated
+```
+
+This outputs static JSON files to `./generated/`. No codegen step required.
+
+### Runtime Schema Generation
+
+If you need JSON Schema or UI Schema **at runtime in your program** (e.g., dynamic form rendering, server-side generation), you have two options:
+
+1. **Chain DSL** - Works at runtime without any codegen step. See the [Chain DSL documentation](../dsl/README.md).
+
+2. **Decorator DSL with codegen** - If you prefer to keep using decorated classes, run codegen to preserve type information:
+
+```bash
+# Generate type metadata file
+formspec codegen ./src/forms.ts -o ./src/__formspec_types__.ts
+```
+
+```typescript
+// Import the generated file at your application entry point
+import './__formspec_types__.js';
+
+// Now buildFormSchemas() has access to full type information
+import { buildFormSchemas } from '@formspec/decorators';
+import { UserRegistration } from './forms.js';
+
+const { jsonSchema, uiSchema } = buildFormSchemas(UserRegistration);
+// jsonSchema: { $schema: "...", type: "object", properties: {...}, required: [...] }
+// uiSchema: { type: "VerticalLayout", elements: [...] }
+```
+
+Add `formspec codegen` to your build process to keep type metadata in sync.
+
+> **Note:** If you need to work with **dynamically fetched schema data** (schemas not known at build time), use the Chain DSL. It's the only option for dynamic schemas.
+
+### API Consistency
+
+The `buildFormSchemas()` function provides the same return type as `@formspec/build`:
+
+| DSL | Function | Returns |
+|-----|----------|---------|
+| Chain DSL | `buildFormSchemas(form)` | `{ jsonSchema, uiSchema }` |
+| Decorator DSL | `buildFormSchemas(Class)` | `{ jsonSchema, uiSchema }` |
+
+This allows you to switch between DSLs without changing how you consume the schemas.
+
+## How It Works
+
+These decorators are **no-ops at runtime** - they have zero overhead in your production code.
+
+The FormSpec CLI uses TypeScript's compiler API to statically analyze your source files. It reads decorator names and arguments directly from the AST, without ever executing your code.
+
+This means:
+- No reflection metadata required
+- No runtime dependencies
+- Works with any TypeScript configuration
+- Tree-shaking friendly
+
+## Available Decorators
+
+### Field Metadata
+
+| Decorator | Purpose | Example |
+|-----------|---------|---------|
+| `@Label(text)` | Display label | `@Label("Full Name")` |
+| `@Placeholder(text)` | Input placeholder | `@Placeholder("Enter name...")` |
+| `@Description(text)` | Help text | `@Description("Your legal name")` |
+
+### Numeric Constraints
+
+| Decorator | Purpose | Example |
+|-----------|---------|---------|
+| `@Min(n)` | Minimum value | `@Min(0)` |
+| `@Max(n)` | Maximum value | `@Max(100)` |
+| `@Step(n)` | Step increment | `@Step(0.01)` |
+
+### String Constraints
+
+| Decorator | Purpose | Example |
+|-----------|---------|---------|
+| `@MinLength(n)` | Minimum length | `@MinLength(1)` |
+| `@MaxLength(n)` | Maximum length | `@MaxLength(255)` |
+| `@Pattern(regex)` | Regex pattern | `@Pattern("^[a-z]+$")` |
+
+### Array Constraints
+
+| Decorator | Purpose | Example |
+|-----------|---------|---------|
+| `@MinItems(n)` | Minimum items | `@MinItems(1)` |
+| `@MaxItems(n)` | Maximum items | `@MaxItems(10)` |
+
+### Enum Options
+
+| Decorator | Purpose | Example |
+|-----------|---------|---------|
+| `@EnumOptions(opts)` | Custom labels | `@EnumOptions([{id: "us", label: "USA"}])` |
+
+### Layout & Conditional
+
+| Decorator | Purpose | Example |
+|-----------|---------|---------|
+| `@Group(name)` | Group fields | `@Group("Contact Info")` |
+| `@ShowWhen(cond)` | Conditional visibility | `@ShowWhen({ field: "type", value: "other" })` |
+
+## TypeScript Configuration
+
+For decorator support, ensure your `tsconfig.json` includes:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true
+  }
+}
+```
+
+Note: The `emitDecoratorMetadata` flag is not required since these decorators don't use reflection.
+
+## License
+
+UNLICENSED

package/dist/index.cjs

@@ -0,0 +1,380 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// dist/index.js
+var index_exports = {};
+__export(index_exports, {
+  Description: () => Description,
+  EnumOptions: () => EnumOptions,
+  Group: () => Group,
+  Label: () => Label,
+  Max: () => Max,
+  MaxItems: () => MaxItems,
+  MaxLength: () => MaxLength,
+  Min: () => Min,
+  MinItems: () => MinItems,
+  MinLength: () => MinLength,
+  Pattern: () => Pattern,
+  Placeholder: () => Placeholder,
+  ShowWhen: () => ShowWhen,
+  Step: () => Step,
+  buildFormSchemas: () => buildFormSchemas,
+  getDecoratorMetadata: () => getDecoratorMetadata,
+  getTypeMetadata: () => getTypeMetadata,
+  toFormSpec: () => toFormSpec
+});
+module.exports = __toCommonJS(index_exports);
+var decoratorMetadata = /* @__PURE__ */ new Map();
+function getFieldMetadata(ctor, propertyKey) {
+  if (!decoratorMetadata.has(ctor)) {
+    decoratorMetadata.set(ctor, /* @__PURE__ */ new Map());
+  }
+  const classMetadata = decoratorMetadata.get(ctor);
+  if (!classMetadata.has(propertyKey)) {
+    classMetadata.set(propertyKey, {});
+  }
+  return classMetadata.get(propertyKey);
+}
+function Label(text) {
+  return function(target, propertyKey) {
+    const ctor = target.constructor;
+    getFieldMetadata(ctor, propertyKey).label = text;
+  };
+}
+function Placeholder(text) {
+  return function(target, propertyKey) {
+    const ctor = target.constructor;
+    getFieldMetadata(ctor, propertyKey).placeholder = text;
+  };
+}
+function Description(text) {
+  return function(target, propertyKey) {
+    const ctor = target.constructor;
+    getFieldMetadata(ctor, propertyKey).description = text;
+  };
+}
+function Min(value) {
+  return function(target, propertyKey) {
+    const ctor = target.constructor;
+    getFieldMetadata(ctor, propertyKey).min = value;
+  };
+}
+function Max(value) {
+  return function(target, propertyKey) {
+    const ctor = target.constructor;
+    getFieldMetadata(ctor, propertyKey).max = value;
+  };
+}
+function Step(value) {
+  return function(target, propertyKey) {
+    const ctor = target.constructor;
+    getFieldMetadata(ctor, propertyKey).step = value;
+  };
+}
+function MinLength(value) {
+  return function(target, propertyKey) {
+    const ctor = target.constructor;
+    getFieldMetadata(ctor, propertyKey).minLength = value;
+  };
+}
+function MaxLength(value) {
+  return function(target, propertyKey) {
+    const ctor = target.constructor;
+    getFieldMetadata(ctor, propertyKey).maxLength = value;
+  };
+}
+function Pattern(regex) {
+  return function(target, propertyKey) {
+    const ctor = target.constructor;
+    getFieldMetadata(ctor, propertyKey).pattern = regex;
+  };
+}
+function MinItems(value) {
+  return function(target, propertyKey) {
+    const ctor = target.constructor;
+    getFieldMetadata(ctor, propertyKey).minItems = value;
+  };
+}
+function MaxItems(value) {
+  return function(target, propertyKey) {
+    const ctor = target.constructor;
+    getFieldMetadata(ctor, propertyKey).maxItems = value;
+  };
+}
+function EnumOptions(options) {
+  return function(target, propertyKey) {
+    const ctor = target.constructor;
+    getFieldMetadata(ctor, propertyKey).options = options;
+  };
+}
+function ShowWhen(condition) {
+  return function(target, propertyKey) {
+    const ctor = target.constructor;
+    getFieldMetadata(ctor, propertyKey).showWhen = condition;
+  };
+}
+function Group(name) {
+  return function(target, propertyKey) {
+    const ctor = target.constructor;
+    getFieldMetadata(ctor, propertyKey).group = name;
+  };
+}
+var FORMSPEC_TYPES_KEY = "__formspec_types__";
+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";
+  }
+}
+function createField(fieldName, typeInfo, decoratorInfo) {
+  const field = {
+    _field: mapTypeToFieldType(typeInfo.type),
+    id: fieldName
+  };
+  if (!typeInfo.optional && !typeInfo.nullable) {
+    field.required = true;
+  }
+  if (decoratorInfo.label)
+    field.label = decoratorInfo.label;
+  if (decoratorInfo.placeholder)
+    field.placeholder = decoratorInfo.placeholder;
+  if (decoratorInfo.description)
+    field.description = decoratorInfo.description;
+  if (decoratorInfo.min !== void 0)
+    field.min = decoratorInfo.min;
+  if (decoratorInfo.max !== void 0)
+    field.max = decoratorInfo.max;
+  if (decoratorInfo.step !== void 0)
+    field.step = decoratorInfo.step;
+  if (decoratorInfo.minLength !== void 0)
+    field.minLength = decoratorInfo.minLength;
+  if (decoratorInfo.maxLength !== void 0)
+    field.maxLength = decoratorInfo.maxLength;
+  if (decoratorInfo.minItems !== void 0)
+    field.minItems = decoratorInfo.minItems;
+  if (decoratorInfo.maxItems !== void 0)
+    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;
+  if (decoratorInfo.options) {
+    field.options = decoratorInfo.options;
+  } else if (typeInfo.values) {
+    field.options = typeInfo.values.map((v) => String(v));
+  }
+  if (typeInfo.type === "object" && typeInfo.properties) {
+    field.fields = Object.entries(typeInfo.properties).map(([propName, propType]) => createField(propName, propType, {}));
+  }
+  return field;
+}
+function toFormSpec(ctor) {
+  const typeMetadata = (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ctor[FORMSPEC_TYPES_KEY] ?? {}
+  );
+  const classDecoratorMeta = decoratorMetadata.get(ctor) ?? /* @__PURE__ */ new Map();
+  const elements = [];
+  for (const [fieldName, typeInfo] of Object.entries(typeMetadata)) {
+    const decoratorInfo = classDecoratorMeta.get(fieldName) ?? {};
+    elements.push(createField(fieldName, typeInfo, decoratorInfo));
+  }
+  if (Object.keys(typeMetadata).length === 0) {
+    for (const [fieldName, decoratorInfo] of classDecoratorMeta.entries()) {
+      elements.push(createField(fieldName, { type: "unknown" }, decoratorInfo));
+    }
+  }
+  return { elements };
+}
+function getDecoratorMetadata(ctor) {
+  return decoratorMetadata.get(ctor) ?? /* @__PURE__ */ new Map();
+}
+function getTypeMetadata(ctor) {
+  return ctor[FORMSPEC_TYPES_KEY] ?? {};
+}
+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";
+  }
+}
+function fieldToJsonSchema(field) {
+  const schema = {};
+  if (field.label) {
+    schema.title = field.label;
+  }
+  const jsonType = fieldTypeToJsonSchemaType(field._field);
+  schema.type = jsonType;
+  if (field.min !== void 0)
+    schema.minimum = field.min;
+  if (field.max !== void 0)
+    schema.maximum = field.max;
+  if (field.minLength !== void 0)
+    schema.minLength = field.minLength;
+  if (field.maxLength !== void 0)
+    schema.maxLength = field.maxLength;
+  if (field.pattern)
+    schema.pattern = field.pattern;
+  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);
+    }
+  }
+  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 !== void 0)
+      schema.minItems = field.minItems;
+    if (field.maxItems !== void 0)
+      schema.maxItems = field.maxItems;
+  }
+  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;
+}
+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 }
+  };
+}
+function fieldToScope(fieldName) {
+  return `#/properties/${fieldName}`;
+}
+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;
+    }
+    if (element.showWhen) {
+      control.rule = {
+        effect: "SHOW",
+        condition: {
+          scope: fieldToScope(element.showWhen.field),
+          schema: { const: element.showWhen.value }
+        }
+      };
+    }
+    result.push(control);
+  }
+  return result;
+}
+function generateUiSchemaFromElements(elements) {
+  return {
+    type: "VerticalLayout",
+    elements: elementsToUiSchema(elements)
+  };
+}
+function buildFormSchemas(ctor) {
+  const { elements } = toFormSpec(ctor);
+  return {
+    jsonSchema: generateJsonSchemaFromElements(elements),
+    uiSchema: generateUiSchemaFromElements(elements)
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Description,
+  EnumOptions,
+  Group,
+  Label,
+  Max,
+  MaxItems,
+  MaxLength,
+  Min,
+  MinItems,
+  MinLength,
+  Pattern,
+  Placeholder,
+  ShowWhen,
+  Step,
+  buildFormSchemas,
+  getDecoratorMetadata,
+  getTypeMetadata,
+  toFormSpec
+});