@clicktap/ui 0.40.8 → 0.40.10

package/docs/migrations/2026/06/2026-06-17-select-standardization.md

@@ -0,0 +1,286 @@
+# Select standardization — one `<Select searchable>`, `DropdownSelect` removed
+
+**Date:** 2026-06-17
+**Affects:** Any app consuming `@clicktap/ui`'s `Select` / `DropdownSelect` (Crispi, FFL, and any fork that renders pickers, sort controls, country/region selects, or configurable-product options).
+**Classification:** FEATURE + BREAKING
+**Breaking:** Yes — (1) `DropdownSelect` removed, (2) the bare `<Select>` is now a **button picker**, not a combobox, (3) `DropdownSelect`'s `classNames.trigger` is now `classNames.input`, (4) the root is `w-full` by default, (5) `<Option>` is react-stately's `Item` — keyed by `key` (no `id`) and **cannot be wrapped**.
+
+## Dependencies
+
+| Package | Minimum version |
+|---|---|
+| `@clicktap/ui` | The release bundling this commit. Confirm with `jq '.dependencies["@clicktap/ui"]' apps/frontend/package.json`. |
+
+(Actual version is set by semantic-release when `bugfixes` merges to `master`.)
+
+## Summary
+
+There used to be **two** components: `DropdownSelect` (a native-feel button picker) and `Select` (a react-aria `ComboBox` with a text input). They had different APIs, different `classNames` keys, and overlapping purposes.
+
+They're now **one** component — `<Select>` — with a `searchable` prop:
+
+- `searchable={false}` *(default)* — **button picker**: click to open, pick one. Right for short, fixed lists (sort order, "show per row"). Backed by a real hidden `<select>`, so it autofills.
+- `searchable` *(`true`)* — **combobox**: type to filter; the first match highlights, Tab/Enter commit it and Tab advances to the next field. Right for long lists (country, region). The dropdown is **portaled** so it works inside modals/drawers, and it ships with a hidden `<select>` mirror so password managers / browser autofill still work.
+- `searchable="auto"` — searchable once there are more than ~8 options.
+
+`<Option>` is react-stately's `Item` (`OptionProps<T> = ItemProps<T>`). **This is a breaking change if you previously passed `id` or wrapped `<Option>`** — see [Options: `id` → `key`, do not wrap](#options-id--key-do-not-wrap).
+
+## What changed
+
+| Area | Before | After |
+|---|---|---|
+| Exports | `DropdownSelect`, `DropdownSelectProps` + `Select` | `Select` only (`DropdownSelect` removed) |
+| Bare `<Select>` | Combobox (type-to-filter) | **Button picker** — add `searchable` to keep filtering |
+| `DropdownSelect` button class | `classNames.trigger` | `classNames.input` |
+| Root width | `DropdownSelect`: auto (`flex items-center`) | `w-full` (form-field default) — override for inline/`justify-end` rows |
+| **`<Option>`** | own element / accepted `id`, could be wrapped | **react-stately `Item`** — keyed by React `key` (no `id`); **cannot be wrapped** (it's a collection descriptor, not a rendered element). Style rows via `classNames.option`. |
+| `SelectSlots.listBoxComponent` | Custom listbox renderer | **No-op** — the dropdown is rendered internally now; remove it |
+| Option row theming | — | new `classNames.option` slot; focus/selected/disabled are `data-[focused]` / `data-[selected]` / `data-[disabled]` variants |
+| Option groups | — | new `<Section title="…">` to group options (accessible heading); `classNames.sectionHeading` slot |
+| Multi-select | — | `selectionMode="multiple"` → `selectedKeys: Key[]` + `onSelectionChange(keys: Key[])`. Searchable = combobox with chips; non-searchable = button with a summary. Single-select props/types unchanged. |
+| Selection types | `SelectProps` is one interface | `SelectProps` is a **discriminated union** on `selectionMode`. New `SelectBaseProps` export = everything except the selection contract — base single-select **wrappers** on it (`Omit` over the union collapses to common keys). |
+| New props | — | `searchable`, `selectTextOnFocus`, `autoFocusFirstOption`, `name` + `autoComplete` (autofill) |
+| Filtering | name only | match by name **or** option `textValue` aliases (codes) |
+
+Find affected usages:
+
+```bash
+grep -rn 'DropdownSelect\|classNames=' apps/frontend libs/ui \
+  | grep -E 'DropdownSelect|trigger:|listBoxComponent' | head -40
+# And every <Select> that relied on type-to-filter:
+grep -rn '<Select' apps/frontend | grep -v 'searchable' | head -40
+```
+
+## Migration Steps
+
+### 1. `DropdownSelect` → `<Select>` (default button mode)
+
+```tsx
+// Before
+import { DropdownSelect, Option } from '@clicktap/ui/components/Select';
+
+<DropdownSelect
+  selectedKey={key}
+  onSelectionChange={onChange}
+  classNames={{ trigger: 'text-xs w-44 h-8', value: 'text-xs', label: '...' }}
+>
+  <Option key="a">A</Option>
+</DropdownSelect>
+
+// After — same button look; `trigger` → `input`
+import { Select, Option } from '@clicktap/ui/components/Select';
+
+<Select
+  selectedKey={key}
+  onSelectionChange={onChange}
+  classNames={{ input: 'text-xs w-44 h-8', value: 'text-xs', label: '...' }}
+>
+  <Option key="a">A</Option>
+</Select>
+```
+
+### 2. Old `<Select>` that filtered → add `searchable`
+
+The bare `<Select>` no longer renders a text input. If you relied on type-to-filter, opt in:
+
+```tsx
+// Before — combobox behavior was implicit
+<Select selectedKey={key} onSelectionChange={onChange}>{options}</Select>
+
+// After — keep type-to-filter
+<Select searchable selectedKey={key} onSelectionChange={onChange}>{options}</Select>
+```
+
+For long lists where you're unsure, `searchable="auto"` turns it on past ~8 options.
+
+### 3. Fix inline / right-floated layout (the `w-full` root)
+
+`DropdownSelect`'s root was auto-width; the new `Select` root is `w-full` (correct for form fields, wrong for a toolbar row). In a `justify-end` / `flex items-center` row it now fills the width and sits left. `cn` is `twMerge`, so a `className` width override on the **root** wins:
+
+```tsx
+// Before (broke: fills the row, left-aligned)
+<div className="flex items-center justify-end">
+  <Select classNames={{ input: 'w-44' }} ... />
+</div>
+
+// After (floats right again)
+<div className="flex items-center justify-end">
+  <Select className="w-44" classNames={{ input: 'w-44' }} ... />
+</div>
+```
+
+> `classNames.input` sizes the button/input; **`className` sizes the root.** Constrain the root anywhere the Select isn't meant to be full-width.
+
+### 4. Options: `id` → `key`, do not wrap
+
+`<Option>` is now react-stately's `Item` (`OptionProps<T> = ItemProps<T>`). Two consequences:
+
+- **`id` is gone — options are keyed by the React `key`.** Every `<Option id={…}>` fails to typecheck.
+  ```tsx
+  // Before
+  <Option id={country.code}>{country.name}</Option>
+  // After
+  <Option key={country.code}>{country.name}</Option>
+  ```
+- **You cannot wrap `<Option>`.** `Item` is a *collection descriptor*, not a rendered element — the Select reads its props to build the list and renders the rows itself. A wrapper (`<MyOption>` → styled `<div>` → `<Item>`) breaks twice: the React `key` is swallowed by the wrapper (identity lost) and the wrapper's markup/`className` is never rendered. Use `<Option>` **directly** and style rows with `classNames.option` (next step).
+
+### 5. Theme the option rows (`classNames.option`)
+
+Option rows previously hard-coded a light palette with no override hook. There's now a `classNames.option` slot, and the focus/selected/disabled states are emitted as **`data-*` variants** so a non-light theme can retarget them:
+
+```tsx
+<Select
+  searchable
+  classNames={{
+    listContainer: 'bg-zinc-900 border-zinc-700',          // the dropdown surface
+    option: 'text-zinc-100 data-[focused]:bg-zinc-800 data-[disabled]:text-zinc-500',
+  }}
+>
+  {items.map((i) => <Option key={i.id}>{i.label}</Option>)}
+</Select>
+```
+
+`classNames.option` is merged last, so `twMerge` lets it win over the defaults (`text-slate-900`, `data-[focused]:bg-slate-100`, …). This replaces the old descendant-selector hack (`classNames.list: '[&_li]:…'`) and any per-option wrapper.
+
+### 6. Remove `slots.listBoxComponent`
+
+The dropdown list is rendered internally now; a custom `listBoxComponent` is ignored. Delete it (style via `classNames.listContainer` / `classNames.list` / `classNames.option` instead).
+
+### 7. (Optional) Enable autofill on a searchable select
+
+A searchable combobox has no native form control for its *selection*, so password managers / browser autofill can't fill it — **unless** you pass `name` (and ideally an `autoComplete` token). The Select then renders a hidden native `<select>` (for ≤300 options) that autofill targets; its change drives the selection.
+
+```tsx
+<Select
+  searchable
+  name="region"
+  autoComplete="address-level1"   // "country" for a country field, etc.
+  selectedKey={value ?? null}
+  onSelectionChange={onChange}
+>
+  {regions.map((r) => <Option key={r.code}>{r.name}</Option>)}
+</Select>
+```
+
+Autofill matches the **option text** (the state/country name), so render the name as the option's children.
+
+### 8. (Optional) Match by code/alias when typing
+
+By default filtering matches the option's `textValue` (its display name). To let users type a **code** ("tx", "us-tx") and still find the row, put the aliases in `textValue` — the field still displays the rendered children, not `textValue`:
+
+```tsx
+<Option key={code} textValue={`${name} ${shortCode} ${code}`}>
+  {name}
+</Option>
+```
+
+**Match ranking.** While filtering a flat searchable list, matches are reordered
+by relevance: an exact whitespace-token match (a code, e.g. `us`) first, then
+options whose name **starts with** the query, then mid-word substring hits. So
+typing `us` ranks *United States* (code `us`) above *Belarus* (substring), and
+typing `uni` ranks *United States* (prefix) above *Reunion* (mid-word). Ranking
+applies only when the Select owns filtering — it's skipped when you control
+`inputValue` (you own ordering), pass a render-fn `children`, or use `<Section>`
+groups (reordering would break grouping). See the `MatchRanking` story.
+
+### 9. (Optional) Group options with `<Section>`
+
+Wrap `<Option>`s in `<Section title="…">` for grouped lists (an accessible group
+heading per section). Works in both modes; in searchable mode the filter matches
+options within groups and drops empty ones, and Tab-complete commits the first
+matching **option** (section headers are skipped). Style headings via
+`classNames.sectionHeading`.
+
+```tsx
+import { Select, Option, Section } from '@clicktap/ui/components/Select';
+
+<Select searchable classNames={{ sectionHeading: 'text-zinc-400' }}>
+  <Section title="North America">
+    <Option key="us">United States</Option>
+    <Option key="ca">Canada</Option>
+  </Section>
+  <Section title="Europe">
+    <Option key="fr">France</Option>
+  </Section>
+</Select>
+```
+
+`<Section>` is react-stately's `Section` (a collection descriptor, like `<Option>`); it also accepts the dynamic `items` render form. `searchable="auto"` counts the options inside groups, not the groups.
+
+### 10. (Optional) Multi-select
+
+`selectionMode="multiple"` switches the selection contract to an array: pick
+several options, the menu stays open until you click away. The callback receives
+a `Key[]`. It works in **both** modes — searchable and not:
+
+```tsx
+const [keys, setKeys] = useState<Key[]>([]);
+
+// Searchable → combobox multi: type to filter, picks shown as removable chips.
+<Select searchable selectionMode="multiple" selectedKeys={keys} onSelectionChange={setKeys}>
+  {/* combines with <Section> groups too */}
+</Select>
+
+// Not searchable → button multi: a button whose summary lists the picks; the
+// open listbox toggles each option (stays open).
+<Select selectionMode="multiple" selectedKeys={keys} onSelectionChange={setKeys}>
+  {/* short fixed lists */}
+</Select>
+```
+
+`SelectProps` is a **discriminated union** on `selectionMode`, so single-select
+keeps its exact `selectedKey`/`onSelectionChange(Key | null)` types — no change to
+existing call sites.
+
+**Display & order conventions:**
+- *Combobox (chips)* — `classNames.tagGroup` / `tag` / `tagRemoveButton`; chips in
+  **selection order** (newest last, the usual token-input convention); full
+  keyboard a11y via react-aria-components `TagGroup` (arrow-nav, Backspace/Delete).
+- *Button (summary)* — comma-joined labels in **collection order** (stable, reads
+  like the list), styled via `classNames.value`.
+
+> **Wrappers:** if you build a single-select wrapper that does
+> `Omit<SelectProps, …>`, switch the base to the new **`SelectBaseProps`** export.
+> `Omit` over a union keeps only keys common to *all* members, which silently
+> drops the per-mode selection props. (This is why `AddressInput` was rebased.)
+>
+> _Caveats:_ button-mode multi has **no hidden native `<select>`** (so no
+> native-form submission / autofill — consume via `selectedKeys`), and selected
+> rows show via `data-[selected]` (no checkmark icon). A `tagOrder` toggle
+> (collection-order chips) is deferred until a use case needs it.
+
+### Verification
+
+```bash
+nx run frontend:typecheck   # no errors referencing DropdownSelect / trigger / listBoxComponent
+nx run ui:typecheck
+nx run ui:build-storybook
+```
+
+Visually confirm, per migrated select:
+- [ ] Button selects open/select/close; value shows.
+- [ ] Searchable selects: type to filter, Tab/Enter commit, Tab advances; clear + Tab clears.
+- [ ] Searchable inside a **modal/drawer**: Tab moves to the next field (dropdown is portaled out of the focus trap).
+- [ ] Toolbar/inline selects float/size correctly (root width set).
+- [ ] Autofill (if enabled): password manager fills the field; value sticks.
+- [ ] Themed rows (if you set `classNames.option`): text + focus/selected/disabled colors apply (see the `ThemedOptions` story).
+- [ ] Grouped options (if you use `<Section>`): headings render, filtering matches within groups, Tab commits the first matching option (see the `Grouped` story).
+- [ ] Multi-select (if you use `selectionMode="multiple"`): combobox shows chips (filter clears per pick, × removes); button shows a collection-order summary; menu stays open until click-away; callback gets `Key[]` (see `Multiple` / `GroupedMultiple` / `ButtonMultiple`).
+
+## Rollback
+
+Revert `@clicktap/ui` in the consuming app:
+
+```bash
+docker compose exec -u app node-app pnpm --filter <app> add '@clicktap/ui@<previous-minor>'
+```
+
+Safe — presentation-layer only, no persistent state.
+
+## References
+
+- Source: `libs/ui/src/components/Select/` (`Select.tsx` dispatches to `ButtonSelect.tsx` / `ComboBoxSelect.tsx`; shared parts in `parts.tsx`)
+- Types: `libs/ui/src/components/Select/Select.types.ts`
+- Stories: `libs/ui/src/components/Select/Select.stories.tsx` (`Picker`, `Searchable`, `SearchableAuto`, `AsyncDataSource`, `ServerSideSearch`, `ThemedOptions`, `Grouped`, `Multiple`, `GroupedMultiple`, `ButtonMultiple`)
+- In-repo consumer examples: `apps/frontend/components/AddressForm/AddressForm.tsx` (country/region, autofill, aliases), `apps/frontend/components/Collection/CollectionToolbar.tsx` (toolbar width), `apps/frontend/components/Product/components/ConfigurableOptions/ConfigurableOptions.tsx`
+- Related: [`Select` `onSelectionChange` widened to `Key | T`](../04/2026-04-17-select-address-input-onchange-key-or-item.md), [`Select` `popoverPortalContainer` restored](../02/2026-02-17-select-popover-portal-container-restored.md)

package/docs/migrations/2026/06/2026-06-18-select-hiddenselect-setvalue-crash.md

@@ -0,0 +1,75 @@
+# `Select` (searchable): fix "setValue is not a function" crash on browser autofill
+
+**Date:** 2026-06-18
+**Affects:** `@clicktap/ui` `Select` — the **searchable** (ComboBox) variant (`ComboBoxSelect`)
+**Classification:** BUGFIX
+**Breaking:** No
+
+## Why
+
+A **searchable** `<Select>` with a `name` (for autofill) crashed on **browser autofill** with:
+
+```
+TypeError: setValue is not a function
+  at @react-aria/select .../HiddenSelect.mjs  (its <select> onChange calls state.setValue)
+```
+
+`ComboBoxSelect` renders react-aria's `HiddenSelect` (a select-only helper) so password
+managers / browser autofill have a native control to fill, and passed it the **combobox** state:
+
+```ts
+<HiddenSelect state={state as unknown as SelectState<T>} … />
+```
+
+That cast is a lie at runtime: `HiddenSelect`'s `<select> onChange` calls `state.setValue`, which
+exists on **SelectState** (`useSelectState`, the non-searchable `ButtonSelect`) but **not** on
+**ComboBoxState** (`useComboBoxState`). So when autofill wrote into the hidden `<select>`, its change
+handler threw. Manual entry didn't trigger it; autofilling an address/country/region/profile form
+did. (`ButtonSelect` never crashed — it has a real `SelectState`.)
+
+This was **not** dep-fixable — it reproduced on the latest `@clicktap/ui` + `react-aria`.
+
+## The fix
+
+Wrap the combobox state in a `Proxy` that supplies `setValue` (mapped to `setSelectedKey`) while
+preserving the state's live getters (`selectedKey`, `collection`, …), and pass *that* to
+`HiddenSelect`:
+
+```ts
+const hiddenSelectState = useMemo(
+  () =>
+    new Proxy(state, {
+      get(target, prop) {
+        if (prop === 'setValue') {
+          return (key: Key | null) => target.setSelectedKey(key);
+        }
+        return Reflect.get(target, prop);
+      },
+    }) as unknown as SelectState<T>,
+  [state],
+);
+// …
+<HiddenSelect state={hiddenSelectState} … />
+```
+
+A `Proxy` (not a spread) is used so the combobox state's getters keep reflecting the current
+selection. The hidden native `<select>` mirror — and thus autofill support — is retained; only the
+crash is removed.
+
+## Consumer action
+
+If you applied an **interim workaround** while this was unfixed, you can remove it once on a build
+with this fix (the next `@clicktap/ui` release, **> 0.40.1**):
+
+- `searchable={false}` forced onto autofill-prone form selects (it routed to `ButtonSelect`/`SelectState` to dodge the crash, at the cost of type-to-filter) — restore `searchable`.
+- a `pnpm patch @clicktap/ui` carrying the `setValue → setSelectedKey` shim — drop the patch.
+
+No API change; searchable `Select`s with a `name` now survive autofill.
+
+## Notes
+
+- Dropping `name` does **not** avoid it — react-aria renders `HiddenSelect` regardless, so autofill
+  still reaches it.
+- A larger future option is to drop `HiddenSelect` for the combobox entirely and use react-aria's
+  combobox form-value path (a hidden text input). The Proxy shim is the contained fix and keeps the
+  existing `<select>`-based autofill behavior.

package/docs/migrations/2026/07/2026-07-31-ui-exports-bundler-resolution.md

@@ -0,0 +1,50 @@
+# `@clicktap/ui` resolves its deep subpaths under `moduleResolution: bundler` (CTAP-1060)
+
+**Date:** 2026-07-31
+**Package:** `@clicktap/ui`
+**Breaking:** No — additive to the `exports` map. Existing `moduleResolution: node` / `node10`
+consumers are unaffected (that resolver ignores `exports`); this only *adds* working resolution under
+`bundler` / `node16` / `nodenext`.
+**Classification:** BUGFIX (packaging) — unblocks `moduleResolution: bundler`, and with it TypeScript 7
+
+## What was wrong
+
+`@clicktap/ui`'s `exports` map pointed its wildcard subpaths at **extensionless** targets
+(`"./utils/*": "./utils/*"`). The legacy `moduleResolution: node` resolver ignores `exports` and
+probes files, and runtime bundlers append extensions, so this *appeared* to work — but
+`moduleResolution: bundler` / `node16` / `nodenext` **use `exports` strictly** and require an
+extensioned target. A deep import like `@clicktap/ui/utils/env` resolved to `./utils/env` (no such
+file) → **~928 `Cannot find module` errors** the moment a consumer switched to `bundler`. TypeScript 7
+removes `node10` outright (`TS5108`), forcing `bundler` / `node16` — so the old map made TS 7
+unreachable for every consumer.
+
+## What changed
+
+The `exports` targets are now extensioned + `types`-conditioned, with an **array fallback** so both
+flat files (`utils/cn.js`) and directory-index modules (`utils/variantOptions/index.js`) resolve:
+
+```jsonc
+"./utils/*": {
+  "types": ["./utils/*.d.ts", "./utils/*/index.d.ts"],
+  "import": ["./utils/*.js", "./utils/*/index.js"]
+}
+```
+
+The same shape applies to `./components/*` and `./hooks/*`; `./types/*` is **type-only** (the build
+emits only `.d.ts` for it).
+
+## What to do
+
+- **On `moduleResolution: node` today:** nothing — you are unaffected. Bump `@clicktap/ui` as usual.
+- **Switching to `moduleResolution: bundler` / `node16`:** bump `@clicktap/ui` to ≥ this release and the
+  deep `@clicktap/ui/utils/*`, `/components/*`, `/hooks/*` imports resolve (types included). This was the
+  prerequisite that previously produced the wall of `Cannot find module` errors.
+- **TypeScript 7:** this removes the `@clicktap/ui` blocker. Note TS 7 has a *separate*, non-clicktap
+  blocker — **nx 20.0.3 cannot build a project graph with TS 7 installed** (`Cannot read properties of
+  undefined (reading 'readFile')`) — so TS 7 also needs an nx major.
+
+## Verified
+
+Resolution was tested against the built package in both modes: under `bundler` all deep subpaths (flat
+file, directory-index, and nested file) resolve **with types**; under `node` (node10) resolution is
+unchanged (no regression).

package/docs/migrations/2026/08/2026-08-02-nextui-to-heroui.md

@@ -0,0 +1,65 @@
+# NextUI → HeroUI for `Accordion`, `Badge`, `Pagination`, `Tooltip`
+
+**Date:** 2026-08-02
+**Affects:** `@clicktap/ui` peer dependencies — `Accordion`, `Badge`, `Pagination`, `Tooltip`
+**Classification:** DEPENDENCY
+**Breaking:** Yes (peer dependencies change; requires Tailwind 4 — see below)
+
+## Dependencies
+
+- **Requires Tailwind 4** (`@heroui/theme >= 2.4.24` peers `tailwindcss >= 4.0.0`). Do the
+  [Tailwind 3 → 4 upgrade](../../../../../apps/frontend/docs/migrations/2026/07/2026-07-31-tailwind-3-to-4.md)
+  first (or together with this).
+
+## Summary
+
+`@clicktap/ui`'s `Accordion`, `Badge`, `Pagination` and `Tooltip` now build on the **`@heroui/*`**
+packages instead of the **deprecated** `@nextui-org/*` ones. npm reports each `@nextui-org/*` as
+deprecated (`Please use @heroui/<name> instead`), and NextUI no longer receives fixes — they land only
+in the HeroUI line. Consumers were inheriting four un-actionable `Deprecated` warnings through
+`@clicktap/ui`; this removes them.
+
+The component **APIs are unchanged** — HeroUI is a straight rename-fork of NextUI. No source changes are
+needed at your call sites; this is a dependency swap.
+
+## What changed in `@clicktap/ui`
+
+| Before (peer) | After (peer) |
+|---|---|
+| `@nextui-org/accordion` | `@heroui/accordion` |
+| `@nextui-org/badge` | `@heroui/badge` |
+| `@nextui-org/pagination` | `@heroui/pagination` |
+| `@nextui-org/tooltip` | `@heroui/tooltip` |
+| *(implicit / unpinned)* | `@heroui/theme` `>= 2.4.24` (declared) |
+| *(implicit / unpinned)* | `@heroui/system` `>= 2.4.18` (declared) |
+
+`@heroui/theme` / `@heroui/system` are now declared explicitly so their versions are aligned and
+satisfiable (previously the theme/system peers came in transitively and could resolve to versions the
+components rejected — e.g. `@heroui/theme@>=2.4.24` unmet with `2.4.6` installed).
+
+## ⚠️ Tailwind 4 is required
+
+`@heroui/theme >= 2.4.24` peers **`tailwindcss >= 4.0.0`**. The HeroUI theme line has moved to Tailwind
+4, so the components' **styles** will not compile correctly under Tailwind 3. If you are still on
+Tailwind 3, complete the Tailwind 3 → 4 upgrade first; the two migrations belong together. (This is why
+`@clicktap/ui`'s own reference frontend, still on Tailwind 3, adopts this alongside its Tailwind 4 move.)
+The type/build surface is fine on either — the coupling is purely the generated CSS.
+
+## Migration steps (consumer)
+
+1. **Bump `@clicktap/ui`** to the release that ships this migration.
+2. **Replace the peer packages** in your `package.json` — remove the four `@nextui-org/*` above, add the
+   four `@heroui/*` plus `@heroui/theme` (`>= 2.4.24`) and `@heroui/system` (`>= 2.4.18`). If you wrap
+   these components, update any direct `@nextui-org/{accordion,badge,pagination,tooltip}` imports in your
+   own code to `@heroui/*` (identical API).
+3. **Be on Tailwind 4** (see the dependency note). Point your HeroUI Tailwind plugin at `@heroui/theme`
+   instead of `@nextui-org/theme` if you configure it directly.
+4. Reinstall and verify: no `Deprecated` warnings for these four, and no `unmet peer @heroui/theme|system`
+   warnings.
+
+## Not included
+
+- `@nextui-org/avatar` and the `@nextui-org/theme` Tailwind plugin still exist in the clicktap **reference
+  frontend** (not in `@clicktap/ui`); migrating those is separate and pairs with the Tailwind 4 work.
+- This is unrelated to the CTAP-1072 SSR-500 (that was the `tailwindcss/plugin.js` async external, not
+  these packages).

package/docs/migrations/README.md

@@ -0,0 +1,31 @@
+# UI Library Migration Guides
+
+Migration guides for the `@clicktap/ui` library. Each doc covers a specific change with before/after examples and checklists.
+
+For migrations affecting the frontend app, see [frontend migrations](../../../../apps/frontend/docs/migrations/README.md).
+
+## Index
+
+| Date | Migration | Breaking | Dependencies |
+|------|-----------|----------|--------------|
+| 2026-01-14 | [External link detection + `LinkProvider`](./2026/01/2026-01-14-external-link-detection.md) | No | *None* |
+| 2026-01-14 | [`useRoute` hook + `RouteProvider`](./2026/01/2026-01-14-use-route-hook.md) | No | *None* |
+| 2026-01-15 | [`Input` `disableSkeleton` prop](./2026/01/2026-01-15-input-disable-skeleton.md) | No | *None* |
+| 2026-02-16 | [Environment utilities — `@clicktap/ui/utils/env`](./2026/02/2026-02-16-env-utils-from-clicktap-ui.md) | No | *None* |
+| 2026-02-17 | [`Select` `popoverPortalContainer` restored](./2026/02/2026-02-17-select-popover-portal-container-restored.md) | No | *None* |
+| 2026-03-24 | [Image: dimmed, hidden, and onReady Props](./2026/03/2026-03-24-image-dimmed-hidden-onready.md) ↔ | No | *None* |
+| 2026-03-24 | [ModalOverlay: fix dismiss on backdrop click](./2026/03/2026-03-24-modal-overlay-backdrop-dismiss.md) | No | *None* |
+| 2026-04-17 | [`Select`/`AddressInput` `onChange` widened to `Key \| T`](./2026/04/2026-04-17-select-address-input-onchange-key-or-item.md) | Yes | *None* |
+| 2026-04-24 | [`PLACEHOLDER_IMAGE` Export from `@clicktap/ui/utils/placeholder`](./2026/04/2026-04-24-image-placeholder-frontend-fallback.md) ↔ | No | *None* |
+| 2026-04-30 | [Top-Down PDP Option Dependency — `@clicktap/ui/utils/variantOptions`](./2026/04/2026-04-30-top-down-pdp-option-dependency.md) ↔ | No | *None* |
+| 2026-04-30 | [PDP Option Selection — Conservative Prune Helper (`pruneInvalidSelections`)](./2026/04/2026-04-30-prune-invalid-pdp-selections.md) ↔ | No | Top-Down PDP Option Dependency |
+| 2026-05-01 | [`buildPdpUrl` Utility — `@clicktap/ui/utils/buildPdpUrl`](./2026/05/2026-05-01-build-pdp-url-util.md) | No | *None* |
+| 2026-05-03 | [Auth-aware GraphQL client — `@clicktap/ui/utils/createAuthAwareGraphqlClient`](./2026/05/2026-05-03-auth-aware-graphql-client.md) | No | *None* |
+| 2026-05-20 | [framer-motion 11.x idioms — opacity-only for modals, primitives elsewhere, matched keyframe shapes](./2026/05/2026-05-20-framer-motion-11-idioms.md) ↔ | Yes (custom `animationVariants` only) | *None* |
+| 2026-05-21 | [`ButtonLoadingContent` helper — right-side spinner for all submit buttons](./2026/05/2026-05-21-button-loading-content.md) ↔ | No | *None* |
+| 2026-05-21 | [`PasswordCheck` `requirements` variant hides until the visitor types](./2026/05/2026-05-21-password-check-hide-on-empty.md) | No | *None* |
+| 2026-05-29 | [`PasswordCheck` — the `requirements` variant (adoption guide for forks)](./2026/05/2026-05-29-password-check-requirements-variant.md) | No | PasswordCheck hide-on-empty |
+| 2026-06-17 | [Select standardization — one `<Select searchable>`, `DropdownSelect` removed](./2026/06/2026-06-17-select-standardization.md) ↔ | Yes | *None* |
+| 2026-06-18 | [Select (searchable): fix "setValue is not a function" crash on browser autofill](./2026/06/2026-06-18-select-hiddenselect-setvalue-crash.md) | No | Select standardization |
+
+↔ = cross-app migration (has counterpart in frontend app)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clicktap/ui",
-  "version": "0.40.8",
+  "version": "0.40.10",
   "private": false,
   "author": "Clicktap",
   "description": "A library of React UI components and low-level hooks.",
@@ -76,10 +76,12 @@
   },
   "peerDependencies": {
     "@floating-ui/react": "^0.27.0",
-    "@nextui-org/accordion": "^2.2.0",
-    "@nextui-org/badge": "^2.2.0",
-    "@nextui-org/pagination": "^2.2.0",
-    "@nextui-org/tooltip": "^2.2.0",
+    "@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/tooltip": "^2.2.0",
     "@types/react": "^18.0.0",
     "framer-motion": "^11.18.0",
     "react": "^18.0.0",