@inneropen/marvin-astro 2.0.0 → 2.1.0

package/README.md

@@ -258,6 +258,8 @@ this needs a newer SDK.
 |---|---|
 | `FormRenderer` | a public form from a submittable entry type's `formSchema`; unstyled, progressive-enhancement submit |
 | `Embed`, `LinkCard`, `EmbedLoader` | media embeds (above) |
+| `PrivacyPolicy`, `CookieTable`, `ProcessorTable` | privacy & cookie policy rendering ([below](#privacy--cookies)) |
+| `ConsentBanner`, `CookieSettingsLink` | cookie-consent banner and settings link ([below](#consent-banner)) |
 | `EntryRenderer` | picks the renderer for an entry from its entry type's `rendering` |
 | `PageRenderer`, `ArticleRenderer`, `FaqRenderer`, `NavigationRenderer` | unstyled, semantic core renderers with `data-renderer`/`data-role` hooks |
 
@@ -288,6 +290,116 @@ Options: `registry` (required), `apiUrl`, `siteToken` (default to the `MARVIN_*`
 Marvin's system entry types name their renderer package `@inneropen/marvin-renderers-core`; the
 core renderers still answer to that name (and to `@inneropen/marvin-astro`).
 
+## Privacy & cookies
+
+Marvin keeps the facts a privacy/cookie policy needs (`site.privacy`: the controller, processors and
+the cookies/storage the site sets). `site.privacy` is read tolerantly (typed field or
+`metadata.privacy`, camelCase or snake_case), so it needs no SDK bump; it is `undefined` until a
+workspace configures it. Not legal advice: you decide the text and the classification.
+
+```astro
+---
+import { PrivacyPolicy } from '@inneropen/marvin-astro/components';
+const site = await marvin.getSite();
+const entry = await policies.bySlug('privacy'); // your policy entry (prose)
+---
+<PrivacyPolicy privacy={site.privacy} headingLevel={2}>
+  <Fragment set:html={entry.bodyHtml} />
+</PrivacyPolicy>
+```
+
+| Component | Renders |
+|---|---|
+| `PrivacyPolicy` | the entry prose (default slot), controller block, processors, cookies, "Last reviewed" |
+| `CookieTable` | `cookies`, one table per category (`category` narrows it); adds the `marvin-consent` storage row as necessary when a banner is required (`includeConsentEntry={false}` to skip) |
+| `ProcessorTable` | `processors`: region, transfer basis, DPA/privacy links (http(s) only) |
+
+All server-rendered with zero JavaScript. Styling is `privacy.css`: zero-specificity `:where()` rules
+you override freely, themed with `--marvin-privacy-gap | -border | -head-bg | -muted | -pad`; tables
+stack below 600px. Every string has a neutral English default; pass `labels={{ ... }}` to change it.
+
+`sitePrivacy(raw)` and `consentVersion(privacy)` are exported from the package root. The version is
+a hash of the sorted non-necessary `category|name|provider` triples, so rewording a purpose or
+moving `lastReviewed` never re-asks, while adding, removing or re-categorising a cookie does.
+
+### Consent banner
+
+`<ConsentBanner>` asks only when it has to. It renders **nothing, and ships no script or CSS**, unless
+`site.privacy.bannerRequired` (at least one listed cookie/storage entry is not `necessary`), so a site
+with no optional cookies carries zero banner bytes.
+
+```astro
+---
+// src/layouts/BaseLayout.astro
+import { ConsentBanner, CookieSettingsLink } from '@inneropen/marvin-astro/components';
+const site = await marvin.getSite();
+---
+<html>
+  <body>
+    <ConsentBanner privacy={site.privacy} policyHref="/privacy" />
+    <main>...</main>
+    <footer>
+      <CookieSettingsLink href="/privacy" privacy={site.privacy} />
+    </footer>
+  </body>
+</html>
+```
+
+- **Fail closed.** The markup is `hidden` and the runtime reveals it only when the visitor has no valid
+  choice; without JavaScript there is no dead banner and nothing optional loads. The link in
+  `<CookieSettingsLink>` is a real link to your policy page; with JavaScript it opens the dialog.
+- **Equal choices.** Accept all and Reject all share one class and size; Customise opens a native
+  `<dialog>` with one unticked checkbox per category listed in `site.privacy.cookies`. A non-modal bottom
+  bar, no focus stealing; after a choice focus moves to `<main>`, and the dialog returns it to its opener.
+- **Remembered for 6 months**, refusals too (`maxAgeDays`, default 180), in
+  `localStorage['marvin-consent']`. The choice is bound to `consentVersion(privacy)`: adding, removing or
+  re-categorising an optional cookie asks everyone again; rewording does not. `consent.version` in
+  Marvin's privacy block is a manual re-ask bump. Safari caps script-written storage at 7 days without
+  interaction, so some visitors are asked sooner.
+- **Disclosure.** `marvin-consent` is listed automatically by `<CookieTable>` / `<PrivacyPolicy>`.
+
+Gate optional scripts and markup so they ship inert and run only after consent:
+
+```html
+<script type="text/plain" data-consent="analytics" data-src="https://stats.example/script.js" defer></script>
+<script type="text/plain" data-consent="analytics">window.track?.();</script>
+<template data-consent="marketing"><iframe src="https://ads.example/widget"></iframe></template>
+```
+
+`data-consent` takes one or more categories (`preferences`, `analytics`, `marketing`; all must be
+allowed). Other attributes on the script are copied over, `data-type="module"` restores a module type.
+An unknown category never runs. A site whose `bannerRequired` is false never activates anything, so a
+gated script with no matching entry in Marvin stays inert; a dev build logs a console warning for that.
+Prefer `data-src` over inline code if you use a CSP (inline gated code needs a hash or `unsafe-inline`).
+
+```ts
+window.marvinConsent.get();            // { v, version, choices, at } | null while undecided
+window.marvinConsent.has('analytics'); // 'necessary' is always true
+window.marvinConsent.set({ analytics: true });
+window.marvinConsent.open();           // the Customise dialog
+document.addEventListener('marvin:consent', (e) => e.detail); // { choices, version, initial }
+```
+
+`marvin:consent` fires on load when a valid choice exists (`initial: true`, after the page's module
+scripts have run, so late listeners see it) and on every change. Withdrawing a category deletes the
+site's listed first-party cookies for it (a trailing `*` is a prefix: `_ga*`; the host and its parent
+domains) and reloads the page so nothing keeps running.
+
+**Embeds** stay click-to-load: the click on a facade is the visitor's consent, and they do not make
+`bannerRequired` true. Opt in to auto-loading them after a category is allowed with
+`<ConsentBanner embeds="marketing" ... />` (off by default; needs `<EmbedLoader />`).
+
+Text defaults to neutral English: override per site with `labels={{ title, body, acceptAll, rejectAll,
+customise, save, settingsLink, policyLink, dialogTitle, dialogBody, categories, categoryDescriptions }}`.
+Theme with `--marvin-consent-bg | -fg | -accent | -radius | -font | -shadow | -z` (zero-specificity
+`consent.css`; dark mode follows `prefers-color-scheme`). No consent log is kept anywhere.
+
+`consent.css` is inlined as a `<style>` next to the banner markup, and the runtime `<script>` is only
+emitted with it, so a page without a banner carries neither (Astro 5 ships a component's `<script>` only
+where it renders but ships imported stylesheets wherever the component is merely imported, hence the
+inline style). Under a CSP without `style-src 'unsafe-inline'`, pass `inlineStyles={false}` and import
+`@inneropen/marvin-astro/components/consent.css` yourself. Check your build output on other Astro versions.
+
 ## Migrating from @inneropen/marvin-renderers-core
 
 The components and logic moved here with their names unchanged. Swap the import paths, then
@@ -354,7 +466,7 @@ verification tags. No styling, no site coupling.
 | `@inneropen/marvin-astro` | `createMarvinContent` and every helper below it |
 | `@inneropen/marvin-astro/types` | resolved types only (`ApiSite`, `ApiSeo`, `ApiSiteChrome`, …) |
 | `@inneropen/marvin-astro/astro` | `SeoHead` |
-| `@inneropen/marvin-astro/components` | `FormRenderer`, `Embed`, `LinkCard`, `EmbedLoader`, `EntryRenderer`, the core renderers, registry, `marvinIntegration` |
+| `@inneropen/marvin-astro/components` | `FormRenderer`, `Embed`, `LinkCard`, `EmbedLoader`, `PrivacyPolicy`, `CookieTable`, `ProcessorTable`, `ConsentBanner`, `CookieSettingsLink`, `EntryRenderer`, the core renderers, registry, `marvinIntegration` |
 | `@inneropen/marvin-astro/components/registry` | `getRenderer`, `astroRegistry`, `coreRendererPackage` |
 | `@inneropen/marvin-astro/components/integration` | `marvinIntegration` (for `astro.config.mjs`) |
 | `@inneropen/marvin-astro/components/*` | individual components, `renderers/*.astro`, `embeds.css` |
@@ -362,7 +474,7 @@ verification tags. No styling, no site coupling.
 
 Beyond `createMarvinContent`, the pieces are usable on their own: `createBackend`,
 `createFetcher`, `createRepository`, `createSiteLoader`, `createChromeLoader`,
-`createFieldAccessor`, `createMarkdownRenderer`, `entryEmbeds`, `findEmbed`, `siteEmbeds`,
+`createFieldAccessor`, `createMarkdownRenderer`, `entryEmbeds`, `findEmbed`, `siteEmbeds`, `sitePrivacy`, `consentVersion`,
 `formatDisplayDate`, `selectValuesForPage`, and the whole `normalize` surface.
 
 ## Development

package/dist/index.d.ts

@@ -3,8 +3,8 @@ import { M as MarvinEmbeds, a as MarvinEmbed } from './embeds-BTNryQA6.js';
 export { b as MarvinEmbedIframe, c as MarvinEmbedKind, d as MarvinEmbedLink, e as MarvinEmbedMode, f as MarvinEmbedStatus, g as MarvinSiteEmbeds, h as entryEmbeds, i as findEmbed, s as siteEmbeds } from './embeds-BTNryQA6.js';
 import * as _inneropen_marvin_sdk from '@inneropen/marvin-sdk';
 import { MarvinClient, MarvinEntry, Entry, PublishedCollectionSummary, Collection, CollectionEntry, MarvinSite, Workspace } from '@inneropen/marvin-sdk';
-import { MarvinContentEntry, ApiSite, ApiSeo, ApiSiteChrome, ApiNavigationLink, ApiSocialLink, AssetSelectOptions, ApiImage, ApiResourceLink, SectionLanding } from './types.js';
-export { ApiActionVariant, ApiHero, ApiHeroAction, ApiPageAction } from './types.js';
+import { M as MarvinContentEntry, A as ApiSite, a as ApiSeo, b as ApiSiteChrome, c as ApiNavigationLink, d as ApiSocialLink, e as AssetSelectOptions, f as ApiImage, g as ApiResourceLink, S as SectionLanding } from './types-4VdGN9e_.js';
+export { h as ApiActionVariant, i as ApiHero, j as ApiHeroAction, k as ApiPageAction, C as CONSENT_CATEGORIES, l as COOKIE_CATEGORIES, m as ConsentCategory, n as CookieCategory, P as PrivacyConsent, o as PrivacyController, p as PrivacyCookie, q as PrivacyProcessor, r as SitePrivacy, s as consentCategories, t as consentVersion, u as cookiesNeedConsent, v as sitePrivacy } from './types-4VdGN9e_.js';
 
 type MarkdownOptions = MarkedOptions;
 /** Per-call options for a {@link MarkdownRenderer}. */

package/dist/index.js

@@ -602,9 +602,9 @@ var EMBEDS = /* @__PURE__ */ Symbol("marvin.embeds");
 var BARE_URL = /^https?:\/\/\S+$/i;
 function paragraphEmbedHtml(token, embeds) {
   if (!embeds) return void 0;
-  const text = token.text.trim();
-  if (!BARE_URL.test(text)) return void 0;
-  const html = findEmbed(embeds, text)?.html;
+  const text2 = token.text.trim();
+  if (!BARE_URL.test(text2)) return void 0;
+  const html = findEmbed(embeds, text2)?.html;
   return typeof html === "string" && html.trim() ? html : void 0;
 }
 function createMarkdownRenderer(options = {}) {
@@ -984,6 +984,109 @@ async function loadSectionLanding(fetcher, slug, renderMarkdown = createMarkdown
   };
 }
 
+// src/privacy.ts
+var COOKIE_CATEGORIES = [
+  "necessary",
+  "preferences",
+  "analytics",
+  "marketing"
+];
+var CONSENT_CATEGORIES = [
+  "preferences",
+  "analytics",
+  "marketing"
+];
+function field2(record, camel) {
+  if (record[camel] !== void 0) return record[camel];
+  return record[camel.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`)];
+}
+function text(record, camel) {
+  const value = asString(field2(record, camel));
+  return value?.trim();
+}
+function records(value) {
+  return Array.isArray(value) ? value.filter((item) => !!item && typeof item === "object") : [];
+}
+function readController(raw) {
+  const value = asRecord(raw);
+  const legalName = text(value, "legalName");
+  if (!legalName) return void 0;
+  return {
+    legalName,
+    contactEmail: text(value, "contactEmail"),
+    address: text(value, "address"),
+    euRepresentative: text(value, "euRepresentative"),
+    dpoEmail: text(value, "dpoEmail")
+  };
+}
+function readProcessor(value) {
+  const name = text(value, "name");
+  if (!name) return void 0;
+  const categories = field2(value, "dataCategories");
+  return {
+    name,
+    purpose: text(value, "purpose"),
+    dataCategories: Array.isArray(categories) ? categories.filter((item) => typeof item === "string" && item.trim() !== "") : [],
+    region: text(value, "region"),
+    transferBasis: text(value, "transferBasis"),
+    dpaUrl: text(value, "dpaUrl"),
+    privacyUrl: text(value, "privacyUrl")
+  };
+}
+function readCookie(value) {
+  const name = text(value, "name");
+  if (!name) return void 0;
+  const category = text(value, "category");
+  return {
+    name,
+    provider: text(value, "provider") ?? "",
+    purpose: text(value, "purpose") ?? "",
+    duration: text(value, "duration"),
+    // A category a newer server invented is treated as the strictest optional one, never as
+    // `necessary`: it must be asked about before anything it covers loads.
+    category: COOKIE_CATEGORIES.includes(category) ? category : "marketing"
+  };
+}
+function cookiesNeedConsent(cookies) {
+  return cookies.some((cookie) => cookie.category !== "necessary");
+}
+function sitePrivacy(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const value = raw;
+  const consent = asRecord(field2(value, "consent"));
+  const cookies = records(value.cookies).map(readCookie).filter((cookie) => cookie !== void 0);
+  const declared = field2(value, "bannerRequired");
+  return {
+    controller: readController(value.controller),
+    processors: records(value.processors).map(readProcessor).filter((processor) => processor !== void 0),
+    cookies,
+    consent: {
+      policyEntrySlug: text(consent, "policyEntrySlug"),
+      cookiePolicyEntrySlug: text(consent, "cookiePolicyEntrySlug"),
+      lastReviewed: text(consent, "lastReviewed"),
+      version: text(consent, "version")
+    },
+    bannerRequired: typeof declared === "boolean" ? declared : cookiesNeedConsent(cookies)
+  };
+}
+function fnv1a(input) {
+  let hash = 2166136261;
+  for (let index = 0; index < input.length; index += 1) {
+    hash ^= input.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function consentVersion(privacy) {
+  const triples = (privacy?.cookies ?? []).filter((cookie) => cookie.category !== "necessary").map((cookie) => `${cookie.category}|${cookie.name}|${cookie.provider}`).sort();
+  const bump = privacy?.consent.version;
+  return fnv1a(bump ? [...triples, `v:${bump}`].join("\n") : triples.join("\n"));
+}
+function consentCategories(privacy) {
+  const present = new Set((privacy?.cookies ?? []).map((cookie) => cookie.category));
+  return CONSENT_CATEGORIES.filter((category) => present.has(category));
+}
+
 // src/site.ts
 function buildSeo(raw, identity) {
   const seo = raw ?? {};
@@ -1071,6 +1174,11 @@ function transformMarvinSite(marvinSite, fallback) {
     embeds: siteEmbeds(
       config.embeds ?? marvinSite.embeds
     ),
+    // Typed `config.privacy` when the SDK declares it (SDK 7.2+), else the raw blob under
+    // `metadata.privacy`; this package's SDK peer range predates the typed field, so read both.
+    privacy: sitePrivacy(
+      config.privacy ?? marvinSite.privacy ?? metadata.privacy
+    ),
     metadata
   };
 }
@@ -1161,6 +1269,8 @@ function createMarvinContent(options = {}) {
   };
 }
 export {
+  CONSENT_CATEGORIES,
+  COOKIE_CATEGORIES,
   DEFAULT_DEV_RETRY_MS,
   DEFAULT_HYDRATE_CONCURRENCY,
   ENV_KEYS,
@@ -1175,6 +1285,9 @@ export {
   buildSeo,
   collectionRole,
   collectionSlugs,
+  consentCategories,
+  consentVersion,
+  cookiesNeedConsent,
   createBackend,
   createChromeLoader,
   createFetcher,
@@ -1213,6 +1326,7 @@ export {
   selectImageAsset,
   selectValuesForPage,
   siteEmbeds,
+  sitePrivacy,
   socialLinkFromKey,
   toNavigationLink
 };