@formwright/schema 0.1.0 → 0.2.2

package/README.md

@@ -1,20 +1,53 @@
 # @formwright/schema
 
-Schema types and a dependency-free runtime validator for [Formwright](../../README.md).
+> Schema types and a dependency-free runtime validator for [Formwright](https://github.com/aliarsalan177/formwright).
 
-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.
+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.
+
+```bash
+npm i @formwright/schema
+```
 
 ```ts
 import { validateSchema, parseSchema } from "@formwright/schema";
 
+// Non-throwing: inspect issues
 const result = validateSchema(unknownInput);
 if (!result.ok) {
   for (const issue of result.issues) console.warn(issue.path, issue.message);
 }
 
-// or throw on failure:
+// Or throw a single aggregated error on failure:
 const schema = parseSchema(unknownInput);
 ```
+
+## Types
+
+`FormSchema`, `FieldSchema`, `FieldType`, `FieldOption`, `ValidationSchema`, `Condition`,
+`SubmitSchema`, and more — the full, serializable shape of a form, including nested `group`
+and `collection` fields and the JSONLogic-style `Condition` algebra.
+
+```ts
+import type { FormSchema } from "@formwright/schema";
+
+const schema: FormSchema = {
+  id: "signup",
+  version: "1.0",
+  fields: [
+    { id: "email", type: "email", validation: { kind: "string", format: "email", required: true } },
+  ],
+};
+```
+
+## Why a runtime validator
+
+LLM-emitted schemas can be malformed. `validateSchema` checks the structure (ids present and
+unique, container fields declared, etc.) and returns issues addressed by path
+(`fields[2].type`), so you can repair or reject input before constructing a `Form`.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -11,9 +11,16 @@ var BUILTIN_TYPES = /* @__PURE__ */ new Set([
   "checkbox",
   "radio",
   "group",
-  "collection"
+  "collection",
+  "steps",
+  "step"
+]);
+var CONTAINER_TYPES = /* @__PURE__ */ new Set([
+  "group",
+  "collection",
+  "steps",
+  "step"
 ]);
-var CONTAINER_TYPES = /* @__PURE__ */ new Set(["group", "collection"]);
 function isRecord(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
@@ -49,7 +56,18 @@ function validateField(field, path, seenIds, c) {
       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));
+      nested.forEach((f, i) => {
+        if (type === "steps") {
+          const childType = isRecord(f) ? f["type"] : void 0;
+          if (childType !== "step") {
+            c.add(
+              `${path}.fields[${i}].type`,
+              `field of type "steps" must contain "step" children (got "${String(childType)}")`
+            );
+          }
+        }
+        validateField(f, `${path}.fields[${i}]`, childIds, c);
+      });
     }
   }
 }

package/dist/index.cjs.map

@@ -1 +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"]}
+{"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  \"steps\",\n  \"step\",\n]);\n\nconst CONTAINER_TYPES: ReadonlySet<string> = new Set<FieldType>([\n  \"group\",\n  \"collection\",\n  \"steps\",\n  \"step\",\n]);\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 must declare nested fields; recurse so nested problems surface with a\n  // 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      const childIds = new Set<string>();\n      nested.forEach((f, i) => {\n        if (type === \"steps\") {\n          const childType = isRecord(f) ? f[\"type\"] : undefined;\n          if (childType !== \"step\") {\n            c.add(\n              `${path}.fields[${i}].type`,\n              `field of type \"steps\" must contain \"step\" children (got \"${String(childType)}\")`,\n            );\n          }\n        }\n        validateField(f, `${path}.fields[${i}]`, childIds, c);\n      });\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

@@ -48,7 +48,25 @@ type Condition = boolean | {
     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 & {});
+type FieldType = "text" | "number" | "email" | "password" | "textarea" | "select" | "checkbox" | "radio" | "date" | "time" | "datetime" | "daterange" | "color" | "range" | "file" | "group" | "collection" | "steps" | "step" | "heading" | "separator" | "paragraph" | (string & {});
+/**
+ * Map a field to your own UI — a custom element, native tag, or a widget you
+ * registered by name. The serializable bits (tag/component/valueProp/event/attrs)
+ * live here; code-level transforms and framework `mount` functions are attached
+ * via `registerWidget` in the renderer.
+ */
+type WidgetRef = string | {
+    /** A registered widget name (takes precedence over `tag`). */
+    readonly component?: string;
+    /** A custom element / native tag to render, e.g. "s-select". */
+    readonly tag?: string;
+    /** Property the value is written to / read from (default "value"). */
+    readonly valueProp?: string;
+    /** DOM event that signals a change, e.g. "value-change" (default "input"). */
+    readonly event?: string;
+    /** Static attributes to set on the element. */
+    readonly attrs?: Record<string, string>;
+};
 /** Validation descriptor — declarative, mapped to a Standard Schema validator at runtime. */
 interface ValidationSchema {
     readonly kind: "string" | "number" | "boolean" | "array";
@@ -59,20 +77,85 @@ interface ValidationSchema {
     readonly maxLength?: number;
     readonly pattern?: string;
     readonly format?: "email" | "url" | "uuid";
+    /** Catch-all override for every rule's message. */
     readonly message?: Resolvable<string>;
+    /** Per-rule message overrides (take precedence over `message` and the defaults). */
+    readonly messages?: {
+        readonly required?: string;
+        readonly min?: string;
+        readonly max?: string;
+        readonly minLength?: string;
+        readonly maxLength?: string;
+        readonly pattern?: string;
+        readonly format?: string;
+        readonly type?: string;
+    };
 }
 /** A selectable option for `select` / `radio` fields. */
 interface FieldOption {
     readonly label: Resolvable<string>;
     readonly value: FieldValue;
 }
+/**
+ * Per-part class overrides — drop in your own CSS classes or Tailwind utilities
+ * to restyle any part of a field without touching the renderer.
+ */
+interface FieldClasses {
+    readonly field?: string;
+    readonly label?: string;
+    readonly control?: string;
+    readonly help?: string;
+    readonly description?: string;
+    readonly error?: string;
+}
+/**
+ * A slot rendered at the start/end of an input — either decorative text/icon
+ * (a string like "$" or "🔍") or a nested field (e.g. a currency `select`) whose
+ * value is added to the payload as a sibling key.
+ */
+type FieldSlot = string | FieldSchema;
 /** 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>;
+    /** Native `autocomplete` token for the input (e.g. "email", "name", "off"). */
+    readonly autocomplete?: string;
     readonly help?: Resolvable<string>;
+    /** Static body text — for `paragraph`/`heading` presentational fields. */
+    readonly content?: Resolvable<string>;
+    /** An info tooltip shown next to the field's label. */
+    readonly tooltip?: Resolvable<string>;
+    /**
+     * Capture a value per locale → payload `{ en: "...", ar: "..." }`. Requires
+     * the form's `locales`. Renders as one input with a language switcher; reshape to
+     * `translations: { en: {...} }` in submit if needed.
+     */
+    readonly localized?: boolean;
+    /** The locale shown first for a `localized` field (default: the form's first locale). */
+    readonly defaultLocale?: string;
+    /** Longer descriptive text, positioned by {@link descriptionPosition}. */
+    readonly description?: Resolvable<string>;
+    /** Where to render `description` (default `"below-label"`). */
+    readonly descriptionPosition?: "below-label" | "below-field";
+    /** For check-like fields (checkbox/toggle): label `"start"` (with control at the end) or `"end"` (default). */
+    readonly labelPosition?: "start" | "end";
+    /** Render content (icon/text or a value-bearing field) before/after the input. */
+    readonly slots?: {
+        readonly start?: FieldSlot;
+        readonly end?: FieldSlot;
+    };
+    /** Exclude this field's value from the submitted payload (UI-only control). */
+    readonly omit?: boolean;
+    /** Render this field with your own component/element instead of the built-in for `type`. */
+    readonly widget?: WidgetRef;
+    /** Columns the field spans in the form's 12-column grid (e.g. 6 = half width, two side by side). */
+    readonly colSpan?: number;
+    /** Extra class(es) on the field wrapper (e.g. Tailwind utilities). */
+    readonly class?: string;
+    /** Per-part class overrides (wrapper, label, control, help, description, error). */
+    readonly classes?: FieldClasses;
     readonly defaultValue?: FieldValue;
     readonly options?: Resolvable<readonly FieldOption[]>;
     readonly validation?: ValidationSchema;
@@ -93,8 +176,19 @@ interface FieldSchema {
      * Container layout:
      *  - `group`: `"fieldset"` (default) or `"accordion"` (collapsible section).
      *  - `collection`: `"list"` (default), `"cards"`, or `"accordion"` (each row collapsible).
+     *  - `steps`: `"bar"` (default), `"tabs"`, or `"numbers"` progress indicator.
      */
-    readonly layout?: "fieldset" | "accordion" | "list" | "cards";
+    readonly layout?: "fieldset" | "accordion" | "list" | "cards" | "bar" | "tabs" | "numbers";
+    /** `steps` only: show a progress indicator (default `true`). */
+    readonly showProgress?: boolean;
+    /** `steps` only: validate the current step before advancing (default `true`). */
+    readonly validateOnNext?: boolean;
+    /** `steps` only: label for the Next button (default `"Next"`). */
+    readonly nextLabel?: Resolvable<string>;
+    /** `steps` only: label for the Back button (default `"Back"`). */
+    readonly prevLabel?: Resolvable<string>;
+    /** `steps` only: label for Submit on the last step (default `"Submit"`). */
+    readonly submitLabel?: Resolvable<string>;
     /** `collection` only: label for each row, e.g. "Contact". */
     readonly itemLabel?: Resolvable<string>;
     /** `collection` only: text for the add-row button (default: "Add"). */
@@ -110,6 +204,18 @@ interface ProviderDecl {
     readonly type: "i18n" | "tanstack-query" | "theme" | (string & {});
     readonly [key: string]: unknown;
 }
+/** A form-level action button (submit, reset, or a named custom action like "delete"). */
+interface FormAction {
+    readonly name: string;
+    readonly label?: Resolvable<string>;
+    /** `"submit"` triggers submission, `"reset"` resets, `"button"` (default) emits an action event. */
+    readonly role?: "submit" | "reset" | "button";
+    readonly variant?: "primary" | "secondary" | "danger";
+    /** Render this button full-width (stretches to fill the action bar). */
+    readonly fullWidth?: boolean;
+    /** Name of a handler in `options.handlers`, called with the form on click. */
+    readonly handler?: string;
+}
 /** How the form submits: transform the payload, send it, handle success/error. */
 interface SubmitSchema {
     /** Name of a registered transform applied to values before sending. */
@@ -131,6 +237,14 @@ interface FormSchema {
     readonly providers?: Record<string, ProviderDecl>;
     readonly fields: readonly FieldSchema[];
     readonly submit?: SubmitSchema;
+    /** Locales for `localized` fields — each captures a value per locale. */
+    readonly locales?: readonly string[];
+    /** Locales rendered right-to-left (defaults to the common RTL set: ar, he, fa, ur, …). */
+    readonly rtlLocales?: readonly string[];
+    /** Action buttons rendered at the bottom of the form (defaults to a single Submit). */
+    readonly actions?: readonly FormAction[];
+    /** How action buttons are aligned: `"start"` (default), `"end"`, or `"between"`. */
+    readonly actionsAlign?: "start" | "end" | "between";
 }
 
 /**
@@ -167,4 +281,4 @@ 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 };
+export { type Condition, type FieldClasses, type FieldOption, type FieldSchema, type FieldSlot, type FieldType, type FieldValue, type FormAction, type FormSchema, type ProviderDecl, type ProviderRef, type Resolvable, SchemaValidationError, type SubmitSchema, type ValidationIssue, type ValidationResult, type ValidationSchema, type WidgetRef, fieldIds, isFormSchema, parseSchema, validateSchema };

package/dist/index.d.ts

@@ -48,7 +48,25 @@ type Condition = boolean | {
     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 & {});
+type FieldType = "text" | "number" | "email" | "password" | "textarea" | "select" | "checkbox" | "radio" | "date" | "time" | "datetime" | "daterange" | "color" | "range" | "file" | "group" | "collection" | "steps" | "step" | "heading" | "separator" | "paragraph" | (string & {});
+/**
+ * Map a field to your own UI — a custom element, native tag, or a widget you
+ * registered by name. The serializable bits (tag/component/valueProp/event/attrs)
+ * live here; code-level transforms and framework `mount` functions are attached
+ * via `registerWidget` in the renderer.
+ */
+type WidgetRef = string | {
+    /** A registered widget name (takes precedence over `tag`). */
+    readonly component?: string;
+    /** A custom element / native tag to render, e.g. "s-select". */
+    readonly tag?: string;
+    /** Property the value is written to / read from (default "value"). */
+    readonly valueProp?: string;
+    /** DOM event that signals a change, e.g. "value-change" (default "input"). */
+    readonly event?: string;
+    /** Static attributes to set on the element. */
+    readonly attrs?: Record<string, string>;
+};
 /** Validation descriptor — declarative, mapped to a Standard Schema validator at runtime. */
 interface ValidationSchema {
     readonly kind: "string" | "number" | "boolean" | "array";
@@ -59,20 +77,85 @@ interface ValidationSchema {
     readonly maxLength?: number;
     readonly pattern?: string;
     readonly format?: "email" | "url" | "uuid";
+    /** Catch-all override for every rule's message. */
     readonly message?: Resolvable<string>;
+    /** Per-rule message overrides (take precedence over `message` and the defaults). */
+    readonly messages?: {
+        readonly required?: string;
+        readonly min?: string;
+        readonly max?: string;
+        readonly minLength?: string;
+        readonly maxLength?: string;
+        readonly pattern?: string;
+        readonly format?: string;
+        readonly type?: string;
+    };
 }
 /** A selectable option for `select` / `radio` fields. */
 interface FieldOption {
     readonly label: Resolvable<string>;
     readonly value: FieldValue;
 }
+/**
+ * Per-part class overrides — drop in your own CSS classes or Tailwind utilities
+ * to restyle any part of a field without touching the renderer.
+ */
+interface FieldClasses {
+    readonly field?: string;
+    readonly label?: string;
+    readonly control?: string;
+    readonly help?: string;
+    readonly description?: string;
+    readonly error?: string;
+}
+/**
+ * A slot rendered at the start/end of an input — either decorative text/icon
+ * (a string like "$" or "🔍") or a nested field (e.g. a currency `select`) whose
+ * value is added to the payload as a sibling key.
+ */
+type FieldSlot = string | FieldSchema;
 /** 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>;
+    /** Native `autocomplete` token for the input (e.g. "email", "name", "off"). */
+    readonly autocomplete?: string;
     readonly help?: Resolvable<string>;
+    /** Static body text — for `paragraph`/`heading` presentational fields. */
+    readonly content?: Resolvable<string>;
+    /** An info tooltip shown next to the field's label. */
+    readonly tooltip?: Resolvable<string>;
+    /**
+     * Capture a value per locale → payload `{ en: "...", ar: "..." }`. Requires
+     * the form's `locales`. Renders as one input with a language switcher; reshape to
+     * `translations: { en: {...} }` in submit if needed.
+     */
+    readonly localized?: boolean;
+    /** The locale shown first for a `localized` field (default: the form's first locale). */
+    readonly defaultLocale?: string;
+    /** Longer descriptive text, positioned by {@link descriptionPosition}. */
+    readonly description?: Resolvable<string>;
+    /** Where to render `description` (default `"below-label"`). */
+    readonly descriptionPosition?: "below-label" | "below-field";
+    /** For check-like fields (checkbox/toggle): label `"start"` (with control at the end) or `"end"` (default). */
+    readonly labelPosition?: "start" | "end";
+    /** Render content (icon/text or a value-bearing field) before/after the input. */
+    readonly slots?: {
+        readonly start?: FieldSlot;
+        readonly end?: FieldSlot;
+    };
+    /** Exclude this field's value from the submitted payload (UI-only control). */
+    readonly omit?: boolean;
+    /** Render this field with your own component/element instead of the built-in for `type`. */
+    readonly widget?: WidgetRef;
+    /** Columns the field spans in the form's 12-column grid (e.g. 6 = half width, two side by side). */
+    readonly colSpan?: number;
+    /** Extra class(es) on the field wrapper (e.g. Tailwind utilities). */
+    readonly class?: string;
+    /** Per-part class overrides (wrapper, label, control, help, description, error). */
+    readonly classes?: FieldClasses;
     readonly defaultValue?: FieldValue;
     readonly options?: Resolvable<readonly FieldOption[]>;
     readonly validation?: ValidationSchema;
@@ -93,8 +176,19 @@ interface FieldSchema {
      * Container layout:
      *  - `group`: `"fieldset"` (default) or `"accordion"` (collapsible section).
      *  - `collection`: `"list"` (default), `"cards"`, or `"accordion"` (each row collapsible).
+     *  - `steps`: `"bar"` (default), `"tabs"`, or `"numbers"` progress indicator.
      */
-    readonly layout?: "fieldset" | "accordion" | "list" | "cards";
+    readonly layout?: "fieldset" | "accordion" | "list" | "cards" | "bar" | "tabs" | "numbers";
+    /** `steps` only: show a progress indicator (default `true`). */
+    readonly showProgress?: boolean;
+    /** `steps` only: validate the current step before advancing (default `true`). */
+    readonly validateOnNext?: boolean;
+    /** `steps` only: label for the Next button (default `"Next"`). */
+    readonly nextLabel?: Resolvable<string>;
+    /** `steps` only: label for the Back button (default `"Back"`). */
+    readonly prevLabel?: Resolvable<string>;
+    /** `steps` only: label for Submit on the last step (default `"Submit"`). */
+    readonly submitLabel?: Resolvable<string>;
     /** `collection` only: label for each row, e.g. "Contact". */
     readonly itemLabel?: Resolvable<string>;
     /** `collection` only: text for the add-row button (default: "Add"). */
@@ -110,6 +204,18 @@ interface ProviderDecl {
     readonly type: "i18n" | "tanstack-query" | "theme" | (string & {});
     readonly [key: string]: unknown;
 }
+/** A form-level action button (submit, reset, or a named custom action like "delete"). */
+interface FormAction {
+    readonly name: string;
+    readonly label?: Resolvable<string>;
+    /** `"submit"` triggers submission, `"reset"` resets, `"button"` (default) emits an action event. */
+    readonly role?: "submit" | "reset" | "button";
+    readonly variant?: "primary" | "secondary" | "danger";
+    /** Render this button full-width (stretches to fill the action bar). */
+    readonly fullWidth?: boolean;
+    /** Name of a handler in `options.handlers`, called with the form on click. */
+    readonly handler?: string;
+}
 /** How the form submits: transform the payload, send it, handle success/error. */
 interface SubmitSchema {
     /** Name of a registered transform applied to values before sending. */
@@ -131,6 +237,14 @@ interface FormSchema {
     readonly providers?: Record<string, ProviderDecl>;
     readonly fields: readonly FieldSchema[];
     readonly submit?: SubmitSchema;
+    /** Locales for `localized` fields — each captures a value per locale. */
+    readonly locales?: readonly string[];
+    /** Locales rendered right-to-left (defaults to the common RTL set: ar, he, fa, ur, …). */
+    readonly rtlLocales?: readonly string[];
+    /** Action buttons rendered at the bottom of the form (defaults to a single Submit). */
+    readonly actions?: readonly FormAction[];
+    /** How action buttons are aligned: `"start"` (default), `"end"`, or `"between"`. */
+    readonly actionsAlign?: "start" | "end" | "between";
 }
 
 /**
@@ -167,4 +281,4 @@ 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 };
+export { type Condition, type FieldClasses, type FieldOption, type FieldSchema, type FieldSlot, type FieldType, type FieldValue, type FormAction, type FormSchema, type ProviderDecl, type ProviderRef, type Resolvable, SchemaValidationError, type SubmitSchema, type ValidationIssue, type ValidationResult, type ValidationSchema, type WidgetRef, fieldIds, isFormSchema, parseSchema, validateSchema };

package/dist/index.js

@@ -9,9 +9,16 @@ var BUILTIN_TYPES = /* @__PURE__ */ new Set([
   "checkbox",
   "radio",
   "group",
-  "collection"
+  "collection",
+  "steps",
+  "step"
+]);
+var CONTAINER_TYPES = /* @__PURE__ */ new Set([
+  "group",
+  "collection",
+  "steps",
+  "step"
 ]);
-var CONTAINER_TYPES = /* @__PURE__ */ new Set(["group", "collection"]);
 function isRecord(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
@@ -47,7 +54,18 @@ function validateField(field, path, seenIds, c) {
       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));
+      nested.forEach((f, i) => {
+        if (type === "steps") {
+          const childType = isRecord(f) ? f["type"] : void 0;
+          if (childType !== "step") {
+            c.add(
+              `${path}.fields[${i}].type`,
+              `field of type "steps" must contain "step" children (got "${String(childType)}")`
+            );
+          }
+        }
+        validateField(f, `${path}.fields[${i}]`, childIds, c);
+      });
     }
   }
 }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/validate.ts"],"names":[],"mappings":"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","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"]}
+{"version":3,"sources":["../src/validate.ts"],"names":[],"mappings":"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","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  \"steps\",\n  \"step\",\n]);\n\nconst CONTAINER_TYPES: ReadonlySet<string> = new Set<FieldType>([\n  \"group\",\n  \"collection\",\n  \"steps\",\n  \"step\",\n]);\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 must declare nested fields; recurse so nested problems surface with a\n  // 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      const childIds = new Set<string>();\n      nested.forEach((f, i) => {\n        if (type === \"steps\") {\n          const childType = isRecord(f) ? f[\"type\"] : undefined;\n          if (childType !== \"step\") {\n            c.add(\n              `${path}.fields[${i}].type`,\n              `field of type \"steps\" must contain \"step\" children (got \"${String(childType)}\")`,\n            );\n          }\n        }\n        validateField(f, `${path}.fields[${i}]`, childIds, c);\n      });\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

@@ -1,6 +1,6 @@
 {
   "name": "@formwright/schema",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "description": "Schema types and runtime validator for Formwright.",
   "license": "MIT",
   "repository": {