@consenti/ui 0.4.0 → 0.6.0

package/README.md

@@ -183,14 +183,17 @@ const widget = new ConsentiSetup({
 
     // Client-side geo resolver (used only when api.enabled = false)
     // 'default' → browser timezone + navigator.language heuristic (built-in, zero deps)
-    // WidgetCountryResolverFn → custom async function: () => Promise<{ country, region, confidence }>
+    // WidgetCountryResolverFn → custom async function: ({ timezone, language, languages, locale }) => Promise<{ country, region, confidence }>
     geoDataProvider: 'default',
 
     // Only meaningful when api.enabled = false (ignored, with a warning, otherwise — the server
     // resolves the group in that mode). Only overrides country→group mapping; country/region
     // detection above always uses the embedded geo data.
     // 'default' → embedded map (default) | a URL string (fetched; the browser's own HTTP cache
-    // honors whatever Cache-Control/ETag the response sends) | an inline ComplianceMapData object
+    // honors whatever Cache-Control/ETag the response sends) | an inline ComplianceMapData object.
+    // A country the map doesn't list falls back to the embedded mapping, unless the document sets
+    // `override: true` — then it gets the strictest group ('opt-in'). Unlike the server, an omitted
+    // `override` is NOT true here: widget maps have always merged over the embedded mapping.
     complianceMap: 'default',
 
     // TCF (IAB Transparency & Consent Framework) client stub (optional) — see "TCF" section below
@@ -272,6 +275,47 @@ profileOverride: {
 no-op (same as omitting the key), the latter merges an empty object onto the existing category,
 changing nothing. Only an explicit `null` removes it.
 
+#### Replacing a whole map: `'*': null`
+
+Removing entries one by one doesn't scale when you want to *replace* a map: every built-in
+profile uses different button ids (`reject-optional`, `save-choices`, `manage-preferences`, …),
+and there are three `buttons` maps (`mainBanner`, `gpcBanner`, `preferenceModal`). Use the
+wildcard key `'*': null` to delete **every key of the base map that your override doesn't name**:
+
+```ts
+profileOverride: {
+  mainBanner: {
+    buttons: {
+      '*': null,                                        // drop all other built-in buttons
+      'accept-all': { text: 'Allow all' },              // kept — only its text changes
+      'my-button': { text: 'Custom', style: 'secondary', action: 'custom', cookies: '!' },
+    },
+  },
+  preferenceModal: {
+    buttons:    { '*': null, 'my-save': { text: 'Save', style: 'primary', action: 'submit' } },
+    categories: { '*': null, necessary: {}, analytics: {} },   // keep only these two categories
+  },
+},
+```
+
+- Keys you **name** are kept and merged onto their base value (so `'accept-all': { text }` keeps
+  its `style`/`action`/`cookies`); keys you **don't name** are deleted; new keys are added.
+- It works per map, so you choose which surfaces to replace — leave `gpcBanner` alone and it keeps
+  its built-in buttons.
+- `'*': null` alone empties the map. It works on any keyed map (`cookies` too), and under
+  `complianceGroupsOverride` and `widget.setProfile()`.
+- `'*'` is reserved in these maps and can't be used as a button/category id.
+- `widget.setProfile()` patches are replayed in order on the resolved profile (rather than being
+  folded together first), so `null` and `'*': null` deletes in a later `setProfile()` call are
+  honoured even after an earlier override.
+
+> **Compliance:** refusing must be as easy as accepting (GDPR Art. 7(3); CNIL/EDPB cookie-banner
+> guidance). If, after overrides, a `mainBanner`/`gpcBanner` has an "accept all" button
+> (`cookies: '*'`) but no reject (`cookies: '!'`) or `manage` button, the widget logs a
+> `console.warn`. Warnings are hidden by default — enable them with `verbose: true` or
+> `core: { console: ['warning'] }`. Keep a reject or manage path when
+> you replace the built-in buttons.
+
 ---
 
 ## Compliance Groups

package/dist/angular.d.cts

@@ -64,6 +64,10 @@ type ComplianceType = 'auto' | ComplianceGroupId | (string & {}) | Symbol;
 
 interface ComplianceMapData {
     version: string;
+    /** `true` (default): this map replaces the embedded one entirely, so only the countries listed here
+     * resolve (server side). `false`: `countries` is merged over the embedded map — a listed country
+     * replaces its embedded entry wholesale, every unlisted country keeps its built-in mapping. */
+    override?: boolean;
     countries: Record<string, CountryComplianceEntry>;
 }
 interface CountryComplianceEntry {
@@ -83,6 +87,9 @@ interface ConsentDbRecord {
     tenantId: string;
     visitorId: string;
     profileId: string;
+    /** The profile's `version` when this consent was last given — with `profileId`, pins the exact
+     * on-disk snapshot (the banner text the visitor saw). Absent on records from before it was tracked. */
+    profileVersion?: number;
     locale: string;
     consentJson: ConsentValue;
     gpcDetected: boolean;
@@ -281,7 +288,12 @@ interface ResolvedProfile {
     /** Apply WCAG 2.1 AA accessibility enhancements to the widget. */
     enhanceAccessibility?: boolean;
 }
-type WidgetCountryResolverFn = () => Promise<{
+type WidgetCountryResolverFn = (hints: {
+    timezone: string;
+    language: string;
+    languages: string[];
+    locale: string;
+}) => Promise<{
     country: string | null;
     region: string | null;
     confidence: number;
@@ -340,8 +352,11 @@ interface ComplianceWidgetConfig {
      * document from (the browser's own HTTP cache honors whatever `Cache-Control`/`ETag` the
      * response sends — no custom caching here), or an inline operator-supplied `ComplianceMapData`
      * object. Invalid data from either a URL or an object logs a warning and falls back to
-     * `'default'`. Only overrides the country→group mapping — country/region detection itself
-     * always uses the embedded geo data. */
+     * `'default'`. Only overrides the country→group mapping — country/region detection itself always
+     * uses the embedded geo data. A country the map doesn't list falls back to the embedded mapping
+     * unless the document sets `override: true` (then it gets the strictest group, `'opt-in'`).
+     * Unlike the server, an omitted `override` is NOT `true` here: widget maps have always merged
+     * over the embedded mapping, and that stays the default. */
     complianceMap?: 'default' | string | ComplianceMapData;
     tcf?: TcfWidgetConfig;
     gpp?: GppWidgetConfig;
@@ -622,6 +637,7 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
     private initializing;
     private profile;
     private resolvedBase;
+    private profilePatches;
     /** cookieId → Category lookup, rebuilt whenever `profile` changes. Avoids rescanning categories on every consent action. */
     private categoryIndex;
     /** Watchers created by the declarative `data-consenti-*` DOM scan — destroyed alongside the widget since they have no other owner. */
@@ -677,6 +693,14 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      * cookies per compliance group (built-in or custom) without authoring a separate profile for
      * each one. Applied before `profileOverride`, which still always wins as the final catch-all. */
     private applyComplianceGroupOverride;
+    /**
+     * Applied in order: compliance-group override → `config.profileOverride` → each `setProfile()`
+     * patch. The `setProfile()` patches are kept as a list and replayed, not folded into one
+     * object, because folding runs `deepMerge` patch-onto-patch, which consumes `null`/`'*': null`
+     * delete markers before they ever reach the profile they were meant to delete from.
+     */
+    private applyProfileOverrides;
+    private warnIfAcceptOnly;
     /**
      * Whether `window.__tcfapi`/`window.__gpp` should stay uninstalled because the corresponding
      * server-side registration (`compliance.tcf`/`compliance.gpp`) is unconfirmed (cmpId/cmpVersion

package/dist/angular.d.ts

@@ -64,6 +64,10 @@ type ComplianceType = 'auto' | ComplianceGroupId | (string & {}) | Symbol;
 
 interface ComplianceMapData {
     version: string;
+    /** `true` (default): this map replaces the embedded one entirely, so only the countries listed here
+     * resolve (server side). `false`: `countries` is merged over the embedded map — a listed country
+     * replaces its embedded entry wholesale, every unlisted country keeps its built-in mapping. */
+    override?: boolean;
     countries: Record<string, CountryComplianceEntry>;
 }
 interface CountryComplianceEntry {
@@ -83,6 +87,9 @@ interface ConsentDbRecord {
     tenantId: string;
     visitorId: string;
     profileId: string;
+    /** The profile's `version` when this consent was last given — with `profileId`, pins the exact
+     * on-disk snapshot (the banner text the visitor saw). Absent on records from before it was tracked. */
+    profileVersion?: number;
     locale: string;
     consentJson: ConsentValue;
     gpcDetected: boolean;
@@ -281,7 +288,12 @@ interface ResolvedProfile {
     /** Apply WCAG 2.1 AA accessibility enhancements to the widget. */
     enhanceAccessibility?: boolean;
 }
-type WidgetCountryResolverFn = () => Promise<{
+type WidgetCountryResolverFn = (hints: {
+    timezone: string;
+    language: string;
+    languages: string[];
+    locale: string;
+}) => Promise<{
     country: string | null;
     region: string | null;
     confidence: number;
@@ -340,8 +352,11 @@ interface ComplianceWidgetConfig {
      * document from (the browser's own HTTP cache honors whatever `Cache-Control`/`ETag` the
      * response sends — no custom caching here), or an inline operator-supplied `ComplianceMapData`
      * object. Invalid data from either a URL or an object logs a warning and falls back to
-     * `'default'`. Only overrides the country→group mapping — country/region detection itself
-     * always uses the embedded geo data. */
+     * `'default'`. Only overrides the country→group mapping — country/region detection itself always
+     * uses the embedded geo data. A country the map doesn't list falls back to the embedded mapping
+     * unless the document sets `override: true` (then it gets the strictest group, `'opt-in'`).
+     * Unlike the server, an omitted `override` is NOT `true` here: widget maps have always merged
+     * over the embedded mapping, and that stays the default. */
     complianceMap?: 'default' | string | ComplianceMapData;
     tcf?: TcfWidgetConfig;
     gpp?: GppWidgetConfig;
@@ -622,6 +637,7 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
     private initializing;
     private profile;
     private resolvedBase;
+    private profilePatches;
     /** cookieId → Category lookup, rebuilt whenever `profile` changes. Avoids rescanning categories on every consent action. */
     private categoryIndex;
     /** Watchers created by the declarative `data-consenti-*` DOM scan — destroyed alongside the widget since they have no other owner. */
@@ -677,6 +693,14 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      * cookies per compliance group (built-in or custom) without authoring a separate profile for
      * each one. Applied before `profileOverride`, which still always wins as the final catch-all. */
     private applyComplianceGroupOverride;
+    /**
+     * Applied in order: compliance-group override → `config.profileOverride` → each `setProfile()`
+     * patch. The `setProfile()` patches are kept as a list and replayed, not folded into one
+     * object, because folding runs `deepMerge` patch-onto-patch, which consumes `null`/`'*': null`
+     * delete markers before they ever reach the profile they were meant to delete from.
+     */
+    private applyProfileOverrides;
+    private warnIfAcceptOnly;
     /**
      * Whether `window.__tcfapi`/`window.__gpp` should stay uninstalled because the corresponding
      * server-side registration (`compliance.tcf`/`compliance.gpp`) is unconfirmed (cmpId/cmpVersion

package/dist/index.d.ts

@@ -64,6 +64,10 @@ type ComplianceType = 'auto' | ComplianceGroupId | (string & {}) | Symbol;
 
 interface ComplianceMapData {
     version: string;
+    /** `true` (default): this map replaces the embedded one entirely, so only the countries listed here
+     * resolve (server side). `false`: `countries` is merged over the embedded map — a listed country
+     * replaces its embedded entry wholesale, every unlisted country keeps its built-in mapping. */
+    override?: boolean;
     countries: Record<string, CountryComplianceEntry>;
 }
 interface CountryComplianceEntry {
@@ -83,6 +87,9 @@ interface ConsentDbRecord {
     tenantId: string;
     visitorId: string;
     profileId: string;
+    /** The profile's `version` when this consent was last given — with `profileId`, pins the exact
+     * on-disk snapshot (the banner text the visitor saw). Absent on records from before it was tracked. */
+    profileVersion?: number;
     locale: string;
     consentJson: ConsentValue;
     gpcDetected: boolean;
@@ -401,7 +408,12 @@ interface ResolvedProfile {
     /** Apply WCAG 2.1 AA accessibility enhancements to the widget. */
     enhanceAccessibility?: boolean;
 }
-type WidgetCountryResolverFn = () => Promise<{
+type WidgetCountryResolverFn = (hints: {
+    timezone: string;
+    language: string;
+    languages: string[];
+    locale: string;
+}) => Promise<{
     country: string | null;
     region: string | null;
     confidence: number;
@@ -460,8 +472,11 @@ interface ComplianceWidgetConfig {
      * document from (the browser's own HTTP cache honors whatever `Cache-Control`/`ETag` the
      * response sends — no custom caching here), or an inline operator-supplied `ComplianceMapData`
      * object. Invalid data from either a URL or an object logs a warning and falls back to
-     * `'default'`. Only overrides the country→group mapping — country/region detection itself
-     * always uses the embedded geo data. */
+     * `'default'`. Only overrides the country→group mapping — country/region detection itself always
+     * uses the embedded geo data. A country the map doesn't list falls back to the embedded mapping
+     * unless the document sets `override: true` (then it gets the strictest group, `'opt-in'`).
+     * Unlike the server, an omitted `override` is NOT `true` here: widget maps have always merged
+     * over the embedded mapping, and that stays the default. */
     complianceMap?: 'default' | string | ComplianceMapData;
     tcf?: TcfWidgetConfig;
     gpp?: GppWidgetConfig;
@@ -789,6 +804,7 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
     private initializing;
     private profile;
     private resolvedBase;
+    private profilePatches;
     /** cookieId → Category lookup, rebuilt whenever `profile` changes. Avoids rescanning categories on every consent action. */
     private categoryIndex;
     /** Watchers created by the declarative `data-consenti-*` DOM scan — destroyed alongside the widget since they have no other owner. */
@@ -844,6 +860,14 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      * cookies per compliance group (built-in or custom) without authoring a separate profile for
      * each one. Applied before `profileOverride`, which still always wins as the final catch-all. */
     private applyComplianceGroupOverride;
+    /**
+     * Applied in order: compliance-group override → `config.profileOverride` → each `setProfile()`
+     * patch. The `setProfile()` patches are kept as a list and replayed, not folded into one
+     * object, because folding runs `deepMerge` patch-onto-patch, which consumes `null`/`'*': null`
+     * delete markers before they ever reach the profile they were meant to delete from.
+     */
+    private applyProfileOverrides;
+    private warnIfAcceptOnly;
     /**
      * Whether `window.__tcfapi`/`window.__gpp` should stay uninstalled because the corresponding
      * server-side registration (`compliance.tcf`/`compliance.gpp`) is unconfirmed (cmpId/cmpVersion