@clicktap/ui 1.0.3 → 1.1.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/index.json

@@ -7,7 +7,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",

package/package.json

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