@tooee/view 0.10.3 → 0.12.0

package/src/outline/outline-panel.tsx

@@ -0,0 +1,171 @@
+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,188 @@
+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

@@ -107,6 +107,7 @@ export const createStandaloneRouter = function createStandaloneRouter(
         codeBlockRenderers={options.codeBlockRenderers}
         contentProvider={provider}
         onMarkdownLinkActivate={activate}
+        outline={options.outline}
         renderers={options.renderers}
       />
     );

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);
@@ -101,6 +104,7 @@ export const View = function View({
           content={content}
           codeBlockRenderers={mergedCodeBlockRenderers}
           onLinkActivate={onMarkdownLinkActivate}
+          outline={outline}
           {...shared}
         />
       );