@dinoreic/fez 0.1.1 → 0.2.2

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,6 +143,7 @@ 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
 
@@ -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 {
@@ -269,103 +212,169 @@ 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
 
-    // window resize event with cleanup
-    this.onResize(func, delay)
+  // node attributes, converted to properties
+  this.props
 
-    // requestAnimationFrame wrapper with deduplication
-    this.nextTick(func, name)
+  // gets single node attribute or property
+  this.prop('onclick')
 
-    // get/set unique ID for root node
-    this.rootId()
+  // shortcut for this.root.querySelector(selector)
+  this.find(selector)
 
-    // get/set attributes on root node
-    this.attr(name, value)
+  // gets value for FORM fields or node innerHTML
+  this.val(selector)
+  // set value to a node, uses value or innerHTML
+  this.val(selector, value)
 
-    // hide the custom element wrapper and move children to parent
-    this.fezHide()
+  // you can publish globally, and subscribe locally
+  Fez.publish('channel', foo)
+  this.subscribe('channel', (foo) => { ... })
 
-    // execute after connect and initial component render
-    this.onMount() { ... } // or this.connected() { ... }
+  // gets root childNodes
+  this.childNodes()
+  this.childNodes(func)  // pass function to loop forEach on selection, mask nodes out of position
 
-    // execute before or after every render
-    this.beforeRender() { ... }
-    this.afterRender() { ... }
+  // check if the this.root node is attached to dom
+  this.isConnected
 
-    // 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) { ... }
+  // this.state has reactiveStore() attached by default. any change will trigger this.render()
+  this.state.foo = 123
 
-    // called when local component state changes
-    this.onStateChange(key, value, oldValue) { ... }
+  // 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 global state changes (if component reads that key)
-    this.onGlobalStateChange(key, value) { ... }
+  // window resize event with cleanup (shorthand for this.on('resize', func, delay))
+  // runs immediately on init and then throttled
+  this.onResize(func, delay)
 
-    // called when component is destroyed
-    this.onDestroy() { ... }
+  // window scroll event with cleanup (shorthand for this.on('scroll', func, delay))
+  // runs immediately on init and then throttled
+  this.onScroll(func, delay)
 
-    // automatic form submission handling if defined
-    this.onSubmit(formData) { ... }
+  // requestAnimationFrame wrapper with deduplication
+  this.nextTick(func, name)
 
-    // render template and attach result dom to root. uses Idiomorph for DOM morph
-    this.render()
+  // get unique ID for root node, set one if needed
+  this.rootId()
 
-    // you can render to another root too
-    this.render(this.find('.body'), someHtmlTemplate)
-  }
+  // get/set attributes on root node
+  this.attr(name, value)
+
+  // 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 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)
 ```
 
 ## Fez script loading and definition
@@ -443,11 +452,14 @@ All parts are optional
     {{block image}}
       <img src={{ props.src}} />
     {{/block}}
-    {{block:image}}<!-- Use the header block -->
-    {{block:image}}<!-- Use the header block -->
+    {{block:image}} <!-- Use the header block -->
+    {{block:image}} <!-- Use the header block -->
+
+    {{raw data}} <!-- unescape HTML -->
+    {{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 -->
@@ -456,7 +468,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.
@@ -464,6 +475,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>

package/bin/fez

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+
+require 'pathname'
+
+command = ARGV[0]
+args = ARGV[1..-1]
+
+if command.nil? || command == '--help' || command == '-h'
+  puts "Usage: fez <command> [<args>]"
+  puts ""
+  puts "Available commands:"
+  
+  bin_dir = Pathname.new(__FILE__).dirname
+  commands = Dir[bin_dir.join("fez-*")].map do |path|
+    File.basename(path).sub(/^fez-/, '')
+  end.sort
+  
+  commands.each do |cmd|
+    puts "  #{cmd}"
+  end
+  
+  exit 0
+end
+
+subcommand_path = File.join(File.dirname(__FILE__), "fez-#{command}")
+
+if File.exist?(subcommand_path) && File.executable?(subcommand_path)
+  exec(subcommand_path, *args)
+else
+  puts "fez: '#{command}' is not a fez command. See 'fez --help'."
+  exit 1
+end

package/bin/fez-index

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+
+require 'pathname'
+require 'json'
+
+# Check if argument is provided
+if ARGV.empty?
+  puts "Usage: #{$0} <directory>"
+  exit 1
+end
+
+dir = ARGV[0]
+
+# If no * in argument, append /*
+pattern = dir.include?('*') ? dir : File.join(dir, '*')
+
+# Check if base directory exists (for error message)
+base_dir = dir.split('*').first.chomp('/')
+if !base_dir.empty? && !File.directory?(base_dir)
+  puts "Error: Directory '#{base_dir}' does not exist"
+  exit 1
+end
+
+# Get files using glob
+files = Dir.glob(pattern).select { |f| File.file?(f) }
+
+# Create index for each file
+file_index = []
+files.each do |path|
+  stat = File.stat(path)
+
+  file_info = {
+    base: File.basename(path, File.extname(path)),
+    path: path,
+    size: stat.size.to_i,
+    modified: stat.mtime.to_i,
+    created: stat.birthtime.to_i
+  }
+
+  file_index << {file: file_info}
+end
+
+# Output as JSON to screen
+puts JSON.pretty_generate(file_index)