@formwright/schema 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Formwright contributors
+
+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

@@ -0,0 +1,20 @@
+# @formwright/schema
+
+Schema types and a dependency-free runtime validator for [Formwright](../../README.md).
+
+The schema is Formwright's public contract: plain, serializable data that both the
+runtime renderer and the codegen compiler consume. This package gives you the
+TypeScript types plus a validator that produces precise, path-addressed issues —
+ideal for repairing LLM-emitted schemas before they reach the runtime.
+
+```ts
+import { validateSchema, parseSchema } from "@formwright/schema";
+
+const result = validateSchema(unknownInput);
+if (!result.ok) {
+  for (const issue of result.issues) console.warn(issue.path, issue.message);
+}
+
+// or throw on failure:
+const schema = parseSchema(unknownInput);
+```

package/dist/index.cjs

@@ -0,0 +1,120 @@
+'use strict';
+
+// src/validate.ts
+var BUILTIN_TYPES = /* @__PURE__ */ new Set([
+  "text",
+  "number",
+  "email",
+  "password",
+  "textarea",
+  "select",
+  "checkbox",
+  "radio",
+  "group",
+  "collection"
+]);
+var CONTAINER_TYPES = /* @__PURE__ */ new Set(["group", "collection"]);
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+var Collector = class {
+  issues = [];
+  add(path, message) {
+    this.issues.push({ path, message });
+  }
+};
+function validateField(field, path, seenIds, c) {
+  if (!isRecord(field)) {
+    c.add(path, "field must be an object");
+    return;
+  }
+  const id = field["id"];
+  if (typeof id !== "string" || id.length === 0) {
+    c.add(`${path}.id`, "field.id must be a non-empty string");
+  } else if (seenIds.has(id)) {
+    c.add(`${path}.id`, `duplicate field id "${id}"`);
+  } else {
+    seenIds.add(id);
+  }
+  const type = field["type"];
+  if (typeof type !== "string" || type.length === 0) {
+    c.add(`${path}.type`, "field.type must be a non-empty string");
+  } else if (!BUILTIN_TYPES.has(type)) ;
+  if ((type === "select" || type === "radio") && field["options"] === void 0) {
+    c.add(`${path}.options`, `field of type "${type}" should declare options`);
+  }
+  if (typeof type === "string" && CONTAINER_TYPES.has(type)) {
+    const nested = field["fields"];
+    if (!Array.isArray(nested) || nested.length === 0) {
+      c.add(`${path}.fields`, `field of type "${type}" must declare a non-empty "fields" array`);
+    } else {
+      const childIds = /* @__PURE__ */ new Set();
+      nested.forEach((f, i) => validateField(f, `${path}.fields[${i}]`, childIds, c));
+    }
+  }
+}
+function validateSchema(input) {
+  const c = new Collector();
+  if (!isRecord(input)) {
+    c.add("$", "schema must be an object");
+    return { ok: false, issues: c.issues };
+  }
+  if (typeof input["id"] !== "string" || input["id"].length === 0) {
+    c.add("id", "schema.id must be a non-empty string");
+  }
+  if (typeof input["version"] !== "string" || input["version"].length === 0) {
+    c.add("version", "schema.version must be a non-empty string");
+  }
+  const fields = input["fields"];
+  if (!Array.isArray(fields)) {
+    c.add("fields", "schema.fields must be an array");
+  } else if (fields.length === 0) {
+    c.add("fields", "schema.fields must contain at least one field");
+  } else {
+    const seenIds = /* @__PURE__ */ new Set();
+    fields.forEach((f, i) => validateField(f, `fields[${i}]`, seenIds, c));
+  }
+  const providers = input["providers"];
+  if (providers !== void 0 && !isRecord(providers)) {
+    c.add("providers", "schema.providers must be an object when present");
+  }
+  const submit = input["submit"];
+  if (submit !== void 0 && !isRecord(submit)) {
+    c.add("submit", "schema.submit must be an object when present");
+  }
+  if (c.issues.length > 0) {
+    return { ok: false, issues: c.issues };
+  }
+  return { ok: true, value: input };
+}
+function parseSchema(input) {
+  const result = validateSchema(input);
+  if (!result.ok) {
+    const detail = result.issues.map((i) => `  - ${i.path}: ${i.message}`).join("\n");
+    throw new SchemaValidationError(`Invalid Formwright schema:
+${detail}`, result.issues);
+  }
+  return result.value;
+}
+var SchemaValidationError = class extends Error {
+  issues;
+  constructor(message, issues) {
+    super(message);
+    this.name = "SchemaValidationError";
+    this.issues = issues;
+  }
+};
+function isFormSchema(input) {
+  return validateSchema(input).ok;
+}
+function fieldIds(schema) {
+  return schema.fields.map((f) => f.id);
+}
+
+exports.SchemaValidationError = SchemaValidationError;
+exports.fieldIds = fieldIds;
+exports.isFormSchema = isFormSchema;
+exports.parseSchema = parseSchema;
+exports.validateSchema = validateSchema;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/validate.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Runtime validation of an unknown value into a typed {@link FormSchema}.\n *\n * Dependency-free and structural — its job is to give precise, path-addressed\n * errors so an LLM-emitted schema can be repaired (or rejected) before it ever\n * reaches the runtime. This validates the *schema shape*, not user form input\n * (that is the job of the per-field {@link ValidationSchema}).\n */\nimport type { FieldSchema, FieldType, FormSchema } from \"./types.js\";\n\nexport interface ValidationIssue {\n  /** JSON-pointer-ish path to the offending node, e.g. `fields[2].type`. */\n  readonly path: string;\n  readonly message: string;\n}\n\nexport type ValidationResult =\n  | { readonly ok: true; readonly value: FormSchema }\n  | { readonly ok: false; readonly issues: readonly ValidationIssue[] };\n\nconst BUILTIN_TYPES: ReadonlySet<string> = new Set<FieldType>([\n  \"text\",\n  \"number\",\n  \"email\",\n  \"password\",\n  \"textarea\",\n  \"select\",\n  \"checkbox\",\n  \"radio\",\n  \"group\",\n  \"collection\",\n]);\n\nconst CONTAINER_TYPES: ReadonlySet<string> = new Set<FieldType>([\"group\", \"collection\"]);\n\nfunction isRecord(v: unknown): v is Record<string, unknown> {\n  return typeof v === \"object\" && v !== null && !Array.isArray(v);\n}\n\nclass Collector {\n  readonly issues: ValidationIssue[] = [];\n  add(path: string, message: string): void {\n    this.issues.push({ path, message });\n  }\n}\n\nfunction validateField(field: unknown, path: string, seenIds: Set<string>, c: Collector): void {\n  if (!isRecord(field)) {\n    c.add(path, \"field must be an object\");\n    return;\n  }\n\n  const id = field[\"id\"];\n  if (typeof id !== \"string\" || id.length === 0) {\n    c.add(`${path}.id`, \"field.id must be a non-empty string\");\n  } else if (seenIds.has(id)) {\n    c.add(`${path}.id`, `duplicate field id \"${id}\"`);\n  } else {\n    seenIds.add(id);\n  }\n\n  const type = field[\"type\"];\n  if (typeof type !== \"string\" || type.length === 0) {\n    c.add(`${path}.type`, \"field.type must be a non-empty string\");\n  } else if (!BUILTIN_TYPES.has(type)) {\n    // Unknown types are allowed (custom widgets) but flagged as a hint, not an error.\n    // We intentionally do not push an issue here.\n  }\n\n  if ((type === \"select\" || type === \"radio\") && field[\"options\"] === undefined) {\n    c.add(`${path}.options`, `field of type \"${type}\" should declare options`);\n  }\n\n  // Containers (group/collection) must declare nested fields; recurse so nested\n  // problems surface with a precise path (e.g. `fields[3].fields[0].id`).\n  if (typeof type === \"string\" && CONTAINER_TYPES.has(type)) {\n    const nested = field[\"fields\"];\n    if (!Array.isArray(nested) || nested.length === 0) {\n      c.add(`${path}.fields`, `field of type \"${type}\" must declare a non-empty \"fields\" array`);\n    } else {\n      // A container opens a new naming scope: child ids are unique within it, not globally.\n      const childIds = new Set<string>();\n      nested.forEach((f, i) => validateField(f, `${path}.fields[${i}]`, childIds, c));\n    }\n  }\n}\n\n/** Validate an unknown value as a {@link FormSchema}. Never throws. */\nexport function validateSchema(input: unknown): ValidationResult {\n  const c = new Collector();\n\n  if (!isRecord(input)) {\n    c.add(\"$\", \"schema must be an object\");\n    return { ok: false, issues: c.issues };\n  }\n\n  if (typeof input[\"id\"] !== \"string\" || (input[\"id\"] as string).length === 0) {\n    c.add(\"id\", \"schema.id must be a non-empty string\");\n  }\n  if (typeof input[\"version\"] !== \"string\" || (input[\"version\"] as string).length === 0) {\n    c.add(\"version\", \"schema.version must be a non-empty string\");\n  }\n\n  const fields = input[\"fields\"];\n  if (!Array.isArray(fields)) {\n    c.add(\"fields\", \"schema.fields must be an array\");\n  } else if (fields.length === 0) {\n    c.add(\"fields\", \"schema.fields must contain at least one field\");\n  } else {\n    const seenIds = new Set<string>();\n    fields.forEach((f, i) => validateField(f, `fields[${i}]`, seenIds, c));\n  }\n\n  const providers = input[\"providers\"];\n  if (providers !== undefined && !isRecord(providers)) {\n    c.add(\"providers\", \"schema.providers must be an object when present\");\n  }\n\n  const submit = input[\"submit\"];\n  if (submit !== undefined && !isRecord(submit)) {\n    c.add(\"submit\", \"schema.submit must be an object when present\");\n  }\n\n  if (c.issues.length > 0) {\n    return { ok: false, issues: c.issues };\n  }\n  return { ok: true, value: input as unknown as FormSchema };\n}\n\n/** Validate and throw a single aggregated error on failure. Convenience for trusted input. */\nexport function parseSchema(input: unknown): FormSchema {\n  const result = validateSchema(input);\n  if (!result.ok) {\n    const detail = result.issues.map((i) => `  - ${i.path}: ${i.message}`).join(\"\\n\");\n    throw new SchemaValidationError(`Invalid Formwright schema:\\n${detail}`, result.issues);\n  }\n  return result.value;\n}\n\nexport class SchemaValidationError extends Error {\n  readonly issues: readonly ValidationIssue[];\n  constructor(message: string, issues: readonly ValidationIssue[]) {\n    super(message);\n    this.name = \"SchemaValidationError\";\n    this.issues = issues;\n  }\n}\n\n/** Type guard form of {@link validateSchema}. */\nexport function isFormSchema(input: unknown): input is FormSchema {\n  return validateSchema(input).ok;\n}\n\n/** Convenience: list the field ids declared by a schema, in order. */\nexport function fieldIds(schema: FormSchema): string[] {\n  return schema.fields.map((f: FieldSchema) => f.id);\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,170 @@
+/**
+ * Formwright schema types — the public, serializable contract.
+ *
+ * A schema is plain data: hand-written, version-controlled, or emitted by an LLM.
+ * Everything the runtime and the codegen compiler need is expressed here as data,
+ * never as code, so a schema can round-trip through JSON.
+ */
+/** Primitive value a form field can hold. */
+type FieldValue = string | number | boolean | null | undefined | FieldValue[];
+/** A reference to a value provided by a registered provider, expressed as a sigil object. */
+type ProviderRef = {
+    readonly $t: string;
+    readonly args?: Record<string, FieldValue>;
+} | {
+    readonly $query: string | readonly [string, Record<string, unknown>?];
+} | {
+    readonly $theme: string;
+};
+/** A value in the schema that may be a literal or resolved through a provider at runtime. */
+type Resolvable<T> = T | ProviderRef;
+/**
+ * A condition expression evaluated against current form values.
+ *
+ * Intentionally a small, sandboxed JSONLogic-style algebra — it is *data*, never
+ * `eval`. `var` reads a field value; the rest compose comparisons and booleans.
+ */
+type Condition = boolean | {
+    readonly var: string;
+} | {
+    readonly "==": readonly [Condition, Condition];
+} | {
+    readonly "!=": readonly [Condition, Condition];
+} | {
+    readonly ">": readonly [Condition, Condition];
+} | {
+    readonly ">=": readonly [Condition, Condition];
+} | {
+    readonly "<": readonly [Condition, Condition];
+} | {
+    readonly "<=": readonly [Condition, Condition];
+} | {
+    readonly in: readonly [Condition, Condition];
+} | {
+    readonly not: Condition;
+} | {
+    readonly and: readonly Condition[];
+} | {
+    readonly or: readonly Condition[];
+} | FieldValue;
+/** Built-in field widget kinds. Extensible: any string maps to a registered widget. */
+type FieldType = "text" | "number" | "email" | "password" | "textarea" | "select" | "checkbox" | "radio" | "group" | "collection" | (string & {});
+/** Validation descriptor — declarative, mapped to a Standard Schema validator at runtime. */
+interface ValidationSchema {
+    readonly kind: "string" | "number" | "boolean" | "array";
+    readonly required?: boolean;
+    readonly min?: number;
+    readonly max?: number;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly pattern?: string;
+    readonly format?: "email" | "url" | "uuid";
+    readonly message?: Resolvable<string>;
+}
+/** A selectable option for `select` / `radio` fields. */
+interface FieldOption {
+    readonly label: Resolvable<string>;
+    readonly value: FieldValue;
+}
+/** A single field in the form. Resolved to a widget by `type`, keyed by `id`. */
+interface FieldSchema {
+    readonly id: string;
+    readonly type: FieldType;
+    readonly label?: Resolvable<string>;
+    readonly placeholder?: Resolvable<string>;
+    readonly help?: Resolvable<string>;
+    readonly defaultValue?: FieldValue;
+    readonly options?: Resolvable<readonly FieldOption[]>;
+    readonly validation?: ValidationSchema;
+    /** Field is rendered only when this condition holds (default: always). */
+    readonly visibleWhen?: Condition;
+    /** Field is interactive only when this condition holds (default: always). */
+    readonly enabledWhen?: Condition;
+    /** Field is required only when this condition holds (overrides validation.required). */
+    readonly requiredWhen?: Condition;
+    /**
+     * Child fields — required for `group` (object) and `collection` (array-of-groups).
+     * A child's conditions resolve names lexically: a sibling first, then the
+     * enclosing scope, up to the form root (so an outer toggle can hide a field
+     * nested inside a group or a collection row).
+     */
+    readonly fields?: readonly FieldSchema[];
+    /**
+     * Container layout:
+     *  - `group`: `"fieldset"` (default) or `"accordion"` (collapsible section).
+     *  - `collection`: `"list"` (default), `"cards"`, or `"accordion"` (each row collapsible).
+     */
+    readonly layout?: "fieldset" | "accordion" | "list" | "cards";
+    /** `collection` only: label for each row, e.g. "Contact". */
+    readonly itemLabel?: Resolvable<string>;
+    /** `collection` only: text for the add-row button (default: "Add"). */
+    readonly addLabel?: Resolvable<string>;
+    /** `collection` only: minimum / maximum number of rows. */
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    /** Arbitrary widget-specific config, passed through to the renderer. */
+    readonly props?: Record<string, unknown>;
+}
+/** Declares a provider the form depends on, resolved by the host at runtime. */
+interface ProviderDecl {
+    readonly type: "i18n" | "tanstack-query" | "theme" | (string & {});
+    readonly [key: string]: unknown;
+}
+/** How the form submits: transform the payload, send it, handle success/error. */
+interface SubmitSchema {
+    /** Name of a registered transform applied to values before sending. */
+    readonly transform?: string;
+    readonly endpoint?: {
+        readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+        readonly url: string;
+    };
+    /** Name of a registered success handler. */
+    readonly onSuccess?: string;
+    /** Name of a registered error handler. */
+    readonly onError?: string;
+}
+/** The root form schema. */
+interface FormSchema {
+    readonly id: string;
+    readonly version: string;
+    readonly title?: Resolvable<string>;
+    readonly providers?: Record<string, ProviderDecl>;
+    readonly fields: readonly FieldSchema[];
+    readonly submit?: SubmitSchema;
+}
+
+/**
+ * Runtime validation of an unknown value into a typed {@link FormSchema}.
+ *
+ * Dependency-free and structural — its job is to give precise, path-addressed
+ * errors so an LLM-emitted schema can be repaired (or rejected) before it ever
+ * reaches the runtime. This validates the *schema shape*, not user form input
+ * (that is the job of the per-field {@link ValidationSchema}).
+ */
+
+interface ValidationIssue {
+    /** JSON-pointer-ish path to the offending node, e.g. `fields[2].type`. */
+    readonly path: string;
+    readonly message: string;
+}
+type ValidationResult = {
+    readonly ok: true;
+    readonly value: FormSchema;
+} | {
+    readonly ok: false;
+    readonly issues: readonly ValidationIssue[];
+};
+/** Validate an unknown value as a {@link FormSchema}. Never throws. */
+declare function validateSchema(input: unknown): ValidationResult;
+/** Validate and throw a single aggregated error on failure. Convenience for trusted input. */
+declare function parseSchema(input: unknown): FormSchema;
+declare class SchemaValidationError extends Error {
+    readonly issues: readonly ValidationIssue[];
+    constructor(message: string, issues: readonly ValidationIssue[]);
+}
+/** Type guard form of {@link validateSchema}. */
+declare function isFormSchema(input: unknown): input is FormSchema;
+/** Convenience: list the field ids declared by a schema, in order. */
+declare function fieldIds(schema: FormSchema): string[];
+
+export { type Condition, type FieldOption, type FieldSchema, type FieldType, type FieldValue, type FormSchema, type ProviderDecl, type ProviderRef, type Resolvable, SchemaValidationError, type SubmitSchema, type ValidationIssue, type ValidationResult, type ValidationSchema, fieldIds, isFormSchema, parseSchema, validateSchema };

package/dist/index.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Formwright schema types — the public, serializable contract.
+ *
+ * A schema is plain data: hand-written, version-controlled, or emitted by an LLM.
+ * Everything the runtime and the codegen compiler need is expressed here as data,
+ * never as code, so a schema can round-trip through JSON.
+ */
+/** Primitive value a form field can hold. */
+type FieldValue = string | number | boolean | null | undefined | FieldValue[];
+/** A reference to a value provided by a registered provider, expressed as a sigil object. */
+type ProviderRef = {
+    readonly $t: string;
+    readonly args?: Record<string, FieldValue>;
+} | {
+    readonly $query: string | readonly [string, Record<string, unknown>?];
+} | {
+    readonly $theme: string;
+};
+/** A value in the schema that may be a literal or resolved through a provider at runtime. */
+type Resolvable<T> = T | ProviderRef;
+/**
+ * A condition expression evaluated against current form values.
+ *
+ * Intentionally a small, sandboxed JSONLogic-style algebra — it is *data*, never
+ * `eval`. `var` reads a field value; the rest compose comparisons and booleans.
+ */
+type Condition = boolean | {
+    readonly var: string;
+} | {
+    readonly "==": readonly [Condition, Condition];
+} | {
+    readonly "!=": readonly [Condition, Condition];
+} | {
+    readonly ">": readonly [Condition, Condition];
+} | {
+    readonly ">=": readonly [Condition, Condition];
+} | {
+    readonly "<": readonly [Condition, Condition];
+} | {
+    readonly "<=": readonly [Condition, Condition];
+} | {
+    readonly in: readonly [Condition, Condition];
+} | {
+    readonly not: Condition;
+} | {
+    readonly and: readonly Condition[];
+} | {
+    readonly or: readonly Condition[];
+} | FieldValue;
+/** Built-in field widget kinds. Extensible: any string maps to a registered widget. */
+type FieldType = "text" | "number" | "email" | "password" | "textarea" | "select" | "checkbox" | "radio" | "group" | "collection" | (string & {});
+/** Validation descriptor — declarative, mapped to a Standard Schema validator at runtime. */
+interface ValidationSchema {
+    readonly kind: "string" | "number" | "boolean" | "array";
+    readonly required?: boolean;
+    readonly min?: number;
+    readonly max?: number;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly pattern?: string;
+    readonly format?: "email" | "url" | "uuid";
+    readonly message?: Resolvable<string>;
+}
+/** A selectable option for `select` / `radio` fields. */
+interface FieldOption {
+    readonly label: Resolvable<string>;
+    readonly value: FieldValue;
+}
+/** A single field in the form. Resolved to a widget by `type`, keyed by `id`. */
+interface FieldSchema {
+    readonly id: string;
+    readonly type: FieldType;
+    readonly label?: Resolvable<string>;
+    readonly placeholder?: Resolvable<string>;
+    readonly help?: Resolvable<string>;
+    readonly defaultValue?: FieldValue;
+    readonly options?: Resolvable<readonly FieldOption[]>;
+    readonly validation?: ValidationSchema;
+    /** Field is rendered only when this condition holds (default: always). */
+    readonly visibleWhen?: Condition;
+    /** Field is interactive only when this condition holds (default: always). */
+    readonly enabledWhen?: Condition;
+    /** Field is required only when this condition holds (overrides validation.required). */
+    readonly requiredWhen?: Condition;
+    /**
+     * Child fields — required for `group` (object) and `collection` (array-of-groups).
+     * A child's conditions resolve names lexically: a sibling first, then the
+     * enclosing scope, up to the form root (so an outer toggle can hide a field
+     * nested inside a group or a collection row).
+     */
+    readonly fields?: readonly FieldSchema[];
+    /**
+     * Container layout:
+     *  - `group`: `"fieldset"` (default) or `"accordion"` (collapsible section).
+     *  - `collection`: `"list"` (default), `"cards"`, or `"accordion"` (each row collapsible).
+     */
+    readonly layout?: "fieldset" | "accordion" | "list" | "cards";
+    /** `collection` only: label for each row, e.g. "Contact". */
+    readonly itemLabel?: Resolvable<string>;
+    /** `collection` only: text for the add-row button (default: "Add"). */
+    readonly addLabel?: Resolvable<string>;
+    /** `collection` only: minimum / maximum number of rows. */
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    /** Arbitrary widget-specific config, passed through to the renderer. */
+    readonly props?: Record<string, unknown>;
+}
+/** Declares a provider the form depends on, resolved by the host at runtime. */
+interface ProviderDecl {
+    readonly type: "i18n" | "tanstack-query" | "theme" | (string & {});
+    readonly [key: string]: unknown;
+}
+/** How the form submits: transform the payload, send it, handle success/error. */
+interface SubmitSchema {
+    /** Name of a registered transform applied to values before sending. */
+    readonly transform?: string;
+    readonly endpoint?: {
+        readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+        readonly url: string;
+    };
+    /** Name of a registered success handler. */
+    readonly onSuccess?: string;
+    /** Name of a registered error handler. */
+    readonly onError?: string;
+}
+/** The root form schema. */
+interface FormSchema {
+    readonly id: string;
+    readonly version: string;
+    readonly title?: Resolvable<string>;
+    readonly providers?: Record<string, ProviderDecl>;
+    readonly fields: readonly FieldSchema[];
+    readonly submit?: SubmitSchema;
+}
+
+/**
+ * Runtime validation of an unknown value into a typed {@link FormSchema}.
+ *
+ * Dependency-free and structural — its job is to give precise, path-addressed
+ * errors so an LLM-emitted schema can be repaired (or rejected) before it ever
+ * reaches the runtime. This validates the *schema shape*, not user form input
+ * (that is the job of the per-field {@link ValidationSchema}).
+ */
+
+interface ValidationIssue {
+    /** JSON-pointer-ish path to the offending node, e.g. `fields[2].type`. */
+    readonly path: string;
+    readonly message: string;
+}
+type ValidationResult = {
+    readonly ok: true;
+    readonly value: FormSchema;
+} | {
+    readonly ok: false;
+    readonly issues: readonly ValidationIssue[];
+};
+/** Validate an unknown value as a {@link FormSchema}. Never throws. */
+declare function validateSchema(input: unknown): ValidationResult;
+/** Validate and throw a single aggregated error on failure. Convenience for trusted input. */
+declare function parseSchema(input: unknown): FormSchema;
+declare class SchemaValidationError extends Error {
+    readonly issues: readonly ValidationIssue[];
+    constructor(message: string, issues: readonly ValidationIssue[]);
+}
+/** Type guard form of {@link validateSchema}. */
+declare function isFormSchema(input: unknown): input is FormSchema;
+/** Convenience: list the field ids declared by a schema, in order. */
+declare function fieldIds(schema: FormSchema): string[];
+
+export { type Condition, type FieldOption, type FieldSchema, type FieldType, type FieldValue, type FormSchema, type ProviderDecl, type ProviderRef, type Resolvable, SchemaValidationError, type SubmitSchema, type ValidationIssue, type ValidationResult, type ValidationSchema, fieldIds, isFormSchema, parseSchema, validateSchema };

package/dist/index.js

@@ -0,0 +1,114 @@
+// src/validate.ts
+var BUILTIN_TYPES = /* @__PURE__ */ new Set([
+  "text",
+  "number",
+  "email",
+  "password",
+  "textarea",
+  "select",
+  "checkbox",
+  "radio",
+  "group",
+  "collection"
+]);
+var CONTAINER_TYPES = /* @__PURE__ */ new Set(["group", "collection"]);
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+var Collector = class {
+  issues = [];
+  add(path, message) {
+    this.issues.push({ path, message });
+  }
+};
+function validateField(field, path, seenIds, c) {
+  if (!isRecord(field)) {
+    c.add(path, "field must be an object");
+    return;
+  }
+  const id = field["id"];
+  if (typeof id !== "string" || id.length === 0) {
+    c.add(`${path}.id`, "field.id must be a non-empty string");
+  } else if (seenIds.has(id)) {
+    c.add(`${path}.id`, `duplicate field id "${id}"`);
+  } else {
+    seenIds.add(id);
+  }
+  const type = field["type"];
+  if (typeof type !== "string" || type.length === 0) {
+    c.add(`${path}.type`, "field.type must be a non-empty string");
+  } else if (!BUILTIN_TYPES.has(type)) ;
+  if ((type === "select" || type === "radio") && field["options"] === void 0) {
+    c.add(`${path}.options`, `field of type "${type}" should declare options`);
+  }
+  if (typeof type === "string" && CONTAINER_TYPES.has(type)) {
+    const nested = field["fields"];
+    if (!Array.isArray(nested) || nested.length === 0) {
+      c.add(`${path}.fields`, `field of type "${type}" must declare a non-empty "fields" array`);
+    } else {
+      const childIds = /* @__PURE__ */ new Set();
+      nested.forEach((f, i) => validateField(f, `${path}.fields[${i}]`, childIds, c));
+    }
+  }
+}
+function validateSchema(input) {
+  const c = new Collector();
+  if (!isRecord(input)) {
+    c.add("$", "schema must be an object");
+    return { ok: false, issues: c.issues };
+  }
+  if (typeof input["id"] !== "string" || input["id"].length === 0) {
+    c.add("id", "schema.id must be a non-empty string");
+  }
+  if (typeof input["version"] !== "string" || input["version"].length === 0) {
+    c.add("version", "schema.version must be a non-empty string");
+  }
+  const fields = input["fields"];
+  if (!Array.isArray(fields)) {
+    c.add("fields", "schema.fields must be an array");
+  } else if (fields.length === 0) {
+    c.add("fields", "schema.fields must contain at least one field");
+  } else {
+    const seenIds = /* @__PURE__ */ new Set();
+    fields.forEach((f, i) => validateField(f, `fields[${i}]`, seenIds, c));
+  }
+  const providers = input["providers"];
+  if (providers !== void 0 && !isRecord(providers)) {
+    c.add("providers", "schema.providers must be an object when present");
+  }
+  const submit = input["submit"];
+  if (submit !== void 0 && !isRecord(submit)) {
+    c.add("submit", "schema.submit must be an object when present");
+  }
+  if (c.issues.length > 0) {
+    return { ok: false, issues: c.issues };
+  }
+  return { ok: true, value: input };
+}
+function parseSchema(input) {
+  const result = validateSchema(input);
+  if (!result.ok) {
+    const detail = result.issues.map((i) => `  - ${i.path}: ${i.message}`).join("\n");
+    throw new SchemaValidationError(`Invalid Formwright schema:
+${detail}`, result.issues);
+  }
+  return result.value;
+}
+var SchemaValidationError = class extends Error {
+  issues;
+  constructor(message, issues) {
+    super(message);
+    this.name = "SchemaValidationError";
+    this.issues = issues;
+  }
+};
+function isFormSchema(input) {
+  return validateSchema(input).ok;
+}
+function fieldIds(schema) {
+  return schema.fields.map((f) => f.id);
+}
+
+export { SchemaValidationError, fieldIds, isFormSchema, parseSchema, validateSchema };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/validate.ts"],"names":[],"mappings":";AAoBA,IAAM,aAAA,uBAAyC,GAAA,CAAe;AAAA,EAC5D,MAAA;AAAA,EACA,QAAA;AAAA,EACA,OAAA;AAAA,EACA,UAAA;AAAA,EACA,UAAA;AAAA,EACA,QAAA;AAAA,EACA,UAAA;AAAA,EACA,OAAA;AAAA,EACA,OAAA;AAAA,EACA;AACF,CAAC,CAAA;AAED,IAAM,kCAAuC,IAAI,GAAA,CAAe,CAAC,OAAA,EAAS,YAAY,CAAC,CAAA;AAEvF,SAAS,SAAS,CAAA,EAA0C;AAC1D,EAAA,OAAO,OAAO,MAAM,QAAA,IAAY,CAAA,KAAM,QAAQ,CAAC,KAAA,CAAM,QAAQ,CAAC,CAAA;AAChE;AAEA,IAAM,YAAN,MAAgB;AAAA,EACL,SAA4B,EAAC;AAAA,EACtC,GAAA,CAAI,MAAc,OAAA,EAAuB;AACvC,IAAA,IAAA,CAAK,MAAA,CAAO,IAAA,CAAK,EAAE,IAAA,EAAM,SAAS,CAAA;AAAA,EACpC;AACF,CAAA;AAEA,SAAS,aAAA,CAAc,KAAA,EAAgB,IAAA,EAAc,OAAA,EAAsB,CAAA,EAAoB;AAC7F,EAAA,IAAI,CAAC,QAAA,CAAS,KAAK,CAAA,EAAG;AACpB,IAAA,CAAA,CAAE,GAAA,CAAI,MAAM,yBAAyB,CAAA;AACrC,IAAA;AAAA,EACF;AAEA,EAAA,MAAM,EAAA,GAAK,MAAM,IAAI,CAAA;AACrB,EAAA,IAAI,OAAO,EAAA,KAAO,QAAA,IAAY,EAAA,CAAG,WAAW,CAAA,EAAG;AAC7C,IAAA,CAAA,CAAE,GAAA,CAAI,CAAA,EAAG,IAAI,CAAA,GAAA,CAAA,EAAO,qCAAqC,CAAA;AAAA,EAC3D,CAAA,MAAA,IAAW,OAAA,CAAQ,GAAA,CAAI,EAAE,CAAA,EAAG;AAC1B,IAAA,CAAA,CAAE,IAAI,CAAA,EAAG,IAAI,CAAA,GAAA,CAAA,EAAO,CAAA,oBAAA,EAAuB,EAAE,CAAA,CAAA,CAAG,CAAA;AAAA,EAClD,CAAA,MAAO;AACL,IAAA,OAAA,CAAQ,IAAI,EAAE,CAAA;AAAA,EAChB;AAEA,EAAA,MAAM,IAAA,GAAO,MAAM,MAAM,CAAA;AACzB,EAAA,IAAI,OAAO,IAAA,KAAS,QAAA,IAAY,IAAA,CAAK,WAAW,CAAA,EAAG;AACjD,IAAA,CAAA,CAAE,GAAA,CAAI,CAAA,EAAG,IAAI,CAAA,KAAA,CAAA,EAAS,uCAAuC,CAAA;AAAA,EAC/D,CAAA,MAAA,IAAW,CAAC,aAAA,CAAc,GAAA,CAAI,IAAI,CAAA,EAAG;AAKrC,EAAA,IAAA,CAAK,SAAS,QAAA,IAAY,IAAA,KAAS,YAAY,KAAA,CAAM,SAAS,MAAM,MAAA,EAAW;AAC7E,IAAA,CAAA,CAAE,IAAI,CAAA,EAAG,IAAI,CAAA,QAAA,CAAA,EAAY,CAAA,eAAA,EAAkB,IAAI,CAAA,wBAAA,CAA0B,CAAA;AAAA,EAC3E;AAIA,EAAA,IAAI,OAAO,IAAA,KAAS,QAAA,IAAY,eAAA,CAAgB,GAAA,CAAI,IAAI,CAAA,EAAG;AACzD,IAAA,MAAM,MAAA,GAAS,MAAM,QAAQ,CAAA;AAC7B,IAAA,IAAI,CAAC,KAAA,CAAM,OAAA,CAAQ,MAAM,CAAA,IAAK,MAAA,CAAO,WAAW,CAAA,EAAG;AACjD,MAAA,CAAA,CAAE,IAAI,CAAA,EAAG,IAAI,CAAA,OAAA,CAAA,EAAW,CAAA,eAAA,EAAkB,IAAI,CAAA,yCAAA,CAA2C,CAAA;AAAA,IAC3F,CAAA,MAAO;AAEL,MAAA,MAAM,QAAA,uBAAe,GAAA,EAAY;AACjC,MAAA,MAAA,CAAO,OAAA,CAAQ,CAAC,CAAA,EAAG,CAAA,KAAM,aAAA,CAAc,CAAA,EAAG,CAAA,EAAG,IAAI,CAAA,QAAA,EAAW,CAAC,CAAA,CAAA,CAAA,EAAK,QAAA,EAAU,CAAC,CAAC,CAAA;AAAA,IAChF;AAAA,EACF;AACF;AAGO,SAAS,eAAe,KAAA,EAAkC;AAC/D,EAAA,MAAM,CAAA,GAAI,IAAI,SAAA,EAAU;AAExB,EAAA,IAAI,CAAC,QAAA,CAAS,KAAK,CAAA,EAAG;AACpB,IAAA,CAAA,CAAE,GAAA,CAAI,KAAK,0BAA0B,CAAA;AACrC,IAAA,OAAO,EAAE,EAAA,EAAI,KAAA,EAAO,MAAA,EAAQ,EAAE,MAAA,EAAO;AAAA,EACvC;AAEA,EAAA,IAAI,OAAO,MAAM,IAAI,CAAA,KAAM,YAAa,KAAA,CAAM,IAAI,CAAA,CAAa,MAAA,KAAW,CAAA,EAAG;AAC3E,IAAA,CAAA,CAAE,GAAA,CAAI,MAAM,sCAAsC,CAAA;AAAA,EACpD;AACA,EAAA,IAAI,OAAO,MAAM,SAAS,CAAA,KAAM,YAAa,KAAA,CAAM,SAAS,CAAA,CAAa,MAAA,KAAW,CAAA,EAAG;AACrF,IAAA,CAAA,CAAE,GAAA,CAAI,WAAW,2CAA2C,CAAA;AAAA,EAC9D;AAEA,EAAA,MAAM,MAAA,GAAS,MAAM,QAAQ,CAAA;AAC7B,EAAA,IAAI,CAAC,KAAA,CAAM,OAAA,CAAQ,MAAM,CAAA,EAAG;AAC1B,IAAA,CAAA,CAAE,GAAA,CAAI,UAAU,gCAAgC,CAAA;AAAA,EAClD,CAAA,MAAA,IAAW,MAAA,CAAO,MAAA,KAAW,CAAA,EAAG;AAC9B,IAAA,CAAA,CAAE,GAAA,CAAI,UAAU,+CAA+C,CAAA;AAAA,EACjE,CAAA,MAAO;AACL,IAAA,MAAM,OAAA,uBAAc,GAAA,EAAY;AAChC,IAAA,MAAA,CAAO,OAAA,CAAQ,CAAC,CAAA,EAAG,CAAA,KAAM,aAAA,CAAc,CAAA,EAAG,CAAA,OAAA,EAAU,CAAC,CAAA,CAAA,CAAA,EAAK,OAAA,EAAS,CAAC,CAAC,CAAA;AAAA,EACvE;AAEA,EAAA,MAAM,SAAA,GAAY,MAAM,WAAW,CAAA;AACnC,EAAA,IAAI,SAAA,KAAc,MAAA,IAAa,CAAC,QAAA,CAAS,SAAS,CAAA,EAAG;AACnD,IAAA,CAAA,CAAE,GAAA,CAAI,aAAa,iDAAiD,CAAA;AAAA,EACtE;AAEA,EAAA,MAAM,MAAA,GAAS,MAAM,QAAQ,CAAA;AAC7B,EAAA,IAAI,MAAA,KAAW,MAAA,IAAa,CAAC,QAAA,CAAS,MAAM,CAAA,EAAG;AAC7C,IAAA,CAAA,CAAE,GAAA,CAAI,UAAU,8CAA8C,CAAA;AAAA,EAChE;AAEA,EAAA,IAAI,CAAA,CAAE,MAAA,CAAO,MAAA,GAAS,CAAA,EAAG;AACvB,IAAA,OAAO,EAAE,EAAA,EAAI,KAAA,EAAO,MAAA,EAAQ,EAAE,MAAA,EAAO;AAAA,EACvC;AACA,EAAA,OAAO,EAAE,EAAA,EAAI,IAAA,EAAM,KAAA,EAAO,KAAA,EAA+B;AAC3D;AAGO,SAAS,YAAY,KAAA,EAA4B;AACtD,EAAA,MAAM,MAAA,GAAS,eAAe,KAAK,CAAA;AACnC,EAAA,IAAI,CAAC,OAAO,EAAA,EAAI;AACd,IAAA,MAAM,MAAA,GAAS,MAAA,CAAO,MAAA,CAAO,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,IAAA,EAAO,CAAA,CAAE,IAAI,KAAK,CAAA,CAAE,OAAO,CAAA,CAAE,CAAA,CAAE,KAAK,IAAI,CAAA;AAChF,IAAA,MAAM,IAAI,qBAAA,CAAsB,CAAA;AAAA,EAA+B,MAAM,CAAA,CAAA,EAAI,MAAA,CAAO,MAAM,CAAA;AAAA,EACxF;AACA,EAAA,OAAO,MAAA,CAAO,KAAA;AAChB;AAEO,IAAM,qBAAA,GAAN,cAAoC,KAAA,CAAM;AAAA,EACtC,MAAA;AAAA,EACT,WAAA,CAAY,SAAiB,MAAA,EAAoC;AAC/D,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,uBAAA;AACZ,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AAAA,EAChB;AACF;AAGO,SAAS,aAAa,KAAA,EAAqC;AAChE,EAAA,OAAO,cAAA,CAAe,KAAK,CAAA,CAAE,EAAA;AAC/B;AAGO,SAAS,SAAS,MAAA,EAA8B;AACrD,EAAA,OAAO,OAAO,MAAA,CAAO,GAAA,CAAI,CAAC,CAAA,KAAmB,EAAE,EAAE,CAAA;AACnD","file":"index.js","sourcesContent":["/**\n * Runtime validation of an unknown value into a typed {@link FormSchema}.\n *\n * Dependency-free and structural — its job is to give precise, path-addressed\n * errors so an LLM-emitted schema can be repaired (or rejected) before it ever\n * reaches the runtime. This validates the *schema shape*, not user form input\n * (that is the job of the per-field {@link ValidationSchema}).\n */\nimport type { FieldSchema, FieldType, FormSchema } from \"./types.js\";\n\nexport interface ValidationIssue {\n  /** JSON-pointer-ish path to the offending node, e.g. `fields[2].type`. */\n  readonly path: string;\n  readonly message: string;\n}\n\nexport type ValidationResult =\n  | { readonly ok: true; readonly value: FormSchema }\n  | { readonly ok: false; readonly issues: readonly ValidationIssue[] };\n\nconst BUILTIN_TYPES: ReadonlySet<string> = new Set<FieldType>([\n  \"text\",\n  \"number\",\n  \"email\",\n  \"password\",\n  \"textarea\",\n  \"select\",\n  \"checkbox\",\n  \"radio\",\n  \"group\",\n  \"collection\",\n]);\n\nconst CONTAINER_TYPES: ReadonlySet<string> = new Set<FieldType>([\"group\", \"collection\"]);\n\nfunction isRecord(v: unknown): v is Record<string, unknown> {\n  return typeof v === \"object\" && v !== null && !Array.isArray(v);\n}\n\nclass Collector {\n  readonly issues: ValidationIssue[] = [];\n  add(path: string, message: string): void {\n    this.issues.push({ path, message });\n  }\n}\n\nfunction validateField(field: unknown, path: string, seenIds: Set<string>, c: Collector): void {\n  if (!isRecord(field)) {\n    c.add(path, \"field must be an object\");\n    return;\n  }\n\n  const id = field[\"id\"];\n  if (typeof id !== \"string\" || id.length === 0) {\n    c.add(`${path}.id`, \"field.id must be a non-empty string\");\n  } else if (seenIds.has(id)) {\n    c.add(`${path}.id`, `duplicate field id \"${id}\"`);\n  } else {\n    seenIds.add(id);\n  }\n\n  const type = field[\"type\"];\n  if (typeof type !== \"string\" || type.length === 0) {\n    c.add(`${path}.type`, \"field.type must be a non-empty string\");\n  } else if (!BUILTIN_TYPES.has(type)) {\n    // Unknown types are allowed (custom widgets) but flagged as a hint, not an error.\n    // We intentionally do not push an issue here.\n  }\n\n  if ((type === \"select\" || type === \"radio\") && field[\"options\"] === undefined) {\n    c.add(`${path}.options`, `field of type \"${type}\" should declare options`);\n  }\n\n  // Containers (group/collection) must declare nested fields; recurse so nested\n  // problems surface with a precise path (e.g. `fields[3].fields[0].id`).\n  if (typeof type === \"string\" && CONTAINER_TYPES.has(type)) {\n    const nested = field[\"fields\"];\n    if (!Array.isArray(nested) || nested.length === 0) {\n      c.add(`${path}.fields`, `field of type \"${type}\" must declare a non-empty \"fields\" array`);\n    } else {\n      // A container opens a new naming scope: child ids are unique within it, not globally.\n      const childIds = new Set<string>();\n      nested.forEach((f, i) => validateField(f, `${path}.fields[${i}]`, childIds, c));\n    }\n  }\n}\n\n/** Validate an unknown value as a {@link FormSchema}. Never throws. */\nexport function validateSchema(input: unknown): ValidationResult {\n  const c = new Collector();\n\n  if (!isRecord(input)) {\n    c.add(\"$\", \"schema must be an object\");\n    return { ok: false, issues: c.issues };\n  }\n\n  if (typeof input[\"id\"] !== \"string\" || (input[\"id\"] as string).length === 0) {\n    c.add(\"id\", \"schema.id must be a non-empty string\");\n  }\n  if (typeof input[\"version\"] !== \"string\" || (input[\"version\"] as string).length === 0) {\n    c.add(\"version\", \"schema.version must be a non-empty string\");\n  }\n\n  const fields = input[\"fields\"];\n  if (!Array.isArray(fields)) {\n    c.add(\"fields\", \"schema.fields must be an array\");\n  } else if (fields.length === 0) {\n    c.add(\"fields\", \"schema.fields must contain at least one field\");\n  } else {\n    const seenIds = new Set<string>();\n    fields.forEach((f, i) => validateField(f, `fields[${i}]`, seenIds, c));\n  }\n\n  const providers = input[\"providers\"];\n  if (providers !== undefined && !isRecord(providers)) {\n    c.add(\"providers\", \"schema.providers must be an object when present\");\n  }\n\n  const submit = input[\"submit\"];\n  if (submit !== undefined && !isRecord(submit)) {\n    c.add(\"submit\", \"schema.submit must be an object when present\");\n  }\n\n  if (c.issues.length > 0) {\n    return { ok: false, issues: c.issues };\n  }\n  return { ok: true, value: input as unknown as FormSchema };\n}\n\n/** Validate and throw a single aggregated error on failure. Convenience for trusted input. */\nexport function parseSchema(input: unknown): FormSchema {\n  const result = validateSchema(input);\n  if (!result.ok) {\n    const detail = result.issues.map((i) => `  - ${i.path}: ${i.message}`).join(\"\\n\");\n    throw new SchemaValidationError(`Invalid Formwright schema:\\n${detail}`, result.issues);\n  }\n  return result.value;\n}\n\nexport class SchemaValidationError extends Error {\n  readonly issues: readonly ValidationIssue[];\n  constructor(message: string, issues: readonly ValidationIssue[]) {\n    super(message);\n    this.name = \"SchemaValidationError\";\n    this.issues = issues;\n  }\n}\n\n/** Type guard form of {@link validateSchema}. */\nexport function isFormSchema(input: unknown): input is FormSchema {\n  return validateSchema(input).ok;\n}\n\n/** Convenience: list the field ids declared by a schema, in order. */\nexport function fieldIds(schema: FormSchema): string[] {\n  return schema.fields.map((f: FieldSchema) => f.id);\n}\n"]}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@formwright/schema",
+  "version": "0.1.0",
+  "description": "Schema types and runtime validator for Formwright.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aliarsalan177/formwright.git",
+    "directory": "packages/schema"
+  },
+  "homepage": "https://github.com/aliarsalan177/formwright#readme",
+  "bugs": "https://github.com/aliarsalan177/formwright/issues",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}