@tsingroc/tsingroc-components 5.0.2 → 5.1.0

package/dist/pages/DayAheadReviewPage/hook/useDayAheadReviewDate.d.ts

@@ -0,0 +1,137 @@
+import type { Dayjs } from "dayjs";
+/**
+ * 日前复盘日期钩子的配置选项。
+ *
+ * @example
+ * ```ts
+ * const options: UseDayAheadReviewDateOptions = {
+ *   projectId: "power-market-review",
+ *   serviceStartDay: "2024-01-01",
+ *   serviceEndDay: "2024-12-31",
+ * };
+ * ```
+ */
+export interface UseDayAheadReviewDateOptions {
+    /**
+     * 用于会话存储键作用域的唯一标识符。
+     * 防止多个实例之间的日期选择冲突。
+     *
+     * @example "power-market-review"
+     */
+    projectId: string;
+    /**
+     * 服务开始日期，格式为 `YYYY-MM-DD`。
+     * 此值之前的日期将在选择器中被禁用。
+     *
+     * @optional
+     * @example "2024-01-01"
+     */
+    serviceStartDay?: string;
+    /**
+     * 服务结束日期，格式为 `YYYY-MM-DD`。
+     * 此值之后的日期将在选择器中被禁用。
+     *
+     * @optional
+     * @example "2024-12-31"
+     */
+    serviceEndDay?: string;
+    /**
+     * 可选的初始日期覆盖。
+     * 如果未提供，默认为昨天（D-1）。
+     *
+     * @optional
+     */
+    initialDate?: Dayjs;
+}
+/**
+ * 日前复盘日期钩子的返回值。
+ *
+ * 提供日期状态管理，具有自动边界约束
+ * 和兼容 Ant Design DatePicker 的禁用日期函数。
+ */
+export interface UseDayAheadReviewDateResult {
+    /**
+     * 当前选中的日期，已约束到服务期间边界内。
+     * 用于 DatePicker 的 `value` 属性。
+     */
+    date: Dayjs;
+    /**
+     * 更新选中日期的函数。
+     * 自动将新值约束到服务期间边界内
+     * 并持久化到会话存储。
+     *
+     * @param newDate - 要设置的新日期（将被约束到边界内）
+     */
+    setDate: (date: Dayjs) => void;
+    /**
+     * 格式化的交易日字符串，格式为 `YYYY-MM-DD`。
+     * 用于 API 调用和数据获取。
+     *
+     * @example "2024-01-15"
+     */
+    tradingDay: string;
+    /**
+     * 从 `serviceStartDay` 派生的最小可选日期。
+     * 如果没有开始日期约束则为 `undefined`。
+     */
+    minDate: Dayjs | undefined;
+    /**
+     * 从 `serviceEndDay` 派生的最大可选日期。
+     * 如果没有结束日期约束则为 `undefined`。
+     */
+    maxDate: Dayjs | undefined;
+    /**
+     * Ant Design DatePicker 的禁用日期函数。
+     * 对于服务期间之外的日期返回 `true`。
+     *
+     * @param current - 正在评估的日期
+     * @returns 如果日期应该被禁用则返回 `true`
+     */
+    disabledDate: (current: Dayjs | null) => boolean;
+}
+/**
+ * 用于管理日前复盘日期选择的自定义 React 钩子。
+ *
+ * 提供日期状态管理，具有会话存储持久化、
+ * 自动边界约束和 Ant Design DatePicker 集成。
+ *
+ * ## 功能特性
+ *
+ * - **会话存储持久化**: 选中的日期在页面刷新后依然保留
+ * - **自动边界约束**: 日期被限制在服务期间内
+ * - **智能初始化**: 默认为昨天（D-1），适用于复盘场景
+ * - **项目隔离**: 通过唯一的 `projectId` 可以共存多个实例
+ *
+ * ## 会话存储
+ *
+ * 日期存储的键格式：`dayAheadReview.selectedDate.{projectId}`
+ *
+ * ## 使用示例
+ *
+ * ```tsx
+ * function ReviewPage() {
+ *   const { date, setDate, tradingDay, disabledDate } = useDayAheadReviewDate({
+ *     projectId: "power-market-review",
+ *     serviceStartDay: "2024-01-01",
+ *     serviceEndDay: dayjs().add(7, "day").format("YYYY-MM-DD"),
+ *   });
+ *
+ *   const { data } = useQuery({
+ *     queryKey: ["review", tradingDay],
+ *     queryFn: () => fetchReviewData(tradingDay),
+ *   });
+ *
+ *   return (
+ *     <DatePicker
+ *       value={date}
+ *       onChange={setDate}
+ *       disabledDate={disabledDate}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @param options - 钩子的配置选项
+ * @returns 日期状态管理工具
+ */
+export declare function useDayAheadReviewDate({ projectId, serviceStartDay, serviceEndDay, initialDate, }: UseDayAheadReviewDateOptions): UseDayAheadReviewDateResult;

package/dist/pages/DayAheadReviewPage/hook/useDayAheadReviewDate.js

@@ -0,0 +1,252 @@
+import { c as _c } from "react/compiler-runtime";
+import dayjs from "dayjs";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+const STORAGE_PREFIX = "dayAheadReview";
+const getStorageKey = projectId => `${STORAGE_PREFIX}.selectedDate.${projectId}`;
+const safeReadSessionStorage = key => {
+  try {
+    return sessionStorage.getItem(key);
+  } catch {
+    return null;
+  }
+};
+const safeWriteSessionStorage = (key, value) => {
+  try {
+    sessionStorage.setItem(key, value);
+  } catch {
+    console.error(`Failed to write sessionStorage for key: ${key}`);
+  }
+};
+const clampToBounds = (value, minDate, maxDate) => {
+  let d = value.startOf("day");
+  if (minDate && d.isBefore(minDate, "day")) d = minDate.startOf("day");
+  if (maxDate && d.isAfter(maxDate, "day")) d = maxDate.startOf("day");
+  return d;
+};
+
+/**
+ * 日前复盘日期钩子的配置选项。
+ *
+ * @example
+ * ```ts
+ * const options: UseDayAheadReviewDateOptions = {
+ *   projectId: "power-market-review",
+ *   serviceStartDay: "2024-01-01",
+ *   serviceEndDay: "2024-12-31",
+ * };
+ * ```
+ */
+
+/**
+ * 日前复盘日期钩子的返回值。
+ *
+ * 提供日期状态管理，具有自动边界约束
+ * 和兼容 Ant Design DatePicker 的禁用日期函数。
+ */
+
+/**
+ * 用于管理日前复盘日期选择的自定义 React 钩子。
+ *
+ * 提供日期状态管理，具有会话存储持久化、
+ * 自动边界约束和 Ant Design DatePicker 集成。
+ *
+ * ## 功能特性
+ *
+ * - **会话存储持久化**: 选中的日期在页面刷新后依然保留
+ * - **自动边界约束**: 日期被限制在服务期间内
+ * - **智能初始化**: 默认为昨天（D-1），适用于复盘场景
+ * - **项目隔离**: 通过唯一的 `projectId` 可以共存多个实例
+ *
+ * ## 会话存储
+ *
+ * 日期存储的键格式：`dayAheadReview.selectedDate.{projectId}`
+ *
+ * ## 使用示例
+ *
+ * ```tsx
+ * function ReviewPage() {
+ *   const { date, setDate, tradingDay, disabledDate } = useDayAheadReviewDate({
+ *     projectId: "power-market-review",
+ *     serviceStartDay: "2024-01-01",
+ *     serviceEndDay: dayjs().add(7, "day").format("YYYY-MM-DD"),
+ *   });
+ *
+ *   const { data } = useQuery({
+ *     queryKey: ["review", tradingDay],
+ *     queryFn: () => fetchReviewData(tradingDay),
+ *   });
+ *
+ *   return (
+ *     <DatePicker
+ *       value={date}
+ *       onChange={setDate}
+ *       disabledDate={disabledDate}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @param options - 钩子的配置选项
+ * @returns 日期状态管理工具
+ */
+export function useDayAheadReviewDate(t0) {
+  const $ = _c(34);
+  const {
+    projectId,
+    serviceStartDay,
+    serviceEndDay,
+    initialDate
+  } = t0;
+  let t1;
+  if ($[0] !== projectId) {
+    t1 = getStorageKey(projectId);
+    $[0] = projectId;
+    $[1] = t1;
+  } else {
+    t1 = $[1];
+  }
+  const storageKey = t1;
+  let t2;
+  if ($[2] !== serviceStartDay) {
+    t2 = serviceStartDay ? dayjs(serviceStartDay).startOf("day") : undefined;
+    $[2] = serviceStartDay;
+    $[3] = t2;
+  } else {
+    t2 = $[3];
+  }
+  const minDate = t2;
+  let t3;
+  if ($[4] !== serviceEndDay) {
+    t3 = serviceEndDay ? dayjs(serviceEndDay).startOf("day") : undefined;
+    $[4] = serviceEndDay;
+    $[5] = t3;
+  } else {
+    t3 = $[5];
+  }
+  const maxDate = t3;
+  let t4;
+  if ($[6] !== initialDate || $[7] !== maxDate || $[8] !== minDate || $[9] !== storageKey) {
+    t4 = () => {
+      const stored = safeReadSessionStorage(storageKey);
+      const now = dayjs().startOf("day");
+      if (stored) {
+        const storedDate = dayjs(stored);
+        if (storedDate.isValid()) {
+          return clampToBounds(storedDate, minDate, maxDate);
+        }
+      }
+      const defaultDate = clampToBounds(initialDate ?? now.subtract(1, "day"), minDate, maxDate);
+      safeWriteSessionStorage(storageKey, defaultDate.format("YYYY-MM-DD"));
+      return defaultDate;
+    };
+    $[6] = initialDate;
+    $[7] = maxDate;
+    $[8] = minDate;
+    $[9] = storageKey;
+    $[10] = t4;
+  } else {
+    t4 = $[10];
+  }
+  const [date, setDateState] = useState(t4);
+  const initializedProjectIdRef = useRef(null);
+  let t5;
+  let t6;
+  if ($[11] !== initialDate || $[12] !== maxDate || $[13] !== minDate || $[14] !== projectId || $[15] !== storageKey) {
+    t5 = () => {
+      if (initializedProjectIdRef.current === projectId) {
+        return;
+      }
+      const stored_0 = safeReadSessionStorage(storageKey);
+      const now_0 = dayjs().startOf("day");
+      let initialValue;
+      if (stored_0) {
+        const storedDate_0 = dayjs(stored_0);
+        initialValue = storedDate_0.isValid() ? clampToBounds(storedDate_0, minDate, maxDate) : clampToBounds(now_0.subtract(1, "day"), minDate, maxDate);
+      } else {
+        initialValue = clampToBounds(initialDate ?? now_0.subtract(1, "day"), minDate, maxDate);
+      }
+      safeWriteSessionStorage(storageKey, initialValue.format("YYYY-MM-DD"));
+      queueMicrotask(() => {
+        setDateState(initialValue);
+      });
+      initializedProjectIdRef.current = projectId;
+    };
+    t6 = [projectId, storageKey, minDate, maxDate, initialDate];
+    $[11] = initialDate;
+    $[12] = maxDate;
+    $[13] = minDate;
+    $[14] = projectId;
+    $[15] = storageKey;
+    $[16] = t5;
+    $[17] = t6;
+  } else {
+    t5 = $[16];
+    t6 = $[17];
+  }
+  useEffect(t5, t6);
+  let t7;
+  if ($[18] !== maxDate || $[19] !== minDate || $[20] !== storageKey) {
+    t7 = newDate => {
+      const clamped = clampToBounds(newDate, minDate, maxDate);
+      setDateState(clamped);
+      safeWriteSessionStorage(storageKey, clamped.format("YYYY-MM-DD"));
+    };
+    $[18] = maxDate;
+    $[19] = minDate;
+    $[20] = storageKey;
+    $[21] = t7;
+  } else {
+    t7 = $[21];
+  }
+  const setDate = t7;
+  let t8;
+  if ($[22] !== maxDate || $[23] !== minDate) {
+    t8 = current => {
+      if (!current) {
+        return true;
+      }
+      if (minDate && current.isBefore(minDate, "day")) {
+        return true;
+      }
+      if (maxDate && current.isAfter(maxDate, "day")) {
+        return true;
+      }
+      return false;
+    };
+    $[22] = maxDate;
+    $[23] = minDate;
+    $[24] = t8;
+  } else {
+    t8 = $[24];
+  }
+  const disabledDate = t8;
+  let t9;
+  if ($[25] !== date) {
+    t9 = date.format("YYYY-MM-DD");
+    $[25] = date;
+    $[26] = t9;
+  } else {
+    t9 = $[26];
+  }
+  let t10;
+  if ($[27] !== date || $[28] !== disabledDate || $[29] !== maxDate || $[30] !== minDate || $[31] !== setDate || $[32] !== t9) {
+    t10 = {
+      date,
+      setDate,
+      tradingDay: t9,
+      minDate,
+      maxDate,
+      disabledDate
+    };
+    $[27] = date;
+    $[28] = disabledDate;
+    $[29] = maxDate;
+    $[30] = minDate;
+    $[31] = setDate;
+    $[32] = t9;
+    $[33] = t10;
+  } else {
+    t10 = $[33];
+  }
+  return t10;
+}

package/dist/pages/DayAheadReviewPage/index.d.ts

@@ -0,0 +1,149 @@
+import type { Dayjs } from "dayjs";
+import { useDayAheadReviewDate } from "./hook/useDayAheadReviewDate";
+import type { ExtendedReviewValue, FilterOption, PricePlotValue, StrategyPlotValue } from "./types/dayahead";
+export type { FilterOption };
+export type { ExtendedReviewValue, PricePlotValue, ProfitPlotValue, StrategyPlotValue, } from "./types/dayahead";
+export { useDayAheadReviewDate };
+/**
+ * 复盘页面所需的所有数据，包含三部分：
+ *
+ * - `power`: 策略对比图（电量）
+ * - `price`: 价格走势图（价格）
+ * - `table`: 明细表格 + 收益图表（组合数据）
+ *
+ * @example
+ * ```ts
+ * const data: DayAheadReviewPageData = {
+ *   power: [{ time: "2024-01-01T00:00", forecastVolume: 120.5, ... }],
+ *   price: [{ time: "2024-01-01T00:00", dayAheadPrice: 350.5, ... }],
+ *   table: [{ time: "2024-01-01T00:00", forecastVolume: 120.5, dayAheadPrice: 350.5, ... }],
+ * };
+ * ```
+ */
+export interface DayAheadReviewPageData {
+    /** 策略对比图的电力/电量数据 */
+    power: StrategyPlotValue[];
+    /** 价格走势图的价格数据 */
+    price: PricePlotValue[];
+    /** 明细表格和收益图表的组合数据 */
+    table: ExtendedReviewValue[];
+}
+/**
+ * DayAheadReviewPage 组件的属性。
+ *
+ * ## 必需属性
+ *
+ * 组件需要日期管理属性和数据。使用提供的 `useDayAheadReviewDate` 钩子可以简化日期处理。
+ *
+ * ## 可选属性
+ *
+ * - `loading`: 获取数据时显示骨架屏加载器
+ * - `error`: 显示错误消息提示
+ * - `onExport`: 导出按钮的自定义导出处理函数
+ *
+ * @example
+ * ```tsx
+ * function ReviewPage() {
+ *   const { date, setDate, tradingDay, disabledDate } = useDayAheadReviewDate({
+ *     projectId: "power-market",
+ *     serviceStartDay: "2024-01-01",
+ *   });
+ *
+ *   const { data, loading } = useQuery({
+ *     queryKey: ["review", tradingDay],
+ *     queryFn: () => fetchReviewData(tradingDay),
+ *   });
+ *
+ *   return (
+ *     <div style={{ height: "100vh", display: "flex", flexDirection: "column" }}>
+ *       <DayAheadReviewPage
+ *         date={date}
+ *         setDate={setDate}
+ *         disabledDate={disabledDate}
+ *         data={data ?? { power: [], price: [], table: [] }}
+ *         loading={loading}
+ *         onExport={(data, date) => exportToCSV(data, `review-${date}.csv`)}
+ *       />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export interface DayAheadReviewPageProps {
+    /**
+     * 当前选中的显示日期。
+     * 通常从 `useDayAheadReviewDate` 钩子获取。
+     */
+    date: Dayjs;
+    /**
+     * 更新选中日期的回调函数。
+     * 通常从 `useDayAheadReviewDate` 钩子获取。
+     */
+    setDate: (date: Dayjs) => void;
+    /**
+     * 判断日期选择器中某个日期是否应该被禁用的函数。
+     * 通常从 `useDayAheadReviewDate` 钩子获取。
+     */
+    disabledDate: (current: Dayjs | null) => boolean;
+    /**
+     * 包含电力、价格和表格数组的交易数据。
+     * 完整的一天应包含 96 个数据点（15 分钟间隔）。
+     */
+    data: DayAheadReviewPageData;
+    /**
+     * 在所有图表上显示加载骨架屏覆盖层。
+     *
+     * @optional
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * 错误对象 - 显示包含错误详情的提示消息。
+     *
+     * @optional
+     */
+    error?: Error;
+    /**
+     * 导出按钮触发的自定义导出处理函数。组件本身不实现导出逻辑；使用者需要提供自己的实现。
+     *
+     * 可以使用 `exportDayAheadReviewDataToExcel` 工具函数快速实现 Excel 导出：
+     *
+     * ```tsx
+     * import { exportDayAheadReviewDataToExcel } from "@tsingroc/tsingroc-components/utils";
+     *
+     * <DayAheadReviewPage
+     *   onExport={exportDayAheadReviewDataToExcel}
+     *   // ... 其他属性
+     * />
+     * ```
+     *
+     * @param data - 要导出的表格数据
+     * @param date - 格式化的日期字符串（YYYY-MM-DD）
+     * @param filename - 推荐的文件名（可以不使用）
+     *
+     * @optional
+     * @example
+     * ```tsx
+     * onExport={(data, dateStr) => {
+     *   const csv = convertToCSV(data);
+     *   downloadFile(csv, `day-ahead-review-${dateStr}.csv`);
+     * }}
+     * ```
+     */
+    onExport?: (data: ExtendedReviewValue[], date: string, filename: string) => void;
+}
+/**
+ * 日前复盘页面组件。
+ *
+ * 提供了一个全面的仪表板，用于分析电力市场日前交易表现。
+ * 以响应式布局展示策略对比、收益分布、价格趋势和详细的间隔数据。
+ *
+ * ## 功能特性
+ *
+ * - **策略对比图表** — 对比 Agent 与人工申报/中标电量
+ * - **价格走势图表** — 可视化日前价格与实时价格
+ * - **收益分布图表** — 分析收益细分及基准对比
+ * - **明细表格** — 查看间隔级别数据并支持导出
+ * - **跨图表高亮** — 所有可视化之间的同步悬停状态
+ */
+export default function DayAheadReviewPage({ date, setDate, disabledDate, data, loading, error, onExport, }: DayAheadReviewPageProps): import("react/jsx-runtime").JSX.Element;