react-native-enriched-markdown 0.7.0 → 0.7.2

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.