💡 RFC: Bring the rendering accuracy & features of the PDF Formatter into HTML

[isaiahdahl]

Background & Motivation

I want to be able to to custom line breaking and the section grouping logic work while getting the benefits of HTML so we could target things like hovering over a chord.

PDF Formatter inherently has a benefit of being able to measure text. Which is just not possible when generating the HTML client side.

Long story short, after quite a bit of research and strategizing with various thinking models (Grok & Claude) I think I've landed on a solution trajectory that would effectively push the creating of the dom elements to the client side.

Through that process I discovered that browser CSS ( even with a bit of JS manipulating or adding custom classes) just won't cut it. You simply can't know when a line will break and so applying the soft break logic and capitilizing the first word isn't possible to target.

I tried multiple times creating a simple HTML demo with markup to simulate how to do this with CSS tricks and got nowhere.

This led me to try and see where we could get to with creating a "measureText" function. Knowing that if we could accurately measure text elements, we could manipulate the song like we do in the PDFormatter and then create a new "song" object and then render elements from that. But since we measured the items, the created dom could know that it won't have to break anything, because the model its rendering from was pre adjusted.

Proposed Solution

This demo measures a simplified song model via two methods. Creating and measuring DOM elements, and creating and measuring canvas elements:

https://codepen.io/isaiahdahl/pen/YPzNNJj

This effectively turns

{
  "title": "Echoes of the Valley",
  "artist": "The Wandering Minstrels",
  "paragraphs": [
    // Verse 1
    {
      "lines": [
        {
          "type": "verse",
          "items": [
            { "chord": "Am", "lyric": "Morning " },
            { "lyric": "light breaks through the " },
            { "chord": "C", "lyric": "mist, " },
            { "lyric": "golden rays the mountains kissed" }
          ]
        },
        {
          "type": "verse",
          "items": [
            { "chord": "G", "lyric": "Valley " },
            { "lyric": "floor starts to " },
            { "chord": "D", "lyric": "glow, " },
            { "lyric": "as the gentle breezes blow" }
          ]
        }
      ]
   }
 ]
}

into

{
  "paragraphs": [
    {
      "paragraph_index": 0,
      "lines": [
        {
          "line_index": 0,
          "type": "verse",
          "total_width": 510,
          "total_height": 24,
          "fits_container": true,
          "items": [
            {
              "text": "Morning ",
              "chord": "Am",
              "text_width": 62,
              "text_height": 24,
              "chord_width": 17,
              "chord_height": 21,
              "x_position": 0,
              "break_points": [
                {
                  "index": 7,
                  "type": "space"
                }
              ]
            },
            {
              "text": "light breaks through the ",
              "chord": "",
              "text_width": 172,
              "text_height": 24,
              "chord_width": 0,
              "chord_height": 0,
              "x_position": 62,
              "break_points": [
                {
                  "index": 5,
                  "type": "space"
                },
                {
                  "index": 12,
                  "type": "space"
                },
                {
                  "index": 20,
                  "type": "space"
                },
                {
                  "index": 24,
                  "type": "space"
                }
              ]
            },
            {
              "text": "mist, ",
              "chord": "C",
              "text_width": 38,
              "text_height": 24,
              "chord_width": 8,
              "chord_height": 21,
              "x_position": 234,
              "break_points": [
                {
                  "index": 4,
                  "type": "comma"
                },
                {
                  "index": 5,
                  "type": "space"
                }
              ]
            },
            {
              "text": "golden rays the mountains kissed",
              "chord": "",
              "text_width": 237,
              "text_height": 24,
              "chord_width": 0,
              "chord_height": 0,
              "x_position": 272,
              "break_points": [
                {
                  "index": 6,
                  "type": "space"
                },
                {
                  "index": 11,
                  "type": "space"
                },
                {
                  "index": 15,
                  "type": "space"
                },
                {
                  "index": 25,
                  "type": "space"
                }
              ]
            }
          ]
        },
        {
          "line_index": 1,
          "type": "verse",
          "total_width": 375,
          "total_height": 24,
          "fits_container": true,
          "items": [
            {
              "text": "Valley ",
              "chord": "G",
              "text_width": 47,
              "text_height": 24,
              "chord_width": 8,
              "chord_height": 21,
              "x_position": 0,
              "break_points": [
                {
                  "index": 6,
                  "type": "space"
                }
              ]
            },
            {
              "text": "floor starts to ",
              "chord": "",
              "text_width": 97,
              "text_height": 24,
              "chord_width": 0,
              "chord_height": 0,
              "x_position": 47,
              "break_points": [
                {
                  "index": 5,
                  "type": "space"
                },
                {
                  "index": 12,
                  "type": "space"
                },
                {
                  "index": 15,
                  "type": "space"
                }
              ]
            },
            {
              "text": "glow, ",
              "chord": "D",
              "text_width": 41,
              "text_height": 24,
              "chord_width": 8,
              "chord_height": 21,
              "x_position": 144,
              "break_points": [
                {
                  "index": 4,
                  "type": "comma"
                },
                {
                  "index": 5,
                  "type": "space"
                }
              ]
            },
            {
              "text": "as the gentle breezes blow",
              "chord": "",
              "text_width": 190,
              "text_height": 24,
              "chord_width": 0,
              "chord_height": 0,
              "x_position": 185,
              "break_points": [
                {
                  "index": 2,
                  "type": "space"
                },
                {
                  "index": 6,
                  "type": "space"
                },
                {
                  "index": 13,
                  "type": "space"
                },
                {
                  "index": 21,
                  "type": "space"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

The trajectory of this solution is to take what's in the PDF formatter and abstract it so that there can be different underlying measure functions.

effectively making it so that this code can be run with a "measurer" and then instead of the node library executing this code. the librarycould expose the code so that the client could run it with the DOm or Canvas measuring logic powering it. The client would be running this with the context of how much space it has to work with.

    paragraph.lines.forEach((line) => {
      if (lineHasContents(line)) {
        const lineLayouts = this.measureAndComputeLineLayouts(line);
        const lineHeight = lineLayouts.reduce((sum, l) => sum + l.lineHeight, 0);
        paragraphSummary.totalHeight += lineHeight;
        lineLayouts.forEach((lineLayout) => {
          if (lineLayout.type === 'ChordLyricsPair') {
            paragraphSummary.countChordLyricPairLines += 1;
          } else if (lineLayout.type === 'Comment' || lineLayout.type === 'SectionLabel') {
            paragraphSummary.countNonLyricLines += 1;
          }
        });
        paragraphSummary.lineLayouts.push(lineLayouts);
      }
    });

    paragraphSummary.lineLayouts = this.insertColumnBreaks(paragraphSummary);

Then instead of the client calling the formatter with the song, it would call the measure...er with a config, width constraint it would know from already rendering the "container" where the song will go and either a custom provided "measure" class, or that specify the one built in the library (which would only work when run in the dom). Then once it's got the measure results, it would build the dom from the results, effectively building it's own renderLines() of the PdfFormatter

In an ideal world I'm thinking we (internally) build the client rendering in StencilJs so that there is structured web-components that can hold the rendering logic of certain elements, makes it easy to power it from a config. Then those web components could be open sourced and you'd have a way to support advanced rendering in the client.

Alternatives considered

I tried multiple times creating a simple HTML demo with markup to simulate how to do this with CSS tricks and got nowhere.

Risks, downsides, and/or tradeoffs

The first thought as to a downside would be speed, but the test parsed a reasonably long song in like 7ms. (though I do have a pretty fast machine); and 15ms on my iPhone 15.

Open Questions

[isaiahdahl]

From Grok:

To address your RFC titled "Bring the rendering accuracy & features of the PDF Formatter into HTML," the goal is to enhance HTML rendering of chord sheets to match the PDF formatter's precision in custom line breaking and section grouping, while adding HTML-specific interactivity (e.g., hovering over chords). Below is a comprehensive solution based on your requirements, the limitations identified, and the demo provided.

---

Understanding the Problem

The PdfFormatter class excels at rendering chord sheets because it operates server-side with precise text measurement capabilities via jsPDF. It can:

• Measure text dimensions accurately.
• Control line breaks and capitalize text post-break.
• Group sections logically.

In contrast, HTML rendering is client-side, dynamic, and browser-dependent, making text measurement and layout control challenging. CSS alone cannot reliably detect line breaks or adjust content dynamically based on layout, as you discovered through your CSS-based attempts.

Your proposed solution—measuring text client-side and pre-adjusting the song model before rendering DOM elements—is a strong foundation. The CodePen demo (https://codepen.io/isaiahdahl/pen/YPzNNJj) demonstrates this by measuring a simplified song using DOM and canvas methods, producing an enhanced song object with precise metrics (e.g., widths, heights, break points).

---

Proposed Solution

The solution involves abstracting the PdfFormatter’s measuring and layout logic into reusable modules, enabling both server-side PDF rendering and client-side HTML rendering with consistent accuracy. Here’s how to implement it:

1. Abstract the Measuring Logic

Create a Measurer interface to standardize text measurement across contexts:

interface Measurer {
  measureTextWidth(text: string, fontConfig: FontConfiguration): number;
  measureTextHeight(text: string, fontConfig: FontConfiguration): number;
}

• PDF Implementation (JsPdfMeasurer):

  • Uses jsPDF’s getTextWidth and getTextDimensions methods.
  • Runs server-side for PDF generation.

  class JsPdfMeasurer implements Measurer {
    constructor(private doc: JsPDF) {}
    measureTextWidth(text: string, fontConfig: FontConfiguration): number {
      this.doc.setFont(fontConfig.family, fontConfig.style || "normal");
      this.doc.setFontSize(fontConfig.size);
      return this.doc.getTextWidth(text);
    }
    measureTextHeight(text: string, fontConfig: FontConfiguration): number {
      this.doc.setFont(fontConfig.family, fontConfig.style || "normal");
      this.doc.setFontSize(fontConfig.size);
      return this.doc.getTextDimensions(text).h;
    }
  }

• HTML Implementation (CanvasMeasurer):

  • Uses the HTML5 Canvas API’s measureText method for speed and consistency.
  • Runs client-side, avoiding DOM manipulation overhead.

  class CanvasMeasurer implements Measurer {
    private ctx: CanvasRenderingContext2D;
    constructor() {
      const canvas = document.createElement("canvas");
      this.ctx = canvas.getContext("2d")!;
    }
    measureTextWidth(text: string, fontConfig: FontConfiguration): number {
      this.ctx.font = `${fontConfig.size}px ${fontConfig.family}`;
      return this.ctx.measureText(text).width;
    }
    measureTextHeight(text: string, fontConfig: FontConfiguration): number {
      // Approximate height based on font size (canvas doesn't provide this directly)
      return fontConfig.size * (fontConfig.lineHeight || 1.2);
    }
  }

  • Why Canvas? It’s faster than DOM-based measuring (e.g., using a hidden div’s offsetWidth), as it avoids reflows, and is well-supported across browsers.

2. Refactor Layout Logic into a LayoutEngine

Extract the layout computation from PdfFormatter (e.g., measureAndComputeLineLayouts, computeLineLayouts) into a standalone LayoutEngine class that uses the Measurer:

interface Layout {
  paragraphs: {
    lines: LineLayout[];
  }[];
}

class LayoutEngine {
  constructor(private measurer: Measurer, private config: Configuration) {}

  computeLayout(song: Song, availableWidth: number): Layout {
    const layout: Layout = { paragraphs: [] };
    song.paragraphs.forEach((paragraph) => {
      const paragraphLayout = { lines: [] };
      paragraph.lines.forEach((line) => {
        if (lineHasContents(line)) {
          const lineLayouts = this.measureAndComputeLineLayouts(line, availableWidth);
          paragraphLayout.lines.push(...lineLayouts);
        }
      });
      layout.paragraphs.push(paragraphLayout);
    });
    return layout;
  }

  private measureAndComputeLineLayouts(line: Line, availableWidth: number): LineLayout[] {
    // Adapted from PdfFormatter: measure items, compute breaks, adjust text
    const measuredItems = line.items.flatMap((item) => this.measureItem(item));
    return this.computeLineLayouts(measuredItems, availableWidth);
  }

  private measureItem(item: Item): MeasuredItem[] {
    // Use this.measurer to measure text based on item type (chords, lyrics, etc.)
    // Logic adapted from PdfFormatter.measureItem
  }

  private computeLineLayouts(items: MeasuredItem[], availableWidth: number): LineLayout[] {
    // Logic adapted from PdfFormatter.computeLineLayouts
    // Handles line breaking, capitalization, etc.
  }
}

• Key Features:
  • Measures text using the provided Measurer.
  • Computes line breaks based on availableWidth.
  • Adjusts text (e.g., capitalizes after breaks) as in PdfFormatter.
  • Outputs a Layout object with all necessary rendering data.

3. Client-Side HTML Rendering

Implement an HtmlRenderer to build DOM elements from the computed layout:

class HtmlRenderer {
  render(layout: Layout, container: HTMLElement): void {
    container.innerHTML = ""; // Clear container
    layout.paragraphs.forEach((paragraph) => {
      const paragraphEl = document.createElement("div");
      paragraphEl.className = "paragraph";
      paragraph.lines.forEach((line) => {
        const lineEl = document.createElement("div");
        lineEl.className = "line";
        line.items.forEach((item) => {
          if (item.item instanceof ChordLyricsPair) {
            const pairEl = document.createElement("span");
            pairEl.className = "chord-lyrics-pair";
            if (item.item.chords) {
              const chordEl = document.createElement("span");
              chordEl.className = "chord";
              chordEl.textContent = item.item.chords;
              chordEl.dataset.tooltip = "Chord info"; // For interactivity
              pairEl.appendChild(chordEl);
            }
            if (item.item.lyrics) {
              const lyricsEl = document.createElement("span");
              lyricsEl.className = "lyrics";
              lyricsEl.textContent = item.item.lyrics;
              pairEl.appendChild(lyricsEl);
            }
            lineEl.appendChild(pairEl);
          }
        });
        paragraphEl.appendChild(lineEl);
      });
      container.appendChild(paragraphEl);
    });
  }
}

• Rendering Strategy:
  • Creates explicit DOM elements (div for lines, span for chords/lyrics) based on the precomputed layout.
  • Avoids reliance on CSS for line breaking by using the layout’s measurements.
  • Adds classes/data attributes for styling and interactivity (e.g., hover tooltips).

4. Client-Side Execution

The client-side process:

1. Determine Available Width: Get the container’s width (e.g., container.offsetWidth).
2. Measure and Compute Layout:

   const measurer = new CanvasMeasurer();
   const layoutEngine = new LayoutEngine(measurer, config);
   const layout = layoutEngine.computeLayout(song, container.offsetWidth);

3. Render:

   const renderer = new HtmlRenderer();
   renderer.render(layout, container);

5. Integration with StencilJS (Optional)

Encapsulate the rendering logic in a StencilJS web component for reusability:

import { Component, Prop, h } from "@stencil/core";

@Component({
  tag: "chord-sheet",
  styleUrl: "chord-sheet.css",
  shadow: true,
})
export class ChordSheet {
  @Prop() song: Song;
  @Prop() config: Configuration;

  private container: HTMLElement;

  componentDidLoad() {
    const measurer = new CanvasMeasurer();
    const layoutEngine = new LayoutEngine(measurer, this.config);
    const layout = layoutEngine.computeLayout(this.song, this.container.offsetWidth);
    const renderer = new HtmlRenderer();
    renderer.render(layout, this.container);
  }

  render() {
    return <div ref={(el) => (this.container = el)} />;
  }
}

• Benefits: Structured, reusable components with encapsulated logic, ideal for open-sourcing.

6. Performance Optimizations

• Caching: Cache measurements for repeated text/font combinations.
• Web Worker: Offload LayoutEngine computation to a web worker to keep the UI responsive:

  const worker = new Worker("layout-worker.js");
  worker.postMessage({ song, config, width: container.offsetWidth });
  worker.onmessage = (e) => renderer.render(e.data.layout, container);

• Results: Your demo showed 7ms on a fast machine and 15ms on an iPhone 15, suggesting viability even on mobile with optimization.

7. Backward Compatibility

• PDF Rendering: The existing PdfFormatter can use JsPdfMeasurer and LayoutEngine server-side, requiring minimal changes (e.g., replace inline measuring with calls to LayoutEngine).
• Coexistence: HTML and PDF rendering share the same layout logic, differing only in measurer and renderer.

8. Testing and Validation

• Test measurement accuracy across browsers (Chrome, Firefox, Safari) and devices.
• Compare HTML output visually and structurally with PDF output to ensure consistency.

---

Addressing Specific Requirements

• Custom Line Breaking: Achieved by precomputing breaks in LayoutEngine using client-side measurements.
• Section Grouping: Handled within LayoutEngine by processing song paragraphs and lines as in PdfFormatter.
• Interactivity: Enabled by explicit DOM creation, allowing hover events or tooltips on chords.

---

Risks and Mitigations

• Performance: Measuring large songs could slow rendering, but canvas measuring and web workers mitigate this. Your 7-15ms benchmarks suggest it’s manageable.
• Browser Variability: Canvas measurements are consistent, but font rendering may vary slightly; test across browsers and use fallback fonts.
• Complexity: Abstraction adds code complexity, but clear interfaces and documentation (e.g., usage examples) ease adoption.

---

Implementation Steps

1. Define Measurer Interface and Implementations:
   • JsPdfMeasurer for PDF.
   • CanvasMeasurer for HTML.
2. Create LayoutEngine:
   • Extract and adapt measureAndComputeLineLayouts and related methods from PdfFormatter.
3. Develop HtmlRenderer:
   • Build DOM elements based on the layout.
4. Integrate Client-Side:
   • Measure container width, compute layout, render DOM.
5. Optimize and Test:
   • Add caching, web worker support, and cross-browser testing.
6. Optional StencilJS Component:
   • Encapsulate for reusability.

---

Conclusion

This solution leverages your demo’s insights, abstracting the PdfFormatter’s strengths into a flexible system for both PDF and HTML. By measuring text client-side with canvas, computing the layout precisely, and rendering explicit DOM elements, you’ll achieve PDF-like accuracy in HTML, plus interactivity. Start with the Measurer and LayoutEngine, then build out the renderer—your chord sheets will soon shine in browsers as they do in PDFs!