@textui/widgets 0.1.0 → 0.3.0

package/src/data/feed.ts

@@ -33,6 +33,20 @@ export interface FeedProps extends BoxProps {
   onSelect?(index: number): void;
   onActivate?(index: number): void;
   scrollbar?: boolean;
+  /**
+   * Who `pageup` and `pagedown` belong to.
+   *
+   * `focused` is the ordinary answer: the keys go to whatever has the
+   * keyboard. `always` claims them even while something else does - for the
+   * feed that *is* the screen, with a text field under it. Somebody typing a
+   * message who presses page up means the conversation above them; there is
+   * nothing else on that screen those keys could be for, and taking the
+   * keyboard away from the field to use them is the thing they are avoiding.
+   *
+   * Only those two keys, and only when the focused node has declined them
+   * first - so a field that pages its own content keeps them.
+   */
+  pageKeys?: 'focused' | 'always';
   focusable?: boolean;
   autoFocus?: boolean;
   /** So a command can send the reader here by name. */
@@ -59,6 +73,7 @@ export interface FeedProps extends BoxProps {
 export const Feed = defineComponent<FeedProps>('Feed', (props) => {
   const {
     children, follow: followProp, onFollowChange, selectedIndex, onSelect, onActivate,
+    pageKeys = 'focused',
     scrollbar = true, focusable = true, autoFocus, focusId, id, ...rest
   } = props;
 
@@ -70,6 +85,20 @@ export const Feed = defineComponent<FeedProps>('Feed', (props) => {
   const measured = useMeasure();
   const extent = useScrollExtent();
   const heights = useRef<number[]>([]);
+  /**
+   * The width those heights were measured at.
+   *
+   * A height is a statement about a width - what a paragraph wrapped to in a
+   * pane this wide - so a resize does not make them stale, it makes them
+   * about a layout that no longer exists. Kept and compared rather than
+   * ignored, because the alternative is a feed that scrolls to the wrong
+   * place for ever after the window is dragged.
+   */
+  const heightsAt = useRef(-1);
+  /** One handler for every entry, so an entry's props do not change with it. */
+  const report = useRef((index: number, height: number): void => {
+    heights.current[index] = height;
+  });
 
   // The catalog's rule, and this has to follow it like every other viewport:
   // given `flex`, a `height`, a `maxHeight` or a `basis`, the layout decided
@@ -86,7 +115,17 @@ export const Feed = defineComponent<FeedProps>('Feed', (props) => {
   const [internalTop, setInternalTop] = useState<number | null>(null);
   const [internalIndex, setInternalIndex] = useState(0);
 
-  const entries = (Array.isArray(children) ? children : [children]).filter((c) => c != null);
+  /*
+   * Flattened, because a feed counts entries and JSX groups them.
+   *
+   * `{caption}{items.map(...)}` arrives as `[caption, [a, b, c]]` - two
+   * children, one of which is an array - so a feed of twenty entries with
+   * anything written beside the map counted two. The cursor then clamped to
+   * the second, every key after the first did nothing, and the scroll never
+   * moved. It reads as a dead list and is an arity bug.
+   */
+  const entries = (Array.isArray(children) ? children.flat(Infinity) : [children])
+    .filter((c) => c != null);
   const count = entries.length;
   const selects = onSelect !== undefined || selectedIndex !== undefined;
   const index = Math.max(0, Math.min(count - 1, selectedIndex ?? internalIndex));
@@ -166,10 +205,70 @@ export const Feed = defineComponent<FeedProps>('Feed', (props) => {
     { focusId: focus.id, enabled: focusable },
   );
 
+  /*
+   * The page keys, from wherever the keyboard happens to be.
+   *
+   * `global` handlers run only after the focused node has declined the key,
+   * so a field that pages its own content still keeps them - this is the one
+   * that catches what nothing else wanted.
+   */
+  useInput(
+    (event) => {
+      if (event.name !== 'pageup' && event.name !== 'pagedown') return false;
+      if (chorded(event)) return false;
+      const page = Math.max(1, measured.height - 2);
+      scrollTo(event.name === 'pageup' ? top - page : top + page);
+      return true;
+    },
+    { global: true, enabled: pageKeys === 'always' },
+  );
+
+  if (measured.width !== heightsAt.current) {
+    heightsAt.current = measured.width;
+    heights.current = [];
+  }
+
+  /*
+   * Which entries are far enough away not to be worth drawing.
+   *
+   * A feed lays out every entry it holds, and laying one out means wrapping
+   * its text - so a viewport thirty rows tall over a transcript of six
+   * hundred entries spent every frame measuring the five hundred and seventy
+   * nobody can see. That cost is paid per *frame*, not per change: a
+   * keystroke in a field elsewhere on the screen, a caret blinking, a
+   * spinner. It is why a long conversation is heavy to type into and a short
+   * one is not.
+   *
+   * An entry is skipped only once it has been measured, which is what keeps
+   * this honest: the first frame draws everything and learns every height,
+   * and from then on the ones outside the window are replaced by a box of
+   * exactly the height they had. Nothing is estimated, so the extent, the
+   * scrollbar and the position of every entry are what they would have been
+   * had all of them been drawn.
+   *
+   * A screenful either side, so scrolling and paging land on something that
+   * is already there rather than on a frame of blanks.
+   */
+  const view = Math.max(1, measured.height);
+  const skipped: boolean[] = [];
+  {
+    let y = 0;
+    for (let i = 0; i < count; i++) {
+      const height = heights.current[i];
+      // Zero is not a height that has been learned, whatever wrote it: an
+      // entry standing in for itself at nothing tall is one that can never
+      // be drawn again to find out how tall it is.
+      if (height === undefined || height <= 0) { skipped[i] = false; continue; }
+      skipped[i] = fills && (y + height < top - view || y > top + view + view);
+      y += height;
+    }
+  }
   const drawn = entries.map((entry, i) => h(FeedEntry, {
     key: i,
-    onHeight: (height: number) => { heights.current[i] = height; },
-  }, entry));
+    index: i,
+    onHeight: report.current,
+    ...(skipped[i] ? { placeholder: true, height: heights.current[i] as number } : {}),
+  }, skipped[i] ? null : entry));
 
   // Content-sized: draw everything and let the box grow. Clamping to a
   // measurement here would clamp to how tall this happened to be last frame,

package/src/data/list.ts

@@ -1,4 +1,4 @@
-import type { BoxProps, SemanticVariant } from '@textui/core';
+import type { BoxProps, RenderOutput, SemanticVariant } from '@textui/core';
 import {
   chorded,
   defineComponent,
@@ -24,15 +24,39 @@ export interface ListItem {
   disabled?: boolean;
 }
 
-export interface ListProps extends BoxProps {
-  items: ListItem[];
+/** How a row stands at the moment it is asked to draw itself. */
+export interface ListItemState {
+  /** The row the selection is on. */
+  selected: boolean;
+  /**
+   * ...and the list itself has the keyboard.
+   *
+   * Both, and not one: a selected row in a list that has lost focus is a
+   * *remembered* choice, and drawing it as loudly as a live one makes two
+   * panes look like they both have the cursor.
+   */
+  focused: boolean;
+  disabled: boolean;
+}
+
+export interface ListProps<T extends ListItem = ListItem> extends BoxProps {
+  /**
+   * The rows.
+   *
+   * `T` is whatever the caller's own row type is, so long as it is a
+   * `ListItem` - which is what the built-in row needs and what `id` being the
+   * selection's name needs. Passing plain `ListItem`s is the ordinary case and
+   * `T` costs nothing there; a caller with a `renderItem` gets its own fields
+   * back on the way in rather than a lookup by id.
+   */
+  items: T[];
   selectedId?: string;
-  onSelect?(id: string, item: ListItem): void;
-  onActivate?(id: string, item: ListItem): void;
+  onSelect?(id: string, item: T): void;
+  onActivate?(id: string, item: T): void;
   /** Rows visible at once. Scrolls when there are more. */
   visibleRows?: number;
   emptyMessage?: string;
-  /** Draw a marker column for the selected row. */
+  /** Draw a marker column for the selected row. Drawn either way. */
   marker?: boolean;
   focusable?: boolean;
   autoFocus?: boolean;
@@ -42,14 +66,42 @@ export interface ListProps extends BoxProps {
    * nothing outside the render can know.
    */
   focusId?: string;
+  /**
+   * Draw one row's contents.
+   *
+   * The built-in row - icon, title, description, meta, on one line - is the
+   * shape most catalogues are, and it is what you get by leaving this alone.
+   * The moment a caller wants a different one, the repair is *not* another
+   * field on `ListItem` and another flag saying where to put it: that road
+   * ends with a component whose props are a small layout language, and it
+   * still cannot draw the row after next.
+   *
+   * So the row is the caller's, and everything a row cannot do for itself
+   * stays here: the selection, the keys that move it, the window that scrolls,
+   * the highlight, the marker column and the click. `state` is what the row
+   * cannot know - whether it is the selected one, and whether that selection
+   * is live.
+   *
+   * A row taller than one line has to say so with `itemHeight`.
+   */
+  renderItem?(item: T, state: ListItemState): RenderOutput;
+  /**
+   * Lines one row occupies, when `renderItem` draws more than one.
+   *
+   * The list scrolls by arithmetic rather than by measurement - it decides how
+   * many rows fit *before* anything is drawn, which is the only way a thousand
+   * rows cost the same as ten. That arithmetic is in lines, so a row that is
+   * two of them has to be declared, not discovered.
+   */
+  itemHeight?: number;
 }
 
-export const List = defineComponent<ListProps>('List', (props) => {
+function ListView<T extends ListItem>(props: ListProps<T>): RenderOutput {
   const theme = useTheme();
   const {
     items, selectedId, onSelect, onActivate, visibleRows,
     emptyMessage = 'Nothing here', marker = true, focusable = true,
-    autoFocus, focusId, ...rest
+    autoFocus, focusId, renderItem, itemHeight = 1, ...rest
   } = props;
 
   const focus = useFocus({
@@ -62,7 +114,20 @@ export const List = defineComponent<ListProps>('List', (props) => {
     items.find((i) => !i.disabled)?.id ?? null,
   );
   const currentId = selectedId ?? internalId;
-  const pageSize = viewportRows(props, measured, 10, { requested: visibleRows });
+
+  /**
+   * How many *rows* fit, when what was measured is lines.
+   *
+   * `visibleRows` is already a count of rows, so it stands as given. Anything
+   * else comes from the space the list was handed, and a two-line row buys
+   * half as many of them.
+   */
+  const lines = Math.max(1, itemHeight);
+  const fit = (content: number): number => {
+    if (visibleRows !== undefined) return Math.max(1, visibleRows);
+    return Math.max(1, Math.floor(viewportRows(props, measured, content * lines) / lines));
+  };
+  const pageSize = fit(10);
   const index = Math.max(0, items.findIndex((i) => i.id === currentId));
 
   /**
@@ -112,13 +177,22 @@ export const List = defineComponent<ListProps>('List', (props) => {
   // Unstated, the row count comes from the space the list was given rather
   // than from how many items it holds - a thousand-row list must not decide
   // how tall its own pane is.
-  const rows = viewportRows(props, measured, items.length, { requested: visibleRows });
+  const rows = fit(items.length);
   const start = Math.max(0, Math.min(index - Math.floor(rows / 2), items.length - rows));
   const window = items.slice(start, start + rows);
 
   return h('box', { id: focus.id, role: 'list', direction: 'column', ...rest },
     ...window.map((item) => {
       const active = item.id === currentId;
+      const state: ListItemState = {
+        selected: active,
+        focused: focus.focused,
+        disabled: item.disabled === true,
+      };
+      // `item.id` is the key as well as the selection's name, and deliberately
+      // the same string: a row that reconciled under one identity while the
+      // selection pointed at another would be a highlight on the wrong row,
+      // and no amount of looking at either one would show why.
       return h('box', {
         key: item.id,
         role: 'listitem',
@@ -126,6 +200,9 @@ export const List = defineComponent<ListProps>('List', (props) => {
         selected: active,
         direction: 'row',
         gap: 1,
+        // One background over the whole row, however many lines it draws: a
+        // highlight that stopped after the first would split the row it is
+        // highlighting in two.
         bg: active && focus.focused ? 'selected' : active ? 'active' : undefined,
         fg: item.disabled ? 'disabled' : active && focus.focused ? 'inverted' : undefined,
         onClick: () => {
@@ -134,16 +211,46 @@ export const List = defineComponent<ListProps>('List', (props) => {
           onSelect?.(item.id, item);
         },
       },
+        // The marker stays here even when the contents are the caller's. It
+        // belongs to the selection rather than to the row, and a column that
+        // every row has to remember to draw is a column that goes crooked.
         marker
-          ? h('text', { content: active ? theme.glyphs.chevronRight : ' ' })
+          ? h('text', { content: active ? theme.glyphs.chevronRight : ' ', shrink: 0 })
           : null,
-        item.icon ? h('text', { content: item.icon, fg: item.tone ? TONE[item.tone] : undefined }) : null,
-        h('text', { content: item.label, flex: 1, truncate: 'end' }),
-        // The secondary columns keep the row's colour once it is selected;
-        // `muted` on a selected background is unreadable.
-        item.description ? h('text', { content: item.description, fg: active ? undefined : 'muted', truncate: 'end' }) : null,
-        item.meta ? h('text', { content: item.meta, fg: active ? undefined : 'muted' }) : null,
+        ...(renderItem
+          ? [h('box', { direction: 'column', flex: 1 }, renderItem(item, state))]
+          : defaultRow(item, active)),
       );
     }),
   );
-});
+}
+
+export const List = defineComponent('List', ListView as (props: ListProps) => RenderOutput) as typeof ListView;
+
+/**
+ * The row you get for free: an icon, a title, an elaboration, a state.
+ *
+ * One line, because a list of a thousand of them has to cost what a list of
+ * ten does, and because most catalogues are exactly this. Anything else is
+ * `renderItem`.
+ */
+function defaultRow(item: ListItem, active: boolean): RenderOutput[] {
+  return [
+    item.icon ? h('text', { content: item.icon, fg: item.tone ? TONE[item.tone] : undefined }) : null,
+    h('text', { content: item.label, flex: 1, truncate: 'end' }),
+    // The secondary columns keep the row's colour once it is selected;
+    // `muted` on a selected background is unreadable.
+    //
+    // The description yields first, and by a lot: it is the elaboration,
+    // and a row reading "brb_fram…" beside a status cut to "waiting on y…"
+    // has spent the width on the wrong two things. `meta` gives up none of
+    // it - a status is three words at most, and it is the column the row
+    // is being scanned for.
+    item.description
+      ? h('text', { content: item.description, fg: active ? undefined : 'muted', truncate: 'end', shrink: 8 })
+      : null,
+    item.meta
+      ? h('text', { content: item.meta, fg: active ? undefined : 'muted', shrink: 0 })
+      : null,
+  ] as RenderOutput[];
+}

package/src/data/markdown-view.ts

@@ -51,6 +51,9 @@ export const MarkdownView = defineComponent<MarkdownViewProps>('MarkdownView', (
       bullet: theme.glyphs.bulletFilled,
       quoteBar: theme.borderChars().left,
       ruled,
+      // How many rules a table gets is the theme's, but *where* they go is a
+      // question about rows, so it is answered in the layout rather than here.
+      tableRules: theme.tableRules,
     }),
     [given, content, width, theme, ruled],
   );
@@ -120,6 +123,59 @@ export const MarkdownView = defineComponent<MarkdownViewProps>('MarkdownView', (
       continue;
     }
 
+    if (row.kind === 'table') {
+      /*
+       * A table is ruled even where nothing else is.
+       *
+       * `theme.border` being `none` is a theme saying "do not box things" -
+       * panels, fences, dialogs. It is not saying "do not tell these columns
+       * apart": the rules in a table are its structure, not its decoration,
+       * and without them it is text that happens to line up, with nothing to
+       * say where it ended. So a borderless theme still gets a table, drawn
+       * in the plainest set there is.
+       *
+       * Asked for by name rather than taken from `borderChars()`, which is
+       * the same request routed through the terminal's own limits: on a
+       * console that cannot draw box characters this comes back as `+`, `-`
+       * and `|` rather than as something it would print as a row of boxes.
+       */
+      const chars = theme.borderChars(theme.border === 'none' ? 'single' : theme.border);
+      const fg = 'borderSubtle';
+
+      if (row.part !== 'head' && row.part !== 'body') {
+        const [left, joint, right] =
+          row.part === 'top' ? [chars.topLeft, chars.teeTop, chars.topRight]
+            : row.part === 'bottom' ? [chars.bottomLeft, chars.teeBottom, chars.bottomRight]
+              : [chars.teeRight, chars.cross, chars.teeLeft];
+        const bar = row.part === 'bottom' ? chars.bottom : chars.top;
+        // Every column plus the space either side of it, which is what the
+        // cell rows spend - an edge measured off the cells alone is an edge
+        // two cells short per column.
+        out.push(h('text', {
+          key,
+          content: left
+            + row.widths.map((w) => repeatToWidth(bar, w + 2)).join(joint)
+            + right,
+          fg,
+          wrap: 'none',
+        }));
+        i++;
+        continue;
+      }
+
+      // The cells arrive padded to their column, so nothing here measures
+      // anything: a row is its cells with a rule between each pair.
+      out.push(h('box', { key, direction: 'row', overflow: 'hidden' },
+        ...row.cells.flatMap((cell, c) => [
+          h('text', { key: `s${c}`, content: c === 0 ? `${chars.left} ` : ` ${chars.left} `, fg, wrap: 'none' }),
+          h('box', { key: `c${c}`, direction: 'row', overflow: 'hidden' },
+            ...runNodes(cell, quiet ? { fg: 'muted' as StyleColor } : {})),
+        ]),
+        h('text', { key: 'end', content: ` ${chars.right}`, fg, wrap: 'none' })));
+      i++;
+      continue;
+    }
+
     if (row.kind === 'rule') {
       out.push(h('box', { key, height: 1, fill: theme.borderChars().top, fg: 'borderSubtle' }));
       i++;

package/src/data/shared.ts

@@ -6,13 +6,35 @@ import { defineComponent, h, useEffect, useMeasure, useTheme } from '@textui/cor
  *
  * Through a ref rather than state, deliberately: a height arriving must not
  * schedule a render, or every measurement would cause the next measurement.
+ *
+ * It reports its `index` to one shared handler rather than taking a closure
+ * that already knows it. A closure per entry is a new prop on every entry
+ * every time the feed itself re-renders, and a changed prop is a re-render -
+ * so a feed that redrew for its own reasons dragged every entry it holds
+ * along with it, however little any of them had changed.
  */
-export const FeedEntry = defineComponent<BoxProps & { onHeight(height: number): void }>(
+export const FeedEntry = defineComponent<BoxProps & {
+  index: number;
+  /**
+   * Standing in for an entry that is not drawn, at the height it had.
+   *
+   * A stand-in must not answer the question it is an answer to. Its height is
+   * one the feed already knows - it is where it came from - and reporting it
+   * back is how a measurement gets to depend on itself: a round where a
+   * stand-in came out any shorter would teach the feed that it *was* shorter,
+   * and the next round would place the rest of them on top of each other.
+   */
+  placeholder?: boolean;
+  onHeight(index: number, height: number): void;
+}>(
   'FeedEntry',
   (props) => {
-    const { onHeight, children, ...rest } = props;
+    const { index, placeholder, onHeight, children, ...rest } = props;
     const measured = useMeasure();
-    useEffect(() => { onHeight(measured.height); }, [measured.height]);
+    useEffect(() => {
+      if (placeholder) return;
+      onHeight(index, measured.height);
+    }, [measured.height, placeholder]);
     return h('box', { direction: 'column', ...rest }, children);
   },
 );