magus-cli 0.0.0-placeholder → 7.0.0

package/src/ui/components/layout/ScreenLayout.tsx

@@ -0,0 +1,321 @@
+import type { ScrollBoxRenderable } from "@opentui/core";
+import type React from "react";
+import { useEffect, useRef } from "react";
+import { useKeyboard } from "../../hooks/useKeyboard.js";
+import { useApp } from "../../state/AppContext.js";
+import { useDimensions } from "../../state/DimensionsContext.js";
+import type { Screen } from "../../state/types.js";
+import { theme } from "../../theme.js";
+import { TabBar } from "../TabBar.js";
+import { type FooterHint, FooterHints } from "./FooterHints.js";
+
+/**
+ * Panel content: a node, or a function handed the panel's usable columns.
+ *
+ * The function form exists because the geometry below — the app frame's side
+ * padding, the 49/50 split, the panel padding and the scrollbar column — is
+ * ScreenLayout's, and a screen that re-derives it from `terminalWidth` is
+ * guessing at constants it cannot see. Both screens that wrap body text did
+ * exactly that, with the same hand-copied formula, and both were wrong.
+ *
+ * `React.ReactNode` does not include functions, so the union is unambiguous.
+ */
+export type PanelContent =
+	| React.ReactNode
+	| ((width: number) => React.ReactNode);
+
+/**
+ * The app frame (App.tsx) pads the screen one column each side before
+ * ScreenLayout ever renders, so every percentage below resolves against
+ * `terminalWidth - 2`.
+ */
+const APP_SIDE_PADDING = 2;
+const LIST_FRACTION = 0.49;
+const DETAIL_FRACTION = 0.5;
+/** The list panel's own `paddingRight`. */
+const LIST_CHROME = 1;
+/** The detail panel's `paddingLeft`, plus the scrollbox's scrollbar column. */
+const DETAIL_CHROME = 2;
+
+/** Columns a panel's content can actually use, at this terminal width. */
+function panelWidth(
+	terminalWidth: number,
+	fraction: number,
+	chrome: number,
+): number {
+	const inner = Math.max(1, terminalWidth - APP_SIDE_PADDING);
+	return Math.max(8, Math.floor(inner * fraction) - chrome);
+}
+
+/**
+ * Usable columns in the list panel.
+ *
+ * MEASURED against real renders at 70…200 columns, not derived from the JSX:
+ * Yoga rounds a fractional percentage to whole cells, so the arithmetic only
+ * matches the pixels if you check. This is exact at 8 of the 12 widths sampled
+ * and one column short at the other four, which is the safe direction — a
+ * budget one column under folds nothing, a budget one column over paints into
+ * the separator.
+ */
+export function listPanelWidth(terminalWidth: number): number {
+	return panelWidth(terminalWidth, LIST_FRACTION, LIST_CHROME);
+}
+
+/**
+ * Usable columns in the detail panel, scrollbar excluded.
+ *
+ * Exact at 11 of the 12 widths sampled, one column short at the twelfth. The
+ * formula each screen used to carry instead was `floor(width * 0.5) - 4`: it
+ * forgot the app frame's padding, counted the scrollbar twice, and then floored
+ * at 24 — so below about 56 columns it asked for MORE room than the panel has.
+ */
+export function detailPanelWidth(terminalWidth: number): number {
+	return panelWidth(terminalWidth, DETAIL_FRACTION, DETAIL_CHROME);
+}
+
+interface ScreenLayoutProps {
+	/** Screen title (e.g., "magus Plugins") */
+	title: string;
+	/** Optional subtitle shown to the right of title */
+	subtitle?: string;
+	/** Current screen for tab highlighting */
+	currentScreen: Screen;
+	/** Search bar configuration (for screens with search) */
+	search?: {
+		/** Is search currently active */
+		isActive: boolean;
+		/** Current search query */
+		query: string;
+		/** Placeholder when not searching (default: "/") */
+		placeholder?: string;
+	};
+	/** Status line content (for screens without search) - shown in second row */
+	statusLine?: React.ReactNode;
+	/**
+	 * One-line warning shown under the header, above the content.
+	 *
+	 * For conditions that make the data on screen untrustworthy — not for
+	 * transient progress. It sits in the fixed chrome rather than in a panel so it
+	 * cannot be scrolled out of view, and it takes a row from the panels only
+	 * while it is present.
+	 */
+	notice?: React.ReactNode;
+	/** Footer hints (left side). Pass a FooterHint[] to render key badges
+	 *  (the standard look). A string or ReactNode is still accepted for
+	 *  free-form footers. */
+	footerHints: FooterHint[] | string | React.ReactNode;
+	/** Left panel content, or a function given the list panel's usable columns. */
+	listPanel: PanelContent;
+	/** Right panel content, or a function given the detail panel's usable columns. */
+	detailPanel: PanelContent;
+	/**
+	 * Identity of the detail content, e.g. the selected row's id. When it
+	 * changes, the detail pane scrolls back to the top — a reading position
+	 * belongs to one document, not to the panel.
+	 */
+	detailKey?: string;
+}
+
+const HEADER_COLOR = theme.colors.accent;
+
+export function ScreenLayout({
+	title,
+	subtitle,
+	currentScreen,
+	search,
+	statusLine,
+	notice,
+	footerHints,
+	listPanel,
+	detailPanel,
+	detailKey,
+}: ScreenLayoutProps) {
+	const dimensions = useDimensions();
+	const { state } = useApp();
+
+	const hasSearchBar = search && (search.isActive || search.query);
+
+	// Fixed chrome: top line + tabs + line + header + separator + footer = 6
+	// Search bar adds 1 when active; the notice adds 1 while present.
+	const fixedHeight = 6 + (hasSearchBar ? 1 : 0) + (notice ? 1 : 0);
+	const panelHeight = Math.max(5, dimensions.contentHeight - fixedHeight);
+	const lineWidth = Math.max(10, dimensions.terminalWidth - 4);
+
+	const listContent =
+		typeof listPanel === "function"
+			? listPanel(listPanelWidth(dimensions.terminalWidth))
+			: listPanel;
+	const detailContent =
+		typeof detailPanel === "function"
+			? detailPanel(detailPanelWidth(dimensions.terminalWidth))
+			: detailPanel;
+
+	const detailScrollRef = useRef<ScrollBoxRenderable | null>(null);
+
+	// The detail pane has no cursor, so it needs its own scroll keys: arrows
+	// move the LIST selection, and the wheel only helps when the terminal
+	// delivers mouse reports (see src/main.tsx). PgUp/PgDn page with two rows
+	// of overlap so a page turn doesn't lose the reader's place; Ctrl+U/Ctrl+D
+	// half-page in the pager tradition — and exist because a MacBook keyboard
+	// hides PgDn behind Fn+↓, where nobody finds it.
+	const detailPageStep = Math.max(1, panelHeight - 2);
+	const detailHalfStep = Math.max(1, Math.floor(panelHeight / 2));
+	useKeyboard((event) => {
+		if (state.modal) return;
+		const ctrl = event.ctrl === true;
+		if (event.name === "pageup" || (ctrl && event.name === "u")) {
+			detailScrollRef.current?.scrollBy(
+				event.name === "pageup" ? -detailPageStep : -detailHalfStep,
+			);
+		} else if (event.name === "pagedown" || (ctrl && event.name === "d")) {
+			detailScrollRef.current?.scrollBy(
+				event.name === "pagedown" ? detailPageStep : detailHalfStep,
+			);
+		}
+	});
+
+	useEffect(() => {
+		if (detailKey !== undefined) detailScrollRef.current?.scrollTo(0);
+	}, [detailKey]);
+
+	return (
+		<box flexDirection="column" height={dimensions.contentHeight}>
+			{/* Line above tabs */}
+			<box height={1} paddingLeft={1} paddingRight={1}>
+				<text fg={theme.colors.dim}>{"─".repeat(lineWidth)}</text>
+			</box>
+
+			{/* Tab bar */}
+			<box height={1} paddingLeft={1} paddingRight={1}>
+				<TabBar currentScreen={currentScreen} />
+			</box>
+
+			{/* Line below tabs */}
+			<box height={1} paddingLeft={1} paddingRight={1}>
+				<text fg={theme.colors.dim}>{"─".repeat(lineWidth)}</text>
+			</box>
+
+			{/* Header — title on left, subtitle/status on right */}
+			<box
+				height={1}
+				paddingLeft={1}
+				paddingRight={1}
+				flexDirection="row"
+				justifyContent="space-between"
+			>
+				{/* The title never yields: an overlong right-hand status once
+				    shrank it away and the two texts read as one sentence. Long
+				    content belongs in the `notice` row, not beside the title. */}
+				<box flexShrink={0} marginRight={2}>
+					<text fg={HEADER_COLOR}>
+						<strong>{title}</strong>
+					</text>
+				</box>
+				{subtitle && <text fg={theme.colors.muted}>{subtitle}</text>}
+				{!subtitle && statusLine ? statusLine : null}
+			</box>
+
+			{/* Search bar — own line, only when active */}
+			{hasSearchBar && (
+				<box height={1} paddingLeft={1} paddingRight={1}>
+					{search.isActive ? (
+						<text fg={theme.colors.text}>
+							<span fg={theme.colors.success}>{"Filter: "}</span>
+							<span fg={theme.colors.text}>{search.query}</span>
+							<span bg={theme.colors.text} fg={theme.hints.fg}>
+								{" "}
+							</span>
+						</text>
+					) : (
+						<text fg={theme.colors.text}>
+							<span fg={theme.colors.success}>{"Filter: "}</span>
+							<span fg={theme.colors.warning}>{search.query}</span>
+							<span fg={theme.colors.muted}> (Esc to clear)</span>
+						</text>
+					)}
+				</box>
+			)}
+
+			{/* Warning line — only when the data on screen cannot be trusted */}
+			{notice && (
+				<box height={1} paddingLeft={1} paddingRight={1}>
+					{notice}
+				</box>
+			)}
+
+			{/* Separator below header */}
+			<box height={1} paddingLeft={1} paddingRight={1}>
+				<text fg={theme.colors.border}>{"─".repeat(lineWidth)}</text>
+			</box>
+
+			{/* Main content area */}
+			<box flexDirection="row" height={panelHeight}>
+				{/* List panel. `overflow="hidden"` is the safety net, not the plan:
+				    the box has a fixed height, so content taller than it does NOT
+				    scroll and does NOT clip on its own — Yoga shrinks the children
+				    and they composite on top of each other. MEASURED at 80×24:
+				    "fable-advisor" and "fable-lead" rendered as "fable-leadical".
+				    A screen that can overflow should budget its own rows; this
+				    stops the failure being unreadable when one does not. */}
+				<box
+					flexDirection="column"
+					width="49%"
+					height={panelHeight}
+					paddingRight={1}
+					overflow="hidden"
+				>
+					{listContent}
+				</box>
+
+				{/* Vertical separator */}
+				<box flexDirection="column" width={1} height={panelHeight}>
+					<text fg={theme.colors.border}>{"│".repeat(panelHeight)}</text>
+				</box>
+
+				{/* Detail panel — scrollable. The thumb is themed so the reader can
+				    see there is more below the fold; the track keeps the library
+				    default so it stays chrome, not signal. */}
+				{/* `overflow: hidden`, like the list panel opposite. Without it a line wider
+				    than the panel is drawn OUTSIDE it, over the terminal's right edge, and the
+				    reader loses characters off the end of a sentence with nothing to say they
+				    were lost. Clipping at the panel is the guarantee; wrapping to
+				    `detailPanelWidth` is what keeps there being nothing to clip. */}
+				<box width="50%" height={panelHeight} paddingLeft={1} overflow="hidden">
+					<scrollbox
+						ref={detailScrollRef}
+						height={panelHeight}
+						scrollY={true}
+						scrollX={false}
+						verticalScrollbarOptions={{
+							showArrows: false,
+							trackOptions: {
+								foregroundColor: theme.colors.muted,
+							},
+						}}
+					>
+						<box flexDirection="column">{detailContent}</box>
+					</scrollbox>
+				</box>
+			</box>
+
+			{/* Footer — the layout appends its own scroll hint so every screen
+			    advertises the detail-pane keys without each screen repeating it */}
+			<box height={1} paddingLeft={1}>
+				{Array.isArray(footerHints) ? (
+					<FooterHints
+						hints={[
+							...(footerHints as FooterHint[]),
+							{ keys: ["^U/^D", "PgUp/Dn"], label: "scroll" },
+						]}
+					/>
+				) : typeof footerHints === "string" ? (
+					<text fg={theme.colors.muted}>{footerHints}</text>
+				) : (
+					footerHints
+				)}
+			</box>
+		</box>
+	);
+}
+
+export default ScreenLayout;

package/src/ui/components/layout/index.ts

@@ -0,0 +1,9 @@
+export { Panel } from "./Panel.js";
+export { ScopeTabs } from "./ScopeTabs.js";
+export { ProgressBar } from "./ProgressBar.js";
+export { ScreenLayout } from "./ScreenLayout.js";
+export {
+	FooterHints,
+	renderFooterHints,
+	type FooterHint,
+} from "./FooterHints.js";

package/src/ui/components/modals/ConfirmModal.tsx

@@ -0,0 +1,62 @@
+import React from "react";
+import { useKeyboard } from "../../hooks/useKeyboard.js";
+import { theme } from "../../theme.js";
+
+interface ConfirmModalProps {
+	/** Modal title */
+	title: string;
+	/** Modal message */
+	message: string;
+	/** Callback when confirmed */
+	onConfirm: () => void;
+	/** Callback when cancelled */
+	onCancel: () => void;
+}
+
+export function ConfirmModal({
+	title,
+	message,
+	onConfirm,
+	onCancel,
+}: ConfirmModalProps) {
+	useKeyboard((key) => {
+		if (key.name === "y") {
+			onConfirm();
+		} else if (key.name === "n" || key.name === "escape") {
+			onCancel();
+		}
+	});
+
+	return (
+		<box
+			flexDirection="column"
+			border
+			borderStyle="rounded"
+			borderColor={theme.colors.dim}
+			backgroundColor={theme.surface.bg}
+			paddingLeft={3}
+			paddingRight={3}
+			paddingTop={1}
+			paddingBottom={1}
+			width={60}
+		>
+			<box marginBottom={1}>
+				<text fg={theme.colors.text}>
+					<strong>{title}</strong>
+				</text>
+			</box>
+			<box marginBottom={1}>
+				<text fg={theme.colors.muted}>{message}</text>
+			</box>
+			<box marginTop={1} flexDirection="row">
+				<text fg={theme.colors.muted}>Press </text>
+				<text fg={theme.colors.text}>Y</text>
+				<text fg={theme.colors.muted}> to confirm • </text>
+				<text fg={theme.colors.text}>N</text>
+				<text fg={theme.colors.muted}> to cancel</text>
+			</box>
+		</box>
+	);
+}
+
+export default ConfirmModal;

package/src/ui/components/modals/InputModal.tsx

@@ -0,0 +1,75 @@
+import type { SubmitEvent } from "@opentui/core";
+import React from "react";
+import { theme } from "../../theme.js";
+
+interface InputModalProps {
+	/** Modal title */
+	title: string;
+	/** Input label */
+	label: string;
+	/** Default input value */
+	defaultValue?: string;
+	/** Callback when submitted */
+	onSubmit: (value: string) => void;
+	/** Callback when cancelled */
+	onCancel: () => void;
+}
+
+export function InputModal({
+	title,
+	label,
+	defaultValue = "",
+	onSubmit,
+}: InputModalProps) {
+	return (
+		<box
+			flexDirection="column"
+			border
+			borderStyle="rounded"
+			borderColor={theme.colors.dim}
+			backgroundColor={theme.surface.bg}
+			paddingLeft={3}
+			paddingRight={3}
+			paddingTop={1}
+			paddingBottom={1}
+			width={60}
+		>
+			<box marginBottom={1}>
+				<text fg={theme.colors.text}>
+					<strong>{title}</strong>
+				</text>
+			</box>
+
+			<box marginBottom={1}>
+				<text fg={theme.colors.muted}>{label}</text>
+			</box>
+
+			<box
+				border
+				borderStyle="rounded"
+				borderColor={theme.colors.dim}
+				paddingLeft={1}
+				paddingRight={1}
+				width={54}
+			>
+				<input
+					value={defaultValue}
+					onSubmit={(value: string | SubmitEvent) => {
+						// @opentui/react types the prop as an intersection of the core
+						// `(event: SubmitEvent) => void` and its own `(value: string) => void`;
+						// at runtime the input hands over the string.
+						if (typeof value === "string") onSubmit(value);
+					}}
+					focused
+					width={50}
+				/>
+			</box>
+
+			<box marginTop={1}>
+				<text fg={theme.colors.muted}>↵ to confirm • Esc to cancel</text>
+			</box>
+		</box>
+	);
+}
+
+export default InputModal;

package/src/ui/components/modals/LoadingModal.tsx

@@ -0,0 +1,51 @@
+import React, { useState, useEffect } from "react";
+import { theme } from "../../theme.js";
+
+interface LoadingModalProps {
+	/** Loading message — supports multiline (first line = status, subsequent = detail) */
+	message: string;
+}
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export function LoadingModal({ message }: LoadingModalProps) {
+	const [frame, setFrame] = useState(0);
+
+	useEffect(() => {
+		const interval = setInterval(() => {
+			setFrame((prev) => (prev + 1) % SPINNER_FRAMES.length);
+		}, 80);
+
+		return () => clearInterval(interval);
+	}, []);
+
+	const lines = message.split("\n");
+	const mainMessage = lines[0];
+	const detail = lines.slice(1).join("\n");
+
+	return (
+		<box
+			flexDirection="column"
+			border
+			borderStyle="rounded"
+			borderColor={theme.colors.dim}
+			backgroundColor={theme.surface.bg}
+			paddingLeft={3}
+			paddingRight={3}
+			paddingTop={1}
+			paddingBottom={1}
+		>
+			<box flexDirection="row">
+				<text fg={theme.colors.muted}>{SPINNER_FRAMES[frame]}</text>
+				<text fg={theme.colors.text}> {mainMessage}</text>
+			</box>
+			{detail ? (
+				<box marginTop={0} paddingLeft={2}>
+					<text fg={theme.colors.dim}>{detail}</text>
+				</box>
+			) : null}
+		</box>
+	);
+}
+
+export default LoadingModal;

package/src/ui/components/modals/MessageModal.tsx

@@ -0,0 +1,66 @@
+import React from "react";
+import { useKeyboard } from "../../hooks/useKeyboard.js";
+import { theme } from "../../theme.js";
+
+interface MessageModalProps {
+	/** Modal title */
+	title: string;
+	/** Modal message */
+	message: string;
+	/** Message variant */
+	variant: "info" | "success" | "error";
+	/** Callback when dismissed */
+	onDismiss: () => void;
+}
+
+const variantConfig = {
+	info: { icon: "ℹ", color: theme.colors.link },
+	success: { icon: "✓", color: theme.colors.success },
+	error: { icon: "✗", color: theme.colors.danger },
+} as const;
+
+export function MessageModal({
+	title,
+	message,
+	variant,
+	onDismiss,
+}: MessageModalProps) {
+	const config = variantConfig[variant];
+
+	useKeyboard(() => {
+		// Any key dismisses
+		onDismiss();
+	});
+
+	return (
+		<box
+			flexDirection="column"
+			border
+			borderStyle="rounded"
+			borderColor={theme.colors.dim}
+			backgroundColor={theme.surface.bg}
+			paddingLeft={3}
+			paddingRight={3}
+			paddingTop={1}
+			paddingBottom={1}
+			width={60}
+		>
+			<box marginBottom={1}>
+				<text fg={config.color}>{config.icon} </text>
+				<text fg={theme.colors.text}>
+					<strong>{title}</strong>
+				</text>
+			</box>
+
+			<box marginBottom={1}>
+				<text fg={theme.colors.muted}>{message}</text>
+			</box>
+
+			<box marginTop={1}>
+				<text fg={theme.colors.muted}>Press any key to continue</text>
+			</box>
+		</box>
+	);
+}
+
+export default MessageModal;