@semiont/react-ui 0.4.19 → 0.4.21

package/src/features/resource-viewer/__tests__/DetectionFlowIntegration.test.tsx

@@ -1,383 +0,0 @@
-/**
- * Layer 3: Feature Integration Test - Detection Flow Architecture
- *
- * Tests the COMPLETE detection flow with real component composition:
- * - EventBusProvider (REAL)
- * - ApiClientProvider (REAL, with MOCKED client)
- * - useMarkFlow (REAL)
- * - useBindFlow (REAL)
- * - useEventSubscriptions (REAL)
- *
- * This test focuses on ARCHITECTURE and EVENT WIRING:
- * - Verifies API called exactly ONCE (catches duplicate subscriptions)
- * - Tests event propagation through the event bus
- * - Validates different motivations call correct API methods
- * - Ensures multiple event listeners don't cause duplicate API calls
- *
- * COMPLEMENTARY TEST: See detection-progress-flow.test.tsx for UI/UX testing
- * - That test verifies the USER EXPERIENCE (button clicks, progress display)
- * - This test verifies the SYSTEM ARCHITECTURE (event wiring, API calls)
- *
- * NO BACKEND SERVER - only mocked API client boundary
- */
-
-import React from 'react';
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { render, screen, waitFor } from '@testing-library/react';
-import { act } from 'react';
-import { useMarkFlow } from '../../../hooks/useMarkFlow';
-import { EventBusProvider, useEventBus } from '../../../contexts/EventBusContext';
-import { ApiClientProvider } from '../../../contexts/ApiClientContext';
-import { AuthTokenProvider } from '../../../contexts/AuthTokenContext';
-import { SemiontApiClient } from '@semiont/api-client';
-import type { Motivation } from '@semiont/core';
-import { resourceId } from '@semiont/core';
-import type { Emitter } from 'mitt';
-
-// Mock Toast module to prevent "useToast must be used within a ToastProvider" errors
-vi.mock('../../../components/Toast', () => ({
-  useToast: () => ({
-    showSuccess: vi.fn(),
-    showError: vi.fn(),
-    showInfo: vi.fn(),
-    showWarning: vi.fn(),
-  }),
-}));
-import type { EventMap } from '@semiont/core';
-
-describe('Detection Flow - Feature Integration', () => {
-  let markReferencesSpy: any;
-  let markHighlightsSpy: any;
-  let detectCommentsSpy: any;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-
-    // Spy on SemiontApiClient prototype HTTP methods (namespace methods call these)
-    markReferencesSpy = vi.spyOn(SemiontApiClient.prototype, 'annotateReferences').mockResolvedValue({ correlationId: 'c1', jobId: 'j1' });
-    markHighlightsSpy = vi.spyOn(SemiontApiClient.prototype, 'annotateHighlights').mockResolvedValue({ correlationId: 'c1', jobId: 'j1' });
-    detectCommentsSpy = vi.spyOn(SemiontApiClient.prototype, 'annotateComments').mockResolvedValue({ correlationId: 'c1', jobId: 'j1' });
-    vi.spyOn(SemiontApiClient.prototype, 'annotateAssessments').mockResolvedValue({ correlationId: 'c1', jobId: 'j1' });
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it('should call annotateReferences exactly ONCE when detection starts (not twice)', async () => {
-    const testId = resourceId('test-resource');
-
-    // Render with real component composition
-    const { emitDetectionStart } = renderDetectionFlow(testId);
-
-    // Trigger detection for linking (uses annotateReferences)
-    act(() => {
-      emitDetectionStart('linking', {
-        entityTypes: ['Person', 'Organization'],
-        includeDescriptiveReferences: false
-      });
-    });
-
-    // CRITICAL ASSERTION: API called exactly once (not twice!)
-    // This would FAIL if useBindFlow was called in multiple places
-    await waitFor(() => {
-      expect(markReferencesSpy).toHaveBeenCalledTimes(1);
-    });
-
-    // Verify correct parameters (eventBus is passed but we don't need to verify its exact value)
-    expect(markReferencesSpy).toHaveBeenCalledWith(
-      testId,
-      {
-        entityTypes: ['Person', 'Organization'],
-        includeDescriptiveReferences: false,
-      },
-      expect.objectContaining({ auth: undefined })
-    );
-  });
-
-  it('should propagate SSE progress events to useMarkFlow state', async () => {
-    const testId = resourceId('test-resource');
-
-    // Render with state observer
-    const { emitDetectionStart, getEventBus } = renderDetectionFlow(testId);
-
-    // Start detection
-    act(() => {
-      emitDetectionStart('linking', {
-        entityTypes: ['Person']
-      });
-    });
-
-    // Wait for stream to be created
-    await waitFor(() => {
-      expect(markReferencesSpy).toHaveBeenCalled();
-    });
-
-    // Simulate SSE progress event being emitted to EventBus (how SSE actually works now)
-    act(() => {
-      getEventBus().get('mark:progress').next({
-        status: 'scanning',
-        message: 'Scanning for Person...',
-        currentEntityType: 'Person',
-        totalEntityTypes: 1,
-        processedEntityTypes: 0,
-        foundCount: 5,
-      });
-    });
-
-    // Verify progress propagated to UI
-    await waitFor(() => {
-      expect(screen.getByTestId('progress')).toHaveTextContent('Scanning for Person...');
-      expect(screen.getByTestId('detecting')).toHaveTextContent('linking');
-    });
-  });
-
-  it('should handle multiple progress updates correctly', async () => {
-    const testId = resourceId('test-resource');
-    const { emitDetectionStart, getEventBus } = renderDetectionFlow(testId);
-
-    // Start detection
-    act(() => {
-      emitDetectionStart('highlighting', {
-        instructions: 'Find important passages'
-      });
-    });
-
-    await waitFor(() => {
-      expect(markHighlightsSpy).toHaveBeenCalledTimes(1);
-    });
-
-    // First progress update via EventBus
-    act(() => {
-      getEventBus().get('mark:progress').next({
-        status: 'started',
-        message: 'Starting analysis...',
-        percentage: 0,
-      });
-    });
-
-    await waitFor(() => {
-      expect(screen.getByTestId('progress')).toHaveTextContent('Starting analysis...');
-    });
-
-    // Second progress update via EventBus
-    act(() => {
-      getEventBus().get('mark:progress').next({
-        status: 'analyzing',
-        message: 'Analyzing text...',
-        percentage: 50,
-      });
-    });
-
-    await waitFor(() => {
-      expect(screen.getByTestId('progress')).toHaveTextContent('Analyzing text...');
-    });
-
-    // Final progress update via EventBus
-    act(() => {
-      getEventBus().get('mark:progress').next({
-        status: 'complete',
-        message: 'Created 14 highlights',
-        percentage: 100,
-      });
-    });
-
-    await waitFor(() => {
-      expect(screen.getByTestId('progress')).toHaveTextContent('Created 14 highlights');
-    });
-  });
-
-  it('should keep progress visible after detection completes', async () => {
-    const testId = resourceId('test-resource');
-    const { emitDetectionStart, getEventBus } = renderDetectionFlow(testId);
-
-    // Start detection
-    act(() => {
-      emitDetectionStart('highlighting', { instructions: 'Test' });
-    });
-
-    await waitFor(() => {
-      expect(screen.getByTestId('detecting')).toHaveTextContent('highlighting');
-    });
-
-    // Send final progress via EventBus
-    act(() => {
-      getEventBus().get('mark:progress').next({
-        status: 'complete',
-        message: 'Created 14 highlights',
-      });
-    });
-
-    await waitFor(() => {
-      expect(screen.getByTestId('progress')).toHaveTextContent('Created 14 highlights');
-    });
-
-    // Emit completion event
-    act(() => {
-      getEventBus().get('mark:assist-finished').next({ motivation: 'highlighting' });
-    });
-
-    // Verify: detecting flag cleared BUT progress still visible
-    await waitFor(() => {
-      expect(screen.getByTestId('detecting')).toHaveTextContent('none');
-      expect(screen.getByTestId('progress')).toHaveTextContent('Created 14 highlights');
-    });
-  });
-
-  it('should clear progress on detection failure', async () => {
-    const testId = resourceId('test-resource');
-    const { emitDetectionStart, getEventBus } = renderDetectionFlow(testId);
-
-    // Start detection
-    act(() => {
-      emitDetectionStart('linking', { entityTypes: ['Person'] });
-    });
-
-    // Add some progress via EventBus
-    act(() => {
-      getEventBus().get('mark:progress').next({
-        status: 'scanning',
-        message: 'Scanning...',
-      });
-    });
-
-    await waitFor(() => {
-      expect(screen.getByTestId('progress')).toHaveTextContent('Scanning...');
-    });
-
-    // Emit failure
-    act(() => {
-      getEventBus().get('mark:assist-failed').next({
-        type: 'job.failed' as const,
-        resourceId: 'test-resource' as any,
-        userId: 'user' as any,
-        id: 'evt-1' as any,
-        timestamp: new Date().toISOString(),
-        version: 1,
-        payload: {
-          jobId: 'job-1' as any,
-          jobType: 'detection',
-          error: 'Network error',
-        },
-      });
-    });
-
-    // Verify: both detecting and progress cleared
-    await waitFor(() => {
-      expect(screen.getByTestId('detecting')).toHaveTextContent('none');
-      expect(screen.getByTestId('progress')).toHaveTextContent('No progress');
-    });
-  });
-
-  it('should handle different detection motivations with correct API calls', async () => {
-    const testId = resourceId('test-resource');
-    const { emitDetectionStart } = renderDetectionFlow(testId);
-
-    // Test highlighting
-    act(() => {
-      emitDetectionStart('highlighting', { instructions: 'Find important text' });
-    });
-
-    await waitFor(() => {
-      expect(markHighlightsSpy).toHaveBeenCalledTimes(1);
-      expect(markHighlightsSpy).toHaveBeenCalledWith(testId, {
-        instructions: 'Find important text',
-      }, expect.objectContaining({ auth: undefined }));
-    });
-
-    // Reset for next test
-    vi.clearAllMocks();
-    detectCommentsSpy.mockResolvedValue({ correlationId: 'c2', jobId: 'j2' });
-
-    // Test commenting
-    act(() => {
-      emitDetectionStart('commenting', {
-        instructions: 'Add helpful comments',
-        tone: 'educational'
-      });
-    });
-
-    await waitFor(() => {
-      expect(detectCommentsSpy).toHaveBeenCalledTimes(1);
-      expect(detectCommentsSpy).toHaveBeenCalledWith(testId, {
-        instructions: 'Add helpful comments',
-        tone: 'educational',
-      }, expect.objectContaining({ auth: undefined }));
-    });
-  });
-
-  it('should only call API once even with multiple event listeners', async () => {
-    const testId = resourceId('test-resource');
-
-    // This test specifically catches the duplicate useBindFlow bug
-    // If multiple components call useBindFlow, we'll see multiple API calls
-    const { emitDetectionStart, getEventBus } = renderDetectionFlow(testId);
-
-    // Add an additional event listener (simulating multiple subscribers)
-    const additionalListener = vi.fn();
-    const subscription = getEventBus().get('mark:assist-request').subscribe(additionalListener);
-
-    // Trigger detection
-    act(() => {
-      emitDetectionStart('linking', { entityTypes: ['Person'] });
-    });
-
-    // Wait for operation to complete
-    await waitFor(() => {
-      expect(markReferencesSpy).toHaveBeenCalled();
-    });
-
-    // VERIFY: API called exactly once, even though multiple listeners exist
-    expect(markReferencesSpy).toHaveBeenCalledTimes(1);
-
-    // VERIFY: Our additional listener was called (events work)
-    expect(additionalListener).toHaveBeenCalledTimes(1);
-
-    subscription.unsubscribe();
-  });
-});
-
-/**
- * Helper: Render useMarkFlow hook with real component composition
- * Returns methods to interact with the rendered component
- */
-function renderDetectionFlow(testId: string) {
-  let eventBusInstance: Emitter<EventMap>;
-
-  // Component to capture EventBus instance
-  function EventBusCapture() {
-    eventBusInstance = useEventBus();
-    return null;
-  }
-
-  // Test harness component that uses the hook
-  function DetectionFlowTestHarness() {
-    const { progress, assistingMotivation } = useMarkFlow(testId as any);
-    return (
-      <div>
-        <div data-testid="detecting">{assistingMotivation || 'none'}</div>
-        <div data-testid="progress">
-          {progress?.message || 'No progress'}
-        </div>
-      </div>
-    );
-  }
-
-  render(
-    <EventBusProvider>
-      <AuthTokenProvider token={null}>
-        <ApiClientProvider baseUrl="http://localhost:4000">
-          <EventBusCapture />
-          <DetectionFlowTestHarness />
-        </ApiClientProvider>
-      </AuthTokenProvider>
-    </EventBusProvider>
-  );
-
-  return {
-    emitDetectionStart: (motivation: Motivation, options: any) => {
-      eventBusInstance.get('mark:assist-request').next({ motivation, options });
-    },
-    getEventBus: () => eventBusInstance,
-  };
-}

package/src/features/resource-viewer/__tests__/ResourceMutations.test.tsx

@@ -1,299 +0,0 @@
-/**
- * Regression test: resource mutations must be hoisted to component top level
- *
- * Bug: handleResourceClone (and handleResourceArchive / handleResourceUnarchive)
- * called useMutation() inside a useCallback, violating the Rules of Hooks.
- * React does not re-execute memoized callbacks on every render, so the mutation
- * object was never properly initialised and .mutateAsync() threw immediately,
- * always landing in the catch block and showing "Failed to generate clone link".
- *
- * Fix: the two mutations (updateMutation, generateCloneTokenMutation) are now
- * called unconditionally at the top level of ResourceViewerPage, and the
- * resulting objects are threaded into the useCallback dependency arrays.
- *
- * This test suite uses a minimal harness that:
- * - Mounts the REAL useResources() hook (which calls useMutation internally)
- * - Wires up a REAL EventBus and subscribes the same handlers as ResourceViewerPage
- * - Spies on SemiontApiClient.prototype to intercept API calls
- *
- * It confirms that each event-driven mutation calls the API exactly once,
- * and that the clipboard is written with the correct token URL for clone.
- */
-
-import React, { useCallback } from 'react';
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { render, waitFor } from '@testing-library/react';
-import { act } from 'react';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { SemiontApiClient } from '@semiont/api-client';
-import { resourceId, accessToken } from '@semiont/core';
-import { EventBusProvider, useEventBus } from '../../../contexts/EventBusContext';
-import { useEventSubscriptions } from '../../../contexts/useEventSubscription';
-import { ApiClientProvider } from '../../../contexts/ApiClientContext';
-import { AuthTokenProvider } from '../../../contexts/AuthTokenContext';
-import { useResources } from '../../../lib/api-hooks';
-import type { EventMap, EventBus } from '@semiont/core';
-
-// ─── Constants ────────────────────────────────────────────────────────────────
-
-const TEST_URI = resourceId('test-resource');
-const TEST_TOKEN = 'test-auth-token-123';
-const BASE_URL = 'http://localhost:4000';
-const CLONE_TOKEN = 'generated-clone-token-xyz';
-
-// ─── Harness ──────────────────────────────────────────────────────────────────
-
-/**
- * Minimal harness that replicates the three mutation-backed event handlers
- * from ResourceViewerPage using the REAL useResources hook.
- *
- * The critical invariant under test: useMutation() is called at hook level
- * (inside useResources), not inside the useCallback bodies.
- */
-function ResourceMutationHarness({ onEventBus }: { onEventBus: (eventBus: EventBus) => void }) {
-  const eventBus = useEventBus();
-
-  // Capture the eventBus for the test to emit events
-  React.useEffect(() => {
-    onEventBus(eventBus);
-  }, []); // eslint-disable-line react-hooks/exhaustive-deps
-
-  // Real hook — mutations are initialised at the top level of useResources()
-  const resources = useResources();
-
-  // Mutations hoisted to this component's top level — same pattern as ResourceViewerPage fix
-  const updateMutation = resources.update.useMutation();
-  const generateCloneTokenMutation = resources.generateCloneToken.useMutation();
-
-  const handleResourceArchive = useCallback(async () => {
-    await updateMutation.mutateAsync({ id: TEST_URI, data: { archived: true } });
-  }, [updateMutation]);
-
-  const handleResourceUnarchive = useCallback(async () => {
-    await updateMutation.mutateAsync({ id: TEST_URI, data: { archived: false } });
-  }, [updateMutation]);
-
-  const handleResourceClone = useCallback(async () => {
-    const result = await generateCloneTokenMutation.mutateAsync(TEST_URI);
-    const cloneUrl = `${window.location.origin}/know/clone?token=${result.token}`;
-    await navigator.clipboard.writeText(cloneUrl);
-  }, [generateCloneTokenMutation]);
-
-  useEventSubscriptions({
-    'mark:archive': handleResourceArchive,
-    'mark:unarchive': handleResourceUnarchive,
-    'yield:clone': handleResourceClone,
-  });
-
-  return null;
-}
-
-// ─── Test setup ───────────────────────────────────────────────────────────────
-
-function renderHarness() {
-  let capturedEventBus: EventBus | null = null;
-
-  const queryClient = new QueryClient({
-    defaultOptions: {
-      queries: { retry: false },
-      mutations: { retry: false },
-    },
-  });
-
-  render(
-    <EventBusProvider>
-      <AuthTokenProvider token={TEST_TOKEN}>
-        <ApiClientProvider baseUrl={BASE_URL}>
-          <QueryClientProvider client={queryClient}>
-            <ResourceMutationHarness onEventBus={(eventBus) => { capturedEventBus = eventBus; }} />
-          </QueryClientProvider>
-        </ApiClientProvider>
-      </AuthTokenProvider>
-    </EventBusProvider>
-  );
-
-  const emit = <K extends keyof EventMap>(event: K, payload: EventMap[K]) => {
-    act(() => { capturedEventBus!.get(event).next(payload); });
-  };
-
-  return { emit };
-}
-
-// ─── Tests ────────────────────────────────────────────────────────────────────
-
-describe('Resource mutations — hooks hoisted to top level', () => {
-  let generateCloneTokenSpy: ReturnType<typeof vi.spyOn>;
-  let updateResourceSpy: ReturnType<typeof vi.spyOn>;
-  let writeTextSpy: ReturnType<typeof vi.fn>;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-
-    generateCloneTokenSpy = vi
-      .spyOn(SemiontApiClient.prototype, 'generateCloneToken')
-      .mockResolvedValue({ token: CLONE_TOKEN } as any);
-
-    updateResourceSpy = vi
-      .spyOn(SemiontApiClient.prototype, 'updateResource')
-      .mockResolvedValue({ resource: {} } as any);
-
-    // jsdom has no clipboard — install a writable spy
-    writeTextSpy = vi.fn().mockResolvedValue(undefined);
-    Object.defineProperty(navigator, 'clipboard', {
-      value: { writeText: writeTextSpy },
-      configurable: true,
-      writable: true,
-    });
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  // ── Clone ──────────────────────────────────────────────────────────────────
-
-  it('calls generateCloneToken API when yield:clone event fires', async () => {
-    const { emit } = renderHarness();
-
-    await act(async () => {
-      emit('yield:clone', undefined);
-    });
-
-    await waitFor(() => {
-      expect(generateCloneTokenSpy).toHaveBeenCalledTimes(1);
-    });
-  });
-
-  it('passes the resource URI to generateCloneToken', async () => {
-    const { emit } = renderHarness();
-
-    await act(async () => {
-      emit('yield:clone', undefined);
-    });
-
-    await waitFor(() => {
-      expect(generateCloneTokenSpy).toHaveBeenCalledWith(
-        TEST_URI,
-        expect.anything(),
-      );
-    });
-  });
-
-  it('passes auth token to generateCloneToken', async () => {
-    const { emit } = renderHarness();
-
-    await act(async () => {
-      emit('yield:clone', undefined);
-    });
-
-    await waitFor(() => {
-      expect(generateCloneTokenSpy).toHaveBeenCalledWith(
-        TEST_URI,
-        expect.objectContaining({ auth: accessToken(TEST_TOKEN) })
-      );
-    });
-  });
-
-  it('writes a clone URL containing the returned token to the clipboard', async () => {
-    const { emit } = renderHarness();
-
-    await act(async () => {
-      emit('yield:clone', undefined);
-    });
-
-    await waitFor(() => {
-      expect(writeTextSpy).toHaveBeenCalledTimes(1);
-    });
-
-    const writtenUrl: string = writeTextSpy.mock.calls[0][0];
-    expect(writtenUrl).toContain(CLONE_TOKEN);
-    expect(writtenUrl).toContain('/know/clone?token=');
-  });
-
-  it('does NOT call updateResource when yield:clone fires', async () => {
-    const { emit } = renderHarness();
-
-    await act(async () => {
-      emit('yield:clone', undefined);
-    });
-
-    await waitFor(() => {
-      expect(generateCloneTokenSpy).toHaveBeenCalledTimes(1);
-    });
-
-    expect(updateResourceSpy).not.toHaveBeenCalled();
-  });
-
-  // ── Archive ────────────────────────────────────────────────────────────────
-
-  it('calls updateResource with archived:true when mark:archive fires', async () => {
-    const { emit } = renderHarness();
-
-    await act(async () => {
-      emit('mark:archive', undefined);
-    });
-
-    await waitFor(() => {
-      expect(updateResourceSpy).toHaveBeenCalledTimes(1);
-    });
-
-    expect(updateResourceSpy).toHaveBeenCalledWith(
-      TEST_URI,
-      expect.objectContaining({ archived: true }),
-      expect.anything(),
-    );
-  });
-
-  it('does NOT call generateCloneToken when mark:archive fires', async () => {
-    const { emit } = renderHarness();
-
-    await act(async () => {
-      emit('mark:archive', undefined);
-    });
-
-    await waitFor(() => {
-      expect(updateResourceSpy).toHaveBeenCalledTimes(1);
-    });
-
-    expect(generateCloneTokenSpy).not.toHaveBeenCalled();
-  });
-
-  // ── Unarchive ──────────────────────────────────────────────────────────────
-
-  it('calls updateResource with archived:false when mark:unarchive fires', async () => {
-    const { emit } = renderHarness();
-
-    await act(async () => {
-      emit('mark:unarchive', undefined);
-    });
-
-    await waitFor(() => {
-      expect(updateResourceSpy).toHaveBeenCalledTimes(1);
-    });
-
-    expect(updateResourceSpy).toHaveBeenCalledWith(
-      TEST_URI,
-      expect.objectContaining({ archived: false }),
-      expect.anything(),
-    );
-  });
-
-  // ── Isolation ─────────────────────────────────────────────────────────────
-
-  it('mark:archive and yield:clone events each call their own API exactly once', async () => {
-    const { emit } = renderHarness();
-
-    await act(async () => {
-      emit('mark:archive', undefined);
-    });
-
-    await act(async () => {
-      emit('yield:clone', undefined);
-    });
-
-    await waitFor(() => {
-      expect(updateResourceSpy).toHaveBeenCalledTimes(1);
-      expect(generateCloneTokenSpy).toHaveBeenCalledTimes(1);
-    });
-  });
-});