forgebook 0.1.7 → 0.2.0

package/dist/src/previewRelay.js

@@ -0,0 +1,69 @@
+/// <reference lib="dom" />
+/**
+ * The page between a client's app and a story's frame: it shows the frame and says when the story is up and how tall.
+ *
+ * @remarks
+ * The app runs on an origin the host chooses, so a frame cannot talk to it: a frame posts to the catalogue's origin
+ * only, which keeps its messages (a story's args among them) from any page that embeds it. This page is on the
+ * catalogue's origin, reads the messages of the frame, on the frames' origin, as the shell does, and passes the app
+ * three facts and nothing else: that it runs, that something was drawn, and the height. A page that embeds it learns no
+ * more than that, so it can post to any origin, as it has to: the app's may be opaque. A story that fails counts as
+ * drawn, as the frame shows the error itself.
+ *
+ * A frame opened alone on a cold dev server can stay blank: when the server prepares a dependency again, a static import
+ * of the frame's own entry fails before any of its code runs, so its reload for a stale module never happens and no
+ * shell is there to load it again. So the relay does, once, when the frame loaded and has said nothing at all, by
+ * loading its address again: the frame's own `location` is another origin's, which this page may not reload.
+ *
+ * Runs in the page, written into it by its source (`previewPages.ts`), so it takes no import.
+ *
+ * @module
+ */
+/**
+ * Shows a story's frame and tells the embedding app about it.
+ *
+ * @param frameAddress - the story's frame, on the frames' origin.
+ * @param title - the frame's name for a screen reader: the story's id.
+ */
+export const previewRelay = (frameAddress, title) => {
+    /** How long a loaded frame may stay silent before its one reload, in ms. */
+    const reloadAfterMs = 4000;
+    /** The only origin a message is heard from: the frame's, which the server wrote in the page. */
+    const framesOrigin = new URL(frameAddress, window.location.href).origin;
+    const frame = document.createElement("iframe");
+    frame.title = title;
+    frame.style.cssText = "display:block;width:100%;height:100vh;border:0";
+    const tell = (message) => {
+        window.parent.postMessage(message, "*");
+    };
+    let hasHeard = false;
+    let hasReloaded = false;
+    frame.addEventListener("load", () => {
+        setTimeout(() => {
+            if (hasHeard || hasReloaded)
+                return;
+            hasReloaded = true;
+            frame.src = frameAddress;
+        }, reloadAfterMs);
+    });
+    window.addEventListener("message", (event) => {
+        if (event.origin !== framesOrigin || event.source !== frame.contentWindow)
+            return;
+        const { data } = event;
+        if (typeof data !== "object" || data === null || !("type" in data))
+            return;
+        hasHeard = true;
+        if (data.type === "forgebook:ready" || data.type === "forgebook:error")
+            tell({ type: "forgebook:preview-ready" });
+        if (data.type === "forgebook:size" &&
+            "height" in data &&
+            typeof data.height === "number" &&
+            data.height > 0) {
+            frame.style.height = `${data.height}px`;
+            tell({ type: "forgebook:preview-size", height: data.height });
+        }
+    });
+    tell({ type: "forgebook:preview-started" });
+    frame.src = frameAddress;
+    document.body.append(frame);
+};

package/dist/src/previewTexts.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The words of a story's preview in a client that renders apps. A catalogue replaces any of them by name
+ * (`strings: { previewOpen: "Open" }` in its configuration), as it does the shell's; they stay out of the shell's texts,
+ * whose page never shows them.
+ *
+ * @module
+ */
+/** The page's words, as Forgebook writes them. */
+export declare const PREVIEW_TEXTS: {
+    previewWaiting: string;
+    previewLoading: string;
+    previewTakingPicture: string;
+    previewUnavailable: string;
+    previewCancelled: string;
+    previewOpen: string;
+    previewPicture: string;
+    previewFrame: string;
+};
+/** The page's words. */
+export type PreviewTexts = typeof PREVIEW_TEXTS;
+/**
+ * The words of a catalogue: its replacements over Forgebook's. A replacement of no word of the page is left out.
+ *
+ * @param strings - the catalogue's `strings`.
+ */
+export declare const previewTexts: (strings: Readonly<Record<string, string>>) => PreviewTexts;

package/dist/src/previewTexts.js

@@ -0,0 +1,33 @@
+/**
+ * The words of a story's preview in a client that renders apps. A catalogue replaces any of them by name
+ * (`strings: { previewOpen: "Open" }` in its configuration), as it does the shell's; they stay out of the shell's texts,
+ * whose page never shows them.
+ *
+ * @module
+ */
+/** The page's words, as Forgebook writes them. */
+export const PREVIEW_TEXTS = {
+    previewWaiting: "Waiting for the story",
+    previewLoading: "Loading the story",
+    previewTakingPicture: "This client cannot show the story live: taking its picture",
+    previewUnavailable: "This client can show neither the story nor its picture. Open it in the catalogue.",
+    previewCancelled: "The preview was cancelled",
+    previewOpen: "Open in the catalogue",
+    previewPicture: "A picture of the story",
+    previewFrame: "The story"
+};
+/**
+ * The words of a catalogue: its replacements over Forgebook's. A replacement of no word of the page is left out.
+ *
+ * @param strings - the catalogue's `strings`.
+ */
+export const previewTexts = (strings) => ({
+    previewWaiting: strings["previewWaiting"] ?? PREVIEW_TEXTS.previewWaiting,
+    previewLoading: strings["previewLoading"] ?? PREVIEW_TEXTS.previewLoading,
+    previewTakingPicture: strings["previewTakingPicture"] ?? PREVIEW_TEXTS.previewTakingPicture,
+    previewUnavailable: strings["previewUnavailable"] ?? PREVIEW_TEXTS.previewUnavailable,
+    previewCancelled: strings["previewCancelled"] ?? PREVIEW_TEXTS.previewCancelled,
+    previewOpen: strings["previewOpen"] ?? PREVIEW_TEXTS.previewOpen,
+    previewPicture: strings["previewPicture"] ?? PREVIEW_TEXTS.previewPicture,
+    previewFrame: strings["previewFrame"] ?? PREVIEW_TEXTS.previewFrame
+});

package/dist/src/previewView.d.ts

@@ -0,0 +1,31 @@
+import type { PreviewTexts } from "./previewTexts.ts";
+/** What the page is given when it is written. */
+export type PreviewViewOptions = {
+    /** Its words. */
+    readonly texts: PreviewTexts;
+    /** Forgebook's version, which it names to the host. */
+    readonly version: string;
+    /** The MCP Apps version it speaks. */
+    readonly protocolVersion: string;
+    /** The tool that takes the picture. */
+    readonly shotTool: string;
+    /** How long a story may stay silent before its picture is asked for, in ms. */
+    readonly silenceMs: number;
+    /** The class of a frame still loading, which the style sheet keeps out of sight. */
+    readonly loadingClass: string;
+};
+/** The ids of the elements `previewPages.ts` writes, which the page fills. */
+export declare const PREVIEW_ELEMENTS: {
+    readonly title: "story";
+    readonly open: "open";
+    readonly status: "status";
+    readonly frame: "frame";
+    readonly picture: "picture";
+};
+/**
+ * Runs the page.
+ *
+ * @param options - what it is given.
+ * @param elements - the ids of its elements.
+ */
+export declare const previewView: (options: PreviewViewOptions, elements: typeof PREVIEW_ELEMENTS) => void;

package/dist/src/previewView.js

@@ -0,0 +1,264 @@
+/** The ids of the elements `previewPages.ts` writes, which the page fills. */
+export const PREVIEW_ELEMENTS = {
+    title: "story",
+    open: "open",
+    status: "status",
+    frame: "frame",
+    picture: "picture"
+};
+/**
+ * Runs the page.
+ *
+ * @param options - what it is given.
+ * @param elements - the ids of its elements.
+ */
+export const previewView = (options, elements) => {
+    const { texts } = options;
+    const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+    const textOf = (value) => typeof value === "string" && value !== "" ? value : undefined;
+    const required = (id, type) => {
+        const found = document.getElementById(id);
+        if (!(found instanceof type))
+            throw new Error(`The page has no ${id}`);
+        return found;
+    };
+    const title = required(elements.title, HTMLElement);
+    const open = required(elements.open, HTMLButtonElement);
+    const status = required(elements.status, HTMLElement);
+    const frame = required(elements.frame, HTMLIFrameElement);
+    const picture = required(elements.picture, HTMLImageElement);
+    /* the host's side of the conversation */
+    let lastId = 0;
+    const waiting = new Map();
+    const post = (message) => {
+        window.parent.postMessage({ jsonrpc: "2.0", ...message }, "*");
+    };
+    const notify = (method, params) => {
+        post({ method, params });
+    };
+    const ask = (method, params) => new Promise((done) => {
+        lastId += 1;
+        waiting.set(lastId, done);
+        post({ id: lastId, method, params });
+    });
+    /* what the page knows */
+    let storyId;
+    let view;
+    let address;
+    let hostOpensLinks = false;
+    let hostCallsTools = false;
+    let isLive = false;
+    let isFallingBack = false;
+    let hasRelay = false;
+    let storyOrigin;
+    let silence;
+    const say = (text) => {
+        status.textContent = text;
+        status.hidden = text === "";
+    };
+    const showLink = () => {
+        open.hidden = !(hostOpensLinks && address !== undefined);
+    };
+    const showLive = () => {
+        isLive = true;
+        clearTimeout(silence);
+        say("");
+        picture.hidden = true;
+        frame.classList.remove(options.loadingClass);
+    };
+    // at this page's own width, so that the picture is not a whole window shrunk into it
+    const pictureView = () => {
+        const search = new URLSearchParams(view);
+        if (!search.has("width"))
+            search.set("width", String(document.body.clientWidth));
+        return search.toString();
+    };
+    const showPicture = async () => {
+        if (isLive || isFallingBack || storyId === undefined)
+            return;
+        isFallingBack = true;
+        clearTimeout(silence);
+        if (!hostCallsTools) {
+            say(texts.previewUnavailable);
+            return;
+        }
+        say(texts.previewTakingPicture);
+        const { result } = await ask("tools/call", {
+            name: options.shotTool,
+            arguments: { id: storyId, views: [pictureView()] }
+        });
+        if (isLive)
+            return;
+        const content = isRecord(result) && Array.isArray(result["content"]) ? result["content"] : [];
+        const image = content.find((block) => isRecord(block) && block["type"] === "image");
+        if (!isRecord(image) || typeof image["data"] !== "string") {
+            say(texts.previewUnavailable);
+            return;
+        }
+        picture.src = `data:image/png;base64,${image["data"]}`;
+        picture.hidden = false;
+        say("");
+    };
+    const showStory = (preview) => {
+        const url = new URL(preview);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return;
+        say(texts.previewLoading);
+        silence = setTimeout(() => void showPicture(), options.silenceMs);
+        storyOrigin = url.origin;
+        // laid out while it loads, only out of sight: a frame with no box has no viewport and no animation frames, so a
+        // story measuring itself gets zero and a play waiting on either never ends
+        frame.classList.add(options.loadingClass);
+        frame.hidden = false;
+        frame.src = url.href;
+    };
+    const showFailure = (structured) => {
+        const reason = isRecord(structured) ? textOf(structured["error"]) : undefined;
+        say(reason ?? texts.previewUnavailable);
+    };
+    const showAnswer = (answer) => {
+        const structured = isRecord(answer) ? answer["structuredContent"] : undefined;
+        const hasFailed = !isRecord(answer) || answer["isError"] === true;
+        if (hasFailed || !isRecord(structured)) {
+            showFailure(structured);
+            return;
+        }
+        const links = structured["links"];
+        address = isRecord(links) ? textOf(links["address"]) : undefined;
+        storyId = textOf(structured["id"]) ?? storyId;
+        title.textContent = storyId ?? "";
+        showLink();
+        const preview = textOf(structured["preview"]);
+        if (preview === undefined)
+            void showPicture();
+        else
+            showStory(preview);
+    };
+    const applyVariables = (styles) => {
+        const variables = isRecord(styles) ? styles["variables"] : undefined;
+        if (!isRecord(variables))
+            return;
+        for (const [name, value] of Object.entries(variables))
+            if (typeof value === "string")
+                document.documentElement.style.setProperty(name, value);
+    };
+    const applyBox = (box) => {
+        if (!isRecord(box))
+            return;
+        const { style } = document.documentElement;
+        style.height = "";
+        style.maxHeight = "";
+        if ("height" in box)
+            style.height = "100vh";
+        else if (typeof box["maxHeight"] === "number")
+            style.maxHeight = `${box["maxHeight"]}px`;
+    };
+    const applyContext = (context) => {
+        if (!isRecord(context))
+            return;
+        const { theme } = context;
+        if (theme === "light" || theme === "dark")
+            document.documentElement.style.colorScheme = theme;
+        applyVariables(context["styles"]);
+        applyBox(context["containerDimensions"]);
+    };
+    let lastSize = "";
+    const reportSize = () => {
+        const { width, height } = document.body.getBoundingClientRect();
+        const size = { width: Math.ceil(width), height: Math.ceil(height) };
+        if (JSON.stringify(size) === lastSize)
+            return;
+        lastSize = JSON.stringify(size);
+        notify("ui/notifications/size-changed", size);
+    };
+    const applyInitialized = (result) => {
+        if (!isRecord(result))
+            return;
+        const capabilities = result["hostCapabilities"];
+        hostOpensLinks = isRecord(capabilities) && isRecord(capabilities["openLinks"]);
+        hostCallsTools = isRecord(capabilities) && isRecord(capabilities["serverTools"]);
+        applyContext(result["hostContext"]);
+        showLink();
+        notify("ui/notifications/initialized", {});
+        new ResizeObserver(reportSize).observe(document.body);
+    };
+    const answerHost = (id, method) => {
+        // the host waits for the answer before it takes the page down; a story in a frame has nothing to save
+        if (method === "ping" || method === "ui/resource-teardown")
+            post({ id, result: {} });
+        else
+            post({ id, error: { code: -32601, message: `Method not found: ${method}` } });
+    };
+    const hearHost = (method, params) => {
+        if (method === "ui/notifications/tool-result")
+            showAnswer(params);
+        if (method === "ui/notifications/host-context-changed")
+            applyContext(params);
+        if (method === "ui/notifications/tool-cancelled")
+            say(texts.previewCancelled);
+        if (method === "ui/notifications/tool-input" && isRecord(params) && isRecord(params["arguments"])) {
+            storyId = textOf(params["arguments"]["id"]);
+            view = textOf(params["arguments"]["view"]);
+            title.textContent = storyId ?? "";
+        }
+    };
+    const hearStory = (message) => {
+        if (!isRecord(message))
+            return;
+        const started = "forgebook:preview-started";
+        const ready = "forgebook:preview-ready";
+        const size = "forgebook:preview-size";
+        if (message["type"] === started)
+            hasRelay = true;
+        if (message["type"] === ready)
+            showLive();
+        if (message["type"] === size && typeof message["height"] === "number" && message["height"] > 0)
+            frame.style.height = `${message["height"]}px`;
+    };
+    window.addEventListener("message", (event) => {
+        if (event.source === frame.contentWindow) {
+            // the source alone would also let a frame that navigated elsewhere speak for the story
+            if (event.origin === storyOrigin)
+                hearStory(event.data);
+            return;
+        }
+        if (event.source !== window.parent || !isRecord(event.data))
+            return;
+        const { id, method, params } = event.data;
+        if (typeof method === "string") {
+            if (id === undefined)
+                hearHost(method, params);
+            else
+                answerHost(id, method);
+            return;
+        }
+        if (typeof id !== "number")
+            return;
+        waiting.get(id)?.(event.data);
+        waiting.delete(id);
+    });
+    // a frame the host's policy refuses never says so to the frame, only to the document that asked for it
+    document.addEventListener("securitypolicyviolation", (event) => {
+        if (event.effectiveDirective === "frame-src")
+            void showPicture();
+    });
+    frame.addEventListener("load", () => {
+        if (!hasRelay)
+            void showPicture();
+    });
+    open.addEventListener("click", () => {
+        if (address !== undefined)
+            void ask("ui/open-link", { url: address });
+    });
+    open.textContent = texts.previewOpen;
+    frame.title = texts.previewFrame;
+    picture.alt = texts.previewPicture;
+    say(texts.previewWaiting);
+    void ask("ui/initialize", {
+        appInfo: { name: "forgebook-story-preview", version: options.version },
+        appCapabilities: { availableDisplayModes: ["inline"] },
+        protocolVersion: options.protocolVersion
+    }).then(({ result }) => {
+        applyInitialized(result);
+    });
+};

package/dist/src/propGroups.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A component's props in their groups, as its TSDoc names them (`@group Selection`): the API reference and the Props
+ * tab list them the same way.
+ *
+ * @remarks
+ * The props that name no group come first: they are the ones an author left out of every group, most often the few
+ * every use of the component sets (`value`, `onChange`). Then each group, in the order a configuration names them
+ * (the component's meta, then the catalogue), the others in the order they first appear among the props. A component
+ * whose props name no group is one list, as it always was. Every group starts open: a reader folds one away, never the
+ * catalogue. Pure.
+ *
+ * @module
+ */
+/** A group of props: its name, none for the props that name no group, and its props in their order. */
+export type PropGroup<TProp> = {
+    /** The group's name, as `@group` writes it; none for the props that name no group. */
+    readonly name: string | undefined;
+    /** Its props, in their order among the component's. */
+    readonly props: readonly TProp[];
+};
+/**
+ * The order of the groups named first: the component's own (its meta's `parameters.propGroups`), then the
+ * catalogue's (`propGroups` in its configuration) not already named, each once.
+ *
+ * @param componentOrder - the groups the component names first; none by default.
+ * @param catalogueOrder - the groups the catalogue names first; none by default.
+ */
+export declare const propGroupOrder: (componentOrder?: readonly string[], catalogueOrder?: readonly string[]) => readonly string[];
+/**
+ * Props in their groups: those naming no group first, then the groups named in `order`, in its order, then the others
+ * in the order they first appear. A group with no props is never listed, even when `order` names it.
+ *
+ * @param props - the props, in their order.
+ * @param order - the groups to show first, in this order (`propGroupOrder`).
+ */
+export declare const groupedProps: <TProp extends {
+    readonly group?: string | undefined;
+}>(props: readonly TProp[], order: readonly string[]) => PropGroup<TProp>[];
+/**
+ * Whether any of the props names a group: when none does, the props are listed as one list, as before groups.
+ *
+ * @param props - the props.
+ */
+export declare const hasPropGroups: (props: readonly {
+    readonly group?: string | undefined;
+}[]) => boolean;

package/dist/src/propGroups.js

@@ -0,0 +1,59 @@
+/**
+ * A component's props in their groups, as its TSDoc names them (`@group Selection`): the API reference and the Props
+ * tab list them the same way.
+ *
+ * @remarks
+ * The props that name no group come first: they are the ones an author left out of every group, most often the few
+ * every use of the component sets (`value`, `onChange`). Then each group, in the order a configuration names them
+ * (the component's meta, then the catalogue), the others in the order they first appear among the props. A component
+ * whose props name no group is one list, as it always was. Every group starts open: a reader folds one away, never the
+ * catalogue. Pure.
+ *
+ * @module
+ */
+/**
+ * The order of the groups named first: the component's own (its meta's `parameters.propGroups`), then the
+ * catalogue's (`propGroups` in its configuration) not already named, each once.
+ *
+ * @param componentOrder - the groups the component names first; none by default.
+ * @param catalogueOrder - the groups the catalogue names first; none by default.
+ */
+export const propGroupOrder = (componentOrder = [], catalogueOrder = []) => [...new Set([...componentOrder, ...catalogueOrder])];
+/**
+ * Props in their groups: those naming no group first, then the groups named in `order`, in its order, then the others
+ * in the order they first appear. A group with no props is never listed, even when `order` names it.
+ *
+ * @param props - the props, in their order.
+ * @param order - the groups to show first, in this order (`propGroupOrder`).
+ */
+export const groupedProps = (props, order) => {
+    const ungrouped = [];
+    // a map keeps its keys in the order they were first set: the order the groups first appear
+    const named = new Map();
+    for (const prop of props) {
+        if (prop.group === undefined) {
+            ungrouped.push(prop);
+            continue;
+        }
+        const group = named.get(prop.group);
+        if (group === undefined)
+            named.set(prop.group, [prop]);
+        else
+            group.push(prop);
+    }
+    const rank = (name) => {
+        const index = order.indexOf(name);
+        return index === -1 ? order.length : index;
+    };
+    const groups = [...named.entries()]
+        .map(([name, grouped]) => ({ name, props: grouped }))
+        // a stable sort: the groups `order` does not name keep the order they appear in
+        .sort((left, right) => rank(left.name ?? "") - rank(right.name ?? ""));
+    return ungrouped.length === 0 ? groups : [{ name: undefined, props: ungrouped }, ...groups];
+};
+/**
+ * Whether any of the props names a group: when none does, the props are listed as one list, as before groups.
+ *
+ * @param props - the props.
+ */
+export const hasPropGroups = (props) => props.some((prop) => prop.group !== undefined);

package/dist/src/realTouch.d.ts

@@ -1,7 +1,7 @@
 /**
  * The mark of a window where Chromium's own touch emulation runs (`forgebook dev --touch`): its pages see real touch,
  * so the catalogue's simulated touch stays off there. Shared by the window that sets it (`@forgebook/testing/touch`)
- * and the frame that reads it (`touchLayer.ts`).
+ * and the frame that reads it (`followTouch.ts`).
  *
  * @module
  */
@@ -18,4 +18,3 @@ export type TouchWindowRequest = {
     /** The catalogue's address. */
     readonly url: string;
 };
-//# sourceMappingURL=realTouch.d.ts.map

package/dist/src/realTouch.js

@@ -1,7 +1,7 @@
 /**
  * The mark of a window where Chromium's own touch emulation runs (`forgebook dev --touch`): its pages see real touch,
  * so the catalogue's simulated touch stays off there. Shared by the window that sets it (`@forgebook/testing/touch`)
- * and the frame that reads it (`touchLayer.ts`).
+ * and the frame that reads it (`followTouch.ts`).
  *
  * @module
  */
@@ -13,4 +13,3 @@ export const REAL_TOUCH_FLAG = "__forgebookRealTouch";
  * @param view - the window.
  */
 export const isRealTouchWindow = (view) => REAL_TOUCH_FLAG in view;
-//# sourceMappingURL=realTouch.js.map

package/dist/src/safeAreaParameter.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The safe areas a story drawn edge to edge in a device is told, in its frame's address: the parameter that carries
+ * them (`forgebook.safe-area=59,0,34,0`, top, right, bottom and left in CSS px) and the custom properties the frame
+ * writes from it on its root, which such a story pads itself with.
+ *
+ * @remarks
+ * A page in a frame cannot be given `env(safe-area-inset-*)`: browsers keep them at zero there, and only a browser's
+ * own protocol can change them. So the frame writes `--forgebook-safe-area-top`, `-right`, `-bottom` and `-left`
+ * instead, and a story reads them with the real insets as the fallback, for the page it ships in:
+ * `padding-top: var(--forgebook-safe-area-top, env(safe-area-inset-top))`. A story that is not drawn edge to edge
+ * sits inside the safe area and is told nothing. Read by the frame, written by the shell and `forgebook shot`, so
+ * every side reads one format. Pure.
+ *
+ * @module
+ */
+/** The frame's address parameter of the safe areas. */
+export declare const SAFE_AREA_PARAMETER = "forgebook.safe-area";
+/** The sides of the safe areas, in the parameter's order and the custom properties' names. */
+declare const SIDES: readonly ["top", "right", "bottom", "left"];
+/** The safe areas on each side, in CSS px. */
+export type SafeArea = Readonly<Record<(typeof SIDES)[number], number>>;
+/**
+ * A frame's address with the safe areas a story drawn edge to edge is told.
+ *
+ * @param address - the frame's address.
+ * @param safeArea - the safe areas.
+ */
+export declare const withSafeArea: (address: string, safeArea: SafeArea) => string;
+/**
+ * The custom properties a frame's address asks for: none when it carries no safe areas, or carries them wrongly.
+ *
+ * @param search - the frame's query.
+ */
+export declare const safeAreaProperties: (search: string) => readonly (readonly [string, string])[];
+/**
+ * Tells a page the safe areas its address carries, as CSS properties on its root.
+ *
+ * @param root - the page's root element.
+ * @param search - the page's address's query.
+ */
+export declare const applySafeArea: (root: HTMLElement, search: string) => void;
+export {};

package/dist/src/safeAreaParameter.js

@@ -0,0 +1,50 @@
+/**
+ * The safe areas a story drawn edge to edge in a device is told, in its frame's address: the parameter that carries
+ * them (`forgebook.safe-area=59,0,34,0`, top, right, bottom and left in CSS px) and the custom properties the frame
+ * writes from it on its root, which such a story pads itself with.
+ *
+ * @remarks
+ * A page in a frame cannot be given `env(safe-area-inset-*)`: browsers keep them at zero there, and only a browser's
+ * own protocol can change them. So the frame writes `--forgebook-safe-area-top`, `-right`, `-bottom` and `-left`
+ * instead, and a story reads them with the real insets as the fallback, for the page it ships in:
+ * `padding-top: var(--forgebook-safe-area-top, env(safe-area-inset-top))`. A story that is not drawn edge to edge
+ * sits inside the safe area and is told nothing. Read by the frame, written by the shell and `forgebook shot`, so
+ * every side reads one format. Pure.
+ *
+ * @module
+ */
+/** The frame's address parameter of the safe areas. */
+export const SAFE_AREA_PARAMETER = "forgebook.safe-area";
+/** The sides of the safe areas, in the parameter's order and the custom properties' names. */
+const SIDES = ["top", "right", "bottom", "left"];
+/**
+ * A frame's address with the safe areas a story drawn edge to edge is told.
+ *
+ * @param address - the frame's address.
+ * @param safeArea - the safe areas.
+ */
+export const withSafeArea = (address, safeArea) => {
+    const value = SIDES.map((side) => String(Math.round(safeArea[side]))).join(",");
+    return `${address}${address.includes("?") ? "&" : "?"}${SAFE_AREA_PARAMETER}=${value}`;
+};
+/**
+ * The custom properties a frame's address asks for: none when it carries no safe areas, or carries them wrongly.
+ *
+ * @param search - the frame's query.
+ */
+export const safeAreaProperties = (search) => {
+    const values = (new URLSearchParams(search).get(SAFE_AREA_PARAMETER) ?? "").split(",").map(Number);
+    if (values.length !== SIDES.length || values.some((value) => !Number.isFinite(value) || value < 0))
+        return [];
+    return SIDES.map((side, index) => [`--forgebook-safe-area-${side}`, `${values[index] ?? 0}px`]);
+};
+/**
+ * Tells a page the safe areas its address carries, as CSS properties on its root.
+ *
+ * @param root - the page's root element.
+ * @param search - the page's address's query.
+ */
+export const applySafeArea = (root, search) => {
+    for (const [name, value] of safeAreaProperties(search))
+        root.style.setProperty(name, value);
+};