@purpurds/table 8.3.1 → 8.5.0

package/src/use-drag-handle.hook.tsx

@@ -0,0 +1,60 @@
+import React, { useState } from "react";
+import { IconDragHorizontal } from "@purpurds/icon/drag-horizontal";
+import c from "classnames/bind";
+
+import styles from "./table.module.scss";
+
+const cx = c.bind(styles);
+const rootClassName = "purpur-table-column-header-cell";
+
+export function useDragHandle() {
+  const [mouseDownActive, setMouseDownActive] = useState(false);
+
+  const handleMouseDown = () => {
+    setMouseDownActive(true);
+    window.addEventListener("mouseup", handleMouseUp, { once: true });
+  };
+
+  const handleMouseUp = () => {
+    setMouseDownActive(false);
+  };
+
+  return { mouseDownActive, handleMouseDown };
+}
+
+export type TableColumnDragHandleProps = {
+  onMouseDown: () => void;
+  overlayActive?: boolean;
+  isFirstColumn: boolean;
+  isLastColumn: boolean;
+  columnDragAriaLabel: string;
+};
+
+export function TableColumnDragHandle({
+  onMouseDown,
+  overlayActive,
+  isFirstColumn,
+  isLastColumn,
+  columnDragAriaLabel,
+}: TableColumnDragHandleProps) {
+  return (
+    <div
+      className={cx(`${rootClassName}__drag-handle`, {
+        [`${rootClassName}__border-radius-first-cell`]: isFirstColumn && !overlayActive,
+        [`${rootClassName}__border-radius-last-cell`]: isLastColumn && !overlayActive,
+        [`${rootClassName}__drag-handle--active`]: overlayActive,
+      })}
+      role="button"
+      tabIndex={0}
+      aria-label={columnDragAriaLabel}
+      onMouseDown={onMouseDown}
+      onKeyDown={(e) => {
+        if (e.key === "Enter" || e.key === " ") {
+          onMouseDown();
+        }
+      }}
+    >
+      <IconDragHorizontal className={cx(`${rootClassName}__drag-handle-icon`)} size="sm" />
+    </div>
+  );
+}

package/src/use-drag-handle.test.tsx

@@ -0,0 +1,380 @@
+import React from "react";
+import { fireEvent, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { axe } from "vitest-axe";
+
+import { TableColumnDragHandle, useDragHandle } from "./use-drag-handle.hook";
+
+// Test component to test the hook
+function TestDragHandleComponent() {
+  const { mouseDownActive, handleMouseDown } = useDragHandle();
+
+  return (
+    <div>
+      <span data-testid="mouse-down-state">{mouseDownActive ? "active" : "inactive"}</span>
+      <button onClick={handleMouseDown} data-testid="trigger-button">
+        Trigger Mouse Down
+      </button>
+    </div>
+  );
+}
+
+describe("useDragHandle Hook", () => {
+  beforeEach(() => {
+    // Clean up any event listeners
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    // Clean up global event listeners
+    const events = ["mouseup"];
+    events.forEach((event) => {
+      window.removeEventListener(event, () => {});
+    });
+  });
+
+  it("should initialize with mouseDownActive as false", () => {
+    render(<TestDragHandleComponent />);
+
+    const stateElement = screen.getByTestId("mouse-down-state");
+    expect(stateElement).toHaveTextContent("inactive");
+  });
+
+  it("should set mouseDownActive to true when handleMouseDown is called", async () => {
+    const user = userEvent.setup();
+    render(<TestDragHandleComponent />);
+
+    const triggerButton = screen.getByTestId("trigger-button");
+    const stateElement = screen.getByTestId("mouse-down-state");
+
+    expect(stateElement).toHaveTextContent("inactive");
+
+    await user.click(triggerButton);
+
+    expect(stateElement).toHaveTextContent("active");
+  });
+
+  it("should reset mouseDownActive to false when mouse up event occurs", async () => {
+    const user = userEvent.setup();
+    render(<TestDragHandleComponent />);
+
+    const triggerButton = screen.getByTestId("trigger-button");
+    const stateElement = screen.getByTestId("mouse-down-state");
+
+    // Trigger mouse down
+    await user.click(triggerButton);
+    expect(stateElement).toHaveTextContent("active");
+
+    // Simulate mouse up on window
+    fireEvent.mouseUp(window);
+
+    expect(stateElement).toHaveTextContent("inactive");
+  });
+
+  it("should add and remove mouseup event listener correctly", async () => {
+    const addEventListenerSpy = vi.spyOn(window, "addEventListener");
+    const removeEventListenerSpy = vi.spyOn(window, "removeEventListener");
+
+    const user = userEvent.setup();
+    render(<TestDragHandleComponent />);
+
+    const triggerButton = screen.getByTestId("trigger-button");
+
+    await user.click(triggerButton);
+
+    expect(addEventListenerSpy).toHaveBeenCalledWith("mouseup", expect.any(Function), {
+      once: true,
+    });
+
+    // Trigger mouseup to remove listener
+    fireEvent.mouseUp(window);
+
+    addEventListenerSpy.mockRestore();
+    removeEventListenerSpy.mockRestore();
+  });
+});
+
+describe("TableColumnDragHandle Component", () => {
+  const defaultProps = {
+    onMouseDown: vi.fn(),
+    overlayActive: false,
+    isFirstColumn: false,
+    isLastColumn: false,
+    columnDragAriaLabel: "Drag to reorder column",
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("Rendering", () => {
+    it("should render drag handle with proper structure", () => {
+      render(<TableColumnDragHandle {...defaultProps} />);
+
+      const dragHandle = screen.getByRole("button");
+      expect(dragHandle).toBeInTheDocument();
+      expect(dragHandle).toHaveAttribute("tabIndex", "0");
+      expect(dragHandle).toHaveAttribute("aria-label", defaultProps.columnDragAriaLabel);
+    });
+
+    it("should contain drag icon", () => {
+      render(<TableColumnDragHandle {...defaultProps} />);
+
+      // The icon should be present (we're looking for the svg element or icon component)
+      const dragHandle = screen.getByRole("button");
+      expect(dragHandle).toBeInTheDocument();
+
+      // Check for the presence of the icon by looking for its class or content
+      const icon = dragHandle.querySelector("svg");
+      expect(icon).toBeInTheDocument();
+    });
+
+    it("should be accessible", async () => {
+      const { container } = render(<TableColumnDragHandle {...defaultProps} />);
+
+      const results = await axe(container);
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      expect(results).toHaveNoViolations();
+    });
+  });
+
+  describe("CSS Classes", () => {
+    it("should have base drag handle class", () => {
+      render(<TableColumnDragHandle {...defaultProps} />);
+
+      const dragHandle = screen.getByRole("button");
+      expect(dragHandle.className).toMatch(/drag-handle/);
+    });
+
+    it("should apply first column border radius class when isFirstColumn is true", () => {
+      render(<TableColumnDragHandle {...defaultProps} isFirstColumn={true} />);
+
+      const dragHandle = screen.getByRole("button");
+      expect(dragHandle.className).toMatch(/border-radius-first-cell/);
+    });
+
+    it("should apply last column border radius class when isLastColumn is true", () => {
+      render(<TableColumnDragHandle {...defaultProps} isLastColumn={true} />);
+
+      const dragHandle = screen.getByRole("button");
+      expect(dragHandle.className).toMatch(/border-radius-last-cell/);
+    });
+
+    it("should apply active class when overlayActive is true", () => {
+      render(<TableColumnDragHandle {...defaultProps} overlayActive={true} />);
+
+      const dragHandle = screen.getByRole("button");
+      expect(dragHandle.className).toMatch(/drag-handle--active/);
+    });
+
+    it("should not apply border radius classes when overlayActive is true", () => {
+      render(
+        <TableColumnDragHandle
+          {...defaultProps}
+          overlayActive={true}
+          isFirstColumn={true}
+          isLastColumn={true}
+        />
+      );
+
+      const dragHandle = screen.getByRole("button");
+      expect(dragHandle).not.toHaveClass(
+        "purpur-table-column-header-cell__border-radius-first-cell"
+      );
+      expect(dragHandle).not.toHaveClass(
+        "purpur-table-column-header-cell__border-radius-last-cell"
+      );
+    });
+
+    it("should apply both first and last column classes when both props are true", () => {
+      render(<TableColumnDragHandle {...defaultProps} isFirstColumn={true} isLastColumn={true} />);
+
+      const dragHandle = screen.getByRole("button");
+      expect(dragHandle.className).toMatch(/border-radius-first-cell/);
+      expect(dragHandle.className).toMatch(/border-radius-last-cell/);
+    });
+  });
+
+  describe("Event Handling", () => {
+    it("should call onMouseDown when clicked", async () => {
+      const user = userEvent.setup();
+      const onMouseDownMock = vi.fn();
+
+      render(<TableColumnDragHandle {...defaultProps} onMouseDown={onMouseDownMock} />);
+
+      const dragHandle = screen.getByRole("button");
+      await user.click(dragHandle);
+
+      expect(onMouseDownMock).toHaveBeenCalledTimes(1);
+    });
+
+    it("should call onMouseDown when mouse down event is triggered", () => {
+      const onMouseDownMock = vi.fn();
+
+      render(<TableColumnDragHandle {...defaultProps} onMouseDown={onMouseDownMock} />);
+
+      const dragHandle = screen.getByRole("button");
+      fireEvent.mouseDown(dragHandle);
+
+      expect(onMouseDownMock).toHaveBeenCalledTimes(1);
+    });
+
+    it("should call onMouseDown when Enter key is pressed", async () => {
+      const user = userEvent.setup();
+      const onMouseDownMock = vi.fn();
+
+      render(<TableColumnDragHandle {...defaultProps} onMouseDown={onMouseDownMock} />);
+
+      const dragHandle = screen.getByRole("button");
+      dragHandle.focus();
+      await user.keyboard("{Enter}");
+
+      expect(onMouseDownMock).toHaveBeenCalledTimes(1);
+    });
+
+    it("should call onMouseDown when Space key is pressed", async () => {
+      const user = userEvent.setup();
+      const onMouseDownMock = vi.fn();
+
+      render(<TableColumnDragHandle {...defaultProps} onMouseDown={onMouseDownMock} />);
+
+      const dragHandle = screen.getByRole("button");
+      dragHandle.focus();
+      await user.keyboard(" ");
+
+      expect(onMouseDownMock).toHaveBeenCalledTimes(1);
+    });
+
+    it("should not call onMouseDown for other key presses", async () => {
+      const user = userEvent.setup();
+      const onMouseDownMock = vi.fn();
+
+      render(<TableColumnDragHandle {...defaultProps} onMouseDown={onMouseDownMock} />);
+
+      const dragHandle = screen.getByRole("button");
+      dragHandle.focus();
+      await user.keyboard("{Escape}");
+
+      expect(onMouseDownMock).not.toHaveBeenCalled();
+    });
+
+    it("should handle multiple rapid clicks", async () => {
+      const user = userEvent.setup();
+      const onMouseDownMock = vi.fn();
+
+      render(<TableColumnDragHandle {...defaultProps} onMouseDown={onMouseDownMock} />);
+
+      const dragHandle = screen.getByRole("button");
+
+      await user.click(dragHandle);
+      await user.click(dragHandle);
+      await user.click(dragHandle);
+
+      expect(onMouseDownMock).toHaveBeenCalledTimes(3);
+    });
+  });
+
+  describe("Accessibility", () => {
+    it("should have proper ARIA attributes", () => {
+      const customAriaLabel = "Custom drag handle";
+      render(<TableColumnDragHandle {...defaultProps} columnDragAriaLabel={customAriaLabel} />);
+
+      const dragHandle = screen.getByRole("button");
+      expect(dragHandle).toHaveAttribute("aria-label", customAriaLabel);
+      expect(dragHandle).toHaveAttribute("tabIndex", "0");
+      expect(dragHandle).toHaveAttribute("role", "button");
+    });
+
+    it("should be focusable", () => {
+      render(<TableColumnDragHandle {...defaultProps} />);
+
+      const dragHandle = screen.getByRole("button");
+      dragHandle.focus();
+
+      expect(dragHandle).toHaveFocus();
+    });
+
+    it("should support keyboard navigation", async () => {
+      const user = userEvent.setup();
+      render(
+        <div>
+          <button>Previous Element</button>
+          <TableColumnDragHandle {...defaultProps} />
+          <button>Next Element</button>
+        </div>
+      );
+
+      const dragHandle = screen.getByRole("button", { name: defaultProps.columnDragAriaLabel });
+
+      // Should be able to tab to the drag handle
+      await user.tab();
+      await user.tab();
+
+      expect(dragHandle).toHaveFocus();
+    });
+
+    it("should maintain accessibility with different states", async () => {
+      const testCases = [
+        { overlayActive: true, isFirstColumn: true, isLastColumn: false },
+        { overlayActive: false, isFirstColumn: false, isLastColumn: true },
+        { overlayActive: true, isFirstColumn: true, isLastColumn: true },
+      ];
+
+      for (const testCase of testCases) {
+        const { container, unmount } = render(
+          <TableColumnDragHandle {...defaultProps} {...testCase} />
+        );
+
+        const results = await axe(container);
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        expect(results).toHaveNoViolations();
+
+        unmount();
+      }
+    });
+  });
+
+  describe("Props Validation", () => {
+    it("should handle undefined onMouseDown gracefully", () => {
+      expect(() => {
+        render(
+          <TableColumnDragHandle
+            {...defaultProps}
+            onMouseDown={
+              undefined as unknown as Parameters<typeof TableColumnDragHandle>[0]["onMouseDown"]
+            }
+          />
+        );
+      }).not.toThrow();
+    });
+
+    it("should handle empty aria label", () => {
+      render(<TableColumnDragHandle {...defaultProps} columnDragAriaLabel="" />);
+
+      const dragHandle = screen.getByRole("button");
+      expect(dragHandle).toHaveAttribute("aria-label", "");
+    });
+
+    it("should handle all boolean combinations", () => {
+      const booleanCombinations = [
+        { overlayActive: false, isFirstColumn: false, isLastColumn: false },
+        { overlayActive: false, isFirstColumn: false, isLastColumn: true },
+        { overlayActive: false, isFirstColumn: true, isLastColumn: false },
+        { overlayActive: false, isFirstColumn: true, isLastColumn: true },
+        { overlayActive: true, isFirstColumn: false, isLastColumn: false },
+        { overlayActive: true, isFirstColumn: false, isLastColumn: true },
+        { overlayActive: true, isFirstColumn: true, isLastColumn: false },
+        { overlayActive: true, isFirstColumn: true, isLastColumn: true },
+      ];
+
+      booleanCombinations.forEach((combination) => {
+        expect(() => {
+          const { unmount } = render(<TableColumnDragHandle {...defaultProps} {...combination} />);
+          unmount();
+        }).not.toThrow();
+      });
+    });
+  });
+});

package/src/use-drag-indicator-position.hook.ts

@@ -0,0 +1,74 @@
+import { type RefObject, useLayoutEffect, useState } from "react";
+
+import type { DropIndicatorPosition } from "./use-drop-indicator.hook";
+
+export interface DragIndicatorPosition {
+  top: number;
+  left: number;
+  container?: HTMLElement;
+}
+
+interface UseDragIndicatorPositionProps {
+  elementRef: RefObject<HTMLElement | null>;
+  dropIndicatorPosition: DropIndicatorPosition | null | undefined;
+}
+
+/**
+ * Calculates the position for the circular drag indicator rendered via portal.
+ * Only circle mode is retained; line indicator logic moved to CSS pseudo-elements.
+ */
+export function useDragIndicatorPosition({
+  elementRef,
+  dropIndicatorPosition,
+}: UseDragIndicatorPositionProps): DragIndicatorPosition | null {
+  const [position, setPosition] = useState<DragIndicatorPosition | null>(null);
+
+  useLayoutEffect(() => {
+    if (!dropIndicatorPosition || !elementRef.current) {
+      setPosition(null);
+      return;
+    }
+
+    const calculatePosition = () => {
+      if (!elementRef.current) return;
+
+      const rect = elementRef.current.getBoundingClientRect();
+      const tableContainer = elementRef.current.closest(
+        ".purpur-table__container"
+      ) as HTMLElement | null;
+
+      const offsetLeft = 2.5;
+      const offsetRight = 1.5;
+
+      if (tableContainer) {
+        const containerRect = tableContainer.getBoundingClientRect();
+        const left =
+          dropIndicatorPosition === "before"
+            ? rect.left - containerRect.left + tableContainer.scrollLeft + offsetLeft
+            : rect.right - containerRect.left + tableContainer.scrollLeft - offsetRight;
+        const top = rect.top - containerRect.top + tableContainer.scrollTop;
+        setPosition({ top, left, container: tableContainer });
+      } else {
+        const left =
+          dropIndicatorPosition === "before" ? rect.left + offsetLeft : rect.right - offsetRight;
+        const top = rect.top;
+        setPosition({ top, left });
+      }
+    };
+
+    calculatePosition();
+
+    const tableContainer = elementRef.current.closest(".purpur-table__container");
+    const handleUpdate = () => requestAnimationFrame(calculatePosition);
+
+    if (tableContainer) tableContainer.addEventListener("scroll", handleUpdate, { passive: true });
+    window.addEventListener("resize", handleUpdate, { passive: true });
+
+    return () => {
+      if (tableContainer) tableContainer.removeEventListener("scroll", handleUpdate);
+      window.removeEventListener("resize", handleUpdate);
+    };
+  }, [dropIndicatorPosition, elementRef]);
+
+  return position;
+}

package/src/use-drop-indicator.hook.ts

@@ -0,0 +1,46 @@
+import { type UniqueIdentifier, useDndContext } from "@dnd-kit/core";
+
+export type DropIndicatorPosition = "before" | "after" | null;
+
+interface UseDropIndicatorProps {
+  itemId?: UniqueIdentifier;
+  sortableId?: string;
+  enableDrag: boolean;
+}
+
+/**
+ * Hook that determines where to show a drop indicator when dragging items
+ * Works for both table columns and rows
+ */
+export function useDropIndicator({
+  itemId,
+  sortableId,
+  enableDrag,
+}: UseDropIndicatorProps): DropIndicatorPosition {
+  const dndContext = useDndContext();
+
+  // Default: no indicator
+  let dropIndicatorPosition: DropIndicatorPosition = null;
+  if (enableDrag && dndContext.active && dndContext.over) {
+    const activeId = dndContext.active.id;
+    const overId = dndContext.over.id;
+    const currentId = sortableId || itemId;
+
+    if (activeId !== overId && overId === currentId) {
+      // Try to get the current order from sortable items first (reflects drag order)
+      // Fall back to droppableContainers if items haven't been populated yet
+      const sortableItems = dndContext.over.data.current?.sortable?.items;
+      const itemOrder =
+        sortableItems && sortableItems.length > 0
+          ? sortableItems
+          : Array.from(dndContext.droppableContainers.keys());
+
+      const activeIndex = itemOrder.indexOf(activeId as string);
+      const overIndex = itemOrder.indexOf(overId as string);
+
+      dropIndicatorPosition = activeIndex > overIndex ? "before" : "after";
+    }
+  }
+
+  return dropIndicatorPosition;
+}

package/src/use-element-visibility.hook.ts

@@ -0,0 +1,28 @@
+import { type RefObject,useEffect, useState } from "react";
+
+export function useElementVisibility<T extends HTMLElement = HTMLElement>(
+  ref: RefObject<T | null>,
+  threshold: number = 1
+): boolean {
+  const [isVisible, setIsVisible] = useState(false);
+
+  useEffect(() => {
+    const currentElement = ref.current;
+    if (!currentElement) return;
+
+    const observer = new window.IntersectionObserver(
+      ([entry]) => {
+        setIsVisible(entry.isIntersecting);
+      },
+      { threshold }
+    );
+
+    observer.observe(currentElement);
+
+    return () => {
+      observer.unobserve(currentElement);
+    };
+  }, [ref, threshold]);
+
+  return isVisible;
+}

package/src/use-table-scroll.hook.tsx

@@ -0,0 +1,30 @@
+import { useEffect,useState } from "react";
+
+interface TableScrollRef {
+  current: HTMLElement | null;
+}
+
+export const useTableScroll = (ref: TableScrollRef): boolean => {
+  const [isScrolled, setIsScrolled] = useState<boolean>(false);
+
+  useEffect(() => {
+    const handleScroll = (): void => {
+      if (ref.current) {
+        setIsScrolled(ref.current.scrollLeft > 0);
+      }
+    };
+
+    const container = ref.current;
+    if (container) {
+      container.addEventListener("scroll", handleScroll);
+    }
+
+    return (): void => {
+      if (container) {
+        container.removeEventListener("scroll", handleScroll);
+      }
+    };
+  }, [ref]);
+
+  return isScrolled;
+};

package/src/utils/custom-keyboard-coordinates.ts

@@ -0,0 +1,83 @@
+import {
+  closestCorners,
+  type DroppableContainer,
+  getFirstCollision,
+  KeyboardCode,
+  type KeyboardCoordinateGetter,
+} from "@dnd-kit/core";
+
+/**
+ * Enhanced keyboard coordinate handler that better handles columns of different widths
+ * by positioning the dragged column appropriately within target columns
+ */
+export const enhancedColumnKeyboardCoordinates: KeyboardCoordinateGetter = (
+  event,
+  { context: { active, collisionRect, droppableRects, droppableContainers, over } }
+) => {
+  if (!active || !collisionRect) {
+    return;
+  }
+
+  // Only handle left/right movements for column dragging
+  if (event.code === KeyboardCode.Right || event.code === KeyboardCode.Left) {
+    event.preventDefault();
+
+    const filteredContainers: DroppableContainer[] = [];
+
+    droppableContainers.getEnabled().forEach((container) => {
+      if (container?.disabled) return;
+
+      const rect = droppableRects.get(container.id);
+      if (!rect) return;
+
+      // Filter based on direction
+      if (event.code === KeyboardCode.Right && collisionRect.left < rect.left) {
+        filteredContainers.push(container);
+      } else if (event.code === KeyboardCode.Left && collisionRect.left > rect.left) {
+        filteredContainers.push(container);
+      }
+    });
+
+    // Sort containers by distance (nearest first) for left movement
+    if (event.code === KeyboardCode.Left && filteredContainers.length > 0) {
+      filteredContainers.sort((a, b) => {
+        const rectA = droppableRects.get(a.id);
+        const rectB = droppableRects.get(b.id);
+        if (!rectA || !rectB) return 0;
+
+        // Sort by closest to furthest from the current position (for left movement)
+        return rectB.left - rectA.left;
+      });
+    }
+
+    // Find closest target
+    const collisions = closestCorners({
+      active,
+      collisionRect,
+      droppableRects,
+      droppableContainers: filteredContainers,
+      pointerCoordinates: null,
+    });
+
+    let targetId = getFirstCollision(collisions, "id");
+
+    // Get second collision if first is current "over" element
+    if (targetId === over?.id && collisions.length > 1) {
+      targetId = collisions[1].id;
+    }
+
+    if (targetId) {
+      const targetRect = droppableRects.get(targetId);
+
+      if (targetRect) {
+        return {
+          x: targetRect.left + targetRect.width * 0.35,
+          y: targetRect.top + targetRect.height / 2,
+        };
+      }
+    }
+  }
+
+  // For other keys, we don't handle them
+  return;
+};