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

package/dist/esm/components/resources/skeleton/section-consolidation.utils.js

@@ -10,7 +10,8 @@
  */
 import { isValidElement } from 'react';
 import { Section } from './Section.js';
-import { buildSectionConfigFromSectionLikeGroup, groupSectionLikeElementsByAppearance, } from '../../../components/sections/section-grouping.shared.js';
+import { LoggerFrontendService } from '../../../core/monitoring/logger.frontend.service.js';
+import { buildSectionConfigFromSectionLikeGroup, expandableGroupNeverTruncates, groupSectionLikeElementsByAppearance, } from '../../../components/sections/section-grouping.shared.js';
 export { isSoloMode, toDisplayChromeMode } from './section-consolidation.shared.js';
 // =============================================================================
 // SECTION ELEMENT DETECTION
@@ -19,6 +20,12 @@ export { isSoloMode, toDisplayChromeMode } from './section-consolidation.shared.
 export function isSectionElement(child) {
     return isValidElement(child) && child.type === Section;
 }
+// =============================================================================
+// SECTION GROUPING FOR LAYOUT COMPONENTS
+// =============================================================================
+const logger = LoggerFrontendService.getLogger();
+/** One warning per authored group (its section names), not one per render. */
+const warnedNeverTruncatingExpandableGroups = new Set();
 /**
  * Groups children by their `appearance` mode for layout rendering.
  *
@@ -35,7 +42,29 @@ export function isSectionElement(child) {
  *   [group(TABS: [section0, section2]), node(section1-CARD), group(ACCORDION: [section3])]
  */
 export function groupSectionsByAppearance(children, defaultAppearance) {
-    return groupSectionLikeElementsByAppearance(children, isSectionElement, defaultAppearance);
+    const grouped = groupSectionLikeElementsByAppearance(children, isSectionElement, defaultAppearance);
+    if (process.env.NODE_ENV !== 'production')
+        warnOnNeverTruncatingExpandableGroups(grouped);
+    return grouped;
+}
+/**
+ * Footgun guard, the sibling of `Section`'s ungrouped-container warning: an EXPANDABLE group that holds
+ * no more sections than it shows before "Show more" renders them all open with no button, which reads
+ * as a template that asked for a toggle and silently got none (#2197). Every layout host (`FormLayout`,
+ * `DisplayLayout`, `CompositeLayout`) groups through this function, so the check covers all three.
+ * It warns rather than throws: the page is still correct, only its author's intent is unmet.
+ */
+function warnOnNeverTruncatingExpandableGroups(grouped) {
+    for (const item of grouped.items) {
+        if (item.type !== 'group' || !expandableGroupNeverTruncates(item.group))
+            continue;
+        const sectionNames = item.group.sections.map((section) => section.props.name);
+        const warnKey = sectionNames.join('|');
+        if (warnedNeverTruncatingExpandableGroups.has(warnKey))
+            continue;
+        warnedNeverTruncatingExpandableGroups.add(warnKey);
+        logger.warn(`[Section] EXPANDABLE group (${sectionNames.join(', ')}) holds ${sectionNames.length} section(s), no more than it shows before "Show more", so it renders every section open with no button. EXPANDABLE truncates a GROUP of sections; to hide one section until the reader opens it, use appearance={SectionMode.COLLAPSIBLE} with defaultFocus={false}.`, { sectionNames });
+    }
 }
 /**
  * Builds a `SectionConfig` from the first section in a group.

package/dist/esm/components/resources/skeleton/section-consolidation.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"section-consolidation.utils.js","sourceRoot":"","sources":["../../../../../../src/components/resources/skeleton/section-consolidation.utils.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb;;;;;;;;GAQG;AAEH,OAAc,EAAkB,cAAc,EAAqB,MAAM,OAAO,CAAC;AACjF,OAAO,EAAE,OAAO,EAAqB,MAAM,WAAW,CAAC;AACvD,OAAO,EACL,sCAAsC,EACtC,oCAAoC,GAIrC,MAAM,iEAAiE,CAAC;AACzE,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAEjF,gFAAgF;AAChF,4BAA4B;AAC5B,gFAAgF;AAEhF,uDAAuD;AACvD,MAAM,UAAU,gBAAgB,CAAC,KAAgB;IAC/C,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC;AACzD,CAAC;AASD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,yBAAyB,CACvC,QAAmB,EACnB,iBAAwC;IAExC,OAAO,oCAAoC,CAAC,QAAQ,EAAE,gBAAgB,EAAE,iBAAiB,CAAC,CAAC;AAC7F,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CAAC,KAAmB;IAC7D,OAAO,sCAAsC,CAAC,KAAK,CAAC,CAAC;AACvD,CAAC","sourcesContent":["'use client';\n\n/**\n * Section Consolidation Utilities\n *\n * Provides shared helpers used by the Section component and layout grouping:\n * - `toDisplayChromeMode`: coerces `ResponsiveChromeMode` to `DisplayChromeMode`\n * - `isSectionElement`: type guard for `<Section>` elements\n * - `groupSectionsByAppearance`: groups sibling `<Section>` children by their\n *   `appearance` prop for layout rendering\n */\n\nimport React, { type ReactNode, isValidElement, type ReactElement } from 'react';\nimport { Section, type SectionProps } from './Section';\nimport {\n  buildSectionConfigFromSectionLikeGroup,\n  groupSectionLikeElementsByAppearance,\n  type ContainerSectionMode,\n  type GroupedSectionLikeChildren,\n  type SectionLikeGroup,\n} from '~wildo-frontend-lib/components/sections/section-grouping.shared';\nexport { isSoloMode, toDisplayChromeMode } from './section-consolidation.shared';\n\n// =============================================================================\n// SECTION ELEMENT DETECTION\n// =============================================================================\n\n/** Type guard: is this child a `<Section>` element? */\nexport function isSectionElement(child: ReactNode): child is ReactElement<SectionProps> {\n  return isValidElement(child) && child.type === Section;\n}\n\n// =============================================================================\n// SECTION GROUPING FOR LAYOUT COMPONENTS\n// =============================================================================\n\nexport type SectionGroup = SectionLikeGroup<SectionProps>;\nexport type GroupedLayoutChildren = GroupedSectionLikeChildren<SectionProps>;\n\n/**\n * Groups children by their `appearance` mode for layout rendering.\n *\n * - Solo mode sections (DEFAULT, CARD, GHOST, COLLAPSIBLE) and non-Section children\n *   are kept in place as individual nodes.\n * - Container mode sections are grouped by their mode. The group is placed at the\n *   position of the **first** occurrence of that mode.\n * - Subsequent sections with the same container mode are collected into the group\n *   (not rendered individually).\n *\n * @example\n * Given children: [Section(TABS), Section(CARD), Section(TABS), Section(ACCORDION)]\n * Result items:\n *   [group(TABS: [section0, section2]), node(section1-CARD), group(ACCORDION: [section3])]\n */\nexport function groupSectionsByAppearance(\n  children: ReactNode,\n  defaultAppearance?: ContainerSectionMode,\n): GroupedLayoutChildren {\n  return groupSectionLikeElementsByAppearance(children, isSectionElement, defaultAppearance);\n}\n\n/**\n * Builds a `SectionConfig` from the first section in a group.\n * The first section's props define the container-level parameters.\n */\nexport function buildSectionConfigFromGroup(group: SectionGroup) {\n  return buildSectionConfigFromSectionLikeGroup(group);\n}\n"]}
+{"version":3,"file":"section-consolidation.utils.js","sourceRoot":"","sources":["../../../../../../src/components/resources/skeleton/section-consolidation.utils.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb;;;;;;;;GAQG;AAEH,OAAc,EAAkB,cAAc,EAAqB,MAAM,OAAO,CAAC;AACjF,OAAO,EAAE,OAAO,EAAqB,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,6DAA6D,CAAC;AACpG,OAAO,EACL,sCAAsC,EACtC,6BAA6B,EAC7B,oCAAoC,GAIrC,MAAM,iEAAiE,CAAC;AACzE,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAEjF,gFAAgF;AAChF,4BAA4B;AAC5B,gFAAgF;AAEhF,uDAAuD;AACvD,MAAM,UAAU,gBAAgB,CAAC,KAAgB;IAC/C,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC;AACzD,CAAC;AAED,gFAAgF;AAChF,yCAAyC;AACzC,gFAAgF;AAEhF,MAAM,MAAM,GAAG,qBAAqB,CAAC,SAAS,EAAE,CAAC;AAEjD,8EAA8E;AAC9E,MAAM,qCAAqC,GAAG,IAAI,GAAG,EAAU,CAAC;AAKhE;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,yBAAyB,CACvC,QAAmB,EACnB,iBAAwC;IAExC,MAAM,OAAO,GAAG,oCAAoC,CAAC,QAAQ,EAAE,gBAAgB,EAAE,iBAAiB,CAAC,CAAC;IACpG,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;QAAE,qCAAqC,CAAC,OAAO,CAAC,CAAC;IAC1F,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,qCAAqC,CAAC,OAA8B;IAC3E,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QACjC,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,6BAA6B,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,SAAS;QAClF,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9E,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,qCAAqC,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,SAAS;QACjE,qCAAqC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACnD,MAAM,CAAC,IAAI,CACT,+BAA+B,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,YAAY,CAAC,MAAM,sQAAsQ,EAC1V,EAAE,YAAY,EAAE,CACjB,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CAAC,KAAmB;IAC7D,OAAO,sCAAsC,CAAC,KAAK,CAAC,CAAC;AACvD,CAAC","sourcesContent":["'use client';\n\n/**\n * Section Consolidation Utilities\n *\n * Provides shared helpers used by the Section component and layout grouping:\n * - `toDisplayChromeMode`: coerces `ResponsiveChromeMode` to `DisplayChromeMode`\n * - `isSectionElement`: type guard for `<Section>` elements\n * - `groupSectionsByAppearance`: groups sibling `<Section>` children by their\n *   `appearance` prop for layout rendering\n */\n\nimport React, { type ReactNode, isValidElement, type ReactElement } from 'react';\nimport { Section, type SectionProps } from './Section';\nimport { LoggerFrontendService } from '~wildo-frontend-lib/core/monitoring/logger.frontend.service';\nimport {\n  buildSectionConfigFromSectionLikeGroup,\n  expandableGroupNeverTruncates,\n  groupSectionLikeElementsByAppearance,\n  type ContainerSectionMode,\n  type GroupedSectionLikeChildren,\n  type SectionLikeGroup,\n} from '~wildo-frontend-lib/components/sections/section-grouping.shared';\nexport { isSoloMode, toDisplayChromeMode } from './section-consolidation.shared';\n\n// =============================================================================\n// SECTION ELEMENT DETECTION\n// =============================================================================\n\n/** Type guard: is this child a `<Section>` element? */\nexport function isSectionElement(child: ReactNode): child is ReactElement<SectionProps> {\n  return isValidElement(child) && child.type === Section;\n}\n\n// =============================================================================\n// SECTION GROUPING FOR LAYOUT COMPONENTS\n// =============================================================================\n\nconst logger = LoggerFrontendService.getLogger();\n\n/** One warning per authored group (its section names), not one per render. */\nconst warnedNeverTruncatingExpandableGroups = new Set<string>();\n\nexport type SectionGroup = SectionLikeGroup<SectionProps>;\nexport type GroupedLayoutChildren = GroupedSectionLikeChildren<SectionProps>;\n\n/**\n * Groups children by their `appearance` mode for layout rendering.\n *\n * - Solo mode sections (DEFAULT, CARD, GHOST, COLLAPSIBLE) and non-Section children\n *   are kept in place as individual nodes.\n * - Container mode sections are grouped by their mode. The group is placed at the\n *   position of the **first** occurrence of that mode.\n * - Subsequent sections with the same container mode are collected into the group\n *   (not rendered individually).\n *\n * @example\n * Given children: [Section(TABS), Section(CARD), Section(TABS), Section(ACCORDION)]\n * Result items:\n *   [group(TABS: [section0, section2]), node(section1-CARD), group(ACCORDION: [section3])]\n */\nexport function groupSectionsByAppearance(\n  children: ReactNode,\n  defaultAppearance?: ContainerSectionMode,\n): GroupedLayoutChildren {\n  const grouped = groupSectionLikeElementsByAppearance(children, isSectionElement, defaultAppearance);\n  if (process.env.NODE_ENV !== 'production') warnOnNeverTruncatingExpandableGroups(grouped);\n  return grouped;\n}\n\n/**\n * Footgun guard, the sibling of `Section`'s ungrouped-container warning: an EXPANDABLE group that holds\n * no more sections than it shows before \"Show more\" renders them all open with no button, which reads\n * as a template that asked for a toggle and silently got none (#2197). Every layout host (`FormLayout`,\n * `DisplayLayout`, `CompositeLayout`) groups through this function, so the check covers all three.\n * It warns rather than throws: the page is still correct, only its author's intent is unmet.\n */\nfunction warnOnNeverTruncatingExpandableGroups(grouped: GroupedLayoutChildren): void {\n  for (const item of grouped.items) {\n    if (item.type !== 'group' || !expandableGroupNeverTruncates(item.group)) continue;\n    const sectionNames = item.group.sections.map((section) => section.props.name);\n    const warnKey = sectionNames.join('|');\n    if (warnedNeverTruncatingExpandableGroups.has(warnKey)) continue;\n    warnedNeverTruncatingExpandableGroups.add(warnKey);\n    logger.warn(\n      `[Section] EXPANDABLE group (${sectionNames.join(', ')}) holds ${sectionNames.length} section(s), no more than it shows before \"Show more\", so it renders every section open with no button. EXPANDABLE truncates a GROUP of sections; to hide one section until the reader opens it, use appearance={SectionMode.COLLAPSIBLE} with defaultFocus={false}.`,\n      { sectionNames },\n    );\n  }\n}\n\n/**\n * Builds a `SectionConfig` from the first section in a group.\n * The first section's props define the container-level parameters.\n */\nexport function buildSectionConfigFromGroup(group: SectionGroup) {\n  return buildSectionConfigFromSectionLikeGroup(group);\n}\n"]}

package/dist/esm/components/resources-fields/_presets/resource-reference/ResourceFieldDisplayPreset_ResourceReference_Default.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ResourceFieldDisplayPreset_ResourceReference_Default.d.ts","sourceRoot":"","sources":["../../../../../../src/components/resources-fields/_presets/resource-reference/ResourceFieldDisplayPreset_ResourceReference_Default.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAA4D,MAAM,OAAO,CAAC;AAsBjF,OAAO,KAAK,EAAE,yDAAyD,EAAE,MAAM,2GAA2G,CAAC;AAwD3L,eAAO,MAAM,oDAAoD,GAAI,gIASlE,yDAAyD,KAAG,KAAK,CAAC,GAAG,CAAC,OAyrBxE,CAAC"}
+{"version":3,"file":"ResourceFieldDisplayPreset_ResourceReference_Default.d.ts","sourceRoot":"","sources":["../../../../../../../src/components/resources-fields/_presets/resource-reference/ResourceFieldDisplayPreset_ResourceReference_Default.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAA4D,MAAM,OAAO,CAAC;AAyBjF,OAAO,KAAK,EAAE,yDAAyD,EAAE,MAAM,2GAA2G,CAAC;AA8D3L,eAAO,MAAM,oDAAoD,GAAI,gIASlE,yDAAyD,KAAG,KAAK,CAAC,GAAG,CAAC,OAwyBxE,CAAC"}

package/dist/esm/components/resources-fields/_presets/resource-reference/ResourceFieldDisplayPreset_ResourceReference_Default.js

@@ -17,13 +17,16 @@ import { Text } from '../../../../components/typography/text.js';
 import { useEventBus } from '../../../../core/events/useEventBus.js';
 import { FrontendEvents } from '../../../../core/events/events.frontend.schemas.js';
 import { useResourceRegistry } from '../../../../core/resources/useResourceRegistry.js';
-import { DEFAULT_FOREIGN_KEY_DISPLAY_MODE, ForeignKeyDisplayMode, getForeignKeyParams } from '@wildo-ai/zod-decorators';
+import { DEFAULT_FOREIGN_KEY_DISPLAY_MODE, ForeignKeyDisplayMode } from '@wildo-ai/zod-decorators';
 import { FrontendComponentType, TextVariant } from '@wildo-ai/presets-components-models';
 import { useI18n } from '../../../../core/i18n/useI18n.js';
 import { cn } from '../../../../core/ui/cn.js';
+import { FocusIndicatorShape, focusIndicatorClasses } from '../../../../core/ui/themes/focus-indicator.js';
 import { FrontendResourceUtils, frontendResourceUtils } from '../../../../core/resources/frontend-resource.utils.js';
 import { pickPreferredOperationForCoreSemanticAddressability } from '../../../../core/resources/resource-addressability.frontend.utils.js';
-import { useResourceDisplayContext } from '../../../../components/data-display/automatic-displayer.utils.js';
+import { scopeReferencedRecord } from '../../../../core/resources/referenced-record-scope.frontend.utils.js';
+import { useResourceDisplayContext, withoutHiddenParentReference } from '../../../../components/data-display/automatic-displayer.utils.js';
+import { resolveForeignKeyReferencedResourceType } from '../../../../components/data-display/reference-display-target.js';
 import { useOptionalFormSchemaContext } from '../../../../components/form/useFormSchemaContext.js';
 import { CoreResourceOperation, ParentDisplay, ResourcesConfigOperationsUrlsBuilderUtils } from '@wildo-ai/saas-models';
 import { NavigationContentType, NavigationZone } from '../../../../core/navigation/navigation.schemas.js';
@@ -56,6 +59,11 @@ function resolvePrePopulatedRecordIdentifier(params) {
  * carries `text-primary`, and the default variant would paint the label in the foreground colour —
  * every linkable reference in every application would stop looking like a link.
  */
+/**
+ * A SUMMARY reference's link: a block in the text colour around its card, with the focus contract's offset ring and a
+ * quiet hover, never the inline link's colour and underline.
+ */
+const SUMMARY_LINK_CLASSES = cn('block rounded-md text-inherit no-underline transition-colors hover:bg-muted/40', focusIndicatorClasses(FocusIndicatorShape.OFFSET));
 function ReferenceLabel({ label }) {
     return _jsx(Text, { as: "span", variant: TextVariant.INHERIT, children: label });
 }
@@ -67,14 +75,13 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
     /*
      * Target resolution precedence: an explicit prop (the dispatcher's per-record polymorphic
      * resolution) → the decorator's declared `referencedResourceType` (an FK named in its own
-     * vocabulary — see the param's JSDoc) → the field-name map, which THROWS on a miss because an
-     * unresolvable FK is a configuration error.
+     * vocabulary — see the param's JSDoc) → the field-name map (`resolveForeignKeyReferencedResourceType`, the
+     * resolver `DisplayField` reads too) — and on a miss the field-name lookup THROWS, because an unresolvable FK
+     * is a configuration error.
      */
-    const declaredReferencedType = schema ? getForeignKeyParams(schema)?.referencedResourceType : undefined;
-    const resourceType = resourceTypeProp
-        || declaredReferencedType
+    const resourceType = resolveForeignKeyReferencedResourceType({ explicitResourceType: resourceTypeProp, schema, fieldName, registry })
         || FrontendResourceUtils.resolveResourceTypeForForeignKey(fieldName, schema, registry);
-    const { t, formatDate, formatDateTime, isReady } = useI18n({ component: FrontendComponentType.RESOURCES_FIELDS_RESOURCE_REFERENCE, resource: resourceType });
+    const { t, tComponent, formatDate, formatDateTime, isReady } = useI18n({ component: FrontendComponentType.RESOURCES_FIELDS_RESOURCE_REFERENCE, resource: resourceType });
     const toUserFacingErrorMessage = useUserFacingErrorMessage();
     // Resolve contextual parameters for scoped FK READ calls.
     // Display path: AutomaticDisplayer already built contextualParameters from contextResourceIdentifiers.
@@ -111,13 +118,31 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
     const displayMode = displayParams?.mode ?? DEFAULT_FOREIGN_KEY_DISPLAY_MODE;
     // ── C1 (P5-02): Parent reference display mode reconciliation ──────────
     const parentRefConfig = displayContext?.parentReferenceConfig;
-    const isParentReference = Boolean(parentRefConfig && resourceType && parentRefConfig.parentResourceType === resourceType);
+    /*
+     * The referenced ids, with a parent reference declared hidden (`ParentDisplay.NONE`) taken out — by the rule
+     * `DisplayField` reads too (`withoutHiddenParentReference`), against the type resolved above, so the field box and
+     * its value cannot disagree (#2195). A reference to ANOTHER record of the parent's type still renders; an array
+     * holding the parent and others renders the others.
+     */
+    const { hidesWholeReference, visibleIds: values } = React.useMemo(() => withoutHiddenParentReference({
+        parentReferenceConfig: parentRefConfig,
+        referencedResourceType: resourceType,
+        referencedIds: normalizeResourceReferenceSelectionValue(value),
+    }), [parentRefConfig, resourceType, value]);
+    /*
+     * Under NONE nothing that remains is the parent — the parent's id was taken out above — so the remaining ids
+     * render as the ordinary reference they are, not in a parent mode.
+     */
+    const isParentReference = Boolean(parentRefConfig
+        && resourceType
+        && parentRefConfig.parentResourceType === resourceType
+        && parentRefConfig.displayMode !== ParentDisplay.NONE);
     /**
      * Effective display mode after reconciliation with ParentDisplay enum:
      * - CONTEXT / BREADCRUMB → forces linkable, keeps current FK mode
      * - BADGE → renders as Badge component
      * - SUMMARY → renders as inline summary text
-     * - NONE → suppresses the parent reference rendering
+     * - NONE → never reaches here: the hidden parent's id was taken out of `values`, and what remains is not the parent
      * - Not a parent reference → uses the decorator-based displayMode as-is
      */
     const effectiveDisplayMode = useMemo(() => {
@@ -129,7 +154,6 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
                 return displayMode;
             case ParentDisplay.BADGE:
             case ParentDisplay.SUMMARY:
-            case ParentDisplay.NONE:
                 return parentRefConfig.displayMode;
             default: return displayMode;
         }
@@ -147,10 +171,6 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
         return displayParams?.linkable ?? true;
     }, [isParentReference, parentRefConfig, displayParams?.linkable]);
     const navigationZone = displayContext?.navigationZone ?? formSchemaContext?.navigationZone;
-    // Normalize value to array
-    const values = React.useMemo(() => {
-        return normalizeResourceReferenceSelectionValue(value);
-    }, [value]);
     // Check if pre-populated data is usable through the configured resource id field.
     const prePopulatedLabel = React.useMemo(() => {
         if (!prePopulatedData || typeof prePopulatedData !== 'object' || !resourceType)
@@ -183,41 +203,70 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
             formatDateTime,
         });
     }, [prePopulatedData, resourceType, value, registry, t, formatDate, formatDateTime]);
-    // ── B1 (P4-03): FK link URL infrastructure ───────────────────────────
-    // Memoize route path selection for the referenced resource type when linkable.
-    const fkLinkUrlInfo = useMemo(() => {
-        if (!resourceType || !isLinkable)
-            return null;
-        const refResourceConfig = registry.resourceConfigurations[resourceType];
-        if (!refResourceConfig)
-            return null;
-        // Gather parent context identifiers for route path matching
-        // (display context or form context — same source as scopedContextualParameters)
-        const parentContextIdentifiers = {};
+    // The HOST's context identifiers, flattened to ids: the page this reference sits on (display context or
+    // form context — the same source as scopedContextualParameters).
+    const hostContextIdentifiers = useMemo(() => {
+        const identifiers = {};
         const contextIds = displayContext?.contextResourceIdentifiers || formSchemaContext?.contextResourceIdentifiers;
         if (contextIds) {
             for (const [resType, idOrObj] of Object.entries(contextIds)) {
                 const idValue = typeof idOrObj === 'string' ? idOrObj : idOrObj?.resourceId;
                 if (idValue)
-                    parentContextIdentifiers[resType] = idValue;
+                    identifiers[resType] = idValue;
             }
         }
+        return identifiers;
+    }, [displayContext?.contextResourceIdentifiers, formSchemaContext?.contextResourceIdentifiers]);
+    // ── B1 (P4-03): FK route infrastructure ──────────────────────────────
+    // Memoize route path selection for the referenced resource type. Computed for a NON-linkable reference too: its READ
+    // is sent on the same route its link would take (#2741), and whether it is drawn as a link is `wrapWithLink`'s call.
+    const fkLinkUrlInfo = useMemo(() => {
+        if (!resourceType)
+            return null;
+        const refResourceConfig = registry.resourceConfigurations[resourceType];
+        if (!refResourceConfig)
+            return null;
+        const contextIds = displayContext?.contextResourceIdentifiers || formSchemaContext?.contextResourceIdentifiers;
         const currentContextResourceType = displayContext?.resourceType || formSchemaContext?.resourceType;
         const currentParentRequirements = currentContextResourceType && contextIds
             ? frontendResourceUtils.buildParentResourcesRequirements(currentContextResourceType, contextIds, registry)
             : [];
         // The resource's own field identifier (e.g., 'userId' for USERS) — for URL param substitution
         const ownFieldIdentifier = registry.allResourceFieldIdentifiers?.[resourceType];
-        return { refResourceConfig, parentContextIdentifiers, ownFieldIdentifier, currentParentRequirements };
+        return { refResourceConfig, ownFieldIdentifier, currentParentRequirements };
     }, [
         resourceType,
-        isLinkable,
         registry,
         displayContext?.contextResourceIdentifiers,
         displayContext?.resourceType,
         formSchemaContext?.contextResourceIdentifiers,
         formSchemaContext?.resourceType,
     ]);
+    /**
+     * The host's context scoped to ONE referenced record (#2144): the identifiers, parameters and parent
+     * requirements every per-target step below starts from — the link URL, the overlay, the label fetch and both
+     * clicks. A self-referencing parent the host carries (`parentUnitId`) describes the host's own record, so it
+     * is kept only for a reference to that record; a unit's link to its parent no longer names the parent as its
+     * own parent. See `frontendResourceUtils.scopeHostContextToReferencedRecord`.
+     */
+    // The record the host renders — a display's or a form's own type and id, never read off its type slot. The
+    // display context has a default value outside a provider, so it is the host only when it names a type.
+    const hostRecord = displayContext?.resourceType
+        ? { resourceType: displayContext.resourceType, id: displayContext.resourceId }
+        : formSchemaContext
+            ? { resourceType: formSchemaContext.resourceType, id: formSchemaContext.resourceId }
+            : undefined;
+    const hostRecordType = hostRecord?.resourceType;
+    const hostRecordId = hostRecord?.id;
+    const scopeToTarget = useCallback((id) => scopeReferencedRecord({
+        hostIdentifiers: hostContextIdentifiers,
+        hostContextualParameters: scopedContextualParameters,
+        hostParentRequirements: fkLinkUrlInfo?.currentParentRequirements,
+        hostRecord: { resourceType: hostRecordType, id: hostRecordId },
+        targetResourceType: resourceType ?? '',
+        targetId: id,
+        registry,
+    }), [hostContextIdentifiers, scopedContextualParameters, fkLinkUrlInfo?.currentParentRequirements, hostRecordType, hostRecordId, resourceType, registry]);
     /**
      * Resolve a concrete link URL for a given FK value.
      * Builds scoped URLs like /organizations/org-123/users/user-456 instead of /USERS/user-456.
@@ -225,11 +274,12 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
     const resolveFkNavigationTarget = useCallback((id) => {
         if (!fkLinkUrlInfo || !resourceType)
             return null;
-        const { refResourceConfig, parentContextIdentifiers, ownFieldIdentifier, currentParentRequirements } = fkLinkUrlInfo;
+        const { refResourceConfig, ownFieldIdentifier } = fkLinkUrlInfo;
+        const targetScope = scopeToTarget(id);
         // Add the FK's own resource type → ID for route matching
-        const fullContextIdentifiers = { ...parentContextIdentifiers, [resourceType]: id };
+        const fullContextIdentifiers = { ...targetScope.identifiers, [resourceType]: id };
         const contextualParameters = {
-            ...scopedContextualParameters,
+            ...targetScope.contextualParameters,
             ...(ownFieldIdentifier ? { [ownFieldIdentifier]: id } : {}),
         };
         const readOp = pickPreferredOperationForCoreSemanticAddressability({
@@ -248,14 +298,14 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
         if (routePaths.length === 0)
             return null;
         try {
-            const matchingPath = frontendResourceUtils.selectMatchingRoutePath(routePaths, fullContextIdentifiers, resourceType, ownFieldIdentifier, currentParentRequirements, registry.allResourceFieldIdentifiers);
+            const matchingPath = frontendResourceUtils.selectMatchingRoutePath(routePaths, fullContextIdentifiers, resourceType, ownFieldIdentifier, targetScope.parentRequirements, registry.allResourceFieldIdentifiers);
             if (!matchingPath?.url)
                 return null;
             const targetParentResourcesRequirements = frontendResourceUtils.buildParentResourcesRequirementsFromRouteParams(matchingPath.parameters ?? [], resourceType, registry);
             // Build field identifiers for URL parameter substitution
             const fieldIdentifiers = {};
-            // Parent field identifiers from scoped contextual parameters
-            for (const [key, val] of Object.entries(scopedContextualParameters)) {
+            // Parent field identifiers from the target's scoped contextual parameters
+            for (const [key, val] of Object.entries(targetScope.contextualParameters)) {
                 if (val !== undefined && val !== null)
                     fieldIdentifiers[key] = String(val);
             }
@@ -277,7 +327,7 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
             // selectMatchingRoutePath may throw — graceful fallback
         }
         return null;
-    }, [fkLinkUrlInfo, registry, resourceType, scopedContextualParameters]);
+    }, [fkLinkUrlInfo, registry, resourceType, scopeToTarget]);
     /**
      * The OVERLAY fallback — a reference whose target READ is `EMBEDDED` (decided 2026-09-01).
      *
@@ -290,8 +340,9 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
     const resolveFkOverlayTarget = useCallback((id) => {
         if (!fkLinkUrlInfo || !resourceType)
             return null;
-        const { refResourceConfig, parentContextIdentifiers, ownFieldIdentifier } = fkLinkUrlInfo;
-        const fullContextIdentifiers = { ...parentContextIdentifiers, [resourceType]: id };
+        const { refResourceConfig, ownFieldIdentifier } = fkLinkUrlInfo;
+        const targetScope = scopeToTarget(id);
+        const fullContextIdentifiers = { ...targetScope.identifiers, [resourceType]: id };
         const readOp = pickPreferredOperationForCoreSemanticAddressability({
             resourceConfig: refResourceConfig,
             operations: refResourceConfig.operations ?? [],
@@ -301,7 +352,7 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
             requireFrontendAddressable: false,
             contextResourceIdentifiers: fullContextIdentifiers,
             contextualParameters: {
-                ...scopedContextualParameters,
+                ...targetScope.contextualParameters,
                 ...(ownFieldIdentifier ? { [ownFieldIdentifier]: id } : {}),
             },
         });
@@ -310,7 +361,48 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
         if (readOp.operationFrontendConfig?.surface !== ResourceOperationFrontendSurface.EMBEDDED)
             return null;
         return { readOp };
-    }, [fkLinkUrlInfo, registry, resourceType, scopedContextualParameters]);
+    }, [fkLinkUrlInfo, registry, resourceType, scopeToTarget]);
+    /**
+     * The route a reference's READ is sent on: the route it links to, else — for a target with no page to link to (an
+     * EMBEDDED or API_ONLY read) — the READ's own most specific HTTP route its target-scoped parameters satisfy. Either
+     * way the read carries that route's parent chain, so a working scope the scoped registry injects into every call (a
+     * selected list) cannot reroute it under a parent the record need not have (#2741). `null` when no READ addresses the
+     * target from its scope: the read is then sent unpinned.
+     */
+    const resolveReadPin = useCallback((id) => {
+        const linkTarget = resolveFkNavigationTarget(id);
+        if (linkTarget)
+            return { readOp: linkTarget.readOp, parentResourcesRequirements: linkTarget.parentResourcesRequirements };
+        if (!fkLinkUrlInfo || !resourceType)
+            return null;
+        const { refResourceConfig, ownFieldIdentifier } = fkLinkUrlInfo;
+        const targetScope = scopeToTarget(id);
+        const contextualParameters = { ...targetScope.contextualParameters, ...(ownFieldIdentifier ? { [ownFieldIdentifier]: id } : {}) };
+        const readOp = pickPreferredOperationForCoreSemanticAddressability({
+            resourceConfig: refResourceConfig,
+            operations: refResourceConfig.operations ?? [],
+            coreOperation: CoreResourceOperation.READ,
+            registry,
+            hasResourceId: true,
+            requireFrontendAddressable: false,
+            contextResourceIdentifiers: { ...targetScope.identifiers, [resourceType]: id },
+            contextualParameters,
+        });
+        if (!readOp)
+            return null;
+        const initiator = FrontendResourceUtils.selectOperationUrlInitiatorInfo({
+            initiatorInfos: readOp.initiatorInfos ?? [],
+            contextualParameters,
+            targetResourceType: resourceType,
+            targetDefaultFieldIdentifier: ownFieldIdentifier ?? '',
+        });
+        if (!initiator)
+            return null;
+        return {
+            readOp,
+            parentResourcesRequirements: frontendResourceUtils.buildParentResourcesRequirementsFromRouteParams(initiator.parameters, resourceType, registry),
+        };
+    }, [resolveFkNavigationTarget, fkLinkUrlInfo, resourceType, scopeToTarget, registry]);
     // Resolve a single FK value via API
     const resolveForeignKey = useCallback(async (id) => {
         if (!resourceType || !id)
@@ -323,12 +415,23 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
         // Mark as loading — ref update is immediate for concurrent call detection
         trackResolvedFK(id, { id, label: null, error: null, isLoading: true });
         try {
+            /*
+             * Read on the route the reference links to (#2741): the most specific route its target-scoped context
+             * satisfies, which `scopeReferencedRecord` keeps to the tenancy unless the target is the host's own record or is
+             * readable only under a parent. Without the pin the request takes the most specific route its PARAMETERS
+             * satisfy, and the scoped registry injects the viewer's whole working scope into every call: with a list
+             * selected in a quick-switcher, a todo of another list was read under the selected one, refused, and shown as
+             * unavailable. A target with no page to link to is pinned to its READ's own route (`resolveReadPin`).
+             */
+            const routeTarget = resolveReadPin(id);
             const { record: fetchedRecord, label } = await fetchResourceReferenceRecordAndLabel({
                 resourceType,
                 id,
                 registry,
                 doOperation,
-                contextualParameters: scopedContextualParameters,
+                ...(routeTarget ? { readOperation: routeTarget.readOp, parentResourcesRequirements: routeTarget.parentResourcesRequirements } : {}),
+                // The target's own scope: a parent the host carries for ITS record is not the target's parent.
+                contextualParameters: scopeToTarget(id).contextualParameters,
                 t,
                 formatDate,
                 formatDateTime,
@@ -340,13 +443,13 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
             // backend's i18n REFERENCE (#1160).
             trackResolvedFK(id, { id, label: null, error: toUserFacingErrorMessage(err), isLoading: false });
         }
-    }, [resourceType, registry, doOperation, trackResolvedFK, t, formatDate, formatDateTime, scopedContextualParameters, fkLinkUrlInfo, toUserFacingErrorMessage]);
+    }, [resourceType, registry, doOperation, trackResolvedFK, t, formatDate, formatDateTime, scopeToTarget, toUserFacingErrorMessage, resolveReadPin]);
     // Resolve all FK values on mount/change — skip API when pre-populated data is available
     useEffect(() => {
         if (!resourceType || values.length === 0)
             return;
-        // Only resolve if mode requires it — skip for ID display and suppressed parent reference
-        if (effectiveDisplayMode === ForeignKeyDisplayMode.ID || effectiveDisplayMode === ParentDisplay.NONE)
+        // Only resolve if mode requires it — skip for ID display
+        if (effectiveDisplayMode === ForeignKeyDisplayMode.ID)
             return;
         // If pre-populated label is available for single value, seed it into resolvedFKs
         if (prePopulatedLabel && values.length === 1 && !resolvedFKsRef.current.has(values[0])) {
@@ -373,6 +476,9 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
     const wrapWithLink = useCallback((id, content) => {
         if (!isLinkable || !resourceType)
             return content;
+        // A SUMMARY card is block content: underlining it and painting it in the link colour underlined every line and
+        // badge of the card. It is a block link instead, drawn by the focus contract, as a selectable card is.
+        const summaryLink = effectiveDisplayMode === ForeignKeyDisplayMode.SUMMARY;
         const navigationTarget = resolveFkNavigationTarget(id);
         const shouldUseControllerNavigation = Boolean(navigationZone && navigationTarget?.readOp && navigationTarget?.url);
         const handleReferenceNavigation = (e) => {
@@ -386,7 +492,7 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
                 return;
             }
             const fullContextIdentifiers = {
-                ...fkLinkUrlInfo.parentContextIdentifiers,
+                ...scopeToTarget(id).identifiers,
                 [resourceType]: id,
             };
             const readContext = frontendResourceUtils.createFrontendResourceOperationContextFromOperation({
@@ -435,7 +541,7 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
                 }, children: content }));
         }
         if (navigationTarget?.url) {
-            return (_jsx(Link, { to: navigationTarget.url, className: "text-primary hover:underline", onClick: handleReferenceNavigation, children: content }));
+            return (_jsx(Link, { to: navigationTarget.url, className: summaryLink ? SUMMARY_LINK_CLASSES : 'text-primary hover:underline', onClick: handleReferenceNavigation, children: content }));
         }
         /*
          * No route — the EMBEDDED-read overlay fallback (see `resolveFkOverlayTarget`).
@@ -451,14 +557,15 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
                 if (e.button !== 0 || e.ctrlKey || e.metaKey || e.shiftKey || e.altKey)
                     return;
                 e.preventDefault();
+                const targetScope = scopeToTarget(id);
                 const readContext = frontendResourceUtils.createFrontendResourceOperationContextFromOperation({
                     resourceType,
                     operation: overlayTarget.readOp,
                     contextResourceIdentifiers: {
-                        ...fkLinkUrlInfo?.parentContextIdentifiers,
+                        ...targetScope.identifiers,
                         [resourceType]: id,
                     },
-                    parentResourcesRequirements: fkLinkUrlInfo?.currentParentRequirements ?? [],
+                    parentResourcesRequirements: targetScope.parentRequirements,
                 });
                 // No urlPath on purpose: an overlay is not a place — nothing to deep-link, nothing to pop.
                 emit(FrontendEvents.NAVIGATION_REQUEST, {
@@ -482,18 +589,17 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
                  * A BLOCK child is the shape that works: an outside marker aligns with the first line box
                  * of a list item's block content, exactly like `<li><p>…</p></li>`.
                  */
-                className: "block text-primary hover:underline bg-transparent border-none p-0 cursor-pointer text-left", onClick: openOverlay, children: content }));
+                className: summaryLink
+                    ? cn(SUMMARY_LINK_CLASSES, 'w-full bg-transparent border-none p-0 cursor-pointer text-left')
+                    : 'block text-primary hover:underline bg-transparent border-none p-0 cursor-pointer text-left', onClick: openOverlay, children: content }));
         }
         return content;
-    }, [emit, fkLinkUrlInfo, isLinkable, isParentReference, navigationZone, parentRefConfig, resolveFkNavigationTarget, resolveFkOverlayTarget, resourceType]);
+    }, [emit, effectiveDisplayMode, fkLinkUrlInfo, isLinkable, isParentReference, navigationZone, parentRefConfig, resolveFkNavigationTarget, resolveFkOverlayTarget, resourceType, scopeToTarget]);
     // Render a single value
     const renderValue = useCallback((id) => {
         if (effectiveDisplayMode === ForeignKeyDisplayMode.ID) {
             return _jsx("span", { className: "font-mono text-sm", children: id });
         }
-        if (effectiveDisplayMode === ParentDisplay.NONE) {
-            return null;
-        }
         const resolved = resolvedFKs.get(id);
         const isLoading = resolved?.isLoading ?? false;
         if (isLoading || !resolved) {
@@ -511,7 +617,11 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
             if (labelFallback) {
                 return (_jsx("span", { className: "text-muted-foreground text-sm", title: resolved.error, children: labelFallback }));
             }
-            return (_jsx("span", { className: "text-muted-foreground font-mono text-sm", title: resolved.error, children: id }));
+            // No readable copy: the field says the record cannot be shown, and keeps the id (and why) on hover for whoever
+            // needs to trace it. An id told a reader nothing (#2329). The words claim no reason on purpose: a 404 is not proof
+            // the record is gone, because a read across a tenant boundary answers 404 by design, so a refusal and a deletion
+            // are the same answer here, and "no longer exists" would be false for the first.
+            return (_jsx("span", { className: "text-muted-foreground text-sm italic", title: `${id} · ${resolved.error}`, children: tComponent(FrontendComponentType.RESOURCES_FIELDS_RESOURCE_REFERENCE, 'recordUnavailable') }));
         }
         // The id is the LAST resort, not the first. A record carrying a readable copy of the reference
         // (`labelFallbackField`) shows that instead — which is what keeps a member directory readable
@@ -526,7 +636,7 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
          * that is a labelling defect in the strategy and the log names it.
          */
         const hasLabelStrategy = !!resourceType
-            && !!registry.resourceConfigurations?.[resourceType]?.frontendConfiguration?.getFrontendResourceLabel;
+            && !!FrontendResourceUtils.frontendResourceLabelDefinitionOf(registry.resourceConfigurations?.[resourceType]);
         const currentLabel = resolved.data && resourceType && hasLabelStrategy
             ? FrontendResourceUtils.computeFrontendResourceLabel({ resourceType, registry, currentObject: resolved.data, t, formatDate, formatDateTime })
             : null;
@@ -552,7 +662,8 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
             // FK field SUMMARY mode — render ResourceSummaryDisplayer
             if (resolved.data && resourceType) {
                 const refConfig = registry.resourceConfigurations[resourceType];
-                const summarySchema = refConfig?.mainSchema;
+                // The referenced record's own schema (#2455): for an inheritance resource, the variant its discriminators name.
+                const summarySchema = FrontendResourceUtils.resolveRowSchema(refConfig, resolved.data);
                 if (summarySchema) {
                     const summaryContent = (_jsx(ResourceSummaryDisplayer, { resourceType: resourceType, schema: summarySchema, data: resolved.data, 
                         // The referenced record's NAME. The field's own label names the FIELD ("Target todo"),
@@ -560,7 +671,9 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
                         // screen says which record is referenced. Measured on Wonder Todos: a relationship row
                         // read "Blocks → Pending –", the blocked todo's badges with no title. The edit picker
                         // passes its option label for the same reason.
-                        primaryLabel: label }));
+                        primaryLabel: label, 
+                        // The host's scope narrowed to the referenced record (#2144): the record's own fields read there (#2198).
+                        contextResourceIdentifiers: scopeToTarget(id).identifiers }));
                     return isLinkable ? wrapWithLink(id, summaryContent) : summaryContent;
                 }
             }
@@ -572,14 +685,16 @@ export const ResourceFieldDisplayPreset_ResourceReference_Default = ({ fieldName
         }
         // Fallback — render as label
         return wrapWithLink(id, _jsx(ReferenceLabel, { label: label }));
-    }, [effectiveDisplayMode, resolvedFKs, resourceType, isParentReference, parentRefConfig, wrapWithLink, registry, isLinkable, t, formatDate, formatDateTime, labelFallback]);
+    }, [effectiveDisplayMode, resolvedFKs, resourceType, isParentReference, parentRefConfig, wrapWithLink, registry, isLinkable, t, tComponent, formatDate, formatDateTime, labelFallback]);
+    // NONE is "don't show any parent reference": when the parent was all there was, the reference is absent — never an
+    // empty-value mark in its place (#2195). A display field omits the whole field by the same rule.
+    if (hidesWholeReference) {
+        return null;
+    }
     // Handle empty values
     if (values.length === 0) {
         return _jsx("span", { className: "text-muted-foreground", children: "-" });
     }
-    if (effectiveDisplayMode === ParentDisplay.NONE) {
-        return _jsx("span", { className: "text-muted-foreground", children: "-" });
-    }
     // Unknown resource type warning
     if (!resourceType && effectiveDisplayMode !== ForeignKeyDisplayMode.ID) {
         // Fall back to showing IDs with a warning