@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/widgets/event-router.d.ts

@@ -0,0 +1,71 @@
+/**
+ * EventRouter — parses raw stdin into KeyEvent / ScreenMouseEvent values
+ * and dispatches them to widgets via a FocusManager and the frame on screen.
+ *
+ * It reads the terminal and never sets it up: raw mode and mouse tracking are
+ * the runtime's (`App`), which undoes them on every path out.
+ *
+ * [LAW:single-enforcer] ANSI escape parsing lives only here — widgets never
+ * see raw bytes. One parser, one dispatch surface.
+ *
+ * [LAW:dataflow-not-control-flow] The same parse pipeline runs for every
+ * input chunk: append → consume one event at a time until the buffer can't
+ * yield more. The byte's value, not a side-mode, decides which event is
+ * emitted. There is no "are we mid-sequence" mode flag — the buffer head
+ * carries all the state we need.
+ *
+ * Lone-ESC handling: a bare `\x1b` is ambiguous (escape key vs. start of a
+ * CSI sequence). When the buffer is drained but ends with a lone ESC, the
+ * router defers emission via setTimeout(0). The next chunk cancels the timer
+ * if it extends the sequence. Tests can call `flush()` to drain synchronously.
+ */
+import { KeyEvent } from "./types.js";
+import type { FrameSource, ScreenMouseEvent, KeyHandlerOptions } from "./types.js";
+import type { Unsubscribe } from "../core/subscription.js";
+import type { TerminalHost } from "../host/terminal-host.js";
+type KeyHandler = (event: KeyEvent) => void;
+export interface EventRouterOptions {
+    source: FrameSource;
+    /** The I/O capability the router reads input from. */
+    host: TerminalHost;
+}
+export declare class EventRouter {
+    private readonly source;
+    private readonly host;
+    private buffer;
+    private running;
+    private dataUnsubscribe;
+    private escTimer;
+    private captured;
+    private pointer;
+    private hoveredWidget;
+    private readonly keyChain;
+    private readonly mouseHandlers;
+    constructor(options: EventRouterOptions);
+    start(): void;
+    stop(): void;
+    /**
+     * Read hover again off the frame just painted: under a pointer that has not
+     * moved, a widget may have gone, moved, or arrived.
+     *
+     * [LAW:one-source-of-truth] Hover is the widget under the pointer on the
+     * frame on screen, so it is re-read whenever either one changes.
+     */
+    framePainted(): void;
+    onKey(handler: KeyHandler, options?: KeyHandlerOptions): Unsubscribe;
+    onMouse(handler: (event: ScreenMouseEvent) => void): Unsubscribe;
+    /** Feed a chunk of bytes (or a string of bytes) into the parser. */
+    feed(chunk: Uint8Array | string): void;
+    /** Force any pending lone ESC out of the buffer. */
+    flush(): void;
+    private drain;
+    private consumeOne;
+    private consumePrintable;
+    private consumeEscape;
+    private consumeSS3;
+    private consumeCSI;
+    private dispatchKey;
+    private dispatchMouse;
+    private hover;
+}
+export {};