@webjsdev/core 0.7.49 → 0.7.51

package/src/component/reactive.js

@@ -0,0 +1,171 @@
+import { tagOf } from '../registry.js';
+
+/**
+ * Default change detection: strict inequality.
+ * @param {unknown} a
+ * @param {unknown} b
+ * @returns {boolean}
+ */
+export function defaultHasChanged(a, b) {
+  return a !== b;
+}
+
+/**
+ * `String(v)` that cannot itself throw.
+ *
+ * A rejection reason is whatever the author rejected with, and not every value
+ * converts to a primitive: `Object.create(null)` has no `toString`, and a
+ * revoked Proxy throws on any operation. Coercing one in an error-reporting
+ * path turned a reportable failure into a second, unreported one.
+ *
+ * @param {unknown} v
+ * @returns {string}
+ */
+export function safeString(v) {
+  try {
+    return String(v);
+  } catch {
+    return Object.prototype.toString.call(v);
+  }
+}
+
+/**
+ * Warn that a function value was dropped rather than reflected (#1169).
+ *
+ * A silently missing attribute is its own confusion, so say what went and why.
+ * The message deliberately does NOT include the value: printing the source is
+ * the leak this guard exists to prevent, and a server log is not always a
+ * private place.
+ *
+ * UNCONDITIONAL, matching the `.prop=${fn}` unserializable-value drop in
+ * `render-server.js`, which is the sibling path this guard mirrors. Two
+ * reasons not to gate it on a dev flag. It fires only on a genuine mistake (a
+ * function is never a meaningful attribute value), so there is no volume to
+ * suppress, and reflection runs per assignment rather than per frame.
+ *
+ * More decisively, a `NODE_ENV` gate does not survive the dist build.
+ * `scripts/build-framework-dist.js` runs esbuild with `platform: 'browser'`
+ * and `minify: true`, which substitutes `process.env.NODE_ENV` with
+ * `"production"` and folds the check to a constant. The SSR half of the
+ * warning would then be unreachable in every published build, which is how
+ * every installed app runs, and SSR is the half that matters most, since that
+ * is where the leaked source reached visitors.
+ *
+ * @param {{ constructor: unknown, tagName?: string }} host
+ * @param {string} propName
+ * @param {string} attrName
+ */
+export function warnFunctionReflection(host, propName, attrName) {
+  if (typeof console === 'undefined' || !console.warn) return;
+  const tag = tagOf(/** @type any */ (host.constructor)) || host.tagName?.toLowerCase() || 'unknown';
+  console.warn(
+    `[webjs] reflect:true property "${propName}" on <${tag}> holds a function `
+    + `(or an array carrying one), which has no HTML attribute representation. `
+    + `Removing "${attrName}" instead of stringifying it (a stringified function `
+    + `writes its source into the page, so a server action's body would ship to `
+    + `the browser). Pass a string, or drop reflect on this property.`
+  );
+}
+
+/**
+ * Warn that a value with no JSON representation was dropped rather than
+ * reflected (#1253).
+ *
+ * `JSON.stringify` throws for three reasons an app hits in practice: a cycle,
+ * a `BigInt`, and an author `toJSON()` that throws. All three mean the same
+ * thing here, that there is no string to put in the attribute, so all three
+ * get the same answer as a function does.
+ *
+ * The caught message IS included, unlike `warnFunctionReflection`, which
+ * withholds its value on purpose. A function's string form is its source,
+ * which is the leak that guard exists to prevent; `JSON.stringify`'s own
+ * message names the property path rather than a value, and the sibling
+ * `.prop=${val}` SSR drop in `render-server.js` already ends the same way.
+ *
+ * UNCONDITIONAL, for the reason recorded on `warnFunctionReflection` above: a
+ * `NODE_ENV` gate is folded to a constant by the dist build, which would make
+ * the SSR half unreachable in every published build, and the SSR half is where
+ * the component silently vanishes.
+ *
+ * @param {{ constructor: unknown, tagName?: string }} host
+ * @param {string} propName
+ * @param {string} attrName
+ * @param {string} [detail] the message `JSON.stringify` threw
+ */
+export function warnUnserializableReflection(host, propName, attrName, detail) {
+  if (typeof console === 'undefined' || !console.warn) return;
+  const tag = tagOf(/** @type any */ (host.constructor)) || host.tagName?.toLowerCase() || 'unknown';
+  console.warn(
+    `[webjs] reflect:true property "${propName}" on <${tag}> holds a value `
+    + `JSON.stringify cannot serialize (a cycle, a BigInt, or a throwing `
+    + `toJSON), so it has no HTML attribute representation. Removing `
+    + `"${attrName}" instead. Detail: ${detail}`
+  );
+}
+
+/**
+ * A minimal base for HTML Custom Elements that mirrors Lit's ergonomics
+ * while staying JSDoc-only and no-build.
+ *
+ * Subclasses declare:
+ *  - `static properties`: attribute/property declarations with type info,
+ *    reflection, custom converters, and internal-state mode
+ *  - `static styles`: CSSResult or array thereof (only meaningful with
+ *    `static shadow = true`; light-DOM components inherit global CSS)
+ *  - `static shadow`: set `true` to opt in to shadow DOM (default: `false`
+ *    → light DOM, so Tailwind / global CSS apply directly)
+ *  - `render()`: returns a TemplateResult
+ *
+ * The tag name is not a static field: pass it to `.register('tag-name')`
+ * at the bottom of the file. Tag must contain a hyphen (HTML spec).
+ *
+ * Lifecycle (lit-aligned, called in order during each update cycle):
+ *  1. `shouldUpdate(changedProperties)`. Skip update if false.
+ *  2. `willUpdate(changedProperties)`. Safe to set properties; folds into this cycle.
+ *  3. controllers' `hostUpdate()`
+ *  4. `update(changedProperties)`. Default impl calls `render()` + commits.
+ *  5. controllers' `hostUpdated()`
+ *  6. `firstUpdated(changedProperties)`: once, on the first render only
+ *  7. `updated(changedProperties)`: every render commit
+ *  8. `updateComplete` promise resolves
+ *
+ * `changedProperties` is a `Map<string, unknown>` where each entry maps
+ * a property name to its previous value.
+ *
+ * MAINTAINER NOTE. Adding a new overridable lifecycle hook here means
+ * the display-only component elision analyser must learn about it too,
+ * or it will wrongly elide a component that now does client work. Add
+ * the hook name to `CLIENT_LIFECYCLE_HOOKS` in
+ * `packages/server/src/component-elision.js`. The guard test at
+ * `packages/server/test/elision/lifecycle-coverage.test.js` introspects
+ * this prototype and fails until you do.
+ *
+ * Usage:
+ * ```js
+ * import { signal } from '@webjsdev/core';
+ *
+ * const count = signal(0);
+ *
+ * class MyCounter extends WebComponent {
+ *   render() {
+ *     return html`<button @click=${() => count.set(count.get() + 1)}>${count.get()}</button>`;
+ *   }
+ * }
+ * MyCounter.register('my-counter');
+ * ```
+ */
+
+/**
+ * Helper to define properties with custom options.
+ *
+ * @param {any} [type]
+ * @param {any} [opts]
+ * @returns {any}
+ */
+export function prop(type, opts = {}) {
+  if (type && typeof type === 'object' && !('call' in type)) {
+    opts = type;
+    type = undefined;
+  }
+  return { ...(type ? { type } : {}), ...opts };
+}

package/src/component/server-element.js

@@ -0,0 +1,248 @@
+/**
+ * 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}
+ */
+export 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).
+ */
+export 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()];
+  }
+
+  /**
+   * Minimal `Element.closest()` for SSR. The SSR walker threads the chain
+   * of enclosing custom-element instances into each instance
+   * (`__ssrAncestors`); this walks self-then-ancestors and returns the
+   * nearest whose tag matches. Only bare tag-name selectors are supported
+   * server-side (`closest('ui-tabs')`), which is what compound components
+   * need to read parent state for a correct first paint; anything more
+   * specific (class, attribute, or descendant selectors) returns null,
+   * matching the pre-shim behaviour. The browser runs the real `closest()`
+   * on hydration.
+   * @param {string} selector
+   * @returns {any}
+   */
+  closest(selector) {
+    const sel = String(selector).trim().toLowerCase();
+    // Tag-name selectors only at SSR; bail (null) on anything else.
+    if (!/^[a-z][a-z0-9-]*$/.test(sel)) return null;
+    if (this.__ssrTag === sel) return this;
+    const chain = this.__ssrAncestors;
+    if (!Array.isArray(chain)) return null;
+    for (let i = chain.length - 1; i >= 0; i--) {
+      if (chain[i] && chain[i].__ssrTag === sel) return chain[i];
+    }
+    return null;
+  }
+
+  /**
+   * `HTMLElement.dataset`: a live view over the element's `data-*`
+   * attributes, backed by the SSR attribute Map. Reading / writing
+   * `el.dataset.fooBar` maps to the `data-foo-bar` attribute (camelCase
+   * to kebab-case), so a `render()` that sets `this.dataset.state = 'on'`
+   * surfaces `data-state="on"` in the SSR'd host tag instead of crashing
+   * on an undefined `dataset`.
+   * @returns {Record<string, string>}
+   */
+  get dataset() {
+    if (this.__dataset) return this.__dataset;
+    const el = this;
+    const toAttr = (p) => 'data-' + String(p).replace(/[A-Z]/g, (m) => '-' + m.toLowerCase());
+    this.__dataset = new Proxy(/** @type {Record<string,string>} */ ({}), {
+      get(_t, prop) {
+        if (typeof prop !== 'string') return undefined;
+        const v = el.getAttribute(toAttr(prop));
+        return v === null ? undefined : v;
+      },
+      set(_t, prop, value) {
+        if (typeof prop === 'string') el.setAttribute(toAttr(prop), value);
+        return true;
+      },
+      has(_t, prop) {
+        return typeof prop === 'string' && el.hasAttribute(toAttr(prop));
+      },
+      deleteProperty(_t, prop) {
+        if (typeof prop === 'string') el.removeAttribute(toAttr(prop));
+        return true;
+      },
+      ownKeys() {
+        return el.getAttributeNames()
+          .filter((n) => n.startsWith('data-'))
+          .map((n) => n.slice(5).replace(/-([a-z])/g, (_m, c) => c.toUpperCase()));
+      },
+      getOwnPropertyDescriptor(_t, prop) {
+        if (typeof prop === 'string' && el.hasAttribute(toAttr(prop))) {
+          return { enumerable: true, configurable: true, value: el.getAttribute(toAttr(prop)) };
+        }
+        return undefined;
+      },
+    });
+    return this.__dataset;
+  }
+
+  // IDL properties that reflect to a content attribute. A render() that
+  // mutates these on the host (a light-DOM compound-component pattern, e.g.
+  // `this.className = ...`, `this.hidden = !active`) then surfaces the
+  // matching attribute in the SSR'd host tag, matching the browser.
+  get className() { return this.getAttribute('class') ?? ''; }
+  set className(v) { this.setAttribute('class', v); }
+  get hidden() { return this.hasAttribute('hidden'); }
+  set hidden(v) { this.toggleAttribute('hidden', !!v); }
+  get id() { return this.getAttribute('id') ?? ''; }
+  set id(v) { this.setAttribute('id', v); }
+  get title() { return this.getAttribute('title') ?? ''; }
+  set title(v) { this.setAttribute('title', v); }
+  get slot() { return this.getAttribute('slot') ?? ''; }
+  set slot(v) { this.setAttribute('slot', v); }
+  get role() { return this.getAttribute('role'); }
+  set role(v) { v == null ? this.removeAttribute('role') : this.setAttribute('role', v); }
+  get tabIndex() { const v = this.getAttribute('tabindex'); return v === null ? -1 : (Number.parseInt(v, 10) || 0); }
+  set tabIndex(v) { this.setAttribute('tabindex', String(v)); }
+
+  // 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;
+  }
+}
+
+// ARIAMixin IDL reflections (`el.ariaPressed = 'true'` writes aria-pressed).
+// A render() that sets ARIA state via the IDL properties then surfaces the
+// matching aria-* attribute in the SSR'd host tag, matching the browser. The
+// IDL name maps to the content attribute by lowercasing the part after
+// `aria` and prefixing `aria-` (ariaPressed -> aria-pressed).
+const ARIA_IDL_PROPS = [
+  'ariaAtomic', 'ariaAutoComplete', 'ariaBusy', 'ariaChecked', 'ariaColCount',
+  'ariaColIndex', 'ariaColSpan', 'ariaCurrent', 'ariaDescription', 'ariaDisabled',
+  'ariaExpanded', 'ariaHasPopup', 'ariaHidden', 'ariaInvalid', 'ariaKeyShortcuts',
+  'ariaLabel', 'ariaLevel', 'ariaLive', 'ariaModal', 'ariaMultiLine',
+  'ariaMultiSelectable', 'ariaOrientation', 'ariaPlaceholder', 'ariaPosInSet',
+  'ariaPressed', 'ariaReadOnly', 'ariaRequired', 'ariaRoleDescription',
+  'ariaRowCount', 'ariaRowIndex', 'ariaRowSpan', 'ariaSelected', 'ariaSetSize',
+  'ariaSort', 'ariaValueMax', 'ariaValueMin', 'ariaValueNow', 'ariaValueText',
+];
+for (const idl of ARIA_IDL_PROPS) {
+  const attr = 'aria-' + idl.slice(4).toLowerCase();
+  Object.defineProperty(ServerElement.prototype, idl, {
+    configurable: true,
+    get() { return this.getAttribute(attr); },
+    set(v) { v == null ? this.removeAttribute(attr) : this.setAttribute(attr, String(v)); },
+  });
+}

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.