npm - @hsu-react/ui - Versions diffs - 1.0.0 → 2.0.1 - Mend

@hsu-react/ui 1.0.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (709) hide show

package/src/layout/NavTabBar/index.module.scss ADDED Viewed

@@ -0,0 +1,179 @@
+// 注意：这是 CSS Module，文件里的每个类名都会被哈希。antd 的类名必须写在 :global() 里，
+// 否则 `.ant-tabs-nav` 会被编译成一串哈希，永远匹配不到 antd 渲染出的 DOM —— 规则不会报错，
+// 只是静悄悄地全部失效。本库其余组件的样式都遵循这个写法。
+.NavTabBar {
+  padding: 6px 8px 0px;
+  // Modern look: keep the white strip; the active tab is a light teal pill
+  background: var(--vita-surface);
+  border-bottom: 1px solid var(--vita-border);
+  // 把根类重复一次（编译成 `.x.x`），只为提一档权重。antd 的卡片样式是
+  // `:where(...).ant-tabs-card.ant-tabs-small.ant-tabs-top > .ant-tabs-nav .ant-tabs-tab`，
+  // `:where()` 不计权重，正好和这里的四个类打平 —— 打平时后注入的赢，而 antd 的
+  // CSS-in-JS 是运行时插进 <head> 的，永远在后面，圆角这类就会被它盖回卡片样式。
+  &.NavTabBar {
+    :global(.ant-tabs-nav) {
+      height: 36px;
+      margin-bottom: 0px;
+      &::before {
+        border-bottom: none;
+      }
+      // Card-style tabs do not need the bottom ink bar
+      :global(.ant-tabs-ink-bar) {
+        display: none;
+      }
+      :global(.ant-tabs-nav-list) {
+        :global(.ant-tabs-tab) {
+          position: relative;
+          padding: 0px;
+          margin: 0px;
+          border: none;
+          border-radius: 8px;
+          background: transparent;
+          transition: background 0.2s;
+          & + :global(.ant-tabs-tab) {
+            margin-left: 4px;
+          }
+          :global(.ant-tabs-tab-btn) {
+            color: var(--vita-muted-foreground);
+            > .tabLabel {
+              display: inline-flex;
+              align-items: center;
+              justify-content: center;
+              column-gap: 5px;
+              width: 100%;
+              height: 100%;
+              padding: 6px 16px;
+            }
+            > .tabLabel.legacyClosableTabLabel {
+              padding-right: 36px;
+            }
+          }
+          &:hover {
+            background: var(--vita-border-weak);
+          }
+          &:global(.ant-tabs-tab-active) {
+            background: var(--vita-muted);
+            :global(.ant-tabs-tab-btn) {
+              color: var(--vita-primary);
+              font-weight: 500;
+            }
+          }
+          :global(.ant-tabs-tab-remove) {
+            position: absolute;
+            right: 16px;
+            top: 50%;
+            transform: translateY(-50%);
+          }
+          &:has(:global(.ant-tabs-tab-remove)) {
+            :global(.ant-tabs-tab-btn) {
+              > .tabLabel {
+                padding-right: 36px;
+              }
+            }
+          }
+        }
+      }
+    }
+    // extra 区域自身没有高度，撑满后才能和页签对齐；右边那条竖线把刷新按钮和页签分开
+    :global(.ant-tabs-extra-content) {
+      display: flex;
+      align-items: center;
+      align-self: stretch;
+      margin-right: 8px;
+      padding-right: 8px;
+      border-right: 1px solid var(--vita-border-weak);
+    }
+    // 「刷新当前页」按钮
+    .reload {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      width: 28px;
+      height: 28px;
+      padding: 0px;
+      color: var(--vita-muted-foreground);
+      &:hover {
+        color: var(--vita-primary);
+      }
+    }
+    :global(.ant-tabs-nav-operations) {
+      > button {
+        cursor: pointer;
+      }
+    }
+  }
+}
+.popover {
+  // antd v6 里承载内边距的是 .ant-popover-container，v5 的 .ant-popover-inner 已经没有了 ——
+  // 照着 v5 写不会报错，只是这条规则永远不生效，右键菜单会白白多出一圈 12px 内边距
+  :global(.ant-popover-container) {
+    padding: 0px;
+  }
+  .part {
+    display: flex;
+    flex-direction: column;
+    padding: 6px 0px;
+    border-bottom: 1px solid var(--vita-border-weak);
+    :global(.ant-btn) {
+      justify-content: flex-start;
+      border-radius: 0px;
+    }
+  }
+}
+.dragOverlay {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  opacity: 0.9;
+  height: 34px;
+  padding: 6px 16px;
+  background: var(--vita-surface);
+  border-radius: 6px 6px 0 0;
+  border: 1px solid var(--vita-border);
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+  .tabLabel {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    column-gap: 5px;
+  }
+}

package/src/layout/NavTabBar/index.tsx ADDED Viewed

@@ -0,0 +1,236 @@
+import { Tabs as AntdTabs, Tooltip } from "antd";
+import React, { ReactNode, useCallback, useMemo, useState } from "react";
+import { useNavigate } from "react-router";
+import type { DragEndEvent, DragStartEvent } from "@dnd-kit/core";
+import {
+  closestCenter,
+  DndContext,
+  PointerSensor,
+  useSensor,
+} from "@dnd-kit/core";
+import {
+  restrictToHorizontalAxis,
+  restrictToParentElement,
+} from "@dnd-kit/modifiers";
+import {
+  arrayMove,
+  horizontalListSortingStrategy,
+  SortableContext,
+} from "@dnd-kit/sortable";
+import { RouteType } from "../types";
+import styles from "./index.module.scss";
+import { useAliveController } from "react-activation";
+import useReload from "../_hooks/useReload";
+import { formatNavTabBar } from "./_utils/formatNavTabBar";
+import { useTabPath } from "./_hooks/useTabPath";
+import { useTabContextMenu } from "./_hooks/useTabContextMenu";
+import { useDropTabKey } from "./_hooks/useDropTabKey";
+import { useTabTitle } from "./_hooks/useTabTitle";
+import TabLabel from "./_components/TabLabel";
+import DraggableTabNode from "./_components/SortableTab";
+import TabDragOverlay from "./_components/TabDragOverlay";
+import { isLegacyHasSelectorBrowser } from "../../utils/cssSupports";
+import Button from "../../components/Button";
+import Icon from "../../components/Icon";
+export interface TabType {
+  label: ReactNode;
+  key: string;
+  element?: React.ReactNode;
+  children?: TabType[];
+  path?: string;
+  name?: ReactNode;
+  affix?: boolean;
+  icon?: ReactNode;
+}
+export interface NavTabBarProps {
+  router: RouteType[];
+  affixRouter?: string[];
+  basePath?: string;
+  /** 页签栏最前面的「刷新当前页」按钮 */
+  showReload?: boolean;
+}
+const NavTabBar: React.FC<NavTabBarProps> = (props) => {
+  const {
+    router,
+    affixRouter = [],
+    basePath = "/",
+    showReload = true,
+  } = props;
+  const navigate = useNavigate();
+  const { drop, refresh } = useAliveController();
+  const onReload = useReload();
+  const legacyHasSelector = isLegacyHasSelectorBrowser();
+  const items = useMemo(() => {
+    return formatNavTabBar(router);
+  }, [router]);
+  const { tabKey, openKeys, setOpenkeys } = useTabPath({
+    items,
+    affixRouter,
+  });
+  const { open, setOpen } = useTabContextMenu();
+  useDropTabKey(setOpenkeys);
+  useTabTitle(setOpenkeys);
+  // ID of the tab currently being dragged
+  const [activeId, setActiveId] = useState<string | null>(null);
+  // Configure the drag sensor with a 10px activation distance to avoid accidental drags
+  const sensor = useSensor(PointerSensor, {
+    activationConstraint: { distance: 10 },
+  });
+  // Handle the drag start event
+  const onDragStart = (event: DragStartEvent) => {
+    setActiveId(String(event.active.id));
+  };
+  // Handle the drag end event
+  const onDragEnd = ({ active, over }: DragEndEvent) => {
+    if (active.id !== over?.id) {
+      setOpenkeys((prev) => {
+        const activeIndex = prev.findIndex((i) => i.key === active.id);
+        const overIndex = prev.findIndex((i) => i.key === over?.id);
+        return arrayMove(prev, activeIndex, overIndex);
+      });
+    }
+    setActiveId(null);
+  };
+  // Handle the drag cancel event
+  const onDragCancel = () => {
+    setActiveId(null);
+  };
+  /**
+   * 刷新当前页。走的是和右键菜单「重新加载」完全相同的两步：`onReload` 通知页面自己重挂，
+   * `refresh` 让 react-activation 丢掉这份缓存。少调其中任何一个，都会出现「看上去刷新了、
+   * 实际还是那棵旧组件树」。
+   *
+   * key 要去掉 query —— 缓存是按路径存的，带上 `?a=1` 会找不到对应的那份。
+   */
+  const reloadCurrent = useCallback(() => {
+    const key = tabKey?.split("?")[0];
+    if (!key) return;
+    onReload(key);
+    refresh(key);
+  }, [tabKey, onReload, refresh]);
+  return (
+    <AntdTabs
+      className={styles.NavTabBar}
+      items={openKeys?.map((item, idx) => {
+        const closable = !(affixRouter.includes(item.key) || item.affix);
+        return {
+          label: (
+            <TabLabel
+              item={item}
+              index={idx}
+              openKeys={openKeys}
+              basePath={basePath}
+              affixRouter={affixRouter}
+              open={open}
+              onReload={onReload}
+              refresh={refresh}
+              drop={drop}
+              setOpenkeys={setOpenkeys}
+              setOpen={setOpen}
+              navigate={navigate}
+              className={
+                legacyHasSelector && closable
+                  ? styles.legacyClosableTabLabel
+                  : undefined
+              }
+            />
+          ),
+          key: item.key,
+          closeIcon: closable ? undefined : false,
+        };
+      })}
+      activeKey={tabKey}
+      tabBarExtraContent={
+        showReload
+          ? {
+              left: (
+                // 不用 Button 的 title —— 本库的 Button 把 title 当作 children 的兜底
+                // （children ?? title），传了会把文案画到按钮里，而不是变成悬浮提示
+                <Tooltip title="刷新当前页">
+                  <Button
+                    className={styles.reload}
+                    type="text"
+                    size="small"
+                    aria-label="刷新当前页"
+                    icon={<Icon icon="ep:refresh" />}
+                    onClick={reloadCurrent}
+                  />
+                </Tooltip>
+              ),
+            }
+          : undefined
+      }
+      hideAdd
+      type="editable-card"
+      onEdit={(key, action) => {
+        if (action === "remove") {
+          drop((key as string)?.split("?")[0] || "");
+          // Find the index of the tab being closed
+          const currentIndex = openKeys.findIndex((item) => item.key === key);
+          const newOpenKeys = openKeys.filter((item) => item.key !== key);
+          setOpenkeys(newOpenKeys);
+          setOpen("");
+          if (key === tabKey) {
+            // If the active tab is closed, select the previous tab; fall back to the first one
+            const targetIndex = currentIndex > 0 ? currentIndex - 1 : 0;
+            navigate(newOpenKeys[targetIndex]?.key || basePath);
+          }
+        }
+      }}
+      size="small"
+      renderTabBar={(tabBarProps, DefaultTabBar) => (
+        <DndContext
+          sensors={[sensor]}
+          onDragStart={onDragStart}
+          onDragEnd={onDragEnd}
+          onDragCancel={onDragCancel}
+          collisionDetection={closestCenter}
+          modifiers={[restrictToHorizontalAxis, restrictToParentElement]}
+        >
+          <SortableContext
+            items={openKeys.map((i) => i.key)}
+            strategy={horizontalListSortingStrategy}
+          >
+            <DefaultTabBar {...tabBarProps}>
+              {(node) => (
+                <DraggableTabNode {...node.props} key={node.key}>
+                  {node}
+                </DraggableTabNode>
+              )}
+            </DefaultTabBar>
+          </SortableContext>
+          <TabDragOverlay
+            activeId={activeId}
+            openKeys={openKeys}
+            basePath={basePath}
+            affixRouter={affixRouter}
+            open={open}
+            onReload={onReload}
+            refresh={refresh}
+            drop={drop}
+            setOpenkeys={setOpenkeys}
+            setOpen={setOpen}
+            navigate={navigate}
+          />
+        </DndContext>
+      )}
+    />
+  );
+};
+export default NavTabBar;

package/src/layout/Theme/ThemeStore.ts ADDED Viewed

@@ -0,0 +1,70 @@
+import { readStorage, writeStorage, STORAGE_KEY } from "../_utils/storage";
+import { makeAutoObservable } from "mobx";
+export type Layout = "left" | "top" | "mixed";
+export type Theme = "light" | "dark";
+export type HeaderTheme = "light" | "dark" | "theme";
+// Three appearance modes (light / dark / follow system)
+export type Appearance = "light" | "dark" | "system";
+class ThemeStore {
+  // Appearance mode selected by the user
+  get appearance() {
+    return this._appearance;
+  }
+  private _appearance: Appearance = "system";
+  // Whether the system is currently dark (takes effect when appearance=system)
+  private _systemDark = false;
+  // Resolved actual dark-mode state
+  get isDark(): boolean {
+    if (this._appearance === "system") return this._systemDark;
+    return this._appearance === "dark";
+  }
+  // Fixed left layout; switching is no longer offered
+  get layout(): Layout {
+    return "left";
+  }
+  // Nav light/dark follows the appearance
+  get headerTheme(): HeaderTheme {
+    return this.isDark ? "dark" : "light";
+  }
+  // Content theme follows the appearance
+  get theme(): Theme {
+    return this.isDark ? "dark" : "light";
+  }
+  constructor() {
+    makeAutoObservable(this);
+    const cached = readStorage(STORAGE_KEY.APPEARANCE) as Appearance | undefined;
+    if (cached === "light" || cached === "dark" || cached === "system") {
+      this._appearance = cached;
+    }
+    // Listen for system color-scheme changes, following in real time when appearance=system
+    if (typeof window !== "undefined" && window.matchMedia) {
+      const mq = window.matchMedia("(prefers-color-scheme: dark)");
+      this._systemDark = mq.matches;
+      mq.addEventListener("change", (e) => this._setSystemDark(e.matches));
+    }
+  }
+  private _setSystemDark = (v: boolean) => {
+    this._systemDark = v;
+  };
+  public setAppearance = (appearance: Appearance) => {
+    this._appearance = appearance;
+    writeStorage(STORAGE_KEY.APPEARANCE, appearance);
+  };
+}
+export default new ThemeStore();

package/src/layout/Theme/index.md ADDED Viewed

@@ -0,0 +1,48 @@
+---
+title: Theme 外观
+order: 5
+---
+# Theme 外观
+外观三态（浅色 / 深色 / 跟随系统）与导航区专属配色。
+## 引入
+```ts
+import Layout from "@hsu-react/ui/es/layout";
+<Layout.Theme>{children}</Layout.Theme>;
+```
+## 与 ConfigProvider 的分工
+这两个组件**不是二选一，也不重复**：
+- [`ConfigProvider`](/components/config-provider) 提供**全局主题** —— 色板、圆角、字号、控件高度、明暗算法、focus ring，全部从设计令牌产出
+- `Layout.Theme` 只做两件它独有的事：
+  1. 写 `html[data-theme]`。令牌的 CSS 变量与 `useIsDark` 都监听这个属性，但没有别的地方写它 —— 外观三态就落在这儿
+  2. 叠加导航区配色。菜单选中态的胶囊、深色侧栏的渐变，这些是布局特有的，通用令牌覆盖不到。选中态的颜色取**当前生效的主色**（antd `useToken` 读到的 `colorPrimary`），所以在 `ConfigProvider` 上换 `primaryColor`，菜单会跟着换
+所以顺序是 `ConfigProvider` 在外、`Layout.Theme` 在内（antd 的嵌套主题规则是内层胜）。
+## API
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| children | 子节点 | `ReactNode` | - |
+| navDarkColors | 深色导航渐变的两端色 | `{ top: string; bottom: string }` | `{ top: "#1f1f1f", bottom: "#141414" }` |
+## ThemeStore
+外观状态是一个 mobx store，应用侧可直接读写（`Layout.Header` 的外观切换器用的就是它）：
+```ts | pure
+import Layout from "@hsu-react/ui/es/layout";
+Layout.ThemeStore.appearance;              // "light" | "dark" | "system"
+Layout.ThemeStore.isDark;                  // 解析 system 之后的实际明暗
+Layout.ThemeStore.setAppearance("dark");   // 切换，并写入 localStorage
+```
+`appearance` 持久化在 `localStorage["hsu-ui:appearance"]`；选了 `system` 时会跟随 `prefers-color-scheme` 实时变化。

package/src/layout/Theme/index.module.scss ADDED Viewed

@@ -0,0 +1,6 @@
+.theme {
+  width: 100vw;
+  height: 100vh;
+  overflow: hidden;
+}

package/src/layout/Theme/index.tsx ADDED Viewed

@@ -0,0 +1,105 @@
+import React, { useEffect, useMemo } from "react";
+import { ConfigProvider as AntdConfigProvider, theme as antdTheme } from "antd";
+import { observer } from "mobx-react-lite";
+import classNames from "classnames";
+import styles from "./index.module.scss";
+import ThemeStore from "./ThemeStore";
+import { lightTokens, darkTokens, withAlpha } from "../../styles/tokens";
+export interface ThemeProps {
+  children?: React.ReactNode;
+  /** 深色导航渐变的两端色，不传用内置值 */
+  navDarkColors?: { top: string; bottom: string };
+}
+/**
+ * 外观控制器 + 布局专属配色。
+ *
+ * 这里刻意**不**做全局主题 —— 色板、圆角、字号、控件高度、明暗算法、focus ring 都由本库的
+ * `ConfigProvider` 从设计令牌统一产出。这个组件只负责两件它独有的事：
+ *
+ * 1. **写 `html[data-theme]`**。令牌的 CSS 变量与 `useIsDark` 都监听这个属性，但**没有人写它** ——
+ *    这是外观三态（light / dark / 跟随系统）落地的地方，也是这个组件存在的主要理由。
+ * 2. **侧栏与导航的配色**。菜单选中态的胶囊、深色导航的渐变，这些是布局特有的，
+ *    通用令牌覆盖不到，用一层就近的 antd ConfigProvider 叠加（antd 的嵌套规则：内层胜）。
+ *
+ * 移植时去掉的（本库已有，留着会重复甚至打架）：
+ * - 自己包一层 antd ConfigProvider 做全局主题、切 darkAlgorithm  -> ConfigProvider
+ * - hexToRgba                                                   -> styles/tokens 的 withAlpha
+ * - 自存一份主题色（原来固定是青色）                                -> antd useToken 里当前生效的 colorPrimary
+ * - matchMedia 监听系统深色                                       -> useIsDark
+ * - borderRadius / colorBorder / Table / Card / Button / Input 等成套 token 覆盖 -> toAntdTheme
+ * - 在包裹元素上内联重定义 --cf-*：那会盖掉 tokens.scss 生成的值，属于主动帮倒忙
+ */
+const Theme: React.FC<ThemeProps> = observer((props) => {
+  const { children, navDarkColors } = props;
+  const { isDark } = ThemeStore;
+  const t = isDark ? darkTokens : lightTokens;
+  // 主色取**当前生效**的那个，而不是自己再存一份 —— 消费方在 ConfigProvider 上换了
+  // primaryColor，导航的选中态要跟着换，否则菜单会是一个和全站无关的颜色。
+  const { token } = antdTheme.useToken();
+  const primaryColor = token.colorPrimary;
+  // 写 data-theme：CSS 变量与 useIsDark 都看它。
+  useEffect(() => {
+    document.documentElement.dataset.theme = isDark ? "dark" : "light";
+  }, [isDark]);
+  const themeConfig = useMemo(
+    () => ({
+      components: {
+        Layout: {
+          headerBg: t.surface,
+          siderBg: t.surface,
+        },
+        Menu: {
+          // 背景透明，好让导航的渐变透出来；选中态是一颗圆角胶囊
+          darkItemBg: "transparent",
+          darkSubMenuItemBg: "transparent",
+          darkPopupBg: t.surface,
+          darkItemColor: "rgba(255, 255, 255, 0.82)",
+          darkItemHoverColor: "#ffffff",
+          darkItemHoverBg: "rgba(255, 255, 255, 0.14)",
+          darkItemSelectedBg: withAlpha(primaryColor, 0.16),
+          darkItemSelectedColor: primaryColor,
+          itemSelectedBg: withAlpha(primaryColor, 0.12),
+          itemSelectedColor: primaryColor,
+          itemActiveBg: withAlpha(primaryColor, 0.12),
+          itemHoverBg: isDark
+            ? "rgba(255, 255, 255, 0.06)"
+            : "rgba(0, 0, 0, 0.04)",
+          itemColor: t.foreground,
+          itemBorderRadius: 6,
+          itemMarginInline: 8,
+          itemMarginBlock: 2,
+          itemHeight: 38,
+          horizontalItemHoverBg: "#0000000a",
+        },
+      },
+    }),
+    [isDark, primaryColor, t]
+  );
+  return (
+    <AntdConfigProvider theme={themeConfig}>
+      <div
+        className={classNames(styles.theme, isDark ? "dark" : "light")}
+        style={
+          {
+            "--nav-dark-top": navDarkColors?.top ?? "#1f1f1f",
+            "--nav-dark-bottom": navDarkColors?.bottom ?? "#141414",
+          } as React.CSSProperties
+        }
+      >
+        {children}
+      </div>
+    </AntdConfigProvider>
+  );
+});
+Theme.displayName = "Theme";
+export default Theme;

package/src/layout/_hooks/useDropTab.ts ADDED Viewed

@@ -0,0 +1,23 @@
+import { createContext, useContext, useCallback } from "react";
+export const NavTabBarContent = createContext<{
+  dropKey?: string;
+  setDropKey?: (key: string) => void;
+}>({});
+export default function useDropTab() {
+  const { setDropKey } = useContext(NavTabBarContent);
+  const drop = useCallback(
+    (key: string) => {
+      setDropKey?.(key);
+      setTimeout(() => {
+        setDropKey?.("");
+      }, 0);
+    },
+    [setDropKey]
+  );
+  return drop;
+}

package/src/layout/_hooks/useReload.ts ADDED Viewed

@@ -0,0 +1,19 @@
+import { createContext, useCallback, useContext } from "react";
+export const ReloadContent = createContext<{
+  id?: string;
+  setId?: (id: string) => void;
+}>({});
+export default function useReload() {
+  const { setId: setReLoadId } = useContext(ReloadContent);
+  const onReload = useCallback(
+    (id: string) => {
+      setReLoadId?.(id);
+    },
+    [setReLoadId]
+  );
+  return onReload;
+}