tickmarkr 1.80.0 → 1.83.0

package/dist/tui/cockpit/keys.d.ts

@@ -0,0 +1,244 @@
+import { type RunViewId } from "./views.js";
+/**
+ * THE key contract for the run cockpit. This registry is the single source of
+ * truth for both halves of a key: what the keybar advertises and what the key
+ * does. The keybar's entries are derived from these bindings (`keybarEntries`),
+ * so a key with no registered handler cannot be drawn — an advertised key that
+ * does nothing is not expressible.
+ */
+/** The subset of an ink key event the run bindings discriminate on. */
+export type RunKeyEvent = {
+    readonly input: string;
+    readonly key: {
+        readonly upArrow?: boolean;
+        readonly downArrow?: boolean;
+        readonly leftArrow?: boolean;
+        readonly rightArrow?: boolean;
+        readonly return?: boolean;
+        readonly tab?: boolean;
+        readonly escape?: boolean;
+        readonly backspace?: boolean;
+        readonly delete?: boolean;
+        readonly ctrl?: boolean;
+    };
+};
+/**
+ * The observable interaction state of the run surface. RunCockpitFrame renders
+ * every field of it — selection pointer, panel focus, opened event, follow
+ * indicator, filter prompt, help overlay — so the initial state below renders
+ * byte-identical to a frame that carries no interaction state at all, and every
+ * transition away from it is a change an operator can see.
+ */
+/** The two top-level tabs: watch reads the engagement, setup writes to it. */
+export type RunTabId = "watch" | "setup";
+export type RunInteractionState = {
+    /** Which of the two tabs the surface draws — switched by Tab, never by a view. */
+    readonly tab: RunTabId;
+    /** The row in the active view the pointer marks; the overview has no rows. */
+    readonly selection: string | null;
+    /** The focused region, index into RUN_PANEL_FOCUS_ORDER — set by diving and backing out. */
+    readonly panel: number;
+    /** The selected rail row, independent from the view currently open. */
+    readonly railSelection: number;
+    /** The view drawn in the main region. */
+    readonly activeView: RunViewId;
+    /** The active view row opened by ⏎, or null while drawing the view itself. */
+    readonly opened: string | null;
+    /** Follow mode — toggled by f; drawn as a status-strip indicator while on. */
+    readonly follow: boolean;
+    /** The / prompt is open and taking filter text. */
+    readonly filterPrompt: boolean;
+    /** The text the journal is narrowed to — empty shows every row. */
+    readonly filterQuery: string;
+    /** Help overlay — toggled by ?. */
+    readonly help: boolean;
+    /** Quit requested by q. */
+    readonly quit: boolean;
+};
+export declare function initialRunInteractionState(): RunInteractionState;
+/**
+ * The panels the run surface's focus moves between, in their painted order;
+ * index 0 is the content panel, and the sidebar is the level every view backs
+ * out to. A width that hides the sidebar resolves every index onto the panel
+ * that remains (`runPanelFocusOrder`).
+ */
+export declare const RUN_PANEL_FOCUS_ORDER: readonly ["CONTENT", "VIEWS"];
+/**
+ * The state the live surface opens in: the watch tab, the sidebar focused, so
+ * the very first arrow key moves the view selection rather than a row. This is
+ * a second constructor rather than a change to the one above: the committed
+ * captures depict a surface with no interaction state at all, and only an
+ * operator-accepted capture may re-freeze them.
+ */
+export declare function openingRunInteractionState(tab?: RunTabId): RunInteractionState;
+/**
+ * The whole surface: the tab being drawn and the tab waiting behind it. Each
+ * half keeps its own selection, so Tab and Tab again returns an operator to
+ * exactly the row and view they left.
+ */
+export type RunSurfaceState = {
+    readonly interaction: RunInteractionState;
+    readonly stashed: RunInteractionState;
+};
+export declare function openingRunSurfaceState(): RunSurfaceState;
+/**
+ * The rows of a view a key may actually stand on. The journal is a tail, not a
+ * list: it is never selected, opened or filtered, in either tab. Stated once
+ * here so the dispatcher and the advertisement cannot disagree about it.
+ */
+export declare function selectableRunViewRowIds(viewId: RunViewId, rowIds: readonly string[]): readonly string[];
+/** The one width predicate shared by rendering, focus and key projection. */
+export declare const RUN_SIDE_RAIL_COLUMN_FLOOR = 80;
+export declare function runSideRailVisible(columns: number): boolean;
+export declare function runPanelFocusOrder(columns: number): readonly (typeof RUN_PANEL_FOCUS_ORDER)[number][];
+export type RunKeyProjectionContext = {
+    readonly interaction: RunInteractionState;
+    readonly columns: number;
+    /** Stable identities in the active view's filtered logical collection. */
+    readonly rowIds?: readonly string[];
+};
+export type RunKeyApplyContext = {
+    readonly rowIds: readonly string[];
+    /**
+     * The terminal width the dispatch was made at, so a handler resolves focus
+     * against the same effective width the advertisement did. Handlers invoked
+     * without a dispatch — tests driving a binding directly — assume the width
+     * that offers every key.
+     */
+    readonly columns?: number;
+};
+export declare function runFocusedPanel({ interaction, columns, }: RunKeyProjectionContext): (typeof RUN_PANEL_FOCUS_ORDER)[number];
+export type RunKeyBinding = {
+    /** The glyph the keybar draws, e.g. "↑↓". */
+    readonly key: string;
+    /** The promise the keybar draws next to the glyph, e.g. "Move". */
+    readonly label: string;
+    /** Whether a key event activates this binding. */
+    readonly matches: (event: RunKeyEvent) => boolean;
+    /** The state transition the label promises. */
+    readonly apply: (state: RunInteractionState, event: RunKeyEvent, context?: RunKeyApplyContext) => RunInteractionState;
+    /** Which projected contexts can actually observe this binding's transition. */
+    readonly available?: (context: RunKeyProjectionContext) => boolean;
+    /** Prompt bindings replace, rather than supplement, the normal roster. */
+    readonly scope?: "normal" | "filter-prompt";
+    /**
+     * How a binding that carries on/off state reports it — the brand's reserved
+     * toggle glyphs, never bracket toggles. Present exactly on the bindings
+     * whose state is on/off.
+     */
+    readonly report?: (state: RunInteractionState) => string;
+    /**
+     * The word naming where a switch key takes the operator from the current
+     * state — Tab promises the tab it will draw. Present exactly on bindings
+     * whose honest label depends on which side of the switch the surface is on.
+     */
+    readonly destination?: (state: RunInteractionState) => string;
+};
+/** A toggle's on/off report: the brand's reserved glyphs, never brackets. */
+export declare function toggleReport(label: string, on: boolean): string;
+/**
+ * Every key the run surface advertises, in keybar order. Each entry carries
+ * its handler, so advertisement and behaviour cannot drift apart.
+ */
+export declare const RUN_KEY_BINDINGS: readonly RunKeyBinding[];
+/**
+ * Number jumps name a view, and a digit means that one view on the whole
+ * surface — one key, one meaning, everywhere. Pressed on the setup tab, which
+ * holds sections rather than views, a digit switches to the tab that holds
+ * the views and lands on the one it numbers; setup waits behind with its own
+ * state intact for the round trip.
+ */
+export declare const RUN_VIEW_KEY_BINDING: RunKeyBinding;
+/** The filter prompt's own advertised and executable input roster. */
+export declare const RUN_FILTER_PROMPT_BINDINGS: readonly RunKeyBinding[];
+/** Every input binding the live run cockpit dispatches or the prompt owns. */
+export declare const RUN_INPUT_BINDINGS: readonly RunKeyBinding[];
+/** The panels the setup surface cycles through, in their painted order. */
+export declare const SETUP_PANEL_FOCUS_ORDER: readonly ["SETUP", "HARNESSES", "KEYS"];
+/**
+ * The observable state owned by setup's bindings. Its initial value is the
+ * already-pinned setup frame: step two, the harness body focused, nothing
+ * selected, no modal action open. Every handler moves away from that state in
+ * a way SetupCockpitFrame paints.
+ */
+export type SetupInteractionState = {
+    readonly selection: number;
+    readonly panel: number;
+    readonly step: number;
+    readonly selected: readonly number[];
+    readonly all: boolean;
+    readonly probeRevision: number;
+    readonly savePrompt: boolean;
+    readonly saved: boolean;
+    readonly help: boolean;
+    readonly quit: boolean;
+};
+export declare function initialSetupInteractionState(): SetupInteractionState;
+export type SetupKeyBinding = {
+    readonly key: string;
+    readonly label: string;
+    readonly matches: (event: RunKeyEvent) => boolean;
+    readonly apply: (state: SetupInteractionState, event: RunKeyEvent) => SetupInteractionState;
+    readonly report?: (state: SetupInteractionState) => string;
+};
+/**
+ * Every setup advertisement and handler, in the exact order the surface has
+ * always drawn. The global six are registered here with setup semantics; the
+ * six setup-only bindings follow them on the same surface registry.
+ */
+export declare const SETUP_KEY_BINDINGS: readonly SetupKeyBinding[];
+/** One surface-aware registry serves both cockpit renderers and dispatchers. */
+export declare const SURFACE_KEY_BINDINGS: {
+    readonly run: readonly RunKeyBinding[];
+    readonly setup: readonly SetupKeyBinding[];
+};
+/** Save confirmation owns input until it is accepted or dismissed. */
+export declare function applySetupPromptInput(event: RunKeyEvent, state: SetupInteractionState): SetupInteractionState | undefined;
+/** What an advertisement looks like once the handler is stripped away. */
+export type KeybarEntry = {
+    readonly key: string;
+    readonly label: string;
+};
+export type RunKeyProjection = (context: RunKeyProjectionContext) => readonly KeybarEntry[];
+/** The lossless text vocabulary shared by frame and plain advertisements. */
+export declare function formatKeybarEntries(entries: readonly KeybarEntry[]): string;
+/**
+ * THE one context projection over the one run registry. Consumers receive its
+ * return value whole; none may filter, append or independently map bindings.
+ */
+export declare function projectRunKeyEntries(context: RunKeyProjectionContext, bindings?: readonly RunKeyBinding[]): readonly KeybarEntry[];
+/**
+ * The keybar's entries, derived from a binding registry. This is the only way
+ * a keybar list is produced: remove a handler and its entry disappears.
+ */
+export declare function keybarEntries(bindings: readonly {
+    readonly key: string;
+    readonly label: string;
+}[]): readonly KeybarEntry[];
+/** The binding a key event activates, or undefined when no handler owns it. */
+export declare function resolveRunKeyBinding(bindings: readonly RunKeyBinding[], event: RunKeyEvent): RunKeyBinding | undefined;
+/**
+ * Re-establish the row invariant after a derivation or filter changes. The
+ * identities themselves are authoritative: an in-range position is never a
+ * substitute for the row that used to occupy it.
+ */
+export declare function reconcileRunInteraction(state: RunInteractionState, rowIds: readonly string[]): RunInteractionState;
+/**
+ * Send a key event to the registry: the matching binding's handler produces
+ * the next interaction state. An event no handler owns changes nothing — and
+ * while the / prompt is open the prompt's own scope is the only roster that
+ * owns anything, so a character grows the query rather than quitting the
+ * surface. One dispatcher decides that, so no caller can own the prompt twice.
+ */
+export declare function dispatchRunKey(event: RunKeyEvent, state: RunInteractionState, bindings?: readonly RunKeyBinding[], rowIds?: readonly string[], columns?: number): RunInteractionState | undefined;
+/**
+ * Send a key event to the whole surface. The registry owns every transition,
+ * including the tab flip; the surface only decides what a flipped tab means —
+ * the tab that was waiting comes forward carrying the state it was left in, and
+ * the tab that was drawn is what waits now.
+ */
+export declare function dispatchRunSurfaceKey(event: RunKeyEvent, surface: RunSurfaceState, bindings?: readonly RunKeyBinding[], rowIds?: readonly string[], columns?: number): RunSurfaceState | undefined;
+/** The setup binding a key event activates, or undefined when none owns it. */
+export declare function resolveSetupKeyBinding(bindings: readonly SetupKeyBinding[], event: RunKeyEvent): SetupKeyBinding | undefined;
+/** Send a key event through the setup half of the shared surface registry. */
+export declare function dispatchSetupKey(event: RunKeyEvent, state: SetupInteractionState, bindings?: readonly SetupKeyBinding[]): SetupInteractionState | undefined;