npm - @srfnstack/fntags - Versions diffs - 0.4.1 → 0.4.2 - Mend

@srfnstack/fntags 0.4.1 → 0.4.2

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

@@ -38,52 +38,45 @@ 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'
+Start a new app with one file
+```html
+<html><body>
+<script type="module">
+import { div } from 'https://cdn.jsdelivr.net/npm/@srfnstack/fntags@0.4.1/src/fnelements.min.mjs'
+document.body.append(div('Hello World!'))
+</script>
+</body></html>
+```
+Make re-usable, customizable components using plain js functions
+```javascript
 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.
+Explicit two-way state binding
 ```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)
-  }),
-)
-```
+import { fnstate } from 'https://cdn.jsdelivr.net/npm/@srfnstack/fntags@0.4.1/src/fntags.min.mjs'
+import { div, input, br } from 'https://cdn.jsdelivr.net/npm/@srfnstack/fntags@0.4.1/src/fnelements.min.mjs'
-### 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.
+const helloInput = () => {
+  const name = fnstate('World')
-Here's an example of the only html you need to write for your entire application.
+  const nameInput = input({
+    value: name.bindAttr(),
+    oninput (){ name(nameInput.value) }
+  })
-Now that these two lines are there you're set to write sweet sweet es6+ and no more html.
+  return div(
+    div('Hello ', name.bindAs(), '!'),
+    br(),
+    nameInput
+  )
+}
-```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>
+document.body.append(helloInput())
 ```
 ### Benchmark

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@srfnstack/fntags",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "author": "Robert Kempton <r@snow87.com>",
   "private": false,
   "homepage": "https://github.com/srfnstack/fntags",
@@ -30,15 +30,21 @@
     "state-management"
   ],
   "devDependencies": {
-    "cypress": "10.3.0",
+    "cypress": "13.6.1",
     "pre-commit": "^1.2.2",
-    "standard": "^16.0.4"
+    "standard": "^17.1.0",
+    "typedoc": "^0.25.4",
+    "typedoc-plugin-markdown": "^3.17.1",
+    "typescript": "^5.3.3"
   },
   "scripts": {
     "test": "cp src/* docs/lib/ && npm run lint && cypress run --spec test/** --headless -b chrome",
     "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"
+    "lint:fix": "standard --env browser --fix src && standard --env browser --env jest --global Prism --global cy --fix test docs",
+    "typedef": "tsc",
+    "docs": "typedoc --plugin typedoc-plugin-markdown --out docs/types ./src/*.mjs",
+    "build": "npm run lint:fix && npm run typedef && npm run docs && npm run test"
   },
   "pre-commit": [
     "lint",

package/src/fnroute.mjs CHANGED Viewed

@@ -1,7 +1,11 @@
+/// <reference path="fntags.mjs" name="fntags"/>
+/**
+ * @module fnroute
+ */
 import { fnstate, getAttrs, h, isAttrs, renderNode } from './fntags.mjs'
 /**
- * An element that is displayed only if the the current route starts with elements path attribute.
+ * An element that is displayed only if the current route starts with elements path attribute.
  *
  * For example,
  *  route({path: "/proc"},
@@ -24,10 +28,10 @@ import { fnstate, getAttrs, h, isAttrs, renderNode } from './fntags.mjs'
  *          )
  *      )
  *
- * @param children The attributes and children of this element.
- * @returns HTMLDivElement
+ * @param {any} children The attributes and children of this element.
+ * @returns {HTMLDivElement} A div element that will only be displayed if the current route starts with the path attribute.
  */
-export const route = (...children) => {
+export function route (...children) {
   const attrs = getAttrs(children)
   children = children.filter(c => !isAttrs(c))
   const routeEl = h('div', attrs)
@@ -50,9 +54,10 @@ export const route = (...children) => {
 /**
  * An element that only renders the first route that matches and updates when the route is changed
  * The primary purpose of this element is to provide catchall routes for not found pages and path variables
- * @param children
+ * @param {any} children
+ * @returns {HTMLDivElement}
  */
-export const routeSwitch = (...children) => {
+export function routeSwitch (...children) {
   const sw = h('div', getAttrs(children))
   return pathState.bindAs(
@@ -89,7 +94,18 @@ function stripParameterValues (currentRoute) {
 const moduleCache = {}
-export const modRouter = ({ routePath, attrs, onerror, frame, sendRawPath, formatPath }) => {
+/**
+ * The main function of this library. It will load the route at the specified path and render it into the container element.
+ * @param {object} options
+ * @param {string} options.routePath The path to the root of the routes. This is used to resolve the paths of the routes.
+ * @param {object} options.attrs The attributes of the container element
+ * @param {(error: Error, newPathState: object)=>void} options.onerror A function that will be called if the route fails to load. The function receives the error and the current pathState object.
+ * @param {(node: Node, module: object)=>Node} options.frame A function that will be called with the rendered route element and the module that was loaded. The function should return a new element to be rendered.
+ * @param {boolean} options.sendRawPath If true, the raw path will be sent to the route. Otherwise, the path will be stripped of parameter values.
+ * @param {(path: string)=>string} options.formatPath A function that will be called with the raw path before it is used to load the route. The function should return a new path.
+ * @return {HTMLElement} The container element
+ */
+export function modRouter ({ routePath, attrs, onerror, frame, sendRawPath, formatPath }) {
   const container = h('div', attrs || {})
   if (!routePath) {
     throw new Error('You must provide a root url for modRouter. Routes in the ui will be looked up relative to this url.')
@@ -104,8 +120,8 @@ export const modRouter = ({ routePath, attrs, onerror, frame, sendRawPath, forma
     }
     const filePath = path ? routePath + ensureOnlyLeadingSlash(path) : routePath
-    const p = moduleCache[filePath]
-      ? Promise.resolve(moduleCache[filePath])
+    const p = moduleCache[filePath]
+      ? Promise.resolve(moduleCache[filePath])
       : import(filePath).then(m => {
         moduleCache[filePath] = m
         return m
@@ -171,9 +187,10 @@ function updatePathParameters () {
 /**
  * A link element that is a link to another route in this single page app
- * @param children The attributes of the anchor element and any children
+ * @param {any} children The attributes of the anchor element and any children
+ * @returns {HTMLAnchorElement} An anchor element that will navigate to the specified route when clicked
  */
-export const fnlink = (...children) => {
+export function fnlink (...children) {
   let context = null
   if (children[0] && children[0].context) {
     context = children[0].context
@@ -198,12 +215,12 @@ export const fnlink = (...children) => {
 /**
  * A function to navigate to the specified route
- * @param route The route to navigate to
- * @param context Data related to the route change
- * @param replace Whether to replace the state or push it. pushState is used by default.
- * @param silent Prevent route change events from being emitted for this route change
+ * @param {string} route The route to navigate to
+ * @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 const goTo = (route, context, replace = false, silent = false) => {
+export function goTo (route, context, replace = false, silent = false) {
   const newPath = window.location.origin + makePath(route)
   const patch = {
@@ -252,8 +269,26 @@ const ensureOnlyLeadingSlash = (part) => removeTrailingSlash(part.startsWith('/'
 const removeTrailingSlash = part => part.endsWith('/') && part.length > 1 ? part.slice(0, -1) : part
+/**
+ * Key value pairs of path parameter names to their values
+ * @typedef {Object} PathParameters
+ */
+/**
+ * The path parameters of the current route
+ * @type {import("./fntags.mjs").FnState<PathParameters>}
+ */
 export const pathParameters = fnstate({})
+/**
+ * The path information for a route
+ * @typedef {{currentRoute: string, rootPath: string, context: any}} PathState
+ */
+/**
+ * The current path state
+ * @type {import("./fntags.mjs").FnState<PathState>}
+ */
 export const pathState = fnstate(
   {
     rootPath: ensureOnlyLeadingSlash(window.location.pathname),
@@ -261,8 +296,23 @@ export const pathState = fnstate(
     context: null
   })
+/**
+ * @typedef {string} RouteEvent
+ */
+/**
+ * Before the route is changed
+ * @type {RouteEvent}
+ */
 export const beforeRouteChange = 'beforeRouteChange'
+/**
+ * After the route is changed
+ * @type {RouteEvent}
+ */
 export const afterRouteChange = 'afterRouteChange'
+/**
+ * After the route is changed and the route element is rendered
+ * @type {RouteEvent}
+ */
 export const routeChangeComplete = 'routeChangeComplete'
 const eventListeners = {
   [beforeRouteChange]: [],
@@ -279,9 +329,9 @@ const emit = (event, newPathState, oldPathState) => {
  * @param event a string event to listen for
  * @param handler A function that will be called when the event occurs.
  *                  The function receives the new and old pathState objects, in that order.
- * @return {function()} a function to stop listening with the passed handler.
+ * @return {()=>void} a function to stop listening with the passed handler.
  */
-export const listenFor = (event, handler) => {
+export function listenFor (event, handler) {
   if (!eventListeners[event]) {
     throw new Error(`Invalid event. Must be one of ${Object.keys(eventListeners)}`)
   }
@@ -296,12 +346,14 @@ export const listenFor = (event, handler) => {
 /**
  * Set the root path of the app. This is necessary to make deep linking work in cases where the same html file is served from all paths.
+ * @param {string} rootPath The root path of the app
  */
-export const setRootPath = (rootPath) =>
-  pathState.assign({
+export function setRootPath (rootPath) {
+  return pathState.assign({
     rootPath: ensureOnlyLeadingSlash(rootPath),
     currentRoute: ensureOnlyLeadingSlash(window.location.pathname.replace(new RegExp('^' + rootPath), '')) || '/'
   })
+}
 window.addEventListener(
   'popstate',

package/src/fntags.mjs CHANGED Viewed

@@ -1,3 +1,6 @@
+/**
+ * @module fntags
+ */
 /**
  * A function to create dom elements with the given attributes and children.
  *
@@ -12,9 +15,9 @@
  *
  * 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 attributes object and children for the element
- * @returns HTMLElement an html element
+ * @param {string} tag html tag to use when created the element
+ * @param {object[]?|Node[]?} children optional attributes object and children for the element
+ * @return {HTMLElement} an html element
  *
  */
 export function h (tag, ...children) {
@@ -79,10 +82,12 @@ function hasNs (val) {
  * 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 in the context to the compiled template to work correctly.
- * @param templateFn {function(object): Node}
- * @return {function(*): Node}
+ *
+ * @param {(any)=>Node} templateFn A function that returns an html node.
+ * @return {(any)=>Node} A function that takes a context object and returns a rendered node.
+ *
  */
-export const fntemplate = templateFn => {
+export function fntemplate (templateFn) {
   if (typeof templateFn !== 'function') {
     throw new Error('You must pass a function to fntemplate. The function must return an html node.')
   }
@@ -139,17 +144,53 @@ export const fntemplate = templateFn => {
   }
 }
+/**
+ * @template T The type of data stored in the state container
+ * @typedef FnStateObj A container for a state value that can be bound to.
+ * @property {(element: (T)=>void|Node|any?, update: (Node)=>void?) => Node|() => Node} bindAs Bind this state to the given element. This causes the element to update when state changes.
+ * If called with no parameters, the state's value will be rendered as an element. If the first parameters is not a function,
+ * the second parameter (the update function) must be provided and must be a function. This function receives the node the state is bound to.
+ * @property {(parent: Node,element: Node|any, update: (Node)=>void?)=> Node|()=> 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|()=>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: string)=>any} bindAttr Bind attribute values to state changes
+ * @property {(style: string)=> string} bindStyle Bind style values to state changes
+ * @property {(element: Node|any, update: (Node)=>void?)=>Node|()=>Node} bindSelect Bind selected state to an element
+ * @property {(attribute: string)=>any} bindSelectAttr Bind selected state to an attribute
+ * @property {(key: any)=>void} select Mark the element with the given key as selected
+ * where the key is identified using the mapKey function passed on creation of the fnstate.
+ * This causes the bound select functions to be executed.
+ * @property {()=> any} selected Get the currently selected key
+ * @property {(update: T)=>void} assign Perform an Object.assign() on the current state using the provided update, triggers
+ * a state change and is a shortcut for `mystate(Object.assign(mystate(), update))`
+ * @property {(path: string)=>any} getPath Get a value at the given property path, an error is thrown if the value is not an object
+ * This returns a reference to the real current value. If you perform any modifications to the object, be sure to call setPath after you're done or the changes
+ * will not be reflected correctly.
+ * @property {(path: string, value: any, fillWithObjects: boolean)=>void} setPath Set a value at the given property path
+ * @property {((newState: T, oldState: T)=>void)=>void} subscribe Register a callback that will be executed whenever the state is changed
+ * @property {(reinit: boolean)=>{}} reset Remove all of the observers and optionally reset the value to it's initial value
+ * @property {} isFnState A flag to indicate that this is an fnstate object
+ */
+/**
+ * @template T The type of data stored in the state container
+ * @typedef {FnStateObj<T> & (newState: T?)=>T} FnState A container for a state value that can be bound to.
+ */
 /**
  * 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.
+ * @template T
+ * @param {T|any} initialValue The initial state
+ * @param {function(T): any?} mapKey A map function to extract a key from an element in the array. Receives the array value to extract the key from.
+ * A key can be any unique value.
+ * @return {FnState<T>} 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 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.
- *
  */
-export const fnstate = (initialValue, mapKey) => {
+export function fnstate (initialValue, mapKey) {
   const ctx = {
     currentValue: initialValue,
     observers: [],
@@ -171,6 +212,15 @@ 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. 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.bindAs = (element, update) => doBindAs(ctx, element ?? ctx.state, update)
   /**
    * Bind the values of this state to the given element.
    * Values are items/elements of an array.
@@ -183,16 +233,7 @@ export const fnstate = (initialValue, mapKey) => {
   ctx.state.bindChildren = (parent, element, update) => doBindChildren(ctx, parent, element, update)
   /**
-   * Bind this state to the given element
-   *
-   * @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.bindAs = (element, update) => doBindAs(ctx, element ?? ctx.state, update)
-  /**
-   * Bind a property of an object stored in this state as a simple value.
+   * Bind to a property of an object stored in this state instead of the state itself.
    *
    * Shortcut for `mystate.bindAs((current)=> current[prop])`
    *
@@ -609,8 +650,10 @@ const evaluateElement = (element, value) => {
 /**
  * Convert non objects (objects are assumed to be nodes) to text nodes and allow promises to resolve to nodes
+ * @param {any} node The node to render
+ * @returns {Node} The rendered node
  */
-export const renderNode = (node) => {
+export function renderNode (node) {
   if (node && node.isTemplatePlaceholder) {
     const element = h('div')
     node(element, 'node')
@@ -719,22 +762,34 @@ const setStyle = (style, styleValue, element) => {
   element.style[style] = styleValue && styleValue.toString()
 }
-export const isAttrs = (val) => val && typeof val === 'object' && val.nodeType === undefined && !Array.isArray(val) && typeof val.then !== 'function'
+/**
+ * Check if the given value is an object that can be used as attributes
+ * @param {any} val The value to check
+ * @returns {boolean} true if the value is an object that can be used as attributes
+ */
+export function isAttrs (val) {
+  return val && typeof val === 'object' && val.nodeType === undefined && !Array.isArray(val) && typeof val.then !== 'function'
+}
 /**
  * helper to get the attr object
+ * @param {any} children
+ * @return {object} the attr object or an empty object
  */
-export const getAttrs = (children) => Array.isArray(children) && isAttrs(children[0]) ? children[0] : {}
+export function getAttrs (children) {
+  return Array.isArray(children) && isAttrs(children[0]) ? children[0] : {}
+}
 /**
  * A function to create an element with a pre-defined style.
  * For example, the flex* elements in fnelements.
  *
- * @param style
- * @param tag
- * @param children
- * @return {*}
+ * @param {object|string} style The style to apply to the element
+ * @param {string} tag The tag to use when creating the element
+ * @param {object|object[]?} children The children to append to the element
+ * @return {*} The styled element
  */
-export const styled = (style, tag, children) => {
+export function styled (style, tag, children) {
   const firstChild = children[0]
   if (isAttrs(firstChild)) {
     if (typeof firstChild.style === 'string') {