blume 2.0.3 → 2.1.0

package/src/components/props.ts

@@ -44,9 +44,15 @@ export type FrameProps = ComponentProps<
 export type PanelProps = ComponentProps<
   typeof import("./content/Panel.astro").default
 >;
+export type ParamFieldProps = ComponentProps<
+  typeof import("./content/ParamField.astro").default
+>;
 export type PromptProps = ComponentProps<
   typeof import("./content/Prompt.astro").default
 >;
+export type ResponseFieldProps = ComponentProps<
+  typeof import("./content/ResponseField.astro").default
+>;
 export type StepProps = ComponentProps<
   typeof import("./content/Step.astro").default
 >;

package/src/consent/client.ts

@@ -0,0 +1,95 @@
+/**
+ * The browser half of the consent layer (`consent` in `blume.config.ts`),
+ * bundled into every layout by `ConsentHead.astro` and started once per real
+ * page load. It answers `window.blumeConsent` (see `init.ts`):
+ *
+ * - Analytics scripts wait in the page as `<script type="text/plain"
+ *   data-blume-consent="analytics">` (see `Analytics.astro`). Once the reader
+ *   allows analytics, each one runs, once per page load: the client router
+ *   brings the held tags back on every navigation, and running them again
+ *   would count every visit twice.
+ * - A reader who takes consent back after the scripts ran gets a reload, the
+ *   one way to stop scripts that already started.
+ * - Any element with `data-blume-consent-open` (the footer's Cookie settings
+ *   link) reopens the adapter's preferences.
+ * - An adapter with a browser module (`native()`'s banner, say) is started
+ *   from here once the runtime is listening; see `consent/clients.ts`.
+ */
+import type { BlumeConsent } from "../components/layout/consent/types.ts";
+
+/** The window, with the state the init script puts on it. */
+type ConsentWindow = Window & { blumeConsent?: BlumeConsent };
+
+/** Analytics tags held until the reader allows analytics. */
+export const HELD_SCRIPTS =
+  'script[type="text/plain"][data-blume-consent="analytics"]';
+
+const OPEN = "[data-blume-consent-open]";
+
+/**
+ * Run each held tag the page hasn't run yet, as a new `<script>` beside it
+ * with the same attributes and body. `ran` is keyed by the tag's markup,
+ * which is the same on every page, so a tag the router brings back is
+ * skipped.
+ */
+export const runHeldScripts = (ran: Set<string>): void => {
+  for (const held of document.querySelectorAll(HELD_SCRIPTS)) {
+    const key = held.outerHTML;
+    if (ran.has(key)) {
+      continue;
+    }
+    ran.add(key);
+    const script = document.createElement("script");
+    for (const { name, value } of held.attributes) {
+      if (name !== "type" && name !== "data-blume-consent") {
+        script.setAttribute(name, value);
+      }
+    }
+    // A created script is async unless told otherwise; keep the tags in
+    // document order, as the parser would have, unless one asked for async.
+    if (!held.hasAttribute("async")) {
+      script.async = false;
+    }
+    script.text = held.textContent ?? "";
+    held.after(script);
+  }
+};
+
+/**
+ * Start the consent runtime on this page load, then the configured adapter's
+ * browser module (`startClient`, from the generated `blume:consent-client`;
+ * none for a hosted manager, whose `<head>` tags report its answers).
+ */
+export const startConsent = (
+  startClient: (consent: BlumeConsent) => void = () => {
+    // No browser module: a hosted manager's <head> tags report its answers.
+  }
+): void => {
+  // SAFETY: ConsentWindow only adds the optional state the init script
+  // creates; it's checked before use.
+  const consent = (window as ConsentWindow).blumeConsent;
+  if (!consent) {
+    return;
+  }
+  const ran = new Set<string>();
+  const run = () => {
+    if (consent.analytics === true) {
+      runHeldScripts(ran);
+    }
+  };
+  window.addEventListener("blume:consent", () => {
+    if (consent.analytics === true) {
+      runHeldScripts(ran);
+    } else if (ran.size > 0) {
+      location.reload();
+    }
+  });
+  document.addEventListener("click", (event) => {
+    if (event.target instanceof Element && event.target.closest(OPEN)) {
+      consent.open?.();
+    }
+  });
+  startClient(consent);
+  run();
+  document.addEventListener("astro:after-swap", run);
+};

package/src/consent/clients.ts

@@ -0,0 +1,19 @@
+/**
+ * The browser module each consent adapter brings, by `kind`. The generated
+ * `blume:consent-client` (see `consentClientTemplate`) imports the configured
+ * adapter's, so a site bundles only its own adapter's browser code, the way
+ * `blume:search-client` does for search.
+ *
+ * Hosted managers (`osano()`, `ethyca()`) have none: their `<head>` tags load
+ * them and report their answers (see `head.ts`). A manager that ships as an
+ * npm package adds its module under `components/layout/consent/` instead: a
+ * `start` (`ConsentClientStart` in its `types.ts`) that reports the reader's answer with
+ * `consent.set({ analytics })` and sets `consent.open`, with the packages it
+ * imports listed in its factory's `runtimeDeps`, so only the sites that pick
+ * it install them.
+ */
+
+/** Each adapter's browser module, as the generated project imports it. */
+export const CONSENT_CLIENT_MODULES = new Map([
+  ["native", "blume/components/layout/consent/native.ts"],
+]);

package/src/consent/ethyca.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+
+import type { HeadScript } from "../analytics/head.ts";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+
+/** Options for {@link ethyca}. */
+export interface EthycaOptions {
+  /**
+   * The key of the privacy notice that covers analytics, as you named it in
+   * Fides. Defaults to `analytics`.
+   */
+  notice?: string;
+  /** Your Fides privacy center's origin, which serves `fides.js`. */
+  privacyCenter: string;
+  /** The Fides property to load, when you have more than one. */
+  propertyId?: string;
+}
+
+export const ethycaOptionsSchema = z.strictObject({
+  notice: z.string().min(1).optional(),
+  privacyCenter: z.url({ protocol: /^https?$/u }),
+  propertyId: z.string().min(1).optional(),
+});
+
+export type EthycaAdapter = AdapterDescriptor<"ethyca", EthycaOptions>;
+
+export const ethycaAdapterSchema = adapterDescriptorSchema(
+  "ethyca",
+  ethycaOptionsSchema
+);
+
+/**
+ * Ethyca's Fides consent manager, loaded from your privacy center. Fides
+ * shows its own banner and modal, set up in Fides, and Blume runs the
+ * analytics once the reader's analytics notice is on. Nothing here is
+ * secret.
+ */
+export const ethyca = (options: EthycaOptions): EthycaAdapter => ({
+  kind: "ethyca",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});
+
+/**
+ * Reports the analytics notice to `window.blumeConsent` when Fides is ready
+ * and whenever the reader saves a change, and reopens Fides' modal from the
+ * Cookie settings link. The notice key rides in as `data-notice`. It counts
+ * as allowed when on (`true`), opted in, or a notice that only asks for
+ * acknowledgment.
+ */
+export const ETHYCA_BRIDGE = `(()=>{const c=window.blumeConsent;if(!c){return;}const k=document.currentScript?.dataset.notice??"analytics";const sync=(e)=>{const v=(e?.detail?.consent??window.Fides?.consent??{})[k];c.set({analytics:v===true||v==="opt_in"||v==="acknowledge"});};c.open=()=>window.Fides?.showModal();addEventListener("FidesReady",sync);addEventListener("FidesUpdated",sync);if(window.Fides?.initialized){sync();}})();`;
+
+/** Fides' script from the privacy center, then the bridge. */
+export const ethycaHead = (options: EthycaOptions): HeadScript[] => {
+  const src = new URL(
+    "fides.js",
+    `${options.privacyCenter.replace(/\/+$/u, "")}/`
+  );
+  if (options.propertyId) {
+    src.searchParams.set("property_id", options.propertyId);
+  }
+  return [
+    { attributes: { src: src.href }, content: null },
+    {
+      attributes: { "data-notice": options.notice ?? "analytics" },
+      content: ETHYCA_BRIDGE,
+    },
+  ];
+};

package/src/consent/head.ts

@@ -0,0 +1,24 @@
+import type { HeadScript } from "../analytics/head.ts";
+import { ethycaHead } from "./ethyca.ts";
+import { osanoHead } from "./osano.ts";
+import type { ConsentAdapter } from "./schema.ts";
+
+/**
+ * The tags one consent adapter emits into `<head>`, after the init script and
+ * ahead of the held analytics: a hosted manager's loader and the bridge that
+ * reports its answers to `window.blumeConsent`. `native()` has none; its
+ * banner is markup (`ConsentBanner.astro`) and its logic is the runtime's.
+ */
+export const consentHead = (adapter: ConsentAdapter): HeadScript[] => {
+  switch (adapter.kind) {
+    case "ethyca": {
+      return ethycaHead(adapter.options);
+    }
+    case "osano": {
+      return osanoHead(adapter.options);
+    }
+    default: {
+      return [];
+    }
+  }
+};

package/src/consent/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Consent adapters for `blume.config.ts`:
+ *
+ * ```ts
+ * import { defineConfig } from "blume";
+ * import { googleAnalytics } from "blume/analytics";
+ * import { native } from "blume/consent";
+ *
+ * export default defineConfig({
+ *   analytics: [googleAnalytics({ id: "G-XXXXXXXXXX" })],
+ *   consent: native({ policy: "/privacy" }),
+ * });
+ * ```
+ *
+ * With `consent` set, analytics waits for the reader: every adapter's tags are
+ * held until the consent adapter reports that analytics is allowed. Each
+ * factory returns a plain descriptor (see `core/adapter.ts`).
+ *
+ * Adding a consent manager: a factory and option schema in its own module,
+ * and a member of `consentAdapterSchema` (`schema.ts`). Then connect it to
+ * `window.blumeConsent` (see `init.ts` for the contract): report the reader's
+ * choice with `set({ analytics })` on load and on every change, and set
+ * `open` to reopen the manager's preferences. A hosted manager does that
+ * with tags in `consentHead` (`head.ts`): its loader, then a constant bridge
+ * script (`osano.ts` is an example). A manager that ships as an npm package
+ * does it in a browser module instead, registered in `clients.ts`, with its
+ * packages in the factory's `runtimeDeps` (`native()`'s banner is the
+ * example).
+ */
+export type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+export { ethyca } from "./ethyca.ts";
+export type { EthycaAdapter, EthycaOptions } from "./ethyca.ts";
+export { native } from "./native.ts";
+export type { NativeAdapter, NativeOptions } from "./native.ts";
+export { osano } from "./osano.ts";
+export type { OsanoAdapter, OsanoOptions } from "./osano.ts";
+export type { ConsentAdapter } from "./schema.ts";

package/src/consent/init.ts

@@ -0,0 +1,29 @@
+/**
+ * The consent layer's first script, inlined at the top of `<head>` on every
+ * page when `consent` is configured, ahead of any adapter's script and the
+ * held analytics. It creates `window.blumeConsent`, the one contract every
+ * consent adapter talks to:
+ *
+ * - `analytics`: `null` until an adapter reports, then the reader's choice.
+ * - `set({ analytics })`: what an adapter calls with the reader's choice, on
+ *   load for a returning reader and again whenever it changes. A change fires
+ *   a `blume:consent` event on `window` (`detail: { analytics }`), which the
+ *   runtime (`client.ts`) answers by running the held analytics, and which a
+ *   site can listen to for its own scripts.
+ * - `open()`: set by an adapter to reopen its preferences; the footer's
+ *   Cookie settings link calls it.
+ * - `kind`: the configured adapter (`native`, `osano`, …), from the tag's
+ *   `data-kind`.
+ *
+ * It also sets `window.webAnalyticsBeforeSend`, which Vercel Web Analytics
+ * reads when it starts, so `vercel()` sends nothing until analytics is
+ * allowed; its script is a component rather than a tag, so it can't be held
+ * like the others.
+ *
+ * A constant, like the layouts' other inline scripts (see
+ * `components/layout/head-scripts.ts`): the kind rides in as an attribute,
+ * never as interpolated source. It runs once per real page load; the client
+ * router never runs an inline script twice, and the state it creates lives
+ * on across navigations.
+ */
+export const CONSENT_INIT_SCRIPT = `(()=>{if(window.blumeConsent){return;}const c={analytics:null,kind:document.currentScript?.dataset.kind??"",set(s){const a=s?.analytics===true;if(c.analytics===a){return;}c.analytics=a;dispatchEvent(new CustomEvent("blume:consent",{detail:{analytics:a}}));}};window.blumeConsent=c;window.webAnalyticsBeforeSend=(e)=>c.analytics===true?e:null;})();`;

package/src/consent/native.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+
+/** Options for {@link native}. */
+export interface NativeOptions {
+  /** Where the banner's privacy policy link goes: a page route or a URL. */
+  policy?: string;
+}
+
+export const nativeOptionsSchema = z.strictObject({
+  policy: z.string().min(1).optional(),
+});
+
+export type NativeAdapter = AdapterDescriptor<"native", NativeOptions>;
+
+export const nativeAdapterSchema = adapterDescriptorSchema(
+  "native",
+  nativeOptionsSchema
+);
+
+/**
+ * Blume's own consent banner: a card at the foot of the page asking to use
+ * analytics cookies, with Accept and Decline side by side and an optional
+ * link to your privacy policy. The answer stays in the reader's browser, and
+ * the footer's Cookie settings link brings the banner back to change it. Its
+ * text comes from the `consent` UI strings, translated in every built-in
+ * language.
+ */
+export const native = (options: NativeOptions = {}): NativeAdapter => ({
+  kind: "native",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});

package/src/consent/osano.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+
+import type { HeadScript } from "../analytics/head.ts";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+
+/** Options for {@link osano}. */
+export interface OsanoOptions {
+  /** The configuration ID from the script tag Osano gives you. */
+  configId: string;
+  /** The customer ID from the script tag Osano gives you. */
+  customerId: string;
+}
+
+export const osanoOptionsSchema = z.strictObject({
+  configId: z.string().min(1),
+  customerId: z.string().min(1),
+});
+
+export type OsanoAdapter = AdapterDescriptor<"osano", OsanoOptions>;
+
+export const osanoAdapterSchema = adapterDescriptorSchema(
+  "osano",
+  osanoOptionsSchema
+);
+
+/**
+ * Osano Cookie Consent. Osano shows its own banner and drawer, set up in the
+ * Osano dashboard, and Blume runs the analytics once Osano reports the
+ * reader's `ANALYTICS` consent. Both IDs come from the script tag Osano
+ * gives you, and neither is secret.
+ */
+export const osano = (options: OsanoOptions): OsanoAdapter => ({
+  kind: "osano",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});
+
+/**
+ * Reports Osano's analytics consent to `window.blumeConsent` now (`Osano.cm`
+ * is ready as soon as its script ran) and on every Osano consent event, and
+ * reopens Osano's drawer from the Cookie settings link.
+ */
+export const OSANO_BRIDGE = `(()=>{const o=window.Osano?.cm;const c=window.blumeConsent;if(!o||!c){return;}const sync=()=>c.set({analytics:o.analytics===true});c.open=()=>o.showDrawer();for(const e of ["osano-cm-initialized","osano-cm-consent-saved","osano-cm-consent-changed"]){o.addEventListener(e,sync);}sync();})();`;
+
+/**
+ * Osano's loader, synchronous as its install guide requires, then the
+ * bridge. The IDs are path segments, so each is encoded.
+ */
+export const osanoHead = (options: OsanoOptions): HeadScript[] => [
+  {
+    attributes: {
+      src: `https://cmp.osano.com/${encodeURIComponent(options.customerId)}/${encodeURIComponent(options.configId)}/osano.js`,
+    },
+    content: null,
+  },
+  { attributes: {}, content: OSANO_BRIDGE },
+];

package/src/consent/schema.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+
+import { ethycaAdapterSchema } from "./ethyca.ts";
+import { nativeAdapterSchema } from "./native.ts";
+import { osanoAdapterSchema } from "./osano.ts";
+
+const ADAPTER_HINT =
+  'consent takes one adapter — e.g. `consent: native()` or `consent: osano({ customerId, configId })`, imported from "blume/consent".';
+
+/**
+ * The configured consent adapter, as its factory returned it. Anything that
+ * isn't one (`true`, a list, an unknown `kind`) fails with the adapter hint;
+ * an adapter's own option errors keep their messages.
+ */
+export const consentAdapterSchema = z.discriminatedUnion(
+  "kind",
+  [ethycaAdapterSchema, nativeAdapterSchema, osanoAdapterSchema],
+  { error: ADAPTER_HINT }
+);
+
+export type ConsentAdapter = z.output<typeof consentAdapterSchema>;
+
+/**
+ * `blume.config.consent`: the adapter that asks readers before analytics
+ * runs. Unset (`null` once resolved) means no consent layer, and analytics
+ * runs as it loads.
+ */
+export const consentConfigSchema = consentAdapterSchema
+  .optional()
+  .transform((adapter) => adapter ?? null);

package/src/core/builtin-tags.ts

@@ -31,7 +31,11 @@ export const BUILTIN_MDX_TAGS = new Set<string>([
   "Math",
   "Operation",
   "Panel",
+  "ParamField",
   "Prompt",
+  "RequestExample",
+  "ResponseExample",
+  "ResponseField",
   "Step",
   "Steps",
   "Tab",
@@ -40,6 +44,7 @@ export const BUILTIN_MDX_TAGS = new Set<string>([
   "Tooltip",
   "Tree",
   "TypeTable",
+  "View",
   "Visibility",
   "YouTube",
 ]);

package/src/core/client-address.ts

@@ -0,0 +1,19 @@
+/** The slice of Astro's `APIContext` a server route reads the reader from. */
+export interface ClientContext {
+  /** The reader's address; Astro's getter throws where the host can't tell. */
+  readonly clientAddress?: string;
+  readonly request: Request;
+}
+
+/**
+ * The reader's IP address as the host reports it (Astro resolves the
+ * platform's trusted header, or the socket on a Node server), or `undefined`
+ * where the host can't tell.
+ */
+export const clientAddressOf = (context: ClientContext): string | undefined => {
+  try {
+    return context.clientAddress || undefined;
+  } catch {
+    return undefined;
+  }
+};