react-native-enriched-markdown 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 Software Mansion
+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

@@ -0,0 +1,551 @@
+<img src="https://github.com/user-attachments/assets/922e57b6-98b7-4ad4-a270-838c7341d102" alt="react-native-enriched-markdown by Software Mansion" width="100%">
+
+# react-native-enriched-markdown
+
+`react-native-enriched-markdown` is a powerful React Native library that renders Markdown content as native text:
+
+- ⚡ Fully native text rendering (no WebView)
+- 🎯 High-performance Markdown parsing with [md4c](https://github.com/mity/md4c)
+- 📐 CommonMark standard compliant
+- 🎨 Fully customizable styles for all elements
+- 📱 iOS and Android support
+- 🏛 Supports only the New Architecture (Fabric)
+- ✨ Text selection and copy support
+- 🔗 Interactive link handling
+- 🖼️ Native image interactions (iOS: Copy, Save to Camera Roll)
+- 🌐 Native platform features (Translate, Look Up, Search Web, Share)
+- 🗣️ Accessibility support (VoiceOver & TalkBack)
+
+Since 2012 [Software Mansion](https://swmansion.com) is a software agency with experience in building web and mobile apps. We are Core React Native Contributors and experts in dealing with all kinds of React Native issues.
+We can help you build your next dream product –
+[Hire us](https://swmansion.com/contact/projects?utm_source=react-native-enriched-markdown&utm_medium=readme).
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Supported Markdown Elements](#supported-markdown-elements)
+- [Link Handling](#link-handling)
+- [Copy Options](#copy-options)
+- [Accessibility](#accessibility)
+- [Styling Architecture](#styling-architecture)
+- [Customizing Styles](#customizing-styles)
+- [API Reference](#api-reference)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Prerequisites
+
+- `react-native-enriched-markdown` currently supports only Android and iOS platforms
+- It works only with [the React Native New Architecture (Fabric)](https://reactnative.dev/architecture/landing-page) and supports following React Native releases: `0.81`, `0.82`, `0.83` and `0.84`
+
+## Installation
+
+### Bare React Native app
+
+#### 1. Install the library
+
+```sh
+yarn add react-native-enriched-markdown
+```
+
+#### 2. Install iOS dependencies
+
+The library includes native code so you will need to re-build the native app.
+
+```sh
+cd ios && bundle install && bundle exec pod install
+```
+
+### Expo app
+
+#### 1. Install the library
+
+```sh
+npx expo install react-native-enriched-markdown
+```
+
+#### 2. Run prebuild
+
+The library includes native code so you will need to re-build the native app.
+
+```sh
+npx expo prebuild
+```
+
+> [!NOTE]
+> The library won't work in Expo Go as it needs native changes.
+
+> [!IMPORTANT]
+> **iOS: Save to Camera Roll**
+>
+> If your Markdown content includes images and you want users to save them to their photo library, add the following to your `Info.plist`:
+> ```xml
+> <key>NSPhotoLibraryAddUsageDescription</key>
+> <string>This app needs access to your photo library to save images.</string>
+> ```
+
+## Usage
+
+Here's a simple example of rendering Markdown content:
+
+```tsx
+import { EnrichedMarkdownText } from 'react-native-enriched-markdown';
+import { Linking } from 'react-native';
+
+const markdown = `
+# Welcome to Markdown!
+
+This is a paragraph with **bold**, *italic*, and [links](https://reactnative.dev).
+
+- List item one
+- List item two
+  - Nested item
+
+\`\`\`javascript
+const greeting = 'Hello, World!';
+console.log(greeting);
+\`\`\`
+`;
+
+export default function App() {
+  const handleLinkPress = (event: { nativeEvent: { url: string } }) => {
+    Linking.openURL(event.nativeEvent.url);
+  };
+
+  return (
+    <EnrichedMarkdownText
+      markdown={markdown}
+      onLinkPress={handleLinkPress}
+    />
+  );
+}
+```
+
+## Supported Markdown Elements
+
+`react-native-enriched-markdown` supports a comprehensive set of Markdown elements:
+
+### Block Elements
+
+| Element | Syntax | Description |
+|---------|--------|-------------|
+| Headings | `# H1` to `###### H6` | Six levels of headings |
+| Paragraphs | Plain text | Regular text paragraphs |
+| Blockquotes | `> Quote` | Quoted text with unlimited nesting |
+| Code Blocks | ` ``` code ``` ` | Multi-line code blocks |
+| Unordered Lists | `- Item`, `* Item`, or `+ Item` | Bullet lists with unlimited nesting |
+| Ordered Lists | `1. Item` | Numbered lists with unlimited nesting |
+| Thematic Break | `---`, `***`, or `___` | Visual separator line |
+| Images | `![alt](url)` | Block-level images |
+
+### Inline Elements
+
+| Element | Syntax | Description |
+|---------|--------|-------------|
+| Bold | `**text**` or `__text__` | Strong emphasis |
+| Italic | `*text*` or `_text_` | Emphasis |
+| Underline | `_text_` | Underlined text (requires `md4cFlags`) |
+| Strikethrough | `~~text~~` | Strikethrough text |
+| Bold + Italic | `***text***`, `___text___`, etc. | Combined emphasis |
+| Links | `[text](url)` | Clickable links |
+| Inline Code | `` `code` `` | Inline code snippets |
+| Inline Images | `![alt](url)` | Images within text flow |
+
+> **Note:** Underscore syntax (`__text__`, `_text_`) works for bold/italic by default. Enable underline via `md4cFlags={{ underline: true }}` to treat `_text_` as underline instead of emphasis.
+
+### Nested Lists Example
+
+```markdown
+- First level
+  - Second level
+    - Third level
+      - Fourth level (unlimited depth!)
+
+1. First item
+   1. Nested numbered
+      1. Deep nested
+   2. Another nested
+2. Second item
+```
+
+### Nested Blockquotes Example
+
+```markdown
+> Level 1 quote
+> > Level 2 nested
+> > > Level 3 nested (unlimited depth!)
+```
+
+## Link Handling
+
+Links in Markdown are interactive and can be handled with the `onLinkPress` and `onLinkLongPress` callbacks:
+
+```tsx
+<EnrichedMarkdownText
+  markdown="Check out [React Native](https://reactnative.dev)!"
+  onLinkPress={({ url }) => {
+    Alert.alert('Link pressed', url);
+    Linking.openURL(url);
+  }}
+  onLinkLongPress={({ url }) => {
+    Alert.alert('Link long pressed', url);
+  }}
+/>
+```
+
+### Link Preview (iOS)
+
+By default, long-pressing a link on iOS shows the native system link preview. When you provide `onLinkLongPress`, the system preview is automatically disabled so your handler can fire instead.
+
+You can also control this behavior explicitly with the `enableLinkPreview` prop:
+
+```tsx
+// Disable system link preview without providing a handler
+<EnrichedMarkdownText
+  markdown={content}
+  enableLinkPreview={false}
+/>
+```
+
+## Copy Options
+
+When text is selected, `react-native-enriched-markdown` provides enhanced copy functionality through the context menu on both platforms.
+
+### Smart Copy
+
+The default **Copy** action copies the selected text with rich formatting support:
+
+#### iOS
+
+Copies in multiple formats simultaneously — receiving apps pick the richest format they support:
+
+| Format | Description |
+|--------|-------------|
+| **Plain Text** | Basic text without formatting |
+| **Markdown** | Original Markdown syntax preserved |
+| **HTML** | Rich HTML representation |
+| **RTF** | Rich Text Format for apps like Notes, Pages |
+| **RTFD** | RTF with embedded images |
+
+#### Android
+
+Copies as both **Plain Text** and **HTML** — apps that support rich text (like Gmail, Google Docs) will preserve formatting.
+
+### Copy as Markdown
+
+A dedicated **Copy as Markdown** option is available in the context menu on both platforms. This copies only the Markdown source text, useful when you want to preserve the original syntax.
+
+### Copy Image URL
+
+When selecting text that contains images, a **Copy Image URL** option appears to copy the image's source URL. On Android, if multiple images are selected, all URLs are copied (one per line).
+
+## Accessibility
+
+`react-native-enriched-markdown` provides accessibility support for screen readers on both platforms — VoiceOver on iOS and TalkBack on Android.
+
+### Supported Elements
+
+| Element | VoiceOver (iOS) | TalkBack (Android) |
+|---------|-----------------|---------------------|
+| **Headings (h1-h6)** | Rotor navigation | Reading controls navigation |
+| **Links** | Rotor navigation, activatable | Reading controls navigation, activatable |
+| **Images** | Alt text announced, rotor navigation | Alt text announced |
+| **List items** | Position announced (e.g., "bullet point", "list item 1") | Position announced |
+| **Nested lists** | Proper depth handling | "Nested" prefix for deeper items |
+
+## Styling Architecture
+
+Understanding how `react-native-enriched-markdown` handles styling helps you create consistent, well-designed Markdown content.
+
+### Block vs Inline Elements
+
+Markdown elements are divided into two categories:
+
+#### Block Elements
+
+Block elements are structural containers that define the layout. Each block has its own typography settings (`fontSize`, `fontFamily`, `fontWeight`, `color`, `lineHeight`, `marginTop`, `marginBottom`).
+
+| Block Type | Description |
+|------------|-------------|
+| `paragraph` | Default text container |
+| `h1` - `h6` | Heading levels |
+| `blockquote` | Quoted content with accent bar |
+| `list` | Ordered and unordered lists |
+| `codeBlock` | Multi-line code containers |
+
+#### Inline Elements
+
+Inline elements modify text within blocks. They inherit the parent block's base typography and apply additional styling.
+
+| Inline Type | Inherits From | Adds |
+|-------------|---------------|------|
+| `strong` | Parent block | Bold weight, optional color |
+| `em` | Parent block | Italic style, optional color |
+| `strikethrough` | Parent block | Strike line with custom color (iOS only) |
+| `underline` | Parent block | Underline with custom color (iOS only) |
+| `code` | Parent block | Monospace font, background |
+| `link` | Parent block | Color, underline |
+
+### Style Inheritance
+
+Inline styles automatically inherit from their containing block:
+
+```
+Heading (h2: fontSize 24, color blue)
+└── Strong text inherits → fontSize 24, color blue + bold weight
+└── Link inherits → fontSize 24 + link color + underline
+
+List item (list: fontSize 16, color gray)
+└── Emphasis inherits → fontSize 16, color gray + italic style
+└── Inline code inherits → fontSize 16 + code background
+```
+
+### Nested Elements
+
+Some elements support unlimited nesting depth with automatic indentation:
+
+- **Blockquotes**: Each level adds a new accent bar
+- **Unordered Lists**: Each level indents with `marginLeft`
+- **Ordered Lists**: Each level indents and maintains separate numbering
+
+```markdown
+> Level 1
+> > Level 2 (inherits L1 styles + additional indent)
+> > > Level 3 (inherits L2 styles + additional indent)
+```
+
+### Platform Defaults
+
+The library provides sensible defaults optimized for each platform:
+
+| Property | iOS | Android |
+|----------|-----|---------|
+| System Font | SF Pro | Roboto |
+| Monospace Font | Menlo | monospace |
+| Line Height | Tighter (0.75x multiplier) | Standard |
+
+## Customizing Styles
+
+The library provides sensible default styles for all Markdown elements out of the box. You can override any of these defaults using the `markdownStyle` prop — only specify the properties you want to change:
+
+```tsx
+<EnrichedMarkdownText
+  markdown={content}
+  markdownStyle={{
+    paragraph: {
+      fontSize: 16,
+      color: '#333',
+      lineHeight: 24,
+    },
+    h1: {
+      fontSize: 32,
+      fontWeight: 'bold',
+      color: '#000',
+      marginBottom: 16,
+      textAlign: 'center',
+    },
+    h2: {
+      fontSize: 24,
+      fontWeight: '600',
+      marginBottom: 12,
+      textAlign: 'left',
+    },
+    strong: {
+      color: '#000',
+    },
+    em: {
+      color: '#666',
+    },
+    strikethrough: {
+      color: '#999',
+    },
+    underline: {
+      color: '#333',
+    },
+    link: {
+      color: '#007AFF',
+      underline: true,
+    },
+    code: {
+      color: '#E91E63',
+      backgroundColor: '#F5F5F5',
+      borderColor: '#E0E0E0',
+    },
+    codeBlock: {
+      fontSize: 14,
+      fontFamily: 'monospace',
+      backgroundColor: '#1E1E1E',
+      color: '#D4D4D4',
+      padding: 16,
+      borderRadius: 8,
+      marginBottom: 16,
+    },
+    blockquote: {
+      borderColor: '#007AFF',
+      borderWidth: 3,
+      backgroundColor: '#F0F8FF',
+      marginBottom: 12,
+    },
+    list: {
+      fontSize: 16,
+      bulletColor: '#007AFF',
+      bulletSize: 6,
+      markerColor: '#007AFF',
+      gapWidth: 8,
+      marginLeft: 20,
+    },
+    image: {
+      borderRadius: 8,
+      marginBottom: 12,
+    },
+    inlineImage: {
+      size: 20,
+    },
+  }}
+/>
+```
+
+> [!NOTE]
+> **Performance:** Memoize the `markdownStyle` prop with `useMemo` to avoid unnecessary re-renders:
+> ```tsx
+> import type { MarkdownStyle } from 'react-native-enriched-markdown';
+>
+> const markdownStyle: MarkdownStyle = useMemo(() => ({
+>   paragraph: { fontSize: 16 },
+>   h1: { fontSize: 32 },
+> }), []);
+> ```
+
+### Style Properties Reference
+
+#### Block Styles (paragraph, h1-h6, blockquote, list, codeBlock)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `fontSize` | `number` | Font size in points |
+| `fontFamily` | `string` | Font family name |
+| `fontWeight` | `string` | Font weight |
+| `color` | `string` | Text color |
+| `marginTop` | `number` | Top margin |
+| `marginBottom` | `number` | Bottom margin |
+| `lineHeight` | `number` | Line height |
+
+#### Paragraph and Heading-specific (paragraph, h1-h6)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `textAlign` | `'auto' \| 'left' \| 'right' \| 'center' \| 'justify'` | Text alignment (default: `'left'`) |
+
+#### Blockquote-specific
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `borderColor` | `string` | Left border color |
+| `borderWidth` | `number` | Left border width |
+| `gapWidth` | `number` | Gap between border and text |
+| `backgroundColor` | `string` | Background color |
+
+#### List-specific
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `bulletColor` | `string` | Bullet point color |
+| `bulletSize` | `number` | Bullet point size |
+| `markerColor` | `string` | Number marker color |
+| `markerFontWeight` | `string` | Number marker font weight |
+| `gapWidth` | `number` | Gap between marker and text |
+| `marginLeft` | `number` | Left margin for nesting |
+
+#### Code Block-specific
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `backgroundColor` | `string` | Background color |
+| `borderColor` | `string` | Border color |
+| `borderRadius` | `number` | Corner radius |
+| `borderWidth` | `number` | Border width |
+| `padding` | `number` | Inner padding |
+
+#### Inline Code-specific
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `color` | `string` | Text color |
+| `backgroundColor` | `string` | Background color |
+| `borderColor` | `string` | Border color |
+
+#### Link-specific
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `color` | `string` | Link text color |
+| `underline` | `boolean` | Show underline |
+
+#### Strikethrough-specific
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `color` | `string` | Strikethrough line color (iOS only) |
+
+#### Underline-specific
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `color` | `string` | Underline color (iOS only) |
+
+#### Image-specific
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `height` | `number` | Image height |
+| `borderRadius` | `number` | Corner radius |
+| `marginTop` | `number` | Top margin |
+| `marginBottom` | `number` | Bottom margin |
+
+#### Inline Image-specific
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `size` | `number` | Image size (square) |
+
+#### Thematic Break (Horizontal Rule)-specific
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `color` | `string` | Line color |
+| `height` | `number` | Line thickness |
+| `marginTop` | `number` | Top margin |
+| `marginBottom` | `number` | Bottom margin |
+
+## API Reference
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `markdown` | `string` | Required | The Markdown content to render |
+| `markdownStyle` | `MarkdownStyle` | `{}` | Style configuration for Markdown elements |
+| `containerStyle` | `ViewStyle` | - | Style for the container view |
+| `onLinkPress` | `(event: LinkPressEvent) => void` | - | Callback when a link is pressed. Access URL via `event.url` |
+| `onLinkLongPress` | `(event: LinkLongPressEvent) => void` | - | Callback when a link is long pressed. Access URL via `event.url`. On iOS, automatically disables the system link preview |
+| `enableLinkPreview` | `boolean` | `true` | Controls the native link preview on long press (iOS only). Automatically set to `false` when `onLinkLongPress` is provided |
+| `selectable` | `boolean` | `true` | Whether text can be selected |
+| `md4cFlags` | `Md4cFlags` | `{ underline: false }` | Configuration for md4c parser extension flags |
+| `allowFontScaling` | `boolean` | `true` | Whether fonts should scale to respect Text Size accessibility settings |
+| `maxFontSizeMultiplier` | `number` | `undefined` | Maximum font scale multiplier when `allowFontScaling` is enabled |
+| `allowTrailingMargin` | `boolean` | `false` | Whether to preserve the bottom margin of the last block element |
+
+## Contributing
+
+See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
+
+## License
+
+`react-native-enriched-markdown` library is licensed under [The MIT License](./LICENSE).
+
+---
+Built by [Software Mansion](https://swmansion.com/).
+
+[<img width="128" height="69" alt="Software Mansion Logo" src="https://github.com/user-attachments/assets/f0e18471-a7aa-4e80-86ac-87686a86fe56" />](https://swmansion.com/)

package/ReactNativeEnrichedMarkdown.podspec

@@ -0,0 +1,27 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "ReactNativeEnrichedMarkdown"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/software-mansion-labs/react-native-enriched-markdown.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,cpp}", "cpp/md4c/*.{c,h}", "cpp/parser/*.{hpp,cpp}"
+  s.private_header_files = "ios/**/*.h"
+
+  # Set header search paths to cpp/md4c and cpp/parser, add preprocessor definitions
+  s.pod_target_xcconfig = {
+    'HEADER_SEARCH_PATHS' => '"$(PODS_TARGET_SRCROOT)/cpp/md4c" "$(PODS_TARGET_SRCROOT)/cpp/parser" "$(PODS_TARGET_SRCROOT)/ios/internals"',
+    'GCC_PREPROCESSOR_DEFINITIONS' => '$(inherited) MD4C_USE_UTF8=1',
+    'CLANG_CXX_LANGUAGE_STANDARD' => 'c++17'
+  }
+
+  install_modules_dependencies(s)
+end

package/android/build.gradle

@@ -0,0 +1,101 @@
+buildscript {
+  ext.getExtOrDefault = {name ->
+    return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties['EnrichedMarkdown_' + name]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+plugins {
+  id "org.jlleitschuh.gradle.ktlint" version "14.0.1"
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+apply plugin: "com.facebook.react"
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["EnrichedMarkdown_" + name]).toInteger()
+}
+
+android {
+  namespace "com.swmansion.enriched.markdown"
+
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs += [
+        "generated/java",
+        "generated/jni"
+      ]
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+def kotlin_version = getExtOrDefault("kotlinVersion")
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+  // Baseline Profile installer for AOT compilation hints
+  implementation "androidx.profileinstaller:profileinstaller:1.3.1"
+}
+
+ktlint {
+  version = "1.8.0"
+  debug = false
+  verbose = true
+  android = true
+  outputToConsole = true
+  ignoreFailures = false
+  enableExperimentalRules = false
+  filter {
+    exclude("**/build/**")
+    exclude("**/generated/**")
+  }
+}
+
+react {
+  jsRootDir = file("../src/")
+  libraryName = "EnrichedMarkdownText"
+  codegenJavaPackageName = "com.swmansion.enriched.markdown"
+}