@getvitops/astro 3.0.0 → 4.1.0

package/src/components/Head.astro

@@ -41,6 +41,33 @@ const THEME_SCRIPT =
   `if(s==='light'||s==='dark'){document.documentElement.dataset.theme=s;` +
   `document.documentElement.style.colorScheme=s+' only'}}catch(e){}`;
 
+/**
+ * The consent gate's build-time signal: "something on this page may need
+ * permission, and the real gate hasn't loaded yet."
+ *
+ * `consent.js` and `elements.js` are both deferred modules with no ordering
+ * guarantee between them, so `<wc-color-scheme-toggle>` can upgrade and be clicked
+ * before the gate exists. Without this, a caller probing for
+ * `window.vitopsConsent` in that window would see nothing, correctly conclude
+ * that sites without the gate should just store — and store. The stub closes the
+ * window by making the gate's *existence* known synchronously in `<head>`, which
+ * is the only place that beats every deferred bundle.
+ *
+ * It answers `false` to everything, because nothing is granted until the store
+ * has been read, and queues what it was asked so `consent/runtime.ts` can replay
+ * it on evaluation. `q` entries are `[category]` for `require()` and
+ * `[category, resolve]` for `request()`. Same shape as the `dataLayer`/`gtag`
+ * stub in `analytics.ts` and for the same reason.
+ *
+ * Emitted only when the gate is on: its absence is what tells a caller the site
+ * has no gate at all.
+ */
+const CONSENT_STUB =
+  `window.vitopsConsent=window.vitopsConsent||{q:[],` +
+  `require:function(c){this.q.push([c]);return false},` +
+  `request:function(c){var s=this;return new Promise(function(r){s.q.push([c,r])})},` +
+  `granted:function(){return false},needed:function(){return false}};`;
+
 /*
  * No `<html>` class flips here on purpose. `animation.css` used to need `no-js`
  * and `.no-scroll-timeline` set before first paint; it now asks the platform
@@ -80,12 +107,23 @@ const THEME_SCRIPT =
 {/* Set by vitops({ sitemap }); null when no sitemap was registered. */}
 {head.sitemap && <link rel="sitemap" type="application/xml" href={head.sitemap} />}
 
+{/*
+  The consent stub — synchronous, and ahead of every module script on purpose.
+  See CONSENT_STUB above: it exists so that code which loads before the gate can
+  tell "the gate isn't here yet" from "this site has no gate", and queue rather
+  than assume it may store. Keyed on `head.consent` (is the gate on?) rather than
+  `head.consentRuntime` (does anything need scheduling?) — a site whose only tag
+  is cookieless loads the runtime to schedule it but gates nothing, so there is
+  nothing for a caller to queue behind.
+*/}
+{head.consent && <script is:inline set:html={CONSENT_STUB} />}
+
 {webComponents && (
   <>
     {/*
       Apply the remembered colour scheme before first paint.
 
-      `<color-scheme-toggle>` persists the choice to localStorage, but it loads
+      `<wc-color-scheme-toggle>` persists the choice to localStorage, but it loads
       as a deferred module — so without this every navigation would paint the
       light token set and flip to dark once the element upgraded. Synchronous and
       inline on purpose: it has to run before the body renders.

package/src/components/Tracking.astro

@@ -0,0 +1,43 @@
+---
+/**
+ * <Tracking /> — ad-click attribution capture. Place in your layout's <head>;
+ * requires the vitops() integration, which supplies `virtual:getvitops/head`.
+ *
+ * A dumb renderer over `resolveTracking()` (src/tracking.ts) — the one decision,
+ * which consent category `_ac` waits on, lives there and is unit-tested.
+ *
+ * Two things it emits, and the marker is the interesting one:
+ *
+ *  - **The marker** carries `data-consent` (which category) and
+ *    `data-consent-cookies` (what to clear). It deliberately does *not* carry
+ *    `data-vitops-tag`, so the consent runtime's `scan()` never tries to activate
+ *    it — this script is ungated by design, because reading the query string is
+ *    not storage and the click ID is only in the URL on the landing page. But
+ *    `clearCookies()` queries `[data-consent="<category>"]` and reads
+ *    `data-consent-cookies` off whatever it finds, so revoking consent clears
+ *    `_ac`. That cleanup did not exist before.
+ *  - **The script**, which captures synchronously and then waits on consent for
+ *    the *write* only. See src/scripts/tracking.ts.
+ *
+ * `<meta>` rather than a `<span>` so it is valid in `<head>`, where this
+ * component belongs — the capture wants to run before the visitor can navigate.
+ */
+// @ts-ignore — virtual module provided by the vitops() integration at build time
+import head from 'virtual:getvitops/head';
+
+const { enabled, category, cookies } = head.tracking ?? { enabled: false };
+---
+
+{enabled && (
+  <>
+    <meta
+      name="vitops-tracking"
+      data-vitops-tracking
+      data-consent={category}
+      data-consent-cookies={cookies?.length ? cookies.join(',') : undefined}
+    />
+    <script>
+      import '../scripts/tracking.ts';
+    </script>
+  </>
+)}

package/src/components/Tree.astro

@@ -0,0 +1,82 @@
+---
+/**
+ * An accessible disclosure tree, progressively enhanced.
+ *
+ * Tier-3 in the framework's terms — an authoring convenience that emits the right
+ * `.tree` markup and requires **no runtime JS**. What it renders is the whole
+ * content, and it stands on its own:
+ *
+ *   - structure is real `<ul>`/`<li>` nesting, so assistive tech announces list
+ *     position and depth. A `<div>` soup looks identical and tells a screen-reader
+ *     user nothing about where they are;
+ *   - every branch is a native `<details>`/`<summary>`, so expanded state and
+ *     keyboard operation come from the platform. No `role="tree"`, no
+ *     `aria-expanded` bookkeeping — a hand-rolled ARIA tree that loses its JS is
+ *     worse than no ARIA at all;
+ *   - nodes carry ids, so any node is linkable without JS.
+ *
+ * **This component emits its own `<wc-tree>`** — do NOT wrap it in one. That is the
+ * tier-3 rule ("the wrapper emits its `<wc-*>` tag with the accessible fallback
+ * inside"), and `CookieConsent.astro` does the same with `<wc-consent>`.
+ * `<wc-tree><Tree /></wc-tree>` nests two elements binding the same tree; the
+ * element now defers to an enclosing one, so it degrades to a no-op rather than two
+ * duelling toolbars, but the single call is the intended shape.
+ *
+ * `<wc-tree>` upgrades it with filter, expand/collapse-all and deep-linking. If
+ * that never loads, only those three conveniences are missing — which is why
+ * `enhance={false}` is a supported way to get the bare fragment.
+ */
+import type { TreeItem } from './tree.ts';
+import TreeNode from './TreeNode.astro';
+
+interface Props {
+  items: TreeItem[];
+  /** Placeholder + aria-label for the filter `<wc-tree>` generates. */
+  label?: string;
+  /** Accessible name for the list itself. */
+  ariaLabel?: string;
+  /** Branches shallower than this render open. 0 = everything closed. */
+  openDepth?: number;
+  /**
+   * Emit the `<wc-tree>` wrapper (default `true`).
+   *
+   * Set false when the fragment is going somewhere the element cannot run or is
+   * unwanted — an email, a PDF, a server-rendered block on a page that doesn't load
+   * `elements.js`. The tree itself is unchanged; only the enhancement layer is
+   * omitted, so nothing is lost but filter/expand-all/deep-link.
+   */
+  enhance?: boolean;
+}
+const {
+  items,
+  label = 'Filter',
+  ariaLabel,
+  openDepth = 0,
+  enhance = true,
+  // Anything else is passed through to `<wc-tree>`, so the element can grow
+  // attributes without this component's prop surface tracking them.
+  ...rest
+} = Astro.props;
+---
+
+{/* One `<ul>`, rendered once, wrapped or not — duplicating the tree markup per
+    branch is how the two paths would drift. */}
+<Fragment>
+  {
+    enhance ? (
+      <wc-tree label={label} {...rest}>
+        <ul class="tree tree--lines" aria-label={ariaLabel}>
+          {items.map((item) => (
+            <TreeNode item={item} depth={0} openDepth={openDepth} />
+          ))}
+        </ul>
+      </wc-tree>
+    ) : (
+      <ul class="tree tree--lines" aria-label={ariaLabel}>
+        {items.map((item) => (
+          <TreeNode item={item} depth={0} openDepth={openDepth} />
+        ))}
+      </ul>
+    )
+  }
+</Fragment>

package/src/components/TreeNode.astro

@@ -0,0 +1,63 @@
+---
+/**
+ * One node of a `<Tree />`, recursing through `Astro.self`.
+ *
+ * Two shapes, and the choice is semantic rather than cosmetic:
+ *
+ *   - a **branch** wraps its label in `<details>`/`<summary>` — a native
+ *     disclosure button, so expanded state is announced and keyboard operation
+ *     is free. The child `<ul>` lives inside the `<details>`, which is what makes
+ *     it collapse with no JS.
+ *   - a **leaf** is a plain `.tree__content` row. A `<details>` with nothing to
+ *     disclose would still render a control and announce as collapsible.
+ *
+ * The item class sits on the `<li>` in both cases, so `<wc-tree>`'s filter treats
+ * leaves and branches as one kind of thing and hiding one hides its whole row.
+ */
+import type { TreeItem } from './tree.ts';
+
+interface Props {
+  item: TreeItem;
+  depth: number;
+  /** Branches at a depth below this render open. */
+  openDepth: number;
+}
+const { item, depth, openDepth } = Astro.props;
+
+const kids = item.children ?? [];
+const isBranch = kids.length > 0;
+---
+
+<li class="tree__item" id={item.id}>
+  {
+    isBranch ? (
+      <details open={depth < openDepth}>
+        <summary>
+          <span class="tree__toggle" aria-hidden="true" />
+          <span class="tree__label">
+            {item.unnamed ? <em>{item.label}</em> : <code>{item.label}</code>}
+            {item.badge && <span class="badge">{item.badge}</span>}
+            {item.flag && <span class="badge badge-danger">{item.flag}</span>}
+          </span>
+        </summary>
+        {item.descriptionHtml && <p class="tree__desc" set:html={item.descriptionHtml} />}
+        <ul class="tree">
+          {kids.map((kid) => (
+            <Astro.self item={kid} depth={depth + 1} openDepth={openDepth} />
+          ))}
+        </ul>
+      </details>
+    ) : (
+      <Fragment>
+        <span class="tree__content">
+          <span class="tree__label">
+            {item.unnamed ? <em>{item.label}</em> : <code>{item.label}</code>}
+            {item.badge && <span class="badge">{item.badge}</span>}
+            {item.flag && <span class="badge badge-danger">{item.flag}</span>}
+          </span>
+        </span>
+        {item.descriptionHtml && <p class="tree__desc" set:html={item.descriptionHtml} />}
+      </Fragment>
+    )
+  }
+</li>

package/src/components/WebComponentLoader.astro

@@ -6,7 +6,7 @@
  *
  * @example
  * <WebComponentLoader src="WCColorSchemeToggle" />
- * <color-scheme-toggle></color-scheme-toggle>
+ * <wc-color-scheme-toggle></wc-color-scheme-toggle>
  */
 interface Props {
   src: string;

package/src/components/tree.ts

@@ -0,0 +1,19 @@
+/** One node of a `<Tree />`. See `Tree.astro` for the rendering contract. */
+export interface TreeItem {
+  label: string;
+  /** Small type/meta chip after the label. */
+  badge?: string;
+  /**
+   * Rendered with `set:html`, so it MUST already be escaped. For schema text use
+   * the generator's `renderInlineMarkdown()` — one tested escaper beats each
+   * caller doing its own, which is how one of them eventually doesn't.
+   */
+  descriptionHtml?: string;
+  /** Extra chip, e.g. "required". */
+  flag?: string;
+  /** Anchor id, so the node is linkable with no JS. */
+  id?: string;
+  /** An unnamed group (a union branch) — label renders as emphasis, not code. */
+  unnamed?: boolean;
+  children?: TreeItem[];
+}

package/src/scripts/tracking.ts

@@ -0,0 +1,149 @@
+// Ad conversion tracking: capture click IDs from the landing URL, track tel:
+// clicks. Form enhancement is in form-enhance.ts.
+//
+// Runs early and ungated on purpose. Reading the query string is not storage and
+// needs nobody's permission; *keeping* it does. So the capture is synchronous —
+// it has to be, the click ID is only in the URL on the landing page — and only
+// the write to `_ac` waits on consent.
+//
+// The `_ac` cookie is a 90-day identifier tying a visitor to the ad that brought
+// them, which is what `marketing` covers. Two things follow, and both matter:
+//
+//   - It **demands** the category rather than passively reading it. Nothing else
+//     on a page would ask for `marketing`, so a passive `granted()` check is a
+//     permanent no-op: the banner never offers it, so it is never granted, so
+//     `_ac` is never written and no attribution ever reaches a notification —
+//     silently, on every site that enabled the gate.
+//   - It only demands when the URL actually carried something. A visitor arriving
+//     organically has nothing to attribute, so they are never asked. That is the
+//     whole point of a demand-driven banner applied to attribution: the one
+//     arrival that needs the permission is the one that requests it.
+//
+// With no gate on the page it behaves as it always has — a site that has not
+// adopted consent has made no promise for this to break.
+
+const COOKIE_NAME = '_ac';
+const COOKIE_DAYS = 90;
+const AB_COOKIE = '_ab';
+
+// Mirrors CLICK_ID_PARAMS/UTM_PARAMS in @getvitops/utils/tracking, deliberately
+// copied rather than imported: this file is inlined into the document by
+// <Tracking />, so a bare import would either fail or drag a module graph into
+// the critical path. `tracking.test.ts` in this package pins the two lists.
+const CLICK_ID_PARAMS = [
+  'gclid',
+  'gbraid',
+  'wbraid', // Google Ads
+  'fbclid', // Meta (Facebook/Instagram)
+  'ttclid', // TikTok
+  'rdt_cid', // Reddit
+  'ScCid', // Snapchat
+  'msclkid', // Microsoft/Bing
+  'li_fat_id', // LinkedIn
+  'epik', // Pinterest
+] as const;
+
+const UTM_PARAMS = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term'] as const;
+
+// ---------------------------------------------------------------------------
+// 1. Capture click IDs + UTMs from URL → cookie
+// ---------------------------------------------------------------------------
+
+const params = new URLSearchParams(location.search);
+const trackingData: Record<string, string> = {};
+
+for (const key of [...CLICK_ID_PARAMS, ...UTM_PARAMS]) {
+  const value = params.get(key);
+  if (value) trackingData[key] = value;
+}
+
+// Include A/B variant if assigned by the router Worker. A cookie present but
+// valueless yields undefined, which must not be written into the record.
+const abMatch = document.cookie.split(';').find((c) => c.trim().startsWith(`${AB_COOKIE}=`));
+const abVariant = abMatch?.split('=')[1]?.trim();
+if (abVariant) trackingData['ab_variant'] = abVariant;
+
+function readCookie(): Record<string, unknown> | null {
+  const match = document.cookie.split(';').find((c) => c.trim().startsWith(`${COOKIE_NAME}=`));
+  if (!match) return null;
+  try {
+    const data: unknown = JSON.parse(decodeURIComponent(match.split('=').slice(1).join('=')));
+    return typeof data === 'object' && data !== null && !Array.isArray(data)
+      ? (data as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function persist(): void {
+  // Merge with any existing cookie data (don't overwrite prior click IDs from a
+  // different session unless new ones are present). `ts` keeps the FIRST
+  // capture: the 90-day window is measured from the original click, and taking
+  // the latest would restart it on every visit.
+  const existing = readCookie();
+  const merged = {
+    ...existing,
+    ...trackingData,
+    landingPage: location.pathname,
+    referrer: document.referrer || undefined,
+    ts: existing?.['ts'] ?? Date.now(),
+  };
+
+  // Remove undefined values before serializing
+  const clean = Object.fromEntries(Object.entries(merged).filter(([, v]) => v !== undefined));
+
+  const expires = new Date(Date.now() + COOKIE_DAYS * 864e5).toUTCString();
+  const secure = location.protocol === 'https:' ? ';Secure' : '';
+  document.cookie = `${COOKIE_NAME}=${encodeURIComponent(
+    JSON.stringify(clean),
+  )};expires=${expires};path=/;SameSite=Lax${secure}`;
+}
+
+/** Typed locally: a global augmentation here would widen `Window` package-wide. */
+interface ConsentLike {
+  granted(c: string): boolean;
+  require(c: string): boolean;
+}
+const gate = (): ConsentLike | undefined =>
+  (window as unknown as { vitopsConsent?: ConsentLike }).vitopsConsent;
+
+if (Object.keys(trackingData).length > 0) {
+  // <Tracking /> writes the category onto this marker, which also carries
+  // `data-consent-cookies` so revoking clears `_ac`.
+  const marker = document.querySelector('[data-vitops-tracking]');
+  const category = marker?.getAttribute('data-consent') ?? 'marketing';
+
+  if (!gate()) {
+    // No gate on this site: behave as it always has.
+    persist();
+  } else {
+    // Ask. This is what raises the banner — without it nothing on the page ever
+    // demands `marketing`, so it is never granted and `_ac` is never written.
+    if (gate()?.require(category)) persist();
+
+    // Then keep listening. A standing listener rather than acting on the one-shot
+    // answer above, for two reasons that both bite: `window.vitopsConsent` may
+    // still be the inline stub <Head /> emits — which queues `require()` and has
+    // no `subscribe` at all — and the visitor may accept a moment later, in this
+    // same page view, with the click ID still in the URL. The event fires either
+    // way, and the runtime publishes once on startup after draining the stub.
+    document.addEventListener('vitops:consent', () => {
+      if (gate()?.granted(category)) persist();
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 2. Tel: click tracking via sendBeacon
+// ---------------------------------------------------------------------------
+
+document.addEventListener('click', (e) => {
+  const link = (e.target as Element).closest?.('a[href^="tel:"]') as HTMLAnchorElement | null;
+  if (!link) return;
+
+  // Fire-and-forget beacon; don't block the tel: navigation
+  if (navigator.sendBeacon) {
+    navigator.sendBeacon('/api/track', JSON.stringify({ event: 'call', phone: link.href }));
+  }
+});

package/src/tracking.ts

@@ -0,0 +1,82 @@
+/**
+ * The `<Tracking />` resolution layer — tracking config in, what to emit out.
+ *
+ * Separate from `Tracking.astro` for the same reason `analytics.ts` is separate
+ * from `Analytics.astro`: everything decidable is a pure function asserted in
+ * `tracking.test.ts`, and the component only renders what this returns.
+ *
+ * The one decision here is **which consent category the `_ac` cookie waits on**,
+ * and it is stated rather than inferred. `_ac` is a 90-day identifier tying a
+ * visitor to the ad that brought them, so `marketing` is the default — but a site
+ * using click IDs purely for its own campaign reporting may reasonably file it
+ * under `analytics`, and that is the consumer's call to make, not ours to guess.
+ */
+
+/** Which consent category the attribution cookie waits on. */
+export type TrackingCategory = 'marketing' | 'analytics';
+
+export interface GetvitopsTrackingOptions {
+  /** Capture ad click IDs and UTMs into `_ac`. */
+  enabled?: boolean;
+  /** Default `marketing`. */
+  category?: TrackingCategory;
+  /** Informational; capture recognises every known click-ID parameter regardless. */
+  platforms?: string[];
+}
+
+/** The cookie the capture script writes. Mirrors `TRACKING_COOKIE` in utils. */
+export const TRACKING_COOKIE = '_ac';
+
+export interface ResolvedTracking {
+  enabled: boolean;
+  category: TrackingCategory;
+  /** Cookie names to clear on revoke — rides on `data-consent-cookies`. */
+  cookies: string[];
+  /** Configuration problems, as prose. The integration logs these. */
+  warnings: string[];
+}
+
+export interface ResolveTrackingContext {
+  /** Is the consent gate enabled on this site (`vitops({ consent })`)? */
+  consent?: boolean;
+  /** Categories the banner offers, so we can catch a demand with no row. */
+  consentCategories?: readonly string[];
+}
+
+/**
+ * Resolve the tracking config into what the component emits.
+ *
+ * Two warnings, both about the same failure — a persistent identifier written
+ * with no way for the visitor to decline, or a permission asked for with no way
+ * to answer. Returned as data rather than logged here so the check is a test
+ * rather than a line someone might scroll past, exactly as `resolveAnalytics`
+ * does.
+ */
+export function resolveTracking(
+  opts: GetvitopsTrackingOptions | undefined,
+  ctx: ResolveTrackingContext = {},
+): ResolvedTracking {
+  const warnings: string[] = [];
+  const category: TrackingCategory = opts?.category ?? 'marketing';
+  const enabled = opts?.enabled === true;
+
+  if (!enabled) return { enabled: false, category, cookies: [], warnings };
+
+  if (!ctx.consent) {
+    warnings.push(
+      `tracking is on, so this site writes the \`${TRACKING_COOKIE}\` cookie — a 90-day ` +
+        'identifier tying a visitor to the ad that brought them — and `consent` is off, so it ' +
+        'is written for every visitor with no way to decline. Set `consent: true`.',
+    );
+  } else if (ctx.consentCategories && !ctx.consentCategories.includes(category)) {
+    // The banner would be raised for a category it renders no row for: the
+    // visitor is asked a question the form does not show them.
+    warnings.push(
+      `tracking demands the \`${category}\` consent category, but the banner offers ` +
+        `${ctx.consentCategories.join(', ') || 'nothing'}. Add \`${category}\` to ` +
+        '`consent.categories`, or the visitor is asked about something the banner never names.',
+    );
+  }
+
+  return { enabled, category, cookies: [TRACKING_COOKIE], warnings };
+}

package/virtual.d.ts

@@ -47,6 +47,17 @@ declare module 'virtual:getvitops/head' {
     consentCategories: string[];
     consentPolicyUrl: string | null;
     consentRuntime: boolean;
+    // Structurally `ResolvedTracking` (src/tracking.ts) — resolved in the
+    // integration rather than the component because its warnings belong beside
+    // the others, and the offered consent categories it checks against are known
+    // only there.
+    tracking: { enabled: boolean; category: string; cookies: string[] } | null;
+    // The site config's `site.ads` block plus this environment's switch —
+    // structurally `{ enabled, properties }` (src/ads.ts), re-typed by <Ads /> on
+    // the way into `resolveAds`. Read in the integration because that is where the
+    // site config is already parsed, and because a pixel is a `marketing` demand
+    // the banner must have a row for.
+    ads: { enabled: boolean; properties: Record<string, unknown> } | null;
   }
   const data: HeadData;
   export default data;