@srfnstack/fntags 0.2.1 → 0.3.3

package/package.json

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

package/src/fntags.mjs

@@ -1,40 +1,40 @@
 /**
  * A function to create dom elements with the given attributes and children.
- * If an argument is a non-node object it is considered an attributes object, attributes are combined with Object.assign in the order received.
- * All standard html attributes can be passed, as well as any other property.
- * Strings are added as attributes via setAttribute, functions are added as event listeners, other types are set as properties.
+ *
+ * The first element of the children array can be an object containing element attributes.
+ * The attribute names are the standard attribute names used in html, and should all be lower case as usual.
+ *
+ * Any attribute starting with 'on' that is a function is added as an event listener with the 'on' removed.
+ * i.e. { onclick: fn } gets added to the element as element.addEventListener('click', fn)
+ *
+ * The style attribute can be an object and the properties of the object will be added as style properties to the element.
+ * i.e. { style: { color: blue } } becomes element.style.color = blue
  *
  * The rest of the arguments will be considered children of this element and appended to it in the same order as passed.
  *
  * @param tag html tag to use when created the element
- * @param children optional attrs and children for the element
+ * @param children optional attributes object and children for the element
  * @returns HTMLElement an html element
  *
  */
-export function h () {
-  const tag = arguments[0]
-  let firstChildIdx = 1
+export function h (tag, ...children) {
+  let firstChildIdx = 0
   let element
   if (tag.startsWith('ns=')) {
-    element = document.createElementNS(...(tag.slice(3).split('|')))
+    element = document.createElementNS(...( tag.slice(3).split('|') ))
   } else {
     element = document.createElement(tag)
   }
 
-  if (isAttrs(arguments[firstChildIdx])) {
-    const attrs = arguments[firstChildIdx]
+  if (isAttrs(children[firstChildIdx])) {
+    const attrs = children[firstChildIdx]
     firstChildIdx += 1
     for (const a in attrs) {
-      let attr = attrs[a]
-      if (typeof attr === 'function' && attr.isBoundAttribute) {
-        attr.init(a, element)
-        attr = attr()
-      }
-      setAttribute(a, attr, element)
+      setAttribute(a, attrs[a], element)
     }
   }
-  for (let i = firstChildIdx; i < arguments.length; i++) {
-    const child = arguments[i]
+  for (let i = firstChildIdx; i < children.length; i++) {
+    const child = children[i]
     if (Array.isArray(child)) {
       for (const c of child) {
         element.append(renderNode(c))
@@ -46,16 +46,86 @@ export function h () {
   return element
 }
 
+/**
+ * Create a compiled template function. The returned function takes a single object that contains the properties
+ * defined in the template.
+ *
+ * This allows fast rendering by pre-creating a dom element with the entire template structure then cloning and populating
+ * the clone with data from the provided context. This avoids the work of having to re-execute the tag functions
+ * one by one and can speed up situations where the a similar element is created many times.
+ *
+ * You cannot bind state to the initial template. If you attempt to, the state will be read, but the elements will
+ * not be updated when the state changes because they will not be bound to the cloned element.
+ * Thus, all state bindings must be passed in the context to the compiled template to work correctly.
+ * @param templateFn {function(object): Node}
+ * @return {function(*): Node}
+ */
+export const fntemplate = templateFn => {
+  if (typeof templateFn !== 'function') {
+    throw new Error('You must pass a function to fntemplate. The function must return an html node.')
+  }
+  const placeholders = {}
+  let id = 1
+  const initContext = prop => {
+    if (!prop || typeof prop !== 'string') {
+      throw new Error('You must pass a non empty string prop name to the context function.')
+    }
+    const placeholder = (element, type, attrOrStyle) => {
+      let selector = element.__fnselector
+      if (!selector) {
+        selector = `fntpl-${id++}`
+        element.__fnselector = selector
+        element.classList.add(selector)
+      }
+      if (!placeholders[selector]) placeholders[selector] = []
+      placeholders[selector].push({ prop, type, attrOrStyle })
+    }
+    placeholder.isTemplatePlaceholder = true
+    return placeholder
+  }
+  // The initial render is cloned to prevent invalid state bindings from changing it
+  const compiled = templateFn(initContext).cloneNode(true)
+  return ctx => {
+    const clone = compiled.cloneNode(true)
+    for (const selectorClass in placeholders) {
+      let targetElement = clone.getElementsByClassName(selectorClass)[0]
+      if (!targetElement) {
+        if (clone.classList.contains(selectorClass)) {
+          targetElement = clone
+        } else {
+          throw new Error(`Cannot find template element for selectorClass ${selectorClass}`)
+        }
+      }
+      targetElement.classList.remove(selectorClass)
+      for (const placeholder of placeholders[selectorClass]) {
+        switch (placeholder.type) {
+          case 'node':
+            targetElement.replaceWith(renderNode(ctx[placeholder.prop]))
+            break
+          case 'attr':
+            setAttribute(placeholder.attrOrStyle, ctx[placeholder.prop], targetElement)
+            break
+          case 'style':
+            setStyle(placeholder.attrOrStyle, ctx[placeholder.prop], targetElement)
+            break
+          default:
+            throw new Error(`Unexpected bindType ${placeholder.type}`)
+        }
+      }
+    }
+    return clone
+  }
+}
+
 /**
  * Create a state object that can be bound to.
  * @param initialValue The initial state
  * @param mapKey A map function to extract a key from an element in the array. Receives the array value to extract the key from.
  * @returns function A function that can be used to get and set the state.
- * When getting the state, you get the actual reference to the underlying value. If you perform modifications to the object, be sure to set the value
- * when you're done or the changes won't be reflected correctly.
+ * When getting the state, you get the actual reference to the underlying value.
+ * If you perform modifications to the value, be sure to call the state function with the updated value when you're done
+ * or the changes won't be reflected correctly and binding updates won't be triggered even though the state appears to be correct.
  *
- * SideNote: this _could_ be implemented such that it returned a clone, however that would add a great deal of overhead, and a lot of code. Thus, the decision
- * was made that it's up to the caller to ensure that the fnstate is called whenever there are modifications.
  */
 export const fnstate = (initialValue, mapKey) => {
   const ctx = {
@@ -66,7 +136,7 @@ export const fnstate = (initialValue, mapKey) => {
     nextId: 0,
     mapKey,
     state (newState) {
-      if (arguments.length === 0 || (arguments.length === 1 && arguments[0] === ctx.state)) {
+      if (arguments.length === 0 || ( arguments.length === 1 && arguments[0] === ctx.state )) {
         return ctx.currentValue
       } else {
         ctx.currentValue = newState
@@ -92,46 +162,39 @@ export const fnstate = (initialValue, mapKey) => {
   /**
    * Bind this state to the given element
    *
-   * @param element The element to bind to. If not a function, an update function must be passed
-   * @param update If passed this will be executed directly when the state changes with no other intervention
-   * @returns {(HTMLDivElement|Text)[]|HTMLDivElement|Text}
-   */
-  ctx.state.bindAs = (element, update) => doBindAs(ctx, element, update)
-
-  /**
-   * Bind this state as it's value
-   *
+   * @param [element] The element to bind to. If not a function, an update function must be passed. If not passed, defaults to the state's value
+   * @param [update] If passed this will be executed directly when the state changes with no other intervention
    * @returns {(HTMLDivElement|Text)[]|HTMLDivElement|Text}
    */
-  ctx.state.bindSelf = () => doBindAs(ctx, ctx.state)
+  ctx.state.bindAs = (element, update) => doBindAs(ctx, element ?? ctx.state, update)
 
   /**
    * Bind attribute values to state changes
-   * @param attribute A function that returns an attribute value
+   * @param [attribute] A function that returns an attribute value. If not passed, defaults to the state's value
    * @returns {function(): *} A function that calls the passed function, with some extra metadata
    */
-  ctx.state.bindAttr = (attribute) => doBindAttr(ctx.state, attribute)
+  ctx.state.bindAttr = (attribute) => doBindAttr(ctx.state, attribute ?? ctx.state)
 
   /**
    * Bind style values to state changes
-   * @param style A function that returns a style's value
+   * @param [style] A function that returns a style's value. If not passed, defaults to the state's value
    * @returns {function(): *} A function that calls the passed function, with some extra metadata
    */
-  ctx.state.bindStyle = (style) => doBindStyle(ctx.state, style)
+  ctx.state.bindStyle = (style) => doBindStyle(ctx.state, style ?? ctx.state)
 
   /**
    * Bind select and deselect to an element
-   * @param element The element to bind to. If not a function, an update function must be passed
+   * @param [element] The element to bind to. If not a function, an update function must be passed. If not passed, defaults to the state's value
    * @param update If passed this will be executed directly when the state changes with no other intervention
    */
-  ctx.state.bindSelect = (element, update) => doBindSelect(ctx, element, update)
+  ctx.state.bindSelect = (element, update) => doBindSelect(ctx, element ?? ctx.state, update)
 
   /**
    * Bind select and deselect to an attribute
-   * @param attribute A function that returns an attribute value
+   * @param [attribute] A function that returns an attribute value. If not passed, defaults to the state's value
    * @returns {function(): *} A function that calls the passed function, with some extra metadata
    */
-  ctx.state.bindSelectAttr = (attribute) => doBindSelectAttr(ctx, attribute)
+  ctx.state.bindSelectAttr = (attribute) => doBindSelectAttr(ctx, attribute ?? ctx.state)
 
   /**
    * Mark the element with the given key as selected. This causes the bound select functions to be executed.
@@ -291,7 +354,7 @@ function doSelect (ctx, key) {
 
 function doBindChildren (ctx, parent, element, update) {
   parent = renderNode(parent)
-  if (parent === undefined) {
+  if (parent === undefined || parent.nodeType === undefined) {
     throw new Error('You must provide a parent element to bind the children to. aka Need Bukkit.')
   }
   if (typeof element !== 'function' && typeof update !== 'function') {
@@ -303,7 +366,7 @@ function doBindChildren (ctx, parent, element, update) {
   }
 
   if (!Array.isArray(ctx.currentValue)) {
-    return ctx.state.bindAs(element, update)
+    throw new Error('You can only use bindChildren with a state that contains an array. try myState([mystate]) before calling this function.')
   }
   ctx.currentValue = ctx.currentValue.map(v => v.isFnState ? v : fnstate(v))
   ctx.bindContexts.push({ element, update, parent })
@@ -513,7 +576,11 @@ const evaluateElement = (element, value) => {
  * Convert non objects (objects are assumed to be nodes) to text nodes and allow promises to resolve to nodes
  */
 export const renderNode = (node) => {
-  if (node && typeof node === 'object') {
+  if (node && node.isTemplatePlaceholder) {
+    const element = h('div')
+    node(element, 'node')
+    return element
+  } else if (node && typeof node === 'object') {
     if (typeof node.then === 'function') {
       let temp = h('div', { style: 'display:none', class: 'fntags-promise-marker' })
       node.then(el => {
@@ -563,13 +630,30 @@ const booleanAttributes = {
 }
 
 const setAttribute = function (attrName, attr, element) {
+  if (typeof attr === 'function') {
+    if (attr.isBoundAttribute) {
+      attr.init(attrName, element)
+      attr = attr()
+    } else if (attr.isTemplatePlaceholder) {
+      attr(element, 'attr', attrName)
+      return
+    } else if (attrName.startsWith('on')) {
+      element.addEventListener(attrName.substring(2), attr)
+      return
+    } else {
+      attr = attr()
+    }
+  }
   if (attrName === 'style' && typeof attr === 'object') {
     for (const style in attr) {
-      if (typeof attr[style] === 'function' && attr[style].isBoundStyle) {
-        attr[style].init(style, element)
-        attr[style] = attr[style]()
-      }
-      element.style[style] = attr[style] && attr[style].toString()
+      setStyle(style, attr[style], element)
+    }
+  } else if (attrName === 'class') {
+    //special handling for class to ensure the selector classes from fntemplate don't get overwritten
+    if (element.__fnselector && element.className) {
+      element.className += ` ${attr}`
+    } else {
+      element.className = attr
     }
   } else if (attrName === 'value') {
     element.setAttribute('value', attr)
@@ -577,17 +661,30 @@ const setAttribute = function (attrName, attr, element) {
     element.value = attr
   } else if (booleanAttributes[attrName]) {
     element[attrName] = !!attr
-  } else if (typeof attr === 'function' && attrName.startsWith('on')) {
-    element.addEventListener(attrName.substring(2), attr)
   } else {
     if (attrName.startsWith('ns=')) {
-      element.setAttributeNS(...(attrName.slice(3).split('|')), attr)
+      element.setAttributeNS(...( attrName.slice(3).split('|') ), attr)
     } else {
       element.setAttribute(attrName, attr)
     }
   }
 }
 
+const setStyle = (style, styleValue, element) => {
+  if (typeof styleValue === 'function') {
+    if (styleValue.isBoundStyle) {
+      styleValue.init(style, element)
+      styleValue = styleValue()
+    } else if (styleValue.isTemplatePlaceholder) {
+      styleValue(element, 'style', style)
+      return
+    } else {
+      styleValue = styleValue()
+    }
+  }
+  element.style[style] = styleValue && styleValue.toString()
+}
+
 export const isAttrs = (val) => val && typeof val === 'object' && val.nodeType === undefined && !Array.isArray(val) && typeof val.then !== 'function'
 /**
  * helper to get the attr object