docs: add dynamic error message and combined refinement examples for refine()

[IdanGonen]

Fixes #5998

Add more examples of custom error messages with .refine() to the API docs:

• Dynamic error messages: shows how to pass a function to the error option, giving access to iss.input to build messages based on the failing value - Combined .refine() + .superRefine(): a practical password schema example demonstrating when to use each — .refine() for simple single-message checks,
  .superRefine() when multiple issues or full control over issue codes/paths is needed
• Best practices guidance: prose note clarifying the decision boundary between the two methods, with a cross-link to the .superRefine() section

[pullfrog]

TL;DR — Adds a dynamic-error-message example and a combined .refine() + .superRefine() example to the .refine() section of api.mdx, fixing #5998. The dynamic-message snippet is a clean, useful addition; the combined-refinement block largely retreads ground already covered later in the same section.

Key changes

• Dynamic error function example — Adds a Zod / Zod Mini tab pair showing error: (iss) => …${iss.input}… immediately after the existing static-string error: example.
• Combined .refine() + .superRefine() password example — Adds a second tab pair chaining both refinement APIs on a { password, confirm } object, with prose framing the decision between them.

_{Summary ｜ 1 file ｜ 1 commit ｜ base: main ← fix/refine-error-examples-5998}

Dynamic error message

Before: .refine() docs only showed error: "static string".
After: A second example shows error: (iss) => … with iss.input interpolated.

This part lands well. The iss.input claim is accurate (same shape used throughout error-customization.mdx) and the example is minimal.

api.mdx

Combined .refine() + .superRefine() section

Before: .refine() section ended at the static error: example; cross-field password === confirm first appeared ~120 lines later under path.
After: A combined password example with .refine() + .superRefine() is inserted directly under the error: examples.

Two things worth reconsidering here:

The cross-field password === confirm refinement with path: ["confirm"] already exists at L2281 (in the path subsection) and again as confirmPassword at L2381 (under when). Multi-issue .superRefine() is already demonstrated at L2485 (UniqueStringArray). The new block is the third copy of essentially the same password/confirm example inside the .refine() section, which makes the page longer without adding a pattern readers can't already get from existing examples.

The prose at L2155 also reads "use .superRefine() instead", but the example then uses both APIs chained on the same schema. Either the framing should be "you can combine them" (matching the example), or the example should drop .refine() and demonstrate pure .superRefine() (matching "instead"). Right now the prose and the code are pointing in different directions.

api.mdx

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

Note

Prior feedback addressed by dropping the combined .refine() + .superRefine() block. Only the dynamic-error-message example remains, which the prior review already endorsed as a clean addition.

Reviewed the following changes:

• Removed the combined .refine() + .superRefine() password example and its "use .superRefine() instead" prose intro, resolving both the duplication with L2281 / L2381 / L2477 and the prose/example mismatch from the prior review.
• Kept the dynamic-error-message tab pair (Zod + Zod Mini) showing error: (iss) => …${iss.input}…, inserted directly after the static-string error: example.

  ^{｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}