glimpse-sdk 0.2.0 → 0.3.0

package/README.md

@@ -16,8 +16,7 @@ npm install glimpse-sdk
 - typed widget builders
 - async runtime
 - explicit typed handler registration
-- state-driven rendering via `await this.setState(...)`
-- single `render()` method that returns all panel state
+- separate `status(state)` and `popover(state)` methods; state mutation via `await this.setState(...)`
 
 ## Example
 
@@ -29,9 +28,9 @@ import {
   Hero,
   Icon,
   Label,
-  RenderResult,
   StatusItem,
-} from "./src/index.js";
+  type TreeNode,
+} from "glimpse-sdk";
 
 interface DeployState {
   version: string;
@@ -50,25 +49,31 @@ class DeployApplet extends Applet<DeployState> {
     });
   }
 
-  protected async render(): Promise<RenderResult> {
-    return new RenderResult({
-      status: [
-        new StatusItem({
-          id: "deploy",
-          icon: Icon.name("software-update-available-symbolic"),
-          label: this.state.status,
-        }),
-      ],
-      hero: new Hero({
+  protected async status(state: DeployState): Promise<StatusItem[]> {
+    return [
+      new StatusItem({
+        id: "deploy",
+        icon: Icon.name("software-update-available-symbolic"),
+        label: state.status,
+      }),
+    ];
+  }
+
+  protected async popover(state: DeployState): Promise<TreeNode | null> {
+    return Box.vertical([
+      new Hero({
         icon: Icon.name("software-update-available-symbolic"),
         title: "Deploy",
-        subtitle: this.state.version,
+        subtitle: state.version,
       }),
-      tree: Box.vertical([
-        new Label("Version"),
-        new Button({ id: "deploy_now", label: "Deploy now" }),
-      ]),
-    });
+      new Label("Version"),
+      new Button({
+        id: "deploy_now",
+        label: "Deploy now",
+        icon: "media-playback-start-symbolic",
+        variant: "primary",
+      }),
+    ]);
   }
 }
 
@@ -85,4 +90,5 @@ Use explicit registration helpers instead of decorators:
 - `this.onChange(id, handler)`
 - `this.onToggle(id, handler)`
 
-The SDK owns the line transport and writes `status {json}` and `popover {json}` messages derived from `render()`.
+The SDK owns the line transport. `status(state)` produces the panel items;
+`popover(state)` produces the popover tree; both are pure functions of state.

package/dist/src/app.d.ts

@@ -7,18 +7,6 @@ interface OutgoingMessage {
     data: unknown;
     line: string;
 }
-export declare class RenderResult {
-    readonly options: {
-        status?: StatusItem[];
-        tree?: TreeNode | null;
-    };
-    constructor(options?: {
-        status?: StatusItem[];
-        tree?: TreeNode | null;
-    });
-    get status(): StatusItem[];
-    get tree(): TreeNode | null;
-}
 export declare abstract class Applet<State extends object> {
     state: State;
     private readonly handlerMap;
@@ -33,7 +21,8 @@ export declare abstract class Applet<State extends object> {
     protected onStart(): Promise<void>;
     protected onInit(_event: InitEvent): Promise<void>;
     protected onCallback(_event: CallbackEvent): Promise<void>;
-    protected render(): Promise<RenderResult>;
+    protected status(_state: State): Promise<StatusItem[]>;
+    protected popover(_state: State): Promise<TreeNode | null>;
     setState(patch: Partial<State>): Promise<void>;
     onClick(id: string, handler: Handler<ClickEvent>): void;
     onScroll(id: string, handler: Handler<ScrollEvent>): void;

package/dist/src/app.js

@@ -1,17 +1,5 @@
 import { createInterface } from "node:readline";
 import { parseCallbackEvent, parseInitEvent, } from "./events.js";
-export class RenderResult {
-    options;
-    constructor(options = {}) {
-        this.options = options;
-    }
-    get status() {
-        return this.options.status ?? [];
-    }
-    get tree() {
-        return this.options.tree ?? null;
-    }
-}
 export class Applet {
     state;
     handlerMap = new Map();
@@ -27,8 +15,11 @@ export class Applet {
     async onStart() { }
     async onInit(_event) { }
     async onCallback(_event) { }
-    async render() {
-        return new RenderResult();
+    async status(_state) {
+        return [];
+    }
+    async popover(_state) {
+        return null;
     }
     async setState(patch) {
         this.state = { ...this.state, ...patch };
@@ -138,15 +129,17 @@ export class Applet {
         await this.flushPromise;
     }
     async flushRender() {
-        const rendered = await this.render();
-        const status = rendered.status.map((item) => item.toProtocol());
-        const tree = { root: rendered.tree?.toProtocol() ?? null };
+        const statusItems = await this.status(this.state);
+        const status = statusItems.map((item) => item.toProtocol());
         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)) {
+        const widget = await this.popover(this.state);
+        const tree = { root: widget?.toProtocol() ?? null };
+        // Emit only when popover open, or first render, or clearing.
+        const shouldEmit = this.popoverOpen || this.lastTree === null || tree.root === null;
+        if (shouldEmit && !deepEqual(tree, this.lastTree)) {
             this.lastTree = tree;
             this.emit("popover", tree);
         }

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export { Applet, RenderResult } from "./app.js";
+export { Applet } 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";
+export { Icon, StatusItem } from "./protocol.js";
+export { ActionItem, type Align, Badge, Box, Button, type ButtonVariant, Card, Checkbox, Column, type ContentFit, Copyable, EmptyState, Expander, Grid, GridChild, Hero, Image, Item, Label, LevelBar, type LevelBarMode, LinkButton, ListBox, MenuButton, Meter, Overlay, type Orientation, type PagerAppearance, PagerItem, PagerStrip, Picture, Progress, type Properties, PropertyList, Row, Scroll, Section, Select, SelectOption, Separator, Slider, Spinner, StatusDot, Switch, ToggleButton, TreeExpander, type TreeNode, type Variant, } from "./widgets.js";

package/dist/src/index.js

@@ -1,4 +1,4 @@
-export { Applet, RenderResult } from "./app.js";
+export { Applet } from "./app.js";
 export { parseCallbackEvent, parseInitEvent, } from "./events.js";
-export { Icon, MenuItem, StatusItem } from "./protocol.js";
-export { ActionMenu, ActionMenuItem, ActionRow, Badge, Box, Button, Card, Checkbox, Collapsible, CollapsibleItem, Column, Copyable, DetailGrid, DetailGridItem, Dropdown, DropdownItem, EmptyState, Grid, GridChild, Header, Hero, IconWidget, Image, Item, Label, Meter, Progress, Row, Scale, Scroll, Section, Separator, Spinner, StatusDot, Switch, Toast, ToastAction, } from "./widgets.js";
+export { Icon, StatusItem } from "./protocol.js";
+export { ActionItem, Badge, Box, Button, Card, Checkbox, Column, Copyable, EmptyState, Expander, Grid, GridChild, Hero, Image, Item, Label, LevelBar, LinkButton, ListBox, MenuButton, Meter, Overlay, PagerItem, PagerStrip, Picture, Progress, PropertyList, Row, Scroll, Section, Select, SelectOption, Separator, Slider, Spinner, StatusDot, Switch, ToggleButton, TreeExpander, } from "./widgets.js";

package/dist/src/protocol.d.ts

@@ -26,18 +26,3 @@ export declare class StatusItem {
     });
     toProtocol(): Record<string, unknown>;
 }
-export declare class MenuItem {
-    readonly options: {
-        id: string;
-        label: string;
-        visible?: boolean;
-        enabled?: boolean;
-    };
-    constructor(options: {
-        id: string;
-        label: string;
-        visible?: boolean;
-        enabled?: boolean;
-    });
-    toProtocol(): Record<string, unknown>;
-}

package/dist/src/protocol.js

@@ -37,22 +37,3 @@ export class StatusItem {
         return payload;
     }
 }
-export class MenuItem {
-    options;
-    constructor(options) {
-        this.options = options;
-    }
-    toProtocol() {
-        const payload = {
-            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;
-    }
-}

package/dist/src/widgets.d.ts

@@ -1,7 +1,11 @@
-import { Icon, MenuItem } from "./protocol.js";
+import { Icon } from "./protocol.js";
 export type Align = "fill" | "start" | "end" | "center" | "baseline";
 export type Orientation = "horizontal" | "vertical";
 export type Variant = "normal" | "muted" | "accent" | "success" | "warning" | "danger";
+export type ButtonVariant = "primary" | "secondary" | "compact" | "flat" | "danger";
+export type PagerAppearance = "dots" | "numbers";
+export type ContentFit = "fill" | "contain" | "cover" | "scale_down";
+export type LevelBarMode = "continuous" | "discrete";
 export interface WidgetNode {
     toProtocol(): Record<string, unknown>;
 }
@@ -39,30 +43,80 @@ export declare class Image extends WidgetBase {
     });
     toProtocol(): Record<string, unknown>;
 }
-export declare class IconWidget extends WidgetBase {
-    readonly icon: Icon;
+export declare class Progress extends WidgetBase {
     private readonly options;
-    constructor(icon: Icon, options?: CommonProps & {
-        pixel_size?: number;
+    constructor(options: CommonProps & {
+        value: number;
+        max?: number;
+        show_text?: boolean;
+        text?: string;
     });
     toProtocol(): Record<string, unknown>;
 }
-export declare class Progress extends WidgetBase {
+export declare class LevelBar extends WidgetBase {
     private readonly options;
     constructor(options: CommonProps & {
         value: number;
+        min?: number;
         max?: number;
-        show_text?: boolean;
-        text?: string;
+        mode?: LevelBarMode;
+    });
+    toProtocol(): Record<string, unknown>;
+}
+export declare class Picture extends WidgetBase {
+    readonly options: CommonProps & {
+        path: string;
+        content_fit?: ContentFit;
+    };
+    constructor(options: CommonProps & {
+        path: string;
+        content_fit?: ContentFit;
     });
     toProtocol(): Record<string, unknown>;
 }
 export declare class Button extends WidgetBase {
     private readonly options;
-    constructor(options?: CommonProps & {
+    constructor(options?: Omit<CommonProps, "variant"> & {
         label?: string;
-        icon?: Icon;
-        child?: TreeNode;
+        icon?: string;
+        enabled?: boolean;
+        variant?: ButtonVariant;
+    });
+    toProtocol(): Record<string, unknown>;
+}
+export declare class LinkButton extends WidgetBase {
+    private readonly options;
+    constructor(options: CommonProps & {
+        uri: string;
+        label?: string;
+    });
+    toProtocol(): Record<string, unknown>;
+}
+export declare class Expander extends WidgetBase {
+    private readonly options;
+    constructor(options: CommonProps & {
+        label: string;
+        child: TreeNode;
+        expanded?: boolean;
+    });
+    toProtocol(): Record<string, unknown>;
+}
+export declare class TreeExpander extends WidgetBase {
+    private readonly options;
+    constructor(options: CommonProps & {
+        child: TreeNode;
+        hide_expander?: boolean;
+        indent_for_depth?: boolean;
+        indent_for_icon?: boolean;
+    });
+    toProtocol(): Record<string, unknown>;
+}
+export declare class MenuButton extends WidgetBase {
+    private readonly options;
+    constructor(options: CommonProps & {
+        label?: string;
+        icon?: string;
+        popover: TreeNode;
     });
     toProtocol(): Record<string, unknown>;
 }
@@ -74,7 +128,15 @@ export declare class Switch extends WidgetBase {
     });
     toProtocol(): Record<string, unknown>;
 }
-export declare class Scale extends WidgetBase {
+export declare class ToggleButton extends WidgetBase {
+    private readonly options;
+    constructor(options?: CommonProps & {
+        label?: string;
+        active?: boolean;
+    });
+    toProtocol(): Record<string, unknown>;
+}
+export declare class Slider extends WidgetBase {
     private readonly options;
     constructor(options?: CommonProps & {
         min?: number;
@@ -94,16 +156,16 @@ export declare class Checkbox extends WidgetBase {
     });
     toProtocol(): Record<string, unknown>;
 }
-export declare class DropdownItem {
+export declare class SelectOption {
     readonly id: string;
     readonly label: string;
     constructor(id: string, label: string);
     toProtocol(): Record<string, unknown>;
 }
-export declare class Dropdown extends WidgetBase {
+export declare class Select extends WidgetBase {
     private readonly options;
     constructor(options?: CommonProps & {
-        items?: DropdownItem[];
+        items?: SelectOption[];
         selected?: number;
     });
     toProtocol(): Record<string, unknown>;
@@ -120,6 +182,21 @@ export declare class Scroll extends WidgetBase {
     constructor(child: TreeNode, options?: CommonProps);
     toProtocol(): Record<string, unknown>;
 }
+export declare class Overlay extends WidgetBase {
+    private readonly options;
+    constructor(options: CommonProps & {
+        child: TreeNode;
+        overlays?: TreeNode[];
+    });
+    toProtocol(): Record<string, unknown>;
+}
+export declare class ListBox extends WidgetBase {
+    private readonly options;
+    constructor(options?: CommonProps & {
+        children?: TreeNode[];
+    });
+    toProtocol(): Record<string, unknown>;
+}
 export declare class GridChild {
     readonly row: number;
     readonly column: number;
@@ -154,54 +231,11 @@ export declare class Card extends WidgetBase {
     });
     toProtocol(): Record<string, unknown>;
 }
-export declare class Header {
-    readonly title: string;
-    readonly subtitle: string;
-    constructor(title: string, subtitle?: string);
-    toProtocol(): Record<string, unknown>;
-}
 export declare class Section extends WidgetBase {
     private readonly options;
     constructor(options: CommonProps & {
         title?: string;
         subtitle?: string;
-        header?: Header;
-        body?: TreeNode[];
-        children?: TreeNode[];
-    });
-    toProtocol(): Record<string, unknown>;
-}
-export declare class Collapsible extends WidgetBase {
-    private readonly options;
-    constructor(options: CommonProps & {
-        title?: string;
-        subtitle?: string;
-        header?: Header;
-        expanded?: boolean;
-        body?: TreeNode[];
-        children?: TreeNode[];
-    });
-    toProtocol(): Record<string, unknown>;
-}
-export declare class Item extends WidgetBase {
-    private readonly options;
-    constructor(options?: CommonProps & {
-        left?: TreeNode;
-        label?: string;
-        right?: TreeNode;
-        clickable?: boolean;
-        menu?: MenuItem[];
-    });
-    toProtocol(): Record<string, unknown>;
-}
-export declare class CollapsibleItem extends WidgetBase {
-    private readonly options;
-    constructor(options?: CommonProps & {
-        left?: TreeNode;
-        label?: string;
-        right?: TreeNode;
-        expanded?: boolean;
-        body?: TreeNode[];
         children?: TreeNode[];
     });
     toProtocol(): Record<string, unknown>;
@@ -228,32 +262,6 @@ export declare class Copyable extends WidgetBase {
     });
     toProtocol(): Record<string, unknown>;
 }
-export declare class ToastAction {
-    readonly id: string;
-    readonly label: string;
-    constructor(id: string, label: string);
-    toProtocol(): Record<string, unknown>;
-}
-export declare class Toast extends WidgetBase {
-    private readonly options;
-    constructor(options: CommonProps & {
-        icon?: Icon;
-        title: string;
-        message?: string;
-        action?: ToastAction;
-    });
-    toProtocol(): Record<string, unknown>;
-}
-export declare class ActionRow extends WidgetBase {
-    private readonly options;
-    constructor(options: CommonProps & {
-        title: string;
-        subtitle?: string;
-        meta?: string;
-        icon?: Icon;
-    });
-    toProtocol(): Record<string, unknown>;
-}
 export declare class Row extends WidgetBase {
     private readonly options;
     constructor(options?: CommonProps & {
@@ -270,50 +278,40 @@ export declare class Column extends WidgetBase {
     });
     toProtocol(): Record<string, unknown>;
 }
-export declare class ActionMenuItem {
-    readonly options: {
-        id: string;
-        label: string;
-        icon?: Icon;
-        visible?: boolean;
-        checked?: boolean;
-        selectable?: boolean;
-    };
-    constructor(options: {
-        id: string;
-        label: string;
-        icon?: Icon;
-        visible?: boolean;
-        checked?: boolean;
-        selectable?: boolean;
-    });
-    toProtocol(): Record<string, unknown>;
-}
-export declare class ActionMenu extends WidgetBase {
+export declare class Spinner extends WidgetBase {
     private readonly options;
     constructor(options?: CommonProps & {
-        header?: string;
-        items?: ActionMenuItem[];
+        spinning?: boolean;
     });
     toProtocol(): Record<string, unknown>;
 }
-export declare class Spinner extends WidgetBase {
+export type Properties = Record<string, string>;
+export declare class PropertyList extends WidgetBase {
     private readonly options;
     constructor(options?: CommonProps & {
-        spinning?: boolean;
+        title?: string;
+        rows?: Properties;
     });
     toProtocol(): Record<string, unknown>;
 }
-export declare class DetailGridItem {
-    readonly key: string;
-    readonly value: string;
-    constructor(key: string, value: string);
+export declare class Item extends WidgetBase {
+    private readonly options;
+    constructor(options: CommonProps & {
+        label: string;
+        sublabel?: string;
+        icon?: string;
+        right?: TreeNode;
+    });
     toProtocol(): Record<string, unknown>;
 }
-export declare class DetailGrid extends WidgetBase {
+export declare class ActionItem extends WidgetBase {
     private readonly options;
-    constructor(options?: CommonProps & {
-        rows?: DetailGridItem[];
+    constructor(options: CommonProps & {
+        label: string;
+        sublabel?: string;
+        icon?: string;
+        right?: TreeNode;
+        enabled?: boolean;
     });
     toProtocol(): Record<string, unknown>;
 }
@@ -336,6 +334,26 @@ export declare class StatusDot extends WidgetBase {
     constructor(options?: CommonProps);
     toProtocol(): Record<string, unknown>;
 }
+export declare class PagerItem extends WidgetBase {
+    private readonly options;
+    constructor(options?: CommonProps & {
+        appearance?: PagerAppearance;
+        label?: string;
+        active?: boolean;
+        inactive?: boolean;
+        occupied?: boolean;
+        urgent?: boolean;
+    });
+    toData(): Record<string, unknown>;
+    toProtocol(): Record<string, unknown>;
+}
+export declare class PagerStrip extends WidgetBase {
+    private readonly options;
+    constructor(options?: CommonProps & {
+        items?: PagerItem[];
+    });
+    toProtocol(): Record<string, unknown>;
+}
 export declare class Box extends WidgetBase {
     private readonly options;
     constructor(options?: CommonProps & {
@@ -347,5 +365,5 @@ export declare class Box extends WidgetBase {
     static horizontal(children: TreeNode[], spacing?: number, options?: CommonProps): Box;
     toProtocol(): Record<string, unknown>;
 }
-export type TreeNode = Hero | Card | Section | Collapsible | Item | CollapsibleItem | Meter | Copyable | Toast | ActionRow | ActionMenu | DetailGrid | EmptyState | Badge | StatusDot | Box | Row | Column | Grid | Scroll | Progress | Separator | Spinner | Label | IconWidget | Image | Button | Switch | Scale | Dropdown | Checkbox;
+export type TreeNode = Hero | Card | Section | Meter | Copyable | PropertyList | Item | ActionItem | EmptyState | Badge | StatusDot | PagerItem | PagerStrip | Box | Row | Column | Grid | Scroll | Overlay | ListBox | LevelBar | TreeExpander | MenuButton | Progress | Separator | Spinner | Label | Image | Picture | Button | LinkButton | Expander | Switch | ToggleButton | Slider | Select | Checkbox;
 export {};