Unify cell detail, rows and documentation in a foldable desktop right inspector

[BorisTyshkevich]

Depends on: #425

Architecture dependency: #577

Migration umbrella if approved: #578 (right inspector is Phase 3)

Coordinate with: #487 so both docked sides share one centre-width policy, shell ownership model, focus behavior, and resize lifecycle.

Goal

Replace the current collection of unrelated desktop right-side overlays and panes with one foldable, shell-owned right inspector for contextual content:

• cell detail;
• rows/detail viewer content;
• function, aggregate-function, data-type, and other Reference documentation;
• future contextual diagnostic/detail tools that belong in the same right-side surface.

On desktop, the inspector is docked beside the Query/Dashboard surface, consumes normal layout width, and pushes the centre surface left. It never covers the editor or Dashboard with a backdrop.

Mobile keeps its existing mobile/full-screen/modal presentation where needed and is not redesigned by this issue.

Status and architecture dependency

Do not begin the full inspector implementation before #577 records the application UI-shell decision.

• If Evaluate Preact migration as an application-wide simplification #577 selects Preact, implement this issue as Phase 3 of Migrate the application UI to Preact in measured simplification phases #578 after the Preact shell and Add a drag-foldable desktop left navigation with rail and focused drawers #487 navigation phase establish the shared ownership and geometry model.
• If Evaluate Preact migration as an application-wide simplification #577 rejects Preact, implement the same product contract with the smaller targeted vanilla architecture recorded by the ADR.

This issue defines the product, domain, validity, accessibility, and integration contracts. It does not prescribe a vanilla renderer, Preact component tree, generic focus coordinator, hook, or global focus manager.

Final desktop shell geometry

The application header remains full width above the shell.

[right inspector folded]
[left navigation] [main Query/Dashboard surface] [chevron]

[right inspector open]
[left navigation] [main Query/Dashboard surface] [chevron] [right inspector]

[left focused drawer and inspector open]
[rail] [left focused drawer] [main surface] [chevron] [right inspector]

On desktop:

• exactly one right-inspector host exists per application shell/document;
• no inspector tool creates a backdrop;
• no inspector tool covers the centre surface;
• no inspector tool traps focus;
• only one inspector tool is visible at a time;
• valid inactive tool state may remain cached for the session.

Fold control

Use one narrow vertical chevron attached to the inspector’s left boundary.

folded: chevron points left, meaning open
open:   chevron points right, meaning fold closed

Requirements:

• the chevron remains visible at the right edge when the inspector is folded;
• when open, it moves with the inspector’s left edge;
• toggling it does not discard valid active-tool state;
• reopening restores the most recently active still-valid tool;
• contextual triggers still open and activate the appropriate tool automatically;
• do not add redundant top-bar open controls solely for panel visibility;
• remove redundant per-tool desktop X controls where the panel-level fold control replaces them;
• the accessible label reflects the current action, such as Open details panel or Close details panel.

Tool registry and ownership

Use a narrow typed registry, initially:

type RightInspectorToolId =
  | 'cell'
  | 'rows'
  | 'reference';

Conceptual shell-facing operations:

interface OpenRightInspectorRequest<T = unknown> {
  tool: RightInspectorToolId;
  payload: T;
  initiator?: Element | null;
}

openRightInspector(request: OpenRightInspectorRequest): void;
activateRightInspectorTool(tool: RightInspectorToolId): void;
foldRightInspector(): void;
unfoldRightInspector(): void;
closeRightInspectorTool(tool: RightInspectorToolId): void;

The exact API may change under #577/#578, but the ownership boundary remains:

Shell owns

• the single inspector host;
• fold/open geometry;
• active-tool selection;
• tool selector chrome;
• width preference and resize separator;
• interaction with left navigation and the centre minimum;
• high-level teardown on workspace replacement and sign-out.

Tool controllers own

• typed payloads;
• content/domain rendering state;
• result or catalog validity;
• async generation tokens;
• tool-specific back stacks, embedded viewers, and actions;
• initiator metadata used for safe focus restoration.

Feature call sites request a tool through the shell-facing API. They must not append independent desktop panels/backdrops or write shell widths.

The selected rendering architecture must give each inspector subtree one owner. Do not leave parallel vanilla and Preact inspector implementations active behind different triggers.

Tool navigation

When more than one valid tool has session content, show compact accessible tabs or an equivalent selector:

Cell | Rows | Reference

Rules:

• only tools with live/available content appear;
• opening a tool unfolds and activates it;
• a new Cell request replaces the Cell payload rather than adding another Cell tab;
• a new Reference target replaces the current target while preserving Reference’s own valid back stack semantics;
• switching tools does not destroy valid inactive tool state;
• closing one tool activates the most recently used valid remaining tool;
• if no valid tool remains, fold the inspector;
• the fold chevron remains panel-level chrome, not a tool tab.

Cell tool

• clicking a supported result cell opens/unfolds Cell;
• preserve formatting, copy, and structured-value rendering;
• bind validity to a stable result-generation token plus tab/query identity;
• result replacement, rerun, tab closure, workspace switch, or sign-out invalidates stale Cell state;
• stale asynchronous formatting/render work cannot repaint a newer payload;
• no desktop backdrop or focus trap;
• opening Cell does not unnecessarily steal editor selection;
• folding/reopening preserves Cell only while its origin remains valid.

A stale cell must never appear as though it belongs to the current result.

Rows/detail tool

• migrate passive rows/detail consumers that currently share cell-drawer chrome;
• preserve table/detail rendering, paging, copy, and result semantics;
• bind validity to the originating result generation;
• result replacement, tab closure, workspace switch, or sign-out invalidates it;
• one Rows tool instance exists per shell and a new request replaces its payload;
• keep truly modal decisions modal; move only passive inspection content into the inspector.

Reference tool

Preserve the existing mature behavior:

• loading, found, missing, unavailable, and Retry states;
• related/alias navigation and disambiguation;
• bounded back stack;
• safe Markdown rendering;
• embedded code-viewer lifecycle;
• stale lookup generation protection;
• catalog capability semantics;
• contextual opening from F1, hover, completion, schema references, and future Reference actions.

Reference validity differs from result-bound tools:

• Query-tab switching does not invalidate it;
• Query/Dashboard switching may preserve it;
• workspace changes preserve it only when connection/catalog identity and target remain valid;
• connection change, catalog invalidation, or sign-out closes it and destroys embedded viewers;
• Reference back-stack state remains owned by the Reference controller, not by the shell.

Width and preference migration

Suggested bounds remain subject to real-browser validation:

const RIGHT_INSPECTOR_DEFAULT_PX = 480;
const RIGHT_INSPECTOR_MIN_PX = 320;
const RIGHT_INSPECTOR_MAX_VIEWPORT_RATIO = 0.55;
const MAIN_SURFACE_MIN_PX = 640;

Final clamping must account for viewport width, #487 left-navigation presentation, active centre surface, and the useful centre minimum.

A temporary viewport clamp must not destroy the saved preferred inspector width.

Replace separate browser preferences:

cellDrawerPx
docPanePx

with:

rightInspectorPx

Compatibility read order:

1. valid rightInspectorPx;
2. valid docPanePx;
3. valid cellDrawerPx;
4. default.

Write only rightInspectorPx after migration. Width is a browser preference and must not enter workspace storage, portable bundles, or share links. Fold state and active payload are session state.

The left-edge separator must support pointer and keyboard resizing and integrate with the shell geometry selected by #577. Do not use arbitrary delayed resize events.

Surface, workspace, and teardown behavior

Query -> Dashboard

• preserve valid Reference;
• invalidate or hide Cell/Rows according to result ownership;
• never destroy Query merely to show/hide the inspector;
• reflow Dashboard when the inspector opens, folds, or resizes.

Dashboard -> Query

• preserve valid Reference;
• restore Cell/Rows only if the same originating result is still valid;
• reflow CodeMirror/results through normal layout hooks.

Workspace switch

• invalidate all result-bound tools;
• clear initiators belonging to the old workspace/shell;
• preserve Reference only when explicitly safe;
• stale callbacks from the previous workspace cannot repaint the inspector.

Sign-out/auth loss

• invalidate every tool;
• destroy embedded viewers and listeners;
• cancel active resize and pending structural transition work;
• remove/fold inspector content before Login;
• late callbacks cannot remount it.

Focus and Escape contract

The desktop inspector is non-modal.

• focus moves normally between inspector, editor, and results;
• there is no focus trap;
• Escape while focus is inside the inspector folds it and is consumed through the existing shortcut/overlay contract so it does not also cancel a query;
• Escape outside retains existing global semantics;
• chevron folding restores the most recent connected, still-valid initiator when appropriate;
• tool switching moves focus only for keyboard navigation or when accessibility requires it;
• the chevron, tabs, and separator remain keyboard reachable with visible focus;
• stale transition work must not steal a newer user focus;
• workspace/sign-out teardown must never restore an initiator from an invalid shell.

The implementation is selected by #577. It may use component lifecycle, a hook, a tiny scheduler plus feature policy, or a small service. Preact does not replace the product-specific destination and validity policy.

Accessibility

Inspector host:

role="complementary"
aria-label="Details and reference"

Tool selector:

• proper tabs/tablist semantics when tabs are used;
• active state is announced;
• unavailable tools are absent rather than disabled placeholders.

Resize separator:

role="separator"
aria-orientation="vertical"
aria-valuemin / aria-valuemax / aria-valuenow

Keys:

• Left/Right Arrow resize by a small step;
• Shift+Left/Right resize by a larger step;
• Home uses minimum width;
• End uses the current maximum width.

Chevron direction, visible state, and accessible label remain synchronized.

Mobile

At the existing mobile breakpoint:

• do not apply desktop docked geometry;
• retain existing mobile/full-screen/modal cell and detail behavior where required;
• Reference may use the established mobile pane pattern;
• reuse domain/tool controllers where practical without forcing one desktop/mobile renderer;
• preserve desktop width preference without narrowing mobile permanently.

Main-surface reflow

Opening, folding, tool replacement, or resizing must correctly reflow:

• CodeMirror/editor measurement;
• result columns and virtualized rows;
• editor/results split layout;
• Dashboard grids, flow layouts, charts, and sticky bars;
• detached/fullscreen views where applicable.

Presentation changes must not cancel a running query or Dashboard execution.

Implementation sequence

After #577 establishes the shell architecture:

1. Add the single inspector host, fold state, chevron, tool registry, and unified width preference.
2. Move Reference into the host while preserving its mature behavior.
3. Move Cell and remove its desktop backdrop/focus trap.
4. Move Rows/detail consumers.
5. Remove obsolete independent desktop insertion, width writes, backdrops, close controls, and renderer/lifecycle paths.
6. Keep mobile-specific composition behind the existing breakpoint.
7. Verify simultaneous left/right docking and Query/Dashboard behavior.
8. If implemented under Migrate the application UI to Preact in measured simplification phases #578, record production LOC removed/added, deleted ownership paths, bundle delta, and temporary bridges.

Tests

Shell and fold state

• one inspector host per shell/document;
• folded state leaves only the chevron and consumes no panel width;
• open state reduces centre width;
• chevron direction and label are correct;
• folding preserves valid tool state;
• no desktop backdrop or focus trap;
• left and right panels coexist within centre-width limits.

Tool selection and validity

• Cell/Rows/Reference open, unfold, and activate correctly;
• replacing one payload does not destroy other valid tool state;
• closing one activates the most recent valid remaining tool;
• no valid tools folds the inspector;
• duplicate independent panels cannot be created;
• result rerun/tab/workspace removal invalidates Cell/Rows;
• stale async work cannot repaint;
• Reference back stack, aliases, disambiguation, Retry, and embedded-viewer disposal remain correct.

Width and migration

• rightInspectorPx restores and clamps;
• compatibility reads docPanePx, then cellDrawerPx;
• only the unified key is written;
• viewport clamping does not overwrite preferred width;
• pointer/keyboard resize behavior matches;
• cancellation, blur, remount, and sign-out leave no listeners or stale work.

Focus, accessibility, and reflow

• Escape inside folds only the inspector and does not cancel a query;
• safe initiator restoration and fallbacks are proven in Chromium and WebKit;
• stale restoration cannot steal newer focus;
• complementary, tabs, separator, and chevron semantics are correct;
• editor/results/Dashboard reflow correctly;
• opening/folding never cancels execution;
• Query state survives Dashboard round trips;
• no mobile, detached, or fullscreen regression.

Acceptance criteria

1. Desktop has one foldable right inspector for Cell, Rows/detail, and Reference.
2. The inspector is docked, consumes layout width, and never overlays the desktop editor/Dashboard.
3. One chevron controls the panel and redundant desktop panel controls are removed.
4. Contextual triggers automatically open the correct tool.
5. Result-bound tools cannot display stale content.
6. Reference retains navigation, async safety, and embedded-viewer lifecycle.
7. Width is unified into one browser preference with deterministic migration.
8. Left navigation, Query, and Dashboard share a coherent width/reflow policy.
9. Mobile behavior remains appropriate and is not permanently narrowed.
10. Focus and Escape behavior are safe, non-modal, and proven in Chromium and WebKit.
11. Workspace switch and sign-out cannot leak tools, listeners, initiators, or stale callbacks.
12. If implemented through Migrate the application UI to Preact in measured simplification phases #578, the inspector deletes the independent vanilla desktop implementations it replaces and reduces production UI complexity.

Non-goals

• Moving unrelated modal confirmations into the inspector.
• Showing several inspector tools side by side.
• Persisting inspector payloads in workspace data.
• Redesigning Cell or Reference content beyond host integration.
• Replacing detached/fullscreen views serving a distinct purpose.
• Redesigning mobile navigation.
• Selecting Preact or defining the whole migration inside this feature issue.

Related

• Add dashboard selection state and a full-size dashboard work surface #425 — prerequisite work.
• Evaluate Preact migration as an application-wide simplification #577 — evaluate and decide the UI-shell architecture.
• Migrate the application UI to Preact in measured simplification phases #578 — phased Preact migration if approved; right inspector is Phase 3.
• Add a drag-foldable desktop left navigation with rail and focused drawers #487 — left navigation and shared centre-width/focus behavior.

[BorisTyshkevich]

sql-browser-shell-prototype.html

[BorisTyshkevich]

Planning update: the issue body now treats the inspector as a product/domain contract rather than prescribing the current imperative shell implementation. Full implementation waits for #577; if Preact is selected it is Phase 3 of #578, after the shared shell and #487 navigation phase are established.