node-html-to-text icon indicating copy to clipboard operation
node-html-to-text copied to clipboard

Refactor lists formatting, make custom lists constructible with BlockTextBuilder

Open KillyMXI opened this issue 4 years ago • 0 comments

An idea formed after discussion in #231

Currently table construction is handled with the primitives provided by BlockTextBuilder. Formatter walks through the model of an HTML table and calls the builder to construct the output table.

Contrary, ordered and unordered lists completely handled in the formatter, only block primitives are called.

  • Pros: smaller API of BlockTextBuilder;
  • Cons: no reusable primitives to construct nice custom lists. To achieve the same quality formatting will require to copy the whole list-formatting code.

Solution: add extra functions to BlockTextBuilder that will take some responsibilities of https://github.com/html-to-text/node-html-to-text/blob/79f673106a63f467d1f43772840ecdb0527f91fe/lib/formatter.js#L204 thus reducing the amount of formatter-specific code and increasing the amount of reusable builder code.

API variant 1:

builder.openList(/* { maxPrefixLength: number, prefixAlign: 'left' } */);
builder.openListItem({ prefix: string });
walk(...);
builder.closeListItem();
builder.closeList();
  • Similar to the API for tables;
  • Might not work with lists. Currently, all list item nodes are collected until all prefixes are known and walked only after that. Table cells have different requirements for text width, and rendered text is accumulated instead;
  • A compromise solution might be to leave it to client code to determine the max length of prefixes.

API variant 2:

builder.openList();
builder.addListItem({ prefix: string, elem: ... });
// or
builder.addListItem({ prefix: string, walk: () => walk(...) });
builder.closeList();
  • Can transfer the logic from existing formatter code;
  • Inconsistent with table building.

I'll need to review the table building, including WIP, to see whether it makes sense to change the API for tables. WIP code for tables wasn't going smooth, would be nice to find an improvement on both fronts.


I'm going with variant 1 and leave upfront max prefix length calculation in the formatter. This provides most natural transition...

KillyMXI avatar Oct 05 '21 19:10 KillyMXI