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

package/src/style.css

@@ -0,0 +1,388 @@
+/* calendar-ui 的默认皮肤：所有颜色/尺寸都走 CSS 变量，外部改 .cui 即可换主题 */
+.cui {
+  --cui-bg: #ffffff;
+  --cui-fg: #1f2328;
+  --cui-muted: #8b949e;
+  --cui-border: #e6e8eb;
+  --cui-accent: #2563eb;
+  --cui-accent-fg: #ffffff;
+  --cui-rest: #e5484d;
+  --cui-hover: #f3f4f6;
+  --cui-radius: 10px;
+
+  color-scheme: light;
+  box-sizing: border-box;
+  width: 100%;
+  max-width: 420px;
+  overflow: hidden;
+  padding: 12px;
+  border: 1px solid var(--cui-border);
+  border-radius: var(--cui-radius);
+  background: var(--cui-bg);
+  color: var(--cui-fg);
+  font-family: system-ui, -apple-system, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
+  font-size: 14px;
+  line-height: 1.4;
+}
+
+/* 双月范围视图 */
+.cui--range {
+  max-width: 900px;
+}
+
+.cui__months {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 16px;
+}
+
+.cui__month {
+  min-width: 0;
+}
+
+@media (max-width: 720px) {
+  .cui__months {
+    grid-template-columns: minmax(0, 1fr);
+  }
+}
+
+/* 显式深色 */
+.cui[data-theme="dark"] {
+  --cui-bg: #161b22;
+  --cui-fg: #e6edf3;
+  --cui-muted: #8b949e;
+  --cui-border: #30363d;
+  --cui-accent: #1f6feb;
+  --cui-accent-fg: #ffffff;
+  --cui-rest: #ff7b72;
+  --cui-hover: #21262d;
+
+  color-scheme: dark;
+}
+
+/* auto：优先跟随最近的 data-theme="dark" */
+[data-theme="dark"] .cui[data-theme="auto"] {
+  --cui-bg: #161b22;
+  --cui-fg: #e6edf3;
+  --cui-muted: #8b949e;
+  --cui-border: #30363d;
+  --cui-accent: #1f6feb;
+  --cui-accent-fg: #ffffff;
+  --cui-rest: #ff7b72;
+  --cui-hover: #21262d;
+
+  color-scheme: dark;
+}
+
+/* auto 且没有 data-theme 时跟随系统 */
+@media (prefers-color-scheme: dark) {
+  .cui[data-theme="auto"] {
+    --cui-bg: #161b22;
+    --cui-fg: #e6edf3;
+    --cui-muted: #8b949e;
+    --cui-border: #30363d;
+    --cui-accent: #1f6feb;
+    --cui-accent-fg: #ffffff;
+    --cui-rest: #ff7b72;
+    --cui-hover: #21262d;
+
+    color-scheme: dark;
+  }
+
+  /* 外层明确 light 时，系统深色不覆盖 */
+  [data-theme="light"] .cui[data-theme="auto"] {
+    --cui-bg: #ffffff;
+    --cui-fg: #1f2328;
+    --cui-muted: #8b949e;
+    --cui-border: #e6e8eb;
+    --cui-accent: #2563eb;
+    --cui-accent-fg: #ffffff;
+    --cui-rest: #e5484d;
+    --cui-hover: #f3f4f6;
+
+    color-scheme: light;
+  }
+}
+
+.cui *,
+.cui *::before,
+.cui *::after {
+  box-sizing: border-box;
+}
+
+/* 头部：上个月 / 年月标题 / 下个月 */
+.cui__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 4px 2px 10px;
+}
+
+.cui__title {
+  font-weight: 600;
+  font-size: 15px;
+}
+
+.cui__nav {
+  width: 30px;
+  height: 30px;
+  border: 1px solid var(--cui-border);
+  border-radius: 8px;
+  background: transparent;
+  color: var(--cui-fg);
+  font-size: 16px;
+  line-height: 1;
+  cursor: pointer;
+}
+
+.cui__nav:hover {
+  background: var(--cui-hover);
+}
+
+.cui__nav:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.cui__nav:disabled:hover {
+  background: transparent;
+}
+
+.cui__nav:focus-visible,
+.cui__day:focus-visible {
+  outline: 2px solid var(--cui-accent);
+  outline-offset: 1px;
+}
+
+/* 星期表头 */
+.cui__weekdays {
+  display: grid;
+  grid-template-columns: repeat(7, minmax(0, 1fr));
+  gap: 4px;
+}
+
+/* 6 行日期；折叠时按行收起，节点仍然复用 */
+.cui__grid {
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+  contain: layout paint;
+}
+
+.cui__week {
+  display: grid;
+  min-height: 0;
+  margin-bottom: 4px;
+  overflow: hidden;
+  grid-template-columns: repeat(7, minmax(0, 1fr));
+  gap: 4px;
+  opacity: 1;
+}
+
+.cui__week:last-child {
+  margin-bottom: 0;
+}
+
+/* 折叠动画由 JS 按真实行高驱动（见 components/grid.ts），这里只负责最终状态 */
+.cui__week.is-collapsed-hidden {
+  height: 0;
+  margin-bottom: 0;
+  opacity: 0;
+  pointer-events: none;
+}
+
+.cui__week[hidden] {
+  display: none;
+}
+
+.cui__viewport {
+  position: relative;
+  min-width: 0;
+  overflow: hidden;
+}
+
+.cui__grid.is-month-clone {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+
+/* 只在动画期间提升为合成层，动画结束后随类名一起移除 */
+.cui__grid.is-month-clone,
+.cui__grid.is-month-in-next,
+.cui__grid.is-month-in-prev {
+  will-change: transform;
+}
+
+.cui--no-animation .cui__grid,
+.cui--no-animation .cui__week {
+  transition: none;
+  animation: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .cui__grid,
+  .cui__week {
+    transition: none;
+    animation: none;
+  }
+}
+
+.cui__weekday {
+  padding: 4px 0;
+  color: var(--cui-muted);
+  font-size: 12px;
+  text-align: center;
+}
+
+/* 日期格 */
+.cui__day {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 2px;
+  min-height: 46px;
+  padding: 4px 2px;
+  border: 1px solid transparent;
+  border-radius: 8px;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+}
+
+.cui__day:hover {
+  background: var(--cui-hover);
+}
+
+.cui__day-num {
+  font-size: 15px;
+  font-weight: 500;
+  line-height: 1.1;
+}
+
+/* 周末：日期数字固定用节假日红（--cui-rest），不由节假日数据决定 */
+.cui__day.is-weekend .cui__day-num {
+  color: var(--cui-rest);
+}
+
+/* 选中时数字跟随反白色，避免红底红字 */
+.cui__day.is-selected .cui__day-num {
+  color: currentColor;
+}
+
+.cui__day-sub {
+  max-width: 100%;
+  overflow: hidden;
+  color: var(--cui-muted);
+  font-size: 11px;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+/* 左上角的休 / 班标记 */
+.cui__day-tag {
+  position: absolute;
+  top: 3px;
+  left: 4px;
+  font-size: 10px;
+  font-weight: 600;
+  line-height: 1;
+  pointer-events: none;
+}
+
+.cui__day-tag[hidden] {
+  display: none;
+}
+
+.cui__day-tag[data-tone="rest"] {
+  color: var(--cui-rest);
+}
+
+.cui__day-tag[data-tone="work"] {
+  color: var(--cui-accent);
+}
+
+.cui__day.is-selected .cui__day-tag {
+  color: currentColor;
+  opacity: 0.9;
+}
+
+/* 状态 */
+.cui__day.is-outside {
+  opacity: 0.35;
+}
+
+.cui__day.is-disabled,
+.cui__day:disabled {
+  opacity: 0.35;
+  cursor: not-allowed;
+}
+
+.cui__day.is-disabled:hover,
+.cui__day:disabled:hover {
+  background: transparent;
+}
+
+.cui__day[data-tone="rest"] .cui__day-sub {
+  color: var(--cui-rest);
+}
+
+.cui__day.is-today {
+  border-color: var(--cui-accent);
+}
+
+.cui__day.is-selected {
+  background: var(--cui-accent);
+  color: var(--cui-accent-fg);
+}
+
+.cui__day.is-in-range:not(.is-selected) {
+  background: color-mix(in srgb, var(--cui-accent) 14%, transparent);
+}
+
+.cui__day.is-in-range:hover:not(.is-selected) {
+  background: color-mix(in srgb, var(--cui-accent) 22%, transparent);
+}
+
+.cui__day.is-selected .cui__day-sub {
+  color: currentColor;
+  opacity: 0.85;
+}
+
+/* 折叠开关：始终只有一个按钮，箭头随状态切换 */
+.cui__collapse {
+  display: flex;
+  width: 100%;
+  align-items: center;
+  justify-content: center;
+  margin-top: 8px;
+  padding: 2px 0;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--cui-muted);
+  font: inherit;
+  font-size: 14px;
+  line-height: 1;
+  cursor: pointer;
+}
+
+.cui__collapse:hover {
+  color: var(--cui-fg);
+  background: var(--cui-hover);
+}
+
+.cui__collapse:focus-visible {
+  outline: 2px solid var(--cui-accent);
+  outline-offset: 1px;
+}
+
+/* 隐藏状态：类选择器里的 display 会盖掉 [hidden] 的默认样式，这里显式补上 */
+.cui[hidden],
+.cui__header[hidden] {
+  display: none;
+}

package/src/types/calendar.ts

@@ -0,0 +1,267 @@
+import type { CalendarLocale, CalendarLocaleName } from "./locale";
+
+/** 一周从哪天开始：0 为周日，1 为周一 */
+export type WeekStartsOn = 0 | 1;
+
+/** 主题：light / dark 显式指定，auto 跟随最近的 data-theme 或系统偏好 */
+export type CalendarTheme = "light" | "dark" | "auto";
+
+/**
+ * 外部传入的日期
+ *
+ * 支持 Date，或本地日期字符串：
+ * `2026-10-01`、`2026-10-1`、`2026/10/01`、`2026/10/1`。
+ */
+export type CalendarDateInput = Date | string;
+
+/** 选择模式：单选 / 范围 */
+export type CalendarMode = "single" | "range";
+
+/** 范围选择结果，start/end 为 null 表示还没选完 */
+export interface CalendarRange {
+  start: Date | null;
+  end: Date | null;
+}
+
+/** 自定义副标题：返回 null/undefined 时回退到 adapter 的 subtitle */
+export type SubtitleRenderer = (day: CalendarDate) => string | null | undefined;
+
+/** 翻月滑动动画；传了 slide 就开启，不传就是直接切换 */
+export interface SlideAnimationOptions {
+  /** 动画时长，单位 ms，默认 220 */
+  duration?: number;
+  /** 缓动函数，默认 "ease" */
+  easing?: string;
+}
+
+/** 折叠配置；传了 collapse 就显示底部折叠箭头并开启过渡 */
+export interface CollapseAnimationOptions {
+  /** 折叠时长，单位 ms，默认 200 */
+  duration?: number;
+  /** 缓动函数，默认 "ease" */
+  easing?: string;
+  /** 初始是否折叠，默认 false（展开） */
+  defaultCollapsed?: boolean;
+}
+
+/** 动画配置；整块不传时不做任何动画，也不显示折叠箭头 */
+export interface CalendarAnimationOptions {
+  /** 翻月滑动；`{}` 表示用默认时长和缓动 */
+  slide?: SlideAnimationOptions;
+  /** 折叠；`{}` 表示启用折叠并默认展开 */
+  collapse?: CollapseAnimationOptions;
+}
+
+/** 规范后的年月 */
+export interface YearMonth {
+  year: number;
+  /** 1-12 */
+  month: number;
+}
+
+/** 日历格的公历日期部分 */
+export interface CalendarDate {
+  /** 公历年 */
+  year: number;
+  /** 公历月，1-12 */
+  month: number;
+  /** 公历日 */
+  day: number;
+  /** 该格对应的日期对象（本地时区） */
+  date: Date;
+  /** 是否属于当前展示的月份（false 表示上一月/下一月的补位格） */
+  inCurrentMonth: boolean;
+}
+
+/** 格子左上角的小标记，例如「休」「班」 */
+export interface CalendarBadge {
+  /** 显示文字 */
+  text: string;
+  /** 传给样式的 data-tone，核心不解释具体含义 */
+  tone?: string;
+}
+
+/** 适配器对单个格子的装饰 */
+export interface DayDecoration<TData = unknown> {
+  /** 格子副标题，例如节气、节日、农历日 */
+  subtitle?: string;
+  /** 左上角小标记；不传则不显示 */
+  badge?: CalendarBadge;
+  /** 透传给 onSelect 的数据，核心不解释 */
+  data?: TData;
+  /** 覆盖默认 aria-label；不传时由日期、标记、副标题拼接 */
+  ariaLabel?: string;
+}
+
+/** 每次渲染月视图时传给适配器的上下文 */
+export interface MonthInput {
+  /** 公历年 */
+  year: number;
+  /** 公历月，1-12 */
+  month: number;
+  /** 一周从哪天开始 */
+  weekStartsOn: WeekStartsOn;
+  /** 今天 */
+  today: Date;
+  /** 当前界面语言 */
+  locale: CalendarLocale;
+  /** 固定 42 个日期，包含上下月补位格 */
+  days: readonly CalendarDate[];
+}
+
+/**
+ * 日历适配器
+ *
+ * 核心只认识这个接口，不依赖任何具体的农历/节假日实现。
+ * 第三方可以实现它接入自己的日历数据。
+ */
+export interface CalendarAdapter<TData = unknown> {
+  /** 适配器标识，用于调试和排查 */
+  readonly id: string;
+
+  /**
+   * 生成当前月的 42 个格子的装饰
+   *
+   * 返回数组按索引和 input.days 对齐；没有装饰的位置返回 null。
+   * 每次换月、选中、重新渲染都会调用，适配器应自行缓存重计算。
+   */
+  decorateMonth(input: MonthInput): ReadonlyArray<DayDecoration<TData> | null>;
+}
+
+/** 日历中的一格 */
+export interface CalendarDay<TData = null> extends CalendarDate {
+  /** 是否今天 */
+  isToday: boolean;
+  /** 是否当前选中 */
+  isSelected: boolean;
+  /** 是否被 minDate / maxDate / disabledDates 禁止 */
+  isDisabled: boolean;
+  /** 是否范围起点 */
+  isRangeStart: boolean;
+  /** 是否范围终点 */
+  isRangeEnd: boolean;
+  /** 是否在已选范围内（含起终点） */
+  isInRange: boolean;
+  /** 格子副标题，例如节气、节日、农历日 */
+  subtitle: string;
+  /** 左上角小标记 */
+  badge: CalendarBadge | null;
+  /** 适配器透传的数据 */
+  data: TData | null;
+  /** 无障碍名称 */
+  ariaLabel: string;
+}
+
+/** 自定义头部能拿到的上下文 */
+export interface HeaderRenderContext {
+  /** 当前展示的年 */
+  year: number;
+  /** 当前展示的月，1-12 */
+  month: number;
+  /** 当前语言包 */
+  locale: CalendarLocale;
+  /** 切到上个月 */
+  prevMonth(): void;
+  /** 切到下个月 */
+  nextMonth(): void;
+}
+
+/** 自定义头部渲染函数：返回要放进头部的元素，每次换月都会重新调用 */
+export type HeaderRenderer = (context: HeaderRenderContext) => HTMLElement;
+
+/** 创建日历时的配置 */
+export interface CalendarOptions<TData = null> {
+  /** 初始日期，默认今天；超出约束时夹到最近的可选日期 */
+  initialDate?: CalendarDateInput;
+  /** 最小可选日期（包含） */
+  minDate?: CalendarDateInput;
+  /** 最大可选日期（包含） */
+  maxDate?: CalendarDateInput;
+  /** 禁止选中的日期，按本地年月日比较 */
+  disabledDates?: readonly CalendarDateInput[];
+  /** 选择模式，默认 "single" */
+  mode?: CalendarMode;
+  /** 范围模式下显示的月数，默认 1；设为 2 时显示相邻两个月 */
+  months?: 1 | 2;
+  /** 范围变化时触发 */
+  onRangeChange?: (range: CalendarRange) => void;
+  /** 一周从哪天开始，默认 1（周一） */
+  weekStartsOn?: WeekStartsOn;
+  /** 界面语言：内置 "zh-CN"（默认）/ "en-US"，也可直接传自定义语言包 */
+  locale?: CalendarLocale | CalendarLocaleName;
+  /** 主题，默认 "auto"：跟随最近的 data-theme，没有则跟随系统 */
+  theme?: CalendarTheme;
+  /**
+   * 动画配置
+   *
+   * 不传时翻月直接切换、不显示折叠箭头。传了 `slide` 才开启滑动，
+   * 传了 `collapse` 才显示折叠箭头。
+   */
+  animation?: CalendarAnimationOptions;
+  /** 自定义副标题；优先于 adapter.subtitle，返回 null/undefined 时回退 */
+  subtitle?: SubtitleRenderer;
+  /** 是否显示头部，默认 true */
+  header?: boolean;
+  /** 自定义头部，替换默认的 ‹ 标题 › */
+  renderHeader?: HeaderRenderer;
+  /** 选中某一天时触发 */
+  onSelect?: (day: CalendarDay<TData>) => void;
+  /** 切换月份时触发 */
+  onMonthChange?: (year: number, month: number) => void;
+  /** 日历适配器；不传时就是纯公历 */
+  adapter?: CalendarAdapter<TData>;
+}
+
+/** 返回的实例 */
+export interface CalendarInstance {
+  /** 日历根元素，方便外部定位或再挂样式 */
+  readonly el: HTMLElement;
+  /** 跳到某年某月 */
+  setMonth(year: number, month: number): void;
+  /** 当前展示的年月 */
+  getMonth(): YearMonth;
+  /** 切到上个月 */
+  prevMonth(): void;
+  /** 切到下个月 */
+  nextMonth(): void;
+  /** 选中某个日期 */
+  select(date: CalendarDateInput): void;
+  /** 当前已选范围；单选模式返回 { start: null, end: null } */
+  getRange(): CalendarRange;
+  /** 设置范围；start 为空时清空，end 省略表示只选了起点 */
+  setRange(start: CalendarDateInput | null, end?: CalendarDateInput | null): void;
+  /** 清空范围 */
+  clearRange(): void;
+  /** 当前选中的日期 */
+  getSelected(): Date | null;
+  /** 显示整个日历 */
+  show(): void;
+  /** 隐藏整个日历 */
+  hide(): void;
+  /** 切换整个日历的显示状态 */
+  toggle(): void;
+  /** 整个日历当前是否可见 */
+  isVisible(): boolean;
+  /** 显示头部 */
+  showHeader(): void;
+  /** 隐藏头部 */
+  hideHeader(): void;
+  /** 切换头部的显示状态 */
+  toggleHeader(): void;
+  /** 头部当前是否可见 */
+  isHeaderVisible(): boolean;
+  /** 当前最小可选日期，未设置时为 null */
+  getMinDate(): Date | null;
+  /** 设置最小可选日期，传 null 取消 */
+  setMinDate(date: CalendarDateInput | null): void;
+  /** 当前最大可选日期，未设置时为 null */
+  getMaxDate(): Date | null;
+  /** 设置最大可选日期，传 null 取消 */
+  setMaxDate(date: CalendarDateInput | null): void;
+  /** 当前主题 */
+  getTheme(): CalendarTheme;
+  /** 切换主题，只改 data-theme，不重建 DOM */
+  setTheme(theme: CalendarTheme): void;
+  /** 移除 DOM 与事件监听 */
+  destroy(): void;
+}

package/src/types/components.ts

@@ -0,0 +1,69 @@
+import type { CalendarDay, HeaderRenderer } from "./calendar";
+import type { CalendarLocale } from "./locale";
+
+/** 头部左右切换按钮的入参 */
+export interface NavOptions {
+  /** 按钮上显示的字符，例如 ‹ › */
+  label: string;
+  /** 无障碍名称，例如「上个月」 */
+  ariaLabel: string;
+  onClick: () => void;
+}
+
+/** 头部左右切换按钮的句柄 */
+export interface NavHandle {
+  el: HTMLButtonElement;
+  /** 设置禁用状态，边界月份时使用 */
+  setDisabled(disabled: boolean): void;
+  destroy(): void;
+}
+
+/** 头部的入参 */
+export interface HeaderOptions {
+  /** 初始展示的年 */
+  year: number;
+  /** 初始展示的月 */
+  month: number;
+  /** 界面文案 */
+  locale: CalendarLocale;
+  /** 自定义标题文本；不传时使用 locale.monthTitle */
+  title?: (year: number, month: number) => string;
+  /** 上个月 */
+  onPrev: () => void;
+  /** 下个月 */
+  onNext: () => void;
+  /** 自定义渲染函数，提供时替换默认的 ‹ 标题 › */
+  renderer?: HeaderRenderer;
+}
+
+/** 头部的句柄 */
+export interface HeaderHandle {
+  el: HTMLElement;
+  /** 换月时更新标题或重绘自定义头部 */
+  update(year: number, month: number): void;
+  /** 更新左右按钮的禁用状态 */
+  setNavDisabled(prevDisabled: boolean, nextDisabled: boolean): void;
+  destroy(): void;
+}
+
+/** 日期网格的入参 */
+export interface GridOptions<TData = null> {
+  /** 点中某一格时触发 */
+  onSelect: (day: CalendarDay<TData>) => void;
+}
+
+/** 日期网格的句柄 */
+export interface GridHandle<TData = null> {
+  el: HTMLElement;
+  /** 换月：更新格子文本与状态（节点复用，不重新创建） */
+  render(days: CalendarDay<TData>[]): void;
+  /** 只更新选中/今天等状态类，不动文本 */
+  updateState(days: CalendarDay<TData>[]): void;
+  /**
+   * 折叠时只显示指定行；传 null 显示全部 6 行
+   *
+   * animate 为 false 时直接切换（翻月时使用），避免和位移动画同时触发布局。
+   */
+  setVisibleRows(rows: readonly number[] | null, animate?: boolean): void;
+  destroy(): void;
+}