create-nextdevtpl 2.6.0

package/template/src/features/settings/schemas/update-profile.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+/**
+ * 更新用户资料的 Zod Schema
+ *
+ * @field name - 用户显示名称，最少 2 个字符，最多 50 个字符
+ * @field image - 用户头像 (存储键名)，可选
+ */
+export const updateProfileSchema = z.object({
+  name: z
+    .string()
+    .min(2, "名称至少需要 2 个字符")
+    .max(50, "名称最多 50 个字符")
+    .optional(),
+  image: z.string().max(255, "头像路径过长").optional(),
+});
+
+/**
+ * 表单数据类型，从 Zod Schema 推断
+ */
+export type UpdateProfileInput = z.infer<typeof updateProfileSchema>;

package/template/src/features/shared/components/cookie-settings-dialog.tsx

@@ -0,0 +1,282 @@
+"use client";
+
+import { ChevronDown } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useCallback, useEffect, useState } from "react";
+
+import { Button } from "@/components/ui/button";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "@/components/ui/collapsible";
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog";
+import { Switch } from "@/components/ui/switch";
+import {
+  COOKIE_CONSENT_CHANGE_EVENT,
+  COOKIE_CONSENT_KEY,
+  COOKIE_PREFERENCES_KEY,
+  type CookieConsentType,
+  type CookiePreferences,
+} from "@/lib/cookie-consent";
+import { cn } from "@/lib/utils";
+
+/**
+ * 默认 Cookie 偏好
+ */
+const DEFAULT_PREFERENCES: CookiePreferences = {
+  analytics: true,
+  marketing: true,
+};
+
+/**
+ * Cookie Settings Dialog 组件属性
+ */
+interface CookieSettingsDialogProps {
+  /** 触发按钮的子元素 */
+  children: React.ReactNode;
+}
+
+/**
+ * Cookie Settings Dialog 组件
+ *
+ * 功能:
+ * - 显示 Cookie 偏好设置对话框
+ * - 可展开的 Cookie 类别
+ * - 支持 Accept all / Reject all / Accept current selection
+ */
+export function CookieSettingsDialog({ children }: CookieSettingsDialogProps) {
+  const t = useTranslations("Cookie");
+  const [open, setOpen] = useState(false);
+  const [preferences, setPreferences] =
+    useState<CookiePreferences>(DEFAULT_PREFERENCES);
+  const [expandedItems, setExpandedItems] = useState<string[]>(["necessary"]);
+
+  const cookieCategories = [
+    {
+      id: "necessary",
+      title: t("essential.title"),
+      description: t("essential.description"),
+      required: true,
+    },
+    {
+      id: "analytics",
+      title: t("analytics.title"),
+      description: t("analytics.description"),
+      required: false,
+    },
+    {
+      id: "marketing",
+      title: t("marketing.title"),
+      description: t("marketing.description"),
+      required: false,
+    },
+  ] as const;
+
+  /**
+   * 加载已保存的偏好设置
+   */
+  useEffect(() => {
+    if (open) {
+      const savedPreferences = localStorage.getItem(COOKIE_PREFERENCES_KEY);
+      if (savedPreferences) {
+        try {
+          setPreferences(JSON.parse(savedPreferences));
+        } catch {
+          // 忽略解析错误
+        }
+      }
+    }
+  }, [open]);
+
+  /**
+   * 切换展开状态
+   */
+  const toggleExpanded = (id: string) => {
+    setExpandedItems((prev) =>
+      prev.includes(id) ? prev.filter((item) => item !== id) : [...prev, id]
+    );
+  };
+
+  /**
+   * 保存 Cookie 同意设置
+   */
+  const saveConsent = useCallback(
+    (consent: CookieConsentType, prefs: CookiePreferences) => {
+      localStorage.setItem(COOKIE_CONSENT_KEY, consent || "");
+      localStorage.setItem(COOKIE_PREFERENCES_KEY, JSON.stringify(prefs));
+      // 触发自定义事件通知 Analytics 组件
+      window.dispatchEvent(new CustomEvent(COOKIE_CONSENT_CHANGE_EVENT));
+      setOpen(false);
+    },
+    []
+  );
+
+  /**
+   * 处理接受全部 Cookie
+   */
+  const handleAcceptAll = useCallback(() => {
+    const allPreferences: CookiePreferences = {
+      analytics: true,
+      marketing: true,
+    };
+    setPreferences(allPreferences);
+    saveConsent("all", allPreferences);
+  }, [saveConsent]);
+
+  /**
+   * 处理拒绝全部（仅必要）
+   */
+  const handleRejectAll = useCallback(() => {
+    const essentialPreferences: CookiePreferences = {
+      analytics: false,
+      marketing: false,
+    };
+    setPreferences(essentialPreferences);
+    saveConsent("essential", essentialPreferences);
+  }, [saveConsent]);
+
+  /**
+   * 处理保存当前选择
+   */
+  const handleSavePreferences = useCallback(() => {
+    const consentType: CookieConsentType =
+      preferences.analytics || preferences.marketing ? "all" : "essential";
+    saveConsent(consentType, preferences);
+  }, [preferences, saveConsent]);
+
+  /**
+   * 更新偏好设置
+   */
+  const updatePreference = (key: keyof CookiePreferences, value: boolean) => {
+    setPreferences((prev) => ({ ...prev, [key]: value }));
+  };
+
+  /**
+   * 获取某个类别的开关状态
+   */
+  const getCategoryValue = (id: string): boolean => {
+    if (id === "necessary") return true;
+    if (id === "analytics") return preferences.analytics;
+    if (id === "marketing") return preferences.marketing;
+    return false;
+  };
+
+  /**
+   * 处理某个类别的开关变化
+   */
+  const handleCategoryChange = (id: string, value: boolean) => {
+    if (id === "analytics") updatePreference("analytics", value);
+    if (id === "marketing") updatePreference("marketing", value);
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={setOpen}>
+      <DialogTrigger asChild>{children}</DialogTrigger>
+      <DialogContent
+        className="max-h-[90vh] max-w-2xl overflow-hidden p-0 [&>button]:hidden"
+        overlayClassName="bg-black/30"
+      >
+        {/* Header */}
+        <DialogHeader className="border-b px-6 py-4">
+          <div className="flex items-center justify-between">
+            <DialogTitle className="text-lg font-semibold">
+              {t("dialog.title")}
+            </DialogTitle>
+          </div>
+        </DialogHeader>
+
+        {/* Content */}
+        <div className="max-h-[60vh] overflow-y-auto px-6 py-4">
+          {/* Description */}
+          <div className="mb-6">
+            <h3 className="mb-2 font-semibold">{t("dialog.heading")}</h3>
+            <p className="text-sm text-muted-foreground">
+              {t("dialog.description")}
+            </p>
+          </div>
+
+          {/* Cookie Categories */}
+          <div className="space-y-3">
+            {cookieCategories.map((category) => {
+              const isExpanded = expandedItems.includes(category.id);
+              const isChecked = getCategoryValue(category.id);
+
+              return (
+                <Collapsible
+                  key={category.id}
+                  open={isExpanded}
+                  onOpenChange={() => toggleExpanded(category.id)}
+                >
+                  <div className="rounded-lg border">
+                    {/* Category Header */}
+                    <div className="flex items-center justify-between p-4">
+                      <CollapsibleTrigger asChild>
+                        <button
+                          type="button"
+                          className="flex items-center gap-2 text-left"
+                        >
+                          <ChevronDown
+                            className={cn(
+                              "h-4 w-4 text-muted-foreground transition-transform",
+                              isExpanded && "rotate-180"
+                            )}
+                          />
+                          <span className="font-medium">{category.title}</span>
+                        </button>
+                      </CollapsibleTrigger>
+                      <Switch
+                        checked={isChecked}
+                        onCheckedChange={(value) =>
+                          handleCategoryChange(category.id, value)
+                        }
+                        disabled={category.required}
+                      />
+                    </div>
+
+                    {/* Category Description */}
+                    <CollapsibleContent>
+                      <div className="border-t px-4 py-3">
+                        <p className="text-sm text-muted-foreground">
+                          {category.description}
+                        </p>
+                      </div>
+                    </CollapsibleContent>
+                  </div>
+                </Collapsible>
+              );
+            })}
+          </div>
+        </div>
+
+        {/* Footer */}
+        <div className="flex items-center justify-between border-t px-6 py-4">
+          <div className="flex gap-2">
+            <Button
+              onClick={handleAcceptAll}
+              className="bg-primary text-primary-foreground hover:bg-primary/90"
+            >
+              {t("acceptAll")}
+            </Button>
+            <Button
+              variant="outline"
+              onClick={handleRejectAll}
+              className="border-border text-foreground hover:bg-muted"
+            >
+              {t("rejectAll")}
+            </Button>
+          </div>
+          <Button variant="outline" onClick={handleSavePreferences}>
+            {t("dialog.acceptCurrentSelection")}
+          </Button>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/template/src/features/shared/components/index.ts

@@ -0,0 +1,5 @@
+// Shared Components
+export { CookieSettingsDialog } from "./cookie-settings-dialog";
+export { LanguageSwitcher } from "./language-switcher";
+export { MaxWidthWrapper } from "./max-width-wrapper";
+export { ModeToggle } from "./mode-toggle";

package/template/src/features/shared/components/language-switcher.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+import { Globe } from "lucide-react";
+import { useParams } from "next/navigation";
+import { useLocale } from "next-intl";
+import { useTransition } from "react";
+
+import { Button } from "@/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { usePathname, useRouter } from "@/i18n/routing";
+
+/**
+ * 支持的语言配置
+ */
+const locales = [
+  { code: "en", label: "English", flag: "🇺🇸" },
+  { code: "zh", label: "中文", flag: "🇨🇳" },
+] as const;
+
+/**
+ * 语言切换器组件
+ *
+ * 功能:
+ * - 显示当前语言
+ * - 下拉菜单切换语言
+ * - 切换时保持当前路径
+ */
+export function LanguageSwitcher() {
+  const locale = useLocale();
+  const router = useRouter();
+  const pathname = usePathname();
+  const params = useParams();
+  const [isPending, startTransition] = useTransition();
+
+  /**
+   * 切换语言
+   */
+  const handleLocaleChange = (newLocale: string) => {
+    startTransition(() => {
+      router.replace(
+        // @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.
+        { pathname, params },
+        { locale: newLocale }
+      );
+    });
+  };
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button
+          variant="ghost"
+          size="icon"
+          disabled={isPending}
+          className="relative"
+        >
+          <Globe className="h-5 w-5" />
+          <span className="sr-only">切换语言</span>
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end">
+        {locales.map((loc) => (
+          <DropdownMenuItem
+            key={loc.code}
+            onClick={() => handleLocaleChange(loc.code)}
+            className={locale === loc.code ? "bg-accent" : ""}
+          >
+            <span className="mr-2">{loc.flag}</span>
+            {loc.label}
+          </DropdownMenuItem>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}

package/template/src/features/shared/components/max-width-wrapper.tsx

@@ -0,0 +1,49 @@
+import { cn } from "@/lib/utils";
+
+/**
+ * 最大宽度容器组件
+ *
+ * 功能:
+ * - 提供统一的页面内容最大宽度限制
+ * - 自动居中对齐
+ * - 响应式内边距
+ *
+ * 使用场景:
+ * - 包裹页面主要内容区域
+ * - 确保内容在大屏幕上不会过宽
+ */
+
+interface MaxWidthWrapperProps {
+  /**
+   * 子元素
+   */
+  children: React.ReactNode;
+  /**
+   * 自定义类名
+   */
+  className?: string;
+  /**
+   * 是否使用较小的最大宽度
+   * - false: max-w-7xl (默认, 80rem)
+   * - true: max-w-5xl (64rem)
+   */
+  narrow?: boolean;
+}
+
+export function MaxWidthWrapper({
+  children,
+  className,
+  narrow = false,
+}: MaxWidthWrapperProps) {
+  return (
+    <div
+      className={cn(
+        "mx-auto w-full px-4 sm:px-6 lg:px-8",
+        narrow ? "max-w-5xl" : "max-w-7xl",
+        className
+      )}
+    >
+      {children}
+    </div>
+  );
+}

package/template/src/features/shared/components/mode-toggle.tsx

@@ -0,0 +1,119 @@
+"use client";
+
+import { Monitor, Moon, Sun } from "lucide-react";
+import { useTheme } from "next-themes";
+
+import { Button } from "@/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { cn } from "@/lib/utils";
+
+/**
+ * 主题切换组件
+ *
+ * 功能:
+ * - 在浅色、深色、系统主题之间切换
+ * - 使用 next-themes 管理主题状态
+ * - 支持两种显示模式: dropdown 和 inline
+ */
+
+interface ModeToggleProps {
+  /**
+   * 显示模式
+   * - dropdown: 下拉菜单形式 (默认)
+   * - inline: 并排按钮形式
+   */
+  variant?: "dropdown" | "inline";
+  /**
+   * 自定义类名
+   */
+  className?: string;
+}
+
+export function ModeToggle({
+  variant = "dropdown",
+  className,
+}: ModeToggleProps) {
+  const { theme, setTheme } = useTheme();
+
+  // 内联按钮模式
+  if (variant === "inline") {
+    return (
+      <div className={cn("flex items-center gap-1", className)}>
+        <button
+          type="button"
+          onClick={() => setTheme("light")}
+          className={cn(
+            "flex h-9 w-9 items-center justify-center rounded-md transition-colors",
+            theme === "light"
+              ? "bg-muted text-foreground"
+              : "text-muted-foreground hover:bg-muted hover:text-foreground"
+          )}
+          title="浅色模式"
+        >
+          <Sun className="h-4 w-4" />
+          <span className="sr-only">浅色模式</span>
+        </button>
+        <button
+          type="button"
+          onClick={() => setTheme("dark")}
+          className={cn(
+            "flex h-9 w-9 items-center justify-center rounded-md transition-colors",
+            theme === "dark"
+              ? "bg-muted text-foreground"
+              : "text-muted-foreground hover:bg-muted hover:text-foreground"
+          )}
+          title="深色模式"
+        >
+          <Moon className="h-4 w-4" />
+          <span className="sr-only">深色模式</span>
+        </button>
+        <button
+          type="button"
+          onClick={() => setTheme("system")}
+          className={cn(
+            "flex h-9 w-9 items-center justify-center rounded-md transition-colors",
+            theme === "system"
+              ? "bg-primary/10 text-primary dark:bg-primary/20 dark:text-primary"
+              : "text-muted-foreground hover:bg-muted hover:text-foreground"
+          )}
+          title="跟随系统"
+        >
+          <Monitor className="h-4 w-4" />
+          <span className="sr-only">跟随系统</span>
+        </button>
+      </div>
+    );
+  }
+
+  // 下拉菜单模式 (默认)
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button variant="ghost" size="icon" className={className}>
+          <Sun className="h-5 w-5 rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
+          <Moon className="absolute h-5 w-5 rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
+          <span className="sr-only">切换主题</span>
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end">
+        <DropdownMenuItem onClick={() => setTheme("light")}>
+          <Sun className="mr-2 h-4 w-4" />
+          浅色
+        </DropdownMenuItem>
+        <DropdownMenuItem onClick={() => setTheme("dark")}>
+          <Moon className="mr-2 h-4 w-4" />
+          深色
+        </DropdownMenuItem>
+        <DropdownMenuItem onClick={() => setTheme("system")}>
+          <Monitor className="mr-2 h-4 w-4" />
+          跟随系统
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}

package/template/src/features/shared/icons/google-icon.tsx

@@ -0,0 +1,39 @@
+/**
+ * Google 图标组件
+ *
+ * 用于 OAuth 登录按钮显示 Google 品牌图标
+ * 使用官方 Google 品牌颜色
+ */
+
+interface GoogleIconProps {
+  /** 自定义类名 */
+  className?: string;
+}
+
+export function GoogleIcon({ className }: GoogleIconProps) {
+  return (
+    <svg className={className} viewBox="0 0 24 24">
+      <title>Google</title>
+      {/* Google 蓝色 - 右侧弧形 */}
+      <path
+        d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"
+        fill="#4285F4"
+      />
+      {/* Google 绿色 - 底部弧形 */}
+      <path
+        d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"
+        fill="#34A853"
+      />
+      {/* Google 黄色 - 左侧弧形 */}
+      <path
+        d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"
+        fill="#FBBC05"
+      />
+      {/* Google 红色 - 顶部弧形 */}
+      <path
+        d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"
+        fill="#EA4335"
+      />
+    </svg>
+  );
+}

package/template/src/features/shared/icons/index.ts

@@ -0,0 +1,7 @@
+/**
+ * 共享图标组件导出
+ *
+ * 包含第三方品牌图标和自定义图标
+ */
+
+export { GoogleIcon } from "./google-icon";

package/template/src/features/shared/index.ts

@@ -0,0 +1,5 @@
+// 共享组件和工具导出
+export * from "./components";
+export * from "./icons";
+export { Providers } from "./providers";
+export { sharedModule } from "./manifest";

package/template/src/features/shared/manifest.ts

@@ -0,0 +1,13 @@
+import { defineModule } from "@/core/modules";
+
+export const sharedModule = defineModule({
+  id: "shared",
+  name: "Shared UI",
+  description: "跨页面复用的基础组件、图标和 Provider",
+  kind: "core",
+  dependencies: [],
+  routes: [],
+  navigation: [],
+  translations: ["Common", "Cookie"],
+  schema: [],
+});

package/template/src/features/shared/providers.tsx

@@ -0,0 +1,59 @@
+"use client";
+
+import { RootProvider } from "fumadocs-ui/provider/next";
+import { ThemeProvider } from "next-themes";
+
+/**
+ * 全局 Providers 组件
+ *
+ * 功能:
+ * - 主题管理 (next-themes)
+ * - Fumadocs UI 框架支持 (RootProvider)
+ * - 可扩展添加其他 Provider (如 QueryClient, SessionProvider 等)
+ */
+
+interface ProvidersProps {
+  children: React.ReactNode;
+  locale?: string;
+}
+
+const docsLocales = [
+  { locale: "en", name: "English" },
+  { locale: "zh", name: "中文" },
+];
+
+const zhDocsTranslations = {
+  search: "搜索",
+  searchNoResult: "没有找到结果",
+  toc: "本页目录",
+  tocNoHeadings: "没有标题",
+  lastUpdate: "最后更新于",
+  chooseLanguage: "选择语言",
+  nextPage: "下一页",
+  previousPage: "上一页",
+  chooseTheme: "选择主题",
+  editOnGithub: "在 GitHub 编辑",
+} as const;
+
+export function Providers({ children, locale = "en" }: ProvidersProps) {
+  const docsLocale = locale === "zh" ? "zh" : "en";
+
+  return (
+    <ThemeProvider
+      attribute="class"
+      defaultTheme="system"
+      enableSystem
+      disableTransitionOnChange
+    >
+      <RootProvider
+        i18n={{
+          locale: docsLocale,
+          locales: docsLocales,
+          ...(docsLocale === "zh" ? { translations: zhDocsTranslations } : {}),
+        }}
+      >
+        {children}
+      </RootProvider>
+    </ThemeProvider>
+  );
+}