feat: add tag open, tag close, and text events

[naktinis]

Summary

Allows hooking into tag tag open, tag close, and text events of the parser to enable more advanced transformations such as inserting a space between two removed block-level tags with preserved text.

Closes #691.

What are the specific steps to test this change?

Added a simple test in the test suite, but you can also test manually by passing the onOpenTag, onCloseTag, and onText listeners in the sanitizer options.

What kind of change does this PR introduce?

(Check at least one)

• Bug fix
• New feature
• Refactor
• Documentation
• Build-related changes
• Other

Make sure the PR fulfills these requirements:

• It includes a) the existing issue ID being resolved, b) a convincing reason for adding this feature, or c) a clear description of the bug it resolves
• The changelog is updated
• Related documentation has been updated
• Related tests have been updated

If adding a new feature without an already open issue, it's best to open a feature request issue first and wait for approval before working on it.

[BoDonkey]

I haven't tried out the code changes, yet, or thought very deeply about the new test. However, can you please add to the CHANGELOG and also add some text to the README so that a user would know how to use the new options you have added? Thanks!

[BlueManCZ]

This would be useful if you were actually using the return values of these functions. Right now, you're just calling them and ignoring the potential results. This has no effect on the result transformation. Am I missing something? Also, it would be nice to add some unit tests with real-world use cases, not just a call counter. (maybe #49 as you mention in the relevant issue #691).

[naktinis]

I would use it to track the parsing state outside of the callbacks.

First of all, here's what would happen if I didn't apply any transformations:

sanitizeHtml(
  '<div>I&#39;m here</div><div>I&#39;m there</div>',
  {
    allowedTags: [],
  },
);
// Returns "I'm hereI'm there"

Here's what happens if I insert a space before each text element:

sanitizeHtml(
  '<div>I&#39;m here</div><div>I&#39;m there</div>',
  {
    allowedTags: [],
    textFilter: (text) => {
      return ' ' + text;
    },
  },
);
// Returns "I ' m here I ' m there"

Finally, a solution using the proposed onOpenTag and onCloseTag:

let addSpace = false;
sanitizeHtml(
  '<div>I&#39;m here</div><div>I&#39;m there</div>',
  {
    allowedTags: [],
    onOpenTag: (tag) => {
      addSpace = true;
    },
    onCloseTag: (tag) => {
      addSpace = true;
    },
    textFilter: (text) => {
      if (addSpace) {
        addSpace = false;
        return ' ' + text;
      }
      return text;
    },
  },
);
// Returns "I'm here I'm there"

So this is the only way I could find to produce this end result correctly (of course, after introducing the new events). I tried hooking into transformTags and exclusiveFilter to detect tag opening and closing, but the current logic prevented it from fully working because they don't really correspond exactly to tag open and tag close events (plus even if it was possible, it still feels like a convoulted and unintuitive way of tracking this state).

Update: just a small clarification why I have onCloseTag there as well - it's because of this scenario:

cleanHtml('<div>I&#39;m here</div><div>I&#39;m there</div>Also here');
// Produces this: "I'm here I'm there Also here" (as expected)