@clicktap/ui 0.43.6 → 1.0.0

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

@@ -0,0 +1,61 @@
+# `next` and `@heroui/*` peer ranges are capped; `react-stately` pinned
+
+**Date:** 2026-08-11
+**Package:** `@clicktap/ui`
+**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.
+**Ticket:** CTAP-1241
+
+## Summary
+
+Three peer ranges were open-ended and are now bounded:
+
+| Peer | Before | After |
+|---|---|---|
+| `next` | `>=14` | `^14.0.0` |
+| `@heroui/system` | `>=2.4.18` | `^2.4.18` |
+| `@heroui/theme` | `>=2.4.24` | `^2.4.24` |
+
+A caret already carries its ceiling — `^14.0.0` *is* `>=14.0.0 <15.0.0` — so the ranges are written that
+way rather than as explicit bounds. For a `0.x` dependency the equivalent is a tilde (`~0.8.0` is
+`>=0.8.0 <0.9.0`), because a `0.x` minor bump is a breaking change.
+
+An open-ended peer with `auto-install-peers=true` means **"newest major, forever"** — a standing licence
+for the next `pnpm update` to move you onto a major this package has never been built against, silently.
+The ceilings are the highest major this repo builds and tests against, not the next major above the
+floor.
+
+## Also: `react-stately` is pinned to the version the app owns
+
+`react-stately` was a `devDependency` at `^3.46.0` while `apps/frontend` pins `3.44.0`, so the family
+split across workspace members — the lib resolved 3.46.0, the app 3.44.0. `react`, `react-aria` and
+`react-aria-components` were all clean singletons at the same time, which is what makes this shape easy
+to miss: a `grep` for duplicate `react@` in the lockfile finds nothing, and only the resolved symlinks
+show the split one family member over.
+
+It is now pinned to `3.44.0`. **Not breaking** — `react-stately` remains a peer at `^3.36.0`, and the
+build already externalizes `react-stately` and `@react-stately/*`, so nothing about what you install
+changes. The pin only stops the lib's own dev tree from resolving a different copy than the app's.
+
+## Action required (consumer)
+
+**On Next 14 and HeroUI 2.x:** nothing.
+
+**Past a ceiling** (Next 15/16, HeroUI 3): your install now reports an unmet peer, and fails under
+`strict-peer-dependencies`. That is the intended signal — it means you are on a major nobody has
+verified this package against. Either move back onto a supported major, or ask for the ceiling to be
+raised deliberately once the package has been built and tested there. Raising it is a one-line change;
+what is missing is the verification, not the willingness.
+
+**Worth checking while you are here:** if you have a `react-stately` (or any `@react-*`) version pinned
+in your own app, confirm it matches what `@clicktap/ui` resolves. The split above existed for a while
+without symptoms, and duplicate react-aria/stately instances surface as subtle focus and overlay bugs
+rather than as an error.
+
+## Verify
+
+```bash
+pnpm install               # no unmet-peer warning for next or @heroui/*
+pnpm why react-stately     # one version across every member
+```

package/docs/migrations/README.md

@@ -31,5 +31,6 @@ For migrations affecting the frontend app, see [frontend migrations](../../../..
 | 2026-08-04 | [Password reveal is press-and-hold, not a toggle](./2026/08/ui-2026-08-04-password-reveal-press-and-hold.md) ⚠️ superseded | Behavioural | *None* (CTAP-1128) |
 | 2026-08-06 | [`Image` is framework-free; Next's optimizer moves to `@clicktap/ui/next`](./2026/08/ui-2026-08-06-clicktap-ui-image-next-subpath.md) ↔ | Yes (Next consumers) | *None* |
 | 2026-08-11 | [Password reveal is a toggle again, not press-and-hold](./2026/08/ui-2026-08-11-password-reveal-toggle.md) | Behavioural | Supersedes CTAP-1128 |
+| 2026-08-11 | [`next` / `@heroui/*` peers capped; `react-stately` pinned](./2026/08/ui-2026-08-11-peer-ranges-capped.md) | Yes (consumers past a ceiling) | *None* |
 
 ↔ = cross-app migration (has counterpart in frontend app)

package/docs/migrations/index.json

@@ -1,4 +1,14 @@
 [
+  {
+    "path": "2026/08/ui-2026-08-11-peer-ranges-capped.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-11",
+    "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."
+  },
   {
     "path": "2026/08/ui-2026-08-11-password-reveal-toggle.md",
     "module": "libs/frontend-modules/ui",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clicktap/ui",
-  "version": "0.43.6",
+  "version": "1.0.0",
   "private": false,
   "author": "Clicktap",
   "description": "A library of React UI components and low-level hooks.",
@@ -124,7 +124,7 @@
     "react-aria-components": "^1.15.0",
     "react-hook-form": "^7.71.1",
     "react-international-phone": "^4.7.0",
-    "react-stately": "^3.46.0",
+    "react-stately": "3.44.0",
     "rollup-preserve-directives": "^1.1.3",
     "tailwindcss": "^4.3.3",
     "vite": "^7.3.1",
@@ -138,13 +138,13 @@
     "@heroui/accordion": "^2.2.0",
     "@heroui/badge": "^2.2.0",
     "@heroui/pagination": "^2.2.0",
-    "@heroui/system": ">=2.4.18",
-    "@heroui/theme": ">=2.4.24",
+    "@heroui/system": "^2.4.18",
+    "@heroui/theme": "^2.4.24",
     "@heroui/tooltip": "^2.2.0",
     "@types/react": "^18.0.0",
     "framer-motion": "^11.18.0",
     "graphql-request": "^6.1.0",
-    "next": ">=14",
+    "next": "^14.0.0",
     "react": "^18.0.0",
     "react-aria": "^3.46.0",
     "react-aria-components": "^1.15.0",