@jmruthers/pace-core 0.6.10 → 0.6.11

package/src/components/DataTable/hooks/useDataTableRenderGuard.test.tsx

@@ -0,0 +1,316 @@
+/**
+ * @file useDataTableRenderGuard Hook Tests
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Hooks
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, render, screen } from '@testing-library/react';
+import React from 'react';
+import { useDataTableRenderGuard } from './useDataTableRenderGuard';
+import type { Table } from '@tanstack/react-table';
+import type { DataRecord } from '../types';
+
+const TEST_TIMEOUT = 10000;
+
+const mockLogger = {
+  error: vi.fn(),
+  warn: vi.fn(),
+  debug: vi.fn(),
+  info: vi.fn(),
+};
+
+function LoadingStub() {
+  return <span data-testid="loading">Loading...</span>;
+}
+
+function AccessDeniedStub({ resource, operation }: { resource: string; operation: string }) {
+  return (
+    <span data-testid="access-denied">
+      Access denied: {resource} / {operation}
+    </span>
+  );
+}
+
+function makeTableMock(): Table<DataRecord> {
+  return {
+    getRowModel: () => ({ rows: [] }),
+    getVisibleFlatColumns: () => [],
+  } as unknown as Table<DataRecord>;
+}
+
+const baseOptions = {
+  user: { id: 'user-1' },
+  permissions: {
+    canRead: { can: true, isLoading: false, error: null as Error | null },
+  },
+  isPermissionLoading: false,
+  permissionElapsed: 0,
+  shouldAllowRenderAfterTimeout: false,
+  isLoading: false,
+  table: makeTableMock(),
+  dataLength: 10,
+  finalTableDataLength: 10,
+  columnsLength: 3,
+  externalIsLoading: false,
+  performanceLoading: false,
+  effectivePageId: 'test-page' as string | undefined,
+  finalPaginationMode: 'client' as string,
+  logger: mockLogger as never,
+  LoadingComponent: LoadingStub,
+  AccessDeniedPage: AccessDeniedStub,
+};
+
+describe('[unit] useDataTableRenderGuard', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns gate throw and null component when user is missing', () => {
+    const { result } = renderHook(() =>
+      useDataTableRenderGuard({
+        ...baseOptions,
+        user: null,
+      })
+    );
+    expect(result.current.gate).toBe('throw');
+    expect(result.current.component).toBeNull();
+    expect(mockLogger.error).toHaveBeenCalledWith('DataTable render blocked: No user', expect.any(Object));
+  }, TEST_TIMEOUT);
+
+  it('returns gate loading and LoadingComponent when permissions are loading', () => {
+    const { result } = renderHook(() =>
+      useDataTableRenderGuard({
+        ...baseOptions,
+        isPermissionLoading: true,
+      })
+    );
+    expect(result.current.gate).toBe('loading');
+    expect(result.current.component).not.toBeNull();
+  }, TEST_TIMEOUT);
+
+  it('returns gate denied and AccessDeniedPage when canRead is false', () => {
+    const { result } = renderHook(() =>
+      useDataTableRenderGuard({
+        ...baseOptions,
+        permissions: {
+          canRead: { can: false, isLoading: false, error: null },
+        },
+      })
+    );
+    expect(result.current.gate).toBe('denied');
+    expect(result.current.component).not.toBeNull();
+    expect(mockLogger.warn).toHaveBeenCalledWith('Access denied - no read permission:', expect.any(Object));
+  }, TEST_TIMEOUT);
+
+  it('returns gate loading when isLoading is true', () => {
+    const { result } = renderHook(() =>
+      useDataTableRenderGuard({
+        ...baseOptions,
+        isLoading: true,
+      })
+    );
+    expect(result.current.gate).toBe('loading');
+    expect(result.current.component).not.toBeNull();
+  }, TEST_TIMEOUT);
+
+  it('returns gate ready and null component when all checks pass', () => {
+    const { result } = renderHook(() => useDataTableRenderGuard(baseOptions));
+    expect(result.current.gate).toBe('ready');
+    expect(result.current.component).toBeNull();
+  }, TEST_TIMEOUT);
+
+  it('when permission loading and permissionElapsed > 10s, still returns loading and logs error', () => {
+    mockLogger.error.mockClear();
+    const { result } = renderHook(() =>
+      useDataTableRenderGuard({
+        ...baseOptions,
+        isPermissionLoading: true,
+        permissionElapsed: 11000,
+      })
+    );
+    expect(result.current.gate).toBe('loading');
+    expect(result.current.component).not.toBeNull();
+    expect(mockLogger.error).toHaveBeenCalledWith(
+      'DataTableCore',
+      'DataTable: Permission check hanging (>10s)',
+      expect.any(Object)
+    );
+  }, TEST_TIMEOUT);
+
+  it('AccessDeniedPage receives effectivePageId or unknown-page', () => {
+    const { result } = renderHook(() =>
+      useDataTableRenderGuard({
+        ...baseOptions,
+        permissions: { canRead: { can: false, isLoading: false, error: null } },
+        effectivePageId: undefined,
+      })
+    );
+    expect(result.current.gate).toBe('denied');
+    expect(result.current.component).not.toBeNull();
+    expect(mockLogger.warn).toHaveBeenCalledWith(
+      'Access denied - no read permission:',
+      expect.objectContaining({ pageId: undefined })
+    );
+  }, TEST_TIMEOUT);
+
+  it('returns gate ready and logs warn when shouldAllowRenderAfterTimeout and permissions still loading', () => {
+    const { result } = renderHook(() =>
+      useDataTableRenderGuard({
+        ...baseOptions,
+        isPermissionLoading: false,
+        permissions: { canRead: { can: true, isLoading: true, error: null } },
+        permissionElapsed: 5000,
+        shouldAllowRenderAfterTimeout: true,
+      })
+    );
+    expect(result.current.gate).toBe('ready');
+    expect(result.current.component).toBeNull();
+    expect(mockLogger.warn).toHaveBeenCalledWith(
+      'DataTable: Rendering after timeout - permissions still loading. Data will remain hidden until confirmed.',
+      expect.objectContaining({
+        pageId: baseOptions.effectivePageId,
+        elapsedMs: 5000,
+      })
+    );
+  }, TEST_TIMEOUT);
+
+  it('when denied, component renders AccessDeniedPage with correct resource and operation', () => {
+    const { result } = renderHook(() =>
+      useDataTableRenderGuard({
+        ...baseOptions,
+        permissions: { canRead: { can: false, isLoading: false, error: null } },
+        effectivePageId: 'my-resource',
+      })
+    );
+    expect(result.current.gate).toBe('denied');
+    render(<>{result.current.component}</>);
+    const el = screen.getByTestId('access-denied');
+    expect(el).toHaveTextContent(/Access denied:.*my-resource.*read/);
+    expect(el.textContent).toContain('my-resource');
+    expect(el.textContent).toContain('read');
+  }, TEST_TIMEOUT);
+
+  it('when denied and effectivePageId undefined, component shows unknown-page', () => {
+    const { result } = renderHook(() =>
+      useDataTableRenderGuard({
+        ...baseOptions,
+        permissions: { canRead: { can: false, isLoading: false, error: null } },
+        effectivePageId: undefined,
+      })
+    );
+    expect(result.current.gate).toBe('denied');
+    render(<>{result.current.component}</>);
+    const el = screen.getByTestId('access-denied');
+    expect(el).toHaveTextContent(/Access denied:.*unknown-page.*read/);
+    expect(el.textContent).toContain('unknown-page');
+    expect(el.textContent).toContain('read');
+  }, TEST_TIMEOUT);
+
+  it('when loading, component renders LoadingComponent', () => {
+    const { result } = renderHook(() =>
+      useDataTableRenderGuard({
+        ...baseOptions,
+        isPermissionLoading: true,
+      })
+    );
+    expect(result.current.gate).toBe('loading');
+    render(<>{result.current.component}</>);
+    expect(screen.getByTestId('loading')).toHaveTextContent('Loading...');
+  }, TEST_TIMEOUT);
+
+  it('when isLoading is true, component renders LoadingComponent', () => {
+    const { result } = renderHook(() =>
+      useDataTableRenderGuard({
+        ...baseOptions,
+        isLoading: true,
+      })
+    );
+    expect(result.current.gate).toBe('loading');
+    render(<>{result.current.component}</>);
+    expect(screen.getByTestId('loading')).toHaveTextContent('Loading...');
+  }, TEST_TIMEOUT);
+
+  describe('NODE_ENV development', () => {
+    const originalNodeEnv = process.env.NODE_ENV;
+
+    afterEach(() => {
+      process.env.NODE_ENV = originalNodeEnv;
+    });
+
+    it('logs debug when permissions loading in development', () => {
+      process.env.NODE_ENV = 'development';
+      mockLogger.debug.mockClear();
+      renderHook(() =>
+        useDataTableRenderGuard({
+          ...baseOptions,
+          isPermissionLoading: true,
+          permissionElapsed: 100,
+        })
+      );
+      expect(mockLogger.debug).toHaveBeenCalledWith(
+        'DataTable render blocked: Permissions loading',
+        expect.objectContaining({
+          elapsedMs: 100,
+          permissionState: baseOptions.permissions.canRead,
+        })
+      );
+    }, TEST_TIMEOUT);
+
+    it('logs debug when proceeding to render after timeout in development', () => {
+      process.env.NODE_ENV = 'development';
+      mockLogger.debug.mockClear();
+      renderHook(() =>
+        useDataTableRenderGuard({
+          ...baseOptions,
+          isPermissionLoading: false,
+          permissions: { canRead: { can: true, isLoading: true, error: null } },
+          permissionElapsed: 5000,
+          shouldAllowRenderAfterTimeout: true,
+        })
+      );
+      expect(mockLogger.debug).toHaveBeenCalledWith(
+        'DataTable: Proceeding to render after timeout - permissions still loading',
+        expect.objectContaining({ pageId: baseOptions.effectivePageId, elapsedMs: 5000 })
+      );
+    }, TEST_TIMEOUT);
+
+    it('logs debug when isLoading blocks render in development', () => {
+      process.env.NODE_ENV = 'development';
+      mockLogger.debug.mockClear();
+      renderHook(() =>
+        useDataTableRenderGuard({
+          ...baseOptions,
+          isLoading: true,
+        })
+      );
+      expect(mockLogger.debug).toHaveBeenCalledWith(
+        'DataTable render blocked: External isLoading',
+        expect.objectContaining({
+          isLoadingSource: expect.objectContaining({
+            externalIsLoading: false,
+            performanceLoading: false,
+            computed: true,
+          }),
+        })
+      );
+    }, TEST_TIMEOUT);
+
+    it('logs debug when proceeding to render in development', () => {
+      process.env.NODE_ENV = 'development';
+      mockLogger.debug.mockClear();
+      renderHook(() => useDataTableRenderGuard(baseOptions));
+      expect(mockLogger.debug).toHaveBeenCalledWith(
+        'DataTable proceeding to render:',
+        expect.objectContaining({
+          willRender: true,
+          tableState: expect.objectContaining({
+            rowCount: 0,
+            columnCount: 0,
+            paginationMode: 'client',
+          }),
+        })
+      );
+    }, TEST_TIMEOUT);
+  });
+});

package/src/components/DataTable/hooks/useDataTableRenderGuard.tsx

@@ -0,0 +1,195 @@
+/**
+ * @file DataTable Render Guard Hook
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Hooks
+ *
+ * Encapsulates RBAC and loading checks; returns gate status and optional component to render.
+ */
+
+import React from 'react';
+import type { Table } from '@tanstack/react-table';
+import type { DataRecord } from '../types';
+
+export interface RenderGuardPermissions {
+  canRead: { can: boolean; isLoading: boolean; error?: Error | null };
+}
+
+export interface UseDataTableRenderGuardOptions<TData extends DataRecord> {
+  user: unknown;
+  permissions: RenderGuardPermissions;
+  isPermissionLoading: boolean;
+  permissionElapsed: number;
+  shouldAllowRenderAfterTimeout: boolean;
+  isLoading: boolean;
+  table: Table<TData> | null;
+  dataLength: number;
+  finalTableDataLength: number;
+  columnsLength: number;
+  externalIsLoading: boolean;
+  performanceLoading: boolean;
+  effectivePageId: string | undefined;
+  finalPaginationMode?: string;
+  logger: ReturnType<typeof import('../../../utils/core/logger').createLogger>;
+  LoadingComponent: React.ComponentType;
+  AccessDeniedPage: React.ComponentType<{ resource: string; operation: string }>;
+}
+
+export type RenderGuardGate = 'ready' | 'loading' | 'denied' | 'throw';
+
+export interface UseDataTableRenderGuardResult {
+  gate: RenderGuardGate;
+  component: React.ReactNode | null;
+}
+
+function buildRenderDiagnostics<TData extends DataRecord>(
+  options: UseDataTableRenderGuardOptions<TData>
+) {
+  const {
+    user,
+    permissions,
+    effectivePageId,
+    externalIsLoading,
+    performanceLoading,
+    isLoading,
+    dataLength,
+    finalTableDataLength,
+    columnsLength,
+    table,
+  } = options;
+  return {
+    hasUser: !!user,
+    userId: (user as { id?: string })?.id,
+    permissionLoading: permissions.canRead.isLoading,
+    permissionCan: permissions.canRead.can,
+    permissionError: permissions.canRead.error,
+    effectivePageId,
+    externalIsLoading,
+    performanceLoading,
+    computedIsLoading: isLoading,
+    dataLength,
+    finalTableDataLength,
+    columnsLength,
+    tableRowsCount: table?.getRowModel().rows.length ?? 0,
+  };
+}
+
+/**
+ * Hook that performs RBAC and loading checks and returns either 'ready' or
+ * the gate plus component to render (loading, denied, or throw).
+ */
+export function useDataTableRenderGuard<TData extends DataRecord>(
+  options: UseDataTableRenderGuardOptions<TData>
+): UseDataTableRenderGuardResult {
+  const {
+    user,
+    permissions,
+    isPermissionLoading,
+    permissionElapsed,
+    shouldAllowRenderAfterTimeout,
+    isLoading,
+    table,
+    effectivePageId,
+    logger,
+    LoadingComponent,
+    AccessDeniedPage,
+  } = options;
+
+  const renderDiagnostics = buildRenderDiagnostics(options);
+
+  if (!user) {
+    logger.error('DataTable render blocked: No user', renderDiagnostics);
+    return { gate: 'throw', component: null };
+  }
+
+  if (isPermissionLoading) {
+    if (permissionElapsed > 10000) {
+      logger.error('DataTableCore', 'DataTable: Permission check hanging (>10s)', {
+        ...renderDiagnostics,
+        permissionState: {
+          can: permissions.canRead.can,
+          isLoading: permissions.canRead.isLoading,
+          error: permissions.canRead.error?.message,
+        },
+        elapsedMs: permissionElapsed,
+        diagnostic:
+          'Permission check has been loading for over 10 seconds. This likely indicates a hanging database query or network issue. Check browser network tab for pending requests to Supabase.',
+        recommendation:
+          'Check: 1) Browser network tab for pending requests, 2) Supabase connection, 3) Database query performance, 4) Super admin check completion',
+      });
+    }
+    if (process.env.NODE_ENV === 'development') {
+      logger.debug('DataTable render blocked: Permissions loading', {
+        ...renderDiagnostics,
+        permissionState: permissions.canRead,
+        elapsedMs: permissionElapsed,
+      });
+    }
+    return { gate: 'loading', component: <LoadingComponent /> };
+  }
+
+  if (permissions.canRead.isLoading && shouldAllowRenderAfterTimeout) {
+    logger.warn(
+      'DataTable: Rendering after timeout - permissions still loading. Data will remain hidden until confirmed.',
+      {
+        pageId: effectivePageId,
+        elapsedMs: permissionElapsed,
+        permissionState: permissions.canRead,
+      }
+    );
+  }
+
+  if (!permissions.canRead.isLoading && !permissions.canRead.can) {
+    logger.warn('Access denied - no read permission:', {
+      canRead: permissions.canRead,
+      pageId: effectivePageId,
+      isLoading: permissions.canRead.isLoading,
+      diagnostics: renderDiagnostics,
+    });
+    return {
+      gate: 'denied',
+      component: (
+        <AccessDeniedPage
+          resource={effectivePageId ?? 'unknown-page'}
+          operation="read"
+        />
+      ),
+    };
+  }
+
+  if (permissions.canRead.isLoading && shouldAllowRenderAfterTimeout) {
+    if (process.env.NODE_ENV === 'development') {
+      logger.debug('DataTable: Proceeding to render after timeout - permissions still loading', {
+        pageId: effectivePageId,
+        elapsedMs: permissionElapsed,
+      });
+    }
+  }
+
+  if (isLoading) {
+    if (process.env.NODE_ENV === 'development') {
+      logger.debug('DataTable render blocked: External isLoading', {
+        ...renderDiagnostics,
+        isLoadingSource: {
+          externalIsLoading: options.externalIsLoading,
+          performanceLoading: options.performanceLoading,
+          computed: isLoading,
+        },
+      });
+    }
+    return { gate: 'loading', component: <LoadingComponent /> };
+  }
+
+  if (process.env.NODE_ENV === 'development') {
+    logger.debug('DataTable proceeding to render:', {
+      ...renderDiagnostics,
+      willRender: true,
+      tableState: {
+        rowCount: table?.getRowModel().rows.length ?? 0,
+        columnCount: table?.getVisibleFlatColumns().length ?? 0,
+        paginationMode: options.finalPaginationMode,
+      },
+    });
+  }
+
+  return { gate: 'ready', component: null };
+}

package/src/components/DataTable/hooks/useDataTableScope.test.ts

@@ -0,0 +1,110 @@
+/**
+ * @file useDataTableScope Hook Tests
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Hooks
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { useDataTableScope } from './useDataTableScope';
+
+const TEST_TIMEOUT = 10000;
+
+const mockUseResolvedScope = vi.fn();
+vi.mock('../../../rbac/hooks/useResolvedScope', () => ({
+  useResolvedScope: (...args: unknown[]) => mockUseResolvedScope(...args),
+}));
+
+describe('[unit] useDataTableScope', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockUseResolvedScope.mockReturnValue({
+      resolvedScope: null,
+      isLoading: false,
+    });
+  });
+
+  it('returns consistentScope with organisationId, eventId, appId', () => {
+    mockUseResolvedScope.mockReturnValue({
+      resolvedScope: {
+        organisationId: 'org-1',
+        eventId: 'ev-1',
+        appId: 'app-1',
+      },
+      isLoading: false,
+    });
+    const { result } = renderHook(() =>
+      useDataTableScope({
+        selectedOrganisation: { id: 'org-1' },
+        selectedEvent: { event_id: 'ev-1', organisation_id: 'org-1' },
+        supabase: {},
+        pageId: undefined,
+        pageName: 'Test Page',
+      })
+    );
+    expect(result.current.consistentScope).toEqual({
+      organisationId: 'org-1',
+      eventId: 'ev-1',
+      appId: 'app-1',
+    });
+  }, TEST_TIMEOUT);
+
+  it('returns empty scope when resolvedScope is null and not loading', () => {
+    const { result } = renderHook(() =>
+      useDataTableScope({
+        selectedOrganisation: null,
+        selectedEvent: null,
+        supabase: {},
+        pageId: undefined,
+        pageName: undefined,
+      })
+    );
+    expect(result.current.consistentScope).toEqual({
+      organisationId: undefined,
+      eventId: undefined,
+      appId: undefined,
+    });
+  }, TEST_TIMEOUT);
+
+  it('with pageId and no pageName, can proceed with empty scope', () => {
+    mockUseResolvedScope.mockReturnValue({
+      resolvedScope: null,
+      isLoading: true,
+    });
+    const { result } = renderHook(() =>
+      useDataTableScope({
+        selectedOrganisation: null,
+        selectedEvent: null,
+        supabase: {},
+        pageId: 'users',
+        pageName: undefined,
+      })
+    );
+    expect(result.current.consistentScope).toEqual({
+      organisationId: undefined,
+      eventId: undefined,
+      appId: undefined,
+    });
+  }, TEST_TIMEOUT);
+
+  it('calls useResolvedScope with supabase and selected ids', () => {
+    const supabase = {};
+    renderHook(() =>
+      useDataTableScope({
+        selectedOrganisation: { id: 'org-1' },
+        selectedEvent: { event_id: 'ev-1', organisation_id: 'org-1' },
+        supabase,
+        pageId: undefined,
+        pageName: undefined,
+      })
+    );
+    expect(mockUseResolvedScope).toHaveBeenCalledWith(
+      expect.objectContaining({
+        supabase,
+        selectedOrganisationId: 'org-1',
+        selectedEventId: 'ev-1',
+        selectedEventOrganisationId: 'org-1',
+      })
+    );
+  }, TEST_TIMEOUT);
+});