react-native-nitro-markdown 0.1.1 → 0.2.1

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,112 +84,166 @@ npx expo prebuild
 
 ## 💻 Usage
 
-### Basic Parsing
-
-The parsing is synchronous and instant. It returns a fully typed JSON AST.
+### Option 1: Batteries Included (Simplest)
 
-```typescript
-import { parseMarkdown } from "react-native-nitro-markdown";
+Use the `Markdown` component with built-in premium dark-mode styling:
 
-const markdown = `
-# Hello World
-This is **bold** text and a [link](https://github.com).
-`;
+```tsx
+import { Markdown } from "react-native-nitro-markdown";
 
-const ast = parseMarkdown(markdown);
-console.log(ast);
-// Output: { type: "document", children: [...] }
+export function MyComponent() {
+  return (
+    <Markdown options={{ gfm: true }}>
+      {"# Hello World\nThis is **bold** text."}
+    </Markdown>
+  );
+}
 ```
 
-### Advanced Options (GFM & Math)
+### Option 2: Custom Renderers
 
-Enable GitHub Flavored Markdown (Tables, TaskLists) or LaTeX Math support.
+Override specific node types while keeping defaults for everything else:
 
-```typescript
-import { parseMarkdown } from "react-native-nitro-markdown";
+```tsx
+import {
+  Markdown,
+  Heading,
+  type CustomRenderers,
+} from "react-native-nitro-markdown";
+import MathJax from "react-native-mathjax-svg";
+
+const renderers: CustomRenderers = {
+  // Custom styled heading
+  heading: ({ node, children }) => (
+    <Heading level={node.level ?? 1}>
+      <Text style={{ color: "pink" }}>{children}</Text>
+    </Heading>
+  ),
+  // Custom math renderer
+  math_inline: ({ node }) => <MathJax fontSize={16}>{node.content}</MathJax>,
+  math_block: ({ node }) => <MathJax fontSize={20}>{node.content}</MathJax>,
+};
+
+<Markdown renderers={renderers} options={{ gfm: true, math: true }}>
+  {markdown}
+</Markdown>;
+```
 
-const ast = parseMarkdown(markdown, {
-  gfm: true, // Tables, Strikethrough, Autolinks, TaskLists
-  math: true, // $E=mc^2$ and $$block$$
-  wiki: true, // [[WikiLinks]]
-});
+### Option 3: Custom Theming
+
+You can easily customize the look and feel of the default components by passing a `theme` object. This allows you to match your app's brand without writing custom renderers for everything.
+
+```tsx
+import { Markdown } from "react-native-nitro-markdown";
+
+const myTheme = {
+  colors: {
+    text: "#2D3748",
+    heading: "#1A202C",
+    link: "#3182CE",
+    tableBorder: "#E2E8F0",
+    tableHeader: "#F7FAFC",
+  },
+  spacing: {
+    m: 16,
+  },
+};
+
+<Markdown theme={myTheme}>{"# Custom Branded Markdown"}</Markdown>;
+
+> **Tip:** The default theme is optimized for Dark Mode. For Light Mode, pass a custom theme object or check out the [theme source](packages/react-native-nitro-markdown/src/theme.ts) to see all available tokens.
 ```
 
----
+### Option 4: Headless (Minimal Bundle)
 
-## 🎨 Rendering
+For maximum control, data processing, or minimal JS overhead:
 
-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.
+```tsx
+/**
+ * Only imports the parser.
+ * Zero UI overhead, purely synchronous AST generation.
+ */
+import { parseMarkdown } from "react-native-nitro-markdown/headless";
+
+const ast = parseMarkdown("# Hello World");
+```
 
-Here is a simple recursive renderer example:
+### Option 5: High-Performance Streaming (LLMs)
+
+When streaming text token-by-token (e.g., from ChatGPT or Gemini), re-parsing the entire document in JavaScript for every token is too slow.
+
+**Nitro Markdown** enables **Native Streaming** via JSI. The text buffer is maintained in C++ and updates are pushed directly to the native view, bypassing React completely.
 
 ```tsx
-import React from "react";
-import { Text, View, StyleSheet } from "react-native";
-import { parseMarkdown, type MarkdownNode } from "react-native-nitro-markdown";
+import {
+  MarkdownStream,
+  useMarkdownSession,
+} from "react-native-nitro-markdown";
+
+export function AIResponseStream() {
+  // 1. Create a native session
+  const session = useMarkdownSession();
 
-export function MarkdownView({ content }: { content: string }) {
-  const ast = parseMarkdown(content, { gfm: true });
+  useEffect(() => {
+    // 2. Append chunks directly to C++ (Zero-Latency)
+    // Example: Socket.on('data', (chunk) => session.getSession().append(chunk));
 
+    session.getSession().append("Hello **Nitro**!");
+
+    return () => session.clear();
+  }, [session]);
+
+  // 3. Render the localized stream component
   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;
-  }
-}
+---
+
+## 🛠️ 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. We recommend using the `/headless` entry point if you only need the parser.
+
+```typescript
+import { parseMarkdown } from "react-native-nitro-markdown/headless";
+
+const ast = parseMarkdown(`
+# Hello World
+This is **bold** text and a [link](https://github.com).
+`);
+console.log(ast);
+// Output: { type: "document", children: [...] }
+```
+
+### Options
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `gfm` | `boolean` | `false` | Enable GitHub Flavored Markdown (Tables, Strikethrough, Autolinks, TaskLists). |
+| `math` | `boolean` | `false` | Enable LaTeX Math support (`$` and `$$`). |
 
-const styles = StyleSheet.create({
-  container: { padding: 16 },
-  h1: { fontSize: 24, fontWeight: "bold", marginVertical: 8 },
-  p: { fontSize: 16, lineHeight: 24, marginBottom: 8 },
-  bold: { fontWeight: "700" },
+### Parser Options (GFM & Math)
+
+Enable GitHub Flavored Markdown (Tables, TaskLists) or LaTeX Math support.
+
+```typescript
+import { parseMarkdownWithOptions } from "react-native-nitro-markdown/headless";
+
+const ast = parseMarkdownWithOptions(markdown, {
+  gfm: true, // Tables (supports complex nested content!), Strikethrough, Autolinks, TaskLists
+  math: true, // $E=mc^2$ and $$block$$
 });
 ```
 

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

package/ios/HybridMarkdownSession.swift

@@ -0,0 +1,64 @@
+import Foundation
+import NitroModules
+
+class HybridMarkdownSession: HybridMarkdownSessionSpec {
+    private var buffer = ""
+    private var listeners: [UUID: () -> Void] = [:]
+    private let lock = NSLock()
+    
+    private(set) var version: Int = 0
+    
+    var highlightPosition: Double = 0
+    
+
+    
+    var memorySize: Int {
+        return buffer.utf8.count + MemoryLayout<HybridMarkdownSession>.size
+    }
+    
+    func append(chunk: String) throws {
+        lock.lock()
+        buffer += chunk
+        version += 1
+        lock.unlock()
+        notifyListeners()
+    }
+    
+    func clear() throws {
+        lock.lock()
+        buffer = ""
+        highlightPosition = 0
+        version += 1
+        lock.unlock()
+        notifyListeners()
+    }
+    
+    func getAllText() throws -> String {
+        lock.lock()
+        defer { lock.unlock() }
+        return buffer
+    }
+    
+    func addListener(listener: @escaping () -> Void) throws -> () -> Void {
+        let id = UUID()
+        lock.lock()
+        listeners[id] = listener
+        lock.unlock()
+        
+        return { [weak self] in
+            self?.lock.lock()
+            self?.listeners.removeValue(forKey: id)
+            self?.lock.unlock()
+        }
+    }
+    
+    private func notifyListeners() {
+        lock.lock()
+        let currentListeners = Array(listeners.values)
+        lock.unlock()
+        
+        for listener in currentListeners {
+            listener()
+        }
+    }
+}

package/lib/commonjs/MarkdownContext.js

@@ -0,0 +1,21 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useMarkdownContext = exports.MarkdownContext = void 0;
+var _react = require("react");
+var _theme = require("./theme.js");
+/**
+ * Object mapping node types to custom renderers.
+ */
+
+// Context for custom renderers and theme
+
+const MarkdownContext = exports.MarkdownContext = /*#__PURE__*/(0, _react.createContext)({
+  renderers: {},
+  theme: _theme.defaultMarkdownTheme
+});
+const useMarkdownContext = () => (0, _react.useContext)(MarkdownContext);
+exports.useMarkdownContext = useMarkdownContext;
+//# sourceMappingURL=MarkdownContext.js.map

package/lib/commonjs/MarkdownContext.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_react","require","_theme","MarkdownContext","exports","createContext","renderers","theme","defaultMarkdownTheme","useMarkdownContext","useContext"],"sourceRoot":"../../src","sources":["MarkdownContext.ts"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AACA,IAAAC,MAAA,GAAAD,OAAA;AAoBA;AACA;AACA;;AAKA;;AAMO,MAAME,eAAe,GAAAC,OAAA,CAAAD,eAAA,gBAAG,IAAAE,oBAAa,EAAuB;EACjEC,SAAS,EAAE,CAAC,CAAC;EACbC,KAAK,EAAEC;AACT,CAAC,CAAC;AAEK,MAAMC,kBAAkB,GAAGA,CAAA,KAAM,IAAAC,iBAAU,EAACP,eAAe,CAAC;AAACC,OAAA,CAAAK,kBAAA,GAAAA,kBAAA","ignoreList":[]}

package/lib/commonjs/MarkdownSession.js

@@ -0,0 +1,11 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createMarkdownSession = createMarkdownSession;
+var _reactNativeNitroModules = require("react-native-nitro-modules");
+function createMarkdownSession() {
+  return _reactNativeNitroModules.NitroModules.createHybridObject("MarkdownSession");
+}
+//# sourceMappingURL=MarkdownSession.js.map

package/lib/commonjs/MarkdownSession.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_reactNativeNitroModules","require","createMarkdownSession","NitroModules","createHybridObject"],"sourceRoot":"../../src","sources":["MarkdownSession.ts"],"mappings":";;;;;;AAAA,IAAAA,wBAAA,GAAAC,OAAA;AAKO,SAASC,qBAAqBA,CAAA,EAAoB;EACvD,OAAOC,qCAAY,CAACC,kBAAkB,CAAkB,iBAAiB,CAAC;AAC5E","ignoreList":[]}