@tsingroc/tsingroc-components 5.0.0-alpha.11 → 5.0.0-alpha.13

package/src/components/Calendar.tsx

@@ -1,182 +0,0 @@
-import { createStyles } from "antd-style";
-import dayjs, { type Dayjs } from "dayjs";
-import localeData from "dayjs/plugin/localeData";
-import { useState } from "react";
-
-export interface CalendarProps
-  extends Omit<React.HTMLAttributes<HTMLTableElement>, "onChange"> {
-  /**
-   * 当前显示的月份。
-   *
-   * 注意：传入的月份的时区会决定整个日历所用的时区。
-   */
-  month: Dayjs;
-  /** 当前选中的日期。*/
-  selected?: Dayjs;
-  /** 选中日期更改时的回调函数。*/
-  onChange?: (selected: Dayjs) => void;
-  /**
-   * 无论一个月需要占用多少周，都总是显示 6 周。
-   * @default false
-   */
-  alwaysSixWeeks?: boolean;
-  /**
-   * 淡化第一周和最后几周不属于本月的日期。
-   * @default true
-   */
-  fadeAdjacentDays?: boolean;
-  /**
-   * 表头单元格的属性，详见 [MDN][1]。可以通过设置这里的 `children` 来自定义表头内容。
-   *
-   * [1]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/th
-   */
-  thProps?: (
-    /**
-     * 范围 0-6，表示一周的第几天
-     *
-     * 注意：这个数字的含义会受到地区设置的影响！请使用 `dayjs.weekdays()` 获取每一天的名称。
-     */
-    weekday: number,
-  ) => React.HTMLAttributes<HTMLTableCellElement>;
-  /**
-   * 日期单元格的属性，详见 [MDN][1]。可以通过设置这里的 `children` 来自定义单元格内容。
-   *
-   * [1]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/td
-   */
-  tdProps?: (
-    date: Dayjs,
-    selected: boolean,
-  ) => React.HTMLAttributes<HTMLTableCellElement>;
-}
-
-dayjs.extend(localeData);
-
-const useStyles = createStyles(({ token, css, cx }) => {
-  const calendarFade = css`
-    color: ${token.colorTextDisabled};
-  `;
-  const calendarSelected = css`
-    background: ${token.colorPrimaryBg};
-    color: ${token.colorPrimary};
-  `;
-  const calendar = css`
-    box-sizing: border-box;
-    width: 100%;
-    height: 100%;
-    border-collapse: collapse;
-    font-family: ${token.fontFamily};
-    font-size: ${token.fontSize}px;
-    line-height: ${token.lineHeight};
-    user-select: none;
-
-    > thead > tr > th {
-      box-sizing: border-box;
-      height: ${token.fontSize * token.lineHeight + token.paddingXXS * 2}px;
-      padding: ${token.paddingXXS}px;
-      font-weight: normal;
-    }
-
-    > tbody > tr > td {
-      box-sizing: border-box;
-      width: calc(100% / 7);
-      border: 1px solid ${token.colorBorder};
-      padding: ${token.paddingXXS}px;
-      vertical-align: bottom;
-      transition:
-        background ease ${token.motionDurationFast},
-        color ease ${token.motionDurationFast};
-
-      &:hover:not(.${cx(calendarSelected)}) {
-        background: ${token.colorBgTextHover};
-      }
-    }
-  `;
-  return {
-    calendar,
-    calendarFade,
-    calendarSelected,
-  };
-});
-
-/**
- * 一个日历组件。
- *
- * 除了文档列出的属性之外，也接受所有 [HTML Table 元素][1] 接受的属性。
- *
- * [1]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table
- */
-function Calendar(props: CalendarProps) {
-  const {
-    month,
-    selected: propsSelected,
-    onChange,
-    alwaysSixWeeks,
-    fadeAdjacentDays = true,
-    thProps,
-    tdProps,
-    className,
-    ...rest
-  } = props;
-  const { cx, styles } = useStyles();
-
-  const [selected, setSelected] =
-    propsSelected === undefined
-      ? // eslint-disable-next-line react-hooks/rules-of-hooks
-        useState<Dayjs | undefined>()
-      : [propsSelected, () => {}];
-
-  const monthStart = month.startOf("month");
-  const calendarStart = monthStart.startOf("week");
-  const monthEnd = month.endOf("month");
-  const minWeeks = Math.ceil(monthEnd.diff(calendarStart, "week", true));
-  const weekdays = [...dayjs.weekdaysShort()];
-  // 按地区设置调整一周的第一天
-  weekdays.splice(0, 0, ...weekdays.splice(calendarStart.day()));
-  return (
-    <table {...rest} className={cx(styles.calendar, className)}>
-      <thead>
-        <tr>
-          {weekdays.map((name, weekday) => (
-            <th key={weekday} children={name} {...thProps?.(weekday)} />
-          ))}
-        </tr>
-      </thead>
-      <tbody>
-        {Array.from({ length: alwaysSixWeeks ? 6 : minWeeks }, (_, week) => (
-          <tr key={week}>
-            {Array(7)
-              .fill(null)
-              .map((_, weekday) => {
-                const date = calendarStart.add(week * 7 + weekday, "day");
-                const fade =
-                  fadeAdjacentDays && date.month() != monthStart.month();
-                const isSelected =
-                  Math.floor(selected?.diff(date, "day", true) ?? NaN) === 0;
-                const { className, ...props } = tdProps?.(date, false) ?? {};
-                return (
-                  <td
-                    key={weekday}
-                    children={date.date()}
-                    onClick={() => {
-                      setSelected(date);
-                      onChange?.(date);
-                    }}
-                    {...props}
-                    className={cx(
-                      {
-                        [styles.calendarFade]: fade,
-                        [styles.calendarSelected]: isSelected,
-                      },
-                      className,
-                    )}
-                  />
-                );
-              })}
-          </tr>
-        ))}
-      </tbody>
-    </table>
-  );
-}
-
-export default Calendar;

package/src/components/CircularProgress.tsx

@@ -1,38 +0,0 @@
-import { Progress, type ProgressProps } from "antd";
-import type { ProgressGradient } from "antd/es/progress/progress";
-
-export interface CircularProgressProps
-  extends ProgressProps,
-    React.RefAttributes<HTMLDivElement> {
-  /** 进度百分比，范围是 0-100。*/
-  progress?: number;
-  /**
-   * 进度条已完成部分的颜色。
-   * @default "#34A9D4"
-   */
-  color?: string | string[] | ProgressGradient;
-}
-
-/**
- * 环形进度条。
- *
- * 本组件基于 [Ant Design 的 `Progress`][1] 自定义而来。
- * 因此，除了文档中列出的属性以外，也兼容 `Progress` 的所有属性。
- *
- * [1]: https://ant-design.antgroup.com/components/progress-cn
- */
-function CircularProgress(props: CircularProgressProps) {
-  return (
-    <Progress
-      type="circle"
-      percent={props.progress}
-      strokeLinecap="butt"
-      strokeWidth={9}
-      strokeColor={props.color ?? "#34A9D4"}
-      trailColor="#22405A"
-      {...props}
-    />
-  );
-}
-
-export default CircularProgress;

package/src/components/ConnectedECharts.tsx

@@ -1,62 +0,0 @@
-import * as echarts from "echarts/core";
-import {
-  createContext,
-  use,
-  useId,
-  type ComponentType,
-  type ReactNode,
-} from "react";
-
-import AutoResizedECharts, { type withAutoResize } from "./AutoResizedECharts"; // eslint-disable-line @typescript-eslint/no-unused-vars
-import type { EChartsHOCType, EChartsProps } from "./ECharts";
-
-const EChartsConnectorContext = createContext<string>("default");
-
-/**
- * 为 {@linkcode ConnectedECharts}/{@linkcode withConnector | withConnector(ECharts)}
- * 提供联动上下文，只有同一个上下文内的 ECharts 会联动。
- */
-export function EChartsConnector({ children }: { children: ReactNode }) {
-  const group = useId();
-  return (
-    <EChartsConnectorContext.Provider value={group}>
-      {children}
-    </EChartsConnectorContext.Provider>
-  );
-}
-
-/**
- * 为 ECharts 增加联动能力。所有添加了该能力的 ECharts 都会相互联动。
- *
- * 可以使用 {@linkcode EChartsConnector} 将同一个页面上的 ECharts
- * 划分为多个组，不同组的 ECharts 不会联动。也可以使用 `group` 属性手动指定联动组。
- */
-export const withConnector: EChartsHOCType<{ group?: string }> =
-  <Props extends EChartsProps>(ECharts: ComponentType<Props>) =>
-  (props: Props & { group?: string }) => {
-    "use memo";
-    const contextGroup = use(EChartsConnectorContext);
-    const { onInit, group = contextGroup, ...rest } = props;
-    return (
-      // @ts-expect-error 见 ./AutoResizedECharts.tsx
-      <ECharts
-        onInit={(instance) => {
-          instance.group = group;
-          echarts.connect(group);
-          return onInit?.(instance);
-        }}
-        {...rest}
-      />
-    );
-  };
-
-/**
- * 预置了联动和自适应容器尺寸能力的 ECharts。
- *
- * @see {@linkcode withConnector}
- * @see {@linkcode withAutoResize}
- */
-const ConnectedECharts = Object.assign(withConnector(AutoResizedECharts), {
-  displayName: "ConnectedECharts",
-});
-export default ConnectedECharts;

package/src/components/ECharts.tsx

@@ -1,206 +0,0 @@
-import type { EChartsOption } from "echarts";
-import type {
-  EChartsCoreOption,
-  EChartsInitOpts,
-  ECharts as EChartsInstance,
-  SetOptionOpts,
-} from "echarts/core";
-import * as echarts from "echarts/core";
-import {
-  useEffect,
-  useEffectEvent,
-  useImperativeHandle,
-  useRef,
-  type ComponentType,
-  type HTMLAttributes,
-  type ReactNode,
-  type Ref,
-  type RefObject,
-} from "react";
-
-import { debugAssert } from "../utils/debug";
-
-export interface EChartsProps<Option extends EChartsCoreOption = EChartsOption>
-  extends HTMLAttributes<HTMLDivElement> {
-  /**
-   * 用于命令式操作 ECharts 容器和实例的 ref。
-   *
-   * 注意 effect 首次执行时 ECharts 实例尚未被创建。如果需要在 ECharts
-   * 实例上添加事件监听器或者执行其它的初始化操作，请使用 {@linkcode onInit}。
-   */
-  ref?: Ref<EChartsRef>;
-  /** 主题。 @default "default" */
-  theme?: string | Record<string, any> | null;
-  /**
-   * 初始化实例时的选项。
-   *
-   * 修改该属性会导致 ECharts 实例被销毁并重新创建，因此建议不要频繁修改该属性，并且推荐使用
-   * React Compiler 或者 useMemo 将该属性记忆化。
-   */
-  initOpts?: EChartsInitOpts;
-  /** 配置对象。 */
-  option?: Option;
-  /**
-   * 更新 {@linkcode option} 时的选项。其中的 {@linkcode SetOptionOpts.silent | silent}
-   * 选项也会在更新 {@linkcode theme} 时使用。
-   *
-   * 注意该属性变化后只会从下一次 option 更新开始生效。
-   */
-  setOptionOpts?: SetOptionOpts;
-  /**
-   * 初始化实例（`echarts.init()`）后执行的回调。如果返回函数，则会在销毁实例（`instance.dispose()`）之前调用。
-   *
-   * 推荐在这个回调中为 ECharts 实例添加事件监听器。
-   */
-  onInit?: (instance: EChartsInstance) => void | undefined | (() => void);
-  /** option 更新（`instance.setOption()`）后执行的回调。注意如果设置了 {@linkcode lazyUpdate}，那么这个回调大概率没什么用。 */
-  onSetOption?: (instance: EChartsInstance) => void;
-}
-
-export interface EChartsRef {
-  /** 容纳 ECharts 画布的 div 容器。 */
-  container: HTMLDivElement;
-  /** ECharts 实例。注意该实例在 ref 连接时尚未创建，如果要在实例创建时执行代码请使用 {@linkcode EChartsProps.onInit | onInit} 属性。 */
-  instance?: EChartsInstance;
-}
-
-/** 用于 HOC 的返回值。 */
-export type EChartsComponentType<Extra> = <
-  Option extends EChartsCoreOption = EChartsOption,
->(
-  props: EChartsProps<Option> & Extra,
-) => ReactNode;
-
-/** 用于方便定义 HOC。 */
-export interface EChartsHOCType<Extra = {}> {
-  <PrevExtra>(
-    ECharts: EChartsComponentType<PrevExtra>,
-  ): EChartsComponentType<PrevExtra & Extra>;
-  <Props extends EChartsProps>(
-    ECharts: (props: Props) => ReactNode,
-  ): (props: Props & Extra) => ReactNode;
-  <Props extends EChartsProps>(
-    ECharts: ComponentType<Props>,
-  ): ComponentType<Props & Extra>;
-}
-
-/**
- * ECharts 的 React 封装，支持 `theme`、`opts` 等初始化参数和 `option` 配置的响应式更新。
- */
-const ECharts: EChartsComponentType<{}> = <
-  Option extends EChartsCoreOption = EChartsOption,
->(
-  props: EChartsProps<Option>,
-) => {
-  const {
-    ref: outerRef,
-    theme,
-    initOpts: opts,
-    option,
-    setOptionOpts,
-    onInit,
-    onSetOption,
-    ...rest
-  } = props;
-
-  const ref = useRef<EChartsRef>(null);
-  useForwardEChartsRef(outerRef, ref);
-
-  // theme 变化时，设置 theme
-  const setTheme = useEffectEvent(
-    (theme: string | Record<string, any> | null | undefined) => {
-      debugAssert(ref.current, "effect should run after ref is connected");
-      ref.current.instance?.setTheme(theme ?? "default", {
-        silent: setOptionOpts?.silent,
-      });
-    },
-  );
-  // 没必要判断是否首次运行，因为首次运行时 ref.current?.instance 必定为 undefined
-  useEffect(() => setTheme(theme), [theme]);
-
-  // option 变化时，设置 option
-  const setOption = useEffectEvent(
-    (option: Option, isInit: boolean = false) => {
-      debugAssert(ref.current, "effect should run after ref is connected");
-      const { instance } = ref.current;
-      if (instance) {
-        instance.setOption(option, {
-          ...setOptionOpts,
-          // 在实例创建时，由于我们已经处在一个 animation frame，没必要再等待下一个 animation frame
-          lazyUpdate: !isInit && setOptionOpts?.lazyUpdate,
-        });
-        onSetOption?.(instance);
-      }
-    },
-  );
-  // 同理，没必要判断是否首次运行
-  useEffect(() => option && setOption(option), [option]);
-
-  // opts 变化时，重新创建实例
-  const onDisposeRef = useRef<() => void>(null);
-  const init = useEffectEvent((opts: EChartsInitOpts | undefined) => {
-    debugAssert(ref.current, "effect should run after ref is connected");
-    const { container, instance: existingInstance } = ref.current;
-    // 严格模式下由于 effect 被执行两次，第二次执行时 instance 已经创建，故应该跳过
-    if (existingInstance) return;
-    const instance = echarts.init(container, theme, opts);
-    ref.current = { container, instance };
-    onDisposeRef.current = onInit?.(instance) ?? null;
-    if (option) {
-      setOption(option, true);
-    }
-  });
-  const dispose = useEffectEvent(() => {
-    if (ref.current) {
-      const { container, instance } = ref.current;
-      if (instance) {
-        onDisposeRef.current?.();
-        instance.dispose();
-        ref.current = { container };
-      }
-    }
-  });
-  useEffect(() => {
-    // 将实例创建延迟到下一个 animation frame 以确保首次渲染尺寸正确
-    const animationFrame = requestAnimationFrame(() => init(opts));
-    return () => {
-      cancelAnimationFrame(animationFrame);
-      dispose();
-    };
-  }, [opts]);
-
-  return (
-    <div
-      ref={(container) => {
-        if (container === null) {
-          ref.current = null;
-        } else {
-          ref.current = { container };
-        }
-      }}
-      {...rest}
-    />
-  );
-};
-export default ECharts;
-
-// React Compiler 无法处理 getter
-function useForwardEChartsRef(
-  outerRef: Ref<EChartsRef> | undefined,
-  innerRef: RefObject<EChartsRef | null>,
-) {
-  useImperativeHandle(outerRef, () => {
-    debugAssert(innerRef.current, "ref should be connected");
-    return {
-      get container() {
-        debugAssert(innerRef.current, "ref should be connected");
-        return innerRef.current.container;
-      },
-      get instance() {
-        debugAssert(innerRef.current, "ref should be connected");
-        return innerRef.current.instance;
-      },
-    };
-    // oxlint-disable-next-line exhaustive-deps
-  }, []);
-}

package/src/components/Header.tsx

@@ -1,136 +0,0 @@
-import { Flex, Layout, Menu, theme, type MenuProps } from "antd";
-import type { CSSProperties, ReactNode } from "react";
-
-import UserButton from "./UserButton";
-
-export type MenuItem = Required<MenuProps>["items"][number];
-
-export interface HeaderProps extends MenuProps {
-  /**
-   * 网站 logo 的 URL。
-   *
-   * 建议导入图片，然后填入导入得到的地址，而不要硬编码地址。
-   */
-  logo?: string;
-  /** 顶栏的标题。*/
-  title?: string;
-  /**
-   * 顶栏左端部分（logo 和标题）的宽度。在与边栏搭配时，推荐设置成与边栏同宽。
-   * @default 260
-   */
-  leftEndWidth?: number | string;
-  /**
-   * 顶栏左端的内容（logo 和标题）。设置了该属性时，
-   * {@linkcode HeaderProps.logo | logo}、
-   * {@linkcode HeaderProps.title | title} 和
-   * {@linkcode HeaderProps.leftEndWidth | leftEndWidth} 将失去作用。
-   * 填 `null` 可以隐藏掉默认值（与 `undefined` 不同！）。
-   */
-  leftEnd?: ReactNode;
-  /**
-   * 菜单项配置，默认为空。
-   *
-   * 该属性以及其余属性的用法可参考 [`Menu` 组件的文档][1]。
-   *
-   * [1]: https://ant-design.antgroup.com/components/menu-cn
-   */
-  items?: MenuItem[];
-  /** 当前选中的菜单项 key 数组。 */
-  selectedKeys?: string[];
-  /** 当前展开的子菜单 key 数组。 */
-  openKeys?: string[];
-  /** 菜单项被选中时的回调函数。 */
-  onSelect?: MenuProps["onSelect"];
-  /** 子菜单展开/收起时的回调函数。 */
-  onOpenChange?: MenuProps["onOpenChange"];
-  /**
-   * 顶栏右端的额外内容。默认使用 {@linkcode UserButton} 组件。
-   * 填 `null` 可以隐藏掉默认值（与 `undefined` 不同！）。
-   * @default <UserButton layout="header" />
-   */
-  rightEnd?: ReactNode;
-  /** 额外的 `className`。*/
-  className?: string;
-  /** 额外的 CSS 样式。*/
-  style?: CSSProperties;
-}
-
-/**
- * 顶栏组件。该组件需要放置在 [Ant Design 的 `Layout` 组件][1]内部才能正常工作。
- * 如果没有指定 {@linkcode HeaderProps.rightEnd | rightEnd} 属性，
- * 那么还需要包裹在 {@linkcode AuthProvider} 内，并且经过 {@linkcode AuthCheck} 验证后
- * 才能正常显示顶栏右端的用户信息按钮。
- *
- * 一般来说，使用该组件时至少需要提供 `logo`、`items` 和 `onSelect` 三个属性，具体用法请参照范例。
- *
- * 除了文档中列出的属性之外，该组件会把额外的属性全部传递给内部的菜单 [`Menu` 组件][2]。
- *
- * [1]: https://ant-design.antgroup.com/components/layout-cn
- * [2]: https://ant-design.antgroup.com/components/menu-cn
- */
-function Header(props: HeaderProps) {
-  const { token } = theme.useToken();
-  const {
-    logo,
-    title,
-    leftEndWidth = 260,
-    leftEnd,
-    rightEnd,
-    className,
-    style,
-    ...rest
-  } = props;
-  return (
-    <Layout.Header
-      className={className}
-      style={{
-        display: "flex",
-        alignItems: "center",
-        boxShadow: "rgba(0, 0, 0, 0.15) 0 0 8px",
-        zIndex: 1,
-        background: token.colorBgContainer,
-        padding: 0,
-        color: token.colorText,
-        ...style,
-      }}
-    >
-      {leftEnd !== undefined ? (
-        leftEnd
-      ) : (
-        <Flex
-          align="center"
-          gap={token.marginSM}
-          style={{
-            minWidth: leftEndWidth,
-            height: "100%",
-            paddingInlineStart: token.paddingLG + token.paddingXXS,
-            paddingInlineEnd: token.paddingSM,
-          }}
-        >
-          <img alt="logo" src={logo} style={{ height: "50%" }} />
-          <h1
-            style={{
-              flexBasis: "100%",
-              textAlign: "center",
-              color: token.colorText,
-            }}
-          >
-            {title}
-          </h1>
-        </Flex>
-      )}
-      <Menu
-        mode="horizontal"
-        {...rest}
-        style={{
-          flexBasis: "100%",
-          height: "100%",
-          borderBlockEnd: "none",
-        }}
-      />
-      {rightEnd !== undefined ? rightEnd : <UserButton layout="header" />}
-    </Layout.Header>
-  );
-}
-
-export default Header;

package/src/components/ImageBackground.tsx

@@ -1,58 +0,0 @@
-export interface ImageBackgroundProps
-  extends React.HTMLAttributes<HTMLDivElement> {
-  /**
-   * 图片的 URL。
-   *
-   * 建议导入图片，然后填入导入得到的地址，而不要硬编码地址。
-   *
-   * ```jsx
-   * import img from "../public/image.png";
-   * <ImageBackground url={img}>...</ImageBackground>
-   * ```
-   */
-  url: string;
-  children: React.ReactNode;
-  /**
-   * 容器的宽度。
-   * @default "100%"
-   */
-  width?: React.CSSProperties["width"];
-  /**
-   * 容器的高度。
-   * @default "100%"
-   */
-  height?: React.CSSProperties["height"];
-  style?: React.CSSProperties;
-}
-
-/**
- * 以图片作为背景的块级容器。除了文档列出的属性以外，也兼容所有 [HTML Div 元素][1] 的属性。
- *
- * [1]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div
- */
-function ImageBackground(props: ImageBackgroundProps) {
-  const {
-    url,
-    children,
-    width = "100%",
-    height = "100%",
-    style,
-    ...rest
-  } = props;
-  return (
-    <div
-      {...rest}
-      style={{
-        backgroundSize: "100% 100%",
-        width: width,
-        height: height,
-        backgroundImage: `url('${url}')`,
-        ...style,
-      }}
-    >
-      {children}
-    </div>
-  );
-}
-
-export default ImageBackground;