react-native-nitro-markdown 0.4.3 → 0.5.1

package/src/markdown.tsx

@@ -1,4 +1,6 @@
 import {
+  memo,
+  useCallback,
   useEffect,
   useMemo,
   type FC,
@@ -10,8 +12,12 @@ import {
   StyleSheet,
   View,
   Text,
+  FlatList,
   Platform,
+  type ListRenderItemInfo,
+  type FlatListProps,
   type StyleProp,
+  type TextStyle,
   type ViewStyle,
 } from "react-native";
 import {
@@ -48,8 +54,201 @@ import {
   type NodeStyleOverrides,
   type StylingStrategy,
 } from "./theme";
+import type { CodeHighlighter } from "./utils/code-highlight";
 
 const baseStylesCache = new WeakMap<MarkdownTheme, BaseStyles>();
+const parseAstCache = new Map<string, MarkdownNode>();
+const MAX_PARSE_CACHE_ENTRIES = 32;
+const MAX_CACHEABLE_TEXT_LENGTH = 24_000;
+
+export type AstTransform = (ast: MarkdownNode) => MarkdownNode;
+export type MarkdownVirtualizationOptions = Pick<
+  FlatListProps<MarkdownNode>,
+  | "initialNumToRender"
+  | "maxToRenderPerBatch"
+  | "windowSize"
+  | "updateCellsBatchingPeriod"
+  | "removeClippedSubviews"
+>;
+
+export type MarkdownPlugin = {
+  /**
+   * Optional plugin name used for diagnostics and debugging.
+   */
+  name?: string;
+  /**
+   * Optional plugin version metadata for diagnostics.
+   */
+  version?: string | number;
+  /**
+   * Execution priority. Higher values run first (default: 0).
+   */
+  priority?: number;
+  /**
+   * Optional text preprocessor executed before native parsing.
+   * Should return a full markdown string.
+   */
+  beforeParse?: (markdown: string) => string;
+  /**
+   * Optional AST postprocessor executed after native parsing.
+   */
+  afterParse?: AstTransform;
+};
+
+const isMarkdownNode = (value: unknown): value is MarkdownNode => {
+  if (typeof value !== "object" || value === null) return false;
+  return typeof Reflect.get(value, "type") === "string";
+};
+
+const warnInDev = (message: string, error?: unknown): void => {
+  if (typeof __DEV__ === "undefined" || !__DEV__) return;
+
+  const runtimeConsole = Reflect.get(globalThis, "console");
+  if (
+    typeof runtimeConsole === "object" &&
+    runtimeConsole !== null &&
+    "warn" in runtimeConsole &&
+    typeof runtimeConsole.warn === "function"
+  ) {
+    runtimeConsole.warn(message, error);
+  }
+};
+
+const cloneMarkdownNode = (node: MarkdownNode): MarkdownNode => {
+  return {
+    ...node,
+    children: node.children?.map(cloneMarkdownNode),
+  };
+};
+
+const getParserOptionsKey = (options?: ParserOptions): string => {
+  if (!options) return "gfm:default|math:default";
+
+  const gfm = options.gfm === undefined ? "default" : options.gfm ? "1" : "0";
+  const math =
+    options.math === undefined ? "default" : options.math ? "1" : "0";
+  return `gfm:${gfm}|math:${math}`;
+};
+
+const normalizeParserOptions = (
+  options?: ParserOptions,
+): ParserOptions | undefined => {
+  if (!options) return undefined;
+
+  const gfm = options.gfm;
+  const math = options.math;
+
+  if (gfm === undefined && math === undefined) {
+    return undefined;
+  }
+
+  return {
+    gfm,
+    math,
+  };
+};
+
+const parseWithNativeParser = (
+  text: string,
+  options?: ParserOptions,
+): MarkdownNode => {
+  if (options) {
+    return parseMarkdownWithOptions(text, options);
+  }
+  return parseMarkdown(text);
+};
+
+const getCachedParsedAst = (
+  text: string,
+  options?: ParserOptions,
+): MarkdownNode => {
+  if (text.length > MAX_CACHEABLE_TEXT_LENGTH) {
+    return parseWithNativeParser(text, options);
+  }
+
+  const cacheKey = `${getParserOptionsKey(options)}|${text}`;
+  const cachedNode = parseAstCache.get(cacheKey);
+  if (cachedNode) {
+    parseAstCache.delete(cacheKey);
+    parseAstCache.set(cacheKey, cachedNode);
+    return cloneMarkdownNode(cachedNode);
+  }
+
+  const parsedNode = parseWithNativeParser(text, options);
+  parseAstCache.set(cacheKey, parsedNode);
+  if (parseAstCache.size > MAX_PARSE_CACHE_ENTRIES) {
+    const oldestCacheKey = parseAstCache.keys().next().value;
+    if (typeof oldestCacheKey === "string") {
+      parseAstCache.delete(oldestCacheKey);
+    }
+  }
+
+  return cloneMarkdownNode(parsedNode);
+};
+
+const applyBeforeParsePlugins = (
+  markdown: string,
+  plugins?: MarkdownPlugin[],
+  onError?: (error: Error, phase: 'before-plugin', pluginName?: string) => void,
+): string => {
+  if (!plugins || plugins.length === 0) {
+    return markdown;
+  }
+
+  const sorted = [...plugins].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+  let nextMarkdown = markdown;
+  for (const plugin of sorted) {
+    if (!plugin.beforeParse) continue;
+
+    try {
+      const transformed = plugin.beforeParse(nextMarkdown);
+      if (typeof transformed === "string") {
+        nextMarkdown = transformed;
+      }
+    } catch (error) {
+      const pluginLabel = plugin.name ? ` (${plugin.name})` : "";
+      warnInDev(
+        `[react-native-nitro-markdown] plugin beforeParse${pluginLabel} threw; using previous markdown.`,
+        error,
+      );
+      onError?.(error instanceof Error ? error : new Error(String(error)), 'before-plugin', plugin.name);
+    }
+  }
+
+  return nextMarkdown;
+};
+
+const applyAfterParsePlugins = (
+  ast: MarkdownNode,
+  plugins?: MarkdownPlugin[],
+  onError?: (error: Error, phase: 'after-plugin', pluginName?: string) => void,
+): MarkdownNode => {
+  if (!plugins || plugins.length === 0) {
+    return ast;
+  }
+
+  const sorted = [...plugins].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+  let nextAst = ast;
+  for (const plugin of sorted) {
+    if (!plugin.afterParse) continue;
+
+    try {
+      const transformed = plugin.afterParse(nextAst);
+      if (isMarkdownNode(transformed)) {
+        nextAst = transformed;
+      }
+    } catch (error) {
+      const pluginLabel = plugin.name ? ` (${plugin.name})` : "";
+      warnInDev(
+        `[react-native-nitro-markdown] plugin afterParse${pluginLabel} threw; using previous AST.`,
+        error,
+      );
+      onError?.(error instanceof Error ? error : new Error(String(error)), 'after-plugin', plugin.name);
+    }
+  }
+
+  return nextAst;
+};
 
 export type MarkdownProps = {
   /**
@@ -60,6 +259,20 @@ export type MarkdownProps = {
    * Parser options to enable GFM or Math support.
    */
   options?: ParserOptions;
+  /**
+   * Optional parser plugins for preprocessing and AST postprocessing.
+   */
+  plugins?: MarkdownPlugin[];
+  /**
+   * Optional pre-parsed AST.
+   * When provided, native parse is skipped and this tree is rendered instead.
+   */
+  sourceAst?: MarkdownNode;
+  /**
+   * Optional transform applied after parsing and before rendering.
+   * The transformed AST is also returned in `onParseComplete`.
+   */
+  astTransform?: AstTransform;
   /**
    * Callback fired when parsing begins.
    */
@@ -72,6 +285,13 @@ export type MarkdownProps = {
     ast: MarkdownNode;
     text: string;
   }) => void;
+  /**
+   * Called when a parse error or plugin error occurs.
+   * @param error - The thrown error.
+   * @param phase - Where the error occurred.
+   * @param pluginName - The plugin name, if applicable.
+   */
+  onError?: (error: Error, phase: 'parse' | 'before-plugin' | 'after-plugin', pluginName?: string) => void;
   /**
    * Custom renderers for specific markdown node types.
    * Each renderer receives { node, children, Renderer } plus type-specific props.
@@ -107,11 +327,43 @@ export type MarkdownProps = {
    * Return false to prevent the default openURL behavior.
    */
   onLinkPress?: LinkPressHandler;
+  /**
+   * Enables top-level block virtualization for very large markdown documents.
+   * Best used when Markdown is the primary scroll container on screen.
+   * - `true`: always virtualize when block threshold is met
+   * - `"auto"`: virtualize only when threshold is met (recommended for large docs)
+   * - `false`: disable virtualization (default)
+   */
+  virtualize?: boolean | "auto";
+  /**
+   * Minimum number of top-level blocks before virtualization is activated.
+   * Helps avoid FlatList overhead on small documents.
+   */
+  virtualizationMinBlocks?: number;
+  /**
+   * Optional FlatList tuning for virtualization.
+   */
+  virtualization?: MarkdownVirtualizationOptions;
+  /**
+   * Optional configuration for the table renderer.
+   */
+  tableOptions?: {
+    minColumnWidth?: number;
+    measurementStabilizeMs?: number;
+  };
+  /**
+   * Enable built-in syntax highlighting for code blocks.
+   * Pass `true` to use the built-in tokenizer, or a custom highlighter function.
+   */
+  highlightCode?: boolean | CodeHighlighter;
 };
 
 export const Markdown: FC<MarkdownProps> = ({
   children,
   options,
+  plugins,
+  sourceAst,
+  astTransform,
   renderers = {},
   theme: userTheme,
   styles: nodeStyles,
@@ -120,41 +372,82 @@ export const Markdown: FC<MarkdownProps> = ({
   onParsingInProgress,
   onParseComplete,
   onLinkPress,
+  onError,
+  virtualize = false,
+  virtualizationMinBlocks = 40,
+  virtualization,
+  tableOptions,
+  highlightCode,
 }) => {
+  const parserOptionGfm = options?.gfm;
+  const parserOptionMath = options?.math;
+
   const parseResult = useMemo(() => {
     try {
-      let ast: MarkdownNode;
-      if (options) {
-        ast = parseMarkdownWithOptions(children, options);
-      } else {
-        ast = parseMarkdown(children);
+      const markdownToParse = applyBeforeParsePlugins(children, plugins, onError ? (e, phase, name) => onError(e, phase, name) : undefined);
+      const parserOptions = normalizeParserOptions({
+        gfm: parserOptionGfm,
+        math: parserOptionMath,
+      });
+      let parsedAst = sourceAst
+        ? cloneMarkdownNode(sourceAst)
+        : getCachedParsedAst(markdownToParse, parserOptions);
+      parsedAst = applyAfterParsePlugins(parsedAst, plugins, onError ? (e, phase, name) => onError(e, phase, name) : undefined);
+
+      let ast = parsedAst;
+      if (astTransform) {
+        try {
+          const nextAst = astTransform(parsedAst);
+          if (isMarkdownNode(nextAst)) {
+            ast = nextAst;
+          }
+        } catch (error) {
+          warnInDev(
+            "[react-native-nitro-markdown] astTransform threw; falling back to parsed AST.",
+            error,
+          );
+          ast = parsedAst;
+        }
       }
 
       return {
         ast,
-        text: getFlattenedText(ast),
       };
-    } catch {
+    } catch (parseError) {
+      onError?.(parseError instanceof Error ? parseError : new Error(String(parseError)), 'parse');
       return {
         ast: null,
-        text: "",
       };
     }
-  }, [children, options]);
+  }, [
+    children,
+    parserOptionGfm,
+    parserOptionMath,
+    plugins,
+    sourceAst,
+    astTransform,
+    onError,
+  ]);
 
   useEffect(() => {
     onParsingInProgress?.();
-  }, [children, options, onParsingInProgress]);
+  }, [
+    children,
+    parserOptionGfm,
+    parserOptionMath,
+    plugins,
+    onParsingInProgress,
+  ]);
 
   useEffect(() => {
-    if (!parseResult.ast) return;
+    if (!parseResult.ast || !onParseComplete) return;
 
-    onParseComplete?.({
+    onParseComplete({
       raw: children,
       ast: parseResult.ast,
-      text: parseResult.text,
+      text: getFlattenedText(parseResult.ast),
     });
-  }, [children, onParseComplete, parseResult.ast, parseResult.text]);
+  }, [children, onParseComplete, parseResult.ast]);
 
   const theme = useMemo(() => {
     const base =
@@ -165,6 +458,43 @@ export const Markdown: FC<MarkdownProps> = ({
   }, [userTheme, stylingStrategy]);
 
   const baseStyles = getBaseStyles(theme);
+  const contextValue = useMemo(
+    () => ({
+      renderers,
+      theme,
+      styles: nodeStyles,
+      stylingStrategy,
+      onLinkPress,
+      tableOptions,
+      highlightCode,
+    }),
+    [renderers, theme, nodeStyles, stylingStrategy, onLinkPress, tableOptions, highlightCode],
+  );
+
+  const topLevelBlocks =
+    parseResult.ast?.type === "document"
+      ? (parseResult.ast.children ?? [])
+      : parseResult.ast
+        ? [parseResult.ast]
+        : [];
+  const shouldVirtualizeBySetting =
+    virtualize === true ||
+    (virtualize === "auto" && topLevelBlocks.length >= virtualizationMinBlocks);
+  const shouldVirtualize =
+    parseResult.ast !== null && shouldVirtualizeBySetting;
+
+  const keyExtractor = useCallback((node: MarkdownNode, index: number) => {
+    const beg = typeof node.beg === "number" ? node.beg : index;
+    const end = typeof node.end === "number" ? node.end : index;
+    return `${node.type}:${beg}:${end}:${index}`;
+  }, []);
+
+  const renderVirtualizedItem = useCallback(
+    ({ item }: ListRenderItemInfo<MarkdownNode>): ReactElement => (
+      <NodeRenderer node={item} depth={0} inListItem={false} />
+    ),
+    [],
+  );
 
   if (!parseResult.ast) {
     return (
@@ -175,17 +505,28 @@ export const Markdown: FC<MarkdownProps> = ({
   }
 
   return (
-    <MarkdownContext.Provider
-      value={{
-        renderers,
-        theme,
-        styles: nodeStyles,
-        stylingStrategy,
-        onLinkPress,
-      }}
-    >
+    <MarkdownContext.Provider value={contextValue}>
       <View style={[baseStyles.container, style]}>
-        <NodeRenderer node={parseResult.ast} depth={0} inListItem={false} />
+        {shouldVirtualize ? (
+          <FlatList
+            data={topLevelBlocks}
+            renderItem={renderVirtualizedItem}
+            keyExtractor={keyExtractor}
+            style={baseStyles.virtualizedList}
+            initialNumToRender={virtualization?.initialNumToRender ?? 12}
+            maxToRenderPerBatch={virtualization?.maxToRenderPerBatch ?? 12}
+            windowSize={virtualization?.windowSize ?? 10}
+            updateCellsBatchingPeriod={
+              virtualization?.updateCellsBatchingPeriod ?? 16
+            }
+            removeClippedSubviews={
+              virtualization?.removeClippedSubviews ?? true
+            }
+            showsVerticalScrollIndicator={false}
+          />
+        ) : (
+          <NodeRenderer node={parseResult.ast} depth={0} inListItem={false} />
+        )}
       </View>
     </MarkdownContext.Provider>
   );
@@ -206,7 +547,7 @@ const isInline = (type: MarkdownNode["type"]): boolean => {
   );
 };
 
-const NodeRenderer: FC<NodeRendererProps> = ({
+const NodeRendererComponent: FC<NodeRendererProps> = ({
   node,
   depth,
   inListItem,
@@ -341,7 +682,9 @@ const NodeRenderer: FC<NodeRendererProps> = ({
     }
   }
 
-  const nodeStyleOverride = nodeStyles?.[node.type];
+  const nodeStyleOverride = nodeStyles?.[node.type] as
+    | (ViewStyle & TextStyle)
+    | undefined;
 
   switch (node.type) {
     case "document":
@@ -521,6 +864,15 @@ const NodeRenderer: FC<NodeRendererProps> = ({
   }
 };
 
+const NodeRenderer = memo(NodeRendererComponent, (previousProps, nextProps) => {
+  return (
+    previousProps.node === nextProps.node &&
+    previousProps.depth === nextProps.depth &&
+    previousProps.inListItem === nextProps.inListItem &&
+    previousProps.parentIsText === nextProps.parentIsText
+  );
+}) as FC<NodeRendererProps>;
+
 type BaseStyles = ReturnType<typeof createBaseStyles>;
 
 const getBaseStyles = (theme: MarkdownTheme): BaseStyles => {
@@ -537,6 +889,9 @@ const createBaseStyles = (theme: MarkdownTheme) =>
     container: {
       flex: 1,
     },
+    virtualizedList: {
+      flex: 1,
+    },
     document: {
       flex: 1,
     },

package/src/renderers/code.tsx

@@ -11,6 +11,7 @@ import {
 import { getTextContent } from "../headless";
 import { useMarkdownContext } from "../MarkdownContext";
 import type { MarkdownNode } from "../headless";
+import { defaultHighlighter, type HighlightedToken } from "../utils/code-highlight";
 
 type CodeBlockProps = {
   language?: string;
@@ -25,7 +26,14 @@ export const CodeBlock: FC<CodeBlockProps> = ({
   node,
   style,
 }) => {
-  const { theme } = useMarkdownContext();
+  const ctx = useMarkdownContext();
+  const { theme } = ctx;
+
+  const highlighter = ctx.highlightCode === true
+    ? defaultHighlighter
+    : typeof ctx.highlightCode === 'function'
+      ? ctx.highlightCode
+      : null;
 
   const displayContent = content ?? (node ? getTextContent(node) : "");
 
@@ -70,8 +78,29 @@ export const CodeBlock: FC<CodeBlockProps> = ({
       {showLanguage ? (
         <Text style={styles.codeLanguage}>{language}</Text>
       ) : null}
-      <ScrollView horizontal showsHorizontalScrollIndicator={false}>
-        <Text style={styles.codeBlockText}>{displayContent}</Text>
+      <ScrollView
+        horizontal
+        showsHorizontalScrollIndicator={false}
+        bounces={false}
+      >
+        {highlighter && language ? (
+          <Text style={styles.codeBlockText} selectable>
+            {highlighter(language, displayContent).map((token: HighlightedToken, i: number) => {
+              const tokenColor = ctx.theme.colors.codeTokenColors?.[token.type];
+              return tokenColor ? (
+                <Text key={i} style={{ color: tokenColor }}>
+                  {token.text}
+                </Text>
+              ) : (
+                <Text key={i}>{token.text}</Text>
+              );
+            })}
+          </Text>
+        ) : (
+          <Text style={styles.codeBlockText} selectable>
+            {displayContent}
+          </Text>
+        )}
       </ScrollView>
     </View>
   );

package/src/renderers/table/cell-content.tsx

@@ -0,0 +1,38 @@
+import { type FC, type ComponentType } from "react";
+import { View, Text, type StyleProp, type TextStyle } from "react-native";
+import type { MarkdownNode } from "../../headless";
+import type { NodeRendererProps } from "../../MarkdownContext";
+
+type CellContentProps = {
+  node: MarkdownNode;
+  Renderer: ComponentType<NodeRendererProps>;
+  styles: {
+    cellContentWrapper: object;
+  };
+  textStyle?: StyleProp<TextStyle>;
+};
+
+export const CellContent: FC<CellContentProps> = ({
+  node,
+  Renderer,
+  styles,
+  textStyle,
+}) => {
+  if (!node.children || node.children.length === 0) {
+    return <Text style={textStyle}>{node.content ?? ""}</Text>;
+  }
+
+  return (
+    <View style={styles.cellContentWrapper}>
+      {node.children.map((child, idx) => (
+        <Renderer
+          key={idx}
+          node={child}
+          depth={0}
+          inListItem={false}
+          parentIsText={false}
+        />
+      ))}
+    </View>
+  );
+};