@djangocfg/layouts 2.1.470 → 2.1.472

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.470",
+  "version": "2.1.472",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -89,11 +89,12 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.470",
-    "@djangocfg/centrifugo": "^2.1.470",
-    "@djangocfg/devtools": "^2.1.470",
-    "@djangocfg/i18n": "^2.1.470",
-    "@djangocfg/ui-core": "^2.1.470",
+    "@djangocfg/analytics": "workspace:*",
+    "@djangocfg/api": "^2.1.472",
+    "@djangocfg/centrifugo": "^2.1.472",
+    "@djangocfg/devtools": "^2.1.472",
+    "@djangocfg/i18n": "^2.1.472",
+    "@djangocfg/ui-core": "^2.1.472",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -120,17 +121,17 @@
     "libphonenumber-js": "^1.13.8",
     "nextjs-toploader": "^3.9.17",
     "qrcode.react": "^4.2.0",
-    "react-ga4": "^2.1.0",
     "uuid": "^11.1.1"
   },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.470",
-    "@djangocfg/centrifugo": "^2.1.470",
-    "@djangocfg/devtools": "^2.1.470",
-    "@djangocfg/i18n": "^2.1.470",
-    "@djangocfg/typescript-config": "^2.1.470",
-    "@djangocfg/ui-core": "^2.1.470",
-    "@djangocfg/ui-tools": "^2.1.470",
+    "@djangocfg/analytics": "workspace:*",
+    "@djangocfg/api": "^2.1.472",
+    "@djangocfg/centrifugo": "^2.1.472",
+    "@djangocfg/devtools": "^2.1.472",
+    "@djangocfg/i18n": "^2.1.472",
+    "@djangocfg/typescript-config": "^2.1.472",
+    "@djangocfg/ui-core": "^2.1.472",
+    "@djangocfg/ui-tools": "^2.1.472",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",
     "@types/react-dom": "19.2.3",

package/src/snippets/Analytics/AnalyticsProvider.tsx

@@ -1,34 +1,120 @@
+'use client';
+
 /**
- * AnalyticsProvider Component
+ * The layouts adapter for `@djangocfg/analytics`.
+ *
+ * BaseApp mounts this inside AuthProvider, which is what lets it attach the
+ * signed-in user's id — the thing hosted analytics (Plausible, Umami, GA4
+ * without extra plumbing) structurally cannot do.
  *
- * Initializes Google Analytics and auto-tracks pageviews.
- * Can work standalone with trackingId prop, or use AppContext if available.
+ * Transports are composed here:
+ *   - `djangocfg` — always on. Same-origin, self-hosted, no third party.
+ *   - `ga4`       — only when a tracking id is configured.
+ *
+ * Note the behavior change from the old implementation: that one hard-gated on
+ * `isProd`, so it was completely silent in development and you could not tell
+ * whether tracking worked until you shipped. Self-hosting removes the reason for
+ * that gate — your dev traffic goes to your own database.
  */
 
-'use client';
+import { ReactNode, useEffect, useMemo } from 'react';
 
-import { ReactNode } from 'react';
+import {
+  AnalyticsProvider as BaseAnalyticsProvider,
+  PageviewTracker,
+  djangocfg,
+  ga4,
+  useAnalyticsClient,
+  type AnalyticsTransport,
+} from '@djangocfg/analytics';
+import { setAnalyticsSink, useAuth } from '@djangocfg/api/auth';
+import { useLocaleOptional } from '@djangocfg/i18n';
 
-import { useAnalytics } from './useAnalytics';
+import { usePathnameWithoutLocale } from '../../hooks/usePathnameWithoutLocale';
 
 interface AnalyticsProviderProps {
   children: ReactNode;
-  /** Google Analytics tracking ID (optional if using AppContext) */
+  /** GA4 measurement ID. Omit to run first-party only. */
   trackingId?: string;
+  /**
+   * Templated route (`/[locale]/blog/[slug]`). Next does not expose it to client
+   * components, so an app can pass it for exact grouping. Optional: without it
+   * the locale-stripped pathname is used, which already prevents the worst
+   * failure (see below).
+   */
+  route?: string;
+}
+
+export function AnalyticsProvider({
+  children,
+  trackingId,
+  route,
+}: AnalyticsProviderProps) {
+  const { user } = useAuth();
+
+  // The locale is READ here rather than passed in by every app.
+  //
+  // It matters: without it, `/en/pricing` and `/ru/pricing` are counted as two
+  // different pages, and the top-pages report is meaningless on a
+  // locale-prefixed site. `useLocaleOptional` returns undefined (rather than
+  // throwing) in an app with no i18n, so this stays safe for both.
+  // `?? undefined` is load-bearing: useLocaleOptional returns `null` with no
+  // I18nProvider, and this package builds with `strict: false`, so a raw null
+  // would sail through the `locale?: string` prop and end up in the payload.
+  const locale = useLocaleOptional() ?? undefined;
+
+  // The locale-stripped path is the fallback "route". Not as good as the real
+  // templated route (`/blog/[slug]` still fragments per slug), but it fixes the
+  // locale split with zero work from the app.
+  const strippedPath = usePathnameWithoutLocale(locale);
+
+  const transports = useMemo<AnalyticsTransport[]>(() => {
+    const list: AnalyticsTransport[] = [djangocfg()];
+    if (trackingId) list.push(ga4({ trackingId }));
+    return list;
+  }, [trackingId]);
+
+  return (
+    <BaseAnalyticsProvider
+      transports={transports}
+      // An opaque id — never an email. Goes back to null on logout, or the next
+      // anonymous session would inherit it.
+      userId={user?.id != null ? String(user.id) : null}
+    >
+      <AuthEventBridge />
+      <PageviewTracker route={route ?? strippedPath} locale={locale} />
+      {children}
+    </BaseAnalyticsProvider>
+  );
 }
 
 /**
- * Analytics Provider that initializes tracking
- * Automatically:
- * - Initializes GA4 with tracking ID from prop or config
- * - Sets user ID when authenticated
- * - Tracks page views on route changes
+ * Routes `@djangocfg/api`'s auth events into the analytics client.
+ *
+ * `api` cannot import `analytics` (analytics reads auth state — that would be a
+ * cycle), so `api` exposes a sink and we install the real implementation here,
+ * where both packages are already in scope.
+ *
+ * Without this bridge, every auth event — AUTH_LOGIN_SUCCESS, AUTH_OAUTH_FAIL,
+ * AUTH_SESSION_EXPIRED — hits api's built-in no-op stub and is silently
+ * discarded. That was the status quo before this package existed.
  */
-export function AnalyticsProvider({ children, trackingId }: AnalyticsProviderProps) {
-  // If trackingId is provided as prop, use it directly
-  // Otherwise, useAnalytics will try to get it from AppContext
-  useAnalytics(trackingId);
-  return <>{children}</>;
+function AuthEventBridge() {
+  const client = useAnalyticsClient();
+
+  useEffect(() => {
+    if (!client) return;
+
+    setAnalyticsSink({
+      event: (name, params) => client.trackEvent(name, params),
+      setUser: (userId) => client.identify(userId),
+    });
+
+    // Uninstall on unmount, or a torn-down client keeps receiving events.
+    return () => setAnalyticsSink(null);
+  }, [client]);
+
+  return null;
 }
 
 export default AnalyticsProvider;

package/src/snippets/Analytics/index.ts

@@ -1,11 +1,19 @@
 /**
- * Analytics Module
+ * Analytics — MOVED to `@djangocfg/analytics`.
  *
- * Google Analytics integration with react-ga4
+ * This is a back-compat re-export so existing imports keep working. New code
+ * should import from `@djangocfg/analytics` directly.
+ *
+ * Why it moved: this module used to own its own route listener. Adding a second
+ * destination (the self-hosted first-party backend) would have meant a SECOND
+ * listener, double-firing pageviews with a drifting event taxonomy. The new
+ * package has one listener that fans out to N transports — GA4 is now just one
+ * of them, alongside the django-cfg ingest endpoint.
  */
 
-export { useAnalytics, Analytics } from './useAnalytics';
+export { AnalyticsCategory, AnalyticsEvent, useAnalytics } from '@djangocfg/analytics';
+
+export type { AnalyticsCategoryType, AnalyticsEventType } from '@djangocfg/analytics';
+
 export { AnalyticsProvider } from './AnalyticsProvider';
-export { AnalyticsEvent, AnalyticsCategory } from './events';
-export type { AnalyticsEventType, AnalyticsCategoryType } from './events';
 export type { AnalyticsConfig } from './types';

package/src/snippets/Analytics/events.ts

@@ -1,60 +0,0 @@
-/**
- * Analytics Events Constants
- *
- * Predefined event names and categories for consistent tracking
- * across the entire application.
- */
-
-/**
- * Event Categories
- */
-export const AnalyticsCategory = {
-  AUTH: 'auth',
-  ERROR: 'error',
-  NAVIGATION: 'navigation',
-  ENGAGEMENT: 'engagement',
-  USER: 'user',
-} as const;
-
-/**
- * Predefined Event Names
- */
-export const AnalyticsEvent = {
-  // Auth Events
-  AUTH_OTP_REQUEST: 'auth_otp_request',
-  AUTH_OTP_VERIFY_SUCCESS: 'auth_otp_verify_success',
-  AUTH_OTP_VERIFY_FAIL: 'auth_otp_verify_fail',
-  AUTH_LOGIN_SUCCESS: 'auth_login_success',
-  AUTH_LOGOUT: 'auth_logout',
-  AUTH_SESSION_EXPIRED: 'auth_session_expired',
-  AUTH_TOKEN_REFRESH: 'auth_token_refresh',
-  AUTH_TOKEN_REFRESH_FAIL: 'auth_token_refresh_fail',
-
-  // OAuth Events
-  AUTH_OAUTH_START: 'auth_oauth_start',
-  AUTH_OAUTH_SUCCESS: 'auth_oauth_success',
-  AUTH_OAUTH_FAIL: 'auth_oauth_fail',
-
-  // Error Events
-  ERROR_BOUNDARY: 'error_boundary',
-  ERROR_API: 'error_api',
-  ERROR_VALIDATION: 'error_validation',
-  ERROR_NETWORK: 'error_network',
-
-  // Navigation Events
-  NAV_ADMIN_ENTER: 'nav_admin_enter',
-  NAV_DASHBOARD_ENTER: 'nav_dashboard_enter',
-  NAV_PAGE_VIEW: 'nav_page_view',
-
-  // Engagement Events
-  THEME_CHANGE: 'theme_change',
-  SIDEBAR_TOGGLE: 'sidebar_toggle',
-  MOBILE_MENU_OPEN: 'mobile_menu_open',
-
-  // User Events
-  USER_PROFILE_VIEW: 'user_profile_view',
-  USER_PROFILE_UPDATE: 'user_profile_update',
-} as const;
-
-export type AnalyticsCategoryType = typeof AnalyticsCategory[keyof typeof AnalyticsCategory];
-export type AnalyticsEventType = typeof AnalyticsEvent[keyof typeof AnalyticsEvent];

package/src/snippets/Analytics/useAnalytics.ts

@@ -1,142 +0,0 @@
-/**
- * useAnalytics Hook
- *
- * Provides Google Analytics tracking via react-ga4
- * Automatically tracks page views on route changes
- * Only works in production mode
- */
-
-'use client';
-
-import { usePathname } from 'next/navigation';
-import { useEffect } from 'react';
-import ReactGA from 'react-ga4';
-
-import { useAuth } from '@djangocfg/api/auth';
-
-// Check if we're in production
-import { isProd as isProduction } from '@djangocfg/ui-core/lib';
-
-// Tracking state
-let isInitialized = false;
-// @ts-ignore reserved for future use (e.g., analytics debugging)
-let _currentTrackingId: string | undefined;
-
-/**
- * Analytics utility object for standalone usage (outside React components)
- *
- * @example
- * ```ts
- * import { Analytics } from '@djangocfg/layouts';
- *
- * // In an event handler or utility function
- * Analytics.event('button_click', { category: 'engagement', label: 'signup' });
- * ```
- */
-export const Analytics = {
-  /**
-   * Initialize Google Analytics (called automatically by useAnalytics hook)
-   */
-  init: (trackingId: string) => {
-    if (!isProduction || !trackingId || isInitialized) return;
-    ReactGA.initialize(trackingId);
-    isInitialized = true;
-    _currentTrackingId = trackingId;
-  },
-
-  /**
-   * Check if Analytics is enabled and initialized
-   */
-  isEnabled: () => isProduction && isInitialized,
-
-  /**
-   * Track a page view
-   */
-  pageview: (path: string) => {
-    if (!Analytics.isEnabled()) return;
-    ReactGA.send({ hitType: 'pageview', page: path });
-  },
-
-  /**
-   * Track a custom event
-   * @param name - Event name (action)
-   * @param params - Optional event parameters
-   */
-  event: (name: string, params: Record<string, any> = {}) => {
-    if (!Analytics.isEnabled()) return;
-    ReactGA.event(name, params);
-  },
-
-  /**
-   * Set user ID for tracking
-   */
-  setUser: (userId: string) => {
-    if (!Analytics.isEnabled()) return;
-    ReactGA.set({ user_id: userId });
-  },
-
-  /**
-   * Set custom dimensions/metrics
-   */
-  set: (fieldsObject: Record<string, any>) => {
-    if (!Analytics.isEnabled()) return;
-    ReactGA.set(fieldsObject);
-  },
-};
-
-/**
- * Hook for Google Analytics tracking via react-ga4
- *
- * Automatically initializes GA and tracks page views on route changes
- * Only works in production mode (NODE_ENV === 'production')
- *
- * @example
- * ```tsx
- * // Just call the hook - it auto-tracks pageviews
- * useAnalytics();
- *
- * // Or use the returned methods for custom tracking
- * const { event, isEnabled } = useAnalytics();
- * event('button_click', { category: 'engagement', label: 'signup' });
- * ```
- */
-export function useAnalytics(trackingIdProp?: string) {
-  const pathname = usePathname();
-  const { user, isAuthenticated } = useAuth();
-
-  // Use trackingId from prop (passed from AppLayout)
-  const trackingId = trackingIdProp;
-  const isEnabled = isProduction && Boolean(trackingId);
-
-  // Initialize GA4
-  useEffect(() => {
-    if (!isEnabled || !trackingId) return;
-    Analytics.init(trackingId);
-  }, [isEnabled, trackingId]);
-
-  // Auto-set user ID when authenticated
-  useEffect(() => {
-    if (!isEnabled || !isAuthenticated || !user?.id) return;
-    Analytics.setUser(String(user.id));
-  }, [isEnabled, isAuthenticated, user?.id]);
-
-  // Auto-track page views on route change (App Router)
-  useEffect(() => {
-    if (!isEnabled || typeof window === 'undefined') return;
-
-    // Track page view when pathname changes
-    const url = pathname + (window.location.search || '');
-    Analytics.pageview(url);
-  }, [pathname, isEnabled]);
-
-  return {
-    isEnabled,
-    trackingId,
-    pageview: Analytics.pageview,
-    event: Analytics.event,
-    setUser: Analytics.setUser,
-    set: Analytics.set,
-  };
-}
-
-export default useAnalytics;