windows-development-sandbox 1.4.3 → 1.7.0

package/dist/cli/tui/dialogs/path-picker.js

@@ -0,0 +1,423 @@
+// A full screen for choosing a folder (or a file): the path on top (type it, Tab completes), the folders below to
+// browse with the arrow keys, drives with their free space, new folders, a filter. Links are shown but never opened.
+import fs from 'node:fs';
+import path from 'node:path';
+import { freeBytesAt, humanBytes } from '../../../core/disk.js';
+import { Text } from '../text.js';
+import { Theme } from '../theme.js';
+import { paragraphs } from './paragraphs.js';
+import { completeInput, folderNameProblem, listDrives, listFolder, narrow, parentOf, splitInput, withSeparator, } from './path-listing.js';
+const win = path.win32;
+/** Resolves to the chosen path, or undefined when you press Esc. */
+export class PathPickerScreen {
+    o;
+    mode = 'input';
+    input;
+    cursor;
+    dir = '';
+    listing = { entries: [], more: 0 };
+    loadedDir = null;
+    selected = 0;
+    scroll = 0;
+    filter = '';
+    newName = '';
+    problem;
+    notice;
+    rows = 10;
+    constructor(o) {
+        this.o = o;
+        this.input = o.initial ?? '';
+        this.cursor = this.input.length;
+        this.syncListing();
+    }
+    render(size) {
+        const width = Math.min(size.width - 4, 100);
+        const inner = width - 4;
+        const typing = this.mode === 'input';
+        const frame = (t) => (typing ? Theme.accent(t) : Theme.muted(t));
+        const start = Math.max(0, this.cursor - inner + 1);
+        const shown = this.input.slice(start, start + inner);
+        const before = shown.slice(0, this.cursor - start);
+        const at = shown[this.cursor - start] ?? ' ';
+        const after = shown.slice(this.cursor - start + 1);
+        const cursor = typing ? (Theme.colour ? '\x1b[7m' + at + '\x1b[27m' : '_') : at;
+        const field = this.input === '' && !typing ? Theme.muted('type a path or pick below') : before + cursor + after;
+        const verdict = this.verdict();
+        const head = [
+            '',
+            '  ' + Theme.bold(this.o.title),
+            ...(this.o.about?.length ? paragraphs(this.o.about, size.width).map((l) => Theme.muted(l)) : []),
+            '  ' + frame('╭' + '─'.repeat(width - 2) + '╮'),
+            '  ' + frame('│') + ' ' + Text.fit(field, inner) + ' ' + frame('│'),
+            '  ' + frame('╰' + '─'.repeat(width - 2) + '╯'),
+            '  ' + this.verdictLine(verdict),
+            '  ' + Theme.muted(this.where()),
+        ];
+        const tail = this.mode === 'name' ? 3 : 0;
+        this.rows = Math.max(3, size.height - head.length - tail - 1);
+        const visible = this.visible();
+        this.keepSelectedInView(visible.length);
+        const lines = visible
+            .slice(this.scroll, this.scroll + this.rows)
+            .map((e, i) => this.row(e, this.scroll + i, size.width));
+        if (!visible.length)
+            lines.push('  ' + Theme.muted(this.listing.error ?? (this.filter ? 'Nothing matches the filter.' : 'Nothing here.')));
+        if (this.listing.more && this.scroll + this.rows >= visible.length)
+            lines.push('  ' +
+                Theme.muted(Theme.glyph.more + ' ' + this.listing.more + ' more (type more of the name to narrow the list)'));
+        const body = [...head, ...lines];
+        if (this.mode === 'name')
+            body.push('', '  New folder name: ' + this.newName + (Theme.colour ? '\x1b[7m \x1b[27m' : '_'));
+        return { path: this.o.path, body, keys: this.keys(), notice: this.notice };
+    }
+    async handle(key) {
+        this.notice = undefined;
+        if (key.ctrl && key.name === 's')
+            return this.choose(this.candidate());
+        if (key.ctrl && key.name === 'return')
+            return this.choose(this.candidate());
+        if (key.ctrl && key.name === 'n')
+            return this.startName();
+        switch (this.mode) {
+            case 'input':
+                return this.typing(key);
+            case 'browse':
+                return this.browsing(key);
+            case 'filter':
+                return this.filtering(key);
+            case 'name':
+                return this.naming(key);
+        }
+    }
+    // ---- what is shown ----
+    /** The entries on screen: the folder's, narrowed by what is typed after the last backslash and by the filter. */
+    visible() {
+        const prefix = this.mode === 'input' || this.dirIsTyped() ? splitInput(this.input).prefix : '';
+        const base = narrow(this.listing.entries, prefix, this.filter);
+        const up = this.dir === '' ? [] : [{ kind: 'up', name: '..', path: parentOf(this.dir) }];
+        return this.filter || prefix ? base : [...up, ...base];
+    }
+    dirIsTyped() {
+        return win.resolve(splitInput(this.input).dir || '.').toLowerCase() === win.resolve(this.dir || '.').toLowerCase();
+    }
+    row(e, index, width) {
+        const on = this.mode !== 'input' && index === this.selected;
+        const mark = on ? Theme.glyph.pointer : ' ';
+        let text;
+        switch (e.kind) {
+            case 'drive':
+                text = e.name + '   ' + Theme.muted(e.detail ?? '');
+                break;
+            case 'up':
+                text = Theme.glyph.back + ' ' + Theme.muted('up one folder');
+                break;
+            case 'dir':
+                text = Theme.glyph.folder + ' ' + e.name;
+                break;
+            case 'link':
+                text = Theme.muted(Theme.glyph.folder + ' ' + e.name + '  (a link: not opened)');
+                break;
+            case 'file':
+                text = Theme.muted('  ' + e.name);
+                break;
+        }
+        const line = ' ' + mark + ' ' + text;
+        return on ? Theme.selected(Text.fit(line, Math.min(width - 2, 100))) : line;
+    }
+    where() {
+        if (this.dir === '')
+            return 'This PC: pick a drive';
+        const free = freeBytesAt(this.dir);
+        const count = this.listing.entries.length + (this.listing.more || 0);
+        const drive = win.parse(win.resolve(this.dir)).root;
+        return (this.dir +
+            '  ' +
+            Theme.glyph.dot +
+            '  ' +
+            count +
+            (this.o.files ? ' items' : ' folders') +
+            (free === null ? '' : '  ' + Theme.glyph.dot + '  ' + humanBytes(free) + ' free on ' + drive));
+    }
+    verdict() {
+        const target = this.candidate();
+        if (!target)
+            return 'Type a ' + (this.o.files ? 'file' : 'folder') + ', or pick one below.';
+        if (this.kept(target))
+            return this.o.validate?.(target) ?? true;
+        if (!win.isAbsolute(target))
+            return 'Type a full path, like D:\\Sandbox.';
+        return this.o.validate?.(target) ?? true;
+    }
+    verdictLine(verdict) {
+        if (this.problem)
+            return Theme.error(Theme.glyph.cross + ' ' + this.problem);
+        const target = this.candidate();
+        if (verdict === true)
+            return (Theme.ok(Theme.glyph.ok) + ' ' + Theme.muted((this.o.use ? 'Will ' + this.o.use + ': ' : 'Will use: ') + target));
+        return target ? Theme.warn(Theme.glyph.cross + ' ' + verdict) : Theme.muted(verdict);
+    }
+    keys() {
+        const use = this.o.use ?? 'use this folder';
+        switch (this.mode) {
+            case 'input':
+                return [
+                    ['↵', 'choose', 0],
+                    ['tab', 'complete'],
+                    ['↓', 'browse'],
+                    ['esc', 'cancel', 0],
+                    ['ctrl+u', 'clear', 9],
+                ];
+            case 'browse':
+                return [
+                    ['↵ →', 'open', 1],
+                    ['←', 'up', 2],
+                    ['s', use, 0],
+                    ['n', 'new folder', 3],
+                    ['/', 'filter', 4],
+                    ['tab', 'type a path', 5],
+                    ['esc', 'cancel', 0],
+                ];
+            case 'filter':
+                return [
+                    ['↵', 'keep filter'],
+                    ['esc', 'clear', 0],
+                ];
+            case 'name':
+                return [
+                    ['↵', 'create', 0],
+                    ['esc', 'cancel', 0],
+                ];
+        }
+    }
+    // ---- what a path means ----
+    /** What choosing now would pick. In the browser a highlighted folder (or file) wins over the folder being shown. */
+    candidate() {
+        if (this.mode === 'browse' || this.mode === 'filter') {
+            const entry = this.visible()[this.selected];
+            if (entry && (entry.kind === 'dir' || (entry.kind === 'file' && this.o.files)))
+                return entry.path;
+            return this.dir === '' ? '' : this.dir.replace(/[\\/]+$/, '') || this.dir;
+        }
+        const text = this.input.trim();
+        return text.length > 3 ? text.replace(/[\\/]+$/, '') : text;
+    }
+    choose(target) {
+        const verdict = this.verdict();
+        if (verdict !== true) {
+            this.problem = verdict;
+            return;
+        }
+        return { done: this.kept(target) ? target : win.resolve(target) };
+    }
+    /** Is this typed text kept as typed: one of the allowed words, or a relative path where those are allowed? */
+    kept(target) {
+        return (this.o.literals ?? []).includes(target) || Boolean(this.o.relative && !win.isAbsolute(target));
+    }
+    // ---- the listing ----
+    /** Reads the folder the input names (only when it changed), keeping what was typed as a filter. */
+    syncListing() {
+        const { dir } = splitInput(this.input);
+        this.openDir(dir === '' || fs.existsSync(dir) ? dir : this.dir === '' ? '' : this.dir);
+    }
+    openDir(dir) {
+        if (dir === this.loadedDir)
+            return;
+        this.loadedDir = dir;
+        this.dir = dir;
+        this.listing = dir === '' ? { entries: listDrives(), more: 0 } : listFolder(dir, this.o.files ?? false);
+        this.selected = 0;
+        this.scroll = 0;
+    }
+    go(dir) {
+        this.filter = '';
+        this.openDir(dir);
+        this.input = withSeparator(dir);
+        this.cursor = this.input.length;
+        this.problem = undefined;
+    }
+    keepSelectedInView(count) {
+        this.selected = Math.max(0, Math.min(count - 1, this.selected));
+        if (this.selected < this.scroll)
+            this.scroll = this.selected;
+        if (this.selected >= this.scroll + this.rows)
+            this.scroll = this.selected - this.rows + 1;
+        this.scroll = Math.max(0, Math.min(this.scroll, Math.max(0, count - this.rows)));
+    }
+    // ---- keys ----
+    typing(key) {
+        if (key.name === 'escape')
+            return { done: undefined };
+        if (key.name === 'return')
+            return this.enterInput();
+        if (key.name === 'down' || key.name === 'pagedown') {
+            this.mode = 'browse';
+            return;
+        }
+        if (key.name === 'tab') {
+            const next = completeInput(this.input, this.listing.entries);
+            this.edit(next, next.length);
+            return;
+        }
+        if (key.name === 'left')
+            this.cursor = Math.max(0, this.cursor - 1);
+        else if (key.name === 'right')
+            this.cursor = Math.min(this.input.length, this.cursor + 1);
+        else if (key.name === 'home')
+            this.cursor = 0;
+        else if (key.name === 'end')
+            this.cursor = this.input.length;
+        else if (key.name === 'backspace') {
+            if (this.cursor > 0)
+                this.edit(this.input.slice(0, this.cursor - 1) + this.input.slice(this.cursor), this.cursor - 1);
+        }
+        else if (key.name === 'delete')
+            this.edit(this.input.slice(0, this.cursor) + this.input.slice(this.cursor + 1), this.cursor);
+        else if (key.ctrl && key.name === 'u')
+            this.edit('', 0);
+        else if (key.text) {
+            const add = key.text.replace(/[\r\n]/g, '').replace(/\//g, '\\');
+            this.edit(this.input.slice(0, this.cursor) + add + this.input.slice(this.cursor), this.cursor + add.length);
+        }
+        return;
+    }
+    edit(next, cursor) {
+        this.input = next;
+        this.cursor = Math.max(0, Math.min(next.length, cursor));
+        this.problem = undefined;
+        this.syncListing();
+        this.selected = 0;
+        this.scroll = 0;
+    }
+    /** A path ending in a backslash is opened to look inside; any other typed path is chosen. */
+    enterInput() {
+        const text = this.input.trim();
+        if (text === '') {
+            this.problem = 'Type a ' + (this.o.files ? 'file' : 'folder') + ', or press ↓ to browse.';
+            return;
+        }
+        if (/[\\/]$/.test(text) || /^[A-Za-z]:$/.test(text)) {
+            const { dir } = splitInput(text);
+            if (fs.existsSync(dir))
+                this.go(dir);
+            else
+                this.problem = 'No such folder: ' + dir;
+            return;
+        }
+        return this.choose(this.candidate());
+    }
+    browsing(key) {
+        const list = this.visible();
+        const move = (by) => {
+            this.selected = Math.max(0, Math.min(list.length - 1, this.selected + by));
+        };
+        if (key.name === 'escape')
+            return { done: undefined };
+        if (key.name === 'up') {
+            if (this.selected === 0)
+                this.mode = 'input';
+            else
+                move(-1);
+        }
+        else if (key.name === 'down')
+            move(1);
+        else if (key.name === 'pageup')
+            move(-this.rows);
+        else if (key.name === 'pagedown')
+            move(this.rows);
+        else if (key.name === 'home')
+            this.selected = 0;
+        else if (key.name === 'end')
+            this.selected = Math.max(0, list.length - 1);
+        else if (key.name === 'return' || key.name === 'right')
+            return this.open(list[this.selected]);
+        else if (key.name === 'left' || key.name === 'backspace')
+            this.go(parentOf(this.dir));
+        else if (key.name === 'tab')
+            this.mode = 'input';
+        else if (key.text === 's')
+            return this.choose(this.candidate());
+        else if (key.text === 'n')
+            return this.startName();
+        else if (key.text === '/') {
+            this.mode = 'filter';
+            this.filter = '';
+            this.selected = 0;
+        }
+        return;
+    }
+    open(entry) {
+        if (!entry)
+            return;
+        if (entry.kind === 'link') {
+            this.notice = 'That is a link; it is not opened. Pick a normal folder.';
+            return;
+        }
+        if (entry.kind === 'file')
+            return this.choose(entry.path);
+        this.go(entry.path);
+        return;
+    }
+    filtering(key) {
+        if (key.name === 'escape') {
+            this.filter = '';
+            this.mode = 'browse';
+            this.selected = 0;
+            return;
+        }
+        if (key.name === 'return') {
+            this.mode = 'browse';
+            return;
+        }
+        if (key.name === 'up')
+            this.selected = Math.max(0, this.selected - 1);
+        else if (key.name === 'down')
+            this.selected++;
+        else if (key.name === 'backspace') {
+            this.filter = this.filter.slice(0, -1);
+            this.selected = 0;
+        }
+        else if (key.text) {
+            this.filter += key.text;
+            this.selected = 0;
+        }
+        return;
+    }
+    startName() {
+        if (this.dir === '') {
+            this.notice = 'Open a drive first.';
+            return;
+        }
+        this.mode = 'name';
+        this.newName = '';
+        return;
+    }
+    naming(key) {
+        if (key.name === 'escape') {
+            this.mode = 'browse';
+            return;
+        }
+        if (key.name === 'backspace')
+            this.newName = this.newName.slice(0, -1);
+        else if (key.name === 'return') {
+            const problem = folderNameProblem(this.newName);
+            if (problem) {
+                this.notice = problem;
+                return;
+            }
+            const made = win.join(this.dir, this.newName.trim());
+            try {
+                fs.mkdirSync(made);
+            }
+            catch (e) {
+                this.notice = 'Could not create it: ' + (e instanceof Error ? e.message : String(e));
+                return;
+            }
+            this.mode = 'browse';
+            this.loadedDir = null;
+            this.go(made);
+        }
+        else if (key.text)
+            this.newName += key.text;
+        return;
+    }
+}

package/dist/cli/tui/dialogs/text-screen.d.ts

@@ -12,6 +12,12 @@ export interface TextOptions {
     validate?: (value: string) => true | string;
     /** Allow an empty answer (otherwise Enter on an empty field cancels). */
     allowEmpty?: boolean;
+    /** Only characters this matches can be typed (a number field takes digits only). */
+    accept?: RegExp;
+    /** A muted line under the field while nothing is wrong (what is allowed: "1 to 65536"). */
+    hint?: string;
+    /** A secret: the field shows * for each character (a password, an API key). */
+    masked?: boolean;
 }
 /** One line of text. Resolves to the text, or undefined when you press Esc. */
 export declare class TextScreen implements Screen<string | undefined> {

package/dist/cli/tui/dialogs/text-screen.js

@@ -14,7 +14,7 @@ export class TextScreen {
     }
     render(size) {
         const width = Math.min(size.width - 4, 100);
-        const chars = [...this.value];
+        const chars = [...this.value].map((ch) => (this.o.masked ? '*' : ch));
         // Scroll the field so the cursor stays visible.
         const inner = width - 4;
         const start = Math.max(0, this.cursor - inner + 1);
@@ -33,7 +33,11 @@ export class TextScreen {
             '  ' + Theme.accent('╭' + '─'.repeat(width - 2) + '╮'),
             '  ' + Theme.accent('│') + ' ' + Text.fit(text, inner) + ' ' + Theme.accent('│'),
             '  ' + Theme.accent('╰' + '─'.repeat(width - 2) + '╯'),
-            this.problem ? '  ' + Theme.error(Theme.glyph.cross + ' ' + this.problem) : '',
+            this.problem
+                ? '  ' + Theme.error(Theme.glyph.cross + ' ' + this.problem)
+                : this.o.hint
+                    ? '  ' + Theme.muted(this.o.hint)
+                    : '',
         ];
         return {
             path: this.o.path,
@@ -95,7 +99,10 @@ export class TextScreen {
             return;
         }
         if (key.text) {
-            const add = [...key.text.replace(/[\r\n]/g, '')];
+            const accept = this.o.accept;
+            const add = [...key.text.replace(/[\r\n]/g, '')].filter((c) => !accept || accept.test(c));
+            if (!add.length)
+                return;
             set([...chars.slice(0, this.cursor), ...add, ...chars.slice(this.cursor)], this.cursor + add.length);
         }
         return;

package/dist/cli/tui/frame.d.ts

@@ -1,18 +1,24 @@
+import { type KeyHint } from './key-bar.js';
+import { type NavState } from './nav.js';
 export interface FrameParts {
     /** Where you are, e.g. ['Settings', 'Languages and tools']. */
     path: string[];
     /** Short line under the title (what is running, which folder). */
     status?: string;
     body: string[];
-    /** [key, what it does] pairs, e.g. [['↵', 'open'], ['esc', 'back']]. */
-    keys: [string, string][];
+    /** [key, what it does] pairs, most important first, e.g. [['↵', 'open'], ['esc', 'back']]. */
+    keys: KeyHint[];
     /** A message for the last action (saved, invalid ...), shown above the footer. */
     notice?: string;
+    /** The navigation on the left (added by the app for every screen of the menu). */
+    nav?: NavState;
 }
 export declare class Frame {
     static title: string;
     static version: string;
-    /** Rows the body may use on a terminal `height` rows high (title, status, two rules, notice and keys take 6). */
+    /** Rows the body may use on a terminal `height` rows high (title, status, rules, notice, keys: 6). */
     static bodyHeight(height: number): number;
+    /** Columns the body may use on a terminal `width` columns wide: what the navigation and its divider leave. */
+    static bodyWidth(width: number, nav?: NavState): number;
     static render(parts: FrameParts, width: number, height: number): string[];
 }

package/dist/cli/tui/frame.js

@@ -1,14 +1,20 @@
-// The frame every screen is drawn in: a title bar with where you are, a status line, the screen's own body and a footer
-// with the keys that work here.
+// The frame every screen is drawn in: a title bar with where you are, a status line, the navigation on the left, the
+// screen's own body and a footer with the keys that work here.
+import { KeyBar } from './key-bar.js';
+import { SideNav } from './nav.js';
 import { Text } from './text.js';
 import { Theme } from './theme.js';
 export class Frame {
     static title = 'Windows Development Sandbox';
     static version = '';
-    /** Rows the body may use on a terminal `height` rows high (title, status, two rules, notice and keys take 6). */
+    /** Rows the body may use on a terminal `height` rows high (title, status, rules, notice, keys: 6). */
     static bodyHeight(height) {
         return Math.max(3, height - 6);
     }
+    /** Columns the body may use on a terminal `width` columns wide: what the navigation and its divider leave. */
+    static bodyWidth(width, nav) {
+        return nav ? Math.max(20, width - SideNav.width(width) - 1) : width;
+    }
     static render(parts, width, height) {
         const w = width - 1;
         const crumbs = [Frame.title, ...parts.path]
@@ -17,13 +23,18 @@ export class Frame {
         const right = Frame.version ? 'v' + Frame.version + ' ' : '';
         const title = Theme.bar(Text.fit(' ' + Theme.accent('◆') + ' ' + crumbs, w - Text.width(right)) + right);
         const status = ' ' + Text.truncate(parts.status ?? '', w - 2);
-        const rule = Theme.dim(Theme.glyph.line.repeat(w));
         const bodyRows = Frame.bodyHeight(height);
+        const navWidth = parts.nav ? SideNav.width(width) : 0;
+        const line = (joint) => Theme.dim(navWidth && navWidth + 1 < w
+            ? Theme.glyph.line.repeat(navWidth) + joint + Theme.glyph.line.repeat(w - navWidth - 1)
+            : Theme.glyph.line.repeat(w));
+        const side = parts.nav ? SideNav.render(parts.nav, width, bodyRows) : [];
+        const divider = Theme.dim(Theme.glyph.vline);
         const body = parts.body.slice(0, bodyRows);
         while (body.length < bodyRows)
             body.push('');
+        const rows = parts.nav ? body.map((row, i) => (side[i] ?? ' '.repeat(navWidth)) + divider + row) : body;
         const notice = parts.notice ? ' ' + Text.truncate(parts.notice, w - 2) : '';
-        const keys = ' ' + parts.keys.map(([k, what]) => Theme.key(k) + ' ' + Theme.muted(what)).join('  ');
-        return [title, status, rule, ...body, notice, rule, Text.truncate(keys, w)];
+        return [title, status, line('┬'), ...rows, notice, line('┴'), KeyBar.render(parts.keys, width)];
     }
 }

package/dist/cli/tui/index.d.ts

@@ -2,10 +2,14 @@ export { App } from './app.js';
 export { type Screen, type Size, type Step } from './screen.js';
 export { ConfirmScreen } from './dialogs/confirm-screen.js';
 export { MessageScreen } from './dialogs/message-screen.js';
-export { TextScreen } from './dialogs/text-screen.js';
-export { Frame } from './frame.js';
+export { dialogBox, OverlayScreen, overlayBox, type OverlayChoice, type OverlayOptions } from './dialogs/overlay.js';
+export { PathPickerScreen, type PathPickerOptions } from './dialogs/path-picker.js';
+export { TextScreen, type TextOptions } from './dialogs/text-screen.js';
+export { Frame, type FrameParts } from './frame.js';
+export { KeyBar, type KeyHint } from './key-bar.js';
+export { SideNav, type NavCategory, type NavSection, type NavState } from './nav.js';
 export { ListScreen } from './list/list-screen.js';
-export { type Category, type ListItem, type ListOptions, type ListResult, type Tab } from './list/list-types.js';
+export { type Category, type ListAction, type ListItem, type ListOptions, type ListResult, type Tab, } from './list/list-types.js';
 export { ExitRequested, Terminal, type Key } from './terminal.js';
 export { Text } from './text.js';
 export { Theme } from './theme.js';

package/dist/cli/tui/index.js

@@ -2,8 +2,12 @@
 export { App } from './app.js';
 export { ConfirmScreen } from './dialogs/confirm-screen.js';
 export { MessageScreen } from './dialogs/message-screen.js';
+export { dialogBox, OverlayScreen, overlayBox } from './dialogs/overlay.js';
+export { PathPickerScreen } from './dialogs/path-picker.js';
 export { TextScreen } from './dialogs/text-screen.js';
 export { Frame } from './frame.js';
+export { KeyBar } from './key-bar.js';
+export { SideNav } from './nav.js';
 export { ListScreen } from './list/list-screen.js';
 export { ExitRequested, Terminal } from './terminal.js';
 export { Text } from './text.js';

package/dist/cli/tui/key-bar.d.ts

@@ -0,0 +1,5 @@
+/** [key, what it does, importance]: importance 0 is never dropped, a bigger number goes earlier (default 5). */
+export type KeyHint = [string, string, number?];
+export declare class KeyBar {
+    static render(keys: readonly KeyHint[], width: number): string;
+}

package/dist/cli/tui/key-bar.js

@@ -0,0 +1,22 @@
+// The footer: only the keys that work on this screen. When the terminal is narrow the least important keys go first.
+import { Text } from './text.js';
+import { Theme } from './theme.js';
+export class KeyBar {
+    static render(keys, width) {
+        const line = (list) => ' ' + list.map(([k, what]) => Theme.key(k) + ' ' + Theme.muted(what)).join('  ');
+        const shown = [...keys];
+        const importance = (k) => k[2] ?? 5;
+        while (Text.width(line(shown)) > width - 1) {
+            // The least important one goes; of equals, the one further right.
+            let drop = -1;
+            shown.forEach((k, i) => {
+                if (importance(k) > 0 && (drop < 0 || importance(k) >= importance(shown[drop])))
+                    drop = i;
+            });
+            if (drop < 0)
+                break;
+            shown.splice(drop, 1);
+        }
+        return Text.truncate(line(shown), width - 1);
+    }
+}

package/dist/cli/tui/list/list-screen.d.ts

@@ -1,11 +1,13 @@
 import type { FrameParts } from '../frame.js';
 import type { Screen, Size, Step } from '../screen.js';
 import type { Key } from '../terminal.js';
-import type { ListResult, ListOptions } from './list-types.js';
+import type { Category, ListResult, ListOptions } from './list-types.js';
 export declare class ListScreen<T> implements Screen<ListResult<T>> {
     private readonly o;
     private category;
     private focus;
+    /** The list has the keyboard (false while the menu's navigation has it): the highlight is drawn softer. */
+    private active;
     private cursor;
     private offset;
     private query;
@@ -20,9 +22,28 @@ export declare class ListScreen<T> implements Screen<ListResult<T>> {
     private rowLine;
     private sideLines;
     private detailsLines;
+    /** The keys that work now, most important first (a narrow footer drops the later ones). */
     private keys;
     /** Programmatic notice (e.g. "Saved") shown until the next key. */
     setNotice(text: string | undefined): void;
+    /** The categories are shown by the menu's navigation, which drives them (no sidebar of its own). */
+    private get external();
+    private enterLabel;
+    private valueAt;
+    /** The categories of the list (empty without any). */
+    get categories(): readonly Category[];
+    /** Opens a category (the menu's navigation does this); a search in progress ends. */
+    setCategory(id: string): void;
+    /** Whether the list has the keyboard (the highlight is drawn softer when it has not). */
+    setActive(on: boolean): void;
+    /** The id of the category open in the sidebar (undefined without a sidebar). */
+    get currentCategory(): string | undefined;
+    /** The extra keys that work now (they may depend on the category and on the highlighted entry). */
+    private actionsNow;
+    /** Keys are going into the search box (digits and letters are text, not shortcuts). */
+    get isSearching(): boolean;
+    /** The entries ticked now (multi-select). */
+    ticked(): T[];
     handle(key: Key): Step<ListResult<T>>;
     private toggle;
     private switchCategory;