formspec 0.0.0 → 0.1.0-alpha.10

package/README.md

@@ -0,0 +1,157 @@
+# formspec
+
+Type-safe form specifications that compile to JSON Schema and JSON Forms UI Schema.
+
+## Installation
+
+```bash
+npm install formspec
+# or
+pnpm add formspec
+```
+
+## Requirements
+
+This package is ESM-only and requires:
+
+```json
+// package.json
+{
+  "type": "module"
+}
+```
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext"
+  }
+}
+```
+
+## Quick Start
+
+```typescript
+import { formspec, field, group, when, is, buildFormSchemas, type InferFormSchema } from "formspec";
+
+// Define a form
+const ContactForm = formspec(
+  field.text("name", { label: "Name", required: true }),
+  field.text("email", { label: "Email", required: true }),
+  field.enum("subject", ["General", "Support", "Sales"], { label: "Subject" }),
+  field.text("message", { label: "Message", required: true }),
+  field.boolean("subscribe", { label: "Subscribe to newsletter" })
+);
+
+// Infer TypeScript type from the form
+type ContactData = InferFormSchema<typeof ContactForm>;
+// { name: string; email: string; subject: "General" | "Support" | "Sales" | undefined; ... }
+
+// Generate JSON Schema and UI Schema
+const { jsonSchema, uiSchema } = buildFormSchemas(ContactForm);
+```
+
+## Features
+
+### Field Types
+
+```typescript
+field.text("name", { label: "Name", required: true });
+field.number("age", { label: "Age", min: 0, max: 120 });
+field.boolean("active", { label: "Active" });
+field.enum("status", ["draft", "published"], { label: "Status" });
+field.dynamicEnum("country", "fetch_countries", { label: "Country" });
+field.array("tags", field.text("tag"));
+field.object("address", field.text("street"), field.text("city"));
+```
+
+### Grouping
+
+```typescript
+const Form = formspec(
+  group("Personal Info", field.text("firstName"), field.text("lastName")),
+  group("Contact", field.text("email"), field.text("phone"))
+);
+```
+
+### Conditional Fields
+
+```typescript
+const Form = formspec(
+  field.enum("type", ["personal", "business"]),
+  when(
+    is("type", "business"),
+    field.text("companyName", { label: "Company Name" }),
+    field.text("taxId", { label: "Tax ID" })
+  )
+);
+```
+
+### Type Inference
+
+```typescript
+// Infer the form data type
+type FormData = InferFormSchema<typeof MyForm>;
+
+// Use with form libraries
+const handleSubmit = (data: FormData) => {
+  // data is fully typed
+};
+```
+
+### Dynamic Enums with Resolvers
+
+```typescript
+import { defineResolvers } from "formspec";
+
+const Form = formspec(field.dynamicEnum("country", "fetch_countries", { label: "Country" }));
+
+const resolvers = defineResolvers(Form, {
+  fetch_countries: async () => ({
+    options: [
+      { value: "us", label: "United States" },
+      { value: "ca", label: "Canada" },
+    ],
+    validity: "valid",
+  }),
+});
+```
+
+### Write Schemas to Disk
+
+```typescript
+import { writeSchemas } from "formspec";
+
+writeSchemas(ContactForm, {
+  outDir: "./generated",
+  name: "contact-form",
+});
+// Creates: ./generated/contact-form-schema.json
+//          ./generated/contact-form-uischema.json
+```
+
+## Package Structure
+
+This umbrella package re-exports from several focused packages:
+
+| Package             | Description                                                |
+| ------------------- | ---------------------------------------------------------- |
+| `@formspec/core`    | Core type definitions                                      |
+| `@formspec/dsl`     | DSL functions (`formspec`, `field`, `group`, `when`, `is`) |
+| `@formspec/build`   | Schema generators (`buildFormSchemas`, `writeSchemas`)     |
+| `@formspec/runtime` | Runtime helpers (`defineResolvers`)                        |
+
+You can import from the umbrella package for convenience, or from individual packages for smaller bundle sizes.
+
+## Related Packages
+
+| Package                | Description                                       |
+| ---------------------- | ------------------------------------------------- |
+| `@formspec/decorators` | Decorator-based API for class definitions         |
+| `@formspec/cli`        | CLI tool for static analysis of decorated classes |
+
+## License
+
+UNLICENSED

package/dist/formspec.d.ts

@@ -0,0 +1,254 @@
+/**
+ * FormSpec - Type-safe form specifications
+ *
+ * This package re-exports everything from the FormSpec library for convenience.
+ * You can import everything you need from a single package:
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   // DSL functions
+ *   formspec, field, group, when, is,
+ *   // Type inference
+ *   type InferSchema,
+ *   // Schema generation
+ *   buildFormSchemas,
+ *   // Resolvers
+ *   defineResolvers,
+ *   // Core types
+ *   type FormSpec, type FormElement,
+ * } from "formspec";
+ *
+ * // Define a form
+ * const InvoiceForm = formspec(
+ *   group("Customer",
+ *     field.text("name", { label: "Name", required: true }),
+ *     field.dynamicEnum("country", "fetch_countries", { label: "Country" }),
+ *   ),
+ *   group("Details",
+ *     field.number("amount", { label: "Amount", min: 0 }),
+ *     field.enum("status", ["draft", "sent", "paid"]),
+ *     when(is("status", "draft"),
+ *       field.text("notes", { label: "Internal Notes" }),
+ *     ),
+ *   ),
+ * );
+ *
+ * // Infer the schema type
+ * type Schema = InferSchema<typeof InvoiceForm.elements>;
+ *
+ * // Generate JSON Schema and UI Schema
+ * const { jsonSchema, uiSchema } = buildFormSchemas(InvoiceForm);
+ *
+ * // Define resolvers for dynamic data
+ * const resolvers = defineResolvers(InvoiceForm, {
+ *   fetch_countries: async () => ({
+ *     options: [{ value: "us", label: "United States" }],
+ *     validity: "valid",
+ *   }),
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import { AnyField } from '@formspec/core';
+import { ArrayField } from '@formspec/core';
+import { BooleanField } from '@formspec/core';
+import { buildFormSchemas } from '@formspec/build';
+import { BuildResult } from '@formspec/build';
+import { BuildSchema } from '@formspec/dsl';
+import { Conditional } from '@formspec/core';
+import { ControlElement } from '@formspec/build';
+import { createInitialFieldState } from '@formspec/core';
+import { DataSourceOption } from '@formspec/core';
+import { DataSourceRegistry } from '@formspec/core';
+import { DataSourceValueType } from '@formspec/core';
+import { defineResolvers } from '@formspec/runtime';
+import { DynamicEnumField } from '@formspec/core';
+import { DynamicSchemaField } from '@formspec/core';
+import { EnumOption } from '@formspec/dsl';
+import { EnumOptionValue } from '@formspec/dsl';
+import { EqualsPredicate } from '@formspec/core';
+import { ExtractFields } from '@formspec/dsl';
+import { ExtractFieldsFromArray } from '@formspec/dsl';
+import { FetchOptionsResponse } from '@formspec/core';
+import { field } from '@formspec/dsl';
+import { FieldState } from '@formspec/core';
+import { FormElement } from '@formspec/core';
+import { FormSpec } from '@formspec/core';
+import { formspec } from '@formspec/dsl';
+import { FormSpecOptions } from '@formspec/dsl';
+import { formspecWithValidation } from '@formspec/dsl';
+import { FormState } from '@formspec/core';
+import { generateJsonSchema } from '@formspec/build';
+import { generateUiSchema } from '@formspec/build';
+import { Group } from '@formspec/core';
+import { group } from '@formspec/dsl';
+import { GroupLayout } from '@formspec/build';
+import { HorizontalLayout } from '@formspec/build';
+import { InferFieldValue } from '@formspec/dsl';
+import { InferFormSchema } from '@formspec/dsl';
+import { InferSchema } from '@formspec/dsl';
+import { is } from '@formspec/dsl';
+import { JSONSchema7 } from '@formspec/build';
+import { JSONSchemaType } from '@formspec/build';
+import { logValidationIssues } from '@formspec/dsl';
+import { NumberField } from '@formspec/core';
+import { ObjectField } from '@formspec/core';
+import { Predicate } from '@formspec/core';
+import { Resolver } from '@formspec/runtime';
+import { ResolverMap } from '@formspec/runtime';
+import { ResolverRegistry } from '@formspec/runtime';
+import { Rule } from '@formspec/build';
+import { RuleEffect } from '@formspec/build';
+import { SchemaBasedCondition } from '@formspec/build';
+import { StaticEnumField } from '@formspec/core';
+import { TextField } from '@formspec/core';
+import { UISchema } from '@formspec/build';
+import { UISchemaElement } from '@formspec/build';
+import { UISchemaElementType } from '@formspec/build';
+import { validateForm } from '@formspec/dsl';
+import { ValidationIssue } from '@formspec/dsl';
+import { ValidationResult } from '@formspec/dsl';
+import { ValidationSeverity } from '@formspec/dsl';
+import { Validity } from '@formspec/core';
+import { VerticalLayout } from '@formspec/build';
+import { when } from '@formspec/dsl';
+import { writeSchemas } from '@formspec/build';
+import { WriteSchemasOptions } from '@formspec/build';
+import { WriteSchemasResult } from '@formspec/build';
+
+export { AnyField }
+
+export { ArrayField }
+
+export { BooleanField }
+
+export { buildFormSchemas }
+
+export { BuildResult }
+
+export { BuildSchema }
+
+export { Conditional }
+
+export { ControlElement }
+
+export { createInitialFieldState }
+
+export { DataSourceOption }
+
+export { DataSourceRegistry }
+
+export { DataSourceValueType }
+
+export { defineResolvers }
+
+export { DynamicEnumField }
+
+export { DynamicSchemaField }
+
+export { EnumOption }
+
+export { EnumOptionValue }
+
+export { EqualsPredicate }
+
+export { ExtractFields }
+
+export { ExtractFieldsFromArray }
+
+export { FetchOptionsResponse }
+
+export { field }
+
+export { FieldState }
+
+export { FormElement }
+
+export { FormSpec }
+
+export { formspec }
+
+export { FormSpecOptions }
+
+export { formspecWithValidation }
+
+export { FormState }
+
+export { generateJsonSchema }
+
+export { generateUiSchema }
+
+export { Group }
+
+export { group }
+
+export { GroupLayout }
+
+export { HorizontalLayout }
+
+export { InferFieldValue }
+
+export { InferFormSchema }
+
+export { InferSchema }
+
+export { is }
+
+export { JSONSchema7 }
+
+export { JSONSchemaType }
+
+export { logValidationIssues }
+
+export { NumberField }
+
+export { ObjectField }
+
+export { Predicate }
+
+export { Resolver }
+
+export { ResolverMap }
+
+export { ResolverRegistry }
+
+export { Rule }
+
+export { RuleEffect }
+
+export { SchemaBasedCondition }
+
+export { StaticEnumField }
+
+export { TextField }
+
+export { UISchema }
+
+export { UISchemaElement }
+
+export { UISchemaElementType }
+
+export { validateForm }
+
+export { ValidationIssue }
+
+export { ValidationResult }
+
+export { ValidationSeverity }
+
+export { Validity }
+
+export { VerticalLayout }
+
+export { when }
+
+export { writeSchemas }
+
+export { WriteSchemasOptions }
+
+export { WriteSchemasResult }
+
+export { }

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * FormSpec - Type-safe form specifications
+ *
+ * This package re-exports everything from the FormSpec library for convenience.
+ * You can import everything you need from a single package:
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   // DSL functions
+ *   formspec, field, group, when, is,
+ *   // Type inference
+ *   type InferSchema,
+ *   // Schema generation
+ *   buildFormSchemas,
+ *   // Resolvers
+ *   defineResolvers,
+ *   // Core types
+ *   type FormSpec, type FormElement,
+ * } from "formspec";
+ *
+ * // Define a form
+ * const InvoiceForm = formspec(
+ *   group("Customer",
+ *     field.text("name", { label: "Name", required: true }),
+ *     field.dynamicEnum("country", "fetch_countries", { label: "Country" }),
+ *   ),
+ *   group("Details",
+ *     field.number("amount", { label: "Amount", min: 0 }),
+ *     field.enum("status", ["draft", "sent", "paid"]),
+ *     when(is("status", "draft"),
+ *       field.text("notes", { label: "Internal Notes" }),
+ *     ),
+ *   ),
+ * );
+ *
+ * // Infer the schema type
+ * type Schema = InferSchema<typeof InvoiceForm.elements>;
+ *
+ * // Generate JSON Schema and UI Schema
+ * const { jsonSchema, uiSchema } = buildFormSchemas(InvoiceForm);
+ *
+ * // Define resolvers for dynamic data
+ * const resolvers = defineResolvers(InvoiceForm, {
+ *   fetch_countries: async () => ({
+ *     options: [{ value: "us", label: "United States" }],
+ *     validity: "valid",
+ *   }),
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { Validity, FieldState, FormState, DataSourceRegistry, DataSourceOption, FetchOptionsResponse, DataSourceValueType, TextField, NumberField, BooleanField, StaticEnumField, DynamicEnumField, DynamicSchemaField, ArrayField, ObjectField, AnyField, Group, Conditional, FormElement, FormSpec, EqualsPredicate, Predicate, } from "@formspec/core";
+export { createInitialFieldState } from "@formspec/core";
+export { field, group, when, is, formspec, formspecWithValidation, validateForm, logValidationIssues, } from "@formspec/dsl";
+export type { EnumOption, EnumOptionValue } from "@formspec/dsl";
+export type { InferFieldValue, ExtractFields, ExtractFieldsFromArray, BuildSchema, InferSchema, InferFormSchema, FormSpecOptions, ValidationSeverity, ValidationIssue, ValidationResult, } from "@formspec/dsl";
+export { generateJsonSchema, generateUiSchema, buildFormSchemas, writeSchemas, } from "@formspec/build";
+export type { JSONSchema7, JSONSchemaType, UISchema, UISchemaElement, UISchemaElementType, ControlElement, VerticalLayout, HorizontalLayout, GroupLayout, Rule, RuleEffect, SchemaBasedCondition, BuildResult, WriteSchemasOptions, WriteSchemasResult, } from "@formspec/build";
+export { defineResolvers } from "@formspec/runtime";
+export type { Resolver, ResolverMap, ResolverRegistry } from "@formspec/runtime";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAMH,YAAY,EAEV,QAAQ,EAGR,UAAU,EAGV,SAAS,EAGT,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EAGnB,SAAS,EACT,WAAW,EACX,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,QAAQ,EACR,KAAK,EACL,WAAW,EACX,WAAW,EACX,QAAQ,EAGR,eAAe,EACf,SAAS,GACV,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAMzD,OAAO,EACL,KAAK,EACL,KAAK,EACL,IAAI,EACJ,EAAE,EACF,QAAQ,EACR,sBAAsB,EACtB,YAAY,EACZ,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAGvB,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEjE,YAAY,EAEV,eAAe,EACf,aAAa,EACb,sBAAsB,EACtB,WAAW,EACX,WAAW,EACX,eAAe,EAEf,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAMvB,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,WAAW,EACX,cAAc,EACd,QAAQ,EACR,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,IAAI,EACJ,UAAU,EACV,oBAAoB,EACpB,WAAW,EACX,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AAMzB,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,67 @@
+/**
+ * FormSpec - Type-safe form specifications
+ *
+ * This package re-exports everything from the FormSpec library for convenience.
+ * You can import everything you need from a single package:
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   // DSL functions
+ *   formspec, field, group, when, is,
+ *   // Type inference
+ *   type InferSchema,
+ *   // Schema generation
+ *   buildFormSchemas,
+ *   // Resolvers
+ *   defineResolvers,
+ *   // Core types
+ *   type FormSpec, type FormElement,
+ * } from "formspec";
+ *
+ * // Define a form
+ * const InvoiceForm = formspec(
+ *   group("Customer",
+ *     field.text("name", { label: "Name", required: true }),
+ *     field.dynamicEnum("country", "fetch_countries", { label: "Country" }),
+ *   ),
+ *   group("Details",
+ *     field.number("amount", { label: "Amount", min: 0 }),
+ *     field.enum("status", ["draft", "sent", "paid"]),
+ *     when(is("status", "draft"),
+ *       field.text("notes", { label: "Internal Notes" }),
+ *     ),
+ *   ),
+ * );
+ *
+ * // Infer the schema type
+ * type Schema = InferSchema<typeof InvoiceForm.elements>;
+ *
+ * // Generate JSON Schema and UI Schema
+ * const { jsonSchema, uiSchema } = buildFormSchemas(InvoiceForm);
+ *
+ * // Define resolvers for dynamic data
+ * const resolvers = defineResolvers(InvoiceForm, {
+ *   fetch_countries: async () => ({
+ *     options: [{ value: "us", label: "United States" }],
+ *     validity: "valid",
+ *   }),
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { createInitialFieldState } from "@formspec/core";
+// =============================================================================
+// DSL functions
+// =============================================================================
+export { field, group, when, is, formspec, formspecWithValidation, validateForm, logValidationIssues, } from "@formspec/dsl";
+// =============================================================================
+// Build tools
+// =============================================================================
+export { generateJsonSchema, generateUiSchema, buildFormSchemas, writeSchemas, } from "@formspec/build";
+// =============================================================================
+// Runtime helpers
+// =============================================================================
+export { defineResolvers } from "@formspec/runtime";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AA0CH,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAEzD,gFAAgF;AAChF,gBAAgB;AAChB,gFAAgF;AAEhF,OAAO,EACL,KAAK,EACL,KAAK,EACL,IAAI,EACJ,EAAE,EACF,QAAQ,EACR,sBAAsB,EACtB,YAAY,EACZ,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAoBvB,gFAAgF;AAChF,cAAc;AACd,gFAAgF;AAEhF,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,GACb,MAAM,iBAAiB,CAAC;AAoBzB,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -1,11 +1,44 @@
 {
   "name": "formspec",
-  "version": "0.0.0",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "version": "0.1.0-alpha.10",
+  "description": "Type-safe form specifications that compile to JSON Schema and JSON Forms UI Schema",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/formspec.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/formspec.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@formspec/core": "0.1.0-alpha.10",
+    "@formspec/dsl": "0.1.0-alpha.10",
+    "@formspec/build": "0.1.0-alpha.10",
+    "@formspec/runtime": "0.1.0-alpha.10"
   },
-  "author": "",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "form",
+    "forms",
+    "json-schema",
+    "json-forms",
+    "type-safe",
+    "typescript"
+  ],
   "license": "UNLICENSED",
-  "description": ""
-}
+  "scripts": {
+    "build": "tsc && declaration-file-normalizer dist/index.d.ts && api-extractor run --local",
+    "clean": "rm -rf dist temp",
+    "typecheck": "tsc --noEmit",
+    "api-extractor": "api-extractor run",
+    "api-extractor:local": "api-extractor run --local",
+    "api-documenter": "api-documenter markdown -i temp -o docs"
+  }
+}