halfcab 15.0.6 → 16.0.0

package/README.md

@@ -25,7 +25,7 @@ Halfcab is no longer built as a common js distribution.
 halfcab exposes a bunch of functions and objects that you import from the halfcab module. If you want to grab them all at once ( you don't ), it'd look like this:
 
 ```js
-import halfcab, { html, css, injectHTML, injectMarkdown, geb, eventEmitter, updateState, rerender, formField, formIsValid, fieldIsTouched, resetTouched, ssr, defineRoute, gotoRoute, http, getRouteComponent, nextTick, Component, LRU, PureComponent, cachedComponent } from 'halfcab'
+import halfcab, { html, css, injectHTML, injectMarkdown, geb, eventEmitter, updateState, rerender, formField, formIsValid, fieldIsTouched, resetTouched, ssr, defineRoute, gotoRoute, http, getRouteComponent, nextTick } from 'halfcab'
 ```
 
 ## Installation
@@ -55,21 +55,17 @@ halfcab({
 #### Components
 - `html` - creates dom elements from template literals
 - `css` - injects css into html component's class property
-- `Component` - nanocomponent: https://www.npmjs.com/package/nanocomponent
-- `LRU` - nanolru: https://www.npmjs.com/package/nanolru
-- `PureComponent` - Extends Component and only rerenders when arguments change
-- `cachedComponent` - pair with PureComponent to automatically cache components using LRU and only rerender when arguments change
-- `injectHTML` - injects html from a string, much like a triple mustache or React's dangerouslySetInnerHTML
+- `injectHTML` - injects html from a string, much like a triple mustache or React's dangerouslySetInnerHTML. Uses lit-html's unsafeHTML
 - `injectMarkdown` - the same as `injectHTML` but first converts markdown into HTML, making sure HTML entities are not double encoded.
 
 Both injectHTML and injectMarkdown have a second argument for options. Currently there's just a single option:
 
 ```{wrapper: false}``` (default is true)
 
-By default injected html will have a wrapping `<div>`. This is to ensure an html element can successfully be made (required by nanohtml)
+By default injected html will have a wrapping `<div>`. This is to ensure an html element can successfully be made.
 If you know that your HTML already has a wrapping element, or it's just a single element, you can set the wrapper to false. Particularly useful when dealing with SVGs.
 
-Under the hood, halfcab uses nanohtml + nanomorph, which turns tagged template literals into elements, and updates the DOM.
+Under the hood, halfcab uses lit-html, which turns tagged template literals into elements, and updates the DOM.
 
 Here's an example of a simple component:
 ```js
@@ -82,7 +78,7 @@ export default args => html`
         <img src="${args.company.logo.url}" />
       </div>
   
-      <div style="width: 216px; text-align: center;" ${args.disabled ? {disabled} : ''}>        
+      <div style="width: 216px; text-align: center;" ?disabled=${args.disabled}>        
         <button onclick=${e => {
         alert('I am a button')}} 
         >Log in <i class="material-icons" style="vertical-align: inherit">account_circle</i>
@@ -93,9 +89,10 @@ export default args => html`
 `
 
 ```
-
 This is just regular HTML with one twist - Using event handlers like onclick will use the scope of your component, not the global scope. Just don't use quotation marks around it. Put it within ${ } instead.
 
+Note: As of version 15, to conditionally include html flags like `disabled`, halfcab now uses the lit-html syntax starting with a question mark, so like the example above, you'd have: `?disabled=${args.disabled}`, where we used to have the nanohtml syntax like this: `${args.disabled ? {disabled} : ''}`
+
 halfcab uses csjs for inline css, like so:
 ```js
 import { html, css } from 'halfcab'
@@ -118,7 +115,7 @@ let styles = css`
 `
 
 export default args => html`
-  <header class=${styles.header}>
+  <header class="${styles.header}">
     <nav>
       <div style="width: 280px;">
         <img src="${args.company.logo.url}" />
@@ -138,24 +135,7 @@ Notice how you can use media queries, and inject variables using JavaScript! The
 
 
 #### Performance
-For larger apps you can get a major performance boost by using the provided `Component`, and `LRU` classes. See nanocomponent and nanolru libraries for details.
-
-For convenience if you want to write pure components that are cached you can use `PureComponent` and not have to have an update method and return cached components like so:
-
-```js
-class DateTimePicker extends PureComponent {
-  createElement(args) {
-    this.myFunction = args.myFunction
-    return html`<div>Datepicker ${args.something}</div>`
-  }
-}
-export default args => cachedComponent(DateTimePicker, args, args.uniqueKey)
-
-```
-
-Make sure you have a uniqueKey (id) so that the component is properly cached and not referenced by any other call to cachedComponent
-
-In the example above, the component that matches the uniqueKey will be extracted from the cache, the new args will be compared against the previous args, and if there's a difference, it will rerender, and if not, you'll just get the existing element from the cache. Note that this does a deep compare of objects and for functions it just copies them across. So make sure that all your functions are copied to `this`. If you see the line with `this.myFunction = args.myFunction` - this is done when the element is created, but it will also automatically be run for anything argument that is a function when performing an update. This is so that if your function argument has closed over any other variables from elsewhere, it always gets the latest function, even if it's not having to rerender the element.
+From version 15 onwards, lit-html is used under the hood (replacing nanohtml and nanomorph) so the old caching system functions have been removed as lit-html is efficient out of the box. This keeps things really simple as you no longer need to provide uniqueKeys for component caching and can just use functions as there's no need for extending classes or managing a cache.
 
 #### Events
 - `geb` - global event bus
@@ -489,8 +469,6 @@ htmlTemplate.mjs
 import pack from '../../../package'
 import components from '../../../components'
 import { ssr } from 'halfcab'
-import { minify } from 'html-minifier'
-
 
 function htmlOutput(data){
   let apiData = data[0]
@@ -510,7 +488,7 @@ function htmlOutput(data){
       </head>
       <body style="padding: 0px; margin: 0px;">
       
-      ${componentsString}
+      <div id="root">${componentsString}</div>
       
       </body>
     </html>
@@ -518,10 +496,7 @@ function htmlOutput(data){
 }
 
 
-export default data => minify(htmlOutput(data), {
-  collapseWhitespace: true,
-  minifyCSS: true
-})
+export default data => htmlOutput(data)
 ```
 
 ###### Browser JS structure
@@ -550,9 +525,6 @@ halfcab({
 })
 
 ```
-Notice:
-1. This browser code is also creating an mock function to add to the cd object, but this time, it's actually importing the real someBrowserOnlyLib library and using it before returning the element.
-2. The halfcab function returns a promise that returns our root element ready for us to use.
 
 ###### The common file between server and browser - components.mjs
 
@@ -570,8 +542,8 @@ function products(products){
   }
 }
 
-export default args => cd.mock(html`
-  <div id="root" style="margin-top: 10px; text-align: center;">
+export default args => html`
+  <div style="margin-top: 10px; text-align: center;">
     ${topNav({
       company: args.company,
       products: products(args.products)
@@ -584,7 +556,7 @@ export default args => cd.mock(html`
     ${footer()}
     ${injectHTML(args.safeHTMLFromServer)}
   </div>
-`)
+`
 ```
 
 This is our top level component, from here we're also pulling in three other components - topNav, body, and footer. This is the start of the tree-like component structure.

package/halfcab.mjs

@@ -18,7 +18,7 @@ let cssTag = cssInject
 let componentCSSString = ''
 let routesArray = []
 let externalRoutes = []
-let state = {}
+let rawState = {}
 let router
 let rootEl
 let components
@@ -39,14 +39,14 @@ function b64DecodeUnicode (str) {
 if (typeof window !== 'undefined') {
   dataInitial = document.querySelector('[data-initial]')
   if (!!dataInitial) {
-    state = (dataInitial && dataInitial.dataset.initial) && Object.assign({}, JSON.parse(b64DecodeUnicode(dataInitial.dataset.initial)))
+    rawState = (dataInitial && dataInitial.dataset.initial) && Object.assign({}, JSON.parse(b64DecodeUnicode(dataInitial.dataset.initial)))
 
-    if (!state.router) {
-      state.router = {}
+    if (!rawState.router) {
+      rawState.router = {}
     }
 
-    if (!state.router.pathname) {
-      Object.assign(state.router, {
+    if (!rawState.router.pathname) {
+      Object.assign(rawState.router, {
         pathname: window.location.pathname,
         hash: window.location.hash,
         query: qs.parse(window.location.search)
@@ -62,6 +62,32 @@ if (typeof window !== 'undefined') {
   }
 }
 
+const proxyCache = new WeakMap()
+
+function createState (target) {
+  if (proxyCache.has(target)) {
+    return proxyCache.get(target)
+  }
+  const proxy = new Proxy(target, {
+    get (obj, prop) {
+      const value = obj[prop]
+      if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        return createState(value)
+      }
+      return value
+    },
+    set (obj, prop, value) {
+      obj[prop] = value
+      debounce(stateUpdated)
+      return true
+    }
+  })
+  proxyCache.set(target, proxy)
+  return proxy
+}
+
+let state = createState(rawState)
+
 let geb = new eventEmitter({state})
 
 const stringsCache = new WeakMap()
@@ -316,19 +342,30 @@ function stateUpdated () {
   }
 }
 
+function mergeInPlace (target, source) {
+  // Recursively merge source into target, mutating target in-place so that
+  // existing object references (and their Proxy wrappers) are preserved.
+  // Arrays are always replaced entirely — merging arrays is complex and error-prone.
+  for (const key of Object.keys(source)) {
+    const srcVal = source[key]
+    const tgtVal = target[key]
+    if (srcVal !== null && typeof srcVal === 'object' && !Array.isArray(srcVal) &&
+        tgtVal !== null && typeof tgtVal === 'object' && !Array.isArray(tgtVal)) {
+      mergeInPlace(tgtVal, srcVal)
+    } else {
+      target[key] = srcVal
+    }
+  }
+}
+
 function updateState (updateObject, options) {
   if (updateObject) {
     if (options && options.deepMerge === false) {
-      Object.assign(state, updateObject)
+      Object.assign(rawState, updateObject)
     } else {
-      let deepMergeOptions = {clone: false}
-      if (options && options.arrayMerge === false) {
-        deepMergeOptions.arrayMerge = (destinationArray, sourceArray, options) => {
-          //don't merge arrays, just return the new one
-          return sourceArray
-        }
-      }
-      Object.assign(state, merge(state, updateObject, deepMergeOptions))
+      // Merge in-place so existing nested object references stay intact,
+      // keeping Proxy cache entries valid.
+      mergeInPlace(rawState, updateObject, options)
     }
   }
 
@@ -344,7 +381,7 @@ function updateState (updateObject, options) {
     console.log(updateObject)
     console.log('  ')
     console.log('------NEW STATE------')
-    console.log(state)
+    console.log(rawState)
     console.log('  ')
   }
 
@@ -513,6 +550,10 @@ export default (config, {shiftyRouter = shiftyRouterModule, href = hrefModule, h
   })
 }
 
+/**
+ * @deprecated The Proxy-based state now triggers rerenders automatically via set traps.
+ * This function is kept for backwards compatibility but is no longer needed in most cases.
+ */
 function rerender () {
   debounce(stateUpdated)
 }
@@ -529,6 +570,7 @@ export {
   html,
   defineRoute,
   updateState,
+  createState,
   state,
   formField,
   gotoRoute,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "halfcab",
-  "version": "15.0.6",
+  "version": "16.0.0",
   "type": "module",
   "description": "A simple universal JavaScript framework focused on making use of es2015 template strings to build components.",
   "main": "halfcab.mjs",
@@ -11,7 +11,7 @@
     "test:coverage": "c8 --reporter=html --check-coverage --lines 75 --functions 75 --branches 75 npm test",
     "test:coveralls": "c8 npm test && c8 report --reporter=text-lcov | coveralls",
     "versionbump:fix": "npm version patch --no-git-tag-version",
-    "versionbump:feature": "npm version major --no-git-tag-version",
+    "versionbump:feature": "npm version minor --no-git-tag-version",
     "versionbump:breakingchanges": "npm version major --no-git-tag-version",
     "npm-publish": "npm publish --tag beta",
     "start:example": "npx --yes serve . -l 5173"

package/test.js

@@ -403,6 +403,56 @@ describe('halfcab', () => {
         .true()
     })
 
+    it('Keeps sub-object references live after overwriting via updateState', (done) => {
+      halfcab({
+        el: '#root',
+        components () {
+          return html `<div></div>`
+        }
+      })
+        .then(({rootEl, state}) => {
+          updateState({
+            user: { name: 'Original Name', age: 25 }
+          })
+
+          nextTick(() => {
+            // Grab a reference to the sub-object proxy
+            const user = state.user
+
+            // Wipe out the user object entirely via a merge
+            updateState({ user: { name: 'New Name', age: 30 } })
+
+            nextTick(() => {
+              // The reference should reflect the new values
+              expect(user.name).to.equal('New Name')
+              expect(user.age).to.equal(30)
+              done()
+            })
+          })
+        })
+    })
+
+    it('Replaces arrays entirely instead of merging them', (done) => {
+      halfcab({
+        el: '#root',
+        components () {
+          return html `<div></div>`
+        }
+      })
+        .then(({rootEl, state}) => {
+          updateState({ list: [1, 2, 3] })
+
+          nextTick(() => {
+            updateState({ list: [4, 5] })
+
+            nextTick(() => {
+              expect(state.list).to.deep.equal([4, 5])
+              done()
+            })
+          })
+        })
+    })
+
     it(`Doesn't clone when merging`, (done) => {
       halfcab({
         el: '#root',