@jwiedeman/gtm-kit-react 1.1.6 → 1.2.1

package/dist/index.d.cts

@@ -1,14 +1,56 @@
-import { PropsWithChildren, JSX } from 'react';
+import { PropsWithChildren, JSX, ReactNode, ErrorInfo, Component } from 'react';
 import { CreateGtmClientOptions, GtmClient, DataLayerValue, ConsentState, ConsentRegionOptions, ScriptLoadState } from '@jwiedeman/gtm-kit';
 
+/**
+ * Check if code is running in a server-side rendering environment.
+ * Returns true if window is undefined (Node.js/SSR), false in browser.
+ */
+declare const isSsr: () => boolean;
+/**
+ * Hook that returns false during SSR and initial hydration, then true after hydration completes.
+ * Use this to prevent hydration mismatches when rendering GTM-dependent content.
+ *
+ * @example
+ * ```tsx
+ * const isHydrated = useHydrated();
+ *
+ * // Safe: won't cause hydration mismatch
+ * return isHydrated ? <DynamicContent /> : <StaticPlaceholder />;
+ * ```
+ */
+declare const useHydrated: () => boolean;
 interface GtmProviderProps extends PropsWithChildren {
     config: CreateGtmClientOptions;
+    /**
+     * Callback executed before GTM initialization.
+     * Use this to set consent defaults.
+     *
+     * @example
+     * ```tsx
+     * <GtmProvider
+     *   config={{ containers: 'GTM-XXXXXX' }}
+     *   onBeforeInit={(client) => {
+     *     client.setConsentDefaults({
+     *       ad_storage: 'denied',
+     *       analytics_storage: 'denied'
+     *     });
+     *   }}
+     * >
+     * ```
+     */
+    onBeforeInit?: (client: GtmClient) => void;
+    /**
+     * Callback executed after GTM initialization.
+     */
+    onAfterInit?: (client: GtmClient) => void;
 }
 interface GtmContextValue {
     client: GtmClient;
     push: (value: DataLayerValue) => void;
     setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;
     updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;
+    /** Synchronously check if all GTM scripts have finished loading */
+    isReady: () => boolean;
     whenReady: () => Promise<ScriptLoadState[]>;
     onReady: (callback: (state: ScriptLoadState[]) => void) => () => void;
 }
@@ -16,11 +58,272 @@ interface GtmConsentApi {
     setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;
     updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;
 }
-declare const GtmProvider: ({ config, children }: GtmProviderProps) => JSX.Element;
+/**
+ * GTM Provider component that initializes Google Tag Manager for your React app.
+ *
+ * ## SSR/Hydration Behavior
+ *
+ * This provider is SSR-safe and handles hydration correctly:
+ * - **Server**: No GTM initialization occurs (no window/document access)
+ * - **Client Hydration**: GTM initializes only after hydration via useEffect
+ * - **No Hydration Mismatch**: Provider renders the same on server and client
+ *
+ * ## Usage with SSR Frameworks
+ *
+ * ```tsx
+ * // Next.js, Remix, etc.
+ * export default function App({ children }) {
+ *   return (
+ *     <GtmProvider config={{ containers: 'GTM-XXXXXX' }}>
+ *       {children}
+ *     </GtmProvider>
+ *   );
+ * }
+ * ```
+ *
+ * ## Preventing Hydration Mismatches
+ *
+ * If you render different content based on GTM state, use `useHydrated`:
+ *
+ * ```tsx
+ * const isHydrated = useHydrated();
+ * const isGtmReady = useGtmInitialized();
+ *
+ * // Safe: both server and client initially render the placeholder
+ * if (!isHydrated) return <Placeholder />;
+ * return isGtmReady ? <TrackedContent /> : <LoadingContent />;
+ * ```
+ */
+declare const GtmProvider: ({ config, children, onBeforeInit, onAfterInit }: GtmProviderProps) => JSX.Element;
+/**
+ * Hook to access the full GTM context. Throws if used outside GtmProvider.
+ *
+ * For most use cases, prefer the specific hooks:
+ * - `useGtmPush()` - Push events to dataLayer
+ * - `useGtmConsent()` - Manage consent state
+ * - `useGtmClient()` - Access the raw GTM client
+ *
+ * @throws Error if called outside of GtmProvider
+ *
+ * @example
+ * ```tsx
+ * const { push, client, isReady, whenReady } = useGtm();
+ * ```
+ */
 declare const useGtm: () => GtmContextValue;
+/**
+ * Hook to check if GtmProvider is present without throwing.
+ *
+ * Useful for components that may be rendered before the provider mounts,
+ * or for optional GTM integration.
+ *
+ * @returns `true` if inside GtmProvider, `false` otherwise
+ *
+ * @example
+ * ```tsx
+ * const hasProvider = useIsGtmProviderPresent();
+ *
+ * const handleClick = () => {
+ *   if (hasProvider) {
+ *     // Safe to use GTM hooks
+ *   }
+ * };
+ * ```
+ */
+declare const useIsGtmProviderPresent: () => boolean;
+/**
+ * Hook to access the raw GTM client instance.
+ *
+ * @throws Error if called outside of GtmProvider
+ * @returns The GTM client instance
+ *
+ * @example
+ * ```tsx
+ * const client = useGtmClient();
+ *
+ * // Access low-level APIs
+ * const diagnostics = client.getDiagnostics();
+ * ```
+ */
 declare const useGtmClient: () => GtmClient;
+/**
+ * Hook to get the push function for sending events to the dataLayer.
+ *
+ * This is the most commonly used hook for tracking events.
+ *
+ * @throws Error if called outside of GtmProvider
+ * @returns Function to push values to the dataLayer
+ *
+ * @example
+ * ```tsx
+ * const push = useGtmPush();
+ *
+ * const handleAddToCart = (product) => {
+ *   push({
+ *     event: 'add_to_cart',
+ *     ecommerce: {
+ *       items: [{ item_id: product.id, item_name: product.name }]
+ *     }
+ *   });
+ * };
+ * ```
+ */
 declare const useGtmPush: () => ((value: DataLayerValue) => void);
+/**
+ * Hook to access consent management functions.
+ *
+ * @throws Error if called outside of GtmProvider
+ * @returns Object with `setConsentDefaults` and `updateConsent` functions
+ *
+ * @example
+ * ```tsx
+ * const { updateConsent } = useGtmConsent();
+ *
+ * const handleAcceptCookies = () => {
+ *   updateConsent({
+ *     ad_storage: 'granted',
+ *     analytics_storage: 'granted'
+ *   });
+ * };
+ * ```
+ */
 declare const useGtmConsent: () => GtmConsentApi;
+/**
+ * Hook that returns the `whenReady` promise function.
+ *
+ * **When to use**: When you need to await GTM script loading before taking an action.
+ * The returned function returns a Promise that resolves when scripts finish loading.
+ *
+ * **Comparison of GTM readiness hooks:**
+ * | Hook | Returns | Re-renders | Use Case |
+ * |------|---------|------------|----------|
+ * | `useGtmReady()` | `() => Promise` | No | Await in event handlers |
+ * | `useIsGtmReady()` | `() => boolean` | No | Synchronous checks in callbacks |
+ * | `useGtmInitialized()` | `boolean` | Yes | Conditional rendering |
+ *
+ * @returns Function that returns a Promise resolving to script load states
+ *
+ * @example
+ * ```tsx
+ * const whenReady = useGtmReady();
+ *
+ * const handleClick = async () => {
+ *   const states = await whenReady();
+ *   if (states.every(s => s.status === 'loaded')) {
+ *     // Safe to rely on GTM being fully loaded
+ *   }
+ * };
+ * ```
+ */
 declare const useGtmReady: () => (() => Promise<ScriptLoadState[]>);
+/**
+ * Hook that returns a function to synchronously check if GTM is ready.
+ *
+ * **When to use**: When you need to check readiness without triggering re-renders,
+ * typically in event handlers or callbacks.
+ *
+ * **Comparison of GTM readiness hooks:**
+ * | Hook | Returns | Re-renders | Use Case |
+ * |------|---------|------------|----------|
+ * | `useGtmReady()` | `() => Promise` | No | Await in event handlers |
+ * | `useIsGtmReady()` | `() => boolean` | No | Synchronous checks in callbacks |
+ * | `useGtmInitialized()` | `boolean` | Yes | Conditional rendering |
+ *
+ * @returns Function that returns `true` if scripts loaded, `false` if still loading
+ *
+ * @example
+ * ```tsx
+ * const checkReady = useIsGtmReady();
+ *
+ * const handleSubmit = () => {
+ *   if (checkReady()) {
+ *     // GTM is ready, proceed with tracking
+ *     push({ event: 'form_submit' });
+ *   }
+ * };
+ * ```
+ */
+declare const useIsGtmReady: () => (() => boolean);
+/**
+ * Reactive hook that returns `true` when GTM scripts have finished loading.
+ *
+ * **When to use**: When you need to conditionally render UI based on GTM readiness.
+ * This hook triggers a re-render when the state changes.
+ *
+ * **Comparison of GTM readiness hooks:**
+ * | Hook | Returns | Re-renders | Use Case |
+ * |------|---------|------------|----------|
+ * | `useGtmReady()` | `() => Promise` | No | Await in event handlers |
+ * | `useIsGtmReady()` | `() => boolean` | No | Synchronous checks in callbacks |
+ * | `useGtmInitialized()` | `boolean` | Yes | Conditional rendering |
+ *
+ * @returns `true` if GTM is initialized, `false` otherwise (reactive)
+ *
+ * @example
+ * ```tsx
+ * const isInitialized = useGtmInitialized();
+ *
+ * if (!isInitialized) {
+ *   return <LoadingSpinner />;
+ * }
+ *
+ * return <AnalyticsDashboard />;
+ * ```
+ */
+declare const useGtmInitialized: () => boolean;
+/**
+ * Result from the useGtmError hook.
+ */
+interface GtmErrorState {
+    /** Whether any scripts failed to load */
+    hasError: boolean;
+    /** Array of failed script states (status 'failed' or 'partial') */
+    failedScripts: ScriptLoadState[];
+    /** Convenience getter for the first error message, if any */
+    errorMessage: string | null;
+}
+/**
+ * Hook to capture GTM script load errors.
+ * Returns reactive state that updates when scripts fail to load.
+ *
+ * @example
+ * ```tsx
+ * const { hasError, failedScripts, errorMessage } = useGtmError();
+ *
+ * if (hasError) {
+ *   console.error('GTM failed to load:', errorMessage);
+ *   // Optionally show fallback UI or retry logic
+ * }
+ * ```
+ */
+declare const useGtmError: () => GtmErrorState;
+/**
+ * Props for GtmErrorBoundary component.
+ */
+interface GtmErrorBoundaryProps {
+    children: ReactNode;
+    /** Fallback UI to render when an error occurs */
+    fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+    /** Callback invoked when an error is caught */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+    /** Whether to log errors to console (default: true in development) */
+    logErrors?: boolean;
+}
+interface GtmErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Error boundary component for GTM provider.
+ * Catches errors during GTM initialization and renders a fallback UI.
+ * Analytics and tracking will be disabled when an error occurs.
+ */
+declare class GtmErrorBoundary extends Component<GtmErrorBoundaryProps, GtmErrorBoundaryState> {
+    constructor(props: GtmErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): GtmErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    reset: () => void;
+    render(): ReactNode;
+}
 
-export { GtmConsentApi, GtmContextValue, GtmProvider, GtmProviderProps, useGtm, useGtmClient, useGtmConsent, useGtmPush, useGtmReady };
+export { GtmConsentApi, GtmContextValue, GtmErrorBoundary, GtmErrorBoundaryProps, GtmErrorState, GtmProvider, GtmProviderProps, isSsr, useGtm, useGtmClient, useGtmConsent, useGtmError, useGtmInitialized, useGtmPush, useGtmReady, useHydrated, useIsGtmProviderPresent, useIsGtmReady };

package/dist/index.d.ts

@@ -1,14 +1,56 @@
-import { PropsWithChildren, JSX } from 'react';
+import { PropsWithChildren, JSX, ReactNode, ErrorInfo, Component } from 'react';
 import { CreateGtmClientOptions, GtmClient, DataLayerValue, ConsentState, ConsentRegionOptions, ScriptLoadState } from '@jwiedeman/gtm-kit';
 
+/**
+ * Check if code is running in a server-side rendering environment.
+ * Returns true if window is undefined (Node.js/SSR), false in browser.
+ */
+declare const isSsr: () => boolean;
+/**
+ * Hook that returns false during SSR and initial hydration, then true after hydration completes.
+ * Use this to prevent hydration mismatches when rendering GTM-dependent content.
+ *
+ * @example
+ * ```tsx
+ * const isHydrated = useHydrated();
+ *
+ * // Safe: won't cause hydration mismatch
+ * return isHydrated ? <DynamicContent /> : <StaticPlaceholder />;
+ * ```
+ */
+declare const useHydrated: () => boolean;
 interface GtmProviderProps extends PropsWithChildren {
     config: CreateGtmClientOptions;
+    /**
+     * Callback executed before GTM initialization.
+     * Use this to set consent defaults.
+     *
+     * @example
+     * ```tsx
+     * <GtmProvider
+     *   config={{ containers: 'GTM-XXXXXX' }}
+     *   onBeforeInit={(client) => {
+     *     client.setConsentDefaults({
+     *       ad_storage: 'denied',
+     *       analytics_storage: 'denied'
+     *     });
+     *   }}
+     * >
+     * ```
+     */
+    onBeforeInit?: (client: GtmClient) => void;
+    /**
+     * Callback executed after GTM initialization.
+     */
+    onAfterInit?: (client: GtmClient) => void;
 }
 interface GtmContextValue {
     client: GtmClient;
     push: (value: DataLayerValue) => void;
     setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;
     updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;
+    /** Synchronously check if all GTM scripts have finished loading */
+    isReady: () => boolean;
     whenReady: () => Promise<ScriptLoadState[]>;
     onReady: (callback: (state: ScriptLoadState[]) => void) => () => void;
 }
@@ -16,11 +58,272 @@ interface GtmConsentApi {
     setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;
     updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;
 }
-declare const GtmProvider: ({ config, children }: GtmProviderProps) => JSX.Element;
+/**
+ * GTM Provider component that initializes Google Tag Manager for your React app.
+ *
+ * ## SSR/Hydration Behavior
+ *
+ * This provider is SSR-safe and handles hydration correctly:
+ * - **Server**: No GTM initialization occurs (no window/document access)
+ * - **Client Hydration**: GTM initializes only after hydration via useEffect
+ * - **No Hydration Mismatch**: Provider renders the same on server and client
+ *
+ * ## Usage with SSR Frameworks
+ *
+ * ```tsx
+ * // Next.js, Remix, etc.
+ * export default function App({ children }) {
+ *   return (
+ *     <GtmProvider config={{ containers: 'GTM-XXXXXX' }}>
+ *       {children}
+ *     </GtmProvider>
+ *   );
+ * }
+ * ```
+ *
+ * ## Preventing Hydration Mismatches
+ *
+ * If you render different content based on GTM state, use `useHydrated`:
+ *
+ * ```tsx
+ * const isHydrated = useHydrated();
+ * const isGtmReady = useGtmInitialized();
+ *
+ * // Safe: both server and client initially render the placeholder
+ * if (!isHydrated) return <Placeholder />;
+ * return isGtmReady ? <TrackedContent /> : <LoadingContent />;
+ * ```
+ */
+declare const GtmProvider: ({ config, children, onBeforeInit, onAfterInit }: GtmProviderProps) => JSX.Element;
+/**
+ * Hook to access the full GTM context. Throws if used outside GtmProvider.
+ *
+ * For most use cases, prefer the specific hooks:
+ * - `useGtmPush()` - Push events to dataLayer
+ * - `useGtmConsent()` - Manage consent state
+ * - `useGtmClient()` - Access the raw GTM client
+ *
+ * @throws Error if called outside of GtmProvider
+ *
+ * @example
+ * ```tsx
+ * const { push, client, isReady, whenReady } = useGtm();
+ * ```
+ */
 declare const useGtm: () => GtmContextValue;
+/**
+ * Hook to check if GtmProvider is present without throwing.
+ *
+ * Useful for components that may be rendered before the provider mounts,
+ * or for optional GTM integration.
+ *
+ * @returns `true` if inside GtmProvider, `false` otherwise
+ *
+ * @example
+ * ```tsx
+ * const hasProvider = useIsGtmProviderPresent();
+ *
+ * const handleClick = () => {
+ *   if (hasProvider) {
+ *     // Safe to use GTM hooks
+ *   }
+ * };
+ * ```
+ */
+declare const useIsGtmProviderPresent: () => boolean;
+/**
+ * Hook to access the raw GTM client instance.
+ *
+ * @throws Error if called outside of GtmProvider
+ * @returns The GTM client instance
+ *
+ * @example
+ * ```tsx
+ * const client = useGtmClient();
+ *
+ * // Access low-level APIs
+ * const diagnostics = client.getDiagnostics();
+ * ```
+ */
 declare const useGtmClient: () => GtmClient;
+/**
+ * Hook to get the push function for sending events to the dataLayer.
+ *
+ * This is the most commonly used hook for tracking events.
+ *
+ * @throws Error if called outside of GtmProvider
+ * @returns Function to push values to the dataLayer
+ *
+ * @example
+ * ```tsx
+ * const push = useGtmPush();
+ *
+ * const handleAddToCart = (product) => {
+ *   push({
+ *     event: 'add_to_cart',
+ *     ecommerce: {
+ *       items: [{ item_id: product.id, item_name: product.name }]
+ *     }
+ *   });
+ * };
+ * ```
+ */
 declare const useGtmPush: () => ((value: DataLayerValue) => void);
+/**
+ * Hook to access consent management functions.
+ *
+ * @throws Error if called outside of GtmProvider
+ * @returns Object with `setConsentDefaults` and `updateConsent` functions
+ *
+ * @example
+ * ```tsx
+ * const { updateConsent } = useGtmConsent();
+ *
+ * const handleAcceptCookies = () => {
+ *   updateConsent({
+ *     ad_storage: 'granted',
+ *     analytics_storage: 'granted'
+ *   });
+ * };
+ * ```
+ */
 declare const useGtmConsent: () => GtmConsentApi;
+/**
+ * Hook that returns the `whenReady` promise function.
+ *
+ * **When to use**: When you need to await GTM script loading before taking an action.
+ * The returned function returns a Promise that resolves when scripts finish loading.
+ *
+ * **Comparison of GTM readiness hooks:**
+ * | Hook | Returns | Re-renders | Use Case |
+ * |------|---------|------------|----------|
+ * | `useGtmReady()` | `() => Promise` | No | Await in event handlers |
+ * | `useIsGtmReady()` | `() => boolean` | No | Synchronous checks in callbacks |
+ * | `useGtmInitialized()` | `boolean` | Yes | Conditional rendering |
+ *
+ * @returns Function that returns a Promise resolving to script load states
+ *
+ * @example
+ * ```tsx
+ * const whenReady = useGtmReady();
+ *
+ * const handleClick = async () => {
+ *   const states = await whenReady();
+ *   if (states.every(s => s.status === 'loaded')) {
+ *     // Safe to rely on GTM being fully loaded
+ *   }
+ * };
+ * ```
+ */
 declare const useGtmReady: () => (() => Promise<ScriptLoadState[]>);
+/**
+ * Hook that returns a function to synchronously check if GTM is ready.
+ *
+ * **When to use**: When you need to check readiness without triggering re-renders,
+ * typically in event handlers or callbacks.
+ *
+ * **Comparison of GTM readiness hooks:**
+ * | Hook | Returns | Re-renders | Use Case |
+ * |------|---------|------------|----------|
+ * | `useGtmReady()` | `() => Promise` | No | Await in event handlers |
+ * | `useIsGtmReady()` | `() => boolean` | No | Synchronous checks in callbacks |
+ * | `useGtmInitialized()` | `boolean` | Yes | Conditional rendering |
+ *
+ * @returns Function that returns `true` if scripts loaded, `false` if still loading
+ *
+ * @example
+ * ```tsx
+ * const checkReady = useIsGtmReady();
+ *
+ * const handleSubmit = () => {
+ *   if (checkReady()) {
+ *     // GTM is ready, proceed with tracking
+ *     push({ event: 'form_submit' });
+ *   }
+ * };
+ * ```
+ */
+declare const useIsGtmReady: () => (() => boolean);
+/**
+ * Reactive hook that returns `true` when GTM scripts have finished loading.
+ *
+ * **When to use**: When you need to conditionally render UI based on GTM readiness.
+ * This hook triggers a re-render when the state changes.
+ *
+ * **Comparison of GTM readiness hooks:**
+ * | Hook | Returns | Re-renders | Use Case |
+ * |------|---------|------------|----------|
+ * | `useGtmReady()` | `() => Promise` | No | Await in event handlers |
+ * | `useIsGtmReady()` | `() => boolean` | No | Synchronous checks in callbacks |
+ * | `useGtmInitialized()` | `boolean` | Yes | Conditional rendering |
+ *
+ * @returns `true` if GTM is initialized, `false` otherwise (reactive)
+ *
+ * @example
+ * ```tsx
+ * const isInitialized = useGtmInitialized();
+ *
+ * if (!isInitialized) {
+ *   return <LoadingSpinner />;
+ * }
+ *
+ * return <AnalyticsDashboard />;
+ * ```
+ */
+declare const useGtmInitialized: () => boolean;
+/**
+ * Result from the useGtmError hook.
+ */
+interface GtmErrorState {
+    /** Whether any scripts failed to load */
+    hasError: boolean;
+    /** Array of failed script states (status 'failed' or 'partial') */
+    failedScripts: ScriptLoadState[];
+    /** Convenience getter for the first error message, if any */
+    errorMessage: string | null;
+}
+/**
+ * Hook to capture GTM script load errors.
+ * Returns reactive state that updates when scripts fail to load.
+ *
+ * @example
+ * ```tsx
+ * const { hasError, failedScripts, errorMessage } = useGtmError();
+ *
+ * if (hasError) {
+ *   console.error('GTM failed to load:', errorMessage);
+ *   // Optionally show fallback UI or retry logic
+ * }
+ * ```
+ */
+declare const useGtmError: () => GtmErrorState;
+/**
+ * Props for GtmErrorBoundary component.
+ */
+interface GtmErrorBoundaryProps {
+    children: ReactNode;
+    /** Fallback UI to render when an error occurs */
+    fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+    /** Callback invoked when an error is caught */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+    /** Whether to log errors to console (default: true in development) */
+    logErrors?: boolean;
+}
+interface GtmErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Error boundary component for GTM provider.
+ * Catches errors during GTM initialization and renders a fallback UI.
+ * Analytics and tracking will be disabled when an error occurs.
+ */
+declare class GtmErrorBoundary extends Component<GtmErrorBoundaryProps, GtmErrorBoundaryState> {
+    constructor(props: GtmErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): GtmErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    reset: () => void;
+    render(): ReactNode;
+}
 
-export { GtmConsentApi, GtmContextValue, GtmProvider, GtmProviderProps, useGtm, useGtmClient, useGtmConsent, useGtmPush, useGtmReady };
+export { GtmConsentApi, GtmContextValue, GtmErrorBoundary, GtmErrorBoundaryProps, GtmErrorState, GtmProvider, GtmProviderProps, isSsr, useGtm, useGtmClient, useGtmConsent, useGtmError, useGtmInitialized, useGtmPush, useGtmReady, useHydrated, useIsGtmProviderPresent, useIsGtmReady };