npm package: @libeilong/react-reactive
Description: 在 React 中使用 Vue 响应式系统的适配器。
Author: lblblong
Latest version: 0.3.0

# @libeilong/react-reactive

在 React 中使用 Vue 响应式系统的适配器。

## 安装

```bash
pnpm add @libeilong/react-reactive
```

## 基础使用

```tsx
import { reactive } from '@vue/reactivity'
import { Observer } from '@libeilong/react-reactive'

function App() {
  const state = reactive({ count: 0 })

  return (
    <Observer>
      {() => (
        <div>
          <p>Count: {state.count}</p>
          <button onClick={() => state.count++}>Increment</button>
        </div>
      )}
    </Observer>
  )
}
```

## SSR 支持 (Next.js)

在 Next.js 等 SSR 框架中，需要在服务端配置静态渲染模式：

```tsx
// app/layout.tsx 或其他服务端入口文件
import { enableStaticRendering } from '@libeilong/react-reactive/static'

// 在服务端启用静态渲染
if (typeof window === 'undefined') {
  enableStaticRendering(true)
}
```

**重要**: SSR 配置必须从 `@libeilong/react-reactive/static` 导入，而不是主入口。主入口包含 `'use client'` 指令，无法在服务端使用。

## 高级功能

### Store 插件系统

通过 `@Provider` 装饰器，你可以为 Store 添加插件，在 Store 渲染时自动包裹 Provider 组件。这对于需要为 Store 提供上下文环境（如主题、国际化、状态管理等）的场景非常有用。

#### 基础示例

```tsx
import { Provider, useStore } from '@libeilong/react-reactive'
import { reactive } from '@vue/reactivity'
import { ThemeProvider } from 'some-theme-library'

// 定义一个插件：接收 store 实例，返回一个 Provider 组件
const themePlugin = (store: AppStore) => {
  return ({ children }) => (
    <ThemeProvider theme={store.theme}>
      {children}
    </ThemeProvider>
  )
}

// 使用 @Provider 装饰器应用插件
@Provider(themePlugin)
class AppStore {
  state = reactive({
    theme: 'dark',
    count: 0,
  })

  get theme() {
    return this.state.theme
  }
}

function App() {
  const store = useStore(AppStore)

  return store.observer(() => (
    <div>
      <p>Count: {store.state.count}</p>
      <button onClick={() => store.state.count++}>Increment</button>
    </div>
  ))
}
```

#### 多插件组合

`@Provider` 装饰器支持多个插件，插件的执行顺序为从左到右（外层到内层）：

```tsx
import { Provider, useStore } from '@libeilong/react-reactive'

const themePlugin = (store) => ({ children }) => (
  <ThemeProvider theme={store.theme}>{children}</ThemeProvider>
)

const i18nPlugin = (store) => ({ children }) => (
  <I18nProvider locale={store.locale}>{children}</I18nProvider>
)

const authPlugin = (store) => ({ children }) => (
  <AuthProvider user={store.user}>{children}</AuthProvider>
)

// 渲染结构：ThemeProvider > I18nProvider > AuthProvider > children
@Provider(themePlugin, i18nPlugin, authPlugin)
class AppStore {
  // ...
}
```

#### 插件类型定义

```tsx
import type { StorePlugin } from '@libeilong/react-reactive'

// 插件接收 store 实例，返回一个 React 组件
type StorePlugin<T = any> = (store: T) => React.FC<{ children: React.ReactNode }>
```

## API

### 客户端 API (从主入口导入)

```tsx
import { Observer, useObserver, useStore, Singleton, Provider } from '@libeilong/react-reactive'
import type { StorePlugin } from '@libeilong/react-reactive'
```

- `Observer`: 响应式组件包装器
- `useObserver`: 响应式 Hook
- `useStore`: Store Hook，返回的 store 实例包含 `provider` 和 `observer` 属性
- `Singleton`: 单例装饰器
- `Provider`: 插件装饰器，用于为 Store 添加 Provider 包装
- `StorePlugin`: 插件类型定义

推荐使用方式：

1. 根组件：`const store = useStore(StoreClass)` 后调用 `store.observer(() => ...)`
2. 子组件：`const store = useStore<Store>()` 后配合 `useObserver(() => ...)`
3. `useStore(StoreClass, ...args)` 中的构造参数仅在首次创建时生效；如果依赖变化需要同步，请在 Store 内部处理，而不是依赖参数变化重建实例

### 服务端 API (从 `/static` 导入)

```tsx
import { enableStaticRendering, isUsingStaticRendering } from '@libeilong/react-reactive/static'
```

- `enableStaticRendering(enable: boolean)`: 启用/禁用静态渲染模式
- `isUsingStaticRendering()`: 检查是否在静态渲染模式

## 特性

- ✅ 完整的响应式系统支持
- ✅ Store 插件系统，支持自动包裹 Provider
- ✅ SSR/SSG 支持
- ✅ React StrictMode 兼容
- ✅ React Concurrent 模式兼容
- ✅ 自动内存管理
- ✅ TypeScript 支持

## License

MIT