From 7a014e5ec5354442ace79b4c58830c81f0357386 Mon Sep 17 00:00:00 2001
From: "Noah (Nguyen Pham)" <ptknguyen04@gmail.com>
Date: Tue, 27 Oct 2026 17:32:11 +0000
Subject: [PATCH 1/2] fix(layer-dialog): hide empty native scrollbar tracks

Base UI's ScrollArea viewport sets `overflow: scroll` and hides the
native scrollbars only with a <style> that React hoists into <head>
once per document. Astro's ClientRouter removes that style on every
soft navigation and React never re-inserts it, so the docs site showed
empty scrollbar tracks along the LayerDialog body wherever scrollbars
are always visible.

- Give the LayerDialog body and Sidebar content viewports Kumo's own
  `no-scrollbar` rule so they no longer depend on the injected style.
- Keep React-hoisted styles across ClientRouter swaps on the docs site.
---
 .changeset/layer-dialog-native-scrollbar.md        |  5 +++++
 .../kumo-docs-astro/src/layouts/BaseLayout.astro   | 14 ++++++++++++++
 .../components/layer-dialog/layer-dialog.test.tsx  | 14 ++++++++++++++
 .../src/components/layer-dialog/layer-dialog.tsx   |  9 +++++++--
 .../kumo/src/components/sidebar/sidebar.test.tsx   | 13 +++++++++++++
 packages/kumo/src/components/sidebar/sidebar.tsx   |  4 ++++
 6 files changed, 57 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/layer-dialog-native-scrollbar.md

diff --git a/.changeset/layer-dialog-native-scrollbar.md b/.changeset/layer-dialog-native-scrollbar.md
new file mode 100644
index 0000000000..9f7e38ae35
--- /dev/null
+++ b/.changeset/layer-dialog-native-scrollbar.md
@@ -0,0 +1,5 @@
+---
+"@cloudflare/kumo": patch
+---
+
+Hide the native scrollbars of the LayerDialog body and Sidebar content with Kumo's own CSS. Base UI only hides them with a style element it injects into the document head, so client routers that swap the head (such as Astro's ClientRouter) or a Content Security Policy that blocks inline styles could leave empty scrollbar tracks along the dialog body.
diff --git a/packages/kumo-docs-astro/src/layouts/BaseLayout.astro b/packages/kumo-docs-astro/src/layouts/BaseLayout.astro
index 9e67246475..5ec5926dd5 100644
--- a/packages/kumo-docs-astro/src/layouts/BaseLayout.astro
+++ b/packages/kumo-docs-astro/src/layouts/BaseLayout.astro
@@ -155,6 +155,20 @@ const buildDate =
   <body>
     <slot />
     <script>
+      import type { TransitionBeforeSwapEvent } from "astro:transitions/client";
+
+      // React hoists `<style precedence>` elements (such as Base UI's
+      // scrollbar-hiding style) into <head> once per document and never
+      // re-inserts them, but the ClientRouter swap removes every <head> style
+      // the incoming page lacks. Copying them into the incoming <head> makes
+      // Astro keep the originals in place and discard the copies.
+      document.addEventListener("astro:before-swap", (event) => {
+        const { newDocument } = event as TransitionBeforeSwapEvent;
+        document.head
+          .querySelectorAll("style[data-precedence]")
+          .forEach((style) => newDocument.head.append(style.cloneNode(true)));
+      });
+
       // Wraps code blocks and injects a copy button. Safe to run on every page
       // load — the `.code-block` parent check prevents double-wrapping.
       function wrapCodeBlocks() {
diff --git a/packages/kumo/src/components/layer-dialog/layer-dialog.test.tsx b/packages/kumo/src/components/layer-dialog/layer-dialog.test.tsx
index 9802726dba..fdf0b457f1 100644
--- a/packages/kumo/src/components/layer-dialog/layer-dialog.test.tsx
+++ b/packages/kumo/src/components/layer-dialog/layer-dialog.test.tsx
@@ -517,6 +517,20 @@ describe("LayerDialog.Body edge clipping", () => {
 
     cleanup();
   });
+
+  it("hides native scrollbars without Base UI's injected style", () => {
+    // Base UI forces `overflow: scroll` on the viewport and hides the native
+    // scrollbars only through a <style> it adds to <head> once per document.
+    // Head-swapping client routers (Astro's ClientRouter) remove that style,
+    // which shows empty scrollbar tracks wherever scrollbars are always
+    // visible, so the viewport must carry Kumo's own rule.
+    const { viewport, cleanup } = renderBodyWithLeadingInput(true);
+
+    expect(viewport.style.overflow).toBe("scroll");
+    expect(viewport.className).toMatch(/(^|\s)no-scrollbar(\s|$)/);
+
+    cleanup();
+  });
 });
 
 describe("LayerDialog dismissal", () => {
diff --git a/packages/kumo/src/components/layer-dialog/layer-dialog.tsx b/packages/kumo/src/components/layer-dialog/layer-dialog.tsx
index 455e1ad9b1..73c5f119e2 100644
--- a/packages/kumo/src/components/layer-dialog/layer-dialog.tsx
+++ b/packages/kumo/src/components/layer-dialog/layer-dialog.tsx
@@ -454,9 +454,14 @@ function LayerDialogBody({ children }: LayerDialogBodyProps) {
       <ScrollAreaBase.Root className="relative flex min-h-0 flex-1 flex-col">
         {/* The top fade falls back to 0px: the body always opens scrolled to
             the top, and Safari skips Base UI's registered 0px initial value,
-            so a non-zero fallback fades out the first row until measured. */}
+            so a non-zero fallback fades out the first row until measured.
+
+            no-scrollbar keeps the native scrollbars of Base UI's
+            `overflow: scroll` viewport hidden. Base UI hides them only with a
+            <style> it adds to <head> once per document, which head-swapping
+            client routers and strict CSPs can drop. */}
         <ScrollAreaBase.Viewport
-          className="min-h-0 flex-1 overscroll-none [mask-image:linear-gradient(to_bottom,transparent_0,black_min(24px,var(--scroll-area-overflow-y-start,0px)),black_calc(100%-min(24px,var(--scroll-area-overflow-y-end,24px))),transparent_100%)]"
+          className="no-scrollbar min-h-0 flex-1 overscroll-none [mask-image:linear-gradient(to_bottom,transparent_0,black_min(24px,var(--scroll-area-overflow-y-start,0px)),black_calc(100%-min(24px,var(--scroll-area-overflow-y-end,24px))),transparent_100%)]"
           onScroll={handleScroll}
         >
           {/* pt-0.5 keeps a first-child control's ring-drawn border and
diff --git a/packages/kumo/src/components/sidebar/sidebar.test.tsx b/packages/kumo/src/components/sidebar/sidebar.test.tsx
index 1f0d36348e..61a3c878c3 100644
--- a/packages/kumo/src/components/sidebar/sidebar.test.tsx
+++ b/packages/kumo/src/components/sidebar/sidebar.test.tsx
@@ -1164,6 +1164,19 @@ describe("Sidebar contained mode", () => {
   });
 });
 
+describe("Sidebar.Content scrollbar", () => {
+  it("should hide the native scrollbar without Base UI's injected style", () => {
+    render(
+      <TestSidebar defaultOpen>
+        <SidebarContent>Content</SidebarContent>
+      </TestSidebar>,
+    );
+    // Base UI's own rule lives in a <style> that head-swapping client
+    // routers can remove, so the viewport must carry Kumo's.
+    expect(getViewport().className).toMatch(/(^|\s)no-scrollbar(\s|$)/);
+  });
+});
+
 // ============================================================================
 // Mobile behavior
 // ============================================================================
diff --git a/packages/kumo/src/components/sidebar/sidebar.tsx b/packages/kumo/src/components/sidebar/sidebar.tsx
index 4d56eaa9a6..93e301877b 100644
--- a/packages/kumo/src/components/sidebar/sidebar.tsx
+++ b/packages/kumo/src/components/sidebar/sidebar.tsx
@@ -1063,6 +1063,10 @@ const SidebarContent = forwardRef<
           "h-full px-[11px] py-3 group-not-data-[state=collapsed]/sidebar:px-3.5",
           "transition-[padding] duration-(--sidebar-animation-duration)",
           "overflow-x-hidden!",
+          // Hide the native scrollbar with Kumo's CSS rather than relying on
+          // the <style> Base UI adds to <head>, which head-swapping client
+          // routers and strict CSPs can drop.
+          "no-scrollbar",
           // Scroll fade via CSS mask driven by Base UI overflow CSS variables
           "[mask-image:linear-gradient(to_bottom,transparent_0,black_min(24px,var(--scroll-area-overflow-y-start,24px)),black_calc(100%-min(24px,var(--scroll-area-overflow-y-end,24px))),transparent_100%)]",
         )}

From 98afe057f493eed5030514d6a6edd63009f140d1 Mon Sep 17 00:00:00 2001
From: "Noah (Nguyen Pham)" <ptknguyen04@gmail.com>
Date: Tue, 27 Oct 2026 23:14:18 +0000
Subject: [PATCH 2/2] docs: drop the ClientRouter hoisted-style workaround

With LayerDialog and Sidebar hiding native scrollbars through Kumo's own
CSS, nothing on the docs site needs Base UI's injected style anymore.
The workaround leaned on undocumented Astro head-swap behavior, and
leaving the site as-is keeps it exposing the problem if another
component starts depending on that style.
---
 .../kumo-docs-astro/src/layouts/BaseLayout.astro   | 14 --------------
 1 file changed, 14 deletions(-)

diff --git a/packages/kumo-docs-astro/src/layouts/BaseLayout.astro b/packages/kumo-docs-astro/src/layouts/BaseLayout.astro
index 5ec5926dd5..9e67246475 100644
--- a/packages/kumo-docs-astro/src/layouts/BaseLayout.astro
+++ b/packages/kumo-docs-astro/src/layouts/BaseLayout.astro
@@ -155,20 +155,6 @@ const buildDate =
   <body>
     <slot />
     <script>
-      import type { TransitionBeforeSwapEvent } from "astro:transitions/client";
-
-      // React hoists `<style precedence>` elements (such as Base UI's
-      // scrollbar-hiding style) into <head> once per document and never
-      // re-inserts them, but the ClientRouter swap removes every <head> style
-      // the incoming page lacks. Copying them into the incoming <head> makes
-      // Astro keep the originals in place and discard the copies.
-      document.addEventListener("astro:before-swap", (event) => {
-        const { newDocument } = event as TransitionBeforeSwapEvent;
-        document.head
-          .querySelectorAll("style[data-precedence]")
-          .forEach((style) => newDocument.head.append(style.cloneNode(true)));
-      });
-
       // Wraps code blocks and injects a copy button. Safe to run on every page
       // load — the `.code-block` parent check prevents double-wrapping.
       function wrapCodeBlocks() {