@astronox/core 0.3.1 → 0.4.1

package/README.md

@@ -63,7 +63,7 @@ component labels can extend `defaultCoreMessages` through
   claims, Firestore, and app-owned mappings.
 - [`R2 publication`](docs/integrations/r2-publication.md): full provider
   snapshots and build-time public projection.
-- [`AdSense`](docs/integrations/adsense.md): provider setup, consent, slots, and
-  fallback canvas.
+- [`AdSense`](docs/integrations/adsense.md): typed configuration, responsive
+  units, host policy, Privacy & Messaging, and deployment.
 - [`release workflow`](docs/release-workflow.md): local links, verification, and
   consumer pinning order.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astronox/core",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Reusable Astro components, patterns, styles, and infrastructure for AstroNox sites.",
   "license": "MIT",
   "keywords": [

package/src/ads/adsense/AdsenseHead.astro

@@ -0,0 +1,55 @@
+---
+import type { AdsenseAdsConfig } from '../contracts';
+import {
+  renderAdsenseControlledMessagingScript,
+  renderAdsenseErrorProtectionScript,
+  toAdsenseClientId,
+} from './provider';
+
+type Props = {
+  config: AdsenseAdsConfig;
+  offerwallEligible: boolean;
+};
+
+const { config, offerwallEligible }: Props = Astro.props;
+const clientId = toAdsenseClientId(config.publisherId);
+const runtimeConfig = JSON.stringify({
+  allowedHosts: config.allowedHosts,
+  clientId,
+  messaging: {
+    adBlockingRecovery: config.messaging.adBlockingRecovery,
+    offerwall: config.messaging.offerwall,
+    offerwallEligible,
+  },
+  publisherId: config.publisherId,
+}).replaceAll('<', '\\u003c');
+const errorProtectionScript = config.messaging.errorProtectionCode
+  ? renderAdsenseErrorProtectionScript({
+      allowedHosts: config.allowedHosts,
+      code: config.messaging.errorProtectionCode,
+    })
+  : undefined;
+const controlledMessagingScript = renderAdsenseControlledMessagingScript(
+  config.messaging.offerwall && offerwallEligible,
+);
+---
+
+<meta name="google-adsense-account" content={clientId} />
+<script
+  is:inline
+  type="application/json"
+  data-astronox-adsense-config
+  set:html={runtimeConfig}
+/>
+<script is:inline set:html={controlledMessagingScript} />
+{
+  errorProtectionScript ? (
+    <script is:inline set:html={errorProtectionScript} />
+  ) : null
+}
+
+<script>
+  import { initAdsenseFromDocument } from './runtime';
+
+  initAdsenseFromDocument();
+</script>

package/src/ads/adsense/AdsenseUnit.astro

@@ -0,0 +1,45 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+import AdSlot from '../../components/monetization/AdSlot/AdSlot.astro';
+import { toAdsenseClientId } from './provider';
+
+type Props = Omit<HTMLAttributes<'aside'>, 'aria-label'> & {
+  format: 'display' | 'multiplex';
+  label: string;
+  publisherId: string;
+  size?: 'compact' | 'standard' | 'tall';
+  slotId: string;
+};
+
+const {
+  format,
+  label,
+  publisherId,
+  size = 'standard',
+  slotId,
+  ...attrs
+}: Props = Astro.props;
+const unitAttributes =
+  format === 'multiplex'
+    ? { 'data-ad-format': 'autorelaxed' }
+    : {
+        'data-ad-format': 'auto',
+        'data-full-width-responsive': 'true',
+      };
+---
+
+<AdSlot
+  {...attrs}
+  data-adsense-format={format}
+  data-adsense-unit
+  label={label}
+  size={size}
+  state="loading"
+>
+  <ins
+    {...unitAttributes}
+    class="adsbygoogle"
+    style="display:block"
+    data-ad-client={toAdsenseClientId(publisherId)}
+    data-ad-slot={slotId}></ins>
+</AdSlot>

package/src/ads/adsense/index.ts

@@ -1 +1,3 @@
-export * from '../adsense';
+export { default as AdsenseHead } from './AdsenseHead.astro';
+export { default as AdsenseUnit } from './AdsenseUnit.astro';
+export * from './provider';

package/src/ads/adsense/provider.ts

@@ -0,0 +1,41 @@
+const adsenseSellerId = 'f08c47fec0942fa0';
+
+export function toAdsenseClientId(publisherId: string): string {
+  return `ca-${publisherId}`;
+}
+
+export function renderAdsenseAdsTxt(publisherId: string): string {
+  return `google.com, ${publisherId}, DIRECT, ${adsenseSellerId}\n`;
+}
+
+export function renderAdsenseErrorProtectionScript({
+  allowedHosts,
+  code,
+}: {
+  allowedHosts: readonly string[];
+  code: string;
+}): string {
+  const hosts = JSON.stringify(
+    allowedHosts.map((host) => host.toLowerCase()),
+  ).replaceAll('<', '\\u003c');
+
+  return `if (${hosts}.includes(window.location.hostname.toLowerCase())) {\n${code}\n}`;
+}
+
+export function renderAdsenseControlledMessagingScript(
+  offerwallAllowed: boolean,
+): string {
+  return `window.googlefc = window.googlefc || {};
+window.googlefc.controlledMessagingFunction = function (message) {
+  if (${String(offerwallAllowed)}) {
+    message.proceed(true);
+    return;
+  }
+  var offerwall = window.googlefc.MessageTypeEnum && window.googlefc.MessageTypeEnum.OFFERWALL;
+  if (typeof offerwall === 'number') {
+    message.proceed(false, [offerwall]);
+    return;
+  }
+  message.proceed(true);
+};`;
+}

package/src/ads/adsense/runtime.ts

@@ -0,0 +1,284 @@
+import { setAdSlotState } from '../slot';
+
+const adsenseScriptTimeoutMs = 12_000;
+const adsenseUnitTimeoutMs = 30_000;
+
+type ControlledMessage = {
+  proceed(allowed: boolean, messageTypes?: readonly number[]): void;
+};
+
+type GoogleFundingChoicesCallback =
+  (() => void) | { CONSENT_API_READY: () => void };
+
+type GoogleFundingChoices = {
+  callbackQueue?: {
+    push(callback: GoogleFundingChoicesCallback): number;
+  };
+  controlledMessagingFunction?: (message: ControlledMessage) => void;
+  MessageTypeEnum?: {
+    OFFERWALL: number;
+  };
+  showRevocationMessage?: () => void;
+};
+
+type AdsenseRuntimeConfig = {
+  allowedHosts: readonly string[];
+  clientId: string;
+  messaging: {
+    adBlockingRecovery: boolean;
+    offerwall: boolean;
+    offerwallEligible: boolean;
+  };
+  publisherId: string;
+};
+
+declare global {
+  interface Window {
+    adsbygoogle?: Record<string, unknown>[];
+    googlefc?: GoogleFundingChoices;
+  }
+}
+
+let adsenseScript: Promise<void> | undefined;
+
+export function initAdsenseFromDocument(): void {
+  const config = readRuntimeConfig();
+  if (!config || !isAllowedHost(config.allowedHosts)) {
+    setAllAdUnitsState('unavailable');
+    return;
+  }
+
+  protectAdAnnotations();
+  configureControlledMessaging(config);
+  initPrivacySettingsControls();
+  if (config.messaging.adBlockingRecovery) {
+    loadAdBlockingRecovery(config.publisherId);
+  }
+
+  void loadAdsenseScript(config.clientId)
+    .then(initAdUnits)
+    .catch(() => setAllAdUnitsState('blocked'));
+}
+
+function readRuntimeConfig(): AdsenseRuntimeConfig | undefined {
+  const element = document.querySelector<HTMLScriptElement>(
+    'script[data-astronox-adsense-config]',
+  );
+  if (!element?.textContent) return undefined;
+
+  try {
+    return JSON.parse(element.textContent) as AdsenseRuntimeConfig;
+  } catch {
+    return undefined;
+  }
+}
+
+function isAllowedHost(allowedHosts: readonly string[]): boolean {
+  const hostname = window.location.hostname.toLowerCase();
+  if (
+    hostname === 'localhost' ||
+    hostname.endsWith('.localhost') ||
+    hostname === '127.0.0.1' ||
+    hostname === '::1'
+  ) {
+    return false;
+  }
+  return allowedHosts.some((host) => host.toLowerCase() === hostname);
+}
+
+function protectAdAnnotations(): void {
+  const protect = (root: ParentNode): void => {
+    if (
+      root instanceof HTMLElement &&
+      root.dataset.adAnnotation === 'exclude'
+    ) {
+      root.classList.add('google-anno-skip');
+    }
+    for (const element of root.querySelectorAll<HTMLElement>(
+      '[data-ad-annotation="exclude"]',
+    )) {
+      element.classList.add('google-anno-skip');
+    }
+  };
+
+  protect(document);
+  new MutationObserver((records) => {
+    for (const record of records) {
+      for (const node of record.addedNodes) {
+        if (node instanceof HTMLElement) protect(node);
+      }
+    }
+  }).observe(document.documentElement, { childList: true, subtree: true });
+}
+
+function configureControlledMessaging(config: AdsenseRuntimeConfig): void {
+  const googlefc = (window.googlefc ??= {});
+  googlefc.controlledMessagingFunction = (message) => {
+    const allowOfferwall =
+      config.messaging.offerwall && config.messaging.offerwallEligible;
+    if (allowOfferwall) {
+      message.proceed(true);
+      return;
+    }
+
+    const offerwallType = window.googlefc?.MessageTypeEnum?.OFFERWALL;
+    if (typeof offerwallType === 'number') {
+      message.proceed(false, [offerwallType]);
+      return;
+    }
+
+    message.proceed(true);
+  };
+}
+
+function initPrivacySettingsControls(): void {
+  const googlefc = (window.googlefc ??= {});
+  googlefc.callbackQueue ??= [];
+  googlefc.callbackQueue.push({
+    CONSENT_API_READY: () => {
+      for (const control of document.querySelectorAll<HTMLButtonElement>(
+        '[data-ads-consent-settings]:not([data-ads-consent-initialized])',
+      )) {
+        control.dataset.adsConsentInitialized = 'true';
+        control.hidden = false;
+        control.addEventListener('click', () => {
+          const showRevocationMessage = window.googlefc?.showRevocationMessage;
+          if (showRevocationMessage) {
+            window.googlefc?.callbackQueue?.push(showRevocationMessage);
+          }
+        });
+      }
+    },
+  });
+}
+
+function loadAdBlockingRecovery(publisherId: string): void {
+  if (document.querySelector('script[data-astronox-ad-recovery]')) return;
+
+  const script = document.createElement('script');
+  script.async = true;
+  script.dataset.astronoxAdRecovery = '';
+  script.src = `https://fundingchoicesmessages.google.com/i/${encodeURIComponent(publisherId)}?ers=1`;
+  document.head.append(script);
+  signalFundingChoicesPresence();
+}
+
+function signalFundingChoicesPresence(): void {
+  if (document.querySelector('iframe[name="googlefcPresent"]')) return;
+  if (!document.body) {
+    window.setTimeout(signalFundingChoicesPresence, 0);
+    return;
+  }
+
+  const frame = document.createElement('iframe');
+  frame.name = 'googlefcPresent';
+  frame.hidden = true;
+  frame.style.display = 'none';
+  document.body.append(frame);
+}
+
+function loadAdsenseScript(clientId: string): Promise<void> {
+  if (adsenseScript) return adsenseScript;
+
+  const loading = new Promise<void>((resolve, reject) => {
+    const existing = document.querySelector<HTMLScriptElement>(
+      'script[data-astronox-adsense]',
+    );
+    if (existing?.dataset.loaded === 'true') {
+      resolve();
+      return;
+    }
+
+    const script = existing ?? document.createElement('script');
+    const timeout = window.setTimeout(() => {
+      reject(new Error('AdSense loading timed out'));
+    }, adsenseScriptTimeoutMs);
+    script.addEventListener(
+      'load',
+      () => {
+        window.clearTimeout(timeout);
+        script.dataset.loaded = 'true';
+        resolve();
+      },
+      { once: true },
+    );
+    script.addEventListener(
+      'error',
+      () => {
+        window.clearTimeout(timeout);
+        reject(new Error('AdSense failed to load'));
+      },
+      { once: true },
+    );
+
+    if (!existing) {
+      script.async = true;
+      script.crossOrigin = 'anonymous';
+      script.dataset.astronoxAdsense = '';
+      script.src = `https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=${encodeURIComponent(clientId)}`;
+      document.head.append(script);
+    }
+  });
+  adsenseScript = loading;
+  void loading.catch(() => {
+    if (adsenseScript === loading) adsenseScript = undefined;
+  });
+
+  return loading;
+}
+
+function initAdUnits(): void {
+  for (const slot of document.querySelectorAll<HTMLElement>(
+    '[data-adsense-unit]:not([data-adsense-initialized])',
+  )) {
+    initAdUnit(slot);
+  }
+}
+
+function initAdUnit(slot: HTMLElement): void {
+  slot.dataset.adsenseInitialized = 'true';
+  setAdSlotState(slot, 'loading');
+  const advertisement = slot.querySelector<HTMLElement>('.adsbygoogle');
+  if (!advertisement) {
+    setAdSlotState(slot, 'unavailable');
+    return;
+  }
+
+  const timeout = window.setTimeout(() => {
+    setAdSlotState(slot, 'unavailable');
+  }, adsenseUnitTimeoutMs);
+  const sync = (): void => {
+    if (advertisement.dataset.adStatus === 'filled') {
+      window.clearTimeout(timeout);
+      observer.disconnect();
+      setAdSlotState(slot, 'filled');
+    } else if (advertisement.dataset.adStatus === 'unfilled') {
+      window.clearTimeout(timeout);
+      observer.disconnect();
+      setAdSlotState(slot, 'unavailable');
+    }
+  };
+  const observer = new MutationObserver(sync);
+  observer.observe(advertisement, {
+    attributes: true,
+    attributeFilter: ['data-ad-status'],
+  });
+
+  try {
+    window.adsbygoogle ??= [];
+    window.adsbygoogle.push({});
+    sync();
+  } catch {
+    window.clearTimeout(timeout);
+    observer.disconnect();
+    setAdSlotState(slot, 'unavailable');
+  }
+}
+
+function setAllAdUnitsState(state: 'blocked' | 'unavailable'): void {
+  for (const slot of document.querySelectorAll<HTMLElement>(
+    '[data-adsense-unit]',
+  )) {
+    setAdSlotState(slot, state);
+  }
+}

package/src/ads/contracts.ts

@@ -1,11 +1,73 @@
 export type AdSlotState =
   'idle' | 'loading' | 'filled' | 'blocked' | 'unavailable';
 
-export type AdConsentProvider = {
-  canLoadAds(): boolean | Promise<boolean>;
+export type DisabledAdsConfig = {
+  enabled: false;
 };
 
-export interface AdProvider {
-  load(): Promise<void>;
-  request(slot: HTMLElement): Promise<void>;
+export type AdsenseAdsConfig = {
+  enabled: true;
+  provider: 'adsense';
+  allowedHosts: readonly string[];
+  publisherId: string;
+  units: {
+    pageEnd: string;
+  };
+  messaging: {
+    adBlockingRecovery: boolean;
+    offerwall: boolean;
+    errorProtectionCode?: string;
+  };
+};
+
+export type AdsConfig = DisabledAdsConfig | AdsenseAdsConfig;
+
+export const adAnnotationExclusionAttributes = {
+  'data-ad-annotation': 'exclude',
+} as const;
+
+export function defineAdsConfig<const TConfig extends AdsConfig>(
+  config: TConfig,
+): TConfig {
+  if (!config.enabled) return config;
+
+  if (config.allowedHosts.length === 0) {
+    throw new Error('Ad configuration requires at least one allowed hostname');
+  }
+  for (const host of config.allowedHosts) {
+    if (!isValidHostname(host)) {
+      throw new Error(`Invalid advertising hostname: ${host}`);
+    }
+  }
+  if (!/^pub-\d+$/.test(config.publisherId)) {
+    throw new Error('Invalid AdSense publisher id');
+  }
+  if (!/^\d+$/.test(config.units.pageEnd)) {
+    throw new Error('Invalid AdSense page-end slot id');
+  }
+  if (/<\/script/i.test(config.messaging.errorProtectionCode ?? '')) {
+    throw new Error(
+      'AdSense error protection must contain the script body only',
+    );
+  }
+
+  return config;
+}
+
+function isValidHostname(host: string): boolean {
+  if (!host || host !== host.trim() || host.includes('/')) return false;
+  if (
+    host.toLowerCase() === 'localhost' ||
+    host.toLowerCase().endsWith('.localhost') ||
+    host === '127.0.0.1' ||
+    host === '::1'
+  ) {
+    return false;
+  }
+
+  try {
+    return new URL(`https://${host}`).hostname === host.toLowerCase();
+  } catch {
+    return false;
+  }
 }

package/src/components/content/CardHeader/CardHeader.astro

@@ -17,6 +17,12 @@ type Props = HTMLAttributes<'header'> &
     headingLevel?: HeadingLevel;
     sticky?: boolean;
     tone?: Tone;
+    trigger?: {
+      controls: string;
+      expanded: boolean;
+      hidden?: boolean;
+      label: string;
+    };
   };
 
 const {
@@ -29,6 +35,7 @@ const {
   headingLevel = 2,
   sticky = false,
   tone,
+  trigger,
   ...attrs
 }: Props = Astro.props;
 const HeadingTag = `h${headingLevel}` as const;
@@ -80,6 +87,19 @@ const resolvedTone = tone ?? dataTone;
           ) : null
         }
       </Inline>
+      {
+        trigger ? (
+          <button
+            class="card-header__trigger"
+            type="button"
+            aria-controls={trigger.controls}
+            aria-expanded={trigger.expanded}
+            aria-label={trigger.label}
+            hidden={trigger.hidden}
+            data-card-header-trigger
+          />
+        ) : null
+      }
     </div>
 
     {

package/src/components/content/CardHeader/CardHeader.css

@@ -90,12 +90,33 @@
 }
 
 .card-header__main {
+  position: relative;
   display: grid;
   min-width: 0;
   align-content: center;
   padding: var(--nox-space-3) var(--nox-space-5);
 }
 
+.card-header__main:has(> .card-header__trigger) > [data-composition='inline'] {
+  pointer-events: none;
+}
+
+.card-header__trigger {
+  position: absolute;
+  z-index: 1;
+  inset: 0;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+}
+
+.card-header__trigger:focus-visible {
+  outline: var(--nox-focus-ring-width) solid var(--nox-tone-focus-ring);
+  outline-offset: calc(var(--nox-focus-ring-width) * -1);
+}
+
 .card-header[data-has-end='true'] .card-header__main {
   padding-block: var(--nox-space-1);
 }