@escape-game-over/atlas 0.1.79 → 0.1.80

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.79",
+    "version": "0.1.80",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -17,6 +17,7 @@
         "./astro/images": "./src/astro/images.ts",
         "./client": "./src/astro/client.ts",
         "./astro/auto-dialog": "./src/astro/AutoDialog.astro",
+        "./astro/background-video": "./src/astro/BackgroundVideo.astro",
         "./astro/consent-banner": "./src/astro/ConsentBanner.astro",
         "./astro/document": "./src/astro/Document.astro",
         "./astro/element": "./src/astro/AtlasElement.astro",

package/src/astro/BackgroundVideo.astro

@@ -0,0 +1,151 @@
+---
+/**
+ * A decorative, silent loop over its own poster, with the pause control WCAG
+ * 2.2.2 asks for. Playback is `backgroundVideo`'s; this is the markup it needs,
+ * which is where a hero quietly goes wrong:
+ *
+ * - The poster is a `<picture>`, not the `poster` attribute, so each
+ *   orientation gets its own still, cut to size. It is usually the largest
+ *   paint, so it loads eagerly and first.
+ * - `preload="none"`: nothing of the loop is fetched until it starts, which is
+ *   after `load` — `metadata` alone was enough to undo that wait.
+ * - `muted`, `loop`, `playsinline`, and hidden from assistive technology.
+ * - The control stays hidden until a cut suits the viewport, and names what it
+ *   will do — `play` or `pause`, the site's own words.
+ *
+ * The site gives the element its size and position, the control its look, and
+ * its two icons as the `playing` slot (shown while it plays: a pause icon) and
+ * the `paused` slot.
+ *
+ * ```astro
+ * <BackgroundVideo
+ *     sources={[{ src: webm, type: 'video/webm; codecs="vp9"' }]}
+ *     posters={[{ image: portraitStill, media: "(orientation: portrait)" }, { image: still }]}
+ *     play={t("hero.play")}
+ *     pause={t("hero.pause")}
+ *     class="absolute inset-0"
+ *     buttonClass="absolute bottom-4 right-4 …"
+ * >
+ *     <Icon slot="playing" name="lucide:pause" />
+ *     <Icon slot="paused" name="lucide:play" />
+ * </BackgroundVideo>
+ * ```
+ */
+import { getImage } from "astro:assets";
+import type { HTMLAttributes } from "astro/types";
+import type { NonEmpty } from "../types.ts";
+import AtlasElement from "./AtlasElement.astro";
+import type { VideoPoster, VideoSource } from "./background-video.ts";
+import { backgroundVideoElement } from "./background-video-element.ts";
+
+type Props = Omit<HTMLAttributes<"div">, "children"> & {
+    readonly sources: NonEmpty<VideoSource>;
+    /** Stills by viewport, as `<picture>` reads them: the last has no `media`. */
+    readonly posters: NonEmpty<VideoPoster>;
+    /** The control's label while paused. */
+    readonly play: string;
+    /** The control's label while playing. */
+    readonly pause: string;
+    readonly buttonClass?: string;
+    /** For the poster's `srcset`. Defaults to `100vw`, a full-bleed background. */
+    readonly sizes?: string;
+};
+
+const {
+    sources,
+    posters,
+    play,
+    pause,
+    buttonClass,
+    sizes = "100vw",
+    ...attrs
+} = Astro.props;
+
+const fallback = posters[posters.length - 1];
+if (fallback?.media !== undefined) {
+    throw new Error(
+        "BackgroundVideo: the last poster is the fallback, and takes no `media`."
+    );
+}
+if (posters.slice(0, -1).some((poster) => poster.media === undefined)) {
+    throw new Error(
+        "BackgroundVideo: every poster but the last needs a `media`; one without would always win."
+    );
+}
+
+const cut = await Promise.all(
+    posters.map(async (poster) => ({
+        media: poster.media,
+        image: await getImage({
+            src: poster.image,
+            widths: [...(poster.widths ?? [960, 1440, 1920])],
+            format: "webp",
+        }),
+    }))
+);
+const still = cut[cut.length - 1];
+
+// Structural, so inline: the still under the video, both covering the element.
+const cover = "width:100%;height:100%;object-fit:cover";
+---
+
+<script src="./background-video-element.ts" />
+
+<AtlasElement
+    of={backgroundVideoElement}
+    data-play={play}
+    data-pause={pause}
+    {...attrs}
+>
+    <picture>
+        {cut.slice(0, -1).map((poster) => (
+            <source
+                media={poster.media}
+                srcset={poster.image.srcSet.attribute}
+                sizes={sizes}
+            />
+        ))}
+        <img
+            src={still?.image.src}
+            srcset={still?.image.srcSet.attribute}
+            sizes={sizes}
+            alt=""
+            fetchpriority="high"
+            style={`position:absolute;inset:0;${cover}`}
+        >
+    </picture>
+    <video
+        style={`position:relative;${cover}`}
+        muted
+        loop
+        playsinline
+        preload="none"
+        aria-hidden="true"
+        tabindex="-1"
+    >
+        {sources.map((source) => (
+            <source
+                src={source.src}
+                media={source.media}
+                type={source.type}
+            />
+        ))}
+    </video>
+    <button
+        type="button"
+        data-video-toggle
+        hidden
+        aria-label={pause}
+        class={buttonClass}
+    >
+        <span data-video-playing>
+            <slot name="playing" />
+        </span>
+        <span
+            data-video-paused
+            hidden
+        >
+            <slot name="paused" />
+        </span>
+    </button>
+</AtlasElement>

package/src/astro/background-video-element.ts

@@ -0,0 +1,38 @@
+// Internal to `BackgroundVideo.astro`: binds its markup to `backgroundVideo`.
+import { type BackgroundVideo, backgroundVideo } from "./background-video.ts";
+import { element } from "./element.ts";
+import { data, ref } from "./ref.ts";
+
+/**
+ * Each root's loop, kept across a re-attach: the reader's pause belongs to the
+ * video, not to one connection of the element.
+ */
+const loops = new WeakMap<HTMLElement, BackgroundVideo>();
+
+export const backgroundVideoElement = element(
+    "atlas-background-video",
+    ({ root, signal }) => {
+        const play = data(root, "play");
+        const pause = data(root, "pause");
+        const button = ref<HTMLButtonElement>(root, "[data-video-toggle]");
+        const whenPlaying = ref<HTMLElement>(root, "[data-video-playing]");
+        const whenPaused = ref<HTMLElement>(root, "[data-video-paused]");
+
+        const loop =
+            loops.get(root) ??
+            backgroundVideo({
+                onChange: ({ playing, playable }) => {
+                    // Nothing to pause where no cut suits this viewport.
+                    button.hidden = !playable;
+                    button.setAttribute("aria-label", playing ? pause : play);
+                    whenPlaying.hidden = !playing;
+                    whenPaused.hidden = playing;
+                },
+            });
+        loops.set(root, loop);
+
+        button.addEventListener("click", () => loop.toggle(), { signal });
+
+        return loop.attach(ref<HTMLVideoElement>(root, "video"));
+    }
+);

package/src/astro/background-video.ts

@@ -1,5 +1,7 @@
 /**
  * A decorative background video's playback — not its markup, and not its button.
+ * `BackgroundVideo.astro` is both, built on this; reach for this directly only
+ * for markup that component cannot write.
  *
  * In `astro/` because it reaches for `matchMedia` and a media element, which the
  * core is type-checked without.
@@ -55,6 +57,27 @@
  * or `"metadata"` keeps the browser from fetching the loop on its own.
  */
 
+/** One file of a `BackgroundVideo`, as a `<source>`. */
+export interface VideoSource {
+    readonly src: string;
+    /**
+     * With its codecs — `video/webm; codecs="vp9"` — so a browser skips what
+     * it cannot play without fetching it to find out.
+     */
+    readonly type: string;
+    /** The viewports this cut is for; the first matching source wins. */
+    readonly media?: string;
+}
+
+/** One still of a `BackgroundVideo`'s poster, as a `<picture>` source. */
+export interface VideoPoster {
+    readonly image: ImageMetadata;
+    /** The widths to cut, for `srcset`. Defaults to 960, 1440 and 1920. */
+    readonly widths?: readonly number[];
+    /** The viewports this still is for. Absent on the last, the fallback. */
+    readonly media?: string;
+}
+
 export interface BackgroundVideoState {
     /** Whether it is playing now: the element's own `paused`, inverted. */
     readonly playing: boolean;