earthnut 0.1.7 → 0.2.0

package/README.md

@@ -8,6 +8,10 @@
 npm install  --save earthnut
 ```
 
+## 文档
+
+参阅 [earthnut](https://earthnut.dev/quickUse/)
+
 ## 涟漪背景
 
 由于当前组件的开发进度较缓慢，目前：
@@ -23,6 +27,105 @@ npm install  --save earthnut
 
 切换背景最好不好通过设置
 
-## 文档
+## 自定义钩子
 
-参阅 [earthnut](https://earthnut.dev/quickUse/)
+几个简单的自定义钩子，写着玩
+
+### useTimeId
+
+就是 `useRef` 和 `useEffect` 的简单使用。
+
+```ts
+import { useTimeId } from 'earthnut';
+
+export function Home () {
+
+  const timeId = useTimeId();
+
+  return <>
+      <button
+      onclick = { () => {
+          timeId.current = setTimeout(() =>
+            console.log('没有感情的按钮 A 打印了一条没有感情的消息'), 2500);
+          }
+      }>
+          没有感情的按钮 A
+      </button>
+      <button onclick={()=> clearTimeout(timeId.current)}>没有感情的按钮 B</button>
+  </>
+}
+```
+
+### useAnimationFrame
+
+使用下一帧动画。
+
+```ts
+import { useAnimationFrame } from 'earthnut';
+```
+
+## scss 样式
+
+导出了一个 `common.css` 作为样式使用，还可以引用其中的 `scss` 文件使用其中的函数。
+
+如果使用 `common.css` 建议仅在跟下进行导入即可，避免在
+
+在使用 `webpack` 的应用中可以这样引入
+
+```javascript
+// webpack.config.js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.scss$/,
+        use: [
+          'style-loader',
+          'css-loader',
+          {
+            loader: 'sass-loader',
+            options: {
+              sassOptions: {
+                includePaths: [path.resolve(__dirname, 'node_modules/ui-library-a/src/scss')], // UI 库 SCSS 路径
+              },
+            },
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
+在使用 `vite` 的应用中可以这样引入
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import path from 'path';
+
+export default defineConfig({
+  css: {
+    preprocessorOptions: {
+      scss: {
+        additionalData: `@use "${path.resolve(__dirname, 'node_modules/ui-library-a/src/scss')}" as lib;`,
+        includePaths: [path.resolve(__dirname, 'node_modules/ui-library-a/src/scss')],
+      },
+    },
+  },
+});
+```
+
+为了防止意外覆盖别人的自定义 css 属性，该样式皆以 `en-` 为前缀。譬如：
+
+```tsx
+import { xcn } from 'earthnut';
+
+export function Home() {
+  return (
+    <div>
+      <p className={xcn('en-text-in=one-line')}>无论我字数多少，仅会会在同一行就行打印。</p>
+    </div>
+  );
+}
+```

package/components/ripples/RipplesEle.d.ts

@@ -25,7 +25,7 @@ import * as React from 'react';
  * 使用：
  *
  * ```ts
- *  import { BackgroundRipple } from 'earthnut/BackgroundRipple';
+ *  import { BackgroundRipple } from 'earthnut';
  *  // 也可以全量导入
  *  // import { BackgroundRipple } from 'earthnut';
  *  ...

package/customHooks/useAnimationFrame.d.ts

@@ -13,36 +13,55 @@
  * @CreateDate  周二  01/07/2025
  * @Description 使用 animationFrame
  ****************************************************************************/
+/**  使用动画结果  */
+export interface UseAnimationFrameResult {
+    /**  取消执行动画  */
+    cancel(): void;
+    /**  当前取消的状态  */
+    canceled: boolean;
+    /**  再次执行  */
+    render(): void;
+}
+export type AnimationFrameOption = boolean | {
+    immediately?: boolean;
+    once?: boolean;
+};
 /**
  *
- * ### 导出一个使用 `useRef` 创建的 `number`
+ *  该钩子在组件卸载时会自动调用 `window.cancelAnimationFrame` 清理传入的回调方法。
+ *  默认是传入即启动调用方法
  *
- *    该数值在组件卸载时会自动调用 `window.cancelAnimationFrame` 清理
- * @description 一个接收 `window.requestAnimationFrame` 的返回值的 `ref`
- * @returns  <React.RefObject: number>
- * @version 0.0.3
- * @see   https://earthnut.dev/use-animation-frame
+ * @description 创建一个会自己关闭（组建卸载时）的 animationFrame。当然，可以通过返回值手动终止
+ * @param callback  使用回调函数。回调函数有两个参数，除了默认的时间，还有另一个用于暂停后的记时时间。如果没有主动暂停，两者时间总是趋近于相等的（可能有其他延迟造成时间差越来越大）。如果没有暂停需求，使用第一个默认时间就可以了。
+ * @param [option=false] 使用第二参数，可指定是否立即执行及是否仅执行一次
+ * @returns  返回值包含执行状态
+ * @version 0.2.0
+ * @see   https://earthnut.dev/custom-hooks/use-animation-frame
  * @example
  * 使用：
  *
  * ```ts
- *  import { useAnimationFrame } from 'earthnut/useAnimationFrame';
- *  // 也可以全量导入
  *  // import { useAnimationFrame } from 'earthnut';
  *  ...
- *  const animationFrameId = useAnimationFrame();
  *
- *  function performAction(time?: number){
- *    useAnimationFrame.current = window.requestAnimationFrame(performAction);
- *    ...
- *  }
- *
- *  useEffect(()=>{
- *      animationFrameId.current = window.requestAnimationFrame(performAction);
+ *  export function Home () {
+ *  // 如果没有主动暂停的需要，直接使用默认的 time 最好。如果中间有使用暂停。那么 time 值是不连贯的，而 runTime 是连贯的
+ *  const result = useAnimationFrame((time ,runTime) => {
+ *     ... //
  *  });
+ *
+ *
+ * return <>
+ *
+ *    <button onclick={() => result.cancel()}>暂停</button>
+ *    <button onclick={() => result.render()}>恢复</button>
+ *   </>
+ * }
  *  ...
  *
  * ```
  *
+ * 当然，可使用第二参数执行立即执行还是仅执行一次（作用不大，不与赘述）
+ *
  */
-export declare function useAnimationFrameId(): React.RefObject<number>;
+export declare function useAnimationFrame(callback: (time: number, runtime: number) => void, option?: AnimationFrameOption): UseAnimationFrameResult;

package/customHooks/useInputIsComposing.d.ts

@@ -22,30 +22,30 @@
  * @param inputRef [React.RefObject<HTMLInputElement | HTMLTextAreaElement>] 输入框的 ref
  * @returns  React.RefObject<boolean>
  * @version 0.0.4
- * @see   https://earthnut.dev/use-input-is-composing
+ * @see   https://earthnut.dev/custom-hooks/use-input-is-composing
  * @example
  *
  * 使用：
  *
  * ```ts
- *  import { useInputIsComposing } from 'earthnut/useInputIsComposing';
- *  // 也可以全量导入
- *  // import { useInputIsComposing } from 'earthnut';
+ *  import { useInputIsComposing } from 'earthnut';
+ *
  *  ...
  *  const inputRef = useRef<HTMLInputElement>(null);
  *
  *  const inputIsComposing = useInputIsComposing(inputRef);
  *  ...
- *  function enterDown()(e: React.KeyboardEvent<HTMLInputElement>) {
+ *  function enterDown(e: React.KeyboardEvent<HTMLInputElement>) {
  *     if (e.key === 'Enter') {
  *        if (isComposing.current) {
  *            console.log("此时此景，按回车键说明为了从候选词中挑选");
- *        } else
+ *        } else {
  *           console.log("输入完毕，敲回车是为了看一些开发者是否绑定了其他事件");
+ *        }
  *     }
  *  }
  *  ...
- *  <input type="text" onKeyDown={enterDown} />
+ *  <input type="text" onKeyDown={enterDown} ref={inputRef} />
  *  ...
  * ```
  */

package/customHooks/useRipples/index.d.ts

@@ -14,16 +14,14 @@ import { Ripples } from './ripplesClass';
  * @param canvas `usrRef` 包裹的 `HTMLCanvasElement`，用于绘制图像
  * @param option  初始化的
  * @version 0.0.3
- * @see  https://earthnut.dev/use-ripples
+ * @see  https://earthnut.dev/custom-hooks/use-ripples
  * @see  JQuery https://github.com/sirxemic/jquery.ripples
  * @example
  *
  * 下面是在 <BackgroundRipple> 中使用
  *
  * ```ts
- * import { useRipples } from 'earthnut/useRipples';
- * // 也可以使用包全量导入
- * // import { useRipples } from 'earthnut';
+ * import { useRipples } from 'earthnut';
  *
  *  export function BackgroundRipple(props: BackgroundRipplesProps) {
  *

package/customHooks/useTimeId.d.ts

@@ -17,8 +17,6 @@
  * 使用：
  *
  * ```ts
- *  import { useTimeId } from 'earthnut/useTimeId';
- *  // 也可以全量导入
  *  // import { useTimeId } from 'earthnut';
  *  ...
  *  const timeoutId = useTimeId();