@textui/widgets 0.5.0 → 0.6.1

package/dist/overlay/command-palette.d.ts

@@ -58,20 +58,6 @@ export interface CommandPaletteProps extends BoxProps {
      */
     openAt?: string;
 }
-/**
- * The command palette.
- *
- * It searches the command registry rather than a list someone maintained, so
- * a command registered anywhere is reachable here the moment it exists - which
- * is the payoff for insisting actions are commands. It also *runs* what it
- * finds, so choosing "Open dialog" here and pressing the button that opens a
- * dialog are the same act, reaching the same code.
- *
- * A command that declares an argument with `choices` gets a second level:
- * choosing it lists the choices, and picking one runs the command with it.
- * That is where sub-items come from - the command says what it needs and the
- * palette asks, rather than every caller inventing its own submenu.
- */
 export declare const CommandPalette: (props: CommandPaletteProps) => import("@textui/core").RenderOutput;
 /**
  * The argument the palette should ask about, if there is one.

package/dist/overlay/command-palette.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-palette.d.ts","sourceRoot":"","sources":["../../src/overlay/command-palette.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAa,MAAM,cAAc,CAAC;AAiB/F,MAAM,WAAW,mBAAoB,SAAQ,QAAQ;IACnD;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,iBAAiB,EAAE,GAAG,CAAC,MAAM,iBAAiB,EAAE,CAAC,CAAC;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,KAAK,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzD,OAAO,CAAC,IAAI,IAAI,CAAC;IACjB,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAClC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,qEA2ZzB,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,iBAAiB,EAC1B,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACtC,OAAO,GAAG,SAAS,CAKrB;AAqBD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAehG"}
+{"version":3,"file":"command-palette.d.ts","sourceRoot":"","sources":["../../src/overlay/command-palette.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAa,MAAM,cAAc,CAAC;AAiB/F,MAAM,WAAW,mBAAoB,SAAQ,QAAQ;IACnD;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,iBAAiB,EAAE,GAAG,CAAC,MAAM,iBAAiB,EAAE,CAAC,CAAC;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,KAAK,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzD,OAAO,CAAC,IAAI,IAAI,CAAC;IACjB,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAClC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAyBD,eAAO,MAAM,cAAc,qEAqczB,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,iBAAiB,EAC1B,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACtC,OAAO,GAAG,SAAS,CAKrB;AAyCD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAehG"}

package/dist/overlay/command-palette.js

@@ -2,20 +2,6 @@ import { defineComponent, h, stringWidth, useEffect, useFocusScope, useInput, us
 import { TextInput } from '../control/index.js';
 import { Menu } from '../navigation/index.js';
 import { hint } from './shared.js';
-/**
- * The command palette.
- *
- * It searches the command registry rather than a list someone maintained, so
- * a command registered anywhere is reachable here the moment it exists - which
- * is the payoff for insisting actions are commands. It also *runs* what it
- * finds, so choosing "Open dialog" here and pressing the button that opens a
- * dialog are the same act, reaching the same code.
- *
- * A command that declares an argument with `choices` gets a second level:
- * choosing it lists the choices, and picking one runs the command with it.
- * That is where sub-items come from - the command says what it needs and the
- * palette asks, rather than every caller inventing its own submenu.
- */
 export const CommandPalette = defineComponent('CommandPalette', (props) => {
     const theme = useTheme();
     const runtime = useRuntime();
@@ -99,10 +85,29 @@ export const CommandPalette = defineComponent('CommandPalette', (props) => {
                 ? { sectionBefore: command.category }
                 : {}),
         }));
+    /** The argument answered last, when this question came after one. */
+    const previousOf = (asked) => {
+        const last = Object.keys(asked.collected).at(-1);
+        return last === undefined ? undefined : (asked.command.args ?? []).find((arg) => arg.name === last);
+    };
+    /**
+     * One question back.
+     *
+     * After a first question the second is asked again from the start with
+     * the earlier answer withdrawn: a wrong provider is corrected by choosing
+     * another, not by closing the whole picker and opening it again. At the
+     * first question, the command list.
+     */
     const back = () => {
         // `null` is "never mind": whatever the preview did gets undone by whoever
         // did it, because only the command knows what it changed.
         pending?.arg.preview?.(null);
+        const previous = pending ? previousOf(pending) : undefined;
+        if (pending && previous) {
+            const { [previous.name]: _withdrawn, ...rest } = pending.collected;
+            drillInto(pending.command, previous, rest);
+            return;
+        }
         setPending(null);
         setChoices([]);
         setQuery('');
@@ -144,9 +149,16 @@ export const CommandPalette = defineComponent('CommandPalette', (props) => {
             setRefresh((n) => n + 1);
         onRun?.(id, args);
     };
-    /** Ask about one command. `choices` may be a function, and may be async. */
+    /**
+     * Ask about one command. `choices` may be a function, and may be async.
+     *
+     * A resolver is handed what was answered before this argument - and an
+     * argument that was not asked because its `default` stood was answered by
+     * that default. Left out, "the models of the chosen provider" would see no
+     * provider exactly when there was only one to choose from.
+     */
     const drillInto = (command, arg, collected = {}) => {
-        const resolved = typeof arg.choices === 'function' ? arg.choices() : arg.choices ?? [];
+        const resolved = typeof arg.choices === 'function' ? arg.choices(answeredBefore(command, arg, collected)) : arg.choices ?? [];
         setPending({ command, arg, collected });
         setQuery('');
         /*
@@ -253,8 +265,10 @@ export const CommandPalette = defineComponent('CommandPalette', (props) => {
             // anybody chose to be at: the caller drilled in on their behalf, and
             // the level underneath is a list of one. Backing out to it reads as
             // "escape did nothing", and the second escape - the one that would
-            // close it - is spent leaving a screen nobody asked to see.
-            if (pending && !openAt) {
+            // close it - is spent leaving a screen nobody asked to see. A question
+            // that came after one is different: there the level underneath is the
+            // earlier question, which somebody did choose to be at.
+            if (pending && (!openAt || previousOf(pending) !== undefined)) {
                 back();
                 return true;
             }
@@ -267,7 +281,7 @@ export const CommandPalette = defineComponent('CommandPalette', (props) => {
             onClose?.();
             return true;
         }
-        if (event.name === 'left' && pending && query === '' && !openAt) {
+        if (event.name === 'left' && pending && query === '' && (!openAt || previousOf(pending) !== undefined)) {
             back();
             return true;
         }
@@ -297,6 +311,8 @@ export const CommandPalette = defineComponent('CommandPalette', (props) => {
     // there - and a sentence about what a mode does is exactly the thing a
     // person needs whole. So the line under the list follows the highlight: the
     // choice's description while there is one, the question's otherwise.
+    // It is the one line in the panel that wraps rather than truncates,
+    // because it is the one place a sentence can be read whole.
     const chosen = pending ? offered[index] : undefined;
     const detail = pending
         ? chosen?.description
@@ -315,7 +331,14 @@ export const CommandPalette = defineComponent('CommandPalette', (props) => {
      * the things that decide it: a question with two short answers still needs
      * somewhere to type and a line saying what the keys do.
      */
-    const content = Math.max(...items.map((item) => rowWidth(item, descriptions)), ...(pending ? [stringWidth(pending.command.title) + 12] : [stringWidth(placeholder ?? '') + 4]));
+    const content = Math.max(...items.map((item) => rowWidth(item, descriptions)), ...(pending ? [stringWidth(pending.command.title) + 12] : [stringWidth(placeholder ?? '') + 4]), 
+    // The sentences the line under the list may show, so a question with
+    // three one-word answers is not a panel 28 wide wrapping a sentence
+    // three times under them. Capped like everything else by `maxWidth`.
+    ...(pending
+        ? [pending.arg.description ?? '', ...offered.map((choice) => choice.description ?? '')]
+            .map((sentence) => (sentence === '' ? 0 : stringWidth(sentence) + 6))
+        : []));
     return h('box', {
         role: 'dialog',
         label: 'Commands',
@@ -361,10 +384,19 @@ export const CommandPalette = defineComponent('CommandPalette', (props) => {
             if (command && argumentOf(command))
                 choose();
         },
+        // A typed answer's field is the answer, so its placeholder is the
+        // question. A list's field is a filter, and the question goes where
+        // there is room to say it once: here, while the line under the list
+        // is busy saying what each answer means; under the list, whole and
+        // wrapped, when the answers have nothing to say for themselves and
+        // that line would otherwise repeat this one, cut to whatever width
+        // three short answers gave the panel.
         placeholder: pending
-            ? (pending.arg.description ?? (pending.arg.choices === undefined
-                ? `${pending.command.title}${theme.glyphs.ellipsis}`
-                : `Choose ${pending.command.title.toLowerCase()}${theme.glyphs.ellipsis}`))
+            ? (pending.arg.choices === undefined
+                ? pending.arg.description ?? `${pending.command.title}${theme.glyphs.ellipsis}`
+                : offered.some((choice) => choice.description) && pending.arg.description
+                    ? pending.arg.description
+                    : `Choose ${pending.command.title.toLowerCase()}${theme.glyphs.ellipsis}`)
             : (placeholder ?? `Type a command${theme.glyphs.ellipsis}`),
         search: true,
         autoFocus: true,
@@ -386,7 +418,7 @@ export const CommandPalette = defineComponent('CommandPalette', (props) => {
     }), h('box', { height: 1, fill: theme.borderChars().top, fg: 'borderSubtle' }), 
     // What the highlighted row actually is, and how to move around. A palette
     // that shows only titles makes you run something to find out what it does.
-    h('box', { direction: 'row', gap: 1 }, h('text', { content: detail, fg: 'muted', flex: 1, truncate: 'end' }), h('text', { content: `${rows.length}`, fg: 'subtle' })), h('box', { direction: 'row', gap: 1 }, h('text', {
+    h('box', { direction: 'row', gap: 1, align: 'start' }, h('text', { content: detail, fg: 'muted', flex: 1, wrap: 'word' }), h('text', { content: `${rows.length}`, fg: 'subtle' })), h('box', { direction: 'row', gap: 1 }, h('text', {
         content: pending
             ? (pending.arg.choices === undefined
                 ? hint(theme, ['type it', 'enter confirm', 'esc back'])
@@ -418,6 +450,23 @@ export function argumentOf(command, collected = {}) {
     return (command.args ?? []).find((arg) => collected[arg.name] === undefined &&
         (arg.choices !== undefined || (arg.required === true && arg.default === undefined)));
 }
+/**
+ * What a `choices` resolver is told: the answers given, under the defaults
+ * of the arguments before this one that stood in for a question.
+ *
+ * Only the ones ahead of it in the declaration. An argument after this one
+ * has not been reached, and its default is not yet an answer to anything.
+ */
+function answeredBefore(command, arg, collected) {
+    const answered = {};
+    for (const spec of command.args ?? []) {
+        if (spec === arg)
+            break;
+        if (spec.default !== undefined)
+            answered[spec.name] = spec.default;
+    }
+    return { ...answered, ...collected };
+}
 /** The short form and the long one, as one shape. */
 function asChoice(choice) {
     return typeof choice === 'string' ? { value: choice } : choice;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@textui/widgets",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "The TextUI component catalog - layout, display, controls, data, overlays and charts",
   "keywords": [
     "terminal",
@@ -46,7 +46,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@textui/core": "^0.5.0"
+    "@textui/core": "^0.6.1"
   },
   "publishConfig": {
     "access": "public"

package/src/overlay/command-palette.ts

@@ -89,6 +89,15 @@ export interface CommandPaletteProps extends BoxProps {
  * That is where sub-items come from - the command says what it needs and the
  * palette asks, rather than every caller inventing its own submenu.
  */
+
+/** The question being asked: the command, the argument, and the answers given before it. */
+interface Pending {
+  command: CommandDefinition;
+  arg: ArgSpec;
+  /** Answers given so far, for a command that asks for more than one. */
+  collected: Record<string, unknown>;
+}
+
 export const CommandPalette = defineComponent<CommandPaletteProps>('CommandPalette', (props) => {
   const theme = useTheme();
   const runtime = useRuntime();
@@ -101,12 +110,7 @@ export const CommandPalette = defineComponent<CommandPaletteProps>('CommandPalet
   const [query, setQuery] = useState('');
   const [highlight, setHighlight] = useState(0);
   /** The command being asked about, when the palette has drilled in. */
-  const [pending, setPending] = useState<{
-    command: CommandDefinition;
-    arg: ArgSpec;
-    /** Answers given so far, for a command that asks for more than one. */
-    collected: Record<string, unknown>;
-  } | null>(null);
+  const [pending, setPending] = useState<Pending | null>(null);
   const [choices, setChoices] = useState<ArgChoice[]>([]);
   /**
    * Whether the answer to "what may I choose" is still on its way.
@@ -186,10 +190,30 @@ export const CommandPalette = defineComponent<CommandPaletteProps>('CommandPalet
           : {}),
       }));
 
+  /** The argument answered last, when this question came after one. */
+  const previousOf = (asked: Pending): ArgSpec | undefined => {
+    const last = Object.keys(asked.collected).at(-1);
+    return last === undefined ? undefined : (asked.command.args ?? []).find((arg) => arg.name === last);
+  };
+
+  /**
+   * One question back.
+   *
+   * After a first question the second is asked again from the start with
+   * the earlier answer withdrawn: a wrong provider is corrected by choosing
+   * another, not by closing the whole picker and opening it again. At the
+   * first question, the command list.
+   */
   const back = (): void => {
     // `null` is "never mind": whatever the preview did gets undone by whoever
     // did it, because only the command knows what it changed.
     pending?.arg.preview?.(null);
+    const previous = pending ? previousOf(pending) : undefined;
+    if (pending && previous) {
+      const { [previous.name]: _withdrawn, ...rest } = pending.collected;
+      drillInto(pending.command, previous, rest);
+      return;
+    }
     setPending(null);
     setChoices([]);
     setQuery('');
@@ -233,13 +257,20 @@ export const CommandPalette = defineComponent<CommandPaletteProps>('CommandPalet
     onRun?.(id, args);
   };
 
-  /** Ask about one command. `choices` may be a function, and may be async. */
+  /**
+   * Ask about one command. `choices` may be a function, and may be async.
+   *
+   * A resolver is handed what was answered before this argument - and an
+   * argument that was not asked because its `default` stood was answered by
+   * that default. Left out, "the models of the chosen provider" would see no
+   * provider exactly when there was only one to choose from.
+   */
   const drillInto = (
     command: CommandDefinition,
     arg: ArgSpec,
     collected: Record<string, unknown> = {},
   ): void => {
-    const resolved = typeof arg.choices === 'function' ? arg.choices() : arg.choices ?? [];
+    const resolved = typeof arg.choices === 'function' ? arg.choices(answeredBefore(command, arg, collected)) : arg.choices ?? [];
     setPending({ command, arg, collected });
     setQuery('');
 
@@ -350,8 +381,10 @@ export const CommandPalette = defineComponent<CommandPaletteProps>('CommandPalet
         // anybody chose to be at: the caller drilled in on their behalf, and
         // the level underneath is a list of one. Backing out to it reads as
         // "escape did nothing", and the second escape - the one that would
-        // close it - is spent leaving a screen nobody asked to see.
-        if (pending && !openAt) { back(); return true; }
+        // close it - is spent leaving a screen nobody asked to see. A question
+        // that came after one is different: there the level underneath is the
+        // earlier question, which somebody did choose to be at.
+        if (pending && (!openAt || previousOf(pending) !== undefined)) { back(); return true; }
         // Whatever a highlighted choice previewed has to be put back on the
         // way out, and `null` is how the command is told to undo it - only it
         // knows what it changed. `back()` did that, so closing instead of
@@ -361,7 +394,7 @@ export const CommandPalette = defineComponent<CommandPaletteProps>('CommandPalet
         onClose?.();
         return true;
       }
-      if (event.name === 'left' && pending && query === '' && !openAt) { back(); return true; }
+      if (event.name === 'left' && pending && query === '' && (!openAt || previousOf(pending) !== undefined)) { back(); return true; }
       // Wrapping, both ways. A list you can walk off the end of makes you
       // check where you are before every press; one that comes round means the
       // last item is one key from the first.
@@ -389,6 +422,8 @@ export const CommandPalette = defineComponent<CommandPaletteProps>('CommandPalet
   // there - and a sentence about what a mode does is exactly the thing a
   // person needs whole. So the line under the list follows the highlight: the
   // choice's description while there is one, the question's otherwise.
+  // It is the one line in the panel that wraps rather than truncates,
+  // because it is the one place a sentence can be read whole.
   const chosen = pending ? offered[index] : undefined;
   const detail = pending
     ? chosen?.description
@@ -411,6 +446,13 @@ export const CommandPalette = defineComponent<CommandPaletteProps>('CommandPalet
   const content = Math.max(
     ...items.map((item) => rowWidth(item, descriptions)),
     ...(pending ? [stringWidth(pending.command.title) + 12] : [stringWidth(placeholder ?? '') + 4]),
+    // The sentences the line under the list may show, so a question with
+    // three one-word answers is not a panel 28 wide wrapping a sentence
+    // three times under them. Capped like everything else by `maxWidth`.
+    ...(pending
+      ? [pending.arg.description ?? '', ...offered.map((choice) => choice.description ?? '')]
+        .map((sentence) => (sentence === '' ? 0 : stringWidth(sentence) + 6))
+      : []),
   );
 
   return h('box', {
@@ -457,10 +499,19 @@ export const CommandPalette = defineComponent<CommandPaletteProps>('CommandPalet
         const command = matches[index];
         if (command && argumentOf(command)) choose();
       },
+      // A typed answer's field is the answer, so its placeholder is the
+      // question. A list's field is a filter, and the question goes where
+      // there is room to say it once: here, while the line under the list
+      // is busy saying what each answer means; under the list, whole and
+      // wrapped, when the answers have nothing to say for themselves and
+      // that line would otherwise repeat this one, cut to whatever width
+      // three short answers gave the panel.
       placeholder: pending
-        ? (pending.arg.description ?? (pending.arg.choices === undefined
-          ? `${pending.command.title}${theme.glyphs.ellipsis}`
-          : `Choose ${pending.command.title.toLowerCase()}${theme.glyphs.ellipsis}`))
+        ? (pending.arg.choices === undefined
+          ? pending.arg.description ?? `${pending.command.title}${theme.glyphs.ellipsis}`
+          : offered.some((choice) => choice.description) && pending.arg.description
+            ? pending.arg.description
+            : `Choose ${pending.command.title.toLowerCase()}${theme.glyphs.ellipsis}`)
         : (placeholder ?? `Type a command${theme.glyphs.ellipsis}`),
       search: true,
       autoFocus: true,
@@ -484,8 +535,8 @@ export const CommandPalette = defineComponent<CommandPaletteProps>('CommandPalet
     h('box', { height: 1, fill: theme.borderChars().top, fg: 'borderSubtle' }),
     // What the highlighted row actually is, and how to move around. A palette
     // that shows only titles makes you run something to find out what it does.
-    h('box', { direction: 'row', gap: 1 },
-      h('text', { content: detail, fg: 'muted', flex: 1, truncate: 'end' }),
+    h('box', { direction: 'row', gap: 1, align: 'start' },
+      h('text', { content: detail, fg: 'muted', flex: 1, wrap: 'word' }),
       h('text', { content: `${rows.length}`, fg: 'subtle' })),
     h('box', { direction: 'row', gap: 1 },
       h('text', {
@@ -528,6 +579,26 @@ export function argumentOf(
   );
 }
 
+/**
+ * What a `choices` resolver is told: the answers given, under the defaults
+ * of the arguments before this one that stood in for a question.
+ *
+ * Only the ones ahead of it in the declaration. An argument after this one
+ * has not been reached, and its default is not yet an answer to anything.
+ */
+function answeredBefore(
+  command: CommandDefinition,
+  arg: ArgSpec,
+  collected: Record<string, unknown>,
+): Record<string, unknown> {
+  const answered: Record<string, unknown> = {};
+  for (const spec of command.args ?? []) {
+    if (spec === arg) break;
+    if (spec.default !== undefined) answered[spec.name] = spec.default;
+  }
+  return { ...answered, ...collected };
+}
+
 /** The short form and the long one, as one shape. */
 function asChoice(choice: string | ArgChoice): ArgChoice {
   return typeof choice === 'string' ? { value: choice } : choice;