Add help button to the packages pane by bricestacey · Pull Request #13499 · posit-dev/positron

bricestacey · 2026-05-11T15:23:40Z

This adds a help button next to each item in the packages pane. Currently, it only supports attached packages. In the case of the packages pane, these are items with a green dot next to them.

Release Notes

New Features

Add help button to attached packages in the Packages pane

Bug Fixes

N/A

Validation Steps

First, you must attach a package to the runtime using your usual import cowsay or library(cowsay)
You'll then need to refresh the packages list.
Finally, the button should appear.

@:help @:packages-pane

github-actions · 2026-05-11T15:24:07Z

E2E Tests 🚀
This PR will run tests tagged with: @:critical @:help @:packages-pane

^readme ^{valid tags}

jennybc

With the caveat that I'm just reacting to the screenshot (I haven't test driven this), I think R folks expect to be taken to a package's help index, as opposed to the package-level help topic. I think this PR is going to the latter (?). Probably the clearest way to see what I mean is to do the equivalent move in RStudio.

bricestacey · 2026-05-11T17:48:14Z

With the caveat that I'm just reacting to the screenshot (I haven't test driven this), I think R folks expect to be taken to a package's help index, as opposed to the package-level help topic. I think this PR is going to the latter (?). Probably the clearest way to see what I mean is to do the equivalent move in RStudio.

You're correct. This uses the Positron help service, which most closely resembles the behavior for ?. I think we have two options:

Option 1:

If the current language is R, we can instead call ??package silently in the console, which opens the help index.
Otherwise, default to the help service.

Option 2:

Go with what this PR does and create follow-up tickets to resolve the inconsistent expectations.

jennybc · 2026-05-11T19:23:05Z

My guess is that opening the help index is a pretty high priority for R users. It turns out most of us ~~don't know about (or forget) the ?? trick and~~ have various weird workarounds for accessing the help index, which is legitimately useful. So I can imagine this is a real reason some folks like the packages pane.

Update: I just assumed ?? opened the help index when I wrote this but that's not true, so I struck it out.

I am agnostic whether to solve in this PR or a subsequent one.

jennybc · 2026-05-11T19:33:03Z

Somewhat related to #9062

bricestacey · 2026-05-11T21:08:50Z

Option 1:

If the current language is R, we can instead call ??package silently in the console, which opens the help index.
Otherwise, default to the help service.

I went ahead and did this, but it feels weird to me. ?? is actually just plain-old search... So, it's like just searching for the package's name. Is that really what people really want? On the other hand, I noticed the default package help pages are mostly useless as it only includes some cover page without any further links to dig deeper.

Here is an example when I do ??datasets:

One bug I ran into was that we would ignore any new help pages if they had the same URL as the current page, so I fixed that in de7d3b4

jennybc · 2026-05-11T21:38:27Z

Sorry I went along with something you said without checking it myself and ended up misleading you.

If people want help for dplyr, they probably want this: help(package = "dplyr"). Which is the index of help topics for the dplyr package.

jennybc · 2026-05-11T21:40:13Z

On the other hand, I noticed the default package help pages are mostly useless as it only includes some cover page without any further links to dig deeper.

Yes, there's no requirement that a package have such a help topic and many don't. Or have something so minimal as to be practically useless.

I assume this was added as a performance enhancement, but it introduces bugs with the Ark implementation of help. The search help pages are all served from the same URL. So if a user entered: ``` ??base ??cowsay ``` The help pane would open to the search results for `base` but not `cowsay`. The user can resolve this by manually navigating away from the page and re-executing `??cowsay` as the `sourceUrls` would never previously match between pages. This bug came out of #13499 but we chose a different implementation where this fix was no longer needed.

softwarenerd · 2026-05-20T20:53:10Z

+}
+
+.packages-list-item:hover .packages-list-item-help {
+	opacity: 0.85;


This reads a little light on my machine. Perhaps just make it fully opaque?

I don't think we want fully opaque because we want a contrast in brightness and therefore emphasis, but you're right the existing opacity was a bit light. Here is at least a justification, but if you try it out I think you'll find it's fine.

Bumped idle opacity from 0.5 → 0.7. Why not fully opaque (softwarenerd's suggestion): WCAG 2.1 SC 1.4.11 requires only 3:1 contrast for non-text UI components. VS Code's default foreground/background contrast is comfortably above 7:1 across stock themes, so 0.7 stays well over the 3:1 floor while preserving the visual hierarchy that lets the package name remain the focal point of each row. Progressive reveal is preserved: idle 0.7 → row hover 0.85 → button hover 1.

softwarenerd · 2026-05-20T21:01:29Z

+					>
+						<svg fill='currentColor' height='11' viewBox='0 0 16 16' width='11'>
+							<path d='M2 2.5A.5.5 0 012.5 2H5c1.1 0 2.1.4 2.9 1.1.7-.7 1.8-1.1 2.9-1.1h2.5a.5.5 0 01.5.5v10a.5.5 0 01-.5.5H11c-1 0-1.9.4-2.5 1.1-.6-.7-1.5-1.1-2.5-1.1H2.5a.5.5 0 01-.5-.5v-10zM7.5 4.1C6.9 3.4 6 3 5 3H3v9h3c.7 0 1.4.2 2 .5.6-.3 1.2-.5 2-.5h2V3h-2c-1 0-1.9.4-2.5 1.1z' />
+						</svg>


Perhaps this should be a codicon? @paul-dicristina can help with generating it.

I just used the codicon, which already exists, but resized it.

Adds a help button on each row in the Packages pane (rendered only for attached packages) that opens the package's help topic in the Help pane via IPositronHelpService.showHelpTopic. Also bumps row horizontal padding to 12px and switches the row to border-box sizing so its padding sits inside react-window's assigned width, eliminating the horizontal scroll the row was producing. See #12773

`??name` does a fuzzy search across every installed package; what we actually want from the Packages-pane button is the package's help index. `help(package = "name", help_type = "html")` is the canonical entry point -- printing the result triggers ark's browseURL hook, which surfaces the index in the help pane. See #12773

Swap the inline SVG for the existing codicon-book glyph, and raise the idle opacity from 0.5 to 0.7 so the help button meets WCAG 1.4.11's 3:1 non-text contrast minimum across stock themes.

bricestacey · 2026-05-21T20:19:58Z

Rebased this so it now includes the new PositronList

softwarenerd

LG.

bricestacey force-pushed the 12773/packages-help-link branch 2 times, most recently from 217950a to 1e6a6da Compare May 11, 2026 16:45

jennybc reviewed May 11, 2026

View reviewed changes

bricestacey mentioned this pull request May 11, 2026

Allow python help to be shown when package not imported #13501

Merged

bricestacey requested a review from softwarenerd May 11, 2026 19:46

bricestacey force-pushed the 12773/packages-help-link branch 2 times, most recently from 107ef99 to de7d3b4 Compare May 11, 2026 21:03

ntluong95 mentioned this pull request May 11, 2026

Update Package pane according to recent changes upstream ntluong95/positron-julia#16

Open

Copilot AI mentioned this pull request May 11, 2026

Update Julia Packages pane integration for latest Positron package API ntluong95/positron-julia#17

Draft

bricestacey force-pushed the 12773/packages-help-link branch from de7d3b4 to 1d5a46a Compare May 12, 2026 00:23

bricestacey mentioned this pull request May 12, 2026

Allow adding help pages even if same sourceUrl #13503

Closed

softwarenerd requested changes May 20, 2026

View reviewed changes

bricestacey requested a review from softwarenerd May 21, 2026 14:15

bricestacey added 7 commits May 21, 2026 16:10

Add e2e tests for the help button

bd8ae22

Refactor using the page object

0eb2f7c

Use filter instead of scroll to find the package

e88b498

R users would prefer to use the ?? operator instead of the default ?

c240922

Use book codicon and bump help button opacity for accessibility

4215b6f

Swap the inline SVG for the existing codicon-book glyph, and raise the idle opacity from 0.5 to 0.7 so the help button meets WCAG 1.4.11's 3:1 non-text contrast minimum across stock themes.

bricestacey force-pushed the 12773/packages-help-link branch from 4d2f67a to 4215b6f Compare May 21, 2026 20:18

softwarenerd approved these changes May 21, 2026

View reviewed changes

ntluong95 mentioned this pull request May 21, 2026

Update Package pane according to recent changes upstream TidierOrg/positron-julia#5

Closed

bricestacey merged commit 4899a3e into main May 22, 2026
24 checks passed

bricestacey deleted the 12773/packages-help-link branch May 22, 2026 13:32

github-actions Bot locked and limited conversation to collaborators May 22, 2026

Conversation

bricestacey commented May 11, 2026

Release Notes

New Features

Bug Fixes

Validation Steps

Uh oh!

github-actions Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jennybc left a comment

Choose a reason for hiding this comment

Uh oh!

bricestacey commented May 11, 2026

Uh oh!

jennybc commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jennybc commented May 11, 2026

Uh oh!

bricestacey commented May 11, 2026

Uh oh!

jennybc commented May 11, 2026

Uh oh!

jennybc commented May 11, 2026

Uh oh!

softwarenerd May 20, 2026

Choose a reason for hiding this comment

Uh oh!

bricestacey May 21, 2026

Choose a reason for hiding this comment

Uh oh!

softwarenerd May 20, 2026

Choose a reason for hiding this comment

Uh oh!

bricestacey May 21, 2026

Choose a reason for hiding this comment

Uh oh!

bricestacey commented May 21, 2026

Uh oh!

softwarenerd left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented May 11, 2026 •

edited

Loading

jennybc commented May 11, 2026 •

edited

Loading