ui-syncup 0.3.13 → 0.4.0-beta.1

package/src/features/issues/hooks/use-elastic-scroll.ts

@@ -0,0 +1,296 @@
+'use client';
+
+import { useCallback, useMemo } from 'react';
+
+export interface Bounds {
+  left: number;
+  right: number;
+  top: number;
+  bottom: number;
+}
+
+export interface UseElasticScrollOptions {
+  /** Container (viewport) dimensions */
+  containerSize: { width: number; height: number };
+  /** Content (image) dimensions after scaling */
+  contentSize: { width: number; height: number };
+  /** Minimum pixels of content that must remain visible */
+  minVisibilityPx?: number;
+  /** Minimum ratio of content that must remain visible (0-1) */
+  minVisibilityRatio?: number;
+  /** Rubber band elasticity (0 = no stretch, 1 = linear with no resistance) */
+  elasticity?: number;
+  /** Whether elastic scroll is enabled */
+  enabled?: boolean;
+}
+
+export interface UseElasticScrollReturn {
+  /** Calculated bounds for pan limits */
+  bounds: Bounds;
+  /** Apply rubber band effect during drag (returns visual position) */
+  applyRubberBand: (panX: number, panY: number) => { x: number; y: number };
+  /** Check if position is beyond bounds */
+  isOverscrolled: (panX: number, panY: number) => boolean;
+  /** Get clamped position within valid bounds */
+  getClampedPosition: (panX: number, panY: number) => { x: number; y: number };
+  /** Get overscroll amount for each direction */
+  getOverscrollAmount: (panX: number, panY: number) => { x: number; y: number };
+}
+
+/**
+ * Apple's rubber band formula using logarithmic resistance.
+ * Creates diminishing returns as you pull further past the boundary.
+ * 
+ * @param offset - Distance from boundary (positive = overscrolled)
+ * @param dimension - Container dimension for resistance calculation
+ * @param elasticity - Elasticity factor (0.55 mimics iOS)
+ */
+function rubberBandClamp(
+  offset: number,
+  dimension: number,
+  elasticity: number
+): number {
+  // Logarithmic damping formula (Apple's approach)
+  // Returns dampened offset that increases slowly the further you pull
+  const resistance = (1 - (1 / ((offset * elasticity / dimension) + 1)));
+  return dimension * resistance;
+}
+
+/**
+ * Apply rubber band effect to a single axis.
+ * Returns the visual position after applying elastic resistance.
+ */
+function applyRubberBandToAxis(
+  pan: number,
+  min: number,
+  max: number,
+  dimension: number,
+  elasticity: number
+): number {
+  if (pan < min) {
+    // Overscrolled past left/top boundary
+    const overscroll = min - pan;
+    const dampened = rubberBandClamp(overscroll, dimension, elasticity);
+    return min - dampened;
+  } else if (pan > max) {
+    // Overscrolled past right/bottom boundary
+    const overscroll = pan - max;
+    const dampened = rubberBandClamp(overscroll, dimension, elasticity);
+    return max + dampened;
+  }
+  // Within bounds - no damping
+  return pan;
+}
+
+/**
+ * Hook for iOS-style elastic overscroll behavior.
+ * 
+ * Features:
+ * - Calculates valid pan bounds based on content/container sizes
+ * - Applies rubber-band damping when panning beyond bounds
+ * - Provides clamped positions for spring-back animation
+ * 
+ * @example
+ * ```tsx
+ * const { bounds, applyRubberBand, getClampedPosition } = useElasticScroll({
+ *   containerSize: { width: 800, height: 600 },
+ *   contentSize: { width: 1200, height: 900 },
+ * });
+ * 
+ * // During drag:
+ * const visual = applyRubberBand(rawPanX, rawPanY);
+ * 
+ * // On release:
+ * const target = getClampedPosition(rawPanX, rawPanY);
+ * animate(panX, target.x, springConfig);
+ * ```
+ */
+export function useElasticScroll({
+  containerSize,
+  contentSize,
+  minVisibilityPx = 100,
+  minVisibilityRatio = 0.2,
+  elasticity = 0.55,
+  enabled = true,
+}: UseElasticScrollOptions): UseElasticScrollReturn {
+  
+  /**
+   * Calculate the bounds (pan limits) based on content and container sizes.
+   * 
+   * The bounds define how far the content can be panned before rubber-band kicks in.
+   * 
+   * Behavior:
+   * - Content LARGER than container: Can pan until minVisibility of VIEWPORT is still covered by image
+   * - Content SMALLER than container: Can pan until minVisibility of CONTENT remains visible
+   * - This ensures consistent 20% visibility constraint in both scenarios
+   */
+  const bounds = useMemo<Bounds>(() => {
+    if (!enabled || contentSize.width === 0 || contentSize.height === 0) {
+      // No bounds when disabled or no content
+      return {
+        left: -Infinity,
+        right: Infinity,
+        top: -Infinity,
+        bottom: Infinity,
+      };
+    }
+
+    // Half dimensions for centering calculations
+    const halfContainerWidth = containerSize.width / 2;
+    const halfContainerHeight = containerSize.height / 2;
+    const halfContentWidth = contentSize.width / 2;
+    const halfContentHeight = contentSize.height / 2;
+
+    let maxPanX: number;
+    let maxPanY: number;
+
+    if (contentSize.width > containerSize.width) {
+      // Content is WIDER than container
+      // Allow pan until minVisibility of VIEWPORT remains covered by image
+      // The image edge can go (containerWidth * minVisibilityRatio) past the viewport edge
+      const minVisibleViewportWidth = Math.max(
+        minVisibilityPx,
+        containerSize.width * minVisibilityRatio
+      );
+      // At center (pan=0), image spans past both edges
+      // Max pan = how far we can go before only minVisibility of viewport is covered
+      maxPanX = halfContentWidth - minVisibleViewportWidth;
+    } else {
+      // Content is SMALLER than or equal to container
+      // Allow pan until minVisibility of CONTENT remains visible in viewport
+      const minVisibleContentWidth = Math.max(
+        minVisibilityPx,
+        contentSize.width * minVisibilityRatio
+      );
+      maxPanX = halfContentWidth - minVisibleContentWidth + halfContainerWidth;
+    }
+
+    if (contentSize.height > containerSize.height) {
+      // Content is TALLER than container
+      // Allow pan until minVisibility of VIEWPORT remains covered by image
+      const minVisibleViewportHeight = Math.max(
+        minVisibilityPx,
+        containerSize.height * minVisibilityRatio
+      );
+      maxPanY = halfContentHeight - minVisibleViewportHeight;
+    } else {
+      // Content is SMALLER than or equal to container
+      // Allow pan until minVisibility of CONTENT remains visible in viewport
+      const minVisibleContentHeight = Math.max(
+        minVisibilityPx,
+        contentSize.height * minVisibilityRatio
+      );
+      maxPanY = halfContentHeight - minVisibleContentHeight + halfContainerHeight;
+    }
+
+    return {
+      left: -maxPanX,
+      right: maxPanX,
+      top: -maxPanY,
+      bottom: maxPanY,
+    };
+  }, [containerSize, contentSize, minVisibilityPx, minVisibilityRatio, enabled]);
+
+  /**
+   * Apply rubber band effect to pan position.
+   * Returns the visual position with elastic damping applied.
+   */
+  const applyRubberBand = useCallback(
+    (panX: number, panY: number): { x: number; y: number } => {
+      if (!enabled) {
+        return { x: panX, y: panY };
+      }
+
+      return {
+        x: applyRubberBandToAxis(
+          panX,
+          bounds.left,
+          bounds.right,
+          containerSize.width,
+          elasticity
+        ),
+        y: applyRubberBandToAxis(
+          panY,
+          bounds.top,
+          bounds.bottom,
+          containerSize.height,
+          elasticity
+        ),
+      };
+    },
+    [bounds, containerSize, elasticity, enabled]
+  );
+
+  /**
+   * Check if position is beyond bounds.
+   */
+  const isOverscrolled = useCallback(
+    (panX: number, panY: number): boolean => {
+      if (!enabled) return false;
+      
+      return (
+        panX < bounds.left ||
+        panX > bounds.right ||
+        panY < bounds.top ||
+        panY > bounds.bottom
+      );
+    },
+    [bounds, enabled]
+  );
+
+  /**
+   * Get clamped position within valid bounds.
+   * Use this as the target for spring-back animation.
+   */
+  const getClampedPosition = useCallback(
+    (panX: number, panY: number): { x: number; y: number } => {
+      if (!enabled) {
+        return { x: panX, y: panY };
+      }
+
+      return {
+        x: Math.max(bounds.left, Math.min(bounds.right, panX)),
+        y: Math.max(bounds.top, Math.min(bounds.bottom, panY)),
+      };
+    },
+    [bounds, enabled]
+  );
+
+  /**
+   * Get the overscroll amount for each axis.
+   * Positive = overscrolled past right/bottom, negative = past left/top.
+   */
+  const getOverscrollAmount = useCallback(
+    (panX: number, panY: number): { x: number; y: number } => {
+      if (!enabled) {
+        return { x: 0, y: 0 };
+      }
+
+      let overscrollX = 0;
+      let overscrollY = 0;
+
+      if (panX < bounds.left) {
+        overscrollX = panX - bounds.left;
+      } else if (panX > bounds.right) {
+        overscrollX = panX - bounds.right;
+      }
+
+      if (panY < bounds.top) {
+        overscrollY = panY - bounds.top;
+      } else if (panY > bounds.bottom) {
+        overscrollY = panY - bounds.bottom;
+      }
+
+      return { x: overscrollX, y: overscrollY };
+    },
+    [bounds, enabled]
+  );
+
+  return {
+    bounds,
+    applyRubberBand,
+    isOverscrolled,
+    getClampedPosition,
+    getOverscrollAmount,
+  };
+}

package/src/features/issues/hooks/use-issue-activities.ts

@@ -0,0 +1,71 @@
+/**
+ * USE ISSUE ACTIVITIES HOOK
+ * Ready-to-wire: React Query hook for issue activity timeline (no business logic)
+ */
+
+import { useQuery } from '@tanstack/react-query';
+import { getIssueActivities } from '../api';
+import { issueKeys } from './use-issue-details';
+import type { ActivityEntry } from '@/features/issues/types';
+
+// ============================================================================
+// HOOK
+// ============================================================================
+
+export interface UseIssueActivitiesParams {
+  issueId: string;
+  cursor?: string | null;
+  limit?: number;
+  enabled?: boolean;
+}
+
+export interface UseIssueActivitiesResult {
+  activities: ActivityEntry[];
+  hasMore: boolean;
+  nextCursor: string | null;
+  isLoading: boolean;
+  isError: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+/**
+ * Ready-to-wire hook: fetch and cache issue activity timeline
+ * Pure data fetching - no business logic
+ *
+ * @example
+ * ```tsx
+ * const { activities, hasMore, nextCursor, isLoading } = useIssueActivities({
+ *   issueId: 'issue_1',
+ *   limit: 10,
+ * });
+ * ```
+ *
+ * TODO: wire to React Query when backend is ready
+ * - Currently uses mock data from fixtures
+ * - Consider implementing infinite query for pagination
+ */
+export function useIssueActivities({
+  issueId,
+  cursor,
+  limit = 10,
+  enabled = true,
+}: UseIssueActivitiesParams): UseIssueActivitiesResult {
+  const query = useQuery({
+    queryKey: [...issueKeys.activities(issueId), cursor, limit],
+    queryFn: () => getIssueActivities({ issueId, cursor: cursor ?? undefined, limit }),
+    enabled: enabled && !!issueId,
+    staleTime: 30 * 1000, // 30 seconds
+    retry: 1,
+  });
+
+  return {
+    activities: query.data?.activities || [],
+    hasMore: query.data?.hasMore || false,
+    nextCursor: query.data?.nextCursor || null,
+    isLoading: query.isLoading,
+    isError: query.isError,
+    error: query.error,
+    refetch: query.refetch,
+  };
+}

package/src/features/issues/hooks/use-issue-delete.ts

@@ -0,0 +1,84 @@
+/**
+ * USE ISSUE DELETE HOOK
+ * Ready-to-wire: React Query mutation for deleting issues
+ */
+
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { toast } from 'sonner';
+import { deleteIssue, type DeleteIssueParams, type DeleteIssueResponse } from '../api';
+import { issueKeys } from './use-issue-details';
+
+// ============================================================================
+// HOOK
+// ============================================================================
+
+export interface UseIssueDeleteOptions {
+  onSuccess?: (data: DeleteIssueResponse) => void;
+  onError?: (error: Error) => void;
+}
+
+export interface UseIssueDeleteResult {
+  mutate: (params: DeleteIssueParams) => void;
+  mutateAsync: (params: DeleteIssueParams) => Promise<DeleteIssueResponse>;
+  isPending: boolean;
+  isError: boolean;
+  error: Error | null;
+  reset: () => void;
+}
+
+/**
+ * Ready-to-wire mutation hook for deleting issues
+ * Automatically invalidates issue lists
+ *
+ * @example
+ * ```tsx
+ * const { mutate: deleteIssueById, isPending } = useIssueDelete({
+ *   onSuccess: () => {
+ *     toast.success('Issue deleted');
+ *     router.push('/issues');
+ *   },
+ *   onError: (error) => toast.error(error.message),
+ * });
+ *
+ * deleteIssueById({ issueId: 'issue_1', actorId: 'user_1' });
+ * ```
+ *
+ * TODO: wire to React Query when backend is ready
+ * - Currently uses mock data from fixtures
+ */
+export function useIssueDelete(options?: UseIssueDeleteOptions): UseIssueDeleteResult {
+  const queryClient = useQueryClient();
+
+  const mutation = useMutation({
+    mutationFn: (params: DeleteIssueParams) => deleteIssue(params),
+    onSuccess: (data, variables) => {
+      // Remove the deleted issue from cache
+      queryClient.removeQueries({ queryKey: issueKeys.detail(variables.issueId) });
+
+      // Invalidate issue lists to refetch
+      queryClient.invalidateQueries({ queryKey: issueKeys.lists() });
+
+      // Show success toast
+      toast.success('Issue deleted successfully');
+
+      // Call custom success handler
+      options?.onSuccess?.(data);
+    },
+    onError: (error: Error) => {
+      // Show error toast
+      toast.error(error.message || 'Failed to delete issue');
+
+      // Call custom error handler
+      options?.onError?.(error);
+    },
+  });
+
+  return {
+    mutate: mutation.mutate,
+    mutateAsync: mutation.mutateAsync,
+    isPending: mutation.isPending,
+    isError: mutation.isError,
+    error: mutation.error,
+    reset: mutation.reset,
+  };
+}

package/src/features/issues/hooks/use-issue-details.ts

@@ -0,0 +1,70 @@
+/**
+ * USE ISSUE DETAILS HOOK
+ * Ready-to-wire: React Query hook for issue details (no business logic)
+ */
+
+import { useQuery } from '@tanstack/react-query';
+import { getIssueDetails } from '../api';
+import type { IssueDetailData } from '@/features/issues/types';
+
+// ============================================================================
+// QUERY KEYS
+// ============================================================================
+
+export const issueKeys = {
+  all: ['issues'] as const,
+  lists: () => [...issueKeys.all, 'list'] as const,
+  list: (filters: Record<string, unknown>) => [...issueKeys.lists(), filters] as const,
+  details: () => [...issueKeys.all, 'detail'] as const,
+  detail: (id: string) => [...issueKeys.details(), id] as const,
+  activities: (id: string) => [...issueKeys.detail(id), 'activities'] as const,
+};
+
+// ============================================================================
+// HOOK
+// ============================================================================
+
+export interface UseIssueDetailsParams {
+  issueId: string;
+  enabled?: boolean;
+}
+
+export interface UseIssueDetailsResult {
+  issue: IssueDetailData | undefined;
+  isLoading: boolean;
+  isError: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+/**
+ * Ready-to-wire hook: fetch and cache issue details
+ * Pure data fetching - no business logic
+ *
+ * @example
+ * ```tsx
+ * const { issue, isLoading, error, refetch } = useIssueDetails({
+ *   issueId: 'issue_1'
+ * });
+ * ```
+ *
+ * TODO: wire to React Query when backend is ready
+ * - Currently uses mock data from fixtures
+ */
+export function useIssueDetails({ issueId, enabled = true }: UseIssueDetailsParams): UseIssueDetailsResult {
+  const query = useQuery({
+    queryKey: issueKeys.detail(issueId),
+    queryFn: () => getIssueDetails({ issueId }).then(res => res.issue),
+    enabled: enabled && !!issueId,
+    staleTime: 30 * 1000, // 30 seconds
+    retry: 1,
+  });
+
+  return {
+    issue: query.data,
+    isLoading: query.isLoading,
+    isError: query.isError,
+    error: query.error,
+    refetch: query.refetch,
+  };
+}

package/src/features/issues/hooks/use-issue-filters.ts

@@ -0,0 +1,50 @@
+'use client'
+/**
+ * USE ISSUE FILTERS HOOK
+ * Ready-to-wire: Simple state management for filters (delegates to utils)
+ */
+
+import { useState, useMemo } from 'react';
+import type { IssueSummary } from '@/features/issues/types';
+import { filterAndSortIssues, DEFAULT_FILTERS, type IssueFilters } from '../utils';
+
+// ============================================================================
+// HOOK
+// ============================================================================
+
+export interface UseIssueFiltersResult {
+  filters: IssueFilters;
+  setFilters: React.Dispatch<React.SetStateAction<IssueFilters>>;
+  filteredIssues: IssueSummary[];
+  totalCount: number;
+  filteredCount: number;
+}
+
+/**
+ * Ready-to-wire hook for managing issue filter state
+ * Business logic delegated to pure utility functions
+ *
+ * @example
+ * ```tsx
+ * const { filters, setFilters, filteredIssues, filteredCount } = useIssueFilters(issues);
+ *
+ * // Update a single filter
+ * setFilters(prev => ({ ...prev, status: 'open' }));
+ * ```
+ */
+export function useIssueFilters(issues: IssueSummary[]): UseIssueFiltersResult {
+  const [filters, setFilters] = useState<IssueFilters>(DEFAULT_FILTERS);
+
+  const filteredIssues = useMemo(
+    () => filterAndSortIssues(issues, filters),
+    [issues, filters]
+  );
+
+  return {
+    filters,
+    setFilters,
+    filteredIssues,
+    totalCount: issues.length,
+    filteredCount: filteredIssues.length,
+  };
+}

package/src/features/issues/hooks/use-issue-update.ts

@@ -0,0 +1,93 @@
+/**
+ * USE ISSUE UPDATE HOOK
+ * Ready-to-wire: React Query mutation for updating issue fields
+ */
+
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { toast } from 'sonner';
+import { updateIssue } from '../api';
+import { issueKeys } from './use-issue-details';
+import type { IssueUpdateResponse } from '@/features/issues/types';
+
+// ============================================================================
+// HOOK
+// ============================================================================
+
+export interface UseIssueUpdateOptions {
+  onSuccess?: (data: IssueUpdateResponse) => void;
+  onError?: (error: Error) => void;
+}
+
+export interface UseIssueUpdateParams {
+  issueId: string;
+  field: string;
+  value: any;
+  actorId: string;
+}
+
+export interface UseIssueUpdateResult {
+  mutate: (params: UseIssueUpdateParams) => void;
+  mutateAsync: (params: UseIssueUpdateParams) => Promise<IssueUpdateResponse>;
+  isPending: boolean;
+  isError: boolean;
+  error: Error | null;
+  reset: () => void;
+}
+
+/**
+ * Ready-to-wire mutation hook for updating issue fields
+ * Automatically revalidates issue details and activities
+ *
+ * @example
+ * ```tsx
+ * const { mutate: updateField, isPending } = useIssueUpdate({
+ *   onSuccess: () => toast.success('Issue updated'),
+ *   onError: (error) => toast.error(error.message),
+ * });
+ *
+ * updateField({
+ *   issueId: 'issue_1',
+ *   field: 'status',
+ *   value: 'in_progress',
+ *   actorId: 'user_1'
+ * });
+ * ```
+ *
+ * TODO: wire to React Query when backend is ready
+ * - Currently uses mock data from fixtures
+ */
+export function useIssueUpdate(options?: UseIssueUpdateOptions): UseIssueUpdateResult {
+  const queryClient = useQueryClient();
+
+  const mutation = useMutation({
+    mutationFn: ({ issueId, field, value, actorId }: UseIssueUpdateParams) =>
+      updateIssue({ issueId, field, value, actorId }),
+    onSuccess: (data, variables) => {
+      // Invalidate issue details and activities to refetch latest data
+      queryClient.invalidateQueries({ queryKey: issueKeys.detail(variables.issueId) });
+      queryClient.invalidateQueries({ queryKey: issueKeys.activities(variables.issueId) });
+
+      // Note: Success toast is handled by individual inline editable components
+      // which provide field-specific messages with Undo functionality
+
+      // Call custom success handler
+      options?.onSuccess?.(data);
+    },
+    onError: (error: Error) => {
+      // Show error toast
+      toast.error(error.message || 'Failed to update issue');
+
+      // Call custom error handler
+      options?.onError?.(error);
+    },
+  });
+
+  return {
+    mutate: mutation.mutate,
+    mutateAsync: mutation.mutateAsync,
+    isPending: mutation.isPending,
+    isError: mutation.isError,
+    error: mutation.error,
+    reset: mutation.reset,
+  };
+}