feat: support paragraph between borders (w:pBdr/w:between)

Extract paragraph border rendering into feature module at
features/paragraph-borders/ with improved between-border support.

- BetweenBorderInfo type replaces boolean flag, carrying gap extension
  and top suppression data per fragment
- Border layers extend into spacing gaps for continuous group borders
- Top borders suppressed for non-first group members
- nil/none between borders no longer form groups
- Feature registry maps OOXML elements to rendering modules

Author: caio-pizzol

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

@@ -4,7 +4,12 @@ import {
   getFragmentParagraphBorders,
   computeBetweenBorderFlags,
   type BlockLookup,
-} from './renderer.js';
+  type BetweenBorderInfo,
+} 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 };
 import { createDomPainter } from './index.js';
 import type {
   ParagraphBorders,
@@ -123,7 +128,7 @@ describe('applyParagraphBorderStyles — between borders', () => {
       top: { style: 'solid', width: 1, color: '#000' },
       between: { style: 'solid', width: 2, color: '#FF0000' },
     };
-    applyParagraphBorderStyles(e, borders, false);
+    applyParagraphBorderStyles(e, borders, betweenOff);
     expect(e.style.getPropertyValue('border-top-style')).toBe('solid');
     expect(e.style.getPropertyValue('border-bottom-style')).toBe('');
   });
@@ -136,7 +141,7 @@ describe('applyParagraphBorderStyles — between borders', () => {
 
   it('applies between border as bottom border when showBetweenBorder is true', () => {
     const e = el();
-    applyParagraphBorderStyles(e, { between: { style: 'dashed', width: 3, color: '#0F0' } }, true);
+    applyParagraphBorderStyles(e, { between: { style: 'dashed', width: 3, color: '#0F0' } }, betweenOn);
     expect(e.style.getPropertyValue('border-bottom-style')).toBe('dashed');
     expect(e.style.getPropertyValue('border-bottom-width')).toBe('3px');
     expect(e.style.getPropertyValue('border-bottom-color')).toBe('#0F0');
@@ -148,7 +153,7 @@ describe('applyParagraphBorderStyles — between borders', () => {
     applyParagraphBorderStyles(
       e,
       { bottom: { style: 'solid', width: 1, color: '#000' }, between: { style: 'double', width: 4, color: '#F00' } },
-      true,
+      betweenOn,
     );
     expect(e.style.getPropertyValue('border-bottom-style')).toBe('double');
     expect(e.style.getPropertyValue('border-bottom-width')).toBe('4px');
@@ -160,7 +165,7 @@ describe('applyParagraphBorderStyles — between borders', () => {
     applyParagraphBorderStyles(
       e,
       { bottom: { style: 'solid', width: 1, color: '#000' }, between: { style: 'double', width: 4, color: '#F00' } },
-      false,
+      betweenOff,
     );
     expect(e.style.getPropertyValue('border-bottom-style')).toBe('solid');
     expect(e.style.getPropertyValue('border-bottom-width')).toBe('1px');
@@ -176,7 +181,7 @@ describe('applyParagraphBorderStyles — between borders', () => {
       left: { style: 'solid', width: 1, color: '#000' },
       between: { style: 'dashed', width: 2, color: '#F00' },
     };
-    applyParagraphBorderStyles(e, borders, true);
+    applyParagraphBorderStyles(e, borders, betweenOn);
     expect(e.style.getPropertyValue('border-top-style')).toBe('solid');
     expect(e.style.getPropertyValue('border-right-style')).toBe('solid');
     expect(e.style.getPropertyValue('border-left-style')).toBe('solid');
@@ -187,59 +192,59 @@ describe('applyParagraphBorderStyles — between borders', () => {
   // --- partial / degenerate border specs ---
   it('handles between border with none style', () => {
     const e = el();
-    applyParagraphBorderStyles(e, { between: { style: 'none', width: 0, color: '#000' } }, true);
+    applyParagraphBorderStyles(e, { between: { style: 'none', width: 0, color: '#000' } }, betweenOn);
     expect(e.style.getPropertyValue('border-bottom-style')).toBe('none');
     expect(e.style.getPropertyValue('border-bottom-width')).toBe('0px');
   });
 
   it('defaults width to 1px when between border has no width', () => {
     const e = el();
-    applyParagraphBorderStyles(e, { between: { style: 'solid', color: '#F00' } }, true);
+    applyParagraphBorderStyles(e, { between: { style: 'solid', color: '#F00' } }, betweenOn);
     expect(e.style.getPropertyValue('border-bottom-width')).toBe('1px');
   });
 
   it('defaults color to #000 when between border has no color', () => {
     const e = el();
-    applyParagraphBorderStyles(e, { between: { style: 'solid', width: 2 } }, true);
+    applyParagraphBorderStyles(e, { between: { style: 'solid', width: 2 } }, betweenOn);
     expect(e.style.getPropertyValue('border-bottom-color')).toBe('#000');
   });
 
   it('defaults style to solid when between border has no style', () => {
     const e = el();
-    applyParagraphBorderStyles(e, { between: { width: 2, color: '#F00' } }, true);
+    applyParagraphBorderStyles(e, { between: { width: 2, color: '#F00' } }, betweenOn);
     expect(e.style.getPropertyValue('border-bottom-style')).toBe('solid');
   });
 
   it('handles between border with only width', () => {
     const e = el();
-    applyParagraphBorderStyles(e, { between: { width: 5 } }, true);
+    applyParagraphBorderStyles(e, { between: { width: 5 } }, betweenOn);
     expect(e.style.getPropertyValue('border-bottom-style')).toBe('solid');
     expect(e.style.getPropertyValue('border-bottom-width')).toBe('5px');
     expect(e.style.getPropertyValue('border-bottom-color')).toBe('#000');
   });
 
   it('clamps negative width to 0px', () => {
     const e = el();
-    applyParagraphBorderStyles(e, { between: { style: 'solid', width: -3 } }, true);
+    applyParagraphBorderStyles(e, { between: { style: 'solid', width: -3 } }, betweenOn);
     expect(e.style.getPropertyValue('border-bottom-width')).toBe('0px');
   });
 
   it('handles width=0 (renders as zero-width border)', () => {
     const e = el();
-    applyParagraphBorderStyles(e, { between: { style: 'solid', width: 0 } }, true);
+    applyParagraphBorderStyles(e, { between: { style: 'solid', width: 0 } }, betweenOn);
     expect(e.style.getPropertyValue('border-bottom-width')).toBe('0px');
   });
 
   it('no-ops when showBetweenBorder=true but borders.between is undefined', () => {
     const e = el();
-    applyParagraphBorderStyles(e, { top: { style: 'solid', width: 1 } }, true);
+    applyParagraphBorderStyles(e, { top: { style: 'solid', width: 1 } }, betweenOn);
     // Should not crash, and no bottom border should appear
     expect(e.style.getPropertyValue('border-bottom-style')).toBe('');
   });
 
   it('no-ops when borders is undefined', () => {
     const e = el();
-    applyParagraphBorderStyles(e, undefined, true);
+    applyParagraphBorderStyles(e, undefined, betweenOn);
     expect(e.style.getPropertyValue('border-bottom-style')).toBe('');
   });
 });
@@ -308,7 +313,11 @@ describe('computeBetweenBorderFlags', () => {
 
     const flags = computeBetweenBorderFlags(fragments, lookup);
     expect(flags.has(0)).toBe(true);
-    expect(flags.size).toBe(1);
+    expect(flags.get(0)?.showBetweenBorder).toBe(true);
+    // Fragment 1 also gets an entry (suppressTopBorder)
+    expect(flags.has(1)).toBe(true);
+    expect(flags.get(1)?.suppressTopBorder).toBe(true);
+    expect(flags.size).toBe(2);
   });
 
   it('does not flag when between border is not defined', () => {
@@ -436,8 +445,14 @@ describe('computeBetweenBorderFlags', () => {
 
     const flags = computeBetweenBorderFlags(fragments, lookup);
     expect(flags.has(0)).toBe(true);
+    expect(flags.get(0)?.showBetweenBorder).toBe(true);
     expect(flags.has(1)).toBe(true);
-    expect(flags.size).toBe(2);
+    expect(flags.get(1)?.showBetweenBorder).toBe(true);
+    expect(flags.get(1)?.suppressTopBorder).toBe(true);
+    expect(flags.has(2)).toBe(true);
+    expect(flags.get(2)?.suppressTopBorder).toBe(true);
+    expect(flags.get(2)?.showBetweenBorder).toBe(false);
+    expect(flags.size).toBe(3);
   });
 
   it('breaks chain when middle paragraph has different borders', () => {

packages/layout-engine/painters/dom/src/features/feature-registry.ts

@@ -0,0 +1,34 @@
+/**
+ * Rendering Feature Registry
+ *
+ * Maps OOXML elements to their rendering feature modules.
+ * This is the primary lookup table for agents and developers.
+ *
+ * To find where an OOXML element renders: search this file.
+ * To add a new rendering feature: add an entry here first.
+ *
+ * Each entry specifies:
+ * - feature: human-readable feature name (matches folder name)
+ * - module: import path relative to this file
+ * - handles: list of OOXML element paths this feature renders
+ * - spec: ECMA-376 section reference
+ */
+export const RENDERING_FEATURES = {
+  // ─── Paragraph Borders ───────────────────────────────────────────
+  // @spec ECMA-376 §17.3.1.24 (pBdr)
+  'w:pBdr': {
+    feature: 'paragraph-borders',
+    module: './paragraph-borders',
+    handles: ['w:pBdr/w:top', 'w:pBdr/w:bottom', 'w:pBdr/w:left', 'w:pBdr/w:right', 'w:pBdr/w:between', 'w:pBdr/w:bar'],
+    spec: '§17.3.1.24',
+  },
+
+  // ─── Paragraph Shading ───────────────────────────────────────────
+  // @spec ECMA-376 §17.3.1.31 (shd)
+  'w:shd': {
+    feature: 'paragraph-borders', // shading shares the border layer module
+    module: './paragraph-borders',
+    handles: ['w:shd/@w:fill', 'w:shd/@w:val', 'w:shd/@w:color'],
+    spec: '§17.3.1.31',
+  },
+} as const;

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

@@ -0,0 +1,158 @@
+/**
+ * Paragraph border DOM layer creation and CSS styling.
+ *
+ * Creates absolutely-positioned overlay elements for paragraph borders
+ * and shading, with indent-aware sizing and between-border group support.
+ *
+ * @ooxml w:pPr/w:pBdr — paragraph border properties
+ * @ooxml w:pPr/w:pBdr/w:top, w:bottom, w:left, w:right — side borders
+ * @ooxml w:pPr/w:pBdr/w:between — between border (rendered as bottom within groups)
+ * @ooxml w:pPr/w:shd — paragraph shading (background fill)
+ * @spec  ECMA-376 §17.3.1.24 (pBdr), §17.3.1.31 (shd)
+ */
+import type { ParagraphAttrs, ParagraphBorder } from '@superdoc/contracts';
+import type { BetweenBorderInfo } from './group-analysis.js';
+
+// ─── Border box sizing ─────────────────────────────────────────────
+
+/**
+ * Computes the indent-aware bounding box for paragraph border/shading layers.
+ * Borders hug the paragraph content, inset by left/right/firstLine/hanging indents.
+ */
+export const getParagraphBorderBox = (
+  fragmentWidth: number,
+  indent?: ParagraphAttrs['indent'],
+): { leftInset: number; width: number } => {
+  const indentLeft = Number.isFinite(indent?.left) ? indent!.left! : 0;
+  const indentRight = Number.isFinite(indent?.right) ? indent!.right! : 0;
+  const firstLine = Number.isFinite(indent?.firstLine) ? indent!.firstLine! : 0;
+  const hanging = Number.isFinite(indent?.hanging) ? indent!.hanging! : 0;
+  const firstLineOffset = firstLine - hanging;
+  const minLeftInset = Math.min(indentLeft, indentLeft + firstLineOffset);
+  const leftInset = Math.max(0, minLeftInset);
+  const rightInset = Math.max(0, indentRight);
+  return {
+    leftInset,
+    width: Math.max(0, fragmentWidth - leftInset - rightInset),
+  };
+};
+
+// ─── Decoration layer factory ──────────────────────────────────────
+
+/**
+ * Builds overlay elements for paragraph shading and borders.
+ * Returns layers in the order they should be appended (shading below borders).
+ *
+ * When `betweenInfo` indicates this fragment is in a border group:
+ * - The border layer extends downward by `gapBelow` px into the paragraph-spacing
+ *   gap, making left/right borders visually continuous across the group.
+ * - `suppressTopBorder` hides the top border for non-first group members.
+ * - `showBetweenBorder` replaces the bottom border with the between definition.
+ */
+export const createParagraphDecorationLayers = (
+  doc: Document,
+  fragmentWidth: number,
+  attrs?: ParagraphAttrs,
+  betweenInfo?: BetweenBorderInfo,
+): { shadingLayer?: HTMLElement; borderLayer?: HTMLElement } => {
+  if (!attrs?.borders && !attrs?.shading) return {};
+
+  const borderBox = getParagraphBorderBox(fragmentWidth, attrs.indent);
+
+  // Extend layers into the spacing gap for continuous group borders
+  const gapExtension = betweenInfo?.showBetweenBorder ? betweenInfo.gapBelow : 0;
+  const bottomValue = gapExtension > 0 ? `-${gapExtension}px` : '0px';
+
+  const baseStyles = {
+    position: 'absolute',
+    top: '0px',
+    bottom: bottomValue,
+    left: `${borderBox.leftInset}px`,
+    width: `${borderBox.width}px`,
+    pointerEvents: 'none',
+    boxSizing: 'border-box',
+  } as const;
+
+  let shadingLayer: HTMLElement | undefined;
+  if (attrs.shading) {
+    shadingLayer = doc.createElement('div');
+    shadingLayer.classList.add('superdoc-paragraph-shading');
+    Object.assign(shadingLayer.style, baseStyles);
+    applyParagraphShadingStyles(shadingLayer, attrs.shading);
+  }
+
+  let borderLayer: HTMLElement | undefined;
+  if (attrs.borders) {
+    borderLayer = doc.createElement('div');
+    borderLayer.classList.add('superdoc-paragraph-border');
+    Object.assign(borderLayer.style, baseStyles);
+    borderLayer.style.zIndex = '1';
+    applyParagraphBorderStyles(borderLayer, attrs.borders, betweenInfo);
+  }
+
+  return { shadingLayer, borderLayer };
+};
+
+// ─── Border CSS application ────────────────────────────────────────
+
+type CssBorderSide = 'top' | 'right' | 'bottom' | 'left';
+const BORDER_SIDES: CssBorderSide[] = ['top', 'right', 'bottom', 'left'];
+
+/**
+ * Applies paragraph border styles to an HTML element.
+ *
+ * Handles between-border groups:
+ * - `suppressTopBorder`: skips top border for non-first group members
+ * - `showBetweenBorder`: replaces bottom with the between border definition
+ */
+export const applyParagraphBorderStyles = (
+  element: HTMLElement,
+  borders?: ParagraphAttrs['borders'],
+  betweenInfo?: BetweenBorderInfo,
+): void => {
+  if (!borders) return;
+  const showBetweenBorder = betweenInfo?.showBetweenBorder ?? false;
+  const suppressTopBorder = betweenInfo?.suppressTopBorder ?? false;
+
+  element.style.boxSizing = 'border-box';
+  BORDER_SIDES.forEach((side) => {
+    if (side === 'top' && suppressTopBorder) return;
+    const border = borders[side];
+    if (!border) return;
+    setBorderSideStyle(element, side, border);
+  });
+
+  // Between border renders as a bottom border, overwriting any normal bottom border
+  // when the fragment is within a border group (consecutive paragraphs with matching borders)
+  if (showBetweenBorder && borders.between) {
+    setBorderSideStyle(element, 'bottom', borders.between);
+  }
+};
+
+const setBorderSideStyle = (element: HTMLElement, side: CssBorderSide, border: ParagraphBorder): void => {
+  const resolvedStyle =
+    border.style && border.style !== 'none' ? border.style : border.style === 'none' ? 'none' : 'solid';
+  if (resolvedStyle === 'none') {
+    element.style.setProperty(`border-${side}-style`, 'none');
+    element.style.setProperty(`border-${side}-width`, '0px');
+    if (border.color) {
+      element.style.setProperty(`border-${side}-color`, border.color);
+    }
+    return;
+  }
+
+  const width = border.width != null ? Math.max(0, border.width) : undefined;
+  element.style.setProperty(`border-${side}-style`, resolvedStyle);
+  element.style.setProperty(`border-${side}-width`, `${width ?? 1}px`);
+  element.style.setProperty(`border-${side}-color`, border.color ?? '#000');
+};
+
+// ─── Shading CSS application ───────────────────────────────────────
+
+/**
+ * Applies paragraph shading (background color) to an HTML element.
+ */
+export const applyParagraphShadingStyles = (element: HTMLElement, shading?: ParagraphAttrs['shading']): void => {
+  if (!shading?.fill) return;
+  element.style.backgroundColor = shading.fill;
+};