feat(catalog): a right-click on a command offers the insert

Author: u8array

src/components/Output/ZPLOutput.sourceEdit.test.tsx

@@ -21,10 +21,11 @@ vi.mock("./ZplCodeMirror", () => {
     readOnly?: boolean;
     highlightLines?: ReadonlySet<number>;
     diagnostics?: readonly { from: number; to: number; message: string }[] | null;
-    ref?: React.Ref<{ focus(): void }>;
+    ref?: React.Ref<{ focus(): void; insertCommand(text: string): void }>;
   }) {
     const el = React.useRef<HTMLTextAreaElement>(null);
-    React.useImperativeHandle(ref, () => ({ focus: () => el.current?.focus() }), []);
+    // Appends and refocuses like the real insert. Enough to prove a command reached the buffer.
+    React.useImperativeHandle(ref, () => ({ focus: () => el.current?.focus(), insertCommand: (text: string) => { onChange(value + text); el.current?.focus(); } }), [onChange, value]);
     return (
       <textarea
         ref={el}
@@ -524,6 +525,23 @@ describe("outside pointerdown", () => {
     expect(outsideAction).toHaveBeenCalledTimes(1);
   });
 
+  it("holds the session on the reference's context menu and inserts the command", async () => {
+    render(<ZPLOutput onResizeMouseDown={vi.fn()} />);
+    typeDraft("^XA^FO10,10^A0N,30,30^FDedited^FS^XZ");
+    fireEvent.contextMenu(screen.getByRole("option", { name: /\^PW/ }), { clientX: 10, clientY: 10 });
+    const insert = within(screen.getByRole("menu")).getByRole("button", { name: t().output.catalogInsert });
+    fireEvent.pointerDown(insert);
+    expect(useLabelStore.getState().sourceEdit.status).toBe("editing");
+    fireEvent.click(insert);
+    expect(useLabelStore.getState().sourceEdit.status).toBe("editing");
+    expect(editor().value).toContain("^PW");
+    fireEvent.contextMenu(screen.getByRole("option", { name: /\^PW/ }), { clientX: 10, clientY: 10 });
+    await act(() => new Promise((r) => setTimeout(r, 0)));
+    fireEvent.keyDown(window, { key: "Escape" });
+    expect(screen.queryByRole("menu")).toBeNull();
+    expect(useLabelStore.getState().sourceEdit.status).toBe("editing");
+  });
+
   it("holds the session on panel chrome (the resize rail lives inside the root)", () => {
     const { container } = render(<ZPLOutput onResizeMouseDown={vi.fn()} />);
     typeDraft("^XA^FO10,10^A0N,30,30^FDedited^FS^XZ");

src/components/Output/ZplCatalogPanel.test.tsx

@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 import { describe, it, expect, afterEach, vi } from "vitest";
-import { render, cleanup, fireEvent, within } from "@testing-library/react";
+import { render, cleanup, fireEvent, within, act } from "@testing-library/react";
 import { ZplCatalogPanel } from "./ZplCatalogPanel";
 import { useCatalogSelection } from "../../hooks/useCatalogSelection";
 import type { CursorCommand } from "../../lib/zplLanguage";
@@ -36,6 +36,31 @@ describe("ZplCatalogPanel", () => {
     expect(detail(getByTestId).getByText("print width")).toBeTruthy();
   });
 
+  it("shows a context menu that selects the row and offers insert", () => {
+    const onInsert = vi.fn();
+    const { getByRole, getByTestId } = render(<Panel cursor={{ id: "^LL", from: 0, pointed: true }} onInsert={onInsert} />);
+    fireEvent.contextMenu(getByRole("option", { name: /\^PW/ }), { clientX: 10, clientY: 10 });
+    expect(detail(getByTestId).getByText("print width")).toBeTruthy();
+    fireEvent.click(within(getByRole("menu")).getByRole("button", { name: /^Insert$/ }));
+    expect(onInsert).toHaveBeenCalledWith("^PW");
+  });
+
+  it("closes the menu on Escape and keeps the row it selected", async () => {
+    const { getByRole, queryByRole, getByTestId } = render(<Panel cursor={{ id: "^LL", from: 0, pointed: true }} onInsert={vi.fn()} />);
+    fireEvent.contextMenu(getByRole("option", { name: /\^PW/ }), { clientX: 10, clientY: 10 });
+    // The menu's listeners attach a tick after the opening gesture.
+    await act(() => new Promise((r) => setTimeout(r, 0)));
+    fireEvent.keyDown(window, { key: "Escape" });
+    expect(queryByRole("menu")).toBeNull();
+    expect(detail(getByTestId).getByText("print width")).toBeTruthy();
+  });
+
+  it("disables the menu's insert when inserting is unavailable", () => {
+    const { getByRole } = render(<Panel cursor={{ id: "^LL", from: 0, pointed: true }} />);
+    fireEvent.contextMenu(getByRole("option", { name: /\^PW/ }), { clientX: 10, clientY: 10 });
+    expect((within(getByRole("menu")).getByRole("button", { name: /^Insert$/ }) as HTMLButtonElement).disabled).toBe(true);
+  });
+
   it("marks the insert button aria-disabled when inserting is unavailable", () => {
     const { getByRole } = render(<Panel cursor={{ id: "^LL", from: 0, pointed: true }} />);
     // Pins aria-disabled: a disabled button would drop its focus to body.

src/components/Output/ZplCatalogPanel.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useId, useRef } from "react";
+import { useEffect, useId, useRef, useState } from "react";
 import { MagnifyingGlassIcon } from "@heroicons/react/24/outline";
 import { CATALOG_SECTIONS, commandId, commandLabel, type CommandSupport, type SupportLevel } from "@zplab/core/catalog";
 import { useT } from "../../hooks/useT";
@@ -7,6 +7,8 @@ import type { CatalogSelection } from "../../hooks/useCatalogSelection";
 import { catalogEmptyText } from "../../lib/catalogText";
 import type { Translations } from "../../locales";
 import { inputCls } from "../Properties/styles";
+import { ContextMenu, type MenuSection } from "../ui/ContextMenu";
+import { useContextMenu } from "../../hooks/useContextMenu";
 
 type OutputKey = keyof Translations["output"];
 
@@ -28,6 +30,11 @@ const LEVEL: Record<SupportLevel, { cls: string; key: OutputKey }> = {
 const domId = (listId: string, key: string): string =>
   `${listId}-${key.replace(/^\^/, "c").replace(/^~/, "t").replace(/[^A-Za-z0-9]/g, "_")}`;
 
+/** One entry: the same insert the row's button and double-click already trigger. */
+function buildCatalogRowMenu(label: string, run: (() => void) | undefined): MenuSection[] {
+  return [{ id: "row", items: [{ id: "insert", label, run, disabled: run === undefined }] }];
+}
+
 /** Command reference beside the source pane; no `onInsert` means inserting is unavailable. */
 export function ZplCatalogPanel({
   selection,
@@ -43,7 +50,12 @@ export function ZplCatalogPanel({
   const summaries = useCatalogSummaries();
   const listId = useId();
   const listRef = useRef<HTMLUListElement>(null);
+  // State, not a ref: the menu's container is read during render.
+  const [panelEl, setPanelEl] = useState<HTMLElement | null>(null);
+  // A row chosen under the pointer is in view already, and scrolling would close the menu that opens with it.
+  const chosenByPointer = useRef<string | null>(null);
   const { query, setQuery, results, ids, entry, emptyReason, shownId, activeIndex, caretVisible, choose, toggle, stepBack, insertTextFor } = selection;
+  const { menu, openAtPointer, close } = useContextMenu<MenuSection[]>();
   // Headings only: the catalog is stored in section order, so the arrow walk reads `ids` as is.
   const groups = CATALOG_SECTIONS.map((section) => ({ section, rows: results.filter((e) => e.section === section.name) })).filter(
     (g) => g.rows.length > 0,
@@ -57,9 +69,18 @@ export function ZplCatalogPanel({
   const keepEditorFocus = (e: React.MouseEvent): void => {
     if (editorHasFocus?.()) e.preventDefault();
   };
+  // A right-click selects the row like a click does, then offers the insert that double-click hides.
+  const openRowMenu = (e: React.MouseEvent, id: string): void => {
+    e.preventDefault();
+    chosenByPointer.current = id;
+    choose(id);
+    openAtPointer(e, buildCatalogRowMenu(t.output.catalogInsert, onInsert ? () => onInsert(insertTextFor(id)) : undefined));
+  };
 
   useEffect(() => {
-    if (!shownId) return;
+    const justChosen = chosenByPointer.current;
+    chosenByPointer.current = null;
+    if (!shownId || shownId === justChosen) return;
     const row = listRef.current?.querySelector(`#${CSS.escape(domId(listId, shownId))}`);
     row?.scrollIntoView?.({ block: "nearest" });
     // `query` re-runs this when a cleared filter re-mounts the active row.
@@ -78,7 +99,7 @@ export function ZplCatalogPanel({
       const next = ids[Math.min(ids.length - 1, Math.max(0, activeIndex < 0 ? enterFrom : activeIndex + step))];
       if (next) choose(next);
     } else if (e.key === "Enter") {
-      // Enter inserts only the highlighted row. Anything else goes through the detail's button.
+      // Enter inserts only the highlighted row. Without one, it only selects the caret.
       const activeId = ids[activeIndex];
       if (activeId) onInsert?.(insertTextFor(activeId));
       else if (caretVisible) choose(caretVisible);
@@ -92,6 +113,7 @@ export function ZplCatalogPanel({
     // tabIndex -1 keeps a description click's focus inside the pane, else the session exit's focusout fires.
     // The data attributes keep the canvas shortcuts and the session's Escape away from the panel's own keys.
     <aside
+      ref={setPanelEl}
       tabIndex={-1}
       onKeyDown={onPanelKeyDown}
       data-text-surface
@@ -196,9 +218,12 @@ export function ZplCatalogPanel({
                           onMouseDown={keepEditorFocus}
                           // The clicks of a double-click must not toggle the pin twice.
                           onClick={(e) => {
-                            if (e.detail <= 1) toggle(id);
+                            if (e.detail > 1) return;
+                            chosenByPointer.current = id;
+                            toggle(id);
                           }}
                           onDoubleClick={() => onInsert?.(insertTextFor(id))}
+                          onContextMenu={(e) => openRowMenu(e, id)}
                           className={`flex items-baseline gap-2 px-3 py-0.5 cursor-default select-none hover:bg-border/60 ${active ? "bg-border/60" : ""}`}
                         >
                           {/* Coloured by web support: the answer most users need at a glance. */}
@@ -214,6 +239,8 @@ export function ZplCatalogPanel({
           </ul>
         </div>
       </div>
+      {/* Mounted inside the panel: the session exit reads a pointerdown outside it as leaving the edit. */}
+      {menu && <ContextMenu sections={menu.data} x={menu.x} y={menu.y} onClose={close} container={panelEl} />}
     </aside>
   );
 }

src/components/ui/ContextMenu.tsx

@@ -36,6 +36,8 @@ interface Props {
   /** Icon per action; consumer-owned so the menu model stays pure data. */
   iconFor?: (item: MenuAction) => IconType | undefined;
   onClose: () => void;
+  /** Where the menu mounts. A panel that watches for pointer events leaving it passes itself. */
+  container?: Element | null;
 }
 
 // Close-grace for submenu hover: long enough to survive a diagonal pointer
@@ -184,7 +186,7 @@ function Row({
 }
 
 /** Pure view over `MenuSection[]`; builders stay data-only. */
-export function ContextMenu({ sections, x, y, labels, iconFor, onClose }: Props) {
+export function ContextMenu({ sections, x, y, labels, iconFor, onClose, container }: Props) {
   const ref = useRef<HTMLDivElement>(null);
   const [pos, setPos] = useState({ x, y });
   // One open submenu across the whole root level (sections included).
@@ -243,6 +245,6 @@ export function ContextMenu({ sections, x, y, labels, iconFor, onClose }: Props)
         </div>
       ))}
     </div>,
-    document.body,
+    container ?? document.body,
   );
 }

src/hooks/useDismiss.ts

@@ -25,20 +25,24 @@ export function useDismiss(
     const onPointer = (e: PointerEvent) => {
       if (!ref.current?.contains(e.target as Node)) onDismissRef.current();
     };
+    // Capture phase and consumed: the open popover is the top layer, so its Escape reaches nothing beneath.
     const onKey = (e: KeyboardEvent) => {
-      if (e.key === "Escape") onDismissRef.current();
+      if (e.key !== "Escape") return;
+      e.preventDefault();
+      e.stopPropagation();
+      onDismissRef.current();
     };
     const attach = () => {
       window.addEventListener("pointerdown", onPointer);
-      window.addEventListener("keydown", onKey);
+      window.addEventListener("keydown", onKey, true);
     };
     let timer: number | undefined;
     if (defer) timer = window.setTimeout(attach, 0);
     else attach();
     return () => {
       if (timer !== undefined) window.clearTimeout(timer);
       window.removeEventListener("pointerdown", onPointer);
-      window.removeEventListener("keydown", onKey);
+      window.removeEventListener("keydown", onKey, true);
     };
   }, [ref, active, defer]);
 }