@sanguo-dev/calendar-ui 0.0.0-stage → 0.0.2

package/src/types/index.ts

@@ -0,0 +1,32 @@
+export type {
+  CalendarAdapter,
+  CalendarAnimationOptions,
+  CalendarBadge,
+  CalendarDate,
+  CalendarDateInput,
+  CalendarDay,
+  CalendarInstance,
+  CalendarMode,
+  CalendarOptions,
+  CalendarRange,
+  CalendarTheme,
+  CollapseAnimationOptions,
+  DayDecoration,
+  HeaderRenderContext,
+  HeaderRenderer,
+  MonthInput,
+  SlideAnimationOptions,
+  SubtitleRenderer,
+  WeekStartsOn,
+  YearMonth,
+} from "./calendar";
+export type {
+  GridHandle,
+  GridOptions,
+  HeaderHandle,
+  HeaderOptions,
+  NavHandle,
+  NavOptions,
+} from "./components";
+export type { CalendarLocale, CalendarLocaleName } from "./locale";
+export type { BuildDaysOptions } from "./utils";

package/src/types/locale.ts

@@ -0,0 +1,26 @@
+/**
+ * 语言包
+ *
+ * 只负责日历自身的界面文字；农历、节气、节日等业务文案由适配器提供。
+ */
+export interface CalendarLocale {
+  /** 语言标签，例如 "zh-CN"，仅用于调试与覆盖 */
+  name: string;
+  /** 一周七天的短名，下标 0 为周日 */
+  weekdays: readonly string[];
+  /** 一周七天的全名，下标 0 为周日，用于 title 提示 */
+  weekdaysLong: readonly string[];
+  /** 头部年月标题 */
+  monthTitle(year: number, month: number): string;
+  /** 上个月按钮的无障碍名称 */
+  prevMonth: string;
+  /** 下个月按钮的无障碍名称 */
+  nextMonth: string;
+  /** 折叠按钮的无障碍名称；不传时使用内置文案 */
+  collapse?: string;
+  /** 展开按钮的无障碍名称；不传时使用内置文案 */
+  expand?: string;
+}
+
+/** 内置语言包的名称，可直接传给 CalendarOptions.locale */
+export type CalendarLocaleName = "zh-CN" | "en-US";

package/src/types/utils.ts

@@ -0,0 +1,28 @@
+import type { CalendarAdapter, SubtitleRenderer, WeekStartsOn } from "./calendar";
+import type { CalendarLocale } from "./locale";
+
+/** buildDays 的入参 */
+export interface BuildDaysOptions<TData = null> {
+  /** 公历年 */
+  year: number;
+  /** 公历月，1-12 */
+  month: number;
+  /** 一周从哪天开始 */
+  weekStartsOn: WeekStartsOn;
+  /** 今天 */
+  today: Date;
+  /** 当前选中的日期，未选中传 null */
+  selected: Date | null;
+  /** 范围起点 */
+  rangeStart?: Date | null;
+  /** 范围终点 */
+  rangeEnd?: Date | null;
+  /** 当前界面语言 */
+  locale: CalendarLocale;
+  /** 判断某个日期是否不可选；不传表示全部都可用 */
+  isDisabled?: (date: Date) => boolean;
+  /** 自定义副标题，优先于 adapter */
+  subtitle?: SubtitleRenderer;
+  /** 日历适配器；不传时就是纯公历 */
+  adapter?: CalendarAdapter<TData>;
+}

package/src/utils/date.ts

@@ -0,0 +1,82 @@
+import type { CalendarDateInput, YearMonth } from "../types";
+
+/** 日期字符串：YYYY-M-D，分隔符必须一致 */
+const DATE_INPUT_PATTERN = /^(\d{4})([-/])(\d{1,2})\2(\d{1,2})$/;
+
+/** 去掉时分秒，只保留本地年月日 */
+export const toDateOnly = function (date: Date): Date {
+  return new Date(date.getFullYear(), date.getMonth(), date.getDate());
+};
+
+/**
+ * 解析用户传入的日期
+ *
+ * 支持 Date，以及 `2026-10-01`、`2026-10-1`、`2026/10/01`、`2026/10/1`。
+ * 不交给 `new Date(string)`，避免时区/格式歧义。
+ */
+export const parseDateInput = function (value: CalendarDateInput, path = "date"): Date {
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) {
+      throw new TypeError(`[calendar-ui] ${path} 必须是有效的 Date`);
+    }
+    return toDateOnly(value);
+  }
+
+  if (typeof value !== "string") {
+    throw new TypeError(`[calendar-ui] ${path} 必须是 Date 或 YYYY-MM-DD / YYYY/MM/DD 字符串`);
+  }
+
+  const match = DATE_INPUT_PATTERN.exec(value.trim());
+  if (!match) {
+    throw new TypeError(
+      `[calendar-ui] ${path} 必须是 Date 或 YYYY-MM-DD / YYYY/MM/DD 字符串，收到 ${JSON.stringify(value)}`,
+    );
+  }
+
+  const year = Number(match[1]);
+  const month = Number(match[3]);
+  const day = Number(match[4]);
+  if (month < 1 || month > 12) {
+    throw new RangeError(`[calendar-ui] ${path} 月份必须在 1-12 之间`);
+  }
+
+  const date = new Date(0);
+  date.setHours(0, 0, 0, 0);
+  date.setFullYear(year, month - 1, day);
+  if (date.getFullYear() !== year || date.getMonth() + 1 !== month || date.getDate() !== day) {
+    throw new RangeError(`[calendar-ui] ${path} 不是有效日期: ${value}`);
+  }
+  return date;
+};
+
+/** 把日期转成可比较的数字 key：YYYYMMDD */
+export const dateKey = function (date: Date): number {
+  return date.getFullYear() * 10000 + (date.getMonth() + 1) * 100 + date.getDate();
+};
+
+/** 加减天数，按本地日历计算 */
+export const addDays = function (date: Date, amount: number): Date {
+  const next = toDateOnly(date);
+  next.setDate(next.getDate() + amount);
+  return next;
+};
+
+/** 比较两个日期，只比年月日 */
+export const compareDay = function (a: Date, b: Date): number {
+  return dateKey(a) - dateKey(b);
+};
+
+/** 同一天（只比年月日，忽略时分秒） */
+export const sameDay = function (a: Date, b: Date): boolean {
+  return (
+    a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate()
+  );
+};
+
+/** 把年月规范成合法值，月份越界时自动进位/退位 */
+export const normalizeMonth = function (year: number, month: number): YearMonth {
+  const date = new Date(year, month - 1, 1);
+  return { year: date.getFullYear(), month: date.getMonth() + 1 };
+};

package/src/utils/days.ts

@@ -0,0 +1,88 @@
+import type { CalendarDate, CalendarDay, DayDecoration, WeekStartsOn } from "../types";
+import type { BuildDaysOptions } from "../types";
+import { compareDay, sameDay } from "./date";
+
+/** 某个年月 1 号是星期几（0 为周日） */
+export const firstWeekdayOf = function (year: number, month: number): number {
+  return new Date(year, month - 1, 1).getDay();
+};
+
+/** 生成 6 行 × 7 列共 42 个公历日期，包含上下月补位格 */
+const buildMonthDates = function (
+  year: number,
+  month: number,
+  weekStartsOn: WeekStartsOn,
+): CalendarDate[] {
+  const offset = (firstWeekdayOf(year, month) - weekStartsOn + 7) % 7;
+  const days: CalendarDate[] = [];
+
+  for (let i = 0; i < 42; i++) {
+    const date = new Date(year, month - 1, i - offset + 1);
+    days.push({
+      year: date.getFullYear(),
+      month: date.getMonth() + 1,
+      day: date.getDate(),
+      date,
+      inCurrentMonth: date.getMonth() + 1 === month && date.getFullYear() === year,
+    });
+  }
+  return days;
+};
+
+/** 生成 42 个格子的数据；今天/选中每次现算，适配器只负责装饰 */
+export const buildDays = function <TData = null>(
+  options: BuildDaysOptions<TData>,
+): CalendarDay<TData>[] {
+  const dates = buildMonthDates(options.year, options.month, options.weekStartsOn);
+  const decorations: ReadonlyArray<DayDecoration<TData> | null> = options.adapter
+    ? options.adapter.decorateMonth({
+        year: options.year,
+        month: options.month,
+        weekStartsOn: options.weekStartsOn,
+        today: options.today,
+        locale: options.locale,
+        days: dates,
+      })
+    : [];
+
+  return dates.map((date, index) => {
+    const decoration = decorations[index] ?? null;
+    const badge = decoration?.badge ?? null;
+    const adapterSubtitle = decoration?.subtitle ?? "";
+    const customSubtitle = options.subtitle?.(date);
+    const subtitle =
+      customSubtitle === null || customSubtitle === undefined ? adapterSubtitle : customSubtitle;
+    const key = `${date.year}-${date.month}-${date.day}`;
+    const isDisabled = options.isDisabled?.(date.date) ?? false;
+    const rangeStart = options.rangeStart ?? null;
+    const rangeEnd = options.rangeEnd ?? null;
+    const isRangeStart = rangeStart !== null && sameDay(date.date, rangeStart);
+    const isRangeEnd = rangeEnd !== null && sameDay(date.date, rangeEnd);
+    const isInRange =
+      rangeStart !== null &&
+      rangeEnd !== null &&
+      compareDay(date.date, rangeStart) >= 0 &&
+      compareDay(date.date, rangeEnd) <= 0;
+
+    return {
+      ...date,
+      isToday: sameDay(date.date, options.today),
+      isSelected:
+        (options.selected !== null && sameDay(date.date, options.selected)) ||
+        isRangeStart ||
+        isRangeEnd,
+      isDisabled,
+      isRangeStart,
+      isRangeEnd,
+      isInRange,
+      subtitle,
+      badge,
+      data: decoration?.data ?? null,
+      ariaLabel:
+        decoration?.ariaLabel ??
+        [key, badge?.text ?? "", subtitle, isDisabled ? "不可选" : ""]
+          .filter((part) => part !== "")
+          .join(" "),
+    };
+  });
+};

package/src/utils/dom.ts

@@ -0,0 +1,11 @@
+/** 简单建节点：文本一律走 textContent，避免节假日名里的特殊字符被当成 HTML */
+export const node = function <K extends keyof HTMLElementTagNameMap>(
+  tag: K,
+  className?: string,
+  text?: string,
+): HTMLElementTagNameMap[K] {
+  const el = document.createElement(tag);
+  if (className) el.className = className;
+  if (text !== undefined) el.textContent = text;
+  return el;
+};

package/src/utils/motion.ts

@@ -0,0 +1,39 @@
+/** 是否开启了「减少动态效果」；jsdom 等环境没有 matchMedia 时当作未开启 */
+export const prefersReducedMotion = function (): boolean {
+  return typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+};
+
+/** 把 CSS 里的时长读成毫秒，支持 `200ms` / `0.2s` / 纯数字；非法值回退 */
+export const parseCssDuration = function (value: string, fallback: number): number {
+  const match = /^\s*(-?\d*\.?\d+)\s*(ms|s)?\s*$/i.exec(value);
+  if (match === null) return fallback;
+
+  const amount = Number(match[1]);
+  if (!Number.isFinite(amount) || amount < 0) return fallback;
+  return match[2]?.toLowerCase() === "s" ? amount * 1000 : amount;
+};
+
+/** 当前元素上的 CSS 变量优先，CSS 变量没有声明时用 JS 选项 */
+export const readCssDuration = function (
+  style: CSSStyleDeclaration,
+  name: string,
+  fallback: number,
+): number {
+  const value = style.getPropertyValue(name).trim();
+  return value === "" ? fallback : parseCssDuration(value, fallback);
+};
+
+export const readCssEasing = function (
+  style: CSSStyleDeclaration,
+  name: string,
+  fallback: string,
+): string {
+  const value = style.getPropertyValue(name).trim();
+  return value === "" ? fallback : value;
+};
+
+/** WAAPI 的 easing 不认非法值会抛错，这里退回到 ease */
+export const normalizeEasing = function (easing: string): string {
+  if (typeof CSS === "undefined" || typeof CSS.supports !== "function") return easing;
+  return CSS.supports("animation-timing-function", easing) ? easing : "ease";
+};