feat(tabs): scroll fade for overflowing segmented tabs (#504)

Author: mattrothenberg

.changeset/tabs-scroll-fade.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/kumo": minor
+---
+
+Add scroll fade to segmented tabs. When tabs overflow, gradient masks appear on the edges based on scroll position via scroll-driven animations (Chrome 115+, degrades gracefully). Scrollbar is hidden; the fade is the scroll affordance.

packages/kumo-docs-astro/src/components/demos/TabsDemo.tsx

@@ -83,17 +83,21 @@ export function TabsControlledDemo() {
 
 export function TabsManyDemo() {
   return (
-    <Tabs
-      tabs={[
-        { value: "overview", label: "Overview" },
-        { value: "analytics", label: "Analytics" },
-        { value: "reports", label: "Reports" },
-        { value: "notifications", label: "Notifications" },
-        { value: "settings", label: "Settings" },
-        { value: "billing", label: "Billing" },
-      ]}
-      selectedValue="overview"
-    />
+    <div className="w-full max-w-md">
+      <Tabs
+        tabs={[
+          { value: "overview", label: "Overview" },
+          { value: "analytics", label: "Analytics" },
+          { value: "reports", label: "Reports" },
+          { value: "notifications", label: "Notifications" },
+          { value: "settings", label: "Settings" },
+          { value: "billing", label: "Billing" },
+          { value: "security", label: "Security" },
+          { value: "integrations", label: "Integrations" },
+        ]}
+        selectedValue="overview"
+      />
+    </div>
   );
 }
 

packages/kumo/package.json

@@ -451,10 +451,10 @@
   },
   "peerDependencies": {
     "@phosphor-icons/react": "^2.1.10",
+    "echarts": "^6.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "zod": "^4.0.0",
-    "echarts": "^6.0.0"
+    "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {
     "zod": {
@@ -465,6 +465,7 @@
     "@base-ui/react": "^1.4.0",
     "@shikijs/langs": "^4.0.0",
     "@shikijs/themes": "^4.0.0",
+    "@use-gesture/react": "^10.3.1",
     "clsx": "^2.1.1",
     "motion": "^12.34.1",
     "react-day-picker": "^9.13.2",

packages/kumo/src/components/tabs/tabs.tsx

@@ -1,6 +1,7 @@
-import type { ReactNode } from "react";
+import { useEffect, useRef, useState, type ReactNode } from "react";
 import type { TabsTab } from "@base-ui/react/tabs";
 import { Tabs as TabsPrimitive } from "@base-ui/react/tabs";
+import { useDrag } from "@use-gesture/react";
 import { cn } from "../../utils/cn";
 
 /** Tabs variant definitions. */
@@ -150,6 +151,8 @@ export function Tabs({
   const isSegmented = variant === "segmented";
   const isUnderline = variant === "underline";
   const isSm = size === "sm";
+  const { ref: listRef, isOverflowing } = useOverflowDetect(isSegmented);
+  const bindDrag = useHorizontalDragScroll(listRef, isOverflowing);
 
   return (
     <TabsPrimitive.Root
@@ -165,10 +168,13 @@ export function Tabs({
         <div className={cn("absolute inset-x-0 top-1/2 z-0 -translate-y-1/2 rounded-lg bg-kumo-recessed", isSm ? "h-6.5" : "h-9")} />
       )}
       <TabsPrimitive.List
+        ref={listRef}
         activateOnFocus={activateOnFocus}
+        data-overflowing={isOverflowing ? "" : undefined}
+        {...bindDrag()}
         className={cn(
-          "scrollbar-hide relative flex min-w-0 shrink items-stretch",
-          isSegmented && "rounded-lg bg-kumo-recessed px-0.5 ring ring-kumo-hairline/70",
+          "relative flex min-w-0 shrink items-stretch",
+          isSegmented && "kumo-tabs-list overflow-x-auto rounded-lg bg-kumo-recessed px-0.5 touch-pan-y ring ring-kumo-hairline/70 [--scroll-fade-width:3rem]",
           isSegmented && (isSm ? "h-6.5 rounded-md" : "h-9"),
           isUnderline && "gap-4 border-b border-kumo-hairline pb-2",
           isUnderline && (isSm ? "h-6.5" : "h-7.5"),
@@ -215,3 +221,60 @@ export function Tabs({
     </TabsPrimitive.Root>
   );
 }
+
+// ─── Horizontal drag-to-scroll ────────────────────────────────────────
+
+/**
+ * Enables pointer/touch drag to horizontally scroll the tab list.
+ * Only active when the list is overflowing. Prevents vertical scroll
+ * interference and uses `touch-action: pan-y` so native vertical
+ * scrolling is preserved.
+ */
+function useHorizontalDragScroll(
+  ref: React.RefObject<HTMLElement | null>,
+  enabled: boolean,
+) {
+  return useDrag(
+    ({ delta: [dx], event }) => {
+      const el = ref.current;
+      if (!el || !enabled) return;
+      // Prevent text selection while dragging
+      event?.preventDefault();
+      el.scrollLeft -= dx;
+    },
+    {
+      axis: "x",
+      pointer: { touch: true },
+      filterTaps: true,
+      from: [0, 0],
+    },
+  );
+}
+
+// ─── Overflow detection ───────────────────────────────────────────────
+
+/**
+ * Detects whether the element's content overflows horizontally.
+ * Returns a ref to attach and a boolean for conditional rendering.
+ * The `data-overflowing` attribute drives the scroll-fade CSS.
+ */
+function useOverflowDetect(enabled: boolean) {
+  const ref = useRef<HTMLDivElement>(null);
+  const [isOverflowing, setIsOverflowing] = useState(false);
+
+  useEffect(() => {
+    if (!enabled) return;
+    const el = ref.current;
+    if (!el) return;
+
+    const check = () => setIsOverflowing(el.scrollWidth > el.clientWidth);
+
+    const ro = new ResizeObserver(check);
+    ro.observe(el);
+    check();
+
+    return () => ro.disconnect();
+  }, [enabled]);
+
+  return { ref, isOverflowing };
+}

packages/kumo/src/styles/kumo-binding.css

@@ -214,6 +214,71 @@
   }
 }
 
+/* Scroll-fade: gradient masks that appear on the edges of a horizontally
+   scrollable container based on scroll position. Uses scroll-driven
+   animations (Chrome 115+, Edge 115+). Degrades gracefully to no fade.
+   Activated by the `data-overflowing` attribute (set via JS ResizeObserver). */
+@keyframes scroll-fade-x-left {
+  to {
+    mask-size:
+      var(--scroll-fade-width, 3rem) 100%,
+      100% 100%,
+      var(--scroll-fade-width, 3rem) 100%;
+  }
+}
+
+@keyframes scroll-fade-x-right {
+  to {
+    mask-size:
+      var(--scroll-fade-width, 3rem) 100%,
+      100% 100%,
+      0 100%;
+  }
+}
+
+[data-overflowing] {
+  @supports (animation-timeline: scroll()) {
+    mask-image:
+      linear-gradient(to right, white, transparent),
+      linear-gradient(white, white),
+      linear-gradient(to right, transparent, white);
+    mask-size:
+      0 100%,
+      100% 100%,
+      var(--scroll-fade-width, 3rem) 100%;
+    mask-repeat: no-repeat;
+    mask-composite: exclude;
+    mask-position: left, center, right;
+
+    animation-name: scroll-fade-x-left, scroll-fade-x-right;
+    animation-timing-function: linear, linear;
+    animation-timeline: scroll(self x);
+    animation-range:
+      0 var(--scroll-fade-range, 3rem),
+      calc(100% - var(--scroll-fade-range, 3rem)) 100%;
+    animation-fill-mode: both;
+    animation-composition: replace;
+  }
+}
+
+/* Tab list scroll behavior. Scrollbar is only hidden when scroll-driven
+   animations are supported (the fade replaces it as the affordance).
+   Unsupported browsers keep the native scrollbar. */
+.kumo-tabs-list {
+  overscroll-behavior-x: contain;
+}
+
+@supports (animation-timeline: scroll()) {
+  .kumo-tabs-list {
+    scrollbar-width: none;
+    -ms-overflow-style: none;
+  }
+
+  .kumo-tabs-list::-webkit-scrollbar {
+    display: none;
+  }
+}
+
 /* Popup outline offset - in dark mode, offset inward to align with inner stroke.
    This compensates for the different geometry of inner vs outer stroke paths.
    Used by: Tooltip, Popover