@marcosgilf/pi-modal 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcos Gil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# pi-modal
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared modal component for Pi extensions. Supports refresh, plain-text copy, and styled rows.
+
+Feature packages provide modal content and actions. This package provides the TUI shell, extra top/bottom padding, and outside-click dismissal. Press `c` to copy full modal text or Ctrl/Cmd+C to copy active fullscreen selection.
+
+## Use
+
+```ts
+import { showModal, type ModalContent } from "@marcosgilf/pi-modal";
+```
+
+`@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` are Pi-provided peer dependencies.

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@marcosgilf/pi-modal",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Shared modal UI components for Pi extension packages.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "keywords": [
+    "pi-library",
+    "pi",
+    "modal"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}

package/src/index.ts

@@ -0,0 +1,218 @@
+import { execFile } from "node:child_process";
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import {
+  type Component,
+  type KeybindingsManager,
+  matchesKey,
+  type TUI,
+  type TuiMouseEvent,
+  truncateToWidth,
+  visibleWidth,
+} from "@earendil-works/pi-tui";
+
+export type ModalRow = { text: string; style?: "accent" | "success" | "warning"; progress?: number };
+export type ModalContent = { rows: ModalRow[]; clipboardText: string };
+export type ModalActions = {
+  refresh: () => Promise<ModalContent>;
+  copy?: (text: string) => Promise<void>;
+};
+
+export function writeClipboard(text: string, command = "pbcopy"): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = execFile(command, (error) => (error ? reject(error) : resolve()));
+    child.stdin?.on("error", reject);
+    child.stdin?.end(text);
+  });
+}
+
+export function formatProgressBar(percent: number, width: number): string {
+  const cells = Math.max(0, Math.floor(width));
+  const value = Number.isFinite(percent) ? Math.min(100, Math.max(0, percent)) : 0;
+  const filled = Math.round((value / 100) * cells);
+  return `${"█".repeat(filled)}${"░".repeat(cells - filled)}`;
+}
+
+function borderedRows(rows: ModalRow[], width: number, theme: Theme): string[] {
+  if (width < 6) {
+    return rows.map(({ text, progress }) =>
+      truncateToWidth(progress === undefined ? text : formatProgressBar(progress, width), width, "…"),
+    );
+  }
+  const contentWidth = width - 4;
+  const edge = theme.fg("muted", "│");
+  const top = theme.fg("muted", `╭${"─".repeat(contentWidth + 2)}╮`);
+  const bottom = theme.fg("muted", `╰${"─".repeat(contentWidth + 2)}╯`);
+  const content = rows.map(({ text, style, progress }) => {
+    const value = progress === undefined ? text : formatProgressBar(progress, contentWidth);
+    const styled = style === "accent" ? theme.fg(style, theme.bold(value)) : style ? theme.fg(style, value) : value;
+    const clipped = truncateToWidth(styled, contentWidth, "…");
+    const padding = " ".repeat(Math.max(0, contentWidth - visibleWidth(clipped)));
+    return `${edge}${theme.bg("selectedBg", ` ${clipped}${padding} `)}${edge}`;
+  });
+  return [top, ...content, bottom];
+}
+
+function modalScreen(
+  rows: ModalRow[],
+  width: number,
+  height: number,
+  theme: Theme,
+): { lines: string[]; bounds: { left: number; top: number; right: number; bottom: number } } {
+  const panelWidth = Math.min(width, 74);
+  const paddedRows = [{ text: "" }, ...rows, { text: "" }];
+  let panel = borderedRows(paddedRows, panelWidth, theme);
+  if (panel.length > height) {
+    const compactRows = rows.filter(({ text, progress }) => text.length > 0 || progress !== undefined);
+    panel = borderedRows(compactRows, panelWidth, theme);
+  }
+  const left = Math.floor((width - panelWidth) / 2);
+  const top = Math.max(0, Math.floor((height - panel.length) / 2));
+  const screen = Array.from({ length: height }, () => " ".repeat(width));
+  panel.forEach((line, index) => {
+    const row = top + index;
+    if (row < height) {
+      screen[row] = `${" ".repeat(left)}${line}${" ".repeat(Math.max(0, width - left - visibleWidth(line)))}`;
+    }
+  });
+  return {
+    lines: screen,
+    bounds: { left, top, right: left + panelWidth, bottom: Math.min(height, top + panel.length) },
+  };
+}
+
+async function copyToClipboard(text: string): Promise<void> {
+  if (process.platform !== "darwin") throw new Error("Clipboard copy requires macOS.");
+  await writeClipboard(text);
+}
+
+export function createModalComponent(
+  tui: TUI,
+  theme: Theme,
+  keybindings: KeybindingsManager,
+  done: () => void,
+  initial: ModalContent,
+  actions: ModalActions,
+): Component & { dispose(): void } {
+  let content = initial;
+  let status: ModalRow | undefined;
+  let disposed = false;
+  let refreshGeneration = 0;
+  let bounds: { left: number; top: number; right: number; bottom: number } | undefined;
+  const selectionTui = tui as TUI & {
+    hasActiveSelection?: () => boolean;
+    copyActiveSelectionToClipboard?: () => Promise<boolean>;
+  };
+  const requestRender = () => {
+    if (!disposed) tui.requestRender();
+  };
+
+  return {
+    dispose() {
+      disposed = true;
+      refreshGeneration++;
+    },
+    render(width: number) {
+      const hint = status ?? { text: "r refresh · c copy full summary · Esc/outside closes" };
+      const layout = modalScreen([...content.rows, { text: "" }, hint], width, tui.terminal.rows, theme);
+      bounds = layout.bounds;
+      return layout.lines;
+    },
+    invalidate() {},
+    handleMouse(event: TuiMouseEvent) {
+      const inside =
+        bounds && event.x >= bounds.left && event.x < bounds.right && event.y >= bounds.top && event.y < bounds.bottom;
+      if (event.type !== "click" || inside) return;
+      done();
+      return { handled: true, render: true };
+    },
+    handleInput(data: string) {
+      if (keybindings.matches(data, "app.interrupt") || keybindings.matches(data, "tui.input.submit")) {
+        done();
+        return;
+      }
+      const key = data.toLowerCase();
+      if (key === "r") {
+        const generation = ++refreshGeneration;
+        status = { text: "Refreshing usage…" };
+        requestRender();
+        void actions
+          .refresh()
+          .then((next) => {
+            if (disposed || generation !== refreshGeneration) return;
+            content = next;
+            status = undefined;
+            requestRender();
+          })
+          .catch((error: unknown) => {
+            if (disposed || generation !== refreshGeneration) return;
+            const message = error instanceof Error ? error.message : String(error);
+            status = { text: `Refresh failed: ${message}`, style: "warning" };
+            requestRender();
+          });
+        return;
+      }
+      const copySelection = matchesKey(data, "super+c") || keybindings.matches(data, "tui.input.copy");
+      if (key === "c" || copySelection) {
+        if (copySelection && selectionTui.hasActiveSelection?.() && selectionTui.copyActiveSelectionToClipboard) {
+          status = { text: "Copying selection…" };
+          requestRender();
+          void selectionTui
+            .copyActiveSelectionToClipboard()
+            .then((copied) => {
+              if (disposed) return;
+              status = copied
+                ? { text: "Copied selection", style: "success" }
+                : { text: "Copy failed", style: "warning" };
+              requestRender();
+            })
+            .catch((error: unknown) => {
+              if (disposed) return;
+              const message = error instanceof Error ? error.message : String(error);
+              status = { text: `Copy failed: ${message}`, style: "warning" };
+              requestRender();
+            });
+          return;
+        }
+        void (actions.copy ?? copyToClipboard)(content.clipboardText)
+          .then(() => {
+            if (disposed) return;
+            status = { text: "Copied plain text", style: "success" };
+            requestRender();
+          })
+          .catch((error: unknown) => {
+            if (disposed) return;
+            const message = error instanceof Error ? error.message : String(error);
+            status = { text: `Copy failed: ${message}`, style: "warning" };
+            requestRender();
+          });
+        return;
+      }
+      requestRender();
+    },
+  };
+}
+
+export async function showModal(
+  ctx: ExtensionContext,
+  initial: ModalContent,
+  actions: ModalActions,
+  unavailableMessage: string,
+): Promise<void> {
+  if (ctx.mode !== "tui") {
+    ctx.ui.notify(unavailableMessage, "warning");
+    return;
+  }
+
+  try {
+    await ctx.ui.custom(
+      (tui, theme, keybindings, done) =>
+        createModalComponent(tui, theme, keybindings, () => done(undefined), initial, actions),
+      {
+        overlay: true,
+        overlayOptions: { anchor: "top-left", width: "100%", maxHeight: "100%", margin: 0 },
+      },
+    );
+  } catch (error) {
+    ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+  }
+}