Documentation
¶
Overview ¶
Command widgets turns legacy widget markup into web component markup: a container becomes a custom element, the state it kept in classes and data attributes becomes properties, and the parts it kept in nested divs become slots.
$ widgets -rule 'div.tabs=my-tabs,data-active:active,part=div.tab-title:title' page.html 3 widgets upgraded, 1 skipped my-tabs 2 upgraded my-accordion 1 upgraded, 1 skipped: its end tag was omitted
Renaming is only safe into a container ¶
A rename writes the new name over the start tag and over the end tag, and whoever parses the output applies the new name's content model to what is inside. The library documents what that does to a table or a select. The void direction is worse, because there are four answers and none of them is "the element, with its content". Measured against x/net/html on <div class="w">x</div>:
renamed to output the tree a parser builds br <br class="w">x</br> two br elements, x between them img hr <img class="w">x</img> one element, x its sibling input wbr (the same shape) one element, x its sibling area col <col class="w">x</col> no element at all, only x meta <meta class="w">x</meta> the element in <head>, x in <body>
br is the only end tag HTML treats as a start tag, so the stray </br> becomes a second element: the rename duplicated the widget. A col outside a table is dropped, so the rename deleted it. A meta belongs in the head, so the rename moved it there and left its content behind. Nothing errors in any of the four.
A custom element name always has a hyphen, and a hyphenated name is always an ordinary container, so this program's targets are safe by construction. It refuses a target that is not one anyway - a void name, a raw-text name, or a name with no hyphen - because the mistake is available and silent.
An omitted end tag is a widget this cannot upgrade ¶
A rename writes over the token that closed the element, and where the source omitted the element's own end tag that token belongs to something else: renaming the items of <ul><li>a<li>b<li>c</ul> yields <ul><my-item>a<my-item>b<my-item>c</my-item>, where the </ul> has become an </my-item> and the list never closes. The outermost rename wins, so with distinct names the </ul> becomes </item-1>.
Whether an element has its own end tag is knowable - the end-tag handler reports the tag that closed it, and a name that differs means the source left this one out - but it is knowable too late, because the rename has to happen at the start tag. So this is two passes: the first records which candidates closed themselves, the second renames only those. The rest are counted and reported, which is the honest answer rather than a corrupted list.
Source Files