tagQuery(): Rename$root() to $allTags(), $selected() to $selectedTags(); Print $selectedTags() like a list()

[schloerke]

• @wch, should we adjust the print method of tagList() to display [[i]] like a regular list?
  • If so, we can remove visibleTagList()

tagQuery(div(span(), a()))$root()
#> <div>
#>   <span></span>
#>   <a></a>
#> </div>

tagQuery(div(span(), a()))$selected()
#> [[1]]
#> <div>
#>   <span></span>
#>   <a></a>
#> </div>

# has extra `visible` class
tagQuery(div(span(), a()))$selected() %>% str()
#> List of 1
#>  $ :List of 3
#>   ..$ attribs : Named list()
#>   ..$ name    : chr "div"
#>   ..$ children:List of 2
#>   .. ..$ :List of 3
#>   .. .. ..$ attribs : Named list()
#>   .. .. ..$ name    : chr "span"
#>   .. .. ..$ children: list()
#>   .. .. ..- attr(*, "class")= chr "shiny.tag"
#>   .. ..$ :List of 3
#>   .. .. ..$ attribs : Named list()
#>   .. .. ..$ name    : chr "a"
#>   .. .. ..$ children: list()
#>   .. .. ..- attr(*, "class")= chr "shiny.tag"
#>   ..- attr(*, "class")= chr "shiny.tag"
#>  - attr(*, "class")= chr [1:3] "htmltools.tag.list.visible" "shiny.tag.list" "list"

tagQuery(div(span(), a()))$root() %>% format() %>% cat()
#> <div>
#>   <span></span>
#>   <a></a>
#> </div>

[wch]

Why do we want to always return a tagList? I do see that there's an advantage in that the return type is more stable, but on the other hand, in most cases, the input is a single tag object at the top level, and the user would expect the returned object to also be a tag (instead of tagList).

[schloerke]

Thought process was "anything in gives a tagList out. Then the same tagList in gives a tagList out." After one cycle, the input and output objects are stable.

I'm ok putting it back to the flexible return type knowing that it is not stable as I would believe that few people will call tagList(myTag)$append(otherTag)$root() and not be shocked by the return type changing.

[wch]

I think that it's OK to return a variable type. If anything, I think always returning a tagList will cause more confusion, because in most cases, that would mean that what comes out is different from what goes in. If we really wanted, we could add a parameter to $root() which tells it to always return a tagList, and have it default to FALSE.

Also, as I was looking at this PR and rstudio/shiny#3372, I think that name $root() is a bit confusing. It sort of suggests you're just getting the root node, but you're really getting the whole tree. Not sure of a better alternative at this moment, though.

[schloerke]

@wch

I think that name $root() is a bit confusing

• $dom()?
• $topLevelTags()?
• $asTags()?

$html() is too related to .html() which has the description of ...

Get the HTML contents of the first element in the set of matched elements.

... so my gut reaction is not comfortable using $html() due to the differences in implementation.

[wch]

Some possible names:

• allTags()
• asTags(). This might be a little confusing because users may expect it to just return the selected items. Maybe $selected() should also then be renamed to $asTagsSelected() or $selectedAsTags()? That one doesn't need a short, concise name because it will not be commonly used, I think.

[schloerke]

How about $allTags() and $selectedTags()?

[wch]

$allTags() and $selectedTags() works for me. @cpsievert?

We should also have a version bump because of the new names.

[cpsievert]

LGTM 👍