@webjsdev/core 0.7.28 → 0.7.30

package/index.d.ts

@@ -65,6 +65,10 @@ export type {
 } from './src/serializable.d.ts';
 
 export { html, 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 { renderToString, renderToStream } from './src/render-server.js';
@@ -113,11 +117,33 @@ export { stringify, parse, serialize, deserialize } from './src/serialize.js';
 export { WebjsFrame } from './src/webjs-frame.js';
 export { WebjsStream, renderStream } from './src/webjs-stream.js';
 
-// Optimistic-mutation helper: set a signal to an expected value immediately,
-// run the action, roll back on a thrown error or a `{ success: false }`
-// ActionResult, keep the value on success. Returns the action's result.
+export interface OptimisticState<State, Action> {
+  readonly value: State;
+  add(payload: Action, promise?: Promise<any> | any): () => void;
+}
+
+// Declarative Signature with custom update reducer
+export function optimistic<State, Action>(
+  host: { requestUpdate?(): void },
+  options: {
+    source: () => State;
+    update: (state: State, action: Action) => State;
+  }
+): OptimisticState<State, Action>;
+
+// Declarative Signature with default replace reducer (Action = State)
+export function optimistic<State>(
+  host: { requestUpdate?(): void },
+  options: {
+    source: () => State;
+  }
+): OptimisticState<State, State>;
+
+
+// Legacy 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>;
+

package/package.json

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

package/src/binding-prefixes.js

@@ -0,0 +1,42 @@
+/**
+ * The template attribute-binding prefixes the renderers recognise.
+ *
+ * A binding hole whose attribute name starts with one of these is NOT a
+ * plain attribute: `@event` is a client event listener (dropped at SSR,
+ * wired only after hydration), `.prop` is a DOM property, `?bool` a
+ * boolean attribute. This object is the SINGLE source of truth for that
+ * set: both the client renderer (`render-client.js`) and the server
+ * renderer (`render-server.js`, two sites) read it instead of hardcoding
+ * the prefix characters inline.
+ *
+ * It is also the anchor for the elision drift guard. The analyser
+ * (`packages/server/src/component-elision.js`) classifies every prefix as
+ * either a client-behaviour ship signal (it drops at SSR and implies the
+ * component does client work, so a component using it must ship) or an
+ * SSR-safe round-trip (it survives into the served HTML, so it is not a
+ * ship signal). The guard test
+ * (`packages/server/test/elision/sigil-coverage.test.js`) asserts that
+ * classification covers EXACTLY these keys, so a new prefix cannot be
+ * added here without the analyser being taught which kind it is. That
+ * closes the one gap the prototype-introspection guard
+ * (`lifecycle-coverage.test.js`) cannot reach, because a sigil is syntax,
+ * not a prototype method or a named export.
+ *
+ * @type {Readonly<Record<string, 'event' | 'prop' | 'bool'>>}
+ */
+export const BINDING_PREFIXES = Object.freeze({
+  '@': 'event',
+  '.': 'prop',
+  '?': 'bool',
+});
+
+/**
+ * True if `ch` is a recognised binding prefix. A single-character string is
+ * expected (the first char of an attribute name).
+ *
+ * @param {string} ch
+ * @returns {boolean}
+ */
+export function isBindingPrefix(ch) {
+  return Object.prototype.hasOwnProperty.call(BINDING_PREFIXES, ch);
+}

package/src/component.js

@@ -573,7 +573,7 @@ class WebComponentBase extends Base {
             `properties via the factory instead: \`class ${name} extends WebComponent({ ` +
             `count: Number })\`. Use the \`prop()\` helper for options ` +
             `(\`prop(Number, { reflect: true })\`) and set defaults in the ` +
-            `constructor after \`super()\`. See https://docs.webjs.com/docs/components.`,
+            `constructor after \`super()\`. See https://docs.webjs.dev/docs/components.`,
         );
       }
       C = Object.getPrototypeOf(C);

package/src/optimistic.js

@@ -1,64 +1,120 @@
-/**
- * `optimistic(signal, value, action)`, a thin optimistic-mutation helper.
- *
- * The optimistic-UI pattern: show the expected result of a mutation
- * IMMEDIATELY (so the interface feels instant), run the real server action,
- * and roll the optimistic value back if the action fails. This wrapper does
- * exactly that and nothing more, no state machine, no extra reactivity, just
- * the existing signal primitive plus a try / envelope check.
- *
- *   import { signal, optimistic } from '@webjsdev/core';
- *   import { likePost } from '../actions/like-post.server.js';
- *
- *   const liked = signal(false);
- *   // In an @click handler:
- *   await optimistic(liked, true, () => likePost(postId));
- *   // `liked` flips to true instantly; if likePost throws or returns
- *   // { success: false }, it rolls back to its prior value.
- *
- * Behaviour:
- *   1. Capture `prev = signal.get()`.
- *   2. `signal.set(value)` so the UI updates before the round-trip.
- *   3. `await action()`.
- *   4a. The action THROWS  -> `signal.set(prev)` (rollback) + re-throw.
- *   4b. The action returns an ActionResult FAILURE envelope
- *       (`result && result.success === false`) -> `signal.set(prev)`
- *       (rollback) + return the result (the caller reads its
- *       `error` / `fieldErrors`).
- *   4c. SUCCESS (anything else) -> keep the optimistic value + return the
- *       result. The caller can reconcile to the authoritative value from the
- *       returned result if it wants to (e.g. `signal.set(result.data.count)`).
- *
- * It rolls back on a thrown error OR a `{ success: false }` ActionResult, and
- * never rolls back on success. Client-only: it mutates a signal (client work),
- * so a component importing it is never elided as display-only.
- *
- * @template T
- * @param {{ get: () => T, set: (v: T) => void }} signal  A webjs signal.
- * @param {T} value  The optimistic value to show immediately.
- * @param {() => Promise<any> | any} action  The server-action call (or any
- *   thunk returning a Promise / value).
- * @returns {Promise<any>}  The action's result. On a `{ success: false }`
- *   envelope the rolled-back result is returned (not thrown); a thrown action
- *   re-throws after rollback.
- */
-export async function optimistic(signal, value, action) {
+class OptimisticState {
+  constructor(host, options) {
+    this.host = host;
+    this.options = options;
+    this.updates = [];
+    this._nextId = 0;
+  }
+
+  get value() {
+    let current = this.options.source();
+    if (!this.options.update) {
+      return this.updates.length > 0
+        ? this.updates[this.updates.length - 1].payload
+        : current;
+    }
+    for (const update of this.updates) {
+      current = this.options.update(current, update.payload);
+    }
+    return current;
+  }
+
+  add(payload, promise) {
+    const id = `opt-${++this._nextId}`;
+    this.updates.push({ id, payload });
+    this.host?.requestUpdate?.();
+
+    const release = () => {
+      const idx = this.updates.findIndex(u => u.id === id);
+      if (idx !== -1) {
+        this.updates.splice(idx, 1);
+        this.host?.requestUpdate?.();
+      }
+    };
+
+    if (promise && typeof promise.then === 'function') {
+      if (typeof promise.finally === 'function') {
+        promise.finally(() => release()).catch(() => {});
+      } else {
+        promise.then(() => release(), () => release());
+      }
+    }
+
+    return release;
+  }
+}
+
+async function runLegacyOptimistic(signal, value, action) {
   const prev = signal.get();
   signal.set(value);
   let result;
   try {
     result = await action();
   } catch (err) {
-    // The action rejected: roll the optimistic value back and let the caller
-    // handle the error (re-throw, do not swallow).
     signal.set(prev);
     throw err;
   }
-  // ActionResult FAILURE envelope: a `{ success: false }` is a handled
-  // failure, not a throw. Roll back and hand the result back so the caller
-  // can read its `error` / `fieldErrors`.
   if (result && result.success === false) {
     signal.set(prev);
   }
   return result;
 }
+
+/**
+ * `optimistic(host, options)`, a React 19 / Next.js-style declarative
+ * optimistic-state wrapper for Web Components.
+ *
+ * The optimistic-UI pattern: show the expected result of a mutation
+ * IMMEDIATELY (so the interface feels instant), run the real server action,
+ * and release the optimistic overlay when the action settles. This wrapper
+ * manages a queue of pending updates, computes the combined value through
+ * an optional reducer, and auto-releases when a passed promise resolves.
+ *
+ *   import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
+ *   import { createTodo } from '../actions/create-todo.server.js';
+ *
+ *   class TodoList extends WebComponent({ todos: prop(Array) }) {
+ *     optimisticTodos = optimistic(this, {
+ *       source: () => this.todos,
+ *       update: (state, title) => [...state, { id: 'tmp', title, pending: true }]
+ *     });
+ *
+ *     async handleSubmit(e) {
+ *       const title = e.target.querySelector('input').value;
+ *       const promise = createTodo({ title });
+ *       this.optimisticTodos.add(title, promise);
+ *       const result = await promise;
+ *       if (result.success) this.todos = [...this.todos, result.data];
+ *     }
+ *
+ *     render() {
+ *       return html`<ul>${this.optimisticTodos.value.map(t =>
+ *         html`<li class=${t.pending ? 'opacity-50' : ''}>${t.title}</li>`)}</ul>`;
+ *     }
+ *   }
+ *
+ * Behaviour:
+ *   1. `.value` reads `source()` and folds all queued updates through `update`.
+ *   2. `.add(payload)` pushes an update and calls `host.requestUpdate()`.
+ *   3. `.add(payload, promise)` auto-releases on promise settlement.
+ *   4. The returned `release()` fn removes the update by ID and re-renders.
+ *   5. Concurrent updates stack; each release removes only its own entry.
+ *
+ * Backward-compatible imperative API (signal-based rollback):
+ *   await optimistic(signal, value, () => likePost(postId));
+ *
+ * Client-only: it calls `host.requestUpdate()` (client work), so a component
+ * importing it is never elided as display-only.
+ *
+ * @template State
+ * @template Action
+ * @param {{ requestUpdate?: () => void }} host  A WebComponent instance.
+ * @param {{ source: () => State, update?: (state: State, action: Action) => State }} options
+ * @returns {OptimisticState<State, Action>}
+ */
+export function optimistic(first, second, third) {
+  if (first && typeof first.get === 'function' && typeof first.set === 'function') {
+    return runLegacyOptimistic(first, second, third);
+  }
+  return new OptimisticState(first, second);
+}

package/src/render-client.js

@@ -1,4 +1,5 @@
 import { isTemplate, MARKER } from './html.js';
+import { BINDING_PREFIXES, isBindingPrefix } from './binding-prefixes.js';
 import { escapeAttr } from './escape.js';
 import { isRepeat } from './repeat.js';
 import { isUnsafeHTML, isLive, isKeyed, isGuard, isTemplateContent, isRef, isCache, isUntil, isAsyncAppend, isAsyncReplace, isWatch } from './directives.js';
@@ -307,10 +308,10 @@ function compile(tr) {
       } else if (state === 'after-eq') {
         const prefix = attrName[0];
         const name = attrName.slice(1);
-        if (prefix === '@' || prefix === '.' || prefix === '?') {
+        if (isBindingPrefix(prefix)) {
           // Strip the attribute name+"=" from html and add a sentinel attr.
           html = html.slice(0, attrStart);
-          const kind = prefix === '@' ? 'event' : prefix === '.' ? 'prop' : 'bool';
+          const kind = BINDING_PREFIXES[prefix];
           const sentinel = `data-${MARKER}${partIdx}`;
           html += `${sentinel}=""`;
           parts.push({ kind, path: [], name });

package/src/render-server.js

@@ -1,4 +1,5 @@
 import { html, isTemplate } from './html.js';
+import { BINDING_PREFIXES } from './binding-prefixes.js';
 import { escapeText, escapeAttr } from './escape.js';
 import { lookup, lookupModuleUrl, allTags } from './registry.js';
 import { stylesToString, isCSS } from './css.js';
@@ -256,12 +257,13 @@ async function renderTemplate(tr, ctx) {
       } else if (state === 'after-eq') {
         const prefix = attrName[0];
         const name = attrName.slice(1);
-        if (prefix === '@') {
+        const kind = BINDING_PREFIXES[prefix];
+        if (kind === 'event') {
           // Event listener. Client-only behaviour, drop at SSR.
           out = out.slice(0, attrStart);
           state = 'in-tag';
           attrName = '';
-        } else if (prefix === '.') {
+        } else if (kind === 'prop') {
           // Property binding. Only meaningful on custom elements (which
           // have a hyphen in the tag name and a WebComponent subclass
           // that knows how to apply + strip data-webjs-prop-* on
@@ -315,7 +317,7 @@ async function renderTemplate(tr, ctx) {
           }
           state = 'in-tag';
           attrName = '';
-        } else if (prefix === '?') {
+        } else if (kind === 'bool') {
           out = out.slice(0, attrStart);
           if (val) out += `${name}=""`;
           state = 'in-tag';
@@ -1422,11 +1424,12 @@ async function streamTemplate(tr, ctx, controller) {
       } else if (state === 'after-eq') {
         const prefix = attrName[0];
         const name = attrName.slice(1);
-        if (prefix === '@' || prefix === '.') {
+        const kind = BINDING_PREFIXES[prefix];
+        if (kind === 'event' || kind === 'prop') {
           buf = buf.slice(0, attrStart);
           state = 'in-tag';
           attrName = '';
-        } else if (prefix === '?') {
+        } else if (kind === 'bool') {
           buf = buf.slice(0, attrStart);
           if (val) buf += `${name}=""`;
           state = 'in-tag';