@particle-academy/fancy-term 0.2.2 → 0.4.0

package/dist/index.js

@@ -1,7 +1,7 @@
-import { forwardRef, useRef, useState, useCallback, useImperativeHandle, useEffect, useId } from 'react';
+import { forwardRef, useRef, useState, useCallback, useImperativeHandle, useEffect, useLayoutEffect, useId } from 'react';
 import { Terminal as Terminal$1 } from '@xterm/xterm';
 import { FitAddon } from '@xterm/addon-fit';
-import { jsx, jsxs } from 'react/jsx-runtime';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 
 // src/components/Terminal.tsx
 
@@ -50,8 +50,181 @@ 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 "";
+}
+var navigatorClipboard = {
+  writeText: (text) => writeClipboardText(text),
+  readText: () => readClipboardText()
+};
+function resolveClipboard(clipboard) {
+  if (clipboard === false) return { enabled: false, provider: navigatorClipboard };
+  if (clipboard && typeof clipboard === "object") return { enabled: true, provider: clipboard };
+  return { enabled: true, provider: navigatorClipboard };
+}
+async function providerWrite(provider, text) {
+  try {
+    await provider.writeText(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function providerRead(provider) {
+  try {
+    return await provider.readText() ?? "";
+  } catch {
+    return "";
+  }
+}
+
+// src/copy-paste-mode.ts
+function copyPasteBehavior(mode) {
+  switch (mode) {
+    case "linux":
+      return { selectToCopy: true, middleClickPaste: true, keyCopy: false, keyPaste: false };
+    case "winmac":
+      return { selectToCopy: false, middleClickPaste: false, keyCopy: true, keyPaste: true };
+    case "contextmenu":
+    default:
+      return { selectToCopy: false, middleClickPaste: false, keyCopy: false, keyPaste: false };
+  }
+}
+function resolveKeyAction(e, hasSelection, behavior) {
+  if (e.type !== "keydown") return null;
+  const key = e.key.toLowerCase();
+  if (key === "c") {
+    if (e.ctrlKey && e.shiftKey && !e.metaKey) return "copy";
+    if (e.metaKey && !e.ctrlKey && hasSelection) return "copy";
+    if (behavior.keyCopy && (e.ctrlKey || e.metaKey) && !e.shiftKey && hasSelection) return "copy";
+    return null;
+  }
+  if (key === "v" && behavior.keyPaste) {
+    if ((e.ctrlKey || e.metaKey) && !e.shiftKey) return "paste";
+    if (e.ctrlKey && e.shiftKey) return "paste";
+    return null;
+  }
+  return null;
+}
+
+// src/osc52.ts
+function encodeBase64(text) {
+  const bytes = new TextEncoder().encode(text);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return typeof btoa === "function" ? btoa(binary) : binary;
+}
+function decodeBase64(b64) {
+  try {
+    const binary = typeof atob === "function" ? atob(b64) : b64;
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return new TextDecoder().decode(bytes);
+  } catch {
+    return "";
+  }
+}
+function parseOsc52(payload) {
+  const semi = payload.indexOf(";");
+  if (semi < 0) return null;
+  const selection = payload.slice(0, semi);
+  const pd = payload.slice(semi + 1);
+  if (pd === "?") return { selection, kind: "read", data: "" };
+  return { selection, kind: "write", data: decodeBase64(pd) };
+}
+function osc52Response(selection, text) {
+  return `\x1B]52;${selection};${encodeBase64(text)}\x07`;
+}
+function registerOsc52(term, provider, mode) {
+  if (mode() === false) return null;
+  return term.parser.registerOscHandler(52, (payload) => {
+    const m = mode();
+    if (m === false) return true;
+    const req = parseOsc52(payload);
+    if (!req) return false;
+    if (req.kind === "write") {
+      if (m === "copy" || m === "both") {
+        void Promise.resolve(provider().writeText(req.data)).catch(() => {
+        });
+      }
+      return true;
+    }
+    if (m === "read" || m === "both") {
+      void providerRead(provider()).then((text) => {
+        term.write(osc52Response(req.selection, text));
+      });
+    }
+    return true;
+  });
+}
+
 // src/hooks/use-terminal.ts
 var DEFAULT_FONT = 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace';
+function makeDeferred() {
+  let resolve;
+  const promise = new Promise((r) => {
+    resolve = r;
+  });
+  return { promise, resolve };
+}
 function readBuffer(term) {
   if (!term) return "";
   const buf = term.buffer.active;
@@ -67,12 +240,16 @@ function useTerminal(containerRef, options = {}) {
   const fitRef = useRef(null);
   const optsRef = useRef(options);
   optsRef.current = options;
+  const readyRef = useRef(makeDeferred());
   const handleRef = useRef(null);
   if (handleRef.current === null) {
     handleRef.current = {
       get xterm() {
         return xtermRef.current;
       },
+      get ready() {
+        return readyRef.current.promise;
+      },
       write: (d) => xtermRef.current?.write(d),
       writeln: (d) => xtermRef.current?.writeln(d),
       clear: () => xtermRef.current?.clear(),
@@ -92,6 +269,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 providerWrite(resolveClipboard(optsRef.current.clipboard).provider, sel);
+      },
+      paste: async (text) => {
+        const data = text ?? await providerRead(resolveClipboard(optsRef.current.clipboard).provider);
+        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.
@@ -129,14 +317,77 @@ function useTerminal(containerRef, options = {}) {
     const resizeSub = term.onResize(
       ({ cols, rows }) => optsRef.current.onResize?.({ cols, rows })
     );
+    const pasteFromClipboard = async () => {
+      const oo = optsRef.current;
+      if (oo.readOnly) return;
+      const text = await providerRead(resolveClipboard(oo.clipboard).provider);
+      if (text) xtermRef.current?.paste(text);
+    };
+    term.attachCustomKeyEventHandler((e) => {
+      const oo = optsRef.current;
+      const clip = resolveClipboard(oo.clipboard);
+      if (!clip.enabled) return true;
+      const action = resolveKeyAction(e, term.hasSelection(), copyPasteBehavior(oo.copyPaste));
+      if (action === "copy") {
+        void providerWrite(clip.provider, term.getSelection());
+        return false;
+      }
+      if (action === "paste") {
+        void pasteFromClipboard();
+        return false;
+      }
+      return true;
+    });
+    const oscDisposable = registerOsc52(
+      term,
+      () => resolveClipboard(optsRef.current.clipboard).provider,
+      () => {
+        const oo = optsRef.current;
+        return resolveClipboard(oo.clipboard).enabled ? oo.osc52 ?? "copy" : false;
+      }
+    );
+    const selectionSub = term.onSelectionChange(() => {
+      const oo = optsRef.current;
+      const clip = resolveClipboard(oo.clipboard);
+      if (clip.enabled && copyPasteBehavior(oo.copyPaste).selectToCopy && term.hasSelection()) {
+        void providerWrite(clip.provider, term.getSelection());
+      }
+    });
+    const onMouseDown = (ev) => {
+      const oo = optsRef.current;
+      if (ev.button !== 1) return;
+      if (!resolveClipboard(oo.clipboard).enabled) return;
+      if (!copyPasteBehavior(oo.copyPaste).middleClickPaste) return;
+      ev.preventDefault();
+      void pasteFromClipboard();
+    };
+    el.addEventListener("mousedown", onMouseDown);
+    const onPasteEvent = (e) => {
+      const o2 = optsRef.current;
+      if (resolveClipboard(o2.clipboard).enabled === 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();
+    optsRef.current.onReady?.(term);
+    readyRef.current.resolve(term);
     return () => {
+      el.removeEventListener("paste", onPasteEvent, true);
+      el.removeEventListener("mousedown", onMouseDown);
+      oscDisposable?.dispose();
+      selectionSub.dispose();
       dataSub.dispose();
       resizeSub.dispose();
       term.dispose();
       xtermRef.current = null;
       fitRef.current = null;
+      readyRef.current = makeDeferred();
     };
   }, [containerRef]);
   useEffect(() => {
@@ -362,6 +613,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 = useRef(null);
+  const [pos, setPos] = useState(at);
+  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]);
+  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__ */ 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__ */ jsx(
+          "div",
+          {
+            role: "separator",
+            style: { height: 1, margin: "4px 6px", background: "#3f3f46" }
+          },
+          it.id
+        ) : /* @__PURE__ */ 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__ */ jsx("span", { style: { width: 16, textAlign: "center", opacity: 0.8 }, children: it.icon ?? "" }),
+              /* @__PURE__ */ jsx("span", { style: { flex: 1 }, children: it.label })
+            ]
+          },
+          it.id
+        )
+      )
+    }
+  );
+}
+
 // src/output-diff.ts
 function diffOutput(written, next) {
   if (next === written) return null;
@@ -378,6 +745,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 = forwardRef(function Terminal2({
   output,
   theme,
@@ -397,6 +786,12 @@ var Terminal = forwardRef(function Terminal2({
   activeShell,
   onShellChange,
   showShellBar = false,
+  clipboard,
+  osc52,
+  copyPaste,
+  onReady,
+  onPaste,
+  contextMenu,
   className,
   style,
   ...rest
@@ -429,12 +824,34 @@ var Terminal = 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,
+    osc52,
+    copyPaste,
+    onReady,
+    onPaste
   });
   useImperativeHandle(
     ref,
     () => ({
-      ...handle,
+      get xterm() {
+        return handle.xterm;
+      },
+      get ready() {
+        return handle.ready;
+      },
+      write: handle.write,
+      writeln: handle.writeln,
+      clear: handle.clear,
+      reset: handle.reset,
+      fit: handle.fit,
+      focus: handle.focus,
+      getBuffer: handle.getBuffer,
+      getSelection: handle.getSelection,
+      copySelection: handle.copySelection,
+      paste: handle.paste,
+      selectAll: handle.selectAll,
+      clearSelection: handle.clearSelection,
       setShell: selectShell,
       getShell: () => shellStateRef.current.shellId
     }),
@@ -449,18 +866,46 @@ var Terminal = forwardRef(function Terminal2({
     handle.write(change.write);
     written.current = output;
   }, [output, handle]);
+  const [menu, setMenu] = useState(null);
+  const openMenu = 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__ */ jsx(TerminalContextMenu, { at: menu.at, items: menu.items, ctx: menu.ctx, onClose: () => setMenu(null) }) : null;
   const surface = /* @__PURE__ */ 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__ */ jsxs(Fragment, { children: [
+      surface,
+      menuNode
+    ] });
+  }
   return /* @__PURE__ */ jsxs(
     "div",
     {
@@ -491,7 +936,8 @@ var Terminal = forwardRef(function Terminal2({
             )
           }
         ),
-        surface
+        surface,
+        menuNode
       ]
     }
   );
@@ -540,6 +986,15 @@ function useTerminalSession(options) {
   return { output, sendData, append, clear, shell, switchShell };
 }
 
-export { BUILTIN_SHELLS, ShellSwitcher, Terminal, fancyDarkTheme, resolveShell, useTerminal, useTerminalFit, useTerminalSession };
+// 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;
+}
+
+export { BUILTIN_SHELLS, ShellSwitcher, Terminal, TerminalContextMenu, clampMenuPosition, copyPasteBehavior, decodeBase64, defaultMenuItems, encodeBase64, fancyDarkTheme, isImageFile, navigatorClipboard, osc52Response, parseOsc52, registerOsc52, resolveClipboard, resolveKeyAction, resolveMenuItems, resolveShell, shouldCopyEvent, useTerminal, useTerminalFit, useTerminalSession };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map