ink-cartridge 3.6.1 → 3.7.0

package/dist/dev/dev-screen.js

@@ -5,6 +5,7 @@ import { useKeyboard, useModalMissListener } from "../keyboard/hook.js";
 import { ModalContext } from "../screen/ModalContext.js";
 import { registerComponent } from "../screen/registry.js";
 import { closeDevTool } from "./entrance.js";
+import GlobalKeyDisplayBox from "./globalKey-display.js";
 const PANEL_HEIGHT = 30;
 /**
  * Developer debugging modal for the ink-cartridge screen system.
@@ -44,6 +45,7 @@ export function DevScreen({ top: initialTop, left }) {
     const { boundKeyboard } = useKeyboard();
     const modalId = useContext(ModalContext);
     const { rows } = useWindowSize();
+    const { openModal } = useScreenSystem();
     const [offsetTop, setOffsetTop] = useState(initialTop);
     const [flashBorder, setFlashBorder] = useState(false);
     const flashTimerRef = useRef(null);
@@ -76,10 +78,21 @@ export function DevScreen({ top: initialTop, left }) {
             if (modalId)
                 closeDevTool();
         });
+        const u4 = boundKeyboard(['ctrl+g'], () => {
+            openModal('__global-display__', GlobalKeyDisplayBox, {
+                top: initialTop + 3,
+                // Add three to prevent complete coverage of the DevBox from fragmenting the visual experience
+                left: left
+            });
+            // Actually, we don't need to pass in zindex here.
+            // Because the current mechanism is that when no zindex is passed, the following modal box overwrites the preceding modal box by default
+            // And our automatic activation mechanism ensures that it is also the one in the highest mode box.
+        });
         return () => {
             u1();
             u2();
             u3();
+            u4();
         };
     }, [modalId]);
     // When the terminal is resized the current position may land outside
@@ -132,7 +145,7 @@ export function DevScreen({ top: initialTop, left }) {
             React.createElement(Text, { dimColor: true },
                 "Screens: ",
                 currentPath.length,
-                "  |  \u2191\u2193 Move  |  Esc Close"),
+                "  |  \u2191\u2193 Move  |  Esc CloseI | Ctrl + G GlobalKeys Display"),
             React.createElement(Text, { dimColor: true },
                 "Top: ",
                 offsetTop,

package/dist/dev/entrance.d.ts

@@ -32,9 +32,7 @@ import { DevProps } from "./types.js";
  * });
  * ```
  */
-export declare function openDevTool({ top, left, zindex }: DevProps & {
-    zindex?: number;
-}): void;
+export declare function openDevTool({ top, left, zindex }: DevProps): void;
 /**
  * Close the developer debugging modal.
  *

package/dist/dev/globalKey-display.d.ts

@@ -1,2 +1,3 @@
 import React from "react";
-export default function GlobalKeyDisplayBox(): React.JSX.Element;
+import { GlobalProps } from "./types.js";
+export default function GlobalKeyDisplayBox({ top: initialTop, left }: GlobalProps): React.JSX.Element;

package/dist/dev/globalKey-display.js

@@ -1,8 +1,147 @@
-import { Box } from "ink";
-import React from "react";
-// This modal box is used to display information about all registered global keys.
-// Because it is a modal box, its keyboard is independent and will not be affected by DevTool.
-// Also make sure that the zindex is greater than the zindex of the DevTool so that the visual effects and keyboard reception are applied correctly when the modal box is opened
-export default function GlobalKeyDisplayBox() {
-    return (React.createElement(Box, { position: "absolute" }));
+import React, { useContext, useEffect, useRef, useState } from "react";
+import { Box, Text, useWindowSize } from "ink";
+import { useKeyboard } from "../keyboard/hook.js";
+import { ModalContext } from "../screen/ModalContext.js";
+import { useScreenSystem } from "../screen/hook.js";
+import { registerComponent } from "../screen/registry.js";
+import { SelectInput } from "../components/select/SelectInput.js";
+// This modal box displays information about all registered global keys.
+// Because it is a modal, its keyboard is independent and will not be
+// affected by DevTool. When the user presses Enter on a list item the
+// detail panel expands; Enter again collapses back to the list.
+// @2026-07-16 v3.6.2
+const PANEL_HEIGHT = 30;
+/**
+ * Build a compact label for a global key entry.
+ *
+ * Shows the key name(s) followed by short badges for non-default options:
+ * `[ao]` = affectOverlay, `[xno]` = executeWhenNoOverlay, `[×N]` = times.
+ */
+function buildLabel(entry) {
+    const keys = Array.isArray(entry.key) ? entry.key.join(', ') : entry.key;
+    const badges = [];
+    if (entry.affectOverlay)
+        badges.push('[ao]');
+    if (entry.executeWhenNoOverlay)
+        badges.push('[xno]');
+    if (entry.times !== undefined)
+        badges.push(`[×${entry.times}]`);
+    return badges.length > 0 ? `${keys}  ${badges.join(' ')}` : keys;
 }
+function fmtCategory(category) {
+    if (category === undefined || category === '*')
+        return '*';
+    return category.map(c => c.displayName || c.name || '?').join(', ');
+}
+/** Renders a boolean value in green (true) or red (false). */
+function BoolVal({ v }) {
+    const c = v === false ? 'red' : 'green';
+    return React.createElement(Text, { color: c }, String(v ?? true));
+}
+/** Two-column detail row: dim label on left, value slot on right. */
+function Row({ label, children }) {
+    return (React.createElement(Box, { flexDirection: "row" },
+        React.createElement(Box, { width: 18 },
+            React.createElement(Text, { dimColor: true }, label)),
+        children));
+}
+/** Blue separator line for visual sectioning. */
+const Sep = () => (React.createElement(Box, null,
+    React.createElement(Text, { color: "blue", dimColor: true }, "─".repeat(50))));
+export default function GlobalKeyDisplayBox({ top: initialTop, left }) {
+    const { getGlobalKeys, boundKeyboard } = useKeyboard();
+    const { closeModal } = useScreenSystem();
+    const modalId = useContext(ModalContext);
+    const { rows } = useWindowSize();
+    const [offsetTop, setOffsetTop] = useState(initialTop);
+    const [expandedEntry, setExpandedEntry] = useState(null);
+    const clampTopRef = useRef((next) => next);
+    clampTopRef.current = (next) => Math.max(0, Math.min(next, rows - PANEL_HEIGHT));
+    const expandedEntryRef = useRef(expandedEntry);
+    expandedEntryRef.current = expandedEntry;
+    // Bind return at the screen level so Enter collapses the detail panel.
+    // When the SelectInput is rendered (not expanded), its focus-level
+    // return binding takes priority and this binding is never reached.
+    useEffect(() => {
+        const unReturn = boundKeyboard(['return'], () => {
+            if (expandedEntryRef.current) {
+                setExpandedEntry(null);
+            }
+        });
+        return () => { unReturn(); };
+    }, []);
+    // Panel movement via up/down arrow keys
+    useEffect(() => {
+        const uUp = boundKeyboard(['up'], () => setOffsetTop(prev => clampTopRef.current(prev - 1)), {
+            focusId: 'globalKey-control'
+        });
+        const uDown = boundKeyboard(['down'], () => setOffsetTop(prev => clampTopRef.current(prev + 1)), {
+            focusId: 'globalKey-control'
+        });
+        return () => { uUp(); uDown(); };
+    }, []);
+    useEffect(() => {
+        const unEscape = boundKeyboard(['escape'], () => {
+            if (modalId)
+                closeModal(modalId);
+        });
+        return () => { unEscape(); };
+    }, [modalId]);
+    // Re-clamp on terminal resize
+    useEffect(() => {
+        setOffsetTop(prev => clampTopRef.current(prev));
+    }, [rows]);
+    const entries = getGlobalKeys();
+    const items = entries.map((entry, i) => ({
+        label: buildLabel(entry),
+        value: entry,
+        Key: `gk-${i}`,
+    }));
+    const handleSelect = (item) => {
+        if (expandedEntry === item.value) {
+            setExpandedEntry(null);
+        }
+        else {
+            setExpandedEntry(item.value);
+        }
+    };
+    return (React.createElement(Box, { position: "absolute", top: offsetTop, left: left, height: PANEL_HEIGHT, width: '100%', borderStyle: 'bold', borderColor: 'white', backgroundColor: 'black', flexDirection: "column", paddingX: 1, paddingY: 1 },
+        React.createElement(Box, null,
+            React.createElement(Text, { bold: true, color: "cyan" }, "\u258C Global Keys "),
+            React.createElement(Text, { dimColor: true },
+                "(",
+                entries.length,
+                ")")),
+        React.createElement(Sep, null),
+        expandedEntry ? (React.createElement(Box, { flexDirection: "column", paddingY: 1 },
+            React.createElement(Box, { paddingBottom: 1 },
+                React.createElement(Text, { color: "yellow", bold: true }, Array.isArray(expandedEntry.key) ? expandedEntry.key.join(', ') : expandedEntry.key)),
+            React.createElement(Sep, null),
+            React.createElement(Box, { paddingY: 1, flexDirection: "column" },
+                React.createElement(Row, { label: "Cover" },
+                    React.createElement(BoolVal, { v: expandedEntry.cover })),
+                React.createElement(Row, { label: "AffectOverlay" },
+                    React.createElement(BoolVal, { v: expandedEntry.affectOverlay })),
+                React.createElement(Row, { label: "ExecWhenNoOv" },
+                    React.createElement(BoolVal, { v: expandedEntry.executeWhenNoOverlay })),
+                React.createElement(Row, { label: "Times" },
+                    React.createElement(Text, { color: "white" }, expandedEntry.times ?? '—')),
+                React.createElement(Row, { label: "Category" },
+                    React.createElement(Text, { color: "white" }, fmtCategory(expandedEntry.category))),
+                React.createElement(Row, { label: "When" },
+                    React.createElement(BoolVal, { v: expandedEntry.when != null })),
+                React.createElement(Row, { label: "Observer" },
+                    React.createElement(BoolVal, { v: expandedEntry.observer != null }))))) : items.length === 0 ? (React.createElement(Box, { flexGrow: 1, justifyContent: "center", alignItems: "center" },
+            React.createElement(Text, { color: "gray" }, "No global keys registered."))) : (React.createElement(SelectInput, { items: items, onSelect: handleSelect, focusId: "global-key-list", limit: 9 })),
+        React.createElement(Sep, null),
+        React.createElement(Box, { paddingTop: 1 },
+            React.createElement(Text, { dimColor: true }, expandedEntry
+                ? 'Enter: collapse  |  Esc: close'
+                : 'Tab: switch focus  |  Enter: details  |  Esc: close')),
+        !expandedEntry && (React.createElement(Box, null,
+            React.createElement(Text, { dimColor: true }, "After collapsing from detail, press Tab to restore the selection highlight.")))));
+}
+registerComponent(GlobalKeyDisplayBox, {
+    top: 0,
+    left: 0
+});

package/dist/dev/types.d.ts

@@ -6,4 +6,18 @@ export interface DevProps {
     top: number;
     /** Horizontal position in columns — 0 is the left edge. */
     left: number;
+    zindex?: number;
+}
+/**
+ * Props accepted by the {@link GlobalKeyDisplayBox} global-keys inspector modal.
+ *
+ * Opened via `Ctrl+G` while the {@link DevScreen} modal is active. Renders as
+ * a white-bordered panel listing all registered global key bindings with
+ * expandable detail cards.
+ */
+export interface GlobalProps {
+    /** Vertical position in rows — 0 is the top of the terminal. */
+    top: number;
+    /** Horizontal position in columns — 0 is the left edge. */
+    left: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ink-cartridge",
-    "version": "3.6.1",
+    "version": "3.7.0",
     "description": "Ready-to-use Ink components and screen management system for building terminal UIs.",
     "type": "module",
     "main": "./dist/index.js",