formspec 0.1.0-alpha.17 → 0.1.0-alpha.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +58 -130
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -1,160 +1,88 @@
1
1
  # formspec
2
2
 
3
- Type-safe form specifications that compile to JSON Schema and JSON Forms UI Schema.
3
+ Umbrella package for the common FormSpec authoring and runtime APIs.
4
4
 
5
- ## Installation
5
+ It re-exports the most commonly used pieces from:
6
6
 
7
- ```bash
8
- npm install formspec
9
- # or
10
- pnpm add formspec
11
- ```
7
+ - `@formspec/core`
8
+ - `@formspec/dsl`
9
+ - `@formspec/build`
10
+ - `@formspec/runtime`
12
11
 
13
- ## Requirements
12
+ It does not include the CLI, ESLint plugin, language server, or playground app.
14
13
 
15
- This package is ESM-only and requires:
14
+ ## Install
16
15
 
17
- ```json
18
- // package.json
19
- {
20
- "type": "module"
21
- }
22
- ```
23
-
24
- ```json
25
- // tsconfig.json
26
- {
27
- "compilerOptions": {
28
- "module": "NodeNext",
29
- "moduleResolution": "NodeNext"
30
- }
31
- }
16
+ ```bash
17
+ pnpm add formspec
32
18
  ```
33
19
 
34
20
  ## Quick Start
35
21
 
36
- ```typescript
37
- import { formspec, field, group, when, is, buildFormSchemas, type InferFormSchema } from "formspec";
38
-
39
- // Define a form
40
- const ContactForm = formspec(
41
- field.text("name", { label: "Name", required: true }),
42
- field.text("email", { label: "Email", required: true }),
43
- field.enum("subject", ["General", "Support", "Sales"], { label: "Subject" }),
44
- field.text("message", { label: "Message", required: true }),
45
- field.boolean("subscribe", { label: "Subscribe to newsletter" })
22
+ ```ts
23
+ import {
24
+ buildFormSchemas,
25
+ defineResolvers,
26
+ field,
27
+ formspec,
28
+ group,
29
+ is,
30
+ type InferFormSchema,
31
+ when,
32
+ } from "formspec";
33
+
34
+ const OrderForm = formspec(
35
+ group(
36
+ "Order",
37
+ field.text("customerName", { required: true }),
38
+ field.enum("status", ["draft", "submitted"] as const, { required: true })
39
+ ),
40
+ when(is("status", "submitted"), field.text("submittedBy"))
46
41
  );
47
42
 
48
- // Infer TypeScript type from the form
49
- type ContactData = InferFormSchema<typeof ContactForm>;
50
- // { name: string; email: string; subject: "General" | "Support" | "Sales" | undefined; ... }
51
-
52
- // Generate JSON Schema and UI Schema
53
- const { jsonSchema, uiSchema } = buildFormSchemas(ContactForm);
54
- ```
55
-
56
- ## Features
43
+ type OrderData = InferFormSchema<typeof OrderForm>;
57
44
 
58
- ### Field Types
45
+ const { jsonSchema, uiSchema } = buildFormSchemas(OrderForm);
59
46
 
60
- ```typescript
61
- field.text("name", { label: "Name", required: true });
62
- field.number("age", { label: "Age", min: 0, max: 120 });
63
- field.boolean("active", { label: "Active" });
64
- field.enum("status", ["draft", "published"], { label: "Status" });
65
- field.dynamicEnum("country", "fetch_countries", { label: "Country" });
66
- field.array("tags", field.text("tag"));
67
- field.object("address", field.text("street"), field.text("city"));
47
+ const resolvers = defineResolvers(OrderForm, {});
68
48
  ```
69
49
 
70
- ### Grouping
50
+ ## What You Get
71
51
 
72
- ```typescript
73
- const Form = formspec(
74
- group("Personal Info", field.text("firstName"), field.text("lastName")),
75
- group("Contact", field.text("email"), field.text("phone"))
76
- );
77
- ```
52
+ ### DSL
78
53
 
79
- ### Conditional Fields
54
+ - `formspec`
55
+ - `field`
56
+ - `group`
57
+ - `when`
58
+ - `is`
59
+ - `formspecWithValidation`
60
+ - `validateForm`
80
61
 
81
- ```typescript
82
- const Form = formspec(
83
- field.enum("type", ["personal", "business"]),
84
- when(
85
- is("type", "business"),
86
- field.text("companyName", { label: "Company Name" }),
87
- field.text("taxId", { label: "Tax ID" })
88
- )
89
- );
90
- ```
91
-
92
- ### Type Inference
93
-
94
- ```typescript
95
- // Infer the form data type
96
- type FormData = InferFormSchema<typeof MyForm>;
97
-
98
- // Use with form libraries
99
- const handleSubmit = (data: FormData) => {
100
- // data is fully typed
101
- };
102
- ```
103
-
104
- ### Dynamic Enums with Resolvers
105
-
106
- ```typescript
107
- import { defineResolvers } from "formspec";
62
+ ### Build
108
63
 
109
- const Form = formspec(field.dynamicEnum("country", "fetch_countries", { label: "Country" }));
110
-
111
- const resolvers = defineResolvers(Form, {
112
- fetch_countries: async () => ({
113
- options: [
114
- { value: "us", label: "United States" },
115
- { value: "ca", label: "Canada" },
116
- ],
117
- validity: "valid",
118
- }),
119
- });
120
- ```
121
-
122
- ### Write Schemas to Disk
123
-
124
- ```typescript
125
- import { writeSchemas } from "formspec";
126
-
127
- writeSchemas(ContactForm, {
128
- outDir: "./generated",
129
- name: "contact-form",
130
- });
131
- // Creates: ./generated/contact-form-schema.json
132
- // ./generated/contact-form-uischema.json
133
- ```
64
+ - `buildFormSchemas`
65
+ - `generateJsonSchema`
66
+ - `generateUiSchema`
67
+ - `writeSchemas`
68
+ - `buildMixedAuthoringSchemas`
134
69
 
135
- ## Package Structure
70
+ ### Runtime
136
71
 
137
- This umbrella package re-exports from several focused packages:
72
+ - `defineResolvers`
138
73
 
139
- | Package | Description |
140
- | ------------------- | ---------------------------------------------------------- |
141
- | `@formspec/core` | Core type definitions |
142
- | `@formspec/dsl` | DSL functions (`formspec`, `field`, `group`, `when`, `is`) |
143
- | `@formspec/build` | Schema generators (`buildFormSchemas`, `writeSchemas`) |
144
- | `@formspec/runtime` | Runtime helpers (`defineResolvers`) |
74
+ ### Types
145
75
 
146
- You can import from the umbrella package for convenience, or from individual packages for smaller bundle sizes.
76
+ - `InferSchema`
77
+ - `InferFormSchema`
78
+ - core field, layout, and state types
147
79
 
148
- ## Related Packages
80
+ ## When To Use Individual Packages
149
81
 
150
- | Package | Description |
151
- | --------------------------- | ------------------------------------------ |
152
- | `@formspec/constraints` | Constraint definitions and validators |
153
- | `@formspec/validator` | JSON Schema validation for secure runtimes |
154
- | `@formspec/eslint-plugin` | ESLint rules for FormSpec |
155
- | `@formspec/language-server` | Language server for editor integration |
156
- | `@formspec/cli` | CLI tool for build-time schema generation |
157
- | `@formspec/playground` | Interactive browser editor (private) |
82
+ - Use `@formspec/build` directly for `generateSchemas()` and static TypeScript analysis.
83
+ - Use `@formspec/eslint-plugin` for lint rules.
84
+ - Use `@formspec/cli` for build-time artifact generation from files.
85
+ - Use `@formspec/validator` for runtime JSON Schema validation.
158
86
 
159
87
  ## License
160
88
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "formspec",
3
- "version": "0.1.0-alpha.17",
3
+ "version": "0.1.0-alpha.19",
4
4
  "description": "Type-safe form specifications that compile to JSON Schema and JSON Forms UI Schema",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",
@@ -18,10 +18,10 @@
18
18
  "README.md"
19
19
  ],
20
20
  "dependencies": {
21
- "@formspec/core": "0.1.0-alpha.17",
22
- "@formspec/dsl": "0.1.0-alpha.17",
23
- "@formspec/build": "0.1.0-alpha.17",
24
- "@formspec/runtime": "0.1.0-alpha.17"
21
+ "@formspec/core": "0.1.0-alpha.19",
22
+ "@formspec/dsl": "0.1.0-alpha.19",
23
+ "@formspec/build": "0.1.0-alpha.19",
24
+ "@formspec/runtime": "0.1.0-alpha.19"
25
25
  },
26
26
  "publishConfig": {
27
27
  "access": "public"