react-native-enriched-markdown-scaffold 0.6.0-scaffold.4

package/src/types/MarkdownTextProps.ts

@@ -0,0 +1,253 @@
+import type { ColorValue, ViewProps, ViewStyle, TextStyle } from 'react-native';
+import type { MarkdownStyle, Md4cFlags } from './MarkdownStyle';
+import type {
+  LinkPressEvent,
+  LinkLongPressEvent,
+  TaskListItemPressEvent,
+} from './events';
+
+/**
+ * Public context menu item. Each item includes a JS-side `onPress` callback
+ * that is called when the user taps the item in the selection context menu.
+ */
+export interface ContextMenuItem {
+  text: string;
+  onPress: (event: {
+    text: string;
+    selection: { start: number; end: number };
+  }) => void;
+  icon?: string;
+  visible?: boolean;
+}
+
+export interface SelectionMenuConfig {
+  /**
+   * Shows the built-in "Copy as Markdown" action for text selections.
+   * @default true
+   */
+  copyAsMarkdown?: boolean;
+  /**
+   * Shows the built-in "Copy Image URL" action when selected content contains images.
+   * @default true
+   */
+  copyImageUrl?: boolean;
+}
+
+export interface StreamingConfig {
+  /**
+   * Controls how incomplete tables are handled during streaming.
+   * - `'hidden'`: hide the entire table until it's complete.
+   * - `'progressive'` (default): show the table row-by-row as rows complete.
+   * Only effective when `streamingAnimation` is `true`.
+   * @default 'progressive'
+   * @platform ios, android
+   */
+  tableMode?: 'hidden' | 'progressive';
+}
+
+export interface EnrichedMarkdownTextProps extends Omit<ViewProps, 'style'> {
+  /**
+   * Markdown content to render.
+   * @platform ios, android, web
+   */
+  markdown: string;
+  /**
+   * Style configuration for markdown elements.
+   * @platform ios, android, web
+   */
+  markdownStyle?: MarkdownStyle;
+  /**
+   * Style for the container view.
+   * @platform ios, android, web
+   */
+  containerStyle?: ViewStyle | TextStyle;
+  /**
+   * MD4C parser flags configuration.
+   * Controls how the markdown parser interprets certain syntax.
+   * @platform ios, android, web
+   */
+  md4cFlags?: Md4cFlags;
+  /**
+   * Callback fired when a link is pressed.
+   * Receives the link URL directly.
+   * @platform ios, android, web
+   */
+  onLinkPress?: (event: LinkPressEvent) => void;
+  /**
+   * Callback fired when a link is long pressed.
+   * Receives the link URL directly.
+   * - iOS: When provided, automatically disables the system link preview
+   *   (unless `enableLinkPreview` is explicitly set to `true`).
+   * - Android: Handles long press gestures on links.
+   * - Web: Mapped to the `contextmenu` event (right-click).
+   * @platform ios, android, web
+   */
+  onLinkLongPress?: (event: LinkLongPressEvent) => void;
+  /**
+   * Callback fired when a task list checkbox is tapped.
+   *
+   * The checkbox is toggled on the native side automatically.
+   * Receives the 0-based task index, the new checked state (after toggling),
+   * and the item's plain text.
+   *
+   * Only fires when `flavor="github"` (GFM task lists require GitHub flavor).
+   * @platform ios, android, web
+   */
+  onTaskListItemPress?: (event: TaskListItemPressEvent) => void;
+  /**
+   * Controls whether the system link preview is shown on long press (iOS only).
+   *
+   * When `true`, long-pressing a link shows the native iOS link preview.
+   * When `false`, the system preview is suppressed.
+   *
+   * Defaults to `true`, but automatically becomes `false` when `onLinkLongPress`
+   * is provided. Set explicitly to override the automatic behavior.
+   *
+   * @default true
+   * @platform ios
+   */
+  enableLinkPreview?: boolean;
+  /**
+   * Controls text selection.
+   * - iOS: Controls text selection and link previews on long press.
+   * - Android: Controls text selection.
+   * - Web: Applies `user-select: none` when `false`.
+   * @default true
+   * @platform ios, android, web
+   */
+  selectable?: boolean;
+  /**
+   * Color of the text selection highlight.
+   *
+   * On iOS, this also affects the caret and selection handle colors
+   * (they share a single tint). On macOS, only the selection background
+   * is affected.
+   *
+   * @platform ios, android, macos, web
+   */
+  selectionColor?: ColorValue;
+  /**
+   * Color of the selection handles (drag anchors).
+   * No-op on API levels below 29.
+   *
+   * @platform android
+   */
+  selectionHandleColor?: ColorValue;
+  /**
+   * Specifies whether fonts should scale to respect Text Size accessibility settings.
+   * When false, text will not scale with the user's accessibility settings.
+   * @default true
+   * @platform ios, android
+   */
+  allowFontScaling?: boolean;
+  /**
+   * Specifies the largest possible scale a font can reach when `allowFontScaling`
+   * is enabled.
+   * - `undefined` / `null` (default): no limit
+   * - `0`: no limit
+   * - `>= 1`: sets the maxFontSizeMultiplier of this node to this value
+   * @default undefined
+   * @platform ios, android
+   */
+  maxFontSizeMultiplier?: number;
+  /**
+   * When false (default), removes trailing margin from the last element to
+   * eliminate bottom spacing.
+   * When true, keeps the trailing margin from the last element's marginBottom style.
+   * @default false
+   * @platform ios, android, web
+   */
+  allowTrailingMargin?: boolean;
+  /**
+   * Specifies which Markdown flavor to use for rendering.
+   * - `'commonmark'` (default): standard CommonMark renderer (single TextView).
+   * - `'github'`: GitHub Flavored Markdown — container-based renderer with
+   *   support for tables and other GFM extensions.
+   * @default 'commonmark'
+   * @platform ios, android
+   */
+  flavor?: 'commonmark' | 'github';
+  /**
+   * When true, newly appended content fades in during streaming updates.
+   * Only the tail (new characters beyond the previous content) is animated.
+   * Recommended for LLM streaming use cases with `flavor="commonmark"`.
+   * @default false
+   * @platform ios, android
+   */
+  streamingAnimation?: boolean;
+  /**
+   * Fine-grained control over streaming behavior for block-level elements.
+   * Only effective when `streamingAnimation` is `true`.
+   * @platform ios, android
+   */
+  streamingConfig?: StreamingConfig;
+  /**
+   * Controls how spoiler text is displayed before being revealed.
+   * - `'particles'` (default): animated particle overlay (CAEmitterLayer on iOS,
+   *   Choreographer-driven Canvas particles on Android).
+   * - `'solid'`: opaque rectangle covering the text (Discord-style).
+   *
+   * Both modes support tap-to-reveal.
+   * @default 'particles'
+   * @platform ios, android
+   */
+  spoilerOverlay?: 'particles' | 'solid';
+  /**
+   * Custom items to show in the text selection context menu.
+   * Each item requires a `text` label and an `onPress` callback.
+   * Items with `visible: false` are hidden from the menu.
+   * @platform ios, android
+   */
+  contextMenuItems?: ContextMenuItem[];
+  /**
+   * Controls built-in items added to the native text selection menu.
+   * Custom app-provided actions are controlled separately with `contextMenuItems`.
+   * @default { copyAsMarkdown: true, copyImageUrl: true }
+   * @platform ios, android, macos
+   */
+  selectionMenuConfig?: SelectionMenuConfig;
+  /**
+   * Sets the text direction on the root container.
+   * Useful for RTL languages — CSS logical properties in the renderers
+   * automatically flip blockquote borders, list indentation, etc.
+   * @platform web
+   */
+  dir?: 'ltr' | 'rtl' | 'auto';
+  /**
+   * Sets the text break strategy on Android (API 23+).
+   * - `'simple'`: no hyphenation, minimal line-break work.
+   * - `'highQuality'` (default): full paragraph optimization with hyphenation.
+   * - `'balanced'`: balances line lengths, no hyphenation.
+   *
+   * Both the measurement pass and the render pass use this value so that
+   * measured line counts match rendered line counts.
+   * @default 'highQuality'
+   * @platform android
+   */
+  textBreakStrategy?: 'simple' | 'highQuality' | 'balanced';
+  /**
+   * Sets the line break strategy on iOS (iOS 14+).
+   * - `'none'` (default): no additional line break strategy.
+   * - `'standard'`: standard line breaking rules.
+   * - `'hangul-word'`: Korean word-boundary breaking.
+   * - `'push-out'`: pushes text out to avoid orphaned words.
+   * @default 'none'
+   * @platform ios
+   */
+  lineBreakStrategyIOS?: 'none' | 'standard' | 'hangul-word' | 'push-out';
+  /**
+   * Paragraph writing direction.
+   * - `'first-strong'` (default): resolves each paragraph from its first strong
+   *   directional character. Neutral-only paragraphs fall back to the view's
+   *   resolved layout direction (inherits ancestor `direction` style). Library
+   *   extension beyond React Native — matches Android's `TEXT_DIRECTION_FIRST_STRONG`.
+   * - `'auto'`: React Native parity. iOS TextKit follows the app's
+   *   `userInterfaceLayoutDirection`; mixed-direction paragraphs do not
+   *   auto-resolve.
+   * - `'ltr'` / `'rtl'`: force base direction on every paragraph. Code blocks
+   *   always stay LTR.
+   * @default 'first-strong'
+   * @platform ios
+   */
+  writingDirection?: 'auto' | 'ltr' | 'rtl' | 'first-strong';
+}

package/src/types/MarkdownTextProps.web.ts

@@ -0,0 +1,90 @@
+import type { CSSProperties, HTMLAttributes } from 'react';
+import type { MarkdownStyle, Md4cFlags } from './MarkdownStyle';
+import type {
+  LinkPressEvent,
+  LinkLongPressEvent,
+  TaskListItemPressEvent,
+} from './events';
+
+export interface EnrichedMarkdownTextProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'style' | 'dir'
+> {
+  /**
+   * Markdown content to render.
+   * @platform ios, android, web
+   */
+  markdown: string;
+  /**
+   * Style configuration for markdown elements.
+   * @platform ios, android, web
+   */
+  markdownStyle?: MarkdownStyle;
+  /**
+   * Style for the container view.
+   * @platform ios, android, web
+   */
+  containerStyle?: CSSProperties;
+  /**
+   * MD4C parser flags configuration.
+   * Controls how the markdown parser interprets certain syntax.
+   * @platform ios, android, web
+   */
+  md4cFlags?: Md4cFlags;
+  /**
+   * Callback fired when a link is pressed.
+   * Receives the link URL directly.
+   * @platform ios, android, web
+   */
+  onLinkPress?: (event: LinkPressEvent) => void;
+  /**
+   * Callback fired when a link is long pressed.
+   * Receives the link URL directly.
+   * - iOS: When provided, automatically disables the system link preview
+   *   (unless `enableLinkPreview` is explicitly set to `true`).
+   * - Android: Handles long press gestures on links.
+   * - Web: Mapped to the `contextmenu` event (right-click).
+   * @platform ios, android, web
+   */
+  onLinkLongPress?: (event: LinkLongPressEvent) => void;
+  /**
+   * Callback fired when a task list checkbox is tapped.
+   *
+   * The checkbox is toggled on the native side automatically.
+   * Receives the 0-based task index, the new checked state (after toggling),
+   * and the item's plain text.
+   *
+   * Only fires when `flavor="github"` (GFM task lists require GitHub flavor).
+   * @platform ios, android, web
+   */
+  onTaskListItemPress?: (event: TaskListItemPressEvent) => void;
+  /**
+   * Controls text selection.
+   * - iOS: Controls text selection and link previews on long press.
+   * - Android: Controls text selection.
+   * - Web: Applies `user-select: none` when `false`.
+   * @default true
+   * @platform ios, android, web
+   */
+  selectable?: boolean;
+  /**
+   * Color of the text selection highlight.
+   * @platform web
+   */
+  selectionColor?: string;
+  /**
+   * When false (default), removes trailing margin from the last element to
+   * eliminate bottom spacing.
+   * When true, keeps the trailing margin from the last element's marginBottom style.
+   * @default false
+   * @platform ios, android, web
+   */
+  allowTrailingMargin?: boolean;
+  /**
+   * Sets the text direction on the root container.
+   * Useful for RTL languages — CSS logical properties in the renderers
+   * automatically flip blockquote borders, list indentation, etc.
+   * @platform web
+   */
+  dir?: 'ltr' | 'rtl' | 'auto';
+}

package/src/types/events.ts

@@ -0,0 +1,32 @@
+export interface LinkPressEvent {
+  url: string;
+}
+
+export interface LinkLongPressEvent {
+  url: string;
+}
+
+export interface TaskListItemPressEvent {
+  index: number;
+  checked: boolean;
+  text: string;
+}
+
+/**
+ * Native-level context menu item config sent to the native component.
+ * Does not include the `onPress` callback — callbacks are managed on the JS side.
+ */
+export interface ContextMenuItemConfig {
+  text: string;
+  icon?: string;
+}
+
+/**
+ * Event payload fired by the native component when a context menu item is pressed.
+ */
+export interface OnContextMenuItemPressEvent {
+  itemText: string;
+  selectedText: string;
+  selectionStart: number;
+  selectionEnd: number;
+}

package/src/utils/regexParser.ts

@@ -0,0 +1,54 @@
+import type { LinkNativeRegex } from '../EnrichedMarkdownTextInputNativeComponent';
+
+const DISABLED_REGEX: LinkNativeRegex = {
+  pattern: '',
+  caseInsensitive: false,
+  dotAll: false,
+  isDisabled: true,
+  isDefault: false,
+};
+
+const DEFAULT_REGEX: LinkNativeRegex = {
+  pattern: '',
+  caseInsensitive: false,
+  dotAll: false,
+  isDisabled: false,
+  isDefault: true,
+};
+
+export const toNativeRegexConfig = (
+  regex: RegExp | undefined | null
+): LinkNativeRegex => {
+  if (regex === null) {
+    return DISABLED_REGEX;
+  }
+
+  if (regex === undefined) {
+    return DEFAULT_REGEX;
+  }
+
+  const source = regex.source;
+
+  const hasLookbehind = source.includes('(?<=') || source.includes('(?<!');
+
+  if (hasLookbehind) {
+    const lookbehindContent = source.match(/\(\?<[=!](.*?)\)/)?.[1] || '';
+    if (/[*+{]/.test(lookbehindContent)) {
+      if (__DEV__) {
+        console.error(
+          'Variable-width lookbehinds are not supported. Using default link regex.'
+        );
+      }
+
+      return DEFAULT_REGEX;
+    }
+  }
+
+  return {
+    pattern: source,
+    caseInsensitive: regex.ignoreCase,
+    dotAll: regex.dotAll,
+    isDisabled: false,
+    isDefault: false,
+  };
+};

package/src/web/EnrichedMarkdownText.tsx

@@ -0,0 +1,154 @@
+import { useState, useEffect, useMemo, type CSSProperties } from 'react';
+import type { EnrichedMarkdownTextProps } from '../types/MarkdownTextProps.web';
+import { normalizeMarkdownStyle } from '../normalizeMarkdownStyle.web';
+import {
+  zeroTrailingMargins,
+  parseErrorFallbackStyle,
+  buildStyles,
+} from './styles';
+import { parseMarkdown } from './parseMarkdown';
+import { RenderNode } from './renderers';
+import type { ASTNode, RendererCallbacks, RenderCapabilities } from './types';
+import { indexTaskItems, markInlineImages } from './utils';
+import { loadKaTeX } from './katex';
+import type { KaTeXInstance } from './katex';
+import { ENRM_TEXT_CLASS, ENRM_SELECTION_BG_VAR } from './globalStyles';
+
+export const EnrichedMarkdownText = ({
+  markdown,
+  markdownStyle = {},
+  md4cFlags = {},
+  onLinkPress,
+  onLinkLongPress,
+  onTaskListItemPress,
+  allowTrailingMargin = false,
+  containerStyle,
+  selectable = true,
+  dir,
+  selectionColor,
+  ...rest
+}: EnrichedMarkdownTextProps) => {
+  const normalizedStyle = useMemo(
+    () => normalizeMarkdownStyle(markdownStyle),
+    [markdownStyle]
+  );
+
+  const [ast, setAst] = useState<ASTNode | null>(null);
+  const [katex, setKatex] = useState<KaTeXInstance | null>(null);
+  const [parseError, setParseError] = useState<boolean>(false);
+
+  const {
+    underline = false,
+    latexMath = true,
+    superscript = false,
+    subscript = false,
+    highlight = false,
+  } = md4cFlags;
+
+  useEffect(() => {
+    let cancelled = false;
+
+    const katexPromise = latexMath ? loadKaTeX() : Promise.resolve(null);
+
+    Promise.all([
+      parseMarkdown(markdown, {
+        underline,
+        latexMath,
+        superscript,
+        subscript,
+        highlight,
+      }),
+      katexPromise,
+    ])
+      .then(([result, katexInstance]) => {
+        if (!cancelled) {
+          indexTaskItems(result);
+          markInlineImages(result);
+
+          setParseError(false);
+          setKatex(katexInstance);
+          setAst(result);
+        }
+      })
+      .catch((error) => {
+        if (!cancelled) {
+          if (__DEV__) {
+            console.error('[EnrichedMarkdownText] Parse failed:', error);
+          }
+
+          setParseError(true);
+          setAst(null);
+          setKatex(null);
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [markdown, underline, latexMath, superscript, subscript, highlight]);
+
+  const callbacks = useMemo<RendererCallbacks>(
+    () => ({ onLinkPress, onLinkLongPress, onTaskListItemPress }),
+    [onLinkPress, onLinkLongPress, onTaskListItemPress]
+  );
+
+  const capabilities = useMemo<RenderCapabilities>(() => ({ katex }), [katex]);
+
+  const lastChildStyle = useMemo(
+    () =>
+      allowTrailingMargin
+        ? normalizedStyle
+        : zeroTrailingMargins(normalizedStyle),
+    [normalizedStyle, allowTrailingMargin]
+  );
+
+  const styles = useMemo(() => buildStyles(normalizedStyle), [normalizedStyle]);
+
+  const lastChildStyles = useMemo(
+    () => buildStyles(lastChildStyle),
+    [lastChildStyle]
+  );
+
+  const wrapperStyle = useMemo<CSSProperties>(
+    () => ({
+      display: 'flex',
+      flexDirection: 'column',
+      ...(containerStyle as CSSProperties),
+      ...(selectable ? undefined : { userSelect: 'none' }),
+      ...(selectionColor
+        ? ({ [ENRM_SELECTION_BG_VAR]: selectionColor } as CSSProperties)
+        : null),
+    }),
+    [containerStyle, selectable, selectionColor]
+  );
+
+  if (parseError) {
+    return (
+      <div className={ENRM_TEXT_CLASS} style={wrapperStyle} dir={dir} {...rest}>
+        <pre style={parseErrorFallbackStyle}>{markdown}</pre>
+      </div>
+    );
+  }
+
+  if (!ast) return null;
+
+  const children = ast.children ?? [];
+  const lastIdx = children.length - 1;
+
+  return (
+    <div className={ENRM_TEXT_CLASS} style={wrapperStyle} dir={dir} {...rest}>
+      {children.map((child, index) => (
+        <RenderNode
+          key={`${child.type}-${index}`}
+          node={child}
+          style={index === lastIdx ? lastChildStyle : normalizedStyle}
+          styles={index === lastIdx ? lastChildStyles : styles}
+          callbacks={callbacks}
+          capabilities={capabilities}
+        />
+      ))}
+    </div>
+  );
+};
+
+export default EnrichedMarkdownText;

package/src/web/globalStyles.ts

@@ -0,0 +1,15 @@
+import { injectStyleOnce } from './injectStyle';
+
+export const ENRM_TEXT_CLASS = 'enrm-text';
+export const ENRM_SELECTION_BG_VAR = '--enrm-selection-bg';
+
+const RULES: ReadonlyArray<readonly [id: string, css: string]> = [
+  [
+    'enrm-selection-style',
+    `.${ENRM_TEXT_CLASS} ::selection { background-color: var(${ENRM_SELECTION_BG_VAR}); }`,
+  ],
+];
+
+for (const [id, css] of RULES) {
+  injectStyleOnce(id, css);
+}

package/src/web/injectStyle.ts

@@ -0,0 +1,17 @@
+/// <reference lib="dom" />
+
+/**
+ * Idempotently injects a `<style>` rule into `document.head`.
+ *
+ * Safe on SSR (no-op when `document` is undefined) and HMR (de-duped by `id`).
+ * Intended for module-level invocation: `N` mounted components produce a
+ * single `<style>` tag in the DOM.
+ */
+export const injectStyleOnce = (id: string, css: string): void => {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById(id) != null) return;
+  const style = document.createElement('style');
+  style.id = id;
+  style.textContent = css;
+  document.head.appendChild(style);
+};

package/src/web/katex.ts

@@ -0,0 +1,31 @@
+export interface KaTeXInstance {
+  renderToString(
+    expression: string,
+    options?: {
+      displayMode?: boolean;
+      throwOnError?: boolean;
+      trust?: boolean;
+      output?: 'html' | 'mathml' | 'htmlAndMathml';
+    }
+  ): string;
+}
+
+let katexLoadPromise: Promise<KaTeXInstance | null> | null = null;
+
+/** Lazily loads KaTeX. Resolves to null if not installed. */
+export function loadKaTeX(): Promise<KaTeXInstance | null> {
+  if (!katexLoadPromise) {
+    let instance: KaTeXInstance | null = null;
+    try {
+      const mod = require('katex');
+      const candidate = (mod?.default ?? mod) as KaTeXInstance | null;
+      if (typeof candidate?.renderToString === 'function') {
+        instance = candidate;
+      }
+    } catch {
+      // katex not installed — math rendering will be skipped
+    }
+    katexLoadPromise = Promise.resolve(instance);
+  }
+  return katexLoadPromise;
+}