@clicktap/ui 0.40.7 → 0.40.9

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)

package/docs/migrations/2026/04/2026-04-30-top-down-pdp-option-dependency.md

@@ -0,0 +1,286 @@
+# Top-Down PDP Option Dependency — `@clicktap/ui/utils/variantOptions`
+
+**Date:** 2026-04-30
+**Affects:** New utility module `@clicktap/ui/utils/variantOptions` (ships generic `filterAvailableOptions`, `findVariant`, `getDownstreamAxisCodes`)
+**Classification:** IMPROVEMENT
+**Breaking:** No (additive)
+
+## Dependencies
+
+- Builds on the per-axis selection model used in [`apps/frontend/.../2026-04-24-pdp-configurable-selector-ux.md`](../../../../../../apps/frontend/docs/migrations/2026/04/2026-04-24-pdp-configurable-selector-ux.md). The previous symmetric filter lived in the frontend app; that logic now lives here in generic, reusable form. See [`apps/frontend/.../2026-04-30-top-down-pdp-option-dependency.md`](2026-04-30-top-down-pdp-option-dependency.md) ↔ for the frontend-side migration steps that adopt the new utilities and switch to top-down semantics.
+
+## Summary
+
+Adds a small reusable module — `@clicktap/ui/utils/variantOptions` — for any consumer that builds a configurable-PDP variant picker. Three pure functions:
+
+1. **`filterAvailableOptions(variants, selections, axes, axisCode)`** — top-down: returns option codes selectable for `axisCode` given only the *upstream* selections (axes earlier in `axes`). Downstream selections never constrain.
+2. **`findVariant(variants, selections)`** — first variant whose attributes match every non-empty selection; matches by option `code` or `id`.
+3. **`getDownstreamAxisCodes(axes, axisCode)`** — axis codes after `axisCode` in `axes`. Useful for clearing dependent selections when an upstream axis changes.
+
+All three are generic (`<V extends VariantLike>`) and operate on a minimal structural shape so consumers don't have to flatten their domain types. Pure, no React dependency, no side effects.
+
+## Why top-down
+
+Symmetric filtering — selecting any axis filters every other axis equally — is what most early implementations do. It feels coherent until the user wants to change a higher-priority pick: every dependent dropdown is now scoped by their previous lower picks, and they can't re-explore the upstream space without manually clearing each lower selection first.
+
+Top-down inverts the relationship: the *first* axis is always fully open, the *second* is filtered by the first, and so on. Changing the first axis is free. The cost is that the consumer must clear lower selections when an upstream changes (their value may not exist in the new scope) — `getDownstreamAxisCodes` makes that mechanical.
+
+This module ships the filter logic only. The selection-state mechanics (clearing downstream when upstream changes, URL sync, manual-clear guards) stay in the consumer app since those are wired into framework-specific state and routing.
+
+## Changes
+
+### New module
+
+**Source:** `libs/ui/src/utils/variantOptions/`
+
+```
+libs/ui/src/utils/variantOptions/
+├── filterAvailableOptions.ts
+├── filterAvailableOptions.test.ts
+├── findVariant.ts
+├── findVariant.test.ts
+├── getDownstreamAxisCodes.ts
+├── getDownstreamAxisCodes.test.ts
+├── index.ts
+└── types.ts
+```
+
+### Public API
+
+```ts
+import {
+  filterAvailableOptions,
+  findVariant,
+  getDownstreamAxisCodes,
+  type VariantLike,
+  type VariantAttribute,
+} from '@clicktap/ui/utils/variantOptions';
+```
+
+### Type contract
+
+The minimum structural shape required by every function:
+
+```ts
+// libs/ui/src/utils/variantOptions/types.ts
+export interface VariantAttribute {
+  attribute: { code: string };
+  option: { code: string; id?: string | null };
+}
+
+export interface VariantLike {
+  attributes: VariantAttribute[];
+}
+```
+
+Real-world variants typically carry far more (price, image, sku, …). Pass them in as-is — the generic constraint only requires `attributes`.
+
+### `filterAvailableOptions`
+
+```ts
+export function filterAvailableOptions<V extends VariantLike>(
+  variants: V[],
+  selections: Record<string, string>,
+  axes: string[],
+  axisCode: string,
+): Set<string>
+```
+
+- `axes` is the contract: top-down order, upstream → downstream. The caller decides ordering (typically via the attribute's `sortPriority` from the backend).
+- For `axisCode` at index `i` in `axes`, only `selections[axes[0]]…selections[axes[i-1]]` constrain. Selections on `axes[i+1]…` are ignored.
+- `axisCode === axes[0]` (or any axis not in `axes`) returns the full reachable set across `variants` for that code.
+- Empty-string and `undefined` selections are treated as unconstrained.
+
+### `findVariant`
+
+```ts
+export function findVariant<V extends VariantLike>(
+  variants: V[],
+  selections: Record<string, string>,
+): V | undefined
+```
+
+- Empty/missing selections per axis are unconstrained.
+- A selection matches if it equals either the option's `code` or `id` — supports callers that key by either.
+
+### `getDownstreamAxisCodes`
+
+```ts
+export function getDownstreamAxisCodes(
+  axes: string[],
+  axisCode: string,
+): string[]
+```
+
+- Returns `axes.slice(idx + 1)` where `idx = axes.indexOf(axisCode)`.
+- Returns `[]` if `axisCode` isn't in `axes` (defensive — caller may pass a non-axis code).
+
+## Pattern for Consumers
+
+A minimal PDP variant picker built on these utilities looks like this:
+
+```tsx
+import { useMemo, useCallback, useState } from 'react';
+import {
+  filterAvailableOptions,
+  findVariant,
+  getDownstreamAxisCodes,
+} from '@clicktap/ui/utils/variantOptions';
+
+type Variant = {
+  id: string;
+  attributes: Array<{
+    attribute: { code: string };
+    option: { code: string; id?: string };
+  }>;
+  // ...your domain fields
+};
+
+type Props = {
+  // Top-down ordered axes — upstream first.
+  axes: { code: string; label: string; options: { code: string; label: string }[] }[];
+  variants: Variant[];
+};
+
+export function VariantPicker({ axes, variants }: Props) {
+  const axisCodes = useMemo(() => axes.map((a) => a.code), [axes]);
+  const [selections, setSelections] = useState<Record<string, string>>({});
+
+  const setSelection = useCallback(
+    (axisCode: string, optionCode: string) => {
+      setSelections((prev) => {
+        // Top-down: clear any selection downstream of this axis. Their value
+        // may not exist in the new upstream scope.
+        const downstream = getDownstreamAxisCodes(axisCodes, axisCode);
+        const next: Record<string, string> = { ...prev, [axisCode]: optionCode };
+        for (const code of downstream) {
+          delete next[code];
+        }
+        return next;
+      });
+    },
+    [axisCodes],
+  );
+
+  const matchedVariant = useMemo(
+    () => findVariant(variants, selections),
+    [variants, selections],
+  );
+
+  return (
+    <div>
+      {axes.map((axis) => {
+        const reachable = filterAvailableOptions(
+          variants,
+          selections,
+          axisCodes,
+          axis.code,
+        );
+        return (
+          <div key={axis.code}>
+            <label>{axis.label}</label>
+            {axis.options
+              .filter((o) => reachable.has(o.code))
+              .map((o) => (
+                <button
+                  key={o.code}
+                  aria-pressed={selections[axis.code] === o.code}
+                  onClick={() => setSelection(axis.code, o.code)}
+                >
+                  {o.label}
+                </button>
+              ))}
+          </div>
+        );
+      })}
+      {matchedVariant && <p>Matched: {matchedVariant.id}</p>}
+    </div>
+  );
+}
+```
+
+Annotations:
+- The `setSelections` callback is the entire top-down rule — clear downstream on any upstream change. Skip this and the picker behaves as a buggy version of symmetric filtering.
+- `filterAvailableOptions` is called once per axis on each render. Cheap — O(variants × attributes).
+- The pattern intentionally doesn't cover URL sync, manual-clear guards, or auto-collapse. Those are framework- and routing-specific; layer them on top.
+
+## Migration Steps
+
+This module is purely additive — there's no migration *required* of existing `@clicktap/ui` consumers. The steps below are for consumers who want to adopt it.
+
+### 1. Bump `@clicktap/ui`
+
+Once a release including this module is published, update the dependency:
+
+```bash
+pnpm up @clicktap/ui
+```
+
+Minimum version: **next minor after 0.27.2** (set the explicit floor once released).
+
+### 2. Import where needed
+
+```ts
+import {
+  filterAvailableOptions,
+  findVariant,
+  getDownstreamAxisCodes,
+} from '@clicktap/ui/utils/variantOptions';
+```
+
+### 3. Pass top-down axis order
+
+Wherever you call `filterAvailableOptions`, pass the axes array in upstream-to-downstream order. The natural source is your attribute list sorted by priority — for backends following the Clicktap shape, that's `sortPriority DESC`:
+
+```ts
+const axisCodes = product.attributes.map((a) => a.code);
+// product.attributes is already sorted by sortPriority DESC server-side.
+
+const reachable = filterAvailableOptions(
+  product.variants,
+  userSelections,
+  axisCodes,
+  attribute.code,
+);
+```
+
+### 4. Clear downstream on upstream change
+
+When the user picks a value for any axis, drop any downstream selections in the same state update:
+
+```ts
+const setUserSelection = (axisCode: string, optionCode: string) => {
+  setSelections((prev) => {
+    const downstream = getDownstreamAxisCodes(axisCodes, axisCode);
+    const next = { ...prev, [axisCode]: optionCode };
+    for (const code of downstream) {
+      delete next[code];
+    }
+    return next;
+  });
+};
+```
+
+Skip this and you'll occasionally see the matched variant query against an impossible (upstream-changed but downstream-stale) selection set.
+
+### Verification
+
+- New axis renders all reachable options regardless of downstream state.
+- Picking the upper axis clears the lower selections.
+- Picking the lowest axis doesn't change which upper options are reachable.
+
+## Files Changed
+
+| File | Change |
+|---|---|
+| `libs/ui/src/utils/variantOptions/types.ts` | New — `VariantLike`, `VariantAttribute` |
+| `libs/ui/src/utils/variantOptions/filterAvailableOptions.ts` | New — top-down filter |
+| `libs/ui/src/utils/variantOptions/findVariant.ts` | New — generic match |
+| `libs/ui/src/utils/variantOptions/getDownstreamAxisCodes.ts` | New — slice helper |
+| `libs/ui/src/utils/variantOptions/index.ts` | New — barrel export |
+| `libs/ui/src/utils/variantOptions/*.test.ts` | New — Jest coverage (15 tests) |
+
+## References
+
+- Frontend counterpart migration: [`apps/frontend/.../2026-04-30-top-down-pdp-option-dependency.md`](2026-04-30-top-down-pdp-option-dependency.md) ↔
+- Prior symmetric-filter implementation it replaces: [`apps/frontend/.../2026-04-24-pdp-configurable-selector-ux.md`](../../../../../../apps/frontend/docs/migrations/2026/04/2026-04-24-pdp-configurable-selector-ux.md)

package/docs/migrations/2026/05/2026-05-01-build-pdp-url-util.md

@@ -0,0 +1,128 @@
+# `buildPdpUrl` Utility — `@clicktap/ui/utils/buildPdpUrl`
+
+**Date:** 2026-05-01
+**Affects:** `@clicktap/ui/utils/buildPdpUrl` — new export
+**Classification:** IMPROVEMENT
+**Breaking:** No (additive)
+
+## Dependencies
+
+*None.*
+
+## Summary
+
+Adds `buildPdpUrl(canonicalUrl, typeOptions)` to `@clicktap/ui/utils/buildPdpUrl`. Encodes a configurable item's variant selections onto its PDP canonical URL as `?attributeCode=optionCode` pairs, matching `ProductTypeResolver.writeSelectionsToUrl` so deep-linking from a cart/order item lands on the exact variant.
+
+## Why
+
+Cart and order item rows hold both a canonical URL (e.g. `/everyday-backpack`) and a list of selected attributes (e.g. `color: orange`, `size: m`). Linking with just the canonical URL drops the variant context — the customer lands on the PDP with no swatch pre-selected and has to re-pick. Encoding the selections onto the link mirrors what the PDP itself writes back to the URL on swatch change, so navigating into a PDP from a cart/order row produces the same URL as if the user had configured the PDP themselves.
+
+The helper was originally inlined under `apps/frontend/components/Checkout/Success/Items/buildPdpUrl.ts`, used only by the order-success page. Promoting it to `@clicktap/ui` makes it reusable from the cart drawer (and any future consumer that pairs a canonical URL with a `typeOptions`-shaped attribute list).
+
+## Public API
+
+```ts
+import { buildPdpUrl } from '@clicktap/ui/utils/buildPdpUrl';
+```
+
+```ts
+/**
+ * Append configurable-product variant selections to a PDP canonical URL as
+ * `?attributeCode=optionCode` pairs (e.g. `?color=black`).
+ *
+ * Accepts the structural shape that any cart-item / order-item / quote-item
+ * `typeOptions` produces on the configurable case.
+ *
+ * Returns the URL unchanged when:
+ *   - the URL is null/empty,
+ *   - the item isn't configurable (no attributes), or
+ *   - the existing URL already carries a query string (we don't merge —
+ *     the item's own variant context is authoritative, and bailing keeps
+ *     caller intent clear).
+ */
+function buildPdpUrl(
+  canonicalUrl: string | null | undefined,
+  typeOptions: unknown,
+): string | null;
+```
+
+The `typeOptions` parameter is intentionally typed `unknown` and read structurally as `{ attributes?: Array<{ attribute?: { code? }, option?: { code? } }> }`. This lets the same helper accept both `OrderItemTypeOptions` and `QuoteItemTypeOptions` (and any other GraphQL union with the same shape) without forcing the lib to import the consumer's generated types.
+
+## Behavior summary
+
+| Input | Output |
+|---|---|
+| `(null, ...)` | `null` |
+| `('', ...)` | `null` |
+| `('/foo', null)` | `'/foo'` |
+| `('/foo', { attributes: [] })` | `'/foo'` |
+| `('/foo', { attributes: [{ attribute: { code: 'color' }, option: { code: 'red' } }] })` | `'/foo?color=red'` |
+| `('/foo', { attributes: [{ color }, { size }] })` | `'/foo?color=red&size=m'` |
+| `('/foo?bar=1', { attributes: [...] })` | `'/foo?bar=1'` (URL has a query — bail rather than merge) |
+
+## Pattern for Consumers
+
+Use it wherever a cart/order item row links to its PDP and you want the variant pre-selected:
+
+```tsx
+import { Link } from '@clicktap/ui/components/Link';
+import { buildPdpUrl } from '@clicktap/ui/utils/buildPdpUrl';
+
+function CartItemRow({ item }: { item: QuoteItem }) {
+  const pdpUrl = buildPdpUrl(item.product.canonicalUrl, item.typeOptions) ?? '';
+  return (
+    <Link href={pdpUrl}>
+      {item.name}
+    </Link>
+  );
+}
+```
+
+The function is structural, so `item.typeOptions` doesn't need to be cast — pass it directly.
+
+## 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 any inlined copies with the shared util
+
+Search consumer projects for inlined copies that predate this migration:
+
+```bash
+grep -rn 'buildPdpUrl' apps/ libs/ --include='*.ts' --include='*.tsx'
+```
+
+Switch each call site to:
+
+```ts
+import { buildPdpUrl } from '@clicktap/ui/utils/buildPdpUrl';
+```
+
+If the consumer project had its own typed-to-`OrderItemTypeOptions` (or any other concrete) signature, the structural `unknown` parameter accepts it without any cast change at the call site — the existing arguments compile as-is.
+
+### 3. (Optional) Wire it into cart/order link components
+
+Anywhere a cart/order row currently links via `product.canonicalUrl` directly, swap to `buildPdpUrl(product.canonicalUrl, typeOptions)`. Make sure your GraphQL selection actually fetches `canonicalUrl` and the `typeOptions { ... attributes { attribute { code }, option { code } } }` block — without those, the helper returns the URL unchanged and the variant won't pre-select.
+
+### Verification
+
+- **Behavior**: open a cart drawer (or order success page) for a configurable product with attributes set, click the item link. The PDP should load with the swatches matching the variant pre-selected.
+- **Typecheck**: `nx run <app>:typecheck` → no errors.
+
+## Files Changed
+
+| File | Change |
+|---|---|
+| `libs/ui/src/utils/buildPdpUrl.ts` | New — structural helper |
+
+## References
+
+- PDP encoding source of truth: `apps/frontend/components/Product/ProductType/.../ProductTypeResolver.writeSelectionsToUrl`