fix: group paragraphs with nil/none between border into continuous box

Word groups consecutive paragraphs with matching borders into a single
bordered box even when w:between is nil/none — it just omits the
separator. SuperDoc was skipping grouping entirely for nil/none between,
rendering each paragraph as a separate bordered box.

- Preserve between: {style: 'none'} during normalization so downstream
  can distinguish "explicitly nil/none" from "no between element"
- Change grouping check to allow nil/none between through
- Add suppressBottomBorder flag for nil/none groups (extend gap without
  drawing a separator)

Author: caio-pizzol

packages/layout-engine/painters/dom/src/between-borders.test.ts

@@ -10,8 +10,18 @@ import {
 } from './features/paragraph-borders/index.js';
 
 /** Helper to create BetweenBorderInfo for tests that previously passed a boolean. */
-const betweenOn: BetweenBorderInfo = { showBetweenBorder: true, suppressTopBorder: false, gapBelow: 0 };
-const betweenOff: BetweenBorderInfo = { showBetweenBorder: false, suppressTopBorder: false, gapBelow: 0 };
+const betweenOn: BetweenBorderInfo = {
+  showBetweenBorder: true,
+  suppressTopBorder: false,
+  suppressBottomBorder: false,
+  gapBelow: 0,
+};
+const betweenOff: BetweenBorderInfo = {
+  showBetweenBorder: false,
+  suppressTopBorder: false,
+  suppressBottomBorder: false,
+  gapBelow: 0,
+};
 import { createDomPainter } from './index.js';
 import type {
   ParagraphBorders,
@@ -258,7 +268,12 @@ describe('applyParagraphBorderStyles — between borders', () => {
       left: { style: 'solid', width: 1, color: '#000' },
       right: { style: 'solid', width: 1, color: '#000' },
     };
-    const info: BetweenBorderInfo = { showBetweenBorder: false, suppressTopBorder: true, gapBelow: 0 };
+    const info: BetweenBorderInfo = {
+      showBetweenBorder: false,
+      suppressTopBorder: true,
+      suppressBottomBorder: false,
+      gapBelow: 0,
+    };
     applyParagraphBorderStyles(e, borders, info);
     expect(e.style.getPropertyValue('border-top-style')).toBe('');
     expect(e.style.getPropertyValue('border-left-style')).toBe('solid');
@@ -274,6 +289,49 @@ describe('applyParagraphBorderStyles — between borders', () => {
     expect(e.style.getPropertyValue('border-top-style')).toBe('dashed');
     expect(e.style.getPropertyValue('border-top-width')).toBe('3px');
   });
+
+  // --- suppressBottomBorder (nil/none between groups) ---
+  it('skips bottom border when suppressBottomBorder is true', () => {
+    const e = el();
+    const borders: ParagraphBorders = {
+      top: { style: 'solid', width: 1, color: '#000' },
+      bottom: { style: 'solid', width: 2, color: '#F00' },
+      left: { style: 'solid', width: 1, color: '#000' },
+      right: { style: 'solid', width: 1, color: '#000' },
+    };
+    const info: BetweenBorderInfo = {
+      showBetweenBorder: false,
+      suppressTopBorder: false,
+      suppressBottomBorder: true,
+      gapBelow: 10,
+    };
+    applyParagraphBorderStyles(e, borders, info);
+    expect(e.style.getPropertyValue('border-top-style')).toBe('solid');
+    expect(e.style.getPropertyValue('border-left-style')).toBe('solid');
+    expect(e.style.getPropertyValue('border-right-style')).toBe('solid');
+    expect(e.style.getPropertyValue('border-bottom-style')).toBe('');
+  });
+
+  it('suppresses both top and bottom for middle fragment in nil/none group', () => {
+    const e = el();
+    const borders: ParagraphBorders = {
+      top: { style: 'solid', width: 1, color: '#000' },
+      bottom: { style: 'solid', width: 1, color: '#000' },
+      left: { style: 'solid', width: 1, color: '#000' },
+      right: { style: 'solid', width: 1, color: '#000' },
+    };
+    const info: BetweenBorderInfo = {
+      showBetweenBorder: false,
+      suppressTopBorder: true,
+      suppressBottomBorder: true,
+      gapBelow: 10,
+    };
+    applyParagraphBorderStyles(e, borders, info);
+    expect(e.style.getPropertyValue('border-top-style')).toBe('');
+    expect(e.style.getPropertyValue('border-bottom-style')).toBe('');
+    expect(e.style.getPropertyValue('border-left-style')).toBe('solid');
+    expect(e.style.getPropertyValue('border-right-style')).toBe('solid');
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -283,15 +341,25 @@ describe('applyParagraphBorderStyles — between borders', () => {
 describe('createParagraphDecorationLayers — gap extension', () => {
   it('sets bottom to negative gapBelow when showBetweenBorder is true', () => {
     const attrs = { borders: { top: { style: 'solid' as const, width: 1 } }, shading: { fill: '#EEE' } };
-    const info: BetweenBorderInfo = { showBetweenBorder: true, suppressTopBorder: false, gapBelow: 8 };
+    const info: BetweenBorderInfo = {
+      showBetweenBorder: true,
+      suppressTopBorder: false,
+      suppressBottomBorder: false,
+      gapBelow: 8,
+    };
     const { borderLayer, shadingLayer } = createParagraphDecorationLayers(document, 400, attrs, info);
     expect(borderLayer!.style.bottom).toBe('-8px');
     expect(shadingLayer!.style.bottom).toBe('-8px');
   });
 
   it('sets bottom to 0px when gapBelow is 0', () => {
     const attrs = { borders: { top: { style: 'solid' as const, width: 1 } } };
-    const info: BetweenBorderInfo = { showBetweenBorder: true, suppressTopBorder: false, gapBelow: 0 };
+    const info: BetweenBorderInfo = {
+      showBetweenBorder: true,
+      suppressTopBorder: false,
+      suppressBottomBorder: false,
+      gapBelow: 0,
+    };
     const { borderLayer } = createParagraphDecorationLayers(document, 400, attrs, info);
     expect(borderLayer!.style.bottom).toBe('0px');
   });
@@ -302,12 +370,31 @@ describe('createParagraphDecorationLayers — gap extension', () => {
     expect(borderLayer!.style.bottom).toBe('0px');
   });
 
-  it('sets bottom to 0px when showBetweenBorder is false even with gapBelow', () => {
+  it('sets bottom to 0px when showBetweenBorder is false and suppressBottomBorder is false', () => {
     const attrs = { borders: { top: { style: 'solid' as const, width: 1 } } };
-    const info: BetweenBorderInfo = { showBetweenBorder: false, suppressTopBorder: true, gapBelow: 12 };
+    const info: BetweenBorderInfo = {
+      showBetweenBorder: false,
+      suppressTopBorder: true,
+      suppressBottomBorder: false,
+      gapBelow: 12,
+    };
     const { borderLayer } = createParagraphDecorationLayers(document, 400, attrs, info);
     expect(borderLayer!.style.bottom).toBe('0px');
   });
+
+  it('sets bottom to negative gapBelow when suppressBottomBorder is true (nil/none between group)', () => {
+    const attrs = {
+      borders: { top: { style: 'solid' as const, width: 1 }, bottom: { style: 'solid' as const, width: 1 } },
+    };
+    const info: BetweenBorderInfo = {
+      showBetweenBorder: false,
+      suppressTopBorder: false,
+      suppressBottomBorder: true,
+      gapBelow: 10,
+    };
+    const { borderLayer } = createParagraphDecorationLayers(document, 400, attrs, info);
+    expect(borderLayer!.style.bottom).toBe('-10px');
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -630,6 +717,78 @@ describe('computeBetweenBorderFlags', () => {
     const flags = computeBetweenBorderFlags(fragments, lookup);
     expect(flags.size).toBe(2);
   });
+
+  // --- nil/none between grouping (continuous box without separator) ---
+  it('groups paragraphs with between: {style: "none"} (nil/none between)', () => {
+    const borders: ParagraphBorders = {
+      top: { style: 'solid', width: 1, color: '#000' },
+      right: { style: 'solid', width: 1, color: '#000' },
+      bottom: { style: 'solid', width: 1, color: '#000' },
+      left: { style: 'solid', width: 1, color: '#000' },
+      between: { style: 'none' },
+    };
+    const b1 = makeParagraphBlock('b1', borders);
+    const b2 = makeParagraphBlock('b2', borders);
+    const lookup = buildLookup([{ block: b1 }, { block: b2 }]);
+    const fragments: Fragment[] = [paraFragment('b1', { y: 0 }), paraFragment('b2', { y: 20 })];
+
+    const flags = computeBetweenBorderFlags(fragments, lookup);
+    expect(flags.size).toBe(2);
+    // First fragment: suppressBottomBorder (not showBetweenBorder)
+    expect(flags.get(0)?.showBetweenBorder).toBe(false);
+    expect(flags.get(0)?.suppressBottomBorder).toBe(true);
+    // Second fragment: suppressTopBorder
+    expect(flags.get(1)?.suppressTopBorder).toBe(true);
+    expect(flags.get(1)?.suppressBottomBorder).toBe(false);
+  });
+
+  it('groups chain of 3 paragraphs with nil/none between', () => {
+    const borders: ParagraphBorders = {
+      top: { style: 'solid', width: 1, color: '#000' },
+      bottom: { style: 'solid', width: 1, color: '#000' },
+      left: { style: 'solid', width: 1, color: '#000' },
+      right: { style: 'solid', width: 1, color: '#000' },
+      between: { style: 'none' },
+    };
+    const b1 = makeParagraphBlock('b1', borders);
+    const b2 = makeParagraphBlock('b2', borders);
+    const b3 = makeParagraphBlock('b3', borders);
+    const lookup = buildLookup([{ block: b1 }, { block: b2 }, { block: b3 }]);
+    const fragments: Fragment[] = [
+      paraFragment('b1', { y: 0 }),
+      paraFragment('b2', { y: 20 }),
+      paraFragment('b3', { y: 40 }),
+    ];
+
+    const flags = computeBetweenBorderFlags(fragments, lookup);
+    expect(flags.size).toBe(3);
+    // First: suppress bottom, keep top
+    expect(flags.get(0)?.suppressBottomBorder).toBe(true);
+    expect(flags.get(0)?.suppressTopBorder).toBe(false);
+    // Middle: suppress both top and bottom
+    expect(flags.get(1)?.suppressTopBorder).toBe(true);
+    expect(flags.get(1)?.suppressBottomBorder).toBe(true);
+    // Last: suppress top, keep bottom
+    expect(flags.get(2)?.suppressTopBorder).toBe(true);
+    expect(flags.get(2)?.suppressBottomBorder).toBe(false);
+  });
+
+  it('does not group nil/none between with real between (different hashes)', () => {
+    const nilBetween: ParagraphBorders = {
+      top: { style: 'solid', width: 1, color: '#000' },
+      between: { style: 'none' },
+    };
+    const realBetween: ParagraphBorders = {
+      top: { style: 'solid', width: 1, color: '#000' },
+      between: { style: 'solid', width: 1, color: '#000' },
+    };
+    const b1 = makeParagraphBlock('b1', nilBetween);
+    const b2 = makeParagraphBlock('b2', realBetween);
+    const lookup = buildLookup([{ block: b1 }, { block: b2 }]);
+    const fragments: Fragment[] = [paraFragment('b1'), paraFragment('b2')];
+
+    expect(computeBetweenBorderFlags(fragments, lookup).size).toBe(0);
+  });
 });
 
 // ---------------------------------------------------------------------------

packages/layout-engine/painters/dom/src/features/paragraph-borders/border-layer.ts

@@ -59,8 +59,10 @@ export const createParagraphDecorationLayers = (
 
   const borderBox = getParagraphBorderBox(fragmentWidth, attrs.indent);
 
-  // Extend layers into the spacing gap for continuous group borders
-  const gapExtension = betweenInfo?.showBetweenBorder ? betweenInfo.gapBelow : 0;
+  // Extend layers into the spacing gap for continuous group borders.
+  // Both real between (showBetweenBorder) and nil/none between (suppressBottomBorder)
+  // need gap extension to keep left/right borders continuous through the spacing gap.
+  const gapExtension = betweenInfo?.showBetweenBorder || betweenInfo?.suppressBottomBorder ? betweenInfo!.gapBelow : 0;
   const bottomValue = gapExtension > 0 ? `-${gapExtension}px` : '0px';
 
   const baseStyles = {
@@ -113,10 +115,12 @@ export const applyParagraphBorderStyles = (
   if (!borders) return;
   const showBetweenBorder = betweenInfo?.showBetweenBorder ?? false;
   const suppressTopBorder = betweenInfo?.suppressTopBorder ?? false;
+  const suppressBottomBorder = betweenInfo?.suppressBottomBorder ?? false;
 
   element.style.boxSizing = 'border-box';
   BORDER_SIDES.forEach((side) => {
     if (side === 'top' && suppressTopBorder) return;
+    if (side === 'bottom' && suppressBottomBorder) return;
     const border = borders[side];
     if (!border) return;
     setBorderSideStyle(element, side, border);
@@ -157,6 +161,7 @@ export const stampBetweenBorderDataset = (element: HTMLElement, betweenInfo?: Be
   if (!betweenInfo) return;
   if (betweenInfo.showBetweenBorder) element.dataset.betweenBorder = 'true';
   if (betweenInfo.suppressTopBorder) element.dataset.suppressTopBorder = 'true';
+  if (betweenInfo.suppressBottomBorder) element.dataset.suppressBottomBorder = 'true';
   if (betweenInfo.gapBelow) element.dataset.gapBelow = String(betweenInfo.gapBelow);
 };
 

packages/layout-engine/painters/dom/src/features/paragraph-borders/group-analysis.ts

@@ -29,6 +29,7 @@ import { hashParagraphBorders } from '../../paragraph-hash-utils.js';
 export type BetweenBorderInfo = {
   showBetweenBorder: boolean;
   suppressTopBorder: boolean;
+  suppressBottomBorder: boolean;
   gapBelow: number;
 };
 
@@ -125,14 +126,17 @@ export const computeBetweenBorderFlags = (
 ): Map<number, BetweenBorderInfo> => {
   // Phase 1: determine which consecutive pairs form between-border groups
   const pairFlags = new Set<number>();
+  const noBetweenPairs = new Set<number>();
 
   for (let i = 0; i < fragments.length - 1; i += 1) {
     const frag = fragments[i];
     if (frag.kind !== 'para' && frag.kind !== 'list-item') continue;
     if (frag.continuesOnNext) continue;
 
     const borders = getFragmentParagraphBorders(frag, blockLookup);
-    if (isBetweenBorderNone(borders)) continue;
+    // Skip if no between element at all (no grouping intent).
+    // between: {style: 'none'} (nil/none) IS allowed — it signals grouping without a separator.
+    if (!borders?.between) continue;
 
     const next = fragments[i + 1];
     if (next.kind !== 'para' && next.kind !== 'list-item') continue;
@@ -147,13 +151,18 @@ export const computeBetweenBorderFlags = (
       continue;
 
     const nextBorders = getFragmentParagraphBorders(next, blockLookup);
-    if (isBetweenBorderNone(nextBorders)) continue;
+    if (!nextBorders?.between) continue;
     if (hashParagraphBorders(borders!) !== hashParagraphBorders(nextBorders!)) continue;
 
     // Skip fragments in different columns (different x positions)
     if (frag.x !== next.x) continue;
 
     pairFlags.add(i);
+
+    // Track nil/none between pairs — these get suppressBottomBorder instead of showBetweenBorder
+    if (isBetweenBorderNone(borders) && isBetweenBorderNone(nextBorders)) {
+      noBetweenPairs.add(i);
+    }
   }
 
   // Phase 2: build per-fragment info with gap distances and top suppression
@@ -164,19 +173,33 @@ export const computeBetweenBorderFlags = (
     const next = fragments[i + 1];
     const fragHeight = getFragmentHeight(frag, blockLookup);
     const gapBelow = Math.max(0, next.y - (frag.y + fragHeight));
+    const isNoBetween = noBetweenPairs.has(i);
 
-    // Current fragment: show between border on bottom, extend into gap
+    // Current fragment: extend into gap.
+    // Real between → showBetweenBorder (replace bottom with between definition).
+    // Nil/none between → suppressBottomBorder (hide bottom, keep left/right continuous).
     if (!result.has(i)) {
-      result.set(i, { showBetweenBorder: true, suppressTopBorder: false, gapBelow });
+      result.set(i, {
+        showBetweenBorder: !isNoBetween,
+        suppressTopBorder: false,
+        suppressBottomBorder: isNoBetween,
+        gapBelow,
+      });
     } else {
       const existing = result.get(i)!;
-      existing.showBetweenBorder = true;
+      existing.showBetweenBorder = !isNoBetween;
+      existing.suppressBottomBorder = isNoBetween;
       existing.gapBelow = gapBelow;
     }
 
     // Next fragment: suppress top border (previous fragment's extended layer covers boundary)
     if (!result.has(i + 1)) {
-      result.set(i + 1, { showBetweenBorder: false, suppressTopBorder: true, gapBelow: 0 });
+      result.set(i + 1, {
+        showBetweenBorder: false,
+        suppressTopBorder: true,
+        suppressBottomBorder: false,
+        gapBelow: 0,
+      });
     } else {
       result.get(i + 1)!.suppressTopBorder = true;
     }

packages/layout-engine/pm-adapter/src/attributes/borders.test.ts

@@ -572,11 +572,13 @@ describe('normalizeParagraphBorders', () => {
       expect(result?.between?.style).toBe('dashed');
     });
 
-    it('should return undefined when between border is nil', () => {
+    it('should preserve between: {style: "none"} when between border is nil', () => {
       const input = {
         between: { val: 'nil' },
       };
-      expect(normalizeParagraphBorders(input)).toBeUndefined();
+      const result = normalizeParagraphBorders(input);
+      expect(result).toBeDefined();
+      expect(result?.between).toEqual({ style: 'none' });
     });
   });
 

packages/layout-engine/pm-adapter/src/attributes/borders.ts

@@ -334,6 +334,17 @@ export const normalizeParagraphBorders = (value: unknown): ParagraphAttrs['borde
     }
   });
 
+  // Preserve between: {style: 'none'} for nil/none between borders.
+  // normalizeBorderSide drops 'none' sides, but for 'between' we need to keep it
+  // so the grouping logic can distinguish "explicitly nil/none" (group without separator)
+  // from "no between element at all" (don't group).
+  if (!borders.between && source.between) {
+    const style = mapBorderStyle((source.between as Record<string, unknown>).val);
+    if (style === 'none') {
+      borders.between = { style: 'none' };
+    }
+  }
+
   return Object.keys(borders).length > 0 ? borders : undefined;
 };