magus-cli 7.3.1 → 7.4.0

package/src/ui/screens/StylesScreen.tsx

@@ -41,7 +41,8 @@ import {
 import { EmptyFilterState } from "../components/EmptyFilterState.js";
 import { ScrollableList } from "../components/ScrollableList.js";
 import { ScreenLayout } from "../components/layout/index.js";
-import { useKeyboard } from "../hooks/useKeyboard.js";
+import { useScreenKeys, useSearchInput } from "../input/KeyRouter.js";
+import { type BindingId, moveDirection } from "../keymap.js";
 import {
 	renderStyleDetail,
 	renderStyleRow,
@@ -57,7 +58,7 @@ export function StylesScreen() {
 	const modal = useModal();
 
 	const isSearchActive =
-		state.isSearching && state.currentRoute.screen === "styles" && !state.modal;
+		state.isSearching && state.currentRoute.screen === "styles";
 
 	// ── Data ──────────────────────────────────────────────────────────────────
 
@@ -748,120 +749,93 @@ export function StylesScreen() {
 		[stylesState.selectedIndex, allItems, dispatch],
 	);
 
-	useKeyboard((event) => {
-		if (state.modal) return;
-
-		// The previous message belongs to the previous ACTION, so clearing it here
-		// covers every action key in one place and replaces the 5-second timer
-		// that used to erase messages while they were still being read.
-		//
-		// Navigation is excluded. A digit or Tab is handled by the global
-		// handler, not by this screen — and clearing on it wiped the message on
-		// the way OUT of the tab, so a round trip lost it even though the state
-		// now survives the unmount.
-		const isNavigation =
-			/^[0-9]$/.test(event.name ?? "") || event.name === "tab";
-		if (stylesState.status && !isNavigation) {
-			dispatch({ type: "STYLES_STATUS_CLEAR" });
-		}
-
-		const hasQuery = stylesState.searchQuery.length > 0;
-
-		if (event.name === "escape") {
-			if (hasQuery || isSearchActive) {
-				dispatch({ type: "STYLES_SET_SEARCH", query: "" });
-				dispatch({ type: "SET_SEARCHING", isSearching: false });
-				dispatch({ type: "STYLES_SELECT", index: 0 });
-			}
-			return;
-		}
-
-		if (event.name === "backspace" || event.name === "delete") {
-			if (hasQuery) {
-				dispatch({ type: "STYLES_SEARCH_BACKSPACE" });
-				// Leaving search mode is driven by what was there BEFORE this
-				// keystroke, which is the one thing the closure does know reliably.
-				if (stylesState.searchQuery.length <= 1) {
-					dispatch({ type: "SET_SEARCHING", isSearching: false });
-				}
-			}
-			return;
-		}
+	// The search box, while it has focus: digits, j/k, q and ? are typed here.
+	useSearchInput({
+		focused: isSearchActive,
+		query: stylesState.searchQuery,
+		append: (char) => dispatch({ type: "STYLES_SEARCH_APPEND", char }),
+		erase: () => dispatch({ type: "STYLES_SEARCH_BACKSPACE" }),
+		clear: () => {
+			dispatch({ type: "STYLES_SET_SEARCH", query: "" });
+			dispatch({ type: "STYLES_SELECT", index: 0 });
+		},
+		blur: () => dispatch({ type: "SET_SEARCHING", isSearching: false }),
+	});
 
-		if (event.name === "up") {
-			if (isSearchActive)
-				dispatch({ type: "SET_SEARCHING", isSearching: false });
-			move(-1);
-			return;
-		}
-		if (event.name === "down") {
-			if (isSearchActive)
-				dispatch({ type: "SET_SEARCHING", isSearching: false });
-			move(1);
-			return;
-		}
+	/**
+	 * The previous message belongs to the previous ACTION, so every key this
+	 * screen acts on clears it first. Keys another layer takes — a digit or Tab
+	 * leaving the tab, text typed into the search box — leave it alone, so a
+	 * round trip through another tab keeps it.
+	 */
+	const clearStatus = () => {
+		if (stylesState.status) dispatch({ type: "STYLES_STATUS_CLEAR" });
+	};
 
-		if (event.name === "space" || event.name === " ") {
+	useScreenKeys("styles", {
+		toggle: () => {
+			clearStatus();
 			handleToggle();
-			return;
-		}
-
-		if (event.name === "return" || event.name === "enter") {
-			if (isSearchActive) {
-				dispatch({ type: "SET_SEARCHING", isSearching: false });
-				return;
-			}
-			// Enter opens the style for editing; Space is the ticking key. Enter
-			// reads as "go into this thing", and ticking already has a key that
-			// means exactly that and nothing else.
-			handleOpen();
-			return;
-		}
-
-		// While typing a filter, letters are text — not commands.
-		if (isSearchActive) {
-			if (
-				event.name &&
-				event.name.length === 1 &&
-				!event.ctrl &&
-				!event.meta &&
-				!/[0-9]/.test(event.name)
-			) {
-				dispatch({ type: "STYLES_SEARCH_APPEND", char: event.name });
-			}
-			return;
-		}
-
-		// Shift+U is tested BEFORE plain u. OpenTUI reports it as
-		// `{name: "u", shift: true}`, so a lowercase branch above this one would
-		// swallow it — the exact bug `uppercase-keybindings.test.ts` exists for.
-		if (event.name === "u" && event.shift) {
-			handleCheckUpdates(true);
-		} else if (event.name === "u") {
-			handleCheckUpdates(false);
-		} else if (event.name === "k") {
-			move(-1);
-		} else if (event.name === "j") {
-			move(1);
-		} else if (event.name === "a") {
-			handleApply();
-		} else if (event.name === "c") {
-			handleClear();
-		} else if (event.name === "x") {
+		},
+		apply: () => {
+			clearStatus();
+			void handleApply();
+		},
+		fill: () => {
+			clearStatus();
+			void handleFillTemplate();
+		},
+		clear: () => {
+			clearStatus();
+			void handleClear();
+		},
+		// Enter opens the style for editing; Space is the ticking key. Enter
+		// reads as "go into this thing", and ticking already has a key that
+		// means exactly that and nothing else.
+		edit: () => {
+			clearStatus();
+			void handleOpen();
+		},
+		fetch: () => {
+			clearStatus();
+			void handleFetch();
+		},
+		new: () => {
+			clearStatus();
+			void handleNewTeamStyle();
+		},
+		check: () => {
+			clearStatus();
+			void handleCheckUpdates(false);
+		},
+		"check-all": () => {
+			clearStatus();
+			void handleCheckUpdates(true);
+		},
+		reset: () => {
+			clearStatus();
 			handleReset();
-		} else if (event.name === "n") {
-			handleNewTeamStyle();
-		} else if (event.name === "e") {
-			handleOpen();
-		} else if (event.name === "f") {
-			handleFetch();
-		} else if (event.name === "t") {
-			handleFillTemplate();
-		} else if (event.name === "r") {
-			fetchData();
-		} else if (event.name === "/") {
+		},
+		refresh: () => {
+			clearStatus();
+			void fetchData();
+		},
+		search: () => {
+			clearStatus();
 			dispatch({ type: "SET_SEARCHING", isSearching: true });
-		}
+		},
+		// Only while a committed filter is set; otherwise Esc is the global back.
+		"clear-filter": () => {
+			if (!stylesState.searchQuery) return false;
+			clearStatus();
+			dispatch({ type: "STYLES_SET_SEARCH", query: "" });
+			dispatch({ type: "STYLES_SELECT", index: 0 });
+			return true;
+		},
+		move: (key) => {
+			clearStatus();
+			move(moveDirection(key));
+		},
 	});
 
 	// ── Status line ───────────────────────────────────────────────────────────
@@ -887,7 +861,7 @@ export function StylesScreen() {
 			{statusMsg.text}
 		</text>
 	) : isFilling ? (
-		<text fg={theme.colors.warning}>
+		<text fg={theme.colors.muted}>
 			Reading the codebase to fill a template… this can take a few minutes
 		</text>
 	) : undefined;
@@ -910,9 +884,9 @@ export function StylesScreen() {
 				<span fg={theme.colors.info}>{` │ profile ${snapshot.profile}`}</span>
 			) : null}
 			{isApplying ? (
-				<span fg={theme.colors.warning}> │ applying…</span>
+				<span fg={theme.colors.muted}> │ applying…</span>
 			) : isFetching ? (
-				<span fg={theme.colors.warning}> │ talking to GitHub…</span>
+				<span fg={theme.colors.muted}> │ talking to GitHub…</span>
 			) : errors.length > 0 ? (
 				<span fg={theme.colors.danger}> │ selection invalid</span>
 			) : syncState === "not-applied" ? (
@@ -948,41 +922,26 @@ export function StylesScreen() {
 		selectedItem?.kind === "style" &&
 		selectedItem.source.kind === "imported" &&
 		selectedItem.source.origin === "community";
-	const selectedHasUpdate =
-		selectedItem?.kind === "style" &&
-		selectedItem.upstream?.state === "update-available";
 
 	/**
-	 * Row-sensitive, and it has to REPLACE rather than append.
-	 *
-	 * The tab bar already degrades at about 94 columns, so a footer that only
-	 * grows pushes itself off the screen on a split pane. `n` and `e` stay bound
-	 * on a community row; they are simply not the keys that row is about.
+	 * Row-sensitive: the footer advertises the keys this row is about. `n` and
+	 * `e` stay bound on a community row; they are simply not what that row is
+	 * for. Everything hidden here still works and is still listed in help.
 	 */
-	const rowHints = selectedIsOffer
-		? [
-				{ keys: ["Space"], label: "fetch" },
-				{ keys: ["a"], label: "apply" },
-			]
+	const rowHidden: BindingId<"styles">[] = selectedIsOffer
+		? ["edit", "new", "fill", "check", "check-all", "reset"]
 		: selectedIsCommunity
-			? [
-					{ keys: ["Space"], label: "toggle" },
-					{ keys: ["a"], label: "apply" },
-					{
-						keys: ["f"],
-						label: selectedHasUpdate ? "accept update" : "re-fetch",
-					},
-					{ keys: ["u"], label: "check" },
-				]
+			? ["new", "edit", "fill"]
 			: [
-					{ keys: ["Space"], label: "toggle" },
-					{ keys: ["a"], label: "apply" },
-					{ keys: ["n"], label: "new" },
-					{ keys: ["e"], label: "edit" },
-					...(selectedIsTemplate
-						? [{ keys: ["t"], label: "fill from codebase" }]
-						: []),
+					"fetch",
+					"check",
+					"check-all",
+					...(selectedIsTemplate ? [] : ["fill" as const]),
 				];
+	const hiddenHints: BindingId<"styles">[] = [
+		...rowHidden,
+		...(stylesState.searchQuery ? [] : ["clear-filter" as const]),
+	];
 
 	return (
 		<ScreenLayout
@@ -999,24 +958,12 @@ export function StylesScreen() {
 						}
 					: undefined
 			}
-			footerHints={
-				isSearchActive
-					? [
-							{ keys: ["type"], label: "filter" },
-							{ keys: ["Enter"], label: "done" },
-							{ keys: ["Esc"], label: "clear" },
-						]
-					: [
-							...rowHints,
-							{ keys: ["c"], label: "clear" },
-							{ keys: ["/"], label: "filter" },
-						]
-			}
+			footer={{ hide: hiddenHints }}
 			listPanel={(listWidth) => (
 				<box flexDirection="column">
 					{stylesState.snapshot.status === "loading" && (
 						<box paddingLeft={2}>
-							<text fg={theme.colors.warning}>Reading styles…</text>
+							<text fg={theme.colors.muted}>Reading styles…</text>
 						</box>
 					)}
 

package/src/ui/state/AppContext.tsx

@@ -7,6 +7,7 @@ import type {
 	ModalState,
 	ProgressState,
 	Route,
+	Screen,
 } from "./types.js";
 
 // ============================================================================
@@ -204,6 +205,11 @@ export function useModal() {
 				},
 			});
 		},
+
+		/** The key help overlay, with `screen`'s keys first. Esc or `?` closes it. */
+		help: (screen: Screen) => {
+			dispatch({ type: "SHOW_MODAL", modal: { type: "help", screen } });
+		},
 	};
 }
 

package/src/ui/state/DimensionsContext.tsx

@@ -27,8 +27,6 @@ interface DimensionsProviderProps {
 	children: React.ReactNode;
 	/** Whether progress bar is visible */
 	showProgress?: boolean;
-	/** Whether debug bar is visible */
-	showDebug?: boolean;
 	/** Whether update banner is visible */
 	showUpdateBanner?: boolean;
 	/** Number of transient banners (recovery, mismatch) currently visible */
@@ -39,7 +37,6 @@ function calculateDimensions(
 	columns: number,
 	rows: number,
 	showProgress: boolean,
-	showDebug: boolean,
 	showUpdateBanner: boolean,
 	transientBannerCount: number,
 ): Dimensions {
@@ -49,7 +46,6 @@ function calculateDimensions(
 	// Calculate total available height for ScreenLayout (includes its header, panels, footer)
 	let contentHeight = terminalHeight - APP_MARGINS;
 	if (showProgress) contentHeight -= PROGRESS_HEIGHT;
-	if (showDebug) contentHeight -= 1;
 	if (showUpdateBanner) contentHeight -= 1;
 	contentHeight -= transientBannerCount;
 	contentHeight = Math.max(10, contentHeight); // Minimum 10 lines for full layout
@@ -77,7 +73,6 @@ function calculateDimensions(
 export function DimensionsProvider({
 	children,
 	showProgress = false,
-	showDebug = false,
 	showUpdateBanner = false,
 	transientBannerCount = 0,
 }: DimensionsProviderProps) {
@@ -88,7 +83,6 @@ export function DimensionsProvider({
 			renderer.width,
 			renderer.height,
 			showProgress,
-			showDebug,
 			showUpdateBanner,
 			transientBannerCount,
 		),
@@ -101,21 +95,19 @@ export function DimensionsProvider({
 				width,
 				height,
 				showProgress,
-				showDebug,
 				showUpdateBanner,
 				transientBannerCount,
 			),
 		);
 	});
 
-	// Update when showProgress/showDebug/showUpdateBanner/transientBannerCount changes
+	// Update when showProgress/showUpdateBanner/transientBannerCount changes
 	useEffect(() => {
 		setDimensions(
 			calculateDimensions(
 				renderer.width,
 				renderer.height,
 				showProgress,
-				showDebug,
 				showUpdateBanner,
 				transientBannerCount,
 			),
@@ -124,7 +116,6 @@ export function DimensionsProvider({
 		renderer.width,
 		renderer.height,
 		showProgress,
-		showDebug,
 		showUpdateBanner,
 		transientBannerCount,
 	]);

package/src/ui/state/reducer.ts

@@ -12,7 +12,6 @@ export const initialState: AppState = {
 	modal: null,
 	progress: null,
 	isSearching: false,
-	detailActive: false,
 
 	// Refresh counter for triggering data refetch
 	dataRefreshVersion: 0,
@@ -104,9 +103,8 @@ export function appReducer(state: AppState, action: AppAction): AppState {
 			return {
 				...state,
 				currentRoute: action.route,
-				// Clear transient sub-view state when navigating away
+				// A search box belongs to the screen it was opened on.
 				isSearching: false,
-				detailActive: false,
 			};
 
 		// =========================================================================
@@ -771,11 +769,13 @@ export function appReducer(state: AppState, action: AppAction): AppState {
 		// =========================================================================
 		// Modals
 		// =========================================================================
+		// The modal key layer shields everything below it, so opening a dialog
+		// leaves a focused search box focused for when it closes.
 		case "SHOW_MODAL":
-			return { ...state, modal: action.modal, isSearching: true };
+			return { ...state, modal: action.modal };
 
 		case "HIDE_MODAL":
-			return { ...state, modal: null, isSearching: false };
+			return { ...state, modal: null };
 
 		// =========================================================================
 		// Progress
@@ -795,9 +795,6 @@ export function appReducer(state: AppState, action: AppAction): AppState {
 		case "SET_SEARCHING":
 			return { ...state, isSearching: action.isSearching };
 
-		case "SET_DETAIL_ACTIVE":
-			return { ...state, detailActive: action.detailActive };
-
 		// =========================================================================
 		// Data Refresh
 		// =========================================================================

package/src/ui/state/types.ts

@@ -131,6 +131,11 @@ export type ModalState =
 	| {
 			type: "loading";
 			message: string;
+	  }
+	| {
+			/** The key help overlay, opened with `?`, listing `screen` first. */
+			type: "help";
+			screen: Screen;
 	  };
 
 // ============================================================================
@@ -348,12 +353,12 @@ export interface AppState {
 	// Global UI state
 	modal: ModalState | null;
 	progress: ProgressState | null;
+	/**
+	 * The current screen's search box has focus. It decides what the box draws
+	 * and whether the screen's input key layer is active; key routing itself
+	 * reads no flag — see ui/input/key-dispatch.ts.
+	 */
 	isSearching: boolean;
-	// True while a screen has a focused sub-view open that owns Escape (e.g.
-	// the Alias tab's flag-detail editor). The global key handler skips its
-	// Escape→navigate branch so Escape backs out of the sub-view instead of
-	// jumping to the home tab. Mirrors how `modal`/`isSearching` gate keys.
-	detailActive: boolean;
 
 	// Refresh counter - incremented when marketplace sync completes
 	// Screens can watch this to know when to refetch data
@@ -449,12 +454,9 @@ export type AppAction =
 	| { type: "UPDATE_PROGRESS"; state: ProgressState }
 	| { type: "HIDE_PROGRESS" }
 
-	// Search state (blocks global key handlers)
+	// Search box focus
 	| { type: "SET_SEARCHING"; isSearching: boolean }
 
-	// Detail sub-view state (gates global Escape→navigate)
-	| { type: "SET_DETAIL_ACTIVE"; detailActive: boolean }
-
 	// Profiles screen
 	| { type: "PROFILES_SELECT"; index: number }
 	| { type: "PROFILES_DATA_LOADING" }