@chenzy-design/svelte 0.3.0 → 0.4.1

package/dist/calendar/meta.js

@@ -1,116 +1,161 @@
 /**
  * Machine-readable component metadata for AI/docs consumption.
- * Calendar — see specs/components/show/Calendar.spec.md
+ * Calendar — 纯事件展示日历，对齐 Semi Design Calendar 契约。
  */
 export const meta = {
     name: 'Calendar',
     category: 'show',
-    description: '月/周/日视图日历：日格网格 + 事件展示与 +N 折叠，today/selected/outside/weekend/disabled 态、导航（上一/今天/下一，月或周或天）；mode 切换月(6×7)/周(1×7)/日(单日时间轴)视图，day 模式纵向列出小时段(dayStartHour~dayEndHour)，带时间的事件按起始小时入对应时段、全天或跨天延续事件入顶部「全天」区，selectionMode 切换单选(selectedDate)/范围(rangeValue，起止+区间高亮+hover 预览)。受控 value(锚点)/selectedDate/rangeValue 不回写，仅通过 onChange/onSelect/onRangeChange/onDateClick/onMoreClick 通知。完整 WAI-ARIA grid roving 键盘焦点（方向键/PageUp-Down/Home-End/Enter-Space），popup 弹层模式（复用 _floating 门户 + 外部点击/Esc 关闭），day 视图时间轴虚拟化（复用 core fixedRange）。',
+    description: '纯事件展示日历，对齐 Semi Design Calendar。四视图 mode=day/week/month/range：day 单日时间轴（左时间列 + 单日列，25×2 半小时可点击格 + 绝对定位事件）；week 星期表头 + 7 列 DayCol，跨天事件走顶部全天区（parseWeekSpanEvents）；range 结构同 week，列数=range 天数（左闭右开），跨天走 parseSpanEvents；month 6×7 网格，跨天条走 getMonthEvents，每格超额显示「还有 N 项」并用 Popover 弹卡片。displayValue 决定展示锚点；onClick 回调点击的精确时间点（日/周精确到半小时，月精确到日）。showCurrTime 当前时间红线（当天列，每 30s 刷新）。事件定位全部来自 @chenzy-design/core 纯算法（getDailyEvents/parseWeekSpanEvents/parseSpanEvents/getMonthEvents/calcRowHeight/allDayEventMap/getPos），本组件只把数值位置转成内联样式。事件外观由 event.children 承载（字符串直出 / snippet render），对齐 Semi children。头部对齐 Semi：无默认导航，仅当传入 header 时渲染自定义头部。',
     exports: ['Calendar'],
     props: [
-        { name: 'value', type: 'Date', default: 'undefined', desc: '受控锚点日期(决定展示月份/周)，受控时不回写' },
-        { name: 'defaultValue', type: 'Date', default: 'new Date()', desc: '非受控初始锚点' },
-        { name: 'mode', type: "'month' | 'week' | 'day'", default: "'month'", desc: '视图模式：月(6×7)/周(1×7)/日(单日时间轴)' },
-        { name: 'selectionMode', type: "'single' | 'range'", default: "'single'", desc: '选择模式：单选或范围' },
-        { name: 'events', type: 'CalendarEvent[]', default: '[]', desc: '事件列表' },
+        { name: 'displayValue', type: 'Date', default: 'new Date()', desc: '展示锚点日期（决定展示的天/周/月）' },
+        { name: 'range', type: '[Date, Date]', default: 'undefined', desc: "mode='range' 时必传，左闭右开 [start, end)" },
+        { name: 'header', type: 'Snippet', default: 'undefined', desc: '自定义头部内容（对齐 Semi header；缺省不渲染头部）' },
+        { name: 'events', type: 'CalendarEvent[]', default: '[]', desc: '事件列表（key 必填且唯一）' },
+        { name: 'mode', type: "'day' | 'week' | 'month' | 'range'", default: "'week'", desc: '视图模式' },
+        { name: 'showCurrTime', type: 'boolean', default: 'true', desc: '显示当前时间红线（日/周/多日视图，当天列）' },
         { name: 'weekStartsOn', type: '0|1|2|3|4|5|6', default: '0', desc: '一周起始(0=周日)' },
-        { name: 'maxEventsPerDay', type: 'number', default: '3', desc: '每格最多事件数，超出折叠 +N（month/week）' },
-        { name: 'dayStartHour', type: 'number', default: '0', desc: 'day 视图时间轴起始小时(0-23)' },
-        { name: 'dayEndHour', type: 'number', default: '23', desc: 'day 视图时间轴结束小时(0-23，含)' },
-        { name: 'weekendDays', type: 'number[]', default: '[0, 6]', desc: '周末列序号' },
-        { name: 'markWeekend', type: 'boolean', default: 'true', desc: '弱化高亮周末列' },
-        { name: 'disabledDate', type: '(date: Date) => boolean', default: 'undefined', desc: '命中则该格禁用' },
-        { name: 'selectedDate', type: 'Date', default: 'undefined', desc: '受控选中日(边框态，single 模式)，受控时不回写' },
-        { name: 'defaultSelectedDate', type: 'Date', default: 'undefined', desc: '非受控选中日初值' },
-        { name: 'rangeValue', type: '[Date, Date] | null', default: 'undefined', desc: '受控选中范围(range 模式)，受控时不回写' },
-        { name: 'defaultRangeValue', type: '[Date, Date] | null', default: 'undefined', desc: '非受控范围初值' },
-        { name: 'locale', type: 'string', default: "'zh-CN'", desc: 'Intl 月份/星期名格式化语言' },
-        { name: 'ariaLabel', type: 'string', default: 'undefined', desc: '网格 aria-label，默认取月份标题' },
-        { name: 'popup', type: 'boolean', default: 'false', desc: '弹层模式：渲染 trigger，日历作为浮层弹出（复用 _floating 门户定位）' },
-        { name: 'open', type: 'boolean', default: 'undefined', desc: '受控展开态(popup)，受控时不回写仅 onOpenChange' },
-        { name: 'defaultOpen', type: 'boolean', default: 'false', desc: '非受控初始展开态' },
-        { name: 'onOpenChange', type: '(info: { open: boolean }) => void', default: 'undefined', desc: '展开态变化回调' },
-        { name: 'placement', type: 'Placement', default: "'bottomStart'", desc: '浮层相对 trigger 的位置' },
-        { name: 'getContainer', type: '() => HTMLElement | null', default: 'undefined', desc: '浮层门户挂载容器(默认 body)' },
-        { name: 'trigger', type: 'Snippet', default: 'undefined', desc: 'popup 模式 trigger 自定义内容 { open, toggle }' },
-        { name: 'virtualizeDay', type: "boolean | 'auto'", default: "'auto'", desc: 'day 时间轴虚拟化：auto 按阈值/true 强制/false 关闭' },
-        { name: 'virtualizeThreshold', type: 'number', default: '18', desc: '触发虚拟化的最少小时行数(auto 生效)' },
-        { name: 'timelineViewportHeight', type: 'number', default: '360', desc: 'day 时间轴虚拟化视口高度(px)' },
-        { name: 'onChange', type: '(info: { value: Date }) => void', default: 'undefined' },
-        { name: 'onSelect', type: '(info: { date: Date }) => void', default: 'undefined' },
-        { name: 'onRangeChange', type: '(info: { range: [Date, Date] }) => void', default: 'undefined' },
-        { name: 'onDateClick', type: '(info: { date: Date }) => void', default: 'undefined' },
+        { name: 'scrollTop', type: 'number', default: '400', desc: '日/周视图默认滚动区高度（px）' },
+        { name: 'markWeekend', type: 'boolean', default: 'false', desc: '区分周末列（灰底）' },
+        {
+            name: 'minEventHeight',
+            type: 'number',
+            default: 'Number.MIN_SAFE_INTEGER',
+            desc: '日/周/多日视图事件块最小高度（px）',
+        },
+        { name: 'width', type: 'number | string', default: 'undefined', desc: '日历整体宽度' },
+        { name: 'height', type: 'number | string', default: '600', desc: '日历整体高度' },
+        {
+            name: 'onClick',
+            type: '(e: Event, date: Date) => void',
+            default: 'undefined',
+            desc: '点击日期格（对齐 Semi function(e, date)）：日/周视图精确到半小时，月视图精确到日',
+        },
+        {
+            name: 'onClose',
+            type: '(e: Event) => void',
+            default: 'undefined',
+            desc: '月视图 +N 卡片关闭回调（对齐 Semi function(e)）',
+        },
         {
             name: 'onMoreClick',
-            type: '(info: { date: Date; events: CalendarEvent[] }) => void',
+            type: '(e: Event, date: Date, remaining: number) => void',
+            default: 'undefined',
+            desc: '月视图点「还有 N 项」回调（对齐 Semi function(e, date, remaining)）',
+        },
+        {
+            name: 'renderTimeDisplay',
+            type: '(hour: number) => unknown',
             default: 'undefined',
+            desc: '自定义日/周视图时间文案（返回字符串即可）',
+        },
+        {
+            name: 'renderDateDisplay',
+            type: 'Snippet<[Date]>',
+            default: 'undefined',
+            desc: '自定义 week/range 视图日期表头（接收 date 的 Snippet，对齐 Semi ReactNode）',
+        },
+        {
+            name: 'dateGridRender',
+            type: '(dateString: string, date: Date) => Snippet | null | undefined',
+            default: 'undefined',
+            desc: '自定义单元格/列额外内容（dateString = date.toString()，对齐 Semi）',
+        },
+        {
+            name: 'allDayEventsRender',
+            type: '(events: CalendarEvent[]) => Snippet | null | undefined',
+            default: 'undefined',
+            desc: '自定义顶部全天区渲染',
         },
-        { name: 'dateCell', type: 'Snippet', default: 'undefined', desc: '自定义整格内容' },
-        { name: 'event', type: 'Snippet', default: 'undefined', desc: '自定义事件块' },
     ],
     events: [
-        { name: 'onChange', desc: '锚点(翻月/翻周/今天)变化' },
-        { name: 'onSelect', desc: '选中某日(single 模式)' },
-        { name: 'onRangeChange', desc: '范围选择完成(range 模式，已排序)' },
-        { name: 'onDateClick', desc: '点击日格' },
-        { name: 'onMoreClick', desc: '点击 +N 折叠触发器' },
+        { name: 'onClick', desc: '点击日期格（日/周半小时、月日）' },
+        { name: 'onMoreClick', desc: '月视图点「还有 N 项」' },
+        { name: 'onClose', desc: '月视图 +N 卡片关闭' },
     ],
     slots: [
-        { name: 'dateCell', desc: '自定义整格内容 { date, events, isToday, isOutside, disabled }' },
-        { name: 'event', desc: '自定义事件块 { event }' },
-        { name: 'trigger', desc: 'popup 模式 trigger 自定义内容 { open, toggle }' },
+        { name: 'header', desc: '自定义头部内容（对齐 Semi header）' },
     ],
     a11y: {
         hasRole: true,
         focusable: true,
-        note: '网格 role=grid，星期表头行 role=row 含 role=columnheader，每周一行 role=row 含 role=gridcell；today 设 aria-current=date，选中设 aria-selected，禁用设 aria-disabled。完整 WAI-ARIA grid roving 焦点：网格内仅活动格 tabindex=0（余 -1），方向键移动焦点（←→ 天、↑↓ 周、PageUp/Down 月、Home/End 周首末），跨月/周自动翻页并落焦，Enter/Space 选中。popup 模式：trigger aria-haspopup=dialog/aria-expanded，浮层 role=dialog，外部点击/Esc 关闭并归还焦点。',
+        note: '根容器 role=grid + aria-label（取标题）。时间轴视图每列 role=gridcell（含 aria-label 日期），半小时格为 <button>（aria-label=日期+时:分）。week/range 视图有日期表头 role=columnheader（day 视图对齐 Semi 无列头）。month 视图：星期表头 role=columnheader，日格 role=gridcell，today 格 aria-current=date，日格可点击（Enter/Space）。月视图「还有 N 项」用 Popover（trigger=click，showCloseButton，title=日期），关闭回调 onClose。',
     },
     tokens: [
-        '--cd-calendar-bg',
-        '--cd-calendar-border',
-        '--cd-calendar-header-bg',
-        '--cd-calendar-text',
-        '--cd-calendar-text-secondary',
-        '--cd-calendar-today-bg',
-        '--cd-calendar-today-fg',
-        '--cd-calendar-selected-border',
-        '--cd-calendar-range-bg',
-        '--cd-calendar-range-edge-bg',
-        '--cd-calendar-week-cell-min-h',
-        '--cd-calendar-hour-min-h',
-        '--cd-calendar-hour-label-w',
-        '--cd-calendar-weekend-bg',
-        '--cd-calendar-cell-bg-hover',
-        '--cd-calendar-event-default-bg',
-        '--cd-calendar-event-fg',
-        '--cd-calendar-disabled-bg',
-        '--cd-calendar-more-color',
-        '--cd-calendar-cell-min-h',
-        '--cd-calendar-radius',
+        // color（$color-calendar_*）
+        '--cd-calendar-color-bg',
+        '--cd-calendar-color-bg-active',
+        '--cd-calendar-color-text-active',
+        '--cd-calendar-color-curr-border',
+        '--cd-calendar-color-currcircle-bg-default',
+        '--cd-calendar-color-date-text-default',
+        '--cd-calendar-color-day-border',
+        '--cd-calendar-color-day-text-default',
+        '--cd-calendar-color-sticky-bg',
+        '--cd-calendar-color-weekend-bg',
+        // width（$width-calendar_*）
+        '--cd-calendar-width-day-grid',
+        '--cd-calendar-width-tag-col',
+        '--cd-calendar-width-currcircle',
+        '--cd-calendar-width-today-date',
+        '--cd-calendar-width-card',
+        // height（$height-calendar_*）
+        '--cd-calendar-height-day-grid',
+        '--cd-calendar-height-allday',
+        '--cd-calendar-height-today-date',
+        '--cd-calendar-height-month-day',
+        '--cd-calendar-height-month-week-row-event-month',
+        // radius（$radius-calendar_*）
+        '--cd-calendar-radius-today-date',
+        // spacing（$spacing-calendar_*）
+        '--cd-calendar-spacing-time-padding-right',
+        '--cd-calendar-spacing-time-item-span-top',
+        '--cd-calendar-spacing-allday-tag-padding-right',
+        '--cd-calendar-spacing-tag-child-padding-right',
+        '--cd-calendar-spacing-grid-row-span-child-padding-x',
+        '--cd-calendar-spacing-currcircle-margin-top',
+        '--cd-calendar-spacing-skeleton-li-child-padding-top',
+        '--cd-calendar-spacing-skeletion-grid-row-li-padding-right',
+        '--cd-calendar-spacing-month-date-right',
+        '--cd-calendar-spacing-month-event-card-wrapper-right',
+        '--cd-calendar-spacing-month-event-card-wrapper-padding-top',
+        '--cd-calendar-spacing-header-info-date-margin-top',
+        '--cd-calendar-spacing-body-pading-x',
+        // z-index（$z-calendar_*）
+        '--cd-calendar-z-stickytop',
+        '--cd-calendar-z-stickyleft',
+        '--cd-calendar-z-curr',
+        '--cd-calendar-z-item',
+        '--cd-calendar-z-line',
+        // 基础层 token
+        '--cd-color-bg-2',
+        '--cd-font-size-regular',
+        '--cd-font-size-small',
+        '--cd-font-size-header',
+        '--cd-focus-ring',
+        '--cd-spacing-extra-tight',
+        '--cd-border-radius-medium',
+        '--cd-border-radius-small',
     ],
     responsive: false,
     examples: [
-        { title: '基础月历', code: '<Calendar />' },
+        { title: '基础周视图', code: '<Calendar />' },
         {
             title: '带事件',
-            code: '<Calendar events={[{ key: 1, start: new Date(), title: "会议" }]} />',
+            code: '<Calendar events={[{ key: 1, start: new Date(), children: "会议" }]} />',
         },
-        { title: '周视图', code: '<Calendar mode="week" />' },
+        { title: '月视图', code: '<Calendar mode="month" />' },
         {
             title: '日视图（单日时间轴）',
-            code: '<Calendar mode="day" dayStartHour={8} dayEndHour={20} events={[{ key: 1, start: new Date(), title: "会议" }]} />',
-        },
-        {
-            title: '范围选择',
-            code: '<Calendar selectionMode="range" onRangeChange={(i) => console.log(i.range)} />',
+            code: '<Calendar mode="day" events={[{ key: 1, start: new Date(), children: "会议" }]} />',
         },
         {
-            title: '弹层模式',
-            code: '<Calendar popup defaultOpen onSelect={(i) => console.log(i.date)} />',
+            title: '多日视图（range）',
+            code: '<Calendar mode="range" range={[start, end]} />',
         },
         {
-            title: '弹层模式（自定义 trigger）',
-            code: '<Calendar popup>{#snippet trigger({ toggle })}<button onclick={toggle}>选择日期</button>{/snippet}</Calendar>',
+            title: '点击回调',
+            code: '<Calendar onClick={(e, date) => console.log(date)} />',
         },
     ],
 };