@slotjs/hooks 0.0.2 → 0.0.4

package/README.md

@@ -1,8 +1,56 @@
 # @slotjs/hooks
 
+`@slotjs/hooks` 目前提供 `useResponsive`，用于根据视口宽度动态设置根节点 `html` 的字体大小，适合基于 `rem` 的响应式布局。
+
+```bash
+npm i @slotjs/hooks
+```
+
+## useResponsive
+
+`useResponsive` 会在组件挂载后立即根据当前视口宽度设置一次 `html` 的 `font-size`，并在窗口尺寸变化时自动更新。
+
+计算规则如下：
+
 ```ts
+html.style.fontSize = `${baseFontSize * Math.min(clientWidth / baseWidth, 2)}px`;
+```
+
+也就是说：
+
+- 设计稿宽度等于 `baseWidth` 时，根字体大小为 `baseFontSize`
+- 页面变宽时会按比例放大，但最大只放大到 `2x`
+- 页面变窄时会按比例缩小
+
+### TypeScript 签名
+
+```ts
+function useResponsive(baseWidth?: number, baseFontSize?: number): boolean;
+```
+
+### 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `baseWidth` | `number` | `1920` | 设计稿基准宽度 |
+| `baseFontSize` | `number` | `16` | 设计稿基准宽度下的根字体大小 |
+
+### 返回值
+
+返回 `boolean` 类型的 `isReady`：
+
+- `false`：初始字体大小尚未设置完成
+- `true`：已经完成首次计算并设置根字体大小
+
+这个返回值适合用来控制首屏渲染，避免依赖 `rem` 的内容在初始化前出现尺寸闪动。
+
+### 基础用法
+
+```tsx
+import { useResponsive } from "@slotjs/hooks";
+
 const Index: React.FC = () => {
-  const isReady = useRootFontSize();
+  const isReady = useResponsive();
 
   return isReady ? (
     <ContentContainer>content</ContentContainer>
@@ -11,3 +59,29 @@ const Index: React.FC = () => {
   );
 };
 ```
+
+### 自定义设计稿宽度和基准字号
+
+```tsx
+import { useResponsive } from "@slotjs/hooks";
+
+const Page = () => {
+  const isReady = useResponsive(1440, 20);
+
+  if (!isReady) return null;
+
+  return <main style={{ fontSize: "1rem" }}>content</main>;
+};
+```
+
+在上面的例子里：
+
+- 当视口宽度为 `1440px` 时，`html` 根字体大小为 `20px`
+- 当视口宽度为 `720px` 时，根字体大小为 `10px`
+- 当视口宽度大于等于 `2880px` 时，根字体大小封顶为 `40px`
+
+### 使用建议
+
+- 推荐配合 `rem` 单位使用，这样页面元素会随着根字体大小一起缩放
+- 该 hook 依赖 `window` 和 `document`，应在浏览器环境中使用
+- 如果项目存在 SSR，建议只在客户端渲染阶段调用

package/dist/types/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A React hook to set the root font size based on the viewport width.
+ * It scales the font size up to a maximum of 2x the base font size.
+ * This is useful for responsive designs where the font size needs to adapt to different screen sizes.
+ * It listens for window resize events to adjust the font size dynamically.
+ *
+ * @param baseWidth
+ * @param baseFontSize
+ * @example
+ * ```ts
+ * const isReady = useResponsive(1920, 16);
+ * ```
+ * // This will set the root font size based on a base width of 1920px
+ * // and a base font size of 16px.
+ * // The hook returns true once the font size has been set, allowing components to render correctly
+ * // with the appropriate font size.
+ * @returns
+ */
+export declare function useResponsive(baseWidth?: number, baseFontSize?: number): boolean;
+
+export { }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@slotjs/hooks",
   "private": false,
-  "version": "0.0.2",
+  "version": "0.0.4",
   "type": "module",
   "description": "@slotjs/hooks for react",
   "homepage": "https://github.com/slotjs/hooks.git#readme",
@@ -16,6 +16,7 @@
   "author": "iamwjun",
   "scripts": {
     "dev": "vite",
+    "types": "tsc -p tsconfig.build.json",
     "build": "tsc -b && vite build",
     "lint": "eslint .",
     "preview": "vite preview",
@@ -30,6 +31,7 @@
     "@eslint/js": "^9.32.0",
     "@testing-library/jest-dom": "^6.6.4",
     "@testing-library/react": "^16.3.0",
+    "@types/node": "^24.3.0",
     "@types/react": "^19.1.9",
     "@types/react-dom": "^19.1.7",
     "@vitejs/plugin-react": "^4.7.0",
@@ -41,9 +43,21 @@
     "typescript": "~5.8.3",
     "typescript-eslint": "^8.39.0",
     "vite": "^7.1.0",
+    "vite-plugin-dts": "^4.5.4",
     "vitest": "^3.2.4"
   },
   "files": [
-    "dist"
-  ]
+    "dist",
+    "README.md"
+  ],
+  "main": "dist/index.umd.cjs",
+  "module": "dist/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.umd.cjs"
+    }
+  }
 }

package/dist/README.md

@@ -1,13 +0,0 @@
-# @slotjs/hooks
-
-```ts
-const Index: React.FC = () => {
-  const isReady = useRootFontSize();
-
-  return isReady ? (
-    <ContentContainer>content</ContentContainer>
-  ) : (
-    <FullScreenWrapper>loading</FullScreenWrapper>
-  );
-};
-```