docs(merge-queue): document date range selection on health charts

[samgutentag]

Summary

• Adds a "Select a date range on a chart" section to the merge queue metrics page
• Documents that users can click and drag on merge health charts to zoom into a specific time window

Source

• trunk2 PR: https://github.com/trunk-io/trunk2/pull/3489

Test plan

• Preview in GitBook

[trunk-staging-io]

😎 Merged successfully - details.

[claude]

Claude finished @samgutentag's task in 1m 3s —— View job

---

PR Review

• Read CLAUDE.md for repo guidelines
• Read changed file and diff
• Review for typos, grammar, formatting, and doc best practices
• Post final review

---

The new "Select a date range on a chart" section is clear and well-written. A couple of minor observations:

1. "span of bars" assumes bar charts only (line 78)

Dragging across a span of bars highlights that window

The heading says this works on "any merge health chart," but the page's own figure alt text shows a line chart ("Time in Queue p50 line chart"). "Bars" doesn't apply to line charts. Consider a more chart-agnostic phrasing:

Dragging across a region of the chart highlights that window…

Fix this →

2. Potential reader confusion with the existing "Drill down into metrics" section

The existing ### Drill down into metrics section (further down the page) also describes a "click and drag across the chart" gesture — but that one surfaces a View PRs button, while this new section describes the chart zooming to the selected range. The two behaviors use identical gestures but produce different outcomes. A brief clarifying note (e.g., "This zooms the chart view; to drill into specific PRs, see Drill down into metrics") would help users who encounter both sections.

---

Both are minor and non-blocking. The content is accurate, the section fits naturally between "Time buckets" and the UTC hint, and no grammar or formatting issues were found.

[github-actions]

Auto-approved: Claude code review passed.

[samgutentag]

Triage status (2026-05-05): up to date with main. Needs review before merge.

[claude]

Claude finished @samgutentag's task in 1m 21s —— View job

---

PR Review

• Read CLAUDE.md for repo guidelines
• Read changed file and diff
• Review for typos, grammar, formatting, and doc best practices
• Post final review

---

The new "Select a date range on a chart" section is well-placed (between Time buckets and the UTC hint) and the prose is clear. Posted four inline comments — one blocking-ish, three minor:

Posted inline:

1. Line 78 — "span of bars" assumes bar charts only. The page's hero figure and the Time in queue chart further down are line charts, so "bars" doesn't fit. Suggested chart-agnostic phrasing as a code suggestion.
2. Line 78 — Conflict with the existing "Drill down into metrics" section. Line 132 already documents the same gesture (click and drag across the chart) but attributes a different outcome (a View PRs button surfaces). The new section says the gesture zooms. Worth clarifying — either cross-reference the two sections or confirm with engineering whether the gestures are actually distinct. This is the one I'd want resolved before merging.
3. Line 78 — "any merge health chart" may overstate scope. The existing Drill down hint at lines 150–152 limits that interaction to Conclusion count and Time in queue. If zoom shares the same constraint, the same caveat applies here.
4. Line 80 — Verify the clear-selection gesture. "Click anywhere outside the selected area" is specific — common alternatives are a Reset zoom button or double-click. Worth confirming against the implementation.

No typos, grammar, or formatting issues. The section flows naturally and the placement is sensible.
| Branch

[claude]

"span of bars" assumes bar charts only. The opening sentence says this works on "any merge health chart," but the page's hero figure (line 7) describes a line chart (Time in Queue p50 line chart) — and the Time in queue chart at line 96 is a line chart. "Bars" doesn't apply there.

Consider chart-agnostic phrasing:

Suggested change

	You can click and drag directly on any merge health chart to select a custom date range. Dragging across a span of bars highlights that window and zooms the view to show only data within the selected range. This lets you isolate a specific incident, deployment window, or performance regression for closer inspection.
	You can click and drag directly on any merge health chart to select a custom date range. Dragging across a region of the chart highlights that window and zooms the view to show only data within the selected range. This lets you isolate a specific incident, deployment window, or performance regression for closer inspection.

[claude]

Possible conflict with the existing "Drill down into metrics" section. Further down the page (line 132), the docs already describe the same gesture — click and drag across the chart — but attribute a different outcome to it: a View PRs button surfaces and you can drill into the PR list.

This new section says the same gesture zooms the view. So the page now documents one gesture with two distinct effects, and a reader who reaches both sections will be confused about which actually happens (or whether both do).

A few options:

1. Add a one-line cross-reference here, e.g. "This zooms the chart view; to open the PR list for a selected range, see Drill down into metrics."
2. Confirm with engineering whether the gestures are truly distinct (e.g. drag vs. drag + click on the highlighted region), and disambiguate them in the prose.
3. If the View PRs button now appears alongside the zoom, update both sections to reflect the unified behavior.

Worth resolving before merging — these two sections are only ~50 lines apart on the same page.

[claude]

"any merge health chart" may overstate scope. The existing Drill down hint at line 150–152 explicitly notes:

Drill down is currently available on the Conclusion count and Time in queue charts. Additional Health charts will support the same interaction as they land in the UI.

If date-range zoom has the same per-chart limitation (likely, since it appears to share the underlying selection mechanism), saying "any merge health chart" will set the wrong expectation. Worth verifying with the source PR (trunk2#3489) and either narrowing the wording or adding a parallel hint.

[claude]

Verify the clear-selection gesture. "Click anywhere outside the selected area on the chart" is a specific claim — worth double-checking against the implementation. Common patterns for this kind of zoom UI are a dedicated Reset zoom button or a double-click, not an outside-click. If the actual mechanism differs, this instruction will frustrate users who try it and find nothing happens.

[samgutentag]

Verification status (2026-05-07, re-verified): live

Verified: customers can use this. Ready to publish.

• Eng PR: trunk2#3489 ("Allow date range selection on merge health charts", merged 2026-04-09, merge commit still on main)
• Linear ticket: none referenced
• Flag: none (no LaunchDarkly gate found in PR body or diff)
• Signals: pure frontend chart UX change, ungated. The merge commit is intact on trunk2 main.

Re-verification surfaced four accuracy issues in the original "Select a date range on a chart" section. All four addressed in commit 895892e:

1. Chart type. Original wording said "span of bars," but the eng PR adds the props to both ConclusionCountsChart (bar) and TimeInQueueChart (line) and they share state in MergeHealthMetrics. Now described as "the rest of the chart dims" / "a range of data points."
2. Section overlap. Per the eng PR body: "This is the first part of [the drill-down feature]." The selection mechanism (this PR) and the View PRs button (later PR) are two outcomes of one click-and-drag gesture. Folded the new affordances into the existing Drill down into metrics > Select Data Points subsection rather than keeping a separate "Select a date range on a chart" section.
3. Scope claim. Original said "any merge health chart," but the eng PR only wires the props into Conclusion count and Time in queue. Same constraint as the existing Drill down hint at line 150-152. Updated the trailing hint to mention "Drill down and range selection" together.
4. Clear mechanism. Original said "click anywhere outside the selected area," but useDateRangeSelection (ts/apps/frontend/src/components/charts/date-range-selection.ts) does not implement that gesture. The actual reset paths are: drag a new range, or change lookbackPeriod / timeGranularity / UTC setting (auto-reset via useEffect in merge-health-metrics.tsx). Clear sentence rewritten to match.

Cross-chart sync (selecting on one chart highlights the same range on the other) is also documented now since it's visible in the diff (MergeHealthMetrics shares one chartSelectionRange between both child charts).

Standalone UTC hint moved up next to "Time buckets" since it is general date-filtering advice rather than range-selection-specific.

trunk check clean on the edited file.

Suggested next action: flip out of draft and merge.

[claude]

PR Review

• Read CLAUDE.md for repo guidelines
• Read changed file and diff
• Review for typos, grammar, formatting, and doc best practices
• Post final review

View job run | Branch

[claude]

Claude finished @samgutentag's task in 2m 12s —— View job

---

PR Review

• Read CLAUDE.md for repo guidelines
• Read changed file and diff
• Review for typos, grammar, formatting, and doc best practices
• Post final review

---

The actual PR diff vs origin/main is +4/-2 — three targeted edits inside the existing Drill down into metrics > Select Data Points subsection. All four blockers from my prior review have been resolved by the restructure in 895892e (folding the standalone section in). The current diff cleanly addresses the engineering behavior:

Verified against the diff:

• metrics.md:126 — expanded bullet describes highlight + dim + cross-chart sync. Chart-agnostic ("range of data points," not "span of bars"). ✅
• metrics.md:132 — clear-selection mechanism now matches the actual useDateRangeSelection hook (drag a new range, or change time range / time bucket / Time in UTC). ✅
• metrics.md:147 — trailing hint widened to "Drill down and range selection… same interactions" so the per-chart scope caveat applies to both. ✅

Style and grammar: clean. No typos. Bold formatting on Time in UTC matches the existing convention at line 77. Pluralization of "interaction" → "interactions" in the hint is correct given two distinct interactions are now covered.

One minor, non-blocking observation (not introduced by this PR):

Lines 130 and 138 use "cancelled" (double-l) in the figure alt text and the Conclusion bullet, while the existing Conclusion count prose at line 82 and the table at line 88 use "canceled" (single-l). Both lines pre-date this PR (they came in via e3cee08), so it's not a blocker here, but worth a follow-up for cross-page consistency.

No blocking issues. Ready to merge.
| Branch

[github-actions]

Auto-approved: Claude code review passed.