@clicktap/ui 1.2.1 → 2.0.4

package/docs/migrations/2026/08/ui-2026-08-21-modal-triggers-wired-explicitly.md

@@ -0,0 +1,43 @@
+# Modal Triggers Are Wired Explicitly; Overlay Animation Back on `motion`
+
+**Date:** 2026-08-21
+**Package:** `@clicktap/ui`
+**Affects:** DialogTrigger, ModalOverlay, Dialog
+**Classification:** BUGFIX
+**Breaking:** No. Same component APIs; consumer `onPress` on the trigger child still runs (chained).
+**Ticket:** CTAP-1383
+
+## Problems
+
+1. **Trigger-driven modals never opened** — every uncontrolled `DialogTrigger` modal
+   (account address/payment create-edit-delete, delete confirmations) rendered an inert
+   button: react-aria-components wires its trigger through `PressResponderContext`, and in
+   this app's production bundles that registration silently never reaches the Button (no
+   aria attributes applied, press never toggles state) — with a verified-single instance
+   of react-aria-components, @react-aria/interactions, react, and framer-motion in the
+   bundle, so it is NOT the dual-package hazard CTAP-1210 fixed. Every working modal in
+   the app (FilterButton, RegionSelectAction, CartDrawer) works because it passes an
+   explicit `onPress`/controlled `isOpen`. Evidence says this has been broken on master
+   too (the same missing aria attributes on QA's trigger buttons).
+2. **`m.create` broke controlled modals** — the CTAP-1383 LazyMotion conversion switched
+   `motion.create(...)` to `m.create(...)` in ModalOverlay/Dialog. In production browser
+   bundles the m-created overlay never mounts its portal (works in jsdom; browser-only).
+   Verified by A/B builds: identical code with `motion.create` opens, `m.create` does not.
+
+## Changes
+
+- `DialogTrigger` no longer wraps react-aria-components' DialogTrigger. It owns a
+  `useOverlayTriggerState`, provides it on `OverlayTriggerStateContext` (which both our
+  ModalOverlay and react-aria's read), and clones the first child with an explicit
+  `onPress` that toggles the state — the mechanism the rest of the app already proves
+  out. A consumer-supplied `onPress` is chained before the toggle. The `useDialogTrigger`
+  shim is unchanged.
+- `ModalOverlay`/`Dialog` are back on `motion.create` (costs ~18 KB gz of initial JS vs
+  the m form — the price of modals that open). Root-causing why `m.create` + react-aria
+  overlays fail in production bundles is a follow-up; if solved, the m form can return.
+
+## What to check
+
+Any `DialogTrigger` + `Button` + `ModalOverlay` combination opens on press — uncontrolled
+(account pages) and controlled (PLP filter) alike. Dialog `aria-label`s are now the only
+labelling source (the react-aria trigger-id fallback is gone) — our dialogs all pass one.

package/docs/migrations/2026/08/ui-2026-08-21-next-image-fallback-keeps-fill.md

@@ -0,0 +1,38 @@
+# next Image: the optimizer-failure fallback keeps fill semantics
+
+**Date:** 2026-08-21
+**Package:** `@clicktap/ui`
+**Ticket:** CTAP-1376 (found during the CTAP-1375 QA incident)
+**Affects:** `@clicktap/ui/next/Image` — every `fill`-mode usage. No consumer code change.
+**Classification:** BUGFIX
+**Breaking:** No
+
+## The failure this removes
+
+When `next/image` optimization fails, this wrapper bypasses it and renders the
+raw src as a plain `<img>` (the `onError` debounce path and the render-error
+boundary). Both forwarded `className`, `style` and `width`/`height` — but a
+`fill` image has no width/height props, and its positioning
+(`position:absolute; inset:0; height/width:100%`) is inline style **NextImage
+itself adds**, which the fallback bypassed along with the optimizer.
+
+So a fill image whose optimizer fetch failed degraded catastrophically instead
+of gracefully: before the raw src loaded it sat as a broken icon at its
+container's top-left; once loaded it rendered at NATURAL size — a 2880px
+category hero escaping its `relative overflow-hidden` banner and filling
+multiple viewports. With an environment-wide optimizer failure (CTAP-1375:
+media URLs pointing at an unreachable host) that was every banner on the site.
+
+## The fix
+
+When the props include `fill`, both fallback `<img>`s re-apply the same inline
+styles NextImage would have (`position:absolute; height/width:100%;
+left/top/right/bottom:0`), merged under the caller's `style`. `object-fit`
+still arrives via the forwarded `className` (`object-cover` etc.). Sized
+images (width/height props) are byte-for-byte unchanged.
+
+## What you need to do
+
+Nothing — take the release. If you have ever worked around this with wrapper
+divs or manual absolute positioning around a fill-mode `Image` specifically
+for its error state, that can come off.

package/docs/migrations/2026/08/ui-2026-08-22-accordion-divider-between-items.md

@@ -0,0 +1,30 @@
+# Accordion Divider Renders BETWEEN Items; react-aria Stack Aligned
+
+**Date:** 2026-08-22
+**Package:** `@clicktap/ui`
+**Affects:** Accordion consumers using `dividerProps` as an inter-item spacer (checkout payment methods); every react-aria-components consumer
+**Classification:** BUGFIX
+**Breaking:** No (peer ranges raised: react-aria ^3.48, react-aria-components ^1.17, react-stately ^3.46).
+**Ticket:** CTAP-1383
+
+## Problems
+
+1. **Divider inside the item box.** The CTAP-1383 Accordion rewrite rendered the
+   between-items `<hr>` INSIDE each Disclosure — inside the consumer's bordered
+   `itemClasses.base` box. The checkout payment list styles the divider as an invisible
+   `h-4` spacer meant as a GAP between boxes, so every payment method carried ~32px of
+   dead space under its title. heroui rendered dividers between items; the rewrite now
+   does too (a sibling after each Disclosure).
+2. **Mixed react-aria internals.** The repo pinned react-aria 3.46 / react-aria-components
+   1.15 while pnpm resolved newer @react-aria internals into their closures. Production
+   bundles with that mix showed a family of RAC-internal failures jsdom never caught:
+   Table rows losing their cells on hover (account orders emptying), and the
+   PressResponder trigger wiring never reaching Buttons. Dev/peer versions now align on
+   the coherent set: react-aria 3.48.0, react-aria-components 1.17.0, react-stately
+   3.46.0 — verified to fix the Table hover failure outright.
+
+## What to check
+
+Payment methods render as compact bordered rows (divider = gap, not in-box padding).
+Account orders survive hovering/navigating rows. Bordered/splitted Accordion variants
+keep their internal spacing (those style the divider as a visible rule, unaffected).

package/docs/migrations/2026/08/ui-2026-08-22-accordion-divider-class-ownership.md

@@ -0,0 +1,14 @@
+# Accordion `dividerProps.className` Owns the Divider Outright
+
+**Date:** 2026-08-22
+**Package:** `@clicktap/ui`
+**Affects:** Accordion consumers styling the inter-item divider
+**Classification:** BUGFIX
+**Breaking:** No.
+**Ticket:** CTAP-1383
+
+A consumer-supplied `dividerProps.className` now replaces the default divider classes
+(spacing and color) instead of stacking on top of them. The checkout payment list
+styles the divider as an invisible `h-4` spacer; with the default `my-2` still applied
+the gap between items doubled to 32px. Consumers that pass no className keep the
+default `my-2` rule.

package/docs/migrations/2026/08/ui-2026-08-22-collection-accessibility-fixes.md

@@ -0,0 +1,28 @@
+# CollectionToolbar and ProductCardSwatches Accessibility Fixes
+
+**Date:** 2026-08-22
+**Package:** `@clicktap/ui`
+**Affects:** `Collection/CollectionToolbar`, `Collection/ProductCardSwatches`
+**Classification:** BUGFIX (accessibility)
+**Breaking:** No. Visual change is 2px of extra gap between card swatches.
+**Ticket:** CTAP-1380
+
+## Changes
+
+**`CollectionToolbar` — invalid `aria-details` removed.** The mobile filter button carried
+`aria-details="show filters"`. `aria-details` takes an **ID reference**, not text, so axe
+flags the value as invalid (`aria-valid-attr-value`). The button already has a visible
+"Filters" label, so the attribute was redundant too.
+
+**`ProductCardSwatches` — swatch spacing meets WCAG 2.5.8.** The swatches are 16px, under
+the 24px minimum target size. The standard's spacing exception allows a smaller target
+when no neighbouring target falls inside a 24px-diameter circle centred on it — centres
+at least 24px apart. The row used `gap-1.5` (6px), leaving centres 22px apart, so every
+swatch failed `target-size` (37 elements on a single collection page). Now `gap-2` (8px),
+which puts centres at exactly 24px. The swatches themselves are unchanged.
+
+## What to check
+
+Swatch rows are 2px wider per gap — confirm no wrapping regression at the narrowest
+breakpoint. Consumers overriding the swatch container's spacing should re-check they
+still satisfy the 24px centre-to-centre rule.

package/docs/migrations/2026/08/ui-2026-08-22-react-aria-moves-as-one-version-set.md

@@ -0,0 +1,46 @@
+# react-aria Moves as One Version Set
+
+**Date:** 2026-08-22
+**Package:** `@clicktap/ui`
+**Affects:** every consumer of react-aria-components — dependency policy, not an API change
+**Classification:** COMPATIBILITY
+**Read before updating:** never bump `react-aria`, `react-aria-components`, or `react-stately` independently — skewed internals fail silently, and only in production bundles.
+**Ticket:** CTAP-1383
+
+## The finding
+
+The repo pinned `react-aria-components@1.15.1` / `react-aria@3.46.0` while pnpm resolved
+NEWER `@react-aria/*` subpackages into their closures (an ordinary lockfile drift — the
+packages install fine, typecheck fine, and every jest suite passes). The mixed internals
+produced a family of failures that exist **only in production browser bundles**:
+
+- **Uncontrolled `DialogTrigger` modals were dead.** The PressResponder trigger wiring
+  never reached the Button: the trigger props arrived structurally but valueless, presses
+  never toggled the overlay state. Every account modal (address/payment create, edit,
+  delete confirmations) silently did nothing — on master too.
+- **`Table` rows lost their cells on hover.** Sweeping the pointer across the account
+  orders table emptied every `<tr>` (row elements remain, children gone) — the "my orders
+  disappear when I hover them" report. Click-through and back-navigation compounded it.
+- Likely related, unproven: `m.create()`-wrapped RAC overlays never mounting their portal
+  (see the modal-triggers guide) — same only-in-production signature.
+
+None of this reproduces in jsdom. All package instances were verified single-copy in the
+bundle (this is NOT the CTAP-1210 dual-package hazard), which is what makes the skew so
+hard to see: the failure lives in version-mismatched internals of one coherent-looking
+install.
+
+## The rule
+
+`react-aria`, `react-aria-components`, and `react-stately` are released together and must
+be adopted together. This package's devDependencies pin one coherent set (currently
+3.48.0 / 1.17.0 / 3.46.0) and its peer ranges floor consumers at the same set; the
+reference app pins the identical versions. When bumping, take the trio from the same
+react-aria release announcement and re-run the production-bundle checks below —
+aligning to the coherent set fixed the Table failure outright with no code change.
+
+## How to verify (jsdom cannot)
+
+Probe a production build in a real browser: open an uncontrolled DialogTrigger modal
+(account → Add Address), hover-sweep the orders table rows and count `[role="row"]`
+children, and diff `.pnpm` instance DIRS — key on the full directory name, not
+`name@version`, or two peer-hash instances of the same version collapse into one.

package/docs/migrations/index.json

@@ -1,4 +1,105 @@
 [
+  {
+    "path": "2026/08/ui-2026-08-22-react-aria-moves-as-one-version-set.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-22",
+    "title": "react-aria Moves as One Version Set",
+    "classification": "COMPATIBILITY",
+    "breaking": "",
+    "affects": "every consumer of react-aria-components — dependency policy, not an API change",
+    "read_before_updating": "never bump `react-aria`, `react-aria-components`, or `react-stately` independently — skewed internals fail silently, and only in production bundles."
+  },
+  {
+    "path": "2026/08/ui-2026-08-22-collection-accessibility-fixes.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-22",
+    "title": "CollectionToolbar and ProductCardSwatches Accessibility Fixes",
+    "classification": "BUGFIX (accessibility)",
+    "breaking": "No. Visual change is 2px of extra gap between card swatches.",
+    "affects": "`Collection/CollectionToolbar`, `Collection/ProductCardSwatches`"
+  },
+  {
+    "path": "2026/08/ui-2026-08-22-accordion-divider-class-ownership.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-22",
+    "title": "Accordion `dividerProps.className` Owns the Divider Outright",
+    "classification": "BUGFIX",
+    "breaking": "No.",
+    "affects": "Accordion consumers styling the inter-item divider"
+  },
+  {
+    "path": "2026/08/ui-2026-08-22-accordion-divider-between-items.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-22",
+    "title": "Accordion Divider Renders BETWEEN Items; react-aria Stack Aligned",
+    "classification": "BUGFIX",
+    "breaking": "No (peer ranges raised: react-aria ^3.48, react-aria-components ^1.17, react-stately ^3.46).",
+    "affects": "Accordion consumers using `dividerProps` as an inter-item spacer (checkout payment methods); every react-aria-components consumer"
+  },
+  {
+    "path": "2026/08/ui-2026-08-21-next-image-fallback-keeps-fill.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-21",
+    "title": "next Image: the optimizer-failure fallback keeps fill semantics",
+    "classification": "BUGFIX",
+    "breaking": "No",
+    "affects": "`@clicktap/ui/next/Image` — every `fill`-mode usage. No consumer code change."
+  },
+  {
+    "path": "2026/08/ui-2026-08-21-modal-triggers-wired-explicitly.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-21",
+    "title": "Modal Triggers Are Wired Explicitly; Overlay Animation Back on `motion`",
+    "classification": "BUGFIX",
+    "breaking": "No. Same component APIs; consumer `onPress` on the trigger child still runs (chained).",
+    "affects": "DialogTrigger, ModalOverlay, Dialog"
+  },
+  {
+    "path": "2026/08/ui-2026-08-21-lazymotion-m-components.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-21",
+    "title": "Animated Components Render `m.*` — Apps Must Provide LazyMotion Features",
+    "classification": "COMPATIBILITY",
+    "breaking": "Animations no-op (components still render and function) until the consuming app mounts a `LazyMotion` provider.",
+    "affects": "every animated component (ModalOverlay, Drawer, Dialog, Menu, ContextMenu, Tabs, Badge, Collapsible, NumberTicker, Meter, Progressbar, UploadImage)."
+  },
+  {
+    "path": "2026/08/ui-2026-08-21-heroui-removed.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-21",
+    "title": "The @heroui Dependency Is Gone — Accordion, Tooltip, Pagination, Badge Are Native",
+    "classification": "COMPATIBILITY",
+    "breaking": "API-compatible for every usage shape in the reference repo (inventoried below). Consumers importing `@heroui`/`@nextui-org` types directly must switch to this package's exports.",
+    "affects": "Accordion, Tooltip, Pagination, Badge. Peer/dev dependencies on `@heroui/*` removed."
+  },
+  {
+    "path": "2026/08/ui-2026-08-21-graphql-peer-covered.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-21",
+    "title": "`graphql` Peer Is Covered — No More Double Bundle",
+    "classification": "BUGFIX (dependency resolution)",
+    "breaking": "No. `graphql ^16.6.0` is an optional peer, matching `@clicktap/state`.",
+    "affects": "consumers' bundle size (~12 KB gz of duplicated `graphql`)"
+  },
+  {
+    "path": "2026/08/ui-2026-08-21-graphql-client-string-documents.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-21",
+    "title": "GraphQL Client Executes String Documents — graphql-request Removed",
+    "classification": "COMPATIBILITY (breaking)",
+    "breaking": "Yes. AST `TypedDocumentNode` documents are no longer accepted; the `GraphQLClient` re-export is gone; `ClientError` is now this module's own class.",
+    "affects": "`utils/createAuthAwareGraphqlClient` (public API)"
+  },
   {
     "path": "2026/08/ui-2026-08-14-zod-error-map.md",
     "module": "libs/frontend-modules/ui",

package/next/Image.js

@@ -1 +1 @@
-"use client";import{jsx as o}from"react/jsx-runtime";import R from"next/image";import{useState as x,useRef as z,Component as T}from"react";import{cn as K}from"../utils/cn.js";import{useManagedOpacity as L,useImageStyle as j,getSrcKey as c,resolveSrc as u}from"../components/Image/imageShared.js";const m=new Set;class B extends T{constructor(){super(...arguments),this.state={hasError:!1}}static getDerivedStateFromError(){return{hasError:!0}}render(){if(this.state.hasError){m.add(c(this.props.src));const{src:i,alt:n,className:a,style:s,width:h,height:r}=this.props;return o("img",{src:u(i),alt:n??"",className:a,style:s,width:h,height:r,loading:"lazy"})}return this.props.children}}function P({src:e,className:i,style:n,dimmed:a,hidden:s,onReady:h,onLoad:r,...t}){const[g,p]=x(null),l=z(),{managed:f,setLoadingImg:y,onReadyRef:S,opacityStyle:w}=L({src:e,dimmed:a,hidden:s,onReady:h}),E="width"in t&&"height"in t&&!("fill"in t),d=j(n,E),v=c(e);return g===e||m.has(v)?o("img",{src:u(e),alt:t.alt??"",className:i,style:d,width:"width"in t?t.width:void 0,height:"height"in t?t.height:void 0,loading:"lazy"}):o(B,{src:e,alt:t.alt,className:i,style:d,width:"width"in t?t.width:void 0,height:"height"in t?t.height:void 0,children:o(R,{src:e,className:K(f&&"transition-opacity duration-200 ease-in-out",i),style:{...d,...w},onError:()=>{l.current=setTimeout(()=>p(e),2e3)},onLoad:I=>{clearTimeout(l.current),y(!1),S.current?.(),typeof r=="function"&&r(I)},...t})})}export{P as Image,P as default};
+"use client";import{jsx as r}from"react/jsx-runtime";import F from"next/image";import{useState as R,useRef as T,Component as b}from"react";import{cn as x}from"../utils/cn.js";import{useManagedOpacity as z,useImageStyle as B,getSrcKey as u,resolveSrc as g}from"../components/Image/imageShared.js";const m=new Set,K={position:"absolute",height:"100%",width:"100%",left:0,top:0,right:0,bottom:0};class A extends b{constructor(){super(...arguments),this.state={hasError:!1}}static getDerivedStateFromError(){return{hasError:!0}}render(){if(this.state.hasError){m.add(u(this.props.src));const{src:e,alt:n,className:a,style:l,width:s,height:o}=this.props;return r("img",{src:g(e),alt:n??"",className:a,style:l,width:s,height:o,loading:"lazy"})}return this.props.children}}function N({src:i,className:e,style:n,dimmed:a,hidden:l,onReady:s,onLoad:o,...t}){const[f,p]=R(null),c=T(),{managed:y,setLoadingImg:S,onReadyRef:w,opacityStyle:E}=z({src:i,dimmed:a,hidden:l,onReady:s}),L="width"in t&&"height"in t&&!("fill"in t),h=B(n,L),d="fill"in t&&!!t.fill?{...K,...h}:h,v=u(i);return f===i||m.has(v)?r("img",{src:g(i),alt:t.alt??"",className:e,style:d,width:"width"in t?t.width:void 0,height:"height"in t?t.height:void 0,loading:"lazy"}):r(A,{src:i,alt:t.alt,className:e,style:d,width:"width"in t?t.width:void 0,height:"height"in t?t.height:void 0,children:r(F,{src:i,className:x(y&&"transition-opacity duration-200 ease-in-out",e),style:{...h,...E},onError:()=>{c.current=setTimeout(()=>p(i),2e3)},onLoad:I=>{clearTimeout(c.current),S(!1),w.current?.(),typeof o=="function"&&o(I)},...t})})}export{N as Image,N as default};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clicktap/ui",
-  "version": "1.2.1",
+  "version": "2.0.4",
   "private": false,
   "author": "Clicktap",
   "description": "A library of React UI components and low-level hooks.",
@@ -104,10 +104,6 @@
   "devDependencies": {
     "@floating-ui/react": "0.27.20",
     "@graphql-typed-document-node/core": "^3.2.0",
-    "@heroui/accordion": "^2.2.0",
-    "@heroui/badge": "^2.2.0",
-    "@heroui/pagination": "^2.2.0",
-    "@heroui/tooltip": "^2.2.0",
     "@nx/react": "20.5.0",
     "@nx/vite": "20.5.0",
     "@storybook/addon-actions": "^8.0.6",
@@ -117,15 +113,15 @@
     "@vitejs/plugin-react": "4.5.2",
     "framer-motion": "^11.18.0",
     "glob": "^11.0.0",
-    "graphql-request": "^6.1.0",
+    "graphql": "16.12.0",
     "next": "14.2.35",
     "react": "18.3.1",
-    "react-aria": "3.46.0",
-    "react-aria-components": "1.15.1",
+    "react-aria": "3.48.0",
+    "react-aria-components": "1.17.0",
     "react-dom": "18.3.1",
     "react-hook-form": "^7.71.1",
     "react-international-phone": "^4.7.0",
-    "react-stately": "3.44.0",
+    "react-stately": "3.46.0",
     "rollup-preserve-directives": "^1.1.3",
     "tailwindcss": "^4.3.3",
     "vite": "^7.3.1",
@@ -136,23 +132,17 @@
   "peerDependencies": {
     "@floating-ui/react": "^0.27.0",
     "@graphql-typed-document-node/core": "^3.2.0",
-    "@heroui/accordion": "^2.2.0",
-    "@heroui/badge": "^2.2.0",
-    "@heroui/pagination": "^2.2.0",
-    "@heroui/system": "^2.4.18",
-    "@heroui/theme": "^2.4.24",
-    "@heroui/tooltip": "^2.2.0",
     "@types/react": "^18.0.0",
     "framer-motion": "^11.18.0",
-    "graphql-request": "^6.1.0",
+    "graphql": "^16.6.0",
     "next": "^14.0.0",
     "react": "^18.0.0",
-    "react-aria": "^3.46.0",
-    "react-aria-components": "^1.15.0",
+    "react-aria": "^3.48.0",
+    "react-aria-components": "^1.17.0",
     "react-dom": "^18.0.0",
     "react-hook-form": "^7.71.1",
     "react-international-phone": "^4.3.0",
-    "react-stately": "^3.36.0"
+    "react-stately": "^3.46.0"
   },
   "peerDependenciesMeta": {
     "@floating-ui/react": {
@@ -161,28 +151,10 @@
     "@graphql-typed-document-node/core": {
       "optional": true
     },
-    "@heroui/accordion": {
-      "optional": true
-    },
-    "@heroui/badge": {
-      "optional": true
-    },
-    "@heroui/pagination": {
-      "optional": true
-    },
-    "@heroui/system": {
-      "optional": true
-    },
-    "@heroui/theme": {
-      "optional": true
-    },
-    "@heroui/tooltip": {
-      "optional": true
-    },
     "framer-motion": {
       "optional": true
     },
-    "graphql-request": {
+    "graphql": {
       "optional": true
     },
     "next": {

package/utils/createAuthAwareGraphqlClient.d.ts

@@ -1,11 +1,100 @@
-import { ClientError, RequestDocument, Variables } from 'graphql-request';
-import { GraphQLClientRequestHeaders } from 'graphql-request/build/esm/types';
-import { TypedDocumentNode } from '@graphql-typed-document-node/core';
-export { ClientError, GraphQLClient } from 'graphql-request';
+/**
+ * Auth-aware GraphQL client over plain `fetch` and string documents.
+ *
+ * Centralizes four behaviors that consumer apps would otherwise re-implement
+ * in every actor / mutation handler:
+ *
+ *   1. **401 → dispatch expired-session event.** Lets the app's auth machine
+ *      log the user out, toast "session expired", and redirect to login.
+ *   2. **403 → dispatch permission-denied event.**
+ *   3. **5xx → dispatch server-error event.**
+ *   4. **Partial responses (HTTP 200 with both `data` and `errors`).** The
+ *      `graphqlRequest()` form returns the partial `data` rather than
+ *      throwing — single field errors don't tear down the whole UI.
+ *
+ * CTAP-1383: this used to wrap `graphql-request`, whose static imports put
+ * the whole `graphql` package (parser, printer, AST) plus `cross-fetch` in
+ * every page's initial JS. Documents are codegen'd as `TypedDocumentString`
+ * now (`documentMode: 'string'`), so executing a request is one JSON POST —
+ * no GraphQL runtime needed. `ClientError` is our own class with the same
+ * shape `graphql-request` threw (`response.data/errors/status`,
+ * `request.query/variables`), so downstream handling — including the
+ * identity-agnostic `getRequestErrorStatus` from `@clicktap/ui/utils/error`
+ * — is unchanged. Owning the class also ends the dual-package hazard the
+ * old re-export existed to paper over.
+ *
+ * Decoupled from app runtime context (xstate actors, routers, toast systems)
+ * via an event bus. The wrappers dispatch typed events on the bus; the app
+ * subscribes from a Provider component where actors and router are in scope.
+ *
+ * Two entry points:
+ *
+ *   - `createAuthAwareGraphqlClient()` — returns a `request(url, doc, …)`
+ *     callable. Drop-in for SSR or simple call sites that just need
+ *     "fetch with the right headers and bail on errors".
+ *
+ *   - `createAuthAwareFetch()` — returns a `fetch` function that dispatches
+ *     events on 401/403/5xx. For callers that manage their own request
+ *     shape (form-data uploads, per-call cors/credentials config). The
+ *     wrapper sees the raw HTTP response, so it catches all status codes
+ *     regardless of how the request was built.
+ *
+ * Subscribe to events via the shared bus:
+ *
+ *   import { authAwareEvents } from '@clicktap/ui/utils/createAuthAwareGraphqlClient';
+ *   const unsub = authAwareEvents.subscribe('unauthenticated', ({ status }) => { … });
+ */
+/**
+ * A GraphQL document as executable text. Structurally matches codegen's
+ * `TypedDocumentString` (`documentMode: 'string'`): a `String` subclass
+ * carrying the result/variables types, so response typing flows through
+ * call sites exactly as it did with `TypedDocumentNode`. Plain strings are
+ * accepted for untyped/ad-hoc calls.
+ *
+ * Method syntax on the marker on purpose: method members compare
+ * bivariantly under `strictFunctionTypes`, so a document typed with
+ * specific variables (`TypedDocumentString<Q, Exact<{…}>>`) stays
+ * assignable at call sites that name only the result generic and let
+ * `TVariables` default.
+ */
+interface DocumentTypeMarker<TData, TVariables> {
+    __apiType?(variables: TVariables): TData;
+}
+export type GraphqlDocument<TData, TVariables> = (DocumentTypeMarker<TData, TVariables> & {
+    toString(): string;
+}) | string;
+export type GraphqlVariables = Record<string, unknown>;
+export interface GraphqlErrorItem {
+    message: string;
+    path?: Array<string | number>;
+    locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Error thrown for HTTP failures and error-only GraphQL responses. Same
+ * shape as `graphql-request`'s `ClientError` (which this replaces): the
+ * status lives at `response.status`, so structural consumers like
+ * `getRequestErrorStatus` keep working unchanged.
+ */
+export declare class ClientError extends Error {
+    readonly response: {
+        status: number;
+        data?: any;
+        errors?: GraphqlErrorItem[];
+    };
+    readonly request: {
+        query: string;
+        variables?: GraphqlVariables;
+    };
+    constructor(response: ClientError['response'], request: ClientError['request']);
+}
 export type AuthAwareEventName = 'unauthenticated' | 'permissionDenied' | 'serverError';
 export interface AuthAwareEventDetail {
     status: number;
-    /** Present when the trigger came from a `graphql-request` ClientError. */
+    /** Present when the trigger came from a GraphQL request error. */
     error?: ClientError;
     /** Present when the trigger came from the fetch wrapper. */
     response?: Response;
@@ -22,12 +111,12 @@ declare class AuthAwareEventBus {
  * listen, regardless of which call triggered the event).
  */
 export declare const authAwareEvents: AuthAwareEventBus;
-export type AuthAwareGraphqlRequest = <TData, TVariables extends Variables = Variables>(url: string, document: RequestDocument | TypedDocumentNode<TData, TVariables>, variables?: TVariables, requestHeaders?: GraphQLClientRequestHeaders) => Promise<TData>;
-export type AuthAwareGraphqlRequestWithOptions = <TData, TVariables extends Variables = Variables>(options: {
+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;
-    document: RequestDocument | TypedDocumentNode<TData, TVariables>;
+    document: GraphqlDocument<TData, TVariables>;
     variables?: TVariables;
-    requestHeaders?: GraphQLClientRequestHeaders;
+    requestHeaders?: HeadersInit;
     signal?: AbortSignal;
 }) => Promise<TData>;
 export type AuthAwareGraphqlClient = AuthAwareGraphqlRequest & {
@@ -36,14 +125,13 @@ export type AuthAwareGraphqlClient = AuthAwareGraphqlRequest & {
 export declare function createAuthAwareGraphqlClient(): AuthAwareGraphqlClient;
 /**
  * Returns a `fetch` function that delegates to the global `fetch` and
- * dispatches `authAwareEvents` on 401/403/5xx responses. Pass to
- * `new GraphQLClient(url, { fetch: createAuthAwareFetch() })` from an
- * actor that needs custom client config.
+ * dispatches `authAwareEvents` on 401/403/5xx responses. For callers that
+ * build their own request (form-data uploads, per-call cors/credentials).
  *
  * The wrapped fetch returns the original Response untouched on success
- * AND on error — `graphql-request` still parses, throws, etc. exactly
- * as it would have. The event dispatch is a side channel for the app
- * to react to the auth state without coupling actor code to router /
- * toast actors.
+ * AND on error — the caller still parses, throws, etc. exactly as it
+ * would have. The event dispatch is a side channel for the app to react
+ * to the auth state without coupling caller code to router / toast actors.
  */
 export declare function createAuthAwareFetch(): typeof fetch;
+export {};