@tsingroc/tsingroc-components 3.14.0 → 3.14.1

package/src/components/LineChartTable.tsx

@@ -0,0 +1,285 @@
+import type { ColumnsType, ColumnType, TableRef } from "antd/es/table";
+import { ConfigProvider, Flex, type FlexProps, Table, theme } from "antd";
+import type { ElementEvent, LineSeriesOption } from "echarts";
+import {
+  type TdHTMLAttributes,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { createStyles } from "antd-style";
+import EChartsReact from "echarts-for-react";
+
+import * as echarts from "../echarts";
+
+export interface LineChartTableProps extends Omit<FlexProps, "children"> {
+  /** X 轴的数据。*/
+  xData: (string | number)[];
+  /**
+   * X 轴的名称。
+   * @default "时间"
+   */
+  xName?: string;
+  /**
+   * Y 轴的名称。
+   * @default "数值"
+   */
+  yName?: string;
+  /** Y 轴的单位，默认不显示。*/
+  yUnit?: string;
+  /** 各个曲线的名称、数据和其它选项（颜色、插值模式等）。*/
+  series?: { name: string; data: number[]; option?: LineSeriesOption }[];
+  /**
+   * 折线图的高度。表格会自动占满剩余的高度。
+   * @default 175
+   */
+  chartHeight?: string | number;
+}
+
+interface DataItem {
+  key: number;
+  x: string | number;
+  [key: `y${string}`]: number;
+  hover?: true | number;
+}
+
+const EMPTY: [] = [];
+
+/**
+ * 折线图与表格的组合，用鼠标指向表格中的数据时会高亮折线图中的对应数据，反之亦然。
+ *
+ * 除了文档列出的属性外，多余的属性会被传递给最外层的 [Flex][1] 组件。
+ *
+ * [1]: https://ant-design.antgroup.com/components/flex-cn#api
+ */
+function LineChartTable(props: LineChartTableProps) {
+  const {
+    xData,
+    xName = "时间",
+    yName = "数值",
+    yUnit,
+    series = [],
+    chartHeight = 175,
+    ...rest
+  } = props;
+  // TODO i18n
+  const unitString = yUnit !== undefined ? `（${yUnit}）` : "";
+  const { cx, styles, theme: token } = useStyles();
+  const isDark =
+    useContext(ConfigProvider.ConfigContext).theme?.algorithm ===
+    theme.darkAlgorithm;
+  const echartsRef = useRef<EChartsReact>(null);
+  const tableRef = useRef<TableRef>(null);
+  type HoverSource = "chart" | "table";
+  const [[hoverSource, hoverXIndex, hoverY], setHover] = useState<
+    [] | [HoverSource, number] | [HoverSource, number, number]
+  >(EMPTY);
+  let [closestYIndex, closestY]: (number | undefined)[] = [];
+  if (hoverXIndex !== undefined && hoverY !== undefined) {
+    let minDist = Infinity;
+    series.forEach((series, index) => {
+      const y = series.data[hoverXIndex];
+      const dist = Math.abs(y - hoverY!);
+      if (dist < minDist) {
+        closestYIndex = index;
+        closestY = y;
+        minDist = dist;
+      }
+    });
+  }
+  const option = echarts.buildEChartsOption(
+    {
+      backgroundColor: "transparent",
+    },
+    echarts.useGrid({
+      option: {
+        id: "grid",
+        left: 12,
+        right: 42,
+        bottom: 40,
+      },
+      xAxis: {
+        name: xName,
+        data: xData,
+        axisPointer: {
+          value: xData[hoverXIndex ?? 0],
+          status: hoverXIndex !== undefined ? "show" : "hide",
+        },
+      },
+      yAxis: {
+        name: yName + unitString,
+        axisPointer: {
+          value: closestY,
+          status: closestY !== undefined ? "show" : "hide",
+        },
+      },
+      series: series.map((series) => echarts.lineSeries(series)),
+    }),
+    echarts.legend({
+      data: series.map((series) => series.name),
+      option: { right: 42 },
+    }),
+    {
+      axisPointer: [{ show: true, triggerOn: "none" }],
+      dataZoom: [{ orient: "horizontal", bottom: 8, filterMode: "empty" }],
+    },
+  );
+  useEffect(() => {
+    const inst = echartsRef.current?.getEchartsInstance()?.getZr();
+    if (!inst) return () => {};
+    const onMousemove = (event: ElementEvent) => {
+      const inst = echartsRef.current?.getEchartsInstance();
+      if (!inst) return;
+      const coord = [event.offsetX, event.offsetY];
+      if (inst.containPixel("grid", coord)) {
+        const [x, y] = inst.convertFromPixel("grid", coord);
+        setHover(["chart", x, y]);
+      } else {
+        setHover(EMPTY);
+      }
+    };
+    const onGlobalout = () => setHover(EMPTY);
+    inst.on("mousemove", onMousemove);
+    inst.on("globalout", onGlobalout);
+    return () => {
+      inst.off("mousemove", onMousemove);
+      inst.off("globalout", onGlobalout);
+    };
+  }, []);
+  useEffect(() => {
+    const inst = echartsRef.current?.getEchartsInstance();
+    if (!inst) return;
+    if (hoverXIndex !== undefined) {
+      inst.dispatchAction({
+        type: "highlight",
+        seriesIndex: closestYIndex,
+        dataIndex: hoverXIndex,
+      });
+      if (hoverSource === "chart") {
+        tableScrollTo(hoverXIndex);
+      }
+    } else {
+      inst.dispatchAction({
+        type: "downplay",
+      });
+    }
+  }, [hoverSource, hoverXIndex, closestYIndex]);
+  const tableDataWithoutHover: DataItem[] = useMemo(() => {
+    const data = xData.map((x, i) => ({ key: i, x }) as DataItem);
+    series.forEach((series) =>
+      series.data.forEach((y, i) => (data[i][`y${series.name}`] = y)),
+    );
+    return data;
+  }, [xData, series]);
+  const tableData: DataItem[] = useMemo(() => {
+    if (hoverSource === "chart" && hoverXIndex !== undefined) {
+      const data = [...tableDataWithoutHover];
+      data[hoverXIndex] = {
+        ...data[hoverXIndex],
+        hover: closestYIndex ?? true,
+      };
+      return data;
+    } else {
+      return tableDataWithoutHover;
+    }
+  }, [tableDataWithoutHover, hoverSource, hoverXIndex, closestYIndex]);
+  const tableColumns = useMemo((): ColumnsType<DataItem> => {
+    const columnWidth = `${100 / series.length}%`;
+    return [
+      {
+        key: "x",
+        dataIndex: "x",
+        title: xName,
+        onCell: (
+          data: DataItem,
+          index?: number,
+        ): TdHTMLAttributes<HTMLTableCellElement> => ({
+          className: cx({
+            [styles.rowHovered]: data.hover !== undefined,
+          }),
+          onMouseEnter: () => setHover(["table", index!]),
+          onMouseLeave: () => setHover(EMPTY),
+        }),
+      },
+      ...series.map(
+        (series, yIndex): ColumnType<DataItem> => ({
+          key: `y${series.name}`,
+          dataIndex: `y${series.name}`,
+          title: series.name + unitString,
+          width: columnWidth,
+          onCell: (
+            data: DataItem,
+            xIndex?: number,
+          ): TdHTMLAttributes<HTMLTableCellElement> => ({
+            className: cx(styles.cell, {
+              [styles.rowHovered]: data.hover !== undefined,
+              [styles.cellHovered]: data.hover === yIndex,
+            }),
+            onMouseEnter: () =>
+              setHover(["table", xIndex!, data[`y${series.name}`]]),
+            onMouseLeave: () => setHover(EMPTY),
+          }),
+        }),
+      ),
+    ];
+  }, [cx, styles, xName, series, unitString]);
+  const tableScrollTo = (index: number) => {
+    const table = tableRef.current?.nativeElement;
+    if (table) {
+      const header = table.getElementsByTagName("thead")[0];
+      const row = table.getElementsByTagName("tr")[index];
+      table.scrollTo({
+        top:
+          row.offsetTop +
+          row.offsetHeight / 2 -
+          (table.offsetHeight - header.offsetHeight) / 2,
+        behavior: "smooth",
+      });
+    }
+  };
+  return (
+    <Flex vertical gap={token.marginXS} {...rest}>
+      <EChartsReact
+        ref={echartsRef}
+        option={option}
+        theme={isDark ? "dark" : undefined}
+        style={{ height: chartHeight, flexShrink: 0 }}
+      />
+      {useMemo(
+        () => (
+          <Table<DataItem>
+            ref={tableRef}
+            dataSource={tableData}
+            columns={tableColumns}
+            size="small"
+            pagination={false}
+            style={{ flexBasis: "100%", overflowY: "auto" }}
+            onHeaderRow={() => ({
+              style: { position: "sticky", top: 0, zIndex: 1 },
+            })}
+          />
+        ),
+        [tableData, tableColumns],
+      )}
+    </Flex>
+  );
+}
+
+export default LineChartTable;
+
+const useStyles = createStyles(({ css, token }) => {
+  const rowHovered = css`
+    background: ${token.colorFillQuaternary};
+  `;
+  const cell = css`
+    [class] > &:hover:hover {
+      background: ${token.colorFillSecondary};
+    }
+  `;
+  const cellHovered = css`
+    background: ${token.colorFillSecondary};
+  `;
+  return { rowHovered, cell, cellHovered };
+});

package/src/components/LinkedLineChart.tsx

@@ -0,0 +1,223 @@
+import { ConfigProvider, theme } from "antd";
+import {
+  createContext,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+} from "react";
+import EChartsReact, { type EChartsReactProps } from "echarts-for-react";
+import type { LineSeriesOption, Payload } from "echarts";
+
+import * as echarts from "../echarts";
+
+interface LineChartLinkContext {
+  listeners: LinkEventListener[];
+  xData: (string | number)[];
+  xName: string;
+}
+
+type LinkEvent = { sourceId: string } & (
+  | { type: "highlight"; xIndex: number }
+  | { type: "downplay" }
+  | { type: "datazoom"; start: number; end: number }
+);
+type LinkEventListener = (event: LinkEvent) => void;
+
+const LineChartLinkContext = createContext<LineChartLinkContext>({
+  listeners: [],
+  xData: [],
+  xName: "时间",
+});
+
+export interface LineChartLinkProviderProps {
+  /** X 轴的数据。*/
+  xData: (string | number)[];
+  /**
+   * X 轴的名称。
+   * @default "时间"
+   */
+  xName?: string;
+  /** 包裹的内容，其中包含需要联动的 {@linkcode LinkedLineChart} 组件。*/
+  children: ReactNode;
+}
+
+/**
+ * {@linkcode LinkedLineChart} 联动上下文的 Provider。
+ *
+ * 用于包裹需要联动的 {@linkcode LinkedLineChart} 组件。
+ */
+export function LineChartLinkProvider(props: LineChartLinkProviderProps) {
+  const listenersRef = useRef<LinkEventListener[]>([]);
+
+  return (
+    <LineChartLinkContext.Provider
+      value={{
+        listeners: listenersRef.current,
+        xData: props.xData,
+        xName: props.xName ?? "时间",
+      }}
+    >
+      {props.children}
+    </LineChartLinkContext.Provider>
+  );
+}
+
+export interface LinkedLineChartProps
+  extends Omit<EChartsReactProps, "option"> {
+  /**
+   * Y 轴的名称。
+   * @default "数值"
+   */
+  yName?: string;
+  /** Y 轴的单位，默认不显示。*/
+  yUnit?: string;
+  /** 各个曲线的名称、数据和其它选项（颜色、插值模式等）。*/
+  series?: { name: string; data: number[]; option?: LineSeriesOption }[];
+  /**
+   * 是否启用横轴下方的缩放条（`dataZoom`）
+   * @default true
+   */
+  dataZoom?: boolean;
+}
+
+/**
+ * 折线图组件，支持多条数据曲线和横轴联动。鼠标悬停在图表上时会触发联动高亮。
+ */
+function LinkedLineChart(props: LinkedLineChartProps) {
+  const {
+    yName = "数值",
+    yUnit,
+    series = [],
+    dataZoom = true,
+    ...rest
+  } = props;
+  const unitString = yUnit !== undefined ? `（${yUnit}）` : "";
+  const isDark =
+    useContext(ConfigProvider.ConfigContext).theme?.algorithm ===
+    theme.darkAlgorithm;
+  const echartsRef = useRef<EChartsReact>(null);
+  const { listeners, xData, xName } = useContext(LineChartLinkContext);
+  const currentId = useId();
+  const option = echarts.buildEChartsOption(
+    {
+      backgroundColor: "transparent",
+    },
+    echarts.useGrid({
+      option: {
+        id: "grid",
+        left: 12,
+        right: 42,
+        bottom: dataZoom ? 40 : 0,
+      },
+      xAxis: {
+        name: xName,
+        data: xData,
+        axisPointer: { show: true },
+      },
+      yAxis: {
+        name: yName + unitString,
+        axisPointer: { show: false },
+      },
+      series: series.map((series) => echarts.lineSeries(series)),
+    }),
+    echarts.legend({
+      data: series.map((series) => series.name),
+      option: { right: 42 },
+    }),
+    echarts.tooltip({
+      trigger: "axis",
+      position: (
+        [x],
+        params,
+        dom,
+        rect,
+        { contentSize: [popupWidth], viewSize: [chartWidth] },
+      ) => [
+        x + 10 + popupWidth <= chartWidth ? x + 10 : x - 10 - popupWidth,
+        20,
+      ],
+    }),
+    {
+      dataZoom: [
+        {
+          show: dataZoom,
+          orient: "horizontal",
+          bottom: 8,
+          filterMode: "empty",
+        },
+      ],
+    },
+  );
+  const onEvents = useMemo(
+    () => ({
+      highlight: (payload: Payload) => {
+        const batch = payload.batch;
+        if (!batch || batch.length === 0) return;
+        listeners.forEach((listener) =>
+          listener({
+            type: "highlight",
+            sourceId: currentId,
+            xIndex: batch[0].dataIndex,
+          }),
+        );
+      },
+      downplay: () => {
+        listeners.forEach((listener) =>
+          listener({ type: "downplay", sourceId: currentId }),
+        );
+      },
+      datazoom: (payload: Payload) => {
+        listeners.forEach((listener) =>
+          listener({
+            type: "datazoom",
+            sourceId: currentId,
+            start: payload.start,
+            end: payload.end,
+          }),
+        );
+      },
+    }),
+    [currentId, listeners],
+  );
+  useEffect(() => {
+    const listener = (event: LinkEvent) => {
+      if (event.sourceId === currentId) return;
+      const chart = echartsRef.current?.getEchartsInstance();
+      if (!chart) return;
+      switch (event.type) {
+        case "highlight":
+          chart.dispatchAction(
+            { type: "showTip", seriesIndex: 0, dataIndex: event.xIndex },
+            { silent: true },
+          );
+          break;
+        case "downplay":
+          chart.setOption({ xAxis: { axisPointer: { status: "hide" } } });
+          chart.dispatchAction({ type: "hideTip" }, { silent: true });
+          break;
+        case "datazoom":
+          chart.dispatchAction(
+            { type: "dataZoom", start: event.start, end: event.end },
+            { silent: true },
+          );
+          break;
+      }
+    };
+    listeners.push(listener);
+    return () => listeners.splice(listeners.indexOf(listener), 1) && undefined;
+  }, [currentId, listeners]);
+  return (
+    <EChartsReact
+      ref={echartsRef}
+      option={option}
+      onEvents={onEvents}
+      theme={isDark ? "dark" : undefined}
+      {...rest}
+    />
+  );
+}
+
+export default LinkedLineChart;

package/src/components/QuickDateRangePicker.tsx

@@ -0,0 +1,84 @@
+import {
+  Button,
+  type ButtonProps,
+  DatePicker,
+  Space,
+  type SpaceProps,
+} from "antd";
+import dayjs, { type Dayjs } from "dayjs";
+import type { NoUndefinedRangeValueType } from "rc-picker/lib/PickerInput/RangePicker";
+import type { RangePickerProps } from "antd/es/date-picker";
+import { useState } from "react";
+
+export interface QuickDateRangePickerProps
+  extends Omit<SpaceProps, "onChange"> {
+  /** 一个二元组 `[start, end]`，表示时间段的开始和结束。*/
+  value?: NoUndefinedRangeValueType<Dayjs>;
+  onChange?: (range: NoUndefinedRangeValueType<Dayjs>) => void;
+  /**
+   * 内部按钮的属性，参见 [Ant Design 的 `Button` API][1]。
+   *
+   * [1]: https://ant-design.antgroup.com/components/button-cn#api
+   */
+  buttonProps?: ButtonProps;
+  /**
+   * 内部日期范围选择器的属性，参见 [Ant Design 的 `DatePicker.RangePicker` API][1]。
+   *
+   * [1]: https://ant-design.antgroup.com/components/date-picker-cn#rangepicker
+   */
+  pickerProps?: RangePickerProps;
+}
+
+const QUICK_PICK_RANGES = [
+  { value: 3, label: "最近 3 天" },
+  { value: 5, label: "最近 5 天" },
+  { value: 7, label: "最近 7 天" },
+];
+
+/**
+ * 带有快速选择最近 3/5/7 天功能的日期范围选择器。
+ *
+ * 除了文档中列出的属性外，该组件会将其它属性传递给 [Ant Design 的 `Space` 组件][1]。
+ *
+ * [1]: https://ant-design.antgroup.com/components/space-cn#api
+ */
+function QuickDateRangePicker(props: QuickDateRangePickerProps) {
+  const { value, onChange, buttonProps, pickerProps, ...rest } = props;
+  const [range, setRange] =
+    value === undefined
+      ? // eslint-disable-next-line react-hooks/rules-of-hooks
+        useState<NoUndefinedRangeValueType<Dayjs> | undefined>(undefined)
+      : [value, () => {}];
+  function quickPick(value: number) {
+    const end = dayjs();
+    const start = end.subtract(value - 1, "day");
+    const newRange: NoUndefinedRangeValueType<Dayjs> = [start, end];
+    setRange(newRange);
+    onChange?.(newRange);
+  }
+  return (
+    <Space {...rest}>
+      {/* TODO i18n */}
+      {QUICK_PICK_RANGES.map((item, index) => (
+        <Button
+          key={index}
+          onClick={() => quickPick(item.value)}
+          {...buttonProps}
+        >
+          {item.label}
+        </Button>
+      ))}
+      <DatePicker.RangePicker
+        value={range}
+        allowClear={false}
+        onChange={(range) => {
+          setRange(range!);
+          onChange?.(range!); // 由于 allowClear=false，这里 range 不可能为 null
+        }}
+        {...pickerProps}
+      />
+    </Space>
+  );
+}
+
+export default QuickDateRangePicker;

package/src/components/SegmentedButtons.tsx

@@ -0,0 +1,46 @@
+import { Radio, type RadioGroupProps } from "antd";
+
+/**
+ * 分段单选按钮。
+ *
+ * 该组件是 [Ant Design 的 `Radio.Group optionType="button"`][1] 的别名。
+ *
+ * [1]: https://ant-design.antgroup.com/components/radio-cn#radiogroup
+ */
+function SegmentedButtons(props: RadioGroupProps) {
+  return <Radio.Group optionType="button" {...props} />;
+}
+
+// TODO i18n
+const TIME_UNIT_OPTIONS = [
+  { label: "日", value: "day" },
+  { label: "周", value: "week" },
+  { label: "月", value: "month" },
+];
+
+export interface TimeUnitSwitcherProps
+  extends Omit<RadioGroupProps, "onChange"> {
+  value?: "day" | "week" | "month";
+  onChange?: (value: "day" | "week" | "month") => void;
+}
+
+/**
+ * 时间单位（日/周/月）切换按钮。
+ *
+ * 该组件是 {@linkcode SegmentedButtons} 的特化版本。更多属性参见 [`Radio.Group`][1]。
+ *
+ * [1]: https://ant-design.antgroup.com/components/radio-cn#radiogroup
+ */
+export function TimeUnitSwitcher(props: TimeUnitSwitcherProps) {
+  const { onChange, ...rest } = props;
+  return (
+    <Radio.Group
+      optionType="button"
+      options={TIME_UNIT_OPTIONS}
+      onChange={(e) => onChange?.(e.target.value)}
+      {...rest}
+    />
+  );
+}
+
+export default SegmentedButtons;