docs: comments for nuanced code

Author: aidenybai

src/browser.ts

@@ -1,7 +1,14 @@
+// This file is only provided in IIFE builds
+// Including this file doesn't allow Lucia to be tree shaken, which is
+// the main reasoning for omitting this file in CJS and ESM builds
+
 import * as Lucia from './index';
 
 if (document.readyState === 'loading') {
   document.addEventListener('DOMContentLoaded', () => {
+    // Lucia allows for a custom initialization function
+    // This is to support for delayed init, like for Turbo Drive
+
     // @ts-expect-error
     const init = window.LuciaInit;
 

src/component.ts

@@ -1,5 +1,4 @@
 /* istanbul ignore next */
-
 import { Directives, DirectiveProps, Watchers, State, ASTNode } from './models/structs';
 
 import { directives } from './core/directive';
@@ -8,7 +7,6 @@ import reactive from './core/reactive';
 import render from './core/render';
 
 import { setElementCustomProp } from './core/utils/elementCustomProp';
-import { DIRECTIVE_PREFIX } from './models/generics';
 
 export class Component {
   public state: State;
@@ -35,7 +33,6 @@ export class Component {
     this.render();
 
     setElementCustomProp(rootEl, 'component', this);
-    this.handleMutations(rootEl);
 
     return this.state;
   }
@@ -51,25 +48,6 @@ export class Component {
   public render(props: string[] = Object.keys(this.state)) {
     render(this.ast!, directives, this.state, props);
   }
-
-  /* istanbul ignore next */
-  public handleMutations(el: HTMLElement) {
-    const mutationObserver = new MutationObserver((mutationsList) => {
-      for (const mutation of mutationsList) {
-        const attrName = String(mutation.attributeName);
-        if (
-          mutation.type === 'attributes' &&
-          attrName.startsWith(DIRECTIVE_PREFIX) &&
-          attrName !== `${DIRECTIVE_PREFIX}for`
-        ) {
-          this.ast = compile(el, this.state);
-          this.render();
-        }
-      }
-    });
-
-    mutationObserver.observe(el, { attributes: true, subtree: true });
-  }
 }
 
 export const component = (state?: State) => new Component(state);

src/core/compile.ts

@@ -77,7 +77,7 @@ export const collectAndInitDirectives = (
 
     if (eventDirectivePrefixRE().test(name)) returnable = false;
 
-    // for directive requires template
+    // for directive requires a template
     if (name.includes('for') && getElementCustomProp(el, '__for_template') === undefined) {
       setElementCustomProp(el, '__for_template', String(el.innerHTML).trim());
       returnable = false;

src/core/directives/for.ts

@@ -13,7 +13,6 @@ import adjustDeps from '../utils/adjustDeps';
 import computeExpression from '../utils/computeExpression';
 
 export const forDirective = ({ el, data, state, node }: DirectiveProps) => {
-  node = node!;
   const marker = getElementCustomProp(el, 'component');
 
   setElementCustomProp(el, 'component', true);
@@ -25,25 +24,19 @@ export const forDirective = ({ el, data, state, node }: DirectiveProps) => {
     (state[target?.trim()] as unknown[]) ?? computeExpression(target?.trim(), el, true)(state);
   const ast = compile(el, state);
 
-  let template = getElementCustomProp(el, '__for_template');
+  const template = getElementCustomProp(el, '__for_template');
   if (el.innerHTML.trim() === template) el.innerHTML = '';
 
+  // for directive is size-based, not content-based, since everything is compiled and rerendered
   const arrayDiff = currArray?.length - el.children.length;
 
   if (currArray?.length === 0) el.innerHTML = '';
   else if (arrayDiff !== 0) {
     for (let i = Math.abs(arrayDiff); i > 0; --i) {
       if (arrayDiff < 0) el.removeChild(el.lastChild as Node);
       else {
-        // Handle table cases
-        const tag = template.startsWith('<th')
-          ? 'thead'
-          : template.startsWith('<td') || template.startsWith('<tr')
-          ? 'tbody'
-          : 'div';
-
-        const temp = document.createElement(tag);
-        let content = template;
+        let content = String(template);
+        const isTable = /^[^\S]*?<(t(?:head|body|foot|r|d|h))/i.test(content);
 
         if (item) {
           content = content.replace(
@@ -58,17 +51,25 @@ export const forDirective = ({ el, data, state, node }: DirectiveProps) => {
           );
         }
 
-        temp.innerHTML = content;
+        // Needing to wrap table elements, else they disappear
+        if (isTable) content = `<table>${content}</table>`;
+
+        const fragment = document.createRange().createContextualFragment(content)
+          .firstElementChild!;
 
-        el.appendChild(temp.firstElementChild!);
+        // fragment and fragment.firstElementChild return the same result
+        // so we have to do it two times for the table, since we need
+        // to unwrap the temporary wrap
+        el.appendChild(isTable ? fragment.firstElementChild! : fragment);
       }
     }
   }
 
   if (!marker) {
-    adjustDeps(ast, data.deps, node, 'for');
+    // Deps recompiled because child nodes may have additional deps
+    adjustDeps(ast, data.deps, node!, 'for');
     el.removeAttribute(`${DIRECTIVE_PREFIX}for`);
   }
 
-  render(compile(el, state, true), directives, state, node.deps);
+  render(compile(el, state, true), directives, state, node!.deps);
 };

src/core/utils/concurrent.ts

@@ -1,3 +1,6 @@
+// Concurrent allows us to delay render calls if the main thread is blocked
+// This is kind of like time slicing in React but less advanced
+
 export const concurrent = (generatorFunction: () => Generator<undefined, void, unknown>) => {
   const generator = generatorFunction();
   return function next() {

src/index.ts

@@ -11,10 +11,10 @@ import computeExpression from './core/utils/computeExpression';
 
 export { component, compile, render, reactive, directives, computeExpression };
 
+// This is generally used for browser builds only, but it can be accessed in bundling environments
 export const init = (element: HTMLElement | Document = document): void => {
   const stateDirective = `${DIRECTIVE_PREFIX}state`;
   const componentElements = element.querySelectorAll(`[${stateDirective}]`);
-  // Filter out uninit scopes only
   const uninitializedComponents = [...componentElements].filter(
     (el) => getElementCustomProp(el as HTMLElement, 'component') === undefined
   );