@tilewise/workbench-client 0.0.0-stage → 0.1.1

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);
+        }
+    }
+}

package/dist/define/defineBlock.d.ts

@@ -0,0 +1,12 @@
+import type { Control, Declared } from '../controls/types.js';
+import { type Part } from './part.js';
+/**
+ * Declares a block's controls, beside its component. They show in a section
+ * of their own, headed by `label`, on any screen while the block is drawn there.
+ */
+export declare function defineBlock<const C extends readonly Control[]>(declaration: {
+    /** The block's component name. */
+    block: string;
+    label: string;
+    controls: C & NoInfer<Declared<C>>;
+}): Part<C>;

package/dist/define/defineBlock.js

@@ -0,0 +1,10 @@
+import { checkDefaults } from './checkDefaults.js';
+import { makePart } from './part.js';
+/**
+ * Declares a block's controls, beside its component. They show in a section
+ * of their own, headed by `label`, on any screen while the block is drawn there.
+ */
+export function defineBlock(declaration) {
+    checkDefaults(declaration.controls, `block "${declaration.block}"`);
+    return makePart({ level: 'block', block: declaration.block }, declaration.controls, declaration.label);
+}

package/dist/define/defineScreen.d.ts

@@ -0,0 +1,11 @@
+import type { Control, Declared } from '../controls/types.js';
+import { type Part } from './part.js';
+/**
+ * Declares a screen's controls, beside its component. They show in the form
+ * on that screen, in the order given.
+ */
+export declare function defineScreen<const C extends readonly Control[]>(declaration: {
+    /** A screen id from the app's screens. */
+    screen: string;
+    controls: C & NoInfer<Declared<C>>;
+}): Part<C>;

package/dist/define/defineScreen.js

@@ -0,0 +1,10 @@
+import { checkDefaults } from './checkDefaults.js';
+import { makePart } from './part.js';
+/**
+ * Declares a screen's controls, beside its component. They show in the form
+ * on that screen, in the order given.
+ */
+export function defineScreen(declaration) {
+    checkDefaults(declaration.controls, `screen "${declaration.screen}"`);
+    return makePart({ level: 'screen', screen: declaration.screen }, declaration.controls);
+}

package/dist/define/part.d.ts

@@ -0,0 +1,23 @@
+import type { Control, Handle, Place } from '../controls/types.js';
+/** Marks a part, so `defineApp` finds it among a module's exports. */
+export declare const PART: unique symbol;
+export interface PartInfo {
+    place: Place;
+    /** A block's heading in the form. */
+    label?: string;
+    controls: readonly Control[];
+    handles: readonly Handle[];
+}
+/**
+ * One `.workbench.ts` file's controls: the app's, a screen's or a block's.
+ * It holds one handle per control, under its id: `home.homepage`.
+ */
+export type Part<C extends readonly Control[] = readonly Control[]> = {
+    readonly [K in C[number] as K['id']]: Handle<K>;
+} & {
+    readonly [PART]: PartInfo;
+};
+export declare function makePart<C extends readonly Control[]>(place: Place, controls: C, label?: string): Part<C>;
+export declare function isPart(value: unknown): value is Part;
+/** Where a part sits, in words, for the messages the start-up checks throw. */
+export declare function nameOf(info: PartInfo): string;

package/dist/define/part.js

@@ -0,0 +1,22 @@
+/** Marks a part, so `defineApp` finds it among a module's exports. */
+export const PART = Symbol.for('@tilewise/workbench-client/part');
+export function makePart(place, controls, label) {
+    const handles = controls.map((control) => ({ id: control.id, control, place }));
+    const info = { place, controls, handles, ...(label !== undefined && { label }) };
+    const byId = Object.fromEntries(handles.map((handle) => [handle.id, handle]));
+    return Object.assign(byId, { [PART]: info });
+}
+export function isPart(value) {
+    return typeof value === 'object' && value !== null && PART in value;
+}
+/** Where a part sits, in words, for the messages the start-up checks throw. */
+export function nameOf(info) {
+    switch (info.place.level) {
+        case 'global':
+            return 'the app';
+        case 'screen':
+            return `screen "${info.place.screen}"`;
+        case 'block':
+            return `block "${info.place.block}"`;
+    }
+}

package/dist/define/registeredApp.d.ts

@@ -0,0 +1,12 @@
+import type { At, Manifest } from '../protocol/types.js';
+/** The app `defineApp` declared, as the bridge needs it. */
+export interface RegisteredApp {
+    manifest: Manifest;
+    /** The app's navigation, going by state id: false for a state it doesn't have. */
+    useNavigation: () => {
+        at: At;
+        go: (state: string) => boolean;
+    };
+}
+export declare function registerApp(app: RegisteredApp): void;
+export declare const registeredApp: () => RegisteredApp | null;

package/dist/define/registeredApp.js

@@ -0,0 +1,5 @@
+let registered = null;
+export function registerApp(app) {
+    registered = app;
+}
+export const registeredApp = () => registered;

package/dist/draw/boolean.d.ts

@@ -0,0 +1,6 @@
+import { type Case } from './choose.js';
+/** What to draw for a boolean's value: `on` and `off`, both required. */
+export declare function boolean<R>(value: boolean, cases: {
+    on: Case<true, R>;
+    off: Case<false, R>;
+}): R;

package/dist/draw/boolean.js

@@ -0,0 +1,5 @@
+import { choose } from './choose.js';
+/** What to draw for a boolean's value: `on` and `off`, both required. */
+export function boolean(value, cases) {
+    return value ? choose(cases.on, true) : choose(cases.off, false);
+}

package/dist/draw/choose.d.ts

@@ -0,0 +1,4 @@
+/** A case: something to draw, or a function that gets the value and returns it. */
+export type Case<V, R> = R | ((value: V) => R);
+/** The case's result for a value. */
+export declare function choose<V, R>(found: Case<V, R> | undefined, value: V): R;

package/dist/draw/choose.js

@@ -0,0 +1,4 @@
+/** The case's result for a value. */
+export function choose(found, value) {
+    return typeof found === 'function' ? found(value) : found;
+}

package/dist/draw/color.d.ts

@@ -0,0 +1,2 @@
+/** A color's token as a CSS value, for a `style`: `color('lime')` is `'var(--lime)'`. */
+export declare function color<T extends string>(token: T): `var(--${T})`;

package/dist/draw/color.js

@@ -0,0 +1,4 @@
+/** A color's token as a CSS value, for a `style`: `color('lime')` is `'var(--lime)'`. */
+export function color(token) {
+    return `var(--${token})`;
+}

package/dist/draw/number.d.ts

@@ -0,0 +1,5 @@
+import { type Case } from './choose.js';
+/** What to draw for a number: any exact numbers, and `other`, required, for the rest. */
+export declare function number<R>(value: number, cases: Readonly<Record<number, Case<number, R>>> & {
+    other: Case<number, R>;
+}): R;

package/dist/draw/number.js

@@ -0,0 +1,5 @@
+import { choose } from './choose.js';
+/** What to draw for a number: any exact numbers, and `other`, required, for the rest. */
+export function number(value, cases) {
+    return choose(Object.hasOwn(cases, String(value)) ? cases[value] : cases.other, value);
+}

package/dist/draw/text.d.ts

@@ -0,0 +1,5 @@
+import { type Case } from './choose.js';
+/** What to draw for a line of text: any exact lines, and `other`, required, for the rest. */
+export declare function text<R>(value: string, cases: Readonly<Record<string, Case<string, R>>> & {
+    other: Case<string, R>;
+}): R;

package/dist/draw/text.js

@@ -0,0 +1,5 @@
+import { choose } from './choose.js';
+/** What to draw for a line of text: any exact lines, and `other`, required, for the rest. */
+export function text(value, cases) {
+    return choose(value !== 'other' && Object.hasOwn(cases, value) ? cases[value] : cases.other, value);
+}

package/dist/draw/variant.d.ts

@@ -0,0 +1,17 @@
+import { type Case } from './choose.js';
+type EveryCase<V extends string, R> = {
+    [K in V]: Case<K, R>;
+};
+/** Some options, and `other` for the rest: its function gets them without the ones listed. */
+type SomeCases<V extends string, L extends string, R> = {
+    [K in L]: K extends 'other' ? Case<Exclude<V, L>, R> : Case<K, R>;
+} & {
+    other: unknown;
+};
+/**
+ * What to draw for a variant's value. A call without `other` lists every
+ * option, so a new option is a type error until every such call handles it.
+ */
+export declare function variant<V extends string, R>(value: V, cases: EveryCase<V, R>): R;
+export declare function variant<V extends string, L extends V | 'other', R>(value: V, cases: SomeCases<V, L, R>): R;
+export {};

package/dist/draw/variant.js

@@ -0,0 +1,4 @@
+import { choose } from './choose.js';
+export function variant(value, cases) {
+    return choose(Object.hasOwn(cases, value) ? cases[value] : cases['other'], value);
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { ScreenScope } from './blocks/ScreenScope.js';
+export { Bridge } from './bridge/Bridge.js';
+export { resetControl } from './controls/resetControl.js';
+export { setControl } from './controls/setControl.js';
+export type { BooleanControl, ColorControl, ColorOption, Control, Handle, Level, NumberControl, Option, Place, TextControl, Value, ValueOf, VariantControl, } from './controls/types.js';
+export { useControl } from './controls/useControl.js';
+export { defineApp } from './define/defineApp.js';
+export { defineBlock } from './define/defineBlock.js';
+export { defineScreen } from './define/defineScreen.js';
+export type { Part } from './define/part.js';
+export { boolean } from './draw/boolean.js';
+export type { Case } from './draw/choose.js';
+export { color } from './draw/color.js';
+export { number } from './draw/number.js';
+export { text } from './draw/text.js';
+export { variant } from './draw/variant.js';
+export { PROTOCOL } from './protocol/protocol.js';
+export type { AppMessage, AppSays, At, DeviceMessage, Manifest, ManifestBlock, ManifestControl, Navigation, Screen, State, StateKind, Tone, ViewerMessage, ViewerSays, } from './protocol/types.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+export { ScreenScope } from './blocks/ScreenScope.js';
+export { Bridge } from './bridge/Bridge.js';
+export { resetControl } from './controls/resetControl.js';
+export { setControl } from './controls/setControl.js';
+export { useControl } from './controls/useControl.js';
+export { defineApp } from './define/defineApp.js';
+export { defineBlock } from './define/defineBlock.js';
+export { defineScreen } from './define/defineScreen.js';
+export { boolean } from './draw/boolean.js';
+export { color } from './draw/color.js';
+export { number } from './draw/number.js';
+export { text } from './draw/text.js';
+export { variant } from './draw/variant.js';
+export { PROTOCOL } from './protocol/protocol.js';

package/dist/protocol/protocol.d.ts

@@ -0,0 +1,8 @@
+/** The protocol this package speaks. */
+export declare const PROTOCOL = 4;
+/**
+ * Every message carries `source`, for every app, as builds from before the
+ * package send them. Each side ignores any message without the other's tag.
+ */
+export declare const FROM_APP = "aitems";
+export declare const FROM_VIEWER = "aitems-workbench";

package/dist/protocol/protocol.js

@@ -0,0 +1,8 @@
+/** The protocol this package speaks. */
+export const PROTOCOL = 4;
+/**
+ * Every message carries `source`, for every app, as builds from before the
+ * package send them. Each side ignores any message without the other's tag.
+ */
+export const FROM_APP = 'aitems';
+export const FROM_VIEWER = 'aitems-workbench';

package/dist/protocol/types.d.ts

@@ -0,0 +1,144 @@
+import type { Control, Value } from '../controls/types.js';
+/**
+ * Protocol 4: what the app and the viewer say to each other through
+ * `postMessage`, between the frame and the page around it. Any change to a
+ * message or to the manifest bumps the protocol, so the viewer can still read
+ * older builds.
+ */
+export type StateKind = 'state' | 'sheet' | 'overlay';
+/** One place on a screen. The app knows how to get there; the viewer only names it. */
+export interface State {
+    /** Unique across the app, and never renamed. */
+    id: string;
+    label: string;
+    kind?: StateKind;
+    note?: string;
+    /** Only while the screen's `statesBy` control has one of these values. */
+    when?: readonly string[];
+}
+export interface Screen<S extends State = State> {
+    id: string;
+    label: string;
+    /** Two letters, for narrow lists. */
+    short: string;
+    /** The screen it sits under in the route tree. */
+    parent?: string;
+    /** The tab-bar tab it is the root of. */
+    tab?: string;
+    /** A heading that holds screens, with no states of its own. */
+    group?: boolean;
+    /** A page pushed from several screens. */
+    page?: boolean;
+    /** Where it opens from, in words. */
+    where?: string;
+    /** A control id: which states it has depends on that value. */
+    statesBy?: string;
+    /** The source files that draw it; a folder ends in `/`. */
+    files?: readonly string[];
+    states: readonly S[];
+}
+/** A control as declared, with where it sits. */
+export type ManifestControl = Control & ({
+    level: 'global';
+} | {
+    level: 'screen';
+    screen: string;
+} | {
+    level: 'block';
+    block: string;
+});
+export interface ManifestBlock {
+    /** The component's name. */
+    id: string;
+    /** Its section's heading in the form. */
+    label: string;
+    /** Its controls' ids, in order. */
+    controls: string[];
+}
+/** Everything the app has, sent once with `hello`. A state goes without its jump. */
+export interface Manifest {
+    /** Whose build this is, such as `aitems`. */
+    app: string;
+    screens: Screen[];
+    controls: ManifestControl[];
+    blocks: ManifestBlock[];
+}
+export type Tone = 'light' | 'dark';
+/** What the app says. */
+export type AppSays = {
+    type: 'hello';
+    protocol: 4;
+    manifest: Manifest;
+} | {
+    type: 'at';
+    screen: string;
+    state: string | null;
+} | {
+    type: 'blocks';
+    screen: string;
+    blocks: string[];
+} | {
+    type: 'values';
+    values: Record<string, Value>;
+} | {
+    type: 'tone';
+    top: Tone;
+} | {
+    type: 'height';
+    height: number;
+}
+/** The screen as it was when asked, at up to twice its size; null when it couldn't be taken. */
+ | {
+    type: 'snapshot';
+    id: number;
+    image: ImageBitmap | null;
+};
+/** What the app says, as sent: tagged `source: 'aitems'`. */
+export type AppMessage = {
+    source: 'aitems';
+} & AppSays;
+export interface DeviceMessage {
+    type: 'device';
+    /** What the status bar and the home indicator take, in px. */
+    insets: {
+        top: number;
+        bottom: number;
+    };
+    platform: 'ios' | 'android' | null;
+    /** Full page: no device, and the frame as tall as the open screen. */
+    whole: boolean;
+}
+/** What the viewer says. */
+export type ViewerSays = {
+    type: 'hello';
+} | DeviceMessage | {
+    type: 'go';
+    state: string;
+} | {
+    type: 'set';
+    id: string;
+    value: Value;
+} | {
+    type: 'reset';
+    id?: string;
+}
+/** A picture of the screen as it is now, answered with the same `id`. */
+ | {
+    type: 'snapshot';
+    id: number;
+};
+/** What the viewer says, as sent: tagged `source: 'aitems-workbench'`. */
+export type ViewerMessage = {
+    source: 'aitems-workbench';
+} & ViewerSays;
+/** Where the app is now. */
+export interface At {
+    screen: string;
+    state: string | null;
+}
+/** How the package moves the app, and learns where it is. */
+export interface Navigation<S extends State = State> {
+    /** Make the jump the state describes. */
+    go: (state: S) => void;
+    at: At;
+}

package/dist/protocol/types.js

@@ -0,0 +1 @@
+export {};

package/dist/vite/apiFetch.d.ts

@@ -0,0 +1,7 @@
+/** What a fake API answers with: the standard fetch handler, as Hono and most servers give one. */
+export type ApiFetch = (request: Request) => Response | Promise<Response>;
+/**
+ * The fetch handler of a fake API's module: its default export, either the
+ * function itself or an object with `fetch`.
+ */
+export declare function apiFetchOf(module: unknown): ApiFetch;

package/dist/vite/apiFetch.js

@@ -0,0 +1,15 @@
+/**
+ * The fetch handler of a fake API's module: its default export, either the
+ * function itself or an object with `fetch`.
+ */
+export function apiFetchOf(module) {
+    const api = module?.default;
+    if (typeof api === 'function') {
+        return api;
+    }
+    const fetch = api?.fetch;
+    if (typeof fetch === 'function') {
+        return fetch.bind(api);
+    }
+    throw new Error('The fake API has no default export with fetch');
+}

package/dist/vite/apiWorkers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Each build's fake API, run in a worker of its own: loaded on its first
+ * request, kept while it is asked things, so a visit's data stays, and stopped
+ * after `idle` with nothing asked, which frees its memory. A worker gets no
+ * environment, so a bundle sees none of the dev server's settings.
+ */
+export declare function createApiWorkers(idle?: number): {
+    answer: (key: string, file: string, request: Request) => Promise<Response>;
+    loaded: () => string[];
+    stopAll: () => void;
+};