zena:web-elements

The base class of an element the host defines from this module.

The lifecycle methods have empty defaults; a subclass overrides the ones it needs. render is called by the host after requestUpdate, once per microtask however many times it was asked.

A stylesheet for an element's styles: the text the host puts in one constructible stylesheet per definition. Only css results and numbers interpolate, as in Lit; unsafeCSS admits text the author vouches for.

One declared property: its name, its attribute, and its accessors over boxed values. The accessors are generic over the field's type where registerProperty makes them, and box so the protocol's typed getter and setter exports can test the box for the kind.

A registered element: what defineElement records and the host reads.

A template and the values for its holes.

strings is the tagged template's TemplateStringsArray, which the compiler makes once per call site; that identity is what tells the host it has seen the template before.

A JavaScript value the module holds without looking inside it, so it can sit in a template: a DOM node for .node=${…}, a Date for a child's property. The host hands the value back unchanged.

The event a listener receives: the host's event object, with the capability functions as methods, which are all a module can do with an event unless the host grants more.

An extension class rather than a wrapper, so a listener's event costs no allocation and a method's import is linked only when something calls it: a module whose listeners never read their events imports none of these.

A property of the element: declared to the host, reflected from its attribute (the lowercased field name), and re-rendering on write.

The #declared initializer runs once per instance; it registers the field with the definition being probed by defineElement and does nothing for every later instance. Registering from an initializer is what field decorators can do today; a per-class registration, run once at module start, is the form this will take once decorators have static members.

Internal reactive state: re-renders on write, like @property, and is declared to the host as a property without an attribute, which is what Lit's @state is.

The protocol's property kinds; the values are its value kinds.

What a hole may hold. A number or boolean arrives boxed: the union accepts the box, which is what tells the checker to wrap a primitive interpolation in one. null renders nothing, and an iterable renders each of its items in turn.

An event listener, for an @event=${…} hole.

The css tag: a stylesheet, with css results and numbers interpolated.

A stylesheet from text the author vouches for, as Lit's unsafeCSS.

Declares a property of the element class being probed: its name, its accessors over the host, and whether an attribute reflects into it. Called by @property and @state through the decorator's context. Returns 0, so it can initialize a field.

Registers an element definition. The host defines a custom element named tag whose instances create makes, with the properties its @property and @state fields declare.

create is a closure because a class is not a value in Zena today: there is no constructor reference to pass, so the factory is written out. The design document lists a constructor reference among the language changes this library would use.

One instance is constructed here and kept: constructing it is what runs the decorators' registrations, and its values decide each property's kind.

Registers an element definition with no tag name. The host builds the custom element class from it and leaves naming and registration to the page (elementDefinitions in @zena-lang/wasm-web-ui/elements), which is how one module serves pages that disagree about tag names.

The definition registered under tag, or null.

A new instance of definition, bound to it.

A property's kind, decided from its definition's probe instance once.

The definition's styles, from its probe instance; null for none.

The boxed value of property on element, as the field's box.

Sets a text property from text; nothing for a property of another kind.

Sets a host-value property from the host's reference.

Sets a number or boolean property from a number; nothing for another kind.

An observed attribute was set. The attribute's text is converted by the property's kind, as Lit's default converters do: a number is parsed, a boolean attribute is true when present, text is taken as it is. A host-value property takes nothing from an attribute.

An observed attribute was removed: a boolean goes false, text goes empty.

The property whose attribute is name, or null.

The definition's stylesheet text, or null for none.

The constructor: a new instance of the definition.

The property's observed attribute was set; value is the attribute's text.

Renders definition as an element: the tag with attributes, a declarative shadow root with the styles and the template, and the end tag. The attributes are applied to a fresh instance before it renders, as the host applies them on the page, so the markup matches what the page's instance will render from the same attributes. tag names a definition declared without one, or renames a tagged one, as the page does when it registers the class itself.

Renders a template result with hydration markers.

Lit's digest of a template's strings, which hydration compares against the digest of the template it is given: two 32-bit DJB hashes over each string's UTF-16 code units, alternating per unit, as 8 bytes in base64.

An HTML template.

An SVG template, for use inside an <svg> element.

A MathML template, for use inside a <math> element.

Every definition the module registered, in registration order.

The value that renders nothing.