feat(tui): add responsive ASCII art and explicit calendar states

package.json

@@ -61,8 +61,8 @@
     "tsx": "^4.23.5",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.67.0",
-    "vite": "^6.4.3",
-    "vitest": "^4.1.11"
+    "vite": "^6.4.4",
+    "vitest": "^4.1.12"
   },
   "engines": {
     "node": ">=20.12.0"

src/app/app.test.ts

@@ -3,6 +3,8 @@ import { ansi } from '../core/canvas.js';
 
 const homeLoad = vi.hoisted(() => vi.fn());
 const dispose = vi.hoisted(() => vi.fn());
+const homeRender = vi.hoisted(() => vi.fn(() => ['Home']));
+const homeFooter = vi.hoisted(() => vi.fn(() => 'Footer'));
 
 vi.mock('./tabs.js', () => ({
   getAppTabs: () => [{ id: 'home', title: 'Home' }],
@@ -13,7 +15,9 @@ vi.mock('./views/home.js', () => ({
     id: 'home',
     title: 'Home',
     load: homeLoad,
-    render: () => ['Home'],
+    render: homeRender,
+    footerHint: homeFooter,
+    scrollsBody: () => true,
     dispose,
   },
 }));
@@ -49,6 +53,7 @@ describe('runApp terminal lifecycle', () => {
 
   beforeEach(() => {
     vi.clearAllMocks();
+    homeRender.mockReturnValue(['Home']);
     signal = undefined;
     Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
     Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true });
@@ -169,4 +174,28 @@ describe('runApp terminal lifecycle', () => {
       else Reflect.deleteProperty(process.stdout, 'columns');
     }
   });
+
+  it('shows overflow and scrolls the home body with arrow keys', async () => {
+    const rows = Object.getOwnPropertyDescriptor(process.stdout, 'rows');
+    const columns = Object.getOwnPropertyDescriptor(process.stdout, 'columns');
+    Object.defineProperty(process.stdout, 'rows', { value: 12, configurable: true });
+    Object.defineProperty(process.stdout, 'columns', { value: 40, configurable: true });
+    homeRender.mockReturnValue(Array.from({ length: 10 }, (_, index) => `Line ${index + 1}`));
+    try {
+      const running = runApp();
+      expect(homeFooter).toHaveBeenLastCalledWith(1, 40, true);
+      expect(writtenOutput()).toContain('0%');
+      const start = writtenOutput().length;
+      process.stdin.emit('data', Buffer.from('\x1b[B'));
+      expect(writtenOutput().slice(start)).toContain('Line 8');
+      expect(writtenOutput().slice(start)).toContain('33%');
+      process.stdin.emit('data', Buffer.from('q'));
+      await running;
+    } finally {
+      if (rows) Object.defineProperty(process.stdout, 'rows', rows);
+      else Reflect.deleteProperty(process.stdout, 'rows');
+      if (columns) Object.defineProperty(process.stdout, 'columns', columns);
+      else Reflect.deleteProperty(process.stdout, 'columns');
+    }
+  });
 });

src/app/app.ts

@@ -110,7 +110,7 @@ export async function runApp(): Promise<void> {
       view,
       cols,
       tabs.length,
-      helpOpen ? t().help.close : active?.footerHint?.(tabs.length, cols),
+      helpOpen ? t().help.close : active?.footerHint?.(tabs.length, cols, body.length > height),
       chrome.footerLines,
       helpOpen || active?.scrollsBody?.() === true ? scrollPercent() : undefined,
     );

src/app/chrome.ts

@@ -26,7 +26,7 @@ function renderRule(cols: number): string {
   const width = Number.isFinite(cols) ? Math.max(1, Math.floor(cols)) : 80;
   const indent = visualWidth(space.indent) < width ? space.indent : '';
   const ruleWidth = Math.max(1, bodyEdge(width) - visualWidth(indent));
-  return indent + type.hint(glyph.rule().repeat(ruleWidth));
+  return indent + c.muted(glyph.rule().repeat(ruleWidth));
 }
 
 function renderTabs(views: { id: ViewId; title: string }[], active: ViewId, cols: number): string {
@@ -144,12 +144,24 @@ export function passiveFooterHint(
   tabCount: number,
   cols = Number.POSITIVE_INFINITY,
   canGoBack = true,
+  canScroll = false,
 ): string {
   const trans = t();
   const dot = glyph.sep();
   const compactTabs = tabCount > 1 ? `1-${tabCount}/Tab ${dot} ` : '';
   const back = canGoBack ? `Esc ${trans.menu.hintBack} ${dot} ` : '';
   const backKey = canGoBack ? `Esc ${dot} ` : '';
+  if (canScroll) {
+    const move = glyph.updown();
+    return fitFooterHint(
+      cols,
+      `${digitTabHint(tabCount)}${move} ${trans.help.scroll} ${dot} ${back}q ${trans.menu.hintQuit} ${dot} ${trans.help.hint}`,
+      `${compactTabs}${move} ${dot} ${backKey}q ${dot} ?`,
+      `${move} ${dot} ${backKey}q`,
+      `${move} q`,
+      'q',
+    );
+  }
   return fitFooterHint(
     cols,
     `${digitTabHint(tabCount)}${back}q ${trans.menu.hintQuit} ${dot} ${trans.help.hint}`,

src/app/view.ts

@@ -32,5 +32,5 @@ export interface View {
   capturesInput?(): boolean;
   capturesPageKeys?(): boolean;
   handleBack?(ctx: AppContext): boolean;
-  footerHint?(tabCount: number, cols: number): string | undefined;
+  footerHint?(tabCount: number, cols: number, canScroll: boolean): string | undefined;
 }

src/app/views/docs-render.test.ts

@@ -119,6 +119,22 @@ describe('renderDocs', () => {
     expect(out).toContain('X Doc');
   });
 
+  it.each([5, 12])('keeps empty-search actions visible in a %i-row body', (bodyRows) => {
+    const searchResultsField = new ListField({
+      title: 'Results',
+      options: [{ value: 'search', label: 'Search again' }],
+    });
+    const lines = renderDocs(
+      { mode: 'searchResults', searchResultsField, searchResultsEmpty: true },
+      80,
+      bodyRows,
+    );
+    const text = lines.map(stripAnsi).join('\n');
+    expect(lines.length).toBeLessThanOrEqual(bodyRows);
+    expect(text).toContain('No documents match your search');
+    expect(text).toContain('Search again');
+  });
+
   it.each([
     ['en', 'Community governance and operations', 'Current', 'No documents match your search'],
     ['zh', '社区治理与组织协作运行机制', '当前', '未找到匹配的文档'],

src/app/views/docs-render.ts

@@ -6,6 +6,7 @@ import type { TextField } from '../fields/text-field.js';
 import type { DocLink } from '../../features/docs.js';
 import { visualWidth, wrapAnsiWithIndent } from '../../core/text.js';
 import { loadingLines } from '../../core/components/spinner.js';
+import { emptyStateLines } from '../../core/components/empty-state.js';
 
 export type DocsMode =
   | 'loading'
@@ -78,6 +79,22 @@ export function renderDocs(
   bodyRows = Number.POSITIVE_INFINITY,
 ): string[] {
   const trans = t();
+  const errorContext = state.errorMessage ? [...hintLines(state.errorMessage, cols), ''] : [];
+  const emptyContext =
+    state.mode === 'searchResults' && state.searchResultsEmpty
+      ? [
+          ...emptyStateLines(
+            'search',
+            trans.docs.searchNoResults,
+            cols,
+            bodyRows -
+              errorContext.length -
+              (state.searchResultsField?.render(Number.POSITIVE_INFINITY, cols).length ?? 0) -
+              1,
+          ),
+          '',
+        ]
+      : [];
   let lines: string[];
   switch (state.mode) {
     case 'loading':
@@ -117,16 +134,7 @@ export function renderDocs(
       break;
     case 'searchResults':
       lines = state.searchResultsField
-        ? renderListFieldWithContext(
-            [
-              ...(state.searchResultsEmpty
-                ? [...hintLines(trans.docs.searchNoResults, cols), '']
-                : []),
-            ],
-            state.searchResultsField,
-            bodyRows,
-            cols,
-          )
+        ? renderListFieldWithContext(emptyContext, state.searchResultsField, bodyRows, cols)
         : [];
       break;
     case 'readerLoading':
@@ -153,12 +161,11 @@ export function renderDocs(
     }
   }
   if (!state.errorMessage) return lines;
-  const errorContext = [...hintLines(state.errorMessage, cols), ''];
   const listField = listFieldForState(state);
   if (!listField) return [...errorContext, ...lines];
   const context =
     state.mode === 'searchResults' && state.searchResultsEmpty
-      ? [...errorContext, ...hintLines(trans.docs.searchNoResults, cols), '']
+      ? [...errorContext, ...emptyContext]
       : errorContext;
   return renderListFieldWithContext(context, listField, bodyRows, cols);
 }