@textui/widgets 0.1.0

package/src/data/code-viewer.ts

@@ -0,0 +1,337 @@
+import type { BoxProps, RenderOutput, ResolvedTheme, SyntaxToken } from '@textui/core';
+import {
+  chorded,
+  defineComponent,
+  expandTabs,
+  h,
+  nameOf,
+  sliceColumns,
+  stringWidth,
+  useEffect,
+  useFocus,
+  useHighlight,
+  useInput,
+  useMeasure,
+  useMemo,
+  useTheme,
+} from '@textui/core';
+import type { LineMark } from '../decorations.js';
+import { MARK_GLYPH, MARK_TONE, useLineMarks } from '../decorations.js';
+import { usePanelState, usePanelStatus } from '../panel/index.js';
+import { viewportRows } from '../viewport.js';
+import { ScrollThumb } from './scroll-thumb.js';
+
+export interface CodeViewerProps extends BoxProps {
+  content: string;
+  /** Show line numbers in a gutter. */
+  lineNumbers?: boolean;
+  startLine?: number;
+  /**
+   * Fix the number of rows. Left off, the viewer renders exactly as many rows
+   * as it was laid out into - which is what stops a long file from resizing
+   * the pane it is shown in.
+   */
+  visibleRows?: number;
+  /** Rows to mark, 1-based. */
+  highlight?: number[];
+  /** Pre-tokenised content, when the caller has already highlighted it. */
+  tokens?: SyntaxToken[][];
+  /** Ask the registry for a highlighter by id... */
+  language?: string;
+  /** ...or by resource kind... */
+  kind?: string;
+  /** ...or by filename. */
+  uri?: string;
+  /** Caret line, 1-based. Controlled when passed. */
+  line?: number;
+  onLineChange?(line: number): void;
+  /** Called whenever the caret or the viewport moves. */
+  onPosition?(position: CodeViewerPosition): void;
+  /** Draw a scrollbar when the content is taller than the view. */
+  scrollbar?: boolean;
+  /** Mark the caret line. Off for a plain excerpt. */
+  showCaret?: boolean;
+  tabWidth?: number;
+  /**
+   * Take the keyboard on mount.
+   *
+   * Wanted by a viewer that is the only thing in a dialog: a modal traps focus
+   * but does not hand it to anything, so a scrollable body nobody focused is a
+   * body nobody can scroll.
+   */
+  autoFocus?: boolean;
+}
+
+export interface CodeViewerPosition {
+  /** Caret line, 1-based. */
+  line: number;
+  /** Leftmost visible column, 0-based. */
+  column: number;
+  /** First visible line, 1-based. */
+  top: number;
+  rows: number;
+  lines: number;
+  /** Longest line, in cells. */
+  width: number;
+}
+
+/**
+ * How far one press of `left` or `right` pans a viewer that cannot fit its
+ * widest line. Exported because every viewer that scrolls sideways has to
+ * agree - a diff that panned by one column beside a code view that panned by
+ * four would be two different keys wearing the same arrow.
+ */
+export const HORIZONTAL_STEP = 4;
+
+/**
+ * A file viewer.
+ *
+ * Two things make this different from a column of `text` nodes. It renders
+ * only the rows it was given room for, so opening a ten-thousand-line file
+ * costs the same as opening a ten-line one and neither of them moves the panes
+ * around it. And it colours by asking the registry for a highlighter, so a new
+ * file type arrives coloured without this component learning what it is.
+ */
+export const CodeViewer = defineComponent<CodeViewerProps>('CodeViewer', (props) => {
+  const {
+    content, lineNumbers = true, startLine = 1, visibleRows, highlight = [],
+    tokens, language, kind, uri, line, onLineChange, onPosition,
+    scrollbar = true, showCaret = true, tabWidth = 4, disabled, autoFocus, ...rest
+  } = props;
+
+  const theme = useTheme();
+  const focus = useFocus({ disabled, ...(autoFocus ? { autoFocus } : {}) });
+  const measured = useMeasure();
+
+  const text = useMemo(() => expandTabs(content, tabWidth), [content, tabWidth]);
+  const lines = useMemo(() => text.split('\n'), [text]);
+  const auto = useHighlight(tokens ? '' : text, { language, kind, uri });
+  const lineTokens = tokens ?? auto;
+
+  /*
+   * Where this viewer is looking belongs to the panel, not to this component.
+   *
+   * Switching tabs and coming back, or swapping this viewer for an editor on
+   * the same file, both unmount it - and both are the moments a reader most
+   * expects to land where they left. `line`, `column`, `top` and `left` are
+   * the shared vocabulary for a renderer that measures in source lines, so an
+   * editor picks up the caret this viewer left behind. Outside a panel the
+   * hook is ordinary component state, which is what a viewer in a dialog gets.
+   */
+  const [view, setView] = usePanelState({ top: 0, left: 0, line: 0 });
+  const top = view.top;
+  const setTop = (next: number): void => setView({ top: next });
+  const left = view.left;
+  const setLeft = (next: number): void => setView({ left: next });
+  // The record counts from zero, like an index; this component's `line` prop
+  // counts from one, like a gutter. The conversion lives here, once.
+  const internalLine = view.line + 1;
+  const setInternalLine = (next: number): void => setView({ line: next - 1 });
+
+  const rows = viewportRows(props, measured, lines.length, { requested: visibleRows });
+
+  /*
+   * The same marks the editor draws, for the same reason.
+   *
+   * "This line changed" is true of the file, not of whether you happen to be
+   * editing it - and it lived only in the editor, so turning the setting on
+   * while reading did nothing at all and said nothing about why.
+   *
+   * The column costs a cell only when somebody has actually marked something,
+   * so a viewer nobody has decorated is the width it always was.
+   */
+  const marks = useLineMarks(uri ?? null);
+  const markWidth = Object.keys(marks).length > 0 ? 1 : 0;
+
+  const gutter = lineNumbers ? String(startLine + lines.length - 1).length : 0;
+  const bars = scrollbar && lines.length > rows ? 1 : 0;
+  const textWidth = Math.max(
+    1,
+    (measured.width > 0 ? measured.width : 80) - (lineNumbers ? gutter + 1 : 0) - markWidth - bars,
+  );
+
+  const longest = useMemo(
+    () => lines.reduce((max, l) => Math.max(max, stringWidth(l)), 0),
+    [lines],
+  );
+
+  const maxTop = Math.max(0, lines.length - rows);
+  const maxLeft = Math.max(0, longest - textWidth);
+  const caret = clampLine(line ?? internalLine, lines.length);
+
+  // The caret leads and the viewport follows, so arrowing past the last row
+  // scrolls rather than parking the caret out of sight.
+  const firstVisible = Math.min(
+    Math.max(0, Math.min(top, maxTop)),
+    Math.max(0, Math.min(caret - 1, maxTop)),
+  );
+  const offset = Math.max(firstVisible, Math.min(caret - rows, maxTop));
+  const leftColumn = Math.max(0, Math.min(left, maxLeft));
+
+  const moveTo = (next: number): void => {
+    const clamped = clampLine(next, lines.length);
+    if (line === undefined) setInternalLine(clamped);
+    onLineChange?.(clamped);
+    if (clamped - 1 < offset) setTop(clamped - 1);
+    else if (clamped > offset + rows) setTop(clamped - rows);
+  };
+
+  const scrollBy = (delta: number): void => {
+    const next = Math.max(0, Math.min(maxTop, offset + delta));
+    setTop(next);
+    // Keep the caret inside the view, the way a pager does.
+    const clamped = clampLine(Math.min(Math.max(caret, next + 1), next + rows), lines.length);
+    if (line === undefined) setInternalLine(clamped);
+    else onLineChange?.(clamped);
+  };
+
+  useInput(
+    (event) => {
+      if (disabled || chorded(event)) return false;
+      switch (event.name) {
+        case 'up': moveTo(caret - 1); return true;
+        case 'down': moveTo(caret + 1); return true;
+        case 'pageup': moveTo(caret - rows); return true;
+        case 'pagedown': moveTo(caret + rows); return true;
+        case 'home': moveTo(1); return true;
+        case 'end': moveTo(lines.length); return true;
+        case 'left': setLeft(Math.max(0, leftColumn - HORIZONTAL_STEP)); return true;
+        case 'right': setLeft(Math.min(maxLeft, leftColumn + HORIZONTAL_STEP)); return true;
+        default: return false;
+      }
+    },
+    { focusId: focus.id },
+  );
+
+  useEffect(() => {
+    onPosition?.({
+      line: caret,
+      column: leftColumn,
+      top: offset + 1,
+      rows,
+      lines: lines.length,
+      width: longest,
+    });
+  }, [caret, leftColumn, offset, rows, lines.length, longest]);
+
+  /*
+   * What this pane says about itself: which file it is showing.
+   *
+   * A viewer is not an editor and should not pretend to be one - `Ln 12,
+   * Col 4` is what the *editor* says, because a caret is a thing you put
+   * somewhere and a reader has not put one anywhere. The name is what a
+   * reader wants confirmed, particularly in a split where two panes are
+   * showing two files and only one of them is focused.
+   */
+  usePanelStatus(uri !== null && uri !== undefined ? nameOf(uri) : null);
+
+  const body: RenderOutput[] = [];
+  for (let i = 0; i < rows; i++) {
+    const index = offset + i;
+    if (index >= lines.length) break;
+
+    const number = startLine + index;
+    const marked = highlight.includes(number);
+    const onCaret = showCaret && focus.focused && number === caret + startLine - 1;
+
+    // No `gap` on this row: the gap would land between every token, not only
+    // between the gutter and the code, and space out the source by a cell per
+    // token. The gutter carries its own trailing space instead.
+    body.push(
+      h('box', {
+        key: number,
+        direction: 'row',
+        height: 1,
+        bg: marked ? 'active' : onCaret ? 'hover' : undefined,
+      },
+        lineNumbers
+          ? h('text', {
+              content: `${String(number).padStart(gutter)} `,
+              fg: onCaret || marked ? 'text' : 'subtle',
+              width: gutter + 1,
+            })
+          : null,
+        // Between the number and the code, which is where the editor puts it
+        // too - so swapping a viewer for an editor on the same file does not
+        // move the text sideways.
+        markWidth > 0
+          ? h('text', {
+              content: MARK_GLYPH[marks[index] as LineMark] ?? ' ',
+              fg: MARK_TONE[marks[index] as LineMark] ?? 'border',
+              width: 1,
+            })
+          : null,
+        ...spansFor(
+          lineTokens[index] ?? [{ text: lines[index] ?? '', scope: 'plain' }],
+          leftColumn,
+          textWidth,
+          theme,
+        ),
+      ),
+    );
+  }
+
+  return h('box', {
+    id: focus.id,
+    role: 'document',
+    direction: 'row',
+    onMouse: (event: { action: string; wheel?: number }) => {
+      if (event.action !== 'wheel') return false;
+      scrollBy((event.wheel ?? 0) * 3);
+      return true;
+    },
+    ...rest,
+  },
+    h('box', { direction: 'column', flex: 1 }, ...body),
+    bars
+      ? h(ScrollThumb, { total: lines.length, rows, offset, focused: focus.focused })
+      : null,
+  );
+});
+
+function clampLine(line: number, total: number): number {
+  return Math.max(1, Math.min(total === 0 ? 1 : total, Math.round(line)));
+}
+
+/**
+ * One `text` node per token, sliced to the visible columns.
+ *
+ * Slicing here rather than truncating in the layout is what keeps the viewer
+ * from claiming the width of its longest line - which is the horizontal half
+ * of the same bug that makes a pane resize when a file is opened.
+ */
+function spansFor(
+  tokens: SyntaxToken[],
+  left: number,
+  width: number,
+  theme: ResolvedTheme,
+): RenderOutput[] {
+  const out: RenderOutput[] = [];
+  let column = 0;
+  let drawn = 0;
+
+  for (let i = 0; i < tokens.length && drawn < width; i++) {
+    const token = tokens[i] as SyntaxToken;
+    const tokenWidth = stringWidth(token.text);
+    const end = column + tokenWidth;
+
+    if (end > left) {
+      const from = Math.max(0, left - column);
+      const slice = sliceColumns(token.text, from, width - drawn);
+      if (slice !== '') {
+        out.push(h('text', {
+          key: i,
+          content: slice,
+          fg: token.scope === 'plain' ? undefined : theme.syntax[token.scope],
+        }));
+        drawn += stringWidth(slice);
+      }
+    }
+    column = end;
+  }
+
+  // The row must still fill its width, or the caret background stops short of
+  // the right edge and the highlight looks ragged.
+  if (drawn < width) out.push(h('box', { flex: 1 }));
+  return out;
+}

package/src/data/feed.ts

@@ -0,0 +1,204 @@
+import type { BoxProps } from '@textui/core';
+import {
+  chorded,
+  defineComponent,
+  h,
+  useFocus,
+  useInput,
+  useMeasure,
+  useRef,
+  useScrollExtent,
+  useState,
+} from '@textui/core';
+import { sizedByLayout } from '../viewport.js';
+import { FeedEntry, FeedScrollbar } from './shared.js';
+
+// ---------------------------------------------------------------------- feed
+
+export interface FeedProps extends BoxProps {
+  /** The entries. Any height each - that is the whole point of this one. */
+  children?: unknown;
+  /**
+   * Stick to the newest entry. Turned off when the reader scrolls up, and back
+   * on at the bottom - a feed that yanks itself away is one you cannot read.
+   */
+  follow?: boolean;
+  onFollowChange?(follow: boolean): void;
+  /**
+   * The cursor, by index. Passed, the caller owns it; omitted, the arrows
+   * scroll by line instead, which is what a feed with nothing to activate
+   * wants.
+   */
+  selectedIndex?: number;
+  onSelect?(index: number): void;
+  onActivate?(index: number): void;
+  scrollbar?: boolean;
+  focusable?: boolean;
+  autoFocus?: boolean;
+  /** So a command can send the reader here by name. */
+  focusId?: string;
+}
+
+/**
+ * A viewport over entries of any height.
+ *
+ * The one between `List` and `ScrollView`, and it is not either of them:
+ * `List` is fixed-height rows with a selection, `ScrollView` is a dumb
+ * viewport, and a feed is entries whose height is whatever their text wrapped
+ * to, with a cursor that moves between them and a tail it follows.
+ *
+ * Heights are **measured, not computed**. What a paragraph wraps to is decided
+ * by the layout, so each entry reports its height after it is laid out and the
+ * feed scrolls by summing them. That is one frame behind, which is invisible,
+ * and it is the only answer that is not a guess.
+ *
+ * A transcript, an activity stream, search results with snippets, a diff whose
+ * files expand - all the same component, because all of them are "an ordered
+ * list of things that are not one line tall".
+ */
+export const Feed = defineComponent<FeedProps>('Feed', (props) => {
+  const {
+    children, follow: followProp, onFollowChange, selectedIndex, onSelect, onActivate,
+    scrollbar = true, focusable = true, autoFocus, focusId, id, ...rest
+  } = props;
+
+  const focus = useFocus({
+    ...(focusId ? { id: focusId } : {}),
+    disabled: !focusable,
+    ...(autoFocus ? { autoFocus } : {}),
+  });
+  const measured = useMeasure();
+  const extent = useScrollExtent();
+  const heights = useRef<number[]>([]);
+
+  // 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
+  // the size and the feed fills it and scrolls; given none of those, the
+  // content decides and it draws everything. Clamping to a measurement in the
+  // second case is clamping to how tall it happened to be last frame, which
+  // for a box that is sized *by* this content is nothing at all - the entries
+  // vanish and the panel is empty.
+  const fills = sizedByLayout(props) && measured.height > 0;
+
+  // Null is "at the tail", rather than a boolean beside a number: the two can
+  // disagree, and a follow flag that says yes while the offset says otherwise
+  // is how a log ends up frozen three lines from the bottom.
+  const [internalTop, setInternalTop] = useState<number | null>(null);
+  const [internalIndex, setInternalIndex] = useState(0);
+
+  const entries = (Array.isArray(children) ? children : [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));
+
+  const total = extent?.height ?? 0;
+  const limit = Math.max(0, total - measured.height);
+  const following = followProp ?? (internalTop === null);
+  const top = following ? limit : Math.min(internalTop ?? 0, limit);
+
+  const scrollTo = (next: number | null): void => {
+    if (next === null) {
+      setInternalTop(null);
+      onFollowChange?.(true);
+      return;
+    }
+    const clamped = Math.max(0, Math.min(next, limit));
+    setInternalTop(clamped);
+    // Scrolled back to the bottom is following again, without a second key.
+    onFollowChange?.(clamped >= limit);
+  };
+
+  /** Where an entry starts, from what the layout measured last frame. */
+  const startOf = (target: number): number => {
+    let y = 0;
+    for (let i = 0; i < target && i < heights.current.length; i++) y += (heights.current[i] ?? 1);
+    return y;
+  };
+
+  const reveal = (target: number): void => {
+    const start = startOf(target);
+    const height = heights.current[target] ?? 1;
+    const view = Math.max(1, measured.height);
+    if (start < top) scrollTo(start);
+    else if (start + height > top + view) scrollTo(start + height - view);
+    else scrollTo(top);
+  };
+
+  const move = (delta: number): void => {
+    if (count === 0) return;
+    const next = Math.max(0, Math.min(count - 1, index + delta));
+    if (selectedIndex === undefined) setInternalIndex(next);
+    onSelect?.(next);
+    reveal(next);
+  };
+
+  useInput(
+    (event) => {
+      const page = Math.max(1, measured.height - 2);
+      if (chorded(event)) return false;
+      switch (event.name) {
+        case 'up': case 'k':
+          if (selects) move(-1); else scrollTo(top - 1);
+          return true;
+        case 'down': case 'j':
+          if (selects) move(1); else scrollTo(top + 1);
+          return true;
+        case 'pageup': scrollTo(top - page); return true;
+        case 'pagedown': scrollTo(top + page); return true;
+        case 'home': case 'g':
+          scrollTo(0);
+          if (selects) { if (selectedIndex === undefined) setInternalIndex(0); onSelect?.(0); }
+          return true;
+        case 'end': case 'G':
+          scrollTo(null);
+          if (selects && count > 0) {
+            if (selectedIndex === undefined) setInternalIndex(count - 1);
+            onSelect?.(count - 1);
+          }
+          return true;
+        case 'f': scrollTo(following ? top : null); return true;
+        case 'enter': case 'space':
+          if (onActivate && count > 0) { onActivate(index); return true; }
+          return false;
+        default: return false;
+      }
+    },
+    { focusId: focus.id, enabled: focusable },
+  );
+
+  const drawn = entries.map((entry, i) => h(FeedEntry, {
+    key: i,
+    onHeight: (height: number) => { heights.current[i] = height; },
+  }, 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,
+  // which for a box sized *by* its own content is nothing at all - the entries
+  // vanish and the panel is empty.
+  if (!fills) {
+    return h('box', {
+      id: id ?? focus.id,
+      role: 'list',
+      ...rest,
+      direction: 'column',
+    }, ...drawn);
+  }
+
+  return h('box', {
+    id: id ?? focus.id,
+    role: 'list',
+    ...rest,
+    direction: 'row',
+    overflow: 'hidden',
+    onMouse: (event: { action: string; wheel?: number }) => {
+      if (event.action !== 'wheel') return false;
+      scrollTo(top + (event.wheel ?? 0) * 3);
+      return true;
+    },
+  },
+    h('box', { flex: 1, direction: 'column', scrollTop: top, overflow: 'scroll' }, ...drawn),
+    // Only when there is somewhere to scroll. A track down the side of a feed
+    // that fits is chrome that states something untrue.
+    scrollbar && limit > 0 ? h(FeedScrollbar, {}) : null,
+  );
+});