earthnut 0.1.7-alpha.0 → 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/image/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @license MIT
+ * earthnut@components/image/index.d.ts 
+ * Copyright (c) 2025 earthnut.dev
+ * 请在项目根参看详细许可证明
+ */
+import React from 'react';
+import { EnImageProps } from './types';
+/**  简单的图像  */
+declare const Image: React.ForwardRefExoticComponent<Omit<EnImageProps, "ref"> & React.RefAttributes<HTMLImageElement>>;
+export { Image };
+export type { EnImageProps };

package/components/image/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @license MIT
+ * earthnut@components/image/types.d.ts 
+ * Copyright (c) 2025 earthnut.dev
+ * 请在项目根参看详细许可证明
+ */
+export type EnImageProps = {
+    /**  下载错误时展示的图像  */
+    errorSrc?: string;
+    /**  加载中的图像  */
+    loadingSrc?: string;
+} & React.DetailedHTMLProps<React.ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>;

package/components/image/useSrcChange.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @license MIT
+ * earthnut@components/image/useSrcChange.d.ts 
+ * Copyright (c) 2025 earthnut.dev
+ * 请在项目根参看详细许可证明
+ */
+/** 当地址触发变更 */
+export declare function useSrcChange(src: string, fallbackSrc?: string): {
+    resultSrc: string;
+    loadComplete: number;
+};

package/components/ripples/LazyRippleEle.d.ts

@@ -12,9 +12,9 @@
  * @CreateDate  周四  12/12/2024
  * @Description 涟漪
  ****************************************************************************/
-import React from 'react';
 import { RipplesOptions } from '../../customHooks/useRipples/types';
 import { RippleEle } from './types';
+import * as React from 'react';
 /**
  *
  * ### 一个 ripple 背景组件

package/components/ripples/RipplesEle.d.ts

@@ -4,9 +4,9 @@
  * Copyright (c) 2025 earthnut.dev
  * 请在项目根参看详细许可证明
  */
-import React from 'react';
 import { RipplesOptions } from '../../customHooks/useRipples/types';
 import { RippleEle } from './types';
+import * as React from 'react';
 /**
  *
  * ### 一个 ripple 背景组件
@@ -25,7 +25,7 @@ import { RippleEle } from './types';
  * 使用：
  *
  * ```ts
- *  import { BackgroundRipple } from 'earthnut/BackgroundRipple';
+ *  import { BackgroundRipple } from 'earthnut';
  *  // 也可以全量导入
  *  // import { BackgroundRipple } from 'earthnut';
  *  ...

package/components/ripples/types.d.ts

@@ -4,7 +4,7 @@
  * Copyright (c) 2025 earthnut.dev
  * 请在项目根参看详细许可证明
  */
-import { RipplesOptions } from '../../customHooks';
+import { RipplesOptions } from '../../customHooks/useRipples';
 export type RippleEle = {
     /**  切换当前的状态  */
     toggleState(): void;

package/components/ripples/useOptionUpdate.d.ts

@@ -4,7 +4,7 @@
  * Copyright (c) 2025 earthnut.dev
  * 请在项目根参看详细许可证明
  */
-import { Ripples, RipplesOptions } from '../../customHooks';
+import { Ripples, RipplesOptions } from '../../customHooks/useRipples/index';
 /**
  * 更新参数数据
  */

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/buildBackground/utils/create-canvas-element.d.ts

@@ -4,6 +4,6 @@
  * Copyright (c) 2025 earthnut.dev
  * 请在项目根参看详细许可证明
  */
-import { Ripples } from 'components/ripples';
+import { Ripples } from '../../../../components/ripples';
 /**  根据给出的 html 数据构建一个 canvas   */
 export declare function createCanvasElement(this: Ripples, img: CanvasImageSource): HTMLCanvasElement;

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/useRipples/use-lazy-ripple.d.ts

@@ -4,10 +4,11 @@
  * Copyright (c) 2025 earthnut.dev
  * 请在项目根参看详细许可证明
  */
-import { useRipples } from '.';
+import { Ripples } from './ripplesClass';
+import { RipplesOptions } from './types';
 /**  动态加载包含的自定义的钩子  */
-export declare function useLazyRipples(): {
-    hook: typeof useRipples | undefined;
+export declare function useLazyRipples(canvas: React.RefObject<HTMLCanvasElement | null>, option?: RipplesOptions): {
+    ripples: React.RefObject<Ripples | null>;
     isLoading: boolean;
-    error: null;
+    error: unknown;
 };

package/customHooks/useTimeId.d.ts

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