@webjsdev/core 0.7.49 → 0.7.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/core",
-  "version": "0.7.49",
+  "version": "0.7.50",
   "type": "module",
   "description": "The runtime for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Ships the html and css template tags, the WebComponent base class, signals, directives, and the isomorphic renderers.",
   "types": "./index.d.ts",

package/src/attribute-reader.js

@@ -0,0 +1,178 @@
+/**
+ * THE attribute reader, singular.
+ *
+ * `attributeChangedCallback` in `component.js` and `applyAttrsToInstance` in
+ * `render-server.js` are both thin callers of the two functions below, so the
+ * client and the SSR pass cannot drift on precedence, on a fallback, or on
+ * which attributes they read at all. They had drifted four ways before this
+ * module existed: the unparseable-JSON fallback (#1253), a missing converter
+ * arm (#1340), and three name-resolution gaps plus the entity decoding (#1341).
+ *
+ * The split between the two exports is the one place the sides legitimately
+ * differ. `resolveAttributeProperty` takes the name the PLATFORM would deliver,
+ * so the SSR caller lowercases its source name first and the client passes the
+ * browser's name straight through. Everything after that is common.
+ *
+ * WHY ITS OWN MODULE, rather than living beside the declaration semantics it
+ * interprets in `component.js`. That was the first shape, and `component.d.ts`
+ * cannot carry the declaration for it: `index.d.ts` re-exports that overlay
+ * with a bare `export *`, so a value declared there joins the ROOT public type
+ * surface of `@webjsdev/core` while `index.js` exports no such runtime value.
+ * An app writing `import { readAttributeValue } from '@webjsdev/core'` would
+ * then type-check and crash at load, which is exactly the phantom the #1031
+ * guard in `test/types/dts-no-phantom-exports.test.mjs` exists to catch, and it
+ * caught this one. Re-exporting the function from `index.js` would silence the
+ * guard by making an internal framework seam app-facing API, which is the wrong
+ * trade. A module with no `.d.ts` overlay keeps the seam internal and typed
+ * from its own JSDoc, which is how `escape.js` and `binding-prefixes.js`
+ * already work.
+ *
+ * It also drops an edge rather than adding one: `render-server.js` reaches the
+ * reader without importing `component.js` at all.
+ *
+ * lit solves the same problem structurally, though in the other direction.
+ * `@lit-labs/ssr`'s LitElementRenderer forwards its `attributeChangedCallback`
+ * into the element's own `_$attributeToProperty` through
+ * `lit-element/private-ssr-support.js`, so its server pass runs the browser's
+ * reader rather than a copy of it. lit can reach INTO the element because its
+ * elements are TypeScript with a generated declaration; WebJs ships buildless
+ * JS under a hand-written overlay, so the shared code moves out instead.
+ */
+
+/**
+ * Read one attribute string into its declared property value.
+ *
+ * The caller owns only the one platform-specific step, lowercasing the source
+ * name at SSR; `resolveAttributeProperty` below owns NAME resolution and
+ * declaration normalisation for both sides, and this function owns the value.
+ * The two callers used to reach an attribute by different routes and NOT see
+ * the same attribute set, which #1341 closed.
+ *
+ * @param {import('./component.js').PropertyDeclaration} def normalised declaration (`{ type, … }`)
+ * @param {string|null} value the attribute text
+ *
+ * BOTH callers hand in an already-decoded value, so no branch decodes anything
+ * (#1341). The client's came out of the DOM, which decodes every character
+ * reference before any reader sees it; the SSR caller runs `decodeAttrEntities`
+ * once at its own call site, ahead of this function, over EVERY branch rather
+ * than only the ones that parse. This used to be a third `decode` parameter
+ * 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.
+ * @returns {unknown}
+ */
+export function readAttributeValue(def, value) {
+  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
+    // `_reflectAttribute` already states for `toAttribute`: its guards sit
+    // AFTER the converter branch because a custom converter is
+    // author-controlled. So a converter that throws throws, on both sides. At
+    // SSR that lands in per-component error isolation (render-server.js), which
+    // surfaces an error box in dev and an empty element at a 200 in prod with
+    // the cause in the server log; on the client it escapes
+    // attributeChangedCallback during upgrade. Catching on one side only would
+    // manufacture a fresh divergence (an SSR paint holding a fallback against a
+    // browser holding the constructor value), which is worse than both sides
+    // failing. lit propagates too (reactive-element `_$attributeToProperty`).
+    //
+    // A converter RETURN that SSR cannot serialise needs no guard here either.
+    // Unreflected it is only a property, and a function in a text hole renders
+    // as nothing. Reflected, the #1169 function guard and the #1253
+    // unserializable guard in `_reflectAttribute` already run on the SSR side
+    // and cover whatever the converter produced.
+    //
+    // The converter is handed DECODED text, which matters more here than
+    // anywhere: the documented reason to write one is a type the built-in
+    // converters cannot parse (Date, Map, Set), those parse their input, and
+    // `escapeAttr` encodes every `"` in an emitted attribute, so an encoded
+    // `{"a":1}` would throw inside the author's converter and (since
+    // the throw is deliberately uncaught) render an empty component at a 200.
+    // Both callers now decode before calling, so it gets the same text on both
+    // sides for hand-written markup as well as for anything WebJs emitted
+    // (#1341); this used to be a `decode` argument applied on this branch and
+    // the JSON one.
+    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 === 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
+    // the author declared `Object` or `Array`, whatever put it there. lit's
+    // `defaultConverter.fromAttribute` lands on the same `null`, for the reason
+    // its own comment gives: an element does not complain about being
+    // mis-configured. Both readers reach this line, so they cannot disagree.
+    //
+    // An attribute that was never PRESENT does not reach either reader, so such
+    // a prop simply keeps its constructor 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
+    // `d.attribute || hyphenate(k)` expression `observedAttributes` maps over
+    // and nothing else, so it skips a `state: true` 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
+    // character reference already decoded, legacy semicolon-less names included.
+    if (value == null) return null;
+    try { return JSON.parse(value); } catch { return null; }
+  }
+  return value;
+}
+
+/** Kebab-case a property name for its default HTML attribute. @param {string} s */
+function hyphenate(s) {
+  return s.replace(/([A-Z])/g, '-$1').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
+ * `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`
+ * `_$attributeToProperty`).
+ *
+ * `attrName` must already be the name the PLATFORM would deliver. The browser
+ * lowercases attribute names while parsing, so the SSR caller lowercases its
+ * source name before calling and the client caller passes the browser's name
+ * through untouched. That one step is the only thing that differs between the
+ * two sides, which is why it lives in the callers and not here. A custom
+ * `attribute` option is matched VERBATIM, as lit matches it and as a browser
+ * would, so a camelCase custom attribute stays unreachable from markup rather
+ * than being reachable at SSR only. Lowercasing the DECLARED side would make
+ * SSR read MORE than a browser can deliver, which is the bug this function
+ * exists to remove, so do not add it.
+ *
+ * The match is EXACTLY `d.attribute || hyphenate(k)`, the same expression
+ * `observedAttributes` maps over, and nothing else. A `props[attrName] ||
+ * props[camelCase(attrName)]` fallback used to sit after the loop, so a prop
+ * declaring a custom attribute also answered to its PROPERTY name. Both readers
+ * carried that code, which read like an agreement and was not one: the browser
+ * only ever calls in with a name from `observedAttributes`, and that list holds
+ * the declared attribute alone, so the fallback was unreachable on the client
+ * and live on the server. Measured, `open: prop(Boolean, { attribute:
+ * 'is-open' })` with `<my-el open>` SSR'd `true` and upgraded to the
+ * constructor value. Deriving the match from the same expression the observed
+ * list is built from is what makes the two sides agree by construction rather
+ * than by two copies staying in step (#1341).
+ *
+ * @param {any} Cls  the component class
+ * @param {string} attrName
+ * @returns {{ propName: string, def: PropertyDeclaration } | undefined}
+ *   `undefined` when the attribute maps to no attribute-backed property, in
+ *   which case the caller must IGNORE the attribute entirely (#1341).
+ */
+export function resolveAttributeProperty(Cls, attrName) {
+  const props = (Cls && Cls.properties) || {};
+  for (const [k, decl] of Object.entries(props)) {
+    const d = typeof decl === 'object' && decl !== null ? decl : { type: decl };
+    if (d.state) continue;
+    if ((d.attribute || hyphenate(k)) === attrName) return { propName: k, def: d };
+  }
+  return undefined;
+}

package/src/component.d.ts

@@ -213,3 +213,13 @@ export declare function prop<T>(
 export declare function prop<T = string>(
   opts?: PropertyDeclaration<T>
 ): PropertyDeclaration<T>;
+
+// The shared attribute reader (`resolveAttributeProperty`, #1341) is NOT here,
+// and nothing about it belongs here. It lives in `src/attribute-reader.js`,
+// which has no `exports` entry, because two guards bracket every mapped entry
+// and `./component` is one: #388 forces every runtime named export of
+// `component.js` to be declared in this file, and #1031 forces every
+// declaration reachable from `index.d.ts` (which re-exports this file with
+// `export *`) to exist on `index.js` at runtime. Together they leave no way to
+// add an INTERNAL named export to `component.js`. That module's header carries
+// the full reasoning.

package/src/component.js

@@ -1,10 +1,12 @@
 import { render as clientRender } from './render-client.js';
+import { readAttributeValue } from './attribute-reader.js';
 import { setActiveActionSignal } from './action-abort-client.js';
 import { carriesFunction } from './form-action.js';
 import { isCSS, adoptStyles } from './css.js';
 import { register, tagOf } from './registry.js';
 import { parse as deserializeProp } from './serialize.js';
 import { Signal } from './signal.js';
+import { resolveAttributeProperty } from './attribute-reader.js';
 import {
   captureAuthoredChildren,
   adoptSSRAssignments,
@@ -85,7 +87,11 @@ const isBrowser = typeof window !== 'undefined' && typeof HTMLElement !== 'undef
  *
  * @property {{ fromAttribute: (value: string|null, type?: Function) => unknown, toAttribute: (value: unknown, type?: Function) => string|null }} [converter]
  *   Custom serialization/deserialization pair for the HTML attribute.
- *   `fromAttribute` is called in `attributeChangedCallback`;
+ *   `fromAttribute` is called by BOTH attribute readers through the shared
+ *   `readAttributeValue` in `attribute-reader.js`: the client
+ *   `attributeChangedCallback` and the SSR
+ *   `applyAttrsToInstance` in `render-server.js` (#1340). So it runs
+ *   server-side too, and must not touch browser globals.
  *   `toAttribute` is called when reflecting back to the attribute.
  *   If omitted, the built-in type-based coercion is used.
  */
@@ -100,6 +106,7 @@ function defaultHasChanged(a, b) {
   return a !== b;
 }
 
+
 /**
  * `String(v)` that cannot itself throw.
  *
@@ -1141,64 +1148,22 @@ class WebComponentBase extends Base {
     // resulting attributeChangedCallback to avoid infinite loops.
     if (this.__reflectingAttribute) return;
 
-    const Ctor = /** @type any */ (this.constructor);
-    const allProps = (Ctor.properties || {});
-    // Resolve the incoming attribute name to its property. A custom
-    // `attribute` option wins; otherwise the kebab-cased property name. Falls
-    // back to the camelCase of the attribute for the common (kebab) case.
-    let propName, raw;
-    for (const [k, decl] of Object.entries(allProps)) {
-      const d = typeof decl === 'object' ? decl : { type: decl };
-      if ((d.attribute || hyphenate(k)) === name) { propName = k; raw = decl; break; }
-    }
-    if (raw === undefined) { propName = camelCase(name); raw = allProps[propName] || allProps[name]; }
-    if (raw === undefined) return;
-    // A declaration is either a full descriptor (`{ type: Number, … }`) or the
-    // bare-constructor shorthand the factory accepts (`count: Number`), in which
-    // case the value IS the type. Normalise so type-based coercion fires either
-    // way (matches `_initializeProperties`).
-    const def = typeof raw === 'object' ? raw : { type: raw };
-
-    let v;
-    if (def.converter && def.converter.fromAttribute) {
-      v = def.converter.fromAttribute(value, def.type);
-    } else if (def.type === Number) {
-      v = value == null ? null : Number(value);
-    } else if (def.type === Boolean) {
-      v = value != null && value !== 'false';
-    } else 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 the author declared `Object` or `Array`, whatever put it
-      // there. lit's `defaultConverter.fromAttribute` lands on the same `null`,
-      // for the reason its own comment gives: an element does not complain
-      // about being mis-configured.
-      //
-      // `applyAttrsToInstance` in `render-server.js` is the SSR counterpart of
-      // THIS branch and yields `null` for the same input. They have to agree,
-      // or an element SSRs holding one value and re-renders holding another.
-      // The agreement is about an attribute that is PRESENT and unparseable;
-      // an attribute that was never there does not reach either reader, so
-      // such a prop simply keeps its constructor value.
-      //
-      // That agreement is about this FALLBACK, not a guarantee that the two
-      // readers see the same attributes in the first place. They reach an
-      // attribute by different routes (this one via `observedAttributes` and
-      // the browser's own name-lowercasing, the SSR one by walking the parsed
-      // source tag), and hand-written markup can land in the gaps between
-      // those routes, so an author literal can still be read by one and not
-      // the other. Those gaps predate #1253 and it neither causes nor closes
-      // any of them; no attempt is made here to enumerate them, because every
-      // attempt so far has been incomplete.
-      //
-      // Scoped to the default converter. A prop supplying its own
-      // `converter.fromAttribute` is handled by the arm above and the SSR
-      // reader has no converter arm at all, so the two sides already read such
-      // a prop differently. That gap predates #1253 and is left alone.
-      try { v = value == null ? null : JSON.parse(value); } catch { v = null; }
-    } else {
-      v = value;
-    }
+    // One name resolver for both sides (#1341). The browser only calls this for
+    // a name in `observedAttributes`, and it has already lowercased that name
+    // while parsing, so it passes straight through; the SSR caller lowercases
+    // its source name first. `resolveAttributeProperty` also normalises the
+    // declaration, so a bare-constructor shorthand (`count: Number`) and the
+    // long form (`{ type: Number, … }`) both arrive here as `{ type, … }`.
+    const resolved = resolveAttributeProperty(this.constructor, name);
+    if (resolved === undefined) return;
+    const { propName, def } = resolved;
+
+    // One reader for both sides, in `attribute-reader.js`: this and
+    // `applyAttrsToInstance` in `render-server.js` call the same function, so
+    // precedence and every fallback are shared rather than mirrored (#1340).
+    // It takes an already-decoded value, which the DOM has done here and
+    // `decodeAttrEntities` does at the SSR call site (#1341).
+    const v = readAttributeValue(def, value);
 
     if (this[propName] !== v) {
       this[propName] = v;