pi-extension-utils 0.2.0 → 0.2.1

package/README.md

@@ -22,8 +22,23 @@ const client = connect(pi, { ctx, clientId: "my-extension" });
 client.widgets.set("belowEditor", "status", (tui, theme) => component, { order: 10 });
 client.widgets.remove("belowEditor", "status");
 
+// Run a custom fullscreen UI: widgets are blanked before mount and
+// restored afterwards, even if the component throws.
+const result = await client.ui.fullscreen<string | null>(
+  (tui, theme, keybindings, done) => new MyOverlayComponent(tui, theme, done),
+);
+
+// Lower-level lease, for manual control over the blank/restore window.
 const lease = client.fullscreen.acquire();
 lease.release();
+
+// Reminders (host absorbed from pi-reminders): fire-and-forget emits;
+// list() resolves { reminders: [], count: 0 } when no host is present.
+client.reminders.upsert({ id: "my-reminder", text: "...", source: "my-extension" });
+client.reminders.remove("my-reminder");
+client.reminders.clearSource("my-extension");
+const { reminders } = await client.reminders.list();
+
 client.dispose();
 
 const log = createLogger("my-extension");

package/dist/src/client.d.ts

@@ -11,6 +11,11 @@ export interface WidgetSetOptions {
 export interface FullscreenLease {
     release(): void;
 }
+/**
+ * Factory signature accepted by `ctx.ui.custom`. Typed structurally so the
+ * client does not depend on pi-tui types directly.
+ */
+export type FullscreenComponentFactory<T> = (tui: unknown, theme: unknown, keybindings: unknown, done: (result: T) => void) => unknown;
 export interface RemindersClient {
     upsert(intent: ReminderIntent): void;
     remove(source: string, key: string): void;
@@ -28,6 +33,14 @@ export interface UtilsClient {
     fullscreen: {
         acquire(): FullscreenLease;
     };
+    ui: {
+        /**
+         * Run a full-screen custom UI: acquires a fullscreen lease (blanking
+         * coordinated widgets), shows the component via `ctx.ui.custom`, and
+         * releases the lease in a finally — even if the component throws.
+         */
+        fullscreen<T>(factory: FullscreenComponentFactory<T>): Promise<T>;
+    };
     reminders: RemindersClient;
     dispose(): void;
 }

package/dist/src/client.js

@@ -104,6 +104,21 @@ export function connect(pi, opts) {
                 };
             },
         },
+        ui: {
+            async fullscreen(factory) {
+                const ui = opts.ctx.ui;
+                if (typeof ui.custom !== "function") {
+                    throw new Error("pi-extension-utils: ui.fullscreen requires an interactive UI (ctx.ui.custom is unavailable)");
+                }
+                const lease = client.fullscreen.acquire();
+                try {
+                    return await ui.custom(factory);
+                }
+                finally {
+                    lease.release();
+                }
+            },
+        },
         reminders: {
             upsert(intent) {
                 if (disposed)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-extension-utils",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "Shared Pi extension utilities for coordinated widgets, fullscreen leases, and logging.",
 	"type": "module",
 	"main": "./dist/src/index.js",