@webjsdev/core 0.7.5 → 0.7.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/core",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "type": "module",
   "description": "webjs core runtime - html/css tags, WebComponent base, isomorphic renderers",
   "types": "./index.d.ts",

package/src/component.js

@@ -147,8 +147,143 @@ function defaultHasChanged(a, b) {
  * ```
  */
 
-// Base class choice: real HTMLElement on the browser, a dummy on the server.
-const Base = isBrowser ? HTMLElement : /** @type {any} */ (class {});
+/**
+ * Inert `ElementInternals`-shaped object returned by the server shim's
+ * `attachInternals()`. Modeled on `@lit-labs/ssr-dom-shim`'s
+ * `ElementInternalsShim` (lit repo, `packages/labs/ssr-dom-shim/src/lib/
+ * element-internals.ts`): form-association, validity, and custom-state
+ * calls are no-ops at SSR (no form, no constraint validation, no `:state()`
+ * matching server-side), so a component that calls `this.attachInternals()`
+ * in its constructor renders instead of crashing. The browser runs the real
+ * `attachInternals()` on hydration.
+ *
+ * Deliberate deviation from lit: lit's `checkValidity` / `reportValidity`
+ * THROW on the server. webjs returns `true` instead, to keep SSR
+ * progressive-enhancement-safe (a stray validity call in a constructor must
+ * not 500 the page); the browser does the real validation.
+ * @returns {any}
+ */
+function makeServerInternals() {
+  return {
+    states: new Set(),
+    shadowRoot: null,
+    form: null,
+    labels: [],
+    role: '',
+    willValidate: true,
+    validity: /** @type {any} */ ({}),
+    validationMessage: '',
+    setFormValue() {},
+    setValidity() {},
+    checkValidity() { return true; },
+    reportValidity() { return true; },
+  };
+}
+
+/**
+ * Server-side stand-in for `HTMLElement`. The SSR pipeline constructs
+ * component instances in Node, where `HTMLElement` does not exist, so the
+ * base class is this shim. It is modeled on `@lit-labs/ssr-dom-shim`'s
+ * `ElementShim` (lit repo, `packages/labs/ssr-dom-shim/src/index.ts`): the
+ * attribute methods (`getAttribute` / `setAttribute` / `hasAttribute` /
+ * `removeAttribute` / `toggleAttribute`, the `attributes` getter) are backed
+ * by a Map, so lit muscle-memory patterns that read attributes in `render()`
+ * or set them while deriving state work server-side; the SSR walker seeds
+ * the Map from the element's source attributes and reads it back to surface
+ * reflected/added attributes in the output. Event methods are no-ops (no
+ * server event loop), and `attachInternals()` returns the inert object
+ * above. The genuinely browser-only surface (`querySelector`, layout reads,
+ * `attachShadow`, `focus`) is deliberately absent and still throws at SSR,
+ * which the `no-browser-globals-in-render` rule and the SSR crash hint flag.
+ *
+ * Deliberate deviation from lit: this shim lowercases attribute names so
+ * `getAttribute('Foo')` after `setAttribute('foo', x)` resolves, matching how
+ * a real browser treats HTML attribute names as case-insensitive. lit's shim
+ * keys the Map by the raw name (a known fidelity gap in lit-labs).
+ */
+class ServerElement {
+  constructor() {
+    /**
+     * Backing store for the attribute methods. Keys are lowercased
+     * attribute names (HTML attributes are case-insensitive). Seeded by the
+     * SSR walker from the element's source attributes.
+     * @type {Map<string, string>}
+     */
+    this.__ssrAttrs = new Map();
+    /** @type {any} */
+    this.__internals = null;
+  }
+
+  /** Mirrors `Element.attributes`: an array of `{ name, value }`. */
+  get attributes() {
+    return [...this.__ssrAttrs].map(([name, value]) => ({ name, value }));
+  }
+
+  /** @param {string} name */
+  getAttribute(name) {
+    const v = this.__ssrAttrs.get(String(name).toLowerCase());
+    return v === undefined ? null : v;
+  }
+
+  /** @param {string} name @param {unknown} value */
+  setAttribute(name, value) {
+    // Emulate the browser casting all values to string (lit does the same).
+    this.__ssrAttrs.set(String(name).toLowerCase(), String(value));
+  }
+
+  /** @param {string} name */
+  removeAttribute(name) {
+    this.__ssrAttrs.delete(String(name).toLowerCase());
+  }
+
+  /** @param {string} name */
+  hasAttribute(name) {
+    return this.__ssrAttrs.has(String(name).toLowerCase());
+  }
+
+  /** @param {string} name @param {boolean} [force] */
+  toggleAttribute(name, force) {
+    // Steps mirror https://dom.spec.whatwg.org/#dom-element-toggleattribute
+    const key = String(name).toLowerCase();
+    const present = this.__ssrAttrs.has(key);
+    const next = force === undefined ? !present : force;
+    if (next) {
+      this.__ssrAttrs.set(key, '');
+      return true;
+    }
+    this.__ssrAttrs.delete(key);
+    return false;
+  }
+
+  /** @returns {string[]} */
+  getAttributeNames() {
+    return [...this.__ssrAttrs.keys()];
+  }
+
+  // No server event loop: listeners never fire at SSR. The no-op keeps a
+  // constructor that wires delegated listeners (a common lit pattern) from
+  // crashing; the browser re-runs the constructor on hydration where the
+  // real HTMLElement methods apply.
+  addEventListener() {}
+  removeEventListener() {}
+  dispatchEvent() { return true; }
+
+  /** @returns {any} */
+  attachInternals() {
+    // Match the browser (and lit's shim): a second attach is an error.
+    if (this.__internals !== null) {
+      throw new Error(
+        "Failed to execute 'attachInternals' on 'HTMLElement': " +
+          'ElementInternals for the specified element was already attached.',
+      );
+    }
+    this.__internals = makeServerInternals();
+    return this.__internals;
+  }
+}
+
+// Base class choice: real HTMLElement on the browser, the shim on the server.
+const Base = isBrowser ? HTMLElement : /** @type {any} */ (ServerElement);
 
 export class WebComponent extends Base {
   /** Whether to use shadow DOM. Default: false (light DOM). @type {boolean} */
@@ -467,6 +602,13 @@ export class WebComponent extends Base {
 
   _activate() {
     this._connected = true;
+    // Reflect declared reflect:true properties from their current value now
+    // that the element is connected. Constructor / willUpdate defaults were
+    // set while disconnected (the setter skips reflection then), so this is
+    // what makes a freshly-created client element carry the same reflected
+    // attributes the SSR walker emitted. Same-value reflects are no-ops, so a
+    // hydrated element (whose attribute already arrived from SSR) is unchanged.
+    this._reflectDeclaredAttributes();
     const Ctor = /** @type any */ (this.constructor);
     if (Ctor.shadow === true) {
       const hadSSRShadow = !!this.shadowRoot;
@@ -815,6 +957,67 @@ export class WebComponent extends Base {
     }
   }
 
+  /**
+   * Run the pre-render half of the update cycle synchronously for SSR.
+   *
+   * The SSR walker constructs the instance, applies attributes/props, then
+   * calls this BEFORE `render()`. It mirrors how lit drives the update
+   * lifecycle server-side: `willUpdate` runs so derived state computed there
+   * is correct in the SSR'd HTML, then reactive controllers' `hostUpdate`
+   * runs, then reflect:true properties are written to attributes so they
+   * appear in the serialized output. It deliberately does NOT run
+   * `shouldUpdate` (SSR always produces the first paint, there is no prior
+   * render to skip), `update` (the walker commits by calling `render`
+   * itself), or the post-commit hooks `firstUpdated` / `updated` (browser-only
+   * DOM work).
+   *
+   * `_isUpdating` is set so a property assignment inside `willUpdate` folds
+   * into the current `changedProperties` snapshot instead of scheduling a
+   * fresh cycle (the SSR scheduler short-circuits anyway, since the element
+   * is not connected). Hook throws propagate to the walker's per-component
+   * try/catch, which logs an actionable hint and skips DSD for that element,
+   * the same as a throwing `render()`.
+   */
+  performServerUpdate() {
+    const changedProperties = this._changedProperties;
+    this._isUpdating = true;
+    try {
+      this.willUpdate(changedProperties);
+      for (const c of this.__controllers) {
+        if (c.hostUpdate) c.hostUpdate();
+      }
+      this._reflectDeclaredAttributes();
+    } finally {
+      this._isUpdating = false;
+    }
+  }
+
+  /**
+   * Reflect every reflect:true (non-state) property to its attribute from its
+   * CURRENT value, regardless of whether the value arrived via the setter.
+   *
+   * The property setter only reflects on a connected change, so a value set
+   * in the constructor (a default) or in `willUpdate` is not reflected by the
+   * setter alone. This syncs those: the SSR walker calls it in
+   * `performServerUpdate` (writing into the server attribute shim, which the
+   * walker reads back into the rendered HTML), and `_activate` calls it on
+   * the client's first connected render. Running it on both sides is what
+   * keeps a server-rendered element and a freshly-created client element
+   * agree on their reflected attributes (matching lit, which reflects during
+   * the first update). `_reflectAttribute`'s re-entrancy guard makes a
+   * same-value reflect a no-op, so re-reflecting an attribute that already
+   * arrived from SSR does not churn.
+   * @private
+   */
+  _reflectDeclaredAttributes() {
+    const props = /** @type {any} */ (this.constructor).properties || {};
+    for (const name of Object.keys(props)) {
+      const decl = props[name];
+      if (!decl || !decl.reflect || decl.state) continue;
+      this._reflectAttribute(name, this[name], decl);
+    }
+  }
+
   // ---------------------------------------------------------------------------
   // Lifecycle hooks: override in subclasses
   // ---------------------------------------------------------------------------

package/src/render-server.js

@@ -322,9 +322,13 @@ const SSR_BROWSER_GLOBALS = new Set([
   'matchMedia', 'requestAnimationFrame', 'getComputedStyle',
   'IntersectionObserver', 'MutationObserver', 'ResizeObserver',
 ]);
+// Attribute methods (get/set/has/remove/toggleAttribute), the event methods
+// (add/removeEventListener, dispatchEvent), and attachInternals are backed by
+// the server-side element shim and work at SSR, so they are NOT listed here.
+// What remains is the genuinely browser-only HTMLElement surface that still
+// has no server stand-in and throws at SSR.
 const SSR_HTMLELEMENT_METHODS = new Set([
-  'attachShadow', 'setAttribute', 'getAttribute', 'removeAttribute',
-  'hasAttribute', 'dispatchEvent', 'querySelector', 'querySelectorAll',
+  'attachShadow', 'querySelector', 'querySelectorAll',
   'getBoundingClientRect', 'focus', 'blur', 'scrollIntoView',
 ]);
 
@@ -383,7 +387,7 @@ async function injectDSD(html, ctx) {
     // Track which custom elements actually appeared: used by SSR to emit
     // `<link rel="modulepreload">` hints for their module URLs.
     if (ctx && ctx.usedComponents) ctx.usedComponents.add(tag);
-    const opening = selfClose ? `<${tag}${attrs}>` : match;
+    let opening = selfClose ? `<${tag}${attrs}>` : match;
     try {
       const isShadow = /** @type any */ (Cls).shadow === true;
       const instance = new /** @type any */ (Cls)();
@@ -394,8 +398,29 @@ async function injectDSD(html, ctx) {
       // properties` type. Property bindings take priority on a name
       // collision because they preserve the original JS reference.
       const propValues = consumePropAttrs(attrMap);
+      // Names already present in the source opening tag (including the
+      // data-webjs-prop-* bindings, which were stripped from attrMap above
+      // but remain in the emitted `attrs` string). Reflected/added
+      // attributes are appended only when their name is NOT already here, so
+      // existing output stays byte-identical when nothing reflects.
+      const presentAttrNames = new Set(Object.keys(parseAttrs(attrs)).map((n) => n.toLowerCase()));
+      // Seed the server attribute shim so `this.getAttribute(...)` /
+      // `this.hasAttribute(...)` in willUpdate / render read the source
+      // attributes (a lit muscle-memory pattern) instead of reading empty.
+      seedServerAttrs(instance, attrMap);
       applyAttrsToInstance(instance, attrMap, Cls);
       for (const [k, v] of Object.entries(propValues)) instance[k] = v;
+      // Run the pre-render lifecycle (willUpdate, controllers' hostUpdate,
+      // then reflect reflect:true props) so derived state computed there is
+      // correct in the SSR'd HTML, matching how lit runs the update cycle at
+      // SSR. WebComponent instances expose performServerUpdate; bare
+      // Base-extending kit components (no lifecycle) do not, so it is guarded.
+      if (typeof instance.performServerUpdate === 'function') instance.performServerUpdate();
+      // Surface attributes the component set before render (reflected
+      // reflect:true props, or an explicit this.setAttribute in the
+      // constructor / willUpdate) that were not already in the source tag.
+      // Appending keeps the original tag byte-identical when nothing changed.
+      opening = appendReflectedAttrs(opening, instance, presentAttrNames);
       let tpl = instance.render ? instance.render() : '';
       if (tpl && typeof tpl.then === 'function') tpl = await tpl;
       // Render the template to HTML. injectDSD recurses on the result so
@@ -764,6 +789,55 @@ function parseAttrs(attrStr) {
   return out;
 }
 
+/**
+ * Seed the element's attributes from the source opening tag so reads like
+ * `this.getAttribute(name)` / `this.hasAttribute(name)` inside willUpdate /
+ * render return the real value during SSR. Goes through `setAttribute`, which
+ * both the server element shim (Node SSR) and a real `HTMLElement`
+ * (renderToString called in a browser, e.g. tests) implement, so the path
+ * does not depend on the shim's internal store. A bare Base-extending kit
+ * component without `setAttribute` is skipped.
+ *
+ * @param {any} instance
+ * @param {Record<string,string>} attrs  parsed source attributes (data-webjs-prop-* already removed)
+ */
+function seedServerAttrs(instance, attrs) {
+  if (!instance || typeof instance.setAttribute !== 'function') return;
+  for (const [name, raw] of Object.entries(attrs)) {
+    instance.setAttribute(name, unescapeAttr(raw));
+  }
+}
+
+/**
+ * Append attributes the component set before render (reflected reflect:true
+ * properties, or an explicit `this.setAttribute` in the constructor /
+ * willUpdate) to the element's opening tag, skipping any name already present
+ * in the source tag. Reads via the standard `getAttributeNames` /
+ * `getAttribute` API so it works whether the instance is the server shim or a
+ * real `HTMLElement`. Returns the opening tag unchanged when there is nothing
+ * to add, so existing SSR output stays byte-identical when no component
+ * reflects, which preserves the elision on-vs-off differential invariant.
+ *
+ * @param {string} opening  the element's opening tag, ending in `>`
+ * @param {any} instance
+ * @param {Set<string>} presentAttrNames  lowercased names already in the source tag
+ * @returns {string}
+ */
+function appendReflectedAttrs(opening, instance, presentAttrNames) {
+  if (!instance || typeof instance.getAttributeNames !== 'function') return opening;
+  let extra = '';
+  for (const rawName of instance.getAttributeNames()) {
+    const name = String(rawName).toLowerCase();
+    if (presentAttrNames.has(name)) continue;
+    const value = instance.getAttribute(rawName);
+    extra += value === '' ? ` ${name}` : ` ${name}="${escapeAttr(String(value))}"`;
+  }
+  if (!extra) return opening;
+  // Insert before the closing `>` (the opening tag is normalised to end in
+  // `>`; a self-closing source tag was already rewritten without the slash).
+  return `${opening.slice(0, -1)}${extra}>`;
+}
+
 /**
  * Coerce attribute strings to typed properties on a component instance
  * based on its static `properties` declaration.
@@ -780,7 +854,12 @@ function applyAttrsToInstance(instance, attrs, Cls) {
     if (def.type === Number) instance[propName] = Number(raw);
     else if (def.type === Boolean) instance[propName] = raw !== 'false';
     else if (def.type === Object || def.type === Array) {
-      try { instance[propName] = JSON.parse(raw); } catch { instance[propName] = raw; }
+      // `raw` is the entity-encoded attribute text (parseAttrs returns the
+      // literal characters between the quotes), so decode the HTML entities
+      // before JSON.parse. A JSON attribute carries `&quot;` for every `"`;
+      // parsing it raw throws and would silently fall back to the string,
+      // leaving an Object/Array prop holding a string at SSR.
+      try { instance[propName] = JSON.parse(unescapeAttr(raw)); } catch { instance[propName] = raw; }
     } else instance[propName] = raw;
   }
 }

package/src/task.js

@@ -93,6 +93,16 @@
  * @readonly
  * @enum {number}
  */
+// The SSR walker now runs controllers' hostUpdate during the pre-render pass
+// (issue #217). A Task must NOT invoke its task function server-side (that
+// would fire a fetch during SSR); the browser runs it on hydration. Read live
+// (not cached) so the auto-run gate reflects the current environment: SSR
+// ships the task's INITIAL state, unchanged from before hostUpdate fired at
+// SSR, and the browser runs it on connect.
+function inBrowser() {
+  return typeof window !== 'undefined';
+}
+
 export const TaskStatus = /** @type {const} */ ({
   INITIAL: 0,
   PENDING: 1,
@@ -326,6 +336,9 @@ export class Task {
    */
   hostUpdate() {
     if (!this._autoRun) return;
+    // Never auto-run server-side: SSR ships the INITIAL state and the task
+    // function (typically a fetch) runs only in the browser on hydration.
+    if (!inBrowser()) return;
 
     const nextArgs = this._argsFn();