@cratis/scene.engine 4.26.0 → 4.27.0

package/dist/esm/validateNavigationDestinations.js

@@ -1,4 +1,6 @@
 import { diagnoseNavigation } from './navigation/diagnoseNavigation.js';
+import './navigation/navigationRegions.js';
+import '@cratis/scene.model';
 
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.

package/dist/esm/validateNavigationDestinations.js.map

@@ -1 +1 @@
-{"version":3,"file":"validateNavigationDestinations.js","sources":["../../validateNavigationDestinations.ts"],"sourcesContent":["// Copyright (c) Cratis. All rights reserved.\n// Licensed under the MIT license. See LICENSE file in the project root for full license information.\n\nimport { DestinationReference, DialogTemplate, Layout, Screen, ScreenTemplate } from '@cratis/scene.model';\nimport { NavigationDiagnostic, diagnoseNavigation } from './navigation';\n\n/**\n * A navigation problem as {@link validateNavigationDestinations} reports it.\n */\nexport type NavigationDestinationDiagnostic = NavigationDiagnostic;\n\n/**\n * Validates destinations against the outlet/route declarations owned by layouts and templates, and - when\n * the screens and dialog templates are given - against the targets that actually exist.\n *\n * A shorthand for {@link diagnoseNavigation} over destinations without entry identities.\n */\nexport function validateNavigationDestinations(\n    destinations: DestinationReference[],\n    surfaces: { layouts?: Layout[]; screenTemplates?: ScreenTemplate[]; screens?: Screen[]; dialogTemplates?: DialogTemplate[] } = {},\n): NavigationDestinationDiagnostic[] {\n    return diagnoseNavigation({ entries: destinations.map(destination => ({ destination })), ...surfaces });\n}\n"],"names":["validateNavigationDestinations","destinations","surfaces","diagnoseNavigation","entries","map","destination"],"mappings":";;AAAA;AACA;AAUA;;;;;AAKC,IACM,SAASA,8BAAAA,CACZC,YAAoC,EACpCC,QAAAA,GAA+H,EAAE,EAAA;AAEjI,IAAA,OAAOC,kBAAAA,CAAmB;AAAEC,QAAAA,OAAAA,EAASH,YAAAA,CAAaI,GAAG,CAACC,CAAAA,eAAgB;AAAEA,gBAAAA;aAAY,CAAA,CAAA;AAAK,QAAA,GAAGJ;AAAS,KAAA,CAAA;AACzG;;"}
+{"version":3,"file":"validateNavigationDestinations.js","sources":["../../validateNavigationDestinations.ts"],"sourcesContent":["// Copyright (c) Cratis. All rights reserved.\n// Licensed under the MIT license. See LICENSE file in the project root for full license information.\n\nimport { DestinationReference, DialogTemplate, Layout, Screen, ScreenTemplate } from '@cratis/scene.model';\nimport { NavigationDiagnostic, diagnoseNavigation } from './navigation';\n\n/**\n * A navigation problem as {@link validateNavigationDestinations} reports it.\n */\nexport type NavigationDestinationDiagnostic = NavigationDiagnostic;\n\n/**\n * Validates destinations against the outlet/route declarations owned by layouts and templates, and - when\n * the screens and dialog templates are given - against the targets that actually exist.\n *\n * A shorthand for {@link diagnoseNavigation} over destinations without entry identities.\n */\nexport function validateNavigationDestinations(\n    destinations: DestinationReference[],\n    surfaces: { layouts?: Layout[]; screenTemplates?: ScreenTemplate[]; screens?: Screen[]; dialogTemplates?: DialogTemplate[] } = {},\n): NavigationDestinationDiagnostic[] {\n    return diagnoseNavigation({ entries: destinations.map(destination => ({ destination })), ...surfaces });\n}\n"],"names":["validateNavigationDestinations","destinations","surfaces","diagnoseNavigation","entries","map","destination"],"mappings":";;;;AAAA;AACA;AAUA;;;;;AAKC,IACM,SAASA,8BAAAA,CACZC,YAAoC,EACpCC,QAAAA,GAA+H,EAAE,EAAA;AAEjI,IAAA,OAAOC,kBAAAA,CAAmB;AAAEC,QAAAA,OAAAA,EAASH,YAAAA,CAAaI,GAAG,CAACC,CAAAA,eAAgB;AAAEA,gBAAAA;aAAY,CAAA,CAAA;AAAK,QAAA,GAAGJ;AAAS,KAAA,CAAA;AACzG;;"}

package/editing/resolveEffectiveConfiguration.ts

@@ -51,6 +51,19 @@ function collectionValue(grant: ExposureGrant, matching: InstanceContribution[],
             continue;
         }
 
+        if (contribution.replaceOwnerItems === true) {
+            if (!grant.operations.includes(CollectionOperation.Replace)) {
+                diagnostics.push(errorDiagnostic(
+                    DiagnosticCode.ContributionOperationNotPermitted,
+                    `'${instance}' replaces the items it inherits in '${grant.path}', but replacing items is not exposed. It is ignored and kept.`,
+                    context));
+                continue;
+            }
+
+            items.splice(0, items.length);
+            contributed = true;
+        }
+
         if (contribution.items.length > 0 && !grant.operations.includes(CollectionOperation.Add)) {
             diagnostics.push(errorDiagnostic(
                 DiagnosticCode.ContributionOperationNotPermitted,

package/navigation/EffectiveNavItem.ts

@@ -0,0 +1,37 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { NavigationItemOrigin } from './NavigationItemOrigin';
+import { ResolvedNavigationTarget } from './ResolvedNavigationTarget';
+
+/**
+ * One item a region effectively shows, with its provenance.
+ */
+export interface EffectiveNavItem {
+    /** The item identity. */
+    id: string;
+
+    /** The text shown for the item. */
+    title: string;
+
+    /** Qualified icon reference, when the item has one. */
+    icon?: string;
+
+    /** The slot the target renders into; `content` when the item names none. */
+    slot: string;
+
+    /** What the item navigates to, with a module resolved to its first feature; absent when the item has no target. */
+    target?: ResolvedNavigationTarget;
+
+    /** Which level defined the item. */
+    origin: NavigationItemOrigin;
+
+    /** Whether the item may not be edited here: it is inherited from the application into a module. */
+    readOnly: boolean;
+
+    /** A sentence saying why the item is shown and whether it can be edited here. */
+    reason: string;
+
+    /** The sub-items; only sidebar items have them. */
+    children?: EffectiveNavItem[];
+}

package/navigation/EffectiveNavigationRegion.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { NavigationRegionKind, NavigationRegionMode } from '@cratis/scene.model';
+import { EffectiveNavItem } from './EffectiveNavItem';
+import { NavigationSources } from './NavigationSources';
+
+/**
+ * The items a region effectively shows for the application or for one module, with where they came from.
+ */
+export interface EffectiveNavigationRegion {
+    /** Which region this is. */
+    region: NavigationRegionKind;
+
+    /** The module the region is resolved for; absent for the application itself. */
+    module?: string;
+
+    /** The effective mode: absent at the application level, which is the base. */
+    mode?: NavigationRegionMode;
+
+    /** Where the items come from, as the region tag shows it. */
+    sources: NavigationSources;
+
+    /** The items in the order they are shown. */
+    items: EffectiveNavItem[];
+}

package/navigation/NavigationDiagnosticCode.ts

@@ -23,4 +23,19 @@ export enum NavigationDiagnosticCode {
 
     /** A destination opens a screen or dialog that does not exist, or names nothing to open. */
     UnavailableTarget = 'unavailableTarget',
+
+    /** A navigation item has no target, or targets a module or feature the application does not have. */
+    NavTargetMissing = 'navTargetMissing',
+
+    /** A navigation item renders into a slot the layout does not declare. */
+    NavSlotUnknown = 'navSlotUnknown',
+
+    /** Two navigation items of one region share an id. */
+    NavDuplicateId = 'navDuplicateId',
+
+    /** A navigation item targets a module that has no feature to go to. */
+    NavModuleWithoutFeatures = 'navModuleWithoutFeatures',
+
+    /** A module's own navigation item targets a different module. */
+    NavTargetOutOfScope = 'navTargetOutOfScope',
 }

package/navigation/NavigationEdit.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ApplicationLogo, NavigationRegionKind, NavigationRegionMode, NavItem } from '@cratis/scene.model';
+import { NavigationEditKind } from './NavigationEditKind';
+
+/**
+ * One change to a {@link NavigationModel}. An edit helper returns the edits that carry out a user's gesture - for
+ * example adding an item to an inheriting region is a switch to `extend` and then the add - so every host that offers
+ * the gesture makes the same change.
+ */
+export interface NavigationEdit {
+    /** What the edit does. */
+    kind: NavigationEditKind;
+
+    /** The module the edit is for; absent for the application level. */
+    module?: string;
+
+    /** The region the edit changes. */
+    region?: NavigationRegionKind;
+
+    /** For `setRegionMode`: the new mode. */
+    mode?: NavigationRegionMode;
+
+    /** For `setRegionItems`: the items the level's region holds afterwards. */
+    items?: NavItem[];
+
+    /** For `addItem`: the id of the item the new item becomes a sub-item of; absent for a top-level item. */
+    parent?: string;
+
+    /** For `addItem`: the item to add, after the items already there. */
+    item?: NavItem;
+
+    /** For `setLogo`: the application logo. */
+    logo?: ApplicationLogo;
+}

package/navigation/NavigationEditKind.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * What a navigation edit does. The values are shared with the C# engine.
+ */
+export enum NavigationEditKind {
+    /** Sets how a module's region relates to the application's. */
+    SetRegionMode = 'setRegionMode',
+
+    /** Replaces the items a level holds in a region. */
+    SetRegionItems = 'setRegionItems',
+
+    /** Adds an item, or a sub-item, after the ones already there. */
+    AddItem = 'addItem',
+
+    /** Sets the application logo. */
+    SetLogo = 'setLogo',
+}

package/navigation/NavigationEditOutcome.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { NavigationModel } from '@cratis/scene.model';
+
+/**
+ * The result of applying navigation edits. Either every edit applies, or none does and `model` is the model given.
+ */
+export interface NavigationEditOutcome {
+    /** Whether every edit was applied. */
+    applied: boolean;
+
+    /** The model after the edits; the model given when they were not applied. */
+    model: NavigationModel;
+
+    /** Why the edits were refused; absent when they were applied. */
+    rejected?: string;
+}

package/navigation/NavigationEditPlan.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { NavigationEdit } from './NavigationEdit';
+
+/**
+ * The edits an edit helper decided on, or why it refused.
+ */
+export interface NavigationEditPlan {
+    /** The edits to apply, in order; empty when the helper refused or nothing needs to change. */
+    edits: NavigationEdit[];
+
+    /** Why the gesture is refused; absent when it is allowed. */
+    rejected?: string;
+}

package/navigation/NavigationGraph.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { DialogTemplate, Layout, Screen, ScreenTemplate } from '@cratis/scene.model';
+import { ApplicationStructure, DialogTemplate, Layout, NavigationModel, Screen, ScreenTemplate } from '@cratis/scene.model';
 import { NavigationEntry } from './NavigationEntry';
 
 /**
@@ -23,4 +23,13 @@ export interface NavigationGraph {
 
     /** The dialog templates dialog destinations may open. */
     dialogTemplates?: DialogTemplate[];
+
+    /** The modules, features and slices of the application; with `navigation`, the navigation regions are checked against them. */
+    structure?: ApplicationStructure;
+
+    /** The application and module navigation regions to check against `structure`. */
+    navigation?: NavigationModel;
+
+    /** The rendering slots navigation items may render into; `content` only when absent. */
+    slots?: string[];
 }

package/navigation/NavigationItemOrigin.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Which level defined a navigation item.
+ */
+export enum NavigationItemOrigin {
+    /** The application defined the item. */
+    Application = 'application',
+
+    /** A module defined the item. */
+    Module = 'module',
+}

package/navigation/NavigationSources.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { NavigationSourcesKind } from './NavigationSourcesKind';
+
+/**
+ * Where a region's items come from, as the region tag in design mode shows it.
+ */
+export interface NavigationSources {
+    /** How the effective items relate to the application's. */
+    kind: NavigationSourcesKind;
+
+    /** The compact tag text: `defined here`, `inherited`, `Application + Sales` or `Sales only`. */
+    label: string;
+}

package/navigation/NavigationSourcesKind.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * How a region's effective items relate to the application's. The values are shared with the C# engine.
+ */
+export enum NavigationSourcesKind {
+    /** The application level: every region is defined here. */
+    DefinedHere = 'definedHere',
+
+    /** A module region that shows the application's items. */
+    Inherited = 'inherited',
+
+    /** A module region that shows the application's items and its own. */
+    Extended = 'extended',
+
+    /** A module region that shows its own items only. */
+    Overridden = 'overridden',
+}

package/navigation/ResolvedNavigationTarget.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Where a navigation item goes, resolved against the application structure.
+ */
+export interface ResolvedNavigationTarget {
+    /** The module the item targets. */
+    module: string;
+
+    /** The feature the item names, a dotted path inside the module; absent when it targets the module. */
+    feature?: string;
+
+    /**
+     * The qualified id of the feature the item opens: the named feature, or for a module target the module's first
+     * feature. Absent when the module or feature does not exist, or the module has no features.
+     */
+    resolvedFeature?: string;
+}

package/navigation/diagnoseNavigation.ts

@@ -3,6 +3,7 @@
 
 import { DestinationKind, DestinationReference, Screen } from '@cratis/scene.model';
 import { collectOutlets } from './collectOutlets';
+import { diagnoseNavigationRegions } from './diagnoseNavigationRegions';
 import { findHostingCycles } from './findHostingCycles';
 import { NavigationDiagnostic } from './NavigationDiagnostic';
 import { NavigationDiagnosticCode } from './NavigationDiagnosticCode';
@@ -16,7 +17,8 @@ import { OutletOwner } from './OutletOwner';
  *
  * Routes are compared by `routeKey` - by default the authored route override, since the engine constructs no
  * URLs. Nothing is rewritten. The C# engine (`NavigationDiagnostics.Diagnose`) reports the same codes and
- * messages in the same order for the same model; both are asserted against `navigation-diagnostic-fixtures.json`.
+ * messages in the same order for the same model; both are asserted against `navigation-diagnostic-fixtures.json`. When the graph carries
+an application `structure` and `navigation` regions, the regions are checked too ({@link diagnoseNavigationRegions}).
  */
 export function diagnoseNavigation(graph: NavigationGraph, routeKey: NavigationRouteKey = authoredRouteKey): NavigationDiagnostic[] {
     const diagnostics: NavigationDiagnostic[] = [];
@@ -62,6 +64,10 @@ export function diagnoseNavigation(graph: NavigationGraph, routeKey: NavigationR
         });
     }
 
+    if (graph.structure && graph.navigation) {
+        diagnostics.push(...diagnoseNavigationRegions(graph.structure, graph.navigation, { slots: graph.slots }));
+    }
+
     return diagnostics;
 }
 

package/navigation/diagnoseNavigationRegions.ts

@@ -0,0 +1,122 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ApplicationStructure, NavigationModel, NavigationRegion, NavigationRegionKind, NavigationRegionMode, NavItem } from '@cratis/scene.model';
+import { ApplicationStructureIndex } from '../structure';
+import { NavigationDiagnostic } from './NavigationDiagnostic';
+import { NavigationDiagnosticCode } from './NavigationDiagnosticCode';
+import { applicationItems, collectItemIds, findNavigationRegion, navigationRegionOrder, primarySlot } from './navigationRegions';
+
+/** What the region diagnostics are checked against. */
+export interface NavigationRegionDiagnosticOptions {
+    /** The rendering slots items may render into; `content` only when absent. */
+    slots?: string[];
+}
+
+/**
+ * Diagnoses the navigation regions of an application against its structure: duplicate item ids, targets that are
+ * missing, out of scope or lead nowhere, and slots the layout does not declare. The application is checked first,
+ * then each module in the order they are declared; within a level the topbar comes before the sidebar and items are
+ * visited depth first.
+ *
+ * The C# engine (`NavigationRegionDiagnostics`) reports the same codes and messages in the same order; both are
+ * asserted against `navigation-inheritance-fixtures.json`, `navigation-targets-fixtures.json` and
+ * `navigation-diagnostic-fixtures.json`.
+ *
+ * @param structure The modules, features and slices of the application.
+ * @param navigation The application and module regions.
+ * @param options The slots items may render into.
+ */
+export function diagnoseNavigationRegions(
+    structure: ApplicationStructure | ApplicationStructureIndex,
+    navigation: NavigationModel,
+    options: NavigationRegionDiagnosticOptions = {},
+): NavigationDiagnostic[] {
+    const index = structure instanceof ApplicationStructureIndex ? structure : new ApplicationStructureIndex(structure);
+    const slots = options.slots ?? [primarySlot];
+    const diagnostics: NavigationDiagnostic[] = [];
+
+    for (const region of navigationRegionOrder) {
+        const defined = findNavigationRegion(navigation.application.regions, region);
+        if (defined) checkRegion(index, slots, diagnostics, undefined, defined, []);
+    }
+
+    for (const moduleNavigation of navigation.modules) {
+        for (const region of navigationRegionOrder) {
+            const defined = findNavigationRegion(moduleNavigation.regions, region);
+            if (!defined) continue;
+
+            const inherited = defined.mode === NavigationRegionMode.Extend ? collectItemIds(applicationItems(navigation.application, region), region) : [];
+            checkRegion(index, slots, diagnostics, moduleNavigation.module, defined, inherited);
+        }
+    }
+
+    return diagnostics;
+}
+
+function checkRegion(
+    index: ApplicationStructureIndex,
+    slots: string[],
+    diagnostics: NavigationDiagnostic[],
+    owner: string | undefined,
+    defined: NavigationRegion,
+    applicationIds: string[],
+): void {
+    const scope = owner === undefined ? 'the application' : `module '${owner}'`;
+    const seen = new Set<string>();
+
+    const visit = (items: NavItem[]): void => {
+        for (const item of items) {
+            const entry = `${owner ?? 'application'}:${defined.region}:${item.id}`;
+            const report = (code: NavigationDiagnosticCode, message: string): void => { diagnostics.push({ code, message, entry }); };
+
+            if (seen.has(item.id)) {
+                report(NavigationDiagnosticCode.NavDuplicateId, `Navigation item '${item.id}' is used more than once in ${scope} ${defined.region}.`);
+            } else if (applicationIds.includes(item.id)) {
+                report(NavigationDiagnosticCode.NavDuplicateId, `Navigation item '${item.id}' in ${scope} ${defined.region} is also used by an application item, and the region extends the application.`);
+            }
+            seen.add(item.id);
+
+            checkTarget(index, owner, item, report);
+
+            const slot = item.slot ?? primarySlot;
+            if (!slots.includes(slot)) {
+                report(NavigationDiagnosticCode.NavSlotUnknown, `Navigation item '${item.id}' renders into slot '${slot}', which the layout does not declare.`);
+            }
+
+            if (defined.region === NavigationRegionKind.Sidebar && item.children) visit(item.children);
+        }
+    };
+
+    visit(defined.items);
+}
+
+function checkTarget(index: ApplicationStructureIndex, owner: string | undefined, item: NavItem, report: (code: NavigationDiagnosticCode, message: string) => void): void {
+    const module = item.target?.module;
+    const hasChildren = (item.children?.length ?? 0) > 0;
+
+    if (!module) {
+        // A sidebar item that only groups sub-items needs no target of its own.
+        if (!hasChildren) report(NavigationDiagnosticCode.NavTargetMissing, `Navigation item '${item.id}' has no target.`);
+        return;
+    }
+
+    if (!index.findModule(module)) {
+        report(NavigationDiagnosticCode.NavTargetMissing, `Navigation item '${item.id}' targets module '${module}', which does not exist.`);
+        return;
+    }
+
+    if (owner !== undefined && module !== owner) {
+        report(NavigationDiagnosticCode.NavTargetOutOfScope, `Navigation item '${item.id}' of module '${owner}' targets module '${module}'; a module's own items may only target that module.`);
+        return;
+    }
+
+    const feature = item.target?.feature;
+    if (feature) {
+        if (!index.findFeature(`${module}.${feature}`)) {
+            report(NavigationDiagnosticCode.NavTargetMissing, `Navigation item '${item.id}' targets feature '${module}.${feature}', which does not exist.`);
+        }
+    } else if (!index.firstFeature(module)) {
+        report(NavigationDiagnosticCode.NavModuleWithoutFeatures, `Navigation item '${item.id}' targets module '${module}', which has no features to go to.`);
+    }
+}

package/navigation/effectiveNavigation.ts

@@ -0,0 +1,105 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ApplicationStructure, NavigationModel, NavigationRegionKind, NavigationRegionMode, NavItem } from '@cratis/scene.model';
+import { ApplicationStructureIndex } from '../structure';
+import { EffectiveNavigationRegion } from './EffectiveNavigationRegion';
+import { EffectiveNavItem } from './EffectiveNavItem';
+import { NavigationItemOrigin } from './NavigationItemOrigin';
+import { NavigationSources } from './NavigationSources';
+import { NavigationSourcesKind } from './NavigationSourcesKind';
+import { applicationItems, findModuleNavigation, findNavigationRegion, modeOfModuleRegion, primarySlot } from './navigationRegions';
+import { ResolvedNavigationTarget } from './ResolvedNavigationTarget';
+
+/**
+ * Resolves the items a navigation region effectively shows, for the application or for one module.
+ *
+ * - Application (no `module`): the application items, editable, `defined here`.
+ * - `inherit` (the default at a module): the application items, read-only; the module's own items are cleared.
+ * - `extend`: the application items, read-only, followed by the module's items.
+ * - `override`: the module's items only.
+ *
+ * Each item carries its `origin`, whether it is `readOnly`, a `reason`, and its target resolved against the
+ * structure: a module target goes to the module's first feature. Sub-items belong to the sidebar; a topbar is flat
+ * and its sub-items are ignored. This is the one function React renderers, Stage, Studio design mode and Studio
+ * preview call; nothing re-implements it.
+ *
+ * The C# engine (`EffectiveNavigation.Resolve`) returns the same result; both are asserted against
+ * `navigation-inheritance-fixtures.json` and `navigation-targets-fixtures.json`.
+ *
+ * @param structure The modules, features and slices of the application.
+ * @param navigation The application and module regions.
+ * @param module The module to resolve for; undefined for the application.
+ * @param region Which region to resolve.
+ */
+export function effectiveNavigation(
+    structure: ApplicationStructure | ApplicationStructureIndex,
+    navigation: NavigationModel,
+    module: string | undefined,
+    region: NavigationRegionKind,
+): EffectiveNavigationRegion {
+    const index = structure instanceof ApplicationStructureIndex ? structure : new ApplicationStructureIndex(structure);
+    const applicationOwned = applicationItems(navigation.application, region);
+
+    if (module === undefined) {
+        return {
+            region,
+            sources: { kind: NavigationSourcesKind.DefinedHere, label: 'defined here' },
+            items: applicationOwned.map(item => resolveItem(index, region, item, NavigationItemOrigin.Application, false, 'Defined here.')),
+        };
+    }
+
+    const mode = modeOfModuleRegion(navigation, module, region);
+    const moduleOwned = findNavigationRegion(findModuleNavigation(navigation, module)?.regions, region)?.items ?? [];
+    const name = index.findModule(module)?.name ?? module;
+    const inherited = (): EffectiveNavItem[] => applicationOwned.map(item => resolveItem(index, region, item, NavigationItemOrigin.Application, true, 'Inherited from the application; edit it there.'));
+    const own = (): EffectiveNavItem[] => moduleOwned.map(item => resolveItem(index, region, item, NavigationItemOrigin.Module, false, `Defined in ${name}.`));
+
+    switch (mode) {
+        case NavigationRegionMode.Extend:
+            return { region, module, mode, sources: sourcesOf(NavigationSourcesKind.Extended, name), items: [...inherited(), ...own()] };
+        case NavigationRegionMode.Override:
+            return { region, module, mode, sources: sourcesOf(NavigationSourcesKind.Overridden, name), items: own() };
+        default:
+            return { region, module, mode: NavigationRegionMode.Inherit, sources: sourcesOf(NavigationSourcesKind.Inherited, name), items: inherited() };
+    }
+}
+
+function sourcesOf(kind: NavigationSourcesKind, moduleName: string): NavigationSources {
+    switch (kind) {
+        case NavigationSourcesKind.Extended: return { kind, label: `Application + ${moduleName}` };
+        case NavigationSourcesKind.Overridden: return { kind, label: `${moduleName} only` };
+        default: return { kind: NavigationSourcesKind.Inherited, label: 'inherited' };
+    }
+}
+
+function resolveItem(index: ApplicationStructureIndex, region: NavigationRegionKind, item: NavItem, origin: NavigationItemOrigin, readOnly: boolean, reason: string): EffectiveNavItem {
+    const resolved: EffectiveNavItem = { id: item.id, title: item.title, slot: item.slot ?? primarySlot, origin, readOnly, reason };
+    if (item.icon !== undefined) resolved.icon = item.icon;
+
+    const target = resolveTarget(index, item);
+    if (target) resolved.target = target;
+
+    if (region === NavigationRegionKind.Sidebar && item.children && item.children.length > 0) {
+        resolved.children = item.children.map(child => resolveItem(index, region, child, origin, readOnly, reason));
+    }
+
+    return resolved;
+}
+
+function resolveTarget(index: ApplicationStructureIndex, item: NavItem): ResolvedNavigationTarget | undefined {
+    const module = item.target?.module;
+    if (!module) return undefined;
+
+    const target: ResolvedNavigationTarget = { module };
+    const feature = item.target?.feature;
+    if (feature) {
+        target.feature = feature;
+        if (index.findFeature(`${module}.${feature}`)) target.resolvedFeature = `${module}.${feature}`;
+    } else {
+        const first = index.firstFeatureId(module);
+        if (first !== undefined) target.resolvedFeature = first;
+    }
+
+    return target;
+}

package/navigation/index.ts

@@ -8,3 +8,17 @@ export * from './NavigationGraph';
 export * from './diagnoseNavigation';
 export * from './navigationEntriesFrom';
 export * from './navigationRoute';
+export * from './navigationRegions';
+export * from './NavigationItemOrigin';
+export * from './NavigationSourcesKind';
+export * from './NavigationSources';
+export * from './ResolvedNavigationTarget';
+export * from './EffectiveNavItem';
+export * from './EffectiveNavigationRegion';
+export * from './effectiveNavigation';
+export * from './diagnoseNavigationRegions';
+export * from './NavigationEditKind';
+export * from './NavigationEdit';
+export * from './NavigationEditPlan';
+export * from './NavigationEditOutcome';
+export * from './navigationEdits';