srcdev-nuxt-components 9.4.2 → 9.4.3

package/.claude/skills/components/cookie-consent-banner.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Fixed, non-modal banner shown while cookie consent is undecided (`useCookieConsent().status === 'unset'`). Accept/Reject buttons call `acceptAll()`/`rejectAll()` on [[composable-cookie-consent]] directly — no `v-model`, no emits to wire up. Pair with [[composable-google-analytics]] (or any other consent-gated script) which reads the same consent state.
+Fixed, non-modal banner shown while cookie consent is undecided (`useCookieConsent().status === 'unset'`). Accept/Reject buttons call `acceptAll()`/`rejectAll()` on [[composable-cookie-consent]] directly — no `v-model`, no emits to wire up. Pair with [[composable-analytics]] (or any other consent-gated script) which reads the same consent state.
 
 **Location**: `app/components/01.atoms/cookie-consent-banner/CookieConsentBanner.vue`
 
@@ -44,13 +44,13 @@ Per [[feedback_i18n_required]] in consuming apps, always fill these slots with `
 
 ## Basic usage
 
-Register once, in the app's default layout, alongside `DisplayToastProvider` and a call to `useGoogleAnalytics()`:
+Register once, in the app's default layout, alongside `DisplayToastProvider` and a call to `useAnalytics()`:
 
 ```vue
 <!-- layouts/default.vue -->
 <script setup lang="ts">
 const { t } = useI18n();
-useGoogleAnalytics();
+useAnalytics();
 </script>
 
 <template>

package/.claude/skills/composable-analytics.md

@@ -0,0 +1,160 @@
+# useAnalytics Composable
+
+## Overview
+
+`useAnalytics` is the **only** analytics composable consuming apps ever call — it fires custom events, tracks page views on client-side route changes, and does the one-time provider setup (script loading, consent wiring), all through the same call. It's deliberately provider-agnostic: `public.analytics.provider` in runtime config picks the backend (today only `"google-analytics"` is implemented), so call sites never reference a specific provider and adding a second one later doesn't touch any consuming-app code.
+
+Gated behind [[composable-cookie-consent]]'s consent state — events don't fire, and (for the Google Analytics provider) `gtag.js` doesn't set any cookie, until the visitor accepts via [[cookie-consent-banner]] (or your own call to `useCookieConsent().acceptAll()`).
+
+**This composable ships inside the `srcdev-nuxt-components` layer** (`app/composables/useAnalytics.ts`). Consuming apps get it via Nuxt's layer auto-import — **do not create a local copy** in the consuming app.
+
+## Prerequisites (for the `google-analytics` provider)
+
+- `NUXT_PUBLIC_ANALYTICS_GOOGLE_ANALYTICS_ID` env var set to your GA4 measurement ID (`G-XXXXXXXXXX`).
+- `@nuxt/scripts` — already a layer dependency, registered in the layer's own `modules` array. Nothing to add in the consuming app.
+- The app's CSP (if using `nuxt-security`) must allow `https://www.googletagmanager.com` in `script-src`/`connect-src` and `https://*.google-analytics.com` (a wildcard — GA4 posts to regional subdomains like `region1.google-analytics.com`, not just the bare host) in `connect-src`, or hits will be blocked once consent is granted.
+
+## Setup in the consuming app
+
+### 1. Runtime config
+
+```ts
+// nuxt.config.ts
+runtimeConfig: {
+  public: {
+    analytics: {
+      provider: "google-analytics", // only value implemented today
+      googleAnalytics: {
+        id: "", // NUXT_PUBLIC_ANALYTICS_GOOGLE_ANALYTICS_ID
+      },
+    },
+  },
+},
+```
+
+### 2. Call it once, near the app root
+
+Call `useAnalytics()` once in the default layout's `<script setup>`, alongside where [[cookie-consent-banner]] is registered — this is what wires up script loading, the consent watcher, and site-wide page-view tracking on route change:
+
+```vue
+<script setup lang="ts">
+useAnalytics();
+</script>
+
+<template>
+  <div class="page-layout">
+    <slot />
+    <CookieConsentBanner />
+  </div>
+</template>
+```
+
+It no-ops (with a console warning) if the active provider's config is unset — safe to call unconditionally in every environment, including local dev without a real measurement ID.
+
+### 3. Fire events from anywhere
+
+`useAnalytics()` is also the API for firing custom events from any page or component — safe/cheap to call repeatedly (the underlying script instance is a registry singleton keyed by measurement ID, so this never re-runs setup or duplicates the consent watcher or the page-view route listener):
+
+```ts
+const { trackEvent } = useAnalytics();
+
+const handlePlanSelect = (plan: PricingPlan) => {
+  trackEvent("select_plan", { plan_tier: plan.id, value: plan.price, currency: "GBP" });
+  // ...
+};
+```
+
+`trackEvent(name, params)` only accepts flat string/number/boolean param values (matches GA4's own event-param constraints) and silently no-ops until consent is granted — never queues events from before consent, by design.
+
+## Composable reference
+
+Source lives at `app/composables/useAnalytics.ts` in the layer. Shown here for reference only — do not recreate it in the consuming app.
+
+```ts
+export type AnalyticsProvider = "google-analytics";
+
+interface AnalyticsProviderImpl {
+  trackEvent: (name: string, params?: Record<string, string | number | boolean>) => void;
+}
+
+let pageViewTrackingRegistered = false;
+
+function useGoogleAnalyticsProvider(): AnalyticsProviderImpl | null {
+  const config = useRuntimeConfig();
+  const id = config.public.analytics?.googleAnalytics?.id;
+  if (!id) {
+    console.warn("[useAnalytics] public.analytics.googleAnalytics.id is not configured");
+    return null;
+  }
+
+  const { status, trigger } = useCookieConsent();
+  const { proxy, consent } = useScriptGoogleAnalytics({
+    id,
+    scriptOptions: { trigger },
+    defaultConsent: {
+      ad_storage: "denied",
+      ad_user_data: "denied",
+      ad_personalization: "denied",
+      analytics_storage: "denied",
+    },
+  });
+
+  watch(
+    status,
+    (value) => {
+      if (value === "unset" || !consent) return;
+      const granted = value === "granted";
+      consent.update({
+        ad_storage: granted ? "granted" : "denied",
+        ad_user_data: granted ? "granted" : "denied",
+        ad_personalization: granted ? "granted" : "denied",
+        analytics_storage: granted ? "granted" : "denied",
+      });
+    },
+    { immediate: true }
+  );
+
+  if (import.meta.client && !pageViewTrackingRegistered) {
+    pageViewTrackingRegistered = true;
+    const router = useRouter();
+    let hasNavigated = false;
+    router.afterEach((to) => {
+      if (!hasNavigated) { hasNavigated = true; return }
+      if (status.value !== "granted") return;
+      proxy.gtag("event", "page_view", { page_path: to.fullPath, page_title: document.title });
+    });
+  }
+
+  return {
+    trackEvent: (name, params) => {
+      if (status.value !== "granted") return;
+      proxy.gtag("event", name, params);
+    },
+  };
+}
+
+export function useAnalytics() {
+  const config = useRuntimeConfig();
+  const provider = config.public.analytics?.provider as AnalyticsProvider | undefined;
+  const impl = provider === "google-analytics" ? useGoogleAnalyticsProvider() : null;
+
+  return {
+    trackEvent: (name: string, params?: Record<string, string | number | boolean>) => {
+      impl?.trackEvent(name, params);
+    },
+  };
+}
+```
+
+### Key rules
+
+- **The public surface (`trackEvent`) never mentions a provider.** All GA-specific code lives in `useGoogleAnalyticsProvider()`, which is not exported. Adding a second provider means: add a branch in `useAnalytics()`, write a new `use<Provider>Provider()` implementing the same `{ trackEvent }` shape, extend the `AnalyticsProvider` union and `public.analytics.<provider>` config — no consuming-app call site changes.
+- **`trigger` only gates whether the script *loads*.** It does not itself update the Consent Mode v2 signals — `consent.update()` is the separate API that reports the visitor's actual decision to `gtag.js` for every hit it sends. Skipping this was a real bug: hits fired successfully (visible in Network) but stayed tagged as denied forever, which GA4 excludes from standard reporting.
+- **The `router.afterEach` page-view listener is registered exactly once**, guarded by a module-scope flag (`pageViewTrackingRegistered`) — not per call-site. Unlike `trackEvent`, which is safe to fire from every component that calls `useAnalytics()`, a router listener registered per call-site would fire once per component on every single route change. The very first navigation is skipped (already covered by `gtag('config', id)`'s own initial page_view).
+- **This composable, not `@nuxt/scripts`' GA registry, is what makes SPA route changes tracked at all** — `@nuxt/scripts`' GA integration has no router hook of its own; without this, only the very first page load (before any client-side navigation) would ever produce a `page_view`.
+
+## Notes
+
+- Only the Google Analytics provider is implemented — no other analytics backend exists yet, despite the provider-agnostic naming.
+- The measurement ID in `public` config is visible in the client bundle — expected, GA4 IDs are not secret.
+- Event names/params are entirely up to the consuming app; this composable doesn't define any standard event vocabulary (e.g. GA4's own `select_item`/`begin_checkout`/`purchase` ecommerce event shapes) — follow GA4's own conventions for anything you want its ecommerce reports to recognize.

package/.claude/skills/composable-cookie-consent.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-`useCookieConsent` tracks the visitor's cookie-consent decision (`unset` / `granted` / `denied`), persists it in a `privacy-notice-consent` cookie, and wraps `@nuxt/scripts`' `useScriptTriggerConsent()` gate so any consent-dependent script (Google Analytics via [[composable-google-analytics]], or anything else added later) can be wired to it.
+`useCookieConsent` tracks the visitor's cookie-consent decision (`unset` / `granted` / `denied`), persists it in a `privacy-notice-consent` cookie, and wraps `@nuxt/scripts`' `useScriptTriggerConsent()` gate so any consent-dependent script (Google Analytics via [[composable-analytics]], or anything else added later) can be wired to it.
 
 **This composable ships inside the `srcdev-nuxt-components` layer** (`app/composables/useCookieConsent.ts`). Consuming apps get it via Nuxt's layer auto-import — **do not create a local copy** in the consuming app.
 
@@ -57,7 +57,7 @@ export function useCookieConsent() {
 ### Key rules
 
 - **`useScriptTriggerConsent()` is called once at module scope**, mirroring `@nuxt/scripts`' own documented pattern — it's a single shared gate for the app's lifetime, not a fresh instance per call-site. `useCookie()` is read fresh inside the function body on every call instead, which stays SSR-request-safe (Nuxt dedupes `useCookie()` by key within a single request).
-- **`status` is the public read API.** `trigger` is exposed only so `useGoogleAnalytics` (or another consent-gated script composable) can pass it straight into `scriptOptions.trigger` — don't read/mutate `trigger` directly from app code, use `status`/`acceptAll`/`rejectAll`.
+- **`status` is the public read API.** `trigger` is exposed only so `useAnalytics` (or another consent-gated script composable) can pass it straight into `scriptOptions.trigger` — don't read/mutate `trigger` directly from app code, use `status`/`acceptAll`/`rejectAll`.
 - A prior "granted" cookie is replayed into the trigger on init, since the in-memory trigger resets on every full page load but the cookie doesn't.
 
 ## Usage
@@ -75,4 +75,4 @@ To let a user change their mind later (e.g. a "cookie preferences" link in the f
 ## Notes
 
 - Cookie name `privacy-notice-consent` is fixed by the layer, not configurable per app.
-- This composable only tracks the yes/no decision — it does not itself load any script. See [[composable-google-analytics]] for the GA4 integration that consumes `trigger`.
+- This composable only tracks the yes/no decision — it does not itself load any script. See [[composable-analytics]] for the GA4 integration that consumes `trigger`.

package/.claude/skills/index.md

@@ -60,7 +60,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── composable-anchor-scroll.md       — useAnchorScroll: smooth anchor scrolling with reduced-motion support, dynamic offset, and TabNavigation integration
 ├── composable-tooltips-guide.md      — useTooltipsGuide: sequential popover guide with auto-start, dismiss-to-advance, manual controls
 ├── composable-cookie-consent.md      — useCookieConsent: unset/granted/denied state, cookie persistence, wraps @nuxt/scripts' useScriptTriggerConsent
-├── composable-google-analytics.md    — useGoogleAnalytics: GA4 via @nuxt/scripts' useScriptGoogleAnalytics, Consent Mode v2 defaultConsent, gated on useCookieConsent
+├── composable-analytics.md           — useAnalytics: provider-agnostic trackEvent/page-view tracking (google-analytics only implemented), consent-gated, single call site for setup + firing events
 └── components/
     ├── alert-content-inner.md    — AlertContentInner: shared icon/body/dismiss molecule under AlertContent + AlertMaskedContent; app.config icon map (alertContent.icons + dismissIcon) covers all consumers
     ├── accordian-core.md       — AccordianCore indexed dynamic slots (accordian-{n}-summary/icon/content), exclusive-open grouping

package/app/composables/tests/useAnalytics.spec.ts

@@ -0,0 +1,177 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { nextTick, ref } from "vue";
+import { mockNuxtImport } from "@nuxt/test-utils/runtime";
+
+// useAnalytics's page-view tracking is registered once via a module-scope flag (see
+// useAnalytics.ts) — vi.resetModules() + a fresh dynamic import per test gives each test its
+// own clean flag state, matching a real fresh page load. useRouter() itself is NOT mocked —
+// Nuxt's own test-app bootstrap (and other internal plugins) depend on a real router instance,
+// so router.afterEach is spied on directly on the real router per test instead.
+const { updateSpy, gtagSpy, useScriptGoogleAnalyticsMock, useRuntimeConfigMock } = vi.hoisted(() => ({
+  updateSpy: vi.fn(),
+  gtagSpy: vi.fn(),
+  useScriptGoogleAnalyticsMock: vi.fn(() => ({
+    proxy: { gtag: gtagSpy },
+    consent: { update: updateSpy, default: vi.fn() },
+  })),
+  useRuntimeConfigMock: vi.fn(() => ({
+    public: { analytics: { provider: "google-analytics", googleAnalytics: { id: "" } } },
+    app: { baseURL: "/" },
+  })),
+}));
+
+const statusRef = ref<"unset" | "granted" | "denied">("unset");
+const trigger = { consented: ref(false), accept: vi.fn(), revoke: vi.fn() };
+
+const defaultRuntimeConfig = () => ({
+  public: { analytics: { provider: "google-analytics" as const, googleAnalytics: { id: "" } } },
+  app: { baseURL: "/" },
+});
+
+mockNuxtImport("useRuntimeConfig", () => useRuntimeConfigMock);
+mockNuxtImport("useScriptGoogleAnalytics", () => useScriptGoogleAnalyticsMock);
+mockNuxtImport("useCookieConsent", () => () => ({ status: statusRef, trigger }));
+
+async function importFresh() {
+  vi.resetModules();
+  return (await import("../useAnalytics")).useAnalytics;
+}
+
+function configuredWith(id: string) {
+  useRuntimeConfigMock.mockReturnValue({
+    public: { analytics: { provider: "google-analytics" as const, googleAnalytics: { id } } },
+    app: { baseURL: "/" },
+  });
+}
+
+describe("useAnalytics", () => {
+  beforeEach(() => {
+    statusRef.value = "unset";
+    trigger.accept.mockClear();
+    trigger.revoke.mockClear();
+    updateSpy.mockClear();
+    gtagSpy.mockClear();
+    useScriptGoogleAnalyticsMock.mockClear();
+    useRuntimeConfigMock.mockReturnValue(defaultRuntimeConfig());
+  });
+
+  it("warns and does nothing when googleAnalytics.id is unconfigured", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const useAnalytics = await importFresh();
+    useAnalytics();
+    expect(warnSpy).toHaveBeenCalledWith("[useAnalytics] public.analytics.googleAnalytics.id is not configured");
+    expect(useScriptGoogleAnalyticsMock).not.toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+
+  it("does nothing when provider is not 'google-analytics'", async () => {
+    useRuntimeConfigMock.mockReturnValue({
+      public: { analytics: { provider: "other-provider", googleAnalytics: { id: "G-TEST123" } } },
+      app: { baseURL: "/" },
+    });
+    const useAnalytics = await importFresh();
+    const { trackEvent } = useAnalytics();
+    trackEvent("test_event");
+    expect(useScriptGoogleAnalyticsMock).not.toHaveBeenCalled();
+    expect(gtagSpy).not.toHaveBeenCalled();
+  });
+
+  it("calls useScriptGoogleAnalytics with the configured id and defaultConsent denied", async () => {
+    configuredWith("G-TEST123");
+    const useAnalytics = await importFresh();
+    useAnalytics();
+    expect(useScriptGoogleAnalyticsMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "G-TEST123",
+        defaultConsent: {
+          ad_storage: "denied",
+          ad_user_data: "denied",
+          ad_personalization: "denied",
+          analytics_storage: "denied",
+        },
+      })
+    );
+  });
+
+  it("does not call consent.update() while status is 'unset'", async () => {
+    configuredWith("G-TEST123");
+    const useAnalytics = await importFresh();
+    useAnalytics();
+    expect(updateSpy).not.toHaveBeenCalled();
+  });
+
+  it("calls consent.update() with all signals granted once status becomes 'granted'", async () => {
+    configuredWith("G-TEST123");
+    const useAnalytics = await importFresh();
+    useAnalytics();
+    statusRef.value = "granted";
+    await nextTick();
+    expect(updateSpy).toHaveBeenCalledWith({
+      ad_storage: "granted",
+      ad_user_data: "granted",
+      ad_personalization: "granted",
+      analytics_storage: "granted",
+    });
+  });
+
+  it("trackEvent() does nothing while status is not 'granted'", async () => {
+    configuredWith("G-TEST123");
+    const useAnalytics = await importFresh();
+    const { trackEvent } = useAnalytics();
+    trackEvent("select_plan", { plan_tier: "basic" });
+    expect(gtagSpy).not.toHaveBeenCalledWith("event", "select_plan", expect.anything());
+  });
+
+  it("trackEvent() calls proxy.gtag('event', name, params) once status is 'granted'", async () => {
+    configuredWith("G-TEST123");
+    const useAnalytics = await importFresh();
+    const { trackEvent } = useAnalytics();
+    statusRef.value = "granted";
+    await nextTick();
+    trackEvent("select_plan", { plan_tier: "basic" });
+    expect(gtagSpy).toHaveBeenCalledWith("event", "select_plan", { plan_tier: "basic" });
+  });
+
+  it("registers a single router.afterEach listener no matter how many times useAnalytics() is called", async () => {
+    configuredWith("G-TEST123");
+    const router = useRouter();
+    const afterEachSpy = vi.spyOn(router, "afterEach");
+    const useAnalytics = await importFresh();
+    useAnalytics();
+    useAnalytics(); // e.g. called again from a second component
+    expect(afterEachSpy).toHaveBeenCalledTimes(1);
+    afterEachSpy.mockRestore();
+  });
+
+  it("skips the first navigation (already covered by gtag('config')'s own page_view) and fires page_view on subsequent navigations once granted", async () => {
+    configuredWith("G-TEST123");
+    const router = useRouter();
+    const afterEachSpy = vi.spyOn(router, "afterEach");
+    const useAnalytics = await importFresh();
+    useAnalytics();
+    statusRef.value = "granted";
+    await nextTick();
+
+    const afterEachCallback = afterEachSpy.mock.calls[0]![0] as (to: { fullPath: string }) => void;
+    afterEachCallback({ fullPath: "/first" });
+    expect(gtagSpy).not.toHaveBeenCalledWith("event", "page_view", expect.anything());
+
+    afterEachCallback({ fullPath: "/second" });
+    expect(gtagSpy).toHaveBeenCalledWith("event", "page_view", { page_path: "/second", page_title: document.title });
+    afterEachSpy.mockRestore();
+  });
+
+  it("does not fire page_view on navigation while consent is not granted", async () => {
+    configuredWith("G-TEST123");
+    const router = useRouter();
+    const afterEachSpy = vi.spyOn(router, "afterEach");
+    const useAnalytics = await importFresh();
+    useAnalytics();
+
+    const afterEachCallback = afterEachSpy.mock.calls[0]![0] as (to: { fullPath: string }) => void;
+    afterEachCallback({ fullPath: "/first" }); // consumed as the "initial" navigation
+    afterEachCallback({ fullPath: "/second" });
+    expect(gtagSpy).not.toHaveBeenCalledWith("event", "page_view", expect.anything());
+    afterEachSpy.mockRestore();
+  });
+});

package/app/composables/tests/useCookieConsent.spec.ts

@@ -79,7 +79,7 @@ describe("useCookieConsent", () => {
     expect(revokeSpy).toHaveBeenCalled();
   });
 
-  it("exposes the raw trigger for useGoogleAnalytics to consume", () => {
+  it("exposes the raw trigger for useAnalytics to consume", () => {
     const { trigger } = useCookieConsent();
     expect(trigger).toBeTruthy();
     expect(typeof trigger.accept).toBe("function");

package/app/composables/useAnalytics.ts

@@ -0,0 +1,101 @@
+export type AnalyticsProvider = "google-analytics";
+
+interface AnalyticsProviderImpl {
+  trackEvent: (name: string, params?: Record<string, string | number | boolean>) => void;
+}
+
+// Registered once regardless of how many times useAnalytics() is called across the app —
+// unlike trackEvent, a router listener must not be set up per call-site, or every route change
+// would fire once per component that ever called useAnalytics(). Guarded to client-only so this
+// module-scope flag can't get "used up" by a server render before any client code runs.
+let pageViewTrackingRegistered = false;
+
+function useGoogleAnalyticsProvider(): AnalyticsProviderImpl | null {
+  const config = useRuntimeConfig();
+  const id = config.public.analytics?.googleAnalytics?.id;
+
+  if (!id) {
+    console.warn("[useAnalytics] public.analytics.googleAnalytics.id is not configured");
+    return null;
+  }
+
+  const { status, trigger } = useCookieConsent();
+
+  const { proxy, consent } = useScriptGoogleAnalytics({
+    id,
+    scriptOptions: { trigger },
+    defaultConsent: {
+      ad_storage: "denied",
+      ad_user_data: "denied",
+      ad_personalization: "denied",
+      analytics_storage: "denied",
+    },
+  });
+
+  // `trigger` above only gates whether gtag.js *loads* — it does not itself flip the Consent
+  // Mode v2 signals gtag.js reports alongside every hit. Without this, hits fire successfully
+  // (visible in Network) but stay tagged with defaultConsent's "denied" state forever, which
+  // GA4 excludes from standard reporting — a real bug found via a live hit's gcs=G100/pscdl=denied
+  // query params still showing after accepting, 2026-09-06. `consent.update()` is the separate
+  // API that actually reports the visitor's decision back to gtag.js; `immediate: true` also
+  // covers a returning visitor whose cookie already says "granted" on this page load.
+  watch(
+    status,
+    (value) => {
+      if (value === "unset" || !consent) return;
+      const granted = value === "granted";
+      consent.update({
+        ad_storage: granted ? "granted" : "denied",
+        ad_user_data: granted ? "granted" : "denied",
+        ad_personalization: granted ? "granted" : "denied",
+        analytics_storage: granted ? "granted" : "denied",
+      });
+    },
+    { immediate: true }
+  );
+
+  if (import.meta.client && !pageViewTrackingRegistered) {
+    pageViewTrackingRegistered = true;
+    const router = useRouter();
+    let hasNavigated = false;
+    router.afterEach((to) => {
+      if (!hasNavigated) {
+        // The initial load's page_view is already sent by gtag('config', id) inside
+        // useScriptGoogleAnalytics' own clientInit — only subsequent client-side
+        // navigations (which don't otherwise fire page_view anywhere in this app or
+        // @nuxt/scripts' GA registry) need an explicit one here.
+        hasNavigated = true;
+        return;
+      }
+      if (status.value !== "granted") return;
+      proxy.gtag("event", "page_view", {
+        page_path: to.fullPath,
+        page_title: document.title,
+      });
+    });
+  }
+
+  return {
+    trackEvent: (name, params) => {
+      if (status.value !== "granted") return;
+      proxy.gtag("event", name, params);
+    },
+  };
+}
+
+// Call from anywhere — the layout, for one-time setup (script load, consent wiring, page-view
+// tracking), or any page/component, to fire an event. Safe/cheap to call repeatedly: the
+// underlying script instance is a registry singleton keyed by measurement ID (@nuxt/scripts
+// dedupes by id), so this never re-runs clientInit or duplicates the consent watcher.
+export function useAnalytics() {
+  const config = useRuntimeConfig();
+  const provider = config.public.analytics?.provider as AnalyticsProvider | undefined;
+
+  const impl = provider === "google-analytics" ? useGoogleAnalyticsProvider() : null;
+
+  return {
+    trackEvent: (name: string, params?: Record<string, string | number | boolean>) => {
+      impl?.trackEvent(name, params);
+    },
+  };
+}

package/app/composables/useCookieConsent.ts

@@ -2,7 +2,7 @@ import type { CookieConsentStatus } from "~/types/components";
 
 // Singleton, same pattern @nuxt/scripts itself documents for
 // useScriptTriggerConsent (a single shared gate for the app's lifetime, not a
-// fresh instance per call-site). This is what useGoogleAnalytics()'s
+// fresh instance per call-site). This is what useAnalytics()'s
 // `trigger` option is wired to.
 //
 // Built lazily on first call rather than at module scope — module-scope
@@ -47,7 +47,7 @@ export function useCookieConsent() {
     acceptAll,
     rejectAll,
     // Internal API: pass straight into useScriptGoogleAnalytics's
-    // scriptOptions.trigger (see useGoogleAnalytics()). Not for consuming
+    // scriptOptions.trigger (see useAnalytics()). Not for consuming
     // app code to read/mutate directly — use status/acceptAll/rejectAll.
     trigger,
   };

package/nuxt.config.ts

@@ -26,10 +26,16 @@ export default defineNuxtConfig({
       colourScheme: {
         enabled: true,
       },
-      // Consumer apps set NUXT_PUBLIC_GOOGLE_ANALYTICS_ID to their GA4 measurement ID
-      // (G-XXXXXXXXXX) to enable useGoogleAnalytics(); left empty it no-ops.
-      googleAnalytics: {
-        id: "",
+      // Consumer apps call useAnalytics() to fire events / track page views. `provider`
+      // selects the backend — only "google-analytics" is implemented today, but call sites
+      // never reference a provider directly, so adding a second one later is additive.
+      // Set NUXT_PUBLIC_ANALYTICS_GOOGLE_ANALYTICS_ID to a GA4 measurement ID (G-XXXXXXXXXX)
+      // to enable it; left empty it no-ops.
+      analytics: {
+        provider: "google-analytics",
+        googleAnalytics: {
+          id: "",
+        },
       },
     },
   },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "srcdev-nuxt-components",
   "type": "module",
-  "version": "9.4.2",
+  "version": "9.4.3",
   "main": "nuxt.config.ts",
   "types": "types.d.ts",
   "license": "MIT",

package/.claude/skills/composable-google-analytics.md

@@ -1,105 +0,0 @@
-# useGoogleAnalytics Composable
-
-## Overview
-
-`useGoogleAnalytics` loads Google Analytics 4 (`gtag.js`) via `@nuxt/scripts`' `useScriptGoogleAnalytics()`, gated behind [[composable-cookie-consent]]'s consent state and Google Consent Mode v2's `defaultConsent`. The script does not fetch, and no analytics cookie is set, until the visitor accepts via [[cookie-consent-banner]] (or your own call to `useCookieConsent().acceptAll()`).
-
-**This composable ships inside the `srcdev-nuxt-components` layer** (`app/composables/useGoogleAnalytics.ts`). Consuming apps get it via Nuxt's layer auto-import — **do not create a local copy** in the consuming app.
-
-## Prerequisites
-
-- `NUXT_PUBLIC_GOOGLE_ANALYTICS_ID` env var set to your GA4 measurement ID (`G-XXXXXXXXXX`).
-- `@nuxt/scripts` — already a layer dependency, registered in the layer's own `modules` array. Nothing to add in the consuming app.
-- The app's CSP (if using `nuxt-security`) must allow `https://www.googletagmanager.com` in `script-src`/`connect-src` and `https://www.google-analytics.com` in `connect-src`, or the script will be blocked once consent is granted.
-
-## Setup in the consuming app
-
-### 1. Runtime config
-
-```ts
-// nuxt.config.ts
-runtimeConfig: {
-  public: {
-    googleAnalytics: {
-      id: "", // NUXT_PUBLIC_GOOGLE_ANALYTICS_ID
-    },
-  },
-},
-```
-
-### 2. Call it once
-
-Call `useGoogleAnalytics()` once, near the app root — e.g. in the default layout's `<script setup>`, alongside where [[cookie-consent-banner]] is registered:
-
-```vue
-<script setup lang="ts">
-useGoogleAnalytics();
-</script>
-
-<template>
-  <div class="page-layout">
-    <slot />
-    <CookieConsentBanner />
-  </div>
-</template>
-```
-
-It no-ops (with a console warning) if `googleAnalytics.id` is unset — safe to call unconditionally in every environment, including local dev without a real measurement ID.
-
-## Composable reference
-
-Source lives at `app/composables/useGoogleAnalytics.ts` in the layer. Shown here for reference only — do not recreate it in the consuming app.
-
-```ts
-export const useGoogleAnalytics = () => {
-  const config = useRuntimeConfig();
-  const id = config.public.googleAnalytics?.id;
-
-  if (!id) {
-    console.warn("[useGoogleAnalytics] public.googleAnalytics.id is not configured");
-    return;
-  }
-
-  const { status, trigger } = useCookieConsent();
-
-  const { consent } = useScriptGoogleAnalytics({
-    id,
-    scriptOptions: { trigger },
-    defaultConsent: {
-      ad_storage: "denied",
-      ad_user_data: "denied",
-      ad_personalization: "denied",
-      analytics_storage: "denied",
-    },
-  });
-
-  // trigger only gates whether gtag.js *loads* — consent.update() is the separate API that
-  // actually reports the visitor's decision back to gtag.js for every hit it sends.
-  watch(
-    status,
-    (value) => {
-      if (value === "unset" || !consent) return;
-      const granted = value === "granted";
-      consent.update({
-        ad_storage: granted ? "granted" : "denied",
-        ad_user_data: granted ? "granted" : "denied",
-        ad_personalization: granted ? "granted" : "denied",
-        analytics_storage: granted ? "granted" : "denied",
-      });
-    },
-    { immediate: true }
-  );
-};
-```
-
-### Key rules
-
-- **`useRuntimeConfig()` inside the function body**, not module scope — same reasoning as `useWhatsApp` (see [[composable-whatsapp]]).
-- **`defaultConsent` is all `"denied"`** — sets the initial Consent Mode v2 state before gtag.js has any real signal. `trigger` (passed to `scriptOptions.trigger`) only controls when the script *loads*; it does **not** itself update the Consent Mode signals. Without the `consent.update()` watcher, hits fire successfully once loaded but stay tagged as denied forever, which GA4 excludes from standard reporting — this was a real bug (hits visible in Network, "no data received" in the GA4 dashboard) until the watcher was added.
-- The `watch(status, ..., { immediate: true })` also covers a returning visitor whose `cookie-consent` cookie already says "granted" on this page load, before any click happens.
-- Does not return anything — it's a side-effecting setup call, not a value composable. Read GA-related state (if ever needed) via `useCookieConsent()` instead.
-
-## Notes
-
-- Only loads GA4 (`gtag.js`) — no other Google tags (Ads, Tag Manager container, etc.). Extend `defaultConsent`/add a second `useScript*` call if those are needed later.
-- The measurement ID in `public` config is visible in the client bundle — expected, GA4 IDs are not secret.

package/app/composables/tests/useGoogleAnalytics.spec.ts

@@ -1,90 +0,0 @@
-import { describe, it, expect, beforeEach, vi } from "vitest";
-import { nextTick, ref } from "vue";
-import { mockNuxtImport } from "@nuxt/test-utils/runtime";
-
-const { useRuntimeConfigMock, updateSpy, useScriptGoogleAnalyticsMock } = vi.hoisted(() => ({
-  useRuntimeConfigMock: vi.fn(() => ({ public: { googleAnalytics: { id: "" } }, app: { baseURL: "/" } })),
-  updateSpy: vi.fn(),
-  useScriptGoogleAnalyticsMock: vi.fn(() => ({ consent: { update: updateSpy, default: vi.fn() } })),
-}));
-
-const statusRef = ref<"unset" | "granted" | "denied">("unset");
-const trigger = { consented: ref(false), accept: vi.fn(), revoke: vi.fn() };
-
-mockNuxtImport("useRuntimeConfig", () => useRuntimeConfigMock);
-mockNuxtImport("useScriptGoogleAnalytics", () => useScriptGoogleAnalyticsMock);
-mockNuxtImport("useCookieConsent", () => () => ({ status: statusRef, trigger }));
-
-const { useGoogleAnalytics } = await import("../useGoogleAnalytics");
-
-describe("useGoogleAnalytics", () => {
-  beforeEach(() => {
-    statusRef.value = "unset";
-    updateSpy.mockClear();
-    useScriptGoogleAnalyticsMock.mockClear();
-    useRuntimeConfigMock.mockReturnValue({ public: { googleAnalytics: { id: "" } }, app: { baseURL: "/" } });
-  });
-
-  it("warns and does nothing when googleAnalytics.id is unconfigured", () => {
-    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-    useGoogleAnalytics();
-    expect(warnSpy).toHaveBeenCalledWith("[useGoogleAnalytics] public.googleAnalytics.id is not configured");
-    expect(useScriptGoogleAnalyticsMock).not.toHaveBeenCalled();
-    warnSpy.mockRestore();
-  });
-
-  it("calls useScriptGoogleAnalytics with the configured id and defaultConsent denied", () => {
-    useRuntimeConfigMock.mockReturnValue({ public: { googleAnalytics: { id: "G-TEST123" } }, app: { baseURL: "/" } });
-    useGoogleAnalytics();
-    expect(useScriptGoogleAnalyticsMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        id: "G-TEST123",
-        defaultConsent: {
-          ad_storage: "denied",
-          ad_user_data: "denied",
-          ad_personalization: "denied",
-          analytics_storage: "denied",
-        },
-      })
-    );
-  });
-
-  it("does not call consent.update() while status is 'unset'", () => {
-    useRuntimeConfigMock.mockReturnValue({ public: { googleAnalytics: { id: "G-TEST123" } }, app: { baseURL: "/" } });
-    useGoogleAnalytics();
-    expect(updateSpy).not.toHaveBeenCalled();
-  });
-
-  it("calls consent.update() with all signals granted once status becomes 'granted'", async () => {
-    useRuntimeConfigMock.mockReturnValue({ public: { googleAnalytics: { id: "G-TEST123" } }, app: { baseURL: "/" } });
-    useGoogleAnalytics();
-    statusRef.value = "granted";
-    await nextTick();
-    expect(updateSpy).toHaveBeenCalledWith({
-      ad_storage: "granted",
-      ad_user_data: "granted",
-      ad_personalization: "granted",
-      analytics_storage: "granted",
-    });
-  });
-
-  it("calls consent.update() with all signals denied when status becomes 'denied'", async () => {
-    useRuntimeConfigMock.mockReturnValue({ public: { googleAnalytics: { id: "G-TEST123" } }, app: { baseURL: "/" } });
-    useGoogleAnalytics();
-    statusRef.value = "denied";
-    await nextTick();
-    expect(updateSpy).toHaveBeenCalledWith({
-      ad_storage: "denied",
-      ad_user_data: "denied",
-      ad_personalization: "denied",
-      analytics_storage: "denied",
-    });
-  });
-
-  it("immediately reports consent.update() for a returning visitor already granted", () => {
-    useRuntimeConfigMock.mockReturnValue({ public: { googleAnalytics: { id: "G-TEST123" } }, app: { baseURL: "/" } });
-    statusRef.value = "granted";
-    useGoogleAnalytics();
-    expect(updateSpy).toHaveBeenCalledWith(expect.objectContaining({ analytics_storage: "granted" }));
-  });
-});

package/app/composables/useGoogleAnalytics.ts

@@ -1,48 +0,0 @@
-// Call once from the consuming app's layout/app.vue. Loading is gated behind
-// useCookieConsent() — the gtag.js script only actually fetches once the
-// visitor accepts, and Google Consent Mode v2's default state starts denied
-// so no analytics cookie is set before that.
-export const useGoogleAnalytics = () => {
-  const config = useRuntimeConfig();
-  const id = config.public.googleAnalytics?.id;
-
-  if (!id) {
-    console.warn("[useGoogleAnalytics] public.googleAnalytics.id is not configured");
-    return;
-  }
-
-  const { status, trigger } = useCookieConsent();
-
-  const { consent } = useScriptGoogleAnalytics({
-    id,
-    scriptOptions: { trigger },
-    defaultConsent: {
-      ad_storage: "denied",
-      ad_user_data: "denied",
-      ad_personalization: "denied",
-      analytics_storage: "denied",
-    },
-  });
-
-  // `trigger` above only gates whether gtag.js *loads* — it does not itself flip the Consent
-  // Mode v2 signals gtag.js reports alongside every hit. Without this, hits fire successfully
-  // (visible in Network) but stay tagged with defaultConsent's "denied" state forever, which
-  // GA4 excludes from standard reporting — confirmed via a real hit's gcs=G100/pscdl=denied
-  // query params still showing after accepting, 2026-09-06. `consent.update()` is the separate
-  // API that actually reports the visitor's decision back to gtag.js; `immediate: true` also
-  // covers a returning visitor whose cookie already says "granted" on this page load.
-  watch(
-    status,
-    (value) => {
-      if (value === "unset" || !consent) return;
-      const granted = value === "granted";
-      consent.update({
-        ad_storage: granted ? "granted" : "denied",
-        ad_user_data: granted ? "granted" : "denied",
-        ad_personalization: granted ? "granted" : "denied",
-        analytics_storage: granted ? "granted" : "denied",
-      });
-    },
-    { immediate: true }
-  );
-};