donar 0.0.1

package/src/components/carousel/index.tsx

@@ -0,0 +1,215 @@
+import {
+  type FC,
+  type CSSProperties,
+  type ReactElement,
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+} from 'react';
+import { useRAfInterval } from '@/hooks';
+
+import {
+  type ShowArrowType,
+  type RerenderType,
+  type NonLoopEndFuncType,
+  usePlayControl,
+  useLoopChildren,
+} from './hooks';
+
+import styles from './index.module.scss';
+
+type IndicatorType = 'line' | 'dot' | 'none';
+export type CarouselProps = {
+  /** 单个轮播项的宽度 */
+  cardWidth?: number;
+  /** 单个轮播项的高度 */
+  cardHeight?: number;
+  /** 轮播容器的宽度 */
+  wrapperWidth?: number;
+  /** 轮播容器的高度 */
+  wrapperHeight?: number;
+  /** 轮播项之间的间隔 */
+  gapSize?: number;
+  /** 是否无缝轮播 */
+  loop?: boolean; // 是否循环
+  /** 切换时间（毫秒） */
+  duration?: number;
+  /** 是否自动播放 */
+  autoPlay?: boolean;
+  /** 箭头类型 */
+  showArrow?: ShowArrowType;
+  /** 指示器类型 */
+  indicatorType?: IndicatorType;
+  /** 主轮播类名，不包括指示器 */
+  className?: string;
+  /** 主轮播样式，不包括指示器 */
+  style?: CSSProperties;
+  /** 轮播项 */
+  children: ReactElement[];
+  /** 轮播项更新依赖方式 */
+  rerender?: RerenderType;
+  /** 非循环模式下，轮播结束回调 */
+  onNonLoopEnd?: NonLoopEndFuncType;
+  /** 非循环模式下，轮播结束时的偏移量。就是提前第几张就算结束。暂不支持延后。 */
+  offsetOnEnd?: number;
+  // 因外框可达于轮播项，一页可能展示多张，设置偏移时注意是否可能永远触发不到
+  /** 自定义渲染箭头 */
+  arrows?: [
+    /** 自定义渲染上一个箭头 */
+    FC<{ onClick: () => void; className?: string }>,
+    /** 自定义渲染下一个箭头 */
+    FC<{ onClick: () => void; className?: string }>,
+  ];
+};
+
+export type CarouselRef = {
+  /** 开始播放 */
+  run: () => void;
+  /** 停止播放 */
+  stop: () => void;
+  /** 切换到上一个或下一个 */
+  stepChange: (arg: 'prev' | 'next') => void;
+  /** 跳转到指定索引 */
+  jumpChange: (arg: number) => void;
+  /** 获取当前索引 */
+  getCurrentIndex: () => number;
+};
+
+/**
+ * @author sonion
+ * @description 轮播组件，用于展示多个轮播项
+ * @param {CarouselProps} props - 组件的属性
+ * @param {number} [props.cardWidth] - 单个轮播项的宽度
+ * @param {number} [props.cardHeight] - 单个轮播项的高度
+ * @param {number} [props.wrapperWidth] - 轮播容器的宽度
+ * @param {number} [props.wrapperHeight] - 轮播容器的高度
+ * @param {number} [props.gapSize] - 轮播项之间的间隔
+ * @param {boolean} [props.loop] - 是否无缝循环
+ * @param {number} [props.duration=6000] - 切换时间（毫秒）
+ * @param {boolean} [props.autoPlay=true] - 是否自动播放
+ * @param {ShowArrowType} [props.showArrow='always'] - 箭头类型
+ * @param {IndicatorType} [props.indicatorType='line'] - 指示器类型
+ * @param {string} [props.className] - 主轮播类名，不包括指示器
+ * @param {CSSProperties} [props.style] - 主轮播样式，不包括指示器
+ * @param {ReactElement[]} children - 轮播项
+ * @param {RerenderType} [props.rerender='length'] - 轮播项更新依赖方式
+ * @param {(direction: 'prev' | 'next', current: number, total: number, offset: number) => void} [props.onNonLoopEnd] - 非循环模式下，轮播结束回调。
+ * @param {number} [props.offsetOnEnd=0] - 非循环模式下，轮播结束时的偏移量。就是提前第几张就算结束。暂不支持延后。
+ * @param {[FC<{ onClick: () => void; className?: string }>, FC<{ onClick: () => void; className?: string }>]} [props.arrows] - 自定义渲染箭头
+ */
+const Carousel = forwardRef<CarouselRef, CarouselProps>(
+  (
+    {
+      cardWidth,
+      cardHeight,
+      wrapperWidth,
+      wrapperHeight,
+      gapSize,
+      loop = true,
+      duration = 6000,
+      autoPlay = true,
+      showArrow = 'always' as ShowArrowType,
+      indicatorType = 'line',
+      className,
+      style,
+      children,
+      rerender = 'length' as RerenderType, // 默认按children更新依赖其数量变化，可以减少重渲染
+      onNonLoopEnd,
+      offsetOnEnd = 0,
+      arrows,
+    },
+    ref
+  ) => {
+    const list = useLoopChildren(children, loop, rerender);
+    const [setBannerRef, stepChange, jumpChange, getCurrentIndex] =
+      usePlayControl({
+        length: children.length,
+        loop,
+        showArrow,
+        cardWidth,
+        onNonLoopEnd,
+        offsetOnEnd,
+      });
+    const [run, stop] = useRAfInterval(stepChange, duration);
+
+    useEffect(() => {
+      if (autoPlay) {
+        run();
+      }
+      return stop;
+    }, [run, stop, autoPlay]);
+    useImperativeHandle(
+      ref,
+      () => ({
+        run,
+        stop,
+        stepChange,
+        jumpChange,
+        getCurrentIndex,
+      }),
+      [run, stop, stepChange, jumpChange, getCurrentIndex]
+    );
+
+    return (
+      <>
+        <div
+          className={`${styles.carousel} ${className ?? ''}`}
+          style={
+            {
+              ...style,
+              '--wrapperWidth': wrapperWidth,
+              '--wrapperHeight': wrapperHeight,
+              '--cardWidth': cardWidth,
+              '--cardHeight': cardHeight,
+              '--gapSize': gapSize,
+            } as unknown as CSSProperties
+          }
+          onMouseEnter={stop}
+          onMouseLeave={autoPlay ? run : void 0}
+        >
+          <div className={`${styles.arrow} ${showArrow}`}>
+            {arrows?.[0] ? (
+              arrows[0]({
+                onClick: () => stepChange('prev'),
+                className: styles.left,
+              })
+            ) : (
+              <i className={styles.left} onClick={() => stepChange('prev')} />
+            )}
+            {arrows?.[1] ? (
+              arrows[1]({
+                onClick: () => stepChange(),
+                className: styles.right,
+              })
+            ) : (
+              <i className={styles.right} onClick={() => stepChange()} />
+            )}
+          </div>
+
+          <div className={styles.wrapper}>
+            <div className={styles.inner} ref={setBannerRef}>
+              {list}
+            </div>
+          </div>
+        </div>
+        <div className={`${styles.indicator} ${indicatorType}`}>
+          {children.map((_, i) => (
+            <i
+              key={i}
+              onClick={(e) => {
+                e.stopPropagation();
+                jumpChange(i);
+              }}
+            />
+          ))}
+        </div>
+      </>
+    );
+  }
+);
+
+Carousel.displayName = 'Carousel'; // 调试/错误 信息友好；屏幕阅读器可识别组件
+
+type CarouselType = typeof Carousel;
+export type { ShowArrowType, RerenderType, CarouselType };
+export default Carousel;

package/src/components/custom-show/index.tsx

@@ -0,0 +1,31 @@
+import type { FC, ReactNode, JSX, PropsWithChildren } from 'react';
+
+export type CustomShowProps<T> = PropsWithChildren<{
+  /** 判断条件 */
+  when: T | null | undefined | false;
+  /** 不满足条件时的渲染内容 */
+  fallback?: ReactNode;
+}>;
+
+export interface CustomShowType<T> extends FC<CustomShowProps<T>> {
+  (props: CustomShowProps<T>): JSX.Element;
+}
+
+/**
+ * @author sonion
+ * @description 根据条件渲染内容，替代用三目运算和短路规则条件渲染
+ * @param {CustomShowProps<T>} props 组件属性
+ * @param {T | null | undefined | false} props.when 条件
+ * @param {ReactNode} props.fallback 不满足条件时的渲染内容
+ * @param {(value: T | null | undefined | false) => ReactNode} props.children 满足条件时的渲染内容
+ * @returns {JSX.Element} - 组件节点
+ */
+function CustomShow<T>({
+  when,
+  fallback = void 0,
+  children,
+}: CustomShowProps<T>): JSX.Element {
+  return <>{when ? children : fallback}</>;
+}
+
+export default CustomShow;

package/src/components/error-boundary/index.tsx

@@ -0,0 +1,48 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+
+export interface ErrorBoundaryProps {
+  /** 正常展示 */
+  children: ReactNode;
+  /** 错误发生时显示的回退内容 */
+  fallback: ReactNode;
+  /** 错误信息的提示文本 */
+  msg?: string;
+}
+
+interface State {
+  hasError: boolean;
+}
+
+/**
+ * @author sonion
+ * @description 错误边界组件，用于捕获子组件的错误并显示自定义的回退内容
+ * @param {ErrorBoundaryProps} props - 组件的属性
+ * @param {ReactNode} props.fallback - 错误发生时显示的回退内容
+ * @param {string} [props.msg='组件加载失败'] - 错误信息的提示文本
+ * @param {ReactNode} props.children - 子组件，可能会触发错误
+ * @returns {import('react').JSX.Element} - 组件节点
+ */
+class ErrorBoundary extends Component<ErrorBoundaryProps, State> {
+  state: State = { hasError: false };
+  private msg: string = this.props.msg ?? '组件加载失败';
+
+  static getDerivedStateFromError(): State {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    console.error(`${this.msg}:`, error, errorInfo);
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback;
+    }
+    return this.props.children;
+  }
+}
+
+type ErrorBoundaryType = typeof ErrorBoundary;
+
+export type { ErrorBoundaryType };
+export default ErrorBoundary;

package/src/components/index.ts

@@ -0,0 +1,11 @@
+export * from './carousel';
+export { default as Carousel } from './carousel'; // 默认导出需重命名
+
+export * from './custom-show';
+export { default as CustomShow } from './custom-show';
+
+export * from './async-custom-show';
+export { default as AsyncCustomShow } from './async-custom-show';
+
+export * from './error-boundary';
+export { default as ErrorBoundary } from './error-boundary';

package/src/hooks/async-guard.ts

@@ -0,0 +1,53 @@
+import { useState, useRef, useCallback } from 'react';
+import { useLatestCallback } from './state';
+
+/**
+ * @author sonion
+ * @description 异步操作锁，防止重复调用。通过返回的 Promise 确定是否执行中，执行中不可重复触发。
+ * @param {(...args: T)=>Promise<R>} asyncAction - 异步方法，需返回Promise
+ * @param {(isPending: boolean) => void} [onChange] - 状态变化回调
+ * @param {string} [msg] - 警告信息
+ * @returns {[boolean, (...args: T) => (Promise<R> | Promise<void>)]} - 返回是否执行中，执行方法
+ */
+export const useAsyncActionLock = <T extends unknown[], R>(
+  asyncAction: (...args: T) => Promise<R>,
+  onChange?: (isPending: boolean) => void,
+  msg?: string
+) => {
+  const [isPending, setIsPending] = useState(false); // 对外可能需要触发渲染
+  const syncPending = useRef(isPending); // 对内，同步更改，返回的函数不更改
+  const getLatestOnChange = useLatestCallback(onChange); // 稳定函数引用
+  const setPending = useCallback(
+    (val: boolean) => {
+      syncPending.current = val;
+      setIsPending(val);
+      getLatestOnChange()?.(val);
+    },
+    [syncPending, setIsPending, getLatestOnChange]
+  );
+
+  const getLatestAsyncAction = useLatestCallback(asyncAction); // 稳定函数引用
+
+  const handler = useCallback<(...args: T) => Promise<R> | Promise<void>>(
+    (...args: T) => {
+      if (syncPending.current) {
+        console.clog(msg || '正在提交中，请稍后再试');
+        return Promise.resolve(void 0);
+      }
+      setPending(true);
+      return new Promise<R>((resolve, reject) => {
+        try {
+          const latestAsyncAction = getLatestAsyncAction();
+          resolve(latestAsyncAction?.(...args));
+        } catch (err) {
+          reject(err);
+        }
+      }).finally(() => {
+        setPending(false);
+      });
+    },
+    [getLatestAsyncAction, msg, setPending]
+  );
+
+  return [isPending, handler] as const;
+};

package/src/hooks/index.ts

@@ -0,0 +1,5 @@
+export * from './state';
+export * from './timer';
+export * from './observer';
+export * from './storage';
+export * from './async-guard';

package/src/hooks/observer.ts

@@ -0,0 +1,236 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+
+import { useCreateSafeRef, useLatestCallback } from './index';
+
+type MutationObserverCallback = (
+  entry: MutationRecord[],
+  observer: MutationObserver
+) => void;
+/**
+ * @author sonion
+ * @description dom变化观察器hook
+ * @param {MutationObserverCallback} callback - 回调函数，参数为 MutationRecord[]
+ * @param {boolean} [once] - 是否只观察一次，默认false
+ */
+export const useMutationObserver = (
+  callback: MutationObserverCallback,
+  once = false
+) => {
+  const observerRef = useRef<MutationObserver>();
+  const getLatestCallback = useLatestCallback(callback);
+
+  useEffect(
+    () => () => {
+      observerRef.current?.disconnect?.(); // 上一次观察器取消，observe没有重新运行的话，观察就丢失了
+      observerRef.current = void 0;
+    },
+    []
+  );
+
+  // MutationObserver 重新生成对象，observe 不会更新，用 observe 做依赖可能造成
+  // MutationObserver 更新了，但没有重新观察。但理论上只有 StrictMode 模式下会重新生成对象
+  // 且observe不是作为依赖，而是直接绑定dom或依赖其它重渲染会改变的状态就不会有问题。
+  // 或用Set存下历史观察，重生成时恢复，但不能用WeakSet，非必要不建议
+  /** 开始观察 因重新生成观察器observe不会更新，故不可以observe是否更新做依赖依据 */
+  const observe = useCallback(
+    (el: Node | null, options?: MutationObserverInit) => {
+      if (!el) return;
+      observerRef.current ??= new MutationObserver(
+        (mutations: MutationRecord[], observer: MutationObserver) => {
+          getLatestCallback()?.(mutations, observer);
+          once && observer.disconnect();
+        }
+      );
+      observerRef.current?.observe?.(el, options);
+    },
+    [once, getLatestCallback]
+  );
+
+  const takeRecords = useCallback(
+    () => observerRef.current?.takeRecords?.(),
+    []
+  );
+
+  const disconnect = useCallback(() => observerRef.current?.disconnect?.(), []);
+
+  return {
+    /** 开始观察 因重新生成观察器observe不会更新，故不可以observe是否更新做依赖依据 */
+    observe,
+    /** 获取所有未处理的观察记录 */
+    takeRecords,
+    /** 取消所有观察，用observe重新启用 */
+    disconnect,
+  };
+};
+
+type IntersectionObserverCallback = (
+  /** 交叉目标 */
+  target: Element,
+  /** 交叉目标的根元素 */
+  root: Element | undefined,
+  /** 交叉观察器实例 */
+  observer: IntersectionObserver
+) => void;
+type IntersectionObserverParams = {
+  callback: IntersectionObserverCallback;
+  rootMargin?: number;
+  threshold?: number;
+  once?: boolean;
+};
+/**
+ * @author sonion
+ * @description 视口交叉观察器hook
+ * @param {IntersectionObserverParams} params - 观察器初始化参数
+ * @param {IntersectionObserverCallback} params.callback - 加载回调。
+ * @param {number} [params.rootMargin] - 提前多少px触发
+ * @param {number} [params.threshold] - 被观察目标与观察区交叉多少触发，0-1
+ * @param {boolean} [params.once] - 是否只触发一次
+ */
+export const useIntersectionObserver = ({
+  callback,
+  rootMargin = 100,
+  threshold = 0,
+  once = false,
+}: IntersectionObserverParams) => {
+  const observerRef = useRef<IntersectionObserver>();
+  const [rootRef, setRootRef] = useCreateSafeRef<Element>();
+  const getLatestCallback = useLatestCallback(callback);
+
+  const options = useMemo(
+    () => ({
+      root: rootRef, // 要观察的区域，视口为null
+      rootMargin: `${rootMargin}px`, // 将观察区域向外扩张多少。扩张后就提前交叉了
+      threshold, // 被观察目标与观察区交叉多少触发，0-1
+    }),
+    [rootRef, rootMargin, threshold]
+  );
+
+  const prevOptions = useRef(options); // 纪录上一次的options，用于比较是否变化
+
+  useEffect(
+    () => () => {
+      observerRef.current?.disconnect?.();
+      observerRef.current = void 0;
+    },
+    [options]
+  );
+
+  const observe = useCallback(
+    (el: Element | null) => {
+      if (!el) return;
+      // options变化，取消观察，重新生成观察器
+      if (prevOptions.current !== options) {
+        observerRef.current?.disconnect?.();
+        observerRef.current = void 0;
+        prevOptions.current = options; // 纪录新值
+      }
+
+      observerRef.current ??= new IntersectionObserver((entries, observer) => {
+        entries.forEach((entry) => {
+          if (entry.isIntersecting) {
+            getLatestCallback()?.(entry.target, rootRef, observer);
+            once && observer.unobserve?.(entry.target); // 取消观察, 因为只需要触发一次。反复触发可不取消
+          }
+        });
+      }, options);
+      observerRef.current?.unobserve?.(el); // 避免重复
+      observerRef.current?.observe?.(el);
+    },
+    // rootRef 已经是options 依赖了
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [options, once, getLatestCallback]
+  );
+
+  const unobserve = useCallback(
+    (el: Element | null) => el && observerRef.current?.unobserve?.(el),
+    []
+  );
+
+  const takeRecords = useCallback(
+    () => observerRef.current?.takeRecords?.(),
+    []
+  );
+
+  const disconnect = useCallback(() => observerRef.current?.disconnect?.(), []);
+  return {
+    rootRef,
+    /** 设置观察区域 */
+    setRootRef,
+    /** 开始观察 */
+    observe,
+    /** 取消观察 */
+    unobserve,
+    /** 取消所有观察，用observe重新启用 */
+    disconnect,
+    /** 获取 未触发回调前，所有未处理的观察记录，触发后清空 */
+    takeRecords,
+  };
+};
+
+type ResizeObserverCallback = (
+  /** 变化记录 */
+  entry: ResizeObserverEntry,
+  /** 观察器实例 */
+  observer: ResizeObserver
+) => void;
+/**
+ * @author sonion
+ * @description 元素尺寸变化观察器hook
+ * @param {ResizeObserverCallback} callback - 回调函数，参数为ResizeObserverEntry
+ * @param {boolean} [once] - 是否只观察一次，默认false
+ */
+export const useResizeObserver = (
+  callback: ResizeObserverCallback,
+  once = false
+) => {
+  const observerRef = useRef<ResizeObserver>();
+  const getLatestCallback = useLatestCallback(callback);
+
+  useEffect(
+    () => () => {
+      observerRef.current?.disconnect?.(); // 上一次观察器取消，observe没有重新运行的话，观察就丢失了
+      observerRef.current = void 0;
+    },
+    []
+  );
+
+  // ResizeObserver 重新生成对象，observe 不会更新，用 observe 做依赖可能造成
+  // ResizeObserver 更新了，但没有重新观察。但理论上只有 StrictMode 模式下会重新生成对象
+  // 且observe不是作为依赖，而是直接绑定dom或依赖其它重渲染会改变的状态就不会有问题。
+  // 或用Set存下历史观察，重生成时恢复，但不能用WeakSet，非必要不建议
+  /** 开始观察 因重新生成观察器observe不会更新，故不可以observe是否更新做依赖依据 */
+  const observe = useCallback(
+    (el: Element | null, options?: ResizeObserverOptions) => {
+      if (!el) return;
+      observerRef.current ??= new ResizeObserver(
+        (entries: ResizeObserverEntry[], observer: ResizeObserver) => {
+          entries.forEach((entry) => {
+            getLatestCallback()?.(entry, observer);
+          });
+          once && observer.disconnect();
+        }
+      );
+      observerRef.current?.unobserve?.(el); // 避免重复
+      observerRef.current?.observe?.(el, options);
+    },
+    [once, getLatestCallback]
+  );
+
+  /** 取消观察 */
+  const unobserve = useCallback(
+    (el: Element | null) => el && observerRef.current?.unobserve?.(el),
+    []
+  );
+
+  /** 取消所有观察，用observe重新启用 */
+  const disconnect = useCallback(() => observerRef.current?.disconnect?.(), []);
+
+  return {
+    /** 开始观察 因重新生成观察器observe不会更新，故不可以observe是否更新做依赖依据 */
+    observe,
+    /** 取消观察 */
+    unobserve,
+    /** 取消所有观察，用observe重新启用 */
+    disconnect,
+  };
+};