### Fez Test Structure Example

Source: https://github.com/dux/fez/blob/main/test/README.md

A JavaScript code snippet demonstrating how to write a new test for the Fez library, including component setup and state assertion.

```javascript
test('My new test', () => {
  class MyComponent extends FezBase {
    init() {
      this.state.value = 'initial';
    }
  }

  const component = new MyComponent();
  component._node = new window.HTMLElement();
  component.root = component._node;
  component.class = MyComponent;
  component.fezRegister();
  component.init();

  assert(component.state.value === 'initial', 'State should be initialized');
});
```

--------------------------------

### FAST Rendering Configuration in Fez

Source: https://github.com/dux/fez/blob/main/AI_FEZ_GUIDE.md

Provides examples of how to configure `FAST = true` for components that do not use slots, preventing render flicker, and conditional fast rendering based on node attributes.

```javascript
// Always fast (no slots)
class { FAST = true }

// Conditional fast rendering
class { 
  FAST = (node) => node.hasAttribute('title')  // Fast if has title, slow if needs innerHTML
}
```

--------------------------------

### FEZ Fetch API - Basic Usage

Source: https://github.com/dux/fez/blob/main/README.md

Illustrates the basic usage of the Fez.fetch API for making GET and POST requests. It shows how to use promises with async/await for handling responses and callbacks for asynchronous processing, highlighting flexible parameter ordering.

```js
// GET request with promise
const data = await Fez.fetch('https://api.example.com/data')

// GET request with callback, does not create promise
Fez.fetch('https://api.example.com/data', (data) => {
  console.log(data)
})

// POST request
const result = await Fez.fetch('POST', 'https://api.example.com/data', { key: 'value' })
```

--------------------------------

### Create and Use a Fez Counter Component

Source: https://github.com/dux/fez/blob/main/index.html

Demonstrates how to create a custom 'ui-counter' component using Fez and then use it within the HTML body. The component can accept a 'start' attribute to initialize its value.

```html
<script fez="/demo/ui-counter.fez"></script>

<div id="counters">
  <ui-counter></ui-counter>
  <ui-counter start="1"></ui-counter>
  <ui-counter start="2"></ui-counter>
</div>
```

--------------------------------

### Dux Fez Task List Rendering and Controls

Source: https://github.com/dux/fez/blob/main/test/tpl.html

This snippet shows how tasks are rendered in the Dux Fez template. It includes conditional rendering for when no tasks are found, iterating through tasks to display their status and action buttons (complete/remove), and provides buttons for adding a new task and clearing completed tasks. It also displays the raw state of the tasks.

```html
{#if !@state.tasks[0]}

No tasks found

{/if}
{#for task, index in @state.tasks}
  {#if task.animate}

  {else}

  {/if}
  ⋅  ⋅ ×
{/for}

add task ⋅ clear completed

{ JSON.stringify(this.state.tasks, null, 2) }
```

--------------------------------

### Task Management Methods in Dux Fez

Source: https://github.com/dux/fez/blob/main/test/tpl.html

Provides methods for managing tasks within the Dux Fez framework. These methods include toggling task completion, clearing all completed tasks, removing a specific task, updating a task's name, adding a new task with animation, and initializing the task list with predefined tasks.

```javascript
toggleComplete(index) {
  const task = this.state.tasks[index]
  task.done = !task.done
}
clearCompleted() {
  this.state.tasks = this.state.tasks.filter((t) => !t.done)
}
removeTask(index) {
  this.state.tasks = this.state.tasks.filter((_, i) => i !== index);
}
setName(index, name) {
  this.state.tasks[index].name = name
}
addTask() {
  this.counter ||= 0
  this.state.tasks.push({ name: `new task ${++this.counter}`, done: false, animate: true })
}
animate(node) {
  $(node)
    .css('display', 'block')
    .animate({height: '33px', opacity: 1}, 200, () => {
      delete this.state.tasks[this.state.tasks.length - 1].animate
      $(node).css('height', 'auto')
    })
}
init() {
  this.state.tasks = [
    {name: 'First task', done: false},
    {name: 'Second task', done: false},
    {name: 'Third task', done: true},
  ]
}
```

--------------------------------

### Define a Counter Component with FEZ

Source: https://github.com/dux/fez/blob/main/README.md

Example of a custom counter component using FEZ, demonstrating reactive state, event handling, conditional rendering, and scoped SCSS.

```html
<script>
  // called when Fez node is connected to DOM
  init() {
    this.MAX = 6
    this.state.count = 0
  }

  isMax() {
    return this.state.count >= this.MAX
  }

  // is state is changed, template is re-rendered
  more() {
    this.state.count += this.isMax() ? 0 : 1
  }
</script>

<style>
  /* compiles from scss to css and injects class in head */
  /* body style */
  background-color: #f7f7f7;

  /* scoped to this component */
  :fez {
    zoom: 2;
    margin: 10px 0;

    button {
      position: relative;
      top: -3px;
    }

    span {
      padding: 0 5px;
    }
  }
</style>

<button onclick="fez.state.count -= 1" disabled={{ state.count == 1 }}>-</button>

<span>
  {{ state.count }}
</span>

<button onclick="fez.more()" disabled={{ isMax() }}>+</button>
{{if state.count > 0}}
  <span>&mdash;</span>
  {{if state.count == MAX }}
    MAX
  {{else}}
    {{#if state.count % 2 }}
      odd
    {{else}}
      even
    {{/if}}
  {{/if}}
{{/if}}
```

--------------------------------

### Shared Counter Example Using Global State

Source: https://github.com/dux/fez/blob/main/README.md

This example demonstrates how multiple Fez counter components can share and synchronize a global maximum count. Each counter updates the global `maxCount`, ensuring all instances reflect the highest count achieved across all components.

```javascript
// Multiple counter components sharing max count
class Counter extends FezBase {
  init(props) {
    this.state.count = parseInt(props.start || 0)
  }

  beforeRender() {
    // All counters share and update the global max
    this.globalState.maxCount ||= 0

    // Find max across all counter instances
    let max = 0
    Fez.state.forEach('maxCount', fez => {
      if (fez.state?.count > max) {
        max = fez.state.count
      }
    })

    this.globalState.maxCount = max
  }

  render() {
    return `
      <button onclick="fez.state.count++">+</button>
      <span>Count: ${this.state.count}</span>
      <span>(Global max: ${this.globalState.maxCount})</span>
    `
  }
}
```

--------------------------------

### Dynamic Fill Control Example

Source: https://github.com/dux/fez/blob/main/demo/fez/ui-star.html

Illustrates controlling the fill percentage of the star rating component dynamically. This is typically done via JavaScript or data binding.

```html
<fez-star id="myStarRating"></fez-star>
<script>
  // Assuming 'myStarRating' is a reference to the fez-star element
  // Example: Set fill to 50%
  // myStarRating.setFill(0.5);
  // Example: Set rating to 2.5 stars out of 5
  // myStarRating.setRating(2.5);
</script>
```

--------------------------------

### Styling the Star Rating Component

Source: https://github.com/dux/fez/blob/main/demo/fez/ui-star.html

Provides an example of CSS styling for the star rating component, specifically adding margin between stars.

```css
.fez-ui-star {
  margin-right: 5px;
}
```

--------------------------------

### Get First-Level Child Nodes (FEZ Instance Helper)

Source: https://github.com/dux/fez/blob/main/demo/fez/ui-tabs.html

The `this.childNodes()` function is a helper within the FEZ instance designed to retrieve all direct child nodes. It specifically excludes text nodes (#text) from the result set, providing a clean list of element-based children. This is useful for iterating over immediate descendants without needing to filter text nodes manually.

```javascript
this.childNodes()
```

--------------------------------

### Fez Component Structure with ES Module Imports and Dynamic Loading

Source: https://github.com/dux/fez/blob/main/AI_FEZ_GUIDE.md

Demonstrates the basic structure of a Fez component, including optional ES Module imports, dynamic loading of JavaScript and CSS, FAST rendering control, and lifecycle methods like init(), onMount(), onStateChange(), onDestroy(), onWindowResize(), and onWindowScroll().

```html
<xmp fez="component-name">
  <script>
    // ES Module imports (optional)
    import library from 'https://cdn.jsdelivr.net/npm/library/+esm'

    // Or load scripts/styles dynamically
    Fez.head({js: 'https://cdn.example.com/script.js'})
    Fez.head({css: 'https://cdn.example.com/styles.css'})

    // FAST rendering control (optional)
    FAST = true  // Renders immediately (no flicker)
    // OR as a function for conditional behavior
    FAST = (node) => !node.children.length  // Fast only if no children

    init(props) {
      // Props are passed as parameter - use props.name, NOT this.prop('name')
      // do not rewrite state, just add to it
      this.state.count = props.count || 0
      this.state.title = props.title || 'Default'
    }
    onMount(props) {
      // Props also available in onMount - use props.name
      if (props.autoFocus) {
        this.find('input').focus()
      }
    } // DOM-ready logic
    onStateChange(key, value)	// React to state changes
    onDestroy()	// Cleanup resources
    onWindowResize() // on Window resize
    onWindowScroll() // on window scroll
    // Custom methods

    increment() {
      this.state.count++  // Reactive assignment
    }
  </script>

  <style>
    /* Global styles (affects entire page) */
    body {
      background: #f5f5f5;
    }

    /* Component-scoped styles - ALWAYS use nested SCSS syntax */
    :fez {
      /* Direct styles on component root */
      padding: 20px;

      /* Nested elements - this is the PREFERRED pattern */
      button {
        background: gold;
        cursor: pointer;

        /* Deep nesting is encouraged */
        span {
          color: black;
          font-weight: bold;
        }

        &:hover {
          background: orange;
        }
      }

      .card {
        border: 1px solid #ddd;

        .header {
          font-size: 18px;

          h3 {
            margin: 0;
          }
        }
      }
    }
  </style>

  <!-- Template -->
  <button onclick="fez.increment()" name={{ state.buttonName }}>
    Count: {{ state.count }}
  </button>
</xmp>
```

--------------------------------

### Initializing Props in Fez Components (JavaScript)

Source: https://github.com/dux/fez/blob/main/AI_FEZ_GUIDE.md

Shows how to access and utilize props within the `init` method of a Fez component, including setting default values and handling function props.

```javascript
init(props) {
  this.state.font_size = props.font_size || 24
  this.state.background_color = props.background_color || '#000'
  this.state.is_active = props.is_active !== undefined
  // Function props are already resolved
  if (props.onselect) {
    this.onSelectHandler = props.onselect
  }
}
```

--------------------------------

### Importing External Libraries in Fez

Source: https://github.com/dux/fez/blob/main/AI_FEZ_GUIDE.md

Shows how to import ES Modules from CDNs using the `/+esm` path and how to dynamically load external JavaScript and CSS files into the Fez application's head.

```javascript
// ES Module imports (use /+esm for CDN modules)
import library from 'https://cdn.jsdelivr.net/npm/library/+esm'

// Dynamic script/style loading
Fez.head({js: 'https://cdn.example.com/script.js'})
Fez.head({css: 'https://cdn.example.com/styles.css'})
```

--------------------------------

### Fez Event Handling: Component Methods and Child Access

Source: https://github.com/dux/fez/blob/main/AI_FEZ_GUIDE.md

Demonstrates how to handle events in Fez components, including calling component methods directly and accessing methods from child components using the Fez constructor.

```html
<button onclick="fez.handleClick()">    <!-- Component method -->
<div onclick="Fez(this).method()">      <!-- Access from children -->
```

--------------------------------

### Fez: Root Node Attribute Management

Source: https://github.com/dux/fez/blob/main/README.md

Gets or sets attributes on the root node. Allows for dynamic modification of the root element's properties.

```javascript
this.attr(name, value)
```

--------------------------------

### Component Communication with Fez Publish/Subscribe

Source: https://github.com/dux/fez/blob/main/AI_FEZ_GUIDE.md

Demonstrates how to implement inter-component communication in Fez using `subscribe` within a component's `init` method and `publish` for sending data between components.

```javascript
// Subscribe (auto-cleanup)
init() {
  this.subscribe('event', this.handler)
}

// Publish
Fez.publish('event', data)
```

--------------------------------

### Fez Debugging Helpers for Logs and State

Source: https://github.com/dux/fez/blob/main/AI_FEZ_GUIDE.md

Explains how to use Fez's debugging helpers to enable framework logs, inspect component state directly, and check global state using Fez utilities.

```javascript
Fez.LOG = true             // Enable framework logs
Fez('component').state     // Inspect component state
Fez.state.get('key')       // Check global state
```

--------------------------------

### Fez: DOM Node Retrieval from HTML

Source: https://github.com/dux/fez/blob/main/README.md

Gets the DOM node containing the passed HTML data or an existing HTML node. Useful for parsing and manipulating HTML fragments.

```javascript
Fez.domRoot(htmlData || htmlNode)
```

--------------------------------

### Fez State Management: Local and Global

Source: https://github.com/dux/fez/blob/main/AI_FEZ_GUIDE.md

Illustrates how to manage local and global state within the Fez framework. Local state updates trigger re-renders, while global state changes are automatically published.

```javascript
// Local state
this.state.value = "reactive"  // Triggers re-render

// Global state
this.globalState.theme = "dark"  // Auto-publishes changes
```

--------------------------------

### Running Fez Tests

Source: https://github.com/dux/fez/blob/main/test/README.md

Commands to execute the test suite for the Fez reactive library using either bun or npm.

```bash
bun run test
```

```bash
npm run test
```

--------------------------------

### Fez Component File Structure

Source: https://github.com/dux/fez/blob/main/AI_COMPONENT_GUIDE.md

Fez components should be written in .fez files and accompanied by an HTML demo in the same directory. The HTML demo should contain an info block with features and usage data, but no styles or HTML wrapper.

```filename
/dux/fez/[name].fez
```

```filename
/demo/fez/[name].html
```

```html
<div class="info">
  <ul>
    <li>features ... <code>...</code></li>
  </ul>
</div>
<h4>Section info</h4>
<div>more example data</div>
```

--------------------------------

### Fez Template Directives: Interpolation, Conditionals, Loops, and Raw HTML

Source: https://github.com/dux/fez/blob/main/AI_FEZ_GUIDE.md

Covers Fez template directives for displaying data (interpolation), controlling rendering based on conditions (conditionals), iterating over data (loops), and rendering raw HTML content.

```html
<!-- Interpolation -->
<p>{{ state.user.name }}</p>

<!-- Conditionals -->
{{if state.isActive}}<div>Active</div>{{else}}<div>Inactive</div>{{/if}}

<!-- IMPORTANT: NEVER use {{if}} inside attributes! Use ternary operator instead -->
<!-- ❌ WRONG: <div class="{{if state.active}}active{{/if}}"> -->
<!-- ✅ CORRECT: <div class={{ state.active ? 'active' : '' }}> -->

<!-- For attributes, ALWAYS use ternary operators -->
<!-- No quotes needed around {{ }} expressions in attributes -->
<button disabled={{ state.loading ? 'disabled' : '' }}>Submit</button>
<div class={{ state.error ? 'error' : 'success' }}>Status</div>
<input value={{ state.name || 'default' }}>
<span title={{ state.tooltip }}>Hover me</span>

<!-- Loops -->
{{for item in state.items}}
  <li>{{ item.name }}</li>
{{/for}}

<!-- Raw HTML -->
<div>{{raw state.htmlContent}}</div>
```

--------------------------------

### Dux Fez Component: Pre-render Preparation

Source: https://github.com/dux/fez/blob/main/demo/fez/ui-slider.html

Illustrates the `this.beforeRender()` lifecycle method for preparing variables prior to rendering, offering a clean alternative to Svelte's `$: {...}` reactive declarations.

```javascript
this.beforeRender(() => {
  // Prepare variables here
});
```

--------------------------------

### Fez Utility Shortcuts for DOM and Fetch

Source: https://github.com/dux/fez/blob/main/AI_FEZ_GUIDE.md

Highlights useful utility shortcuts provided by Fez for DOM manipulation, timeouts, fetching data, form data retrieval, and resolving function references from strings or functions.

```javascript
this.find('.selector')      // Scoped querySelector
this.setTimeout(fn, 1000)  // Auto-cleaned timeout
Fez.fetch('/data')          // Built-in cached fetch
this.formData()             // Get form values

// Resolve a function from a string or function reference
Fez.getFunction(this.props.onclick)
Fez.getFunction('alert("Hi")', window)

// to check if value is true, that comes from props
Fez.isTrue(value)
```

--------------------------------

### Scoped SCSS Styling in Fez Components

Source: https://github.com/dux/fez/blob/main/AI_FEZ_GUIDE.md

Illustrates how to use nested SCSS syntax and the `:fez` selector for scoped component styles to prevent global CSS conflicts and leverage nesting for element hierarchies.

```scss
:fez {
  .container {
    padding: 20px;

    .header {
      font-size: 24px;

      h1 {
        margin: 0;
        color: #333;
      }
    }

    button {
      &:hover { background: #f0f0f0; }
      &.active { background: #007bff; }
    }
  }
}
```

--------------------------------

### Passing Props in HTML with Fez

Source: https://github.com/dux/fez/blob/main/AI_FEZ_GUIDE.md

Demonstrates how to pass evaluated values (functions, objects, booleans) and string values as props to Fez components using colon prefixes for evaluated attributes.

```html
<!-- Passing evaluated values (functions, objects, etc.) -->
<my-component :onclick="handleClick" :config="{theme: 'dark'}" :is_active="true">

<!-- Passing string values (no colon needed) -->
<my-component title="Hello" class_name="primary">

```

--------------------------------

### Fez Component Creation and Subscription

Source: https://github.com/dux/fez/blob/main/demo/fez/ui-pub-sub.html

Demonstrates the creation of a Fez component named 'ui-pubsub' which subscribes to 'ping' events and updates its target element's inner HTML with the received data. It also includes a mechanism to publish random data to the 'ping' topic at regular intervals.

```javascript
add listener Fez('ui-pubsub', class { update (info) { this.target.innerHTML = info } init() { this.target = this.find('.target') this.subscribe('ping', this.update) this.update('waiting for a ping...') } })
setInterval(()=>Fez.publish('ping', Math.random()), 1000)
```

--------------------------------

### FEZ Custom Node Initialization and Usage

Source: https://github.com/dux/fez/blob/main/README.md

Shows how to initialize and globally expose a custom FEZ component, allowing it to be controlled from anywhere in the application. It also demonstrates how to select and interact with FEZ nodes using selectors.

```html
<ui-dialog id="main-dialog"></ui-dialog>
```

```js
Fez('ui-dialog', class {
  init() {
    // makes dialog globally available
    window.Dialog = this
  }

  close() {
    ...
  }
})

// close dialog window, from anywhere
Dialog.close()

// you can load via Fez + node selector
Fez('#main-dialog').close()
```

--------------------------------

### Use a FEZ Component in HTML

Source: https://github.com/dux/fez/blob/main/README.md

Demonstrates how to load a FEZ component using the template tag and then instantiate it in your HTML.

```html
<!-- Load Fez library -->
<script src="https://dux.github.io/fez/dist/fez.js"></script>

<!-- Load component via template tag -->
<template fez="/fez-libs/ex-counter.fez.html"></template>

<!-- Use the component -->
<ex-counter></ex-counter>
```

--------------------------------

### React List Rendering with useRef and forwardRef

Source: https://github.com/dux/fez/blob/main/benchmark.html

Demonstrates how to render a list using React's `forwardRef` and `createRef` to imperatively update the list items. It measures the time taken for DOM updates.

```javascript
const reactRoot = ReactDOM.createRoot(reactMount);
const ListWithRef = React.forwardRef((props, ref) => {
  const [items, setItems] = React.useState([]);
  React.useImperativeHandle(ref, () => ({
    setItems: (newItems) => setItems(newItems)
  }), []);
  return React.createElement('div', null, items.map((item, i) => React.createElement('span', { key: i }, item)) );
});
const reactRef = React.createRef();
reactRoot.render(React.createElement(ListWithRef, { ref: reactRef }));
```

--------------------------------

### Include Fez and a Custom Component in HTML

Source: https://github.com/dux/fez/blob/main/index.html

Demonstrates how to integrate the Fez framework and a custom Fez component (ui-time) into an HTML page. It uses script tags to load the Fez library and the component definition.

```html
<html>
<head>
  <title>Time</title>
  <script script="https://dux.github.io/fez/dist/fez.js"></script>
  <script script="/fez/ui-time.fez"></script>
</head>
<body>
  <ui-time city="My place"></ui-time>
<body>
</html>
```

--------------------------------

### Fez Special Attributes: Binding, References, Hooks, and Evaluated Attributes

Source: https://github.com/dux/fez/blob/main/AI_FEZ_GUIDE.md

Explains Fez's special attributes like `fez-bind` for two-way data binding, `fez-this` for element references, `fez-use` for DOM hooks, and the use of the colon prefix for evaluated attributes (functions, objects, etc.) in templates.

```html
<input fez-bind="state.username">      <!-- Two-way binding -->
<div fez-this="myElement">             <!-- Element reference -->
<input fez-use="el => el.foucs()">     <!-- DOM hook -->

<!-- IMPORTANT: Use colon prefix for evaluated attributes (functions, objects, etc.) -->
<ui-emoji :onselect="handleEmojiSelect">   <!-- Pass function reference -->
<my-component :config="{foo: 'bar'}">      <!-- Pass object literal -->
<user-card :user="state.currentUser">      <!-- Pass state object -->
<toggle :checked="state.isActive">         <!-- Pass boolean -->

<!-- Without colon, values are treated as strings -->
<my-component title="Hello World">         <!-- String value (no colon needed) -->
```

--------------------------------

### Dux Fez Component: Window Resize Handling

Source: https://github.com/dux/fez/blob/main/demo/fez/ui-slider.html

Shows how to use `this.onWindowResize()` to execute code when the window is resized. This listener is automatically cleared when the component's node is removed.

```javascript
this.onWindowResize(() => {
  // Execute code on window resize
});
```

--------------------------------

### FEZ Component Structure - HTML Template Syntax

Source: https://github.com/dux/fez/blob/main/README.md

Demonstrates the structure of a FEZ component, including how to include elements in the document head, define component logic with scripts, apply global and local styles, and use various templating directives for conditional rendering, loops, blocks, and data binding.

```html
<xmp tag="some-tag">
  <head>
    <!-- everything in head will be copied to document head-->
    <script>console.log('Added to document head, first script to execute.')</script>
  </head>

  <script>
    class {
      init(props) { ... }     // when fez node is initialized, before template render
      onMount(props) { ... }  // called after first template render
    }
  </script>
  <script> // class can be omitted if only functions are passed
    init(props) { ... }
  </script>

  <style>
    b {
      color: red; /* will be global style*/
    }

    :fez {
      /* component styles */
    }
  </style>
  <style>
    color: red; /* if "body {" or ":fez {" is not found, style is considered local component style */
  </style>

  <div> ... <!-- any other html after head, script or style is considered template-->
    <!-- resolve any condition -->
    {{if foo}} ... {{/if}}

    <!-- unless directive - opposite of if -->
    {{unless fez.list.length}}
      <p>No items to display</p>
    {{/unless}}

    <!-- runs in node scope, you can use for loop -->
    {{each fez.list as name, index}} ... {{/each}}
    {{for name, index in fez.list}} ... {{/for}}

    <!-- Block definitions -->
    {{block image}}
      <img src={{ props.src}} />
    {{/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) -->
    <!-- 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 -->
    <!-- this.animate(node) -->
    <li fez-use="animate">

    <!-- fez-bind for two-way data binding on form elements -->
    <input type="text" fez-bind="state.username" />

    <!--
      fez-class for adding classes with optional delay.
      class will be added to SPAN element, 100ms after dom mount (to trigger animations)
    -->
    <span fez-class="active:100">Delayed class</span>

    <!-- preserve state by key, not affected by state changes-->>
    <p fez-keep="key">...</p>

    <!-- memoize DOM content by key (component-scoped) -->
    <!-- stores DOM on first render, restores on subsequent renders with same key -->
    <div fez-memoize="unique-key">expensive content</div>

    <!-- :attribute for evaluated attributes (converts to JSON) -->
    <div :data-config="state.config"></div>
  </div>
</xmp>
```

--------------------------------

### Dynamic Component Loading with `<template>`

Source: https://github.com/dux/fez/blob/main/README.md

Fez supports loading component templates from external URLs using the `<template fez='path/to/component.html'>` tag.

```html
<template fez="components/header.html"></template>
```

--------------------------------

### Fez: Dynamic Property Binding

Source: https://github.com/dux/fez/blob/main/README.md

Allows for dynamic property binding in Fez components using the `:` prefix, enabling live updates based on JavaScript expressions evaluated before node mounting.

```html
<foo-bar :size="document.getElementById('icon-range').value"></foo-bar>
```

--------------------------------

### Creating Custom Fez Nodes

Source: https://github.com/dux/fez/blob/main/README.md

Demonstrates how to define and use custom Fez nodes, making them globally accessible or selectable via CSS selectors.

```APIDOC
## Custom Fez Nodes

Custom Fez nodes can be defined globally and interacted with from anywhere in the application.

### Defining a Custom Node

Use `Fez(selector, classDefinition)` to define a custom component.

```html
<!-- HTML Structure -->
<ui-dialog id="main-dialog"></ui-dialog>
```

```js
// JavaScript Definition
Fez('ui-dialog', class {
  init() {
    // Makes the dialog controller globally available
    window.Dialog = this;
  }

  close() {
    // Implementation for closing the dialog
    ...
  }
});
```

### Interacting with Custom Nodes

Custom nodes can be controlled globally or by selecting them directly.

```js
// Calling globally exposed method
Dialog.close();

// Selecting and calling method via Fez
Fez('#main-dialog').close();
```
```

--------------------------------

### Load Fez JS Library

Source: https://github.com/dux/fez/blob/main/index.html

Includes the Fez JavaScript library into your HTML document. This is a prerequisite for using Fez components.

```html
<script src="https://dux.github.io/fez/dist/fez.js"></script>
```

--------------------------------

### Dux Fez Component: Node Finding

Source: https://github.com/dux/fez/blob/main/demo/fez/ui-slider.html

Demonstrates the `this.find()` method for locating nodes within a component's template, serving as a shortcut for `this.root.querySelector()`.

```javascript
this.find('selector');
```

--------------------------------

### Fez Publish/Subscribe System

Source: https://github.com/dux/fez/blob/main/README.md

Illustrates the Publish/Subscribe system in Fez, covering component-level and global-level messaging, subscription management, and manual unsubscription.

```javascript
// Publish/Subscribe system
// Component-level: publishes bubble up to parent components until a subscriber is found
this.publish('channel', data)          // publish from component, bubbles up to parents
this.subscribe('channel', (data) => {}) // subscribe in component

// Global-level: publish to all subscribers (components and global listeners)
Fez.publish('channel', data)            // publish globally

// Global subscribe: runs only if node is connected to DOM
// Automatically removes subscription when node is disconnected
Fez.subscribe(node, 'channel', callback)     // subscribe specific node
Fez.subscribe('#myId', 'channel', callback)  // subscribe by selector
Fez.subscribe('channel', callback)           // subscribe to document.body

// Manual unsubscribe (automatic cleanup happens when node disconnects)
const unsub = Fez.subscribe('channel', callback)
unsub() // manually remove subscription
```

--------------------------------

### Fez Component Structure and Directives

Source: https://github.com/dux/fez/blob/main/README.md

Details the structure of a Fez component, including script, style, and template sections, and explains various directives like {{if}}, {{each}}, {{block}}, fez-this, fez-use, fez-bind, fez-class, fez-keep, fez-memoize, and :attribute.

```APIDOC
## Component Structure

Fez components are structured with optional `head`, `script`, and `style` sections, followed by the main template.

### Head Elements

Supports inline `<head>` elements within XML tags, which are copied to the document's head.

```html
<xmp tag="some-tag">
  <head>
    <script>console.log('Added to document head, first script to execute.')</script>
  </head>
  ...
</xmp>
```

### Script Section

Can define a class with `init` and `onMount` methods, or just functions. The `init` method is called when the Fez node is initialized, and `onMount` is called after the first template render.

```html
<script>
  class {
    init(props) { ... }     // called before template render
    onMount(props) { ... }  // called after first template render
  }
</script>
<script>
  // class can be omitted if only functions are passed
  init(props) { ... }
</script>
```

### Style Section

Styles can be global (if matching `body` or `:fez`) or local component styles.

```html
<style>
  b { color: red; } /* global style */
  :fez { /* component styles */ }
</style>
<style>
  color: red; /* local component style if no :fez or body selector found */
</style>
```

### Template Syntax

Fez supports conditional rendering, loops, blocks, raw HTML output, and JSON dumping.

- **Conditionals**: `{{if condition}} ... {{/if}}`, `{{unless condition}} ... {{/unless}}`
- **Loops**: `{{each fez.list as name, index}} ... {{/each}}`, `{{for name, index in fez.list}} ... {{/for}}`
- **Blocks**: `{{block name}} ... {{/block}}`, `{{block:name}} ... {{/block:name}}`
- **Raw/JSON**: `{{raw data}}`, `{{json data}}`

### Directives

- **`fez-this="propertyName"`**: Links a DOM node to an object property.
- **`fez-use="functionName"`**: Calls an object function when the node is added to the DOM.
- **`fez-bind="state.propertyName"`**: Enables two-way data binding on form elements.
- **`fez-class="className:delay"`**: Adds a class to an element with an optional delay.
- **`fez-keep="key"`**: Preserves the state of a DOM element by a key.
- **`fez-memoize="key"`**: Memoizes DOM content by a key for performance.
- **`:attribute="expression"`**: Evaluates an attribute expression and sets the attribute (converts to JSON).
```

--------------------------------

### Combined Margin and Padding

Source: https://github.com/dux/fez/blob/main/demo/fez/css-base.html

Shows how to combine margin and padding utility classes for complex spacing. Supports desktop-specific overrides.

```CSS
.m-2.desktop-p-3 { margin: 8px; } @media (min-width: 1024px) { .desktop-p-3 { padding: 12px; } }
.mx-5 { margin-left: 20px; margin-right: 20px; }
.py-3 { padding-top: 12px; padding-bottom: 12px; }
```

--------------------------------

### CSS: Styling for Content Box and Demo Section

Source: https://github.com/dux/fez/blob/main/demo/fez/ui-auto-height.html

This CSS defines the visual appearance of the demo section and the content box, including margins, padding, background colors, borders, and shadows.

```css
.demo-section { margin-bottom: 30px; padding: 20px; background: #f5f5f5; border-radius: 8px; }
.content-box { background: white; padding: 20px; border-radius: 6px; border: 2px solid #ccc; box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
.button-group { margin-bottom: 15px; display: flex; gap: 10px; }
```

--------------------------------

### Publish/Subscribe System

Source: https://github.com/dux/fez/blob/main/README.md

Fez includes a built-in publish/subscribe system for efficient component communication.

```javascript
class Publisher extends Fez {
  publishEvent() {
    Fez.pubsub.publish('my-event', { message: 'Hello from Publisher!' });
  }
}

class Subscriber extends Fez {
  onMount() {
    this.subscription = Fez.pubsub.subscribe('my-event', (data) => {
      console.log('Received:', data);
    });
  }
  onDestroy() {
    this.subscription.unsubscribe();
  }
}

Fez.define('publisher-comp', Publisher);
Fez.define('subscriber-comp', Subscriber);
```

--------------------------------

### Event Listeners for Benchmark Controls

Source: https://github.com/dux/fez/blob/main/benchmark.html

Sets up event listeners for buttons to clear results, run all benchmarks, or run individual benchmarks (mount/unmount, state update, list rendering).

```javascript
document.getElementById('clearBtn').addEventListener('click', () => { document.getElementById('results-mount').innerHTML = ''; updateStatus('Results cleared'); });
document.getElementById('runAllBtn').addEventListener('click', async () => {
    updateStatus('Running all benchmarks...');
    benchmark.results = [];
    await runMountUnmountBenchmark();
    await new Promise(resolve => setTimeout(resolve, 500));
    await runStateUpdateBenchmark();
    await new Promise(resolve => setTimeout(resolve, 500));
    await runListRenderingBenchmark();
    updateStatus('All benchmarks complete!');
});
document.getElementById('mountBtn').addEventListener('click', runMountUnmountBenchmark);
document.getElementById('updateBtn').addEventListener('click', runStateUpdateBenchmark);
document.getElementById('listBtn').addEventListener('click', runListRenderingBenchmark);
```

--------------------------------

### Fez Component Lifecycle Methods

Source: https://github.com/dux/fez/blob/main/README.md

Details the various lifecycle methods available within a Fez component, including initialization, mounting, rendering, attribute changes, state changes, and destruction.

```javascript
// called when fez element is connected to dom, before first render
// here you still have your slot available in this.root
init(props) { ... }

// execute after init and first render
onMount() { ... }

// execute before or after every render
beforeRender() { ... }
afterRender() { ... }

// if you want to monitor new or changed node attributes
// monitors all original node attributes
// <ui-icon name="home" color="red" />
onPropsChange(attrName, attrValue) { ... }

// called when local component state changes
onStateChange(key, value, oldValue) { ... }

// called when global state changes (only if component uses key in question that key)
onGlobalStateChange(key, value) { ... }

// called when component is destroyed
onDestroy() { ... }
```

--------------------------------

### Fez Custom Component Definition

Source: https://github.com/dux/fez/blob/main/README.md

Shows how to define a custom Fez component, including setting the element's node name, CSS styles, HTML content, rendering behavior, and global accessibility.

```javascript
// define custom DOM node name -> <foo-bar>...
Fez('foo-bar', class {
  // set element node name, set as property or method, defaults to DIV
  // why? because Fez renames custom dom nodes to regular HTML nodes
  NAME = 'span'
  NAME(node) { ... }
  // alternative: static nodeName = 'span'

  // set element style, set as property or method
  CSS = `scss string... `

  // 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 = `...`

  // Control rendering timing to prevent flicker (property or method)
  // If true: renders immediately in main loop (no flicker)
  // If false/undefined: renders in next animation frame (may flicker with nested non-fast elements)
  // Components that don't accept slots or work without slots should set FAST = true
  FAST = true
  FAST = (node) => node.hasAttribute('title') // Function: e.g., ui-btn renders fast if has title attribute

  // Make it globally accessible as `window.Dialog`
  // The component is automatically appended to the document body as a singleton. See `demo/fez/ui-dialog.fez` for a complete example.
  GLOBAL = 'Dialog'
  GLOBAL = true // just append node to document, do not create window reference
})
```

--------------------------------

### Default Fez Components

Source: https://github.com/dux/fez/blob/main/README.md

Lists and describes the default components provided by Fez.js, including `fez-component`, `fez-include`, and `fez-inline`.

```APIDOC
## Default Components

Fez includes several pre-built components available when `defaults.js` is included.

### `fez-component`

Dynamically includes another Fez component by name.

```html
<fez-component name="some-node" :props="fez.props"></fez-component>
```

### `fez-include`

Loads remote HTML content from a specified URL.

```html
<fez-include src="./demo/fez/ui-slider.html"></fez-include>
```

### `fez-inline`

Creates inline components with their own reactive state.

```html
<fez-inline :state="{count: 0}">
  <button onclick="fez.state.count += 1">+</button>
  {{ state.count }} * {{ state.count }} = {{ state.count * state.count }}
</fez-inline>
```
```

--------------------------------

### Global State Management

Source: https://github.com/dux/fez/blob/main/README.md

Fez offers automatic subscription-based global state management via a proxy object.

```javascript
class GlobalStateDisplay extends Fez {
  static template = /* html */`
    <div>Global Count: ${this.globalState.count}</div>
  `;

  onGlobalStateChange(newState) {
    this.render();
  }
}

Fez.define('global-display', GlobalStateDisplay);

// To update global state (e.g., in another component or globally):
// Fez.globalState.count = (Fez.globalState.count || 0) + 1;
```

--------------------------------

### Fez Component Definition

Source: https://github.com/dux/fez/blob/main/benchmark.html

Defines a Fez counter component with state and an increment method. It uses a template literal for HTML and initializes state in the `init` method.

```javascript
Fez('fez-counter', class { 
    HTML = `<div>Count: {{ state.count }}</div>` 
    init() { 
        this.state.count = 0 
    }
    increment() { 
        this.state.count++; 
    }
});
```