@webjsdev/core 0.7.64 → 0.8.0

package/index-browser.js

@@ -23,10 +23,10 @@
  * Keep this list in sync with `./index.js` for everything else.
  */
 
-export { html, isTemplate, MARKER } from './src/html.js';
+export { html, svg, isTemplate, MARKER } from './src/html.js';
 export { css, isCSS, adoptStyles, stylesToString } from './src/css.js';
 export { WebComponent, prop } from './src/component.js';
-export { register, lookup, lookupModuleUrl, isLazy, allTags, primeModuleUrl, tagOf } from './src/registry.js';
+export { lookup, lookupModuleUrl, isLazy, allTags, primeModuleUrl, tagOf } from './src/registry.js';
 export { render } from './src/render-client.js';
 export { escapeText, escapeAttr } from './src/escape.js';
 export { notFound, redirect, forbidden, unauthorized, isNotFound, isRedirect, isForbidden, isUnauthorized } from './src/nav.js';
@@ -100,3 +100,7 @@ export { createContext, ContextProvider, ContextConsumer, ContextRequestEvent }
 
 // Task controller, also available via '@webjsdev/core/task'
 export { Task, TaskStatus } from './src/task.js';
+
+export { nothing, noChange } from './src/sentinels.js';
+
+export { classMap, styleMap, ifDefined } from './src/attribute-directives.js';

package/index.d.ts

@@ -74,13 +74,13 @@ export type {
   NonSerializable,
 } from './src/serializable.d.ts';
 
-export { html, isTemplate, MARKER } from './src/html.js';
+export { html, svg, isTemplate, MARKER } from './src/html.js';
 // The `html\`\`` return type. A JSDoc typedef in html.js used across the
 // component / route / testing type surfaces; re-exported so an app or the
 // docs/website can annotate a value as `TemplateResult` (#772).
 export type { TemplateResult } from './src/html.js';
 export { css, isCSS, adoptStyles, stylesToString } from './src/css.js';
-export { register, lookup, lookupModuleUrl, isLazy, allTags, primeModuleUrl, tagOf } from './src/registry.js';
+export { lookup, lookupModuleUrl, isLazy, allTags, primeModuleUrl, tagOf } from './src/registry.js';
 export { renderToString, renderToStream } from './src/render-server.js';
 export { render } from './src/render-client.js';
 export { escapeText, escapeAttr } from './src/escape.js';
@@ -152,10 +152,14 @@ export function optimistic<State>(
 ): OptimisticState<State, State>;
 
 
-// Legacy Imperative Signature (Signal-based rollback)
+// Imperative signature (signal-based rollback)
 export function optimistic<T, R>(
   signal: { get(): T; set(v: T): void },
   value: T,
   action: () => Promise<R> | R,
 ): Promise<R>;
 
+
+export { nothing, noChange } from './src/sentinels.js';
+
+export { classMap, styleMap, ifDefined } from './src/attribute-directives.js';

package/index.js

@@ -6,10 +6,10 @@
  * renderer is only reached on the server.
  */
 
-export { html, isTemplate, MARKER } from './src/html.js';
+export { html, svg, isTemplate, MARKER } from './src/html.js';
 export { css, isCSS, adoptStyles, stylesToString } from './src/css.js';
 export { WebComponent, prop } from './src/component.js';
-export { register, lookup, lookupModuleUrl, isLazy, allTags, primeModuleUrl, tagOf } from './src/registry.js';
+export { lookup, lookupModuleUrl, isLazy, allTags, primeModuleUrl, tagOf } from './src/registry.js';
 export { renderToString, renderToStream } from './src/render-server.js';
 export { render } from './src/render-client.js';
 export { escapeText, escapeAttr } from './src/escape.js';
@@ -68,3 +68,7 @@ export { createContext, ContextProvider, ContextConsumer, ContextRequestEvent }
 
 // Task controller, also available via '@webjsdev/core/task'
 export { Task, TaskStatus } from './src/task.js';
+
+export { nothing, noChange } from './src/sentinels.js';
+
+export { classMap, styleMap, ifDefined } from './src/attribute-directives.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/core",
-  "version": "0.7.64",
+  "version": "0.8.0",
   "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-directives.d.ts

@@ -0,0 +1,6 @@
+import { nothing } from './sentinels.js';
+export interface ClassMapDirective { readonly _$webjs: 'class-map'; readonly value: Record<string, unknown>; }
+export interface StyleMapDirective { readonly _$webjs: 'style-map'; readonly value: Record<string, string | number | null | undefined>; }
+export function classMap(classes: Record<string, unknown>): ClassMapDirective;
+export function styleMap(styles: Record<string, string | number | null | undefined>): StyleMapDirective;
+export function ifDefined<T>(value: T): NonNullable<T> | typeof nothing;

package/src/attribute-directives.js

@@ -0,0 +1,49 @@
+import { nothing } from './sentinels.js';
+
+/** Map class names to whether each should be present. @param {Record<string, unknown>} classes */
+export function classMap(classes) { return { _$webjs: 'class-map', value: classes }; }
+/** Map CSS property names to their values. @param {Record<string, string | number | null | undefined>} styles */
+export function styleMap(styles) { return { _$webjs: 'style-map', value: styles }; }
+/** Remove an attribute when its value is nullish. @template T @param {T} value */
+export function ifDefined(value) { return value ?? nothing; }
+
+export function isAttributeMap(value) {
+  return value && (value._$webjs === 'class-map' || value._$webjs === 'style-map');
+}
+export function cssName(name) { return name.startsWith('--') ? name : name.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase()); }
+export function attributeMapText(value, name) {
+  const classes = value._$webjs === 'class-map';
+  if (name !== (classes ? 'class' : 'style')) throw new Error('classMap/styleMap must be used in a class/style attribute.');
+  // Lit deliberately pads even an empty map to separate adjacent static classes.
+  return classes
+    ? ' ' + Object.keys(value.value).filter((key) => value.value[key]).join(' ') + ' '
+    : Object.entries(value.value).filter(([, v]) => v != null).map(([key, v]) => `${cssName(key)}:${v};`).join('');
+}
+
+/** Commit only the map-owned tokens, preserving static and externally added values. */
+export function applyAttributeMap(part, value) {
+  if (part.kind !== 'attr' && part.kind !== 'attr-mixed') throw new Error('classMap/styleMap require an attribute binding.');
+  const classes = value._$webjs === 'class-map';
+  if (part.name !== (classes ? 'class' : 'style')) throw new Error('classMap/styleMap must be used in a class/style attribute.');
+  if (part.group && part.group.length !== 1) throw new Error('classMap/styleMap require a single expression.');
+  if (part.__mapKind !== value._$webjs) {
+    part.el.setAttribute(part.name, (part.statics || []).join(classes ? ' ' : ''));
+    part.__mapKind = value._$webjs;
+    part.__mapKeys = new Set();
+    part.__staticClasses = classes ? new Set(part.el.classList) : new Set();
+  }
+  const next = new Set();
+  for (const [key, v] of Object.entries(value.value)) {
+    if (classes) {
+      if (v && !part.__staticClasses.has(key)) { part.el.classList.add(key); next.add(key); }
+    } else if (v != null) {
+      const name = cssName(key); const text = String(v);
+      part.el.style.setProperty(name, text.replace(/\s*!important\s*$/, ''), /!important\s*$/.test(text) ? 'important' : '');
+      next.add(name);
+    }
+  }
+  for (const key of part.__mapKeys) if (!next.has(key)) {
+    if (classes) part.el.classList.remove(key); else part.el.style.removeProperty(key);
+  }
+  part.__mapKeys = next;
+}

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.
  *
@@ -110,7 +124,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
@@ -130,7 +144,7 @@ function hyphenate(s) {
  * 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`
@@ -212,11 +226,31 @@ export function observedAttributeNames(Cls) {
  * @returns {{ propName: string, def: PropertyDeclaration, primary: string, alias: string | undefined }[]}
  */
 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.
+  if (Cls && typeof Cls === 'function') {
+    const hit = BACKED_PROPS.get(Cls);
+    if (hit) return hit;
+    const built = buildAttributeBackedProps(Cls);
+    BACKED_PROPS.set(Cls, built);
+    return built;
+  }
+  return buildAttributeBackedProps(Cls);
+}
+
+/** @type {WeakMap<Function, { propName: string, def: any, primary: string, alias: string | undefined }[]>} */
+const BACKED_PROPS = new WeakMap();
+
+function buildAttributeBackedProps(Cls) {
   const props = (Cls && Cls.properties) || {};
   const out = [];
   for (const [k, decl] of Object.entries(props)) {
     const d = typeof decl === 'object' && decl !== null ? decl : { type: decl };
-    if (d.state) continue;
+    if (!isAttributeBacked(d)) continue;
     const primary = d.attribute || hyphenate(k);
     const lower = k.toLowerCase();
     const alias = !d.attribute && lower !== primary ? lower : undefined;

package/src/binding-prefixes.js

@@ -1,3 +1,4 @@
+import { nothing, noChange } from './sentinels.js';
 /**
  * The template attribute-binding prefixes the renderers recognise.
  *
@@ -42,48 +43,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 ?? '');
 }