Template/part proposals - Naming for DOM Parts API

[yuzhe-han]

In our virtual F2F breakout discussion for DOM Parts API, naming for the new APIs, Part, could cause confusion with CSS Shadow Parts.

Current Proposal: DOM Parts

interface Part {...};
interface NodePart : Part {...};
interface AttributePart : NodePart {...};
interface ChildNodePart : NodePart {...};
interface PropertyPart : NodePart {...};
interface CustomPart : NodePart{...};
interface PartGroup {...};

Naming alternatives to the Parts API :

1. Location can be an alternative to Part since they point to locations in the DOM where mutation can happen.
   The API becomes:

interface Location {...};
interface NodeLocation : Location {...};
interface AttributeLocation : NodeLocation {...};
...

2. Another common term used to indicate a placeholder for future data is binding.
   Frameworks like Angular and Vue uses binding to mark a place in an element where application data is inserted.

interface Binding {...};
interface NodeBinding : Binding {...};
interface AttributeBinding : NodeBinding {...};
...

What do you guys think?

@EisenbergEffect @caridy @JanMiksovsky @rniwa @hober @justinfagnani @mfreed7

[domenic]

Drive by: Attribute -> Attr would be nice for consistency and conciseness :)

[annevk]

Location already exists (see HTML). Binding doesn't have a lot of precedent other than IDL, but seems a bit confusing to me personally.

Did you consider "marker" or "insertion point" or some such?

[rniwa]

Location already exists (see HTML). Binding doesn't have a lot of precedent other than IDL, but seems a bit confusing to me personally.

Did you consider "marker" or "insertion point" or some such?

point might be a good terminology to use here given we already have boundary points for Range.

Maybe mutation points or manipulation points? Perhaps replacement points?

[annevk]

I like mutation points. Ties it right back to mutation observers and the mutation algorithms in general.

[EisenbergEffect]

Perhaps something like AttrMutator, ChildNodeMutator, PropertyMutator. Maybe LifecycleMutator for the custom callback scenario?

[justinfagnani]

Reference is name that somewhat naturally falls out of what the object is. I often talk about Parts as being cloneable references into the DOM.

[kenchris]

Maybe keep it short like WeakRef.: DOMRef

[annevk]

NodeRef, but yes, that is kinda nice too.

[yuzhe-han]

I like the concept of Reference too. The shortened version, NodeRef, AttrRef, PropertyRef sounds appealing.

[keithamus]

Has this reached consensus? So the new names will be:

interface Ref {...};
interface NodeRef : Ref {...};
interface AttributeRef : NodeRef {...};
interface ChildNodeRef : NodeRef {...};
interface PropertyRef : NodeRef {...};
interface CustomRef : NodeRef {...};
interface RefGroup {...};

Should a PR be raised to alter the proposed spec to reflect this?

[rniwa]

I don't think we've reached any consensus yet. I'm not certain that Ref is a good suffix here. We're not really referencing a node per se. It's really a reference to a specific location of DOM tree.

[bathos]

Re: "binding," mentioned in the initial post: doesn't this typically refer to associating referenceable names with things, not anonymous representations? (e.g. "the name foo is bound in this scope") I can see how the concept might be generalized to "placeholder", but I think the name-association association is pretty strong for that word?

Of those mentioned so far, "mutation point" seems strongest to me. I'd throw position out there as a candidate too, e.g. as DOMPosition. The advantage of "position" over "point" from my POV is that "point" might be too suggestive of absolute pixel coordinates as opposed to junctures in a DOM tree.

[annevk]

To be clear, we don't want to use the prefix DOM for new APIs. It's a legacy thing as DOM in practice means too many different things. Node can work (it's also called a node tree in the DOM Standard).

Building on points as @rniwa suggested in #902 (comment) still seems reasonable to me.

[rniwa]

Of those mentioned so far, "mutation point" seems strongest to me. I'd throw position out there as a candidate too, e.g. as DOMPosition. The advantage of "position" over "point" from my POV is that "point" might be too suggestive of absolute pixel coordinates as opposed to junctures in a DOM tree.

mutation position seems okay and it's probably less confusing than point, which has much greater association with graphics like a point on a line, a plane, or in a 3D space. But Range uses the term point to refer to its end points via compareBoundaryPoints, comparePoint, isPointInRange, etc... so there is that too.

[keithamus]

So do we have consensus for the following?

interface MutationPosition {...};
interface NodeMutationPosition : MutationPosition {...};
interface AttributeMutationPosition : NodeMutationPosition {...};
interface ChildNodeMutationPosition : NodeMutationPosition {...};
interface PropertyMutationPosition : NodeMutationPosition {...};
interface CustomMutationPosition : NodeMutationPosition {...};
interface MutationPositionGroup {...};

[dy]

Field is conventional name used in printf, by @developit in htm as template literal part and in other places.

interface Field {...};
interface NodeField : Field {...};
interface AttributeField : Field {...};
interface ChildNodeField : NodeField {...};
interface PropertyField : Field {...};
interface CustomField : Field {...};
interface FieldGroup {...};

Alternatives:

• Variable (Django calls {{ }} variables),
• Partial
• Param (as in github/template-parts)

interface Param {...};
interface NodeParam : Param {...};
interface AttributeParam : Param {...};
interface ChildNodeParam : NodeParam {...};
interface PropertyParam : Param {...};
interface CustomParam : Param {...};
interface Params {...};

[VicGUTT]

Not sure if what we're going for here is what makes since relative the DOM/API/Other spec or the end user.
Or if we're going for a term accurately and non-biasedly describing the action being performed.

As an end user, personally, I'd expect words like "placeholder", "variable", "param", "prop".
For the DOM, I guess terms like "mutation", "position", "point" etc...
For an accurate definition, I'd go with: interpolation.

As mentioned above {{ }} can be referenced as variables in other environnements (Django, Laravel's Blade, VueJS).

In VueJS particularly, based on context and the action being performed, {{ someVariableNameHere }} can be referenced as "variable", "binding", interpolation.

• someVariableNameHere the variable
• {{ }} interpolating
• {{ someVariableNameHere }} data binding

In Laravel's Blade, {{ someVariableNameHere }} is the act of "echoing" out the variable named someVariableNameHere.

---

In order, I'd personally vote for : "interpolation", "placeholder", "binding".
In second place (no particular order) : "variable", "param", "prop".

---

interpolation

noun

1. The act of interpolating; the insertion of new words or expressions in a book or manuscript; especially, the falsification of a text by spurious or unauthorized insertions.
2. That which is interpolated; new or (especially) spurious matter inserted; an unannounced or unauthorized insertion in a text.
3. In mathematics, the process of finding, from the given values of a function for certain values of the variable, its approximate value for an intermediate value of the variable.

• https://duckduckgo.com/?q=Interpolation+def
• https://www.merriam-webster.com/dictionary/interpolation

[annevk]

@VicGUTT you (and others in this thread) might be interested in https://w3ctag.github.io/design-principles/#naming-is-hard.

[VicGUTT]

Nice ressource and guidelines !
It was an interesting and informative read, thank you !

[VicGUTT]

I believe my suggestions above ("interpolation", "placeholder", "binding") do not infringe the guideline.

• Use common words (at the very least common enough, definitely common in my sphere of the web)
• Use ASCII names (check)
• Consult others on naming (this is what's happening)
• Use future-proof names (yes, otherwise proven / open for debate)
• Name things consistently (check)
• Warn about dangerous features (not applicable)

Albeit interpolation should be disqualified as it mostly describe the action being undertaken rather than the elements being acted upon. Plus reading through my answer, I believe I got side tracked a bit as this would make no sens:

// ...
interface NodeInterpolation : Interpolation {...};
interface AttributeInterpolation : Interpolation {...};
// ...

So, "placeholder" and "binding" are left :)

// ...
interface NodePlaceholder : Placeholder {...};
interface AttributePlaceholder : Placeholder {...};
// ...

// ...
interface NodeBinding : Binding {...};
interface AttributeBinding : Binding {...};
// ...

[bathos]

@VicGUTT, to me “placeholder” suggests something that appears (conceptually or presentationally) in place of something else which is absent, pending, or inapplicable.

I don’t know for sure if most other folks also expect the word to refer to this, but existing APIs seem to: as used in OffscreenCanvas (placeholder canvases), HTML form elements (placeholder content attributes), and CSS pseudos corresponding to the last (:placeholder-shown, ::placeholder), the “placeholder” is something that “holds the place” of something else which is absent by appearing where it would have been. It is not itself the place that it holds (holds in the sense of “occupies”).

[VicGUTT]

@bathos I agree with your point, although I had to "twist my brain" to get the semantical differences. But still, I believe "placeholder" to at least be the closest concept so far.

Seeing NodePlaceholder would, personally, allow me to immediately grasp that something somewhere would need to be substituted by something else at some point or never.
Whereas other suggested options here leave me with open questions (position, point : as in "Node" what now...?) or confusion with other concepts (part : as in "oh this is related to CSS Shadow Parts, or, is it?").

Doing a quick reading throught the proposal again does present "placeholder" as not being too far-fetched:

[...] a native mechanism to instantiate it [-> template element] with some parts of it substituted, conditionally included, or repeated based on JavaScript values

Here I read: something that can be replaced by something else

[...] the essence of the previous proposal: NodeTemplatePart and AttributeTemplatePart which provide mechanisms to insert or replace content at a specific location in a DOM tree.

Here I read: something that can be replaced somewhere

We introduce the concept of a DOM part, which represents an unit of mutable state in a DOM tree.

Here I read: "a unit" of something that can change

That said

Going throught the Ember.js and Angular examples provided in the proposal, a couple similarly defining terms have come up, namely: reference (suggested above) or marked up xxx (I guess we'd use marker here).

Other common and related terms:

• interpolation | NodeInterpolation
• expression | NodeExpression
• binding | NodeBinding
• statement | NodeStatement

Other common terms in the same realm:

• directive | NodeDirective
• component | NodeComponent

Finally

In my opinion, if we're going for something that represents the concept of:

• "a thing that is to be substituted in a specific location" then: Mutable / MutationLocation / MutationPosition (ex.: NodeMutable, NodeMutationLocation)
• "a thing that is referencing the location of something else" then: Reference / Marker / LocationReference / PositionReference (ex.: NodeReference, NodeLocationReference, NodeMarker, NodeLocationMarker)
• "a place holder place holding something that is able to be place holded" then: Placeholder / Placeholdable (ex.: NodePlaceholder, NodePlaceholdable)

Otherwise, I'd fall into using common terminology found in userland implementations.

[bathos]

But still, I believe "placeholder" to at least be the closest concept so far.

I’m unattached to any of what’s been suggested so far and agree none of em are perfect, but I’m afraid I would say this is by far the furthest from describing what it is. Where the others are too general to communicate what it means immediately, this communicates that it’s something else entirely.

[sashafirsov]

Could someone elaborate on the need to separate AttributePart and ChildNodePart?
From API interface and implementation I could not come up with any difference. Like none.
If that is true, why we need separate interfaces?

From "evolutionary architecture/design" prospective at this stage better to keep minimal/common interface and only when it appears to be needed, extend. No need so far? Drop it.

Also if/when ATTRIBUTE node would become declaratively available, the PART would be candidate for declarative definition as well. It would be same as within SPAN as within ATTRIBUTE.

[keithamus]

Could someone elaborate on the need to separate AttributePart and ChildNodePart?
From API interface and implementation I could not come up with any difference. Like none.
If that is true, why we need separate interfaces?

They need to be separate interfaces as they perform different operations on a node. ChildNodePart is a stand in for a child node, and so the value could be another Node such as an element, otherwise it'd be coerced to text and added as a TextNode. If you were to build this yourself ChildNode's commit() would likely use .append() or similar.

AttributePart would represent an AttributeNode's value, and as such should always be a string. If you were to build this yourself it would likely use .setAttribute() or similar.

[luwes]

don't want to poke the bear here but it seemed initially strange that a location, point, or position could have multiple child nodes associated with it. it feels very singular without much contents but yea I guess this is highly subjective.

Part sounded good to me because it had this meaning of substance.

From the new ones in this thread Field and Interpolation feel most natural to me.

Maybe something more in the lines of Range and Fragment. Just throwing out some ideas:

edited (removed slices, frames, clusters, sets)

favorite but naming colliding with CSS parts

DOM parts

interface ChildPart;
interface ChildNodePart;
interface AttrPart;

alternatives

DOM partials

interface ChildPartial;
interface ChildNodePartial;
interface AttrPartial;

DOM fields

interface ChildField;
interface ChildNodeField;
interface AttrField;

random ideas

DOM segments

interface ChildSegment;
interface AttrSegment;

DOM blocks

interface ChildBlock;
interface AttrBlock;

[justinfagnani]

@luwes I named it ChildPart in lit-html 2.0 (updated from NodePart in lit-html 1.0) mainly because it's a Part in child position. I suppose it also could have been ChildrenPart. This proposal and lit-html have influenced each other, so the names are similar...

I don't think any name is going to be perfect here. I suspect the names that are generic enough to apply to to attributes, children, properties, etc; specific enough to refer to a place but not a specific Node; and short enough to be nice and convenient; will end up being very general and likely collide with other concepts: "part", "range", "point" and so on.

If we did have to live with some potential collision with other concepts, I think "part" still has a lot going for it on other aspects.

[bathos]

I suppose it also could have been ChildrenPart.

I guess the question there is whether the qualifying word describes the part’s own position or the nature of its possible content. If it’s the latter, ChildrenPart (or FragmentPart?) might be clearer, but if it’s the former, ChildPart is, I think: it is the only “part” whose position is that of “a child node”. AttrPart (as opposed to, say, AttrValuePart) seems to be named consistently with ChildPart in Lit’s API and I think this is sensible.

Re random ideas: -1 for “frame” because it’s the userland/public API term for (something like) “browsing context” in many APIs (HTMLIFrameElement, client.frameType, window.frames, etc) but 👀 for “block” which, afaik, is “unused” [edit: found “CSSLayerBlockRule” but still, looks like low risk of ambiguity].

[luwes]

@bathos yes, I agree with frame. it's not a good fit, also reading it again now it sounds weirder.

if there is a need to diverge from part, I'm really liking partial actually. it's obviously very close to part but enough to make a distinction of CSS parts vs DOM partials.

it does have a collision with the string templates concept of partials in Mustache, Handlebars etc. but not sure that is all bad.
it already explains what it does in some sense.

[justinfagnani]

It occurred to me that we have another term that we used in lit-html around this concept: "marker". I'm not sure if that conveys the active nature of the API we're talking about. Would it make sense for a marker to have a value or to be updated (even though it stays int he same place)? In lit-html a marker is just what we use in the DOM to mark the location of a part.

[EisenbergEffect]

FAST uses "marker" terminology as well. We also use the term "placeholder". Other terms we use that are related include "behavior" and "directive".

In FAST parlance:

• Directives have the responsibility for creating markers and their associated behavior factories.
• The template pre-processor inserts markers/placeholders into html and associates each with a behavior factory instance.
• The template compiler converts placeholders into dom "paths" and removes placeholders. The paths are associated with the original behavior factory indicated by the placeholder. (A path might be something like r.2.4.3, which means "go to the root, then the 2nd child index of that, then the 4th child index of that, then the 3rd child index of that.)
• When a template is instantiated, the factories instantiate behaviors. Each behavior uses its associated path to find the DOM node that it needs to act upon. Then depending on the type of behavior it is, it will apply different effects. Examples include data binding, repeat rendering, conditional rendering, nested template composition, etc.

[keithamus]

WCCG had their spring F2F in which this was discussed. Present members of WCCG identified an action item to take the topic of DOM Parts and break it out into extended discussions. You can read the full notes of the discussion (#978 (comment)) in which this was discussed, heading entitled "DOM Parts API".

As this issue pertains to DOM parts, I'd like to call out that #999 has been raised for extended discussions and this topic may be discussed during those sessions.