x-next 1.5.0 → 1.7.0

package/dist/components/heatmap/Heatmap.d.ts

@@ -0,0 +1,311 @@
+import { PropType, SlotsType } from 'vue';
+import { HeatmapCell, HeatmapData, HeatmapFirstDayOfWeek, HeatmapLoadingProps, HeatmapRange, HeatmapResolvedRange, HeatmapSize, HeatmapTooltipProps } from './interface';
+declare const _default: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    /**
+     * @zh 热力图数据
+     * @en Heatmap data
+     */
+    data: {
+        type: PropType<HeatmapData>;
+        default: () => never[];
+    };
+    /**
+     * @zh 要渲染的自然年；设置后优先于 startDate / endDate
+     * @en Year to render; takes priority over startDate / endDate
+     */
+    year: {
+        type: NumberConstructor;
+    };
+    /**
+     * @zh 自定义范围起始（时间戳或日期字符串）
+     * @en Custom range start (timestamp or date string)
+     */
+    startDate: {
+        type: PropType<HeatmapRange>;
+    };
+    /**
+     * @zh 自定义范围结束（时间戳或日期字符串）
+     * @en Custom range end (timestamp or date string)
+     */
+    endDate: {
+        type: PropType<HeatmapRange>;
+    };
+    /**
+     * @zh 由浅到深的色阶；不传使用内置主色阶
+     * @en Colors from light to dark; built-in primary ramp when omitted
+     */
+    activeColors: {
+        type: PropType<string[]>;
+    };
+    /**
+     * @zh 最小值（含无数据格）的颜色
+     * @en Color for the minimum value and cells without data
+     */
+    minimumColor: {
+        type: StringConstructor;
+    };
+    /**
+     * @zh 格子尺寸
+     * @en Cell size
+     * @values 'small', 'medium', 'large'
+     * @defaultValue 'medium'
+     */
+    size: {
+        type: PropType<HeatmapSize>;
+    };
+    /**
+     * @zh 一周的起始日（0 为周日）
+     * @en First day of the week (0 is Sunday)
+     * @defaultValue 0
+     */
+    firstDayOfWeek: {
+        type: PropType<HeatmapFirstDayOfWeek>;
+        default: number;
+        validator: (value: number) => boolean;
+    };
+    /**
+     * @zh 是否展示星期标签
+     * @en Whether to show weekday labels
+     * @defaultValue true
+     */
+    showWeekLabels: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * @zh 是否展示月份标签
+     * @en Whether to show month labels
+     * @defaultValue true
+     */
+    showMonthLabels: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * @zh 是否展示颜色图例
+     * @en Whether to show the color indicator
+     * @defaultValue true
+     */
+    showColorIndicator: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * @zh 鼠标悬浮提示；传对象时透传给内部浮层
+     * @en Hover tooltip; pass an object to configure the inner popup
+     * @defaultValue true
+     */
+    tooltip: {
+        type: PropType<HeatmapTooltipProps>;
+        default: boolean;
+    };
+    /**
+     * @zh 加载中
+     * @en Loading state
+     * @defaultValue false
+     */
+    loading: {
+        type: PropType<HeatmapLoadingProps>;
+        default: boolean;
+    };
+    /**
+     * @zh 无障碍名称；设置后根节点带 role="img"
+     * @en Accessible name; adds role="img" to the root when set
+     */
+    ariaLabel: {
+        type: StringConstructor;
+    };
+}>, {
+    t: (key: import('../..').LocaleKey | (string & {}), params?: Record<string, string | number>) => string;
+    className: {
+        block: string;
+        element: (className: string) => string;
+        modifier: (className: string) => string;
+        is: (className: string) => string;
+    };
+    mergedSize: import('vue').ComputedRef<"mini" | "small" | "medium" | "large">;
+    cells: import('vue').ComputedRef<HeatmapCell[]>;
+    rows: import('vue').ComputedRef<HeatmapCell[][]>;
+    range: import('vue').ComputedRef<HeatmapResolvedRange | null>;
+    gridStyle: import('vue').ComputedRef<{
+        '--x-heatmap-cell-size': string;
+        gridTemplateRows: string;
+    }>;
+    weekdayLabels: import('vue').ComputedRef<string[]>;
+    monthLabels: import('vue').ComputedRef<{
+        text: string;
+        colIndex: number;
+    }[]>;
+    activeCell: import('vue').ComputedRef<HeatmapCell | null>;
+    tooltipEnabled: import('vue').ComputedRef<boolean>;
+    tooltipStyle: import('vue').ComputedRef<{
+        left?: undefined;
+        top?: undefined;
+    } | {
+        left: string;
+        top: string;
+    }>;
+    cellColor: (cell: HeatmapCell) => string;
+    cellLabel: (cell: HeatmapCell) => string;
+    handleCellClick: (cell: HeatmapCell, ev: MouseEvent) => void;
+    throttledMove: {
+        (...args: any[]): void;
+        cancel(): void;
+    };
+    clearActive: () => void;
+    isInRange: (cell: HeatmapCell) => boolean;
+    colorPalette: import('vue').ComputedRef<string[]>;
+    slots: Readonly<{
+        tooltip?: ((props: unknown) => unknown) | undefined;
+        cell?: ((props: unknown) => unknown) | undefined;
+        footer?: (() => unknown) | undefined;
+        indicator?: ((props: {
+            colors: string[];
+        }) => unknown) | undefined;
+        'indicator-leading-text'?: (() => unknown) | undefined;
+        'indicator-trailing-text'?: (() => unknown) | undefined;
+    }>;
+}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    /**
+     * @zh 点击某个日期格时触发
+     * @en Emitted when a day cell is clicked
+     * @param {HeatmapCell} cell
+     * @param {MouseEvent} ev
+     */
+    cellClick: (cell: HeatmapCell, ev: MouseEvent) => true;
+}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    /**
+     * @zh 热力图数据
+     * @en Heatmap data
+     */
+    data: {
+        type: PropType<HeatmapData>;
+        default: () => never[];
+    };
+    /**
+     * @zh 要渲染的自然年；设置后优先于 startDate / endDate
+     * @en Year to render; takes priority over startDate / endDate
+     */
+    year: {
+        type: NumberConstructor;
+    };
+    /**
+     * @zh 自定义范围起始（时间戳或日期字符串）
+     * @en Custom range start (timestamp or date string)
+     */
+    startDate: {
+        type: PropType<HeatmapRange>;
+    };
+    /**
+     * @zh 自定义范围结束（时间戳或日期字符串）
+     * @en Custom range end (timestamp or date string)
+     */
+    endDate: {
+        type: PropType<HeatmapRange>;
+    };
+    /**
+     * @zh 由浅到深的色阶；不传使用内置主色阶
+     * @en Colors from light to dark; built-in primary ramp when omitted
+     */
+    activeColors: {
+        type: PropType<string[]>;
+    };
+    /**
+     * @zh 最小值（含无数据格）的颜色
+     * @en Color for the minimum value and cells without data
+     */
+    minimumColor: {
+        type: StringConstructor;
+    };
+    /**
+     * @zh 格子尺寸
+     * @en Cell size
+     * @values 'small', 'medium', 'large'
+     * @defaultValue 'medium'
+     */
+    size: {
+        type: PropType<HeatmapSize>;
+    };
+    /**
+     * @zh 一周的起始日（0 为周日）
+     * @en First day of the week (0 is Sunday)
+     * @defaultValue 0
+     */
+    firstDayOfWeek: {
+        type: PropType<HeatmapFirstDayOfWeek>;
+        default: number;
+        validator: (value: number) => boolean;
+    };
+    /**
+     * @zh 是否展示星期标签
+     * @en Whether to show weekday labels
+     * @defaultValue true
+     */
+    showWeekLabels: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * @zh 是否展示月份标签
+     * @en Whether to show month labels
+     * @defaultValue true
+     */
+    showMonthLabels: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * @zh 是否展示颜色图例
+     * @en Whether to show the color indicator
+     * @defaultValue true
+     */
+    showColorIndicator: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * @zh 鼠标悬浮提示；传对象时透传给内部浮层
+     * @en Hover tooltip; pass an object to configure the inner popup
+     * @defaultValue true
+     */
+    tooltip: {
+        type: PropType<HeatmapTooltipProps>;
+        default: boolean;
+    };
+    /**
+     * @zh 加载中
+     * @en Loading state
+     * @defaultValue false
+     */
+    loading: {
+        type: PropType<HeatmapLoadingProps>;
+        default: boolean;
+    };
+    /**
+     * @zh 无障碍名称；设置后根节点带 role="img"
+     * @en Accessible name; adds role="img" to the root when set
+     */
+    ariaLabel: {
+        type: StringConstructor;
+    };
+}>> & Readonly<{
+    onCellClick?: ((cell: HeatmapCell, ev: MouseEvent) => any) | undefined;
+}>, {
+    loading: HeatmapLoadingProps;
+    data: HeatmapData;
+    tooltip: HeatmapTooltipProps;
+    firstDayOfWeek: HeatmapFirstDayOfWeek;
+    showWeekLabels: boolean;
+    showMonthLabels: boolean;
+    showColorIndicator: boolean;
+}, SlotsType<{
+    tooltip?: (props: unknown) => unknown;
+    cell?: (props: unknown) => unknown;
+    footer?: () => unknown;
+    indicator?: (props: {
+        colors: string[];
+    }) => unknown;
+    'indicator-leading-text'?: () => unknown;
+    'indicator-trailing-text'?: () => unknown;
+}>, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/components/heatmap/helpers/matrix.d.ts

@@ -0,0 +1,58 @@
+import { dayjs } from '../../../_utils/date';
+import { HeatmapCell, HeatmapData, HeatmapFirstDayOfWeek, HeatmapRange, HeatmapResolvedRange, HeatmapSize } from '../interface';
+/**
+ * 热力图日期矩阵算法。
+ *
+ * 与 DatePicker 保持一致：按 `firstDayOfWeek` 对齐周首时使用 offset 公式，
+ * 不用 `dayjs().startOf('week')`——后者依赖 dayjs 全局 locale，
+ * 会和按 `firstDayOfWeek` 排布的网格错位（date-picker 已踩过此坑）。
+ */
+/** 单元格边长（像素） */
+export declare const CELL_SIZE: Record<HeatmapSize, number>;
+/** 默认色阶档位数（不含 minimumColor 档） */
+export declare const DEFAULT_COLOR_LEVELS = 5;
+/** 该日期所在周的周首 */
+export declare const startOfWeekByDay: (value: ReturnType<typeof dayjs>, firstDayOfWeek: HeatmapFirstDayOfWeek) => import('dayjs').Dayjs;
+/**
+ * 解析要渲染的日期范围。
+ *
+ * 优先级：`year` > `startDate`/`endDate` > 从 `data` 推导（首尾 timestamp）。
+ * 返回的起止都已按 `firstDayOfWeek` 对齐到周首与周末，因此列数恒为整数。
+ */
+export declare const resolveRange: (props: {
+    year?: number;
+    startDate?: number | string;
+    endDate?: number | string;
+    data?: HeatmapData;
+}, firstDayOfWeek: HeatmapFirstDayOfWeek) => HeatmapResolvedRange | null;
+/** 把数据按「当天零点时间戳」索引，渲染时 O(1) 命中 */
+export declare const indexDataByDay: (data: HeatmapData) => Map<number, number | null>;
+/**
+ * 值 → 色阶档位。
+ *
+ * 返回 `0` 表示该格使用 `minimumColor`（无数据或无效值）；
+ * 有效值按 `[min, max]` 均分到 `1..levels`。当 max === min 时统一取最高档，
+ * 避免整片数据同值时全部落到最浅档。
+ */
+export declare const getColorLevel: (value: number | null | undefined, min: number, max: number, levels: number) => number;
+/** 数据中有效值的最小/最大值；无有效值时返回 null */
+export declare const getValueExtent: (data: HeatmapData) => {
+    min: number;
+    max: number;
+} | null;
+/**
+ * 构建 7 行 × weeks 列的可渲染格子。
+ * 每格带时间戳、值、色阶档位与坐标；`outOfRange` 用于区分「补齐的首尾格」。
+ */
+export declare const buildMatrix: (range: HeatmapResolvedRange, dataMap: Map<number, number | null>, extent: {
+    min: number;
+    max: number;
+} | null, levels: number) => HeatmapCell[];
+/** 每列的月份归属，供月标签定位（列内取一个有效日，整列同月） */
+export declare const getMonthLabels: (range: HeatmapResolvedRange, cells: HeatmapCell[], monthLabelFormatter: (value: ReturnType<typeof dayjs>) => string) => {
+    text: string;
+    colIndex: number;
+}[];
+/** 该格是否落在用户请求的原始范围内（用于视觉上弱化补齐格） */
+export declare const isCellInRequestedRange: (cell: HeatmapCell, from: ReturnType<typeof dayjs>, to: ReturnType<typeof dayjs>) => boolean;
+export type { HeatmapRange };