@wildo-ai/saas-frontend-lib 1.1.10 → 1.1.11

package/dist/esm/core/navigation/navigation.utils.js

@@ -4,15 +4,15 @@
  * Shared utility functions for the navigation system.
  * Centralized to avoid duplication across navigation modules.
  */
-import { CascadeDirection, CoreResourceOperation, coreResourceShared_FieldIdentifier, NavigationTransition, NavigationZoneName, ParentDisplay, ResourcesConfigOperationsUrlsBuilderUtils, ResourceRelationshipCardinality, Resources_SharedUtils, } from '@wildo-ai/saas-models';
+import { CascadeDirection, CoreResourceOperation, coreResourceShared_FieldIdentifier, NavigationTransition, NavigationZoneName, ParentDisplay, ResourcesConfigOperationsUrlsBuilderUtils, Resources_SharedUtils, } from '@wildo-ai/saas-models';
 import { COMPOSITE_ROUTE_CONTEXT_QUERY_PARAM_PREFIX } from '../../core/config/composite-view.schemas.js';
 import { CHART_ROUTE_CONTEXT_QUERY_PARAM_PREFIX, CHART_ROUTE_PATH_PREFIX } from '../../core/config/chart-view.frontend.schemas.js';
 import { HOSTED_PANE_QUERY_PARAM } from './hosted-pane.constants.js';
 import { resolveViewportDiscriminated } from './navigation-policy-resolver.service.js';
 import { EXECUTION_ROUTE_CONTEXT_QUERY_PARAM_PREFIX } from '../../core/config/execution-view.schemas.js';
 import { isOperationAddressable } from '../../core/resources/resources.frontend.schemas.js';
-import { frontendResourceUtils } from '../../core/resources/frontend-resource.utils.js';
-import { pickPreferredOperationForCoreSemantic, resolveEffectiveCoreOperationFromOperation, } from '../../core/resources/operation-semantics.frontend.utils.js';
+import { FrontendResourceUtils, frontendResourceUtils } from '../../core/resources/frontend-resource.utils.js';
+import { operationAddressesOneRecord, pickPreferredOperationForCoreSemantic, resolveEffectiveCoreOperation, resolveEffectiveCoreOperationFromOperation, } from '../../core/resources/operation-semantics.frontend.utils.js';
 import { pickPreferredOperationForCoreSemanticAddressability } from '../../core/resources/resource-addressability.frontend.utils.js';
 import { NavigationZone, APP_LEVEL_NAVIGATION_SOURCE, NavigationContentType, isCustomComponentNavigationItem, isEnginePageNavigationItem, isSettingsHubNavigationItem, isViewNavigationItem, } from './navigation.schemas.js';
 import { LoggerFrontendService } from '../../core/monitoring/logger.frontend.service.js';
@@ -1118,7 +1118,7 @@ export class NavigationUtils {
         }
         else if (target.contentType === NavigationContentType.SETTINGS_HUB) {
             // URL-first: navigate() short-circuits SETTINGS_HUB content to a route
-            // navigation, and `useSettingsHubRouterSync` reconstructs the hub in the
+            // navigation, and `useSettingsHubOverlaySync` reconstructs the hub in the
             // overlay. Every settings entry point converges on this one path.
             navigate({
                 content: {
@@ -1191,11 +1191,27 @@ export class NavigationUtils {
     }
     /**
      * Create initiator context for operation-related navigation (from within a structural zone).
+     *
+     * `sourceOperation` records the CORE operation the navigating surface performs (`list`, `read`, `create`, …), which
+     * is the closed vocabulary `NavigationInitiatorContextSchema` validates. Pass the operation itself, not its
+     * identifier: an application's own operation is recorded as the core operation it behaves like
+     * (`list_my_requests`, `resourceOperationLike: LIST` → `list`), and one that behaves like none (an action such as
+     * `approve`) records nothing. A bare identifier is kept only when it IS a core operation.
+     *
+     * This used to cast the identifier to `CoreResourceOperation`, which the type checker believed and the event bus did
+     * not: every navigation started from a custom operation's surface was rejected as `Invalid payload for
+     * navigation_replace` and never happened — Wonder Procurement's "create" button on its "My requests" list did
+     * nothing (2026-10-11).
      */
     static createOperationInitiator(sourceZone, sourceOperation) {
+        const coreSourceOperation = typeof sourceOperation === 'string'
+            ? resolveEffectiveCoreOperation(sourceOperation)
+            : sourceOperation
+                ? resolveEffectiveCoreOperationFromOperation(sourceOperation)
+                : undefined;
         return {
             sourceZone: sourceZone ?? NavigationZone.PRIMARY,
-            ...(sourceOperation ? { sourceOperation: sourceOperation } : {}),
+            ...(coreSourceOperation ? { sourceOperation: coreSourceOperation } : {}),
         };
     }
     /**
@@ -1607,23 +1623,36 @@ export class NavigationUtils {
                 Resources_SharedUtils.tryResolveRelationshipForeignKeyIdentity(rel, registry.allResourceFieldIdentifiers)?.fieldIdentifier === foreignKeyField));
     }
     /**
-     * Determine the default ancestor operation based on relationship cardinality.
-     *
-     * Cardinality semantics:
-     * - 1:N (parent ONE → child MANY): ancestor shows LIST (list of children / siblings)
-     * - 1:1 (parent ONE → child ONE): ancestor shows READ (parent detail)
-     * - N:1 (reversed perspective): ancestor shows READ (parent detail)
-     * - M:N (junction): ancestor shows LIST (related items)
+     * The operation an ancestor zone shows by default, when a record is placed beside its parent.
+     *
+     * - **Self-referencing** (a unit and its sub-unit): the relationship's `inParentNavigation.direction`
+     *   decides — BACKWARD shows the parent RECORD; FORWARD, or no direction declared, the collection. A
+     *   collection of the record's OWN type beside it is the list-detail pairing, which the
+     *   zone-dependency cleanup keeps.
+     * - **Every other relationship, whatever its cardinality: the parent RECORD (READ).**
+     *
+     * Why READ, and not the parent type's collection for a one-to-many or many-to-many parent (the rule
+     * until 2026-10-01, #2115). Three things agree on the parent record, and the collection contradicted
+     * all of them:
+     *
+     *   1. **The click.** A record opened beside its parent was opened FROM the parent's page, so the
+     *      parent's record is what primary holds while the reader works. A deep link has to rebuild that.
+     *   2. **The URL.** `/todo-lists/:listId/todos/:todoId` names the parent by id; its prefix is the
+     *      parent's own page.
+     *   3. **The zone-dependency cleanup.** `isContentRelevantToParent` keeps a pane beside the parent
+     *      RECORD it belongs to and, deliberately, not beside a collection of that type (it has no id to
+     *      match, "fails closed"). So a collection placed here was judged stale one tick later and the
+     *      pane it was placed FOR was cleared — measured on Wonder Todos: reloading a todo opened beside
+     *      its list showed the "Todo Lists" collection and no todo.
+     *
+     * The comment this replaces described the collection as "the list of children / siblings", which it
+     * never was: it is the ANCESTOR type's collection, the parents. A relationship that wants a collection
+     * there anyway says so with `inParentNavigation.ancestorOperation` — see that field for what it costs.
      *
      * @param relationship - The resource relationship
      * @returns The default CoreResourceOperation for the ancestor zone
      */
     static deriveDefaultAncestorOperation(relationship) {
-        const { cardinality1, cardinality2 } = relationship;
-        const isParentOne = cardinality1 === ResourceRelationshipCardinality.ONE
-            || cardinality1 === ResourceRelationshipCardinality.ZERO_OR_ONE;
-        const isChildOne = cardinality2 === ResourceRelationshipCardinality.ONE
-            || cardinality2 === ResourceRelationshipCardinality.ZERO_OR_ONE;
         // Self-referencing: use the relationship-owned navigation direction to disambiguate
         // which side is "parent" vs "child" for the ancestor zone operation.
         // Without this, the engine can't distinguish forward (parent→child = LIST)
@@ -1634,28 +1663,17 @@ export class NavigationUtils {
                 return CoreResourceOperation.READ;
             return CoreResourceOperation.LIST;
         }
-        // 1:1 → READ parent detail
-        if (isParentOne && isChildOne) {
-            return CoreResourceOperation.READ;
-        }
-        // 1:N (parent=ONE, child=MANY) → LIST (show siblings in parent context)
-        if (isParentOne) {
-            return CoreResourceOperation.LIST;
-        }
-        // N:1 reversed → READ parent
-        if (isChildOne) {
-            return CoreResourceOperation.READ;
-        }
-        // M:N → LIST
-        return CoreResourceOperation.LIST;
+        // Any other relationship: the parent record (see above).
+        return CoreResourceOperation.READ;
     }
     /**
      * Resolve the ancestor operation for a given relationship.
      *
      * Resolution order:
      * 1. Explicit `ancestorOperation` override from display.inParentNavigation → use directly
-     * 2. Cardinality-based default (deriveDefaultAncestorOperation)
-     * 3. Fallback: swap LIST ↔ READ if default is not available
+     * 2. The default (deriveDefaultAncestorOperation): the parent record, or the self-ref direction
+     * 3. Fallback: swap LIST ↔ READ if default is not available (`cascadeAncestorZones` refuses a
+     *    collection of another resource in PRIMARY and places the pane below's own collection instead)
      * 4. null if no suitable operation exists
      *
      * @param relationship - The resource relationship between ancestor and descendant
@@ -1699,7 +1717,7 @@ export class NavigationUtils {
         };
         // 1. Explicit override from display.inParentNavigation.ancestorOperation.
         // This allows relationship config to force a specific operation (LIST or READ)
-        // for the ancestor zone, overriding the cardinality-based default.
+        // for the ancestor zone, overriding the default below.
         if (relationship) {
             const navigationConfig = relationship.display?.inParentNavigation;
             const ancestorOp = navigationConfig?.ancestorOperation;
@@ -1710,14 +1728,20 @@ export class NavigationUtils {
                 }
             }
         }
-        // 2. Cardinality-based default
+        // 2. The default: the parent record (self-referencing: its declared direction). With no
+        // relationship known, the ancestor is still a PARENT of the record (it comes from the record's
+        // parent requirements), so its record too.
         const defaultOp = relationship
             ? NavigationUtils.deriveDefaultAncestorOperation(relationship)
-            : CoreResourceOperation.LIST;
+            : CoreResourceOperation.READ;
         const defaultOperation = findOp(defaultOp);
         if (defaultOperation)
             return defaultOperation;
-        // 3. Fallback: swap LIST ↔ READ
+        // 3. Fallback: the other of LIST / READ. This resolver does not know which ZONE the ancestor lands in,
+        //    and that is what decides whether a collection of another resource is acceptable: in SECONDARY it
+        //    is (the companion is still kept by the record in PRIMARY), in PRIMARY it is not (the
+        //    zone-dependency cleanup measures SECONDARY against PRIMARY's top entry, and a collection of the
+        //    parent's type has no parent id to match). `cascadeAncestorZones` applies that rule.
         const fallbackOp = defaultOp === CoreResourceOperation.LIST
             ? CoreResourceOperation.READ
             : CoreResourceOperation.LIST;
@@ -1727,18 +1751,6 @@ export class NavigationUtils {
         // 4. No suitable operation
         return null;
     }
-    /**
-     * Check if secondary/companion zone content is relevant to the current PRIMARY top entry.
-     *
-     * Content is considered "stale" (irrelevant) when:
-     * - It's a resource operation whose parentResourcesRequirements no longer match
-     *   the PRIMARY zone's parent resource type and id
-     * - It's a view (composite/chart) — always stale on PRIMARY change
-     *
-     * @param dependentContent - Content in SECONDARY or COMPANION zone
-     * @param primaryContent - Current top content in PRIMARY zone
-     * @returns true if the dependent content is still relevant to the primary
-     */
     /**
      * Does this operation address a COLLECTION rather than one record?
      *
@@ -1753,23 +1765,95 @@ export class NavigationUtils {
         const semantic = resolveEffectiveCoreOperationFromOperation(operation);
         return semantic === CoreResourceOperation.LIST || semantic === CoreResourceOperation.SEARCH;
     }
-    static isContentRelevantToParent(dependentContent, primaryContent) {
-        // Views are not relationship-aware → always stale on PRIMARY change
+    /**
+     * Does this operation address a SCOPE rather than one existing record?
+     *
+     * Everything but a non-bulk READ, UPDATE or DELETE does (`operationAddressesOneRecord`): every collection
+     * verb — LIST, SEARCH, COUNT, CREATE, CREATE_MANY, UPDATE_MANY, DELETE_MANY, read from saas-models'
+     * `ALL_COLLECTION_OPERATIONS` — every BULK variant, and an operation whose verb cannot be resolved. A CREATE
+     * addresses no record yet, only the collection it creates into, and inherits that collection's identifiers.
+     * So none of them has an id of its own: what `getPrimaryResourceIdentifier` reads off its type slot is ambient
+     * scope. A non-bulk READ, UPDATE or DELETE addresses the record its identifiers name (a singleton's READ
+     * names none, and is still one record).
+     *
+     * A context with NO operation at all is treated as a record. An unresolved verb is treated as a scope, which
+     * flipped with the shared predicate (it was a record when this class was hand-closed over three verbs). The
+     * resource factory refuses a custom API-call operation that declares no `resourceOperationLike`, so a
+     * factory-built API operation never has one.
+     */
+    static isScopeAddressedOperationContext(resourceContext) {
+        const operation = resourceContext.operation;
+        return !!operation && !operationAddressesOneRecord(operation);
+    }
+    /**
+     * Do two resource operations show the same TARGET — the same record, or the same scope?
+     *
+     * The zone-dependency cleanup (`NavigationContext`) skips itself when PRIMARY still shows the same target.
+     * A RECORD is the same when its type and id are. A SCOPE-addressed operation (any collection verb, a list or
+     * a CREATE among them — `isScopeAddressedOperationContext`) has no id of its own, so two of them are the same only when their
+     * type and whole scope are: the todos of one list are not the todos of another, and a CREATE pushed over
+     * its own list is the same target as that list, so the panes beside the list stay. A record and a
+     * scope-addressed operation are never the same target, whatever ids they carry.
+     *
+     * The scope is compared by key shape (`FrontendResourceUtils.buildContextResourceIdentifiersKey`), so the
+     * same scope keyed two ways compares as different. That errs toward running the cleanup, which is a
+     * relevance check and keeps every pane that belongs.
+     */
+    static isSameResourceTarget(current, previous) {
+        if (current.resourceType !== previous.resourceType)
+            return false;
+        const currentIsScope = NavigationUtils.isScopeAddressedOperationContext(current);
+        if (currentIsScope !== NavigationUtils.isScopeAddressedOperationContext(previous))
+            return false;
+        if (currentIsScope) {
+            return FrontendResourceUtils.buildContextResourceIdentifiersKey(current.contextResourceIdentifiers)
+                === FrontendResourceUtils.buildContextResourceIdentifiersKey(previous.contextResourceIdentifiers);
+        }
+        return frontendResourceUtils.getPrimaryResourceIdentifier(current)
+            === frontendResourceUtils.getPrimaryResourceIdentifier(previous);
+    }
+    /**
+     * Is a pane's content still current beside the content of the zone it depends on?
+     *
+     * The zone-dependency cleanup (`NavigationContext`) asks it of SECONDARY against PRIMARY's top entry,
+     * and of COMPANION against PRIMARY's top entry or the SECONDARY record beside it (a companion is kept
+     * when either answers yes).
+     *
+     * Relevant when:
+     * - `parentContent` is a SCOPE-ADDRESSED operation of the dependent's own type (its collection, a CREATE into
+     *   it — `isScopeAddressedOperationContext`) whose scope agrees with the dependent's parents (the list-detail
+     *   pairing, #203);
+     * - or `parentContent` is a RECORD the dependent names as a parent, with the same id.
+     *
+     * Stale otherwise — in particular a view (composite/chart) as the dependent, any non-resource
+     * `parentContent`, and a collection or CREATE of the dependent's PARENT type (no id to match: fail-closed).
+     *
+     * @param dependentContent - Content in SECONDARY or COMPANION
+     * @param parentContent - The top content of the zone it is measured against (PRIMARY, or SECONDARY for a companion)
+     * @returns true if the dependent content is still relevant beside `parentContent`
+     */
+    static isContentRelevantToParent(dependentContent, parentContent) {
+        // Views are not relationship-aware → always stale on a change
         if (dependentContent.contentType !== NavigationContentType.RESOURCE_OPERATION) {
             return false;
         }
-        // Primary is not a resource operation → dependent is stale
-        if (primaryContent.contentType !== NavigationContentType.RESOURCE_OPERATION) {
+        // The zone above is not a resource operation → dependent is stale
+        if (parentContent.contentType !== NavigationContentType.RESOURCE_OPERATION) {
             return false;
         }
-        const primaryResourceType = primaryContent.resourceContext.resourceType;
-        const primaryResourceId = frontendResourceUtils.getPrimaryResourceIdentifier(primaryContent.resourceContext);
+        const parentResourceType = parentContent.resourceContext.resourceType;
+        // Only a RECORD has an id to match a dependent's parent against. A scope-addressed operation has none: its
+        // type slot holds at most ambient scope (the quick-switcher's selected record), so reading it as an id
+        // would match a dependent against a record the operation does not address.
+        const parentResourceId = NavigationUtils.isScopeAddressedOperationContext(parentContent.resourceContext)
+            ? null
+            : frontendResourceUtils.getPrimaryResourceIdentifier(parentContent.resourceContext);
         /*
          * SAME-RESOURCE LIST → DETAIL is relevant, and it is checked BEFORE the parent-requirement rule
          * below because that rule cannot see it (#203).
          *
          * A flat resource's detail has no parent requirements — it is a root resource — so the rule below
-         * calls it "not dependent on PRIMARY" and the zone-dependency cleanup clears it. The premise is
+         * calls it "not dependent on the zone above" and the zone-dependency cleanup clears it. The premise is
          * true and the conclusion does not follow: a detail sitting beside its OWN collection is not
          * stale, it is the entire list-detail pattern. `NAVIGATION_LAYOUT_SPLIT` exists to produce exactly
          * this pairing.
@@ -1780,20 +1864,60 @@ export class NavigationUtils {
          * being placed, with no CLEAR_ZONE event to find it by, because this cleanup calls
          * `clearZoneEntries` directly rather than through the bus.
          */
-        if (primaryContent.resourceContext.resourceType === dependentContent.resourceContext.resourceType
-            && NavigationUtils.isCollectionOperationContext(primaryContent.resourceContext)) {
+        /*
+         * The collection must be the dependent's OWN collection, not one of the same type under another parent:
+         * a todo beside the todos of a DIFFERENT list is not its list-detail pairing. Compared only on the
+         * parents the dependent carries, so a flat resource (no parents) is unaffected, and a parent one side
+         * does not carry decides nothing.
+         *
+         * The parents compared are the ones the dependent's requirements name, plus every foreign-key slot it
+         * carries tagged with its own key (`parentUnitId: { fieldIdentifier: 'parentUnitId', resourceId }`). That
+         * tagged slot is how a self-referencing parent is kept apart from the record's own id — the router and
+         * `deriveChildResourceContext` build it — and a context built without requirements still carries it: the
+         * per-row operation context of a list and hostless read navigation pass none.
+         *
+         * Both sides are read the same way: the FOREIGN-KEY slot first (`todoListId`), then the TYPE slot
+         * (`todoLists`). Both shapes are real — a route-built requirement names the foreign key while the context
+         * is keyed by type, and the cascade's sibling list is keyed by the foreign key — so reading one slot alone
+         * found nothing on either side and decided nothing. The type slot is never read for a parent of the
+         * dependent's OWN type: on either side that slot holds the context's own id or ambient scope, and a
+         * self-referencing parent lives in its foreign-key slot (#2143).
+         *
+         * The other side may be any SCOPE-ADDRESSED operation of the dependent's type, not only a collection: a
+         * CREATE into the dependent's own list addresses that list, so the detail beside it stays, as it does
+         * beside the list itself.
+         */
+        const dependentType = dependentContent.resourceContext.resourceType;
+        const dependentIdentifiers = dependentContent.resourceContext.contextResourceIdentifiers ?? {};
+        const parentScopeOf = (resourceContext, parent) => ((parent.foreignKeyField ? NavigationUtils.resolveContextIdentifierValue(resourceContext, parent.foreignKeyField) : undefined)
+            ?? (parent.resourceType !== undefined && parent.resourceType !== dependentType
+                ? NavigationUtils.resolveContextIdentifierValue(resourceContext, parent.resourceType)
+                : undefined));
+        const requirementParents = dependentContent.resourceContext.parentResourcesRequirements ?? [];
+        const taggedForeignKeyParents = Object.entries(dependentIdentifiers)
+            .filter(([key, value]) => key !== dependentType
+            && frontendResourceUtils.getFieldIdentifier(value) === key
+            && !requirementParents.some((requirement) => requirement.foreignKeyField === key))
+            .map(([key]) => ({ foreignKeyField: key }));
+        if (parentContent.resourceContext.resourceType === dependentType
+            && NavigationUtils.isScopeAddressedOperationContext(parentContent.resourceContext)
+            && [...requirementParents, ...taggedForeignKeyParents].every((parent) => {
+                const scopeAbove = parentScopeOf(parentContent.resourceContext, parent);
+                const dependentScope = parentScopeOf(dependentContent.resourceContext, parent);
+                return !scopeAbove || !dependentScope || scopeAbove === dependentScope;
+            })) {
             return true;
         }
         const parentReqs = dependentContent.resourceContext.parentResourcesRequirements;
-        // If dependent has no parent requirements → it's a root resource, not dependent on PRIMARY
+        // If dependent has no parent requirements → it's a root resource, not dependent on the zone above
         if (!parentReqs || parentReqs.length === 0) {
             return false;
         }
         return parentReqs.some((requirement) => {
-            if (requirement.resourceType !== primaryResourceType) {
+            if (requirement.resourceType !== parentResourceType) {
                 return false;
             }
-            if (!primaryResourceId) {
+            if (!parentResourceId) {
                 return false;
             }
             const requirementContextKey = requirement.foreignKeyField ?? requirement.resourceType;
@@ -1801,7 +1925,7 @@ export class NavigationUtils {
             if (!expectedParentId) {
                 return false;
             }
-            return expectedParentId === primaryResourceId;
+            return expectedParentId === parentResourceId;
         });
     }
     // =========================================================================
@@ -1838,8 +1962,11 @@ export class NavigationUtils {
             if (topEntry?.content && 'resourceContext' in topEntry.content) {
                 const topResourceContext = topEntry.content.resourceContext;
                 const topResourceType = topResourceContext?.resourceType;
+                // The parent is visible only when the source zone shows its RECORD: an operation that addresses no record
+                // (its children list, a CREATE) has no id of its own, so a parent id carried there as scope is not the
+                // parent on screen (`getAddressedRecordId`).
                 const topResourceId = topResourceContext
-                    ? frontendResourceUtils.getPrimaryResourceIdentifier(topResourceContext)
+                    ? frontendResourceUtils.getAddressedRecordId(topResourceContext)
                     : undefined;
                 const sourceRelationship = navigationInitiator?.sourceRelationship;
                 if (topResourceType === sourceRelationship?.parentResourceType &&