@aranova/tracking-react 0.9.0 → 0.9.1

package/README.md

@@ -176,13 +176,70 @@ npx @aranova/tracking-cli gen          # reads ARANOVA_TRACKING_SECRET_KEY from
 See the full guide: [sales-tracking.md](https://github.com/AranovaIO/aranova_internal/blob/master/docs/tracking-package/sales-tracking.md)
 and the CLI reference: [cli.md](https://github.com/AranovaIO/aranova_internal/blob/master/docs/tracking-package/cli.md).
 
+## Consent UI
+
+The bundled `<ConsentBanner />` renders a non-blocking bottom-docked banner while consent is `pending`, persists the visitor's choice to `localStorage`, and propagates it to Google Consent Mode v2 when gtag is loaded. **Inline-styled** — no Tailwind or CSS imports required at the consumer.
+
+```tsx
+import { ConsentBanner } from '@aranova/tracking-react';
+
+// Drop-in, defaults work everywhere
+<ConsentBanner />
+```
+
+All props are optional:
+
+```tsx
+<ConsentBanner
+  title="Cookies"
+  message="We use cookies to track ad performance."
+  acceptLabel="Sure"
+  declineLabel="No thanks"
+  policyHref="/privacy"
+  policyLabel="Privacy policy"          // default: "Learn more"
+  onAccept={() => track('consent_accepted')}
+  onDecline={() => track('consent_declined')}
+  position="bottom"                      // or "top"
+  theme="light"                          // "light" | "dark" | "auto"
+  className="my-extra-classes"
+  style={{ background: '#fafafa' }}      // wins over the theme defaults
+/>
+```
+
+### Fully custom UI — `useConsent()`
+
+For a bespoke banner, skip the component and drive your own UI with the headless hook:
+
+```tsx
+import { useConsent } from '@aranova/tracking-react';
+
+function CookieBar() {
+  const { state, accept, decline, reset, isPending } = useConsent();
+
+  if (!isPending) {
+    // Footer link: re-open the banner if they change their mind.
+    return <button onClick={reset}>Cookie preferences</button>;
+  }
+  return (
+    <MyBespokeBanner>
+      <button onClick={decline}>No thanks</button>
+      <button onClick={accept}>Sure</button>
+    </MyBespokeBanner>
+  );
+}
+```
+
+The hook handles localStorage persistence, gtag sync, and cross-tab propagation — same machinery the default banner uses. `resetConsent()` is also exported as a standalone for non-component contexts.
+
 ## Exports
 
 - `createTracking()`
 - `TrackingProvider` and scoped `useTracking`
 - `GoogleAdsTracking`
-- `ConsentBanner`
-- `useTrackingParams()`, `useGclid()`, `useConsentState()`
+- `ConsentBanner` + `ConsentBannerProps`
+- Consent hooks: `useConsent()` + `UseConsentResult` (headless); `useConsentState()` (read-only alias)
+- Standalone consent helpers: `getConsentState()`, `setConsentState()`, `resetConsent()`
+- Attribution hooks: `useTrackingParams()`, `useGclid()`
 - `createSalesClient()` (isomorphic sales client — public key writes, secret key reads/CRUD) + money helpers (`toMinor`/`fromMinor`/`formatMoney`)
 - Codegen: [`@aranova/tracking-cli`](https://www.npmjs.com/package/@aranova/tracking-cli) — `gen` typed service unions (devDependency)
 - Event metadata/config types such as `FormSubmitMetadata`, `PhoneClickMetadata`, and `JsonValue`

package/dist/index.d.mts

@@ -1,15 +1,71 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
+import { ReactNode, CSSProperties } from 'react';
 import * as src from 'src';
 import { z } from 'zod';
 
 /**
  * Default non-blocking consent banner.
  *
- * Renders only while consent is `pending`. Accept/decline choices are stored
- * in localStorage and propagated to Google Consent Mode when gtag is loaded.
- */
-declare function ConsentBanner(): react_jsx_runtime.JSX.Element | null;
+ * Renders only while consent is `pending`; collapses to `null` once the
+ * visitor has chosen.
+ *
+ * **Styling is intentionally self-contained** — inline styles, zero CSS
+ * dependencies, no Tailwind required at the consumer. The Tailwind-based
+ * banner shipped before 0.9.1 rendered as transparent in any consumer that
+ * didn't configure their content array to scan
+ * `node_modules/@aranova/tracking-react/dist/**`; this version sidesteps that
+ * class of bug entirely.
+ *
+ * For a fully bespoke banner, skip this component and use {@link useConsent}
+ * directly to drive your own UI.
+ *
+ * @example
+ * // Drop-in default
+ * <ConsentBanner />
+ *
+ * @example
+ * // Customized
+ * <ConsentBanner
+ *   message="We use cookies to learn which ads drive bookings."
+ *   acceptLabel="Sounds good"
+ *   declineLabel="No thanks"
+ *   policyHref="/privacy"
+ *   policyLabel="Privacy policy"
+ *   theme="dark"
+ *   onAccept={() => track('consent_accepted')}
+ *   onDecline={() => track('consent_declined')}
+ * />
+ */
+interface ConsentBannerProps {
+    /** Body text. Defaults to the standard cookies-for-ad-performance message. */
+    message?: ReactNode;
+    /** Optional bold title above the body text. */
+    title?: ReactNode;
+    /** Label for the accept button. Default: `"Accept"`. */
+    acceptLabel?: string;
+    /** Label for the decline button. Default: `"Decline"`. */
+    declineLabel?: string;
+    /** Optional link inline with the message (e.g. to a privacy policy). */
+    policyHref?: string;
+    /** Visible text for {@link policyHref}. Default: `"Learn more"`. */
+    policyLabel?: string;
+    /**
+     * Fires after the consent state is persisted + propagated to gtag. Useful
+     * for emitting your own analytics event on the choice.
+     */
+    onAccept?: () => void;
+    onDecline?: () => void;
+    /** Where the banner docks. Default: `"bottom"`. */
+    position?: 'top' | 'bottom';
+    /**
+     * Visual theme. `"auto"` follows `prefers-color-scheme`. Default: `"light"`.
+     */
+    theme?: 'light' | 'dark' | 'auto';
+    /** Class added to the outer wrapper for additional styling hooks. */
+    className?: string;
+    /** Inline style overrides applied to the outer wrapper after the defaults. */
+    style?: CSSProperties;
+}
+declare function ConsentBanner({ message, title, acceptLabel, declineLabel, policyHref, policyLabel, onAccept, onDecline, position, theme, className, style, }?: ConsentBannerProps): ReactNode;
 
 /**
  * Visitor consent state stored by the SDK.
@@ -187,6 +243,22 @@ declare function getConsentState(): ConsentState;
  * loaded.
  */
 declare function setConsentState(state: GtagConsentValue): void;
+/**
+ * Clear the stored consent choice so the banner re-appears on next render.
+ *
+ * Power a "Cookie preferences" link in a footer so visitors can change their
+ * mind without losing access to your site:
+ *
+ * ```tsx
+ * const { reset } = useConsent();
+ * <button onClick={reset}>Cookie preferences</button>
+ * ```
+ *
+ * Does NOT push an `update` to gtag — there's nothing to update because the
+ * visitor hasn't chosen anything yet. The next `setConsentState()` call will
+ * sync gtag once they re-choose.
+ */
+declare function resetConsent(): void;
 
 interface TrackingContextInput {
     packageName?: string | null;
@@ -1781,8 +1853,46 @@ declare function useTrackingParams(): TrackingParams;
 /**
  * Read the current visitor consent state and update when another tab changes
  * the stored value.
+ *
+ * Prefer {@link useConsent} for new code — it returns the same state plus
+ * the `accept` / `decline` / `reset` actions a custom consent UI needs.
+ * `useConsentState` is kept as a convenience for callers that only need to
+ * read.
  */
 declare function useConsentState(): ConsentState;
+/**
+ * The headless consent surface — state + actions in one hook.
+ *
+ * Build a fully-custom banner without losing the gtag-sync, localStorage
+ * persistence, or cross-tab propagation:
+ *
+ * ```tsx
+ * const { state, accept, decline, reset, isPending } = useConsent();
+ *
+ * if (!isPending) {
+ *   return <button onClick={reset}>Cookie preferences</button>;
+ * }
+ * return (
+ *   <MyBannerStyling>
+ *     <button onClick={decline}>No thanks</button>
+ *     <button onClick={accept}>Sure</button>
+ *   </MyBannerStyling>
+ * );
+ * ```
+ *
+ * The boolean helpers (`isPending` / `isGranted` / `isDenied`) are equivalent
+ * to comparing `state` directly — they're there for readability at call sites.
+ */
+interface UseConsentResult {
+    state: ConsentState;
+    isPending: boolean;
+    isGranted: boolean;
+    isDenied: boolean;
+    accept: () => void;
+    decline: () => void;
+    reset: () => void;
+}
+declare function useConsent(): UseConsentResult;
 
 interface CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
     /**
@@ -1853,4 +1963,4 @@ interface CreateTrackingResult<TRegistry extends TriggerRegistryConfig> {
 }
 declare function createTracking<TRegistry extends TriggerRegistryConfig>(options: CreateTrackingOptions<TRegistry>): CreateTrackingResult<TRegistry>;
 
-export { AranovaApiError, type AutomaticEventName, ConsentBanner, type ConsentState, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, type EventConfig, type EventMetadata, type EventName, type FormStartConfig, type FormStartMetadata, type FormSubmitConfig, type FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, type JsonValue, type ManualEventName, type MultiPageSessionConfig, type MultiPageSessionMetadata, type PageViewConfig, type PageViewMetadata, type PhoneClickConfig, type PhoneClickMetadata, type PublicServiceItem, type RegisteredAutomaticEvents, type RegisteredManualEvents, type Sale, type SaleCursorPage, type SaleInput, type SaleItem, type SaleItemInput, type SaleListPage, type SaleListQuery, type SaleUpdateInput, type SalesClient, type SalesClientConfig, type SalesTransportConfig, type ScrollDepthConfig, type ScrollDepthMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, type SupportedCurrency, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackingClient, type TrackingClientContext, type TrackingEventCreatePayload, type TrackingInitConfig, type TrackingInstallSurface, type TrackingParams, type TrackingProviderProps, type TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, captureTrackingParamsFromLocation, createSalesClient, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, fetchServices, formatMoney, fromMinor, getConsentState, setConsentState, toMinor, useConsentState, useGclid, useTrackingParams };
+export { AranovaApiError, type AutomaticEventName, ConsentBanner, type ConsentBannerProps, type ConsentState, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, type EventConfig, type EventMetadata, type EventName, type FormStartConfig, type FormStartMetadata, type FormSubmitConfig, type FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, type JsonValue, type ManualEventName, type MultiPageSessionConfig, type MultiPageSessionMetadata, type PageViewConfig, type PageViewMetadata, type PhoneClickConfig, type PhoneClickMetadata, type PublicServiceItem, type RegisteredAutomaticEvents, type RegisteredManualEvents, type Sale, type SaleCursorPage, type SaleInput, type SaleItem, type SaleItemInput, type SaleListPage, type SaleListQuery, type SaleUpdateInput, type SalesClient, type SalesClientConfig, type SalesTransportConfig, type ScrollDepthConfig, type ScrollDepthMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, type SupportedCurrency, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackingClient, type TrackingClientContext, type TrackingEventCreatePayload, type TrackingInitConfig, type TrackingInstallSurface, type TrackingParams, type TrackingProviderProps, type TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, type UseConsentResult, captureTrackingParamsFromLocation, createSalesClient, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, fetchServices, formatMoney, fromMinor, getConsentState, resetConsent, setConsentState, toMinor, useConsent, useConsentState, useGclid, useTrackingParams };

package/dist/index.d.ts

@@ -1,15 +1,71 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
+import { ReactNode, CSSProperties } from 'react';
 import * as src from 'src';
 import { z } from 'zod';
 
 /**
  * Default non-blocking consent banner.
  *
- * Renders only while consent is `pending`. Accept/decline choices are stored
- * in localStorage and propagated to Google Consent Mode when gtag is loaded.
- */
-declare function ConsentBanner(): react_jsx_runtime.JSX.Element | null;
+ * Renders only while consent is `pending`; collapses to `null` once the
+ * visitor has chosen.
+ *
+ * **Styling is intentionally self-contained** — inline styles, zero CSS
+ * dependencies, no Tailwind required at the consumer. The Tailwind-based
+ * banner shipped before 0.9.1 rendered as transparent in any consumer that
+ * didn't configure their content array to scan
+ * `node_modules/@aranova/tracking-react/dist/**`; this version sidesteps that
+ * class of bug entirely.
+ *
+ * For a fully bespoke banner, skip this component and use {@link useConsent}
+ * directly to drive your own UI.
+ *
+ * @example
+ * // Drop-in default
+ * <ConsentBanner />
+ *
+ * @example
+ * // Customized
+ * <ConsentBanner
+ *   message="We use cookies to learn which ads drive bookings."
+ *   acceptLabel="Sounds good"
+ *   declineLabel="No thanks"
+ *   policyHref="/privacy"
+ *   policyLabel="Privacy policy"
+ *   theme="dark"
+ *   onAccept={() => track('consent_accepted')}
+ *   onDecline={() => track('consent_declined')}
+ * />
+ */
+interface ConsentBannerProps {
+    /** Body text. Defaults to the standard cookies-for-ad-performance message. */
+    message?: ReactNode;
+    /** Optional bold title above the body text. */
+    title?: ReactNode;
+    /** Label for the accept button. Default: `"Accept"`. */
+    acceptLabel?: string;
+    /** Label for the decline button. Default: `"Decline"`. */
+    declineLabel?: string;
+    /** Optional link inline with the message (e.g. to a privacy policy). */
+    policyHref?: string;
+    /** Visible text for {@link policyHref}. Default: `"Learn more"`. */
+    policyLabel?: string;
+    /**
+     * Fires after the consent state is persisted + propagated to gtag. Useful
+     * for emitting your own analytics event on the choice.
+     */
+    onAccept?: () => void;
+    onDecline?: () => void;
+    /** Where the banner docks. Default: `"bottom"`. */
+    position?: 'top' | 'bottom';
+    /**
+     * Visual theme. `"auto"` follows `prefers-color-scheme`. Default: `"light"`.
+     */
+    theme?: 'light' | 'dark' | 'auto';
+    /** Class added to the outer wrapper for additional styling hooks. */
+    className?: string;
+    /** Inline style overrides applied to the outer wrapper after the defaults. */
+    style?: CSSProperties;
+}
+declare function ConsentBanner({ message, title, acceptLabel, declineLabel, policyHref, policyLabel, onAccept, onDecline, position, theme, className, style, }?: ConsentBannerProps): ReactNode;
 
 /**
  * Visitor consent state stored by the SDK.
@@ -187,6 +243,22 @@ declare function getConsentState(): ConsentState;
  * loaded.
  */
 declare function setConsentState(state: GtagConsentValue): void;
+/**
+ * Clear the stored consent choice so the banner re-appears on next render.
+ *
+ * Power a "Cookie preferences" link in a footer so visitors can change their
+ * mind without losing access to your site:
+ *
+ * ```tsx
+ * const { reset } = useConsent();
+ * <button onClick={reset}>Cookie preferences</button>
+ * ```
+ *
+ * Does NOT push an `update` to gtag — there's nothing to update because the
+ * visitor hasn't chosen anything yet. The next `setConsentState()` call will
+ * sync gtag once they re-choose.
+ */
+declare function resetConsent(): void;
 
 interface TrackingContextInput {
     packageName?: string | null;
@@ -1781,8 +1853,46 @@ declare function useTrackingParams(): TrackingParams;
 /**
  * Read the current visitor consent state and update when another tab changes
  * the stored value.
+ *
+ * Prefer {@link useConsent} for new code — it returns the same state plus
+ * the `accept` / `decline` / `reset` actions a custom consent UI needs.
+ * `useConsentState` is kept as a convenience for callers that only need to
+ * read.
  */
 declare function useConsentState(): ConsentState;
+/**
+ * The headless consent surface — state + actions in one hook.
+ *
+ * Build a fully-custom banner without losing the gtag-sync, localStorage
+ * persistence, or cross-tab propagation:
+ *
+ * ```tsx
+ * const { state, accept, decline, reset, isPending } = useConsent();
+ *
+ * if (!isPending) {
+ *   return <button onClick={reset}>Cookie preferences</button>;
+ * }
+ * return (
+ *   <MyBannerStyling>
+ *     <button onClick={decline}>No thanks</button>
+ *     <button onClick={accept}>Sure</button>
+ *   </MyBannerStyling>
+ * );
+ * ```
+ *
+ * The boolean helpers (`isPending` / `isGranted` / `isDenied`) are equivalent
+ * to comparing `state` directly — they're there for readability at call sites.
+ */
+interface UseConsentResult {
+    state: ConsentState;
+    isPending: boolean;
+    isGranted: boolean;
+    isDenied: boolean;
+    accept: () => void;
+    decline: () => void;
+    reset: () => void;
+}
+declare function useConsent(): UseConsentResult;
 
 interface CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
     /**
@@ -1853,4 +1963,4 @@ interface CreateTrackingResult<TRegistry extends TriggerRegistryConfig> {
 }
 declare function createTracking<TRegistry extends TriggerRegistryConfig>(options: CreateTrackingOptions<TRegistry>): CreateTrackingResult<TRegistry>;
 
-export { AranovaApiError, type AutomaticEventName, ConsentBanner, type ConsentState, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, type EventConfig, type EventMetadata, type EventName, type FormStartConfig, type FormStartMetadata, type FormSubmitConfig, type FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, type JsonValue, type ManualEventName, type MultiPageSessionConfig, type MultiPageSessionMetadata, type PageViewConfig, type PageViewMetadata, type PhoneClickConfig, type PhoneClickMetadata, type PublicServiceItem, type RegisteredAutomaticEvents, type RegisteredManualEvents, type Sale, type SaleCursorPage, type SaleInput, type SaleItem, type SaleItemInput, type SaleListPage, type SaleListQuery, type SaleUpdateInput, type SalesClient, type SalesClientConfig, type SalesTransportConfig, type ScrollDepthConfig, type ScrollDepthMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, type SupportedCurrency, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackingClient, type TrackingClientContext, type TrackingEventCreatePayload, type TrackingInitConfig, type TrackingInstallSurface, type TrackingParams, type TrackingProviderProps, type TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, captureTrackingParamsFromLocation, createSalesClient, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, fetchServices, formatMoney, fromMinor, getConsentState, setConsentState, toMinor, useConsentState, useGclid, useTrackingParams };
+export { AranovaApiError, type AutomaticEventName, ConsentBanner, type ConsentBannerProps, type ConsentState, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, type EventConfig, type EventMetadata, type EventName, type FormStartConfig, type FormStartMetadata, type FormSubmitConfig, type FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, type JsonValue, type ManualEventName, type MultiPageSessionConfig, type MultiPageSessionMetadata, type PageViewConfig, type PageViewMetadata, type PhoneClickConfig, type PhoneClickMetadata, type PublicServiceItem, type RegisteredAutomaticEvents, type RegisteredManualEvents, type Sale, type SaleCursorPage, type SaleInput, type SaleItem, type SaleItemInput, type SaleListPage, type SaleListQuery, type SaleUpdateInput, type SalesClient, type SalesClientConfig, type SalesTransportConfig, type ScrollDepthConfig, type ScrollDepthMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, type SupportedCurrency, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackingClient, type TrackingClientContext, type TrackingEventCreatePayload, type TrackingInitConfig, type TrackingInstallSurface, type TrackingParams, type TrackingProviderProps, type TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, type UseConsentResult, captureTrackingParamsFromLocation, createSalesClient, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, fetchServices, formatMoney, fromMinor, getConsentState, resetConsent, setConsentState, toMinor, useConsent, useConsentState, useGclid, useTrackingParams };