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

package/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// pnpm links the bin at install time, before anything is built, so it cannot live in build/.
+import './build/index.js';

package/build/cards.d.ts

@@ -1,14 +1,14 @@
-import type { ApiResult, CardConfig } from '@stats-forge/github-stats-forge-core/api';
 /**
  * @file What each card accepts, in the order the prompts walk it.
  *
  * The core schemas validate these params;
  * this catalog is what makes them navigable, so it carries the prose and the choices a schema has no room for.
  */
+import type { ApiResult, CardConfig } from '@stats-forge/github-stats-forge-core/api';
 /** How a param is asked for, and how the answer becomes a query string value. */
 type OptionKind = 'text' | 'boolean' | 'number' | 'list' | 'choice';
 /** One param of one card. */
-export interface CardOption {
+export interface CardField {
     /** Query param the answer is written to. */
     name: string;
     /** What the prompt asks. */
@@ -19,14 +19,28 @@ export interface CardOption {
     /** Shown under the prompt, for anything the label cannot say. */
     hint?: string;
 }
+/** Which section of the option menu a param sits in. */
+export type OptionGroup = 'data' | 'display' | 'text' | 'colors';
+/**
+ * The menu's sections, in the order it shows them.
+ * A section no option sits under is dropped, so a card that counts nothing has none.
+ */
+export declare const OPTION_GROUPS: ReadonlyArray<{
+    group: OptionGroup;
+    label: string;
+}>;
+/** One optional param of one card. It is required so a new option cannot go ungrouped. */
+export interface CardOption extends CardField {
+    group: OptionGroup;
+}
 /** A card, its params, and the core handler that renders it. */
 export interface CardKind {
     id: string;
     label: string;
     /** Whether rendering it calls the GitHub API, and so needs a token. */
     needsToken: boolean;
-    /** Asked first: the card renders nothing without them. */
-    required: ReadonlyArray<CardOption>;
+    /** Asked first, before the menu opens, so no section applies to them. */
+    required: ReadonlyArray<CardField>;
     /** Everything else, navigable in any order. */
     options: ReadonlyArray<CardOption>;
     /** @returns The rendered card, or the rendered error. */
@@ -34,7 +48,11 @@ export interface CardKind {
 }
 /** Colors and the theme, which every card accepts. */
 export declare const COMMON_OPTIONS: ReadonlyArray<CardOption>;
-/** Every card, with the options every card shares appended to its own. */
+/**
+ * Every card, with the options every card shares beside its own.
+ * The shared ones come first so the theme heads the colors section,
+ * which is where a card's own color options land behind it.
+ */
 export declare const cards: ReadonlyArray<CardKind>;
 /**
  * @returns The card, or `undefined` when nothing renders under that name.

package/build/cards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cards.d.ts","sourceRoot":"","sources":["../src/cards.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAEtF;;;;;GAKG;AAEH,iFAAiF;AACjF,KAAK,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEpE,6BAA6B;AAC7B,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,UAAU,CAAC;IACjB,wFAAwF;IACxF,OAAO,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAChC,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,gEAAgE;AAChE,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,UAAU,EAAE,OAAO,CAAC;IACpB,0DAA0D;IAC1D,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACpC,+CAA+C;IAC/C,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACnC,yDAAyD;IACzD,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;CACnF;AAID,sDAAsD;AACtD,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,UAAU,CA8BpD,CAAC;AA8VF,0EAA0E;AAC1E,eAAO,MAAM,KAAK,EAAE,aAAa,CAAC,QAAQ,CAGvC,CAAC;AAEJ;;GAEG;AACH,eAAO,MAAM,QAAQ,OAAQ,MAAM,KAAG,QAAQ,GAAG,SAAiD,CAAC"}
+{"version":3,"file":"cards.d.ts","sourceRoot":"","sources":["../src/cards.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAEtF,iFAAiF;AACjF,KAAK,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEpE,6BAA6B;AAC7B,MAAM,WAAW,SAAS;IACxB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,UAAU,CAAC;IACjB,wFAAwF;IACxF,OAAO,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAChC,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wDAAwD;AACxD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,aAAa,CAAC;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAK9E,CAAC;AAEF,0FAA0F;AAC1F,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,gEAAgE;AAChE,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,UAAU,EAAE,OAAO,CAAC;IACpB,yEAAyE;IACzE,QAAQ,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACnC,+CAA+C;IAC/C,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACnC,yDAAyD;IACzD,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;CACnF;AAID,sDAAsD;AACtD,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,UAAU,CAkCpD,CAAC;AAsYF;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,aAAa,CAAC,QAAQ,CAGvC,CAAC;AAEJ;;GAEG;AACH,eAAO,MAAM,QAAQ,OAAQ,MAAM,KAAG,QAAQ,GAAG,SAAiD,CAAC"}

package/build/cards.js

@@ -1,4 +1,20 @@
+/**
+ * @file What each card accepts, in the order the prompts walk it.
+ *
+ * The core schemas validate these params;
+ * this catalog is what makes them navigable, so it carries the prose and the choices a schema has no room for.
+ */
 import { contributedTo, gist, org, pin, stats, themes, topLangs, wakatime, } from '@stats-forge/github-stats-forge-core/api';
+/**
+ * The menu's sections, in the order it shows them.
+ * A section no option sits under is dropped, so a card that counts nothing has none.
+ */
+export const OPTION_GROUPS = [
+    { group: 'data', label: 'What it counts' },
+    { group: 'display', label: 'What it shows' },
+    { group: 'text', label: 'Text and size' },
+    { group: 'colors', label: 'Colors and border' },
+];
 const THEME_NAMES = Object.keys(themes);
 /** Colors and the theme, which every card accepts. */
 export const COMMON_OPTIONS = [
@@ -6,6 +22,7 @@ export const COMMON_OPTIONS = [
         name: 'theme',
         label: 'Theme',
         kind: 'choice',
+        group: 'colors',
         choices: THEME_NAMES,
         hint: 'An unknown name falls back to the default theme',
     },
@@ -13,24 +30,27 @@ export const COMMON_OPTIONS = [
         name: 'title_color',
         label: 'Title color',
         kind: 'text',
+        group: 'colors',
         hint: 'Hex, no #',
     },
-    { name: 'text_color', label: 'Text color', kind: 'text', hint: 'Hex, no #' },
-    { name: 'icon_color', label: 'Icon color', kind: 'text', hint: 'Hex, no #' },
+    { name: 'text_color', label: 'Text color', kind: 'text', group: 'colors', hint: 'Hex, no #' },
+    { name: 'icon_color', label: 'Icon color', kind: 'text', group: 'colors', hint: 'Hex, no #' },
     {
         name: 'bg_color',
         label: 'Background color',
         kind: 'text',
+        group: 'colors',
         hint: 'Hex, no #, or a gradient: angle,color,color',
     },
     {
         name: 'border_color',
         label: 'Border color',
         kind: 'text',
+        group: 'colors',
         hint: 'Hex, no #',
     },
-    { name: 'border_radius', label: 'Border radius', kind: 'number' },
-    { name: 'hide_border', label: 'Hide the border', kind: 'boolean' },
+    { name: 'border_radius', label: 'Border radius', kind: 'number', group: 'colors' },
+    { name: 'hide_border', label: 'Hide the border', kind: 'boolean', group: 'colors' },
 ];
 /**
  * The two ends of a card's date range.
@@ -40,14 +60,15 @@ export const COMMON_OPTIONS = [
 const rangeOptions = (counted) => {
     const hint = 'A year, a month or a day: 2024, 2024-03, 2024-03-15';
     return [
-        { name: 'from', label: `Count ${counted} from`, kind: 'text', hint },
-        { name: 'to', label: `Count ${counted} up to`, kind: 'text', hint },
+        { name: 'from', label: `Count ${counted} from`, kind: 'text', group: 'data', hint },
+        { name: 'to', label: `Count ${counted} up to`, kind: 'text', group: 'data', hint },
     ];
 };
 const LOCALE_OPTION = {
     name: 'locale',
     label: 'Locale',
     kind: 'text',
+    group: 'text',
     hint: 'Two-letter code, e.g. es',
 };
 const CARDS = [
@@ -61,76 +82,88 @@ const CARDS = [
                 name: 'show',
                 label: 'Extra stats to show',
                 kind: 'list',
+                group: 'display',
                 choices: stats.OPTIONS.show,
             },
             {
                 name: 'hide',
                 label: 'Stats to hide',
                 kind: 'list',
+                group: 'display',
                 choices: stats.OPTIONS.hide,
             },
-            { name: 'show_icons', label: 'Show the stat icons', kind: 'boolean' },
-            { name: 'hide_rank', label: 'Hide the rank circle', kind: 'boolean' },
+            { name: 'show_icons', label: 'Show the stat icons', kind: 'boolean', group: 'display' },
+            { name: 'hide_rank', label: 'Hide the rank circle', kind: 'boolean', group: 'display' },
             {
                 name: 'rank_icon',
                 label: 'Rank indicator',
                 kind: 'choice',
+                group: 'display',
                 choices: stats.OPTIONS.rank_icon,
             },
             {
                 name: 'include_all_commits',
                 label: 'Count commits of all time',
                 kind: 'boolean',
+                group: 'data',
             },
             ...rangeOptions('commits'),
             {
                 name: 'exclude_repo',
                 label: 'Repositories to exclude',
                 kind: 'list',
+                group: 'data',
             },
             {
                 name: 'repo',
                 label: 'Repositories the search-based stats are scoped to',
                 kind: 'list',
+                group: 'data',
             },
             {
                 name: 'owner',
                 label: 'Owners the search-based stats are scoped to',
                 kind: 'list',
+                group: 'data',
             },
             {
                 name: 'role',
                 label: 'Owner affiliations to include',
                 kind: 'list',
+                group: 'data',
                 choices: stats.OPTIONS.role,
             },
             {
                 name: 'contribs_include_own_repos',
                 label: 'Count contributions to your own repositories',
                 kind: 'boolean',
+                group: 'data',
             },
-            { name: 'custom_title', label: 'Card title', kind: 'text' },
-            { name: 'hide_title', label: 'Hide the title', kind: 'boolean' },
-            { name: 'card_width', label: 'Card width', kind: 'number' },
-            { name: 'line_height', label: 'Line height', kind: 'number' },
-            { name: 'text_bold', label: 'Bold stat values', kind: 'boolean' },
+            { name: 'custom_title', label: 'Card title', kind: 'text', group: 'text' },
+            { name: 'hide_title', label: 'Hide the title', kind: 'boolean', group: 'text' },
+            { name: 'card_width', label: 'Card width', kind: 'number', group: 'text' },
+            { name: 'line_height', label: 'Line height', kind: 'number', group: 'text' },
+            { name: 'text_bold', label: 'Bold stat values', kind: 'boolean', group: 'text' },
             {
                 name: 'number_format',
                 label: 'Number format',
                 kind: 'choice',
+                group: 'text',
                 choices: stats.OPTIONS.number_format,
             },
             {
                 name: 'number_precision',
                 label: 'Decimals kept when abbreviating',
                 kind: 'number',
+                group: 'text',
             },
             {
                 name: 'disable_animations',
                 label: 'Disable the animations',
                 kind: 'boolean',
+                group: 'text',
             },
-            { name: 'ring_color', label: 'Rank ring color', kind: 'text' },
+            { name: 'ring_color', label: 'Rank ring color', kind: 'text', group: 'colors' },
             LOCALE_OPTION,
         ],
         render: stats,
@@ -145,51 +178,59 @@ const CARDS = [
                 name: 'layout',
                 label: 'Layout',
                 kind: 'choice',
+                group: 'display',
                 choices: topLangs.OPTIONS.layout,
             },
-            { name: 'langs_count', label: 'Languages to show', kind: 'number' },
-            { name: 'hide', label: 'Languages to hide', kind: 'list' },
-            { name: 'exclude_repo', label: 'Repositories to exclude', kind: 'list' },
+            { name: 'langs_count', label: 'Languages to show', kind: 'number', group: 'data' },
+            { name: 'hide', label: 'Languages to hide', kind: 'list', group: 'data' },
+            { name: 'exclude_repo', label: 'Repositories to exclude', kind: 'list', group: 'data' },
             {
                 name: 'size_weight',
                 label: "Weight given to a language's size",
                 kind: 'number',
+                group: 'data',
             },
             {
                 name: 'count_weight',
                 label: 'Weight given to its repository count',
                 kind: 'number',
+                group: 'data',
             },
             {
                 name: 'stats_format',
                 label: 'Show values as',
                 kind: 'choice',
+                group: 'display',
                 choices: topLangs.OPTIONS.stats_format,
             },
             {
                 name: 'hide_progress',
                 label: 'Hide the progress bars',
                 kind: 'boolean',
+                group: 'display',
             },
-            { name: 'hide_values', label: 'Hide the values', kind: 'boolean' },
+            { name: 'hide_values', label: 'Hide the values', kind: 'boolean', group: 'display' },
             {
                 name: 'prog_bar_bg_color',
                 label: 'Progress bar background color',
                 kind: 'text',
+                group: 'colors',
             },
             {
                 name: 'role',
                 label: 'Owner affiliations to include',
                 kind: 'list',
+                group: 'data',
                 choices: topLangs.OPTIONS.role,
             },
-            { name: 'custom_title', label: 'Card title', kind: 'text' },
-            { name: 'hide_title', label: 'Hide the title', kind: 'boolean' },
-            { name: 'card_width', label: 'Card width', kind: 'number' },
+            { name: 'custom_title', label: 'Card title', kind: 'text', group: 'text' },
+            { name: 'hide_title', label: 'Hide the title', kind: 'boolean', group: 'text' },
+            { name: 'card_width', label: 'Card width', kind: 'number', group: 'text' },
             {
                 name: 'disable_animations',
                 label: 'Disable the animations',
                 kind: 'boolean',
+                group: 'text',
             },
             LOCALE_OPTION,
         ],
@@ -204,31 +245,35 @@ const CARDS = [
             { name: 'repo', label: 'Repository name', kind: 'text' },
         ],
         options: [
-            { name: 'show_owner', label: 'Show the owner', kind: 'boolean' },
+            { name: 'show_owner', label: 'Show the owner', kind: 'boolean', group: 'display' },
             {
                 name: 'show',
                 label: 'Extra stats to show',
                 kind: 'list',
+                group: 'display',
                 choices: pin.OPTIONS.show,
             },
-            { name: 'show_icons', label: 'Show the stat icons', kind: 'boolean' },
+            { name: 'show_icons', label: 'Show the stat icons', kind: 'boolean', group: 'display' },
             {
                 name: 'description_lines_count',
                 label: 'Lines the description wraps to',
                 kind: 'number',
+                group: 'text',
             },
             {
                 name: 'browser_rendering',
                 label: 'Let the browser wrap the description',
                 kind: 'boolean',
+                group: 'text',
             },
-            { name: 'card_width', label: 'Card width', kind: 'number' },
-            { name: 'line_height', label: 'Line height', kind: 'number' },
-            { name: 'text_bold', label: 'Bold stat values', kind: 'boolean' },
+            { name: 'card_width', label: 'Card width', kind: 'number', group: 'text' },
+            { name: 'line_height', label: 'Line height', kind: 'number', group: 'text' },
+            { name: 'text_bold', label: 'Bold stat values', kind: 'boolean', group: 'text' },
             {
                 name: 'number_format',
                 label: 'Number format',
                 kind: 'choice',
+                group: 'text',
                 choices: pin.OPTIONS.number_format,
             },
             LOCALE_OPTION,
@@ -245,35 +290,40 @@ const CARDS = [
                 name: 'show',
                 label: 'Extra stats to show',
                 kind: 'list',
+                group: 'display',
                 choices: org.OPTIONS.show,
             },
             {
                 name: 'hide',
                 label: 'Stats to hide',
                 kind: 'list',
+                group: 'display',
                 choices: org.OPTIONS.hide,
             },
-            { name: 'show_icons', label: 'Show the stat icons', kind: 'boolean' },
+            { name: 'show_icons', label: 'Show the stat icons', kind: 'boolean', group: 'display' },
             {
                 name: 'hide_description',
                 label: "Hide the organization's description",
                 kind: 'boolean',
+                group: 'display',
             },
-            { name: 'custom_title', label: 'Card title', kind: 'text' },
-            { name: 'hide_title', label: 'Hide the title', kind: 'boolean' },
-            { name: 'card_width', label: 'Card width', kind: 'number' },
-            { name: 'line_height', label: 'Line height', kind: 'number' },
-            { name: 'text_bold', label: 'Bold stat values', kind: 'boolean' },
+            { name: 'custom_title', label: 'Card title', kind: 'text', group: 'text' },
+            { name: 'hide_title', label: 'Hide the title', kind: 'boolean', group: 'text' },
+            { name: 'card_width', label: 'Card width', kind: 'number', group: 'text' },
+            { name: 'line_height', label: 'Line height', kind: 'number', group: 'text' },
+            { name: 'text_bold', label: 'Bold stat values', kind: 'boolean', group: 'text' },
             {
                 name: 'number_format',
                 label: 'Number format',
                 kind: 'choice',
+                group: 'text',
                 choices: org.OPTIONS.number_format,
             },
             {
                 name: 'disable_animations',
                 label: 'Disable the animations',
                 kind: 'boolean',
+                group: 'text',
             },
             LOCALE_OPTION,
         ],
@@ -285,16 +335,18 @@ const CARDS = [
         needsToken: true,
         required: [{ name: 'username', label: 'GitHub username', kind: 'text' }],
         options: [
-            { name: 'repos_count', label: 'Repositories to show', kind: 'number' },
+            { name: 'repos_count', label: 'Repositories to show', kind: 'number', group: 'data' },
             {
                 name: 'include_own_repos',
                 label: 'Include your own repositories',
                 kind: 'boolean',
+                group: 'data',
             },
             {
                 name: 'exclude_repo',
                 label: 'Repositories to exclude',
                 kind: 'list',
+                group: 'data',
                 hint: 'Each one an owner/name, or just the name',
             },
             ...rangeOptions('contributions'),
@@ -302,15 +354,17 @@ const CARDS = [
                 name: 'hide_years',
                 label: 'Hide the year marks',
                 kind: 'boolean',
+                group: 'display',
                 hint: 'One mark per contribution year, filled for the years that repo got one',
             },
-            { name: 'custom_title', label: 'Card title', kind: 'text' },
-            { name: 'hide_title', label: 'Hide the title', kind: 'boolean' },
-            { name: 'card_width', label: 'Card width', kind: 'number' },
+            { name: 'custom_title', label: 'Card title', kind: 'text', group: 'text' },
+            { name: 'hide_title', label: 'Hide the title', kind: 'boolean', group: 'text' },
+            { name: 'card_width', label: 'Card width', kind: 'number', group: 'text' },
             {
                 name: 'disable_animations',
                 label: 'Disable the animations',
                 kind: 'boolean',
+                group: 'text',
             },
             LOCALE_OPTION,
         ],
@@ -322,11 +376,12 @@ const CARDS = [
         needsToken: true,
         required: [{ name: 'id', label: 'Gist ID', kind: 'text' }],
         options: [
-            { name: 'show_owner', label: 'Show the owner', kind: 'boolean' },
+            { name: 'show_owner', label: 'Show the owner', kind: 'boolean', group: 'display' },
             {
                 name: 'browser_rendering',
                 label: 'Let the browser wrap the description',
                 kind: 'boolean',
+                group: 'text',
             },
             LOCALE_OPTION,
         ],
@@ -342,34 +397,39 @@ const CARDS = [
                 name: 'layout',
                 label: 'Layout',
                 kind: 'choice',
+                group: 'display',
                 choices: wakatime.OPTIONS.layout,
             },
             {
                 name: 'display_format',
                 label: 'Show values as',
                 kind: 'choice',
+                group: 'display',
                 choices: wakatime.OPTIONS.display_format,
             },
-            { name: 'langs_count', label: 'Languages to show', kind: 'number' },
-            { name: 'hide', label: 'Languages to hide', kind: 'list' },
+            { name: 'langs_count', label: 'Languages to show', kind: 'number', group: 'data' },
+            { name: 'hide', label: 'Languages to hide', kind: 'list', group: 'data' },
             {
                 name: 'hide_progress',
                 label: 'Hide the progress bars',
                 kind: 'boolean',
+                group: 'display',
             },
-            { name: 'custom_title', label: 'Card title', kind: 'text' },
-            { name: 'hide_title', label: 'Hide the title', kind: 'boolean' },
-            { name: 'card_width', label: 'Card width', kind: 'number' },
-            { name: 'line_height', label: 'Line height', kind: 'number' },
+            { name: 'custom_title', label: 'Card title', kind: 'text', group: 'text' },
+            { name: 'hide_title', label: 'Hide the title', kind: 'boolean', group: 'text' },
+            { name: 'card_width', label: 'Card width', kind: 'number', group: 'text' },
+            { name: 'line_height', label: 'Line height', kind: 'number', group: 'text' },
             {
                 name: 'disable_animations',
                 label: 'Disable the animations',
                 kind: 'boolean',
+                group: 'text',
             },
             {
                 name: 'api_domain',
                 label: 'WakaTime instance',
                 kind: 'text',
+                group: 'data',
                 hint: 'Defaults to wakatime.com',
             },
             LOCALE_OPTION,
@@ -377,10 +437,14 @@ const CARDS = [
         render: wakatime,
     },
 ];
-/** Every card, with the options every card shares appended to its own. */
+/**
+ * Every card, with the options every card shares beside its own.
+ * The shared ones come first so the theme heads the colors section,
+ * which is where a card's own color options land behind it.
+ */
 export const cards = CARDS.map((card) => ({
     ...card,
-    options: [...card.options, ...COMMON_OPTIONS],
+    options: [...COMMON_OPTIONS, ...card.options],
 }));
 /**
  * @returns The card, or `undefined` when nothing renders under that name.

package/build/prompts.d.ts

@@ -1,11 +1,12 @@
-import type { CardKind, CardOption } from './cards.ts';
-import type { Answer } 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 type { CardKind, CardOption } from './cards.ts';
+import type { Answer } from './query.ts';
 /** @returns The card to render. */
 export declare const pickCard: () => Promise<CardKind>;
 /** How a trip through the option menu ended. */

package/build/prompts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC;;;;;GAKG;AAEH,mCAAmC;AACnC,eAAO,MAAM,QAAQ,QAAO,OAAO,CAAC,QAAQ,CAIxC,CAAC;AAuCL,gDAAgD;AAChD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEtD,sDAAsD;AACtD,MAAM,WAAW,IAAI;IACnB,uCAAuC;IACvC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;CAC9C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,SACpB,QAAQ,QACR,IAAI,WACD,MAAM,KACd,OAAO,CAAC,UAAU,CAmCpB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,SAAgB,QAAQ,KAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAY7E,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,eAAsB,MAAM,KAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAMhF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,QAAQ,QAAa,OAAO,CAAC,MAAM,GAAG,SAAS,CAM3D,CAAC"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC,mCAAmC;AACnC,eAAO,MAAM,QAAQ,QAAO,OAAO,CAAC,QAAQ,CAIxC,CAAC;AAuCL,gDAAgD;AAChD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AA8BtD,sDAAsD;AACtD,MAAM,WAAW,IAAI;IACnB,uCAAuC;IACvC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;CAC9C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,SACpB,QAAQ,QACR,IAAI,WACD,MAAM,KACd,OAAO,CAAC,UAAU,CAsDpB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,SAAgB,QAAQ,KAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAY7E,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,eAAsB,MAAM,KAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAMhF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,QAAQ,QAAa,OAAO,CAAC,MAAM,GAAG,SAAS,CAM3D,CAAC"}

package/build/prompts.js

@@ -1,12 +1,14 @@
-import { checkbox, confirm, input, password, select } from '@inquirer/prompts';
-import { cards } from './cards.js';
-import { describeAnswer } from './query.js';
 /**
  * @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 { cards, OPTION_GROUPS } from './cards.js';
+import { describeAnswer, UNSET } from './query.js';
 /** @returns The card to render. */
 export const pickCard = () => select({
     message: 'Which card?',
@@ -44,6 +46,29 @@ const askOption = async (option, current) => {
     });
     return answer.trim() === '' ? undefined : answer.trim();
 };
+/** Rows the list may use: the terminal, less the message, the help line and some air. */
+const menuHeight = () => 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, width) => 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) => {
+    const all = [
+        ...keys,
+        ['type', 'to jump — g generate, s save, q quit'],
+    ];
+    return all
+        .map(([key, action]) => `${styleText('bold', key)} ${styleText('dim', action)}`)
+        .join(styleText('dim', ' • '));
+};
 /**
  * Walks a card's options until the run asks for the card, or to leave.
  *
@@ -55,21 +80,37 @@ const askOption = async (option, current) => {
 export const navigateOptions = async (card, menu, status) => {
     // 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(({ 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({
             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' },
                 { name: 'Save these options', value: 'save' },
                 { name: 'Quit', value: 'quit' },
-                ...card.options.map((option) => ({
-                    name: `${option.label.padEnd(38)} ${describeAnswer(option, menu.answers.get(option.name))}`,
-                    value: option,
-                })),
+                ...sections,
             ],
         });
         menu.cursor = choice;