contour-deck 0.0.0-stage → 0.2.0

package/dist/astro/Deck.astro

@@ -0,0 +1,68 @@
+---
+/**
+ * The Astro host of a Contour deck. Put the rendered Markdown (the output of `contour-deck/rehype`)
+ * in the slot; without JavaScript it stays a document.
+ *
+ *   <Deck docClass="prose" legacy><Content /></Deck>
+ *   <button data-ct-start>START</button>
+ *   <a href="?view=notes" data-ct-start="notes">Notes</a>
+ *
+ * `?view=deck` and `?view=notes` open the deck on load; so does any `[data-ct-start]` control.
+ * With `remote` or `relay`, the deck has a remote (R): `?view=remote` is the phone, `?view=presenter` the presenter window.
+ *
+ * The build copies this file to dist/astro/, and the import paths are the ones that hold there:
+ * ../style.css is dist/style.css, ./host.js the compiled src/astro/host.ts.
+ */
+import "../style.css";
+
+interface Props {
+  /** Classes of the wrapper in both views. */
+  class?: string;
+  /**
+   * Classes the wrapper carries only while the deck is closed, such as a prose class.
+   * The open deck stays inside the wrapper, so these would otherwise restyle the stage and the shell.
+   */
+  docClass?: string;
+  /** `snap`: one wheel gesture moves one stop. `free`: native scrolling. Default `snap`. */
+  paging?: "snap" | "free";
+  /** How the outline looks on entry. Default `flat`. */
+  overview?: "flat" | "3d";
+  /** Accept old reveal.js links, `?view=slides&slide=h.v`, through `data-legacy`. */
+  legacy?: boolean;
+  /** The remote button and the `R` key: presenter window and notes link. Implied by `relay`. */
+  remote?: boolean;
+  /** Base URL of the relay (`wss://…`), so a phone can pair and control the deck. See docs/PROTOCOL.md. */
+  relay?: string;
+}
+
+const { class: className, docClass, paging, overview, legacy = false, remote = false, relay } = Astro.props;
+---
+
+<div
+  data-ct-host
+  class:list={[className, docClass]}
+  data-ct-doc-class={docClass}
+  data-ct-paging={paging}
+  data-ct-overview={overview}
+  data-ct-legacy={legacy ? "" : undefined}
+  data-ct-remote={remote ? "" : undefined}
+  data-ct-relay={relay}
+>
+  <slot />
+</div>
+
+<script>
+  import { mountAll, type Host } from "./host.js";
+
+  let hosts: Host[] = mountAll();
+
+  // Under Astro's client router this module runs once; each later page mounts on page-load,
+  // and an open deck is put back before the old page is swapped out.
+  document.addEventListener("astro:page-load", () => {
+    hosts = mountAll();
+  });
+  document.addEventListener("astro:before-swap", () => {
+    for (const host of hosts) host.unmount();
+    hosts = [];
+  });
+</script>

package/dist/astro/host.d.ts

@@ -0,0 +1,20 @@
+import type { Deck, DeckOptions } from "../core/index.js";
+import type { RemoteOptions } from "../remote/index.js";
+/**
+ * Options of the remote for every deck of the page, such as a QR encoder the site already ships:
+ * `configureRemote({ qr: text => QRCode.toString(text, { type: "svg" }) })`.
+ * A `data-ct-relay` on a wrapper wins over `relay` given here.
+ */
+export declare function configureRemote(options: RemoteOptions): void;
+export interface Host {
+    /** The open deck, or `null` while the page shows the document. */
+    readonly deck: Deck | null;
+    open(options?: Pick<DeckOptions, "view" | "at">): void;
+    close(): void;
+    /** Closes the deck and removes every listener. */
+    unmount(): void;
+}
+/** Wires one `[data-ct-host]`. Mounting the same element twice returns the first host. */
+export declare function mount(host: HTMLElement): Host | null;
+/** Mounts every `[data-ct-host]` in the document that is not mounted yet. */
+export declare function mountAll(): Host[];

package/dist/astro/host.js

@@ -0,0 +1,170 @@
+/**
+ * What a host page does around the core, written once: open the deck when the URL or a control asks
+ * for it, close it on exit, and send old reveal.js links to their new position.
+ * `Deck.astro` calls this; a plain HTML host can call it too.
+ *
+ * | Host markup                              | Meaning                                                      |
+ * | ---------------------------------------- | ------------------------------------------------------------ |
+ * | `[data-ct-host]`                         | wrapper of one `[data-ct-deck]`                              |
+ * | `data-ct-doc-class="prose"`              | classes the wrapper carries only while the deck is closed    |
+ * | `data-ct-paging`, `data-ct-overview`     | the `paging` and `overview` options of the core              |
+ * | `data-ct-legacy`                         | accept `?view=slides&slide=h.v`                              |
+ * | `[data-ct-start]`, `[data-ct-start="notes"]` | a control that opens the deck or its notes view: inside a host for that deck, elsewhere for the first deck of the page |
+ * | `data-ct-remote`, `data-ct-relay="wss://…"` | the remote button and the `R` key; with a relay URL a phone can pair (docs/PROTOCOL.md) |
+ *
+ * The remote (`contour-deck/remote`) is loaded on first use: on `R`, on `?view=remote` (the phone),
+ * and on `?view=presenter` (the presenter window).
+ */
+import { createDeck } from "../core/index.js";
+import { hostKey } from "../remote/store.js";
+import { legacyAt, parseLegacy, readLegacy } from "./legacy.js";
+let remoteDefaults = {};
+/**
+ * Options of the remote for every deck of the page, such as a QR encoder the site already ships:
+ * `configureRemote({ qr: text => QRCode.toString(text, { type: "svg" }) })`.
+ * A `data-ct-relay` on a wrapper wins over `relay` given here.
+ */
+export function configureRemote(options) {
+    remoteDefaults = { ...remoteDefaults, ...options };
+}
+const mounted = new WeakMap();
+function stored(key) {
+    try {
+        return sessionStorage.getItem(key) !== null;
+    }
+    catch {
+        return false;
+    }
+}
+function optionsOf(host) {
+    const { ctPaging, ctOverview } = host.dataset;
+    return {
+        ...(ctPaging === "free" || ctPaging === "snap" ? { paging: ctPaging } : {}),
+        ...(ctOverview === "3d" || ctOverview === "flat" ? { overview: ctOverview } : {}),
+    };
+}
+/**
+ * Rewrites `?view=slides&slide=h.v` to `?view=deck&at=b.s.p` in place and returns nothing:
+ * the core then reads its own parameters. An old link without a match opens the outline.
+ */
+function adoptLegacyUrl(root) {
+    const url = new URL(location.href);
+    if (url.searchParams.get("view") !== "slides")
+        return;
+    const old = parseLegacy(url.searchParams.get("slide") ?? "0");
+    const at = old && legacyAt(readLegacy(root), old.h, old.v);
+    url.searchParams.delete("slide");
+    url.searchParams.set("view", "deck");
+    if (at)
+        url.searchParams.set("at", at);
+    history.replaceState(history.state, "", url);
+}
+/** Wires one `[data-ct-host]`. Mounting the same element twice returns the first host. */
+export function mount(host) {
+    const known = mounted.get(host);
+    if (known)
+        return known;
+    const root = host.querySelector("[data-ct-deck]");
+    if (!root)
+        return null;
+    const docClasses = (host.dataset.ctDocClass ?? "").split(/\s+/).filter(Boolean);
+    const abort = new AbortController();
+    let deck = null;
+    let view = null;
+    let opener = null;
+    const relayUrl = host.dataset.ctRelay;
+    const hasRemote = "ctRemote" in host.dataset || !!relayUrl;
+    const remoteOptions = () => ({ ...remoteDefaults, ...(relayUrl ? { relay: relayUrl } : {}) });
+    /** Starts the remote session of the open deck, or returns the one it has; `null` when the deck closed while the module loaded. */
+    const remoteOf = async (open) => {
+        const { remoteHost } = await import("../remote/session.js");
+        return deck === open ? remoteHost(open, root, remoteOptions()) : null;
+    };
+    function close() {
+        view?.destroy();
+        view = null;
+        if (!deck)
+            return void host.classList.add(...docClasses);
+        deck.destroy();
+        deck = null;
+        host.classList.add(...docClasses);
+        opener?.focus({ preventScroll: true });
+        opener = null;
+    }
+    function open(options = {}) {
+        if (deck)
+            return;
+        // Document-view classes (a prose class, say) would restyle the shell and the stage, so they wait outside.
+        host.classList.remove(...docClasses);
+        try {
+            deck = createDeck(root, {
+                ...optionsOf(host),
+                ...(hasRemote ? { remote: (open) => void remoteOf(open).then(remote => remote?.toggle()) } : {}),
+                ...options,
+            });
+        }
+        catch (error) {
+            host.classList.add(...docClasses);
+            throw error;
+        }
+        deck.on("exit", close);
+        // A remote session of this tab (a paired phone, a running clock) continues after a reload.
+        if (hasRemote && stored(hostKey()))
+            void remoteOf(deck);
+    }
+    /** The phone remote or the presenter window: this page as a view of a deck open elsewhere. */
+    async function openView(kind) {
+        host.classList.remove(...docClasses);
+        const made = kind === "remote"
+            ? (await import("../remote/phone.js")).remoteView(root, remoteOptions())
+            : (await import("../remote/presenter.js")).presenterView(root, remoteOptions());
+        if (abort.signal.aborted)
+            made.destroy();
+        else
+            view = made;
+    }
+    // In the capture phase: a client-side router that listens on the document would otherwise
+    // take a start link as a navigation before this handler sees it.
+    document.addEventListener("click", event => {
+        const control = event.target.closest?.("[data-ct-start]");
+        if (!control || event.defaultPrevented)
+            return;
+        // A modified click on a start link opens it in a new tab or window, as any link.
+        if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+            return;
+        // A control inside a host opens that deck; one elsewhere opens the first deck of the page.
+        if ((control.closest("[data-ct-host]") ?? document.querySelector("[data-ct-host]")) !== host)
+            return;
+        event.preventDefault();
+        opener = control;
+        open({ view: control.dataset.ctStart === "notes" ? "notes" : "deck" });
+    }, { capture: true, signal: abort.signal });
+    if ("ctLegacy" in host.dataset)
+        adoptLegacyUrl(root);
+    const asked = new URLSearchParams(location.search).get("view");
+    if (asked === "deck" || asked === "notes")
+        open();
+    // The remote views follow the first deck of the page.
+    else if ((asked === "remote" || asked === "presenter") && document.querySelector("[data-ct-host]") === host)
+        void openView(asked);
+    const api = {
+        get deck() {
+            return deck;
+        },
+        open,
+        close,
+        unmount() {
+            close();
+            abort.abort();
+            mounted.delete(host);
+        },
+    };
+    mounted.set(host, api);
+    return api;
+}
+/** Mounts every `[data-ct-host]` in the document that is not mounted yet. */
+export function mountAll() {
+    return Array.from(document.querySelectorAll("[data-ct-host]"))
+        .map(mount)
+        .filter((host) => host !== null);
+}

package/dist/astro/legacy.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Old reveal.js links (`?view=slides&slide=h.v`) to a Contour position, read from the
+ * `data-legacy` and `data-legacy-v` attributes of docs/CONTRACT.md.
+ */
+/** One slide as the old deck knew it: its horizontal index, the vertical index of its first page, its page count. */
+export interface LegacySlide {
+    legacy: number;
+    legacyV: number;
+    pages: number;
+}
+/** `"11"` or `"11.2"` to the old indexes; `null` when the text is not an old slide parameter. */
+export declare function parseLegacy(slide: string): {
+    h: number;
+    v: number;
+} | null;
+/**
+ * The `?at=` value (1-based `b.s.p`) of the old slide `h.v`. `blocks[b][s]` describes slide `s` of block `b`.
+ * A `v` past the end of the old stack lands on its last page; an `h` the deck never had gives `null`.
+ */
+export declare function legacyAt(blocks: LegacySlide[][], h: number, v: number): string | null;
+/** Reads the legacy table of a deck element. Slides without `data-legacy` never match. */
+export declare function readLegacy(root: Element): LegacySlide[][];

package/dist/astro/legacy.js

@@ -0,0 +1,42 @@
+/**
+ * Old reveal.js links (`?view=slides&slide=h.v`) to a Contour position, read from the
+ * `data-legacy` and `data-legacy-v` attributes of docs/CONTRACT.md.
+ */
+/** `"11"` or `"11.2"` to the old indexes; `null` when the text is not an old slide parameter. */
+export function parseLegacy(slide) {
+    const match = /^(\d+)(?:\.(\d+))?$/.exec(slide.trim());
+    return match ? { h: Number(match[1]), v: Number(match[2] ?? 0) } : null;
+}
+/**
+ * The `?at=` value (1-based `b.s.p`) of the old slide `h.v`. `blocks[b][s]` describes slide `s` of block `b`.
+ * A `v` past the end of the old stack lands on its last page; an `h` the deck never had gives `null`.
+ */
+export function legacyAt(blocks, h, v) {
+    let found;
+    for (const [b, slides] of blocks.entries()) {
+        for (const [s, slide] of slides.entries()) {
+            if (slide.legacy !== h)
+                continue;
+            // Slides split from one old stack share `h`; the one that holds `v` starts at or before it.
+            if (!found || (slide.legacyV <= v && slide.legacyV >= found.slide.legacyV))
+                found = { b, s, slide };
+        }
+    }
+    if (!found)
+        return null;
+    const page = Math.min(Math.max(v - found.slide.legacyV, 0), found.slide.pages - 1);
+    return `${found.b + 1}.${found.s + 1}.${page + 1}`;
+}
+/** Reads the legacy table of a deck element. Slides without `data-legacy` never match. */
+export function readLegacy(root) {
+    const childrenWith = (el, attribute) => Array.from(el.children).filter(child => child.hasAttribute(attribute));
+    const index = (el, attribute, missing) => {
+        const value = el.getAttribute(attribute);
+        return value !== null && /^\d+$/.test(value) ? Number(value) : missing;
+    };
+    return childrenWith(root, "data-ct-block").map(block => childrenWith(block, "data-ct-slide").map(slide => ({
+        legacy: index(slide, "data-legacy", -1),
+        legacyV: index(slide, "data-legacy-v", 0),
+        pages: childrenWith(slide, "data-ct-page").length,
+    })));
+}

package/dist/core/deck.d.ts

@@ -0,0 +1,2 @@
+import type { Deck, DeckOptions } from "./types.js";
+export declare function createDeck(root: HTMLElement, options?: DeckOptions): Deck;