finish refactor pre merge

app/page.tsx

@@ -19,41 +19,35 @@ import {
     loadBackgroundLayerVisibilityFromStorage,
     persistBackgroundLayerVisibility,
 } from "@/lib/editor/background/backgroundVisibilityStorage";
+import { EMPTY_FEATURE_COLLECTION, WORLD_BBOX } from "@/lib/geo/constants";
+import { clampYearToFixedRange, TIMELINE_DEBOUNCE_MS } from "@/lib/timeline";
 
-const EMPTY_FC: FeatureCollection = { type: "FeatureCollection", features: [] };
-const WORLD_BBOX = {
-    minLng: -180,
-    minLat: -90,
-    maxLng: 180,
-    maxLat: 90,
-} as const;
 const CURRENT_YEAR = new Date().getUTCFullYear();
-const FALLBACK_TIMELINE_RANGE: TimelineRange = {
-    min: -2000,
-    max: 2000,
-};
-const TIMELINE_DEBOUNCE_MS = 180;
-
-type TimelineRange = {
-    min: number;
-    max: number;
-};
 
 export default function Page() {
-    const [initialData, setInitialData] = useState<FeatureCollection>(EMPTY_FC);
+    // Dữ liệu GeoJSON hiện đang hiển thị trên map (theo timelineYear).
+    const [initialData, setInitialData] = useState<FeatureCollection>(EMPTY_FEATURE_COLLECTION);
+    // ID geometry đang được chọn trên map (null nếu chưa chọn).
     const [selectedFeatureId, setSelectedFeatureId] = useState<string | number | null>(null);
+    // Năm timeline "đã chốt" để trigger fetch dữ liệu.
     const [timelineYear, setTimelineYear] = useState<number>(() =>
-        clampYearValue(CURRENT_YEAR, FALLBACK_TIMELINE_RANGE.min, FALLBACK_TIMELINE_RANGE.max)
+        clampYearToFixedRange(CURRENT_YEAR)
     );
+    // Năm timeline đang kéo/nhập (debounce rồi mới đẩy sang timelineYear).
     const [timelineDraftYear, setTimelineDraftYear] = useState<number>(() =>
-        clampYearValue(CURRENT_YEAR, FALLBACK_TIMELINE_RANGE.min, FALLBACK_TIMELINE_RANGE.max)
+        clampYearToFixedRange(CURRENT_YEAR)
     );
+    // Cờ loading khi fetch geometries theo timeline.
     const [isTimelineLoading, setIsTimelineLoading] = useState(false);
+    // Thông báo trạng thái/lỗi khi load timeline.
     const [timelineStatus, setTimelineStatus] = useState<string | null>(null);
+    // Trạng thái bật/tắt các layer nền.
     const [backgroundVisibility, setBackgroundVisibility] = useState<BackgroundLayerVisibility>(
         () => ({ ...HIDDEN_BACKGROUND_LAYER_VISIBILITY })
     );
+    // Đảm bảo đã load backgroundVisibility từ storage trước khi render map.
     const [isBackgroundVisibilityReady, setIsBackgroundVisibilityReady] = useState(false);
+    // Counter để bỏ qua response cũ khi user đổi timeline liên tục.
     const timelineFetchRequestRef = useRef(0);
 
     const selectedFeature =
@@ -154,7 +148,7 @@ export default function Page() {
     };
 
     const handleTimelineYearChange = (nextYear: number) => {
-        setTimelineDraftYear(clampYear(Math.trunc(nextYear), FALLBACK_TIMELINE_RANGE));
+        setTimelineDraftYear(clampYearToFixedRange(Math.trunc(nextYear)));
     };
 
     const selectedType = resolveSelectedTypeSummary(selectedFeature);
@@ -250,18 +244,6 @@ export default function Page() {
     );
 }
 
-function clampYear(year: number, range: TimelineRange): number {
-    return clampYearValue(year, range.min, range.max);
-}
-
-function clampYearValue(year: number, minYear: number, maxYear: number): number {
-    const lower = Math.min(minYear, maxYear);
-    const upper = Math.max(minYear, maxYear);
-    if (year < lower) return lower;
-    if (year > upper) return upper;
-    return year;
-}
-
 function isYearNumber(value: number | null | undefined): value is number {
     return typeof value === "number" && Number.isFinite(value);
 }