@jinntec/fore 3.3.1 → 4.0.0

package/src/ui/fx-control-menu.js

@@ -5,12 +5,15 @@ import XfAbstractControl from './abstract-control.js';
  * in a popup list for activation. 'on-demand' is not a state like 'relevant' but just
  * shows/hides controls on demand. The controls still behave as usual otherwise.
  *
- *
+ * Implements the ARIA "menu button" pattern: the slotted trigger gets `aria-haspopup`/
+ * `aria-expanded`/`aria-controls`, the popup gets `role="menu"` with `role="menuitem"`
+ * entries, and Up/Down/Home/End move a roving tabindex across the open menu.
  */
 export class FxControlMenu extends XfAbstractControl {
   connectedCallback() {
     this.attachShadow({ mode: 'open' });
     this.selectExpr = this.getAttribute('select');
+    this.triggerButton = null;
 
     const style = `
       :host {
@@ -52,10 +55,11 @@ export class FxControlMenu extends XfAbstractControl {
     this.shadowRoot.innerHTML = `
       <style>${style}</style>
       <slot></slot>
-      <div class="menu" part="menu"></div>
+      <div class="menu" part="menu" role="menu"></div>
     `;
 
     this.menuEl = this.shadowRoot.querySelector('.menu');
+    this.menuEl.addEventListener('keydown', e => this._handleMenuKeydown(e));
 
     // Slotted button click
     const slot = this.shadowRoot.querySelector('slot');
@@ -64,12 +68,19 @@ export class FxControlMenu extends XfAbstractControl {
       const button = nodes.find(
         node => node.nodeType === Node.ELEMENT_NODE && node.tagName === 'BUTTON',
       );
-      if (button) {
+      if (button && button !== this.triggerButton) {
+        this.triggerButton = button;
+        button.setAttribute('aria-haspopup', 'true');
+        button.setAttribute('aria-expanded', 'false');
         button.addEventListener('click', e => {
           e.preventDefault();
           e.stopPropagation();
           this.updateMenu();
-          this.menuEl.classList.toggle('visible');
+          if (this.menuEl.classList.contains('visible')) {
+            this._closeMenu();
+          } else {
+            this._openMenu();
+          }
         });
       }
     });
@@ -83,14 +94,14 @@ export class FxControlMenu extends XfAbstractControl {
     document.addEventListener('click', e => {
       const inside = this.contains(e.target) || this.shadowRoot.contains(e.target);
       if (!inside) {
-        this.menuEl.classList.remove('visible');
+        this._closeMenu();
       }
     });
 
-    // Close on Escape
+    // Close on Escape, returning focus to the trigger
     document.addEventListener('keydown', e => {
-      if (e.key === 'Escape') {
-        this.menuEl.classList.remove('visible');
+      if (e.key === 'Escape' && this.menuEl.classList.contains('visible')) {
+        this._closeMenu({ restoreFocus: true });
       }
     });
 
@@ -132,11 +143,66 @@ export class FxControlMenu extends XfAbstractControl {
     return null;
   }
 
+  /**
+   * Opens the popup, reflects `aria-expanded` on the trigger, and moves focus to the
+   * first menu item (ARIA "menu button" pattern).
+   */
+  _openMenu() {
+    this.menuEl.classList.add('visible');
+    this.triggerButton?.setAttribute('aria-expanded', 'true');
+    this.menuEl.querySelector('a')?.focus();
+  }
+
+  /**
+   * Closes the popup and reflects `aria-expanded` on the trigger. Focus is only restored
+   * to the trigger for dismissal paths (Escape, outside click) - not on item selection,
+   * where `el.activate()` already moves focus to the newly revealed control.
+   */
+  _closeMenu({ restoreFocus = false } = {}) {
+    this.menuEl.classList.remove('visible');
+    this.triggerButton?.setAttribute('aria-expanded', 'false');
+    if (restoreFocus) {
+      this.triggerButton?.focus();
+    }
+  }
+
+  /**
+   * Roving-tabindex arrow-key navigation between menu items (Up/Down/Home/End), following
+   * the WAI-ARIA menu pattern.
+   */
+  _handleMenuKeydown(e) {
+    const items = Array.from(this.menuEl.querySelectorAll('a'));
+    if (items.length === 0) return;
+    const idx = items.indexOf(e.target);
+    if (idx === -1) return;
+
+    let newIdx;
+    switch (e.key) {
+      case 'ArrowDown':
+        newIdx = (idx + 1) % items.length;
+        break;
+      case 'ArrowUp':
+        newIdx = (idx - 1 + items.length) % items.length;
+        break;
+      case 'Home':
+        newIdx = 0;
+        break;
+      case 'End':
+        newIdx = items.length - 1;
+        break;
+      default:
+        return;
+    }
+    e.preventDefault();
+    items.forEach((item, i) => item.setAttribute('tabindex', i === newIdx ? '0' : '-1'));
+    items[newIdx].focus();
+  }
+
   updateMenu() {
     const container = this._getScopedContainer();
     if (!container) return;
 
-    let targets = [];
+    const targets = [];
     // ✅ Include container itself if it has on-demand
     if (container.hasAttribute('on-demand')) {
       targets.push(container);
@@ -163,7 +229,7 @@ export class FxControlMenu extends XfAbstractControl {
     }
 
     if (targets.length === 0) {
-      this.menuEl.classList.remove('visible');
+      this._closeMenu();
       return;
     }
 
@@ -182,6 +248,8 @@ export class FxControlMenu extends XfAbstractControl {
       const item = document.createElement('a');
       item.href = '#';
       item.textContent = label;
+      item.setAttribute('role', 'menuitem');
+      item.setAttribute('tabindex', index === 0 ? '0' : '-1');
 
       item.addEventListener('click', e => {
         e.preventDefault();
@@ -189,7 +257,7 @@ export class FxControlMenu extends XfAbstractControl {
           el.activate();
         }
 
-        this.menuEl.classList.remove('visible');
+        this._closeMenu();
 
         // Wait one frame to let DOM updates (like on-demand removal) take effect
         requestAnimationFrame(() => {

package/src/ui/fx-control.js

@@ -9,8 +9,8 @@ import getInScopeContext from '../getInScopeContext.js';
 import { Fore } from '../fore.js';
 import { debounce } from '../events.js';
 import { FxModel } from '../fx-model.js';
+import { FxFore } from '../fx-fore.js';
 import { DependencyNotifyingDomFacade } from '../DependencyNotifyingDomFacade';
-import { extractPredicateDependencies } from '../extract-predicate-deps.js';
 import '../fx-instance.js';
 
 const WIDGETCLASS = 'widget';
@@ -122,14 +122,23 @@ export default class FxControl extends XfAbstractControl {
       );
     }
 
-    this.shadowRoot.innerHTML = `
+    const controlHtml = this.renderHTML(this.ref);
+    const sheet = Fore.getSharedStyleSheet(style);
+    if (sheet) {
+      this.shadowRoot.innerHTML = controlHtml;
+      this.shadowRoot.adoptedStyleSheets = [sheet];
+    } else {
+      this.shadowRoot.innerHTML = `
             <style>
                 ${style}
             </style>
-            ${this.renderHTML(this.ref)}
+            ${controlHtml}
         `;
+    }
 
     this.widget = this.getWidget();
+    this._associateLabel();
+    this._associateDescriptions();
 
     this.addEventListener('mousedown', e => {
       // ### prevent mousedown events on all control content that is not the widget or within the widget
@@ -155,6 +164,8 @@ export default class FxControl extends XfAbstractControl {
         listenOn = target;
       }
     }
+    // retained for setValue()'s undo-coalescing focus check (see there)
+    this._listenOn = listenOn;
 
     this.addEventListener('keyup', () => {
       FxModel.dataChanged = true;
@@ -172,6 +183,14 @@ export default class FxControl extends XfAbstractControl {
       });
       this.updateEvent = 'blur'; // needs to be registered too
     }
+    // blur both commits the final value and closes any open undo-coalescing session, so
+    // typing into this field again after leaving it starts a new undo step. Must be a
+    // normal (non-`once`) listener: a field can be focused/blurred more than once.
+    const onBlur = () => {
+      this.setValue(this._getValueOfWidget());
+      this.getModel()?.getEffectiveUndoManager()?.endCoalescingSession();
+    };
+
     if (this.debounceDelay) {
       listenOn.addEventListener(
         this.updateEvent,
@@ -185,6 +204,7 @@ export default class FxControl extends XfAbstractControl {
           this.debounceDelay,
         ),
       );
+      listenOn.addEventListener('blur', onBlur);
     } else {
       listenOn.addEventListener(this.updateEvent, event => {
         if (this._isRefreshing) {
@@ -193,13 +213,7 @@ export default class FxControl extends XfAbstractControl {
         }
         this.setValue(this._getValueOfWidget());
       });
-      listenOn.addEventListener(
-        'blur',
-        event => {
-          this.setValue(this._getValueOfWidget());
-        },
-        { once: true },
-      );
+      listenOn.addEventListener('blur', onBlur);
     }
 
     this.addEventListener('return', e => {
@@ -272,18 +286,61 @@ export default class FxControl extends XfAbstractControl {
       return; // do nothing when modelItem is readonly
     }
 
+    // direct widget edits bypass the action pipeline (no execute()), so undo capture
+    // happens here - unless an action chain is already running and capturing, or the
+    // form is mid-refresh (teardown blurs replay stale widget values; recording those
+    // would clear the redo stack right after an undo)
+    const undoManager = this.getModel()?.getEffectiveUndoManager();
+    const captureUndo =
+      !!undoManager?.enabled &&
+      FxFore.outermostHandler === null &&
+      !this.getOwnerForm()?.isRefreshing;
+    if (captureUndo) undoManager.beginCapture();
+    const undoKey = captureUndo
+      ? Array.isArray(modelitem?.node)
+        ? modelitem.node[0]
+        : modelitem?.node
+      : null;
+    const valueBefore = captureUndo ? modelitem?.value : null;
+    // coalesce only while the widget is genuinely focused - a session opened by a fully
+    // programmatic call (no real focus) would never see a blur to close it, and could
+    // silently absorb an unrelated later edit to the same node. Also coalesce when a
+    // session for this exact node is already open: the blur handler's own setValue() call
+    // fires *after* document.activeElement has already moved away, so without this it
+    // would wrongly split the final keystroke into its own entry instead of merging it
+    // into the session that blur is about to close.
+    const isFocused =
+      captureUndo &&
+      (document.activeElement === this._listenOn || undoManager?.openSession?.key === undoKey);
+    const commitUndo = () => {
+      if (!captureUndo) return;
+      if (modelitem && modelitem.value !== valueBefore) {
+        if (isFocused) {
+          undoManager.commitCoalesced(undoKey);
+        } else {
+          undoManager.commit(undoKey);
+        }
+      } else {
+        undoManager.discard();
+      }
+    };
+
     if (this.getAttribute('as') === 'node') {
       const replace = this.shadowRoot.getElementById('replace');
       replace.replace(this.nodeset, val);
       if (modelitem && val && val !== modelitem.value) {
         modelitem.value = val;
         FxModel.dataChanged = true;
+        commitUndo();
         replace.actionPerformed();
+      } else {
+        commitUndo();
       }
       return;
     }
     const setval = this.shadowRoot.getElementById('setvalue');
     setval.setValue(modelitem, val);
+    commitUndo();
 
     /*
     if (this.modelItem instanceof ModelItem && !this.modelItem?.boundControls.includes(this)) {
@@ -329,6 +386,41 @@ export default class FxControl extends XfAbstractControl {
         `;
   }
 
+  /**
+   * Associates the control's label with its widget.
+   *
+   * Two label mechanisms exist: a light-DOM `<label>` child (slotted alongside the widget, so
+   * both share the same tree and `for`/`id` works), and the `label="..."` attribute (rendered as
+   * bare text into the *shadow root* by `renderHTML()` - a different tree than the light-DOM
+   * widget, so an id reference cannot cross that boundary and `aria-label` (a string, not an id
+   * reference) is used instead).
+   */
+  _associateLabel() {
+    const label = this.querySelector(':scope > label');
+    if (label) {
+      const id = label.getAttribute('for') || this.widget.id || `fx-${Fore.createUUID()}`;
+      if (!label.hasAttribute('for')) label.setAttribute('for', id);
+      if (!this.widget.id) this.widget.id = id;
+      return;
+    }
+    if (this.label) {
+      this.widget.setAttribute('aria-label', this.label);
+    }
+  }
+
+  /**
+   * Wires any statically-authored `<fx-hint>`/`<fx-alert>` light-DOM children into the widget's
+   * aria-describedby, so validation/help text is announced as part of the field's description.
+   * Dynamically-created alerts (from a `<fx-bind>`'s `alert`) are wired separately in
+   * `AbstractControl.handleValid()`.
+   */
+  _associateDescriptions() {
+    this.querySelectorAll(':scope > fx-hint, :scope > fx-alert').forEach(el => {
+      el.id = el.id || `fx-${el.localName}-${Fore.createUUID()}`;
+      this._addDescribedBy(el.id);
+    });
+  }
+
   /**
    * The widget is the actual control being used in the UI e.g. a native input control or any
    * other component that presents a control that can be interacted with.
@@ -551,13 +643,11 @@ export default class FxControl extends XfAbstractControl {
       this.widget = imported;
 
       if (!theFore) {
-        Fore.dispatch('error', {
-          detail: {
-            message: `Fore element not found in '${this.src}'. Maybe wrapped within 'template' element?`,
-          },
+        await Fore.dispatch(this, 'error', {
+          message: `Fore element not found in '${this.src}'. Maybe wrapped within 'template' element?`,
         });
       }
-      Fore.dispatch('loaded', { detail: { fore: theFore } });
+      await Fore.dispatch(this, 'loaded', { fore: theFore });
     } catch (error) {
       // console.log('error', error);
       Fore.dispatch(this, 'error', {
@@ -689,7 +779,7 @@ export default class FxControl extends XfAbstractControl {
     if (dataRefd && dataRefd.closest('fx-control') === this) {
       this.boundList = dataRefd;
       const ref = dataRefd.getAttribute('data-ref');
-      this._handleBoundWidget(dataRefd, true); //todo: revisit !!! observer
+      this._handleBoundWidget(dataRefd, true); // todo: revisit !!! observer
     }
   }
 
@@ -714,23 +804,18 @@ export default class FxControl extends XfAbstractControl {
       const inscope = getInScopeContext(this, ref);
       // const nodeset = evaluateXPathToNodes(ref, inscope, this);
 
-      const touchedNodes = new Set();
-      const domFacade = new DependencyNotifyingDomFacade(node => touchedNodes.add(node));
-
-      const nodeset = evaluateXPath(ref, inscope, this, domFacade);
-
-      const contextNode = Array.isArray(inscope) ? inscope[0] : inscope;
-      // console.log('Extracting model', this.getModel());
-      // console.log('Extracting model inited', this.getModel().inited);
-      const model = this.getModel();
-      if (!contextNode) return;
-      // console.log('Extracting predicate deps from ref:', ref);
-      extractPredicateDependencies(
-        ref,
-        model,
-        mi => mi.addObserver(this),
-        node => model.getModelItem(node),
-      );
+      let touchedNodes = null;
+      let domFacade = null;
+      if (this._refNeedsDependencyTracking(ref)) {
+        touchedNodes = new Set();
+        domFacade = new DependencyNotifyingDomFacade(node => touchedNodes.add(node));
+      }
+
+      const nodeset = evaluateXPath(ref, inscope, this, {}, {}, domFacade);
+
+      if (touchedNodes) {
+        this._trackRefDependencies(touchedNodes, 'widget');
+      }
 
       // ### bail out when nodeset is array and empty
       if (Array.isArray(nodeset) && nodeset.length === 0) return;
@@ -783,6 +868,12 @@ export default class FxControl extends XfAbstractControl {
           this.updateEntry(newEntry, nodeset);
         }
         this.boundInitialized = true;
+
+        // Newly created entries may carry template expressions in attributes that
+        // updateEntry() does not know about (e.g. a `name="{$qno}"` on a generated
+        // radio input). Flag them for scanning on the next fx-fore refresh, the same
+        // way fx-repeat does for newly rendered repeat items.
+        this.getOwnerForm()?.scanForNewTemplateExpressionsNextRefresh();
       }
 
       if (this.valueProp === 'selectedOptions') {
@@ -809,8 +900,7 @@ export default class FxControl extends XfAbstractControl {
     }
 
     const valueExpr = valueAttribute;
-    const cutted = valueExpr.substring(1, valueExpr.length - 1);
-    const evaluated = evaluateXPathToString(cutted, node, this);
+    const evaluated = Fore.evaluateTemplateString(valueExpr, node, this);
     newEntry.setAttribute('value', evaluated);
 
     if (this.value === evaluated) {
@@ -818,10 +908,9 @@ export default class FxControl extends XfAbstractControl {
     }
 
     if (newEntry.hasAttribute('title')) {
-      let titleExpr = newEntry.getAttribute('title');
-      titleExpr = titleExpr.substring(1, titleExpr.length - 1);
-      const evaluated = evaluateXPathToString(titleExpr, node, newEntry);
-      newEntry.setAttribute('title', evaluated);
+      const titleExpr = newEntry.getAttribute('title');
+      const evaluatedTitle = Fore.evaluateTemplateString(titleExpr, node, newEntry);
+      newEntry.setAttribute('title', evaluatedTitle);
     }
     // ### set label
     const optionLabel = newEntry.textContent.trim();
@@ -836,10 +925,10 @@ export default class FxControl extends XfAbstractControl {
    * @param {HTMLElement} newEntry
    */
   evalLabel(optionLabel, node, newEntry) {
-    const labelExpr = optionLabel.trim().substring(1, optionLabel.length - 1);
+    const labelExpr = optionLabel.trim();
     if (!labelExpr) return;
 
-    const label = evaluateXPathToString(labelExpr, node, this);
+    const label = Fore.evaluateTemplateString(labelExpr, node, this);
     newEntry.textContent = label;
   }
 

package/src/ui/fx-dialog.js

@@ -1,5 +1,10 @@
 import { Fore } from '../fore.js';
 
+/**
+ * @deprecated - use the native HTML `<dialog>` element instead, which already provides a
+ * focus trap, `aria-modal`, and Escape-to-close for free. `fx-show`/`fx-hide` work unchanged
+ * against `<dialog>` (see `demo/dialog.html`), so this is a markup-only migration.
+ */
 export class FxDialog extends HTMLElement {
   static get properties() {
     return {

package/src/ui/fx-items.js

@@ -1,4 +1,4 @@
-import { evaluateXPath, evaluateXPathToString, resolveId } from '../xpath-evaluation.js';
+import { resolveId } from '../xpath-evaluation.js';
 import FxControl from './fx-control.js';
 import { Fore } from '../fore.js';
 import { XPathUtil } from '../xpath-util.js';
@@ -119,11 +119,12 @@ export class FxItems extends FxControl {
 
     // ### handle 'label'
     const label = newEntry.querySelector('label');
-    const lblExpr = Fore.getExpression(label.textContent);
 
     // ROOT FIX: JSON lens nodes are objects; do NOT use direct JS property access.
     // Always go through evaluateXPathToString() for JSON too.
-    const lblEvaluated = evaluateXPathToString(lblExpr, node, this);
+    // Use evaluateTemplateString() rather than getExpression() as the label may mix
+    // static text with one or more `{expr}` placeholders (e.g. "foo {name}").
+    const lblEvaluated = Fore.evaluateTemplateString(label.textContent, node, this);
     // console.log('lblEvaluated ', lblEvaluated);
     label.textContent = lblEvaluated;
 
@@ -134,10 +135,9 @@ export class FxItems extends FxControl {
     const input = newEntry.querySelector('[value]');
     // getting expr
     const expr = input.value;
-    const cutted = Fore.getExpression(expr);
 
     // ROOT FIX: same here
-    const evaluated = evaluateXPathToString(cutted, node, this);
+    const evaluated = Fore.evaluateTemplateString(expr, node, this);
     // console.log('evaluated ', lblEvaluated);
 
     // Set both property and attribute so *any* downstream code path works
@@ -158,4 +158,4 @@ export class FxItems extends FxControl {
 
 if (!customElements.get('fx-items')) {
   customElements.define('fx-items', FxItems);
-}
+}

package/src/ui/fx-output.js

@@ -51,17 +51,39 @@ export class FxOutput extends XfAbstractControl {
             </span>
         `;
 
-    this.shadowRoot.innerHTML = `
+    const sheet = Fore.getSharedStyleSheet(style);
+    if (sheet) {
+      this.shadowRoot.innerHTML = outputHtml;
+      this.shadowRoot.adoptedStyleSheets = [sheet];
+    } else {
+      this.shadowRoot.innerHTML = `
             <style>
                 ${style}
             </style>
             ${outputHtml}
         `;
+    }
     // this.widget = this.shadowRoot.querySelector('#widget');
     // this.widget = this.getWidget();
     // console.log('widget ', this.widget);
     this.mediatype = this.hasAttribute('mediatype') ? this.getAttribute('mediatype') : null;
 
+    // The label is a slotted light-DOM element while the widget is a shadow-DOM <span> - an id
+    // reference (for/aria-labelledby) can't cross that boundary, so derive an aria-label string
+    // (which can) from the slotted label's text instead.
+    const labelSlot = this.shadowRoot.querySelector('slot[name="label"]');
+    const applyLabel = () => {
+      const text = this._getLabelText();
+      const valueEl = this.getWidget();
+      if (text) {
+        valueEl.setAttribute('aria-label', text);
+      } else {
+        valueEl.removeAttribute('aria-label');
+      }
+    };
+    labelSlot.addEventListener('slotchange', applyLabel);
+    applyLabel();
+
     /*
     this.addEventListener('slotchange', e => {
       console.log('slotchange ', e);
@@ -103,6 +125,16 @@ export class FxOutput extends XfAbstractControl {
     return valueWrapper;
   }
 
+  _getLabelText() {
+    const labelSlot = this.shadowRoot.querySelector('slot[name="label"]');
+    if (!labelSlot) return '';
+    return labelSlot
+      .assignedNodes({ flatten: true })
+      .map(n => n.textContent)
+      .join('')
+      .trim();
+  }
+
   handleReadonly() {
     // An output is always read-only
     this.setAttribute('readonly', 'readonly');
@@ -138,6 +170,10 @@ export class FxOutput extends XfAbstractControl {
     if (this.mediatype === 'image') {
       const img = document.createElement('img');
       img.setAttribute('src', this.value);
+      // axe/WCAG require the accessible name directly on the <img> - aria-label on the
+      // wrapping #value span (see applyLabel() above) doesn't satisfy that for a descendant
+      // img. Empty alt is still valid (marks it decorative) when no label is given.
+      img.setAttribute('alt', this._getLabelText());
       // Reset the output before adding the image
       this.innerHTML = '';
       valueWrapper.appendChild(img);