@semiont/react-ui 0.4.14 → 0.4.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semiont/react-ui",
-  "version": "0.4.14",
+  "version": "0.4.15",
   "description": "React components and hooks for Semiont",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
@@ -64,7 +64,8 @@
     "test:components:modals:keyboard": "NODE_OPTIONS=--max-old-space-size=8192 vitest run src/components/modals/__tests__/SearchModal.keyboard.test.tsx",
     "test:components:modals:accessibility": "NODE_OPTIONS=--max-old-space-size=8192 vitest run src/components/modals/__tests__/SearchModal.accessibility.test.tsx",
     "test:components:modals:visual": "NODE_OPTIONS=--max-old-space-size=8192 vitest run src/components/modals/__tests__/SearchModal.visual.test.tsx",
-    "test:components:modals": "npm run test:components:modals:basic && npm run test:components:modals:keyboard && npm run test:components:modals:accessibility && npm run test:components:modals:visual",
+    "test:components:modals:auth": "NODE_OPTIONS=--max-old-space-size=8192 vitest run src/components/modals/__tests__/SessionExpiredModal.test.tsx src/components/modals/__tests__/PermissionDeniedModal.test.tsx",
+    "test:components:modals": "npm run test:components:modals:basic && npm run test:components:modals:keyboard && npm run test:components:modals:accessibility && npm run test:components:modals:visual && npm run test:components:modals:auth",
     "test:components:other": "NODE_OPTIONS=--max-old-space-size=8192 vitest run src/components/annotation src/components/Button src/components/resource/__tests__ src/components/__tests__",
     "test:features": "NODE_OPTIONS=--max-old-space-size=8192 vitest run src/features",
     "test:other": "NODE_OPTIONS=--max-old-space-size=8192 vitest run src/contexts src/hooks src/lib src/assets",
@@ -103,6 +104,7 @@
   },
   "dependencies": {
     "@semiont/api-client": "*",
-    "@semiont/core": "*"
+    "@semiont/core": "*",
+    "react-error-boundary": "^4.1.2"
   }
 }

package/src/components/ProtectedErrorBoundary.tsx

@@ -0,0 +1,95 @@
+import React from 'react';
+import { ErrorBoundary, type FallbackProps } from 'react-error-boundary';
+
+interface ProtectedErrorBoundaryProps {
+  children: React.ReactNode;
+  /**
+   * Values that, when any change, reset the boundary back to its non-error
+   * state. Apps typically pass `[location.pathname]` so navigating away from
+   * a crashed page automatically recovers.
+   */
+  resetKeys?: unknown[];
+}
+
+/**
+ * Error boundary for protected (authenticated) routes.
+ *
+ * Catches unexpected render-time crashes inside the protected tree and
+ * shows a generic "something went wrong" fallback with a refresh option.
+ *
+ * NOT auth-specific. Auth state changes (sign-in, sign-out, expiry) flow
+ * through the KnowledgeBaseSession context, not exceptions — so this
+ * boundary will never catch an "auth error" in normal operation. Its job
+ * is purely to keep a render bug from blanking the screen.
+ *
+ * The optional `resetKeys` prop lets callers wire automatic recovery on
+ * navigation (e.g. `resetKeys={[location.pathname]}`).
+ */
+export function ProtectedErrorBoundary({
+  children,
+  resetKeys,
+}: ProtectedErrorBoundaryProps) {
+  return (
+    <ErrorBoundary
+      FallbackComponent={ProtectedErrorFallback}
+      onError={(error, info) => {
+        if (process.env.NODE_ENV === 'development') {
+          console.error('ProtectedErrorBoundary caught:', error, info);
+        }
+      }}
+      {...(resetKeys && { resetKeys })}
+    >
+      {children}
+    </ErrorBoundary>
+  );
+}
+
+function ProtectedErrorFallback({ error, resetErrorBoundary }: FallbackProps) {
+  return (
+    <div className="min-h-[400px] flex items-center justify-center p-4">
+      <div className="max-w-md w-full bg-white dark:bg-gray-800 rounded-lg shadow-lg p-6">
+        <div className="flex items-center gap-3 mb-4">
+          <div className="flex-shrink-0 w-10 h-10 bg-red-100 dark:bg-red-900/30 rounded-full flex items-center justify-center">
+            <svg className="w-6 h-6 text-red-600 dark:text-red-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" />
+            </svg>
+          </div>
+          <h2 className="text-xl font-semibold text-gray-900 dark:text-white">
+            Something went wrong
+          </h2>
+        </div>
+
+        <p className="text-gray-600 dark:text-gray-300 mb-6">
+          An unexpected error occurred. Try again, or refresh the page.
+        </p>
+
+        {process.env.NODE_ENV === 'development' && (
+          <details className="mb-4">
+            <summary className="text-sm text-gray-500 cursor-pointer hover:text-gray-700 dark:hover:text-gray-300">
+              Error details (development only)
+            </summary>
+            <pre className="mt-2 text-xs bg-gray-100 dark:bg-gray-900 p-2 rounded-sm overflow-auto">
+              {error.message}
+              {error.stack}
+            </pre>
+          </details>
+        )}
+
+        <div className="flex gap-3">
+          <button
+            onClick={resetErrorBoundary}
+            className="flex-1 px-4 py-2 text-gray-700 dark:text-gray-200 border border-gray-300 dark:border-gray-600 rounded-lg hover:bg-gray-50 dark:hover:bg-gray-700 transition-colors"
+          >
+            Try Again
+          </button>
+          <button
+            onClick={() => window.location.reload()}
+            className="flex-1 px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 transition-colors"
+          >
+            Refresh Page
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/__tests__/ProtectedErrorBoundary.test.tsx

@@ -0,0 +1,197 @@
+/**
+ * ProtectedErrorBoundary Tests
+ *
+ * The boundary catches render-time crashes inside the protected tree and
+ * shows a generic "something went wrong" fallback. It is NOT auth-specific.
+ * Auth state changes flow through context, not exceptions.
+ *
+ * Implementation: thin wrapper around `react-error-boundary`'s `ErrorBoundary`,
+ * with a custom fallback and an optional `resetKeys` prop for navigation-based
+ * auto-recovery.
+ */
+
+import React from 'react';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+
+import { ProtectedErrorBoundary } from '../ProtectedErrorBoundary';
+
+function ThrowOnRender({ message }: { message: string }): React.ReactElement {
+  throw new Error(message);
+}
+
+/**
+ * A child that throws on first render but stops throwing if `shouldThrow`
+ * becomes false. Used to test boundary reset behavior.
+ */
+function ThrowOnce({ shouldThrow }: { shouldThrow: boolean }): React.ReactElement {
+  if (shouldThrow) throw new Error('boom');
+  return <div data-testid="recovered">recovered</div>;
+}
+
+describe('ProtectedErrorBoundary', () => {
+  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    // React logs caught render errors to console.error in development;
+    // suppress to keep test output clean.
+    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore();
+  });
+
+  describe('happy path', () => {
+    it('renders children unchanged when no error', () => {
+      render(
+        <ProtectedErrorBoundary>
+          <div data-testid="child">protected content</div>
+        </ProtectedErrorBoundary>
+      );
+
+      expect(screen.getByTestId('child')).toBeInTheDocument();
+      expect(screen.getByText('protected content')).toBeInTheDocument();
+      expect(screen.queryByText('Something went wrong')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('on render error', () => {
+    it('shows the generic fallback heading', () => {
+      render(
+        <ProtectedErrorBoundary>
+          <ThrowOnRender message="boom" />
+        </ProtectedErrorBoundary>
+      );
+
+      expect(screen.getByText('Something went wrong')).toBeInTheDocument();
+    });
+
+    it('does NOT show "Authentication Error" — the boundary is not auth-themed', () => {
+      // Throw an error whose message contains the word "session" — the old
+      // AuthErrorBoundary substring-matched on this and switched its UI to
+      // an auth-flavored fallback. The new boundary must not.
+      render(
+        <ProtectedErrorBoundary>
+          <ThrowOnRender message="session blew up" />
+        </ProtectedErrorBoundary>
+      );
+
+      expect(screen.queryByText(/Authentication Error/i)).not.toBeInTheDocument();
+      expect(screen.queryByRole('button', { name: /sign in/i })).not.toBeInTheDocument();
+      expect(screen.getByText('Something went wrong')).toBeInTheDocument();
+    });
+
+    it('renders both a Try Again and a Refresh Page button', () => {
+      render(
+        <ProtectedErrorBoundary>
+          <ThrowOnRender message="boom" />
+        </ProtectedErrorBoundary>
+      );
+
+      expect(screen.getByRole('button', { name: /try again/i })).toBeInTheDocument();
+      expect(screen.getByRole('button', { name: /refresh page/i })).toBeInTheDocument();
+    });
+
+    it('calls window.location.reload when the Refresh Page button is clicked', () => {
+      const originalLocation = window.location;
+      const reload = vi.fn();
+      Object.defineProperty(window, 'location', {
+        value: { ...originalLocation, reload },
+        writable: true,
+        configurable: true,
+      });
+
+      try {
+        render(
+          <ProtectedErrorBoundary>
+            <ThrowOnRender message="boom" />
+          </ProtectedErrorBoundary>
+        );
+
+        fireEvent.click(screen.getByRole('button', { name: /refresh page/i }));
+        expect(reload).toHaveBeenCalled();
+      } finally {
+        Object.defineProperty(window, 'location', {
+          value: originalLocation,
+          writable: true,
+          configurable: true,
+        });
+      }
+    });
+
+    it('Try Again resets the boundary so children re-render', () => {
+      // The child reads `shouldThrow` from a closed-over variable that we
+      // flip between the initial mount and the click. Using an external
+      // flag (rather than counting renders) sidesteps React 18's
+      // strict-mode double-invocation of component bodies.
+      let shouldThrow = true;
+      function MaybeThrow(): React.ReactElement {
+        if (shouldThrow) throw new Error('boom');
+        return <div data-testid="recovered">recovered</div>;
+      }
+
+      render(
+        <ProtectedErrorBoundary>
+          <MaybeThrow />
+        </ProtectedErrorBoundary>
+      );
+      expect(screen.getByText('Something went wrong')).toBeInTheDocument();
+
+      // Stop throwing so the next render succeeds
+      shouldThrow = false;
+      fireEvent.click(screen.getByRole('button', { name: /try again/i }));
+
+      expect(screen.queryByText('Something went wrong')).not.toBeInTheDocument();
+      expect(screen.getByTestId('recovered')).toBeInTheDocument();
+    });
+  });
+
+  describe('resetKeys', () => {
+    it('auto-resets when a resetKey changes (simulating navigation)', () => {
+      function Harness({ pathname, shouldThrow }: { pathname: string; shouldThrow: boolean }) {
+        return (
+          <ProtectedErrorBoundary resetKeys={[pathname]}>
+            <ThrowOnce shouldThrow={shouldThrow} />
+          </ProtectedErrorBoundary>
+        );
+      }
+
+      const { rerender } = render(<Harness pathname="/know" shouldThrow={true} />);
+      expect(screen.getByText('Something went wrong')).toBeInTheDocument();
+
+      // Simulate navigation to a different path AND a render that no longer throws
+      rerender(<Harness pathname="/admin" shouldThrow={false} />);
+
+      // Boundary auto-recovers because the resetKey changed
+      expect(screen.queryByText('Something went wrong')).not.toBeInTheDocument();
+      expect(screen.getByTestId('recovered')).toBeInTheDocument();
+    });
+
+    it('logs the error to console.error in development', () => {
+      // Vitest's NODE_ENV defaults to "test", but the boundary's
+      // componentDidCatch logs only when NODE_ENV === 'development'.
+      // Force it for this test.
+      const originalEnv = process.env.NODE_ENV;
+      process.env.NODE_ENV = 'development';
+
+      try {
+        render(
+          <ProtectedErrorBoundary>
+            <ThrowOnRender message="instrumented boom" />
+          </ProtectedErrorBoundary>
+        );
+
+        // Multiple console.error calls happen (React's own logs, plus ours).
+        // Look for the boundary's prefix specifically.
+        const ourCall = consoleErrorSpy.mock.calls.find(
+          call => typeof call[0] === 'string' && call[0].includes('ProtectedErrorBoundary caught:')
+        );
+        expect(ourCall).toBeDefined();
+      } finally {
+        process.env.NODE_ENV = originalEnv;
+      }
+    });
+  });
+});

package/src/components/modals/PermissionDeniedModal.tsx

@@ -0,0 +1,140 @@
+'use client';
+
+import { Dialog, DialogPanel, DialogTitle, Transition, TransitionChild } from '@headlessui/react';
+import { useKnowledgeBaseSession } from '../../contexts/KnowledgeBaseSessionContext';
+
+/**
+ * Modal that surfaces when a 403 forbidden error is reported via
+ * `notifyPermissionDenied` (called from QueryCache.onError).
+ *
+ * Reads `permissionDeniedAt` and `permissionDeniedMessage` from
+ * KnowledgeBaseSessionContext. The provider clears the flag when the user
+ * dismisses the modal.
+ *
+ * Must be mounted inside KnowledgeBaseSessionProvider.
+ */
+export function PermissionDeniedModal() {
+  const {
+    permissionDeniedAt,
+    permissionDeniedMessage,
+    acknowledgePermissionDenied,
+  } = useKnowledgeBaseSession();
+  const showModal = permissionDeniedAt !== null;
+  const message = permissionDeniedMessage ?? 'You do not have permission to perform this action.';
+
+  const handleGoBack = () => {
+    acknowledgePermissionDenied();
+    window.history.back();
+  };
+
+  const handleGoHome = () => {
+    acknowledgePermissionDenied();
+    window.location.href = '/';
+  };
+
+  const handleSwitchAccount = () => {
+    acknowledgePermissionDenied();
+    window.location.href = `/auth/connect?callbackUrl=${encodeURIComponent(window.location.pathname)}`;
+  };
+
+  return (
+    <Transition appear show={showModal}>
+      <Dialog as="div" className="semiont-modal" onClose={handleGoBack}>
+        <TransitionChild
+          enter="ease-out duration-200"
+          enterFrom="opacity-0"
+          enterTo="opacity-100"
+          leave="ease-in duration-150"
+          leaveFrom="opacity-100"
+          leaveTo="opacity-0"
+        >
+          <div className="semiont-modal__backdrop" />
+        </TransitionChild>
+
+        <div className="semiont-modal__container">
+          <div className="semiont-modal__wrapper">
+            <TransitionChild
+              enter="ease-out duration-200"
+              enterFrom="opacity-0 scale-95"
+              enterTo="opacity-100 scale-100"
+              leave="ease-in duration-150"
+              leaveFrom="opacity-100 scale-100"
+              leaveTo="opacity-0 scale-95"
+            >
+              <DialogPanel className="semiont-modal__panel semiont-modal__panel--medium">
+                <div className="semiont-modal__icon-wrapper">
+                  <div className="semiont-modal__icon">
+                    <svg style={{ width: '1.5rem', height: '1.5rem', color: 'var(--semiont-color-amber-600, #d97706)' }} fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z" />
+                    </svg>
+                  </div>
+                </div>
+
+                <div className="semiont-modal__content">
+                  <DialogTitle className="semiont-modal__title semiont-modal__title--centered">
+                    Access Denied
+                  </DialogTitle>
+                  <p className="semiont-modal__description">
+                    {message}
+                  </p>
+                </div>
+
+                <div style={{
+                  padding: '0.75rem',
+                  backgroundColor: 'var(--semiont-bg-secondary)',
+                  borderRadius: 'var(--semiont-radius-md, 0.375rem)',
+                  border: '1px solid var(--semiont-border-primary)',
+                  fontSize: 'var(--semiont-text-sm, 0.875rem)',
+                  marginBottom: '1rem',
+                }}>
+                  <p style={{ color: 'var(--semiont-text-secondary)', marginBottom: '0.5rem' }}>
+                    This could be because:
+                  </p>
+                  <ul style={{
+                    listStyle: 'disc',
+                    listStylePosition: 'inside',
+                    color: 'var(--semiont-text-tertiary)',
+                    display: 'flex',
+                    flexDirection: 'column',
+                    gap: '0.25rem',
+                  }}>
+                    <li>You don't have the required permissions</li>
+                    <li>The resource is restricted to specific users or teams</li>
+                    <li>Your account type doesn't include this feature</li>
+                  </ul>
+                </div>
+
+                <div className="semiont-modal__actions">
+                  <button
+                    type="button"
+                    onClick={handleGoBack}
+                    className="semiont-button--primary semiont-button--flex"
+                  >
+                    Go Back
+                  </button>
+                  <button
+                    type="button"
+                    onClick={handleGoHome}
+                    className="semiont-button--secondary semiont-button--flex"
+                  >
+                    Go to Home
+                  </button>
+                </div>
+                <div className="semiont-modal__actions" style={{ marginTop: '0.5rem', paddingTop: '0.5rem', borderTop: '1px solid var(--semiont-border-primary)' }}>
+                  <button
+                    type="button"
+                    onClick={handleSwitchAccount}
+                    className="semiont-button--secondary semiont-button--flex"
+                    style={{ fontSize: 'var(--semiont-text-sm, 0.875rem)' }}
+                  >
+                    Switch Account
+                  </button>
+                </div>
+              </DialogPanel>
+            </TransitionChild>
+          </div>
+        </div>
+      </Dialog>
+    </Transition>
+  );
+}

package/src/components/modals/ReferenceWizardModal.tsx

@@ -144,18 +144,19 @@ export function ReferenceWizardModal({
   }, []);
 
   const handleSearchSubmit = useCallback((config: SearchConfig) => {
-    if (!annotationId || !context) return;
+    if (!annotationId || !context || !resourceId) return;
     setIsSearching(true);
     const contextWithHint = userHint ? { ...context, userHint } : context;
     eventBus.get('match:search-requested').next({
       correlationId: crypto.randomUUID(),
+      resourceId,
       referenceId: annotationId,
       context: contextWithHint,
       limit: config.limit,
       useSemanticScoring: config.useSemanticScoring,
     });
     // Stay on configure-search until results arrive (subscription above handles transition)
-  }, [annotationId, context, eventBus, userHint]);
+  }, [annotationId, resourceId, context, eventBus, userHint]);
 
   const handleGenerateSubmit = useCallback((config: GenerationConfig) => {
     if (!annotationId) return;

package/src/components/modals/SessionExpiredModal.tsx

@@ -0,0 +1,101 @@
+'use client';
+
+import { Dialog, DialogPanel, DialogTitle, Transition, TransitionChild } from '@headlessui/react';
+import { useKnowledgeBaseSession } from '../../contexts/KnowledgeBaseSessionContext';
+
+/**
+ * Modal that surfaces when the active KB's session expires (a 401 from
+ * either the provider's own JWT validation or from any React Query call
+ * via the QueryCache.onError handler).
+ *
+ * Reads `sessionExpiredAt` from KnowledgeBaseSessionContext. When the user
+ * dismisses the modal, the provider clears the flag.
+ *
+ * Must be mounted inside KnowledgeBaseSessionProvider.
+ */
+export function SessionExpiredModal() {
+  const {
+    sessionExpiredAt,
+    sessionExpiredMessage,
+    acknowledgeSessionExpired,
+  } = useKnowledgeBaseSession();
+  const showModal = sessionExpiredAt !== null;
+
+  const handleSignIn = () => {
+    acknowledgeSessionExpired();
+    window.location.href = `/auth/connect?callbackUrl=${encodeURIComponent(window.location.pathname)}`;
+  };
+
+  const handleClose = () => {
+    acknowledgeSessionExpired();
+    window.location.href = '/';
+  };
+
+  return (
+    <Transition appear show={showModal}>
+      <Dialog as="div" className="semiont-modal" onClose={handleClose}>
+        <TransitionChild
+          enter="ease-out duration-200"
+          enterFrom="opacity-0"
+          enterTo="opacity-100"
+          leave="ease-in duration-150"
+          leaveFrom="opacity-100"
+          leaveTo="opacity-0"
+        >
+          <div className="semiont-modal__backdrop" />
+        </TransitionChild>
+
+        <div className="semiont-modal__container">
+          <div className="semiont-modal__wrapper">
+            <TransitionChild
+              enter="ease-out duration-200"
+              enterFrom="opacity-0 scale-95"
+              enterTo="opacity-100 scale-100"
+              leave="ease-in duration-150"
+              leaveFrom="opacity-100 scale-100"
+              leaveTo="opacity-0 scale-95"
+            >
+              <DialogPanel className="semiont-modal__panel semiont-modal__panel--medium">
+                <div className="semiont-modal__icon-wrapper">
+                  <div className="semiont-modal__icon" style={{
+                    background: 'linear-gradient(to bottom right, var(--semiont-color-red-100, #fee2e2), var(--semiont-color-red-300, #fca5a5))',
+                  }}>
+                    <svg style={{ width: '1.5rem', height: '1.5rem', color: 'var(--semiont-color-red-600, #dc2626)' }} fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z" />
+                    </svg>
+                  </div>
+                </div>
+
+                <div className="semiont-modal__content">
+                  <DialogTitle className="semiont-modal__title semiont-modal__title--centered">
+                    Session Expired
+                  </DialogTitle>
+                  <p className="semiont-modal__description">
+                    {sessionExpiredMessage ?? 'Your session has expired for security reasons. Please sign in again to continue working.'}
+                  </p>
+                </div>
+
+                <div className="semiont-modal__actions">
+                  <button
+                    type="button"
+                    onClick={handleClose}
+                    className="semiont-button--secondary semiont-button--flex"
+                  >
+                    Go to Home
+                  </button>
+                  <button
+                    type="button"
+                    onClick={handleSignIn}
+                    className="semiont-button--primary semiont-button--flex"
+                  >
+                    Sign In Again
+                  </button>
+                </div>
+              </DialogPanel>
+            </TransitionChild>
+          </div>
+        </div>
+      </Dialog>
+    </Transition>
+  );
+}