@typescript-calendar-lib/core 0.1.1 → 0.4.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nazozokc
+
+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,235 @@
+# @typescript-calendar-lib/core
+
+Shared, framework-agnostic calendar utilities: date math, locale data, and grid building. Zero runtime dependencies.
+
+> **Tip:** You normally don't need `core` directly — the `cli`, `react`, and `tui` packages re-export the types and utilities you'll need. Reach for `core` when building your own renderer.
+
+## Installation
+
+```sh
+pnpm add @typescript-calendar-lib/core
+# or
+npm install @typescript-calendar-lib/core
+# or
+bun add @typescript-calendar-lib/core
+```
+
+## Types
+
+### `Locale`
+
+```ts
+type Locale = "en" | "ja" | "es" | "de" | "fr" | "ko" | "zh";
+```
+
+English, Japanese, Spanish, German, French, Korean, and Chinese (Simplified).
+
+### `WeekStart`
+
+```ts
+type WeekStart = "sunday" | "monday";
+```
+
+### `HighlightStyle`
+
+```ts
+type HighlightStyle = "bracket" | "reverse";
+```
+
+`"bracket"` wraps the day in brackets (`[8]`), `"reverse"` uses reverse-video styling.
+
+### `CalendarOptions`
+
+```ts
+interface CalendarOptions {
+  year: number;
+  month: number; // 1-indexed (1–12)
+  locale?: Locale;          // default: "en"
+  weekStart?: WeekStart;    // default: "sunday"
+  highlight?: Date;         // date to highlight (e.g. today)
+  highlightStyle?: HighlightStyle; // default: "bracket"
+  range?: { from: Date; to: Date };
+  color?: boolean;          // default: false
+}
+```
+
+### `CalendarYearOptions`
+
+Same as `CalendarOptions` minus `month` — renders a full year:
+
+```ts
+interface CalendarYearOptions {
+  year: number;
+  locale?: Locale;
+  weekStart?: WeekStart;
+  highlight?: Date;
+  highlightStyle?: HighlightStyle;
+  range?: { from: Date; to: Date };
+  color?: boolean;
+}
+```
+
+### `CalendarRangeOptions`
+
+Same as `CalendarOptions` minus `year`/`month`, rendered for every month between `from` and `to` (inclusive):
+
+```ts
+interface CalendarRangeOptions {
+  from: Date;
+  to: Date;
+  locale?: Locale;
+  weekStart?: WeekStart;
+  highlight?: Date;
+  highlightStyle?: HighlightStyle;
+  range?: { from: Date; to: Date };
+  color?: boolean;
+}
+```
+
+### `RenderMonthOptions`
+
+Same as `CalendarOptions` minus `year`/`month`. Used by the low-level `renderMonth` helper.
+
+## Constants
+
+### `LOCALES`
+
+```ts
+const LOCALES: Record<Locale, LocaleData>;
+```
+
+Contains month names, weekday headers, and short weekday headers for each locale.
+
+### `MIN_YEAR` / `MAX_YEAR`
+
+The supported year range (`1` / `9999`). Values outside this range are rejected by validation.
+
+## Functions
+
+### `getMonthName(locale, month): string`
+
+Returns the localized month name for a 1-indexed month:
+
+```ts
+getMonthName("en", 9); // "September"
+getMonthName("ja", 9); // "9月"
+```
+
+### `getWeekdayHeaders(locale, weekStart): readonly string[]`
+
+Returns the weekday header array respecting `weekStart`:
+
+```ts
+getWeekdayHeaders("en", "sunday"); // ["Sun", "Mon", ..., "Sat"]
+getWeekdayHeaders("en", "monday"); // ["Mon", "Tue", ..., "Sun"]
+```
+
+### `buildMonthGrid(year, month, weekStart): (number | null)[][]`
+
+Builds a 6×7 grid of day numbers (`1`–`31`) with `null` for empty cells. The grid is always 6 rows tall for stable layouts:
+
+```ts
+buildMonthGrid(2026, 9, "sunday");
+// [
+//   [null, null, 1, 2, 3, 4, 5],
+//   [6, 7, 8, 9, 10, 11, 12],
+//   ...
+// ]
+```
+
+### `firstDayOfMonth(year, month): Date`
+
+Returns a `Date` for the 1st of the month:
+
+```ts
+firstDayOfMonth(2026, 9); // Tue Sep 01 2026
+```
+
+### `lastDayOfMonth(year, month): Date`
+
+Returns a `Date` for the last day of the month:
+
+```ts
+lastDayOfMonth(2026, 2); // Sat Feb 28 2026 (no leap year)
+lastDayOfMonth(2028, 2); // Tue Feb 29 2028 (leap year)
+```
+
+### `isDateInRange(date, range?): boolean`
+
+Returns `true` if `date` falls within `range` (inclusive). Returns `false` when `range` is `undefined`.
+
+Throws `RangeError` when `range.from` is after `range.to`, or when any date is invalid.
+
+### `isSameDay(a, b): boolean`
+
+Compares dates by year, month, and day only (ignores time component). Throws `RangeError` when either date is invalid.
+
+### `getMonthRange(from, to): { year: number; month: number }[]`
+
+Returns the list of all months from `from` to `to` (inclusive):
+
+```ts
+getMonthRange(new Date(2026, 5, 1), new Date(2026, 8, 30));
+// [{ year: 2026, month: 6 }, { year: 2026, month: 7 },
+//  { year: 2026, month: 8 }, { year: 2026, month: 9 }]
+```
+
+Throws `RangeError` when `from` is after `to`, or when either date is invalid.
+
+### `createDate(year, monthIndex, day): Date`
+
+Creates a local `Date` at `00:00:00` without the `new Date(year, ...)` 1900-interpretation for years `0`–`99`. `monthIndex` is 0-based like `Date`.
+
+### `assertValidDate(date): void`
+
+Throws `RangeError` when `date` is not a `Date` instance or is an `Invalid Date`.
+
+## Input validation
+
+All functions validate their inputs and throw `RangeError` on invalid values instead of silently producing wrong results:
+
+| Input | Accepted range | Example of invalid input |
+| :--- | :--- | :--- |
+| `year` | integer `1`–`9999` | `0`, `-1`, `10000`, `2026.5`, `NaN` |
+| `month` | integer `1`–`12` | `0`, `13`, `2.5`, `NaN` |
+| `weekStart` | `"sunday"` \| `"monday"` | `"tuesday"` |
+| `locale` | `"en"` \| `"ja"` \| `"es"` \| `"de"` \| `"fr"` \| `"ko"` \| `"zh"` | `"xx"` |
+| `range` | `from <= to`, valid `Date`s | reversed or invalid dates |
+
+> **Note:** `new Date(year, ...)` interprets years `0`–`99` as `1900 + year`. The library avoids this by using `setFullYear` internally (`createDate`), so `firstDayOfMonth(50, 9)` correctly returns the year `50` — but you still cannot pass year `0` or `10000`.
+
+## Exports
+
+```ts
+// Types
+import type {
+  CalendarOptions,
+  CalendarRangeOptions,
+  CalendarYearOptions,
+  HighlightStyle,
+  Locale,
+  RenderMonthOptions,
+  WeekStart,
+} from "@typescript-calendar-lib/core";
+
+// Values
+import {
+  LOCALES,
+  MAX_YEAR,
+  MIN_YEAR,
+  assertValidDate,
+  buildMonthGrid,
+  createDate,
+  firstDayOfMonth,
+  getMonthName,
+  getMonthRange,
+  getWeekdayHeaders,
+  isDateInRange,
+  isSameDay,
+  lastDayOfMonth,
+} from "@typescript-calendar-lib/core";
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+//#region src/types.d.ts
+type Locale = "en" | "ja" | "es" | "de" | "fr" | "ko" | "zh";
+type WeekStart = "sunday" | "monday";
+type HighlightStyle = "bracket" | "reverse";
+interface BaseCalendarOptions {
+  locale?: Locale;
+  weekStart?: WeekStart;
+  highlight?: Date;
+  highlightStyle?: HighlightStyle;
+  range?: {
+    from: Date;
+    to: Date;
+  };
+  color?: boolean;
+}
+interface CalendarOptions extends BaseCalendarOptions {
+  year: number;
+  month: number;
+}
+interface CalendarYearOptions extends BaseCalendarOptions {
+  year: number;
+}
+interface CalendarRangeOptions extends BaseCalendarOptions {
+  from: Date;
+  to: Date;
+}
+interface RenderMonthOptions extends BaseCalendarOptions {}
+//#endregion
+//#region src/locale.d.ts
+interface LocaleData {
+  months: readonly string[];
+  weekdays: readonly string[];
+  weekdaysShort: readonly string[];
+  weekdaysMonday: readonly string[];
+  weekdaysMondayShort: readonly string[];
+}
+export declare const LOCALES: Record<Locale, LocaleData>;
+export declare function getWeekdayHeaders(locale: Locale, weekStart: WeekStart): readonly string[];
+export declare function getMonthName(locale: Locale, month: number): string;
+//#endregion
+//#region src/utils.d.ts
+interface CalendarCellState {
+  isWeekend: boolean;
+  isToday: boolean;
+  isHighlight: boolean;
+  isInRange: boolean;
+}
+/** 月初日（1日）を返す */
+export declare function firstDayOfMonth(year: number, month: number): Date;
+/** 月末日を返す */
+export declare function lastDayOfMonth(year: number, month: number): Date;
+/**
+ * 月の日付グリッドを生成する（6行×7列）
+ * 各セルは日数（1-31）または null（空欄）
+ */
+export declare function buildMonthGrid(year: number, month: number, weekStart: WeekStart): (number | null)[][];
+/** 日付が範囲内に含まれるか */
+export declare function isDateInRange(date: Date, range?: {
+  from: Date;
+  to: Date;
+}): boolean;
+/** 日付が今日と一致するか（日付のみ比較） */
+export declare function isSameDay(a: Date, b: Date): boolean;
+/** 日付セルの表示状態を計算する */
+export declare function getCalendarCellState(date: Date, options?: {
+  today?: Date;
+  highlight?: Date;
+  range?: {
+    from: Date;
+    to: Date;
+  };
+}): CalendarCellState;
+/** 日付が範囲の開始年から終了年までの月リストを返す */
+export declare function getMonthRange(from: Date, to: Date): {
+  year: number;
+  month: number;
+}[];
+/** グレゴリオ暦のうるう年判定（4で割れるが100では割れない、または400で割れる） */
+export declare function isLeapYear(year: number): boolean;
+/** 月の日数（1-31）を返す */
+export declare function daysInMonth(year: number, month: number): number;
+//#endregion
+//#region src/validation.d.ts
+/** サポートする年の最小値（JS Date は 0-99 を 1900+年 と解釈するため 1 から） */
+export declare const MIN_YEAR = 1;
+/** サポートする年の最大値 */
+export declare const MAX_YEAR = 9999;
+/** Date が有効（Invalid Date でない）ことを検証する */
+export declare function assertValidDate(date: Date): void;
+/**
+ * ローカルの指定日 00:00:00 を生成する。
+ * `new Date(year, ...)` は year 0-99 を 1900+year と解釈するため、
+ * setFullYear を使って year 0-99 も正しく扱えるようにする。
+ *
+ * - year は 1-9999、monthIndex は 0-12、day は 0-31 の整数である必要がある（それ以外は RangeError）
+ * - monthIndex 12 は翌年1月（`new Date` と同じロールオーバー。lastDayOfMonth が 12月の月末取得に使う）
+ * - day 0 は前月の月末（`new Date` と同じ規則）
+ * - day がその月の日数を超える場合は翌月にロールする（`new Date` と同じ挙動）
+ */
+export declare function createDate(year: number, monthIndex: number, day: number): Date;
+//#endregion
+export type { CalendarCellState, CalendarOptions, CalendarRangeOptions, CalendarYearOptions, HighlightStyle, Locale, LocaleData, RenderMonthOptions, WeekStart };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,346 @@
+//#region src/validation.ts
+/** サポートする年の最小値（JS Date は 0-99 を 1900+年 と解釈するため 1 から） */
+const MIN_YEAR = 1;
+/** サポートする年の最大値 */
+const MAX_YEAR = 9999;
+/** 値が min-max の整数であることを検証する（不正なら RangeError） */
+function assertIntegerInRange(name, value, min, max) {
+	if (!Number.isInteger(value) || value < min || value > max) throw new RangeError(`Invalid ${name}: ${value} (expected an integer between ${min} and ${max})`);
+}
+/** 年が 1-9999 の整数であることを検証する */
+function assertValidYear(year) {
+	assertIntegerInRange("year", year, 1, MAX_YEAR);
+}
+/** 月が 1-12 の整数であることを検証する */
+function assertValidMonth(month) {
+	assertIntegerInRange("month", month, 1, 12);
+}
+/** 年の組み合わせ（year と month）を検証する */
+function assertValidYearMonth(year, month) {
+	assertValidYear(year);
+	assertValidMonth(month);
+}
+/** 週の開始曜日を検証する */
+function assertValidWeekStart(weekStart) {
+	if (weekStart !== "sunday" && weekStart !== "monday") throw new RangeError(`Invalid weekStart: "${weekStart}" (expected "sunday" or "monday")`);
+}
+/** Date が有効（Invalid Date でない）ことを検証する */
+function assertValidDate(date) {
+	if (!(date instanceof Date) || Number.isNaN(date.getTime())) throw new RangeError(`Invalid Date: ${String(date)}`);
+}
+/**
+* ローカルの指定日 00:00:00 を生成する。
+* `new Date(year, ...)` は year 0-99 を 1900+year と解釈するため、
+* setFullYear を使って year 0-99 も正しく扱えるようにする。
+*
+* - year は 1-9999、monthIndex は 0-12、day は 0-31 の整数である必要がある（それ以外は RangeError）
+* - monthIndex 12 は翌年1月（`new Date` と同じロールオーバー。lastDayOfMonth が 12月の月末取得に使う）
+* - day 0 は前月の月末（`new Date` と同じ規則）
+* - day がその月の日数を超える場合は翌月にロールする（`new Date` と同じ挙動）
+*/
+function createDate(year, monthIndex, day) {
+	assertValidYear(year);
+	assertIntegerInRange("monthIndex", monthIndex, 0, 12);
+	assertIntegerInRange("day", day, 0, 31);
+	const date = /* @__PURE__ */ new Date(0);
+	date.setHours(0, 0, 0, 0);
+	date.setFullYear(year, monthIndex, day);
+	return date;
+}
+//#endregion
+//#region src/locale.ts
+/** 月曜始まりの配列は日曜始まりの配列を前ローテーションして生成する */
+function makeLocale(months, weekdays, weekdaysShort = weekdays) {
+	const rotate = (arr) => [...arr.slice(1), arr[0]];
+	return {
+		months,
+		weekdays,
+		weekdaysShort,
+		weekdaysMonday: rotate(weekdays),
+		weekdaysMondayShort: rotate(weekdaysShort)
+	};
+}
+const LOCALES = {
+	en: makeLocale([
+		"January",
+		"February",
+		"March",
+		"April",
+		"May",
+		"June",
+		"July",
+		"August",
+		"September",
+		"October",
+		"November",
+		"December"
+	], [
+		"Sun",
+		"Mon",
+		"Tue",
+		"Wed",
+		"Thu",
+		"Fri",
+		"Sat"
+	], [
+		"Su",
+		"Mo",
+		"Tu",
+		"We",
+		"Th",
+		"Fr",
+		"Sa"
+	]),
+	ja: makeLocale([
+		"1月",
+		"2月",
+		"3月",
+		"4月",
+		"5月",
+		"6月",
+		"7月",
+		"8月",
+		"9月",
+		"10月",
+		"11月",
+		"12月"
+	], [
+		"日",
+		"月",
+		"火",
+		"水",
+		"木",
+		"金",
+		"土"
+	]),
+	es: makeLocale([
+		"enero",
+		"febrero",
+		"marzo",
+		"abril",
+		"mayo",
+		"junio",
+		"julio",
+		"agosto",
+		"septiembre",
+		"octubre",
+		"noviembre",
+		"diciembre"
+	], [
+		"dom",
+		"lun",
+		"mar",
+		"mié",
+		"jue",
+		"vie",
+		"sáb"
+	], [
+		"do",
+		"lu",
+		"ma",
+		"mi",
+		"ju",
+		"vi",
+		"sá"
+	]),
+	de: makeLocale([
+		"Januar",
+		"Februar",
+		"März",
+		"April",
+		"Mai",
+		"Juni",
+		"Juli",
+		"August",
+		"September",
+		"Oktober",
+		"November",
+		"Dezember"
+	], [
+		"So",
+		"Mo",
+		"Di",
+		"Mi",
+		"Do",
+		"Fr",
+		"Sa"
+	]),
+	fr: makeLocale([
+		"janvier",
+		"février",
+		"mars",
+		"avril",
+		"mai",
+		"juin",
+		"juillet",
+		"août",
+		"septembre",
+		"octobre",
+		"novembre",
+		"décembre"
+	], [
+		"dim.",
+		"lun.",
+		"mar.",
+		"mer.",
+		"jeu.",
+		"ven.",
+		"sam."
+	], [
+		"di",
+		"lu",
+		"ma",
+		"me",
+		"je",
+		"ve",
+		"sa"
+	]),
+	ko: makeLocale([
+		"1월",
+		"2월",
+		"3월",
+		"4월",
+		"5월",
+		"6월",
+		"7월",
+		"8월",
+		"9월",
+		"10월",
+		"11월",
+		"12월"
+	], [
+		"일",
+		"월",
+		"화",
+		"수",
+		"목",
+		"금",
+		"토"
+	]),
+	zh: makeLocale([
+		"一月",
+		"二月",
+		"三月",
+		"四月",
+		"五月",
+		"六月",
+		"七月",
+		"八月",
+		"九月",
+		"十月",
+		"十一月",
+		"十二月"
+	], [
+		"日",
+		"一",
+		"二",
+		"三",
+		"四",
+		"五",
+		"六"
+	])
+};
+/** ロケールデータを取得する（未知のロケールは RangeError） */
+function getLocaleData(locale) {
+	const data = LOCALES[locale];
+	if (data === void 0) throw new RangeError(`Invalid locale: "${locale}"`);
+	return data;
+}
+function getWeekdayHeaders(locale, weekStart) {
+	assertValidWeekStart(weekStart);
+	const data = getLocaleData(locale);
+	return weekStart === "monday" ? data.weekdaysMonday : data.weekdays;
+}
+function getMonthName(locale, month) {
+	assertValidMonth(month);
+	return getLocaleData(locale).months[month - 1];
+}
+//#endregion
+//#region src/utils.ts
+/** 月初日（1日）を返す */
+function firstDayOfMonth(year, month) {
+	assertValidYearMonth(year, month);
+	return createDate(year, month - 1, 1);
+}
+/** 月末日を返す */
+function lastDayOfMonth(year, month) {
+	assertValidYearMonth(year, month);
+	return createDate(year, month, 0);
+}
+/**
+* 月の日付グリッドを生成する（6行×7列）
+* 各セルは日数（1-31）または null（空欄）
+*/
+function buildMonthGrid(year, month, weekStart) {
+	assertValidYearMonth(year, month);
+	assertValidWeekStart(weekStart);
+	const daysInMonth = lastDayOfMonth(year, month).getDate();
+	let skip = firstDayOfMonth(year, month).getDay();
+	if (weekStart === "monday") skip = (skip + 6) % 7;
+	const grid = [];
+	let day = 1;
+	for (let week = 0; week < 6; week++) {
+		const row = [];
+		for (let col = 0; col < 7; col++) if (day > daysInMonth || week === 0 && col < skip) row.push(null);
+		else row.push(day++);
+		grid.push(row);
+	}
+	return grid;
+}
+/** 範囲（from/to）が有効であることを検証する */
+function assertValidRange(from, to) {
+	assertValidDate(from);
+	assertValidDate(to);
+	if (from.getTime() > to.getTime()) throw new RangeError("Invalid range: from must not be after to");
+}
+/** 日付が範囲内に含まれるか */
+function isDateInRange(date, range) {
+	if (!range) return false;
+	assertValidRange(range.from, range.to);
+	assertValidDate(date);
+	const time = date.getTime();
+	return time >= range.from.getTime() && time <= range.to.getTime();
+}
+/** 日付が今日と一致するか（日付のみ比較） */
+function isSameDay(a, b) {
+	assertValidDate(a);
+	assertValidDate(b);
+	return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
+}
+/** 日付セルの表示状態を計算する */
+function getCalendarCellState(date, options = {}) {
+	assertValidDate(date);
+	return {
+		isWeekend: date.getDay() === 0 || date.getDay() === 6,
+		isToday: options.today !== void 0 && isSameDay(date, options.today),
+		isHighlight: options.highlight !== void 0 && isSameDay(date, options.highlight),
+		isInRange: options.range !== void 0 && isDateInRange(date, options.range)
+	};
+}
+/** 日付が範囲の開始年から終了年までの月リストを返す */
+function getMonthRange(from, to) {
+	assertValidRange(from, to);
+	const start = from.getFullYear() * 12 + from.getMonth();
+	const end = to.getFullYear() * 12 + to.getMonth();
+	return Array.from({ length: end - start + 1 }, (_, i) => {
+		const n = start + i;
+		return {
+			year: Math.floor(n / 12),
+			month: n % 12 + 1
+		};
+	});
+}
+/** グレゴリオ暦のうるう年判定（4で割れるが100では割れない、または400で割れる） */
+function isLeapYear(year) {
+	assertValidYear(year);
+	return year % 4 === 0 && year % 100 !== 0 || year % 400 === 0;
+}
+/** 月の日数（1-31）を返す */
+function daysInMonth(year, month) {
+	assertValidYearMonth(year, month);
+	return lastDayOfMonth(year, month).getDate();
+}
+//#endregion
+export { LOCALES, MAX_YEAR, MIN_YEAR, assertValidDate, buildMonthGrid, createDate, daysInMonth, firstDayOfMonth, getCalendarCellState, getMonthName, getMonthRange, getWeekdayHeaders, isDateInRange, isLeapYear, isSameDay, lastDayOfMonth };
+
+//# sourceMappingURL=index.js.map