@consenti/ui 0.1.0 → 0.2.0

package/dist/react.d.cts

@@ -1,13 +1,54 @@
+type NonEmptyArray<T> = [T, ...T[]];
+type DeepPartial<T> = T extends Function ? T : T extends Array<infer InferredArrayType> ? Array<DeepPartial<InferredArrayType>> : T extends ReadonlyArray<infer InferredReadonlyArrayType> ? ReadonlyArray<DeepPartial<InferredReadonlyArrayType>> : T extends object ? {
+    [Key in keyof T]?: DeepPartial<T[Key]>;
+} : T;
+
+declare const COMPLIANCE_GROUP_IDS: readonly ["opt-in", "opt-out", "opt-out-strict", "opt-in-dpdpa", "opt-in-china", "opt-in-brazil", "general-privacy-consent", "notice-only"];
+
+/**
+ * Compliance-related literal types, derived from the regulation/group ID data
+ * that lives in @consenti/utils (packages/utils/src/compliance.ts).
+ *
+ * This import is type-only and fully erased at compile time — @consenti/types
+ * has no runtime dependency on @consenti/utils. The actual data (COMPLIANCE_GROUPS,
+ * EMBEDDED_COMPLIANCE_MAP, COMPLIANCE_VALIDATION_RULES, GPC_OPTIONS, etc.) lives in
+ * @consenti/utils; import it from there.
+ *
+ * HOW TO ADD A NEW REGULATION OR COMPLIANCE GROUP: see the header comment in
+ * packages/utils/src/compliance.ts — these types auto-update from that data.
+ */
+
+type ComplianceGroupId = typeof COMPLIANCE_GROUP_IDS[number];
+
+interface ComplianceMapData {
+    version: string;
+    countries: Record<string, CountryComplianceEntry>;
+}
+interface CountryComplianceEntry {
+    complianceGroup: ComplianceGroupId;
+    default: ComplianceGroupId;
+    description: string;
+    overriddenRegions?: Record<string, {
+        complianceGroup: ComplianceGroupId;
+        description: string;
+    }>;
+}
+
 type ConsentStatus = 'granted' | 'denied' | 'objected';
+type ConsentAction = 'accept_all' | 'reject_all' | 'custom' | 'update';
 type ConsentValue = Record<string, ConsentStatus>;
 interface Cookie {
     id: string;
-    type?: 'consent' | 'legitimate_interest';
+    legalBasis?: 'mandatory' | 'consent' | 'legitimate_interest';
+    /** @deprecated use legalBasis: 'mandatory' */
     mandatory?: boolean;
+    /** @deprecated use legalBasis */
+    type?: 'consent' | 'legitimate_interest';
     listenGpc?: boolean;
     expiry?: number;
     tcfVendorId?: number;
     tcfPurposes?: number[];
+    tcfSpecialFeatures?: number[];
     cpraCategory?: 'sale' | 'sharing' | 'sensitive';
 }
 type ButtonStyle = 'primary' | 'secondary' | 'text' | 'accent';
@@ -18,6 +59,7 @@ interface Button {
     action: ButtonAction;
     cookies?: string[] | '*' | '!';
     url?: string;
+    type?: string;
 }
 interface MainBanner {
     position: 'top' | 'bottom' | 'middle' | 'left-bottom' | 'right-bottom';
@@ -43,18 +85,13 @@ interface Category {
     };
     cookies: string[];
 }
-interface PreferenceModal {
+interface PreferenceModal extends Omit<MainBanner, "position"> {
     position?: 'left' | 'right' | 'center';
-    overlayOpacity?: number;
-    showClose?: boolean;
-    showLocaleSwitcher?: boolean;
-    heading?: string;
-    headingTag?: string;
     subheading?: string;
-    htmlText?: string;
-    buttons: Button[];
     categories: Category[];
     persistent?: boolean;
+    /** Screen width in px below which the modal expands to full screen. Default: 576. Set to 0 to disable. */
+    mobileFullScreenBreakpoint?: number;
 }
 interface DpdpaConfig {
     dataFiduciary: string;
@@ -63,6 +100,7 @@ interface DpdpaConfig {
 }
 interface ResolvedProfile {
     id: number;
+    profileUuid?: string;
     version: number;
     defaultLocale: string;
     locales?: string[];
@@ -73,6 +111,26 @@ interface ResolvedProfile {
     cookieSigningKey?: string;
     dpdpa?: DpdpaConfig;
     darkMode?: boolean;
+    gpcMode?: 'ignore' | 'honor' | 'strict';
+    complianceGroup?: string;
+    complianceConfig?: Record<string, string>;
+}
+type WidgetCountryResolverFn = () => Promise<{
+    country: string | null;
+    region: string | null;
+    confidence: number;
+}>;
+interface AgeGateWidgetConfig {
+    enabled: boolean;
+    minimumAge: number;
+    requireParentalConsent?: boolean;
+}
+interface ComplianceWidgetConfig {
+    type?: 'auto' | ComplianceGroupId | string;
+    geoDataProvider?: 'default' | WidgetCountryResolverFn;
+    autoComplianceMap?: 'default' | ComplianceMapData | 'auto';
+    complianceMapUrl?: string;
+    ageGate?: AgeGateWidgetConfig;
 }
 interface GtmConfig {
     containerId?: string;
@@ -88,6 +146,9 @@ interface ApiConfig {
     enabled?: boolean;
     baseUrl?: string;
     authToken?: string;
+    tenantId?: string;
+    complianceGroup?: string;
+    trustDomain?: boolean;
 }
 interface ThemeConfig {
     bgColor?: string;
@@ -109,35 +170,52 @@ interface ThemeConfig {
     accentTextColor?: string;
 }
 interface CoreConfig {
-    profileId?: number;
+    tenantId?: string;
     autoHonorGPC?: boolean | 'strict';
     locale?: string;
     disableCssTemplate?: boolean;
-    signCookies?: boolean;
     cookieSigningKey?: string;
     allowReceipt?: boolean;
     cookieDomains?: string;
     storage?: 'cookie' | 'localStorage';
     theme?: ThemeConfig;
-    privacyPolicyUrl?: string;
-    regulation?: 'gdpr' | 'ccpa' | 'cpra' | 'dpdpa' | 'uk-gdpr' | 'lgpd' | 'pipeda' | 'popia' | 'pdpa-th' | 'appi' | 'kvkk';
     userId?: string;
+    usePrebuiltProfiles?: 'all' | NonEmptyArray<ComplianceGroupId>;
+    cacheResolvedProfiles?: boolean;
+    console?: Array<'info' | 'log' | 'warning' | 'error'>;
 }
 interface ConsentiConfig {
     core: CoreConfig;
+    compliance?: ComplianceWidgetConfig;
     rootEl?: string | HTMLElement;
     darkMode?: boolean;
     autoInit?: boolean;
     api?: ApiConfig;
     utils?: UtilsConfig;
     plugins?: ConsentiPlugin[];
-    profileOverride?: Partial<ResolvedProfile>;
+    profileOverride?: DeepPartial<ResolvedProfile>;
+    /** When true, suppresses the "Powered by Consenti" footer link in the banner and modal. */
+    hidePoweredBy?: boolean;
 }
+type ConsentiEventName = 'bannerInitialized' | 'consenti:bannerInitialized' | 'bannerVisibility' | 'consenti:bannerVisibility' | 'modalVisibility' | 'consenti:modalVisibility' | 'consentBeingSubmitted' | 'consenti:consentBeingSubmitted' | 'consentSubmitted' | 'consenti:consentSubmitted';
 interface ConsentiWidgetAPI {
     hasConsent(): boolean;
     getConsent(): ConsentValue | null;
     getConsentDate(): Date | false;
     getGTMConsent(): Record<string, string> | null;
+    isCookieGranted(cookieId: string, requestValue?: boolean): boolean | ConsentStatus;
+    isCategoryGranted(categoryId: string, requestValue?: boolean): boolean | {
+        [cookieId: string]: ConsentStatus;
+    }[];
+    grantAll(onlyMandatory?: boolean): Promise<void>;
+    denyAll(includingMandatory?: boolean): Promise<void>;
+    on(event: ConsentiEventName, handler: (data: ConsentEvent) => void): void;
+    off(event: ConsentiEventName, handler: (data: ConsentEvent) => void): void;
+    version(): {
+        package: string;
+        profileVersion: number | null;
+        consentVersion: number;
+    };
     bannerVisibility(): 'main' | 'gpc' | false;
     modalVisibility(): 'preference' | false;
     getProfile(): ResolvedProfile | null;
@@ -152,6 +230,10 @@ interface ConsentiWidgetAPI {
     getBannerElement(): HTMLElement | null;
     getModalElement(): HTMLElement | null;
     switchLocale(locale: string): void;
+    setDarkMode(enable?: boolean): void;
+    setTheme(theme: Partial<ThemeConfig>): void;
+    setConfig(config: DeepPartial<ConsentiConfig>): void;
+    setProfile(override: DeepPartial<ResolvedProfile>): void;
     init(): Promise<void>;
     onReady(callback: () => void): void;
     destroy(): void;
@@ -165,6 +247,19 @@ declare abstract class ConsentiPlugin {
     onModalShow?(): void | Promise<void>;
     onModalHide?(): void | Promise<void>;
 }
+interface ConsentEvent {
+    profileId?: number;
+    consent?: ConsentValue;
+    hasExistingConsent?: boolean;
+    show?: boolean;
+    action?: boolean;
+    consentAction?: ConsentAction;
+    consentId?: string;
+    pageUrl?: string;
+    apiResponse?: unknown;
+    fromBroadcast?: boolean;
+    gpcDetected?: boolean;
+}
 
 /**
  * Main entry point for the Consenti widget.
@@ -176,7 +271,7 @@ declare abstract class ConsentiPlugin {
  * @example
  * ```ts
  * const widget = new ConsentiSetup({
- *   core: { profileId: 0 },
+ *   compliance: { type: 'opt-in' },
  * })
  * await widget.ready
  * console.log(widget.hasConsent())
@@ -188,6 +283,7 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
     private initialized;
     private initializing;
     private profile;
+    private resolvedBase;
     private consentStore;
     private eventBus;
     private banner;
@@ -201,6 +297,8 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
     private lastSignature;
     /** Tracks which banner variant is currently visible, or null when hidden. */
     private _bannerVariant;
+    /** Maps original handler functions to their DOM-wrapped listeners for on/off bookkeeping. */
+    private _eventHandlers;
     /**
      * Creates and initialises the consent widget.
      *
@@ -233,6 +331,8 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      * @param invoke - Function that calls the desired hook method on a single plugin.
      */
     private callPluginHook;
+    private _buildGrantAllConsent;
+    private _buildDenyAllConsent;
     private buildHandlers;
     /**
      * Classifies a consent submission as `accept_all`, `reject_all`, `custom`, or `update`.
@@ -381,6 +481,93 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      * @param locale - BCP 47 locale code to switch to (e.g. `'fr'`, `'de-AT'`).
      */
     switchLocale(locale: string): void;
+    /**
+     * Returns `true` if the named cookie's consent is `'granted'`.
+     * When `requestValue` is `true`, returns the raw `ConsentStatus` string instead of a boolean,
+     * or `false` if the cookie is not in the consent map.
+     */
+    isCookieGranted(cookieId: string, requestValue?: boolean): boolean | 'granted' | 'denied' | 'objected';
+    /**
+     * Checks consent for all cookies belonging to the given category.
+     *
+     * With `requestValue = false` (default): returns `true` only when every cookie in the
+     * category is `'granted'`, `false` otherwise.
+     *
+     * With `requestValue = true`: returns an array of one-key records — one per cookie in the
+     * category — e.g. `[{ analytics: 'granted' }, { pixel: 'denied' }]`.
+     *
+     * Returns `false` / `[]` if the category is not found or the widget is not yet initialized.
+     */
+    isCategoryGranted(categoryId: string, requestValue?: boolean): boolean | {
+        [cookieId: string]: 'granted' | 'denied' | 'objected';
+    }[];
+    /**
+     * Programmatically accepts cookies and hides the banner.
+     *
+     * @param onlyMandatory - When `true`, only mandatory cookies are granted and all others
+     *                        are set to `'denied'`. Defaults to `false` (grant everything).
+     */
+    grantAll(onlyMandatory?: boolean): Promise<void>;
+    /**
+     * Programmatically denies cookies and hides the banner.
+     *
+     * @param includingMandatory - When `true`, mandatory cookies are also denied. Defaults to
+     *                             `false` (mandatory cookies remain `'granted'`). Passing `true`
+     *                             logs a warning — ensure this is intentional.
+     */
+    denyAll(includingMandatory?: boolean): Promise<void>;
+    /**
+     * Subscribes to a Consenti widget event. The `consenti:` prefix is optional —
+     * both `'consentSubmitted'` and `'consenti:consentSubmitted'` are accepted.
+     *
+     * The same handler reference must be passed to `off()` to unsubscribe.
+     *
+     * @example
+     * ```ts
+     * const handler = (data) => console.log(data)
+     * widget.on('consentSubmitted', handler)
+     * // later:
+     * widget.off('consentSubmitted', handler)
+     * ```
+     */
+    on(event: ConsentiEventName, handler: (data: ConsentEvent) => void): void;
+    /**
+     * Removes a previously registered event handler. The same function reference passed to
+     * `on()` must be used here.
+     */
+    off(event: ConsentiEventName, handler: (data: ConsentEvent) => void): void;
+    /**
+     * Returns the current version of the package and the active profile/consent versions.
+     * Useful for debugging and support diagnostics.
+     */
+    version(): {
+        package: string;
+        profileVersion: number | null;
+        consentVersion: number;
+    };
+    /**
+     * Toggles or sets dark mode at runtime without re-initialising the widget.
+     * When `enable` is omitted, the current dark mode state is toggled.
+     */
+    setDarkMode(enable?: boolean): void;
+    /**
+     * Applies partial theme token overrides at runtime, merging them into the current theme.
+     * CSS custom properties on the root element are updated immediately.
+     */
+    setTheme(theme: Partial<ThemeConfig>): void;
+    /**
+     * Deep-merges a partial config into the current widget config.
+     * Theme and dark mode side-effects are re-applied immediately.
+     * Changes to locale or profile require an explicit `switchLocale()` or `init()` call.
+     */
+    setConfig(config: DeepPartial<ConsentiConfig>): void;
+    /**
+     * Merges a partial profile override into the current profile and re-renders any visible UI.
+     * Does not make a network request — the resolved base profile from the last `init()` is reused.
+     *
+     * No-op before `init()` completes (while `resolvedBase` is null).
+     */
+    setProfile(override: DeepPartial<ResolvedProfile>): void;
     /**
      * Destroys the widget — removes all DOM elements, disconnects the BroadcastChannel,
      * and calls `destroy()` on all registered plugins.
@@ -398,7 +585,7 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
  *
  * Intended for **Next.js** (App Router and Pages Router) and any other React 18+
  * project where you manage the `ConsentiSetup` instance yourself and want the
- * `useConsent()` hook to re-render when consent changes.
+ * `useConsent()` hook to re-render when consent or UI state changes.
  *
  * @example
  * ```tsx
@@ -410,7 +597,9 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
  *
  * export function ConsentiProvider({ children }: { children: React.ReactNode }) {
  *   useEffect(() => {
- *     const widget = new ConsentiSetup({ core: { profileId: 0 } })
+ *     const widget = new ConsentiSetup({
+ *       api: { enabled: true, baseUrl: process.env.NEXT_PUBLIC_API_URL },
+ *     })
  *     setConsentiWidget(widget)
  *   }, [])
  *   return <>{children}</>
@@ -419,10 +608,10 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
  * // Any component
  * import { useConsent } from '@consenti/ui/react'
  *
- * function CookieBanner() {
- *   const { hasConsent, submitConsent } = useConsent()
- *   if (hasConsent()) return null
- *   return <button onClick={() => submitConsent({ analytics: 'granted' })}>Accept</button>
+ * function CookieStatus() {
+ *   const { hasConsent, consent, showModal } = useConsent()
+ *   if (!hasConsent) return <button onClick={showModal}>Manage Cookies</button>
+ *   return <span>{consent?.analytics === 'granted' ? 'Analytics on' : 'Analytics off'}</span>
  * }
  * ```
  */
@@ -435,18 +624,33 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
  */
 declare function setConsentiWidget(widget: ConsentiSetup): void;
 /**
- * React hook that exposes consent state and lets components react to consent changes.
+ * React hook that exposes consent state, banner/modal visibility, and widget actions.
+ *
+ * Subscribes to `consenti:consentSubmitted`, `consenti:bannerVisibility`, and
+ * `consenti:modalVisibility` on `window` and triggers re-renders on each event.
+ * Returns SSR-safe initial values during server render.
  *
- * Subscribes to `consenti:consentSubmitted` on `window` and triggers a re-render
- * each time consent is updated. Returns SSR-safe fallback values during server render.
+ * Destructure only what you need — unused values do not cause extra renders.
  *
- * @returns An object with `hasConsent`, `getConsent`, `submitConsent`, and `getConsentDate`.
+ * @returns Consent state values and widget action functions.
  */
 declare function useConsent(): {
-    hasConsent: () => boolean;
-    getConsent: () => ConsentValue | null;
-    submitConsent: (_consent: Partial<ConsentValue>) => Promise<void>;
-    getConsentDate: () => Date | false;
+    hasConsent: boolean;
+    consent: ConsentValue | null;
+    consentDate: Date | false;
+    bannerVisible: "main" | "gpc" | false;
+    modalVisible: "preference" | false;
+    showBanner: (_gpc?: boolean) => void;
+    hideBanner: () => void;
+    showModal: () => void;
+    hideModal: () => void;
+    grantAll: (_onlyMandatory?: boolean) => Promise<void>;
+    denyAll: (_includingMandatory?: boolean) => Promise<void>;
+    submitConsent: (_c: Partial<ConsentValue>) => Promise<void>;
+    reConsent: () => Promise<void>;
+    isCookieGranted: (_id: string) => boolean;
+    isCategoryGranted: (_id: string) => boolean;
+    switchLocale: (_locale: string) => void;
 };
 
 export { setConsentiWidget, useConsent };