[FEAT] 통계 페이지 캘린더 구현

apps/timo-web/app/[locale]/(main)/statistics/_components/StatisticsCalendar.tsx

@@ -0,0 +1,120 @@
+import {
+  StatisticsClockEmptyIcon,
+  StatisticsClockFilledIcon,
+  StatisticsClockLightIcon,
+  StatisticsClockOutlineIcon,
+} from "@repo/timo-design-system/icons";
+import { cn } from "@repo/timo-design-system/utils";
+
+import type { StatisticsCalendarResponse } from "@/app/[locale]/(main)/statistics/_types/statistics";
+
+import {
+  formatStatisticsCalendarDate,
+  formatStatisticsMonth,
+} from "@/app/[locale]/(main)/statistics/_utils/format-statistics-date";
+import {
+  formatDateKey,
+  getCalendarDates,
+  getFirstDayOffset,
+} from "@/app/[locale]/(main)/statistics/_utils/statistics-calendar";
+
+type CalendarIconStatus = "disabled" | "empty" | "outline" | "light" | "filled";
+
+const DisabledClockIcon = () => (
+  <div className="bg-timo-gray-300 size-16.5 rounded-full" />
+);
+
+const STATUS_ICON = {
+  disabled: DisabledClockIcon,
+  empty: StatisticsClockEmptyIcon,
+  outline: StatisticsClockOutlineIcon,
+  light: StatisticsClockLightIcon,
+  filled: StatisticsClockFilledIcon,
+};
+
+const getIconStatus = (completionRate: number | null): CalendarIconStatus => {
+  if (completionRate === null) return "disabled";
+  if (completionRate === 0) return "empty";
+  if (completionRate < 50) return "outline";
+  if (completionRate < 100) return "light";
+  return "filled";
+};
+
+const WEEKDAYS = [
+  { label: "M", ariaLabel: "Monday" },
+  { label: "T", ariaLabel: "Tuesday" },
+  { label: "W", ariaLabel: "Wednesday" },
+  { label: "T", ariaLabel: "Thursday" },
+  { label: "F", ariaLabel: "Friday" },
+  { label: "S", ariaLabel: "Saturday" },
+  { label: "S", ariaLabel: "Sunday" },
+];
+
+interface StatisticsCalendarProps {
+  currentMonth: Date;
+  calendarData: StatisticsCalendarResponse;
+}
+
+export const StatisticsCalendar = ({
+  currentMonth,
+  calendarData,
+}: StatisticsCalendarProps) => {
+  const today = new Date(calendarData.today);
+  const calendarDates = getCalendarDates(currentMonth);
+  const firstDayOffset = getFirstDayOffset(currentMonth);
+  const completionRateByDate = new Map(
+    calendarData.days.map(({ date, completionRate }) => [date, completionRate]),
+  );
+  const todayLabel = formatStatisticsCalendarDate(today);
+
+  return (
+    <section className="w-full px-14.75 pt-10 pb-13">
+      <div className="w-199.5">
+        <div className="mb-17.25">
+          <h1 className="typo-headline-b-30 text-timo-gray-900">
+            {formatStatisticsMonth(currentMonth)}
+          </h1>
+
+          <p className="typo-headline-m-14 text-timo-black mt-2">
+            {todayLabel}
+          </p>
+        </div>
+
+        <div className="grid grid-cols-7 gap-x-14 gap-y-5">
+          {WEEKDAYS.map(({ label, ariaLabel }, index) => (
+            <div
+              key={ariaLabel}
+              aria-label={ariaLabel}
+              className={cn(
+                "typo-body-r-12 flex h-6 items-center justify-center",
+                index >= 5 ? "text-timo-red" : "text-timo-gray-900",
+              )}
+            >
+              {label}
+            </div>
+          ))}
+
+          {Array.from({ length: firstDayOffset }, (_, index) => (
+            <div key={`empty-${index}`} />
+          ))}
+
+          {calendarDates.map((calendarDate) => {
+            const dateKey = formatDateKey(calendarDate.date);
+            const completionRate = completionRateByDate.get(dateKey) ?? null;
+            const status = getIconStatus(completionRate);
+            const Icon = STATUS_ICON[status];
+
+            return (
+              <div key={dateKey} className="flex flex-col items-center gap-2.5">
+                <Icon />
+                <span className="typo-body-sb-11 text-timo-gray-700">
+                  {calendarDate.day}
+                </span>
+              </div>
+            );
+          })}
+        </div>
+      </div>
+    </section>
+  );
+};

apps/timo-web/app/[locale]/(main)/statistics/_containers/StatisticsContainer.tsx

@@ -0,0 +1,24 @@
+"use client";
+
+import { useState } from "react";
+
+import { StatisticsCalendar } from "@/app/[locale]/(main)/statistics/_components/StatisticsCalendar";
+import { StatisticsHeaderContainer } from "@/app/[locale]/(main)/statistics/_containers/StatisticsHeaderContainer";
+import { MOCK_STATISTICS_CALENDAR } from "@/app/[locale]/(main)/statistics/_mocks/statistics-calendar";
+
+export const StatisticsContainer = () => {
+  const [currentMonth, setCurrentMonth] = useState(() => new Date());
+
+  return (
+    <>
+      <StatisticsHeaderContainer
+        currentMonth={currentMonth}
+        onChangeMonth={setCurrentMonth}
+      />
+      <StatisticsCalendar
+        currentMonth={currentMonth}
+        calendarData={MOCK_STATISTICS_CALENDAR}
+      />
+    </>
+  );
+};

apps/timo-web/app/[locale]/(main)/statistics/_containers/StatisticsHeaderContainer.tsx

@@ -1,23 +1,30 @@
 "use client";
 
-import { useState } from "react";
+import type { Dispatch, SetStateAction } from "react";
 
 import { Header } from "@/components/layout/header/Header";
 import { useNavigationSidebar } from "@/components/layout/sidebar/navigation/NavigationSidebarContext";
 
+interface StatisticsHeaderContainerProps {
+  currentMonth: Date;
+  onChangeMonth: Dispatch<SetStateAction<Date>>;
+}
+
 const MONTH_LABEL_FORMATTER = new Intl.DateTimeFormat("en-US", {
   month: "long",
 });
 
 const addMonths = (date: Date, amount: number) =>
   new Date(date.getFullYear(), date.getMonth() + amount, 1);
 
-export const StatisticsHeaderContainer = () => {
-  const [currentMonth, setCurrentMonth] = useState(() => new Date());
+export const StatisticsHeaderContainer = ({
+  currentMonth,
+  onChangeMonth,
+}: StatisticsHeaderContainerProps) => {
   const { isOpen, toggle } = useNavigationSidebar();
 
-  const handlePrev = () => setCurrentMonth((prev) => addMonths(prev, -1));
-  const handleNext = () => setCurrentMonth((prev) => addMonths(prev, 1));
+  const handlePrev = () => onChangeMonth((prev) => addMonths(prev, -1));
+  const handleNext = () => onChangeMonth((prev) => addMonths(prev, 1));
 
   return (
     <Header

apps/timo-web/app/[locale]/(main)/statistics/_containers/StatisticsPageContainer.tsx

@@ -0,0 +1,24 @@
+"use client";
+
+import { useState } from "react";
+
+import { StatisticsCalendar } from "@/app/[locale]/(main)/statistics/_components/StatisticsCalendar";
+import { StatisticsHeaderContainer } from "@/app/[locale]/(main)/statistics/_containers/StatisticsHeaderContainer";
+import { MOCK_STATISTICS_CALENDAR } from "@/app/[locale]/(main)/statistics/_mocks/statistics-calendar";
+
+export const StatisticsContainer = () => {
+  const [currentMonth, setCurrentMonth] = useState(() => new Date());
+
+  return (
+    <>
+      <StatisticsHeaderContainer
+        currentMonth={currentMonth}
+        onChangeMonth={setCurrentMonth}
+      />
+      <StatisticsCalendar
+        currentMonth={currentMonth}
+        calendarData={MOCK_STATISTICS_CALENDAR}
+      />
+    </>
+  );
+};

apps/timo-web/app/[locale]/(main)/statistics/_mocks/statistics-calendar.ts

@@ -0,0 +1,13 @@
+import type { StatisticsCalendarResponse } from "@/app/[locale]/(main)/statistics/_types/statistics";
+
+export const MOCK_STATISTICS_CALENDAR: StatisticsCalendarResponse = {
+  yearMonth: "2026-07",
+  today: "2026-07-10",
+  days: [
+    { date: "2026-07-01", completionRate: 0 },
+    { date: "2026-07-02", completionRate: 25 },
+    { date: "2026-07-03", completionRate: 75 },
+    { date: "2026-07-04", completionRate: 100 },
+    { date: "2026-07-05", completionRate: null },
+  ],
+};

apps/timo-web/app/[locale]/(main)/statistics/_types/statistics.ts

@@ -22,10 +22,25 @@ export const statisticsDayDetailSchema = z.object({
   todos: z.array(statisticsTodoRecordSchema),
 });
 
+export const statisticsCalendarResponseSchema = z.object({
+  yearMonth: z.string(),
+  today: z.string(),
+  days: z.array(
+    z.object({
+      date: z.string(),
+      completionRate: z.number().nullable(),
+    }),
+  ),
+});
+
 export type StatisticsMonthSummary = z.infer<
   typeof statisticsMonthSummarySchema
 >;
 
 export type StatisticsDayDetail = z.infer<typeof statisticsDayDetailSchema>;
 
 export type StatisticsTodoRecord = z.infer<typeof statisticsTodoRecordSchema>;
+
+export type StatisticsCalendarResponse = z.infer<
+  typeof statisticsCalendarResponseSchema
+>;

apps/timo-web/app/[locale]/(main)/statistics/_utils/format-statistics-date.ts

@@ -0,0 +1,34 @@
+/**
+ * 통계 캘린더 헤더에 표시할 월 이름을 반환합니다.
+ *
+ * @param date - 월 이름을 가져올 날짜
+ * @param locale - 날짜 표기에 사용할 locale 값
+ * @returns locale에 맞게 변환된 월 이름
+ *
+ * @example
+ * formatStatisticsMonth(new Date(2026, 5, 1)); // "6월"
+ */
+export const formatStatisticsMonth = (date: Date, locale = "ko") => {
+  return new Intl.DateTimeFormat(locale, {
+    month: "long",
+  }).format(date);
+};
+
+/**
+ * 통계 캘린더 설명 영역에 표시할 날짜 문구를 반환합니다.
+ *
+ * @param date - 표시할 날짜
+ * @param locale - 날짜 표기에 사용할 locale 값
+ * @returns 년, 월, 일, 요일이 포함된 날짜 문구
+ *
+ * @example
+ * formatStatisticsCalendarDate(new Date(2026, 5, 28)); // "2026년 6월 28일 일요일"
+ */
+export const formatStatisticsCalendarDate = (date: Date, locale = "ko") => {
+  return new Intl.DateTimeFormat(locale, {
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+    weekday: "long",
+  }).format(date);
+};

apps/timo-web/app/[locale]/(main)/statistics/_utils/statistics-calendar.ts

@@ -0,0 +1,61 @@
+export interface CalendarDate {
+  date: Date;
+  day: number;
+}
+
+const getLastDayOfMonth = (date: Date) => {
+  return new Date(date.getFullYear(), date.getMonth() + 1, 0).getDate();
+};
+
+/**
+ * 주어진 월에 포함된 날짜 목록을 반환합니다.
+ * 이전/다음 달 날짜는 포함하지 않고 현재 월 날짜만 생성합니다.
+ *
+ * @param month - 날짜 목록을 생성할 기준 월
+ * @returns 해당 월의 날짜와 일자를 담은 배열
+ */
+export const getCalendarDates = (month: Date): CalendarDate[] => {
+  const year = month.getFullYear();
+  const monthIndex = month.getMonth();
+  const lastDay = getLastDayOfMonth(month);
+
+  return Array.from({ length: lastDay }, (_, index) => {
+    const day = index + 1;
+
+    return {
+      date: new Date(year, monthIndex, day),
+      day,
+    };
+  });
+};
+
+/**
+ * 월요일 시작 캘린더에서 1일 앞에 필요한 빈 칸 개수를 반환합니다.
+ * JS Date.getDay()는 일요일을 0으로 반환하므로 월요일 기준 인덱스로 변환합니다.
+ *
+ * @param month - 첫 주 offset을 계산할 기준 월
+ * @returns 월요일 시작 캘린더에서 1일 앞에 필요한 빈 칸 개수
+ */
+export const getFirstDayOffset = (month: Date) => {
+  const firstDate = new Date(month.getFullYear(), month.getMonth(), 1);
+
+  return (firstDate.getDay() + 6) % 7;
+};
+
+/**
+ * Date 객체를 API 응답 날짜 형식인 yyyy-MM-dd 문자열로 변환합니다.
+ * 날짜별 completionRate를 매칭할 때 사용합니다.
+ *
+ * @param date - 변환할 날짜
+ * @returns yyyy-MM-dd 형식의 날짜 문자열
+ *
+ * @example
+ * formatDateKey(new Date(2026, 5, 28)); // "2026-06-28"
+ */
+export const formatDateKey = (date: Date) => {
+  const year = date.getFullYear();
+  const month = `${date.getMonth() + 1}`.padStart(2, "0");
+  const day = `${date.getDate()}`.padStart(2, "0");
+
+  return `${year}-${month}-${day}`;
+};

apps/timo-web/app/[locale]/(main)/statistics/page.tsx

@@ -1,5 +1,5 @@
-import { StatisticsHeaderContainer } from "@/app/[locale]/(main)/statistics/_containers/StatisticsHeaderContainer";
+import { StatisticsContainer } from "@/app/[locale]/(main)/statistics/_containers/StatisticsContainer";
 
 export default function StatisticsPage() {
-  return <StatisticsHeaderContainer />;
+  return <StatisticsContainer />;
 }