Introduce TagConsumer downcast extension point for DOM interop

[yoxjames]

I am working on an implementation of the SVG 1.1 protocol. One thing I would really like to be able to do is seamless inter-operation with kotlinx-html. However I ran into an issue. For most targets, where the HTML being generated is really just text, this can be accomplished by simply using the unsafe raw text API:

val html = buildString {
            appendHTML(prettyPrint = true).html {
                body {
                    div {
                        unsafe {
                            raw(svgString { // My DSL Begins
                                svg {
                                  // Can use all the SVG elements you want in here
                                }
                            })
                        }
                    }
                }
            }
        }

I could easily refactor this into an extension function that simply taps into the raw call. In fact, there are quite a few examples of libraries that have done this. However on targets like JS or WasmJS, kotlinx-html actually generates DOM elements. If I attempt to tap into the raw(...) calls I'll just be adding text to DOM elements and not adding DOM elements!

I want the ability for one DSL to seamlessly interoperate with kotlinx-html on those targets! Obviously this was created due to a need for a library I am developing, but this should be generic enough to be used any library that would like to interop this way.

Right now, if I want to create an extension function it look something like this:

fun <T> TagConsumer<HTMLElement>.svg4k(
    block: context(dev.jamesyox.svg4k.TagConsumer<SVGElement>, RootContainer) () -> T
): T {
    val tagConsumer = JsDomTagConsumer(document)
    val output = block(tagConsumer, RootContainer)
    val svgDom = tagConsumer.output()
    val hackDiv = div { }
    val currentNode = hackDiv.parentNode
    currentNode?.removeChild(hackDiv)

    currentNode?.let {
        svgDom.forEach { child -> it.appendChild(child) }
    }
    return output
}

Essentially I create a div so that I can get what that method returns as I have no way to grab the HTML element inside of the DSL. I brought this up on slack as well:
https://kotlinlang.slack.com/archives/CKWA2MV8U/p1771194798125389

This solution "works" but I'll be honest that it has some aspects I don't love, I'll get into those with comments.

[yoxjames]

Realistically this is only available on the JSDOMBuilder (js and wasmjs). I guess it's not a terrible idea to have the interface though.

[yoxjames]

This sort of assumes that all use cases of this would be appending to the DOM. That might be fine but part of me wondered if instead of a method like this, the DOM tag consumers should just expose path.last() somehow letting users modify the current last DOM leaf however they want?

[yoxjames]

This I really don't like all that much. We have no way to offer this method since all the DSL methods dangle off HTMLTag which contains a TagConsumer<*>. Unless there wasa whole distinct set of Tags for JS which contained a more specific type of consumer. However that would be a lot more bloat. This method is only available on js and wasmJs which limits the blast radius.

[yoxjames]

This is a standin for what a sister library could do.

[bjhham]

I am thinking maybe the best way to go here would be to introduce a val out: Any? = null here where this points to path.last() in JSDOMBuilder and the generic appendable in the streaming one (and delegates in the delegating ones). This should give us something to easily hook into for HTMLElement functions using as? / is operators.

I think you could introduce this here with an opt-in annotation, since we can probably come up with something better in a later release when significant breaking changes are on the table.

[yoxjames]

I agree. I actually was planning to refactor into something like that. It probably makes more sense to keep some of this awkward implementation in consumers for now.

I assume this library will be significantly refactored for context params. Might be better to consider options then.

[yoxjames]

Done. I think it's a lot less problematic this way.

[yoxjames]

Noticed that the JVM dom consumer could also use this. I never even knew this existed before. Interesting!

[bjhham]

Yeah, this approach looks good to me 👍

[bjhham]

We can use HtmlElement return type here and replace references to path.last() to tidy things here.

[yoxjames]

I figured preventing a throw was ideal, though since this is an experimental opt in I am not against it. Realistically I would be hanging this off of a Tag function when I use it which means it shouldn't ever throw. I will follow the standards you deem ideal for this library though! Just wanted to explain my thought process.

[yoxjames]

It has been updated to use last().

[bjhham]

lgtm 👍