@noya-app/noya-designsystem 0.1.77 → 0.1.78

package/src/components/Virtualized.tsx

@@ -13,8 +13,13 @@ import React, {
   useState,
 } from "react";
 import { flushSync } from "react-dom";
-import { IVirtualizedList } from "./IVirtualizedList";
-import { ScrollArea2 } from "./ScrollArea2";
+import {
+  IVirtualizedList,
+  ScrollToIndexAlign,
+  ScrollToIndexOptions,
+  ScrollToIndexPadding,
+} from "./IVirtualizedList";
+import { ScrollArea } from "./ScrollArea";
 
 export type ItemMeasurement = {
   index: number;
@@ -47,18 +52,35 @@ type VisibleRange = {
   end: number;
 };
 
+function resolveScrollPadding(padding?: ScrollToIndexPadding): {
+  top: number;
+  bottom: number;
+} {
+  if (typeof padding === "number") {
+    return { top: padding, bottom: padding };
+  }
+  return {
+    top: padding?.top ?? 0,
+    bottom: padding?.bottom ?? 0,
+  };
+}
+
 export function calculateScrollOffsetForIndex({
   measurements,
   height,
   totalHeight,
   targetIndex,
   currentScrollTop,
+  align = "auto",
+  padding,
 }: {
   measurements: ItemMeasurement[];
   height: number;
   totalHeight: number;
   targetIndex: number;
   currentScrollTop: number;
+  align?: ScrollToIndexAlign;
+  padding?: ScrollToIndexPadding;
 }): number | undefined {
   if (!measurements.length) return;
 
@@ -71,17 +93,32 @@ export function calculateScrollOffsetForIndex({
   const viewportBottom = viewportTop + height;
   const itemTop = measurement.start;
   const itemBottom = measurement.end;
+  const { top: paddingTop, bottom: paddingBottom } =
+    resolveScrollPadding(padding);
 
   let nextScrollTop = viewportTop;
 
-  if (itemTop < viewportTop) {
-    nextScrollTop = itemTop;
-  } else if (itemBottom > viewportBottom) {
-    const canAlignTop = height >= measurement.size;
-
-    nextScrollTop = canAlignTop ? itemTop : itemBottom - height;
+  if (align === "start") {
+    // Always align item to top of viewport, with padding above
+    nextScrollTop = itemTop - paddingTop;
+  } else if (align === "end") {
+    // Always align item to bottom of viewport, with padding below
+    nextScrollTop = itemBottom - height + paddingBottom;
+  } else if (align === "center") {
+    // Always center item in viewport (padding not applied for center)
+    nextScrollTop = itemTop - (height - measurement.size) / 2;
   } else {
-    return;
+    // "auto": scroll minimum distance to make item visible
+    if (itemTop < viewportTop) {
+      // Item is above viewport, scroll up to show it at top with padding
+      nextScrollTop = itemTop - paddingTop;
+    } else if (itemBottom > viewportBottom) {
+      // Item is below viewport, scroll down to show it at bottom with padding
+      nextScrollTop = itemBottom - height + paddingBottom;
+    } else {
+      // Item is already fully visible, no scroll needed
+      return;
+    }
   }
 
   const maxScrollTop = Math.max(0, totalHeight - height);
@@ -203,6 +240,78 @@ export function calculateVisibleRange({
   };
 }
 
+export type StickyRowPosition = {
+  index: number;
+  stickyTop: number;
+};
+
+export function calculateStickyRows({
+  measurements,
+  scrollTop,
+  isStickyRow,
+}: {
+  measurements: ItemMeasurement[];
+  scrollTop: number;
+  isStickyRow: (index: number) => boolean;
+}): StickyRowPosition[] {
+  // Find all sticky row indices
+  const stickyIndices: number[] = [];
+  for (const measurement of measurements) {
+    if (isStickyRow(measurement.index)) {
+      stickyIndices.push(measurement.index);
+    }
+  }
+
+  if (stickyIndices.length === 0) return [];
+
+  // Find the current sticky row (the last one that has scrolled past the top)
+  let currentStickyIdx = -1;
+  for (let i = 0; i < stickyIndices.length; i++) {
+    const measurement = measurements[stickyIndices[i]];
+    if (measurement.start <= scrollTop) {
+      currentStickyIdx = i;
+    } else {
+      break;
+    }
+  }
+
+  if (currentStickyIdx === -1) return [];
+
+  const currentSticky = measurements[stickyIndices[currentStickyIdx]];
+  const result: StickyRowPosition[] = [];
+
+  // Check if there's a next sticky row approaching
+  const nextStickyIdx = currentStickyIdx + 1;
+  if (nextStickyIdx < stickyIndices.length) {
+    const nextSticky = measurements[stickyIndices[nextStickyIdx]];
+    // Calculate how much the current sticky should be pushed up
+    // When nextSticky.start reaches scrollTop + currentSticky.size, push starts
+    const pushDistance = scrollTop + currentSticky.size - nextSticky.start;
+
+    if (pushDistance > 0) {
+      // Current sticky is being pushed up
+      result.push({
+        index: currentSticky.index,
+        stickyTop: -pushDistance,
+      });
+    } else {
+      // Current sticky stays at top
+      result.push({
+        index: currentSticky.index,
+        stickyTop: 0,
+      });
+    }
+  } else {
+    // No next sticky, current stays at top
+    result.push({
+      index: currentSticky.index,
+      stickyTop: 0,
+    });
+  }
+
+  return result;
+}
+
 export type VirtualizedProps = {
   height: number;
   itemCount: number;
@@ -230,13 +339,19 @@ export type VirtualizedProps = {
    */
   gap?: number;
   /**
-   * Render content inside ScrollArea2 instead of a plain div.
+   * Render content inside ScrollArea instead of a plain div.
    */
   useScrollArea?: boolean;
   /**
    * Optional class applied to the ScrollArea viewport when `useScrollArea` is true.
    */
   scrollAreaViewportClassName?: string;
+  /**
+   * Callback to determine if a row should be sticky.
+   * Only one sticky row is shown at a time. When the next sticky row approaches,
+   * it pushes the current one up and out of view.
+   */
+  isStickyRow?: (index: number) => boolean;
 };
 
 const DEFAULT_OVERSCAN = 2;
@@ -260,6 +375,7 @@ const VirtualizedInner = React.forwardRef(function Virtualized(
     gap = 0,
     useScrollArea = false,
     scrollAreaViewportClassName,
+    isStickyRow,
   }: VirtualizedProps,
   forwardedRef: ForwardedRef<IVirtualizedList>
 ) {
@@ -312,6 +428,15 @@ const VirtualizedInner = React.forwardRef(function Virtualized(
     [height, measurements, overscan, scrollTop]
   );
 
+  const stickyRows = useMemo(() => {
+    if (!isStickyRow) return [];
+    return calculateStickyRows({
+      measurements,
+      scrollTop,
+      isStickyRow,
+    });
+  }, [measurements, scrollTop, isStickyRow]);
+
   const handleScroll = useCallback<UIEventHandler<HTMLDivElement>>(
     (event) => {
       const nextOffset = event.currentTarget.scrollTop;
@@ -333,7 +458,7 @@ const VirtualizedInner = React.forwardRef(function Virtualized(
   useImperativeHandle(
     forwardedRef,
     () => ({
-      scrollToIndex(index: number) {
+      scrollToIndex(index: number, options?: ScrollToIndexOptions) {
         const container = containerRef.current;
         if (!container) return;
 
@@ -343,6 +468,8 @@ const VirtualizedInner = React.forwardRef(function Virtualized(
           totalHeight,
           targetIndex: index,
           currentScrollTop: container.scrollTop,
+          align: options?.align,
+          padding: options?.padding,
         });
 
         if (nextScrollTop == null) return;
@@ -408,19 +535,66 @@ const VirtualizedInner = React.forwardRef(function Virtualized(
     </div>
   );
 
+  const stickyOverlay =
+    stickyRows.length > 0 ? (
+      <div
+        style={{
+          position: "sticky",
+          top: 0,
+          height: 0,
+          overflow: "visible",
+          pointerEvents: "none",
+          zIndex: 1,
+        }}
+      >
+        <div
+          style={{
+            position: "absolute",
+            top: 0,
+            width: "100%",
+            overflow: "hidden",
+          }}
+        >
+          {stickyRows.map(({ index, stickyTop }) => {
+            const measurement = measurements[index];
+            const key = itemKey
+              ? `sticky-${itemKey(index)}`
+              : `sticky-${index}`;
+
+            return (
+              <div
+                key={key}
+                style={{
+                  position: "relative",
+                  top: stickyTop,
+                  width: "100%",
+                  height: measurement.size,
+                  pointerEvents: "auto",
+                }}
+              >
+                {renderItem(index)}
+              </div>
+            );
+          })}
+        </div>
+      </div>
+    ) : null;
+
   if (useScrollArea) {
     return (
-      <ScrollArea2
+      <ScrollArea
         className={className}
         style={scrollAreaStyle}
         viewportClassName={scrollAreaViewportClassName}
         viewportProps={{
           ref: setScrollElement,
           onScroll: handleScroll,
+          style: isStickyRow ? { isolation: "isolate" } : undefined,
         }}
       >
+        {stickyOverlay}
         {totalContent}
-      </ScrollArea2>
+      </ScrollArea>
     );
   }
 
@@ -428,9 +602,14 @@ const VirtualizedInner = React.forwardRef(function Virtualized(
     <div
       ref={setScrollElement}
       className={className}
-      style={containerStyle}
+      style={
+        isStickyRow
+          ? { ...containerStyle, isolation: "isolate" }
+          : containerStyle
+      }
       onScroll={handleScroll}
     >
+      {stickyOverlay}
       {totalContent}
     </div>
   );

package/src/components/VisuallyHidden.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+import React from "react";
+
+const visuallyHiddenStyle: React.CSSProperties = {
+  border: 0,
+  clip: "rect(0 0 0 0)",
+  clipPath: "inset(50%)",
+  height: "1px",
+  margin: "-1px",
+  overflow: "hidden",
+  padding: 0,
+  position: "absolute",
+  whiteSpace: "nowrap",
+  width: "1px",
+};
+
+export function VisuallyHidden({ children }: { children: React.ReactNode }) {
+  return <span style={visuallyHiddenStyle}>{children}</span>;
+}