npm - @srfnstack/fntags - Versions diffs - 0.3.2 → 0.3.6 - Mend

@srfnstack/fntags 0.3.2 → 0.3.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -1,7 +1,90 @@
-# fntags
+<p align="center">
+  <img alt="fntags header" src="https://raw.githubusercontent.com/SRFNStack/fntags/master/docs/fntags_header.gif">
+</p>
-> not your usual f'n framework
+---
-### [Documentation](https://srfnstack.github.io/fntags)
+## What the f?
+fntags primary goal is to make the developer experience pleasant while providing high performance and neato features.
-Check the docs to get started.
+- No dependencies and no build tools
+  <br> - Import the framework directly from your favorite cdn and start building.
+- Everything is javascript
+  <br> - There's no special templating language to learn, and you won't be writing html. <br> - This removes the template+functionality duality and helps keep you focused by removing context switching.
+- Real DOM elements
+  <br> - Every element is a real dom element, there's no virtual dom and no wrapper objects.
+- It's familiar
+  <br> - fntags was inspired by React, and the state management is similar to react hooks.
+- [State binding is explicit and granular](https://srfnstack.github.io/fntags/state#Binding%20State)
+  <br> - Bind only the text of an element, an attribute, or a style. You control the binding, replace as much or as little as you want.
+- State exists without components
+  <br> - This allows app wide states to be maintained using export/import and removes the need for complex state management like redux.
+- [Dynamic routing](https://srfnstack.github.io/fntags/routing#Dynamic%20Path%20Based%20Routing%3A%20modRouter)
+  <br> - The modRouter only loads the files required by each route and doesn't require bundling.
+  <br> - Bye bye fat bundles, hello highly cacheable routes.
+- [Async Rendering](https://srfnstack.github.io/fntags/components#Async%20Rendering)
+  <br> - fntags will resolve promises that are passed to element functions, no special handling required.
+## [Documentation](https://srfnstack.github.io/fntags)
+Check out the [documentation](https://srfnstack.github.io/fntags) to learn more!
+### f'n examples
+<hr>
+Components are plain functions
+```javascript
+import { div } from 'https://cdn.jsdelivr.net/npm/@srfnstack/fntags@0.3.3/src/fnelements.min.mjs'
+const hello = name => div('Hello ', name)
+document.body.append( hello('world!') )
+```
+Two-way binding is a breeze with the bind functions provided by fnstate objects.
+```javascript
+import { fnstate } from 'https://cdn.jsdelivr.net/npm/@srfnstack/fntags@0.3.3/src/fntags.min.mjs'
+import { div, input, br } from 'https://cdn.jsdelivr.net/npm/@srfnstack/fntags@0.3.3/src/fnelements.min.mjs'
+export const userName = fnstate('world')
+export const appColor = fnstate('MediumTurquoise')
+document.body.append(
+  div( { style: { color: appColor.bindStyle() } },
+    'Hello ', userName.bindAs(), '!'
+  ),
+  br(),
+  input({
+    value: userName.bindAttr(),
+    oninput: e => userName(e.target.value)
+  }),
+  br(),
+  input({
+    value: appColor.bindAttr(),
+    oninput: e => appColor(e.target.value)
+  }),
+)
+```
+### Required HTML
+Unfortunately browsers lack the ability to render a js file directly, and thus you still need a tiny bit of html to bootstrap your app.
+Here's an example of the only html you need to write for your entire application.
+Now that these two lines are there you're set to write sweet sweet es6+ and no more html.
+```html
+<html><body><script type="module">
+import { div } from 'https://cdn.jsdelivr.net/npm/@srfnstack/fntags@0.3.3/src/fnelements.min.mjs'
+document.body.append(div('hello world!'))
+</script></body></html>
+```
+### Benchmark
+Check the latest benchmark results in the widely used [JS Web Frameworks Benchmark](https://krausest.github.io/js-framework-benchmark/current.html)!

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@srfnstack/fntags",
-  "version": "0.3.2",
+  "version": "0.3.6",
   "author": "Robert Kempton <r@snow87.com>",
   "private": false,
   "homepage": "https://github.com/srfnstack/fntags",
@@ -30,7 +30,8 @@
     "state-management"
   ],
   "devDependencies": {
-    "cypress": "^6.8.0",
+    "cypress": "^9.2.0",
+    "pre-commit": "^1.2.2",
     "standard": "^16.0.4"
   },
   "scripts": {
@@ -38,5 +39,9 @@
     "cypress": "cypress run --spec test/** -b chrome",
     "lint": "standard --env browser src && standard --env browser --env jest --global Prism --global cy test docs",
     "lint:fix": "standard --env browser --fix src && standard --env browser --env jest --global Prism --global cy --fix test docs"
-  }
+  },
+  "pre-commit": [
+    "lint",
+    "test"
+  ]
 }

package/src/fnroute.mjs CHANGED Viewed

@@ -104,7 +104,12 @@ export const modRouter = ({ routePath, attrs, onerror, frame, sendRawPath, forma
     }
     const filePath = path ? routePath + ensureOnlyLeadingSlash(path) : routePath
-    const p = moduleCache[filePath] ? Promise.resolve(moduleCache[filePath]) : import(filePath).then(m => { moduleCache[filePath] = m })
+    const p = moduleCache[filePath]
+      ? Promise.resolve(moduleCache[filePath])
+      : import(filePath).then(m => {
+        moduleCache[filePath] = m
+        return m
+      })
     p.then(module => {
       const route = module.default

package/src/fntags.mjs CHANGED Viewed

@@ -1,19 +1,24 @@
 /**
  * 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('|')))
@@ -21,15 +26,15 @@ export function h () {
     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) {
       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))
@@ -45,26 +50,31 @@ export function h () {
  * 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 precreating a dom element with the entire template structure and cloning and populating
+ * 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 same elements are created many times.
+ * one by one and can speed up situations where 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.
- *
- * All state bindings must be passed to the compiled template function to work correctly.
+ * 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 => {
-  const placeholders = { }
+  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.selector
+      let selector = element.__fnselector
       if (!selector) {
-        selector = `fntpl-${prop}-${id++}`
-        element.selector = selector
+        selector = `fntpl-${id++}`
+        element.__fnselector = selector
         element.classList.add(selector)
       }
       if (!placeholders[selector]) placeholders[selector] = []
@@ -74,16 +84,20 @@ export const fntemplate = templateFn => {
     return placeholder
   }
   // The initial render is cloned to prevent invalid state bindings from changing it
-  const rendered = templateFn(initContext).cloneNode(true)
+  const compiled = templateFn(initContext).cloneNode(true)
   return ctx => {
-    const clone = rendered.cloneNode(true)
+    const clone = compiled.cloneNode(true)
     for (const selectorClass in placeholders) {
-      const targetElement = clone.classList.contains(selectorClass) ? clone : clone.getElementsByClassName(selectorClass)[0]
+      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]) {
-        if (!ctx[placeholder.prop]) {
-          console.warn(`No value provided for template prop: ${placeholder.prop}`)
-        }
         switch (placeholder.type) {
           case 'node':
             targetElement.replaceWith(renderNode(ctx[placeholder.prop]))
@@ -108,11 +122,10 @@ export const fntemplate = templateFn => {
  * @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 = {
@@ -126,9 +139,10 @@ export const fnstate = (initialValue, mapKey) => {
       if (arguments.length === 0 || (arguments.length === 1 && arguments[0] === ctx.state)) {
         return ctx.currentValue
       } else {
+        const oldState = ctx.currentValue
         ctx.currentValue = newState
         for (const observer of ctx.observers) {
-          observer.fn(newState)
+          observer.fn(newState, oldState)
         }
       }
       return newState
@@ -299,6 +313,7 @@ function createBoundAttr (attr) {
   if (typeof attr !== 'function') {
     throw new Error('You must pass a function to bindAttr')
   }
+  // wrap the function to avoid modifying it
   const boundAttr = () => attr()
   boundAttr.isBoundAttribute = true
   return boundAttr
@@ -341,7 +356,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') {
@@ -353,11 +368,11 @@ 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 })
-  ctx.state.subscribe(() => {
+  ctx.state.subscribe((newState, 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.')
       new Promise((resolve) => {
@@ -371,7 +386,7 @@ function doBindChildren (ctx, parent, element, update) {
         throw e
       })
     } else {
-      reconcile(ctx)
+      reconcile(ctx, oldState)
     }
   })
   reconcile(ctx)
@@ -443,12 +458,12 @@ const doBindAs = (ctx, element, update) =>
 /**
  * Reconcile the state of the current array value with the state of the bound elements
  */
-function reconcile (ctx) {
+function reconcile (ctx, oldState) {
   for (const bindContext of ctx.bindContexts) {
     if (bindContext.boundElementByKey === undefined) {
       bindContext.boundElementByKey = {}
     }
-    arrangeElements(ctx, bindContext)
+    arrangeElements(ctx, bindContext, oldState)
   }
 }
@@ -462,7 +477,7 @@ function keyMapper (mapKey, value) {
   }
 }
-function arrangeElements (ctx, bindContext) {
+function arrangeElements (ctx, bindContext, oldState) {
   if (ctx.currentValue.length === 0) {
     bindContext.parent.textContent = ''
     bindContext.boundElementByKey = {}
@@ -479,7 +494,8 @@ function arrangeElements (ctx, bindContext) {
     }
     const key = keyMapper(ctx.mapKey, valueState())
     if (keys[key]) {
-      throw new Error('Duplicate keys in a bound array are not allowed.')
+      if (oldState) ctx.state(oldState)
+      throw new Error('Duplicate keys in a bound array are not allowed, state reset to previous value.')
     }
     keys[key] = i
     keysArr[i] = key
@@ -636,8 +652,8 @@ const setAttribute = function (attrName, attr, element) {
       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.selector && element.className) {
+    // 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
@@ -690,9 +706,18 @@ export const getAttrs = (children) => Array.isArray(children) && isAttrs(childre
 export const styled = (style, tag, children) => {
   const firstChild = children[0]
   if (isAttrs(firstChild)) {
-    children[0].style = Object.assign(style, firstChild.style)
+    if (typeof firstChild.style === 'string') {
+      firstChild.style = [stringifyStyle(style), stringifyStyle(firstChild.style)].join(';')
+    } else {
+      firstChild.style = Object.assign(style, firstChild.style)
+    }
   } else {
     children.unshift({ style })
   }
   return h(tag, ...children)
 }
+const stringifyStyle = style =>
+  typeof style === 'string'
+    ? style
+    : Object.keys(style).map(prop => `${prop}:${style[prop]}`).join(';')