@clicktap/ui 0.40.11 → 0.41.0

package/components/ResendCode/ResendCode.d.ts

@@ -0,0 +1,9 @@
+import { ResendCodeProps } from './ResendCode.types';
+/**
+ * "Didn't get a code? Resend" control for OTP flows. Presentation only — the caller owns the resend
+ * 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`.
+ */
+export declare function ResendCode({ cooldownSeconds, isResending, canResend, onResend, prompt, label, resendingLabel, className, buttonClassName, }: ResendCodeProps): import("react/jsx-runtime").JSX.Element;
+export default ResendCode;

package/components/ResendCode/ResendCode.js

@@ -0,0 +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};

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

@@ -0,0 +1,20 @@
+export type ResendCodeProps = {
+    /** Seconds remaining on the cooldown; when > 0 the control reads "Resend in Ns". */
+    cooldownSeconds: number;
+    /** True while a resend request is in flight (shows `resendingLabel`). */
+    isResending: boolean;
+    /** Whether the control is actionable (no active cooldown and not in flight). */
+    canResend: boolean;
+    /** Fired when the user activates the control. */
+    onResend: () => void;
+    /** Leading prompt text. Defaults to "Didn't get a code?". */
+    prompt?: string;
+    /** Idle action label. Defaults to "Resend code". */
+    label?: string;
+    /** Label shown while a resend is in flight. Defaults to "Sending…". */
+    resendingLabel?: string;
+    /** className for the wrapping paragraph. */
+    className?: string;
+    /** className for the action button. */
+    buttonClassName?: string;
+};

package/components/ResendCode/index.d.ts

@@ -0,0 +1,2 @@
+export { ResendCode } from './ResendCode';
+export type { ResendCodeProps } from './ResendCode.types';

package/components/ResendCode/index.js

@@ -0,0 +1 @@
+import{ResendCode as p}from"./ResendCode.js";import"react/jsx-runtime";import"../../utils/cn.js";export{p as ResendCode};

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

@@ -76,15 +76,19 @@ The cleanest fix is a type guard at the callback boundary:
 > ```ts
 > import type { Key } from 'react-aria-components';
 >
-> export function narrowKey<T extends { id: Key }>(
+> 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;
+>   return value.id ?? null;
 > }
 > ```
 >
+> The constraint is `{ id?: Key }` (optional), not `{ id: Key }`: real call sites often can't statically prove the item carries a **required** `id` — the inline versions cast `(value as { id?: string }).id` — so a required-`id` constraint fails to typecheck exactly where the helper is meant to be used. Returning `value.id ?? null` keeps the return type `Key | null`.
+>
+> **Behaviour note:** this helper returns `null` where an inline `value.id` could return `undefined`. Harmless for callers guarding with `?? ''` or `== null`, but it is a real behaviour change — name it if any call site distinguishes the two.
+>
 > 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

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

@@ -0,0 +1,68 @@
+# `ResendCode` control + `useCooldown` hook
+
+**Date:** 2026-08-04
+**Affects:** `@clicktap/ui` — new `components/ResendCode` and `hooks/useCooldown` exports.
+**Classification:** IMPROVEMENT (new capability)
+**Breaking:** No — additive exports.
+**Consumers:** the OTP resend timer — [wire it everywhere](../../../../../../apps/frontend/docs/migrations/2026/08/2026-08-04-otp-resend-timer.md) ·
+GraphQL contract — [resend mutations](../../../../../../libs/mezzio-modules/user/docs/migrations/2026/08/2026-08-04-otp-resend-mutations.md)
+
+## Summary
+
+Two additive, headless-friendly exports for building "Resend code" controls (CTAP-1114), so every OTP
+flow renders the same states from one place instead of hand-rolling the markup per form.
+
+### `@clicktap/ui/hooks/useCooldown`
+
+A one-second countdown. `start(n)` sets the remaining seconds and it ticks to zero.
+
+```ts
+const { seconds, isActive, start, reset, isActiveNow } = useCooldown();
+```
+
+| Field | |
+|---|---|
+| `seconds` | remaining seconds (0 when inactive) — drives rendering |
+| `isActive` | `seconds > 0` |
+| `start(seconds)` | begin/restart (rounds up, floors at 0) |
+| `reset()` | clear immediately |
+| `isActiveNow()` | **stale-free** active check for use inside event handlers / re-entry guards |
+
+**StrictMode-safe:** the tick lives in an effect (never in a state updater), and the count is mirrored
+into a ref so the effect reads the latest value and `isActiveNow()` never goes stale. Do **not** put a
+side effect inside a `setState` updater to guard re-entry — StrictMode double-invokes updaters and it
+fires twice.
+
+### `@clicktap/ui/components/ResendCode`
+
+Presentational only — the caller owns the request + cooldown state. Renders one of three labels
+(countdown / in-flight / idle) and disables the button unless `canResend`.
+
+```tsx
+<ResendCode
+  cooldownSeconds={seconds}
+  isResending={isResending}
+  canResend={canResend}
+  onResend={resend}
+  prompt="Didn't get a code?"   // default
+  label="Resend code"           // default idle label
+  resendingLabel="Sending…"     // default
+  className="…"                 // wrapper <p>
+  buttonClassName="…"           // action <button>
+/>
+```
+
+Renders `Didn't get a code? {Resend code | Resend in Ns | Sending…}`. Style per context via
+`className` / `buttonClassName` (tailwind-merge, so your `text-xs` overrides the default `text-sm`).
+
+## Action required (consumer)
+
+1. **Bump `@clicktap/ui`** to the release that ships this migration.
+2. Use `<ResendCode>` for OTP resend controls; drive it from `useCooldown` (or a domain hook that
+   composes it — see the frontend guide's `useResendCode`).
+
+## Notes
+
+- `ResendCode` is a plain `<button type="button">` — safe inside a `react-aria` `Form` (won't submit).
+- `useCooldown` is domain-agnostic; the OTP rate-limit contract (`otp_rate_limited`,
+  `retryAfterSeconds`) lives in the consuming app, not here.

package/docs/migrations/README.md

@@ -27,5 +27,6 @@ For migrations affecting the frontend app, see [frontend migrations](../../../..
 | 2026-05-29 | [`PasswordCheck` — the `requirements` variant (adoption guide for forks)](./2026/05/2026-05-29-password-check-requirements-variant.md) | No | PasswordCheck hide-on-empty |
 | 2026-06-17 | [Select standardization — one `<Select searchable>`, `DropdownSelect` removed](./2026/06/2026-06-17-select-standardization.md) ↔ | Yes | *None* |
 | 2026-06-18 | [Select (searchable): fix "setValue is not a function" crash on browser autofill](./2026/06/2026-06-18-select-hiddenselect-setvalue-crash.md) | No | Select standardization |
+| 2026-08-04 | [`ResendCode` control + `useCooldown` hook](./2026/08/2026-08-04-resend-code-control.md) ↔ | No | OTP resend timer (CTAP-1114) |
 
 ↔ = cross-app migration (has counterpart in frontend app)

package/hooks/useCooldown.d.ts

@@ -0,0 +1,24 @@
+export interface UseCooldownResult {
+    /** Seconds remaining; 0 when inactive. Drives rendering (e.g. "Resend in Ns"). */
+    seconds: number;
+    /** True while a cooldown is counting down. */
+    isActive: boolean;
+    /** Begin (or restart) the cooldown at `seconds` (rounded up, floored at 0). */
+    start: (seconds: number) => void;
+    /** Clear the cooldown immediately. */
+    reset: () => void;
+    /**
+     * Stale-free active check for use inside event handlers / re-entry guards, where the `seconds`
+     * state captured by a stable callback would be out of date.
+     */
+    isActiveNow: () => boolean;
+}
+/**
+ * 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()`.
+ */
+export declare function useCooldown(): UseCooldownResult;
+export default useCooldown;

package/hooks/useCooldown.js

@@ -0,0 +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};

package/package.json

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