glimpse-sdk 0.7.0 → 0.8.0

package/README.md

@@ -15,19 +15,19 @@ npm install glimpse-sdk
 Create and live-run a TypeScript applet project with the Glimpse tooling:
 
 ```sh
-glimpse-applet new counter --lang typescript
+glimpse-shell applets new counter --lang typescript
 cd counter
-glimpse-applet dev
+glimpse-shell applets dev
 ```
 
-Read `docs/custom-applets/tooling.md` for project layout, `applet.toml`, dev applets, linking, and diagnostics.
+Read `docs/custom-applets/tooling.md` for project layout, `applet.toml`, dev applets, local linking, distribution, and diagnostics.
 
 ## Goals
 
 - typed protocol models
 - typed widget builders
 - async runtime
-- explicit typed handler registration
+- widget-local callbacks, with explicit typed handler registration available when needed
 - separate `status(state)` and `popover(state)` methods; state mutation via `await this.setState(...)`
 
 ## Example
@@ -35,12 +35,11 @@ Read `docs/custom-applets/tooling.md` for project layout, `applet.toml`, dev app
 ```ts
 import {
   Applet,
-  Box,
-  Button,
+  Column,
   Hero,
-  Icon,
-  StatusItem,
   Label,
+  StatusItem,
+  Tile,
   type TreeNode,
 } from "glimpse-sdk";
 
@@ -50,42 +49,43 @@ interface DeployState {
 }
 
 class DeployApplet extends Applet<DeployState> {
-  protected initialState(): DeployState {
-    return { version: "2026.04.07", status: "Ready" };
-  }
-
   constructor() {
     super();
-    this.onClick("deploy_now", async () => {
-      await this.setState({ status: "Deploying" });
-    });
+  }
+
+  protected initialState(): DeployState {
+    return { version: "2026.04.07", status: "Ready" };
   }
 
   protected async status(state: DeployState): Promise<StatusItem[]> {
     return [
       new StatusItem({
         id: "deploy",
-        icon: Icon.name("software-update-available-symbolic"),
+        icon: "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: state.version,
-      }),
-      new Label("Version"),
-      new Button({
-        id: "deploy_now",
-        label: "Deploy now",
-        icon: "media-playback-start-symbolic",
-        variant: "primary",
-      }),
-    ]);
+    return new Column({
+      children: [
+        new Hero({
+          icon: "software-update-available-symbolic",
+          title: "Deploy",
+          subtitle: state.version,
+        }),
+        new Label("Version"),
+        new Tile({
+          id: "deploy_now",
+          primary: "Deploy now",
+          left_icon: "media-playback-start-symbolic",
+          on_click: async () => {
+            await this.setState({ status: "Deploying" });
+          },
+        }),
+      ],
+    });
   }
 }
 
@@ -94,7 +94,9 @@ await new DeployApplet().run();
 
 ## Handler Registration
 
-Use explicit registration helpers instead of decorators:
+Prefer widget-local callbacks for controls rendered in `popover(state)`.
+Explicit registration helpers are still available when the handler should live
+outside the widget tree:
 
 - `this.onClick(id, handler)`
 - `this.onScroll(id, handler)`

package/dist/src/protocol.d.ts

@@ -4,12 +4,20 @@ export declare class StatusItem {
         icon?: string;
         label?: string;
         tooltip?: string;
+        cssClasses?: string[];
     };
     constructor(options?: {
         id?: string;
         icon?: string;
         label?: string;
         tooltip?: string;
+        cssClasses?: string[];
     });
+    /**
+     * Return a copy with `cssClass` appended to `cssClasses`. Immutable-update
+     * form that mirrors the Rust SDK's `css_class()` builder so SDK-hopping
+     * users see equivalent ergonomics across languages.
+     */
+    withCssClass(cssClass: string): StatusItem;
     toProtocol(): Record<string, unknown>;
 }

package/dist/src/protocol.js

@@ -3,6 +3,17 @@ export class StatusItem {
     constructor(options = {}) {
         this.options = options;
     }
+    /**
+     * Return a copy with `cssClass` appended to `cssClasses`. Immutable-update
+     * form that mirrors the Rust SDK's `css_class()` builder so SDK-hopping
+     * users see equivalent ergonomics across languages.
+     */
+    withCssClass(cssClass) {
+        return new StatusItem({
+            ...this.options,
+            cssClasses: [...(this.options.cssClasses ?? []), cssClass],
+        });
+    }
     toProtocol() {
         const payload = {};
         if (this.options.id !== undefined) {
@@ -17,6 +28,9 @@ export class StatusItem {
         if (this.options.tooltip !== undefined) {
             payload.tooltip = this.options.tooltip;
         }
+        if (this.options.cssClasses && this.options.cssClasses.length > 0) {
+            payload.css_classes = [...this.options.cssClasses];
+        }
         return payload;
     }
 }

package/dist/src/widgets.d.ts

@@ -1,6 +1,8 @@
 export type InlineHandler = (event: unknown) => void | Promise<void>;
 export declare class InlineHandlerRegistry {
     readonly handlers: Map<string, InlineHandler>;
+    generatedId(event: "click" | "toggle" | "change", path: number[]): string;
+    targetId(event: "click" | "toggle" | "change", id: string | undefined, path: number[]): string;
     add(event: "click" | "toggle" | "change", id: string, handler: InlineHandler): void;
 }
 export type BadgeKind = "default" | "success" | "warning" | "error" | "accent";
@@ -195,7 +197,6 @@ export declare class Tile extends WidgetBase {
         left_icon?: string;
         left?: TreeNode;
         right?: TreeNode;
-        activatable?: boolean;
         on_click?: InlineHandler;
     };
     readonly type: string;
@@ -206,7 +207,6 @@ export declare class Tile extends WidgetBase {
         left_icon?: string;
         left?: TreeNode;
         right?: TreeNode;
-        activatable?: boolean;
         on_click?: InlineHandler;
     });
     data(): Record<string, unknown>;

package/dist/src/widgets.js

@@ -1,5 +1,12 @@
 export class InlineHandlerRegistry {
     handlers = new Map();
+    generatedId(event, path) {
+        const suffix = path.length === 0 ? "root" : path.join(".");
+        return `__glimpse:${event}:${suffix}`;
+    }
+    targetId(event, id, path) {
+        return id ?? this.generatedId(event, path);
+    }
     add(event, id, handler) {
         this.handlers.set(`${event}:${id}`, handler);
     }
@@ -73,8 +80,10 @@ export class Hero extends WidgetBase {
         return out;
     }
     bindHandlers(registry, path) {
-        if (this.options.id && this.options.on_toggle)
+        if (this.options.on_toggle) {
+            this.options.id = registry.targetId("toggle", this.options.id, path);
             registry.add("toggle", this.options.id, this.options.on_toggle);
+        }
         this.options.trailing?.bindHandlers(registry, [...path, 0]);
     }
 }
@@ -250,7 +259,7 @@ export class Tile extends WidgetBase {
         this.options = options;
     }
     data() {
-        const out = { ...this.commonData(), primary: this.options.primary, activatable: this.options.activatable ?? false };
+        const out = { ...this.commonData(), primary: this.options.primary };
         for (const key of ["id", "secondary", "left_icon"])
             if (this.options[key] !== undefined)
                 out[key] = this.options[key];
@@ -263,8 +272,10 @@ export class Tile extends WidgetBase {
         return out;
     }
     bindHandlers(registry, path) {
-        if (this.options.id && this.options.on_click)
+        if (this.options.on_click) {
+            this.options.id = registry.targetId("click", this.options.id, path);
             registry.add("click", this.options.id, this.options.on_click);
+        }
         this.options.left?.bindHandlers(registry, [...path, 0]);
         this.options.right?.bindHandlers(registry, [...path, 1]);
     }
@@ -286,8 +297,10 @@ export class SegmentedTile extends Tile {
     }
     bindHandlers(registry, path) {
         super.bindHandlers(registry, path);
-        if (this.options.id && this.options.on_toggle)
+        if (this.options.on_toggle) {
+            this.options.id = registry.targetId("toggle", this.options.id, path);
             registry.add("toggle", this.options.id, this.options.on_toggle);
+        }
         this.options.child?.bindHandlers(registry, [...path, 2]);
     }
 }
@@ -335,8 +348,10 @@ export class ExpanderTile extends WidgetBase {
         return out;
     }
     bindHandlers(registry, path) {
-        if (this.options.id && this.options.on_toggle)
+        if (this.options.on_toggle) {
+            this.options.id = registry.targetId("toggle", this.options.id, path);
             registry.add("toggle", this.options.id, this.options.on_toggle);
+        }
         this.options.left?.bindHandlers(registry, [...path, 0]);
         this.options.child?.bindHandlers(registry, [...path, 1]);
     }
@@ -382,8 +397,10 @@ export class ChoiceTile extends WidgetBase {
         return out;
     }
     bindHandlers(registry, path) {
-        if (this.options.id && this.options.on_click)
+        if (this.options.on_click) {
+            this.options.id = registry.targetId("click", this.options.id, path);
             registry.add("click", this.options.id, this.options.on_click);
+        }
         this.options.left?.bindHandlers(registry, [...path, 0]);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glimpse-sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Typed async framework for building Glimpse exec applets",
   "type": "module",
   "main": "dist/src/index.js",

package/src/protocol.ts

@@ -5,9 +5,22 @@ export class StatusItem {
       icon?: string;
       label?: string;
       tooltip?: string;
+      cssClasses?: string[];
     } = {},
   ) {}
 
+  /**
+   * Return a copy with `cssClass` appended to `cssClasses`. Immutable-update
+   * form that mirrors the Rust SDK's `css_class()` builder so SDK-hopping
+   * users see equivalent ergonomics across languages.
+   */
+  withCssClass(cssClass: string): StatusItem {
+    return new StatusItem({
+      ...this.options,
+      cssClasses: [...(this.options.cssClasses ?? []), cssClass],
+    });
+  }
+
   toProtocol(): Record<string, unknown> {
     const payload: Record<string, unknown> = {};
     if (this.options.id !== undefined) {
@@ -22,6 +35,9 @@ export class StatusItem {
     if (this.options.tooltip !== undefined) {
       payload.tooltip = this.options.tooltip;
     }
+    if (this.options.cssClasses && this.options.cssClasses.length > 0) {
+      payload.css_classes = [...this.options.cssClasses];
+    }
     return payload;
   }
 }

package/src/widgets.ts

@@ -2,6 +2,15 @@ export type InlineHandler = (event: unknown) => void | Promise<void>;
 export class InlineHandlerRegistry {
   readonly handlers = new Map<string, InlineHandler>();
 
+  generatedId(event: "click" | "toggle" | "change", path: number[]): string {
+    const suffix = path.length === 0 ? "root" : path.join(".");
+    return `__glimpse:${event}:${suffix}`;
+  }
+
+  targetId(event: "click" | "toggle" | "change", id: string | undefined, path: number[]): string {
+    return id ?? this.generatedId(event, path);
+  }
+
   add(event: "click" | "toggle" | "change", id: string, handler: InlineHandler): void {
     this.handlers.set(`${event}:${id}`, handler);
   }
@@ -82,7 +91,10 @@ export class Hero extends WidgetBase {
     return out;
   }
   bindHandlers(registry: InlineHandlerRegistry, path: number[]): void {
-    if (this.options.id && this.options.on_toggle) registry.add("toggle", this.options.id, this.options.on_toggle);
+    if (this.options.on_toggle) {
+      this.options.id = registry.targetId("toggle", this.options.id, path);
+      registry.add("toggle", this.options.id, this.options.on_toggle);
+    }
     this.options.trailing?.bindHandlers(registry, [...path, 0]);
   }
 }
@@ -212,9 +224,9 @@ export class PopoverShell extends ChildrenWidget {
 
 export class Tile extends WidgetBase {
   readonly type: string = "tile";
-  constructor(protected readonly options: CommonOptions & { primary: string; id?: string; secondary?: string; left_icon?: string; left?: TreeNode; right?: TreeNode; activatable?: boolean; on_click?: InlineHandler }) { super(options); }
+  constructor(protected readonly options: CommonOptions & { primary: string; id?: string; secondary?: string; left_icon?: string; left?: TreeNode; right?: TreeNode; on_click?: InlineHandler }) { super(options); }
   data(): Record<string, unknown> {
-    const out: Record<string, unknown> = { ...this.commonData(), primary: this.options.primary, activatable: this.options.activatable ?? false };
+    const out: Record<string, unknown> = { ...this.commonData(), primary: this.options.primary };
     for (const key of ["id", "secondary", "left_icon"] as const) if (this.options[key] !== undefined) out[key] = this.options[key];
     const left = child(this.options.left);
     const right = child(this.options.right);
@@ -223,7 +235,10 @@ export class Tile extends WidgetBase {
     return out;
   }
   bindHandlers(registry: InlineHandlerRegistry, path: number[]): void {
-    if (this.options.id && this.options.on_click) registry.add("click", this.options.id, this.options.on_click);
+    if (this.options.on_click) {
+      this.options.id = registry.targetId("click", this.options.id, path);
+      registry.add("click", this.options.id, this.options.on_click);
+    }
     this.options.left?.bindHandlers(registry, [...path, 0]);
     this.options.right?.bindHandlers(registry, [...path, 1]);
   }
@@ -241,7 +256,10 @@ export class SegmentedTile extends Tile {
   }
   bindHandlers(registry: InlineHandlerRegistry, path: number[]): void {
     super.bindHandlers(registry, path);
-    if (this.options.id && this.options.on_toggle) registry.add("toggle", this.options.id, this.options.on_toggle);
+    if (this.options.on_toggle) {
+      this.options.id = registry.targetId("toggle", this.options.id, path);
+      registry.add("toggle", this.options.id, this.options.on_toggle);
+    }
     this.options.child?.bindHandlers(registry, [...path, 2]);
   }
 }
@@ -275,7 +293,10 @@ export class ExpanderTile extends WidgetBase {
     return out;
   }
   bindHandlers(registry: InlineHandlerRegistry, path: number[]): void {
-    if (this.options.id && this.options.on_toggle) registry.add("toggle", this.options.id, this.options.on_toggle);
+    if (this.options.on_toggle) {
+      this.options.id = registry.targetId("toggle", this.options.id, path);
+      registry.add("toggle", this.options.id, this.options.on_toggle);
+    }
     this.options.left?.bindHandlers(registry, [...path, 0]);
     this.options.child?.bindHandlers(registry, [...path, 1]);
   }
@@ -308,7 +329,10 @@ export class ChoiceTile extends WidgetBase {
     return out;
   }
   bindHandlers(registry: InlineHandlerRegistry, path: number[]): void {
-    if (this.options.id && this.options.on_click) registry.add("click", this.options.id, this.options.on_click);
+    if (this.options.on_click) {
+      this.options.id = registry.targetId("click", this.options.id, path);
+      registry.add("click", this.options.id, this.options.on_click);
+    }
     this.options.left?.bindHandlers(registry, [...path, 0]);
   }
 }