feat: add list.markerWidth for aligning unordered, ordered, and task lists

Today each list type reserves its own natural marker column width — the
bullet radius (`bulletSize / 2`) for unordered, the width of `"99."` at
the marker font for ordered, and the checkbox size for tasks. Mixed
lists therefore look ragged: bullets and task boxes hang far to the left
of numbers.

The new optional `list.markerWidth` acts as a floor applied to all three
list types. Each list's effective column becomes `max(markerWidth,
natural)`, so consumers can widen the gutter uniformly without shrinking
ordered lists or resizing bullet/checkbox glyphs. Values below the
natural width are ignored.

```tsx
<EnrichedMarkdownText
  markdownStyle={{
    list: {
      bulletSize: 6,
      markerWidth: 22, // widens UL and task rows to match OL at 17pt
    },
  }}
  ...
/>
```

Implementation:

- Public `ListStyle.markerWidth?: number` (undefined = current
  per-list-natural behavior).
- Internal codegen prop is a concrete `Float`; negative = "auto". Default
  is set in `normalizeMarkdownStyle` so consumers never touch the
  sentinel.
- iOS: `StyleConfig` now floors each list kind — new
  `effectiveListMarginLeftForTask` plus updated
  `effectiveListMarginLeftForBullet` / `effectiveListMarginLeftForNumber`.
  `ListItemRenderer.m` routes the task case through the new accessor.
  Wired through `StylePropsUtils` and included in the measurement cache
  key so cached sizes invalidate when it changes.
- Android: `ListStyle.effectiveMarkerWidth(natural)` helper; each span
  (`UnorderedListSpan`, `OrderedListSpan`, `TaskListSpan`) applies the
  floor. Bullets and checkboxes now position themselves relative to the
  reserved column's right edge so they line up flush with the gap —
  behaviorally identical at the default since the column width equals
  the natural glyph width.
- Docs: replaced the old bulletSize-only row in `docs/STYLES.md` with
  the shared `markerWidth` semantics.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mozharovsky

android/src/main/java/com/swmansion/enriched/markdown/spans/OrderedListSpan.kt

@@ -52,7 +52,7 @@ class OrderedListSpan(
 
   override fun getMarkerWidth(): Float {
     val paint = configureMarkerPaint()
-    return paint.measureText("99.")
+    return listStyle.effectiveMarkerWidth(paint.measureText("99."))
   }
 
   var itemNumber: Int = 1

android/src/main/java/com/swmansion/enriched/markdown/spans/TaskListSpan.kt

@@ -13,7 +13,7 @@ import com.swmansion.enriched.markdown.styles.TaskListStyle
 
 class TaskListSpan(
   private val taskStyle: TaskListStyle,
-  listStyle: ListStyle,
+  private val listStyle: ListStyle,
   depth: Int,
   context: Context,
   styleCache: SpanStyleCache,
@@ -34,6 +34,7 @@ class TaskListSpan(
     gapWidth = listStyle.gapWidth,
   ) {
   private val checkboxSize = taskStyle.checkboxSize
+  private val markerColumnWidth = listStyle.effectiveMarkerWidth(checkboxSize)
   private val cornerRadius = taskStyle.checkboxBorderRadius
   private val rect = RectF()
   private val checkPath = Path()
@@ -55,7 +56,7 @@ class TaskListSpan(
       strokeJoin = Paint.Join.ROUND
     }
 
-  override fun getMarkerWidth(): Float = checkboxSize
+  override fun getMarkerWidth(): Float = markerColumnWidth
 
   override fun drawMarker(
     canvas: Canvas,
@@ -71,7 +72,10 @@ class TaskListSpan(
     val fontMetrics = paint.fontMetrics
     val capHeight = -fontMetrics.ascent * CAP_HEIGHT_RATIO
     val centerY = baseline - capHeight / HALF_DIVISOR
-    val centerX = x + (depth * marginLeft + checkboxSize / HALF_DIVISOR) * dir
+    // Right-align the checkbox inside the reserved marker column so it hugs
+    // the gap before the text. At the default (markerColumnWidth ==
+    // checkboxSize) this is identical to the previous flush-left layout.
+    val centerX = x + (depth * marginLeft + markerColumnWidth - checkboxSize / HALF_DIVISOR) * dir
     val half = checkboxSize / HALF_DIVISOR
     rect.set(centerX - half, centerY - half, centerX + half, centerY + half)
 

android/src/main/java/com/swmansion/enriched/markdown/spans/UnorderedListSpan.kt

@@ -35,13 +35,14 @@ class UnorderedListSpan(
   }
 
   private val radius: Float = listStyle.bulletSize / 2f
+  private val markerColumnWidth: Float = listStyle.effectiveMarkerWidth(radius)
 
   private fun configureBulletPaint(): Paint =
     sharedBulletPaint.apply {
       color = listStyle.bulletColor
     }
 
-  override fun getMarkerWidth(): Float = radius
+  override fun getMarkerWidth(): Float = markerColumnWidth
 
   override fun drawMarker(
     canvas: Canvas,
@@ -55,7 +56,11 @@ class UnorderedListSpan(
     start: Int,
   ) {
     val bulletPaint = configureBulletPaint()
-    val bulletX = x + (depth * marginLeft + radius) * dir
+    // Center the bullet at the right edge of the reserved marker column so
+    // it hugs the gap before the text — matches iOS behavior and stays
+    // visually flush-left when the column width equals the bullet radius
+    // (the default).
+    val bulletX = x + (depth * marginLeft + markerColumnWidth) * dir
     val fontMetrics = paint.fontMetrics
     val bulletY = baseline + (fontMetrics.ascent + fontMetrics.descent) / 2f
 

android/src/main/java/com/swmansion/enriched/markdown/styles/ListStyle.kt

@@ -12,11 +12,17 @@ data class ListStyle(
   override val lineHeight: Float,
   val bulletColor: Int,
   val bulletSize: Float,
+  val markerWidth: Float,
   val markerColor: Int,
   val markerFontWeight: String,
   val gapWidth: Float,
   val marginLeft: Float,
 ) : BaseBlockStyle {
+
+  /** Floor `naturalWidth` by the consumer-configured `markerWidth`. */
+  fun effectiveMarkerWidth(naturalWidth: Float): Float =
+    if (markerWidth > naturalWidth) markerWidth else naturalWidth
+
   companion object {
     fun fromReadableMap(
       map: ReadableMap,
@@ -32,6 +38,13 @@ data class ListStyle(
       val lineHeight = parser.toPixelFromSP(lineHeightRaw)
       val bulletColor = parser.parseColor(map, "bulletColor")
       val bulletSize = parser.toPixelFromDIP(map.getDouble("bulletSize").toFloat())
+      val markerWidthRaw = map.getDouble("markerWidth").toFloat()
+      val markerWidth =
+        if (markerWidthRaw < 0f) {
+          -1f
+        } else {
+          parser.toPixelFromDIP(markerWidthRaw)
+        }
       val markerColor = parser.parseColor(map, "markerColor")
       val markerFontWeight = parser.parseString(map, "markerFontWeight", "normal")
       val gapWidth = parser.toPixelFromDIP(map.getDouble("gapWidth").toFloat())
@@ -47,6 +60,7 @@ data class ListStyle(
         lineHeight,
         bulletColor,
         bulletSize,
+        markerWidth,
         markerColor,
         markerFontWeight,
         gapWidth,

apps/example/src/markdownStyles.ts

@@ -69,6 +69,7 @@ export const customMarkdownStyle: MarkdownStyle = {
     lineHeight: Platform.select({ ios: 22, android: 26, default: 26 }),
     bulletColor: '#6b7280',
     bulletSize: 6,
+    markerWidth: 20,
     markerColor: '#6b7280',
     markerFontWeight: '500',
     gapWidth: 8,

docs/STYLES.md

@@ -238,6 +238,7 @@ The library provides sensible default styles for all Markdown elements out of th
 |----------|------|-------------|
 | `bulletColor` | `string` | Bullet point color |
 | `bulletSize` | `number` | Bullet point size |
+| `markerWidth` | `number` | Minimum reserved marker column width (floors the natural width of every list type) |
 | `markerColor` | `string` | Number marker color |
 | `markerFontWeight` | `string` | Number marker font weight |
 | `gapWidth` | `number` | Gap between marker and text |

ios/internals/MeasurementCache.h

@@ -103,7 +103,7 @@ template <typename StyleStruct> inline size_t computeStyleFingerprint(const Styl
   hashFields(s.blockquote.borderWidth, s.blockquote.gapWidth);
 
   hashTextLayout(s.list);
-  hashFields(s.list.bulletSize, s.list.markerFontWeight, s.list.gapWidth, s.list.marginLeft);
+  hashFields(s.list.bulletSize, s.list.markerWidth, s.list.markerFontWeight, s.list.gapWidth, s.list.marginLeft);
 
   // Code & Inlines
   hashFields(s.codeBlock.fontFamily, s.codeBlock.fontSize, s.codeBlock.fontWeight, s.codeBlock.marginTop,

ios/renderer/ListItemRenderer.m

@@ -73,7 +73,7 @@ - (void)renderNode:(MarkdownASTNode *)node into:(NSMutableAttributedString *)out
 
   // currentDepth - 1 handles the horizontal offset for nested lists
   const NSInteger nestingLevel = currentDepth - 1;
-  const CGFloat baseMarkerWidth = isTask                                  ? [_config taskListCheckboxSize]
+  const CGFloat baseMarkerWidth = isTask                                  ? [_config effectiveListMarginLeftForTask]
                                   : (context.listType == ListTypeOrdered) ? [_config effectiveListMarginLeftForNumber]
                                                                           : [_config effectiveListMarginLeftForBullet];
 

ios/styles/StyleConfig.h

@@ -236,6 +236,8 @@
 - (void)setListStyleBulletColor:(RCTUIColor *)newValue;
 - (CGFloat)listStyleBulletSize;
 - (void)setListStyleBulletSize:(CGFloat)newValue;
+- (CGFloat)listStyleMarkerWidth;
+- (void)setListStyleMarkerWidth:(CGFloat)newValue;
 - (RCTUIColor *)listStyleMarkerColor;
 - (void)setListStyleMarkerColor:(RCTUIColor *)newValue;
 - (NSString *)listStyleMarkerFontWeight;
@@ -249,6 +251,7 @@
 - (CGFloat)effectiveListGapWidth;
 - (CGFloat)effectiveListMarginLeftForBullet;
 - (CGFloat)effectiveListMarginLeftForNumber;
+- (CGFloat)effectiveListMarginLeftForTask;
 // Code block properties
 - (CGFloat)codeBlockFontSize;
 - (void)setCodeBlockFontSize:(CGFloat)newValue;

ios/styles/StyleConfig.mm

@@ -151,6 +151,7 @@ @implementation StyleConfig {
   CGFloat _listStyleLineHeight;
   RCTUIColor *_listStyleBulletColor;
   CGFloat _listStyleBulletSize;
+  CGFloat _listStyleMarkerWidth;
   RCTUIColor *_listStyleMarkerColor;
   NSString *_listStyleMarkerFontWeight;
   CGFloat _listStyleGapWidth;
@@ -434,6 +435,7 @@ - (id)copyWithZone:(NSZone *)zone
   copy->_listStyleLineHeight = _listStyleLineHeight;
   copy->_listStyleBulletColor = [_listStyleBulletColor copy];
   copy->_listStyleBulletSize = _listStyleBulletSize;
+  copy->_listStyleMarkerWidth = _listStyleMarkerWidth;
   copy->_listStyleMarkerColor = [_listStyleMarkerColor copy];
   copy->_listStyleMarkerFontWeight = [_listStyleMarkerFontWeight copy];
   copy->_listStyleGapWidth = _listStyleGapWidth;
@@ -1706,6 +1708,16 @@ - (void)setListStyleBulletSize:(CGFloat)newValue
   _listStyleBulletSize = newValue;
 }
 
+- (CGFloat)listStyleMarkerWidth
+{
+  return _listStyleMarkerWidth;
+}
+
+- (void)setListStyleMarkerWidth:(CGFloat)newValue
+{
+  _listStyleMarkerWidth = newValue;
+}
+
 - (RCTUIColor *)listStyleMarkerColor
 {
   return _listStyleMarkerColor;
@@ -1786,16 +1798,30 @@ - (CGFloat)effectiveListGapWidth
 
 - (CGFloat)effectiveListMarginLeftForBullet
 {
-  // Just the minimum width needed for bullet (radius)
-  return _listStyleBulletSize / 2.0;
+  // Natural width for a bullet is the bullet radius (bulletSize / 2). The
+  // consumer-provided `markerWidth` acts as a floor so bulleted lists can
+  // line up with ordered / task lists without resizing the bullet glyph.
+  CGFloat natural = _listStyleBulletSize / 2.0;
+  return _listStyleMarkerWidth > natural ? _listStyleMarkerWidth : natural;
 }
 
 - (CGFloat)effectiveListMarginLeftForNumber
 {
-  // Reserve width for numbers up to 99 (matching Android)
+  // Reserve width for numbers up to 99 (matching Android). `markerWidth`
+  // floors the value so consumers can widen the column uniformly.
   UIFont *font = [self listMarkerFont];
-  return
+  CGFloat natural =
       [@"99." sizeWithAttributes:@{NSFontAttributeName : font ?: [UIFont systemFontOfSize:_listStyleFontSize]}].width;
+  return _listStyleMarkerWidth > natural ? _listStyleMarkerWidth : natural;
+}
+
+- (CGFloat)effectiveListMarginLeftForTask
+{
+  // Task checkbox reserves at least its own size. `markerWidth` can widen
+  // the column so task rows align with adjacent UL/OL rows. The checkbox
+  // glyph itself is still drawn at its configured size.
+  CGFloat natural = [self taskListCheckboxSize];
+  return _listStyleMarkerWidth > natural ? _listStyleMarkerWidth : natural;
 }
 
 // Code block properties