@object-ui/react 2.0.0 → 3.0.1

package/src/__tests__/view-switching.test.tsx

@@ -0,0 +1,456 @@
+/**
+ * ObjectUI — View Switching State Preservation Tests
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * Tests that switching between grid ↔ kanban ↔ calendar views preserves
+ * selection state, scroll position concept, and filter criteria.
+ * Part of P2.4 Performance at Scale roadmap.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import React from 'react';
+
+// ---------------------------------------------------------------------------
+// Types for view switching state management
+// ---------------------------------------------------------------------------
+
+type ViewType = 'grid' | 'kanban' | 'calendar';
+
+interface ViewState {
+  currentView: ViewType;
+  selectedIds: string[];
+  filters: Record<string, string>;
+  scrollPosition: number;
+  sortField?: string;
+  sortDirection?: 'asc' | 'desc';
+}
+
+// ---------------------------------------------------------------------------
+// useViewSwitcher hook — manages cross-view state preservation
+// ---------------------------------------------------------------------------
+
+function useViewSwitcher(initialView: ViewType = 'grid') {
+  const [state, setState] = React.useState<ViewState>({
+    currentView: initialView,
+    selectedIds: [],
+    filters: {},
+    scrollPosition: 0,
+  });
+
+  const switchView = React.useCallback(
+    (newView: ViewType) => {
+      setState((prev) => ({
+        ...prev,
+        currentView: newView,
+      }));
+    },
+    [],
+  );
+
+  const setSelectedIds = React.useCallback(
+    (ids: string[]) => {
+      setState((prev) => ({ ...prev, selectedIds: ids }));
+    },
+    [],
+  );
+
+  const setFilters = React.useCallback(
+    (filters: Record<string, string>) => {
+      setState((prev) => ({ ...prev, filters }));
+    },
+    [],
+  );
+
+  const setScrollPosition = React.useCallback(
+    (position: number) => {
+      setState((prev) => ({ ...prev, scrollPosition: position }));
+    },
+    [],
+  );
+
+  const setSort = React.useCallback(
+    (field: string, direction: 'asc' | 'desc') => {
+      setState((prev) => ({ ...prev, sortField: field, sortDirection: direction }));
+    },
+    [],
+  );
+
+  const clearSelection = React.useCallback(() => {
+    setState((prev) => ({ ...prev, selectedIds: [] }));
+  }, []);
+
+  const clearFilters = React.useCallback(() => {
+    setState((prev) => ({ ...prev, filters: {} }));
+  }, []);
+
+  return {
+    state,
+    switchView,
+    setSelectedIds,
+    setFilters,
+    setScrollPosition,
+    setSort,
+    clearSelection,
+    clearFilters,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('View Switching: state preservation', () => {
+  it('should initialize with default view and empty state', () => {
+    const { result } = renderHook(() => useViewSwitcher('grid'));
+
+    expect(result.current.state.currentView).toBe('grid');
+    expect(result.current.state.selectedIds).toEqual([]);
+    expect(result.current.state.filters).toEqual({});
+    expect(result.current.state.scrollPosition).toBe(0);
+  });
+
+  it('should switch from grid to kanban while preserving selection', () => {
+    const { result } = renderHook(() => useViewSwitcher('grid'));
+
+    act(() => {
+      result.current.setSelectedIds(['row-1', 'row-5', 'row-10']);
+    });
+
+    expect(result.current.state.selectedIds).toEqual(['row-1', 'row-5', 'row-10']);
+
+    act(() => {
+      result.current.switchView('kanban');
+    });
+
+    expect(result.current.state.currentView).toBe('kanban');
+    expect(result.current.state.selectedIds).toEqual(['row-1', 'row-5', 'row-10']);
+  });
+
+  it('should switch from kanban to calendar while preserving selection', () => {
+    const { result } = renderHook(() => useViewSwitcher('kanban'));
+
+    act(() => {
+      result.current.setSelectedIds(['card-3', 'card-7']);
+    });
+
+    act(() => {
+      result.current.switchView('calendar');
+    });
+
+    expect(result.current.state.currentView).toBe('calendar');
+    expect(result.current.state.selectedIds).toEqual(['card-3', 'card-7']);
+  });
+
+  it('should switch from calendar to grid while preserving selection', () => {
+    const { result } = renderHook(() => useViewSwitcher('calendar'));
+
+    act(() => {
+      result.current.setSelectedIds(['event-1']);
+    });
+
+    act(() => {
+      result.current.switchView('grid');
+    });
+
+    expect(result.current.state.currentView).toBe('grid');
+    expect(result.current.state.selectedIds).toEqual(['event-1']);
+  });
+});
+
+describe('View Switching: filter preservation', () => {
+  it('should preserve filters when switching grid → kanban', () => {
+    const { result } = renderHook(() => useViewSwitcher('grid'));
+
+    act(() => {
+      result.current.setFilters({ status: 'active', department: 'engineering' });
+    });
+
+    act(() => {
+      result.current.switchView('kanban');
+    });
+
+    expect(result.current.state.currentView).toBe('kanban');
+    expect(result.current.state.filters).toEqual({
+      status: 'active',
+      department: 'engineering',
+    });
+  });
+
+  it('should preserve filters when switching kanban → calendar', () => {
+    const { result } = renderHook(() => useViewSwitcher('kanban'));
+
+    act(() => {
+      result.current.setFilters({ priority: 'high' });
+    });
+
+    act(() => {
+      result.current.switchView('calendar');
+    });
+
+    expect(result.current.state.filters).toEqual({ priority: 'high' });
+  });
+
+  it('should preserve filters across multiple view switches', () => {
+    const { result } = renderHook(() => useViewSwitcher('grid'));
+
+    act(() => {
+      result.current.setFilters({ type: 'bug', assignee: 'alice' });
+    });
+
+    // grid → kanban
+    act(() => {
+      result.current.switchView('kanban');
+    });
+    expect(result.current.state.filters).toEqual({ type: 'bug', assignee: 'alice' });
+
+    // kanban → calendar
+    act(() => {
+      result.current.switchView('calendar');
+    });
+    expect(result.current.state.filters).toEqual({ type: 'bug', assignee: 'alice' });
+
+    // calendar → grid
+    act(() => {
+      result.current.switchView('grid');
+    });
+    expect(result.current.state.filters).toEqual({ type: 'bug', assignee: 'alice' });
+  });
+
+  it('should allow clearing filters independently of view switch', () => {
+    const { result } = renderHook(() => useViewSwitcher('grid'));
+
+    act(() => {
+      result.current.setFilters({ status: 'open' });
+    });
+
+    act(() => {
+      result.current.switchView('kanban');
+    });
+
+    act(() => {
+      result.current.clearFilters();
+    });
+
+    expect(result.current.state.currentView).toBe('kanban');
+    expect(result.current.state.filters).toEqual({});
+  });
+});
+
+describe('View Switching: scroll position preservation', () => {
+  it('should preserve scroll position when switching views', () => {
+    const { result } = renderHook(() => useViewSwitcher('grid'));
+
+    act(() => {
+      result.current.setScrollPosition(1500);
+    });
+
+    act(() => {
+      result.current.switchView('kanban');
+    });
+
+    expect(result.current.state.scrollPosition).toBe(1500);
+  });
+
+  it('should preserve scroll position across full cycle: grid → kanban → calendar → grid', () => {
+    const { result } = renderHook(() => useViewSwitcher('grid'));
+
+    act(() => {
+      result.current.setScrollPosition(3200);
+    });
+
+    act(() => {
+      result.current.switchView('kanban');
+    });
+    expect(result.current.state.scrollPosition).toBe(3200);
+
+    act(() => {
+      result.current.switchView('calendar');
+    });
+    expect(result.current.state.scrollPosition).toBe(3200);
+
+    act(() => {
+      result.current.switchView('grid');
+    });
+    expect(result.current.state.scrollPosition).toBe(3200);
+  });
+});
+
+describe('View Switching: sort preservation', () => {
+  it('should preserve sort when switching views', () => {
+    const { result } = renderHook(() => useViewSwitcher('grid'));
+
+    act(() => {
+      result.current.setSort('name', 'asc');
+    });
+
+    act(() => {
+      result.current.switchView('kanban');
+    });
+
+    expect(result.current.state.sortField).toBe('name');
+    expect(result.current.state.sortDirection).toBe('asc');
+  });
+
+  it('should preserve sort across multiple switches', () => {
+    const { result } = renderHook(() => useViewSwitcher('grid'));
+
+    act(() => {
+      result.current.setSort('createdAt', 'desc');
+    });
+
+    act(() => {
+      result.current.switchView('calendar');
+    });
+
+    act(() => {
+      result.current.switchView('kanban');
+    });
+
+    expect(result.current.state.sortField).toBe('createdAt');
+    expect(result.current.state.sortDirection).toBe('desc');
+  });
+});
+
+describe('View Switching: combined state preservation', () => {
+  it('should preserve all state simultaneously when switching views', () => {
+    const { result } = renderHook(() => useViewSwitcher('grid'));
+
+    // Set up complex state
+    act(() => {
+      result.current.setSelectedIds(['item-1', 'item-2', 'item-3']);
+      result.current.setFilters({ status: 'active', priority: 'high' });
+      result.current.setScrollPosition(2500);
+      result.current.setSort('title', 'asc');
+    });
+
+    // Switch to kanban
+    act(() => {
+      result.current.switchView('kanban');
+    });
+
+    expect(result.current.state.currentView).toBe('kanban');
+    expect(result.current.state.selectedIds).toEqual(['item-1', 'item-2', 'item-3']);
+    expect(result.current.state.filters).toEqual({ status: 'active', priority: 'high' });
+    expect(result.current.state.scrollPosition).toBe(2500);
+    expect(result.current.state.sortField).toBe('title');
+    expect(result.current.state.sortDirection).toBe('asc');
+
+    // Switch to calendar
+    act(() => {
+      result.current.switchView('calendar');
+    });
+
+    expect(result.current.state.currentView).toBe('calendar');
+    expect(result.current.state.selectedIds).toEqual(['item-1', 'item-2', 'item-3']);
+    expect(result.current.state.filters).toEqual({ status: 'active', priority: 'high' });
+    expect(result.current.state.scrollPosition).toBe(2500);
+    expect(result.current.state.sortField).toBe('title');
+    expect(result.current.state.sortDirection).toBe('asc');
+
+    // Switch back to grid
+    act(() => {
+      result.current.switchView('grid');
+    });
+
+    expect(result.current.state.currentView).toBe('grid');
+    expect(result.current.state.selectedIds).toEqual(['item-1', 'item-2', 'item-3']);
+    expect(result.current.state.filters).toEqual({ status: 'active', priority: 'high' });
+    expect(result.current.state.scrollPosition).toBe(2500);
+    expect(result.current.state.sortField).toBe('title');
+    expect(result.current.state.sortDirection).toBe('asc');
+  });
+
+  it('should allow modifying state after view switch', () => {
+    const { result } = renderHook(() => useViewSwitcher('grid'));
+
+    act(() => {
+      result.current.setSelectedIds(['item-1']);
+      result.current.setFilters({ status: 'open' });
+    });
+
+    act(() => {
+      result.current.switchView('kanban');
+    });
+
+    // Modify state in kanban view
+    act(() => {
+      result.current.setSelectedIds(['item-1', 'item-4']);
+      result.current.setFilters({ status: 'open', type: 'feature' });
+    });
+
+    expect(result.current.state.selectedIds).toEqual(['item-1', 'item-4']);
+    expect(result.current.state.filters).toEqual({ status: 'open', type: 'feature' });
+
+    // Switch to calendar - should have updated state
+    act(() => {
+      result.current.switchView('calendar');
+    });
+
+    expect(result.current.state.selectedIds).toEqual(['item-1', 'item-4']);
+    expect(result.current.state.filters).toEqual({ status: 'open', type: 'feature' });
+  });
+
+  it('should handle clearing selection independently of other state', () => {
+    const { result } = renderHook(() => useViewSwitcher('grid'));
+
+    act(() => {
+      result.current.setSelectedIds(['a', 'b', 'c']);
+      result.current.setFilters({ status: 'done' });
+      result.current.setScrollPosition(800);
+    });
+
+    act(() => {
+      result.current.switchView('kanban');
+    });
+
+    act(() => {
+      result.current.clearSelection();
+    });
+
+    expect(result.current.state.selectedIds).toEqual([]);
+    expect(result.current.state.filters).toEqual({ status: 'done' });
+    expect(result.current.state.scrollPosition).toBe(800);
+  });
+});
+
+describe('View Switching: rapid switching', () => {
+  it('should handle rapid view switches without losing state', () => {
+    const { result } = renderHook(() => useViewSwitcher('grid'));
+
+    act(() => {
+      result.current.setSelectedIds(['item-1']);
+      result.current.setFilters({ query: 'test' });
+    });
+
+    // Rapid switches
+    act(() => {
+      result.current.switchView('kanban');
+      result.current.switchView('calendar');
+      result.current.switchView('grid');
+      result.current.switchView('kanban');
+    });
+
+    expect(result.current.state.currentView).toBe('kanban');
+    expect(result.current.state.selectedIds).toEqual(['item-1']);
+    expect(result.current.state.filters).toEqual({ query: 'test' });
+  });
+
+  it('should handle switching to the same view', () => {
+    const { result } = renderHook(() => useViewSwitcher('grid'));
+
+    act(() => {
+      result.current.setSelectedIds(['x']);
+    });
+
+    act(() => {
+      result.current.switchView('grid');
+    });
+
+    expect(result.current.state.currentView).toBe('grid');
+    expect(result.current.state.selectedIds).toEqual(['x']);
+  });
+});

package/src/context/DndContext.tsx

@@ -0,0 +1,260 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * @object-ui/react - Drag and Drop Context
+ *
+ * Provides a unified DnD configuration system to the component tree.
+ * Implements DndConfigSchema, DragItemSchema, DropZoneSchema,
+ * DragConstraintSchema, and DropEffectSchema from @objectstack/spec v2.0.7.
+ */
+
+import React, { createContext, useCallback, useContext, useMemo, useState } from 'react';
+
+/** Drop effect types aligned with DropEffectSchema */
+export type DropEffectType = 'move' | 'copy' | 'link' | 'none';
+
+/** Drag constraint axis aligned with DragConstraintSchema */
+export type DragAxis = 'x' | 'y' | 'both';
+
+/** Drag item metadata */
+export interface DragItemData {
+  /** Unique identifier for the dragged item */
+  id: string;
+  /** Type of the dragged item (for drop zone filtering) */
+  type: string;
+  /** Arbitrary data associated with the drag */
+  data?: Record<string, unknown>;
+  /** Source container/zone identifier */
+  sourceId?: string;
+}
+
+/** Drop zone configuration */
+export interface DropZoneConfig {
+  /** Unique identifier for the drop zone */
+  id: string;
+  /** Accepted drag item types */
+  acceptTypes: string[];
+  /** Drop effect to apply */
+  effect?: DropEffectType;
+  /** Whether the zone is currently disabled */
+  disabled?: boolean;
+  /** Maximum number of items this zone can hold */
+  maxItems?: number;
+}
+
+/** Drag constraints configuration */
+export interface DragConstraintConfig {
+  /** Constrain movement to an axis */
+  axis?: DragAxis;
+  /** Minimum distance before drag starts (in pixels) */
+  activationDistance?: number;
+  /** Whether to show a drag handle */
+  showHandle?: boolean;
+  /** Container bounds (CSS selector) */
+  containerId?: string;
+}
+
+/** Overall DnD configuration aligned with DndConfigSchema */
+export interface DndSystemConfig {
+  /** Whether DnD is enabled */
+  enabled?: boolean;
+  /** Default drag constraints */
+  defaultConstraints?: DragConstraintConfig;
+  /** Whether to show drag overlay/preview */
+  showPreview?: boolean;
+  /** Auto-scroll when dragging near edges */
+  autoScroll?: boolean;
+}
+
+/** Drag event information */
+export interface DragEvent {
+  /** The dragged item */
+  item: DragItemData;
+  /** Target drop zone (null if not over a zone) */
+  targetZoneId: string | null;
+  /** The applied drop effect */
+  effect: DropEffectType;
+}
+
+export interface DndProviderProps {
+  children: React.ReactNode;
+  /** System-wide DnD configuration */
+  config?: DndSystemConfig;
+  /** Called when a drag starts */
+  onDragStart?: (event: DragEvent) => void;
+  /** Called when an item is dropped */
+  onDrop?: (event: DragEvent) => void;
+  /** Called when a drag is cancelled */
+  onDragCancel?: (event: DragEvent) => void;
+}
+
+interface DndContextValue {
+  /** System-wide DnD configuration */
+  config: DndSystemConfig;
+  /** Whether DnD is enabled */
+  enabled: boolean;
+  /** Currently dragging item (null if not dragging) */
+  activeItem: DragItemData | null;
+  /** Registered drop zones */
+  dropZones: Map<string, DropZoneConfig>;
+  /** Start a drag operation */
+  startDrag: (item: DragItemData) => void;
+  /** End the current drag operation */
+  endDrag: (targetZoneId?: string) => void;
+  /** Cancel the current drag */
+  cancelDrag: () => void;
+  /** Register a drop zone */
+  registerDropZone: (zone: DropZoneConfig) => void;
+  /** Unregister a drop zone */
+  unregisterDropZone: (zoneId: string) => void;
+  /** Check if a drop zone accepts a drag item type */
+  canDrop: (zoneId: string, itemType: string) => boolean;
+}
+
+const DndCtx = createContext<DndContextValue | null>(null);
+
+/**
+ * DndProvider — Provides a unified DnD system aligned with @objectstack/spec v2.0.7.
+ *
+ * This is a coordination layer; actual drag mechanics are delegated to
+ * libraries like @dnd-kit/core or react-grid-layout in individual plugins.
+ *
+ * @example
+ * ```tsx
+ * <DndProvider
+ *   config={{ enabled: true, showPreview: true, autoScroll: true }}
+ *   onDrop={(event) => handleDrop(event.item, event.targetZoneId)}
+ * >
+ *   <KanbanBoard />
+ * </DndProvider>
+ * ```
+ */
+export const DndProvider: React.FC<DndProviderProps> = ({
+  children,
+  config: userConfig = {},
+  onDragStart,
+  onDrop,
+  onDragCancel,
+}) => {
+  const config = useMemo<DndSystemConfig>(
+    () => ({
+      enabled: true,
+      showPreview: true,
+      autoScroll: true,
+      ...userConfig,
+    }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [JSON.stringify(userConfig)],
+  );
+
+  const [activeItem, setActiveItem] = useState<DragItemData | null>(null);
+  const [dropZones] = useState<Map<string, DropZoneConfig>>(() => new Map());
+
+  const startDrag = useCallback(
+    (item: DragItemData) => {
+      if (!config.enabled) return;
+      setActiveItem(item);
+      onDragStart?.({ item, targetZoneId: null, effect: 'move' });
+    },
+    [config.enabled, onDragStart],
+  );
+
+  const endDrag = useCallback(
+    (targetZoneId?: string) => {
+      if (!activeItem) return;
+      const zone = targetZoneId ? dropZones.get(targetZoneId) : undefined;
+      const effect: DropEffectType = zone?.effect ?? 'move';
+      onDrop?.({ item: activeItem, targetZoneId: targetZoneId ?? null, effect });
+      setActiveItem(null);
+    },
+    [activeItem, dropZones, onDrop],
+  );
+
+  const cancelDrag = useCallback(() => {
+    if (!activeItem) return;
+    onDragCancel?.({ item: activeItem, targetZoneId: null, effect: 'none' });
+    setActiveItem(null);
+  }, [activeItem, onDragCancel]);
+
+  const registerDropZone = useCallback(
+    (zone: DropZoneConfig) => {
+      dropZones.set(zone.id, zone);
+    },
+    [dropZones],
+  );
+
+  const unregisterDropZone = useCallback(
+    (zoneId: string) => {
+      dropZones.delete(zoneId);
+    },
+    [dropZones],
+  );
+
+  const canDrop = useCallback(
+    (zoneId: string, itemType: string): boolean => {
+      const zone = dropZones.get(zoneId);
+      if (!zone || zone.disabled) return false;
+      return zone.acceptTypes.includes(itemType);
+    },
+    [dropZones],
+  );
+
+  const value = useMemo<DndContextValue>(
+    () => ({
+      config,
+      enabled: config.enabled ?? true,
+      activeItem,
+      dropZones,
+      startDrag,
+      endDrag,
+      cancelDrag,
+      registerDropZone,
+      unregisterDropZone,
+      canDrop,
+    }),
+    [
+      config,
+      activeItem,
+      dropZones,
+      startDrag,
+      endDrag,
+      cancelDrag,
+      registerDropZone,
+      unregisterDropZone,
+      canDrop,
+    ],
+  );
+
+  return <DndCtx.Provider value={value}>{children}</DndCtx.Provider>;
+};
+
+DndProvider.displayName = 'DndProvider';
+
+/**
+ * Hook to consume the DnD context.
+ *
+ * @throws Error if used outside a DndProvider
+ */
+export function useDnd(): DndContextValue {
+  const ctx = useContext(DndCtx);
+  if (!ctx) {
+    throw new Error(
+      'useDnd must be used within a <DndProvider>. ' +
+        'Wrap your app with <DndProvider> to use the drag and drop system.',
+    );
+  }
+  return ctx;
+}
+
+/**
+ * Hook to check if a DndProvider is available.
+ */
+export function useHasDndProvider(): boolean {
+  return useContext(DndCtx) !== null;
+}