formspec 0.1.0-alpha.4 → 0.1.0-alpha.41

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

@@ -1,164 +1,95 @@
 # formspec
 
-Type-safe form specifications that compile to JSON Schema and JSON Forms UI Schema.
+Umbrella package for the common FormSpec authoring and runtime APIs.
 
-## Installation
+It re-exports the most commonly used pieces from:
 
-```bash
-npm install formspec
-# or
-pnpm add formspec
-```
+- `@formspec/core`
+- `@formspec/dsl`
+- `@formspec/build`
+- `@formspec/runtime`
 
-## Requirements
+It does not include the CLI, ESLint plugin, language server, or playground app.
 
-This package is ESM-only and requires:
+## Install
 
-```json
-// package.json
-{
-  "type": "module"
-}
-```
-
-```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext"
-  }
-}
+```bash
+pnpm add formspec
 ```
 
 ## 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" }),
+```ts
+import {
+  buildFormSchemas,
+  defineResolvers,
+  field,
+  formspec,
+  group,
+  is,
+  type InferFormSchema,
+  when,
+} from "formspec";
+
+const OrderForm = formspec(
+  group(
+    "Order",
+    field.text("customerName", { required: true }),
+    field.enum("status", ["draft", "submitted"] as const, { required: true })
   ),
+  when(is("status", "submitted"), field.text("submittedBy"))
 );
-```
 
-### Type Inference
+type OrderData = InferFormSchema<typeof OrderForm>;
 
-```typescript
-// Infer the form data type
-type FormData = InferFormSchema<typeof MyForm>;
+const { jsonSchema, uiSchema } = buildFormSchemas(OrderForm);
 
-// Use with form libraries
-const handleSubmit = (data: FormData) => {
-  // data is fully typed
-};
+const resolvers = defineResolvers(OrderForm, {});
 ```
 
-### Dynamic Enums with Resolvers
+## What You Get
 
-```typescript
-import { defineResolvers } from "formspec";
+### DSL
 
-const Form = formspec(
-  field.dynamicEnum("country", "fetch_countries", { label: "Country" }),
-);
+- `formspec`
+- `field`
+- `group`
+- `when`
+- `is`
+- `formspecWithValidation`
+- `validateForm`
 
-const resolvers = defineResolvers(Form, {
-  fetch_countries: async () => ({
-    options: [
-      { value: "us", label: "United States" },
-      { value: "ca", label: "Canada" },
-    ],
-    validity: "valid",
-  }),
-});
-```
+### Build
 
-### Write Schemas to Disk
+- `buildFormSchemas`
+- `generateJsonSchema`
+- `generateUiSchema`
+- `writeSchemas`
 
-```typescript
-import { writeSchemas } from "formspec";
+### Runtime
 
-writeSchemas(ContactForm, {
-  outDir: "./generated",
-  name: "contact-form",
-});
-// Creates: ./generated/contact-form-schema.json
-//          ./generated/contact-form-uischema.json
-```
+- `defineResolvers`
 
-## Package Structure
+### Types
 
-This umbrella package re-exports from several focused packages:
+- `InferSchema`
+- `InferFormSchema`
+- core field, layout, and state types
+- resolver and validation helper types
 
-| 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`) |
+### Utilities
 
-You can import from the umbrella package for convenience, or from individual packages for smaller bundle sizes.
+- `createInitialFieldState`
+- `validateForm`
+- `logValidationIssues`
 
-## Related Packages
+## When To Use Individual Packages
 
-| Package | Description |
-|---------|-------------|
-| `@formspec/decorators` | Decorator-based API for class definitions |
-| `@formspec/cli` | CLI tool for static analysis of decorated classes |
+- 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.