@semiont/react-ui 0.2.33-build.79 → 0.2.33-build.81

package/src/components/resource/__tests__/ResourceViewer.mode-switch.test.tsx

@@ -0,0 +1,231 @@
+/**
+ * ResourceViewer Mode Switching Tests
+ *
+ * These tests ensure that switching between Browse and Annotate modes
+ * doesn't cause React Hook ordering violations.
+ *
+ * Bug: Previously had 3 separate useEventSubscriptions() calls causing
+ * "Rendered more hooks than during the previous render" error.
+ *
+ * Fix: Combined all event subscriptions into a single useEventSubscriptions() call.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { ResourceViewer } from '../ResourceViewer';
+import { EventBusProvider } from '../../../contexts/EventBusContext';
+import { CacheProvider } from '../../../contexts/CacheContext';
+import { TranslationProvider } from '../../../contexts/TranslationContext';
+import { ResourceAnnotationsProvider } from '../../../contexts/ResourceAnnotationsContext';
+import { ApiClientProvider } from '../../../contexts/ApiClientContext';
+import { AuthTokenProvider } from '../../../contexts/AuthTokenContext';
+import type { components } from '@semiont/api-client';
+
+type SemiontResource = components['schemas']['ResourceDescriptor'];
+
+// Mock dependencies
+vi.mock('../../../hooks/useObservableNavigation', () => ({
+  useObservableExternalNavigation: () => vi.fn(),
+}));
+
+const mockResource: SemiontResource & { content: string } = {
+  '@context': 'https://www.w3.org/ns/activitystreams',
+  '@id': 'http://example.com/resources/test-123',
+  name: 'Test Document',
+  created: '2024-01-01T00:00:00Z',
+  entityTypes: [],
+  archived: false,
+  representations: [
+    {
+      mediaType: 'text/plain',
+      byteSize: 100,
+    },
+  ],
+  content: 'This is test content for mode switching.',
+};
+
+const mockAnnotations = {
+  highlights: [],
+  references: [],
+  assessments: [],
+  comments: [],
+  tags: [],
+};
+
+const mockCacheManager = {
+  invalidateAnnotations: vi.fn(),
+  invalidate: vi.fn(),
+  invalidateEvents: vi.fn(),
+};
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { retry: false },
+    mutations: { retry: false },
+  },
+});
+
+const mockTranslationManager = {
+  t: (namespace: string, key: string, params?: Record<string, any>) => {
+    return `${namespace}.${key}`;
+  },
+};
+
+function TestWrapper({ children }: { children: React.ReactNode }) {
+  return (
+    <TranslationProvider translationManager={mockTranslationManager}>
+      <AuthTokenProvider token="test-token">
+        <ApiClientProvider baseUrl="http://localhost:4000">
+          <QueryClientProvider client={queryClient}>
+            <EventBusProvider>
+              <ResourceAnnotationsProvider>
+                <CacheProvider cacheManager={mockCacheManager}>
+                  {children}
+                </CacheProvider>
+              </ResourceAnnotationsProvider>
+            </EventBusProvider>
+          </QueryClientProvider>
+        </ApiClientProvider>
+      </AuthTokenProvider>
+    </TranslationProvider>
+  );
+}
+
+describe('ResourceViewer - Mode Switching', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Clear localStorage before each test
+    if (typeof localStorage !== 'undefined') {
+      localStorage.clear();
+    }
+  });
+
+  it('should render without crashing in browse mode', () => {
+    render(
+      <TestWrapper>
+        <ResourceViewer
+          resource={mockResource}
+          annotations={mockAnnotations}
+        />
+      </TestWrapper>
+    );
+
+    expect(screen.getByText('This is test content for mode switching.')).toBeInTheDocument();
+  });
+
+  it('should switch to annotate mode without hook ordering errors', async () => {
+    const { rerender } = render(
+      <TestWrapper>
+        <ResourceViewer
+          resource={mockResource}
+          annotations={mockAnnotations}
+        />
+      </TestWrapper>
+    );
+
+    // Initial render in browse mode
+    expect(screen.getByText('This is test content for mode switching.')).toBeInTheDocument();
+
+    // Simulate mode toggle by setting localStorage and triggering re-render
+    localStorage.setItem('annotateMode', 'true');
+
+    // Re-render (simulating what would happen when the event fires)
+    rerender(
+      <TestWrapper>
+        <ResourceViewer
+          resource={mockResource}
+          annotations={mockAnnotations}
+        />
+      </TestWrapper>
+    );
+
+    // Should still render without errors
+    expect(screen.getByText('This is test content for mode switching.')).toBeInTheDocument();
+  });
+
+  it('should toggle between browse and annotate modes multiple times without errors', async () => {
+    const { rerender } = render(
+      <TestWrapper>
+        <ResourceViewer
+          resource={mockResource}
+          annotations={mockAnnotations}
+        />
+      </TestWrapper>
+    );
+
+    // Toggle to annotate
+    localStorage.setItem('annotateMode', 'true');
+    rerender(
+      <TestWrapper>
+        <ResourceViewer
+          resource={mockResource}
+          annotations={mockAnnotations}
+        />
+      </TestWrapper>
+    );
+    expect(screen.getByText('This is test content for mode switching.')).toBeInTheDocument();
+
+    // Toggle back to browse
+    localStorage.setItem('annotateMode', 'false');
+    rerender(
+      <TestWrapper>
+        <ResourceViewer
+          resource={mockResource}
+          annotations={mockAnnotations}
+        />
+      </TestWrapper>
+    );
+    expect(screen.getByText('This is test content for mode switching.')).toBeInTheDocument();
+
+    // Toggle to annotate again
+    localStorage.setItem('annotateMode', 'true');
+    rerender(
+      <TestWrapper>
+        <ResourceViewer
+          resource={mockResource}
+          annotations={mockAnnotations}
+        />
+      </TestWrapper>
+    );
+    expect(screen.getByText('This is test content for mode switching.')).toBeInTheDocument();
+
+    // No React Hook ordering errors should occur
+  });
+
+  it('should maintain consistent hook calls across mode switches', async () => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const { rerender } = render(
+      <TestWrapper>
+        <ResourceViewer
+          resource={mockResource}
+          annotations={mockAnnotations}
+        />
+      </TestWrapper>
+    );
+
+    // Multiple rapid mode switches
+    for (let i = 0; i < 5; i++) {
+      localStorage.setItem('annotateMode', i % 2 === 0 ? 'true' : 'false');
+      rerender(
+        <TestWrapper>
+          <ResourceViewer
+            resource={mockResource}
+            annotations={mockAnnotations}
+          />
+        </TestWrapper>
+      );
+    }
+
+    // Should not have any React Hook warnings
+    const hookErrors = consoleError.mock.calls.filter(call =>
+      call[0]?.toString().includes('Rendered more hooks') ||
+      call[0]?.toString().includes('Rendered fewer hooks')
+    );
+
+    expect(hookErrors).toHaveLength(0);
+
+    consoleError.mockRestore();
+  });
+});

package/src/components/resource/panels/AssessmentEntry.tsx

@@ -1,8 +1,9 @@
 'use client';
 
-import { useEffect, useRef } from 'react';
+import { forwardRef } from 'react';
 import type { components } from '@semiont/api-client';
 import { getAnnotationExactText } from '@semiont/api-client';
+import { useEventBus } from '../../../contexts/EventBusContext';
 
 type Annotation = components['schemas']['Annotation'];
 
@@ -17,9 +18,7 @@ interface TextualBody {
 interface AssessmentEntryProps {
   assessment: Annotation;
   isFocused: boolean;
-  onClick: () => void;
-  onAssessmentRef: (assessmentId: string, el: HTMLElement | null) => void;
-  onAssessmentHover?: (assessmentId: string | null) => void;
+  isHovered?: boolean;
 }
 
 function formatRelativeTime(isoString: string): string {
@@ -67,42 +66,35 @@ function getAssessmentText(annotation: Annotation): string | null {
   return null;
 }
 
-export function AssessmentEntry({
-  assessment,
-  isFocused,
-  onClick,
-  onAssessmentRef,
-  onAssessmentHover,
-}: AssessmentEntryProps) {
-  const assessmentRef = useRef<HTMLDivElement>(null);
-
-  // Register ref with parent
-  useEffect(() => {
-    onAssessmentRef(assessment.id, assessmentRef.current);
-    return () => {
-      onAssessmentRef(assessment.id, null);
-    };
-  }, [assessment.id, onAssessmentRef]);
-
-  // Scroll to assessment when focused
-  useEffect(() => {
-    if (isFocused && assessmentRef.current) {
-      assessmentRef.current.scrollIntoView({ behavior: 'smooth', block: 'center' });
-    }
-  }, [isFocused]);
+export const AssessmentEntry = forwardRef<HTMLDivElement, AssessmentEntryProps>(
+  function AssessmentEntry(
+    {
+      assessment,
+      isFocused,
+      isHovered = false,
+    },
+    ref
+  ) {
+  const eventBus = useEventBus();
 
   const selectedText = getAnnotationExactText(assessment);
   const assessmentText = getAssessmentText(assessment);
 
   return (
     <div
-      ref={assessmentRef}
-      className="semiont-annotation-entry"
+      ref={ref}
+      className={`semiont-annotation-entry${isHovered ? ' semiont-annotation-pulse' : ''}`}
       data-type="assessment"
       data-focused={isFocused ? 'true' : 'false'}
-      onClick={onClick}
-      onMouseEnter={() => onAssessmentHover?.(assessment.id)}
-      onMouseLeave={() => onAssessmentHover?.(null)}
+      onClick={() => {
+        eventBus.emit('annotation:click', { annotationId: assessment.id, motivation: assessment.motivation });
+      }}
+      onMouseEnter={() => {
+        eventBus.emit('annotation:hover', { annotationId: assessment.id });
+      }}
+      onMouseLeave={() => {
+        eventBus.emit('annotation:hover', { annotationId: null });
+      }}
     >
       {/* Selected text quote */}
       {selectedText && (
@@ -124,4 +116,4 @@ export function AssessmentEntry({
       </div>
     </div>
   );
-}
+});

package/src/components/resource/panels/AssessmentPanel.tsx

@@ -1,11 +1,12 @@
 'use client';
 
-import { useState, useEffect } from 'react';
+import { useState, useEffect, useRef, useCallback, useMemo } from 'react';
 import { useTranslations } from '../../../contexts/TranslationContext';
-import { useMakeMeaningEvents } from '../../../contexts/MakeMeaningEventBusContext';
+import { useEventBus } from '../../../contexts/EventBusContext';
+import { useEventSubscriptions } from '../../../contexts/useEventSubscription';
 import type { components, Selector } from '@semiont/api-client';
+import { getTextPositionSelector, getTargetSelector } from '@semiont/api-client';
 import { AssessmentEntry } from './AssessmentEntry';
-import { useAnnotationPanel } from '../../../hooks/useAnnotationPanel';
 import { DetectSection } from './DetectSection';
 import { PanelHeader } from './PanelHeader';
 import './AssessmentPanel.css';
@@ -38,13 +39,7 @@ function getSelectorDisplayText(selector: Selector | Selector[]): string | null
 
 interface AssessmentPanelProps {
   annotations: Annotation[];
-  onAnnotationClick: (annotation: Annotation) => void;
-  focusedAnnotationId: string | null;
-  hoveredAnnotationId?: string | null;
-  onAnnotationHover?: (annotationId: string | null) => void;
-  onCreate: (assessmentText: string) => void;
   pendingAnnotation: PendingAnnotation | null;
-  onDetect?: (instructions?: string) => void | Promise<void>;
   isDetecting?: boolean;
   detectionProgress?: {
     status: string;
@@ -52,31 +47,105 @@ interface AssessmentPanelProps {
     message?: string;
   } | null;
   annotateMode?: boolean;
+  scrollToAnnotationId?: string | null;
+  onScrollCompleted?: () => void;
+  hoveredAnnotationId?: string | null;
 }
 
+/**
+ * Panel for managing assessment annotations with text input
+ *
+ * @emits annotation:create - Create new assessment annotation. Payload: { motivation: 'assessing', selector: Selector | Selector[], body: Body[] }
+ * @emits annotation:cancel-pending - Cancel pending assessment annotation. Payload: undefined
+ * @subscribes annotation:click - Annotation clicked. Payload: { annotationId: string }
+ */
 export function AssessmentPanel({
   annotations,
-  onAnnotationClick,
-  focusedAnnotationId,
-  hoveredAnnotationId,
-  onAnnotationHover,
-  onCreate,
   pendingAnnotation,
-  onDetect,
   isDetecting = false,
   detectionProgress,
   annotateMode = true,
+  scrollToAnnotationId,
+  onScrollCompleted,
+  hoveredAnnotationId,
 }: AssessmentPanelProps) {
   const t = useTranslations('AssessmentPanel');
-  const eventBus = useMakeMeaningEvents();
+  const eventBus = useEventBus();
   const [newAssessmentText, setNewAssessmentText] = useState('');
+  const [focusedAnnotationId, setFocusedAnnotationId] = useState<string | null>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  // Direct ref management
+  const entryRefs = useRef<Map<string, HTMLDivElement>>(new Map());
+
+  // Sort annotations by their position in the resource
+  const sortedAnnotations = useMemo(() => {
+    return [...annotations].sort((a, b) => {
+      const aSelector = getTextPositionSelector(getTargetSelector(a.target));
+      const bSelector = getTextPositionSelector(getTargetSelector(b.target));
+      if (!aSelector || !bSelector) return 0;
+      return aSelector.start - bSelector.start;
+    });
+  }, [annotations]);
+
+  // Ref callback for entry components
+  const setEntryRef = useCallback((id: string, element: HTMLDivElement | null) => {
+    if (element) {
+      entryRefs.current.set(id, element);
+    } else {
+      entryRefs.current.delete(id);
+    }
+  }, []);
+
+  // Handle scrollToAnnotationId (click scroll)
+  useEffect(() => {
+    if (!scrollToAnnotationId) return;
+    const element = entryRefs.current.get(scrollToAnnotationId);
+    if (element && containerRef.current) {
+      const elementTop = element.offsetTop;
+      const containerHeight = containerRef.current.clientHeight;
+      const elementHeight = element.offsetHeight;
+      const scrollTo = elementTop - (containerHeight / 2) + (elementHeight / 2);
+      containerRef.current.scrollTo({ top: scrollTo, behavior: 'smooth' });
+      element.classList.remove('semiont-annotation-pulse');
+      void element.offsetWidth;
+      element.classList.add('semiont-annotation-pulse');
+      if (onScrollCompleted) onScrollCompleted();
+    }
+  }, [scrollToAnnotationId]);
 
-  const { sortedAnnotations, containerRef, handleAnnotationRef } =
-    useAnnotationPanel(annotations, hoveredAnnotationId);
+  // Handle hoveredAnnotationId (hover scroll only - pulse is handled by isHovered prop)
+  useEffect(() => {
+    if (!hoveredAnnotationId) return;
+    const element = entryRefs.current.get(hoveredAnnotationId);
+    if (!element || !containerRef.current) return;
+
+    const container = containerRef.current;
+    const elementRect = element.getBoundingClientRect();
+    const containerRect = container.getBoundingClientRect();
+    const isVisible = elementRect.top >= containerRect.top && elementRect.bottom <= containerRect.bottom;
+    if (!isVisible) {
+      const elementTop = element.offsetTop;
+      const containerHeight = container.clientHeight;
+      const elementHeight = element.offsetHeight;
+      const scrollTo = elementTop - (containerHeight / 2) + (elementHeight / 2);
+      container.scrollTo({ top: scrollTo, behavior: 'smooth' });
+    }
+
+    // Pulse effect is handled by isHovered prop on AssessmentEntry
+  }, [hoveredAnnotationId]);
 
   const handleSaveNewAssessment = () => {
-    if (newAssessmentText.trim()) {
-      onCreate(newAssessmentText);
+    if (pendingAnnotation) {
+      const body: components['schemas']['AnnotationBody'][] = newAssessmentText.trim()
+        ? [{ type: 'TextualBody' as const, value: newAssessmentText, purpose: 'assessing' as const }]
+        : [];
+
+      eventBus.emit('annotation:create', {
+        motivation: 'assessing',
+        selector: pendingAnnotation.selector,
+        body,
+      });
       setNewAssessmentText('');
     }
   };
@@ -87,14 +156,25 @@ export function AssessmentPanel({
 
     const handleEscape = (e: KeyboardEvent) => {
       if (e.key === 'Escape') {
-        eventBus.emit('ui:annotation:cancel-pending');
+        eventBus.emit('annotation:cancel-pending', undefined);
         setNewAssessmentText('');
       }
     };
 
     document.addEventListener('keydown', handleEscape);
     return () => document.removeEventListener('keydown', handleEscape);
-  }, [pendingAnnotation, eventBus]);
+  }, [pendingAnnotation]);
+
+  // Event handler for annotation clicks (extracted to avoid inline arrow function)
+  const handleAnnotationClick = useCallback(({ annotationId }: { annotationId: string }) => {
+    setFocusedAnnotationId(annotationId);
+    setTimeout(() => setFocusedAnnotationId(null), 3000);
+  }, []);
+
+  // Subscribe to click events - update focused state
+  useEventSubscriptions({
+    'annotation:click': handleAnnotationClick,
+  });
 
   return (
     <div className="semiont-panel">
@@ -129,7 +209,7 @@ export function AssessmentPanel({
             <div className="semiont-annotation-prompt__actions">
               <button
                 onClick={() => {
-                  eventBus.emit('ui:annotation:cancel-pending');
+                  eventBus.emit('annotation:cancel-pending', undefined);
                   setNewAssessmentText('');
                 }}
                 className="semiont-button semiont-button--secondary"
@@ -152,12 +232,11 @@ export function AssessmentPanel({
       {/* Scrollable content area */}
       <div ref={containerRef} className="semiont-panel__content">
         {/* Detection Section - only in Annotate mode and for text resources */}
-        {annotateMode && onDetect && (
+        {annotateMode && (
           <DetectSection
             annotationType="assessment"
             isDetecting={isDetecting}
             detectionProgress={detectionProgress}
-            onDetect={onDetect}
           />
         )}
 
@@ -173,9 +252,8 @@ export function AssessmentPanel({
                 key={assessment.id}
                 assessment={assessment}
                 isFocused={assessment.id === focusedAnnotationId}
-                onClick={() => onAnnotationClick(assessment)}
-                onAssessmentRef={handleAnnotationRef}
-                {...(onAnnotationHover && { onAssessmentHover: onAnnotationHover })}
+                isHovered={assessment.id === hoveredAnnotationId}
+                ref={(el) => setEntryRef(assessment.id, el)}
               />
             ))
           )}

package/src/components/resource/panels/CommentEntry.tsx

@@ -1,18 +1,17 @@
 'use client';
 
-import { useState, useEffect, useRef } from 'react';
+import { useState, useEffect, useRef, forwardRef, useImperativeHandle } from 'react';
 import { useTranslations } from '../../../contexts/TranslationContext';
 import type { components } from '@semiont/api-client';
 import { getAnnotationExactText, getCommentText } from '@semiont/api-client';
+import { useEventBus } from '../../../contexts/EventBusContext';
 
 type Annotation = components['schemas']['Annotation'];
 
 interface CommentEntryProps {
   comment: Annotation;
   isFocused: boolean;
-  onClick: () => void;
-  onCommentRef: (commentId: string, el: HTMLElement | null) => void;
-  onCommentHover?: (commentId: string | null) => void;
+  isHovered?: boolean;
   annotateMode?: boolean;
 }
 
@@ -33,37 +32,38 @@ function formatRelativeTime(isoString: string): string {
   return date.toLocaleDateString();
 }
 
-export function CommentEntry({
-  comment,
-  isFocused,
-  onClick,
-  onCommentRef,
-  onCommentHover,
-  annotateMode = true,
-}: CommentEntryProps) {
+export const CommentEntry = forwardRef<HTMLDivElement, CommentEntryProps>(
+  function CommentEntry(
+    {
+      comment,
+      isFocused,
+      isHovered = false,
+      annotateMode = true,
+    },
+    ref
+  ) {
   const t = useTranslations('CommentsPanel');
+  const eventBus = useEventBus();
   const [isEditing, setIsEditing] = useState(false);
   const [editText, setEditText] = useState('');
-  const commentRef = useRef<HTMLDivElement>(null);
+  const internalRef = useRef<HTMLDivElement>(null);
 
-  // Register ref with parent
-  useEffect(() => {
-    onCommentRef(comment.id, commentRef.current);
-    return () => {
-      onCommentRef(comment.id, null);
-    };
-  }, [comment.id, onCommentRef]);
+  // Combine external ref with internal ref
+  useImperativeHandle(ref, () => internalRef.current!);
+
+  const commentText = getCommentText(comment) || '';
+  const selectedText = getAnnotationExactText(comment);
 
-  // Scroll to comment when focused
+  // Scroll into view when focused
   useEffect(() => {
-    if (isFocused && commentRef.current) {
-      commentRef.current.scrollIntoView({ behavior: 'smooth', block: 'center' });
+    if (isFocused && internalRef.current) {
+      internalRef.current.scrollIntoView({
+        behavior: 'smooth',
+        block: 'center',
+      });
     }
   }, [isFocused]);
 
-  const commentText = getCommentText(comment) || '';
-  const selectedText = getAnnotationExactText(comment);
-
   const handleEditClick = () => {
     setEditText(commentText);
     setIsEditing(true);
@@ -81,13 +81,19 @@ export function CommentEntry({
 
   return (
     <div
-      ref={commentRef}
-      className="semiont-annotation-entry"
+      ref={internalRef}
+      className={`semiont-annotation-entry${isHovered ? ' semiont-annotation-pulse' : ''}`}
       data-type="comment"
       data-focused={isFocused ? 'true' : 'false'}
-      onClick={onClick}
-      onMouseEnter={() => onCommentHover?.(comment.id)}
-      onMouseLeave={() => onCommentHover?.(null)}
+      onClick={() => {
+        eventBus.emit('annotation:click', { annotationId: comment.id, motivation: comment.motivation });
+      }}
+      onMouseEnter={() => {
+        eventBus.emit('annotation:hover', { annotationId: comment.id });
+      }}
+      onMouseLeave={() => {
+        eventBus.emit('annotation:hover', { annotationId: null });
+      }}
     >
       {/* Selected text quote - only for text annotations */}
       {selectedText && (
@@ -153,4 +159,4 @@ export function CommentEntry({
       )}
     </div>
   );
-}
+});