tona-hooks 1.0.20 → 1.0.22

package/README.md

@@ -1,15 +1,169 @@
 # tona-hooks
 
-博客园皮肤开发用的 React Hooks 工具库。
+<p align="center">
+  <img src="../../assets/tona.png" alt="Tona" width="100" />
+</p>
 
-## 安装
+<p align="center">
+  React hooks collection for CNBlogs theme development.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/tona-hooks"><img src="https://img.shields.io/npm/v/tona-hooks?style=flat-square" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/tona-hooks?style=flat-square" alt="license"></a>
+  <a href="https://preactjs.com"><img src="https://img.shields.io/badge/Preact->=10.0.0-673AB8?style=flat-square&logo=preact" alt="Preact"></a>
+</p>
+
+**English** | [中文](./README.zh-CN.md)
+
+## Features
+
+- **Preact Compatible** - Built for Preact, works with React
+- **CNBlogs Optimized** - Hooks designed specifically for CNBlogs environment
+- **TypeScript Support** - Full type definitions included
+- **Lightweight** - Tree-shakeable and minimal footprint
+
+## Installation
 
 ```bash
 npm install tona-hooks
 ```
 
-## 使用
+```bash
+pnpm add tona-hooks
+```
+
+```bash
+yarn add tona-hooks
+```
+
+## Usage
+
+```typescript
+import { useQueryDOM, useLocalStorage, useScroll } from 'tona-hooks'
+```
+
+## Available Hooks
+
+### `useAjaxComplete`
+
+Listen for AJAX requests completion.
+
+```typescript
+import { useAjaxComplete } from 'tona-hooks'
+
+useAjaxComplete((event, xhr, settings) => {
+  console.log('AJAX completed:', settings.url)
+})
+```
+
+### `useEffectOnce`
+
+Run effect only once on mount.
+
+```typescript
+import { useEffectOnce } from 'tona-hooks'
+
+useEffectOnce(() => {
+  console.log('Component mounted')
+})
+```
+
+### `useEventCallback`
+
+Create a stable callback reference.
+
+```typescript
+import { useEventCallback } from 'tona-hooks'
+
+const handleClick = useEventCallback(() => {
+  console.log('Clicked!')
+})
+```
+
+### `useIsomorphicLayoutEffect`
+
+Safe layout effect for SSR and browser.
+
+```typescript
+import { useIsomorphicLayoutEffect } from 'tona-hooks'
+
+useIsomorphicLayoutEffect(() => {
+  // DOM measurements
+}, [])
+```
 
-```javascript
+### `useLocalStorage`
+
+Persist state to localStorage.
+
+```typescript
+import { useLocalStorage } from 'tona-hooks'
+
+const [value, setValue] = useLocalStorage('key', 'defaultValue')
+```
+
+### `useQueryDOM`
+
+Query and observe DOM elements.
+
+```typescript
 import { useQueryDOM } from 'tona-hooks'
+
+const element = useQueryDOM('#my-element')
 ```
+
+### `useRafState`
+
+State updates synced with requestAnimationFrame.
+
+```typescript
+import { useRafState } from 'tona-hooks'
+
+const [position, setPosition] = useRafState({ x: 0, y: 0 })
+```
+
+### `useScroll`
+
+Track scroll position of an element.
+
+```typescript
+import { useScroll } from 'tona-hooks'
+
+const [x, y] = useScroll(ref)
+```
+
+### `useUnmount`
+
+Run cleanup on component unmount.
+
+```typescript
+import { useUnmount } from 'tona-hooks'
+
+useUnmount(() => {
+  console.log('Component unmounted')
+})
+```
+
+### `useWindowScroll`
+
+Track window scroll position.
+
+```typescript
+import { useWindowScroll } from 'tona-hooks'
+
+const [x, y] = useWindowScroll()
+```
+
+## Peer Dependencies
+
+```json
+{
+  "preact": ">=10.0.0"
+}
+```
+
+## Related
+
+- [tona](https://github.com/guangzan/tona/tree/main/packages/core) - Core framework
+- [tona-ui](https://github.com/guangzan/tona/tree/main/packages/ui) - UI components

package/README.zh-CN.md

@@ -0,0 +1,169 @@
+# tona-hooks
+
+<p align="center">
+  <img src="../../assets/tona.png" alt="Tona" width="100" />
+</p>
+
+<p align="center">
+  用于博客园主题开发的 React Hooks 集合。
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/tona-hooks"><img src="https://img.shields.io/npm/v/tona-hooks?style=flat-square" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/tona-hooks?style=flat-square" alt="license"></a>
+  <a href="https://preactjs.com"><img src="https://img.shields.io/badge/Preact->=10.0.0-673AB8?style=flat-square&logo=preact" alt="Preact"></a>
+</p>
+
+[English](./README.md) | **中文**
+
+## 特性
+
+- **Preact 兼容** - 为 Preact 构建，兼容 React
+- **博客园优化** - 专为博客园环境设计的 Hooks
+- **TypeScript 支持** - 包含完整的类型定义
+- **轻量级** - 可摇树优化，占用空间小
+
+## 安装
+
+```bash
+npm install tona-hooks
+```
+
+```bash
+pnpm add tona-hooks
+```
+
+```bash
+yarn add tona-hooks
+```
+
+## 使用
+
+```typescript
+import { useQueryDOM, useLocalStorage, useScroll } from 'tona-hooks'
+```
+
+## 可用的 Hooks
+
+### `useAjaxComplete`
+
+监听 AJAX 请求完成。
+
+```typescript
+import { useAjaxComplete } from 'tona-hooks'
+
+useAjaxComplete((event, xhr, settings) => {
+  console.log('AJAX completed:', settings.url)
+})
+```
+
+### `useEffectOnce`
+
+仅在挂载时运行一次 effect。
+
+```typescript
+import { useEffectOnce } from 'tona-hooks'
+
+useEffectOnce(() => {
+  console.log('Component mounted')
+})
+```
+
+### `useEventCallback`
+
+创建稳定的回调引用。
+
+```typescript
+import { useEventCallback } from 'tona-hooks'
+
+const handleClick = useEventCallback(() => {
+  console.log('Clicked!')
+})
+```
+
+### `useIsomorphicLayoutEffect`
+
+适用于 SSR 和浏览器的安全 layout effect。
+
+```typescript
+import { useIsomorphicLayoutEffect } from 'tona-hooks'
+
+useIsomorphicLayoutEffect(() => {
+  // DOM 测量
+}, [])
+```
+
+### `useLocalStorage`
+
+将状态持久化到 localStorage。
+
+```typescript
+import { useLocalStorage } from 'tona-hooks'
+
+const [value, setValue] = useLocalStorage('key', 'defaultValue')
+```
+
+### `useQueryDOM`
+
+查询和观察 DOM 元素。
+
+```typescript
+import { useQueryDOM } from 'tona-hooks'
+
+const element = useQueryDOM('#my-element')
+```
+
+### `useRafState`
+
+与 requestAnimationFrame 同步的状态更新。
+
+```typescript
+import { useRafState } from 'tona-hooks'
+
+const [position, setPosition] = useRafState({ x: 0, y: 0 })
+```
+
+### `useScroll`
+
+跟踪元素的滚动位置。
+
+```typescript
+import { useScroll } from 'tona-hooks'
+
+const [x, y] = useScroll(ref)
+```
+
+### `useUnmount`
+
+在组件卸载时运行清理。
+
+```typescript
+import { useUnmount } from 'tona-hooks'
+
+useUnmount(() => {
+  console.log('Component unmounted')
+})
+```
+
+### `useWindowScroll`
+
+跟踪窗口滚动位置。
+
+```typescript
+import { useWindowScroll } from 'tona-hooks'
+
+const [x, y] = useWindowScroll()
+```
+
+## 对等依赖
+
+```json
+{
+  "preact": ">=10.0.0"
+}
+```
+
+## 相关
+
+- [tona](https://github.com/guangzan/tona/tree/main/packages/core) - 核心框架
+- [tona-ui](https://github.com/guangzan/tona/tree/main/packages/ui) - UI 组件

package/dist/index.d.ts

@@ -1,9 +1,8 @@
 import { Dispatch, EffectCallback, useEffect } from "preact/hooks";
-import { SetStateAction } from "preact/compat";
+import { Dispatch as Dispatch$1, SetStateAction } from "preact/compat";
 import { RefObject } from "preact";
 
 //#region src/use-ajax-complete.d.ts
-
 /**
  * 通用的 Ajax 完成监听 Hook
  * @param config 配置对象
@@ -27,6 +26,16 @@ declare function useEventCallback<Args extends unknown[], R>(fn: ((...args: Args
 //#region src/use-isomorphic-layout-effect.d.ts
 declare const useIsomorphicLayoutEffect: typeof useEffect;
 //#endregion
+//#region src/use-local-storage.d.ts
+type parserOptions<T> = {
+  raw: true;
+} | {
+  raw: false;
+  serializer: (value: T) => string;
+  deserializer: (value: string) => T;
+};
+declare const useLocalStorage: <T>(key: string, initialValue?: T, options?: parserOptions<T>) => [T | undefined, Dispatch$1<SetStateAction<T | undefined>>, () => void];
+//#endregion
 //#region src/use-query-dom.d.ts
 interface UseQueryDomOptions<T> {
   selector: string;
@@ -68,4 +77,4 @@ interface State {
 }
 declare const useWindowScroll: () => State;
 //#endregion
-export { useAjaxComplete, useEffectOnce, useEventCallback, useIsomorphicLayoutEffect, useQueryDOM, useRafState, useScroll, useUnmount, useWindowScroll };
+export { useAjaxComplete, useEffectOnce, useEventCallback, useIsomorphicLayoutEffect, useLocalStorage, useQueryDOM, useRafState, useScroll, useUnmount, useWindowScroll };

package/dist/index.js

@@ -1,6 +1,5 @@
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "preact/hooks";
-import { useCallback as useCallback$1, useRef as useRef$1 } from "preact/compat";
-
+import { useCallback as useCallback$1, useLayoutEffect as useLayoutEffect$1, useRef as useRef$1, useState as useState$1 } from "preact/compat";
 //#region src/use-ajax-complete.ts
 /**
 * 通用的 Ajax 完成监听 Hook
@@ -27,17 +26,14 @@ function useAjaxComplete(config) {
 		};
 	}, [config]);
 }
-
 //#endregion
 //#region src/use-effect-once.ts
 const useEffectOnce = (effect) => {
 	useEffect(effect, []);
 };
-
 //#endregion
 //#region src/use-isomorphic-layout-effect.ts
 const useIsomorphicLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
-
 //#endregion
 //#region src/use-event-callback.ts
 function useEventCallback(fn) {
@@ -49,7 +45,65 @@ function useEventCallback(fn) {
 	}, [fn]);
 	return useCallback$1((...args) => ref.current?.(...args), [ref]);
 }
-
+//#endregion
+//#region src/misc/util.ts
+const noop = () => {};
+function on(obj, ...args) {
+	if (obj?.addEventListener) obj.addEventListener(...args);
+}
+function off(obj, ...args) {
+	if (obj?.removeEventListener) obj.removeEventListener(...args);
+}
+const isBrowser = typeof window !== "undefined";
+//#endregion
+//#region src/use-local-storage.ts
+const useLocalStorage = (key, initialValue, options) => {
+	if (!isBrowser) return [
+		initialValue,
+		noop,
+		noop
+	];
+	if (!key) throw new Error("useLocalStorage key may not be falsy");
+	const deserializer = options ? options.raw ? (value) => value : options.deserializer : JSON.parse;
+	const initializer = useRef$1((key) => {
+		try {
+			const serializer = options ? options.raw ? String : options.serializer : JSON.stringify;
+			const localStorageValue = localStorage.getItem(key);
+			if (localStorageValue !== null) return deserializer(localStorageValue);
+			else {
+				initialValue && localStorage.setItem(key, serializer(initialValue));
+				return initialValue;
+			}
+		} catch {
+			return initialValue;
+		}
+	});
+	const [state, setState] = useState$1(() => initializer.current(key));
+	useLayoutEffect$1(() => setState(initializer.current(key)), [key]);
+	return [
+		state,
+		useCallback$1((valOrFunc) => {
+			try {
+				const newState = typeof valOrFunc === "function" ? valOrFunc(state) : valOrFunc;
+				if (typeof newState === "undefined") return;
+				let value;
+				if (options) if (options.raw) if (typeof newState === "string") value = newState;
+				else value = JSON.stringify(newState);
+				else if (options.serializer) value = options.serializer(newState);
+				else value = JSON.stringify(newState);
+				else value = JSON.stringify(newState);
+				localStorage.setItem(key, value);
+				setState(deserializer(value));
+			} catch {}
+		}, [key, setState]),
+		useCallback$1(() => {
+			try {
+				localStorage.removeItem(key);
+				setState(void 0);
+			} catch {}
+		}, [key, setState])
+	];
+};
 //#endregion
 //#region src/use-query-dom.ts
 function useQueryDOM({ selector, observe = false, queryFn, ajaxUrl }) {
@@ -150,7 +204,6 @@ function useQueryDOM({ selector, observe = false, queryFn, ajaxUrl }) {
 		isPending
 	};
 }
-
 //#endregion
 //#region src/use-unmount.ts
 const useUnmount = (fn) => {
@@ -158,7 +211,6 @@ const useUnmount = (fn) => {
 	fnRef.current = fn;
 	useEffectOnce(() => () => fnRef.current());
 };
-
 //#endregion
 //#region src/use-raf-state.ts
 const useRafState = (initialState) => {
@@ -175,21 +227,9 @@ const useRafState = (initialState) => {
 	});
 	return [state, setRafState];
 };
-
-//#endregion
-//#region src/misc/util.ts
-function on(obj, ...args) {
-	if (obj?.addEventListener) obj.addEventListener(...args);
-}
-function off(obj, ...args) {
-	if (obj?.removeEventListener) obj.removeEventListener(...args);
-}
-const isBrowser = typeof window !== "undefined";
-
 //#endregion
 //#region src/use-scroll.ts
 const useScroll = (ref) => {
-	if (typeof ref !== "object" || typeof ref.current === "undefined") console.error("`useScroll` expects a single ref argument.");
 	const [state, setState] = useRafState({
 		x: 0,
 		y: 0
@@ -211,7 +251,6 @@ const useScroll = (ref) => {
 	}, [ref, setState]);
 	return state;
 };
-
 //#endregion
 //#region src/use-window-scroll.ts
 const useWindowScroll = () => {
@@ -221,12 +260,12 @@ const useWindowScroll = () => {
 	}));
 	useEffect(() => {
 		const handler = () => {
-			setState((state$1) => {
+			setState((state) => {
 				const { pageXOffset, pageYOffset } = window;
-				return state$1.x !== pageXOffset || state$1.y !== pageYOffset ? {
+				return state.x !== pageXOffset || state.y !== pageYOffset ? {
 					x: pageXOffset,
 					y: pageYOffset
-				} : state$1;
+				} : state;
 			});
 		};
 		handler();
@@ -240,6 +279,5 @@ const useWindowScroll = () => {
 	}, [setState]);
 	return state;
 };
-
 //#endregion
-export { useAjaxComplete, useEffectOnce, useEventCallback, useIsomorphicLayoutEffect, useQueryDOM, useRafState, useScroll, useUnmount, useWindowScroll };
+export { useAjaxComplete, useEffectOnce, useEventCallback, useIsomorphicLayoutEffect, useLocalStorage, useQueryDOM, useRafState, useScroll, useUnmount, useWindowScroll };

package/package.json

@@ -1,46 +1,46 @@
 {
   "name": "tona-hooks",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "description": "",
+  "keywords": [
+    "博客园"
+  ],
+  "homepage": "https://github.com/guangzan/tona/tree/main/packages/hooks#readme",
+  "bugs": {
+    "url": "https://github.com/guangzan/tona/issues"
+  },
+  "license": "MIT",
   "author": {
     "name": "guangzan",
-    "url": "https://www.cnblogs.com/guangzan",
-    "email": "guangzan1999@outlook.com"
+    "email": "guangzan1999@outlook.com",
+    "url": "https://www.cnblogs.com/guangzan"
   },
-  "license": "MIT",
-  "homepage": "https://github.com/guangzan/tona/tree/main/packages/hooks#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/guangzan/tona.git",
     "directory": "packages/hooks"
   },
-  "bugs": {
-    "url": "https://github.com/guangzan/tona/issues"
-  },
-  "keywords": [
-    "博客园"
+  "files": [
+    "dist"
   ],
   "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     }
   },
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
   "devDependencies": {
-    "tsdown": "latest"
+    "vite-plus": "latest"
   },
   "peerDependencies": {
-    "preact": "^10.28.2"
+    "preact": "^10.29.0"
   },
   "scripts": {
-    "dev": "tsdown --watch",
-    "build": "tsdown"
+    "dev": "vp pack --watch",
+    "build": "vp pack"
   }
 }