@qwickapps/server 1.2.0 → 1.3.1

package/ui/src/components/index.ts

@@ -0,0 +1,62 @@
+/**
+ * Control Panel UI Components
+ *
+ * Re-exports all public UI components for use by consumers.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+export { ControlPanelApp, type ControlPanelAppProps } from './ControlPanelApp';
+
+// Re-export MenuItem from react-framework for convenience
+export type { MenuItem } from '@qwickapps/react-framework';
+
+// Re-export base pages for consumers who want to use them directly
+export { DashboardPage } from '../pages/DashboardPage';
+export { LogsPage } from '../pages/LogsPage';
+export { SystemPage } from '../pages/SystemPage';
+export { NotFoundPage } from '../pages/NotFoundPage';
+export { UsersPage, type UsersPageProps } from '../pages/UsersPage';
+export { EntitlementsPage, type EntitlementsPageProps } from '../pages/EntitlementsPage';
+
+// Re-export dashboard widget system (legacy context-based + new plugin-based)
+export {
+  // Legacy context-based widget system
+  DashboardWidgetProvider,
+  useDashboardWidgets,
+  useRegisterWidget,
+  DashboardWidgetRenderer,
+  type DashboardWidget,
+  type DashboardWidgetProviderProps,
+  // New plugin-based widget system
+  WidgetComponentRegistryProvider,
+  useWidgetComponentRegistry,
+  PluginWidgetRenderer,
+  getBuiltInWidgetComponents,
+  ServiceHealthWidget,
+  type WidgetComponent,
+  type WidgetComponentRegistryProviderProps,
+} from '../dashboard';
+
+// Re-export API client and types
+export { api } from '../api/controlPanelApi';
+export type {
+  HealthCheck,
+  HealthResponse,
+  InfoResponse,
+  DiagnosticsResponse,
+  ConfigResponse,
+  LogEntry,
+  LogsResponse,
+  LogSource,
+  // User management types
+  User,
+  UsersResponse,
+  Ban,
+  BansResponse,
+  EntitlementDefinition,
+  EntitlementResult,
+  EntitlementSourceInfo,
+  EntitlementsStatus,
+  PluginFeatures,
+} from '../api/controlPanelApi';

package/ui/src/dashboard/DashboardWidgetRegistry.tsx

@@ -0,0 +1,129 @@
+/**
+ * Dashboard Widget Registry
+ *
+ * A context-based registry for dashboard widgets that allows:
+ * - Registration of widgets at runtime
+ * - Dynamic adding/removing of widgets
+ * - Priority-based ordering of widgets
+ *
+ * Usage:
+ * ```tsx
+ * // In your app setup:
+ * const { registerWidget } = useDashboardWidgets();
+ * registerWidget({
+ *   id: 'user-stats',
+ *   title: 'User Statistics',
+ *   component: <UserStatsWidget />,
+ *   priority: 10,
+ * });
+ *
+ * // Or via the provider:
+ * <DashboardWidgetProvider initialWidgets={[...]} />
+ * ```
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { createContext, useContext, useState, useCallback, ReactNode } from 'react';
+
+export interface DashboardWidget {
+  /** Unique identifier for the widget */
+  id: string;
+  /** Display title for the widget section */
+  title?: string;
+  /** The widget component to render */
+  component: ReactNode;
+  /** Priority for ordering (lower = first, default: 100) */
+  priority?: number;
+  /** Whether the widget is visible */
+  visible?: boolean;
+}
+
+interface DashboardWidgetContextValue {
+  /** All registered widgets */
+  widgets: DashboardWidget[];
+  /** Register a new widget */
+  registerWidget: (widget: DashboardWidget) => void;
+  /** Unregister a widget by ID */
+  unregisterWidget: (id: string) => void;
+  /** Toggle widget visibility */
+  toggleWidget: (id: string, visible?: boolean) => void;
+  /** Get visible widgets sorted by priority */
+  getVisibleWidgets: () => DashboardWidget[];
+}
+
+const DashboardWidgetContext = createContext<DashboardWidgetContextValue | null>(null);
+
+export interface DashboardWidgetProviderProps {
+  /** Initial widgets to register */
+  initialWidgets?: DashboardWidget[];
+  children: ReactNode;
+}
+
+export function DashboardWidgetProvider({ initialWidgets = [], children }: DashboardWidgetProviderProps) {
+  const [widgets, setWidgets] = useState<DashboardWidget[]>(
+    initialWidgets.map(w => ({ ...w, visible: w.visible !== false, priority: w.priority ?? 100 }))
+  );
+
+  const registerWidget = useCallback((widget: DashboardWidget) => {
+    setWidgets(prev => {
+      // Check if widget already exists
+      const exists = prev.some(w => w.id === widget.id);
+      if (exists) {
+        // Update existing widget
+        return prev.map(w => w.id === widget.id ? { ...widget, visible: widget.visible !== false, priority: widget.priority ?? 100 } : w);
+      }
+      // Add new widget
+      return [...prev, { ...widget, visible: widget.visible !== false, priority: widget.priority ?? 100 }];
+    });
+  }, []);
+
+  const unregisterWidget = useCallback((id: string) => {
+    setWidgets(prev => prev.filter(w => w.id !== id));
+  }, []);
+
+  const toggleWidget = useCallback((id: string, visible?: boolean) => {
+    setWidgets(prev => prev.map(w => {
+      if (w.id === id) {
+        return { ...w, visible: visible ?? !w.visible };
+      }
+      return w;
+    }));
+  }, []);
+
+  const getVisibleWidgets = useCallback(() => {
+    return widgets
+      .filter(w => w.visible !== false)
+      .sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+  }, [widgets]);
+
+  return (
+    <DashboardWidgetContext.Provider value={{ widgets, registerWidget, unregisterWidget, toggleWidget, getVisibleWidgets }}>
+      {children}
+    </DashboardWidgetContext.Provider>
+  );
+}
+
+export function useDashboardWidgets() {
+  const context = useContext(DashboardWidgetContext);
+  if (!context) {
+    throw new Error('useDashboardWidgets must be used within a DashboardWidgetProvider');
+  }
+  return context;
+}
+
+/**
+ * Hook to register a widget on mount and unregister on unmount
+ */
+export function useRegisterWidget(widget: DashboardWidget) {
+  const { registerWidget, unregisterWidget } = useDashboardWidgets();
+
+  // Register on mount
+  useState(() => {
+    registerWidget(widget);
+    return null;
+  });
+
+  // Return unregister function for manual cleanup
+  return () => unregisterWidget(widget.id);
+}

package/ui/src/dashboard/DashboardWidgetRenderer.tsx

@@ -0,0 +1,34 @@
+/**
+ * Dashboard Widget Renderer
+ *
+ * Renders all visible dashboard widgets from the registry.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { Box, Typography } from '@mui/material';
+import { useDashboardWidgets } from './DashboardWidgetRegistry';
+
+export function DashboardWidgetRenderer() {
+  const { getVisibleWidgets } = useDashboardWidgets();
+  const widgets = getVisibleWidgets();
+
+  if (widgets.length === 0) {
+    return null;
+  }
+
+  return (
+    <>
+      {widgets.map(widget => (
+        <Box key={widget.id} sx={{ mt: 4 }}>
+          {widget.title && (
+            <Typography variant="h6" sx={{ mb: 2, color: 'var(--theme-text-primary)' }}>
+              {widget.title}
+            </Typography>
+          )}
+          {widget.component}
+        </Box>
+      ))}
+    </>
+  );
+}

package/ui/src/dashboard/PluginWidgetRenderer.tsx

@@ -0,0 +1,118 @@
+/**
+ * Plugin Widget Renderer
+ *
+ * Fetches widget contributions from the server API and renders them using
+ * the WidgetComponentRegistry to resolve component names to React components.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { useState, useEffect } from 'react';
+import { Box, Typography, CircularProgress, Alert } from '@mui/material';
+import { api } from '../api/controlPanelApi';
+import { useWidgetComponentRegistry } from './WidgetComponentRegistry';
+
+/**
+ * Widget contribution from the server
+ */
+interface WidgetContribution {
+  id: string;
+  title: string;
+  component: string;
+  priority?: number;
+  showByDefault?: boolean;
+  pluginId: string;
+}
+
+interface PluginWidgetRendererProps {
+  /** Only show widgets marked as showByDefault (default: true) */
+  defaultOnly?: boolean;
+  /** Additional widget IDs to show (beyond showByDefault) */
+  additionalWidgetIds?: string[];
+}
+
+/**
+ * Renders widgets from plugins that have registered them via the server API
+ */
+export function PluginWidgetRenderer({
+  defaultOnly = true,
+  additionalWidgetIds = [],
+}: PluginWidgetRendererProps) {
+  const [widgets, setWidgets] = useState<WidgetContribution[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const { getComponent, hasComponent } = useWidgetComponentRegistry();
+
+  useEffect(() => {
+    const fetchWidgets = async () => {
+      try {
+        const data = await api.getUiContributions();
+        setWidgets(data.widgets || []);
+        setError(null);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Failed to fetch widgets');
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    fetchWidgets();
+  }, []);
+
+  if (loading) {
+    return (
+      <Box sx={{ display: 'flex', justifyContent: 'center', py: 4 }}>
+        <CircularProgress size={24} />
+      </Box>
+    );
+  }
+
+  if (error) {
+    return (
+      <Alert severity="error" sx={{ mt: 2 }}>
+        {error}
+      </Alert>
+    );
+  }
+
+  // Filter widgets to show
+  const visibleWidgets = widgets
+    .filter(widget => {
+      // Show if marked as default, or if in additionalWidgetIds
+      if (defaultOnly) {
+        return widget.showByDefault || additionalWidgetIds.includes(widget.id);
+      }
+      return true;
+    })
+    .filter(widget => {
+      // Only show widgets that have a registered component
+      if (!hasComponent(widget.component)) {
+        console.warn(`Widget "${widget.id}" references unregistered component "${widget.component}"`);
+        return false;
+      }
+      return true;
+    })
+    .sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+
+  if (visibleWidgets.length === 0) {
+    return null;
+  }
+
+  return (
+    <>
+      {visibleWidgets.map(widget => {
+        const Component = getComponent(widget.component);
+        return (
+          <Box key={widget.id} sx={{ mt: 4 }}>
+            {widget.title && (
+              <Typography variant="h6" sx={{ mb: 2, color: 'var(--theme-text-primary)' }}>
+                {widget.title}
+              </Typography>
+            )}
+            {Component && <Component />}
+          </Box>
+        );
+      })}
+    </>
+  );
+}

package/ui/src/dashboard/WidgetComponentRegistry.tsx

@@ -0,0 +1,120 @@
+/**
+ * Widget Component Registry
+ *
+ * Maps widget component names (from server-side WidgetContribution) to actual React components.
+ * Plugins register their widgets here so the dashboard can render them.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React, { createContext, useContext, useState, useCallback, useMemo, type ReactNode } from 'react';
+
+/**
+ * Widget component definition
+ *
+ * IMPORTANT: We store component functions (ComponentType), not JSX instances (ReactNode).
+ * This ensures cross-React-version compatibility when the library is used in apps
+ * with different React versions.
+ */
+export interface WidgetComponent {
+  /** Component name (must match server-side WidgetContribution.component) */
+  name: string;
+  /** The React component function to render */
+  component: React.ComponentType;
+}
+
+interface WidgetComponentRegistryContextValue {
+  /** Register a widget component */
+  registerComponent: (name: string, component: React.ComponentType) => void;
+  /** Register multiple widget components */
+  registerComponents: (components: WidgetComponent[]) => void;
+  /** Get a component by name */
+  getComponent: (name: string) => React.ComponentType | null;
+  /** Check if a component is registered */
+  hasComponent: (name: string) => boolean;
+  /** Get all registered component names */
+  getRegisteredNames: () => string[];
+}
+
+const WidgetComponentRegistryContext = createContext<WidgetComponentRegistryContextValue | null>(null);
+
+export interface WidgetComponentRegistryProviderProps {
+  /** Initial components to register */
+  initialComponents?: WidgetComponent[];
+  children: ReactNode;
+}
+
+/**
+ * Provider for the widget component registry
+ */
+export function WidgetComponentRegistryProvider({
+  initialComponents = [],
+  children,
+}: WidgetComponentRegistryProviderProps) {
+  const [components, setComponents] = useState<Map<string, React.ComponentType>>(() => {
+    const map = new Map<string, React.ComponentType>();
+    for (const comp of initialComponents) {
+      map.set(comp.name, comp.component);
+    }
+    return map;
+  });
+
+  const registerComponent = useCallback((name: string, component: React.ComponentType) => {
+    setComponents(prev => {
+      const next = new Map(prev);
+      next.set(name, component);
+      return next;
+    });
+  }, []);
+
+  const registerComponents = useCallback((comps: WidgetComponent[]) => {
+    setComponents(prev => {
+      const next = new Map(prev);
+      for (const comp of comps) {
+        next.set(comp.name, comp.component);
+      }
+      return next;
+    });
+  }, []);
+
+  const getComponent = useCallback((name: string): React.ComponentType | null => {
+    return components.get(name) ?? null;
+  }, [components]);
+
+  const hasComponent = useCallback((name: string): boolean => {
+    return components.has(name);
+  }, [components]);
+
+  const getRegisteredNames = useCallback((): string[] => {
+    return Array.from(components.keys());
+  }, [components]);
+
+  // Memoize context value to prevent unnecessary re-renders of consumers
+  const contextValue = useMemo(
+    () => ({
+      registerComponent,
+      registerComponents,
+      getComponent,
+      hasComponent,
+      getRegisteredNames,
+    }),
+    [registerComponent, registerComponents, getComponent, hasComponent, getRegisteredNames]
+  );
+
+  return (
+    <WidgetComponentRegistryContext.Provider value={contextValue}>
+      {children}
+    </WidgetComponentRegistryContext.Provider>
+  );
+}
+
+/**
+ * Hook to access the widget component registry
+ */
+export function useWidgetComponentRegistry() {
+  const context = useContext(WidgetComponentRegistryContext);
+  if (!context) {
+    throw new Error('useWidgetComponentRegistry must be used within a WidgetComponentRegistryProvider');
+  }
+  return context;
+}

package/ui/src/dashboard/builtInWidgets.tsx

@@ -0,0 +1,35 @@
+/**
+ * Built-in Widget Components
+ *
+ * Maps built-in widget component names to their React components.
+ * These are the widgets that qwickapps-server provides out of the box.
+ *
+ * IMPORTANT: We export component functions, not JSX instances.
+ * This ensures cross-React-version compatibility.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { ServiceHealthWidget } from './widgets';
+import type { WidgetComponent } from './WidgetComponentRegistry';
+
+/**
+ * Map of built-in widget component names to their React component functions.
+ * Use this when you need to look up a component by name.
+ */
+export const builtInWidgetComponents: Record<string, React.ComponentType> = {
+  ServiceHealthWidget: ServiceHealthWidget,
+};
+
+/**
+ * Get built-in widget components as WidgetComponent array.
+ * Use this when registering with WidgetComponentRegistryProvider.
+ *
+ * Returns component functions (not JSX instances) to ensure compatibility
+ * across different React versions.
+ */
+export function getBuiltInWidgetComponents(): WidgetComponent[] {
+  return [
+    { name: 'ServiceHealthWidget', component: ServiceHealthWidget },
+  ];
+}

package/ui/src/dashboard/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Dashboard Module
+ *
+ * Exports the dashboard widget system for dynamic dashboard customization.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+// Legacy context-based widget system (for backwards compatibility)
+export {
+  DashboardWidgetProvider,
+  useDashboardWidgets,
+  useRegisterWidget,
+  type DashboardWidget,
+  type DashboardWidgetProviderProps,
+} from './DashboardWidgetRegistry';
+
+export { DashboardWidgetRenderer } from './DashboardWidgetRenderer';
+
+// New plugin-based widget system
+export {
+  WidgetComponentRegistryProvider,
+  useWidgetComponentRegistry,
+  type WidgetComponent,
+  type WidgetComponentRegistryProviderProps,
+} from './WidgetComponentRegistry';
+
+export { PluginWidgetRenderer } from './PluginWidgetRenderer';
+
+// Built-in widgets
+export { ServiceHealthWidget } from './widgets';
+
+// Built-in widget component map (component name -> React component function)
+// Product code should use getBuiltInWidgetComponents() to get the full list with JSX
+export { builtInWidgetComponents, getBuiltInWidgetComponents } from './builtInWidgets';

package/ui/src/dashboard/widgets/ServiceHealthWidget.tsx

@@ -0,0 +1,140 @@
+/**
+ * Service Health Widget
+ *
+ * Displays health check status with latency for all registered health checks.
+ * This is a built-in widget provided by qwickapps-server.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { useState, useEffect } from 'react';
+import { Box, Card, CardContent, Chip } from '@mui/material';
+import { GridLayout, Text } from '@qwickapps/react-framework';
+import CheckCircleIcon from '@mui/icons-material/CheckCircle';
+import ErrorIcon from '@mui/icons-material/Error';
+import WarningIcon from '@mui/icons-material/Warning';
+import { api, HealthResponse } from '../../api/controlPanelApi';
+
+function getStatusIcon(status: string) {
+  switch (status) {
+    case 'healthy':
+      return <CheckCircleIcon sx={{ fontSize: 24, color: 'var(--theme-success)' }} />;
+    case 'degraded':
+      return <WarningIcon sx={{ fontSize: 24, color: 'var(--theme-warning)' }} />;
+    case 'unhealthy':
+      return <ErrorIcon sx={{ fontSize: 24, color: 'var(--theme-error)' }} />;
+    default:
+      return <WarningIcon sx={{ fontSize: 24, color: 'var(--theme-text-secondary)' }} />;
+  }
+}
+
+function getStatusColor(status: string): string {
+  switch (status) {
+    case 'healthy':
+      return 'var(--theme-success)';
+    case 'degraded':
+      return 'var(--theme-warning)';
+    case 'unhealthy':
+      return 'var(--theme-error)';
+    default:
+      return 'var(--theme-text-secondary)';
+  }
+}
+
+/** Get grid columns count (1-4) based on item count */
+function getGridColumns(count: number): 1 | 2 | 3 | 4 {
+  if (count <= 1) return 1;
+  if (count === 2) return 2;
+  if (count === 3) return 3;
+  return 4;
+}
+
+/**
+ * Service Health Widget Component
+ */
+export function ServiceHealthWidget() {
+  const [health, setHealth] = useState<HealthResponse | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const fetchHealth = async () => {
+      try {
+        const data = await api.getHealth();
+        setHealth(data);
+        setError(null);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Failed to fetch health');
+      }
+    };
+
+    fetchHealth();
+    const interval = setInterval(fetchHealth, 10000);
+    return () => clearInterval(interval);
+  }, []);
+
+  if (error) {
+    return (
+      <Card sx={{ bgcolor: 'var(--theme-surface)', border: '1px solid var(--theme-error)' }}>
+        <CardContent>
+          <Text variant="body2" customColor="var(--theme-error)" content={error} />
+        </CardContent>
+      </Card>
+    );
+  }
+
+  const healthChecks = health ? Object.entries(health.checks) : [];
+
+  if (healthChecks.length === 0) {
+    return (
+      <Card sx={{ bgcolor: 'var(--theme-surface)' }}>
+        <CardContent>
+          <Text variant="body2" customColor="var(--theme-text-secondary)" content="No health checks configured" />
+        </CardContent>
+      </Card>
+    );
+  }
+
+  // Determine grid columns based on number of health checks (max 4)
+  const columns = getGridColumns(healthChecks.length);
+
+  return (
+    <GridLayout columns={columns} spacing="medium" equalHeight>
+      {healthChecks.map(([name, check]) => (
+        <Card key={name} sx={{ bgcolor: 'var(--theme-surface)' }}>
+          <CardContent>
+            <Box sx={{ display: 'flex', alignItems: 'center', gap: 2 }}>
+              {getStatusIcon(check.status)}
+              <Box sx={{ flex: 1, minWidth: 0 }}>
+                <Text
+                  variant="body1"
+                  fontWeight="500"
+                  content={name.charAt(0).toUpperCase() + name.slice(1)}
+                  customColor="var(--theme-text-primary)"
+                />
+                <Box sx={{ display: 'flex', alignItems: 'center', gap: 1, mt: 0.5 }}>
+                  <Chip
+                    label={check.status}
+                    size="small"
+                    sx={{
+                      bgcolor: getStatusColor(check.status) + '20',
+                      color: getStatusColor(check.status),
+                      fontSize: '0.75rem',
+                      height: 20,
+                    }}
+                  />
+                  {check.latency !== undefined && (
+                    <Text
+                      variant="caption"
+                      content={`${check.latency}ms`}
+                      customColor="var(--theme-text-secondary)"
+                    />
+                  )}
+                </Box>
+              </Box>
+            </Box>
+          </CardContent>
+        </Card>
+      ))}
+    </GridLayout>
+  );
+}

package/ui/src/dashboard/widgets/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Built-in Dashboard Widgets
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+export { ServiceHealthWidget } from './ServiceHealthWidget';