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.

.publish/validation/package.json

@@ -1,9 +1,25 @@
 {
   "name": "@wrnexus/validation",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
-  "description": "@wrnexus/validation — part of the WrNexus framework.",
+  "description": "Shared server/browser schemas, validation helpers, form runtime, and reusable error components.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://git.workroot.in/WorkRoot/WRNexusJS.git",
+    "directory": "packages/validation"
+  },
+  "homepage": "https://wrnexusjs.dev/packages/validation",
+  "bugs": {
+    "url": "https://git.workroot.in/WorkRoot/WRNexusJS/issues"
+  },
+  "keywords": [
+    "wrnexus",
+    "bun",
+    "typescript",
+    "validation"
+  ],
+  "sideEffects": false,
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -18,9 +34,28 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js"
+    },
+    "./components/*": "./components/*"
+  },
+  "dependencies": {
+    "@wrnexus/core": "^0.8.0",
+    "@wrnexus/plugin": "^0.8.0",
+    "@wrnexus/ui": "^0.8.0"
+  },
+  "wrnexus": {
+    "plugin": {
+      "plugin": "./dist/plugin.js",
+      "export": "default",
+      "factory": true
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "components"
   ]
 }