@escape-game-over/atlas 0.1.24 → 0.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.24",
+    "version": "0.1.25",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -15,18 +15,11 @@
         ".": "./src/index.ts",
         "./astro": "./src/astro/index.ts",
         "./astro/images": "./src/astro/images.ts",
-        "./astro/background-video": "./src/astro/background-video.ts",
-        "./astro/carousel": "./src/astro/carousel.ts",
         "./client": "./src/astro/client.ts",
-        "./astro/consent": "./src/astro/consent.ts",
-        "./astro/dev-log": "./src/astro/dev-log.ts",
-        "./astro/dom": "./src/astro/dom.ts",
-        "./astro/element": "./src/astro/element.ts",
-        "./astro/filters": "./src/astro/filters.ts",
-        "./astro/filters-view": "./src/astro/filters-view.ts",
-        "./astro/markup": "./src/astro/markup.ts",
-        "./astro/meta-tags": "./src/astro/MetaTags.astro",
-        "./astro/youtube": "./src/astro/youtube.ts"
+        "./astro/consent-banner": "./src/astro/ConsentBanner.astro",
+        "./astro/document": "./src/astro/Document.astro",
+        "./astro/image": "./src/astro/Image.astro",
+        "./astro/rich-text": "./src/astro/RichText.astro"
     },
     "bin": {
         "atlas": "bin/use-project.mjs"

package/src/analytics/google.ts

@@ -1,5 +1,5 @@
 import { warn } from "../warn.ts";
-import { type AnalyticsTags, literal } from "./tags.ts";
+import { type AnalyticsTags, literal, preconnect } from "./tags.ts";
 
 /**
  * Google's tags — Analytics and Tag Manager — and the consent state they read.
@@ -366,16 +366,16 @@ export function googleScripts(
             // Ahead of the inline block, which is the only position that buys
             // anything: for a container the loader's URL is written *by* that
             // block, so this is the only mention of the origin the browser can
-            // act on before the script has run. See `AnalyticsTag`.
-            { kind: "preconnect", origin: TAG_ORIGIN },
-            { kind: "inline", content: inline },
+            // act on before the script has run.
+            preconnect(TAG_ORIGIN),
+            { kind: "script", content: inline },
             ...(first === undefined
                 ? []
                 : [
                       {
-                          kind: "external" as const,
+                          kind: "externalScript" as const,
                           src: `${TAG_ORIGIN}/gtag/js?id=${encodeURIComponent(first)}`,
-                          attributes: {},
+                          attrs: {},
                       },
                   ]),
         ],

package/src/analytics/index.ts

@@ -1,6 +1,7 @@
+import type { MetaTag } from "../meta/tag.ts";
 import type { HttpsUrl } from "../url.ts";
 import { type GoogleSettings, googleEmits, googleScripts } from "./google.ts";
-import type { AnalyticsTag, AnalyticsTags } from "./tags.ts";
+import type { AnalyticsTags } from "./tags.ts";
 import {
     checkUmamiDomains,
     type UmamiSettings,
@@ -28,7 +29,7 @@ export {
     type ConsentState,
     type GoogleSettings,
 } from "./google.ts";
-export type { AnalyticsTag, AnalyticsTags } from "./tags.ts";
+export type { AnalyticsTags } from "./tags.ts";
 export type {
     UmamiReplay,
     UmamiSettings,
@@ -134,6 +135,6 @@ export const NOT_FOUND_TAG = "404";
  */
 export function notFoundAnalytics(
     analytics: AnalyticsSettings | undefined
-): readonly AnalyticsTag[] {
+): readonly MetaTag[] {
     return umamiScripts(analytics?.umami, NOT_FOUND_TAG);
 }

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/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,61 @@
+---
+/** Internal to `ConsentBanner.astro`, so its script ships only where it renders. */
+import type { HTMLAttributes } from "astro/types";
+import { consentBanner } from "./consent.ts";
+
+type Props = HTMLAttributes<"div">;
+---
+
+<atlas-consent
+    {...Astro.props}
+    {...consentBanner.root}
+    hidden
+    role="dialog"
+    aria-modal="false"
+>
+    <slot />
+</atlas-consent>
+
+<script>
+import {
+    applyConsent,
+    CONSENT_ROLES,
+    consentApplies,
+    consentReopen,
+    consentStore,
+} from "./consent.ts";
+import { element } from "./element.ts";
+
+element("atlas-consent", CONSENT_ROLES, (host, { answer }, 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 { element, values } of answer.all()) {
+        element.addEventListener(
+            "click",
+            () => {
+                store.record(values.choice);
+                host.hidden = true;
+            },
+            { signal }
+        );
+    }
+
+    // Outside the banner — withdrawing must be as easy as granting.
+    for (const { element } of consentReopen.all(document)) {
+        element.hidden = false;
+        element.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,102 @@
+---
+/**
+ * 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

package/src/astro/RichText.astro

@@ -0,0 +1,71 @@
+---
+/**
+ * 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.
+ *
+ * ```astro
+ * <RichText spans={rich("about.intro", { venue: "contact" })} variants={{ accent: "…" }} />
+ * ```
+ */
+import type { HTMLTag } from "astro/types";
+import type { RichText } from "../content/index.ts";
+import { warn } from "../warn.ts";
+
+interface Props {
+    readonly spans: RichText;
+    /** The element wrapping the runs. Defaults to `p`. */
+    readonly as?: HTMLTag;
+    readonly class?: string;
+    /** `[v:name]` → classes. */
+    readonly variants?: Readonly<Record<string, string>>;
+    /** Classes on every link: `[a:]`, `[mail]` and `[tel]`. */
+    readonly link?: string;
+}
+
+const {
+    spans,
+    as: Tag = "p",
+    class: className,
+    variants = {},
+    link,
+}: Props = Astro.props;
+
+// The words still render: losing the sentence is worse than losing its style.
+const variantClass = (variant: string): string | undefined => {
+    if (!Object.hasOwn(variants, variant)) {
+        warn(
+            Astro.url.pathname,
+            `[v:${variant}] has no class in RichText's variants.`
+        );
+    }
+    return variants[variant];
+};
+---
+
+<Tag class={className}>
+    {spans.map((span) => {
+        switch (span.kind) {
+            case "text":
+                return span.text;
+            case "bold":
+                return <strong>{span.text}</strong>;
+            case "variant":
+                return <span 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;
+        }
+    })}
+</Tag>

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,29 @@
  * 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 ElementRoles, element } from "./element.ts";
 export * from "./filters.ts";
 export * from "./filters-view.ts";
-export * from "./markup.ts";
+export {
+    type Component,
+    type Marked,
+    type Markup,
+    marker,
+    markup,
+} from "./markup.ts";
 export * from "./youtube.ts";