react-native-enriched-markdown-scaffold 0.6.0-scaffold.8 → 0.7.4-scaffold.10

package/docs/LATEX_MATH.md

@@ -0,0 +1,198 @@
+# 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',
+      paddingVertical: 4,
+    },
+  }}
+/>
+```
+
+Block math equations are rendered as standalone display elements with spacing and an optional background. Inline math inherits the surrounding block's typography.
+
+### Spacing around inline formulas
+
+An inline formula reports its own height, and tall constructs such as `\frac` are routinely taller than the
+surrounding text. The block's `lineHeight` cannot loosen those lines: it is applied expand-only, so a value
+below the formula's natural height is ignored rather than compressing the formula out of its box. Two wrapped
+lines that each contain a fraction therefore sit flush against each other.
+
+`inlineMath.paddingVertical` (points, default `4`) adds empty space above and below the formula box, which is
+what pushes those lines apart. It affects only lines that actually contain inline math — prose-only lines keep
+the line height they had. Set it to `0` to get the old flush behaviour back. Block math (`$$...$$`) has its own
+`math.padding` instead.
+
+### Bold formulas
+
+`math.fontWeight` / `inlineMath.fontWeight` (`'normal'` | `'bold'`, default `'normal'`) typeset a
+formula at bold weight. Set it wherever the surrounding text is bold so the formula follows it.
+
+The embolden is **synthetic on every platform** — no real bold face is ever used.
+
+On **iOS and Android** it is a stroke on the glyph outline and the platform's fake-bold
+respectively, rather than a switch to the bundled KaTeX bold faces. That is deliberate. The native
+engine has no weight parameter, and by the time a style applies, glyph positions are already laid
+out: the bold faces' advances run up to 15% wider than the regular ones the layout reserved, so
+swapping them in would make glyphs collide. Stroking and fake-bold both preserve every advance.
+
+Two consequences worth knowing:
+
+- Fraction bars and rules keep their own thickness, so they do not thicken with the glyphs.
+- On iOS the stroke width also applies to the handful of decorations the engine strokes itself
+  (`\cancel`, `\textcircled`, `\corresponds`, `\imageof`). Prefer turning bold on per surface
+  rather than globally.
+
+On **web** the prop is a plain CSS declaration on the KaTeX output — but the library renders in
+[MathML output mode](#web) and loads no KaTeX stylesheet or fonts, so `font-weight` is resolved by
+the browser's own math font (STIX Two Math, Latin Modern Math, Cambria Math). Most of those ship no
+bold face, so the browser synthesizes one there too. Treat web as synthetic as well, not as a
+reference for how heavy bold "should" look.
+
+`EnrichedMarkdownTextInput` honours the same prop for the formula chips typed into the editor, under
+its own style keys — `math.fontWeight` for inline chips (`$...$`) and `mathBlock.fontWeight` for
+block chips (`$$...$$`). `mathBlock` inherits the weight from `math` when it does not set one of its
+own, the way it already inherits `color` and the border props:
+
+```tsx
+<EnrichedMarkdownTextInput
+  markdownStyle={{
+    math: { fontWeight: 'bold' },       // inline chips bold…
+    mathBlock: { fontWeight: 'normal' }, // …block chips opt back out
+  }}
+/>
+```
+
+The caveats above apply unchanged — the embolden is the same synthetic one, and the chip keeps its
+measured width because fake-bold and stroking both preserve the glyph advances. Editor chips are
+iOS + Android only; there is no web or macOS chip surface.
+
+> [!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.
+
+If you load `katex/dist/katex.min.css` anyway — some setups do — its `.katex` rule opens with the
+`font` shorthand, which resets `font-weight` and would drop [`fontWeight`](#bold-formulas) on the
+way down to the formula. The library injects `.katex { font-weight: inherit; }` to keep the prop
+working in that case; nothing is required of you.
+
+> [!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.

package/docs/MARKDOWN_STREAMING.md

@@ -0,0 +1,36 @@
+# Markdown Streaming
+
+If you need to render markdown that streams token-by-token from an LLM, check out [react-native-streamdown](https://github.com/software-mansion-labs/react-native-streamdown) — a streaming-ready markdown component built on top of `react-native-enriched-markdown`.
+
+It combines [remend](https://www.npmjs.com/package/remend) for fixing incomplete markdown on the fly with [react-native-worklets](https://docs.swmansion.com/react-native-worklets/) **Bundle Mode** to run all processing off the JS thread, keeping your UI responsive while tokens arrive.
+
+```tsx
+import { StreamdownText } from 'react-native-streamdown';
+
+<StreamdownText markdown={partialMarkdown} />;
+```
+
+`StreamdownText` accepts all props from `EnrichedMarkdownText` and adds a `remendConfig` prop for customizing the markdown repair pipeline. See the [react-native-streamdown README](https://github.com/software-mansion-labs/react-native-streamdown#readme) for full setup instructions including the required Babel and Metro configuration for Bundle Mode.
+
+## Table Streaming (GFM)
+
+When using `flavor="github"` with streaming content, tables require special handling because they are block-level elements that can't be rendered until the parser has enough structure (at minimum a header row and separator line).
+
+The `streamingConfig` prop controls this behavior:
+
+```tsx
+<EnrichedMarkdownText
+  markdown={streamingMarkdown}
+  flavor="github"
+  streamingAnimation
+  streamingConfig={{ tableMode: 'hidden' }}
+/>
+```
+
+### Table Modes
+
+| Mode | Behavior |
+|---|---|
+| `'progressive'` (default) | Renders the table row-by-row as content arrives. New rows fade in when `streamingAnimation` is enabled. Incomplete trailing rows are automatically trimmed. |
+| `'hidden'` | The table is completely hidden until it is followed by a blank line, indicating the table is complete. Prevents visual jank from partially formed tables. |
+

package/docs/MENTIONS.md

@@ -0,0 +1,97 @@
+# Mentions
+
+`EnrichedMarkdownTextInput` supports mention flows — token-triggered inline entities (e.g. `@user`, `#channel`) rendered as styled links.
+
+## How It Works
+
+1. User types an indicator (`@`, `#`) or toolbar calls `startMention(indicator)`.
+2. `onStartMention` fires → show suggestion list.
+3. `onChangeMention` fires on each keystroke → filter suggestions by query.
+4. User picks a suggestion → call `insertMention(displayText, url)`.
+5. `onEndMention` fires → hide suggestions.
+
+## Example
+
+```tsx
+<EnrichedMarkdownTextInput
+  ref={ref}
+  mentionIndicators={['@', '#']}
+  markdownStyle={{
+    link: { color: '#2563EB', underline: true },
+    linkVariants: {
+      '^user:': { color: '#1264A3', backgroundColor: '#E8F5FB', underline: false },
+      '^channel:': { color: '#065F46', backgroundColor: '#D1FAE5', underline: false },
+    },
+  }}
+  onStartMention={({ indicator }) => setShowSuggestions(true)}
+  onChangeMention={({ indicator, text }) => setQuery(text)}
+  onEndMention={() => setShowSuggestions(false)}
+  onCaretRectChange={setCaretRect} // for positioning the popup
+/>
+```
+
+When the user selects a suggestion:
+
+```tsx
+ref.current?.insertMention(`@${item.name}`, item.url);
+// Markdown output: [@Alice](user://u_1)
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `mentionIndicators` | `string[]` | `[]` | Trigger strings that start a mention flow. |
+
+## Events
+
+| Event | Payload | When |
+| ----- | ------- | ---- |
+| `onStartMention` | `{ indicator }` | Mention flow starts. |
+| `onChangeMention` | `{ indicator, text }` | Query text changes (each keystroke). |
+| `onEndMention` | `{ indicator }` | Mention flow ends (cancel, insert, or cursor moved away). |
+
+## Ref Methods
+
+| Method | Description |
+| ------ | ----------- |
+| `startMention(indicator)` | Inserts the indicator at cursor and triggers the mention flow. Must be in `mentionIndicators`. |
+| `insertMention(displayText, url)` | Replaces the active mention token with a styled link. Only works during an active flow. |
+
+## Link Variants (Styling)
+
+Mentions are links — style them per URL pattern via `linkVariants` in `markdownStyle`:
+
+```tsx
+linkVariants: {
+  '^user:':    { color: '#1264A3', backgroundColor: '#E8F5FB', underline: false },
+  '^channel:': { color: '#065F46', backgroundColor: '#D1FAE5', underline: false },
+}
+```
+
+Each key is a regex tested against the link URL. First match wins. Unspecified properties inherit from the base `link` style. Patterns are auto-sorted longest-first.
+
+## Positioning the Suggestion List
+
+Use `onCaretRectChange` to get the caret's `{ x, y, width, height }` relative to the input. Combine with the input's position (via `onLayout`) to place a floating popup:
+
+```tsx
+<View
+  style={{
+    position: 'absolute',
+    left: inputLayout.x + caretRect.x,
+    top: inputLayout.y + caretRect.y + caretRect.height + 4,
+  }}
+>
+  {/* suggestions */}
+</View>
+```
+
+For simpler layouts, just render the list adjacent to the input without caret tracking.
+
+## Behavior Notes
+
+- **Atomic deletion**: Backspacing into a mention deletes it entirely (Slack-like).
+- **Debounce**: `onChangeMention` fires every keystroke — debounce network requests.
+- **Toolbar**: Call `focus()` before `startMention()` if the input isn't focused.
+- **URL schemes**: Use custom schemes (`user://`, `channel://`) to distinguish mention types from regular links.

package/docs/RTL.md

@@ -0,0 +1,82 @@
+# RTL Support
+
+`react-native-enriched-markdown` resolves writing direction **per paragraph** on both platforms: each paragraph picks its own base direction from its first strong directional character. Arabic, Hebrew, and Persian content right-aligns automatically, even inside an LTR app and even when mixed with English paragraphs in the same document.
+
+This document describes the read-only [`EnrichedMarkdownText`](TEXT.md) renderer. The rich [`EnrichedMarkdownTextInput`](INPUT.md#rtl-support) follows the same per-paragraph rules — see its [RTL section](INPUT.md#rtl-support) for input-specific caveats (placeholder, code blocks, etc.).
+
+## Platform Setup
+
+No setup is required. Both platforms autodetect direction per paragraph out of the box.
+
+### Android
+
+Uses Android's `TEXT_DIRECTION_FIRST_STRONG` heuristic on every `StaticLayout`. Paragraphs with no strong character fall back to the view's resolved layout direction (inherits ancestor `<View style={{ direction: 'rtl' }}>` and `I18nManager.isRTL`).
+
+### iOS
+
+iOS TextKit's `NSWritingDirectionNatural` does **not** do per-paragraph first-strong — it follows the app's global UI layout direction. The library implements first-strong itself as a post-render pass, matching Android's behavior. The mode is controlled by the [`writingDirection`](#writingdirection-prop-ios) prop and defaults to `'first-strong'`.
+
+> **Note:** Earlier versions documented `I18nManager.forceRTL(true)` as a requirement on iOS. That is no longer needed for content direction — `first-strong` resolves each paragraph from its content. `I18nManager.forceRTL` still affects the surrounding app layout (Yoga direction, navigation, etc.) and remains useful if you want the whole app in RTL mode, but it's no longer a precondition for Markdown to render right-aligned.
+
+## `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. |
+
+Code blocks always render LTR regardless of this prop.
+
+Android ignores the prop; it always uses first-strong via the platform.
+
+```tsx
+// Default — mixed Arabic/English document renders each paragraph correctly.
+<EnrichedMarkdownText markdown={mixedContent} />
+
+// Force RTL for the whole document (e.g. forms or admin UI in an Arabic locale).
+<EnrichedMarkdownText writingDirection="rtl" markdown={content} />
+```
+
+## Element RTL Behavior
+
+Each element follows the **paragraph it belongs to**, not a global flag — so a single document can mix sides cleanly.
+
+| Element | Behavior |
+|---|---|
+| **Paragraphs & headings** | Base direction set per paragraph from first-strong (or forced by the prop). |
+| **Unordered lists** | Bullet drawn on the side that matches the item's paragraph direction. |
+| **Ordered lists** | Number drawn on the side that matches the item's paragraph direction. |
+| **Task lists** | Checkbox drawn on the matching side; tap hit-test follows the same side. |
+| **Blockquotes** | Border drawn on the side that matches the quoted paragraph. |
+| **Tables** (`flavor="github"`) | Each cell resolves its own direction independently from cell content. |
+| **Code blocks** | Always LTR. |
+| **Inline code** | Inherits its paragraph's direction; characters flow correctly via TextKit Bidi. |
+
+## Yoga layout-direction inheritance
+
+For paragraphs with no strong directional character (digits, punctuation, block spacers), the library falls back to the view's **Yoga-resolved layout direction**. That means:
+
+```tsx
+// "123 456 789." has no strong character. Inside an RTL ancestor view,
+// it right-aligns; otherwise it left-aligns.
+<View style={{ direction: 'rtl' }}>
+  <EnrichedMarkdownText markdown="123 456 789." />
+</View>
+```
+
+This mirrors Android's first-strong fallback and lets you place an LTR app in an RTL screen (or vice versa) without surprises for neutral content.
+
+## Copy-as-HTML caveat
+
+When you copy markdown content to the clipboard, the HTML representation carries a single `dir` attribute on `<html>` (or on `<table>` for table copies). That attribute is read from the document's first paragraph:
+
+- `first-strong` document starting with Arabic → `<html dir="rtl">`
+- `first-strong` document starting with English → `<html dir="ltr">`
+- `'auto'` → `<html dir="auto">` (receivers do best-effort first-strong)
+- `'ltr'` / `'rtl'` → forced
+
+**Receivers (Gmail, Notes, Word, etc.) apply their own Bidi algorithm to the pasted HTML.** Mixed-direction documents may not visually reproduce the per-paragraph layout you see in-app — receivers can only honor what the markup encodes, and HTML's `dir` attribute is scoped to elements, not paragraphs within them. The plain-text and Markdown clipboard representations are unaffected and round-trip cleanly.
+
+If you need precise mixed-direction output in a specific receiver, the rendered HTML carries no per-`<p>` `dir` attribute today — that would be a future enhancement.