@qlover/create-app 0.3.3 → 0.3.5

package/templates/react-app/src/base/cases/RouterLoader.ts

@@ -0,0 +1,166 @@
+import type { ComponentType, LazyExoticComponent, ReactNode } from 'react';
+import { RouteObject } from 'react-router-dom';
+import isString from 'lodash/isString';
+
+/**
+ * Component mapping type for lazy-loaded components
+ * @description Maps component identifiers to their lazy-loaded implementations
+ */
+export type ComponentValue = Record<string, () => unknown>;
+
+/**
+ * Route component type definition supporting both regular and lazy-loaded components
+ */
+type RouteComponentType<T = unknown> =
+  | ComponentType<T>
+  | LazyExoticComponent<ComponentType<T>>;
+
+/**
+ * Extended route configuration interface
+ * @description Extends React Router's RouteObject with additional meta information
+ */
+export type RouteConfigValue = Omit<RouteObject, 'element' | 'children'> & {
+  /**
+   * Component identifier string that maps to a component in componentMaps
+   *
+   * TODO: support `ReactNode`
+   *
+   * @description Used to lookup the actual component implementation
+   */
+  element?: string;
+
+  /**
+   * Nested route configurations
+   */
+  children?: RouteConfigValue[];
+
+  /**
+   * Additional metadata for the route
+   * @description Can store any route-specific data like permissions, titles, etc.
+   */
+  meta?: Record<string, unknown>;
+};
+
+/**
+ * Route rendering function type
+ * @description Function to customize how route components are rendered
+ */
+export type RouterLoaderRender = (
+  route: Omit<RouteConfigValue, 'element'> & {
+    element: () => RouteComponentType;
+  }
+) => ReactNode;
+
+/**
+ * Router loader configuration options
+ */
+export type RouterLoaderOptions = {
+  /**
+   * Route configuration array
+   * @description Defines the application's routing structure
+   */
+  routes?: RouteConfigValue[];
+
+  /**
+   * Component mapping object
+   * @description Maps component identifiers to their actual implementations
+   * @example
+   * {
+   *   'Home': () => import('./pages/Home'),
+   *   'About': () => import('./pages/About')
+   * }
+   */
+  componentMaps?: ComponentValue;
+
+  /**
+   * Custom route rendering function
+   * @description Controls how route components are rendered
+   * @required
+   */
+  render: RouterLoaderRender;
+};
+
+/**
+ * Router Configuration Loader
+ *
+ * Significance: Manages dynamic route configuration and component loading
+ * Core idea: Separate route definitions from component implementations
+ * Main function: Transform route configurations into React Router compatible routes
+ * Main purpose: Enable dynamic and code-split routing with lazy loading
+ *
+ * @example
+ * const loader = new RouterLoader({
+ *   routes: [{
+ *     path: '/',
+ *     element: 'Home',
+ *     children: [{
+ *       path: 'about',
+ *       element: 'About'
+ *     }]
+ *   }],
+ *   componentMaps: {
+ *     'Home': () => import('./pages/Home'),
+ *     'About': () => import('./pages/About')
+ *   },
+ *   render: (route) => <Suspense><route.element /></Suspense>
+ * });
+ */
+export class RouterLoader {
+  constructor(private readonly options: RouterLoaderOptions) {
+    if (!options.render) {
+      throw new Error('RouterLoader render is required');
+    }
+  }
+
+  /**
+   * Get the component mapping object
+   * @returns Component mapping dictionary
+   */
+  getComponentMaps(): ComponentValue {
+    const { componentMaps = {} } = this.options;
+    return componentMaps;
+  }
+
+  /**
+   * Retrieve a component implementation by its identifier
+   * @param element Component identifier string
+   * @returns Component loader function
+   * @throws Error if component is not found in componentMaps
+   */
+  getComponent(element: string): () => RouteComponentType {
+    const maps = this.getComponentMaps();
+    const component = maps[element];
+
+    if (!component) {
+      throw new Error(`Component not found: ${element}`);
+    }
+
+    return component as () => RouteComponentType;
+  }
+
+  /**
+   * Transform a route configuration into a React Router compatible route
+   * @param route Route configuration object
+   * @returns React Router route object
+   */
+  toRoute(route: RouteConfigValue): RouteObject {
+    const { render } = this.options;
+    const { element, children, ...rest } = route;
+
+    if (!element || !isString(element)) {
+      console.warn(
+        `Invalid route, path is: ${route.path}, element is: ${element}`
+      );
+    }
+
+    const componet = this.getComponent(element || '404');
+    const Element = render({ ...rest, element: componet });
+
+    // @ts-expect-error
+    return {
+      ...rest,
+      element: Element,
+      children: children?.map((child) => this.toRoute(child))
+    };
+  }
+}

package/templates/react-app/src/base/port/InteractionHubInterface.ts

@@ -0,0 +1,94 @@
+import type { ModalFuncProps } from 'antd';
+
+/**
+ * Confirmation dialog configuration options
+ * Extends Ant Design's ModalFuncProps and requires a title
+ */
+export interface ConfirmOptions extends ModalFuncProps {
+  content: string;
+}
+
+/**
+ * Basic dialog configuration options
+ */
+export interface InteractionOptions {
+  /** Display duration (milliseconds) */
+  duration?: number;
+  /** Close callback function */
+  onClose?: () => void;
+  /** Error object */
+  error?: unknown;
+}
+
+/**
+ * Interaction Hub Interface
+ *
+ * This interface serves as the central interaction layer for the application,
+ * managing all user interface interactions, notifications, and feedback functionality.
+ * Main responsibilities include:
+ * 1. Providing a unified message notification mechanism (success/error/info/warn)
+ * 2. Handling user interaction confirmation scenarios (confirm)
+ * 3. Unified error display and handling approach
+ *
+ * Design Goals:
+ * - Uniformity: Provide consistent user interaction experience
+ * - Extensibility: Easy to add new interaction types
+ * - Configurability: Support custom interaction behaviors
+ * - Decoupling: Separate UI interaction layer from business logic
+ *
+ * Use Cases:
+ * - Operation success/failure feedback
+ * - Important operation confirmation prompts
+ * - System message notifications
+ * - Warning message display
+ *
+ * Implementation Notes:
+ * - Currently implemented based on Ant Design component library
+ * - Supports other UI libraries through different adapters
+ * - Supports global configuration of default behaviors
+ *
+ * @example
+ * // Success notification
+ * interactionHub.success("Operation successful", { duration: 3000 });
+ *
+ * // Confirmation dialog
+ * interactionHub.confirm({
+ *   content: "Are you sure you want to delete?",
+ *   onOk: () => handleDelete()
+ * });
+ */
+export interface InteractionHubInterface {
+  /**
+   * Display success notification
+   * @param message Notification message
+   * @param options Configuration options
+   */
+  success(message: string, options?: InteractionOptions): void;
+
+  /**
+   * Display error notification
+   * @param message Error message
+   * @param options Configuration options
+   */
+  error(message: string, options?: InteractionOptions): void;
+
+  /**
+   * Display information notification
+   * @param message Information message
+   * @param options Configuration options
+   */
+  info(message: string, options?: InteractionOptions): void;
+
+  /**
+   * Display warning notification
+   * @param message Warning message
+   * @param options Configuration options
+   */
+  warn(message: string, options?: InteractionOptions): void;
+
+  /**
+   * Display confirmation dialog
+   * @param options Confirmation dialog configuration options
+   */
+  confirm(options: ConfirmOptions): void;
+}

package/templates/react-app/src/base/services/I18nService.ts

@@ -88,4 +88,23 @@ export class I18nService
   static isValidLanguage(language: string): language is I18nServiceLocale {
     return supportedLngs.includes(language as I18nServiceLocale);
   }
+
+  /**
+   * translate the key
+   * @param key - key to translate
+   * @param params - params to pass to the translation
+   * @returns translated value
+   */
+  t(key: string, params?: Record<string, unknown>): string {
+    const i18nValue = i18n.t(key, {
+      lng: i18n.language,
+      ...params
+    });
+
+    if (!i18nValue || i18nValue === key) {
+      return key;
+    }
+
+    return i18nValue;
+  }
 }

package/templates/react-app/src/base/types/deprecated-antd.d.ts

@@ -0,0 +1,60 @@
+import AntdMessageStatic from 'antd/es/message';
+import { TypeOpen } from 'antd/es/message/interface';
+import AntdModalStatic from 'antd/es/modal';
+
+import { ModalFunc } from 'antd/es/modal/confirm';
+
+declare module 'antd' {
+  /**
+   * @deprecated Please use alternative message implementation instead
+   */
+  export const message: typeof AntdMessageStatic & {
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    info: TypeOpen;
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    success: TypeOpen;
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    error: TypeOpen;
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    warning: TypeOpen;
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    loading: TypeOpen;
+  };
+
+  export const Modal: typeof AntdModalStatic & {
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    confirm: ModalFunc;
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    info: ModalFunc;
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    success: ModalFunc;
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    error: ModalFunc;
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    warn: ModalFunc;
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    warning: ModalFunc;
+  };
+}

package/templates/react-app/src/core/IOC.ts

@@ -11,11 +11,14 @@ import {
 } from '@qlover/corekit-bridge';
 import type { JSONSerializer, JSONStorage } from '@qlover/fe-corekit';
 import type { LoggerInterface } from '@qlover/logger';
+import type { AppConfig } from '@/base/cases/AppConfig';
 import { Container } from 'inversify';
 import { IOCRegisterInterface } from '@qlover/corekit-bridge';
+import { DialogHandler } from '@/base/cases/DialogHandler';
 
 export type IocRegisterOptions = {
   pathname: string;
+  appConfig: AppConfig;
 };
 
 export type InversifyRegisterContainer = Container;
@@ -72,7 +75,8 @@ export const IOCIdentifier = Object.freeze({
   FeApiCommonPlugin: 'FeApiCommonPlugin',
   AppConfig: 'AppConfig',
   ApiMockPlugin: 'ApiMockPlugin',
-  ApiCatchPlugin: 'ApiCatchPlugin'
+  ApiCatchPlugin: 'ApiCatchPlugin',
+  DialogHandler: 'DialogHandler'
 });
 
 /**
@@ -87,6 +91,7 @@ export interface IOCIdentifierMap {
   [IOCIdentifier.AppConfig]: EnvConfigInterface;
   [IOCIdentifier.ApiMockPlugin]: ApiMockPlugin;
   [IOCIdentifier.ApiCatchPlugin]: ApiCatchPlugin;
+  [IOCIdentifier.DialogHandler]: DialogHandler;
 }
 
 export const IOC = createIOCFunction<IOCIdentifierMap>(

package/templates/react-app/src/core/bootstrap.ts

@@ -1,11 +1,4 @@
-import {
-  Bootstrap,
-  type InjectGlobalConfig,
-  type InjectIOCOptions,
-  type IOCContainerInterface,
-  type InjectEnvConfig
-} from '@qlover/corekit-bridge';
-import AppConfig from '@/core/AppConfig';
+import { Bootstrap } from '@qlover/corekit-bridge';
 import { envBlackList, envPrefix, browserGlobalsName } from '@config/common';
 import { IOC } from './IOC';
 import * as globals from '@/core/globals';
@@ -24,33 +17,30 @@ export default async function startup({
     throw new Error(GLOBAL_NO_WINDOW);
   }
 
-  const { logger } = globals;
+  const { logger, appConfig } = globals;
 
-  const envOptions: InjectEnvConfig = {
-    target: AppConfig,
-    source: envSource,
-    prefix: envPrefix,
-    blackList: envBlackList
-  };
-
-  const iocOptions: InjectIOCOptions<IOCContainerInterface> = {
-    manager: IOC,
-    register: new IocRegister({
-      pathname: root.location.pathname
-    })
-  };
-
-  const globalOptions: InjectGlobalConfig = {
-    sources: globals,
-    target: browserGlobalsName
-  };
+  const iocRegister = new IocRegister({
+    pathname: root.location.pathname,
+    appConfig
+  });
 
   const bootstrap = new Bootstrap({
     root,
     logger,
-    ioc: iocOptions,
-    envOptions,
-    globalOptions
+    ioc: {
+      manager: IOC,
+      register: iocRegister
+    },
+    envOptions: {
+      target: appConfig,
+      source: envSource,
+      prefix: envPrefix,
+      blackList: envBlackList
+    },
+    globalOptions: {
+      sources: globals,
+      target: browserGlobalsName
+    }
   });
 
   try {
@@ -63,6 +53,6 @@ export default async function startup({
 
     await bootstrap.use(bootstrapsRegistry.register()).start();
   } catch (error) {
-    logger.error(`${AppConfig.appName} starup error:`, error);
+    logger.error(`${appConfig.appName} starup error:`, error);
   }
 }

package/templates/react-app/src/core/globals.ts

@@ -1,14 +1,21 @@
 // ! global variables, don't import any dependencies and don't have side effects
 import { JSONStorage, JSONSerializer, SyncStorage } from '@qlover/fe-corekit';
 import { ColorFormatter, ConsoleHandler, Logger } from '@qlover/corekit-bridge';
+import { DialogHandler } from '@/base/cases/DialogHandler';
+import { loggerStyles } from '@config/common';
+import { AppConfig } from '@/base/cases/AppConfig';
 
 const isProduction = import.meta.env.VITE_USER_NODE_ENV === 'production';
 
+export const appConfig = new AppConfig();
+
+export const dialogHandler = new DialogHandler();
+
 /**
  * Global logger
  */
 export const logger = new Logger({
-  handlers: new ConsoleHandler(new ColorFormatter()),
+  handlers: new ConsoleHandler(new ColorFormatter(loggerStyles)),
   silent: isProduction
 });
 

package/templates/react-app/src/core/registers/RegisterGlobals.ts

@@ -1,19 +1,23 @@
 import { JSONSerializer, JSONStorage } from '@qlover/fe-corekit';
-import type { EnvConfigInterface } from '@qlover/corekit-bridge';
-import { JSON, localJsonStorage, logger } from '../globals';
+import type { IOCManagerInterface } from '@qlover/corekit-bridge';
+import { dialogHandler, JSON, localJsonStorage, logger } from '../globals';
 import {
   type InversifyContainer,
   type InversifyRegisterInterface,
-  IOCIdentifier
+  IOCIdentifier,
+  IocRegisterOptions
 } from '@/core/IOC';
 import { Logger } from '@qlover/logger';
 
 export class RegisterGlobals implements InversifyRegisterInterface {
-  constructor(private appConfig: EnvConfigInterface) {}
-
-  register(container: InversifyContainer): void {
+  register(
+    container: InversifyContainer,
+    _: IOCManagerInterface<InversifyContainer>,
+    options: IocRegisterOptions
+  ): void {
     // inject AppConfig to IOC
-    container.bind(IOCIdentifier.AppConfig, this.appConfig);
+    container.bind(IOCIdentifier.AppConfig, options.appConfig);
+    container.bind(IOCIdentifier.DialogHandler, dialogHandler);
 
     container.bind(JSONSerializer, JSON);
     container.bind(IOCIdentifier.JSON, JSON);

package/templates/react-app/src/core/registers/index.ts

@@ -2,7 +2,6 @@ import { RegisterGlobals } from './RegisterGlobals';
 import { RegisterCommon } from './RegisterCommon';
 import { RegisterApi } from './RegisterApi';
 import { RegisterControllers } from './RegisterControllers';
-import AppConfig from '../AppConfig';
 import {
   InversifyContainer,
   InversifyRegisterInterface,
@@ -15,7 +14,7 @@ export class IocRegister implements InversifyRegisterInterface {
 
   getRegisterList(): InversifyRegisterInterface[] {
     return [
-      new RegisterGlobals(AppConfig),
+      new RegisterGlobals(),
       new RegisterCommon(),
       new RegisterApi(),
       new RegisterControllers()

package/templates/react-app/src/pages/base/About.tsx

@@ -1,14 +1,127 @@
 import { useBaseRoutePage } from '@/uikit/contexts/BaseRouteContext';
 import * as i18nKeys from '@config/Identifier.I18n';
+import {
+  Button,
+  Tooltip,
+  message,
+  notification,
+  Modal,
+  Drawer,
+  Popover,
+  Popconfirm,
+  Alert
+} from 'antd';
+import { useState } from 'react';
 
 export default function About() {
   const { t } = useBaseRoutePage();
+  const [messageApi, contextHolder] = message.useMessage();
+  const [notificationApi, contextHolder2] = notification.useNotification();
+  const [isModalOpen, setIsModalOpen] = useState(false);
+  const [isDrawerOpen, setIsDrawerOpen] = useState(false);
+
+  const showMessage = () => {
+    messageApi.info(t(i18nKeys.ABOUT_MESSAGE_TEST), 2000);
+  };
+
+  const showNotification = () => {
+    notificationApi.open({
+      message: t(i18nKeys.ABOUT_NOTIFICATION_TITLE),
+      description: t(i18nKeys.ABOUT_NOTIFICATION_DESC),
+      duration: 2000
+    });
+  };
+  const showNotification2 = () => {
+    notification.open({
+      message: t(i18nKeys.ABOUT_NOTIFICATION_TITLE),
+      description: t(i18nKeys.ABOUT_NOTIFICATION_DESC),
+      duration: 2000
+    });
+  };
+
+  const showModal = () => {
+    setIsModalOpen(true);
+  };
+  const showMessage2 = () => {
+    message.info(t(i18nKeys.ABOUT_MESSAGE_TEST), 200);
+  };
+
+  const showDrawer = () => {
+    setIsDrawerOpen(true);
+  };
+
   return (
     <div className="min-h-screen bg-primary py-6 flex flex-col justify-center sm:py-12">
+      {contextHolder}
+      {contextHolder2}
       <div className="relative py-3 sm:max-w-xl sm:mx-auto">
-        <h1 className="text-2xl font-bold text-center text-text">
+        <h1 className="text-2xl font-bold text-center text-text mb-8">
           {t(i18nKeys.PAGE_ABOUT_TITLE)}
         </h1>
+
+        <div className="space-x-4 flex justify-center flex-wrap gap-4">
+          <Button onClick={showMessage}>{t(i18nKeys.ABOUT_BTN_MESSAGE)}</Button>
+          <Button onClick={showMessage2}>
+            {t(i18nKeys.ABOUT_BTN_MESSAGE2)}
+          </Button>
+
+          <Button onClick={showNotification}>
+            {t(i18nKeys.ABOUT_BTN_NOTIFICATION)}
+          </Button>
+
+          <Button onClick={showNotification2}>
+            {t(i18nKeys.ABOUT_BTN_NOTIFICATION2)}
+          </Button>
+
+          <Tooltip title={t(i18nKeys.ABOUT_TOOLTIP_TEXT)}>
+            <Button>{t(i18nKeys.ABOUT_BTN_TOOLTIP)}</Button>
+          </Tooltip>
+
+          <Modal
+            title={t(i18nKeys.ABOUT_MODAL_TITLE)}
+            open={isModalOpen}
+            onOk={() => setIsModalOpen(false)}
+            onCancel={() => setIsModalOpen(false)}
+          >
+            <p>{t(i18nKeys.ABOUT_MODAL_CONTENT)}</p>
+          </Modal>
+
+          <Button onClick={showModal}>{t(i18nKeys.ABOUT_BTN_MODAL)}</Button>
+
+          <Drawer
+            title={t(i18nKeys.ABOUT_DRAWER_TITLE)}
+            open={isDrawerOpen}
+            onClose={() => setIsDrawerOpen(false)}
+          >
+            <p>{t(i18nKeys.ABOUT_DRAWER_CONTENT)}</p>
+          </Drawer>
+
+          <Button onClick={showDrawer}>{t(i18nKeys.ABOUT_BTN_DRAWER)}</Button>
+
+          <Popover
+            content={t(i18nKeys.ABOUT_POPOVER_CONTENT)}
+            title={t(i18nKeys.ABOUT_POPOVER_TITLE)}
+          >
+            <Button>{t(i18nKeys.ABOUT_BTN_POPOVER)}</Button>
+          </Popover>
+
+          <Popconfirm
+            title={t(i18nKeys.ABOUT_POPCONFIRM_TITLE)}
+            description={t(i18nKeys.ABOUT_POPCONFIRM_DESC)}
+            okText={t(i18nKeys.COMMON_OK)}
+            cancelText={t(i18nKeys.COMMON_CANCEL)}
+          >
+            <Button>{t(i18nKeys.ABOUT_BTN_POPCONFIRM)}</Button>
+          </Popconfirm>
+
+          <Alert
+            message={t(i18nKeys.ABOUT_ALERT_MESSAGE)}
+            type="warning"
+            showIcon
+            closable
+            className="mt-4"
+          />
+        </div>
       </div>
     </div>
   );