@trypattern/sdk 0.0.0-stage → 0.1.0

package/dist/flows/flowBrowser.d.ts

@@ -0,0 +1,23 @@
+import type { ViewportName } from './browser.ts';
+export type VisualFlowSettings = {
+    url: string;
+    wsEndpoint: string;
+    directory: string;
+    viewports: readonly ViewportName[];
+};
+declare module 'vitest' {
+    interface ProvidedContext {
+        patternVisualFlows?: VisualFlowSettings;
+    }
+}
+export declare function closeFlowBrowser(): Promise<void>;
+export declare function openFlowPage(settings: VisualFlowSettings, viewport: ViewportName, startAt: string, signedInAs: string | null, seed: object, admins: readonly string[]): Promise<{
+    send: (command: unknown) => Promise<void>;
+    snapshot: () => Promise<unknown>;
+    hold: (call: string) => Promise<void>;
+    release: (call: string) => Promise<void>;
+    reload: (path: string) => Promise<void>;
+    screenshot: (name: string) => Promise<void>;
+    problems: string[];
+    close: () => Promise<void>;
+}>;

package/dist/flows/flowBrowser.js

@@ -0,0 +1,21 @@
+import { connectChrome, openApp } from "./browser.js";
+let browser;
+export async function closeFlowBrowser() {
+    const connected = browser;
+    browser = undefined;
+    await (await connected)?.close();
+}
+export async function openFlowPage(settings, viewport, startAt, signedInAs, seed, admins) {
+    browser ??= connectChrome(settings.wsEndpoint);
+    const app = await openApp(await browser, settings.url, startAt, viewport, signedInAs, seed, admins);
+    return {
+        send: app.dispatch,
+        snapshot: app.snapshot,
+        hold: app.hold,
+        release: app.release,
+        reload: app.reload,
+        screenshot: (name) => app.screenshot(`${settings.directory}/${name}-${viewport}.png`),
+        problems: app.problems,
+        close: app.close
+    };
+}

package/dist/flows/flowSetup.d.ts

@@ -0,0 +1,3 @@
+import type { TestProject } from 'vitest/node';
+export declare function setup(project: TestProject): Promise<void>;
+export declare function teardown(): Promise<void>;

package/dist/flows/flowSetup.js

@@ -0,0 +1,35 @@
+import { mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { launchChromeServer, viewportNames } from "./browser.js";
+import { writeContactSheet } from "./contactSheet.js";
+const ROOT = process.cwd();
+const SCREENSHOTS_DIRECTORY = join(ROOT, '.dev', 'screenshots');
+const FLOW_SCREENSHOTS_DIRECTORY = join(SCREENSHOTS_DIRECTORY, 'flows');
+const CONTACT_SHEET = join(SCREENSHOTS_DIRECTORY, 'contact-sheet.png');
+let server;
+export async function setup(project) {
+    const url = process.env['PATTERN_VISUAL_URL'];
+    if (url === undefined) {
+        throw new Error('Visual flows need the dev server: run `app test --visual`');
+    }
+    rmSync(FLOW_SCREENSHOTS_DIRECTORY, { recursive: true, force: true });
+    rmSync(CONTACT_SHEET, { force: true });
+    mkdirSync(FLOW_SCREENSHOTS_DIRECTORY, { recursive: true });
+    server = await launchChromeServer();
+    project.provide('patternVisualFlows', {
+        url,
+        wsEndpoint: server.wsEndpoint(),
+        directory: FLOW_SCREENSHOTS_DIRECTORY,
+        viewports: viewportNames
+    });
+}
+export async function teardown() {
+    if (server === undefined)
+        return;
+    try {
+        await writeContactSheet(server.wsEndpoint(), FLOW_SCREENSHOTS_DIRECTORY, CONTACT_SHEET);
+    }
+    finally {
+        await server.close();
+    }
+}

package/dist/flows/flows.d.ts

@@ -0,0 +1,41 @@
+import { expect } from 'vitest';
+import type { ApiCall } from '../api.ts';
+import type { AppClass, RunningApp } from '../app.ts';
+import type { Seed, Tables } from '../table.ts';
+export { expect };
+export { accessFlows } from './accessFlows.ts';
+declare module 'vitest' {
+    interface ProvidedContext {
+        patternSeed?: Seed<Tables>;
+        patternAdmins?: readonly string[];
+    }
+}
+type Expected<Value> = Value extends readonly (infer Item)[] ? readonly Expected<Item>[] : Value extends object ? {
+    [Key in keyof Value]?: Expected<Value[Key]>;
+} : Value;
+export type FlowStep<Command, Snapshot, Call extends string> = {
+    send: Command;
+} | {
+    expect: Expected<Snapshot> & object;
+} | {
+    screenshot: string;
+} | {
+    hold: Call;
+} | {
+    release: Call;
+} | {
+    restart: true;
+};
+export type FlowOptions<Call extends string> = {
+    startAt?: string;
+    failing?: readonly Call[];
+    signedInAs?: string | null;
+};
+export type FlowBinding<Group extends Tables, Command, Snapshot extends {
+    readonly path: string;
+}> = {
+    App: AppClass<Group, RunningApp<Command, Snapshot>>;
+};
+export declare function defineFlow<Group extends Tables, Command, Snapshot extends {
+    readonly path: string;
+}>({ App }: FlowBinding<Group, Command, Snapshot>): (name: string, steps: readonly FlowStep<Command, Snapshot, ApiCall<Group>>[], { startAt, failing, signedInAs }?: FlowOptions<ApiCall<Group>>) => void;

package/dist/flows/flows.js

@@ -0,0 +1,148 @@
+import { createMemoryRouter } from 'react-router';
+import { afterAll, expect, inject, test } from 'vitest';
+import { apiCalls, memoryApi } from "../api.js";
+import { Cache } from "../cache.js";
+import { Gate } from "../gate.js";
+import { routeObjects } from "../routes.js";
+import { screenshotNameProblem } from "./screenshotName.js";
+export { expect };
+export { accessFlows } from "./accessFlows.js";
+const DEFAULT_USER = 'ada@acme.test';
+const screenshotNamesInThisFile = new Set();
+let closesBrowserAfterThisFile = false;
+function checkSteps(steps, calls) {
+    for (const step of steps) {
+        for (const key of ['hold', 'release']) {
+            const call = Reflect.get(step, key);
+            if (typeof call === 'string' && !calls.includes(call)) {
+                throw new Error(`{ ${key}: '${call}' } names no server call. Calls: ${calls.join(', ')}`);
+            }
+        }
+        const name = Reflect.get(step, 'screenshot');
+        if (typeof name !== 'string')
+            continue;
+        const problem = screenshotNameProblem(name);
+        if (problem !== undefined)
+            throw new Error(problem);
+        if (screenshotNamesInThisFile.has(name)) {
+            throw new Error(`Screenshot name "${name}" is used twice; each screenshot step needs its own name.`);
+        }
+        screenshotNamesInThisFile.add(name);
+    }
+}
+async function runSteps(name, steps, run) {
+    for (const [index, step] of steps.entries()) {
+        if ('send' in step) {
+            await run.send(step.send);
+        }
+        else if ('screenshot' in step) {
+            await run.screenshot(step.screenshot);
+        }
+        else if ('hold' in step) {
+            await run.hold(step.hold);
+        }
+        else if ('release' in step) {
+            await run.release(step.release);
+        }
+        else if ('restart' in step) {
+            await run.restart();
+        }
+        else {
+            expect(await run.snapshot(), `step ${index + 1} of "${name}": expected ${JSON.stringify(step.expect)}`).toMatchObject(step.expect);
+        }
+    }
+}
+function withTestParams(path, failing, held) {
+    const params = new URLSearchParams([
+        ['memory', ''],
+        ...failing.map((call) => ['fail', call]),
+        ...[...held].map((call) => ['hold', call])
+    ]);
+    return `${path}?${params.toString()}`;
+}
+export function defineFlow({ App }) {
+    const { tables, routes } = App.definition;
+    const seed = (inject('patternSeed') ?? {});
+    const admins = inject('patternAdmins') ?? [];
+    const calls = apiCalls(tables);
+    const router = (path) => createMemoryRouter(routeObjects(routes), { initialEntries: [path] });
+    function headless(name, steps, startAt, failing, signedInAs) {
+        test(name, async () => {
+            const gate = new Gate(failing);
+            const deps = {
+                api: memoryApi(tables, seed, { gate, signedInAs, admins }),
+                cache: Cache.memory(),
+                gate
+            };
+            let app = new App(router(startAt), deps);
+            await runSteps(name, steps, {
+                send: async (command) => void app.send(command),
+                snapshot: async () => {
+                    await app.whenIdle();
+                    return app.getSnapshot();
+                },
+                screenshot: async () => undefined,
+                hold: async (call) => gate.hold(call),
+                release: async (call) => gate.release(call),
+                restart: async () => {
+                    app = new App(router(app.getSnapshot().path), deps);
+                }
+            });
+            await app.whenIdle();
+        });
+    }
+    return function flow(name, steps, { startAt = '/', failing = [], signedInAs = DEFAULT_USER } = {}) {
+        checkSteps(steps, calls);
+        const visual = inject('patternVisualFlows');
+        if (visual === undefined) {
+            headless(name, steps, startAt, failing, signedInAs);
+            return;
+        }
+        if (!closesBrowserAfterThisFile) {
+            closesBrowserAfterThisFile = true;
+            afterAll(async () => {
+                const { closeFlowBrowser } = await import("./flowBrowser.js");
+                await closeFlowBrowser();
+            });
+        }
+        for (const viewport of visual.viewports) {
+            test(`${name} [${viewport}]`, async () => {
+                const { openFlowPage } = await import("./flowBrowser.js");
+                const held = new Set();
+                const page = await openFlowPage(visual, viewport, withTestParams(startAt, failing, held), signedInAs, seed, admins);
+                let stepFailure;
+                try {
+                    await runSteps(name, steps, {
+                        send: page.send,
+                        snapshot: page.snapshot,
+                        screenshot: page.screenshot,
+                        hold: async (call) => {
+                            held.add(call);
+                            await page.hold(call);
+                        },
+                        release: async (call) => {
+                            held.delete(call);
+                            await page.release(call);
+                        },
+                        restart: async () => {
+                            const snapshot = await page.snapshot();
+                            const path = typeof snapshot === 'object' && snapshot !== null
+                                ? Reflect.get(snapshot, 'path')
+                                : undefined;
+                            await page.reload(withTestParams(typeof path === 'string' ? path : startAt, failing, held));
+                        }
+                    });
+                }
+                catch (error) {
+                    stepFailure = error;
+                }
+                finally {
+                    await page.close();
+                }
+                expect(page.problems, `"${name}" [${viewport}] logged errors in the browser; fix them`).toEqual([]);
+                if (stepFailure !== undefined)
+                    throw stepFailure;
+            });
+        }
+    };
+}

package/dist/flows/screenshotName.d.ts

@@ -0,0 +1 @@
+export declare function screenshotNameProblem(name: string): string | undefined;

package/dist/flows/screenshotName.js

@@ -0,0 +1,6 @@
+const KEBAB_CASE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export function screenshotNameProblem(name) {
+    return KEBAB_CASE.test(name)
+        ? undefined
+        : `Screenshot name "${name}" must be kebab-case (lowercase letters, digits and dashes), like "settings" or "sidebar-drawer": it becomes the PNG file name.`;
+}

package/dist/gate.d.ts

@@ -0,0 +1,8 @@
+export declare class Gate {
+    #private;
+    constructor(failing?: readonly string[]);
+    pass<Value>(call: string, run: () => Promise<Value>): Promise<Value>;
+    hold(call: string): void;
+    release(call: string): void;
+    whenIdle(): Promise<void>;
+}

package/dist/gate.js

@@ -0,0 +1,52 @@
+function nextMacrotask() {
+    return new Promise((done) => setTimeout(done, 0));
+}
+export class Gate {
+    #failing;
+    #holds = new Map();
+    #active = 0;
+    #waiting = [];
+    constructor(failing = []) {
+        this.#failing = failing;
+    }
+    async pass(call, run) {
+        if (this.#failing.includes(call))
+            throw new Error(`${call} failed`);
+        this.#active += 1;
+        const value = await run().finally(() => {
+            this.#active -= 1;
+            this.#wakeIfIdle();
+        });
+        await this.#holds.get(call)?.opened;
+        return value;
+    }
+    hold(call) {
+        if (this.#holds.has(call))
+            return;
+        let open = () => { };
+        const opened = new Promise((resolve) => {
+            open = resolve;
+        });
+        this.#holds.set(call, { opened, open });
+    }
+    release(call) {
+        this.#holds.get(call)?.open();
+        this.#holds.delete(call);
+    }
+    async whenIdle() {
+        do {
+            if (this.#active > 0) {
+                await new Promise((wake) => this.#waiting.push(wake));
+            }
+            await nextMacrotask();
+        } while (this.#active > 0);
+    }
+    #wakeIfIdle() {
+        if (this.#active > 0)
+            return;
+        const woken = this.#waiting;
+        this.#waiting = [];
+        for (const wake of woken)
+            wake();
+    }
+}

package/dist/hooks/appContext.d.ts

@@ -0,0 +1,14 @@
+import type { Toasts } from '../builtins/Toasts.ts';
+import type { AppModels } from '../registered.ts';
+import type { AppProviderOf, UseModel } from './appHooks.ts';
+export type ReactApp = {
+    readonly name: string;
+    readonly models: AppModels;
+    readonly stores: {
+        readonly toasts: Toasts;
+    };
+    pressKey(key: string): Promise<void> | undefined;
+};
+export declare const AppProvider: AppProviderOf<ReactApp>;
+export declare const useApp: () => ReactApp;
+export declare const useModel: UseModel<AppModels>;

package/dist/hooks/appContext.js

@@ -0,0 +1,5 @@
+import { createAppHooks } from "./appHooks.js";
+const hooks = createAppHooks();
+export const AppProvider = hooks.AppProvider;
+export const useApp = hooks.useApp;
+export const useModel = hooks.useModel;

package/dist/hooks/appHooks.d.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react';
+import type { PublishedOf } from '../model.ts';
+type PublishingModel = {
+    readonly subscribe: (listener: () => void) => () => void;
+    readonly published: object;
+};
+type AppLike = {
+    readonly models: Readonly<Record<string, PublishingModel>>;
+    pressKey(key: string): Promise<void> | undefined;
+};
+export type UseModel<Models> = <Name extends keyof Models & string>(name: Name) => PublishedOf<Models[Name]>;
+export type AppProviderOf<App> = (props: {
+    app: App;
+    children: ReactNode;
+}) => ReactNode;
+export declare function createAppHooks<App extends AppLike>(): {
+    AppProvider: AppProviderOf<App>;
+    useApp: () => App;
+    useModel: UseModel<App['models']>;
+};
+export {};

package/dist/hooks/appHooks.js

@@ -0,0 +1,24 @@
+import { createContext, createElement, use, useSyncExternalStore } from 'react';
+import { useShortcuts } from "../shortcuts.js";
+export function createAppHooks() {
+    const AppContext = createContext(null);
+    function useApp() {
+        const app = use(AppContext);
+        if (app === null) {
+            throw new Error('Pattern hooks must be used inside <AppProvider>');
+        }
+        return app;
+    }
+    function useModel(name) {
+        const model = useApp().models[name];
+        if (model === undefined)
+            throw new Error(`There is no model named ${name}`);
+        const read = () => model.published;
+        return useSyncExternalStore(model.subscribe, read, read);
+    }
+    function AppProvider({ app, children }) {
+        useShortcuts((key) => app.pressKey(key));
+        return createElement(AppContext, { value: app }, children);
+    }
+    return { AppProvider, useApp, useModel };
+}

package/dist/hooks/useAnimatesOnChange.d.ts

@@ -0,0 +1 @@
+export declare function useAnimatesOnChange(value: unknown, durationMs: number): boolean;

package/dist/hooks/useAnimatesOnChange.js

@@ -0,0 +1,14 @@
+import { useEffect, useState } from 'react';
+export function useAnimatesOnChange(value, durationMs) {
+    const [tracked, setTracked] = useState({ value, isAnimating: false });
+    if (tracked.value !== value) {
+        setTracked({ value, isAnimating: true });
+    }
+    useEffect(() => {
+        if (!tracked.isAnimating)
+            return undefined;
+        const timer = setTimeout(() => setTracked((current) => ({ ...current, isAnimating: false })), durationMs);
+        return () => clearTimeout(timer);
+    }, [tracked, durationMs]);
+    return tracked.isAnimating || tracked.value !== value;
+}

package/dist/hooks/useStoreState.d.ts

@@ -0,0 +1,6 @@
+type ObservedStore<State> = {
+    readonly currentState: State;
+    readonly subscribe: (listener: () => void) => () => void;
+};
+export declare function useStoreState<State>(store: ObservedStore<State>): State;
+export {};

package/dist/hooks/useStoreState.js

@@ -0,0 +1,5 @@
+import { useSyncExternalStore } from 'react';
+export function useStoreState(store) {
+    const read = () => store.currentState;
+    return useSyncExternalStore(store.subscribe, read, read);
+}

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+export { defineApp } from './app.ts';
+export { ActionsStore, bindActions, rankActions } from './actions.ts';
+export type { Action, ActionsBuilder } from './actions.ts';
+export { startApp } from './start.ts';
+export type { StartOptions } from './start.ts';
+export { appearance } from './appearance.ts';
+export type { Appearance } from './appearance.ts';
+export { defineIcons } from './components/icons.ts';
+export type { IconDrawing } from './components/icons.ts';
+export type { Interaction } from './components/interaction.ts';
+export { apiCalls, browserApi, httpApi, memoryApi } from './api.ts';
+export type { ApiCall, AppApi } from './api.ts';
+export { SessionStore } from './auth/sessionStore.ts';
+export type { SessionState } from './auth/sessionStore.ts';
+export { HttpSessionApi, MemorySessionApi } from './auth/sessionApi.ts';
+export type { EmailCodeOutcome, SessionApi, SessionCall } from './auth/sessionApi.ts';
+export { userSchema } from './auth/user.ts';
+export type { User } from './auth/user.ts';
+export type { AppClass, AppDefinition, AppDependencies, AppSnapshotShape, DataRouter, ModelServicesOf, NavigateCommand, PressKeyCommand, PublicStores, PlainJsonModel, RunningApp, StoreClasses, StoreInstances, StoresOf, TableStores } from './app.ts';
+export { defineRoutes } from './routes.ts';
+export type { PageOf, PathOf, RouteDefinition } from './routes.ts';
+export { Model, action, appPath, defineActions } from './registered.ts';
+export type { ActionContext, AppAction, AppActionGroup, AppCommand, AppModels, AppPage, AppPath, AppSnapshot, AppStores, ModelServices, Register } from './registered.ts';
+export { Cache, Cached } from './cache.ts';
+export type { CacheStorage } from './cache.ts';
+export { EntityStore, WriteRefused, entityCalls } from './entityStore.ts';
+export type { Entity, EntityApi, EntityCall, EntityDeps, EntitySnapshot, PendingWrite } from './entityStore.ts';
+export { Gate } from './gate.ts';
+export { MemoryEntityApi, MemoryServer } from './memoryApi.ts';
+export type { MemoryApiOptions } from './memoryApi.ts';
+export { Store, StoreBase, keepEqualParts, snapshotsOf } from './store.ts';
+export type { Snapshots, StoreClass, StoreConfig } from './store.ts';
+export type { Json, Persisted, StateOf, StateSpec } from './state.ts';
+export { defineTables } from './table.ts';
+export type { Access, Columns, Fields, Level, PublicRow, Row, Seed, Table, TableDefinition, TableOf, Tables, Value, Writes } from './table.ts';
+export { HttpTableApi, MemoryTableApi, PublicTableStore, TableStore, httpTables, memoryTables, publicStoreName, tableCalls } from './tables.ts';
+export type { PublicSnapshot, TableApi, TableCall, TablesApi } from './tables.ts';
+export type { ReadScope, Viewer, WriteOutcome } from './access.ts';
+export { ModelBase, command, commandsOf, createModels, modelSnapshotsOf, parseMessage, sendMessage, splitType } from './model.ts';
+export type { Command, CommandKeys, CommandOptions, CommandResult, InputOf, Instances, Message, MessagesOf, ModelSnapshots, PublishedCommands, PublishedOf, SnapshotOf, DerivedOf, RouteParams, ModelClass, ModelClassLike, ModelConfig } from './model.ts';

package/dist/index.js

@@ -0,0 +1,19 @@
+export { defineApp } from "./app.js";
+export { ActionsStore, bindActions, rankActions } from "./actions.js";
+export { startApp } from "./start.js";
+export { appearance } from "./appearance.js";
+export { defineIcons } from "./components/icons.js";
+export { apiCalls, browserApi, httpApi, memoryApi } from "./api.js";
+export { SessionStore } from "./auth/sessionStore.js";
+export { HttpSessionApi, MemorySessionApi } from "./auth/sessionApi.js";
+export { userSchema } from "./auth/user.js";
+export { defineRoutes } from "./routes.js";
+export { Model, action, appPath, defineActions } from "./registered.js";
+export { Cache, Cached } from "./cache.js";
+export { EntityStore, WriteRefused, entityCalls } from "./entityStore.js";
+export { Gate } from "./gate.js";
+export { MemoryEntityApi, MemoryServer } from "./memoryApi.js";
+export { Store, StoreBase, keepEqualParts, snapshotsOf } from "./store.js";
+export { defineTables } from "./table.js";
+export { HttpTableApi, MemoryTableApi, PublicTableStore, TableStore, httpTables, memoryTables, publicStoreName, tableCalls } from "./tables.js";
+export { ModelBase, command, commandsOf, createModels, modelSnapshotsOf, parseMessage, sendMessage, splitType } from "./model.js";

package/dist/memoryApi.d.ts

@@ -0,0 +1,19 @@
+import type { Entity, EntityApi } from './entityStore.ts';
+import type { Gate } from './gate.ts';
+export type MemoryApiOptions = {
+    latencyMs: number;
+    gate: Gate;
+};
+export declare class MemoryServer {
+    #private;
+    constructor(name: string, options: MemoryApiOptions);
+    reply<Value>(call: string, respond: () => Value): Promise<Value>;
+}
+export declare class MemoryEntityApi<T extends Entity> implements EntityApi<T> {
+    #private;
+    constructor(name: string, seed: readonly T[], options: MemoryApiOptions);
+    list(): Promise<readonly T[]>;
+    create(entity: T): Promise<T>;
+    update(entity: T): Promise<T>;
+    remove(id: string): Promise<void>;
+}

package/dist/memoryApi.js

@@ -0,0 +1,42 @@
+export class MemoryServer {
+    #name;
+    #options;
+    constructor(name, options) {
+        this.#name = name;
+        this.#options = options;
+    }
+    reply(call, respond) {
+        return this.#options.gate.pass(`${this.#name}.${call}`, async () => {
+            await new Promise((done) => setTimeout(done, this.#options.latencyMs));
+            return respond();
+        });
+    }
+}
+export class MemoryEntityApi {
+    #server;
+    #saved;
+    constructor(name, seed, options) {
+        this.#server = new MemoryServer(name, options);
+        this.#saved = seed;
+    }
+    list() {
+        return this.#server.reply('list', () => this.#saved);
+    }
+    create(entity) {
+        return this.#server.reply('create', () => {
+            this.#saved = [...this.#saved, entity];
+            return entity;
+        });
+    }
+    update(entity) {
+        return this.#server.reply('update', () => {
+            this.#saved = this.#saved.map((item) => item.id === entity.id ? entity : item);
+            return entity;
+        });
+    }
+    remove(id) {
+        return this.#server.reply('remove', () => {
+            this.#saved = this.#saved.filter((item) => item.id !== id);
+        });
+    }
+}