@nisli/core 0.57.0 → 0.57.1

package/README.md

@@ -14,6 +14,9 @@ npm install @nisli/core
 `@nisli/core` has no runtime dependencies. It works with TypeScript or plain
 JavaScript and does not require a framework-specific build step.
 
+See the [framework tenets](https://github.com/gkoreli/nisli/blob/main/docs/TENETS.md)
+for design constraints.
+
 ## Quick start
 
 ```ts
@@ -36,6 +39,30 @@ Signals are read with `.value` in TypeScript and passed directly to templates.
 Only the bound text, attribute, class, or child slot updates when a signal
 changes.
 
+## Native form bindings
+
+`html` and `el()` synchronize native `value` (input, textarea, select), `checked`
+(input), and `selected` (option) properties as well as their attributes. An
+external signal change therefore replaces a user-edited value without a ref or
+an application effect:
+
+```ts
+const name = signal('');
+html`<input value=${name} @input=${(event: Event) => {
+  name.value = (event.target as HTMLInputElement).value;
+}}>`;
+```
+
+Bindings remain one-way; native events update your model only through handlers.
+Equal text-value writes preserve the caret. Select values initialize after
+options and reconcile in a mutation-observer microtask when options change.
+A select value is scalar; bind option `selected` states for multiple selections.
+Nonempty file values cannot populate uploads; an empty value can clear them.
+
+Form reset keeps native defaults: input value/checked and option selected
+attributes, textarea child text, and select option defaults. Reset does not write
+signals. Ordinary attributes and custom-element props keep their existing paths.
+
 ## Components that also work as HTML
 
 `component()` registers a standard custom element and returns its typed factory.
@@ -264,9 +291,11 @@ per-key DOM identity does the rest, with no generated names:
 - Safe light-DOM templates: signal bindings, typed events and modifiers,
   `class:*`, branded `html:inner` (trusted or sanitizer-routed), refs, and
   dynamic HTML tags through `el()`.
-- Stable control flow: lazy `when()` branches and keyed `each()` lists that
-  preserve focus, scroll position, and component state, moved atomically with
-  `moveBefore()` where the engine has it.
+- Stable control flow: lazy `when()` branches and keyed `each()` lists retain
+  component state and DOM identity. Reorders use `moveBefore()` where available;
+  the fallback keeps a retained focused row attached without refocusing it.
+  Other moved rows can lose native state such as iframe documents or popovers
+  on the fallback path; document Selection ranges are not preserved.
 - Two scopes of dependency injection: app-wide singleton services with
   `inject`/`provide`, and portal-safe subtree state with `createContext`.
 - Lifecycle and resilience: `onMount`, `onCleanup`, `useHostEvent`, automatic

package/dist/bundler/template.js

@@ -105,8 +105,10 @@ function html(strings, ...values) {
       mounted = true;
       const template = parseTemplate(strings, values.length);
       const fragment = template.content.cloneNode(true);
-      processNode(fragment, values, bindings, disposers);
+      const afterMount = [];
+      processNode(fragment, values, bindings, disposers, afterMount);
       host.appendChild(fragment);
+      for (const sync of afterMount) sync();
     },
     dispose() {
       for (const d of disposers) {
@@ -129,10 +131,11 @@ function html(strings, ...values) {
     }
   };
 }
-function processNode(node, values, bindings, disposers) {
+function processNode(node, values, bindings, disposers, afterMount) {
+  let afterChildren;
   if (node.nodeType === Node.ELEMENT_NODE) {
     const el2 = node;
-    processAttributes(el2, values, bindings, disposers);
+    afterChildren = processAttributes(el2, values, bindings, disposers, afterMount);
   }
   if (node.nodeType === Node.COMMENT_NODE) {
     const comment = node;
@@ -146,11 +149,13 @@ function processNode(node, values, bindings, disposers) {
   }
   const children = [...node.childNodes];
   for (const child of children) {
-    processNode(child, values, bindings, disposers);
+    processNode(child, values, bindings, disposers, afterMount);
   }
+  if (afterChildren) for (const bind of afterChildren) bind();
 }
-function processAttributes(el2, values, bindings, disposers) {
+function processAttributes(el2, values, bindings, disposers, afterMount) {
   const attrsToRemove = [];
+  let afterChildren;
   for (const attr of [...el2.attributes]) {
     const name = attr.name;
     const attrValue = attr.value;
@@ -209,8 +214,9 @@ function processAttributes(el2, values, bindings, disposers) {
       const markers = [...attrValue.matchAll(/<!--bk-(\d+)-->/g)];
       if (markers.length) {
         const first = markers[0];
+        let value;
         if (markers.length === 1 && first && attrValue === first[0]) {
-          bindAttribute(el2, name, values[Number(first[1])], bindings, disposers);
+          value = values[Number(first[1])];
         } else {
           const resolve = () => attrValue.replace(/<!--bk-(\d+)-->/g, (_, i) => {
             const v = values[Number(i)];
@@ -218,7 +224,12 @@ function processAttributes(el2, values, bindings, disposers) {
             return raw2 == null || raw2 === false ? "" : String(raw2);
           });
           const hasSignals = markers.some((m) => isSignal(values[Number(m[1])]));
-          bindAttribute(el2, name, hasSignals ? computed(resolve) : resolve(), bindings, disposers);
+          value = hasSignals ? computed(resolve) : resolve();
+        }
+        if (nativeFormProperty(el2, name)) {
+          (afterChildren ??= []).push(() => bindAttribute(el2, name, value, bindings, disposers, afterMount));
+        } else {
+          bindAttribute(el2, name, value, bindings, disposers, afterMount);
         }
       }
       continue;
@@ -227,6 +238,7 @@ function processAttributes(el2, values, bindings, disposers) {
   for (const name of attrsToRemove) {
     el2.removeAttribute(name);
   }
+  return afterChildren;
 }
 function mountFactoryResult(factory) {
   const el2 = document.createElement(factory.tagName);
@@ -425,7 +437,7 @@ function replaceMarkerWithBinding(comment, value, bindings, disposers) {
     parent.replaceChild(textNode, comment);
   }
 }
-function bindAttribute(el2, name, value, bindings, disposers) {
+function bindAttribute(el2, name, value, bindings, disposers, afterMount) {
   if (name === "class") {
     bindClassAttribute(el2, value, bindings, disposers);
     return;
@@ -446,32 +458,69 @@ function bindAttribute(el2, name, value, bindings, disposers) {
     }
     return;
   }
-  bindPlainAttribute(el2, name, value, bindings, disposers);
+  bindPlainAttribute(el2, name, value, bindings, disposers, afterMount);
 }
-function bindPlainAttribute(el2, name, value, bindings, disposers) {
+function bindPlainAttribute(el2, name, value, bindings, disposers, afterMount) {
+  const property = nativeFormProperty(el2, name);
+  let current;
+  const apply = (v) => {
+    current = v;
+    if (v == null || v === false) {
+      el2.removeAttribute(name);
+    } else {
+      el2.setAttribute(name, v === true ? "" : String(v));
+    }
+    if (property) syncFormProperty(el2, property, v);
+  };
   if (isSignal(value)) {
     const binding = { type: "attribute", element: el2, name };
     bindings.push(binding);
-    const dispose = effect(() => {
-      const v = value.value;
-      if (v == null || v === false) {
-        el2.removeAttribute(name);
-      } else if (v === true) {
-        el2.setAttribute(name, "");
-      } else {
-        el2.setAttribute(name, String(v));
-      }
-    });
+    const dispose = effect(() => apply(value.value));
     binding.dispose = dispose;
     disposers.push(dispose);
   } else {
-    if (value == null || value === false) {
-      el2.removeAttribute(name);
-    } else if (value === true) {
-      el2.setAttribute(name, "");
-    } else {
-      el2.setAttribute(name, String(value));
-    }
+    apply(value);
+  }
+  if (property === "value" && el2.localName === "select") {
+    let active = true;
+    const sync = () => {
+      if (active) syncFormProperty(el2, "value", current);
+    };
+    const observer = new MutationObserver(sync);
+    observer.observe(el2, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+      attributes: true,
+      attributeFilter: ["value", "selected"]
+    });
+    disposers.push(() => {
+      active = false;
+      observer.disconnect();
+    });
+    afterMount.push(sync);
+    queueMicrotask(sync);
+  }
+}
+function nativeFormProperty(el2, name) {
+  const attribute = name.toLowerCase();
+  if (attribute !== "value" && attribute !== "checked" && attribute !== "selected") return;
+  if (el2.namespaceURI !== "http://www.w3.org/1999/xhtml") return;
+  const tag = el2.localName;
+  if (attribute === "value" && (tag === "input" || tag === "textarea" || tag === "select")) return attribute;
+  if (attribute === "checked" && tag === "input") return attribute;
+  if (attribute === "selected" && tag === "option") return attribute;
+}
+function syncFormProperty(el2, property, value) {
+  if (property === "value") {
+    const control = el2;
+    const next = value == null || typeof value === "boolean" ? "" : String(value);
+    if (el2.localName === "input" && el2.type === "file" && next !== "") return;
+    if (el2.localName === "select" || control.value !== next) control.value = next;
+  } else {
+    const control = el2;
+    const next = value != null && value !== false;
+    if (control[property] !== next) control[property] = next;
   }
 }
 function bindClassAttribute(el2, value, bindings, disposers) {
@@ -728,11 +777,28 @@ function each(items, keyFn, templateFn) {
         entry.wrapper.parentNode?.removeChild(entry.wrapper);
       }
     }
-    let cursor = startMarker;
-    for (const entry of newEntries) {
+    const atomic = canMoveWithin(parent);
+    let focusedIndex = -1;
+    if (!atomic) {
+      const root = parent.getRootNode();
+      let active = "activeElement" in root ? root.activeElement : null;
+      while (active && active.parentNode !== parent) active = active.parentElement;
+      if (active) focusedIndex = newEntries.findIndex((entry) => entry.wrapper === active);
+    }
+    if (focusedIndex !== -1) {
+      let next = newEntries[focusedIndex].wrapper;
+      for (let i = focusedIndex - 1; i >= 0; i--) {
+        const wrapper = newEntries[i].wrapper;
+        if (wrapper.nextSibling !== next) parent.insertBefore(wrapper, next);
+        next = wrapper;
+      }
+    }
+    let cursor = focusedIndex === -1 ? startMarker : newEntries[focusedIndex].wrapper;
+    for (let i = focusedIndex + 1; i < newEntries.length; i++) {
+      const entry = newEntries[i];
       const nextSibling = cursor.nextSibling;
       if (nextSibling !== entry.wrapper) {
-        if (entry.wrapper.parentNode === parent && canMoveWithin(parent)) {
+        if (entry.wrapper.parentNode === parent && atomic) {
           parent.moveBefore(entry.wrapper, nextSibling);
         } else {
           parent.insertBefore(entry.wrapper, nextSibling);
@@ -772,8 +838,11 @@ function el(tag, props = {}, children) {
     mount(host) {
       const element = document.createElement(tag);
       node = element;
+      let afterChildren;
+      const afterMount = [];
       for (const [key, val] of Object.entries(props)) {
-        if (val === void 0) continue;
+        const formProperty = nativeFormProperty(element, key);
+        if (val === void 0 && !formProperty) continue;
         if (key === "ref") {
           if (isRef(val)) {
             val.current = element;
@@ -793,7 +862,11 @@ function el(tag, props = {}, children) {
           bindClassAttribute(element, val, bindings, disposers);
           continue;
         }
-        bindPlainAttribute(element, key, val, bindings, disposers);
+        if (formProperty) {
+          (afterChildren ??= []).push(() => bindPlainAttribute(element, key, val, bindings, disposers, afterMount));
+        } else {
+          bindPlainAttribute(element, key, val, bindings, disposers, afterMount);
+        }
       }
       const flat = [];
       flattenChildren(children, flat);
@@ -802,7 +875,9 @@ function el(tag, props = {}, children) {
         element.appendChild(anchor);
         replaceMarkerWithBinding(anchor, child, bindings, disposers);
       }
+      if (afterChildren) for (const bind of afterChildren) bind();
       host.appendChild(element);
+      for (const sync of afterMount) sync();
     },
     dispose() {
       for (const d of disposers) {