release: WRNexusJS 0.8.0

.publish/validation/README.md

@@ -4,6 +4,31 @@
 
 Part of the **WrNexus** framework — an SSR-first, Bun-native full-stack web framework.
 
+## Boundary contracts
+
+Use `ContractRegistry` with `defineContract` or `defineEvent` to publish the
+same schema descriptors for APIs, actions, webhooks, realtime, queues, cron,
+pub/sub, plugins, configuration, and environment variables.
+
+```ts
+import { ContractRegistry, defineEvent, v } from "@wrnexus/validation";
+
+export const contracts = new ContractRegistry().register(
+  defineEvent({
+    name: "user.created",
+    version: 1,
+    consumers: ["notification-worker", "audit-service"],
+    payload: v.object({ userId: v.string().uuid(), createdAt: v.string().date() }),
+  }),
+);
+```
+
+Export the registry from `app/contracts.ts`, then accept a baseline with
+`wrnexus contracts snapshot`. CI can run `wrnexus contracts check`; removed
+contracts/fields, required-field additions, type changes, narrowed enums, and
+tighter validation fail with stable `WRN-CONTRACT-*` diagnostics and list known
+consumers. A generated `wrnexus.contracts.json` can be used instead of a module.
+
 ## Overview
 
 Define a schema once with the fluent `v` builder, then reuse it in three places: `.parse()` runs server-side and returns coerced values plus per-field errors; `.describe()` emits a plain-JSON `SchemaDescriptor` that the browser runtime interprets (no `eval`, no bundled validator); and helpers like `parseBody` and `parseEnv` wire schemas straight into API routes and startup config. The server rule logic (`applyRule`/`checkField`) and the client runtime (`VALIDATE_RUNTIME`) mirror each other exactly, so a form validates identically in both places. Schemas are conventionally kept in `app/schemas/`.
@@ -178,3 +203,55 @@ const head = `<script>${renderSchemasScript({ signup: signupSchema.describe() })
 - Refinements (`refine`) run only server-side and are never serialized — client and server agree on every other rule because both interpret the same `RuleDescriptor` list.
 - No runtime dependencies. Ships as TypeScript source (`src/index.ts`) executed directly by Bun.
 - Pairs with the WrNexus server (`@wrnexus/core`) for route handlers and the SSR layer that injects `renderSchemasScript` / `VALIDATE_RUNTIME`.
+
+## Helper and component kit
+
+The public helper API includes `parseOrThrow`, `ValidationError`, `validationResponse`, `firstValidationError`, `validationSummary`, and `schemaFieldNames`.
+
+Schema output is inferred automatically by `ObjectSchema`, `parseOrThrow`, `parseBody`, `parseEnv`, and `asyncSchema`. Use `InferSchema<typeof schema>` when a named output type is useful:
+
+```ts
+const accountSchema = v.object({
+  email: v.string().email(),
+  attempts: v.number().integer(),
+});
+
+type AccountInput = InferSchema<typeof accountSchema>;
+const account = parseOrThrow(accountSchema, input);
+// account.email: string
+// account.attempts: number
+```
+
+Enable `validationPlugin()` for:
+
+- `<ValidationSummary />`
+- `<FieldError />`
+
+The summary block composes `Alert` from `@wrnexus/ui`, while `FieldError` remains a lightweight accessible field-level primitive.
+Schemas can drive external contracts without maintaining a second definition:
+
+```ts
+import {
+  localizeDescriptor,
+  openApiRequestBody,
+  parseDescriptor,
+  toJsonSchema,
+} from "@wrnexus/validation";
+
+const jsonSchema = toJsonSchema(contactSchema, {
+  id: "urn:example:contact",
+  title: "Contact request",
+});
+const requestBody = openApiRequestBody(contactSchema);
+
+const mr = localizeDescriptor(contactSchema, (key, params) =>
+  translations.t(`validation.${key}`, params),
+);
+const result = parseDescriptor(mr, input);
+```
+
+JSON Schema output targets draft 2020-12, closes unknown object properties, and
+maps lengths/ranges/formats/enums/patterns/integer rules. OpenAPI request bodies
+reuse the same properties. Localized descriptors preserve explicit custom
+messages and fill default required, type-coercion, and rule messages; the same
+descriptor is consumable by server parsing and the eval-free browser runtime.