@tilewise/workbench-client 0.0.0-stage → 0.1.1

package/dist/bridge/revealControl.js

@@ -0,0 +1,62 @@
+/**
+ * Shows what a control changes: after the viewer sets or resets one, the
+ * screen scrolls to the first part on show marked with it
+ * (`data-control="<id> …"`). A control with no marked part scrolls nothing.
+ * A mark may sit on a `display: contents` wrapper; then its first child with
+ * a box is what is shown.
+ */
+const ROOM = 72;
+function boxOf(element) {
+    if (getComputedStyle(element).display !== 'contents') {
+        return element.getClientRects().length > 0 ? element : null;
+    }
+    for (const child of Array.from(element.children)) {
+        const box = boxOf(child);
+        if (box) {
+            return box;
+        }
+    }
+    return null;
+}
+/** The first part marked with the control that is on show; a hidden tab's has no box. */
+export function firstShown(id) {
+    for (const element of document.querySelectorAll(`[data-control~="${CSS.escape(id)}"]`)) {
+        const box = boxOf(element);
+        if (box) {
+            return box;
+        }
+    }
+    return null;
+}
+function scrollerOf(element) {
+    for (let parent = element.parentElement; parent; parent = parent.parentElement) {
+        const { overflowY } = getComputedStyle(parent);
+        if ((overflowY === 'auto' || overflowY === 'scroll') &&
+            parent.scrollHeight > parent.clientHeight) {
+            return parent;
+        }
+    }
+    return null;
+}
+/** A part can ask for more room above it with CSS `scroll-margin-top`. */
+function bring(scroller, target) {
+    const room = Math.max(ROOM, parseFloat(getComputedStyle(target).scrollMarginTop) || 0);
+    const top = scroller.scrollTop +
+        target.getBoundingClientRect().top -
+        scroller.getBoundingClientRect().top -
+        room;
+    const behavior = matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth';
+    scroller.scrollTo({ top: Math.max(0, top), behavior });
+}
+export function revealControl(id) {
+    // Two frames: the change draws first, and a block may only now exist.
+    requestAnimationFrame(() => {
+        return requestAnimationFrame(() => {
+            const part = firstShown(id);
+            const scroller = part && scrollerOf(part);
+            if (part && scroller) {
+                bring(scroller, part);
+            }
+        });
+    });
+}

package/dist/bridge/snapshot.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A picture of the screen as it is now, for the viewer to show on the half of
+ * a foldable that swings; null if it can't be taken. The library that takes
+ * it loads with the first one asked for, so an app that is never folded never
+ * loads it.
+ */
+export declare function snapshot(): Promise<ImageBitmap | null>;

package/dist/bridge/snapshot.js

@@ -0,0 +1,47 @@
+/**
+ * What the picture needs: the elements drawn, and not wholly below or right of
+ * the window. A hidden tab's are most of an app's, and the slowest to copy.
+ */
+function inView(node) {
+    if (!(node instanceof HTMLElement)) {
+        return true;
+    }
+    if (getComputedStyle(node).display === 'none') {
+        return false;
+    }
+    const { top, left } = node.getBoundingClientRect();
+    return top < window.innerHeight && left < window.innerWidth;
+}
+/**
+ * A picture of the screen as it is now, for the viewer to show on the half of
+ * a foldable that swings; null if it can't be taken. The library that takes
+ * it loads with the first one asked for, so an app that is never folded never
+ * loads it.
+ */
+export async function snapshot() {
+    try {
+        const { createContext, domToCanvas } = await import('modern-screenshot');
+        const context = await createContext(document.documentElement, {
+            width: window.innerWidth,
+            height: window.innerHeight,
+            scale: Math.min(2, window.devicePixelRatio),
+            filter: inView,
+            // Images that haven't loaded, such as lazy ones out of view, aren't waited for: the
+            // picture fetches each one it shows itself.
+            timeout: 1,
+            autoDestruct: true,
+            features: {
+                restoreScrollPosition: true,
+                copyScrollbar: false,
+                // Safari's fix draws the picture again for every image in it, a tenth of a second apart.
+                fixSvgXmlDecode: false,
+            },
+        });
+        // Fetching those images and drawing the picture get the time they need.
+        context.timeout = 3000;
+        return await createImageBitmap(await domToCanvas(context));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/bridge/toneAtTop.d.ts

@@ -0,0 +1,3 @@
+import type { Tone } from '../protocol/types.js';
+/** Light or dark: the first solid colour under where the status bar's clock sits. */
+export declare function toneAtTop(): Tone;

package/dist/bridge/toneAtTop.js

@@ -0,0 +1,23 @@
+/** The red, green and blue of a computed colour, when it is mostly opaque. */
+function solid(colour) {
+    const parts = colour.match(/[\d.]+/g);
+    if (!parts || (parts.length >= 4 && Number(parts[3]) <= 0.5)) {
+        return null;
+    }
+    return parts.slice(0, 3).map(Number);
+}
+/** Light or dark: the first solid colour under where the status bar's clock sits. */
+export function toneAtTop() {
+    if (typeof document.elementsFromPoint !== 'function') {
+        return 'light';
+    }
+    const top = parseFloat(getComputedStyle(document.documentElement).getPropertyValue('--safe-top')) || 20;
+    for (const element of document.elementsFromPoint(24, top / 2)) {
+        const rgb = solid(getComputedStyle(element).backgroundColor);
+        if (rgb) {
+            const [red = 0, green = 0, blue = 0] = rgb;
+            return (0.2126 * red + 0.7152 * green + 0.0722 * blue) / 255 < 0.5 ? 'dark' : 'light';
+        }
+    }
+    return 'light';
+}

package/dist/bridge/watchScreen.d.ts

@@ -0,0 +1,10 @@
+import type { AppSays } from '../protocol/types.js';
+type Report = (message: Extract<AppSays, {
+    type: 'tone' | 'height';
+}>) => void;
+/**
+ * Tells the viewer the tone at the top of the screen and, on Full page, the
+ * screen's height, whenever either changes. Returns how to stop.
+ */
+export declare function watchScreen(report: Report): () => void;
+export {};

package/dist/bridge/watchScreen.js

@@ -0,0 +1,50 @@
+import { isWhole, onDeviceChange } from './device.js';
+import { toneAtTop } from './toneAtTop.js';
+import { wholeHeight } from './wholeHeight.js';
+/**
+ * Tells the viewer the tone at the top of the screen and, on Full page, the
+ * screen's height, whenever either changes. Returns how to stop.
+ */
+export function watchScreen(report) {
+    let tone = null;
+    let height = 0;
+    // A timer, not a frame: a frame behind another window never draws, but the viewer still listens.
+    let timer;
+    const check = () => {
+        timer = undefined;
+        const now = toneAtTop();
+        if (now !== tone) {
+            tone = now;
+            report({ type: 'tone', top: now });
+        }
+        if (!isWhole()) {
+            height = 0;
+            return;
+        }
+        const whole = Math.ceil(wholeHeight());
+        if (whole !== height) {
+            height = whole;
+            report({ type: 'height', height: whole });
+        }
+    };
+    const soon = () => {
+        timer ??= setTimeout(check, 50);
+    };
+    onDeviceChange(soon);
+    const mutations = new MutationObserver(soon);
+    mutations.observe(document.body, {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        attributeFilter: ['class', 'style', 'data-workbench-body'],
+    });
+    const resizes = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(soon);
+    resizes?.observe(document.documentElement);
+    soon();
+    return () => {
+        mutations.disconnect();
+        resizes?.disconnect();
+        clearTimeout(timer);
+        onDeviceChange(null);
+    };
+}

package/dist/bridge/wholeHeight.d.ts

@@ -0,0 +1,8 @@
+/**
+ * How tall the window must be for the open screen to show all of it: its
+ * height plus what the open screen's scrolling body hides. The app marks each
+ * screen's scrolling body `data-workbench-body`, and takes the mark off a
+ * screen covered by another; a body with no height, as in a hidden tab, is
+ * skipped.
+ */
+export declare function wholeHeight(): number;

package/dist/bridge/wholeHeight.js

@@ -0,0 +1,16 @@
+/**
+ * How tall the window must be for the open screen to show all of it: its
+ * height plus what the open screen's scrolling body hides. The app marks each
+ * screen's scrolling body `data-workbench-body`, and takes the mark off a
+ * screen covered by another; a body with no height, as in a hidden tab, is
+ * skipped.
+ */
+export function wholeHeight() {
+    let more = 0;
+    for (const body of document.querySelectorAll('[data-workbench-body]')) {
+        if (body.clientHeight > 0) {
+            more = Math.max(more, body.scrollHeight - body.clientHeight);
+        }
+    }
+    return window.innerHeight + more;
+}

package/dist/controls/paint.d.ts

@@ -0,0 +1,8 @@
+import type { Control, Value } from './types.js';
+/**
+ * Writes a global control's value to the root, as `html[data-<id>]`, and a
+ * number or a color also as `--tweak-<id>`, so a pure-CSS tweak needs no code.
+ * Screen and block values are never written here: a component that styles by
+ * one puts it on its own root.
+ */
+export declare function paint(control: Control, value: Value): void;

package/dist/controls/paint.js

@@ -0,0 +1,16 @@
+/**
+ * Writes a global control's value to the root, as `html[data-<id>]`, and a
+ * number or a color also as `--tweak-<id>`, so a pure-CSS tweak needs no code.
+ * Screen and block values are never written here: a component that styles by
+ * one puts it on its own root.
+ */
+export function paint(control, value) {
+    const root = document.documentElement;
+    root.setAttribute(`data-${control.id}`, String(value));
+    if (control.type === 'number') {
+        root.style.setProperty(`--tweak-${control.id}`, String(value));
+    }
+    else if (control.type === 'color') {
+        root.style.setProperty(`--tweak-${control.id}`, `var(--${String(value)})`);
+    }
+}

package/dist/controls/parseValue.d.ts

@@ -0,0 +1,7 @@
+import type { Control, Value } from './types.js';
+/**
+ * A value as it arrives, as text, checked against its control. Anything that
+ * doesn't fit falls back to the default; a number outside its range is
+ * clamped, and text over `maxLength` is cut.
+ */
+export declare function parseValue(control: Control, raw: string | null | undefined): Value;

package/dist/controls/parseValue.js

@@ -0,0 +1,34 @@
+/**
+ * A value as it arrives, as text, checked against its control. Anything that
+ * doesn't fit falls back to the default; a number outside its range is
+ * clamped, and text over `maxLength` is cut.
+ */
+export function parseValue(control, raw) {
+    if (raw === null || raw === undefined) {
+        return control.default;
+    }
+    switch (control.type) {
+        case 'boolean': {
+            if (raw === 'true') {
+                return true;
+            }
+            return raw === 'false' ? false : control.default;
+        }
+        case 'number': {
+            const number = Number(raw);
+            if (raw.trim() === '' || !Number.isFinite(number)) {
+                return control.default;
+            }
+            return Math.min(control.max, Math.max(control.min, number));
+        }
+        case 'variant': {
+            return control.options.some((option) => option.value === raw) ? raw : control.default;
+        }
+        case 'color': {
+            return control.options.some((option) => option.token === raw) ? raw : control.default;
+        }
+        case 'text': {
+            return control.maxLength === undefined ? raw : raw.slice(0, control.maxLength);
+        }
+    }
+}

package/dist/controls/resetControl.d.ts

@@ -0,0 +1,3 @@
+import type { Control, Handle } from './types.js';
+/** Puts a control back to its default, and forgets the value picked. */
+export declare function resetControl<C extends Control>(handle: Handle<C>): void;

package/dist/controls/resetControl.js

@@ -0,0 +1,6 @@
+import { declare, resetValue } from './store.js';
+/** Puts a control back to its default, and forgets the value picked. */
+export function resetControl(handle) {
+    declare(handle);
+    resetValue(handle.id);
+}

package/dist/controls/setControl.d.ts

@@ -0,0 +1,3 @@
+import type { Control, Handle, ValueOf } from './types.js';
+/** Sets a control, as the viewer's `set` does: checked against its declaration first. */
+export declare function setControl<C extends Control>(handle: Handle<C>, value: ValueOf<C>): void;

package/dist/controls/setControl.js

@@ -0,0 +1,6 @@
+import { declare, setValue } from './store.js';
+/** Sets a control, as the viewer's `set` does: checked against its declaration first. */
+export function setControl(handle, value) {
+    declare(handle);
+    setValue(handle.id, value);
+}

package/dist/controls/store.d.ts

@@ -0,0 +1,12 @@
+import type { Handle, Value } from './types.js';
+/** Makes a control known, with its starting value, and returns its value now. */
+export declare function declare(handle: Handle): Value;
+/** Sets a control by its id, checked against its declaration. False for an id nobody declared. */
+export declare function setValue(id: string, raw: Value): boolean;
+/** Puts a control back to its default, by its id. False for an id nobody declared. */
+export declare function resetValue(id: string): boolean;
+/** Puts every control back. */
+export declare function resetAll(): void;
+/** Every control's value, now. The same object until one changes. */
+export declare const valuesNow: () => Readonly<Record<string, Value>>;
+export declare function subscribeValues(listener: () => void): () => void;

package/dist/controls/store.js

@@ -0,0 +1,125 @@
+import { paint } from './paint.js';
+import { parseValue } from './parseValue.js';
+const entries = new Map();
+const listeners = new Set();
+let values = {};
+let listening = false;
+const storageKey = (id) => `control:${id}`;
+const inPage = () => typeof window !== 'undefined';
+function emit() {
+    for (const listener of listeners) {
+        listener();
+    }
+}
+function store(id, value) {
+    try {
+        if (value === null) {
+            localStorage.removeItem(storageKey(id));
+        }
+        else {
+            localStorage.setItem(storageKey(id), String(value));
+        }
+    }
+    catch {
+        // Storage is off, as in some private windows: the value lasts this page only.
+    }
+}
+function startingValue(control) {
+    if (!inPage()) {
+        return control.default;
+    }
+    const linked = new URLSearchParams(window.location.search).get(control.id);
+    if (linked !== null) {
+        const value = parseValue(control, linked);
+        store(control.id, value);
+        return value;
+    }
+    try {
+        return parseValue(control, localStorage.getItem(storageKey(control.id)));
+    }
+    catch {
+        return control.default;
+    }
+}
+function put(id, entry, value) {
+    values = { ...values, [id]: value };
+    if (entry.global && inPage()) {
+        paint(entry.control, value);
+    }
+}
+function followOtherTabs() {
+    if (listening || !inPage()) {
+        return;
+    }
+    listening = true;
+    window.addEventListener('storage', (event) => {
+        if (!event.key?.startsWith('control:')) {
+            return;
+        }
+        const id = event.key.slice('control:'.length);
+        const entry = entries.get(id);
+        if (!entry) {
+            return;
+        }
+        const value = parseValue(entry.control, event.newValue);
+        if (values[id] !== value) {
+            put(id, entry, value);
+            emit();
+        }
+    });
+}
+/** Makes a control known, with its starting value, and returns its value now. */
+export function declare(handle) {
+    const known = values[handle.id];
+    if (known !== undefined) {
+        return known;
+    }
+    const entry = { control: handle.control, global: handle.place.level === 'global' };
+    entries.set(handle.id, entry);
+    put(handle.id, entry, startingValue(handle.control));
+    followOtherTabs();
+    // Known while drawing: everyone who reads every value hears of it next.
+    queueMicrotask(emit);
+    return values[handle.id];
+}
+/** Sets a control by its id, checked against its declaration. False for an id nobody declared. */
+export function setValue(id, raw) {
+    const entry = entries.get(id);
+    if (!entry) {
+        return false;
+    }
+    const value = parseValue(entry.control, String(raw));
+    if (values[id] !== value) {
+        store(id, value);
+        put(id, entry, value);
+        emit();
+    }
+    return true;
+}
+/** Puts a control back to its default, by its id. False for an id nobody declared. */
+export function resetValue(id) {
+    const entry = entries.get(id);
+    if (!entry) {
+        return false;
+    }
+    store(id, null);
+    if (values[id] !== entry.control.default) {
+        put(id, entry, entry.control.default);
+        emit();
+    }
+    return true;
+}
+/** Puts every control back. */
+export function resetAll() {
+    for (const id of entries.keys()) {
+        resetValue(id);
+    }
+}
+/** Every control's value, now. The same object until one changes. */
+export const valuesNow = () => values;
+export function subscribeValues(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}

package/dist/controls/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * A control: one value a reviewer can change from the viewer. There are five
+ * types and no others; the viewer draws one fixed row for each, so a new
+ * control is one more declaration, never new UI.
+ */
+export interface Option {
+    value: string;
+    label: string;
+}
+export interface ColorOption {
+    /** A name from the app's tokens, such as `lime` for `--lime`. */
+    token: string;
+    label: string;
+}
+interface Base {
+    /** Its name in links, storage and messages. Unique across the app, and never renamed. */
+    id: string;
+    /** Its name in the form. */
+    label: string;
+    /** A line the form shows quietly under its row, for a rule its label can't hold. */
+    note?: string;
+}
+export type VariantControl = Base & {
+    type: 'variant';
+    options: readonly Option[];
+    /** One of the options' values. */
+    default: string;
+};
+export type BooleanControl = Base & {
+    type: 'boolean';
+    default: boolean;
+};
+export type NumberControl = Base & {
+    type: 'number';
+    min: number;
+    max: number;
+    step?: number;
+    default: number;
+};
+export type ColorControl = Base & {
+    type: 'color';
+    options: readonly ColorOption[];
+    /** One of the options' tokens. */
+    default: string;
+};
+export type TextControl = Base & {
+    type: 'text';
+    maxLength?: number;
+    default: string;
+};
+export type Control = VariantControl | BooleanControl | NumberControl | ColorControl | TextControl;
+/** A control's value: a string, a number or a boolean. */
+export type Value = string | number | boolean;
+/** The value a control holds, from its declaration: a variant's values as a union. */
+export type ValueOf<C> = C extends {
+    type: 'boolean';
+} ? boolean : C extends {
+    type: 'number';
+} ? number : C extends {
+    type: 'variant';
+    options: readonly (infer O)[];
+} ? O extends {
+    value: infer V extends string;
+} ? V : never : C extends {
+    type: 'color';
+    options: readonly (infer O)[];
+} ? O extends {
+    token: infer T extends string;
+} ? T : never : string;
+/** Where a control shows in the form. */
+export type Level = 'global' | 'screen' | 'block';
+/** Where a control sits: the whole app, one screen, or one block. */
+export type Place = {
+    level: 'global';
+} | {
+    level: 'screen';
+    screen: string;
+} | {
+    level: 'block';
+    block: string;
+};
+/** What a part hands its code for one control: read it with `useControl(handle)`. */
+export interface Handle<C extends Control = Control> {
+    readonly id: string;
+    readonly control: C;
+    readonly place: Place;
+}
+/** The declared shape of a control of the same type as `C`. */
+type ShapeOf<C> = C extends {
+    type: infer T;
+} ? Extract<Control, {
+    type: T;
+}> : Control;
+/** Refuses keys a control's type doesn't have, as `screens`. */
+type NoExtraKeys<C> = Record<Exclude<keyof C, keyof ShapeOf<C>>, never>;
+type ExactOptions<C> = C extends {
+    options: readonly (infer O)[];
+} ? ShapeOf<C> extends {
+    options: readonly (infer S)[];
+} ? {
+    options: readonly (O & Record<Exclude<keyof O, keyof S>, never>)[];
+} : unknown : unknown;
+/**
+ * Each control as declared, held to its type: no keys it doesn't have, and no
+ * option's `short`. A default that isn't one of its values is caught as the
+ * app starts.
+ */
+export type Declared<C extends readonly Control[]> = {
+    [K in keyof C]: C[K] & NoExtraKeys<C[K]> & ExactOptions<C[K]>;
+};
+export {};

package/dist/controls/types.js

@@ -0,0 +1,6 @@
+/**
+ * A control: one value a reviewer can change from the viewer. There are five
+ * types and no others; the viewer draws one fixed row for each, so a new
+ * control is one more declaration, never new UI.
+ */
+export {};

package/dist/controls/useControl.d.ts

@@ -0,0 +1,7 @@
+import type { Control, Handle, ValueOf } from './types.js';
+/**
+ * A control's value, typed by its declaration, drawn again whenever it
+ * changes. A block's control also reports the block as drawn on the screen
+ * of the nearest `<ScreenScope>`, until it unmounts.
+ */
+export declare function useControl<C extends Control>(handle: Handle<C>): ValueOf<C>;

package/dist/controls/useControl.js

@@ -0,0 +1,16 @@
+import { useContext, useEffect, useSyncExternalStore } from 'react';
+import { reportBlock } from '../blocks/drawnBlocks.js';
+import { ScreenContext } from '../blocks/screenContext.js';
+import { declare, subscribeValues } from './store.js';
+/**
+ * A control's value, typed by its declaration, drawn again whenever it
+ * changes. A block's control also reports the block as drawn on the screen
+ * of the nearest `<ScreenScope>`, until it unmounts.
+ */
+export function useControl(handle) {
+    const value = useSyncExternalStore(subscribeValues, () => declare(handle), () => handle.control.default);
+    const screen = useContext(ScreenContext);
+    const block = handle.place.level === 'block' ? handle.place.block : null;
+    useEffect(() => (screen && block ? reportBlock(screen, block) : undefined), [screen, block]);
+    return value;
+}

package/dist/define/buildManifest.d.ts

@@ -0,0 +1,8 @@
+import type { Manifest, Screen } from '../protocol/types.js';
+import { type Part } from './part.js';
+/**
+ * Everything the app has, for the viewer: its screens and states, every
+ * control with where it sits, and every block. A state goes without its jump,
+ * so only the fields the protocol names are copied.
+ */
+export declare function buildManifest(app: string, screens: readonly Screen[], parts: readonly Part[]): Manifest;