[ADR-0006] Phase 1: Layout mode state and toggle controls by yurishkuro · Pull Request #3558 · jaegertracing/jaeger-ui

yurishkuro · 2026-03-05T04:38:46Z

Implements Phase 1 of ADR-0006: wire up Redux state, config options, and UI toggle controls for the upcoming side-panel and tree-only trace timeline modes. No visual layout changes in this PR — the work is purely state plumbing and a new settings component.

New config options

// jaeger-config.js
traceTimeline: {
  // Reveals the "Show Span in Sidebar" toggle. Off by default (experimental, opt-in).
  enableSidePanel: false,

  // When enableSidePanel is true and the user has no stored preference,
  // open new sessions in side-panel mode instead of inline.
  defaultDetailPanelMode: 'inline', // or 'sidepanel'
}

New Redux state (`TTraceTimeline`)

Three new fields in the trace timeline slice, all persisted to localStorage:

Field	Type	Default	Storage key
`detailPanelMode`	`'inline' \| 'sidepanel'`	`'inline'`	`detailPanelMode`
`timelineVisible`	`boolean`	`true`	`timelineVisible`
`sidePanelWidth`	`number` (ratio 0–1)	`0.45`	`sidePanelWidth`

New actions: SET_DETAIL_PANEL_MODE, SET_TIMELINE_VISIBLE, SET_SIDE_PANEL_WIDTH.

newInitialState() reads config and localStorage on startup. setTrace preserves all three layout preferences when navigating between traces. detailToggle is made mode-aware: in sidepanel mode it keeps at most one entry in detailStates (enforcing single-span-at-a-time selection semantics).

Width values loaded from localStorage are clamped to safe ranges on both read and write:

Preference	Min	Max
`spanNameColumnWidth`	0.15	0.85
`sidePanelWidth`	0.20	0.70

New `TraceViewSettings` component

Replaces the standalone KeyboardShortcutsHelp (⌘) button in the trace header with a gear-icon (⚙) dropdown that consolidates all view settings:

Show Timeline — toggle timeline bars on/off (always shown)
Show Span in Sidebar — toggle detail panel mode (shown only when enableSidePanel: true in config)
Keyboard Shortcuts — open the shortcuts reference modal (always shown)

Active settings are indicated with a checkmark. Preferences survive page reload via localStorage.

KeyboardShortcutsHelp is refactored from a self-contained button+modal into a controlled modal component (open / onClose props). The analytics track() call fires via useEffect when the modal becomes visible, keeping the caller free of tracking concerns.

The showShortcutsHelp prop is removed — the settings gear is always rendered.

codecov · 2026-03-05T04:41:07Z

Codecov Report

❌ Patch coverage is 98.75000% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 88.67%. Comparing base (125a76d) to head (098f3cf).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
...ts/TracePage/TracePageHeader/TraceViewSettings.tsx	93.75%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3558      +/-   ##
==========================================
+ Coverage   88.60%   88.67%   +0.06%     
==========================================
  Files         299      300       +1     
  Lines        9484     9551      +67     
  Branches     2502     2526      +24     
==========================================
+ Hits         8403     8469      +66     
- Misses       1077     1078       +1     
  Partials        4        4

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copilot

Pull request overview

Implements ADR-0006 (Phase 1) groundwork for Trace Timeline layout controls by adding configuration knobs, Redux state for layout mode/visibility, and a new header settings dropdown to toggle these preferences (persisted via localStorage).

Changes:

Add config.traceTimeline options (enableSidePanel, defaultDetailPanelMode) and defaults.
Extend traceTimeline Redux state with detailPanelMode, timelineBarsVisible, and sidePanelWidth, plus new actions/reducers and persistence.
Replace the header’s shortcuts button with a new Trace view settings dropdown that hosts layout toggles + keyboard shortcuts modal.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
packages/jaeger-ui/src/types/config.ts	Adds `traceTimeline` config schema and docs.
packages/jaeger-ui/src/types/TTraceTimeline.ts	Extends timeline Redux state type for new layout prefs.
packages/jaeger-ui/src/constants/default-config.ts	Provides default values for new `traceTimeline` config.
packages/jaeger-ui/src/components/TracePage/index.tsx	Wires new Redux state/actions into TracePage and passes feature flag to header.
packages/jaeger-ui/src/components/TracePage/index.test.js	Updates TracePage tests for new props/state wiring.
packages/jaeger-ui/src/components/TracePage/TraceTimelineViewer/duck.ts	Adds new layout state/actions and localStorage persistence; updates detail toggle behavior by mode.
packages/jaeger-ui/src/components/TracePage/TracePageHeader/TraceViewSettings.tsx	New settings dropdown component with layout toggles + keyboard shortcuts modal.
packages/jaeger-ui/src/components/TracePage/TracePageHeader/TraceViewSettings.css	Styles for the new settings trigger/icon.
packages/jaeger-ui/src/components/TracePage/TracePageHeader/TracePageHeader.tsx	Replaces `KeyboardShortcutsHelp` with `TraceViewSettings` and wires new props.
packages/jaeger-ui/src/components/TracePage/TracePageHeader/TracePageHeader.test.js	Updates header tests to mock/render the new settings component.
docs/adr/README.md	Adds ADR-0006 to the ADR index.
docs/adr/0006-side-panel-span-details.md	Adds new ADR describing side panel details + tree-only mode and phased plan.
docs/adr/0002-otlp-api-v3-migration.md	Updates ADR-0002 status wording.
docs/adr/0001-design-token-based-theming.md	Updates ADR-0001 status and removes placeholder next review.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

Signed-off-by: Yuri Shkuro <github@ysh.us>

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 10 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

Signed-off-by: Yuri Shkuro <github@ysh.us>

Copilot

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

Copilot · 2026-03-05T17:46:08Z

+let kbdTable: React.ReactNode | null = null;
+
+function getHelpModal() {
+  if (kbdTable) {
+    return kbdTable;
+  }


Caching kbdTable in a module-level variable makes the rendered keyboard shortcuts table effectively global and never refreshed (even if keyboardMappings changes due to build-time differences, future dynamic loading, or test isolation needs). Consider moving the cache to component scope (e.g. useMemo) or rebuilding on open so state remains local and predictable.

Signed-off-by: Yuri Shkuro <github@ysh.us>

Copilot

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

Signed-off-by: Yuri Shkuro <github@ysh.us>

Closes out the ADR-0006 implementation (side panel span details + tree-only mode). Previous phases: [Phase 1 #3558](#3558), [Phase 2 #3562](#3562), [Phase 3 #3569](#3569), [Phase 4 #3576](#3576). ## What changed ### Analytics tracking (`duck.track.ts`) Three new Redux actions are now tracked: | Action | Category | Tracked value | |---|---|---| | `SET_DETAIL_PANEL_MODE` | `jaeger/ux/trace/timeline/panel-mode` | mode string (`'inline'` / `'sidepanel'`) | | `SET_TIMELINE_BARS_VISIBLE` | `jaeger/ux/trace/timeline/timeline-visible` | `'true'` / `'false'` | | `SET_SIDE_PANEL_WIDTH` | `jaeger/ux/trace/timeline/column` | width × 1000 (integer), same pattern as `SET_SPAN_NAME_COLUMN_WIDTH` | ### Test coverage (`index.test.js`) Added a `describe('layout combinations')` block that renders `TraceTimelineViewerImpl` for all four `{detailPanelMode, timelineBarsVisible}` combinations and asserts: - Side panel container is present/absent as expected - `VerticalResizer` is present only when `detailPanelMode='sidepanel'` **and** `timelineBarsVisible=true` - `VirtualizedTraceView` is always rendered ### ADR `docs/adr/0006-side-panel-span-details.md` status updated to **Implemented**; Phase 5 marked complete. ## Testing ```bash npm run prettier npm run lint npm test npm run build ``` All 2560 tests pass. ### Manual testing of all four layout combinations Enable the side panel feature flag in `default-config.ts` (`enableSidePanel: true`) or via query param, then verify each combination: | `detailPanelMode` | `timelineBarsVisible` | Expected | |---|---|---| | `inline` | `true` | Default behavior — inline expand, timeline bars visible | | `inline` | `false` | Tree-only — inline expand, no timeline bars | | `sidepanel` | `true` | Side panel on right, `VerticalResizer` divider visible | | `sidepanel` | `false` | Side panel fills remaining width, no resizer | To test in embedded mode, append `?uiEmbed=v0` (optionally with `uiTimelineCollapseTitle=1`, `uiTimelineHideMinimap=1`, `uiTimelineHideSummary=1`) to a trace URL and verify the side panel and settings gear work normally. ## AI Usage in this PR (choose one) See [AI Usage Policy](https://github.com/jaegertracing/jaeger/blob/main/CONTRIBUTING_GUIDELINES.md#ai-usage-policy). - [ ] **None**: No AI tools were used in creating this PR - [ ] **Light**: AI provided minor assistance (formatting, simple suggestions) - [ ] **Moderate**: AI helped with code generation or debugging specific parts - [x] **Heavy**: AI generated most or all of the code changes --------- Signed-off-by: Yuri Shkuro <github@ysh.us>

) ## Description of the changes - Enables displaying span details in a side panel as an option - Default view is still inline span details, can be changed via `traceTimeline.defaultDetailPanelMode="sidepanel"` config option. <img width="1920" height="964" alt="image" src="https://github.com/user-attachments/assets/c71a9f98-e30d-4030-8947-6dc8e5b6bd0c" /> Previous phases: [Phase 1 #3558](#3558), [Phase 2 #3562](#3562), [Phase 3 #3569](#3569), [Phase 4 #3576](#3576), [Phase 5 #3577](#3577). --------- Signed-off-by: Yuri Shkuro <github@ysh.us>

…ing#3558) Implements Phase 1 of [ADR-0006](packages/jaeger-ui/docs/adr/0006-side-panel-span-details.md): wire up Redux state, config options, and UI toggle controls for the upcoming side-panel and tree-only trace timeline modes. No visual layout changes in this PR — the work is purely state plumbing and a new settings component. ## New config options ```js // jaeger-config.js traceTimeline: { // Reveals the "Show Span in Sidebar" toggle. Off by default (experimental, opt-in). enableSidePanel: false, // When enableSidePanel is true and the user has no stored preference, // open new sessions in side-panel mode instead of inline. defaultDetailPanelMode: 'inline', // or 'sidepanel' } ``` ## New Redux state (`TTraceTimeline`) Three new fields in the trace timeline slice, all persisted to `localStorage`: | Field | Type | Default | Storage key | |---|---|---|---| | `detailPanelMode` | `'inline' \| 'sidepanel'` | `'inline'` | `detailPanelMode` | | `timelineVisible` | `boolean` | `true` | `timelineVisible` | | `sidePanelWidth` | `number` (ratio 0–1) | `0.45` | `sidePanelWidth` | New actions: `SET_DETAIL_PANEL_MODE`, `SET_TIMELINE_VISIBLE`, `SET_SIDE_PANEL_WIDTH`. `newInitialState()` reads config and `localStorage` on startup. `setTrace` preserves all three layout preferences when navigating between traces. `detailToggle` is made mode-aware: in `sidepanel` mode it keeps at most one entry in `detailStates` (enforcing single-span-at-a-time selection semantics). Width values loaded from `localStorage` are clamped to safe ranges on both read and write: | Preference | Min | Max | |---|---|---| | `spanNameColumnWidth` | 0.15 | 0.85 | | `sidePanelWidth` | 0.20 | 0.70 | ## New `TraceViewSettings` component Replaces the standalone `KeyboardShortcutsHelp` (⌘) button in the trace header with a gear-icon (⚙) dropdown that consolidates all view settings: - **Show Timeline** — toggle timeline bars on/off (always shown) - **Show Span in Sidebar** — toggle detail panel mode (shown only when `enableSidePanel: true` in config) - **Keyboard Shortcuts** — open the shortcuts reference modal (always shown) Active settings are indicated with a checkmark. Preferences survive page reload via `localStorage`. `KeyboardShortcutsHelp` is refactored from a self-contained button+modal into a controlled modal component (`open` / `onClose` props). The analytics `track()` call fires via `useEffect` when the modal becomes visible, keeping the caller free of tracking concerns. The `showShortcutsHelp` prop is removed — the settings gear is always rendered. --------- Signed-off-by: Yuri Shkuro <github@ysh.us>

…acing#3577) Closes out the ADR-0006 implementation (side panel span details + tree-only mode). Previous phases: [Phase 1 jaegertracing#3558](jaegertracing#3558), [Phase 2 jaegertracing#3562](jaegertracing#3562), [Phase 3 jaegertracing#3569](jaegertracing#3569), [Phase 4 jaegertracing#3576](jaegertracing#3576). ## What changed ### Analytics tracking (`duck.track.ts`) Three new Redux actions are now tracked: | Action | Category | Tracked value | |---|---|---| | `SET_DETAIL_PANEL_MODE` | `jaeger/ux/trace/timeline/panel-mode` | mode string (`'inline'` / `'sidepanel'`) | | `SET_TIMELINE_BARS_VISIBLE` | `jaeger/ux/trace/timeline/timeline-visible` | `'true'` / `'false'` | | `SET_SIDE_PANEL_WIDTH` | `jaeger/ux/trace/timeline/column` | width × 1000 (integer), same pattern as `SET_SPAN_NAME_COLUMN_WIDTH` | ### Test coverage (`index.test.js`) Added a `describe('layout combinations')` block that renders `TraceTimelineViewerImpl` for all four `{detailPanelMode, timelineBarsVisible}` combinations and asserts: - Side panel container is present/absent as expected - `VerticalResizer` is present only when `detailPanelMode='sidepanel'` **and** `timelineBarsVisible=true` - `VirtualizedTraceView` is always rendered ### ADR `docs/adr/0006-side-panel-span-details.md` status updated to **Implemented**; Phase 5 marked complete. ## Testing ```bash npm run prettier npm run lint npm test npm run build ``` All 2560 tests pass. ### Manual testing of all four layout combinations Enable the side panel feature flag in `default-config.ts` (`enableSidePanel: true`) or via query param, then verify each combination: | `detailPanelMode` | `timelineBarsVisible` | Expected | |---|---|---| | `inline` | `true` | Default behavior — inline expand, timeline bars visible | | `inline` | `false` | Tree-only — inline expand, no timeline bars | | `sidepanel` | `true` | Side panel on right, `VerticalResizer` divider visible | | `sidepanel` | `false` | Side panel fills remaining width, no resizer | To test in embedded mode, append `?uiEmbed=v0` (optionally with `uiTimelineCollapseTitle=1`, `uiTimelineHideMinimap=1`, `uiTimelineHideSummary=1`) to a trace URL and verify the side panel and settings gear work normally. ## AI Usage in this PR (choose one) See [AI Usage Policy](https://github.com/jaegertracing/jaeger/blob/main/CONTRIBUTING_GUIDELINES.md#ai-usage-policy). - [ ] **None**: No AI tools were used in creating this PR - [ ] **Light**: AI provided minor assistance (formatting, simple suggestions) - [ ] **Moderate**: AI helped with code generation or debugging specific parts - [x] **Heavy**: AI generated most or all of the code changes --------- Signed-off-by: Yuri Shkuro <github@ysh.us>

…egertracing#3578) ## Description of the changes - Enables displaying span details in a side panel as an option - Default view is still inline span details, can be changed via `traceTimeline.defaultDetailPanelMode="sidepanel"` config option. <img width="1920" height="964" alt="image" src="https://github.com/user-attachments/assets/c71a9f98-e30d-4030-8947-6dc8e5b6bd0c" /> Previous phases: [Phase 1 jaegertracing#3558](jaegertracing#3558), [Phase 2 jaegertracing#3562](jaegertracing#3562), [Phase 3 jaegertracing#3569](jaegertracing#3569), [Phase 4 jaegertracing#3576](jaegertracing#3576), [Phase 5 jaegertracing#3577](jaegertracing#3577). --------- Signed-off-by: Yuri Shkuro <github@ysh.us>

Copilot AI review requested due to automatic review settings March 5, 2026 04:38

yurishkuro requested a review from a team as a code owner March 5, 2026 04:38

Copilot started reviewing on behalf of yurishkuro March 5, 2026 04:39 View session

yurishkuro added the changelog:experimental Experimental feature, may not be stable label Mar 5, 2026

yurishkuro force-pushed the 03-04-_adr-6_phase_1 branch from 021b4f6 to cbf64cb Compare March 5, 2026 04:42

Copilot AI reviewed Mar 5, 2026

View reviewed changes

yurishkuro added 2 commits March 4, 2026 23:45

ADR: Span Details in Side Panel

d93e592

Signed-off-by: Yuri Shkuro <github@ysh.us>

[adr-6] Phase 1

f17d275

Signed-off-by: Yuri Shkuro <github@ysh.us>

yurishkuro force-pushed the 03-04-_adr-6_phase_1 branch from cbf64cb to f17d275 Compare March 5, 2026 04:46

graphite-app Bot reviewed Mar 5, 2026

View reviewed changes

Comment thread packages/jaeger-ui/src/components/TracePage/TracePageHeader/TraceViewSettings.tsx Outdated

fix

8614b6c

Signed-off-by: Yuri Shkuro <github@ysh.us>

Copilot AI review requested due to automatic review settings March 5, 2026 05:01

Copilot started reviewing on behalf of yurishkuro March 5, 2026 05:02 View session

Copilot AI reviewed Mar 5, 2026

View reviewed changes

fix

1bffe68

Signed-off-by: Yuri Shkuro <github@ysh.us>

graphite-app Bot reviewed Mar 5, 2026

View reviewed changes

Comment thread packages/jaeger-ui/src/components/TracePage/TraceTimelineViewer/duck.ts Outdated

fix

669db71

Signed-off-by: Yuri Shkuro <github@ysh.us>

Copilot AI review requested due to automatic review settings March 5, 2026 16:31

yurishkuro added 3 commits March 5, 2026 11:53

fix

0f34d17

Signed-off-by: Yuri Shkuro <github@ysh.us>

fix

903c6cd

Signed-off-by: Yuri Shkuro <github@ysh.us>

fix

c084c1d

Signed-off-by: Yuri Shkuro <github@ysh.us>

yurishkuro commented Mar 5, 2026

View reviewed changes

Comment thread packages/jaeger-ui/src/components/TracePage/TracePageHeader/TracePageHeader.tsx Outdated

Copilot AI reviewed Mar 5, 2026

View reviewed changes

yurishkuro commented Mar 5, 2026

View reviewed changes

Comment thread packages/jaeger-ui/src/components/TracePage/TracePageHeader/TraceViewSettings.tsx Outdated

yurishkuro added 2 commits March 5, 2026 13:22

fix

48a34b1

Signed-off-by: Yuri Shkuro <github@ysh.us>

fix

f04273d

Signed-off-by: Yuri Shkuro <github@ysh.us>

Copilot AI review requested due to automatic review settings March 5, 2026 18:45

Copilot AI reviewed Mar 5, 2026

fix

098f3cf

Signed-off-by: Yuri Shkuro <github@ysh.us>

yurishkuro changed the title ~~[adr-006] Add Configuration, Layout Mode State, and Toggle Controls'~~ [adr-006/phase 1] Add Configuration, Layout Mode State, and Toggle Controls' Mar 5, 2026

yurishkuro changed the title ~~[adr-006/phase 1] Add Configuration, Layout Mode State, and Toggle Controls'~~ [ADR-0006] Phase 1: Layout mode state and toggle controls Mar 5, 2026

yurishkuro merged commit b5c0a73 into main Mar 5, 2026
15 checks passed

yurishkuro deleted the 03-04-_adr-6_phase_1 branch March 5, 2026 19:22

yurishkuro mentioned this pull request Mar 7, 2026

[ADR-0006] Phase 5: Combined Modes, Analytics, Final Polish #3577

Merged

4 tasks

yurishkuro mentioned this pull request Mar 7, 2026

Allow viewing span details in a side panel instead of inline view #3578

Merged

Uh oh!

Conversation

yurishkuro commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

New config options

New Redux state (TTraceTimeline)

New TraceViewSettings component

Uh oh!

codecov Bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

yurishkuro commented Mar 5, 2026 •

edited

Loading

New Redux state (`TTraceTimeline`)

New `TraceViewSettings` component

codecov Bot commented Mar 5, 2026 •

edited

Loading