@clicktap/ui 1.1.1 → 2.0.3

package/utils/zod/configureZodErrorMap.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The shape of a zod 4 issue, to the extent this helper reads one.
+ *
+ * Declared structurally rather than imported from `zod` on purpose — see {@link configureZodErrorMap}.
+ */
+export interface ZodIssueLike {
+    /** The value that failed. `undefined` means the key was never supplied. */
+    readonly input?: unknown;
+    readonly code?: string;
+    /** What was measured: `'string'`, `'number'`, `'array'`, … */
+    readonly origin?: string;
+    readonly minimum?: unknown;
+    readonly maximum?: unknown;
+}
+/**
+ * The one method this needs from the zod namespace.
+ *
+ * Structural, so any zod 4.x satisfies it and nothing here depends on a particular copy.
+ */
+export interface ZodNamespaceLike {
+    config(config: {
+        customError: (issue: ZodIssueLike) => string | undefined;
+    }): unknown;
+}
+/**
+ * Messages for the constraint checks whose zod 4 defaults leak internals.
+ *
+ * Each is a function of the bound so a consumer can localise or reword without reimplementing the
+ * branching. A per-check message (`.min(8, '…')`) or a schema-level one always wins over these —
+ * that is the whole contract of the error map below.
+ */
+export interface ZodConstraintMessages {
+    stringTooSmall: (minimum: number) => string;
+    stringTooBig: (maximum: number) => string;
+    numberTooSmall: (minimum: number) => string;
+    numberTooBig: (maximum: number) => string;
+    arrayTooSmall: (minimum: number) => string;
+    arrayTooBig: (maximum: number) => string;
+}
+export interface ConfigureZodErrorMapOptions {
+    /**
+     * Shown when the value is absent entirely. This is the one that matters most — see below.
+     *
+     * @default 'This field is required.'
+     */
+    required?: string;
+    /**
+     * Readable copy for the common constraint checks. Pass `false` to rewrite only the
+     * missing-value case and leave every other default alone.
+     *
+     * @default true
+     */
+    constraints?: boolean | Partial<ZodConstraintMessages>;
+}
+/**
+ * Install a global zod 4 error map that produces human-readable validation messages.
+ *
+ * ```ts
+ * import { z } from 'zod';
+ * import { configureZodErrorMap } from '@clicktap/ui/utils/zod';
+ *
+ * configureZodErrorMap(z);
+ * ```
+ *
+ * ## Why every app needs this
+ *
+ * zod 4 dropped zod 3's readable defaults. Verified against zod 4.4.3:
+ *
+ * ```
+ * undefined against z.string()  ->  "Invalid input: expected string, received undefined"
+ * z.string().min(8)             ->  "Too small: expected string to have >=8 characters"
+ * ```
+ *
+ * Both are developer output. Neither should reach a visitor.
+ *
+ * **The first cannot be fixed with per-field messages, which is the part that catches people out.**
+ * react-hook-form leaves an untouched field as `undefined` (inputs render `value ?? ''`), so
+ * `.min(1, '…')` and `.nonempty({ message })` only ever see an empty string — their message never
+ * applies to the missing case. Submitting an untouched form is the common path, so nearly every
+ * field in every app is exposed. It has to be fixed globally, which is what this does.
+ *
+ * ## Why you pass `z` in
+ *
+ * So this package does not depend on zod. A version is not the issue — two *copies* are: the map
+ * has to land on the zod instance your schemas were built with, and an app on zod 3 must be able to
+ * install `@clicktap/ui` without a stray zod 4 appearing in its type graph. (It does appear, and it
+ * breaks `zodResolver`, which is how this API was arrived at.) Passing the namespace makes the
+ * instance explicit and costs a consumer one argument.
+ *
+ * ## Precedence
+ *
+ * The map returns `undefined` for anything it does not handle, and zod then falls back to the
+ * message attached at the schema. So per-check messages keep winning:
+ *
+ * ```ts
+ * z.string().min(8, 'Pick a longer password.')   // -> 'Pick a longer password.'
+ * z.string().min(8)                              // -> 'Must be at least 8 characters.'
+ * ```
+ *
+ * ## Where to call it
+ *
+ * Once per module registry. In a Next.js app that is **two** places, because server and browser
+ * bundles are separate registries and a module evaluated in one is not evaluated in the other:
+ *
+ * ```ts
+ * // app/layout.tsx    — SSR and server actions
+ * // app/providers.tsx — 'use client', the browser
+ * configureZodErrorMap(z);
+ * ```
+ *
+ * It is a plain idempotent function rather than a side-effecting import on purpose: calling it
+ * twice is harmless, and an explicit call is not something a bundler can tree-shake away.
+ */
+export declare function configureZodErrorMap(z: ZodNamespaceLike, options?: ConfigureZodErrorMapOptions): void;
+export default configureZodErrorMap;

package/utils/zod/configureZodErrorMap.js

@@ -0,0 +1 @@
+const a={stringTooSmall:r=>r===1?"This field is required.":`Must be at least ${r} characters.`,stringTooBig:r=>`Must be ${r} character${r===1?"":"s"} or fewer.`,numberTooSmall:r=>`Must be ${r} or more.`,numberTooBig:r=>`Must be ${r} or less.`,arrayTooSmall:r=>r===1?"Select at least one option.":`Select at least ${r} options.`,arrayTooBig:r=>`Select no more than ${r} option${r===1?"":"s"}.`};function m(r,n={}){const e=n.required??"This field is required.",i=n.constraints!==!1,t={...a,...typeof n.constraints=="object"?n.constraints:{}};r.config({customError:o=>{if(o.input===void 0)return e;if(i){if(o.code==="too_small"&&typeof o.minimum=="number"){if(o.origin==="string")return t.stringTooSmall(o.minimum);if(o.origin==="number")return t.numberTooSmall(o.minimum);if(o.origin==="array")return t.arrayTooSmall(o.minimum)}if(o.code==="too_big"&&typeof o.maximum=="number"){if(o.origin==="string")return t.stringTooBig(o.maximum);if(o.origin==="number")return t.numberTooBig(o.maximum);if(o.origin==="array")return t.arrayTooBig(o.maximum)}}}})}export{m as configureZodErrorMap,m as default};

package/utils/zod/index.d.ts

@@ -0,0 +1 @@
+export { configureZodErrorMap, type ConfigureZodErrorMapOptions, type ZodConstraintMessages, type ZodIssueLike, type ZodNamespaceLike, } from './configureZodErrorMap';

package/utils/zod/index.js

@@ -0,0 +1 @@
+import{configureZodErrorMap as e}from"./configureZodErrorMap.js";export{e as configureZodErrorMap};

package/utils/zod.d.ts

@@ -0,0 +1 @@
+export * from './zod/index';

package/utils/zod.js

@@ -0,0 +1 @@
+export * from './zod/index.js';