@getvitops/astro 2.1.0 → 4.0.0

package/src/components/Popover.astro

@@ -17,7 +17,7 @@ interface Props {
   /**
    * Map a semantic name onto a fully-qualified one before rendering.
    *
-   * @deprecated The `icons` option on `getvitops()` now does this centrally, so
+   * @deprecated The `icons` option on `vitops()` now does this centrally, so
    * the site's set is configured once instead of threaded through every call
    * site. Left in place because removing it would break consumers passing one;
    * when omitted, `<Icon />` resolves through the site config.

package/src/components/Seo.astro

@@ -4,7 +4,7 @@
  * alongside <Head /> (which owns favicons, theme-color and the web-component
  * runtime — the two don't overlap).
  *
- * Site-level defaults come from `getvitops({ seo: … })` via the
+ * Site-level defaults come from `vitops({ seo: … })` via the
  * `virtual:getvitops/head` module; the props here override them per page.
  *
  * It owns <title> and <meta name="description">, so **remove them from your
@@ -21,7 +21,7 @@
  * On an EmDash site use <EmDashHead> instead — it covers the same tags from the
  * CMS. Using both double-emits every og:/twitter: tag.
  */
-// @ts-ignore — virtual module provided by the getvitops() integration at build time
+// @ts-ignore — virtual module provided by the vitops() integration at build time
 import head from 'virtual:getvitops/head';
 import { resolveSeo, type SeoProps } from '../seo.ts';
 

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,147 @@
+// 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
+] 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/seo.ts

@@ -17,11 +17,11 @@ export type SeoTwitterCard = 'summary' | 'summary_large_image' | 'app' | 'player
 export type SeoOgType = 'website' | 'article' | 'profile';
 
 /**
- * Site-level SEO defaults, passed to `getvitops({ seo })` and baked into the
+ * Site-level SEO defaults, passed to `vitops({ seo })` and baked into the
  * `virtual:getvitops/head` module. Per-page `<Seo />` props override these.
  *
  * The vocabulary mirrors the site-config schema's `seo` block
- * (`@getvitops/generator`, `src/site.ts`) so a `SiteConfig` → these adapter would
+ * (`@getvitops/generator`, `src/config.ts`) so a `Config` → these adapter would
  * be a flat field map — but it is not imported from there. This is the
  * integration's own option surface, and it must stay JSON-serialisable: it is
  * `JSON.stringify`d into the virtual module, so no functions, no `URL`s, no dates.

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,11 @@ 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;
   }
   const data: HeadData;
   export default data;