@madgex/design-system 14.1.0 → 14.3.0

package/src/components/consent-gate/consent-gate.spec.js

@@ -0,0 +1,582 @@
+/* eslint-disable n/no-unsupported-features/node-builtins -- jsdom test env */
+// eslint-disable-next-line n/no-unpublished-import
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { MdsConsentGate } from './consent-gate.js';
+import { grant, revoke, setConsentAdapter } from './consent-store.js';
+
+if (!customElements.get('mds-consent-gate')) {
+  customElements.define('mds-consent-gate', MdsConsentGate);
+}
+
+const CATEGORY = 'test-provider';
+const EMBED_URL = 'https://example.com/embed/abc';
+
+function gateHtml({ category = CATEGORY, embedUrl = EMBED_URL, extra = '' } = {}) {
+  return `
+    <mds-consent-gate category="${category}" ${extra}>
+      <template><iframe src="${embedUrl}" title="Test embed"></iframe></template>
+      <a slot="fallback" href="https://example.com">View on Example</a>
+    </mds-consent-gate>
+  `;
+}
+
+describe('MdsConsentGate', () => {
+  let container;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    revoke(CATEGORY);
+    revoke('other-provider');
+    localStorage.clear();
+  });
+
+  afterEach(() => {
+    container.remove();
+    revoke(CATEGORY);
+    revoke('other-provider');
+    setConsentAdapter(null);
+    localStorage.clear();
+  });
+
+  describe('skeleton', () => {
+    it('registers as the mds-consent-gate custom element', () => {
+      expect(customElements.get('mds-consent-gate')).toBe(MdsConsentGate);
+    });
+
+    it('mounts in light DOM', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.shadowRoot).toBeNull();
+    });
+
+    it('attaches a [part="placeholder"] and [part="content"] in light DOM', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.querySelector('[part="placeholder"]')).toBeTruthy();
+      expect(el.querySelector('[part="content"]')).toBeTruthy();
+    });
+  });
+
+  describe('pre-consent', () => {
+    it('does not clone template content into [part=content]', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.querySelector('[part="content"]').children.length).toBe(0);
+    });
+
+    it('VPPA invariant: no <iframe> anywhere in document before consent', () => {
+      container.innerHTML = gateHtml();
+      expect(document.querySelectorAll('iframe').length).toBe(0);
+    });
+
+    it('sets data-state="placeholder"', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.dataset.state).toBe('placeholder');
+    });
+  });
+
+  describe('placeholder', () => {
+    it('renders a consent message', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      const msg = el.querySelector('[part="consent-message"]');
+      expect(msg).toBeTruthy();
+      expect(msg.textContent.trim()).toBeTruthy();
+    });
+
+    it('renders an Accept button with default label', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      const btn = el.querySelector('button[part="accept"]');
+      expect(btn).toBeTruthy();
+      expect(btn.textContent.trim()).toBe('Load content');
+    });
+
+    it('renders custom acceptLabel via i18n', () => {
+      container.innerHTML = gateHtml({
+        extra: `i18n='${JSON.stringify({ acceptLabel: 'Watch video' })}'`,
+      });
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.querySelector('button[part="accept"]').textContent.trim()).toBe('Watch video');
+    });
+
+    it('renders custom consentMessage via i18n', () => {
+      container.innerHTML = gateHtml({
+        extra: `i18n='${JSON.stringify({ consentMessage: 'Custom message' })}'`,
+      });
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.querySelector('[part="consent-message"]').textContent.trim()).toBe('Custom message');
+    });
+
+    it('uses defaults when i18n JSON is invalid', () => {
+      container.innerHTML = gateHtml({ extra: `i18n='not-json'` });
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.querySelector('button[part="accept"]').textContent.trim()).toBe('Load content');
+      expect(el.querySelector('[part="consent-message"]').textContent.trim()).toBe(
+        'Loads content from a third-party provider, which may set cookies and collect personal data.',
+      );
+    });
+
+    it('partial i18n object uses defaults for missing keys', () => {
+      container.innerHTML = gateHtml({
+        extra: `i18n='${JSON.stringify({ acceptLabel: 'Go' })}'`,
+      });
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.querySelector('button[part="accept"]').textContent.trim()).toBe('Go');
+      expect(el.querySelector('[part="consent-message"]').textContent.trim()).toBe(
+        'Loads content from a third-party provider, which may set cookies and collect personal data.',
+      );
+    });
+
+    it('empty string in i18n falls back to default for that field', () => {
+      container.innerHTML = gateHtml({
+        extra: `i18n='${JSON.stringify({ acceptLabel: '', consentMessage: 'Only body' })}'`,
+      });
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.querySelector('button[part="accept"]').textContent.trim()).toBe('Load content');
+      expect(el.querySelector('[part="consent-message"]').textContent.trim()).toBe('Only body');
+    });
+
+    it('non-string i18n values fall back to defaults', () => {
+      container.innerHTML = gateHtml({
+        extra: `i18n='${JSON.stringify({ acceptLabel: 42, consentMessage: null })}'`,
+      });
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.querySelector('button[part="accept"]').textContent.trim()).toBe('Load content');
+      expect(el.querySelector('[part="consent-message"]').textContent.trim()).toBe(
+        'Loads content from a third-party provider, which may set cookies and collect personal data.',
+      );
+    });
+
+    it('parses array JSON as no overrides (defaults)', () => {
+      container.innerHTML = gateHtml({ extra: `i18n='[1,2]'` });
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.querySelector('button[part="accept"]').textContent.trim()).toBe('Load content');
+    });
+
+    it('handles consentMessage containing double quotes', () => {
+      container.innerHTML = gateHtml({
+        extra: `i18n='${JSON.stringify({ consentMessage: 'Say "yes" to load' })}'`,
+      });
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.querySelector('[part="consent-message"]').textContent.trim()).toBe('Say "yes" to load');
+    });
+
+    it('Accept button is described by consent-message for a11y', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      const btn = el.querySelector('button[part="accept"]');
+      const describedBy = btn.getAttribute('aria-describedby');
+      expect(describedBy).toBeTruthy();
+      expect(el.querySelector(`#${describedBy}`)).toBeTruthy();
+    });
+
+    it('updates i18n live via setAttribute', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      el.setAttribute('i18n', JSON.stringify({ acceptLabel: 'Hello', consentMessage: 'World' }));
+      expect(el.querySelector('button[part="accept"]').textContent.trim()).toBe('Hello');
+      expect(el.querySelector('[part="consent-message"]').textContent.trim()).toBe('World');
+    });
+
+    it('removeAttribute(i18n) restores defaults', () => {
+      container.innerHTML = gateHtml({
+        extra: `i18n='${JSON.stringify({ acceptLabel: 'Temp', consentMessage: 'Temp msg' })}'`,
+      });
+      const el = container.querySelector('mds-consent-gate');
+      el.removeAttribute('i18n');
+      expect(el.querySelector('button[part="accept"]').textContent.trim()).toBe('Load content');
+      expect(el.querySelector('[part="consent-message"]').textContent.trim()).toBe(
+        'Loads content from a third-party provider, which may set cookies and collect personal data.',
+      );
+    });
+  });
+
+  describe('heading slot', () => {
+    it('places heading slot content inside [part="heading-wrap"]', () => {
+      container.innerHTML = `
+        <mds-consent-gate category="${CATEGORY}">
+          <span slot="heading">My heading</span>
+          <template><iframe src="${EMBED_URL}" title="Test"></iframe></template>
+          <a slot="fallback" href="https://example.com">Fallback</a>
+        </mds-consent-gate>
+      `;
+      const el = container.querySelector('mds-consent-gate');
+      const wrap = el.querySelector(':scope > [part="heading-wrap"]');
+      expect(wrap).toBeTruthy();
+      const heading = wrap.querySelector('[slot="heading"]');
+      expect(heading).toBeTruthy();
+      expect(heading.textContent).toBe('My heading');
+    });
+  });
+
+  describe('fallback slot', () => {
+    it('keeps fallback slot content as a direct child of host', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      const fallback = el.querySelector(':scope > [slot="fallback"]');
+      expect(fallback).toBeTruthy();
+      expect(fallback.parentElement).toBe(el);
+    });
+  });
+
+  describe('clicking Accept', () => {
+    it('calls grant(category) on Accept click', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      el.querySelector('button[part="accept"]').click();
+      expect(localStorage.getItem('mds-consent')).toContain(CATEGORY);
+    });
+  });
+
+  describe('after grant', () => {
+    it('clones <template> content into [part="content"]', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      el.querySelector('button[part="accept"]').click();
+
+      const content = el.querySelector('[part="content"]');
+      expect(content.querySelector('iframe')).toBeTruthy();
+      expect(content.querySelector('iframe').getAttribute('src')).toBe(EMBED_URL);
+    });
+
+    it('iframe is in document after grant', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      el.querySelector('button[part="accept"]').click();
+      expect(document.querySelectorAll('iframe').length).toBe(1);
+    });
+
+    it('sets data-state="consented"', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      el.querySelector('button[part="accept"]').click();
+      expect(el.dataset.state).toBe('consented');
+    });
+  });
+
+  describe('script rehydration', () => {
+    it('<script> inside <template> is rehydrated into a fresh element after grant', () => {
+      container.innerHTML = `
+        <mds-consent-gate category="${CATEGORY}">
+          <template><script data-rehydrate-test>window.__mdsConsentGateTest = true;</script></template>
+        </mds-consent-gate>
+      `;
+      const el = container.querySelector('mds-consent-gate');
+      el.querySelector('button[part="accept"]').click();
+      const content = el.querySelector('[part="content"]');
+      const script = content.querySelector('script[data-rehydrate-test]');
+      expect(script).toBeTruthy();
+      const original = el.querySelector(':scope > template').content.querySelector('script');
+      expect(script).not.toBe(original);
+    });
+  });
+
+  describe('mds-consent-gate:grant event', () => {
+    it('fires with { category, container } on accept', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+
+      const events = [];
+      el.addEventListener('mds-consent-gate:grant', (e) => events.push(e.detail));
+      el.querySelector('button[part="accept"]').click();
+
+      expect(events.length).toBe(1);
+      expect(events[0].category).toBe(CATEGORY);
+      expect(events[0].container).toBeTruthy();
+      expect(events[0].container.querySelector('iframe')).toBeTruthy();
+    });
+
+    it('event bubbles and is composed', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+
+      let bubbled = false;
+      document.addEventListener(
+        'mds-consent-gate:grant',
+        () => {
+          bubbled = true;
+        },
+        { once: true },
+      );
+      el.querySelector('button[part="accept"]').click();
+      expect(bubbled).toBe(true);
+    });
+  });
+
+  describe('revoke', () => {
+    it('removes cloned content on revoke', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      el.querySelector('button[part="accept"]').click();
+      expect(el.querySelector('[part="content"]').children.length).toBeGreaterThan(0);
+
+      revoke(CATEGORY);
+
+      expect(el.querySelector('[part="content"]').children.length).toBe(0);
+    });
+
+    it('flips data-state back to "placeholder" on revoke', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      el.querySelector('button[part="accept"]').click();
+      revoke(CATEGORY);
+      expect(el.dataset.state).toBe('placeholder');
+    });
+
+    it('fires mds-consent-gate:revoke with { category }', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      el.querySelector('button[part="accept"]').click();
+
+      const events = [];
+      el.addEventListener('mds-consent-gate:revoke', (e) => events.push(e.detail));
+      revoke(CATEGORY);
+
+      expect(events.length).toBe(1);
+      expect(events[0].category).toBe(CATEGORY);
+    });
+
+    it('iframe is removed from document after revoke', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      el.querySelector('button[part="accept"]').click();
+      revoke(CATEGORY);
+      expect(document.querySelectorAll('iframe').length).toBe(0);
+    });
+  });
+
+  describe('no <template> child', () => {
+    it('sets data-state="error" with no Accept button', () => {
+      container.innerHTML = `
+        <mds-consent-gate category="${CATEGORY}">
+          <a slot="fallback" href="https://example.com">Fallback</a>
+        </mds-consent-gate>
+      `;
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.dataset.state).toBe('error');
+      expect(el.querySelector(':scope > [slot="fallback"]')).toBeTruthy();
+    });
+
+    it('dispatches mds-consent-gate:error with reason no-template', () => {
+      const events = [];
+      const handler = (e) => events.push(e.detail);
+      document.addEventListener('mds-consent-gate:error', handler);
+      container.innerHTML = `
+        <mds-consent-gate category="${CATEGORY}">
+          <a slot="fallback" href="https://example.com">Fallback</a>
+        </mds-consent-gate>
+      `;
+      document.removeEventListener('mds-consent-gate:error', handler);
+      expect(events.length).toBe(1);
+      expect(events[0].reason).toBe('no-template');
+    });
+  });
+
+  describe('no category attribute', () => {
+    it('sets data-state="error"', () => {
+      container.innerHTML = `
+        <mds-consent-gate>
+          <template><iframe src="${EMBED_URL}" title="Test"></iframe></template>
+          <a slot="fallback" href="https://example.com">Fallback</a>
+        </mds-consent-gate>
+      `;
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.dataset.state).toBe('error');
+    });
+
+    it('dispatches mds-consent-gate:error with reason no-category', () => {
+      const events = [];
+      const handler = (e) => events.push(e.detail);
+      document.addEventListener('mds-consent-gate:error', handler);
+      container.innerHTML = `
+        <mds-consent-gate>
+          <template><iframe src="${EMBED_URL}" title="Test"></iframe></template>
+        </mds-consent-gate>
+      `;
+      document.removeEventListener('mds-consent-gate:error', handler);
+      expect(events.length).toBe(1);
+      expect(events[0].reason).toBe('no-category');
+    });
+  });
+
+  describe('bare-content guard', () => {
+    it('warns and dispatches error for direct-child <iframe> outside <template>', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const events = [];
+      const handler = (e) => events.push(e.detail);
+      document.addEventListener('mds-consent-gate:error', handler);
+
+      container.innerHTML = `
+        <mds-consent-gate category="${CATEGORY}">
+          <iframe src="${EMBED_URL}" title="Test"></iframe>
+        </mds-consent-gate>
+      `;
+
+      document.removeEventListener('mds-consent-gate:error', handler);
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('mds-consent-gate'));
+      expect(events.some((e) => e.reason === 'unwrapped-content')).toBe(true);
+      warnSpy.mockRestore();
+    });
+  });
+
+  describe('multiple gates, same category', () => {
+    it('single grant reveals all gates with that category', () => {
+      container.innerHTML = `
+        ${gateHtml()}
+        ${gateHtml()}
+      `;
+      const [gate1, gate2] = container.querySelectorAll('mds-consent-gate');
+
+      gate1.querySelector('button[part="accept"]').click();
+
+      expect(gate1.dataset.state).toBe('consented');
+      expect(gate2.dataset.state).toBe('consented');
+    });
+  });
+
+  describe('template-less gate ignores grant events', () => {
+    it('does not re-render or error when category is granted but no template exists', () => {
+      container.innerHTML = `
+        <mds-consent-gate category="${CATEGORY}">
+          <a slot="fallback" href="https://example.com">Fallback</a>
+        </mds-consent-gate>
+      `;
+      const el = container.querySelector('mds-consent-gate');
+      const errorEvents = [];
+      el.addEventListener('mds-consent-gate:error', (e) => errorEvents.push(e));
+
+      grant(CATEGORY);
+
+      expect(el.querySelector('[part="content"]').children.length).toBe(0);
+      expect(errorEvents.length).toBe(0);
+    });
+  });
+
+  describe('already consented at mount', () => {
+    it('clones content synchronously on connect, no placeholder shown', () => {
+      grant(CATEGORY);
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+
+      expect(el.dataset.state).toBe('consented');
+      expect(el.querySelector('[part="content"]').querySelector('iframe')).toBeTruthy();
+    });
+
+    it('fires mds-consent-gate:grant on mount when already consented', () => {
+      grant(CATEGORY);
+      const events = [];
+      const handler = (e) => events.push(e.detail);
+      document.addEventListener('mds-consent-gate:grant', handler);
+      container.innerHTML = gateHtml();
+      document.removeEventListener('mds-consent-gate:grant', handler);
+      expect(events.length).toBe(1);
+      expect(events[0].category).toBe(CATEGORY);
+    });
+  });
+
+  describe('category attribute change', () => {
+    it('removes content and re-evaluates consent for new category', () => {
+      grant(CATEGORY);
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.dataset.state).toBe('consented');
+
+      el.setAttribute('category', 'other-provider');
+
+      expect(el.dataset.state).toBe('placeholder');
+      expect(el.querySelector('[part="content"]').children.length).toBe(0);
+    });
+
+    it('clones content when new category is already consented', () => {
+      grant('other-provider');
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.dataset.state).toBe('placeholder');
+
+      el.setAttribute('category', 'other-provider');
+      expect(el.dataset.state).toBe('consented');
+    });
+  });
+
+  describe('custom adapter (setConsentAdapter)', () => {
+    it('gate reacts to programmatic consent changes via custom adapter', () => {
+      let listener;
+      setConsentAdapter({
+        has: () => false,
+        grant: () => {},
+        revoke: () => {},
+        subscribe: (fn) => {
+          listener = fn;
+          return () => {};
+        },
+      });
+
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.dataset.state).toBe('placeholder');
+
+      listener(CATEGORY, true);
+
+      expect(el.dataset.state).toBe('consented');
+    });
+  });
+
+  describe('disconnectedCallback', () => {
+    it('removes cloned content from light DOM on disconnect', () => {
+      grant(CATEGORY);
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.querySelector('[part="content"]')?.querySelector('iframe')).toBeTruthy();
+
+      el.remove();
+      expect(el.querySelector('[part="content"]')?.querySelector('iframe')).toBeFalsy();
+    });
+
+    it('unsubscribes from consent changes after disconnect', () => {
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+
+      el.remove();
+      grant(CATEGORY);
+      expect(el.dataset.state).not.toBe('consented');
+    });
+  });
+
+  describe('reconnect after consent', () => {
+    it('re-clones content on reconnect when category is consented', () => {
+      grant(CATEGORY);
+      container.innerHTML = gateHtml();
+      const el = container.querySelector('mds-consent-gate');
+
+      el.remove();
+
+      container.appendChild(el);
+      expect(el.dataset.state).toBe('consented');
+      expect(el.querySelector('[part="content"]').querySelector('iframe')).toBeTruthy();
+    });
+  });
+
+  describe('style hooks', () => {
+    it('aspect-ratio attr sets --mds-consent-gate-aspect-ratio', () => {
+      container.innerHTML = gateHtml({ extra: 'aspect-ratio="16 / 9"' });
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.style.getPropertyValue('--mds-consent-gate-aspect-ratio')).toBe('16 / 9');
+    });
+
+    it('preview-image attr sets --mds-consent-gate-preview-image as url()', () => {
+      container.innerHTML = gateHtml({ extra: 'preview-image="/img/thumb.jpg"' });
+      const el = container.querySelector('mds-consent-gate');
+      expect(el.style.getPropertyValue('--mds-consent-gate-preview-image')).toBe('url("/img/thumb.jpg")');
+    });
+
+    it('removing aspect-ratio attr removes the custom property', () => {
+      container.innerHTML = gateHtml({ extra: 'aspect-ratio="4 / 3"' });
+      const el = container.querySelector('mds-consent-gate');
+      el.removeAttribute('aspect-ratio');
+      expect(el.style.getPropertyValue('--mds-consent-gate-aspect-ratio')).toBe('');
+    });
+  });
+});

package/src/components/consent-gate/consent-store.js

@@ -0,0 +1,109 @@
+/* eslint-disable n/no-unsupported-features/node-builtins -- browser-only module */
+/**
+ * Per-category consent state for `<mds-consent-gate>`.
+ *
+ * Default backend persists to `localStorage` under `mds-consent` and emits a
+ * window-level `mds-consent:change` event. Replace via `setConsentAdapter()`
+ * to delegate to a CMP (e.g. OneTrust). Subscriptions registered via
+ * `subscribe()` survive adapter swaps.
+ *
+ * `has` MUST be synchronous so the element can pick its initial render state
+ * without a microtask round-trip.
+ *
+ * Adapter contract:
+ *   has(category): boolean      — synchronous
+ *   grant(category): void
+ *   revoke(category): void
+ *   subscribe(fn): () => void   — fn(category, granted)
+ */
+
+const STORAGE_KEY = 'mds-consent';
+const CHANGE_EVENT = 'mds-consent:change';
+
+function createDefaultBackend() {
+  const listeners = new Set();
+  let state = read();
+
+  function read() {
+    try {
+      const raw = typeof localStorage !== 'undefined' ? localStorage.getItem(STORAGE_KEY) : null;
+      return raw ? JSON.parse(raw) : {};
+    } catch {
+      return {};
+    }
+  }
+
+  function persist() {
+    try {
+      if (typeof localStorage !== 'undefined') {
+        localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+      }
+    } catch {
+      // localStorage may be disabled (private browsing, quota); fail silently.
+    }
+  }
+
+  function emit(category, granted) {
+    for (const fn of listeners) fn(category, granted);
+    if (typeof window !== 'undefined') {
+      window.dispatchEvent(new CustomEvent(CHANGE_EVENT, { detail: { category, granted } }));
+    }
+  }
+
+  return {
+    has(category) {
+      return state[category] === true;
+    },
+    grant(category) {
+      if (state[category] === true) return;
+      state[category] = true;
+      persist();
+      emit(category, true);
+    },
+    revoke(category) {
+      if (!state[category]) return;
+      delete state[category];
+      persist();
+      emit(category, false);
+    },
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+  };
+}
+
+const subscribers = new Set();
+function fanout(category, granted) {
+  for (const fn of subscribers) fn(category, granted);
+}
+
+let active = createDefaultBackend();
+let unbind = active.subscribe(fanout);
+
+export function has(category) {
+  return active.has(category);
+}
+
+export function grant(category) {
+  active.grant(category);
+}
+
+export function revoke(category) {
+  active.revoke(category);
+}
+
+export function subscribe(fn) {
+  subscribers.add(fn);
+  return () => subscribers.delete(fn);
+}
+
+/**
+ * Replace the consent backend. Pass `null` to restore the default
+ * localStorage backend. Existing `subscribe()` registrations are preserved.
+ */
+export function setConsentAdapter(adapter) {
+  unbind?.();
+  active = adapter || createDefaultBackend();
+  unbind = active.subscribe(fanout);
+}