@carlesandres/house 0.3.1 → 0.4.0

package/src/CommandPalette.tsx

@@ -0,0 +1,126 @@
+/**
+ * CommandPalette — modal overlay for searching and running commands.
+ *
+ * Render-only: state lives in Browser.tsx alongside helpVisible / filterOpen
+ * (#70 design log §state location). Key handling sits in Browser.tsx's
+ * `useKeyboard` palette-branch, mirroring the filterOpen pattern.
+ *
+ * V1 ships a flat list in `browserBindings` order — no category headers,
+ * no mouse, no recency. See #91/#93/#94/#95/#96 for the follow-ups.
+ */
+
+import { colors } from "./theme/colors.ts"
+import type { AppCommand } from "./commands/types.ts"
+
+export interface CommandPaletteProps {
+	readonly commands: readonly AppCommand[]
+	readonly query: string
+	readonly selectedIndex: number
+	readonly viewportWidth: number
+	readonly viewportHeight: number
+}
+
+const FOOTER_HINT = "↑↓ select  enter run  esc close"
+
+export const CommandPalette = ({
+	commands,
+	query,
+	selectedIndex,
+	viewportWidth,
+	viewportHeight,
+}: CommandPaletteProps) => {
+	const overlayWidth = Math.min(viewportWidth - 4, 64)
+	// Reserve: 2 for border (top+bottom), 1 query row, 1 spacer below query,
+	// 1 spacer above footer, 1 footer row. Body gets the rest.
+	const chrome = 2 + 1 + 1 + 1 + 1
+	const maxBody = Math.max(1, viewportHeight - 4 - chrome)
+	const desiredBody = Math.max(1, commands.length || 1)
+	const bodyHeight = Math.min(desiredBody, maxBody)
+	const overlayHeight = chrome + bodyHeight
+	const left = Math.max(0, Math.floor((viewportWidth - overlayWidth) / 2))
+	const top = Math.max(0, Math.floor((viewportHeight - overlayHeight) / 2))
+
+	// Inner content width: overlay minus 1-cell border + 1-cell padding on each side.
+	const rowWidth = Math.max(4, overlayWidth - 4)
+
+	// Window the visible slice around the selection. With 9 commands in v1
+	// this is usually a no-op (list fits), but the math is in place for the
+	// inevitable backlog growth.
+	const scrollTop = (() => {
+		if (commands.length <= bodyHeight) return 0
+		const maxScroll = commands.length - bodyHeight
+		let s = 0
+		if (selectedIndex >= bodyHeight) s = selectedIndex - bodyHeight + 1
+		return Math.max(0, Math.min(s, maxScroll))
+	})()
+	const visible = commands.slice(scrollTop, scrollTop + bodyHeight)
+
+	// Shortcut column width — long enough for `shift+t`-style chords but
+	// trimmed to prevent the title from being squeezed below ~16 cells.
+	const SHORTCUT_WIDTH = 10
+	const titleWidth = Math.max(8, rowWidth - 2 /* selector */ - SHORTCUT_WIDTH - 1 /* gap */)
+
+	const fit = (s: string, width: number): string =>
+		s.length === width
+			? s
+			: s.length > width
+				? s.slice(0, Math.max(0, width - 1)) + "…"
+				: s + " ".repeat(width - s.length)
+
+	const fitRight = (s: string, width: number): string =>
+		s.length >= width ? s.slice(0, width) : " ".repeat(width - s.length) + s
+
+	return (
+		<box
+			position="absolute"
+			left={left}
+			top={top}
+			width={overlayWidth}
+			height={overlayHeight}
+			zIndex={20}
+			title=" Commands "
+			titleAlignment="left"
+			paddingLeft={1}
+			paddingRight={1}
+			style={{
+				border: true,
+				borderColor: colors.borderActive,
+				flexDirection: "column",
+				backgroundColor: colors.surface,
+			}}
+		>
+			<text
+				wrapMode="none"
+				content={fit(`> ${query}▏`, rowWidth)}
+				style={{ fg: colors.textStrong }}
+			/>
+			<text content=" " />
+			{commands.length === 0 ? (
+				<text wrapMode="none" content="  (no matches)" style={{ fg: colors.textMuted }} />
+			) : (
+				visible.map((cmd, i) => {
+					const realIdx = scrollTop + i
+					const isSelected = realIdx === selectedIndex
+					const selector = isSelected ? "▸ " : "  "
+					const titleText = fit(cmd.title, titleWidth)
+					const shortcutText = cmd.shortcut
+						? fitRight(cmd.shortcut, SHORTCUT_WIDTH)
+						: " ".repeat(SHORTCUT_WIDTH)
+					// Title and shortcut render as separate spans so the shortcut
+					// can use `textMuted` while the title uses `text`/`textStrong`.
+					// Same trick opencode pulls with `--text-weak` — the theme
+					// guarantees the contrast, we just pick the right role.
+					const titleFg = isSelected ? colors.textStrong : colors.text
+					return (
+						<text key={cmd.id} wrapMode="none" style={isSelected ? { bg: colors.selectedBg } : {}}>
+							<span style={{ fg: titleFg }}>{`${selector}${titleText} `}</span>
+							<span style={{ fg: colors.textMuted }}>{shortcutText}</span>
+						</text>
+					)
+				})
+			)}
+			<text content=" " />
+			<text wrapMode="none" content={fit(FOOTER_HINT, rowWidth)} style={{ fg: colors.textMuted }} />
+		</box>
+	)
+}

package/src/Footer.tsx

@@ -11,6 +11,10 @@
  * were discovered. Intentional — `q:quit` and `?:help` are exactly what an
  * empty-vault user needs as an exit and discoverability anchor.
  *
+ * The filter input does not live here — it renders as a row inside the
+ * sidebar (see Browser.tsx). The pattern mirrors ghui's PR list, where the
+ * filter is part of the list it filters.
+ *
  * Width math assumes hint labels are ASCII plus a small set of single-cell
  * BMP glyphs (see `displayKey`). `fitHints` and notice clipping use string
  * length as a proxy for cell count; introducing a CJK or emoji label would
@@ -29,10 +33,15 @@ export interface FooterProps<C> {
 	readonly ctx: C
 	readonly width: number
 	readonly notice?: string | null
-	/** When set, the footer row turns into the filter input — `/<query>▏` —
-	 *  and suppresses both the hint row and the notice. Mirrors hunk's
-	 *  StatusBar: one row of chrome, content swaps by state. */
-	readonly filter?: { readonly query: string } | null
+	/** Persistent status line (e.g. "indexing… 42"). Distinct from `notice`:
+	 *  no TTL, cleared by the caller when the underlying activity finishes.
+	 *  Loses to `notice` when both are set so transient toasts still surface. */
+	readonly discoveryStatus?: string | null
+	/** When a filter is applied but the input is closed, surface a chip in the
+	 *  hint row so the user remembers `[`/`]` walks the filtered set. Pass null
+	 *  while the filter input is open (the sidebar already shows the query) or
+	 *  when no filter is applied. */
+	readonly filterQuery?: string | null
 }
 
 const HINT_SEPARATOR = "  "
@@ -88,13 +97,16 @@ const fitHints = (hints: readonly string[], width: number): string => {
 	return firstKey.slice(0, width)
 }
 
-/** Hints shown alongside the filter input. Mirrors the modal-mode key
- *  handler in `Browser.tsx`; if those bindings change, update both. */
-const FILTER_HINTS = "↵:open  esc:cancel"
-/** Minimum gap between the filter input and its hints on the same row. */
-const FILTER_HINT_GAP = 2
+const STATUS_SEPARATOR = " · "
 
-export const Footer = <C,>({ bindings, ctx, width, notice, filter }: FooterProps<C>) => {
+export const Footer = <C,>({
+	bindings,
+	ctx,
+	width,
+	notice,
+	discoveryStatus,
+	filterQuery,
+}: FooterProps<C>) => {
 	const usableWidth = Math.max(0, width - 2) // 1-cell horizontal padding each side
 
 	const rowStyle = {
@@ -107,45 +119,60 @@ export const Footer = <C,>({ bindings, ctx, width, notice, filter }: FooterProps
 		backgroundColor: colors.background,
 	} as const
 
-	// Filter mode is two-column: input left, hints right, separated by a
-	// flex-grow spacer. Hints drop entirely on narrow viewports rather than
-	// pushing the input off-screen — the input is the primary surface.
-	if (filter) {
-		const input = `/${filter.query}▏`
-		const showHints = input.length + FILTER_HINT_GAP + FILTER_HINTS.length <= usableWidth
-		return (
-			<box style={rowStyle}>
-				<text content={input} wrapMode="none" style={{ fg: colors.textStrong }} />
-				{showHints && (
-					<>
-						<box style={{ flexGrow: 1 }} />
-						<text content={FILTER_HINTS} wrapMode="none" style={{ fg: colors.textMuted }} />
-					</>
-				)}
-			</box>
-		)
-	}
-
 	const hints: string[] = []
+	// The filter chip prepends to the hint row when a filter is applied and the
+	// input is closed. Bracketed to avoid looking like a `key:hint` binding —
+	// "filter" is not a key. Surfaces the otherwise-invisible invariant that
+	// `[`/`]` walks the filtered set. See DESIGN.md §7.1 Q1.
+	if (filterQuery && filterQuery.length > 0) {
+		hints.push(`[filter: ${filterQuery}]`)
+	}
 	for (const b of bindings) {
 		if (b.when && !b.when(ctx)) continue
 		const h = formatHint(b)
 		if (h !== null) hints.push(h)
 	}
-	const hintContent = fitHints(hints, usableWidth)
+
+	// Discovery status sits left of the hints, separated by " · ". On tight
+	// viewports it claims its budget first; hints fit into the remainder so
+	// the indicator stays visible while less-essential hints drop off.
+	const status = discoveryStatus && discoveryStatus.length > 0 ? discoveryStatus : null
+	const statusBudget = status ? Math.min(status.length + STATUS_SEPARATOR.length, usableWidth) : 0
+	const hintsWidth = Math.max(0, usableWidth - statusBudget)
+	const hintContent = fitHints(hints, hintsWidth)
+	const statusContent = status
+		? status.slice(0, Math.max(0, statusBudget - STATUS_SEPARATOR.length))
+		: ""
+
 	const noticeContent = notice
 		? notice.length > usableWidth
 			? notice.slice(0, usableWidth)
 			: notice
 		: null
 
-	// Notice > hints. Notice fg is strong; hints are muted.
-	const content = noticeContent ?? hintContent
-	const fg = noticeContent ? colors.textStrong : colors.textMuted
+	// Priority: notice > (status + hints). Notice fg is strong; status sits
+	// at the muted level so it reads as ambient state, not an event.
+	if (noticeContent !== null) {
+		return (
+			<box style={rowStyle}>
+				<text content={noticeContent} wrapMode="none" style={{ fg: colors.textStrong }} />
+			</box>
+		)
+	}
+
+	if (status !== null) {
+		return (
+			<box style={rowStyle}>
+				<text content={statusContent} wrapMode="none" style={{ fg: colors.textMuted }} />
+				<text content={STATUS_SEPARATOR} wrapMode="none" style={{ fg: colors.textMuted }} />
+				<text content={hintContent} wrapMode="none" style={{ fg: colors.textMuted }} />
+			</box>
+		)
+	}
 
 	return (
 		<box style={rowStyle}>
-			<text content={content} wrapMode="none" style={{ fg }} />
+			<text content={hintContent} wrapMode="none" style={{ fg: colors.textMuted }} />
 		</box>
 	)
 }

package/src/cli/argv.ts

@@ -21,6 +21,10 @@ export interface ParsedArgs {
 	readonly help: boolean
 	/** True when `--version` was passed. */
 	readonly version: boolean
+	/** True when `--config-path` was passed: print resolved config path and exit. */
+	readonly configPath: boolean
+	/** Value of `--sidebar <mode>` (`auto`, `on`, `off`), or null. Validated by the boot layer. */
+	readonly sidebar: string | null
 }
 
 /**
@@ -41,6 +45,8 @@ export const parseArgv = (argv: readonly string[]): ParsedArgs => {
 	let port: string | null = null
 	let help = false
 	let version = false
+	let configPath = false
+	let sidebar: string | null = null
 
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i]!
@@ -79,13 +85,27 @@ export const parseArgv = (argv: readonly string[]): ParsedArgs => {
 			case "-v":
 				version = true
 				continue
+			case "--config-path":
+				configPath = true
+				continue
+			case "--sidebar": {
+				// Don't swallow the following flag as the sidebar value.
+				// `--sidebar --width 80` should leave sidebar=null (the boot
+				// layer reports a missing value) without losing --width.
+				const next = argv[i + 1]
+				if (next !== undefined && !next.startsWith("-")) {
+					sidebar = next
+					i++
+				}
+				continue
+			}
 		}
 		if (path === null && !arg.startsWith("-")) {
 			path = arg
 		}
 	}
 
-	return { path, theme, tone, width, all, sort, serve, port, help, version }
+	return { path, theme, tone, width, all, sort, serve, port, help, version, configPath, sidebar }
 }
 
 const themeList = themeDefinitions.map((t) => t.id).join(", ")
@@ -100,7 +120,15 @@ options:
   --width <N>    cap rendered markdown width at N columns
   --all          include hidden and gitignored files in discovery
   --sort <mode>  sidebar order: dirs-first (default) or files-first
+  --sidebar <m>  initial sidebar visibility: auto (default), on, or off
   --serve        serve the given file as HTML in the browser (skips TUI)
   --port <N>     port for --serve (default: OS-assigned)
   -h, --help     show this help and exit
-  -v, --version  print version and exit`
+  -v, --version  print version and exit
+  --config-path  print path to the config file and exit
+
+configuration:
+  file: $XDG_CONFIG_HOME/house/config.toml  (default ~/.config/house/config.toml)
+  keys: theme, tone
+  env:  HOUSE_THEME, HOUSE_TONE
+  precedence (high → low): flags → env → file → defaults`

package/src/commands/buildCommands.ts

@@ -0,0 +1,102 @@
+/**
+ * Derive palette commands from `browserBindings` plus the annotation map.
+ *
+ * The annotation map is the *only* hand-written list keyed by binding id:
+ * it carries (a) hide flags for bindings that are pure keystroke nav, and
+ * (b) title rewrites for bindings whose `description` reads as a help-row
+ * entry rather than a palette command. Every other binding is exposed
+ * verbatim — its `description` becomes the palette `title`, its first key
+ * becomes the `shortcut`.
+ *
+ * Commands close over the per-render `BrowserCtx`, same shape the keymap
+ * dispatcher uses, so the palette and the keymap fire the same action via
+ * different surfaces. See #70 design log §list construction (option 3b)
+ * for why this beat (a) a fully hand-written palette list and (b) deriving
+ * everything via #92's atom-driven registry.
+ */
+
+import { browserBindings, type BrowserCtx } from "../keymap/browser.ts"
+import { paletteOnlyCommands } from "./paletteOnlyCommands.ts"
+import type { AppCommand } from "./types.ts"
+
+interface Annotation {
+	/** Override the binding's `description` for palette display. */
+	readonly title?: string
+	/** Carried for #91's category headers; unused in v1's flat list. */
+	readonly category?: string
+	/** If true, the binding does not appear in the palette. */
+	readonly hidden?: boolean
+	readonly keywords?: readonly string[]
+}
+
+/**
+ * Pure-keystroke nav (j/k/space/b/[/]…) is intentionally hidden — those
+ * bindings have no command-shaped meaning. Reader prev/next file (`[`/`]`)
+ * and sidebar `open` (Return/l) are the borderline cases from #70 Q6a;
+ * hidden in v1, reconsider if users ask. Title rewrites convert
+ * help-overlay phrasing ("Toggle sidebar visibility") into imperative
+ * palette phrasing ("Toggle sidebar"). See #70 design log §6.
+ */
+const annotations: Record<string, Annotation> = {
+	// --- Keep, with title rewrites where the binding description reads awkwardly as a command ---
+	quit: { category: "App" },
+	"focus.toggle": { title: "Toggle focus", category: "View" },
+	"sidebar.toggle": { title: "Toggle sidebar", category: "View" },
+	"help.toggle": { title: "Show help", category: "App" },
+	"filter.open": { title: "Filter files…", category: "Navigation" },
+	"serve.current": { title: "Open in browser", category: "File" },
+	"theme.next": { category: "Appearance" },
+	"theme.prev": { category: "Appearance" },
+	"theme.toneToggle": { title: "Toggle dark/light tone", category: "Appearance" },
+
+	// --- Hide: pure keystroke navigation (j/k/space/b/g/G…) ---
+	"sidebar.down": { hidden: true },
+	"sidebar.up": { hidden: true },
+	"sidebar.jumpDown": { hidden: true },
+	"sidebar.jumpUp": { hidden: true },
+	"sidebar.pageDown": { hidden: true },
+	"sidebar.pageUp": { hidden: true },
+	"sidebar.top": { hidden: true },
+	"sidebar.bottom": { hidden: true },
+
+	// --- Hide: borderline reader nav. `[`/`]` and Return-to-open feel command-shaped
+	//     but are pure keystroke navigation under the hood. #70 Q6a — reconsider
+	//     if user feedback expects them in the palette.
+	"sidebar.open": { hidden: true },
+	"reader.back": { hidden: true },
+	"reader.prevFile": { hidden: true },
+	"reader.nextFile": { hidden: true },
+
+	// --- Hide: the palette opener itself shouldn't appear in the palette ---
+	"palette.open": { hidden: true },
+}
+
+/**
+ * Build the AppCommand list for a given render. Iterates `browserBindings`
+ * in array order (the empty-query palette renders in this order, by design
+ * — see #70 design log §empty-state ordering), drops hidden entries and
+ * those whose `when` predicate currently returns false, and resolves
+ * annotations to populate title / category / keywords.
+ */
+export const buildCommands = (ctx: BrowserCtx): readonly AppCommand[] => {
+	const out: AppCommand[] = []
+	for (const binding of browserBindings) {
+		const ann = annotations[binding.id]
+		if (ann?.hidden) continue
+		// Same gating the keymap dispatcher uses. Disabled bindings get
+		// hidden from the palette (per #70 Q5b — see #96 for the show-with-
+		// reason follow-up after the atom-driven migration).
+		if (binding.when && !binding.when(ctx)) continue
+		const cmd: AppCommand = {
+			id: binding.id,
+			title: ann?.title ?? binding.description,
+			...(ann?.category !== undefined && { category: ann.category }),
+			...(ann?.keywords !== undefined && { keywords: ann.keywords }),
+			...(binding.keys[0] !== undefined && { shortcut: binding.keys[0] }),
+			run: () => binding.run(ctx),
+		}
+		out.push(cmd)
+	}
+	for (const cmd of paletteOnlyCommands(ctx)) out.push(cmd)
+	return out
+}

package/src/commands/paletteOnlyCommands.ts

@@ -0,0 +1,16 @@
+/**
+ * Commands that exist *only* in the palette — no `browserBindings` entry.
+ *
+ * Empty in v1 by design (#70 Q6c). This file exists as scaffolding so
+ * future palette-only commands (#93 reveal-in-OS, #94 copy-path, …) have
+ * an obvious home that's already wired into `buildCommands.ts`.
+ *
+ * Commands here follow the same shape as keymap-derived ones: they take
+ * the per-render `BrowserCtx` so they can read selection state, mutate
+ * focus, surface notices, etc.
+ */
+
+import type { BrowserCtx } from "../keymap/browser.ts"
+import type { AppCommand } from "./types.ts"
+
+export const paletteOnlyCommands = (_ctx: BrowserCtx): readonly AppCommand[] => []

package/src/commands/score.ts

@@ -0,0 +1,78 @@
+/**
+ * Command palette scorer — ported from ghui's pre-May `commands.ts`.
+ *
+ * Tiered ranking: title-prefix → text-prefix → title-includes →
+ * text-includes → acronym → fuzzy-includes. Lower score wins. Ties broken
+ * by `browserBindings` array order (the `index` field) so the empty-query
+ * palette renders in the keymap's natural order. See #70 design log for
+ * why we didn't reach for `fuzzysort`.
+ */
+
+import type { AppCommand } from "./types.ts"
+
+const normalize = (text: string): string =>
+	text
+		.toLowerCase()
+		.replace(/[^a-z0-9#]+/g, " ")
+		.trim()
+
+const acronym = (text: string): string =>
+	normalize(text)
+		.split(" ")
+		.filter(Boolean)
+		.map((word) => word[0])
+		.join("")
+
+const fuzzyIncludes = (text: string, query: string): boolean => {
+	let index = 0
+	for (const char of text) {
+		if (char === query[index]) index++
+		if (index >= query.length) return true
+	}
+	return query.length === 0
+}
+
+const searchText = (command: AppCommand): string =>
+	normalize(
+		[command.title, command.category, command.shortcut, ...(command.keywords ?? [])]
+			.filter((s): s is string => Boolean(s))
+			.join(" "),
+	)
+
+/** Returns the tier (lower = better) or `null` if the query doesn't match. */
+const score = (command: AppCommand, query: string): number | null => {
+	const q = normalize(query)
+	if (q.length === 0) return 0
+	const title = normalize(command.title)
+	const text = searchText(command)
+	if (title.startsWith(q)) return 0
+	if (text.startsWith(q)) return 1
+	if (title.includes(q)) return 2
+	if (text.includes(q)) return 3
+	if (acronym(command.title).startsWith(q)) return 4
+	if (fuzzyIncludes(text, q.replaceAll(" ", ""))) return 5
+	return null
+}
+
+/**
+ * Filter and sort commands against a query. With an empty query, every
+ * command tiers to 0 and the original index breaks ties — so the result is
+ * the input list in its original order (which v1 uses as `browserBindings`
+ * order). See #70 design log §empty-state ordering.
+ */
+export const filterCommands = (
+	commands: readonly AppCommand[],
+	query: string,
+): readonly AppCommand[] =>
+	commands
+		.flatMap((command, index) => {
+			const tier = score(command, query)
+			return tier === null ? [] : [{ command, index, tier }]
+		})
+		.sort((a, b) => a.tier - b.tier || a.index - b.index)
+		.map(({ command }) => command)
+
+export const clampSelectedIndex = (index: number, commands: readonly AppCommand[]): number => {
+	if (commands.length === 0) return 0
+	return Math.max(0, Math.min(commands.length - 1, index))
+}

package/src/commands/types.ts

@@ -0,0 +1,26 @@
+/**
+ * Palette command shape.
+ *
+ * Commands are derived at render time from `browserBindings` via the
+ * annotation map (`buildCommands.ts`). The `run` field closes over the
+ * per-render `BrowserCtx` so dispatching a command is equivalent to firing
+ * the corresponding key binding — single source of truth for the action,
+ * two surfaces (keymap + palette) that can invoke it.
+ *
+ * See issue #70 (and its design-log comments) for the rejected alternatives
+ * — atom-driven registry (#92), fully hand-written list, fuzzysort dep, etc.
+ */
+
+export interface AppCommand {
+	/** Stable id; matches the binding's id for keymap-derived commands. */
+	readonly id: string
+	/** Imperative-phrased label shown in the palette row. */
+	readonly title: string
+	/** Optional category for #91's grouped headers. Carried but unused in v1. */
+	readonly category?: string
+	/** Extra match terms (synonyms, alt phrasings). */
+	readonly keywords?: readonly string[]
+	/** Display-only shortcut hint (first key of the binding, if any). */
+	readonly shortcut?: string
+	readonly run: () => void
+}