@tooee/view 0.10.3 → 0.12.0

package/src/components/subviews/markdown-subview.tsx

@@ -1,4 +1,5 @@
 import type { TextBufferRenderable } from "@opentui/core";
+import { useTerminalDimensions } from "@opentui/react";
 import { useBuildCommandContext, useCommand } from "@tooee/commands";
 import { MarkdownView, flattenMarkdown, getFlatBlockText } from "@tooee/renderers";
 import type { CodeBlockRenderer, FlatBlock } from "@tooee/renderers";
@@ -6,7 +7,11 @@ import type { DocumentRowAdapter } from "@tooee/shell";
 import { useMemo, useRef } from "react";
 import type { ReactNode } from "react";
 
+import { markdownHeadingFoldRanges } from "../../folds/markdown-heading-folds.js";
+import { useFoldActions, useFoldCommands, useFoldState } from "../../folds/use-folds.js";
 import { useContentDocument } from "../../hooks/use-content-document.js";
+import { OutlinePanel } from "../../outline/outline-panel.js";
+import { useMarkdownOutline } from "../../outline/use-outline.js";
 import type { MarkdownContent, MarkdownLinkActivateHandler } from "../../types.js";
 import { ViewScreen } from "../view-screen.js";
 import type { SubviewProps } from "./types.js";
@@ -15,6 +20,8 @@ interface MarkdownSubviewProps extends SubviewProps {
   content: MarkdownContent;
   codeBlockRenderers?: Record<string, CodeBlockRenderer>;
   onLinkActivate?: MarkdownLinkActivateHandler;
+  /** Open the heading outline beside the document at start. */
+  outline?: boolean;
 }
 
 /** Columns moved per h/l press when scrolling a wide block horizontally. */
@@ -23,17 +30,26 @@ const BLOCK_HSCROLL_STEP = 4;
 /**
  * Blocks are the row unit. `getFlatBlockText` keeps search/copy in step with the
  * source mapping (notably for synthetic bullet rows), and `getSource` projects
- * each block's Markdown provenance onto the controller's anchors.
+ * each block's Markdown provenance onto the controller's anchors. The key is
+ * the block's index in the full flattened document, so it stays the same when
+ * folds hide the blocks around it.
  */
-const MARKDOWN_BLOCK_ADAPTER: DocumentRowAdapter<FlatBlock> = {
-  getSource: (block) => block.source,
-  getText: (block) => getFlatBlockText(block),
+const markdownBlockAdapter = function markdownBlockAdapter(
+  blocks: readonly FlatBlock[]
+): DocumentRowAdapter<FlatBlock> {
+  const indices = new Map(blocks.map((block, index) => [block, index]));
+  return {
+    getKey: (block, index) => indices.get(block) ?? index,
+    getSource: (block) => block.source,
+    getText: (block) => getFlatBlockText(block),
+  };
 };
 
 export const MarkdownSubview = function MarkdownSubview({
   content,
   codeBlockRenderers,
   onLinkActivate,
+  outline: initialOutline = false,
   decorations,
   actions,
   ...screen
@@ -41,19 +57,37 @@ export const MarkdownSubview = function MarkdownSubview({
   const textContent = content.markdown;
   const lineCount = useMemo(() => textContent.split("\n").length, [textContent]);
   const blocks = useMemo(() => flattenMarkdown(content.markdown), [content.markdown]);
+  const adapter = useMemo(() => markdownBlockAdapter(blocks), [blocks]);
+  const foldRanges = useMemo(() => markdownHeadingFoldRanges(blocks), [blocks]);
+  // Closed heading folds filter `blocks`; `folds.rows` is the one array both
+  // the controller and the renderer see.
+  const folds = useFoldState(blocks, foldRanges, decorations);
 
   const { document, showLineNumbers, statusItems } = useContentDocument<FlatBlock>(
-    blocks,
-    MARKDOWN_BLOCK_ADAPTER,
-    { actions, content, decorations, textContent },
+    folds.rows,
+    adapter,
+    { actions, content, decorations: folds.decorations, textContent },
     {
       multiSelect: true,
+      preserveCursorByKey: true,
       statusItems: [
         { label: "Format:", value: content.format },
         { label: "Lines:", value: String(lineCount) },
       ],
     }
   );
+  const foldActions = useFoldActions(folds, document.navigation);
+  useFoldCommands(folds, foldActions, document.navigation);
+  // Declared after the controller, so its jump effect runs after the
+  // controller has taken the new rows.
+  const outline = useMarkdownOutline({
+    blocks,
+    folds,
+    initialOpen: initialOutline,
+    navigation: document.navigation,
+    revealRow: document.revealRow,
+  });
+  const { width: terminalWidth } = useTerminalDimensions();
   const buildCommandContext = useBuildCommandContext();
   const handleLinkActivate = onLinkActivate
     ? (href: string) => onLinkActivate(href, buildCommandContext())
@@ -97,17 +131,21 @@ export const MarkdownSubview = function MarkdownSubview({
       controller={document}
       actions={actions}
       statusItems={statusItems}
+      aside={<OutlinePanel outline={outline} foldActions={foldActions} />}
       {...screen}
     >
       <MarkdownView
         content={content.markdown}
-        blocks={blocks}
+        blocks={folds.rows}
+        rowNumbers={folds.rowNumbers}
+        foldedBlocks={folds.view.hiddenCounts}
         showLineNumbers={showLineNumbers}
         document={document}
         hScrollableBlocksRef={hScrollableBlocksRef}
         codeBlockRenderers={codeBlockRenderers}
         onLinkActivate={handleLinkActivate}
         imageBasePath={content.imageBasePath}
+        width={outline.visible ? terminalWidth - outline.width : undefined}
       />
     </ViewScreen>
   );

package/src/components/view-screen.tsx

@@ -21,6 +21,8 @@ export interface ViewScreenProps<T> {
   setMarkSet: (set: MarkSet) => void;
   clearMarkNamespace: (namespace: string) => void;
   clearAllUserMarks: () => void;
+  /** Optional side region beside the content, such as the Markdown outline. */
+  aside?: ReactNode;
   children: ReactNode;
 }
 
@@ -41,6 +43,7 @@ export const ViewScreen = function ViewScreen<T>({
   setMarkSet,
   clearMarkNamespace,
   clearAllUserMarks,
+  aside,
   children,
 }: ViewScreenProps<T>): ReactNode {
   useProvideViewCommandContext({
@@ -71,6 +74,7 @@ export const ViewScreen = function ViewScreen<T>({
       statusItems={items}
       actions={actions}
       context={{ kind: content.format, reload, title: content.title }}
+      aside={aside}
     >
       {children}
     </DocumentScreen>

package/src/folds/fold-decorations.ts

@@ -0,0 +1,30 @@
+import type { DecorationLayer, RowDecoration } from "@tooee/renderers";
+
+import type { FoldView } from "./fold-model.js";
+
+/**
+ * Map decoration layers written against full-array rows onto the visible rows
+ * of `view`. Decorations on rows that a closed fold hides are dropped.
+ */
+export const projectDecorationLayers = function projectDecorationLayers(
+  layers: readonly DecorationLayer[],
+  view: FoldView
+): DecorationLayer[] {
+  const { visibleToSource, sourceToVisible } = view;
+  return layers.map((layer): DecorationLayer => ({
+    *forVisibleRows(from: number, to: number): Generator<RowDecoration> {
+      const sourceFrom = visibleToSource[from];
+      const sourceTo = visibleToSource[Math.min(to, visibleToSource.length - 1)];
+      if (sourceFrom === undefined || sourceTo === undefined) {
+        return;
+      }
+      for (const decoration of layer.forVisibleRows(sourceFrom, sourceTo)) {
+        const row = sourceToVisible[decoration.row] ?? -1;
+        if (row !== -1) {
+          yield { ...decoration, row };
+        }
+      }
+    },
+    priority: layer.priority,
+  }));
+};

package/src/folds/fold-model.ts

@@ -0,0 +1,99 @@
+import type { Key } from "react";
+
+/**
+ * A foldable range of rows. `start` is the header row that stays visible;
+ * `start + 1 ..= end` are the rows a closed fold hides. Indices point into the
+ * full row array, and `key` is the header row's key, so closed state survives
+ * row changes that keep keys stable.
+ */
+export interface FoldRange {
+  key: Key;
+  start: number;
+  end: number;
+}
+
+/** The visible projection of a full row array under a set of closed folds. */
+export interface FoldView {
+  /** Full-array index of each visible row, in order. */
+  visibleToSource: readonly number[];
+  /** Visible index of each full-array row, or `-1` when a closed fold hides it. */
+  sourceToVisible: readonly number[];
+  /** Hidden row count for each closed header, keyed by the header's visible index. */
+  hiddenCounts: ReadonlyMap<number, number>;
+}
+
+/**
+ * Project `rowCount` rows through the closed folds. A closed range hides its
+ * body even when it sits inside another closed range; the outermost header
+ * shown carries the count of every row hidden below it.
+ */
+export const computeFoldView = function computeFoldView(
+  rowCount: number,
+  ranges: readonly FoldRange[],
+  closedKeys: ReadonlySet<Key>
+): FoldView {
+  const closedEnds = new Map<number, number>();
+  for (const range of ranges) {
+    if (range.end > range.start && closedKeys.has(range.key)) {
+      closedEnds.set(range.start, Math.max(closedEnds.get(range.start) ?? range.end, range.end));
+    }
+  }
+
+  const visibleToSource: number[] = [];
+  const sourceToVisible: number[] = Array.from({ length: rowCount }, () => -1);
+  const hiddenCounts = new Map<number, number>();
+  let hiddenUntil = -1;
+  for (let index = 0; index < rowCount; index += 1) {
+    if (index <= hiddenUntil) {
+      continue;
+    }
+    const visibleIndex = visibleToSource.length;
+    visibleToSource.push(index);
+    sourceToVisible[index] = visibleIndex;
+    const end = closedEnds.get(index);
+    if (end !== undefined) {
+      hiddenUntil = Math.min(end, rowCount - 1);
+      hiddenCounts.set(visibleIndex, hiddenUntil - index);
+    }
+  }
+
+  return { hiddenCounts, sourceToVisible, visibleToSource };
+};
+
+/** Ranges that contain `row` (header included), innermost first. */
+export const foldsAt = function foldsAt(
+  ranges: readonly FoldRange[],
+  row: number
+): readonly FoldRange[] {
+  return ranges
+    .filter((range) => range.end > range.start && range.start <= row && row <= range.end)
+    .toSorted((left, right) => right.start - left.start || left.end - right.end);
+};
+
+/**
+ * Keys of the closed ranges that hide `row`: closed ranges whose body
+ * (`start + 1 ..= end`) contains it. Opening them all makes `row` visible.
+ */
+export const closedFoldsHiding = function closedFoldsHiding(
+  ranges: readonly FoldRange[],
+  closedKeys: ReadonlySet<Key>,
+  row: number
+): Key[] {
+  return ranges
+    .filter((range) => closedKeys.has(range.key) && range.start < row && row <= range.end)
+    .map((range) => range.key);
+};
+
+/**
+ * The full-array row the cursor should rest on once `view` applies: `row`
+ * itself when it stays visible, otherwise the nearest visible row before it,
+ * which is the header of the outermost closed fold that hides it.
+ */
+export const visibleAnchorRow = function visibleAnchorRow(view: FoldView, row: number): number {
+  for (let index = Math.min(row, view.sourceToVisible.length - 1); index >= 0; index -= 1) {
+    if ((view.sourceToVisible[index] ?? -1) !== -1) {
+      return index;
+    }
+  }
+  return row;
+};

package/src/folds/markdown-heading-folds.ts

@@ -0,0 +1,55 @@
+import type { FlatBlock } from "@tooee/renderers";
+import type { Tokens } from "marked";
+
+import type { FoldRange } from "./fold-model.js";
+
+/** The Marked heading token of a flattened block, or `null` when the block is not a heading. */
+export const headingToken = function headingToken(block: FlatBlock): Tokens.Heading | null {
+  if (block.token.type !== "heading") {
+    return null;
+  }
+  // SAFETY: Marked creates a Heading token for the checked "heading" discriminator.
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Marked's Generic fallback prevents discriminator narrowing
+  return block.token as Tokens.Heading;
+};
+
+const headingDepth = function headingDepth(block: FlatBlock): number | null {
+  return headingToken(block)?.depth ?? null;
+};
+
+/**
+ * Heading fold ranges over flattened Markdown blocks. A heading at depth `d`
+ * folds every following block up to the next heading of depth `d` or less, or
+ * the end of the document. A heading with no body yields no range. Keys are
+ * the heading's block index, the same key the Markdown row adapter uses.
+ */
+export const markdownHeadingFoldRanges = function markdownHeadingFoldRanges(
+  blocks: readonly FlatBlock[]
+): FoldRange[] {
+  const ranges: FoldRange[] = [];
+  const open: { depth: number; start: number }[] = [];
+  const close = (start: number, end: number) => {
+    if (end > start) {
+      ranges.push({ end, key: start, start });
+    }
+  };
+
+  for (const [index, block] of blocks.entries()) {
+    const depth = headingDepth(block);
+    if (depth === null) {
+      continue;
+    }
+    while (open.length > 0 && (open.at(-1)?.depth ?? 0) >= depth) {
+      const finished = open.pop();
+      if (finished) {
+        close(finished.start, index - 1);
+      }
+    }
+    open.push({ depth, start: index });
+  }
+  for (const finished of open) {
+    close(finished.start, blocks.length - 1);
+  }
+
+  return ranges.toSorted((left, right) => left.start - right.start);
+};

package/src/folds/use-folds.ts

@@ -0,0 +1,203 @@
+import { useActions, useCommandGroup } from "@tooee/commands";
+import type { ActionDefinition, CommandContext, CommandHandler } from "@tooee/commands";
+import type { DecorationLayer } from "@tooee/renderers";
+import type { NavigationState } from "@tooee/shell";
+import { useMemo, useState } from "react";
+import type { Key } from "react";
+
+import { projectDecorationLayers } from "./fold-decorations.js";
+import { computeFoldView, foldsAt, visibleAnchorRow } from "./fold-model.js";
+import type { FoldRange, FoldView } from "./fold-model.js";
+
+const EMPTY_KEYS: ReadonlySet<Key> = new Set();
+
+/** Fold state over a full row array and the visible projection it produces. */
+export interface FoldState<T> {
+  /** The visible rows: pass this array to the document controller and the renderer. */
+  rows: readonly T[];
+  /** The full-array row count. */
+  rowCount: number;
+  ranges: readonly FoldRange[];
+  view: FoldView;
+  closedKeys: ReadonlySet<Key>;
+  setClosedKeys: (keys: ReadonlySet<Key>) => void;
+  /** External decoration layers projected onto the visible rows. */
+  decorations: DecorationLayer[];
+  /** One-based full-array row number for each visible row, or `undefined` when nothing is hidden. */
+  rowNumbers: readonly number[] | undefined;
+}
+
+/**
+ * Hold the closed fold keys for `rows` and project the rows, decorations and
+ * gutter numbers onto what stays visible. `ranges` and `decorations` use
+ * full-array row indices. With no closed fold, `rows` and `decorations` pass
+ * through unchanged.
+ */
+export const useFoldState = function useFoldState<T>(
+  rows: readonly T[],
+  ranges: readonly FoldRange[],
+  decorations: DecorationLayer[]
+): FoldState<T> {
+  const [closedKeys, setClosedKeys] = useState<ReadonlySet<Key>>(EMPTY_KEYS);
+  const view = useMemo(
+    () => computeFoldView(rows.length, ranges, closedKeys),
+    [rows.length, ranges, closedKeys]
+  );
+  const folded = view.visibleToSource.length < rows.length;
+
+  const visibleRows = useMemo(
+    () =>
+      folded
+        ? view.visibleToSource.flatMap((index) => {
+            const row = rows[index];
+            return row === undefined ? [] : [row];
+          })
+        : rows,
+    [folded, rows, view]
+  );
+  const visibleDecorations = useMemo(
+    () => (folded ? projectDecorationLayers(decorations, view) : decorations),
+    [folded, decorations, view]
+  );
+  const rowNumbers = useMemo(
+    () => (folded ? view.visibleToSource.map((index) => index + 1) : undefined),
+    [folded, view]
+  );
+
+  return {
+    closedKeys,
+    decorations: visibleDecorations,
+    ranges,
+    rowCount: rows.length,
+    rowNumbers,
+    rows: visibleRows,
+    setClosedKeys,
+    view,
+  };
+};
+
+/** Fold operations. Row arguments are full-array row indices. */
+export interface FoldActions {
+  /** Toggle the innermost fold that contains `row`. Returns false when no fold contains it. */
+  toggle: (row: number) => boolean;
+  /** Close the innermost open fold that contains `row`. Returns false when there is none. */
+  close: (row: number) => boolean;
+  /** Open the innermost closed fold that contains `row`. Returns false when there is none. */
+  open: (row: number) => boolean;
+  /** Open a fold at `row` when one is closed, else close the innermost open fold. */
+  toggleBlock: (row: number) => boolean;
+  closeAll: () => void;
+  openAll: () => void;
+}
+
+/**
+ * Fold operations over a fold state. Any change that hides the document
+ * cursor row first moves the cursor to the header of the outermost closed
+ * fold that hides it, and key preservation keeps it there. This holds for
+ * every target row, so a fold closed from the outline also keeps the cursor
+ * visible.
+ */
+export const useFoldActions = function useFoldActions<T>(
+  folds: FoldState<T>,
+  navigation: Pick<NavigationState, "cursor" | "setCursor">
+): FoldActions {
+  const { closedKeys, ranges, rowCount, setClosedKeys, view } = folds;
+  const { cursor, setCursor } = navigation;
+  const cursorRow = cursor === null ? undefined : view.visibleToSource[cursor];
+
+  const apply = (next: ReadonlySet<Key>) => {
+    if (cursorRow !== undefined) {
+      const anchor = visibleAnchorRow(computeFoldView(rowCount, ranges, next), cursorRow);
+      const anchorIndex = view.sourceToVisible[anchor] ?? -1;
+      if (anchor !== cursorRow && anchorIndex !== -1) {
+        setCursor(anchorIndex);
+      }
+    }
+    setClosedKeys(next);
+  };
+  const withKey = (key: Key | undefined, closed: boolean): boolean => {
+    if (key === undefined) {
+      return false;
+    }
+    const next = new Set(closedKeys);
+    if (closed) {
+      next.add(key);
+    } else {
+      next.delete(key);
+    }
+    apply(next);
+    return true;
+  };
+  const close = (row: number) =>
+    withKey(foldsAt(ranges, row).find((range) => !closedKeys.has(range.key))?.key, true);
+  const open = (row: number) =>
+    withKey(foldsAt(ranges, row).find((range) => closedKeys.has(range.key))?.key, false);
+
+  return {
+    close,
+    closeAll: () => {
+      apply(new Set(ranges.map((range) => range.key)));
+    },
+    open,
+    openAll: () => {
+      apply(EMPTY_KEYS);
+    },
+    toggle: (row) => {
+      const [innermost] = foldsAt(ranges, row);
+      return withKey(innermost?.key, innermost !== undefined && !closedKeys.has(innermost.key));
+    },
+    toggleBlock: (row) =>
+      foldsAt(ranges, row).some((range) => closedKeys.has(range.key)) ? open(row) : close(row),
+  };
+};
+
+/**
+ * The Vim fold commands (`z a`, `z c`, `z o`, `z z`, `z shift+m`,
+ * `z shift+r`) as action definitions. The row commands act on `targetRow()`:
+ * the document cursor row on the root surface, or the selected heading in the
+ * outline. `idPrefix` keeps the ids apart on each surface, and `noFoldMessage`
+ * is the warning when no fold contains the target row.
+ */
+export const foldActionDefinitions = function foldActionDefinitions(
+  actions: FoldActions,
+  targetRow: () => number | undefined,
+  idPrefix: string,
+  noFoldMessage: string
+): ActionDefinition[] {
+  const atTarget =
+    (run: (row: number) => boolean) =>
+    (ctx: CommandContext): void => {
+      const row = targetRow();
+      if (row === undefined || !run(row)) {
+        ctx.toast?.toast({ level: "warning", message: noFoldMessage });
+      }
+    };
+  const definitions: [hotkey: string, id: string, title: string, handler: CommandHandler][] = [
+    ["z a", "toggle", "Toggle fold", atTarget(actions.toggle)],
+    ["z c", "close", "Close fold", atTarget(actions.close)],
+    ["z o", "open", "Open fold", atTarget(actions.open)],
+    ["z z", "toggle-block", "Open or close fold", atTarget(actions.toggleBlock)],
+    ["z shift+m", "close-all", "Close all folds", actions.closeAll],
+    ["z shift+r", "open-all", "Open all folds", actions.openAll],
+  ];
+  return definitions.map(([hotkey, id, title, handler]) => ({
+    category: "Fold",
+    handler,
+    hotkey,
+    id: `${idPrefix}.${id}`,
+    modes: ["cursor"],
+    title,
+  }));
+};
+
+/** Register the fold commands on the current surface, acting on the document cursor row. */
+export const useFoldCommands = function useFoldCommands<T>(
+  folds: FoldState<T>,
+  actions: FoldActions,
+  navigation: Pick<NavigationState, "cursor">
+): void {
+  const { cursor } = navigation;
+  const cursorRow = cursor === null ? undefined : folds.view.visibleToSource[cursor];
+  useCommandGroup({ id: "fold", prefix: "z", title: "Fold" });
+  useActions(foldActionDefinitions(actions, () => cursorRow, "fold", "No fold at cursor"));
+};

package/src/launch.tsx

@@ -23,6 +23,8 @@ export interface ViewLaunchOptions {
    * Unmatched types fall back to the default syntax-highlighted code block.
    */
   codeBlockRenderers?: Record<string, CodeBlockRenderer>;
+  /** Open the heading outline beside Markdown content at start. */
+  outline?: boolean;
 }
 
 export interface DirectoryLaunchOptions {

package/src/outline/markdown-outline.ts

@@ -0,0 +1,45 @@
+import { getPlainText } from "@tooee/renderers";
+import type { FlatBlock } from "@tooee/renderers";
+
+import { headingToken } from "../folds/markdown-heading-folds.js";
+
+/** One heading in a document outline. */
+export interface OutlineEntry {
+  /** The heading's index in the full row array, the same key folds use. */
+  row: number;
+  /** Heading level, 1 for `#`. */
+  depth: number;
+  /** Indent level in the outline: depth relative to the shallowest heading. */
+  level: number;
+  /** Unstyled heading text. */
+  text: string;
+}
+
+/**
+ * The headings of flattened Markdown blocks, in document order. Levels start
+ * at 0 for the shallowest heading in the document, so a document that starts
+ * at `##` is not indented.
+ */
+export const markdownOutline = function markdownOutline(
+  blocks: readonly FlatBlock[]
+): OutlineEntry[] {
+  const headings = blocks.flatMap((block, row) => {
+    const heading = headingToken(block);
+    return heading === null
+      ? []
+      : [{ depth: heading.depth, row, text: getPlainText(heading.tokens).trim() }];
+  });
+  const minDepth = Math.min(...headings.map((heading) => heading.depth));
+  return headings.map((heading) => ({ ...heading, level: heading.depth - minDepth }));
+};
+
+/**
+ * Index of the entry for the heading that contains `row`: the last heading at
+ * or before it. Returns `-1` before the first heading or for an empty outline.
+ */
+export const outlineIndexAt = function outlineIndexAt(
+  entries: readonly OutlineEntry[],
+  row: number
+): number {
+  return entries.findLastIndex((entry) => entry.row <= row);
+};