@clicktap/ui 0.40.8 → 0.40.10

package/docs/migrations/2026/01/2026-01-15-input-disable-skeleton.md

@@ -0,0 +1,82 @@
+# Input disableSkeleton Prop
+
+**Date:** 2026-01-15
+**Affects:** `@clicktap/ui`, `apps/frontend`
+**Breaking:** No
+**Classification:** IMPROVEMENT
+
+
+## Dependencies
+
+*None*
+
+## Summary
+
+Added a `disableSkeleton` prop to the Input component that allows consumers to skip the skeleton loading state during hydration. This is useful when you need immediate interactivity (e.g., auto-focus) on page load.
+
+## Background
+
+The Input component uses `useIsClient()` to show a skeleton placeholder during server-side rendering and hydration. This prevents hydration mismatches but causes a brief "flash" where the input appears disabled/skeleton before becoming interactive.
+
+For forms where immediate user interaction is expected (like login/authentication pages), this delay can feel sluggish.
+
+## Changes
+
+### New Prop
+
+```typescript
+interface InputProps extends TextFieldProps {
+  // ... existing props
+
+  /**
+   * When true, renders the input immediately without showing a skeleton during hydration.
+   * Use this when the input doesn't need hydration protection (e.g., simple text inputs
+   * that don't have complex state or need immediate interactivity).
+   */
+  disableSkeleton?: boolean;
+}
+```
+
+## Usage
+
+### Before
+
+```tsx
+<Input
+  name="email"
+  type="email"
+  label="Email"
+  autoFocus  // Won't work - skeleton renders first
+/>
+```
+
+### After
+
+```tsx
+<Input
+  name="email"
+  type="email"
+  label="Email"
+  disableSkeleton  // Renders immediately
+  autoFocus        // Now works as expected
+/>
+```
+
+## When to Use
+
+**Use `disableSkeleton` when:**
+- The input needs to auto-focus on page load
+- Immediate interactivity is important for UX
+- The input is a simple text/email/password field without complex state
+
+**Don't use `disableSkeleton` when:**
+- The input has complex state that could cause hydration mismatches
+- The input relies on client-only data that isn't available during SSR
+- You're unsure - the default skeleton behavior is safer
+
+## Migration Checklist
+
+- [ ] Identify inputs that need immediate interactivity (e.g., login forms)
+- [ ] Add `disableSkeleton` prop to those inputs
+- [ ] Add `autoFocus` if the input should focus on page load
+- [ ] Test that hydration works correctly (no console errors)

package/docs/migrations/2026/02/2026-02-16-env-utils-from-clicktap-ui.md

@@ -0,0 +1,94 @@
+# Environment Utilities from @clicktap/ui
+
+**Date:** 2026-02-16
+**Affects:** All files importing `isDevelopment` / `isProduction` from local `utils/env`
+**Classification:** IMPROVEMENT
+**Breaking:** No
+
+## Dependencies
+
+- [Payment Method Error Handling](../../../../../../apps/frontend/docs/migrations/2026/01/2026-01-14-payment-error-handling.md) — introduced the local `utils/env.ts`
+
+## Summary
+
+The `isDevelopment` and `isProduction` boolean constants have been moved from the frontend's local `utils/env.ts` into `@clicktap/ui/utils/env`, making them available to all apps consuming `@clicktap/ui`. The local file has been deleted.
+
+## Problem
+
+The `isDevelopment` / `isProduction` utility was defined locally in `apps/frontend/utils/env.ts`. Other apps (admin, future storefronts) that need the same pattern would have to duplicate it. Moving it into the shared UI library centralises the definition.
+
+Additionally, the `@clicktap/ui` Vite build was replacing `process.env.NODE_ENV` with `"production"` at library build time, which meant any `NODE_ENV`-based guards inside the UI library (e.g., `console.warn` in the Image component) were dead-code-eliminated before consumers ever saw them. A `define` override in `libs/ui/vite.config.ts` now preserves `process.env.NODE_ENV` so the **consuming app's** bundler handles the replacement.
+
+## Changes
+
+### Vite library build fix
+
+The `@clicktap/ui` Vite config now includes:
+
+```ts
+define: {
+  'process.env.NODE_ENV': 'process.env.NODE_ENV',
+},
+```
+
+This prevents Vite from baking `"production"` into the published bundle, so environment-guarded code (like dev-only `console.warn`) works correctly at the consumer's build time.
+
+**Source:** `libs/ui/vite.config.ts`
+
+### New shared utility
+
+```ts
+// @clicktap/ui/utils/env
+export const isDevelopment = process.env.NODE_ENV === 'development';
+export const isProduction = process.env.NODE_ENV === 'production';
+```
+
+**Source:** `libs/ui/src/utils/env.ts`
+
+### Import change
+
+**Before:**
+```ts
+import { isDevelopment } from '../utils/env';
+import { isDevelopment } from '../../../utils/env';
+import { isDevelopment } from '../../../../../utils/env';
+```
+
+**After:**
+```ts
+import { isDevelopment } from '@clicktap/ui/utils/env';
+```
+
+### Files changed
+
+| File | Change |
+|------|--------|
+| `apps/frontend/utils/env.ts` | Deleted |
+| `providers/CybersourceMicroformV2Provider.tsx` | Import updated |
+| `components/Checkout/ExpressCheckout/PaypalButton.tsx` | Import updated |
+| `components/Checkout/ExpressCheckout/GooglePayButton.tsx` | Import updated |
+| `components/Checkout/ExpressCheckout/ApplePayButton.tsx` | Import updated |
+| `components/Checkout/ExpressCheckout/AmazonPayButton.tsx` | Import updated |
+| `components/Checkout/Step/Review/CheckoutButton/ApplePayCheckoutButton.tsx` | Import updated |
+| `components/Checkout/Step/Review/CheckoutButton/GooglePayCheckoutButton.tsx` | Import updated |
+| `components/Checkout/Step/Review/CheckoutButton/PaypalCheckoutButton.tsx` | Import updated |
+| `components/Checkout/Step/Review/CheckoutButton/AmazonCheckoutButton.tsx` | Import updated |
+| `components/Checkout/Step/Payment/Authorizenet/AuthorizenetPaymentMethod.tsx` | Import updated |
+
+## Migration Steps
+
+1. Update `@clicktap/ui` to the version containing this change.
+2. Find all imports from the local `utils/env`:
+   ```bash
+   grep -r "from.*utils/env" apps/frontend/
+   ```
+3. Replace each import path with `@clicktap/ui/utils/env`.
+4. Delete `apps/frontend/utils/env.ts`.
+5. Run typecheck to confirm no broken imports.
+
+## Migration Checklist
+
+- [ ] Update `@clicktap/ui` to latest
+- [ ] Replace all `utils/env` imports with `@clicktap/ui/utils/env`
+- [ ] Delete `apps/frontend/utils/env.ts`
+- [ ] Run typecheck: `nx run frontend:typecheck`

package/docs/migrations/2026/02/2026-02-17-select-popover-portal-container-restored.md

@@ -0,0 +1,84 @@
+# Select popoverPortalContainer Restored
+
+**Date:** 2026-02-17
+**Affects:** `@clicktap/ui` Select component, any consumer using Select inside Dialog or Modal
+**Classification:** BUGFIX
+**Breaking:** No
+
+## Dependencies
+
+*None*
+
+## Summary
+
+The `popoverPortalContainer` prop was incorrectly removed from the Select component on 2026-01-30 during the react-aria upgrade refactor. This prop controls where the Popover is portalled, which is essential when Select is used inside a Dialog — without it, the Popover renders into `document.body`, causing incorrect width calculation because both Dialog and Popover use react-aria's Modal internals. The prop has been restored using `UNSAFE_PortalProvider` from `react-aria`.
+
+## Problem
+
+The react-aria upgrade (commits `7c27599` and `93ae6b3` on 2026-01-30) removed `popoverPortalContainer` in two steps:
+
+1. Commit `7c27599` correctly migrated from `UNSTABLE_portalContainer` (on Popover) to `UNSAFE_PortalProvider` (wrapper), preserving the feature
+2. Commit `93ae6b3` then removed the feature entirely — deleting the prop from types, removing the `UNSAFE_PortalProvider` import and conditional rendering
+
+The migration guide in [Checkout Fixes — Section 6](../../../../../../apps/frontend/docs/migrations/2026/01/2026-01-14-checkout-fixes.md) was updated to document this removal as intentional. It was not — `popoverPortalContainer` was a working feature, not a deprecated one.
+
+**If your codebase was updated following that migration guide**, you may have removed `popoverPortalContainer` usage from Select instances. Review git history around 2026-01-30 for removals:
+
+```bash
+git log --all --oneline --after="2026-01-28" --before="2026-02-01" -- '*.tsx' '*.ts' | head -20
+git log --all -p --after="2026-01-28" --before="2026-02-01" -S "popoverPortalContainer" -- '*.tsx'
+```
+
+## Changes
+
+| File | What changed |
+|------|-------------|
+| `libs/ui/src/components/Select/Select.tsx` | Restored `UNSAFE_PortalProvider` import from `react-aria`; restored conditional portal wrapping |
+| `libs/ui/src/components/Select/Select.types.ts` | Restored `popoverPortalContainer?: () => HTMLElement | null` prop |
+
+### Restored behavior
+
+When `popoverPortalContainer` is provided, the Popover is wrapped in `UNSAFE_PortalProvider` which controls where the portal renders. When omitted, default react-aria behavior applies (portal to `document.body`).
+
+```tsx
+// Select.tsx — restored conditional
+{popoverPortalContainer ? (
+  <UNSAFE_PortalProvider getContainer={popoverPortalContainer}>
+    {popoverContent}
+  </UNSAFE_PortalProvider>
+) : (
+  popoverContent
+)}
+```
+
+**Source:** `libs/ui/src/components/Select/Select.tsx:209`
+
+## Migration Steps
+
+1. **If you removed `popoverPortalContainer` from Select usage** following the previous migration guide, restore it:
+
+   ```tsx
+   // Restore this where Select is used inside Dialog/Modal
+   <Select popoverPortalContainer={() => dialogRef.current}>
+   ```
+
+2. **Note the type change from the original API** — this was correctly updated during the react-aria upgrade and remains changed:
+
+   ```tsx
+   // Old (pre-upgrade)
+   popoverPortalContainer?: Element;
+
+   // Current (restored)
+   popoverPortalContainer?: () => HTMLElement | null;
+   ```
+
+   The prop now takes a **getter function** instead of a direct element reference.
+
+3. **The `UNSAFE_PortalProvider` import is from `react-aria`**, not `react-aria-components`. If you have custom components that also need portal control, import from the correct package.
+
+## Migration Checklist
+
+- [ ] Search git history for removed `popoverPortalContainer` usage around 2026-01-30
+- [ ] Restore `popoverPortalContainer` on any Select used inside Dialog, Modal, or other overlay contexts
+- [ ] Update prop value from `Element` to `() => HTMLElement | null` getter if restoring pre-upgrade code
+- [ ] Verify Select popover width matches trigger width when rendered inside Dialog

package/docs/migrations/2026/03/2026-03-24-image-dimmed-hidden-onready.md

@@ -0,0 +1,108 @@
+# Image: dimmed, hidden, and onReady Props
+
+**Date:** 2026-03-24
+**Affects:** `@clicktap/ui` — `Image` component
+**Classification:** IMPROVEMENT
+**Breaking:** No
+**Group:** plp-image-transitions
+
+## Dependencies
+
+*None*
+
+See also: [Collection Image Filter Transitions](../../../../../../apps/frontend/docs/migrations/2026/03/2026-03-24-collection-image-filter-transitions.md) ↔ — frontend implementation using these props
+
+## Summary
+
+The `Image` component gains three optional props for opacity-based loading transitions: `dimmed` (50% opacity), `hidden` (0% opacity), and `onReady` (callback when a new image loads after src change). When none of these props are passed, the component behaves exactly as before (blur-based loading). This also fixes a flicker bug caused by `onError` firing on valid images.
+
+## Problem
+
+Two issues existed:
+
+1. **No way to coordinate image transitions** — collection grids needed to dim/hide images during filter changes to prevent stale variant images from flashing. The `Image` component had no props for external opacity control.
+
+2. **onError flicker** — Next.js image optimization can fire `onError` on valid images when one `srcSet` variant fails while another succeeds. The immediate `setErrorSrc` call caused a re-render that produced a visible flicker. Additionally, `key={srcKey}` on the error boundary caused a full component remount on every src change.
+
+## Changes
+
+### New props on `ExtendedImageProps`
+
+```typescript
+export type ExtendedImageProps = ImageProps & {
+  /** Reduce opacity to 50% (e.g., while waiting for data) */
+  dimmed?: boolean;
+  /** Hide image completely — opacity 0 (e.g., before grid rearrange) */
+  hidden?: boolean;
+  /** Fires when a new image has loaded after a src change */
+  onReady?: () => void;
+};
+```
+
+**Source**: `libs/ui/src/components/Image/Image.tsx:62-69`
+
+### Managed vs unmanaged mode
+
+When `dimmed`, `hidden`, or `onReady` are passed ("managed" mode):
+- Opacity transitions replace the blur loading effect
+- `opacity: 0` when hidden, `0.5` when loading or dimmed, `1` when loaded
+- Src changes are detected during render (not `useEffect`) to prevent stale frame flash
+- `onReady` fires when a new image finishes loading
+
+When none are passed ("unmanaged" mode):
+- Existing blur-based loading (`blur-md`) is preserved
+- No opacity management, no src change detection
+- Fully backward compatible
+
+### onError debounce (bugfix)
+
+`onError` now uses a 2-second debounced timeout. If `onLoad` fires within that window (which it does for valid images), the timeout is cleared and no error fallback occurs.
+
+**Before:**
+```tsx
+onError={() => setErrorSrc(src)}
+```
+
+**After:**
+```tsx
+onError={() => {
+  errorTimer.current = setTimeout(() => setErrorSrc(src), 2000);
+}}
+onLoad={(e) => {
+  clearTimeout(errorTimer.current);
+  setLoadingImg(false);
+  // ...
+}}
+```
+
+### Error boundary key removal (bugfix)
+
+The `key={srcKey}` on `ImageErrorBoundary` has been removed. It was causing a full component remount on every src change, which destroyed state and produced flicker. The error boundary's `errorSrc` state check already handles src changes correctly.
+
+## Migration Steps
+
+No action required — these are additive, non-breaking changes. Existing `Image` usage is unaffected.
+
+To use the new props:
+
+```tsx
+import { Image } from '@clicktap/ui/components/Image';
+
+<Image
+  alt="Product"
+  src={imageUrl}
+  width={500}
+  height={625}
+  dimmed={isLoading}         // optional: 50% opacity
+  hidden={isHidden}          // optional: 0% opacity
+  onReady={() => onLoaded()} // optional: callback when loaded
+/>
+```
+
+## Migration Checklist
+
+- [ ] Verify existing `Image` usage still works (blur loading, error fallback)
+- [ ] Verify `dimmed` prop reduces opacity to 50%
+- [ ] Verify `hidden` prop hides image completely (opacity 0)
+- [ ] Verify `onReady` fires after src change + image load
+- [ ] Verify no flicker on images that previously flickered with `onError`

package/docs/migrations/2026/03/2026-03-24-modal-overlay-backdrop-dismiss.md

@@ -0,0 +1,81 @@
+# ModalOverlay: Fix Dismiss on Backdrop Click
+
+**Date:** 2026-03-24
+**Affects:** `@clicktap/ui` — `ModalOverlay` component
+**Classification:** BUGFIX
+**Breaking:** No
+
+## Dependencies
+
+*None*
+
+## Summary
+
+Clicking the backdrop overlay behind a drawer or modal did not dismiss it, even with `isDismissable` set. Pressing Escape and the close button worked correctly. The fix adds an explicit `onPointerDown` handler to the `ModalOverlay` that closes when the user clicks directly on the backdrop.
+
+## Problem
+
+react-aria's `useInteractOutside` hook detects clicks **outside** a ref element to trigger dismiss. However, the `ModalOverlay` component covers the entire viewport — so every click, including on the backdrop, is considered "inside" the overlay ref. The dismiss never fires for backdrop clicks.
+
+The `Modal` component already had `pointer-events-none [&>*]:pointer-events-auto` to let clicks pass through to the overlay, but react-aria's event detection still could not distinguish backdrop clicks from content clicks.
+
+## Changes
+
+**File**: `libs/ui/src/components/ModalOverlay/ModalOverlay.tsx`
+
+The `InnerModalOverlay` component now:
+
+1. Extracts `onOpenChange` from props (previously spread via `...restProps`)
+2. Adds a `handlePointerDown` callback that calls `onOpenChange(false)` when the click target is the overlay element itself (`e.target === e.currentTarget`)
+3. Passes both `onOpenChange` and `onPointerDown` to the overlay element
+
+```tsx
+const {
+  key,
+  shouldCloseOnInteractOutside: propShouldClose,
+  onOpenChange,
+  ...restProps
+} = props;
+
+// react-aria's useInteractOutside checks clicks outside the overlay ref,
+// but since the overlay covers the viewport, backdrop clicks are "inside"
+// and never trigger dismiss. Handle backdrop clicks explicitly.
+const handlePointerDown = useCallback(
+  (e: PointerEvent<HTMLDivElement>) => {
+    if (isDismissable && e.target === e.currentTarget && onOpenChange) {
+      onOpenChange(false);
+    }
+  },
+  [isDismissable, onOpenChange],
+);
+
+const commonProps = {
+  isDismissable,
+  shouldCloseOnInteractOutside,
+  onOpenChange,
+  onPointerDown: handlePointerDown,
+  // ...rest
+};
+```
+
+**Source**: `libs/ui/src/components/ModalOverlay/ModalOverlay.tsx:139-183`
+
+The `e.target === e.currentTarget` check ensures that only clicks directly on the backdrop trigger dismiss — clicks on child elements (the drawer/dialog content) are ignored because `e.target` would be a descendant, not the overlay itself.
+
+## Migration Steps
+
+1. Update `libs/ui/src/components/ModalOverlay/ModalOverlay.tsx`:
+   - Add `PointerEvent` to the React type imports
+   - Destructure `onOpenChange` from props alongside `key` and `shouldCloseOnInteractOutside`
+   - Add the `handlePointerDown` callback
+   - Add `onOpenChange` and `onPointerDown: handlePointerDown` to `commonProps`
+
+2. Verify by opening any drawer (e.g., cart drawer) and clicking the dark backdrop area — it should now close.
+
+## Migration Checklist
+
+- [ ] Update `ModalOverlay.tsx` with the `handlePointerDown` handler
+- [ ] Verify drawers dismiss on backdrop click
+- [ ] Verify clicking inside a drawer does **not** dismiss it
+- [ ] Verify Escape key still dismisses
+- [ ] Verify close button still works

package/docs/migrations/2026/04/2026-04-17-select-address-input-onchange-key-or-item.md

@@ -0,0 +1,182 @@
+# Select / AddressInput: `onSelectionChange` / `onChange` callback widened to `Key | T`
+
+**Date:** 2026-04-17 *(documentation date; underlying react-aria upgrade landed 2026-01-19 via commit `7c27599b2a`)*
+**Affects:** Frontend apps consuming `@clicktap/ui`'s `Select` and components that re-export its types (`AddressInput`, etc.). Any handler typed as `(value: Key) => void` breaks after the update.
+**Classification:** COMPATIBILITY
+**Breaking:** Yes — TypeScript-only. No runtime change; existing handlers still receive the same value at runtime, but strict TS setups fail to compile.
+
+## Dependencies
+
+| Package | Minimum version |
+|---|---|
+| `@clicktap/ui` | The release that bundles `react-aria-components ^1.12.x` (commit `7c27599b2a`). Confirm with `pnpm why react-aria-components` that the resolved version is `>= 1.12.0`. |
+
+## Summary
+
+`@clicktap/ui`'s `Select<T>` extends `AriaComboBoxProps<T>`. After the react-aria upgrade, the `onSelectionChange` argument type widened from `Key | null` to effectively `Key | null | T` — callers can now receive either the selected item's key **or**, in certain configurations, the full item object, depending on how the consumer sets up `items` and `selectedKey`.
+
+For consumer handlers that were strictly typed `(key: Key) => void`, TypeScript now complains that `Key | T` is not assignable to `Key`. The fix is to narrow at the callback entry point.
+
+## Consumer Impact
+
+Types changed:
+
+| Type | Before | After |
+|---|---|---|
+| `SelectProps<T>['onSelectionChange']` | `(key: Key \| null) => void` | `(key: Key \| null \| T) => void` (widened union) |
+| `AddressInputProps['onChange']` (in `apps/frontend/components/AddressForm/AddressInput`) | Re-typed to `(address?: AddressSuggestion) => void` — consumer-owned. Still works after upgrade if the inner `onSelectionChange` handler narrows correctly. |
+
+Find affected handlers:
+
+```bash
+# Handlers passed to Select or wrappers that assume `Key` only
+grep -rn 'onSelectionChange\|onChange=' apps/frontend/ | \
+  grep -E 'Select|AddressInput|Combobox|Dropdown' | \
+  head -40
+```
+
+## Preconditions
+
+- [ ] `@clicktap/ui` is pinned to the release containing commit `7c27599b2a` or later. Check with:
+  ```bash
+  jq '.dependencies["@clicktap/ui"]' apps/frontend/package.json
+  ```
+- [ ] `apps/frontend/package.json` is tracked in git. Some legacy project layouts gitignore it — de-ignore before applying changes so CI/typecheck runs see the fix.
+
+## Migration Steps
+
+### 1. Narrow the argument in your handler
+
+The cleanest fix is a type guard at the callback boundary:
+
+```tsx
+// Before — TS error after upgrade
+<Select
+  items={items}
+  onSelectionChange={(key: Key) => {
+    selectItemByKey(key);
+  }}
+/>
+
+// After — narrow the widened union
+<Select
+  items={items}
+  onSelectionChange={(keyOrItem) => {
+    const key = typeof keyOrItem === 'string' || typeof keyOrItem === 'number'
+      ? keyOrItem
+      : keyOrItem?.id;            // or whatever your T's key field is
+    if (key === null || key === undefined) return;
+    selectItemByKey(key);
+  }}
+/>
+```
+
+> **For consumers with 10+ call sites:** the per-site narrow above gets repetitive. Consider extracting a local helper to your project's `utils/` module:
+>
+> ```ts
+> import type { Key } from 'react-aria-components';
+>
+> export function narrowKey<T extends { id: Key }>(
+>   value: Key | T | null,
+> ): Key | null {
+>   if (value === null) return null;
+>   if (typeof value === 'string' || typeof value === 'number') return value;
+>   return value.id;
+> }
+> ```
+>
+> Then each call site becomes `onSelectionChange={(v) => { const key = narrowKey(v); if (key !== null) selectItemByKey(key); }}`. We may upstream this helper to `@clicktap/ui/utils` in a future release; for now, ship it locally if your codebase has enough call sites to justify the abstraction.
+
+### 2. If you need the full item, accept it directly
+
+When a handler wants the full `T`, skip the narrow and type against it:
+
+```tsx
+type Option = { id: Key; label: string };
+
+<Select<Option>
+  items={options}
+  onSelectionChange={(value) => {
+    // value is Key | null | Option — narrow by shape
+    const option = typeof value === 'object' && value !== null ? value : null;
+    if (option) onOptionSelected(option);
+  }}
+/>
+```
+
+### 3. For wrappers like `AddressInput`, narrow inside the wrapper once
+
+If your app wraps `Select` (the clicktap `AddressInput` does this), narrow in one place so every consumer of the wrapper keeps its old `(address?: T) => void` contract:
+
+```tsx
+// apps/frontend/components/AddressForm/AddressInput/AddressInput.tsx
+<Select<AddressSuggestion>
+  items={suggestions}
+  onSelectionChange={(keyOrItem) => {
+    const selection = typeof keyOrItem === 'object' && keyOrItem !== null
+      ? keyOrItem
+      : suggestions.find((s) => s.key === keyOrItem);
+    props.onChange?.(selection);
+  }}
+/>
+```
+
+### Verification
+
+```bash
+# Typecheck should pass with zero errors mentioning onSelectionChange
+nx run frontend:typecheck
+```
+
+## Consumer-Project Workaround
+
+If for any reason the consumer project can't yet take the new `@clicktap/ui` release but must compile:
+
+1. **Pin the previous minor** in `apps/frontend/package.json`:
+   ```json
+   "@clicktap/ui": "~X.Y.Z"
+   ```
+   Replace `X.Y.Z` with the last minor before the react-aria 3.43.x bump.
+
+2. **Or wrap locally** until ready — shadow `Select` in a local component that narrows the callback before forwarding:
+   ```tsx
+   // apps/frontend/components/LegacySelect.tsx
+   import { Select as UpstreamSelect, type SelectProps } from '@clicktap/ui/components/Select';
+   import type { Key } from 'react-aria-components';
+
+   type LegacySelectProps<T extends { id: Key }> = Omit<SelectProps<T>, 'onSelectionChange'> & {
+     onSelectionChange?: (key: Key | null) => void;
+   };
+
+   export function LegacySelect<T extends { id: Key }>(props: LegacySelectProps<T>) {
+     return (
+       <UpstreamSelect<T>
+         {...props}
+         onSelectionChange={(v) => {
+           const key = typeof v === 'object' && v !== null ? v.id : v;
+           props.onSelectionChange?.(key ?? null);
+         }}
+       />
+     );
+   }
+   ```
+
+Prefer the narrow-in-handler fix over the wrapper — the wrapper is only for bulk migrations where touching every call site at once isn't feasible.
+
+## Rollback
+
+Revert `@clicktap/ui` in `apps/frontend/package.json`:
+
+```bash
+docker compose exec -u app node-app pnpm --filter frontend add '@clicktap/ui@<previous-minor>'
+```
+
+Safe — TypeScript-only change. No persistent state involved.
+
+## References
+
+- Upstream commit: `7c27599b2a` — `refactor(ui): upgrade react-aria and refactor Select component`
+- react-aria upgrade: `react-aria ^3.43.1`, `react-aria-components ^1.12.2`
+- Existing related guide: `docs/migrations/2026-01-14-checkout-fixes.md` (partially documents this upgrade; expand with the onSelectionChange narrowing pattern above)
+- Source: `libs/ui/src/components/Select/Select.types.ts`
+- Wrapper reference: `apps/frontend/components/AddressForm/AddressInput/AddressInput.types.ts`