htmltools::tag() and varArgs not documented

[JosiahParry]

I am trying to understand how to create a custom tag for a component library. However the tag() function does not have an example. It is unclear what the structure of varArgs argument should be.

https://github.com/rstudio/htmltools/blob/038ef7be3b02a9248f122b745ad7830cc429d437/R/tags.R#L639-L667

[JosiahParry]

I also noticed that varArgs argument might be out of date or could benefit from better input checking

"List of tag attributes and children."

htmltools::tag("hello-world", list(c("a", "b", "c")))
#> Error in writeImpl(text): Text to be written must be a length-one character vector

[gadenbuie]

Agreed, we could definitely improve both the docs to add an example and the error message.

varArgs should be a list where the primary restriction is that any character items in the list must be scalar. In other words list("a", "b", "c") or list("a b c") will work but list(c("a", "b", "c")) will not. So Text to be written must be a length-one character vector is accurate but not very helpful.

The hard part in making the error message better is that it happens at a much lower level than where varArgs is provided and it's discovered as a part of a recursive walk of the varArgs list.

library(htmltools)

tag("hello-world", list("a", "b", "c"))
#> <hello-world>
#> a
#> b
#> c
#> </hello-world>

tag("hello-world", list(div("a", "b"), span("c")))
#> <hello-world>
#> <div>
#> a
#> b
#> </div>
#> <span>c</span>
#> </hello-world>