@lichta/core 2.1.0 → 2.2.1

package/dist/index.d.mts

@@ -15,22 +15,14 @@ interface SolarDate {
     month: number;
     year: number;
 }
+/** Một lần xuất hiện Tiết Khí (Solar Term) trong năm dương lịch */
+interface SolarTerm {
+    index: number;
+    name: string;
+    date: SolarDate;
+    jd: number;
+}
 
-/**
- * Chuyển ngày Gregorian sang Julian Day Number.
- *
- * @param dd - Ngày (1-31)
- * @param mm - Tháng (1-12)
- * @param yy - Năm
- */
-declare function jdFromDate(dd: number, mm: number, yy: number): number;
-/**
- * Chuyển Julian Day Number sang ngày Gregorian.
- *
- * @param jd - Julian Day Number
- * @returns Tuple [day, month, year]
- */
-declare function jdToDate(jd: number): [number, number, number];
 declare class LichTa {
     /**
      * Chuyển đổi ngày Dương lịch sang Âm lịch.
@@ -72,6 +64,62 @@ declare class LichTa {
     static toSolar(lunarDay: number, lunarMonth: number, lunarYear: number, isLeap?: boolean, timeZone?: number): SolarDate;
 }
 
+/**
+ * Thuật toán thiên văn nền tảng cho chuyển đổi Dương lịch ↔ Âm lịch Việt Nam
+ * Dựa trên công trình của Hồ Ngọc Đức (Đại học Leipzig)
+ * Tham khảo: Jean Meeus, "Astronomical Algorithms" (1998)
+ *
+ * Copyright (c) 2006 Ho Ngoc Duc. All Rights Reserved.
+ * TypeScript adaptation for Lichta library.
+ */
+/**
+ * Chuyển ngày Gregorian sang Julian Day Number.
+ *
+ * @param dd - Ngày (1-31)
+ * @param mm - Tháng (1-12)
+ * @param yy - Năm
+ */
+declare function jdFromDate(dd: number, mm: number, yy: number): number;
+/**
+ * Chuyển Julian Day Number sang ngày Gregorian.
+ *
+ * @param jd - Julian Day Number
+ * @returns Tuple [day, month, year]
+ */
+declare function jdToDate(jd: number): [number, number, number];
+
+/** Một ô ngày trong lưới lịch tháng. */
+interface CalendarDayCell {
+    solar: Date;
+    lunar: LunarDate;
+    isToday: boolean;
+    isSelected: boolean;
+    isCurrentMonth: boolean;
+    /** Số tuần trong năm (ISO-8601) của hàng chứa ô này — giống nhau cho cả 7 ô trong hàng. */
+    weekNumber: number;
+}
+/** Ngày bắt đầu tuần: 0 = Chủ Nhật (mặc định, giống `Date.getDay()`), 1 = Thứ Hai. */
+type FirstDayOfWeek = 0 | 1;
+/**
+ * Tính số tuần theo chuẩn ISO-8601: tuần bắt đầu Thứ Hai, tuần 1 của năm là
+ * tuần chứa Thứ Năm đầu tiên (tương đương: tuần chứa ngày 4/1).
+ */
+declare function getISOWeekNumber(date: Date): number;
+/**
+ * Dựng lưới 42 ô (6 tuần x 7 ngày) cho 1 tháng dương lịch, gồm ngày tràn từ
+ * tháng trước/sau để lấp đầy tuần đầu/cuối, mỗi ô kèm ngày âm tương ứng.
+ *
+ * Logic này trước đây bị lặp lại độc lập ở Calendar.tsx/vue/svelte — tách ra
+ * đây để có 1 nguồn tính toán duy nhất (tránh 3 bản có thể lệch nhau khi sửa
+ * riêng lẻ), dùng chung cho cả Calendar và DatePicker ở mọi framework.
+ *
+ * @param month - Tháng dương lịch (1-12)
+ * @param year - Năm dương lịch
+ * @param selectedDate - Ngày đang được chọn (nếu có), dùng để đánh dấu `isSelected`
+ * @param firstDayOfWeek - Ngày bắt đầu tuần: 0 = Chủ Nhật (mặc định), 1 = Thứ Hai
+ */
+declare function getCalendarGrid(month: number, year: number, selectedDate?: Date | null, firstDayOfWeek?: FirstDayOfWeek): CalendarDayCell[];
+
 /**
  * Internationalization — Hỗ trợ song ngữ Việt-Anh
  */
@@ -93,6 +141,10 @@ declare function t(locale: Locale): {
     readonly yearLabel: "Năm";
     readonly monthLabel: "Tháng";
     readonly destiny: "Mệnh";
+    readonly solarTermNames: readonly ["Xuân Phân", "Thanh Minh", "Cốc Vũ", "Lập Hạ", "Tiểu Mãn", "Mang Chủng", "Hạ Chí", "Tiểu Thử", "Đại Thử", "Lập Thu", "Xử Thử", "Bạch Lộ", "Thu Phân", "Hàn Lộ", "Sương Giáng", "Lập Đông", "Tiểu Tuyết", "Đại Tuyết", "Đông Chí", "Tiểu Hàn", "Đại Hàn", "Lập Xuân", "Vũ Thủy", "Kinh Trập"];
+    readonly trucNames: readonly ["Kiến", "Trừ", "Mãn", "Bình", "Định", "Chấp", "Phá", "Nguy", "Thành", "Thu", "Khai", "Bế"];
+    readonly elementRelationNames: readonly ["Tương sinh", "Được sinh", "Tương khắc", "Bị khắc", "Tương hòa"];
+    readonly trucQualityNames: readonly ["Xấu", "Trung bình", "Tốt"];
 } | {
     readonly heavenlyStems: readonly ["Giáp", "Ất", "Bính", "Đinh", "Mậu", "Kỷ", "Canh", "Tân", "Nhâm", "Quý"];
     readonly earthlyBranches: readonly ["Tý", "Sửu", "Dần", "Mão", "Thìn", "Tỵ", "Ngọ", "Mùi", "Thân", "Dậu", "Tuất", "Hợi"];
@@ -106,6 +158,10 @@ declare function t(locale: Locale): {
     readonly yearLabel: "Year";
     readonly monthLabel: "Month";
     readonly destiny: "Destiny";
+    readonly solarTermNames: readonly ["Spring Equinox", "Clear and Bright", "Grain Rain", "Start of Summer", "Grain Full", "Grain in Ear", "Summer Solstice", "Minor Heat", "Major Heat", "Start of Autumn", "End of Heat", "White Dew", "Autumn Equinox", "Cold Dew", "Frost's Descent", "Start of Winter", "Minor Snow", "Major Snow", "Winter Solstice", "Minor Cold", "Major Cold", "Start of Spring", "Rain Water", "Awakening of Insects"];
+    readonly trucNames: readonly ["Kiến", "Trừ", "Mãn", "Bình", "Định", "Chấp", "Phá", "Nguy", "Thành", "Thu", "Khai", "Bế"];
+    readonly elementRelationNames: readonly ["Generates", "Generated By", "Overcomes", "Overcome By", "Same Element"];
+    readonly trucQualityNames: readonly ["Bad", "Neutral", "Good"];
 } | {
     readonly heavenlyStems: readonly ["甲", "乙", "丙", "丁", "戊", "己", "庚", "辛", "壬", "癸"];
     readonly earthlyBranches: readonly ["子", "丑", "寅", "卯", "辰", "巳", "午", "未", "申", "酉", "戌", "亥"];
@@ -119,6 +175,10 @@ declare function t(locale: Locale): {
     readonly yearLabel: "年";
     readonly monthLabel: "月";
     readonly destiny: "命";
+    readonly solarTermNames: readonly ["春分", "清明", "穀雨", "立夏", "小満", "芒種", "夏至", "小暑", "大暑", "立秋", "処暑", "白露", "秋分", "寒露", "霜降", "立冬", "小雪", "大雪", "冬至", "小寒", "大寒", "立春", "雨水", "啓蟄"];
+    readonly trucNames: readonly ["建", "除", "満", "平", "定", "執", "破", "危", "成", "収", "開", "閉"];
+    readonly elementRelationNames: readonly ["相生", "被生", "相克", "被克", "比和"];
+    readonly trucQualityNames: readonly ["凶", "普通", "吉"];
 } | {
     readonly heavenlyStems: readonly ["갑", "을", "병", "정", "무", "기", "경", "신", "임", "계"];
     readonly earthlyBranches: readonly ["자", "축", "인", "묘", "진", "사", "오", "미", "신", "유", "술", "해"];
@@ -132,6 +192,10 @@ declare function t(locale: Locale): {
     readonly yearLabel: "년";
     readonly monthLabel: "월";
     readonly destiny: "명";
+    readonly solarTermNames: readonly ["춘분", "청명", "곡우", "입하", "소만", "망종", "하지", "소서", "대서", "입추", "처서", "백로", "추분", "한로", "상강", "입동", "소설", "대설", "동지", "소한", "대한", "입춘", "우수", "경칩"];
+    readonly trucNames: readonly ["건", "제", "만", "평", "정", "집", "파", "위", "성", "수", "개", "폐"];
+    readonly elementRelationNames: readonly ["상생", "피생", "상극", "피극", "비화"];
+    readonly trucQualityNames: readonly ["흉", "보통", "길"];
 };
 /**
  * Lấy tên con giáp theo locale
@@ -139,32 +203,13 @@ declare function t(locale: Locale): {
  * @param locale - Ngôn ngữ
  */
 declare function getZodiacAnimal(branchIndex: number, locale?: Locale): string;
-
-/** Kết quả trả về của {@link getYearDetails}. */
-interface YearDetails {
-    can: string;
-    chi: string;
-    menh: string;
-    fullString: string;
-}
 /**
- * Lấy ra chuỗi mô tả toàn bộ Can, Chi và Mệnh dựa vào số năm (Ví dụ: 2024)
- * Theo quy ước: Năm 4 (sau CN) là năm Giáp Tý (Can index 0, Chi index 0)
- *
- * Công thức Can Chi là chu kỳ 60 năm lặp lại vô hạn nên nhận mọi số năm nguyên,
- * kể cả năm 0 hoặc âm (trước Công Nguyên) — không giới hạn phạm vi như
- * {@link LichTa.toLunar} (phạm vi đó là do thuật toán tìm Điểm Sóc, không áp
- * dụng cho công thức Can Chi thuần).
- *
- * @param year - Năm (số nguyên bất kỳ, kể cả 0 hoặc âm)
- *
- * @example
- * ```typescript
- * getYearDetails(2024);
- * // → { can: 'Giáp', chi: 'Thìn', menh: 'Thủy', fullString: 'Giáp Thìn - Mệnh Thủy' }
- * ```
+ * Lấy nhãn thứ trong tuần theo locale, xoay vòng theo ngày bắt đầu tuần.
+ * @param locale - Ngôn ngữ
+ * @param firstDayOfWeek - Ngày bắt đầu tuần: 0 = Chủ Nhật (mặc định), 1 = Thứ Hai
  */
-declare function getYearDetails(year: number): YearDetails;
+declare function getWeekDayLabels(locale: Locale, firstDayOfWeek?: FirstDayOfWeek): string[];
+
 /**
  * Tính Can Chi ngày từ Julian Day Number.
  *
@@ -205,6 +250,247 @@ declare function getMonthCanChi(lunarMonth: number, lunarYear: number, locale?:
  * @param locale - Ngôn ngữ hiển thị (mặc định: 'vi', giữ nguyên hành vi cũ)
  */
 declare function getHourCanChi(hour: number, dayJd: number, locale?: Locale): string;
+
+/**
+ * Lấy tên Ngũ Hành theo index và locale.
+ *
+ * @param index - Index Ngũ Hành (0-4, vào FIVE_ELEMENTS: Kim, Mộc, Thủy, Hỏa, Thổ)
+ * @param locale - Ngôn ngữ hiển thị (mặc định: 'vi')
+ */
+declare function getElementName(index: number, locale?: Locale): string;
+/**
+ * Tính index Ngũ Hành Nạp Âm (0-4, vào FIVE_ELEMENTS) của ngày, dùng chung bảng
+ * Nạp Âm 60 Hoa Giáp với `getYearDetails` (almanac.ts). Chỉ số Can/Chi tính giống hệt
+ * {@link import('./can-chi.js').getDayCanChi}.
+ *
+ * @param jd - Julian Day Number
+ */
+declare function getDayElementIndex(jd: number): number;
+/**
+ * Tính Mệnh (Ngũ Hành Nạp Âm) của ngày theo locale (xem {@link getDayElementIndex}).
+ *
+ * @param jd - Julian Day Number
+ * @param locale - Ngôn ngữ hiển thị (mặc định: 'vi')
+ */
+declare function getDayElement(jd: number, locale?: Locale): string;
+/**
+ * Tính index Ngũ Hành Nạp Âm (0-4, vào FIVE_ELEMENTS) của tháng âm lịch. Chỉ số
+ * Can/Chi tính giống hệt {@link import('./can-chi.js').getMonthCanChi}.
+ *
+ * @param lunarMonth - Tháng âm lịch (1-12)
+ * @param lunarYear - Năm âm lịch
+ */
+declare function getMonthElementIndex(lunarMonth: number, lunarYear: number): number;
+/**
+ * Tính Mệnh (Ngũ Hành Nạp Âm) của tháng âm lịch theo locale (xem {@link getMonthElementIndex}).
+ *
+ * @param lunarMonth - Tháng âm lịch (1-12)
+ * @param lunarYear - Năm âm lịch
+ * @param locale - Ngôn ngữ hiển thị (mặc định: 'vi')
+ */
+declare function getMonthElement(lunarMonth: number, lunarYear: number, locale?: Locale): string;
+/**
+ * Tính index Ngũ Hành Nạp Âm (0-4, vào FIVE_ELEMENTS) của giờ. Chỉ số Can/Chi tính
+ * giống hệt {@link import('./can-chi.js').getHourCanChi}.
+ *
+ * @param hour - Giờ (0-23)
+ * @param dayJd - Julian Day Number của ngày
+ */
+declare function getHourElementIndex(hour: number, dayJd: number): number;
+/**
+ * Tính Mệnh (Ngũ Hành Nạp Âm) của giờ theo locale (xem {@link getHourElementIndex}).
+ *
+ * @param hour - Giờ (0-23)
+ * @param dayJd - Julian Day Number của ngày
+ * @param locale - Ngôn ngữ hiển thị (mặc định: 'vi')
+ */
+declare function getHourElement(hour: number, dayJd: number, locale?: Locale): string;
+/**
+ * Tính quan hệ Ngũ Hành từ `fromIndex` tới `toIndex`, trả về index 0-4:
+ *   0 = sinh (from sinh to)      2 = khắc (from khắc to)      4 = hòa (cùng hành)
+ *   1 = được sinh (to sinh from) 3 = bị khắc (to khắc from)
+ *
+ * Với 5 hành, 2 hành khác nhau bất kỳ luôn rơi vào đúng 1 trong 4 quan hệ trên
+ * (mỗi hành có đúng 1 hành sinh nó, 1 hành nó sinh, 1 hành khắc nó, 1 hành nó khắc)
+ * — không có trường hợp mơ hồ.
+ *
+ * @param fromIndex - Index Ngũ Hành thứ nhất (0-4, vào FIVE_ELEMENTS)
+ * @param toIndex - Index Ngũ Hành thứ hai (0-4, vào FIVE_ELEMENTS)
+ */
+declare function getElementRelationIndex(fromIndex: number, toIndex: number): number;
+/**
+ * Lấy tên quan hệ Ngũ Hành giữa 2 hành theo locale (xem {@link getElementRelationIndex}).
+ *
+ * @param fromIndex - Index Ngũ Hành thứ nhất (0-4, vào FIVE_ELEMENTS)
+ * @param toIndex - Index Ngũ Hành thứ hai (0-4, vào FIVE_ELEMENTS)
+ * @param locale - Ngôn ngữ hiển thị (mặc định: 'vi')
+ *
+ * @example
+ * ```typescript
+ * // Mộc (1) và Hỏa (3): Mộc sinh Hỏa
+ * getElementRelation(1, 3); // → 'Tương sinh'
+ * getElementRelation(3, 1); // → 'Được sinh' (từ góc nhìn của Hỏa: được Mộc sinh)
+ * ```
+ */
+declare function getElementRelation(fromIndex: number, toIndex: number, locale?: Locale): string;
+
+/**
+ * Tính index Trực (0-11: Kiến, Trừ, Mãn, Bình, Định, Chấp, Phá, Nguy, Thành, Thu, Khai, Bế)
+ * tại một ngày dương lịch (Julian Day Number).
+ *
+ * Theo đúng phép Kiến Trừ thập nhị khách truyền thống, mỗi Tiết trong 12 Tiết (Lập
+ * Xuân, Kinh Trập, Thanh Minh, ... — tức các index lẻ trong 24 Tiết Khí, xem
+ * {@link import('./tiet-khi.js').getSolarTermsInYear}) ứng với một Chi "Kiến" CỐ ĐỊNH
+ * (Lập Xuân → Kiến Dần, Kinh Trập → Kiến Mão, Thanh Minh → Kiến Thìn, ..., Tiểu Hàn →
+ * Kiến Sửu). Trực của một ngày = độ lệch giữa Chi của chính ngày đó và Chi Kiến của
+ * Tiết đang hiệu lực — KHÔNG phải số ngày đã trôi qua kể từ khi Tiết bắt đầu.
+ *
+ * Hai cách tính chỉ trùng nhau khi ngày bắt đầu Tiết tình cờ có đúng Chi Kiến của Tiết
+ * đó (không phải lúc nào cũng vậy — ví dụ Tiểu Thử 2026 rơi vào ngày Nhâm Ngọ chứ không
+ * phải ngày Mùi). Vì vậy KHÔNG được gán "Kiến" (index 0) cho chính ngày bắt đầu Tiết
+ * một cách mặc định.
+ *
+ * Cũng dùng Tiết (không dùng số tháng âm lịch) để neo, vì tháng nhuận âm lịch không
+ * tương ứng với một Tiết mới (dùng số tháng âm lịch sẽ cho kết quả sai trong các
+ * tháng nhuận).
+ *
+ * Dùng `getSolarTermOccurrencesInYear` (dữ liệu thô, có cache theo năm+timeZone)
+ * thay vì `getSolarTermsInYear` công khai — tránh tính tên/locale không cần dùng
+ * tới, và tránh quét lại kinh độ Mặt Trời mỗi lần gọi khi hàm này được gọi lặp lại
+ * cho nhiều ngày cùng năm (vd. dựng lịch Trực cho cả tháng/năm).
+ *
+ * @param jd - Julian Day Number của ngày cần tra
+ * @param timeZone - Múi giờ (mặc định: 7 cho GMT+7 Việt Nam)
+ */
+declare function getTrucIndex(jd: number, timeZone?: number): number;
+/**
+ * Lấy tên Trực theo index và locale.
+ *
+ * @param index - Index Trực (0-11, xem {@link getTrucIndex})
+ * @param locale - Ngôn ngữ hiển thị (mặc định: 'vi')
+ */
+declare function getTrucName(index: number, locale?: Locale): string;
+/**
+ * Lấy tên Trực tại một ngày dương lịch (Julian Day Number).
+ *
+ * @param jd - Julian Day Number của ngày cần tra
+ * @param timeZone - Múi giờ (mặc định: 7 cho GMT+7 Việt Nam)
+ * @param locale - Ngôn ngữ hiển thị (mặc định: 'vi')
+ */
+declare function getTruc(jd: number, timeZone?: number, locale?: Locale): string;
+/**
+ * Lấy index mức tốt/xấu (0-2) của một Trực — xem giải thích độ tin cậy ở
+ * {@link TRUC_QUALITY_INDEX}.
+ *
+ * @param trucIndex - Index Trực (0-11, xem {@link getTrucIndex})
+ */
+declare function getTrucQualityIndex(trucIndex: number): number;
+/**
+ * Lấy tên mức tốt/xấu của một Trực theo locale (xem {@link getTrucQualityIndex}).
+ *
+ * @param trucIndex - Index Trực (0-11, xem {@link getTrucIndex})
+ * @param locale - Ngôn ngữ hiển thị (mặc định: 'vi')
+ */
+declare function getTrucQuality(trucIndex: number, locale?: Locale): string;
+/**
+ * Lấy Chi đối xung (Lục Xung) với một Chi cho trước — 2 Chi cách nhau đúng 6 vị
+ * trí trong vòng tròn 12 Chi: Tý-Ngọ, Sửu-Mùi, Dần-Thân, Mão-Dậu, Thìn-Tuất, Tỵ-Hợi.
+ *
+ * @param branchIndex - Index Địa Chi (0-11, vào EARTHLY_BRANCHES)
+ * @returns Index Địa Chi đối xung
+ */
+declare function getXungBranchIndex(branchIndex: number): number;
+/**
+ * Kiểm tra 2 Chi (tuổi) có phạm Lục Xung với nhau không.
+ *
+ * @param branchIndexA - Index Địa Chi thứ nhất (0-11)
+ * @param branchIndexB - Index Địa Chi thứ hai (0-11)
+ */
+declare function isXung(branchIndexA: number, branchIndexB: number): boolean;
+/**
+ * Lấy Chi bị Lục Hại với một Chi cho trước (xem {@link HAI_BRANCH_TARGET}).
+ *
+ * @param branchIndex - Index Địa Chi (0-11, vào EARTHLY_BRANCHES)
+ * @returns Index Địa Chi bị hại
+ */
+declare function getHaiBranchIndex(branchIndex: number): number;
+/**
+ * Kiểm tra 2 Chi (tuổi) có phạm Lục Hại với nhau không.
+ *
+ * @param branchIndexA - Index Địa Chi thứ nhất (0-11)
+ * @param branchIndexB - Index Địa Chi thứ hai (0-11)
+ */
+declare function isHai(branchIndexA: number, branchIndexB: number): boolean;
+/**
+ * Lấy nhóm Tứ Hành Xung (0-2) chứa một Chi cho trước.
+ *
+ * @param branchIndex - Index Địa Chi (0-11, vào EARTHLY_BRANCHES)
+ * @returns Index nhóm (0-2, xem {@link getTuHanhXungGroupMembers})
+ */
+declare function getTuHanhXungGroupIndex(branchIndex: number): number;
+/**
+ * Lấy 4 Chi thuộc cùng nhóm Tứ Hành Xung với một Chi cho trước (bao gồm cả chính nó).
+ *
+ * @param branchIndex - Index Địa Chi (0-11, vào EARTHLY_BRANCHES)
+ * @returns Mảng 4 index Địa Chi cùng nhóm
+ */
+declare function getTuHanhXungGroupMembers(branchIndex: number): number[];
+/**
+ * Kiểm tra 2 Chi (tuổi) khác nhau có cùng nhóm Tứ Hành Xung không.
+ *
+ * @param branchIndexA - Index Địa Chi thứ nhất (0-11)
+ * @param branchIndexB - Index Địa Chi thứ hai (0-11)
+ */
+declare function isTuHanhXung(branchIndexA: number, branchIndexB: number): boolean;
+/** Kết quả trả về của {@link getZodiacConflicts}. */
+interface ZodiacConflicts {
+    xung: boolean;
+    hai: boolean;
+    tuHanhXung: boolean;
+}
+/**
+ * Kiểm tra toàn bộ quan hệ "kỵ tuổi" (Lục Xung, Lục Hại, Tứ Hành Xung) giữa 2 tuổi
+ * (Chi năm sinh). Không loại trừ lẫn nhau — 1 cặp Chi có thể vừa Lục Xung vừa cùng
+ * nhóm Tứ Hành Xung (vd. Tý-Ngọ là cả 2).
+ *
+ * @param branchIndexA - Index Địa Chi (con giáp) thứ nhất (0-11)
+ * @param branchIndexB - Index Địa Chi (con giáp) thứ hai (0-11)
+ *
+ * @example
+ * ```typescript
+ * getZodiacConflicts(0, 6); // Tý (0) và Ngọ (6)
+ * // → { xung: true, hai: false, tuHanhXung: true }
+ * ```
+ */
+declare function getZodiacConflicts(branchIndexA: number, branchIndexB: number): ZodiacConflicts;
+
+/** Kết quả trả về của {@link getYearDetails}. */
+interface YearDetails {
+    can: string;
+    chi: string;
+    menh: string;
+    /** Index Ngũ Hành của `menh` (0-4, vào FIVE_ELEMENTS) — dùng cho `getElementRelation` (ngu-hanh.ts). */
+    menhIndex: number;
+    fullString: string;
+}
+/**
+ * Lấy ra chuỗi mô tả toàn bộ Can, Chi và Mệnh dựa vào số năm (Ví dụ: 2024)
+ * Theo quy ước: Năm 4 (sau CN) là năm Giáp Tý (Can index 0, Chi index 0)
+ *
+ * Công thức Can Chi là chu kỳ 60 năm lặp lại vô hạn nên nhận mọi số năm nguyên,
+ * kể cả năm 0 hoặc âm (trước Công Nguyên) — không giới hạn phạm vi như
+ * `LichTa.toLunar` (phạm vi đó là do thuật toán tìm Điểm Sóc, không áp
+ * dụng cho công thức Can Chi thuần).
+ *
+ * @param year - Năm (số nguyên bất kỳ, kể cả 0 hoặc âm)
+ *
+ * @example
+ * ```typescript
+ * getYearDetails(2024);
+ * // → { can: 'Giáp', chi: 'Thìn', menh: 'Hỏa', menhIndex: 3, fullString: 'Giáp Thìn - Mệnh Hỏa' }
+ * ```
+ */
+declare function getYearDetails(year: number): YearDetails;
 /**
  * Lấy danh sách 6 giờ Hoàng Đạo trong ngày.
  * Giờ Hoàng Đạo phụ thuộc vào Địa Chi của ngày.
@@ -226,6 +512,65 @@ declare function getAuspiciousHours(dayJd: number, locale?: Locale): string[];
  * @returns Mảng 6 index Địa Chi (ví dụ: [0, 1, 3, 6, 7, 9])
  */
 declare function getAuspiciousHourIndices(dayJd: number): number[];
+/**
+ * Lấy index (0-11, theo thứ tự Địa Chi Tý→Hợi) của 6 giờ Hắc Đạo (giờ xấu) trong
+ * ngày — phần bù của {@link getAuspiciousHourIndices} trong 12 canh giờ (6 giờ
+ * Hoàng Đạo + 6 giờ Hắc Đạo = đủ 12 canh).
+ *
+ * @param dayJd - Julian Day Number của ngày
+ * @returns Mảng 6 index Địa Chi, tăng dần
+ */
+declare function getInauspiciousHourIndices(dayJd: number): number[];
+/**
+ * Lấy danh sách 6 giờ Hắc Đạo (giờ xấu) trong ngày theo locale (xem
+ * {@link getInauspiciousHourIndices}).
+ *
+ * @param dayJd - Julian Day Number của ngày
+ * @param locale - Ngôn ngữ hiển thị (mặc định: 'vi')
+ * @returns Mảng 6 chuỗi tên Địa Chi
+ */
+declare function getInauspiciousHours(dayJd: number, locale?: Locale): string[];
+
+/**
+ * Lấy tên Tiết Khí theo index và locale.
+ *
+ * @param index - Index Tiết Khí (0-23, xem {@link getSolarTermIndex} trong astronomical.ts;
+ *   0 = Xuân Phân, 18 = Đông Chí, 21 = Lập Xuân, ...)
+ * @param locale - Ngôn ngữ hiển thị (mặc định: 'vi')
+ */
+declare function getSolarTermName(index: number, locale?: Locale): string;
+/**
+ * Lấy Tiết Khí đang hiệu lực tại một ngày dương lịch cho trước.
+ *
+ * `getSolarTermIndex` (astronomical.ts) trả về kinh độ Mặt Trời tại thời điểm 00:00 (đầu
+ * ngày) của `jdn`. Theo quy ước almanac truyền thống, một ngày được tính là "ngày
+ * Tiết Khí X" nếu thời điểm chuyển Tiết Khí rơi vào bất kỳ lúc nào trong ngày đó —
+ * tức là dùng giá trị tại 00:00 của ngày **kế tiếp** mới phản ánh đúng Tiết Khí đã
+ * "chốt" cho ngày hiện tại. Vì vậy hàm này tra cứu tại `jd + 1`, không phải `jd`.
+ *
+ * @param day - Ngày dương lịch (1-31)
+ * @param month - Tháng dương lịch (1-12)
+ * @param year - Năm dương lịch
+ * @param timeZone - Múi giờ (mặc định: 7 cho GMT+7 Việt Nam)
+ * @param locale - Ngôn ngữ hiển thị (mặc định: 'vi')
+ *
+ * @example
+ * ```typescript
+ * getSolarTerm(21, 6, 2024);
+ * // → { index: 6, name: 'Hạ Chí', date: { day: 21, month: 6, year: 2024 }, jd: ... }
+ * ```
+ */
+declare function getSolarTerm(day: number, month: number, year: number, timeZone?: number, locale?: Locale): SolarTerm;
+/**
+ * Liệt kê toàn bộ Tiết Khí bắt đầu trong một năm dương lịch (thường 24 hoặc 25 lần
+ * xuất hiện tùy năm, do các Tiết Khí không rơi đúng vào ranh giới năm).
+ *
+ * @param year - Năm dương lịch
+ * @param timeZone - Múi giờ (mặc định: 7 cho GMT+7 Việt Nam)
+ * @param locale - Ngôn ngữ hiển thị (mặc định: 'vi')
+ * @returns Mảng {@link SolarTerm} theo thứ tự thời gian tăng dần
+ */
+declare function getSolarTermsInYear(year: number, timeZone?: number, locale?: Locale): SolarTerm[];
 
 /**
  * Lấy tên tháng âm lịch dạng chữ truyền thống.
@@ -302,26 +647,4 @@ declare function formatLunarDate(lunar: LunarDate, pattern: string, locale?: Loc
  */
 declare function formatTraditional(lunar: LunarDate): string;
 
-/** Một ô ngày trong lưới lịch tháng. */
-interface CalendarDayCell {
-    solar: Date;
-    lunar: LunarDate;
-    isToday: boolean;
-    isSelected: boolean;
-    isCurrentMonth: boolean;
-}
-/**
- * Dựng lưới 42 ô (6 tuần x 7 ngày) cho 1 tháng dương lịch, gồm ngày tràn từ
- * tháng trước/sau để lấp đầy tuần đầu/cuối, mỗi ô kèm ngày âm tương ứng.
- *
- * Logic này trước đây bị lặp lại độc lập ở Calendar.tsx/vue/svelte — tách ra
- * đây để có 1 nguồn tính toán duy nhất (tránh 3 bản có thể lệch nhau khi sửa
- * riêng lẻ), dùng chung cho cả Calendar và DatePicker ở mọi framework.
- *
- * @param month - Tháng dương lịch (1-12)
- * @param year - Năm dương lịch
- * @param selectedDate - Ngày đang được chọn (nếu có), dùng để đánh dấu `isSelected`
- */
-declare function getCalendarGrid(month: number, year: number, selectedDate?: Date | null): CalendarDayCell[];
-
-export { type CalendarDayCell, LichTa, type Locale, type LunarDate, type SolarDate, type YearDetails, formatLunarDate, formatTraditional, getAuspiciousHourIndices, getAuspiciousHours, getCalendarGrid, getDayCanChi, getDayName, getHourCanChi, getMonthCanChi, getMonthName, getYearDetails, getZodiacAnimal, jdFromDate, jdToDate, t };
+export { type CalendarDayCell, type FirstDayOfWeek, LichTa, type Locale, type LunarDate, type SolarDate, type SolarTerm, type YearDetails, type ZodiacConflicts, formatLunarDate, formatTraditional, getAuspiciousHourIndices, getAuspiciousHours, getCalendarGrid, getDayCanChi, getDayElement, getDayElementIndex, getDayName, getElementName, getElementRelation, getElementRelationIndex, getHaiBranchIndex, getHourCanChi, getHourElement, getHourElementIndex, getISOWeekNumber, getInauspiciousHourIndices, getInauspiciousHours, getMonthCanChi, getMonthElement, getMonthElementIndex, getMonthName, getSolarTerm, getSolarTermName, getSolarTermsInYear, getTruc, getTrucIndex, getTrucName, getTrucQuality, getTrucQualityIndex, getTuHanhXungGroupIndex, getTuHanhXungGroupMembers, getWeekDayLabels, getXungBranchIndex, getYearDetails, getZodiacAnimal, getZodiacConflicts, isHai, isTuHanhXung, isXung, jdFromDate, jdToDate, t };