@webjsdev/core 0.7.65 → 0.9.0

package/src/attribute-reader.js

@@ -39,6 +39,20 @@
  * JS under a hand-written overlay, so the shared code moves out instead.
  */
 
+/**
+ * Whether a declared property has an HTML attribute at all. lit's two ways to
+ * say no, both honoured: `state: true` (internal state, which lit normalizes
+ * to `attribute: false`) and `attribute: false` (a public, property-only
+ * input). A property without one is never observed, never read from a source
+ * attribute at SSR, and never reflected; a `.prop` binding still reaches it.
+ *
+ * @param {{ state?: boolean, attribute?: string | false } | null | undefined} decl
+ * @returns {boolean}
+ */
+export function isAttributeBacked(decl) {
+  return !!decl && decl.state !== true && decl.attribute !== false;
+}
+
 /**
  * Read one attribute string into its declared property value.
  *
@@ -59,9 +73,13 @@
  * applied to the JSON and converter branches alone, which left a `String`-typed
  * prop holding the raw source text at SSR while `getAttribute()` on the client
  * returned the decoded one.
+ * @param {string} [propName] the property being read, named in the Boolean warning
  * @returns {unknown}
  */
-export function readAttributeValue(def, value) {
+export function readAttributeValue(def, value, propName) {
+  // Lit's function form: a bare `converter: (value, type) => ...` IS the
+  // `fromAttribute` half, and reflection uses the default serialization.
+  if (typeof def.converter === 'function') return def.converter(value, def.type);
   if (def.converter && def.converter.fromAttribute) {
     // Deliberately UNGUARDED, and deliberately first (#1340). An author who
     // supplies a converter owns the whole read, which is the same rule
@@ -95,7 +113,13 @@ export function readAttributeValue(def, value) {
     return def.converter.fromAttribute(value, def.type);
   }
   if (def.type === Number) return value == null ? null : Number(value);
-  if (def.type === Boolean) return value != null && value !== 'false';
+  if (def.type === Boolean) {
+    // A boolean attribute is on whenever it is PRESENT, as in HTML and Lit,
+    // so `open="false"` is true. Say so once per property, since the literal
+    // reads as off to anyone coming from a JSX prop.
+    if (value === 'false') warnFalseBoolean(def, propName);
+    return value != null;
+  }
   if (def.type === Object || def.type === Array) {
     // An attribute that is not parseable JSON yields `null` rather than the raw
     // string (#1253), because a STRING is never a valid value for a property
@@ -110,7 +134,7 @@ export function readAttributeValue(def, value) {
     // The two readers now see the SAME attribute set, so this fallback is not
     // the only thing they agree on (#1341). Both resolve a name through
     // `resolveAttributeProperty` below, which matches the same names
-    // `observedAttributes` lists (via `observedAttributeNames`) and nothing else, so it skips a `state: true` prop and ignores a name that
+    // `observedAttributes` lists (via `observedAttributeNames`) and nothing else, so it skips a `state: true` or `attribute: false` prop and ignores a name that
     // maps to no attribute-backed property exactly as the observed list does.
     // The SSR caller lowercases its source name first, because the browser
     // lowercases while parsing. And both are handed a value with every
@@ -121,16 +145,54 @@ export function readAttributeValue(def, value) {
   return value;
 }
 
+/** Declarations already warned about a literal "false". @type {WeakSet<object>} */
+const WARNED_FALSE = new WeakSet();
+
+/**
+ * @param {object} def
+ * @param {string | undefined} propName
+ */
+function warnFalseBoolean(def, propName) {
+  if (WARNED_FALSE.has(def)) return;
+  WARNED_FALSE.add(def);
+  const name = propName ? `\`${String(propName)}\`` : 'A Boolean property';
+  console.warn(
+    `[webjs] ${name} received the attribute value "false", which is TRUE: a Boolean property is on whenever its ` +
+      `attribute is present, as in HTML and Lit. To turn it off, leave the attribute out, or bind it with ` +
+      `?attr=\${false} in a template.`,
+  );
+}
+
 /** Kebab-case a property name for its default HTML attribute. @param {string} s */
 function hyphenate(s) {
   return s.replace(/([A-Z])/g, '-$1').toLowerCase();
 }
 
+/**
+ * The attribute a declared property reads and reflects to, Lit's
+ * `attribute` option: a string is used as written, `false` (or
+ * `state: true`) means none, and anything else (absent, or `true`) is Lit's
+ * default name, the LOWERCASED property name (`isOpen` -> `isopen`). The
+ * kebab spelling (`is-open`) stays readable as an alias (see
+ * `attributeBackedProps`) but is never what a property reflects to.
+ *
+ * @param {string} propName
+ * @param {{ attribute?: string | boolean, state?: boolean }} decl  normalised declaration
+ * @returns {string | undefined}
+ */
+export function attributeNameFor(propName, decl) {
+  if (!isAttributeBacked(decl)) return undefined;
+  if (typeof decl.attribute === 'string') return decl.attribute;
+  // A symbol-keyed property has no default attribute name, as in Lit.
+  if (typeof propName !== 'string') return undefined;
+  return propName.toLowerCase();
+}
+
 /**
  * Resolve an attribute NAME to the property it feeds, and to that property's
  * normalised declaration.
  *
- * `state: true` props are skipped, because they are absent from
+ * `state: true` and `attribute: false` props are skipped, because they are absent from
  * `observedAttributes` and so the browser never delivers their attribute to any
  * reader. lit reaches the same outcome the same way, resolving through the very
  * map `observedAttributes` is built from (`reactive-element.ts`
@@ -168,14 +230,20 @@ function hyphenate(s) {
  *   which case the caller must IGNORE the attribute entirely (#1341).
  */
 export function resolveAttributeProperty(Cls, attrName) {
-  // Primary names first, so a prop literally named `foobar` keeps `foobar`
-  // even when a sibling `fooBar` would answer to it as an alias.
+  // Primary names first, then aliases. Two props can share a primary name
+  // (`fooBar` and `foobar` both default to `foobar`); the prop literally
+  // named after the attribute keeps it, so a sibling never steals a real prop.
+  let primaryHit;
   let aliasHit;
   for (const { propName, def, primary, alias } of attributeBackedProps(Cls)) {
-    if (primary === attrName) return { propName, def };
-    if (aliasHit === undefined && alias === attrName) aliasHit = { propName, def };
+    if (primary === attrName) {
+      if (propName === attrName) return { propName, def };
+      if (primaryHit === undefined) primaryHit = { propName, def };
+    } else if (aliasHit === undefined && alias === attrName) {
+      aliasHit = { propName, def };
+    }
   }
-  return aliasHit;
+  return primaryHit ?? aliasHit;
 }
 
 /**
@@ -195,13 +263,128 @@ export function observedAttributeNames(Cls) {
   return [...names];
 }
 
+/**
+ * Every reactive property `Cls` declares, its own over its superclasses', the
+ * way Lit's `finalize` merges `elementProperties` down the chain. A class's own
+ * `static properties` (Lit's spelling, a field or a `static get`) and the map
+ * the `WebComponent({ ... })` factory puts on the base it returns are the same
+ * thing here, so a subclass adding props keeps its parent's, and a factory
+ * class may add a `static properties` block of its own.
+ *
+ * Memoized per class: the accessors (`installAccessors`), the attribute list
+ * (`attributeBackedProps`) and reflection all read this one map, so they
+ * cannot disagree about which props exist. The map is the same OBJECT for as
+ * long as the class's declarations, and its superclasses', are unchanged, so
+ * a memo derived from it is keyed on that identity.
+ *
+ * A memo holds its superclasses' declarations merged in, so `createProperty`
+ * on a parent has to reach every subclass already read, which a WeakMap
+ * cannot enumerate. So each memo records its parent's map and its own class's
+ * version, and stays valid while both are unchanged: a change rebuilds exactly
+ * the changed class and the classes below it. Checking that walks the chain,
+ * so it runs only after some class changed (`epoch` moved); until then a read
+ * is one lookup.
+ *
+ * @param {any} Cls  the component class
+ * @returns {Record<string, any>}
+ */
+export function declaredProperties(Cls) {
+  if (!Cls || typeof Cls !== 'function') return (Cls && Cls.properties) || {};
+  const hit = DECLARED.get(Cls);
+  if (hit && hit.epoch === epoch) return hit.merged;
+  const parent = Object.getPrototypeOf(Cls);
+  const inherited = parent && parent !== Function.prototype ? declaredProperties(parent) : ROOT;
+  const version = VERSION.get(Cls) ?? 0;
+  if (hit && hit.inherited === inherited && hit.version === version) {
+    // Unaffected by whatever changed: keep the same map, valid at this epoch.
+    hit.epoch = epoch;
+    return hit.merged;
+  }
+  const own = Object.hasOwn(Cls, 'properties') ? Cls.properties : undefined;
+  const created = CREATED.get(Cls);
+  let merged = own && typeof own === 'object' ? { ...inherited, ...own } : inherited;
+  if (created) merged = { ...merged, ...created };
+  DECLARED.set(Cls, { epoch, inherited, version, merged });
+  return merged;
+}
+
+/** @type {WeakMap<Function, { epoch: number, inherited: Record<string, any>, version: number, merged: Record<string, any> }>} */
+const DECLARED = new WeakMap();
+
+/** The declarations above every class: none. Shared, so a root-level memo can be compared by identity. */
+const ROOT = Object.freeze({});
+
+/** Per class, how many times its own declarations changed (`createProperty`). @type {WeakMap<Function, number>} */
+const VERSION = new WeakMap();
+
+/** Moves whenever any class's declarations change, so a memo knows to re-check its chain. */
+let epoch = 0;
+
+/**
+ * The current declarations epoch, for a memo outside this module derived from
+ * `declaredProperties` (lifecycle.js's `elementProperties`): while it has not
+ * moved, no class's declarations changed and a memo needs no re-check.
+ * @returns {number}
+ */
+export function declarationsEpoch() {
+  return epoch;
+}
+
+/**
+ * Properties added to a class through Lit's `static createProperty(name,
+ * options)`, per class. Merged LAST in `declaredProperties`, so a created
+ * property wins over a same-named `static properties` entry, as it does in Lit
+ * (`createProperty` writes straight into `elementProperties`).
+ * @type {WeakMap<Function, Record<string, any>>}
+ */
+const CREATED = new WeakMap();
+
+/**
+ * Normalise one declaration: the bare-constructor shorthand (`count: Number`)
+ * becomes `{ type: Number }`, an options object is returned as is.
+ * @param {unknown} decl
+ * @returns {Record<string, any>}
+ */
+export function normalizeDecl(decl) {
+  return typeof decl === 'object' && decl !== null ? /** @type {any} */ (decl) : { type: decl };
+}
+
+/**
+ * Record a property created through `static createProperty()` and drop the
+ * class's memoized declarations so the next read includes it.
+ * @param {Function} Cls
+ * @param {string} name
+ * @param {Record<string, any>} decl
+ */
+export function addCreatedProperty(Cls, name, decl) {
+  let own = CREATED.get(Cls);
+  if (!own) CREATED.set(Cls, (own = {}));
+  own[name] = decl;
+  invalidateClass(Cls);
+}
+
+/**
+ * Drop every memo this module keeps for `Cls`, so its declarations are read
+ * again on next use.
+ * @param {Function} Cls
+ */
+export function invalidateClass(Cls) {
+  // This class's memo is rebuilt, which gives it a new map, and every
+  // subclass's memo then sees a parent map it was not built from. Classes on
+  // other chains re-check once and keep their maps.
+  VERSION.set(Cls, (VERSION.get(Cls) ?? 0) + 1);
+  epoch++;
+}
+
 /**
  * The attribute-backed props of `Cls` with the names each answers to.
  *
  * `primary` is the custom `attribute` option, matched VERBATIM, or else the
- * kebab-cased property name. `alias` is the LOWERCASED property name, lit's
- * default attribute name, present only when the prop has no custom `attribute`
- * and the lowercased name differs from the kebab one. Without it,
+ * LOWERCASED property name, Lit's default attribute name and the one a
+ * reflected property writes. `alias` is the KEBAB-cased property name, kept
+ * as a read-only alias (WebJs's earlier default, and the spelling HTML
+ * authors reach for), present only when the prop has no custom `attribute`
+ * and the kebab name differs from the lowercase one. Without it,
  * `<quiz-player quizId=${id}>` against `{ quizId: Number }` reached neither
  * side: the parser lowercases the name to `quizid`, which matched nothing, so
  * the prop silently stayed undefined on the server AND the client (#1540).
@@ -215,31 +398,36 @@ function attributeBackedProps(Cls) {
   // Memoized per class (#1646): the SSR walk resolves every source attribute
   // of every instance through this list, and rebuilding it (one hyphenate per
   // declared prop) was a measurable share of a component's render. A class's
-  // declarations never change after it is defined (a `static properties`
-  // block throws at runtime, and the factory fixes the set), so the first
-  // walk is the only one.
+  // declarations are fixed once it is defined (`declaredProperties` reads them
+  // once per class), so the first walk is the only one.
   if (Cls && typeof Cls === 'function') {
+    // Valid while no declarations changed anywhere (one lookup); after a
+    // change, while the class's declarations map is the same object, which it
+    // stays unless this class or a superclass changed.
     const hit = BACKED_PROPS.get(Cls);
-    if (hit) return hit;
+    if (hit && hit.epoch === epoch) return hit.built;
+    const merged = declaredProperties(Cls);
+    if (hit && hit.merged === merged) { hit.epoch = epoch; return hit.built; }
     const built = buildAttributeBackedProps(Cls);
-    BACKED_PROPS.set(Cls, built);
+    BACKED_PROPS.set(Cls, { epoch, merged, built });
     return built;
   }
   return buildAttributeBackedProps(Cls);
 }
 
-/** @type {WeakMap<Function, { propName: string, def: any, primary: string, alias: string | undefined }[]>} */
+/** @type {WeakMap<Function, { epoch: number, merged: Record<string, any>, built: { propName: string, def: any, primary: string, alias: string | undefined }[] }>} */
 const BACKED_PROPS = new WeakMap();
 
 function buildAttributeBackedProps(Cls) {
-  const props = (Cls && Cls.properties) || {};
+  const props = declaredProperties(Cls);
   const out = [];
-  for (const [k, decl] of Object.entries(props)) {
-    const d = typeof decl === 'object' && decl !== null ? decl : { type: decl };
-    if (d.state) continue;
-    const primary = d.attribute || hyphenate(k);
-    const lower = k.toLowerCase();
-    const alias = !d.attribute && lower !== primary ? lower : undefined;
+  // Symbol keys too: one reaches an attribute through its `attribute` option.
+  for (const k of Reflect.ownKeys(props)) {
+    const d = normalizeDecl(props[k]);
+    const primary = attributeNameFor(k, d);
+    if (primary === undefined) continue;
+    const kebab = typeof k === 'string' ? hyphenate(k) : primary;
+    const alias = typeof d.attribute !== 'string' && kebab !== primary ? kebab : undefined;
     out.push({ propName: k, def: d, primary, alias });
   }
   return out;

package/src/binding-prefixes.js

@@ -1,3 +1,4 @@
+import { nothing, noChange } from './sentinels.js';
 /**
  * The template attribute-binding prefixes the renderers recognise.
  *
@@ -9,18 +10,6 @@
  * renderer (`render-server.js`, two sites) read it instead of hardcoding
  * the prefix characters inline.
  *
- * It is also the anchor for the elision drift guard. The analyser
- * (`packages/server/src/component-elision.js`) classifies every prefix as
- * either a client-behaviour ship signal (it drops at SSR and implies the
- * component does client work, so a component using it must ship) or an
- * SSR-safe round-trip (it survives into the served HTML, so it is not a
- * ship signal). The guard test
- * (`packages/server/test/elision/sigil-coverage.test.js`) asserts that
- * classification covers EXACTLY these keys, so a new prefix cannot be
- * added here without the analyser being taught which kind it is. That
- * closes the one gap the prototype-introspection guard
- * (`lifecycle-coverage.test.js`) cannot reach, because a sigil is syntax,
- * not a prototype method or a named export.
  *
  * @type {Readonly<Record<string, 'event' | 'prop' | 'bool'>>}
  */
@@ -42,48 +31,16 @@ export function isBindingPrefix(ch) {
 }
 
 /**
- * The HTML boolean attributes: present means on, absent means off, and the
- * value is meant to be empty. A boolean in a PLAIN hole on one of these renders
- * exactly like `?attr` (#1579), so `checked=${isDefault}` cannot serve the
- * `checked="false"` that HTML reads as checked. Lowercase, from the HTML spec's
- * attribute index.
- */
-const BOOLEAN_ATTRIBUTES = new Set([
-  'allowfullscreen', 'async', 'autofocus', 'autoplay', 'checked', 'controls',
-  'default', 'defer', 'disabled', 'formnovalidate', 'hidden', 'inert',
-  'ismap', 'itemscope', 'loop', 'multiple', 'muted', 'nomodule', 'novalidate',
-  'open', 'playsinline', 'readonly', 'required', 'reversed', 'selected',
-  'shadowrootclonable', 'shadowrootdelegatesfocus', 'shadowrootserializable',
-]);
-
-/**
- * What a PLAIN attribute hole (`name=${value}`, unquoted, the whole value)
- * writes, or `null` when the attribute is omitted. The one rule both renderers
- * follow, so the server never serves an attribute the client then removes
- * (#1573, #1579):
- *
- *   - `null` / `undefined` omit the attribute. This is the "omit" value, so a
- *     conditional attribute is `aria-current=${active ? 'page' : null}`.
- *   - `false` omits it too, EXCEPT on an `aria-*` attribute, where it writes
- *     `"false"`. For a tri-state ARIA attribute (`aria-expanded`,
- *     `aria-pressed`, `aria-checked`) `"false"` and absent mean different
- *     things, so the value an author passes is the value the user agent gets.
- *   - `true` on an HTML boolean attribute (`checked`, `selected`, `disabled`,
- *     and the rest) writes the empty value, exactly as `?attr=${true}` does. Anywhere
- *     else it is `"true"`.
- *   - anything else is `String(value)`.
- *
- * A quoted or mixed value (`title="${x}"`, `class="a ${x}"`) is not a plain
- * hole: the author wrote the attribute statically, so it stays and a nullish
- * piece reads as empty text.
+ * Serialize an ordinary whole-value attribute expression for SSR and client
+ * commits. Nullish values become empty strings and booleans stringify.
+ * `nothing` omits the attribute. `noChange` omits it on initial SSR; client
+ * updates handle that sentinel before serialization to retain the prior value.
  *
- * @param {string} name the attribute name as written
- * @param {unknown} value the hole's value (`live()` already unwrapped)
+ * @param {string} _name attribute name (kept for the shared call signature)
+ * @param {unknown} value the expression value (`live()` already unwrapped)
  * @returns {string | null}
  */
-export function attrHoleValue(name, value) {
-  if (value == null) return null;
-  if (value === false) return /^aria-/i.test(name) ? 'false' : null;
-  if (value === true && BOOLEAN_ATTRIBUTES.has(String(name).toLowerCase())) return '';
-  return String(value);
+export function attrHoleValue(_name, value) {
+  if (value === nothing || value === noChange) return null;
+  return String(value ?? '');
 }