react-native-enriched-markdown 0.7.0 → 0.7.2

package/docs/COPY_OPTIONS.md

@@ -0,0 +1,127 @@
+# 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).
+
+## Controlling Built-in Menu Items
+
+Use `selectionMenuConfig` to hide built-in selection menu actions while keeping the native menu and any `contextMenuItems` intact. Each item takes an object — `{ enabled }` toggles visibility:
+
+```tsx
+<EnrichedMarkdownText
+  markdown={content}
+  selectionMenuConfig={{
+    copyAsMarkdown: { enabled: false },
+    copyImageUrl: { enabled: false },
+  }}
+/>
+```
+
+`EnrichedMarkdownTextInput` supports the same `{ enabled, label }` shape. In addition to `copyAsMarkdown`, the input's `selectionMenuConfig` exposes the built-in **Format** submenu, and `formatMenuConfig` controls the items inside it:
+
+```tsx
+<EnrichedMarkdownTextInput
+  selectionMenuConfig={{
+    format: { enabled: false },
+    copyAsMarkdown: { enabled: false },
+  }}
+  formatMenuConfig={{
+    spoiler: { enabled: false },
+    link: { enabled: false },
+  }}
+/>
+```
+
+## Localizing Menu Labels
+
+The built-in copy actions are shown in English by default (**Copy**, **Copy as
+Markdown**, **Copy Image URL**). Set a `label` on each `selectionMenuConfig` item
+to translate it so it matches the rest of your app's UI — typically wired to your
+i18n library:
+
+```tsx
+<EnrichedMarkdownText
+  markdown={content}
+  selectionMenuConfig={{
+    copy: { label: t('copy') }, // "Copia"
+    copyAsMarkdown: { label: t('copyAsMarkdown') }, // "Copia come Markdown"
+    copyImageUrl: {
+      label: t('copyImageUrl'), // "Copia URL immagine" (single image)
+      pluralLabels: {
+        // Forms for multiple images, chosen with Intl.PluralRules.
+        other: t('copyImageUrls'), // "Copia {count} URL immagine"
+      },
+    },
+  }}
+/>
+```
+
+Notes:
+
+- Any `label` left `undefined` keeps its English default, so you can override
+  only the strings you need.
+- `pluralLabels` provides the forms used when several images are selected. The
+  right form is picked at runtime from the number of selected images with
+  `Intl.PluralRules` (resolved against the app's default locale), keyed by CLDR
+  plural category (`zero`, `one`, `two`, `few`, `many`, `other`). Only `other` is
+  required; any category left `undefined` falls back to it. The `{count}` token
+  is replaced by the number of selected images.
+- The labels apply to the main text selection menu as well as the table and math
+  block copy menus.
+- OS-provided actions (Look Up, Translate…) and the system **Cut / Paste /
+  Select All** items are localized by the platform and are not affected by this
+  config.
+
+### Input (`EnrichedMarkdownTextInput`)
+
+The input exposes the same `{ enabled, label }` shape on `selectionMenuConfig`
+(for the **Format** submenu title and **Copy as Markdown** action) and on
+`formatMenuConfig` (for each item inside the Format submenu — Bold, Italic,
+Underline, Strikethrough, Spoiler, Link):
+
+```tsx
+<EnrichedMarkdownTextInput
+  selectionMenuConfig={{
+    format: { label: t('format') },
+    copyAsMarkdown: { label: t('copyAsMarkdown') },
+  }}
+  formatMenuConfig={{
+    bold: { label: t('bold') },
+    italic: { label: t('italic') },
+    underline: { label: t('underline') },
+    strikethrough: { label: t('strikethrough') },
+    spoiler: { label: t('spoiler') },
+    link: { label: t('link') },
+  }}
+/>
+```
+
+> The simplest way to keep these in sync with the device language is to feed the
+> same translation function you already use for the rest of your UI.

package/docs/ELEMENTS_STRUCTURE.md

@@ -0,0 +1,112 @@
+# Element Structure
+
+Markdown elements in `react-native-enriched-markdown` are organized into block and inline categories, each with distinct rendering behaviors.
+
+## Supported Markdown Elements
+
+`react-native-enriched-markdown` supports a comprehensive set of Markdown elements:
+
+### Block Elements
+
+| Element | Syntax | Style Property | Description |
+|---------|--------|----------------|-------------|
+| Headings | `# H1` to `###### H6` | `h1` - `h6` | Six levels of headings |
+| Paragraphs | Plain text | `paragraph` | Default text container |
+| Blockquotes | `> Quote` | `blockquote` | Quoted content with accent bar, unlimited nesting |
+| Code Blocks | ` ``` code ``` ` | `codeBlock` | Multi-line code containers |
+| Unordered Lists | `- Item`, `* Item`, or `+ Item` | `list` | Bullet lists with unlimited nesting |
+| Ordered Lists | `1. Item` | `list` | Numbered lists with unlimited nesting |
+| Task Lists | `- [x] Done`, `- [ ] Todo` | `taskList` | Interactive checkboxes (requires `flavor="github"`) |
+| Thematic Break | `---`, `***`, or `___` | `thematicBreak` | Horizontal rule separator |
+| Images | `![alt](url)` | `image` | Block-level images with spacing |
+| Tables | `| col | col |` | `table` | GFM tables with alignment support (requires `flavor="github"`) |
+| Math Block | `$$...$$` | `math` | Block-level LaTeX math (display equations) (requires `flavor="github"`) |
+
+### Inline Elements
+
+| Element | Syntax | Style Property | Inherits From | Adds |
+|---------|--------|----------------|---------------|------|
+| Bold | `**text**` or `__text__` | `strong` | Parent block | Bold weight, optional color |
+| Italic | `*text*` or `_text_` | `em` | Parent block | Italic style, optional color |
+| Underline | `_text_` | `underline` | Parent block | Underline with custom color (iOS only; requires `md4cFlags`) |
+| Strikethrough | `~~text~~` | `strikethrough` | Parent block | Strike line with custom color (iOS only) |
+| Bold + Italic | `***text***`, `___text___`, etc. | `strong` + `em` | Parent block | Combined emphasis |
+| Links | `[text](url)` | `link` | Parent block | Optional font family, color, underline |
+| Inline Code | `` `code` `` | `code` | Parent block | Monospace font, background, optional fontSize |
+| Inline Images | `![alt](url)` | `inlineImage` | N/A | Inline images within text flow |
+| Inline Math | `$...$` | `inlineMath` | Parent block | LaTeX math rendered within the text flow |
+| Spoiler | `\|\|text\|\|` | `spoiler` | Parent block | Text concealed behind animated particle overlay, tap to reveal. Can wrap inline text or entire blocks (e.g. a full paragraph) |
+| Superscript | `^text^` | `superscript` | Parent block | Raised text at a reduced font size (requires `md4cFlags={{ superscript: true }}`) |
+| Subscript | `~text~` | `subscript` | Parent block | Lowered text at a reduced font size (requires `md4cFlags={{ subscript: true }}`) |
+
+> **Note:** Spoiler syntax (`||text||`) is always enabled. Any double-pipe delimiters in your content will be parsed as spoilers — for example, `a || b || c` would render `b` as a spoiler span rather than plain text.
+
+> **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.
+
+> **Note:** Enabling subscript (`md4cFlags={{ subscript: true }}`) changes the behaviour of single tildes — `~text~` becomes subscript instead of strikethrough. Double tildes (`~~text~~`) continue to work as strikethrough regardless.
+
+### 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!)
+```
+
+### Superscript and Subscript Examples
+
+```markdown
+E = mc^2^
+
+H~2~O   H~2~SO~4~
+
+^14^C dating  (isotope notation)
+
+H~3~O^+^  (mixed superscript and subscript)
+```
+
+> Superscript and subscript can be nested inside other inline elements such as bold, italic, and links. They cannot be nested inside each other.
+
+## Block vs Inline Elements
+
+Markdown elements are divided into two categories:
+
+### Block Elements
+
+Block elements are structural containers that define the layout and establish their own typography context.
+
+### Inline Elements
+
+Inline elements modify text within blocks and apply additional styling on top of the block's typography.
+
+## Images: Block vs Inline
+
+Images are automatically detected as block or inline based on context:
+
+- **Block images**: When an image is the only content in a paragraph (standalone), it's treated as a block image and uses block-level spacing
+- **Inline images**: When an image appears alongside other text content, it's treated as inline and aligns with the text baseline
+
+You don't need to specify which type—the renderer automatically determines this based on the image's position in the content.
+
+## 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

package/docs/IMAGE_CACHING.md

@@ -0,0 +1,25 @@
+# Image Caching
+
+Images in Markdown content are loaded, cached, and reused automatically — no configuration required.
+
+## Cache Layers
+
+The library uses a three-tier caching strategy on both platforms:
+
+| Layer | Android | iOS | Size |
+|---|---|---|---|
+| **Originals (memory)** | `LruCache` | `NSCache` | 20 MB |
+| **Processed variants (memory)** | `LruCache` | `NSCache` | 30 MB |
+| **Disk** | OkHttp `Cache` | `NSURLCache` | 100 MB |
+
+- **Original cache** stores decoded images keyed by URL. On Android, large images are downsampled to screen width during decode to reduce peak memory.
+- **Processed cache** stores scaled and clipped variants keyed by URL + dimensions + border radius, so repeated layouts with the same geometry skip all image processing.
+- **Disk cache** persists raw HTTP responses across app launches, respecting standard HTTP cache headers.
+
+## Request Deduplication
+
+When multiple components request the same image URL simultaneously (e.g. during a re-render), only one network request is made. All pending callbacks are coalesced and dispatched together once the download completes.
+
+## Instance Reuse
+
+`ImageSpan` (Android) and `ENRMImageAttachment` (iOS) instances are reused across re-renders for the same URL, avoiding redundant object allocation and image reloading.

package/docs/INPUT.md

@@ -0,0 +1,233 @@
+# EnrichedMarkdownTextInput
+
+`EnrichedMarkdownTextInput` is a rich text input component that outputs Markdown. It is an uncontrolled input — it doesn't use any state or props to store its value, but instead directly interacts with the underlying platform-specific components. Thanks to this, the component is really performant and simple to use.
+
+## Usage
+
+Here's a simple example of an input that lets you toggle bold on its text and shows whether bold is currently active via the button color.
+
+```tsx
+import { useRef, useState } from 'react';
+import { View, Button, StyleSheet } from 'react-native';
+import {
+  EnrichedMarkdownTextInput,
+  type EnrichedMarkdownTextInputInstance,
+  type StyleState,
+} from 'react-native-enriched-markdown';
+
+export default function App() {
+  const ref = useRef<EnrichedMarkdownTextInputInstance>(null);
+  const [state, setState] = useState<StyleState | null>(null);
+
+  return (
+    <View style={styles.container}>
+      <EnrichedMarkdownTextInput
+        ref={ref}
+        placeholder="Type here..."
+        onChangeState={setState}
+        style={styles.input}
+      />
+      <View style={styles.toolbar}>
+        <Button
+          title={state?.bold.isActive ? 'Unbold' : 'Bold'}
+          color={state?.bold.isActive ? 'green' : 'gray'}
+          onPress={() => ref.current?.toggleBold()}
+        />
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1, justifyContent: 'center', alignItems: 'center' },
+  input: { width: '100%', fontSize: 20, padding: 10, maxHeight: 200, backgroundColor: 'lightgray' },
+  toolbar: { flexDirection: 'row', gap: 8, marginTop: 8 },
+});
+```
+
+Summary of what happens here:
+
+1. Any methods imperatively called on the input to e.g. toggle some style must be used through a `ref` of `EnrichedMarkdownTextInputInstance` type. Here, `toggleBold` method that is called on the button press calls `ref.current?.toggleBold()`, which toggles the bold styling within the current selection.
+2. All style state information is emitted by the `onChangeState` callback. The callback payload provides a nested object for each style (e.g., `bold`, `italic`), containing an `isActive` property to guide your UI logic — indicating if the style is currently applied (highlight the button).
+
+## Inline Styles
+
+Supported styles:
+
+- bold
+- italic
+- underline
+- strikethrough
+- spoiler
+
+Each of the styles can be toggled the same way as in the example from [usage section](#usage); call a proper `toggle` function on the component ref.
+
+Each call toggles the style within the current text selection. They are being toggled on exactly the character range that is currently selected. When toggling the style with just the cursor in place (no selection), the style is ready to be used and will be applied to the next characters that the user inputs.
+
+Styles are also available through the built-in native format bar that appears on text selection, and through the system context menu.
+
+## Links
+
+Links are a piece of text with a URL attributed to it. They can be managed by calling methods on the input ref:
+
+- [`setLink(url)`](API_REFERENCE.md#setlinkurl-string) — applies a link to the currently selected text.
+- [`insertLink(text, url)`](API_REFERENCE.md#insertlinktext-string-url-string) — inserts a new link at the cursor position with the given text and URL. Useful when there is no selection.
+- [`removeLink()`](API_REFERENCE.md#removelink) — removes the link from the current selection.
+
+The built-in native format bar also includes a link option that presents a URL prompt when text is selected.
+
+A complete example of a setup that supports both setting links on the selected text, as well as inserting them at the cursor position can be found in the example app code.
+
+## Auto-Link Detection
+
+`EnrichedMarkdownTextInput` can automatically detect URLs as the user types and convert them into Markdown links. Detected links are visually styled in the input and serialized as `[text](url)` in the Markdown output.
+
+### Basic usage
+
+Auto-link detection is enabled by default. URLs like `google.com`, `www.google.com`, and `https://google.com` are detected when followed by a space or newline.
+
+Bare domains and `www.` prefixes are automatically normalized with `https://` (e.g., `google.com` becomes `[google.com](https://google.com)`).
+
+### Custom regex
+
+You can provide a custom regex pattern to control which text is detected as a link:
+
+```tsx
+<EnrichedMarkdownTextInput
+  linkRegex={/https?:\/\/[^\s]+/i}
+/>
+```
+
+Pass `null` to disable auto-link detection entirely:
+
+```tsx
+<EnrichedMarkdownTextInput linkRegex={null} />
+```
+
+### Listening for detections
+
+Use the `onLinkDetected` callback to be notified when a new link is detected:
+
+```tsx
+<EnrichedMarkdownTextInput
+  onLinkDetected={({ text, url, start, end }) => {
+    console.log(`Detected link: ${text} -> ${url} at [${start}, ${end}]`);
+  }}
+/>
+```
+
+The callback fires only for newly detected links — not for links that were already detected and remain unchanged.
+
+### Interaction with manual links
+
+When a manual link is applied (via `setLink` or `insertLink`) over an auto-detected link, the auto-detected link is replaced by the manual one. Auto-link detection skips ranges that already contain a manual link.
+
+## Caret Position Tracking
+
+`EnrichedMarkdownTextInput` can report the caret's pixel position relative to the input, which is useful when the input is embedded in a scrollable container with `scrollEnabled={false}` and you need to keep the caret visible.
+
+### `onCaretRectChange`
+
+A push-based callback that fires whenever the caret moves (typing, selection change, content reflow). The native side diffs the caret rect before emitting, so redundant events are suppressed automatically.
+
+```tsx
+<EnrichedMarkdownTextInput
+  scrollEnabled={false}
+  onCaretRectChange={(rect) => {
+    console.log(rect);
+  }}
+/>
+```
+
+### `getCaretRect()`
+
+An imperative, pull-based method for one-off queries. Returns a Promise that resolves with the current caret rect.
+
+```tsx
+const rect = await ref.current?.getCaretRect();
+```
+
+## Mentions
+
+`EnrichedMarkdownTextInput` supports mention flows with configurable trigger indicators, lifecycle events for showing suggestion lists, and per-pattern styling via `linkVariants`.
+
+See [Mentions](MENTIONS.md) for full documentation on setup, events, ref methods, and styling.
+
+## Clipboard
+
+The input's content can be copied to the system clipboard from a ref, without requiring the user to select text and open the context menu:
+
+- [`copyToClipboard()`](API_REFERENCE.md#copytoclipboard) — copies the full content to the system clipboard, matching the result of selecting all text and pressing the context menu's copy action. The selection is left unchanged, and calling it on an empty input is a no-op.
+
+On iOS and macOS the clipboard receives both plain text and a private Markdown pasteboard type, so pasting back into an `EnrichedMarkdownTextInput` restores the formatting; external apps receive plain text only. On Android the clipboard receives plain text only — inline styles are not preserved for any paste target.
+
+## Style Detection
+
+All of the above styles can be detected with the use of [onChangeState](API_REFERENCE.md#onchangestate) callback payload.
+
+You can find some examples in the [usage section](#usage) or in the example app.
+
+## Other Events
+
+`EnrichedMarkdownTextInput` emits a few more events that may be of use:
+
+- [onFocus](API_REFERENCE.md#onfocus-1) - emits whenever input focuses.
+- [onBlur](API_REFERENCE.md#onblur) - emits whenever input blurs.
+- [onChangeText](API_REFERENCE.md#onchangetext) - returns the input's plain text (without Markdown syntax) anytime it changes.
+- [onChangeMarkdown](API_REFERENCE.md#onchangemarkdown) - returns the Markdown string parsed from current input text and styles anytime it would change. As parsing the Markdown on each input change can be expensive, not assigning the event's callback will skip the serialization for better performance.
+- [onChangeSelection](API_REFERENCE.md#onchangeselection) - returns `{ start, end }` of the current selection, useful for working with [links](#links).
+
+## RTL Support
+
+`EnrichedMarkdownTextInput` resolves writing direction **per paragraph**, matching the read-only [`EnrichedMarkdownText`](RTL.md) renderer. Arabic, Hebrew, and Persian content right-aligns automatically as the user types — even mixed with English paragraphs in the same input.
+
+### Platform setup
+
+No setup is required. Both platforms autodetect direction per paragraph out of the box.
+
+- **Android** — `EditText` resolves direction per paragraph via `View.TEXT_DIRECTION_FIRST_STRONG` (the platform default). The [`writingDirection`](#writingdirection-prop-ios) prop is accepted but has no effect.
+- **iOS** — TextKit's `NSWritingDirectionNatural` follows the app's global UI layout direction and does not do per-paragraph first-strong. The library applies first-strong itself after every formatting pass. The mode is controlled by [`writingDirection`](#writingdirection-prop-ios) and defaults to `'first-strong'`.
+
+### `writingDirection` prop (iOS)
+
+| Value | Behavior |
+|---|---|
+| `'first-strong'` (default) | Per-paragraph autodetection. Neutral-only paragraphs fall back to the view's resolved layout direction. Matches Android. |
+| `'auto'` | React Native parity. TextKit follows the app's `userInterfaceLayoutDirection`; mixed-direction documents do not auto-resolve. |
+| `'ltr'` | Forces LTR on every paragraph. |
+| `'rtl'` | Forces RTL on every paragraph. |
+
+```tsx
+<EnrichedMarkdownTextInput writingDirection="rtl" placeholder="اكتب هنا..." />
+```
+
+### Known limitations
+
+- **Placeholder** follows the host view's layout direction, not the prop. If you need an RTL placeholder, wrap the input in `<View style={{ direction: 'rtl' }}>` or set `I18nManager.forceRTL(true)`.
+- **Mixed paragraphs while typing** — newly inserted characters in an empty paragraph briefly inherit the previous paragraph's direction; the first-strong pass corrects this on the next input event.
+- **Code blocks, tables, blockquotes, lists** are not supported in the input (it's a flat inline-formatting surface). For those, use [`EnrichedMarkdownText`](TEXT.md).
+
+See [RTL Support](RTL.md) for the full per-element behavior on the rendered output side.
+
+## Customizing \<EnrichedMarkdownTextInput /> Styles
+
+`EnrichedMarkdownTextInput` accepts a `markdownStyle` prop for customizing how formatted text appears in the input:
+
+```tsx
+<EnrichedMarkdownTextInput
+  markdownStyle={{
+    strong: { color: '#1D4ED8' },
+    em: { color: '#7C3AED' },
+    link: { color: '#2563EB', underline: true },
+  }}
+/>
+```
+
+Available style properties:
+
+- `strong.color` — text color for bold text (defaults to the input's text color).
+- `em.color` — text color for italic text (defaults to the input's text color).
+- `link.color` — text color for links (defaults to `#2563EB`).
+- `link.underline` — whether links are underlined (defaults to `true`).
+- `spoiler.color` — text color for spoiler text.
+- `spoiler.backgroundColor` — background color for spoiler text.

package/docs/LATEX_MATH.md

@@ -0,0 +1,136 @@
+# LaTeX Math
+
+LaTeX math rendering is supported for both block and inline equations:
+
+- **Block math (`$$...$$`)**: Rendered as a standalone display element. Requires `flavor="github"`.
+- **Inline math (`$...$`)**: Rendered within the text flow. Works with both `flavor="commonmark"` and `flavor="github"`.
+
+## Usage
+
+```tsx
+<EnrichedMarkdownText
+  flavor="github"
+  markdown={`
+The quadratic formula:
+
+$$x = \\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}$$
+
+Einstein's mass-energy equivalence $E = mc^2$ is one of the most famous equations.
+  `}
+  markdownStyle={{
+    math: {
+      fontSize: 20,
+      color: '#1F2937',
+      backgroundColor: '#F3F4F6',
+      padding: 12,
+      textAlign: 'center',
+    },
+    inlineMath: {
+      color: '#1F2937',
+    },
+  }}
+/>
+```
+
+Block math equations are rendered as standalone display elements with spacing and an optional background. Inline math inherits the surrounding block's typography.
+
+> [!IMPORTANT]
+> LaTeX commands use backslashes (e.g. `\frac`, `\alpha`). In regular JS strings and template literals, backslashes are escape characters. Use `String.raw` or double backslashes (`\\frac`) to preserve them. Block math (`$$...$$`) must be on its own line to render as a display element.
+
+## Web
+
+On web the library renders LaTeX via [KaTeX](https://katex.org/) in **MathML output mode**. Browsers render MathML natively — no CSS or font files are required.
+
+### Installation
+
+Install the optional peer dependency:
+
+```sh
+npm install katex
+# or
+yarn add katex
+```
+
+KaTeX is loaded lazily the first time a LaTeX node is encountered, so it has no impact on pages that do not render math. No stylesheet or `<link>` tag is needed.
+
+> [!NOTE]
+> MathML is supported natively in Chrome 109+, Firefox, and Safari. Older browsers will display the raw LaTeX source as a text fallback.
+
+### Disabling on web
+
+Pass `latexMath: false` in `md4cFlags` to skip parsing and treat `$` as plain text:
+
+```tsx
+<EnrichedMarkdownText markdown="Price is $5" md4cFlags={{ latexMath: false }} />
+```
+
+This also prevents KaTeX from being loaded at runtime.
+
+## Disabling LaTeX Math (reducing bundle size)
+
+LaTeX math rendering relies on **RaTeX** — a native, KaTeX-compatible math engine — on both iOS and Android. It is included by default but can be excluded to reduce your app's binary size (~3–5 MB on iOS, varies on Android).
+
+### 1. Disable at the parser level (JS)
+
+Set `latexMath: false` in `md4cFlags` so the parser treats `$` as plain text:
+
+```tsx
+<EnrichedMarkdownText markdown="Price is $5" md4cFlags={{ latexMath: false }} />
+```
+
+This alone prevents math rendering without any native changes. The steps below go further by removing the native math libraries from your binary entirely.
+
+### 2. Remove the native iOS dependency
+
+Add the following to your Podfile and re-run `pod install`:
+
+```ruby
+ENV['ENRICHED_MARKDOWN_ENABLE_MATH'] = '0'
+```
+
+This excludes **RaTeX** from the build. Rebuild the app after running `pod install`.
+
+> [!NOTE]
+> When math is **enabled** (the default), your Podfile must use dynamic frameworks:
+> ```ruby
+> use_frameworks! :linkage => :dynamic
+> ```
+> This is required for CocoaPods to resolve the RaTeX Swift Package dependency.
+
+> [!NOTE]
+> **macOS**: LaTeX math is currently not supported on macOS because `react-native-macos` does not support `use_frameworks!` ([microsoft/react-native-macos#1969](https://github.com/microsoft/react-native-macos/issues/1969)). Math is automatically disabled in the macOS example app.
+
+### 3. Remove the native Android dependency
+
+Add the following to your project's `gradle.properties`:
+
+```properties
+enrichedMarkdown.enableMath=false
+```
+
+This excludes **RaTeX** from the Android build. Rebuild the app after changing this property.
+
+### 4. Expo config plugin
+
+If you are using Expo, you can use the built-in config plugin to disable LaTeX math rendering on both platforms at once.
+
+Add the following to your `app.json` or `app.config.js`:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "react-native-enriched-markdown",
+        {
+          "enableMath": false
+        }
+      ]
+    ]
+  }
+}
+```
+
+This will automatically apply both the [iOS](#2-remove-the-native-ios-dependency) and [Android](#3-remove-the-native-android-dependency) native changes listed above during `npx expo prebuild`.
+
+If you later re-enable math (e.g. remove the plugin or set `enableMath: true`), run `npx expo prebuild --clean` so native projects are regenerated without the disable flags, then rebuild.

package/docs/MACOS.md

@@ -0,0 +1,19 @@
+# macOS Support
+
+`react-native-enriched-markdown` supports macOS via [react-native-macos](https://github.com/microsoft/react-native-macos). The native layer shares code with iOS through a platform abstraction header (`ENRMUIKit.h`), with macOS-specific implementations for context menus, text selection, and clipboard handling.
+
+The macOS implementation supports the same rendering elements as iOS — CommonMark, GitHub Flavored Markdown (tables, task lists, strikethrough), images, code blocks, blockquotes, and all other supported elements. `EnrichedMarkdownTextInput` is also available on macOS with full support for inline styles, links, and the native context menu.
+
+## Known limitations
+
+These will be addressed in upcoming releases:
+
+- **LaTeX math** (both inline and block) is not available on macOS. The math engine (RaTeX) is distributed as a Swift Package, which requires `use_frameworks!` in CocoaPods. `react-native-macos` does not currently support `use_frameworks!` due to circular dependencies between `React-Core` and `React-RCTText` ([microsoft/react-native-macos#1969](https://github.com/microsoft/react-native-macos/issues/1969)). Math will be enabled once this upstream issue is resolved.
+- **Tail fade-in animation** falls back to instant reveal (no `CADisplayLink` on macOS)
+- **VoiceOver** accessibility is stubbed (pending `NSAccessibility` implementation)
+- **Font scale observation** does not respond to system font size changes
+- **`selectionColor`** affects only the selection background. The iOS-style caret + handle tinting isn't available on macOS, since AppKit's `NSTextView` doesn't expose them via `tintColor`.
+
+## Example app
+
+See the [react-native-macos-example/](../apps/react-native-macos-example/) directory for a working example app.