@clicktap/ui 1.0.3 → 1.2.1

package/components/Breadcrumbs/BreadcrumbLink.js

@@ -1 +1 @@
-"use client";import{jsx as o}from"react/jsx-runtime";import{Link as u}from"react-aria-components";import{cn as i}from"../../utils/cn.js";function c({children:e,className:r,...t}){return o(u,{className:i("text-slate-600 no-underline cursor-pointer","focus-visible:outline-2 focus-visible:outline focus-visible:outline-border-subtle","hover:text-fg hover:underline","current:cursor-default current:text-fg current:font-semibold","disabled:cursor-default disabled:text-fg-subtle disabled:current:text-fg",r),...t,children:e})}export{c as BreadcrumbLink,c as default};
+"use client";import{jsx as u}from"react/jsx-runtime";import{Link as o}from"react-aria-components";import{cn as i}from"../../utils/cn.js";function f({children:e,className:r,...t}){return u(o,{className:i("text-fg-muted no-underline cursor-pointer","focus-visible:outline-2 focus-visible:outline focus-visible:outline-border-subtle","hover:text-fg hover:underline","current:cursor-default current:text-fg current:font-semibold","disabled:cursor-default disabled:text-fg-subtle disabled:current:text-fg",r),...t,children:e})}export{f as BreadcrumbLink,f as default};

package/components/Breadcrumbs/BreadcrumbSeparator.js

@@ -1 +1 @@
-"use client";import{jsx as e}from"react/jsx-runtime";import{Breadcrumb as i}from"react-aria-components";import{cn as n}from"../../utils/cn.js";function c({children:r,className:t,...o}){return e(i,{className:n("flex items-center text-slate-600","my-0 mx-2",t),...o,children:r??e("svg",{"aria-hidden":"true",xmlns:"http://www.w3.org/2000/svg",width:"16",height:"16",viewBox:"0 0 16 16",fill:"none",className:"w-4 h-4",children:e("path",{d:"M6 12L10 8L6 4",stroke:"currentColor",strokeWidth:"1.5",strokeLinecap:"round",strokeLinejoin:"round"})})})}export{c as BreadcrumbSeparator,c as default};
+"use client";import{jsx as e}from"react/jsx-runtime";import{Breadcrumb as i}from"react-aria-components";import{cn as n}from"../../utils/cn.js";function d({children:r,className:t,...o}){return e(i,{className:n("flex items-center text-fg-muted","my-0 mx-2",t),...o,children:r??e("svg",{"aria-hidden":"true",xmlns:"http://www.w3.org/2000/svg",width:"16",height:"16",viewBox:"0 0 16 16",fill:"none",className:"w-4 h-4",children:e("path",{d:"M6 12L10 8L6 4",stroke:"currentColor",strokeWidth:"1.5",strokeLinecap:"round",strokeLinejoin:"round"})})})}export{d as BreadcrumbSeparator,d as default};

package/docs/migrations/2026/08/ui-2026-08-11-peer-ranges-capped.md

@@ -5,6 +5,7 @@
 **Affects:** every consumer — the peer ranges are the declaration your package manager installs against.
 **Classification:** COMPATIBILITY
 **Breaking:** Yes for a consumer already past a ceiling. No code change; the contract narrowed.
+**Read before updating:** the capped ranges are the contract your install resolves against — decide before taking `@clicktap/ui` 1.x, not after
 **Ticket:** CTAP-1241
 
 ## Summary
@@ -53,6 +54,35 @@ in your own app, confirm it matches what `@clicktap/ui` resolves. The split abov
 without symptoms, and duplicate react-aria/stately instances surface as subtle focus and overlay bugs
 rather than as an error.
 
+### When the duplicate is transitive — nothing of yours to pin
+
+The paragraph above assumes the second copy comes from a declaration you own. Often it does not:
+crispi resolves `react-stately` 3.49.0 cleanly across every workspace member and still carries a
+second copy at 3.46.0, arriving via `@adobe/react-spectrum` → `react-aria-components`. No manifest of
+theirs names it, so there is no pin to correct.
+
+Decide it in this order:
+
+1. **Ask whether the two copies ever share a context.** The hazard is not two versions existing; it
+   is two versions of the same *provider* — `@react-aria/overlays`' focus scope and dismiss stack,
+   most of all — being live in one tree at once. Two design systems that each portal their own
+   overlays, never nesting one inside the other, can hold separate copies indefinitely. Two copies
+   reached through the same `OverlayProvider` cannot.
+2. **If they do share one, force a single resolution with `pnpm.overrides`:**
+   ```json
+   { "pnpm": { "overrides": { "react-stately": "3.49.0" } } }
+   ```
+   A bare-name override collapses every copy in the tree whatever any package declares. Verify with
+   `pnpm why react-stately` and then exercise the *other* library's overlays — you have moved it onto
+   a version it did not choose, which is the cost of this lever.
+3. **If they do not, record the decision and move on.** `@clicktap/ui` externalizes `react-stately`
+   and `@react-stately/*`, so the copy under a foreign design system is never the copy this package
+   imports.
+
+What you should not do is leave the check unresolved either way. A duplicate you have decided is
+harmless is a different state from one you have not looked at, and only the first survives the next
+person reading `pnpm why`.
+
 ## Verify
 
 ```bash

package/docs/migrations/2026/08/ui-2026-08-14-breadcrumb-trail-fully-tokenised.md

@@ -0,0 +1,80 @@
+# The breadcrumb trail is fully tokenised, so a dark-ground app can re-theme it
+
+**Date:** 2026-08-14
+**Package:** `@clicktap/ui`
+**Affects:** any consumer rendering `Breadcrumbs` — and, for the diagnosis below, any consumer on a
+dark ground.
+**Classification:** BUGFIX
+**Breaking:** No. One small visual change in light mode: the ancestor crumbs and the chevron move
+from `slate-600` to the `fg-muted` token (`slate-500`), one step lighter. The current crumb is
+unchanged.
+
+## What was wrong
+
+`BreadcrumbLink` and `BreadcrumbSeparator` still carried a literal `text-slate-600` — residue from
+the CTAP-1123 token sweep. A literal palette class cannot be re-themed at all: a consumer overriding
+`--color-fg-muted` for a dark ground got no effect on the trail, because nothing in it read that
+token.
+
+Both now use `text-fg-muted`, so the whole trail re-themes with the rest of the library.
+
+## The reported symptom, and what actually causes it
+
+The report (CTAP-1304) was that the **current** crumb is illegible on a dark ground — roughly
+1.2:1 against a black body. That crumb is styled `current:text-fg`, which is already a token, so
+this fix does not change it. The cause is one level up:
+
+> `@clicktap/ui` ships **light** token defaults and deliberately does not assume a ground. Re-theming
+> is a runtime override of the tokens — see the top of `theme.css`.
+
+An app that paints `body { background-color: #000 }` without overriding `--color-fg` gets
+`slate-900` text on black. That is not specific to breadcrumbs: **`text-fg` appears 132 times across
+39 components**, so the same app has the same problem everywhere. Breadcrumbs is simply where QA
+noticed, because the current crumb is the item you most expect to stand out.
+
+The fix on the consumer side is two lines, and it repairs all 39 components at once:
+
+```css
+:root[data-theme='dark'] {
+  --color-fg: oklch(98% 0 0);
+  --color-fg-muted: oklch(70.4% 0.04 256.788);
+}
+```
+
+The new `DarkGround` story shows exactly this. Delete the two custom properties from it and it
+reproduces the reported bug.
+
+## Overriding just the current crumb
+
+If you are not re-theming globally and want to repaint one crumb, there is a sharp edge worth
+knowing — it is why an override can look like it does nothing:
+
+> tailwind-merge only drops a conflicting class when the **variant strings match**. `current:text-fg`
+> (ours) and `data-[current]:text-white` (the natural guess) are different variants, so both survive
+> the merge and stylesheet order decides the winner.
+
+Claim the same variant and it resolves deterministically:
+
+```tsx
+<BreadcrumbLink className="current:text-white">Product</BreadcrumbLink>
+```
+
+The `OverridingTheCurrentCrumb` story demonstrates it. This is also why a consumer override written
+against `data-[disabled]` never affected the current crumb — `disabled` and `current` are different
+states, so it was never going to match.
+
+## Migration checklist
+
+- [ ] Nothing required. The trail keeps working as-is.
+- [ ] If you are on a dark ground, override `--color-fg` and `--color-fg-muted` rather than
+  restyling components — and check the rest of your app, since the same tokens drive 39 components.
+- [ ] If you carry a local patch repainting breadcrumb colours, it can go; if you keep one, make
+  sure it claims the `current:` variant.
+
+## Known residue
+
+Twenty-six literal `text-slate-*` occurrences remain elsewhere in the library (CTAP-1123 residue,
+across `FeatureGate`, `Collection`, `Pagination`, `EmptyResults` and others). They have the same
+un-themeable problem as the two fixed here, but mapping them onto the token ladder is a visual
+judgement per site rather than a mechanical swap — `slate-700` and `slate-800` have no exact token —
+so they are deliberately not swept here. Tracked separately.

package/docs/migrations/2026/08/ui-2026-08-14-zod-error-map.md

@@ -0,0 +1,104 @@
+# A shared zod 4 error map, so every app stops hand-rolling `config/zod.ts`
+
+**Date:** 2026-08-14
+**Package:** `@clicktap/ui`
+**Affects:** any consumer on **zod 4**. Nothing changes for a zod 3 app, or for one not using zod
+at all.
+**Classification:** IMPROVEMENT
+**Breaking:** No. Purely additive — one new subpath. `@clicktap/ui` gains **no** dependency on zod,
+so nothing about your install changes.
+
+## Why this exists
+
+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, and that 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.
+
+## Usage
+
+```ts
+import { z } from 'zod';
+import { configureZodErrorMap } from '@clicktap/ui/utils/zod';
+
+configureZodErrorMap(z);
+```
+
+**You pass `z` in, and that is deliberate.** This package does not depend on zod — not on a version
+and not on a copy. 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.
+That last one is not hypothetical: adding zod 4 to this library, even only as a dev dependency,
+made `@hookform/resolvers`' `zodResolver` resolve zod 4's types against the reference app's zod 3
+schemas and produced 29 typecheck errors across it. Passing the namespace makes the instance
+explicit and costs one argument.
+
+Call it **once per module registry**. In a Next.js app that is two places, because the 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. That also answers
+the "structure it so there is only one import point" question — there is no structure that can
+collapse two module registries into one, so the API is at least honest about needing both calls.
+
+### Customising
+
+```ts
+configureZodErrorMap(z, {
+  required: 'Required.',
+  constraints: { stringTooSmall: (min) => `At least ${min}, please.` },
+});
+
+configureZodErrorMap(z, { constraints: false }); // only rewrite the missing-value case
+```
+
+## Precedence — per-check messages still win
+
+The map returns `undefined` for anything it does not handle, so zod falls back to whatever message
+is attached at the schema. Covered by tests:
+
+| schema | input | message |
+| --- | --- | --- |
+| `z.string().min(8, 'Pick a longer password.')` | `'abc'` | `Pick a longer password.` |
+| `z.string().min(8)` | `'abc'` | `Must be at least 8 characters.` |
+| `z.string().min(1, 'Enter your name.')` | `''` | `Enter your name.` |
+| `z.string().min(1, 'Enter your name.')` | `undefined` | `This field is required.` |
+| `z.email()` | `'nope'` | `Invalid email address` (zod's own, already readable) |
+
+The fourth row is the one worth staring at: the field's own message loses to the global map,
+because the field was never filled in and its `.min(1)` check never ran.
+
+## Migration checklist
+
+- [ ] **Delete your hand-rolled `config/zod.ts`** and call `configureZodErrorMap(z)` from the same
+  two places the side-effect import was made.
+- [ ] Nothing to install — you supply your own `z`.
+- [ ] If you are on zod 3, ignore this entirely.
+
+## Note for maintainers
+
+The behaviour above was verified against a real zod 4.4.3 before the API was settled; the unit tests
+then drive the map with issue fixtures captured from that run, since the package carries no zod to
+test against.
+
+An earlier attempt imported zod directly and declared it an optional peer. Two things killed it, in
+order of discovery: the library build **inlined zod's own global-config implementation**
+(`globalThis.__zod_globalConfig` and the assignment around it) rather than importing it — visible
+only by reading `dist/`, because the in-repo import resolves through the tsconfig path alias and
+looks identical either way — and installing zod 4 here to test against broke the zod-3 reference
+app's typecheck. Taking the namespace as an argument removes both problems at once.

package/docs/migrations/index.json

@@ -1,4 +1,24 @@
 [
+  {
+    "path": "2026/08/ui-2026-08-14-zod-error-map.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-14",
+    "title": "A shared zod 4 error map, so every app stops hand-rolling `config/zod.ts`",
+    "classification": "IMPROVEMENT",
+    "breaking": "No. Purely additive — one new subpath. `@clicktap/ui` gains **no** dependency on zod,",
+    "affects": "any consumer on **zod 4**. Nothing changes for a zod 3 app, or for one not using zod"
+  },
+  {
+    "path": "2026/08/ui-2026-08-14-breadcrumb-trail-fully-tokenised.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-14",
+    "title": "The breadcrumb trail is fully tokenised, so a dark-ground app can re-theme it",
+    "classification": "BUGFIX",
+    "breaking": "No. One small visual change in light mode: the ancestor crumbs and the chevron move",
+    "affects": "any consumer rendering `Breadcrumbs` — and, for the diagnosis below, any consumer on a"
+  },
   {
     "path": "2026/08/ui-2026-08-11-peer-ranges-capped.md",
     "module": "libs/frontend-modules/ui",
@@ -7,7 +27,8 @@
     "title": "`next` and `@heroui/*` peer ranges are capped; `react-stately` pinned",
     "classification": "COMPATIBILITY",
     "breaking": "Yes for a consumer already past a ceiling. No code change; the contract narrowed.",
-    "affects": "every consumer — the peer ranges are the declaration your package manager installs against."
+    "affects": "every consumer — the peer ranges are the declaration your package manager installs against.",
+    "read_before_updating": "the capped ranges are the contract your install resolves against — decide before taking `@clicktap/ui` 1.x, not after"
   },
   {
     "path": "2026/08/ui-2026-08-11-password-reveal-toggle.md",
@@ -17,7 +38,9 @@
     "title": "Password reveal is a toggle again, not press-and-hold",
     "classification": "IMPROVEMENT (UX / accessibility)",
     "breaking": "Behavioural only — the reveal changed from press-and-hold back to a click toggle, and the",
-    "affects": "`@clicktap/ui` — `Input` with `type=\"password\"`."
+    "affects": "`@clicktap/ui` — `Input` with `type=\"password\"`.",
+    "revised": "2026-08-11",
+    "revised_note": "2026-08-11 — consumer action now says to rename a component named for the press-and-hold"
   },
   {
     "path": "2026/08/ui-2026-08-07-ui-peer-contract-form-graphql-optional-peers.md",
@@ -97,7 +120,9 @@
     "title": "`@clicktap/ui` resolves its deep subpaths under `moduleResolution: bundler` (CTAP-1060)",
     "classification": "BUGFIX (packaging) — unblocks `moduleResolution: bundler`, and with it TypeScript 7",
     "breaking": "No — additive to the `exports` map. Existing `moduleResolution: node` / `node10`",
-    "affects": ""
+    "affects": "",
+    "revised": "2026-08-08",
+    "revised_note": "2026-08-08 — the test-runner half (CTAP-1195): every runtime subpath entry gains a `default` condition, so CJS resolvers (Jest) stop falling through to the `.d.ts`. See \"Test runners (Jest)\" below; reported by noco."
   },
   {
     "path": "2026/06/ui-2026-06-18-select-hiddenselect-setvalue-crash.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clicktap/ui",
-  "version": "1.0.3",
+  "version": "1.2.1",
   "private": false,
   "author": "Clicktap",
   "description": "A library of React UI components and low-level hooks.",

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';