> ## Documentation Index
> Fetch the complete documentation index at: https://decilia.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Bookmark Interaction Summary

> Executive summary of all bookmarks in the Demo Dataset report, including interaction map, key technical findings, and recommendations.

# Power BI Report Bookmarks Documentation

**Report:** DEMO DATASET
**Documentation Date:** 2025-12-24
**Author:** Alexandru BADIU
**Total Bookmarks:** {/* build_docs:start:total */}5{/* build_docs:end:total */}
**Documentation Standard:** pbir-documentation skill format

***

## Executive Summary

This report contains {/* build_docs:start:count */}**5 bookmarks**{/* build_docs:end:count */} designed to demonstrate Power BI bookmark capabilities, from simple visualization toggles to complex state-dependent behaviors. The bookmarks showcase best practices in interactive report design while also illustrating the critical importance of documentation for maintaining complex bookmark interactions.

### Bookmark Inventory

| Bookmark            | ID                   | Purpose                               | Complexity | Year Filter |
| ------------------- | -------------------- | ------------------------------------- | ---------- | ----------- |
| **Reset Filters**   | 77f6391b96f7c17022ed | Return to baseline state              | Moderate   | 2023        |
| **Clustered Chart** | 5977e1c788aabf285a32 | Value comparison view                 | Simple     | 2019        |
| **Ribon Chart**     | 3c04be006f1ebff4ddc5 | Toggle to Ribbon Chart view           | Simple     | 2019        |
| **FocusSpecific**   | a87d1123fc3c1c928935 | Advanced state-dependent highlighting | Complex    | 2019        |
| **Prepare Demo**    | 179ba89b97b6ee4b4619 | Governance/documentation-gate demo    | Simple     | 2023        |

***

## Quick Reference

### Bookmark Purposes

**Reset Filters** ([details](/documentation/bookmarks/ResetFilters)) — Moderate

* **Purpose:** Classic reset/home state following UX/UI best practices. Provides users with a reliable way to return to a known baseline state, resets ad-hoc filters, and sets the report to the current year (2023) as the default view.

**Clustered Chart** ([details](/documentation/bookmarks/ClusteredChart)) — Simple

* **Purpose:** Value comparison view optimized for comparing current year sales vs prior year sales side-by-side, and quickly identifying top-performing continents sorted by sales value descending.

**Ribon Chart** ([details](/documentation/bookmarks/RibonChart)) — Simple

* **Purpose:** Demonstration and training example to showcase Power BI bookmark functionality, specifically how to toggle between different visualization types while maintaining consistent filter states.

**FocusSpecific** ([details](/documentation/bookmarks/FocusSpecific)) — Complex

* **Purpose:** Complex demonstration of advanced bookmark behaviors illustrating how intricate bookmarks can become and the criticality of documenting business intent. Demonstrates cross-highlighting and state-dependent behavior where results differ based on previous bookmark state.

**Prepare Demo** ([details](/documentation/bookmarks/PrepareDemo)) — Simple

* **Purpose:** A demo/training artifact, not an analytical bookmark. Created during a live demo to show that the repository's commit hook (require-bookmark-docs) blocks committing a bookmark without a Documentation annotation and business justification.
* **When to use:** Not intended for report end users. Used by the presenter during a live walkthrough of the PBIP bookmark-documentation and commit-gate workflow.

***

## Key Technical Findings

### 1. Measure Table Inconsistency

⚠️ **Important Discovery:**

* **Demo bookmarks** (Ribon Chart, Clustered Chart, FocusSpecific): Reference `Sales[Sales]` and `Sales[Sales PY]`
* **Reset Filters bookmark**: References `_Measures[Sales]` and `_Measures[Sales PY]`

**Implication:** This suggests a refactoring where measures were moved to a dedicated `_Measures` table. The Reset Filters bookmark likely represents the current/production standard.

**Recommendation:** Standardize all bookmarks to use the `_Measures` table for consistency.

### 2. Year Filter Logic

* **2019:** Used by demo bookmarks (Ribon Chart, Clustered Chart, FocusSpecific) - historical data for demonstration
* **2023:** Used by Reset Filters - represents the current/baseline year for actual analysis

**Implication:** The report is designed for 2023 as the primary analysis year, with 2019 used for training/demo purposes.

### 3. State-Dependent Behavior (FocusSpecific)

The **FocusSpecific** bookmark exhibits complex state-dependent behavior:

```
Reset Filters → Focus Specific = Result A
Ribon Chart → Focus Specific = Result B (different!)
Clustered Chart → Focus Specific = Result C
```

**Why:** FocusSpecific does not explicitly control the Ribbon Chart's visibility, so the visible chart depends on the previous bookmark's state.

**Critical Learning:** This demonstrates why business intent documentation is essential - the technical JSON alone cannot reveal this complexity.

### 4. Filter Type Variations

| Bookmark                                    | Gender Filter Type             |
| ------------------------------------------- | ------------------------------ |
| Ribon Chart, Clustered Chart, Reset Filters | Contains "Ma"                  |
| FocusSpecific                               | **In \['Male']** (exact match) |

**Implication:** FocusSpecific uses a more precise filter, which may behave differently if data contains variations like "Male", "male", or other similar values.

***

## Bookmark Interaction Map

```
┌─────────────────────────────────────────────────────────────┐
│                    BOOKMARK INTERACTIONS                     │
└─────────────────────────────────────────────────────────────┘

Reset Filters (Baseline)
    │
    ├──→ Ribon Chart ←──→ Clustered Chart (Toggle Pair)
    │         │                    │
    │         └────────┬───────────┘
    │                  │
    └──────────────→ FocusSpecific (State-dependent)
                         ↓
                   (Different result based on previous!)

Prepare Demo (standalone) — documentation-gate demo; hides detail visuals
```

### Navigation Recommendations

1. **For Training:** Reset → Ribon → Clustered → Ribon (toggle demo)
2. **For Complexity Demo:** Reset → Focus → Reset → Ribon → Focus (shows different results)
3. **For Analysis:** Reset → Clustered (establishes sorted value view)

***

## Visual Inventory

The following visuals are controlled by bookmarks:

| Visual ID            | Type              | Used in Bookmarks                                        | Primary Function            |
| -------------------- | ----------------- | -------------------------------------------------------- | --------------------------- |
| ed774ceec96dd040ac19 | ribbonChart       | Ribon Chart, Clustered Chart (hidden), Focus (state-dep) | Show continent ranking flow |
| 34f97140074284eaa8de | clusteredBarChart | Clustered Chart, Ribon Chart (hidden), Focus, Reset      | Compare CY vs PY sales      |
| bf11a6fb91dc9f853419 | slicer (Gender)   | All bookmarks                                            | Filter by gender            |
| 621534302dec46c4557a | slicer (Age)      | Focus, Reset                                             | Filter by age               |
| a4a1181b341466474c49 | scatterChart      | Focus, Reset                                             | Margin vs Sales analysis    |
| a5dbb271c8b93debaa5e | bookmarkNavigator | Focus, Reset                                             | Bookmark navigation         |
| 5e6acabae3ac49fd5c3b | (Unknown)         | Reset                                                    | **Needs documentation**     |

***

## Recommendations

### 1. Standardization

* [ ] Update demo bookmarks (Ribon, Clustered, Focus) to use `_Measures` table instead of `Sales` table
* [ ] Standardize gender filter type (either all "Contains" or all exact match)
* [ ] Consider updating year in Reset Filters if 2023 is no longer current

### 2. Documentation

* [ ] Identify and document visual 5e6acabae3ac49fd5c3b
* [ ] Add tooltip descriptions to bookmarks in Power BI Desktop for end-user guidance
* [ ] Create user guide explaining FocusSpecific's state-dependent behavior

### 3. UX Improvements

* [ ] Consider making FocusSpecific explicitly control Ribbon Chart visibility to eliminate state dependency
* [ ] Add "Reset Filters" bookmark to prominent position in bookmark navigator
* [ ] Decide if Gender filter should be cleared in Reset Filters (true reset vs contextual reset)

### 4. Testing

* [ ] Create test matrix for FocusSpecific from all navigation paths
* [ ] Verify all measure references work after table standardization
* [ ] Test bookmark behavior with current data (post-2023)

***

## Documentation Files

Detailed documentation for each bookmark is available in the `documentation/bookmarks/` folder:

* [RibonChart.md](documentation/bookmarks/RibonChart.md) - Full technical and business documentation
* [ClusteredChart.md](documentation/bookmarks/ClusteredChart.md) - Full technical and business documentation
* [FocusSpecific.md](documentation/bookmarks/FocusSpecific.md) - Complex behavior analysis
* [ResetFilters.md](documentation/bookmarks/ResetFilters.md) - UX best practice example
* [PrepareDemo.md](documentation/bookmarks/PrepareDemo.md) - Documentation/governance-gate demo

Each file follows the **pbir-documentation skill** standard format including:

* Business purpose and user scenarios
* Technical specifications and filter states
* Behavior descriptions
* Dependencies and relationships
* Maintenance notes and testing procedures
* Change history

***

## Validation Status

### Critical (Level 1) ✅

* [x] All bookmarks have basic documentation
* [x] All visual references verified to exist
* [x] All measure references documented
* [x] No placeholder text in documentation
* [x] All markdown files valid

### Recommended (Level 2) ✅

* [x] Business purpose documented for all bookmarks
* [x] User scenarios described
* [x] Measure dependencies documented
* [x] Change history initiated

### Optional (Level 3) ✅

* [x] Performance considerations noted
* [x] Known limitations documented
* [x] Testing procedures specified
* [x] Maintenance recommendations provided

***

## Important Bookmark Behaviors (Reference)

### "All Visuals" vs "Selected Visuals"

**Critical distinction:**

* **True "All Visuals":** No `targetVisualNames` property → affects all current AND future visuals
* **"Selected Visuals":** `targetVisualNames` present → only affects listed visuals

⚠️ All bookmarks in this report use **"Selected Visuals"** mode.

### Filter State Behavior

Filter states (Data setting) are ALWAYS applied to all visuals on the page, regardless of `targetVisualNames`. The `targetVisualNames` property only limits Display/Selection changes.

### Cross-Highlighting vs Filtering

* **Filtering** (Ribon, Clustered, Reset): Removes data from the visual entirely
* **Highlighting** (FocusSpecific): Keeps all data visible but emphasizes specific elements

***

## Schema Information

**Schema Version:** 1.4.0
**Schema URL:** `https://developer.microsoft.com/json-schemas/fabric/item/report/definition/bookmark/1.4.0/schema.json`

***

## Change History

* **2025-12-24:** Initial comprehensive documentation created using pbir-documentation skill format
  * Documented all 4 bookmarks with business context
  * Identified measure table inconsistency
  * Discovered FocusSpecific state-dependent behavior
  * Cataloged all visual references
  * Created detailed individual bookmark documentation files
  * Established testing and maintenance recommendations

***

**For questions or updates to this documentation, contact:** Alexandru BADIU