@acorex/platform 21.0.0-next.70 → 21.0.0-next.72

package/fesm2022/acorex-platform-core.mjs

@@ -1,12 +1,15 @@
 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 { get, isPlainObject, 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 { AXTranslationService, resolveMultiLanguageString } from '@acorex/core/translation';
+import { AXDataSource } from '@acorex/cdk/common';
+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 { signalStore, withState, withComputed, withMethods, patchState } from '@ngrx/signals';
 import * as i1 from '@acorex/components/skeleton';
 import { AXSkeletonModule } from '@acorex/components/skeleton';
 import { Subject, interval, fromEvent } from 'rxjs';
-import { AXDataSource } from '@acorex/cdk/common';
-import { AXTranslationService, resolveMultiLanguageString } from '@acorex/core/translation';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { DOCUMENT } from '@angular/common';
+import { AXLocaleService } from '@acorex/core/locale';
 import { AXCalendarService } from '@acorex/core/date-time';
 import { startWith, map, debounceTime } from 'rxjs/operators';
 
@@ -32,6 +35,184 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
 class AXPActivityLogProvider {
 }
 
+//#region ---- Catalog scope definition ----
+//#endregion
+
+//#region ---- Provider contract ----
+const AXP_CATALOG_SCOPE_DEFINITION_PROVIDER = new InjectionToken('AXP_CATALOG_SCOPE_DEFINITION_PROVIDER');
+//#endregion
+
+//#region ---- Imports ----
+//#endregion
+//#region ---- Aggregator service ----
+/**
+ * Collects {@link AXPCatalogScopeDefinition} entries from all registered providers.
+ */
+class AXPCatalogScopeDefinitionProviderService {
+    constructor() {
+        //#region ---- Services & Dependencies ----
+        this.providers = inject(AXP_CATALOG_SCOPE_DEFINITION_PROVIDER, { optional: true });
+        this.translation = inject(AXTranslationService);
+    }
+    //#endregion
+    //#region ---- Public API ----
+    async items() {
+        const merged = [];
+        const seen = new Set();
+        if (!Array.isArray(this.providers)) {
+            return merged;
+        }
+        for (const raw of this.providers) {
+            const provider = await Promise.resolve(raw);
+            if (!provider || typeof provider.items !== 'function') {
+                continue;
+            }
+            for (const item of await provider.items()) {
+                const name = item.name?.trim();
+                if (!name) {
+                    continue;
+                }
+                if (seen.has(name)) {
+                    throw new Error(`Duplicate catalog scope definition: "${name}"`);
+                }
+                seen.add(name);
+                merged.push(item);
+            }
+        }
+        return merged.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+    }
+    async get(name) {
+        const key = name?.trim();
+        if (!key) {
+            return undefined;
+        }
+        return (await this.items()).find((d) => d.name === key);
+    }
+    /**
+     * Scopes applicable to the given entity ref (`Module.Entity`).
+     */
+    async byTarget(entityRef) {
+        const target = entityRef?.trim();
+        if (!target) {
+            return [];
+        }
+        return (await this.items()).filter((d) => d.targets?.some((t) => t === target));
+    }
+    /**
+     * Resolves display title for a scope key (active locale).
+     */
+    resolveTitle(definition) {
+        const locale = this.translation.getActiveLang() ?? 'en-US';
+        if (typeof definition.title === 'string') {
+            const title = definition.title.trim();
+            if (title.startsWith('@')) {
+                return this.translation.translateSync(title) || title;
+            }
+            return title;
+        }
+        return resolveMultiLanguageString(definition.title, locale) || definition.name;
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: AXPCatalogScopeDefinitionProviderService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: AXPCatalogScopeDefinitionProviderService, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: AXPCatalogScopeDefinitionProviderService, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+//#region ---- Imports ----
+//#endregion
+//#region ---- Constants ----
+/** Data source name for select widgets listing registered catalog scopes. */
+const PLATFORM_CATALOG_SCOPES_DATASOURCE_NAME = 'platform-catalog-scopes';
+//#endregion
+//#region ---- Data source definition ----
+/**
+ * Registered catalog scopes for select / selection-list widgets via {@link PLATFORM_CATALOG_SCOPES_DATASOURCE_NAME}.
+ */
+class AXPCatalogScopeDefinitionsDataSourceDefinition {
+    constructor() {
+        //#region ---- Services & Dependencies ----
+        this.catalogScopeRegistry = inject(AXPCatalogScopeDefinitionProviderService);
+        //#endregion
+    }
+    //#endregion
+    //#region ---- Public API ----
+    async items() {
+        return [
+            {
+                name: PLATFORM_CATALOG_SCOPES_DATASOURCE_NAME,
+                title: 'Catalog scopes',
+                source: () => new AXDataSource({
+                    key: 'name',
+                    pageSize: 500,
+                    load: async (e) => {
+                        const all = await this.catalogScopeRegistry.items();
+                        const localeFilter = this.readTargetFilter(e?.filter);
+                        const items = all
+                            .filter((scope) => !localeFilter || scope.targets?.includes(localeFilter))
+                            .map((scope) => ({
+                            name: scope.name,
+                            title: this.catalogScopeRegistry.resolveTitle(scope),
+                            description: scope.description,
+                            targets: scope.targets,
+                            icon: scope.icon,
+                            cssClass: scope.cssClass,
+                        }));
+                        return { items, total: items.length };
+                    },
+                    byKey: async (key) => {
+                        const name = String(key ?? '').trim();
+                        if (!name) {
+                            return undefined;
+                        }
+                        const scope = await this.catalogScopeRegistry.get(name);
+                        if (!scope) {
+                            return undefined;
+                        }
+                        return {
+                            name: scope.name,
+                            title: this.catalogScopeRegistry.resolveTitle(scope),
+                            description: scope.description,
+                            targets: scope.targets,
+                            icon: scope.icon,
+                            cssClass: scope.cssClass,
+                        };
+                    },
+                }),
+                columns: [
+                    { name: 'name', title: 'Name', datatype: 'string', type: 'text-editor' },
+                    { name: 'title', title: 'Title', datatype: 'string', type: 'text-editor' },
+                ],
+                filters: [
+                    {
+                        field: 'targets',
+                        title: 'Target entity',
+                        operator: { type: 'contains' },
+                        widget: { type: 'text-editor' },
+                        filterType: { advance: false, inline: false },
+                    },
+                ],
+                textField: { name: 'title', title: 'Title' },
+                valueField: { name: 'name', title: 'Name' },
+            },
+        ];
+    }
+    //#endregion
+    //#region ---- Helpers ----
+    readTargetFilter(filter) {
+        if (!filter || typeof filter !== 'object') {
+            return undefined;
+        }
+        const f = filter;
+        if (f.field === 'targets' && typeof f.value === 'string' && f.value.trim()) {
+            return f.value.trim();
+        }
+        return undefined;
+    }
+}
+//#endregion
+
 //#region ----   Color Palette Provider   ----
 /**
  * Abstract class for color palette providers
@@ -527,6 +708,42 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
             type: Directive
         }] });
 
+//#region ---- Locale map shape ----
+/** Per-locale string map (`{ 'en-US': '...', 'fa-IR': '...' }`). */
+function isLocaleStringMap(value) {
+    if (!isPlainObject(value)) {
+        return false;
+    }
+    const entries = Object.values(value);
+    if (entries.length === 0) {
+        return false;
+    }
+    return entries.every((entry) => entry === null || entry === undefined || typeof entry === 'string');
+}
+/**
+ * Use locale-map read/write when the option is on or live/saved data is already a map.
+ * Auto-enables when API data is a map but the editor option was left off.
+ */
+function shouldUseLocaleMapShape(localeMapOptionEnabled, current, saved) {
+    return localeMapOptionEnabled || isLocaleStringMap(current) || isLocaleStringMap(saved);
+}
+/** Updates one locale entry; preserves sibling locales from current or saved map. */
+function buildLocaleTextMapValue(current, saved, lang, input) {
+    const seed = isLocaleStringMap(current)
+        ? { ...current }
+        : isLocaleStringMap(saved)
+            ? { ...saved }
+            : {};
+    seed[lang] = input ?? '';
+    for (const key of Object.keys(seed)) {
+        if ((seed[key] ?? '').trim() === '') {
+            delete seed[key];
+        }
+    }
+    return Object.keys(seed).length === 0 ? null : seed;
+}
+//#endregion
+
 function extractNestedFieldsWildcard(obj, basePath, fields) {
     const result = {};
     if (fields.length === 1 && fields[0] === '*') {
@@ -788,46 +1005,355 @@ function getDetailedChanges(obj1, obj2) {
 function getEnumValues(enumType) {
     return Object.entries(enumType).map(([key, value]) => ({ id: value, title: key }));
 }
+//#region ---- Form value equality (dirty / baseline) ----
+/** Whether a value uses the multi-language text widget shape (string or locale map). */
+function isMultiLanguageFormShape(value) {
+    if (value === null || value === undefined) {
+        return true;
+    }
+    if (typeof value === 'string') {
+        return true;
+    }
+    return isLocaleStringMap(value);
+}
+/** Drops empty/whitespace locale entries from a multi-language map. */
+function normalizeLocaleStringMap(value) {
+    const normalized = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry !== 'string') {
+            continue;
+        }
+        const trimmed = entry.trim();
+        if (trimmed !== '') {
+            normalized[key] = trimmed;
+        }
+    }
+    return Object.keys(normalized).length === 0 ? null : normalized;
+}
+/**
+ * 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).
+ */
+function compareMultiLanguageFormValues(a, b) {
+    if (!isMultiLanguageFormShape(a) || !isMultiLanguageFormShape(b)) {
+        return null;
+    }
+    const normalizeScalar = (value) => {
+        if (value === null || value === undefined) {
+            return null;
+        }
+        if (typeof value === 'string') {
+            const trimmed = value.trim();
+            return trimmed === '' ? null : trimmed;
+        }
+        if (isLocaleStringMap(value)) {
+            return normalizeLocaleStringMap(value);
+        }
+        return null;
+    };
+    const left = normalizeScalar(a);
+    const right = normalizeScalar(b);
+    if (left === null && right === null) {
+        return true;
+    }
+    if (left === null || right === null) {
+        return false;
+    }
+    if (typeof left === 'string' && typeof right === 'string') {
+        return left === right;
+    }
+    if (typeof left === 'string' && typeof right === 'object') {
+        const values = Object.values(right);
+        return values.length > 0 && values.every((text) => text === left);
+    }
+    if (typeof right === 'string' && typeof left === 'object') {
+        const values = Object.values(left);
+        return values.length > 0 && values.every((text) => text === right);
+    }
+    if (typeof left !== 'object' || typeof right !== 'object') {
+        return false;
+    }
+    const leftMap = left;
+    const rightMap = right;
+    const leftKeys = Object.keys(leftMap).sort();
+    const rightKeys = Object.keys(rightMap).sort();
+    if (leftKeys.length !== rightKeys.length) {
+        return false;
+    }
+    return leftKeys.every((key) => leftMap[key] === rightMap[key]);
+}
+/** Lookup/select filter-mode payload: `{ value, displayText?, operation }`. */
+function isFilterFormShape(value) {
+    if (!isPlainObject(value)) {
+        return false;
+    }
+    const record = value;
+    return 'value' in record && 'operation' in record;
+}
+/**
+ * Compares filter-mode widget values by selection identity; ignores derived `displayText`.
+ */
+function compareFilterFormValues(a, b) {
+    if (!isFilterFormShape(a) || !isFilterFormShape(b)) {
+        return null;
+    }
+    const left = a;
+    const right = b;
+    if (!isFormValueEqual(left['value'], right['value'])) {
+        return false;
+    }
+    const opLeft = get(left, 'operation.type');
+    const opRight = get(right, 'operation.type');
+    if (opLeft !== undefined || opRight !== undefined) {
+        return opLeft === opRight;
+    }
+    return true;
+}
+function isReferenceScalar(value) {
+    return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+}
+/** Scalar id or `{ id }` identity used by lookup/select widgets. */
+function getReferenceId(value) {
+    if (isNil(value)) {
+        return undefined;
+    }
+    if (isReferenceScalar(value)) {
+        return value;
+    }
+    if (isPlainObject(value)) {
+        const id = get(value, 'id');
+        if (!isNil(id)) {
+            return id;
+        }
+    }
+    return undefined;
+}
+/**
+ * Compares scalar selection ids to full lookup/select items (`5` vs `{ id: 5, ... }`).
+ * Does not apply when both sides are objects — those use structural compare so field edits stay dirty.
+ */
+function compareReferenceFormValues(a, b) {
+    const refA = getReferenceId(a);
+    const refB = getReferenceId(b);
+    if (refA === undefined || refB === undefined) {
+        return null;
+    }
+    const aIsScalar = isReferenceScalar(a);
+    const bIsScalar = isReferenceScalar(b);
+    if (!aIsScalar && !bIsScalar) {
+        return null;
+    }
+    return isEqual(normalizeFormValue(refA), normalizeFormValue(refB));
+}
+/**
+ * Semantic equality for lookup/select values when restoring saved baseline shape.
+ * Compares by selection identity (id), including two full items with the same id.
+ */
+function isSelectionValueEqual(a, b) {
+    const filterEqual = compareFilterFormValues(a, b);
+    if (filterEqual !== null) {
+        return filterEqual;
+    }
+    const refA = getReferenceId(a);
+    const refB = getReferenceId(b);
+    if (refA !== undefined && refB !== undefined) {
+        return isEqual(normalizeFormValue(refA), normalizeFormValue(refB));
+    }
+    return isFormValueEqual(a, b);
+}
+/**
+ * Stable sort key for order-insensitive array comparison (after normalization).
+ */
+function formValueSortKey(value) {
+    if (value === null) {
+        return '\0';
+    }
+    if (typeof value === 'number') {
+        return `n:${value}`;
+    }
+    if (typeof value === 'boolean') {
+        return `b:${value}`;
+    }
+    if (typeof value === 'string') {
+        return `s:${value}`;
+    }
+    try {
+        return `j:${JSON.stringify(value)}`;
+    }
+    catch {
+        return `u:${String(value)}`;
+    }
+}
+/**
+ * Sorts normalized array items so order does not affect dirty checks.
+ */
+function sortNormalizedArrayItems(items) {
+    return [...items].sort((a, b) => formValueSortKey(a).localeCompare(formValueSortKey(b)));
+}
+/**
+ * Normalizes a form/context value for semantic baseline comparison.
+ *
+ * Rules:
+ * - `null`, `undefined`, whitespace-only strings, and empty arrays → `null` (empty)
+ * - Numeric strings → numbers (`"5"` and `5` match)
+ * - Arrays → elements normalized; empty/all-empty → `null`; otherwise sorted (order ignored)
+ * - Plain objects → keys sorted; `null`/empty nested values omitted
+ * - `Date` → epoch milliseconds
+ */
+function normalizeFormValue(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed === '') {
+            return null;
+        }
+        if (/^-?\d+(\.\d+)?$/.test(trimmed)) {
+            const num = Number(trimmed);
+            if (!Number.isNaN(num)) {
+                return num;
+            }
+        }
+        return trimmed;
+    }
+    if (typeof value === 'number') {
+        return Number.isNaN(value) ? null : value;
+    }
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    if (value instanceof Date) {
+        return value.getTime();
+    }
+    if (isArray(value)) {
+        const normalizedItems = value
+            .map((item) => normalizeFormValue(item))
+            .filter((item) => item !== null);
+        if (normalizedItems.length === 0) {
+            return null;
+        }
+        return sortNormalizedArrayItems(normalizedItems);
+    }
+    if (isPlainObject(value)) {
+        const record = value;
+        if (isLocaleStringMap(record)) {
+            return normalizeLocaleStringMap(record);
+        }
+        const normalized = {};
+        for (const key of Object.keys(record).sort()) {
+            const next = normalizeFormValue(record[key]);
+            if (next !== null) {
+                normalized[key] = next;
+            }
+        }
+        return normalized;
+    }
+    return value;
+}
+/**
+ * Semantic equality for dirty-state and baseline checks.
+ * Prefer over lodash `isEqual` when comparing user-edited form/context data to a saved baseline.
+ *
+ * Arrays: `[]`, `null`, and all-empty lists are equivalent; non-empty arrays compare as multisets (order ignored).
+ */
+function isFormValueEqual(a, b) {
+    const multiLanguageEqual = compareMultiLanguageFormValues(a, b);
+    if (multiLanguageEqual !== null) {
+        return multiLanguageEqual;
+    }
+    const filterEqual = compareFilterFormValues(a, b);
+    if (filterEqual !== null) {
+        return filterEqual;
+    }
+    const referenceEqual = compareReferenceFormValues(a, b);
+    if (referenceEqual !== null) {
+        return referenceEqual;
+    }
+    if (isArray(a) && isArray(b)) {
+        // Empty repeater rows normalize away; raw length must differ before multiset compare.
+        if (a.length !== b.length) {
+            return false;
+        }
+        return isEqual(normalizeFormValue(a), normalizeFormValue(b));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const left = a;
+        const right = b;
+        const keys = new Set([...Object.keys(left), ...Object.keys(right)]);
+        for (const key of keys) {
+            if (!isFormValueEqual(left[key], right[key])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    return isEqual(normalizeFormValue(a), normalizeFormValue(b));
+}
+/**
+ * Returns whether `current` differs from the saved/clean `baseline` snapshot.
+ */
+function isFormContextDirty(current, baseline) {
+    return !isFormValueEqual(current, baseline);
+}
+/**
+ * Clones a context object for use as a dirty-tracking baseline.
+ */
+function captureFormContextBaseline(context) {
+    return cloneDeep(context);
+}
+//#endregion
 
 class AXPContextChangeEvent {
 }
 //#endregion
 //#region ---- Context signal store ----
-// Shared reactive context: root injector has a default instance; widget/layout trees
-const AXPContextStore = signalStore(
-// Initial State
-withState(() => ({
-    data: {}, // Shared context data
-    state: 'initiated', // Current state
-    initialSnapshot: {}, // Snapshot of the first initialized state
-    previousSnapshot: {}, // Snapshot of the previous state
+const AXPContextStore = signalStore(withState(() => ({
+    data: {},
+    state: 'initiated',
+    /** Last committed / saved baseline — discard reverts to this snapshot. */
+    savedSnapshot: {},
+    previousSnapshot: {},
     lastChange: {
         state: 'initiated',
-    }, // Last change event
-})), 
-// Computed Signals
-withComputed(({ data, state, lastChange, initialSnapshot, previousSnapshot }) => ({
+    },
+})), withComputed(({ data, state, lastChange, savedSnapshot, previousSnapshot }) => ({
     isChanged: computed(() => state() === 'changed'),
     isReset: computed(() => state() === 'restored'),
     isInitiated: computed(() => state() === 'initiated'),
     isEmpty: computed(() => Object.keys(data()).length === 0),
-    isDirty: computed(() => !isEqual(data(), previousSnapshot())),
-    snapshot: computed(() => cloneDeep(data())), // Current data snapshot
-    initial: computed(() => cloneDeep(initialSnapshot())), // Initial snapshot
-    previous: computed(() => cloneDeep(previousSnapshot())), // Previous snapshot
-    changeEvent: computed(() => lastChange()), // Reactive last change event
-})), 
-// Methods for State Management
-withMethods((store) => ({
-    // Update a specific value
-    update(path, value) {
+    isSavedCommitted: computed(() => !isEmpty(savedSnapshot())),
+    isDirty: computed(() => {
+        const saved = savedSnapshot();
+        if (isEmpty(saved)) {
+            return false;
+        }
+        return isFormContextDirty(data(), saved);
+    }),
+    snapshot: computed(() => cloneDeep(data())),
+    saved: computed(() => cloneDeep(savedSnapshot())),
+    /** @deprecated Use {@link saved} — only saved baseline is tracked. */
+    initial: computed(() => cloneDeep(savedSnapshot())),
+    previous: computed(() => cloneDeep(previousSnapshot())),
+    changeEvent: computed(() => lastChange()),
+})), withMethods((store) => {
+    const updateValue = (path, value, options) => {
         const currentData = cloneDeep(store.data());
         const oldValue = getSmart(currentData, path);
-        // Skip if the value hasn't changed
-        if (isEqual(oldValue, value)) {
+        const hasSaved = !isEmpty(store.savedSnapshot());
+        const savedAtPath = hasSaved ? getSmart(store.savedSnapshot(), path) : undefined;
+        if (hasSaved && isSelectionValueEqual(value, savedAtPath) && !isEqual(value, savedAtPath)) {
+            value = cloneDeep(savedAtPath);
+        }
+        const isArrayLengthChange = Array.isArray(value) && (!Array.isArray(oldValue) || value.length !== oldValue.length);
+        if (!isArrayLengthChange && isEqual(oldValue, value)) {
+            return;
+        }
+        const shouldNormalizeSavedShape = hasSaved && isSelectionValueEqual(value, savedAtPath) && !isEqual(oldValue, value);
+        if (!isArrayLengthChange && isFormValueEqual(oldValue, value) && !shouldNormalizeSavedShape) {
             return;
         }
-        // Update the value and prepare the change event
+        const origin = options?.origin ?? 'system';
         const updatedData = setSmart(currentData, path, value);
         const changeEvent = {
             oldValue,
@@ -835,78 +1361,122 @@ withMethods((store) => ({
             path,
             state: 'changed',
             data: updatedData,
+            origin,
         };
-        // Patch the state
         patchState(store, {
-            previousSnapshot: store.snapshot(), // Save the previous state
+            previousSnapshot: store.snapshot(),
             data: updatedData,
             state: 'changed',
             lastChange: changeEvent,
         });
-    },
-    patch(context, skipDirtyTracking = false) {
-        const currentData = cloneDeep(store.data());
-        // Update the value and prepare the change event
-        const updatedData = { ...currentData, ...context };
-        const changeEvent = {
-            state: 'patch',
-            data: updatedData,
-        };
-        // Patch the state
-        patchState(store, {
-            ...(skipDirtyTracking ? {} : { previousSnapshot: store.snapshot() }),
-            data: updatedData,
-            state: 'changed',
-            lastChange: changeEvent,
-        });
-    },
-    // Reset to the initial state
-    reset() {
-        const initialData = store.initial();
+    };
+    const applyObjectPaths = (obj, options, prefix = '') => {
+        for (const [key, value] of Object.entries(obj ?? {})) {
+            const path = prefix ? `${prefix}.${key}` : key;
+            if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+                applyObjectPaths(value, options, path);
+            }
+            else {
+                updateValue(path, value, options);
+            }
+        }
+    };
+    const revertToSaved = () => {
+        const savedData = store.saved();
         const changeEvent = {
-            oldValue: cloneDeep(store.data()), // Current data becomes old value
-            newValue: cloneDeep(initialData), // Reset to the initial state
+            oldValue: cloneDeep(store.data()),
+            newValue: cloneDeep(savedData),
             path: '',
             state: 'restored',
-            data: initialData,
+            data: savedData,
         };
         patchState(store, {
-            previousSnapshot: store.snapshot(), // Save the previous state
-            data: initialData,
+            previousSnapshot: store.snapshot(),
+            data: savedData,
             state: 'restored',
             lastChange: changeEvent,
         });
-    },
-    // Initialize the state
-    set(initialData) {
-        const currentData = store.data();
-        if (isEqual(currentData, initialData)) {
-            return; // Skip if the current state matches the initial state
-        }
-        const changeEvent = {
-            oldValue: null,
-            newValue: cloneDeep(initialData),
-            path: '',
-            state: 'initiated',
-            data: initialData,
-        };
-        patchState(store, {
-            initialSnapshot: cloneDeep(initialData), // Save the initial state
-            previousSnapshot: store.snapshot(), // Save the current state as the previous
-            data: initialData,
-            state: 'initiated',
-            lastChange: changeEvent,
-        });
-    },
-    // Get a specific value
-    getValue(path) {
-        return getSmart(store.data(), path);
-    },
-    // Check if a path exists in the context
-    hasValue(path) {
-        return has(store.data(), path);
-    },
-})));
+    };
+    return {
+        update(path, value, options) {
+            updateValue(path, value, options);
+        },
+        applyObjectPaths,
+        patch(context, options) {
+            const currentData = cloneDeep(store.data());
+            const updatedData = { ...currentData, ...context };
+            const changeEvent = {
+                state: 'patch',
+                data: updatedData,
+            };
+            const syncedSnapshot = cloneDeep(updatedData);
+            patchState(store, {
+                ...(options?.updateSaved
+                    ? { savedSnapshot: syncedSnapshot, previousSnapshot: syncedSnapshot }
+                    : { previousSnapshot: store.snapshot() }),
+                data: updatedData,
+                state: 'changed',
+                lastChange: changeEvent,
+            });
+        },
+        /** Reverts live data to the last saved snapshot. */
+        revertToSaved,
+        reset() {
+            revertToSaved();
+        },
+        /** Loads live data; saved baseline is committed separately via {@link commitSaved}. */
+        set(initialData) {
+            const currentData = store.data();
+            if (isFormValueEqual(currentData, initialData)) {
+                return;
+            }
+            const changeEvent = {
+                oldValue: null,
+                newValue: cloneDeep(initialData),
+                path: '',
+                state: 'initiated',
+                data: initialData,
+            };
+            patchState(store, {
+                previousSnapshot: store.snapshot(),
+                data: initialData,
+                state: 'initiated',
+                lastChange: changeEvent,
+            });
+        },
+        getValue(path) {
+            return getSmart(store.data(), path);
+        },
+        getSavedValue(path) {
+            return getSmart(store.savedSnapshot(), path);
+        },
+        hasValue(path) {
+            return has(store.data(), path);
+        },
+        /** Marks the current data as the saved baseline. */
+        commitSaved() {
+            const snapshot = cloneDeep(store.data());
+            patchState(store, {
+                savedSnapshot: snapshot,
+                previousSnapshot: snapshot,
+                state: 'initiated',
+                lastChange: {
+                    state: 'initiated',
+                    data: snapshot,
+                },
+            });
+        },
+        /** Merges parent-bound entity fields without resetting the saved baseline. */
+        applyParentBind(merged) {
+            if (isFormValueEqual(store.data(), merged)) {
+                return;
+            }
+            patchState(store, {
+                data: merged,
+            });
+        },
+    };
+}));
 //#endregion
 
 class AXPExpressionEvaluatorScopeProviderContext {
@@ -2069,6 +2639,709 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
             args: [{ providedIn: 'root' }]
         }] });
 
+//#region ---- Types ----
+/** Priority tier — higher values win when multiple bindings match. */
+var AXPKeyboardShortcutPriority;
+(function (AXPKeyboardShortcutPriority) {
+    AXPKeyboardShortcutPriority[AXPKeyboardShortcutPriority["Global"] = 0] = "Global";
+    AXPKeyboardShortcutPriority[AXPKeyboardShortcutPriority["Page"] = 10] = "Page";
+    AXPKeyboardShortcutPriority[AXPKeyboardShortcutPriority["Panel"] = 20] = "Panel";
+    AXPKeyboardShortcutPriority[AXPKeyboardShortcutPriority["Modal"] = 100] = "Modal";
+})(AXPKeyboardShortcutPriority || (AXPKeyboardShortcutPriority = {}));
+//#endregion
+
+//#region ---- Overlay Layer DOM Utilities ----
+/** Acorex overlay root (modal shell, popup, dialog). */
+const AX_OVERLAY_CONTAINER_SELECTOR = '.ax-overlay-container';
+/** Anchored widget panel inside an overlay (select, date picker, dropdown). */
+const AX_OVERLAY_PANE_SELECTOR = '.ax-overlay-pane';
+/**
+ * True when a visible overlay layer is foreground (modal, popup, widget popover/picker).
+ */
+function hasForegroundOverlayLayer(document) {
+    if (getVisibleAnchoredOverlayPanes(document).length > 0) {
+        return true;
+    }
+    return getVisibleOverlayContainers(document).length > 0;
+}
+/**
+ * Returns visible anchored overlay panes (widget popovers/pickers).
+ */
+function getVisibleAnchoredOverlayPanes(document) {
+    return Array.from(document.querySelectorAll(AX_OVERLAY_PANE_SELECTOR)).filter(isVisibleOverlayElement);
+}
+/**
+ * Visible anchored panes that are not contained by `excludeContainer` (e.g. dialog shell).
+ */
+function getNestedVisibleOverlayPanes(document, excludeContainer) {
+    return getVisibleAnchoredOverlayPanes(document).filter((pane) => !excludeContainer?.contains(pane));
+}
+/**
+ * Collects visible overlay containers in stacking order (later / higher z-index wins).
+ */
+function getVisibleOverlayContainers(document) {
+    return Array.from(document.querySelectorAll(AX_OVERLAY_CONTAINER_SELECTOR))
+        .filter(isVisibleOverlayElement)
+        .sort(compareOverlayStackOrder);
+}
+/** Topmost visible overlay container, if any. */
+function getTopVisibleOverlayContainer(document) {
+    const containers = getVisibleOverlayContainers(document);
+    return containers.length ? containers[containers.length - 1] : null;
+}
+/** Nearest overlay container ancestor of `element`. */
+function findOverlayContainerAncestor(element) {
+    return element.closest(AX_OVERLAY_CONTAINER_SELECTOR);
+}
+/**
+ * Returns true when the overlay element is rendered and visible in the viewport.
+ */
+function isVisibleOverlayElement(element) {
+    if (!(element instanceof HTMLElement)) {
+        return false;
+    }
+    const style = getComputedStyle(element);
+    if (style.display === 'none' || style.visibility === 'hidden' || Number(style.opacity) === 0) {
+        return false;
+    }
+    const rect = element.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0;
+}
+function compareOverlayStackOrder(a, b) {
+    const za = Number(getComputedStyle(a).zIndex) || 0;
+    const zb = Number(getComputedStyle(b).zIndex) || 0;
+    if (za !== zb) {
+        return za - zb;
+    }
+    const position = a.compareDocumentPosition(b);
+    if (position & Node.DOCUMENT_POSITION_FOLLOWING) {
+        return -1;
+    }
+    if (position & Node.DOCUMENT_POSITION_PRECEDING) {
+        return 1;
+    }
+    return 0;
+}
+//#endregion
+
+//#region ---- Imports ----
+const HORIZONTAL_DIRECTIONAL_KEY_MIRRORS = {
+    arrowleft: 'arrowright',
+    arrowright: 'arrowleft',
+    left: 'right',
+    right: 'left',
+    '[': ']',
+    ']': '[',
+};
+/** Maps a horizontal direction key to its RTL semantic counterpart. */
+function mirrorHorizontalDirectionalKey(key) {
+    const normalized = normalizeShortcutToken(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;
+}
+/**
+ * Resolves direction behavior for a chord.
+ * Horizontal direction keys default to `semantic`; others default to `physical`.
+ * An explicit binding value always wins.
+ */
+function resolveEffectiveDirectionBehavior(chord, explicit) {
+    if (explicit === 'physical' || explicit === 'semantic') {
+        return explicit;
+    }
+    const { key } = parseKeyboardShortcutChord(chord);
+    return isHorizontalDirectionalShortcutKey(key) ? 'semantic' : 'physical';
+}
+/** Resolves the key the user presses for a semantically registered chord in RTL. */
+function resolveSemanticDirectionalKey(storedKey, rtl) {
+    const normalized = normalizeShortcutToken(storedKey);
+    if (!rtl) {
+        return normalized;
+    }
+    return mirrorHorizontalDirectionalKey(normalized);
+}
+/** Chord string with directional key mirrored for RTL display/matching when semantic. */
+function resolveDisplayShortcutChord(chord, isRtl, explicitDirectionBehavior) {
+    const directionBehavior = resolveEffectiveDirectionBehavior(chord, explicitDirectionBehavior);
+    const parts = chord
+        .trim()
+        .split('+')
+        .map((part) => part.trim())
+        .filter(Boolean);
+    if (parts.length === 0) {
+        return chord;
+    }
+    const keyPart = parts.pop() ?? '';
+    const rtl = directionBehavior === 'semantic' && isRtl;
+    const resolvedKey = resolveSemanticDirectionalKey(keyPart, rtl);
+    return [...parts, resolvedKey].join('+');
+}
+const MODIFIER_ALIASES = {
+    ctrl: 'ctrl',
+    control: 'ctrl',
+    shift: 'shift',
+    alt: 'alt',
+    option: 'alt',
+    meta: 'meta',
+    cmd: 'meta',
+    command: 'meta',
+    win: 'meta',
+};
+const KEY_DISPLAY_MAC = {
+    ctrl: '⌃',
+    control: '⌃',
+    shift: '⇧',
+    alt: '⌥',
+    option: '⌥',
+    meta: '⌘',
+    cmd: '⌘',
+    command: '⌘',
+    win: '⌘',
+    enter: '↵',
+    escape: 'Esc',
+    esc: 'Esc',
+    home: 'Home',
+    arrowleft: '←',
+    arrowright: '→',
+    arrowup: '↑',
+    arrowdown: '↓',
+    pageup: 'PgUp',
+    pagedown: 'PgDn',
+    backspace: '⌫',
+    delete: '⌦',
+    space: 'Space',
+};
+/**
+ * Parses a shortcut chord such as `Enter`, `Escape`, or `ctrl+shift+s`.
+ */
+function parseKeyboardShortcutChord(chord) {
+    const parts = chord
+        .trim()
+        .toLowerCase()
+        .split('+')
+        .map((part) => part.trim())
+        .filter(Boolean);
+    const key = normalizeShortcutToken(parts.pop() ?? '');
+    const parsed = {
+        ctrl: false,
+        shift: false,
+        alt: false,
+        meta: false,
+        key,
+    };
+    for (const part of parts) {
+        const alias = MODIFIER_ALIASES[part];
+        if (alias) {
+            parsed[alias] = true;
+        }
+    }
+    return parsed;
+}
+/**
+ * Returns true when the keyboard event matches the given chord.
+ * On macOS, `ctrl+*` chords also match `meta+*` for common platform shortcuts.
+ */
+function matchesKeyboardShortcutChord(event, chord, options) {
+    const parsed = parseKeyboardShortcutChord(chord);
+    const mac = isMacPlatform();
+    const directionBehavior = resolveEffectiveDirectionBehavior(chord, options?.directionBehavior);
+    if (!matchesShortcutModifiers(parsed, event, mac)) {
+        return false;
+    }
+    const actualKey = normalizeShortcutEventKey(event);
+    const expectedKey = normalizeShortcutToken(parsed.key);
+    const rtlSemantic = directionBehavior === 'semantic' &&
+        options?.isRtl === true &&
+        isHorizontalDirectionalShortcutKey(expectedKey);
+    if (rtlSemantic) {
+        return actualKey === mirrorHorizontalDirectionalKey(expectedKey);
+    }
+    return actualKey === expectedKey;
+}
+/**
+ * Matches modifier keys for a parsed chord.
+ * `ctrl+alt` chords also accept AltGraph (Windows) so layout-produced characters still match physical keys.
+ */
+function matchesShortcutModifiers(parsed, event, mac) {
+    if (parsed.shift !== event.shiftKey) {
+        return false;
+    }
+    const altGraph = hasAltGraphModifier(event);
+    if (parsed.ctrl && parsed.alt) {
+        if (altGraph) {
+            return true;
+        }
+        return event.ctrlKey && event.altKey;
+    }
+    if (parsed.alt !== event.altKey) {
+        return false;
+    }
+    if (parsed.meta) {
+        if (!event.metaKey) {
+            return false;
+        }
+        return true;
+    }
+    if (parsed.ctrl) {
+        if (mac) {
+            return event.metaKey || event.ctrlKey;
+        }
+        return event.ctrlKey;
+    }
+    if (event.ctrlKey || event.metaKey) {
+        return false;
+    }
+    return true;
+}
+function hasAltGraphModifier(event) {
+    return typeof event.getModifierState === 'function' && event.getModifierState('AltGraph');
+}
+/**
+ * Formats one chord for UI display (OS-aware modifier symbols).
+ */
+function formatKeyboardShortcutChord(chord, options) {
+    const directionBehavior = resolveEffectiveDirectionBehavior(chord, options?.directionBehavior);
+    const resolvedChord = options?.skipDirectionResolve
+        ? chord
+        : resolveDisplayShortcutChord(chord, options?.isRtl === true, directionBehavior);
+    const mac = isMacPlatform();
+    const parts = resolvedChord
+        .trim()
+        .split('+')
+        .map((part) => part.trim())
+        .filter(Boolean);
+    if (parts.length === 0) {
+        return '';
+    }
+    const keyPart = normalizeShortcutToken(parts.pop() ?? '');
+    const modifierParts = parts.map((part) => formatShortcutPart(part.toLowerCase(), mac));
+    const keyDisplay = formatShortcutPart(keyPart, mac);
+    if (mac) {
+        return [...modifierParts, keyDisplay].join('');
+    }
+    return [...modifierParts, keyDisplay].join('+');
+}
+/**
+ * Formats multiple chords as a single display string (e.g. `← / PgUp`).
+ */
+function formatKeyboardShortcutChords(chords, options) {
+    return chords.map((chord) => formatKeyboardShortcutChord(chord, options)).join(' / ');
+}
+/** Maps a chord to `ax-kbd-item` key parts (modifiers + display symbols). */
+function chordToKbdItemKeys(chord, options) {
+    const directionBehavior = resolveEffectiveDirectionBehavior(chord, options?.directionBehavior);
+    const resolvedChord = options?.skipDirectionResolve
+        ? chord
+        : resolveDisplayShortcutChord(chord, options?.isRtl === true, directionBehavior);
+    const mac = isMacPlatform();
+    const symbolKeys = {
+        arrowleft: '←',
+        arrowright: '→',
+        arrowup: '↑',
+        arrowdown: '↓',
+        pageup: 'PgUp',
+        pagedown: 'PgDn',
+        enter: '↵',
+        escape: 'Esc',
+        esc: 'Esc',
+        space: 'Space',
+        '[': '[',
+        ']': ']',
+    };
+    return resolvedChord
+        .trim()
+        .split('+')
+        .map((part) => part.trim())
+        .filter(Boolean)
+        .map((part) => {
+        const normalized = part.toLowerCase();
+        if (mac && (normalized === 'ctrl' || normalized === 'control')) {
+            return '⌘';
+        }
+        return symbolKeys[normalized] ?? part;
+    });
+}
+/**
+ * When focus is in a native edit control, avoid stealing plain key shortcuts.
+ */
+function isKeyboardTargetInsideEditableField(target) {
+    if (!(target instanceof HTMLElement)) {
+        return false;
+    }
+    if (target.isContentEditable) {
+        return true;
+    }
+    const field = target.closest('input, textarea, select');
+    if (!field || field.disabled) {
+        return false;
+    }
+    if (field instanceof HTMLInputElement) {
+        const type = field.type;
+        if (type === 'hidden' ||
+            type === 'checkbox' ||
+            type === 'radio' ||
+            type === 'button' ||
+            type === 'submit' ||
+            type === 'reset' ||
+            type === 'file' ||
+            field.readOnly) {
+            return false;
+        }
+        return true;
+    }
+    if (field instanceof HTMLTextAreaElement) {
+        return !field.readOnly;
+    }
+    return true;
+}
+/**
+ * Returns true when Esc should close an open widget overlay first (select, date picker, popover, modal).
+ * Used by the global shortcut registry so page-level Esc bindings do not swallow overlay dismiss.
+ */
+function shouldDeferEscapeToOpenOverlay(document) {
+    return hasForegroundOverlayLayer(document);
+}
+function isMacPlatform() {
+    if (typeof navigator === 'undefined') {
+        return false;
+    }
+    return /Mac|iPhone|iPad|iPod/i.test(navigator.userAgent);
+}
+function normalizeShortcutToken(key) {
+    const normalized = key.trim().toLowerCase();
+    if (normalized === 'esc') {
+        return 'escape';
+    }
+    if (normalized === 'left') {
+        return 'arrowleft';
+    }
+    if (normalized === 'right') {
+        return 'arrowright';
+    }
+    if (normalized === 'up') {
+        return 'arrowup';
+    }
+    if (normalized === 'down') {
+        return 'arrowdown';
+    }
+    if (normalized === '[' || normalized === 'bracketleft') {
+        return '[';
+    }
+    if (normalized === ']' || normalized === 'bracketright') {
+        return ']';
+    }
+    return normalized;
+}
+function normalizeShortcutEventKey(event) {
+    if (event.key === 'Enter') {
+        return 'enter';
+    }
+    if (event.key === 'Escape') {
+        return 'escape';
+    }
+    if (event.key === 'Home') {
+        return 'home';
+    }
+    if (event.key === ' ') {
+        return 'space';
+    }
+    if (event.key === '[' || event.code === 'BracketLeft') {
+        return '[';
+    }
+    if (event.key === ']' || event.code === 'BracketRight') {
+        return ']';
+    }
+    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];
+    }
+    if (event.key.length === 1) {
+        return event.key.toLowerCase();
+    }
+    const fnMatch = event.code.match(/^F(\d+)$/);
+    if (fnMatch) {
+        return `f${fnMatch[1]}`;
+    }
+    return event.key.toLowerCase();
+}
+function formatShortcutPart(part, mac) {
+    const normalized = normalizeShortcutToken(part);
+    if (mac && KEY_DISPLAY_MAC[normalized]) {
+        return KEY_DISPLAY_MAC[normalized];
+    }
+    if (!mac && MODIFIER_ALIASES[normalized]) {
+        return normalized.charAt(0).toUpperCase() + normalized.slice(1);
+    }
+    if (KEY_DISPLAY_MAC[normalized]) {
+        return KEY_DISPLAY_MAC[normalized];
+    }
+    if (normalized.length === 1) {
+        return normalized.toUpperCase();
+    }
+    return normalized.charAt(0).toUpperCase() + normalized.slice(1);
+}
+//#endregion
+
+//#region ---- Keyboard Shortcut Declaration Utilities ----
+/**
+ * Normalizes a declarative shortcut (`'ctrl+s'` or `{ keys: 'home', allowInEditableFields: false }`).
+ */
+function normalizeKeyboardShortcut(shortcut) {
+    if (typeof shortcut === 'string') {
+        const chord = shortcut.trim();
+        if (!chord) {
+            return undefined;
+        }
+        return { keys: [chord] };
+    }
+    return normalizeKeyboardShortcutConfig(shortcut);
+}
+/**
+ * Normalizes an array of declarative shortcuts. Empty or invalid entries are skipped.
+ */
+function normalizeKeyboardShortcuts(shortcuts) {
+    if (!shortcuts?.length) {
+        return [];
+    }
+    const result = [];
+    for (const shortcut of shortcuts) {
+        const normalized = normalizeKeyboardShortcut(shortcut);
+        if (normalized) {
+            result.push(normalized);
+        }
+    }
+    return result;
+}
+/** Returns the first chord from declarative shortcuts (for UI hints such as `ax-kbd`). */
+function getPrimaryKeyboardShortcutChord(shortcuts) {
+    return normalizeKeyboardShortcuts(shortcuts)[0]?.keys[0];
+}
+function normalizeKeyboardShortcutConfig(shortcut) {
+    const keys = Array.isArray(shortcut.keys) ? shortcut.keys : [shortcut.keys];
+    const normalizedKeys = keys.map((chord) => chord.trim()).filter(Boolean);
+    if (normalizedKeys.length === 0) {
+        return undefined;
+    }
+    return {
+        keys: normalizedKeys,
+        allowInEditableFields: shortcut.allowInEditableFields,
+        when: shortcut.when,
+        directionBehavior: shortcut.directionBehavior,
+    };
+}
+//#endregion
+
+//#region ---- Imports ----
+//#endregion
+class AXPKeyboardShortcutRegistry {
+    constructor() {
+        //#region ---- Services & Dependencies ----
+        this.document = inject(DOCUMENT);
+        this.localeService = inject(AXLocaleService);
+        this.activeProfile = toSignal(this.localeService.profileChanged$, {
+            initialValue: this.localeService.activeProfile(),
+        });
+        this.registrations = signal([], ...(ngDevMode ? [{ debugName: "registrations" }] : /* istanbul ignore next */ []));
+        this.helpDialogHandler = null;
+        this.listenerAttached = false;
+        //#endregion
+        //#region ---- Computed Properties ----
+        /** Active shortcut entries for the help dialog. */
+        this.helpEntries = computed(() => {
+            this.activeProfile();
+            return this.buildHelpEntries();
+        }, ...(ngDevMode ? [{ debugName: "helpEntries" }] : /* istanbul ignore next */ []));
+        this.onDocumentKeyDown = (event) => {
+            if (event.key === 'Escape' && shouldDeferEscapeToOpenOverlay(this.document)) {
+                return;
+            }
+            if (event.key === 'F1') {
+                event.preventDefault();
+                event.stopImmediatePropagation();
+                if (hasForegroundOverlayLayer(this.document)) {
+                    return;
+                }
+            }
+            const candidates = this.resolveActiveCandidates(event);
+            if (candidates.length === 0) {
+                return;
+            }
+            const match = candidates[0];
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            void match.binding.handler(event);
+        };
+    }
+    //#endregion
+    //#region ---- Public Methods ----
+    /**
+     * Registers a scope of shortcuts. Unregisters automatically when `owner` is destroyed.
+     */
+    register(options) {
+        const { owner, ...registrationOptions } = options;
+        const registrationId = `${options.id}-${this.createRegistrationId()}`;
+        const entry = {
+            ...registrationOptions,
+            registrationId,
+            priority: options.priority ?? 0,
+        };
+        this.registrations.update((items) => [
+            ...items.filter((item) => item.id !== options.id),
+            entry,
+        ]);
+        this.ensureListener();
+        owner.onDestroy(() => {
+            this.unregister(registrationId);
+        });
+    }
+    /**
+     * Wires the F1 help dialog opener (provided by platform/common).
+     */
+    setHelpDialogHandler(handler) {
+        this.helpDialogHandler = handler;
+        this.ensureHelpShortcutRegistered();
+    }
+    /** OS-aware display string for UI hints. */
+    formatDisplayKeys(chords) {
+        return formatKeyboardShortcutChords(chords, { isRtl: this.isRtlProfile() });
+    }
+    //#endregion
+    //#region ---- Private Methods ----
+    ensureHelpShortcutRegistered() {
+        const alreadyRegistered = this.registrations().some((entry) => entry.id === 'system:keyboard-shortcuts-help');
+        if (alreadyRegistered || !this.helpDialogHandler) {
+            return;
+        }
+        const handler = this.helpDialogHandler;
+        const entry = {
+            registrationId: 'system:keyboard-shortcuts-help',
+            id: 'system:keyboard-shortcuts-help',
+            priority: -1,
+            scope: '@general:keyboard-shortcuts.groups.system',
+            shortcuts: [
+                {
+                    keys: ['f1'],
+                    title: '@general:keyboard-shortcuts.help-action',
+                    allowInEditableFields: true,
+                    handler: () => {
+                        void handler();
+                    },
+                },
+            ],
+        };
+        this.registrations.update((items) => [...items, entry]);
+        this.ensureListener();
+    }
+    createRegistrationId() {
+        if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+            return crypto.randomUUID();
+        }
+        return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    }
+    unregister(registrationId) {
+        this.registrations.update((items) => items.filter((item) => item.registrationId !== registrationId));
+    }
+    ensureListener() {
+        if (this.listenerAttached || typeof this.document === 'undefined') {
+            return;
+        }
+        this.document.addEventListener('keydown', this.onDocumentKeyDown, true);
+        this.listenerAttached = true;
+    }
+    resolveActiveCandidates(event) {
+        const editable = isKeyboardTargetInsideEditableField(event.target);
+        const candidates = [];
+        for (const registration of this.registrations()) {
+            if (!this.isRegistrationActive(registration)) {
+                continue;
+            }
+            const priority = registration.priority ?? 0;
+            for (const binding of registration.shortcuts) {
+                if (binding.when && !binding.when()) {
+                    continue;
+                }
+                if (editable && !binding.allowInEditableFields) {
+                    continue;
+                }
+                for (const chord of binding.keys) {
+                    const directionBehavior = resolveEffectiveDirectionBehavior(chord, binding.directionBehavior);
+                    if (!matchesKeyboardShortcutChord(event, chord, {
+                        directionBehavior,
+                        isRtl: this.isRtlProfile(),
+                    })) {
+                        continue;
+                    }
+                    candidates.push({
+                        priority,
+                        registration,
+                        binding,
+                        chord,
+                    });
+                    break;
+                }
+            }
+        }
+        return candidates.sort((a, b) => b.priority - a.priority);
+    }
+    isRegistrationActive(registration) {
+        if (registration.when && !registration.when()) {
+            return false;
+        }
+        const element = registration.elementRef?.nativeElement;
+        if (element && !this.document.contains(element)) {
+            return false;
+        }
+        return true;
+    }
+    isRtlProfile() {
+        return this.activeProfile()?.i18nMeta?.rtl === true;
+    }
+    buildHelpEntries() {
+        const entries = [];
+        const isRtl = this.isRtlProfile();
+        for (const registration of this.registrations()) {
+            if (!this.isRegistrationActive(registration)) {
+                continue;
+            }
+            if (registration.id === 'system:keyboard-shortcuts-help') {
+                continue;
+            }
+            const priority = registration.priority ?? 0;
+            for (const binding of registration.shortcuts) {
+                const displayChords = binding.keys.map((chord) => {
+                    const directionBehavior = resolveEffectiveDirectionBehavior(chord, binding.directionBehavior);
+                    return resolveDisplayShortcutChord(chord, isRtl, directionBehavior);
+                });
+                entries.push({
+                    registrationId: registration.registrationId,
+                    bindingTitle: binding.title,
+                    chords: [...binding.keys],
+                    displayChords,
+                    displayKeys: formatKeyboardShortcutChords(displayChords, { skipDirectionResolve: true }),
+                    scope: registration.scope,
+                    group: binding.group ?? registration.group,
+                    priority,
+                });
+            }
+        }
+        return entries.sort((a, b) => b.priority - a.priority || a.bindingTitle.localeCompare(b.bindingTitle));
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: AXPKeyboardShortcutRegistry, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: AXPKeyboardShortcutRegistry, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: AXPKeyboardShortcutRegistry, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root',
+                }]
+        }] });
+
 //#region ----   Imports   ----
 //#endregion
 
@@ -2428,6 +3701,8 @@ class AXPAppStartUpService {
         this.translationService = inject(AXTranslationService);
         this.tasks = [];
     }
+    //#endregion
+    //#region ----   Public Methods   ----
     registerTask(task) {
         this.tasks.push(task);
     }
@@ -3734,16 +5009,6 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
 
 const loggingEnabled = false; // Set to true to enable logging, false to disable
 //#region ---- Multilingual string helpers ----
-/**
- * Per-locale string map as produced by multilingual editors (e.g. `{ "en-US": "...", "fa-IR": "..." }`).
- */
-function isLocaleStringMap(value) {
-    if (value === null || typeof value !== 'object' || Array.isArray(value) || value instanceof Date) {
-        return false;
-    }
-    const values = Object.values(value);
-    return values.length > 0 && values.every((v) => typeof v === 'string');
-}
 /**
  * Lowercased text for client-side filtering: plain string or all locale values joined.
  */
@@ -4468,5 +5733,5 @@ function generateKebabCase(title) {
  * Generated bundle index. Do not edit.
  */
 
-export { AXHighlightService, AXPActivityLogProvider, AXPActivityLogService, AXPAppStartUpProvider, AXPAppStartUpService, AXPBroadcastEventService, AXPColorPaletteProvider, AXPColorPaletteService, AXPColumnWidthService, AXPComponentLogoConfig, AXPComponentSlot, AXPComponentSlotDirective, AXPComponentSlotModule, AXPComponentSlotRegistryService, AXPContentCheckerDirective, AXPContextChangeEvent, AXPContextDefinitionProviderService, AXPContextStore, AXPCountdownPipe, AXPDataGenerator, AXPDataSourceDefinitionProviderService, AXPDblClickDirective, AXPDefaultColorPalettesProvider, AXPDeviceService, AXPDeviceType, AXPDistributedEventListenerService, AXPElementDataDirective, AXPExportTemplateToken, AXPExpressionEvaluatorScopeProviderContext, AXPExpressionEvaluatorScopeProviderService, AXPExpressionEvaluatorService, AXPFeatureDefinitionProviderContext, AXPGridLayoutDirective, AXPHookService, AXPIconLogoConfig, AXPImageUrlLogoConfig, AXPModuleManifestModule, AXPModuleManifestRegistry, AXPModuleManifestsDataSourceDefinition, AXPPlatformScope, AXPScreenSize, AXPSystemActionType, AXPSystemActions, AXPTagProvider, AXPTagService, AXP_ACTIVITY_LOG_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, MODULE_MANIFESTS_DATASOURCE_NAME, applyFilterArray, applyPagination, applyQueryArray, applySortArray, applySystemActionDefault, cleanDeep, coerceUnknownToBoolean, coerceUnknownToDate, coerceUnknownToFiniteNumber, coerceUnknownToTrimmedString, compareMultiLanguageStrings, containsHtmlMarkup, createProviderWithInjectionContext, defaultColumnWidthProvider, extractNestedFieldsWildcard, extractTextFromHtml, extractValue, generateKebabCase, getActionButton, getChangedPaths, getDetailedChanges, getEnumValues, getNestedKeys, getSmart, getSystemActions, normalizeDefinitionCategories, objectKeyValueTransforms, provideLazyProvider, resolveActionLook, resolvePlatformScopeKey, resolvePlatformScopeName, searchInMultiLanguageString, setSmart, sortByMultiLanguageString, unwrapValueProperty };
+export { AXHighlightService, AXPActivityLogProvider, AXPActivityLogService, AXPAppStartUpProvider, AXPAppStartUpService, AXPBroadcastEventService, AXPCatalogScopeDefinitionProviderService, AXPCatalogScopeDefinitionsDataSourceDefinition, AXPColorPaletteProvider, AXPColorPaletteService, AXPColumnWidthService, AXPComponentLogoConfig, AXPComponentSlot, AXPComponentSlotDirective, AXPComponentSlotModule, AXPComponentSlotRegistryService, AXPContentCheckerDirective, AXPContextChangeEvent, AXPContextDefinitionProviderService, AXPContextStore, AXPCountdownPipe, AXPDataGenerator, AXPDataSourceDefinitionProviderService, AXPDblClickDirective, AXPDefaultColorPalettesProvider, AXPDeviceService, AXPDeviceType, AXPDistributedEventListenerService, AXPElementDataDirective, AXPExportTemplateToken, AXPExpressionEvaluatorScopeProviderContext, AXPExpressionEvaluatorScopeProviderService, AXPExpressionEvaluatorService, AXPFeatureDefinitionProviderContext, AXPGridLayoutDirective, AXPHookService, AXPIconLogoConfig, AXPImageUrlLogoConfig, AXPKeyboardShortcutPriority, AXPKeyboardShortcutRegistry, AXPModuleManifestModule, AXPModuleManifestRegistry, AXPModuleManifestsDataSourceDefinition, AXPPlatformScope, AXPScreenSize, AXPSystemActionType, 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, MODULE_MANIFESTS_DATASOURCE_NAME, PLATFORM_CATALOG_SCOPES_DATASOURCE_NAME, applyFilterArray, applyPagination, applyQueryArray, applySortArray, applySystemActionDefault, buildLocaleTextMapValue, captureFormContextBaseline, chordToKbdItemKeys, cleanDeep, coerceUnknownToBoolean, coerceUnknownToDate, coerceUnknownToFiniteNumber, coerceUnknownToTrimmedString, compareMultiLanguageStrings, containsHtmlMarkup, createProviderWithInjectionContext, defaultColumnWidthProvider, extractNestedFieldsWildcard, extractTextFromHtml, extractValue, findOverlayContainerAncestor, formatKeyboardShortcutChord, formatKeyboardShortcutChords, generateKebabCase, getActionButton, getChangedPaths, getDetailedChanges, getEnumValues, getNestedKeys, getNestedVisibleOverlayPanes, getPrimaryKeyboardShortcutChord, getSmart, getSystemActions, getTopVisibleOverlayContainer, getVisibleAnchoredOverlayPanes, getVisibleOverlayContainers, hasForegroundOverlayLayer, isFormContextDirty, isFormValueEqual, isHorizontalDirectionalShortcutKey, isKeyboardTargetInsideEditableField, isLocaleStringMap, isMacPlatform, isSelectionValueEqual, isVisibleOverlayElement, matchesKeyboardShortcutChord, mirrorHorizontalDirectionalKey, normalizeDefinitionCategories, normalizeKeyboardShortcut, normalizeKeyboardShortcuts, objectKeyValueTransforms, parseKeyboardShortcutChord, provideLazyProvider, resolveActionLook, resolveDisplayShortcutChord, resolveEffectiveDirectionBehavior, resolvePlatformScopeKey, resolvePlatformScopeName, resolveSemanticDirectionalKey, searchInMultiLanguageString, setSmart, shouldDeferEscapeToOpenOverlay, shouldUseLocaleMapShape, sortByMultiLanguageString, unwrapValueProperty };
 //# sourceMappingURL=acorex-platform-core.mjs.map