{"_id":"@coffeefish/beauty-calendar","name":"@coffeefish/beauty-calendar","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@coffeefish/beauty-calendar","version":"0.1.0","description":"A sci-fi styled, drag-to-create calendar component for Vue 3 — day / week / month views with i18n and theme switching.","type":"module","license":"MIT","author":{"name":"coffeefish"},"repository":{"type":"git","url":"git+https://github.com/codeingforcoffee/beauty-calendar.git"},"homepage":"https://github.com/codeingforcoffee/beauty-calendar#readme","bugs":{"url":"https://github.com/codeingforcoffee/beauty-calendar/issues"},"engines":{"node":">=18"},"sideEffects":["**/*.css","**/*.scss"],"publishConfig":{"access":"public"},"keywords":["vue","vue3","calendar","schedule","drag","day-view","week-view","month-view","tech","i18n"],"main":"./dist/beauty-calendar.umd.cjs","module":"./dist/beauty-calendar.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/beauty-calendar.js","require":"./dist/beauty-calendar.umd.cjs"},"./style.css":"./dist/beauty-calendar.css"},"scripts":{"dev":"vite","play":"vite","build":"vite build --config vite.lib.config.ts && vue-tsc --declaration --emitDeclarationOnly -p tsconfig.build.json","build:play":"vite build","preview":"vite preview","type-check":"vue-tsc --noEmit","test":"vitest run --passWithNoTests","test:watch":"vitest","prepublishOnly":"pnpm build"},"peerDependencies":{"vue":"^3.4.0"},"dependencies":{"@vueuse/core":"^11.0.0","dayjs":"^1.11.10"},"devDependencies":{"@vitejs/plugin-vue":"^5.1.0","pinia":"^2.2.0","sass":"^1.77.0","typescript":"^5.5.0","vite":"^5.4.0","vitest":"^2.1.0","vue":"^3.5.0","vue-tsc":"^2.1.0"},"gitHead":"4f3bbcb8b1b585ccfcffc5ef4cfb5cabd4f74be3","_id":"@coffeefish/beauty-calendar@0.1.0","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-Q/5DHBgovMH1kXNZHMjATH4+HUVqhgNqE3FfB4uNYkgSvBnVFF7xlqEZDMsKREI8L6zFfBrrCdechtgE7p0FHg==","shasum":"77272664bf43e29574629c8ab5744fefa3d88778","tarball":"https://registry.npmjs.org/@coffeefish/beauty-calendar/-/beauty-calendar-0.1.0.tgz","fileCount":41,"unpackedSize":467316,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDaFYCfnnLYm/3loASctzcO/oebcB0QHWlUqlHpH+HZ4AIgFAkQAgpyZV2SUhgRm71s7pDnnYuaXYyS7TnMuBPbw/c="}]},"_npmUser":{"name":"coffeefish","email":"garryxia666@gmail.com"},"directories":{},"maintainers":[{"name":"coffeefish","email":"garryxia666@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/beauty-calendar_0.1.0_1782669305262_0.48984474164212854"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-28T17:55:05.100Z","0.1.0":"2026-06-28T17:55:05.381Z","modified":"2026-06-28T17:55:05.601Z"},"maintainers":[{"name":"coffeefish","email":"garryxia666@gmail.com"}],"description":"A sci-fi styled, drag-to-create calendar component for Vue 3 — day / week / month views with i18n and theme switching.","homepage":"https://github.com/codeingforcoffee/beauty-calendar#readme","keywords":["vue","vue3","calendar","schedule","drag","day-view","week-view","month-view","tech","i18n"],"repository":{"type":"git","url":"git+https://github.com/codeingforcoffee/beauty-calendar.git"},"author":{"name":"coffeefish"},"bugs":{"url":"https://github.com/codeingforcoffee/beauty-calendar/issues"},"license":"MIT","readme":"<div align=\"center\">\n\n# Beauty Calendar\n\n**一個科技風、可拖曳建立日程的 Vue 3 日曆元件。**\n\n日 / 週 / 月檢視 · 跨天拖曳建立 · 移動與縮放 · 滑鼠右鍵刪除 · 國際化 · 執行時換膚。\n\n[![Vue 3](https://img.shields.io/badge/Vue-3.4%2B-42b883?logo=vue.js&logoColor=white)](https://vuejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-22d3ee.svg)](./LICENSE)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-a855f7.svg)](#參與貢獻)\n\n[English](./README.md) · [简体中文](./README.zh-CN.md) · **繁體中文** · [日本語](./README.ja.md)\n\n![Beauty Calendar preview](./docs/preview.svg)\n\n</div>\n\n---\n\n## 為什麼\n\n大多數日曆函式庫不是笨重且與業務高度耦合,就是只停留在靜態渲染。Beauty Calendar 專注於兩件真正難做好的事——**面板渲染**與**拖曳互動**——並且與任何後端完全解耦。資料模型刻意做得極小(`startTime`、`endTime`、`title`、`creator`),其餘欄位都交給你自由擴充。\n\n## 目錄\n\n- [特性](#特性)\n- [環境需求](#環境需求)\n- [安裝](#安裝)\n- [快速開始](#快速開始)\n- [本機執行](#本機執行)\n- [整合指南](#整合指南)\n- [互動說明](#互動說明)\n- [API 屬性](#api-屬性)\n- [API 事件](#api-事件)\n- [資料模型](#資料模型)\n- [主題客製化](#主題客製化)\n- [國際化](#國際化)\n- [無頭與進階用法](#無頭與進階用法)\n- [專案結構](#專案結構)\n- [指令腳本](#指令腳本)\n- [參與貢獻](#參與貢獻)\n- [授權](#授權)\n\n## 特性\n\n- 🗓 **日 / 週 / 月**檢視,附動畫切換器\n- 🖱 **拖曳建立**——日內縱向拖曳、**跨欄拖曳產生跨天日程**(日 / 週檢視),或在月檢視跨格拖曳\n- ✅ **二次確認彈窗**——拖曳後彈出浮層卡片(標題 · 時間 · 建立人),確認後才真正寫入\n- ↕ **移動與縮放**既有日程,附格線吸附(週檢視還支援橫向換天)\n- 🗑 **滑鼠右鍵選單**刪除日程\n- 🧲 智慧重疊版面——日 / 週檢視依車道排列,月檢視為跨天長條\n- 🎨 **科技 / 賽博風主題**:6 套強調色預設 + 暗 / 亮配色,或自訂顏色——全部基於 CSS 變數\n- 🌍 內建**國際化**(zh-CN / zh-TW / en / ja),可完全覆寫,零額外相依套件\n- 🧩 既可直接當元件用,也可使用無頭核心函式(`createGeometry`、`layoutDay`、`layoutMonthWeek` 等)\n- 📦 零業務耦合。Peer 相依僅 `vue`、`dayjs`、`@vueuse/core`。產物含 ESM + UMD + 型別宣告。\n\n## 環境需求\n\n- **Node** ≥ 18\n- **Vue** ≥ 3.4(使用了 `defineModel`)\n- 支援 `.vue` 單一檔案元件與 CSS 匯入的建置工具(Vite、Vue CLI、Nuxt 等)\n\n## 安裝\n\n```bash\npnpm add beauty-calendar\n# 或\nnpm i beauty-calendar\n# 或\nyarn add beauty-calendar\n```\n\n`dayjs` 與 `@vueuse/core` 是執行時相依套件;`vue` 是你已具備的 peer 相依。\n\n## 快速開始\n\n```vue\n<script setup lang=\"ts\">\nimport { ref } from \"vue\";\nimport { BeautyCalendar, type CalendarEvent } from \"beauty-calendar\";\nimport \"beauty-calendar/style.css\";\n\nconst events = ref<CalendarEvent[]>([\n  {\n    id: \"1\",\n    title: \"设计评审\",\n    startTime: Date.now(),\n    endTime: Date.now() + 60 * 60 * 1000,\n    creator: \"Alice\",\n  },\n]);\n</script>\n\n<template>\n  <div style=\"height: 100vh\">\n    <BeautyCalendar v-model:events=\"events\" theme=\"aurora\" scheme=\"dark\" current-user=\"You\" />\n  </div>\n</template>\n```\n\n> 元件會撐滿父容器——記得給外層容器一個高度。\n\n這就是全部設定。在空白格線上拖曳即可建立,拖曳日程可移動 / 縮放,滑鼠右鍵可刪除。建立 / 更新 / 刪除會同時寫回繫結的 `events` 模型**並**對外發出事件,因此開箱即用,又始終可控。\n\n## 本機執行\n\n複製儲存庫並啟動內建的 **playground**(Vite + Pinia)——探索每個屬性與互動的最快方式:\n\n```bash\ngit clone https://github.com/codeingforcoffee/beauty-calendar.git\ncd beauty-calendar\npnpm install\npnpm play          # → http://localhost:5180\n```\n\nplayground 使用 **Pinia store** 儲存示範資料,並提供主題、配色、語言、每週起始、列高、可編輯 / 可建立等開關,以及一份記錄所有事件的活動紀錄。\n\n建置函式庫或 playground:\n\n```bash\npnpm build         # 库 → dist/(ESM + UMD + .d.ts + css)\npnpm build:play    # 静态 playground → dist-play/\npnpm type-check    # vue-tsc 类型检查,不产出\npnpm test          # vitest 单元测试\n```\n\n## 整合指南\n\n### 1. 區域元件(推薦)\n\n```ts\nimport { BeautyCalendar } from \"beauty-calendar\";\nimport \"beauty-calendar/style.css\";\n```\n\n### 2. 全域外掛\n\n```ts\nimport { createApp } from \"vue\";\nimport { BeautyCalendarPlugin } from \"beauty-calendar\";\nimport \"beauty-calendar/style.css\";\n\ncreateApp(App).use(BeautyCalendarPlugin).mount(\"#app\");\n// 此后任意位置都可使用 <BeautyCalendar />\n```\n\n### 3. 受控與非受控\n\n所有狀態都是 `v-model`——需要控制的就繫結,不需要的就省略:\n\n```vue\n<BeautyCalendar\n  v-model:events=\"events\"\n  v-model:view=\"view\"        <!-- 'day' | 'week' | 'month' -->\n  v-model:date=\"anchorDate\"  <!-- 可视范围锚点 -->\n  v-model:locale=\"locale\"\n/>\n```\n\n### 4. 串接後端\n\n元件會即時修改本機 `events` 模型以取得流暢回饋,同時發出相同的變更供你持久化。把事件當作同步點即可:\n\n```vue\n<script setup lang=\"ts\">\nimport { ref } from \"vue\";\nimport { BeautyCalendar, type CalendarEvent, type TimeRange } from \"beauty-calendar\";\nimport { api } from \"./api\";\n\nconst events = ref<CalendarEvent[]>(await api.list());\n\nconst onCreate = (ev: CalendarEvent) => api.create(ev);\nconst onUpdate = (p: { id: string } & TimeRange) => api.patch(p.id, p);\nconst onDelete = (ev: CalendarEvent) => api.remove(ev.id);\n</script>\n\n<template>\n  <BeautyCalendar\n    v-model:events=\"events\"\n    @event-create=\"onCreate\"\n    @event-update=\"onUpdate\"\n    @event-delete=\"onDelete\"\n  />\n</template>\n```\n\n想要自訂建立流程(例如彈出你自己的表單)?設定 `:confirm-create=\"false\"` 並監聽 `@event-create`,或保留內建確認彈窗、在那裡讀取標題。\n\n## 互動說明\n\n| 手勢                         | 結果                                                |\n| ---------------------------- | --------------------------------------------------- |\n| 在空白格線拖曳(日 / 週)    | 建立——單天縱向拖曳,**跨欄拖曳產生跨天日程**        |\n| 點擊空白格線(日 / 週)      | 在該時刻建立一個 `defaultCreateMinutes` 時長的日程  |\n| 在月檢視跨格拖曳             | 建立跨這些天的日程(開始 = 最近的步進時間)         |\n| 拖曳日程主體                 | 移動(週檢視同時換天)                              |\n| 拖曳日程上 / 下邊緣          | 縮放(僅單天日程)                                  |\n| 滑鼠右鍵日程                 | 開啟選單 → **刪除**                                 |\n| 點擊日期數字 / 表頭          | 跳至該天的「日」檢視                                |\n\n拖曳建立預設彈出**確認彈窗**;按 <kbd>Enter</kbd> 確認,<kbd>Esc</kbd> 或點擊外部取消。\n\n## API 屬性\n\n| 屬性                   | 型別                                       | 預設值     | 說明                                |\n| ---------------------- | ------------------------------------------ | ---------- | ----------------------------------- |\n| `v-model:events`       | `CalendarEvent[]`                          | `[]`       | 要渲染的日程(雙向)。              |\n| `v-model:view`         | `'day' \\| 'week' \\| 'month'`               | `'week'`   | 目前檢視。                          |\n| `v-model:date`         | `number \\| string \\| Date`                 | 目前時間   | 可視範圍的錨點日期。                |\n| `v-model:locale`       | `string`                                   | `'zh-CN'`  | 語言 key。                          |\n| `theme`                | `string \\| { accent, accent2 }`            | `'aurora'` | 強調色預設 key 或明確指定的顏色對。 |\n| `scheme`               | `'dark' \\| 'light'`                        | `'dark'`   | 配色方案。                          |\n| `weekStart`            | `0 \\| 1`                                    | `1`        | 每週起始為週日(0)或週一(1)。   |\n| `hourHeight`           | `number`                                    | `56`       | 每小時列高(像素)。               |\n| `snapMinutes`          | `number`                                    | `15`       | 拖曳吸附粒度(分鐘)。             |\n| `minEventMinutes`      | `number`                                    | `15`       | 渲染的最小時長。                    |\n| `defaultCreateMinutes` | `number`                                    | `30`       | 未拖動直接點擊建立時的時長。        |\n| `editable`             | `boolean`                                   | `true`     | 允許移動 / 縮放。                   |\n| `creatable`            | `boolean`                                   | `true`     | 允許拖曳建立。                      |\n| `deletable`            | `boolean`                                   | `true`     | 允許滑鼠右鍵刪除。                  |\n| `confirmCreate`        | `boolean`                                   | `true`     | 拖曳建立後是否彈出確認彈窗。        |\n| `currentUser`          | `string`                                    | —          | 寫入新建日程的建立人識別。          |\n| `messages`             | `Record<string, Partial<LocaleMessages>>`   | —          | 依語言覆寫文案。                    |\n| `nowInterval`          | `number`                                    | `30000`    | 目前時間指示線的重新整理間隔(毫秒)。 |\n\n## API 事件\n\n| 事件           | 載荷                          | 觸發時機                            |\n| -------------- | ----------------------------- | ----------------------------------- |\n| `event-create` | `CalendarEvent`               | 拖曳 / 點擊建立被確認後。           |\n| `event-update` | `{ id, startTime, endTime }`  | 移動 / 縮放結束後。                 |\n| `event-delete` | `CalendarEvent`               | 從選單刪除日程後。                  |\n| `event-click`  | `CalendarEvent`               | 點擊(非拖曳)日程時。              |\n| `date-click`   | `Dayjs`                       | 點擊日期數字 / 表頭時。            |\n\n## 資料模型\n\n```ts\ninterface CalendarEvent {\n  id: string;        // 稳定 id,用于 key 及更新 / 删除\n  title: string;\n  startTime: number; // epoch 毫秒\n  endTime: number;   // epoch 毫秒\n  creator?: string;  // 可选标识;同时作为自动配色的种子\n  color?: string;    // 可选显式颜色;否则按 creator 推导\n  [key: string]: unknown; // 自由携带你自己的字段\n}\n```\n\n## 主題客製化\n\n一套主題就是兩個強調色;中性色板來自配色方案。可用預設 key 或自訂顏色對:\n\n```vue\n<BeautyCalendar theme=\"neon\" scheme=\"dark\" />\n<BeautyCalendar :theme=\"{ accent: '#22d3ee', accent2: '#6366f1' }\" scheme=\"light\" />\n```\n\n預設:`aurora` · `neon` · `matrix` · `sunset` · `ice` · `gold`。\n\n每個視覺值都是作用於 `.beauty-calendar` 的 CSS 變數,你可以在自己的樣式裡覆寫任意一項:\n\n```css\n.beauty-calendar {\n  --bc-hour-height: 64px;\n  --bc-radius-md: 14px;\n  --bc-now: #ff3366;\n}\n```\n\n## 國際化\n\n內建語言:`zh-CN`、`zh-TW`、`en`、`ja`。可依語言覆寫文案,或新增你自己的語言:\n\n```vue\n<BeautyCalendar\n  locale=\"en\"\n  :messages=\"{ en: { createNew: 'Add', views: { week: 'Wk' } } }\"\n/>\n```\n\n日期格式由語言包中的 `monthsLong` / `weekdaysLong` 陣列驅動(無需 dayjs 的 locale 套件),因此覆寫文案也會同步在地化表頭。要註冊一種全新語言,在 `messages` 中以新 key 傳入完整的 `LocaleMessages`,再把 `locale` 指向它即可。\n\n## 無頭與進階用法\n\n幾何與版面計算都已匯出,可用於自訂渲染器:\n\n```ts\nimport {\n  createGeometry, // 像素 ↔ 时间换算与吸附\n  layoutDay,      // 单天列的重叠车道\n  layoutMonthWeek,// 月视图某周行的跨天长条\n  viewDays,       // 日 / 周 / 月网格生成\n  nearestStepMinutes,\n} from \"beauty-calendar\";\n\nconst geo = createGeometry(56, 15);\nconst positioned = layoutDay(Date.now(), events, geo); // → { top, height, lane, lanes, … }[]\n```\n\n也可以在子元件中 `useCalendar()` 讀取即時上下文(檢視、幾何、文案、動作),組裝你自己的部件。\n\n## 專案結構\n\n```\nsrc/\n  core/         # 纯逻辑(无 Vue):time、layout、month-layout、grid、format\n  composables/  # use-context(provide/inject)、use-drag-create、use-drag-move\n  components/   # BeautyCalendar、表头、视图(日周 / 月)、日程块、弹窗、菜单\n  i18n/         # 语言注册表 + zh-CN / zh-TW / en / ja\n  theme/        # 强调色预设 + 自动配色板\n  styles/       # 设计令牌(CSS 变量)+ 基础样式\n  index.ts      # 对外入口\nplayground/     # Vite + Pinia 演示应用\n```\n\n## 指令腳本\n\n| 指令               | 說明                       |\n| ------------------ | -------------------------- |\n| `pnpm play`        | 啟動 playground 開發伺服器 |\n| `pnpm dev`         | `pnpm play` 的別名         |\n| `pnpm build`       | 將函式庫建置到 `dist/`     |\n| `pnpm build:play`  | 建置靜態 playground        |\n| `pnpm type-check`  | 用 `vue-tsc` 做型別檢查    |\n| `pnpm test`        | 用 Vitest 執行單元測試     |\n\n## 參與貢獻\n\n歡迎 issue 與 PR。開始開發:\n\n```bash\npnpm install\npnpm play          # 基于 playground 开发\npnpm type-check    # 保持类型干净\n```\n\n慣例:全程 TypeScript;保持 `src/core/**` 不相依 Vue / DOM 以便單元測試;遵循既有元件風格。提交 PR 前請先跑 `pnpm type-check`。\n\n## 授權\n\n[MIT](./LICENSE) © coffeefish\n","readmeFilename":"README.zh-TW.md","_rev":"1-1a5a8794b5b6c1b65244ea8494d7022c"}