@tooee/view 0.11.0 → 0.13.0

package/src/folds/use-folds.ts

@@ -1,5 +1,5 @@
-import { useCommand, useCommandGroup } from "@tooee/commands";
-import type { CommandContext } from "@tooee/commands";
+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";
@@ -39,10 +39,12 @@ export const useFoldState = function useFoldState<T>(
   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(
@@ -50,15 +52,18 @@ export const useFoldState = function useFoldState<T>(
       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]
@@ -76,114 +81,141 @@ export const useFoldState = function useFoldState<T>(
   };
 };
 
-const warnNoFold = function warnNoFold(ctx: CommandContext): void {
-  ctx.toast?.toast({ level: "warning", message: "No fold at cursor" });
-};
+/** 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;
+}
 
 /**
- * Register the Vim fold commands (`z a`, `z c`, `z o`, `z shift+m`,
- * `z shift+r`) against a fold state and the controller's navigation. When a
- * close hides the cursor row, the cursor moves first to the header of the
- * outermost closed fold, and key preservation keeps it there.
+ * 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 useFoldCommands = function useFoldCommands<T>(
+export const useFoldActions = function useFoldActions<T>(
   folds: FoldState<T>,
   navigation: Pick<NavigationState, "cursor" | "setCursor">
-): void {
+): FoldActions {
   const { closedKeys, ranges, rowCount, setClosedKeys, view } = folds;
   const { cursor, setCursor } = navigation;
-  const sourceRow = cursor === null ? undefined : view.visibleToSource[cursor];
-  const atCursor = sourceRow === undefined ? [] : foldsAt(ranges, sourceRow);
+  const cursorRow = cursor === null ? undefined : view.visibleToSource[cursor];
 
   const apply = (next: ReadonlySet<Key>) => {
-    if (sourceRow !== undefined) {
-      const anchor = visibleAnchorRow(computeFoldView(rowCount, ranges, next), sourceRow);
+    if (cursorRow !== undefined) {
+      const anchor = visibleAnchorRow(computeFoldView(rowCount, ranges, next), cursorRow);
       const anchorIndex = view.sourceToVisible[anchor] ?? -1;
-      if (anchor !== sourceRow && anchorIndex !== -1) {
+
+      if (anchor !== cursorRow && anchorIndex !== -1) {
         setCursor(anchorIndex);
       }
     }
+
     setClosedKeys(next);
   };
-  const withKey = (key: Key, closed: boolean) => {
+
+  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;
   };
 
-  useCommandGroup({ id: "fold", prefix: "z", title: "Fold" });
+  const close = (row: number) =>
+    withKey(foldsAt(ranges, row).find((range) => !closedKeys.has(range.key))?.key, true);
 
-  useCommand({
-    category: "Fold",
-    handler: (ctx) => {
-      const [innermost] = atCursor;
-      if (innermost === undefined) {
-        warnNoFold(ctx);
-        return;
-      }
-      withKey(innermost.key, !closedKeys.has(innermost.key));
+  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)));
     },
-    hotkey: "z a",
-    id: "fold.toggle",
-    modes: ["cursor"],
-    title: "Toggle fold",
-  });
+    open,
+    openAll: () => {
+      apply(EMPTY_KEYS);
+    },
+    toggle: (row) => {
+      const [innermost] = foldsAt(ranges, row);
 
-  useCommand({
-    category: "Fold",
-    handler: (ctx) => {
-      const target = atCursor.find((range) => !closedKeys.has(range.key));
-      if (target === undefined) {
-        warnNoFold(ctx);
-        return;
-      }
-      withKey(target.key, true);
+      return withKey(innermost?.key, innermost !== undefined && !closedKeys.has(innermost.key));
     },
-    hotkey: "z c",
-    id: "fold.close",
-    modes: ["cursor"],
-    title: "Close fold",
-  });
+    toggleBlock: (row) =>
+      foldsAt(ranges, row).some((range) => closedKeys.has(range.key)) ? open(row) : close(row),
+  };
+};
 
-  useCommand({
-    category: "Fold",
-    handler: (ctx) => {
-      const target = atCursor.find((range) => closedKeys.has(range.key));
-      if (target === undefined) {
-        warnNoFold(ctx);
-        return;
+/**
+ * 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 });
       }
-      withKey(target.key, false);
-    },
-    hotkey: "z o",
-    id: "fold.open",
-    modes: ["cursor"],
-    title: "Open fold",
-  });
+    };
 
-  useCommand({
-    category: "Fold",
-    handler: () => {
-      apply(new Set(ranges.map((range) => range.key)));
-    },
-    hotkey: "z shift+m",
-    id: "fold.close-all",
-    modes: ["cursor"],
-    title: "Close all folds",
-  });
+  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],
+  ];
 
-  useCommand({
+  return definitions.map(([hotkey, id, title, handler]) => ({
     category: "Fold",
-    handler: () => {
-      apply(EMPTY_KEYS);
-    },
-    hotkey: "z shift+r",
-    id: "fold.open-all",
+    handler,
+    hotkey,
+    id: `${idPrefix}.${id}`,
     modes: ["cursor"],
-    title: "Open all folds",
-  });
+    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/hooks/use-content-document.ts

@@ -1,4 +1,5 @@
 import type { ActionDefinition } from "@tooee/commands";
+import { StatusPriority } from "@tooee/layout";
 import type { StatusBarItem } from "@tooee/layout";
 import type { DecorationLayer } from "@tooee/renderers";
 import { useDocumentController } from "@tooee/shell";
@@ -37,6 +38,7 @@ export const useContentDocument = function useContentDocument<T>(
   options: ContentDocumentOptions<T>
 ): ContentDocumentResult<T> {
   const { showLineNumbers } = useContentCommands({ content, textContent });
+
   const document = useDocumentController<T>({
     adapter,
     contextMenu: options.contextMenu === false ? false : actions,
@@ -45,10 +47,11 @@ export const useContentDocument = function useContentDocument<T>(
     preserveCursorByKey: options.preserveCursorByKey,
     rows,
   });
+
   const statusItems = options.buildStatusItems?.(document) ??
     options.statusItems ?? [
-      { label: "Format:", value: content.format },
-      { label: "Lines:", value: String(rows.length) },
+      { label: "Format:", priority: StatusPriority.content, value: content.format },
+      { label: "Lines:", priority: StatusPriority.content, value: String(rows.length) },
     ];
 
   return { document, showLineNumbers, statusItems };

package/src/hooks/use-content-loader.ts

@@ -39,6 +39,7 @@ export const useContentLoader = function useContentLoader(
     });
     const { requestId } = store.getSnapshot().context;
     const loaded = contentProvider.load();
+
     let cleanup: () => void = () => {
       // Synchronous providers have no pending work to cancel.
     };
@@ -55,16 +56,20 @@ export const useContentLoader = function useContentLoader(
             // preserve sequential stream consumption for ordered backpressure.
             // oxlint-disable-next-line no-await-in-loop -- each chunk must be consumed in iterator order
             const result = await iterator.next();
+
             if (result.done === true) {
               break;
             }
+
             store.trigger.chunkReceived({ chunk: result.value, requestId });
           }
+
           store.trigger.streamEnded({ requestId });
         } catch (error) {
           store.trigger.loadFailed({ error: normalizeError(error), requestId });
         }
       })();
+
       cleanup = () => {
         store.trigger.loadCancelled({ requestId });
         void (async () => {
@@ -84,6 +89,7 @@ export const useContentLoader = function useContentLoader(
           store.trigger.loadFailed({ error: normalizeError(error), requestId });
         }
       })();
+
       cleanup = () => {
         store.trigger.loadCancelled({ requestId });
       };
@@ -99,6 +105,7 @@ export const useContentLoader = function useContentLoader(
   const error = useSelector(store, (snapshot) => selectError(snapshot.context));
   const providerMarks = useSelector(store, (snapshot) => selectProviderMarks(snapshot.context));
   const status = useSelector(store, (snapshot) => selectStatus(snapshot.context));
+
   const reload = useCallback(() => {
     store.trigger.reloadRequested({});
   }, [store]);

package/src/hooks/use-view-command-context.ts

@@ -72,6 +72,7 @@ export const createViewCommandContext = function createViewCommandContext({
   marks,
 }: CreateViewCommandContextOptions): ViewCommandContext {
   const resolvedFormat = format ?? content?.format ?? "custom";
+
   const resolvedContent: AnyContent =
     content ??
     ({

package/src/index.ts

@@ -1,27 +1,39 @@
 export { View } from "./view.js";
+
 export { DirectoryView } from "./directory-view.js";
+
 export { launch, launchDirectory } from "./launch.js";
+
 export type { ViewLaunchOptions } from "./launch.js";
+
 export {
   createFileProvider,
   createStdinProvider,
   createTableFileProvider,
   createTableStdinProvider,
 } from "./default-provider.js";
+
 export type { CreateProviderOptions } from "./default-provider.js";
+
 export { listDirectoryFiles } from "./directory-provider.js";
+
 export type { DirectoryEntry } from "./directory-provider.js";
+
 export {
   createViewCommandContext,
   useProvideViewCommandContext,
 } from "./hooks/use-view-command-context.js";
+
 export type {
   CreateViewCommandContextOptions,
   ProvideViewCommandContextOptions,
   ViewCommandContext,
 } from "./hooks/use-view-command-context.js";
+
 export type { ContentLoaderState } from "./hooks/use-content-loader.js";
+
 export type { ContentCommandsResult } from "./hooks/use-content-commands.js";
+
 export type {
   AnyContent,
   Content,
@@ -43,8 +55,13 @@ export type {
   ColumnDef,
   TableRow,
 } from "./types.js";
+
 export { getTextContent, isBuiltinContent, isCustomContent } from "./types.js";
+
 export { CodeBlockChrome } from "@tooee/renderers";
+
 export type { CodeBlockRenderer, CodeBlockRendererProps, CodeBlockHScroll } from "@tooee/renderers";
+
 export { localFileLinkHandler } from "./link-handlers.js";
+
 export type { LinkHandler, LinkHandlerContext, LinkTarget } from "./link-handlers.js";

package/src/launch.tsx

@@ -7,7 +7,7 @@ import type { ReactNode } from "react";
 import { DirectoryView } from "./directory-view.js";
 import type { LinkHandler } from "./link-handlers.js";
 import { createStandaloneRouter } from "./standalone-router.js";
-import type { ContentProvider, ContentRenderer } from "./types.js";
+import type { ContentProvider, ContentRenderer, MarkdownLinkActivateHandler } from "./types.js";
 
 export interface ViewLaunchOptions {
   contentProvider: ContentProvider;
@@ -15,6 +15,12 @@ export interface ViewLaunchOptions {
   filePath?: string;
   /** Synchronous handlers tried before local file navigation. */
   linkHandlers?: readonly LinkHandler[];
+  /**
+   * Handles activation of a Markdown link, by mouse or by Enter on the cursor
+   * line. When set, it replaces the default handling: `linkHandlers`, local
+   * file navigation, and the stdin "Links need a source file" toast.
+   */
+  onMarkdownLinkActivate?: MarkdownLinkActivateHandler;
   actions?: ActionDefinition[];
   renderers?: Record<string, ContentRenderer>;
   /**
@@ -23,6 +29,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 {
@@ -33,9 +41,11 @@ export interface DirectoryLaunchOptions {
 export const launch = async function launch(options: ViewLaunchOptions): Promise<void> {
   const { router } = createStandaloneRouter(options);
   const startup = await router.start();
+
   if (startup.status !== "committed") {
     throw new Error(`View router startup ${startup.status}`);
   }
+
   await runCliSession<undefined>(
     (): ReactNode => (
       <RouterProvider router={router}>

package/src/link-handlers.ts

@@ -24,22 +24,29 @@ export type LinkHandler = (link: LinkTarget, context: LinkHandlerContext) => boo
 
 export const localFileLinkHandler: LinkHandler = function localFileLinkHandler(link, context) {
   const result = resolveMarkdownLink(link.href, link.baseDir, link.currentPath);
+
   if (result.status === "unsupported") {
     return false;
   }
+
   if (result.status === "file") {
     void context.navigate.push(context.documentRoute, { path: result.path });
+
     return true;
   }
+
   const relative = path.relative(link.baseDir, result.path);
+
   const target =
     relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)
       ? result.path
       : relative || ".";
+
   context.command.toast?.toast({
     level: "warning",
     message: `${result.status === "missing" ? "File not found" : "Not a file"}: ${target}`,
   });
+
   return true;
 };
 
@@ -54,9 +61,12 @@ export const runLinkHandlers = function runLinkHandlers(
       return true;
     }
   }
+
   if (localFileLinkHandler(link, context)) {
     return true;
   }
+
   context.command.toast?.toast({ level: "warning", message: `Unsupported link: ${link.href}` });
+
   return true;
 };

package/src/markdown-links.ts

@@ -19,39 +19,53 @@ export const resolveMarkdownLink = function resolveMarkdownLink(
 ): LinkResolution {
   try {
     const decoded = decodeURIComponent(href);
+
     if (/[\p{Cc}\\]/u.test(decoded)) {
       return { status: "unsupported" };
     }
+
     const target = href.trim();
+
     if (!target || target.startsWith("//")) {
       return { status: "unsupported" };
     }
+
     const [rawPath] = target.split("#", 1);
+
     if (rawPath.includes("?")) {
       return { status: "unsupported" };
     }
+
     let path: string;
+
     if (/^[a-zA-Z][a-zA-Z\d+.-]*:/u.test(rawPath)) {
       // Check the authority before URL normalizes localhost into an empty host.
       if (!/^file:\/\/\//iu.test(rawPath)) {
         return { status: "unsupported" };
       }
+
       const url = new URL(rawPath);
+
       if (url.hostname || url.search) {
         return { status: "unsupported" };
       }
+
       path = fileURLToPath(url);
     } else {
       path = rawPath
         ? nodePath.resolve(baseDir, decodeURIComponent(rawPath))
         : (currentPath ?? baseDir);
     }
+
     const absolute = nodePath.resolve(path);
+
     try {
       const stat = statSync(absolute);
+
       if (stat.isFile()) {
         return { path: absolute, status: "file" };
       }
+
       return stat.isDirectory()
         ? { path: absolute, status: "directory" }
         : { status: "unsupported" };
@@ -82,8 +96,10 @@ const collect = (tokens: Token[], links: MarkdownLink[]): void => {
     }
   }
 };
+
 export const markdownLinks = function markdownLinks(line: string): MarkdownLink[] {
   const links: MarkdownLink[] = [];
   collect(Lexer.lexInline(line), links);
+
   return links;
 };

package/src/outline/markdown-outline.ts

@@ -0,0 +1,48 @@
+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);
+};