@jinntec/fore 3.2.0 → 3.3.0

package/src/fx-fore.js

@@ -102,6 +102,7 @@ export class FxFore extends HTMLElement {
       },
       /**
        * merge-partial
+       * @deprecated
        */
       mergePartial: {
         type: Boolean,
@@ -346,15 +347,92 @@ export class FxFore extends HTMLElement {
     this.initialRun = true;
     this._scanForNewTemplateExpressionsNextRefresh = false;
     this.repeatsFromAttributesCreated = false;
+/*
     this.validateOn = this.hasAttribute('validate-on')
       ? this.getAttribute('validate-on')
       : 'update';
+*/
     // this.mergePartial = this.hasAttribute('merge-partial')? true:false;
     this.mergePartial = false;
     this.createNodes = this.hasAttribute('create-nodes') ? true : false;
     this._localNamesWithChanges = new Set();
     this.setAttribute('role', 'form'); // set aria role
     this._pendingRefresh = false;
+
+    this.debugInfo = {
+      id: this.id || null,
+      debugId: crypto.randomUUID ? crypto.randomUUID() : `fore-${Date.now()}`,
+      createdAt: performance.now(),
+      readyAt: null,
+      modelConstructStartedAt: null,
+      modelConstructDoneAt: null,
+      refreshCount: 0,
+      lastRefreshAt: null,
+      lastRefreshForce: null,
+      lastRefresh: null,
+    };
+  }
+
+  getDebugInfo() {
+    return {
+      ...this.debugInfo,
+      id: this.id || null,
+      ready: this.ready,
+      lazyRefresh: this.lazyRefresh,
+      createNodes: this.createNodes,
+
+      initOn: this.getAttribute('init-on') || null,
+      initOnTarget: this.getAttribute('init-on-target') || null,
+      ignoreExpressions: this.getAttribute('ignore-expressions') || null,
+
+      model: this.model?.getDebugInfo?.() || null,
+    };
+  }
+
+  getDebugSnapshot(options = {}) {
+    const model = this.model;
+
+    const debugRefElements = Array.from(this.querySelectorAll('[ref]'))
+        .filter(element => typeof element.getDebugInfo === 'function');
+
+    const bindingElements = debugRefElements
+        .filter(element => element.localName === 'fx-bind');
+
+    const boundElementNames = new Set([
+      'fx-control',
+      'fx-output',
+      'fx-upload',
+      'fx-group',
+      'fx-repeat',
+      'fx-switch',
+    ]);
+
+    const boundUiElements = debugRefElements
+        .filter(element => boundElementNames.has(element.localName));
+
+    const bindings = bindingElements.map(element => element.getDebugInfo());
+
+    const boundElements = boundUiElements.map(element => element.getDebugInfo());
+
+    const submissions = Array.from(this.querySelectorAll('fx-submission'))
+        .filter(element => typeof element.getDebugInfo === 'function')
+        .map(element => element.getDebugInfo());
+
+    return {
+      fore: this.getDebugInfo?.() || null,
+
+      model:
+          model?.getDebugInfo?.({
+            includeGraphs: options.includeGraphs === true,
+          }) || null,
+
+      instances: model?.instances?.map(instance => instance.getDebugInfo?.()) || [],
+      modelItems: model?.modelItems?.map(item => item.getDebugInfo?.()) || [],
+
+      bindings,
+      boundElements,
+      submissions
+    };
   }
 
   /**
@@ -387,7 +465,7 @@ export class FxFore extends HTMLElement {
     return null;
   }
 
-  _isReadyTarget(el) {
+  static _isReadyTarget(el) {
     return !!(
       el &&
       (el.ready === true ||
@@ -396,6 +474,17 @@ export class FxFore extends HTMLElement {
     );
   }
 
+  /**
+   * Resolves once `fore` has dispatched its initial `ready` event (or
+   * immediately, if it's already ready).
+   */
+  static waitUntilReady(fore) {
+    if (FxFore._isReadyTarget(fore)) {
+      return Promise.resolve();
+    }
+    return FxFore._waitForEvent(fore, 'ready', FxFore._isReadyTarget);
+  }
+
   /**
    * Collect all init gates derived from attributes.
    *
@@ -433,7 +522,7 @@ export class FxFore extends HTMLElement {
     return gates;
   }
 
-  _waitForEvent(target, eventName, isSatisfiedFn = null) {
+  static _waitForEvent(target, eventName, isSatisfiedFn = null) {
     // If a caller provides an explicit satisfaction check, honor it first.
     if (typeof isSatisfiedFn === 'function' && isSatisfiedFn(target)) {
       FxFore._markInitEventSeen(target, eventName);
@@ -495,20 +584,20 @@ export class FxFore extends HTMLElement {
   _waitForInitGate({ event, targetSpec }) {
     // Direct targets
     if (targetSpec === 'self') {
-      const satisfied = event === 'ready' ? t => this._isReadyTarget(t) : null;
-      return this._waitForEvent(this, event, satisfied);
+      const satisfied = event === 'ready' ? t => FxFore._isReadyTarget(t) : null;
+      return FxFore._waitForEvent(this, event, satisfied);
     }
     if (targetSpec === 'document') {
-      return this._waitForEvent(document, event);
+      return FxFore._waitForEvent(document, event);
     }
     if (targetSpec === 'window') {
-      return this._waitForEvent(window, event);
+      return FxFore._waitForEvent(window, event);
     }
 
     // Special: closest fx-fore
     if (targetSpec === 'closest') {
       const recheckFn =
-        event === 'ready' ? () => this._isReadyTarget(this.closest('fx-fore')) : null;
+        event === 'ready' ? () => FxFore._isReadyTarget(this.closest('fx-fore')) : null;
 
       const matchesFn = ev => {
         const t = ev.target;
@@ -522,7 +611,7 @@ export class FxFore extends HTMLElement {
     const selector = targetSpec;
 
     const recheckFn =
-      event === 'ready' ? () => this._isReadyTarget(this._findBySelector(selector)) : null;
+      event === 'ready' ? () => FxFore._isReadyTarget(this._findBySelector(selector)) : null;
 
     if (typeof recheckFn === 'function' && recheckFn()) {
       return Promise.resolve();
@@ -627,7 +716,10 @@ export class FxFore extends HTMLElement {
       const libs = Array.from(this.querySelectorAll('fx-functionlib'));
       await Promise.all(libs.map(l => l.readyPromise || Promise.resolve()));
 
+      this.debugInfo.modelConstructStartedAt = performance.now();
       await modelElement.modelConstruct();
+      this.debugInfo.modelConstructDoneAt = performance.now();
+
       console.log('varbindings ', this._instanceVarBindings);
       this._handleModelConstructDone();
     }
@@ -702,9 +794,8 @@ export class FxFore extends HTMLElement {
               // e.stopImmediatePropagation();
             },true);
         */
-    this.ignoreExpressions = this.hasAttribute('ignore-expressions')
-      ? this.getAttribute('ignore-expressions')
-      : null;
+    const userIgnore = this.getAttribute('ignore-expressions');
+    this.ignoreExpressions = userIgnore ? `[pattern], ${userIgnore}` : '[pattern]';
 
     this.lazyRefresh = this.hasAttribute('refresh-on-view');
     if (this.lazyRefresh) {
@@ -945,6 +1036,11 @@ export class FxFore extends HTMLElement {
   async refresh(force) {
     // If we're already refreshing, do NOT drop the request.
     // Queue a hard refresh and return a promise that resolves when the next refresh finishes.
+
+    this.debugInfo.refreshCount += 1;
+    this.debugInfo.lastRefreshAt = performance.now();
+    this.debugInfo.lastRefreshForce = !!force;
+
     if (this.isRefreshing) {
       // keep "strongest" request: any true means hard refresh
       this._pendingRefresh = this._pendingRefresh || force === true;
@@ -957,8 +1053,12 @@ export class FxFore extends HTMLElement {
     this.isRefreshing = true;
     this.isRefreshPhase = true;
 
+    const refreshStart = performance.now();
+    const isFullRefresh = force === true || this.initialRun;
+    const batchedCount = this.batchedNotifications.size;
+
     try {
-      if (force === true || this.initialRun) {
+      if (isFullRefresh) {
         performance.mark('force-refresh-start');
         console.log('🔄 🔴🔴🔴 ### full refresh() on ', this);
         await Fore.refreshChildren(this, force);
@@ -985,6 +1085,15 @@ export class FxFore extends HTMLElement {
         this.getModel().modelItems,
       );
 
+      // Record timing before dispatching 'refresh-done' since listeners (eg. fx-debugger)
+      // may synchronously read this.debugInfo.lastRefresh in response to the event.
+      this.debugInfo.lastRefresh = {
+        timestamp: performance.now(),
+        kind: isFullRefresh ? 'full' : 'partial',
+        durationMs: performance.now() - refreshStart,
+        batchedCount,
+      };
+
       Fore.dispatch(this, 'refresh-done', {});
 
       const subFores = Array.from(this.querySelectorAll('fx-fore'));
@@ -1018,59 +1127,63 @@ export class FxFore extends HTMLElement {
   }
 
   /**
-   * Process all batched notifications at the end of the refresh phase
+   * Process all batched notifications at the end of the refresh phase.
+   * Async so that all control refresh() calls (which are themselves async) are awaited
+   * before refresh-done fires — prevents _isRefreshing from being true when the
+   * next user input event arrives.
    */
-  _processBatchedNotifications() {
+  async _processBatchedNotifications() {
     if (this.batchedNotifications.size > 0) {
       console.log(`🔄 🎯  ### processing ${this.batchedNotifications.size} batched notifications`);
       console.log('🔄 🎯  ### processing ', Array.from(this.batchedNotifications));
 
-      // console.log(`🔍 Processing ${this.batchedNotifications.size} batched notifications`);
+      const refreshPromises = [];
 
-      // Process all batched notifications
+      // Process all batched notifications.
+      // Note: Set.forEach visits items added during iteration (they are appended to the end),
+      // so controls added via observer.update() (which calls addToBatchedNotifications) are
+      // also visited and their refresh() promises collected.
       this.batchedNotifications.forEach(entry => {
-        // console.log('batched update', entry);
-        // handle repeatitems created via data-ref
         if (entry.classList && entry.classList.contains('fx-repeatitem')) {
-          Fore.refreshChildren(entry, true);
+          refreshPromises.push(Fore.refreshChildren(entry, true));
         }
         if (entry && typeof entry.refresh === 'function') {
-          // Entry is a Ui Element
-          // Force refresh for this whole subtree
           const uiElement = /** @type {import('./ui/UIElement.js').UIElement} */ (entry);
           if (!uiElement.ownerDocument.contains(uiElement)) {
-            // Something already removed this ui element. Skip.
             return;
           }
-          uiElement.refresh(true);
+          refreshPromises.push(uiElement.refresh(true));
         }
         const nonrelevant = Array.from(this.querySelectorAll('[nonrelevant]'));
-        // loop nonrelevant elements
         if (nonrelevant) {
-          nonrelevant.forEach(entry => {
-            if (entry.refresh) {
-              entry.refresh();
+          nonrelevant.forEach(el => {
+            if (el.refresh) {
+              refreshPromises.push(el.refresh());
             }
           });
         }
         if (entry.observers) {
-          // Item is a model item
           entry.observers.forEach(observer => {
-            // console.log('🔍 processing observer', observer);
             if (typeof observer.update === 'function') {
-              // console.log('updating observer', observer);
               observer.update(entry);
             }
           });
         }
       });
 
-      // Update template expressions after processing batched notifications
-      // This ensures template expressions are re-evaluated when data changes
       this._processTemplateExpressions();
-
-      // Clear the batch
       this.batchedNotifications.clear();
+
+      if (refreshPromises.length > 0) {
+        await Promise.all(refreshPromises);
+      }
+
+      // Items added to batchedNotifications during the async Promise.all phase
+      // (e.g. by a second event listener that fired after the batch was cleared)
+      // are picked up here so they aren't lost.
+      if (this.batchedNotifications.size > 0) {
+        await this._processBatchedNotifications();
+      }
     }
   }
 
@@ -1230,10 +1343,8 @@ export class FxFore extends HTMLElement {
   } // eslint-disable-next-line class-methods-use-this
   _getTemplateExpression(node) {
     if (this.ignoredNodes) {
-      if (node.nodeType === Node.ATTRIBUTE_NODE) {
-        node = node.ownerElement;
-      }
-      const found = this.ignoredNodes.find(n => n.contains(node));
+      const checkNode = node.nodeType === Node.ATTRIBUTE_NODE ? node.ownerElement : node;
+      const found = this.ignoredNodes.find(n => n.contains(checkNode));
       if (found) return null;
     }
     if (node.nodeType === Node.ATTRIBUTE_NODE) {
@@ -1252,6 +1363,7 @@ export class FxFore extends HTMLElement {
    * @private
    */
   _handleModelConstructDone() {
+    this.debugInfo.modelConstructDoneAt = performance.now();
     if (this.showConfirmation) {
       window.addEventListener('beforeunload', event => {
         if (this.dirtyState === dirtyStates.DIRTY) {
@@ -1418,6 +1530,7 @@ export class FxFore extends HTMLElement {
     // console.log(`### <<<<< ${this.id} ready >>>>>`);
 
     Fore.dispatch(this, 'ready', {});
+    this.debugInfo.readyAt = performance.now();
     // console.log('dataChanged', FxModel.dataChanged);
     this.markAsClean();
 

package/src/fx-instance.js

@@ -9,7 +9,11 @@ async function handleResponse(fxInstance, response) {
     alert(`response status:  ${status} - failed to load data for '${fxInstance.src}' - stopping.`);
     throw new Error(`failed to load data - status: ${status}`);
   }
-  let responseContentType = response.headers.get('content-type').split(';')[0].trim().toLowerCase();
+  const responseContentType = response.headers
+    .get('content-type')
+    .split(';')[0]
+    .trim()
+    .toLowerCase();
 
   if (responseContentType.startsWith('text/html')) {
     return response.text().then(result => new DOMParser().parseFromString(result, 'text/html'));
@@ -49,6 +53,37 @@ export class FxInstance extends HTMLElement {
 
     // JSON facade (only relevant for JSON instances)
     this.domFacade = null;
+
+    this.debugInfo = {
+      debugId: `instance-${Math.random().toString(36).slice(2, 9)}`,
+      createdAt: performance.now(),
+      initializedAt: null,
+      loadCount: 0,
+/*
+      mutationCount: 0,
+      lastMutationAt: null,
+*/
+    };
+  }
+
+  getDebugInfo() {
+    const defaultContext = this.getDefaultContext?.();
+
+    return {
+      ...this.debugInfo,
+      id: this.getAttribute('id') || null,
+      instanceId: this.instanceId,
+      type: this.type,
+      src: this.getAttribute('src') || null,
+      shared: this.hasAttribute('shared'),
+      hasData: !!this.instanceData,
+      hasNodeset: !!this.nodeset,
+      defaultContextType: defaultContext?.nodeType
+        ? 'xml-node'
+        : defaultContext?.__jsonlens__
+          ? 'json-lens'
+          : typeof defaultContext,
+    };
   }
 
   connectedCallback() {
@@ -61,7 +96,9 @@ export class FxInstance extends HTMLElement {
     // If the author did not provide an id on that first instance, we set id="default".
     // If the author provided an id on that first instance, we use that id instead.
     const parentModel =
-      this.parentNode && this.parentNode.nodeName && this.parentNode.nodeName.toUpperCase() === 'FX-MODEL'
+      this.parentNode &&
+      this.parentNode.nodeName &&
+      this.parentNode.nodeName.toUpperCase() === 'FX-MODEL'
         ? this.parentNode
         : null;
 
@@ -92,7 +129,9 @@ export class FxInstance extends HTMLElement {
       }
     }
 
-    this.credentials = this.hasAttribute('credentials') ? this.getAttribute('credentials') : 'same-origin';
+    this.credentials = this.hasAttribute('credentials')
+      ? this.getAttribute('credentials')
+      : 'same-origin';
     if (!['same-origin', 'include', 'omit'].includes(this.credentials)) {
       console.error(
         `fx-submission: the value of credentials is not valid. Expected 'same-origin', 'include' or 'omit' but got '${this.credentials}'`,
@@ -144,6 +183,8 @@ export class FxInstance extends HTMLElement {
 
     // Signal structure mutation (used by fx-fore for refresh decisions)
     this.dispatchEvent(new CustomEvent('path-mutated', { bubbles: true, composed: true }));
+    // this.debugInfo.mutationCount += 1;
+    // this.debugInfo.lastMutationAt = performance.now();
   }
 
   /**
@@ -162,6 +203,8 @@ export class FxInstance extends HTMLElement {
   }
 
   reset() {
+    // this.debugInfo.mutationCount += 1;
+    // this.debugInfo.lastMutationAt = performance.now();
     // use the setter so nodeset is rebuilt for JSON too
     if (this.originalInstance && this.type === 'xml') {
       this.instanceData = this.originalInstance.cloneNode(true);
@@ -193,6 +236,8 @@ export class FxInstance extends HTMLElement {
    * legacy setter API: keep it, but forward to instanceData setter
    */
   setInstanceData(data) {
+    // this.debugInfo.mutationCount += 1;
+    // this.debugInfo.lastMutationAt = performance.now();
     this.instanceData = data;
   }
 
@@ -224,6 +269,8 @@ export class FxInstance extends HTMLElement {
     } else if (this.childNodes.length !== 0) {
       this._useInlineData();
     }
+    this.debugInfo.initializedAt = performance.now();
+    this.debugInfo.loadCount += 1;
   }
 
   createInstanceData() {
@@ -339,4 +386,4 @@ export class FxInstance extends HTMLElement {
 
 if (!customElements.get('fx-instance')) {
   customElements.define('fx-instance', FxInstance);
-}
+}