@gaozh1024/rn-kit 0.3.3 → 0.4.0

package/README.md

@@ -16,6 +16,13 @@
 - `OverlayProvider`
 - `AppStatusBar`
 
+另外在**开发环境**下，`AppProvider` 默认会启用一套轻量的开发日志基础设施：
+
+- `LoggerProvider`
+- CLI 彩色日志输出
+- App 内 `LogOverlay` 浮层
+- `AppErrorBoundary` React 渲染错误兜底
+
 这样页面切换、主题切换时，状态栏会自动跟随全局主题变化。
 
 ## 📦 安装
@@ -61,6 +68,7 @@ module.exports = {
   ],
   safelist: [
     { pattern: /^(flex)-(1|2|3|4|5|6|7|8|9|10|11|12)$/ },
+    'flex-wrap',
     { 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)$/ },
@@ -148,6 +156,7 @@ import {
   AppScrollView,
   AppText,
   AppPressable,
+  KeyboardDismissView,
   AppInput, // 原子组件
   Row,
   Col,
@@ -167,10 +176,85 @@ import {
   Radio,
   Switch,
   Select,
+  Picker,
   DatePicker, // 表单
 } from '@gaozh1024/rn-kit';
 ```
 
+#### 布局与容器约定
+
+- `AppView` / `Row` 支持 `wrap`，等价于 `flex-wrap`
+- `Card` 支持常用间距快捷属性：`p` / `px` / `py` / `gap`
+- `SafeScreen` / `AppScreen` 同时支持：
+  - `bg="primary-500"` 这类显式颜色
+  - `surface="background" | "card" | "muted"` 这类语义背景
+  - `dismissKeyboardOnPressOutside`：点击非输入区域时收起键盘
+- `AppScrollView` 支持 `dismissKeyboardOnPressOutside`
+  - 开启后会自动启用点击空白收起键盘
+  - 并默认补上 `keyboardShouldPersistTaps="handled"`
+- `KeyboardDismissView` 适合非页面容器、自定义布局场景下单独包裹使用
+
+#### Button 颜色语义
+
+`AppButton` 目前支持以下 `color`：
+
+- `primary`
+- `secondary`
+- `success`
+- `warning`
+- `info`
+- `error`
+- `danger`（`error` 的兼容别名）
+- `muted`
+
+```tsx
+<AppButton color="success">保存成功</AppButton>
+<AppButton color="warning" variant="outline">
+  继续操作
+</AppButton>
+<AppButton color="danger">删除</AppButton>
+```
+
+#### 键盘收起交互
+
+`AppButton` 新增：
+
+- `dismissKeyboardOnPress?: boolean`
+- 默认值：`true`
+
+也就是说，大多数提交/保存/登录按钮在点击前会先自动收起键盘：
+
+```tsx
+<AppButton onPress={handleSubmit}>提交</AppButton>
+
+<AppButton dismissKeyboardOnPress={false} onPress={handleToolbarAction}>
+  保持键盘
+</AppButton>
+```
+
+容器侧推荐这样使用：
+
+```tsx
+<AppScreen dismissKeyboardOnPressOutside>
+  <AppScrollView dismissKeyboardOnPressOutside>
+    <AppInput placeholder="请输入手机号" />
+    <AppInput placeholder="请输入密码" secureTextEntry />
+    <AppButton onPress={handleLogin}>登录</AppButton>
+  </AppScrollView>
+</AppScreen>
+```
+
+如果不是整页容器，而是局部自定义布局，也可以单独使用：
+
+```tsx
+<KeyboardDismissView>
+  <AppView p={4} gap={3}>
+    <AppInput placeholder="搜索内容" />
+    <AppButton onPress={handleSearch}>搜索</AppButton>
+  </AppView>
+</KeyboardDismissView>
+```
+
 #### 可本地化文案参数（i18n 推荐）
 
 - `AppList`
@@ -183,13 +267,189 @@ import {
   - `emptyText`：空状态文案
   - `selectedCountText`：多选计数模板，支持 `{{count}}`
   - `confirmText`：多选确认按钮文案
+- `Picker`
+  - `pickerTitle` / `cancelText` / `confirmText`：弹窗文案
+  - `renderDisplayText`：自定义触发区展示文本
+  - `renderFooter`：自定义底部区域，适合扩展省市区、级联选择等场景
 - `DatePicker`
   - `cancelText` / `confirmText`：弹窗操作按钮文案
   - `pickerTitle`：弹窗标题文案
-  - `pickerDateFormat`：弹窗顶部日期格式
   - `yearLabel` / `monthLabel` / `dayLabel`：列标题文案
   - `todayText` / `minDateText` / `maxDateText`：快捷按钮文案
 
+#### 表单与反馈 Hook 当前 API
+
+```tsx
+import { useForm, useToast, useLoading, useAlert, useLogger } from '@gaozh1024/rn-kit';
+
+const form = useForm({
+  schema,
+  defaultValues: { name: '' },
+});
+
+form.values;
+form.errors;
+form.setValue('name', 'Panther');
+await form.validate();
+await form.validateField('name');
+await form.handleSubmit(async values => {
+  console.log(values);
+});
+
+const toast = useToast();
+toast.show('已保存', 'success', 2000);
+toast.success('成功');
+
+const loading = useLoading();
+loading.show('加载中...');
+loading.hide();
+
+const alert = useAlert();
+alert.alert({ title: '提示', message: '操作完成' });
+alert.confirm({ title: '确认删除', message: '删除后不可恢复' });
+
+const logger = useLogger('auth');
+logger.info('开始登录', { page: 'Login' });
+logger.error('登录失败', { code: 401 });
+```
+
+说明：
+
+- `useForm` 使用 `defaultValues`，不是 `initialValues`
+- `useForm` 提供 `setValue` / `handleSubmit`，不是 `setFieldValue` / `submit`
+- `useToast` 当前签名为 `show(message, type?, duration?)`
+- `useLoading` 当前签名为 `show(text?)` / `hide()`
+- `useAlert` 当前提供 `alert()` / `confirm()`，不包含 `prompt()` / `custom()`
+- `useLogger(namespace?)` 提供 `debug / info / warn / error / clear / entries`
+
+#### 开发日志 / 可观测性基础设施
+
+框架现在内置了一套**开发态可观测性基础设施**，目标是帮助排查问题，而不是直接做线上监控平台。
+
+默认能力：
+
+- `useLogger(namespace?)`：组件内打点
+- 内存日志缓冲：保留最近若干条日志
+- Console Transport：CLI 中按 level 彩色输出
+- `LogOverlay`：App 内浮动日志面板
+- 浮层增强：level 筛选 / namespace 筛选 / 关键字搜索 / 导出当前日志
+
+##### 1. 最简单用法：直接跟随 `AppProvider`
+
+```tsx
+import { AppProvider, useLogger, AppButton } from '@gaozh1024/rn-kit';
+
+function LoginButton() {
+  const logger = useLogger('login');
+
+  return (
+    <AppButton
+      onPress={() => {
+        logger.info('点击登录按钮');
+      }}
+    >
+      登录
+    </AppButton>
+  );
+}
+
+export default function App() {
+  return (
+    <AppProvider>
+      <LoginButton />
+    </AppProvider>
+  );
+}
+```
+
+说明：
+
+- `AppProvider` 在开发环境下默认 `enableLogger = true`
+- 生产环境默认关闭
+- 开启后会同时启用 console 输出和 App 内日志浮层
+
+##### 2. 显式控制是否启用
+
+```tsx
+<AppProvider
+  enableLogger
+  enableErrorBoundary
+  loggerProps={{
+    level: 'info',
+    maxEntries: 300,
+    consoleEnabled: true,
+    defaultExpanded: false,
+  }}
+>
+  <App />
+</AppProvider>
+```
+
+常用 `loggerProps`：
+
+- `enabled`
+- `level`: `'debug' | 'info' | 'warn' | 'error'`
+- `maxEntries`
+- `consoleEnabled`
+- `overlayEnabled`
+- `defaultExpanded`
+- `exportEnabled`
+- `onExport`
+
+`onExport` 会收到：
+
+```tsx
+{
+  entries: LogEntry[];
+  serialized: string;
+}
+```
+
+错误边界相关：
+
+- `enableErrorBoundary`：是否启用 React 错误边界
+- `errorBoundaryProps.title`：兜底标题
+- `errorBoundaryProps.description`：兜底说明
+- `errorBoundaryProps.showDetails`：是否显示错误详情
+- `errorBoundaryProps.resetText`：重试按钮文案
+
+当错误边界与 logger 同时开启时，组件渲染异常会自动写入 `react` 命名空间日志，便于在控制台和 `LogOverlay` 中回看。
+
+##### 3. 单独使用 `OverlayProvider` / `LoggerProvider`
+
+如果你不是通过 `AppProvider` 接入，而是自己手动包 Provider，需要注意：
+
+- `LoggerProvider` 默认 `enabled = false`
+- `OverlayProvider` 里传入的 logger 也默认不主动开启
+
+所以需要显式打开：
+
+```tsx
+import { OverlayProvider } from '@gaozh1024/rn-kit';
+
+<OverlayProvider
+  loggerProps={{
+    enabled: true,
+    overlayEnabled: true,
+    consoleEnabled: true,
+  }}
+>
+  <App />
+</OverlayProvider>;
+```
+
+或者：
+
+```tsx
+import { AppErrorBoundary, LoggerProvider } from '@gaozh1024/rn-kit';
+
+<LoggerProvider enabled overlayEnabled consoleEnabled>
+  <AppErrorBoundary enabled showDetails>
+    <App />
+  </AppErrorBoundary>
+</LoggerProvider>;
+```
+
 ### 🪝 Hooks
 
 ```tsx
@@ -317,6 +577,14 @@ import { GradientView, AppText } from '@gaozh1024/rn-kit';
 </GradientView>;
 ```
 
+TypeScript 下如果你把颜色数组先提到变量里，建议写成 tuple：
+
+```tsx
+const heroColors = ['#f38b32', '#fb923c'] as const;
+
+<GradientView colors={heroColors} />;
+```
+
 如果你的应用是手动集成 `@gaozh1024/rn-kit`，请同时安装：
 
 ```bash
@@ -359,7 +627,7 @@ import { DrawerContent, DrawerNavigator } from '@gaozh1024/rn-kit';
 ### 🔌 API 工厂
 
 ```tsx
-import { createAPI, z, storage, ErrorCode } from '@gaozh1024/rn-kit';
+import { createAPI, createApiLoggerTransport, z, storage, ErrorCode } from '@gaozh1024/rn-kit';
 
 const api = createAPI({
   baseURL: 'https://api.example.com',
@@ -372,6 +640,85 @@ const api = createAPI({
 });
 ```
 
+#### API 自动打点（request / response / error）
+
+`createAPI` 已支持开发态自动打点。
+
+默认行为：
+
+- 开发环境下 `observability.enabled` 默认开启
+- 如果当前 App 已通过 `AppProvider` / `LoggerProvider` 启用了 logger
+- 那么 API 请求会自动写入 `api` 命名空间日志
+
+记录阶段：
+
+- request
+- response
+- error
+
+```tsx
+const api = createAPI({
+  baseURL: 'https://api.example.com',
+  observability: {
+    enabled: true,
+    includeInput: true,
+    includeResponseData: false,
+  },
+  endpoints: {
+    getProfile: {
+      method: 'GET',
+      path: '/profile',
+    },
+  },
+});
+```
+
+也可以添加自定义 transport：
+
+```tsx
+const api = createAPI({
+  baseURL: 'https://api.example.com',
+  observability: {
+    enabled: true,
+    transports: [
+      event => {
+        console.log('api event', event.stage, event.endpointName);
+      },
+    ],
+  },
+  endpoints: {
+    getProfile: {
+      method: 'GET',
+      path: '/profile',
+    },
+  },
+});
+```
+
+如果你想手动指定写到某个 logger，也可以：
+
+```tsx
+const transport = createApiLoggerTransport({
+  namespace: 'network',
+  includeInput: true,
+  includeResponseData: true,
+});
+
+const api = createAPI({
+  baseURL: 'https://api.example.com',
+  observability: {
+    enabled: true,
+    transports: [transport],
+  },
+  endpoints: {
+    getProfile: {
+      method: 'GET',
+      path: '/profile',
+    },
+  },
+});
+```
+
 ## 📄 文档
 
 - [框架文档](../../docs/README.md) - 完整文档索引
@@ -398,16 +745,31 @@ export default function App() {
 
 - 亮色主题：`dark-content`
 - 暗色主题：`light-content`
+- 默认 `translucent={false}`
 - Android 状态栏背景默认跟随当前主题背景色
 
-### 2. 页面级覆盖
+### 2. 使用 `AppHeader` 时的默认行为
+
+如果页面使用了 `AppHeader`，通常不需要再单独处理状态栏：
+
+- `AppHeader` 内部会自动注入 `AppFocusedStatusBar`
+- 配置为 `translucent + backgroundColor="transparent"`
+- 顶部状态栏区域会直接显示 Header 自身背景色
+
+适合：
+
+- 普通详情页
+- 设置页
+- 使用有色 Header 的二级页面
+
+### 3. 页面级覆盖
 
 如果某个页面需要单独控制状态栏，可以在页面内显式渲染：
 
 ```tsx
-import { AppStatusBar } from '@gaozh1024/rn-kit';
+import { AppFocusedStatusBar } from '@gaozh1024/rn-kit';
 
-<AppStatusBar barStyle="light-content" backgroundColor="#f38b32" />;
+<AppFocusedStatusBar barStyle="light-content" backgroundColor="transparent" translucent />;
 ```
 
 适合：
@@ -416,19 +778,21 @@ import { AppStatusBar } from '@gaozh1024/rn-kit';
 - 沉浸式详情页
 - 顶部大图/渐变背景页
 
-### 3. 登录页全屏背景示例
+对于导航页面，优先使用 `AppFocusedStatusBar`，这样只有当前聚焦页面会覆盖状态栏配置。
+
+### 4. 登录页全屏背景示例
 
 如果登录页希望顶部状态栏区域也和页面背景保持一致，不要直接使用默认白底容器。
 
 推荐：
 
 ```tsx
-import { AppStatusBar, SafeScreen, AppView } from '@gaozh1024/rn-kit';
+import { AppFocusedStatusBar, SafeScreen, AppView } from '@gaozh1024/rn-kit';
 
 export function LoginScreen() {
   return (
     <>
-      <AppStatusBar barStyle="light-content" backgroundColor="#f38b32" translucent={false} />
+      <AppFocusedStatusBar barStyle="light-content" backgroundColor="transparent" translucent />
 
       <SafeScreen bg="primary-500">
         <AppView flex className="bg-primary-500">
@@ -440,15 +804,15 @@ export function LoginScreen() {
 }
 ```
 
-### 4. 沉浸式状态栏示例
+### 5. 沉浸式状态栏示例
 
 ```tsx
-import { AppStatusBar, SafeScreen, AppView } from '@gaozh1024/rn-kit';
+import { AppFocusedStatusBar, SafeScreen, AppView } from '@gaozh1024/rn-kit';
 
 export function HeroScreen() {
   return (
     <>
-      <AppStatusBar barStyle="light-content" backgroundColor="transparent" translucent />
+      <AppFocusedStatusBar barStyle="light-content" backgroundColor="transparent" translucent />
 
       <SafeScreen top={false} bottom={false}>
         <AppView flex className="bg-black">
@@ -460,13 +824,13 @@ export function HeroScreen() {
 }
 ```
 
-### 5. 常见问题
+### 6. 常见问题
 
 #### 为什么顶部还是白色？
 
 通常是以下原因之一：
 
-1. 当前页面没有单独覆盖 `AppStatusBar`
+1. 当前页面没有使用 `AppHeader`，也没有单独覆盖 `AppFocusedStatusBar` / `AppStatusBar`
 2. 页面容器本身是白底
 3. 使用了 `AppScreen` / `SafeScreen`，但没有设置 `bg`
 4. 顶部安全区没有和页面背景统一

package/TAILWIND_SETUP.md

@@ -40,6 +40,7 @@ module.exports = {
   ],
   safelist: [
     { pattern: /^(flex)-(1|2|3|4|5|6|7|8|9|10|11|12)$/ },
+    'flex-wrap',
     { 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)$/ },