@clicktap/ui 2.1.2 → 2.1.4

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-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,14 @@
 [
+  {
+    "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-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.2",
+  "version": "2.1.4",
   "private": false,
   "author": "Clicktap",
   "description": "A library of React UI components and low-level hooks.",