@tooee/view 0.11.0 → 0.13.0

package/src/outline/outline-panel.tsx

@@ -0,0 +1,184 @@
+import type { MouseEvent, ScrollBoxRenderable } from "@opentui/core";
+import { useActions } from "@tooee/commands";
+import type { ActionDefinition } from "@tooee/commands";
+import { Panel, PanelGroup } from "@tooee/panels";
+import { useTheme } from "@tooee/themes";
+import { useEffect, useRef } from "react";
+import type { ReactNode } from "react";
+
+import { foldActionDefinitions } from "../folds/use-folds.js";
+import type { FoldActions } from "../folds/use-folds.js";
+import type { OutlineEntry } from "./markdown-outline.js";
+import type { OutlineState } from "./use-outline.js";
+
+const OUTLINE_PANEL_ID = "outline";
+
+const INDENT = "  ";
+
+/** Columns the panel border and the list padding take from the panel width. */
+const OUTLINE_CHROME_WIDTH = 4;
+
+const entryId = (entry: OutlineEntry): string => `outline-entry-${entry.row}`;
+
+/** One outline line: indent, current-heading marker and text, cut to `width` columns. */
+export const outlineLabel = function outlineLabel(
+  entry: OutlineEntry,
+  current: boolean,
+  closed: boolean,
+  width: number
+): string {
+  const suffix = closed ? " ⋯" : "";
+  const label = `${INDENT.repeat(entry.level)}${current ? "▸ " : "  "}${entry.text}`;
+  const room = Math.max(1, width - suffix.length);
+  const cut = label.length > room ? `${label.slice(0, Math.max(0, room - 1))}…` : label;
+
+  return `${cut}${suffix}`;
+};
+
+/**
+ * The panel-owned outline commands. They register on the outline panel's
+ * surface, so they only dispatch while the outline has focus, and they shadow
+ * the root commands on the same keys. `g o` closes the outline here, because
+ * the panel's `g g` holds the `g` chord. The fold keys act on the selected
+ * heading's section, so the panel registers the whole `z` set.
+ */
+const OutlineCommands = function OutlineCommands({
+  outline,
+  foldActions,
+}: {
+  outline: OutlineState;
+  foldActions: FoldActions;
+}): null {
+  const next = (): void => {
+    outline.move(1);
+  };
+
+  const previous = (): void => {
+    outline.move(-1);
+  };
+
+  const first = (): void => {
+    outline.select(0);
+  };
+
+  const last = (): void => {
+    outline.select(outline.entries.length - 1);
+  };
+
+  const jump = (): void => {
+    outline.jump(outline.selectedIndex);
+  };
+
+  const commands: [hotkey: string, id: string, title: string, run: () => void][] = [
+    ["j", "outline.down", "Next heading", next],
+    ["down", "outline.down-arrow", "Next heading", next],
+    ["k", "outline.up", "Previous heading", previous],
+    ["up", "outline.up-arrow", "Previous heading", previous],
+    ["g g", "outline.first", "First heading", first],
+    ["shift+g", "outline.last", "Last heading", last],
+    ["enter", "outline.jump", "Jump to heading", jump],
+    ["escape", "outline.focus-content", "Return to document", outline.focusContent],
+    ["g o", "outline.close", "Close outline", outline.close],
+  ];
+
+  const selectedRow = (): number | undefined => outline.entries[outline.selectedIndex]?.row;
+  useActions([
+    ...commands.map(([hotkey, id, title, run]): ActionDefinition => ({
+      category: "Outline",
+      handler: run,
+      hotkey,
+      id,
+      modes: ["cursor"],
+      title,
+    })),
+    ...foldActionDefinitions(foldActions, selectedRow, "outline.fold", "No fold at heading"),
+  ]);
+
+  return null;
+};
+
+const OutlineList = function OutlineList({ outline }: { outline: OutlineState }): ReactNode {
+  const { theme } = useTheme();
+  const scrollRef = useRef<ScrollBoxRenderable | null>(null);
+  const textWidth = Math.max(1, outline.width - OUTLINE_CHROME_WIDTH);
+  const selected = outline.entries[outline.selectedIndex];
+
+  useEffect(() => {
+    if (selected !== undefined) {
+      scrollRef.current?.scrollChildIntoView(entryId(selected));
+    }
+  }, [selected]);
+
+  if (outline.entries.length === 0) {
+    return <text content="No headings" fg={theme.textMuted} paddingLeft={1} />;
+  }
+
+  return (
+    <scrollbox
+      ref={scrollRef}
+      style={{ flexGrow: 1 }}
+      focused={false}
+      verticalScrollbarOptions={{ visible: false }}
+    >
+      {outline.entries.map((entry, index): ReactNode => {
+        const current = index === outline.currentIndex;
+        const highlighted = outline.focused && index === outline.selectedIndex;
+
+        return (
+          <box
+            key={entry.row}
+            id={entryId(entry)}
+            paddingLeft={1}
+            paddingRight={1}
+            backgroundColor={highlighted ? theme.cursorLine : undefined}
+            onMouseDown={(event: MouseEvent) => {
+              event.stopPropagation();
+              outline.jump(index);
+            }}
+          >
+            <text
+              content={outlineLabel(entry, current, outline.closedRows.has(entry.row), textWidth)}
+              fg={current ? theme.accent : theme.text}
+            />
+          </box>
+        );
+      })}
+    </scrollbox>
+  );
+};
+
+/**
+ * The outline as a side panel. A controlled group with one panel: the panel
+ * is active only while the outline has focus, so the document keeps the root
+ * surface the rest of the time. Built-in Tab switching is off, so Tab keeps
+ * its multi-select meaning in the document.
+ */
+export const OutlinePanel = function OutlinePanel({
+  outline,
+  foldActions,
+}: {
+  outline: OutlineState;
+  foldActions: FoldActions;
+}): ReactNode {
+  if (!outline.visible) {
+    return null;
+  }
+
+  // The only panel asks for activation on a mouse-down inside it.
+  const handleActivePanelChange = (): void => {
+    outline.focus();
+  };
+
+  return (
+    <PanelGroup
+      activePanelId={outline.focused ? OUTLINE_PANEL_ID : null}
+      onActivePanelChange={handleActivePanelChange}
+      switchKeys={null}
+    >
+      <Panel id={OUTLINE_PANEL_ID} title="Outline" style={{ flexShrink: 0, width: outline.width }}>
+        <OutlineCommands outline={outline} foldActions={foldActions} />
+        <OutlineList outline={outline} />
+      </Panel>
+    </PanelGroup>
+  );
+};

package/src/outline/use-outline.ts

@@ -0,0 +1,212 @@
+import { useTerminalDimensions } from "@opentui/react";
+import { useCommand } from "@tooee/commands";
+import type { FlatBlock } from "@tooee/renderers";
+import type { DocumentController, NavigationState } from "@tooee/shell";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import { closedFoldsHiding } from "../folds/fold-model.js";
+import type { FoldState } from "../folds/use-folds.js";
+import { markdownOutline, outlineIndexAt } from "./markdown-outline.js";
+import type { OutlineEntry } from "./markdown-outline.js";
+
+/** Outline width in columns, border included. */
+const OUTLINE_WIDTH = 32;
+
+/** The outline never takes more than this share of the terminal width. */
+const OUTLINE_MAX_SHARE = 0.4;
+
+/** Below this terminal width the outline is not shown. */
+export const OUTLINE_MIN_TERMINAL_WIDTH = 60;
+
+/**
+ * Lines of the document kept above a heading after a jump. The heading lands
+ * near the top of the view, with a little of the text before it for context.
+ */
+export const OUTLINE_JUMP_MARGIN = 3;
+
+/** Columns for the outline at a terminal width, or 0 when the terminal is too narrow. */
+export const outlineWidth = function outlineWidth(terminalWidth: number): number {
+  if (terminalWidth < OUTLINE_MIN_TERMINAL_WIDTH) {
+    return 0;
+  }
+
+  return Math.min(OUTLINE_WIDTH, Math.floor(terminalWidth * OUTLINE_MAX_SHARE));
+};
+
+/** State and actions of a document outline. */
+export interface OutlineState {
+  entries: readonly OutlineEntry[];
+  /** Entry of the heading that contains the document cursor, or -1. */
+  currentIndex: number;
+  /** Entry the outline highlights as selected: the current heading unless the outline has focus. */
+  selectedIndex: number;
+  /** Full-array rows whose own heading fold is closed. */
+  closedRows: ReadonlySet<number>;
+  /** True when the outline is open and the terminal is wide enough to show it. */
+  visible: boolean;
+  /** True when the visible outline owns keyboard input. */
+  focused: boolean;
+  /** Outline width in columns, or 0 when the terminal is too narrow. */
+  width: number;
+  focus: () => void;
+  focusContent: () => void;
+  close: () => void;
+  move: (delta: number) => void;
+  select: (index: number) => void;
+  /** Move the document cursor to an entry's heading and give focus back to the content. */
+  jump: (index: number) => void;
+}
+
+interface UseOutlineOptions {
+  blocks: readonly FlatBlock[];
+  folds: FoldState<FlatBlock>;
+  navigation: Pick<NavigationState, "cursor" | "setCursor">;
+  /** Scrolls a jumped-to heading near the top of the document view. */
+  revealRow: DocumentController<FlatBlock>["revealRow"];
+  initialOpen?: boolean;
+}
+
+/**
+ * Outline state for a Markdown document, and the root `g o` command that
+ * opens, focuses and closes it. A jump to a heading inside closed folds opens
+ * those folds, then moves the cursor once the new rows are in place. Every
+ * jump scrolls the heading to near the top of the view.
+ */
+export const useMarkdownOutline = function useMarkdownOutline({
+  blocks,
+  folds,
+  navigation,
+  revealRow,
+  initialOpen = false,
+}: UseOutlineOptions): OutlineState {
+  const entries = useMemo(() => markdownOutline(blocks), [blocks]);
+  const { width: terminalWidth } = useTerminalDimensions();
+  const width = outlineWidth(terminalWidth);
+  const [open, setOpen] = useState(initialOpen);
+  const [focusRequested, setFocusRequested] = useState(false);
+  const [selected, setSelected] = useState(0);
+
+  const { closedKeys, ranges, setClosedKeys, view } = folds;
+  const { cursor, setCursor } = navigation;
+  const visible = open && width > 0;
+
+  const moveTo = useCallback(
+    (index: number) => {
+      setCursor(index);
+      revealRow(index, { align: "start", margin: OUTLINE_JUMP_MARGIN });
+    },
+    [setCursor, revealRow]
+  );
+
+  const focused = visible && focusRequested;
+  const sourceRow = cursor === null ? undefined : view.visibleToSource[cursor];
+  const currentIndex = sourceRow === undefined ? -1 : outlineIndexAt(entries, sourceRow);
+  const selectedIndex = focused ? Math.min(selected, entries.length - 1) : currentIndex;
+
+  const closedRows = useMemo(
+    () => new Set(ranges.filter((range) => closedKeys.has(range.key)).map((range) => range.start)),
+    [ranges, closedKeys]
+  );
+
+  // A jump that opens folds waits for the new fold view, then moves the
+  // cursor. This effect runs after the controller's own rows effect, so the
+  // store already holds the new rows.
+  const pendingRowRef = useRef<number | null>(null);
+  useEffect(() => {
+    const row = pendingRowRef.current;
+    const index = row === null ? -1 : (view.sourceToVisible[row] ?? -1);
+
+    if (index !== -1) {
+      pendingRowRef.current = null;
+      moveTo(index);
+    }
+  }, [view, moveTo]);
+
+  const focus = () => {
+    setSelected(Math.max(currentIndex, 0));
+    setFocusRequested(true);
+  };
+
+  const focusContent = () => {
+    setFocusRequested(false);
+  };
+
+  const close = () => {
+    setOpen(false);
+    setFocusRequested(false);
+  };
+
+  const select = (index: number) => {
+    setSelected(Math.max(0, Math.min(index, entries.length - 1)));
+  };
+
+  const move = (delta: number) => {
+    select(selectedIndex + delta);
+  };
+
+  const jump = (index: number) => {
+    const entry = entries[index];
+    setFocusRequested(false);
+
+    if (entry === undefined) {
+      return;
+    }
+
+    const hiding = closedFoldsHiding(ranges, closedKeys, entry.row);
+
+    if (hiding.length === 0) {
+      moveTo(view.sourceToVisible[entry.row] ?? 0);
+
+      return;
+    }
+
+    const next = new Set(closedKeys);
+
+    for (const key of hiding) {
+      next.delete(key);
+    }
+
+    pendingRowRef.current = entry.row;
+    setClosedKeys(next);
+  };
+
+  useCommand({
+    category: "Outline",
+    handler: (ctx) => {
+      if (width === 0) {
+        ctx.toast?.toast({ level: "info", message: "The outline needs a wider terminal" });
+
+        return;
+      }
+
+      if (open && focused) {
+        close();
+
+        return;
+      }
+
+      setOpen(true);
+      focus();
+    },
+    hotkey: "g o",
+    id: "outline.toggle",
+    modes: ["cursor"],
+    title: "Toggle outline",
+  });
+
+  return {
+    close,
+    closedRows,
+    currentIndex,
+    entries,
+    focus,
+    focusContent,
+    focused,
+    jump,
+    move,
+    select,
+    selectedIndex,
+    visible,
+    width,
+  };
+};

package/src/standalone-router.tsx

@@ -2,7 +2,6 @@ import path from "node:path";
 
 import { useChooseDialog } from "@tooee/choose";
 import { useCommand } from "@tooee/commands";
-import type { CommandContext } from "@tooee/commands";
 import {
   createRoute,
   createRouter,
@@ -22,6 +21,7 @@ import { runLinkHandlers } from "./link-handlers.js";
 import { markdownLinks } from "./markdown-links.js";
 import type { MarkdownLink } from "./markdown-links.js";
 import { getTextContent } from "./types.js";
+import type { MarkdownLinkActivateHandler } from "./types.js";
 import { View } from "./view.js";
 
 const documentParams: Codec<{ path?: string }> = {
@@ -30,12 +30,15 @@ const documentParams: Codec<{ path?: string }> = {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
       throw new TypeError("Expected document params");
     }
+
     if (!("path" in value) || value.path === undefined) {
       return {};
     }
+
     if (typeof value.path !== "string" || !path.isAbsolute(value.path)) {
       throw new TypeError("Expected an absolute document path");
     }
+
     /* oxlint-enable anti-slop/no-runtime-typeof */
     return { path: value.path };
   },
@@ -55,32 +58,45 @@ export const createStandaloneRouter = function createStandaloneRouter(
     const navigate = useNavigate();
     const { stack } = useRouter();
     const chooseLink = useChooseDialog<MarkdownLink>();
+
     const provider = useMemo(
       () =>
         documentPath === undefined ? options.contentProvider : createFileProvider(documentPath),
       [documentPath]
     );
-    const activate = (href: string, command: CommandContext): boolean => {
+
+    const activate: MarkdownLinkActivateHandler = (href, command) => {
+      if (options.onMarkdownLinkActivate) {
+        return options.onMarkdownLinkActivate(href, command);
+      }
+
       if (options.filePath === undefined) {
         command.toast?.toast({ level: "info", message: "Links need a source file" });
+
         return true;
       }
+
       const currentPath = path.resolve(documentPath ?? options.filePath);
+
       return runLinkHandlers(
         options.linkHandlers ?? [],
         { baseDir: path.dirname(currentPath), currentPath, href },
         { command, documentRoute, navigate }
       );
     };
+
     useCommand({
       handler: async (context) => {
         // Source positions are zero-based, unlike the displayed line numbers.
         const line = context.document?.activeAnchor?.source?.primary?.start.line;
         const content = context.view?.content;
+
         if (line === undefined || content === undefined) {
           return;
         }
+
         const links = markdownLinks(getTextContent(content).split("\n")[line] ?? "");
+
         // One link follows directly; several open a chooser so none is silently preferred.
         const link =
           links.length > 1
@@ -90,6 +106,7 @@ export const createStandaloneRouter = function createStandaloneRouter(
                 toItem: (item) => ({ description: item.href, text: item.text }),
               })
             : (links[0] ?? null);
+
         if (link !== null) {
           activate(link.href, context);
         }
@@ -100,6 +117,7 @@ export const createStandaloneRouter = function createStandaloneRouter(
       title: "Follow Markdown link",
       when: (context) => context.view?.format === "markdown",
     });
+
     return (
       <View
         key={`${stack.length}:${documentPath ?? ""}`}
@@ -107,18 +125,22 @@ export const createStandaloneRouter = function createStandaloneRouter(
         codeBlockRenderers={options.codeBlockRenderers}
         contentProvider={provider}
         onMarkdownLinkActivate={activate}
+        outline={options.outline}
         renderers={options.renderers}
       />
     );
   };
+
   const documentRoute = createRoute({
     component: DocumentScreen,
     id: "view.document",
     params: documentParams,
   });
+
   const router = createRouter({
     initial: { routeId: documentRoute.id },
     routes: [documentRoute],
   });
+
   return { documentRoute, router };
 };

package/src/types.ts

@@ -137,7 +137,9 @@ export interface ContentProvider {
 // === Compat aliases ===
 
 export type ViewContent = Content;
+
 export type ViewContentProvider = ContentProvider;
+
 export type { ColumnDef, TableRow } from "@tooee/renderers";
 
 // === Utilities ===
@@ -167,29 +169,38 @@ export const getTextContent = function getTextContent(content: AnyContent): stri
     case "markdown": {
       return content.markdown;
     }
+
     case "code": {
       return content.code;
     }
+
     case "diff": {
       return content.patch;
     }
+
     case "text": {
       return content.text;
     }
+
     case "image": {
       // oxlint-disable-next-line anti-slop/no-runtime-typeof -- ImageSource is OpenTUI's public string-or-binary union; only its string and URL variants have text content
       if (typeof content.src === "string") {
         return content.src;
       }
+
       return content.src instanceof URL ? content.src.href : "";
     }
+
     case "table": {
       const headers = content.columns.map((column) => column.header ?? column.key);
+
       const rowLines = content.rows.map((row) =>
         content.columns.map((column) => formatTableCell(row[column.key])).join("\t")
       );
+
       return [headers.join("\t"), ...rowLines].join("\n");
     }
+
     default: {
       return "";
     }

package/src/view.tsx

@@ -30,6 +30,8 @@ interface ViewProps {
   codeBlockRenderers?: Record<string, CodeBlockRenderer>;
   /** Handles primary-button activation of inline Markdown links. */
   onMarkdownLinkActivate?: MarkdownLinkActivateHandler;
+  /** Open the heading outline beside Markdown content at start. Other formats ignore it. */
+  outline?: boolean;
 }
 
 export const View = function View({
@@ -38,6 +40,7 @@ export const View = function View({
   renderers,
   codeBlockRenderers,
   onMarkdownLinkActivate,
+  outline,
 }: ViewProps): ReactNode {
   const { theme } = useTheme();
   const { content, streaming, error, providerMarks, reload } = useContentLoader(contentProvider);
@@ -47,6 +50,7 @@ export const View = function View({
   const setMarkSet = useCallback((set: MarkSet) => {
     setUserMarks((prev) => {
       const filtered = prev.filter((s) => s.namespace !== set.namespace);
+
       return [...filtered, set];
     });
   }, []);
@@ -101,23 +105,29 @@ export const View = function View({
           content={content}
           codeBlockRenderers={mergedCodeBlockRenderers}
           onLinkActivate={onMarkdownLinkActivate}
+          outline={outline}
           {...shared}
         />
       );
     }
+
     case "code":
     case "text": {
       return <CodeSubview content={content} {...shared} />;
     }
+
     case "image": {
       return <ImageSubview content={content} {...shared} />;
     }
+
     case "table": {
       return <TableSubview content={content} {...shared} />;
     }
+
     case "diff": {
       return <DiffSubview content={content} {...shared} />;
     }
+
     default: {
       return null;
     }