@usefragments/ui 1.5.4 → 1.7.0

package/src/components/ScrollArea/ScrollArea.module.scss

@@ -1,80 +1,46 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
-
-// ============================================
-// ScrollArea Root
-// ============================================
+@use "../../tokens/measurements.generated" as measurements;
+@use "../../tokens/variables" as *;
 
 .root {
+  --fui-scrollarea-track-size: var(--fui-raw-space-6, #{measurements.raw-space(6)});
+  --fui-scrollarea-inline-fade: var(--fui-raw-space-48, #{measurements.raw-space(48)});
+  --fui-scrollarea-block-fade: var(--fui-raw-space-32, #{measurements.raw-space(32)});
+  --_fui-scrollarea-track-size: var(
+    --fui-scrollarea-track-size,
+    var(--fui-raw-space-6, #{measurements.raw-space(6)})
+  );
+  --_fui-scrollarea-inline-fade: var(
+    --fui-scrollarea-inline-fade,
+    var(--fui-raw-space-48, #{measurements.raw-space(48)})
+  );
+  --_fui-scrollarea-block-fade: var(
+    --fui-scrollarea-block-fade,
+    var(--fui-raw-space-32, #{measurements.raw-space(32)})
+  );
+
   position: relative;
   overflow: hidden;
 }
 
-// ============================================
-// Fade masks — applied to the viewport via CSS mask-image.
-// This fades out the actual content at the edges, which is
-// far more visible than overlaying a gradient pseudo-element.
-// ============================================
-
-.fadeMaskEnd {
-  &.horizontal {
-    mask-image: linear-gradient(to right, black calc(100% - 48px), transparent 100%);
-  }
-
-  &.vertical {
-    mask-image: linear-gradient(to bottom, black calc(100% - 32px), transparent 100%);
-  }
-
-  &.both {
-    mask-image: linear-gradient(to right, black calc(100% - 48px), transparent 100%);
-  }
-}
-
-.fadeMaskStart {
-  &.horizontal {
-    mask-image: linear-gradient(to left, black calc(100% - 48px), transparent 100%);
-  }
-
-  &.vertical {
-    mask-image: linear-gradient(to top, black calc(100% - 32px), transparent 100%);
-  }
-
-  &.both {
-    mask-image: linear-gradient(to left, black calc(100% - 48px), transparent 100%);
-  }
-}
-
-.fadeMaskBoth {
-  &.horizontal {
-    mask-image: linear-gradient(to right, transparent, black 48px, black calc(100% - 48px), transparent 100%);
-  }
-
-  &.vertical {
-    mask-image: linear-gradient(to bottom, transparent, black 32px, black calc(100% - 32px), transparent 100%);
-  }
-
-  &.both {
-    mask-image: linear-gradient(to right, transparent, black 48px, black calc(100% - 48px), transparent 100%);
-  }
-}
-
-// ============================================
-// Viewport (scrollable area)
-// ============================================
-
 .viewport {
-  width: 100%;
-  height: 100%;
+  --_fui-scrollarea-inline-mask: linear-gradient(black, black);
+  --_fui-scrollarea-block-mask: linear-gradient(black, black);
+
+  inline-size: 100%;
+  block-size: 100%;
   overflow: hidden;
-  // Reserve gutter space so the thumb revealing on hover doesn't shift
-  // content; transparent at rest gives the overlay-scrollbar look.
   scrollbar-width: thin;
   scrollbar-color: transparent transparent;
+  mask-image: var(--_fui-scrollarea-inline-mask), var(--_fui-scrollarea-block-mask);
+  mask-repeat: no-repeat;
+  mask-size: 100% 100%;
+  mask-composite: intersect;
+  -webkit-mask-image: var(--_fui-scrollarea-inline-mask), var(--_fui-scrollarea-block-mask);
+  -webkit-mask-composite: source-in;
 
-  // Webkit custom scrollbar
   &::-webkit-scrollbar {
-    width: 6px;
-    height: 6px;
+    width: var(--_fui-scrollarea-track-size);
+    height: var(--_fui-scrollarea-track-size);
   }
 
   &::-webkit-scrollbar-track {
@@ -82,27 +48,26 @@
   }
 
   &::-webkit-scrollbar-thumb {
+    border-radius: var(--fui-radius-full, #{$fui-radius-full});
     background-color: transparent;
-    border-radius: var(--fui-radius-full, $fui-radius-full);
-    transition: background-color var(--fui-transition-fast, $fui-transition-fast);
+    transition: background-color var(--fui-transition-fast, #{$fui-transition-fast});
   }
 
-  // Reveal thumb while the viewport is hovered
-  &:hover {
-    scrollbar-color: var(--fui-border-strong, $fui-border-strong) transparent;
-  }
+  &:hover,
+  &:focus-within,
+  &[data-scrollbar-visibility="always"] {
+    scrollbar-color: var(--fui-border-strong, #{$fui-border-strong}) transparent;
 
-  &:hover::-webkit-scrollbar-thumb {
-    background-color: var(--fui-border-strong, $fui-border-strong);
+    &::-webkit-scrollbar-thumb {
+      background-color: var(--fui-border-strong, #{$fui-border-strong});
+    }
   }
 
-  // Darker when hovering the thumb itself
   &::-webkit-scrollbar-thumb:hover {
-    background-color: var(--fui-text-tertiary, $fui-text-tertiary);
+    background-color: var(--fui-text-tertiary, #{$fui-text-tertiary});
   }
 }
 
-// Orientation variants
 .horizontal {
   overflow-x: auto;
   overflow-y: hidden;
@@ -117,33 +82,94 @@
   overflow: auto;
 }
 
-// ============================================
-// Scrollbar visibility modes
-// ============================================
+.horizontal:not([data-scroll-x="none"]),
+.both:not([data-scroll-x="none"]) {
+  scroll-padding-inline: var(--_fui-scrollarea-inline-fade);
+}
 
-// Always show scrollbar
-.scrollbarAlways {
-  &::-webkit-scrollbar-thumb {
-    background-color: var(--fui-border-strong, $fui-border-strong);
-  }
+.vertical:not([data-scroll-y="none"]),
+.both:not([data-scroll-y="none"]) {
+  scroll-padding-block: var(--_fui-scrollarea-block-fade);
 }
 
-// Only show scrollbar on hover
-.scrollbarHover {
-  scrollbar-width: none;
+.viewport[data-scroll-x="end"] {
+  --_fui-scrollarea-inline-mask: linear-gradient(
+    to right,
+    black calc(100% - var(--_fui-scrollarea-inline-fade)),
+    transparent
+  );
+}
 
-  &::-webkit-scrollbar {
-    width: 0;
-    height: 0;
-  }
+.viewport[data-scroll-x="start"] {
+  --_fui-scrollarea-inline-mask: linear-gradient(
+    to right,
+    transparent,
+    black var(--_fui-scrollarea-inline-fade)
+  );
+}
 
-  &:hover {
-    scrollbar-width: thin;
+.viewport[data-scroll-x="both"] {
+  --_fui-scrollarea-inline-mask: linear-gradient(
+    to right,
+    transparent,
+    black var(--_fui-scrollarea-inline-fade),
+    black calc(100% - var(--_fui-scrollarea-inline-fade)),
+    transparent
+  );
+}
 
-    &::-webkit-scrollbar {
-      width: 6px;
-      height: 6px;
-    }
+.viewport[data-scroll-x="end"]:dir(rtl) {
+  --_fui-scrollarea-inline-mask: linear-gradient(
+    to right,
+    transparent,
+    black var(--_fui-scrollarea-inline-fade)
+  );
+}
+
+.viewport[data-scroll-x="start"]:dir(rtl) {
+  --_fui-scrollarea-inline-mask: linear-gradient(
+    to right,
+    black calc(100% - var(--_fui-scrollarea-inline-fade)),
+    transparent
+  );
+}
+
+.viewport[data-scroll-y="end"] {
+  --_fui-scrollarea-block-mask: linear-gradient(
+    to bottom,
+    black calc(100% - var(--_fui-scrollarea-block-fade)),
+    transparent
+  );
+}
+
+.viewport[data-scroll-y="start"] {
+  --_fui-scrollarea-block-mask: linear-gradient(
+    to bottom,
+    transparent,
+    black var(--_fui-scrollarea-block-fade)
+  );
+}
+
+.viewport[data-scroll-y="both"] {
+  --_fui-scrollarea-block-mask: linear-gradient(
+    to bottom,
+    transparent,
+    black var(--_fui-scrollarea-block-fade),
+    black calc(100% - var(--_fui-scrollarea-block-fade)),
+    transparent
+  );
+}
+
+@media (forced-colors: active) {
+  .viewport {
+    scrollbar-color: CanvasText Canvas;
+    mask-image: none;
+    -webkit-mask-image: none;
   }
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .viewport::-webkit-scrollbar-thumb {
+    transition: none;
+  }
+}

package/src/components/ScrollArea/index.tsx

@@ -1,7 +1,13 @@
-'use client';
+"use client";
 
-import * as React from 'react';
-import styles from './ScrollArea.module.scss';
+import * as React from "react";
+import styles from "./ScrollArea.module.scss";
+import {
+  detectRtlScrollModel,
+  readScrollAxes,
+  type ScrollAxesState,
+  type ScrollOrientation,
+} from "./scroll-state";
 
 // ============================================
 // Types
@@ -10,10 +16,10 @@ import styles from './ScrollArea.module.scss';
 export interface ScrollAreaProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
   /** Scroll direction */
-  orientation?: 'horizontal' | 'vertical' | 'both';
+  orientation?: ScrollOrientation;
   /** Scrollbar visibility behavior */
-  scrollbarVisibility?: 'auto' | 'always' | 'hover';
-  /** Whether to show fade indicators at scroll edges */
+  scrollbarVisibility?: "auto" | "always" | "hover";
+  /** Whether to show fade indicators at scroll edges. Defaults to false. */
   showFades?: boolean;
   /** Additional class name */
   className?: string;
@@ -31,82 +37,94 @@ export interface ScrollAreaProps extends React.HTMLAttributes<HTMLDivElement> {
  */
 function ScrollAreaRoot({
   children,
-  orientation = 'vertical',
-  scrollbarVisibility = 'auto',
+  orientation = "vertical",
+  scrollbarVisibility = "auto",
   showFades = false,
   className,
+  dir,
   ...htmlProps
 }: ScrollAreaProps) {
   const viewportRef = React.useRef<HTMLDivElement>(null);
-  const [canScrollStart, setCanScrollStart] = React.useState(false);
-  const [canScrollEnd, setCanScrollEnd] = React.useState(false);
-
-  const updateScrollState = React.useCallback(() => {
-    const el = viewportRef.current;
-    if (!el || !showFades) return;
-
-    if (orientation === 'horizontal') {
-      setCanScrollStart(el.scrollLeft > 1);
-      setCanScrollEnd(el.scrollLeft < el.scrollWidth - el.clientWidth - 1);
-    } else {
-      setCanScrollStart(el.scrollTop > 1);
-      setCanScrollEnd(el.scrollTop < el.scrollHeight - el.clientHeight - 1);
-    }
-  }, [orientation, showFades]);
+  const [axes, setAxes] = React.useState<ScrollAxesState>({ x: "none", y: "none" });
 
   React.useEffect(() => {
-    const el = viewportRef.current;
-    if (!el || !showFades) return;
+    const viewport = viewportRef.current;
+    if (!viewport || !showFades) return;
+
+    let frame: number | null = null;
+    const observedChildren = new Set<Element>();
+
+    const readAndCommit = () => {
+      frame = null;
+      const view = viewport.ownerDocument.defaultView;
+      const computedDirection = view?.getComputedStyle(viewport).direction;
+      const direction = (computedDirection || dir) === "rtl" ? "rtl" : "ltr";
+      const nextAxes = readScrollAxes(viewport, {
+        orientation,
+        direction,
+        rtlModel: direction === "rtl" ? detectRtlScrollModel(viewport.ownerDocument) : undefined,
+      });
+
+      setAxes((currentAxes) =>
+        currentAxes.x === nextAxes.x && currentAxes.y === nextAxes.y ? currentAxes : nextAxes
+      );
+    };
+
+    const schedule = () => {
+      if (frame === null) frame = requestAnimationFrame(readAndCommit);
+    };
 
-    // Defer initial check to ensure children have laid out
-    const raf = requestAnimationFrame(updateScrollState);
+    const resizeObserver = new ResizeObserver(schedule);
+    const syncObservedChildren = () => {
+      const currentChildren = new Set(Array.from(viewport.children));
+      observedChildren.forEach((child) => {
+        if (!currentChildren.has(child)) {
+          resizeObserver.unobserve(child);
+          observedChildren.delete(child);
+        }
+      });
+      currentChildren.forEach((child) => {
+        if (!observedChildren.has(child)) {
+          resizeObserver.observe(child);
+          observedChildren.add(child);
+        }
+      });
+    };
 
-    el.addEventListener('scroll', updateScrollState, { passive: true });
+    const mutationObserver = new MutationObserver(() => {
+      syncObservedChildren();
+      schedule();
+    });
 
-    // Observe both the viewport AND its children for size changes
-    // (viewport size stays constant when children overflow — only scrollWidth changes)
-    const observer = new ResizeObserver(updateScrollState);
-    observer.observe(el);
-    Array.from(el.children).forEach(child => observer.observe(child));
+    resizeObserver.observe(viewport);
+    syncObservedChildren();
+    mutationObserver.observe(viewport, { childList: true, subtree: true });
+    viewport.addEventListener("scroll", schedule, { passive: true });
+    schedule();
 
     return () => {
-      cancelAnimationFrame(raf);
-      el.removeEventListener('scroll', updateScrollState);
-      observer.disconnect();
+      if (frame !== null) cancelAnimationFrame(frame);
+      viewport.removeEventListener("scroll", schedule);
+      resizeObserver.disconnect();
+      mutationObserver.disconnect();
+      observedChildren.clear();
     };
-  }, [showFades, updateScrollState]);
-
-  const rootClasses = [
-    styles.root,
-    className,
-  ].filter(Boolean).join(' ');
-
-  // Determine which fade mask to apply to the viewport
-  const fadeMask = showFades
-    ? canScrollStart && canScrollEnd
-      ? styles.fadeMaskBoth
-      : canScrollStart
-        ? styles.fadeMaskStart
-        : canScrollEnd
-          ? styles.fadeMaskEnd
-          : undefined
-    : undefined;
-
-  const viewportClasses = [
-    styles.viewport,
-    styles[orientation],
-    scrollbarVisibility === 'always' && styles.scrollbarAlways,
-    scrollbarVisibility === 'hover' && styles.scrollbarHover,
-    fadeMask,
-  ].filter(Boolean).join(' ');
+  }, [dir, orientation, showFades]);
+
+  const rootClasses = [styles.root, className].filter(Boolean).join(" ");
+  const visibleAxes = showFades ? axes : { x: "none" as const, y: "none" as const };
+
+  const viewportClasses = [styles.viewport, styles[orientation]].filter(Boolean).join(" ");
 
   return (
-    <div
-      {...htmlProps}
-      className={rootClasses}
-      data-orientation={orientation}
-    >
-      <div ref={viewportRef} className={viewportClasses}>
+    <div {...htmlProps} className={rootClasses} data-orientation={orientation} dir={dir}>
+      <div
+        ref={viewportRef}
+        className={viewportClasses}
+        data-scroll-x={visibleAxes.x}
+        data-scroll-y={visibleAxes.y}
+        data-scrollbar-visibility={scrollbarVisibility}
+      >
         {children}
       </div>
     </div>

package/src/components/ScrollArea/scroll-state.ts

@@ -0,0 +1,87 @@
+export type ScrollOrientation = "horizontal" | "vertical" | "both";
+export type ScrollEdgeState = "none" | "start" | "end" | "both";
+export type RtlScrollModel = "negative" | "positive-descending" | "positive-ascending";
+
+export interface ScrollAxesState {
+  x: ScrollEdgeState;
+  y: ScrollEdgeState;
+}
+
+export const SCROLL_EDGE_EPSILON_PX = 1;
+
+const rtlScrollModels = new WeakMap<Document, RtlScrollModel>();
+
+/** Detect the browser's RTL scrollLeft model without retaining probe elements. */
+export function detectRtlScrollModel(document: Document): RtlScrollModel {
+  const cachedModel = rtlScrollModels.get(document);
+  if (cachedModel) return cachedModel;
+
+  const viewport = document.createElement("div");
+  const content = document.createElement("div");
+  viewport.dir = "rtl";
+  viewport.style.cssText =
+    "position:absolute;inset-block-start:-9999px;inline-size:4px;block-size:1px;overflow:scroll;visibility:hidden";
+  content.style.cssText = "inline-size:8px;block-size:1px";
+  viewport.append(content);
+  (document.body ?? document.documentElement).append(viewport);
+
+  let model: RtlScrollModel;
+  if (viewport.scrollLeft > 0) {
+    model = "positive-descending";
+  } else {
+    viewport.scrollLeft = 1;
+    model = viewport.scrollLeft === 0 ? "negative" : "positive-ascending";
+  }
+
+  viewport.remove();
+  rtlScrollModels.set(document, model);
+  return model;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+function resolveEdgeState(distanceFromStart: number, maxScroll: number): ScrollEdgeState {
+  if (maxScroll <= SCROLL_EDGE_EPSILON_PX) return "none";
+  if (distanceFromStart <= SCROLL_EDGE_EPSILON_PX) return "end";
+  if (maxScroll - distanceFromStart <= SCROLL_EDGE_EPSILON_PX) return "start";
+  return "both";
+}
+
+export function readScrollAxes(
+  element: Pick<
+    HTMLElement,
+    "clientWidth" | "clientHeight" | "scrollWidth" | "scrollHeight" | "scrollLeft" | "scrollTop"
+  >,
+  options: {
+    orientation: ScrollOrientation;
+    direction: "ltr" | "rtl";
+    rtlModel?: RtlScrollModel;
+  }
+): ScrollAxesState {
+  const allowX = options.orientation === "horizontal" || options.orientation === "both";
+  const allowY = options.orientation === "vertical" || options.orientation === "both";
+
+  const maxX = Math.max(0, element.scrollWidth - element.clientWidth);
+  const maxY = Math.max(0, element.scrollHeight - element.clientHeight);
+
+  let x: ScrollEdgeState = "none";
+  if (allowX) {
+    let logicalScrollLeft = element.scrollLeft;
+    if (options.direction === "rtl") {
+      const rtlModel = options.rtlModel ?? "negative";
+      if (rtlModel === "negative") {
+        logicalScrollLeft = -element.scrollLeft;
+      } else if (rtlModel === "positive-descending") {
+        logicalScrollLeft = maxX - element.scrollLeft;
+      }
+    }
+
+    x = resolveEdgeState(clamp(logicalScrollLeft, 0, maxX), maxX);
+  }
+
+  const y = allowY ? resolveEdgeState(clamp(element.scrollTop, 0, maxY), maxY) : "none";
+
+  return { x, y };
+}