@tsingroc/tsingroc-components 3.14.0 → 4.0.0

package/src/echarts/series.ts

@@ -0,0 +1,441 @@
+import type {
+  Color,
+  BarSeriesOption as OrigBarSeriesOption,
+  BoxplotSeriesOption as OrigBoxplotSeriesOption,
+  LineSeriesOption as OrigLineSeriesOption,
+  PieSeriesOption as OrigPieSeriesOption,
+} from "echarts";
+
+import type { EChartsSeries } from ".";
+
+export type DataItem = number | string | undefined;
+
+export type LineSeriesPreset = (option: OrigLineSeriesOption) => void;
+
+export interface LineSeriesOption {
+  /** 系列名称，不可与其他系列重名。*/
+  name: string;
+  /**
+   * 折线的数据。
+   *
+   * 数据的结构是二维数组，每一行表示一个数据点，第一、第二列分别代表两个轴。
+   * 若两个轴中有且只有一个是类目轴，则数据类型可以是一维数组，表示另一个轴的值。
+   */
+  data: [DataItem, DataItem, ...DataItem[]][] | DataItem[];
+  /**
+   * 其它需要添加到系列上的选项，参见 [ECharts 文档][1]。优先级**低于**预设 `presets`。
+   *
+   * [1]: https://echarts.apache.org/zh/option.html#series-line
+   */
+  option?: OrigLineSeriesOption;
+  /**
+   * 需要应用的配置预设。预设的优先级**高于** `option`。
+   *
+   * 可用的预设：{@linkcode gradientArea}
+   */
+  presets?: LineSeriesPreset[];
+}
+
+/**
+ * 在坐标系上添加一条折线。
+ */
+export function lineSeries(
+  option: LineSeriesOption,
+): EChartsSeries<OrigLineSeriesOption> {
+  const series: OrigLineSeriesOption = {
+    type: "line",
+    id: option.name,
+    name: option.name,
+    data: option.data,
+    smooth: true,
+    showSymbol: false,
+    ...option.option,
+  };
+  option.presets?.forEach((preset) => preset(series));
+  return { series: [series] };
+}
+
+/**
+ * 折线图预设，使折线下方区域在纵向呈现线性渐变色。
+ *
+ * 参数 `top` 表示顶部颜色；参数 `bottom` 表示底部颜色，默认为全透明 `"transparent"`。
+ */
+export function gradientArea(
+  top: string,
+  bottom: string = "transparent",
+): LineSeriesPreset {
+  return (option) => {
+    (option.areaStyle ??= {}).color = {
+      type: "linear",
+      x: 0,
+      y: 0,
+      x2: 0,
+      y2: 1,
+      colorStops: [
+        {
+          offset: 0,
+          color: top,
+        },
+        {
+          offset: 1,
+          color: bottom,
+        },
+      ],
+    };
+  };
+}
+
+export interface IntervalSeriesOption {
+  /** 系列名称，不可与其他系列重名。*/
+  name: string;
+  /**
+   * 区间的下边界，请将最小值数据填入此处。其它设置参见 [ECharts 文档][1]。
+   *
+   * [1]: https://echarts.apache.org/zh/option.html#series-line
+   */
+  min: OrigLineSeriesOption & { data: number[] };
+  /**
+   * 区间的上边界，请将最小值数据填入此处。其它设置参见 [ECharts 文档][1]。
+   *
+   * [1]: https://echarts.apache.org/zh/option.html#series-line
+   */
+  max: OrigLineSeriesOption & { data: number[] };
+  /**
+   * 区间条带，此处必须设置一个颜色。其它设置参见 [ECharts 文档][1]。
+   *
+   * [1]: https://echarts.apache.org/zh/option.html#series-line
+   */
+  interval: OrigLineSeriesOption & { color: Color };
+}
+
+const INTERVAL_SERIES_DEFAULTS: OrigLineSeriesOption = {
+  type: "line",
+  smooth: true,
+  showSymbol: false,
+  lineStyle: { opacity: 0 },
+  emphasis: { disabled: true },
+};
+
+/** 绘制一个从下边界到上边界的带状区间。*/
+export function intervalSeries(
+  option: IntervalSeriesOption,
+): EChartsSeries<OrigLineSeriesOption> {
+  // TODO i18n
+  const min: OrigLineSeriesOption = {
+    id: option.name + "下边界",
+    name: option.name + "下边界",
+    stack: option.name,
+    ...INTERVAL_SERIES_DEFAULTS,
+    ...option.min,
+  };
+  const max: OrigLineSeriesOption = {
+    id: option.name + "上边界",
+    name: option.name + "上边界",
+    ...INTERVAL_SERIES_DEFAULTS,
+    ...option.max,
+  };
+  const interval: OrigLineSeriesOption = {
+    id: option.name,
+    name: option.name,
+    stack: option.name,
+    stackStrategy: "all",
+    symbol: "none",
+    data: Array.from(
+      { length: option.min.data.length },
+      (_, i) => option.max.data[i] - option.min.data[i],
+    ),
+    ...INTERVAL_SERIES_DEFAULTS,
+    ...option.interval,
+    tooltip: { show: false, ...option.interval.tooltip },
+    areaStyle: { color: option.interval.color, ...option.interval.areaStyle },
+  };
+  return { series: [min, interval, max] };
+}
+
+export interface WindLineSeriesOption {
+  /** 系列名称，不可与其他系列重名。*/
+  name: string;
+  /**
+   * 风力数据，支持两种形式：
+   *
+   * - `type: "cartesian"`，用沿经线和沿纬线的风速分量表示风力；
+   * - `type: "polar"`，用风速和风向表示风力。
+   */
+  data:
+    | {
+        type: "cartesian";
+        /** 沿纬线向**东**吹（西风）的风速分量，单位 m/s。*/
+        u: number[];
+        /** 沿经线向**北**吹（南风）的风速分量，单位 m/s。*/
+        v: number[];
+      }
+    | {
+        type: "polar";
+        /** 风速，单位 m/s。*/
+        speed: number[];
+        /** 风向，单位是角度（deg），`0` 表示**北风**（往南吹），随着角度增大，风向**顺时针**旋转。*/
+        direction: number[];
+      };
+  /**
+   * 风向标的宽度和长度。
+   * @default [10, 20]
+   */
+  symbolSize?: [number, number];
+  /**
+   * 其它需要添加到系列上的选项，参见 [ECharts 文档][1]。优先级**低于**预设 `presets`。
+   *
+   * [1]: https://echarts.apache.org/zh/option.html#series-line
+   */
+  option?: OrigLineSeriesOption;
+  /**
+   * 需要应用的配置预设。预设的优先级**高于** `option`。
+   *
+   * 可用的预设：{@linkcode gradientArea}
+   */
+  presets?: LineSeriesPreset[];
+}
+
+/**
+ * 风速风向折线图。
+ */
+export function windLineSeries(
+  option: WindLineSeriesOption,
+): EChartsSeries<OrigLineSeriesOption> {
+  const data = option.data;
+  const { speed, direction } =
+    data.type === "polar"
+      ? data
+      : {
+          speed: data.u.map((u, i) => Math.sqrt(u * u + data.v[i] * data.v[i])),
+          direction: data.u.map(
+            (u, i) => (Math.atan2(-u, -data.v[i]) / Math.PI) * 180,
+          ),
+        };
+  const symbolSize = option.symbolSize ?? [10, 20];
+  const series: OrigLineSeriesOption = {
+    type: "line",
+    id: option.name,
+    name: option.name,
+    data: speed,
+    smooth: true,
+    symbol: "arrow",
+    symbolSize: symbolSize,
+    symbolOffset: (data, param) => {
+      const rad = (direction[param.dataIndex] / 180) * Math.PI;
+      const halfSize = symbolSize[1] / 2;
+      return [-halfSize * Math.sin(rad), halfSize * Math.cos(rad)];
+    },
+    symbolRotate: (data, param) => 180 - direction[param.dataIndex],
+    ...option.option,
+    itemStyle: {
+      borderWidth: 1,
+      borderColor: "#fff",
+      ...option.option?.itemStyle,
+    },
+    tooltip: {
+      valueFormatter: (value, index) =>
+        (value as number).toFixed(2) +
+        " m/s，" +
+        WIND_DIRECTIONS[(Math.round(direction[index] / 45) + 8) % 8] +
+        "风",
+      ...option.option?.tooltip,
+    },
+  };
+  option.presets?.forEach((preset) => preset(series));
+  return { series: [series] };
+}
+
+const WIND_DIRECTIONS = [
+  "北",
+  "东北",
+  "东",
+  "东南",
+  "南",
+  "西南",
+  "西",
+  "西北",
+];
+
+export interface MaxBarSeriesOption {
+  /** 系列名称，不可与其他系列重名。*/
+  name: string;
+  /** 需要求最大值的各个系列的数据。*/
+  data: (number | undefined)[][];
+  /** 各个系列的颜色，各个最大值条形将被设为对应的颜色。若留空，则使用默认颜色。*/
+  palette?: Color[];
+  /**
+   * 其它需要添加到系列上的选项，参见 [ECharts 文档][1]。
+   *
+   * [1]: https://echarts.apache.org/zh/option.html#series-bar
+   */
+  option?: OrigBarSeriesOption;
+}
+
+/** 求出多个系列的最大值，显示为条形图。*/
+export function maxBarSeries(
+  option: MaxBarSeriesOption,
+): EChartsSeries<OrigBarSeriesOption> {
+  const series: OrigBarSeriesOption = {
+    type: "bar",
+    id: option.name,
+    name: option.name,
+    data: Array.from({ length: option.data[0].length }, (_, i) => {
+      // prettier-ignore
+      const [max, maxJ] = option.data
+        .map((series) => series[i])
+        .reduce<[number | undefined, number]>(
+          ([max, maxJ], y, j) =>
+            max === undefined || (y !== undefined && y > max)
+            ? [y, j]
+            : [max, maxJ],
+          [undefined, -1]
+        );
+      if (max !== undefined && option.palette) {
+        return {
+          value: max,
+          itemStyle: {
+            color: option.palette[maxJ],
+          },
+        };
+      } else {
+        return max;
+      }
+    }),
+    ...option.option,
+    itemStyle: { opacity: 0.7, ...option.option?.itemStyle },
+    tooltip: { show: false, ...option.option?.tooltip },
+  };
+  return { series: [series] };
+}
+
+/** 饼图的数据项。*/
+export type PieDataItem = (OrigPieSeriesOption["data"] & {})[0] extends
+  | number
+  | string
+  | unknown[]
+  | infer T
+  ? T
+  : never;
+
+export type PieSeriesPreset = (option: OrigPieSeriesOption) => void;
+
+export interface PieSeriesOption {
+  /** 系列名称，不可与其他系列重名。*/
+  name: string;
+  /** 饼图的数据，数组元素可以是单个数值或者一个对象。*/
+  data: (number | PieDataItem)[];
+  /**
+   * 其它需要添加到系列上的选项，参见 [ECharts 文档][1]。优先级**低于**预设 `presets`。
+   *
+   * [1]: https://echarts.apache.org/zh/option.html#series-pie
+   */
+  option?: OrigPieSeriesOption;
+  /**
+   * 需要应用的配置预设。预设的优先级**高于** `option`。
+   *
+   * 可用的预设：{@linkcode ringPie}
+   */
+  presets?: PieSeriesPreset[];
+}
+
+/**
+ * 添加一个饼图。
+ *
+ * 请使用 ECharts 的 legend 组件来添加图例，不要手动编写 React 代码制作图例。
+ */
+export function pieSeries(
+  option: PieSeriesOption,
+): EChartsSeries<OrigPieSeriesOption> {
+  const series: OrigPieSeriesOption = {
+    type: "pie",
+    id: option.name,
+    name: option.name,
+    data: option.data,
+    ...option.option,
+  };
+  option.presets?.forEach((preset) => preset(series));
+  return { series: [series] };
+}
+
+const RING_PIE = (option: OrigPieSeriesOption) => {
+  option.radius = ["43%", "75%"];
+  option.avoidLabelOverlap = false;
+  option.label = {
+    show: false,
+    position: "center",
+  };
+  option.labelLine = {
+    show: false,
+  };
+  option.emphasis = {
+    label: {
+      show: true,
+      fontSize: 16,
+      fontWeight: "bold",
+    },
+  };
+};
+
+/** 饼图预设，使饼图变为环状，标签出现在环的中央。*/
+export function ringPie(): PieSeriesPreset {
+  return RING_PIE;
+}
+
+export interface BoxplotSeriesOption {
+  /** 系列名称，不可与其他系列重名。*/
+  name: string;
+  /** 箱线图的数据，每一行按顺序分别是最小值、下四分位数、中位数、上四分位数、最大值。*/
+  data: [number, number, number, number, number][];
+  /**
+   * 每个数据值的格式化函数。
+   * @default (value) => value.toFixed(2)
+   */
+  valueFormatter?: (value: number) => string;
+  /**
+   * 其它需要添加到系列上的选项，参见 [ECharts 文档][1]。
+   *
+   * [1]: https://echarts.apache.org/zh/option.html#series-boxplot
+   */
+  option?: OrigBoxplotSeriesOption;
+}
+
+/** 在坐标系上添加一组箱线图。*/
+export function boxplotSeries(
+  option: BoxplotSeriesOption,
+): EChartsSeries<OrigBoxplotSeriesOption> {
+  const valueFormatter = option.valueFormatter ?? ((value) => value.toFixed(2));
+  const series: OrigBoxplotSeriesOption = {
+    type: "boxplot",
+    id: option.name,
+    name: option.name,
+    data: option.data,
+    ...option.option,
+    tooltip: {
+      formatter: (param) => {
+        // prettier-ignore
+        const data = param.data as (
+          [number | string, number, number, number, number, number]
+        );
+        const strong = (body: string) =>
+          `<strong style="text-align: right;">${body}</strong>`;
+        // TODO i18n
+        return `
+          ${param.name}<br>
+          <div style="
+            display: inline-grid;
+            grid: auto-flow / auto auto;
+            gap: 0 20px;
+          ">
+            最大值 ${strong(valueFormatter(data[5]))}
+            上四分位数 ${strong(valueFormatter(data[4]))}
+            中位数 ${strong(valueFormatter(data[3]))}
+            下四分位数 ${strong(valueFormatter(data[2]))}
+            最小值 ${strong(valueFormatter(data[1]))}
+          </div>
+        `;
+      },
+      ...option.option?.tooltip,
+    },
+  };
+  return { series: [series] };
+}

package/src/echarts/tooltip.ts

@@ -0,0 +1,17 @@
+import type { TooltipComponentOption } from "echarts";
+
+import type { EChartsComponent } from ".";
+
+/**
+ * 添加悬停提示。这只是对官方 tooltip 组件的简单包装，设置参见 [ECharts 文档][1]。
+ *
+ * **注意**：ECharts 尚不支持多个 tooltip，在含有多个图表的
+ * ECharts 实例中 tooltip 的 `trigger` 值必须支持所有图表。
+ * 因此，若需要对每个图表使用不同的 tooltip 设置，请将其拆分成多个
+ * ECharts 实例。
+ *
+ * [1]: https://echarts.apache.org/zh/option.html#tooltip
+ */
+export function tooltip(option: TooltipComponentOption = {}): EChartsComponent {
+  return { tooltip: [option] };
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+export {
+  AuthProvider,
+  type AuthProviderProps,
+  AuthCheck,
+  type AuthCheckProps,
+  AuthCallback,
+  type AuthCallbackProps,
+  useAuth,
+  type Auth,
+  type CasdoorAuth,
+  type LocalAuth,
+} from "./components/Auth";
+
+export { default as Calendar, type CalendarProps } from "./components/Calendar";
+
+export {
+  default as CircularProgress,
+  type CircularProgressProps,
+} from "./components/CircularProgress";
+
+export { default as Header, type HeaderProps } from "./components/Header";
+
+export {
+  default as ImageBackground,
+  type ImageBackgroundProps,
+} from "./components/ImageBackground";
+
+export {
+  default as IndicatorLight,
+  type IndicatorLightProps,
+} from "./components/IndicatorLight";
+
+export {
+  default as LineChartEditor,
+  type LineChartEditorProps,
+} from "./components/LineChartEditor";
+
+export {
+  default as LineChartTable,
+  type LineChartTableProps,
+} from "./components/LineChartTable";
+
+export {
+  default as LinkedLineChart,
+  LineChartLinkProvider,
+  type LinkedLineChartProps,
+  type LineChartLinkProviderProps,
+} from "./components/LinkedLineChart";
+
+export {
+  default as QuickDateRangePicker,
+  type QuickDateRangePickerProps,
+} from "./components/QuickDateRangePicker";
+
+export {
+  default as SegmentedButtons,
+  TimeUnitSwitcher,
+  type TimeUnitSwitcherProps,
+} from "./components/SegmentedButtons";
+
+export { default as Sidebar, type SidebarProps } from "./components/Sidebar";
+
+export {
+  default as TsingrocDatePicker,
+  type DatePickerProps,
+} from "./components/TsingrocDatePicker";
+
+export {
+  default as TsingrocTheme,
+  type TsingrocThemeProps,
+} from "./components/TsingrocTheme";
+
+export {
+  default as UserButton,
+  type UserButtonProps,
+} from "./components/UserButton";
+
+export {
+  default as WeatherMap,
+  type WeatherMapProps,
+  type WeatherData,
+} from "./components/WeatherMap";