react-native-nitro-markdown 0.4.2 → 0.5.0

package/src/markdown.tsx

@@ -1,18 +1,21 @@
 import {
-  defaultMarkdownTheme,
-  minimalMarkdownTheme,
-  mergeThemes,
-  type MarkdownTheme,
-  type PartialMarkdownTheme,
-  type NodeStyleOverrides,
-  type StylingStrategy,
-} from "./theme";
-import { useMemo, type ReactNode, type FC, Fragment } from "react";
+  memo,
+  useCallback,
+  useEffect,
+  useMemo,
+  type FC,
+  Fragment,
+  type ReactElement,
+  type ReactNode,
+} from "react";
 import {
   StyleSheet,
   View,
   Text,
+  FlatList,
   Platform,
+  type ListRenderItemInfo,
+  type FlatListProps,
   type StyleProp,
   type ViewStyle,
 } from "react-native";
@@ -28,21 +31,214 @@ import {
   MarkdownContext,
   useMarkdownContext,
   type CustomRenderers,
+  type LinkPressHandler,
   type NodeRendererProps,
 } from "./MarkdownContext";
-
-import { Heading } from "./renderers/heading";
-import { Paragraph } from "./renderers/paragraph";
-import { Link } from "./renderers/link";
 import { Blockquote } from "./renderers/blockquote";
-import { HorizontalRule } from "./renderers/horizontal-rule";
 import { CodeBlock, InlineCode } from "./renderers/code";
-import { List, ListItem, TaskListItem } from "./renderers/list";
-import { TableRenderer } from "./renderers/table";
+import { Heading } from "./renderers/heading";
+import { HorizontalRule } from "./renderers/horizontal-rule";
 import { Image } from "./renderers/image";
+import { Link } from "./renderers/link";
+import { List, ListItem, TaskListItem } from "./renderers/list";
 import { MathInline, MathBlock } from "./renderers/math";
+import { Paragraph } from "./renderers/paragraph";
+import { TableRenderer } from "./renderers/table";
+import {
+  defaultMarkdownTheme,
+  minimalMarkdownTheme,
+  mergeThemes,
+  type MarkdownTheme,
+  type PartialMarkdownTheme,
+  type NodeStyleOverrides,
+  type StylingStrategy,
+} from "./theme";
 
-export interface MarkdownProps {
+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;
+  /**
+   * 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[],
+): string => {
+  if (!plugins || plugins.length === 0) {
+    return markdown;
+  }
+
+  let nextMarkdown = markdown;
+  for (const plugin of plugins) {
+    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,
+      );
+    }
+  }
+
+  return nextMarkdown;
+};
+
+const applyAfterParsePlugins = (
+  ast: MarkdownNode,
+  plugins?: MarkdownPlugin[],
+): MarkdownNode => {
+  if (!plugins || plugins.length === 0) {
+    return ast;
+  }
+
+  let nextAst = ast;
+  for (const plugin of plugins) {
+    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,
+      );
+    }
+  }
+
+  return nextAst;
+};
+
+export type MarkdownProps = {
   /**
    * The markdown string to parse and render.
    */
@@ -51,6 +247,20 @@ export interface 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.
    */
@@ -93,11 +303,36 @@ export interface MarkdownProps {
    * Optional style for the container view.
    */
   style?: StyleProp<ViewStyle>;
-}
+  /**
+   * Optional link press handler.
+   * 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;
+};
 
 export const Markdown: FC<MarkdownProps> = ({
   children,
   options,
+  plugins,
+  sourceAst,
+  astTransform,
   renderers = {},
   theme: userTheme,
   styles: nodeStyles,
@@ -105,34 +340,78 @@ export const Markdown: FC<MarkdownProps> = ({
   style,
   onParsingInProgress,
   onParseComplete,
+  onLinkPress,
+  virtualize = false,
+  virtualizationMinBlocks = 40,
+  virtualization,
 }) => {
-  const ast = useMemo(() => {
-    try {
-      if (onParsingInProgress) {
-        onParsingInProgress();
-      }
+  const parserOptionGfm = options?.gfm;
+  const parserOptionMath = options?.math;
 
-      let result: MarkdownNode;
-      if (options) {
-        result = parseMarkdownWithOptions(children, options);
-      } else {
-        result = parseMarkdown(children);
-      }
-
-      if (onParseComplete) {
-        onParseComplete({
-          raw: children,
-          ast: result,
-          text: getFlattenedText(result),
-        });
+  const parseResult = useMemo(() => {
+    try {
+      const markdownToParse = applyBeforeParsePlugins(children, plugins);
+      const parserOptions = normalizeParserOptions({
+        gfm: parserOptionGfm,
+        math: parserOptionMath,
+      });
+      let parsedAst = sourceAst
+        ? cloneMarkdownNode(sourceAst)
+        : getCachedParsedAst(markdownToParse, parserOptions);
+      parsedAst = applyAfterParsePlugins(parsedAst, plugins);
+
+      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 result;
-    } catch (error) {
-      console.error("Failed to parse markdown:", error);
-      return null;
+      return {
+        ast,
+      };
+    } catch {
+      return {
+        ast: null,
+      };
     }
-  }, [children, options, onParsingInProgress, onParseComplete]);
+  }, [
+    children,
+    parserOptionGfm,
+    parserOptionMath,
+    plugins,
+    sourceAst,
+    astTransform,
+  ]);
+
+  useEffect(() => {
+    onParsingInProgress?.();
+  }, [
+    children,
+    parserOptionGfm,
+    parserOptionMath,
+    plugins,
+    onParsingInProgress,
+  ]);
+
+  useEffect(() => {
+    if (!parseResult.ast || !onParseComplete) return;
+
+    onParseComplete({
+      raw: children,
+      ast: parseResult.ast,
+      text: getFlattenedText(parseResult.ast),
+    });
+  }, [children, onParseComplete, parseResult.ast]);
 
   const theme = useMemo(() => {
     const base =
@@ -142,9 +421,44 @@ export const Markdown: FC<MarkdownProps> = ({
     return mergeThemes(base, userTheme);
   }, [userTheme, stylingStrategy]);
 
-  const baseStyles = useMemo(() => createBaseStyles(theme), [theme]);
+  const baseStyles = getBaseStyles(theme);
+  const contextValue = useMemo(
+    () => ({
+      renderers,
+      theme,
+      styles: nodeStyles,
+      stylingStrategy,
+      onLinkPress,
+    }),
+    [renderers, theme, nodeStyles, stylingStrategy, onLinkPress],
+  );
+
+  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 (!ast) {
+  if (!parseResult.ast) {
     return (
       <View style={[baseStyles.container, style]}>
         <Text style={baseStyles.errorText}>Error parsing markdown</Text>
@@ -153,11 +467,28 @@ export const Markdown: FC<MarkdownProps> = ({
   }
 
   return (
-    <MarkdownContext.Provider
-      value={{ renderers, theme, styles: nodeStyles, stylingStrategy }}
-    >
+    <MarkdownContext.Provider value={contextValue}>
       <View style={[baseStyles.container, style]}>
-        <NodeRenderer node={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>
   );
@@ -178,14 +509,14 @@ const isInline = (type: MarkdownNode["type"]): boolean => {
   );
 };
 
-const NodeRenderer: FC<NodeRendererProps> = ({
+const NodeRendererComponent: FC<NodeRendererProps> = ({
   node,
   depth,
   inListItem,
   parentIsText = false,
 }) => {
   const { renderers, theme, styles: nodeStyles } = useMarkdownContext();
-  const baseStyles = useMemo(() => createBaseStyles(theme), [theme]);
+  const baseStyles = getBaseStyles(theme);
 
   const renderChildren = (
     children?: MarkdownNode[],
@@ -308,7 +639,9 @@ const NodeRenderer: FC<NodeRendererProps> = ({
     };
 
     const result = customRenderer(enhancedProps);
-    if (result !== undefined) return <>{result}</>;
+    if (result !== undefined) {
+      return result as ReactElement | null;
+    }
   }
 
   const nodeStyleOverride = nodeStyles?.[node.type];
@@ -491,11 +824,34 @@ 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 => {
+  const cached = baseStylesCache.get(theme);
+  if (cached) return cached;
+
+  const created = createBaseStyles(theme);
+  baseStylesCache.set(theme, created);
+  return created;
+};
+
 const createBaseStyles = (theme: MarkdownTheme) =>
   StyleSheet.create({
     container: {
       flex: 1,
     },
+    virtualizedList: {
+      flex: 1,
+    },
     document: {
       flex: 1,
     },

package/src/renderers/blockquote.tsx

@@ -1,11 +1,11 @@
-import { ReactNode, useMemo, type FC } from "react";
+import { useMemo, type FC, type ReactNode } from "react";
 import { View, StyleSheet, type ViewStyle } from "react-native";
 import { useMarkdownContext } from "../MarkdownContext";
 
-interface BlockquoteProps {
+type BlockquoteProps = {
   children: ReactNode;
   style?: ViewStyle;
-}
+};
 
 export const Blockquote: FC<BlockquoteProps> = ({ children, style }) => {
   const { theme } = useMarkdownContext();
@@ -23,7 +23,7 @@ export const Blockquote: FC<BlockquoteProps> = ({ children, style }) => {
           borderRadius: theme.borderRadius.s,
         },
       }),
-    [theme]
+    [theme],
   );
 
   return <View style={[styles.blockquote, style]}>{children}</View>;

package/src/renderers/code.tsx

@@ -1,4 +1,4 @@
-import { ReactNode, useMemo, type FC } from "react";
+import { useMemo, type FC, type ReactNode } from "react";
 import {
   View,
   Text,
@@ -8,16 +8,16 @@ import {
   type ViewStyle,
   type TextStyle,
 } from "react-native";
+import { getTextContent } from "../headless";
 import { useMarkdownContext } from "../MarkdownContext";
 import type { MarkdownNode } from "../headless";
-import { getTextContent } from "../headless";
 
-interface CodeBlockProps {
+type CodeBlockProps = {
   language?: string;
   content?: string;
   node?: MarkdownNode;
   style?: ViewStyle;
-}
+};
 
 export const CodeBlock: FC<CodeBlockProps> = ({
   language,
@@ -60,27 +60,33 @@ export const CodeBlock: FC<CodeBlockProps> = ({
           ...(Platform.OS === "android" && { includeFontPadding: false }),
         },
       }),
-    [theme]
+    [theme],
   );
 
   const showLanguage = theme.showCodeLanguage && language;
 
   return (
     <View style={[styles.codeBlock, style]}>
-      {showLanguage && <Text style={styles.codeLanguage}>{language}</Text>}
-      <ScrollView horizontal showsHorizontalScrollIndicator={false}>
+      {showLanguage ? (
+        <Text style={styles.codeLanguage}>{language}</Text>
+      ) : null}
+      <ScrollView
+        horizontal
+        showsHorizontalScrollIndicator={false}
+        bounces={false}
+      >
         <Text style={styles.codeBlockText}>{displayContent}</Text>
       </ScrollView>
     </View>
   );
 };
 
-interface InlineCodeProps {
+type InlineCodeProps = {
   content?: string;
   node?: MarkdownNode;
   children?: ReactNode;
   style?: TextStyle;
-}
+};
 
 export const InlineCode: FC<InlineCodeProps> = ({
   content,
@@ -109,7 +115,7 @@ export const InlineCode: FC<InlineCodeProps> = ({
           ...(Platform.OS === "android" && { includeFontPadding: false }),
         },
       }),
-    [theme]
+    [theme],
   );
   return <Text style={[styles.codeInline, style]}>{displayContent}</Text>;
 };

package/src/renderers/heading.tsx

@@ -1,12 +1,12 @@
-import { ReactNode, useMemo, type FC } from "react";
+import { useMemo, type FC, type ReactNode } from "react";
 import { Text, StyleSheet, Platform, type TextStyle } from "react-native";
 import { useMarkdownContext } from "../MarkdownContext";
 
-interface HeadingProps {
+type HeadingProps = {
   level: number;
   children: ReactNode;
   style?: TextStyle;
-}
+};
 
 const ANDROID_SYSTEM_FONTS = new Set([
   "sans-serif",
@@ -71,7 +71,7 @@ export const Heading: FC<HeadingProps> = ({ level, children, style }) => {
           color: theme.colors.textMuted,
         },
       }),
-    [theme]
+    [headingWeight, theme],
   );
 
   const headingStyles = [

package/src/renderers/horizontal-rule.tsx

@@ -2,9 +2,9 @@ import { useMemo, type FC } from "react";
 import { View, StyleSheet, type ViewStyle } from "react-native";
 import { useMarkdownContext } from "../MarkdownContext";
 
-interface HorizontalRuleProps {
+type HorizontalRuleProps = {
   style?: ViewStyle;
-}
+};
 
 export const HorizontalRule: FC<HorizontalRuleProps> = ({ style }) => {
   const { theme } = useMarkdownContext();
@@ -17,7 +17,7 @@ export const HorizontalRule: FC<HorizontalRuleProps> = ({ style }) => {
           marginVertical: theme.spacing.xl,
         },
       }),
-    [theme]
+    [theme],
   );
   return <View style={[styles.horizontalRule, style]} />;
 };