@lotics/ui 1.9.0 → 1.11.0

package/src/kanban/kanban_column.tsx

@@ -0,0 +1,487 @@
+import React, { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  FlatList,
+  GestureResponderEvent,
+  LayoutChangeEvent,
+  ListRenderItem,
+  NativeScrollEvent,
+  NativeSyntheticEvent,
+  Pressable,
+  StyleSheet,
+  View,
+} from "react-native";
+import { colors } from "../colors";
+import {
+  KanbanItem,
+  KanbanRenderAddCardPlaceholderProps,
+  KanbanRenderInsertCardButtonProps,
+  KanbanRenderCardProps,
+  KanbanRenderCollapsedColumnProps,
+  KanbanRenderColumnHeaderProps,
+} from "./types";
+import { KanbanCard } from "./kanban_card";
+import { CardPlaceholder, ColumnPlaceholder } from "./placeholders";
+import { COLUMN_CONTENT_PADDING, DRAG_THRESHOLD } from "./constants";
+import type { ColumnRegistration } from "./kanban_board";
+
+// Memoized separator component to prevent re-renders
+const ItemSeparator = memo(function ItemSeparator({ height }: { height: number }) {
+  const style = useMemo(() => ({ height }), [height]);
+  return <View style={style} />;
+});
+
+// Memoized footer placeholder component
+const FooterPlaceholder = memo(function FooterPlaceholder({ height }: { height: number }) {
+  return <CardPlaceholder height={height} />;
+});
+
+// Stable key extractor (defined outside component to avoid recreation)
+const keyExtractor = <T,>(item: KanbanItem<T>) => item.id;
+
+interface KanbanColumnProps<T> {
+  columnKey: string;
+  title: string;
+  index: number;
+  items: KanbanItem<T>[];
+  renderCard: (props: KanbanRenderCardProps<T>) => React.ReactNode;
+  renderColumnHeader: (props: KanbanRenderColumnHeaderProps) => React.ReactNode;
+  renderAddCardPlaceholder: (props: KanbanRenderAddCardPlaceholderProps) => React.ReactNode;
+  renderInsertCardButton?: (props: KanbanRenderInsertCardButtonProps) => React.ReactNode;
+  renderCollapsedColumn: (props: KanbanRenderCollapsedColumnProps) => React.ReactNode;
+  isDragging: boolean;
+  isDropTarget: boolean;
+  /** True when any card is being dragged (disables insert zones) */
+  isDragInProgress: boolean;
+  cardDragId: string | null;
+  cardDropTargetIndex: number | null;
+  /** Height of the card being dragged (for placeholder sizing) */
+  draggedCardHeight: number | null;
+  /** Show full-column highlight when a card is being dropped (column-only mode) */
+  showCardDropHighlight: boolean;
+  columnWidth: number;
+  /** Width to use for drop target placeholder (matches dragged column's width) */
+  placeholderWidth: number;
+  /** Height to use for drop target placeholder (matches dragged column's height) */
+  placeholderHeight?: number;
+  itemHeight: number | ((item: T, index: number) => number);
+  itemGap: number;
+  onCardPress?: (cardId: string, item: T, columnKey: string) => void;
+  onAddCard?: (columnKey: string) => void;
+  onAddCardAtIndex?: (columnKey: string, index: number) => void;
+  startCardDrag: (
+    cardId: string,
+    columnKey: string,
+    index: number,
+    startX: number,
+    startY: number,
+    rect: { x: number; y: number; width: number; height: number },
+  ) => void;
+  startColumnDrag: (
+    columnKey: string,
+    index: number,
+    startX: number,
+    startY: number,
+    rect: { x: number; y: number; width: number; height: number },
+  ) => void;
+  registerColumn: (columnKey: string, data: ColumnRegistration | null) => void;
+  updateColumnScroll: (columnKey: string, scrollY: number) => void;
+  onPointerEnter: (columnKey: string) => void;
+  isMinimized: boolean;
+  onMinimizeToggle: (columnKey: string) => void;
+}
+
+function KanbanColumnInner<T>({
+  columnKey,
+  title,
+  index,
+  items,
+  renderCard,
+  renderColumnHeader,
+  renderAddCardPlaceholder,
+  renderInsertCardButton,
+  renderCollapsedColumn,
+  isDragging,
+  isDropTarget,
+  isDragInProgress,
+  cardDragId,
+  cardDropTargetIndex,
+  draggedCardHeight,
+  showCardDropHighlight,
+  columnWidth,
+  placeholderWidth,
+  placeholderHeight,
+  itemHeight,
+  itemGap,
+  onCardPress,
+  onAddCard,
+  onAddCardAtIndex,
+  startCardDrag,
+  startColumnDrag,
+  registerColumn,
+  updateColumnScroll,
+  onPointerEnter,
+  isMinimized,
+  onMinimizeToggle,
+}: KanbanColumnProps<T>) {
+  const containerRef = useRef<View>(null);
+  const listRef = useRef<FlatList>(null);
+  const headerHeightRef = useRef(0);
+
+  const cardDragIdRef = useRef(cardDragId);
+  const cardDropTargetIndexRef = useRef(cardDropTargetIndex);
+  const itemsLengthRef = useRef(items.length);
+  const draggedCardHeightRef = useRef(draggedCardHeight);
+
+  cardDragIdRef.current = cardDragId;
+  cardDropTargetIndexRef.current = cardDropTargetIndex;
+  itemsLengthRef.current = items.length;
+  draggedCardHeightRef.current = draggedCardHeight;
+
+  // Column drag threshold state (similar to card dragging)
+  const [isHeaderPressing, setIsHeaderPressing] = useState(false);
+  const headerPressStartRef = useRef<{ x: number; y: number } | null>(null);
+  const hasColumnDraggedRef = useRef(false);
+  const columnRectRef = useRef<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  } | null>(null);
+
+  const getHeight = useCallback(
+    (item: T, idx: number): number => {
+      return typeof itemHeight === "function" ? itemHeight(item, idx) : itemHeight;
+    },
+    [itemHeight],
+  );
+
+  useEffect(() => {
+    const element = containerRef.current as unknown as HTMLElement | null;
+    if (element && (listRef.current || isMinimized)) {
+      registerColumn(columnKey, {
+        element,
+        headerHeight: isMinimized ? 0 : headerHeightRef.current,
+        listRef: listRef.current, // null when minimized, FlatList when expanded
+      });
+    }
+    return () => registerColumn(columnKey, null);
+  }, [columnKey, registerColumn, isMinimized]);
+
+  const handleHeaderLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      headerHeightRef.current = event.nativeEvent.layout.height;
+      const element = containerRef.current as unknown as HTMLElement | null;
+      if (element && listRef.current) {
+        registerColumn(columnKey, {
+          element,
+          headerHeight: headerHeightRef.current,
+          listRef: listRef.current,
+        });
+      }
+    },
+    [columnKey, registerColumn],
+  );
+
+  // Handle column drag with threshold (same as cards)
+  useEffect(() => {
+    if (!isHeaderPressing) return;
+
+    const handleMouseMove = (e: MouseEvent) => {
+      if (!headerPressStartRef.current || hasColumnDraggedRef.current) return;
+
+      const dx = Math.abs(e.clientX - headerPressStartRef.current.x);
+      const dy = Math.abs(e.clientY - headerPressStartRef.current.y);
+
+      if (dx > DRAG_THRESHOLD || dy > DRAG_THRESHOLD) {
+        hasColumnDraggedRef.current = true;
+        if (columnRectRef.current) {
+          startColumnDrag(columnKey, index, e.clientX, e.clientY, columnRectRef.current);
+        }
+      }
+    };
+
+    const handleMouseUp = () => {
+      setIsHeaderPressing(false);
+      headerPressStartRef.current = null;
+      columnRectRef.current = null;
+    };
+
+    window.addEventListener("mousemove", handleMouseMove);
+    window.addEventListener("mouseup", handleMouseUp);
+
+    return () => {
+      window.removeEventListener("mousemove", handleMouseMove);
+      window.removeEventListener("mouseup", handleMouseUp);
+    };
+  }, [isHeaderPressing, columnKey, index, startColumnDrag]);
+
+  const handleHeaderPressIn = useCallback((event: GestureResponderEvent) => {
+    // Use clientX/clientY (viewport-relative) for consistency with mousemove events
+    const clientX = event.nativeEvent.pageX - window.scrollX;
+    const clientY = event.nativeEvent.pageY - window.scrollY;
+    headerPressStartRef.current = { x: clientX, y: clientY };
+    hasColumnDraggedRef.current = false;
+
+    const element = containerRef.current as unknown as HTMLElement | null;
+    if (element) {
+      const rect = element.getBoundingClientRect();
+      columnRectRef.current = rect;
+      setIsHeaderPressing(true);
+    }
+  }, []);
+
+  const handleScroll = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      updateColumnScroll(columnKey, event.nativeEvent.contentOffset.y);
+    },
+    [columnKey, updateColumnScroll],
+  );
+
+  const handlePointerEnter = useCallback(() => {
+    onPointerEnter(columnKey);
+  }, [columnKey, onPointerEnter]);
+
+  const handleMinimizeToggle = useCallback(() => {
+    onMinimizeToggle(columnKey);
+  }, [columnKey, onMinimizeToggle]);
+
+  const handleMinimizedPress = useCallback(() => {
+    onMinimizeToggle(columnKey);
+  }, [columnKey, onMinimizeToggle]);
+
+  const flatListGetItemLayout = useCallback(
+    (_: ArrayLike<KanbanItem<T>> | null | undefined, itemIndex: number) => {
+      if (typeof itemHeight === "number") {
+        return {
+          length: itemHeight,
+          offset: itemIndex * (itemHeight + itemGap),
+          index: itemIndex,
+        };
+      }
+      let offset = 0;
+      for (let i = 0; i < itemIndex; i++) {
+        offset += getHeight(items[i].data, i) + itemGap;
+      }
+      return {
+        length: getHeight(items[itemIndex]?.data, itemIndex),
+        offset,
+        index: itemIndex,
+      };
+    },
+    [items, itemHeight, itemGap, getHeight],
+  );
+
+  // O(1) lookup map for item id -> index
+  const itemIndexMap = useMemo(() => {
+    const map = new Map<string, number>();
+    items.forEach((item, idx) => map.set(item.id, idx));
+    return map;
+  }, [items]);
+
+  // Separator that hides when after dragged card that renders null
+  // When onAddCardAtIndex is provided, cards render their own gaps with insert zones
+  const renderSeparator = useCallback(
+    (props: { leadingItem: KanbanItem<T> | null }) => {
+      // When insert zones are enabled, cards render their own gaps
+      if (onAddCardAtIndex) {
+        return null;
+      }
+
+      if (!props.leadingItem) {
+        return <ItemSeparator height={itemGap} />;
+      }
+
+      const isLeadingDragging = cardDragIdRef.current === props.leadingItem.id;
+      const leadingIndex = itemIndexMap.get(props.leadingItem.id) ?? -1;
+
+      if (isLeadingDragging) {
+        // Dragged card renders null unless it's also the drop target
+        const isLeadingDropTarget = cardDropTargetIndexRef.current === leadingIndex;
+
+        // Skip separator after dragged card that renders null
+        if (!isLeadingDropTarget) {
+          return null;
+        }
+      }
+
+      return <ItemSeparator height={itemGap} />;
+    },
+    [itemGap, itemIndexMap, onAddCardAtIndex],
+  );
+
+  const renderItem: ListRenderItem<KanbanItem<T>> = useCallback(
+    ({ item, index: itemIndex }) => {
+      const isCardDragging = cardDragIdRef.current === item.id;
+      const isCardDropTarget = cardDropTargetIndexRef.current === itemIndex;
+      const height = getHeight(item.data, itemIndex);
+
+      return (
+        <KanbanCard
+          id={item.id}
+          columnKey={columnKey}
+          index={itemIndex}
+          item={item.data}
+          renderCard={renderCard}
+          isDragging={isCardDragging}
+          isDropTarget={isCardDropTarget}
+          isDragInProgress={isDragInProgress}
+          onCardPress={onCardPress}
+          onAddCardAtIndex={onAddCardAtIndex}
+          renderInsertCardButton={renderInsertCardButton}
+          startCardDrag={startCardDrag}
+          placeholderHeight={height}
+          // Only pass draggedCardHeight to drop target - prevents all cards from re-rendering
+          draggedCardHeight={isCardDropTarget ? draggedCardHeightRef.current : null}
+          itemGap={itemGap}
+        />
+      );
+    },
+    [
+      columnKey,
+      renderCard,
+      onCardPress,
+      onAddCardAtIndex,
+      renderInsertCardButton,
+      startCardDrag,
+      getHeight,
+      itemGap,
+      isDragInProgress,
+    ],
+  );
+
+  const handleAddCard = useCallback(() => {
+    onAddCard?.(columnKey);
+  }, [onAddCard, columnKey]);
+
+  // Stable footer renderer using memoized component
+  const renderFooter = useCallback(() => {
+    if (cardDropTargetIndexRef.current === null) return null;
+    if (cardDropTargetIndexRef.current !== itemsLengthRef.current) return null;
+
+    const height = draggedCardHeightRef.current ?? 60;
+    return <FooterPlaceholder height={height} />;
+  }, []);
+
+  // Tells FlatList when to re-render items (refs don't trigger re-renders)
+  const listExtraData = useMemo(
+    () => [cardDragId, cardDropTargetIndex, draggedCardHeight],
+    [cardDragId, cardDropTargetIndex, draggedCardHeight],
+  );
+
+  // Stable container styles
+  const containerStyle = useMemo(() => [styles.container, { width: columnWidth }], [columnWidth]);
+
+  // List content style - remove top padding when insert zones are enabled
+  // since first card renders its own gap
+  const listContentStyle = useMemo(
+    () => (onAddCardAtIndex ? [styles.listContent, { paddingTop: 0 }] : styles.listContent),
+    [onAddCardAtIndex],
+  );
+  const minimizedContainerStyle = useMemo(
+    () => ({ width: columnWidth, height: "100%" as const }),
+    [columnWidth],
+  );
+
+  if (isDragging) {
+    return isDropTarget ? (
+      <ColumnPlaceholder width={placeholderWidth} height={placeholderHeight} />
+    ) : null;
+  }
+
+  if (isMinimized) {
+    const showDropIndicator = showCardDropHighlight || cardDropTargetIndex !== null;
+
+    return (
+      <>
+        {isDropTarget && <ColumnPlaceholder width={placeholderWidth} height={placeholderHeight} />}
+        <View
+          ref={containerRef}
+          style={minimizedContainerStyle}
+          onPointerEnter={handlePointerEnter}
+        >
+          {renderCollapsedColumn({
+            columnKey,
+            title,
+            itemCount: items.length,
+            showDropIndicator,
+            onExpand: handleMinimizedPress,
+          })}
+        </View>
+      </>
+    );
+  }
+
+  return (
+    <>
+      {isDropTarget && <ColumnPlaceholder width={placeholderWidth} height={placeholderHeight} />}
+      <View ref={containerRef} style={containerStyle} onPointerEnter={handlePointerEnter}>
+        <Pressable onLayout={handleHeaderLayout} onPressIn={handleHeaderPressIn}>
+          {renderColumnHeader({
+            columnKey,
+            title,
+            itemCount: items.length,
+            isMinimized,
+            onMinimizeToggle: handleMinimizeToggle,
+          })}
+        </Pressable>
+        <FlatList
+          ref={listRef}
+          data={items}
+          extraData={listExtraData}
+          keyExtractor={keyExtractor}
+          renderItem={renderItem}
+          contentContainerStyle={listContentStyle}
+          ItemSeparatorComponent={renderSeparator}
+          ListFooterComponent={renderFooter}
+          showsVerticalScrollIndicator={true}
+          onScroll={handleScroll}
+          scrollEventThrottle={16}
+          getItemLayout={flatListGetItemLayout}
+          // Performance optimizations
+          removeClippedSubviews={false} // Keep false for smooth drag animations
+          maxToRenderPerBatch={10}
+          updateCellsBatchingPeriod={50}
+          windowSize={5} // Render 5 screens worth (enough for most columns)
+          initialNumToRender={15}
+        />
+        {onAddCard && (
+          <View style={styles.addCardFooter}>
+            {renderAddCardPlaceholder({
+              columnKey,
+              onPress: handleAddCard,
+            })}
+          </View>
+        )}
+        {showCardDropHighlight && <View style={styles.cardDropHighlight} />}
+      </View>
+    </>
+  );
+}
+
+export const KanbanColumn = memo(KanbanColumnInner) as typeof KanbanColumnInner;
+
+const styles = StyleSheet.create({
+  container: {
+    backgroundColor: colors.zinc[50],
+    borderRadius: 16,
+    maxHeight: "100%",
+  },
+  listContent: {
+    padding: COLUMN_CONTENT_PADDING,
+  },
+  addCardFooter: {
+    padding: COLUMN_CONTENT_PADDING,
+    paddingTop: 0,
+  },
+  cardDropHighlight: {
+    position: "absolute",
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    backgroundColor: colors.blue[100],
+    opacity: 0.5,
+    borderRadius: 8,
+    pointerEvents: "none",
+  },
+});

package/src/kanban/placeholders.tsx

@@ -0,0 +1,54 @@
+import React, { memo } from "react";
+import { StyleSheet, View } from "react-native";
+import { colors } from "../colors";
+
+interface CardPlaceholderProps {
+  height: number;
+}
+
+/**
+ * Placeholder shown when dragging a card to a new position
+ */
+export const CardPlaceholder = memo(function CardPlaceholder({ height }: CardPlaceholderProps) {
+  return <View style={[styles.cardPlaceholder, { height }]} />;
+});
+
+interface ColumnPlaceholderProps {
+  width: number;
+  height?: number;
+}
+
+/**
+ * Placeholder shown when dragging a column to a new position
+ */
+export const ColumnPlaceholder = memo(function ColumnPlaceholder({
+  width,
+  height,
+}: ColumnPlaceholderProps) {
+  return (
+    <View style={[styles.columnPlaceholder, { width, height }]}>
+      <View style={styles.columnPlaceholderContent} />
+    </View>
+  );
+});
+
+const styles = StyleSheet.create({
+  cardPlaceholder: {
+    backgroundColor: colors.blue[50],
+    borderRadius: 8,
+    borderWidth: 2,
+    borderColor: colors.blue[300],
+    boxSizing: "border-box",
+  },
+  columnPlaceholder: {
+    minHeight: 200,
+    backgroundColor: colors.blue[50],
+    borderRadius: 8,
+    borderWidth: 2,
+    borderColor: colors.blue[300],
+  },
+  columnPlaceholderContent: {
+    flex: 1,
+    minHeight: 100,
+  },
+});

package/src/kanban/types.ts

@@ -0,0 +1,116 @@
+/**
+ * Represents a single item/card in the Kanban board
+ */
+export interface KanbanItem<T = unknown> {
+  id: string;
+  data: T;
+}
+
+/**
+ * Represents a column in the Kanban board
+ */
+export interface KanbanColumn<T = unknown> {
+  key: string;
+  title: string;
+  items: KanbanItem<T>[];
+}
+
+/**
+ * Props passed to the renderCard function
+ */
+export interface KanbanRenderCardProps<T = unknown> {
+  item: T;
+  columnKey: string;
+  id: string;
+  hovered: boolean;
+  isDragging: boolean;
+}
+
+/**
+ * Props passed to the renderColumnHeader function
+ */
+export interface KanbanRenderColumnHeaderProps {
+  columnKey: string;
+  title: string;
+  itemCount: number;
+  isMinimized: boolean;
+  onMinimizeToggle: () => void;
+}
+
+/**
+ * Information about the current drag operation
+ */
+export interface DragInfo {
+  type: "card" | "column";
+  id: string;
+  sourceColumnKey: string;
+  sourceIndex: number;
+}
+
+/**
+ * Information about the current drop target
+ */
+export interface DropTarget {
+  type: "card" | "column";
+  columnKey: string;
+  index: number;
+}
+
+/**
+ * Drag preview dimensions and offset
+ */
+export interface DragPreviewInfo {
+  width: number;
+  height: number;
+  offsetX: number;
+  offsetY: number;
+}
+
+/**
+ * Result of a card move operation
+ */
+export interface CardMoveResult<T = unknown> {
+  cardId: string;
+  cardData: T;
+  sourceColumnKey: string;
+  sourceIndex: number;
+  targetColumnKey: string;
+  targetIndex: number;
+}
+
+/**
+ * Result of a column move operation
+ */
+export interface ColumnMoveResult {
+  columnKey: string;
+  sourceIndex: number;
+  targetIndex: number;
+}
+
+/**
+ * Props passed to the renderAddCardPlaceholder function
+ */
+export interface KanbanRenderAddCardPlaceholderProps {
+  columnKey: string;
+  onPress: () => void;
+}
+
+/**
+ * Props passed to the renderInsertCardButton function
+ */
+export interface KanbanRenderInsertCardButtonProps {
+  columnKey: string;
+  index: number;
+  onPress: () => void;
+}
+
+/**
+ * Props passed to the renderCollapsedColumn function
+ */
+export interface KanbanRenderCollapsedColumnProps {
+  columnKey: string;
+  title: string;
+  itemCount: number;
+  showDropIndicator: boolean;
+  onExpand: () => void;
+}