@jinntec/fore 3.2.1 → 3.3.0

package/index.js

@@ -1,3 +1,4 @@
+import './tools/debug/auto-debugger.js';
 // core + models classes
 import './src/fx-bind.js';
 import './src/fx-connection.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jinntec/fore",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "description": "Fore - declarative user interfaces in plain HTML",
   "module": "./index.js",
   "publishConfig": {
@@ -93,7 +93,8 @@
     "test:prune-snapshots": "karma start --prune-snapshots",
     "test:bs": "karma start karma.bs.config.js --coverage",
     "start:build": "cd dist && es-dev-server --open",
-    "build": "rimraf dist && rollup -c rollup.config.js",
+    "build": "rimraf dist && vite build --config vite.build.config.js && vite build --config vite.build-dev.config.js",
+    "build:rollup": "rimraf dist && rollup -c rollup.config.js",
     "start": "vite --open --port 8090 --host",
     "preversion": "npm run test",
     "prepare": "npm run build",

package/resources/fore.css

@@ -66,6 +66,25 @@
         display: block;
     }
 
+    /*
+     * Native-constraint alert visibility: show fx-alert only after the user has
+     * interacted with the field (:user-invalid fires after first dirty interaction).
+     * Complements .visited[invalid] above, which covers Fore-driven (XPath) invalidity.
+     */
+    fx-control:has(input.widget:user-invalid) fx-alert {
+        display: block;
+    }
+
+    /*
+     * Fallback for browsers without :user-invalid support.
+     * :placeholder-shown is false when a value is present, approximating "user typed".
+     */
+    @supports not selector(input:user-invalid) {
+        fx-control[invalid]:has(input.widget:not(:placeholder-shown)) fx-alert {
+            display: block;
+        }
+    }
+
     /* case not displayed by default - if you want e.g. apply transitions you have to overwrite this rule with display='inline' or similar */
     fx-case {
         display: none;
@@ -73,6 +92,9 @@
     fx-case.selected-case{
         display:block;
     }
+    fx-case.deselected-case{
+        display:none;
+    }
 
     fx-output[readonly] img {
         background: inherit;

package/src/ForeElementMixin.js

@@ -68,6 +68,24 @@ export default class ForeElementMixin extends HTMLElement {
     this.ownerForm = null;
   }
 
+  getDebugInfo() {
+    return {
+      localName: this.localName,
+      id: this.id || null,
+      ref: this.getAttribute?.('ref') || null,
+
+      modelItemPath: this.modelItem?.path || null,
+      instanceId: this.modelItem?.instanceId || null,
+
+      value: this.modelItem?.value,
+
+      relevant: this.modelItem?.relevant,
+      readonly: this.modelItem?.readonly,
+      required: this.modelItem?.required,
+      constraint: this.modelItem?.constraint,
+    };
+  }
+
   connectedCallback() {
     if (this.parentElement) {
       this.dependencies.setParentDependencies(this.parentElement?.closest('[ref]')?.dependencies);

package/src/actions/abstract-action.js

@@ -186,10 +186,69 @@ export class AbstractAction extends ForeElementMixin {
     }
   }
 
+  getActionDebugDetail(extra = {}) {
+    const getAttr = name => {
+      try {
+        return this.getAttribute(name) || null;
+      } catch (error) {
+        return null;
+      }
+    };
+
+    return {
+      action: this.localName || null,
+      actionClass: this.constructor?.name || null,
+      id: this.id || null,
+      event: this.event || null,
+      ref: getAttr('ref'),
+      target: getAttr('target'),
+      origin: getAttr('origin'),
+      submission: getAttr('submission'),
+      control: getAttr('control'),
+      if: getAttr('if'),
+      while: getAttr('while'),
+      iterate: getAttr('iterate'),
+      delay: this.delay || 0,
+      needsUpdate: this.needsUpdate,
+      ownerFore: this.getOwnerFormSafe()?.id || null,
+      ...extra,
+    };
+  }
+
+  dispatchActionDebugEvent(type, extra = {}) {
+    try {
+      const target = this.isConnected ? this : (this.getOwnerFormSafe() ?? this);
+      target.dispatchEvent(
+          new CustomEvent(type, {
+            composed: true,
+            bubbles: true,
+            cancelable: false,
+            detail: this.getActionDebugDetail(extra),
+          }),
+      );
+    } catch (error) {
+      // Debug events must never affect action execution.
+    }
+  }
+
+  getOwnerFormSafe() {
+    try {
+      return this.getOwnerForm?.() || null;
+    } catch (error) {
+      return null;
+    }
+  }
+
   async performSafe() {
+    let success = false;
+
+    this.dispatchActionDebugEvent('action-start', {
+      phase: 'start',
+    });
+
     try {
       await this.perform();
-      // Return true to indicate success
+      success = true;
       return true;
     } catch (error) {
       await Fore.dispatch(this, 'error', {
@@ -198,11 +257,15 @@ export class AbstractAction extends ForeElementMixin {
         expr: error,
         level: 'Error',
       });
-      // Return false to indicate failure. Any loops must be canceled
+
       return false;
+    } finally {
+      this.dispatchActionDebugEvent('action-end', {
+        phase: 'end',
+        success,
+      });
     }
   }
-
   /**
    * executes the action.
    *
@@ -263,8 +326,10 @@ export class AbstractAction extends ForeElementMixin {
 
     // Outermost handling
     if (FxFore.outermostHandler === null) {
+      const ownerForm = this.getOwnerFormSafe();
+
       console.log(
-        `%coutermost Action on ${this.getOwnerForm().id}`,
+        `%coutermost Action on ${ownerForm?.id || ''}`,
         'background:darkblue; color:white; padding:0.3rem; display:inline-block; white-space: nowrap; border-radius:0.3rem;',
         this,
       );
@@ -319,7 +384,8 @@ export class AbstractAction extends ForeElementMixin {
     if (this.delay) {
       // Delay further execution until the delay is done
       await wait(this.delay);
-      if (!XPathUtil.contains(this.getOwnerForm(), this)) {
+      const ownerForm = this.getOwnerFormSafe();
+      if (!ownerForm || !XPathUtil.contains(ownerForm, this)) {
         // We are no longer in the document. Stop working
         this.actionPerformed();
         resolveThisEvent();
@@ -336,7 +402,8 @@ export class AbstractAction extends ForeElementMixin {
     // Start by waiting
     await wait(this.delay || 0);
 
-    if (!XPathUtil.contains(this.getOwnerForm(), this)) {
+    const ownerForm = this.getOwnerFormSafe();
+    if (!ownerForm || !XPathUtil.contains(ownerForm, this)) {
       // We are no longer in the document. Stop working
       return;
     }
@@ -347,7 +414,7 @@ export class AbstractAction extends ForeElementMixin {
     }
 
     // Perform the action once. But quit if it failed
-    if (!this.performSafe()) {
+    if (!(await this.performSafe())) {
       return;
     }
 
@@ -373,7 +440,8 @@ export class AbstractAction extends ForeElementMixin {
         return;
       }
 
-      if (!XPathUtil.contains(this.getOwnerForm(), this)) {
+      const ownerForm = this.getOwnerFormSafe();
+      if (!ownerForm || !XPathUtil.contains(ownerForm, this)) {
         // We are no longer in the document. Stop working
         return;
       }
@@ -400,8 +468,10 @@ export class AbstractAction extends ForeElementMixin {
     this.currentEvent = null;
     this.actionPerformed();
     if (FxFore.outermostHandler === this) {
+      const ownerForm = this.getOwnerFormSafe();
+
       console.log(
-        `%cfinalizing outermost Action on ${this.getOwnerForm()?.id}`,
+        `%cfinalizing outermost Action on ${ownerForm?.id || ''}`,
         'background:darkblue; color:white; padding:0.3rem; display:inline-block; white-space: nowrap; border-radius:0.3rem;',
         this,
       );
@@ -430,24 +500,22 @@ export class AbstractAction extends ForeElementMixin {
    * Template method to be implemented by each action that is called by execute() as part of
    * the processing.
    *
-   * This function should not called on any action directly - call execute() instead to ensure proper execution of 'if' and 'while'
+   * This function should not called on any action directly - call execute() instead to ensure proper execution of 'if' and 'while'.
+   *
+   * TODO Fore DevTools:
+   * Concrete actions overriding perform() should call `await super.perform()` at the start.
+   * Otherwise the debugger will not see the `execute-action` event for that action.
    */
   async perform() {
-    // await Fore.dispatch(document, 'execute-action', {action:this, event:this.event});
-
-    // todo: review - this evaluation seems redundant as we already evaluated in execute
     if (this.isBound() || this.nodeName === 'FX-ACTION') {
       this.evalInContext();
     }
 
-    this.dispatchEvent(
-      new CustomEvent('execute-action', {
-        composed: true,
-        bubbles: true,
-        cancelable: true,
-        detail: { action: this, event: this.event },
-      }),
-    );
+/*
+    await Fore.dispatch(this, 'execute-action', this.getActionDebugDetail({
+      phase: 'before',
+    }));
+*/
   }
 
   /**
@@ -475,7 +543,8 @@ export class AbstractAction extends ForeElementMixin {
       // console.log('running update cycle for outermostHandler', this);
       model.recalculate();
       model.revalidate();
-      this.getOwnerForm().refresh(false);
+      const ownerForm = this.getOwnerFormSafe();
+      ownerForm?.refresh(false);
       this.dispatchActionPerformed();
     } else if (this.needsUpdate) {
       // console.log('Update delayed!');
@@ -493,8 +562,9 @@ export class AbstractAction extends ForeElementMixin {
    * @event action-performed - whenever an action has been run
    */
   dispatchActionPerformed() {
-    // console.log('action-performed ', this);
-    Fore.dispatch(this, 'action-performed', {});
+    Fore.dispatch(this, 'action-performed', this.getActionDebugDetail({
+      phase: 'after',
+    }));
   }
 }
 

package/src/actions/fx-insert.js

@@ -413,7 +413,7 @@ export class FxInsert extends AbstractAction {
       xpath,
     });
 
-    document.dispatchEvent(
+    this.dispatchEvent(
         new CustomEvent('index-changed', {
           composed: true,
           bubbles: true,
@@ -674,7 +674,7 @@ export class FxInsert extends AbstractAction {
       xpath,
     });
 
-    document.dispatchEvent(
+    this.dispatchEvent(
       new CustomEvent('index-changed', {
         composed: true,
         bubbles: true,

package/src/fx-bind.js

@@ -45,6 +45,34 @@ export class FxBind extends ForeElementMixin {
     this.inited = false;
   }
 
+  getDebugInfo() {
+    return {
+      ref: this.getAttribute('ref'),
+      id: this.id || null,
+      instanceId: this.instanceId,
+      bindType: this.bindType,
+
+      calculate: this.getAttribute('calculate'),
+      readonly: this.getAttribute('readonly'),
+      required: this.getAttribute('required'),
+      relevant: this.getAttribute('relevant'),
+      constraint: this.getAttribute('constraint'),
+      type: this.getAttribute('type'),
+
+      modelItemCount: this._debugModelItemCount?.() || null,
+    };
+  }
+
+  _debugModelItemCount() {
+    const model = this.getModel?.();
+
+    if (!model || !Array.isArray(model.modelItems)) {
+      return 0;
+    }
+
+    return model.modelItems.filter(item => item?.bind === this).length;
+  }
+
   connectedCallback() {
     // console.log('connectedCallback ', this);
     // this.id = this.hasAttribute('id')?this.getAttribute('id'):;

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
+    };
   }
 
   /**
@@ -638,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();
     }
@@ -713,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) {
@@ -956,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;
@@ -968,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);
@@ -996,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'));
@@ -1029,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();
+      }
     }
   }
 
@@ -1241,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) {
@@ -1263,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) {
@@ -1429,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();