create-web-0to1 0.1.0

package/source/core/auth/auth-events.ts

@@ -0,0 +1,13 @@
+export const AUTH_UNAUTHORIZED_EVENT = 'app:auth-unauthorized';
+
+/**
+ * 클라이언트 전역에서 인증 만료를 감지했을 때
+ * 로그인 이동 같은 후속 처리를 트리거하는 공통 이벤트입니다.
+ */
+export function dispatchUnauthorizedEvent() {
+  if (typeof window === 'undefined') {
+    return;
+  }
+
+  window.dispatchEvent(new Event(AUTH_UNAUTHORIZED_EVENT));
+}

package/source/core/error/app-error.ts

@@ -0,0 +1,85 @@
+export const APP_ERROR_CODES = {
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  FORBIDDEN: 'FORBIDDEN',
+  NOT_FOUND: 'NOT_FOUND',
+  INVALID_RESPONSE: 'INVALID_RESPONSE',
+  REQUEST_ABORTED: 'REQUEST_ABORTED',
+  INVALID_CONFIGURATION: 'INVALID_CONFIGURATION',
+  UNKNOWN_ERROR: 'UNKNOWN_ERROR',
+} as const;
+
+export type AppErrorCode = (typeof APP_ERROR_CODES)[keyof typeof APP_ERROR_CODES];
+
+export type AppError = {
+  code: AppErrorCode;
+  message: string;
+  status?: number;
+};
+
+export const APP_ERROR_MESSAGES: Record<AppErrorCode, string> = {
+  [APP_ERROR_CODES.NETWORK_ERROR]: '네트워크 오류가 발생했습니다.',
+  [APP_ERROR_CODES.UNAUTHORIZED]: '로그인이 필요합니다.',
+  [APP_ERROR_CODES.FORBIDDEN]: '접근 권한이 없습니다.',
+  [APP_ERROR_CODES.NOT_FOUND]: '요청한 리소스를 찾을 수 없습니다.',
+  [APP_ERROR_CODES.INVALID_RESPONSE]: '응답 형식이 올바르지 않습니다.',
+  [APP_ERROR_CODES.REQUEST_ABORTED]: '요청이 취소되었습니다.',
+  [APP_ERROR_CODES.INVALID_CONFIGURATION]: 'core 설정이 초기화되지 않았습니다.',
+  [APP_ERROR_CODES.UNKNOWN_ERROR]: '알 수 없는 오류가 발생했습니다.',
+};
+
+export class ApiError extends Error implements AppError {
+  code: AppErrorCode;
+  status?: number;
+
+  constructor(
+    message: string,
+    status?: number,
+    code: AppErrorCode = APP_ERROR_CODES.UNKNOWN_ERROR,
+  ) {
+    super(message);
+    this.name = 'ApiError';
+    this.code = code;
+    this.status = status;
+  }
+}
+
+export function isAppError(value: unknown): value is AppError {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+
+  return 'code' in value && 'message' in value;
+}
+
+export function getAppErrorMessage(code: AppErrorCode) {
+  return APP_ERROR_MESSAGES[code];
+}
+
+/**
+ * fetch가 던지는 브라우저/런타임 오류를 템플릿 공통 AppError로 맞춥니다.
+ */
+export function normalizeAppError(error: unknown): AppError {
+  if (isAppError(error)) {
+    return error;
+  }
+
+  if (error instanceof DOMException && error.name === 'AbortError') {
+    return {
+      code: APP_ERROR_CODES.REQUEST_ABORTED,
+      message: getAppErrorMessage(APP_ERROR_CODES.REQUEST_ABORTED),
+    };
+  }
+
+  if (error instanceof TypeError) {
+    return {
+      code: APP_ERROR_CODES.NETWORK_ERROR,
+      message: getAppErrorMessage(APP_ERROR_CODES.NETWORK_ERROR),
+    };
+  }
+
+  return {
+    code: APP_ERROR_CODES.UNKNOWN_ERROR,
+    message: getAppErrorMessage(APP_ERROR_CODES.UNKNOWN_ERROR),
+  };
+}

package/source/core/error/handle-app-error.client.ts

@@ -0,0 +1,35 @@
+import { dispatchUnauthorizedEvent } from '../auth/auth-events';
+import { APP_ERROR_CODES, normalizeAppError } from './app-error';
+import { useModalStore } from '../ui/modal-store';
+
+/**
+ * AppProviders에서 QueryProviders의 onGlobalError로 연결할 때 사용할 수 있는
+ * 기본 클라이언트 에러 정책 예시입니다.
+ */
+export function handleClientAppError(error: unknown) {
+  const appError = normalizeAppError(error);
+
+  if (appError.code === APP_ERROR_CODES.REQUEST_ABORTED) {
+    return;
+  }
+
+  if (appError.code === APP_ERROR_CODES.UNAUTHORIZED) {
+    dispatchUnauthorizedEvent();
+    return;
+  }
+
+  if (appError.code === APP_ERROR_CODES.NETWORK_ERROR) {
+    useModalStore.getState().openModal({
+      title: '네트워크 오류',
+      description: '잠시 후 다시 시도해주세요.',
+    });
+    return;
+  }
+
+  if (appError.code === APP_ERROR_CODES.FORBIDDEN) {
+    useModalStore.getState().openModal({
+      title: '접근 권한 없음',
+      description: '이 작업을 수행할 권한이 없습니다.',
+    });
+  }
+}

package/source/core/lib/dayjs.ts

@@ -0,0 +1,25 @@
+import 'dayjs/locale/ko';
+
+import dayjsBase, { type ConfigType } from 'dayjs';
+import customParseFormat from 'dayjs/plugin/customParseFormat';
+import timezone from 'dayjs/plugin/timezone';
+import utc from 'dayjs/plugin/utc';
+
+dayjsBase.extend(utc);
+dayjsBase.extend(timezone);
+dayjsBase.extend(customParseFormat);
+dayjsBase.locale('ko');
+
+export const APP_TIME_ZONE = 'Asia/Seoul';
+
+dayjsBase.tz.setDefault(APP_TIME_ZONE);
+
+export const dayjs = dayjsBase;
+
+export function appDayjs(value?: ConfigType) {
+  if (value === undefined) {
+    return dayjs.tz();
+  }
+
+  return dayjs.tz(value);
+}

package/source/core/query/query-client.ts

@@ -0,0 +1,126 @@
+import {
+  type DefaultOptions,
+  MutationCache,
+  QueryCache,
+  QueryClient,
+} from '@tanstack/react-query';
+
+const baseDefaultOptions: DefaultOptions = {
+  queries: {
+    staleTime: 30_000,
+    retry: 1,
+  },
+};
+
+export type SharedQueryClientOptions = {
+  onGlobalError?: (error: unknown) => void;
+  defaultOptions?: DefaultOptions;
+};
+
+export type StandaloneQueryClientOptions = Pick<
+  SharedQueryClientOptions,
+  'onGlobalError'
+>;
+
+export type MakeQueryClientOptions = StandaloneQueryClientOptions;
+
+type SharedQueryClientRuntimeOptions = {
+  /**
+   * React / Next standalone 템플릿은 서버에서 매번 기본 QueryClient를 새로 만들고,
+   * 서버 호출 시 전달된 옵션은 무시하는 기존 동작을 유지합니다.
+   */
+  useServerOptions?: boolean;
+};
+
+/**
+ * 공통 QueryClient 기본 옵션과 타깃별 override를 한 번만 합칩니다.
+ */
+export function mergeQueryClientDefaultOptions(
+  baseOptions: DefaultOptions,
+  overrideOptions?: DefaultOptions,
+): DefaultOptions {
+  return {
+    ...baseOptions,
+    ...overrideOptions,
+    queries: {
+      ...baseOptions.queries,
+      ...overrideOptions?.queries,
+    },
+    mutations: {
+      ...baseOptions.mutations,
+      ...overrideOptions?.mutations,
+    },
+  };
+}
+
+export function makeSharedQueryClient({
+  onGlobalError,
+  defaultOptions,
+}: SharedQueryClientOptions = {}) {
+  return new QueryClient({
+    queryCache: new QueryCache({
+      onError: onGlobalError,
+    }),
+    mutationCache: new MutationCache({
+      onError: onGlobalError,
+    }),
+    defaultOptions: mergeQueryClientDefaultOptions(
+      baseDefaultOptions,
+      defaultOptions,
+    ),
+  });
+}
+
+let browserQueryClient: QueryClient | undefined;
+
+function isServerEnvironment() {
+  return typeof window === 'undefined';
+}
+
+/**
+ * runtime 분기는 core 한 곳에서만 처리합니다.
+ * 브라우저에서는 싱글톤을 재사용하고, 서버에서는 요청마다 새 client를 만듭니다.
+ */
+export function getSharedQueryClient(
+  options: SharedQueryClientOptions = {},
+  runtimeOptions: SharedQueryClientRuntimeOptions = {},
+) {
+  const { useServerOptions = true } = runtimeOptions;
+
+  if (isServerEnvironment()) {
+    return makeSharedQueryClient(useServerOptions ? options : {});
+  }
+
+  if (!browserQueryClient) {
+    browserQueryClient = makeSharedQueryClient(options);
+  }
+
+  return browserQueryClient;
+}
+
+export function createSharedQueryClient(options: SharedQueryClientOptions = {}) {
+  return makeSharedQueryClient(options);
+}
+
+export function makeStandaloneQueryClient({
+  onGlobalError,
+}: StandaloneQueryClientOptions = {}) {
+  return makeSharedQueryClient({
+    onGlobalError,
+  });
+}
+
+/**
+ * standalone 템플릿의 기존 계약을 유지합니다.
+ * 서버에서는 옵션 없는 새 client를 만들고, 브라우저에서는 singleton을 재사용합니다.
+ */
+export function getStandaloneQueryClient(
+  options: StandaloneQueryClientOptions = {},
+) {
+  return getSharedQueryClient(options, {
+    useServerOptions: false,
+  });
+}
+
+export const makeQueryClient = makeStandaloneQueryClient;
+export const getQueryClient = getStandaloneQueryClient;

package/source/core/request/request-core.ts

@@ -0,0 +1,210 @@
+import {
+  APP_ERROR_CODES,
+  type AppError,
+  getAppErrorMessage,
+  normalizeAppError,
+} from '../error/app-error';
+import { buildQueryString } from '../utils/build-query-string';
+
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+type Primitive = string | number | boolean | null | undefined;
+type ErrorResponse = {
+  code?: AppError['code'];
+  message?: string;
+};
+type NextFetchOptions = {
+  revalidate?: number | false;
+  tags?: string[];
+};
+type RequestCoreInit = RequestInit & {
+  next?: NextFetchOptions;
+};
+
+export type RequestParamValue = Primitive | Primitive[];
+
+export type RequestParams = Record<string, RequestParamValue>;
+
+export type JsonValue = Primitive | JsonObject | JsonValue[];
+
+export type JsonObject = {
+  [key: string]: JsonValue;
+};
+
+export type RequestData = JsonObject | FormData | null;
+
+export type RequestOptions = Omit<RequestCoreInit, 'body' | 'headers' | 'method'> & {
+  method: HttpMethod;
+  url: string;
+  params?: RequestParams;
+  data?: RequestData;
+  headers?: HeadersInit;
+  baseUrl?: string;
+};
+
+type RequestRuntimeOptions<TRequestOptions extends RequestOptions = RequestOptions> = {
+  resolveBaseUrl?: (
+    baseUrl: string | undefined,
+    options: TRequestOptions,
+  ) => string | undefined;
+  createHeaders?: (args: {
+    data: RequestData | undefined;
+    headers: HeadersInit | undefined;
+    options: TRequestOptions;
+    requestUrl: string;
+    resolvedBaseUrl: string | undefined;
+  }) => HeadersInit | undefined;
+  resolveCredentials?: (args: {
+    options: TRequestOptions;
+    requestUrl: string;
+    resolvedBaseUrl: string | undefined;
+  }) => RequestCredentials | undefined;
+};
+
+function isAbsoluteUrl(url: string) {
+  return url.startsWith('http://') || url.startsWith('https://');
+}
+
+export function isFormData(value: RequestData | undefined): value is FormData {
+  return typeof FormData !== 'undefined' && value instanceof FormData;
+}
+
+function getAppErrorCodeFromStatus(status: number): AppError['code'] {
+  switch (status) {
+    case 401:
+      return APP_ERROR_CODES.UNAUTHORIZED;
+    case 403:
+      return APP_ERROR_CODES.FORBIDDEN;
+    case 404:
+      return APP_ERROR_CODES.NOT_FOUND;
+    default:
+      return APP_ERROR_CODES.UNKNOWN_ERROR;
+  }
+}
+
+export function buildRequestUrl(
+  url: string,
+  params?: RequestParams,
+  baseUrl?: string,
+) {
+  const query = params ? buildQueryString(params) : '';
+
+  if (isAbsoluteUrl(url)) {
+    return `${url}${query}`;
+  }
+
+  if (!baseUrl) {
+    throw new Error('상대 경로 요청에는 API 기본 URL이 필요합니다.');
+  }
+
+  return `${baseUrl}${url}${query}`;
+}
+
+export function createRequestBody(
+  method: RequestOptions['method'],
+  data: RequestData | undefined,
+) {
+  if (method === 'GET' || method === 'DELETE' || data === undefined) {
+    return undefined;
+  }
+
+  if (isFormData(data)) {
+    return data;
+  }
+
+  return JSON.stringify(data);
+}
+
+/**
+ * JSON 요청은 기본 Content-Type만 보장하고,
+ * FormData는 브라우저가 boundary를 직접 붙이도록 그대로 둡니다.
+ */
+export function createRequestHeaders(
+  data: RequestData | undefined,
+  headers?: HeadersInit,
+) {
+  const nextHeaders = new Headers(headers);
+
+  if (!isFormData(data) && !nextHeaders.has('Content-Type')) {
+    nextHeaders.set('Content-Type', 'application/json');
+  }
+
+  return nextHeaders;
+}
+
+async function parseResponse<T>(response: Response): Promise<T | ErrorResponse | null> {
+  if (response.status === 204 || response.status === 205) {
+    return null;
+  }
+
+  try {
+    return (await response.json()) as T | ErrorResponse;
+  } catch {
+    throw {
+      code: APP_ERROR_CODES.INVALID_RESPONSE,
+      message: getAppErrorMessage(APP_ERROR_CODES.INVALID_RESPONSE),
+      status: response.status,
+    } satisfies AppError;
+  }
+}
+
+/**
+ * 요청 직렬화, 응답 파싱, 공통 오류 처리는 core에서 한 번만 담당합니다.
+ * wrapper는 baseUrl, 헤더, 인증 정책처럼 타깃별 차이만 주입합니다.
+ */
+export async function executeRequest<
+  T,
+  TRequestOptions extends RequestOptions = RequestOptions,
+>(
+  options: TRequestOptions,
+  runtimeOptions: RequestRuntimeOptions<TRequestOptions> = {},
+): Promise<T> {
+  const { method, url, params, data, headers, baseUrl, ...init } = options;
+  const resolvedBaseUrl = runtimeOptions.resolveBaseUrl?.(baseUrl, options) ?? baseUrl;
+  const requestUrl = buildRequestUrl(url, params, resolvedBaseUrl);
+  const resolvedCredentials =
+    init.credentials ??
+    runtimeOptions.resolveCredentials?.({
+      options,
+      requestUrl,
+      resolvedBaseUrl,
+    });
+  const resolvedHeaders =
+    runtimeOptions.createHeaders?.({
+      data,
+      headers,
+      options,
+      requestUrl,
+      resolvedBaseUrl,
+    }) ?? createRequestHeaders(data, headers);
+
+  const requestInit: RequestCoreInit = {
+    ...init,
+    method,
+    credentials: resolvedCredentials,
+    headers: resolvedHeaders,
+    body: createRequestBody(method, data),
+  };
+
+  let response: Response;
+
+  try {
+    response = await fetch(requestUrl, requestInit);
+  } catch (error) {
+    throw normalizeAppError(error);
+  }
+
+  const payload = await parseResponse<T>(response);
+
+  if (!response.ok) {
+    const code =
+      (payload as ErrorResponse | null)?.code ?? getAppErrorCodeFromStatus(response.status);
+
+    throw {
+      code,
+      message: (payload as ErrorResponse | null)?.message ?? getAppErrorMessage(code),
+      status: response.status,
+    } satisfies AppError;
+  }
+
+  return payload as T;
+}

package/source/core/routes/route-paths.ts

@@ -0,0 +1,4 @@
+export const routePaths = {
+  home: '/',
+  login: '/login',
+} as const;

package/source/core/ui/button.tsx

@@ -0,0 +1,24 @@
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
+
+export type ButtonProps = {
+  children: ReactNode;
+  isLoading?: boolean;
+} & ButtonHTMLAttributes<HTMLButtonElement>;
+
+export function Button({
+  children,
+  disabled,
+  isLoading = false,
+  className = '',
+  ...props
+}: ButtonProps) {
+  return (
+    <button
+      disabled={disabled || isLoading}
+      className={`inline-flex items-center justify-center rounded-xl bg-zinc-950 px-4 py-2 text-sm font-medium text-white transition hover:bg-zinc-800 disabled:cursor-not-allowed disabled:bg-zinc-400 ${className}`}
+      {...props}
+    >
+      {isLoading ? '저장 중...' : children}
+    </button>
+  );
+}

package/source/core/ui/modal-store.ts

@@ -0,0 +1,32 @@
+import { create } from 'zustand';
+
+type ModalPayload = {
+  title: string;
+  description?: string;
+};
+
+type ModalState = {
+  isOpen: boolean;
+  title: string;
+  description?: string;
+  openModal: (payload: ModalPayload) => void;
+  closeModal: () => void;
+};
+
+export const useModalStore = create<ModalState>((set) => ({
+  isOpen: false,
+  title: '',
+  description: '',
+  openModal: ({ title, description }) =>
+    set({
+      isOpen: true,
+      title,
+      description,
+    }),
+  closeModal: () =>
+    set({
+      isOpen: false,
+      title: '',
+      description: '',
+    }),
+}));

package/source/core/ui/text-input-field.tsx

@@ -0,0 +1,36 @@
+import type { InputHTMLAttributes } from 'react';
+
+export type TextInputFieldProps = {
+  label: string;
+  required?: boolean;
+  error?: string;
+  helperText?: string;
+} & InputHTMLAttributes<HTMLInputElement>;
+
+export function TextInputField({
+  label,
+  required,
+  error,
+  helperText,
+  id,
+  className = '',
+  ...props
+}: TextInputFieldProps) {
+  const inputId = id ?? props.name;
+
+  return (
+    <div className="flex flex-col gap-2">
+      <label htmlFor={inputId} className="text-sm font-semibold text-zinc-900">
+        {label}
+        {required ? <span className="ml-1 text-rose-600">*</span> : null}
+      </label>
+      <input
+        id={inputId}
+        className={`rounded-xl border px-4 py-3 text-sm text-zinc-950 outline-none ring-0 transition placeholder:text-zinc-400 focus:border-zinc-950 ${error ? 'border-rose-500' : 'border-zinc-300'} ${className}`}
+        {...props}
+      />
+      {error ? <p className="text-sm text-rose-600">{error}</p> : null}
+      {!error && helperText ? <p className="text-sm text-zinc-500">{helperText}</p> : null}
+    </div>
+  );
+}

package/source/core/utils/build-query-string.ts

@@ -0,0 +1,30 @@
+type Primitive = string | number | boolean | null | undefined;
+type QueryValue = Primitive | Primitive[];
+
+export function buildQueryString(params: Record<string, QueryValue>) {
+  const searchParams = new URLSearchParams();
+
+  Object.entries(params).forEach(([key, value]) => {
+    if (Array.isArray(value)) {
+      value.forEach((item) => {
+        if (item === null || item === undefined || item === '') {
+          return;
+        }
+
+        searchParams.append(key, String(item));
+      });
+
+      return;
+    }
+
+    if (value === null || value === undefined || value === '') {
+      return;
+    }
+
+    searchParams.set(key, String(value));
+  });
+
+  const queryString = searchParams.toString();
+
+  return queryString ? `?${queryString}` : '';
+}

package/source/core/utils/format/date.ts

@@ -0,0 +1,41 @@
+import type { ConfigType } from 'dayjs';
+
+import { appDayjs } from '../../lib/dayjs';
+
+export type DateValue = ConfigType | null | undefined;
+
+const EMPTY_FORMAT_VALUE = '-';
+
+function formatDateValue(value: DateValue, pattern: string, fallback = EMPTY_FORMAT_VALUE) {
+  if (value === null || value === undefined) {
+    return fallback;
+  }
+
+  const date = appDayjs(value);
+
+  if (!date.isValid()) {
+    return fallback;
+  }
+
+  return date.format(pattern);
+}
+
+export function formatDate(value: DateValue) {
+  return formatDateValue(value, 'YYYY-MM-DD');
+}
+
+export function formatDateTime(value: DateValue) {
+  return formatDateValue(value, 'YYYY-MM-DD HH:mm');
+}
+
+export function formatDateTimeSeconds(value: DateValue) {
+  return formatDateValue(value, 'YYYY-MM-DD HH:mm:ss');
+}
+
+export function formatMonthDay(value: DateValue) {
+  return formatDateValue(value, 'MM-DD');
+}
+
+export function toDateKey(value: DateValue = new Date()) {
+  return formatDateValue(value, 'YYYYMMDD', '');
+}

package/source/core/utils/format/index.ts

@@ -0,0 +1,3 @@
+export * from './date';
+export * from './number';
+export * from './text';

package/source/core/utils/format/number.ts

@@ -0,0 +1,13 @@
+const numberFormatter = new Intl.NumberFormat('ko-KR');
+const compactNumberFormatter = new Intl.NumberFormat('ko-KR', {
+  notation: 'compact',
+  maximumFractionDigits: 1,
+});
+
+export function formatNumber(value: number) {
+  return numberFormatter.format(value);
+}
+
+export function formatCompactNumber(value: number) {
+  return compactNumberFormatter.format(value);
+}