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

package/android/src/main/java/com/swmansion/enriched/markdown/utils/text/view/SelectionActionMode.kt

@@ -25,8 +25,30 @@ private const val MENU_ITEM_CUSTOM_GROUP = 2001
 data class SelectionMenuConfig(
   val copyAsMarkdown: Boolean = true,
   val copyImageUrl: Boolean = true,
+  val copyLabel: String = "",
+  val copyAsMarkdownLabel: String = "",
+  val copyImageUrlLabel: String = "",
+  val copyImageUrlsLabel: String = "",
+  // Plural templates indexed by image count (0..100). Empty when no pluralLabels
+  // are set; counts > 100 use copyImageUrlsLabel (the "other" form).
+  val copyImageUrlPluralTemplates: List<String> = emptyList(),
 )
 
+/**
+ * Resolves the "Copy Image URL(s)" menu title for the given image count. Uses the
+ * precomputed plural templates when present (counts > 100 use the "other" form),
+ * otherwise the singular/`{count}` templates. All labels are resolved JS-side.
+ */
+private fun SelectionMenuConfig.imageUrlsTitle(count: Int): String {
+  val template =
+    when {
+      copyImageUrlPluralTemplates.isNotEmpty() && count in 0..100 -> copyImageUrlPluralTemplates[count]
+      count == 1 -> copyImageUrlLabel
+      else -> copyImageUrlsLabel
+    }
+  return template.replace("{count}", count.toString())
+}
+
 /**
  * Creates an ActionMode.Callback that adds custom copy options and
  * overrides the default "Copy" action to include HTML for rich text support.
@@ -56,12 +78,24 @@ fun createSelectionActionModeCallback(
 
       val selectionMenuConfig = getSelectionMenuConfig()
 
+      // The system Copy item is added by the platform; relabel it so it
+      // matches the rest of the localized menu (iOS rebuilds the menu so
+      // gets this for free; Android only intercepts the click).
+      if (selectionMenuConfig.copyLabel.isNotEmpty()) {
+        menu.findItem(android.R.id.copy)?.title = selectionMenuConfig.copyLabel
+      }
+
       if (
         selectionMenuConfig.copyAsMarkdown &&
         textView.selectionStart >= 0 &&
         textView.selectionEnd > textView.selectionStart
       ) {
-        menu.add(Menu.NONE, MENU_ITEM_COPY_MARKDOWN, Menu.NONE, "Copy as Markdown")
+        menu.add(
+          Menu.NONE,
+          MENU_ITEM_COPY_MARKDOWN,
+          Menu.NONE,
+          selectionMenuConfig.copyAsMarkdownLabel,
+        )
       }
 
       if (textView.selectionStart >= 0 && textView.selectionEnd > textView.selectionStart) {
@@ -80,12 +114,7 @@ fun createSelectionActionModeCallback(
           emptyList()
         }
       if (imageUrls.isNotEmpty()) {
-        val title =
-          if (imageUrls.size == 1) {
-            "Copy Image URL"
-          } else {
-            "Copy ${imageUrls.size} Image URLs"
-          }
+        val title = selectionMenuConfig.imageUrlsTitle(imageUrls.size)
         menu.add(Menu.NONE, MENU_ITEM_COPY_IMAGE_URL, Menu.NONE, title)
       }
 

package/android/src/main/java/com/swmansion/enriched/markdown/views/TableContainerView.kt

@@ -15,9 +15,12 @@ import android.text.TextPaint
 import android.text.style.AlignmentSpan
 import android.text.style.MetricAffectingSpan
 import android.view.Gravity
+import android.view.MotionEvent
 import android.view.View
 import android.widget.FrameLayout
 import android.widget.HorizontalScrollView
+import androidx.core.view.ViewCompat
+import com.swmansion.enriched.markdown.accessibility.AccessibilityLabels
 import com.swmansion.enriched.markdown.parser.MarkdownASTNode
 import com.swmansion.enriched.markdown.parser.MarkdownASTNode.NodeType
 import com.swmansion.enriched.markdown.renderer.Renderer
@@ -28,6 +31,8 @@ import com.swmansion.enriched.markdown.utils.common.serialization.MarkdownASTSer
 import com.swmansion.enriched.markdown.utils.text.conversion.HTMLGenerator
 import com.swmansion.enriched.markdown.utils.text.extensions.replaceMathSpansWithPlaceholders
 import com.swmansion.enriched.markdown.utils.text.view.LinkLongPressMovementMethod
+import com.swmansion.enriched.markdown.utils.text.view.cancelJSTouchForLinkTap
+import com.swmansion.enriched.markdown.utils.text.view.reallowParentInterceptIfLinkReleased
 import com.swmansion.enriched.markdown.views.ContextMenuPopup
 import kotlin.math.ceil
 import kotlin.math.max
@@ -49,12 +54,26 @@ class TableContainerView(
   var maxFontSizeMultiplier = 0f
   var onLinkPress: ((String) -> Unit)? = null
   var onLinkLongPress: ((String) -> Unit)? = null
+  var accessibilityLabels: AccessibilityLabels = AccessibilityLabels()
+    set(value) {
+      if (field == value) return
+      field = value
+      if (rowCount > 0) renderGrid()
+    }
+
+  var copyLabel: String = ""
+  var copyAsMarkdownLabel: String = ""
 
   private val scrollView =
     HorizontalScrollView(context).apply {
       isHorizontalScrollBarEnabled = true
       overScrollMode = View.OVER_SCROLL_NEVER
-      addView(GridContainerView(context))
+      importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_NO
+      addView(
+        GridContainerView(context).apply {
+          importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_NO
+        },
+      )
     }
   private val gridContainer get() = scrollView.getChildAt(0) as GridContainerView
 
@@ -93,6 +112,7 @@ class TableContainerView(
   private var tableMarkdown = ""
 
   init {
+    importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_NO
     addView(scrollView, LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.WRAP_CONTENT))
   }
 
@@ -191,6 +211,7 @@ class TableContainerView(
               showContextMenu(view)
               true
             }
+            importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS
           }
 
         gridContainer.addView(
@@ -204,12 +225,51 @@ class TableContainerView(
         if (col < row.size) addTextToCell(cellBg, row[col], columnWidth, rowHeight)
         if (!isRtl) xOffset += columnWidth
       }
+
+      addRowAccessibilityOverlay(row, rowIndex, isHeaderRow, yOffset, rowHeight)
+
       if (!isHeaderRow) bodyRowIndex++
       yOffset += rowHeight
     }
     gridContainer.layoutParams = LayoutParams(ceil(totalTableWidth).toInt(), ceil(totalTableHeight).toInt())
   }
 
+  private fun addRowAccessibilityOverlay(
+    row: List<TableCellData>,
+    rowIndex: Int,
+    isHeaderRow: Boolean,
+    yOffset: Float,
+    rowHeight: Float,
+  ) {
+    val joinedContent = row.joinToString(", ") { it.plainText }
+    val description =
+      accessibilityLabels.tableRow
+        .replace("{n}", (rowIndex + 1).toString())
+        .replace("{content}", joinedContent)
+
+    val overlay =
+      View(context).apply {
+        isClickable = false
+        isLongClickable = false
+        isFocusable = true
+        isScreenReaderFocusable = true
+        importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_YES
+        contentDescription = description
+        if (isHeaderRow) ViewCompat.setAccessibilityHeading(this, true)
+      }
+    gridContainer.addView(
+      overlay,
+      0,
+      LayoutParams(
+        ceil(totalTableWidth).toInt(),
+        ceil(rowHeight + tableStyle.borderWidth).toInt(),
+      ).apply {
+        leftMargin = 0
+        topMargin = ceil(yOffset).toInt()
+      },
+    )
+  }
+
   private fun addTextToCell(
     container: CellBackgroundView,
     data: TableCellData,
@@ -279,7 +339,7 @@ class TableContainerView(
   private fun showContextMenu(anchor: View) {
     val clipboard = context.getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
     ContextMenuPopup.show(anchor, this) {
-      item(ContextMenuPopup.Icon.COPY, "Copy") {
+      item(ContextMenuPopup.Icon.COPY, copyLabel) {
         val plainText = rows.joinToString("\n") { row -> row.joinToString("\t") { it.plainText } }
         if (plainText.isNotEmpty()) {
           val displayMetrics = context.resources.displayMetrics
@@ -291,7 +351,7 @@ class TableContainerView(
           clipboard.setPrimaryClip(ClipData.newHtmlText("Table", plainText, html))
         }
       }
-      item(ContextMenuPopup.Icon.DOCUMENT, "Copy as Markdown") {
+      item(ContextMenuPopup.Icon.DOCUMENT, copyAsMarkdownLabel) {
         if (tableMarkdown.isNotEmpty()) clipboard.setPrimaryClip(ClipData.newPlainText("Table", tableMarkdown))
       }
     }
@@ -488,6 +548,16 @@ class TableContainerView(
       movementMethod = LinkLongPressMovementMethod.createInstance()
       layoutDirection = View.LAYOUT_DIRECTION_LOCALE
       textDirection = View.TEXT_DIRECTION_LOCALE
+      importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_NO
+    }
+
+    override fun onTouchEvent(event: MotionEvent): Boolean {
+      val result = super.onTouchEvent(event)
+      when (event.action) {
+        MotionEvent.ACTION_DOWN -> cancelJSTouchForLinkTap(event)
+        else -> reallowParentInterceptIfLinkReleased()
+      }
+      return result
     }
   }
 

package/android/src/main/jni/CMakeLists.txt

@@ -8,7 +8,21 @@ set(LIB_ANDROID_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../../..)
 set(LIB_ANDROID_GENERATED_JNI_DIR ${LIB_ANDROID_DIR}/generated/jni)
 set(LIB_ANDROID_GENERATED_COMPONENTS_DIR ${LIB_ANDROID_GENERATED_JNI_DIR}/react/renderer/components/${LIB_LITERAL})
 
-set(CPP_ROOT "${LIB_ANDROID_DIR}/../cpp")
+# cpp/ is a symlink to packages/core/cpp in the monorepo; published tarballs
+# ship real files (materialized at prepack). Use paths relative to this file —
+# Android's cross-compile CMake pass cannot access absolute paths outside the
+# module via symlinks or REALPATH.
+set(CPP_IN_PACKAGE "${CMAKE_CURRENT_SOURCE_DIR}/../../../../cpp")
+set(CPP_IN_MONOREPO "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../core/cpp")
+
+if(EXISTS "${CPP_IN_PACKAGE}/md4c/md4c.c")
+  set(CPP_ROOT "${CPP_IN_PACKAGE}")
+elseif(EXISTS "${CPP_IN_MONOREPO}/md4c/md4c.c")
+  set(CPP_ROOT "${CPP_IN_MONOREPO}")
+else()
+  message(FATAL_ERROR "EnrichedMarkdown C++ sources not found. Expected cpp/ or packages/core/cpp.")
+endif()
+
 set(ANDROID_CPP_DIR "${LIB_ANDROID_DIR}/src/main/cpp")
 
 file(GLOB MD4C_SOURCES "${CPP_ROOT}/md4c/*.c")

package/android/src/math/java/com/swmansion/enriched/markdown/views/MathContainerView.kt

@@ -11,6 +11,7 @@ import android.view.ViewGroup.LayoutParams.MATCH_PARENT
 import android.view.ViewGroup.LayoutParams.WRAP_CONTENT
 import android.widget.FrameLayout
 import android.widget.HorizontalScrollView
+import com.swmansion.enriched.markdown.accessibility.AccessibilityLabels
 import com.swmansion.enriched.markdown.spans.MathMeasureHelper
 import com.swmansion.enriched.markdown.spans.MathMeasureRequest
 import com.swmansion.enriched.markdown.spans.MathRenderMode
@@ -30,6 +31,16 @@ class MathContainerView(
   private val scrollView = HorizontalScrollView(context)
   private var cachedLatex: String = ""
 
+  var accessibilityLabels: AccessibilityLabels = AccessibilityLabels()
+    set(value) {
+      field = value
+      updateAccessibilityLabel()
+    }
+
+  // Set reflectively by EnrichedMarkdown (math is an optional module).
+  var copyLabel: String = ""
+  var copyAsMarkdownLabel: String = ""
+
   override val segmentMarginTop: Int get() = mathStyle.marginTop.toInt()
   override val segmentMarginBottom: Int get() = mathStyle.marginBottom.toInt()
 
@@ -64,11 +75,17 @@ class MathContainerView(
       isHorizontalScrollBarEnabled = true
       overScrollMode = View.OVER_SCROLL_NEVER
       isFillViewport = true
+      importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS
       addView(mathWrapper, LayoutParams(WRAP_CONTENT, WRAP_CONTENT))
     }
 
     addView(scrollView, LayoutParams(MATCH_PARENT, WRAP_CONTENT))
 
+    isFocusable = true
+    isScreenReaderFocusable = true
+    importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_YES
+    updateAccessibilityLabel()
+
     setOnLongClickListener { view ->
       showContextMenu(view)
       true
@@ -90,15 +107,20 @@ class MathContainerView(
     }
     mathView.requestLayout()
     mathView.invalidate()
+    updateAccessibilityLabel()
+  }
+
+  private fun updateAccessibilityLabel() {
+    contentDescription = accessibilityLabels.mathEquation.replace("{latex}", cachedLatex)
   }
 
   private fun showContextMenu(anchor: View) {
     val clipboard = context.getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
     ContextMenuPopup.show(anchor, this) {
-      item(ContextMenuPopup.Icon.COPY, "Copy") {
+      item(ContextMenuPopup.Icon.COPY, copyLabel) {
         clipboard.setPrimaryClip(ClipData.newPlainText("Math", cachedLatex))
       }
-      item(ContextMenuPopup.Icon.DOCUMENT, "Copy as Markdown") {
+      item(ContextMenuPopup.Icon.DOCUMENT, copyAsMarkdownLabel) {
         clipboard.setPrimaryClip(ClipData.newPlainText("Math", "$$\n$cachedLatex\n$$"))
       }
     }

package/app.plugin.js

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

package/cpp/parser/MD4CParser.cpp

@@ -536,4 +536,4 @@ const std::string MD4CParser::Impl::ATTR_LANGUAGE = "language";
 const std::string MD4CParser::Impl::ATTR_IS_TASK = "isTask";
 const std::string MD4CParser::Impl::ATTR_TASK_CHECKED = "taskChecked";
 
-} // namespace Markdown
+} // namespace Markdown

package/cpp/wasm/build.sh

@@ -6,17 +6,17 @@
 #   # or follow https://emscripten.org/docs/getting_started/downloads.html
 #
 # Usage:
-#   bash cpp/wasm/build.sh
+#   bash packages/core/cpp/wasm/build.sh
 #
 # Output:
-#   src/web/wasm/md4c.js   — Emscripten glue with WASM binary inlined as base64
-#                            (SINGLE_FILE=1 means no separate .wasm file is needed)
+#   packages/react-native-enriched-markdown/src/web/wasm/md4c.js
 
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PACKAGE_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-OUT_DIR="$PACKAGE_ROOT/src/web/wasm"
+CPP_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+OUT_DIR="${OUT_DIR:-$REPO_ROOT/packages/react-native-enriched-markdown/src/web/wasm}"
 
 mkdir -p "$OUT_DIR"
 
@@ -24,18 +24,18 @@ echo "Building md4c WASM…"
 
 # Compile the C file separately (no -std=c++17)
 emcc \
-  -I "$PACKAGE_ROOT/cpp" \
+  -I "$CPP_ROOT" \
   -O2 \
-  -c "$PACKAGE_ROOT/cpp/md4c/md4c.c" \
+  -c "$CPP_ROOT/md4c/md4c.c" \
   -o "$OUT_DIR/md4c.o"
 
 # Compile C++ sources and link everything together
 emcc \
   "$SCRIPT_DIR/md4c_wasm.cpp" \
   "$SCRIPT_DIR/ASTSerializer.cpp" \
-  "$PACKAGE_ROOT/cpp/parser/MD4CParser.cpp" \
+  "$CPP_ROOT/parser/MD4CParser.cpp" \
   "$OUT_DIR/md4c.o" \
-  -I "$PACKAGE_ROOT/cpp" \
+  -I "$CPP_ROOT" \
   -I "$SCRIPT_DIR" \
   -O2 \
   -std=c++17 \

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.