@inneropen/marvin-astro 2.0.0 → 2.1.1

package/src/components/consent.ts

@@ -0,0 +1,246 @@
+/**
+ * The consent runtime behind `<ConsentBanner>`.
+ *
+ * It remembers one visitor choice per consent version in `localStorage['marvin-consent']`, turns
+ * inert markup on only for categories the visitor allowed, and exposes `window.marvinConsent`.
+ * Nothing optional runs until a valid choice exists, and without JavaScript nothing runs at all.
+ *
+ * Gating markup (the category list is space or comma separated; every listed category must be
+ * allowed, `necessary` always is):
+ *
+ *   <script type="text/plain" data-consent="analytics" data-src="https://…"></script>
+ *   <script type="text/plain" data-consent="analytics">inline code</script>
+ *   <template data-consent="marketing"><iframe …></iframe></template>
+ *
+ * An unknown category never activates. `data-type="module"` restores a module type.
+ *
+ * This module has no imports so the browser bundle stays small (measured under 3 KB gzipped).
+ */
+
+export type ConsentCategoryName = 'preferences' | 'analytics' | 'marketing';
+export type ConsentChoices = Record<ConsentCategoryName, boolean>;
+
+export type ConsentRecord = {
+  v: 1;
+  /** The `consentVersion()` the choice answers. */
+  version: string;
+  choices: ConsentChoices;
+  /** Epoch milliseconds the choice was made. */
+  at: number;
+};
+
+export type MarvinConsentApi = {
+  /** The current valid record, or `null` while the visitor still has to choose. */
+  get(): ConsentRecord | null;
+  /** `necessary` is always true; others need a valid choice that allows them. */
+  has(category: string): boolean;
+  /** Record a choice (unspecified categories keep their current value), then apply it. */
+  set(choices: Partial<ConsentChoices>): void;
+  /** Open the Customise dialog. */
+  open(): void;
+};
+
+export type ConsentDetail = { choices: ConsentChoices; version: string; initial: boolean };
+
+export type InstallOptions = {
+  /** Reload after a withdrawal. Defaults to `location.reload()`. */
+  reload?: () => void;
+  /** Clock override for tests. */
+  now?: () => number;
+};
+
+declare global {
+  interface Window {
+    marvinConsent?: MarvinConsentApi;
+  }
+}
+
+export const CONSENT_KEY = 'marvin-consent';
+const CATEGORIES: readonly ConsentCategoryName[] = ['preferences', 'analytics', 'marketing'];
+const DAY = 864e5;
+const GATED = 'script[type="text/plain"][data-consent],template[data-consent]';
+const FACADE = 'button[data-marvin-embed-attrs],button[data-marvin-embed-src]';
+
+export function installConsent(doc: Document, options: InstallOptions = {}): MarvinConsentApi | undefined {
+  const win = doc.defaultView as Window & typeof globalThis;
+  const root = doc.querySelector<HTMLElement>('[data-marvin-consent-banner]');
+  if (!win || !root) return undefined;
+  if (win.marvinConsent) return win.marvinConsent;
+
+  const now = options.now ?? Date.now;
+  const reload = options.reload ?? (() => win.location.reload());
+  const bar = root.querySelector<HTMLElement>('[data-marvin-consent-bar]');
+  const dialog = root.querySelector<HTMLDialogElement>('dialog');
+  const version = root.dataset.version ?? '';
+  const maxAge = (Number(root.dataset.maxAge) || 180) * DAY;
+  const offered = (root.dataset.categories ?? '').split(' ').filter(Boolean) as ConsentCategoryName[];
+  const embedsCategory = root.dataset.embeds;
+  let cookieNames: Record<string, string[]> = {};
+  try {
+    cookieNames = JSON.parse(root.dataset.cookies ?? '{}');
+  } catch {
+    /* no withdrawal cleanup, the reload still stops the scripts */
+  }
+
+  let record: ConsentRecord | null = null;
+  let opener: Element | null = null;
+
+  const read = (): ConsentRecord | null => {
+    try {
+      const raw = JSON.parse(win.localStorage.getItem(CONSENT_KEY) ?? 'null');
+      if (
+        raw?.v === 1 &&
+        raw.version === version &&
+        typeof raw.at === 'number' &&
+        now() - raw.at < maxAge &&
+        raw.choices
+      ) {
+        return {
+          v: 1,
+          version,
+          at: raw.at,
+          choices: Object.fromEntries(CATEGORIES.map((c) => [c, raw.choices[c] === true])) as ConsentChoices,
+        };
+      }
+    } catch {
+      /* storage blocked or corrupt: ask again */
+    }
+    return null;
+  };
+
+  const allowed = (category: string) => category === 'necessary' || record?.choices[category as ConsentCategoryName] === true;
+
+  const activate = () => {
+    doc.querySelectorAll<HTMLElement>(GATED).forEach((el) => {
+      const needs = (el.dataset.consent ?? '').split(/[\s,]+/).filter(Boolean);
+      if (!needs.length || !needs.every(allowed)) return;
+      if (el instanceof win.HTMLTemplateElement) {
+        el.replaceWith(doc.importNode(el.content, true));
+        return;
+      }
+      const script = doc.createElement('script');
+      script.async = false;
+      for (const { name, value } of Array.from(el.attributes)) {
+        if (!['type', 'data-consent', 'data-src', 'data-type'].includes(name)) script.setAttribute(name, value);
+      }
+      if (el.dataset.src) script.src = el.dataset.src;
+      if (el.dataset.type) script.type = el.dataset.type;
+      script.text = el.textContent ?? '';
+      el.replaceWith(script);
+    });
+  };
+
+  /** Delete first-party cookies by name; a trailing `*` matches a prefix. Host and parent domains. */
+  const expire = (patterns: string[] = []) => {
+    const present = doc.cookie.split(';').map((pair) => pair.split('=')[0]!.trim()).filter(Boolean);
+    const labels = win.location.hostname.split('.');
+    const domains = ['', ...labels.slice(0, -1).map((_, i) => labels.slice(i).join('.'))];
+    if (labels.length < 2) domains.push(win.location.hostname);
+    for (const pattern of patterns) {
+      const prefix = pattern.endsWith('*') ? pattern.slice(0, -1) : null;
+      for (const name of present.filter((n) => (prefix === null ? n === pattern : n.startsWith(prefix)))) {
+        for (const domain of domains) {
+          doc.cookie = `${name}=;expires=Thu, 01 Jan 1970 00:00:00 GMT;max-age=0;path=/${domain ? `;domain=${domain}` : ''}`;
+        }
+      }
+    }
+  };
+
+  const emit = (initial: boolean) => {
+    if (!record) return;
+    const detail: ConsentDetail = { choices: { ...record.choices }, version, initial };
+    doc.dispatchEvent(new win.CustomEvent('marvin:consent', { detail }));
+  };
+
+  const loadEmbeds = () => {
+    // The facades' own delegated handler does the work; this only presses them.
+    if (embedsCategory && allowed(embedsCategory)) doc.querySelectorAll<HTMLElement>(FACADE).forEach((b) => b.click());
+  };
+
+  const focusAfter = () => {
+    const back = opener && doc.contains(opener) && (!bar?.contains(opener) || !bar.hidden) ? opener : null;
+    const target = (back ?? doc.querySelector<HTMLElement>('main,[role="main"]')) as HTMLElement | null;
+    if (target && !target.matches('a,button,input,select,textarea,[tabindex]')) target.setAttribute('tabindex', '-1');
+    target?.focus({ preventScroll: true });
+  };
+
+  const closeDialog = () => {
+    if (dialog?.open) typeof dialog.close === 'function' ? dialog.close() : dialog.removeAttribute('open');
+    focusAfter();
+  };
+
+  const api: MarvinConsentApi = {
+    get: () => (record ? { ...record, choices: { ...record.choices } } : null),
+    has: allowed,
+    set(choices) {
+      const previous = record;
+      const next: ConsentChoices = { preferences: false, analytics: false, marketing: false };
+      for (const c of CATEGORIES) next[c] = choices[c] ?? previous?.choices[c] ?? false;
+      record = { v: 1, version, choices: next, at: now() };
+      try {
+        win.localStorage.setItem(CONSENT_KEY, JSON.stringify(record));
+      } catch {
+        /* kept in memory for this page only */
+      }
+      CATEGORIES.filter((c) => !next[c]).forEach((c) => expire(cookieNames[c]));
+      if (bar) bar.hidden = true;
+      emit(false);
+      if (CATEGORIES.some((c) => previous?.choices[c] && !next[c])) {
+        reload();
+        return;
+      }
+      activate();
+      loadEmbeds();
+    },
+    open() {
+      if (!dialog) return;
+      dialog.querySelectorAll<HTMLInputElement>('input[data-marvin-consent-category]').forEach((input) => {
+        input.checked = record?.choices[input.dataset.marvinConsentCategory as ConsentCategoryName] === true;
+      });
+      if (typeof dialog.showModal === 'function') dialog.showModal();
+      else dialog.setAttribute('open', '');
+    },
+  };
+
+  const choose = (accept: boolean) =>
+    api.set(Object.fromEntries(CATEGORIES.map((c) => [c, accept && offered.includes(c)])));
+
+  doc.addEventListener('click', (event) => {
+    const mouse = event as MouseEvent;
+    const target = (event.target as Element | null)?.closest?.('[data-marvin-consent-action],[data-marvin-consent-open]');
+    if (!target || mouse.button || mouse.metaKey || mouse.ctrlKey || mouse.shiftKey) return;
+    event.preventDefault();
+    const action = target.getAttribute('data-marvin-consent-action');
+    if (!action || action === 'customise') {
+      opener = target;
+      api.open();
+      return;
+    }
+    if (action === 'save') {
+      const picked: Partial<ConsentChoices> = {};
+      dialog?.querySelectorAll<HTMLInputElement>('input[data-marvin-consent-category]').forEach((input) => {
+        picked[input.dataset.marvinConsentCategory as ConsentCategoryName] = input.checked;
+      });
+      api.set(picked);
+    } else {
+      opener = target;
+      choose(action === 'accept');
+    }
+    closeDialog();
+  });
+  dialog?.addEventListener('close', focusAfter);
+
+  win.marvinConsent = api;
+  record = read();
+  if (record) {
+    activate();
+    // Listeners attached during page load (later module scripts) must not miss the initial event.
+    win.setTimeout(() => {
+      emit(true);
+      loadEmbeds();
+    }, 0);
+  } else if (bar) {
+    bar.hidden = false;
+  }
+  return api;
+}

package/src/components/index.ts

@@ -22,8 +22,20 @@ export { default as FormRenderer } from './FormRenderer.astro';
 export { default as Embed } from './Embed.astro';
 export { default as LinkCard } from './LinkCard.astro';
 export { default as EmbedLoader } from './EmbedLoader.astro';
+export { default as CookieTable } from './CookieTable.astro';
+export { default as ProcessorTable } from './ProcessorTable.astro';
+export { default as PrivacyPolicy } from './PrivacyPolicy.astro';
+export { default as ConsentBanner } from './ConsentBanner.astro';
+export { default as CookieSettingsLink } from './CookieSettingsLink.astro';
 export { marvinIntegration } from './integration.js';
 export { iframeAttributes, installEmbedLoader, isAllowedFrameSrc } from './embed-frame.js';
+export { installConsent } from './consent.js';
+export type {
+  ConsentChoices,
+  ConsentDetail,
+  ConsentRecord,
+  MarvinConsentApi,
+} from './consent.js';
 
 // The framework-agnostic renderer logic, so one import covers a renderer component's needs.
 export * from '../renderers/index.js';

package/src/components/privacy-text.ts

@@ -0,0 +1,149 @@
+/**
+ * Neutral English defaults for the privacy and consent components. Every string can be replaced
+ * per site through the components' `labels` props; Marvin-editable text is a later step.
+ */
+import type { CookieCategory } from '../privacy.js';
+
+/** Default consent lifetime, ~6 months. Refusals last as long as acceptances. */
+export const DEFAULT_MAX_AGE_DAYS = 180;
+
+/** The storage key the consent runtime writes; disclosed as a necessary entry. */
+export const CONSENT_STORAGE_KEY = 'marvin-consent';
+
+export const CATEGORY_LABELS: Record<CookieCategory, string> = {
+  necessary: 'Necessary',
+  preferences: 'Preferences',
+  analytics: 'Analytics',
+  marketing: 'Marketing',
+};
+
+export const CATEGORY_DESCRIPTIONS: Record<CookieCategory, string> = {
+  necessary: 'Needed for the site to work, or to remember a choice you made. Always on.',
+  preferences: 'Remember settings such as your language or theme.',
+  analytics: 'Help us understand how the site is used so we can improve it.',
+  marketing: 'Used to show relevant content or measure campaigns.',
+};
+
+export type PrivacyLabels = {
+  // Tables
+  cookieName: string;
+  provider: string;
+  purpose: string;
+  duration: string;
+  processor: string;
+  data: string;
+  region: string;
+  transferBasis: string;
+  links: string;
+  dpa: string;
+  privacyPolicy: string;
+  thisSite: string;
+  consentCookiePurpose: string;
+  noscript: string;
+  // Policy page
+  controller: string;
+  legalName: string;
+  address: string;
+  contact: string;
+  euRepresentative: string;
+  dpo: string;
+  processors: string;
+  cookies: string;
+  lastReviewed: string;
+  changeSettings: string;
+  categories: Record<CookieCategory, string>;
+};
+
+export const DEFAULT_PRIVACY_LABELS: PrivacyLabels = {
+  cookieName: 'Name',
+  provider: 'Provider',
+  purpose: 'Purpose',
+  duration: 'Duration',
+  processor: 'Processor',
+  data: 'Data',
+  region: 'Region',
+  transferBasis: 'Transfer basis',
+  links: 'Links',
+  dpa: 'Data processing agreement',
+  privacyPolicy: 'Privacy policy',
+  thisSite: 'This site',
+  consentCookiePurpose: 'Remembers your cookie choices.',
+  noscript: 'Optional cookies are off because JavaScript is disabled.',
+  controller: 'Who is responsible for your data',
+  legalName: 'Controller',
+  address: 'Address',
+  contact: 'Contact',
+  euRepresentative: 'EU representative',
+  dpo: 'Data protection officer',
+  processors: 'Who else handles your data',
+  cookies: 'Cookies and similar storage',
+  lastReviewed: 'Last reviewed',
+  changeSettings: 'Change your cookie settings',
+  categories: CATEGORY_LABELS,
+};
+
+/** `labels` merged over the defaults (one level deep, plus `categories`). */
+export function privacyLabels(overrides?: Partial<Omit<PrivacyLabels, 'categories'>> & {
+  categories?: Partial<Record<CookieCategory, string>>;
+}): PrivacyLabels {
+  return {
+    ...DEFAULT_PRIVACY_LABELS,
+    ...overrides,
+    categories: { ...CATEGORY_LABELS, ...overrides?.categories },
+  };
+}
+
+/** 180 → "6 months", 365 → "12 months", 30 → "30 days". */
+export function formatMaxAge(days: number): string {
+  if (days >= 60) return `${Math.round(days / 30)} months`;
+  return `${days} ${days === 1 ? 'day' : 'days'}`;
+}
+
+export type ConsentLabels = {
+  title: string;
+  body: string;
+  acceptAll: string;
+  rejectAll: string;
+  customise: string;
+  save: string;
+  /** The "Cookie settings" link (`<CookieSettingsLink>`). */
+  settingsLink: string;
+  /** The link to the policy page, shown when `policyHref` is given. */
+  policyLink: string;
+  dialogTitle: string;
+  dialogBody: string;
+  cookiesList: string;
+  categories: Record<CookieCategory, string>;
+  categoryDescriptions: Record<CookieCategory, string>;
+};
+
+export const DEFAULT_CONSENT_LABELS: ConsentLabels = {
+  title: 'Your privacy choices',
+  body: 'This site would like to use optional cookies and similar storage. Necessary ones are always on. You can accept all, reject all, or choose.',
+  acceptAll: 'Accept all',
+  rejectAll: 'Reject all',
+  customise: 'Customise',
+  save: 'Save choices',
+  settingsLink: 'Cookie settings',
+  policyLink: 'Cookie policy',
+  dialogTitle: 'Cookie settings',
+  dialogBody: 'Choose which optional cookies this site may use. You can change this at any time.',
+  cookiesList: 'Cookies',
+  categories: CATEGORY_LABELS,
+  categoryDescriptions: CATEGORY_DESCRIPTIONS,
+};
+
+export type ConsentLabelOverrides = Partial<Omit<ConsentLabels, 'categories' | 'categoryDescriptions'>> & {
+  categories?: Partial<Record<CookieCategory, string>>;
+  categoryDescriptions?: Partial<Record<CookieCategory, string>>;
+};
+
+/** `labels` merged over the defaults. */
+export function consentLabels(overrides?: ConsentLabelOverrides): ConsentLabels {
+  return {
+    ...DEFAULT_CONSENT_LABELS,
+    ...overrides,
+    categories: { ...CATEGORY_LABELS, ...overrides?.categories },
+    categoryDescriptions: { ...CATEGORY_DESCRIPTIONS, ...overrides?.categoryDescriptions },
+  };
+}

package/src/components/privacy.css

@@ -0,0 +1,150 @@
+/*
+ * Base styles for the privacy & cookie policy components.
+ *
+ * Every selector is wrapped in :where() so it carries zero specificity: any site rule wins.
+ * Theme through the custom properties below rather than overriding the rules.
+ *
+ *   --marvin-privacy-gap          space between sections (default 2rem)
+ *   --marvin-privacy-border       table rule colour (default currentColor at 20%)
+ *   --marvin-privacy-head-bg      table header background (default currentColor at 6%)
+ *   --marvin-privacy-muted        secondary text (default currentColor at 75%)
+ *   --marvin-privacy-pad          table cell padding (default 0.5rem 0.75rem)
+ *   --marvin-privacy-breakpoint   documentation only; tables stack below 600px
+ *
+ * Markup:
+ *   div.marvin-privacy
+ *     section.marvin-privacy__section  (controller, processors, cookies)
+ *       dl.marvin-privacy__facts
+ *       table.marvin-privacy__table.marvin-privacy__table--{cookies|processors}
+ */
+
+:where(.marvin-privacy) {
+  display: grid;
+  /* A bare `1fr`/auto track grows to its widest child's min-content, so one wide table would push
+     the whole policy past the viewport. minmax(0, 1fr) keeps the track at the container's width. */
+  grid-template-columns: minmax(0, 1fr);
+  gap: var(--marvin-privacy-gap, 2rem);
+}
+
+:where(.marvin-privacy__section > :first-child) {
+  margin-top: 0;
+}
+
+:where(.marvin-privacy__facts) {
+  display: grid;
+  grid-template-columns: max-content 1fr;
+  gap: 0.25rem 1.5rem;
+  margin: 0;
+}
+
+:where(.marvin-privacy__facts dt) {
+  font-weight: 600;
+}
+
+:where(.marvin-privacy__facts dd) {
+  margin: 0;
+  min-width: 0;
+  overflow-wrap: break-word;
+}
+
+:where(.marvin-privacy__notice, .marvin-privacy__reviewed) {
+  color: var(--marvin-privacy-muted, color-mix(in srgb, currentColor 75%, transparent));
+}
+
+:where(.marvin-privacy__table-wrap) {
+  /* Safety net: if a table still cannot fit (many columns in a narrow column, a long URL in a
+     purpose cell) it scrolls inside its own box instead of stretching the page. */
+  max-width: 100%;
+  overflow-x: auto;
+}
+
+:where(.marvin-privacy__table) {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 0 0 1.5rem;
+  text-align: left;
+}
+
+:where(.marvin-privacy__table caption) {
+  text-align: left;
+  font-weight: 600;
+  padding-bottom: 0.5rem;
+}
+
+:where(.marvin-privacy__table caption small) {
+  display: block;
+  font-weight: 400;
+  color: var(--marvin-privacy-muted, color-mix(in srgb, currentColor 75%, transparent));
+}
+
+:where(.marvin-privacy__table th, .marvin-privacy__table td) {
+  padding: var(--marvin-privacy-pad, 0.5rem 0.75rem);
+  border-bottom: 1px solid var(--marvin-privacy-border, color-mix(in srgb, currentColor 20%, transparent));
+  vertical-align: top;
+  /* Ordinary words wrap at normal break points. `break-word` (unlike `anywhere`) does not shrink a
+     column's min-content width, so a narrow column never splits a word that could sit on its own
+     line. Only an unbreakable token wider than its cell is broken, below. */
+  overflow-wrap: break-word;
+}
+
+/* Long unbreakable tokens (cookie names such as _ga_XXXXXXXX, addresses) may break anywhere, and
+   `anywhere` lets their column shrink so the table stays inside its container. */
+:where(.marvin-privacy__table code, .marvin-privacy__table a[href^="mailto:"], .marvin-privacy__facts a[href^="mailto:"]) {
+  overflow-wrap: anywhere;
+}
+
+:where(.marvin-privacy__table thead th) {
+  background: var(--marvin-privacy-head-bg, color-mix(in srgb, currentColor 6%, transparent));
+}
+
+:where(.marvin-privacy__table tbody th) {
+  font-weight: 600;
+}
+
+:where(.marvin-privacy__links) {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+/* Below 600px each row becomes a stacked card: the header row is hidden visually (still read by
+   assistive tech) and every cell carries its column name from data-label. */
+@media (max-width: 599px) {
+  :where(.marvin-privacy__table, .marvin-privacy__table tbody, .marvin-privacy__table tr, .marvin-privacy__table th, .marvin-privacy__table td) {
+    display: block;
+  }
+
+  /* The caption is otherwise sized as a shrink-to-fit table-caption and wraps in a sliver. */
+  :where(.marvin-privacy__table caption) {
+    display: block;
+    width: 100%;
+  }
+
+  :where(.marvin-privacy__table thead) {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+
+  :where(.marvin-privacy__table tr) {
+    padding: 0.5rem 0;
+    border-bottom: 1px solid var(--marvin-privacy-border, color-mix(in srgb, currentColor 20%, transparent));
+  }
+
+  :where(.marvin-privacy__table th, .marvin-privacy__table td) {
+    border-bottom: 0;
+    padding-block: 0.125rem;
+  }
+
+  :where(.marvin-privacy__table td[data-label])::before {
+    content: attr(data-label) ': ';
+    font-weight: 600;
+  }
+
+  :where(.marvin-privacy__facts) {
+    grid-template-columns: 1fr;
+  }
+}

package/src/index.ts

@@ -137,6 +137,14 @@ export {
   type RenderMarkdownOptions,
 } from './markdown.js';
 export { entryEmbeds, findEmbed, siteEmbeds } from './embeds.js';
+export {
+  COOKIE_CATEGORIES,
+  CONSENT_CATEGORIES,
+  consentCategories,
+  consentVersion,
+  cookiesNeedConsent,
+  sitePrivacy,
+} from './privacy.js';
 export * from './normalize.js';
 export {
   createRepository,