@tooee/view 0.7.3 → 0.9.0

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

@@ -3,12 +3,12 @@ import type { TextBufferRenderable } from "@opentui/core";
 import { MarkdownView, flattenMarkdown, getFlatBlockText } from "@tooee/renderers";
 import type { CodeBlockRenderer, FlatBlock } from "@tooee/renderers";
 import { useBuildCommandContext, useCommand } from "@tooee/commands";
-import { useDocumentController } from "@tooee/shell";
 import type { DocumentRowAdapter } from "@tooee/shell";
 import type { MarkdownContent, MarkdownLinkActivateHandler } from "../../types.js";
-import { useContentCommands } from "../../hooks/use-content-commands.js";
+import { useContentDocument } from "../../hooks/use-content-document.js";
 import { ViewScreen } from "../view-screen.js";
 import type { SubviewProps } from "./types.js";
+import type { ReactNode } from "react";
 
 interface MarkdownSubviewProps extends SubviewProps {
   content: MarkdownContent;
@@ -36,26 +36,28 @@ export const MarkdownSubview = function MarkdownSubview({
   decorations,
   actions,
   ...screen
-}: MarkdownSubviewProps): React.ReactNode {
+}: MarkdownSubviewProps): ReactNode {
   const textContent = content.markdown;
   const lineCount = useMemo(() => textContent.split("\n").length, [textContent]);
   const blocks = useMemo(() => flattenMarkdown(content.markdown), [content.markdown]);
 
-  const { showLineNumbers } = useContentCommands({ content, textContent });
+  const { document, showLineNumbers, statusItems } = useContentDocument<FlatBlock>(
+    blocks,
+    MARKDOWN_BLOCK_ADAPTER,
+    { actions, content, decorations, textContent },
+    {
+      multiSelect: true,
+      statusItems: [
+        { label: "Format:", value: content.format },
+        { label: "Lines:", value: String(lineCount) },
+      ],
+    },
+  );
   const buildCommandContext = useBuildCommandContext();
   const handleLinkActivate = onLinkActivate
-    ? (href: string): unknown => onLinkActivate(href, buildCommandContext())
+    ? (href: string) => onLinkActivate(href, buildCommandContext())
     : undefined;
 
-  const document = useDocumentController<FlatBlock>({
-    adapter: MARKDOWN_BLOCK_ADAPTER,
-    // The controller projects the screen's actions onto menu entries at open time.
-    contextMenu: actions,
-    decorations,
-    multiSelect: true,
-    rows: blocks,
-  });
-
   const hScrollableBlocksRef = useRef<Map<number, TextBufferRenderable>>(new Map());
   const cursorScrollable = () =>
     document.activeIndex === null
@@ -88,14 +90,6 @@ export const MarkdownSubview = function MarkdownSubview({
     when: () => cursorScrollable() !== undefined,
   });
 
-  const statusItems = useMemo(
-    () => [
-      { label: "Format:", value: content.format },
-      { label: "Lines:", value: String(lineCount) },
-    ],
-    [content.format, lineCount],
-  );
-
   return (
     <ViewScreen
       content={content}

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

@@ -1,84 +1,44 @@
 import { useMemo } from "react";
-import { Table } from "@tooee/renderers";
+import { Table, formatTableCell } from "@tooee/renderers";
 import type { TableRow } from "@tooee/renderers";
-import { useDocumentController } from "@tooee/shell";
 import { getTextContent } from "../../types.js";
 import type { TableContent } from "../../types.js";
-import { useContentCommands } from "../../hooks/use-content-commands.js";
+import { useContentDocument } from "../../hooks/use-content-document.js";
 import { ViewScreen } from "../view-screen.js";
 import type { SubviewProps } from "./types.js";
+import type { ReactNode } from "react";
 
 interface TableSubviewProps extends SubviewProps {
   content: TableContent;
 }
 
-const stringifyRowCell = function stringifyRowCell(value: unknown): string {
-  if (value === null || value === undefined) {
-    return "";
-  }
-  if (typeof value === "string") {
-    return value;
-  }
-  if (typeof value === "number" || typeof value === "boolean") {
-    return String(value);
-  }
-  if (typeof value === "string") {
-    return value;
-  }
-  if (
-    typeof value === "number" ||
-    typeof value === "bigint" ||
-    typeof value === "boolean" ||
-    typeof value === "symbol"
-  ) {
-    return value.toString();
-  }
-  if (value === null || value === undefined) {
-    return String(value);
-  }
-  if (typeof value === "function") {
-    return Function.prototype.toString.call(value);
-  }
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return Array.isArray(value) ? value.join(",") : Object.prototype.toString.call(value);
-  }
-};
-
 export const TableSubview = function TableSubview({
   content,
   decorations,
   actions,
   ...screen
-}: TableSubviewProps): React.ReactNode {
+}: TableSubviewProps): ReactNode {
   const textContent = useMemo(() => getTextContent(content), [content]);
-  const { showLineNumbers } = useContentCommands({ content, textContent });
-
   const { columns, rows } = content;
   const adapter = useMemo(
     () => ({
       getText: (row: TableRow) =>
-        columns.map((column) => stringifyRowCell(row[column.key])).join("\t"),
+        columns.map((column) => formatTableCell(row[column.key])).join("\t"),
     }),
     [columns],
   );
-  const document = useDocumentController<TableRow>({
-    adapter,
-    // The controller projects the screen's actions onto menu entries at open time.
-    contextMenu: actions,
-    decorations,
-    multiSelect: true,
+  const { document, showLineNumbers, statusItems } = useContentDocument<TableRow>(
     rows,
-  });
-
-  const statusItems = useMemo(
-    () => [
-      { label: "Format:", value: content.format },
-      { label: "Rows:", value: String(rows.length) },
-      { label: "Cols:", value: String(columns.length) },
-    ],
-    [content.format, rows.length, columns.length],
+    adapter,
+    { actions, content, decorations, textContent },
+    {
+      multiSelect: true,
+      statusItems: [
+        { label: "Format:", value: content.format },
+        { label: "Rows:", value: String(rows.length) },
+        { label: "Cols:", value: String(columns.length) },
+      ],
+    },
   );
 
   return (

package/src/components/view-state.tsx

@@ -1,4 +1,5 @@
 import { useQuitCommand } from "@tooee/shell";
+import type { ReactNode } from "react";
 
 interface ViewStateProps {
   message: string;
@@ -6,7 +7,7 @@ interface ViewStateProps {
 }
 
 /** A non-document view state that preserves the viewer's normal quit command. */
-export const ViewState = function ViewState({ message, color }: ViewStateProps): React.ReactNode {
+export const ViewState = function ViewState({ message, color }: ViewStateProps): ReactNode {
   useQuitCommand();
 
   return (

package/src/content-loader-store.ts

@@ -2,6 +2,8 @@ import { createStore } from "@xstate/store";
 import type { MarkSet } from "@tooee/marks";
 import type { AnyContent, Content, ContentChunk, ContentFormat } from "./types.js";
 
+type ContentProviderResult = AnyContent | Promise<AnyContent> | AsyncIterable<ContentChunk>;
+
 export type ContentLoaderStatus = "idle" | "loading" | "streaming" | "ready" | "error";
 
 export interface ContentLoaderContext {
@@ -30,11 +32,12 @@ export type ContentLoaderEvents = {
 };
 
 export const isAsyncIterable = function isAsyncIterable(
-  value: unknown,
+  value: ContentProviderResult,
 ): value is AsyncIterable<ContentChunk> {
   return (
     value !== null &&
     value !== undefined &&
+    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- provider result boundary distinguishes the documented async-iterable source from content and promises
     typeof value === "object" &&
     Symbol.asyncIterator in value
   );
@@ -69,11 +72,11 @@ const ensureContentFormat = function ensureContentFormat<F extends ContentFormat
   title?: string,
 ): Extract<Content, { format: F }> {
   if (!current || current.format !== format) {
-    // Deferred(lint-sweep): add schema-based validation for custom and streamed content formats.
+    // SAFETY: createEmptyContent returns the built-in content variant selected by the same format.
     // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- format-dependent content is trusted at this provider boundary
     return createEmptyContent(format, title) as Extract<Content, { format: F }>;
   }
-  // Deferred(lint-sweep): add schema-based validation for custom and streamed content formats.
+  // SAFETY: The equality guard narrows current to the built-in content variant selected by format.
   // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the provider contract supplies the matching format
   return current as Extract<Content, { format: F }>;
 };
@@ -117,8 +120,8 @@ export const applyContentChunk = function applyContentChunk(
   }
 };
 
-export const normalizeError = function normalizeError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
+export const normalizeError = function normalizeError(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
 };
 
 export const createContentLoaderStore = function createContentLoaderStore() {

package/src/default-provider.ts

@@ -7,10 +7,12 @@ export interface CreateProviderOptions {
   renderer?: ContentFormat;
 }
 
-const detectFormat = function detectFormat(filePath: string): {
+interface DetectedFileFormat {
   format: ContentFormat;
   language?: string;
-} {
+}
+
+const detectFormat = function detectFormat(filePath: string): DetectedFileFormat {
   const ext = filePath.split(".").pop()?.toLowerCase();
   if (ext === undefined || ext === "") {
     return { format: "text" };
@@ -36,36 +38,36 @@ const detectFormat = function detectFormat(filePath: string): {
     return { format: "markdown" };
   }
 
-  const codeExts: Record<string, string> = {
-    bash: "bash",
-    c: "c",
-    cpp: "cpp",
-    css: "css",
-    go: "go",
-    h: "c",
-    hpp: "cpp",
-    html: "html",
-    java: "java",
-    js: "javascript",
-    json: "json",
-    jsx: "javascript",
-    kt: "kotlin",
-    py: "python",
-    rb: "ruby",
-    rs: "rust",
-    sh: "bash",
-    sql: "sql",
-    swift: "swift",
-    toml: "toml",
-    ts: "typescript",
-    tsx: "typescript",
-    yaml: "yaml",
-    yml: "yaml",
-    zsh: "zsh",
-  };
-
-  const language = codeExts[ext];
-  if (typeof language === "string") {
+  const codeExts = new Map<string, string>([
+    ["bash", "bash"],
+    ["c", "c"],
+    ["cpp", "cpp"],
+    ["css", "css"],
+    ["go", "go"],
+    ["h", "c"],
+    ["hpp", "cpp"],
+    ["html", "html"],
+    ["java", "java"],
+    ["js", "javascript"],
+    ["json", "json"],
+    ["jsx", "javascript"],
+    ["kt", "kotlin"],
+    ["py", "python"],
+    ["rb", "ruby"],
+    ["rs", "rust"],
+    ["sh", "bash"],
+    ["sql", "sql"],
+    ["swift", "swift"],
+    ["toml", "toml"],
+    ["ts", "typescript"],
+    ["tsx", "typescript"],
+    ["yaml", "yaml"],
+    ["yml", "yaml"],
+    ["zsh", "zsh"],
+  ]);
+
+  const language = codeExts.get(ext);
+  if (language !== undefined) {
     return { format: "code", language };
   }
 

package/src/directory-view.tsx

@@ -7,6 +7,7 @@ import type { DirectoryEntry } from "./directory-provider.js";
 import type { AnyContent, ContentProvider } from "./types.js";
 import { createFileProvider } from "./default-provider.js";
 import { ViewState } from "./components/view-state.js";
+import type { ReactNode } from "react";
 
 const createDirectoryFileProvider = function createDirectoryFileProvider(
   entry: DirectoryEntry,
@@ -17,7 +18,8 @@ const createDirectoryFileProvider = function createDirectoryFileProvider(
   return {
     async load(): Promise<AnyContent> {
       const result = inner.load();
-      // Deferred(lint-sweep): add schema-based validation for custom and streamed content formats.
+      // SAFETY: createFileProvider owns this provider and its load method returns Content directly
+      // or through a Promise; it never returns the ContentProvider async-iterable arm.
       // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- file providers return external content at this boundary
       const content = result instanceof Promise ? await result : (result as AnyContent);
       return {
@@ -36,7 +38,7 @@ interface DirectoryViewProps {
 export const DirectoryView = function DirectoryView({
   dirPath,
   actions,
-}: DirectoryViewProps): React.ReactNode {
+}: DirectoryViewProps): ReactNode {
   const files = useMemo(() => listDirectoryFiles(dirPath), [dirPath]);
   const [currentIndex, setCurrentIndex] = useState(0);
 

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

@@ -8,6 +8,11 @@ interface UseContentCommandsParams {
   textContent: string;
 }
 
+/** View display state controlled by content-level commands. */
+export interface ContentCommandsResult {
+  showLineNumbers: boolean;
+}
+
 /**
  * The commands a content viewer owns on top of `DocumentScreen`: copying the
  * whole document and toggling the line-number gutter. Theme, quit, actions and
@@ -16,7 +21,7 @@ interface UseContentCommandsParams {
 export const useContentCommands = function useContentCommands({
   content,
   textContent,
-}: UseContentCommandsParams) {
+}: UseContentCommandsParams): ContentCommandsResult {
   const config = useConfig();
   const [showLineNumbers, setShowLineNumbers] = useState(config.view?.gutter ?? true);
 

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

@@ -0,0 +1,54 @@
+import type { ActionDefinition } from "@tooee/commands";
+import type { StatusBarItem } from "@tooee/layout";
+import type { DecorationLayer } from "@tooee/renderers";
+import { useDocumentController } from "@tooee/shell";
+import type { DocumentController, DocumentRowAdapter } from "@tooee/shell";
+import type { AnyContent } from "../types.js";
+import { useContentCommands } from "./use-content-commands.js";
+
+interface ContentDocumentProps {
+  actions?: ActionDefinition[];
+  content: AnyContent;
+  decorations: DecorationLayer[];
+  textContent: string;
+}
+
+interface ContentDocumentOptions<T> {
+  buildStatusItems?: (document: DocumentController<T>) => StatusBarItem[];
+  contextMenu?: boolean;
+  multiSelect: boolean;
+  preserveCursorByKey?: boolean;
+  statusItems?: StatusBarItem[];
+}
+
+/** Shared document state used by each built-in content subview. */
+export interface ContentDocumentResult<T> {
+  document: DocumentController<T>;
+  showLineNumbers: boolean;
+  statusItems: StatusBarItem[];
+}
+
+/** Build the command, controller, and status state shared by content subviews. */
+export const useContentDocument = function useContentDocument<T>(
+  rows: readonly T[],
+  adapter: DocumentRowAdapter<T>,
+  { actions, content, decorations, textContent }: ContentDocumentProps,
+  options: ContentDocumentOptions<T>,
+): ContentDocumentResult<T> {
+  const { showLineNumbers } = useContentCommands({ content, textContent });
+  const document = useDocumentController<T>({
+    adapter,
+    contextMenu: options.contextMenu === false ? false : actions,
+    decorations,
+    multiSelect: options.multiSelect,
+    preserveCursorByKey: options.preserveCursorByKey,
+    rows,
+  });
+  const statusItems = options.buildStatusItems?.(document) ??
+    options.statusItems ?? [
+      { label: "Format:", value: content.format },
+      { label: "Lines:", value: String(rows.length) },
+    ];
+
+  return { document, showLineNumbers, statusItems };
+};

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

@@ -1,6 +1,8 @@
 import { useCallback, useEffect, useMemo } from "react";
 import { useSelector } from "@xstate/store-react";
-import type { ContentProvider } from "../types.js";
+import type { AnyContent, ContentProvider } from "../types.js";
+import type { MarkSet } from "@tooee/marks";
+import type { ContentLoaderStatus } from "../content-loader-store.js";
 import {
   createContentLoaderStore,
   isAsyncIterable,
@@ -13,7 +15,19 @@ import {
   selectStreaming,
 } from "../content-loader-store.js";
 
-export const useContentLoader = function useContentLoader(contentProvider: ContentProvider) {
+/** Reactive state exposed by the content provider loader. */
+export interface ContentLoaderState {
+  content: AnyContent | null;
+  error: string | null;
+  providerMarks: MarkSet[];
+  reload: () => void;
+  status: ContentLoaderStatus;
+  streaming: boolean;
+}
+
+export const useContentLoader = function useContentLoader(
+  contentProvider: ContentProvider,
+): ContentLoaderState {
   const store = useMemo(createContentLoaderStore, []);
   const loadSeq = useSelector(store, (snapshot) => selectLoadSeq(snapshot.context));
 
@@ -37,7 +51,7 @@ export const useContentLoader = function useContentLoader(contentProvider: Conte
       void (async () => {
         try {
           while (true) {
-            // Deferred(lint-sweep): preserve sequential stream consumption for ordered backpressure.
+            // 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) {

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

@@ -27,7 +27,7 @@ export interface ViewCommandContext {
 
 declare module "@tooee/commands" {
   interface CommandContext {
-    view: ViewCommandContext;
+    view?: ViewCommandContext;
   }
 }
 
@@ -50,6 +50,18 @@ export interface CreateViewCommandContextOptions {
 
 export type ProvideViewCommandContextOptions = CreateViewCommandContextOptions;
 
+type ViewCommandContextInput =
+  | ProvideViewCommandContextOptions
+  | (() => ProvideViewCommandContextOptions);
+
+/** Resolve the hook's public eager-or-lazy option union at its boundary. */
+const resolveViewCommandContextOptions = function resolveViewCommandContextOptions(
+  options: ViewCommandContextInput,
+): ProvideViewCommandContextOptions {
+  // oxlint-disable-next-line anti-slop/no-runtime-typeof -- public hook boundary distinguishes the documented lazy options callback from eager options
+  return typeof options === "function" ? options() : options;
+};
+
 export const createViewCommandContext = function createViewCommandContext({
   content,
   format,
@@ -84,9 +96,9 @@ export const createViewCommandContext = function createViewCommandContext({
 };
 
 export const useProvideViewCommandContext = function useProvideViewCommandContext(
-  options: ProvideViewCommandContextOptions | (() => ProvideViewCommandContextOptions),
-) {
+  options: ViewCommandContextInput,
+): void {
   useProvideCommandContextKey("view", () =>
-    createViewCommandContext(typeof options === "function" ? options() : options),
+    createViewCommandContext(resolveViewCommandContextOptions(options)),
   );
 };

package/src/index.ts

@@ -20,6 +20,8 @@ export type {
   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,
@@ -44,3 +46,5 @@ export type {
 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

@@ -1,12 +1,19 @@
-import { launchCli } from "@tooee/shell";
+import { launchCli, runCliSession } from "@tooee/shell";
 import type { ActionDefinition } from "@tooee/commands";
 import type { CodeBlockRenderer } from "@tooee/renderers";
-import { View } from "./view.js";
+import { Outlet, RouterProvider } from "@tooee/router";
+import { createStandaloneRouter } from "./standalone-router.js";
+import type { LinkHandler } from "./link-handlers.js";
 import { DirectoryView } from "./directory-view.js";
 import type { ContentProvider, ContentRenderer } from "./types.js";
+import type { ReactNode } from "react";
 
 export interface ViewLaunchOptions {
   contentProvider: ContentProvider;
+  /** Source file for standalone local Markdown navigation; omitted for stdin. */
+  filePath?: string;
+  /** Synchronous handlers tried before local file navigation. */
+  linkHandlers?: readonly LinkHandler[];
   actions?: ActionDefinition[];
   renderers?: Record<string, ContentRenderer>;
   /**
@@ -23,18 +30,28 @@ export interface DirectoryLaunchOptions {
 }
 
 export const launch = async function launch(options: ViewLaunchOptions): Promise<void> {
-  await launchCli(
-    <View
-      contentProvider={options.contentProvider}
-      actions={options.actions}
-      renderers={options.renderers}
-      codeBlockRenderers={options.codeBlockRenderers}
-    />,
+  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}>
+        <Outlet />
+      </RouterProvider>
+    ),
+    {
+      stdinPolicy: "tty-if-piped",
+      stdoutPolicy: "tty-if-redirected",
+    },
   );
 };
 
 export const launchDirectory = async function launchDirectory(
   options: DirectoryLaunchOptions,
 ): Promise<void> {
-  await launchCli(<DirectoryView dirPath={options.dirPath} actions={options.actions} />);
+  await launchCli(<DirectoryView dirPath={options.dirPath} actions={options.actions} />, {
+    stdoutPolicy: "tty-if-redirected",
+  });
 };

package/src/link-handlers.ts

@@ -0,0 +1,60 @@
+import path from "node:path";
+import type { CommandContext } from "@tooee/commands";
+import type { NavigateHandle, RouteDefinition } from "@tooee/router";
+import { resolveMarkdownLink } from "./markdown-links.js";
+
+export interface LinkTarget {
+  href: string;
+  /** Directory that relative targets resolve against. */
+  baseDir: string;
+  /** Source document for fragment-only links. */
+  currentPath?: string;
+}
+
+export interface LinkHandlerContext {
+  navigate: NavigateHandle;
+  documentRoute: RouteDefinition<{ path?: string }>;
+  command: CommandContext;
+}
+
+/** Decide synchronously: true consumes the link, false tries the next handler. */
+export type LinkHandler = (link: LinkTarget, context: LinkHandlerContext) => boolean;
+
+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;
+};
+
+export const runLinkHandlers = function runLinkHandlers(
+  handlers: readonly LinkHandler[],
+  link: LinkTarget,
+  context: LinkHandlerContext,
+): boolean {
+  for (const handler of handlers) {
+    // oxlint-disable-next-line typescript/no-unnecessary-boolean-literal-compare -- preserve exact-true consumption for JavaScript callers too
+    if (handler(link, context) === true) {
+      return true;
+    }
+  }
+  if (localFileLinkHandler(link, context)) {
+    return true;
+  }
+  context.command.toast?.toast({ level: "warning", message: `Unsupported link: ${link.href}` });
+  return true;
+};