@tilewise/workbench-client 0.0.0-stage → 0.1.0

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;

package/dist/define/buildManifest.js

@@ -0,0 +1,51 @@
+import { 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 function buildManifest(app, screens, parts) {
+    const controls = parts.flatMap((part) => {
+        const { place, controls: declared } = part[PART];
+        return declared.map((control) => ({ ...control, ...place }));
+    });
+    const blocks = parts.flatMap((part) => {
+        const { place, label, controls: declared } = part[PART];
+        return place.level === 'block'
+            ? [
+                {
+                    id: place.block,
+                    label: label ?? place.block,
+                    controls: declared.map((control) => control.id),
+                },
+            ]
+            : [];
+    });
+    return { app, screens: screens.map(screenOf), controls, blocks };
+}
+function screenOf(screen) {
+    const { id, label, short, parent, tab, group, page, where, statesBy, files } = screen;
+    return {
+        id,
+        label,
+        short,
+        ...(parent !== undefined && { parent }),
+        ...(tab !== undefined && { tab }),
+        ...(group !== undefined && { group }),
+        ...(page !== undefined && { page }),
+        ...(where !== undefined && { where }),
+        ...(statesBy !== undefined && { statesBy }),
+        ...(files !== undefined && { files: [...files] }),
+        states: screen.states.map(stateOf),
+    };
+}
+function stateOf(state) {
+    const { id, label, kind, note, when } = state;
+    return {
+        id,
+        label,
+        ...(kind !== undefined && { kind }),
+        ...(note !== undefined && { note }),
+        ...(when !== undefined && { when: [...when] }),
+    };
+}

package/dist/define/checkDefaults.d.ts

@@ -0,0 +1,3 @@
+import type { Control } from '../controls/types.js';
+/** Throws on a `default` that isn't one of the options, or a number's outside `min` and `max`. */
+export declare function checkDefaults(controls: readonly Control[], where: string): void;

package/dist/define/checkDefaults.js

@@ -0,0 +1,29 @@
+/** Throws on a `default` that isn't one of the options, or a number's outside `min` and `max`. */
+export function checkDefaults(controls, where) {
+    for (const control of controls) {
+        const fault = faultOf(control);
+        if (fault) {
+            throw new Error(`workbench-client: in ${where}, the default of "${control.id}" ${fault}.`);
+        }
+    }
+}
+function faultOf(control) {
+    switch (control.type) {
+        case 'variant':
+            return control.options.some((option) => option.value === control.default)
+                ? null
+                : `("${control.default}") isn't one of its options`;
+        case 'color':
+            return control.options.some((option) => option.token === control.default)
+                ? null
+                : `("${control.default}") isn't one of its tokens`;
+        case 'number':
+            return control.default >= control.min && control.default <= control.max
+                ? null
+                : `(${control.default}) is outside ${control.min} to ${control.max}`;
+        case 'boolean':
+            return typeof control.default === 'boolean' ? null : "isn't true or false";
+        case 'text':
+            return typeof control.default === 'string' ? null : "isn't text";
+    }
+}

package/dist/define/defineApp.d.ts

@@ -0,0 +1,24 @@
+import type { Control, Declared } from '../controls/types.js';
+import type { Navigation, Screen, State } from '../protocol/types.js';
+import { type Part } from './part.js';
+/**
+ * Declares the app: its name, its screens and how to move between them,
+ * every other part, and the global controls, which show on every page. An
+ * app has exactly one, beside its root component.
+ *
+ * `parts` is every module that holds a part, as `import.meta.glob` gives
+ * them, so each loads as the app starts and the manifest and the first
+ * `values` hold every control. As it starts, the app throws on two controls
+ * with one id, two blocks with one name, a screen id that isn't in `screens`,
+ * a bad default, or a second `defineApp`.
+ */
+export declare function defineApp<S extends State, const C extends readonly Control[]>(declaration: {
+    /** The app's name in the manifest, such as `aitems`. */
+    app: string;
+    /** Every screen and its states, each state with the jump that gets there. */
+    screens: readonly Screen<S>[];
+    /** A hook: how to go to a state, and where the app is now. */
+    useNavigation: () => Navigation<S>;
+    parts: Readonly<Record<string, unknown>>;
+    controls: C & NoInfer<Declared<C>>;
+}): Part<C>;

package/dist/define/defineApp.js

@@ -0,0 +1,92 @@
+import { declare } from '../controls/store.js';
+import { buildManifest } from './buildManifest.js';
+import { checkDefaults } from './checkDefaults.js';
+import { isPart, makePart, nameOf, PART } from './part.js';
+import { registerApp, registeredApp } from './registeredApp.js';
+/**
+ * Declares the app: its name, its screens and how to move between them,
+ * every other part, and the global controls, which show on every page. An
+ * app has exactly one, beside its root component.
+ *
+ * `parts` is every module that holds a part, as `import.meta.glob` gives
+ * them, so each loads as the app starts and the manifest and the first
+ * `values` hold every control. As it starts, the app throws on two controls
+ * with one id, two blocks with one name, a screen id that isn't in `screens`,
+ * a bad default, or a second `defineApp`.
+ */
+export function defineApp(declaration) {
+    if (registeredApp()) {
+        throw new Error('workbench-client: defineApp was called a second time; an app has exactly one.');
+    }
+    checkDefaults(declaration.controls, 'the app');
+    const global = makePart({ level: 'global' }, declaration.controls);
+    const parts = [global, ...partsIn(declaration.parts)];
+    checkParts(parts, new Set(declaration.screens.map((screen) => screen.id)));
+    for (const part of parts) {
+        for (const handle of part[PART].handles) {
+            declare(handle);
+        }
+    }
+    const states = new Map();
+    for (const screen of declaration.screens) {
+        for (const state of screen.states) {
+            states.set(state.id, state);
+        }
+    }
+    registerApp({
+        manifest: buildManifest(declaration.app, declaration.screens, parts),
+        useNavigation: () => {
+            const navigation = declaration.useNavigation();
+            return {
+                at: navigation.at,
+                go: (id) => {
+                    const state = states.get(id);
+                    if (state) {
+                        navigation.go(state);
+                    }
+                    return state !== undefined;
+                },
+            };
+        },
+    });
+    return global;
+}
+/** Every part among the modules' exports, each once. */
+function partsIn(modules) {
+    const found = new Set();
+    for (const module of Object.values(modules)) {
+        if (typeof module !== 'object' || module === null) {
+            continue;
+        }
+        for (const value of Object.values(module)) {
+            if (isPart(value)) {
+                found.add(value);
+            }
+        }
+    }
+    return [...found];
+}
+function checkParts(parts, screens) {
+    const ids = new Map();
+    const blocks = new Set();
+    for (const part of parts) {
+        const info = part[PART];
+        const where = nameOf(info);
+        if (info.place.level === 'screen' && !screens.has(info.place.screen)) {
+            throw new Error(`workbench-client: ${where} isn't one of the app's screens.`);
+        }
+        if (info.place.level === 'block') {
+            if (blocks.has(info.place.block)) {
+                throw new Error(`workbench-client: two blocks are named "${info.place.block}".`);
+            }
+            blocks.add(info.place.block);
+        }
+        for (const control of info.controls) {
+            const first = ids.get(control.id);
+            if (first !== undefined) {
+                throw new Error(`workbench-client: two controls have the id "${control.id}", in ${first} and in ${where}.`);
+            }
+            ids.set(control.id, where);
+        }
+    }
+}