[declarative-custom-elements] Capabilities needed and open questions

[justinfagnani]

At the Spring 2023 F2F we talked about the need to discover all the open questions and dependencies on other specs that declarative custom elements have, in order to use declarative custom elements to help discover, prioritize other work.

Here are some questions and spec dependencies I can think of:

Questions

• Declaration
  • How are attributes and properties declared?
    • How are attributes reflected to properties? Do attributes have converters for numbers, boolean, enums, etc?
  • How are styles declared?
    • Are they part of the template or can they be shared and adopted?
    • Can they be external? Or bundled and referenced from a nested sheet?
  • Are registrations always global, or can they be scoped?
    • If scoped, does the declaration establish an id that can be used to define the element in a scope?
    • If scoped, do we need a way to define all the child definitions that might be used?
  • How do you set ShadowRootInit options like mode and delegates focus?
• Scripting
  • Do declarative custom elements run with JavaScript disabled?
  • Will HTML Modules be importable from HTML with JavaScript disabled?
  • What is the base class for a declarative custom element? Does it directly extend HTMLElement, or is there another class with shared behavior?
  • Can a declarative custom element be enhanced with script?
    • How is that script associated with the element?
    • Must the script be inline, or can it be bundled?
    • Can the script be loaded late? Is there an upgrade-like step when it does?
• Lifecycle
  • How do elements detect changes to data?
  • When do element re-render? Synchronously or asynchronously?
    • If synchronously, how do you handle data-consistency? ie <img src="/avatars/{{lastName}}/{{firstName}}.jpg"> will make erroneous requests if firstName and lastName are set at the same time.
    • If asynchronous, on what timing? Microtask? Is there an API for waiting for an element to update?
• Templates
  • What are the semantics of template updates?
    • Is static DOM guaranteed to not be updated when re-rendering the same template?
    • Are bindings dirty-checked?
      • If so, do we need an opt-out for binding to stateful properties like input.value?
    • If a new template (ie from a different branch in a conditional) is rendered, does it clear the existing DOM?
  • How are event listeners added in templates?
    • Do event listeners make sense in declarative custom elements? What kinds of things could they do declaratively ? Fire another event? Assign a property?
    • Or does event handling require augmenting declarative definitions with script?
  • How are properties set on elements in templates?
    • How do you set mixedCase property names?
  • How are conditional and looping handled in templates?
    • Is there a keyed looping construct that reorders DOM?
  • Can templates be shared? Is there a sub-template "call" operation and a named template declaration?
  • What is the expression language for bindings? Is it a subset of JS?
    • Does it support literals? Array literals?
    • Does it support optional-chaining and nullish coalescing?
    • Can expressions contain method calls? If not, does the scope for expressions need a wrapper over some of the DOM to turn methods into getters? (ie this.getAttribute('name') -> this.attributes.name)
  • What is the data model available to to expressions?
    • Is the scope something like class scope where you have the globals and this?
  • What happens if expressions throw?
  • Is there a way to remove an attribute that has bindings? ie <img src="/foo/{{bar}}.jpg"> when bar is null
• Security
  • Do declarative custom elements introduce a script gadget vulnerability?
    • Do they only run when script would have run? ie, not from innerHTML?
    • Are they inline script for CSP?
    • Do they support nonces?
  • Is expression evaluation sanitized?
    • Do we denylist things like window.location which can be used to exfiltrate data in bindings?
    • Do we denylist the Function constructor which can be used to eval code?
  • Are bindings in text positions always escaped?
    • If so, is there an unsafe operation for inserting HTML as a string?
  • Can bindings to attributes do contextual autoescaping? (disallow onclick="javascript:...")
• Can ElementInternals properties be set?
  • How do you define ARIA properties?
  • How can an element be a FACE?
  • How can ARIA associations be made across children shadow boundaries?
• SSR
  • How do declarative elements handle an existing shadow root from declarative shadow DOM (hydration)?
  • Do we need a deferred hydration system to ensure top-down initialization?
  • Depending on how template updates work, do we need a system for marking what template SSR'ed a chunk of DOM so that we can perform an update on hydration instead of a replace?

I'm sure there are many more questions than this, of course.

Probable Spec Dependencies

• DOM Parts
• Template Instation
• Expressions
• Declarative ARIA
• Hydration
• Declarative CSS Modules
• ...

Use cases

Many of these questions need to be driven from use cases. We'll need to know what kind of elements we're trying to allow to be built. One of the most import questions there whether interactive elements are in scope. For example, can you build the basic counter element that's a common framework example? That alone requires event listeners and self-updating state.

[bahrus]

This is a nice and thorough list. Is this issue meant to serve only as snapshot in time of open questions, or an (evolving) index of supporting issues/proposals, or is it (also) to serve as a place to discuss possible solutions/pose other questions?

[justinfagnani]

We definitely need to collect more open questions. I'm not claiming this list is complete.

[bahrus]

To the SSR category I would add:

How much (if any) of the SSR/SSG generated element(s) can be optionally used to define the custom element -- can the rendered DOM be used to take a snapshot and turn it into the template? If so, does it make sense to standardize some markers (like processing instructions) indicating things that can be removed/added during that process?

[justinfagnani]

@bahrus I'm not completely following. I think this is covered by the hydration question, no? Is it just more specifics there on how hydration is achieved?

[bahrus]

Maybe.

When I look at some of the proposals for what declarative custom elements might look like:

<definition name="percentage-bar">
    <template shadowmode="closed">
        <div>...</div>
        <style>/*...*/</style>
    </template>
    <script type=module>
        export default class MyEl extends HTMLElement { /*...*/ }
    </script>
</definition>

... it's unclear to me whether that definition is intended to serve dual roles, or a single role. Dual roles would be not only does it define the structure of the custom element, but it would also be rendered directly in the live DOM tree as one instance of the custom element.

A single role would mean that the SSR generated content would automatically become ShadowDOM(ed) (already possible today in Chrome and Safari), but without that separate definition tag added somewhere, it would remain static HTML, and not morph into a web component.

I make that distinction clear (in my mind) here. Examples 1,2, 4, 5, the defining element serves dual roles. Example 3, that uses a template to define the element, doesn't. Example 3 has fewer parts to resolve, as there's no issue with how to construct the template for repeated renderings, for starters.

It's not clear to me whether I'm the only one who thinks serving dual roles is something worth pursuing, or if everyone is assuming that that goes without saying?

[justinfagnani]

Definitions are just that - only definitions. They are not instances. Your example would only create an instance when there's a <percentage-bar> element.

<template shadowrootmode> does not belong inside a definition. Shadow roots are for instances. A definition would have a plain <template> (possibly with a new attribute opting into the expression syntax).

[bahrus]

That's what I thought, looking at that example of the percentage-bar. I guess, then, I'm the only one who thinks it is worth pursuing making the first instance also serve as a definition, as the second link I provide demonstrates.

Does my open question make sense to you now? I think you are saying no, by definition, the definition should not also be an instance. I.e. my open question has been opened and shut :-). I agree taking the stance you are taking simplifies things. Maybe I can reraise the possibility once that's accomplished (baby steps).

[justinfagnani]

I personally think there should be a clear line between definitions and instances.

Making an instance also a definition raises all kinds of issues around expressions, conditionals, and control flow. They might be solvable, but I believe if they are that it could be added later. It could also probably be done in user-land by patching up the element definition based on the first instance's DOM.

[matthewp]

What is the use-case for having a definition also be an instance? This would be quite unexpected to me personally. It also makes rendering complicated. It's easy to add a definition at the top of the body tag. If it were an instance I would need to keep track of how many times a tag has been rendered and then do some special rendering so that the definition is added the first time and then never again.

[bahrus]

There are some web components that may contain quite a bit of HTML, and aren't even guaranteed to appear more than once on the page.

Consider how much html is behind this period table, for example. Expand the pug to generate the full html to see what I mean. Other examples: Calendars, Calculators, Chessboards.

So not supporting this would double the payload, for a single instance, especially if there's no dynamic logic to generate the HTML.

I also think it makes quite a bit of sense when writing to HTML to "define" the HTML markup for something, previewing what you are generating as you type, then give it a name, and reuse it, similar to defining a variable when coding. That's what my POC was meant to convey.

[bahrus]

Another example would be the hamburger menu, which might likely be 1% JavaScript, 10% HTML, 89% CSS. We know we will need one instance for the top menu. We might, later, need to reuse the menuing capabilities it provides by some pieces of the page, lazily loaded. Again, seems like we are doubling the payload to accommodate complex scenarios (lots of dynamic content), at the expense of simple, static-ish scenarios. I'm perfectly fine doing one first, holding off on the other, but I just wanted to provide my use cases (there may be others).

[matthewp]

I don't understand how this doubles the payload. You would define all of the HTML in the <definition> tag and then when you use it it's just <periodic-table></periodic-table>. Having the definition first means you don't need to include the DSD (correct me if I'm wrong here @justinfagnani).

[EisenbergEffect]

That should be correct. A declarative element would have a template with some sort of binding syntax in it so that the instances used afterwards simply render using the template declared as part of the original definition.

[bahrus]

In the context of streaming declarative ShadowDOM (which is the context in which I raised the issue) you would have the definition plus at least one instance rendered to by the server.