@noya-app/noya-designsystem 0.1.70 → 0.1.72

package/src/components/Virtualized.tsx

@@ -0,0 +1,439 @@
+"use client";
+
+import React, {
+  CSSProperties,
+  ForwardedRef,
+  ReactNode,
+  UIEventHandler,
+  useCallback,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { flushSync } from "react-dom";
+import { IVirtualizedList } from "./IVirtualizedList";
+import { ScrollArea2 } from "./ScrollArea2";
+
+export type ItemMeasurement = {
+  index: number;
+  size: number;
+  start: number;
+  end: number;
+};
+
+export type VirtualizedRenderItem = (index: number) => ReactNode;
+
+type VirtualizedPadding =
+  | number
+  | {
+      top?: number;
+      bottom?: number;
+    };
+
+type PaddingValues = {
+  top: number;
+  bottom: number;
+};
+
+type MeasurementResult = {
+  measurements: ItemMeasurement[];
+  totalHeight: number;
+};
+
+type VisibleRange = {
+  start: number;
+  end: number;
+};
+
+export function calculateScrollOffsetForIndex({
+  measurements,
+  height,
+  totalHeight,
+  targetIndex,
+  currentScrollTop,
+}: {
+  measurements: ItemMeasurement[];
+  height: number;
+  totalHeight: number;
+  targetIndex: number;
+  currentScrollTop: number;
+}): number | undefined {
+  if (!measurements.length) return;
+
+  const index = Math.min(Math.max(targetIndex, 0), measurements.length - 1);
+  const measurement = measurements[index];
+
+  if (!measurement) return;
+
+  const viewportTop = currentScrollTop;
+  const viewportBottom = viewportTop + height;
+  const itemTop = measurement.start;
+  const itemBottom = measurement.end;
+
+  let nextScrollTop = viewportTop;
+
+  if (itemTop < viewportTop) {
+    nextScrollTop = itemTop;
+  } else if (itemBottom > viewportBottom) {
+    const canAlignTop = height >= measurement.size;
+
+    nextScrollTop = canAlignTop ? itemTop : itemBottom - height;
+  } else {
+    return;
+  }
+
+  const maxScrollTop = Math.max(0, totalHeight - height);
+  nextScrollTop = Math.max(0, Math.min(nextScrollTop, maxScrollTop));
+
+  if (nextScrollTop === viewportTop) return;
+
+  return nextScrollTop;
+}
+
+export function resolvePaddingValues(
+  padding?: VirtualizedPadding
+): PaddingValues {
+  if (typeof padding === "number") {
+    return { top: padding, bottom: padding };
+  }
+
+  return {
+    top: padding?.top ?? 0,
+    bottom: padding?.bottom ?? 0,
+  };
+}
+
+export function clampGapValue(gap: number | undefined): number {
+  return Math.max(0, gap ?? 0);
+}
+
+export function buildMeasurements({
+  itemCount,
+  getItemHeight,
+  paddingTop,
+  paddingBottom,
+  gap,
+}: {
+  itemCount: number;
+  getItemHeight: (index: number) => number;
+  paddingTop: number;
+  paddingBottom: number;
+  gap: number;
+}): MeasurementResult {
+  const measurements: ItemMeasurement[] = [];
+  let offset = paddingTop;
+
+  for (let index = 0; index < itemCount; index += 1) {
+    const size = Math.max(0, getItemHeight(index));
+    const start = offset;
+    const end = start + size;
+    measurements.push({ index, size, start, end });
+    offset = end + gap;
+  }
+
+  const totalHeight = measurements.length
+    ? measurements[measurements.length - 1].end + paddingBottom
+    : paddingTop + paddingBottom;
+
+  return { measurements, totalHeight };
+}
+
+export function findFirstVisibleIndex(
+  measurements: ItemMeasurement[],
+  offset: number
+): number {
+  if (!measurements.length) return 0;
+
+  let low = 0;
+  let high = measurements.length - 1;
+  let match = measurements.length - 1;
+
+  while (low <= high) {
+    const middle = Math.floor((low + high) / 2);
+    const measurement = measurements[middle];
+
+    if (measurement.end > offset) {
+      match = middle;
+      high = middle - 1;
+    } else {
+      low = middle + 1;
+    }
+  }
+
+  return match;
+}
+
+export function calculateVisibleRange({
+  measurements,
+  scrollTop,
+  height,
+  overscan,
+}: {
+  measurements: ItemMeasurement[];
+  scrollTop: number;
+  height: number;
+  overscan: number;
+}): VisibleRange {
+  if (!measurements.length) {
+    return { start: 0, end: -1 };
+  }
+
+  const viewBottom = scrollTop + height;
+  const firstVisible = findFirstVisibleIndex(measurements, scrollTop);
+  let lastVisibleExclusive = firstVisible;
+
+  while (
+    lastVisibleExclusive < measurements.length &&
+    measurements[lastVisibleExclusive].start < viewBottom
+  ) {
+    lastVisibleExclusive += 1;
+  }
+
+  const lastVisible = Math.max(
+    firstVisible,
+    Math.min(measurements.length - 1, lastVisibleExclusive - 1)
+  );
+  const overscanCount = Math.max(0, Math.floor(overscan));
+
+  return {
+    start: Math.max(0, firstVisible - overscanCount),
+    end: Math.min(measurements.length - 1, lastVisible + overscanCount),
+  };
+}
+
+export type VirtualizedProps = {
+  height: number;
+  itemCount: number;
+  getItemHeight: (index: number) => number;
+  renderItem: VirtualizedRenderItem;
+  overscan?: number;
+  className?: string;
+  style?: CSSProperties;
+  innerClassName?: string;
+  innerStyle?: CSSProperties;
+  onScroll?: (scrollTop: number) => void;
+  itemKey?: (index: number) => string | number;
+  initialScrollOffset?: number;
+  /**
+   * When true (default) we flush scroll updates with `flushSync`
+   * to avoid visual gaps during fast scrolling.
+   */
+  syncScrollUpdates?: boolean;
+  /**
+   * Optional padding applied above and below the content. Numbers apply to both.
+   */
+  padding?: VirtualizedPadding;
+  /**
+   * Optional constant gap inserted between items.
+   */
+  gap?: number;
+  /**
+   * Render content inside ScrollArea2 instead of a plain div.
+   */
+  useScrollArea?: boolean;
+  /**
+   * Optional class applied to the ScrollArea viewport when `useScrollArea` is true.
+   */
+  scrollAreaViewportClassName?: string;
+};
+
+const DEFAULT_OVERSCAN = 2;
+
+const VirtualizedInner = React.forwardRef(function Virtualized(
+  {
+    height,
+    itemCount,
+    getItemHeight,
+    renderItem,
+    overscan = DEFAULT_OVERSCAN,
+    className,
+    style,
+    innerClassName,
+    innerStyle,
+    onScroll,
+    itemKey,
+    initialScrollOffset = 0,
+    syncScrollUpdates = true,
+    padding,
+    gap = 0,
+    useScrollArea = false,
+    scrollAreaViewportClassName,
+  }: VirtualizedProps,
+  forwardedRef: ForwardedRef<IVirtualizedList>
+) {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const setScrollElement = useCallback((element: HTMLDivElement | null) => {
+    containerRef.current = element;
+  }, []);
+  const [scrollTop, setScrollTop] = useState(initialScrollOffset);
+  const pendingInitialOffset = useRef<number | null>(initialScrollOffset);
+
+  useLayoutEffect(() => {
+    if (pendingInitialOffset.current == null) return;
+    if (containerRef.current) {
+      containerRef.current.scrollTop = pendingInitialOffset.current;
+      setScrollTop(pendingInitialOffset.current);
+    }
+    pendingInitialOffset.current = null;
+  }, []);
+
+  const paddingValues = useMemo(() => resolvePaddingValues(padding), [padding]);
+
+  const gapValue = useMemo(() => clampGapValue(gap), [gap]);
+
+  const { measurements, totalHeight } = useMemo(
+    () =>
+      buildMeasurements({
+        itemCount,
+        getItemHeight,
+        paddingTop: paddingValues.top,
+        paddingBottom: paddingValues.bottom,
+        gap: gapValue,
+      }),
+    [
+      gapValue,
+      getItemHeight,
+      itemCount,
+      paddingValues.bottom,
+      paddingValues.top,
+    ]
+  );
+
+  const visibleRange = useMemo(
+    () =>
+      calculateVisibleRange({
+        measurements,
+        scrollTop,
+        height,
+        overscan,
+      }),
+    [height, measurements, overscan, scrollTop]
+  );
+
+  const handleScroll = useCallback<UIEventHandler<HTMLDivElement>>(
+    (event) => {
+      const nextOffset = event.currentTarget.scrollTop;
+
+      if (nextOffset === scrollTop) return;
+
+      if (syncScrollUpdates) {
+        flushSync(() => {
+          setScrollTop(nextOffset);
+        });
+      } else {
+        setScrollTop(nextOffset);
+      }
+      onScroll?.(nextOffset);
+    },
+    [onScroll, scrollTop, syncScrollUpdates]
+  );
+
+  useImperativeHandle(
+    forwardedRef,
+    () => ({
+      scrollToIndex(index: number) {
+        const container = containerRef.current;
+        if (!container) return;
+
+        const nextScrollTop = calculateScrollOffsetForIndex({
+          measurements,
+          height,
+          totalHeight,
+          targetIndex: index,
+          currentScrollTop: container.scrollTop,
+        });
+
+        if (nextScrollTop == null) return;
+
+        container.scrollTop = nextScrollTop;
+        setScrollTop(nextScrollTop);
+      },
+    }),
+    [height, measurements, totalHeight]
+  );
+
+  const containerStyle = useMemo<CSSProperties>(
+    () => ({
+      height,
+      overflowY: "auto",
+      overflowX: "hidden",
+      ...style,
+    }),
+    [height, style]
+  );
+
+  const scrollAreaStyle = useMemo<CSSProperties>(
+    () => ({
+      height,
+      ...style,
+    }),
+    [height, style]
+  );
+
+  const totalContent = (
+    <div
+      className={innerClassName}
+      style={{
+        position: "relative",
+        width: "100%",
+        height: totalHeight,
+        ...innerStyle,
+      }}
+    >
+      {visibleRange.end >= visibleRange.start &&
+        Array.from(
+          { length: visibleRange.end - visibleRange.start + 1 },
+          (_, offset) => {
+            const index = visibleRange.start + offset;
+            const measurement = measurements[index];
+            const key = itemKey ? itemKey(index) : index;
+
+            return (
+              <div
+                key={key}
+                style={{
+                  position: "absolute",
+                  top: measurement.start,
+                  height: measurement.size,
+                  width: "100%",
+                }}
+              >
+                {renderItem(index)}
+              </div>
+            );
+          }
+        )}
+    </div>
+  );
+
+  if (useScrollArea) {
+    return (
+      <ScrollArea2
+        className={className}
+        style={scrollAreaStyle}
+        viewportClassName={scrollAreaViewportClassName}
+        viewportProps={{
+          ref: setScrollElement,
+          onScroll: handleScroll,
+        }}
+      >
+        {totalContent}
+      </ScrollArea2>
+    );
+  }
+
+  return (
+    <div
+      ref={setScrollElement}
+      className={className}
+      style={containerStyle}
+      onScroll={handleScroll}
+    >
+      {totalContent}
+    </div>
+  );
+});
+
+export const Virtualized = React.memo(VirtualizedInner);

package/src/components/__tests__/Virtualized.math.test.ts

@@ -0,0 +1,153 @@
+import { expect, test } from "bun:test";
+import {
+  buildMeasurements,
+  calculateScrollOffsetForIndex,
+  calculateVisibleRange,
+  clampGapValue,
+  findFirstVisibleIndex,
+  ItemMeasurement,
+  resolvePaddingValues,
+} from "../Virtualized";
+
+test("resolvePaddingValues handles numbers and objects", () => {
+  expect(resolvePaddingValues(8)).toEqual({ top: 8, bottom: 8 });
+  expect(resolvePaddingValues({ top: 4 })).toEqual({ top: 4, bottom: 0 });
+  expect(resolvePaddingValues(undefined)).toEqual({ top: 0, bottom: 0 });
+});
+
+test("clampGapValue avoids negatives", () => {
+  expect(clampGapValue(undefined)).toBe(0);
+  expect(clampGapValue(-10)).toBe(0);
+  expect(clampGapValue(6)).toBe(6);
+});
+
+test("buildMeasurements returns cumulative offsets and total height", () => {
+  const { measurements, totalHeight } = buildMeasurements({
+    itemCount: 3,
+    getItemHeight: (index) => 10 + index,
+    paddingTop: 5,
+    paddingBottom: 15,
+    gap: 4,
+  });
+
+  expect(measurements).toEqual([
+    { index: 0, size: 10, start: 5, end: 15 },
+    { index: 1, size: 11, start: 19, end: 30 },
+    { index: 2, size: 12, start: 34, end: 46 },
+  ]);
+  expect(totalHeight).toBe(61);
+});
+
+test("findFirstVisibleIndex binary searches measurement offsets", () => {
+  const measurements = [
+    { index: 0, size: 10, start: 0, end: 10 },
+    { index: 1, size: 10, start: 10, end: 20 },
+    { index: 2, size: 10, start: 20, end: 30 },
+  ];
+
+  expect(findFirstVisibleIndex(measurements, 0)).toBe(0);
+  expect(findFirstVisibleIndex(measurements, 5)).toBe(0);
+  expect(findFirstVisibleIndex(measurements, 10)).toBe(1);
+  expect(findFirstVisibleIndex(measurements, 25)).toBe(2);
+});
+
+test("calculateVisibleRange respects overscan and height", () => {
+  const measurements = [
+    { index: 0, size: 10, start: 0, end: 10 },
+    { index: 1, size: 10, start: 10, end: 20 },
+    { index: 2, size: 10, start: 20, end: 30 },
+    { index: 3, size: 10, start: 30, end: 40 },
+    { index: 4, size: 10, start: 40, end: 50 },
+  ];
+
+  const visible = calculateVisibleRange({
+    measurements,
+    scrollTop: 12,
+    height: 20,
+    overscan: 1,
+  });
+
+  expect(visible).toEqual({ start: 0, end: 4 });
+});
+
+const sampleMeasurements: ItemMeasurement[] = [
+  { index: 0, size: 30, start: 0, end: 30 },
+  { index: 1, size: 30, start: 30, end: 60 },
+  { index: 2, size: 30, start: 60, end: 90 },
+  { index: 3, size: 30, start: 90, end: 120 },
+];
+
+const extendedMeasurements: ItemMeasurement[] = [
+  { index: 0, size: 30, start: 0, end: 30 },
+  { index: 1, size: 30, start: 30, end: 60 },
+  { index: 2, size: 30, start: 60, end: 90 },
+  { index: 3, size: 30, start: 90, end: 120 },
+  { index: 4, size: 30, start: 120, end: 150 },
+  { index: 5, size: 30, start: 150, end: 180 },
+  { index: 6, size: 30, start: 180, end: 210 },
+];
+
+test("calculateScrollOffsetForIndex returns undefined when already visible", () => {
+  const offset = calculateScrollOffsetForIndex({
+    measurements: sampleMeasurements,
+    height: 60,
+    totalHeight: 120,
+    targetIndex: 1,
+    currentScrollTop: 30,
+  });
+
+  expect(offset).toBeUndefined();
+});
+
+test("calculateScrollOffsetForIndex scrolls up when item above viewport", () => {
+  const offset = calculateScrollOffsetForIndex({
+    measurements: sampleMeasurements,
+    height: 60,
+    totalHeight: 120,
+    targetIndex: 0,
+    currentScrollTop: 50,
+  });
+
+  expect(offset).toBe(0);
+});
+
+test("calculateScrollOffsetForIndex scrolls down when item below viewport", () => {
+  const offset = calculateScrollOffsetForIndex({
+    measurements: extendedMeasurements,
+    height: 60,
+    totalHeight: 210,
+    targetIndex: 4,
+    currentScrollTop: 0,
+  });
+
+  expect(offset).toBe(120);
+});
+
+test("calculateScrollOffsetForIndex clamps to end of content", () => {
+  const offset = calculateScrollOffsetForIndex({
+    measurements: sampleMeasurements,
+    height: 80,
+    totalHeight: 120,
+    targetIndex: 3,
+    currentScrollTop: 10,
+  });
+
+  expect(offset).toBe(40);
+});
+
+test("calculateScrollOffsetForIndex aligns bottom when item taller than viewport", () => {
+  const tallMeasurements: ItemMeasurement[] = [
+    { index: 0, size: 120, start: 0, end: 120 },
+    { index: 1, size: 120, start: 120, end: 240 },
+  ];
+
+  const offset = calculateScrollOffsetForIndex({
+    measurements: tallMeasurements,
+    height: 60,
+    totalHeight: 240,
+    targetIndex: 1,
+    currentScrollTop: 0,
+  });
+
+  expect(offset).toBe(180);
+});

package/src/components/__tests__/Virtualized.test.tsx

@@ -0,0 +1,85 @@
+import { act, render } from "@testing-library/react";
+import { expect, test } from "bun:test";
+import React from "react";
+import { Virtualized } from "../Virtualized";
+
+test("virtualized window updates visible rows when scrolling", () => {
+  const items = Array.from({ length: 100 }, (_, index) => `Row ${index + 1}`);
+
+  const { container, getByTestId, queryByTestId } = render(
+    <Virtualized
+      height={100}
+      itemCount={items.length}
+      getItemHeight={() => 20}
+      renderItem={(index) => (
+        <div data-testid={`row-${index}`}>{items[index]}</div>
+      )}
+    />
+  );
+
+  const scroller = container.firstChild as HTMLDivElement;
+
+  expect(getByTestId("row-0")).toBeTruthy();
+
+  act(() => {
+    scroller.scrollTop = 200;
+    scroller.dispatchEvent(new Event("scroll"));
+  });
+
+  expect(queryByTestId("row-0")).toBeNull();
+  expect(getByTestId("row-10")).toBeTruthy();
+});
+
+test("accounts for padding and gap", () => {
+  const { container } = render(
+    <Virtualized
+      height={120}
+      itemCount={2}
+      getItemHeight={() => 20}
+      padding={{ top: 12, bottom: 8 }}
+      gap={6}
+      renderItem={(index) => <div>Row {index}</div>}
+    />
+  );
+
+  const scroller = container.firstChild as HTMLDivElement;
+  const inner = scroller.firstChild as HTMLDivElement;
+  const firstRow = inner.firstChild as HTMLDivElement;
+  const secondRow = firstRow.nextSibling as HTMLDivElement;
+
+  expect(inner.style.height).toBe("66px");
+  expect(firstRow.style.top).toBe("12px");
+  expect(secondRow.style.top).toBe("38px");
+});
+
+test("supports ScrollArea as the scroller", () => {
+  const items = Array.from({ length: 50 }, (_, index) => `Row ${index + 1}`);
+
+  const { container, getByTestId, queryByTestId } = render(
+    <Virtualized
+      height={120}
+      itemCount={items.length}
+      getItemHeight={() => 20}
+      useScrollArea
+      scrollAreaViewportClassName="virtualized-scrollarea-viewport"
+      renderItem={(index) => (
+        <div data-testid={`scroll-row-${index}`}>{items[index]}</div>
+      )}
+    />
+  );
+
+  const viewport = container.querySelector(
+    ".virtualized-scrollarea-viewport"
+  ) as HTMLDivElement;
+
+  expect(viewport).toBeTruthy();
+  expect(getByTestId("scroll-row-0")).toBeTruthy();
+
+  act(() => {
+    viewport.scrollTop = 200;
+    viewport.dispatchEvent(new Event("scroll"));
+  });
+
+  expect(queryByTestId("scroll-row-0")).toBeNull();
+  expect(getByTestId("scroll-row-10")).toBeTruthy();
+});

package/src/components/listView/ListViewContexts.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { createContext, ReactNode } from "react";
+import { createContext } from "react";
 import {
   ListColorScheme,
   ListRowMarginType,
@@ -61,8 +61,3 @@ export const ListRowContext = createContext<ListRowContextValue>({
   isSectionHeader: false,
 });
 (ListRowContext as any).displayName = "ListRowContext";
-
-export const RenderItemContext = createContext<(index: number) => ReactNode>(
-  () => null
-);
-(RenderItemContext as any).displayName = "RenderItemContext";