sh-ui-cli 0.57.0 → 0.58.0

package/templates/nextjs-standalone/_arch/fsd/src/app/providers/GlobalProvider/index.tsx

@@ -0,0 +1,23 @@
+import type { ReactNode } from 'react';
+import { Toaster } from 'sonner';
+
+import { QueryClientProvider } from '../tanstack/QueryClientProvider';
+import { TanstackDevtoolsProvider } from '../tanstack/TanstackDevtoolsProvider';
+import { ThemeProviders } from '../theme/ThemeProviders';
+
+interface GlobalProviderProps {
+  children: ReactNode;
+}
+
+export function GlobalProvider({ children }: GlobalProviderProps) {
+  return (
+    <ThemeProviders>
+      <QueryClientProvider>
+        <TanstackDevtoolsProvider>
+          <Toaster />
+          {children}
+        </TanstackDevtoolsProvider>
+      </QueryClientProvider>
+    </ThemeProviders>
+  );
+}

package/templates/nextjs-standalone/_arch/fsd/src/app/providers/index.tsx

@@ -0,0 +1 @@
+export { GlobalProvider } from './GlobalProvider';

package/templates/nextjs-standalone/_arch/fsd/src/app/providers/tanstack/TanstackDevtoolsProvider.tsx

@@ -0,0 +1,13 @@
+'use client';
+
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
+import type { ReactNode } from 'react';
+
+export function TanstackDevtoolsProvider({ children }: { children: ReactNode }) {
+  return (
+    <>
+      {children}
+      <ReactQueryDevtools initialIsOpen={false} />
+    </>
+  );
+}

package/templates/nextjs-standalone/_arch/fsd/src/app/providers/theme/ThemeProviders.tsx

@@ -0,0 +1,12 @@
+'use client';
+
+import { ThemeProvider } from 'next-themes';
+import type { ReactNode } from 'react';
+
+export function ThemeProviders({ children }: { children: ReactNode }) {
+  return (
+    <ThemeProvider attribute='class' defaultTheme='system' enableSystem>
+      {children}
+    </ThemeProvider>
+  );
+}

package/templates/nextjs-standalone/_arch/fsd/src/shared/api/apiTypes.ts

@@ -0,0 +1,21 @@
+/** 공통 API 에러 형식 */
+export type ApiErrorBody = {
+  message: string;
+  code: string;
+};
+
+/** 백엔드 공통 응답 래퍼 */
+export type ApiResponse<TData = unknown, TError = ApiErrorBody> = {
+  result: 'SUCCESS' | 'ERROR';
+  data: TData;
+  error: TError | null;
+};
+
+/** 페이지네이션 응답 래퍼 */
+export type PaginatedData<T> = {
+  content: T[];
+  totalItems: number;
+  offset: number;
+  limit: number;
+  hasNext: boolean;
+};

package/templates/nextjs-standalone/_arch/fsd/src/shared/api/clientFetch.ts

@@ -0,0 +1,40 @@
+'use client';
+
+import type { ApiResponse } from './apiTypes';
+import { ApiError } from './error';
+
+const PROXY_BASE = '/api/proxy';
+
+export async function clientFetch<T>(
+  path: string,
+  init: RequestInit = {},
+): Promise<T> {
+  const url = `${PROXY_BASE}${path.startsWith('/') ? path : `/${path}`}`;
+
+  const res = await fetch(url, {
+    ...init,
+    headers: {
+      'Content-Type': 'application/json',
+      ...(init.headers as Record<string, string> | undefined),
+    },
+    credentials: 'include',
+  });
+
+  const body = (await res.json()) as ApiResponse<T>;
+
+  if (res.status === 401) {
+    if (
+      typeof window !== 'undefined' &&
+      !window.location.pathname.startsWith('/sign-in')
+    ) {
+      window.location.href = '/sign-in';
+    }
+    throw new ApiError(401, body.error?.code ?? 'UNAUTHORIZED', body.error);
+  }
+
+  if (!res.ok || body.result === 'ERROR') {
+    throw new ApiError(res.status, body.error?.code ?? '', body.error);
+  }
+
+  return body.data;
+}

package/templates/nextjs-standalone/_arch/fsd/src/shared/api/error.ts

@@ -0,0 +1,12 @@
+import type { ApiErrorBody } from './apiTypes';
+
+export class ApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly code: string,
+    public readonly data: ApiErrorBody | null,
+  ) {
+    super(data?.message ?? `API 요청 실패 (${status})`);
+    this.name = 'ApiError';
+  }
+}

package/templates/nextjs-standalone/_arch/fsd/src/shared/api/http.ts

@@ -0,0 +1,13 @@
+import { clientFetch } from './clientFetch';
+import { serverFetch } from './serverFetch';
+
+/**
+ * isomorphic 진입점.
+ * RSC/서버에서는 백엔드로 직통, 브라우저에서는 /api/proxy 경유.
+ * API 함수는 한 번만 작성하고 환경 분기는 여기서 처리한다.
+ */
+export function http<T>(path: string, init?: RequestInit): Promise<T> {
+  return typeof window === 'undefined'
+    ? serverFetch<T>(path, init)
+    : clientFetch<T>(path, init);
+}

package/templates/nextjs-standalone/_arch/fsd/src/shared/api/observability.ts

@@ -0,0 +1,20 @@
+type ApiCaptureParams = {
+  url: string;
+  apiPath: string;
+  method: string;
+  status: number | undefined;
+  responseBody?: unknown;
+};
+
+type ApiLogParams = {
+  url: string;
+  method: string;
+  status: number | undefined;
+  requestHeaders?: Record<string, string | undefined>;
+  requestBody?: unknown;
+  responseBody?: unknown;
+};
+
+export const captureApiError = (_params: ApiCaptureParams): void => {};
+
+export const logApiError = (_prefix: string, _params: ApiLogParams): void => {};

package/templates/nextjs-standalone/_arch/fsd/src/shared/api/queryClient.ts

@@ -0,0 +1,30 @@
+import {
+  QueryClient,
+  defaultShouldDehydrateQuery,
+  isServer,
+} from '@tanstack/react-query';
+import { cache } from 'react';
+
+function makeQueryClient(): QueryClient {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000,
+        retry: 1,
+      },
+      dehydrate: {
+        shouldDehydrateQuery: (q) =>
+          defaultShouldDehydrateQuery(q) || q.state.status === 'pending',
+      },
+    },
+  });
+}
+
+export const getServerQueryClient = cache(makeQueryClient);
+
+let browserQueryClient: QueryClient | undefined;
+
+export function getBrowserQueryClient(): QueryClient {
+  if (isServer) return makeQueryClient();
+  return (browserQueryClient ??= makeQueryClient());
+}

package/templates/nextjs-standalone/_arch/fsd/src/shared/api/serverFetch.ts

@@ -0,0 +1,59 @@
+import { cookies } from 'next/headers';
+
+import type { ApiResponse } from './apiTypes';
+import { ApiError } from './error';
+import { captureApiError, logApiError } from './observability';
+
+const API_URL = process.env.API_URL ?? 'http://localhost:8080/api';
+
+const ACCESS_TOKEN_COOKIE = 'accessToken';
+const LOCALE_COOKIE = 'NEXT_LOCALE';
+
+export async function serverFetch<T>(
+  path: string,
+  init: RequestInit = {},
+): Promise<T> {
+  const jar = await cookies();
+  const accessToken = jar.get(ACCESS_TOKEN_COOKIE)?.value;
+  const locale = jar.get(LOCALE_COOKIE)?.value;
+
+  const url = `${API_URL}${path.startsWith('/') ? path : `/${path}`}`;
+  const method = (init.method ?? 'GET').toUpperCase();
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    ...(accessToken && { Authorization: `Bearer ${accessToken}` }),
+    ...(locale && { 'Accept-Language': locale }),
+    ...(init.headers as Record<string, string> | undefined),
+  };
+
+  const res = await fetch(url, {
+    ...init,
+    headers,
+    cache: init.cache ?? 'no-store',
+  });
+
+  const body = (await res.json()) as ApiResponse<T>;
+
+  if (!res.ok || body.result === 'ERROR') {
+    logApiError('SERVER_FETCH', {
+      url,
+      method,
+      status: res.status,
+      requestBody: typeof init.body === 'string' ? init.body : undefined,
+      responseBody: body,
+    });
+
+    captureApiError({
+      url,
+      apiPath: path,
+      method,
+      status: res.status,
+      responseBody: body,
+    });
+
+    throw new ApiError(res.status, body.error?.code ?? '', body.error);
+  }
+
+  return body.data;
+}

package/templates/nextjs-standalone/_arch/fsd/src/shared/hooks/useAppMutation.ts

@@ -0,0 +1,52 @@
+import {
+  useMutation,
+  type UseMutationOptions,
+  type DefaultError,
+} from '@tanstack/react-query';
+import { toast } from 'sonner';
+
+import { ApiError } from '../api/error';
+
+type AppMutationOptions<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TContext = unknown,
+> = UseMutationOptions<TData, TError, TVariables, TContext> & {
+  errorMessage?: string;
+  showErrorToast?: boolean;
+};
+
+/**
+ * useMutation 래퍼 — 에러 발생 시 ApiError.message 를 toast 로 띄운다.
+ * showErrorToast: false 로 끌 수 있고, errorMessage 로 fallback 메시지 지정.
+ */
+export const useAppMutation = <
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TContext = unknown,
+>(
+  options: AppMutationOptions<TData, TError, TVariables, TContext>,
+) => {
+  const { errorMessage, showErrorToast = true, onError, ...rest } = options;
+
+  return useMutation({
+    ...rest,
+    onError: (...args) => {
+      onError?.(...args);
+
+      if (!showErrorToast) return;
+
+      const [error] = args;
+      const message =
+        error instanceof ApiError
+          ? (error.data?.message ?? errorMessage)
+          : errorMessage;
+
+      if (message) {
+        toast.error(message);
+      }
+    },
+  });
+};

package/templates/nextjs-standalone/_arch/fsd/src/shared/lib/formatDate.ts

@@ -0,0 +1,22 @@
+/**
+ * Date → 로케일 기반 날짜 포맷 (시간 없음).
+ */
+export const formatDate = (date: Date, locale = 'ko-KR'): string =>
+  new Intl.DateTimeFormat(locale, {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  }).format(date);
+
+/**
+ * Date → 로케일 기반 날짜 + 시간 포맷 (24h).
+ */
+export const formatDateTime = (date: Date, locale = 'ko-KR'): string =>
+  new Intl.DateTimeFormat(locale, {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+  }).format(date);

package/templates/nextjs-standalone/_arch/fsd/src/shared/lib/formatPrice.ts

@@ -0,0 +1,10 @@
+/**
+ * 숫자 → 한국 원화(KRW) 포맷. 소수점 없음.
+ * 예: 12000 → "₩12,000"
+ */
+export const formatPrice = (amount: number, locale = 'ko-KR'): string =>
+  new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency: 'KRW',
+    maximumFractionDigits: 0,
+  }).format(amount);

package/templates/nextjs-standalone/_arch/fsd/src/shared/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/templates/nextjs-standalone/_arch/fsd/src/shared/styles/tokens.css

@@ -0,0 +1,135 @@
+/* Generated by @sh-ui/tokens — do not edit directly */
+/* base=neutral radius=md mode=light-dark */
+
+/* sh-ui:theme-colors-start */
+:root {
+  --background: #FFFFFF;
+  --background-subtle: #FAFAFA;
+  --background-muted: #F5F5F5;
+  --background-inverse: #0A0A0A;
+  --foreground: #0A0A0A;
+  --foreground-muted: #525252;
+  --foreground-subtle: #A3A3A3;
+  --foreground-inverse: #FFFFFF;
+  --border: #E5E5E5;
+  --border-strong: #D4D4D4;
+  --primary: #171717;
+  --primary-foreground: #FAFAFA;
+  --primary-hover: #262626;
+  --danger: #DC2626;
+  --danger-foreground: #FFFFFF;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not(.light):not(.dark) {
+    --background: #0A0A0A;
+    --background-subtle: #171717;
+    --background-muted: #262626;
+    --background-inverse: #FFFFFF;
+    --foreground: #FAFAFA;
+    --foreground-muted: #A3A3A3;
+    --foreground-subtle: #737373;
+    --foreground-inverse: #0A0A0A;
+    --border: #262626;
+    --border-strong: #404040;
+    --primary: #FAFAFA;
+    --primary-foreground: #171717;
+    --primary-hover: #E5E5E5;
+    --danger: #DC2626;
+    --danger-foreground: #FFFFFF;
+  }
+}
+.dark {
+  --background: #0A0A0A;
+  --background-subtle: #171717;
+  --background-muted: #262626;
+  --background-inverse: #FFFFFF;
+  --foreground: #FAFAFA;
+  --foreground-muted: #A3A3A3;
+  --foreground-subtle: #737373;
+  --foreground-inverse: #0A0A0A;
+  --border: #262626;
+  --border-strong: #404040;
+  --primary: #FAFAFA;
+  --primary-foreground: #171717;
+  --primary-hover: #E5E5E5;
+  --danger: #DC2626;
+  --danger-foreground: #FFFFFF;
+}
+/* sh-ui:theme-colors-end */
+
+:root {
+  /* sh-ui:theme-radius-start */
+  --radius: 0.5rem;
+  /* sh-ui:theme-radius-end */
+  /* sh-ui:theme-space-start */
+  --space-0: 0px;
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-5: 20px;
+  --space-6: 24px;
+  --space-8: 32px;
+  --space-10: 40px;
+  --space-12: 48px;
+  --space-16: 64px;
+  /* sh-ui:theme-space-end */
+  /* sh-ui:theme-text-start */
+  --text-xs: 12px;
+  --text-sm: 14px;
+  --text-base: 16px;
+  --text-lg: 18px;
+  --text-xl: 20px;
+  --text-2xl: 24px;
+  --text-3xl: 30px;
+  --text-4xl: 36px;
+  /* sh-ui:theme-text-end */
+  /* sh-ui:theme-weight-start */
+  --weight-regular: 400;
+  --weight-medium: 500;
+  --weight-semibold: 600;
+  --weight-bold: 700;
+  /* sh-ui:theme-weight-end */
+  /* sh-ui:theme-shadow-start */
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.08);
+  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.12);
+  --shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.15);
+  --shadow-xl: 0 16px 48px rgba(0, 0, 0, 0.18);
+  /* sh-ui:theme-shadow-end */
+  /* sh-ui:theme-duration-start */
+  --duration-fast: 120ms;
+  --duration-base: 160ms;
+  --duration-slow: 200ms;
+  /* sh-ui:theme-duration-end */
+  /* sh-ui:theme-ease-start */
+  --ease-standard: cubic-bezier(0.4, 0, 0.2, 1);
+  --ease-emphasized: cubic-bezier(0.2, 0, 0, 1);
+  /* sh-ui:theme-ease-end */
+  /* sh-ui:theme-control-start */
+  --control-sm: 32px;
+  --control-md: 40px;
+  --control-lg: 48px;
+  /* sh-ui:theme-control-end */
+  /* sh-ui:theme-border-width-start */
+  --border-width: 1px;
+  --border-width-strong: 2px;
+  /* sh-ui:theme-border-width-end */
+  /* sh-ui:theme-gradient-start */
+  --gradient-primary: linear-gradient(135deg, #171717 0%, #525252 100%);
+  --gradient-surface: linear-gradient(180deg, #FFFFFF 0%, #F5F5F5 100%);
+  --gradient-overlay: linear-gradient(180deg, #000000 0%, #1F1F1F 100%);
+  /* sh-ui:theme-gradient-end */
+  --opacity-disabled: 0.5;
+  --z-base: 0;
+  --z-sticky: 100;
+  --z-dropdown: 200;
+  --z-overlay: 300;
+  --z-modal: 400;
+  --z-popover: 500;
+  --z-toast: 600;
+  --z-tooltip: 700;
+  --bp-sm: 640px;
+  --bp-md: 768px;
+  --bp-lg: 1024px;
+  --bp-xl: 1280px;
+}

package/templates/nextjs-standalone/_arch/fsd/src/shared/test/createTestQueryClient.ts

@@ -0,0 +1,18 @@
+import { QueryClient } from '@tanstack/react-query';
+
+/**
+ * 테스트 전용 QueryClient — retry/refetch 끄고 gcTime 0 으로 격리.
+ */
+export const createTestQueryClient = (): QueryClient =>
+  new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+        refetchOnWindowFocus: false,
+        gcTime: 0,
+      },
+      mutations: {
+        retry: false,
+      },
+    },
+  });

package/templates/nextjs-standalone/_arch/fsd/src/shared/test/index.ts

@@ -0,0 +1,2 @@
+export { createTestQueryClient } from './createTestQueryClient';
+export { renderWithProviders } from './renderWithProviders';

package/templates/nextjs-standalone/_arch/fsd/src/shared/test/renderWithProviders.tsx

@@ -0,0 +1,40 @@
+import type { ReactElement, ReactNode } from 'react';
+
+import {
+  render,
+  type RenderOptions,
+  type RenderResult,
+} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+import { createTestQueryClient } from './createTestQueryClient';
+
+type Options = Omit<RenderOptions, 'wrapper'> & {
+  queryClient?: QueryClient;
+};
+
+type Result = RenderResult & {
+  user: ReturnType<typeof userEvent.setup>;
+  queryClient: QueryClient;
+};
+
+/**
+ * RTL render + QueryClientProvider + userEvent setup 한 번에.
+ * 추가 Provider 가 필요하면 이 파일을 직접 수정하거나 wrapper 옵션을 쓴다.
+ */
+export const renderWithProviders = (
+  ui: ReactElement,
+  options: Options = {},
+): Result => {
+  const { queryClient = createTestQueryClient(), ...rtlOptions } = options;
+
+  const Wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+
+  const result = render(ui, { wrapper: Wrapper, ...rtlOptions });
+  const user = userEvent.setup();
+
+  return { ...result, user, queryClient };
+};

package/templates/nextjs-standalone/_arch/fsd/src/shared/ui/FallbackBoundary/index.tsx

@@ -0,0 +1,89 @@
+'use client';
+
+import {
+  Component,
+  type ComponentType,
+  type ErrorInfo,
+  type ReactNode,
+  Suspense,
+} from 'react';
+import { QueryErrorResetBoundary } from '@tanstack/react-query';
+
+export type ErrorFallbackProps = {
+  error: Error | null;
+  resetErrorBoundary: () => void;
+};
+
+type ErrorBoundaryProps = {
+  children: ReactNode;
+  fallback?: ComponentType<ErrorFallbackProps>;
+  onReset: () => void;
+  onError?: (error: Error, info: ErrorInfo) => void;
+};
+
+type ErrorBoundaryState = {
+  hasError: boolean;
+  error: Error | null;
+};
+
+class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  state: ErrorBoundaryState = { hasError: false, error: null };
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    this.props.onError?.(error, info);
+  }
+
+  resetErrorBoundary = () => {
+    this.props.onReset();
+    this.setState({ hasError: false, error: null });
+  };
+
+  render() {
+    const { hasError, error } = this.state;
+    const { children, fallback: Fallback } = this.props;
+
+    if (hasError && Fallback) {
+      return (
+        <Fallback error={error} resetErrorBoundary={this.resetErrorBoundary} />
+      );
+    }
+
+    return children;
+  }
+}
+
+type FallbackBoundaryProps = {
+  children: ReactNode;
+  errorFallback?: ComponentType<ErrorFallbackProps>;
+  suspenseFallback?: ReactNode;
+  onError?: (error: Error, info: ErrorInfo) => void;
+};
+
+/**
+ * Suspense + ErrorBoundary 합성. React Query 의 reset 신호에 맞춰
+ * `errorFallback` 의 `resetErrorBoundary` 가 쿼리까지 함께 리셋한다.
+ */
+export function FallbackBoundary({
+  children,
+  errorFallback,
+  suspenseFallback,
+  onError,
+}: FallbackBoundaryProps) {
+  return (
+    <QueryErrorResetBoundary>
+      {({ reset }) => (
+        <ErrorBoundary
+          onReset={reset}
+          fallback={errorFallback}
+          onError={onError}
+        >
+          <Suspense fallback={suspenseFallback}>{children}</Suspense>
+        </ErrorBoundary>
+      )}
+    </QueryErrorResetBoundary>
+  );
+}