@workbench-kit/react 0.0.2-prototype.0.1.2 → 0.0.2-prototype.0.2.2

package/src/primitives/scroll-area/ScrollArea.tsx

@@ -0,0 +1,200 @@
+import './scroll-area-overlay.css';
+
+import {
+  useEffect,
+  useRef,
+  useState,
+  type ComponentPropsWithRef,
+  type CSSProperties,
+  type ElementType,
+  type ReactNode,
+  type Ref,
+  type UIEvent,
+} from 'react';
+
+import { cx } from '../../utils/cx';
+
+export type ScrollAreaGutter = 'auto' | 'stable';
+export type ScrollAreaOrientation = 'both' | 'horizontal' | 'vertical';
+export type ScrollAreaScrollbarVisibility = 'auto' | 'hidden' | 'overlay';
+
+export interface ScrollAreaProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
+  as?: ElementType | undefined;
+  children?: ReactNode | undefined;
+  gutter?: ScrollAreaGutter | undefined;
+  orientation?: ScrollAreaOrientation | undefined;
+  scrollbars?: ScrollAreaScrollbarVisibility | undefined;
+}
+
+type OverlayThumb = {
+  readonly length: number;
+  readonly offset: number;
+  readonly overflow: boolean;
+};
+
+const OVERLAY_THUMB_MIN_PX = 24;
+
+function assignRef<T>(ref: Ref<T> | undefined, value: T | null): void {
+  if (typeof ref === 'function') {
+    ref(value);
+    return;
+  }
+  if (ref && typeof ref === 'object') {
+    (ref as { current: T | null }).current = value;
+  }
+}
+
+function measureOverlayThumb(
+  viewport: HTMLElement,
+  orientation: ScrollAreaOrientation,
+): OverlayThumb {
+  const vertical = orientation !== 'horizontal';
+  const client = vertical ? viewport.clientHeight : viewport.clientWidth;
+  const scroll = vertical ? viewport.scrollHeight : viewport.scrollWidth;
+  const position = vertical ? viewport.scrollTop : viewport.scrollLeft;
+  const overflow = scroll > client + 1;
+  if (!overflow || client <= 0) {
+    return { length: 0, offset: 0, overflow: false };
+  }
+  const length = Math.max((client / scroll) * client, OVERLAY_THUMB_MIN_PX);
+  const maxOffset = Math.max(client - length, 0);
+  const maxScroll = Math.max(scroll - client, 1);
+  const offset = (position / maxScroll) * maxOffset;
+  return { length, offset, overflow: true };
+}
+
+/**
+ * Overlay mode keeps the scrollport gutter-free (native bar hidden) and paints
+ * an absolute rail/thumb over content so hover never reflows classic scrollports.
+ */
+function OverlayScrollArea({
+  as,
+  children,
+  className,
+  gutter = 'auto',
+  orientation = 'both',
+  onScroll,
+  ref,
+  ...props
+}: Omit<ScrollAreaProps, 'scrollbars'>) {
+  const Component = (as ?? 'div') as ElementType;
+  const viewportRef = useRef<HTMLDivElement | null>(null);
+  const [thumb, setThumb] = useState<OverlayThumb>({ length: 0, offset: 0, overflow: false });
+  const vertical = orientation !== 'horizontal';
+
+  useEffect(() => {
+    const viewport = viewportRef.current;
+    if (!viewport) {
+      return;
+    }
+
+    const sync = () => {
+      setThumb(measureOverlayThumb(viewport, orientation));
+    };
+
+    sync();
+    const observer = new ResizeObserver(sync);
+    observer.observe(viewport);
+    Array.from(viewport.children).forEach((child) => {
+      observer.observe(child);
+    });
+    window.addEventListener('resize', sync);
+    return () => {
+      observer.disconnect();
+      window.removeEventListener('resize', sync);
+    };
+  }, [orientation, children]);
+
+  const handleScroll = (event: UIEvent<HTMLDivElement>) => {
+    setThumb(measureOverlayThumb(event.currentTarget, orientation));
+    onScroll?.(event);
+  };
+
+  const thumbStyle: CSSProperties = vertical
+    ? { height: thumb.length, transform: `translateY(${thumb.offset}px)` }
+    : { width: thumb.length, transform: `translateX(${thumb.offset}px)` };
+
+  return (
+    <Component
+      className={cx(
+        'ui-scroll-area',
+        'ui-scroll-area--overlay-host',
+        `ui-scroll-area--${orientation}`,
+        gutter === 'stable' && 'ui-scroll-area--stable-gutter',
+        className,
+      )}
+      {...props}
+    >
+      <div
+        className={cx(
+          'ui-scroll-area__viewport',
+          'ui-workbench-scrollbar',
+          'ui-workbench-scrollbar--overlay',
+          `ui-scroll-area--${orientation}`,
+        )}
+        ref={(node) => {
+          viewportRef.current = node;
+          assignRef(ref as Ref<HTMLDivElement | null> | undefined, node);
+        }}
+        onScroll={handleScroll}
+      >
+        {children}
+      </div>
+      {thumb.overflow ? (
+        <div
+          aria-hidden="true"
+          className={cx(
+            'ui-scroll-area__overlay-rail',
+            vertical
+              ? 'ui-scroll-area__overlay-rail--vertical'
+              : 'ui-scroll-area__overlay-rail--horizontal',
+          )}
+        >
+          <div className="ui-scroll-area__overlay-thumb" style={thumbStyle} />
+        </div>
+      ) : null}
+    </Component>
+  );
+}
+
+export function ScrollArea({
+  as,
+  children,
+  className,
+  gutter = 'stable',
+  orientation = 'both',
+  scrollbars = 'auto',
+  ...props
+}: ScrollAreaProps) {
+  if (scrollbars === 'overlay') {
+    return (
+      <OverlayScrollArea
+        as={as}
+        className={className}
+        gutter={gutter === 'stable' ? 'auto' : gutter}
+        orientation={orientation}
+        {...props}
+      >
+        {children}
+      </OverlayScrollArea>
+    );
+  }
+
+  const Component = (as ?? 'div') as ElementType;
+
+  return (
+    <Component
+      className={cx(
+        'ui-scroll-area',
+        'ui-workbench-scrollbar',
+        `ui-scroll-area--${orientation}`,
+        gutter === 'stable' && 'ui-scroll-area--stable-gutter',
+        scrollbars === 'hidden' && 'ui-workbench-scrollbar--hidden',
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </Component>
+  );
+}

package/src/primitives/scroll-area/index.ts

@@ -0,0 +1 @@
+export * from './ScrollArea';

package/src/primitives/scroll-area/scroll-area-overlay.css

@@ -0,0 +1,69 @@
+/*
+ * Overlay ScrollArea: native bar stays hidden (gutter 0). An absolute rail/thumb
+ * paints over content on hover/focus-within without changing scrollport width.
+ */
+.ui-scroll-area--overlay-host {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  min-width: 0;
+  min-height: 0;
+}
+
+/* Host must not become the scrollport — orientation overflow stays on the viewport. */
+.ui-scroll-area--overlay-host.ui-scroll-area--both,
+.ui-scroll-area--overlay-host.ui-scroll-area--horizontal,
+.ui-scroll-area--overlay-host.ui-scroll-area--vertical {
+  overflow: hidden;
+}
+
+.ui-scroll-area__viewport {
+  flex: 1 1 auto;
+  min-width: 0;
+  min-height: 0;
+}
+
+.ui-scroll-area__overlay-rail {
+  position: absolute;
+  z-index: 2;
+  pointer-events: none;
+  opacity: 0;
+  transition: opacity 120ms ease;
+}
+
+.ui-scroll-area--overlay-host:hover .ui-scroll-area__overlay-rail,
+.ui-scroll-area--overlay-host:focus-within .ui-scroll-area__overlay-rail {
+  opacity: 1;
+}
+
+.ui-scroll-area__overlay-rail--vertical {
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: var(--scrollbar-size);
+}
+
+.ui-scroll-area__overlay-rail--horizontal {
+  right: 0;
+  bottom: 0;
+  left: 0;
+  height: var(--scrollbar-size);
+}
+
+.ui-scroll-area__overlay-thumb {
+  box-sizing: border-box;
+  border: var(--scrollbar-thumb-inset) solid transparent;
+  border-radius: calc(var(--scrollbar-size) / 2);
+  background: var(--scrollbar-thumb);
+  background-clip: content-box;
+  will-change: transform;
+}
+
+.ui-scroll-area__overlay-rail--vertical .ui-scroll-area__overlay-thumb {
+  width: 100%;
+}
+
+.ui-scroll-area__overlay-rail--horizontal .ui-scroll-area__overlay-thumb {
+  height: 100%;
+}

package/src/primitives/scroll-area-infinite-load/ScrollAreaInfiniteSentinel.tsx

@@ -0,0 +1,22 @@
+import './scroll-area-infinite-sentinel.css';
+import { forwardRef, type HTMLAttributes } from 'react';
+
+import { cx } from '../../utils/cx';
+
+export type ScrollAreaInfiniteSentinelProps = HTMLAttributes<HTMLDivElement>;
+
+export const ScrollAreaInfiniteSentinel = forwardRef<
+  HTMLDivElement,
+  ScrollAreaInfiniteSentinelProps
+>(function ScrollAreaInfiniteSentinel({ className, ...props }, ref) {
+  return (
+    <div
+      aria-hidden="true"
+      className={cx('ui-scroll-area-infinite-sentinel', className)}
+      ref={ref}
+      {...props}
+    />
+  );
+});
+
+ScrollAreaInfiniteSentinel.displayName = 'ScrollAreaInfiniteSentinel';

package/src/primitives/scroll-area-infinite-load/index.ts

@@ -0,0 +1,2 @@
+export * from './ScrollAreaInfiniteSentinel';
+export * from './useScrollAreaInfiniteLoad';

package/src/primitives/scroll-area-infinite-load/scroll-area-infinite-sentinel.css

@@ -0,0 +1,6 @@
+.ui-scroll-area-infinite-sentinel {
+  block-size: 1px;
+  flex-shrink: 0;
+  inline-size: 100%;
+  pointer-events: none;
+}

package/src/primitives/scroll-area-infinite-load/useScrollAreaInfiniteLoad.ts

@@ -0,0 +1,84 @@
+import { useEffect, useRef, type RefObject } from 'react';
+
+const DEFAULT_ROOT_MARGIN = '0px 0px 120px 0px';
+
+export interface UseScrollAreaInfiniteLoadOptions {
+  enabled?: boolean | undefined;
+  hasMore: boolean;
+  isLoading?: boolean | undefined;
+  isLoadingMore?: boolean | undefined;
+  onLoadMore: () => void | Promise<void>;
+  rootMargin?: string | undefined;
+  scrollAreaRef?: RefObject<HTMLElement | null> | undefined;
+}
+
+export interface UseScrollAreaInfiniteLoadResult {
+  sentinelRef: RefObject<HTMLDivElement | null>;
+}
+
+export function useScrollAreaInfiniteLoad({
+  enabled = true,
+  hasMore,
+  isLoading = false,
+  isLoadingMore = false,
+  onLoadMore,
+  rootMargin = DEFAULT_ROOT_MARGIN,
+  scrollAreaRef,
+}: UseScrollAreaInfiniteLoadOptions): UseScrollAreaInfiniteLoadResult {
+  const sentinelRef = useRef<HTMLDivElement>(null);
+  const loadMoreInFlightRef = useRef(false);
+  const onLoadMoreRef = useRef(onLoadMore);
+  const hasMoreRef = useRef(hasMore);
+  const isLoadingRef = useRef(isLoading);
+  const isLoadingMoreRef = useRef(isLoadingMore);
+
+  onLoadMoreRef.current = onLoadMore;
+  hasMoreRef.current = hasMore;
+  isLoadingRef.current = isLoading;
+  isLoadingMoreRef.current = isLoadingMore;
+
+  useEffect(() => {
+    if (!enabled || !hasMore || isLoading || isLoadingMore) {
+      return undefined;
+    }
+
+    const scrollContainer =
+      scrollAreaRef?.current ??
+      sentinelRef.current?.closest('.ui-scroll-area') ??
+      sentinelRef.current?.parentElement;
+    const sentinel = sentinelRef.current;
+
+    if (!scrollContainer || !sentinel || typeof IntersectionObserver === 'undefined') {
+      return undefined;
+    }
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (
+          !entry?.isIntersecting ||
+          loadMoreInFlightRef.current ||
+          !hasMoreRef.current ||
+          isLoadingRef.current ||
+          isLoadingMoreRef.current
+        ) {
+          return;
+        }
+
+        loadMoreInFlightRef.current = true;
+        void Promise.resolve(onLoadMoreRef.current()).finally(() => {
+          loadMoreInFlightRef.current = false;
+        });
+      },
+      {
+        root: scrollContainer,
+        rootMargin,
+        threshold: 0,
+      },
+    );
+
+    observer.observe(sentinel);
+    return () => observer.disconnect();
+  }, [enabled, hasMore, isLoading, isLoadingMore, rootMargin, scrollAreaRef]);
+
+  return { sentinelRef };
+}