@semiont/react-ui 0.2.33-build.84 → 0.2.33-build.85

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semiont/react-ui",
-  "version": "0.2.33-build.84",
+  "version": "0.2.33-build.85",
   "description": "React components and hooks for Semiont",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",

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

@@ -0,0 +1,300 @@
+/**
+ * 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, resourceUri, accessToken } from '@semiont/api-client';
+import { EventBusProvider, useEventBus, resetEventBusForTesting } 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 } from '../../../contexts/EventBusContext';
+import type { Emitter } from 'mitt';
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const TEST_URI = resourceUri('http://localhost:4000/resources/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: (bus: Emitter<EventMap>) => void }) {
+  const eventBus = useEventBus();
+
+  // Capture the bus 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({ rUri: TEST_URI, data: { archived: true } });
+  }, [updateMutation]);
+
+  const handleResourceUnarchive = useCallback(async () => {
+    await updateMutation.mutateAsync({ rUri: 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({
+    'resource:archive': handleResourceArchive,
+    'resource:unarchive': handleResourceUnarchive,
+    'resource:clone': handleResourceClone,
+  });
+
+  return null;
+}
+
+// ─── Test setup ───────────────────────────────────────────────────────────────
+
+function renderHarness() {
+  let capturedBus: Emitter<EventMap> | null = null;
+
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+      mutations: { retry: false },
+    },
+  });
+
+  render(
+    <AuthTokenProvider token={TEST_TOKEN}>
+      <ApiClientProvider baseUrl={BASE_URL}>
+        <QueryClientProvider client={queryClient}>
+          <EventBusProvider>
+            <ResourceMutationHarness onEventBus={(bus) => { capturedBus = bus; }} />
+          </EventBusProvider>
+        </QueryClientProvider>
+      </ApiClientProvider>
+    </AuthTokenProvider>
+  );
+
+  const emit = <K extends keyof EventMap>(event: K, payload: EventMap[K]) => {
+    act(() => { capturedBus!.emit(event, 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();
+    resetEventBusForTesting();
+
+    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 resource:clone event fires', async () => {
+    const { emit } = renderHarness();
+
+    await act(async () => {
+      emit('resource:clone', undefined);
+    });
+
+    await waitFor(() => {
+      expect(generateCloneTokenSpy).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it('passes the resource URI to generateCloneToken', async () => {
+    const { emit } = renderHarness();
+
+    await act(async () => {
+      emit('resource: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('resource: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('resource: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 resource:clone fires', async () => {
+    const { emit } = renderHarness();
+
+    await act(async () => {
+      emit('resource:clone', undefined);
+    });
+
+    await waitFor(() => {
+      expect(generateCloneTokenSpy).toHaveBeenCalledTimes(1);
+    });
+
+    expect(updateResourceSpy).not.toHaveBeenCalled();
+  });
+
+  // ── Archive ────────────────────────────────────────────────────────────────
+
+  it('calls updateResource with archived:true when resource:archive fires', async () => {
+    const { emit } = renderHarness();
+
+    await act(async () => {
+      emit('resource: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 resource:archive fires', async () => {
+    const { emit } = renderHarness();
+
+    await act(async () => {
+      emit('resource:archive', undefined);
+    });
+
+    await waitFor(() => {
+      expect(updateResourceSpy).toHaveBeenCalledTimes(1);
+    });
+
+    expect(generateCloneTokenSpy).not.toHaveBeenCalled();
+  });
+
+  // ── Unarchive ──────────────────────────────────────────────────────────────
+
+  it('calls updateResource with archived:false when resource:unarchive fires', async () => {
+    const { emit } = renderHarness();
+
+    await act(async () => {
+      emit('resource:unarchive', undefined);
+    });
+
+    await waitFor(() => {
+      expect(updateResourceSpy).toHaveBeenCalledTimes(1);
+    });
+
+    expect(updateResourceSpy).toHaveBeenCalledWith(
+      TEST_URI,
+      expect.objectContaining({ archived: false }),
+      expect.anything()
+    );
+  });
+
+  // ── Isolation ─────────────────────────────────────────────────────────────
+
+  it('resource:archive and resource:clone events each call their own API exactly once', async () => {
+    const { emit } = renderHarness();
+
+    await act(async () => {
+      emit('resource:archive', undefined);
+    });
+
+    await act(async () => {
+      emit('resource:clone', undefined);
+    });
+
+    await waitFor(() => {
+      expect(updateResourceSpy).toHaveBeenCalledTimes(1);
+      expect(generateCloneTokenSpy).toHaveBeenCalledTimes(1);
+    });
+  });
+});

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

@@ -41,6 +41,8 @@ vi.mock('../../../lib/api-hooks', () => ({
   useResources: () => ({
     annotations: { useQuery: () => ({ data: { annotations: [] } }) },
     referencedBy: { useQuery: () => ({ data: { referencedBy: [] }, isLoading: false }) },
+    update: { useMutation: () => ({ mutateAsync: vi.fn() }) },
+    generateCloneToken: { useMutation: () => ({ mutateAsync: vi.fn() }) },
   }),
   useEntityTypes: () => ({
     list: { useQuery: () => ({ data: { entityTypes: ['Document', 'Article', 'Book'] } }) },

package/src/features/resource-viewer/components/ResourceViewerPage.tsx

@@ -279,41 +279,41 @@ export function ResourceViewerPage({
     }, []),
   });
 
+  // Mutations hoisted to top level — hooks must not be called inside callbacks
+  const updateMutation = resources.update.useMutation();
+  const generateCloneTokenMutation = resources.generateCloneToken.useMutation();
+
   // Event handlers extracted to useCallback (tenet: no inline handlers in useEventSubscriptions)
   const handleResourceArchive = useCallback(async () => {
     try {
-      await resources.update.useMutation().mutateAsync({ rUri, data: { archived: true } });
+      await updateMutation.mutateAsync({ rUri, data: { archived: true } });
       await refetchDocument();
-      showSuccess('Document archived');
     } catch (err) {
       console.error('Failed to archive document:', err);
       showError('Failed to archive document');
     }
-  }, [resources.update, rUri, refetchDocument, showSuccess, showError]);
+  }, [updateMutation, rUri, refetchDocument, showError]);
 
   const handleResourceUnarchive = useCallback(async () => {
     try {
-      await resources.update.useMutation().mutateAsync({ rUri, data: { archived: false } });
+      await updateMutation.mutateAsync({ rUri, data: { archived: false } });
       await refetchDocument();
-      showSuccess('Document unarchived');
     } catch (err) {
       console.error('Failed to unarchive document:', err);
       showError('Failed to unarchive document');
     }
-  }, [resources.update, rUri, refetchDocument, showSuccess, showError]);
+  }, [updateMutation, rUri, refetchDocument, showError]);
 
   const handleResourceClone = useCallback(async () => {
     try {
-      const result = await resources.generateCloneToken.useMutation().mutateAsync(rUri);
+      const result = await generateCloneTokenMutation.mutateAsync(rUri);
       const token = result.token;
-      const cloneUrl = `${typeof window !== 'undefined' ? window.location.origin : ''}/know/clone?token=${token}`;
-      await navigator.clipboard.writeText(cloneUrl);
-      showSuccess('Clone link copied to clipboard');
+      eventBus.emit('navigation:router-push', { path: `/know/compose?mode=clone&token=${token}`, reason: 'clone' });
     } catch (err) {
       console.error('Failed to generate clone token:', err);
       showError('Failed to generate clone link');
     }
-  }, [resources.generateCloneToken, rUri, showSuccess, showError]);
+  }, [generateCloneTokenMutation, rUri, showError]);
 
   const handleAnnotationSparkle = useCallback(({ annotationId }: { annotationId: string }) => {
     triggerSparkleAnimation(annotationId);

package/src/styles/core/checkboxes.css

@@ -31,11 +31,19 @@
 .semiont-checkbox:checked {
   background-color: var(--semiont-color-primary-500);
   border-color: var(--semiont-color-primary-500);
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill='none' stroke='white' stroke-width='2.5' stroke-linecap='round' stroke-linejoin='round' d='M3 8l3.5 3.5L13 4.5'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: center;
+  background-size: 75%;
 }
 
 [data-theme="dark"] .semiont-checkbox:checked {
   background-color: var(--semiont-color-primary-400);
   border-color: var(--semiont-color-primary-400);
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill='none' stroke='white' stroke-width='2.5' stroke-linecap='round' stroke-linejoin='round' d='M3 8l3.5 3.5L13 4.5'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: center;
+  background-size: 75%;
 }
 
 /* Focus State */