@formwright/schema 0.1.0 → 0.2.0

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.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" | "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;
@@ -110,6 +193,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 +226,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 +270,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" | "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;
@@ -110,6 +193,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 +226,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 +270,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/package.json

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