@clicktap/ui 2.1.3 → 2.2.0

package/components/ModalOverlay/ModalOverlay.d.ts

@@ -19,5 +19,5 @@ import { ModalOverlayProps } from './ModalOverlay.types';
  * Exported for unit tests only.
  */
 export declare function useOverlayAnimationState(overlayState: OverlayTriggerState | null | undefined): [DriverAnimationState, Dispatch<SetStateAction<DriverAnimationState>>];
-export declare function ModalOverlay(props: ModalOverlayProps): import("react/jsx-runtime").JSX.Element;
+export declare function ModalOverlay(props: ModalOverlayProps): import("react/jsx-runtime").JSX.Element | null;
 export default ModalOverlay;

package/components/ModalOverlay/ModalOverlay.js

@@ -1 +1 @@
-"use client";import{jsx as a}from"react/jsx-runtime";import{forwardRef as N,useContext as M,useState as k,useEffect as A,useId as R,useCallback as O}from"react";import{ModalOverlay as E,OverlayTriggerStateContext as w}from"react-aria-components";import{motion as T,AnimatePresence as F}from"framer-motion";import{cn as j}from"../../utils/cn.js";const q="body > [inert]:not(#__next):not([data-overlay-container])";function z(e){return Object.keys(e).some(t=>t.startsWith("__react"))}function p(){document.querySelectorAll(q).forEach(e=>e.removeAttribute("inert"))}function L(e){return!!(e.closest("[data-overlay-container]")||e.closest("#__next"))}const W=N(({style:e,children:t,...i},n)=>{const r=typeof e=="function"?e(i):e;return a(E,{...i,ref:n,style:r,children:t})});let m=null;function $(){return typeof window>"u"?null:(m||(m=T.create(W)),m)}const h=$();function g({animate:e,animation:t,setAnimation:i,className:n,animationVariants:r,isDismissable:u=!0,children:v,...x}){const C=R();A(()=>{p();const o=new MutationObserver(l=>{for(const d of l)if(d.type==="attributes"&&d.attributeName==="inert"){const f=d.target;f.parentElement===document.body?p():z(f)||f.removeAttribute("inert")}});return o.observe(document.body,{attributes:!0,attributeFilter:["inert"],subtree:!0}),()=>o.disconnect()},[]);const{key:S,shouldCloseOnInteractOutside:c,onOpenChange:s,..._}=x,P=O(o=>c?c(o):L(o),[c]),y=M(w),I=O(o=>{!u||o.target!==o.currentTarget||(s?s(!1):y?.close())},[u,s,y]),b={isDismissable:u,shouldCloseOnInteractOutside:P,onOpenChange:s,onPointerDown:I,className:j("bg-black/30 backdrop-blur-sm","fixed top-0 left-0","z-[1000]","w-screen h-[var(--visual-viewport-height)]",n),..._};return h?a(h,{isExiting:t==="hidden",onAnimationComplete:o=>{i(l=>o==="hidden"&&l==="hidden"?"unmounted":l)},variants:r||{hidden:{opacity:0,transition:{delay:.08}},visible:{opacity:1}},initial:"hidden",animate:e,exit:"hidden",...b,children:v},S||C):a(E,{...b,children:v})}function B(e){const t=e?.isOpen??!1,[i,n]=k(t?"visible":"unmounted");return A(()=>{n(t?"visible":r=>r==="visible"?"hidden":r)},[t]),[i,n]}function Q(e){const{isOpen:t}=e,i=M(w),[n,r]=B(i);return t!==void 0?a(F,{children:t&&a(g,{...e,animate:"visible",animation:n,setAnimation:r})}):a(g,{...e,animate:n,animation:n,setAnimation:r})}export{Q as ModalOverlay,Q as default,B as useOverlayAnimationState};
+"use client";import{jsx as a}from"react/jsx-runtime";import{forwardRef as N,useContext as M,useState as k,useEffect as A,useId as R,useCallback as O}from"react";import{ModalOverlay as E,OverlayTriggerStateContext as w}from"react-aria-components";import{motion as T,AnimatePresence as F}from"framer-motion";import{cn as j}from"../../utils/cn.js";const q="body > [inert]:not(#__next):not([data-overlay-container])";function z(e){return Object.keys(e).some(t=>t.startsWith("__react"))}function p(){document.querySelectorAll(q).forEach(e=>e.removeAttribute("inert"))}function L(e){return!!(e.closest("[data-overlay-container]")||e.closest("#__next"))}const W=N(({style:e,children:t,...i},n)=>{const r=typeof e=="function"?e(i):e;return a(E,{...i,ref:n,style:r,children:t})});let m=null;function $(){return typeof window>"u"?null:(m||(m=T.create(W)),m)}const h=$();function g({animate:e,animation:t,setAnimation:i,className:n,animationVariants:r,isDismissable:u=!0,children:v,...x}){const C=R();A(()=>{p();const o=new MutationObserver(l=>{for(const d of l)if(d.type==="attributes"&&d.attributeName==="inert"){const f=d.target;f.parentElement===document.body?p():z(f)||f.removeAttribute("inert")}});return o.observe(document.body,{attributes:!0,attributeFilter:["inert"],subtree:!0}),()=>o.disconnect()},[]);const{key:S,shouldCloseOnInteractOutside:c,onOpenChange:s,..._}=x,P=O(o=>c?c(o):L(o),[c]),y=M(w),I=O(o=>{!u||o.target!==o.currentTarget||(s?s(!1):y?.close())},[u,s,y]),b={isDismissable:u,shouldCloseOnInteractOutside:P,onOpenChange:s,onPointerDown:I,className:j("bg-black/30 backdrop-blur-sm","fixed top-0 left-0","z-[1000]","w-screen h-[var(--visual-viewport-height)]",n),..._};return h?a(h,{isExiting:t==="hidden",onAnimationComplete:o=>{i(l=>o==="hidden"&&l==="hidden"?"unmounted":l)},variants:r||{hidden:{opacity:0,transition:{delay:.08}},visible:{opacity:1}},initial:"hidden",animate:e,exit:"hidden",...b,children:v},S||C):a(E,{...b,children:v})}function B(e){const t=e?.isOpen??!1,[i,n]=k(t?"visible":"unmounted");return A(()=>{n(t?"visible":r=>r==="visible"?"hidden":r)},[t]),[i,n]}function Q(e){const{isOpen:t}=e,i=M(w),[n,r]=B(i);return t!==void 0?a(F,{children:t&&a(g,{...e,animate:"visible",animation:n,setAnimation:r})}):n==="unmounted"?null:a(g,{...e,animate:n,animation:n,setAnimation:r})}export{Q as ModalOverlay,Q as default,B as useOverlayAnimationState};

package/docs/migrations/2026/09/ui-2026-09-15-server-request-headers-provider.md

@@ -0,0 +1,52 @@
+# `createAuthAwareGraphqlClient`: a server-side request-headers provider, so SSR calls can carry the shopper
+
+**Date:** 2026-09-15
+**Package:** `@clicktap/ui`
+**Affects:** `utils/createAuthAwareGraphqlClient` — new export `setServerRequestHeadersProvider()`; `executeGraphql` and `createAuthAwareFetch` consult it server-side
+**Classification:** FEATURE
+**Breaking:** No. Nothing changes until a provider is registered; explicit request headers always win over provided ones.
+**Ticket:** CTAP-1719
+
+## Why
+
+A request the Node server makes to the middleware on a shopper's behalf (SSR, route handlers)
+carried nothing identifying the shopper — the middleware saw the Node container for every visitor.
+Anything keyed on the client there (a rate limit, a lockout) would put the whole storefront in one
+bucket.
+
+The fix has to be in the shared client, because that is the one place every server-side request
+passes through — `graphqlRequest`, the quote/checkout transports (`request` and `createFetch`), route
+handlers. But this module is framework-agnostic and reachable from client components, so it cannot
+import `next/headers` itself. Hence a **provider** the app registers:
+
+```ts
+import { setServerRequestHeadersProvider } from '@clicktap/ui/utils/createAuthAwareGraphqlClient';
+
+setServerRequestHeadersProvider(() => {
+  const forwardedFor = headers().get('x-forwarded-for');   // next/headers, in a server-only module
+  return forwardedFor ? { 'x-forwarded-for': forwardedFor } : undefined;
+});
+```
+
+## Rules
+
+- Consulted **only server-side** (`typeof window === 'undefined'`); the browser path is untouched.
+- **Explicit headers win.** A header the caller passed is never overwritten by the provider.
+- **A throwing provider contributes nothing.** `headers()` throws outside a request scope (a static
+  render, a warm-up); that is "nothing to forward", not a failed request.
+- Sync or async providers are accepted.
+- Applies to both `createAuthAwareGraphqlClient()` requests and `createAuthAwareFetch()` calls.
+
+## What a consumer does
+
+Register a provider from a **server-only** module (`import 'server-only'` + `next/headers`), imported
+by the root layouts and by any route handler that fetches — see the `frontend` guide of the same
+date for the reference module. Forward the incoming `X-Forwarded-For` **verbatim**: the middleware's
+trusted-proxy walk reads it from its own end, so the browser's forged entries are inert and
+"cleaning" the chain here would only remove information.
+
+## Verification
+
+```bash
+nx run ui:test -- createAuthAwareGraphqlClient
+```

package/docs/migrations/2026/09/ui-2026-09-16-modal-overlay-detached-motion-element.md

@@ -0,0 +1,71 @@
+# BUGFIX: a closed trigger-driven `ModalOverlay` no longer keeps a detached framer-motion element mounted
+
+**Date:** 2026-09-16
+**Package:** `@clicktap/ui`
+**Affects:** `src/components/ModalOverlay/ModalOverlay.tsx` — every trigger-driven `<ModalOverlay>` (no `isOpen` prop, state from `DialogTrigger` / `OverlayTriggerStateContext`). Controlled overlays (`isOpen` given) are unchanged.
+**Classification:** BUGFIX
+**Breaking:** No API change. **Behavioral:** while its trigger is closed and has never opened, the overlay now renders `null` instead of a mounted `motion()` wrapper around an empty react-aria overlay. Nothing consumer-visible was in the DOM before either.
+**Ticket:** CTAP-1729
+
+## Problem
+
+`ModalOverlay` has two render paths. The controlled one wraps `InnerModalOverlay` in
+`AnimatePresence` and mounts it only while `isOpen`. The **trigger-driven** one mounted
+`InnerModalOverlay` **unconditionally** — including while `useOverlayAnimationState` reported
+`unmounted`. In that state react-aria's `ModalOverlay` renders nothing (closed, not exiting), but
+our `motion.create(...)` wrapper was still mounted around it: a framer-motion `VisualElement` with
+`element.current === null`, holding `initial="hidden"`, `exit="hidden"` and `animate="unmounted"`
+(which names no variant), for as long as the trigger stayed shut.
+
+Any animation that reached that element crashed framer-motion 11.18.2 with
+`TypeError: Cannot read properties of null (reading '0')`: the animation seeds `[null, target]`
+and expects the DOM read to hydrate the first keyframe; `DOMKeyframesResolver` bails on a missing
+element, so `null` survives into `mix(null, 0)` → `mixObject(null, '0')`. Two routes in, both
+observed:
+
+1. **An ancestor `AnimatePresence` exits** and propagates `exit="hidden"` down the subtree.
+2. **The subtree unmounts** — `VisualElement.unmount` stops the motion values, which flushes
+   keyframe resolvers synchronously on the detached element.
+
+🚨 Thrown inside framer-motion's frame loop, so nothing reaches server logs and no React error
+boundary catches it. noco hit it in the warranty admin: a controlled drawer (route 1) containing a
+never-opened trigger-driven Page Builder overlay threw **13 errors on every close**, and in
+production that broke the frame loop — the close animation and the success toast were both lost.
+Every other trigger-driven overlay in that app (delete confirms, edit modals) carried the same
+detached element and only stayed quiet because nothing above them animated on exit yet.
+
+## What changed
+
+The trigger-driven path returns `null` while `animation === 'unmounted'` — exactly the DOM
+react-aria was already producing, minus the motion element. The lifecycle the controlled path
+already gets from `AnimatePresence` is now the same on both paths:
+
+| trigger | `animation` | rendered |
+|---|---|---|
+| closed, never opened | `unmounted` | `null` |
+| opens | `visible` | `InnerModalOverlay` mounts with `initial="hidden"` → `animate="visible"` (entrance plays) |
+| closes while visible | `hidden` | stays mounted; `isExiting` keeps react-aria's portal alive while the exit plays |
+| exit completes | `unmounted` (via `onAnimationComplete`) | `null` again |
+
+## Consumer impact
+
+- **Nothing to change.** Take the release. If you gated the overlay yourself in a wrapper (noco
+  tried it in `@noco/ui`), **remove that gate**: mounting only once already open, with the hook
+  initialized to `visible`, gives framer-motion no transition to play and leaves the backdrop stuck
+  at `opacity: 0`. The fix has to live where the animation state is derived.
+- ⚠️ Do not read the mount as a signal. Nothing should depend on a closed trigger-driven overlay
+  having a React subtree — refs into `InnerModalOverlay` are `null` while closed now, as they
+  effectively were before (react-aria rendered no node).
+
+## Verification
+
+Unit: `ModalOverlay.mount.spec.tsx` mocks `motion.create` to record every render of the wrapper and
+pins the contract — no motion render while closed and never opened; first render on open is
+`initial: 'hidden', animate: 'visible'`; on close the last render is `animate: 'hidden', isExiting:
+true`; after `onAnimationComplete('hidden')` no further renders, including on unrelated re-renders.
+Controlled path covered for parity.
+
+Manual, in any app: open a controlled `ModalOverlay` (a drawer) that contains a `DialogTrigger`
+whose `ModalOverlay` you never open; close the drawer. Before: `Cannot read properties of null
+(reading '0')` in the console, one per animated value. After: nothing. Then open the inner overlay
+once and close both — entrance and exit both play.

package/docs/migrations/index.json

@@ -1,4 +1,24 @@
 [
+  {
+    "path": "2026/09/ui-2026-09-16-modal-overlay-detached-motion-element.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-09-16",
+    "title": "BUGFIX: a closed trigger-driven `ModalOverlay` no longer keeps a detached framer-motion element mounted",
+    "classification": "BUGFIX",
+    "breaking": "No API change. **Behavioral:** while its trigger is closed and has never opened, the overlay now renders `null` instead of a mounted `motion()` wrapper around an empty react-aria overlay. Nothing consumer-visible was in the DOM before either.",
+    "affects": "`src/components/ModalOverlay/ModalOverlay.tsx` — every trigger-driven `<ModalOverlay>` (no `isOpen` prop, state from `DialogTrigger` / `OverlayTriggerStateContext`). Controlled overlays (`isOpen` given) are unchanged."
+  },
+  {
+    "path": "2026/09/ui-2026-09-15-server-request-headers-provider.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-09-15",
+    "title": "`createAuthAwareGraphqlClient`: a server-side request-headers provider, so SSR calls can carry the shopper",
+    "classification": "FEATURE",
+    "breaking": "No. Nothing changes until a provider is registered; explicit request headers always win over provided ones.",
+    "affects": "`utils/createAuthAwareGraphqlClient` — new export `setServerRequestHeadersProvider()`; `executeGraphql` and `createAuthAwareFetch` consult it server-side"
+  },
   {
     "path": "2026/09/ui-2026-09-09-graphql-field-errors-reported-in-production.md",
     "module": "libs/frontend-modules/ui",

package/package.json

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

package/utils/createAuthAwareGraphqlClient.d.ts

@@ -111,6 +111,24 @@ declare class AuthAwareEventBus {
  * listen, regardless of which call triggered the event).
  */
 export declare const authAwareEvents: AuthAwareEventBus;
+/**
+ * Headers a SERVER-SIDE caller wants attached to every outbound request, resolved per request.
+ *
+ * CTAP-1719: a request the Node server makes to the middleware on a shopper's behalf (SSR, route
+ * handlers) carried no trace of the shopper — the middleware saw the Node container's address for
+ * every visitor, so anything keyed on the client (a rate limit, a lockout) would put the whole
+ * storefront in one bucket. The app registers a provider that reads the incoming request's
+ * `X-Forwarded-For` (via `next/headers`, which only exists in a request scope) and returns it here,
+ * so the middleware's trusted-proxy walk lands on the browser rather than on Node.
+ *
+ * Registered rather than imported because this module must stay framework-agnostic and bundleable
+ * on the client: `next/headers` cannot be imported from anything a client component reaches. The
+ * provider is only ever consulted server-side (`typeof window === 'undefined'`); explicit request
+ * headers always win over what it returns; and a provider that throws (no request scope — a build-time
+ * render, a cron) contributes nothing rather than failing the request.
+ */
+export type ServerRequestHeadersProvider = () => HeadersInit | undefined | Promise<HeadersInit | undefined>;
+export declare function setServerRequestHeadersProvider(provider: ServerRequestHeadersProvider | undefined): void;
 export type AuthAwareGraphqlRequest = <TData, TVariables extends GraphqlVariables = GraphqlVariables>(url: string, document: GraphqlDocument<TData, TVariables>, variables?: TVariables, requestHeaders?: HeadersInit) => Promise<TData>;
 export type AuthAwareGraphqlRequestWithOptions = <TData, TVariables extends GraphqlVariables = GraphqlVariables>(options: {
     url: string;

package/utils/createAuthAwareGraphqlClient.js

@@ -1 +1 @@
-class l extends Error{constructor(t,s){const e=t.errors?.[0]?.message;super(`GraphQL request failed: ${e??`HTTP ${t.status}`}`),this.name="ClientError",this.response=t,this.request=s}}class f{constructor(){this.listeners=new Map}subscribe(t,s){return this.listeners.has(t)||this.listeners.set(t,new Set),this.listeners.get(t).add(s),()=>{this.listeners.get(t)?.delete(s)}}dispatch(t,s){this.listeners.get(t)?.forEach(e=>e(s))}}const u=new f;function p(r,t){r===401?u.dispatch("unauthenticated",t):r===403?u.dispatch("permissionDenied",t):r>=500&&u.dispatch("serverError",t)}function w(r,t,s){if(!s.length)return;const e=r.match(/^\s*(?:query|mutation|subscription)\s+([A-Za-z_][A-Za-z0-9_]*)/)?.[1];for(const n of s){const c=n.path?.join(".")??"unknown",a=`[GraphQL] ${e??"operation"} — field error at ${c}: ${n.message}`;if(process.env.NODE_ENV==="development"){console.error(a,{error:n,request:{operationName:e,variables:t,query:r}});continue}console.error(a,{operationName:e,path:n.path,code:n.extensions?.code,debugMessage:n.extensions?.debugMessage})}}async function d(r){const{url:t,query:s,variables:e,requestHeaders:n,signal:c}=r,a=new Headers(n);a.set("Content-Type","application/json"),a.has("Accept")||a.set("Accept","application/json");const i=await fetch(t,{method:"POST",headers:a,body:JSON.stringify({query:s,variables:e}),signal:c});let o;try{o=await i.json()}catch{o=void 0}if(!i.ok){const h=new l({status:i.status,data:o?.data,errors:o?.errors},{query:s,variables:e});throw p(i.status,{status:i.status,error:h}),h}if(o?.data)return o.errors?.length&&w(s,e,o.errors),o.data;throw new l({status:i.status,errors:o?.errors},{query:s,variables:e})}function g(){const r=async(e,n,c,a)=>d({url:e,query:String(n),variables:c,requestHeaders:a}),t=async e=>d({url:e.url,query:String(e.document),variables:e.variables,requestHeaders:e.requestHeaders,signal:e.signal}),s=r;return s.withOptions=t,s}function y(){return async function(t,s){const e=await fetch(t,s);return(e.status===401||e.status===403||e.status>=500)&&p(e.status,{status:e.status,response:e.clone()}),e}}export{l as ClientError,u as authAwareEvents,y as createAuthAwareFetch,g as createAuthAwareGraphqlClient};
+class l extends Error{constructor(t,s){const e=t.errors?.[0]?.message;super(`GraphQL request failed: ${e??`HTTP ${t.status}`}`),this.name="ClientError",this.response=t,this.request=s}}class v{constructor(){this.listeners=new Map}subscribe(t,s){return this.listeners.has(t)||this.listeners.set(t,new Set),this.listeners.get(t).add(s),()=>{this.listeners.get(t)?.delete(s)}}dispatch(t,s){this.listeners.get(t)?.forEach(e=>e(s))}}const u=new v;function p(r,t){r===401?u.dispatch("unauthenticated",t):r===403?u.dispatch("permissionDenied",t):r>=500&&u.dispatch("serverError",t)}function g(r,t,s){if(!s.length)return;const e=r.match(/^\s*(?:query|mutation|subscription)\s+([A-Za-z_][A-Za-z0-9_]*)/)?.[1];for(const n of s){const a=n.path?.join(".")??"unknown",o=`[GraphQL] ${e??"operation"} — field error at ${a}: ${n.message}`;if(process.env.NODE_ENV==="development"){console.error(o,{error:n,request:{operationName:e,variables:t,query:r}});continue}console.error(o,{operationName:e,path:n.path,code:n.extensions?.code,debugMessage:n.extensions?.debugMessage})}}let d;function y(r){d=r}async function w(){if(!(typeof window<"u"||!d))try{const r=await d();return r?new Headers(r):void 0}catch{return}}async function q(r){return(await w())?.forEach((s,e)=>{r.has(e)||r.set(e,s)}),r}async function f(r){const{url:t,query:s,variables:e,requestHeaders:n,signal:a}=r,o=await q(new Headers(n));o.set("Content-Type","application/json"),o.has("Accept")||o.set("Accept","application/json");const c=await fetch(t,{method:"POST",headers:o,body:JSON.stringify({query:s,variables:e}),signal:a});let i;try{i=await c.json()}catch{i=void 0}if(!c.ok){const h=new l({status:c.status,data:i?.data,errors:i?.errors},{query:s,variables:e});throw p(c.status,{status:c.status,error:h}),h}if(i?.data)return i.errors?.length&&g(s,e,i.errors),i.data;throw new l({status:c.status,errors:i?.errors},{query:s,variables:e})}function E(){const r=async(e,n,a,o)=>f({url:e,query:String(n),variables:a,requestHeaders:o}),t=async e=>f({url:e.url,query:String(e.document),variables:e.variables,requestHeaders:e.requestHeaders,signal:e.signal}),s=r;return s.withOptions=t,s}function A(){return async function(t,s){const e=await w();let n=s;if(e){const o=new Headers(s?.headers);e.forEach((c,i)=>{o.has(i)||o.set(i,c)}),n={...s,headers:o}}const a=await fetch(t,n);return(a.status===401||a.status===403||a.status>=500)&&p(a.status,{status:a.status,response:a.clone()}),a}}export{l as ClientError,u as authAwareEvents,A as createAuthAwareFetch,E as createAuthAwareGraphqlClient,y as setServerRequestHeadersProvider};