Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .changeset/quiet-sidebar-scroll.md
Original file line number Diff line number Diff line change
@@ -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.
31 changes: 31 additions & 0 deletions packages/core/src/components/sidebar/default-sidebar.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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: (
<SidebarGroup title="Main" icon={<Home />}>
<SidebarItem to="/dashboard" />
</SidebarGroup>
),
},
{ 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<HTMLElement>('[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.
Expand Down
15 changes: 14 additions & 1 deletion packages/core/src/components/sidebar/primitives.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -634,13 +635,25 @@ function SidebarSeparator({ className, ...props }: React.ComponentProps<typeof S
);
}

function SidebarContent({ className, ...props }: React.ComponentProps<"div">) {
function SidebarContent({ className, onScroll, ...props }: React.ComponentProps<"div">) {
const scroll = useScrolling();
return (
<div
data-slot="sidebar-content"
data-sidebar="content"
data-scrolling={scroll.scrolling || undefined}
onScroll={(event) => {
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}
Expand Down
43 changes: 43 additions & 0 deletions packages/core/src/components/sidebar/scroll-area.ts
Original file line number Diff line number Diff line change
@@ -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<ReturnType<typeof setTimeout>>(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 };
}
54 changes: 34 additions & 20 deletions packages/core/src/components/sidebar/sidebar-group.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -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";

Expand All @@ -94,6 +97,7 @@ const IconRailFlyout = ({
const [open, setOpen] = useState(false);
const itemRef = useRef<HTMLLIElement>(null);
const popupRef = useRef<HTMLDivElement>(null);
const scroll = useScrolling();
// On a hover device the group's own page is the trigger's link.
const linkTrigger = hasHover && to !== undefined;

Expand Down Expand Up @@ -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
<div
data-slot="sidebar-group-flyout-content"
data-scrolling={scroll.scrolling || undefined}
onScroll={scroll.onScroll}
className={cn(
"astw:min-h-0 astw:overflow-y-auto astw:p-1",
SIDEBAR_SCROLL_AREA_CLASS,
)}
>
{/* A group with its own page links to it from the heading, so the
page is reachable from the flyout on every device. */}
{to ? (
<Link
to={to}
aria-current={isActive ? "page" : undefined}
className={cn(
FLYOUT_HEADING_CLASS,
"astw:rounded-sm astw:hover:text-foreground astw:focus-visible:outline-2 astw:focus-visible:outline-ring",
)}
>
{title}
</Link>
) : (
<div className={FLYOUT_HEADING_CLASS}>{title}</div>
)}
{/* Inside the flyout the items are no longer in the icon rail: they
{to ? (
<Link
to={to}
aria-current={isActive ? "page" : undefined}
className={cn(
FLYOUT_HEADING_CLASS,
"astw:rounded-sm astw:hover:text-foreground astw:focus-visible:outline-2 astw:focus-visible:outline-ring",
)}
>
{title}
</Link>
) : (
<div className={FLYOUT_HEADING_CLASS}>{title}</div>
)}
{/* 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. */}
<SidebarRailContext.Provider value={false}>
<ul className="astw:flex astw:min-w-0 astw:flex-col astw:gap-0.5">{children}</ul>
</SidebarRailContext.Provider>
<SidebarRailContext.Provider value={false}>
<ul className="astw:flex astw:min-w-0 astw:flex-col astw:gap-0.5">{children}</ul>
</SidebarRailContext.Provider>
</div>
</Popover.Popup>
</Popover.Positioner>
</Popover.Portal>
Expand Down
38 changes: 37 additions & 1 deletion packages/core/src/components/sidebar/sidebar.test.tsx
Original file line number Diff line number Diff line change
@@ -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";
Expand Down Expand Up @@ -465,6 +465,42 @@
});
});

describe("SidebarContent scrolling", () => {
afterEach(() => {
vi.useRealTimers();
cleanup();
});

it("shows its scrollbar only while scrolling", () => {
vi.useFakeTimers();
const onScroll = vi.fn();
render(<SidebarContent data-testid="list" onScroll={onScroll} />);
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(<SidebarContent data-testid="list" />);
const { className } = screen.getByTestId("list");
expect(className).toContain("astw:group-data-[variant=inset]:-mr-2");

Check failure on line 499 in packages/core/src/components/sidebar/sidebar.test.tsx

View workflow job for this annotation

GitHub Actions / ci

src/components/sidebar/sidebar.test.tsx > SidebarContent scrolling > reaches into the inset sidebar's padding so the scrollbar sits on its edge

AssertionError: expected 'astw:flex astw:min-h-0 astw:flex-1 as…' to contain 'astw:group-data-[variant=inset]:-mr-2' Expected: "astw:group-data-[variant=inset]:-mr-2" Received: "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 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 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" ❯ src/components/sidebar/sidebar.test.tsx:499:23
expect(className).toContain("astw:group-data-[variant=inset]:pr-2");
});
});

describe("Mobile sidebar", () => {
afterEach(() => {
vi.restoreAllMocks();
Expand Down
15 changes: 15 additions & 0 deletions packages/core/src/globals.css
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading