Skip to content

Viewer: pin the projections list as a pane - #77

Open
agorischek wants to merge 8 commits into
toolbar-sidesfrom
projections-pane
Open

agorischek wants to merge 8 commits into
toolbar-sidesfrom
projections-pane

Conversation

@agorischek

@agorischek agorischek commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Stacked on #65 (toolbar-sides). The user asked to turn the projections list into a pinnable pane: the dropdown stays the default, and "Pin projections pane" at the end of the menu turns the list into a durable left pane, with an X that returns to the dropdown.

Viewer (CLI viewer and Copilot canvas)

  • Menu: the title's projection menu ends with Pin projections pane (lucide PanelLeft), after a separator. It's the last option the arrow keys reach.
  • Pinned:
    • a 240px pane at the page's start, beside the toolbar and stage, under the header, with one 1px divider against the stage;
    • its header row is 41px, the toolbar's row, so the two read as one band;
    • each projection shows its title, its ID in mono, and its status dot.
  • Accessibility: a nav landmark named "Projections"; the shown projection has aria-current="page". Focus moves to it when pinned, and back to the title's menu when closed.
  • The title: while pinned, it's the title alone, with no menu.
  • Persistence: localStorage projections:pane-pinned:viewer. After a reload it's still pinned and doesn't take focus.
  • When it's offered: only with more than one projection and at least 900px of width (32px hysteresis). Narrower, a pinned pane falls back to the menu, which doesn't offer pinning.

Host core API (for other surfaces; the shadcn hosted rebuild and host-primer use the same names):

  • ProjectionsPane({items, current, onChoose?, onClose, label?, autoFocus?, footer?}), with items {id, title, detail?, status?}
  • usePinnedPane(key)
  • usePaneRoom(element?)
  • paneWidth (240), paneHeaderHeight (41), paneMinWidth (900)

The Inspector takes an aside beside a viewer page's body. The guide (docs/guides/host-core.md) documents it.

Not here:

  • VS Code: it already has the native Projections tree in its side bar, and each projection is its own tab, so a second list in the tab would duplicate it.
  • The browser Inspector workbench: it's being retired.
  • The Playground PR tab: built on githubnext/projections.private#16 with Primer NavList.

Tests: packages/cli/browser/viewer.spec.ts has a new test, run by CI. It covers:

  • pinning by keyboard from the menu's last option;
  • the landmark, its 240px width and the focused current item;
  • the toolbar starting at 240;
  • choosing another projection;
  • a reload keeping it pinned without focus;
  • the 860px fallback, with no pin option;
  • closing, which returns focus to the menu and clears storage.

The title test now expects the pin option after the two projections. I checked the same flow by hand against a running viewer, in light and dark.

The screenshots predate #65's floating foot (the legend and summary show as bands here).

Light Dark
Unpinned unpinned, light unpinned, dark
Menu menu with Pin projections pane, light menu with Pin projections pane, dark
Pinned pinned pane, light pinned pane, dark
880px: falls back to the menu narrow fallback, light narrow fallback, dark

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved keyboard and focus issues leave the switcher targeting a removed option after resizing, focus an off-screen projection when pinning, and cause the fallback dropdown to reopen unexpectedly on later resizes.

3 open issues
What changed in this PR

Adds a pinnable projections list to the CLI viewer and Copilot canvas, building on the toolbar layout work. The dropdown remains the default, with a persistent pane available when space allows.

Changes:

  • Adds a 240px pane with projection status, selection, and keyboard focus handling.
  • Persists pinning across reloads and falls back to the dropdown on narrow screens.
  • Exports reusable host-core components and hooks, with documentation and browser coverage.
File Description
packages/​host/​inspector/​src/​viewer/​title.tsx Adds pin action and focus restoration support.
packages/​host/​inspector/​src/​viewer/​pane.tsx Implements viewer pane, persistence, and visibility.
packages/​host/​inspector/​src/​viewer/​mount.tsx Mounts the pane beside the viewer.
packages/​host/​inspector/​src/​viewer/​chrome.tsx Connects pinned state to title menu behavior.
packages/​host/​inspector/​src/​shell/​switcher.tsx Adds the keyboard-accessible pin option.
packages/​host/​inspector/​src/​mount.tsx Passes the aside option into the Inspector.
packages/​host/​inspector/​src/​app/​workbench.tsx Places the aside beside the viewer body.
packages/​host/​inspector/​src/​app/​props.ts Defines the viewer aside property.
packages/​host/​inspector/​src/​app/​inspector-app.tsx Forwards the aside to the page frame.
packages/​host/​core/​src/​ui/​projections-pane.tsx Adds reusable pane UI, sizing, and persistence hooks.
packages/​host/​core/​src/​ui/​index.ts Exports the pane API.
packages/​cli/​browser/​viewer.spec.ts Covers pinning, selection, persistence, fallback, and closing.
docs/​guides/​host-core.md Documents the pane API and clarifies loading-status behavior.

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

3 open issues
3 resolved since last review

Review effort: Lite

Comment thread packages/cli/browser/viewer.spec.ts Resolved

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

When responsive resizing hides the pinned pane while it owns focus, focus falls to the document body instead of returning to the title menu.

1 open issue
3 resolved since last review

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The review identifies no active issues blocking approval of the pinnable projections pane change.

No open issues 🎉

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Two focus-management issues remain: enabling autoFocus can focus an off-screen row, and a menu-focus request queued during disconnection can later steal focus after reconnection.

2 open issues

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Focus handoff transitions remain scattered across writable state and component effects, leaving ordering implicit and requiring a centralized machine with an explore test covering pin, close, resize, and disconnect sequences.

1 open issue
2 resolved since last review

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The persistent, pinnable projections pane change has no active review issues.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

agorischek and others added 8 commits November 20, 2026 20:31
The title's projection menu ends with "Pin projections pane", after a separator
and reached by the arrow keys. Pinned, the list is a 240px pane at the page's
start, beside the toolbar and stage: a "Projections" navigation landmark whose
header (the toolbar's row) has a close button back to the menu, and each
projection with its ID and status, the shown one `aria-current="page"` and
scrolled into view. Focus moves to it when the person pins it and back to the
menu when they close it. The title is the title alone while it's pinned. It is
remembered across reloads (`projections:pane-pinned:viewer`) and offered only
with more than one projection and 900px of room; narrower, the page falls back
to the menu.

The host core exports it for other surfaces: `ProjectionsPane`,
`usePinnedPane`, `usePaneRoom`, `paneWidth`, `paneHeaderHeight` and
`paneMinWidth`. The Inspector takes an `aside` beside a viewer page's body.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The title closes its menu in an effect when the menu goes away; the header
measures the pane's room once; the spec's widths tolerate fractional layout.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…the menu

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…pane

The title's menu says when it goes away holding focus, and the pane that
replaces it takes focus; ProjectionsPane focuses whenever autoFocus turns on.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
usePinnedPane, usePaneRoom and paneMinWidth move to the package root so a
custom UI can reuse them; ProjectionsPane and its sizes stay in /ui.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…s store

Replaces the boolean refs, which the lifecycle check flags, with the store's
focusWithin.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…us only to a menu that's there

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
paneFocusMachine owns where focus is and where it goes next (pinning, closing,
the page narrowing or widening, the server stopping); the pane and the title's
menu report focus and take it when the state asks. Explored in its test.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants