jean-react-utils 0.2.0 → 0.2.1

package/README.md

@@ -1,39 +1,177 @@
-# Jean-utils
+# Jean-react-utils
 
-## 目的
+一个为 Next.js 项目打造的 React 组件和工具库，集成了常用 UI 组件、Hooks、主题系统和国际化功能。
 
-个人 Next.js 博客与网站的可复用 UI 组件库
+## 特性
 
-## 内容
-- 通用组件（Button、Card）
-- React Hooks（useForceRerender）
-- Tailwind theme 配置
-- i18n 封装，基于 next-intl
-  - 支持调用方自定义messages路径
-  - 兼容 getRequestConfig 自动集成功能
+- 🎨 现代化的 UI 组件，基于 Tailwind CSS
+- 🌗 内置暗黑模式支持
+- 🌐 完整的国际化解决方案（基于 next-intl）
+- 🎯 TypeScript 支持
+- ⚡ 轻量级，tree-shakeable
+- 📦 开箱即用的主题系统
+
+## 安装
+
+```bash
+# npm
+npm install jean-react-utils
+
+# yarn
+yarn add jean-react-utils
+
+# pnpm
+pnpm add jean-react-utils
+```
+
+## 快速开始
+
+1. 配置 Tailwind CSS（如果你还没有配置）：
+
+```js
+// tailwind.config.js
+module.exports = {
+  content: [
+    // ...
+    "./node_modules/jean-react-utils/**/*.{js,ts,jsx,tsx}",
+  ],
+  // ...
+}
+```
+
+2. 导入并使用组件：
+
+```tsx
+import { Button, Heading } from 'jean-react-utils';
+
+export default function MyComponent() {
+  return (
+    <div>
+      <Heading.PageTitle>Welcome</Heading.PageTitle>
+      <Button variant="primary">Click me</Button>
+    </div>
+  );
+}
+```
+
+## 组件
+
+### Button
+现代化的按钮组件，支持多种变体和尺寸。
+
+```tsx
+<Button variant="default" size="lg">
+  Click me
+</Button>
+```
+
+变体选项：
+- default: 主要按钮
+- destructive: 危险操作
+- outline: 轮廓按钮
+- secondary: 次要按钮
+- ghost: 幽灵按钮
+- link: 链接样式
+
+尺寸选项：
+- default: 默认大小
+- sm: 小型按钮
+- lg: 大型按钮
+- icon: 图标按钮
+
+### Heading
+一组标题组件，包含不同级别和样式的标题。
+
+```tsx
+<Heading.PageTitle>页面标题</Heading.PageTitle>
+<Heading.SectionTitle>区块标题</Heading.SectionTitle>
+<Heading.CardTitle>卡片标题</Heading.CardTitle>
+<Heading.SubTitle>子标题</Heading.SubTitle>
+```
+
+## Hooks
+
+### useForceRerender
+强制组件重新渲染的 Hook。
+
+```tsx
+import { useForceRerender } from 'jean-react-utils';
+
+const Component = () => {
+  const rerender = useForceRerender();
+  
+  return <button onClick={rerender}>Force Rerender</button>;
+};
+```
+
+## 主题系统
+
+内置支持明暗主题切换，基于 Tailwind CSS。
+
+```tsx
+import { ThemeProvider, ThemeToggle } from 'jean-react-utils';
+
+export default function App() {
+  return (
+    <ThemeProvider>
+      <ThemeToggle />
+      {/* 你的应用内容 */}
+    </ThemeProvider>
+  );
+}
+```
+
+## 国际化
+
+基于 next-intl 的国际化解决方案，支持自定义消息路径和自动集成。
+
+```tsx
+// 配置示例
+import { i18nConfig } from 'jean-react-utils';
+
+export default i18nConfig({
+  messages: {
+    zh: { ... },
+    en: { ... }
+  }
+});
+```
 
 ## 项目结构
 ```
-jean-utils/
+jean-react-utils/
 ├── src/
 │   ├── components/    ← Button / Card 等通用组件
 │   ├── layout/        ← Header / Footer / Nav
 │   ├── hooks/         ← useForceRerender、useMediaQuery 等
-│   ├── theme/         ← tailwind theme、token
+│   ├── theme/         ← tailwind theme、token 主题切换
 │   ├── i18n/          ← next-intl 封装
 │   └── index.ts       ← 统一导出
 ├── package.json
 ├── tsconfig.json
-├── tailwind.config.ts
-├── vitest.config.ts
-├── postcss.config.js
 └── README.md
 ```
 
-## 现有痛点
-- 每次调试都涉及多个package，心智负担大
-- 更新组件时要发布版本、链接依赖、跑构建流程
+## 开发
+
+```bash
+# 安装依赖
+pnpm install
 
+# 开发模式
+pnpm dev
+
+# 构建
+pnpm build
+
+# 运行测试
+pnpm test
 ```
 
-```
+## 贡献
+
+欢迎提交 Issue 和 Pull Request。
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -1,39 +1,169 @@
-import React, { ReactNode } from 'react';
+import * as class_variance_authority_dist_types from 'class-variance-authority/dist/types';
+import * as React$1 from 'react';
+import React__default, { ReactNode } from 'react';
+import { VariantProps } from 'class-variance-authority';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ThemeProviderProps } from 'next-themes';
+import { ClassValue } from 'clsx';
 
-interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
-    variant?: 'primary' | 'secondary' | 'outline';
-    size?: 'sm' | 'md' | 'lg';
+/**
+ * 按钮变体样式配置
+ * @private
+ */
+declare const buttonVariants: (props?: ({
+    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | "borderNone" | null | undefined;
+    size?: "default" | "sm" | "lg" | "icon" | null | undefined;
+} & class_variance_authority_dist_types.ClassProp) | undefined) => string;
+/**
+ * Button 组件的属性类型
+ * @extends {React.ButtonHTMLAttributes<HTMLButtonElement>} 继承原生按钮属性
+ */
+interface ButtonProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
 }
-declare const Button: React.FC<ButtonProps>;
+/**
+ * 现代化的按钮组件，支持多种变体和尺寸。
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // 默认按钮
+ * <Button>Click me</Button>
+ *
+ * // 带变体的按钮
+ * <Button variant="destructive" size="lg">Delete</Button>
+ *
+ * // 图标按钮
+ * <Button variant="ghost" size="icon">
+ *   <IconComponent />
+ * </Button>
+ * ```
+ *
+ * @param {ButtonProps} props - 组件属性
+ * @param {string} [props.variant="default"] - 按钮变体样式
+ *   - 'default' - 主要按钮
+ *   - 'destructive' - 危险操作按钮
+ *   - 'outline' - 轮廓按钮
+ *   - 'secondary' - 次要按钮
+ *   - 'ghost' - 幽灵按钮
+ *   - 'link' - 链接样式按钮
+ * @param {string} [props.size="default"] - 按钮尺寸
+ *   - 'default' - 默认大小
+ *   - 'sm' - 小型按钮
+ *   - 'lg' - 大型按钮
+ *   - 'icon' - 图标按钮
+ * @param {string} [props.className] - 自定义类名
+ */
+declare const Button: React$1.ForwardRefExoticComponent<ButtonProps & React$1.RefAttributes<HTMLButtonElement>>;
 
+/**
+ * Heading 组件的通用属性类型
+ */
 interface HeadingProps {
+    /** 子元素内容 */
     children?: ReactNode;
+    /** 自定义类名 */
     className?: string;
+    /** 标题文本，可以替代 children */
     title?: string;
 }
+/**
+ * 页面主标题组件，带有渐变色效果和动画
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <PageTitle>Welcome to My Site</PageTitle>
+ *
+ * // 使用 title 属性
+ * <PageTitle title="Welcome" className="my-8" />
+ * ```
+ */
 declare function PageTitle({ children, title, className }: HeadingProps): react_jsx_runtime.JSX.Element;
+/**
+ * 区块标题组件，用于页面主要区块的标题
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <SectionTitle>Featured Products</SectionTitle>
+ *
+ * // 自定义样式
+ * <SectionTitle className="mb-8">Our Services</SectionTitle>
+ * ```
+ */
 declare function SectionTitle({ children, title, className }: HeadingProps): react_jsx_runtime.JSX.Element;
+/**
+ * 卡片标题组件，用于卡片或小区块的标题
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <CardTitle>Product Features</CardTitle>
+ *
+ * // 在卡片中使用
+ * <Card>
+ *   <CardTitle>Premium Plan</CardTitle>
+ *   <CardContent>...</CardContent>
+ * </Card>
+ * ```
+ */
 declare function CardTitle({ children, title, className }: HeadingProps): react_jsx_runtime.JSX.Element;
+/**
+ * 子标题组件，用于次级内容的标题
+ *
+ * @component
+ * @example
+ * font-semibold: font-weight: 600;
+ * text-lg: font-size: 1.125rem;
+ * ```tsx
+ * <SubTitle>Technical Details</SubTitle>
+ *
+ * // 在列表中使用
+ * <div>
+ *   <SubTitle>Specifications</SubTitle>
+ *   <ul>...</ul>
+ * </div>
+ * ```
+ */
 declare function SubTitle({ children, title, className }: HeadingProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * 导航项接口
+ * @interface NavItem
+ */
 interface NavItem {
+    /** 导航项唯一标识 */
     key: string;
+    /** 导航链接地址 */
     href: string;
     label: string;
+    /** 自定义样式类名 */
     className?: {
+        /** PC端样式 */
         pc?: string;
+        /** 移动端样式 */
         mobile?: string;
     };
 }
+interface HeaderTheme {
+    activeClassName?: string;
+    mobileMenu?: {
+        button?: string;
+        nav?: string;
+    };
+}
 interface HeaderProps {
-    logo: React.ReactNode;
+    /** Logo 组件 */
+    logo: React__default.ReactNode;
+    /** 导航菜单项 */
     menuItems: NavItem[];
+    /** 自定义样式类名 */
     className?: string;
-    /** 是否啟用動畫效果 */
+    /** 是否启用动画效果 */
     enableAnimation?: boolean;
+    theme?: HeaderTheme;
 }
-declare const Header: React.FC<HeaderProps>;
+declare const Header: React__default.FC<HeaderProps>;
 
 interface FooterLink {
     href: string;
@@ -66,8 +196,50 @@ interface FooterProps {
     /** 自定義類名 */
     className?: string;
 }
-declare const Footer: React.FC<FooterProps>;
+declare const Footer: React__default.FC<FooterProps>;
+
+/**
+ * 基础布局组件，提供页面的基本结构
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <BasicLayout>
+ *   <main>
+ *     <h1>Welcome</h1>
+ *     <p>Content goes here</p>
+ *   </main>
+ * </BasicLayout>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 带有 metadata 的使用示例
+ * <BasicLayout
+ *   metadata={{
+ *     title: 'My Page',
+ *     description: 'Page description'
+ *   }}
+ * >
+ *   <div>Content</div>
+ * </BasicLayout>
+ * ```
+ */
+declare function BasicLayout({ children }: {
+    children: React.ReactNode;
+}): JSX.Element;
 
 declare const useForceRerender: () => [number, () => void];
 
-export { Button, CardTitle, Footer, Header, PageTitle, SectionTitle, SubTitle, useForceRerender };
+interface SmoothScrollProviderProps {
+    children: React$1.ReactNode;
+}
+declare function SmoothScrollProvider({ children }: SmoothScrollProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function ThemeToggle(): react_jsx_runtime.JSX.Element;
+
+declare function ThemeProvider({ children, ...props }: ThemeProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function cn(...inputs: ClassValue[]): string;
+
+export { BasicLayout, Button, CardTitle, Footer, Header, PageTitle, SectionTitle, SmoothScrollProvider, SubTitle, ThemeProvider, ThemeToggle, cn, useForceRerender };

package/dist/index.d.ts

@@ -1,39 +1,169 @@
-import React, { ReactNode } from 'react';
+import * as class_variance_authority_dist_types from 'class-variance-authority/dist/types';
+import * as React$1 from 'react';
+import React__default, { ReactNode } from 'react';
+import { VariantProps } from 'class-variance-authority';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ThemeProviderProps } from 'next-themes';
+import { ClassValue } from 'clsx';
 
-interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
-    variant?: 'primary' | 'secondary' | 'outline';
-    size?: 'sm' | 'md' | 'lg';
+/**
+ * 按钮变体样式配置
+ * @private
+ */
+declare const buttonVariants: (props?: ({
+    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | "borderNone" | null | undefined;
+    size?: "default" | "sm" | "lg" | "icon" | null | undefined;
+} & class_variance_authority_dist_types.ClassProp) | undefined) => string;
+/**
+ * Button 组件的属性类型
+ * @extends {React.ButtonHTMLAttributes<HTMLButtonElement>} 继承原生按钮属性
+ */
+interface ButtonProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
 }
-declare const Button: React.FC<ButtonProps>;
+/**
+ * 现代化的按钮组件，支持多种变体和尺寸。
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // 默认按钮
+ * <Button>Click me</Button>
+ *
+ * // 带变体的按钮
+ * <Button variant="destructive" size="lg">Delete</Button>
+ *
+ * // 图标按钮
+ * <Button variant="ghost" size="icon">
+ *   <IconComponent />
+ * </Button>
+ * ```
+ *
+ * @param {ButtonProps} props - 组件属性
+ * @param {string} [props.variant="default"] - 按钮变体样式
+ *   - 'default' - 主要按钮
+ *   - 'destructive' - 危险操作按钮
+ *   - 'outline' - 轮廓按钮
+ *   - 'secondary' - 次要按钮
+ *   - 'ghost' - 幽灵按钮
+ *   - 'link' - 链接样式按钮
+ * @param {string} [props.size="default"] - 按钮尺寸
+ *   - 'default' - 默认大小
+ *   - 'sm' - 小型按钮
+ *   - 'lg' - 大型按钮
+ *   - 'icon' - 图标按钮
+ * @param {string} [props.className] - 自定义类名
+ */
+declare const Button: React$1.ForwardRefExoticComponent<ButtonProps & React$1.RefAttributes<HTMLButtonElement>>;
 
+/**
+ * Heading 组件的通用属性类型
+ */
 interface HeadingProps {
+    /** 子元素内容 */
     children?: ReactNode;
+    /** 自定义类名 */
     className?: string;
+    /** 标题文本，可以替代 children */
     title?: string;
 }
+/**
+ * 页面主标题组件，带有渐变色效果和动画
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <PageTitle>Welcome to My Site</PageTitle>
+ *
+ * // 使用 title 属性
+ * <PageTitle title="Welcome" className="my-8" />
+ * ```
+ */
 declare function PageTitle({ children, title, className }: HeadingProps): react_jsx_runtime.JSX.Element;
+/**
+ * 区块标题组件，用于页面主要区块的标题
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <SectionTitle>Featured Products</SectionTitle>
+ *
+ * // 自定义样式
+ * <SectionTitle className="mb-8">Our Services</SectionTitle>
+ * ```
+ */
 declare function SectionTitle({ children, title, className }: HeadingProps): react_jsx_runtime.JSX.Element;
+/**
+ * 卡片标题组件，用于卡片或小区块的标题
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <CardTitle>Product Features</CardTitle>
+ *
+ * // 在卡片中使用
+ * <Card>
+ *   <CardTitle>Premium Plan</CardTitle>
+ *   <CardContent>...</CardContent>
+ * </Card>
+ * ```
+ */
 declare function CardTitle({ children, title, className }: HeadingProps): react_jsx_runtime.JSX.Element;
+/**
+ * 子标题组件，用于次级内容的标题
+ *
+ * @component
+ * @example
+ * font-semibold: font-weight: 600;
+ * text-lg: font-size: 1.125rem;
+ * ```tsx
+ * <SubTitle>Technical Details</SubTitle>
+ *
+ * // 在列表中使用
+ * <div>
+ *   <SubTitle>Specifications</SubTitle>
+ *   <ul>...</ul>
+ * </div>
+ * ```
+ */
 declare function SubTitle({ children, title, className }: HeadingProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * 导航项接口
+ * @interface NavItem
+ */
 interface NavItem {
+    /** 导航项唯一标识 */
     key: string;
+    /** 导航链接地址 */
     href: string;
     label: string;
+    /** 自定义样式类名 */
     className?: {
+        /** PC端样式 */
         pc?: string;
+        /** 移动端样式 */
         mobile?: string;
     };
 }
+interface HeaderTheme {
+    activeClassName?: string;
+    mobileMenu?: {
+        button?: string;
+        nav?: string;
+    };
+}
 interface HeaderProps {
-    logo: React.ReactNode;
+    /** Logo 组件 */
+    logo: React__default.ReactNode;
+    /** 导航菜单项 */
     menuItems: NavItem[];
+    /** 自定义样式类名 */
     className?: string;
-    /** 是否啟用動畫效果 */
+    /** 是否启用动画效果 */
     enableAnimation?: boolean;
+    theme?: HeaderTheme;
 }
-declare const Header: React.FC<HeaderProps>;
+declare const Header: React__default.FC<HeaderProps>;
 
 interface FooterLink {
     href: string;
@@ -66,8 +196,50 @@ interface FooterProps {
     /** 自定義類名 */
     className?: string;
 }
-declare const Footer: React.FC<FooterProps>;
+declare const Footer: React__default.FC<FooterProps>;
+
+/**
+ * 基础布局组件，提供页面的基本结构
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <BasicLayout>
+ *   <main>
+ *     <h1>Welcome</h1>
+ *     <p>Content goes here</p>
+ *   </main>
+ * </BasicLayout>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 带有 metadata 的使用示例
+ * <BasicLayout
+ *   metadata={{
+ *     title: 'My Page',
+ *     description: 'Page description'
+ *   }}
+ * >
+ *   <div>Content</div>
+ * </BasicLayout>
+ * ```
+ */
+declare function BasicLayout({ children }: {
+    children: React.ReactNode;
+}): JSX.Element;
 
 declare const useForceRerender: () => [number, () => void];
 
-export { Button, CardTitle, Footer, Header, PageTitle, SectionTitle, SubTitle, useForceRerender };
+interface SmoothScrollProviderProps {
+    children: React$1.ReactNode;
+}
+declare function SmoothScrollProvider({ children }: SmoothScrollProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function ThemeToggle(): react_jsx_runtime.JSX.Element;
+
+declare function ThemeProvider({ children, ...props }: ThemeProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function cn(...inputs: ClassValue[]): string;
+
+export { BasicLayout, Button, CardTitle, Footer, Header, PageTitle, SectionTitle, SmoothScrollProvider, SubTitle, ThemeProvider, ThemeToggle, cn, useForceRerender };