@qwickapps/server 1.2.0 → 1.3.0

package/ui/src/components/ControlPanelApp.tsx

@@ -0,0 +1,209 @@
+/**
+ * ControlPanelApp Component
+ *
+ * A wrapper around QwickApp that provides control panel functionality.
+ * Injects base control panel routes (Dashboard, Health, Logs, System)
+ * and allows consumers to add custom routes.
+ *
+ * Usage:
+ * ```tsx
+ * import { ControlPanelApp } from '@qwickapps/server/ui';
+ *
+ * function App() {
+ *   return (
+ *     <ControlPanelApp
+ *       productName="My Service"
+ *       logo={<MyLogo />}
+ *       customDashboard={<MyDashboard />}
+ *     >
+ *       <Route path="/users" element={<UsersPage />} />
+ *       <Route path="/settings" element={<SettingsPage />} />
+ *     </ControlPanelApp>
+ *   );
+ * }
+ * ```
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { ReactNode, useState, useEffect } from 'react';
+import { Routes, Route } from 'react-router-dom';
+import { Box, Link } from '@mui/material';
+import { QwickApp, ProductLogo, Text, type MenuItem } from '@qwickapps/react-framework';
+import { defaultConfig } from '../config/AppConfig';
+
+// Base pages
+import { DashboardPage } from '../pages/DashboardPage';
+import { LogsPage } from '../pages/LogsPage';
+import { SystemPage } from '../pages/SystemPage';
+import { NotFoundPage } from '../pages/NotFoundPage';
+
+// Dashboard widget system
+import {
+  DashboardWidgetProvider,
+  WidgetComponentRegistryProvider,
+  getBuiltInWidgetComponents,
+  type DashboardWidget,
+  type WidgetComponent,
+} from '../dashboard';
+
+// API
+import { api } from '../api/controlPanelApi';
+
+export interface ControlPanelAppProps {
+  /** Product name displayed in the header */
+  productName?: string;
+
+  /** Custom logo component */
+  logo?: ReactNode;
+
+  /** Custom footer content (replaces default) */
+  footerContent?: ReactNode;
+
+  /** Initial dashboard widgets to register (legacy context-based system) */
+  dashboardWidgets?: DashboardWidget[];
+
+  /**
+   * Widget components to register for the plugin-based widget system.
+   * These map component names (from server WidgetContribution) to React components.
+   * Built-in widgets (ServiceHealthWidget, etc.) are registered automatically.
+   */
+  widgetComponents?: WidgetComponent[];
+
+  /** Additional navigation items to add to the base control panel nav */
+  navigationItems?: MenuItem[];
+
+  /** Whether to show the base control panel navigation (Dashboard, Health, etc.) */
+  showBaseNavigation?: boolean;
+
+  /** Base navigation item IDs to hide (e.g., ['health'] to hide the Health page) */
+  hideBaseNavItems?: string[];
+
+  /** Whether to show theme switcher in settings */
+  showThemeSwitcher?: boolean;
+
+  /** Whether to show palette switcher in settings */
+  showPaletteSwitcher?: boolean;
+
+  /** Base path for the control panel (e.g., '/cpanel') */
+  basePath?: string;
+
+  /** Custom routes to add (as Route elements) */
+  children?: ReactNode;
+}
+
+/**
+ * Default footer with QwickApps Server branding
+ */
+function DefaultFooter({ version }: { version: string }) {
+  return (
+    <Box sx={{ display: 'flex', alignItems: 'center', justifyContent: 'center', gap: 0.5, py: 2 }}>
+      <Text variant="caption" customColor="var(--theme-text-secondary)">
+        Built with{' '}
+        <Link
+          href="https://qwickapps.com/products/qwickapps-server"
+          target="_blank"
+          rel="noopener noreferrer"
+          sx={{ color: 'primary.main' }}
+        >
+          QwickApps Server
+        </Link>
+        {version && ` v${version}`}
+      </Text>
+    </Box>
+  );
+}
+
+/**
+ * Base navigation items for control panel
+ * Routes are relative to BrowserRouter's basename (handled by NavigationProvider in QwickApp)
+ */
+function getBaseNavigationItems(): MenuItem[] {
+  return [
+    { id: 'dashboard', label: 'Dashboard', route: '/', icon: 'dashboard' },
+    { id: 'logs', label: 'Logs', route: '/logs', icon: 'article' },
+    { id: 'system', label: 'System', route: '/system', icon: 'settings' },
+  ];
+}
+
+export function ControlPanelApp({
+  productName = 'Control Panel',
+  logo,
+  footerContent,
+  dashboardWidgets = [],
+  widgetComponents = [],
+  navigationItems = [],
+  showBaseNavigation = true,
+  hideBaseNavItems = [],
+  showThemeSwitcher = true,
+  showPaletteSwitcher = true,
+  basePath = '',
+  children,
+}: ControlPanelAppProps) {
+  const [version, setVersion] = useState<string>('');
+
+  // Combine built-in widget components with custom ones
+  const allWidgetComponents = [...getBuiltInWidgetComponents(), ...widgetComponents];
+
+  // Configure API base URL based on basePath - do this synchronously before any renders
+  // If basePath is '/cpanel', API is at '/cpanel/api'
+  // If basePath is '' or '/', API is at '/api'
+  const apiBasePath = basePath && basePath !== '/' ? basePath : '';
+  api.setBaseUrl(apiBasePath);
+
+  // Fetch version from API
+  useEffect(() => {
+    api.getInfo()
+      .then((info) => setVersion(info.version || ''))
+      .catch(() => {});
+  }, [apiBasePath]); // Re-fetch when apiBasePath changes
+
+  // Build navigation: base items (filtered by hideBaseNavItems) + custom items
+  // Navigation routes are relative to BrowserRouter's basename
+  const filteredBaseItems = showBaseNavigation
+    ? getBaseNavigationItems().filter(item => !hideBaseNavItems.includes(item.id))
+    : [];
+  const allNavigationItems: MenuItem[] = [
+    ...filteredBaseItems,
+    ...navigationItems,
+  ];
+
+  // Default logo if not provided
+  const effectiveLogo = logo || <ProductLogo name={productName} />;
+
+  // Default footer if not provided
+  const effectiveFooter = footerContent || <DefaultFooter version={version} />;
+
+  return (
+    <WidgetComponentRegistryProvider initialComponents={allWidgetComponents}>
+      <DashboardWidgetProvider initialWidgets={dashboardWidgets}>
+        <QwickApp
+          config={defaultConfig}
+          logo={effectiveLogo}
+          footerContent={effectiveFooter}
+          enableScaffolding={true}
+          navigationItems={allNavigationItems}
+          showThemeSwitcher={showThemeSwitcher}
+          showPaletteSwitcher={showPaletteSwitcher}
+        >
+          <Routes>
+            {/* Base control panel routes (filtered by hideBaseNavItems) */}
+            {showBaseNavigation && (
+              <>
+                {!hideBaseNavItems.includes('dashboard') && <Route path="/" element={<DashboardPage />} />}
+                {!hideBaseNavItems.includes('logs') && <Route path="/logs" element={<LogsPage />} />}
+                {!hideBaseNavItems.includes('system') && <Route path="/system" element={<SystemPage />} />}
+              </>
+            )}
+
+            {/* Custom routes from consumer */}
+            {children}
+
+            {/* Catch-all for 404 */}
+            <Route path="*" element={<NotFoundPage />} />
+          </Routes>
+        </QwickApp>
+      </DashboardWidgetProvider>
+    </WidgetComponentRegistryProvider>
+  );
+}

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,115 @@
+/**
+ * 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 => (
+        <Box key={widget.id} sx={{ mt: 4 }}>
+          {widget.title && (
+            <Typography variant="h6" sx={{ mb: 2, color: 'var(--theme-text-primary)' }}>
+              {widget.title}
+            </Typography>
+          )}
+          {getComponent(widget.component)}
+        </Box>
+      ))}
+    </>
+  );
+}

package/ui/src/dashboard/WidgetComponentRegistry.tsx

@@ -0,0 +1,116 @@
+/**
+ * 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 { ReactNode, createContext, useContext, useState, useCallback, useMemo } from 'react';
+
+/**
+ * Widget component definition
+ */
+export interface WidgetComponent {
+  /** Component name (must match server-side WidgetContribution.component) */
+  name: string;
+  /** The React component to render */
+  component: ReactNode;
+}
+
+interface WidgetComponentRegistryContextValue {
+  /** Register a widget component */
+  registerComponent: (name: string, component: ReactNode) => void;
+  /** Register multiple widget components */
+  registerComponents: (components: WidgetComponent[]) => void;
+  /** Get a component by name */
+  getComponent: (name: string) => ReactNode | 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, ReactNode>>(() => {
+    const map = new Map<string, ReactNode>();
+    for (const comp of initialComponents) {
+      map.set(comp.name, comp.component);
+    }
+    return map;
+  });
+
+  const registerComponent = useCallback((name: string, component: ReactNode) => {
+    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): ReactNode | 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,29 @@
+/**
+ * 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.
+ *
+ * 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 with JSX elements.
+ * Use this when registering with WidgetComponentRegistryProvider.
+ */
+export function getBuiltInWidgetComponents(): WidgetComponent[] {
+  return [
+    { name: 'ServiceHealthWidget', component: <ServiceHealthWidget /> },
+  ];
+}