react-native-enriched-markdown-scaffold 0.7.4-scaffold.9 → 1.0.2-scaffold.10

package/docs/BREAKING_CHANGES.md

@@ -0,0 +1,129 @@
+# Breaking changes
+
+This file tracks breaking changes and how to migrate for each. Entries are newest first. Deprecations
+(things that still work but are slated for removal) are noted alongside the change that introduces them.
+
+## Unreleased
+
+### `EnrichedMarkdownTextInput` math style keys renamed to match the renderer
+
+The editor's `markdownStyle` used `math` for the **inline** chip and `mathBlock` for the **block**
+chip — the exact opposite of `EnrichedMarkdownText`, where `math` is the block style and `inlineMath`
+the inline one. The same key name meant two different things depending on which component you were
+styling. The editor now follows the renderer.
+
+**Migrate:**
+
+| Before (input) | After (input) | Renderer equivalent |
+|---|---|---|
+| `markdownStyle.math` | `markdownStyle.inlineMath` | `markdownStyle.inlineMath` |
+| `markdownStyle.mathBlock` | `markdownStyle.math` | `markdownStyle.math` |
+| `markdownStyle.mathBlock.alignment` | `markdownStyle.math.textAlign` | `markdownStyle.math.textAlign` |
+
+```diff
+ <EnrichedMarkdownTextInput
+   markdownStyle={{
+-    math: { color: '#0F172A', backgroundColor: '#EEF2FF' },
+-    mathBlock: { fontSize: 22, alignment: 'center' },
++    inlineMath: { color: '#0F172A', backgroundColor: '#EEF2FF' },
++    math: { fontSize: 22, textAlign: 'center' },
+   }}
+ />
+```
+
+`markdownStyle.math` additionally accepts `padding` as a shorthand for both axes, matching the
+renderer's `math.padding`; `paddingHorizontal` / `paddingVertical` still override it per axis.
+
+The accompanying types are exported for the first time under names that say which surface they belong
+to: `InputInlineMathStyle` and `InputMathStyle` (the renderer's own math style types stay internal to
+`MarkdownStyle`).
+
+
+## v1.0.2
+
+### The Expo config plugin was removed
+
+The built-in Expo config plugin (`app.plugin.js` and the `plugin/` folder) has been removed. Feature
+configuration now lives entirely in your app's `package.json`, read directly by the native build and by
+`postinstall` — the same approach `react-native-worklets` uses for its static feature flags.
+
+Why: the plugin only wrote the (now deprecated) Podfile `ENV` / `gradle.properties` channels, it could
+never influence the install-time asset download (it runs during `expo prebuild`, _after_ `npm install`),
+and its option shape diverged from the `package.json` block. The `package.json` block supersedes it for
+both the download and the build, and it survives `expo prebuild`.
+
+**Migrate:** remove the plugin entry from `app.json` / `app.config.js` and move the options into the
+`enriched-markdown` block of your `package.json`.
+
+Before (`app.json`):
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "react-native-enriched-markdown-scaffold",
+        {
+          "enableMath": false,
+          "codeHighlight": {
+            "enabled": true,
+            "languages": ["javascript", "tsx"]
+          }
+        }
+      ]
+    ]
+  }
+}
+```
+
+After (`package.json`):
+
+```json
+{
+  "enriched-markdown": {
+    "enableMath": false,
+    "enableCodeHighlight": true,
+    "codeHighlightLanguages": ["javascript", "tsx"]
+  }
+}
+```
+
+Note the key renames: the plugin's `codeHighlight.enabled` / `codeHighlight.languages` become
+`enableCodeHighlight` / `codeHighlightLanguages`. Then run `pod install` (iOS) or rebuild (Android).
+These are compile/link-time settings, so they apply only in builds you compile yourself (a custom dev
+client or `expo prebuild`) — they cannot be changed in Expo Go, which ships a fixed prebuilt binary.
+
+The `@expo/config-plugins` peer dependency was dropped as part of this removal.
+
+### Feature config moved to `package.json`; ENV vars and gradle properties are deprecated
+
+The `enriched-markdown` block in your app's `package.json` is now the single source of truth for
+`enableMath`, `enableCodeHighlight`, and `codeHighlightLanguages` on both platforms — the native build
+reads it directly at `pod install` / Gradle configuration time. The previous build flags still work as a
+fallback but are deprecated, print a warning, and are ignored when the matching `package.json` key is set:
+
+| Deprecated flag                                                                                                | Replaced by (`package.json` `enriched-markdown`) |
+| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| Podfile `ENV['ENRICHED_MARKDOWN_ENABLE_MATH']` / gradle `enrichedMarkdown.enableMath`                          | `enableMath`                                     |
+| Podfile `ENV['ENRICHED_MARKDOWN_ENABLE_CODE_HIGHLIGHT']` / gradle `enrichedMarkdown.enableCodeHighlight`       | `enableCodeHighlight`                            |
+| Podfile `ENV['ENRICHED_MARKDOWN_CODE_HIGHLIGHT_LANGUAGES']` / gradle `enrichedMarkdown.codeHighlightLanguages` | `codeHighlightLanguages`                         |
+
+In a monorepo the _build_ flag is read from the app's `package.json` (the one beside `ios/`/`android/`),
+so each app configures independently. The _download_ opt-out is read where the install runs — usually the
+workspace root — so put it in the root `package.json` to skip a download for the whole repo. See
+[Native assets](./NATIVE_ASSETS.md).
+
+### Explicitly enabling a feature whose assets are missing now fails the build
+
+Previously, a missing native asset (the RaTeX XCFramework, or the tree-sitter grammars) always silently
+disabled the feature. Now, if you **explicitly** set `enableMath: true` or `enableCodeHighlight: true` but
+the asset was not downloaded (for example an install with `--ignore-scripts`, or a monorepo root opt-out
+that an app overrides), the build fails with an actionable error instead of degrading. Features left on by
+default still degrade to a clean build. To fix, restore the assets:
+
+```sh
+node node_modules/react-native-enriched-markdown-scaffold/postinstall.mjs
+# or: npm rebuild react-native-enriched-markdown-scaffold
+```
+
+then re-run `pod install` (iOS) / rebuild (Android).

package/docs/CODE_HIGHLIGHT.md

@@ -0,0 +1,133 @@
+# Code-block syntax highlighting
+
+Fenced code blocks are syntax-highlighted natively via [tree-sitter](https://tree-sitter.github.io/).
+Highlighting is **foreground-only** (it recolors tokens and never changes text metrics), so a code
+block's measured height always matches its drawn height. It is enabled by default on iOS and Android
+with a curated set of languages, and can be trimmed or disabled to reduce binary size.
+
+## Usage
+
+Highlighting activates automatically for a fenced block whose info string names a supported language:
+
+````tsx
+<EnrichedMarkdownText
+  flavor="github"
+  markdown={String.raw`
+\`\`\`python
+def greet(name: str) -> str:
+    return f"Hello, {name}!"  # a comment
+\`\`\`
+`}
+  markdownStyle={{
+    codeBlock: {
+      syntaxColors: {
+        keyword: '#C678DD',
+        string: '#98C379',
+        number: '#D19A66',
+        comment: '#7F848E',
+        function: '#61AFEF',
+        type: '#E5C07B',
+        // ...any of the 14 token types
+      },
+    },
+  }}
+/>
+````
+
+Token colors are set through `codeBlock.syntaxColors`. The 14 token types are: `keyword`,
+`operator`, `punctuation`, `string`, `number`, `constant`, `comment`, `function`, `type`,
+`variable`, `property`, `tag`, `attribute`, `embedded`. Any type left unset is drawn in the normal
+code color.
+
+## Copy button
+
+With `flavor="github"`, each code block's header shows a copy button (and a long-press context
+menu with **Copy** / **Copy as Markdown**). The CommonMark flavor renders code blocks inline with
+no header, so it has no copy button. To observe when a user copies code, pass
+[`onCopyPress`](./API_REFERENCE.md#oncopypress) — it fires with the copied `code` and its
+`language` for the header button, the context-menu **Copy** action, and the VoiceOver copy action.
+The copy label shown to assistive technologies is configurable via
+[`selectionMenuConfig`](./COPY_OPTIONS.md).
+
+## Supported languages
+
+Fence info strings map to a grammar (for example `js` and `jsx` both select JavaScript). The **curated default
+set** is compiled in unless you override it. It is defined by `default:true` in
+`vendor/grammar-versions.json` (the single source of truth the iOS podspec and Android build both
+derive from), so the table below tracks that manifest:
+
+| Default (on) | Opt-in (heavier) |
+|---|---|
+| json, html, css, markdown, yaml, go, java, javascript, python, c, rust, bash, typescript, tsx | cpp, swift, php, ruby, c-sharp |
+
+The default set is the smaller-footprint tier (~32 MB of grammar C source across the whole set).
+The opt-in grammars are larger (17-29 MB each) and are only compiled when you list them explicitly.
+A block whose language is not compiled in simply renders as plain (uncolored) code.
+
+## Choosing languages / reducing binary size
+
+Only the grammars you compile end up in your binary, so trimming the list is the main size lever.
+The seam degrades to plain code whenever a grammar is absent, so nothing breaks when you remove one.
+
+Configure everything through the `enriched-markdown` block of your app's `package.json` — it is the
+single source of truth for both platforms and both the install-time download and the build:
+
+```json
+{
+  "enriched-markdown": {
+    "enableCodeHighlight": true,
+    "codeHighlightLanguages": ["javascript", "tsx", "json", "bash"]
+  }
+}
+```
+
+How the two keys interact:
+
+- **`enableCodeHighlight`** (default `true`) is the master switch. When `false`, the grammar download is
+  skipped **and** the tree-sitter runtime is excluded from the native build. In that state
+  **`codeHighlightLanguages` is ignored — it is a no-op**, because there is no highlighter compiled in for
+  languages to feed.
+- **`codeHighlightLanguages`** selects which grammars to compile *when highlighting is enabled*. Omit it
+  for the curated default set, or pass a subset to shrink the binary. An empty array (`[]`) compiles no
+  grammars, which disables highlighting entirely — equivalent to `enableCodeHighlight: false`.
+
+Re-run `pod install` (iOS) / rebuild (Android) after changing these. The same block works with Expo —
+`node_modules` survives `npx expo prebuild`, so no config plugin is needed (highlighting is compiled in,
+so it can't be changed in **Expo Go**; use a dev client or `expo prebuild`). See
+[Skipping the download](./NATIVE_ASSETS.md#skipping-the-download-opt-out).
+
+> [!NOTE]
+> **Deprecated:** the `ENV['ENRICHED_MARKDOWN_*']` Podfile variables and the `enrichedMarkdown.*` gradle
+> properties still work as a fallback but are deprecated and print a warning; they are ignored when the
+> corresponding `package.json` key is set. The Expo config plugin was removed — see
+> [Breaking changes](./BREAKING_CHANGES.md). Prefer the `package.json` block above.
+
+## How it works
+
+Grammars are **vendored** into `packages/core/cpp/highlight/vendor/` (only each grammar's
+`parser.c`/`scanner.c` + `highlights.scm`, never whole npm packages), so the native build itself is
+fully offline and deterministic. The stable tree-sitter runtime is vendored the same way and compiled
+with WebAssembly support left out. A build-time codegen emits a registry for exactly the selected
+languages, so the binary and link step only ever reference compiled grammars.
+
+The entire `vendor/` tree is **gitignored** to keep the repo and PRs small — nothing generated lives
+in git. `vendor/vendor-grammars.mjs` restores all of it from the pins in `vendor/grammar-versions.json`:
+the tree-sitter runtime (`vendor/tree-sitter/`) is fetched and sha256-verified from the pinned GitHub
+release tarball, the ~178 MB of grammar `parser.c` tables (`vendor/grammars/`) are copied from the
+pinned grammar devDependencies, and the default registry (`vendor/generated/`) is codegen'd from them.
+It is wired into the package `prepare` script (so a plain `yarn install` restores everything, with
+`.stamp` guards making repeats a no-op).
+
+The published npm tarball ships only the small default registry, **not** the heavy grammar/runtime
+source — that would bloat every install to ~230 MB. Instead a `postinstall` script downloads the
+grammar sources (from the npm registry) and the tree-sitter runtime (from the pinned GitHub release)
+into the installed package, sha256-verified and idempotent. See [Native assets](./NATIVE_ASSETS.md)
+for the install-time behavior, network requirements, and how to recover an offline/pnpm install.
+
+Highlighting runs synchronously when a code block is applied and is cached per block, with a size cap
+(~50 KB / ~2000 lines) that falls back to plain rendering for pathological inputs. Maintainers re-pin
+by editing `vendor/grammar-versions.json` (for a runtime bump, also update `runtime.sha256` — a full
+`node vendor/vendor-grammars.mjs --force` run prints the correct digest on mismatch) and re-running
+the script; there is nothing generated to commit. To vendor the runtime from a local tree-sitter
+checkout instead of the network, pass `--runtime-src <path to tree-sitter/lib>` (or set
+`TREE_SITTER_SRC`).

package/docs/COPY_OPTIONS.md

@@ -1,6 +1,6 @@
 # Copy Options
 
-When text is selected, `react-native-enriched-markdown` provides enhanced copy functionality through the context menu on both platforms.
+When text is selected, `react-native-enriched-markdown-scaffold` provides enhanced copy functionality through the context menu on both platforms.
 
 ## Smart Copy
 
@@ -44,6 +44,59 @@ Use `selectionMenuConfig` to hide built-in selection menu actions while keeping
 />
 ```
 
+### Copy as Markdown only, no system items
+
+`copy` can also be hidden (`{ enabled: false }`) or switched to Markdown with
+`format: 'markdown'`, and `systemItems: 'none'` drops everything the OS adds
+(Select All, Look Up, Share, Translate, app text actions…):
+
+```tsx
+<EnrichedMarkdownText
+  markdown={content}
+  selectionMenuConfig={{
+    copy: { format: 'markdown' }, // inline math → $…$, plain text only
+    copyAsMarkdown: { enabled: false },
+    systemItems: 'none',
+    codeBlockCopyButton: { enabled: false },
+  }}
+/>
+```
+
+The same `copy` and `copyAsMarkdown` settings drive the long-press menus on
+table, math and code blocks: with `format: 'markdown'` their Copy item writes
+the block's Markdown (`$$…$$`, a fenced code block, a Markdown table). On code
+blocks, the header copy button and the VoiceOver copy action always copy the raw
+code and fire `onCopyPress`; `codeBlockCopyButton: { enabled: false }` hides the
+button, and `copy: { enabled: false }` also removes the VoiceOver action.
+`copy.enabled`, `copy.format` and `systemItems` are ignored on macOS.
+
+### Handling Copy in JS
+
+To decide in JS what lands on the clipboard, pass `onCopy`. The Copy item
+(text selection and block menus) then writes nothing itself and hands you the
+content — `markdown`, `text`, `source` and `whole` — to write with your
+clipboard library. See [`onCopy`](API_REFERENCE.md#oncopy).
+
+```tsx
+<EnrichedMarkdownText
+  markdown={content}
+  onCopy={({ markdown }) => Clipboard.setStringAsync(markdown)}
+/>
+```
+
+To turn the menu off entirely rather than item by item, use `contextMenuHidden`:
+
+```tsx
+// No selection menu at all — text is still selectable
+<EnrichedMarkdownText markdown={content} contextMenuHidden />
+```
+
+The two are complementary: `selectionMenuConfig` prunes individual built-in
+items and leaves the menu in place, while `contextMenuHidden` suppresses the
+menu as a whole — including `contextMenuItems` and the copy menus on table,
+code and math blocks. Note that `contextMenuHidden` applies to `EnrichedMarkdownText`
+only; it does not affect `EnrichedMarkdownTextInput`.
+
 `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
@@ -93,8 +146,13 @@ Notes:
   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.
+- The labels apply to the main text selection menu as well as the table, math,
+  and code block copy menus. With `flavor="github"`, the code block header's copy
+  button also reuses the copy label for assistive technologies (the CommonMark
+  flavor renders code inline with no header button): it is the button's
+  contentDescription on Android, and on iOS it names the VoiceOver custom
+  action that triggers the copy. To be notified when code is copied from a code
+  block, use the [`onCopyPress`](./API_REFERENCE.md#oncopypress) callback.
 - 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.

package/docs/ELEMENTS_STRUCTURE.md

@@ -1,10 +1,10 @@
 # Element Structure
 
-Markdown elements in `react-native-enriched-markdown` are organized into block and inline categories, each with distinct rendering behaviors.
+Markdown elements in `react-native-enriched-markdown-scaffold` 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:
+`react-native-enriched-markdown-scaffold` supports a comprehensive set of Markdown elements:
 
 ### Block Elements
 
@@ -13,7 +13,7 @@ Markdown elements in `react-native-enriched-markdown` are organized into block a
 | 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 |
+| Code Blocks | ` ``` code ``` ` | `codeBlock` | Multi-line code containers; with `flavor="github"` rendered as a block component with a language header and copy-code button |
 | 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"`) |
@@ -60,6 +60,22 @@ Markdown elements in `react-native-enriched-markdown` are organized into block a
 2. Second item
 ```
 
+### Lists with Block Content Example
+
+List items can contain block elements — fenced code blocks, nested lists, and multiple paragraphs:
+
+````markdown
+1. Install via npm:
+
+   ```
+   npm install
+   ```
+
+2. Verify the connection.
+````
+
+Code blocks indent to the item's content column, and the marker is drawn next to the first line even when a code block or nested list is the item's first child.
+
 ### Nested Blockquotes Example
 
 ```markdown
@@ -94,6 +110,38 @@ Block elements are structural containers that define the layout and establish th
 
 Inline elements modify text within blocks and apply additional styling on top of the block's typography.
 
+## Line Breaks
+
+Newlines follow standard CommonMark semantics by default:
+
+- **Blank line**: Starts a new paragraph.
+- **Single newline (soft break)**: Renders as a space — consecutive lines flow together into one wrapped paragraph, matching how GitHub and other CommonMark renderers display Markdown.
+- **Hard break**: Ends a line with two spaces or a backslash to force a line break within the paragraph.
+
+```markdown
+This line and
+this line render as one continuous sentence.
+
+A blank line starts a new paragraph.
+
+Two trailing spaces  
+or a trailing backslash\
+force a line break within the paragraph.
+```
+
+### Preserving single newlines
+
+When displaying content authored in `EnrichedMarkdownTextInput`, pressing Enter produces a single newline in the serialized markdown. By default, `EnrichedMarkdownText` collapses these to spaces (per CommonMark). To preserve them as visible line breaks, enable the `hardSoftBreaks` flag:
+
+```tsx
+<EnrichedMarkdownText
+  markdown={markdownFromInput}
+  md4cFlags={{ hardSoftBreaks: true }}
+/>
+```
+
+This forces the parser to treat every soft break as a hard break, so single newlines render as line breaks on all platforms.
+
 ## Images: Block vs Inline
 
 Images are automatically detected as block or inline based on context:
@@ -101,7 +149,7 @@ 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.
+You don't need to specify which type—the renderer automatically determines this based on the image's position in the content. Note that a single newline doesn't split a paragraph, so an image on its own source line directly below text is still inline; separate it with a blank line to make it a block image.
 
 ## Nested Elements
 

package/docs/IMAGE_CACHING.md

@@ -2,6 +2,30 @@
 
 Images in Markdown content are loaded, cached, and reused automatically — no configuration required.
 
+## Supported Image Sources
+
+Markdown image URLs are strings, so bundled assets must be resolved to a URI before being interpolated into the markdown:
+
+```tsx
+import { Image } from 'react-native';
+
+const logoUri = Image.resolveAssetSource(require('./assets/logo.png')).uri;
+const markdown = `![Logo](${logoUri})`;
+```
+
+This works in every environment: in dev the URI is a Metro dev-server URL, while in a release build it resolves to a drawable resource name on Android and a bundle `file://` URL on iOS — all of which are supported. URIs from `expo-asset` (`asset.uri` / `asset.localUri`) work the same way.
+
+| Source | Android | iOS / macOS |
+|---|---|---|
+| `http://`, `https://` | Yes | Yes |
+| `file://` (including percent-encoded paths) | Yes | Yes |
+| Bare asset name (release builds, expo-asset `localUri`) | Yes (drawable/raw resource) | Yes (bundle resource) |
+| `file:///android_res/…`, `file:///android_asset/…` | Yes | No |
+| `asset://`, `res://`, `content://` | Yes | No |
+| `data:` (base64) | Yes | Yes |
+
+Local sources skip the HTTP layers below (disk cache, request headers, deduplication) but still use both memory cache tiers.
+
 ## Cache Layers
 
 The library uses a three-tier caching strategy on both platforms:
@@ -16,6 +40,12 @@ The library uses a three-tier caching strategy on both platforms:
 - **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 Headers
+
+When `imageRequestHeaders` is set, the headers become part of the cache identity for both memory tiers and for request deduplication: the same URL requested with different headers is fetched and cached separately, and changing the prop re-fetches the images.
+
+One caveat: the disk cache is managed by the HTTP stack (OkHttp / `NSURLCache`) and keys responses by URL alone. A response fetched with one set of headers can be served from disk for a request with different headers, subject to standard HTTP caching semantics (`Cache-Control`, `Vary`).
+
 ## 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.