@webjsdev/core 0.7.65 → 0.9.0

package/src/render-server/walk.js

@@ -1,3 +1,5 @@
+import { isAttributeMap, attributeMapText } from '../attribute-directives.js';
+import { nothing, noChange } from '../sentinels.js';
 import { isTemplate } from '../html.js';
 import { attrHoleValue } from '../binding-prefixes.js';
 import { escapeText, escapeAttr } from '../escape.js';
@@ -10,6 +12,8 @@ import {
   isSubmitterReflectedProp, FORM_ACTION_FIELD,
 } from '../form-action.js';
 import { isRepeat } from '../repeat.js';
+import { isDirectiveResult, PartType } from '../directive.js';
+import { isSignal } from '../signal.js';
 import { isSuspense } from '../suspense.js';
 import { isUnsafeHTML, isLive, isKeyed, isGuard, isTemplateContent, isRef, isCache, isUntil, isAsyncAppend, isAsyncReplace, isWatch } from '../directives.js';
 import { stringify } from '../serialize.js';
@@ -81,6 +85,8 @@ export class Walker {
     this.defer = 0;
     /** @type {any} */
     this.tagState = null;
+    /** How many component templates (render / renderError) are being walked. */
+    this.componentDepth = 0;
   }
 
   // -------------------------------------------------------------------------
@@ -163,7 +169,11 @@ export class Walker {
    * @param {unknown} value
    */
   async value(value) {
-    if (value == null || value === false || value === true) return;
+    if (isDirectiveResult(value)) value = resolveDirective(value, CHILD_PART);
+    // A bare `${signal}` renders its current value (the client binds the hole
+    // to the signal so it updates in place, as `watch()` does).
+    if (isSignal(value)) value = /** @type any */ (value).get();
+    if (value == null || value === nothing || value === noChange) return;
     if (typeof (/** @type any */ (value).then) === 'function') {
       return this.value(await value);
     }
@@ -173,6 +183,14 @@ export class Walker {
       for (const v of value) await this.value(v);
       return;
     }
+    // Any other iterable renders like an array, as in lit: a generator from
+    // `map()` / `join()` / `range()`, a Set, a Map's values. A string is
+    // iterable too and was handled above, and every directive marker is a
+    // plain object with no iterator, so none of them reaches this branch.
+    if (typeof value === 'object' && typeof (/** @type any */ (value))[Symbol.iterator] === 'function') {
+      for (const v of /** @type {Iterable<unknown>} */ (value)) await this.value(v);
+      return;
+    }
     // An unsafeHTML value is raw markup. With expansion on, the components it
     // carries render too (the output rescan used to find them), through the
     // same tokenizer the template went through, so a tag written inside one
@@ -242,6 +260,12 @@ export class Walker {
 
   /** @param {import('../html.js').TemplateResult} tr */
   async template(tr) {
+    // Only a tagged template's strings carry `raw`, so a result that arrived as
+    // data (JSON with the `_$webjs` brand) is refused rather than rendered as
+    // markup, as the client renderer and lit's `trustFromTemplateString` do.
+    if (!Array.isArray(tr.strings) || !Object.prototype.hasOwnProperty.call(tr.strings, 'raw')) {
+      throw new Error("[webjs] refusing to render a template result whose strings are not a tagged template's (a TemplateResult built from data, not by html``).");
+    }
     await this.ops(compile(tr.strings), tr.values);
     this.flush();
   }
@@ -300,8 +324,46 @@ export class Walker {
               await this.attr(op, val);
               break;
             case VALUE:
+              if (op.quote) {
+                // Resolve the complete attribute before emitting any of it so a
+                // sentinel in any expression can omit the entire attribute.
+                this.buf = this.buf.slice(0, -op.prefix.length);
+                let attribute = op.prefix;
+                let omitted = false;
+                let piece = val;
+                for (let j = i; j < ops.length; j++) {
+                  const next = ops[j];
+                  if (next.t === HOLE) {
+                    if (j !== i) {
+                      piece = values[vi++];
+                      if (piece && typeof piece.then === 'function') piece = await piece;
+                      if (isLive(piece)) piece = piece.value;
+                    }
+                    piece = await attrValueOf(piece);
+                    if (isDirectiveResult(piece)) piece = resolveDirective(piece, { type: PartType.ATTRIBUTE, name: op.name, tagName: op.tag?.toUpperCase() });
+                    if (isSignal(piece) || isWatch(piece)) piece = signalValue(piece);
+                    if (isAttributeMap(piece)) piece = attributeMapText(piece, op.name);
+                    assertNotFunctionActionAttr(piece, op.name, op.tag);
+                    if (piece === nothing) omitted = true;
+                    attribute += piece === nothing || piece === noChange ? '' : escapeAttr(String(piece ?? ''));
+                  } else if (next.t === TEXT) {
+                    const close = next.s.indexOf(op.quote);
+                    if (close >= 0) {
+                      if (!omitted) this.buf += attribute + next.s.slice(0, close + 1);
+                      this.buf += next.s.slice(close + 1);
+                      i = j;
+                      break;
+                    }
+                    attribute += next.s;
+                  }
+                }
+                break;
+              }
               // A hole inside a quoted/unquoted value, the `action="${fn}"` and
               // mixed `action="/x/${fn}"` shapes (#1154).
+              val = await attrValueOf(val);
+              if (isDirectiveResult(val)) val = resolveDirective(val, { type: PartType.ATTRIBUTE, name: op.name, tagName: op.tag?.toUpperCase() });
+              if (isSignal(val) || isWatch(val)) val = signalValue(val);
               assertNotFunctionActionAttr(val, op.name, op.tag);
               this.buf += escapeAttr(String(val ?? ''));
               break;
@@ -317,6 +379,8 @@ export class Walker {
   // -------------------------------------------------------------------------
   // Start tags
   // -------------------------------------------------------------------------
+  // (attrValueOf, the attribute-position unwrap of the value-carrying
+  // built-in directives, is a module function below.)
 
   /** @param {string} tag */
   open(tag) {
@@ -366,11 +430,32 @@ export class Walker {
    * @param {unknown} val
    */
   async attr(op, val) {
+    if (op.kind !== 'event') val = await attrValueOf(val);
+    // A custom directive renders its `render()` result at SSR (lit's server
+    // rule: `update()` needs a DOM). An event part is client-only, so its
+    // directive never runs here.
+    if (isDirectiveResult(val) && op.kind !== 'event') {
+      const type = op.kind === 'prop' ? PartType.PROPERTY : op.kind === 'bool' ? PartType.BOOLEAN_ATTRIBUTE : PartType.ATTRIBUTE;
+      val = resolveDirective(val, { type, name: op.name, tagName: op.tag?.toUpperCase() });
+    }
+    // A bare signal in an attribute or boolean hole renders its current value;
+    // a `.prop` hole hands the signal object itself to the property, as lit's
+    // signals package does.
+    if ((isSignal(val) || isWatch(val)) && (op.kind === 'plain' || op.kind === 'bool')) val = signalValue(val);
+    if (isAttributeMap(val)) {
+      if (op.kind !== 'plain') throw new Error('classMap/styleMap require an attribute binding.');
+      val = attributeMapText(val, op.name);
+    }
+    if (val === noChange) return;
+    if (val === nothing && op.kind === 'prop') val = undefined;
     const ts = this.tagState;
     const name = /** @type string */ (op.name);
     const tag = /** @type string */ (op.tag);
     if (op.kind === 'event') {
-      // An event listener is client-only behaviour, dropped at SSR.
+      // An event listener is client-only behaviour, dropped at SSR. Outside
+      // any component template it can never run either: a page or layout
+      // never hydrates. Dev makes that a render error naming the fix.
+      if (this.dev && this.componentDepth === 0) throw new Error(pageBindingError(true, name, tag));
       return;
     }
     if (op.kind === 'prop') {
@@ -384,6 +469,9 @@ export class Walker {
         return;
       }
       if (!tag.includes('-')) {
+        if (this.dev && this.componentDepth === 0 && !isReflectedFormProp(name, tag)) {
+          throw new Error(pageBindingError(false, name, tag));
+        }
         // A native element's `.prop` is dropped at SSR. It still refuses a
         // function where the property is a REFLECTED IDL attribute (`.action`
         // on a form, `.formAction` on a button or input), and records the
@@ -412,7 +500,7 @@ export class Walker {
       // `?action=${fn}` is meaningless in every case; refusing it keeps the
       // rule true for every sigil rather than only the quoted ones.
       assertNotFunctionActionAttr(val, name, tag);
-      if (val) this.buf += `${name}=""`;
+      if (val && val !== nothing) this.buf += `${name}=""`;
       return;
     }
     // A plain `name=${value}` hole.
@@ -424,7 +512,7 @@ export class Walker {
         // page's own url; the identity is remembered for the `>`. Trailing
         // whitespace goes with the attribute, since every injected attribute
         // carries its own leading space.
-        if (ts) ts.actionId = assertIdentifiableAction(await resolveFormActionId(val), tag);
+        if (ts) ts.actionId = assertIdentifiableAction(await resolveFormActionId(val), tag, val);
         this.buf = this.buf.replace(/\s+$/, '');
       } else {
         // #1207, the submitter binding. The identity replaces the
@@ -435,7 +523,7 @@ export class Walker {
         if (attrs.has('name')) assertSubmitterHasNoName(attrs.get('name') || '', tag, false);
         if (attrs.has('value')) assertSubmitterHasNoValue(tag);
         if (attrs.has('form')) assertSubmitterHasNoFormAttribute(tag);
-        const subId = assertIdentifiableAction(await resolveFormActionId(val), tag);
+        const subId = assertIdentifiableAction(await resolveFormActionId(val), tag, val);
         if (ts) ts.submitterTag = tag;
         this.buf += `name="${FORM_ACTION_FIELD}" value="${escapeAttr(subId)}"`;
       }
@@ -686,6 +774,37 @@ export class Walker {
 
 const EMPTY = Object.freeze([]);
 
+/**
+ * The current value of a bare signal or a `watch(signal)` marker in an
+ * attribute-shaped hole (SSR reads it once; the client binds the hole).
+ * @param {any} v
+ */
+function signalValue(v) {
+  return isWatch(v) ? v.signal.get() : v.get();
+}
+
+/** The part info every child-position directive is constructed with. */
+const CHILD_PART = Object.freeze({ type: PartType.CHILD });
+
+/**
+ * Resolve a custom directive result (`directive(C)(...values)`) to the value
+ * it renders, lit's server rule: construct the class with the part info and
+ * call `render(...values)` (never `update()`, which needs a DOM). A directive
+ * that returns another directive resolves in turn. A fresh instance per
+ * render is right here, since an SSR render is one shot.
+ * @param {any} value
+ * @param {{ type: number, name?: string, tagName?: string }} partInfo
+ * @returns {unknown}
+ */
+function resolveDirective(value, partInfo) {
+  for (let depth = 0; isDirectiveResult(value); depth++) {
+    if (depth > 100) throw new Error('[webjs] a custom directive kept returning directives (more than 100 levels deep).');
+    const instance = new value.ctor(partInfo);
+    value = instance.render(...value.values);
+  }
+  return value;
+}
+
 /**
  * #1155: a `.method` / `.enctype` / `.encoding` prop on a form is dropped at
  * SSR but applied for real in the browser, where all three are reflected IDL
@@ -756,3 +875,56 @@ export async function streamValue(value, ctx, controller) {
   await w.value(value);
   w.flush();
 }
+
+/**
+ * A form-shape property the dedicated form guards judge (and refuse with a
+ * more specific message), so the page-binding error leaves it to them.
+ * @param {string} name
+ * @param {string} tag
+ */
+function isReflectedFormProp(name, tag) {
+  return /^(?:action|method|enctype|encoding|formaction|formmethod|formenctype)$/i.test(name)
+    && /^(?:form|button|input)$/.test(tag);
+}
+
+/**
+ * The dev error for an `@event` or native `.prop` binding in a template no
+ * component renders (a page or layout, which never hydrates).
+ * @param {boolean} isEvent an `@event` listener (else a `.prop` binding)
+ * @param {string} name
+ * @param {string} tag
+ */
+function pageBindingError(isEvent, name, tag) {
+  const what = isEvent ? `an \`@${name}\` event listener` : `a \`.${name}\` property binding`;
+  return `webjs: ${what} on <${tag}> in a page or layout template. Pages and layouts render only on the server and never hydrate, so it is dropped and never runs. `
+    + `Move the interactive markup into a WebComponent and render its tag from the page (its render() hydrates in the browser)`
+    + (!isEvent ? ', or write a plain attribute (\`' + name.toLowerCase() + '=${value}\`) when the value only needs to reach the HTML' : '')
+    + '. This check runs in dev only. See https://webjs.dev/docs/troubleshooting#binding-in-page-template';
+}
+
+/**
+ * The value a value-carrying built-in directive stands for in an ATTRIBUTE,
+ * property or boolean position, as in Lit (#1686): `guard` renders its
+ * callback's result, `until` its first non-promise argument (else the first
+ * promise to settle, a rejection reading as no value), `keyed` and `cache`
+ * their value. A child position unwraps these in `value()`; an attribute hole
+ * used to stringify the directive object to "[object Object]".
+ * @param {unknown} v
+ * @returns {Promise<unknown>}
+ */
+async function attrValueOf(v) {
+  for (let depth = 0; depth < 8; depth++) {
+    /** @type any */
+    const d = v;
+    if (isGuard(d)) v = d.fn();
+    else if (isKeyed(d) || isCache(d)) v = d.value;
+    else if (isLive(d)) v = d.value;
+    else if (isUntil(d)) {
+      const sync = d.args.find((a) => !a || typeof a.then !== 'function');
+      if (sync !== undefined || d.args.some((a) => !a || typeof a.then !== 'function')) v = sync;
+      else if (d.args.length) v = await Promise.race(d.args.map((p) => Promise.resolve(p).catch(() => undefined)));
+      else v = undefined;
+    } else return v;
+  }
+  return v;
+}

package/src/render-server.d.ts

@@ -12,3 +12,6 @@ export function renderToStream(
   value: unknown,
   opts?: { ssr?: boolean; suspenseCtx?: SuspenseContext },
 ): ReadableStream;
+/** A React-ism in an html template's static strings: `className=` / `htmlFor=` or a capitalised tag. */
+export function findJsxIsm(strings: readonly string[]): { kind: 'attr' | 'tag'; name: string } | null;
+export function jsxIsmMessage(ism: { kind: 'attr' | 'tag'; name: string }): string;

package/src/render-server.js

@@ -4,3 +4,5 @@
 // backs the published `@webjsdev/core/server` subpath, so re-exporting it would
 // widen the package's public API for a helper no consumer asked for.
 export { renderToString, renderToStream } from './render-server/stream.js';
+// The JSX-in-template scan, shared with `webjs check` (`no-jsx-attributes`).
+export { findJsxIsm, jsxIsmMessage } from './jsx-guard.js';

package/src/repeat.d.ts

@@ -3,13 +3,18 @@
 // exported, so it cannot be named, and no consumer constructs one by hand.
 export interface RepeatDirective<T> {
   items: T[];
-  keyFn: (item: T, i: number) => string | number;
+  keyFn: (item: T, i: number) => unknown;
   templateFn: (item: T, i: number) => unknown;
 }
 
 export function repeat<T>(
   items: Iterable<T>,
-  keyFn: (item: T, i: number) => string | number,
+  keyFn: (item: T, i: number) => unknown,
+  templateFn: (item: T, i: number) => unknown,
+): RepeatDirective<T>;
+/** lit's two-argument form: no key function, so each item is keyed by its index. */
+export function repeat<T>(
+  items: Iterable<T>,
   templateFn: (item: T, i: number) => unknown,
 ): RepeatDirective<T>;
 export function isRepeat(x: unknown): x is RepeatDirective<unknown>;

package/src/repeat.js

@@ -7,8 +7,10 @@
  * html`<ul>${repeat(items, (it) => it.id, (it) => html`<li>${it.title}</li>`)}</ul>`;
  * ```
  *
- * Without `repeat()`, an array re-render rebuilds every child (losing focus,
- * selection, and scroll). With `repeat()`, the client renderer maintains a
+ * Without `repeat()`, an array updates positionally: the DOM for item N is
+ * reused for whatever is now at index N, so focus, selection and component
+ * state follow the position, not the item. With `repeat()`, the client
+ * renderer maintains a
  * `Map<key, TemplateInstance>`: matched items update in place, new items
  * mount fresh, removed items unmount, and the surviving DOM nodes are moved
  * (not recreated) when the order changes.
@@ -16,19 +18,31 @@
  * Keys must be stable and unique within the call. Bad keys (array indices)
  * defeat the purpose; prefer a stable id from the data.
  *
+ * The two-argument form, `repeat(items, (it) => html`...`)`, is lit's too: with
+ * no key function each item is keyed by its INDEX, which makes it a plain
+ * positional list (no DOM moves on reorder). Pass a key function whenever item
+ * identity has to follow the data.
+ *
  * On the server this marker is just iterated: order matters, keys don't.
  */
 
 const REPEAT = Symbol.for('webjs.repeat');
 
+/** The key of an item `repeat(items, template)` was given no key function for. */
+const indexKey = (/** @type {unknown} */ _item, /** @type {number} */ i) => i;
+
 /**
  * @template T
  * @param {Iterable<T>} items
- * @param {(item: T, i: number) => string | number} keyFn
- * @param {(item: T, i: number) => unknown} templateFn
+ * @param {((item: T, i: number) => unknown)} keyFnOrTemplate the key function,
+ *   or, when `templateFn` is omitted, the template function (lit's two-argument form)
+ * @param {(item: T, i: number) => unknown} [templateFn]
  */
-export function repeat(items, keyFn, templateFn) {
-  return { [REPEAT]: true, items: [...items], keyFn, templateFn };
+export function repeat(items, keyFnOrTemplate, templateFn) {
+  if (templateFn === undefined) {
+    return { [REPEAT]: true, items: [...items], keyFn: indexKey, templateFn: keyFnOrTemplate };
+  }
+  return { [REPEAT]: true, items: [...items], keyFn: keyFnOrTemplate, templateFn };
 }
 
 /** @param {unknown} x */

package/src/router-client/anchors.js

@@ -37,8 +37,10 @@ export function closestAnchor(target) {
       const a = el.closest && el.closest('a');
       if (a instanceof HTMLAnchorElement) return a;
     }
+    // Only a real ShadowRoot has a host to cross to (a detached subtree's
+    // root can be an <a>, whose `host` is a URL string).
     const root = node.getRootNode ? node.getRootNode() : null;
-    node = root && /** @type any */ (root).host ? /** @type any */ (root).host : null;
+    node = typeof ShadowRoot !== 'undefined' && root instanceof ShadowRoot ? root.host : null;
   }
   return null;
 }

package/src/router-client/boundaries.js

@@ -159,6 +159,20 @@ export function collectBoundaries(root) {
  *   live: { routeKey: string, start: Comment, end: Comment },
  *   incoming: { routeKey: string, start: Comment, end: Comment } } | null}
  */
+/**
+ * Does segment `inner` sit at or below segment `outer`. Boundary segments are
+ * nested path prefixes, so `/ui/docs` is within `/ui` and within `/`, and
+ * `/uix` is within neither `/ui` nor `/ui/docs`. The one statement of the
+ * nesting rule: the swap plan below and the stylesheet ownership in
+ * owned-styles.js both use it, so they cannot disagree about which range a
+ * segment belongs to.
+ * @param {string} inner
+ * @param {string} outer
+ */
+export function segmentWithin(inner, outer) {
+  return inner === outer || inner.startsWith(outer === '/' ? '/' : outer + '/');
+}
+
 export function planBoundarySwap(here, there) {
   // Shared segments, shallowest first (a nested path prefix is shorter).
   const shared = [...here.keys()].filter((s) => there.has(s)).sort((a, b) => a.length - b.length);
@@ -169,7 +183,7 @@ export function planBoundarySwap(here, there) {
       let parent = null;
       for (const p of shared) {
         if (p === seg) break;
-        if (seg.startsWith(p === '/' ? p : p + '/')) parent = p;
+        if (seg !== p && segmentWithin(seg, p)) parent = p;
       }
       if (!parent) return null; // no anchored parent: degrade
       return { mode: 'replace', segment: parent, live: here.get(parent), incoming: there.get(parent) };

package/src/router-client/constants.js

@@ -204,3 +204,33 @@ export function _isNonHtmlPath(pathname) {
  * alone rather than reverted.
  */
 export const WRITE_BACK_ARMED_MS = 250;
+
+/**
+ * Marks the router's temporary stylesheet copies (`stylesheets.js`). Here,
+ * in the leaf module, so `owned-styles.js` can skip those copies without
+ * importing `stylesheets.js`, which imports `head-merge.js`, which imports
+ * `owned-styles.js`.
+ */
+export const PRELOAD_ATTR = 'data-webjs-preload-style';
+
+/**
+ * Does `el`'s `rel` name a stylesheet that applies (`stylesheet`, not
+ * `alternate`). The one test both the stylesheet loader (`stylesheets.js`) and
+ * the owned-sheet merge (`owned-styles.js`) use, so the two cannot disagree.
+ * @param {Element} el
+ */
+export function relIsStylesheet(el) {
+  const rel = relTokens(el);
+  return rel.includes('stylesheet') && !rel.includes('alternate');
+}
+
+/**
+ * The lowercased tokens of `el`'s `rel`, the one parse every stylesheet test
+ * in the router builds on (`relIsStylesheet` here, and the head merge's
+ * never-remove rule, which counts an alternate stylesheet too).
+ * @param {Element} el
+ * @returns {string[]}
+ */
+export function relTokens(el) {
+  return (el.getAttribute('rel') || '').toLowerCase().split(/\s+/);
+}

package/src/router-client/dom-differ.js

@@ -224,9 +224,25 @@ export function diffElementInPlace(dst, src) {
   }
   // Update attributes from src; remove ones not in src.
   const srcAttrs = new Set();
+  // A server-passed `.prop` binding on a reused, upgraded component (#1686):
+  // its `data-webjs-prop-*` attribute was read once at upgrade and stripped,
+  // so writing the new value as an attribute changed nothing and the property
+  // stayed stale after a same-page update. A binding whose value changed is
+  // handed to the component to decode; an unchanged one is left alone, so a
+  // value the component changed locally survives, as in Lit.
+  const hydrated = isHydratedComponent(dst) && typeof (/** @type any */ (dst))._hydratePropAttrs === 'function';
+  let propsChanged = false;
   for (const attr of src.attributes) {
     srcAttrs.add(attr.name);
     if (LIVE_ATTRS.has(attr.name)) continue;
+    if (hydrated && attr.name.startsWith('data-webjs-prop-')) {
+      const seen = /** @type any */ (dst).__webjsPropAttrValues;
+      if (!seen || seen.get(attr.name) !== attr.value) {
+        dst.setAttribute(attr.name, attr.value);
+        propsChanged = true;
+      }
+      continue;
+    }
     // The serialized-restore stamp is a message to a NOT-YET-UPGRADED
     // element's connectedCallback; copying it onto a live reused host would
     // leave a consume-once marker lingering in the live DOM forever. Note
@@ -243,6 +259,7 @@ export function diffElementInPlace(dst, src) {
     if (LIVE_ATTRS.has(attr.name)) continue;
     if (!srcAttrs.has(attr.name)) dst.removeAttribute(attr.name);
   }
+  if (propsChanged) /** @type any */ (dst)._hydratePropAttrs();
   // For form-control-like elements, preserve live IDL state.
   // (`value`, `checked`, `open`, etc.: see LIVE_ATTRS below for full list.)
   // The attribute version is skipped above; we deliberately do nothing