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