@textui/widgets 0.1.0 → 0.2.0

package/src/display/color-text.ts

@@ -0,0 +1,386 @@
+import type {
+  CellStyle, Color, InteractionState, PaintSurface,
+  RenderContext, StyleColor, TextProps, TextWrap,
+} from '@textui/core';
+import {
+  attrsFromStyle, defineComponent, flattenStyleInput, graphemeWidth, graphemes, h,
+  mergeStyles, mix, packColor, resolveColor, sanitize, stringWidth, styleFromProps,
+  truncate, truncateSideOf, unpackColor, useMeasure, wrapModeOf, wrapText,
+} from '@textui/core';
+
+/**
+ * One cell, as the ink sees it.
+ *
+ * Both a column and an index, because they are not the same number and which
+ * one is wanted depends on the question. `col` is where the cell lands - a
+ * wide character advances it by two - so a gradient stays vertical over CJK
+ * and emoji. `index` counts graphemes, which is what "the fourth letter"
+ * means. Colouring by `index` and painting at `col` is the bug this pair
+ * exists to prevent.
+ */
+export interface InkCell {
+  /** The grapheme cluster about to be painted. */
+  char: string;
+  /** Column within the line, in cells. */
+  col: number;
+  /** Line index, after wrapping. */
+  line: number;
+  /** Grapheme index within the line. */
+  index: number;
+  /** Grapheme index within the whole block. */
+  offset: number;
+  /** Cells in this line. */
+  width: number;
+  /** Lines in the block. */
+  height: number;
+  /** Cells in the widest line of the block. */
+  blockWidth: number;
+}
+
+/**
+ * An ink written as code. Returns a colour, a whole cell style, or nothing.
+ *
+ * Nothing means "leave this cell to the component's own style", which is what
+ * makes an ink that colours one thing - the vowels, the column under the
+ * cursor - a two-line function rather than an exhaustive one.
+ */
+export type InkFn = (cell: InkCell, ctx: RenderContext) => StyleColor | CellStyle | undefined;
+
+/** A ramp between colour stops. */
+export interface GradientInk {
+  /** Two or more stops. One stop is a flat colour, none is nothing. */
+  gradient: StyleColor[];
+  /** Across, down, or corner to corner. */
+  axis?: 'x' | 'y' | 'xy';
+  /**
+   * What the ramp is measured against.
+   *
+   * `block` is the widest line, so every line of a banner shares one ramp and
+   * the colours line up down the block. `line` restarts the ramp on each line,
+   * which is what a paragraph of ragged lines wants - under `block` a short
+   * line would stop halfway through the ramp and look unfinished.
+   */
+  per?: 'block' | 'line';
+}
+
+/**
+ * What advances the colour.
+ *
+ * `cell` counts columns, so bands stay vertical across the lines of a block -
+ * the reason it is the default. `grapheme` counts every cluster including
+ * spaces, `letter` counts only the ones that print, and `word` and `line`
+ * are what they say.
+ */
+export type InkUnit = 'cell' | 'grapheme' | 'letter' | 'word' | 'line';
+
+/** A palette walked in order and repeated. */
+export interface CycleInk {
+  cycle: StyleColor[];
+  /**
+   * How much of the text each colour takes.
+   *
+   * A number is a fixed run. An array is a repeating pattern of runs, so
+   * `[4, 3]` gives four cells of the first colour, three of the second, four
+   * of the third, and keeps going in fours and threes.
+   */
+  every?: number | number[];
+  unit?: InkUnit;
+  /**
+   * Whether the count carries across a line break. Off by default: a run that
+   * restarts on every line keeps the bands of a block aligned, and a run that
+   * carries over puts them on a diagonal.
+   */
+  continuous?: boolean;
+}
+
+/**
+ * How a `ColorText` is coloured.
+ *
+ * An array is the short spelling of one colour per line. The two object forms
+ * are data, so a screen written as JSON can carry them; the function form
+ * cannot be serialized and is the escape hatch - the same trade `canvas`
+ * makes with `draw`.
+ */
+export type Ink = StyleColor[] | GradientInk | CycleInk | InkFn;
+
+/**
+ * Everything a `text` takes, plus the ink.
+ *
+ * The same props on purpose: `wrap`, `truncate`, `textAlign` and the style
+ * keys all mean here what they mean there, so swapping one for the other is a
+ * change of colour and nothing else.
+ */
+export interface ColorTextProps extends TextProps {
+  /** Left unset, this is an ordinary block of text. */
+  ink?: Ink;
+  /**
+   * Align the block as one thing, rather than each line on its own.
+   *
+   * `textAlign` centres every line over its own middle, which is right for
+   * prose and shears a picture: five rows of block letters do not have equal
+   * widths once the trailing spaces are gone, so each row lands somewhere
+   * slightly different and the letters lean. Under this, the whole block is
+   * placed once and the lines keep their offsets from each other.
+   *
+   * Off by default, because that is what `text` does and the two are supposed
+   * to mean the same thing by the same prop.
+   */
+  alignBlock?: boolean;
+}
+
+/**
+ * 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<ColorTextProps>('ColorText', (props) => {
+  const { content, children, ink, ellipsis, alignBlock, ...rest } = props;
+  const source = sanitize(textOf(content, children));
+  const wrap = (props.wrap ?? 'none') as TextWrap;
+
+  // 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: PaintSurface, ctx: RenderContext): void => {
+    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 as Record<string, unknown>),
+      flattenStyleInput(props.style, stateOf(ctx)),
+    );
+    const rest: CellStyle = {
+      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] as string;
+      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: Color[], t: number): Color {
+  if (stops.length === 0) return 'default';
+  if (stops.length === 1) return stops[0] as Color;
+  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] as Color, stops[i + 1] as Color, at - i);
+}
+
+/** Two colours mixed. `t` of 0 is `a`, 1 is `b`. Tokens must be resolved first. */
+export function blend(a: Color, b: Color, t: number): Color {
+  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: Ink | undefined,
+  ctx: RenderContext,
+): (cell: InkCell) => CellStyle | undefined {
+  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] as Color };
+  };
+}
+
+/** Which run of a repeating pattern a count falls in. `[4, 3]` over 8 gives 2. */
+function runIndex(n: number, runs: number[]): number {
+  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] as number)) { rest -= runs[i] as number; i++; }
+  return cycles * runs.length + i;
+}
+
+/** A colour, a style, or nothing - as a style, with its tokens resolved. */
+function styleOf(
+  value: StyleColor | CellStyle | undefined,
+  ctx: RenderContext,
+): CellStyle | undefined {
+  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 as Color };
+  const style = value as CellStyle;
+  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: unknown, children: unknown): string {
+  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: 'left' | 'center' | 'right', area: number, width: number): number {
+  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: string, wrap: TextWrap, width: number): string[] {
+  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: RenderContext): InteractionState {
+  return {
+    focused: ctx.focused, hovered: ctx.hovered, active: ctx.active,
+    selected: ctx.selected, disabled: ctx.disabled,
+  };
+}

package/src/display/index.ts

@@ -2,6 +2,7 @@ import type { ComponentDefinition } from '@textui/core';
 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';
@@ -25,6 +26,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';
@@ -47,6 +49,7 @@ export const DISPLAY_COMPONENTS: ComponentDefinition[] = [
   { 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/src/layout/divider.ts

@@ -1,4 +1,4 @@
-import type { BoxProps } from '@textui/core';
+import type { BoxProps, DividerStyle } from '@textui/core';
 import { defineComponent, h, useTheme } from '@textui/core';
 
 export interface DividerProps extends Omit<BoxProps, 'direction'> {
@@ -7,25 +7,33 @@ export interface DividerProps extends Omit<BoxProps, 'direction'> {
   /** 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 const Divider = defineComponent<DividerProps>('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,
+    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 ?? chars.top, fg: 'border' }) : null,
+    labelAlign !== 'right' ? h('box', { flex: 1, fill: char ?? rule.horizontal, fg }) : null,
   );
 });

package/src/layout/scroll-view.ts

@@ -27,6 +27,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;
 }
 
 /**
@@ -38,10 +48,10 @@ export interface ScrollViewProps extends BoxProps {
  */
 export const ScrollView = defineComponent<ScrollViewProps>('ScrollView', (props) => {
   const {
-    offset, onScroll, scrollbar = true, focusable = true, autoFocus, id,
+    offset, onScroll, scrollbar = true, focusable = true, autoFocus, focusId, id,
     children, ...rest
   } = props;
-  const focus = useFocus({ disabled: !focusable, autoFocus });
+  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/src/navigation/menu.ts

@@ -1,5 +1,5 @@
 import type { BoxProps, SemanticVariant } from '@textui/core';
-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';
 
@@ -13,6 +13,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
@@ -29,6 +41,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
@@ -40,7 +64,8 @@ export interface MenuProps extends BoxProps {
 export const Menu = defineComponent<MenuProps>('Menu', (props) => {
   const theme = useTheme();
   const {
-    items, onSelect, visibleRows, activeId, autoFocus, interactive = true, ...rest
+    items, onSelect, visibleRows, activeId, autoFocus, interactive = true,
+    descriptions = 'inline', ...rest
   } = props;
   const focus = useFocus({ autoFocus, disabled: !interactive });
   const selectable = items.filter((i) => !i.disabled);
@@ -82,17 +107,9 @@ export const Menu = defineComponent<MenuProps>('Menu', (props) => {
   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); },
-      },
+      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 })
@@ -108,7 +125,7 @@ export const Menu = defineComponent<MenuProps>('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,
@@ -123,6 +140,49 @@ export const Menu = defineComponent<MenuProps>('Menu', (props) => {
         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 as string,
+              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];
@@ -132,3 +192,18 @@ export const Menu = defineComponent<MenuProps>('Menu', (props) => {
       : 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: MenuItem, switches: boolean): number {
+  // The marker, plus the gap after it.
+  let width = 2;
+  if (switches) width += 2;
+  if (item.icon) width += stringWidth(item.icon) + 1;
+  return width;
+}