@dinoreic/fez 0.2.0 → 0.3.0

package/README.md

@@ -29,9 +29,7 @@ It replaces modern JS frameworks by using native Autonomous Custom Elements to c
 
 This article, [Web Components Will Replace Your Frontend Framework](https://www.dannymoerkerke.com/blog/web-components-will-replace-your-frontend-framework/), is from 2019. Join the future, ditch React, Angular and other never defined, always "evolving" monstrosities. Vanilla is the way :)
 
-There is no some "internal state" that is by some magic reflected to DOM. No! All methods Fez use to manipulate DOM are just helpers around native DOM interface. Work on DOM raw, use jQuery, use built in [node builder](https://github.com/dux/fez/blob/main/src/lib/n.js) or full template mapping with [morphing](https://github.com/bigskysoftware/idiomorph).
-
-It great in combination with another widely used JS libs, as jQuery, Zepto, underscore of loDash.
+There is no some "internal state" that is by some magic reflected to DOM. No! All methods Fez use to manipulate DOM are just helpers around native DOM interface. Work on DOM raw, use built in [node builder](https://github.com/dux/fez/blob/main/src/lib/n.js) or full template mapping with [morphing](https://github.com/bigskysoftware/idiomorph).
 
 ## How it works
 
@@ -49,25 +47,17 @@ Here's a simple counter component that demonstrates Fez's core features:
 ```html
 <!-- Define a counter component in ex-counter.fez.html -->
 <script>
+  // called when Fez node is connected to DOM
   init() {
-    // called when Fez node is connected to DOM
     this.MAX = 6
     this.state.count = 0
   }
 
-  onStateChange(key, value, oldValue) {
-    // called whenever this.state changes
-    console.log(`State ${key} changed from ${oldValue} to ${value}`)
-    if (key === 'count' && value >= this.MAX) {
-      console.log('Counter reached maximum!')
-    }
-  }
-
   isMax() {
-    // is state is changed, template is re-rendered
     return this.state.count >= this.MAX
   }
 
+  // is state is changed, template is re-rendered
   more() {
     this.state.count += this.isMax() ? 0 : 1
   }
@@ -153,12 +143,13 @@ This example showcases:
 * **Powerful Template Engine** - Multiple syntaxes (`{{ }}` and `[[ ]]`), control flow (`#if`, `#unless`, `#for`, `#each`), and block templates
 * **Reactive State Management** - Built-in reactive `state` object automatically triggers re-renders on property changes
 * **DOM Morphing** - Uses [Idiomorph](https://github.com/bigskysoftware/idiomorph) for intelligent DOM updates that preserve element state and animations
+* **Preserve DOM Elements** - Use `fez-keep="unique-key"` attribute to preserve DOM elements across re-renders (useful for animations, form inputs, or stateful elements)
 * **Style Macros** - Define custom CSS shortcuts like `Fez.styleMacro('mobile', '@media (max-width: 768px)')` and use as `:mobile { ... }`
 * **Scoped & Global Styles** - Components can define both scoped CSS (`:fez { ... }`) and global styles in the same component
 
 ### Developer Experience
 
-* **Built-in Utilities** - Helpful methods like `formData()`, `setInterval()` (auto-cleanup), `onResize()`, and `nextTick()`
+* **Built-in Utilities** - Helpful methods like `formData()`, `setInterval()` (auto-cleanup), `onWindowResize()`, and `nextTick()`
 * **Two-Way Data Binding** - Use `fez-bind` directive for automatic form synchronization
 * **Advanced Slot System** - Full `<slot />` support with event listener preservation
 * **Publish/Subscribe** - Built-in pub/sub system for component communication
@@ -168,8 +159,8 @@ This example showcases:
 
 ### Performance & Integration
 
-* **Fast/Slow Render Modes** - Optimize initial render with `FAST = true` to prevent flickering
-* **Request Animation Frame** - Smart RAF integration for smooth updates
+* **Optimized Rendering** - Batched microtask rendering for flicker-free component initialization
+* **Smart DOM Updates** - Efficient DOM manipulation with minimal reflows
 * **Built-in Fetch with Caching** - `Fez.fetch()` includes automatic response caching and JSON/FormData handling
 * **Global Component Access** - Register components globally with `GLOBAL = 'ComponentName'` for easy access
 * **Rich Lifecycle Hooks** - `init`, `onMount`, `beforeRender`, `afterRender`, `onDestroy`, `onPropsChange`, `onStateChange`, `onGlobalStateChange`
@@ -189,57 +180,9 @@ This example showcases:
 ### Fez Static Methods
 
 ```js
-Fez('#foo')          // find fez node with id="foo"
-Fez('ui-tabs', this) // find first parent node ui-tabs
-
-// add global scss
-Fez.globalCss(`
-  .some-class {
-    color: red;
-    &.foo { ... }
-    .foo { ... }
-  }
-  ...
-`)
-
-// internal, get unique ID for a string, poor mans MD5 / SHA1
-Fez.fnv1('some string')
-
-// get generated css class name, from scss source string
-Fez.css(text)
-
-// get generated css class name without global attachment
-Fez.cssClass(text)
-
-// display information about fast/slow bind components in console
-Fez.info()
-
-// low-level DOM morphing function
-Fez.morphdom(target, newNode, opts)
-
-// HTML escaping utility
-Fez.htmlEscape(text)
-
-// create HTML tags with encoded props
-Fez.tag(tag, opts, html)
-
-// execute function until it returns true
-Fez.untilTrue(func, pingRate)
-
-// add scripts/styles to document head
-// Load JavaScript from URL: Fez.head({ js: 'path/to/script.js' })
-// Load JavaScript with attributes: Fez.head({ js: 'path/to/script.js', type: 'module', async: true })
-// Load JavaScript with callback: Fez.head({ js: 'path/to/script.js' }, () => console.log('loaded'))
-// Load JavaScript module and auto-import to window: Fez.head({ js: 'path/to/module.js', module: 'MyModule' })
-// Load CSS: Fez.head({ css: 'path/to/styles.css' })
-// Load CSS with attributes: Fez.head({ css: 'path/to/styles.css', media: 'print' })
-// Execute inline script: Fez.head({ script: 'console.log("Hello world")' })
-Fez.head(config, callback)
-
-// define custom style macro
-// Fez.styleMacro('mobile', '@media (max-width:  768px)')
-// :mobile { ... } -> @media (max-width:  768px) { ... }
-Fez.styleMacro(name, value)
+Fez('#foo')                  // find fez node with id="foo"
+Fez('ui-tabs', this)         // find first parent node ui-tabs
+Fez('ui-tabs', (fez)=> ... ) // loop over all ui-tabs nodes
 
 // define custom DOM node name -> <foo-bar>...
 Fez('foo-bar', class {
@@ -252,14 +195,6 @@ Fez('foo-bar', class {
   // set element style, set as property or method
   CSS = `scss string... `
 
-  // unless node has no innerHTML on initialization, bind will be set to slow (fastBind = false)
-  // if you are using components that to not use innerHTML and slots, enable fast bind (fastBind = true)
-  // component will be rendered as parsed, and not on next tick (reduces flickering)
-  // <fez-icon name="gear" />
-  FAST = true
-  FAST(node) { ... }
-  // alternative: static fastBind() { return true }
-
   // define static HTML. calling `this.render()` (no arguments) will refresh current node.
   // if you pair it with `reactiveStore()`, to auto update on props change, you will have Svelte or Vue style reactive behaviour.
   HTML = `...`
@@ -269,112 +204,175 @@ Fez('foo-bar', class {
   GLOBAL = 'Dialog'
   GLOBAL = true // just append node to document, do not create window reference
 
-  // use connect or created
-  init(props) {
-    // copy original attributes from attr hash to root node
-    this.copy('href', 'onclick', 'style')
+  // called when fez element is connected to dom, before first render
+  // here you still have your slot available in this.root
+  init(props) { ... }
 
-    // set style property to root node. look at a clock example
-    // shortcut to this.root.style.setProperty(key, value)
-    this.setStyle('--color', 'red')
+  // execute after init and first render
+  onMount() { ... }
 
-    // clasic interval, that runs only while node is attached
-    this.setInterval(func, tick) { ... }
+  // execute before or after every render
+  beforeRender() { ... }
+  afterRender() { ... }
 
-    // get closest form data, as object
-    this.formData()
+  // if you want to monitor new or changed node attributes
+  // monitors all original node attributes
+  // <ui-icon name="home" color="red" />
+  onPropsChange(attrName, attrValue) { ... }
 
-    // mounted DOM node root
-    this.root
+  // called when local component state changes
+  onStateChange(key, value, oldValue) { ... }
 
-    // mounted DOM node root wrapped in $, only if jQuery is available
-    this.$root
+  // called when global state changes (only if component uses key in question that key)
+  onGlobalStateChange(key, value) { ... }
 
-    // node attributes, converted to properties
-    this.props
+  // called when component is destroyed
+  onDestroy() { ... }
 
-    // gets single node attribute or property
-    this.prop('onclick')
+  /* used inside lifecycle methods (init(), onMount(), ... */
 
-    // shortcut for this.root.querySelector(selector)
-    this.find(selector)
+  // copy original attributes from attr hash to root node
+  this.copy('href', 'onclick', 'style')
 
-    // gets value for FORM fields or node innerHTML
-    this.val(selector)
-    // set value to a node, uses value or innerHTML
-    this.val(selector, value)
+  // set style property to root node. look at a clock example
+  // shortcut to this.root.style.setProperty(key, value)
+  this.setStyle('--color', 'red')
 
-    // you can publish globally, and subscribe locally
-    Fez.publish('channel', foo)
-    this.subscribe('channel', (foo) => { ... })
+  // clasic interval, that runs only while node is attached
+  this.setInterval(func, tick) { ... }
 
-    // gets root childNodes
-    this.childNodes()
-    this.childNodes(func)  // pass function to loop forEach on selection, removed nodes from DOM
+  // get closest form data, as object. Searches for first parent or child FORM element
+  this.formData()
 
-    // check if the this.root node is attached to dom
-    this.isConnected()
+  // mounted DOM node root. Only in init() point to original <slot /> data, in onMount() to rendered data.
+  this.root
 
-    // on every "this.state" props change, auto update view.
-    this.state = this.reactiveStore()
-    // this.state has reactiveStore() attached by default. any change will trigger this.render()
-    this.state.foo = 123
+  // mounted DOM node root wrapped in $, only if jQuery is available
+  this.$root
 
-    // generic window event handler with automatic cleanup
-    // eventName: 'resize', 'scroll', 'mousemove', etc.
-    // delay: throttle delay in ms (default: 200ms)
-    // runs immediately on init and then throttled
-    this.on(eventName, func, delay)
+  // node attributes, converted to properties
+  this.props
 
-    // window resize event with cleanup (shorthand for this.on('resize', func, delay))
-    this.onResize(func, delay)
-    
-    // window scroll event with cleanup (shorthand for this.on('scroll', func, delay))
-    this.onScroll(func, delay)
+  // gets single node attribute or property
+  this.prop('onclick')
 
-    // requestAnimationFrame wrapper with deduplication
-    this.nextTick(func, name)
+  // shortcut for this.root.querySelector(selector)
+  this.find(selector)
 
-    // get/set unique ID for root node
-    this.rootId()
+  // gets value for FORM fields or node innerHTML
+  this.val(selector)
+  // set value to a node, uses value or innerHTML
+  this.val(selector, value)
 
-    // get/set attributes on root node
-    this.attr(name, value)
+  // you can publish globally, and subscribe locally
+  Fez.publish('channel', foo)
+  this.subscribe('channel', (foo) => { ... })
 
-    // hide the custom element wrapper and move children to parent
-    this.fezHide()
+  // gets root childNodes
+  this.childNodes()
+  this.childNodes(func)  // pass function to loop forEach on selection, mask nodes out of position
 
-    // execute after connect and initial component render
-    this.onMount() { ... } // or this.connected() { ... }
+  // check if the this.root node is attached to dom
+  this.isConnected
 
-    // execute before or after every render
-    this.beforeRender() { ... }
-    this.afterRender() { ... }
+  // this.state has reactiveStore() attached by default. any change will trigger this.render()
+  this.state.foo = 123
 
-    // if you want to monitor new or changed node attributes
-    // monitors all original node attributes
-    // <ui-icon name="home" color="red" />
-    this.onPropsChange(attrName, attrValue) { ... }
+  // generic window event handler with automatic cleanup
+  // eventName: 'resize', 'scroll', 'mousemove', etc.
+  // delay: throttle delay in ms (default: 200ms)
+  this.on(eventName, func, delay)
 
-    // called when local component state changes
-    this.onStateChange(key, value, oldValue) { ... }
+  // window resize event with cleanup (shorthand for this.on('resize', func, delay))
+  // runs immediately on init and then throttled
+  this.onWindowResize(func, delay)
 
-    // called when global state changes (if component reads that key)
-    this.onGlobalStateChange(key, value) { ... }
+  // window scroll event with cleanup (shorthand for this.on('scroll', func, delay))
+  // runs immediately on init and then throttled
+  this.onWindowScroll(func, delay)
 
-    // called when component is destroyed
-    this.onDestroy() { ... }
+  // requestAnimationFrame wrapper with deduplication
+  this.nextTick(func, name)
 
-    // automatic form submission handling if defined
-    this.onSubmit(formData) { ... }
+  // get unique ID for root node, set one if needed
+  this.rootId()
 
-    // render template and attach result dom to root. uses Idiomorph for DOM morph
-    this.render()
+  // get/set attributes on root node
+  this.attr(name, value)
 
-    // you can render to another root too
-    this.render(this.find('.body'), someHtmlTemplate)
-  }
+  // hide the custom element wrapper and move children to parent
+  this.fezHide()
+
+  // automatic form submission handling if there is FORM as parent or child node
+  this.onSubmit(formData) { ... }
+
+  // render template and attach result dom to root. uses Idiomorph for DOM morph
+  this.render()
+  this.render(this.find('.body'), someHtmlTemplate) // you can render to another root too
 })
+
+/* Utility methods */
+
+// define custom style macro
+// Fez.styleMacro('mobile', '@media (max-width:  768px)')
+// :mobile { ... } -> @media (max-width:  768px) { ... }
+Fez.styleMacro(name, value)
+
+// add global scss
+Fez.globalCss(`
+  .some-class {
+    color: red;
+    &.foo { ... }
+    .foo { ... }
+  }
+  ...
+`)
+
+// internal, get unique ID for a string, poor mans MD5 / SHA1
+Fez.fnv1('some string')
+
+// get dom node containing passed html
+Fez.domRoot(htmlData || htmlNode)
+
+// activates node by adding class to node, and removing it from siblings
+Fez.activateNode(node, className = 'active')
+
+// get generated css class name, from scss source string
+Fez.css(text)
+
+// get generated css class name without global attachment
+Fez.cssClass(text)
+
+// display information about registered components in console
+Fez.info()
+
+// low-level DOM morphing function
+Fez.morphdom(target, newNode, opts)
+
+// HTML escaping utility
+Fez.htmlEscape(text)
+
+// create HTML tags with encoded props
+Fez.tag(tag, opts, html)
+
+// execute function until it returns true
+Fez.untilTrue(func, pingRate)
+
+// resolve and execute a function from string or function reference
+// useful for event handlers that can be either functions or strings
+// Fez.resolveFunction('alert("hi")', element) - creates function and calls with element as this
+// Fez.resolveFunction(myFunc, element) - calls myFunc with element as this
+Fez.resolveFunction(pointer, context)
+
+// add scripts/styles to document head
+// Load JavaScript from URL: Fez.head({ js: 'path/to/script.js' })
+// Load JavaScript with attributes: Fez.head({ js: 'path/to/script.js', type: 'module', async: true })
+// Load JavaScript with callback: Fez.head({ js: 'path/to/script.js' }, () => console.log('loaded'))
+// Load JavaScript module and auto-import to window: Fez.head({ js: 'path/to/module.js', module: 'MyModule' })
+// Load CSS: Fez.head({ css: 'path/to/styles.css' })
+// Load CSS with attributes: Fez.head({ css: 'path/to/styles.css', media: 'print' })
+// Execute inline script: Fez.head({ script: 'console.log("Hello world")' })
+Fez.head(config, callback)
 ```
 
 ## Fez script loading and definition
@@ -395,9 +393,6 @@ Fez('foo-bar', class {
   <!-- pass JSON template via data-json-template -->
   <script type="text/template">{...}</script>
   <foo-bar data-json-template="true"></foo-bar>
-
-  <!-- override slow bind behavior -->
-  <foo-bar fez-fast="true"></foo-bar>
 ```
 
 ## Component structure
@@ -459,7 +454,7 @@ All parts are optional
     {{json data}} <!-- JSON dump in PRE.json tag -->
 
     <!-- fez-this will link DOM node to object property (inspired by Svelte) -->
-    <!-- this.listRoot -->
+    <!-- linkes to -> this.listRoot -->
     <ul fez-this="listRoot">
 
     <!-- when node is added to dom fez-use will call object function by name, and pass current node -->
@@ -468,7 +463,6 @@ All parts are optional
 
     <!-- fez-bind for two-way data binding on form elements -->
     <input type="text" fez-bind="state.username" />
-    <input onkeyup="fez.list[{{ index }}].name = fez.value" value="{{ name }}" />
 
     <!--
       fez-class for adding classes with optional delay.
@@ -476,6 +470,9 @@ All parts are optional
     -->
     <span fez-class="active:100">Delayed class</span>
 
+    <!-- preserve state by key, not affected by state changes-->>
+    <p fez-keep="key">...</p>
+
     <!-- :attribute for evaluated attributes (converts to JSON) -->
     <div :data-config="state.config"></div>
   </div>