@usefragments/ui 1.5.4 → 1.6.0

package/src/components/ScrollArea/ScrollArea.contract.json

@@ -3,13 +3,7 @@
   "name": "ScrollArea",
   "description": "A styled scrollable container with thin scrollbars and optional fade indicators.",
   "category": "layout",
-  "tags": [
-    "scroll",
-    "overflow",
-    "scrollbar",
-    "container",
-    "layout"
-  ],
+  "tags": ["scroll", "overflow", "scrollbar", "container", "layout"],
   "status": "stable",
   "sourcePath": "src/components/ScrollArea/index.tsx",
   "exportName": "ScrollArea",
@@ -31,22 +25,14 @@
       "description": "Scroll direction",
       "default": "vertical",
       "required": false,
-      "values": [
-        "horizontal",
-        "vertical",
-        "both"
-      ]
+      "values": ["horizontal", "vertical", "both"]
     },
     "scrollbarVisibility": {
       "type": "enum",
       "description": "When to show the scrollbar",
       "default": "auto",
       "required": false,
-      "values": [
-        "auto",
-        "always",
-        "hover"
-      ]
+      "values": ["auto", "always", "hover"]
     },
     "showFades": {
       "type": "boolean",
@@ -74,11 +60,11 @@
     "guidelines": [
       "Use `orientation` to constrain scroll direction",
       "Use `showFades` to hint at hidden content beyond the viewport",
-      "The `hover` scrollbar visibility keeps the UI clean until the user interacts",
+      "The `auto` and `hover` modes keep the thumb quiet until hover or keyboard focus without changing track geometry",
       "Combine with `orientation=\"horizontal\"` for tab bars and chip rows"
     ],
     "accessibility": [
-      "Preserves native scroll behavior and keyboard support",
+      "Preserves native scroll behavior and keyboard support across both axes",
       "Scrollbar is visible on focus for keyboard users",
       "Respects prefers-reduced-motion for fade transitions"
     ]
@@ -96,12 +82,12 @@
     },
     {
       "name": "With Fades",
-      "description": "Fade indicators show when content is scrollable in either direction.",
+      "description": "Fade indicators independently show the available logical direction on each scrollable axis.",
       "code": "<ScrollArea orientation=\"horizontal\" showFades>\n  {/* Overflowing content */}\n</ScrollArea>"
     },
     {
       "name": "Hover Scrollbar",
-      "description": "Scrollbar is hidden until the user hovers over the scroll area.",
+      "description": "Scrollbar thumb paint appears on hover or keyboard focus without changing track dimensions.",
       "code": "<ScrollArea scrollbarVisibility=\"hover\" style={{ height: '200px' }}>\n  {/* Content */}\n</ScrollArea>"
     }
   ],
@@ -114,9 +100,7 @@
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ],
+    "subComponents": ["Root"],
     "commonPatterns": [
       "<ScrollArea orientation=\"horizontal\"><div style={{ display: \"flex\", gap: 8 }}>{items}</div></ScrollArea>",
       "<ScrollArea style={{ height: 300 }}>{longContent}</ScrollArea>"

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

@@ -1,80 +1,46 @@
+@use '../../tokens/measurements.generated' as measurements;
 @use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
-
-// ============================================
-// ScrollArea Root
-// ============================================
 
 .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

@@ -2,6 +2,12 @@
 
 import * as React from 'react';
 import styles from './ScrollArea.module.scss';
+import {
+  detectRtlScrollModel,
+  readScrollAxes,
+  type ScrollAxesState,
+  type ScrollOrientation,
+} from './scroll-state';
 
 // ============================================
 // Types
@@ -10,7 +16,7 @@ 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 */
@@ -35,78 +41,90 @@ function ScrollAreaRoot({
   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 };
+}