@composy/attendance-core

@composy/attendance-core

框架无关的考勤核心包，提供考勤日历、打卡面板、统计面板、请假面板、状态工具和演示数据生成器。

特性

• 考勤日历：月份切换、回到今天、选中日期、状态图例、排班展示和键盘可访问点击。
• 打卡面板：自动判断上班/下班打卡，支持默认地点、打卡方式、禁用态、打卡记录回调。
• 统计面板：出勤率、准点率、异常次数、工作时长、请假余额。
• 请假面板：假期余额进度、请假记录、审批状态、记录点击回调。
• 样式规范：所有组件 class 使用 ldesign-attendance-* 前缀；颜色使用 packages/color 生成的 --ld-* 变量，尺寸使用 packages/size 生成的 --ld-* 变量。
• 产物：dist、es、esm、lib 四套目录，包含 JS、声明文件和 CSS。

安装

pnpm add @composy/attendance-core

使用

import {
  createAttendanceCalendar,
  generateMonthRecords,
  generateSchedules,
  getCurrentMonth,
} from '@composy/attendance-core'
import '@composy/attendance-core/index.css'

const month = getCurrentMonth()

const calendar = createAttendanceCalendar({
  container: '#calendar',
  month,
  records: generateMonthRecords(month),
  schedules: generateSchedules(month),
  showShift: true,
  selectedDate: `${month}-01`,
  onDateClick(date, record) {
    console.info(date, record)
  },
})

calendar.nextMonth()

公开入口

• @composy/attendance-core：核心 API 与类型。
• @composy/attendance-core/index.css：完整组件样式。
• @composy/attendance-core/style：样式子路径。
• @composy/attendance-core/core/*、theme/*、utils/*、types：按需子路径。

验证

pnpm type-check       # .ldesign/tsconfig.json
pnpm type-check:cjs   # .ldesign/tsconfig.cjs.json
pnpm build            # Builder + 产物归一化和 exports 契约检查
pnpm lint:check       # ESLint 严格检查

相关链接

• @composy/attendance-vue — Vue 3 适配层
• workspace 总览 — 子模块结构与根脚本

License

MIT

状态快照与输入边界

四个 Core 实例都提供 getSnapshot()：

const snapshot = calendar.getSnapshot()
snapshot.records[0]?.clocks.push({ time: '09:00', type: 'clock-in' })
// 修改 snapshot 不会改变日历内部数据

实例会在构造、set*、updateConfig 和事件回调边界复制记录、班次、额度与请假对象。 ClockInPanel.clock() 返回的记录也可以安全交给状态管理器。日期工具会校验初始月份和选中日期， prevMonth/nextMonth 在 0000-01 与 9999-12 边界抛出 RangeError，不会生成不可解析月份。

日历使用 grid/gridcell、aria-selected、aria-current 和可键盘触发的日期单元格；统计与请假额度使用 progressbar 语义，打卡面板提供实时钟表和按钮标签。运行时传入的未知状态、班次或请假类型不会直接进入 CSS class 名称。

组件实例方法

除了各自的 set* 与 updateConfig 外，实例方法还包括：

• AttendanceCalendar.getSnapshot()
• AttendanceStats.getSnapshot()
• ClockInPanel.getSnapshot()、getTodayClocks()
• LeavePanel.getSnapshot()

快照类型 AttendanceCalendarSnapshot、AttendanceStatsSnapshot、ClockInPanelSnapshot 和 LeavePanelSnapshot 会随包导出；clone* 工具适合在 provider、缓存或状态管理器边界显式复制数据。