@qwickapps/react-framework 1.5.6 → 1.5.8

package/src/components/plugins/DataTable.tsx

@@ -0,0 +1,259 @@
+/**
+ * DataTable - Sortable, filterable table component for plugin management pages
+ *
+ * Provides consistent table UI with sorting, filtering, pagination, and bulk actions.
+ *
+ * @example
+ * ```tsx
+ * <DataTable
+ *   columns={[
+ *     { key: 'email', label: 'Email', sortable: true },
+ *     { key: 'status', label: 'Status', render: (val) => <Badge>{val}</Badge> }
+ *   ]}
+ *   data={users}
+ *   onRowClick={(user) => navigate(`/users/${user.id}`)}
+ *   bulkActions={[
+ *     { label: 'Delete', onClick: (rows) => handleDelete(rows), variant: 'danger' }
+ *   ]}
+ * />
+ * ```
+ */
+
+import React, { useState, useMemo } from 'react';
+
+export interface Column<T> {
+  /** Column key (must match data property) */
+  key: keyof T;
+
+  /** Display label */
+  label: string;
+
+  /** Enable sorting for this column */
+  sortable?: boolean;
+
+  /** Custom render function */
+  render?: (value: unknown, row: T) => React.ReactNode;
+
+  /** Column width (CSS value) */
+  width?: string;
+}
+
+export interface DataTableProps<T> {
+  /** Column definitions */
+  columns: Column<T>[];
+
+  /** Table data */
+  data: T[];
+
+  /** Row click handler */
+  onRowClick?: (row: T) => void;
+
+  /** Bulk action buttons */
+  bulkActions?: Array<{
+    label: string;
+    onClick: (selectedRows: T[]) => void;
+    variant?: 'primary' | 'secondary' | 'danger';
+  }>;
+
+  /** Enable row selection */
+  selectable?: boolean;
+
+  /** Empty state message */
+  emptyMessage?: string;
+
+  /** Loading state */
+  loading?: boolean;
+
+  /** Row key extractor */
+  getRowKey?: (row: T, index: number) => string | number;
+}
+
+export function DataTable<T = Record<string, unknown>>({
+  columns,
+  data,
+  onRowClick,
+  bulkActions = [],
+  selectable = bulkActions.length > 0,
+  emptyMessage = 'No data available',
+  loading = false,
+  getRowKey = (row: T, index: number) => {
+    // Type-safe check for id property
+    const rowObj = row as Record<string, unknown>;
+    const hasValidId = 'id' in rowObj &&
+      (typeof rowObj.id === 'string' || typeof rowObj.id === 'number');
+    return hasValidId ? (rowObj.id as string | number) : index;
+  },
+}: DataTableProps<T>) {
+  const [selectedRows, setSelectedRows] = useState<Set<string | number>>(new Set());
+  const [sortColumn, setSortColumn] = useState<keyof T | null>(null);
+  const [sortDirection, setSortDirection] = useState<'asc' | 'desc'>('asc');
+
+  // Sorted data
+  const sortedData = useMemo(() => {
+    if (!sortColumn) return data;
+
+    return [...data].sort((a, b) => {
+      const aVal = a[sortColumn];
+      const bVal = b[sortColumn];
+
+      if (aVal === bVal) return 0;
+
+      const comparison = aVal < bVal ? -1 : 1;
+      return sortDirection === 'asc' ? comparison : -comparison;
+    });
+  }, [data, sortColumn, sortDirection]);
+
+  const handleSort = (column: keyof T) => {
+    if (sortColumn === column) {
+      setSortDirection(sortDirection === 'asc' ? 'desc' : 'asc');
+    } else {
+      setSortColumn(column);
+      setSortDirection('asc');
+    }
+  };
+
+  const handleSelectAll = () => {
+    if (selectedRows.size === data.length) {
+      setSelectedRows(new Set());
+    } else {
+      setSelectedRows(new Set(data.map((row, index) => getRowKey(row, index))));
+    }
+  };
+
+  const handleSelectRow = (rowKey: string | number) => {
+    const newSelection = new Set(selectedRows);
+    if (newSelection.has(rowKey)) {
+      newSelection.delete(rowKey);
+    } else {
+      newSelection.add(rowKey);
+    }
+    setSelectedRows(newSelection);
+  };
+
+  const getSelectedRowData = () => {
+    return data.filter((row, index) =>
+      selectedRows.has(getRowKey(row, index))
+    );
+  };
+
+  if (loading) {
+    return (
+      <div className="animate-pulse space-y-2">
+        <div className="h-10 bg-gray-200 dark:bg-gray-700 rounded"></div>
+        <div className="h-16 bg-gray-200 dark:bg-gray-700 rounded"></div>
+        <div className="h-16 bg-gray-200 dark:bg-gray-700 rounded"></div>
+      </div>
+    );
+  }
+
+  if (data.length === 0) {
+    return (
+      <div className="text-center py-12 text-gray-500 dark:text-gray-400">
+        {emptyMessage}
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-4">
+      {/* Bulk Actions */}
+      {selectable && selectedRows.size > 0 && bulkActions.length > 0 && (
+        <div className="flex items-center gap-3 p-3 bg-blue-50 dark:bg-blue-900/20 rounded-lg">
+          <span className="text-sm font-medium text-blue-900 dark:text-blue-100">
+            {selectedRows.size} selected
+          </span>
+          {bulkActions.map((action, index) => (
+            <button
+              key={index}
+              onClick={() => action.onClick(getSelectedRowData())}
+              className={`
+                px-3 py-1.5 rounded text-sm font-medium
+                ${action.variant === 'danger'
+                  ? 'bg-red-600 hover:bg-red-700 text-white'
+                  : 'bg-blue-600 hover:bg-blue-700 text-white'}
+              `}
+            >
+              {action.label}
+            </button>
+          ))}
+        </div>
+      )}
+
+      {/* Table */}
+      <div className="overflow-x-auto rounded-lg border border-gray-200 dark:border-gray-700">
+        <table className="min-w-full divide-y divide-gray-200 dark:divide-gray-700">
+          <thead className="bg-gray-50 dark:bg-gray-800">
+            <tr>
+              {selectable && (
+                <th className="w-12 px-4 py-3">
+                  <input
+                    type="checkbox"
+                    checked={selectedRows.size === data.length && data.length > 0}
+                    onChange={handleSelectAll}
+                    className="rounded"
+                  />
+                </th>
+              )}
+              {columns.map((column) => (
+                <th
+                  key={String(column.key)}
+                  style={{ width: column.width }}
+                  className={`
+                    px-4 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider
+                    ${column.sortable ? 'cursor-pointer hover:bg-gray-100 dark:hover:bg-gray-700' : ''}
+                  `}
+                  onClick={() => column.sortable && handleSort(column.key)}
+                >
+                  <div className="flex items-center gap-2">
+                    {column.label}
+                    {column.sortable && sortColumn === column.key && (
+                      <span>{sortDirection === 'asc' ? '↑' : '↓'}</span>
+                    )}
+                  </div>
+                </th>
+              ))}
+            </tr>
+          </thead>
+          <tbody className="bg-white dark:bg-gray-900 divide-y divide-gray-200 dark:divide-gray-700">
+            {sortedData.map((row, rowIndex) => {
+              const rowKey = getRowKey(row, rowIndex);
+              const isSelected = selectedRows.has(rowKey);
+
+              return (
+                <tr
+                  key={rowKey}
+                  className={`
+                    ${onRowClick ? 'cursor-pointer hover:bg-gray-50 dark:hover:bg-gray-800' : ''}
+                    ${isSelected ? 'bg-blue-50 dark:bg-blue-900/20' : ''}
+                  `}
+                  onClick={() => onRowClick?.(row)}
+                >
+                  {selectable && (
+                    <td className="px-4 py-3" onClick={(e) => e.stopPropagation()}>
+                      <input
+                        type="checkbox"
+                        checked={isSelected}
+                        onChange={() => handleSelectRow(rowKey)}
+                        className="rounded"
+                      />
+                    </td>
+                  )}
+                  {columns.map((column) => (
+                    <td
+                      key={String(column.key)}
+                      className="px-4 py-3 text-sm text-gray-900 dark:text-gray-100"
+                    >
+                      {column.render
+                        ? column.render(row[column.key], row)
+                        : String(row[column.key] ?? '')}
+                    </td>
+                  ))}
+                </tr>
+              );
+            })}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+}

package/src/components/plugins/StatCard.tsx

@@ -0,0 +1,122 @@
+/**
+ * StatCard - Display a single metric with optional trend indicator
+ *
+ * Used in plugin status widgets to show key metrics at a glance.
+ *
+ * @example
+ * ```tsx
+ * <StatCard
+ *   label="Active Connections"
+ *   value={42}
+ *   unit="connections"
+ *   trend={{ value: 12, direction: 'up' }}
+ *   status="healthy"
+ * />
+ * ```
+ */
+
+import React from 'react';
+
+export interface StatCardProps {
+  /** Label describing the metric */
+  label: string;
+
+  /** Current value */
+  value: number | string;
+
+  /** Optional unit (e.g., "MB", "requests/sec") */
+  unit?: string;
+
+  /** Optional suffix (alias for unit, for backward compatibility) */
+  suffix?: string;
+
+  /** Optional trend indicator */
+  trend?: {
+    value: number;
+    direction: 'up' | 'down' | 'stable';
+  };
+
+  /** Status indicator */
+  status?: 'healthy' | 'warning' | 'error' | 'info';
+
+  /** Optional click handler */
+  onClick?: () => void;
+
+  /** Optional icon */
+  icon?: React.ReactNode;
+
+  /** Optional sub-value displayed below the label */
+  subValue?: string;
+
+  /** Optional custom color for the icon/accent */
+  color?: string;
+}
+
+export const StatCard: React.FC<StatCardProps> = ({
+  label,
+  value,
+  unit,
+  suffix,
+  trend,
+  status = 'info',
+  onClick,
+  icon,
+  subValue,
+  color,
+}) => {
+  // Use suffix as fallback for unit (backward compatibility)
+  const displayUnit = unit || suffix;
+  const statusColors = {
+    healthy: 'text-green-600 dark:text-green-400 bg-green-50 dark:bg-green-900/20',
+    warning: 'text-yellow-600 dark:text-yellow-400 bg-yellow-50 dark:bg-yellow-900/20',
+    error: 'text-red-600 dark:text-red-400 bg-red-50 dark:bg-red-900/20',
+    info: 'text-blue-600 dark:text-blue-400 bg-blue-50 dark:bg-blue-900/20',
+  };
+
+  const trendIcons = {
+    up: '↑',
+    down: '↓',
+    stable: '→',
+  };
+
+  return (
+    <div
+      className={`
+        rounded-lg border p-4
+        ${statusColors[status]}
+        ${onClick ? 'cursor-pointer hover:shadow-md transition-shadow' : ''}
+      `}
+      onClick={onClick}
+      role={onClick ? 'button' : undefined}
+      tabIndex={onClick ? 0 : undefined}
+    >
+      <div className="flex items-start justify-between">
+        <div className="flex-1">
+          <p className="text-sm font-medium opacity-80">{label}</p>
+          <div className="mt-1 flex items-baseline gap-2">
+            <p className="text-2xl font-semibold">
+              {value}
+            </p>
+            {displayUnit && (
+              <span className="text-sm opacity-70">{displayUnit}</span>
+            )}
+          </div>
+          {subValue && (
+            <p className="text-xs opacity-70 mt-1">{subValue}</p>
+          )}
+          {trend && (
+            <div className="mt-2 flex items-center gap-1 text-sm">
+              <span>{trendIcons[trend.direction]}</span>
+              <span>{trend.value}%</span>
+            </div>
+          )}
+        </div>
+        {icon && (
+          <div className="ml-4 text-2xl opacity-70" style={color ? { color } : undefined}>
+            {icon}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+};

package/src/components/plugins/__tests__/DataTable.test.tsx

@@ -0,0 +1,158 @@
+/**
+ * DataTable tests
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { DataTable, type Column, type DataTableProps } from '../DataTable';
+
+describe('DataTable', () => {
+  interface TestRow {
+    id: number;
+    name: string;
+    email: string;
+  }
+
+  const mockData: TestRow[] = [
+    { id: 1, name: 'Alice', email: 'alice@example.com' },
+    { id: 2, name: 'Bob', email: 'bob@example.com' },
+    { id: 3, name: 'Charlie', email: 'charlie@example.com' },
+  ];
+
+  const mockColumns: Column<TestRow>[] = [
+    { key: 'id', label: 'ID', sortable: true },
+    { key: 'name', label: 'Name', sortable: true },
+    { key: 'email', label: 'Email', sortable: true },
+  ];
+
+  describe('Type Safety', () => {
+    it('should accept generic type parameter correctly', () => {
+      const props: DataTableProps<TestRow> = {
+        columns: mockColumns,
+        data: mockData,
+      };
+
+      expect(props.columns).toBeDefined();
+      expect(props.data).toBeDefined();
+    });
+
+    it('should have type-safe column keys', () => {
+      // This test verifies that TypeScript enforces column keys match the data type
+      const validColumn: Column<TestRow> = { key: 'name', label: 'Name' };
+      expect(validColumn.key).toBe('name');
+
+      // TypeScript should prevent invalid keys at compile time
+      // @ts-expect-error - invalid key should cause type error
+      const invalidColumn: Column<TestRow> = { key: 'invalid', label: 'Invalid' };
+      expect(invalidColumn).toBeDefined(); // Just to use the variable
+    });
+
+    it('should handle getRowKey with type-safe id extraction', () => {
+      // Test the default getRowKey behavior
+      const { container } = render(
+        <DataTable<TestRow> columns={mockColumns} data={mockData} />
+      );
+
+      expect(container).toBeInTheDocument();
+      // The component should render rows using ids as keys
+      // This verifies the type-safe id extraction works
+    });
+
+    it('should handle custom getRowKey function', () => {
+      const customGetRowKey = (row: TestRow, index: number) => `row-${row.id}-${index}`;
+
+      render(
+        <DataTable<TestRow>
+          columns={mockColumns}
+          data={mockData}
+          getRowKey={customGetRowKey}
+        />
+      );
+
+      // Component should render with custom keys
+      expect(screen.getByText('Alice')).toBeInTheDocument();
+    });
+
+    it('should handle rows without id property using index fallback', () => {
+      interface RowWithoutId {
+        name: string;
+      }
+
+      const dataWithoutId: RowWithoutId[] = [
+        { name: 'Alice' },
+        { name: 'Bob' },
+      ];
+
+      const columnsWithoutId: Column<RowWithoutId>[] = [
+        { key: 'name', label: 'Name' },
+      ];
+
+      const { container } = render(
+        <DataTable<RowWithoutId> columns={columnsWithoutId} data={dataWithoutId} />
+      );
+
+      expect(container).toBeInTheDocument();
+      expect(screen.getByText('Alice')).toBeInTheDocument();
+      expect(screen.getByText('Bob')).toBeInTheDocument();
+    });
+  });
+
+  describe('Component Rendering', () => {
+    it('should render empty message when data is empty', () => {
+      render(
+        <DataTable<TestRow>
+          columns={mockColumns}
+          data={[]}
+          emptyMessage="No users found"
+        />
+      );
+
+      expect(screen.getByText('No users found')).toBeInTheDocument();
+    });
+
+    it('should render loading state', () => {
+      const { container } = render(
+        <DataTable<TestRow> columns={mockColumns} data={mockData} loading={true} />
+      );
+
+      // Check for loading skeleton (has animate-pulse class)
+      const loadingSkeleton = container.querySelector('.animate-pulse');
+      expect(loadingSkeleton).toBeInTheDocument();
+    });
+
+    it('should render column headers', () => {
+      render(<DataTable<TestRow> columns={mockColumns} data={mockData} />);
+
+      expect(screen.getByText('ID')).toBeInTheDocument();
+      expect(screen.getByText('Name')).toBeInTheDocument();
+      expect(screen.getByText('Email')).toBeInTheDocument();
+    });
+
+    it('should render data rows', () => {
+      render(<DataTable<TestRow> columns={mockColumns} data={mockData} />);
+
+      expect(screen.getByText('Alice')).toBeInTheDocument();
+      expect(screen.getByText('Bob')).toBeInTheDocument();
+      expect(screen.getByText('Charlie')).toBeInTheDocument();
+      expect(screen.getByText('alice@example.com')).toBeInTheDocument();
+    });
+
+    it('should use custom render function when provided', () => {
+      const columnsWithCustomRender: Column<TestRow>[] = [
+        {
+          key: 'name',
+          label: 'Name',
+          render: (value) => <strong>{String(value)}</strong>,
+        },
+      ];
+
+      render(<DataTable<TestRow> columns={columnsWithCustomRender} data={mockData} />);
+
+      const strongElement = screen.getByText('Alice').closest('strong');
+      expect(strongElement).toBeInTheDocument();
+    });
+  });
+});

package/src/components/plugins/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Generic UI Components
+ *
+ * Reusable UI primitives for building admin interfaces.
+ * Server-specific plugin patterns are in @qwickapps/server/ui
+ *
+ * @packageDocumentation
+ */
+
+export { StatCard } from './StatCard.js';
+export type { StatCardProps } from './StatCard.js';
+
+export { DataTable } from './DataTable.js';
+export type { DataTableProps, Column } from './DataTable.js';

package/src/components/shared/createSerializableView.tsx

@@ -154,11 +154,11 @@ export function createSerializableView<P extends ViewProps>(
 
   // Attach static properties for serialization
   const component = SerializableViewComponent as unknown as SerializableComponent<P>;
-  
+
   // Component identification
   component.tagName = tagName;
   component.version = version;
-  component[QWICKAPP_COMPONENT] = QWICKAPP_COMPONENT;
+  Object.assign(component, { [QWICKAPP_COMPONENT]: QWICKAPP_COMPONENT });
 
   // Serialization methods
   component.fromJson = function fromJson(data: unknown): ReactElement {
@@ -178,8 +178,9 @@ export function createSerializableView<P extends ViewProps>(
     if (childrenStrategy.mode === 'content-prop') {
       const propName = childrenStrategy.propName || 'content';
       // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      const { children, ...rest } = componentData || {};
-      const contentData = { ...rest, [propName]: componentData?.[propName] || '' };
+      const typedComponentData = (componentData as Record<string, unknown>) || {};
+      const { children, ...rest } = typedComponentData;
+      const contentData = { ...rest, [propName]: typedComponentData[propName] || '' };
       return React.createElement(component as ComponentType<P>, contentData as P);
     } else {
       // For react-children strategy, recursively deserialize children
@@ -197,8 +198,9 @@ export function createSerializableView<P extends ViewProps>(
     if (childrenStrategy.mode === 'content-prop') {
       const propName = childrenStrategy.propName || 'content';
       // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      const { children, ...rest } = props || {};
-      const contentValue = (props as Record<string, unknown>)?.[propName] ?? toText((props as Record<string, unknown>)?.children as ReactNode);
+      const typedProps = (props as Record<string, unknown>) || {};
+      const { children, ...rest } = typedProps;
+      const contentValue = typedProps[propName] ?? toText(typedProps.children as ReactNode);
 
       // Clean props for content-prop serialization
       const cleanProps: Record<string, unknown> = {};

package/src/contexts/NavigationContext.tsx

@@ -15,7 +15,7 @@ import { createContext, useContext, type ReactNode } from 'react';
 import {
   useNavigate,
   useLocation,
-  UNSAFE_NavigationContext as RouterContext,
+  useInRouterContext,
 } from 'react-router-dom';
 
 /**
@@ -58,17 +58,23 @@ function ReactRouterNavigationProvider({ children }: { children: ReactNode }) {
     }
   };
 
+  // Defensive check for location - fall back to window.location if React Router's location is undefined
+  const location: NavigationLocation | undefined = reactRouterLocation
+    ? {
+        pathname: reactRouterLocation.pathname,
+        search: reactRouterLocation.search,
+        hash: reactRouterLocation.hash,
+      }
+    : typeof window !== 'undefined'
+      ? {
+          pathname: window.location.pathname,
+          search: window.location.search,
+          hash: window.location.hash,
+        }
+      : undefined;
+
   return (
-    <NavigationContext.Provider
-      value={{
-        navigate,
-        location: {
-          pathname: reactRouterLocation.pathname,
-          search: reactRouterLocation.search,
-          hash: reactRouterLocation.hash,
-        },
-      }}
-    >
+    <NavigationContext.Provider value={{ navigate, location }}>
       {children}
     </NavigationContext.Provider>
   );
@@ -115,11 +121,11 @@ function FallbackNavigationProvider({ children }: { children: ReactNode }) {
  * This is included automatically by QwickApp - you don't need to add it manually.
  */
 export function NavigationProvider({ children }: { children: ReactNode }) {
-  // Check if we're inside a React Router by checking its internal context
-  // useContext doesn't throw - it returns null if the context doesn't exist
-  const routerContext = useContext(RouterContext);
+  // Check if we're inside a React Router using the official hook
+  // This is more reliable than checking internal UNSAFE contexts
+  const isInRouter = useInRouterContext();
 
-  if (routerContext) {
+  if (isInRouter) {
     // We're inside a Router, use React Router's navigation
     return (
       <ReactRouterNavigationProvider>{children}</ReactRouterNavigationProvider>

package/src/hooks/useBaseProps.ts

@@ -264,4 +264,4 @@ export function useBaseProps<T extends BaseComponentProps>(props: T) {
 /**
  * Type helper for components using base props
  */
-export type WithBaseProps<P = Record<string, never>> = P & BaseComponentProps;
+export type WithBaseProps<P = object> = P & BaseComponentProps;