@codefast/tracking 0.5.0-canary.4 → 0.5.0-canary.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (277) hide show
  1. package/CHANGELOG.md +473 -0
  2. package/README.md +177 -95
  3. package/dist/adapters/tanstack-start.d.ts +80 -0
  4. package/dist/adapters/tanstack-start.d.ts.map +1 -0
  5. package/dist/adapters/tanstack-start.js +74 -0
  6. package/dist/adapters/tanstack-start.js.map +1 -0
  7. package/dist/client/ad-framework-consent.d.ts +62 -0
  8. package/dist/client/ad-framework-consent.d.ts.map +1 -0
  9. package/dist/client/ad-framework-consent.js +40 -0
  10. package/dist/client/ad-framework-consent.js.map +1 -0
  11. package/dist/client/browser-cookie.d.ts +9 -0
  12. package/dist/client/browser-cookie.d.ts.map +1 -0
  13. package/dist/client/browser-cookie.js +15 -0
  14. package/dist/client/browser-cookie.js.map +1 -0
  15. package/dist/client/consent-runtime.d.ts +53 -0
  16. package/dist/client/consent-runtime.d.ts.map +1 -0
  17. package/dist/client/consent-runtime.js +33 -0
  18. package/dist/client/consent-runtime.js.map +1 -0
  19. package/dist/client/{consent-storage.d.mts → consent-storage.d.ts} +8 -6
  20. package/dist/client/consent-storage.d.ts.map +1 -0
  21. package/dist/client/consent-storage.js +109 -0
  22. package/dist/client/consent-storage.js.map +1 -0
  23. package/dist/client/consent-withdrawal.d.ts +18 -0
  24. package/dist/client/consent-withdrawal.d.ts.map +1 -0
  25. package/dist/client/consent-withdrawal.js +17 -0
  26. package/dist/client/consent-withdrawal.js.map +1 -0
  27. package/dist/client/cookie-anonymous-id.d.ts +41 -0
  28. package/dist/client/cookie-anonymous-id.d.ts.map +1 -0
  29. package/dist/client/cookie-anonymous-id.js +65 -0
  30. package/dist/client/cookie-anonymous-id.js.map +1 -0
  31. package/dist/client/create-client-tracker.d.ts +60 -0
  32. package/dist/client/create-client-tracker.d.ts.map +1 -0
  33. package/dist/client/create-client-tracker.js +91 -0
  34. package/dist/client/create-client-tracker.js.map +1 -0
  35. package/dist/client/gpc.d.ts +10 -0
  36. package/dist/client/gpc.d.ts.map +1 -0
  37. package/dist/client/gpc.js +12 -0
  38. package/dist/client/gpc.js.map +1 -0
  39. package/dist/client/initial-consent-store.d.ts +63 -0
  40. package/dist/client/initial-consent-store.d.ts.map +1 -0
  41. package/dist/client/initial-consent-store.js +138 -0
  42. package/dist/client/initial-consent-store.js.map +1 -0
  43. package/dist/client/is-analytics-allowed.d.ts +26 -0
  44. package/dist/client/is-analytics-allowed.d.ts.map +1 -0
  45. package/dist/client/is-analytics-allowed.js +22 -0
  46. package/dist/client/is-analytics-allowed.js.map +1 -0
  47. package/dist/client/server-persisted-anonymous-id.d.ts +30 -0
  48. package/dist/client/server-persisted-anonymous-id.d.ts.map +1 -0
  49. package/dist/client/server-persisted-anonymous-id.js +72 -0
  50. package/dist/client/server-persisted-anonymous-id.js.map +1 -0
  51. package/dist/core/consent-config.d.ts +24 -0
  52. package/dist/core/consent-config.d.ts.map +1 -0
  53. package/dist/core/consent-config.js +9 -0
  54. package/dist/core/consent-config.js.map +1 -0
  55. package/dist/core/consent-receipt.d.ts +71 -0
  56. package/dist/core/consent-receipt.d.ts.map +1 -0
  57. package/dist/core/consent-receipt.js +39 -0
  58. package/dist/core/consent-receipt.js.map +1 -0
  59. package/dist/core/consent.d.ts +182 -0
  60. package/dist/core/consent.d.ts.map +1 -0
  61. package/dist/core/consent.js +159 -0
  62. package/dist/core/consent.js.map +1 -0
  63. package/dist/core/cookie.d.ts +15 -0
  64. package/dist/core/cookie.d.ts.map +1 -0
  65. package/dist/core/cookie.js +26 -0
  66. package/dist/core/cookie.js.map +1 -0
  67. package/dist/core/destination.d.ts +29 -0
  68. package/dist/core/destination.d.ts.map +1 -0
  69. package/dist/core/destination.js +2 -0
  70. package/dist/core/destination.js.map +1 -0
  71. package/dist/core/event-catalog.d.ts +35 -0
  72. package/dist/core/event-catalog.d.ts.map +1 -0
  73. package/dist/core/event-catalog.js +30 -0
  74. package/dist/core/event-catalog.js.map +1 -0
  75. package/dist/core/event-id.d.ts +7 -0
  76. package/dist/core/event-id.d.ts.map +1 -0
  77. package/dist/core/event-id.js +9 -0
  78. package/dist/core/event-id.js.map +1 -0
  79. package/dist/core/tracked-event.d.ts +15 -0
  80. package/dist/core/tracked-event.d.ts.map +1 -0
  81. package/dist/core/tracked-event.js +2 -0
  82. package/dist/core/tracked-event.js.map +1 -0
  83. package/dist/destinations/ad-consent.d.ts +23 -0
  84. package/dist/destinations/ad-consent.d.ts.map +1 -0
  85. package/dist/destinations/ad-consent.js +12 -0
  86. package/dist/destinations/ad-consent.js.map +1 -0
  87. package/dist/destinations/google-analytics.d.ts +148 -0
  88. package/dist/destinations/google-analytics.d.ts.map +1 -0
  89. package/dist/destinations/google-analytics.js +156 -0
  90. package/dist/destinations/google-analytics.js.map +1 -0
  91. package/dist/destinations/google-consent.d.ts +62 -0
  92. package/dist/destinations/google-consent.d.ts.map +1 -0
  93. package/dist/destinations/google-consent.js +109 -0
  94. package/dist/destinations/google-consent.js.map +1 -0
  95. package/dist/destinations/meta.d.ts +63 -0
  96. package/dist/destinations/meta.d.ts.map +1 -0
  97. package/dist/destinations/meta.js +44 -0
  98. package/dist/destinations/meta.js.map +1 -0
  99. package/dist/destinations/microsoft-uet.d.ts +56 -0
  100. package/dist/destinations/microsoft-uet.d.ts.map +1 -0
  101. package/dist/destinations/microsoft-uet.js +41 -0
  102. package/dist/destinations/microsoft-uet.js.map +1 -0
  103. package/dist/destinations/shared.d.ts +18 -0
  104. package/dist/destinations/shared.d.ts.map +1 -0
  105. package/dist/destinations/shared.js +19 -0
  106. package/dist/destinations/shared.js.map +1 -0
  107. package/dist/destinations/tiktok.d.ts +55 -0
  108. package/dist/destinations/tiktok.d.ts.map +1 -0
  109. package/dist/destinations/tiktok.js +40 -0
  110. package/dist/destinations/tiktok.js.map +1 -0
  111. package/dist/destinations/vercel-analytics.d.ts +25 -0
  112. package/dist/destinations/vercel-analytics.d.ts.map +1 -0
  113. package/dist/destinations/vercel-analytics.js +23 -0
  114. package/dist/destinations/vercel-analytics.js.map +1 -0
  115. package/dist/index.d.ts +64 -0
  116. package/dist/index.d.ts.map +1 -0
  117. package/dist/index.js +41 -0
  118. package/dist/index.js.map +1 -0
  119. package/dist/react/consent-banner.d.ts +155 -0
  120. package/dist/react/consent-banner.d.ts.map +1 -0
  121. package/dist/react/consent-banner.js +171 -0
  122. package/dist/react/consent-banner.js.map +1 -0
  123. package/dist/react/gtag-consent-bootstrap.d.ts +17 -0
  124. package/dist/react/gtag-consent-bootstrap.d.ts.map +1 -0
  125. package/dist/react/gtag-consent-bootstrap.js +22 -0
  126. package/dist/react/gtag-consent-bootstrap.js.map +1 -0
  127. package/dist/react/use-consent.d.ts +42 -0
  128. package/dist/react/use-consent.d.ts.map +1 -0
  129. package/dist/react/use-consent.js +60 -0
  130. package/dist/react/use-consent.js.map +1 -0
  131. package/dist/react/use-google-consent-sync.d.ts +20 -0
  132. package/dist/react/use-google-consent-sync.d.ts.map +1 -0
  133. package/dist/react/use-google-consent-sync.js +22 -0
  134. package/dist/react/use-google-consent-sync.js.map +1 -0
  135. package/dist/react/use-initial-consent.d.ts +11 -0
  136. package/dist/react/use-initial-consent.d.ts.map +1 -0
  137. package/dist/react/use-initial-consent.js +18 -0
  138. package/dist/react/use-initial-consent.js.map +1 -0
  139. package/dist/server/anonymous-id-cookie.d.ts +67 -0
  140. package/dist/server/anonymous-id-cookie.d.ts.map +1 -0
  141. package/dist/server/anonymous-id-cookie.js +71 -0
  142. package/dist/server/anonymous-id-cookie.js.map +1 -0
  143. package/dist/server/consent-receipt-store.d.ts +56 -0
  144. package/dist/server/consent-receipt-store.d.ts.map +1 -0
  145. package/dist/server/consent-receipt-store.js +44 -0
  146. package/dist/server/consent-receipt-store.js.map +1 -0
  147. package/dist/server/consent-receipt.d.ts +41 -0
  148. package/dist/server/consent-receipt.d.ts.map +1 -0
  149. package/dist/server/consent-receipt.js +60 -0
  150. package/dist/server/consent-receipt.js.map +1 -0
  151. package/dist/server/initial-consent.d.ts +26 -0
  152. package/dist/server/initial-consent.d.ts.map +1 -0
  153. package/dist/server/initial-consent.js +31 -0
  154. package/dist/server/initial-consent.js.map +1 -0
  155. package/dist/server/measurement-protocol.d.ts +69 -0
  156. package/dist/server/measurement-protocol.d.ts.map +1 -0
  157. package/dist/server/measurement-protocol.js +61 -0
  158. package/dist/server/measurement-protocol.js.map +1 -0
  159. package/dist/server/region.d.ts +27 -0
  160. package/dist/server/region.d.ts.map +1 -0
  161. package/dist/server/region.js +69 -0
  162. package/dist/server/region.js.map +1 -0
  163. package/dist/server/user-deletion.d.ts +64 -0
  164. package/dist/server/user-deletion.d.ts.map +1 -0
  165. package/dist/server/user-deletion.js +54 -0
  166. package/dist/server/user-deletion.js.map +1 -0
  167. package/dist/tooling/import-protection.d.ts +19 -0
  168. package/dist/tooling/import-protection.d.ts.map +1 -0
  169. package/dist/tooling/import-protection.js +23 -0
  170. package/dist/tooling/import-protection.js.map +1 -0
  171. package/package.json +202 -107
  172. package/src/adapters/tanstack-start.ts +135 -0
  173. package/src/client/ad-framework-consent.ts +86 -0
  174. package/src/client/browser-cookie.ts +16 -0
  175. package/src/client/consent-runtime.ts +80 -0
  176. package/src/client/consent-storage.ts +31 -1
  177. package/src/client/consent-withdrawal.ts +32 -0
  178. package/src/client/cookie-anonymous-id.ts +112 -0
  179. package/src/client/create-client-tracker.ts +128 -86
  180. package/src/client/gpc.ts +4 -2
  181. package/src/client/initial-consent-store.ts +218 -0
  182. package/src/client/is-analytics-allowed.ts +43 -0
  183. package/src/client/server-persisted-anonymous-id.ts +102 -0
  184. package/src/core/consent-config.ts +27 -0
  185. package/src/core/consent-receipt.ts +115 -0
  186. package/src/core/consent.ts +164 -10
  187. package/src/core/cookie.ts +29 -0
  188. package/src/core/destination.ts +17 -8
  189. package/src/core/event-catalog.ts +29 -15
  190. package/src/core/event-id.ts +1 -2
  191. package/src/core/tracked-event.ts +4 -4
  192. package/src/css/consent.css +119 -0
  193. package/src/destinations/ad-consent.ts +29 -0
  194. package/src/destinations/google-analytics.ts +196 -133
  195. package/src/destinations/google-consent.ts +164 -0
  196. package/src/destinations/meta.ts +96 -0
  197. package/src/destinations/microsoft-uet.ts +86 -0
  198. package/src/destinations/shared.ts +45 -0
  199. package/src/destinations/tiktok.ts +85 -0
  200. package/src/destinations/vercel-analytics.ts +23 -24
  201. package/src/index.ts +165 -8
  202. package/src/react/consent-banner.tsx +308 -111
  203. package/src/react/gtag-consent-bootstrap.tsx +48 -0
  204. package/src/react/use-consent.ts +53 -45
  205. package/src/react/use-google-consent-sync.ts +38 -0
  206. package/src/react/use-initial-consent.ts +22 -0
  207. package/src/server/anonymous-id-cookie.ts +103 -0
  208. package/src/server/consent-receipt-store.ts +79 -0
  209. package/src/server/consent-receipt.ts +89 -0
  210. package/src/server/initial-consent.ts +46 -0
  211. package/src/server/measurement-protocol.ts +114 -0
  212. package/src/server/region.ts +22 -15
  213. package/src/server/user-deletion.ts +93 -0
  214. package/src/tooling/import-protection.ts +22 -0
  215. package/dist/client/consent-storage.mjs +0 -63
  216. package/dist/client/create-client-tracker.d.mts +0 -37
  217. package/dist/client/create-client-tracker.mjs +0 -66
  218. package/dist/client/gpc.d.mts +0 -10
  219. package/dist/client/gpc.mjs +0 -12
  220. package/dist/client/index.d.mts +0 -8
  221. package/dist/client/index.mjs +0 -8
  222. package/dist/client/lifecycle.d.mts +0 -23
  223. package/dist/client/lifecycle.mjs +0 -30
  224. package/dist/client/local-storage.d.mts +0 -13
  225. package/dist/client/local-storage.mjs +0 -31
  226. package/dist/client/queue.d.mts +0 -49
  227. package/dist/client/queue.mjs +0 -71
  228. package/dist/client/router.d.mts +0 -30
  229. package/dist/client/router.mjs +0 -17
  230. package/dist/core/consent.d.mts +0 -89
  231. package/dist/core/consent.mjs +0 -57
  232. package/dist/core/destination.d.mts +0 -23
  233. package/dist/core/destination.mjs +0 -1
  234. package/dist/core/event-catalog.d.mts +0 -36
  235. package/dist/core/event-catalog.mjs +0 -12
  236. package/dist/core/event-id.d.mts +0 -10
  237. package/dist/core/event-id.mjs +0 -12
  238. package/dist/core/index.d.mts +0 -6
  239. package/dist/core/index.mjs +0 -4
  240. package/dist/core/tracked-event.d.mts +0 -17
  241. package/dist/core/tracked-event.mjs +0 -1
  242. package/dist/destinations/ga4-measurement-protocol.d.mts +0 -54
  243. package/dist/destinations/ga4-measurement-protocol.mjs +0 -89
  244. package/dist/destinations/google-analytics.d.mts +0 -98
  245. package/dist/destinations/google-analytics.mjs +0 -126
  246. package/dist/destinations/http-destination.d.mts +0 -20
  247. package/dist/destinations/http-destination.mjs +0 -25
  248. package/dist/destinations/index.d.mts +0 -5
  249. package/dist/destinations/index.mjs +0 -5
  250. package/dist/destinations/vercel-analytics.d.mts +0 -13
  251. package/dist/destinations/vercel-analytics.mjs +0 -30
  252. package/dist/index.d.mts +0 -6
  253. package/dist/index.mjs +0 -4
  254. package/dist/react/consent-banner.d.mts +0 -75
  255. package/dist/react/consent-banner.mjs +0 -114
  256. package/dist/react/index.d.mts +0 -3
  257. package/dist/react/index.mjs +0 -3
  258. package/dist/react/use-consent.d.mts +0 -49
  259. package/dist/react/use-consent.mjs +0 -54
  260. package/dist/server/create-server-tracker.d.mts +0 -42
  261. package/dist/server/create-server-tracker.mjs +0 -67
  262. package/dist/server/index.d.mts +0 -3
  263. package/dist/server/index.mjs +0 -3
  264. package/dist/server/region.d.mts +0 -20
  265. package/dist/server/region.mjs +0 -56
  266. package/src/client/index.ts +0 -17
  267. package/src/client/lifecycle.ts +0 -50
  268. package/src/client/local-storage.ts +0 -44
  269. package/src/client/queue.ts +0 -117
  270. package/src/client/router.ts +0 -37
  271. package/src/core/index.ts +0 -24
  272. package/src/destinations/ga4-measurement-protocol.ts +0 -166
  273. package/src/destinations/http-destination.ts +0 -33
  274. package/src/destinations/index.ts +0 -20
  275. package/src/react/index.ts +0 -5
  276. package/src/server/create-server-tracker.ts +0 -128
  277. package/src/server/index.ts +0 -4
@@ -1,127 +1,299 @@
1
- import type { ComponentProps, ReactNode } from "react";
2
- import { useState } from "react";
1
+ "use client";
2
+
3
+ import type { ComponentProps, Dispatch, ReactNode, SetStateAction } from "react";
4
+ import { createContext, useContext, useEffect, useState } from "react";
3
5
 
4
6
  import type { ConsentCategory, ConsentDecision } from "#/core/consent";
5
- import { CONSENT_CATEGORIES } from "#/core/consent";
6
7
  import type { UseConsentResult } from "#/react/use-consent";
7
8
 
9
+ interface ConsentBannerContextValue {
10
+ consent: UseConsentResult;
11
+ /** The in-progress per-category selection — `undefined` while the preferences layer is closed. */
12
+ pending: ConsentDecision | undefined;
13
+ setPending: Dispatch<SetStateAction<ConsentDecision | undefined>>;
14
+ }
15
+
16
+ const ConsentBannerContext = createContext<ConsentBannerContextValue | null>(null);
17
+
18
+ function useConsentBannerContext(part: string): ConsentBannerContextValue {
19
+ const context = useContext(ConsentBannerContext);
20
+
21
+ if (context === null) {
22
+ throw new Error(`\`${part}\` must be rendered inside \`ConsentBanner\``);
23
+ }
24
+
25
+ return context;
26
+ }
27
+
28
+ /**
29
+ * @since 0.5.0-canary.4
30
+ */
31
+ export interface ConsentBannerProps extends ComponentProps<"section"> {
32
+ consent: UseConsentResult;
33
+ /** Overrides the default `isPromptNeeded` gating — e.g. to reopen the banner as a settings panel. */
34
+ open?: boolean | undefined;
35
+ }
36
+
8
37
  /**
9
- * One row of the preferences layer — the visitor-facing wording for a consent category.
38
+ * Non-blocking opt-in prompt for GDPR/PDPL (VN) regions, as composable parts — the root owns
39
+ * the visibility gating and the preferences-layer state; the `Accept`/`Reject`/`Customize`/
40
+ * `Save` parts wire their own clicks to the consent hook, so any markup (including a
41
+ * design system's button styles via `className`) slots in. Renders nothing once a decision
42
+ * exists or the region defaults to opt-out (`consent.isPromptNeeded`), unless `open` says
43
+ * otherwise. Rendered as a labeled region, not a `<dialog>`: an open non-modal dialog
44
+ * neither traps focus nor blocks the page, so the dialog semantics would over-promise.
45
+ * Unstyled by default — style via `className`/`data-slot` selectors, or import the
46
+ * optional `@codefast/tracking/css/consent.css` theme. `data-state` on the root flips
47
+ * between `prompt` and `preferences` for state-dependent styling.
10
48
  *
11
49
  * @since 0.5.0-canary.4
12
50
  */
13
- export interface ConsentCategoryOption {
51
+ export function ConsentBanner({ children, consent, open, ...props }: ConsentBannerProps): ReactNode {
52
+ const [pending, setPending] = useState<ConsentDecision | undefined>(undefined);
53
+
54
+ const isVisible = open ?? consent.isPromptNeeded;
55
+
56
+ // Closing must reset the layer — a reopened banner starts at the prompt, not mid-preferences.
57
+ useEffect(() => {
58
+ if (!isVisible) {
59
+ setPending(undefined);
60
+ }
61
+ }, [isVisible]);
62
+
63
+ if (!isVisible) {
64
+ return null;
65
+ }
66
+
67
+ return (
68
+ <ConsentBannerContext.Provider value={{ consent, pending, setPending }}>
69
+ <section
70
+ aria-label="Cookie consent"
71
+ data-slot="consent-banner"
72
+ data-state={pending === undefined ? "prompt" : "preferences"}
73
+ {...props}
74
+ >
75
+ {children}
76
+ </section>
77
+ </ConsentBannerContext.Provider>
78
+ );
79
+ }
80
+
81
+ /**
82
+ * @since 0.5.0-canary.5
83
+ */
84
+ export interface ConsentBannerTitleProps extends ComponentProps<"h2"> {}
85
+
86
+ /**
87
+ * @since 0.5.0-canary.5
88
+ */
89
+ export function ConsentBannerTitle({ children, ...props }: ConsentBannerTitleProps): ReactNode {
90
+ return (
91
+ <h2 data-slot="consent-title" {...props}>
92
+ {children}
93
+ </h2>
94
+ );
95
+ }
96
+
97
+ /**
98
+ * @since 0.5.0-canary.5
99
+ */
100
+ export interface ConsentBannerDescriptionProps extends ComponentProps<"p"> {}
101
+
102
+ /**
103
+ * Hosts the message and the privacy-policy link informed consent requires.
104
+ *
105
+ * @since 0.5.0-canary.5
106
+ */
107
+ export function ConsentBannerDescription(props: ConsentBannerDescriptionProps): ReactNode {
108
+ return <p data-slot="consent-description" {...props} />;
109
+ }
110
+
111
+ /**
112
+ * @since 0.5.0-canary.5
113
+ */
114
+ export interface ConsentBannerActionsProps extends ComponentProps<"div"> {}
115
+
116
+ /**
117
+ * @since 0.5.0-canary.5
118
+ */
119
+ export function ConsentBannerActions(props: ConsentBannerActionsProps): ReactNode {
120
+ return <div data-slot="consent-actions" {...props} />;
121
+ }
122
+
123
+ /**
124
+ * @since 0.5.0-canary.5
125
+ */
126
+ export interface ConsentBannerAcceptProps extends Omit<ComponentProps<"button">, "type"> {}
127
+
128
+ /**
129
+ * Grants the categories the app requested (`useConsent`'s `requestedCategories`) — never more.
130
+ *
131
+ * @since 0.5.0-canary.5
132
+ */
133
+ export function ConsentBannerAccept({ onClick, ...props }: ConsentBannerAcceptProps): ReactNode {
134
+ const { consent, setPending } = useConsentBannerContext("ConsentBannerAccept");
135
+
136
+ return (
137
+ <button
138
+ data-action="accept"
139
+ data-slot="consent-action"
140
+ {...props}
141
+ // the part owns the decision — composed so a consumer onClick (e.g. closing a settings view) still runs
142
+ onClick={(event) => {
143
+ onClick?.(event);
144
+ consent.grantAll();
145
+ setPending(undefined);
146
+ }}
147
+ type="button"
148
+ />
149
+ );
150
+ }
151
+
152
+ /**
153
+ * @since 0.5.0-canary.5
154
+ */
155
+ export interface ConsentBannerRejectProps extends Omit<ComponentProps<"button">, "type"> {}
156
+
157
+ /**
158
+ * @since 0.5.0-canary.5
159
+ */
160
+ export function ConsentBannerReject({ onClick, ...props }: ConsentBannerRejectProps): ReactNode {
161
+ const { consent, setPending } = useConsentBannerContext("ConsentBannerReject");
162
+
163
+ return (
164
+ <button
165
+ data-action="reject"
166
+ data-slot="consent-action"
167
+ {...props}
168
+ // the part owns the decision — composed so a consumer onClick (e.g. closing a settings view) still runs
169
+ onClick={(event) => {
170
+ onClick?.(event);
171
+ consent.denyAll();
172
+ setPending(undefined);
173
+ }}
174
+ type="button"
175
+ />
176
+ );
177
+ }
178
+
179
+ /**
180
+ * @since 0.5.0-canary.5
181
+ */
182
+ export interface ConsentBannerCustomizeProps extends Omit<ComponentProps<"button">, "type"> {}
183
+
184
+ /**
185
+ * Opens the per-category preferences layer, starting from the current effective state so
186
+ * nothing arrives pre-ticked in an opt-in region (pre-ticked consent is invalid under
187
+ * GDPR). Hidden while the layer is open — `ConsentBannerSave` takes over.
188
+ *
189
+ * @since 0.5.0-canary.5
190
+ */
191
+ export function ConsentBannerCustomize({ onClick, ...props }: ConsentBannerCustomizeProps): ReactNode {
192
+ const { consent, pending, setPending } = useConsentBannerContext("ConsentBannerCustomize");
193
+
194
+ if (pending !== undefined) {
195
+ return null;
196
+ }
197
+
198
+ return (
199
+ <button
200
+ data-action="customize"
201
+ data-slot="consent-action"
202
+ {...props}
203
+ // the part owns the layer toggle — composed so a consumer onClick still runs
204
+ onClick={(event) => {
205
+ onClick?.(event);
206
+ setPending(consent.effectiveConsent);
207
+ }}
208
+ type="button"
209
+ />
210
+ );
211
+ }
212
+
213
+ /**
214
+ * @since 0.5.0-canary.5
215
+ */
216
+ export interface ConsentBannerPreferencesProps extends ComponentProps<"div"> {}
217
+
218
+ /**
219
+ * Container for the per-category rows — renders only while the preferences layer is open.
220
+ *
221
+ * @since 0.5.0-canary.5
222
+ */
223
+ export function ConsentBannerPreferences(props: ConsentBannerPreferencesProps): ReactNode {
224
+ const { pending } = useConsentBannerContext("ConsentBannerPreferences");
225
+
226
+ if (pending === undefined) {
227
+ return null;
228
+ }
229
+
230
+ return <div data-slot="consent-preferences" {...props} />;
231
+ }
232
+
233
+ /**
234
+ * @since 0.5.0-canary.5
235
+ */
236
+ export interface ConsentBannerCategoryProps extends ComponentProps<"label"> {
14
237
  category: ConsentCategory;
15
- description?: string;
16
- label: string;
17
238
  }
18
239
 
19
240
  /**
20
- * @since 0.5.0-canary.4
241
+ * One checkbox row of the preferences layer — `children` is the visitor-facing wording.
242
+ *
243
+ * @since 0.5.0-canary.5
21
244
  */
22
- export interface ConsentBannerProps extends Omit<ComponentProps<"section">, "children"> {
23
- acceptLabel?: string;
24
- /** Enables the per-category preferences layer; omit to keep the two-button banner. */
25
- categories?: ReadonlyArray<ConsentCategoryOption>;
26
- consent: UseConsentResult;
27
- customizeLabel?: string;
28
- /** A node, not just a string — informed consent needs the privacy-policy link inside the message. */
29
- message?: ReactNode;
30
- rejectLabel?: string;
31
- saveLabel?: string;
32
- }
33
-
34
- /**
35
- * Non-blocking opt-in prompt for GDPR/NĐ 13 regions — renders nothing once a decision
36
- * exists or the region defaults to opt-out (`consent.needsPrompt` covers both). Accept
37
- * grants only the categories the app requested (`useConsent`'s `categories`), and the
38
- * optional `categories` prop adds a second layer of per-category checkboxes — GDPR
39
- * consent must be granular per purpose, not a single yes/no. Rendered as a labeled
40
- * region, not a `<dialog>`: an open non-modal dialog neither traps focus nor blocks the
41
- * page, so the dialog semantics would over-promise. No styling is baked in — target the
42
- * root via `className` and the parts via their `data-slot` attributes (`consent-message`,
43
- * `consent-actions`, `consent-action`, `consent-preferences`, `consent-category`).
245
+ export function ConsentBannerCategory({ category, children, ...props }: ConsentBannerCategoryProps): ReactNode {
246
+ const { pending, setPending } = useConsentBannerContext("ConsentBannerCategory");
247
+
248
+ if (pending === undefined) {
249
+ return null;
250
+ }
251
+
252
+ return (
253
+ <label data-slot="consent-category" {...props}>
254
+ <input
255
+ checked={pending[category]}
256
+ data-slot="consent-category-checkbox"
257
+ onChange={(event) => {
258
+ setPending({ ...pending, [category]: event.target.checked });
259
+ }}
260
+ type="checkbox"
261
+ />
262
+ {children}
263
+ </label>
264
+ );
265
+ }
266
+
267
+ /**
268
+ * @since 0.5.0-canary.5
269
+ */
270
+ export interface ConsentBannerSaveProps extends Omit<ComponentProps<"button">, "type"> {}
271
+
272
+ /**
273
+ * Persists the pending per-category selection — renders only while the preferences layer is open.
44
274
  *
45
- * @since 0.5.0-canary.4
275
+ * @since 0.5.0-canary.5
46
276
  */
47
- export function ConsentBanner({
48
- acceptLabel = "Accept",
49
- categories,
50
- consent,
51
- customizeLabel = "Customize",
52
- message = "We use cookies to understand how you use this site.",
53
- rejectLabel = "Reject",
54
- saveLabel = "Save preferences",
55
- ...props
56
- }: ConsentBannerProps): ReactNode {
57
- // The pending per-category selection — `undefined` while the preferences layer is closed.
58
- const [pending, setPending] = useState<ConsentDecision | undefined>(undefined);
277
+ export function ConsentBannerSave({ onClick, ...props }: ConsentBannerSaveProps): ReactNode {
278
+ const { consent, pending, setPending } = useConsentBannerContext("ConsentBannerSave");
59
279
 
60
- if (!consent.needsPrompt) {
280
+ if (pending === undefined) {
61
281
  return null;
62
282
  }
63
283
 
64
284
  return (
65
- <section aria-label="Cookie consent" data-slot="consent-banner" {...props}>
66
- <p data-slot="consent-message">{message}</p>
67
- {pending !== undefined && categories !== undefined ? (
68
- <div data-slot="consent-preferences">
69
- {categories.map((option) => (
70
- <label data-slot="consent-category" key={option.category}>
71
- <input
72
- checked={pending[option.category]}
73
- data-slot="consent-category-checkbox"
74
- onChange={(event) => {
75
- setPending({ ...pending, [option.category]: event.target.checked });
76
- }}
77
- type="checkbox"
78
- />
79
- <span data-slot="consent-category-label">{option.label}</span>
80
- {option.description === undefined ? null : (
81
- <span data-slot="consent-category-description">{option.description}</span>
82
- )}
83
- </label>
84
- ))}
85
- </div>
86
- ) : null}
87
- <div data-slot="consent-actions">
88
- {pending === undefined ? (
89
- <>
90
- <button data-action="accept" data-slot="consent-action" onClick={consent.grantAll} type="button">
91
- {acceptLabel}
92
- </button>
93
- <button data-action="reject" data-slot="consent-action" onClick={consent.denyAll} type="button">
94
- {rejectLabel}
95
- </button>
96
- {categories !== undefined && categories.length > 0 ? (
97
- <button
98
- data-action="customize"
99
- data-slot="consent-action"
100
- onClick={() => {
101
- // Starts from the current effective state — all-denied in opt-in regions,
102
- // so no box arrives pre-ticked (pre-ticked consent is invalid under GDPR).
103
- setPending(consent.effectiveConsent);
104
- }}
105
- type="button"
106
- >
107
- {customizeLabel}
108
- </button>
109
- ) : null}
110
- </>
111
- ) : (
112
- <button
113
- data-action="save"
114
- data-slot="consent-action"
115
- onClick={() => {
116
- consent.save(pending);
117
- }}
118
- type="button"
119
- >
120
- {saveLabel}
121
- </button>
122
- )}
123
- </div>
124
- </section>
285
+ <button
286
+ data-action="save"
287
+ data-slot="consent-action"
288
+ {...props}
289
+ // the part owns the decision — composed so a consumer onClick still runs
290
+ onClick={(event) => {
291
+ onClick?.(event);
292
+ consent.saveDecision(pending);
293
+ setPending(undefined);
294
+ }}
295
+ type="button"
296
+ />
125
297
  );
126
298
  }
127
299
 
@@ -129,15 +301,31 @@ export function ConsentBanner({
129
301
  * @since 0.5.0-canary.4
130
302
  */
131
303
  export interface ConsentToggleProps extends Omit<ComponentProps<"button">, "children" | "onClick" | "type"> {
132
- allowLabel?: string;
304
+ /**
305
+ * Label shown while the scoped categories are denied — clicking grants them. Defaults
306
+ * to "Allow tracking".
307
+ */
308
+ allowLabel?: string | undefined;
133
309
  consent: UseConsentResult;
134
- denyLabel?: string;
310
+ /**
311
+ * Label shown while any scoped category is granted — clicking denies them. Defaults to
312
+ * CCPA/CPRA "Do Not Sell or Share My Personal Information".
313
+ */
314
+ denyLabel?: string | undefined;
315
+ /**
316
+ * Purposes this control flips. Defaults to `["ads"]` — CCPA/CPRA "Do Not Sell or Share"
317
+ * mirrors GPC (ads denied, first-party analytics left alone). Pass `["analytics"]` (or
318
+ * both) for a broader opt-out. Distinct from `useConsent`'s `requestedCategories` (what the
319
+ * prompt asks about / `grantAll` grants).
320
+ */
321
+ toggledCategories?: ReadonlyArray<ConsentCategory> | undefined;
135
322
  }
136
323
 
137
324
  /**
138
325
  * Always-visible control for opt-out regions — CCPA/CPRA requires a persistent
139
326
  * "Do Not Sell or Share My Personal Information" mechanism, not just a one-time prompt.
140
- * Flips between denying everything and re-granting the app's requested categories.
327
+ * By default it only flips `ads` (same scope as a GPC signal); pass `toggledCategories`
328
+ * to include analytics or both.
141
329
  *
142
330
  * @since 0.5.0-canary.4
143
331
  */
@@ -145,19 +333,28 @@ export function ConsentToggle({
145
333
  allowLabel = "Allow tracking",
146
334
  consent,
147
335
  denyLabel = "Do Not Sell or Share My Personal Information",
336
+ toggledCategories = ["ads"],
148
337
  ...props
149
338
  }: ConsentToggleProps): ReactNode {
150
- const anyAllowed = CONSENT_CATEGORIES.some((category) => consent.effectiveConsent[category]);
339
+ const isAnyCategoryGranted = toggledCategories.some((category) => consent.effectiveConsent[category]);
151
340
 
152
341
  return (
153
342
  <button
154
343
  data-slot="consent-toggle"
155
344
  {...props}
156
- // the toggle owns its click — flipping the stored decision is its whole purpose
157
- onClick={anyAllowed ? consent.denyAll : consent.grantAll}
345
+ // the toggle owns its click — flipping the scoped categories is its whole purpose
346
+ onClick={() => {
347
+ const next = { ...consent.effectiveConsent };
348
+
349
+ for (const category of toggledCategories) {
350
+ next[category] = !isAnyCategoryGranted;
351
+ }
352
+
353
+ consent.saveDecision(next);
354
+ }}
158
355
  type="button"
159
356
  >
160
- {anyAllowed ? denyLabel : allowLabel}
357
+ {isAnyCategoryGranted ? denyLabel : allowLabel}
161
358
  </button>
162
359
  );
163
360
  }
@@ -0,0 +1,48 @@
1
+ import type { ComponentProps, ReactNode } from "react";
2
+
3
+ import type { GtagConsentBootstrapOptions } from "#/destinations/google-analytics";
4
+ import { buildGtagConsentBootstrapScript } from "#/destinations/google-analytics";
5
+
6
+ /**
7
+ * @since 1.0.0-canary.6
8
+ */
9
+ export interface GtagConsentBootstrapProps
10
+ extends
11
+ Omit<ComponentProps<"script">, "children" | "dangerouslySetInnerHTML" | "nonce" | "src" | "type">,
12
+ GtagConsentBootstrapOptions {}
13
+
14
+ /**
15
+ * Framework-agnostic inline `<script>` that runs `buildGtagConsentBootstrapScript` before
16
+ * hydration. Pass the same `nonce` here and in `loadGtagScript` for CSP; this component
17
+ * only sets the attribute on the host script — the generated source also stamps it onto
18
+ * the injected gtag.js tag when `nonce` is provided.
19
+ *
20
+ * @since 1.0.0-canary.6
21
+ */
22
+ export function GtagConsentBootstrap({
23
+ config,
24
+ dataLayerName,
25
+ defaultConsent,
26
+ debugMode,
27
+ gaMeasurementId,
28
+ nonce,
29
+ ...props
30
+ }: GtagConsentBootstrapProps): ReactNode {
31
+ const bootstrapOptions: GtagConsentBootstrapOptions = {
32
+ config,
33
+ defaultConsent,
34
+ gaMeasurementId,
35
+ ...(dataLayerName === undefined ? {} : { dataLayerName }),
36
+ ...(debugMode === undefined ? {} : { debugMode }),
37
+ ...(nonce === undefined ? {} : { nonce }),
38
+ };
39
+
40
+ return (
41
+ <script
42
+ {...props}
43
+ dangerouslySetInnerHTML={{ __html: buildGtagConsentBootstrapScript(bootstrapOptions) }}
44
+ {...(nonce === undefined ? {} : { nonce })}
45
+ suppressHydrationWarning
46
+ />
47
+ );
48
+ }
@@ -1,22 +1,20 @@
1
- import { useRef, useSyncExternalStore } from "react";
1
+ "use client";
2
2
 
3
- import type { ConsentCategory, ConsentDecision, ConsentMode, ConsentStorage } from "#/core/consent";
4
- import { CONSENT_CATEGORIES, createConsentDecision, isConsentDecision, resolveDefaultConsent } from "#/core/consent";
3
+ import { useCallback, useMemo, useRef, useSyncExternalStore } from "react";
4
+
5
+ import type { ConsentDecision, ConsentMode, ConsentStorage } from "#/core/consent";
6
+ import { CONSENT_CATEGORIES, createConsentDecision, readStoredDecision, resolveDefaultConsent } from "#/core/consent";
7
+ import type { ConsentConfig } from "#/core/consent-config";
5
8
 
6
9
  /**
7
10
  * @since 0.5.0-canary.4
8
11
  */
9
12
  export interface UseConsentOptions {
10
- /**
11
- * Categories the app's prompt actually asks about — `grantAll` grants exactly these,
12
- * so an analytics-only banner can never grant ads consent it never asked for.
13
- * Defaults to `["analytics"]`.
14
- */
15
- categories?: ReadonlyArray<ConsentCategory>;
16
- hasGlobalPrivacyControlSignal?: boolean;
13
+ /** Must be the same object the tracker gate and the tag bootstraps receive — one config, every surface. */
14
+ config: ConsentConfig;
15
+ hasGlobalPrivacyControlSignal?: boolean | undefined;
17
16
  mode: ConsentMode;
18
- onDecision?: (decision: ConsentDecision) => void;
19
- policyVersion: string;
17
+ onDecision?: ((decision: ConsentDecision) => void) | undefined;
20
18
  /** Must be a stable reference (module-level or memoized) — a new object per render resubscribes every render. */
21
19
  storage: ConsentStorage;
22
20
  }
@@ -32,15 +30,13 @@ export interface UseConsentResult {
32
30
  effectiveConsent: ConsentDecision;
33
31
  grantAll: () => void;
34
32
  /** Effective `analytics` consent — gates this package's own tracker pipeline. */
35
- isTrackingAllowed: boolean;
33
+ isAnalyticsAllowed: boolean;
36
34
  /** True only for opt-in regions with no stored decision yet — drives whether to render the banner. */
37
- needsPrompt: boolean;
35
+ isPromptNeeded: boolean;
38
36
  /** Persist a granular per-category choice, e.g. from a preferences panel. */
39
- save: (decision: ConsentDecision) => void;
37
+ saveDecision: (decision: ConsentDecision) => void;
40
38
  }
41
39
 
42
- const DEFAULT_CATEGORIES: ReadonlyArray<ConsentCategory> = ["analytics"];
43
-
44
40
  /**
45
41
  * Bridges `resolveConsentMode`/`resolveDefaultConsent` (core, region-aware) to React via
46
42
  * `useSyncExternalStore`: the stored record is the single source of truth, hydration is
@@ -51,8 +47,9 @@ const DEFAULT_CATEGORIES: ReadonlyArray<ConsentCategory> = ["analytics"];
51
47
  * @since 0.5.0-canary.4
52
48
  */
53
49
  export function useConsent(options: UseConsentOptions): UseConsentResult {
54
- const { storage } = options;
55
- const categories = options.categories ?? DEFAULT_CATEGORIES;
50
+ const { mode, onDecision, storage } = options;
51
+ const { policyVersion, requestedCategories } = options.config;
52
+ const hasGlobalPrivacyControlSignal = options.hasGlobalPrivacyControlSignal ?? false;
56
53
 
57
54
  // useSyncExternalStore needs a referentially stable snapshot, but JSON-backed storages
58
55
  // parse a fresh record per load — so the last valid decision is cached by value.
@@ -61,51 +58,62 @@ export function useConsent(options: UseConsentOptions): UseConsentResult {
61
58
  const decision = useSyncExternalStore(
62
59
  storage.subscribe,
63
60
  (): ConsentDecision | undefined => {
64
- const record = storage.load();
65
-
66
61
  // Only a well-formed decision under the current policy version counts — the store
67
62
  // is tamperable plain JSON, and a garbage value must re-prompt, not silently deny.
68
- if (record?.policyVersion !== options.policyVersion || !isConsentDecision(record.decision)) {
63
+ const stored = readStoredDecision(storage, policyVersion);
64
+
65
+ if (stored === undefined) {
69
66
  cachedDecision.current = undefined;
70
67
 
71
68
  return undefined;
72
69
  }
73
70
 
74
- const stored = record.decision;
75
71
  const cached = cachedDecision.current;
76
72
 
77
73
  if (cached !== undefined && CONSENT_CATEGORIES.every((category) => cached[category] === stored[category])) {
78
74
  return cached;
79
75
  }
80
76
 
81
- // A normalized copy, so tampered extra keys never leak past the hook.
82
- cachedDecision.current = createConsentDecision(CONSENT_CATEGORIES.filter((category) => stored[category]));
77
+ cachedDecision.current = stored;
83
78
 
84
79
  return cachedDecision.current;
85
80
  },
86
81
  () => undefined,
87
82
  );
88
83
 
89
- function save(next: ConsentDecision): void {
90
- // No local state — the save notifies the subscription, which re-renders with the new snapshot.
91
- storage.save({ decision: next, policyVersion: options.policyVersion, timestamp: Date.now() });
92
- options.onDecision?.(next);
93
- }
84
+ // Kept stable across renders (when their own inputs don't change) so a consumer that
85
+ // passes this hook's result down as a prop/effect-dep doesn't get a fresh identity —
86
+ // and therefore an unnecessary re-render/effect-rerun — every render.
87
+ const saveDecision = useCallback(
88
+ (next: ConsentDecision): void => {
89
+ // No local state — the save notifies the subscription, which re-renders with the new snapshot.
90
+ storage.save({ decision: next, policyVersion, timestamp: Date.now() });
91
+ onDecision?.(next);
92
+ },
93
+ [onDecision, policyVersion, storage],
94
+ );
95
+
96
+ const denyAll = useCallback(() => {
97
+ saveDecision(createConsentDecision([]));
98
+ }, [saveDecision]);
94
99
 
95
- const effectiveConsent =
96
- decision ?? resolveDefaultConsent(options.mode, categories, options.hasGlobalPrivacyControlSignal ?? false);
100
+ const grantAll = useCallback(() => {
101
+ saveDecision(createConsentDecision(requestedCategories));
102
+ }, [requestedCategories, saveDecision]);
97
103
 
98
- return {
99
- decision,
100
- denyAll: () => {
101
- save(createConsentDecision([]));
102
- },
103
- effectiveConsent,
104
- grantAll: () => {
105
- save(createConsentDecision(categories));
106
- },
107
- isTrackingAllowed: effectiveConsent.analytics,
108
- needsPrompt: options.mode === "opt-in" && decision === undefined,
109
- save,
110
- };
104
+ const effectiveConsent =
105
+ decision ?? resolveDefaultConsent({ hasGlobalPrivacyControlSignal, mode, requestedCategories });
106
+
107
+ return useMemo(
108
+ () => ({
109
+ decision,
110
+ denyAll,
111
+ effectiveConsent,
112
+ grantAll,
113
+ isAnalyticsAllowed: effectiveConsent.analytics,
114
+ isPromptNeeded: mode === "opt-in" && decision === undefined,
115
+ saveDecision,
116
+ }),
117
+ [decision, denyAll, effectiveConsent, grantAll, mode, saveDecision],
118
+ );
111
119
  }