@qwickapps/react-framework 1.5.7 → 1.5.8

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/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;

package/src/schemas/transformers/ReactNodeTransformer.ts

@@ -185,7 +185,8 @@ export class ReactNodeTransformer {
     }
 
     // Use Html component to render HTML content safely
-    return createElement(Html, { key, children: props.children });
+    const typedProps = props as Record<string, unknown>;
+    return createElement(Html, { key, children: typedProps.children });
   }
 
   /**
@@ -217,22 +218,24 @@ export class ReactNodeTransformer {
    * @returns Text content or null
    */
   private static extractTextContent(props: unknown): string | null {
-    if (!props) return null;
+    if (!props || typeof props !== 'object') return null;
 
-    if (typeof props.children === 'string') {
-      return props.children;
+    const typedProps = props as Record<string, unknown>;
+
+    if (typeof typedProps.children === 'string') {
+      return typedProps.children;
     }
 
-    if (props.title && typeof props.title === 'string') {
-      return props.title;
+    if (typedProps.title && typeof typedProps.title === 'string') {
+      return typedProps.title;
     }
 
-    if (props.label && typeof props.label === 'string') {
-      return props.label;
+    if (typedProps.label && typeof typedProps.label === 'string') {
+      return typedProps.label;
     }
 
-    if (props.text && typeof props.text === 'string') {
-      return props.text;
+    if (typedProps.text && typeof typedProps.text === 'string') {
+      return typedProps.text;
     }
 
     return null;

package/src/utils/iconMap.tsx

@@ -14,89 +14,108 @@
 
 import React from 'react';
 
-// Material UI Icons - sorted alphabetically
-import {
-  AccountCircle,
-  Add,
-  Architecture,
-  ArrowBack,
-  ArrowForward,
-  Article,
-  AttachMoney,
-  Autorenew,
-  Block,
-  Book,
-  Business,
-  Check,
-  CheckCircle,
-  Close,
-  Cloud,
-  CloudDownload,
-  CloudUpload,
-  Code,
-  Computer,
-  Construction,
-  Dashboard,
-  Delete,
-  Download,
-  Edit,
-  Email,
-  Explore,
-  Favorite,
-  Group,
-  Help,
-  HelpOutline,
-  Home,
-  Info,
-  InsertPhoto,
-  IntegrationInstructions,
-  Inventory,
-  Inventory2,
-  Key,
-  Layers,
-  LibraryBooks,
-  LocalOffer,
-  Lock,
-  LockOpen,
-  Login,
-  Logout,
-  ManageAccounts,
-  Memory,
-  Menu,
-  Notifications,
-  People,
-  Person,
-  PersonSearch,
-  Phone,
-  PhotoLibrary,
-  PlayArrow,
-  Psychology,
-  Refresh,
-  Rocket,
-  RotateRight,
-  Route,
-  Save,
-  Search,
-  Security,
-  Send,
-  Settings,
-  Share,
-  Shield,
-  ShoppingCart,
-  Speed,
-  Star,
-  Storage,
-  SupportAgent,
-  Sync,
-  TrendingUp,
-  Tune,
-  VerifiedUser,
-  Visibility,
-  VisibilityOff,
-  VpnKey,
-  Work,
-  WorkspacePremium,
-} from '@mui/icons-material';
+// Material UI Icons - Direct imports to avoid loading the entire barrel index
+// This prevents EMFILE errors when Node.js tries to parse thousands of icon exports
+import AccountCircle from '@mui/icons-material/AccountCircle';
+import Add from '@mui/icons-material/Add';
+import Architecture from '@mui/icons-material/Architecture';
+import ArrowBack from '@mui/icons-material/ArrowBack';
+import ArrowForward from '@mui/icons-material/ArrowForward';
+import Article from '@mui/icons-material/Article';
+import AttachMoney from '@mui/icons-material/AttachMoney';
+import Autorenew from '@mui/icons-material/Autorenew';
+import Block from '@mui/icons-material/Block';
+import Book from '@mui/icons-material/Book';
+import Business from '@mui/icons-material/Business';
+import Check from '@mui/icons-material/Check';
+import CheckCircle from '@mui/icons-material/CheckCircle';
+import Close from '@mui/icons-material/Close';
+import Cloud from '@mui/icons-material/Cloud';
+import CloudDownload from '@mui/icons-material/CloudDownload';
+import CloudUpload from '@mui/icons-material/CloudUpload';
+import Code from '@mui/icons-material/Code';
+import Computer from '@mui/icons-material/Computer';
+import Construction from '@mui/icons-material/Construction';
+import Dashboard from '@mui/icons-material/Dashboard';
+import Delete from '@mui/icons-material/Delete';
+import Download from '@mui/icons-material/Download';
+import Edit from '@mui/icons-material/Edit';
+import Email from '@mui/icons-material/Email';
+import Explore from '@mui/icons-material/Explore';
+import Favorite from '@mui/icons-material/Favorite';
+import Group from '@mui/icons-material/Group';
+import Help from '@mui/icons-material/Help';
+import HelpOutline from '@mui/icons-material/HelpOutline';
+import Home from '@mui/icons-material/Home';
+import Info from '@mui/icons-material/Info';
+import InsertPhoto from '@mui/icons-material/InsertPhoto';
+import IntegrationInstructions from '@mui/icons-material/IntegrationInstructions';
+import Inventory from '@mui/icons-material/Inventory';
+import Inventory2 from '@mui/icons-material/Inventory2';
+import Key from '@mui/icons-material/Key';
+import Layers from '@mui/icons-material/Layers';
+import LibraryBooks from '@mui/icons-material/LibraryBooks';
+import LocalOffer from '@mui/icons-material/LocalOffer';
+import Lock from '@mui/icons-material/Lock';
+import LockOpen from '@mui/icons-material/LockOpen';
+import Login from '@mui/icons-material/Login';
+import Logout from '@mui/icons-material/Logout';
+import ManageAccounts from '@mui/icons-material/ManageAccounts';
+import Memory from '@mui/icons-material/Memory';
+import Menu from '@mui/icons-material/Menu';
+import Notifications from '@mui/icons-material/Notifications';
+import People from '@mui/icons-material/People';
+import Person from '@mui/icons-material/Person';
+import PersonSearch from '@mui/icons-material/PersonSearch';
+import Phone from '@mui/icons-material/Phone';
+import PhotoLibrary from '@mui/icons-material/PhotoLibrary';
+import PlayArrow from '@mui/icons-material/PlayArrow';
+import Psychology from '@mui/icons-material/Psychology';
+import Refresh from '@mui/icons-material/Refresh';
+import Rocket from '@mui/icons-material/Rocket';
+import RotateRight from '@mui/icons-material/RotateRight';
+import Route from '@mui/icons-material/Route';
+import Save from '@mui/icons-material/Save';
+import Search from '@mui/icons-material/Search';
+import Security from '@mui/icons-material/Security';
+import Send from '@mui/icons-material/Send';
+import Settings from '@mui/icons-material/Settings';
+import Share from '@mui/icons-material/Share';
+import Shield from '@mui/icons-material/Shield';
+import ShoppingCart from '@mui/icons-material/ShoppingCart';
+import Speed from '@mui/icons-material/Speed';
+import Star from '@mui/icons-material/Star';
+import Storage from '@mui/icons-material/Storage';
+import SupportAgent from '@mui/icons-material/SupportAgent';
+import Sync from '@mui/icons-material/Sync';
+import TrendingUp from '@mui/icons-material/TrendingUp';
+import Tune from '@mui/icons-material/Tune';
+import VerifiedUser from '@mui/icons-material/VerifiedUser';
+import Visibility from '@mui/icons-material/Visibility';
+import VisibilityOff from '@mui/icons-material/VisibilityOff';
+import VpnKey from '@mui/icons-material/VpnKey';
+import Work from '@mui/icons-material/Work';
+import WorkspacePremium from '@mui/icons-material/WorkspacePremium';
+// Additional icons for components
+import Accessibility from '@mui/icons-material/Accessibility';
+import BrokenImage from '@mui/icons-material/BrokenImage';
+import Circle from '@mui/icons-material/Circle';
+import ContentCopy from '@mui/icons-material/ContentCopy';
+import DarkMode from '@mui/icons-material/DarkMode';
+import Error from '@mui/icons-material/Error';
+import ExpandLess from '@mui/icons-material/ExpandLess';
+import ExpandMore from '@mui/icons-material/ExpandMore';
+import FormatBold from '@mui/icons-material/FormatBold';
+import FormatItalic from '@mui/icons-material/FormatItalic';
+import FormatUnderlined from '@mui/icons-material/FormatUnderlined';
+import Launch from '@mui/icons-material/Launch';
+import LightMode from '@mui/icons-material/LightMode';
+import MoreVert from '@mui/icons-material/MoreVert';
+import Palette from '@mui/icons-material/Palette';
+import RadioButtonUnchecked from '@mui/icons-material/RadioButtonUnchecked';
+import Schedule from '@mui/icons-material/Schedule';
+import SettingsSystemDaydream from '@mui/icons-material/SettingsSystemDaydream';
+import Warning from '@mui/icons-material/Warning';
 
 /**
  * Icon mapping entry with both Material-UI component and emoji representation
@@ -235,6 +254,47 @@ export const iconMap: Record<string, IconMapping> = {
   person_search: { emoji: '🔍', component: PersonSearch },
   user: { emoji: '👤', component: Person }, // alias
   users: { emoji: '👥', component: People }, // alias
+
+  // === UI & Interaction ===
+  accessibility: { emoji: '♿', component: Accessibility },
+  broken_image: { emoji: '🖼️', component: BrokenImage },
+  brokenimage: { emoji: '🖼️', component: BrokenImage }, // alias
+  circle: { emoji: '⭕', component: Circle },
+  content_copy: { emoji: '📋', component: ContentCopy },
+  contentcopy: { emoji: '📋', component: ContentCopy }, // alias
+  copy: { emoji: '📋', component: ContentCopy }, // alias
+  dark_mode: { emoji: '🌙', component: DarkMode },
+  darkmode: { emoji: '🌙', component: DarkMode }, // alias
+  error: { emoji: '❌', component: Error },
+  expand_less: { emoji: '▲', component: ExpandLess },
+  expandless: { emoji: '▲', component: ExpandLess }, // alias
+  expand_more: { emoji: '▼', component: ExpandMore },
+  expandmore: { emoji: '▼', component: ExpandMore }, // alias
+  format_bold: { emoji: '𝐁', component: FormatBold },
+  formatbold: { emoji: '𝐁', component: FormatBold }, // alias
+  bold: { emoji: '𝐁', component: FormatBold }, // alias
+  format_italic: { emoji: '𝐼', component: FormatItalic },
+  formatitalic: { emoji: '𝐼', component: FormatItalic }, // alias
+  italic: { emoji: '𝐼', component: FormatItalic }, // alias
+  format_underlined: { emoji: 'U̲', component: FormatUnderlined },
+  formatunderlined: { emoji: 'U̲', component: FormatUnderlined }, // alias
+  underline: { emoji: 'U̲', component: FormatUnderlined }, // alias
+  launch: { emoji: '🚀', component: Launch },
+  open: { emoji: '🚀', component: Launch }, // alias
+  light_mode: { emoji: '☀️', component: LightMode },
+  lightmode: { emoji: '☀️', component: LightMode }, // alias
+  more_vert: { emoji: '⋮', component: MoreVert },
+  morevert: { emoji: '⋮', component: MoreVert }, // alias
+  more: { emoji: '⋮', component: MoreVert }, // alias
+  palette: { emoji: '🎨', component: Palette },
+  radio_button_unchecked: { emoji: '○', component: RadioButtonUnchecked },
+  radiobuttonunchecked: { emoji: '○', component: RadioButtonUnchecked }, // alias
+  schedule: { emoji: '📅', component: Schedule },
+  calendar: { emoji: '📅', component: Schedule }, // alias
+  settings_system_daydream: { emoji: '💻', component: SettingsSystemDaydream },
+  settingssystemdaydream: { emoji: '💻', component: SettingsSystemDaydream }, // alias
+  system: { emoji: '💻', component: SettingsSystemDaydream }, // alias
+  warning: { emoji: '⚠️', component: Warning },
 };
 
 /**