@webjsdev/core 0.8.0 → 0.9.0

package/src/context.js

@@ -1,28 +1,23 @@
+/**
+ * @license
+ * Portions derived from Lit (`@lit/context`), Copyright Google LLC, BSD-3-Clause.
+ * https://github.com/lit/lit/blob/main/packages/context/LICENSE
+ */
+
 /**
  * Context Protocol: cross-component data sharing without prop drilling.
  *
- * Implements the W3C Community Group Context Protocol so any web component
- * (not just WebJs components) can participate as a provider or consumer.
+ * A port of Lit's `@lit/context`, which implements the Web Components
+ * Community Group Context Protocol, so any web component (not only a WebJs
+ * one) can take part, and a component written from Lit memory behaves the
+ * same under the `@webjsdev/core/context` import.
  *
  * ## When to use
  *
- * Use Context when you need to share data (theme, auth state, locale,
- * config, feature flags) across deeply nested components without passing
- * props through every intermediate level.
- *
- * Prefer Context over module-level globals when the shared data is **scoped
- * to a subtree**: e.g. a specific page, panel, or dialog: and different
- * subtrees may hold different values for the same context key.
- *
- * ## When NOT to use
- *
- * - For page-level data loading, use async page functions or server actions
- *   instead. Context is a client-side primitive.
- * - If only a parent and its direct child need to communicate, plain
- *   properties/attributes are simpler.
- * - If every component in the app needs the same single value (e.g. a
- *   singleton API client), a module-level export may be simpler than
- *   context.
+ * Share data (theme, auth state, locale, config) with deeply nested
+ * components without passing it through every level. Prefer it over a
+ * module-level signal when the value is SCOPED to a subtree, so different
+ * subtrees can hold different values for the same context.
  *
  * ## Quick example
  *
@@ -30,15 +25,17 @@
  * import { WebComponent, html } from '@webjsdev/core';
  * import { createContext, ContextProvider, ContextConsumer } from '@webjsdev/core/context';
  *
- * const ThemeCtx = createContext('theme');
+ * // The KEY is the identity: the same string (or the same Symbol) in two
+ * // modules is the same context.
+ * export const themeContext = createContext('theme');
  *
  * class MyApp extends WebComponent {
- *   _theme = new ContextProvider(this, { context: ThemeCtx, initialValue: 'light' });
+ *   _theme = new ContextProvider(this, { context: themeContext, initialValue: 'light' });
  *   render() {
  *     return html`
- *       <button @click=${() => this._theme.setValue(
- *         this._theme.value === 'light' ? 'dark' : 'light'
- *       )}>Toggle</button>
+ *       <button @click=${() => this._theme.setValue(this._theme.value === 'light' ? 'dark' : 'light')}>
+ *         Toggle
+ *       </button>
  *       <slot></slot>
  *     `;
  *   }
@@ -46,7 +43,7 @@
  * MyApp.register('my-app');
  *
  * class ThemedCard extends WebComponent {
- *   _theme = new ContextConsumer(this, { context: ThemeCtx, subscribe: true });
+ *   _theme = new ContextConsumer(this, { context: themeContext, subscribe: true });
  *   render() {
  *     return html`<div class=${this._theme.value}>Card content</div>`;
  *   }
@@ -54,176 +51,237 @@
  * ThemedCard.register('themed-card');
  * ```
  *
- * `<themed-card>` can live at any depth under `<my-app>`: it finds the
- * provider automatically via a bubbling `context-request` event that
- * crosses shadow-DOM boundaries (`composed: true`).
- *
  * @module
  */
 
 // ---------------------------------------------------------------------------
-// Context key
+// createContext
 // ---------------------------------------------------------------------------
 
 /**
- * @template T
- * @typedef {{ __context__: typeof CONTEXT_KEY, name: string }} Context
- */
-
-const CONTEXT_KEY = Symbol.for('webjs.context');
-
-/**
- * Create a typed context key.
- *
- * The returned object is used as an identity token: two calls to
- * `createContext('theme')` produce **different** contexts even though
- * the debug name is the same. Store the key in a shared module and
- * import it from both provider and consumer.
+ * Create a context key. It returns `key` itself, typed with the value type,
+ * exactly as Lit does: the key IS the identity, so `createContext('theme')`
+ * in two modules produces the same context. Use a `Symbol('theme')` exported
+ * from one module when the context must not collide with any other.
  *
- * @template T
- * @param {string} name  Human-readable name (used in error messages and
- *   devtools, not for matching).
- * @returns {Context<T>}
+ * @template ValueType
+ * @template [K=unknown]
+ * @param {K} key
+ * @returns {K}
  */
-export function createContext(name) {
-  return { __context__: CONTEXT_KEY, name };
+export function createContext(key) {
+  return key;
 }
 
 // ---------------------------------------------------------------------------
-// ContextRequestEvent
+// Events
 // ---------------------------------------------------------------------------
 
 /**
- * Fired by a consumer to locate a provider higher in the DOM.
- *
- * - `bubbles: true` so it walks up the DOM tree.
- * - `composed: true` so it crosses shadow-DOM boundaries.
- *
- * Providers listen for this event on their host element and respond by
- * calling the event's `callback` with the current value.
- *
- * @template T
+ * Fired by a consumer to ask for a value. It bubbles and is composed, so it
+ * crosses shadow roots on its way to the nearest provider.
  */
 export class ContextRequestEvent extends Event {
   /**
-   * @param {Context<T>} context   The context key to request.
-   * @param {(value: T, unsubscribe?: () => void) => void} callback
-   *   Called by the provider with the current value. If `subscribe` is
-   *   true the provider retains the callback and calls it again whenever
-   *   the value changes (passing an `unsubscribe` function on each call).
-   * @param {boolean} subscribe  Whether the consumer wants ongoing updates.
+   * @param {unknown} context The context key.
+   * @param {Element} contextTarget The element asking (the consumer's host).
+   * @param {(value: any, unsubscribe?: () => void) => void} callback
+   *   Called by the provider with the value. A subscribing request also gets
+   *   an `unsubscribe` function, and is called again on every change.
+   * @param {boolean} [subscribe=false] Whether to keep receiving changes.
    */
-  constructor(context, callback, subscribe = false) {
+  constructor(context, contextTarget, callback, subscribe) {
     super('context-request', { bubbles: true, composed: true });
-    /** @type {Context<T>} */
+    /** @readonly */
     this.context = context;
-    /** @type {(value: T, unsubscribe?: () => void) => void} */
+    /** @readonly */
+    this.contextTarget = contextTarget;
+    /** @readonly */
     this.callback = callback;
-    /** @type {boolean} */
-    this.subscribe = subscribe;
+    /** @readonly */
+    this.subscribe = subscribe ?? false;
+  }
+}
+
+/**
+ * Fired by a provider when it connects, so a provider ABOVE it can hand over
+ * the subscriptions that now belong to the nearer provider, and so a
+ * `ContextRoot` can replay requests that arrived before any provider existed.
+ */
+export class ContextProviderEvent extends Event {
+  /**
+   * @param {unknown} context The context key.
+   * @param {Element} contextTarget The provider's host.
+   */
+  constructor(context, contextTarget) {
+    super('context-provider', { bubbles: true, composed: true });
+    /** @readonly */
+    this.context = context;
+    /** @readonly */
+    this.contextTarget = contextTarget;
   }
 }
 
 // ---------------------------------------------------------------------------
-// ContextProvider
+// ValueNotifier (the provider's value + subscriber list)
 // ---------------------------------------------------------------------------
 
 /**
+ * Holds a value and the callbacks subscribed to it. The base of
+ * {@link ContextProvider}, as in Lit.
  * @template T
- * @typedef {{ callback: (value: T, unsubscribe?: () => void) => void }} Subscription
  */
+export class ValueNotifier {
+  /** @param {T} [defaultValue] */
+  constructor(defaultValue) {
+    /**
+     * Subscribed callbacks, each with its disposer and the consumer host it
+     * came from (used to re-dispatch when a nearer provider appears).
+     * @type {Map<Function, { disposer: () => void, consumerHost: Element }>}
+     */
+    this.subscriptions = new Map();
+    /** @type {T} */
+    this._value = /** @type {T} */ (undefined);
+    if (defaultValue !== undefined) this.value = defaultValue;
+  }
+
+  /** @returns {T} */
+  get value() {
+    return this._value;
+  }
+
+  /** @param {T} v */
+  set value(v) {
+    this.setValue(v);
+  }
+
+  /**
+   * Set the value and, when it changed (or `force` is true), call every
+   * subscriber with it.
+   * @param {T} v
+   * @param {boolean} [force=false]
+   */
+  setValue(v, force = false) {
+    const update = force || !Object.is(v, this._value);
+    this._value = v;
+    if (update) this.updateObservers();
+  }
+
+  /** Call every subscriber with the current value. */
+  updateObservers = () => {
+    for (const [callback, { disposer }] of this.subscriptions) {
+      callback(this._value, disposer);
+    }
+  };
+
+  /**
+   * Answer a request: call `callback` with the value, and keep it for later
+   * changes when `subscribe` is true.
+   * @param {(value: T, unsubscribe?: () => void) => void} callback
+   * @param {Element} consumerHost
+   * @param {boolean} [subscribe]
+   */
+  addCallback(callback, consumerHost, subscribe) {
+    if (!subscribe) {
+      callback(this.value);
+      return;
+    }
+    if (!this.subscriptions.has(callback)) {
+      this.subscriptions.set(callback, {
+        disposer: () => {
+          this.subscriptions.delete(callback);
+        },
+        consumerHost,
+      });
+    }
+    const { disposer } = /** @type {{ disposer: () => void }} */ (this.subscriptions.get(callback));
+    callback(this.value, disposer);
+  }
+
+  /** Drop every subscriber. */
+  clearCallbacks() {
+    this.subscriptions.clear();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ContextProvider
+// ---------------------------------------------------------------------------
 
 /**
- * A ReactiveController that provides a context value to descendant
- * components.
+ * A ReactiveController that provides a value to descendants. It listens on
+ * its host from construction, answers matching `context-request` events from
+ * descendants (never its own host's), and on connect fires
+ * `context-provider` so an outer provider of the same context hands over the
+ * subscribers that are now nearer to this one.
  *
- * The provider listens for `context-request` events on its host element.
- * When a matching request arrives it delivers the current value (and,
- * for subscribing consumers, retains the callback for future updates).
- *
- * ## AI guidance
- *
- * - Create one `ContextProvider` per context key per component.
- * - Call `setValue()` to push updates to all subscribing consumers.
- * - The provider **must** be a DOM ancestor of its consumers (shadow-DOM
- *   depth does not matter thanks to `composed: true`).
+ * `new ContextProvider(host, { context, initialValue })` or
+ * `new ContextProvider(host, context, initialValue)`.
  *
  * @template T
+ * @extends {ValueNotifier<T>}
  */
-export class ContextProvider {
+export class ContextProvider extends ValueNotifier {
   /**
-   * @param {import('./component.js').WebComponent} host
-   *   The host component that owns this provider.
-   * @param {{ context: Context<T>, initialValue?: T }} options
+   * @param {any} host The host element (a WebComponent or any element).
+   * @param {any} contextOrOptions `{ context, initialValue }`, or the context.
+   * @param {T} [initialValue] The value, positional form only.
    */
-  constructor(host, { context, initialValue }) {
-    /** @type {import('./component.js').WebComponent} */
-    this._host = host;
-    /** @type {Context<T>} */
-    this._context = context;
-    /** @type {T} */
-    this._value = /** @type {T} */ (initialValue);
-    /** @type {Set<Subscription<T>>} */
-    this._subscriptions = new Set();
-
-    /** @type {(e: Event) => void} */
-    this._onRequest = (e) => {
-      const evt = /** @type {ContextRequestEvent<T>} */ (e);
-      if (evt.context !== this._context) return;
-
-      // Prevent further providers higher in the tree from also responding.
-      e.stopPropagation();
-
-      if (evt.subscribe) {
-        /** @type {Subscription<T>} */
-        const sub = { callback: evt.callback };
-        const unsubscribe = () => { this._subscriptions.delete(sub); };
-        this._subscriptions.add(sub);
-        evt.callback(this._value, unsubscribe);
-      } else {
-        evt.callback(this._value);
-      }
-    };
-
-    // Follow the ReactiveController protocol.
-    if (typeof host.addController === 'function') {
-      host.addController(this);
-    }
+  constructor(host, contextOrOptions, initialValue) {
+    const isOptions = contextOrOptions != null && contextOrOptions.context !== undefined;
+    super(isOptions ? contextOrOptions.initialValue : initialValue);
+    /** @protected */
+    this.host = host;
+    /** @private */
+    this.context = isOptions ? contextOrOptions.context : contextOrOptions;
+    this.attachListeners();
+    this.host.addController?.(this);
   }
 
-  /** @returns {T} The current provided value. */
-  get value() {
-    return this._value;
-  }
+  /** @param {Event} e */
+  onContextRequest = (e) => {
+    const ev = /** @type {ContextRequestEvent} */ (e);
+    if (ev.context !== this.context) return;
+    const consumerHost = ev.contextTarget ?? ev.composedPath()[0];
+    // A host never provides to itself: a component that both provides and
+    // consumes a context reads it from an ancestor.
+    if (consumerHost === this.host) return;
+    ev.stopPropagation();
+    this.addCallback(ev.callback, consumerHost, ev.subscribe);
+  };
 
   /**
-   * Update the provided value and notify all subscribers.
-   *
-   * Every subscribing consumer's callback is invoked synchronously with
-   * the new value. Each consumer then calls `host.requestUpdate()` to
-   * schedule a re-render: so one `setValue` batches all downstream
-   * re-renders via the microtask queue.
-   *
-   * @param {T} newValue
+   * A nearer provider of the same context connected below this one: re-send
+   * every subscriber's request from its consumer, so the nearest provider
+   * answers it. The consumer drops this provider's subscription when the new
+   * one calls back with a different disposer.
+   * @param {Event} e
    */
-  setValue(newValue) {
-    if (Object.is(this._value, newValue)) return;
-    this._value = newValue;
-    for (const sub of this._subscriptions) {
-      const unsubscribe = () => { this._subscriptions.delete(sub); };
-      sub.callback(newValue, unsubscribe);
+  onProviderRequest = (e) => {
+    const ev = /** @type {ContextProviderEvent} */ (e);
+    if (ev.context !== this.context) return;
+    const childProviderHost = ev.contextTarget ?? ev.composedPath()[0];
+    if (childProviderHost === this.host) return;
+    const seen = new Set();
+    for (const [callback, { consumerHost }] of this.subscriptions) {
+      if (seen.has(callback)) continue;
+      seen.add(callback);
+      consumerHost.dispatchEvent(
+        new ContextRequestEvent(this.context, consumerHost, /** @type {any} */ (callback), true),
+      );
     }
-  }
+    ev.stopPropagation();
+  };
 
-  /** Called by the host's controller lifecycle when the element connects. */
-  hostConnected() {
-    this._host.addEventListener('context-request', this._onRequest);
+  /** @private */
+  attachListeners() {
+    this.host.addEventListener('context-request', this.onContextRequest);
+    this.host.addEventListener('context-provider', this.onProviderRequest);
   }
 
-  /** Called by the host's controller lifecycle when the element disconnects. */
-  hostDisconnected() {
-    this._host.removeEventListener('context-request', this._onRequest);
-    this._subscriptions.clear();
+  /** ReactiveController hook: announce this provider to the tree above. */
+  hostConnected() {
+    this.host.dispatchEvent(new ContextProviderEvent(this.context, this.host));
   }
 }
 
@@ -232,96 +290,162 @@ export class ContextProvider {
 // ---------------------------------------------------------------------------
 
 /**
- * A ReactiveController that consumes a context value from an ancestor
- * provider.
- *
- * On `hostConnected` it dispatches a `ContextRequestEvent`. If a provider
- * for the matching context key exists higher in the DOM tree, the consumer
- * receives the current value immediately (and, if `subscribe: true`, all
- * future updates as well).
- *
- * ## AI guidance
+ * A ReactiveController that reads a context value from the nearest provider
+ * above its host. It requests the value on connect and re-renders the host
+ * on delivery. With `subscribe: true` it keeps receiving changes; the
+ * default, as in Lit, is a one-time read per connection.
  *
- * - Use `subscribe: true` (the default) when you want the consumer to
- *   update automatically whenever the provider calls `setValue()`. This is
- *   the common case for reactive data like theme, auth, or locale.
- * - Use `subscribe: false` for one-shot reads where you only need the
- *   value at connection time (e.g. reading a static config once).
- * - Access the value via `consumer.value`. It is `undefined` until a
- *   provider responds.
- * - If no provider exists in the ancestor chain, `value` stays
- *   `undefined`: design your render method to handle that case.
+ * `new ContextConsumer(host, { context, callback, subscribe })` or
+ * `new ContextConsumer(host, context, callback, subscribe)`.
  *
  * @template T
  */
 export class ContextConsumer {
   /**
-   * @param {import('./component.js').WebComponent} host
-   *   The host component that owns this consumer.
-   * @param {{ context: Context<T>, subscribe?: boolean }} options
-   *   `subscribe` defaults to `true`.
+   * @param {any} host The host element.
+   * @param {any} contextOrOptions `{ context, callback, subscribe }`, or the context.
+   * @param {(value: T, dispose?: () => void) => void} [callback] Positional form only.
+   * @param {boolean} [subscribe] Positional form only.
    */
-  constructor(host, { context, subscribe = true }) {
-    /** @type {import('./component.js').WebComponent} */
-    this._host = host;
-    /** @type {Context<T>} */
-    this._context = context;
-    /** @type {boolean} */
-    this._subscribe = subscribe;
+  constructor(host, contextOrOptions, callback, subscribe) {
+    /** @protected */
+    this.host = host;
+    /** @private */
+    this.provided = false;
     /** @type {T | undefined} */
-    this._value = undefined;
-    /** @type {(() => void) | undefined} */
-    this._unsubscribe = undefined;
-
-    if (typeof host.addController === 'function') {
-      host.addController(this);
+    this.value = undefined;
+    /** @private @type {(() => void) | undefined} */
+    this.unsubscribe = undefined;
+    if (contextOrOptions != null && contextOrOptions.context !== undefined) {
+      /** @private */
+      this.context = contextOrOptions.context;
+      /** @private */
+      this.callback = contextOrOptions.callback;
+      /** @private */
+      this.subscribe = contextOrOptions.subscribe ?? false;
+    } else {
+      this.context = contextOrOptions;
+      this.callback = callback;
+      this.subscribe = subscribe ?? false;
     }
+    this.host.addController(this);
   }
 
-  /**
-   * The current context value. `undefined` if no provider has responded
-   * yet.
-   * @returns {T | undefined}
-   */
-  get value() {
-    return this._value;
-  }
-
-  /** Called by the host's controller lifecycle when the element connects. */
+  /** ReactiveController hook: request the value. */
   hostConnected() {
-    this._dispatchRequest();
+    this.dispatchRequest();
   }
 
-  /** Called by the host's controller lifecycle when the element disconnects. */
+  /** ReactiveController hook: stop receiving changes. */
   hostDisconnected() {
-    if (this._unsubscribe) {
-      this._unsubscribe();
-      this._unsubscribe = undefined;
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = undefined;
     }
   }
 
   /** @private */
-  _dispatchRequest() {
-    const event = new ContextRequestEvent(
-      this._context,
-      (value, unsubscribe) => {
-        // Guard against duplicate updates with the same value.
-        const old = this._value;
-        this._value = value;
-        if (unsubscribe) {
-          this._unsubscribe = unsubscribe;
-        }
-        // Trigger a re-render of the consuming component when the value
-        // changes (skip on the very first delivery during connection,
-        // since the host will render after connectedCallback anyway -
-        // but we still update to be safe with various host lifecycles).
-        if (!Object.is(old, value) && typeof this._host.requestUpdate === 'function') {
-          this._host.requestUpdate();
-        }
-      },
-      this._subscribe,
+  dispatchRequest() {
+    this.host.dispatchEvent(
+      new ContextRequestEvent(this.context, this.host, this._callback, this.subscribe),
     );
+  }
+
+  /**
+   * One stable callback per consumer, so a provider recognises a repeat
+   * request and a hand-over between providers.
+   * @private
+   * @param {T} value
+   * @param {() => void} [unsubscribe]
+   */
+  _callback = (value, unsubscribe) => {
+    if (this.unsubscribe) {
+      // A different disposer means a different (nearer) provider answered:
+      // leave the old one.
+      if (this.unsubscribe !== unsubscribe) {
+        this.provided = false;
+        this.unsubscribe();
+      }
+      if (!this.subscribe) this.unsubscribe();
+    }
+    this.value = value;
+    this.host.requestUpdate();
+    if (!this.provided || this.subscribe) {
+      this.provided = true;
+      if (this.callback) this.callback(value, unsubscribe);
+    }
+    this.unsubscribe = unsubscribe;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// ContextRoot
+// ---------------------------------------------------------------------------
+
+/**
+ * Buffers SUBSCRIBING requests that reach it unanswered (no provider above
+ * the consumer yet, typically because the provider's element upgrades
+ * later), and replays them when a provider for that context connects.
+ * Attach one near the root, before components upgrade:
+ *
+ * ```js
+ * new ContextRoot().attach(document.body);
+ * ```
+ */
+export class ContextRoot {
+  constructor() {
+    /**
+     * @private
+     * @type {Map<unknown, { callbacks: WeakMap<Element, WeakSet<Function>>, requests: Array<{ elementRef: WeakRef<Element>, callbackRef: WeakRef<Function> }> }>}
+     */
+    this.pendingContextRequests = new Map();
+  }
 
-    this._host.dispatchEvent(event);
+  /** @param {Element} element */
+  attach(element) {
+    element.addEventListener('context-request', this.onContextRequest);
+    element.addEventListener('context-provider', this.onContextProvider);
   }
+
+  /** @param {Element} element */
+  detach(element) {
+    element.removeEventListener('context-request', this.onContextRequest);
+    element.removeEventListener('context-provider', this.onContextProvider);
+  }
+
+  /** @private @param {Event} e */
+  onContextProvider = (e) => {
+    const event = /** @type {ContextProviderEvent} */ (e);
+    const pending = this.pendingContextRequests.get(event.context);
+    if (pending === undefined) return;
+    this.pendingContextRequests.delete(event.context);
+    for (const { elementRef, callbackRef } of pending.requests) {
+      const element = elementRef.deref();
+      const callback = callbackRef.deref();
+      if (element === undefined || callback === undefined) continue;
+      element.dispatchEvent(
+        new ContextRequestEvent(event.context, element, /** @type {any} */ (callback), true),
+      );
+    }
+  };
+
+  /** @private @param {Event} e */
+  onContextRequest = (e) => {
+    const event = /** @type {ContextRequestEvent} */ (e);
+    // Only a subscribing request can be answered later.
+    if (event.subscribe !== true) return;
+    const element = event.contextTarget ?? /** @type {Element} */ (event.composedPath()[0]);
+    const callback = event.callback;
+    let pending = this.pendingContextRequests.get(event.context);
+    if (pending === undefined) {
+      this.pendingContextRequests.set(event.context, (pending = { callbacks: new WeakMap(), requests: [] }));
+    }
+    let callbacks = pending.callbacks.get(element);
+    if (callbacks === undefined) {
+      pending.callbacks.set(element, (callbacks = new WeakSet()));
+    }
+    if (callbacks.has(callback)) return;
+    callbacks.add(callback);
+    pending.requests.push({ elementRef: new WeakRef(element), callbackRef: new WeakRef(callback) });
+  };
 }

package/src/converters.d.ts

@@ -0,0 +1,7 @@
+/** Lit's default attribute converter, as `lit` exports it. */
+export declare const defaultConverter: {
+  toAttribute(value: unknown, type?: unknown): unknown;
+  fromAttribute(value: string | null, type?: unknown): unknown;
+};
+/** Lit's default `hasChanged`: true when `value` and `old` differ by `Object.is`. */
+export declare const notEqual: (value: unknown, old: unknown) => boolean;