@srfnstack/fntags 1.2.6 → 1.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@srfnstack/fntags",
-  "version": "1.2.6",
+  "version": "1.2.8",
   "author": "Robert Kempton <r@snow87.com>",
   "private": false,
   "homepage": "https://github.com/srfnstack/fntags",

package/src/fntags.d.mts

@@ -1,3 +1,10 @@
+/**
+ * Toggle dev-mode warnings. Defaults to true. Call `setDevMode(false)` in
+ * production to skip diagnostic checks such as the focus-loss warning fired
+ * when bindAs replaces a subtree containing the focused element.
+ * @param {boolean} on
+ */
+export function setDevMode(on: boolean): void;
 /**
  * A function to create dom elements with the given attributes and children.
  *
@@ -24,12 +31,14 @@ export function h<T extends HTMLElement | SVGElement>(tag: string, ...children:
  * @typedef FnStateObj A container for a state value that can be bound to.
  * @property {(element?: (newValue: T, oldValue: T)=>(Node|any))=>Node} bindAs Bind this state to the given element function. This causes the element to be replaced when the state changes.
  * If called with no parameters, the state's value will be rendered as an element.
+ * Do not wrap form inputs (input, textarea, select) in bindAs — it replaces the element on every update and the focused input will lose focus mid-keystroke. Bind the `value` attribute with bindAttr instead.
  * @property {(parent: (()=>(Node|any))|any|Node, element: (childState: FnState)=>(Node|any))=>Node} bindChildren Bind the values of this state to the given element.
  * Values are items/elements of an array.
  * If the current value is not an array, this will behave the same as bindAs.
  * @property {(prop: string)=>Node} bindProp Bind to a property of an object stored in this state instead of the state itself.
  * Shortcut for `mystate.bindAs((current)=> current[prop])`
- * @property {(attribute?: (newValue: T, oldValue: T)=>(string|any))=>any} bindAttr Bind attribute values to state changes
+ * @property {(attribute?: (newValue: T, oldValue: T)=>(string|any))=>any} bindAttr Bind attribute values to state changes.
+ * Prefer this over bindAs for form inputs: binding the `value` attribute updates the element in place without replacing it, so focus and caret position are preserved.
  * @property {(style?: (newValue: T, oldValue: T)=>string) => string} bindStyle Bind style values to state changes
  * @property {(element?: (selectedKey: any)=>(Node|any))=>Node} bindSelect Bind selected state to an element
  * @property {(attribute?: (selectedKey: any)=>(string|any))=>any} bindSelectAttr Bind selected state to an attribute
@@ -147,6 +156,7 @@ export type FnStateObj<T> = {
     /**
      * Bind this state to the given element function. This causes the element to be replaced when the state changes.
      * If called with no parameters, the state's value will be rendered as an element.
+     * Do not wrap form inputs (input, textarea, select) in bindAs — it replaces the element on every update and the focused input will lose focus mid-keystroke. Bind the `value` attribute with bindAttr instead.
      */
     bindAs: (element?: (newValue: T, oldValue: T) => (Node | any)) => Node;
     /**
@@ -161,7 +171,8 @@ export type FnStateObj<T> = {
      */
     bindProp: (prop: string) => Node;
     /**
-     * Bind attribute values to state changes
+     * Bind attribute values to state changes.
+     * Prefer this over bindAs for form inputs: binding the `value` attribute updates the element in place without replacing it, so focus and caret position are preserved.
      */
     bindAttr: (attribute?: (newValue: T, oldValue: T) => (string | any)) => any;
     /**

package/src/fntags.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"fntags.d.mts","sourceRoot":"","sources":["fntags.mjs"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,2DALW,MAAM,eACH,CAAC,IAAI,MAAO,CAAC,OA6C1B;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;GAGG;AAEH;;;;;;;;;;GAUG;AACH,iEAPgB,GAAG,cAqIlB;AAqfD;;;;GAIG;AACH,iCAHW,GAAG,GACD,IAAI,CAuBhB;AAqFD;;;;GAIG;AACH,6BAHW,GAAG,GACD,OAAO,CAInB;AAED;;;;GAIG;AACH,mCAHW,GAAG,GACF,MAAM,CAIjB;AAED;;;;;;;;;;GAUG;AACH,kEALW,MAAM,GAAC,MAAM,OACb,MAAM,YACN,MAAM,EAAE,GAAC,IAAI,EAAE,KAezB;AAOD;;;;;;;;GAQG;AACH,wCAJW,MAAM,0BAiBhB;AAED;;;;;;;;;GASG;AACH,oCALW,MAAM,gBACN,GAAG,eACE,GAAG,KAAK,MAAM,OAc7B;AAED;;;;;;;;GAQG;AACH,mCAJW,WAAW,SACX,CAAC,MAAI,IAAI,CAAC,GAAC,IAAI,GACb,WAAW,CAWvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qDAJkB,IAAI,iBACH,IAAI,CA+DtB;;;;;;;;;kCA18BmC,CAAC,YAAY,CAAC,KAAG,CAAC,IAAI,GAAC,GAAG,CAAC,KAAG,IAAI;;;;;;2BAE/C,CAAC,MAAI,CAAC,IAAI,GAAC,GAAG,CAAC,CAAC,GAAC,GAAG,GAAC,IAAI,gCAAkC,CAAC,IAAI,GAAC,GAAG,CAAC,KAAG,IAAI;;;;;qBAG9E,MAAM,KAAG,IAAI;;;;sCAEI,CAAC,YAAY,CAAC,KAAG,CAAC,MAAM,GAAC,GAAG,CAAC,KAAG,GAAG;;;;mCACvC,CAAC,YAAY,CAAC,KAAG,MAAM,KAAK,MAAM;;;;yCAC7B,GAAG,KAAG,CAAC,IAAI,GAAC,GAAG,CAAC,KAAG,IAAI;;;;+CACrB,GAAG,KAAG,CAAC,MAAM,GAAC,GAAG,CAAC,KAAG,GAAG;;;;;;kBAC7C,GAAG,KAAG,IAAI;;;;cAGhB,MAAK,GAAG;;;;;qBACC,CAAC,KAAG,IAAI;;;;;;oBAEV,MAAM,KAAG,GAAG;;;;oBAGZ,MAAM,SAAS,GAAG,mBAAmB,OAAO,KAAG,IAAI;;;;uCAClC,CAAC,YAAY,CAAC,KAAG,IAAI,KAAK,IAAI;;;;eACtD,OAAO;;;;;sDAKqB,CAAC,KAAG,CAAC"}
+{"version":3,"file":"fntags.d.mts","sourceRoot":"","sources":["fntags.mjs"],"names":[],"mappings":"AAcA;;;;;GAKG;AACH,+BAFW,OAAO,QAIjB;AAQD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,2DALW,MAAM,eACH,CAAC,IAAI,MAAO,CAAC,OA6C1B;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;GAGG;AAEH;;;;;;;;;;GAUG;AACH,iEAPgB,GAAG,cAqIlB;AA2kBD;;;;GAIG;AACH,iCAHW,GAAG,GACD,IAAI,CAuBhB;AAqFD;;;;GAIG;AACH,6BAHW,GAAG,GACD,OAAO,CAInB;AAED;;;;GAIG;AACH,mCAHW,GAAG,GACF,MAAM,CAIjB;AAED;;;;;;;;;;GAUG;AACH,kEALW,MAAM,GAAC,MAAM,OACb,MAAM,YACN,MAAM,EAAE,GAAC,IAAI,EAAE,KAezB;AAOD;;;;;;;;GAQG;AACH,wCAJW,MAAM,0BAiBhB;AAED;;;;;;;;;GASG;AACH,oCALW,MAAM,gBACN,GAAG,eACE,GAAG,KAAK,MAAM,OAc7B;AAED;;;;;;;;GAQG;AACH,mCAJW,WAAW,SACX,CAAC,MAAI,IAAI,CAAC,GAAC,IAAI,GACb,WAAW,CAWvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qDAJkB,IAAI,iBACH,IAAI,CA+DtB;;;;;;;;;;kCAliCmC,CAAC,YAAY,CAAC,KAAG,CAAC,IAAI,GAAC,GAAG,CAAC,KAAG,IAAI;;;;;;2BAG/C,CAAC,MAAI,CAAC,IAAI,GAAC,GAAG,CAAC,CAAC,GAAC,GAAG,GAAC,IAAI,gCAAkC,CAAC,IAAI,GAAC,GAAG,CAAC,KAAG,IAAI;;;;;qBAG9E,MAAM,KAAG,IAAI;;;;;sCAEI,CAAC,YAAY,CAAC,KAAG,CAAC,MAAM,GAAC,GAAG,CAAC,KAAG,GAAG;;;;mCAEvC,CAAC,YAAY,CAAC,KAAG,MAAM,KAAK,MAAM;;;;yCAC7B,GAAG,KAAG,CAAC,IAAI,GAAC,GAAG,CAAC,KAAG,IAAI;;;;+CACrB,GAAG,KAAG,CAAC,MAAM,GAAC,GAAG,CAAC,KAAG,GAAG;;;;;;kBAC7C,GAAG,KAAG,IAAI;;;;cAGhB,MAAK,GAAG;;;;;qBACC,CAAC,KAAG,IAAI;;;;;;oBAEV,MAAM,KAAG,GAAG;;;;oBAGZ,MAAM,SAAS,GAAG,mBAAmB,OAAO,KAAG,IAAI;;;;uCAClC,CAAC,YAAY,CAAC,KAAG,IAAI,KAAK,IAAI;;;;eACtD,OAAO;;;;;sDAKqB,CAAC,KAAG,CAAC"}

package/src/fntags.mjs

@@ -6,6 +6,22 @@
 // up when the bindAs re-renders. null means we are not inside a render.
 let activeRenderCleanups = null
 
+// When on, the framework emits console warnings for misuse that is easy to
+// hit and hard to diagnose (e.g. bindAs replacing a focused input, omitting
+// a key mapper from bindChildren). The checks are cheap but non-zero, so
+// production can opt out via setDevMode(false).
+let devMode = true
+
+/**
+ * Toggle dev-mode warnings. Defaults to true. Call `setDevMode(false)` in
+ * production to skip diagnostic checks such as the focus-loss warning fired
+ * when bindAs replaces a subtree containing the focused element.
+ * @param {boolean} on
+ */
+export function setDevMode (on) {
+  devMode = !!on
+}
+
 function runCleanups (elCtx) {
   if (!elCtx.cleanups) return
   for (const unsub of elCtx.cleanups) unsub()
@@ -88,12 +104,14 @@ function hasNs (val) {
  * @typedef FnStateObj A container for a state value that can be bound to.
  * @property {(element?: (newValue: T, oldValue: T)=>(Node|any))=>Node} bindAs Bind this state to the given element function. This causes the element to be replaced when the state changes.
  * If called with no parameters, the state's value will be rendered as an element.
+ * Do not wrap form inputs (input, textarea, select) in bindAs — it replaces the element on every update and the focused input will lose focus mid-keystroke. Bind the `value` attribute with bindAttr instead.
  * @property {(parent: (()=>(Node|any))|any|Node, element: (childState: FnState)=>(Node|any))=>Node} bindChildren Bind the values of this state to the given element.
  * Values are items/elements of an array.
  * If the current value is not an array, this will behave the same as bindAs.
  * @property {(prop: string)=>Node} bindProp Bind to a property of an object stored in this state instead of the state itself.
  * Shortcut for `mystate.bindAs((current)=> current[prop])`
- * @property {(attribute?: (newValue: T, oldValue: T)=>(string|any))=>any} bindAttr Bind attribute values to state changes
+ * @property {(attribute?: (newValue: T, oldValue: T)=>(string|any))=>any} bindAttr Bind attribute values to state changes.
+ * Prefer this over bindAs for form inputs: binding the `value` attribute updates the element in place without replacing it, so focus and caret position are preserved.
  * @property {(style?: (newValue: T, oldValue: T)=>string) => string} bindStyle Bind style values to state changes
  * @property {(element?: (selectedKey: any)=>(Node|any))=>Node} bindSelect Bind selected state to an element
  * @property {(attribute?: (selectedKey: any)=>(string|any))=>any} bindSelectAttr Bind selected state to an attribute
@@ -428,7 +446,9 @@ function doBindChildren (parent, element) {
     throw new Error('You must pass a function to produce child elements.')
   }
   if (typeof ctx.mapKey !== 'function') {
-    console.warn('Using value index as key, may not work correctly when moving items...')
+    if (devMode) {
+      console.warn('bindChildren: no mapKey provided — falling back to array index as key, which can misbehave when items are moved, inserted, or removed. Pass a mapKey function as the second argument to fnstate(array, item => item.id).')
+    }
     ctx.mapKey = (_, i) => i
   }
 
@@ -459,7 +479,9 @@ function doBindChildren (parent, element) {
 
   this.subscribe((_, oldState) => {
     if (!Array.isArray(ctx.currentValue)) {
-      console.warn('A state used with bindChildren was updated to a non array value. This will be converted to an array of 1 and the state will be updated.')
+      if (devMode) {
+        console.warn('bindChildren: state was updated to a non-array value. Wrapping it in a single-element array — if you meant to replace the whole binding, use bindAs instead.')
+      }
       new Promise((resolve) => {
         this([ctx.currentValue])
         resolve()
@@ -489,7 +511,17 @@ const doBind = function (ctx, element, handleReplace) {
   const prevRenderCleanups = activeRenderCleanups
   const thisRenderCleanups = []
   activeRenderCleanups = thisRenderCleanups
-  const elCtx = { current: renderNode(evaluateElement(element, ctx.currentValue)), cleanups: thisRenderCleanups }
+  const evaluated = evaluateElement(element, ctx.currentValue)
+  const childElCtx = (typeof evaluated === 'function' && evaluated.isBindGetter)
+    ? evaluated.elCtx
+    : null
+  const elCtx = { current: renderNode(evaluated), cleanups: thisRenderCleanups }
+  // When the evaluated element is itself a bind getter (a nested bindAs/bindSelect),
+  // register this elCtx as a back-ref on the child so that later child-driven
+  // node swaps keep this elCtx.current in sync with the live DOM node.
+  if (childElCtx && childElCtx.current === elCtx.current) {
+    addParentRef(childElCtx, elCtx)
+  }
   // Suppress tracking during handleReplace — the driving subscription is
   // registered separately below as part of a cascading cleanup.
   activeRenderCleanups = null
@@ -504,10 +536,68 @@ const doBind = function (ctx, element, handleReplace) {
       if (elCtx.drivingUnsub) elCtx.drivingUnsub()
       if (elCtx.selectUnsub) elCtx.selectUnsub()
       runCleanups(elCtx)
+      // Mark dead so any child elCtx that still holds us in its parentRefs
+      // can prune us lazily on its next propagateReplace walk.
+      elCtx.dead = true
     })
   }
 
-  return () => elCtx.current
+  const getter = () => elCtx.current
+  getter.isBindGetter = true
+  getter.elCtx = elCtx
+  return getter
+}
+
+// Register a back-ref from a child bind elCtx to a parent elCtx, avoiding
+// duplicate entries when the same parent re-renders against the same child.
+function addParentRef (childElCtx, parentElCtx) {
+  if (!childElCtx.parentRefs) {
+    childElCtx.parentRefs = [parentElCtx]
+  } else if (!childElCtx.parentRefs.includes(parentElCtx)) {
+    childElCtx.parentRefs.push(parentElCtx)
+  }
+}
+
+// Walk the back-ref chain and update any ancestor elCtx whose .current still
+// points at the old DOM node. Used when a nested bindAs swaps its node so the
+// outer bindAs keeps a live reference instead of a detached one. Prunes any
+// dead ancestors encountered so parentRefs does not retain torn-down elCtxs.
+function propagateReplace (elCtx, oldNode, newNode) {
+  const refs = elCtx.parentRefs
+  if (!refs) return
+  for (let i = refs.length - 1; i >= 0; i--) {
+    const parent = refs[i]
+    if (parent.dead) {
+      refs.splice(i, 1)
+      continue
+    }
+    if (parent.current === oldNode) {
+      parent.current = newNode
+      propagateReplace(parent, oldNode, newNode)
+    }
+  }
+}
+
+// Emit a dev-mode warning when a bindAs replacement would destroy a subtree
+// containing the focused element. This is the most common fntags footgun:
+// wrapping an <input> in bindAs replaces the element on every keystroke, so
+// the user loses focus and caret position mid-edit. The fix is almost always
+// to bind the `value` attribute with bindAttr instead. We only check once per
+// replacement and only touch the DOM when an element is actually focused.
+function warnIfReplacingFocused (oldNode) {
+  if (typeof document === 'undefined') return
+  const active = document.activeElement
+  if (!active || active === document.body) return
+  if (oldNode && oldNode.nodeType === 1 && (oldNode === active || oldNode.contains(active))) {
+    console.warn(
+      'bindAs is about to replace a subtree containing the focused element <' +
+      active.tagName.toLowerCase() + '>. The replacement will steal focus and ' +
+      'reset caret/selection. For form inputs, bind the `value` attribute with ' +
+      'bindAttr instead of wrapping the input in bindAs. ' +
+      'Call setDevMode(false) to silence this warning.',
+      active
+    )
+  }
 }
 
 const updateReplacer = (ctx, element, elCtx) => (_, oldValue) => {
@@ -520,7 +610,11 @@ const updateReplacer = (ctx, element, elCtx) => (_, oldValue) => {
   const prevRenderCleanups = activeRenderCleanups
   const thisRenderCleanups = []
   activeRenderCleanups = thisRenderCleanups
-  let rendered = renderNode(evaluateElement(element, ctx.currentValue, oldValue))
+  const evaluated = evaluateElement(element, ctx.currentValue, oldValue)
+  const childElCtx = (typeof evaluated === 'function' && evaluated.isBindGetter)
+    ? evaluated.elCtx
+    : null
+  let rendered = renderNode(evaluated)
   activeRenderCleanups = prevRenderCleanups
   elCtx.cleanups = thisRenderCleanups
 
@@ -533,14 +627,24 @@ const updateReplacer = (ctx, element, elCtx) => (_, oldValue) => {
         bindContext.boundElementByKey[elCtx.current.key] = rendered
       }
     }
+    // Re-establish the parent-ref link when a re-render resolves to another
+    // nested bind getter, so future child swaps propagate back to this elCtx.
+    if (childElCtx && childElCtx.current === rendered) {
+      addParentRef(childElCtx, elCtx)
+    }
     // Perform this action on the next event loop to give the parent a chance to render
     new Promise((resolve) => {
       // Guard: skip replaceWith when the same element is returned (e.g. when
       // toggling between two pre-built element references). el.replaceWith(el)
       // is a no-op in the DOM but wastes a microtask.
       if (rendered !== elCtx.current) {
+        const oldCurrent = elCtx.current
+        if (devMode) warnIfReplacingFocused(oldCurrent)
         elCtx.current.replaceWith(rendered)
         elCtx.current = rendered
+        // Keep any ancestor bindAs whose elCtx shared this node in sync with
+        // the new node, so their next replaceWith targets a live DOM node.
+        propagateReplace(elCtx, oldCurrent, rendered)
       }
       rendered = null
       resolve()