@textui/widgets 0.1.0 → 0.2.0

package/dist/display/color-text.js

@@ -0,0 +1,246 @@
+import { attrsFromStyle, defineComponent, flattenStyleInput, graphemeWidth, graphemes, h, mergeStyles, mix, packColor, resolveColor, sanitize, stringWidth, styleFromProps, truncate, truncateSideOf, unpackColor, useMeasure, wrapModeOf, wrapText, } from '@textui/core';
+/**
+ * Multiline text coloured cell by cell.
+ *
+ * A `text` takes one colour for the whole run, which is the right answer for
+ * nearly everything and no answer at all for the cases where the colour *is*
+ * the content - a banner, a ramp across a title, a palette walked down a
+ * block of ascii art. This is that case, and only that case: it is still just
+ * text, and the alternative to it is a `text` node.
+ *
+ * It paints on a `canvas`, and the price of the escape hatch is that inherited
+ * colour stops here. A cell the ink declines takes this component's own `fg`
+ * rather than the one a parent row would have handed a `text`, so a
+ * `ColorText` inside something that recolours its children when selected has
+ * to be told about it. Everything an ink does paint is unaffected.
+ *
+ * ```tsx
+ * <ColorText ink={{ gradient: ['cyan', 'magenta'] }}>{banner}</ColorText>
+ * <ColorText ink={['danger', 'warning', 'success']}>{lines}</ColorText>
+ * <ColorText ink={{ cycle: palette, every: [4, 3] }}>{title}</ColorText>
+ * <ColorText ink={(cell) => (cell.line === cell.col ? 'accent' : undefined)}>{grid}</ColorText>
+ * ```
+ *
+ * The colour is decoration and never the message: a 16-colour session flattens
+ * a three-stop ramp into a couple of bands, and a piped log loses all of it.
+ */
+export const ColorText = defineComponent('ColorText', (props) => {
+    const { content, children, ink, ellipsis, alignBlock, ...rest } = props;
+    const source = sanitize(textOf(content, children));
+    const wrap = (props.wrap ?? 'none');
+    // The width layout settled on last frame, for the height this frame asks
+    // for. Painting uses the surface's own width instead - that one is current -
+    // so the lag here costs a line count and never a wrong line break.
+    const measured = useMeasure().width;
+    const natural = source.split('\n').reduce((w, line) => Math.max(w, stringWidth(line)), 0);
+    const height = linesOf(source, wrap, measured > 0 ? measured : natural).length;
+    // A block that does not wrap is as wide as its widest line and says so -
+    // that is what a banner is. One that wraps or truncates asks for nothing and
+    // takes what it is given, because a paragraph that reported the width of its
+    // unbroken text would push every sibling off the row to get it.
+    const width = wrap === 'none' ? natural : 0;
+    const draw = (surface, ctx) => {
+        const { width: area, height: rows } = surface.rect;
+        if (area <= 0 || rows <= 0 || source === '')
+            return;
+        // The component's own style, resolved for the state it is in. Not the
+        // inherited one - a canvas is not told what it was nested in.
+        const own = mergeStyles(styleFromProps(props), flattenStyleInput(props.style, stateOf(ctx)));
+        const rest = {
+            fg: resolveColor(own.fg, ctx.theme, 'default'),
+            attrs: attrsFromStyle(own),
+            link: typeof props.link === 'string' ? props.link : undefined,
+        };
+        const cut = props.truncate ?? truncateSideOf(wrap) ?? 'end';
+        const dots = ellipsis ?? ctx.theme.glyphs.ellipsis;
+        const lines = linesOf(source, wrap, area).map((line) => (stringWidth(line) > area && cut !== false ? truncate(line, area, dots, cut) : line));
+        // After truncating, not before: the width the block is placed by is the
+        // width it is going to occupy.
+        const blockWidth = lines.reduce((w, line) => Math.max(w, stringWidth(line)), 0);
+        const paint = painterOf(ink, ctx);
+        const align = own.textAlign ?? 'left';
+        const origin = alignBlock ? indentFor(align, area, blockWidth) : undefined;
+        let offset = 0;
+        for (let y = 0; y < lines.length && y < rows; y++) {
+            const line = lines[y];
+            const lineWidth = stringWidth(line);
+            const indent = origin ?? indentFor(align, area, lineWidth);
+            let col = 0;
+            let index = 0;
+            for (const char of graphemes(line)) {
+                const advance = graphemeWidth(char);
+                if (advance === 0)
+                    continue;
+                const style = paint({
+                    char, col, line: y, index, offset, width: lineWidth, height: lines.length, blockWidth,
+                });
+                // A space with nothing but a foreground has nothing to show, and
+                // painting it would wipe out whatever the box behind it drew there.
+                if (char !== ' ' || style?.bg !== undefined || rest.bg !== undefined) {
+                    surface.put(indent + col, y, char, style ? { ...rest, ...style } : rest);
+                }
+                col += advance;
+                index++;
+                offset++;
+            }
+        }
+    };
+    return h('canvas', { draw, intrinsic: { width, height }, ...rest });
+});
+// ------------------------------------------------------------------- inks
+/**
+ * A colour a fraction of the way along a set of stops.
+ *
+ * Exported because an ink written by hand wants it and the alternative is
+ * unpacking colours in application code. `t` outside 0..1 is clamped rather
+ * than extrapolated - a ramp has ends.
+ */
+export function gradientAt(stops, t) {
+    if (stops.length === 0)
+        return 'default';
+    if (stops.length === 1)
+        return stops[0];
+    const at = Math.min(1, Math.max(0, t)) * (stops.length - 1);
+    const i = Math.min(stops.length - 2, Math.floor(at));
+    return blend(stops[i], stops[i + 1], at - i);
+}
+/** Two colours mixed. `t` of 0 is `a`, 1 is `b`. Tokens must be resolved first. */
+export function blend(a, b, t) {
+    return unpackColor(mix(packColor(a), packColor(b), Math.min(1, Math.max(0, t))));
+}
+/**
+ * An ink in any of its spellings, as the one function paint uses.
+ *
+ * Exported so a component that paints its own cells - a chart, a viewer with a
+ * heat column - can take an `Ink` and mean the same thing by it.
+ */
+export function painterOf(ink, ctx) {
+    if (ink === undefined)
+        return () => undefined;
+    if (typeof ink === 'function') {
+        return (cell) => styleOf(ink(cell, ctx), ctx);
+    }
+    if (Array.isArray(ink)) {
+        return painterOf({ cycle: ink, unit: 'line' }, ctx);
+    }
+    if ('gradient' in ink) {
+        const stops = ink.gradient.map((c) => resolveColor(c, ctx.theme, 'default'));
+        const axis = ink.axis ?? 'x';
+        const per = ink.per ?? 'block';
+        return (cell) => {
+            const span = per === 'line' ? cell.width : cell.blockWidth;
+            // A single column or a single line has no distance to ramp over, and
+            // dividing by zero would put every cell at the far end of the ramp.
+            const x = span > 1 ? cell.col / (span - 1) : 0;
+            const y = cell.height > 1 ? cell.line / (cell.height - 1) : 0;
+            const t = axis === 'x' ? x : axis === 'y' ? y : (x + y) / 2;
+            return { fg: gradientAt(stops, t) };
+        };
+    }
+    const colors = ink.cycle.map((c) => resolveColor(c, ctx.theme, 'default'));
+    if (colors.length === 0)
+        return () => undefined;
+    const unit = ink.unit ?? 'cell';
+    const runs = (Array.isArray(ink.every) ? ink.every : [ink.every ?? 1])
+        .map((n) => Math.max(1, Math.floor(n)));
+    const continuous = ink.continuous ?? false;
+    // `letter` and `word` are counted rather than derived, because both depend
+    // on what came before them on the line and neither can be recovered from a
+    // column number. Kept per line so the run restarts where the line does.
+    let letters = 0;
+    let words = 0;
+    let wasBlank = true;
+    let at = -1;
+    return (cell) => {
+        if (cell.line !== at) {
+            at = cell.line;
+            if (!continuous) {
+                letters = 0;
+                words = 0;
+            }
+            wasBlank = true;
+        }
+        const blank = cell.char.trim() === '';
+        if (!blank && wasBlank)
+            words++;
+        if (!blank)
+            letters++;
+        wasBlank = blank;
+        const n = unit === 'cell' ? (continuous ? cell.offset : cell.col)
+            : unit === 'grapheme' ? (continuous ? cell.offset : cell.index)
+                : unit === 'letter' ? Math.max(0, letters - 1)
+                    : unit === 'word' ? Math.max(0, words - 1)
+                        : cell.line;
+        return { fg: colors[runIndex(n, runs) % colors.length] };
+    };
+}
+/** Which run of a repeating pattern a count falls in. `[4, 3]` over 8 gives 2. */
+function runIndex(n, runs) {
+    const total = runs.reduce((a, b) => a + b, 0);
+    const cycles = Math.floor(n / total);
+    let rest = n % total;
+    let i = 0;
+    while (rest >= runs[i]) {
+        rest -= runs[i];
+        i++;
+    }
+    return cycles * runs.length + i;
+}
+/** A colour, a style, or nothing - as a style, with its tokens resolved. */
+function styleOf(value, ctx) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'string')
+        return { fg: resolveColor(value, ctx.theme, 'default') };
+    if ('rgb' in value || 'palette' in value)
+        return { fg: value };
+    const style = value;
+    return {
+        ...style,
+        fg: style.fg === undefined ? undefined : resolveColor(style.fg, ctx.theme, 'default'),
+        bg: style.bg === undefined ? undefined : resolveColor(style.bg, ctx.theme, 'default'),
+    };
+}
+// ------------------------------------------------------------------ text
+function textOf(content, children) {
+    if (typeof content === 'string')
+        return content;
+    if (typeof content === 'number')
+        return String(content);
+    if (typeof children === 'string')
+        return children;
+    if (typeof children === 'number')
+        return String(children);
+    if (Array.isArray(children)) {
+        return children.filter((c) => typeof c === 'string' || typeof c === 'number').join('');
+    }
+    return '';
+}
+/** Where a line of `width` starts, in a box of `area`. */
+function indentFor(align, area, width) {
+    if (align === 'center')
+        return Math.max(0, Math.floor((area - width) / 2));
+    if (align === 'right')
+        return Math.max(0, area - width);
+    return 0;
+}
+/** The same line-breaking `text` does, so the two agree about where a line ends. */
+function linesOf(text, wrap, width) {
+    if (text === '')
+        return [];
+    // The truncating modes are one line by definition; a newline inside one has
+    // nowhere to go, so it becomes a space rather than silently taking the rest
+    // of the text with it.
+    if (truncateSideOf(wrap) !== undefined)
+        return [text.replace(/\n/g, ' ')];
+    const mode = wrapModeOf(wrap);
+    if (mode === 'none' || width <= 0)
+        return text.split('\n');
+    return wrapText(text, width, mode);
+}
+function stateOf(ctx) {
+    return {
+        focused: ctx.focused, hovered: ctx.hovered, active: ctx.active,
+        selected: ctx.selected, disabled: ctx.disabled,
+    };
+}

package/dist/display/index.d.ts

@@ -10,6 +10,7 @@ import type { ComponentDefinition } from '@textui/core';
 export * from './alert.js';
 export * from './badge.js';
 export * from './card.js';
+export * from './color-text.js';
 export * from './empty-state.js';
 export * from './error-state.js';
 export * from './heading.js';

package/dist/display/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/display/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAgBxD;;;;;;;GAOG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAE9B,eAAO,MAAM,kBAAkB,EAAE,mBAAmB,EAenD,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/display/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAiBxD;;;;;;;GAOG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAE9B,eAAO,MAAM,kBAAkB,EAAE,mBAAmB,EAgBnD,CAAC"}

package/dist/display/index.js

@@ -1,6 +1,7 @@
 import { Alert } from './alert.js';
 import { Badge } from './badge.js';
 import { Card } from './card.js';
+import { ColorText } from './color-text.js';
 import { EmptyState } from './empty-state.js';
 import { ErrorState } from './error-state.js';
 import { Heading } from './heading.js';
@@ -23,6 +24,7 @@ import { Timeline } from './timeline.js';
 export * from './alert.js';
 export * from './badge.js';
 export * from './card.js';
+export * from './color-text.js';
 export * from './empty-state.js';
 export * from './error-state.js';
 export * from './heading.js';
@@ -44,6 +46,7 @@ export const DISPLAY_COMPONENTS = [
     { component: 'KeyValue', category: 'data', renderer: { kind: 'function', render: KeyValue }, description: 'Aligned label/value pairs.' },
     { component: 'Progress', category: 'feedback', renderer: { kind: 'function', render: Progress }, role: 'progressbar', description: 'Determinate or indeterminate bar, sub-cell resolution.' },
     { component: 'Spinner', category: 'feedback', renderer: { kind: 'function', render: Spinner }, role: 'status', description: 'Animated activity indicator.' },
+    { component: 'ColorText', category: 'display', renderer: { kind: 'function', render: ColorText }, description: 'Multiline text coloured cell by cell - a ramp, a palette per line, or a function.' },
     { component: 'Marquee', category: 'display', renderer: { kind: 'function', render: Marquee }, role: 'marquee', description: 'Text too long for its box, read by sliding it while it has the cursor.' },
     { component: 'Skeleton', category: 'feedback', renderer: { kind: 'function', render: Skeleton }, description: 'Loading placeholder.' },
     { component: 'EmptyState', category: 'feedback', renderer: { kind: 'function', render: EmptyState }, description: 'Nothing here, and what to do about it.' },

package/dist/layout/divider.d.ts

@@ -1,10 +1,15 @@
-import type { BoxProps } from '@textui/core';
+import type { BoxProps, DividerStyle } from '@textui/core';
 export interface DividerProps extends Omit<BoxProps, 'direction'> {
     /** A divider runs across the flow, so it names its own axis. */
     direction?: 'horizontal' | 'vertical';
     /** Text set into the rule. */
     label?: string;
     labelAlign?: 'left' | 'center' | 'right';
+    /**
+     * The rule style. The theme's own is the default, so a borderless theme
+     * still gets the line it asked for.
+     */
+    rule?: DividerStyle;
     char?: string;
 }
 export declare const Divider: (props: DividerProps) => import("@textui/core").RenderOutput;

package/dist/layout/divider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"divider.d.ts","sourceRoot":"","sources":["../../src/layout/divider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAG7C,MAAM,WAAW,YAAa,SAAQ,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/D,gEAAgE;IAChE,SAAS,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;IACtC,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,OAAO,8DAkBlB,CAAC"}
+{"version":3,"file":"divider.d.ts","sourceRoot":"","sources":["../../src/layout/divider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG3D,MAAM,WAAW,YAAa,SAAQ,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/D,gEAAgE;IAChE,SAAS,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;IACtC,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IACzC;;;OAGG;IACH,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,OAAO,8DAqBlB,CAAC"}

package/dist/layout/divider.js

@@ -1,13 +1,13 @@
 import { defineComponent, h, useTheme } from '@textui/core';
 export const Divider = defineComponent('Divider', (props) => {
     const theme = useTheme();
-    const { direction = 'horizontal', label, labelAlign = 'left', char, ...rest } = props;
-    const chars = theme.borderChars();
+    const { direction = 'horizontal', label, labelAlign = 'left', char, rule: ruleStyle, fg = 'divider', ...rest } = props;
+    const rule = theme.dividerChars(ruleStyle);
     if (direction === 'vertical') {
-        return h('box', { role: 'separator', width: 1, fill: char ?? chars.left, fg: 'border', ...rest });
+        return h('box', { role: 'separator', width: 1, fill: char ?? rule.vertical, fg, ...rest });
     }
     if (!label) {
-        return h('box', { role: 'separator', height: 1, fill: char ?? chars.top, fg: 'border', ...rest });
+        return h('box', { role: 'separator', height: 1, fill: char ?? rule.horizontal, fg, ...rest });
     }
-    return h('box', { direction: 'row', gap: 1, height: 1, ...rest }, labelAlign !== 'left' ? h('box', { flex: 1, fill: char ?? chars.top, fg: 'border' }) : null, h('text', { content: label, fg: 'muted' }), labelAlign !== 'right' ? h('box', { flex: 1, fill: char ?? chars.top, fg: 'border' }) : null);
+    return h('box', { direction: 'row', gap: 1, height: 1, ...rest }, labelAlign !== 'left' ? h('box', { flex: 1, fill: char ?? rule.horizontal, fg }) : null, h('text', { content: label, fg: 'muted' }), labelAlign !== 'right' ? h('box', { flex: 1, fill: char ?? rule.horizontal, fg }) : null);
 });

package/dist/layout/scroll-view.d.ts

@@ -15,6 +15,16 @@ export interface ScrollViewProps extends BoxProps {
      */
     focusable?: boolean;
     autoFocus?: boolean;
+    /**
+     * A stable focus id, so a command - or the screen that owns this - can put
+     * the reader here by name.
+     *
+     * Without one the id comes from the instance, which nothing outside the
+     * render can know: "scroll the preview" has nothing to name and the key that
+     * would do it cannot be written. Every other focusable control takes one;
+     * this was the exception, and there was no reason for it.
+     */
+    focusId?: string;
 }
 /**
  * A scrolling viewport.

package/dist/layout/scroll-view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scroll-view.d.ts","sourceRoot":"","sources":["../../src/layout/scroll-view.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAa7C,MAAM,WAAW,eAAgB,SAAQ,QAAQ;IAC/C,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,iEA4ErB,CAAC"}
+{"version":3,"file":"scroll-view.d.ts","sourceRoot":"","sources":["../../src/layout/scroll-view.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAa7C,MAAM,WAAW,eAAgB,SAAQ,QAAQ;IAC/C,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,iEA4ErB,CAAC"}

package/dist/layout/scroll-view.js

@@ -8,8 +8,8 @@ import { ScrollThumb } from '../data/scroll-thumb.js';
  * rounds.
  */
 export const ScrollView = defineComponent('ScrollView', (props) => {
-    const { offset, onScroll, scrollbar = true, focusable = true, autoFocus, id, children, ...rest } = props;
-    const focus = useFocus({ disabled: !focusable, autoFocus });
+    const { offset, onScroll, scrollbar = true, focusable = true, autoFocus, focusId, id, children, ...rest } = props;
+    const focus = useFocus({ ...(focusId ? { id: focusId } : {}), disabled: !focusable, autoFocus });
     const [internal, setInternal] = useState(0);
     const top = offset ?? internal;
     // How far down this can go before the last line leaves the bottom. Written

package/dist/navigation/menu.d.ts

@@ -9,6 +9,18 @@ export interface MenuItem {
     disabled?: boolean;
     tone?: SemanticVariant;
     separatorBefore?: boolean;
+    /**
+     * A heading on the line above this row, naming the group it starts.
+     *
+     * The name of a group belongs to the group, so it is said once at the top
+     * of it rather than repeated on every row - a column reading "Screens,
+     * Screens, Screens" spends the width that the rows themselves need, and
+     * still does not say where one group ends.
+     *
+     * It takes the line a `separatorBefore` would have used rather than adding
+     * one, so a grouped menu is the same height either way.
+     */
+    sectionBefore?: string;
     /**
      * A switch, and whether it is on. Absent means the row is not a switch, so
      * a menu of ordinary commands keeps its left edge rather than indenting
@@ -24,6 +36,18 @@ export interface MenuProps extends BoxProps {
     visibleRows?: number;
     activeId?: string;
     autoFocus?: boolean;
+    /**
+     * Where a row's description goes.
+     *
+     * `inline` right-aligns it on the row, sharing the width with the label -
+     * which is the right shape for a word or two of state. `below` gives it a
+     * line of its own under the label, indented to it, which is the only shape
+     * that fits a sentence: inline, a list of modes whose whole difference is
+     * the sentence under each shows the same truncated half of every one.
+     *
+     * `below` makes every row two lines, so `visibleRows` buys half as much.
+     */
+    descriptions?: 'inline' | 'below';
     /**
      * Take focus and handle keys. Off when something else drives the selection -
      * a command palette, where typing belongs to the search field and the list

package/dist/navigation/menu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"menu.d.ts","sourceRoot":"","sources":["../../src/navigation/menu.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAK9D,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,SAAU,SAAQ,QAAQ;IACzC,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,QAAQ,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC5C,0BAA0B;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,eAAO,MAAM,IAAI,2DA8Ff,CAAC"}
+{"version":3,"file":"menu.d.ts","sourceRoot":"","sources":["../../src/navigation/menu.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAK9D,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,SAAU,SAAQ,QAAQ;IACzC,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,QAAQ,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC5C,0BAA0B;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAClC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,eAAO,MAAM,IAAI,2DAkIf,CAAC"}

package/dist/navigation/menu.js

@@ -1,9 +1,9 @@
-import { defineComponent, h, useFocus, useInput, useState, useTheme } from '@textui/core';
+import { defineComponent, h, stringWidth, useFocus, useInput, useState, useTheme } from '@textui/core';
 import { Marquee } from '../display/index.js';
 import { TONE } from '../tone.js';
 export const Menu = defineComponent('Menu', (props) => {
     const theme = useTheme();
-    const { items, onSelect, visibleRows, activeId, autoFocus, interactive = true, ...rest } = props;
+    const { items, onSelect, visibleRows, activeId, autoFocus, interactive = true, descriptions = 'inline', ...rest } = props;
     const focus = useFocus({ autoFocus, disabled: !interactive });
     const selectable = items.filter((i) => !i.disabled);
     const [internalHighlight, setHighlight] = useState(Math.max(0, items.findIndex((i) => i.id === activeId)));
@@ -43,18 +43,8 @@ export const Menu = defineComponent('Menu', (props) => {
     const switches = items.some((item) => item.checked !== undefined);
     return h('box', { id: focus.id, role: 'menu', direction: 'column', ...rest }, ...window.flatMap((item, i) => {
         const active = start + i === highlight;
-        const row = h('box', {
-            key: item.id,
-            role: 'menuitem',
-            label: item.label,
-            selected: active,
-            direction: 'row',
-            gap: 1,
-            bg: active ? 'selected' : undefined,
-            fg: item.disabled ? 'disabled' : active ? 'inverted' : item.tone ? TONE[item.tone] : undefined,
-            onClick: () => { if (!item.disabled)
-                onSelect?.(item.id, item); },
-        }, h('text', { content: active ? theme.glyphs.chevronRight : ' ', shrink: 0 }), switches
+        const below = descriptions === 'below' && item.description !== undefined;
+        const head = h('box', { direction: 'row', gap: 1 }, h('text', { content: active ? theme.glyphs.chevronRight : ' ', shrink: 0 }), switches
             ? h('text', { content: item.checked === true ? theme.glyphs.check : ' ', shrink: 0 })
             : null, 
         // The mark never gives up room. It is the shortest thing on the row
@@ -67,7 +57,7 @@ export const Menu = defineComponent('Menu', (props) => {
         // The description yields first, and by a lot. It is the elaboration;
         // the label is the thing being chosen, and a row reading "Accept ed…"
         // beside a full sentence has given up the wrong half.
-        item.description
+        item.description && !below
             ? h(Marquee, {
                 content: item.description,
                 active,
@@ -79,6 +69,43 @@ export const Menu = defineComponent('Menu', (props) => {
         // which is what the command palette knows about an argument whose
         // choices it has not resolved yet.
         item.children ? h('text', { content: theme.glyphs.chevronRight }) : null);
+        const row = h('box', {
+            key: item.id,
+            role: 'menuitem',
+            label: item.label,
+            selected: active,
+            direction: 'column',
+            // One background over both lines: a highlight that stopped after the
+            // label would split the row it is highlighting in two.
+            bg: active ? 'selected' : undefined,
+            fg: item.disabled ? 'disabled' : active ? 'inverted' : item.tone ? TONE[item.tone] : undefined,
+            onClick: () => { if (!item.disabled)
+                onSelect?.(item.id, item); },
+        }, head, 
+        // Under the label rather than under the cursor: the sentence is about
+        // the thing being chosen, so it starts where that thing starts.
+        below
+            ? h('box', { direction: 'row' }, h('text', { content: ' '.repeat(leading(item, switches)), shrink: 0 }), 
+            // A `Marquee`, like the inline one: a sentence too long for the
+            // panel is still readable on the row the cursor is on, by sliding
+            // it. Truncated and still is right for the rows being scanned past
+            // and useless for the one that has been stopped on.
+            h(Marquee, {
+                content: item.description,
+                active,
+                fg: active ? 'inverted' : 'muted',
+                flex: 1,
+            }))
+            : null);
+        if (item.sectionBefore) {
+            return [
+                h('box', { key: `${item.id}-sec`, role: 'heading', direction: 'row', gap: 1 }, 
+                // The same leading columns the rows have, so a heading sits over
+                // the labels it names rather than over the cursor's gutter.
+                h('text', { content: ' ', shrink: 0 }), switches ? h('text', { content: ' ', shrink: 0 }) : null, h('text', { content: item.sectionBefore, bold: true, fg: 'muted', truncate: 'end' })),
+                row,
+            ];
+        }
         return item.separatorBefore
             ? [h('box', { key: `${item.id}-sep`, height: 1, fill: theme.borderChars().top, fg: 'borderSubtle' }), row]
             : [row];
@@ -86,3 +113,19 @@ export const Menu = defineComponent('Menu', (props) => {
         ? h('text', { content: '  no matches', fg: 'subtle' })
         : null);
 });
+/**
+ * The columns before a row's label, so a second line can start under it.
+ *
+ * The cursor's column and the switch's are the same on every row - that is
+ * what keeps a menu's left edge straight - but the icon is per-row and may be
+ * two cells wide, so it has to be measured rather than assumed.
+ */
+function leading(item, switches) {
+    // The marker, plus the gap after it.
+    let width = 2;
+    if (switches)
+        width += 2;
+    if (item.icon)
+        width += stringWidth(item.icon) + 1;
+    return width;
+}

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

@@ -14,10 +14,41 @@ export interface CommandPaletteProps extends BoxProps {
     onClose?(): void;
     /** Off makes this a picker: it reports the choice and runs nothing. */
     execute?: boolean;
-    /** Group the list by `category`, with a rule between groups. */
+    /**
+     * Group the list by `category`, with the category named above each group.
+     *
+     * Only while nothing is typed. A query sorts by relevance, which interleaves
+     * the categories - and a heading over one row is not a group.
+     */
     grouped?: boolean;
     visibleRows?: number;
+    /**
+     * A fixed width, in cells.
+     *
+     * Left off, the panel is as wide as its widest row and no wider than
+     * `maxWidth` - which is what a list of five short answers wants, and what a
+     * list of five sentences needs. A number here is a number: the panel is that
+     * wide whether the rows fill it or overflow it.
+     */
     width?: number;
+    /**
+     * The widest the panel may grow when `width` is left off. 60 by default.
+     *
+     * There is always a limit: a description is prose, and prose has no width it
+     * stops at. Past this the rows truncate, and the row under the cursor slides
+     * what it truncated.
+     */
+    maxWidth?: number;
+    /**
+     * Where a row's description goes. `inline` right-aligns it beside the label;
+     * `below` gives it a line of its own.
+     *
+     * `below` for a question whose answers differ by a sentence rather than by a
+     * word - four approval modes named in two words each are told apart by the
+     * line under them, and inline that line is the half that gets truncated.
+     * Every row costs two lines, so `visibleRows` buys half as many.
+     */
+    descriptions?: 'inline' | 'below';
     /**
      * Open already drilled into this command's choices.
      *

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;AAgB/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,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,qEA0VzB,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;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,qEAsZzB,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"}