@tsingroc/tsingroc-components 3.13.4 → 3.14.1

package/src/components/Calendar.tsx

@@ -0,0 +1,182 @@
+import dayjs, { type Dayjs } from "dayjs";
+import { createStyles } from "antd-style";
+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

@@ -0,0 +1,38 @@
+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/Header.tsx

@@ -0,0 +1,136 @@
+import type { CSSProperties, ReactNode } from "react";
+import { Flex, Layout, Menu, type MenuProps, theme } from "antd";
+
+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

@@ -0,0 +1,58 @@
+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;

package/src/components/IndicatorLight.tsx

@@ -0,0 +1,106 @@
+import { createStyles, keyframes } from "antd-style";
+import type { HTMLAttributes } from "react";
+
+export interface IndicatorLightProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * 指示灯的直径。
+   * @default token.sizeXL
+   */
+  size?: number | string;
+  /**
+   * 指示的状态。设置了这一项时，{@linkcode onColor}、{@linkcode mode} 和 {@linkcode period} 会被忽略。
+   *
+   * `"healthy"` 表示常绿，`"attention"` 表示绿色闪烁，
+   * `"danger"` 表示常红，`"emergency"` 表示红色闪烁，
+   * `"off"` 表示关闭。
+   * 具体色值取自 design token。
+   */
+  status?: "healthy" | "attention" | "danger" | "emergency" | "off";
+  /**
+   * 灯亮时的颜色。
+   * @default token.colorError
+   */
+  onColor?: string;
+  /**
+   * 灯灭时的颜色。
+   * @default token.colorFill
+   */
+  offColor?: string;
+  /**
+   * 灯的状态。`"on"` 表示常亮，`"flash"` 表示闪烁，`"off"` 表示常暗。
+   * @default "on"
+   */
+  mode?: "on" | "flash" | "off";
+  /**
+   * 闪烁周期（一亮一暗）的时长，以秒为单位。不可为 `0`、`NaN` 或 `Infinity`。
+   * @default 1
+   */
+  period?: number;
+}
+
+const ANIMATION_MAP: Record<IndicatorLightProps["mode"] & {}, string> = {
+  on: "linear(0, 0) paused",
+  flash: "cubic-bezier(0.9, 0, 0.1, 1) infinite alternate",
+  off: "linear(1, 1) paused",
+};
+
+const useStyles = createStyles(({ token, css }, props: IndicatorLightProps) => {
+  const size = props.size ?? token.sizeXL;
+  const sizeCss = typeof size === "number" ? size + "px" : size;
+  const colorMap: Record<
+    IndicatorLightProps["status"] & {},
+    { onColor: string; mode: "on" | "flash" | "off" }
+  > = {
+    healthy: { onColor: token.colorSuccess, mode: "on" },
+    attention: { onColor: token.colorSuccess, mode: "flash" },
+    danger: { onColor: token.colorError, mode: "on" },
+    emergency: { onColor: token.colorError, mode: "flash" },
+    off: { onColor: token.colorError, mode: "off" },
+  };
+  const { onColor = token.colorError, mode = "on" } = props.status
+    ? colorMap[props.status]
+    : props;
+  const offColor = props.offColor ?? token.colorFillSecondary;
+  const halfPeriod = (props.period ?? 1) / 2;
+  const flash = keyframes`
+    from {
+      background-color: ${onColor};
+      box-shadow: 0 0 6px 2px ${onColor};
+    }
+    to {
+      background-color: ${offColor};
+    }
+  `;
+  return {
+    light: css`
+      width: 100%;
+      height: 100%;
+      border-radius: 50%;
+      animation: ${flash} ${halfPeriod}s ${ANIMATION_MAP[mode]};
+    `,
+    lightBorder: css`
+      height: ${sizeCss};
+      aspect-ratio: 1;
+      border: ${token.colorBorder} 2px solid;
+      border-radius: 50%;
+    `,
+  };
+});
+
+/**
+ * 一个指示灯。
+ *
+ * 文档内未列出的属性会被传递给组件顶层的 `div` 元素。
+ */
+function IndicatorLight(props: IndicatorLightProps) {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { size, status, onColor, offColor, mode, period, ...rest } = props;
+  const { cx, styles } = useStyles(props);
+  return (
+    <div {...rest} className={cx(styles.lightBorder, rest.className)}>
+      <div className={cx(styles.light)}></div>
+    </div>
+  );
+}
+
+export default IndicatorLight;