react-public-components 1.1.16 → 1.1.18

package/README.md

@@ -2,11 +2,12 @@
 
 封装 react 常用的组件，欢迎更多同学提出大众化普遍存在的业务场景。
 
-本仓库包含三个独立的 React 组件：
+本仓库包含四个独立的 React 组件：
 
 1. **CollapseBox** — 可折叠的内容容器组件
 2. **Splitter** — 可拖拽调整、可折叠的分屏面板组件
 3. **DisabledBox** — 禁用态包装容器组件（带锁图标及拦截事件）
+4. **Masonry** — 瀑布流布局组件（一比一复刻 Ant Design V6 规范）
 
 ---
 
@@ -198,7 +199,108 @@ export default function Demo() {
 
 ---
 
-## 四、目录结构
+## 四、Masonry 瀑布流组件
+
+### 简介
+
+`Masonry` 是一个符合 Ant Design V6 规范的瀑布流布局组件。支持固定或响应式列数配置（`columns`）、水平垂直间距配置（`gutter`）、持续监听子项尺寸变化（`fresh`）、自定义语义化结构样式/类名（`styles`/`classNames`）以及列排序回调（`onLayoutChange`）。
+
+### 引入方式
+
+```tsx
+import { Masonry } from 'react-public-components';
+```
+
+### Masonry Props
+
+| 参数             | 说明                                         | 类型                                                                                                        | 默认值  |
+| ---------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------- |
+| `classNames`     | 自定义内部语义化结构 class，支持对象或函数   | `Record<'root' \| 'item', string> \| ((info: { props }) => Record<'root' \| 'item', string>)`               | `-`     |
+| `columns`        | 列数，固定数字或响应式配置                   | `number \| { xs?: number; sm?: number; md?: number; lg?: number; xl?: number; xxl?: number }`               | `3`     |
+| `fresh`          | 是否持续监听子项尺寸变化                     | `boolean`                                                                                                   | `false` |
+| `gutter`         | 间距，固定数字、响应式配置或水平垂直间距配置 | `Gap \| [Gap, Gap]`                                                                                         | `0`     |
+| `items`          | 瀑布流数据项                                 | `MasonryItem[]`                                                                                             | `-`     |
+| `itemRender`     | 自定义数据项渲染函数                         | `(item: MasonryItem) => ReactNode`                                                                          | `-`     |
+| `styles`         | 语义化结构 style，支持对象和函数形式         | `Record<'root' \| 'item', CSSProperties> \| ((info: { props }) => Record<'root' \| 'item', CSSProperties>)` | `-`     |
+| `onLayoutChange` | 列排序计算完成回调                           | `(layout: { key: React.Key; column: number }[]) => void`                                                    | `-`     |
+
+### MasonryItem 属性
+
+| 参数       | 说明                                             | 类型               | 默认值 |
+| ---------- | ------------------------------------------------ | ------------------ | ------ |
+| `children` | 自定义展示内容，相对 `itemRender` 具有更高优先级 | `ReactNode`        | `-`    |
+| `column`   | 自定义指定放置列（0-indexed）                    | `number`           | `-`    |
+| `data`     | 自定义存储数据                                   | `T`                | `-`    |
+| `height`   | 高度（手指定时优先使用）                         | `number`           | `-`    |
+| `key`      | 唯一标识                                         | `string \| number` | `-`    |
+
+### 基础用法
+
+```tsx
+import { Masonry } from 'react-public-components';
+
+export default function Demo() {
+	return (
+		<Masonry
+			columns={{ xs: 1, sm: 2, md: 3, lg: 4 }}
+			gutter={[16, 16]}
+			fresh={true}
+			items={[
+				{ key: '1', height: 120, children: <div>卡片 1</div> },
+				{ key: '2', height: 180, children: <div>卡片 2</div> },
+				{ key: '3', height: 150, children: <div>卡片 3</div> },
+			]}
+		/>
+	);
+}
+```
+
+---
+
+## 五、BorderBeam 边框流光组件
+
+### 简介
+
+`BorderBeam` 是一个给任意容器边框添加持续流动高亮效果的组件。使用现代 CSS Mask 遮罩与 CSS Motion Path 动画，支持单色与多点渐变色配置、多条流光均匀分布、流光尺寸与线宽调节，以及贴合自定义宿主容器。
+
+### 引入方式
+
+```tsx
+import { BorderBeam } from 'react-public-components';
+```
+
+### API
+
+| 参数        | 说明                                                                                                                  | 类型                                             | 默认值 | 版本  | 全局配置 |
+| ----------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------ | ----- | -------- |
+| `children`  | 装饰内容                                                                                                              | `ReactNode`                                      | `-`    | 6.4.0 | ×        |
+| `color`     | 流光颜色配置，支持单色字符串或渐变停靠点数组。`percent` 使用 `0 ~ 100` 的输入区间，组件会在内部为尾部透明过渡预留空间 | `string \| { color: string; percent: number }[]` | `-`    | 6.4.0 | ×        |
+| `count`     | 流光数量                                                                                                              | `number`                                         | `1`    | 6.6.0 | ×        |
+| `duration`  | 流光完成一圈动画的时间，单位秒                                                                                        | `number`                                         | `6`    | 6.5.0 | ×        |
+| `lineWidth` | 流光线宽，数字类型按像素处理                                                                                          | `number \| string`                               | `1px`  | 6.5.0 | ×        |
+| `outset`    | 流光层相对容器边缘的外扩距离，遇到裁剪容器时可设为 `0`                                                                | `number \| string`                               | `-`    | 6.4.0 | ×        |
+| `size`      | 流光可见段的尺寸，数字类型按像素处理                                                                                  | `number \| string`                               | `100`  | 6.5.0 | ×        |
+
+### 基础用法
+
+```tsx
+import { BorderBeam } from 'react-public-components';
+
+export default function Demo() {
+	return (
+		<BorderBeam size={100} duration={6} color="#1677ff">
+			<div style={{ padding: 24, borderRadius: 12, border: '1px solid #eee' }}>
+				<h3>Workspace overview</h3>
+				<p>Review task status, deployment health, and recent automation activity in one panel.</p>
+			</div>
+		</BorderBeam>
+	);
+}
+```
+
+---
+
+## 六、目录结构
 
 ```
 .
@@ -207,14 +309,20 @@ export default function Demo() {
 │   └── index.less
 ├── Splitter/
 │   └── index.tsx
-└── DisabledBox/
+├── DisabledBox/
+│   ├── index.tsx
+│   └── index.less
+├── Masonry/
+│   ├── index.tsx
+│   └── index.less
+└── BorderBeam/
     ├── index.tsx
     └── index.less
 ```
 
 ---
 
-## 五、发布到 npm
+## 七、发布到 npm
 
 ### 1. 前置准备
 

package/dist/index.cjs

@@ -30,8 +30,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BorderBeam: () => BorderBeam_default,
   CollapseBox: () => CollapseBox_default,
   DisabledBox: () => DisabledBox_default,
+  Masonry: () => Masonry_default,
   Splitter: () => Splitter_default
 });
 module.exports = __toCommonJS(index_exports);
@@ -865,10 +867,351 @@ var DisabledBox = (props) => {
   );
 };
 var DisabledBox_default = DisabledBox;
+
+// Masonry/index.tsx
+var import_react3 = __toESM(require("react"), 1);
+var import_jsx_runtime5 = require("react/jsx-runtime");
+var BREAKPOINT_ORDER = ["xs", "sm", "md", "lg", "xl", "xxl"];
+function getBreakpoint(width) {
+  if (width >= 1600) return "xxl";
+  if (width >= 1200) return "xl";
+  if (width >= 992) return "lg";
+  if (width >= 768) return "md";
+  if (width >= 576) return "sm";
+  return "xs";
+}
+function resolveResponsiveValue(value, currentBp, defaultValue) {
+  if (value === void 0 || value === null) return defaultValue;
+  if (typeof value === "object") {
+    const obj = value;
+    if (obj[currentBp] !== void 0) return obj[currentBp];
+    const currentIdx = BREAKPOINT_ORDER.indexOf(currentBp);
+    for (let i = currentIdx - 1; i >= 0; i--) {
+      const bp = BREAKPOINT_ORDER[i];
+      if (obj[bp] !== void 0) return obj[bp];
+    }
+    for (let i = currentIdx + 1; i < BREAKPOINT_ORDER.length; i++) {
+      const bp = BREAKPOINT_ORDER[i];
+      if (obj[bp] !== void 0) return obj[bp];
+    }
+    return defaultValue;
+  }
+  return value;
+}
+function resolveGutter(gutter, currentBp) {
+  if (!gutter) return [0, 0];
+  if (Array.isArray(gutter)) {
+    const h = resolveResponsiveValue(gutter[0], currentBp, 0);
+    const v = resolveResponsiveValue(gutter[1], currentBp, 0);
+    return [h, v];
+  }
+  const g = resolveResponsiveValue(gutter, currentBp, 0);
+  return [g, g];
+}
+var Masonry = (props) => {
+  const {
+    classNames,
+    columns = 3,
+    fresh = false,
+    gutter = 0,
+    items,
+    itemRender,
+    styles,
+    onLayoutChange,
+    className,
+    style,
+    children
+  } = props;
+  const rootRef = (0, import_react3.useRef)(null);
+  const [containerWidth, setContainerWidth] = (0, import_react3.useState)(0);
+  const [measuredHeights, setMeasuredHeights] = (0, import_react3.useState)({});
+  const itemRefs = (0, import_react3.useRef)(/* @__PURE__ */ new Map());
+  const normalizedItems = (0, import_react3.useMemo)(() => {
+    if (items) return items;
+    if (!children) return [];
+    return import_react3.default.Children.toArray(children).map((child, index) => {
+      var _a;
+      if (import_react3.default.isValidElement(child)) {
+        const key = (_a = child.key) != null ? _a : `masonry-item-${index}`;
+        return {
+          key,
+          children: child
+        };
+      }
+      return {
+        key: `masonry-item-${index}`,
+        children: child
+      };
+    });
+  }, [items, children]);
+  const currentBreakpoint = (0, import_react3.useMemo)(() => getBreakpoint(containerWidth), [containerWidth]);
+  const resolvedColumns = (0, import_react3.useMemo)(() => {
+    const count = resolveResponsiveValue(columns, currentBreakpoint, 3);
+    return Math.max(1, Math.floor(count));
+  }, [columns, currentBreakpoint]);
+  const [horizontalGap, verticalGap] = (0, import_react3.useMemo)(
+    () => resolveGutter(gutter, currentBreakpoint),
+    [gutter, currentBreakpoint]
+  );
+  (0, import_react3.useEffect)(() => {
+    if (!rootRef.current) return;
+    const observer = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        const width = entry.contentRect.width;
+        if (width > 0) {
+          setContainerWidth(width);
+        }
+      }
+    });
+    observer.observe(rootRef.current);
+    return () => observer.disconnect();
+  }, []);
+  const measureItems = (0, import_react3.useCallback)(() => {
+    let hasChange = false;
+    const newHeights = {};
+    itemRefs.current.forEach((el, key) => {
+      if (el) {
+        const strKey = String(key);
+        const h = el.offsetHeight;
+        if (h > 0) {
+          newHeights[strKey] = h;
+          if (measuredHeights[strKey] !== h) {
+            hasChange = true;
+          }
+        }
+      }
+    });
+    if (hasChange) {
+      setMeasuredHeights((prev) => ({ ...prev, ...newHeights }));
+    }
+  }, [measuredHeights]);
+  (0, import_react3.useLayoutEffect)(() => {
+    const handle = requestAnimationFrame(() => {
+      measureItems();
+    });
+    return () => cancelAnimationFrame(handle);
+  }, [measureItems]);
+  (0, import_react3.useEffect)(() => {
+    if (!fresh) return;
+    const observer = new ResizeObserver(() => {
+      measureItems();
+    });
+    itemRefs.current.forEach((el) => {
+      if (el) observer.observe(el);
+    });
+    return () => observer.disconnect();
+  }, [fresh, measureItems, normalizedItems]);
+  const columnWidth = (0, import_react3.useMemo)(() => {
+    if (containerWidth <= 0) return 0;
+    const totalGap = (resolvedColumns - 1) * horizontalGap;
+    return Math.max(0, (containerWidth - totalGap) / resolvedColumns);
+  }, [containerWidth, resolvedColumns, horizontalGap]);
+  const { layoutItems, containerHeight, layoutChangeData } = (0, import_react3.useMemo)(() => {
+    const colHeights = new Array(resolvedColumns).fill(0);
+    const changeData = [];
+    const computedList = normalizedItems.map((item) => {
+      var _a, _b;
+      const h = (_b = (_a = item.height) != null ? _a : measuredHeights[String(item.key)]) != null ? _b : 0;
+      let targetCol = 0;
+      if (typeof item.column === "number" && item.column >= 0 && item.column < resolvedColumns) {
+        targetCol = Math.floor(item.column);
+      } else {
+        let minH = colHeights[0];
+        for (let i = 1; i < resolvedColumns; i++) {
+          if (colHeights[i] < minH) {
+            minH = colHeights[i];
+            targetCol = i;
+          }
+        }
+      }
+      const left = targetCol * (columnWidth + horizontalGap);
+      const top = colHeights[targetCol];
+      colHeights[targetCol] += h + (h > 0 ? verticalGap : 0);
+      changeData.push({ key: item.key, column: targetCol });
+      return {
+        item,
+        left,
+        top,
+        width: columnWidth,
+        height: h,
+        column: targetCol
+      };
+    });
+    const totalH = Math.max(0, ...colHeights);
+    return {
+      layoutItems: computedList,
+      containerHeight: totalH,
+      layoutChangeData: changeData
+    };
+  }, [normalizedItems, resolvedColumns, horizontalGap, verticalGap, columnWidth, measuredHeights]);
+  const prevLayoutRef = (0, import_react3.useRef)("");
+  (0, import_react3.useEffect)(() => {
+    const layoutKey = JSON.stringify(layoutChangeData);
+    if (layoutKey !== prevLayoutRef.current) {
+      prevLayoutRef.current = layoutKey;
+      onLayoutChange == null ? void 0 : onLayoutChange(layoutChangeData);
+    }
+  }, [layoutChangeData, onLayoutChange]);
+  const semanticClassNames = (0, import_react3.useMemo)(() => {
+    var _a;
+    if (typeof classNames === "function") {
+      return (_a = classNames({ props })) != null ? _a : {};
+    }
+    return classNames != null ? classNames : {};
+  }, [classNames, props]);
+  const semanticStyles = (0, import_react3.useMemo)(() => {
+    var _a;
+    if (typeof styles === "function") {
+      return (_a = styles({ props })) != null ? _a : {};
+    }
+    return styles != null ? styles : {};
+  }, [styles, props]);
+  return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(
+    "div",
+    {
+      ref: rootRef,
+      className: ["masonry_root", semanticClassNames.root, className].filter(Boolean).join(" "),
+      style: {
+        minHeight: containerHeight > 0 ? containerHeight : void 0,
+        height: containerHeight > 0 ? containerHeight : void 0,
+        ...semanticStyles.root,
+        ...style
+      },
+      children: layoutItems.map(({ item, left, top, width, height }) => {
+        var _a;
+        const content = (_a = item.children) != null ? _a : itemRender == null ? void 0 : itemRender(item);
+        return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(
+          "div",
+          {
+            ref: (node) => {
+              if (node) {
+                itemRefs.current.set(item.key, node);
+              } else {
+                itemRefs.current.delete(item.key);
+              }
+            },
+            className: ["masonry_item", semanticClassNames.item].filter(Boolean).join(" "),
+            style: {
+              width: containerWidth > 0 ? width : "100%",
+              height: height > 0 ? height : void 0,
+              transform: containerWidth > 0 ? `translate3d(${left}px, ${top}px, 0)` : void 0,
+              opacity: containerWidth > 0 ? 1 : 0,
+              ...semanticStyles.item
+            },
+            onLoad: measureItems,
+            children: content
+          },
+          item.key
+        );
+      })
+    }
+  );
+};
+var Masonry_default = Masonry;
+
+// BorderBeam/index.tsx
+var import_jsx_runtime6 = require("react/jsx-runtime");
+var formatSizeUnit = (value, defaultValue) => {
+  if (value === void 0 || value === null) {
+    return defaultValue;
+  }
+  if (typeof value === "number") {
+    return `${value}px`;
+  }
+  return value;
+};
+var buildGradientString = (color) => {
+  if (!color) {
+    return "linear-gradient(to left, #1677ff 0%, transparent 100%)";
+  }
+  if (typeof color === "string") {
+    return `linear-gradient(to left, ${color} 0%, transparent 100%)`;
+  }
+  if (Array.isArray(color)) {
+    if (color.length === 0) {
+      return "linear-gradient(to left, #1677ff 0%, transparent 100%)";
+    }
+    const sorted = [...color].sort((a, b) => a.percent - b.percent);
+    const mappedStops = sorted.map((stop) => {
+      const mappedPercent = Math.min(Math.max(stop.percent / 100 * 80, 0), 80);
+      return `${stop.color} ${mappedPercent.toFixed(2)}%`;
+    });
+    return `linear-gradient(to left, ${mappedStops.join(", ")}, transparent 100%)`;
+  }
+  return "linear-gradient(to left, #1677ff 0%, transparent 100%)";
+};
+var BorderBeam = (props) => {
+  const {
+    children,
+    color,
+    count = 1,
+    duration = 6,
+    lineWidth = "1px",
+    outset = "0px",
+    size = 100,
+    className,
+    style,
+    ...restProps
+  } = props;
+  const formattedLineWidth = formatSizeUnit(lineWidth, "1px");
+  const formattedOutset = formatSizeUnit(outset, "0px");
+  const formattedSize = formatSizeUnit(size, "100px");
+  const gradientCss = buildGradientString(color);
+  const maskStyle = {
+    "--border-beam-line-width": formattedLineWidth,
+    "--border-beam-outset": formattedOutset,
+    "--border-beam-size": formattedSize,
+    "--border-beam-duration": `${duration}s`,
+    "--border-beam-gradient": gradientCss
+  };
+  const beamCount = Math.max(1, count);
+  const beams = Array.from({ length: beamCount }).map((_, index) => {
+    const delaySeconds = -(duration * index / beamCount);
+    return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(
+      "div",
+      {
+        className: "react-public-border-beam-item",
+        style: {
+          animationDelay: `${delaySeconds}s`
+        }
+      },
+      index
+    );
+  });
+  if (children !== void 0) {
+    return /* @__PURE__ */ (0, import_jsx_runtime6.jsxs)(
+      "div",
+      {
+        className: `react-public-border-beam-container ${className || ""}`.trim(),
+        style,
+        ...restProps,
+        children: [
+          children,
+          /* @__PURE__ */ (0, import_jsx_runtime6.jsx)("div", { className: "react-public-border-beam-mask", style: maskStyle, children: beams })
+        ]
+      }
+    );
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(
+    "div",
+    {
+      className: `react-public-border-beam-mask ${className || ""}`.trim(),
+      style: {
+        ...maskStyle,
+        ...style
+      },
+      ...restProps,
+      children: beams
+    }
+  );
+};
+var BorderBeam_default = BorderBeam;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BorderBeam,
   CollapseBox,
   DisabledBox,
+  Masonry,
   Splitter
 });
 //# sourceMappingURL=index.cjs.map