@particle-academy/fancy-term 0.2.2 → 0.3.0

package/README.md

@@ -77,6 +77,9 @@ fancy-query's `useFancyStream`.
 | `activeShell` | `string` | controlled selected shell id (omit for uncontrolled) |
 | `onShellChange` | `(id, profile) => void` | fired when the user / `setShell` switches |
 | `showShellBar` | `boolean` | render the `<ShellSwitcher>` toolbar above the surface (default `false`) |
+| `clipboard` | `boolean` | enable the copy chord + paste interceptor (default `true`) |
+| `onPaste` | `(payload) => void \| boolean` | every paste; receives `{ text, files, images }` — handle pasted **images** here. Return `false` to suppress the native text paste |
+| `contextMenu` | `false \| Item[] \| (ctx, defaults) => Item[]` | the right-click selection menu (see [Clipboard & context menu](#clipboard--context-menu)) |
 
 The ref exposes a `TerminalHandle`:
 
@@ -85,11 +88,56 @@ const term = useRef<TerminalHandle>(null);
 // term.current.write / writeln / clear / reset / fit / focus
 // term.current.getBuffer()      → the visible buffer as text (what an agent "sees")
 // term.current.getSelection()   → current selection
+// term.current.copySelection()  → copy the selection to the system clipboard (Promise<boolean>)
+// term.current.paste(text?)     → paste text (or the system clipboard) into the terminal
+// term.current.selectAll() / clearSelection()
 // term.current.setShell("pwsh") → switch the active shell (fires onShellChange)
 // term.current.getShell()       → the active shell id
 // term.current.xterm            → the raw xterm.js instance (escape hatch)
 ```
 
+## Clipboard & context menu
+
+**Copy** — select text, then **Ctrl+Shift+C** (Windows/Linux) or **Cmd+C** (macOS,
+with a selection) copies to the system clipboard. Plain **Ctrl+C** is never
+intercepted — it stays **SIGINT**.
+
+**Paste** — text pastes natively. **Images** can't render in a shell, so a pasted
+image is handed to you via `onPaste` to upload / feed an agent / write a path:
+
+```tsx
+<Terminal
+  output={out}
+  onData={(d) => backend.send(d)}
+  onPaste={({ text, images }) => {
+    for (const img of images) upload(img).then((url) => backend.send(url));
+    // return false here to also suppress the native text paste
+  }}
+/>
+```
+
+**Context menu** — right-click shows Copy / Paste / Select all / Clear by default.
+Customize it with the `contextMenu` prop:
+
+```tsx
+// disable it
+<Terminal contextMenu={false} … />
+
+// add to the defaults (the function gets the default items)
+<Terminal
+  contextMenu={(ctx, defaults) => [
+    ...defaults,
+    { id: "sep", separator: true },
+    { id: "send-agent", label: "Send selection to agent", icon: "🤖",
+      disabled: !ctx.hasSelection, onSelect: (c) => agent.send(c.selection) },
+  ]}
+  …
+/>
+```
+
+Each item is `{ id, label?, icon?, disabled?, separator?, onSelect?(ctx) }`. Set
+`clipboard={false}` to turn off the copy chord + image-paste interception entirely.
+
 ## Switching shells
 
 fancy-term is a **frontend wrapper** — it never spawns a shell. It owns the
@@ -220,3 +268,9 @@ mutations so every write broadcasts `AgentActivity`, and supports a staged
 ## License
 
 MIT
+
+---
+
+## ⭐ Star Fancy UI
+
+If this package is useful to you, a quick ⭐ on the repo really helps us build a better kit. Thank you!

package/dist/index.cjs

@@ -52,6 +52,77 @@ function useTerminalFit(ref, fit, enabled = true) {
   }, [ref, enabled]);
 }
 
+// src/clipboard.ts
+function isImageFile(f) {
+  return typeof f.type === "string" && f.type.startsWith("image/");
+}
+function readDataTransfer(dt) {
+  const files = [];
+  let text = "";
+  if (dt) {
+    try {
+      text = dt.getData("text/plain") ?? "";
+    } catch {
+    }
+    const items = dt.items;
+    if (items) {
+      for (let i = 0; i < items.length; i++) {
+        const it = items[i];
+        if (it && it.kind === "file") {
+          const f = it.getAsFile();
+          if (f) files.push(f);
+        }
+      }
+    }
+    if (files.length === 0 && dt.files) {
+      for (let i = 0; i < dt.files.length; i++) files.push(dt.files[i]);
+    }
+  }
+  return { text, files, images: files.filter(isImageFile) };
+}
+async function writeClipboardText(text) {
+  try {
+    const nav = typeof navigator !== "undefined" ? navigator : void 0;
+    if (nav?.clipboard?.writeText) {
+      await nav.clipboard.writeText(text);
+      return true;
+    }
+  } catch {
+  }
+  try {
+    if (typeof document === "undefined") return false;
+    const ta = document.createElement("textarea");
+    ta.value = text;
+    ta.style.position = "fixed";
+    ta.style.left = "-9999px";
+    ta.style.opacity = "0";
+    document.body.appendChild(ta);
+    ta.select();
+    const ok = document.execCommand("copy");
+    document.body.removeChild(ta);
+    return ok;
+  } catch {
+    return false;
+  }
+}
+async function readClipboardText() {
+  try {
+    const nav = typeof navigator !== "undefined" ? navigator : void 0;
+    if (nav?.clipboard?.readText) return await nav.clipboard.readText();
+  } catch {
+  }
+  return "";
+}
+
+// src/copy-keybinding.ts
+function shouldCopyEvent(e, hasSelection) {
+  if (e.type !== "keydown") return false;
+  if (e.key !== "c" && e.key !== "C") return false;
+  if (e.ctrlKey && e.shiftKey && !e.metaKey) return true;
+  if (e.metaKey && !e.ctrlKey && hasSelection) return true;
+  return false;
+}
+
 // src/hooks/use-terminal.ts
 var DEFAULT_FONT = 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace';
 function readBuffer(term) {
@@ -94,6 +165,17 @@ function useTerminal(containerRef, options = {}) {
       focus: () => xtermRef.current?.focus(),
       getBuffer: () => readBuffer(xtermRef.current),
       getSelection: () => xtermRef.current?.getSelection() ?? "",
+      copySelection: async () => {
+        const sel = xtermRef.current?.getSelection() ?? "";
+        if (!sel) return false;
+        return writeClipboardText(sel);
+      },
+      paste: async (text) => {
+        const data = text ?? await readClipboardText();
+        if (data) xtermRef.current?.paste(data);
+      },
+      selectAll: () => xtermRef.current?.selectAll(),
+      clearSelection: () => xtermRef.current?.clearSelection(),
       // Shell selection is owned by the <Terminal> component layer (it needs the
       // `shells` list + onShellChange). The headless engine is shell-agnostic, so
       // these are no-ops here and get overridden when <Terminal> composes them.
@@ -131,9 +213,29 @@ function useTerminal(containerRef, options = {}) {
     const resizeSub = term.onResize(
       ({ cols, rows }) => optsRef.current.onResize?.({ cols, rows })
     );
+    term.attachCustomKeyEventHandler((e) => {
+      if (optsRef.current.clipboard === false) return true;
+      if (shouldCopyEvent(e, term.hasSelection())) {
+        void writeClipboardText(term.getSelection());
+        return false;
+      }
+      return true;
+    });
+    const onPasteEvent = (e) => {
+      const o2 = optsRef.current;
+      if (o2.clipboard === false) return;
+      if (o2.readOnly) {
+        e.preventDefault();
+        return;
+      }
+      const payload = readDataTransfer(e.clipboardData);
+      if (o2.onPaste?.(payload) === false) e.preventDefault();
+    };
+    el.addEventListener("paste", onPasteEvent, true);
     if (o.initialOutput) term.write(o.initialOutput);
     if (o.fit ?? true) handle.fit();
     return () => {
+      el.removeEventListener("paste", onPasteEvent, true);
       dataSub.dispose();
       resizeSub.dispose();
       term.dispose();
@@ -364,6 +466,122 @@ function ShellSwitcher({
   );
 }
 
+// src/menu-position.ts
+function clampMenuPosition(at, menu, viewport, margin = 8) {
+  const maxX = Math.max(margin, viewport.width - menu.width - margin);
+  const maxY = Math.max(margin, viewport.height - menu.height - margin);
+  return {
+    x: Math.min(Math.max(margin, at.x), maxX),
+    y: Math.min(Math.max(margin, at.y), maxY)
+  };
+}
+function TerminalContextMenu({
+  at,
+  items,
+  ctx,
+  onClose
+}) {
+  const ref = react.useRef(null);
+  const [pos, setPos] = react.useState(at);
+  react.useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el || typeof window === "undefined") return;
+    const r = el.getBoundingClientRect();
+    setPos(
+      clampMenuPosition(
+        at,
+        { width: r.width, height: r.height },
+        { width: window.innerWidth, height: window.innerHeight }
+      )
+    );
+  }, [at]);
+  react.useEffect(() => {
+    const onDown = (e) => {
+      if (ref.current && !ref.current.contains(e.target)) onClose();
+    };
+    const onKey = (e) => {
+      if (e.key === "Escape") onClose();
+    };
+    document.addEventListener("mousedown", onDown, true);
+    document.addEventListener("keydown", onKey, true);
+    return () => {
+      document.removeEventListener("mousedown", onDown, true);
+      document.removeEventListener("keydown", onKey, true);
+    };
+  }, [onClose]);
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "div",
+    {
+      ref,
+      "data-fancy-terminal-menu": "",
+      role: "menu",
+      style: {
+        position: "fixed",
+        left: pos.x,
+        top: pos.y,
+        zIndex: 2147483e3,
+        minWidth: 176,
+        padding: 4,
+        background: "#18181b",
+        border: "1px solid #3f3f46",
+        borderRadius: 8,
+        boxShadow: "0 10px 32px -8px rgba(0,0,0,.6)",
+        color: "#e4e4e7",
+        font: '13px/1.4 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
+        userSelect: "none"
+      },
+      children: items.map(
+        (it) => it.separator ? /* @__PURE__ */ jsxRuntime.jsx(
+          "div",
+          {
+            role: "separator",
+            style: { height: 1, margin: "4px 6px", background: "#3f3f46" }
+          },
+          it.id
+        ) : /* @__PURE__ */ jsxRuntime.jsxs(
+          "button",
+          {
+            type: "button",
+            role: "menuitem",
+            "data-menu-item": it.id,
+            disabled: it.disabled,
+            onClick: () => {
+              if (it.disabled) return;
+              it.onSelect?.(ctx);
+              onClose();
+            },
+            onMouseEnter: (e) => {
+              if (!it.disabled) e.currentTarget.style.background = "#27272a";
+            },
+            onMouseLeave: (e) => {
+              e.currentTarget.style.background = "transparent";
+            },
+            style: {
+              display: "flex",
+              alignItems: "center",
+              gap: 9,
+              width: "100%",
+              textAlign: "left",
+              padding: "6px 9px",
+              border: "none",
+              borderRadius: 5,
+              background: "transparent",
+              color: it.disabled ? "#52525b" : "inherit",
+              cursor: it.disabled ? "default" : "pointer",
+              font: "inherit"
+            },
+            children: [
+              /* @__PURE__ */ jsxRuntime.jsx("span", { style: { width: 16, textAlign: "center", opacity: 0.8 }, children: it.icon ?? "" }),
+              /* @__PURE__ */ jsxRuntime.jsx("span", { style: { flex: 1 }, children: it.label })
+            ]
+          },
+          it.id
+        )
+      )
+    }
+  );
+}
+
 // src/output-diff.ts
 function diffOutput(written, next) {
   if (next === written) return null;
@@ -380,6 +598,28 @@ function decideShellSelect(shells, current, id) {
 function decideShellSwitch(current, next) {
   return { changed: current !== next };
 }
+
+// src/context-menu.ts
+function defaultMenuItems(ctx, actions) {
+  const items = [
+    { id: "copy", label: "Copy", icon: "\u29C9", disabled: !ctx.hasSelection, onSelect: actions.copy }
+  ];
+  if (!ctx.readOnly) {
+    items.push({ id: "paste", label: "Paste", icon: "\u2398", onSelect: actions.paste });
+  }
+  items.push({ id: "select-all", label: "Select all", onSelect: actions.selectAll });
+  if (!ctx.readOnly) {
+    items.push({ id: "sep-default", separator: true });
+    items.push({ id: "clear", label: "Clear", onSelect: actions.clear });
+  }
+  return items;
+}
+function resolveMenuItems(config, ctx, actions) {
+  if (config === false) return null;
+  const defaults = defaultMenuItems(ctx, actions);
+  const items = config === void 0 || config === true ? defaults : Array.isArray(config) ? config : config(ctx, defaults);
+  return items.length > 0 ? items : null;
+}
 var Terminal = react.forwardRef(function Terminal2({
   output,
   theme,
@@ -399,6 +639,9 @@ var Terminal = react.forwardRef(function Terminal2({
   activeShell,
   onShellChange,
   showShellBar = false,
+  clipboard,
+  onPaste,
+  contextMenu,
   className,
   style,
   ...rest
@@ -431,7 +674,9 @@ var Terminal = react.forwardRef(function Terminal2({
     // diffing effect below owns the buffer, so don't double-write.
     initialOutput: output === void 0 ? initialOutput : void 0,
     onData,
-    onResize
+    onResize,
+    clipboard,
+    onPaste
   });
   react.useImperativeHandle(
     ref,
@@ -451,18 +696,46 @@ var Terminal = react.forwardRef(function Terminal2({
     handle.write(change.write);
     written.current = output;
   }, [output, handle]);
+  const [menu, setMenu] = react.useState(null);
+  const openMenu = react.useCallback(
+    (e) => {
+      if (contextMenu === false) return;
+      e.preventDefault();
+      const selection = handle.getSelection();
+      const ctx = {
+        hasSelection: selection.length > 0,
+        selection,
+        readOnly: !!readOnly
+      };
+      const items = resolveMenuItems(contextMenu, ctx, {
+        copy: () => void handle.copySelection(),
+        paste: () => void handle.paste(),
+        selectAll: () => handle.selectAll(),
+        clear: () => handle.clear()
+      });
+      if (items) setMenu({ at: { x: e.clientX, y: e.clientY }, items, ctx });
+    },
+    [contextMenu, handle, readOnly]
+  );
+  const menuNode = menu ? /* @__PURE__ */ jsxRuntime.jsx(TerminalContextMenu, { at: menu.at, items: menu.items, ctx: menu.ctx, onClose: () => setMenu(null) }) : null;
   const surface = /* @__PURE__ */ jsxRuntime.jsx(
     "div",
     {
       ref: containerRef,
       "data-fancy-terminal": "",
+      onContextMenu: openMenu,
       "data-readonly": readOnly ? "" : void 0,
       "data-fancy-terminal-shell": shellId ?? void 0,
       style: showShellBar && shells ? { width: "100%", flex: 1, minHeight: 0 } : { width: "100%", height: "100%", ...style },
       ...showShellBar && shells ? {} : rest
     }
   );
-  if (!showShellBar || !shells) return surface;
+  if (!showShellBar || !shells) {
+    return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+      surface,
+      menuNode
+    ] });
+  }
   return /* @__PURE__ */ jsxRuntime.jsxs(
     "div",
     {
@@ -493,7 +766,8 @@ var Terminal = react.forwardRef(function Terminal2({
             )
           }
         ),
-        surface
+        surface,
+        menuNode
       ]
     }
   );
@@ -545,8 +819,14 @@ function useTerminalSession(options) {
 exports.BUILTIN_SHELLS = BUILTIN_SHELLS;
 exports.ShellSwitcher = ShellSwitcher;
 exports.Terminal = Terminal;
+exports.TerminalContextMenu = TerminalContextMenu;
+exports.clampMenuPosition = clampMenuPosition;
+exports.defaultMenuItems = defaultMenuItems;
 exports.fancyDarkTheme = fancyDarkTheme;
+exports.isImageFile = isImageFile;
+exports.resolveMenuItems = resolveMenuItems;
 exports.resolveShell = resolveShell;
+exports.shouldCopyEvent = shouldCopyEvent;
 exports.useTerminal = useTerminal;
 exports.useTerminalFit = useTerminalFit;
 exports.useTerminalSession = useTerminalSession;