@jinntec/fore 3.1.2 → 3.2.0

package/dist/fore-dev.js

@@ -1,4 +1,4 @@
-/* Version: 3.1.2 - May 27, 2026 14:39:35 */
+/* 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']);
   }
 
   /**
@@ -25479,7 +25479,7 @@ class FxFore extends HTMLElement {
       this._createRepeatsFromAttributes();
       this.inited = true;
     };
-    this.version = 'Version: 3.1.2 - built on May 27, 2026 14:39:35';
+    this.version = 'Version: 3.2.0 - built on June 9, 2026 10:50:39';
 
     /**
      * @type {import('./fx-model.js').FxModel}
@@ -26929,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;
       }
@@ -26978,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;
@@ -29635,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.
  */
@@ -31153,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.2 - May 27, 2026 14:39:34 */
+/* 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']);
   }
 
   /**
@@ -25425,7 +25425,7 @@ class FxFore extends HTMLElement {
       this._createRepeatsFromAttributes();
       this.inited = true;
     };
-    this.version = 'Version: 3.1.2 - built on May 27, 2026 14:39:34';
+    this.version = 'Version: 3.2.0 - built on June 9, 2026 10:50:37';
 
     /**
      * @type {import('./fx-model.js').FxModel}
@@ -26859,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;
       }
@@ -26908,7 +26908,7 @@ class FxFore extends HTMLElement {
         }
       }
       bound.evalInContext();
-      bound.getModelItem().bind?.evalInContext();
+      bound.getModelItem()?.bind?.evalInContext();
       if (!isResolvedBound(bound)) {
         continue;
       }
@@ -31053,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.2",
+  "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);

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);
+}