refactor: enhance breadcrumb management in DotAnalyticsDashboardComonent and BreadcrumbFeature

[adrianjm-dotCMS]

This pull request introduces a robust mechanism for handling breadcrumb tab switching in the analytics dashboard, ensuring that tab transitions never accumulate redundant breadcrumbs and that tab crumbs persist correctly across reloads. The changes include a new rule-based system for deciding when to replace the last breadcrumb, updates to analytics report components to use feature-namespaced IDs, and enhancements to documentation and tests.

Breadcrumb tab switching and persistence improvements:

• Added a rule-based function shouldReplaceLastCrumb in breadcrumb.utils.ts that determines whether the last breadcrumb should be replaced based on stable patterns (e.g., both items are analytics tabs or content-edit routes). This prevents accumulation of tab crumbs when switching between analytics tabs. [1] [2]
• Updated analytics report components to use feature-namespaced IDs (analytics-engagement, analytics-conversions, analytics-pageview) when adding breadcrumbs, aligning them with the new rule system. [1] [2] [3]
• Enhanced the breadcrumb store logic to preserve analytics tab crumbs appended before menu items load, so tab selections survive page reloads and menu resets. [1] [2]

Testing and documentation updates:

• Added comprehensive tests for the shouldReplaceLastCrumb function, covering both content-edit and analytics tab rules, as well as edge cases.
• Updated documentation in BREADCRUMBS.md to explain the new rule-based replace behavior for tabs, how to add new rules, and best practices for sub-level and tab breadcrumbs. [1] [2] [3]

UI improvements:

• Modified the analytics dashboard template to render only the active tab panel, simplifying the report display logic. [1] [2]

These changes collectively ensure that analytics tab breadcrumbs behave intuitively, are not duplicated, and persist reliably across navigation and reloads.

Screen.Recording.2026-03-09.at.2.53.44.PM.mov

This PR fixes: #34694

This PR fixes: #34694

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

[claude]

Claude encountered an error —— View job

Failed to fetch PR data

---

I'll analyze this and get back to you.

[claude]

Claude finished @adrianjm-dotCMS's task —— View job

---

PR Review: Analytics Breadcrumb Management

Reviewing this PR for potential issues, edge cases, and design problems.

Issues Found:

1. Type Safety Vulnerability in shouldReplaceLastCrumb (breadcrumb.utils.ts:175-182)
The analyticsTab rule has proper type guards for strings, but the implementation could still fail with edge cases:

• If item.id or last.id is 0 (number), the type check typeof itemId !== 'string' will correctly return false, but the comment suggests this was a specific concern about RegExp coercion
• The code is actually fine, but the comment on line 173-174 about coercing 0 → "0" is misleading since the type guards prevent this

2. Potential State Corruption in Breadcrumb Feature (breadcrumb.feature.ts:164-168)
The addNewBreadcrumb method has a race condition risk:

if (lastBreadcrumb && shouldReplaceLastCrumb(item, lastBreadcrumb)) {
    setLastBreadcrumb(item);
} else {
    appendCrumb(item);
}

If lastBreadcrumb changes between the check and the action (due to async operations), the wrong action could be taken. Consider capturing lastBreadcrumb once.

3. Truncation Logic Bug (breadcrumb.feature.ts:250-252)

if (result.index && result.index > -1) {
    truncateBreadcrumbs(result.index);
}

This condition result.index && result.index > -1 is problematic because 0 is falsy in JavaScript. If result.index is 0 (truncate to just the first breadcrumb), the truncation won't happen. Should be:

if (result.index !== undefined && result.index > -1) {

4. Missing Edge Case in URL Normalization (breadcrumb.feature.ts:139-146)
The normalizeUrl function handles empty hash and no hash, but doesn't handle malformed URLs or null values that could cause runtime errors.

5. Session Storage Error Handling (breadcrumb.feature.ts:172-179)
The loadBreadcrumbs function silently fails on JSON parse errors and resets to empty array. This might hide corruption issues - consider logging the error for debugging.

6. Test Coverage Gap
The analytics dashboard component tests don't verify the breadcrumb replacement logic that was the core of this fix. The existing tests only check that breadcrumbs are added, not that they replace correctly when switching tabs.

Architecture Concerns:

7. Tight Coupling Between Analytics and Breadcrumb Logic
The breadcrumb utils now contain analytics-specific rules hardcoded with magic strings like 'analytics-'. This breaks separation of concerns - breadcrumb logic shouldn't know about specific feature implementations.

8. Rule Registration Pattern Missing
There's no way for other features to register their own replacement rules dynamically. The REPLACE_LAST_CRUMB_RULES object is closed for extension.

Minor Issues:

9. Inconsistent Error Handling Patterns
Some functions return undefined on error, others throw, others silently fail. Pick one pattern and be consistent.

10. Magic String Dependencies
The analytics tab IDs (analytics-engagement, analytics-conversions) are hardcoded in multiple places without shared constants, creating maintenance burden.

---