@stats-forge/github-stats-forge-cli 0.3.2 → 0.4.0

package/src/prompts.ts

@@ -1,17 +1,20 @@
-import { checkbox, confirm, input, password, select } from '@inquirer/prompts';
-
-import type { CardKind, CardOption } from './cards.ts';
-import { cards } from './cards.ts';
-import type { Answer } from './query.ts';
-import { describeAnswer } from './query.ts';
-
 /**
  * @file The navigation itself.
  *
- * A card first, then its required options, then a menu of every other option:
- * pick one, answer it, and land back on the menu with the answer beside it.
+ * A card first, then its required options, then a menu of every other option
+ * under the section it belongs to: pick one, answer it, and land back on the
+ * menu with the answer beside it.
  */
 
+import { styleText } from 'node:util';
+
+import { checkbox, confirm, input, password, select, Separator } from '@inquirer/prompts';
+
+import type { CardKind, CardOption } from './cards.ts';
+import { cards, OPTION_GROUPS } from './cards.ts';
+import type { Answer } from './query.ts';
+import { describeAnswer, UNSET } from './query.ts';
+
 /** @returns The card to render. */
 export const pickCard = (): Promise<CardKind> =>
   select({
@@ -59,6 +62,34 @@ const askOption = async (option: CardOption, current: Answer): Promise<Answer> =
 /** How a trip through the option menu ended. */
 export type MenuChoice = 'generate' | 'save' | 'quit';
 
+/** Rows the list may use: the terminal, less the message, the help line and some air. */
+const menuHeight = (): number =>
+  process.stdout.isTTY ? Math.max(10, process.stdout.rows - 6) : 15;
+
+/**
+ * A section heading, ruled out to the width of the labels under it.
+ *
+ * @returns A `Separator`, so the cursor steps straight over it.
+ */
+const heading = (label: string, width: number): Separator =>
+  new Separator(styleText('dim', `── ${label} ${'─'.repeat(Math.max(2, width - label.length))}`));
+
+/**
+ * Typing jumps to the first row whose label starts with what was typed, which is
+ * what keeps the three actions one key away however far down the list the cursor sits.
+ *
+ * @returns The line under the list.
+ */
+const keysHelpTip = (keys: ReadonlyArray<[key: string, action: string]>): string => {
+  const all: ReadonlyArray<[string, string]> = [
+    ...keys,
+    ['type', 'to jump — g generate, s save, q quit'],
+  ];
+  return all
+    .map(([key, action]) => `${styleText('bold', key)} ${styleText('dim', action)}`)
+    .join(styleText('dim', ' • '));
+};
+
 /** What the menu carries between trips through it. */
 export interface Menu {
   /** Answers so far, edited in place. */
@@ -86,22 +117,41 @@ export const navigateOptions = async (
 ): Promise<MenuChoice> => {
   // The label carries a description after an em dash; the menu wants the name.
   const [name = card.id] = card.label.split(' — ');
+  const width = Math.max(...card.options.map((option) => option.label.length));
 
   for (;;) {
+    // A section none of this card's options sit under is dropped, heading and all.
+    const sections = OPTION_GROUPS.flatMap<Separator | { name: string; value: CardOption }>(
+      ({ group, label }) => {
+        const options = card.options.filter((option) => option.group === group);
+        if (options.length === 0) {
+          return [];
+        }
+        return [
+          heading(label, width),
+          ...options.map((option) => {
+            // An unanswered option recedes, so what is set reads as the foreground.
+            const answer = describeAnswer(option, menu.answers.get(option.name));
+            const value = answer === UNSET ? styleText('dim', answer) : answer;
+            return { name: `${option.label.padEnd(width)}  ${value}`, value: option };
+          }),
+        ];
+      },
+    );
+
     const choice = await select<CardOption | MenuChoice>({
       message: status ? `${name} — ${status}` : `${name} — set an option, or generate`,
-      pageSize: 15,
+      pageSize: menuHeight(),
+      theme: { style: { keysHelpTip } },
       // Matched by reference against the values below, so the option objects work.
       // `default` does not accept an explicit undefined, so an unset cursor omits it.
       ...(menu.cursor !== undefined && { default: menu.cursor }),
       choices: [
+        heading('Actions', width),
         { name: 'Generate the card', value: 'generate' as const },
         { name: 'Save these options', value: 'save' as const },
         { name: 'Quit', value: 'quit' as const },
-        ...card.options.map((option) => ({
-          name: `${option.label.padEnd(38)} ${describeAnswer(option, menu.answers.get(option.name))}`,
-          value: option,
-        })),
+        ...sections,
       ],
     });
 

package/src/query.ts

@@ -1,5 +1,3 @@
-import type { CardKind, CardOption } from './cards.ts';
-
 /**
  * @file Answers in, query params out.
  *
@@ -7,6 +5,8 @@ import type { CardKind, CardOption } from './cards.ts';
  * answer becomes one here, and an unanswered option is simply absent.
  */
 
+import type { CardKind, CardOption } from './cards.ts';
+
 /** What a prompt answered, before it becomes a query param. */
 export type Answer = string | number | boolean | Array<string> | undefined;
 
@@ -37,15 +37,18 @@ export const toQuery = (answers: ReadonlyMap<string, Answer>): Record<string, st
   return query;
 };
 
+/** What the menu shows for an option nothing has answered. */
+export const UNSET = '—';
+
 /**
  * How an answer reads back in the option menu.
  *
- * @returns The value as the menu shows it.
+ * @returns The value as the menu shows it, or {@link UNSET}.
  */
 export const describeAnswer = (option: CardOption, value: Answer): string => {
   const param = toParam(value);
   if (param === undefined) {
-    return '—';
+    return UNSET;
   }
   return option.kind === 'boolean' ? (value === true ? 'yes' : 'no') : param;
 };

package/src/saved-card.ts

@@ -1,3 +1,10 @@
+/**
+ * @file A card, written down.
+ *
+ * The file holds what a query string would hold — the card and its options as
+ * strings — so it reads like the URL it stands for, and can be edited by hand.
+ */
+
 import { existsSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
@@ -6,13 +13,6 @@ import type { CardKind } from './cards.ts';
 import { findCard } from './cards.ts';
 import type { Answer } from './query.ts';
 
-/**
- * @file A card, written down.
- *
- * The file holds what a query string would hold — the card and its options as
- * strings — so it reads like the URL it stands for, and can be edited by hand.
- */
-
 /** A card and the answers it was rendered from: the shape of the file. */
 interface SavedCard {
   /** Which card, by the id the catalog gives it. */

package/src/tokens.ts

@@ -1,8 +1,3 @@
-import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
-
-import type { PersonalAccessToken } from '@stats-forge/github-stats-forge-core/api';
-
 /**
  * @file Where the GitHub token comes from.
  *
@@ -11,6 +6,11 @@ import type { PersonalAccessToken } from '@stats-forge/github-stats-forge-core/a
  * Whatever is left over is asked for interactively, so a first run needs no setup.
  */
 
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import type { PersonalAccessToken } from '@stats-forge/github-stats-forge-core/api';
+
 /** The file loaded when `--env-file` is not given. */
 export const DEFAULT_ENV_FILE = '.env';