finish refactor pre merge

lib/editor/session/useBackgroundSessionState.ts

@@ -5,9 +5,11 @@ import {
 } from "@/lib/backgroundLayers";
 
 export function useBackgroundSessionState() {
+    // Trạng thái bật/tắt layer nền (khởi tạo default hidden; sẽ load từ storage ở page).
     const [backgroundVisibility, setBackgroundVisibility] = useState<BackgroundLayerVisibility>(
         () => ({ ...HIDDEN_BACKGROUND_LAYER_VISIBILITY })
     );
+    // Đảm bảo đã load visibility trước khi render map thật.
     const [isBackgroundVisibilityReady, setIsBackgroundVisibilityReady] = useState(false);
 
     return {
@@ -17,4 +19,3 @@ export function useBackgroundSessionState() {
         setIsBackgroundVisibilityReady,
     };
 }
-

lib/editor/session/useEntitySessionState.ts

@@ -10,27 +10,41 @@ import type {
 } from "@/lib/editor/session/sessionTypes";
 
 export function useEntitySessionState() {
+    // Entities đã persisted từ backend (dùng cho search/binding).
     const [persistedEntities, setPersistedEntities] = useState<Entity[]>([]);
+    // Entities tạo mới trong phiên nhưng chưa commit lên backend.
     const [pendingEntityCreates, setPendingEntityCreates] = useState<PendingEntityCreate[]>([]);
+    // Tóm tắt entities đã tạo (để hiển thị nhanh ở sidebar).
     const [createdEntities, setCreatedEntities] = useState<CreatedEntitySummary[]>([]);
+    // Thông báo trạng thái/lỗi liên quan entity/session.
     const [entityStatus, setEntityStatus] = useState<string | null>(null);
+    // Feature đang được chọn để thao tác bind entities/metadata.
     const [selectedFeatureId, setSelectedFeatureId] = useState<FeatureId | null>(null);
+    // Form tạo entity mới (độc lập).
     const [entityForm, setEntityForm] = useState<EntityFormState>({
         name: "",
         slug: "",
         type_id: DEFAULT_ENTITY_TYPE_ID,
     });
+    // Danh sách entity IDs đang chọn để bind vào geometry hiện tại.
     const [selectedGeometryEntityIds, setSelectedGeometryEntityIds] = useState<string[]>([]);
+    // Form metadata geometry (time range + binding ids).
     const [geometryMetaForm, setGeometryMetaForm] = useState<GeometryMetaFormState>({
         time_start: "",
         time_end: "",
         binding: "",
     });
+    // Cờ loading khi apply entity/metadata (local submit).
     const [isEntitySubmitting, setIsEntitySubmitting] = useState(false);
+    // Thông báo trạng thái/lỗi cho form entity/metadata.
     const [entityFormStatus, setEntityFormStatus] = useState<string | null>(null);
+    // Keyword search entity theo name.
     const [entitySearchQuery, setEntitySearchQuery] = useState("");
+    // Kết quả search entity để user chọn.
     const [entitySearchResults, setEntitySearchResults] = useState<Entity[]>([]);
+    // Entity ID đang được chọn trong dropdown kết quả search.
     const [selectedSearchEntityId, setSelectedSearchEntityId] = useState<string | null>(null);
+    // Cờ loading khi search entity.
     const [isEntitySearchLoading, setIsEntitySearchLoading] = useState(false);
 
     return {

lib/editor/session/useSectionSessionState.ts

@@ -9,6 +9,7 @@ type Options = {
 type SectionTask = "idle" | "saving" | "submitting" | "opening-section";
 
 export function useSectionSessionState(options: Options) {
+    // Single state machine cho các tác vụ async của section (saving/submitting/opening).
     const [sectionTask, setSectionTask] = useState<SectionTask>("idle");
     const setTaskFlag = useCallback((task: Exclude<SectionTask, "idle">, next: SetStateAction<boolean>) => {
         setSectionTask((prev) => {
@@ -32,15 +33,25 @@ export function useSectionSessionState(options: Options) {
         setTaskFlag("opening-section", next);
     }, [setTaskFlag]);
 
+    // Danh sách sections để user chọn mở.
     const [availableSections, setAvailableSections] = useState<Section[]>([]);
+    // Section ID đang được chọn trong dropdown.
     const [selectedSectionId, setSelectedSectionId] = useState("");
+    // Title section mới (để create).
     const [newSectionTitle, setNewSectionTitle] = useState("");
+    // Input title cho commit.
     const [commitTitle, setCommitTitle] = useState("");
+    // Input note cho commit.
     const [commitNote, setCommitNote] = useState("");
+    // User ID dùng để gắn vào commit/submit/lock.
     const [editorUserIdInput, setEditorUserIdInput] = useState(options.defaultEditorUserId);
+    // Section đang mở để edit (null nếu chưa mở).
     const [activeSection, setActiveSection] = useState<Section | null>(null);
+    // Trạng thái section (version/head/status/lock).
     const [sectionState, setSectionState] = useState<SectionState | null>(null);
+    // Danh sách commits của section đang mở.
     const [sectionCommits, setSectionCommits] = useState<SectionCommit[]>([]);
+    // Snapshot gần nhất đã load (để build snapshot diff/metadata).
     const [lastSectionSnapshot, setLastSectionSnapshot] = useState<EditorSnapshot | null>(null);
 
     return {

lib/editor/session/useTimelineState.ts

@@ -1,5 +1,6 @@
 import { useState } from "react";
 import type { TimelineRange } from "@/lib/editor/session/sessionTypes";
+import { clampYearValue } from "@/lib/timeline";
 
 type Options = {
     currentYear: number;
@@ -7,6 +8,7 @@ type Options = {
 };
 
 export function useTimelineState(options: Options) {
+    // Năm timeline "đã chốt" để fetch dữ liệu.
     const [timelineYear, setTimelineYear] = useState<number>(() =>
         clampYearValue(
             options.currentYear,
@@ -14,6 +16,7 @@ export function useTimelineState(options: Options) {
             options.fallbackTimelineRange.max
         )
     );
+    // Năm timeline đang chỉnh (debounce rồi đẩy sang timelineYear).
     const [timelineDraftYear, setTimelineDraftYear] = useState<number>(() =>
         clampYearValue(
             options.currentYear,
@@ -21,7 +24,9 @@ export function useTimelineState(options: Options) {
             options.fallbackTimelineRange.max
         )
     );
+    // Cờ loading khi fetch theo timeline.
     const [isTimelineLoading, setIsTimelineLoading] = useState(false);
+    // Thông báo trạng thái/lỗi khi fetch theo timeline.
     const [timelineStatus, setTimelineStatus] = useState<string | null>(null);
 
     return {
@@ -35,11 +40,3 @@ export function useTimelineState(options: Options) {
         setTimelineStatus,
     };
 }
-
-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;
-}