@tsingroc/tsingroc-components 3.14.0 → 3.14.1

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;