create-pardx-scaffold 0.1.10 → 0.1.11

package/template/apps/web/components/client-only.tsx

@@ -0,0 +1,28 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+interface ClientOnlyProps {
+  children: React.ReactNode;
+  /** Optional fallback during SSR and before mount. Use to avoid layout shift. */
+  fallback?: React.ReactNode;
+}
+
+/**
+ * Renders children only after the component has mounted on the client.
+ * Use to avoid hydration mismatches for components that rely on client-only
+ * APIs or generate different markup on server vs client (e.g. Radix UI useId).
+ */
+export function ClientOnly({ children, fallback = null }: ClientOnlyProps) {
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  if (!mounted) {
+    return <>{fallback}</>;
+  }
+
+  return <>{children}</>;
+}

package/template/apps/web/components/index.ts

@@ -29,3 +29,26 @@ export {
   withSuspense,
   withAsyncBoundary,
 } from './suspense-utils';
+
+// Client-only rendering
+export { ClientOnly } from './client-only';
+
+// Runtime i18n bridge
+export { RuntimeI18nBridge } from './runtime-i18n-bridge';
+
+// State components
+export {
+  LoadingSpinner,
+  ErrorState,
+  EmptyState,
+  PageLoading,
+  PageError,
+} from './state-components';
+
+// Layout components
+export {
+  AppShell,
+  AppSidebar,
+  AppNavbar,
+  LocaleSwitcher,
+} from './layout';

package/template/apps/web/components/layout/app-navbar.tsx

@@ -0,0 +1,109 @@
+'use client';
+
+import { ClientOnly } from '@/components/client-only';
+import { useAuth } from '@/providers';
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  Button,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+  Separator,
+  SidebarTrigger,
+} from '@repo/ui';
+import { LogOut, Search, Settings, User } from 'lucide-react';
+import { useTranslations } from 'next-intl';
+import { Link } from '@/i18n/navigation';
+import { LocaleSwitcher } from './locale-switcher';
+
+/**
+ * Get initials from nickname
+ * Returns first character of nickname (uppercase)
+ */
+function getInitials(nickname: string | null | undefined): string {
+  if (!nickname) return '';
+  return nickname.charAt(0).toUpperCase();
+}
+
+export function AppNavbar() {
+  const t = useTranslations('navigation.menu');
+  const { user, logout } = useAuth();
+
+  const handleLogout = () => {
+    logout();
+  };
+
+  const initials = getInitials(user?.nickname);
+
+  return (
+    <header className="flex h-14 shrink-0 items-center justify-between border-b px-4">
+      <div className="flex items-center gap-3">
+        {/* Mobile sidebar trigger - only visible on mobile */}
+        <SidebarTrigger className="md:hidden -ml-2" />
+      </div>
+
+      <div className="flex items-center gap-1">
+        <Button variant="ghost" size="icon" className="size-8">
+          <Search className="size-4" />
+          <span className="sr-only">{t('search')}</span>
+        </Button>
+        <Separator orientation="vertical" className="mx-1 h-4" />
+        <LocaleSwitcher />
+        <Separator orientation="vertical" className="mx-1 h-4" />
+        <ClientOnly
+          fallback={
+            <Button variant="ghost" size="icon" className="size-8 rounded-full">
+              <Avatar className="size-8">
+                <AvatarFallback className="text-xs">
+                  <User className="size-4" />
+                </AvatarFallback>
+              </Avatar>
+            </Button>
+          }
+        >
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button variant="ghost" size="icon" className="size-8 rounded-full">
+                <Avatar className="size-8">
+                  <AvatarImage
+                    src={user?.headerImg || ''}
+                    alt={user?.nickname || 'User'}
+                  />
+                  <AvatarFallback className="text-xs">
+                    {initials || <User className="size-4" />}
+                  </AvatarFallback>
+                </Avatar>
+              </Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="end" className="w-48">
+              <DropdownMenuLabel>{user?.nickname || t('account')}</DropdownMenuLabel>
+              <DropdownMenuSeparator />
+              <DropdownMenuItem asChild>
+                <Link href="/settings">
+                  <User className="mr-2 size-4" />
+                  {t('profile')}
+                </Link>
+              </DropdownMenuItem>
+              <DropdownMenuItem asChild>
+                <Link href="/settings">
+                  <Settings className="mr-2 size-4" />
+                  {t('settings')}
+                </Link>
+              </DropdownMenuItem>
+              <DropdownMenuSeparator />
+              <DropdownMenuItem variant="destructive" onClick={handleLogout}>
+                <LogOut className="mr-2 size-4" />
+                {t('logout')}
+              </DropdownMenuItem>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        </ClientOnly>
+      </div>
+    </header>
+  );
+}

package/template/apps/web/components/layout/app-shell.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import { SidebarInset, SidebarProvider } from '@repo/ui';
+import { AppNavbar } from './app-navbar';
+import { AppSidebar } from './app-sidebar';
+
+interface AppShellProps {
+  children: React.ReactNode;
+}
+
+export function AppShell({ children }: AppShellProps) {
+  return (
+    <SidebarProvider defaultOpen={true}>
+      <div className="flex h-screen flex-col w-full">
+        {/* Full-width navbar at top */}
+        <AppNavbar />
+
+        {/* Sidebar and content below navbar */}
+        <div className="flex flex-1 overflow-hidden [&_[data-slot=sidebar-container]]:top-14 [&_[data-slot=sidebar-container]]:h-[calc(100svh-3.5rem)] [&_[data-slot=sidebar-wrapper]]:min-h-0">
+          <AppSidebar />
+          <SidebarInset>
+            <main className="flex h-full flex-1 flex-col overflow-hidden">
+              <div className="h-full flex-1 overflow-auto">{children}</div>
+            </main>
+          </SidebarInset>
+        </div>
+      </div>
+    </SidebarProvider>
+  );
+}

package/template/apps/web/components/layout/app-sidebar.tsx

@@ -0,0 +1,206 @@
+'use client';
+
+import { useMemo, useCallback, memo } from 'react';
+import type { ComponentType } from 'react';
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarTrigger,
+} from '@repo/ui';
+import { cn } from '@repo/ui/lib/utils';
+import {
+  LayoutDashboard,
+  Settings,
+  type LucideIcon,
+} from 'lucide-react';
+import { useTranslations } from 'next-intl';
+import { Link, usePathname } from '@/i18n/navigation';
+import { useApp, useIsAdmin } from '@/providers';
+
+interface NavGroup {
+  groupKey: string;
+  items: NavItem[];
+}
+
+interface NavItem {
+  titleKey?: string;
+  title?: string;
+  href: string;
+  icon: ComponentType<{ className?: string }>;
+  adminOnly?: boolean;
+}
+
+/**
+ * Navigation configuration for sidebar
+ * Customize this for your application
+ */
+const navGroups: NavGroup[] = [
+  {
+    groupKey: 'main',
+    items: [
+      {
+        titleKey: 'dashboard',
+        href: '/dashboard',
+        icon: LayoutDashboard,
+      },
+    ],
+  },
+  {
+    groupKey: 'settings',
+    items: [
+      {
+        titleKey: 'settings',
+        href: '/settings',
+        icon: Settings,
+      },
+    ],
+  },
+];
+
+// Memoized nav item component
+const NavItemComponent = memo(function NavItemComponent({
+  item,
+  isActive,
+  title,
+}: {
+  item: NavItem;
+  isActive: boolean;
+  title: string;
+}) {
+  return (
+    <SidebarMenuItem key={item.href}>
+      <SidebarMenuButton
+        asChild
+        isActive={isActive}
+        tooltip={title}
+        className={cn(
+          'relative h-9 rounded-md transition-all duration-150',
+          isActive
+            ? ['bg-primary/20', 'font-medium', 'shadow-sm']
+            : ['hover:bg-accent'],
+        )}
+      >
+        <Link
+          href={item.href}
+          className="flex items-center gap-2 group-data-[collapsible=icon]:justify-center"
+        >
+          <item.icon
+            className={cn(
+              'size-4 shrink-0',
+              isActive ? 'text-primary' : '',
+            )}
+          />
+          <span className="truncate group-data-[collapsible=icon]:hidden">
+            {title}
+          </span>
+          {isActive && (
+            <span className="absolute left-0 top-1/2 -translate-y-1/2 w-[3px] h-5 bg-primary rounded-r-full" />
+          )}
+        </Link>
+      </SidebarMenuButton>
+    </SidebarMenuItem>
+  );
+});
+
+export function AppSidebar() {
+  const t = useTranslations('navigation.menu');
+  const pathname = usePathname();
+  const { brandName, brandLogo } = useApp();
+  const isAdmin = useIsAdmin();
+
+  const currentPath = useMemo(() => pathname || '/', [pathname]);
+
+  // Memoize filtered groups based on admin permission
+  const filteredGroups = useMemo(() => {
+    return navGroups
+      .map((group) => ({
+        ...group,
+        items: group.items.filter((item) => !item.adminOnly || isAdmin),
+      }))
+      .filter((group) => group.items.length > 0);
+  }, [isAdmin]);
+
+  // Memoize title getter
+  const getItemTitle = useCallback(
+    (item: NavItem) => item.title || (item.titleKey ? t(item.titleKey) : ''),
+    [t],
+  );
+
+  // Memoize active state checker
+  const isItemActive = useCallback(
+    (href: string) =>
+      currentPath === href || currentPath.startsWith(`${href}/`),
+    [currentPath],
+  );
+
+  // Render a navigation group
+  const renderNavGroup = useCallback(
+    (group: NavGroup & { items: NavItem[] }) => (
+      <SidebarGroup key={group.groupKey}>
+        <SidebarGroupLabel className="uppercase tracking-widest text-[10px] font-medium px-3 mb-1">
+          {t(
+            `group${group.groupKey.charAt(0).toUpperCase()}${group.groupKey.slice(1)}` as Parameters<
+              typeof t
+            >[0],
+          )}
+        </SidebarGroupLabel>
+        <SidebarGroupContent>
+          <SidebarMenu className="gap-1 px-2">
+            {group.items.map((item) => (
+              <NavItemComponent
+                key={item.href}
+                item={item}
+                isActive={isItemActive(item.href)}
+                title={getItemTitle(item)}
+              />
+            ))}
+          </SidebarMenu>
+        </SidebarGroupContent>
+      </SidebarGroup>
+    ),
+    [t, isItemActive, getItemTitle],
+  );
+
+  return (
+    <Sidebar collapsible="icon" variant="sidebar">
+      <SidebarContent className="pt-4">
+        {filteredGroups.map(renderNavGroup)}
+      </SidebarContent>
+
+      <SidebarFooter className="border-t border-sidebar-border/50 relative">
+        <div className="p-3">
+          <div className="flex items-center">
+            {/* Expanded state: show logo + brand name */}
+            <div className="flex items-center gap-2 group-data-[collapsible=icon]:hidden">
+              <span className="font-semibold truncate">
+                {brandName}
+              </span>
+            </div>
+
+            {/* Collapsed state: only show brand name initial */}
+            <div className="hidden group-data-[collapsible=icon]:flex items-center justify-center w-full">
+              <span className="font-semibold">
+                {brandName.charAt(0)}
+              </span>
+            </div>
+          </div>
+        </div>
+
+        {/* Collapse/expand button, fixed at bottom right */}
+        <div
+          className="absolute -right-3"
+          style={{ bottom: 'calc(0.75rem + 50px)' }}
+        >
+          <SidebarTrigger className="size-8 bg-accent" />
+        </div>
+      </SidebarFooter>
+    </Sidebar>
+  );
+}

package/template/apps/web/components/layout/index.ts

@@ -0,0 +1,4 @@
+export { AppShell } from './app-shell';
+export { AppSidebar } from './app-sidebar';
+export { AppNavbar } from './app-navbar';
+export { LocaleSwitcher } from './locale-switcher';

package/template/apps/web/components/layout/locale-switcher.tsx

@@ -0,0 +1,57 @@
+'use client';
+
+import { useLocale, useTranslations } from 'next-intl';
+import { Globe } from 'lucide-react';
+import {
+  Button,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@repo/ui';
+import { useRouter, usePathname } from '@/i18n/navigation';
+import { locales, localeNames, localeFlags, type Locale } from '@/i18n/config';
+import { ClientOnly } from '@/components/client-only';
+
+export function LocaleSwitcher() {
+  const locale = useLocale() as Locale;
+  const ta = useTranslations('navigation.a11y');
+  const router = useRouter();
+  const pathname = usePathname();
+
+  const handleLocaleChange = (newLocale: Locale) => {
+    router.replace(pathname, { locale: newLocale });
+  };
+
+  const triggerButton = (
+    <Button variant="ghost" size="icon" className="size-8">
+      <Globe className="size-4" />
+      <span className="sr-only">{ta('switchLanguage')}</span>
+    </Button>
+  );
+
+  return (
+    <ClientOnly fallback={triggerButton}>
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button variant="ghost" size="icon" className="size-8">
+            <Globe className="size-4" />
+            <span className="sr-only">{ta('switchLanguage')}</span>
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end">
+          {locales.map((loc) => (
+            <DropdownMenuItem
+              key={loc}
+              onClick={() => handleLocaleChange(loc)}
+              className={locale === loc ? 'bg-accent' : ''}
+            >
+              <span className="mr-2">{localeFlags[loc]}</span>
+              {localeNames[loc]}
+            </DropdownMenuItem>
+          ))}
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </ClientOnly>
+  );
+}

package/template/apps/web/components/runtime-i18n-bridge.tsx

@@ -0,0 +1,32 @@
+'use client';
+
+import { useEffect } from 'react';
+import { useTranslations } from 'next-intl';
+import { registerIntlNamespace } from '@/lib/i18n/runtime-translator';
+
+/**
+ * 向非 React 模块（如 ts-rest fetch、deprecation-warning）注册 errors / common 的翻译函数。
+ */
+export function RuntimeI18nBridge() {
+  const tErrors = useTranslations('errors');
+  const tCommon = useTranslations('common');
+
+  useEffect(() => {
+    registerIntlNamespace('errors', (key, values) =>
+      values && Object.keys(values).length > 0
+        ? tErrors(key, values)
+        : tErrors(key),
+    );
+    registerIntlNamespace('common', (key, values) =>
+      values && Object.keys(values).length > 0
+        ? tCommon(key, values)
+        : tCommon(key),
+    );
+    return () => {
+      registerIntlNamespace('errors', null);
+      registerIntlNamespace('common', null);
+    };
+  }, [tErrors, tCommon]);
+
+  return null;
+}