@clicktap/ui 0.42.3 → 0.43.0

package/components/ResendCode/ResendCode.d.ts

@@ -4,6 +4,10 @@ import { ResendCodeProps } from './ResendCode.types';
  * request and cooldown state (e.g. via a resend hook composing `useCooldown`). Renders one of three
  * labels: the cooldown countdown, the in-flight label, or the idle action label; the button is
  * disabled unless `canResend`.
+ *
+ * A visually-hidden polite live region announces when resend becomes available (CTAP-1167). The
+ * announcement is a separate region — not `aria-live` on the button — so screen-reader users hear
+ * the cooldown END without having every one-second countdown label change read out.
  */
-export declare function ResendCode({ cooldownSeconds, isResending, canResend, onResend, prompt, label, resendingLabel, className, buttonClassName, }: ResendCodeProps): import("react/jsx-runtime").JSX.Element;
+export declare function ResendCode({ cooldownSeconds, isResending, canResend, onResend, prompt, label, resendingLabel, availableAnnouncement, className, buttonClassName, }: ResendCodeProps): import("react/jsx-runtime").JSX.Element;
 export default ResendCode;

package/components/ResendCode/ResendCode.js

@@ -1 +1 @@
-"use client";import{jsxs as u,jsx as b}from"react/jsx-runtime";import{cn as n}from"../../utils/cn.js";function f({cooldownSeconds:e,isResending:t,canResend:d,onResend:s,prompt:i="Didn't get a code?",label:l="Resend code",resendingLabel:o="Sending…",className:a,buttonClassName:r}){const c=e>0?`Resend in ${e}s`:t?o:l;return u("p",{className:n("text-sm",a),children:[i," ",b("button",{type:"button",onClick:s,disabled:!d,className:n("underline disabled:no-underline disabled:opacity-50 disabled:cursor-not-allowed",r),children:c})]})}export{f as ResendCode,f as default};
+"use client";import{jsxs as m,jsx as t}from"react/jsx-runtime";import{cn as a}from"../../utils/cn.js";function x({cooldownSeconds:e,isResending:n,canResend:s,onResend:d,prompt:i="Didn't get a code?",label:l="Resend code",resendingLabel:r="Sending…",availableAnnouncement:o="You can request a new code now.",className:c,buttonClassName:u}){const b=e>0?`Resend in ${e}s`:n?r:l;return m("p",{className:a("text-sm",c),children:[i," ",t("button",{type:"button",onClick:d,disabled:!s,className:a("underline disabled:no-underline disabled:opacity-50 disabled:cursor-not-allowed",u),children:b}),t("span",{"aria-live":"polite",className:"sr-only",children:e===0&&!n?o:""})]})}export{x as ResendCode,x as default};

package/components/ResendCode/ResendCode.types.d.ts

@@ -13,6 +13,11 @@ export type ResendCodeProps = {
     label?: string;
     /** Label shown while a resend is in flight. Defaults to "Sending…". */
     resendingLabel?: string;
+    /**
+     * Screen-reader announcement made (via a polite live region) when the cooldown ends and resend
+     * becomes available. Defaults to "You can request a new code now.".
+     */
+    availableAnnouncement?: string;
     /** className for the wrapping paragraph. */
     className?: string;
     /** className for the action button. */

package/docs/migrations/2026/01/2026-01-14-external-link-detection.md

@@ -1,6 +1,7 @@
 # External Link Detection Migration
 
 **Date:** 2026-01-14
+**Package:** `@clicktap/ui`
 **Affects:** `@clicktap/ui`, `apps/frontend`
 **Breaking:** No (additive, but requires provider setup for SSR)
 **Classification:** IMPROVEMENT

package/docs/migrations/2026/01/2026-01-14-use-route-hook.md

@@ -1,6 +1,7 @@
 # useRoute Hook Migration
 
 **Date:** 2026-01-14
+**Package:** `@clicktap/ui`
 **Affects:** `@clicktap/ui`, `apps/frontend`
 **Breaking:** No (additive, but recommended migration)
 **Classification:** IMPROVEMENT

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

@@ -1,6 +1,7 @@
 # Input disableSkeleton Prop
 
 **Date:** 2026-01-15
+**Package:** `@clicktap/ui`
 **Affects:** `@clicktap/ui`, `apps/frontend`
 **Breaking:** No
 **Classification:** IMPROVEMENT

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

@@ -1,6 +1,7 @@
 # Select popoverPortalContainer Restored
 
 **Date:** 2026-02-17
+**Package:** `@clicktap/ui`
 **Affects:** `@clicktap/ui` Select component, any consumer using Select inside Dialog or Modal
 **Classification:** BUGFIX
 **Breaking:** No

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

@@ -1,6 +1,7 @@
 # Environment Utilities from @clicktap/ui
 
 **Date:** 2026-02-16
+**Package:** `@clicktap/ui`
 **Affects:** All files importing `isDevelopment` / `isProduction` from local `utils/env`
 **Classification:** IMPROVEMENT
 **Breaking:** No
@@ -55,6 +56,7 @@ import { isDevelopment } from '../../../../../utils/env';
 ```
 
 **After:**
+**Formerly named:** `ui-2026-02-16-env-utils-from-clicktap-ui.md` — renamed 2026-08-07 (CTAP-1143) for global filename uniqueness; an identically-named guide exists in another tree and mirrored folders overwrote each other. **If you carry a `-applied` sibling under the old name, rename it to match — do NOT re-apply.**
 ```ts
 import { isDevelopment } from '@clicktap/ui/utils/env';
 ```

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

@@ -1,6 +1,7 @@
 # Image: dimmed, hidden, and onReady Props
 
 **Date:** 2026-03-24
+**Package:** `@clicktap/ui`
 **Affects:** `@clicktap/ui` — `Image` component
 **Classification:** IMPROVEMENT
 **Breaking:** No

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

@@ -1,6 +1,7 @@
 # ModalOverlay: Fix Dismiss on Backdrop Click
 
 **Date:** 2026-03-24
+**Package:** `@clicktap/ui`
 **Affects:** `@clicktap/ui` — `ModalOverlay` component
 **Classification:** BUGFIX
 **Breaking:** No

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

@@ -1,6 +1,7 @@
 # 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`)*
+**Package:** `@clicktap/ui`
 **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.

package/docs/migrations/2026/04/{2026-04-24-image-placeholder-frontend-fallback.md → ui-2026-04-24-image-placeholder-frontend-fallback.md}

@@ -1,13 +1,15 @@
 # `PLACEHOLDER_IMAGE` Export from `@clicktap/ui/utils/placeholder`
 
 **Date:** 2026-04-24
+**Package:** `@clicktap/ui`
 **Affects:** `@clicktap/ui` consumers that render product/category images
 **Classification:** IMPROVEMENT
 **Breaking:** No
+**Formerly named:** `ui-2026-04-24-image-placeholder-frontend-fallback.md` — renamed 2026-08-07 (CTAP-1143) for global filename uniqueness; an identically-named guide exists in another tree and mirrored folders overwrote each other. **If you carry a `-applied` sibling under the old name, rename it to match — do NOT re-apply.**
 
 ## Dependencies
 
-- See [frontend counterpart](../../../../../../apps/frontend/docs/migrations/2026/04/2026-04-24-image-placeholder-frontend-fallback.md) ↔ for the consuming-app changes.
+- See [frontend counterpart](../../../../../../apps/frontend/docs/migrations/2026/04/ui-2026-04-24-image-placeholder-frontend-fallback.md) ↔ for the consuming-app changes.
 
 ## Summary
 
@@ -60,7 +62,7 @@ Works equally well with raw `<img>`:
 <img src={product.image ?? PLACEHOLDER_IMAGE} alt="" />
 ```
 
-For the PDP/PLP migration, see the [frontend counterpart guide](../../../../../../apps/frontend/docs/migrations/2026/04/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.
+For the PDP/PLP migration, see the [frontend counterpart guide](../../../../../../apps/frontend/docs/migrations/2026/04/ui-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
 
@@ -74,7 +76,7 @@ For the PDP/PLP migration, see the [frontend counterpart guide](../../../../../.
 
 - [ ] `@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](../../../../../../apps/frontend/docs/migrations/2026/04/2026-04-24-image-placeholder-frontend-fallback.md) for the consuming-app changes.
+- [ ] Apply the [frontend counterpart guide](../../../../../../apps/frontend/docs/migrations/2026/04/ui-2026-04-24-image-placeholder-frontend-fallback.md) for the consuming-app changes.
 
 ## Why a data URL and not a bundled file?
 

package/docs/migrations/2026/04/{2026-04-30-prune-invalid-pdp-selections.md → ui-2026-04-30-prune-invalid-pdp-selections.md}

@@ -1,14 +1,16 @@
 # PDP Option Selection — Conservative Prune Helper (`pruneInvalidSelections`)
 
 **Date:** 2026-04-30
+**Package:** `@clicktap/ui`
 **Affects:** `@clicktap/ui/utils/variantOptions` — adds `pruneInvalidSelections`
 **Classification:** IMPROVEMENT
 **Breaking:** No (additive)
+**Formerly named:** `ui-2026-04-30-prune-invalid-pdp-selections.md` — renamed 2026-08-07 (CTAP-1143) for global filename uniqueness; an identically-named guide exists in another tree and mirrored folders overwrote each other. **If you carry a `-applied` sibling under the old name, rename it to match — do NOT re-apply.**
 
 ## 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`](../../../../../../apps/frontend/docs/migrations/2026/04/2026-04-30-prune-invalid-pdp-selections.md) ↔.
+- Builds on [`2026-04-30-top-down-pdp-option-dependency.md`](./ui-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/.../ui-2026-04-30-prune-invalid-pdp-selections.md`](../../../../../../apps/frontend/docs/migrations/2026/04/ui-2026-04-30-prune-invalid-pdp-selections.md) ↔.
 
 ## Summary
 
@@ -162,5 +164,5 @@ Replace the manual delete loop with a single `pruneInvalidSelections` call (see
 
 ## References
 
-- Frontend counterpart migration: [`apps/frontend/.../2026-04-30-prune-invalid-pdp-selections.md`](../../../../../../apps/frontend/docs/migrations/2026/04/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)
+- Frontend counterpart migration: [`apps/frontend/.../ui-2026-04-30-prune-invalid-pdp-selections.md`](../../../../../../apps/frontend/docs/migrations/2026/04/ui-2026-04-30-prune-invalid-pdp-selections.md) ↔
+- Previous top-down migration this builds on: [`2026-04-30-top-down-pdp-option-dependency.md`](./ui-2026-04-30-top-down-pdp-option-dependency.md)

package/docs/migrations/2026/04/{2026-04-30-top-down-pdp-option-dependency.md → ui-2026-04-30-top-down-pdp-option-dependency.md}

@@ -1,13 +1,14 @@
 # Top-Down PDP Option Dependency — `@clicktap/ui/utils/variantOptions`
 
 **Date:** 2026-04-30
+**Package:** `@clicktap/ui`
 **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`](../../../../../../apps/frontend/docs/migrations/2026/04/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.
+- 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/.../ui-2026-04-30-top-down-pdp-option-dependency.md`](../../../../../../apps/frontend/docs/migrations/2026/04/ui-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
 
@@ -32,6 +33,7 @@ This module ships the filter logic only. The selection-state mechanics (clearing
 ### New module
 
 **Source:** `libs/ui/src/utils/variantOptions/`
+**Formerly named:** `ui-2026-04-30-top-down-pdp-option-dependency.md` — renamed 2026-08-07 (CTAP-1143) for global filename uniqueness; an identically-named guide exists in another tree and mirrored folders overwrote each other. **If you carry a `-applied` sibling under the old name, rename it to match — do NOT re-apply.**
 
 ```
 libs/ui/src/utils/variantOptions/
@@ -282,5 +284,5 @@ Skip this and you'll occasionally see the matched variant query against an impos
 
 ## References
 
-- Frontend counterpart migration: [`apps/frontend/.../2026-04-30-top-down-pdp-option-dependency.md`](../../../../../../apps/frontend/docs/migrations/2026/04/2026-04-30-top-down-pdp-option-dependency.md) ↔
+- Frontend counterpart migration: [`apps/frontend/.../ui-2026-04-30-top-down-pdp-option-dependency.md`](../../../../../../apps/frontend/docs/migrations/2026/04/ui-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

@@ -1,6 +1,7 @@
 # `buildPdpUrl` Utility — `@clicktap/ui/utils/buildPdpUrl`
 
 **Date:** 2026-05-01
+**Package:** `@clicktap/ui`
 **Affects:** `@clicktap/ui/utils/buildPdpUrl` — new export
 **Classification:** IMPROVEMENT
 **Breaking:** No (additive)

package/docs/migrations/2026/05/2026-05-03-auth-aware-graphql-client.md

@@ -1,6 +1,7 @@
 # Auth-aware GraphQL client — `@clicktap/ui/utils/createAuthAwareGraphqlClient`
 
 **Date:** 2026-05-03
+**Package:** `@clicktap/ui`
 **Affects:** `@clicktap/ui/utils/createAuthAwareGraphqlClient` — new export
 **Classification:** IMPROVEMENT
 **Breaking:** No (additive)

package/docs/migrations/2026/05/2026-05-20-framer-motion-11-idioms.md

@@ -1,6 +1,7 @@
 # framer-motion 11.x idioms — opacity-only for modal entry/exit, primitives over transform strings, matched keyframe shapes
 
 **Date:** 2026-05-20
+**Package:** `@clicktap/ui`
 **Affects:** `@clicktap/ui/components/Dialog`, `@clicktap/ui/components/ModalOverlay`, `@clicktap/ui/components/Badge`, `@clicktap/ui/components/Loader/CircularEasing`, `@clicktap/ui/components/Loader/Pulse`, and any consumer-side `motion.*` usage on framer-motion 11.x.
 **Classification:** COMPATIBILITY
 **Breaking:** Yes (for consumers passing custom `animationVariants` containing multi-function `transform` strings, transform/scale primitives in modal variants, calc-with-mixed-units in animate targets, or who copy-paste the affected motion patterns into their own components — see Consumer Impact)

package/docs/migrations/2026/05/2026-05-21-button-loading-content.md

@@ -1,6 +1,7 @@
 # `ButtonLoadingContent` helper — standardized right-side spinner for all submit buttons
 
 **Date:** 2026-05-21
+**Package:** `@clicktap/ui`
 **Affects:** `@clicktap/ui/components/Button` (new `ButtonLoadingContent` export) and every submit-style button in the frontend app.
 **Classification:** IMPROVEMENT
 **Breaking:** No

package/docs/migrations/2026/05/2026-05-21-password-check-hide-on-empty.md

@@ -1,6 +1,7 @@
 # `PasswordCheck` `requirements` variant hides until the visitor types
 
 **Date:** 2026-05-21
+**Package:** `@clicktap/ui`
 **Affects:** `libs/ui/src/components/PasswordCheck/PasswordCheck.tsx`
 **Classification:** IMPROVEMENT
 **Breaking:** No

package/docs/migrations/2026/05/2026-05-29-password-check-requirements-variant.md

@@ -1,6 +1,7 @@
 # `PasswordCheck` — the `requirements` variant (adoption guide for forks)
 
 **Date:** 2026-05-29 (retroactive — the variant already ships in `@clicktap/ui`)
+**Package:** `@clicktap/ui`
 **Affects:** `libs/ui/src/components/PasswordCheck/PasswordCheck.tsx`, `libs/ui/src/components/PasswordCheck/PasswordCheck.types.ts`
 **Classification:** IMPROVEMENT
 **Breaking:** No (the variant is additive; `default` is unchanged)

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

@@ -1,6 +1,7 @@
 # Select standardization — one `<Select searchable>`, `DropdownSelect` removed
 
 **Date:** 2026-06-17
+**Package:** `@clicktap/ui`
 **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**.

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

@@ -1,6 +1,7 @@
 # `Select` (searchable): fix "setValue is not a function" crash on browser autofill
 
 **Date:** 2026-06-18
+**Package:** `@clicktap/ui`
 **Affects:** `@clicktap/ui` `Select` — the **searchable** (ComboBox) variant (`ComboBoxSelect`)
 **Classification:** BUGFIX
 **Breaking:** No

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

@@ -1,6 +1,7 @@
 # NextUI → HeroUI for `Accordion`, `Badge`, `Pagination`, `Tooltip`
 
 **Date:** 2026-08-02
+**Package:** `@clicktap/ui`
 **Affects:** `@clicktap/ui` peer dependencies — `Accordion`, `Badge`, `Pagination`, `Tooltip`
 **Classification:** DEPENDENCY
 **Breaking:** Yes (peer dependencies change; requires Tailwind 4 — see below)

package/docs/migrations/2026/08/2026-08-04-password-reveal-press-and-hold.md

@@ -1,6 +1,7 @@
 # Password reveal is press-and-hold, not a toggle
 
 **Date:** 2026-08-04
+**Package:** `@clicktap/ui`
 **Affects:** `@clicktap/ui` — `Input` with `type="password"`.
 **Classification:** IMPROVEMENT (security / UX)
 **Breaking:** Behavioural only — the reveal changed from a click-toggle to press-and-hold. No API/prop

package/docs/migrations/2026/08/2026-08-04-resend-code-control.md

@@ -1,6 +1,7 @@
 # `ResendCode` control + `useCooldown` hook
 
 **Date:** 2026-08-04
+**Package:** `@clicktap/ui`
 **Affects:** `@clicktap/ui` — new `components/ResendCode` and `hooks/useCooldown` exports.
 **Classification:** IMPROVEMENT (new capability)
 **Breaking:** No — additive exports.

package/docs/migrations/2026/08/2026-08-06-clicktap-ui-image-next-subpath.md

@@ -1,6 +1,7 @@
 # `Image` is framework-free; Next's optimizer moves to `@clicktap/ui/next`
 
 **Date:** 2026-08-06
+**Package:** `@clicktap/ui`
 **Ticket:** CTAP-1125 (epic CTAP-1122)
 **Affects:** Any consumer importing `@clicktap/ui/components/Image` or `@clicktap/ui/components/UploadImage`. Consumer counterpart: [`apps/frontend/docs/migrations/2026/08/2026-08-06-image-from-clicktap-ui-next.md`](../../../../../../apps/frontend/docs/migrations/2026/08/2026-08-06-image-from-clicktap-ui-next.md)
 **Requires:** `@clicktap/ui` at the release bundling CTAP-1125. Next consumers additionally need `next >= 14` installed — it is now an **optional peer**, so your package manager will not add it for you.

package/docs/migrations/2026/08/2026-08-06-clicktap-ui-loaders-drop-framer-motion.md

@@ -1,6 +1,7 @@
 # `Button` and the loaders no longer need `framer-motion` (CTAP-1156)
 
 **Date:** 2026-08-06
+**Package:** `@clicktap/ui`
 **Affects:** `@clicktap/ui` — `Button`, `ButtonLoadingContent`, `Loader/CircularEasing`, `Loader/Pulse`
 **Breaking:** No API change. **One requirement to be aware of** — see below.
 **Requires:** `@import '@clicktap/ui/theme.css'` in your CSS entry

package/docs/migrations/2026/08/2026-08-06-clicktap-ui-semantic-tokens.md

@@ -1,6 +1,7 @@
 # `@clicktap/ui` semantic design tokens — add one CSS import (CTAP-1123)
 
 **Date:** 2026-08-06
+**Package:** `@clicktap/ui`
 **Affects:** `@clicktap/ui`, every app that renders its components
 **Breaking:** **Yes — one required import.** Components render *unstyled* without it.
 **Requires:** Tailwind v4 (`@import 'tailwindcss'` in your CSS entry). See

package/docs/migrations/README.md

@@ -11,14 +11,14 @@ For migrations affecting the frontend app, see [frontend migrations](../../../..
 | 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-16 | [Environment utilities — `@clicktap/ui/utils/env`](./2026/02/ui-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-04-24 | [`PLACEHOLDER_IMAGE` Export from `@clicktap/ui/utils/placeholder`](./2026/04/ui-2026-04-24-image-placeholder-frontend-fallback.md) ↔ | No | *None* |
+| 2026-04-30 | [Top-Down PDP Option Dependency — `@clicktap/ui/utils/variantOptions`](./2026/04/ui-2026-04-30-top-down-pdp-option-dependency.md) ↔ | No | *None* |
+| 2026-04-30 | [PDP Option Selection — Conservative Prune Helper (`pruneInvalidSelections`)](./2026/04/ui-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* |

package/docs/migrations/index.json

@@ -0,0 +1,272 @@
+[
+  {
+    "path": "2026/08/2026-08-07-ui-peer-contract-form-graphql-optional-peers.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-07",
+    "title": "`@clicktap/ui` peer contract: three new optional peers; `clsx` corrected (CTAP-1158)",
+    "classification": "COMPATIBILITY",
+    "breaking": "No for minimal consumers; action needed only if you use the form or GraphQL-aware components",
+    "affects": ""
+  },
+  {
+    "path": "2026/08/2026-08-06-clicktap-ui-semantic-tokens.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-06",
+    "title": "`@clicktap/ui` semantic design tokens — add one CSS import (CTAP-1123)",
+    "classification": "COMPATIBILITY",
+    "breaking": "**Yes — one required import.** Components render *unstyled* without it.",
+    "affects": "`@clicktap/ui`, every app that renders its components"
+  },
+  {
+    "path": "2026/08/2026-08-06-clicktap-ui-loaders-drop-framer-motion.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-06",
+    "title": "`Button` and the loaders no longer need `framer-motion` (CTAP-1156)",
+    "classification": "IMPROVEMENT",
+    "breaking": "No API change. **One requirement to be aware of** — see below.",
+    "affects": "`@clicktap/ui` — `Button`, `ButtonLoadingContent`, `Loader/CircularEasing`, `Loader/Pulse`"
+  },
+  {
+    "path": "2026/08/2026-08-06-clicktap-ui-image-next-subpath.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-06",
+    "title": "`Image` is framework-free; Next's optimizer moves to `@clicktap/ui/next`",
+    "classification": "IMPROVEMENT",
+    "breaking": "Yes, for Next consumers — one import path per call site. See \"If you are a Next app\" below.",
+    "affects": "Any consumer importing `@clicktap/ui/components/Image` or `@clicktap/ui/components/UploadImage`. Consumer counterpart: [`apps/frontend/docs/migrations/2026/08/2026-08-06-image-from-clicktap-ui-next.md`](../../../../../../apps/frontend/docs/migrations/2026/08/2026-08-06-image-from-clicktap-ui-next.md)"
+  },
+  {
+    "path": "2026/08/2026-08-04-resend-code-control.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-04",
+    "title": "`ResendCode` control + `useCooldown` hook",
+    "classification": "IMPROVEMENT (new capability)",
+    "breaking": "No — additive exports.",
+    "affects": "`@clicktap/ui` — new `components/ResendCode` and `hooks/useCooldown` exports."
+  },
+  {
+    "path": "2026/08/2026-08-04-password-reveal-press-and-hold.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-04",
+    "title": "Password reveal is press-and-hold, not a toggle",
+    "classification": "IMPROVEMENT (security / UX)",
+    "breaking": "Behavioural only — the reveal changed from a click-toggle to press-and-hold. No API/prop",
+    "affects": "`@clicktap/ui` — `Input` with `type=\"password\"`."
+  },
+  {
+    "path": "2026/08/2026-08-02-nextui-to-heroui.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-02",
+    "title": "NextUI → HeroUI for `Accordion`, `Badge`, `Pagination`, `Tooltip`",
+    "classification": "DEPENDENCY",
+    "breaking": "Yes (peer dependencies change; requires Tailwind 4 — see below)",
+    "affects": "`@clicktap/ui` peer dependencies — `Accordion`, `Badge`, `Pagination`, `Tooltip`"
+  },
+  {
+    "path": "2026/07/2026-07-31-ui-exports-bundler-resolution.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-07-31",
+    "title": "`@clicktap/ui` resolves its deep subpaths under `moduleResolution: bundler` (CTAP-1060)",
+    "classification": "BUGFIX (packaging) — unblocks `moduleResolution: bundler`, and with it TypeScript 7",
+    "breaking": "No — additive to the `exports` map. Existing `moduleResolution: node` / `node10`",
+    "affects": ""
+  },
+  {
+    "path": "2026/06/2026-06-18-select-hiddenselect-setvalue-crash.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-06-18",
+    "title": "`Select` (searchable): fix \"setValue is not a function\" crash on browser autofill",
+    "classification": "BUGFIX",
+    "breaking": "No",
+    "affects": "`@clicktap/ui` `Select` — the **searchable** (ComboBox) variant (`ComboBoxSelect`)"
+  },
+  {
+    "path": "2026/06/2026-06-17-select-standardization.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-06-17",
+    "title": "Select standardization — one `<Select searchable>`, `DropdownSelect` removed",
+    "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**.",
+    "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)."
+  },
+  {
+    "path": "2026/05/2026-05-29-password-check-requirements-variant.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-05-29",
+    "title": "`PasswordCheck` — the `requirements` variant (adoption guide for forks)",
+    "classification": "IMPROVEMENT",
+    "breaking": "No (the variant is additive; `default` is unchanged)",
+    "affects": "`libs/ui/src/components/PasswordCheck/PasswordCheck.tsx`, `libs/ui/src/components/PasswordCheck/PasswordCheck.types.ts`"
+  },
+  {
+    "path": "2026/05/2026-05-21-password-check-hide-on-empty.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-05-21",
+    "title": "`PasswordCheck` `requirements` variant hides until the visitor types",
+    "classification": "IMPROVEMENT",
+    "breaking": "No",
+    "affects": "`libs/ui/src/components/PasswordCheck/PasswordCheck.tsx`"
+  },
+  {
+    "path": "2026/05/2026-05-21-button-loading-content.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-05-21",
+    "title": "`ButtonLoadingContent` helper — standardized right-side spinner for all submit buttons",
+    "classification": "IMPROVEMENT",
+    "breaking": "No",
+    "affects": "`@clicktap/ui/components/Button` (new `ButtonLoadingContent` export) and every submit-style button in the frontend app."
+  },
+  {
+    "path": "2026/05/2026-05-20-framer-motion-11-idioms.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-05-20",
+    "title": "framer-motion 11.x idioms — opacity-only for modal entry/exit, primitives over transform strings, matched keyframe shapes",
+    "classification": "COMPATIBILITY",
+    "breaking": "Yes (for consumers passing custom `animationVariants` containing multi-function `transform` strings, transform/scale primitives in modal variants, calc-with-mixed-units in animate targets, or who copy-paste the affected motion patterns into their own components — see Consumer Impact)",
+    "affects": "`@clicktap/ui/components/Dialog`, `@clicktap/ui/components/ModalOverlay`, `@clicktap/ui/components/Badge`, `@clicktap/ui/components/Loader/CircularEasing`, `@clicktap/ui/components/Loader/Pulse`, and any consumer-side `motion.*` usage on framer-motion 11.x."
+  },
+  {
+    "path": "2026/05/2026-05-03-auth-aware-graphql-client.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-05-03",
+    "title": "Auth-aware GraphQL client — `@clicktap/ui/utils/createAuthAwareGraphqlClient`",
+    "classification": "IMPROVEMENT",
+    "breaking": "No (additive)",
+    "affects": "`@clicktap/ui/utils/createAuthAwareGraphqlClient` — new export"
+  },
+  {
+    "path": "2026/05/2026-05-01-build-pdp-url-util.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-05-01",
+    "title": "`buildPdpUrl` Utility — `@clicktap/ui/utils/buildPdpUrl`",
+    "classification": "IMPROVEMENT",
+    "breaking": "No (additive)",
+    "affects": "`@clicktap/ui/utils/buildPdpUrl` — new export"
+  },
+  {
+    "path": "2026/04/ui-2026-04-30-top-down-pdp-option-dependency.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-04-30",
+    "title": "Top-Down PDP Option Dependency — `@clicktap/ui/utils/variantOptions`",
+    "classification": "IMPROVEMENT",
+    "breaking": "No (additive)",
+    "affects": "New utility module `@clicktap/ui/utils/variantOptions` (ships generic `filterAvailableOptions`, `findVariant`, `getDownstreamAxisCodes`)"
+  },
+  {
+    "path": "2026/04/ui-2026-04-30-prune-invalid-pdp-selections.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-04-30",
+    "title": "PDP Option Selection — Conservative Prune Helper (`pruneInvalidSelections`)",
+    "classification": "IMPROVEMENT",
+    "breaking": "No (additive)",
+    "affects": "`@clicktap/ui/utils/variantOptions` — adds `pruneInvalidSelections`"
+  },
+  {
+    "path": "2026/04/ui-2026-04-24-image-placeholder-frontend-fallback.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-04-24",
+    "title": "`PLACEHOLDER_IMAGE` Export from `@clicktap/ui/utils/placeholder`",
+    "classification": "IMPROVEMENT",
+    "breaking": "No",
+    "affects": "`@clicktap/ui` consumers that render product/category images"
+  },
+  {
+    "path": "2026/04/2026-04-17-select-address-input-onchange-key-or-item.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-04-17",
+    "title": "Select / AddressInput: `onSelectionChange` / `onChange` callback widened to `Key | T`",
+    "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.",
+    "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."
+  },
+  {
+    "path": "2026/03/2026-03-24-modal-overlay-backdrop-dismiss.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-03-24",
+    "title": "ModalOverlay: Fix Dismiss on Backdrop Click",
+    "classification": "BUGFIX",
+    "breaking": "No",
+    "affects": "`@clicktap/ui` — `ModalOverlay` component"
+  },
+  {
+    "path": "2026/03/2026-03-24-image-dimmed-hidden-onready.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-03-24",
+    "title": "Image: dimmed, hidden, and onReady Props",
+    "classification": "IMPROVEMENT",
+    "breaking": "No",
+    "affects": "`@clicktap/ui` — `Image` component"
+  },
+  {
+    "path": "2026/02/2026-02-17-select-popover-portal-container-restored.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-02-17",
+    "title": "Select popoverPortalContainer Restored",
+    "classification": "BUGFIX",
+    "breaking": "No",
+    "affects": "`@clicktap/ui` Select component, any consumer using Select inside Dialog or Modal"
+  },
+  {
+    "path": "2026/02/ui-2026-02-16-env-utils-from-clicktap-ui.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-02-16",
+    "title": "Environment Utilities from @clicktap/ui",
+    "classification": "IMPROVEMENT",
+    "breaking": "No",
+    "affects": "All files importing `isDevelopment` / `isProduction` from local `utils/env`"
+  },
+  {
+    "path": "2026/01/2026-01-15-input-disable-skeleton.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-01-15",
+    "title": "Input disableSkeleton Prop",
+    "classification": "IMPROVEMENT",
+    "breaking": "No",
+    "affects": "`@clicktap/ui`, `apps/frontend`"
+  },
+  {
+    "path": "2026/01/2026-01-14-use-route-hook.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-01-14",
+    "title": "useRoute Hook Migration",
+    "classification": "IMPROVEMENT",
+    "breaking": "No (additive, but recommended migration)",
+    "affects": "`@clicktap/ui`, `apps/frontend`"
+  },
+  {
+    "path": "2026/01/2026-01-14-external-link-detection.md",
+    "module": "libs/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-01-14",
+    "title": "External Link Detection Migration",
+    "classification": "IMPROVEMENT",
+    "breaking": "No (additive, but requires provider setup for SSR)",
+    "affects": "`@clicktap/ui`, `apps/frontend`"
+  }
+]

package/hooks/useCooldown.d.ts

@@ -16,9 +16,16 @@ export interface UseCooldownResult {
 /**
  * A headless one-second countdown. `start(n)` sets the remaining seconds and it ticks down to zero.
  *
- * StrictMode-safe: the tick lives in an effect (not a state updater), and the countdown is mirrored
- * into a ref so the effect reads the latest value without re-subscribing each second and so callers
- * get a stale-free view via `isActiveNow()`.
+ * Deadline-based (CTAP-1167): `start(n)` stores an absolute deadline and every tick recomputes the
+ * remaining time from the clock instead of decrementing. Browsers and WebViews throttle timers in
+ * backgrounded tabs (Capacitor apps aggressively), so a decrementing counter falls behind real
+ * time — a 60s cooldown resumed after backgrounding would still show tens of seconds long after
+ * the real deadline passed. Recomputing makes the first tick after a throttled gap snap to the
+ * true remaining time, and `isActiveNow()` compares against the deadline itself so re-entry
+ * guards are immune to a stale count.
+ *
+ * StrictMode-safe: the tick lives in an effect (not a state updater), and the deadline is a ref so
+ * the timer chain reads the latest value without re-subscribing each second.
  */
 export declare function useCooldown(): UseCooldownResult;
 export default useCooldown;

package/hooks/useCooldown.js

@@ -1 +1 @@
-"use client";import{useState as i,useRef as f,useCallback as r,useEffect as l}from"react";function d(){const[s,n]=i(0),t=f(0),o=r(c=>{const e=Math.max(0,Math.ceil(c));t.current=e,n(e)},[]),u=r(()=>{t.current=0,n(0)},[]),a=r(()=>t.current>0,[]);return l(()=>{if(s<=0)return;const c=setTimeout(()=>{const e=Math.max(0,t.current-1);t.current=e,n(e)},1e3);return()=>clearTimeout(c)},[s]),{seconds:s,isActive:s>0,start:o,reset:u,isActiveNow:a}}export{d as default,d as useCooldown};
+"use client";import{useState as f,useRef as d,useCallback as r,useEffect as w}from"react";function M(){const[u,o]=f(0),e=d(0),i=r(n=>{const t=Math.max(0,Math.ceil(n));e.current=t>0?Date.now()+t*1e3:0,o(t)},[]),l=r(()=>{e.current=0,o(0)},[]),m=r(()=>e.current>Date.now(),[]),c=u>0;return w(()=>{if(!c)return;let n;const t=()=>{const s=e.current-Date.now();return s>0?s%1e3||1e3:0},a=()=>{const s=Math.max(0,Math.ceil((e.current-Date.now())/1e3));o(s),s>0&&(n=setTimeout(a,t()))};return n=setTimeout(a,t()),()=>clearTimeout(n)},[c]),{seconds:u,isActive:c,start:i,reset:l,isActiveNow:m}}export{M as default,M as useCooldown};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clicktap/ui",
-  "version": "0.42.3",
+  "version": "0.43.0",
   "private": false,
   "author": "Clicktap",
   "description": "A library of React UI components and low-level hooks.",