@lmy54321/design-system 1.1.2 → 1.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lmy54321/design-system",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "A comprehensive React component library and design system based on Tailwind CSS and Motion.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -29,8 +29,8 @@
     "test": "vitest"
   },
   "peerDependencies": {
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
+    "react": "^18.3.1 || ^19.0.0",
+    "react-dom": "^18.3.1 || ^19.0.0",
     "tailwindcss": "^4.2.1"
   },
   "dependencies": {

package/rules/design-system.mdc

@@ -41,6 +41,15 @@ provider:
 | `TopToolbar` | 顶部导航栏 |
 | `BottomNavigationBar` | 底部标签栏 |
 
+#### BottomNavigationBar 类型定义
+
+`BottomNavigationBar` 的 Tab ID 使用 `TabId` 类型，需从组件路径导入：
+```tsx
+import { BottomNavigationBar } from '@lmy54321/design-system'
+// TabId 类型为字面量联合: "home" | "explore" | "plan" | "me"
+type TabId = "home" | "explore" | "plan" | "me";
+```
+
 ### 容器组件
 | 组件 | 用途 |
 |------|------|
@@ -287,6 +296,77 @@ import { Dialog, Toast, Btn, SearchBox, IconFont, cn } from '@lmy54321/design-sy
 | 拖拽 | ✅ 手势切换 | ❌ 禁用 |
 | 遮罩 | LARGE时60%黑色遮罩 | 无需遮罩 |
 
+### BottomNavigationBar 与 DraggablePanel 层级关系（重要）
+
+**BottomNavigationBar 必须在 DraggablePanel 之上**，使用 z-index 层级差来实现。以下是正确的 z-index 层级表：
+
+| 元素 | z-index | 说明 |
+|------|---------|------|
+| Toast | `z-[2000]` | 最顶层，轻提示 |
+| **BottomNavigationBar** | **`z-[1001]`** | 底部导航栏，**必须在面板之上** |
+| DraggablePanel TopToolbar | `z-[1000]` | 面板内置顶部工具栏 |
+| **DraggablePanel** | **`z-[999]`** | 可拖拽面板主体 |
+| 地图控件 | `z-40` | 地图浮层按钮 |
+
+**BottomNavigationBar 的正确用法：**
+
+```tsx
+{/* BottomNavigationBar 必须用 absolute 定位 + z-[1001] 压盖在 DraggablePanel 上方 */}
+{panelState !== DRAWER_STATES.FULL && (
+  <div className="absolute bottom-[12px] left-1/2 -translate-x-1/2 z-[1001]">
+    <BottomNavigationBar activeTab={activeTab} onTabChange={onTabChange} />
+  </div>
+)}
+
+{/* DraggablePanel 的 z-index 是 z-[999]，低于 BottomNavigationBar */}
+<DraggablePanel
+  state={panelState}
+  onStateChange={setPanelState}
+  customSmallHeight={260}
+  bottomOffset={8}
+>
+  {/* 页卡内容 */}
+</DraggablePanel>
+```
+
+**关键规则：**
+1. `BottomNavigationBar` **不能**放在 `DraggablePanel` 内部，必须作为**同级兄弟元素**
+2. `BottomNavigationBar` 外层容器**必须**设置 `z-[1001]`（高于面板的 `z-[999]`）
+3. 当面板进入 `DRAWER_STATES.FULL` 全屏状态时，**必须隐藏** `BottomNavigationBar`
+4. `BottomNavigationBar` 使用 `absolute bottom-[12px] left-1/2 -translate-x-1/2` 定位在屏幕底部居中
+5. `DraggablePanel` 设置 `bottomOffset={8}` 保持面板底部与屏幕底部的间距
+
+**完整的页面骨架结构：**
+
+```tsx
+<div className="relative w-full h-[100dvh] overflow-hidden bg-background">
+  {/* 底图 */}
+  <TencentMap className="absolute inset-0" />
+
+  {/* 地图控件 z-40 */}
+  {/* ... */}
+
+  {/* BottomNavigationBar — z-[1001]，在面板上方 */}
+  {panelState !== DRAWER_STATES.FULL && (
+    <div className="absolute bottom-[12px] left-1/2 -translate-x-1/2 z-[1001]">
+      <BottomNavigationBar activeTab={activeTab} onTabChange={onTabChange} />
+    </div>
+  )}
+
+  {/* DraggablePanel — z-[999]，在导航栏下方 */}
+  <DraggablePanel
+    state={panelState}
+    onStateChange={setPanelState}
+    customSmallHeight={260}
+    bottomOffset={8}
+  >
+    {/* 页卡内容 */}
+  </DraggablePanel>
+
+  {/* Toast — z-[2000]，最顶层 */}
+</div>
+```
+
 ### 严禁行为
 
 1. **禁止**在需要底图联动的页面直接使用全屏页卡遮盖底图
@@ -295,6 +375,7 @@ import { Dialog, Toast, Btn, SearchBox, IconFont, cn } from '@lmy54321/design-sy
 4. **禁止**使用渐变背景 `div` 模拟地图底图，必须使用 `TencentMap` 组件
 5. **禁止**将底部操作栏（`BottomActionButtons`/`BottomToolbar`/底部按钮组）放在 `DraggablePanel` 的 `children` 内部，必须通过 `bottomBar` prop 传入以保持吸底
 6. **禁止**在 `DraggablePanel` 的 `children` 内部对 `flex-1` 子项省略 `min-h-0`，否则 `bottomBar` 将被内容推出可视区域
+7. **禁止**将 `BottomNavigationBar` 放在 `DraggablePanel` 内部或使用低于 `z-[1001]` 的层级，否则会被面板遮盖
 
 ## 瀑布流布局规范