react-retro-display-tty-ansi-ascii 0.1.39 → 0.1.46

package/README.md

@@ -45,6 +45,66 @@ That is the whole entry point.
 You hand the component a mode, a value or controller when needed, and let it handle the grid,
 wrapping, cursor rendering, and terminal feel.
 
+## Touch Input
+
+Use `touchInput` when the display itself should behave like a touch surface and report
+grid-aligned cell hits back to the host application.
+
+The touch contract is intentionally simple:
+
+- the component emits 1-based `row` and `col` coordinates
+- it also reports the measured `rows` and `cols` that were active for that touch
+- input is delivered as a single `down` event for each press
+- long presses do not stream repeated events
+- move events are ignored by default in touch mode
+- the next touch is not accepted until the current press is released
+
+That makes it a good fit for grid-driven interfaces such as soft terminals, retro games,
+touch menus, and keypad-like overlays where the host wants to interpret one deliberate press
+at a time.
+
+```tsx
+import { useState } from "react";
+import { RetroScreen } from "react-retro-display-tty-ansi-ascii";
+import "react-retro-display-tty-ansi-ascii/styles.css";
+
+export function TouchDemo() {
+  const [lastTouch, setLastTouch] = useState("Tap the screen");
+
+  return (
+    <RetroScreen
+      mode="terminal"
+      gridMode="static"
+      rows={12}
+      cols={32}
+      value={[
+        "┌──────────────────────────────┐",
+        "│                              │",
+        "│          TOUCH ME            │",
+        "│                              │",
+        "│   ↑ up          right →      │",
+        "│                              │",
+        "│   ← left       down ↓        │",
+        "│                              │",
+        "│                              │",
+        "│                              │",
+        "│                              │",
+        "└──────────────────────────────┘"
+      ].join("\\n")}
+      touchInput={{
+        enabled: true,
+        onTouchCell: ({ row, col, rows, cols, pointerType }) => {
+          setLastTouch(`${pointerType} @ ${row},${col} inside ${rows}x${cols}`);
+        }
+      }}
+    />
+  );
+}
+```
+
+The host remains responsible for deciding what a touch means. RetroScreen only handles the
+overlay, pointer capture, hit testing, and the single-press-until-release behavior.
+
 ## Display Padding
 
 Use `displayPadding` when the screen content should sit tighter to the glass or breathe a little

package/dist/index.cjs

@@ -3915,6 +3915,10 @@ var joinClassNames2 = (...classNames) => classNames.filter(Boolean).join(" ");
 var useIsomorphicLayoutEffect2 = typeof window === "undefined" ? import_react9.useEffect : import_react9.useLayoutEffect;
 var clampSelection2 = (value, text) => Math.max(0, Math.min(text.length, Number.isFinite(value) ? Math.floor(value) : text.length));
 var isMouseTrackingActive = (snapshot) => snapshot.modes.mouseTrackingMode !== "none" && snapshot.modes.mouseProtocol === "sgr";
+var shouldHandleRetroTouchPointer = ({
+  enabled,
+  phase
+}) => Boolean(enabled) && phase === "down";
 var isEditorWordNavigationModifier = (event) => event.altKey || event.ctrlKey || event.metaKey;
 var isEditorSelectAllShortcut = (event) => (event.ctrlKey || event.metaKey) && !event.altKey && event.key.toLowerCase() === "a";
 var toTerminalMouseButton = (button) => {
@@ -3958,6 +3962,7 @@ function RetroScreen(props) {
   const editorProps = props.mode === "editor" ? props : null;
   const terminalProps = props.mode === "terminal" ? props : null;
   const promptProps = props.mode === "prompt" ? props : null;
+  const touchInput = props.touchInput;
   const screenRef = (0, import_react9.useRef)(null);
   const viewportRef = (0, import_react9.useRef)(null);
   const probeRef = (0, import_react9.useRef)(null);
@@ -3967,6 +3972,7 @@ function RetroScreen(props) {
   const editorSelectionAnchorRef = (0, import_react9.useRef)(null);
   const editorSelectionDraggingRef = (0, import_react9.useRef)(false);
   const previousEditableValueRef = (0, import_react9.useRef)(valueProps?.value ?? "");
+  const activeTouchPointerIdRef = (0, import_react9.useRef)(null);
   const internalTerminalController = useRetroScreenController({
     rows: staticGridActive ? props.rows : void 0,
     cols: staticGridActive ? props.cols : void 0,
@@ -4590,6 +4596,51 @@ function RetroScreen(props) {
       shiftKey: event.shiftKey
     };
   };
+  const handleTouchOverlayPointer = async (event, phase) => {
+    if (phase === "up") {
+      if (activeTouchPointerIdRef.current === event.pointerId) {
+        activeTouchPointerIdRef.current = null;
+      }
+      try {
+        if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+          event.currentTarget.releasePointerCapture(event.pointerId);
+        }
+      } catch {
+      }
+      return;
+    }
+    if (!touchInput?.onTouchCell || !shouldHandleRetroTouchPointer({ enabled: touchInput.enabled, phase })) {
+      return;
+    }
+    if (activeTouchPointerIdRef.current !== null && activeTouchPointerIdRef.current !== event.pointerId) {
+      return;
+    }
+    const screenNode = screenRef.current;
+    if (!screenNode) {
+      return;
+    }
+    const { row, col } = getRetroScreenPointerGridPosition({
+      clientX: event.clientX,
+      clientY: event.clientY,
+      rect: screenNode.getBoundingClientRect(),
+      geometry
+    });
+    activeTouchPointerIdRef.current = event.pointerId;
+    try {
+      event.currentTarget.setPointerCapture(event.pointerId);
+    } catch {
+    }
+    event.preventDefault();
+    await touchInput.onTouchCell({
+      row,
+      col,
+      rows: geometry.rows,
+      cols: geometry.cols,
+      phase,
+      pointerType: event.pointerType,
+      buttons: event.buttons
+    });
+  };
   const maybeEmitFocusReport = (focusedState) => {
     if (props.mode !== "terminal" || !captureTerminalFocusReport || !terminalSnapshot.modes.focusReportingMode) {
       return;
@@ -4822,6 +4873,26 @@ function RetroScreen(props) {
       "data-fit-width-content-aspect-ratio": fitWidthLayoutMetrics ? String(fitWidthLayoutMetrics.contentAspectRatio) : void 0,
       children: [
         /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { className: "retro-screen__bezel", "aria-hidden": "true" }),
+        touchInput?.enabled ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+          "div",
+          {
+            className: "retro-screen__touch-overlay",
+            "data-testid": touchInput.overlayTestId,
+            "aria-hidden": "true",
+            onPointerCancel: (event) => {
+              void handleTouchOverlayPointer(event, "up");
+            },
+            onPointerDown: (event) => {
+              void handleTouchOverlayPointer(event, "down");
+            },
+            onPointerMove: (event) => {
+              void handleTouchOverlayPointer(event, "move");
+            },
+            onPointerUp: (event) => {
+              void handleTouchOverlayPointer(event, "up");
+            }
+          }
+        ) : null,
         /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
           RetroScreenDisplay,
           {