@ashley-shrok/viewmodel-shell 0.3.10 → 0.3.11

package/dist/index.d.ts

@@ -0,0 +1,192 @@
+export interface ActionEvent {
+    name: string;
+    context?: Record<string, unknown>;
+    files?: Record<string, File>;
+}
+export interface Adapter {
+    render(vm: ViewNode, onAction: (action: ActionEvent) => void): void;
+}
+export type ViewNode = PageNode | SectionNode | ListNode | ListItemNode | FormNode | FieldNode | CheckboxNode | ButtonNode | TextNode | LinkNode | StatBarNode | TabsNode | ProgressNode | ModalNode | TableNode;
+export interface PageNode {
+    type: "page";
+    title?: string;
+    children: ViewNode[];
+}
+export interface SectionNode {
+    type: "section";
+    heading?: string;
+    children: ViewNode[];
+}
+export interface ListNode {
+    type: "list";
+    id?: string;
+    children: ViewNode[];
+}
+export interface ListItemNode {
+    type: "list-item";
+    id?: string;
+    /** Appended as a BEM modifier: vms-list-item--{variant} */
+    variant?: string;
+    children: ViewNode[];
+}
+export interface FormNode {
+    type: "form";
+    submitAction: ActionEvent;
+    submitLabel?: string;
+    children: ViewNode[];
+}
+export interface FieldNode {
+    type: "field";
+    name: string;
+    inputType: "text" | "email" | "password" | "number" | "date" | "time" | "datetime-local" | "textarea" | "hidden" | "file" | "select" | "select-multiple" | "checkbox" | "code";
+    label?: string;
+    placeholder?: string;
+    value?: string;
+    required?: boolean;
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** Optional language hint for `inputType: "code"`. Emitted as a class
+     *  (`vms-field--code-{language}`) so apps can attach a syntax-highlighter
+     *  library (CodeMirror, Monaco, etc.) — the framework only ships
+     *  monospaced editable text, no coloring. */
+    language?: string;
+    /** Dispatched when Enter is pressed (text-like inputs only). Adapter merges { [name]: value } into context. */
+    action?: ActionEvent;
+}
+export interface CheckboxNode {
+    type: "checkbox";
+    name: string;
+    checked: boolean;
+    label?: string;
+    /** Dispatched immediately on change. Adapter merges { checked: boolean } into context. */
+    action?: ActionEvent;
+}
+export interface ButtonNode {
+    type: "button";
+    label: string;
+    action: ActionEvent;
+    variant?: "primary" | "secondary" | "danger";
+}
+export interface TextNode {
+    type: "text";
+    value: string;
+    style?: "heading" | "subheading" | "body" | "muted" | "strikethrough" | "error" | "pre";
+}
+export interface LinkNode {
+    type: "link";
+    label: string;
+    href: string;
+    /** true = open outside current app context (browser: new tab + noopener) */
+    external?: boolean;
+}
+export interface StatBarNode {
+    type: "stat-bar";
+    stats: Array<{
+        label: string;
+        value: string | number;
+    }>;
+}
+export interface TabsNode {
+    type: "tabs";
+    selected: string;
+    /** Base action. Adapter merges { value: tab.value } into context on click. */
+    action: ActionEvent;
+    tabs: Array<{
+        value: string;
+        label: string;
+    }>;
+}
+export interface ProgressNode {
+    type: "progress";
+    value: number;
+}
+export interface ModalNode {
+    type: "modal";
+    title?: string;
+    children: ViewNode[];
+    /** Optional footer row (typically holds action buttons). Rendered as an inline row at the bottom of the modal. */
+    footer?: ViewNode[];
+    /** Dispatched when the close button is clicked. If omitted, no close button is rendered. */
+    dismissAction?: ActionEvent;
+    /** Width variant. Default is "medium" (~520px). "wide" (~800px) suits tables/dashboards;
+     *  "fullscreen" (~95vw/95vh) for content that needs the whole viewport. */
+    size?: "narrow" | "medium" | "wide" | "fullscreen";
+}
+export interface TableColumn {
+    key: string;
+    label: string;
+    sortable?: boolean;
+    filterable?: boolean;
+    filterValue?: string;
+    /** If set, cell values render as <a href={value}>{linkLabel}</a> */
+    linkLabel?: string;
+    /** true = open outside current app context (browser: new tab + noopener) */
+    linkExternal?: boolean;
+}
+export interface TableRow {
+    id?: string;
+    cells: Record<string, string>;
+    action?: ActionEvent;
+    variant?: string;
+}
+export interface TableNode {
+    type: "table";
+    columns: TableColumn[];
+    rows: TableRow[];
+    sortColumn?: string;
+    sortDirection?: "asc" | "desc";
+    /** Base action. Adapter merges { column, direction } into context on header click. */
+    sortAction?: ActionEvent;
+    /** Base action. Adapter merges { column, value, filters } into context on Enter. */
+    filterAction?: ActionEvent;
+}
+export interface ShellOptions {
+    endpoint: string;
+    actionEndpoint: string;
+    adapter: Adapter;
+    onError?: (err: Error) => void;
+    onLoading?: (loading: boolean) => void;
+    /** Called before each dispatch — merge the returned headers into every POST request. */
+    getRequestHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Called when the server responds with a redirect URL. Defaults to window.location.href = url. */
+    onRedirect?: (url: string) => void;
+    /** When set, the shell dispatches a "poll" action at this interval (ms) after every load/dispatch.
+     *  The server can override the next interval via ShellResponse.nextPollIn, or stop polling by
+     *  omitting nextPollIn when no pollInterval is configured. */
+    pollInterval?: number;
+}
+export interface ShellSideEffect {
+    /** "set-local-storage" | "set-session-storage" — unknown types are silently ignored. */
+    type: string;
+    key?: string;
+    value?: string;
+}
+export interface ShellResponse {
+    vm: ViewNode;
+    state: unknown;
+    /** When set, the shell navigates to this URL instead of re-rendering. */
+    redirect?: string;
+    /** Applied in order before redirect or re-render. */
+    sideEffects?: ShellSideEffect[];
+    /** When set, schedules the next poll at this delay (ms). Overrides pollInterval for one tick. */
+    nextPollIn?: number;
+}
+export declare class ViewModelShell {
+    private options;
+    private currentVm;
+    private currentState;
+    private dispatching;
+    private pollTimer;
+    constructor(options: ShellOptions);
+    load(params?: Record<string, string>): Promise<void>;
+    dispatch(action: ActionEvent, silent?: boolean): Promise<void>;
+    /** Feed a pre-parsed ShellResponse into the shell — for SSE/WebSocket integrations. */
+    push(response: ShellResponse): void;
+    stopPolling(): void;
+    getCurrentVm(): ViewNode | null;
+    getCurrentState(): unknown;
+    private processResponse;
+    private schedulePoll;
+}

package/dist/index.js

@@ -0,0 +1,125 @@
+// ─── Action ──────────────────────────────────────────────────────────────────
+export class ViewModelShell {
+    options;
+    currentVm = null;
+    currentState = null;
+    dispatching = false;
+    pollTimer = null;
+    constructor(options) {
+        this.options = options;
+    }
+    async load(params) {
+        const { endpoint, adapter, onError, onLoading } = this.options;
+        this.stopPolling();
+        try {
+            onLoading?.(true);
+            const url = params ? `${endpoint}?${new URLSearchParams(params)}` : endpoint;
+            const extraHeaders = this.options.getRequestHeaders ? await this.options.getRequestHeaders() : {};
+            const res = await fetch(url, { headers: { Accept: "application/json", ...extraHeaders } });
+            if (!res.ok)
+                throw new Error(`${res.status} ${res.statusText}`);
+            const body = (await res.json());
+            this.currentVm = body.vm;
+            this.currentState = body.state;
+            adapter.render(body.vm, (action) => this.dispatch(action));
+            this.schedulePoll(body.nextPollIn);
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            onError ? onError(error) : console.error("[ViewModelShell]", error);
+        }
+        finally {
+            onLoading?.(false);
+        }
+    }
+    async dispatch(action, silent = false) {
+        if (this.dispatching)
+            return;
+        const { actionEndpoint, onError, onLoading } = this.options;
+        if (this.currentState === null) {
+            const err = new Error(`Cannot dispatch '${action.name}' before initial load completes. ` +
+                `Call shell.load() and wait for it before allowing user interaction.`);
+            onError ? onError(err) : console.error("[ViewModelShell]", err);
+            return;
+        }
+        try {
+            this.dispatching = true;
+            if (!silent)
+                onLoading?.(true);
+            const form = new FormData();
+            form.append("_action", JSON.stringify({ name: action.name, context: action.context ?? {} }));
+            form.append("_state", JSON.stringify(this.currentState));
+            if (action.files) {
+                for (const [name, file] of Object.entries(action.files)) {
+                    form.append(name, file);
+                }
+            }
+            const extraHeaders = this.options.getRequestHeaders ? await this.options.getRequestHeaders() : {};
+            const res = await fetch(actionEndpoint, {
+                method: "POST",
+                headers: { Accept: "application/json", ...extraHeaders },
+                body: form,
+            });
+            if (!res.ok)
+                throw new Error(`Action '${action.name}' failed: ${res.status}`);
+            this.processResponse((await res.json()));
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            onError ? onError(error) : console.error("[ViewModelShell]", error);
+        }
+        finally {
+            this.dispatching = false;
+            if (!silent)
+                onLoading?.(false);
+        }
+    }
+    /** Feed a pre-parsed ShellResponse into the shell — for SSE/WebSocket integrations. */
+    push(response) {
+        if (this.dispatching)
+            return;
+        this.processResponse(response);
+    }
+    stopPolling() {
+        if (this.pollTimer) {
+            clearTimeout(this.pollTimer);
+            this.pollTimer = null;
+        }
+    }
+    getCurrentVm() { return this.currentVm; }
+    getCurrentState() { return this.currentState; }
+    processResponse(body) {
+        for (const effect of body.sideEffects ?? []) {
+            if (effect.type === "set-local-storage" && effect.key != null) {
+                localStorage.setItem(effect.key, effect.value ?? "");
+            }
+            else if (effect.type === "set-session-storage" && effect.key != null) {
+                sessionStorage.setItem(effect.key, effect.value ?? "");
+            }
+        }
+        if (body.redirect) {
+            if (this.options.onRedirect) {
+                this.options.onRedirect(body.redirect);
+            }
+            else {
+                window.location.href = body.redirect;
+            }
+            return;
+        }
+        this.currentVm = body.vm;
+        this.currentState = body.state;
+        this.options.adapter.render(body.vm, (a) => this.dispatch(a));
+        this.schedulePoll(body.nextPollIn);
+    }
+    schedulePoll(nextPollIn) {
+        const delay = nextPollIn ?? this.options.pollInterval;
+        if (delay == null)
+            return;
+        if (this.pollTimer)
+            clearTimeout(this.pollTimer);
+        this.pollTimer = setTimeout(() => {
+            this.pollTimer = null;
+            this.dispatch({ name: "poll" }, true);
+        }, delay);
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,44 @@
+import type { ViewNode, ShellSideEffect } from "./index.js";
+export * from "./index.js";
+export interface ActionPayload<TState> {
+    name: string;
+    context: Record<string, unknown> | null;
+    state: TState;
+    /** Populated only on multipart submissions (FormData). Empty for JSON bodies. */
+    files: Record<string, File>;
+}
+/** Parse a multipart/form-data action body — the wire format the TypeScript shell uses. */
+export declare function parseFormDataAction<TState>(formData: FormData): ActionPayload<TState>;
+/** Parse a flat JSON action body — { name, context, state }. For curl/agent callers. */
+export declare function parseJsonAction<TState>(body: string | object): ActionPayload<TState>;
+/** What an action handler returns. All fields are optional — see ShellResponse reference in AGENTS.md. */
+export interface ShellResponseBody<TState> {
+    vm?: ViewNode | null;
+    state?: TState | null;
+    redirect?: string;
+    sideEffects?: ShellSideEffect[];
+    nextPollIn?: number;
+}
+/** Build a redirect response (Vm and State omitted; shell navigates the browser). */
+export declare function shellRedirect<TState = unknown>(url: string): ShellResponseBody<TState>;
+/** Side-effect factories matching the C# ShellSideEffect static methods. */
+export declare const shellSideEffect: {
+    setLocalStorage: (key: string, value: string) => ShellSideEffect;
+    setSessionStorage: (key: string, value: string) => ShellSideEffect;
+};
+/**
+ * Web Fetch API–native request handler factory. Auto-detects content-type
+ * (application/json vs multipart/form-data), parses the body, calls your
+ * handler, and returns the JSON response.
+ *
+ * Works directly with Hono, Bun.serve, Deno.serve, Cloudflare Workers, or
+ * any Request → Response runtime. For Express, wrap with a small adapter
+ * that constructs a Request from (req) and writes the Response back to res.
+ *
+ * @example
+ *   app.post("/api/tasks/action", createAction<TasksState>(async (payload) => {
+ *     const state = applyAction(payload);
+ *     return { vm: buildVm(state), state };
+ *   }));
+ */
+export declare function createAction<TState>(handler: (payload: ActionPayload<TState>) => Promise<ShellResponseBody<TState>> | ShellResponseBody<TState>): (request: Request) => Promise<Response>;

package/dist/server.js

@@ -0,0 +1,93 @@
+// ─── ViewModel Shell — server subpath ────────────────────────────────────────
+// Backend types and helpers for TypeScript/Node/Bun/Deno/Workers backends.
+// Mirrors the C# ViewModelShell NuGet package — same wire format, same shapes.
+//
+// Web Fetch API–native: works directly with Hono, Bun.serve, Deno.serve,
+// Cloudflare Workers. Express users can adapt createAction's (Request → Response)
+// handler with a 3-line wrapper.
+// Re-export the ViewNode hierarchy and wire types so a backend can import
+// everything it needs from one place.
+export * from "./index.js";
+/** Parse a multipart/form-data action body — the wire format the TypeScript shell uses. */
+export function parseFormDataAction(formData) {
+    const actionRaw = formData.get("_action");
+    const stateRaw = formData.get("_state");
+    if (typeof actionRaw !== "string" || typeof stateRaw !== "string") {
+        throw new Error("Missing _action or _state form field");
+    }
+    const action = JSON.parse(actionRaw);
+    const state = JSON.parse(stateRaw);
+    const files = {};
+    for (const [key, value] of formData.entries()) {
+        if (key !== "_action" && key !== "_state" && value instanceof File) {
+            files[key] = value;
+        }
+    }
+    return {
+        name: action.name,
+        context: action.context ?? null,
+        state,
+        files,
+    };
+}
+/** Parse a flat JSON action body — { name, context, state }. For curl/agent callers. */
+export function parseJsonAction(body) {
+    const parsed = typeof body === "string"
+        ? JSON.parse(body)
+        : body;
+    return {
+        name: parsed.name,
+        context: parsed.context ?? null,
+        state: parsed.state,
+        files: {},
+    };
+}
+/** Build a redirect response (Vm and State omitted; shell navigates the browser). */
+export function shellRedirect(url) {
+    return { redirect: url };
+}
+/** Side-effect factories matching the C# ShellSideEffect static methods. */
+export const shellSideEffect = {
+    setLocalStorage: (key, value) => ({ type: "set-local-storage", key, value }),
+    setSessionStorage: (key, value) => ({ type: "set-session-storage", key, value }),
+};
+// ─── Action handler factory ──────────────────────────────────────────────────
+/**
+ * Web Fetch API–native request handler factory. Auto-detects content-type
+ * (application/json vs multipart/form-data), parses the body, calls your
+ * handler, and returns the JSON response.
+ *
+ * Works directly with Hono, Bun.serve, Deno.serve, Cloudflare Workers, or
+ * any Request → Response runtime. For Express, wrap with a small adapter
+ * that constructs a Request from (req) and writes the Response back to res.
+ *
+ * @example
+ *   app.post("/api/tasks/action", createAction<TasksState>(async (payload) => {
+ *     const state = applyAction(payload);
+ *     return { vm: buildVm(state), state };
+ *   }));
+ */
+export function createAction(handler) {
+    return async (request) => {
+        const contentType = request.headers.get("content-type") ?? "";
+        let payload;
+        try {
+            if (contentType.includes("application/json")) {
+                payload = parseJsonAction(await request.text());
+            }
+            else {
+                payload = parseFormDataAction(await request.formData());
+            }
+        }
+        catch (err) {
+            return new Response(JSON.stringify({ error: err.message }), {
+                status: 400,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        const result = await handler(payload);
+        return new Response(JSON.stringify(result), {
+            headers: { "Content-Type": "application/json" },
+        });
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "description": "A server-driven UI framework where the wire format is structured enough that agents can build full-stack apps without ever opening a browser and all UI tests are pure unit tests with no browser runtime. Server returns a JSON tree of typed nodes; a thin TypeScript adapter renders it to DOM. Backend-agnostic — a .NET reference backend ships with the repo, but any language can produce the JSON contract.",
   "type": "module",
   "license": "MIT",
@@ -19,15 +19,31 @@
     "typescript"
   ],
   "files": [
-    "src",
+    "dist",
     "styles",
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
   "exports": {
-    ".": "./src/index.ts",
-    "./browser": "./src/browser.ts",
-    "./server": "./src/server.ts",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
     "./styles.css": "./styles/default.css",
     "./themes/dark-blue.css": "./styles/themes/dark-blue.css",
     "./themes/dark-green.css": "./styles/themes/dark-green.css",