thunderous 2.4.3 → 2.4.5-next.1776736743

package/dist/index.cjs

@@ -20,6 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  clearRenderState: () => clearRenderState,
+  clearServerCss: () => clearServerCss,
   clientOnlyCallback: () => clientOnlyCallback,
   createEffect: () => createEffect,
   createRegistry: () => createRegistry,
@@ -100,13 +102,14 @@ var createSignal = (initVal, options) => {
       const effectRef = effects.get(sym);
       if (effectRef !== void 0) {
         try {
-          effectRef.fn({
+          const result = effectRef.fn({
             lastValue: effectRef.value,
             destroy: () => {
               effects.delete(sym);
               queueMicrotask(() => subscribers.delete(sym));
             }
           });
+          if (result !== void 0) effectRef.value = result;
         } catch (error) {
           console.error("Error in subscriber:", { error, oldValue, newValue, fn: effectRef.fn });
         }
@@ -147,14 +150,16 @@ var derived = (fn, options) => {
 };
 var createEffect = (fn, value) => {
   const privateIdent = ident = {};
-  effects.set(ident, { fn, value });
+  const effectRef = { fn, value };
+  effects.set(ident, effectRef);
   try {
-    fn({
+    const result = fn({
       lastValue: value,
       destroy: () => {
         effects.delete(privateIdent);
       }
     });
+    if (result !== void 0) effectRef.value = result;
   } catch (error) {
     console.error("Error in effect:", { error, fn });
   }
@@ -163,12 +168,6 @@ var createEffect = (fn, value) => {
 
 // src/utilities.ts
 var NOOP = () => void 0;
-var queryComment = (node, comment) => {
-  const walker = document.createTreeWalker(node, NodeFilter.SHOW_COMMENT, {
-    acceptNode: (n) => n.nodeValue === comment ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP
-  });
-  return walker.nextNode();
-};
 var queryChildren = (children, selector) => {
   for (const child of children) {
     if (child instanceof Element && child.matches(selector)) {
@@ -184,6 +183,9 @@ var serverDefineFns = /* @__PURE__ */ new Set();
 var onServerDefine = (fn) => {
   serverDefineFns.add(fn);
 };
+var clearServerCss = () => {
+  serverCss.clear();
+};
 var serverDefine = ({
   tagName,
   serverRender,
@@ -321,7 +323,7 @@ var clientOnlyCallback = (fn) => {
 // src/render.ts
 var CALLBACK_BINDING_REGEX = /(\{\{callback:.+\}\})/;
 var LEGACY_CALLBACK_BINDING_REGEX = /(this.getRootNode\(\).host.__customCallbackFns.get\('.+'\)\(event\))/;
-var SIGNAL_BINDING_REGEX = /(\{\{signal:.+\}\})/;
+var SIGNAL_BINDING_REGEX = /(\{\{signal:.+?\}\})/;
 var FRAGMENT_ATTRIBUTE = "___thunderous-fragment";
 var renderState = {
   currentShadowRoot: null,
@@ -332,6 +334,13 @@ var renderState = {
   propertyMap: /* @__PURE__ */ new Map(),
   registry: typeof customElements !== "undefined" ? customElements : {}
 };
+var clearRenderState = () => {
+  renderState.signalMap.clear();
+  renderState.callbackMap.clear();
+  renderState.propertyMap.clear();
+  renderState.fragmentMap.clear();
+  renderState.childrenMap.clear();
+};
 var logPropertyWarning = (propName, element) => {
   console.warn(
     `Property "${propName}" does not exist on element:`,
@@ -339,19 +348,34 @@ var logPropertyWarning = (propName, element) => {
     "\n\nThunderous will attempt to set the property anyway, but this may result in unexpected behavior. Please make sure the property exists on the element prior to setting it."
   );
 };
-var asNodeList = (value, parent) => {
+var asNodeList = (value, parent, autoKey) => {
+  if (value === null || value === void 0) return [];
   if (typeof value === "string") return [new Text(value)];
-  if (value instanceof DocumentFragment) return [...value.children];
+  if (typeof value === "number" || typeof value === "boolean") return [new Text(String(value))];
+  if (value instanceof DocumentFragment) {
+    const children = Array.from(value.children);
+    if (autoKey !== void 0 && children.length > 0) {
+      const child = children[0];
+      if (child instanceof Element && child.getAttribute("key") === null) {
+        child.setAttribute("key", String(autoKey));
+      }
+    }
+    return children;
+  }
   if (Array.isArray(value)) {
     const nodeList = [];
     let count = 0;
     const keys = /* @__PURE__ */ new Set();
     for (const item of value) {
       const cachedItem = item instanceof DocumentFragment ? renderState.childrenMap.get(item) : void 0;
-      const children = cachedItem ?? asNodeList(item, parent);
+      const children = cachedItem ?? asNodeList(item, parent, item instanceof DocumentFragment ? count : void 0);
       if (cachedItem === void 0 && item instanceof DocumentFragment) {
         renderState.childrenMap.set(item, children);
       }
+      if (!(item instanceof DocumentFragment)) {
+        nodeList.push(...children);
+        continue;
+      }
       if (children.length > 1) {
         console.error(
           "When rendering arrays, fragments must contain only one top-level element at a time. Error occured in:",
@@ -404,73 +428,68 @@ var processValue = (value) => {
     renderState.callbackMap.set(uniqueKey, value);
     return isServer ? String(value()) : `{{callback:${uniqueKey}}}`;
   }
-  return String(value);
+  return value === null || value === void 0 ? "" : String(value);
 };
 var evaluateBindings = (element, fragment) => {
-  for (const child of [...element.childNodes]) {
+  for (const child of Array.from(element.childNodes)) {
     if (child instanceof Text && SIGNAL_BINDING_REGEX.test(child.data)) {
       const textList = child.data.split(SIGNAL_BINDING_REGEX);
-      const nextSibling = child.nextSibling;
-      const prevSibling = child.previousSibling;
-      textList.forEach((text, i) => {
+      const allInitialChildren = [];
+      const signalEntries = [];
+      let signalIndex = 0;
+      const totalSignals = textList.filter((t) => SIGNAL_BINDING_REGEX.test(t)).length;
+      textList.forEach((text) => {
         const uniqueKey = SIGNAL_BINDING_REGEX.test(text) ? text.replace(/\{\{signal:(.+)\}\}/, "$1") : void 0;
         const signal = uniqueKey !== void 0 ? renderState.signalMap.get(uniqueKey) : void 0;
         const newValue = signal !== void 0 ? signal() : text;
-        const initialChildren = asNodeList(newValue, element);
-        if (i === 0) {
-          child.replaceWith(...initialChildren);
-        } else {
-          const endAnchor2 = queryComment(element, `${uniqueKey}:end`) ?? nextSibling;
-          if (endAnchor2 !== null) {
-            endAnchor2.before(...initialChildren);
-          } else {
-            element.append(...initialChildren);
-          }
+        const autoKey = signal !== void 0 && totalSignals > 1 ? signalIndex++ : void 0;
+        const initialChildren = asNodeList(newValue, element, autoKey);
+        allInitialChildren.push(...initialChildren);
+        if (uniqueKey !== void 0 && signal !== void 0) {
+          signalEntries.push({ uniqueKey, signal, initialChildren, autoKey });
         }
-        if (uniqueKey === void 0) return;
+      });
+      child.replaceWith(...allInitialChildren);
+      signalEntries.forEach(({ uniqueKey, signal, initialChildren, autoKey }) => {
+        const firstChild = initialChildren[0];
+        const lastChild = initialChildren[initialChildren.length - 1];
+        if (firstChild === void 0) return;
         const startAnchor = document.createComment(`${uniqueKey}:start`);
-        if (prevSibling !== null) {
-          prevSibling.after(startAnchor);
-        } else {
-          element.prepend(startAnchor);
-        }
+        firstChild.before(startAnchor);
         const endAnchor = document.createComment(`${uniqueKey}:end`);
-        if (nextSibling !== null) {
-          nextSibling.before(endAnchor);
-        } else {
-          element.append(endAnchor);
-        }
+        lastChild.after(endAnchor);
         const bindText = (node, signal2) => {
           createEffect(({ destroy }) => {
             const result = signal2();
             if (Array.isArray(result)) {
               destroy();
-              bindArray(signal2);
+              bindArray(signal2, autoKey);
               return;
             }
             if (result instanceof DocumentFragment) {
               destroy();
-              bindFragment(signal2);
+              bindFragment(signal2, initialChildren, autoKey);
               return;
             }
-            node.data = result === null ? "" : String(result);
+            node.data = result === null || result === void 0 ? "" : String(result);
           });
         };
-        const bindArray = (signal2) => {
+        const bindArray = (signal2, autoKey2) => {
           createEffect(
             ({ lastValue: oldChildren, destroy }) => {
               const result = signal2();
-              const newChildren = asNodeList(result, element);
-              const firstChild = newChildren[0];
-              if (!Array.isArray(result) && newChildren.length === 1 && firstChild instanceof DocumentFragment) {
-                destroy();
-                bindFragment(signal2);
-                return;
-              }
-              if (newChildren.length === 1 && firstChild instanceof Text) {
-                destroy();
-                bindText(firstChild, signal2);
-                return;
+              const newChildren = asNodeList(result, element, autoKey2);
+              const firstChild2 = newChildren[0];
+              if (!Array.isArray(result)) {
+                if (newChildren.length === 1 && firstChild2 instanceof Text) {
+                  while (startAnchor.nextSibling !== endAnchor) {
+                    startAnchor.nextSibling?.remove();
+                  }
+                  startAnchor.after(firstChild2);
+                  destroy();
+                  bindText(firstChild2, signal2);
+                  return;
+                }
               }
               while (startAnchor.nextSibling !== endAnchor) {
                 startAnchor.nextSibling?.remove();
@@ -480,16 +499,15 @@ var evaluateBindings = (element, fragment) => {
               for (const persistedChild of oldChildren) {
                 if (persistedChild instanceof Element) {
                   const key = persistedChild.getAttribute("key");
-                  if (key === null) continue;
                   const newChild = queryChildren(newChildren, `[key="${key}"]`);
                   if (newChild === null) {
                     persistedChild.remove();
                     continue;
                   }
-                  for (const attr of [...persistedChild.attributes]) {
+                  for (const attr of Array.from(persistedChild.attributes)) {
                     if (!newChild.hasAttribute(attr.name)) persistedChild.removeAttribute(attr.name);
                   }
-                  for (const newAttr of [...newChild.attributes]) {
+                  for (const newAttr of Array.from(newChild.attributes)) {
                     const oldAttrValue = persistedChild.getAttribute(newAttr.name);
                     if (oldAttrValue?.startsWith("this.__customCallbackFns")) continue;
                     persistedChild.setAttribute(newAttr.name, newAttr.value);
@@ -502,40 +520,52 @@ var evaluateBindings = (element, fragment) => {
             null
           );
         };
-        const bindFragment = (signal2) => {
+        const bindFragment = (signal2, initialChildren2, autoKey2) => {
           const initialFragment = signal2();
-          renderState.childrenMap.set(initialFragment, [...initialFragment.childNodes]);
+          const firstInitialChild = initialChildren2[0];
+          if (firstInitialChild instanceof Element) {
+            renderState.childrenMap.set(initialFragment, initialChildren2);
+          }
           createEffect(({ destroy }) => {
             const result = signal2();
-            const cachedChildren = renderState.childrenMap.get(initialFragment);
-            const children = cachedChildren ?? asNodeList(result, element);
+            const cachedChildren = result instanceof DocumentFragment ? renderState.childrenMap.get(result) : void 0;
+            const children = cachedChildren ?? asNodeList(result, element, autoKey2);
+            if (result instanceof DocumentFragment && !renderState.childrenMap.has(result)) {
+              renderState.childrenMap.set(result, children);
+            }
             if (Array.isArray(result)) {
               destroy();
-              bindArray(signal2);
+              bindArray(signal2, autoKey2);
               return;
             }
-            if (result instanceof Text) {
-              const children2 = asNodeList(result, element);
-              const text2 = children2[0];
+            if (!(result instanceof DocumentFragment) && result !== null && result !== void 0) {
+              while (startAnchor.nextSibling !== endAnchor) {
+                startAnchor.nextSibling?.remove();
+              }
+              const children2 = asNodeList(result, element, autoKey2);
+              const text = children2[0];
+              startAnchor.after(text);
               destroy();
-              bindText(text2, signal2);
+              bindText(text, signal2);
               return;
             }
             while (startAnchor.nextSibling !== endAnchor) {
               startAnchor.nextSibling?.remove();
             }
+            if (result === null || result === void 0) {
+              return;
+            }
             startAnchor.after(...children);
           });
         };
-        if (signal !== void 0) {
-          if (Array.isArray(newValue)) {
-            bindArray(signal);
-          } else if (initialChildren instanceof DocumentFragment) {
-            bindFragment(signal);
-          } else {
-            const initialChild = initialChildren[0];
-            bindText(initialChild, signal);
-          }
+        const currentValue = signal();
+        if (Array.isArray(currentValue)) {
+          bindArray(signal, autoKey);
+        } else if (currentValue instanceof DocumentFragment) {
+          bindFragment(signal, initialChildren, autoKey);
+        } else {
+          const initialChild = initialChildren[0];
+          bindText(initialChild, signal);
         }
       });
     }
@@ -546,7 +576,7 @@ var evaluateBindings = (element, fragment) => {
         child.replaceWith(childFragment);
       }
     } else if (child instanceof Element) {
-      for (const attr of [...child.attributes]) {
+      for (const attr of Array.from(child.attributes)) {
         const attrName = attr.name;
         if (SIGNAL_BINDING_REGEX.test(attr.value)) {
           const textList = attr.value.split(SIGNAL_BINDING_REGEX);
@@ -572,7 +602,6 @@ var evaluateBindings = (element, fragment) => {
               if (newText !== prevText) child.setAttribute(attrName, newText);
             }
             if (attrName.startsWith("prop-id:")) {
-              if (child.hasAttribute(attrName)) child.removeAttribute(attrName);
               const propId = attrName.replace("prop-id:", "");
               const propName = renderState.propertyMap.get(propId);
               if (propName === void 0) {
@@ -607,9 +636,7 @@ var evaluateBindings = (element, fragment) => {
                 child.__customCallbackFns.set(uniqueKey, callback);
               }
             }
-            if (uniqueKey !== "" && !attrName.startsWith("prop-id:")) {
-              child.setAttribute(attrName, `this.__customCallbackFns.get('${uniqueKey}')(event)`);
-            } else if (attrName.startsWith("prop-id:")) {
+            if (attrName.startsWith("prop-id:")) {
               child.removeAttribute(attrName);
               const propId = attrName.replace("prop-id:", "");
               const propName = renderState.propertyMap.get(propId);
@@ -622,6 +649,8 @@ var evaluateBindings = (element, fragment) => {
               }
               if (!(propName in child)) logPropertyWarning(propName, child);
               child[propName] = child.__customCallbackFns.get(uniqueKey);
+            } else {
+              child.setAttribute(attrName, `this.__customCallbackFns.get('${uniqueKey}')(event)`);
             }
           });
         } else if (attrName.startsWith("prop-id:")) {
@@ -651,7 +680,7 @@ var html = (strings, ...values) => {
     } else {
       value = processValue(value);
     }
-    innerHTML2 += str + String(value === null ? "" : value);
+    innerHTML2 += str + String(value);
     return innerHTML2;
   }, "");
   if (isServer) return innerHTML;
@@ -672,7 +701,7 @@ var html = (strings, ...values) => {
   evaluateBindings(fragment, fragment);
   return fragment;
 };
-var adoptedStylesSupported = typeof window !== "undefined" && window.ShadowRoot?.prototype.hasOwnProperty("adoptedStyleSheets") && window.CSSStyleSheet?.prototype.hasOwnProperty("replace");
+var isAdoptedStylesSupported = () => typeof window !== "undefined" && window.ShadowRoot?.prototype.hasOwnProperty("adoptedStyleSheets") && window.CSSStyleSheet?.prototype.hasOwnProperty("replace");
 var isCSSStyleSheet = (stylesheet) => {
   return typeof CSSStyleSheet !== "undefined" && stylesheet instanceof CSSStyleSheet;
 };
@@ -696,7 +725,7 @@ var css = (strings, ...values) => {
   if (isServer) {
     return cssText;
   }
-  const stylesheet = adoptedStylesSupported ? new CSSStyleSheet() : document.createElement("style");
+  const stylesheet = isAdoptedStylesSupported() ? new CSSStyleSheet() : document.createElement("style");
   const textList = cssText.split(signalBindingRegex);
   createEffect(() => {
     const newCSSTextList = [];
@@ -803,8 +832,9 @@ var customElement = (render, options) => {
     #observer = options?.observedAttributes !== void 0 ? null : new MutationObserver((mutations) => {
       for (const mutation of mutations) {
         const attrName = mutation.attributeName;
-        if (mutation.type !== "attributes" || attrName === null) continue;
-        if (!(attrName in this.#attrSignals)) this.#attrSignals[attrName] = createSignal(null);
+        if (!(attrName in this.#attrSignals)) {
+          this.#attrSignals[attrName] = createSignal(this.getAttribute(attrName));
+        }
         const [getter, setter] = this.#attrSignals[attrName];
         const oldValue = getter();
         const newValue = this.getAttribute(attrName);
@@ -904,7 +934,9 @@ You must set an initial value before calling a property signal's getter.
           {},
           {
             get: (_, prop) => {
-              if (!(prop in this.#attrSignals)) this.#attrSignals[prop] = createSignal(null);
+              if (!(prop in this.#attrSignals)) {
+                this.#attrSignals[prop] = createSignal(this.getAttribute(prop));
+              }
               const [getter] = this.#attrSignals[prop];
               const setter = (newValue) => this.setAttribute(prop, newValue);
               return [getter, setter];
@@ -973,9 +1005,7 @@ You must set an initial value before calling a property signal's getter.
     constructor() {
       try {
         super();
-        if (!Object.prototype.hasOwnProperty.call(this, "__customCallbackFns")) {
-          this.__customCallbackFns = /* @__PURE__ */ new Map();
-        }
+        this.__customCallbackFns = /* @__PURE__ */ new Map();
         for (const attr of this.attributes) {
           this.#attrSignals[attr.name] = createSignal(attr.value);
         }
@@ -986,12 +1016,13 @@ You must set an initial value before calling a property signal's getter.
           { cause: error }
         );
         console.error(_error);
-        throw _error;
       }
     }
     connectedCallback() {
       for (const [attrName, attr] of this.#attributesAsPropertiesMap) {
-        if (!(attrName in this.#attrSignals)) this.#attrSignals[attrName] = createSignal(null);
+        if (!(attrName in this.#attrSignals)) {
+          this.#attrSignals[attrName] = createSignal(this.getAttribute(attrName));
+        }
         const propName = attr.prop;
         const [getter] = this.#getPropSignal(propName, { allowUndefined: true });
         let busy = false;
@@ -1008,6 +1039,14 @@ You must set an initial value before calling a property signal's getter.
           busy = false;
         });
       }
+      for (const attrName of Object.keys(this.#attrSignals)) {
+        const signal = this.#attrSignals[attrName];
+        const [getter, setter] = signal;
+        const currentValue = this.getAttribute(attrName);
+        if (getter() !== currentValue) {
+          setter(currentValue);
+        }
+      }
       if (this.#observer !== null) {
         this.#observer.observe(this, { attributes: true });
       }
@@ -1176,6 +1215,8 @@ var createRegistry = (args) => {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  clearRenderState,
+  clearServerCss,
   clientOnlyCallback,
   createEffect,
   createRegistry,

package/dist/index.d.cts

@@ -94,7 +94,7 @@ type RegistryArgs = {
 
 type Styles = CSSStyleSheet | HTMLStyleElement;
 
-type SignalOptions = { debugMode: boolean; label?: string };
+type SignalOptions = { debugMode?: boolean; label?: string };
 type SignalGetter<T> = {
 	(options?: SignalOptions): T;
 	getter: true;
@@ -143,7 +143,41 @@ declare const customElement: <Props extends CustomElementProps>(render: RenderFu
  */
 declare const createRegistry: (args?: RegistryArgs) => RegistryResult;
 
+/**
+ * Add a callback to handle each call to `define()` on the server.
+ *
+ * This enables you to intercept those definitions and respond to them,
+ * for example to inject declarative shadow DOM templates.
+ *
+ * @example
+ * ```ts
+ * let response = originalResponse;
+ * onServerDefine((tagName, htmlString) => {
+ *   // ...
+ *   response = htmlString.replace(tagName, `my-${tagName}`);
+ * });
+ * ```
+ */
 declare const onServerDefine: (fn: ServerDefineFn) => void;
+/**
+ * Thunderous tracks its state using several maps to associate values with
+ * their respective elements.
+ *
+ * This function clears the map that tracks CSS on the server side, to prevent
+ * memory leaks and purge stale data from previous renders.
+ *
+ * If you are building a framework or plugin that depends on Thunderous, you
+ * should call this function before every render. Otherwise, the map will
+ * accumulate stale data and may create significant performance issues.
+ *
+ * @example
+ * ```ts
+ * import { clearServerCss } from 'thunderous'
+ *
+ * clearServerCss();
+ * ```
+ */
+declare const clearServerCss: () => void;
 declare const insertTemplates: (tagName: string, template: string, inputString: string) => string;
 declare const clientOnlyCallback: (fn: (() => void) | (() => Promise<void>)) => void | Promise<void>;
 
@@ -178,10 +212,29 @@ declare const derived: <T>(fn: () => T, options?: SignalOptions) => SignalGetter
  */
 declare const createEffect: <T = unknown>(fn: Effect<T>, value?: T) => void;
 
+/**
+ * Thunderous tracks its state using several maps to associate values with
+ * their respective elements.
+ *
+ * This function clears the maps tracking render state, to prevent memory
+ * leaks and purge stale data from previous renders.
+ *
+ * If you are building a framework or plugin that depends on Thunderous, you
+ * should call this function before every render. Otherwise, the maps will
+ * accumulate stale data and may create significant performance issues.
+ *
+ * @example
+ * ```ts
+ * import { clearRenderState } from 'thunderous'
+ *
+ * clearRenderState();
+ * ```
+ */
+declare const clearRenderState: () => void;
 /**
  * A tagged template function for creating DocumentFragment instances.
  */
 declare const html: (strings: TemplateStringsArray, ...values: unknown[]) => DocumentFragment;
 declare const css: (strings: TemplateStringsArray, ...values: unknown[]) => Styles;
 
-export { type ElementResult, type HTMLCustomElement, type RegistryResult, type RenderArgs, type RenderFunction, type Signal, type SignalGetter, type SignalSetter, clientOnlyCallback, createEffect, createRegistry, createSignal, css, customElement, derived, html, insertTemplates, onServerDefine };
+export { type ElementResult, type HTMLCustomElement, type RegistryResult, type RenderArgs, type RenderFunction, type Signal, type SignalGetter, type SignalSetter, clearRenderState, clearServerCss, clientOnlyCallback, createEffect, createRegistry, createSignal, css, customElement, derived, html, insertTemplates, onServerDefine };

package/dist/index.d.ts

@@ -94,7 +94,7 @@ type RegistryArgs = {
 
 type Styles = CSSStyleSheet | HTMLStyleElement;
 
-type SignalOptions = { debugMode: boolean; label?: string };
+type SignalOptions = { debugMode?: boolean; label?: string };
 type SignalGetter<T> = {
 	(options?: SignalOptions): T;
 	getter: true;
@@ -143,7 +143,41 @@ declare const customElement: <Props extends CustomElementProps>(render: RenderFu
  */
 declare const createRegistry: (args?: RegistryArgs) => RegistryResult;
 
+/**
+ * Add a callback to handle each call to `define()` on the server.
+ *
+ * This enables you to intercept those definitions and respond to them,
+ * for example to inject declarative shadow DOM templates.
+ *
+ * @example
+ * ```ts
+ * let response = originalResponse;
+ * onServerDefine((tagName, htmlString) => {
+ *   // ...
+ *   response = htmlString.replace(tagName, `my-${tagName}`);
+ * });
+ * ```
+ */
 declare const onServerDefine: (fn: ServerDefineFn) => void;
+/**
+ * Thunderous tracks its state using several maps to associate values with
+ * their respective elements.
+ *
+ * This function clears the map that tracks CSS on the server side, to prevent
+ * memory leaks and purge stale data from previous renders.
+ *
+ * If you are building a framework or plugin that depends on Thunderous, you
+ * should call this function before every render. Otherwise, the map will
+ * accumulate stale data and may create significant performance issues.
+ *
+ * @example
+ * ```ts
+ * import { clearServerCss } from 'thunderous'
+ *
+ * clearServerCss();
+ * ```
+ */
+declare const clearServerCss: () => void;
 declare const insertTemplates: (tagName: string, template: string, inputString: string) => string;
 declare const clientOnlyCallback: (fn: (() => void) | (() => Promise<void>)) => void | Promise<void>;
 
@@ -178,10 +212,29 @@ declare const derived: <T>(fn: () => T, options?: SignalOptions) => SignalGetter
  */
 declare const createEffect: <T = unknown>(fn: Effect<T>, value?: T) => void;
 
+/**
+ * Thunderous tracks its state using several maps to associate values with
+ * their respective elements.
+ *
+ * This function clears the maps tracking render state, to prevent memory
+ * leaks and purge stale data from previous renders.
+ *
+ * If you are building a framework or plugin that depends on Thunderous, you
+ * should call this function before every render. Otherwise, the maps will
+ * accumulate stale data and may create significant performance issues.
+ *
+ * @example
+ * ```ts
+ * import { clearRenderState } from 'thunderous'
+ *
+ * clearRenderState();
+ * ```
+ */
+declare const clearRenderState: () => void;
 /**
  * A tagged template function for creating DocumentFragment instances.
  */
 declare const html: (strings: TemplateStringsArray, ...values: unknown[]) => DocumentFragment;
 declare const css: (strings: TemplateStringsArray, ...values: unknown[]) => Styles;
 
-export { type ElementResult, type HTMLCustomElement, type RegistryResult, type RenderArgs, type RenderFunction, type Signal, type SignalGetter, type SignalSetter, clientOnlyCallback, createEffect, createRegistry, createSignal, css, customElement, derived, html, insertTemplates, onServerDefine };
+export { type ElementResult, type HTMLCustomElement, type RegistryResult, type RenderArgs, type RenderFunction, type Signal, type SignalGetter, type SignalSetter, clearRenderState, clearServerCss, clientOnlyCallback, createEffect, createRegistry, createSignal, css, customElement, derived, html, insertTemplates, onServerDefine };

package/dist/index.js

@@ -65,13 +65,14 @@ var createSignal = (initVal, options) => {
       const effectRef = effects.get(sym);
       if (effectRef !== void 0) {
         try {
-          effectRef.fn({
+          const result = effectRef.fn({
             lastValue: effectRef.value,
             destroy: () => {
               effects.delete(sym);
               queueMicrotask(() => subscribers.delete(sym));
             }
           });
+          if (result !== void 0) effectRef.value = result;
         } catch (error) {
           console.error("Error in subscriber:", { error, oldValue, newValue, fn: effectRef.fn });
         }
@@ -112,14 +113,16 @@ var derived = (fn, options) => {
 };
 var createEffect = (fn, value) => {
   const privateIdent = ident = {};
-  effects.set(ident, { fn, value });
+  const effectRef = { fn, value };
+  effects.set(ident, effectRef);
   try {
-    fn({
+    const result = fn({
       lastValue: value,
       destroy: () => {
         effects.delete(privateIdent);
       }
     });
+    if (result !== void 0) effectRef.value = result;
   } catch (error) {
     console.error("Error in effect:", { error, fn });
   }
@@ -128,12 +131,6 @@ var createEffect = (fn, value) => {
 
 // src/utilities.ts
 var NOOP = () => void 0;
-var queryComment = (node, comment) => {
-  const walker = document.createTreeWalker(node, NodeFilter.SHOW_COMMENT, {
-    acceptNode: (n) => n.nodeValue === comment ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP
-  });
-  return walker.nextNode();
-};
 var queryChildren = (children, selector) => {
   for (const child of children) {
     if (child instanceof Element && child.matches(selector)) {
@@ -149,6 +146,9 @@ var serverDefineFns = /* @__PURE__ */ new Set();
 var onServerDefine = (fn) => {
   serverDefineFns.add(fn);
 };
+var clearServerCss = () => {
+  serverCss.clear();
+};
 var serverDefine = ({
   tagName,
   serverRender,
@@ -286,7 +286,7 @@ var clientOnlyCallback = (fn) => {
 // src/render.ts
 var CALLBACK_BINDING_REGEX = /(\{\{callback:.+\}\})/;
 var LEGACY_CALLBACK_BINDING_REGEX = /(this.getRootNode\(\).host.__customCallbackFns.get\('.+'\)\(event\))/;
-var SIGNAL_BINDING_REGEX = /(\{\{signal:.+\}\})/;
+var SIGNAL_BINDING_REGEX = /(\{\{signal:.+?\}\})/;
 var FRAGMENT_ATTRIBUTE = "___thunderous-fragment";
 var renderState = {
   currentShadowRoot: null,
@@ -297,6 +297,13 @@ var renderState = {
   propertyMap: /* @__PURE__ */ new Map(),
   registry: typeof customElements !== "undefined" ? customElements : {}
 };
+var clearRenderState = () => {
+  renderState.signalMap.clear();
+  renderState.callbackMap.clear();
+  renderState.propertyMap.clear();
+  renderState.fragmentMap.clear();
+  renderState.childrenMap.clear();
+};
 var logPropertyWarning = (propName, element) => {
   console.warn(
     `Property "${propName}" does not exist on element:`,
@@ -304,19 +311,34 @@ var logPropertyWarning = (propName, element) => {
     "\n\nThunderous will attempt to set the property anyway, but this may result in unexpected behavior. Please make sure the property exists on the element prior to setting it."
   );
 };
-var asNodeList = (value, parent) => {
+var asNodeList = (value, parent, autoKey) => {
+  if (value === null || value === void 0) return [];
   if (typeof value === "string") return [new Text(value)];
-  if (value instanceof DocumentFragment) return [...value.children];
+  if (typeof value === "number" || typeof value === "boolean") return [new Text(String(value))];
+  if (value instanceof DocumentFragment) {
+    const children = Array.from(value.children);
+    if (autoKey !== void 0 && children.length > 0) {
+      const child = children[0];
+      if (child instanceof Element && child.getAttribute("key") === null) {
+        child.setAttribute("key", String(autoKey));
+      }
+    }
+    return children;
+  }
   if (Array.isArray(value)) {
     const nodeList = [];
     let count = 0;
     const keys = /* @__PURE__ */ new Set();
     for (const item of value) {
       const cachedItem = item instanceof DocumentFragment ? renderState.childrenMap.get(item) : void 0;
-      const children = cachedItem ?? asNodeList(item, parent);
+      const children = cachedItem ?? asNodeList(item, parent, item instanceof DocumentFragment ? count : void 0);
       if (cachedItem === void 0 && item instanceof DocumentFragment) {
         renderState.childrenMap.set(item, children);
       }
+      if (!(item instanceof DocumentFragment)) {
+        nodeList.push(...children);
+        continue;
+      }
       if (children.length > 1) {
         console.error(
           "When rendering arrays, fragments must contain only one top-level element at a time. Error occured in:",
@@ -369,73 +391,68 @@ var processValue = (value) => {
     renderState.callbackMap.set(uniqueKey, value);
     return isServer ? String(value()) : `{{callback:${uniqueKey}}}`;
   }
-  return String(value);
+  return value === null || value === void 0 ? "" : String(value);
 };
 var evaluateBindings = (element, fragment) => {
-  for (const child of [...element.childNodes]) {
+  for (const child of Array.from(element.childNodes)) {
     if (child instanceof Text && SIGNAL_BINDING_REGEX.test(child.data)) {
       const textList = child.data.split(SIGNAL_BINDING_REGEX);
-      const nextSibling = child.nextSibling;
-      const prevSibling = child.previousSibling;
-      textList.forEach((text, i) => {
+      const allInitialChildren = [];
+      const signalEntries = [];
+      let signalIndex = 0;
+      const totalSignals = textList.filter((t) => SIGNAL_BINDING_REGEX.test(t)).length;
+      textList.forEach((text) => {
         const uniqueKey = SIGNAL_BINDING_REGEX.test(text) ? text.replace(/\{\{signal:(.+)\}\}/, "$1") : void 0;
         const signal = uniqueKey !== void 0 ? renderState.signalMap.get(uniqueKey) : void 0;
         const newValue = signal !== void 0 ? signal() : text;
-        const initialChildren = asNodeList(newValue, element);
-        if (i === 0) {
-          child.replaceWith(...initialChildren);
-        } else {
-          const endAnchor2 = queryComment(element, `${uniqueKey}:end`) ?? nextSibling;
-          if (endAnchor2 !== null) {
-            endAnchor2.before(...initialChildren);
-          } else {
-            element.append(...initialChildren);
-          }
+        const autoKey = signal !== void 0 && totalSignals > 1 ? signalIndex++ : void 0;
+        const initialChildren = asNodeList(newValue, element, autoKey);
+        allInitialChildren.push(...initialChildren);
+        if (uniqueKey !== void 0 && signal !== void 0) {
+          signalEntries.push({ uniqueKey, signal, initialChildren, autoKey });
         }
-        if (uniqueKey === void 0) return;
+      });
+      child.replaceWith(...allInitialChildren);
+      signalEntries.forEach(({ uniqueKey, signal, initialChildren, autoKey }) => {
+        const firstChild = initialChildren[0];
+        const lastChild = initialChildren[initialChildren.length - 1];
+        if (firstChild === void 0) return;
         const startAnchor = document.createComment(`${uniqueKey}:start`);
-        if (prevSibling !== null) {
-          prevSibling.after(startAnchor);
-        } else {
-          element.prepend(startAnchor);
-        }
+        firstChild.before(startAnchor);
         const endAnchor = document.createComment(`${uniqueKey}:end`);
-        if (nextSibling !== null) {
-          nextSibling.before(endAnchor);
-        } else {
-          element.append(endAnchor);
-        }
+        lastChild.after(endAnchor);
         const bindText = (node, signal2) => {
           createEffect(({ destroy }) => {
             const result = signal2();
             if (Array.isArray(result)) {
               destroy();
-              bindArray(signal2);
+              bindArray(signal2, autoKey);
               return;
             }
             if (result instanceof DocumentFragment) {
               destroy();
-              bindFragment(signal2);
+              bindFragment(signal2, initialChildren, autoKey);
               return;
             }
-            node.data = result === null ? "" : String(result);
+            node.data = result === null || result === void 0 ? "" : String(result);
           });
         };
-        const bindArray = (signal2) => {
+        const bindArray = (signal2, autoKey2) => {
           createEffect(
             ({ lastValue: oldChildren, destroy }) => {
               const result = signal2();
-              const newChildren = asNodeList(result, element);
-              const firstChild = newChildren[0];
-              if (!Array.isArray(result) && newChildren.length === 1 && firstChild instanceof DocumentFragment) {
-                destroy();
-                bindFragment(signal2);
-                return;
-              }
-              if (newChildren.length === 1 && firstChild instanceof Text) {
-                destroy();
-                bindText(firstChild, signal2);
-                return;
+              const newChildren = asNodeList(result, element, autoKey2);
+              const firstChild2 = newChildren[0];
+              if (!Array.isArray(result)) {
+                if (newChildren.length === 1 && firstChild2 instanceof Text) {
+                  while (startAnchor.nextSibling !== endAnchor) {
+                    startAnchor.nextSibling?.remove();
+                  }
+                  startAnchor.after(firstChild2);
+                  destroy();
+                  bindText(firstChild2, signal2);
+                  return;
+                }
               }
               while (startAnchor.nextSibling !== endAnchor) {
                 startAnchor.nextSibling?.remove();
@@ -445,16 +462,15 @@ var evaluateBindings = (element, fragment) => {
               for (const persistedChild of oldChildren) {
                 if (persistedChild instanceof Element) {
                   const key = persistedChild.getAttribute("key");
-                  if (key === null) continue;
                   const newChild = queryChildren(newChildren, `[key="${key}"]`);
                   if (newChild === null) {
                     persistedChild.remove();
                     continue;
                   }
-                  for (const attr of [...persistedChild.attributes]) {
+                  for (const attr of Array.from(persistedChild.attributes)) {
                     if (!newChild.hasAttribute(attr.name)) persistedChild.removeAttribute(attr.name);
                   }
-                  for (const newAttr of [...newChild.attributes]) {
+                  for (const newAttr of Array.from(newChild.attributes)) {
                     const oldAttrValue = persistedChild.getAttribute(newAttr.name);
                     if (oldAttrValue?.startsWith("this.__customCallbackFns")) continue;
                     persistedChild.setAttribute(newAttr.name, newAttr.value);
@@ -467,40 +483,52 @@ var evaluateBindings = (element, fragment) => {
             null
           );
         };
-        const bindFragment = (signal2) => {
+        const bindFragment = (signal2, initialChildren2, autoKey2) => {
           const initialFragment = signal2();
-          renderState.childrenMap.set(initialFragment, [...initialFragment.childNodes]);
+          const firstInitialChild = initialChildren2[0];
+          if (firstInitialChild instanceof Element) {
+            renderState.childrenMap.set(initialFragment, initialChildren2);
+          }
           createEffect(({ destroy }) => {
             const result = signal2();
-            const cachedChildren = renderState.childrenMap.get(initialFragment);
-            const children = cachedChildren ?? asNodeList(result, element);
+            const cachedChildren = result instanceof DocumentFragment ? renderState.childrenMap.get(result) : void 0;
+            const children = cachedChildren ?? asNodeList(result, element, autoKey2);
+            if (result instanceof DocumentFragment && !renderState.childrenMap.has(result)) {
+              renderState.childrenMap.set(result, children);
+            }
             if (Array.isArray(result)) {
               destroy();
-              bindArray(signal2);
+              bindArray(signal2, autoKey2);
               return;
             }
-            if (result instanceof Text) {
-              const children2 = asNodeList(result, element);
-              const text2 = children2[0];
+            if (!(result instanceof DocumentFragment) && result !== null && result !== void 0) {
+              while (startAnchor.nextSibling !== endAnchor) {
+                startAnchor.nextSibling?.remove();
+              }
+              const children2 = asNodeList(result, element, autoKey2);
+              const text = children2[0];
+              startAnchor.after(text);
               destroy();
-              bindText(text2, signal2);
+              bindText(text, signal2);
               return;
             }
             while (startAnchor.nextSibling !== endAnchor) {
               startAnchor.nextSibling?.remove();
             }
+            if (result === null || result === void 0) {
+              return;
+            }
             startAnchor.after(...children);
           });
         };
-        if (signal !== void 0) {
-          if (Array.isArray(newValue)) {
-            bindArray(signal);
-          } else if (initialChildren instanceof DocumentFragment) {
-            bindFragment(signal);
-          } else {
-            const initialChild = initialChildren[0];
-            bindText(initialChild, signal);
-          }
+        const currentValue = signal();
+        if (Array.isArray(currentValue)) {
+          bindArray(signal, autoKey);
+        } else if (currentValue instanceof DocumentFragment) {
+          bindFragment(signal, initialChildren, autoKey);
+        } else {
+          const initialChild = initialChildren[0];
+          bindText(initialChild, signal);
         }
       });
     }
@@ -511,7 +539,7 @@ var evaluateBindings = (element, fragment) => {
         child.replaceWith(childFragment);
       }
     } else if (child instanceof Element) {
-      for (const attr of [...child.attributes]) {
+      for (const attr of Array.from(child.attributes)) {
         const attrName = attr.name;
         if (SIGNAL_BINDING_REGEX.test(attr.value)) {
           const textList = attr.value.split(SIGNAL_BINDING_REGEX);
@@ -537,7 +565,6 @@ var evaluateBindings = (element, fragment) => {
               if (newText !== prevText) child.setAttribute(attrName, newText);
             }
             if (attrName.startsWith("prop-id:")) {
-              if (child.hasAttribute(attrName)) child.removeAttribute(attrName);
               const propId = attrName.replace("prop-id:", "");
               const propName = renderState.propertyMap.get(propId);
               if (propName === void 0) {
@@ -572,9 +599,7 @@ var evaluateBindings = (element, fragment) => {
                 child.__customCallbackFns.set(uniqueKey, callback);
               }
             }
-            if (uniqueKey !== "" && !attrName.startsWith("prop-id:")) {
-              child.setAttribute(attrName, `this.__customCallbackFns.get('${uniqueKey}')(event)`);
-            } else if (attrName.startsWith("prop-id:")) {
+            if (attrName.startsWith("prop-id:")) {
               child.removeAttribute(attrName);
               const propId = attrName.replace("prop-id:", "");
               const propName = renderState.propertyMap.get(propId);
@@ -587,6 +612,8 @@ var evaluateBindings = (element, fragment) => {
               }
               if (!(propName in child)) logPropertyWarning(propName, child);
               child[propName] = child.__customCallbackFns.get(uniqueKey);
+            } else {
+              child.setAttribute(attrName, `this.__customCallbackFns.get('${uniqueKey}')(event)`);
             }
           });
         } else if (attrName.startsWith("prop-id:")) {
@@ -616,7 +643,7 @@ var html = (strings, ...values) => {
     } else {
       value = processValue(value);
     }
-    innerHTML2 += str + String(value === null ? "" : value);
+    innerHTML2 += str + String(value);
     return innerHTML2;
   }, "");
   if (isServer) return innerHTML;
@@ -637,7 +664,7 @@ var html = (strings, ...values) => {
   evaluateBindings(fragment, fragment);
   return fragment;
 };
-var adoptedStylesSupported = typeof window !== "undefined" && window.ShadowRoot?.prototype.hasOwnProperty("adoptedStyleSheets") && window.CSSStyleSheet?.prototype.hasOwnProperty("replace");
+var isAdoptedStylesSupported = () => typeof window !== "undefined" && window.ShadowRoot?.prototype.hasOwnProperty("adoptedStyleSheets") && window.CSSStyleSheet?.prototype.hasOwnProperty("replace");
 var isCSSStyleSheet = (stylesheet) => {
   return typeof CSSStyleSheet !== "undefined" && stylesheet instanceof CSSStyleSheet;
 };
@@ -661,7 +688,7 @@ var css = (strings, ...values) => {
   if (isServer) {
     return cssText;
   }
-  const stylesheet = adoptedStylesSupported ? new CSSStyleSheet() : document.createElement("style");
+  const stylesheet = isAdoptedStylesSupported() ? new CSSStyleSheet() : document.createElement("style");
   const textList = cssText.split(signalBindingRegex);
   createEffect(() => {
     const newCSSTextList = [];
@@ -768,8 +795,9 @@ var customElement = (render, options) => {
     #observer = options?.observedAttributes !== void 0 ? null : new MutationObserver((mutations) => {
       for (const mutation of mutations) {
         const attrName = mutation.attributeName;
-        if (mutation.type !== "attributes" || attrName === null) continue;
-        if (!(attrName in this.#attrSignals)) this.#attrSignals[attrName] = createSignal(null);
+        if (!(attrName in this.#attrSignals)) {
+          this.#attrSignals[attrName] = createSignal(this.getAttribute(attrName));
+        }
         const [getter, setter] = this.#attrSignals[attrName];
         const oldValue = getter();
         const newValue = this.getAttribute(attrName);
@@ -869,7 +897,9 @@ You must set an initial value before calling a property signal's getter.
           {},
           {
             get: (_, prop) => {
-              if (!(prop in this.#attrSignals)) this.#attrSignals[prop] = createSignal(null);
+              if (!(prop in this.#attrSignals)) {
+                this.#attrSignals[prop] = createSignal(this.getAttribute(prop));
+              }
               const [getter] = this.#attrSignals[prop];
               const setter = (newValue) => this.setAttribute(prop, newValue);
               return [getter, setter];
@@ -938,9 +968,7 @@ You must set an initial value before calling a property signal's getter.
     constructor() {
       try {
         super();
-        if (!Object.prototype.hasOwnProperty.call(this, "__customCallbackFns")) {
-          this.__customCallbackFns = /* @__PURE__ */ new Map();
-        }
+        this.__customCallbackFns = /* @__PURE__ */ new Map();
         for (const attr of this.attributes) {
           this.#attrSignals[attr.name] = createSignal(attr.value);
         }
@@ -951,12 +979,13 @@ You must set an initial value before calling a property signal's getter.
           { cause: error }
         );
         console.error(_error);
-        throw _error;
       }
     }
     connectedCallback() {
       for (const [attrName, attr] of this.#attributesAsPropertiesMap) {
-        if (!(attrName in this.#attrSignals)) this.#attrSignals[attrName] = createSignal(null);
+        if (!(attrName in this.#attrSignals)) {
+          this.#attrSignals[attrName] = createSignal(this.getAttribute(attrName));
+        }
         const propName = attr.prop;
         const [getter] = this.#getPropSignal(propName, { allowUndefined: true });
         let busy = false;
@@ -973,6 +1002,14 @@ You must set an initial value before calling a property signal's getter.
           busy = false;
         });
       }
+      for (const attrName of Object.keys(this.#attrSignals)) {
+        const signal = this.#attrSignals[attrName];
+        const [getter, setter] = signal;
+        const currentValue = this.getAttribute(attrName);
+        if (getter() !== currentValue) {
+          setter(currentValue);
+        }
+      }
       if (this.#observer !== null) {
         this.#observer.observe(this, { attributes: true });
       }
@@ -1140,6 +1177,8 @@ var createRegistry = (args) => {
   };
 };
 export {
+  clearRenderState,
+  clearServerCss,
   clientOnlyCallback,
   createEffect,
   createRegistry,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thunderous",
-  "version": "2.4.3",
+  "version": "2.4.5-next.1776736743",
   "description": "A lightweight, functional web components library that brings the power of signals to your UI.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -15,7 +15,8 @@
   "author": "Jonathan DeWitt <jon.dewitt@thunder.solutions>",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Thunder-Solutions/Thunderous"
+    "url": "https://github.com/Thunder-Solutions/Thunderous",
+    "directory": "packages/thunderous"
   },
   "keywords": [
     "thunderous",
@@ -27,7 +28,7 @@
   "bugs": {
     "url": "https://github.com/Thunder-Solutions/Thunderous/issues"
   },
-  "homepage": "https://github.com/Thunder-Solutions/Thunderous#readme",
+  "homepage": "https://thunderous.dev",
   "license": "MIT",
   "peerDependencies": {
     "@webcomponents/scoped-custom-element-registry": "^0.0.10"
@@ -37,19 +38,29 @@
       "optional": true
     }
   },
+  "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "@vitest/browser": "^4.1.4",
+    "@vitest/browser-playwright": "^4.1.4",
+    "@vitest/coverage-istanbul": "^4.1.4",
+    "istanbul-merge": "^2.0.0",
+    "nyc": "^18.0.0",
+    "vitest": "^4.1.4"
+  },
   "scripts": {
     "demo": "cd demo && npm start",
-    "demo:ssr": "cd demo && npm run ssr",
+    "demo:ssr": "cd demo && pnpm ssr",
     "build": "tsup src/index.ts --format cjs,esm --dts --no-clean",
-    "test": "npm run test:server && npm run test:client",
-    "test:server": "find src/__test__/server -name '*.test.ts' | xargs c8 tsx --test",
-    "test:client": "PLAYWRIGHT_BROWSERS_PATH=../../.browsers playwright test",
+    "clean": "rm -rf dist",
+    "test": "pnpm test:server & pnpm test:client && pnpm coverage",
+    "test:server": "vitest run --config vitest.server.config.ts --coverage",
+    "test:client": "vitest run --config vitest.client.config.ts --coverage",
+    "coverage": "istanbul-merge --out ./coverage/merged/coverage-final.json ./coverage/server/coverage-final.json ./coverage/client/coverage-final.json && nyc report && nyc check-coverage",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --check . --ignore-path ../../.gitignore",
     "format:fix": "prettier --write . --ignore-path ../../.gitignore",
-    "preversion": "npm run typecheck && npm run lint && npm test && npm run build",
     "version": "node postversion.js"
   }
 }