@vsceasy/cli 0.1.6 → 0.1.8

package/templates/react/src/shared/vsceasy/client.ts

@@ -6,3 +6,30 @@ export {
   webviewState,
 } from './rpc';
 export type { RpcClient, Handlers, Transport, RpcClientOptions, WebviewApi } from './rpc';
+
+export { defineStore } from './store';
+export type { Store } from './store';
+
+import type { RpcClient, Handlers } from './rpc';
+
+/**
+ * Listen for a change pushed from the host over the RPC event channel, and run a
+ * callback when it arrives. This is the webview side of the reactivity model —
+ * the host emits with `server.emit(topic, …)` (usually wired via `watch()` /
+ * `watchEntity()`), and your visual element reacts here. Returns an unsubscribe
+ * function; call it on unmount.
+ *
+ *   const api = connectWebview<TodoStatsViewApi>();
+ *   // re-read + re-render whenever todos change on the host:
+ *   const off = listen(api, 'todos:changed', () => refresh());
+ *
+ * It's a thin, named wrapper over `api.on(topic, handler)` so the place you
+ * listen reads clearly in the UI code. The payload (if any) is passed through.
+ */
+export function listen<H extends Handlers>(
+  api: RpcClient<H>,
+  topic: string,
+  handler: (payload?: unknown) => void,
+): () => void {
+  return api.on(topic, handler);
+}

package/templates/react/src/shared/vsceasy/define.ts

@@ -2,6 +2,18 @@ import type * as vscode from 'vscode';
 import type { Handlers } from './rpc';
 import type { CodiconName } from './codiconNames';
 
+/**
+ * Push a change to this webview over the RPC event channel. The webview reacts
+ * with `listen(api, topic, …)`. Wire it to a data source with `watch()` /
+ * `watchEntity()` inside `rpc()`:
+ *
+ *   rpc: (vscode, ctx, emit) => {
+ *     watchEntity(Todos, () => emit('todos:changed'));
+ *     return { stats: () => … };
+ *   }
+ */
+export type RpcEmit = (topic: string, payload?: unknown) => void;
+
 export interface PanelDef<H extends Handlers = Handlers> {
   /** Stable id. Default: file basename. Used as command suffix and webview key. */
   id?: string;
@@ -13,8 +25,11 @@ export interface PanelDef<H extends Handlers = Handlers> {
   column?: 'active' | 'beside' | 'one' | 'two' | 'three';
   /** Keep DOM alive when hidden. Default: true. */
   retainContext?: boolean;
-  /** RPC handlers — receives vscode namespace + extension context. */
-  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext) => H;
+  /**
+   * RPC handlers — receives the vscode namespace, the extension context, and
+   * `emit` for pushing change events to this webview (see {@link RpcEmit}).
+   */
+  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext, emit: RpcEmit) => H;
   /** Optional command palette entry that opens this panel. Default: true. */
   command?:
     | boolean
@@ -125,8 +140,11 @@ export interface SubpanelDef<H extends Handlers = Handlers> {
   ui?: string;
   /** Keep DOM alive when hidden. Default: true. */
   retainContext?: boolean;
-  /** RPC handlers — receives vscode namespace + extension context. */
-  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext) => H;
+  /**
+   * RPC handlers — receives the vscode namespace, the extension context, and
+   * `emit` for pushing change events to this webview (see {@link RpcEmit}).
+   */
+  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext, emit: RpcEmit) => H;
 }
 
 export function defineSubpanel<H extends Handlers = Handlers>(def: SubpanelDef<H>): SubpanelDef<H> {
@@ -228,6 +246,18 @@ export interface TreeViewDef {
     vscode: typeof import('vscode'),
     ctx: vscode.ExtensionContext,
   ) => TreeNode[] | Promise<TreeNode[]>;
+  /**
+   * Keep the tree live. Receives `refresh` — call it (directly or as a callback)
+   * to re-run `getChildren`. Subscribe to a data source here so the tree updates
+   * itself; return an unsubscribe to clean up.
+   *
+   *   watch: (refresh) => watchEntity(Todos, refresh),
+   */
+  watch?: (
+    refresh: () => void,
+    vscode: typeof import('vscode'),
+    ctx: vscode.ExtensionContext,
+  ) => (() => void) | void;
 }
 
 export function defineTreeView(def: TreeViewDef): TreeViewDef {

package/templates/react/src/shared/vsceasy/index.ts

@@ -1,5 +1,5 @@
 export { definePanel, defineCommand, defineMenu, defineStatusBar, defineSubpanel, defineTreeView, defineJob } from './define';
-export type { PanelDef, CommandDef, MenuDef, MenuItem, MenuIcon, StatusBarDef, StatusBarMenuItem, KeybindingDef, SubpanelDef, TreeViewDef, TreeNode, JobDef, JobSchedule, CodiconName } from './define';
+export type { PanelDef, CommandDef, MenuDef, MenuItem, MenuIcon, StatusBarDef, StatusBarMenuItem, KeybindingDef, SubpanelDef, TreeViewDef, TreeNode, JobDef, JobSchedule, CodiconName, RpcEmit } from './define';
 export { bootstrap } from './bootstrap';
 export type { Registry, BootstrapOptions, ActivateHook } from './bootstrap';
 export {
@@ -11,3 +11,6 @@ export {
   webviewState,
 } from './rpc';
 export type { Transport, RpcClient, Handlers, RpcClientOptions, WebviewApi } from './rpc';
+export { defineStore, watch } from './store';
+export type { Store, Watchable } from './store';
+export { listen } from './client';

package/templates/react/src/shared/vsceasy/store.ts

@@ -0,0 +1,73 @@
+/**
+ * Reactive stores — a tiny, framework-agnostic observable value.
+ *
+ * A store holds one value and notifies subscribers when it changes. It's the
+ * non-ORM half of the reactivity model: use it for arbitrary state (a counter,
+ * a flag, a selection) that a visual element should track.
+ *
+ *   const counter = defineStore(0);
+ *   counter.subscribe((v) => console.log('now', v));
+ *   counter.set(1);          // logs: now 1
+ *   counter.update((n) => n + 1);
+ *
+ * Pair it with `watch()` on the host to push changes to a webview, and
+ * `listen()` on the webview to react — see those helpers below and in client.ts.
+ */
+export interface Store<T> {
+  /** Read the current value. */
+  get(): T;
+  /** Replace the value and notify subscribers (no-op if `Object.is`-equal). */
+  set(next: T): void;
+  /** Derive the next value from the current one, then `set` it. */
+  update(fn: (current: T) => T): void;
+  /** Subscribe to changes. Returns an unsubscribe function. */
+  subscribe(cb: (value: T) => void): () => void;
+}
+
+export function defineStore<T>(initial: T): Store<T> {
+  let value = initial;
+  const subs = new Set<(value: T) => void>();
+
+  return {
+    get: () => value,
+    set(next) {
+      if (Object.is(value, next)) return;
+      value = next;
+      subs.forEach((cb) => {
+        try { cb(value); } catch { /* a bad subscriber must not break a set */ }
+      });
+    },
+    update(fn) {
+      this.set(fn(value));
+    },
+    subscribe(cb) {
+      subs.add(cb);
+      return () => { subs.delete(cb); };
+    },
+  };
+}
+
+/**
+ * Anything that can be watched: it exposes a `subscribe(cb)` returning an
+ * unsubscribe function. Stores satisfy this directly. (ORM entities are watched
+ * with `watchEntity` from your generated `db.ts`, which has the same shape.)
+ */
+export interface Watchable {
+  subscribe(cb: (...args: any[]) => void): () => void;
+}
+
+/**
+ * Bridge a watchable source to a side-effect — typically an RPC emit that pushes
+ * the change to a subscribed webview. Runs `effect` on every change. Returns an
+ * unsubscribe function; register it on the panel's `ctx.subscriptions` (wrapped
+ * in `{ dispose }`) so it's cleaned up when the extension deactivates.
+ *
+ *   // host side, in a panel's rpc():
+ *   watch(badgeCount, () => server.emit('badge:changed'));
+ *
+ * For ORM entities, use `watchEntity(Todos, () => server.emit('todos:changed'))`
+ * from your generated db.ts — same idea, same return.
+ */
+export function watch(source: Watchable, effect: () => void): () => void {
+  return source.subscribe(() => effect());
+}