donar 0.0.1

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "donar",
+  "version": "0.0.1",
+  "description": "Donar: A modern frontend library offering utility functions, React hooks, and components with TypeScript support, ESM only, and tree-shaking capabilities.",
+  "type": "module",
+  "module": "dist/index.esm.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.esm.js",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./utils": {
+      "import": "./dist/utils.esm.js",
+      "types": "./dist/types/utils.d.ts"
+    },
+    "./hooks": {
+      "import": "./dist/hooks.esm.js",
+      "types": "./dist/types/hooks.d.ts"
+    },
+    "./components": {
+      "import": "./dist/components.esm.js",
+      "types": "./dist/types/components.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "rimraf dist && vite build",
+    "lint": "eslint '{src,apps,packages}/**/*.{ts,tsx,js,jsx,vue}'",
+    "lint:fix": "eslint '{src,apps,packages}/**/*.{ts,tsx,js,jsx,vue}' --fix",
+    "lint:error": "eslint '{src,apps,packages}/**/*.{ts,tsx,js,jsx,vue}' --quiet",
+    "lint:spell": "cspell lint '{src,apps,packages}/**/*.{js,ts,jsx,tsx,mjs,cjs,json,css,less,scss,vue,html,md}'",
+    "fmt": "oxfmt '{src,packages,apps}/**/*.*'",
+    "fmt:check": "oxfmt --check '{src,packages,apps}/**/*.*'",
+    "preinstall": "npm run sync:node-version && (npx -y only-allow pnpm || exit 1)",
+    "prepare": "npx simple-git-hooks",
+    "sync:node-version": "node scripts/sync-node-version/index.js"
+  },
+  "engines": {
+    "node": ">=24.14.0",
+    "pnpm": ">=10.32.1"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.5.0",
+    "@commitlint/config-conventional": "^20.5.0",
+    "@eslint/js": "^9.39.4",
+    "@types/node": "^24.12.0",
+    "@types/react": "^18.3.28",
+    "@types/react-dom": "^18.3.7",
+    "@vitejs/plugin-react": "^6.0.1",
+    "cspell": "^9.7.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jsdoc": "^62.8.1",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.4.0",
+    "lint-staged": "^16.4.0",
+    "only-allow": "^1.2.2",
+    "oxfmt": "^0.42.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "rimraf": "^6.1.3",
+    "sass-embedded": "^1.98.0",
+    "simple-git-hooks": "^2.13.1",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.57.2",
+    "vite": "^8.0.3",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-plugin-lib-inject-css": "^2.2.2",
+    "vitest": "^4.1.2"
+  },
+  "keywords": [
+    "hooks",
+    "utils",
+    "components",
+    "react"
+  ],
+  "author": "sonion",
+  "license": "MIT",
+  "repository": "https://github.com/sonion028/tonar",
+  "bugs": {
+    "url": "https://github.com/sonion028/tonar/issues"
+  },
+  "private": false
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+onlyBuiltDependencies:
+  - esbuild
+  - simple-git-hooks

package/scripts/sync-node-version/index.js

@@ -0,0 +1,31 @@
+/* global process */
+import fs from 'node:fs';
+import path from 'node:path';
+
+// 读取 package.json
+const packageJsonPath = path.join(process.cwd(), 'package.json');
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+
+// 提取 node 版本
+const nodeVersion = packageJson.engines?.node;
+
+if (!nodeVersion) {
+  console.error('Error: No node version found in package.json engines');
+  process.exit(1);
+}
+
+// 提取版本号（去掉 >= 等前缀）
+const versionMatch = nodeVersion.match(/>=?([0-9]+\.[0-9]+\.[0-9]+)/);
+
+if (!versionMatch) {
+  console.error('Error: Could not parse node version:', nodeVersion);
+  process.exit(1);
+}
+
+const cleanVersion = versionMatch[1];
+
+// 写入 .node-version 文件
+const nodeVersionPath = path.join(process.cwd(), '.node-version');
+fs.writeFileSync(nodeVersionPath, cleanVersion, 'utf8');
+
+console.log(`Synced node version: ${cleanVersion}`);

package/simple-git-hooks.js

@@ -0,0 +1,4 @@
+export default {
+  'pre-commit': "npx lint-staged --allow-empty && echo 'Pre-commit done ^_^'",
+  'commit-msg': 'npx commitlint --edit $1',
+};

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

@@ -0,0 +1,37 @@
+import { type FC, type ReactNode, type JSX, useEffect, useState } from 'react';
+
+export type AsyncCustomShowProps<T> = {
+  /** 异步判断 Promise */
+  when: Promise<T> | undefined | null | false;
+  /** 异步失败时的展示 */
+  fallback?: ReactNode;
+  /** 异步成功时的展示 */
+  children: (value: T | undefined | null | false) => ReactNode;
+};
+
+export interface AsyncCustomShowType<T> extends FC<AsyncCustomShowProps<T>> {
+  (props: AsyncCustomShowProps<T>): JSX.Element;
+}
+
+/**
+ * @author sonion
+ * @description 异步展示组件
+ * @param {AsyncCustomShowProps<T>} props - 组件属性
+ * @param {Promise<T> | undefined | null | false} props.when 异步判断 Promise
+ * @param {ReactNode} [props.fallback] 异步失败时的展示
+ * @param {(value: T | undefined | null | false) => ReactNode} props.children 异步成功时的展示
+ */
+function AsyncCustomShow<T>({
+  when,
+  fallback,
+  children,
+}: AsyncCustomShowProps<T>) {
+  const [show, setShow] = useState<Awaited<typeof when>>(void 0);
+  useEffect(() => {
+    if (!when) return;
+    Promise.resolve(when).then(setShow);
+  }, [when]);
+  return <>{show ? children(show) : fallback}</>;
+}
+
+export default AsyncCustomShow;

package/src/components/carousel/hooks.ts

@@ -0,0 +1,312 @@
+import {
+  type ReactElement,
+  cloneElement,
+  useCallback,
+  useEffect,
+  useRef,
+  useMemo,
+} from 'react';
+
+import { useCreateSafeRef } from '@/hooks';
+
+/**
+ * @author sonion
+ * @description 无动画切换
+ * @param {HTMLElement} el - 元素
+ * @param {number} index - 要切换的索引
+ * @returns {void}
+ */
+const noAnimationSwitch = (el: HTMLElement, index: number) => {
+  el.style.cssText = `transition-duration: 0s; --index: ${index}`;
+  el.clientLeft; // 触发回流
+  el.style.cssText = ''; // 恢复过渡动画
+};
+
+/**
+ * @author sonion
+ * @description 更新翻页按钮的dom操作
+ * @param {HTMLElement} wrapper - 容器元素。就是轮播子项的父元素（轮播inner）的父元素
+ * @param {Array} showArrow - 左右箭头显示状态
+ * @returns {void}
+ */
+const arrowDomOperation = (
+  wrapper: HTMLElement,
+  showArrow: [boolean, boolean]
+) => {
+  const arrow = wrapper.previousElementSibling as HTMLElement;
+  if (!arrow) {
+    return;
+  }
+  const [showLeft, showRight] = showArrow;
+  arrow.children[0]?.classList.toggle('show', showLeft);
+  arrow.children[1]?.classList.toggle('show', showRight);
+};
+
+/**
+ * @author sonion
+ * @description 每一次切换是的dom操作（更新主轮播图位置、指示器显示、翻页按钮）
+ * @param {HTMLElement} el - 元素
+ * @param {number} index - 操作索引
+ * @param {Array} showArrow - 左右箭头显示状态
+ * @returns {void}
+ */
+const domOperation = (
+  el: HTMLElement,
+  index: number,
+  showArrow: [boolean, boolean]
+) => {
+  /** 轮播主要index */
+  el.style.setProperty('--index', `${index}`);
+
+  const wrapper = el.parentElement;
+  if (!wrapper) {
+    return;
+  }
+  /** 设置指示器 */
+  const indicator = wrapper.parentElement?.nextElementSibling as HTMLElement;
+  if (indicator) {
+    indicator.querySelector('.active')?.classList.remove('active');
+    indicator.children[
+      index >= indicator.children.length ? 0 : index
+    ]?.classList.add('active');
+  }
+  /** 设置箭头 */
+  arrowDomOperation(wrapper, showArrow);
+};
+
+/* 箭头类型 */
+export type ShowArrowType = 'always' | 'auto' | 'hover' | 'none';
+
+type ShowArrowHookParams = {
+  /** 箭头类型 */
+  showArrow: ShowArrowType;
+  /** 轮播图数量 */
+  length: number;
+  /** 轮播图宽度 */
+  cardWidth?: number;
+  /** 轮播图容器 */
+  wrapperRef?: HTMLElement;
+};
+/**
+ * @author sonion
+ * @description 计算是否显示左右箭头
+ * @param {ShowArrowHookParams} params - hook参数
+ * @param {ShowArrowType} params.showArrow - 箭头类型
+ * @param {number} params.length - 轮播图数量
+ * @param {number} params.cardWidth - 轮播图宽度
+ * @param {HTMLElement} params.wrapperRef - 轮播图容器
+ * @returns {(index: number)=>[boolean, boolean]} - 计算是否显示左右箭头的函数
+ */
+export const useShowArrow = ({
+  showArrow,
+  length,
+  cardWidth,
+  wrapperRef,
+}: ShowArrowHookParams) => {
+  const displayQuantity = useMemo(() => {
+    const wrapperWidth =
+      (wrapperRef?.parentElement?.parentElement?.clientWidth || cardWidth) ?? 0;
+    if (!cardWidth) {
+      return 1;
+    }
+    return Math.floor(wrapperWidth / cardWidth); // 可完整显示的数量
+  }, [wrapperRef, cardWidth]);
+
+  return useCallback<(index: number) => [boolean, boolean]>(
+    (index: number) => {
+      if (showArrow !== 'auto') {
+        return [true, true];
+      }
+      let isRightShowArrow: boolean;
+      if (length > displayQuantity) {
+        const lastDisplayedIndex = index + displayQuantity - 1;
+        isRightShowArrow = lastDisplayedIndex < length - 1;
+      } else {
+        isRightShowArrow = false;
+      }
+      return [index > 0, isRightShowArrow];
+    },
+    [displayQuantity, length, showArrow]
+  );
+};
+
+export type NonLoopEndFuncType = (
+  /** 切换方向 */
+  direction: 'prev' | 'next',
+  /** 当前索引 */
+  current: number,
+  /** 轮播图数量 */
+  total: number,
+  /** 非循环轮播结束时的偏移量 */
+  offset: number
+) => void;
+type PlayControlHookParams = {
+  /** 轮播图数量 */
+  length: number;
+  /** 是否无缝轮播 */
+  loop: boolean;
+  /** 箭头类型 */
+  showArrow: ShowArrowType;
+  /** 轮播图宽度 */
+  cardWidth?: number;
+  /** 非循环轮播结束时的回调 */
+  onNonLoopEnd?: NonLoopEndFuncType;
+  /** 非循环轮播结束时的偏移量 */
+  offsetOnEnd?: number;
+};
+
+/**
+ * @author sonion
+ * @description 播放轮播图控制
+ * @param {PlayControlHookParams} params - hook参数
+ * @param {number} params.length - 轮播图数量
+ * @param {boolean} params.loop - 是否无缝轮播
+ * @param {ShowArrowType} params.showArrow - 箭头类型
+ * @param {number} params.cardWidth - 轮播图宽度
+ * @param {NonLoopEndFuncType} params.onNonLoopEnd - 非循环轮播结束回调
+ * @param {number} params.offsetOnEnd - 非循环轮播结束时的偏移量
+ */
+export const usePlayControl = ({
+  length,
+  loop,
+  showArrow,
+  cardWidth,
+  onNonLoopEnd,
+  offsetOnEnd = 0,
+}: PlayControlHookParams) => {
+  const FIRST = 0;
+  const LAST = length;
+  const indexRef = useRef(FIRST); // 第一张
+  const [ref, setRef, isReadyRef] = useCreateSafeRef();
+
+  // 非循环轮播时，偏移量参数规范化
+  offsetOnEnd = ~~offsetOnEnd; // 向下取整数
+  // 如偏移量为负数（轮播数再往后，就没了）或大于等于轮播图数量，都相当于不设置偏移
+  offsetOnEnd = offsetOnEnd < 0 || offsetOnEnd >= length ? 0 : offsetOnEnd;
+
+  // 生成计算是否显示左右箭头的函数
+  const getShowArrow = useShowArrow({
+    showArrow,
+    length,
+    cardWidth,
+    wrapperRef: ref,
+  });
+
+  // length 变化箭头类型为自动的可能需要重新设置，否则隐藏了的不会更新
+  useEffect(() => {
+    const wrapper = ref?.parentElement;
+    if (showArrow !== 'auto' || !wrapper) {
+      return;
+    }
+    const arrowStatus = getShowArrow(indexRef.current);
+    arrowDomOperation(wrapper, arrowStatus);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [length]);
+
+  const stepChange = useCallback(
+    (direction?: 'prev' | 'next') => {
+      if (!ref) {
+        return;
+      }
+      if (loop) {
+        if (indexRef.current >= LAST && direction !== 'prev') {
+          indexRef.current = 0;
+          noAnimationSwitch(ref, indexRef.current);
+        } else if (indexRef.current <= FIRST && direction === 'prev') {
+          indexRef.current = LAST;
+          noAnimationSwitch(ref, indexRef.current);
+        }
+      }
+      direction === 'prev' ? indexRef.current-- : indexRef.current++;
+      const arrowStatus = getShowArrow(indexRef.current);
+      domOperation(ref, indexRef.current, arrowStatus);
+      // 不循环轮播 结束事件
+      if (!loop && onNonLoopEnd) {
+        indexRef.current === length - offsetOnEnd - 1 &&
+          onNonLoopEnd(
+            direction ?? 'next',
+            indexRef.current,
+            length,
+            offsetOnEnd
+          );
+      }
+    },
+    [length, loop, ref, getShowArrow, offsetOnEnd, onNonLoopEnd, LAST]
+  );
+
+  const jumpChange = useCallback(
+    (index: number) => {
+      const originalIndex = indexRef.current; // 记录更改前索引
+      indexRef.current = index < 0 ? 0 : index > length ? length : index;
+      const arrowStatus = getShowArrow(indexRef.current);
+      ref && domOperation(ref, indexRef.current, arrowStatus);
+      if (!loop && onNonLoopEnd) {
+        const direction = originalIndex < indexRef.current ? 'next' : 'prev';
+        const _triggerIndex = length - offsetOnEnd - 1; // 触发非循环结束需要的索引
+        // 当前索引大于等于触发索引，那原索引小于触发索引，才是首次满足，才该触发
+        // 当前索引小于等于触发索引，那原索引大于触发索引，才是首次满足，才该触发
+        ((indexRef.current >= _triggerIndex && originalIndex < _triggerIndex) ||
+          (indexRef.current <= _triggerIndex &&
+            originalIndex > _triggerIndex)) &&
+          onNonLoopEnd(direction, indexRef.current, length, offsetOnEnd);
+      }
+    },
+    [length, loop, ref, getShowArrow, offsetOnEnd, onNonLoopEnd]
+  );
+
+  const getCurrentIndex = useCallback(() => indexRef.current, []);
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  useEffect(() => jumpChange(indexRef.current), [ref]); // 初始化时设置--index
+  return [setRef, stepChange, jumpChange, getCurrentIndex, isReadyRef] as const;
+};
+
+/**
+ * @author sonion
+ * @description 创建自增id函数
+ * @returns {()=>string} - 自增id函数
+ */
+const createAutoIncrementId = () => {
+  const fix = Math.random().toString(36).slice(2);
+  let id = 0;
+  return () => `${fix}-${++id}`;
+};
+/** 自增id函数 */
+const autoIncrementId = createAutoIncrementId();
+
+/**
+ * 子元素重渲染的依赖的类型
+ * length 依赖 children的数量
+ * child 依赖 children本身的变化
+ */
+export type RerenderType = 'length' | 'child';
+
+/**
+ * @author sonion
+ * @description 创建无缝轮播结构
+ * @param {ReactElement} children - 轮播列表
+ * @param {boolean} loop - 是否无缝轮播
+ * @param {RerenderType} rerender - 子元素重渲染的依赖类型
+ * @returns {ReactElement[]} - 无缝轮播结构
+ */
+export const useLoopChildren = (
+  children: ReactElement[],
+  loop: boolean,
+  rerender: RerenderType
+) =>
+  // 依赖 children?.length 或 children 的问题可忽略
+
+  useMemo(() => {
+    if (!Array.isArray(children) || !children.length) {
+      throw new Error('Carousel children must be an array');
+    }
+    if (loop) {
+      const first = children[0];
+      const clonedChildren = [...children]; // 加到后面，指示器和轮播项目好对应
+      // const last = children.at(-1);
+      // clonedChildren.unshift(cloneElement(last!, { key: autoIncrementId() }));
+      clonedChildren.push(cloneElement(first, { key: autoIncrementId() }));
+      return clonedChildren;
+    }
+    return children;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [rerender === 'child' ? children : children?.length, loop]);

package/src/components/carousel/index.module.scss

@@ -0,0 +1,163 @@
+.carousel {
+  position: relative;
+  overflow: hidden;
+  width: 100%; // 没制定宽度，默认100%
+  height: 100%;
+
+  &[style*='--wrapperWidth'] {
+    // 指定宽度用变量
+    width: calc(var(--wrapperWidth) * 1px);
+  }
+
+  &[style*='--wrapperHeight'] {
+    // 指定了高度
+    height: calc(var(--wrapperHeight) * 1px);
+  }
+
+  &:not([style*='--cardHeight']) {
+    // 没有指定高度，默认100%
+    .wrapper {
+      .inner {
+        height: 100%;
+      }
+    }
+  }
+
+  &[style*='--cardWidth'] {
+    // 指定了单张宽度
+    .wrapper {
+      width: calc(var(--cardWidth) * 1px); // 和卡片宽度一致，作为逻辑宽度
+      .inner {
+        transform: translateX(
+          calc(var(--index) * (var(--cardWidth) + var(--gapSize, 0)) * -1px)
+        );
+        & > * {
+          flex: 0 0 calc(var(--cardWidth) * 1px);
+          height: 100%;
+        }
+      }
+    }
+  }
+
+  &:not([style*='--cardWidth']) {
+    // 没有指定单张宽度
+    .wrapper {
+      width: 100%; // 没制定宽度，默认100%
+      .inner {
+        transform: translateX(
+          calc((-100% + (var(--gapSize, 0) * -1px)) * var(--index))
+        );
+        & > * {
+          flex: 0 0 100%;
+          height: 100%;
+        }
+      }
+    }
+  }
+
+  &:hover > .arrow:global(.hover) {
+    // hover时显示箭头
+    display: block;
+  }
+  & > .arrow {
+    // 切换箭头
+    &:global(.hover) {
+      // 有hover类时不显示
+      display: none;
+    }
+    &:global(.none) {
+      display: none;
+    }
+    &:global(.always),
+    &:global(.auto) {
+      display: block;
+    }
+    .left,
+    .right {
+      display: none;
+      position: absolute;
+      top: 50%;
+      transform: translateY(-50%);
+      z-index: 9;
+      width: 20px;
+      height: 20px;
+      padding: 14px;
+      border: 1px solid rgb(221, 226, 233);
+      border-radius: 50%;
+      background: rgb(255, 255, 255)
+        url('data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjEiIGhlaWdodD0iMjAiIHZpZXdCb3g9IjAgMCAyMSAyMCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPGcgaWQ9ImRvd24iPgo8cGF0aCBpZD0iVW5pb24iIGZpbGwtcnVsZT0iZXZlbm9kZCIgY2xpcC1ydWxlPSJldmVub2RkIiBkPSJNNi43OTE4MiA1Ljc2ODY1QzYuNDAyNzMgNS4zNzk1NiA2LjQwMjczIDQuNzQ4NzEgNi43OTE4MiA0LjM1OTYyTDcuNDk2MzQgMy42NTUxQzcuODg1NDMgMy4yNjYwMSA4LjUxNjI4IDMuMjY2MDEgOC45MDUzNyAzLjY1NTFMMTQuNTQxNSA5LjI5MTI0QzE0LjczNzEgOS40ODY4MyAxNC44MzQ0IDkuNzQzNSAxNC44MzMzIDkuOTk5ODVDMTQuODM0NCAxMC4yNTYyIDE0LjczNzEgMTAuNTEyOSAxNC41NDE1IDEwLjcwODVMOC45MDUzNyAxNi4zNDQ2QzguNTE2MjggMTYuNzMzNyA3Ljg4NTQzIDE2LjczMzcgNy40OTYzNCAxNi4zNDQ2TDYuNzkxODIgMTUuNjQwMUM2LjQwMjczIDE1LjI1MSA2LjQwMjczIDE0LjYyMDEgNi43OTE4MiAxNC4yMzExTDExLjAyMyA5Ljk5OTg1TDYuNzkxODIgNS43Njg2NVoiIGZpbGw9IiMwMDY2RkMiLz4KPC9nPgo8L3N2Zz4K')
+        no-repeat center / contain;
+      background-origin: content-box;
+      box-shadow:
+        0px 15px 35px -2px rgba(0, 0, 0, 0.05),
+        0px 5px 15px 0px rgba(0, 0, 0, 0.05);
+      cursor: pointer;
+    }
+    // 通过dom操作，所以用global
+    & > :global(.show) {
+      display: block;
+    }
+    .left {
+      left: 12px;
+      transform: translateY(-50%) rotate(180deg);
+    }
+    .right {
+      right: 12px;
+    }
+  }
+  .wrapper {
+    // 轮播图容器
+    height: 100%;
+    .inner {
+      // 轮播图内容列表
+      display: flex;
+      gap: calc(var(--gapSize) * 1px);
+      height: calc(var(--cardHeight) * 1px);
+      transition: transform 0.3s;
+    }
+  }
+}
+
+.indicator {
+  // 指示器
+  position: absolute;
+  bottom: -17px;
+  left: 50%;
+  z-index: 9;
+  transform: translateX(-50%);
+  display: flex;
+  gap: 8px;
+  border-radius: 8px;
+  &:global(.none) {
+    // 指示器为none
+    display: none;
+  }
+  &:global(.line) {
+    // 指示器为line
+    & > i {
+      width: 40px;
+      height: 5px;
+      border-radius: 8px;
+      background-color: var(--Gray-3, rgb(229, 232, 239));
+      cursor: pointer;
+      // 通过dom操作，所以用global
+      &:global(.active) {
+        background: var(--byte-plus-blue-brand-primary-60, rgb(0, 102, 252));
+      }
+    }
+  }
+  &:global(.dot) {
+    // 指示器为dot
+    & > i {
+      width: 6px;
+      height: 6px;
+      border-radius: 50%;
+      background-color: var(--Gray-3, rgb(229, 232, 239));
+      cursor: pointer;
+      // 通过dom操作，所以用global
+      &:global(.active) {
+        background: var(--byte-plus-blue-brand-primary-60, rgb(0, 102, 252));
+      }
+    }
+  }
+}