react-native-enriched-markdown 0.7.0 → 0.7.2

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,215 @@
+<img src="https://github.com/user-attachments/assets/83cb462c-17df-4809-8b8a-fa4abb258cb3" alt="react-native-enriched-markdown by Software Mansion" width="100%">
+<a href="https://swm-delivery.com/www/delivery/ck-slug.php?zoneid=zone-gh-react-native-enriched-1&n=1"><img src="https://swm-delivery.com/www/images/zone-gh-react-native-enriched-1?n=1" /></a>
+<a href="https://swm-delivery.com/www/delivery/ck-slug.php?zoneid=zone-gh-react-native-enriched-2&n=1"><img src="https://swm-delivery.com/www/images/zone-gh-react-native-enriched-2?n=1" /></a>
+<a href="https://swm-delivery.com/www/delivery/ck-slug.php?zoneid=zone-gh-react-native-enriched-3&n=1"><img src="https://swm-delivery.com/www/images/zone-gh-react-native-enriched-3?n=1" /></a>
+
+# react-native-enriched-markdown
+
+`react-native-enriched-markdown` is a powerful React Native library that renders Markdown content as native text and provides a rich text input with Markdown output. It supports iOS, Android, macOS, and Web, and requires the New Architecture (Fabric) for native platforms.
+
+### EnrichedMarkdownText
+
+- ⚡ Fully native text rendering (no WebView)
+- 🌐 Web support via [react-native-web](https://necolas.github.io/react-native-web/) + [md4c](https://github.com/mity/md4c) compiled to WebAssembly
+- 🎯 High-performance Markdown parsing with [md4c](https://github.com/mity/md4c)
+- 📐 CommonMark standard compliant
+- 📊 GitHub Flavored Markdown (GFM)
+- 🧮 LaTeX math rendering (block `$$...$$` with `flavor="github"`, inline `$...$` in all flavors)
+- 🔀 [Markdown Streaming](docs/MARKDOWN_STREAMING.md) support (via [react-native-streamdown](https://github.com/software-mansion-labs/react-native-streamdown))
+- 🎨 Fully customizable styles for all elements
+- ✨ Text selection and copy support
+- 📌 Custom text selection context menu items
+- 🔗 Interactive link handling with [per-URL-pattern styling](docs/MENTIONS.md#link-variants-styling) (`linkVariants`)
+- 👤 Renders mentions as styled links (compatible with `EnrichedMarkdownTextInput` mention output)
+- 🙈 Spoiler text with animated particle overlay and tap-to-reveal
+- 🖼️ Native image interactions (iOS: Copy, Save to Camera Roll)
+- 🌐 Native platform features (Translate, Look Up, Search Web, Share)
+- 🗣️ Accessibility support (VoiceOver on iOS, TalkBack on Android, semantic HTML on web)
+- 🔄 Full RTL (right-to-left) support including text, lists, blockquotes, tables, and task lists
+
+### EnrichedMarkdownTextInput
+
+- ✏️ Rich text input with Markdown output
+- 🕹️ Imperative API for toggling styles and managing links
+- 📋 Native context menu with formatting submenu
+- 🔍 Real-time style state detection
+- 🔗 Auto-link detection with customizable regex
+- 🔄 Smart copy/paste with Markdown preservation
+- 🎨 Customizable bold, italic, and link colors
+- 👤 [Mentions](docs/MENTIONS.md) with configurable indicators, suggestion lifecycle events, and per-pattern link styling
+
+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)
+- [EnrichedMarkdownText](#enrichedmarkdowntext-1)
+  - [Usage](docs/TEXT.md#usage)
+  - [Supported Markdown Elements](docs/TEXT.md#supported-markdown-elements)
+  - [Copy Options](docs/TEXT.md#copy-options)
+  - [Accessibility](docs/TEXT.md#accessibility)
+  - [RTL Support](docs/TEXT.md#rtl-support)
+  - [Customizing Styles](docs/TEXT.md#customizing-styles)
+  - [LaTeX Math](docs/LATEX_MATH.md)
+  - [Image Caching](docs/IMAGE_CACHING.md)
+  - [Markdown Streaming](docs/MARKDOWN_STREAMING.md)
+- [EnrichedMarkdownTextInput](#enrichedmarkdowntextinput-1)
+  - [Usage](docs/INPUT.md#usage)
+  - [Inline Styles](docs/INPUT.md#inline-styles)
+  - [Links](docs/INPUT.md#links)
+  - [Auto-Link Detection](docs/INPUT.md#auto-link-detection)
+  - [Mentions](docs/MENTIONS.md)
+  - [Style Detection](docs/INPUT.md#style-detection)
+  - [Other Events](docs/INPUT.md#other-events)
+  - [Customizing Styles](docs/INPUT.md#customizing-enrichedmarkdowntextinput--styles)
+- [API Reference](#api-reference)
+- [Web Support](docs/WEB.md)
+- [macOS Support](docs/MACOS.md)
+- [Compatibility Table](#compatibility-table)
+- [Contributing](#contributing)
+- [Future Plans](#future-plans)
+- [License](#license)
+
+## Prerequisites
+
+**Native (iOS / Android / macOS)**
+
+- Requires [the React Native New Architecture (Fabric)](https://reactnative.dev/architecture/landing-page)
+- See [Compatibility Table](#compatibility-table) for supported React Native versions
+- macOS support via [react-native-macos](https://github.com/microsoft/react-native-macos) `0.81+`
+
+**Web**
+
+- Requires [`react-native-web`](https://necolas.github.io/react-native-web/) and Metro (or another bundler with `.web.tsx` platform resolution)
+- No New Architecture requirement — the web renderer runs entirely in JavaScript via WebAssembly
+- Only `EnrichedMarkdownText` is supported on web (`EnrichedMarkdownTextInput` is native-only)
+- LaTeX math requires the optional [`katex`](https://katex.org/) peer dependency
+
+## Installation
+
+### Web
+
+No steps beyond having `react-native-web` configured. For LaTeX math, install the optional peer dependency:
+
+```sh
+npm install katex
+# or
+yarn add katex
+```
+
+See [Web Support](docs/WEB.md) for full setup details, supported features, and prop behaviour.
+
+### Bare React Native app (iOS / Android)
+
+#### 1. Install the library
+
+```sh
+yarn add react-native-enriched-markdown
+```
+
+> [!TIP]
+> To try the latest features before they land in a stable release, install the nightly build:
+>
+> ```sh
+> yarn add react-native-enriched-markdown@nightly
+> ```
+>
+> Nightly versions are published to npm automatically and may contain breaking changes.
+
+#### 2. Install iOS / macOS dependencies
+
+The library includes native code so you will need to re-build the native app.
+
+```sh
+# iOS
+cd ios && bundle install && bundle exec pod install
+
+# macOS (react-native-macos)
+cd macos && 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>
+> ```
+
+## EnrichedMarkdownText
+
+See [EnrichedMarkdownText](docs/TEXT.md) for detailed documentation on usage examples, GFM tables, task lists, link handling, supported elements, copy options, accessibility, RTL support, and customizing styles. Mentions created by `EnrichedMarkdownTextInput` render as styled links — use [`linkVariants`](docs/MENTIONS.md#link-variants-styling) to customize their appearance.
+
+## EnrichedMarkdownTextInput
+
+See [EnrichedMarkdownTextInput](docs/INPUT.md) for detailed documentation on usage examples, inline styles, links, style detection, events, and customizing styles.
+
+## API Reference
+
+See the [API Reference](docs/API_REFERENCE.md) for a detailed overview of all the props, methods, and events available.
+
+## Web Support
+
+See [Web Support](docs/WEB.md) for details on supported features, web-specific prop behaviour, and known limitations.
+
+## macOS Support
+
+`react-native-enriched-markdown` supports macOS via [react-native-macos](https://github.com/microsoft/react-native-macos). See [macOS Support](docs/MACOS.md) for details on macOS-specific features, known limitations, and the example app.
+
+## Future Plans
+
+We're actively working on expanding the capabilities of `react-native-enriched-markdown`. Here's what's on the roadmap:
+
+- `EnrichedMarkdownTextInput`: headings, lists, blockquotes, code blocks, inline images
+- `EnrichedMarkdownTextInput` web support
+- macOS: block math rendering, VoiceOver accessibility, tail fade-in animation
+- Web: spoiler text, streaming animation, configurable link `target`, copy options (Copy as Markdown, multi-format clipboard)
+
+## Compatibility Table
+
+| | 0.82 | 0.83 | 0.84 | 0.85 | 0.86 |
+|---|:---:|:---:|:---:|:---:|:---:|
+| **nightly** | ⛔ | ✅ | ✅ | ✅ | ✅ |
+| **0.7.0** | ⛔ | ✅ | ✅ | ✅ | ✅ |
+| **0.6.0** | ⛔ | ✅ | ✅ | ✅ | ⛔ |
+| **0.5.0** | ⛔ | ✅ | ✅ | ✅ | ⛔ |
+| **0.4.x** | ✅ | ✅ | ✅ | ⛔ | ⛔ |
+| **0.3.0** | ✅ | ✅ | ✅ | ⛔ | ⛔ |
+
+## 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/app.plugin.js

@@ -1 +1,2 @@
-module.exports = require('./lib/module/plugin/withReactNativeEnrichedMarkdown');
+module.exports =
+  require('./plugin/build/withReactNativeEnrichedMarkdown').default;

package/docs/ACCESSIBILITY.md

@@ -0,0 +1,172 @@
+# Accessibility
+
+`react-native-enriched-markdown` provides comprehensive accessibility support for screen readers on both iOS and Android platforms.
+
+## Overview
+
+The library implements native accessibility features that enable screen readers (VoiceOver on iOS and TalkBack on Android) to properly navigate and understand Markdown content. This includes semantic labeling, custom navigation controls, and proper announcements for all supported elements.
+
+## Text Announcements
+
+Plain text paragraphs without inline links or images are announced as a single VoiceOver element per paragraph. Paragraphs containing links or images are segmented into text, link, and image parts so that each remains independently navigable. List items follow the same logic — a list item without inline specials is a single element, while one containing a link is split accordingly. Whitespace-only segments between elements are filtered out to avoid empty announcements.
+
+## Translating announcements — `accessibilityLabels`
+
+All strings spoken by the screen reader (list announcements, blockquote suffix, table rows, math equation prefix, and iOS rotor names) can be overridden via the optional `accessibilityLabels` prop on `EnrichedMarkdownText`. The defaults are English; consumers wire in their own i18n pipeline.
+
+```tsx
+import { EnrichedMarkdownText } from 'react-native-enriched-markdown';
+
+<EnrichedMarkdownText
+  markdown={markdown}
+  accessibilityLabels={{
+    list: {
+      bulletPoint: 'Punkt',
+      nestedBulletPoint: 'Eingebetteter Punkt',
+      orderedItem: 'Listenelement {n}',
+      nestedOrderedItem: 'Eingebettetes Listenelement {n}',
+    },
+    blockquote: {
+      quote: 'Zitat',
+      nestedQuote: 'Eingebettetes Zitat',
+    },
+    table: { row: 'Zeile {n}: {content}' },
+    math: { equation: 'Formel: {latex}' },
+    rotor: {
+      headings: 'Überschriften',
+      links: 'Links',
+      images: 'Bilder',
+    },
+  }}
+/>
+```
+
+Every field is optional. Any field you omit falls back to the English default below. Defaults are resolved on the JS side before being forwarded to native, so once you set even a single override the rest stay on their built-ins automatically.
+
+### Defaults
+
+| Field | Default | Platform |
+|---|---|---|
+| `list.bulletPoint` | `"Bullet point"` | iOS + Android |
+| `list.nestedBulletPoint` | `"Nested bullet point"` | iOS + Android |
+| `list.orderedItem` | `"List item {n}"` | iOS + Android |
+| `list.nestedOrderedItem` | `"Nested list item {n}"` | iOS + Android |
+| `blockquote.quote` | `"Blockquote"` | iOS + Android |
+| `blockquote.nestedQuote` | `"Nested blockquote"` | iOS + Android |
+| `table.row` | `"Row {n}: {content}"` | iOS + Android |
+| `math.equation` | `"Math: {latex}"` | iOS + Android |
+| `rotor.headings` | `"Headings"` | iOS only |
+| `rotor.links` | `"Links"` | iOS only |
+| `rotor.images` | `"Images"` | iOS only |
+
+### Placeholder syntax
+
+- `{n}` — 1-based index (list item number, table row index). Substituted at speak time.
+- `{content}` — comma-joined cell texts for a table row.
+- `{latex}` — math equation source.
+
+Placeholder names must be preserved in translations exactly. Defaults intentionally use the no-plural cardinal form (`"List item 2"`, `"Row 2"`) instead of ordinals or count-aware variants — a single template works in every language without per-locale plural rules.
+
+## Supported Elements
+
+| Element | VoiceOver (iOS) | TalkBack (Android) |
+|---------|-----------------|---------------------|
+| **Headings (h1-h6)** | Rotor navigation, `UIAccessibilityTraitHeader` → "heading" suffix | Reading controls navigation, `isHeading = true` → "heading" suffix |
+| **Links** | Rotor navigation, activatable, "link" suffix | Reading controls navigation, activatable, "link" suffix |
+| **Images** | Alt text announced, rotor navigation, "image" suffix | Alt text announced, "image" role |
+| **Unordered list items** | "Bullet point" / "Nested bullet point" appended (`accessibilityValue`) | Same string appended via `roleDescription` |
+| **Ordered list items** | "List item N" / "Nested list item N" appended | Same string appended via `roleDescription` |
+| **Blockquote content** | "Blockquote" / "Nested blockquote" appended | Same string appended via `roleDescription` |
+| **Table rows** | One focusable element per row, `"Row N: <cells>"` label, header row carries `UIAccessibilityTraitHeader` | One focusable overlay per row, same template, header row carries `setAccessibilityHeading(true)` |
+| **Math equations** | `"Math: <latex>"` (latex read verbatim — no TTS engine) | Same |
+
+## Architecture
+
+### iOS (VoiceOver)
+
+**Custom Rotors:**
+- **Headings Rotor**: Navigate between all headings in the document
+- **Links Rotor**: Jump between all links
+- **Images Rotor**: Navigate through all images
+
+Rotor names are translated via `accessibilityLabels.rotor.*`. When VoiceOver is active, a two-finger twist on the screen cycles through these rotors; swipe up/down jumps between elements of the currently-selected type.
+
+**Semantic Traits:**
+- Headings: `UIAccessibilityTraitHeader | UIAccessibilityTraitStaticText`
+- Links: `UIAccessibilityTraitLink | UIAccessibilityTraitStaticText`
+- Images: `UIAccessibilityTraitImage` (+ `UIAccessibilityTraitLink` if the image is linked)
+- Plain text: `UIAccessibilityTraitStaticText`
+
+List, blockquote and table row labels are exposed via `accessibilityValue` so VoiceOver speaks them after the main text.
+
+### Android (TalkBack)
+
+**Reading Controls:**
+- Headings, links, and images are available in TalkBack's reading controls for quick navigation
+- List items are properly announced with their position and type (ordered vs unordered)
+
+**Accessibility Node Info:**
+- Headings: `isHeading = true` — TalkBack speaks "heading" as the role
+- Links: `isClickable = true` + `roleDescription = "link"`
+- Images: alt text becomes `contentDescription`, `roleDescription = "image"`
+- List items: `CollectionItemInfoCompat` is set so TalkBack also announces position-in-collection; the localized label is appended via `roleDescription`
+- Blockquote content: localized label appended via `roleDescription` (combined with link/list role when nested)
+- Table rows: one transparent overlay per row exposes the row's joined content via `contentDescription`; header rows additionally call `ViewCompat.setAccessibilityHeading(true)`
+- Math: `MathContainerView` exposes the full equation via `contentDescription` (`"Math: <latex>"` template)
+
+## Element Details
+
+### Headings
+
+Headings are marked with the platform's "heading" trait/role. Screen readers announce the heading text followed by "heading" — the heading **level** is not spoken by default (the trait already conveys "this is a heading"; spelling the level out adds friction). The level remains available programmatically so platform navigation controls (rotor on iOS, reading controls on Android) can jump between headings of any level.
+
+**Example announcement:**
+- "Welcome to Markdown, heading"
+- "Getting Started, heading"
+
+### Links
+
+Links are fully interactive and can be activated through screen reader gestures. The link text is announced followed by "link".
+
+**Example announcement:**
+- "React Native, link"
+
+### Images
+
+Images with alt text announce the alt text + "image". Images without alt text are intentionally **silent** (no fallback string) — if you want them announced, supply alt text in the markdown source.
+
+**Example announcement:**
+- "Misty forest at sunrise, image"
+- *(silent for `![](url)`)*
+
+### Lists
+
+List items are announced with their position and type:
+
+- Unordered: `"<text>, Bullet point"` (top-level) or `"<text>, Nested bullet point"` (deeper)
+- Ordered: `"<text>, List item 1"`, `"<text>, List item 2"`, etc.
+
+Override via `accessibilityLabels.list.*`. The `{n}` placeholder is substituted with the 1-based item number.
+
+### Blockquotes
+
+Content inside a blockquote gets the blockquote label appended (after any list or link suffix). Nested blockquotes use the `nestedQuote` label instead.
+
+**Example announcement:**
+- `"This is a quoted line., Blockquote"`
+- `"Nested quote text., Nested blockquote"`
+
+### Tables
+
+Tables expose one focusable element per row (header included), labeled with the `table.row` template. The default reads `"Row 1: Column A, Column B"` for the header, `"Row 2: Cell A1, Cell B1"` for the first body row, and so on. The header row additionally carries the heading trait/role.
+
+### Math
+
+Each math block exposes a single focusable element labeled `"Math: <latex>"`. The library does **not** convert LaTeX to natural language — the screen reader reads the raw LaTeX source. If you need spoken math, plug in a LaTeX→speech library on the consumer side and translate the labels accordingly.
+
+## Known Limitations
+
+- **Inline formatting** (bold / italic / underline / strikethrough / inline code / spoiler) is not split into separate accessibility elements — the entire paragraph is read as one element, exactly as the surrounding text. Screen readers don't apply visual emphasis to bold/italic by default.
+- **macOS** screen-reader support is still pending — `MarkdownAccessibilityElementBuilder.m` ships a no-op stub for macOS. Tracked as a TODO; iOS implementation can serve as a reference.
+- **Android** has no rotor concept — `accessibilityLabels.rotor.*` is silently ignored on that platform.
+- **iOS** blockquote backgrounds may break at link boundaries instead of spanning the full line. Visual only; doesn't affect accessibility.