@srfnstack/fntags 1.2.7 → 1.3.0

package/package.json

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

package/src/fnroute.d.mts

@@ -40,13 +40,25 @@ export function routeSwitch(...children: (any | Node)[]): Node | (() => Node);
  */
 export function fnlink(...children: (any | Node)[]): HTMLAnchorElement;
 /**
- * A function to navigate to the specified route
+ * A function to navigate to the specified route.
+ *
+ * Navigating to the current path with only a different hash or query (for example from /docs to /docs#faq)
+ * and no new context is not a route change: the history entry is updated and the hash target is scrolled
+ * into view, but the route is not re-rendered and no route events are emitted.
  * @param {string} route The route to navigate to
- * @param {any} context Data related to the route change
+ * @param {any} [context] Data related to the route change
  * @param {boolean} replace Whether to replace the state or push it. pushState is used by default.
  * @param {boolean} silent Prevent route change events from being emitted for this route change
  */
 export function goTo(route: string, context?: any, replace?: boolean, silent?: boolean): void;
+/**
+ * Scroll the element whose id matches the hash into view. If the element does not exist yet, for example because
+ * the route's content is a promise that has not resolved, wait for it to be added to the document and scroll then.
+ * With no hash, scroll to the top of the page.
+ * @param {string|null|undefined} hash The hash to scroll to, with or without the leading #
+ * @param {number} [timeout] How long to wait for the element to appear, in milliseconds
+ */
+export function scrollToHash(hash: string | null | undefined, timeout?: number): void;
 /**
  * Listen for routing events
  * @param {string} event a string event to listen for

package/src/fnroute.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"fnroute.d.mts","sourceRoot":"","sources":["fnroute.mjs"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,mCAHW,CAAC,MAAO,IAAI,CAAC,EAAE,GACb,cAAc,CAoB1B;AAED;;;;;GAKG;AACH,yCAHW,CAAC,MAAO,IAAI,CAAC,EAAE,GACb,IAAI,GAAC,CAAC,MAAI,IAAI,CAAC,CAyB3B;AAoBD;;;;GAIG;AACH,oCAHW,CAAC,MAAO,IAAI,CAAC,EAAE,GACb,iBAAiB,CAuB7B;AAED;;;;;;GAMG;AACH,4BALW,MAAM,YACN,GAAG,YACH,OAAO,WACP,OAAO,QA4CjB;AAiED;;;;;;GAMG;AACH,iCALW,MAAM,iBAGL,MAAI,IAAI,CAanB;AAED;;;GAGG;AACH,sCAFW,MAAM,QAOhB;AAxFD;;;GAGG;AAEH;;;GAGG;AACH,6BAFU,OAAO,cAAc,EAAE,OAAO,CAAC,cAAc,CAAC,CAEf;AAEzC;;;GAGG;AAEH;;;GAGG;AACH,wBAFU,OAAO,cAAc,EAAE,OAAO,CAAC,SAAS,CAAC,CAO/C;AAMJ;;GAEG;AACH;;;GAGG;AACH,gCAFU,UAAU,CAEgC;AACpD;;;GAGG;AACH,+BAFU,UAAU,CAE8B;AAClD;;;GAGG;AACH,kCAFU,UAAU,CAEoC;;;;;;;;wBAnC3C;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,GAAG,CAAA;CAAC;yBAmBrD,MAAM"}
+{"version":3,"file":"fnroute.d.mts","sourceRoot":"","sources":["fnroute.mjs"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,mCAHW,CAAC,MAAO,IAAI,CAAC,EAAE,GACb,cAAc,CAoB1B;AAED;;;;;GAKG;AACH,yCAHW,CAAC,MAAO,IAAI,CAAC,EAAE,GACb,IAAI,GAAC,CAAC,MAAI,IAAI,CAAC,CAyB3B;AAoBD;;;;GAIG;AACH,oCAHW,CAAC,MAAO,IAAI,CAAC,EAAE,GACb,iBAAiB,CAuB7B;AAED;;;;;;;;;;GAUG;AACH,4BALW,MAAM,YACN,GAAG,YACH,OAAO,WACP,OAAO,QA+CjB;AAID;;;;;;GAMG;AACH,mCAHW,MAAM,GAAC,IAAI,GAAC,SAAS,YACrB,MAAM,QAiChB;AAiED;;;;;;GAMG;AACH,iCALW,MAAM,iBAGL,MAAI,IAAI,CAanB;AAED;;;GAGG;AACH,sCAFW,MAAM,QAOhB;AAxFD;;;GAGG;AAEH;;;GAGG;AACH,6BAFU,OAAO,cAAc,EAAE,OAAO,CAAC,cAAc,CAAC,CAEf;AAEzC;;;GAGG;AAEH;;;GAGG;AACH,wBAFU,OAAO,cAAc,EAAE,OAAO,CAAC,SAAS,CAAC,CAO/C;AAMJ;;GAEG;AACH;;;GAGG;AACH,gCAFU,UAAU,CAEgC;AACpD;;;GAGG;AACH,+BAFU,UAAU,CAE8B;AAClD;;;GAGG;AACH,kCAFU,UAAU,CAEoC;;;;;;;;wBAnC3C;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,GAAG,CAAA;CAAC;yBAmBrD,MAAM"}

package/src/fnroute.mjs

@@ -106,7 +106,7 @@ function updatePathParameters () {
  * @returns {HTMLAnchorElement} An anchor element that will navigate to the specified route when clicked
  */
 export function fnlink (...children) {
-  let context = null
+  let context
   if (children[0] && children[0].context) {
     context = children[0].context
   }
@@ -129,21 +129,36 @@ export function fnlink (...children) {
 }
 
 /**
- * A function to navigate to the specified route
+ * A function to navigate to the specified route.
+ *
+ * Navigating to the current path with only a different hash or query (for example from /docs to /docs#faq)
+ * and no new context is not a route change: the history entry is updated and the hash target is scrolled
+ * into view, but the route is not re-rendered and no route events are emitted.
  * @param {string} route The route to navigate to
- * @param {any} context Data related to the route change
+ * @param {any} [context] Data related to the route change
  * @param {boolean} replace Whether to replace the state or push it. pushState is used by default.
  * @param {boolean} silent Prevent route change events from being emitted for this route change
  */
-export function goTo (route, context = {}, replace = false, silent = false) {
+export function goTo (route, context, replace = false, silent = false) {
   const newPath = window.location.origin + makePath(route)
+  const hash = newPath.indexOf('#') > -1 ? newPath.split('#')[1] : null
+  const oldPathState = pathState()
+  const currentPath = ensureOnlyLeadingSlash(route.split(/[#?]/)[0])
 
-  const patch = {
-    currentPath: route.split(/[#?]/)[0],
-    context
+  if (currentPath === oldPathState.currentPath && context === undefined) {
+    if (replace) {
+      history.replaceState({}, route, newPath)
+    } else {
+      history.pushState({}, route, newPath)
+    }
+    scrollToHash(hash)
+    return
   }
 
-  const oldPathState = pathState()
+  const patch = {
+    currentPath,
+    context: context === undefined ? {} : context
+  }
   const newPathState = Object.assign({}, oldPathState, patch)
   if (!silent) {
     try {
@@ -160,25 +175,59 @@ export function goTo (route, context = {}, replace = false, silent = false) {
   }
 
   setTimeout(() => {
-    pathState.assign({
-      currentPath: route.split(/[#?]/)[0],
-      context
-    })
+    pathState.assign(patch)
     if (!silent) {
       emit(afterRouteChange, newPathState, oldPathState)
     }
-    if (newPath.indexOf('#') > -1) {
-      const el = document.getElementById(decodeURIComponent(newPath.split('#')[1]))
-      el && el.scrollIntoView()
-    } else {
-      window.scrollTo(0, 0)
-    }
+    scrollToHash(hash)
     if (!silent) {
       emit(routeChangeComplete, newPathState, oldPathState)
     }
   })
 }
 
+let cancelPendingScroll = null
+
+/**
+ * Scroll the element whose id matches the hash into view. If the element does not exist yet, for example because
+ * the route's content is a promise that has not resolved, wait for it to be added to the document and scroll then.
+ * With no hash, scroll to the top of the page.
+ * @param {string|null|undefined} hash The hash to scroll to, with or without the leading #
+ * @param {number} [timeout] How long to wait for the element to appear, in milliseconds
+ */
+export function scrollToHash (hash, timeout = 5000) {
+  if (cancelPendingScroll) {
+    cancelPendingScroll()
+  }
+  const id = hash ? decodeURIComponent(hash.startsWith('#') ? hash.slice(1) : hash) : ''
+  if (!id) {
+    window.scrollTo(0, 0)
+    return
+  }
+  const scrollIfPresent = () => {
+    const el = document.getElementById(id)
+    if (el) {
+      el.scrollIntoView()
+    }
+    return !!el
+  }
+  if (scrollIfPresent() || typeof MutationObserver === 'undefined') {
+    return
+  }
+  const observer = new MutationObserver(() => {
+    if (scrollIfPresent()) {
+      cancelPendingScroll()
+    }
+  })
+  const timer = setTimeout(() => cancelPendingScroll(), timeout)
+  cancelPendingScroll = () => {
+    observer.disconnect()
+    clearTimeout(timer)
+    cancelPendingScroll = null
+  }
+  observer.observe(document.documentElement, { childList: true, subtree: true })
+}
+
 const ensureOnlyLeadingSlash = (part) => removeTrailingSlash(part.startsWith('/') ? part : '/' + part)
 
 const removeTrailingSlash = part => part.endsWith('/') && part.length > 1 ? part.slice(0, -1) : part
@@ -280,6 +329,12 @@ window.addEventListener(
     const patch = {
       currentPath: ensureOnlyLeadingSlash(window.location.pathname.replace(new RegExp('^' + pathState().rootPath), '')) || '/'
     }
+    // Clicking <a href="#section"> and moving back/forward between hash entries fire popstate without
+    // changing the path. That is not a route change, so leave the rendered route alone and let the
+    // browser handle scrolling to the fragment.
+    if (patch.currentPath === oldPathState.currentPath) {
+      return
+    }
     const newPathState = Object.assign({}, oldPathState, patch)
     try {
       emit(beforeRouteChange, newPathState, oldPathState)
@@ -294,6 +349,12 @@ window.addEventListener(
   }
 )
 
+// On initial load the browser only scrolls to the hash if the target already exists. When the target is inside
+// a route whose content has not rendered yet, wait for it the same way goTo does.
+if (window.location.hash && !document.getElementById(decodeURIComponent(window.location.hash.slice(1)))) {
+  scrollToHash(window.location.hash)
+}
+
 const makePath = path => (pathState().rootPath === '/' ? '' : pathState().rootPath) + ensureOnlyLeadingSlash(path)
 
 const makePathPattern = (path, absolute) => {

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
@@ -63,7 +72,8 @@ export function h<T extends HTMLElement | SVGElement>(tag: string, ...children:
  */
 export function fnstate<T>(initialValue: T, mapKey?: (T: any) => any): FnState<T>;
 /**
- * Convert non objects (objects are assumed to be nodes) to text nodes and allow promises to resolve to nodes
+ * Convert non objects (objects are assumed to be nodes) to text nodes and allow promises to resolve to nodes.
+ * Arrays are flattened at any depth into a DocumentFragment.
  * @param {any} node The node to render
  * @returns {Node} The rendered node
  */
@@ -147,6 +157,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 +172,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;AAgjBD;;;;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;;;;;;;;;kCArgCmC,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,OAsC1B;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;GAGG;AAEH;;;;;;;;;;GAUG;AACH,iEAPgB,GAAG,cAqIlB;AAwlBD;;;;;GAKG;AACH,iCAHW,GAAG,GACD,IAAI,CAgChB;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;;;;;;;;;;kCAzjCmC,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()
@@ -65,6 +81,8 @@ export function h (tag, ...children) {
   for (let i = firstChildIdx; i < children.length; i++) {
     const child = children[i]
     if (Array.isArray(child)) {
+      // Append array items directly to skip the DocumentFragment renderNode would build.
+      // Nested arrays inside still go through renderNode, which flattens them.
       for (const c of child) {
         element.append(renderNode(c))
       }
@@ -88,12 +106,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 +448,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 +481,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()
@@ -478,6 +502,15 @@ function doBindChildren (parent, element) {
   return parent
 }
 
+// A bound function must produce exactly one node. A DocumentFragment empties
+// itself when inserted, so there would be nothing left to replaceWith on the
+// next state change and the binding would silently stop updating.
+function assertSingleNode (evaluated, name) {
+  if (Array.isArray(evaluated)) {
+    throw new Error(name + ' functions must return a single node, not an array. Wrap the array in an element, e.g. div(...items).')
+  }
+}
+
 const doBind = function (ctx, element, handleReplace) {
   if (typeof element !== 'function') {
     throw new Error('You must pass a function to bind with')
@@ -490,6 +523,7 @@ const doBind = function (ctx, element, handleReplace) {
   const thisRenderCleanups = []
   activeRenderCleanups = thisRenderCleanups
   const evaluated = evaluateElement(element, ctx.currentValue)
+  assertSingleNode(evaluated, 'bindAs')
   const childElCtx = (typeof evaluated === 'function' && evaluated.isBindGetter)
     ? evaluated.elCtx
     : null
@@ -556,6 +590,28 @@ function propagateReplace (elCtx, 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) => {
   // Clean up subscriptions from the previous render before re-rendering.
   // This prevents nested bindAs/bindAttr/bindStyle subscriptions from
@@ -567,6 +623,7 @@ const updateReplacer = (ctx, element, elCtx) => (_, oldValue) => {
   const thisRenderCleanups = []
   activeRenderCleanups = thisRenderCleanups
   const evaluated = evaluateElement(element, ctx.currentValue, oldValue)
+  assertSingleNode(evaluated, 'bindAs')
   const childElCtx = (typeof evaluated === 'function' && evaluated.isBindGetter)
     ? evaluated.elCtx
     : null
@@ -595,6 +652,7 @@ const updateReplacer = (ctx, element, elCtx) => (_, oldValue) => {
       // 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
@@ -745,7 +803,9 @@ function arrangeElements (ctx, bindContext, oldState) {
       const thisElementCleanups = []
       activeRenderCleanups = thisElementCleanups
       // Pass the valueState (the fnstate wrapper) to the user's element builder
-      current = bindContext.boundElementByKey[key] = renderNode(evaluateElement(bindContext.element, valueState))
+      const evaluated = evaluateElement(bindContext.element, valueState)
+      assertSingleNode(evaluated, 'bindChildren')
+      current = bindContext.boundElementByKey[key] = renderNode(evaluated)
       activeRenderCleanups = prevCleanups
       bindContext.elementCleanups[key] = thisElementCleanups
       current.key = key
@@ -814,7 +874,8 @@ const evaluateElement = (element, value, oldValue) => {
 }
 
 /**
- * Convert non objects (objects are assumed to be nodes) to text nodes and allow promises to resolve to nodes
+ * Convert non objects (objects are assumed to be nodes) to text nodes and allow promises to resolve to nodes.
+ * Arrays are flattened at any depth into a DocumentFragment.
  * @param {any} node The node to render
  * @returns {Node} The rendered node
  */
@@ -823,6 +884,15 @@ export function renderNode (node) {
     const element = h('div')
     node(element, 'node')
     return element
+  } else if (Array.isArray(node)) {
+    // Arrays (including nested arrays and arrays resolved from promises) are
+    // flattened into a DocumentFragment so each item lands in the DOM as its
+    // own node. Without this, append/replaceWith would stringify the array.
+    const frag = document.createDocumentFragment()
+    for (const child of node) {
+      frag.append(renderNode(child))
+    }
+    return frag
   } else if (node && typeof node === 'object') {
     if (typeof node.then === 'function') {
       let temp = h('div', { style: 'display:none', class: 'fntags-promise-marker' })