react-native-nitro-markdown 0.1.2 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 João Paulo C. Marra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,6 @@
 <p align="center">
   <img src="./readme/demo.gif" alt="react-native-nitro-markdown demo" width="300" />
+  <img src="./readme/stream-demo.gif" alt="react-native-nitro-markdown stream demo" width="300" />
 </p>
 
 # react-native-nitro-markdown 🚀
@@ -41,6 +42,9 @@ Choose your preferred package manager to install the package and its core depend
 npm install react-native-nitro-markdown react-native-nitro-modules
 ```
 
+> **Note:** If you want to use **Math** (LaTeX) or certain **Image** features, you should also install the optional peer dependencies:
+> `npm install react-native-svg react-native-mathjax-svg`
+
 **Yarn**
 
 ```bash
@@ -80,159 +84,330 @@ npx expo prebuild
 
 ## 💻 Usage
 
-### Basic Parsing
+### Option 1: Batteries Included (Simplest)
 
-The parsing is synchronous and instant. It returns a fully typed JSON AST.
+Use the `Markdown` component with built-in premium dark-mode styling:
 
-```typescript
-import { parseMarkdown } from "react-native-nitro-markdown";
+```tsx
+import { Markdown } from "react-native-nitro-markdown";
 
-const markdown = `
-# Hello World
-This is **bold** text and a [link](https://github.com).
-`;
+export function MyComponent() {
+  return (
+    <Markdown options={{ gfm: true }}>
+      {"# Hello World\nThis is **bold** text."}
+    </Markdown>
+  );
+}
+```
+
+### Option 2: Light Theme / Theme Presets
+
+The default theme is optimized for dark mode. For light backgrounds, use the provided `lightMarkdownTheme`:
 
-const ast = parseMarkdown(markdown);
-console.log(ast);
-// Output: { type: "document", children: [...] }
+```tsx
+import { Markdown, lightMarkdownTheme } from "react-native-nitro-markdown";
+
+<Markdown theme={lightMarkdownTheme}>{"# Light Mode Markdown"}</Markdown>;
 ```
 
-### Advanced Options (GFM & Math)
+Available presets:
 
-Enable GitHub Flavored Markdown (Tables, TaskLists) or LaTeX Math support.
+- `defaultMarkdownTheme` / `darkMarkdownTheme` - Modern dark theme
+- `lightMarkdownTheme` - Clean light theme
+- `minimalMarkdownTheme` - Bare minimum styling for a clean slate
 
-```typescript
-import { parseMarkdown } from "react-native-nitro-markdown";
+### Option 3: Custom Theming
 
-const ast = parseMarkdown(markdown, {
-  gfm: true, // Tables, Strikethrough, Autolinks, TaskLists
-  math: true, // $E=mc^2$ and $$block$$
-  wiki: true, // [[WikiLinks]]
-});
+Customize the look and feel by passing a partial `theme` object:
+
+```tsx
+import { Markdown } from "react-native-nitro-markdown";
+
+const myTheme = {
+  colors: {
+    text: "#2D3748",
+    heading: "#1A202C",
+    link: "#3182CE",
+  },
+  fontFamilies: {
+    regular: "Inter",
+    heading: "Inter-Bold",
+    mono: "JetBrainsMono",
+  },
+  borderRadius: {
+    s: 4,
+    m: 8,
+    l: 16,
+  },
+  showCodeLanguage: true, // Toggle code language labels
+};
+
+<Markdown theme={myTheme}>{"# Custom Themed Markdown"}</Markdown>;
 ```
 
----
+**Theme Properties:**
+
+- `colors` - All color tokens (text, heading, link, code, codeBackground, codeLanguage, etc.)
+- `spacing` - Spacing tokens (xs, s, m, l, xl)
+- `fontSizes` - Font sizes (xs, s, m, l, xl, h1-h6)
+- `fontFamilies` - Font families for regular, heading, and mono text
+- `borderRadius` - Border radius tokens (s, m, l)
+- `showCodeLanguage` - Show/hide code block language labels
+
+### Option 4: Style Overrides per Node Type
+
+Apply quick style overrides to specific node types without writing custom renderers:
+
+```tsx
+<Markdown
+  styles={{
+    heading: { color: "red", fontWeight: "900" },
+    code_block: { backgroundColor: "#1a1a2e", borderRadius: 16 },
+    blockquote: { borderLeftColor: "#ff6b6b" },
+  }}
+>
+  {markdown}
+</Markdown>
+```
+
+### Option 5: Minimal Styling Strategy
+
+Start with a clean slate using the `stylingStrategy` prop:
+
+```tsx
+<Markdown stylingStrategy="minimal" theme={myLightTheme}>
+  {content}
+</Markdown>
+```
+
+This zeros out all spacing and removes opinionated colors, letting you build up from scratch.
+
+### Option 6: Custom Renderers
+
+Override specific node types with full control. Custom renderers now receive **pre-mapped props** for common values:
+
+```tsx
+import {
+  Markdown,
+  CodeBlock,
+  type HeadingRendererProps,
+  type CodeBlockRendererProps,
+} from "react-native-nitro-markdown";
+
+const renderers = {
+  // Pre-mapped `level` prop - no need for node.level!
+  heading: ({ level, children }: HeadingRendererProps) => (
+    <MyHeading level={level}>{children}</MyHeading>
+  ),
+
+  // Pre-mapped `content` and `language` - no getTextContent() needed!
+  code_block: ({ content, language }: CodeBlockRendererProps) => (
+    <CodeBlock
+      content={content}
+      language={language}
+      style={{ borderWidth: 2 }}
+    />
+  ),
+};
+
+<Markdown renderers={renderers} options={{ gfm: true }}>
+  {markdown}
+</Markdown>;
+```
+
+**Pre-mapped Props by Node Type:**
 
-## 🎨 Rendering
+- `heading` → `level` (1-6)
+- `link` → `href`, `title`
+- `image` → `url`, `alt`, `title`
+- `code_block` → `content`, `language`
+- `code_inline` → `content`
+- `list` → `ordered`, `start`
+- `task_list_item` → `checked`
 
-This library is a **Parser Only**. It gives you the raw data (AST) so you can render it with native components (`<Text>`, `<View>`) for maximum performance.
+### Option 7: Style Props on Individual Renderers
 
-Here is a simple recursive renderer example:
+All built-in renderers accept a `style` prop for fine-grained overrides:
 
 ```tsx
-import React from "react";
-import { Text, View, StyleSheet } from "react-native";
-import { parseMarkdown, type MarkdownNode } from "react-native-nitro-markdown";
+import { Heading, CodeBlock, InlineCode } from "react-native-nitro-markdown";
+
+// Works in custom renderers
+<Heading level={1} style={{ color: "hotpink" }}>Title</Heading>
+<CodeBlock content={code} style={{ borderRadius: 0 }} />
+<InlineCode style={{ backgroundColor: "#ff0" }}>code</InlineCode>
+```
+
+### Option 8: Auto Content Extraction for Code
 
-export function MarkdownView({ content }: { content: string }) {
-  const ast = parseMarkdown(content, { gfm: true });
+The `CodeBlock` and `InlineCode` components now accept a `node` prop for automatic content extraction:
+
+```tsx
+// Before: Manual extraction required
+code_block: ({ node }) => (
+  <CodeBlock content={getTextContent(node)} language={node.language} />
+);
+
+// After: Just pass the node
+code_block: ({ node }) => <CodeBlock node={node} />;
+
+// Or use the pre-mapped content prop (recommended)
+code_block: ({ content, language }) => (
+  <CodeBlock content={content} language={language} />
+);
+```
+
+### Option 9: Headless (Minimal Bundle)
+
+For maximum control, data processing, or minimal JS overhead:
+
+```tsx
+import {
+  parseMarkdown,
+  getTextContent,
+} from "react-native-nitro-markdown/headless";
+
+const ast = parseMarkdown("# Hello World");
+const text = getTextContent(ast); // "Hello World"
+```
+
+### Option 10: High-Performance Streaming (LLMs)
+
+When streaming text token-by-token (e.g., from ChatGPT or Gemini):
+
+```tsx
+import {
+  MarkdownStream,
+  useMarkdownSession,
+} from "react-native-nitro-markdown";
+
+export function AIResponseStream() {
+  const session = useMarkdownSession();
+
+  useEffect(() => {
+    session.getSession().append("Hello **Nitro**!");
+    return () => session.clear();
+  }, [session]);
 
   return (
-    <View style={styles.container}>
-      <Renderer node={ast} />
-    </View>
+    <MarkdownStream session={session.getSession()} options={{ gfm: true }} />
   );
 }
+```
 
-function Renderer({ node }: { node: MarkdownNode }) {
-  switch (node.type) {
-    case "document":
-      return (
-        <View>
-          {node.children?.map((child, i) => (
-            <Renderer key={i} node={child} />
-          ))}
-        </View>
-      );
-
-    case "heading":
-      return (
-        <Text style={styles.h1}>
-          {node.children?.map((c, i) => (
-            <Renderer key={i} node={c} />
-          ))}
-        </Text>
-      );
-
-    case "paragraph":
-      return (
-        <Text style={styles.p}>
-          {node.children?.map((child, i) => (
-            <Renderer key={i} node={child} />
-          ))}
-        </Text>
-      );
-
-    case "text":
-      return <Text>{node.content}</Text>;
-
-    case "bold":
-      return (
-        <Text style={styles.bold}>
-          {node.children?.map((c, i) => (
-            <Renderer key={i} node={c} />
-          ))}
-        </Text>
-      );
-
-    // Handle 'table', 'code_block', 'math_inline' etc...
-    default:
-      return null;
-  }
-}
+---
+
+## 🎨 Using Context in Custom Renderers
+
+Access theme and context in custom renderers:
+
+```tsx
+import {
+  useMarkdownContext,
+  MarkdownContext,
+} from "react-native-nitro-markdown";
+
+const MyCustomRenderer = ({ children }) => {
+  const { theme, stylingStrategy } = useMarkdownContext();
 
-const styles = StyleSheet.create({
-  container: { padding: 16 },
-  h1: { fontSize: 24, fontWeight: "bold", marginVertical: 8 },
-  p: { fontSize: 16, lineHeight: 24, marginBottom: 8 },
-  bold: { fontWeight: "700" },
-});
+  return <View style={{ padding: theme.spacing.m }}>{children}</View>;
+};
 ```
 
 ---
 
+## 🛠️ Exported Utilities
+
+```tsx
+// Parser and utilities
+export {
+  parseMarkdown,
+  parseMarkdownWithOptions,
+  getTextContent,
+} from "./headless";
+
+// Theme presets
+export {
+  defaultMarkdownTheme,
+  lightMarkdownTheme,
+  darkMarkdownTheme,
+  minimalMarkdownTheme,
+  mergeThemes,
+};
+
+// Context
+export { useMarkdownContext, MarkdownContext };
+
+// Individual renderers
+export {
+  Heading,
+  Paragraph,
+  Link,
+  Blockquote,
+  HorizontalRule,
+  CodeBlock,
+  InlineCode,
+  List,
+  ListItem,
+  TaskListItem,
+  TableRenderer,
+  Image,
+  MathInline,
+  MathBlock,
+};
+```
+
+---
+
+## 🛠️ Headless vs. Non-Headless
+
+| Feature         | **Headless** (`/headless`)  | **Non-Headless** (`default`)       |
+| :-------------- | :-------------------------- | :--------------------------------- |
+| **Logic**       | Raw C++ md4c Parser         | Parser + Full UI Renderer          |
+| **Output**      | JSON AST Tree               | React Native Views                 |
+| **Best For**    | Search Indexing, Custom UIs | Fast Implementation, Documentation |
+| **JS Overhead** | ~4 KB                       | ~60 KB                             |
+
+---
+
+### Basic Parsing API
+
+The parsing is synchronous and instant. It returns a fully typed JSON AST:
+
+```typescript
+import { parseMarkdown } from "react-native-nitro-markdown/headless";
+
+const ast = parseMarkdown(`
+# Hello World
+This is **bold** text and a [link](https://github.com).
+`);
+```
+
+### Options
+
+| Option | Type      | Default | Description                                                                    |
+| :----- | :-------- | :------ | :----------------------------------------------------------------------------- |
+| `gfm`  | `boolean` | `false` | Enable GitHub Flavored Markdown (Tables, Strikethrough, Autolinks, TaskLists). |
+| `math` | `boolean` | `false` | Enable LaTeX Math support (`$` and `$$`).                                      |
+
+---
+
 ## 📐 AST Structure
 
-The parser returns a `MarkdownNode` tree. The Types are fully exported for TypeScript support.
+The parser returns a `MarkdownNode` tree:
 
 ```typescript
 export interface MarkdownNode {
   type: NodeType;
-  // Content for Text/Code/Math
   content?: string;
-  // Hierarchy
   children?: MarkdownNode[];
-  // Metadata
-  level?: number; // Headings (1-6)
-  href?: string; // Links
-  checked?: boolean; // Task Lists
-  language?: string; // Code Blocks
-  // Table Props
+  level?: number;
+  href?: string;
+  checked?: boolean;
+  language?: string;
   align?: "left" | "center" | "right";
   isHeader?: boolean;
 }
-
-export type NodeType =
-  | "document"
-  | "paragraph"
-  | "text"
-  | "heading"
-  | "bold"
-  | "italic"
-  | "strikethrough"
-  | "link"
-  | "image"
-  | "code_inline"
-  | "code_block"
-  | "blockquote"
-  | "list"
-  | "list_item"
-  | "task_list_item"
-  | "table"
-  | "table_row"
-  | "table_cell"
-  | "math_inline"
-  | "math_block";
 ```
 
 ---
@@ -241,16 +416,17 @@ export type NodeType =
 
 We parse math delimiters (`$` and `$$`) natively using the `MD_FLAG_LATEXMATHSPANS` flag in `md4c`.
 
-To render the math, you should use a library like `react-native-math-view`, `react-native-mathjax-svg`, or `react-native-katex` inside your renderer:
+To render the math, use a library like `react-native-mathjax-svg`:
 
 ```tsx
-// Inside your switch(node.type)
 case 'math_inline':
   return <MathView math={node.content} style={styles.math} />;
 case 'math_block':
   return <MathView math={node.content} style={styles.mathBlock} />;
 ```
 
+---
+
 ## 📊 Package Size
 
 | Metric               | Size    |
@@ -259,8 +435,6 @@ case 'math_block':
 | **Unpacked**         | ~325 kB |
 | **Total files**      | 55      |
 
-> The package includes the [md4c](https://github.com/mity/md4c) C source code (~244 kB) which is compiled natively on iOS and Android. This is a one-time cost that enables the high-performance parsing.
-
 ---
 
 ## 🤝 Contributing

package/android/src/main/cpp/cpp-adapter.cpp

@@ -2,6 +2,6 @@
 #include "NitroMarkdownOnLoad.hpp"
 
 JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
-  return margelo::nitro::NitroMarkdown::initialize(vm);
+  return margelo::nitro::Markdown::initialize(vm);
 }
 

package/android/src/main/java/com/margelo/nitro/com/nitromarkdown/HybridMarkdownSession.kt

@@ -0,0 +1,61 @@
+package com.margelo.nitro.com.nitromarkdown
+
+class HybridMarkdownSession : HybridMarkdownSessionSpec() {
+    private var buffer = StringBuilder()
+    private val listeners = mutableMapOf<Long, () -> Unit>()
+    private var nextListenerId = 0L
+    private val lock = Any()
+
+    override var highlightPosition: Double = 0.0
+        set(value) {
+            synchronized(lock) { field = value }
+            // No notify for highlighting to avoid flood
+        }
+
+
+
+    override val memorySize: Long
+        get() = buffer.length.toLong()
+
+    override fun append(chunk: String) {
+        synchronized(lock) {
+            buffer.append(chunk)
+        }
+        notifyListeners()
+    }
+
+    override fun clear() {
+        synchronized(lock) {
+            buffer.clear()
+            highlightPosition = 0.0
+        }
+        notifyListeners()
+    }
+
+    override fun getAllText(): String {
+        synchronized(lock) {
+            return buffer.toString()
+        }
+    }
+
+    override fun addListener(listener: () -> Unit): () -> Unit {
+        val id: Long
+        synchronized(lock) {
+            id = nextListenerId++
+            listeners[id] = listener
+        }
+        return {
+            synchronized(lock) {
+                listeners.remove(id)
+            }
+        }
+    }
+
+    private fun notifyListeners() {
+        val currentListeners: Collection<() -> Unit>
+        synchronized(lock) {
+            currentListeners = listeners.values.toList()
+        }
+        currentListeners.forEach { it() }
+    }
+}

package/android/src/main/java/com/nitromarkdown/NitroMarkdownPackage.kt

@@ -4,6 +4,7 @@ import com.facebook.react.TurboReactPackage
 import com.facebook.react.bridge.NativeModule
 import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.module.model.ReactModuleInfoProvider
+import com.facebook.react.uimanager.ViewManager
 
 class NitroMarkdownPackage : TurboReactPackage() {
     companion object {
@@ -19,5 +20,8 @@ class NitroMarkdownPackage : TurboReactPackage() {
     override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
         return ReactModuleInfoProvider { emptyMap() }
     }
-}
 
+    override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
+        return emptyList()
+    }
+}

package/cpp/bindings/HybridMarkdownParser.cpp

@@ -2,7 +2,7 @@
 #include <sstream>
 #include <iomanip>
 
-namespace margelo::nitro::NitroMarkdown {
+namespace margelo::nitro::Markdown {
 
 std::string HybridMarkdownParser::parse(const std::string& text) {
     InternalParserOptions opts;
@@ -109,4 +109,4 @@ std::string HybridMarkdownParser::nodeToJson(const std::shared_ptr<InternalMarkd
     return json.str();
 }
 
-} // namespace margelo::nitro::NitroMarkdown
+} // namespace margelo::nitro::Markdown

package/cpp/bindings/HybridMarkdownParser.hpp

@@ -4,7 +4,7 @@
 #include "../core/MD4CParser.hpp"
 #include <memory>
 
-namespace margelo::nitro::NitroMarkdown {
+namespace margelo::nitro::Markdown {
 
 using InternalMarkdownNode = ::NitroMarkdown::MarkdownNode;
 using InternalParserOptions = ::NitroMarkdown::ParserOptions;
@@ -25,4 +25,4 @@ private:
     std::string nodeToJson(const std::shared_ptr<InternalMarkdownNode>& node);
 };
 
-} // namespace margelo::nitro::NitroMarkdown
+} // namespace margelo::nitro::Markdown