Support 'allowElements' to allow custom tag names.

[isoos]

To enable supporting dartdoc's callout-box: dart-lang/pub-dev#9488

[sigurdm]

Should we also allow a custom set of attributes now we are making things non-fixed?

[sigurdm]

de morgan's?

Suggested change

	if (!_allowedElements.contains(tagName) &&
	!(allowElements?.call(tagName) ?? false)) {
	if (!(_allowedElements.contains(tagName) ||
	(allowElements?.call(tagName) ?? false))) {

[sigurdm]

This needs more explanation.

Are the elements allowed by this function allowed on top of the basic allowlist or exclusively these?

[jonasfj]

Should we also allow a custom set of attributes now we are making things non-fixed?

Yes, if we are going down this route, then maybe the better choice is to accept a Policy object.

If you look at the code:
https://github.com/isoos/dart-neats/blob/e7ffc01a919ff2583ce9f3c35f4e2c2753f738a5/sanitize_html/lib/src/sane_html_validator.dart

We could make a policy object that is something like:

/// Rules for sanitizing HTML in a high-performance SAX-style pass.
///
/// A [SanitizerRules] implementation is stateful and must be used for a
/// single sanitization pass. This allows the implementation to track
/// element nesting and attribute state to make complex decisions.
///
/// The parser using these rules should prioritize yielding original
/// substrings from the input HTML whenever actions return 'Keep'.
abstract base class SanitizerRules {
  /// Called when an element start tag `<tagName` is encountered.
  ///
  /// If this returns [RemoveElementAction], the tag and all its 
  /// children are stripped from the output.
  /// 
  /// If this returns [UnwrapElementAction], the tag itself is stripped, 
  /// but its children are processed and retained.
  ElementAction beginOpenElement(String tagName);

  /// Called for each `name="value"` pair on a kept element.
  ///
  /// [value] is the decoded HTML entity value.
  AttributeAction attribute(String tagName, String name, String value);

  /// Called when the open tag is finished `>`.
  ///
  /// Return an [Iterable] of `(name, value)` pairs to inject additional
  /// attributes into the tag.
  ///
  /// [isVoid] is true if the element is a void element (e.g. <img>, <br>).
  /// [isSelfClosing] is true if the tag used the self-closing syntax `<tag/>`.
  Iterable<(String name, String value)>? endOpenElement(
    String tagName, {
    required bool isVoid,
    required bool isSelfClosing,
  });

  /// Called when an element's closing tag is encountered `</tagName>`.
  ///
  /// For void elements, the parser must call this immediately after
  /// [endOpenElement] to maintain stack consistency for the rules.
  void closeElement(
    String tagName, {
    required bool isVoid,
    required bool isSelfClosing,
  });

  /// Called for text content between tags.
  TextAction text(String text);

  /// Called for HTML comments `<!-- content -->`.
  ///
  /// Return [KeepTextAction] to keep the comment (as-is), 
  /// [RemoveTextAction] to strip it, or [RewriteTextAction] to 
  /// replace the content of the comment.
  TextAction comment(String content);

  const SanitizerRules();
}

/// Action to take for text content.
sealed class TextAction {
  const TextAction._();

  /// Keep the text content as-is.
  factory TextAction.keep() => KeepTextAction();

  /// Remove the text content.
  factory TextAction.remove() => RemoveTextAction();

  /// Rewrite the text content to [newValue].
  factory TextAction.rewrite(String newValue) = RewriteTextAction;
}

/// Keep the text content as-is.
final class KeepTextAction extends TextAction {
  static const KeepTextAction _instance = KeepTextAction._();
  const KeepTextAction._() : super._();
  factory KeepTextAction() => _instance;
}

/// Remove the text content.
final class RemoveTextAction extends TextAction {
  static const RemoveTextAction _instance = RemoveTextAction._();
  const RemoveTextAction._() : super._();
  factory RemoveTextAction() => _instance;
}

/// Rewrite the text content.
final class RewriteTextAction extends TextAction {
  final String newValue;
  const RewriteTextAction(this.newValue) : super._();
}

/// Action to take for an HTML element.
sealed class ElementAction {
  const ElementAction._();

  /// Keep the element and its attributes.
  factory ElementAction.keep() => KeepElementAction();

  /// Remove the element and all its children.
  factory ElementAction.remove() => RemoveElementAction();

  /// Remove the tag but keep and sanitize its children.
  factory ElementAction.unwrap() => UnwrapElementAction();

  /// Rename the element to [newTagName].
  ///
  /// The original attributes are preserved and passed to [SanitizerRules.attribute].
  factory ElementAction.rename(String newTagName) = RenameElementAction;

  /// Replace the element and its children with [replacementHtml].
  ///
  /// The [replacementHtml] is inserted as-is and is **NOT sanitized**.
  factory ElementAction.replace(String replacementHtml) = ReplaceElementAction;
}

/// Keep the element and its attributes.
final class KeepElementAction extends ElementAction {
  static const KeepElementAction _instance = KeepElementAction._();
  const KeepElementAction._() : super._();
  factory KeepElementAction() => _instance;
}

/// Remove the element and all its children.
final class RemoveElementAction extends ElementAction {
  static const RemoveElementAction _instance = RemoveElementAction._();
  const RemoveElementAction._() : super._();
  factory RemoveElementAction() => _instance;
}

/// Remove the tag but keep and sanitize its children.
final class UnwrapElementAction extends ElementAction {
  static const UnwrapElementAction _instance = UnwrapElementAction._();
  const UnwrapElementAction._() : super._();
  factory UnwrapElementAction() => _instance;
}

/// Rename the element to [newTagName].
final class RenameElementAction extends ElementAction {
  final String newTagName;
  const RenameElementAction(this.newTagName) : super._();
}

/// Replace the element and its children with [replacementHtml].
final class ReplaceElementAction extends ElementAction {
  final String replacementHtml;
  const ReplaceElementAction(this.replacementHtml) : super._();
}

/// Action to take for an attribute.
sealed class AttributeAction {
  const AttributeAction._();

  /// Keep the attribute as-is.
  factory AttributeAction.keep() => KeepAttributeAction();

  /// Remove the attribute.
  factory AttributeAction.remove() => RemoveAttributeAction();

  /// Rewrite the attribute value to [newValue].
  factory AttributeAction.rewrite(String newValue) = RewriteAttributeAction;
}

/// Keep the attribute as-is.
final class KeepAttributeAction extends AttributeAction {
  static const KeepAttributeAction _instance = KeepAttributeAction._();
  const KeepAttributeAction._() : super._();
  factory KeepAttributeAction() => _instance;
}

/// Remove the attribute.
final class RemoveAttributeAction extends AttributeAction {
  static const RemoveAttributeAction _instance = RemoveAttributeAction._();
  const RemoveAttributeAction._() : super._();
  factory RemoveAttributeAction() => _instance;
}

/// Rewrite the attribute value.
final class RewriteAttributeAction extends AttributeAction {
  final String newValue;
  const RewriteAttributeAction(this.newValue) : super._();
}

I drafted this a while ago, but never had time to finish it. The idea was to power it with SAX style parser, but there is no reason we could use it with package:html and just emulate the SAX parser as we traverse the DOM.

[jonasfj]

Another option would be to just accept a Map like we have here:

final _commonAttributeValidator = {
  for (final a in _alwaysAllowedAttributes)
    a: _alwaysAllowed,
};

final policy =
    <String, Map<String, bool Function(String)>>{
  for (final e in _allowedElements)
    e: _commonAttributeValidator,
  'A': {
    'href': _validLink,
  },
  'IMG': {
    'src': _validUrl,
    'longdesc': _validUrl,
  },
  'SOURCE': {
    'srcset': _validSrcset,
  },
  'DIV': {
    'itemscope': _alwaysAllowed,
    'itemtype': _alwaysAllowed,
  },
  'BLOCKQUOTE': _citeAttributeValidator,
  'DEL': _citeAttributeValidator,
  'INS': _citeAttributeValidator,
  'Q': _citeAttributeValidator,
};

We just can't rewrite attributes, or add rel attributes with this pattern.

[jonasfj]

I don't have string objections, to this.

[isoos]

Note: we should be able to easily allow @youtube marker support that has an output like this:
dart-lang/pub-dev#9490 (comment)