@qlover/create-app 0.10.0 → 0.10.2

package/dist/templates/next-app/src/uikit/components/ClinetRenderProvider.tsx

@@ -0,0 +1,42 @@
+'use client';
+
+import { useMountedClient } from '@brain-toolkit/react-kit';
+
+export interface ClinetRenderProviderProps {
+  children: React.ReactNode;
+}
+
+/**
+ * ClinetRenderProvider is a provider for the client components
+ *
+ *
+ * 当前组件仅用于需要客户端渲染的组件, 比如 adminLayout 等完全客户端渲染的组件
+ *
+ *
+ * @param children - The children components
+ * @returns
+ */
+export function ClinetRenderProvider(props: ClinetRenderProviderProps) {
+  const { children } = props;
+
+  const mounted = useMountedClient();
+
+  return (
+    <>
+      {children}
+
+      {/* 为了防止语言切换时页面闪烁, 使用一个固定定位的div, 当客户端渲染时才渲染 */}
+      {!mounted && (
+        <div
+          role="status"
+          aria-label="Loading..."
+          aria-busy="true"
+          style={{
+            zIndex: '99999 !important'
+          }}
+          className="fixed inset-0 overflow-hidden cursor-wait no-scrollbar bg-primary pointer-events-none"
+        ></div>
+      )}
+    </>
+  );
+}

package/dist/templates/next-app/src/uikit/components/IOCProvider.tsx

@@ -0,0 +1,34 @@
+'use client';
+
+import { useMemo } from 'react';
+import { appConfig } from '@/core/globals';
+import { clientIOC, IOCContext, IOCInstance } from '../context/IOCContext';
+
+export function IOCProvider(props: { children: React.ReactNode }) {
+  /**
+   * 加载组件就立即注册
+   *
+   * 这样在渲染子组件时保证 IOC.get 正常工作
+   *
+   * 但是这样会导致注册时无法传递浏览器端的依赖, 比如 window.location.pathname
+   *
+   * - 如果有需要，可以将注册放在下面 useStrictEffect 中, 然后 IocMounted=true 时在渲染子节点
+   *
+   * **但是这样会有一个问题, 组件会重新挂载渲染，当切换语言时会闪烁**
+   *
+   * 因为页面初始化时有些组件可能已经使用了容器注入，这样就会丢失注册的依赖
+   *
+   * TODO: 这是一个需要解决的问题
+   */
+  useMemo(() => {
+    clientIOC.register({
+      appConfig: appConfig
+    });
+  }, []);
+
+  return (
+    <IOCContext.Provider data-testid="IOCProvider" value={IOCInstance}>
+      {props.children}
+    </IOCContext.Provider>
+  );
+}

package/dist/templates/next-app/src/uikit/components/LocaleLink.tsx

@@ -5,8 +5,7 @@ import type { LinkProps } from 'next/link';
 import type { ReactNode } from 'react';
 
 interface LocaleLinkProps
-  extends Omit<LinkProps, 'href'>,
-    React.HTMLAttributes<HTMLAnchorElement> {
+  extends Omit<LinkProps, 'href'>, React.HTMLAttributes<HTMLAnchorElement> {
   href:
     | string
     | {

package/dist/templates/next-app/src/uikit/components-app/AppBridge.tsx

@@ -0,0 +1,17 @@
+'use client';
+
+import { useEffect } from 'react';
+import { NavigateBridge } from '@/base/cases/NavigateBridge';
+import { useRouter } from '@/i18n/routing';
+import { useIOC } from '../hook/useIOC';
+
+export function AppBridge() {
+  const router = useRouter();
+  const navigateBridge = useIOC(NavigateBridge);
+
+  useEffect(() => {
+    navigateBridge.setUIBridge(router);
+  }, [router, navigateBridge]);
+
+  return null;
+}

package/dist/templates/next-app/src/uikit/components-app/AppRoutePage.tsx

@@ -0,0 +1,112 @@
+import { TeamOutlined } from '@ant-design/icons';
+import { clsx } from 'clsx';
+import { useLocale } from 'next-intl';
+import { useMemo, type HTMLAttributes } from 'react';
+import { AppBridge } from './AppBridge';
+import { LanguageSwitcher } from './LanguageSwitcher';
+import { LogoutButton } from './LogoutButton';
+import { ThemeSwitcher } from './ThemeSwitcher';
+import { LocaleLink } from '../components/LocaleLink';
+
+export interface AppRoutePageTT {
+  title: string;
+  adminTitle: string;
+}
+
+export interface AppRoutePageProps extends HTMLAttributes<HTMLDivElement> {
+  showLogoutButton?: boolean;
+  showAdminButton?: boolean;
+  mainProps?: HTMLAttributes<HTMLElement>;
+  headerClassName?: string;
+  headerHref?: string;
+  tt: AppRoutePageTT;
+}
+
+/**
+ * App Route Page
+ *
+ * 主要用于 /src/app 目录下页面的基础布局，包含头部、主体内容等
+ *
+ * @description
+ * - /src/app/[locale]/page.tsx
+ * - /src/app/[locale]/login/page.tsx
+ *
+ */
+export function AppRoutePage({
+  children,
+  showLogoutButton,
+  showAdminButton,
+  mainProps,
+  headerClassName,
+  tt,
+  headerHref = '/',
+  ...props
+}: AppRoutePageProps) {
+  const locale = useLocale();
+  const adminTitle = tt.adminTitle;
+
+  const actions = useMemo(() => {
+    return [
+      showAdminButton && (
+        <LocaleLink
+          key="admin-button"
+          href="/admin"
+          title={adminTitle}
+          locale={locale}
+          className="text-text hover:text-text-hover cursor-pointer text-lg transition-colors"
+        >
+          <TeamOutlined className="text-lg text-text" />
+        </LocaleLink>
+      ),
+
+      <LanguageSwitcher key="language-switcher" />,
+
+      <ThemeSwitcher key="theme-switcher" />,
+
+      showLogoutButton && <LogoutButton key="logout-button" />
+    ].filter(Boolean);
+  }, [adminTitle, showAdminButton, showLogoutButton, locale]);
+
+  return (
+    <div
+      data-testid="AppRoutePage"
+      className="flex flex-col min-h-screen"
+      {...props}
+    >
+      <AppBridge />
+      <header
+        data-testid="BaseHeader"
+        className="h-14 bg-secondary border-b border-c-border sticky top-0 z-50"
+      >
+        <div
+          className={clsx(
+            'flex items-center justify-between h-full px-4 mx-auto max-w-7xl',
+            headerClassName
+          )}
+        >
+          <div className="flex items-center">
+            <LocaleLink
+              data-testid="BaseHeaderLogo"
+              title={tt.title}
+              href={headerHref}
+              locale={locale}
+              className="flex items-center hover:opacity-80 transition-opacity"
+            >
+              <span
+                data-testid="base-header-app-name"
+                className="text-lg font-semibold text-text"
+              >
+                {tt.title}
+              </span>
+            </LocaleLink>
+          </div>
+          <div className="flex items-center gap-2 md:gap-4">{actions}</div>
+        </div>
+      </header>
+
+      <main className="flex flex-1 flex-col bg-primary" {...mainProps}>
+        {children}
+      </main>
+    </div>
+  );
+}

package/dist/templates/next-app/src/uikit/{components → components-app}/LanguageSwitcher.tsx

@@ -2,22 +2,20 @@
 
 import { TranslationOutlined } from '@ant-design/icons';
 import { Dropdown } from 'antd';
+import { useParams } from 'next/navigation';
 import { useLocale } from 'next-intl';
-import { useCallback, useMemo } from 'react';
-import type { I18nServiceLocale } from '@/base/port/I18nServiceInterface';
+import { useCallback, useMemo, useTransition } from 'react';
 import { usePathname, useRouter } from '@/i18n/routing';
 import { i18nConfig } from '@config/i18n';
 import type { LocaleType } from '@config/i18n';
-import { I } from '@config/IOCIdentifier';
-import { useIOC } from '../hook/useIOC';
 import type { ItemType } from 'antd/es/menu/interface';
 
 export function LanguageSwitcher() {
-  const i18nService = useIOC(I.I18nServiceInterface);
-  const pathname = usePathname(); // current pathname, aware of i18n
-
-  const router = useRouter(); // i18n-aware router instance
-  const currentLocale = useLocale() as LocaleType; // currently active locale
+  const pathname = usePathname();
+  const router = useRouter();
+  const currentLocale = useLocale() as LocaleType;
+  const [isPending, startTransition] = useTransition();
+  const params = useParams();
 
   const options: ItemType[] = useMemo(() => {
     return i18nConfig.supportedLngs.map(
@@ -34,18 +32,16 @@ export function LanguageSwitcher() {
 
   const handleLanguageChange = useCallback(
     async (value: string) => {
-      // Set a persistent cookie with the user's preferred locale (valid for 1 year)
-      document.cookie = `NEXT_LOCALE=${value}; path=/; max-age=31536000; SameSite=Lax`;
-      // Route to the same page in the selected locale
-      router.replace(pathname, { locale: value });
+      if (isPending) return;
 
-      try {
-        await i18nService.changeLanguage(value as I18nServiceLocale);
-      } catch (error) {
-        console.error('Failed to change language:', error);
-      }
+      startTransition(() => {
+        // @ts-expect-error -- TypeScript will validate that only known `params`
+        // are used in combination with a given `pathname`. Since the two will
+        // always match for the current route, we can skip runtime checks.
+        router.replace({ pathname, params }, { locale: value });
+      });
     },
-    [i18nService, pathname, router]
+    [pathname, router, isPending, params]
   );
 
   const nextLocale = useMemo(() => {

package/dist/templates/next-app/src/uikit/{components → components-app}/ThemeSwitcher.tsx

@@ -14,11 +14,20 @@ import { useMountedClient } from '@brain-toolkit/react-kit';
 import { Dropdown } from 'antd';
 import { clsx } from 'clsx';
 import { useTheme } from 'next-themes';
-import { useMemo } from 'react';
+import { useEffect, useMemo } from 'react';
+import {
+  COMMON_THEME_DARK,
+  COMMON_THEME_DEFAULT,
+  COMMON_THEME_LIGHT,
+  COMMON_THEME_PINK
+} from '@config/Identifier';
+import { I } from '@config/IOCIdentifier';
 import { type SupportedTheme, themeConfig } from '@config/theme';
+import { useIOC } from '../hook/useIOC';
+import { useWarnTranslations } from '../hook/useWarnTranslations';
 import type { ItemType } from 'antd/es/menu/interface';
 
-const { supportedThemes } = themeConfig;
+const { supportedThemes, storageKey } = themeConfig;
 
 const defaultTheme = supportedThemes[0] || 'system';
 const themesList = ['system', ...supportedThemes];
@@ -31,71 +40,76 @@ const colorMap: Record<
     normalColor: string;
     Icon: React.ElementType;
     SelectedIcon: React.ElementType;
-    TriggerIcon: React.ElementType;
   }
 > = {
   system: {
-    i18nkey: 'System',
+    i18nkey: COMMON_THEME_DEFAULT,
     selectedColor: 'text-text',
     normalColor: 'text-text-secondary',
     Icon: SettingOutlined,
-    SelectedIcon: SettingFilled,
-    TriggerIcon: SettingOutlined
+    SelectedIcon: SettingFilled
   },
   light: {
-    i18nkey: 'Light',
+    i18nkey: COMMON_THEME_LIGHT,
     selectedColor: 'text-text',
     normalColor: 'text-text-secondary',
     Icon: SunOutlined,
-    SelectedIcon: SunFilled,
-    TriggerIcon: SunOutlined
+    SelectedIcon: SunFilled
   },
   dark: {
-    i18nkey: 'Dark',
+    i18nkey: COMMON_THEME_DARK,
     selectedColor: 'text-[#9333ea]',
     normalColor: 'text-[#a855f7]',
     Icon: MoonOutlined,
-    SelectedIcon: MoonFilled,
-    TriggerIcon: MoonOutlined
+    SelectedIcon: MoonFilled
   },
   pink: {
-    i18nkey: 'Pink',
+    i18nkey: COMMON_THEME_PINK,
     selectedColor: 'text-[#f472b6]',
     normalColor: 'text-[#ec4899]',
     Icon: HeartOutlined,
-    SelectedIcon: HeartFilled,
-    TriggerIcon: HeartOutlined
+    SelectedIcon: HeartFilled
   }
 };
 
 export function ThemeSwitcher() {
   const { theme: currentTheme, resolvedTheme, setTheme } = useTheme();
   const mounted = useMountedClient();
+  const cookieStorage = useIOC(I.CookieStorage);
+  const t = useWarnTranslations();
+
+  useEffect(() => {
+    if (resolvedTheme) {
+      cookieStorage.setItem(storageKey, resolvedTheme);
+    }
+  }, [resolvedTheme, cookieStorage]);
 
-  const themeOptions = themesList.map((themeName) => {
-    const { i18nkey, selectedColor, normalColor, Icon, SelectedIcon } =
-      colorMap[themeName] || colorMap.light;
+  const themeOptions = useMemo(() => {
+    return themesList.map((themeName) => {
+      const { i18nkey, selectedColor, normalColor, Icon, SelectedIcon } =
+        colorMap[themeName] || colorMap.light;
 
-    const isCurrentTheme =
-      currentTheme === themeName ||
-      (themeName === resolvedTheme && currentTheme === 'system');
+      const isCurrentTheme =
+        currentTheme === themeName ||
+        (themeName === resolvedTheme && currentTheme === 'system');
 
-    return {
-      key: themeName,
-      value: themeName,
-      label: (
-        <div
-          className={clsx(
-            'flex items-center gap-2',
-            isCurrentTheme ? selectedColor : normalColor
-          )}
-        >
-          {isCurrentTheme ? <SelectedIcon /> : <Icon />}
-          <span>{i18nkey}</span>
-        </div>
-      )
-    } as ItemType;
-  });
+      return {
+        key: themeName,
+        value: themeName,
+        label: (
+          <div
+            className={clsx(
+              'flex items-center gap-2',
+              isCurrentTheme ? selectedColor : normalColor
+            )}
+          >
+            {isCurrentTheme ? <SelectedIcon /> : <Icon />}
+            <span>{t(i18nkey)}</span>
+          </div>
+        )
+      } as ItemType;
+    });
+  }, [currentTheme, resolvedTheme, t]);
 
   const nextTheme = useMemo(() => {
     if (!currentTheme) {
@@ -106,26 +120,13 @@ export function ThemeSwitcher() {
     return supportedThemes[targetIndex % supportedThemes.length];
   }, [currentTheme]);
 
-  const TriggerIcon = colorMap[currentTheme || defaultTheme].TriggerIcon;
-
-  if (!mounted) {
-    return (
-      <span
-        data-testid="ThemeSwitcher"
-        className="text-text hover:text-text-hover cursor-pointer text-lg transition-colors"
-      >
-        <SettingOutlined />
-      </span>
-    );
-  }
-
   return (
     <Dropdown
       data-testid="ThemeSwitcherDropdown"
       trigger={['hover']}
       menu={{
         items: themeOptions,
-        selectedKeys: [currentTheme!],
+        selectedKeys: mounted ? [resolvedTheme!] : undefined,
         onClick: ({ key }) => {
           setTheme(key);
         }
@@ -136,7 +137,7 @@ export function ThemeSwitcher() {
         className="text-text hover:text-text-hover cursor-pointer text-lg transition-colors"
         onClick={() => setTheme(nextTheme)}
       >
-        <TriggerIcon />
+        <SunOutlined />
       </span>
     </Dropdown>
   );

package/dist/templates/next-app/src/uikit/components-pages/LanguageSwitcher.tsx

@@ -0,0 +1,98 @@
+'use client';
+
+import { TranslationOutlined } from '@ant-design/icons';
+import { Dropdown } from 'antd';
+import { useRouter } from 'next/router';
+import { useLocale } from 'next-intl';
+import { useCallback, useMemo, useState } from 'react';
+import { useLocaleRoutes } from '@config/common';
+import { i18nConfig } from '@config/i18n';
+import type { LocaleType } from '@config/i18n';
+import type { ItemType } from 'antd/es/menu/interface';
+
+export function LanguageSwitcher() {
+  const router = useRouter();
+  const currentLocale = useLocale() as LocaleType;
+  const [isPending, setIsPending] = useState(false);
+
+  const options: ItemType[] = useMemo(() => {
+    return i18nConfig.supportedLngs.map(
+      (lang) =>
+        ({
+          type: 'item',
+          key: lang,
+          value: lang,
+          label:
+            i18nConfig.localeNames[lang as keyof typeof i18nConfig.localeNames]
+        }) as ItemType
+    );
+  }, []);
+
+  const handleLanguageChange = useCallback(
+    async (value: string) => {
+      if (isPending || value === currentLocale) return;
+
+      setIsPending(true);
+
+      try {
+        // Get current path
+        let newPath = router.asPath;
+
+        if (useLocaleRoutes) {
+          // Replace locale in path (e.g., /en/about -> /zh/about)
+          const pathWithoutLocale = newPath.replace(
+            new RegExp(`^/${currentLocale}(/|$)`),
+            '/'
+          );
+          // Remove leading slash if path is root
+          const cleanPath = pathWithoutLocale === '/' ? '' : pathWithoutLocale;
+          newPath = `/${value}${cleanPath}`;
+        } else {
+          // If not using locale routes, just update query param
+          newPath = router.pathname;
+          router.replace({
+            pathname: router.pathname,
+            query: { ...router.query, locale: value }
+          });
+          setIsPending(false);
+          return;
+        }
+
+        // Replace the route
+        router.replace(newPath);
+      } finally {
+        setIsPending(false);
+      }
+    },
+    [router, currentLocale, isPending]
+  );
+
+  const nextLocale = useMemo(() => {
+    const targetIndex = i18nConfig.supportedLngs.indexOf(currentLocale) + 1;
+    return i18nConfig.supportedLngs[
+      targetIndex % i18nConfig.supportedLngs.length
+    ];
+  }, [currentLocale]);
+
+  return (
+    <Dropdown
+      data-testid="LanguageSwitcherDropdown"
+      trigger={['hover']}
+      menu={{
+        selectedKeys: [currentLocale],
+        items: options,
+        onClick: ({ key }) => {
+          handleLanguageChange(key);
+        }
+      }}
+    >
+      <span
+        data-testid="LanguageSwitcher"
+        className="text-text hover:text-text-hover cursor-pointer text-lg transition-colors"
+        onClick={() => handleLanguageChange(nextLocale)}
+      >
+        <TranslationOutlined />
+      </span>
+    </Dropdown>
+  );
+}

package/dist/templates/next-app/src/uikit/components-pages/PagesRoutePage.tsx

@@ -0,0 +1,93 @@
+import { TeamOutlined } from '@ant-design/icons';
+import { clsx } from 'clsx';
+import { useLocale } from 'next-intl';
+import { useMemo } from 'react';
+import { LanguageSwitcher } from './LanguageSwitcher';
+import { LocaleLink } from '../components/LocaleLink';
+import { ThemeSwitcher } from '../components-app/ThemeSwitcher';
+import type { AppRoutePageProps } from '../components-app/AppRoutePage';
+
+/**
+ * App Route Page
+ *
+ * 主要用于 /src/app 目录下页面的基础布局，包含头部、主体内容等
+ *
+ * @description
+ * - /src/app/[locale]/page.tsx
+ * - /src/app/[locale]/login/page.tsx
+ *
+ */
+export function PagesRoutePage({
+  children,
+  showAdminButton,
+  mainProps,
+  headerClassName,
+  tt,
+  headerHref = '/',
+  ...props
+}: AppRoutePageProps) {
+  const locale = useLocale();
+  const adminTitle = tt.adminTitle;
+
+  const actions = useMemo(() => {
+    return [
+      showAdminButton && (
+        <LocaleLink
+          key="admin-button"
+          href="/admin"
+          title={adminTitle}
+          locale={locale}
+          className="text-text hover:text-text-hover cursor-pointer text-lg transition-colors"
+        >
+          <TeamOutlined className="text-lg text-text" />
+        </LocaleLink>
+      ),
+
+      <LanguageSwitcher key="language-switcher" />,
+
+      <ThemeSwitcher key="theme-switcher" />
+    ].filter(Boolean);
+  }, [adminTitle, showAdminButton, locale]);
+
+  return (
+    <div
+      data-testid="AppRoutePage"
+      className="flex flex-col min-h-screen"
+      {...props}
+    >
+      <header
+        data-testid="BaseHeader"
+        className="h-14 bg-secondary border-b border-c-border sticky top-0 z-50"
+      >
+        <div
+          className={clsx(
+            'flex items-center justify-between h-full px-4 mx-auto max-w-7xl',
+            headerClassName
+          )}
+        >
+          <div className="flex items-center">
+            <LocaleLink
+              data-testid="BaseHeaderLogo"
+              title={tt.title}
+              href={headerHref}
+              locale={locale}
+              className="flex items-center hover:opacity-80 transition-opacity"
+            >
+              <span
+                data-testid="base-header-app-name"
+                className="text-lg font-semibold text-text"
+              >
+                {tt.title}
+              </span>
+            </LocaleLink>
+          </div>
+          <div className="flex items-center gap-2 md:gap-4">{actions}</div>
+        </div>
+      </header>
+
+      <main className="flex flex-1 flex-col bg-primary" {...mainProps}>
+        {children}
+      </main>
+    </div>
+  );
+}

package/dist/templates/next-app/src/uikit/context/IOCContext.ts

@@ -1,11 +1,23 @@
 'use client';
 
+import {
+  type IOCContainerInterface,
+  type IOCFunctionInterface
+} from '@qlover/corekit-bridge';
 import { createContext } from 'react';
+import { ClientIOC } from '@/core/clientIoc/ClientIOC';
 import type { IOCIdentifierMap } from '@config/IOCIdentifier';
-import type {
-  IOCContainerInterface,
-  IOCFunctionInterface
-} from '@qlover/corekit-bridge';
+
+// export const IOCInstance = new ClientIOC();
+
+// export const IOCContext =
+//   createContext<IOCInterface<IOCIdentifierMap, IOCContainerInterface>>(
+//     IOCInstance
+//   );
+
+export const clientIOC = new ClientIOC();
+
+export const IOCInstance = clientIOC.create();
 
 export const IOCContext = createContext<IOCFunctionInterface<
   IOCIdentifierMap,