@hagicode/hagilight-starlight 0.20.1-dev.196.1.d67f4e4 → 0.20.1-dev.200.1.6beb099

package/Footer.astro

@@ -18,6 +18,10 @@ interface Props {
   randomAvatar?: boolean;
   /** Adds the "Cookie settings" entry. Set only when the site mounts the consent popup. Defaults to `false`. */
   consent?: boolean;
+  /** A regional site: the "Cookie settings" entry is rendered hidden and revealed by the consent popup's decision. */
+  regional?: boolean;
+  /** A regional site with session replay opt-in: renders the replay entry, hidden until the decision reveals it. */
+  replayEntry?: boolean;
 }
 
 const {
@@ -29,6 +33,8 @@ const {
   avatar,
   randomAvatar,
   consent = false,
+  regional = false,
+  replayEntry = false,
 } = Astro.props;
 const consentCopy = resolveConsentCopy(locale);
 const buildItems = buildInfoItems(buildInfo);
@@ -105,7 +111,23 @@ const resolvedLinks = resolveSiteLinks(currentLanguage ?? locale, {
         >{link.label}</a>
       ))}
       {consent && (
-        <button type="button" class="hagilight-consent-entry" data-consent-preferences>{consentCopy.footerEntry}</button>
+        <button
+          type="button"
+          class="hagilight-consent-entry"
+          data-consent-preferences
+          data-consent-entry={regional ? 'settings' : undefined}
+          hidden={regional}
+        >{consentCopy.footerEntry}</button>
+      )}
+      {consent && replayEntry && (
+        <button
+          type="button"
+          class="hagilight-consent-entry"
+          data-consent-preferences
+          data-consent-mode="replay"
+          data-consent-entry="replay"
+          hidden
+        >{consentCopy.replayEntry}</button>
       )}
     </nav>
   </div>
@@ -176,6 +198,10 @@ const resolvedLinks = resolveSiteLinks(currentLanguage ?? locale, {
     cursor: pointer;
   }
 
+  .hagilight-consent-entry[hidden] {
+    display: none;
+  }
+
   /* Footer columns: four level, purpose-based columns. Each column owns a rule that
      draws in as it scrolls into view and runs the full width while the column is
      used; the other columns' headings step back. */

package/README.md

@@ -190,3 +190,30 @@ See the [repository documentation](https://github.com/HagiCode-org/hagilight#rea
 ### Consent
 
 `analytics.consent` (`enabled`, `privacyUrl`, `policyVersion`) is on by default whenever a provider is enabled. The plugin mounts the popup through its generated Footer and Head, on every page including 404, and passes `consent` to the Google Analytics, 51LA and PostHog components. `enabled: false` restores immediate loading; invalid `privacyUrl` or `policyVersion` values fail with the option named. See the core README, "Analytics consent", for the storage names and rules.
+
+#### Regional consent
+
+Set `analytics.consent.regions` to let visitors outside the consent-required countries start analytics without a click. Without it every visitor sees the popup and the output is unchanged. All options sit under `analytics.consent`, with the same names, defaults and errors as the Docusaurus and Astro integrations:
+
+| Option | Default | Values and errors |
+| --- | --- | --- |
+| `regions` | absent (global consent) | `'default'`, or a non-empty array of upper-case ISO 3166-1 alpha-2 codes that replaces the default set. Other values fail with an error naming `analytics.consent.regions`, which also fails when `enabled` is `false`. |
+| `countryCode` | none | One upper-case ISO code that skips detection. Needs `regions`. |
+| `regionHook` | none | Name of a function on `window` that returns `'required'`, `'notRequired'`, `'unknown'`, a boolean or a promise of one of these. Needs `regions`. |
+| `settingsEntry` | `'requiredOnly'` | `always` also shows Cookie settings to visitors who do not need consent. Needs `regions`. |
+| `sessionReplay` | `'optIn'` | `projectDefault` follows the PostHog project. `off` never runs replay in these regions and renders no entry. Needs `regions`. |
+
+A regional-only option set without `regions` fails with an error that names the option and says `regions` is required.
+
+```js
+hagilight({ analytics: { consent: { regions: 'default' } } });
+hagilight({ analytics: { consent: { regions: ['DE', 'FR'], settingsEntry: 'always' } } });
+```
+
+The default consent-required set is the EU27 (AT BE BG HR CY CZ DK EE FI FR DE GR HU IE IT LV LT LU MT NL PL PT RO SK SI ES SE), the EEA (IS LI NO), GB, CH and BR. It is a product configuration, not legal advice, and needs confirmation by counsel. A site list replaces it entirely.
+
+Resolution runs in this order: `countryCode`, `regionHook`, the same-origin `/cdn-cgi/trace` `loc` line (1200 ms timeout, no credentials, the IP line is never read), then a time-zone fallback. The whole decision is bounded by 1800 ms. **Fail-closed:** an unknown location, a failing hook, a timeout or an invalid code means consent is required, so the popup appears and no provider loads until the visitor accepts.
+
+`/cdn-cgi/trace` answers only for hostnames proxied through Cloudflare. On `www` it returned no `loc` in verification, so the time-zone fallback decides there unless the site sets `countryCode` or `regionHook`.
+
+With `sessionReplay: 'optIn'`, replay stays off in not-required regions until the visitor allows it from the footer entry "Allow session replay". Google Consent Mode and cookieless pings stay off in every region.

package/dist/index.d.ts

@@ -40,6 +40,19 @@ export interface HagilightConsentOptions {
     privacyUrl?: string;
     /** Defaults to `1`. Changing it asks every visitor again. 1 to 32 letters, digits, dots, underscores or hyphens. */
     policyVersion?: string;
+    /**
+     * Regional consent. `default` uses the built-in consent-required set; an array of upper-case ISO 3166-1 alpha-2 codes
+     * replaces it. Absent keeps the global popup. Unknown location means consent is required.
+     */
+    regions?: 'default' | readonly string[];
+    /** An ISO 3166-1 alpha-2 code that fixes every visitor's region and skips detection. Needs `regions`. */
+    countryCode?: string;
+    /** The name of a function defined on `window` that returns the visitor's region. Needs `regions`. */
+    regionHook?: string;
+    /** Defaults to `requiredOnly`, which shows the Cookie settings entry only where consent is required. `always` shows it everywhere. */
+    settingsEntry?: 'requiredOnly' | 'always';
+    /** Defaults to `optIn`, which offers session replay to visitors where consent is not required. `projectDefault` or `off` change that. */
+    sessionReplay?: 'optIn' | 'projectDefault' | 'off';
 }
 export interface HagilightPostHogOptions {
     /** Defaults to true when the provider options are omitted, otherwise to whether apiKey is set. */

package/dist/index.js

@@ -6,7 +6,7 @@ import { resolveBuildInfo } from '@hagicode/hagilight-core/build-info-resolver';
 import { resolveFooterAvatarOptions } from '@hagicode/hagilight-core/footer-avatar';
 import { checkContentImageRegistration, registerContentImages } from '@hagicode/hagilight-core/content-images';
 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 { resolveRssLocales } from '@hagicode/hagilight-core/rss';
 import { RSS_OWNER, registerStarlightRssOwner, } from '@hagicode/hagilight-core/rss-ownership';
 import { isValidSeoImageReference, resolveSeoImageUrl } from '@hagicode/hagilight-core/seo';
@@ -59,15 +59,18 @@ const contentWidthHeadScript = `(() => {
 })();`;
 /**
  * Consent is on by default whenever a provider is enabled, and `enabled: false` restores immediate loading. Invalid
- * values throw from the core validators, which name the option.
+ * values throw from the core validators, which name the option. Regional options are validated by the core too, so
+ * every integration reports the same messages; they resolve to `undefined` on a global site.
  */
 function resolveConsentOptions(config, providers) {
     const record = optionalRecord(config, 'analytics consent');
     const requested = optionalBoolean(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),
+        regional: resolveRegionalOptions(record, record?.enabled !== false),
         providers,
     };
 }
@@ -283,8 +286,16 @@ import options from '${optionsId}';
     const consentImport = serializedOptions.consentEnabled
         ? `import CookieConsent from ${JSON.stringify(coreExport('CookieConsent'))};`
         : '';
+    // Regional sites also pass their options to the popup, whose descriptor the footer entries read at runtime.
+    const consentRegionalAttribute = serializedOptions.consentRegional ? ' regional={options.consentRegional}' : '';
     const consentRender = serializedOptions.consentEnabled
-        ? '<CookieConsent providers={options.consentProviders} privacyUrl={options.consentPrivacyUrl} policyVersion={options.consentPolicyVersion} locale={Astro.locals?.starlightRoute?.locale} />'
+        ? `<CookieConsent providers={options.consentProviders} privacyUrl={options.consentPrivacyUrl} policyVersion={options.consentPolicyVersion} locale={Astro.locals?.starlightRoute?.locale}${consentRegionalAttribute} />`
+        : '';
+    // Regional entries render hidden; the popup reveals them from its descriptor. The replay entry needs opt-in.
+    const footerRegionalAttributes = serializedOptions.consentRegional
+        ? `  regional={true}
+  replayEntry={${serializedOptions.consentRegional.sessionReplay === 'optIn'}}
+`
         : '';
     const footerSource = `---
 import Footer from ${JSON.stringify(footerPath)};
@@ -303,7 +314,7 @@ import options from '${optionsId}';
   avatar={options.footerAvatar.avatar}
   randomAvatar={options.footerAvatar.randomAvatar}
 ${consentAttribute ? `  consent={true}
-` : ''}/>
+` : ''}${footerRegionalAttributes}/>
 ${promotionRender}
 ${analyticsRender}
 ${consentRender}
@@ -509,6 +520,7 @@ export default function hagilight(options = {}) {
         consentProviders: consent.providers,
         consentPrivacyUrl: consent.privacyUrl,
         consentPolicyVersion: consent.policyVersion,
+        consentRegional: consent.regional,
         posthogSearchQuery,
         aiDisclosures,
         seoEnabled: seo.enabled,
@@ -612,7 +624,12 @@ export default function hagilight(options = {}) {
                         fiftyOneLa: serializedOptions.fiftyOneLaId !== undefined,
                         posthog: serializedOptions.posthogApiKey !== undefined,
                     },
-                    features: { seo: seo.enabled, promoto: promotoEnabled, consent: consent.enabled },
+                    features: {
+                        seo: seo.enabled,
+                        promoto: promotoEnabled,
+                        consent: consent.enabled,
+                        consentMode: consent.enabled ? (consent.regional ? 'regional' : 'globalRequired') : undefined,
+                    },
                 }, unregisterSiteMetadataOwner));
                 updateConfig({
                     ...(config.logo === undefined ? { logo: { src: defaultLogo, alt: 'HagiCode' } } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-starlight",
-  "version": "0.20.1-dev.196.1.d67f4e4",
+  "version": "0.20.1-dev.200.1.6beb099",
   "type": "module",
   "description": "Starlight plugin and components for HagiCode documentation",
   "repository": {
@@ -53,7 +53,7 @@
     "assets/showcase/*"
   ],
   "dependencies": {
-    "@hagicode/hagilight-core": "0.20.1-dev.196.1.d67f4e4"
+    "@hagicode/hagilight-core": "0.20.1-dev.200.1.6beb099"
   },
   "peerDependencies": {
     "@astrojs/starlight": "^0.42.4",