@srfnstack/fntags 1.2.8 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@srfnstack/fntags",
-  "version": "1.2.8",
+  "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

@@ -72,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
  */

package/src/fntags.d.mts.map

@@ -1 +1 @@
-{"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"}
+{"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

@@ -81,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))
       }
@@ -500,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')
@@ -512,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
@@ -611,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
@@ -790,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
@@ -859,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
  */
@@ -868,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' })