@acorex/platform 21.0.0-next.88 → 21.0.0-next.89

package/fesm2022/acorex-platform-core.mjs

@@ -1,9 +1,9 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, inject, Injectable, Directive, computed, Injector, ChangeDetectionStrategy, Component, input, ElementRef, ViewContainerRef, signal, effect, runInInjectionContext, Optional, Inject, NgModule, EventEmitter, HostListener, Output, provideAppInitializer, Pipe } from '@angular/core';
+import { InjectionToken, inject, Injectable, Directive, computed, Injector, ChangeDetectionStrategy, Component, input, ElementRef, ViewContainerRef, signal, effect, runInInjectionContext, Optional, Inject, NgModule, EventEmitter, HostListener, Output, DestroyRef, untracked, provideAppInitializer, Pipe } from '@angular/core';
 import { AXTranslationService, resolveMultiLanguageString } from '@acorex/core/translation';
 import { AXDataSource } from '@acorex/cdk/common';
 import { AXPPlatformCoreDataSourceKeys, AXPSystemActionType } from '@acorex/platform/contracts';
-import { isPlainObject, get, set, isNil, isEmpty, isArray, merge, isObjectLike, transform, isEqual, differenceWith, union, cloneDeep, has, sortBy, isUndefined, endsWith, startsWith, includes, lte, gte, lt, gt, orderBy } from 'lodash-es';
+import { isPlainObject, get, set, isNil, isEmpty, isArray, merge, isObjectLike, transform, isEqual, differenceWith, union, cloneDeep, has, unset, sortBy, isUndefined, endsWith, startsWith, includes, lte, gte, lt, gt, orderBy } from 'lodash-es';
 import { signalStore, withState, withComputed, withMethods, patchState } from '@ngrx/signals';
 import { AXFormatService } from '@acorex/core/format';
 import * as i1 from '@acorex/components/skeleton';
@@ -12,6 +12,7 @@ import { Subject, interval, fromEvent } from 'rxjs';
 import { toSignal } from '@angular/core/rxjs-interop';
 import { DOCUMENT } from '@angular/common';
 import { AXLocaleService } from '@acorex/core/locale';
+import { delay } from '@acorex/core/utils';
 import { AXCalendarService } from '@acorex/core/date-time';
 import { startWith, map, debounceTime } from 'rxjs/operators';
 
@@ -706,6 +707,104 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
             type: Directive
         }] });
 
+//#region ---- Imports ----
+//#endregion
+//#region ---- Debug Service ----
+/**
+ * Platform debug and trace logging.
+ * Call `trace` / `traceGroup` for diagnostics (gated by tenant Debug Mode).
+ * Call `warn` / `error` for always-on console output.
+ *
+ * Debug Mode is applied via `setDebugMode()` (wired from settings in platform common).
+ */
+class AXPDebugService {
+    //#endregion
+    //#region ---- Lifecycle ----
+    constructor() {
+        //#endregion
+        //#region ---- State ----
+        this.debugModeEnabled = false;
+        AXPDebugService.instance = this;
+    }
+    //#endregion
+    //#region ---- Debug Mode ----
+    isDebugMode() {
+        return this.debugModeEnabled;
+    }
+    setDebugMode(enabled) {
+        this.debugModeEnabled = enabled;
+    }
+    //#endregion
+    //#region ---- Trace API ----
+    /**
+     * @param namespace Module/feature namespace (kebab-case). Filter console with `[AXP:<namespace>]`.
+     * @param title Short area name (component, service, middleware).
+     * @param message What happened.
+     * @param data Optional structured payload, or a factory evaluated only when Debug Mode is on.
+     */
+    trace(namespace, title, message, data) {
+        if (!this.debugModeEnabled) {
+            return;
+        }
+        this.log('log', namespace, title, message, data);
+    }
+    /**
+     * Same as {@link trace} but emits a collapsible console group (useful for multi-field payloads).
+     */
+    traceGroup(namespace, title, message, data) {
+        if (!this.debugModeEnabled) {
+            return;
+        }
+        const resolved = this.resolveData(data);
+        console.groupCollapsed(this.formatPrefix(namespace, title, message));
+        if (resolved != null) {
+            for (const [key, value] of Object.entries(resolved)) {
+                if (value !== undefined) {
+                    console.log(key, value);
+                }
+            }
+        }
+        console.groupEnd();
+    }
+    warn(namespace, title, message, data) {
+        this.log('warn', namespace, title, message, data);
+    }
+    error(namespace, title, message, data) {
+        this.log('error', namespace, title, message, data);
+    }
+    //#endregion
+    //#region ---- Utility Methods ----
+    formatPrefix(namespace, title, message) {
+        return `[AXP:${namespace}] ${title} — ${message}`;
+    }
+    resolveData(data) {
+        if (data == null) {
+            return undefined;
+        }
+        return typeof data === 'function' ? data() : data;
+    }
+    log(level, namespace, title, message, data) {
+        const prefix = this.formatPrefix(namespace, title, message);
+        const resolved = this.resolveData(data);
+        if (resolved != null) {
+            console[level](prefix, resolved);
+            return;
+        }
+        console[level](prefix);
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: AXPDebugService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: AXPDebugService, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: AXPDebugService, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root',
+                }]
+        }], ctorParameters: () => [] });
+
+/** Trace namespace for form dirty-state diagnostics (lookup/select revert, discard, baseline). */
+const FORM_DIRTY_TRACE_NS = 'FORM STATE';
+
 //#region ---- Locale map shape ----
 /** Per-locale string map (`{ 'en-US': '...', 'fa-IR': '...' }`). */
 function isLocaleStringMap(value) {
@@ -1028,6 +1127,13 @@ function normalizeLocaleStringMap(value) {
     }
     return Object.keys(normalized).length === 0 ? null : normalized;
 }
+function compareMultiLanguageLocaleStrings(a, b) {
+    const htmlEqual = compareHtmlFormValues(a, b);
+    if (htmlEqual !== null) {
+        return htmlEqual;
+    }
+    return a === b;
+}
 /**
  * Compares multi-language field values (plain string vs locale map) for dirty/baseline checks.
  * Returns `null` when either side is not a multi-language shape (caller uses generic normalization).
@@ -1058,15 +1164,13 @@ function compareMultiLanguageFormValues(a, b) {
         return false;
     }
     if (typeof left === 'string' && typeof right === 'string') {
-        return left === right;
+        return compareMultiLanguageLocaleStrings(left, right);
     }
     if (typeof left === 'string' && typeof right === 'object') {
-        const values = Object.values(right);
-        return values.length > 0 && values.every((text) => text === left);
+        return Object.values(right).some((text) => typeof text === 'string' && compareMultiLanguageLocaleStrings(left, text));
     }
     if (typeof right === 'string' && typeof left === 'object') {
-        const values = Object.values(left);
-        return values.length > 0 && values.every((text) => text === right);
+        return Object.values(left).some((text) => typeof text === 'string' && compareMultiLanguageLocaleStrings(right, text));
     }
     if (typeof left !== 'object' || typeof right !== 'object') {
         return false;
@@ -1078,7 +1182,56 @@ function compareMultiLanguageFormValues(a, b) {
     if (leftKeys.length !== rightKeys.length) {
         return false;
     }
-    return leftKeys.every((key) => leftMap[key] === rightMap[key]);
+    return leftKeys.every((key) => compareMultiLanguageLocaleStrings(leftMap[key], rightMap[key]));
+}
+/**
+ * Lookup/select expose may write a resolved MLS string while the baseline keeps the locale map.
+ * Restore baseline shape when the string matches any locale entry.
+ */
+function shouldRestoreSavedMultiLanguageShape(value, savedAtPath) {
+    if (typeof value !== 'string' || !isLocaleStringMap(savedAtPath)) {
+        return false;
+    }
+    const trimmed = value.trim();
+    if (trimmed === '') {
+        return false;
+    }
+    return Object.values(savedAtPath).some((entry) => typeof entry === 'string' && entry.trim() === trimmed);
+}
+/** Decode common HTML entities for rich-text baseline compare. */
+function decodeHtmlEntities(value) {
+    return value
+        .replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCharCode(parseInt(hex, 16)))
+        .replace(/&#(\d+);/g, (_, dec) => String.fromCharCode(parseInt(dec, 10)))
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"');
+}
+function looksLikeHtmlFormValue(value) {
+    return /<[a-z][\s\S]*>/i.test(value.trim());
+}
+/** Normalizes rich-text HTML for semantic dirty/baseline compare (e.g. Quill `p`/`br` drift). */
+function normalizeRichTextHtmlForCompare(value) {
+    const html = decodeHtmlEntities(value.trim());
+    if (typeof document === 'undefined') {
+        return html.replace(/\s+/g, ' ').trim();
+    }
+    const doc = new DOMParser().parseFromString(html, 'text/html');
+    return (doc.body.textContent ?? '').replace(/\s+/g, ' ').trim();
+}
+/**
+ * Compares rich-text HTML strings by visible text (ignores `p` vs `br` structure drift).
+ * Returns `null` when either side is not HTML markup.
+ */
+function compareHtmlFormValues(a, b) {
+    if (typeof a !== 'string' || typeof b !== 'string') {
+        return null;
+    }
+    if (!looksLikeHtmlFormValue(a) || !looksLikeHtmlFormValue(b)) {
+        return null;
+    }
+    return normalizeRichTextHtmlForCompare(a) === normalizeRichTextHtmlForCompare(b);
 }
 /** Lookup/select filter-mode payload: `{ value, displayText?, operation }`. */
 function isFilterFormShape(value) {
@@ -1286,6 +1439,12 @@ function isFormValueEqual(a, b) {
         }
         return true;
     }
+    if (typeof a === 'string' && typeof b === 'string') {
+        const htmlEqual = compareHtmlFormValues(a, b);
+        if (htmlEqual !== null) {
+            return htmlEqual;
+        }
+    }
     return isEqual(normalizeFormValue(a), normalizeFormValue(b));
 }
 /**
@@ -1294,6 +1453,45 @@ function isFormValueEqual(a, b) {
 function isFormContextDirty(current, baseline) {
     return !isFormValueEqual(current, baseline);
 }
+/**
+ * Lists paths where live context differs from baseline (for dirty-state trace logs).
+ */
+function summarizeFormContextDirtyDiff(current, baseline, maxEntries = 12) {
+    const diffs = [];
+    const walk = (path, currentValue, baselineValue) => {
+        if (diffs.length >= maxEntries) {
+            return;
+        }
+        if (isFormValueEqual(currentValue, baselineValue)) {
+            return;
+        }
+        const bothPlainObjects = isPlainObject(currentValue) &&
+            isPlainObject(baselineValue) &&
+            !isArray(currentValue) &&
+            !isArray(baselineValue);
+        if (bothPlainObjects) {
+            const left = currentValue;
+            const right = baselineValue;
+            const keys = new Set([...Object.keys(left), ...Object.keys(right)]);
+            for (const key of keys) {
+                if (diffs.length >= maxEntries) {
+                    return;
+                }
+                const nextPath = path ? `${path}.${key}` : key;
+                walk(nextPath, left[key], right[key]);
+            }
+            return;
+        }
+        diffs.push({
+            path: path || '(root)',
+            current: currentValue,
+            baseline: baselineValue,
+            selectionEqual: isSelectionValueEqual(currentValue, baselineValue),
+        });
+    };
+    walk('', current, baseline);
+    return diffs;
+}
 /**
  * Clones a context object for use as a dirty-tracking baseline.
  */
@@ -1312,20 +1510,26 @@ const AXPContextStore = signalStore(withState(() => ({
     /** Last committed / saved baseline — discard reverts to this snapshot. */
     savedSnapshot: {},
     previousSnapshot: {},
+    /** True after a user-origin update since the last {@link commitSaved}. */
+    userEditedSinceCommit: false,
     lastChange: {
         state: 'initiated',
     },
-})), withComputed(({ data, state, lastChange, savedSnapshot, previousSnapshot }) => ({
+})), withComputed(({ data, state, lastChange, savedSnapshot, previousSnapshot, userEditedSinceCommit }) => ({
     isChanged: computed(() => state() === 'changed'),
     isReset: computed(() => state() === 'restored'),
     isInitiated: computed(() => state() === 'initiated'),
     isEmpty: computed(() => Object.keys(data()).length === 0),
     isSavedCommitted: computed(() => !isEmpty(savedSnapshot())),
+    hasUserEditedSinceCommit: computed(() => userEditedSinceCommit()),
     isDirty: computed(() => {
         const saved = savedSnapshot();
         if (isEmpty(saved)) {
             return false;
         }
+        if (!userEditedSinceCommit()) {
+            return false;
+        }
         return isFormContextDirty(data(), saved);
     }),
     snapshot: computed(() => cloneDeep(data())),
@@ -1335,24 +1539,80 @@ const AXPContextStore = signalStore(withState(() => ({
     previous: computed(() => cloneDeep(previousSnapshot())),
     changeEvent: computed(() => lastChange()),
 })), withMethods((store) => {
+    const traceDirty = (title, message, data) => {
+        AXPDebugService.instance?.trace(FORM_DIRTY_TRACE_NS, title, message, data);
+    };
+    const traceDirtyState = (reason, data, path) => {
+        const saved = store.savedSnapshot();
+        const current = store.data();
+        const hasSaved = !isEmpty(saved);
+        const contextDirty = hasSaved && isFormContextDirty(current, saved);
+        traceDirty('context-store', reason, () => ({
+            path,
+            userEditedSinceCommit: store.userEditedSinceCommit(),
+            isSavedCommitted: hasSaved,
+            isFormContextDirty: contextDirty,
+            isDirty: store.isDirty(),
+            ...(hasSaved
+                ? {
+                    dirtyPaths: contextDirty ? summarizeFormContextDirtyDiff(current, saved) : [],
+                }
+                : {}),
+            ...data,
+        }));
+    };
     const updateValue = (path, value, options) => {
         const currentData = cloneDeep(store.data());
         const oldValue = getSmart(currentData, path);
         const hasSaved = !isEmpty(store.savedSnapshot());
-        const savedAtPath = hasSaved ? getSmart(store.savedSnapshot(), path) : undefined;
+        const saved = store.savedSnapshot();
+        const savedAtPath = hasSaved ? getSmart(saved, path) : undefined;
+        const origin = options?.origin ?? 'system';
         if (hasSaved && isSelectionValueEqual(value, savedAtPath) && !isEqual(value, savedAtPath)) {
             value = cloneDeep(savedAtPath);
         }
+        if (hasSaved && !isEqual(value, savedAtPath) && isFormValueEqual(value, savedAtPath)) {
+            value = cloneDeep(savedAtPath);
+        }
         const isArrayLengthChange = Array.isArray(value) && (!Array.isArray(oldValue) || value.length !== oldValue.length);
-        if (!isArrayLengthChange && isEqual(oldValue, value)) {
+        /** Same selection id as baseline but different object shape (lookup/select item vs scalar). */
+        const needsSavedShapeRestore = hasSaved && isSelectionValueEqual(value, savedAtPath) && !isFormValueEqual(value, savedAtPath);
+        if (!isArrayLengthChange && isEqual(oldValue, value) && !needsSavedShapeRestore) {
+            traceDirty('context-store', 'updateValue skipped (lodash isEqual)', () => ({
+                path,
+                origin,
+                oldValue,
+                value,
+                needsSavedShapeRestore,
+                selectionEqualToSaved: hasSaved ? isSelectionValueEqual(value, savedAtPath) : null,
+                savedAtPath,
+            }));
             return;
         }
         const shouldNormalizeSavedShape = hasSaved && isSelectionValueEqual(value, savedAtPath) && !isEqual(oldValue, value);
-        if (!isArrayLengthChange && isFormValueEqual(oldValue, value) && !shouldNormalizeSavedShape) {
+        if (!isArrayLengthChange &&
+            isFormValueEqual(oldValue, value) &&
+            !shouldNormalizeSavedShape &&
+            !needsSavedShapeRestore) {
+            traceDirty('context-store', 'updateValue skipped (isFormValueEqual)', () => ({
+                path,
+                origin,
+                oldValue,
+                value,
+                needsSavedShapeRestore,
+                shouldNormalizeSavedShape,
+                selectionEqualToSaved: hasSaved ? isSelectionValueEqual(value, savedAtPath) : null,
+                savedAtPath,
+            }));
             return;
         }
-        const origin = options?.origin ?? 'system';
         const updatedData = setSmart(currentData, path, value);
+        const isStillDirty = hasSaved && isFormContextDirty(updatedData, saved);
+        const nextUserEdited = isStillDirty
+            ? origin === 'user'
+                ? true
+                : store.userEditedSinceCommit()
+            : false;
         const changeEvent = {
             oldValue,
             newValue: value,
@@ -1366,7 +1626,22 @@ const AXPContextStore = signalStore(withState(() => ({
             data: updatedData,
             state: 'changed',
             lastChange: changeEvent,
+            userEditedSinceCommit: nextUserEdited,
         });
+        traceDirty('context-store', 'updateValue applied', () => ({
+            path,
+            origin,
+            oldValue,
+            newValue: value,
+            savedAtPath,
+            selectionEqualToSaved: hasSaved ? isSelectionValueEqual(value, savedAtPath) : null,
+            formValueEqualToSaved: hasSaved ? isFormValueEqual(value, savedAtPath) : null,
+            needsSavedShapeRestore,
+            isStillDirty,
+            nextUserEdited,
+            isDirty: !isEmpty(saved) && nextUserEdited && isStillDirty,
+            dirtyPaths: isStillDirty ? summarizeFormContextDirtyDiff(updatedData, saved) : [],
+        }));
     };
     const applyObjectPaths = (obj, options, prefix = '') => {
         for (const [key, value] of Object.entries(obj ?? {})) {
@@ -1379,6 +1654,57 @@ const AXPContextStore = signalStore(withState(() => ({
             }
         }
     };
+    const removePathFromContext = (path, origin = 'system') => {
+        const currentData = cloneDeep(store.data());
+        if (!has(currentData, path)) {
+            return;
+        }
+        unset(currentData, path);
+        const parts = path.split('.');
+        for (let i = parts.length - 1; i > 0; i--) {
+            const parentPath = parts.slice(0, i).join('.');
+            const parentObj = getSmart(currentData, parentPath);
+            if (isPlainObject(parentObj) && isEmpty(Object.keys(parentObj))) {
+                unset(currentData, parentPath);
+            }
+        }
+        const saved = store.savedSnapshot();
+        const isStillDirty = !isEmpty(saved) && isFormContextDirty(currentData, saved);
+        patchState(store, {
+            previousSnapshot: store.snapshot(),
+            data: currentData,
+            state: 'changed',
+            lastChange: {
+                path,
+                state: 'changed',
+                data: currentData,
+                origin,
+            },
+            userEditedSinceCommit: isStillDirty
+                ? origin === 'user'
+                    ? true
+                    : store.userEditedSinceCommit()
+                : false,
+        });
+        traceDirty('context-store', 'removePathFromContext', () => ({
+            path,
+            origin,
+            isStillDirty,
+            dirtyPaths: isStillDirty ? summarizeFormContextDirtyDiff(currentData, saved) : [],
+        }));
+    };
+    const syncPathToSavedBaseline = (path, options) => {
+        const saved = store.savedSnapshot();
+        if (isEmpty(saved)) {
+            return;
+        }
+        const origin = options?.origin ?? 'system';
+        if (has(saved, path)) {
+            updateValue(path, cloneDeep(getSmart(saved, path)), { origin });
+            return;
+        }
+        removePathFromContext(path, origin);
+    };
     const revertToSaved = () => {
         const savedData = store.saved();
         const changeEvent = {
@@ -1393,13 +1719,17 @@ const AXPContextStore = signalStore(withState(() => ({
             data: savedData,
             state: 'restored',
             lastChange: changeEvent,
+            userEditedSinceCommit: false,
         });
+        traceDirtyState('revertToSaved');
     };
     return {
         update(path, value, options) {
             updateValue(path, value, options);
         },
         applyObjectPaths,
+        /** Aligns a context path with the saved baseline (restore value or remove if absent). */
+        syncPathToSavedBaseline,
         patch(context, options) {
             const currentData = cloneDeep(store.data());
             const updatedData = { ...currentData, ...context };
@@ -1440,6 +1770,7 @@ const AXPContextStore = signalStore(withState(() => ({
                 data: initialData,
                 state: 'initiated',
                 lastChange: changeEvent,
+                userEditedSinceCommit: false,
             });
         },
         getValue(path) {
@@ -1458,11 +1789,13 @@ const AXPContextStore = signalStore(withState(() => ({
                 savedSnapshot: snapshot,
                 previousSnapshot: snapshot,
                 state: 'initiated',
+                userEditedSinceCommit: false,
                 lastChange: {
                     state: 'initiated',
                     data: snapshot,
                 },
             });
+            traceDirtyState('commitSaved');
         },
         /** Merges parent-bound entity fields without resetting the saved baseline. */
         applyParentBind(merged) {
@@ -2826,12 +3159,12 @@ const HORIZONTAL_DIRECTIONAL_KEY_MIRRORS = {
 };
 /** Maps a horizontal direction key to its RTL semantic counterpart. */
 function mirrorHorizontalDirectionalKey(key) {
-    const normalized = normalizeShortcutToken(key);
+    const normalized = normalizeShortcutToken$1(key);
     return HORIZONTAL_DIRECTIONAL_KEY_MIRRORS[normalized] ?? normalized;
 }
 /** True when the chord's primary key is a horizontal direction key (`←`/`→`, `[`/`]`). */
 function isHorizontalDirectionalShortcutKey(key) {
-    return normalizeShortcutToken(key) in HORIZONTAL_DIRECTIONAL_KEY_MIRRORS;
+    return normalizeShortcutToken$1(key) in HORIZONTAL_DIRECTIONAL_KEY_MIRRORS;
 }
 /**
  * Resolves direction behavior for a chord.
@@ -2847,7 +3180,7 @@ function resolveEffectiveDirectionBehavior(chord, explicit) {
 }
 /** Resolves the key the user presses for a semantically registered chord in RTL. */
 function resolveSemanticDirectionalKey(storedKey, rtl) {
-    const normalized = normalizeShortcutToken(storedKey);
+    const normalized = normalizeShortcutToken$1(storedKey);
     if (!rtl) {
         return normalized;
     }
@@ -2914,7 +3247,7 @@ function parseKeyboardShortcutChord(chord) {
         .split('+')
         .map((part) => part.trim())
         .filter(Boolean);
-    const key = normalizeShortcutToken(parts.pop() ?? '');
+    const key = normalizeShortcutToken$1(parts.pop() ?? '');
     const parsed = {
         ctrl: false,
         shift: false,
@@ -2942,7 +3275,7 @@ function matchesKeyboardShortcutChord(event, chord, options) {
         return false;
     }
     const actualKey = normalizeShortcutEventKey(event);
-    const expectedKey = normalizeShortcutToken(parsed.key);
+    const expectedKey = normalizeShortcutToken$1(parsed.key);
     const rtlSemantic = directionBehavior === 'semantic' &&
         options?.isRtl === true &&
         isHorizontalDirectionalShortcutKey(expectedKey);
@@ -3006,7 +3339,7 @@ function formatKeyboardShortcutChord(chord, options) {
     if (parts.length === 0) {
         return '';
     }
-    const keyPart = normalizeShortcutToken(parts.pop() ?? '');
+    const keyPart = normalizeShortcutToken$1(parts.pop() ?? '');
     const modifierParts = parts.map((part) => formatShortcutPart(part.toLowerCase(), mac));
     const keyDisplay = formatShortcutPart(keyPart, mac);
     if (mac) {
@@ -3100,7 +3433,7 @@ function isMacPlatform() {
     }
     return /Mac|iPhone|iPad|iPod/i.test(navigator.userAgent);
 }
-function normalizeShortcutToken(key) {
+function normalizeShortcutToken$1(key) {
     const normalized = key.trim().toLowerCase();
     if (normalized === 'esc') {
         return 'escape';
@@ -3162,7 +3495,7 @@ function normalizeShortcutEventKey(event) {
     return event.key.toLowerCase();
 }
 function formatShortcutPart(part, mac) {
-    const normalized = normalizeShortcutToken(part);
+    const normalized = normalizeShortcutToken$1(part);
     if (mac && KEY_DISPLAY_MAC[normalized]) {
         return KEY_DISPLAY_MAC[normalized];
     }
@@ -3439,6 +3772,271 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                 }]
         }] });
 
+//#region ---- Dialog Action Shortcut Utilities ----
+const DEFAULT_CANCEL_DIALOG_ACTION_SHORTCUTS = ['Esc'];
+const DEFAULT_SUBMIT_DIALOG_ACTION_SHORTCUTS = ['Enter', 'ctrl+s'];
+const PRIMARY_DIALOG_ACTION_COMMANDS = new Set([
+    'submit',
+    'create',
+    'apply',
+    'save',
+    'select',
+    'entity-form-done',
+    'upload-image',
+]);
+/**
+ * Parses a shortcut string such as `Enter`, `Escape`, or `ctrl+shift+s`.
+ */
+function parseDialogActionShortcut(shortcut) {
+    const parts = shortcut
+        .trim()
+        .toLowerCase()
+        .split('+')
+        .map((part) => part.trim())
+        .filter(Boolean);
+    const key = normalizeShortcutToken(parts.pop() ?? '');
+    return {
+        ctrl: parts.includes('ctrl') || parts.includes('control'),
+        shift: parts.includes('shift'),
+        alt: parts.includes('alt') || parts.includes('option'),
+        meta: parts.includes('meta') || parts.includes('cmd') || parts.includes('command'),
+        key,
+    };
+}
+/**
+ * Returns true when the keyboard event matches the given shortcut definition.
+ */
+function matchesDialogActionShortcut(event, shortcut) {
+    const parsed = parseDialogActionShortcut(shortcut);
+    if (parsed.ctrl !== event.ctrlKey) {
+        return false;
+    }
+    if (parsed.shift !== event.shiftKey) {
+        return false;
+    }
+    if (parsed.alt !== event.altKey) {
+        return false;
+    }
+    if (parsed.meta !== event.metaKey) {
+        return false;
+    }
+    return normalizeShortcutKey(event) === normalizeShortcutToken(parsed.key);
+}
+/**
+ * Resolves footer action shortcuts: defaults when omitted, merge when extras are provided, none when `[]`.
+ */
+function resolveDialogActionShortcuts(defaults, overrides) {
+    if (overrides !== undefined) {
+        if (overrides.length === 0) {
+            return undefined;
+        }
+        return flattenDialogActionShortcutChords([...defaults, ...overrides]);
+    }
+    return flattenDialogActionShortcutChords(defaults);
+}
+/**
+ * Applies built-in footer shortcuts when actions are declared without `shortcuts`
+ * (e.g. workflow `show-layout-popup` raw action config).
+ */
+function resolveConfiguredFooterActionShortcuts(command, explicit) {
+    if (explicit !== undefined) {
+        return resolveDialogActionShortcuts([], explicit);
+    }
+    if (command === 'cancel') {
+        return resolveDialogActionShortcuts(DEFAULT_CANCEL_DIALOG_ACTION_SHORTCUTS, undefined);
+    }
+    if (command && PRIMARY_DIALOG_ACTION_COMMANDS.has(command)) {
+        return resolveDialogActionShortcuts(DEFAULT_SUBMIT_DIALOG_ACTION_SHORTCUTS, undefined);
+    }
+    return undefined;
+}
+function flattenDialogActionShortcutChords(shortcuts) {
+    const chords = normalizeKeyboardShortcuts(shortcuts).flatMap((shortcut) => shortcut.keys);
+    const deduped = dedupeDialogActionShortcuts(chords);
+    return deduped.length ? deduped : undefined;
+}
+function dedupeDialogActionShortcuts(shortcuts) {
+    const seen = new Set();
+    const result = [];
+    for (const shortcut of shortcuts) {
+        const token = normalizeShortcutToken(shortcut);
+        if (!token || seen.has(token)) {
+            continue;
+        }
+        seen.add(token);
+        result.push(shortcut.trim());
+    }
+    return result;
+}
+function normalizeShortcutToken(key) {
+    const normalized = key.trim().toLowerCase();
+    if (normalized === 'esc') {
+        return 'escape';
+    }
+    return normalized;
+}
+/**
+ * Whether a dialog footer shortcut may fire while focus is inside an editable field.
+ */
+function isDialogShortcutAllowedInEditableField(shortcut) {
+    const parsed = parseDialogActionShortcut(shortcut);
+    const isPlainEnter = parsed.key === 'enter' && !parsed.ctrl && !parsed.shift && !parsed.alt && !parsed.meta;
+    return !isPlainEnter;
+}
+/**
+ * Normalizes dialog footer chord strings for {@link AXPKeyboardShortcutRegistry} (`Esc` → `escape`).
+ */
+function normalizeDialogActionShortcutChord(shortcut) {
+    const parts = shortcut
+        .trim()
+        .split('+')
+        .map((part) => part.trim())
+        .filter(Boolean);
+    if (parts.length === 0) {
+        return shortcut.trim();
+    }
+    const key = normalizeShortcutToken(parts.pop() ?? '');
+    const modifiers = parts.map((part) => part.toLowerCase());
+    return modifiers.length ? `${modifiers.join('+')}+${key}` : key;
+}
+/**
+ * Whether a shortcut should fire given the current focus target.
+ * Enter without modifiers is suppressed in multiline / rich-text fields.
+ */
+function shouldTriggerDialogActionShortcut(event, shortcut) {
+    const parsed = parseDialogActionShortcut(shortcut);
+    const isPlainEnter = parsed.key === 'enter' && !parsed.ctrl && !parsed.shift && !parsed.alt && !parsed.meta;
+    if (!isPlainEnter) {
+        return true;
+    }
+    return !isKeyboardTargetMultilineEditable(event.target);
+}
+function normalizeShortcutKey(event) {
+    if (event.key === 'Enter') {
+        return 'enter';
+    }
+    if (event.key === 'Escape') {
+        return 'escape';
+    }
+    if (event.key === ' ') {
+        return 'space';
+    }
+    if (event.key.length === 1) {
+        return event.key.toLowerCase();
+    }
+    const codeMatch = event.code.match(/^Key([A-Z])$/);
+    if (codeMatch) {
+        return codeMatch[1].toLowerCase();
+    }
+    const digitMatch = event.code.match(/^Digit([0-9])$/);
+    if (digitMatch) {
+        return digitMatch[1];
+    }
+    return event.key.toLowerCase();
+}
+function isKeyboardTargetMultilineEditable(target) {
+    if (!(target instanceof HTMLElement)) {
+        return false;
+    }
+    if (target.isContentEditable) {
+        return true;
+    }
+    const textarea = target.closest('textarea');
+    if (textarea && !textarea.readOnly && !textarea.disabled) {
+        return true;
+    }
+    const richText = target.closest('[contenteditable="true"]');
+    return richText instanceof HTMLElement;
+}
+//#endregion
+
+//#region ---- Popup Footer Keyboard Shortcuts ----
+/**
+ * Registers popup footer shortcuts at modal priority so they win over page bindings and stop bubbling.
+ */
+function registerPopupFooterKeyboardShortcuts(options) {
+    const group = '@general:keyboard-shortcuts.groups.dialog';
+    const scope = options.scope ?? group;
+    const shortcuts = [];
+    for (const action of options.actions) {
+        if (action.hidden?.()) {
+            continue;
+        }
+        const chords = action.shortcuts !== undefined
+            ? resolveConfiguredFooterActionShortcuts(action.command, action.shortcuts)
+            : resolveConfiguredFooterActionShortcuts(action.command, undefined);
+        if (!chords?.length) {
+            continue;
+        }
+        for (const shortcut of chords) {
+            shortcuts.push({
+                keys: [normalizeDialogActionShortcutChord(shortcut)],
+                title: action.title,
+                group,
+                allowInEditableFields: isDialogShortcutAllowedInEditableField(shortcut),
+                when: () => {
+                    if (options.when && !options.when()) {
+                        return false;
+                    }
+                    if (action.hidden?.()) {
+                        return false;
+                    }
+                    if (action.disabled?.()) {
+                        return false;
+                    }
+                    return true;
+                },
+                handler: () => {
+                    void action.handler();
+                },
+            });
+        }
+    }
+    options.registry.register({
+        owner: options.owner,
+        elementRef: options.elementRef,
+        id: options.id,
+        priority: AXPKeyboardShortcutPriority.Modal,
+        scope,
+        when: options.when,
+        shortcuts,
+    });
+}
+/**
+ * Binds footer shortcuts for AXPopupService-hosted components. Call from the popup constructor.
+ */
+function setupPopupFooterKeyboardShortcuts(getActions, config) {
+    const destroyRef = inject(DestroyRef);
+    const elementRef = inject(ElementRef);
+    const registry = inject(AXPKeyboardShortcutRegistry);
+    const id = config?.id ?? 'popup-footer';
+    effect(() => {
+        getActions();
+        config?.when?.();
+        untracked(() => {
+            registerPopupFooterKeyboardShortcuts({
+                registry,
+                owner: destroyRef,
+                elementRef,
+                id,
+                scope: config?.scope,
+                when: config?.when,
+                actions: getActions(),
+            });
+        });
+    });
+}
+//#endregion
+
+/** Global overlay flag + task count ({@link AXPLayoutThemeService}). */
+const OVERLAY_LAYOUT_TRACE_NS = 'OVERLAY-LAYOUT';
+/** Root shell loading dialog sync ({@link AXPRootLayoutComponent}). */
+const OVERLAY_ROOT_LAYOUT_TRACE_NS = 'OVERLAY-ROOT-LAYOUT';
+/** Details view page load and overlay release orchestration. */
+const OVERLAY_DETAILS_VIEW_TRACE_NS = 'OVERLAY-DETAILS-VIEW';
+/** Widget tree mount / settle polling ({@link AXPWidgetContainerComponent}). */
+const OVERLAY_WIDGET_SETTLE_TRACE_NS = 'OVERLAY-WIDGET-SETTLE';
+
 //#region ----   Imports   ----
 //#endregion
 
@@ -3932,7 +4530,7 @@ class AXPIdleSchedulerService {
         const timeoutMs = options?.timeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
         const minIdleMs = options?.minIdleMs ?? DEFAULT_MIN_IDLE_MS;
         if (this.pausedState() || typeof document !== 'undefined' && document.visibilityState === 'hidden') {
-            return this.delay(timeoutMs);
+            return delay(timeoutMs);
         }
         return new Promise((resolve) => {
             let settled = false;
@@ -3992,9 +4590,6 @@ class AXPIdleSchedulerService {
             }
         }
     }
-    delay(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
-    }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: AXPIdleSchedulerService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
     static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: AXPIdleSchedulerService, providedIn: 'root' }); }
 }
@@ -5821,5 +6416,5 @@ function generateKebabCase(title) {
  * Generated bundle index. Do not edit.
  */
 
-export { AXHighlightService, AXPActivityLogProvider, AXPActivityLogService, AXPAppStartUpProvider, AXPAppStartUpService, AXPBroadcastEventService, AXPCatalogScopeDefinitionProviderService, AXPCatalogScopeDefinitionsDataSourceDefinition, AXPColorPaletteProvider, AXPColorPaletteService, AXPColumnWidthService, AXPComponentLogoConfig, AXPComponentSlot, AXPComponentSlotDirective, AXPComponentSlotModule, AXPComponentSlotRegistryService, AXPContentCheckerDirective, AXPContextChangeEvent, AXPContextDefinitionProviderService, AXPContextEvalFactory, AXPContextStore, AXPCountdownPipe, AXPDataGenerator, AXPDataSourceDefinitionProviderService, AXPDblClickDirective, AXPDefaultColorPalettesProvider, AXPDeviceService, AXPDeviceType, AXPDistributedEventListenerService, AXPElementDataDirective, AXPExpressionEvaluatorScopeProviderContext, AXPExpressionEvaluatorScopeProviderService, AXPExpressionEvaluatorService, AXPFeatureDefinitionProviderContext, AXPGridLayoutDirective, AXPHookService, AXPIconLogoConfig, AXPIdleSchedulerService, AXPImageUrlLogoConfig, AXPKeyboardShortcutPriority, AXPKeyboardShortcutRegistry, AXPModuleManifestModule, AXPModuleManifestRegistry, AXPModuleManifestsDataSourceDefinition, AXPScreenSize, AXPSystemActions, AXPTagProvider, AXPTagService, AXP_ACTIVITY_LOG_PROVIDER, AXP_CATALOG_SCOPE_DEFINITION_PROVIDER, AXP_COLOR_PALETTE_PROVIDER, AXP_COLUMN_WIDTH_PROVIDER, AXP_CONTEXT_DEFINITION_PROVIDER, AXP_DATASOURCE_DEFINITION_PROVIDER, AXP_DISTRIBUTED_EVENT_LISTENER_PROVIDER, AXP_EXPRESSION_EVALUATOR_SCOPE_PROVIDER, AXP_FEATURE_DEFINITION_PROVIDER, AXP_MODULE_MANIFEST_PROVIDER, AXP_SESSION_SERVICE, AXP_TAG_PROVIDER, AX_OVERLAY_CONTAINER_SELECTOR, AX_OVERLAY_PANE_SELECTOR, applyContextEvalPipes, applyFilterArray, applyPagination, applyQueryArray, applySortArray, applySystemActionDefault, buildLocaleTextMapValue, captureFormContextBaseline, chordToKbdItemKeys, cleanDeep, coerceUnknownToBoolean, coerceUnknownToDate, coerceUnknownToFiniteNumber, coerceUnknownToTrimmedString, compareMultiLanguageStrings, containsHtmlMarkup, contextEvalWithPipes, createProviderWithInjectionContext, defaultColumnWidthProvider, extractNestedFieldsWildcard, extractTextFromHtml, extractValue, findOverlayContainerAncestor, formatKeyboardShortcutChord, formatKeyboardShortcutChords, generateKebabCase, getActionButton, getChangedPaths, getDetailedChanges, getEnumValues, getNestedVisibleOverlayPanes, getPrimaryKeyboardShortcutChord, getSmart, getSystemActions, getTopVisibleOverlayContainer, getVisibleAnchoredOverlayPanes, getVisibleOverlayContainers, hasForegroundOverlayLayer, isFormContextDirty, isFormValueEqual, isHorizontalDirectionalShortcutKey, isKeyboardTargetInsideEditableField, isLocaleStringMap, isMacPlatform, isSelectionValueEqual, isVisibleOverlayElement, matchesKeyboardShortcutChord, mirrorHorizontalDirectionalKey, normalizeContextEvalPipes, normalizeExpressionTemplate, normalizeKeyboardShortcut, normalizeKeyboardShortcuts, objectKeyValueTransforms, parseKeyboardShortcutChord, provideLazyProvider, resolveActionLook, resolveDisplayShortcutChord, resolveEffectiveDirectionBehavior, resolveSemanticDirectionalKey, searchInMultiLanguageString, setSmart, shouldDeferEscapeToOpenOverlay, shouldUseLocaleMapShape, sortByMultiLanguageString, unwrapValueProperty };
+export { AXHighlightService, AXPActivityLogProvider, AXPActivityLogService, AXPAppStartUpProvider, AXPAppStartUpService, AXPBroadcastEventService, AXPCatalogScopeDefinitionProviderService, AXPCatalogScopeDefinitionsDataSourceDefinition, AXPColorPaletteProvider, AXPColorPaletteService, AXPColumnWidthService, AXPComponentLogoConfig, AXPComponentSlot, AXPComponentSlotDirective, AXPComponentSlotModule, AXPComponentSlotRegistryService, AXPContentCheckerDirective, AXPContextChangeEvent, AXPContextDefinitionProviderService, AXPContextEvalFactory, AXPContextStore, AXPCountdownPipe, AXPDataGenerator, AXPDataSourceDefinitionProviderService, AXPDblClickDirective, AXPDebugService, AXPDefaultColorPalettesProvider, AXPDeviceService, AXPDeviceType, AXPDistributedEventListenerService, AXPElementDataDirective, AXPExpressionEvaluatorScopeProviderContext, AXPExpressionEvaluatorScopeProviderService, AXPExpressionEvaluatorService, AXPFeatureDefinitionProviderContext, AXPGridLayoutDirective, AXPHookService, AXPIconLogoConfig, AXPIdleSchedulerService, AXPImageUrlLogoConfig, AXPKeyboardShortcutPriority, AXPKeyboardShortcutRegistry, AXPModuleManifestModule, AXPModuleManifestRegistry, AXPModuleManifestsDataSourceDefinition, AXPScreenSize, AXPSystemActions, AXPTagProvider, AXPTagService, AXP_ACTIVITY_LOG_PROVIDER, AXP_CATALOG_SCOPE_DEFINITION_PROVIDER, AXP_COLOR_PALETTE_PROVIDER, AXP_COLUMN_WIDTH_PROVIDER, AXP_CONTEXT_DEFINITION_PROVIDER, AXP_DATASOURCE_DEFINITION_PROVIDER, AXP_DISTRIBUTED_EVENT_LISTENER_PROVIDER, AXP_EXPRESSION_EVALUATOR_SCOPE_PROVIDER, AXP_FEATURE_DEFINITION_PROVIDER, AXP_MODULE_MANIFEST_PROVIDER, AXP_SESSION_SERVICE, AXP_TAG_PROVIDER, AX_OVERLAY_CONTAINER_SELECTOR, AX_OVERLAY_PANE_SELECTOR, DEFAULT_CANCEL_DIALOG_ACTION_SHORTCUTS, DEFAULT_SUBMIT_DIALOG_ACTION_SHORTCUTS, FORM_DIRTY_TRACE_NS, OVERLAY_DETAILS_VIEW_TRACE_NS, OVERLAY_LAYOUT_TRACE_NS, OVERLAY_ROOT_LAYOUT_TRACE_NS, OVERLAY_WIDGET_SETTLE_TRACE_NS, applyContextEvalPipes, applyFilterArray, applyPagination, applyQueryArray, applySortArray, applySystemActionDefault, buildLocaleTextMapValue, captureFormContextBaseline, chordToKbdItemKeys, cleanDeep, coerceUnknownToBoolean, coerceUnknownToDate, coerceUnknownToFiniteNumber, coerceUnknownToTrimmedString, compareMultiLanguageStrings, containsHtmlMarkup, contextEvalWithPipes, createProviderWithInjectionContext, defaultColumnWidthProvider, extractNestedFieldsWildcard, extractTextFromHtml, extractValue, findOverlayContainerAncestor, formatKeyboardShortcutChord, formatKeyboardShortcutChords, generateKebabCase, getActionButton, getChangedPaths, getDetailedChanges, getEnumValues, getNestedVisibleOverlayPanes, getPrimaryKeyboardShortcutChord, getSmart, getSystemActions, getTopVisibleOverlayContainer, getVisibleAnchoredOverlayPanes, getVisibleOverlayContainers, hasForegroundOverlayLayer, isDialogShortcutAllowedInEditableField, isFormContextDirty, isFormValueEqual, isHorizontalDirectionalShortcutKey, isKeyboardTargetInsideEditableField, isLocaleStringMap, isMacPlatform, isSelectionValueEqual, isVisibleOverlayElement, matchesDialogActionShortcut, matchesKeyboardShortcutChord, mirrorHorizontalDirectionalKey, normalizeContextEvalPipes, normalizeDialogActionShortcutChord, normalizeExpressionTemplate, normalizeKeyboardShortcut, normalizeKeyboardShortcuts, objectKeyValueTransforms, parseDialogActionShortcut, parseKeyboardShortcutChord, provideLazyProvider, registerPopupFooterKeyboardShortcuts, resolveActionLook, resolveConfiguredFooterActionShortcuts, resolveDialogActionShortcuts, resolveDisplayShortcutChord, resolveEffectiveDirectionBehavior, resolveSemanticDirectionalKey, searchInMultiLanguageString, setSmart, setupPopupFooterKeyboardShortcuts, shouldDeferEscapeToOpenOverlay, shouldRestoreSavedMultiLanguageShape, shouldTriggerDialogActionShortcut, shouldUseLocaleMapShape, sortByMultiLanguageString, summarizeFormContextDirtyDiff, unwrapValueProperty };
 //# sourceMappingURL=acorex-platform-core.mjs.map