@ssebastien/tcmd 0.1.4 → 0.1.7

package/src/js/tcmd/components/Help.js

@@ -4,90 +4,185 @@
 // Created: 2026-10-02
 
 // Module: tcmd/components/Help
-// Shared behavior for the `?` key reference overlay, plus the reference text
-// itself (`helpLines`). The content is built from the live keymap and command
-// registry, so it cannot drift from the actual bindings. Both presentations
-// (`Help.xml` / `Help.html`) render the same lines.
+// Shared behavior for the `?` key reference overlay, plus the reference data
+// itself. The categories are built from the live keymap and command registry,
+// so they cannot drift from the actual bindings. The TUI keeps the bracket
+// shorthand (`[Open ⏎]`); the web renders toolbar-like action chips with Lucide
+// icons and key badges. Rows are balanced across two columns with bright
+// uppercase section headings. Both presentations (`Help.xml` / `Help.html`)
+// render the same row data through `HelpRow`.
 
 import { unwrap } from "select/state/cells"
-import { DEFAULT_KEYMAP } from "../core/keymap.js"
+import { DEFAULT_KEYMAP, keyGlyph } from "../core/keymap.js"
 import { getCommands } from "../core/commands.js"
+import { commandLabel, keyGlyph as keyLabelGlyph } from "./CommandItem.js"
 
-// Function: keyGlyph
-// Human-readable glyph for a keymap chord ("↑", "⇧Tab", "^W", "PgUp").
-function keyGlyph(chord) {
-	const name = chord.key
-	const named = {
-		up: "↑",
-		down: "↓",
-		left: "←",
-		right: "→",
-		return: "↵",
-		enter: "↵",
-		space: "Space",
-		tab: "Tab",
-		pageup: "PgUp",
-		pagedown: "PgDn",
-		escape: "Esc",
-		backspace: "Bksp",
-		home: "Home",
-		end: "End",
-	}
-	let base = named[name] ?? (name.length === 1 ? name.toUpperCase() : `${name}`)
-	if (chord.ctrl) base = `^${base}`
-	if (chord.meta) base = `⌘${base}`
-	if (chord.shift && name !== "tab") base = `⇧${base}`
-	return base
-}
+// Constant: BRACKET
+// The shorthand delimiters, shared with the command bar.
+const OPEN = "["
+const CLOSE = "]"
+
+// Constant: CLOSE_HINT
+// The footer shorthand: Esc dismisses the overlay.
+const CLOSE_HINT = { title: "Close", keys: "Esc" }
+
+// Constant: BOLD
+// OpenTUI's `TextAttributes.BOLD` bit, set on section headings through the
+// TUI's `out:attributes` slot. The web bolds through CSS instead.
+const BOLD = 1
 
 // Constant: GROUP_ORDER / GROUP_TITLES
 // Help sections, in display order.
-const GROUP_ORDER = ["nav", "pane", "list", "bookmark", "view", "file", "panel", "filter", "app"]
+const GROUP_ORDER = ["nav", "pane", "list", "bookmark", "view", "file", "history", "trash", "panel", "filter", "app"]
 const GROUP_TITLES = {
 	app: "Session",
 	bookmark: "Bookmarks",
 	file: "Files",
 	filter: "Filter",
+	history: "History",
 	list: "Selection",
 	nav: "Navigation",
 	panel: "Commands",
 	pane: "Panes",
+	trash: "Trash",
 	view: "View",
 }
 
-// Function: helpLines
-// The categorized key reference, one line per heading or binding.
-function helpLines() {
+// Toolbar actions and key-reference entries share Lucide icons in the web UI.
+// The TUI keeps its compact textual row layout.
+const HELP_ICONS = {
+	"nav.up": "arrow-up",
+	"nav.down": "arrow-down",
+	"nav.jumpUp": "arrow-up",
+	"nav.jumpDown": "arrow-down",
+	"nav.pageUp": "arrow-up",
+	"nav.pageDown": "arrow-down",
+	"nav.home": "arrow-up",
+	"nav.end": "arrow-down",
+	"pane.enter": "arrow-right",
+	"pane.up": "arrow-up",
+	"pane.back": "arrow-left",
+	"pane.forward": "arrow-right",
+	"pane.toggle": "columns-2",
+	"pane.reload": "refresh-cw",
+	"list.mark": "check",
+	"bookmark.open": "bookmark",
+	"view.togglePreview": "panel-right",
+	"view.maximize": "maximize",
+	"view.toggleMode": "columns-2",
+	"file.mkdir": "folder-plus",
+	"file.open": "file",
+	"file.edit": "file-text",
+	"history.open": "refresh-cw",
+	"history.undo": "arrow-left",
+	"history.redo": "arrow-right",
+	"trash.open": "trash",
+	"panel.open": "terminal",
+	"panel.shell": "terminal",
+	"filter.start": "search",
+	"app.quit": "power",
+	"app.help": "circle-question-mark",
+}
+
+// Function: helpGroups
+// The categorized key reference as `{ title, rows }` groups in display order.
+// One row per command, with every distinct chord from the live keymap. The
+// registry provides the action title.
+function helpGroups() {
 	const byId = new Map(getCommands().map((command) => [command.id, command]))
 	const groups = new Map()
-	const seen = new Set()
 	for (const binding of DEFAULT_KEYMAP) {
 		const command = byId.get(binding.command)
 		if (!command) continue
 		const group = binding.command.split(".")[0]
 		if (!groups.has(group)) groups.set(group, new Map())
 		const rows = groups.get(group)
-		if (!rows.has(binding.command)) rows.set(binding.command, { keys: [], title: command.title })
+		if (!rows.has(binding.command)) rows.set(binding.command, { keys: [], id: binding.command, title: command.title })
 		const row = rows.get(binding.command)
 		const glyph = keyGlyph(binding)
-		if (!row.keys.includes(glyph) && !seen.has(`${binding.command}:${glyph}`)) {
-			row.keys.push(glyph)
-			seen.add(`${binding.command}:${glyph}`)
-		}
+		if (!row.keys.includes(glyph)) row.keys.push(glyph)
 	}
-	const lines = []
+	const out = []
 	for (const group of GROUP_ORDER) {
 		const rows = groups.get(group)
 		if (!rows) continue
-		lines.push(GROUP_TITLES[group] ?? group)
+		const list = []
 		for (const row of rows.values()) {
-			lines.push(`  ${row.keys.join("/").padEnd(9)} ${row.title}`)
+			list.push({ id: row.id, title: row.title, keys: row.keys.map(keyLabelGlyph).join("/") })
 		}
+		out.push({ title: GROUP_TITLES[group] ?? group, rows: list })
+	}
+	return out
+}
+
+// Function: helpLines
+// The flat reference: group headings and rows, one per line, blank line
+// between groups (the single-column fallback).
+function helpLines() {
+	const lines = []
+	for (const group of helpGroups()) {
+		lines.push(group.title)
+		for (const row of group.rows) lines.push(commandLabel(row).trim())
 		lines.push("")
 	}
 	return lines
 }
 
+// Function: helpBlocks
+// The reference split into two columns balanced by line count, as flat lists of
+// renderable blocks: `{ type: "section", label }` headings,
+// `{ type: "entry", open, head, keys, close }` rows and `{ type: "spacer" }`
+// blank lines between groups. Every entry title and key is padded to the widest
+// one across both columns, so all brackets share one width and the keys align
+// down each column (keys right-aligned against the closing bracket).
+function helpBlocks() {
+	const groups = helpGroups()
+	const commands = new Map(getCommands().map((command) => [command.id, command]))
+	let titleWidth = 0
+	let keyWidth = 0
+	for (const group of groups) {
+		for (const row of group.rows) {
+			titleWidth = Math.max(titleWidth, row.title.length)
+			keyWidth = Math.max(keyWidth, keyLabelGlyph(row.keys).length)
+		}
+	}
+	const columns = [[], []]
+	const loads = [0, 0]
+	for (const group of groups) {
+		const at = loads[0] <= loads[1] ? 0 : 1
+		columns[at].push({ type: "section", key: `section:${group.title}`, label: group.title.toUpperCase() })
+		for (const row of group.rows) {
+			const command = commands.get(row.id)
+			// The compact web badge shows the command's canonical key when the
+			// registry has one (lowercase `b`, `Spc`, `⇥`); otherwise fall back
+			// to the keymap chords, which may list several alternatives.
+			const shortcut = command?.keys ? keyLabelGlyph(command.keys) : keyLabelGlyph(row.keys)
+			columns[at].push({
+				type: "entry",
+				key: `entry:${row.id}`,
+				icon: HELP_ICONS[row.id] ?? "chevron-right",
+				title: row.title,
+				shortcut,
+				open: OPEN,
+				head: `${row.title.padEnd(titleWidth)} `,
+				keys: keyLabelGlyph(row.keys).padStart(keyWidth),
+				close: CLOSE,
+			})
+		}
+		// A blank row separates the groups (and costs one line, like the
+		// heading).
+		columns[at].push({ type: "spacer", key: `spacer:${group.title}` })
+		// A group costs its rows plus its heading and the blank after it.
+		loads[at] += group.rows.length + 2
+	}
+	// The blank line separates groups, so the bottom of each column ends on its
+	// last entry instead.
+	for (const column of columns) {
+		if (column[column.length - 1]?.type === "spacer") column.pop()
+	}
+	return { left: columns[0], right: columns[1] }
+}
+
 // Function: createBehaviors
 // Builds the Help behavior map for the given renderer environment.
 function createBehaviors(env) {
@@ -95,15 +190,71 @@ function createBehaviors(env) {
 		bg: () => env.theme.surfaceBg,
 		borderFg: () => env.theme.borderPrimaryActiveFg,
 		dimFg: () => env.theme.textSecondaryFg,
-		hint: () => " Esc / ? close ",
+		leftRows: (self, data) => env.rows?.(self, data, "left") ?? [],
+		rightRows: (self, data) => env.rows?.(self, data, "right") ?? [],
+		// The reference has no cursor for the scrollbox to follow, so its
+		// vertical bar is driven here: visible only while the two columns
+		// actually overflow the viewport. The viewport height is derived from
+		// the injected `size` (so the bar tracks a resize) and the dialog's own
+		// geometry (`Help.xml`: 82% tall, minus padding, borders, rule and
+		// footer).
+		scrollbar: (self, data) => {
+			const scroll = self?.ref?.scroll
+			const bar = scroll?.verticalScrollBar
+			if (!bar) return ""
+			const height = unwrap(data?.size)?.height ?? self?.ctx?.height ?? 0
+			const viewport = height > 0 ? Math.floor(height * 0.82) - 6 : 0
+			const columns = helpBlocks()
+			const rows = Math.max(columns.left.length, columns.right.length)
+			const want = viewport > 0 && rows > viewport
+			if (bar.visible !== want) bar.visible = want
+			return ""
+		},
 		open: (_self, data) => Boolean(unwrap(data.open)),
-		text: () => helpLines().join("\n"),
+		// The footer shorthand reads like the bar: dim brackets, bright title,
+		// accent key.
+		hintOpen: () => OPEN,
+		hintHead: () => `${CLOSE_HINT.title} `,
+		hintKeys: () => CLOSE_HINT.keys,
+		hintClose: () => CLOSE,
+		bracketFg: () => env.theme.textSecondaryFg,
+		headFg: () => env.theme.textFg,
+		keyFg: () => env.theme.accentFg,
+		// Separator rule above the footer (a top border on a one-row box).
+		rule: () => ["top"],
+		ruleFg: () => env.theme.textSecondaryFg,
 		textFg: () => env.theme.textFg,
 		title: () => " Keys ",
 		titleFg: () => env.theme.textHeadingFg,
 	}
 }
 
-export { createBehaviors, helpLines, keyGlyph }
+// Function: createRowBehaviors
+// Builds the HelpRow behavior map (one section heading or one key entry).
+function createRowBehaviors(env) {
+	return {
+		isSection: (_self, data) => data.item?.type === "section",
+		isEntry: (_self, data) => data.item?.type === "entry",
+		section: (_self, data) => data.item?.label ?? "",
+		// Sections are bright; the TUI adds bold via OpenTUI's attribute bit
+		// (the web bolds through CSS instead).
+		sectionFg: () => env.theme.textHeadingFg,
+		sectionAttrs: () => BOLD,
+		open: (_self, data) => data.item?.open ?? "",
+		head: (_self, data) => data.item?.head ?? "",
+		keys: (_self, data) => data.item?.keys ?? "",
+		close: (_self, data) => data.item?.close ?? "",
+		hasIcon: (_self, data) => Boolean(env.theme.lucideIcons && data.item?.icon),
+		iconHref: (_self, data) =>
+			env.theme.lucideIcons && data.item?.icon ? `#lucide-${data.item.icon}` : "",
+		actionTitle: (_self, data) => data.item?.title ?? `${data.item?.head ?? ""}`.trim(),
+		shortcut: (_self, data) => data.item?.shortcut ?? `${data.item?.keys ?? ""}`.trim(),
+		bracketFg: () => env.theme.textSecondaryFg,
+		headFg: () => env.theme.textFg,
+		keyFg: () => env.theme.accentFg,
+	}
+}
+
+export { createBehaviors, createRowBehaviors, helpBlocks, helpGroups, helpLines, keyGlyph }
 
 // EOF

package/src/js/tcmd/components/Help.xml

@@ -3,9 +3,18 @@
 	     out:title="title" out:titleColor="titleFg" out:borderColor="borderFg"
 	     out:backgroundColor="bg" flexDirection="column"
 	     paddingLeft="2" paddingRight="2" paddingTop="1" paddingBottom="1">
-		<scrollbox flexGrow="1">
-			<text out="text" out:fg="textFg"></text>
-		</scrollbox>
-		<text out="hint" out:fg="dimFg"></text>
+		<helpscroll out="scrollbar" ref="scroll" flexGrow="1" overflow="hidden">
+			<box flexDirection="row" overflow="hidden">
+				<box out="leftRows" flexDirection="column" flexGrow="1" flexBasis="0" overflow="hidden"></box>
+				<box out="rightRows" flexDirection="column" flexGrow="1" flexBasis="0" overflow="hidden" paddingLeft="2"></box>
+			</box>
+		</helpscroll>
+		<box height="1" flexShrink="0" out:border="rule" out:borderColor="ruleFg"></box>
+		<box height="1" flexShrink="0" flexDirection="row" overflow="hidden">
+			<text out="hintOpen" out:fg="bracketFg" wrapMode="none"></text>
+			<text out="hintHead" out:fg="headFg" wrapMode="none"></text>
+			<text out="hintKeys" out:fg="keyFg" wrapMode="none"></text>
+			<text out="hintClose" out:fg="bracketFg" wrapMode="none"></text>
+		</box>
 	</box>
 </box>

package/src/js/tcmd/components/HelpRow.html

@@ -0,0 +1,8 @@
+<div class="help-block">
+	<span class="help-section" when="isSection" out="section"></span>
+	<span class="help-entry" when="isEntry" role="group">
+		<svg class="help-icon ui-icon" when="hasIcon" aria-hidden="true" focusable="false" viewBox="0 0 24 24"><use out:href="iconHref"></use></svg>
+		<span class="help-title" out="actionTitle"></span>
+		<kbd class="help-key" out="shortcut"></kbd>
+	</span>
+</div>

package/src/js/tcmd/components/HelpRow.xml

@@ -0,0 +1,7 @@
+<box height="1" flexDirection="row" flexShrink="0" overflow="hidden">
+	<text when="isSection" out="section" out:fg="sectionFg" out:attributes="sectionAttrs" wrapMode="none"></text>
+	<text when="isEntry" out="open" out:fg="bracketFg" wrapMode="none"></text>
+	<text when="isEntry" out="head" out:fg="headFg" wrapMode="none"></text>
+	<text when="isEntry" out="keys" out:fg="keyFg" wrapMode="none"></text>
+	<text when="isEntry" out="close" out:fg="bracketFg" wrapMode="none"></text>
+</box>

package/src/js/tcmd/components/OverlayList.html

@@ -0,0 +1,8 @@
+<div class="overlay-list" when="open" role="dialog" aria-modal="true" aria-label="History and trash" on:click="!dialog:overlay-cancel">
+	<div class="overlay-dialog" on:click="dialogStop">
+		<h2 out="title"></h2>
+		<p class="overlay-empty" when="emptyVisible" out="empty"></p>
+		<ul class="overlay-rows" out="rows"></ul>
+		<footer out="footer"></footer>
+	</div>
+</div>

package/src/js/tcmd/components/OverlayList.js

@@ -0,0 +1,69 @@
+// Project: TinyCommand
+// Author:  Sebastien Pierre
+// License: BSD
+// Created: 2026-10-17
+
+// Module: tcmd/components/OverlayList
+// The shared modal list overlay: the undo history (`u`) and the trash browser
+// (`⇧T`). One component, two modes — `history` lists the journal (a row jumps
+// the file state to that point), `trash` lists trashed entries (a row restores
+// one). The row logic lives in `OverlayRow.js`; this parent maps its `items` to
+// rows and switches title/footer/empty text on the mode.
+//
+// Environment: `overlayBg`, `borderPrimaryActiveFg`, `textHeadingFg` (title),
+// `textSecondaryFg` (footer/empty), `rows(data)` returning the keyed rows and
+// `scrollTop(self, data)` (TUI viewport tracking).
+
+import { unwrap } from "select/state/cells"
+
+// Function: overlayMode
+// "trash" or "history" for the data's mode (an absent mode reads as history).
+function overlayMode(mode) {
+	return unwrap(mode) === "trash" ? "trash" : "history"
+}
+
+// Function: overlayTitle
+function overlayTitle(mode) {
+	return overlayMode(mode)
+}
+
+// Function: overlayFooter
+function overlayFooter(mode) {
+	return overlayMode(mode) === "trash"
+		? "↑↓ move   ↵ restore   Esc close"
+		: "↑↓ move   ↵ jump   ^Z undo   ^⇧Z redo   Esc close"
+}
+
+// Function: overlayEmpty
+// The empty-state line: no history yet, or an empty trash.
+function overlayEmpty(mode) {
+	return overlayMode(mode) === "trash" ? "  trash is empty" : "  no history yet"
+}
+
+// Function: createBehaviors
+// Builds the OverlayList behavior map for the given renderer environment.
+function createBehaviors(env) {
+	const behaviors = {
+		bg: () => env.overlayBg,
+		borderFg: () => env.borderPrimaryActiveFg,
+		titleColor: () => env.textHeadingFg,
+		title: (_self, data) => overlayTitle(data.mode),
+		footer: (_self, data) => overlayFooter(data.mode),
+		footerFg: () => env.textSecondaryFg,
+		empty: (_self, data) => overlayEmpty(data.mode),
+		emptyFg: () => env.textSecondaryFg,
+		emptyVisible: (_self, data) => (unwrap(data.items)?.length ?? 0) === 0,
+		open: (_self, data) => Boolean(unwrap(data.open)),
+	}
+	if (env?.rows) {
+		behaviors.rows = (self, data) => env.rows(self, data)
+	}
+	if (env?.scrollTop) {
+		behaviors.scrollTop = (self, data) => env.scrollTop(self, data)
+	}
+	return behaviors
+}
+
+export { createBehaviors, overlayEmpty, overlayFooter, overlayMode, overlayTitle }
+
+// EOF

package/src/js/tcmd/components/OverlayList.xml

@@ -0,0 +1,13 @@
+<box when="open" width="100%" height="100%" alignItems="center" justifyContent="center">
+	<box width="72%" height="60%" border borderStyle="rounded"
+	     out:title="title" out:titleColor="titleColor" out:borderColor="borderFg"
+	     out:backgroundColor="bg" flexDirection="column">
+		<text when="emptyVisible" out="empty" out:fg="emptyFg" paddingLeft="1" wrapMode="none"></text>
+		<scrollbox when="!emptyVisible" ref="list" flexGrow="1">
+			<box out="rows" flexDirection="column"></box>
+		</scrollbox>
+		<box flexDirection="row" height="1" paddingLeft="1">
+			<text out="footer" out:fg="footerFg"></text>
+		</box>
+	</box>
+</box>

package/src/js/tcmd/components/OverlayRow.html

@@ -0,0 +1,5 @@
+<li class="overlay-row" out:class="rowClass" out:data-current="rowCurrent" out:data-dim="rowDim" on:click="item.key!overlay:select">
+	<span class="overlay-marker" out="rowMarker"></span>
+	<span class="overlay-text" out="rowText"></span>
+	<span class="overlay-meta" out="rowMeta"></span>
+</li>

package/src/js/tcmd/components/OverlayRow.js

@@ -0,0 +1,47 @@
+// Project: TinyCommand
+// Author:  Sebastien Pierre
+// License: BSD
+// Created: 2026-10-17
+
+// Module: tcmd/components/OverlayRow
+// One row of the shared list overlay (`u` history / `⇧T` trash). Reads
+// `{ item: { text, meta, dim }, index, currentRow }`; the builder snapshots the
+// overlay cursor into a plain `currentRow` boolean, with the shared `cursor`
+// cell as fallback for hand-built bags.
+//
+// Environment: `accentSecondaryFg`, `textFg`, `textSecondaryFg`,
+// `textHeadingFg`, `cursorBg` (current row background), `currentClass` (web).
+
+import { unwrap } from "select/state/cells"
+
+// Function: rowCurrent
+// Whether the row is the overlay cursor: the plain `currentRow` flag wins over
+// the shared `cursor` cell.
+function rowCurrent(data) {
+	if (data.currentRow !== undefined) return data.currentRow === true
+	return data.index === unwrap(data.cursor)
+}
+
+// Function: createBehaviors
+// Builds the OverlayRow behavior map for the given renderer environment.
+function createBehaviors(env) {
+	return {
+		rowBg: (_self, data) => (rowCurrent(data) ? env.cursorBg : undefined),
+		rowClass: (_self, data) => (rowCurrent(data) ? env.currentClass : null),
+		rowCurrent: (_self, data) => `${rowCurrent(data)}`,
+		rowDim: (_self, data) => `${Boolean(data.item?.dim)}`,
+		rowMarker: (_self, data) => (rowCurrent(data) ? "> " : "  "),
+		rowMarkerFg: () => env.accentSecondaryFg,
+		rowText: (_self, data) => data.item?.text ?? "",
+		// The cursor row reads bright; an undone/dim row (a superseded history
+		// entry) takes the secondary colour, like a hint.
+		rowTextFg: (_self, data) =>
+			rowCurrent(data) ? env.textHeadingFg : data.item?.dim ? env.textSecondaryFg : env.textFg,
+		rowMeta: (_self, data) => data.item?.meta ?? "",
+		rowMetaFg: () => env.textSecondaryFg,
+	}
+}
+
+export { createBehaviors, rowCurrent }
+
+// EOF

package/src/js/tcmd/components/OverlayRow.xml

@@ -0,0 +1,9 @@
+<box flexDirection="row" height="1" columnGap="1" out:backgroundColor="rowBg" on:click="item.key!overlay:select">
+	<text out="rowMarker" width="2" out:fg="rowMarkerFg"></text>
+	<box flexGrow="1" minWidth="0" overflow="hidden">
+		<text out="rowText" out:fg="rowTextFg" wrapMode="none" truncate="true"></text>
+	</box>
+	<box flexShrink="0" overflow="hidden">
+		<text out="rowMeta" out:fg="rowMetaFg" wrapMode="none" truncate="true"></text>
+	</box>
+</box>

package/src/js/tcmd/components/format.js

@@ -5,7 +5,10 @@
 
 // Module: tcmd/components/format
 // Presentation-only formatting helpers (sizes, counts, header title) shared by
-// every component for every renderer.
+// every component for every renderer. Size and disk formatting come from
+// `core/format` because operations report the same values.
+
+import { formatDisk, formatSize } from "../core/format.js"
 
 // Function: formatTitle
 // Header line `TinyCmd - HOST DIR/BASE` for the given directory. When it
@@ -78,28 +81,6 @@ function elideCrumbs(segments, width) {
 	return [marker, ...rest]
 }
 
-// Function: formatSize
-// Human-readable byte size; directories pass through their own label.
-function formatSize(bytes) {
-	const value = Number(bytes ?? 0)
-	if (value < 1024) return `${value}B`
-	const units = ["K", "M", "G", "T"]
-	let size = value / 1024
-	let unit = 0
-	while (size >= 1024 && unit < units.length - 1) {
-		size /= 1024
-		unit++
-	}
-	return `${size >= 100 ? Math.round(size) : size.toFixed(1)}${units[unit]}`
-}
-
-// Function: formatDisk
-// Compact free/total disk line, e.g. "12G free of 256G".
-function formatDisk(disk) {
-	if (!disk) return ""
-	return `${formatSize(disk.free)} free of ${formatSize(disk.total)}`
-}
-
 // Function: formatTime
 // Local `YYYY-MM-DD HH:MM` stamp for a millisecond epoch; empty when absent.
 function formatTime(ms) {