@gaozh1024/rn-kit 0.2.0-beta.0

package/README.md

@@ -0,0 +1,363 @@
+# @gaozh1024/rn-kit
+
+> Panther Expo Framework - All-in-one React Native framework
+
+一个集成的 React Native 开发框架，包含主题系统、UI 组件、API 工厂和导航组件。
+
+## ✅ 推荐初始化方式
+
+业务 App 推荐优先使用 `AppProvider`，而不是只手动包一层 `ThemeProvider`。
+
+`AppProvider` 默认会整合：
+
+- `SafeAreaProvider`
+- `ThemeProvider`
+- `NavigationProvider`
+- `OverlayProvider`
+- `AppStatusBar`
+
+这样页面切换、主题切换时，状态栏会自动跟随全局主题变化。
+
+## 📦 安装
+
+```bash
+npm install @gaozh1024/rn-kit
+# 或
+pnpm add @gaozh1024/rn-kit
+# 或
+yarn add @gaozh1024/rn-kit
+```
+
+### 前置依赖
+
+```bash
+npm install react react-native
+npm install react-native-screens react-native-safe-area-context
+npm install react-native-gesture-handler react-native-reanimated
+npm install react-native-svg
+```
+
+### ⚠️ 样式配置（必看）
+
+本框架使用 **Tailwind CSS** 类名实现样式（如 `bg-primary-500`, `flex-1`, `p-4`），需要在你的项目中配置 **NativeWind** 才能正常显示样式。
+
+如果你发现 `AppHeader`、`AppView`、`AppButton` 没有样式或布局错乱，通常不是框架内部渲染失败，而是消费方 app 没有把 NativeWind 和 Tailwind 扫描范围配置完整。
+
+```bash
+npm install nativewind
+npm install -D tailwindcss
+```
+
+创建 `tailwind.config.js`：
+
+```javascript
+module.exports = {
+  content: [
+    './App.{js,jsx,ts,tsx}',
+    './src/**/*.{js,jsx,ts,tsx}',
+    './node_modules/@gaozh1024/rn-kit/dist/**/*.{js,mjs}', // 必须包含框架路径
+  ],
+  safelist: [
+    { pattern: /^(flex)-(1|2|3|4|5|6|7|8|9|10|11|12)$/ },
+    { pattern: /^(items)-(start|center|end|stretch)$/ },
+    { pattern: /^(justify)-(start|center|end|between|around)$/ },
+    { pattern: /^(p|px|py|gap)-(0|1|2|3|4|5|6|8|10|12)$/ },
+    { pattern: /^(rounded)-(none|sm|md|lg|xl|2xl|full)$/ },
+    {
+      pattern: /^(bg|text)-(primary|secondary|success|warning|error|info|gray|white|black)(-.+)?$/,
+    },
+  ],
+  theme: { extend: {} },
+  plugins: [],
+};
+```
+
+修改 `babel.config.js`：
+
+```javascript
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: [['babel-preset-expo', { jsxImportSource: 'nativewind' }], 'nativewind/babel'],
+  };
+};
+```
+
+📖 [查看完整 Tailwind 配置指南](./TAILWIND_SETUP.md)
+
+## 🚀 快速开始
+
+```tsx
+import { AppProvider, AppView, AppText, AppButton, useToggle } from '@gaozh1024/rn-kit';
+
+function App() {
+  const [visible, { toggle }] = useToggle(false);
+
+  return (
+    <AppProvider>
+      <AppView flex p={4}>
+        <AppText size="xl">Hello Panther!</AppText>
+        <AppButton onPress={toggle}>{visible ? '隐藏' : '显示'}</AppButton>
+      </AppView>
+    </AppProvider>
+  );
+}
+```
+
+如果你只需要最小主题能力，也可以单独使用：
+
+```tsx
+import { ThemeProvider, createTheme } from '@gaozh1024/rn-kit';
+
+const theme = createTheme({
+  colors: {
+    primary: '#f38b32',
+  },
+});
+```
+
+## 📚 API 概览
+
+### 🎨 主题系统
+
+```tsx
+import { ThemeProvider, createTheme, useTheme } from '@gaozh1024/rn-kit';
+```
+
+### 🧱 应用初始化与状态栏
+
+```tsx
+import { AppProvider, AppStatusBar } from '@gaozh1024/rn-kit';
+```
+
+受控切换主题时，推荐直接给 `AppProvider` / `ThemeProvider` 传 `isDark`，不要再通过重建根组件强制刷新：
+
+```tsx
+<AppProvider lightTheme={lightTheme} darkTheme={darkTheme} isDark={themeMode === 'dark'}>
+  <RootNavigator />
+</AppProvider>
+```
+
+### 🧩 UI 组件
+
+```tsx
+import {
+  AppView,
+  AppScrollView,
+  AppText,
+  AppPressable,
+  AppInput, // 原子组件
+  Row,
+  Col,
+  Center, // 布局
+  AppButton, // 组合组件
+  Toast,
+  Alert,
+  Loading,
+  Progress, // 反馈
+  Card,
+  Icon,
+  AppImage,
+  AppList, // 数据展示
+  Checkbox,
+  Radio,
+  Switch,
+  Select,
+  DatePicker, // 表单
+} from '@gaozh1024/rn-kit';
+```
+
+### 🪝 Hooks
+
+```tsx
+import {
+  // UI Hooks
+  useToggle,
+  useDebounce,
+  useThrottle,
+  useKeyboard,
+  useDimensions,
+  useOrientation,
+  // Core Hooks
+  useAsyncState,
+  useRequest,
+  usePagination,
+  useRefresh,
+  useInfinite,
+  useStorage,
+} from '@gaozh1024/rn-kit';
+```
+
+### 🧭 导航
+
+```tsx
+import {
+  NavigationProvider,
+  StackNavigator,
+  TabNavigator,
+  BottomTabBar,
+  DrawerNavigator,
+  useNavigation,
+  useRoute,
+} from '@gaozh1024/rn-kit';
+```
+
+`TabNavigator` 在未显式传入 `tabBar` 时，会默认使用框架内置的 `BottomTabBar`（默认高度 `65`）。
+
+```tsx
+<TabNavigator
+  tabBarOptions={{
+    activeTintColor: '#f38b32',
+    inactiveTintColor: '#9ca3af',
+    height: 72,
+    style: { borderTopWidth: 0 },
+  }}
+>
+  {/* screens */}
+</TabNavigator>
+```
+
+如果你需要完全自定义底栏，也可以手动覆盖：
+
+```tsx
+<TabNavigator tabBar={props => <BottomTabBar {...props} height={72} />}>
+  {/* screens */}
+</TabNavigator>
+```
+
+### 🔌 API 工厂
+
+```tsx
+import { createAPI, z, storage, ErrorCode } from '@gaozh1024/rn-kit';
+
+const api = createAPI({
+  baseURL: 'https://api.example.com',
+  endpoints: {
+    getUser: {
+      method: 'GET',
+      path: '/users/:id',
+    },
+  },
+});
+```
+
+## 📄 文档
+
+- [框架文档](../../docs/README.md) - 完整文档索引
+
+## 📱 状态栏使用说明
+
+### 1. 全局默认行为
+
+推荐：
+
+```tsx
+import { AppProvider } from '@gaozh1024/rn-kit';
+
+export default function App() {
+  return (
+    <AppProvider>
+      <RootNavigator />
+    </AppProvider>
+  );
+}
+```
+
+此时框架会自动注入全局 `AppStatusBar`：
+
+- 亮色主题：`dark-content`
+- 暗色主题：`light-content`
+- Android 状态栏背景默认跟随当前主题背景色
+
+### 2. 页面级覆盖
+
+如果某个页面需要单独控制状态栏，可以在页面内显式渲染：
+
+```tsx
+import { AppStatusBar } from '@gaozh1024/rn-kit';
+
+<AppStatusBar barStyle="light-content" backgroundColor="#f38b32" />;
+```
+
+适合：
+
+- 登录页
+- 沉浸式详情页
+- 顶部大图/渐变背景页
+
+### 3. 登录页全屏背景示例
+
+如果登录页希望顶部状态栏区域也和页面背景保持一致，不要直接使用默认白底容器。
+
+推荐：
+
+```tsx
+import { AppStatusBar, SafeScreen, AppView } from '@gaozh1024/rn-kit';
+
+export function LoginScreen() {
+  return (
+    <>
+      <AppStatusBar barStyle="light-content" backgroundColor="#f38b32" translucent={false} />
+
+      <SafeScreen bg="primary-500">
+        <AppView flex className="bg-primary-500">
+          {/* page content */}
+        </AppView>
+      </SafeScreen>
+    </>
+  );
+}
+```
+
+### 4. 沉浸式状态栏示例
+
+```tsx
+import { AppStatusBar, SafeScreen, AppView } from '@gaozh1024/rn-kit';
+
+export function HeroScreen() {
+  return (
+    <>
+      <AppStatusBar barStyle="light-content" backgroundColor="transparent" translucent />
+
+      <SafeScreen top={false} bottom={false}>
+        <AppView flex className="bg-black">
+          {/* hero content */}
+        </AppView>
+      </SafeScreen>
+    </>
+  );
+}
+```
+
+### 5. 常见问题
+
+#### 为什么顶部还是白色？
+
+通常是以下原因之一：
+
+1. 当前页面没有单独覆盖 `AppStatusBar`
+2. 页面容器本身是白底
+3. 使用了 `Page` / `SafeScreen`，但没有设置 `bg`
+4. 顶部安全区没有和页面背景统一
+
+如果你用的是：
+
+```tsx
+<Page>
+```
+
+那它默认不适合登录页这类全屏品牌色场景。请改成：
+
+```tsx
+<Page bg="primary-500">
+```
+
+或者直接用：
+
+```tsx
+<SafeScreen bg="primary-500">
+```
+
+## 📄 许可证
+
+MIT

package/TAILWIND_SETUP.md

@@ -0,0 +1,307 @@
+# Tailwind CSS / NativeWind 配置指南
+
+> 本框架使用 Tailwind CSS 类名来实现样式，需要在你的项目中配置 NativeWind 才能正常使用。
+
+## 为什么需要这个配置？
+
+框架的 UI 组件（如 `AppView`, `AppText`, `AppButton` 等）使用 Tailwind CSS 类名（如 `bg-primary-500`, `flex-1`, `p-4`）来定义样式。
+
+这些类名需要 **NativeWind** 在构建时解析并转换为 React Native 的 StyleSheet。
+
+`AppHeader` 也是同样的机制。它的布局依赖 `AppView` 生成的 `flex-row`、`items-center`、`px-4` 等类名，所以如果 app 没把 NativeWind 和 Tailwind 配完整，`AppHeader` 会直接表现成“没有样式”。
+
+## 安装依赖
+
+```bash
+npm install nativewind
+npm install -D tailwindcss
+```
+
+## 配置文件
+
+### 1. 创建 Tailwind 配置文件
+
+在项目根目录创建 `tailwind.config.js`：
+
+```javascript
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    // 你的项目文件
+    './App.{js,jsx,ts,tsx}',
+    './src/**/*.{js,jsx,ts,tsx}',
+
+    // 使用发布包时，必须包含框架产物路径
+    './node_modules/@gaozh1024/rn-kit/dist/**/*.{js,mjs}',
+
+    // 如果你通过 workspace / file: / 本地源码接入框架，
+    // 还需要把实际源码路径加进来
+    // '../rn-monorepo/packages/framework/src/**/*.{ts,tsx}',
+  ],
+  safelist: [
+    { pattern: /^(flex)-(1|2|3|4|5|6|7|8|9|10|11|12)$/ },
+    { pattern: /^(items)-(start|center|end|stretch)$/ },
+    { pattern: /^(justify)-(start|center|end|between|around)$/ },
+    { pattern: /^(p|px|py|gap)-(0|1|2|3|4|5|6|8|10|12)$/ },
+    { pattern: /^(rounded)-(none|sm|md|lg|xl|2xl|full)$/ },
+    {
+      pattern: /^(bg|text)-(primary|secondary|success|warning|error|info|gray|white|black)(-.+)?$/,
+    },
+  ],
+  theme: {
+    extend: {
+      // 可以扩展或覆盖框架主题
+      colors: {
+        primary: {
+          DEFAULT: '#f38b32',
+          50: '#fff7ed',
+          100: '#ffedd5',
+          200: '#fed7aa',
+          300: '#fdba74',
+          400: '#fb923c',
+          500: '#f38b32',
+          600: '#ea580c',
+          700: '#c2410c',
+          800: '#9a3412',
+          900: '#7c2d12',
+          950: '#431407',
+        },
+        // ... 其他颜色
+      },
+    },
+  },
+  plugins: [],
+};
+```
+
+### 为什么还需要 `safelist`？
+
+因为框架部分组件会通过 props 动态生成类名，例如：
+
+```tsx
+<AppView px={4} items="center" bg="primary-500" rounded="lg" />
+```
+
+这类写法在运行时才会变成：
+
+- `px-4`
+- `items-center`
+- `bg-primary-500`
+- `rounded-lg`
+
+如果不通过 `safelist` 提前告诉 Tailwind，这些类名可能不会被生成，最终表现为：
+
+- 间距不生效
+- 背景色不生效
+- 圆角不生效
+- `AppHeader` 没有布局
+
+### 2. 配置 Babel
+
+修改 `babel.config.js`：
+
+```javascript
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: [['babel-preset-expo', { jsxImportSource: 'nativewind' }], 'nativewind/babel'],
+  };
+};
+```
+
+关键点：
+
+- `nativewind/babel` 在 NativeWind 4.x 里是 `preset`，不要放进 `plugins`
+- Expo 项目需要在 `babel-preset-expo` 上补 `jsxImportSource: 'nativewind'`
+- 对 Expo SDK 54 + Reanimated 4 场景，不需要再额外挂 `react-native-reanimated/plugin`
+
+错误示例：
+
+```javascript
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: ['babel-preset-expo'],
+    plugins: ['nativewind/babel'], // 错误：这里会触发 .plugins is not a valid Plugin property
+  };
+};
+```
+
+### 3. 配置 Metro（如果需要）
+
+对于某些 React Native 版本，可能需要配置 `metro.config.js`：
+
+```javascript
+const { getDefaultConfig } = require('metro-config');
+
+module.exports = (async () => {
+  const {
+    resolver: { sourceExts, assetExts },
+  } = await getDefaultConfig();
+
+  return {
+    transformer: {
+      babelTransformerPath: require.resolve('nativewind/src/css-interop/transformer'),
+    },
+    resolver: {
+      assetExts: assetExts.filter(ext => ext !== 'css'),
+      sourceExts: [...sourceExts, 'css'],
+    },
+  };
+})();
+```
+
+### 4. 创建 CSS 入口文件（推荐）
+
+创建 `global.css` 文件：
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+在应用入口导入（如 `App.tsx`）：
+
+```tsx
+import './global.css';
+// ... 其他导入
+```
+
+## 验证配置
+
+创建一个测试页面验证样式是否正常：
+
+```tsx
+import { AppView, AppText, AppButton } from '@gaozh1024/rn-kit';
+
+export function TestScreen() {
+  return (
+    <AppView flex center p={4} bg="gray-100">
+      <AppText size="xl" weight="bold" color="primary-500">
+        如果这行文字是橙色，说明配置成功！
+      </AppText>
+
+      <AppButton
+        className="mt-4 px-6 py-3 bg-primary-500 rounded-lg"
+        onPress={() => console.log('Clicked!')}
+      >
+        测试按钮
+      </AppButton>
+    </AppView>
+  );
+}
+```
+
+## 常见问题
+
+### Q: 样式不生效，组件显示默认样式？
+
+**检查清单**：
+
+1. ✅ `tailwind.config.js` 中的 `content` 是否包含框架路径？
+2. ✅ `babel.config.js` 是否按 NativeWind 4.x 写成 `presets` 配置？
+3. ✅ `tailwind.config.js` 是否添加了框架需要的 `safelist`？
+4. ✅ 是否重启了 Metro bundler？（修改配置后需要重启）
+5. ✅ 是否清除了缓存？（Expo 推荐 `npx expo start -c`，React Native CLI 可用 `npx react-native start --reset-cache`）
+6. ✅ `babel-preset-expo` 是否配置了 `jsxImportSource: 'nativewind'`？
+
+### Q: 为什么 `AppHeader` 也没有样式？
+
+`AppHeader` 不是纯 `StyleSheet` 组件，它依赖框架内部的：
+
+- `AppView row`
+- `items="center"`
+- `px={4}`
+
+这些最终都会走 NativeWind 的 `className` 管线。所以如果：
+
+- Babel 没加 `nativewind/babel`
+- `content` 没扫到框架文件
+- `safelist` 没覆盖动态类
+
+那么 `AppHeader` 会非常像“完全没有样式”。
+
+### Q: 这是框架 bug 吗？
+
+通常不是渲染 bug，而是消费方配置不完整。
+
+但要注意一点：框架当前确实使用了部分**动态 className** 生成方式，因此消费方 app 不能只配最基础的 NativeWind，还必须把 `safelist` 配上。
+
+另一个常见例外是本地链接包没有同步：
+
+- 如果你通过 `yalc`、`file:`、workspace 或本地源码方式接入框架，app 里跑的未必是最新构建产物
+- 框架源码虽然已经修复，但 app 里的 `.yalc` 或本地链接目录如果没更新，最终表现仍然会是“没有样式”
+
+推荐排查顺序：
+
+```bash
+# 在框架仓库
+pnpm --filter @gaozh1024/rn-kit build
+
+# 如果使用 yalc
+yalc publish
+
+# 在 app 仓库
+yalc update @gaozh1024/rn-kit
+npx expo start -c
+```
+
+### Q: `AppHeader` 没样式，但 `tailwind.config.js` 已经配了，为什么？
+
+优先检查 `babel.config.js` 有没有把 `nativewind/babel` 错写到 `plugins`，或者漏掉 `jsxImportSource: 'nativewind'`。
+
+这类错误会让 NativeWind 转换根本没有接通，表现通常是：
+
+- `AppHeader` 没有左右内边距
+- 标题不居中
+- `AppView` 的 `row`、`items="center"`、`px={4}` 像完全失效
+
+### Q: 如何自定义主题颜色？
+
+在 `tailwind.config.js` 中扩展主题：
+
+```javascript
+module.exports = {
+  content: [
+    /* ... */
+  ],
+  theme: {
+    extend: {
+      colors: {
+        // 覆盖框架默认主色
+        primary: {
+          500: '#1890ff', // 改为蓝色
+        },
+        // 添加自定义颜色
+        brand: {
+          500: '#ff6b6b',
+        },
+      },
+    },
+  },
+};
+```
+
+然后在组件中使用：
+
+```tsx
+<AppView bg="brand-500" /> // 使用自定义颜色
+```
+
+### Q: 与框架主题系统的关系？
+
+框架的 `ThemeProvider` 和 `createTheme` 提供**运行时主题数据**（如颜色值、间距值）。
+
+Tailwind CSS 提供**构建时样式类名**。
+
+两者配合工作：
+
+- Tailwind 类名决定样式结构（如 `flex`, `p-4`, `rounded-lg`）
+- 主题系统提供具体的颜色值（如 `primary-500` 对应的颜色）
+
+## 相关文档
+
+- [NativeWind 官方文档](https://www.nativewind.dev/)
+- [Tailwind CSS 文档](https://tailwindcss.com/docs)
+- [框架快速开始](../SETUP.md)