@c15t/react 2.2.1 → 3.0.0-alpha.0

package/dist-types/components/integrations/google-map.d.ts

@@ -1,82 +0,0 @@
-import type { AllConsentNames } from 'c15t';
-import { type ComponentPropsWithRef, type ReactNode } from 'react';
-export type GoogleMapCoordinates = google.maps.LatLngLiteral;
-export type GoogleMapsApi = typeof google;
-export type GoogleMapInstance = google.maps.Map;
-export type GoogleMapOptions = google.maps.MapOptions;
-export type GoogleMapsLibrary = 'addressValidation' | 'airQuality' | 'core' | 'drawing' | 'elevation' | 'geocoding' | 'geometry' | 'journeySharing' | 'maps' | 'maps3d' | 'marker' | 'places' | 'routes' | 'streetView' | 'visualization';
-export interface GoogleMapProps extends Omit<ComponentPropsWithRef<'div'>, 'children' | 'onError'> {
-    /** Browser API key for the Google Maps JavaScript API. */
-    apiKey: string;
-    /** Initial and controlled center of the map. */
-    center: GoogleMapCoordinates;
-    /**
-     * Initial and controlled zoom level.
-     *
-     * @default 12
-     */
-    zoom?: number;
-    /**
-     * Cloud map id. Changing this value recreates the map because Google treats
-     * it as construction-time configuration.
-     */
-    mapId?: string;
-    /** Additional options passed to the Google Maps constructor. */
-    options?: Omit<GoogleMapOptions, 'center' | 'zoom' | 'mapId'>;
-    /**
-     * Consent category required before the Maps SDK loads.
-     *
-     * @default 'measurement'
-     */
-    consentCategory?: AllConsentNames;
-    /** Google Maps libraries to load with the shared page-level SDK. */
-    libraries?: GoogleMapsLibrary[];
-    /** Language used by Maps controls and service responses. */
-    language?: string;
-    /** Two-character region code used for Maps localization and biasing. */
-    region?: string;
-    /** Google Maps JavaScript API version channel. */
-    version?: string;
-    /** Limits referrer information sent to Google to the current origin. */
-    authReferrerPolicy?: 'origin';
-    /** Google Maps usage-tracking channel. */
-    channel?: string;
-    /** Cloud map ids to preload with the Maps SDK. */
-    mapIds?: string[];
-    /** Google Maps solution-channel identifier. */
-    solutionChannel?: string;
-    /** CSP nonce applied to the Maps script registration. */
-    nonce?: string;
-    /**
-     * Shared c15t script registration id.
-     *
-     * Keep this id and all loader options consistent across the page.
-     *
-     * @default 'c15t-google-maps'
-     */
-    scriptId?: string;
-    /**
-     * Time to wait for the Maps readiness callback before reporting an error.
-     *
-     * @default 15000
-     */
-    timeoutMs?: number;
-    /**
-     * Change this value to retry a failed loader or map initialization.
-     * Successful page-level loader registrations remain shared.
-     *
-     * @default 0
-     */
-    retryKey?: string | number;
-    /** Content shown before the configured consent category is allowed. */
-    placeholder?: ReactNode;
-    /** Content shown while the Maps SDK or map instance is loading. */
-    loadingFallback?: ReactNode;
-    /** Content shown when configuration, loading, authentication, or setup fails. */
-    errorFallback?: ReactNode;
-    /** Called when the map instance is ready. */
-    onReady?: (map: GoogleMapInstance, api: GoogleMapsApi) => void;
-    /** Called when configuration, loading, authentication, or setup fails. */
-    onError?: (error: Error) => void;
-}
-export declare const GoogleMap: import("react").ForwardRefExoticComponent<Omit<GoogleMapProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;

package/dist-types/components/integrations/index.d.ts

@@ -1,2 +0,0 @@
-export { GoogleMap, type GoogleMapCoordinates, type GoogleMapInstance, type GoogleMapOptions, type GoogleMapProps, type GoogleMapsApi, type GoogleMapsLibrary, } from './google-map';
-export { YouTubeEmbed, type YouTubeEmbedParams, type YouTubeEmbedProps, type YouTubeSrcSource, type YouTubeVideoIdSource, } from './youtube-embed';

package/dist-types/components/integrations/shared.d.ts

@@ -1,12 +0,0 @@
-import type { AllConsentNames } from 'c15t';
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-import { FrameRoot } from '../frame';
-export declare function IntegrationPlaceholder({ category, children, showButton, ...props }: {
-    category: AllConsentNames;
-    children?: ReactNode;
-    showButton?: boolean;
-} & Omit<ComponentPropsWithoutRef<typeof FrameRoot>, 'children'>): import("react").JSX.Element;
-export declare function IntegrationStatus({ category, status, }: {
-    category: AllConsentNames;
-    status: 'error' | 'loading';
-}): import("react").JSX.Element;

package/dist-types/components/integrations/youtube-embed.d.ts

@@ -1,95 +0,0 @@
-import type { AllConsentNames } from 'c15t';
-import { type ComponentPropsWithRef, type ReactNode } from 'react';
-import { type FrameProps } from '../frame';
-export type YouTubeEmbedParams = Record<string, string | number | boolean | null | undefined>;
-interface YouTubeEmbedBaseProps extends Omit<ComponentPropsWithRef<'iframe'>, 'children' | 'src' | 'title'> {
-    /**
-     * Accessible title for the embedded player.
-     */
-    title: string;
-    /**
-     * Consent category required before the iframe mounts.
-     *
-     * @default 'marketing'
-     */
-    consentCategory?: AllConsentNames;
-    /**
-     * Class name for the iframe element targeted by the forwarded ref.
-     */
-    className?: string;
-    /**
-     * Class name for the consent-gated frame wrapper.
-     */
-    wrapperClassName?: string;
-    /**
-     * Placeholder rendered while consent is missing.
-     */
-    placeholder?: ReactNode;
-    /**
-     * Fallback rendered when the iframe cannot be configured or when the
-     * browser reports a native iframe loading error.
-     *
-     * YouTube player-level errors require the IFrame Player API and are not
-     * reported reliably by a standard cross-origin iframe.
-     */
-    errorFallback?: ReactNode;
-    /**
-     * Fallback rendered after consent while the iframe is loading.
-     */
-    loadingFallback?: ReactNode;
-    /**
-     * Additional props passed to the underlying Frame component.
-     */
-    frameProps?: Omit<FrameProps, 'children' | 'category' | 'className' | 'placeholder'>;
-}
-export interface YouTubeVideoIdSource {
-    /**
-     * YouTube video id. Use this for first-party construction of the embed URL.
-     */
-    videoId: string;
-    src?: never;
-    /**
-     * Whether to use youtube-nocookie.com.
-     *
-     * @default true
-     */
-    privacyEnhanced?: boolean;
-    /**
-     * Optional start time in seconds. This takes precedence over `params.start`.
-     */
-    start?: number;
-    /**
-     * Additional query params for the generated embed URL.
-     */
-    params?: YouTubeEmbedParams;
-}
-export interface YouTubeSrcSource {
-    /**
-     * Fully formed YouTube embed URL. Use this when migrating existing embeds.
-     */
-    src: string;
-    videoId?: never;
-    privacyEnhanced?: never;
-    start?: never;
-    params?: never;
-}
-export type YouTubeEmbedProps = YouTubeEmbedBaseProps & (YouTubeVideoIdSource | YouTubeSrcSource);
-/**
- * Renders a YouTube iframe behind c15t consent gating.
- *
- * Use `videoId` for a privacy-enhanced URL built by c15t, or `src` to migrate
- * an existing complete embed URL. The two source modes are mutually exclusive.
- * The iframe is mounted only after consent and includes responsive 16:9 layout,
- * native lazy loading, and a visible loading state by default.
- *
- * @example
- * ```tsx
- * <YouTubeEmbed
- *   consentCategory="marketing"
- *   title="Product demo"
- *   videoId="dQw4w9WgXcQ"
- * />
- * ```
- */
-export declare const YouTubeEmbed: import("react").ForwardRefExoticComponent<(Omit<YouTubeEmbedBaseProps & YouTubeSrcSource, "ref"> | Omit<YouTubeEmbedBaseProps & YouTubeVideoIdSource, "ref">) & import("react").RefAttributes<HTMLIFrameElement>>;
-export {};

package/dist-types/context/consent-manager-context.d.ts

@@ -1,31 +0,0 @@
-/**
- * @packageDocumentation
- * Provides the context for sharing consent management state across components.
- */
-import type { ConsentManagerInterface, ConsentStoreState } from 'c15t';
-/**
- * The context value provided by ConsentManagerProvider.
- */
-export interface ConsentStateContextValue {
-    /**
-     * Current consent management state
-     */
-    state: ConsentStoreState;
-    /**
-     * Reference to the consent manager store instance
-     * We use object type to avoid circular dependencies
-     */
-    store: {
-        getState: () => ConsentStoreState;
-        subscribe: (listener: (state: ConsentStoreState) => void) => () => void;
-        setState: (state: Partial<ConsentStoreState>) => void;
-    };
-    /**
-     * Optional API client instance
-     */
-    manager: ConsentManagerInterface | null;
-}
-/**
- * Context for sharing consent management state across components.
- */
-export declare const ConsentStateContext: import("react").Context<ConsentStateContextValue | undefined>;

package/dist-types/hooks/index.d.ts

@@ -1,12 +0,0 @@
-export * from './use-component-config';
-export * from './use-consent-dialog-trigger';
-export * from './use-consent-manager';
-export * from './use-consent-script';
-export * from './use-focus-trap';
-export * from './use-headless-consent-ui';
-export * from './use-headless-iab-consent-ui';
-export * from './use-reduced-motion';
-export * from './use-ssr-status';
-export * from './use-text-direction';
-export * from './use-theme';
-export * from './use-translations';

package/dist-types/hooks/use-consent-dialog-trigger.d.ts

@@ -1,10 +0,0 @@
-export type ConsentDialogTriggerVisibility = 'always' | 'after-consent' | 'never';
-export interface UseConsentDialogTriggerOptions {
-    showWhen?: ConsentDialogTriggerVisibility;
-    onClick?: () => void;
-}
-export interface UseConsentDialogTriggerResult {
-    isVisible: boolean;
-    openDialog: () => void;
-}
-export declare function useConsentDialogTrigger(options?: UseConsentDialogTriggerOptions): UseConsentDialogTriggerResult;

package/dist-types/hooks/use-consent-manager.d.ts

@@ -1,27 +0,0 @@
-/**
- * @packageDocumentation
- * Hook for accessing and managing consent state.
- */
-import type { ConsentManagerInterface, ConsentStoreState } from 'c15t';
-/**
- * Hook for accessing and managing consent state.
- *
- * @remarks
- * This hook provides access to the complete consent management API, including:
- * - Current consent state (what consents are given/required)
- * - Methods to update consents
- * - Compliance settings and region detection
- * - State persistence and retrieval
- * - The consent manager (if configured)
- *
- * The hook must be used within a ConsentManagerProvider component.
- *
- * @throws {Error}
- * Throws if used outside of a ConsentManagerProvider context.
- *
- * @returns Combined state and methods for consent management
- * @public
- */
-export declare function useConsentManager(): ConsentStoreState & {
-    manager: ConsentManagerInterface | null;
-};

package/dist-types/hooks/use-consent-script.d.ts

@@ -1,80 +0,0 @@
-import type { Script } from 'c15t';
-export type ConsentScriptStatus = 'idle' | 'blocked' | 'loading' | 'ready' | 'error';
-export type ConsentScriptUnmountBehavior = 'keep' | 'remove';
-export declare class ConsentScriptConflictError extends Error {
-    readonly scriptId: string;
-    constructor(scriptId: string);
-}
-export interface ConsentScriptReadyControls<TReady> {
-    resolve: (value: TReady) => void;
-    reject: (error: Error) => void;
-}
-export interface UseConsentScriptOptions<TReady = unknown> {
-    /**
-     * Script configuration registered with c15t's script manager.
-     */
-    script: Script;
-    /**
-     * Whether this hook should register the script.
-     *
-     * @default true
-     */
-    enabled?: boolean;
-    /**
-     * Returns the SDK object when it is already available.
-     */
-    resolveReady?: () => TReady | false | null | undefined;
-    /**
-     * Registers callback-based SDK readiness, such as `callback=` query params.
-     * The returned cleanup function runs after readiness settles or the registry
-     * entry is released.
-     */
-    registerReadyCallback?: (controls: ConsentScriptReadyControls<TReady>) => undefined | (() => void);
-    /**
-     * Semantic key for the SDK readiness contract shared by this script id.
-     *
-     * Consumers of the same script id must use the same key. Set this when the
-     * readiness callbacks are configured differently from the script itself.
-     *
-     * @default script.id
-     */
-    readinessKey?: string;
-    /**
-     * Optional timeout for SDK readiness after the script is registered.
-     */
-    timeoutMs?: number;
-    /**
-     * Changing this value retries a failed registration with the same script id.
-     * Successful singleton registrations remain shared.
-     *
-     * @default 0
-     */
-    retryKey?: string | number;
-    /**
-     * Whether c15t should retain an owned script registration after the final
-     * hook consumer unmounts. Use `keep` for page-level singleton SDKs that
-     * cannot safely be loaded more than once.
-     *
-     * @default 'remove'
-     */
-    unmountBehavior?: ConsentScriptUnmountBehavior;
-}
-export interface UseConsentScriptResult<TReady = unknown> {
-    status: ConsentScriptStatus;
-    scriptId: string;
-    hasConsent: boolean;
-    scriptAppended: boolean;
-    readyValue: TReady | null;
-    error: Error | null;
-    ready: Promise<TReady> | null;
-}
-/**
- * Registers a consent-gated script through c15t and exposes SDK readiness as a promise.
- *
- * @remarks
- * Registrations are shared within one ConsentManagerProvider. The hook adopts
- * compatible scripts already registered with that manager and never removes
- * registrations it does not own. Inline script objects and callbacks are safe:
- * lifecycle callbacks are read from the latest render without re-registering.
- */
-export declare function useConsentScript<TReady = unknown>(options: UseConsentScriptOptions<TReady>): UseConsentScriptResult<TReady>;

package/dist-types/hooks/use-headless-consent-ui.d.ts

@@ -1,46 +0,0 @@
-import { type PolicyUiAction, type PolicyUiActionDirection, type PolicyUiActionGroup, type PolicyUiProfile } from '@c15t/ui/utils';
-import { useConsentManager } from './use-consent-manager';
-export type HeadlessConsentSurface = 'banner' | 'dialog';
-export type HeadlessConsentSurfaceAction = PolicyUiAction;
-export type HeadlessConsentWriteAction = 'accept' | 'reject';
-export type HeadlessConsentBannerAction = HeadlessConsentSurfaceAction;
-export type HeadlessConsentDialogAction = HeadlessConsentSurfaceAction;
-export interface HeadlessConsentSurfaceState<TAction extends string = HeadlessConsentSurfaceAction> {
-    allowedActions: TAction[];
-    orderedActions: TAction[];
-    actionGroups: TAction[][];
-    primaryActions: TAction[];
-    layout?: PolicyUiActionGroup[];
-    direction: PolicyUiActionDirection;
-    uiProfile?: PolicyUiProfile;
-    scrollLock?: boolean;
-    hasPolicyHints: boolean;
-    shouldFillActions: boolean;
-    isVisible: boolean;
-}
-export type HeadlessConsentBannerState = HeadlessConsentSurfaceState<HeadlessConsentBannerAction>;
-export type HeadlessConsentDialogState = HeadlessConsentSurfaceState<HeadlessConsentDialogAction>;
-export interface UseHeadlessConsentUIResult {
-    activeUI: ReturnType<typeof useConsentManager>['activeUI'];
-    banner: HeadlessConsentBannerState;
-    dialog: HeadlessConsentDialogState;
-    openBanner: (options?: {
-        force?: boolean;
-    }) => void;
-    openDialog: () => void;
-    closeUI: () => void;
-    performAction: (action: HeadlessConsentWriteAction, options: {
-        surface: HeadlessConsentSurface;
-        uiSource?: string;
-    }) => Promise<void>;
-    performBannerAction: (action: HeadlessConsentWriteAction, options?: {
-        uiSource?: string;
-    }) => Promise<void>;
-    performDialogAction: (action: HeadlessConsentWriteAction, options?: {
-        uiSource?: string;
-    }) => Promise<void>;
-    saveCustomPreferences: (options?: {
-        uiSource?: string;
-    }) => Promise<void>;
-}
-export declare function useHeadlessConsentUI(): UseHeadlessConsentUIResult;

package/dist-types/hooks/use-ssr-status.d.ts

@@ -1,57 +0,0 @@
-/**
- * @packageDocumentation
- * Hook for accessing SSR data usage status.
- */
-/**
- * Return value of {@link useSSRStatus}.
- *
- * @public
- */
-export interface SSRStatus {
-    /**
-     * Whether SSR data was used for initialization.
-     *
-     * `true` if SSR data was provided and successfully consumed,
-     * `false` otherwise.
-     */
-    ssrDataUsed: boolean;
-    /**
-     * Reason SSR data was skipped, or `null` if used successfully.
-     *
-     * - `'no_data'` — no `ssrData` prop was provided to the provider
-     * - `'fetch_failed'` — `ssrData` was provided but the Promise resolved with no data
-     * - `'context_mismatch'` — `ssrData` did not match the current runtime request context
-     */
-    ssrSkippedReason: 'no_data' | 'fetch_failed' | 'context_mismatch' | null;
-}
-/**
- * Returns information about SSR data usage.
- *
- * @remarks
- * This hook is useful for debugging whether server-side data was used
- * for consent manager initialization. It can help identify issues with
- * SSR data fetching or hydration.
- *
- * The hook must be used within a ConsentManagerProvider component.
- *
- * @throws {Error}
- * Throws if used outside of a ConsentManagerProvider context.
- *
- * @returns Object containing SSR status information
- *
- * @example
- * ```tsx
- * function DebugInfo() {
- *   const { ssrDataUsed, ssrSkippedReason } = useSSRStatus();
- *
- *   if (ssrDataUsed) {
- *     return <span>SSR data was used</span>;
- *   }
- *
- *   return <span>SSR skipped: {ssrSkippedReason}</span>;
- * }
- * ```
- *
- * @public
- */
-export declare function useSSRStatus(): SSRStatus;

package/dist-types/hooks/use-styles.d.ts

@@ -1,21 +0,0 @@
-import type { AllThemeKeys, ClassNameStyle, ThemeValue } from '../types/theme';
-/**
- * Hook for retrieving and merging styles from theme context and component props.
- *
- * @remarks
- * This hook manages the style resolution process by pulling styles from
- * theme slots and merging them with component-level props.
- *
- * Precedence (lowest to highest):
- * 1. Component internal base classes (baseClassName)
- * 2. Theme slot classes (from theme context)
- * 3. Component prop classes (from className prop)
- *
- * @param themeKey - The slot key to lookup styles (e.g. 'bannerCard')
- * @param componentStyle - Optional component-level styles to merge
- * @param themeOverride - Optional theme override
- *
- * @returns An object containing merged className and style properties
- * @public
- */
-export declare function useStyles(themeKey: AllThemeKeys, componentStyle?: ThemeValue, themeOverride?: any): ClassNameStyle;

package/dist-types/hooks/use-translations.d.ts

@@ -1,28 +0,0 @@
-import type { Translations } from 'c15t';
-/**
- * Hook for accessing translations in the current language.
- *
- * @remarks
- * This hook provides access to the translations for the currently selected language.
- * It automatically handles language selection based on the translation configuration.
- * Falls back to English if the selected language is not available.
- *
- * @returns The translations for the current language
- *
- * @example
- * ```tsx
- * function CookieBanner() {
- *   const translations = useTranslations();
- *
- *   return (
- *     <div>
- *       <h2>{translations.cookieBanner.title}</h2>
- *       <p>{translations.cookieBanner.description}</p>
- *     </div>
- *   );
- * }
- * ```
- *
- * @public
- */
-export declare function useTranslations(): Translations;

package/dist-types/providers/consent-manager-provider.d.ts

@@ -1,40 +0,0 @@
-import type { ConsentManagerProviderProps } from '../types/consent-manager';
-/**
- * Clears all cached consent managers and stores.
- *
- * @remarks
- * This utility function is primarily intended for use in tests to ensure
- * clean state between test cases. The module-level caches persist across
- * component unmounts/remounts, which can cause test interference.
- *
- * @internal
- */
-export declare function clearConsentRuntimeCache(): void;
-/**
- * Provider component for consent management functionality.
- *
- * @remarks
- * This component initializes and manages the consent management system, including:
- * - Setting up the consent store with initial configuration
- * - Creating a consent manager from the provided options
- * - Detecting user's region for compliance
- * - Managing consent state updates
- * - Providing access to consent management throughout the app
- *
- * @example
- * ```tsx
- * <ConsentManagerProvider
- *   options={{
- *     mode: 'offline',
- *     callbacks: {
- *       onConsentSet: (response) => console.log('Consent updated')
- *     }
- *   }}
- * >
- *   {children}
- * </ConsentManagerProvider>
- * ```
- *
- * @public
- */
-export declare function ConsentManagerProvider({ children, options, }: ConsentManagerProviderProps): import("react").JSX.Element;

package/dist-types/types/consent-manager.d.ts

@@ -1,39 +0,0 @@
-import type { BaseConsentManagerOptions, UIOptions } from '@c15t/ui/theme';
-import type { ReactNode } from 'react';
-/**
- * React-specific configuration options
- */
-export interface ReactUIOptions extends UIOptions {
-}
-/**
- * Extended configuration options for the React consent manager.
- *
- * @remarks
- * This type composes:
- * - Base framework-agnostic options from {@link BaseConsentManagerOptions}
- * - React-specific UI configuration
- *
- * In offline mode this also includes `offlinePolicy` configuration for
- * local policy previews.
- *
- * @see {@link https://c15t.com/docs/frameworks/react/policy-packs}
- */
-export type ConsentManagerOptions = BaseConsentManagerOptions & ReactUIOptions;
-/**
- * Configuration options for the ConsentManagerProvider.
- *
- * @public
- */
-export interface ConsentManagerProviderProps {
-    /**
-     * React children to render within the provider.
-     */
-    children: ReactNode;
-    /**
-     * Configuration options for the consent manager.
-     * This includes core, React, store, and translation settings.
-     *
-     * @see {@link https://c15t.com/docs/frameworks/react/components/consent-manager-provider}
-     */
-    options: ConsentManagerOptions;
-}

package/dist-types/types/theme/style-keys.d.ts

@@ -1 +0,0 @@
-export type { AllThemeKeys } from '@c15t/ui/theme';

package/dist-types/utils/test-helpers.d.ts

@@ -1,31 +0,0 @@
-import type { ReactNode } from 'react';
-import type { ThemeValue } from '../types/theme';
-interface ComponentStyles {
-    component: ReactNode;
-    testCases: {
-        testId: string;
-        styles: string | ThemeValue;
-    }[];
-    noStyle?: boolean;
-    theme?: any;
-}
-/**
- * A robust test utility to verify components render correctly with applied styles.
- *
- * This function:
- * - Handles both direct container elements and portal-rendered elements
- * - Performs basic className checks
- * - Is tolerant of browser-specific style differences
- * - Works with string classNames and object style formats
- *
- * @example
- * ```tsx
- * await testComponentStyles({
- *   component: <MyComponent />,
- *   theme: { slots: { root: 'custom-class' } },
- *   testCases: [{ testId: 'my-component-root', styles: 'custom-class' }]
- * });
- * ```
- */
-export declare function testComponentStyles({ component, testCases, noStyle, theme, }: ComponentStyles): Promise<void>;
-export default testComponentStyles;