From e35e3a5d72b88ebda24fc7210625e68979b3e4d8 Mon Sep 17 00:00:00 2001 From: itsprade Date: Wed, 18 Nov 2026 11:59:57 +0530 Subject: [PATCH 1/2] feat(sidebar): quieter scrollbars and a bottom fade in the sidebar 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 --- .changeset/quiet-sidebar-scroll.md | 11 ++++ .../sidebar/default-sidebar.test.tsx | 31 +++++++++++ .../src/components/sidebar/primitives.tsx | 13 ++++- .../src/components/sidebar/scroll-area.ts | 42 +++++++++++++++ .../src/components/sidebar/sidebar-group.tsx | 54 ++++++++++++------- .../src/components/sidebar/sidebar.test.tsx | 38 ++++++++++++- packages/core/src/globals.css | 10 ++++ 7 files changed, 177 insertions(+), 22 deletions(-) create mode 100644 .changeset/quiet-sidebar-scroll.md create mode 100644 packages/core/src/components/sidebar/scroll-area.ts diff --git a/.changeset/quiet-sidebar-scroll.md b/.changeset/quiet-sidebar-scroll.md new file mode 100644 index 000000000..bb0f80079 --- /dev/null +++ b/.changeset/quiet-sidebar-scroll.md @@ -0,0 +1,11 @@ +--- +"@tailor-platform/app-shell": patch +--- + +The sidebar's item list and the icon rail's group flyout scroll more quietly. + +- The scrollbar is thin with no track, and shows only while the list is scrolling. +- In the default inset sidebar, it sits on the sidebar's edge instead of 8px inside it. +- While there is more to scroll, the bottom of the list fades out, like the top of the page content does. + +The global scrollbar style and every other scroll area are unchanged. diff --git a/packages/core/src/components/sidebar/default-sidebar.test.tsx b/packages/core/src/components/sidebar/default-sidebar.test.tsx index d1a6ec34f..f609c3567 100644 --- a/packages/core/src/components/sidebar/default-sidebar.test.tsx +++ b/packages/core/src/components/sidebar/default-sidebar.test.tsx @@ -424,6 +424,37 @@ describe("DefaultSidebar opt-in props", () => { expect(within(flyout).getByRole("link", { name: /products/i })).toBeDefined(); }); + it("scrolls the flyout's list inside the popup, showing its scrollbar while scrolling", async () => { + const user = userEvent.setup(); + renderWithProps( + { + iconRail: true, + hideHeader: true, + children: ( + }> + + + ), + }, + { defaultOpen: false }, + ); + await user.hover(screen.getByRole("button", { name: "Main" })); + + const flyout = openFlyout("Main"); + assert(flyout); + // The list scrolls, not the popup, so the list's bottom fade (a mask) + // leaves the popup's border and shadow alone. + expect(flyout.className).toContain("astw:overflow-hidden"); + const list = flyout.querySelector('[data-slot="sidebar-group-flyout-content"]'); + assert(list); + expect(list.className).toContain("astw:overflow-y-auto"); + expect(within(list).getByRole("link", { name: /dashboard/i })).toBeDefined(); + + expect(list.dataset.scrolling).toBeUndefined(); + fireEvent.scroll(list); + expect(list.dataset.scrolling).toBe("true"); + }); + /** Renders a collapsed icon rail on a touch device (no hover) at `width`. */ const renderTouchRail = (width: number, to?: string) => { // A touch screen cannot hover, so the rail's flyout must open on tap. diff --git a/packages/core/src/components/sidebar/primitives.tsx b/packages/core/src/components/sidebar/primitives.tsx index 4701a896b..dd614bb5d 100644 --- a/packages/core/src/components/sidebar/primitives.tsx +++ b/packages/core/src/components/sidebar/primitives.tsx @@ -6,6 +6,7 @@ import { useRender } from "@base-ui/react/use-render"; import { useIsMobile } from "@/hooks/use-mobile"; import { useIsTablet } from "@/hooks/use-tablet"; import { DEFAULT_SIDEBAR_WIDTH, MIN_WIDTH, SidebarResizeHandle } from "./sidebar-resize-handle"; +import { SIDEBAR_SCROLL_AREA_CLASS, useScrolling } from "./scroll-area"; import { cn } from "@/lib/utils"; import { Button } from "@/components/button"; import { Input } from "@/components/input"; @@ -634,13 +635,23 @@ function SidebarSeparator({ className, ...props }: React.ComponentProps) { +function SidebarContent({ className, onScroll, ...props }: React.ComponentProps<"div">) { + const scroll = useScrolling(); return (
{ + scroll.onScroll(); + onScroll?.(event); + }} className={cn( "astw:flex astw:min-h-0 astw:flex-1 astw:flex-col astw:gap-2 astw:overflow-auto astw:group-data-[collapsible=icon]:overflow-hidden", + 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", className, )} {...props} diff --git a/packages/core/src/components/sidebar/scroll-area.ts b/packages/core/src/components/sidebar/scroll-area.ts new file mode 100644 index 000000000..688d792a3 --- /dev/null +++ b/packages/core/src/components/sidebar/scroll-area.ts @@ -0,0 +1,42 @@ +import * as React from "react"; + +/** How long a sidebar scroll area's scrollbar stays visible after the last scroll. */ +const SCROLLBAR_HIDE_DELAY = 800; + +/** + * Classes for a scroll area in the sidebar (the item list and the icon rail's + * flyout). Pair them with `useScrolling`, setting `data-scrolling` from it. + * + * - A thin scrollbar with no track, visible only while `data-scrolling` is set, + * like an overlay scrollbar, so it doesn't draw a stripe down the list at rest. + * - A bottom fade while there is more to scroll, mirroring the content area's + * top fade: it clears over the last 2rem of scroll, and a list that fits has + * no scroll range, so no fade. Keyframes live in globals.css. + * - Scroll padding as tall as the fade, so an item scrolled into view by + * keyboard focus stops clear of it. + */ +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]", + "astw:[animation:appshell-sidebar-fade_auto_linear_both] astw:[animation-timeline:scroll(self_block)] astw:[animation-range:calc(100%_-_2rem)_100%]", + "astw:scroll-pb-8", +].join(" "); + +/** + * Whether the element is scrolling: true from a scroll event until + * `SCROLLBAR_HIDE_DELAY` after the last one. Spread `onScroll` on the scroll + * area and set `data-scrolling={scrolling || undefined}`. + */ +export function useScrolling() { + const [scrolling, setScrolling] = React.useState(false); + const hideTimer = React.useRef>(undefined); + React.useEffect(() => () => clearTimeout(hideTimer.current), []); + + const onScroll = React.useCallback(() => { + setScrolling(true); + clearTimeout(hideTimer.current); + hideTimer.current = setTimeout(() => setScrolling(false), SCROLLBAR_HIDE_DELAY); + }, []); + + return { scrolling, onScroll }; +} diff --git a/packages/core/src/components/sidebar/sidebar-group.tsx b/packages/core/src/components/sidebar/sidebar-group.tsx index c2627713c..62675a5df 100644 --- a/packages/core/src/components/sidebar/sidebar-group.tsx +++ b/packages/core/src/components/sidebar/sidebar-group.tsx @@ -11,6 +11,7 @@ import { SidebarMenuSub, } from "./primitives"; import { SidebarButtonIcon } from "./sidebar-button-icon"; +import { SIDEBAR_SCROLL_AREA_CLASS, useScrolling } from "./scroll-area"; import { useHasHover } from "@/hooks/use-has-hover"; import { cn } from "@/lib/utils"; import { useT } from "@/i18n-labels"; @@ -71,8 +72,10 @@ function useIsIconRail(): boolean { * an `expanded` sidebar context so the child items show labels and drop their * own icon-rail tooltips. */ +// The popup only frames the flyout; the list inside scrolls, so its bottom +// fade (a mask) doesn't also erase the popup's border and shadow. const FLYOUT_POPUP_CLASS = - "astw:z-(--z-portal) astw:max-h-[calc(100dvh-1rem)] astw:min-w-48 astw:overflow-y-auto astw:rounded-md astw:border astw:border-border astw:bg-popover astw:p-1 astw:text-popover-foreground astw:shadow-md astw:outline-none"; + "astw:z-(--z-portal) astw:flex astw:max-h-[calc(100dvh-1rem)] astw:min-w-48 astw:flex-col astw:overflow-hidden astw:rounded-md astw:border astw:border-border astw:bg-popover astw:text-popover-foreground astw:shadow-md astw:outline-none"; const FLYOUT_HEADING_CLASS = "astw:block astw:px-2 astw:py-1.5 astw:text-label-sm astw:text-muted-foreground"; @@ -94,6 +97,7 @@ const IconRailFlyout = ({ const [open, setOpen] = useState(false); const itemRef = useRef(null); const popupRef = useRef(null); + const scroll = useScrolling(); // On a hover device the group's own page is the trigger's link. const linkTrigger = hasHover && to !== undefined; @@ -178,28 +182,38 @@ const IconRailFlyout = ({ data-slot="sidebar-group-flyout" className={FLYOUT_POPUP_CLASS} > - {/* A group with its own page links to it from the heading, so the +
+ {/* A group with its own page links to it from the heading, so the page is reachable from the flyout on every device. */} - {to ? ( - - {title} - - ) : ( -
{title}
- )} - {/* Inside the flyout the items are no longer in the icon rail: they + {to ? ( + + {title} + + ) : ( +
{title}
+ )} + {/* Inside the flyout the items are no longer in the icon rail: they show their labels (the popover escapes the rail's icon-collapse styling) and drop their own redundant icon-rail tooltips. */} - -
    {children}
-
+ +
    {children}
+
+
diff --git a/packages/core/src/components/sidebar/sidebar.test.tsx b/packages/core/src/components/sidebar/sidebar.test.tsx index 576591c16..36223f824 100644 --- a/packages/core/src/components/sidebar/sidebar.test.tsx +++ b/packages/core/src/components/sidebar/sidebar.test.tsx @@ -1,4 +1,4 @@ -import { render, screen, within, cleanup } from "@testing-library/react"; +import { act, fireEvent, render, screen, within, cleanup } from "@testing-library/react"; import userEvent from "@testing-library/user-event"; import { describe, it, expect, afterEach, vi } from "vitest"; import { MemoryRouter } from "react-router"; @@ -465,6 +465,42 @@ describe("SidebarSeparator", () => { }); }); +describe("SidebarContent scrolling", () => { + afterEach(() => { + vi.useRealTimers(); + cleanup(); + }); + + it("shows its scrollbar only while scrolling", () => { + vi.useFakeTimers(); + const onScroll = vi.fn(); + render(); + const list = screen.getByTestId("list"); + expect(list.dataset.scrolling).toBeUndefined(); + + fireEvent.scroll(list); + expect(list.dataset.scrolling).toBe("true"); + // The consumer's own handler still runs. + expect(onScroll).toHaveBeenCalledTimes(1); + + // Each scroll restarts the countdown. + act(() => vi.advanceTimersByTime(600)); + fireEvent.scroll(list); + act(() => vi.advanceTimersByTime(600)); + expect(list.dataset.scrolling).toBe("true"); + + act(() => vi.advanceTimersByTime(200)); + expect(list.dataset.scrolling).toBeUndefined(); + }); + + it("reaches into the inset sidebar's padding so the scrollbar sits on its edge", () => { + render(); + const { className } = screen.getByTestId("list"); + expect(className).toContain("astw:group-data-[variant=inset]:-mr-2"); + expect(className).toContain("astw:group-data-[variant=inset]:pr-2"); + }); +}); + describe("Mobile sidebar", () => { afterEach(() => { vi.restoreAllMocks(); diff --git a/packages/core/src/globals.css b/packages/core/src/globals.css index 4ba86acd3..c2766484e 100644 --- a/packages/core/src/globals.css +++ b/packages/core/src/globals.css @@ -82,6 +82,16 @@ } } +/* 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%); + } + to { + mask-image: linear-gradient(to top, #000 0, #000 2rem, #000 100%); + } +} + @layer utilities { /* * Sidebar active item — hairline border (~0.5px @ 30% black). Wrapper components in From c2deb86635694747c0249e08de084c9006cf4fec Mon Sep 17 00:00:00 2001 From: itsprade Date: Wed, 18 Nov 2026 13:26:58 +0530 Subject: [PATCH 2/2] fix(sidebar): address review feedback on scrollbar and fade - 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 --- .changeset/quiet-sidebar-scroll.md | 2 +- packages/core/src/components/sidebar/primitives.tsx | 4 +++- packages/core/src/components/sidebar/scroll-area.ts | 3 ++- packages/core/src/globals.css | 11 ++++++++--- 4 files changed, 14 insertions(+), 6 deletions(-) diff --git a/.changeset/quiet-sidebar-scroll.md b/.changeset/quiet-sidebar-scroll.md index bb0f80079..d609e6b24 100644 --- a/.changeset/quiet-sidebar-scroll.md +++ b/.changeset/quiet-sidebar-scroll.md @@ -5,7 +5,7 @@ The sidebar's item list and the icon rail's group flyout scroll more quietly. - The scrollbar is thin with no track, and shows only while the list is scrolling. -- In the default inset sidebar, it sits on the sidebar's edge instead of 8px inside it. +- In the default inset sidebar, it sits on the sidebar's edge instead of 8px inside it, unless the sidebar is resizable, where it keeps clear of the resize handle. - While there is more to scroll, the bottom of the list fades out, like the top of the page content does. The global scrollbar style and every other scroll area are unchanged. diff --git a/packages/core/src/components/sidebar/primitives.tsx b/packages/core/src/components/sidebar/primitives.tsx index dd614bb5d..6249575f6 100644 --- a/packages/core/src/components/sidebar/primitives.tsx +++ b/packages/core/src/components/sidebar/primitives.tsx @@ -651,7 +651,9 @@ function SidebarContent({ className, onScroll, ...props }: React.ComponentProps< 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", + // Skipped when a resize handle is present: its hit area overlaps the last + // 6px of the panel and would sit on top of the scrollbar thumb. + "astw:group-data-[variant=inset]:not-group-has-[[data-slot=sidebar-resize-handle]]:-mr-2 astw:group-data-[variant=inset]:not-group-has-[[data-slot=sidebar-resize-handle]]:pr-2", className, )} {...props} diff --git a/packages/core/src/components/sidebar/scroll-area.ts b/packages/core/src/components/sidebar/scroll-area.ts index 688d792a3..b420de9d1 100644 --- a/packages/core/src/components/sidebar/scroll-area.ts +++ b/packages/core/src/components/sidebar/scroll-area.ts @@ -17,7 +17,8 @@ const SCROLLBAR_HIDE_DELAY = 800; */ 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]", + "astw:data-scrolling:[scrollbar-color:var(--muted-foreground)_transparent]", + "astw:[mask-image:linear-gradient(to_top,transparent_0,#000_2rem,#000_100%)] astw:[mask-size:100%_calc(100%_+_2rem)] astw:[mask-repeat:no-repeat]", "astw:[animation:appshell-sidebar-fade_auto_linear_both] astw:[animation-timeline:scroll(self_block)] astw:[animation-range:calc(100%_-_2rem)_100%]", "astw:scroll-pb-8", ].join(" "); diff --git a/packages/core/src/globals.css b/packages/core/src/globals.css index c2766484e..edb3fcefe 100644 --- a/packages/core/src/globals.css +++ b/packages/core/src/globals.css @@ -82,13 +82,18 @@ } } -/* Sidebar list: fades its bottom edge while there is more to scroll. */ +/* + * Sidebar list: fades its bottom edge while there is more to scroll. `mask-image` + * itself animates discretely, so the mask is one fixed gradient, 2rem taller than + * the list, and the keyframes slide it with `mask-position`, which interpolates: + * at `from` the gradient's fade sits on the bottom edge, at `to` its opaque end does. + */ @keyframes appshell-sidebar-fade { from { - mask-image: linear-gradient(to top, #0000 0, #000 2rem, #000 100%); + mask-position: 0 100%; } to { - mask-image: linear-gradient(to top, #000 0, #000 2rem, #000 100%); + mask-position: 0 0; } }