react-native-lich-am 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nguyen Hoa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,248 @@
+# react-native-lich-am
+
+[![CI](https://github.com/sep21th03/react-native-lich-am/actions/workflows/ci.yml/badge.svg)](https://github.com/sep21th03/react-native-lich-am/actions/workflows/ci.yml)
+
+Thư viện **lịch âm (âm lịch Việt Nam)** cho React Native và JavaScript.
+
+- Thuật toán thuần — **không phụ thuộc thư viện nào**, không cần native module
+- **Không cần build**: `lib/` đã dựng sẵn trong package
+- Kèm **dữ liệu chi tiết 1.462 ngày** (01/01/2024 → 01/01/2028): sao tốt/xấu, việc nên làm, điểm từng giờ, hướng tốt, tuổi xung
+- Kèm component `<LunarCalendar />` và `<LunarDayDetail />` sẵn dùng
+- TypeScript đầy đủ — chạy trên Hermes, Expo, Node và trình duyệt
+
+---
+
+## Cài đặt
+
+```bash
+npm i react-native-lich-am
+# hoặc: yarn add react-native-lich-am | pnpm add react-native-lich-am
+```
+
+Yêu cầu (chỉ khi dùng phần component): `react >= 17`, `react-native >= 0.64`.
+Hai gói này là **peer dependency tuỳ chọn** — chỉ dùng phần core/dữ liệu thì không cần.
+
+---
+
+## Chọn entry point
+
+| Entry point | Nội dung | Kích thước |
+|---|---|---|
+| `react-native-lich-am` | Core thuật toán — không kèm dữ liệu | ~60 KB |
+| `react-native-lich-am/dataset` | Dữ liệu chi tiết 2024–2028 | ~1 MB |
+| `react-native-lich-am/dataset/2024` | Chỉ một năm | ~245 KB |
+| `react-native-lich-am/ui` | Component React Native | ~52 KB |
+
+Chỉ cần đổi ngày dương ↔ âm thì import entry gốc là đủ, bundle không tăng.
+
+---
+
+## Dùng cơ bản
+
+```ts
+import { getLunarDayInfo, getTodayLunar, solarToLunar, lunarToSolar } from 'react-native-lich-am';
+
+const info = getLunarDayInfo(new Date());
+
+info.solar.iso;              // "2026-09-29"
+info.lunar.text;             // "19/8/2026"
+info.lunar.monthNameFull;    // "tháng Tám"
+info.canChi.day.name;        // "Bính Ngọ"
+info.canChi.year.name;       // "Bính Ngọ"  (can chi năm)
+info.conGiap;                // "Ngựa"
+info.napAm.day.name;         // "Thiên Hà Thủy"
+info.tietKhi.name;           // "Thu phân"
+info.truc.name;              // "Bình"
+info.gioHoangDao.map(g => `${g.chi} ${g.range}`);
+// ["Tý 23:00 – 00:59", "Sửu 01:00 – 02:59", ...]
+info.huongXuatHanh;          // { hyThan: "Tây Nam", taiThan: "Tây", hacThan: "Đông" }
+```
+
+### Chuyển đổi
+
+```ts
+solarToLunar(10, 2, 2024);
+// { day: 1, month: 1, year: 2024, leap: false, jd: 2460351 }  → mùng 1 Tết Giáp Thìn
+
+lunarToSolar(1, 1, 2024);
+// { day: 10, month: 2, year: 2024, jd: 2460351 }
+
+solarToLunar(25, 7, 2025).leap;   // true  (tháng 6 nhuận năm 2025)
+```
+
+### Ngày âm hôm nay
+
+```ts
+getTodayLunar();   // { day, month, year, leap, monthName, text }
+```
+
+---
+
+## Dữ liệu chi tiết theo ngày
+
+```ts
+import { getDayData, findGoodDays, topDays, getQualityStats, listActivities } from 'react-native-lich-am/dataset';
+
+const d = getDayData('2026-09-29');
+
+d.lunar;         // { day: 19, month: 8, year: 2026 }
+d.lunarRaw;      // "19-8-2026"
+d.saoTot;        // ["Thiên ân", "Nguyệt ân", ...]
+d.saoXau;        // ["Thiên hỏa", "Nguyệt yếm", ...]
+d.nenLam;        // ["Cầu cúng", "Khai trương", ...]
+d.khongNenLam;   // ["Động thổ", "An táng", ...]
+d.gio;           // đủ 12 khung: { index, chi, diem, sao, top, nguon }
+d.gioRaw;        // 12 khung ở dạng chưa chuẩn hoá
+d.gioTotNhat;    // 5 giờ tốt nhất (thang điểm riêng, xem ghi chú bên dưới)
+d.bonGioDaiCat;  // 4 giờ đại cát (Thiên ất / Thiên không)
+d.gioQuyDangThienMon;
+d.huong.ngay;    // [{ son: "Khôn", huong: "Chính Tây Nam", soSao: 4 }, ...]
+d.tuoiXung;      // ["Mậu Tý", "Nhâm Tý", "Giáp Ngọ", ...]
+d.diem;          // 0–100
+d.chatLuong;     // 'dep' | 'tot' | 'bt' | 'xau' | 'ratxau'
+d.ngayRatXau;    // boolean
+```
+
+### `d.gio` — luôn đủ 12 khung giờ
+
+Mỗi khung có dạng `{ index, chi, diem, sao, top, nguon }`:
+
+- `diem` — điểm của giờ, tính bằng `Σ trọng số các sao` chiếu vào giờ đó
+- `sao` — danh sách sao; luôn có **đúng một** thần hoàng đạo/hắc đạo
+- `nguon` — `'nguon' | 'sua' | 'suy-ra'`, mức độ can thiệp so với dữ liệu thô
+- `gioRaw` — bản thô chưa chuẩn hoá, nếu bạn cần đối chiếu
+
+`d.gio` luôn có **12 phần tử** với `index` từ 0 (Tý) đến 11 (Hợi), nên render lưới
+giờ không cần kiểm tra thiếu phần tử.
+
+### Tìm ngày tốt cho một việc
+
+```ts
+listActivities();   // 31 việc: "Thành hôn", "Khai trương", "Động thổ", ...
+
+const days = findGoodDays({
+  activity: 'Khai trương',
+  from: '2026-10-01',
+  to: '2026-12-31',
+  minQuality: 'tot',
+  excludeVeryBad: true,
+  limit: 10,
+});
+// → 10 ngày, xếp theo điểm giảm dần
+```
+
+Với **một việc cụ thể**, thư viện dùng thẳng dữ liệu: việc đó có nằm trong nhóm
+**"Nên làm"** của ngày hay không — không suy diễn thêm.
+
+```ts
+topDays('2026-10-01', '2026-10-31', 5);      // 5 ngày đẹp nhất tháng
+getQualityStats('2026-01-01', '2026-12-31'); // { dep, tot, bt, xau, ratxau, total, avgDiem }
+```
+
+---
+
+## Component
+
+```tsx
+import { LunarCalendar, LunarDayDetail } from 'react-native-lich-am/ui';
+import { getDayData } from 'react-native-lich-am/dataset';
+import { getLunarDayInfo } from 'react-native-lich-am';
+import { useState } from 'react';
+
+export default function App() {
+  const [info, setInfo] = useState(() => getLunarDayInfo(new Date()));
+
+  return (
+    <>
+      <LunarCalendar
+        dayDataProvider={getDayData}      // có → tô màu chất lượng ngày + hiện chú thích
+        onSelectDay={(day) => setInfo(day)}
+        weekStartsOn={1}                  // tuần bắt đầu từ Thứ hai
+        colorScheme="light"               // 'light' | 'dark'
+      />
+      <LunarDayDetail day={info} data={getDayData(info.solar.iso)} />
+    </>
+  );
+}
+```
+
+`<LunarDayDetail />` có prop `sections` để chọn phần hiển thị:
+`'canchi' | 'gio' | 'sao' | 'viec' | 'huong' | 'tuoixung'`.
+
+### Tuỳ biến màu
+
+```tsx
+<LunarCalendar
+  theme={{ primary: '#0EA5E9', radius: 16, quality: { dep: '#22C55E' } }}
+/>
+```
+
+---
+
+## Đã kiểm chứng
+
+Đối chiếu trên **1.462 ngày** liên tục:
+
+| Trường | Khớp |
+|---|---|
+| Ngày âm (ngày/tháng/năm, kể cả tháng nhuận) | 1462/1462 |
+| Can chi năm / tháng / ngày | 1462/1462 |
+| Ngũ hành nạp âm của ngày | 1462/1462 |
+| Trực | 1462/1462 |
+| Tiết khí (24 tiết) | 1462/1462 |
+| Giờ hoàng đạo | 1462/1462 |
+| Thần cai quản từng giờ | 43.541/43.541 |
+
+Bảng giờ hoàng đạo và hướng xuất hành cũng đối chiếu khớp với nguồn độc lập
+(29/09/2026 — ngày Bính Ngọ: Tý Sửu Mão Ngọ Thân Dậu · Hỷ Tây Nam · Tài Tây · Hạc Đông).
+
+---
+
+## Ghi chú kỹ thuật
+
+- **Múi giờ**: mặc định UTC+7 (lịch Việt Nam). Mọi hàm đều nhận tham số `timeZone` nếu cần.
+- **Sóc (new moon)** dùng chuỗi Meeus 49.1 + 49.2 đầy đủ, kể cả số hạng nhiễu hành tinh —
+  chính xác cỡ vài chục giây, đủ để không lệch ngày ở những kỳ sóc rơi sát nửa đêm.
+- **Tiết khí** ấn định cho ngày mà **thời điểm giao tiết rơi vào**, nên vị trí mặt trời
+  được lấy ở **cuối ngày** địa phương chứ không phải 00:00.
+- **Trực** tính theo **chi tháng tiết khí** (Lập xuân → Dần, …), không phải tháng âm.
+- **Can chi tháng** tính theo **tháng âm** (Ngũ Hổ Độn); can chi giờ theo Ngũ Thử Độn.
+- **Giờ hoàng đạo** sinh từ công thức `(2 × chi ngày + 8) mod 12` — cho ra đúng bảng cổ điển.
+- **Điểm ngày đẹp** (`d.diem`) là chỉ số tổng hợp do thư viện tính:
+  `1,0 × sao tốt − 1,2 × sao xấu − 3,0 × (ngày rất xấu) + (tổng điểm giờ tốt)/4 + hệ số Trực`,
+  rồi quy về thang 0–100 theo phân vị trên toàn bộ 1.462 ngày.
+- **`d.gioTotNhat` dùng thang điểm riêng**, không so được với `d.gio[].diem`.
+- **`d.tuoiXung`** là dữ liệu tra cứu, không suy ra từ công thức.
+
+---
+
+## Phát triển
+
+```bash
+npm run smoke     # 66 assert, chạy trong 1 giây
+npm run build     # dựng lại lib/ từ src/ (TypeScript)
+```
+
+`lib/` là bản dựng sẵn đã commit — người dùng cài là chạy, không cần build.
+CI dựng lại `lib/` từ `src/` và so với bản đã commit, nên nhớ chạy `npm run build`
+trước khi push.
+
+```
+src/            nguồn TypeScript (nguồn chân lý)
+  core/         thuật toán — không phụ thuộc gì
+  dataset/      giải mã dữ liệu + tra cứu
+  ui/           component React Native
+lib/            bản JS đã dựng (được publish)
+core/ dataset/ ui/   proxy cho bundler không hỗ trợ trường "exports"
+```
+
+---
+
+## Giấy phép
+
+**MIT** — xem [LICENSE](./LICENSE).
+
+Bộ dữ liệu lịch kèm theo chỉ nên dùng cho mục đích cá nhân / tham khảo.
+
+Nội dung can chi, sao tốt xấu, giờ hoàng đạo là **tham khảo văn hoá**, không phải
+lời khuyên về tài chính, y tế hay pháp lý.

package/core/index.d.ts

@@ -0,0 +1 @@
+export * from '../lib/core/index';

package/core/index.js

@@ -0,0 +1 @@
+module.exports = require('../lib/core/index.js');

package/core/package.json

@@ -0,0 +1,5 @@
+{
+  "main": "../lib/core/index.js",
+  "types": "../lib/core/index.d.ts",
+  "sideEffects": false
+}

package/dataset/2024.d.ts

@@ -0,0 +1 @@
+export * from '../lib/dataset/2024';

package/dataset/2024.js

@@ -0,0 +1 @@
+module.exports = require('../lib/dataset/2024.js');

package/dataset/2025.d.ts

@@ -0,0 +1 @@
+export * from '../lib/dataset/2025';

package/dataset/2025.js

@@ -0,0 +1 @@
+module.exports = require('../lib/dataset/2025.js');

package/dataset/2026.d.ts

@@ -0,0 +1 @@
+export * from '../lib/dataset/2026';

package/dataset/2026.js

@@ -0,0 +1 @@
+module.exports = require('../lib/dataset/2026.js');

package/dataset/2027.d.ts

@@ -0,0 +1 @@
+export * from '../lib/dataset/2027';

package/dataset/2027.js

@@ -0,0 +1 @@
+module.exports = require('../lib/dataset/2027.js');

package/dataset/2028.d.ts

@@ -0,0 +1 @@
+export * from '../lib/dataset/2028';

package/dataset/2028.js

@@ -0,0 +1 @@
+module.exports = require('../lib/dataset/2028.js');

package/dataset/index.d.ts

@@ -0,0 +1 @@
+export * from '../lib/dataset/index';

package/dataset/index.js

@@ -0,0 +1 @@
+module.exports = require('../lib/dataset/index.js');

package/dataset/package.json

@@ -0,0 +1,5 @@
+{
+  "main": "../lib/dataset/index.js",
+  "types": "../lib/dataset/index.d.ts",
+  "sideEffects": false
+}

package/lib/core/astro.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Phần thiên văn: số ngày Julian, sóc (new moon) và kinh độ mặt trời.
+ *
+ * Công thức theo bộ tính âm lịch phổ biến của Hồ Ngọc Đức (dựa trên
+ * Jean Meeus — "Astronomical Algorithms"), đã được đối chiếu với
+ * 1.462 ngày dữ liệu lịch Việt (2024–2028) trong quá trình kiểm thử.
+ */
+/** Làm tròn xuống (khác `Math.floor` với số âm, giống `int()` của C) */
+export declare function int(v: number): number;
+/**
+ * Số ngày Julian của ngày dương lịch.
+ * Tự động dùng lịch Julius trước 15/10/1582 và lịch Gregorian sau đó.
+ */
+export declare function jdFromDate(dd: number, mm: number, yy: number): number;
+/** Đổi số ngày Julian về [ngày, tháng, năm] dương lịch */
+export declare function jdToDate(jd: number): [number, number, number];
+/**
+ * Thời điểm sóc (new moon) thứ k, trả về JD theo giờ UT.
+ *
+ * Dùng chuỗi Meeus 49.1 + 49.2 đầy đủ (kể cả nhiễu hành tinh), chính xác
+ * tới cỡ vài chục giây. Bản rút gọn của Hồ Ngọc Đức sai tới ~15 phút, đủ để
+ * lật ngày ở những kỳ sóc rơi sát nửa đêm (ví dụ tháng 7 âm lịch năm 2026).
+ */
+export declare function newMoon(k: number): number;
+/** Kinh độ thật của mặt trời tại thời điểm jdn, đơn vị radian (0 → 2π) */
+export declare function sunLongitude(jdn: number): number;
+/** Ngày (theo múi giờ) chứa thời điểm sóc thứ k */
+export declare function getNewMoonDay(k: number, timeZone?: number): number;
+/**
+ * Kinh độ mặt trời tại nửa đêm địa phương, quy về 12 cung
+ * (mỗi cung 30°, tương ứng 12 "trung khí").
+ */
+export declare function getSunLongitude(dayNumber: number, timeZone?: number): number;
+/** Ngày bắt đầu tháng 11 âm lịch của năm dương lịch `yy` (dạng JD) */
+export declare function getLunarMonth11(yy: number, timeZone?: number): number;
+/** Độ lệch của tháng nhuận so với tháng 11 âm lịch (0 = không nhuận) */
+export declare function getLeapMonthOffset(a11: number, timeZone?: number): number;
+/** JD của 00:00 ngày hôm nay theo múi giờ `timeZone` (tính từ Date) */
+export declare function jdFromDateObject(date: Date, timeZone?: number): number;
+/** JD (tại 00:00 UTC) → timestamp mili giây */
+export declare function jdToTimestamp(jd: number): number;
+/** Timestamp mili giây → JD */
+export declare function timestampToJd(ms: number): number;

package/lib/core/astro.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * Phần thiên văn: số ngày Julian, sóc (new moon) và kinh độ mặt trời.
+ *
+ * Công thức theo bộ tính âm lịch phổ biến của Hồ Ngọc Đức (dựa trên
+ * Jean Meeus — "Astronomical Algorithms"), đã được đối chiếu với
+ * 1.462 ngày dữ liệu lịch Việt (2024–2028) trong quá trình kiểm thử.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.timestampToJd = exports.jdToTimestamp = exports.jdFromDateObject = exports.getLeapMonthOffset = exports.getLunarMonth11 = exports.getSunLongitude = exports.getNewMoonDay = exports.sunLongitude = exports.newMoon = exports.jdToDate = exports.jdFromDate = exports.int = void 0;
+const constants_1 = require("./constants");
+const PI = Math.PI;
+const DR = PI / 180;
+/** Làm tròn xuống (khác `Math.floor` với số âm, giống `int()` của C) */
+function int(v) {
+    return Math.floor(v);
+}
+exports.int = int;
+/**
+ * Số ngày Julian của ngày dương lịch.
+ * Tự động dùng lịch Julius trước 15/10/1582 và lịch Gregorian sau đó.
+ */
+function jdFromDate(dd, mm, yy) {
+    const a = int((14 - mm) / 12);
+    const y = yy + 4800 - a;
+    const m = mm + 12 * a - 3;
+    let jd = dd + int((153 * m + 2) / 5) + 365 * y + int(y / 4) - int(y / 100) + int(y / 400) - 32045;
+    if (jd < 2299161) {
+        jd = dd + int((153 * m + 2) / 5) + 365 * y + int(y / 4) - 32083;
+    }
+    return jd;
+}
+exports.jdFromDate = jdFromDate;
+/** Đổi số ngày Julian về [ngày, tháng, năm] dương lịch */
+function jdToDate(jd) {
+    let a;
+    let b;
+    let c;
+    if (jd > 2299160) {
+        a = jd + 32044;
+        b = int((4 * a + 3) / 146097);
+        c = a - int((b * 146097) / 4);
+    }
+    else {
+        b = 0;
+        c = jd + 32082;
+    }
+    const d = int((4 * c + 3) / 1461);
+    const e = c - int((1461 * d) / 4);
+    const m = int((5 * e + 2) / 153);
+    const day = e - int((153 * m + 2) / 5) + 1;
+    const month = m + 3 - 12 * int(m / 10);
+    const year = b * 100 + d - 4800 + int(m / 10);
+    return [day, month, year];
+}
+exports.jdToDate = jdToDate;
+/**
+ * Hệ số k của Hồ Ngọc Đức lấy mốc 1900-01-01, còn Meeus lấy mốc 2000-01-06.
+ * Hai mốc cách nhau đúng 1237 tuần trăng nên chỉ cần dịch k;
+ * pha của các số hạng tuần hoàn vẫn giữ nguyên.
+ */
+const MEEUS_K_OFFSET = 1237;
+/** ΔT (TT − UT) tính bằng giây — Espenak & Meeus, dùng cho giai đoạn 2005–2050 */
+function deltaTSeconds(year) {
+    if (year < 2005) {
+        const t0 = year - 2000;
+        return 63.86 + 0.3345 * t0 - 0.060374 * t0 * t0 + 0.0017275 * t0 * t0 * t0;
+    }
+    const t = year - 2000;
+    return 62.92 + 0.32217 * t + 0.005589 * t * t;
+}
+/**
+ * Thời điểm sóc (new moon) thứ k, trả về JD theo giờ UT.
+ *
+ * Dùng chuỗi Meeus 49.1 + 49.2 đầy đủ (kể cả nhiễu hành tinh), chính xác
+ * tới cỡ vài chục giây. Bản rút gọn của Hồ Ngọc Đức sai tới ~15 phút, đủ để
+ * lật ngày ở những kỳ sóc rơi sát nửa đêm (ví dụ tháng 7 âm lịch năm 2026).
+ */
+function newMoon(k) {
+    const km = k - MEEUS_K_OFFSET;
+    const T = km / 1236.85;
+    const T2 = T * T;
+    const T3 = T2 * T;
+    const T4 = T3 * T;
+    const jde = 2451550.09766 + 29.530588861 * km
+        + 0.00015437 * T2 - 0.000000150 * T3 + 0.00000000073 * T4;
+    const E = 1 - 0.002516 * T - 0.0000074 * T2;
+    const M = (2.5534 + 29.10535670 * km - 0.0000014 * T2 - 0.00000011 * T3) * DR;
+    const Mp = (201.5643 + 385.81693528 * km + 0.0107582 * T2 + 0.00001238 * T3 - 0.000000058 * T4) * DR;
+    const F = (160.7108 + 390.67050284 * km - 0.0016118 * T2 - 0.00000227 * T3 + 0.000000011 * T4) * DR;
+    const Om = (124.7746 - 1.56375588 * km + 0.0020672 * T2 + 0.00000215 * T3) * DR;
+    let c = 0;
+    c -= 0.40720 * Math.sin(Mp);
+    c += 0.17241 * E * Math.sin(M);
+    c += 0.01608 * Math.sin(2 * Mp);
+    c += 0.01039 * Math.sin(2 * F);
+    c += 0.00739 * E * Math.sin(Mp - M);
+    c -= 0.00514 * E * Math.sin(Mp + M);
+    c += 0.00208 * E * E * Math.sin(2 * M);
+    c -= 0.00111 * Math.sin(Mp - 2 * F);
+    c -= 0.00057 * Math.sin(Mp + 2 * F);
+    c += 0.00056 * E * Math.sin(2 * Mp + M);
+    c -= 0.00042 * Math.sin(3 * Mp);
+    c += 0.00042 * E * Math.sin(M + 2 * F);
+    c += 0.00038 * E * Math.sin(M - 2 * F);
+    c -= 0.00024 * E * Math.sin(2 * Mp - M);
+    c -= 0.00017 * Math.sin(Om);
+    c -= 0.00007 * Math.sin(Mp + 2 * M);
+    c += 0.00004 * Math.sin(2 * Mp - 2 * F);
+    c += 0.00004 * Math.sin(3 * M);
+    c += 0.00003 * Math.sin(Mp + M - 2 * F);
+    c += 0.00003 * Math.sin(2 * Mp + 2 * F);
+    c -= 0.00003 * Math.sin(Mp + M + 2 * F);
+    c += 0.00003 * Math.sin(Mp - M + 2 * F);
+    c -= 0.00002 * Math.sin(Mp - M - 2 * F);
+    c -= 0.00002 * Math.sin(3 * Mp + M);
+    c += 0.00002 * Math.sin(4 * Mp);
+    // Nhiễu do các hành tinh khác (Meeus, bảng 49.A)
+    c += 0.000325 * Math.sin((299.77 + 0.107408 * km - 0.009173 * T2) * DR);
+    c += 0.000165 * Math.sin((251.88 + 0.016321 * km) * DR);
+    c += 0.000164 * Math.sin((251.83 + 26.651886 * km) * DR);
+    c += 0.000126 * Math.sin((349.42 + 36.412478 * km) * DR);
+    c += 0.000110 * Math.sin((84.66 + 18.206239 * km) * DR);
+    c += 0.000062 * Math.sin((141.74 + 53.303771 * km) * DR);
+    c += 0.000060 * Math.sin((207.14 + 2.453732 * km) * DR);
+    c += 0.000056 * Math.sin((154.84 + 7.306860 * km) * DR);
+    c += 0.000047 * Math.sin((34.52 + 27.261239 * km) * DR);
+    c += 0.000042 * Math.sin((207.19 + 0.121824 * km) * DR);
+    c += 0.000040 * Math.sin((291.34 + 1.844379 * km) * DR);
+    c += 0.000037 * Math.sin((161.72 + 24.198154 * km) * DR);
+    c += 0.000035 * Math.sin((239.56 + 25.513099 * km) * DR);
+    c += 0.000023 * Math.sin((331.55 + 3.592518 * km) * DR);
+    return jde + c - deltaTSeconds(1900 + k / 12.3685) / 86400;
+}
+exports.newMoon = newMoon;
+/** Kinh độ thật của mặt trời tại thời điểm jdn, đơn vị radian (0 → 2π) */
+function sunLongitude(jdn) {
+    const T = (jdn - 2451545.0) / 36525;
+    const T2 = T * T;
+    const M = 357.5291 + 35999.0503 * T - 0.0001559 * T2 - 0.00000048 * T * T2;
+    const L0 = 280.46645 + 36000.76983 * T + 0.0003032 * T2;
+    let dl = (1.9146 - 0.004817 * T - 0.000014 * T2) * Math.sin(DR * M);
+    dl += (0.019993 - 0.000101 * T) * Math.sin(DR * 2 * M) + 0.00029 * Math.sin(DR * 3 * M);
+    let l = (L0 + dl) * DR;
+    l -= PI * 2 * int(l / (PI * 2));
+    return l;
+}
+exports.sunLongitude = sunLongitude;
+/** Ngày (theo múi giờ) chứa thời điểm sóc thứ k */
+function getNewMoonDay(k, timeZone = constants_1.TZ_VN) {
+    return int(newMoon(k) + 0.5 + timeZone / 24);
+}
+exports.getNewMoonDay = getNewMoonDay;
+/**
+ * Kinh độ mặt trời tại nửa đêm địa phương, quy về 12 cung
+ * (mỗi cung 30°, tương ứng 12 "trung khí").
+ */
+function getSunLongitude(dayNumber, timeZone = constants_1.TZ_VN) {
+    return int((sunLongitude(dayNumber - 0.5 - timeZone / 24) / PI) * 6);
+}
+exports.getSunLongitude = getSunLongitude;
+/** Ngày bắt đầu tháng 11 âm lịch của năm dương lịch `yy` (dạng JD) */
+function getLunarMonth11(yy, timeZone = constants_1.TZ_VN) {
+    const off = jdFromDate(31, 12, yy) - 2415021;
+    const k = int(off / 29.530588853);
+    let nm = getNewMoonDay(k, timeZone);
+    const sunLong = getSunLongitude(nm, timeZone);
+    if (sunLong >= 9) {
+        nm = getNewMoonDay(k - 1, timeZone);
+    }
+    return nm;
+}
+exports.getLunarMonth11 = getLunarMonth11;
+/** Độ lệch của tháng nhuận so với tháng 11 âm lịch (0 = không nhuận) */
+function getLeapMonthOffset(a11, timeZone = constants_1.TZ_VN) {
+    const k = int((a11 - 2415021.076998695) / 29.530588853 + 0.5);
+    let last = 0;
+    let i = 1;
+    let arc = getSunLongitude(getNewMoonDay(k + i, timeZone), timeZone);
+    do {
+        last = arc;
+        i += 1;
+        arc = getSunLongitude(getNewMoonDay(k + i, timeZone), timeZone);
+    } while (arc !== last && i < 14);
+    return i - 1;
+}
+exports.getLeapMonthOffset = getLeapMonthOffset;
+/** JD của 00:00 ngày hôm nay theo múi giờ `timeZone` (tính từ Date) */
+function jdFromDateObject(date, timeZone = constants_1.TZ_VN) {
+    const shifted = new Date(date.getTime() + timeZone * 3600 * 1000);
+    return jdFromDate(shifted.getUTCDate(), shifted.getUTCMonth() + 1, shifted.getUTCFullYear());
+}
+exports.jdFromDateObject = jdFromDateObject;
+/** JD (tại 00:00 UTC) → timestamp mili giây */
+function jdToTimestamp(jd) {
+    return Math.round((jd - constants_1.JD_UNIX_EPOCH) * 86400000);
+}
+exports.jdToTimestamp = jdToTimestamp;
+/** Timestamp mili giây → JD */
+function timestampToJd(ms) {
+    return ms / 86400000 + constants_1.JD_UNIX_EPOCH;
+}
+exports.timestampToJd = timestampToJd;

package/lib/core/canchi.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Can Chi: năm, tháng, ngày, giờ — kèm Nạp Âm (ngũ hành) và con giáp.
+ */
+export interface CanChi {
+    /** Chỉ số 0–9 của thiên can */
+    canIndex: number;
+    /** Chỉ số 0–11 của địa chi */
+    chiIndex: number;
+    /** Chuỗi ghép, ví dụ "Giáp Tý" */
+    name: string;
+    /** Can */
+    can: string;
+    /** Chi */
+    chi: string;
+}
+export interface NapAm {
+    /** Tên nạp âm, ví dụ "Hải Trung Kim" */
+    name: string;
+    /** Ngũ hành: Kim | Mộc | Thủy | Hỏa | Thổ */
+    element: string;
+}
+/** Chỉ số 0–59 trong vòng 60 hoa giáp, từ cặp (can, chi) */
+export declare function canChiIndex(canIndex: number, chiIndex: number): number;
+/** Can Chi của năm âm lịch */
+export declare function getCanChiYear(lunarYear: number): CanChi;
+/** Can Chi của ngày, suy từ số ngày Julian */
+export declare function getCanChiDay(jd: number): CanChi;
+/**
+ * Can Chi của tháng âm lịch (theo Ngũ Hổ Độn).
+ *
+ * Tháng 1 (Dần) của năm Giáp/Kỷ là Bính Dần, Ất/Canh là Mậu Dần,
+ * Bính/Tân là Canh Dần, Đinh/Nhâm là Nhâm Dần, Mậu/Quý là Giáp Dần.
+ */
+export declare function getCanChiMonth(lunarMonth: number, lunarYear: number): CanChi;
+/**
+ * Can Chi của giờ (theo Ngũ Thử Độn).
+ *
+ * @param dayCanIndex chỉ số can của ngày (0 = Giáp)
+ * @param hourChiIndex chỉ số chi của giờ (0 = Tý)
+ */
+export declare function getCanChiHour(dayCanIndex: number, hourChiIndex: number): CanChi;
+/** Nạp âm của một cặp can chi */
+export declare function getNapAm(canIndex: number, chiIndex: number): NapAm;
+/** Ngũ hành của nạp âm ngày (dạng số 1..5 đúng quy ước Lịch Việt) */
+export declare function getNguHanhId(element: string): number;
+/** Con giáp của năm âm lịch */
+export declare function getConGiap(lunarYear: number): string;