@multiplatform.one/components 7.10.0 → 7.15.0

package/src/views/TreeView.tsx

@@ -134,6 +134,10 @@ export interface TreeViewProps<T = unknown> extends Omit<YStackProps, "children"
   overscan?: number;
   /** Height of the scrollable container in pixels */
   height?: number;
+  /** Initial vertical offset in layout pixels, restored once after usable list layout. */
+  initialScrollOffset?: number;
+  /** Observed, bounded vertical offset. Does not report unacknowledged scroll commands. */
+  onScrollOffsetChange?: (offset: number) => void;
   /** Message shown when there are no nodes */
   emptyMessage?: string;
   /** Controlled expansion; takes precedence over initial expansion props. */
@@ -142,6 +146,8 @@ export interface TreeViewProps<T = unknown> extends Omit<YStackProps, "children"
   onExpandedIdsChange?: (ids: string[]) => void;
   /** Expand ancestors and reveal this row. Change requestId to reveal the same ID again. */
   revealRequest?: { id: string; requestId: number };
+  /** Called once when the current reveal target is measured, mounted and visible. */
+  onRevealComplete?: (request: { id: string; requestId: number }) => void;
   /** Initially expanded node IDs (wins over expandByDefault when provided) */
   defaultExpandedIds?: string[];
   /** Expand every branch on initial load */
@@ -298,11 +304,14 @@ export function TreeView<T = unknown>({
   estimateSize: estimateSizeProp,
   overscan = 10,
   height: heightProp,
+  initialScrollOffset,
+  onScrollOffsetChange,
   emptyMessage: emptyMessageProp,
   defaultExpandedIds,
   expandedIds: controlledExpandedIds,
   onExpandedIdsChange,
   revealRequest,
+  onRevealComplete,
   expandByDefault = false,
   display = "default",
   showExpansionArrows = true,
@@ -349,6 +358,31 @@ export function TreeView<T = unknown>({
   const treeId = useId();
   const containerRef = useRef<HTMLDivElement>(null);
   const flashListRef = useRef<FlashListRef<FlatNode<T>>>(null);
+  const initialScroll = useRef<
+    | {
+        offset: number;
+        attempted?: { target: number; width: number; height: number; contentHeight: number };
+      }
+    | undefined
+  >(
+    initialScrollOffset === undefined
+      ? undefined
+      : { offset: Number.isFinite(initialScrollOffset) ? Math.max(0, initialScrollOffset) : 0 },
+  );
+  const cancelInitialScroll = useCallback(() => {
+    initialScroll.current = undefined;
+  }, []);
+  const hasNodes = nodes.length > 0;
+  const listInstance = useMemo(
+    () => ({ hasNodes, attached: false, loaded: false, indexScrollRequested: false, offset: 0 }),
+    [hasNodes],
+  );
+  const scrollActive = useRef(true);
+  const lastReportedOffset = useRef<number | undefined>(undefined);
+  const offsetCallback = useRef(onScrollOffsetChange);
+  useLayoutEffect(() => {
+    offsetCallback.current = onScrollOffsetChange;
+  }, [onScrollOffsetChange]);
   const [focusedIndex, setFocusedIndex] = useState(-1);
   // LC-71: ring is a React flag, not a render-time wasKeyboardFocus() read —
   // Tab-away/Tab-back with the same activedescendant must still re-paint.
@@ -396,6 +430,7 @@ export function TreeView<T = unknown>({
 
   const toggleNode = useCallback(
     (node: TreeNode<T>) => {
+      cancelInitialScroll();
       const next = new Set(expandedIds);
       if (next.has(node.id)) {
         next.delete(node.id);
@@ -405,7 +440,7 @@ export function TreeView<T = unknown>({
       setExpandedIds(next);
       onNodeToggle?.(node);
     },
-    [expandedIds, setExpandedIds, onNodeToggle],
+    [expandedIds, setExpandedIds, onNodeToggle, cancelInitialScroll],
   );
 
   const previousExpandedIds = useRef(expandedIds);
@@ -470,16 +505,98 @@ export function TreeView<T = unknown>({
       }
     | undefined
   >(undefined);
-  const revealFrame = useRef<number | undefined>(undefined);
-  const revealStep = useRef<() => void>(() => {});
+  const scrollFrame = useRef<number | undefined>(undefined);
+  const scrollStep = useRef<() => void>(() => {});
   const renderedRows = useRef(new Set<string>());
-  const scheduleReveal = useCallback(() => {
-    if (!revealIntent.current || revealIntent.current.complete || revealFrame.current !== undefined)
+  const scrollBounds = useCallback(() => {
+    const list = flashListRef.current;
+    if (!scrollActive.current || !listInstance.attached || !listInstance.loaded || !list) return;
+    if (isWeb) {
+      const rect = containerRef.current?.getBoundingClientRect();
+      if (!rect || !(rect.width > 0) || !(rect.height > 0)) return;
+    }
+    const viewport = list.getWindowSize();
+    const contentHeight = list.getChildContainerDimensions().height + list.getFirstItemOffset();
+    if (
+      !Number.isFinite(viewport.width) ||
+      viewport.width <= 0 ||
+      !Number.isFinite(viewport.height) ||
+      viewport.height <= 0 ||
+      !Number.isFinite(contentHeight) ||
+      contentHeight <= 0
+    )
+      return;
+    return {
+      list,
+      width: viewport.width,
+      height: viewport.height,
+      contentHeight,
+      maxOffset: Math.max(0, contentHeight - viewport.height),
+    };
+  }, [listInstance]);
+  const observeOffset = useCallback(
+    (offset: number, fromEvent = false) => {
+      if (!scrollActive.current || !listInstance.attached || !Number.isFinite(offset)) return;
+      if (
+        fromEvent &&
+        initialScroll.current?.attempted === undefined &&
+        offset !== listInstance.offset
+      ) {
+        cancelInitialScroll();
+      }
+      listInstance.offset = offset;
+      const bounds = scrollBounds();
+      if (!bounds) return;
+      const bounded = Math.max(0, Math.min(offset, bounds.maxOffset));
+      const initial = initialScroll.current;
+      if (initial) {
+        const target = Math.min(initial.offset, bounds.maxOffset);
+        if (initial.attempted ? Math.abs(bounded - target) >= 1 : bounded !== target) return;
+        initialScroll.current = undefined;
+      }
+      if (offsetCallback.current && lastReportedOffset.current !== bounded) {
+        lastReportedOffset.current = bounded;
+        offsetCallback.current(bounded);
+      }
+    },
+    [cancelInitialScroll, scrollBounds, listInstance],
+  );
+  const scheduleScroll = useCallback(() => {
+    if (!scrollActive.current || !listInstance.attached || scrollFrame.current !== undefined)
       return;
-    revealFrame.current = requestAnimationFrame(() => {
-      revealFrame.current = undefined;
-      revealStep.current();
+    if (
+      !initialScroll.current &&
+      (!revealIntent.current || revealIntent.current.complete) &&
+      !offsetCallback.current
+    )
+      return;
+    scrollFrame.current = requestAnimationFrame(() => {
+      scrollFrame.current = undefined;
+      if (listInstance.attached) scrollStep.current();
     });
+  }, [listInstance]);
+  const attachList = useCallback(
+    (list: FlashListRef<FlatNode<T>> | null) => {
+      flashListRef.current = list;
+      listInstance.attached = list !== null;
+      if (!list) {
+        listInstance.loaded = false;
+        if (initialScroll.current) initialScroll.current.attempted = undefined;
+        if (scrollFrame.current !== undefined) cancelAnimationFrame(scrollFrame.current);
+        scrollFrame.current = undefined;
+      }
+    },
+    [listInstance],
+  );
+
+  useLayoutEffect(() => {
+    scrollActive.current = true;
+    return () => {
+      scrollActive.current = false;
+      revealIntent.current = undefined;
+      if (scrollFrame.current !== undefined) cancelAnimationFrame(scrollFrame.current);
+      scrollFrame.current = undefined;
+    };
   }, []);
 
   useLayoutEffect(() => {
@@ -489,11 +606,49 @@ export function TreeView<T = unknown>({
       revealIntent.current?.id !== revealRequest.id ||
       revealIntent.current?.requestId !== revealRequest.requestId
     ) {
+      cancelInitialScroll();
       revealIntent.current = { ...revealRequest, complete: false };
     }
-    revealStep.current = () => {
+    const step = () => {
+      const currentList = flashListRef.current;
+      if (currentList) {
+        // Index preparation changes FlashList's getter before transport completes.
+        // Once requested, only delivered events can advance this list's observation.
+        observeOffset(
+          listInstance.indexScrollRequested
+            ? listInstance.offset
+            : currentList.getAbsoluteLastScrollOffset(),
+        );
+      }
+      if (!scrollActive.current) return;
+      if (scrollStep.current !== step) {
+        scheduleScroll();
+        return;
+      }
       const intent = revealIntent.current;
-      if (!intent || intent.complete) return;
+      if (!intent || intent.complete) {
+        const initial = initialScroll.current;
+        const bounds = scrollBounds();
+        if (!initial || !bounds || flatNodes.length === 0) return;
+        const target = Math.min(initial.offset, bounds.maxOffset);
+        const attempted = initial.attempted;
+        if (
+          !attempted ||
+          attempted.target !== target ||
+          attempted.width !== bounds.width ||
+          attempted.height !== bounds.height ||
+          attempted.contentHeight !== bounds.contentHeight
+        ) {
+          initial.attempted = {
+            target,
+            width: bounds.width,
+            height: bounds.height,
+            contentHeight: bounds.contentHeight,
+          };
+          bounds.list.scrollToOffset({ offset: target, animated: false });
+        }
+        return;
+      }
       const next = treeRevealExpansion(nodes, expandedIds, intent.id);
       if (!next) return;
       if (next !== expandedIds) {
@@ -519,29 +674,39 @@ export function TreeView<T = unknown>({
       if (viewport.width <= 0) return;
       const layout = list.getLayout(index);
       if (!layout) return;
-      const offset = list.getAbsoluteLastScrollOffset();
+      const offset = listInstance.indexScrollRequested
+        ? listInstance.offset
+        : list.getAbsoluteLastScrollOffset();
+      const top = layout.y + list.getFirstItemOffset();
       const nextOffset = treeRevealOffset(
-        { y: layout.y + list.getFirstItemOffset(), height: layout.height },
+        { y: top, height: layout.height },
         offset,
         viewport.height,
       );
       if (nextOffset === undefined) return;
       if (Math.abs(nextOffset - offset) < 1) {
-        const visible = list.computeVisibleIndices();
+        let visible = top < offset + viewport.height && top + layout.height > offset;
+        if (!listInstance.indexScrollRequested) {
+          const range = list.computeVisibleIndices();
+          visible = visible && index >= range.startIndex && index <= range.endIndex;
+        }
         if (
+          revealIntent.current === intent &&
           layout.isHeightMeasured &&
           renderedRows.current.has(intent.id) &&
-          index >= visible.startIndex &&
-          index <= visible.endIndex
-        )
+          visible
+        ) {
           intent.complete = true;
+          onRevealComplete?.({ id: intent.id, requestId: intent.requestId });
+        }
         return;
       }
       // FlashList's scrollToIndex has uncancellable delayed steps. Immediate offsets
       // let the next layout/scroll event correct estimates using only the latest intent.
       list.scrollToOffset({ offset: nextOffset, animated: false });
     };
-    scheduleReveal();
+    scrollStep.current = step;
+    scheduleScroll();
   }, [
     nodes,
     expandedIds,
@@ -549,27 +714,25 @@ export function TreeView<T = unknown>({
     flatNodes,
     revealRequest?.id,
     revealRequest?.requestId,
+    onRevealComplete,
     height,
     motion,
-    scheduleReveal,
+    scheduleScroll,
+    cancelInitialScroll,
+    observeOffset,
+    scrollBounds,
+    listInstance,
   ]);
 
-  useLayoutEffect(
-    () => () => {
-      revealIntent.current = undefined;
-      if (revealFrame.current !== undefined) cancelAnimationFrame(revealFrame.current);
-      revealFrame.current = undefined;
-    },
-    [],
-  );
-
   const scrollToIndex = useCallback(
     (index: number) => {
       if (index >= 0 && index < flatNodes.length) {
+        cancelInitialScroll();
+        listInstance.indexScrollRequested = true;
         flashListRef.current?.scrollToIndex({ index, animated: true });
       }
     },
-    [flatNodes.length],
+    [flatNodes.length, cancelInitialScroll, listInstance],
   );
 
   const focusRow = useCallback(
@@ -863,6 +1026,7 @@ export function TreeView<T = unknown>({
       if (!container?.getBoundingClientRect) return false;
       const session = treeKeyboardLift(nodes, flat.node.id);
       if (!session) return false;
+      cancelInitialScroll();
       const rowRect = rowEl.getBoundingClientRect();
       const containerRect = container.getBoundingClientRect();
       grabOffsetRef.current = { x: clientX - rowRect.left, y: clientY - rowRect.top };
@@ -890,7 +1054,7 @@ export function TreeView<T = unknown>({
       startAutoScroll();
       return true;
     },
-    [announce, nodes, startAutoScroll],
+    [announce, nodes, startAutoScroll, cancelInitialScroll],
   );
 
   const handleDragHandlePointerDown = useCallback(
@@ -1037,6 +1201,7 @@ export function TreeView<T = unknown>({
     if (!flat) return false;
     const session = treeKeyboardLift(nodes, flat.node.id);
     if (!session) return false;
+    cancelInitialScroll();
     const ui: TreeDragUi<T> = {
       mode: "keyboard",
       node: flat.node,
@@ -1054,7 +1219,16 @@ export function TreeView<T = unknown>({
     dragUiRef.current = ui;
     announce(describeTreeDragState("lift", session, nodes, flat.node.label));
     return true;
-  }, [announce, canReorder, dndRows, flatNodes, focusedIndex, getRowHeight, nodes]);
+  }, [
+    announce,
+    canReorder,
+    dndRows,
+    flatNodes,
+    focusedIndex,
+    getRowHeight,
+    nodes,
+    cancelInitialScroll,
+  ]);
 
   const moveKeyboardDrag = useCallback(
     (direction: "up" | "down" | "left" | "right"): boolean => {
@@ -1284,21 +1458,28 @@ export function TreeView<T = unknown>({
         onFocus={handleContainerFocus}
         onBlur={handleContainerBlur}
         onKeyDown={handleTreeKeyDown}
-        onLayout={revealRequest ? scheduleReveal : undefined}
+        onLayout={scheduleScroll}
+        {...(isWeb && { onWheel: cancelInitialScroll, onPointerDown: cancelInitialScroll })}
         position="relative"
         style={{
           height,
         }}
       >
         <FlashList
-          ref={flashListRef}
+          ref={attachList}
           data={flatNodes}
           drawDistance={overscan * estimateSize}
           keyExtractor={(item) => item.node.id}
-          {...(revealRequest && {
-            onLoad: scheduleReveal,
-            onCommitLayoutEffect: scheduleReveal,
-          })}
+          onLoad={() => {
+            if (!scrollActive.current || !listInstance.attached) return;
+            listInstance.loaded = true;
+            scheduleScroll();
+          }}
+          onCommitLayoutEffect={scheduleScroll}
+          onContentSizeChange={scheduleScroll}
+          onScrollBeginDrag={() => {
+            if (scrollActive.current && listInstance.attached) cancelInitialScroll();
+          }}
           extraData={{
             focused: effectiveFocused,
             selectedId,
@@ -1309,17 +1490,17 @@ export function TreeView<T = unknown>({
             keyboardRing,
             collapsedSelectedAncestors,
           }}
-          {...((canReorder || revealRequest) && {
-            onScroll: (e: any) => {
-              const y = e?.nativeEvent?.contentOffset?.y;
-              if (typeof y === "number") {
-                scrollOffsetRef.current = y;
-                if (dragUiRef.current) setDragScrollY(y);
-              }
-              scheduleReveal();
-            },
-            scrollEventThrottle: 16,
-          })}
+          onScroll={(e: any) => {
+            if (!scrollActive.current || !listInstance.attached) return;
+            const y = e?.nativeEvent?.contentOffset?.y;
+            if (typeof y === "number" && Number.isFinite(y)) {
+              scrollOffsetRef.current = y;
+              if (dragUiRef.current) setDragScrollY(y);
+              observeOffset(y, true);
+            }
+            scheduleScroll();
+          }}
+          scrollEventThrottle={16}
           renderItem={({ item, index }) => {
             const { node, depth, hasChildren, isExpanded } = item;
             const isFocused = effectiveFocused === index;
@@ -1379,7 +1560,7 @@ export function TreeView<T = unknown>({
                 ref={(row) => {
                   if (row) renderedRows.current.add(node.id);
                   else renderedRows.current.delete(node.id);
-                  scheduleReveal();
+                  scheduleScroll();
                 }}
                 id={`${treeId}-node-${index}`}
                 {...{ "data-treeview-row": node.id }}
@@ -1407,7 +1588,7 @@ export function TreeView<T = unknown>({
                 onLayout={(e: any) => {
                   const h = e?.nativeEvent?.layout?.height;
                   if (typeof h === "number" && h > 0) rowHeights.current.set(node.id, h);
-                  scheduleReveal();
+                  scheduleScroll();
                 }}
                 backgroundColor={
                   // Nest-into parent highlight wins while a drag is active

package/src/views/ganttMath.ts

@@ -127,14 +127,16 @@ export interface GanttRange {
   end: Date;
 }
 
-function startOfWeek(date: Date, firstDayOfWeek: 0 | 1): Date {
+/** Local start of the week containing `date` (`firstDayOfWeek`: 0 = Sunday, 1 = Monday). */
+export function startOfWeek(date: Date, firstDayOfWeek: 0 | 1): Date {
   const day = startOfDay(date);
   let offset = day.getDay() - firstDayOfWeek;
   if (offset < 0) offset += 7;
   return addDays(day, -offset);
 }
 
-function startOfMonth(date: Date): Date {
+/** Local first of the month containing `date`. */
+export function startOfMonth(date: Date): Date {
   return new Date(date.getFullYear(), date.getMonth(), 1);
 }
 

package/src/views/index.ts

@@ -130,6 +130,8 @@ export {
   shiftSpanByDays,
   spanInclusiveDays,
   startOfDay,
+  startOfMonth,
+  startOfWeek,
   todayLineX,
   xToDate,
   type GanttBarGeometry,
@@ -141,6 +143,34 @@ export {
   type GanttTick,
   type GanttZoom,
 } from "./ganttMath";
+export {
+  MatrixView,
+  type MatrixViewProps,
+  type MatrixRow,
+  type MatrixCellRef,
+  type MatrixLegendItem,
+} from "./Matrix";
+// matrixMath is surfaced whole for the same reason ganttMath is: pure bucket
+// math a consumer laying out its own grid on the same axis needs unchanged.
+export {
+  alignMatrixRange,
+  bucketName,
+  bucketStart,
+  computeMatrixRange,
+  generateBuckets,
+  localDateKey,
+  matrixCellIntensity,
+  matrixCellKey,
+  matrixMaxValue,
+  nextBucketStart,
+  summarizeMatrixCells,
+  type MatrixBucket,
+  type MatrixBucketRule,
+  type MatrixCell,
+  type MatrixCellSummary,
+  type MatrixIntent,
+  type MatrixRange,
+} from "./matrixMath";
 // Kanban drag maths. Only the helper other packages consume is surfaced, in
 // keeping with this barrel's curated style: @multiplatform.one/table's
 // ChildTable imports renumberIdx to renumber rows after a reorder, and failed