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

package/dist/esm/core/resources/frontend-resource.utils.js

@@ -1,16 +1,49 @@
 import { CoreResourceOperation, ResourceParentResourceRequirement, ErrorType, ErrorCustomMessageReference, ResourceOperationsUtils, ResourcesConfig_OperationPathUtils, ResourcesConfigOperationsUrlsBuilderUtils, getParentDirectionRelationships, Resources_SharedUtils, PRIMARY_SCOPE_TO_FIELD_IDENTIFIER, RelationshipMutationModel, RelationshipNature, } from "@wildo-ai/saas-models";
 import { ErrorBuilderFrontend } from '../../core/errors/errors-builder.frontend.services.js';
 import { envLoader } from '../../core/runtime/env-variable-loader.frontend.service.js';
-import { pickPreferredOperationForCoreSemantic, resolveEffectiveCoreOperationFromOperation, } from './operation-semantics.frontend.utils.js';
+import { operationAddressesOneRecord, pickPreferredOperationForCoreSemantic, resolveEffectiveCoreOperationFromOperation, } from './operation-semantics.frontend.utils.js';
 import { AutomatedLayoutFrontendUtils } from '../../core/automated-layout/automated-layout.frontend.utils.js';
 import { isSummaryField, isHiddenForDisplay } from '@wildo-ai/zod-decorators';
 import { BACKEND_ONLY_I18N_SECTIONS } from '@wildo-ai/presets-components-models';
-import { describeCaughtError } from '@wildo-ai/saas-models';
+import { describeCaughtError, resolveSchemaForObject, resourceInheritanceVariantSchemas } from '@wildo-ai/saas-models';
 /**
  * Singleton utility class for frontend resource operations
  * Provides centralized helper functions for resource context management
  */
 export class FrontendResourceUtils {
+    /**
+     * The schema ONE row of a resource is described by (#2455): for an inheritance resource, the variant its own
+     * discriminator values name (`resolveSchemaForObject`), else its `mainSchema`. A family registers its BASE as
+     * `mainSchema`, so a surface that renders one row from the base alone renders its variant fields untyped or not at
+     * all. A variant's schema never describes a row of another variant.
+     */
+    static resolveRowSchema(resourceConfig, row) {
+        const mainSchema = resourceConfig?.mainSchema;
+        if (!mainSchema || !row || !resourceConfig?.inheritenceSchemaDefinition)
+            return mainSchema;
+        return resolveSchemaForObject(mainSchema, resourceConfig.inheritenceSchemaDefinition, row);
+    }
+    /**
+     * Every top-level field SOME row of a resource can hold (#2455): its base, then each field only an inheritance variant
+     * declares, the base's copy kept for a field both declare. For a surface over many rows (table columns, a filter, a
+     * field lookup by name), where no one row decides the shape. `undefined` when the main schema has no object shape.
+     */
+    static resolveFieldShapeOfAnyVariant(resourceConfig) {
+        const mainSchema = resourceConfig?.mainSchema;
+        if (!mainSchema)
+            return undefined;
+        const baseShape = AutomatedLayoutFrontendUtils.getObjectLikeFieldShape(mainSchema, { commonOnly: false });
+        if (!baseShape)
+            return undefined;
+        const shape = { ...baseShape };
+        for (const variant of resourceInheritanceVariantSchemas(resourceConfig?.inheritenceSchemaDefinition)) {
+            for (const [fieldName, fieldSchema] of Object.entries(AutomatedLayoutFrontendUtils.getObjectLikeFieldShape(variant, { commonOnly: false }) ?? {})) {
+                if (!(fieldName in shape))
+                    shape[fieldName] = fieldSchema;
+            }
+        }
+        return shape;
+    }
     static instance;
     errorBuilder;
     constructor() {
@@ -578,8 +611,24 @@ export class FrontendResourceUtils {
         return [...sections].sort();
     }
     /**
-     * Compute a resource label using the canonical resource configuration contract:
-     * `resourceConfig.frontendConfiguration.getFrontendResourceLabel`.
+     * How a resource names its records (#2666 S7, #2775): the resource's `recordLabelFields` (the name the backend's chat
+     * surface reads too, joined like any `string[]` strategy), else its ui-behavior's own `getFrontendResourceLabel`. The
+     * registry refuses a resource declaring both, so a record never has two names; reading `recordLabelFields` first keeps
+     * that true for a configuration built outside the registry.
+     *
+     * The ONE reader of a record's naming strategy: every label surface asks it. A resource with no ui-behavior keeps no
+     * `frontendConfiguration`, because that still means "this resource has a ui-behavior" to the launcher (re-review R8),
+     * and still names its records here.
+     */
+    static frontendResourceLabelDefinitionOf(config) {
+        const declared = config?.recordLabelFields;
+        if (declared && declared.length > 0)
+            return [...declared];
+        return config?.frontendConfiguration?.getFrontendResourceLabel;
+    }
+    /**
+     * Compute a resource label using the canonical resource configuration contract: the resource's `recordLabelFields`,
+     * else `resourceConfig.frontendConfiguration.getFrontendResourceLabel` ({@link frontendResourceLabelDefinitionOf}).
      *
      * - If config label is a `string[]`, we join non-empty values with a space.
      * - If config label is a function, we call it with `t` and (optional) context.
@@ -597,7 +646,7 @@ export class FrontendResourceUtils {
             return null;
         const obj = currentObject;
         const config = registry.resourceConfigurations?.[resourceType];
-        const labelDef = config?.frontendConfiguration?.getFrontendResourceLabel;
+        const labelDef = FrontendResourceUtils.frontendResourceLabelDefinitionOf(config);
         const { t } = params;
         try {
             if (Array.isArray(labelDef)) {
@@ -627,8 +676,8 @@ export class FrontendResourceUtils {
             // ignore and fall back
         }
         // No config-defined label strategy — flag as configuration gap
-        console.error(`[FrontendResourceUtils] No getFrontendResourceLabel configured for "${resourceType}". ` +
-            `Add getFrontendResourceLabel to frontendConfiguration.`);
+        console.error(`[FrontendResourceUtils] No record label configured for "${resourceType}". ` +
+            `Declare recordLabelFields on the resource (which also names its records in a chat), or getFrontendResourceLabel in its frontendConfiguration.`);
         /*
          * Fallback: the record's own DECLARED SUMMARY FIELDS.
          *
@@ -721,12 +770,9 @@ export class FrontendResourceUtils {
         return fieldName === primaryScopeFieldIdentifier;
     }
     static detectSummaryFields(resourceConfig) {
-        const mainSchema = resourceConfig?.mainSchema;
-        if (!mainSchema)
-            return [];
-        // Polymorphic resources feed a discriminated-union schema; resolve the union-aware field shape
-        // (else getObjectShape returns null for the union → no field labels).
-        const shape = AutomatedLayoutFrontendUtils.getObjectLikeFieldShape(mainSchema, { commonOnly: false }) ?? null;
+        // Every field some row can hold (#2455): a summary field only an inheritance variant declares is a summary field of
+        // the resource. (A family's `mainSchema` is its base object since #2414, not a discriminated union.)
+        const shape = FrontendResourceUtils.resolveFieldShapeOfAnyVariant(resourceConfig) ?? null;
         if (!shape)
             return [];
         const fieldIdentifier = resourceConfig?.resourceFieldIdentifier;
@@ -832,6 +878,109 @@ export class FrontendResourceUtils {
         }
         return typeof value === 'string' ? null : (value.fieldIdentifier || null);
     }
+    /**
+     * The foreign-key field identifiers of a resource type's self-referencing relationships (`parentUnitId`
+     * for organization units). A route parameter or identifier slot named by one of them stands for a PARENT
+     * of the same type, never for the record itself.
+     */
+    selfReferenceForeignKeysOf(resourceType, registry) {
+        return (registry.resourceConfigurations[resourceType]?.resourceRelationships?.selfRelationships ?? [])
+            .map((relationship) => Resources_SharedUtils.tryResolveRelationshipForeignKeyIdentity(relationship, registry.allResourceFieldIdentifiers)?.fieldIdentifier)
+            .filter((fieldIdentifier) => fieldIdentifier !== undefined);
+    }
+    /**
+     * The id of the ONE record an operation context addresses, or null when it addresses none.
+     *
+     * An operation that addresses no record (`operationAddressesOneRecord`: a collection verb, a CREATE, a bulk
+     * variant) has no id of its own, so its own-type slot is never read as one: it holds at most ambient scope —
+     * the quick-switcher's selected record, merged into every route's identifiers, or (before #2143) a
+     * self-referencing parent. The automated form read it regardless, so a CREATE took that id as the id of the
+     * record it was about to create. A context with no operation is read as a record.
+     */
+    getAddressedRecordId(context) {
+        if (context.operation && !operationAddressesOneRecord(context.operation))
+            return null;
+        return this.getResourceId(context.contextResourceIdentifiers?.[context.resourceType]) || null;
+    }
+    /**
+     * A host's identifiers or contextual parameters without the slots keyed by one of `resourceType`'s
+     * self-referencing foreign keys (`parentUnitId`). For a step that addresses NO particular record of that type
+     * — a picker searching its population, a quick-create of a new one — the host's self-referencing parent
+     * describes only the host and would narrow or misplace the step: a same-type picker would search the
+     * host's siblings, a quick-created unit would be filed under the host's parent (#2144).
+     */
+    withoutSelfReferencingParents(record, resourceType, registry) {
+        const parentKeys = this.selfReferenceForeignKeysOf(resourceType, registry);
+        return Object.fromEntries(Object.entries(record).filter(([key]) => !parentKeys.includes(key)));
+    }
+    /**
+     * A host's context, scoped to ONE record the host REFERENCES (a foreign-key link, its label fetch, its
+     * overlay) — the identifiers, contextual parameters and parent requirements a reference display carries over
+     * from the page it sits on (#2144).
+     *
+     * A self-referencing parent slot the host carries (`parentUnitId`) describes the parent of the host's own
+     * record of that type. It is right for a reference to that same record (a member page linking to its unit),
+     * and wrong for any other record of the type: carried over, it names a parent the target does not have. A
+     * unit's link to its own parent u-1 was resolved as u-1 under u-1, and its label fetched from that route.
+     * So, unless the target IS the host's record, every slot, parameter and requirement keyed by one of the
+     * type's self-referencing foreign keys is dropped; everything else (organization, other parents) is kept.
+     * With nothing left to place the target under its parent, the standalone READ route is chosen, which is the
+     * honest one: the target's own parent is not known here.
+     *
+     * This is the HOST-scoped primitive. Callers reach a referenced record through `scopeReferencedRecord`
+     * (`referenced-record-scope.frontend.utils.ts`), which narrows this further to the tenancy whenever the target is
+     * readable there (#2741): a non-self-referencing parent the host carries is not known to be the target's either.
+     *
+     * The host's record is what the HOST says it renders (`hostRecord`: a display's or a form's `resourceType` +
+     * `resourceId`), never what its type slot holds: on a list or a CREATE that slot is ambient scope (the
+     * quick-switcher's selection), and reading it as the host's record kept the host's parent for a reference to
+     * a record the host does not show.
+     */
+    scopeHostContextToReferencedRecord(params) {
+        const parentRequirements = params.hostParentRequirements ?? [];
+        if (this.isReferencedTargetTheHostRecord(params)) {
+            return { identifiers: { ...params.hostIdentifiers }, contextualParameters: { ...params.hostContextualParameters }, parentRequirements };
+        }
+        const hostParentKeys = this.selfReferenceForeignKeysOf(params.targetResourceType, params.registry);
+        return {
+            identifiers: this.withoutSelfReferencingParents(params.hostIdentifiers, params.targetResourceType, params.registry),
+            contextualParameters: this.withoutSelfReferencingParents(params.hostContextualParameters, params.targetResourceType, params.registry),
+            parentRequirements: parentRequirements.filter((requirement) => !(requirement.resourceType === params.targetResourceType
+                && requirement.foreignKeyField !== undefined
+                && hostParentKeys.includes(requirement.foreignKeyField))),
+        };
+    }
+    /**
+     * Whether a referenced target IS the record its host renders (same type, same id) — the one case where the host's
+     * whole context describes the target. ONE definition, shared by `scopeHostContextToReferencedRecord` and the
+     * tenancy narrowing of `scopeReferencedRecord`.
+     */
+    isReferencedTargetTheHostRecord(params) {
+        return params.hostRecord?.resourceType === params.targetResourceType
+            && !!params.hostRecord.id
+            && params.hostRecord.id === params.targetId;
+    }
+    /**
+     * The identifiers of ONE RECORD of a collection, built from the collection's own identifiers: the
+     * record's id goes in its type slot, and whatever else scoped the collection is kept.
+     *
+     * The collection's own type slot holds at most AMBIENT scope (the quick-switcher's selected record, for
+     * instance), which the record's id replaces. A self-referencing parent is never there: the router and
+     * `deriveChildResourceContext` key it by its foreign key (`parentUnitId`), so it survives this as it is —
+     * the shape the router builds for the record's own URL (#2143). Until that was so, this function moved a
+     * parent the router had left in the type slot; the producers were fixed instead.
+     *
+     * Used wherever a collection's row, or a record just created in it, becomes a record: a list row click,
+     * its per-row operations and can-read check, a search result click, the create reveal, hostless read
+     * navigation and inline edit.
+     *
+     * @param collectionIdentifiers - the collection's `contextResourceIdentifiers`
+     * @param resourceType - the collection's resource type, which is the record's
+     * @param recordId - the id of the record that was chosen or created
+     */
+    buildRecordIdentifiersFromCollection(collectionIdentifiers, resourceType, recordId) {
+        return { ...(collectionIdentifiers ?? {}), [resourceType]: recordId };
+    }
     /**
      * Flatten contextResourceIdentifiers to simple string values.
      * Handles both string and object formats ({ fieldIdentifier, resourceId }).
@@ -884,13 +1033,19 @@ export class FrontendResourceUtils {
      * For self-referencing trees (e.g., ORGANIZATION_UNITS), both parent and child
      * share the same resource type, so the second entry would overwrite the first.
      *
-     * Solution: when a resource type appears multiple times in routePathParameters
-     * (detected via `typeCount`), the **non-default** FK param (e.g., `parentUnitId`)
-     * uses the **FK field name** as the map key instead of the resource type.
+     * Solution: a **non-default** param that is one of its type's self-referencing foreign keys
+     * (e.g., `parentUnitId`) uses the **FK field name** as the map key instead of the resource type —
+     * whether the type appears twice in the route (`/…/:parentUnitId/…/:unitId`, the record) or once
+     * (`/…/:parentUnitId/organization-units`, its children list, and every CREATE opened from it).
      * `buildContextualParameters` already handles complex values via `fieldIdentifier`,
      * so the correct URL parameter (`parentUnitId=abc`) is produced without any
      * changes to downstream callers.
      *
+     * Until 2026-10-01 only the twice-appearing case was detected (`typeCount`), so a children list kept its
+     * parent in its own TYPE slot, where every reader of "this context's own id" took the parent for the
+     * record: the zone cleanup, the relevance rule, a row click, the create reveal, the automated form's
+     * `resourceId` (#2143). Its type slot now holds nothing, which is what a collection's own id is.
+     *
      * @param urlParameters - The URL parameters from React Router
      * @param registry - The resources registry
      * @param routePathParameters - Route path parameters for accurate FK field mapping
@@ -900,7 +1055,7 @@ export class FrontendResourceUtils {
         // If routePathParameters provided, use them for accurate mapping
         // This handles FK fields like assignedToUserId correctly
         if (routePathParameters && routePathParameters.length > 0) {
-            // Detect resource types that appear multiple times (self-referencing relationships)
+            // A type appearing twice in one route is a self-referencing chain (parent + record).
             const typeCount = new Map();
             for (const p of routePathParameters) {
                 typeCount.set(p.resourceType, (typeCount.get(p.resourceType) || 0) + 1);
@@ -911,13 +1066,16 @@ export class FrontendResourceUtils {
                     const resourceConfig = registry.resourceConfigurations[paramInfo.resourceType];
                     const isDefaultField = resourceConfig &&
                         resourceConfig.resourceFieldIdentifier === paramInfo.fieldIdentifier;
-                    const isSelfRefType = (typeCount.get(paramInfo.resourceType) || 0) > 1;
+                    // A self-referencing parent: the route names its type twice, or the param is one of the type's
+                    // self-referencing foreign keys (a children list names its type once, through the parent).
+                    const namesSelfReferencingParent = (typeCount.get(paramInfo.resourceType) || 0) > 1
+                        || this.selfReferenceForeignKeysOf(paramInfo.resourceType, registry).includes(paramInfo.fieldIdentifier);
                     if (isDefaultField) {
                         resourceIdentifiers[paramInfo.resourceType] = paramValue;
                     }
-                    else if (isSelfRefType) {
+                    else if (namesSelfReferencingParent) {
                         // Self-ref FK field (e.g., parentUnitId for ORGANIZATION_UNITS → ORGANIZATION_UNITS).
-                        // Use the FK field name as the map key to avoid overwriting the resource's own entry.
+                        // Keyed by the FK field name, so the type slot is left for the context's OWN id.
                         // buildContextualParameters handles this via the complex value's fieldIdentifier.
                         resourceIdentifiers[paramInfo.fieldIdentifier] = {
                             fieldIdentifier: paramInfo.fieldIdentifier,
@@ -934,7 +1092,11 @@ export class FrontendResourceUtils {
             }
             return resourceIdentifiers;
         }
-        // Fallback: use registry-based mapping for backwards compatibility
+        // Fallback: use registry-based mapping for backwards compatibility. The map holds only each type's DEFAULT
+        // identifier field, so a foreign-key param — a self-referencing parent such as `parentUnitId` included — is
+        // not mapped here and is dropped, never keyed into a type slot (#2143). Every caller passes
+        // `routePathParameters` (`AppRouter`, both `useNavigationRouterSync` sites, the AppScope URL bridge in
+        // `NavigationContext`), so this branch does not meet one today.
         const fieldToResourceMap = this.buildResourceFieldIdentifierToResourceIdentifierMap(registry);
         for (const [paramName, paramValue] of Object.entries(urlParameters)) {
             // Look up the resource identifier using the registry mapping
@@ -1326,7 +1488,9 @@ export class FrontendResourceUtils {
      *    (e.g., `parentUnitId` for ORGANIZATION_UNITS).
      * 2. If yes, move the parent's ID to a FK-keyed slot
      *    (`contextResourceIdentifiers["parentUnitId"] = { fieldIdentifier, resourceId }`).
-     * 3. Then write the child's ID under the resource type key.
+     * 3. Then write the child's ID under the resource type key — or, for a child with no id of its own
+     *    (its children LIST, a CREATE under the parent), leave the type key EMPTY, so the parent is never
+     *    read as the child's own id (#2143).
      *
      * Downstream, `buildContextualParameters` produces both URL parameters
      * (`unitId=child` + `parentUnitId=parent`) from this structure.
@@ -1391,6 +1555,14 @@ export class FrontendResourceUtils {
                         fieldIdentifier: selfRefForeignKey,
                         resourceId: parentId,
                     };
+                    // A child with no id of its own (the children LIST, a CREATE under the parent) must not keep the
+                    // parent in its type slot as well: that slot is read as the context's OWN id — the zone cleanup,
+                    // the relevance rule, a row click, the automated form's `resourceId` — and each took the parent for
+                    // the record (#2143). The parent now lives only in its foreign-key slot, the shape the router gives
+                    // the same list.
+                    if (!childConfig.resourceId) {
+                        delete contextResourceIdentifiers[childConfig.resourceType];
+                    }
                 }
             }
         }