Skip to content

feat(sidebar): quieter scrollbars and a bottom fade in the sidebar - #740

Open
itsprade wants to merge 2 commits into
mainfrom
feat/sidebar-scroll-polish
Open

itsprade wants to merge 2 commits into
mainfrom
feat/sidebar-scroll-polish

Conversation

@itsprade

Copy link
Copy Markdown
Contributor

What

The sidebar's item list and the icon rail's group flyout used the global scrollbar: 8px wide with a grey track, always visible. It drew a stripe down the sidebar, 8px in from its edge. This PR makes both scroll more quietly, without touching the global scrollbar style.

  • Show-while-scrolling scrollbar: thin, with no track, visible only while the list is scrolling. It hides 0.8s after the last scroll.
  • On the edge: in the default inset sidebar, the list reaches into the panel's 8px padding, so the scrollbar sits on the sidebar's edge. The items don't move. The floating variant keeps its card padding.
  • Bottom fade: while there is more to scroll, the bottom 2rem of the list fades out. It clears over the last 2rem of scroll, and a list that fits never fades. It uses the same scroll-driven mask as the content area's existing top fade, so it needs no JavaScript.
  • Keyboard focus: both scroll areas get 2rem of bottom scroll padding, so an item scrolled into view by Tab stops clear of the fade.

How

  • Shared helper: sidebar/scroll-area.ts (internal) holds the classes and a small useScrolling hook. "Scrolling" is set from the scroll event handler, and a timer clears it. The only effect clears that timer on unmount.
  • Sidebar list: SidebarContent uses the helper and still calls a consumer's own onScroll.
  • Flyout: its list now scrolls inside the popup instead of the popup itself. Otherwise the fade's mask would also erase the popup's border and shadow.
  • Keyframes: globals.css gains one keyframe, appshell-sidebar-fade, next to the existing appshell-content-fade. No existing rule changes.

No public API changes. A patch changeset describes the visual change.

Browser support

  • The fade: needs scroll-driven animations (Chrome and Edge 115+, Safari 26). Elsewhere, such as Firefox, there's simply no fade, as with the existing top fade.
  • The scrollbar style: uses scrollbar-width and scrollbar-color. Safari may ignore scrollbar-color and keep the global 8px webkit scrollbar style there. Worth a check if anyone is on Safari with "Show scroll bars: Always".

Testing

  • New tests:
    • the scrolling flag sets on scroll, restarts on each scroll, clears 0.8s after the last one, and the consumer's onScroll still runs
    • the inset-edge classes
    • the flyout's list scrolls inside the popup and shows its scrollbar while scrolling
  • Checked in the example app:
    • no scrollbar at rest
    • the list's edge meets the sidebar border
    • the fade appears with more below and clears at the end
    • the flyout keeps its border and shadow
  • All checks pass: format, docs, types, lint, tests (3,093) and the example app's types.
  • Merges cleanly with fix(sidebar): keep the shell frame from scrolling #706 (shell frame scroll fix); the two are independent.

Things to look at

  • The scrollbar now sits on the sidebar's edge, where the resize handle's hover zone is. It felt fine in use, but have a quick go at grabbing the handle.
  • The thumb is a soft grey (45% of --muted-foreground), similar to a macOS overlay scrollbar. It's lighter than the 3:1 guidance for controls; say if you'd rather it be stronger.

🤖 Generated with Claude Code

The sidebar's item list and the icon rail's group flyout used the global
scrollbar: 8px with a grey track, always visible, drawing a stripe down
the sidebar.

- Thin scrollbar with no track, shown only while the list is scrolling.
- In the inset sidebar, the list reaches into the panel's 8px padding so
  the scrollbar sits on the sidebar's edge; the items stay in place.
- A bottom fade while there is more to scroll, using the same
  scroll-driven mask as the content area's top fade.
- Scroll padding as tall as the fade, so keyboard focus stops clear of it.
- The flyout's list now scrolls inside the popup, so the fade doesn't
  also mask the popup's border and shadow.

Shared by both through sidebar/scroll-area.ts. Global scrollbar styles
are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@itsprade
itsprade requested a review from a team as a code owner November 18, 2026 06:30
@github-actions

Copy link
Copy Markdown
Contributor

Code Metrics Report

main (923933d) #740 (a8fb1b1) +/-
Coverage 62.9% 62.9% +0.0%
Test Execution Time 4m3s 3m7s -56s
Details
  |                     | main (923933d) | #740 (a8fb1b1) |  +/-  |
  |---------------------|----------------|----------------|-------|
+ | Coverage            |          62.9% |          62.9% | +0.0% |
  |   Files             |            294 |            295 |    +1 |
  |   Lines             |          13483 |          13503 |   +20 |
+ |   Covered           |           8485 |           8500 |   +15 |
+ | Test Execution Time |           4m3s |           3m7s |  -56s |

Code coverage of files in pull request scope (11.5% → 11.7%, patch 100.0%)

Files Coverage +/- Patch Coverage Status
packages/core/dist/app-shell.js 8.5% +0.0% - affected
packages/core/src/components/sidebar/primitives.tsx 91.3% +0.2% 100.0% modified
packages/core/src/components/sidebar/scroll-area.ts 100.0% +100.0% 100.0% added
packages/core/src/components/sidebar/sidebar-group.tsx 100.0% 0.0% 100.0% modified

Reported by octocov

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

The changes leave overlapping scrollbar and resize-handle targets, scrollbar-thumb contrast below the required 3:1 ratio, and a scroll mask that snaps rather than fades smoothly.

3 open issues
What changed in this PR

This PR refines scrolling in AppShell’s sidebar list and icon-rail flyouts without changing the public API or global scrollbar styles.

Changes:

  • Adds a shared scrolling hook for thin, trackless scrollbars that hide after 800ms.
  • Moves inset sidebar scrollbars to the panel edge and adds a scroll-driven bottom fade with keyboard-focus padding.
  • Moves flyout scrolling inside the popup to preserve its frame, with regression tests and a patch changeset.
File Description
packages/​core/​src/​globals.css Adds sidebar bottom-fade keyframes.
packages/​core/​src/​components/​sidebar/​sidebar.test.tsx Tests scrollbar timing, consumer callbacks, and inset-edge classes.
packages/​core/​src/​components/​sidebar/​sidebar-group.tsx Introduces an inner flyout scroll area.
packages/​core/​src/​components/​sidebar/​scroll-area.ts Adds shared scroll styling and visibility state.
packages/​core/​src/​components/​sidebar/​primitives.tsx Applies scrolling behavior and inset-edge spacing to the sidebar list.
packages/​core/​src/​components/​sidebar/​default-sidebar.test.tsx Tests flyout scroll containment and visibility state.
.changeset/​quiet-sidebar-scroll.md Records the visual changes for a patch release.

Review effort: Balanced

SIDEBAR_SCROLL_AREA_CLASS,
// The inset sidebar pads its panel by 8px; reach into that padding so
// the scrollbar sits on the sidebar's edge, keeping the content in place.
"astw:group-data-[variant=inset]:-mr-2 astw:group-data-[variant=inset]:pr-2",
*/
export const SIDEBAR_SCROLL_AREA_CLASS = [
"astw:[scrollbar-width:thin] astw:[scrollbar-color:transparent_transparent]",
"astw:data-scrolling:[scrollbar-color:color-mix(in_oklab,var(--muted-foreground)_45%,transparent)_transparent]",
Comment thread packages/core/src/globals.css Outdated
/* Sidebar list: fades its bottom edge while there is more to scroll. */
@keyframes appshell-sidebar-fade {
from {
mask-image: linear-gradient(to top, #0000 0, #000 2rem, #000 100%);
- Keep the scrollbar clear of the resize handle's hit area
- Use the full --muted-foreground thumb colour to meet 3:1 contrast
- Animate the bottom fade smoothly by sliding a fixed gradient mask

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
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