knobkit 0.0.1

package/dist/lib/bound.d.ts

@@ -0,0 +1,12 @@
+import type { Widget } from "./types.js";
+export type Path = (string | number)[];
+export type EditOp = "set" | "append" | "appendText";
+export interface Bound {
+    read<T>(widget: Widget<any>, path: Path): Promise<T>;
+    edit(widget: Widget<any>, op: EditOp, path: Path, value: unknown): void;
+    enable(widget: Widget<any>, value: boolean): void;
+    busy(widget: Widget<any>, value: boolean): void;
+    key(widget: Widget<any>): string;
+}
+export declare function setBoundResolver(fn: () => Bound | undefined): void;
+export declare function bound(_widget: Widget<any>): Bound;

package/dist/lib/bound.js

@@ -0,0 +1,10 @@
+let resolve = () => undefined;
+export function setBoundResolver(fn) {
+    resolve = fn;
+}
+export function bound(_widget) {
+    const b = resolve();
+    if (!b)
+        throw new Error("widget method called outside a knobkit handler");
+    return b;
+}

package/dist/lib/controls.d.ts

@@ -0,0 +1,9 @@
+import type { Widget } from "./types.js";
+export declare const controls: {
+    enable(this: Widget): void;
+    disable(this: Widget): void;
+    setEnabled(this: Widget, value: boolean): void;
+    busyStart(this: Widget): void;
+    busyEnd(this: Widget): void;
+    busy(this: Widget, run: (payload: any) => any): (payload: any) => Promise<any>;
+};

package/dist/lib/controls.js

@@ -0,0 +1,35 @@
+import { bound } from "./bound.js";
+// Spread into every widget factory so enable()/disable()/busy() are uniform. `enabled` and `busy` are
+// two orthogonal runtime flags (both separate from state, both drop the widget's input events): enabled
+// is a persistent "can't use this" (dimmed); busy is a transient "this is working" (a loading bar).
+// `busyStart`/`busyEnd` mark a busy span by hand (e.g. across a setup() load); `busy(fn)` wraps an
+// async fn in the same span. `this` is the widget at call time.
+export const controls = {
+    enable() {
+        bound(this).enable(this, true);
+    },
+    disable() {
+        bound(this).enable(this, false);
+    },
+    setEnabled(value) {
+        bound(this).enable(this, value);
+    },
+    busyStart() {
+        bound(this).busy(this, true);
+    },
+    busyEnd() {
+        bound(this).busy(this, false);
+    },
+    busy(run) {
+        const self = this;
+        return async (payload) => {
+            self.busyStart();
+            try {
+                return await run(payload);
+            }
+            finally {
+                self.busyEnd();
+            }
+        };
+    },
+};

package/dist/lib/ctx.d.ts

@@ -0,0 +1,9 @@
+import type { Bound, EditOp, Path } from "./bound.js";
+import type { Widget } from "./types.js";
+export declare function makeBound(opts: {
+    read: (key: string, path: Path) => Promise<unknown>;
+    edit: (key: string, op: EditOp, path: Path, value: unknown) => void;
+    enable: (key: string, value: boolean) => void;
+    busy: (key: string, value: boolean) => void;
+    keyFor: (widget: Widget<any>) => string;
+}): Bound;

package/dist/lib/ctx.js

@@ -0,0 +1,22 @@
+// Builds a handler-time Bound from low-level transport functions. Reads proxy to wherever the state
+// lives (the client, over the socket); edits/enables are sent for the client to apply. Translates the
+// widget object to its key; the handler never sees keys.
+export function makeBound(opts) {
+    return {
+        read(widget, path) {
+            return opts.read(opts.keyFor(widget), path);
+        },
+        edit(widget, op, path, value) {
+            opts.edit(opts.keyFor(widget), op, path, value);
+        },
+        enable(widget, value) {
+            opts.enable(opts.keyFor(widget), value);
+        },
+        busy(widget, value) {
+            opts.busy(opts.keyFor(widget), value);
+        },
+        key(widget) {
+            return opts.keyFor(widget);
+        },
+    };
+}

package/dist/lib/declare.d.ts

@@ -0,0 +1,18 @@
+import type { AppConfig, Widget } from "./types.js";
+export interface WidgetDecl {
+    key: string;
+    type: string;
+    state: unknown;
+    enabled: boolean;
+    props: Record<string, unknown>;
+    events: Record<string, string>;
+}
+export interface AppDecl {
+    title?: string;
+    description?: string;
+    widgets: WidgetDecl[];
+    root: string;
+    serverEvents: string[];
+}
+export declare function widgetKeys(widgets: Widget<any> | Widget<any>[]): Map<Widget<any>, string>;
+export declare function declare(config: AppConfig, serverEvents?: string[]): AppDecl;

package/dist/lib/declare.js

@@ -0,0 +1,43 @@
+const SKIP = new Set(["state", "behavior", "view", "fold", "type", "children", "__subapp"]);
+function buildTree(widgets) {
+    let n = 0;
+    const visit = (w) => ({
+        widget: w,
+        key: `${w.type || "widget"}-${n++}`,
+        children: (w.children ?? []).map(visit),
+    });
+    const root = Array.isArray(widgets) ? { type: "col", state: {}, children: widgets } : widgets;
+    return visit(root);
+}
+function flatten(node) {
+    return [node, ...node.children.flatMap(flatten)];
+}
+export function widgetKeys(widgets) {
+    const map = new Map();
+    for (const node of flatten(buildTree(widgets)))
+        map.set(node.widget, node.key);
+    return map;
+}
+function toDecl(node) {
+    const w = node.widget;
+    const props = {};
+    const events = {};
+    for (const [k, v] of Object.entries(w)) {
+        if (SKIP.has(k))
+            continue;
+        if (typeof v === "function" && typeof v.type === "string") {
+            events[k] = v.type;
+        }
+        else if (typeof v !== "function") {
+            props[k] = v;
+        }
+    }
+    const isContainer = Array.isArray(w.children);
+    const state = isContainer ? { items: node.children.map((c) => c.key) } : w.state;
+    return { key: node.key, type: w.type ?? "", state, enabled: true, props, events };
+}
+export function declare(config, serverEvents = []) {
+    const root = buildTree(config.widgets);
+    const widgets = flatten(root).map(toDecl);
+    return { title: config.title, description: config.description, widgets, root: root.key, serverEvents };
+}

package/dist/lib/event.d.ts

@@ -0,0 +1,2 @@
+import type { EventCtor } from "./types.js";
+export declare function event<P = void>(name?: string): EventCtor<P>;

package/dist/lib/event.js

@@ -0,0 +1,9 @@
+let counter = 0;
+// Declare an event. Each call is a distinct event with a unique `type`; the optional name is only
+// for readability. The returned constructor makes instances: `Token("hi") -> { type, payload }`.
+export function event(name) {
+    const type = `${name ?? "event"}#${counter++}`;
+    const ctor = ((payload) => ({ type, payload }));
+    ctor.type = type;
+    return ctor;
+}

package/dist/lib/index.d.ts

@@ -0,0 +1,10 @@
+export type { Event, EventCtor, Emit, On, Widget, SelfListen, Produce, Listen, AppConfig, KnobkitServer, } from "./types.js";
+export type { Handler } from "./on.js";
+export type { Bound } from "./bound.js";
+export { event } from "./event.js";
+export { widget } from "./widget.js";
+export { bound } from "./bound.js";
+export { stream } from "./stream.js";
+export { Knobkit, knobkit } from "./knobkit.js";
+export type { KnobkitApp } from "./knobkit.js";
+export * from "./widgets/index.js";

package/dist/lib/index.js

@@ -0,0 +1,6 @@
+export { event } from "./event.js";
+export { widget } from "./widget.js";
+export { bound } from "./bound.js";
+export { stream } from "./stream.js";
+export { Knobkit, knobkit } from "./knobkit.js";
+export * from "./widgets/index.js";

package/dist/lib/knobkit.d.ts

@@ -0,0 +1,19 @@
+import type { AppConfig, KnobkitServer, EventCtor, Widget } from "./types.js";
+import type { Handler } from "./on.js";
+export declare class Knobkit {
+    config: AppConfig;
+    readonly handlers: Map<string, Handler<any>[]>;
+    readonly setups: Array<() => void | Promise<void>>;
+    private readonly keys;
+    constructor(config: AppConfig);
+    keyFor(widget: Widget<any>): string;
+    on<P>(source: EventCtor<P>, handler: Handler<P>): this;
+    setup(fn: () => void | Promise<void>): this;
+    serverEvents(): string[];
+    mount(selector: string): void;
+    serve(opts?: {
+        port?: number;
+    }): Promise<KnobkitServer>;
+}
+export type KnobkitApp = Knobkit;
+export declare function knobkit(config: AppConfig): Knobkit;

package/dist/lib/knobkit.js

@@ -0,0 +1,48 @@
+import { widgetKeys } from "./declare.js";
+import { collectSubapps } from "./widgets/embed.js";
+// The knobkit is the authored app: a set of widgets plus the `on(event, handler)` handlers registered
+// against their events. It holds no state — the browser owns that. Handlers run on the server (serve)
+// or in-browser (mount); both resolve a handler by the event's `type`.
+export class Knobkit {
+    config;
+    handlers = new Map();
+    setups = [];
+    keys;
+    constructor(config) {
+        this.config = config;
+        this.keys = widgetKeys(config.widgets);
+        for (const sub of collectSubapps(config.widgets)) {
+            for (const [type, hs] of sub.handlers)
+                this.handlers.set(type, [...(this.handlers.get(type) ?? []), ...hs]);
+            this.setups.push(...sub.setups);
+        }
+    }
+    keyFor(widget) {
+        const key = this.keys.get(widget);
+        if (!key)
+            throw new Error("widget is not part of this knobkit — pass it to knobkit({ widgets })");
+        return key;
+    }
+    on(source, handler) {
+        const list = this.handlers.get(source.type) ?? [];
+        list.push(handler);
+        this.handlers.set(source.type, list);
+        return this;
+    }
+    setup(fn) {
+        this.setups.push(fn);
+        return this;
+    }
+    serverEvents() {
+        return [...this.handlers.keys()];
+    }
+    mount(selector) {
+        void import("../client/mount.js").then(({ mount }) => mount(this, selector));
+    }
+    serve(opts) {
+        return import("../server/serve.js").then(({ serve }) => serve(this, opts));
+    }
+}
+export function knobkit(config) {
+    return new Knobkit(config);
+}

package/dist/lib/on.d.ts

@@ -0,0 +1,2 @@
+import type { Event } from "./types.js";
+export type Handler<P> = (payload: P) => void | Event | Promise<void | Event>;

package/dist/lib/on.js

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

package/dist/lib/stream.d.ts

@@ -0,0 +1 @@
+export declare function stream<T>(run: (push: (value: T) => void) => Promise<void> | void): AsyncGenerator<T>;

package/dist/lib/stream.js

@@ -0,0 +1,33 @@
+export async function* stream(run) {
+    const buffer = [];
+    let wake = null;
+    let done = false;
+    let failure = null;
+    const push = (value) => {
+        buffer.push(value);
+        wake?.();
+        wake = null;
+    };
+    Promise.resolve(run(push)).then(() => {
+        done = true;
+        wake?.();
+    }, (err) => {
+        failure = err;
+        done = true;
+        wake?.();
+    });
+    while (true) {
+        if (buffer.length) {
+            yield buffer.shift();
+            continue;
+        }
+        if (done) {
+            if (failure)
+                throw failure;
+            return;
+        }
+        await new Promise((resolve) => {
+            wake = resolve;
+        });
+    }
+}

package/dist/lib/types.d.ts

@@ -0,0 +1,48 @@
+export interface Event<P = unknown> {
+    type: string;
+    payload: P;
+}
+export interface EventCtor<P = void> {
+    (payload: P): Event<P>;
+    type: string;
+}
+export type Emit = <P>(event: Event<P>) => void;
+export type On<P = any> = EventCtor<P> | Widget<any>;
+export type Produce<P = any, I = any, V = any> = (payload: P, inputs: I) => V | Promise<V> | AsyncIterable<V>;
+export interface Widget<S = unknown> {
+    type?: string;
+    state: S;
+    children?: Widget<any>[];
+    fold?: (state: any, value: any) => S;
+    behavior?: SelfListen<any, any>[];
+    view?: (state: S, emit: Emit) => unknown;
+    enable(): void;
+    disable(): void;
+    setEnabled(value: boolean): void;
+    busyStart(): void;
+    busyEnd(): void;
+    busy<P = unknown>(run: (payload: P) => void | Event | Promise<void | Event>): (payload: P) => Promise<void | Event>;
+    [key: string]: unknown;
+}
+export interface SelfListen<P = any, V = any> {
+    on: EventCtor<P>;
+    from?: Record<string, Widget<any>>;
+    respond: Produce<P, any, V>;
+}
+export interface Listen<P = any, I = any, V = any> {
+    on: On<P>;
+    in: Widget<any>;
+    from?: Record<string, Widget<any>>;
+    respond: Produce<P, I, V>;
+}
+export interface AppConfig {
+    title?: string;
+    description?: string;
+    events?: EventCtor<any>[];
+    widgets: Widget<any> | Widget<any>[];
+    loading?: string;
+}
+export interface KnobkitServer {
+    url: string;
+    stop(): Promise<void>;
+}

package/dist/lib/types.js

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

package/dist/lib/widget.d.ts

@@ -0,0 +1,7 @@
+import type { Emit, SelfListen, Widget } from "./types.js";
+export declare function widget<S>(init: {
+    state: S;
+    fold?: (state: S, value: any) => S;
+    view?: (state: S, emit: Emit) => unknown;
+    behavior?: SelfListen<any, any>[];
+}): Widget<S>;

package/dist/lib/widget.js

@@ -0,0 +1,4 @@
+import { controls } from "./controls.js";
+export function widget(init) {
+    return { state: init.state, fold: init.fold, view: init.view, behavior: init.behavior, ...controls };
+}

package/dist/lib/widgets/annotated-image.d.ts

@@ -0,0 +1,14 @@
+import type { Widget } from "../types.js";
+export interface Annotation {
+    label: string;
+    box?: [number, number, number, number];
+    mask?: string;
+}
+export interface AnnotatedImageWidget extends Widget<{
+    src: string;
+    annotations: Annotation[];
+    colorMap: Record<string, string>;
+}> {
+    set(src: string, annotations?: Annotation[], colorMap?: Record<string, string>): void;
+}
+export declare function annotatedImage(): AnnotatedImageWidget;

package/dist/lib/widgets/annotated-image.js

@@ -0,0 +1,16 @@
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+export function annotatedImage() {
+    return {
+        type: "annotatedImage",
+        state: { src: "", annotations: [], colorMap: {} },
+        ...controls,
+        set(src, annotations, colorMap) {
+            const b = bound(this);
+            if (colorMap !== undefined)
+                b.edit(this, "set", ["colorMap"], colorMap);
+            b.edit(this, "set", ["annotations"], annotations ?? []);
+            b.edit(this, "set", ["src"], src);
+        },
+    };
+}

package/dist/lib/widgets/audio.d.ts

@@ -0,0 +1,10 @@
+import type { Widget } from "../types.js";
+export interface AudioWidget extends Widget<{
+    src: string;
+}> {
+    autoplay: boolean;
+    set(value: string): void;
+}
+export declare function audio(opts?: {
+    autoplay?: boolean;
+}): AudioWidget;

package/dist/lib/widgets/audio.js

@@ -0,0 +1,13 @@
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+export function audio(opts = {}) {
+    return {
+        type: "audio",
+        state: { src: "" },
+        autoplay: opts.autoplay ?? false,
+        ...controls,
+        set(value) {
+            bound(this).edit(this, "set", ["src"], value);
+        },
+    };
+}

package/dist/lib/widgets/button.d.ts

@@ -0,0 +1,11 @@
+import type { EventCtor, Widget } from "../types.js";
+export interface ButtonState {
+    label: string;
+}
+export interface ButtonWidget extends Widget<ButtonState> {
+    clicked: EventCtor;
+    set(patch: Partial<ButtonState>): void;
+}
+export declare function button(opts: {
+    label: string;
+}): ButtonWidget;

package/dist/lib/widgets/button.js

@@ -0,0 +1,17 @@
+import { event } from "../event.js";
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+// state is the label it shows; whether it's interactive is the framework-level enabled flag (controls)
+export function button(opts) {
+    return {
+        type: "button",
+        state: { label: opts.label },
+        clicked: event("button.clicked"),
+        ...controls,
+        set(patch) {
+            const rt = bound(this);
+            for (const [k, v] of Object.entries(patch))
+                rt.edit(this, "set", [k], v);
+        },
+    };
+}

package/dist/lib/widgets/chart.d.ts

@@ -0,0 +1,20 @@
+import type { Widget } from "../types.js";
+export type Point = Record<string, unknown>;
+export interface ChartWidget extends Widget<{
+    data: Point[];
+}> {
+    kind: "bar" | "line" | "area";
+    x: string;
+    y: string | string[];
+    maxHeight: number;
+    data(): Promise<Point[]>;
+    setData(data: Point[]): void;
+    push(point: Point): void;
+}
+export declare function chart(opts: {
+    x: string;
+    y: string | string[];
+    kind?: "bar" | "line" | "area";
+    data?: Point[];
+    maxHeight?: number;
+}): ChartWidget;

package/dist/lib/widgets/chart.js

@@ -0,0 +1,24 @@
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+// A read-only chart rendered by Recharts. Pure output: state is `{ data }` (an array of row objects)
+// and the view reads it; nothing rounds-trips back. `x`/`y` name which keys map to the axes/series.
+export function chart(opts) {
+    return {
+        type: "chart",
+        state: { data: opts.data ?? [] },
+        kind: opts.kind ?? "bar",
+        x: opts.x,
+        y: opts.y,
+        maxHeight: opts.maxHeight ?? 300,
+        ...controls,
+        data() {
+            return bound(this).read(this, ["data"]);
+        },
+        setData(data) {
+            bound(this).edit(this, "set", ["data"], data);
+        },
+        push(point) {
+            bound(this).edit(this, "append", ["data"], point);
+        },
+    };
+}

package/dist/lib/widgets/chat.d.ts

@@ -0,0 +1,26 @@
+import type { EventCtor, Widget } from "../types.js";
+export interface Message {
+    role: "user" | "assistant" | "system";
+    content: string;
+    image?: string;
+}
+export interface ChatWidget extends Widget<{
+    messages: Message[];
+}> {
+    sent: EventCtor<{
+        text: string;
+        image?: string;
+    }>;
+    recorded: EventCtor<Float32Array>;
+    placeholder: string;
+    voice: boolean;
+    images: boolean;
+    history(): Promise<Message[]>;
+    say(message: Message): void;
+    append(token: string): void;
+}
+export declare function chat(opts?: {
+    placeholder?: string;
+    voice?: boolean;
+    images?: boolean;
+}): ChatWidget;

package/dist/lib/widgets/chat.js

@@ -0,0 +1,24 @@
+import { event } from "../event.js";
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+export function chat(opts = {}) {
+    return {
+        type: "chat",
+        state: { messages: [] },
+        sent: event("chat.sent"),
+        recorded: event("chat.recorded"),
+        placeholder: opts.placeholder ?? "Say something…",
+        voice: opts.voice ?? false,
+        images: opts.images ?? false,
+        ...controls,
+        history() {
+            return bound(this).read(this, ["messages"]);
+        },
+        say(message) {
+            bound(this).edit(this, "append", ["messages"], message);
+        },
+        append(token) {
+            bound(this).edit(this, "appendText", ["messages", -1, "content"], token);
+        },
+    };
+}

package/dist/lib/widgets/checkbox-group.d.ts

@@ -0,0 +1,4 @@
+export declare function checkboxGroup(opts: {
+    choices: string[];
+    value?: string[];
+}): import("./value.js").ValueWidget<string[]>;

package/dist/lib/widgets/checkbox-group.js

@@ -0,0 +1,5 @@
+import { value } from "./value.js";
+// Multi-select from a fixed set; its `value` is the array of checked choices.
+export function checkboxGroup(opts) {
+    return value("checkboxGroup", opts.value ?? [], { choices: opts.choices });
+}

package/dist/lib/widgets/checkbox.d.ts

@@ -0,0 +1,4 @@
+export declare function checkbox(opts?: {
+    label?: string;
+    value?: boolean;
+}): import("./value.js").ValueWidget<boolean>;

package/dist/lib/widgets/checkbox.js

@@ -0,0 +1,4 @@
+import { value } from "./value.js";
+export function checkbox(opts = {}) {
+    return value("checkbox", opts.value ?? false, { label: opts.label });
+}

package/dist/lib/widgets/code.d.ts

@@ -0,0 +1,5 @@
+export declare function code(opts?: {
+    value?: string;
+    language?: string;
+    editable?: boolean;
+}): import("./value.js").ValueWidget<string>;

package/dist/lib/widgets/code.js

@@ -0,0 +1,10 @@
+import { value } from "./value.js";
+// A code editor over the uniform `value` attribute: holds `{ value: string }`, plus `language` (syntax
+// highlighting) and `editable` (false = a read-only, still-highlighted viewer) as static props. The
+// CodeMirror instance lives in the view; this stays a plain value widget (changed/value()/set()).
+export function code(opts = {}) {
+    return value("code", opts.value ?? "", {
+        language: opts.language ?? "",
+        editable: opts.editable ?? true,
+    });
+}

package/dist/lib/widgets/dropdown.d.ts

@@ -0,0 +1,4 @@
+export declare function dropdown(opts: {
+    choices: string[];
+    value?: string;
+}): import("./value.js").ValueWidget<string>;

package/dist/lib/widgets/dropdown.js

@@ -0,0 +1,4 @@
+import { value } from "./value.js";
+export function dropdown(opts) {
+    return value("dropdown", opts.value ?? opts.choices[0], { choices: opts.choices });
+}

package/dist/lib/widgets/embed.d.ts

@@ -0,0 +1,5 @@
+import type { Knobkit } from "../knobkit.js";
+import type { Widget } from "../types.js";
+export declare const SUBAPP = "__subapp";
+export declare function embed(app: Knobkit): Widget;
+export declare function collectSubapps(widgets: Widget | Widget[]): Knobkit[];