miaoda-expo-devkit 0.1.1-beta.5 → 0.1.1-beta.51

package/README.md

@@ -7,6 +7,10 @@ Expo / React Native 开发环境工具集，通过 Metro 构建层注入以下
 - **Bundle 首部注入** — 在 expo-router 初始化之前执行自定义脚本
 - **HMR postMessage 控制** — 通过 `window.postMessage` 在运行时启动或停止 Fast Refresh
 - **LogBox 屏蔽** — web 平台禁用 Expo 全屏错误遮罩
+- **expo-notifications stub** — Expo Go（Android）中提供 no-op 实现，核心 API 调用时弹出带参数校验的调试 Alert，Dev Build 透传真实模块
+- **expo-media-library stub** — Expo Go / Web 中提供 no-op 实现，`saveToLibraryAsync`、`createAssetAsync`、权限请求等 API 调用时弹出 Alert 提示，Dev Build 原生环境透传真实模块
+- **expo-calendar stub** — Expo Go / Web 中提供 no-op 实现，`getEventsAsync`、`createEventAsync`、`getCalendarsAsync`、权限请求等核心 API 调用时弹出 Alert 提示并校验参数，Dev Build 原生环境透传真实模块
+- **expo-image-picker stub** — 桌面 Web 中 `launchCameraAsync` 通过 `getUserMedia` 打开摄像头预览弹窗（浏览器原生 `capture` 属性在 PC 端被忽略），移动端浏览器透传 expo 原实现，Native 不受影响
 
 ## 安装
 
@@ -32,16 +36,16 @@ pnpm install
 ```js
 // metro.config.js
 const { getDefaultConfig } = require('expo/metro-config');
-const { withDevStubs, withEntryInjection } = require('miaoda-expo-devkit/metro');
+const { withDevkit } = require('miaoda-expo-devkit/metro');
 
-const config = getDefaultConfig(__dirname);
-module.exports = withEntryInjection(withDevStubs(config));
+module.exports = withDevkit(getDefaultConfig(__dirname));
 ```
 
-支持与其他 Metro wrapper 链式组合：
+`withDevkit` 已内置所有 wrapper（含 expo-notifications、expo-media-library、expo-calendar stub），无需手动叠加。也可单独使用各 wrapper：
 
 ```js
-module.exports = withNativeWind(withEntryInjection(withDevStubs(config)), { input: './global.css' });
+const { withDevStubs, withEntryInjection, withExpoMediaLibraryStub, withExpoCalendarStub } = require('miaoda-expo-devkit/metro');
+module.exports = withExpoCalendarStub(withExpoMediaLibraryStub(withEntryInjection(withDevStubs(config))));
 ```
 
 ### Sentry 初始化
@@ -225,12 +229,35 @@ expect(onError).toHaveBeenCalledWith(
 
 ```
 metro.config.js
-  └─ withEntryInjection(withDevStubs(config))
+  └─ withDevkit(config)
        │
        ├─ withDevStubs → resolver.resolveRequest
        │    ├─ @sentry/react-native        →  dist/stubs/sentry-react-native-stub.js  （全平台）
        │    └─ @expo/log-box               →  dist/stubs/no-op-logbox.js              （仅 web）
        │
+       ├─ withExpoNotificationsStub → resolver.resolveRequest
+       │    └─ expo-notifications          →  dist/stubs/expo-notifications-stub.js   （仅 Android）
+       │         ├─ Expo Go：no-op + 调试 Alert（含参数校验）
+       │         └─ Dev Build：透传真实 expo-notifications
+       │
+       ├─ withExpoMediaLibraryStub → resolver.resolveRequest
+       │    └─ expo-media-library          →  dist/stubs/expo-media-library-stub.js   （全平台）
+       │         ├─ Expo Go / Web：no-op + Alert 提示（不崩溃）
+       │         └─ Dev Build（原生）：透传真实 expo-media-library
+       │
+       ├─ withExpoCalendarStub → resolver.resolveRequest
+       │    └─ expo-calendar              →  dist/stubs/expo-calendar-stub.js          （全平台）
+       │         ├─ Expo Go / Web：no-op + Alert 提示 + 参数校验（不崩溃）
+       │         └─ Dev Build（原生）：透传真实 expo-calendar
+       │
+       ├─ withExpoImagePickerStub → resolver.resolveRequest
+       │    └─ expo-image-picker          →  dist/stubs/expo-image-picker-stub.js      （仅 web）
+       │         ├─ 桌面 Web：launchCameraAsync → getUserMedia + #__devkit_camera_overlay__ 弹窗
+       │         │    ├─ 点"拍照"：canvas.toDataURL → ImagePickerResult { canceled:false, assets }
+       │         │    └─ 点"取消"：返回 { canceled:true, assets:null }
+       │         ├─ 移动端浏览器：透传 expo 原实现（capture 属性正常工作）
+       │         └─ getUserMedia 不可用：降级透传 expo 原实现（不崩溃）
+       │
        └─ withEntryInjection → resolver.resolveRequest
             └─ expo-router/entry-classic   →  dist/stubs/expo-router-entry-stub.js
                  ├─ require('./entry-inject')           ← 注入脚本（bundle 首部执行）
@@ -262,10 +289,15 @@ sentry-react-native-stub.js
 | 子路径 | 文件 | 内容 |
 |---|---|---|
 | `.` | `dist/index.js` | `SentryCapture`、`MetroSymbolicator`、全部类型 |
-| `./metro` | `dist/metro.js` | `withDevStubs`、`withEntryInjection` |
+| `./metro` | `dist/metro.js` | `withDevkit`、`withDevStubs`、`withEntryInjection`、`withExpoNotificationsStub`、`withExpoMediaLibraryStub`、`withExpoCalendarStub` 等 |
 | `./babel-plugin-jsx-source` | `dist/babel/plugin-jsx-source.js` | Babel 插件：为 JSX 注入 source 信息 |
+| `./babel-preset` | `dist/babel/preset.js` | Babel Preset：集成 jsx-source 和 lucide 插件 |
 | `./sentry-react-native-stub` | `dist/stubs/sentry-react-native-stub.js` | `@sentry/react-native` 模块替换 stub |
 | `./no-op-logbox` | `dist/stubs/no-op-logbox.js` | LogBox no-op stub |
+| `./expo-notifications-stub` | `dist/stubs/expo-notifications-stub.js` | `expo-notifications` Expo Go Android stub |
+| `./expo-media-library-stub` | `dist/stubs/expo-media-library-stub.js` | `expo-media-library` Expo Go / Web stub |
+| `./expo-calendar-stub` | `dist/stubs/expo-calendar-stub.js` | `expo-calendar` Expo Go / Web stub |
+| `./expo-image-picker-stub` | `dist/stubs/expo-image-picker-stub.js` | `expo-image-picker` 桌面 Web stub |
 
 ---
 
@@ -388,6 +420,145 @@ LogBox no-op stub，用于 web 平台禁用 Expo 全屏错误遮罩。
 
 ---
 
+### expo-notifications-stub.js
+
+`expo-notifications` 模块替换 stub，由 `withExpoNotificationsStub()` 在 Metro 层注入（**仅 Android 平台**）。
+
+**背景：** Expo SDK 53 起，`expo-notifications` 的 Android native module 已从 Expo Go 中移除，直接 import 会在 Expo Go 启动时崩溃。
+
+**运行时行为：**
+- **Expo Go（Android）**：提供 no-op 实现，`requestPermissionsAsync`、`setNotificationChannelAsync`、`scheduleNotificationAsync` 等核心 API 调用时弹出带参数校验的调试 Alert
+- **Development Build（Android）**：透传真实 `expo-notifications`，功能完全正常
+- **iOS（任意）**：不经过此 stub，直接使用真实 `expo-notifications`
+
+**手动验证：** 在 `devkit-e2e` App 中扫码进入「Notification Stub 验证」页面，逐按钮触发并对照期望结果。
+
+---
+
+### expo-media-library-stub.js
+
+`expo-media-library` 模块替换 stub，由 `withExpoMediaLibraryStub()` 在 Metro 层注入（**全平台**）。
+
+**背景：** `expo-media-library` 依赖原生相册 API，在 Expo Go 和 Web 环境中不可用，调用 `saveToLibraryAsync` 等 API 会直接崩溃。
+
+**运行时行为：**
+- **Expo Go / Web**：提供 no-op 实现，以下 API 调用时弹出 Alert 提示（不崩溃）：
+  - `usePermissions()` — 返回 `{ status: 'undetermined', granted: false }`，`requestPermission()` 弹 Alert
+  - `requestPermissionsAsync()` / `getPermissionsAsync()` — 前者弹 Alert，后者静默返回 denied
+  - `saveToLibraryAsync(uri)` — 弹 Alert 显示操作和 URI（超 60 字符自动截断）
+  - `createAssetAsync(uri)` — 弹 Alert 并返回合法的伪资产对象
+  - 其他未知 API — Proxy 兜底，静默返回 `undefined`；以 `PermissionsAsync` 结尾的 API 返回 denied 结构
+- **Development Build（原生）**：透传真实 `expo-media-library`，功能完全正常
+
+**Alert 消息格式：**
+```
+保存到相册
+Expo Go 扫码预览不支持访问手机相册
+操作: 图片: file:///tmp/test.jpg
+发布为正式 App 后可正常使用
+```
+
+**手动验证：** 在 `devkit-e2e` App 中扫码进入「Media Library Stub 验证」页面，逐按钮触发并对照期望结果。
+
+---
+
+### expo-calendar-stub.js
+
+`expo-calendar` 模块替换 stub，由 `withExpoCalendarStub()` 在 Metro 层注入（**全平台**）。
+
+**背景：** `expo-calendar` 依赖原生系统日历 API，在 Expo Go 和 Web 环境中不可用，调用 `getEventsAsync` 等 API 会直接崩溃。
+
+**运行时行为：**
+- **Expo Go / Web**：提供 no-op 实现，以下 API 调用时弹出 Alert / Dialog 提示（不崩溃）：
+  - `useCalendarPermissions()` / `useRemindersPermissions()` — 初始返回 `undetermined`，`requestPermission()` 弹 Alert
+  - `requestCalendarPermissionsAsync()` / `requestRemindersPermissionsAsync()` — 弹 Alert 提示，返回 denied
+  - `getCalendarPermissionsAsync()` / `getRemindersPermissionsAsync()` — 静默返回 denied
+  - `getCalendarsAsync(entityType?)` — 弹 Alert 显示查询类型，返回空数组
+  - `createCalendarAsync(details)` — 弹 Alert 含名称和颜色，校验 `details.title` 非空
+  - `updateCalendarAsync(id, details)` / `deleteCalendarAsync(id)` — 弹 Alert 含日历 ID，校验 ID 格式
+  - `getEventsAsync(calendarIds, startDate, endDate)` — 弹 Alert 含时间范围，校验 calendarIds 非空及日期合法性，返回空数组
+  - `createEventAsync(calendarId, eventData)` — 弹 Alert 含标题和时间，Android 下校验 startDate/endDate
+  - `updateEventAsync(id, details)` / `deleteEventAsync(id)` — 弹 Alert 含事件 ID，校验 ID 格式
+  - 其他未知 API — Proxy 兜底，静默返回 `undefined`；以 `PermissionsAsync` 结尾的 API 返回 denied 结构
+- **Development Build（原生）**：透传真实 `expo-calendar`，功能完全正常
+
+**枚举常量**（stub & Dev Build 均可用）：
+`EntityTypes`、`Frequency`、`Availability`、`CalendarType`、`EventStatus`、`SourceType`、
+`AttendeeRole`、`AttendeeStatus`、`AttendeeType`、`AlarmMethod`、`EventAccessLevel`、
+`CalendarAccessLevel`、`ReminderStatus`、`DayOfTheWeek`、`MonthOfTheYear`
+
+**Alert 消息格式（合规示例）：**
+```
+创建日历事件
+秒哒扫码预览不支持访问手机日历
+
+日历 ID: cal1
+标题: 团队会议
+开始: 2025/1/1 10:00:00
+结束: 2025/1/1 11:00:00
+
+✅ 参数合规
+发布为正式 App 后可正常使用
+```
+
+**手动验证：** 在 `devkit-e2e` App 中扫码进入「Calendar Stub 验证」页面，逐按钮触发并对照期望结果。
+
+---
+
+---
+
+### expo-image-picker-stub.js
+
+`expo-image-picker` 模块替换 stub，由 `withExpoImagePickerStub()` 在 Metro 层注入（**仅 web 平台**）。
+
+**背景：** `expo-image-picker` 的 `launchCameraAsync` 在 web 上底层使用 `<input type="file" capture="environment">`。桌面浏览器（Chrome、Firefox、Safari）**有意忽略 `capture` 属性**，直接弹出文件选择框而不是摄像头。这是浏览器厂商的硬限制，无法通过任何 HTML 属性或 meta 标签绕过。
+
+**运行时行为：**
+- **桌面 Web（非 mobile UA）**：`launchCameraAsync` 调用 `navigator.mediaDevices.getUserMedia` 打开摄像头预览弹窗（`#__devkit_camera_overlay__`），用户点击"📷 拍照"后截取一帧并以 `data:image/jpeg` 格式返回，点击"取消"返回 `{ canceled: true }`
+- **移动端浏览器（Android Chrome / iOS Safari）**：透传 expo 原实现，`capture` 属性在移动端正常调起系统相机
+- **`getUserMedia` 不可用**（无摄像头或浏览器限制）：静默降级，透传 expo 原实现（不崩溃）
+- **Native（iOS / Android）**：Metro resolver 不拦截，直接使用原生 `expo-image-picker`，功能完全不变
+
+**弹窗 DOM 结构（供 Playwright 定位）：**
+```html
+<div id="__devkit_camera_overlay__">   <!-- 全屏遮罩 -->
+  <div>                                <!-- 面板 -->
+    <p>拍照</p>
+    <video autoplay muted playsinline> <!-- 摄像头预览 -->
+    <div>
+      <button>📷 拍照</button>
+      <button>取消</button>
+    </div>
+    <p><!-- 错误信息（getUserMedia 失败时显示） --></p>
+  </div>
+</div>
+```
+
+**返回值格式（与 expo 原实现兼容）：**
+```ts
+// 拍照成功
+{
+  canceled: false,
+  assets: [{
+    uri: 'data:image/jpeg;base64,...',
+    width: 640,
+    height: 480,
+    type: 'image',
+    fileName: 'photo_1234567890.jpg',
+    mimeType: 'image/jpeg',
+    base64: null,
+    exif: null,
+  }]
+}
+
+// 取消
+{ canceled: true, assets: null }
+```
+
+**E2E 测试：** `devkit-e2e/tests/e2e/image-picker-stub.spec.ts`，使用 `addInitScript` mock `getUserMedia`（注入 canvas stream 替代真实摄像头），覆盖弹窗出现/消失、拍照返回结果、取消、降级等场景。
+
+---
+
 ## Babel 插件：jsx-source
 
 `babel-plugin-jsx-source` 为 JSX 元素注入 source 属性（文件路径、行列号），用于开发调试。通过 `dataSet` 对象注入，这是 React Web 可识别的数据通道。
@@ -434,3 +605,81 @@ module.exports = {
 |---|---|---|---|
 | `rootDir` | `string` | - | 项目根目录，用于计算相对路径。不提供则使用绝对路径 |
 | `excludePaths` | `string[]` | `[]` | 跳过注入的路径模式列表（相对于 rootDir 的路径片段） |
+
+---
+
+## Babel 插件：lucide-react-native
+
+Metro 没有 tree-shaking，直接写 `import { Star } from "lucide-react-native"` 会把整个图标库（约 1500 个图标）打进 bundle。`babel-plugin-lucide-react-native` 在编译阶段将具名导入改写为直接按文件导入，彻底规避这个问题。
+
+**转换效果：**
+
+```ts
+// 转换前
+import { Star, BookOpen } from "lucide-react-native";
+
+// 转换后（CJS，默认）
+import _Star     from "lucide-react-native/dist/cjs/icons/star";
+import _BookOpen from "lucide-react-native/dist/cjs/icons/book-open";
+```
+
+### 配置
+
+推荐通过内置 Preset 一次性启用所有 Babel 插件：
+
+```js
+// babel.config.js
+module.exports = {
+  presets: [['miaoda-expo-devkit/babel-preset', { excludePaths: ['src/components/ui'] }]],
+};
+```
+
+也可以单独使用：
+
+```js
+module.exports = {
+  plugins: [['miaoda-expo-devkit/babel-plugin-lucide-react-native']],
+};
+```
+
+### 选项
+
+| 选项 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `useES` | `boolean` | `false` | 使用 ESM 格式（`dist/esm/icons/`）而非默认的 CJS |
+
+### 支持的写法
+
+插件可识别所有常见的图标引用写法：
+
+```ts
+import { BookOpen, Star, Crown } from "lucide-react-native";
+
+// JSX 直接使用
+<BookOpen size={24} />
+
+// 赋值给变量
+const icon = BookOpen;
+
+// 对象 value
+const ITEMS = [{ icon: BookOpen }, { icon: Star }];
+
+// 计算属性 key
+const map = { [BookOpen]: 'read' };
+
+// 数组、三元、函数参数
+const list = [BookOpen, Star];
+const active = flag ? BookOpen : Star;
+renderIcon(Crown);
+
+// 导入别名
+import { BookOpen as ReadIcon } from "lucide-react-native";
+<ReadIcon />
+
+// re-export
+export { Star, BookOpen as ReadIcon } from "lucide-react-native";
+```
+
+### 版本兼容性
+
+插件在运行时探测 `lucide-react-native` 的实际目录结构，自动适配新旧版本的路径差异（`>= 1.9` 新增 `icons/` 子目录；旧版 `1.8.x` 图标直接位于 `dist/cjs/`），lucide 升级时无需修改配置。

package/biome-config.json

@@ -1,4 +1,15 @@
 {
+	"vcs": {
+		"enabled": true,
+		"clientKind": "git",
+		"useIgnoreFile": true
+	},
+	"files": {
+		"includes": [
+			"src/**/*.{js,jsx,ts,tsx,css,scss}",
+			"tailwind.config.js"
+		]
+	},
 	"linter": {
 		"enabled": true,
 		"rules": {
@@ -10,5 +21,17 @@
 	},
 	"formatter": {
 		"enabled": false
-	}
+	},
+	"overrides": [
+		{
+			"includes": ["tailwind.config.js"],
+			"linter": {
+				"rules": {
+					"style": {
+						"noCommonJs": "off"
+					}
+				}
+			}
+		}
+	]
 }

package/dist/babel/plugin-jsx-source.d.ts

@@ -14,8 +14,10 @@ import { types, PluginObj } from '@babel/core';
  *
  * 对于纯文本节点：
  *   <div>hello world</div>
+ *   <div>{"hello world"}</div>
  * 转换后：
  *   <div dataSet={{"mdId": "path/to/file.tsx:10:4", "componentContent": "{\"text\":\"hello world\"}"}}>hello world</div>
+ *   <div dataSet={{"mdId": "path/to/file.tsx:11:4", "componentContent": "{\"text\":\"hello world\"}"}}>{"hello world"}</div>
  *
  * 用法（babel.config.js）：
  *

package/dist/babel/plugin-jsx-source.js

@@ -69,9 +69,18 @@ function getTextNodeContent(t, path) {
   const children = parent.children;
   if (children.length !== 1) return null;
   const child = children[0];
-  if (!t.isJSXText(child)) return null;
-  const text = child.value.trim();
-  return text || null;
+  if (t.isJSXText(child)) {
+    const text = child.value.trim();
+    return text || null;
+  }
+  if (t.isJSXExpressionContainer(child) && t.isStringLiteral(child.expression)) {
+    const text = child.expression.value.trim();
+    return text || null;
+  }
+  if (t.isJSXExpressionContainer(child) && t.isNumericLiteral(child.expression)) {
+    return String(child.expression.value);
+  }
+  return null;
 }
 function shouldSkipElement(t, name) {
   if (t.isJSXIdentifier(name)) {

package/dist/babel/plugin-lucide-react-native.d.ts

@@ -0,0 +1,31 @@
+import babelCore from '@babel/core';
+
+/**
+ * babel-plugin-lucide-react-native
+ *
+ * 将 lucide-react-native 的具名导入转换为按图标文件直接导入，绕过 Metro
+ * 缺乏 tree-shaking 的问题，避免将整个图标库打进 bundle。
+ *
+ * 转换示意：
+ *   import { Star, BookHeart } from "lucide-react-native"
+ *   →
+ *   import _Star     from "lucide-react-native/dist/cjs/icons/star"
+ *   import _BookHeart from "lucide-react-native/dist/cjs/icons/book-heart"
+ */
+
+type Core = typeof babelCore;
+interface Config extends babelCore.PluginPass {
+    opts: {
+        /** 使用 ESM 格式（dist/esm）。默认 false，使用 CJS（dist/cjs）。 */
+        useES?: boolean;
+        /**
+         * lucide-react-native 包根目录的绝对路径（含 package.json 的那一层）。
+         * 不传时通过 require.resolve 自动定位，适用于生产场景。
+         * 测试时可传入特定版本的路径，验证不同版本的兼容性。
+         */
+        lucidePkgRoot?: string;
+    };
+}
+declare function lucideReactNativePlugin({ types: t }: Core): babelCore.PluginObj<Config>;
+
+export { lucideReactNativePlugin as default };