diff --git a/.changeset/quiet-sidebar-scroll.md b/.changeset/quiet-sidebar-scroll.md new file mode 100644 index 000000000..d609e6b24 --- /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, 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/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..6249575f6 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,25 @@ 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. + // 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 new file mode 100644 index 000000000..b420de9d1 --- /dev/null +++ b/packages/core/src/components/sidebar/scroll-area.ts @@ -0,0 +1,43 @@ +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: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(" "); + +/** + * 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..edb3fcefe 100644 --- a/packages/core/src/globals.css +++ b/packages/core/src/globals.css @@ -82,6 +82,21 @@ } } +/* + * 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-position: 0 100%; + } + to { + mask-position: 0 0; + } +} + @layer utilities { /* * Sidebar active item — hairline border (~0.5px @ 30% black). Wrapper components in