rustdoc: add a handle that makes sidebar resizing more obvious

[lolbinarycat]

r? @notriddle

light theme not yet supported.

handle is given a different cursor mainly because the col-resize cursor doesn't work on my machine for some reason.

[rust-log-analyzer]

The job mingw-check-tidy failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)

info: removing rustup binaries
info: rustup is uninstalled
##[group]Image checksum input
mingw-check-tidy
# We use the ghcr base image because ghcr doesn't have a rate limit
# and the mingw-check-tidy job doesn't cache docker images in CI.
FROM ghcr.io/rust-lang/ubuntu:22.04

ARG DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
  g++ \
  make \
---

COPY host-x86_64/mingw-check/validate-toolstate.sh /scripts/
COPY host-x86_64/mingw-check/validate-error-codes.sh /scripts/

# NOTE: intentionally uses python2 for x.py so we can test it still works.
# validate-toolstate only runs in our CI, so it's ok for it to only support python3.
ENV SCRIPT TIDY_PRINT_DIFF=1 python2.7 ../x.py test \
           --stage 0 src/tools/tidy tidyselftest --extra-checks=py,cpp
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    pip-compile --allow-unsafe --generate-hashes reuse-requirements.in
---
#12 2.839 Building wheels for collected packages: reuse
#12 2.840   Building wheel for reuse (pyproject.toml): started
#12 3.059   Building wheel for reuse (pyproject.toml): finished with status 'done'
#12 3.060   Created wheel for reuse: filename=reuse-4.0.3-cp310-cp310-manylinux_2_35_x86_64.whl size=132719 sha256=5bb60f62728aaedff7162745ce743c7f2f55069b3e7f82e6a37d70df455797cc
#12 3.061   Stored in directory: /tmp/pip-ephem-wheel-cache-lngft5m_/wheels/3d/8d/0a/e0fc6aba4494b28a967ab5eaf951c121d9c677958714e34532
#12 3.063 Successfully built reuse
#12 3.064 Installing collected packages: boolean-py, binaryornot, tomlkit, reuse, python-debian, markupsafe, license-expression, jinja2, chardet, attrs
#12 3.482 Successfully installed attrs-23.2.0 binaryornot-0.4.4 boolean-py-4.0 chardet-5.2.0 jinja2-3.1.4 license-expression-30.3.0 markupsafe-2.1.5 python-debian-0.1.49 reuse-4.0.3 tomlkit-0.13.0
#12 3.483 WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
#12 4.040 Collecting virtualenv
#12 4.082   Downloading virtualenv-20.30.0-py3-none-any.whl (4.3 MB)
#12 4.147      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.3/4.3 MB 69.6 MB/s eta 0:00:00
#12 4.188 Collecting distlib<1,>=0.3.7
#12 4.192   Downloading distlib-0.3.9-py2.py3-none-any.whl (468 kB)
#12 4.200      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 469.0/469.0 KB 84.6 MB/s eta 0:00:00
#12 4.236 Collecting platformdirs<5,>=3.9.1
#12 4.241   Downloading platformdirs-4.3.7-py3-none-any.whl (18 kB)
#12 4.280 Collecting filelock<4,>=3.12.2
#12 4.284   Downloading filelock-3.18.0-py3-none-any.whl (16 kB)
#12 4.371 Installing collected packages: distlib, platformdirs, filelock, virtualenv
#12 4.568 Successfully installed distlib-0.3.9 filelock-3.18.0 platformdirs-4.3.7 virtualenv-20.30.0
#12 4.569 WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
#12 DONE 4.7s

#13 [7/8] COPY host-x86_64/mingw-check/validate-toolstate.sh /scripts/
#13 DONE 0.0s
---
DirectMap4k:      137152 kB
DirectMap2M:     7202816 kB
DirectMap1G:    11534336 kB
##[endgroup]
Executing TIDY_PRINT_DIFF=1 python2.7 ../x.py test            --stage 0 src/tools/tidy tidyselftest --extra-checks=py,cpp
+ TIDY_PRINT_DIFF=1 python2.7 ../x.py test --stage 0 src/tools/tidy tidyselftest --extra-checks=py,cpp
##[group]Building bootstrap
    Finished `dev` profile [unoptimized] target(s) in 0.05s
##[endgroup]
WARN: currently no CI rustc builds have rustc debug assertions enabled. Please either set `rust.debug-assertions` to `false` if you want to use download CI rustc or set `rust.download-rustc` to `false`.
WARN: `rust.debug-assertions = true` will prevent downloading CI rustc as alt CI rustc is not currently built with debug assertions.
---
[TIMING] core::build_steps::tool::Tidy { compiler: Compiler { stage: 0, host: x86_64-unknown-linux-gnu, forced_compiler: false }, target: x86_64-unknown-linux-gnu } -- 0.000
fmt check
fmt: checked 5952 files
tidy check
- --code-block-background-color: #f5f5f5;
+ --sidebar-resize-hint-color: #000a;
tidy error: noscript.css:46 and rustdoc.css:2914 contain copies of light theme that are not the same
tidy: Skipping binary file check, read-only filesystem
##[error]tidy error: /checkout/src/librustdoc/html/static/css/rustdoc.css:525: trailing whitespace
removing old virtual environment
creating virtual environment at '/checkout/obj/build/venv' using 'python3.10' and 'venv'
creating virtual environment at '/checkout/obj/build/venv' using 'python3.10' and 'virtualenv'
Requirement already satisfied: pip in ./build/venv/lib/python3.10/site-packages (25.0.1)
linting python files
All checks passed!
checking python file formatting
26 files already formatted
checking C++ file formatting
some tidy checks failed
Command has failed. Rerun with -v to see more details.
Build completed unsuccessfully in 0:01:54
  local time: Sat Apr  5 19:44:37 UTC 2025
  network time: Sat, 05 Apr 2025 19:44:38 GMT
##[error]Process completed with exit code 1.
Post job cleanup.

[notriddle]

Do any other applications have resize handles that look like this? I can't think of any, but I haven't really looked.

[lolbinarycat]

I've definitely seen something similar before, but i can't say exactly where.

maybe it was an old version of chrome os when using 2 windows in split screen.

there's not a lot of "modern" (non-skeuomorphic) programs that use resizable ui element (unfortunately imo, win95 era ui has a lot of conventions that are very useful), so i'm a bit starved for inspiration outside of dishant memories.

there's the textarea handle, but that would clash awkwardly with the scrollbar.

at the very least, this should make it clear that there's something that can be done there, which is a large improvement over the statue quo.

i should definitely add a tooltip, tho.

[notriddle]

I poked around a few apps that I knew had resizeable sidebars. You're right: most have nothing. The folder navigation sidebars in GitHub, Windows, macOS, KDE, and GTK are all resizeable, but there's no real indicator of this, just a line.

The ones I found were mdBook, The GIMP, and LibreOffice.

Screenshots

Note that the big black thing in LO's sidebars is actually a button you can click to hide and show the sidebar, but you can also drag it.

Here's what it looks line with version that looks line LibreOffice and mdBook:

Here's what it looks like with a copy of GIMP's version:

Code

/* mdBook/libreoffice version */
.sidebar-resizer {
  touch-action: none;
  width: 9px;
  cursor: col-resize;
  z-index: calc(var(--desktop-sidebar-z-index) + 1);
  position: fixed;
  height: 100%;
  left: calc(var(--desktop-sidebar-width));
  border-left: solid 2px var(--sidebar-background-color);
  border-right: solid 2px var(--main-background-color);
  image-rendering: crisp-edges;
  background:
url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="8" height="32" viewBox="0 0 8 32"><line stroke-width="2" stroke="%23888" y1="24" x1="3" y2="8" x2="3"/></svg>') no-repeat center center;
}
/* GIMP version */
.sidebar-resizer {
  touch-action: none;
  width: 9px;
  cursor: col-resize;
  z-index: calc(var(--desktop-sidebar-z-index) + 1);
  position: fixed;
  height: 100%;
  left: calc(var(--desktop-sidebar-width));
  border-left: solid 2px var(--sidebar-background-color);
  border-right: solid 2px var(--main-background-color);
  border-image:
url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAQCAAAAAAO4WGhAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAdnJLH8AAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAAAlwSFlzAAAuIwAALiMBeKU/dgAAAAd0SU1FB+kEBwEQAanPNmMAAAASSURBVAhbY5AzBQE/OYbBwQAAEpEZMUR2DroAAAAASUVORK5CYII=) 2;
  image-rendering: crisp-edges;
  background:
url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="8" height="32" viewBox="0 0 8 32"><circle r="2" fill="%23888" cy="16" cx="3"/><circle r="2" fill="%23888" cy="24" cx="3"/><circle r="2" fill="%23888" cy="8" cx="3"/></svg>') no-repeat center center;
}

[notriddle]

I'm leaning towards doing nothing, though. Because literally every major desktop has resizeable navigation sidebars with no visible handle, there's no convention we can expect readers to recognize.

An indicator that the user doesn't recognize is clutter, and clutter is worse than useless.

[lolbinarycat]

@notriddle The problem is, resizable elements are potentially orders of magnitude more common in desktop applications than on the web, and the cursor change may not work.

I do agree that the current addition does add significant clutter, which is not ideal.

What about a resize handle that only shows up when hovering over it, in addition to widening the handle, and adding a tooltip?

[notriddle]

unfortunately imo, win95 era ui has a lot of conventions that are very useful

It's actually pretty hard to decide how to do this even if I do look to old versions of Windows

In that screenshot:

• I can drag on the little | handles to resize and move individual toolbar and taskbar modules
• I can drag on the edge of the taskbar to make it bigger
• I can drag on the divider between the Favorites sidebar and main content area, or between the toolbar and main content area
• I cannot resize the status bar, even though it has nearly the same style of divider as the toolbar (Maybe it's a little shorter? Hard to tell because nearby color contrast is different.)

The closest thing to a truly unambiguous indicator of resizability is the | at the lefthand edge of each toolbar module, and, as Joel Spolsky recounts, that feature had poor usability and was ultimately canned.

there's not a lot of "modern" (non-skeuomorphic) programs that use resizable ui element

I did some more hunting, and finally found another web app with an explicit handle and enough market penetration to make a convention: Jira. It looks a lot like GIMP, but with four dots instead of three.

What about a resize handle that only shows up when hovering over it

It already does that. It doesn't help much, because things that only appear on hover aren't easily discoverable.

and the cursor change may not work

We should try to fix that. It's the only truly solid convention we have.

Does the file browser in GitHub work on your system? When I say "file browser," I explicitly mean the one that comes up when you browse into a repository's files: the pull request patch viewer's sidebar doesn't seem to be resizable.

[lolbinarycat]

@notriddle

It's actually pretty hard to decide how to do this even if I do look to old versions of Windows

I don't know if it will help here, but I think its a good source of inspiration in general. For example, we already use the icon w/ label underneath pattern in rustdoc.

Does the file browser in GitHub work on your system? When I say "file browser," I explicitly mean the one that comes up when you browse into a repository's files: the pull request patch viewer's sidebar doesn't seem to be resizable.

It does not work, col-resize is missing from my cursor theme. I think the only thing that would work is if we used a cursor from a url.

Unfortunately we can't provide multiple builtin cursor options like you can with fonts. I've actually opened a w3c issue about this: w3c/csswg-drafts#12047