@hagicode/hagilight-docusaurus 0.20.1-dev.196.1.d67f4e4 → 0.20.1-dev.199.1.c17b214

package/README.md

@@ -109,6 +109,40 @@ Docusaurus sends `not_found_viewed` from its 404 page, `code_copied` from its co
 Each provider is independent: disabling Google Analytics and 51LA alone leaves PostHog enabled. Choose one PostHog initialization owner and opt out here if the site already supplies it. The loader initializes once per document, and the supplied SDK defaults own navigation tracking. The head registers the site context (`site_framework` `docusaurus`, the plugin version, and `site_id` from `links.siteId` or the site URL's hostname) once. On every route update, including the first page load, the plugin refreshes only `locale` and `page_type` through `posthog.register`, with `page_type` derived from the path, so the 404 page reports a path-derived type rather than `other`. The analytics client module is bundled whenever PostHog is enabled, even when Google Analytics and 51LA are disabled, so marked links are captured as `cta_click` without Google Analytics. Google Analytics and 51LA keep their navigation behavior.
 
 
+### Regional consent
+
+> Legal notice: this is a product configuration, not legal advice. The default country set, Brazil's inclusion and the default hiding of "Cookie settings" for not-required visitors need confirmation by counsel, and site privacy notices may need matching updates. The `features.consentMode` metadata reports `globalRequired` or `regional`.
+
+Regional consent starts analytics without a click for visitors whose country does not require consent. It is off unless `analytics.consent.regions` is set. Without it every visitor sees the popup first, and the output is unchanged.
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `regions` | absent (global consent) | `'default'` for the built-in country set, or an array of upper-case ISO 3166-1 alpha-2 codes that replaces it. Setting it enables regional mode. |
+| `countryCode` | none | One upper-case ISO code that overrides detection. Needs `regions`. |
+| `regionHook` | none | Name of a function on `window`, such as `"siteRegion"`. It returns `'required'`, `'notRequired'`, `'unknown'`, a boolean, or a promise of one of these. Needs `regions`. |
+| `settingsEntry` | `'requiredOnly'` | `'always'` shows the footer "Cookie settings" entry to every visitor. Needs `regions`. |
+| `sessionReplay` | `'optIn'` | `'projectDefault'` lets replay follow the PostHog project. `'off'` removes the replay entry. Needs `regions`. |
+
+```js
+hagilightDocusaurus({
+  analytics: { consent: { regions: 'default', settingsEntry: 'requiredOnly', sessionReplay: 'optIn' } },
+});
+```
+
+Invalid values fail at configuration time with a `TypeError` that names the option. The messages come from the core validator, so they match the Starlight and Astro integrations. A regional-only option without `regions` fails, and so does `regions` with `enabled: false`.
+
+**Default country set.** `'default'` requires consent for the EU27, the EEA (IS, LI, NO), GB, CH and BR. This is a product configuration, not a legal determination. A list replaces the whole set.
+
+**Sources.** The decision uses the first answer from: `countryCode`, `regionHook`, the same-origin `/cdn-cgi/trace` endpoint (only its `loc` line is read, with a 1200 ms timeout), and a coarse time-zone fallback. The whole decision has a 1800 ms deadline. It is resolved once per document, so client-side navigation does not resolve it again, and each provider starts once.
+
+**Fail-closed.** `unknown` requires consent: no country, an unrecognized hook result, a timeout, an invalid `countryCode`, or an uncertain time zone. The popup appears, and no provider loads until the visitor accepts.
+
+**Cloudflare trace and `www`.** `/cdn-cgi/trace` answers only for hostnames proxied through Cloudflare. `www.hagicode.com` returned no `loc` when verified, so on a `www` host the time-zone fallback decides unless `countryCode` or `regionHook` is set.
+
+**Session replay.** With `sessionReplay: 'optIn'`, a not-required visitor gets replay off and an "Allow session replay" footer entry. Replay stays off until the visitor allows it. The settings and replay entries belong to the Hagilight footer, so `footer: { enabled: false }` removes them.
+
+Google Consent Mode and cookieless pings stay off, and no `gtag` consent default is added. Turning regional mode on changes what GA4 and PostHog collect, so annotate the deployment date in GA4.
+
 ### SEO
 
 - `seo.image` is an absolute HTTP(S) URL or a site-root path. When it is unset, `themeConfig.image` is the fallback sharing image.
@@ -194,4 +228,4 @@ The demo site for this package lives in the monorepo at `examples/demo-docusauru
 
 ### Consent
 
-`analytics.consent` (`enabled`, `privacyUrl`, `policyVersion`) mirrors the Starlight option. With consent on, providers leave inert descriptors in the head, the client module mounts the popup and gate, PostHog's click sink installs only after a grant, and the swizzled footer shows the localized "Cookie settings" entry. The popup styles ship in `consent.css`. `enabled: false` restores immediate loading.
+`analytics.consent` (`enabled`, `privacyUrl`, `policyVersion`) mirrors the Starlight option. With consent on, providers leave inert descriptors in the head, the client module mounts the popup and gate, PostHog's click sink installs only after a grant, and the swizzled footer shows the localized "Cookie settings" entry. The popup styles ship in `consent.css`. `enabled: false` restores immediate loading. Regional options (`regions` and the four related options) are under [Regional consent](#regional-consent).

package/dist/discovery.js

@@ -221,7 +221,12 @@ async function writeSiteMetadataFile(outputs) {
             fiftyOneLa: production && options.fiftyOneLaId !== undefined,
             posthog: production && options.posthogApiKey !== undefined,
         },
-        features: { seo: options.seo.enabled, promoto: options.promoto, consent: options.consent.enabled },
+        features: {
+            seo: options.seo.enabled,
+            promoto: options.promoto,
+            consent: options.consent.enabled,
+            consentMode: options.consent.enabled ? (options.consent.regional ? 'regional' : 'globalRequired') : undefined,
+        },
     });
     writeSiteMetadata({
         outDir,

package/dist/footer.d.ts

@@ -1,4 +1,5 @@
 import { resolveSiteLinks, type SiteLinksOptions } from '@hagicode/hagilight-core/links';
+import type { ResolvedConsentOptions } from './options.js';
 export interface FooterLinksInput {
     locale: string;
     baseUrl: string;
@@ -7,3 +8,12 @@ export interface FooterLinksInput {
 }
 export type FooterLinks = ReturnType<typeof resolveSiteLinks>;
 export declare function resolveFooterLinks({ locale, baseUrl, links, rssEnabled }: FooterLinksInput): FooterLinks;
+export interface FooterConsentEntries {
+    /** The "Cookie settings" label. Absent when consent is off, so no entry renders. */
+    consentLabel: string | undefined;
+    /** A regional site: the settings entry renders hidden until the consent popup reveals it. */
+    regional: boolean;
+    /** The session replay entry label, for a regional site with replay opt-in. */
+    replayLabel: string | undefined;
+}
+export declare function resolveFooterConsent(consent: ResolvedConsentOptions, locale: string): FooterConsentEntries;

package/dist/footer.js

@@ -1,3 +1,4 @@
+import { resolveConsentCopy } from '@hagicode/hagilight-core/consent-copy';
 import { resolveSiteLinks } from '@hagicode/hagilight-core/links';
 export function resolveFooterLinks({ locale, baseUrl, links, rssEnabled }) {
     const sitemap = links.overrides?.sitemap;
@@ -10,3 +11,14 @@ export function resolveFooterLinks({ locale, baseUrl, links, rssEnabled }) {
         },
     });
 }
+export function resolveFooterConsent(consent, locale) {
+    if (!consent.enabled)
+        return { consentLabel: undefined, regional: false, replayLabel: undefined };
+    const copy = resolveConsentCopy(locale);
+    const regional = consent.regional !== undefined;
+    return {
+        consentLabel: copy.footerEntry,
+        regional,
+        replayLabel: regional && consent.regional?.sessionReplay === 'optIn' ? copy.replayEntry : undefined,
+    };
+}

package/dist/index.js

@@ -43,6 +43,7 @@ function analyticsHeadTags(options, site) {
                 providers: options.consent.providers,
                 privacyUrl: options.consent.privacyUrl,
                 policyVersion: options.consent.policyVersion,
+                regional: options.consent.regional,
             })] : []),
     ];
 }

package/dist/options.d.ts

@@ -1,6 +1,6 @@
 import type { SiteLinksOptions } from '@hagicode/hagilight-core/links';
 import { type ResolvedFooterAvatarOptions } from '@hagicode/hagilight-core/footer-avatar';
-import { type ConsentPopupOptions } from '@hagicode/hagilight-core/consent-markup';
+import { type ConsentPopupOptions, type RegionalPopupOptions } from '@hagicode/hagilight-core/consent-markup';
 import { type SiteMetadataOption } from '@hagicode/hagilight-core/site-metadata';
 export interface FeatureToggle {
     enabled?: boolean;
@@ -24,12 +24,24 @@ export interface ConsentOptions {
     privacyUrl?: string;
     /** Defaults to `1`. Changing it asks every visitor again. */
     policyVersion?: string;
+    /** `default` applies the built-in country set; a list of ISO 3166-1 alpha-2 codes replaces it. Setting it enables regional consent. */
+    regions?: 'default' | readonly string[];
+    /** One ISO 3166-1 alpha-2 code for every visitor. Needs `regions`. */
+    countryCode?: string;
+    /** The name of a function defined on `window`, such as "siteRegion". Needs `regions`. */
+    regionHook?: string;
+    /** `requiredOnly` (default) shows the settings entry only where consent is required. `always` shows it everywhere. Needs `regions`. */
+    settingsEntry?: 'requiredOnly' | 'always';
+    /** `optIn` (default) offers session replay as a separate choice. `projectDefault` or `off` change that. Needs `regions`. */
+    sessionReplay?: 'optIn' | 'projectDefault' | 'off';
 }
 export interface ResolvedConsentOptions {
     enabled: boolean;
     privacyUrl: string | undefined;
     policyVersion: string;
     providers: ConsentPopupOptions['providers'];
+    /** Set only when a regional option is given; its absence keeps the global consent output unchanged. */
+    regional: RegionalPopupOptions | undefined;
 }
 export interface PostHogOptions extends FeatureToggle {
     apiKey?: string;

package/dist/options.js

@@ -1,6 +1,6 @@
 import { resolveFooterAvatarOptions } from '@hagicode/hagilight-core/footer-avatar';
 import { DEFAULT_POSTHOG_API_KEY, POSTHOG_API_KEY_PATTERN } from '@hagicode/hagilight-core/posthog';
-import { validatePolicyVersion, validatePrivacyUrl, } from '@hagicode/hagilight-core/consent-markup';
+import { resolveRegionalOptions, validatePolicyVersion, validatePrivacyUrl, } from '@hagicode/hagilight-core/consent-markup';
 import { isValidSeoImageReference, resolveAbsoluteHttpUrl } from '@hagicode/hagilight-core/seo';
 import { resolveSiteMetadataOption } from '@hagicode/hagilight-core/site-metadata';
 import { DEFAULT_FIFTY_ONE_LA_ID, DEFAULT_GOOGLE_ANALYTICS_ID, FIFTY_ONE_LA_ID_PATTERN, GOOGLE_ANALYTICS_ID_PATTERN, } from './analytics.js';
@@ -122,10 +122,13 @@ function resolveRss(value) {
 function resolveConsent(config, providers) {
     const record = config === undefined ? {} : objectOption(config, 'analytics.consent');
     const requested = booleanOption(record.enabled, 'analytics.consent.enabled');
+    const enabled = providers.length > 0 && (requested ?? true);
     return {
-        enabled: providers.length > 0 && (requested ?? true),
+        enabled,
         privacyUrl: validatePrivacyUrl(record.privacyUrl),
         policyVersion: validatePolicyVersion(record.policyVersion),
+        // The core validator names each option, so the messages match the Starlight and Astro integrations.
+        regional: resolveRegionalOptions(record, record.enabled !== false),
         providers,
     };
 }

package/dist/theme/Footer/FooterView.d.ts

@@ -19,5 +19,9 @@ export interface FooterViewProps {
     siteUrl?: string;
     /** The localized "Cookie settings" label. Set only when the consent popup is mounted. */
     consentLabel?: string;
+    /** A regional site: the "Cookie settings" entry renders hidden and the consent popup reveals it. */
+    regional?: boolean;
+    /** The session replay entry label. Set only for a regional site with replay opt-in, alongside `consentLabel`. */
+    replayLabel?: string;
 }
-export declare function FooterView({ links, version, year, buildInfo, avatar, siteId, siteUrl, consentLabel }: FooterViewProps): ReactElement;
+export declare function FooterView({ links, version, year, buildInfo, avatar, siteId, siteUrl, consentLabel, regional, replayLabel }: FooterViewProps): ReactElement;

package/dist/theme/Footer/FooterView.js

@@ -30,8 +30,8 @@ function FooterBrand({ locale, links, avatar, siteId, siteUrl }) {
     });
     return (_jsxs("section", { className: "hagilight-brand", lang: brand.locale, "aria-labelledby": "hagilight-brand-title", children: [_jsxs("div", { className: "hagilight-brand__lead", children: [_jsxs("div", { className: "hagilight-brand__title", children: [avatar && (_jsxs("picture", { className: "hagilight-brand__avatar", "data-random-fan": avatar.randomPool && randomPoolAttribute(avatar.randomPool), children: [_jsx("source", { type: "image/avif", srcSet: avatar.avif }), _jsx("source", { type: "image/webp", srcSet: avatar.webp }), _jsx("img", { src: avatar.webp, ...footerAvatarImageAttributes() })] })), _jsx("h2", { className: "hagilight-brand__headline", id: "hagilight-brand-title", children: brand.headline })] }), _jsxs("div", { className: "hagilight-brand__body", children: [_jsx("p", { className: "hagilight-brand__summary", children: brand.summary }), (primary || secondary) && (_jsxs("div", { className: "hagilight-brand__actions", children: [primary && (_jsxs("a", { className: "hagilight-brand__primary", href: brandHref(primary), target: primary.target, rel: primary.rel, "aria-label": primary.ariaLabel, ...siteLinkGaAttributes(primary, 'footer_brand'), children: [_jsx("span", { children: primary.label }), _jsx("svg", { className: "hagilight-brand__arrow", viewBox: "0 0 16 16", width: "16", height: "16", "aria-hidden": "true", focusable: "false", children: _jsx("path", { d: "M2.5 8h10M8.5 3.5 13 8l-4.5 4.5", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round" }) })] })), secondary && (_jsx("a", { className: "hagilight-brand__secondary", href: brandHref(secondary), target: secondary.target, rel: secondary.rel, "aria-label": secondary.ariaLabel, ...siteLinkGaAttributes(secondary, 'footer_brand'), children: secondary.label }))] }))] })] }), _jsx("dl", { className: "hagilight-brand__pillars", children: brand.pillars.map((pillar, index) => (_jsxs("div", { className: "hagilight-brand__pillar", "data-pillar": pillar.id, style: { '--hagilight-brand-i': index }, children: [_jsx("dt", { children: pillar.label }), _jsx("dd", { children: pillar.description })] }, pillar.id))) })] }));
 }
-export function FooterView({ links, version, year, buildInfo, avatar, siteId, siteUrl, consentLabel }) {
+export function FooterView({ links, version, year, buildInfo, avatar, siteId, siteUrl, consentLabel, regional, replayLabel }) {
     const { labels } = links;
     const buildItems = buildInfoItems(buildInfo);
-    return (_jsxs("footer", { className: "hagilight-footer", children: [_jsx(FooterBrand, { locale: links.locale, links: links.quick, avatar: avatar, siteId: siteId, siteUrl: siteUrl }), _jsx("div", { className: "hagilight-footer__sections", children: _jsx("div", { className: "hagilight-cols", children: links.columns.map((column, index) => (_jsxs("nav", { className: "hagilight-col", "data-column": column.id, style: { '--hagilight-col-i': index }, "aria-labelledby": `hagilight-col-${column.id}`, children: [_jsx("h2", { id: `hagilight-col-${column.id}`, children: labels.columns[column.id] }), _jsx("ul", { children: column.entries.map((entry) => (_jsx("li", { children: _jsx(ColumnLink, { entry: entry }) }, entry.id))) })] }, column.id))) }) }), _jsxs("div", { className: "hagilight-footer__base", children: [links.feeds.length > 0 && (_jsx("nav", { className: "hagilight-footer__feeds", "aria-label": labels.navigation.feeds, children: links.feeds.map((entry) => (_jsx(ColumnLink, { entry: entry }, entry.id))) })), (links.filings.length > 0 || consentLabel) && (_jsxs("nav", { className: "hagilight-footer__filings", "aria-label": labels.navigation.filings, children: [links.filings.map((link) => (_jsx("a", { href: link.href, target: link.target, rel: link.rel, "aria-label": link.ariaLabel, children: link.label }, link.id))), consentLabel && (_jsx("button", { type: "button", className: "hagilight-footer__consent", "data-consent-preferences": true, children: consentLabel }))] }))] }), _jsxs("p", { className: "hagilight-footer__copyright", children: [_jsxs("span", { children: ["\u00A9 ", year, " HagiCode"] }), ' | ', _jsxs("span", { className: "hagilight-footer__attribution", children: ["Powered By hagilight-docusaurus@", version] }), buildItems.map((item) => (_jsxs(Fragment, { children: [' | ', _jsxs("span", { className: "hagilight-footer__build", "data-build-field": item.field, title: item.title, "data-build-commit": item.title, children: [item.label, ": ", item.datetime ? _jsx("time", { dateTime: item.datetime, children: item.text }) : item.text] })] }, item.field)))] })] }));
+    return (_jsxs("footer", { className: "hagilight-footer", children: [_jsx(FooterBrand, { locale: links.locale, links: links.quick, avatar: avatar, siteId: siteId, siteUrl: siteUrl }), _jsx("div", { className: "hagilight-footer__sections", children: _jsx("div", { className: "hagilight-cols", children: links.columns.map((column, index) => (_jsxs("nav", { className: "hagilight-col", "data-column": column.id, style: { '--hagilight-col-i': index }, "aria-labelledby": `hagilight-col-${column.id}`, children: [_jsx("h2", { id: `hagilight-col-${column.id}`, children: labels.columns[column.id] }), _jsx("ul", { children: column.entries.map((entry) => (_jsx("li", { children: _jsx(ColumnLink, { entry: entry }) }, entry.id))) })] }, column.id))) }) }), _jsxs("div", { className: "hagilight-footer__base", children: [links.feeds.length > 0 && (_jsx("nav", { className: "hagilight-footer__feeds", "aria-label": labels.navigation.feeds, children: links.feeds.map((entry) => (_jsx(ColumnLink, { entry: entry }, entry.id))) })), (links.filings.length > 0 || consentLabel) && (_jsxs("nav", { className: "hagilight-footer__filings", "aria-label": labels.navigation.filings, children: [links.filings.map((link) => (_jsx("a", { href: link.href, target: link.target, rel: link.rel, "aria-label": link.ariaLabel, children: link.label }, link.id))), consentLabel && (_jsx("button", { type: "button", className: "hagilight-footer__consent", "data-consent-preferences": true, "data-consent-entry": regional ? 'settings' : undefined, hidden: regional, children: consentLabel })), consentLabel && replayLabel && (_jsx("button", { type: "button", className: "hagilight-footer__consent", "data-consent-preferences": true, "data-consent-mode": "replay", "data-consent-entry": "replay", hidden: true, children: replayLabel }))] }))] }), _jsxs("p", { className: "hagilight-footer__copyright", children: [_jsxs("span", { children: ["\u00A9 ", year, " HagiCode"] }), ' | ', _jsxs("span", { className: "hagilight-footer__attribution", children: ["Powered By hagilight-docusaurus@", version] }), buildItems.map((item) => (_jsxs(Fragment, { children: [' | ', _jsxs("span", { className: "hagilight-footer__build", "data-build-field": item.field, title: item.title, "data-build-commit": item.title, children: [item.label, ": ", item.datetime ? _jsx("time", { dateTime: item.datetime, children: item.text }) : item.text] })] }, item.field)))] })] }));
 }

package/dist/theme/Footer/index.js

@@ -2,8 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import FooterDefaults from '@theme-init/Footer';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import { usePluginData } from '@docusaurus/useGlobalData';
-import { resolveFooterLinks } from '../../footer.js';
-import { resolveConsentCopy } from '@hagicode/hagilight-core/consent-copy';
+import { resolveFooterConsent, resolveFooterLinks } from '../../footer.js';
 import { PLUGIN_NAME } from '../../global-data.js';
 import { FooterView } from './FooterView.js';
 import avatarAvif from '@hagicode/hagilight-core/assets/footer/avatar.avif';
@@ -13,6 +12,7 @@ export default function Footer() {
     const { version, options, buildInfo, footerAvatarPool } = usePluginData(PLUGIN_NAME);
     if (!options.footer)
         return _jsx(FooterDefaults, {});
+    const consent = resolveFooterConsent(options.consent, i18n.currentLocale);
     const avatar = options.footerAvatar.avatar
         ? { avif: avatarAvif, webp: avatarWebp, randomPool: footerAvatarPool }
         : undefined;
@@ -22,5 +22,5 @@ export default function Footer() {
         links: options.links,
         rssEnabled: options.rss.enabled,
     });
-    return (_jsx(FooterView, { links: links, version: version, year: new Date().getFullYear(), buildInfo: buildInfo, avatar: avatar, siteId: options.links.siteId, siteUrl: options.links.siteUrl ?? siteConfig.url, consentLabel: options.consent.enabled ? resolveConsentCopy(i18n.currentLocale).footerEntry : undefined }));
+    return (_jsx(FooterView, { links: links, version: version, year: new Date().getFullYear(), buildInfo: buildInfo, avatar: avatar, siteId: options.links.siteId, siteUrl: options.links.siteUrl ?? siteConfig.url, consentLabel: consent.consentLabel, regional: consent.regional, replayLabel: consent.replayLabel }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-docusaurus",
-  "version": "0.20.1-dev.196.1.d67f4e4",
+  "version": "0.20.1-dev.199.1.c17b214",
   "type": "module",
   "description": "Docusaurus plugin for HagiCode site features: footer, analytics, promote card, locales, SEO, sitemap, robots.txt, and RSS",
   "repository": {
@@ -39,7 +39,7 @@
   ],
   "dependencies": {
     "@docusaurus/types": "^3.9.2",
-    "@hagicode/hagilight-core": "0.20.1-dev.196.1.d67f4e4"
+    "@hagicode/hagilight-core": "0.20.1-dev.199.1.c17b214"
   },
   "peerDependencies": {
     "@docusaurus/core": "^3.9.2",