@escape-game-over/atlas 0.1.24 → 0.1.26

package/src/analytics/tags.ts

@@ -1,62 +1,16 @@
+import { link, type MetaTag } from "../meta/tag.ts";
+
 /**
- * What an analytics vendor comes to, as data.
+ * An origin to open a connection to before anything asks it for bytes: every
+ * vendor here is served from a host that is not the site's.
  *
- * A list rather than a set, because **order is part of the answer**. Google's
- * consent defaults have to be queued before any tag that reads them, and a tag
- * that fires first does not error — it simply applies the permissive implicit
- * default and sets cookies nobody agreed to. Returning a sequence makes that
- * ordering something lib decides once, rather than something a layout could
- * shuffle.
+ * **No `crossorigin`, and that is load-bearing.** A preconnect is reused only by
+ * a request whose CORS mode matches, and every script here is a classic
+ * `<script src>`. One carrying `crossorigin` would open a second connection
+ * that nothing uses.
  */
-export type AnalyticsTag =
-    | {
-          readonly kind: "external";
-          readonly src: string;
-          readonly attributes: Readonly<Record<string, string>>;
-      }
-    | {
-          readonly kind: "inline";
-          readonly content: string;
-      }
-    /**
-     * A hidden iframe inside `<noscript>` — Tag Manager's fallback, and so far
-     * only that.
-     *
-     * Structured rather than a string of HTML, for the reason `externalScript`
-     * is: a field holding markup is a passthrough, and lib does not have those.
-     * A `src` is all this shape can carry, so it is all anyone can put in it.
-     */
-    | {
-          readonly kind: "noscriptFrame";
-          readonly src: string;
-      }
-    /**
-     * An origin to open a connection to before anything asks it for bytes.
-     *
-     * Every vendor here is served from a host that is not the site's, so the
-     * first tag to load pays a DNS lookup, a TCP handshake and a TLS
-     * negotiation before a single byte of script arrives. Tag Manager is the
-     * worst case: its loader is written by the inline block above, so the
-     * origin appears nowhere a preload scanner can read it and the connection
-     * cannot begin until that script has run.
-     *
-     * An origin rather than a URL, and `preconnect` rather than `preload`,
-     * because the handshake is the part worth moving and the fetch is not.
-     * Preloading a tag would raise a third-party analytics script to the
-     * priority of the things the page is drawn from — it would arrive sooner
-     * by making the image beside it arrive later.
-     *
-     * **No `crossorigin`, and that is load-bearing.** A preconnect is reused
-     * only by a request whose CORS mode matches it, and every script here is
-     * fetched as a classic `<script src>`, which is not a CORS request. One
-     * carrying `crossorigin` would open a second connection that nothing uses,
-     * warm nothing, and look entirely correct in the markup. Fonts are the
-     * opposite case and do need it, which is why this is worth stating.
-     */
-    | {
-          readonly kind: "preconnect";
-          readonly origin: string;
-      };
+export const preconnect = (origin: string): MetaTag =>
+    link({ rel: "preconnect", href: origin });
 
 /**
  * Where a tag goes. Two channels, because two tags genuinely differ.
@@ -67,8 +21,9 @@ export type AnalyticsTag =
  * cannot put one where the other goes.
  */
 export interface AnalyticsTags {
-    readonly head: readonly AnalyticsTag[];
-    readonly body: readonly AnalyticsTag[];
+    /** In order: Google's consent defaults must be queued before any tag reads them. */
+    readonly head: readonly MetaTag[];
+    readonly body: readonly MetaTag[];
 }
 
 /**

package/src/analytics/umami.ts

@@ -1,6 +1,7 @@
+import type { MetaTag } from "../meta/tag.ts";
 import { type HttpsUrl, joinUrl, type UrlPath } from "../url.ts";
 import { warn } from "../warn.ts";
-import type { AnalyticsTag } from "./tags.ts";
+import { preconnect } from "./tags.ts";
 
 /**
  * Umami's tracker — the script that counts pageviews.
@@ -225,7 +226,7 @@ export function checkUmamiDomains(
 export function umamiScripts(
     umami: UmamiSettings | undefined,
     tag?: string
-): readonly AnalyticsTag[] {
+): readonly MetaTag[] {
     if (umami === undefined) return [];
 
     // Through `joinUrl`, not concatenation. `HttpsUrl` cannot express "without
@@ -251,12 +252,11 @@ export function umamiScripts(
         // Before the script that needs it. A `src.` subdomain reads as
         // first-party and is not one to the network stack: it is a separate
         // origin, and the tracker pays its full handshake before it can start.
-        // See `AnalyticsTag` for why this is a preconnect and not a preload.
-        { kind: "preconnect", origin: umami.host },
+        preconnect(umami.host),
         {
-            kind: "external",
+            kind: "externalScript",
             src: at(umami.tracker?.path ?? "/script.js"),
-            attributes: stated({
+            attrs: stated({
                 ...common,
                 // The one default lib overrides — see `UmamiTracker`. The
                 // others are left to Umami: `auto-track` and `auto-pageview`
@@ -281,9 +281,9 @@ export function umamiScripts(
             ? []
             : [
                   {
-                      kind: "external" as const,
+                      kind: "externalScript" as const,
                       src: at(umami.replay.path ?? "/recorder.js"),
-                      attributes: stated(common),
+                      attrs: stated(common),
                   },
               ]),
     ];

package/src/astro/AtlasElement.astro

@@ -0,0 +1,26 @@
+---
+/**
+ * Renders a custom element with the root attribute: what a stylesheet gives
+ * every root its display by, and what `element` checks for in dev.
+ *
+ * ```astro
+ * <AtlasElement of={trailer} data-video={video} class="…">…</AtlasElement>
+ * ```
+ */
+import type { HTMLAttributes } from "astro/types";
+import { type ElementTag, ROOT_ATTRIBUTE } from "./element.ts";
+
+interface Props extends HTMLAttributes<"div"> {
+    readonly of: ElementTag;
+}
+
+const { of, ...rest } = Astro.props;
+const Tag = of.tag;
+---
+
+<Tag
+    {...rest}
+    {...{ [ROOT_ATTRIBUTE]: "" }}
+>
+    <slot />
+</Tag>

package/src/astro/ConsentBanner.astro

@@ -0,0 +1,25 @@
+---
+/**
+ * The consent banner's behaviour; the site supplies its markup and copy as the
+ * children, with `consent.accept` and `consent.decline` on its buttons.
+ *
+ * Renders nothing — and ships no script — when this site's analytics need no
+ * permission. Otherwise the banner starts hidden and shows only to a visitor
+ * with no answer on record, or when `consent.reopen` is pressed.
+ */
+import type { HTMLAttributes } from "astro/types";
+import { type AnalyticsSettings, consentRequired } from "../analytics/index.ts";
+import ConsentElement from "./ConsentElement.astro";
+
+type Props = HTMLAttributes<"div"> & {
+    readonly analytics: AnalyticsSettings | undefined;
+};
+
+const { analytics, ...attrs } = Astro.props;
+---
+
+{consentRequired(analytics) && (
+    <ConsentElement {...attrs}>
+        <slot />
+    </ConsentElement>
+)}

package/src/astro/ConsentElement.astro

@@ -0,0 +1,67 @@
+---
+/** Internal to `ConsentBanner.astro`, so its script ships only where it renders. */
+import type { HTMLAttributes } from "astro/types";
+import AtlasElement from "./AtlasElement.astro";
+import { consentBanner } from "./consent.ts";
+
+type Props = HTMLAttributes<"div">;
+---
+
+<AtlasElement
+    of={consentBanner}
+    {...Astro.props}
+    hidden
+    role="dialog"
+    aria-modal="false"
+>
+    <slot />
+</AtlasElement>
+
+<script>
+import {
+    applyConsent,
+    CONSENT_ANSWER,
+    CONSENT_REOPEN,
+    consentApplies,
+    consentStore,
+} from "./consent.ts";
+import { element } from "./element.ts";
+import { refs } from "./ref.ts";
+
+element("atlas-consent", ({ host, signal }) => {
+    // The head script left no consent hook: nothing here sets a cookie.
+    if (!consentApplies()) return;
+
+    const store = consentStore();
+    const show = (): void => {
+        host.hidden = false;
+    };
+
+    for (const button of refs(host, `[${CONSENT_ANSWER}]`)) {
+        const choice = button.getAttribute(CONSENT_ANSWER);
+        if (choice !== "granted" && choice !== "denied") {
+            throw new Error(`${CONSENT_ANSWER} is "${choice}"`);
+        }
+        button.addEventListener(
+            "click",
+            () => {
+                store.record(choice);
+                host.hidden = true;
+            },
+            { signal }
+        );
+    }
+
+    // Outside the banner — withdrawing must be as easy as granting.
+    for (const button of refs(document, `[${CONSENT_REOPEN}]`)) {
+        button.hidden = false;
+        button.addEventListener("click", show, { signal });
+    }
+
+    // Applied, not re-recorded: recording stamps today's date, and an answer
+    // renewed on every page view never expires.
+    const stored = store.read();
+    if (stored === undefined) show();
+    else applyConsent(stored.choice);
+});
+</script>

package/src/astro/Document.astro

@@ -0,0 +1,44 @@
+---
+/**
+ * The page document: `<html lang dir>`, every head tag `metaFor` produced, and
+ * the body tags first thing in `<body>`, so no layout can forget one.
+ * `head-start` comes before every tag Atlas writes — a consent manager that must
+ * load ahead of the analytics goes there; `head` comes after.
+ *
+ * ```astro
+ * <Document meta={meta} html={{ class: "scroll-smooth" }} body={{ class: "…" }}>
+ *     <Fragment slot="head"><link rel="preload" … /></Fragment>
+ *     …page…
+ * </Document>
+ * ```
+ */
+import type { HTMLAttributes } from "astro/types";
+import type { PageMeta } from "../site/index.ts";
+import MetaTags from "./MetaTags.astro";
+
+interface Props {
+    readonly meta: PageMeta;
+    /** `lang` and `dir` are the page's locale's, from `meta`. */
+    readonly html?: Omit<HTMLAttributes<"html">, "lang" | "dir">;
+    readonly body?: HTMLAttributes<"body">;
+}
+
+const { meta, html, body } = Astro.props;
+---
+
+<!doctype html>
+<html
+    {...html}
+    lang={meta.lang}
+    dir={meta.dir}
+>
+    <head>
+        <slot name="head-start" />
+        <MetaTags tags={meta.tags} />
+        <slot name="head" />
+    </head>
+    <body {...body}>
+        <MetaTags tags={meta.bodyTags} />
+        <slot />
+    </body>
+</html>

package/src/astro/Image.astro

@@ -0,0 +1,101 @@
+---
+/**
+ * An imported image, as AVIF with a WebP fallback.
+ *
+ * - **Fixed size** — a logo, a flag: give the `width` or `height` it is drawn
+ *   at. Served at 1× and 2×.
+ * - **Follows the layout** — a photo, a card, a background: give `sizes`. Files
+ *   are made at standard device widths up to the source's own. A lazy image
+ *   gets `auto` in front, so browsers that can measure the real width do.
+ *
+ * `zoom` opens the image larger in a dialog.
+ */
+import { Picture } from "astro:assets";
+import type { ComponentProps } from "astro/types";
+import Zoom from "./Zoom.astro";
+
+interface Base {
+    readonly src: ImageMetadata;
+    /** Required; `""` only for decorative artwork. */
+    readonly alt: string;
+    /** Above the fold: loads eagerly, at high priority. */
+    readonly priority?: boolean;
+    readonly class?: string;
+    readonly zoom?: { readonly closeLabel: string; readonly class?: string };
+}
+
+type Props = Base &
+    (
+        | {
+              readonly width: number;
+              readonly height?: never;
+              readonly sizes?: never;
+          }
+        | {
+              readonly height: number;
+              readonly width?: never;
+              readonly sizes?: never;
+          }
+        | {
+              readonly sizes: string;
+              readonly width?: never;
+              readonly height?: never;
+          }
+    );
+
+/** Common device widths, as Astro uses for its own responsive images. */
+const DEVICE_WIDTHS = [640, 750, 828, 1080, 1280, 1668, 1920, 2048, 2560, 3840];
+
+const given = Astro.props;
+const { src, alt, priority = false, zoom } = given;
+
+const shape =
+    given.sizes !== undefined
+        ? (() => {
+              // Up to the source, and the source itself as the widest.
+              const widths = [
+                  ...DEVICE_WIDTHS.filter((w) => w < src.width),
+                  src.width,
+              ];
+              return {
+                  width: src.width,
+                  height: src.height,
+                  widths,
+                  sizes: priority ? given.sizes : `auto, ${given.sizes}`,
+              };
+          })()
+        : (() => {
+              const aspect = src.height / src.width;
+              const width =
+                  given.width ?? Math.round((given.height ?? 0) / aspect);
+              return {
+                  width,
+                  height: Math.round(width * aspect),
+                  // Nothing wider than the source: Astro would only upscale it.
+                  densities: width * 2 <= src.width ? [1, 2] : [1],
+              };
+          })();
+
+const picture: ComponentProps<typeof Picture> = {
+    src,
+    alt,
+    ...shape,
+    formats: ["avif", "webp"],
+    loading: priority ? "eager" : "lazy",
+    decoding: priority ? "sync" : "async",
+    fetchpriority: priority ? "high" : "auto",
+    class: given.class,
+};
+---
+
+{zoom === undefined ? (
+    <Picture {...picture} />
+) : (
+    <Zoom
+        src={src}
+        alt={alt}
+        closeLabel={zoom.closeLabel}
+        class={zoom.class}>
+        <Picture {...picture} />
+    </Zoom>
+)}

package/src/astro/MetaTags.astro

@@ -1,31 +1,8 @@
 ---
 /**
- * Renders what `metaFor` described, one element per `MetaTag`.
- *
- * The other half of `asMetaTag` in `lib/meta/tag.ts`: that one converts *into*
- * the union, this one out of it. Both enumerate the same kinds, and keeping
- * them in different repositories is what let them drift — the converter had an
- * exhaustiveness guard from the day it was written and this file did not, so a
- * kind added to `MetaTag` would have rendered here as a bare `<meta>`.
- *
- * In `lib/astro/` rather than a project's `src/`, unlike every other component
- * in this template, because it carries no design and no copy: no classes, no
- * translated strings, nothing from `@config`. It is a `kind` → element switch,
- * and the four things it knows are each a decision worth making once —
- * `set:html` for pre-escaped JSON, `is:inline` so the bundler leaves a
- * third-party URL alone, `defer` so measuring a page does not cost what it
- * measures, and the zero-sized frame Tag Manager wants. Four chances for a
- * repository to get one of them wrong.
- *
- * ```astro
- * import MetaTags from "@escape-game-over/atlas/astro/meta-tags";
- *
- * <head><MetaTags tags={meta.tags} /></head>
- * <body><MetaTags tags={meta.bodyTags} /> …
- * ```
- *
- * Both lists, and in those places: `bodyTags` is usually empty and holds the
- * one tag the head would ignore.
+ * One element per `MetaTag`. Internal to `Document.astro`: `set:html` for
+ * pre-escaped JSON, `is:inline` so the bundler leaves a third-party URL alone,
+ * `defer` so measuring a page does not cost what it measures.
  */
 // Relative, like every other file in the package: the bare specifier is the
 // consumer's name for this package, and depending on it here would make the
@@ -48,27 +25,40 @@ const { tags } = Astro.props;
     // again as HTML would turn each quote into an entity and leave a block no
     // parser reads.
     if (tag.kind === "script") {
-      return <script type={tag.type} is:inline set:html={tag.content} />;
+        return (
+            <script
+                type={tag.type}
+                is:inline
+                set:html={tag.content}
+            />
+        );
     }
     // `is:inline` so the bundler leaves a third-party URL alone, and `defer`
     // because a script that blocks the parser costs the thing it measures.
     if (tag.kind === "externalScript") {
-      return <script is:inline defer src={tag.src} {...tag.attrs} />;
+        return (
+            <script
+                is:inline
+                defer
+                src={tag.src}
+                {...tag.attrs}
+            />
+        );
     }
     // Tag Manager's fallback, and only ever in the body list. Hidden the way
     // Google's own snippet hides it — a zero-sized iframe nothing can see.
     if (tag.kind === "noscriptFrame") {
-      return (
-        <noscript>
-          <iframe
-            src={tag.src}
-            title="Google Tag Manager"
-            height="0"
-            width="0"
-            style="display:none;visibility:hidden"
-          />
-        </noscript>
-      );
+        return (
+            <noscript>
+                <iframe
+                    src={tag.src}
+                    title='Google Tag Manager'
+                    height='0'
+                    width='0'
+                    style='display:none;visibility:hidden'
+                />
+            </noscript>
+        );
     }
     if (tag.kind === "meta") return <meta {...tag.attrs} />;
     // Named rather than left to a trailing `return`, which used to catch
@@ -82,4 +72,4 @@ const { tags } = Astro.props;
     // copied into every project.
     const unhandled: never = tag;
     throw new Error(`Unhandled meta tag: ${JSON.stringify(unhandled)}`);
-  })}
+})}

package/src/astro/RichText.astro

@@ -0,0 +1,88 @@
+---
+/**
+ * Renders what `site.rich()` returns. The site supplies the look: a class per
+ * `[v:name]` variant and one for links; everything else is decided here. Only
+ * the runs — the caller writes the element they sit in.
+ *
+ * ```astro
+ * <p class="…">
+ *     <RichText spans={rich("about.intro", { venue: "contact" })} variants={{ accent: "…" }} />
+ * </p>
+ * ```
+ */
+import type { RichText } from "../content/index.ts";
+import { warn } from "../warn.ts";
+
+interface Props {
+    readonly spans: RichText;
+    /** `[v:name]` → classes. */
+    readonly variants?: Readonly<Record<string, string>>;
+    /** `[v:name]` → attributes, so a script can find that run. */
+    readonly attrs?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    /** Classes on every link: `[a:]`, `[mail]` and `[tel]`. */
+    readonly link?: string;
+}
+
+const { spans, variants = {}, attrs = {}, link }: Props = Astro.props;
+
+// The words still render: losing the sentence is worse than losing its style.
+// A run with attributes and no class is a script's hook, not a missing style.
+const variantClass = (variant: string): string | undefined => {
+    if (!Object.hasOwn(variants, variant) && !Object.hasOwn(attrs, variant)) {
+        warn(
+            Astro.url.pathname,
+            `[v:${variant}] has no class in RichText's variants and no attrs.`
+        );
+    }
+    return Object.hasOwn(variants, variant) ? variants[variant] : undefined;
+};
+
+const variantAttrs = (variant: string) =>
+    Object.hasOwn(attrs, variant) ? attrs[variant] : undefined;
+---
+
+{spans.map((span) => {
+    switch (span.kind) {
+        case "text":
+            return span.text;
+        case "bold":
+            return <strong>{span.text}</strong>;
+        case "variant":
+            return (
+                <span
+                    {...variantAttrs(span.variant)}
+                    class={variantClass(span.variant)}>
+                    {span.text}
+                </span>
+            );
+        case "break":
+            return <br />;
+        case "link":
+            return span.to === "external" ? (
+                <a
+                    href={span.href}
+                    class={link}
+                    target='_blank'
+                    rel='noopener noreferrer'>
+                    {span.text}
+                </a>
+            ) : (
+                <a
+                    href={span.href}
+                    class={link}>
+                    {span.text}
+                </a>
+            );
+        case "mail":
+        case "tel":
+            return (
+                <a
+                    href={span.href}
+                    class={link}>
+                    {span.text}
+                </a>
+            );
+        default:
+            return span satisfies never;
+    }
+})}

package/src/astro/Zoom.astro

@@ -0,0 +1,61 @@
+---
+/**
+ * Internal to `Image.astro`. No script: `command="show-modal"` opens the dialog
+ * and `closedby="any"` lets a click outside close it. The large image is lazy
+ * inside a closed dialog, so it is fetched on open.
+ */
+
+import { getImage } from "astro:assets";
+import type { ImageMetadata } from "astro";
+
+interface Props {
+    readonly src: ImageMetadata;
+    readonly alt: string;
+    readonly closeLabel: string;
+    /** On the `<dialog>`. */
+    readonly class?: string;
+}
+
+const { src, alt, closeLabel, class: dialogClass } = Astro.props;
+const large = await getImage({
+    src,
+    width: Math.min(src.width, 2048),
+    format: "webp",
+});
+// The file's URL carries Astro's content hash, so the id is the same every
+// build. The same image zoomed twice on a page opening one dialog is harmless.
+const id = `atlas-zoom${large.src.replace(/[^\w-]/g, "-")}`;
+---
+
+<button
+    type="button"
+    commandfor={id}
+    command="show-modal"
+    style="padding:0;border:0;background:none;cursor:zoom-in"
+>
+    <slot />
+</button>
+<dialog
+    id={id}
+    closedby="any"
+    class={dialogClass}
+    aria-label={alt}
+>
+    <button
+        type="button"
+        commandfor={id}
+        command="close"
+        aria-label={closeLabel}
+    >
+        ×
+    </button>
+    <img
+        src={large.src}
+        width={large.attributes.width}
+        height={large.attributes.height}
+        alt={alt}
+        loading="lazy"
+        decoding="async"
+        style="display:block;max-width:100%;max-height:85vh;height:auto"
+    >
+</dialog>

package/src/astro/client.ts

@@ -5,19 +5,28 @@
  * import { filters, searchBox } from "@escape-game-over/atlas/client";
  * ```
  *
- * **For the browser.** Everything here exists to touch a live document, and is
- * meant for a `<script src>`, not for frontmatter or `astro.config.ts`. A
- * component's contract is the one thing both halves need, and it stays on
- * `astro/markup`, which touches nothing.
+ * The only import path for browser code. Nothing here touches the DOM at
+ * import, so a component's contract can be imported from frontmatter too.
  */
 
 export * from "./background-video.ts";
 export * from "./carousel.ts";
-export * from "./consent.ts";
-export * from "./dev-log.ts";
-export * from "./dom.ts";
-export * from "./element.ts";
+export {
+    applyConsent,
+    type ConsentChoice,
+    type ConsentRecord,
+    type ConsentStoreOptions,
+    consent,
+    consentApplies,
+    consentStore,
+} from "./consent.ts";
+export {
+    type Connect,
+    type ElementContext,
+    type ElementTag,
+    element,
+} from "./element.ts";
 export * from "./filters.ts";
 export * from "./filters-view.ts";
-export * from "./markup.ts";
+export { data, ref, refs } from "./ref.ts";
 export * from "./youtube.ts";