@miaskiewicz/turbo-dom 0.5.7 → 0.6.0

package/src/runtime/cssom.mjs

@@ -63,11 +63,10 @@ export class CSSStyleSheet {
   get rules() { return this.cssRules; }
 
   insertRule(rule, index = 0) {
-    const i = index === undefined ? 0 : index;
-    if (i < 0 || i > this.cssRules.length) throw new RangeError('insertRule: index out of bounds');
-    this.cssRules.splice(i, 0, new CSSStyleRule(rule));
+    if (index < 0 || index > this.cssRules.length) throw new RangeError('insertRule: index out of bounds');
+    this.cssRules.splice(index, 0, new CSSStyleRule(rule));
     this.#invalidate();
-    return i;
+    return index;
   }
 
   deleteRule(index) {

package/src/runtime/custom-elements.mjs

@@ -0,0 +1,398 @@
+// HTML custom elements for the JS runtime (miaskiewicz/turbo-dom#26 item 2): each element's
+// custom element state (what `:defined` reads), the window's CustomElementRegistry, element
+// upgrade / construction, and the lifecycle callbacks. Kept in lockstep with the Rust engine,
+// whose tree records the same state (crates/turbo-dom/src/rtdom/custom_element_state.rs) and
+// whose V8 binding upgrades like Chrome — both checked against the Chrome 156 control
+// crates/turbo-dom-browser-env/src/custom_elements_defined_chrome156.json
+// (test/custom-elements-chrome.test.mjs here).
+//
+// State. An element's state is fixed when it is created and changes only through upgrade
+// or construction. Without either, it is the creation-time state: an HTML element whose
+// local name is a valid custom element name, or that was created with an `is` value (the
+// parser's `is` attribute, `createElement(name, {is})`, a clone of one), is "undefined";
+// every other element is "uncustomized". A later `is` attribute edit never changes it.
+// `el.__ce` holds an explicit state (unset = the creation-time one) and `el.__ceIs` an `is`
+// value the buffer cannot tell (created, cloned and innerHTML-parsed elements); both live
+// only on the rare elements that need them, so plain elements carry nothing.
+//
+// Pay-for-what-you-use: the DOM's hooks (dom.mjs) run only once the document has a
+// registry with a definition (`Document.__ceRegistry`, set when `window.customElements` is
+// first touched); until then every mutation path is unchanged.
+//
+// Reactions are queued per element and run when the outermost DOM call returns, element by
+// element, like Chrome's [CEReactions] (see "reactions" below; miaskiewicz/turbo-dom#29 item
+// 4): upgrades (constructor, then attributeChangedCallback for observed attributes and
+// connectedCallback), disconnectedCallback on removal, adoptedCallback on adoption.
+// Exceptions from constructors and callbacks are reported (`window.reportError`), never
+// thrown into the DOM call, like Chrome; a throwing constructor leaves the element "failed".
+
+export const UNDEFINED = 'undefined';
+export const FAILED = 'failed';
+export const UNCUSTOMIZED = 'uncustomized';
+export const PRECUSTOMIZED = 'precustomized';
+export const CUSTOM = 'custom';
+const STATES = new Set([UNDEFINED, FAILED, UNCUSTOMIZED, PRECUSTOMIZED, CUSTOM]);
+
+// HTML's "valid custom element name" for the names the parser and createElement produce.
+const RESERVED = new Set(['annotation-xml', 'color-profile', 'font-face', 'font-face-src', 'font-face-uri',
+  'font-face-format', 'font-face-name', 'missing-glyph']);
+export function isCustomName(name) {
+  return /^[a-z][^A-Z]*-[^A-Z]*$/.test(name) && !RESERVED.has(name);
+}
+
+// The `is` value the parser saw (the immutable buffer's attribute, whatever later edits did).
+function parsedIs(el) {
+  const doc = el.ownerDocument, buf = doc && doc.__buf;
+  return el.__attrIdx >= 0 && buf ? buf.attrGet(el.__attrIdx, 'is') : null;
+}
+
+// Keep the parser's `is` value when the element loses its buffer link (adoption).
+export function freezeParsedIs(el) {
+  const is = parsedIs(el);
+  if (is === null) return;
+  el.__ceIs = is;
+  if (el.__ce === undefined) el.__ce = UNDEFINED;
+}
+
+// A fragment-parsed (innerHTML) element: its `is` attribute is its `is` value.
+export function parsedIsAttribute(el) {
+  const attrs = el.__attrs;
+  for (let i = 0; i < attrs.length; i++) {
+    if (attrs[i].name === 'is' && attrs[i].prefix === '') { el.__ceIs = attrs[i].value; el.__ce = UNDEFINED; return; }
+  }
+}
+
+// The element's `is` value (HTML: read once, at creation).
+export function isValue(el) {
+  return el.__ceIs !== undefined ? el.__ceIs : parsedIs(el);
+}
+
+// The element's custom element state: the recorded one, else the creation-time state.
+export function customElementState(el) {
+  if (!el || el.nodeType !== 1 || el.__ns !== '') return UNCUSTOMIZED;
+  const state = el.__ce;
+  if (state !== undefined) return state;
+  const name = el.localName;
+  return (name.indexOf('-') !== -1 && isCustomName(name)) || parsedIs(el) !== null ? UNDEFINED : UNCUSTOMIZED;
+}
+
+// :defined — uncustomized or custom.
+export function isDefinedElement(el) {
+  const state = customElementState(el);
+  return state === UNCUSTOMIZED || state === CUSTOM;
+}
+
+// Record an element's state (an embedder's upgrade report, or this module's own). Returns
+// whether the state changed; a change bumps the DOM version so cached queries and
+// computed styles see it. Non-elements and non-HTML elements are ignored.
+export function setCustomElementState(el, state) {
+  if (!STATES.has(state)) throw new TypeError(`unknown custom element state: ${state}`);
+  if (!el || el.nodeType !== 1 || el.__ns !== '') return false;
+  const before = customElementState(el);
+  el.__ce = state;
+  if (before === state) return false;
+  const doc = el.ownerDocument;
+  if (doc) doc.__touch();
+  return true;
+}
+
+// The state a copy (clone / import) starts in: "undefined" when the source is a custom
+// element or was created with an `is` value, else uncustomized; the `is` value travels.
+export function copyCustomElementState(source, copy) {
+  const is = isValue(source);
+  if (is !== null) copy.__ceIs = is;
+  if (customElementState(source) !== UNCUSTOMIZED) copy.__ce = UNDEFINED;
+}
+
+// ---------------------------------------------------------------- registry ----
+
+const definitions = new WeakMap(); // constructor -> definition (its registry's)
+const ALREADY_CONSTRUCTED = {};
+
+function report(doc, error) {
+  const win = doc && doc.defaultView;
+  const reportError = win && win.reportError;
+  if (typeof reportError === 'function') reportError(error);
+}
+
+// The live registry state of a document, when it has at least one definition.
+function active(doc) {
+  const reg = doc && doc.__ceRegistry;
+  return reg !== undefined && reg !== null && reg.defs.size !== 0 ? reg : null;
+}
+
+function lookup(reg, localName, is) {
+  const autonomous = reg.defs.get(localName);
+  if (autonomous !== undefined && autonomous.localName === localName) return autonomous;
+  if (is === null) return null;
+  const customized = reg.defs.get(is);
+  return customized !== undefined && customized.localName === localName ? customized : null;
+}
+
+function definitionOf(el) {
+  if (customElementState(el) !== UNDEFINED) return null;
+  const reg = active(el.ownerDocument);
+  return reg && lookup(reg, el.localName, isValue(el));
+}
+
+// ------------------------------------------------------------- reactions ----
+// HTML [CEReactions]: upgrades and lifecycle callbacks are queued on the element's own
+// reaction queue (`el.__ceReactions`) and the element on the open scope's element queue;
+// the outermost DOM call of the current script level runs them when it returns, element by
+// element (each element's whole queue, then the next element). dom.mjs opens a scope
+// (`withReactions`) around the DOM calls that can queue reactions, only when a document
+// involved has custom element hooks armed (`__ceRegistry !== undefined`). Constructors and
+// callbacks run with no scope open (`reactionDepth === 0`), so a DOM call they make opens
+// its own scope and runs its reactions before returning to them. A reaction queued with no
+// scope open (a single-step DOM call such as setAttribute) runs right away — the same
+// moment as "when the call returns".
+
+export let reactionDepth = 0;
+let elementQueue = null;
+
+// Run `fn.apply(self, args)` as one [CEReactions] scope.
+export function withReactions(fn, self, args) {
+  if (reactionDepth++ === 0) elementQueue = [];
+  try {
+    return fn.apply(self, args);
+  } finally {
+    if (--reactionDepth === 0) {
+      const queue = elementQueue;
+      elementQueue = null;
+      for (let i = 0; i < queue.length; i++) drain(queue[i]);
+    }
+  }
+}
+
+// Invoke the element's queued reactions in order (later ones queued meanwhile included).
+function drain(el) {
+  const reactions = el.__ceReactions;
+  while (reactions.length !== 0) {
+    const reaction = reactions.shift();
+    if (reaction.fn === undefined) upgrade(el, reaction.def);
+    // reported in the definition's window (the element may have moved to another document)
+    else try { reaction.fn.apply(el, reaction.args); } catch (error) { report(reaction.def.registry.document, error); }
+  }
+}
+
+function enqueue(el, reaction) {
+  const reactions = el.__ceReactions;
+  if (reactions === undefined) el.__ceReactions = [reaction];
+  else reactions.push(reaction);
+  if (elementQueue !== null) elementQueue.push(el);
+  else drain(el);
+}
+
+// HTML "enqueue a custom element callback reaction" (a no-op without that callback).
+function enqueueCallback(el, def, name, args) {
+  const fn = def[name];
+  if (fn !== undefined) enqueue(el, { def, fn, args });
+}
+
+// HTML "enqueue a custom element upgrade reaction".
+function enqueueUpgrade(el, def) {
+  enqueue(el, { def, fn: undefined, args: undefined });
+}
+
+// A callback queued while the element's own reactions are running (upgrade's initial
+// attributeChanged / connected): picked up by the running drain, no element queue entry.
+function enqueueOwn(el, def, name, args) {
+  const fn = def[name];
+  if (fn !== undefined) el.__ceReactions.push({ def, fn, args });
+}
+
+// HTML "upgrade an element": run the definition's constructor on the existing element.
+function upgrade(el, def) {
+  if (customElementState(el) !== UNDEFINED) return;
+  setCustomElementState(el, PRECUSTOMIZED);
+  def.stack.push(el);
+  let result, error, threw = false;
+  try { result = Reflect.construct(def.ctor, []); } catch (e) { threw = true; error = e; }
+  def.stack.pop();
+  if (!threw && result !== el) {
+    threw = true;
+    error = new TypeError('Custom element constructors must call super() first and must not return a different object');
+  }
+  if (threw) {
+    setCustomElementState(el, FAILED);
+    report(el.ownerDocument, error);
+    return;
+  }
+  el.__ceDef = def;
+  setCustomElementState(el, CUSTOM);
+  if (el.__ceReactions === undefined) el.__ceReactions = [];
+  if (def.attributeChangedCallback !== undefined) {
+    for (const name of def.observed) {
+      const value = el.getAttribute(name);
+      if (value !== null) enqueueOwn(el, def, 'attributeChangedCallback', [name, null, value, null]);
+    }
+  }
+  if (el.isConnected) enqueueOwn(el, def, 'connectedCallback', []);
+}
+
+// HTML "try to upgrade an element": queue an upgrade when its definition exists.
+function tryUpgrade(el) {
+  const def = definitionOf(el);
+  if (def) enqueueUpgrade(el, def);
+}
+
+// Shadow-including inclusive descendants in shadow-including tree order (elements only).
+function eachElement(root, visit) {
+  if (root.nodeType === 1) {
+    visit(root);
+    const shadow = root.__shadow;
+    if (shadow) eachElement(shadow, visit);
+  }
+  const kids = root.__children();
+  for (let i = 0; i < kids.length; i++) if (kids[i].nodeType === 1 || kids[i].nodeType === 11) eachElement(kids[i], visit);
+}
+
+// The HTML element constructors (HTMLElement and the tag interfaces): `new C()` for a
+// defined C makes a new custom element; during an upgrade it returns the element being
+// upgraded. Returns null for a constructor that is not defined (the caller's fallback).
+export function constructCustomElement(newTarget) {
+  const def = definitions.get(newTarget);
+  if (def === undefined || def.registry.document.__ceRegistry !== def.registry) return null;
+  const proto = newTarget.prototype;
+  const stack = def.stack;
+  if (stack.length === 0) {
+    const el = def.registry.document.__newHtmlElement(def.localName);
+    if (def.localName !== def.name) el.__ceIs = def.name;
+    Object.setPrototypeOf(el, proto);
+    el.__ceDef = def;
+    el.__ce = CUSTOM;
+    return el;
+  }
+  const el = stack[stack.length - 1];
+  if (el === ALREADY_CONSTRUCTED) throw new TypeError("Failed to construct 'HTMLElement': This instance is already constructed");
+  Object.setPrototypeOf(el, proto);
+  stack[stack.length - 1] = ALREADY_CONSTRUCTED;
+  return el;
+}
+
+// HTML "create an element" for an HTML element of `doc` (createElement, cloneNode):
+// `synchronous` runs an autonomous definition's constructor directly (createElement),
+// else the element is created "undefined" and upgraded (clones).
+export function createCustomElement(doc, localName, is, synchronous) {
+  const reg = active(doc);
+  const def = reg && lookup(reg, localName, is);
+  if (def && def.localName === def.name && synchronous) {
+    try {
+      const el = Reflect.construct(def.ctor, []);
+      if (!el || el.nodeType !== 1 || el.localName !== localName || el.ownerDocument !== doc || el.parentNode
+        || el.__children().length !== 0 || (el.__attrs !== undefined && el.__attrs.length !== 0)) {
+        throw new TypeError(`Failed to execute 'createElement' on 'Document': The result must be a fresh <${localName}> element`);
+      }
+      return el;
+    } catch (error) {
+      report(doc, error);
+      const el = doc.__newHtmlElement(localName);
+      el.__ce = FAILED;
+      return el;
+    }
+  }
+  const el = doc.__newHtmlElement(localName);
+  if (is !== null) { el.__ceIs = is; el.__ce = UNDEFINED; }
+  // a customized built-in upgrades synchronously; a fresh element queues no reactions
+  if (def) upgrade(el, def);
+  return el;
+}
+
+// ------------------------------------------------------------- DOM hooks ----
+// Called by dom.mjs only when `doc.__ceRegistry` is set (one predicted-false read otherwise).
+// They queue reactions; the enclosing withReactions scope runs them.
+
+// A clone (or import) of `source`: copy the state, queue an upgrade when a definition exists.
+export function clonedElement(source, copy) {
+  copyCustomElementState(source, copy);
+  if (active(copy.ownerDocument)) tryUpgrade(copy);
+}
+
+// `node` was inserted: connectedCallback for custom elements (in any document — one adopted
+// into a document without a registry stays custom), try to upgrade the others.
+export function insertedNode(node) {
+  if (!node.isConnected) return;
+  const upgrades = active(node.ownerDocument) !== null;
+  eachElement(node, (el) => {
+    if (el.__ce === CUSTOM) { if (el.__ceDef) enqueueCallback(el, el.__ceDef, 'connectedCallback', []); }
+    else if (upgrades) tryUpgrade(el);
+  });
+}
+
+// Elements created by an HTML fragment parse (innerHTML, insertAdjacentHTML): upgrades
+// queued at creation when their definition exists, connected or not (Chrome creates them
+// in the context element's document) — before the old children are removed.
+export function parsedFragment(nodes) {
+  if (nodes.length === 0 || !active(nodes[0].ownerDocument)) return;
+  for (const node of nodes) eachElement(node, tryUpgrade);
+}
+
+// `node` was removed from a connected tree: disconnectedCallback for custom elements.
+export function removedNode(node) {
+  eachElement(node, (el) => { if (el.__ce === CUSTOM && el.__ceDef) enqueueCallback(el, el.__ceDef, 'disconnectedCallback', []); });
+}
+
+// An attribute of `el` changed (`oldValue` null when it was added).
+export function attributeChanged(el, name, oldValue) {
+  const def = el.__ce === CUSTOM ? el.__ceDef : undefined;
+  if (def === undefined || def.attributeChangedCallback === undefined || !def.observed.includes(name)) return;
+  enqueueCallback(el, def, 'attributeChangedCallback', [name, oldValue, el.getAttribute(name), null]);
+}
+
+// `node` was adopted from `oldDocument`: adoptedCallback for custom elements.
+export function adoptedNode(node, oldDocument, newDocument) {
+  eachElement(node, (el) => {
+    if (el.__ce === CUSTOM && el.__ceDef) enqueueCallback(el, el.__ceDef, 'adoptedCallback', [oldDocument, newDocument]);
+  });
+}
+
+// --------------------------------------------------- CustomElementRegistry ----
+
+// The window's registry over `document`: define / get / getName / whenDefined / upgrade.
+export function makeCustomElements(document) {
+  const reg = { document, defs: new Map() };
+  const waiters = new Map();
+  if (document) document.__ceRegistry = reg;
+  return {
+    define(name, ctor, options) {
+      name = String(name);
+      if (typeof ctor !== 'function') throw new TypeError("Failed to execute 'define' on 'CustomElementRegistry': The provided value is not a constructor");
+      if (reg.defs.has(name)) throw new Error(`'${name}' already defined`);
+      const localName = options && options.extends != null ? String(options.extends) : name;
+      const proto = ctor.prototype;
+      const def = { registry: reg, name, localName, ctor, stack: [], observed: [] };
+      for (const key of ['connectedCallback', 'disconnectedCallback', 'adoptedCallback', 'attributeChangedCallback']) {
+        const fn = proto[key];
+        def[key] = typeof fn === 'function' ? fn : undefined;
+      }
+      if (def.attributeChangedCallback !== undefined) {
+        const observed = ctor.observedAttributes;
+        if (observed != null) def.observed = Array.from(observed, String);
+      }
+      reg.defs.set(name, def);
+      definitions.set(ctor, def);
+      // upgrade the document's candidates in shadow-including tree order
+      if (document && document.__ceRegistry === reg) withReactions(eachElement, null, [document, (el) => {
+        if (el.localName === localName && customElementState(el) === UNDEFINED && lookup(reg, localName, isValue(el)) === def) enqueueUpgrade(el, def);
+      }]);
+      const w = waiters.get(name);
+      if (w) { w.forEach((resolve) => resolve(ctor)); waiters.delete(name); }
+    },
+    get(name) { const def = reg.defs.get(String(name)); return def ? def.ctor : undefined; },
+    getName(ctor) { for (const [n, def] of reg.defs) if (def.ctor === ctor) return n; return null; },
+    whenDefined(name) {
+      name = String(name);
+      const def = reg.defs.get(name);
+      if (def) return Promise.resolve(def.ctor);
+      return new Promise((resolve) => { const a = waiters.get(name) || []; a.push(resolve); waiters.set(name, a); });
+    },
+    upgrade(root) {
+      if (!root || typeof root.__children !== 'function') return;
+      withReactions(eachElement, null, [root, (el) => {
+        const def = el.ownerDocument && el.ownerDocument.__ceRegistry === reg && customElementState(el) === UNDEFINED
+          ? lookup(reg, el.localName, isValue(el)) : null;
+        if (def) enqueueUpgrade(el, def);
+      }]);
+    },
+  };
+}