glimpse-sdk 0.1.0

package/src/app.ts

@@ -0,0 +1,241 @@
+import { createInterface } from "node:readline";
+
+import {
+  type CallbackEvent,
+  type ChangeEvent,
+  type ClickEvent,
+  type InitEvent,
+  type InputEvent,
+  type PopoverEvent,
+  type ScrollEvent,
+  type ToggleEvent,
+  parseCallbackEvent,
+  parseInitEvent,
+} from "./events.js";
+import { StatusItem } from "./protocol.js";
+import { type TreeNode } from "./widgets.js";
+
+type Handler<EventT> = (event: EventT) => void | Promise<void>;
+
+interface OutgoingMessage {
+  command: string;
+  data: unknown;
+  line: string;
+}
+
+export class RenderResult {
+  constructor(
+    public readonly options: {
+      status?: StatusItem[];
+      tree?: TreeNode | null;
+    } = {},
+  ) {}
+
+  get status(): StatusItem[] {
+    return this.options.status ?? [];
+  }
+
+  get tree(): TreeNode | null {
+    return this.options.tree ?? null;
+  }
+}
+
+export abstract class Applet<State extends object> {
+  state: State;
+
+  private readonly handlerMap = new Map<string, Handler<CallbackEvent>>();
+  private readonly outgoing: OutgoingMessage[] = [];
+  private flushPromise: Promise<void> | null = null;
+  private renderQueued = false;
+  private lastStatus: unknown[] | null = null;
+  private lastTree: Record<string, unknown> | null = null;
+  private popoverOpen = false;
+
+  protected constructor() {
+    this.state = this.initialState();
+  }
+
+  protected abstract initialState(): State;
+
+  protected async onStart(): Promise<void> {}
+
+  protected async onInit(_event: InitEvent): Promise<void> {}
+
+  protected async onCallback(_event: CallbackEvent): Promise<void> {}
+
+  protected async render(): Promise<RenderResult> {
+    return new RenderResult();
+  }
+
+  async setState(patch: Partial<State>): Promise<void> {
+    this.state = { ...this.state, ...patch };
+    await this.scheduleRender();
+  }
+
+  onClick(id: string, handler: Handler<ClickEvent>): void {
+    this.register("click", id, handler as Handler<CallbackEvent>);
+  }
+
+  onScroll(id: string, handler: Handler<ScrollEvent>): void {
+    this.register("scroll", id, handler as Handler<CallbackEvent>);
+  }
+
+  onInput(id: string, handler: Handler<InputEvent>): void {
+    this.register("input", id, handler as Handler<CallbackEvent>);
+  }
+
+  onChange(id: string, handler: Handler<ChangeEvent>): void {
+    this.register("change", id, handler as Handler<CallbackEvent>);
+  }
+
+  onToggle(id: string, handler: Handler<ToggleEvent>): void {
+    this.register("toggle", id, handler as Handler<CallbackEvent>);
+  }
+
+  isPopoverOpen(): boolean {
+    return this.popoverOpen;
+  }
+
+  async run(): Promise<void> {
+    process.stdout.on("error", (err: NodeJS.ErrnoException) => {
+      if (err.code === "EPIPE") {
+        process.exit(0);
+      }
+    });
+
+    await this.onStart();
+    await this.scheduleRender();
+
+    const rl = createInterface({
+      input: process.stdin,
+      crlfDelay: Infinity,
+    });
+
+    for await (const line of rl) {
+      if (!line) {
+        continue;
+      }
+      let raw: { command: string; data: unknown } | null;
+      try {
+        raw = parseLine(line);
+      } catch (err) {
+        process.stderr.write(`glimpse-sdk: ignoring malformed input: ${err}\n`);
+        continue;
+      }
+      if (raw === null) {
+        continue;
+      }
+      const data = raw.data as Record<string, unknown>;
+      try {
+        await this.handleIncoming(raw.command, data);
+      } catch (err) {
+        process.stderr.write(`glimpse-sdk: error handling input: ${err}\n`);
+      }
+    }
+  }
+
+  protected async drainOutgoingForTest(): Promise<OutgoingMessage[]> {
+    await this.scheduleRender();
+    const drained = [...this.outgoing];
+    this.outgoing.length = 0;
+    return drained;
+  }
+
+  private register(event: string, id: string, handler: Handler<CallbackEvent>): void {
+    this.handlerMap.set(`${event}:${id}`, handler);
+  }
+
+  private async dispatchCallback(event: CallbackEvent): Promise<void> {
+    const handler = this.handlerMap.get(`${event.event}:${event.id}`);
+    if (handler !== undefined) {
+      await handler(event);
+      return;
+    }
+    await this.onCallback(event);
+  }
+
+  private async handleIncoming(type: string, data: Record<string, unknown>): Promise<void> {
+    if (type === "init") {
+      await this.onInit(parseInitEvent(data));
+      await this.scheduleRender();
+      return;
+    }
+    if (type === "event") {
+      const event = parseCallbackEvent(data);
+      if (isPopoverEvent(event)) {
+        this.popoverOpen = event.open;
+      }
+      await this.dispatchCallback(event);
+      await this.scheduleRender();
+    }
+  }
+
+  private async scheduleRender(): Promise<void> {
+    this.renderQueued = true;
+    if (this.flushPromise === null) {
+      this.flushPromise = Promise.resolve().then(async () => {
+        try {
+          while (this.renderQueued) {
+            this.renderQueued = false;
+            await this.flushRender();
+          }
+        } finally {
+          this.flushPromise = null;
+        }
+      });
+    }
+    await this.flushPromise;
+  }
+
+  private async flushRender(): Promise<void> {
+    const rendered = await this.render();
+    const status = rendered.status.map((item) => item.toProtocol());
+    const tree = { root: rendered.tree?.toProtocol() ?? null };
+
+    if (!deepEqual(status, this.lastStatus)) {
+      this.lastStatus = status;
+      this.emit("status", { items: status });
+    }
+    const publishPopover = this.popoverOpen || this.lastTree === null || tree.root === null;
+    if (publishPopover && !deepEqual(tree, this.lastTree)) {
+      this.lastTree = tree;
+      this.emit("popover", tree);
+    }
+  }
+
+  private emit(command: string, data: unknown): void {
+    const line = `${command} ${JSON.stringify(data)}`;
+    this.outgoing.push({ command, data, line });
+    try {
+      process.stdout.write(`${line}\n`);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException)?.code;
+      if (code !== "EPIPE") {
+        throw err;
+      }
+    }
+  }
+}
+
+function parseLine(line: string): { command: string; data: unknown } | null {
+  const trimmed = line.trim();
+  if (trimmed === "") {
+    return null;
+  }
+  const split = trimmed.search(/\s/);
+  if (split < 0) {
+    throw new Error("missing command payload");
+  }
+  return {
+    command: trimmed.slice(0, split),
+    data: JSON.parse(trimmed.slice(split).trimStart()),
+  };
+}
+
+function deepEqual(left: unknown, right: unknown): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function isPopoverEvent(event: CallbackEvent): event is PopoverEvent {
+  return event.event === "open" || event.event === "close";
+}

package/src/events.ts

@@ -0,0 +1,85 @@
+export interface InitEvent {
+  instance: string;
+  options: Record<string, unknown>;
+}
+
+interface CallbackEventBase {
+  id: string;
+  event: string;
+}
+
+export interface ClickEvent extends CallbackEventBase {
+  event: "click";
+  button?: string;
+}
+
+export interface ScrollEvent extends CallbackEventBase {
+  event: "scroll";
+  delta_y?: number;
+}
+
+export interface InputEvent extends CallbackEventBase {
+  event: "input";
+  text: string;
+}
+
+export interface ChangeEvent extends CallbackEventBase {
+  event: "change";
+  value: unknown;
+}
+
+export interface ToggleEvent extends CallbackEventBase {
+  event: "toggle";
+  value: boolean;
+}
+
+export interface PopoverEvent extends CallbackEventBase {
+  event: "open" | "close";
+  open: boolean;
+}
+
+export type CallbackEvent =
+  | ClickEvent
+  | ScrollEvent
+  | InputEvent
+  | ChangeEvent
+  | ToggleEvent
+  | PopoverEvent;
+
+export function parseInitEvent(payload: Record<string, unknown>): InitEvent {
+  return {
+    instance: String(payload.instance ?? ""),
+    options: (payload.options ?? {}) as Record<string, unknown>,
+  };
+}
+
+export function parseCallbackEvent(payload: Record<string, unknown>): CallbackEvent {
+  const event = String(payload.type ?? payload.event ?? "");
+  const id = String(payload.id ?? "");
+  if (event === "click") {
+    return { id, event, button: payload.button === undefined ? undefined : String(payload.button) };
+  }
+  if (event === "scroll") {
+    return {
+      id,
+      event,
+      delta_y: typeof payload.delta_y === "number" ? payload.delta_y : undefined,
+    };
+  }
+  if (event === "input") {
+    return { id, event, text: String(payload.text ?? "") };
+  }
+  if (event === "toggle") {
+    let value = false;
+    if (typeof payload.active === "boolean") {
+      value = payload.active;
+    } else if (typeof payload.value === "boolean") {
+      value = payload.value;
+    }
+    return { id, event, value };
+  }
+  if (event === "open" || event === "close") {
+    return { id, event, open: event === "open" };
+  }
+  return { id, event: "change", value: payload.value };
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+export { Applet, RenderResult } from "./app.js";
+export {
+  type CallbackEvent,
+  type ChangeEvent,
+  type ClickEvent,
+  type InitEvent,
+  type InputEvent,
+  type PopoverEvent,
+  type ScrollEvent,
+  type ToggleEvent,
+  parseCallbackEvent,
+  parseInitEvent,
+} from "./events.js";
+export { Icon, MenuItem, StatusItem } from "./protocol.js";
+export {
+  ActionMenu,
+  ActionMenuItem,
+  ActionRow,
+  type Align,
+  Badge,
+  Box,
+  Button,
+  Card,
+  Checkbox,
+  Collapsible,
+  CollapsibleItem,
+  Column,
+  Copyable,
+  DetailGrid,
+  DetailGridItem,
+  Dropdown,
+  DropdownItem,
+  EmptyState,
+  Grid,
+  GridChild,
+  Header,
+  Hero,
+  IconWidget,
+  Image,
+  Item,
+  Label,
+  Meter,
+  type Orientation,
+  Progress,
+  Row,
+  Scale,
+  Scroll,
+  Section,
+  Separator,
+  Spinner,
+  StatusDot,
+  Switch,
+  Toast,
+  ToastAction,
+  type TreeNode,
+  type Variant,
+} from "./widgets.js";

package/src/protocol.ts

@@ -0,0 +1,73 @@
+export type IconKind = "name" | "path";
+
+export class Icon {
+  constructor(
+    public readonly kind: IconKind,
+    public readonly value: string,
+  ) {}
+
+  static name(value: string): Icon {
+    return new Icon("name", value);
+  }
+
+  static path(value: string): Icon {
+    return new Icon("path", value);
+  }
+
+  toProtocol(): { name: string } | { path: string } {
+    return this.kind === "name" ? { name: this.value } : { path: this.value };
+  }
+}
+
+export class StatusItem {
+  constructor(
+    public readonly options: {
+      id?: string;
+      icon?: Icon;
+      label?: string;
+      tooltip?: string;
+    } = {},
+  ) {}
+
+  toProtocol(): Record<string, unknown> {
+    const payload: Record<string, unknown> = {};
+    if (this.options.id !== undefined) {
+      payload.id = this.options.id;
+    }
+    if (this.options.icon !== undefined) {
+      payload.icon = this.options.icon.toProtocol();
+    }
+    if (this.options.label !== undefined) {
+      payload.label = this.options.label;
+    }
+    if (this.options.tooltip !== undefined) {
+      payload.tooltip = this.options.tooltip;
+    }
+    return payload;
+  }
+}
+
+export class MenuItem {
+  constructor(
+    public readonly options: {
+      id: string;
+      label: string;
+      visible?: boolean;
+      enabled?: boolean;
+    },
+  ) {}
+
+  toProtocol(): Record<string, unknown> {
+    const payload: Record<string, unknown> = {
+      id: this.options.id,
+      label: this.options.label,
+    };
+    if (this.options.visible !== undefined) {
+      payload.visible = this.options.visible;
+    }
+    if (this.options.enabled !== undefined) {
+      payload.enabled = this.options.enabled;
+    }
+    return payload;
+  }
+}