@clicktap/ui 0.40.8 → 0.40.9

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`

package/docs/migrations/2026/04/2026-04-24-image-placeholder-frontend-fallback.md

@@ -0,0 +1,85 @@
+# `PLACEHOLDER_IMAGE` Export from `@clicktap/ui/utils/placeholder`
+
+**Date:** 2026-04-24
+**Affects:** `@clicktap/ui` consumers that render product/category images
+**Classification:** IMPROVEMENT
+**Breaking:** No
+
+## Dependencies
+
+- See [frontend counterpart](2026-04-24-image-placeholder-frontend-fallback.md) ↔ for the consuming-app changes.
+
+## Summary
+
+Adds `PLACEHOLDER_IMAGE` — a self-contained data URL — to `@clicktap/ui/utils/placeholder`. Frontend apps render this whenever they have a null image to display, replacing the old "backend returns a placeholder URL" pattern.
+
+The value is an inline `data:image/svg+xml;utf8,...` string containing a neutral grayscale "no image available" SVG (camera icon with diagonal slash). Works in every bundler (Next.js, Storybook, Jest, vanilla node) without consumer-side asset pipeline configuration — no `public/` copy, no rewrite, no build script.
+
+## Changes
+
+### New export
+
+```ts
+// libs/ui/src/utils/placeholder.ts
+export const PLACEHOLDER_IMAGE: string;
+```
+
+Import path:
+
+```ts
+import { PLACEHOLDER_IMAGE } from '@clicktap/ui/utils/placeholder';
+```
+
+### What it looks like
+
+The SVG is 200×200, viewBox `0 0 200 200`, with:
+- Light gray background (`#f3f4f6`)
+- Camera icon (rect + viewfinder bump + concentric lens circles), stroke `#9ca3af` weight 4
+- Diagonal slash from upper-right to lower-left at 45° through the camera
+
+The body is centered on the canvas (lens at canvas center 100,100); slash passes through canvas center. Symmetric.
+
+## Pattern for Consumers
+
+Use directly as the `src` for any image renderer:
+
+```tsx
+import { Image } from '@clicktap/ui/components/Image';
+import { PLACEHOLDER_IMAGE } from '@clicktap/ui/utils/placeholder';
+
+<Image
+  src={product.image ?? PLACEHOLDER_IMAGE}
+  alt={product.name}
+  // ...
+/>
+```
+
+Works equally well with raw `<img>`:
+
+```tsx
+<img src={product.image ?? PLACEHOLDER_IMAGE} alt="" />
+```
+
+For the PDP/PLP migration, see the [frontend counterpart guide](2026-04-24-image-placeholder-frontend-fallback.md) — it covers the full cascade decision (variant → placeholder, no parent fallback) and the dead `no_selection` checks to remove.
+
+## Files Changed
+
+| File | What changed |
+|---|---|
+| `libs/ui/src/utils/placeholder.ts` | New file. Inlines the SVG and exports a data-URL constant. |
+| `libs/ui/src/assets/clicktap-placeholder.svg` | New file. Source of truth for the SVG; the data URL above is a byte-for-byte copy. Keep in sync if the icon changes. |
+| `libs/ui/package.json` | Adds `./assets/*` to the `exports` map (already in place from earlier work; mentioned here for completeness). |
+
+## Migration Checklist
+
+- [ ] `@clicktap/ui >= 0.27.0` installed in consumers.
+- [ ] No need to copy any SVG into the consuming app's `public/` folder.
+- [ ] Apply the [frontend counterpart guide](2026-04-24-image-placeholder-frontend-fallback.md) for the consuming-app changes.
+
+## Why a data URL and not a bundled file?
+
+Three reasons:
+
+1. **Zero consumer setup.** A bundled file requires consumers to either copy it into `public/` or configure a static-file plugin. A data URL works on import.
+2. **Bundler-agnostic.** The `@clicktap/ui` package ships to apps using Next.js, Storybook, and Jest test runners. SVG-as-static-asset semantics differ across them; a string constant is identical everywhere.
+3. **Tiny payload.** The SVG is ~700 bytes; URL-encoded it's ~1KB. Network overhead vs an HTTP-fetched SVG is negligible and we avoid a second request.

package/docs/migrations/2026/04/2026-04-30-prune-invalid-pdp-selections.md

@@ -0,0 +1,166 @@
+# PDP Option Selection — Conservative Prune Helper (`pruneInvalidSelections`)
+
+**Date:** 2026-04-30
+**Affects:** `@clicktap/ui/utils/variantOptions` — adds `pruneInvalidSelections`
+**Classification:** IMPROVEMENT
+**Breaking:** No (additive)
+
+## Dependencies
+
+- Builds on [`2026-04-30-top-down-pdp-option-dependency.md`](./2026-04-30-top-down-pdp-option-dependency.md). That migration introduced top-down option filtering with a blanket "clear every downstream selection on any upstream change". This migration replaces the recommended consumer pattern with a more conservative prune that preserves still-valid downstream picks.
+- Frontend counterpart: [`apps/frontend/.../2026-04-30-prune-invalid-pdp-selections.md`](2026-04-30-prune-invalid-pdp-selections.md) ↔.
+
+## Summary
+
+Adds `pruneInvalidSelections(variants, selections, axes)` to `@clicktap/ui/utils/variantOptions`. Walks the selection map top-to-bottom and drops only entries whose value is no longer reachable under the (possibly already-pruned) upstream context. Preserves user intent: a downstream pick is dropped only when actually invalid, never just because an upstream sibling changed.
+
+`getDownstreamAxisCodes` is kept exported for convenience but the recommended `setUserSelection` pattern now uses `pruneInvalidSelections` instead.
+
+## Why
+
+The previous `setUserSelection` pattern (from the earlier 2026-04-30 migration) blanket-cleared every axis downstream of the changed one. That's correct, but it discards user intent in a common case:
+
+- User has `Color=Red, Size=Large, Material=Cotton`.
+- User changes `Color` to `Blue`.
+- If `Blue+Large+Cotton` is a real variant, blanket-clear still drops both `Size` and `Material` and forces the user to repick.
+
+`pruneInvalidSelections` keeps still-valid downstream picks. Three behaviors:
+
+| Scenario | Blanket clear (old) | Prune (new) |
+|---|---|---|
+| `Blue+Large+Cotton` is a real variant | Drops Size and Material | Keeps both |
+| `Blue+Large` exists but `Blue+Large+Cotton` doesn't | Drops Size and Material | Keeps Size, drops Material |
+| `Blue+Large` doesn't exist | Drops Size and Material | Drops Size and Material |
+
+## Public API
+
+```ts
+import {
+  pruneInvalidSelections,
+  filterAvailableOptions,
+  findVariant,
+  getDownstreamAxisCodes,
+} from '@clicktap/ui/utils/variantOptions';
+```
+
+```ts
+/**
+ * Walks `selections` top-to-bottom along `axes` and drops any whose value
+ * is no longer reachable under the (possibly already-pruned) upstream
+ * context.
+ *
+ * Validates the entire selection map, not just downstream of one axis —
+ * works for both selection mutation and URL/state rehydration.
+ *
+ * Returns the same object reference when nothing was dropped, so callers
+ * can use `===` to skip downstream state updates.
+ */
+function pruneInvalidSelections<V extends VariantLike>(
+  variants: V[],
+  selections: Record<string, string>,
+  axes: string[],
+): Record<string, string>;
+```
+
+Implementation properties worth knowing:
+
+- **Top-to-bottom iteration**: each axis evaluates against axes earlier in `axes` that have already been validated this pass. Cascades through naturally — if an upstream pick gets dropped, downstream is re-checked against the now-empty upstream slot.
+- **Object identity preserved**: returns `selections` unchanged when nothing is dropped. Lets `useState` setters skip downstream re-renders via referential equality.
+- **Conservative**: a downstream value is dropped only when its reachable set (under current upstream) doesn't contain it. Independence between sibling axes is preserved. E.g. switching `Color: Red→Blue` keeps `Material: Cotton` even when `Size` was dropped, as long as `Blue+(any size)+Cotton` exists.
+
+## Pattern for Consumers
+
+Replace `getDownstreamAxisCodes` + manual delete in your selection handler with `pruneInvalidSelections` over the full candidate map. **Read the previous selections from the closure and run all side effects in event-handler scope — do NOT use the functional-updater form of setState here**:
+
+```tsx
+import { pruneInvalidSelections } from '@clicktap/ui/utils/variantOptions';
+
+const setSelection = useCallback(
+  (axisCode: string, optionCode: string) => {
+    if (selections[axisCode] === optionCode) {
+      return;
+    }
+    const candidate = { ...selections, [axisCode]: optionCode };
+    // Prune cascades: top-to-bottom, each axis reads pruned upstream.
+    const next = pruneInvalidSelections(variants, candidate, axisCodes);
+
+    setSelections(next);
+    writeSelectionsToUrl(next); // or any other side effect
+  },
+  [axisCodes, selections, variants],
+);
+```
+
+> ⚠ **Don't put side effects inside a `setSelections((prev) => ...)` updater.**
+> React requires functional updaters to be pure — no calls that schedule
+> updates on other components, no mutations. Calling `router.replace()` (or
+> any side effect that dispatches into another component's render cycle)
+> from inside an updater triggers `"Cannot update a component while
+> rendering a different component"` and a recoverable crash on
+> first-select / deselect interactions. React 19 enforces this harder.
+> Read the previous state from the closure and put side effects after the
+> setter, in the event-handler scope. Trade-off: closure-read loses
+> stale-closure protection if multiple selections fire in the same
+> event-loop tick — fine for swatch clicks paced by humans, but if you
+> wire a programmatic batch-set-multiple-axes flow on top, defer the side
+> effects to a `useEffect` keyed on `selections` and bring back the
+> functional updater for the state write.
+
+If your component tracks per-axis manual-clear flags (so auto-collapse doesn't re-fill an axis the user explicitly cleared), only unflag the axes that the prune actually dropped:
+
+```tsx
+const candidate = { ...selections, [axisCode]: optionCode };
+const next      = pruneInvalidSelections(variants, candidate, axisCodes);
+
+for (const code of axisCodes) {
+  if (candidate[code] !== undefined && next[code] === undefined) {
+    manuallyClearedAxes.current.delete(code);
+  }
+}
+
+setSelections(next);
+writeSelectionsToUrl(next);
+```
+
+Otherwise, a kept (still-valid) selection could later get auto-collapsed back to a value the user previously cleared.
+
+## Migration Steps
+
+This is purely additive — existing code keeps compiling. To adopt:
+
+### 1. Bump `@clicktap/ui`
+
+```bash
+pnpm up @clicktap/ui
+```
+
+Minimum version: **next minor after the release that ships this migration**.
+
+### 2. Replace blanket clear with prune in selection handlers
+
+Find every call site that uses `getDownstreamAxisCodes` to clear downstream selections:
+
+```bash
+grep -rn 'getDownstreamAxisCodes' apps/ libs/ --include='*.ts' --include='*.tsx'
+```
+
+Replace the manual delete loop with a single `pruneInvalidSelections` call (see "Pattern for Consumers" above). `getDownstreamAxisCodes` itself stays exported for any caller that genuinely needs the codes for non-prune purposes.
+
+### Verification
+
+- **Behavior**: change an upstream axis on a configurable PDP. Confirm a downstream selection that's still reachable (i.e. the new combination is a real variant) stays selected. Confirm a downstream selection that's now unreachable gets dropped.
+- **Lib tests**: `nx test ui --testPathPattern variantOptions` → 26 tests pass (was 15).
+- **Typecheck**: `nx run frontend:typecheck` (or your app equivalent) → no errors.
+
+## Files Changed
+
+| File | Change |
+|---|---|
+| `libs/ui/src/utils/variantOptions/pruneInvalidSelections.ts` | New — top-to-bottom prune helper |
+| `libs/ui/src/utils/variantOptions/pruneInvalidSelections.test.ts` | New — Jest coverage (11 tests) |
+| `libs/ui/src/utils/variantOptions/index.ts` | Export `pruneInvalidSelections` |
+
+## References
+
+- Frontend counterpart migration: [`apps/frontend/.../2026-04-30-prune-invalid-pdp-selections.md`](2026-04-30-prune-invalid-pdp-selections.md) ↔
+- Previous top-down migration this builds on: [`2026-04-30-top-down-pdp-option-dependency.md`](./2026-04-30-top-down-pdp-option-dependency.md)