@jinntec/fore 3.1.1 → 3.2.0

package/dist/fore-dev.js

@@ -1,4 +1,4 @@
-/* Version: 3.1.1 - May 20, 2026 17:16:48 */
+/* Version: 3.2.0 - June 9, 2026 10:50:39 */
 function t$2(t, s, r, i) {
   const n = {
     op: s,
@@ -20124,7 +20124,7 @@ class Fore {
     return Fore.ACTION_ELEMENTS.includes(elementName);
   }
   static get UI_ELEMENTS() {
-    return new Set(['FX-ALERT', 'FX-CONTROL', 'FX-DIALOG', 'FX-FILENAME', 'FX-MEDIATYPE', 'FX-GROUP', 'FX-HINT', 'FX-ITEMS', 'FX-OUTPUT', 'FX-RANGE', 'FX-REPEAT', 'FX-REPEATITEM', 'FX-REPEAT-ATTRIBUTES', 'FX-SWITCH', 'FX-SECRET', 'FX-SELECT', 'FX-SUBMIT', 'FX-TEXTAREA', 'FX-TRIGGER', 'FX-UPLOAD', 'FX-VAR']);
+    return new Set(['FX-ALERT', 'FX-CONTROL', 'FX-DIALOG', 'FX-FILENAME', 'FX-MEDIATYPE', 'FX-GROUP', 'FX-HINT', 'FX-ITEMS', 'FX-INCLUDE', 'FX-OUTPUT', 'FX-RANGE', 'FX-REPEAT', 'FX-REPEATITEM', 'FX-REPEAT-ATTRIBUTES', 'FX-SWITCH', 'FX-SECRET', 'FX-SELECT', 'FX-SUBMIT', 'FX-TEXTAREA', 'FX-TRIGGER', 'FX-UPLOAD', 'FX-VAR']);
   }
 
   /**
@@ -21574,10 +21574,8 @@ class FxModel extends HTMLElement {
     const instance = model.getInstance(instanceId);
     const fore = model.formElement;
     if (fore?.createNodes && (node === null || node === undefined)) {
-      const mi = new ModelItem(undefined, ref, null, null, instanceId, fore);
-      mi.isSynthetic = true;
-      model.registerModelItem(mi);
-      return mi;
+      // Do not create the model item. It may be exchanged later when create-nodes actually made the node
+      return null;
     }
     if (node === null || node === undefined) return null;
     let targetNode = Array.isArray(node) ? node[0] : node;
@@ -25481,7 +25479,7 @@ class FxFore extends HTMLElement {
       this._createRepeatsFromAttributes();
       this.inited = true;
     };
-    this.version = 'Version: 3.1.1 - built on May 20, 2026 17:16:48';
+    this.version = 'Version: 3.2.0 - built on June 9, 2026 10:50:39';
 
     /**
      * @type {import('./fx-model.js').FxModel}
@@ -26931,7 +26929,7 @@ class FxFore extends HTMLElement {
         bound.evalInContext();
         if (bound.nodeName !== 'FX-REPEAT') {
           // Do not try to get a bind for a nodeSET of a repeat. there are multiple.
-          bound.getModelItem().bind?.evalInContext();
+          bound.getModelItem()?.bind?.evalInContext();
         }
         continue;
       }
@@ -26980,7 +26978,7 @@ class FxFore extends HTMLElement {
         }
       }
       bound.evalInContext();
-      bound.getModelItem().bind?.evalInContext();
+      bound.getModelItem()?.bind?.evalInContext();
       if (!isResolvedBound(bound)) {
         console.warn('create-nodes: could not resolve bound after node creation, skipping', bound);
         continue;
@@ -27114,6 +27112,11 @@ class FxFore extends HTMLElement {
         continue;
       }
       const parsed = parseName(token);
+      if (!isValidName(parsed.localName)) {
+        // This did not result in a valid name. Stop.
+        console.warn(`Creating node for the XPath ${xpath} failed because the part ${parsed.localName} is not a valid Name.`);
+        return;
+      }
       if (parsed.isAttribute) {
         if (!current) {
           const attr = ownerDoc.createAttribute(parsed.localName);
@@ -27122,11 +27125,6 @@ class FxFore extends HTMLElement {
         current.setAttribute(parsed.localName, '');
         continue;
       }
-      if (!isValidName(parsed.localName)) {
-        // This did not result in a valid name. Stop.
-        console.warn(`Creating node for the XPath ${xpath} failed because the part ${parsed.localName} is not a valid Name.`);
-        return;
-      }
       const element = parsed.namespaceURI ? ownerDoc.createElementNS(parsed.namespaceURI, parsed.localName) : ownerDoc.createElement(parsed.localName);
       for (const predicate of predicates) {
         const attrName = predicate.name.includes(':') ? predicate.name.split(':')[1] : predicate.name;
@@ -29637,6 +29635,211 @@ if (!customElements.get('fx-hint')) {
   customElements.define('fx-hint', FxHint);
 }
 
+/**
+ * <fx-include>
+ *
+ * Lazy light-DOM include component.
+ *
+ * Loads markup either from:
+ *   - a direct child <template>
+ *   - an external HTML document via @src
+ *
+ * Default behavior:
+ *   - listens for an event
+ *   - includes content once
+ *   - removes the event listener afterwards
+ *
+ * With @reload:
+ *   - listens repeatedly
+ *   - clears previously included content
+ *   - includes fresh content again
+ *
+ * Attributes:
+ *   event      Event name to listen for. Defaults to "click".
+ *   target     CSS selector for the event target. Defaults to "self".
+ *              Special values: self, document, window.
+ *   src        Optional external HTML source.
+ *   selector   Optional selector inside external HTML.
+ *   replace    Replace <fx-include> with the included content.
+ *   immediate  Include immediately when connected.
+ *   reload     Re-include on every matching event.
+ */
+class FxInclude extends HTMLElement {
+  constructor() {
+    super();
+    this._listener = this._handleEvent.bind(this);
+    this._eventTarget = null;
+    this._loaded = false;
+    this._replaced = false;
+  }
+  connectedCallback() {
+    this.eventName = this.getAttribute('event') || 'click';
+    this.targetSelector = this.getAttribute('target') || 'self';
+    this.src = this.getAttribute('src');
+    this.selector = this.getAttribute('selector');
+    this.replace = this.hasAttribute('replace');
+    this.immediate = this.hasAttribute('immediate');
+    this.reload = this.hasAttribute('reload');
+    if (this.immediate) {
+      queueMicrotask(() => this.include());
+      return;
+    }
+    this._bindListener();
+  }
+  disconnectedCallback() {
+    this._unbindListener();
+  }
+  _bindListener() {
+    const target = this._resolveEventTarget();
+    if (!target) {
+      this._dispatchError(`fx-include: event target not found: '${this.targetSelector}'`);
+      return;
+    }
+    target.addEventListener(this.eventName, this._listener);
+    this._eventTarget = target;
+  }
+  _unbindListener() {
+    if (this._eventTarget && this._listener) {
+      this._eventTarget.removeEventListener(this.eventName, this._listener);
+    }
+    this._eventTarget = null;
+  }
+  _resolveEventTarget() {
+    if (!this.targetSelector || this.targetSelector === 'self') {
+      return this;
+    }
+    if (this.targetSelector === 'document') {
+      return document;
+    }
+    if (this.targetSelector === 'window') {
+      return window;
+    }
+    const fore = this.closest('fx-fore');
+    return fore?.querySelector(this.targetSelector) || document.querySelector(this.targetSelector);
+  }
+  async _handleEvent(event) {
+    await this.include(event);
+  }
+  async include(triggerEvent = null) {
+    if (this._replaced) {
+      return;
+    }
+    if (this._loaded && !this.reload) {
+      return;
+    }
+    const fragment = this.src ? await this._loadExternalFragment() : this._loadTemplateFragment();
+    if (!fragment) {
+      return;
+    }
+    if (this.replace) {
+      await this._replaceSelf(fragment, triggerEvent);
+      return;
+    }
+    this._clearIncludedContent();
+    const wrapper = document.createElement('span');
+    wrapper.setAttribute('data-fx-include-content', '');
+    wrapper.style.display = 'contents';
+    wrapper.appendChild(fragment);
+    this.appendChild(wrapper);
+    this._loaded = true;
+    await this._initializeInsertedContent(wrapper);
+    await Fore.dispatch(this, 'include-done', {
+      src: this.src || null,
+      included: wrapper,
+      replaced: false,
+      triggerEvent
+    });
+    if (!this.reload) {
+      this._unbindListener();
+    }
+  }
+  _loadTemplateFragment() {
+    const template = this.querySelector(':scope > template');
+    if (!template) {
+      this._dispatchError('fx-include: no src and no direct template child found');
+      return null;
+    }
+    return template.content.cloneNode(true);
+  }
+  async _loadExternalFragment() {
+    const html = await Fore.loadHtml(this.src);
+    if (!html) {
+      this._dispatchError(`fx-include: failed to load '${this.src}'`);
+      return null;
+    }
+    const parsed = new DOMParser().parseFromString(html, 'text/html');
+    if (this.selector) {
+      const selected = parsed.querySelector(this.selector);
+      if (!selected) {
+        this._dispatchError(`fx-include: selector '${this.selector}' not found in '${this.src}'`);
+        return null;
+      }
+      const fragment = document.createDocumentFragment();
+      fragment.appendChild(document.importNode(selected, true));
+      return fragment;
+    }
+    const template = parsed.querySelector('template');
+    if (template) {
+      return document.importNode(template.content, true);
+    }
+    const fragment = document.createDocumentFragment();
+    Array.from(parsed.body.childNodes).forEach(node => {
+      fragment.appendChild(document.importNode(node, true));
+    });
+    return fragment;
+  }
+  async _replaceSelf(fragment, triggerEvent) {
+    const parent = this.parentNode;
+    if (!parent) {
+      return;
+    }
+    const wrapper = document.createElement('span');
+    wrapper.setAttribute('data-fx-include-replacement', '');
+    wrapper.style.display = 'contents';
+    wrapper.appendChild(fragment);
+    this._unbindListener();
+    this.replaceWith(wrapper);
+    this._replaced = true;
+    this._loaded = true;
+    await this._initializeInsertedContent(wrapper);
+    await Fore.dispatch(wrapper, 'include-done', {
+      src: this.src || null,
+      included: wrapper,
+      replaced: true,
+      triggerEvent
+    });
+  }
+  _clearIncludedContent() {
+    this.querySelectorAll(':scope > [data-fx-include-content]').forEach(node => {
+      node.remove();
+    });
+  }
+  async _initializeInsertedContent(startElement) {
+    this._initForeUiDescendants(startElement);
+    await Fore.refreshChildren(startElement, true);
+  }
+  _initForeUiDescendants(startElement) {
+    Array.from(startElement.children || []).forEach(element => {
+      if (element.nodeName.toUpperCase() === 'FX-FORE') {
+        return;
+      }
+      if (Fore.isUiElement(element.nodeName) && typeof element.init === 'function') {
+        element.init();
+      }
+      this._initForeUiDescendants(element);
+    });
+  }
+  _dispatchError(message) {
+    Fore.dispatch(this, 'error', {
+      level: 'Error',
+      message
+    });
+  }
+}
+if (!customElements.get('fx-include')) {
+  customElements.define('fx-include', FxInclude);
+}
+
 /**
  * todo: review placing of value. should probably work with value attribute and not allow slotted content.
  */
@@ -31155,6 +31358,13 @@ class FxCase extends FxContainer {
         }
         await parentNode.replaceCase(this, replacement);
         target = replacement;
+        // Re-dispatch 'select' on the loaded replacement so its fx-action handlers fire.
+        // The replacement's handlers are registered after async loading; they miss the
+        // initial 'select' that triggered the load.
+        if (parentNode.selectedCase === replacement) {
+          await Fore.dispatch(replacement, 'select', {});
+          return;
+        }
       }
       ownerForm.getModel();
       ownerForm.addToBatchedNotifications(target);

package/dist/fore.js

@@ -1,4 +1,4 @@
-/* Version: 3.1.1 - May 20, 2026 17:16:47 */
+/* Version: 3.2.0 - June 9, 2026 10:50:37 */
 function t$2(t, s, r, i) {
   const n = {
     op: s,
@@ -20121,7 +20121,7 @@ class Fore {
     return Fore.ACTION_ELEMENTS.includes(elementName);
   }
   static get UI_ELEMENTS() {
-    return new Set(['FX-ALERT', 'FX-CONTROL', 'FX-DIALOG', 'FX-FILENAME', 'FX-MEDIATYPE', 'FX-GROUP', 'FX-HINT', 'FX-ITEMS', 'FX-OUTPUT', 'FX-RANGE', 'FX-REPEAT', 'FX-REPEATITEM', 'FX-REPEAT-ATTRIBUTES', 'FX-SWITCH', 'FX-SECRET', 'FX-SELECT', 'FX-SUBMIT', 'FX-TEXTAREA', 'FX-TRIGGER', 'FX-UPLOAD', 'FX-VAR']);
+    return new Set(['FX-ALERT', 'FX-CONTROL', 'FX-DIALOG', 'FX-FILENAME', 'FX-MEDIATYPE', 'FX-GROUP', 'FX-HINT', 'FX-ITEMS', 'FX-INCLUDE', 'FX-OUTPUT', 'FX-RANGE', 'FX-REPEAT', 'FX-REPEATITEM', 'FX-REPEAT-ATTRIBUTES', 'FX-SWITCH', 'FX-SECRET', 'FX-SELECT', 'FX-SUBMIT', 'FX-TEXTAREA', 'FX-TRIGGER', 'FX-UPLOAD', 'FX-VAR']);
   }
 
   /**
@@ -21553,10 +21553,8 @@ class FxModel extends HTMLElement {
     const instance = model.getInstance(instanceId);
     const fore = model.formElement;
     if (fore?.createNodes && (node === null || node === undefined)) {
-      const mi = new ModelItem(undefined, ref, null, null, instanceId, fore);
-      mi.isSynthetic = true;
-      model.registerModelItem(mi);
-      return mi;
+      // Do not create the model item. It may be exchanged later when create-nodes actually made the node
+      return null;
     }
     if (node === null || node === undefined) return null;
     let targetNode = Array.isArray(node) ? node[0] : node;
@@ -25427,7 +25425,7 @@ class FxFore extends HTMLElement {
       this._createRepeatsFromAttributes();
       this.inited = true;
     };
-    this.version = 'Version: 3.1.1 - built on May 20, 2026 17:16:47';
+    this.version = 'Version: 3.2.0 - built on June 9, 2026 10:50:37';
 
     /**
      * @type {import('./fx-model.js').FxModel}
@@ -26861,7 +26859,7 @@ class FxFore extends HTMLElement {
         bound.evalInContext();
         if (bound.nodeName !== 'FX-REPEAT') {
           // Do not try to get a bind for a nodeSET of a repeat. there are multiple.
-          bound.getModelItem().bind?.evalInContext();
+          bound.getModelItem()?.bind?.evalInContext();
         }
         continue;
       }
@@ -26910,7 +26908,7 @@ class FxFore extends HTMLElement {
         }
       }
       bound.evalInContext();
-      bound.getModelItem().bind?.evalInContext();
+      bound.getModelItem()?.bind?.evalInContext();
       if (!isResolvedBound(bound)) {
         continue;
       }
@@ -27043,6 +27041,10 @@ class FxFore extends HTMLElement {
         continue;
       }
       const parsed = parseName(token);
+      if (!isValidName(parsed.localName)) {
+        // This did not result in a valid name. Stop.
+        return;
+      }
       if (parsed.isAttribute) {
         if (!current) {
           const attr = ownerDoc.createAttribute(parsed.localName);
@@ -27051,10 +27053,6 @@ class FxFore extends HTMLElement {
         current.setAttribute(parsed.localName, '');
         continue;
       }
-      if (!isValidName(parsed.localName)) {
-        // This did not result in a valid name. Stop.
-        return;
-      }
       const element = parsed.namespaceURI ? ownerDoc.createElementNS(parsed.namespaceURI, parsed.localName) : ownerDoc.createElement(parsed.localName);
       for (const predicate of predicates) {
         const attrName = predicate.name.includes(':') ? predicate.name.split(':')[1] : predicate.name;
@@ -31055,6 +31053,13 @@ class FxCase extends FxContainer {
         }
         await parentNode.replaceCase(this, replacement);
         target = replacement;
+        // Re-dispatch 'select' on the loaded replacement so its fx-action handlers fire.
+        // The replacement's handlers are registered after async loading; they miss the
+        // initial 'select' that triggered the load.
+        if (parentNode.selectedCase === replacement) {
+          await Fore.dispatch(replacement, 'select', {});
+          return;
+        }
       }
       ownerForm.getModel();
       ownerForm.addToBatchedNotifications(target);

package/index.js

@@ -14,6 +14,7 @@ import './src/ui/fx-control.js';
 import './src/ui/fx-container.js';
 import './src/ui/fx-group.js';
 import './src/ui/fx-hint.js';
+import './src/ui/fx-include.js';
 import './src/ui/fx-output.js';
 import './src/ui/fx-repeat.js';
 import './src/ui/fx-repeat-attributes.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jinntec/fore",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "Fore - declarative user interfaces in plain HTML",
   "module": "./index.js",
   "publishConfig": {

package/src/fore.js

@@ -239,6 +239,7 @@ export class Fore {
       'FX-GROUP',
       'FX-HINT',
       'FX-ITEMS',
+      'FX-INCLUDE',
       'FX-OUTPUT',
       'FX-RANGE',
       'FX-REPEAT',

package/src/fx-fore.js

@@ -1819,7 +1819,7 @@ export class FxFore extends HTMLElement {
         bound.evalInContext();
         if (bound.nodeName !== 'FX-REPEAT') {
           // Do not try to get a bind for a nodeSET of a repeat. there are multiple.
-          bound.getModelItem().bind?.evalInContext();
+          bound.getModelItem()?.bind?.evalInContext();
         }
         continue;
       }
@@ -1878,7 +1878,7 @@ export class FxFore extends HTMLElement {
       }
 
       bound.evalInContext();
-      bound.getModelItem().bind?.evalInContext();
+      bound.getModelItem()?.bind?.evalInContext();
 
       if (!isResolvedBound(bound)) {
         console.warn('create-nodes: could not resolve bound after node creation, skipping', bound);
@@ -2016,6 +2016,14 @@ export class FxFore extends HTMLElement {
 
       const parsed = parseName(token);
 
+      if (!isValidName(parsed.localName)) {
+        // This did not result in a valid name. Stop.
+        console.warn(
+          `Creating node for the XPath ${xpath} failed because the part ${parsed.localName} is not a valid Name.`,
+        );
+        return;
+      }
+
       if (parsed.isAttribute) {
         if (!current) {
           const attr = ownerDoc.createAttribute(parsed.localName);
@@ -2025,14 +2033,6 @@ export class FxFore extends HTMLElement {
         continue;
       }
 
-      if (!isValidName(parsed.localName)) {
-        // This did not result in a valid name. Stop.
-        console.warn(
-          `Creating node for the XPath ${xpath} failed because the part ${parsed.localName} is not a valid Name.`,
-        );
-        return;
-      }
-
       const element = parsed.namespaceURI
         ? ownerDoc.createElementNS(parsed.namespaceURI, parsed.localName)
         : ownerDoc.createElement(parsed.localName);

package/src/fx-model.js

@@ -133,10 +133,8 @@ export class FxModel extends HTMLElement {
     const fore = model.formElement;
 
     if (fore?.createNodes && (node === null || node === undefined)) {
-      const mi = new ModelItem(undefined, ref, null, null, instanceId, fore);
-      mi.isSynthetic = true;
-      model.registerModelItem(mi);
-      return mi;
+      // Do not create the model item. It may be exchanged later when create-nodes actually made the node
+      return null;
     }
     if (node === null || node === undefined) return null;
 
@@ -159,8 +157,10 @@ export class FxModel extends HTMLElement {
     }
 
     const isLensObject =
-        !!targetNode && typeof targetNode === 'object' &&
-        typeof targetNode.get === 'function' && typeof targetNode.set === 'function';
+      !!targetNode &&
+      typeof targetNode === 'object' &&
+      typeof targetNode.get === 'function' &&
+      typeof targetNode.set === 'function';
 
     // If ModelItem for same path exists, RETARGET it (node OR lens)
     if (path) {
@@ -182,12 +182,12 @@ export class FxModel extends HTMLElement {
     }
 
     const mi = new ModelItem(
-        path,
-        ref,
-        targetNode,
-        model.getBindForElement(targetNode),
-        instanceId,
-        fore,
+      path,
+      ref,
+      targetNode,
+      model.getBindForElement(targetNode),
+      instanceId,
+      fore,
     );
     mi.isSynthetic = true;
 
@@ -231,7 +231,8 @@ export class FxModel extends HTMLElement {
           const defInst = this.getDefaultInstance();
           if (defInst) {
             const t = (defInst.getAttribute && defInst.getAttribute('type')) || defInst.type;
-            bindings.default = t === 'json' ? defInst.getInstanceData() : defInst.getDefaultContext();
+            bindings.default =
+              t === 'json' ? defInst.getInstanceData() : defInst.getDefaultContext();
           }
         } catch (_e) {
           // ignore
@@ -734,14 +735,14 @@ export class FxModel extends HTMLElement {
 
     // Path lookup
     if (typeof nodeOrPath === 'string') {
-      const key = nodeOrPath.includes(':') ? nodeOrPath.substring(0, nodeOrPath.indexOf(':')) : nodeOrPath;
+      const key = nodeOrPath.includes(':')
+        ? nodeOrPath.substring(0, nodeOrPath.indexOf(':'))
+        : nodeOrPath;
       return this.modelItems.find(mi => mi.path === key) || null;
     }
 
     // Node/lens lookup
-    return (
-        this.modelItems.find(mi => mi.node === nodeOrPath || mi.lens === nodeOrPath) || null
-    );
+    return this.modelItems.find(mi => mi.node === nodeOrPath || mi.lens === nodeOrPath) || null;
   }
 
   /**
@@ -791,9 +792,9 @@ export class FxModel extends HTMLElement {
     // ### lookup in parent Fore if present (shared instances)
     if (!found) {
       const parentFore =
-          this.fore.parentNode.nodeType === Node.DOCUMENT_FRAGMENT_NODE
-              ? this.fore.parentNode.host.closest('fx-fore')
-              : this.fore.parentNode.closest('fx-fore');
+        this.fore.parentNode.nodeType === Node.DOCUMENT_FRAGMENT_NODE
+          ? this.fore.parentNode.host.closest('fx-fore')
+          : this.fore.parentNode.closest('fx-fore');
 
       if (parentFore) {
         const parentInstances = parentFore.getModel().instances;

package/src/ui/fx-case.js

@@ -81,6 +81,13 @@ export class FxCase extends FxContainer {
         }
         await parentNode.replaceCase(this, replacement);
         target = replacement;
+        // Re-dispatch 'select' on the loaded replacement so its fx-action handlers fire.
+        // The replacement's handlers are registered after async loading; they miss the
+        // initial 'select' that triggered the load.
+        if (parentNode.selectedCase === replacement) {
+          await Fore.dispatch(replacement, 'select', {});
+          return;
+        }
       }
       const model = ownerForm.getModel();
       ownerForm.addToBatchedNotifications(target);

package/src/ui/fx-include.js

@@ -0,0 +1,264 @@
+import { Fore } from '../fore.js';
+
+/**
+ * <fx-include>
+ *
+ * Lazy light-DOM include component.
+ *
+ * Loads markup either from:
+ *   - a direct child <template>
+ *   - an external HTML document via @src
+ *
+ * Default behavior:
+ *   - listens for an event
+ *   - includes content once
+ *   - removes the event listener afterwards
+ *
+ * With @reload:
+ *   - listens repeatedly
+ *   - clears previously included content
+ *   - includes fresh content again
+ *
+ * Attributes:
+ *   event      Event name to listen for. Defaults to "click".
+ *   target     CSS selector for the event target. Defaults to "self".
+ *              Special values: self, document, window.
+ *   src        Optional external HTML source.
+ *   selector   Optional selector inside external HTML.
+ *   replace    Replace <fx-include> with the included content.
+ *   immediate  Include immediately when connected.
+ *   reload     Re-include on every matching event.
+ */
+export class FxInclude extends HTMLElement {
+  constructor() {
+    super();
+
+    this._listener = this._handleEvent.bind(this);
+    this._eventTarget = null;
+    this._loaded = false;
+    this._replaced = false;
+  }
+
+  connectedCallback() {
+    this.eventName = this.getAttribute('event') || 'click';
+    this.targetSelector = this.getAttribute('target') || 'self';
+    this.src = this.getAttribute('src');
+    this.selector = this.getAttribute('selector');
+
+    this.replace = this.hasAttribute('replace');
+    this.immediate = this.hasAttribute('immediate');
+    this.reload = this.hasAttribute('reload');
+
+    if (this.immediate) {
+      queueMicrotask(() => this.include());
+      return;
+    }
+
+    this._bindListener();
+  }
+
+  disconnectedCallback() {
+    this._unbindListener();
+  }
+
+  _bindListener() {
+    const target = this._resolveEventTarget();
+
+    if (!target) {
+      this._dispatchError(`fx-include: event target not found: '${this.targetSelector}'`);
+      return;
+    }
+
+    target.addEventListener(this.eventName, this._listener);
+    this._eventTarget = target;
+  }
+
+  _unbindListener() {
+    if (this._eventTarget && this._listener) {
+      this._eventTarget.removeEventListener(this.eventName, this._listener);
+    }
+
+    this._eventTarget = null;
+  }
+
+  _resolveEventTarget() {
+    if (!this.targetSelector || this.targetSelector === 'self') {
+      return this;
+    }
+
+    if (this.targetSelector === 'document') {
+      return document;
+    }
+
+    if (this.targetSelector === 'window') {
+      return window;
+    }
+
+    const fore = this.closest('fx-fore');
+
+    return fore?.querySelector(this.targetSelector) || document.querySelector(this.targetSelector);
+  }
+
+  async _handleEvent(event) {
+    await this.include(event);
+  }
+
+  async include(triggerEvent = null) {
+    if (this._replaced) {
+      return;
+    }
+
+    if (this._loaded && !this.reload) {
+      return;
+    }
+
+    const fragment = this.src ? await this._loadExternalFragment() : this._loadTemplateFragment();
+
+    if (!fragment) {
+      return;
+    }
+
+    if (this.replace) {
+      await this._replaceSelf(fragment, triggerEvent);
+      return;
+    }
+
+    this._clearIncludedContent();
+
+    const wrapper = document.createElement('span');
+    wrapper.setAttribute('data-fx-include-content', '');
+    wrapper.style.display = 'contents';
+    wrapper.appendChild(fragment);
+
+    this.appendChild(wrapper);
+
+    this._loaded = true;
+
+    await this._initializeInsertedContent(wrapper);
+
+    await Fore.dispatch(this, 'include-done', {
+      src: this.src || null,
+      included: wrapper,
+      replaced: false,
+      triggerEvent,
+    });
+
+    if (!this.reload) {
+      this._unbindListener();
+    }
+  }
+
+  _loadTemplateFragment() {
+    const template = this.querySelector(':scope > template');
+
+    if (!template) {
+      this._dispatchError('fx-include: no src and no direct template child found');
+      return null;
+    }
+
+    return template.content.cloneNode(true);
+  }
+
+  async _loadExternalFragment() {
+    const html = await Fore.loadHtml(this.src);
+
+    if (!html) {
+      this._dispatchError(`fx-include: failed to load '${this.src}'`);
+      return null;
+    }
+
+    const parsed = new DOMParser().parseFromString(html, 'text/html');
+
+    if (this.selector) {
+      const selected = parsed.querySelector(this.selector);
+
+      if (!selected) {
+        this._dispatchError(`fx-include: selector '${this.selector}' not found in '${this.src}'`);
+        return null;
+      }
+
+      const fragment = document.createDocumentFragment();
+      fragment.appendChild(document.importNode(selected, true));
+      return fragment;
+    }
+
+    const template = parsed.querySelector('template');
+
+    if (template) {
+      return document.importNode(template.content, true);
+    }
+
+    const fragment = document.createDocumentFragment();
+
+    Array.from(parsed.body.childNodes).forEach(node => {
+      fragment.appendChild(document.importNode(node, true));
+    });
+
+    return fragment;
+  }
+
+  async _replaceSelf(fragment, triggerEvent) {
+    const parent = this.parentNode;
+
+    if (!parent) {
+      return;
+    }
+
+    const wrapper = document.createElement('span');
+    wrapper.setAttribute('data-fx-include-replacement', '');
+    wrapper.style.display = 'contents';
+    wrapper.appendChild(fragment);
+
+    this._unbindListener();
+
+    this.replaceWith(wrapper);
+
+    this._replaced = true;
+    this._loaded = true;
+
+    await this._initializeInsertedContent(wrapper);
+
+    await Fore.dispatch(wrapper, 'include-done', {
+      src: this.src || null,
+      included: wrapper,
+      replaced: true,
+      triggerEvent,
+    });
+  }
+
+  _clearIncludedContent() {
+    this.querySelectorAll(':scope > [data-fx-include-content]').forEach(node => {
+      node.remove();
+    });
+  }
+
+  async _initializeInsertedContent(startElement) {
+    this._initForeUiDescendants(startElement);
+    await Fore.refreshChildren(startElement, true);
+  }
+
+  _initForeUiDescendants(startElement) {
+    Array.from(startElement.children || []).forEach(element => {
+      if (element.nodeName.toUpperCase() === 'FX-FORE') {
+        return;
+      }
+
+      if (Fore.isUiElement(element.nodeName) && typeof element.init === 'function') {
+        element.init();
+      }
+
+      this._initForeUiDescendants(element);
+    });
+  }
+
+  _dispatchError(message) {
+    Fore.dispatch(this, 'error', {
+      level: 'Error',
+      message,
+    });
+  }
+}
+
+if (!customElements.get('fx-include')) {
+  customElements.define('fx-include', FxInclude);
+}