@beppla/tapas-ui 1.5.10 → 1.5.12

package/package/module/Input/README.md

@@ -0,0 +1,157 @@
+# TapasInput 组件
+
+基于 `@rneui/themed` 的 Input 组件封装，提供了额外的功能和样式定制。
+
+## 功能特性
+
+- ✅ 自定义标签位置和样式
+- ✅ 支持必填标识
+- ✅ **RN 0.77 Bridgeless 模式兼容性修复**（Android 平台）
+
+## RN 0.77 Bridgeless 模式兼容性
+
+### 问题说明
+
+React Native 0.77 引入的 Bridgeless 模式在 Android 平台上可能导致输入框在点击后键盘弹出但立即失焦的问题。这是 RN 0.77 的已知问题。
+
+### 组件库修复
+
+`TapasInput` 组件已经内置了针对 Bridgeless 模式的兼容性修复：
+
+- **自动检测 Bridgeless 模式**：组件会自动检测是否运行在 Bridgeless 模式下
+- **延迟 blur 处理**：在 Android 上延迟处理 blur 事件，给键盘足够时间显示
+- **自动重新聚焦**：当键盘显示时，如果输入框失焦，会自动尝试重新聚焦
+- **智能延迟时间**：Bridgeless 模式下使用更长的延迟时间（800ms）来适应新架构
+
+### 使用方式
+
+默认情况下，兼容性修复是**自动启用**的：
+
+```tsx
+import { TapasInput } from '@beppla/tapas-ui';
+
+<TapasInput
+  label="用户名"
+  placeholder="请输入用户名"
+  // enableBridgelessFix={true} // 默认启用，无需手动设置
+/>
+```
+
+如果遇到问题，可以尝试禁用修复：
+
+```tsx
+<TapasInput
+  label="用户名"
+  enableBridgelessFix={false} // 禁用 Bridgeless 修复
+/>
+```
+
+### 应用端配置建议
+
+虽然组件库已经提供了修复，但应用端也可以进行一些配置来进一步优化体验：
+
+#### 1. AndroidManifest.xml 配置
+
+在 `android/app/src/main/AndroidManifest.xml` 中，确保 `windowSoftInputMode` 设置为 `adjustResize`：
+
+```xml
+<activity
+  android:name=".MainActivity"
+  android:windowSoftInputMode="adjustResize"
+  ...>
+</activity>
+```
+
+#### 2. ScrollView 配置
+
+如果输入框在 ScrollView 中，确保添加 `keyboardShouldPersistTaps`：
+
+```tsx
+<ScrollView
+  keyboardShouldPersistTaps="handled"
+  keyboardDismissMode="none"
+>
+  <TapasInput ... />
+</ScrollView>
+```
+
+#### 3. Layout 组件
+
+如果使用 `Layout` 组件，它已经自动配置了 `keyboardShouldPersistTaps`。
+
+## API
+
+### TapasInputProps
+
+继承自 `@rneui/themed` 的 `InputProps`，并添加了以下属性：
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `labelPosition` | `"top" \| "middle"` | `"top"` | 标签位置 |
+| `defaultShowLabel` | `boolean` | `false` | 是否默认显示标签 |
+| `labelBg` | `string` | - | 标签背景色 |
+| `labelColor` | `string` | - | 标签文字颜色 |
+| `required` | `boolean` | `false` | 是否必填（显示 * 标识） |
+| `enableBridgelessFix` | `boolean` | `true` | 是否启用 RN 0.77 Bridgeless 模式兼容性修复 |
+
+## 示例
+
+### 基础用法
+
+```tsx
+<TapasInput
+  label="用户名"
+  placeholder="请输入用户名"
+  value={username}
+  onChangeText={setUsername}
+/>
+```
+
+### 必填字段
+
+```tsx
+<TapasInput
+  label="邮箱"
+  placeholder="请输入邮箱"
+  required
+  value={email}
+  onChangeText={setEmail}
+/>
+```
+
+### 自定义标签样式
+
+```tsx
+<TapasInput
+  label="密码"
+  labelBg="#ffffff"
+  labelColor="#333333"
+  secureTextEntry
+  value={password}
+  onChangeText={setPassword}
+/>
+```
+
+### 禁用 Bridgeless 修复
+
+```tsx
+<TapasInput
+  label="备注"
+  enableBridgelessFix={false}
+  value={notes}
+  onChangeText={setNotes}
+/>
+```
+
+## 注意事项
+
+1. **Bridgeless 模式检测**：组件会自动检测是否运行在 Bridgeless 模式下，无需手动配置
+2. **性能影响**：兼容性修复会添加一些延迟和监听器，但对性能影响很小
+3. **向后兼容**：修复不会影响非 Bridgeless 模式或 iOS 平台的正常使用
+4. **问题反馈**：如果遇到问题，可以尝试禁用 `enableBridgelessFix` 或联系组件库维护者
+
+## 相关链接
+
+- [React Native 0.77 发布说明](https://reactnative.dev/blog)
+- [Bridgeless 模式文档](https://reactnative.dev/docs/the-new-architecture/landing-page)
+

package/package/module/Layout/README.md

@@ -0,0 +1,174 @@
+# Layout
+
+应用程序主框架布局组件，整合导航栏、页眉和内容区域，并内置 Toast 和 Drawer 上下文管理。
+
+## 功能特性
+
+- 自动响应式布局（移动端导航隐藏，桌面端导航常驻左侧）
+- 集成 Navigation 导航栏组件（可选显示、可自定义替换）
+- 集成 Header 页眉组件（可自定义替换）
+- 内置 ToastProvider 和 DrawerProvider 上下文
+- 内容区域自动 ScrollView 滚动
+- 移动端通过 Header 菜单按钮控制导航栏显示/隐藏
+- 桌面端导航栏占据左侧 56px，内容区自动偏移
+
+## 安装使用
+
+```tsx
+import Layout from '@beppla/tapas-ui/components/Layout';
+// 或
+import { Layout } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| children | `React.ReactNode` | - | 布局主体内容 |
+| headerProps | `HeaderProps` | - | Header 组件的 Props |
+| headerComponent | `React.ReactNode` | - | 自定义 Header 组件（替换默认 Header） |
+| navigationProps | `NavigationProps` | - | Navigation 组件的 Props |
+| navigationComponent | `React.ReactNode` | - | 自定义 Navigation 组件（替换默认导航） |
+| showNavigation | `boolean` | `true` | 是否显示导航栏 |
+| testID | `string` | - | 测试 ID |
+
+## 上下文 API
+
+### DrawerContext
+
+通过 `DrawerContext` 可在 Layout 内部任意组件中控制 Drawer 的开关。
+
+```tsx
+import { useContext } from 'react';
+import { DrawerContext } from '@beppla/tapas-ui/components/Layout/DrawerContext';
+
+const { open, close, drawerInfo, setDrawerInfo } = useContext(DrawerContext);
+
+// 打开 Drawer
+open({
+  title: 'Filter',
+  component: <FilterForm />,
+  showFooter: true,
+  rightButtonText: 'Apply',
+  rightButtonOnPress: () => handleApply(),
+});
+
+// 关闭 Drawer
+close();
+```
+
+### ToastContext
+
+通过 `ToastContext` 可在 Layout 内部任意组件中显示 Toast 消息。
+
+```tsx
+import { useContext } from 'react';
+import { ToastContext } from '@beppla/tapas-ui/components/Layout/ToastContext';
+
+const { open, close } = useContext(ToastContext);
+
+// 显示 Toast
+open({ message: 'Operation succeeded', visible: true });
+
+// 关闭 Toast
+close();
+```
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+import Layout from '@beppla/tapas-ui/components/Layout';
+import { Text } from 'react-native';
+
+const navItems = [
+  { name: 'Product', iconName: 'product_items' },
+  { name: 'About', iconName: 'manufacturing' },
+];
+
+export default function App() {
+  return (
+    <Layout
+      navigationProps={{
+        navItems,
+        logoImg: require('./logo.png'),
+      }}
+      headerProps={{
+        title: 'Welcome',
+        avatarSource: 'https://example.com/avatar.jpg',
+      }}
+    >
+      <Text>Main content goes here</Text>
+    </Layout>
+  );
+}
+```
+
+### 带导航切换的完整示例
+
+```tsx
+import Layout, { NavItem } from '@beppla/tapas-ui/components/Layout';
+import { useState } from 'react';
+import { Text } from 'react-native';
+
+const navItems: NavItem[] = [
+  { name: 'Home', iconName: 'home' },
+  { name: 'Products', iconName: 'product_items' },
+];
+
+const systemItems: NavItem[] = [
+  { name: 'Settings', iconName: 'settings' },
+];
+
+export default function App() {
+  const [selected, setSelected] = useState('Home');
+
+  return (
+    <Layout
+      navigationProps={{
+        navItems,
+        systemItems,
+        logoImg: require('./logo.png'),
+        onItemPress: (item) => setSelected(item.name),
+      }}
+      headerProps={{ title: selected }}
+    >
+      <Text>{selected} Page Content</Text>
+    </Layout>
+  );
+}
+```
+
+### 自定义 Header 组件
+
+```tsx
+<Layout
+  navigationProps={{ navItems, logoImg: require('./logo.png') }}
+  headerComponent={
+    <View style={{ height: 72, justifyContent: 'center', paddingHorizontal: 16 }}>
+      <Text style={{ fontSize: 20 }}>Custom Header</Text>
+    </View>
+  }
+>
+  <Text>Content</Text>
+</Layout>
+```
+
+### 隐藏导航栏
+
+```tsx
+<Layout showNavigation={false} headerProps={{ title: 'No Navigation' }}>
+  <Text>Full width content</Text>
+</Layout>
+```
+
+## 注意事项
+
+- Layout 的 index.tsx 导出版本自动包裹 ToastProvider 和 DrawerProvider，无需手动包裹
+- 移动端导航栏默认隐藏，通过 Header 左侧菜单按钮切换显示/隐藏
+- 桌面端导航栏常驻左侧（宽度 56px），内容区自动左偏移 56px
+- 自定义 `headerComponent` 会完全替代默认 Header，包括菜单按钮
+- 自定义 `navigationComponent` 会完全替代默认 Navigation
+- 内容区域使用 ScrollView 包裹，设置了 `keyboardShouldPersistTaps="handled"`
+- Toast 在桌面端显示在右上角，移动端显示在顶部

package/package/module/LineChart/README.md

@@ -0,0 +1,181 @@
+# LineChart
+
+折线图组件，支持单系列/多系列数据、多种曲线类型、自定义图例和 Tooltip。采用**双平台渲染**策略：Web 端使用 recharts，Native 端使用 react-native-svg-charts。
+
+## 功能特性
+
+- ✅ **双平台渲染**：Web 使用 recharts（功能完整），Native 使用 react-native-svg-charts（基础功能）
+- ✅ 支持单系列和多系列数据
+- ✅ 多种曲线类型：monotone / linear / step / natural / basis
+- ✅ 可显示/隐藏数据点（showDots）
+- ✅ 可独立控制 X 轴和 Y 轴的显示/隐藏
+- ✅ 图例支持 top / bottom / left / right 四个位置
+- ✅ 自定义图例图标类型：circle / rect / square / line
+- ✅ 自定义图例图标尺寸和文本样式
+- ✅ 自定义 Tooltip：完全自定义渲染（customTooltip）或数据格式化（tooltipFormatter）
+- ✅ 数据点点击事件回调（onLineClick）
+- ✅ Y 轴 / X 轴格式化函数
+- ✅ 响应式容器（Web 端 ResponsiveContainer）
+
+## 安装使用
+
+```tsx
+import { LineChart } from '@beppla/tapas-ui/components/LineChart';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| data | `LineChartDataPoint[] \| LineChartSeriesData[]` | (必填) | 数据源 |
+| width | `number` | - | 图表宽度 |
+| height | `number` | `300` | 图表高度 |
+| color | `string` | `'#0066CC'` | 单系列线条颜色 |
+| colors | `string[]` | - | 多系列颜色方案 |
+| showGrid | `boolean` | `true` | 是否显示网格线 |
+| showLabels | `boolean` | `true` | 是否显示标签 |
+| showXAxis | `boolean` | `true` | 是否显示 X 轴 |
+| showYAxis | `boolean` | `true` | 是否显示 Y 轴 |
+| showLegend | `boolean` | `true` | 是否显示图例 |
+| legendPosition | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | 图例位置 |
+| legendIconType | `'circle' \| 'rect' \| 'square' \| 'line'` | `'rect'` | 图例图标类型 |
+| legendIconSize | `{ width: number; height: number }` | `{ width: 18, height: 8 }` | 图例图标尺寸 |
+| legendTextStyle | `{ fontFamily?: string; fontSize?: number; fontWeight?: string \| number; letterSpacing?: number }` | Bricolage Grotesque 10px | 图例文本样式 |
+| curveType | `'monotone' \| 'linear' \| 'step' \| 'natural' \| 'basis'` | `'monotone'` | 曲线类型 |
+| showDots | `boolean` | `true` | 是否显示数据点 |
+| showArea | `boolean` | - | 是否显示面积填充 |
+| customTooltip | `(data: TooltipData) => ReactElement \| null` | - | 自定义 Tooltip 渲染函数 |
+| tooltipFormatter | `(data: TooltipData) => { title?: string; items?: Array<{ label: string; value: string \| number }> }` | - | Tooltip 数据格式化函数 |
+| contentInset | `{ top?: number; bottom?: number; left?: number; right?: number }` | `{ top: 20, bottom: 20, left: 20, right: 20 }` | 内容边距 |
+| yAxisFormat | `(value: number) => string` | - | Y 轴格式化 |
+| xAxisFormat | `(value: number, index: number) => string` | - | X 轴格式化 |
+| onLineClick | `(seriesLabel: string, dataPoint: LineChartDataPoint, dataIndex: number) => void` | - | 数据点点击回调 |
+| style | `any` | - | 容器样式 |
+| testID | `string` | - | 测试标识 |
+
+### LineChartDataPoint
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| value | `number` | 数值（必填） |
+| label | `string` | 标签 |
+
+### LineChartSeriesData
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| data | `LineChartDataPoint[]` | 数据点数组（必填） |
+| color | `string` | 线条颜色 |
+| label | `string` | 系列标签（显示在图例中） |
+
+### TooltipData
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| label | `string` | 当前数据点标签 |
+| value | `number` | 当前数据点值 |
+| dataIndex | `number` | 数据索引 |
+| seriesLabel | `string` | 系列标签 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<LineChart
+  data={[
+    { value: 50, label: 'Jan' },
+    { value: 75, label: 'Feb' },
+    { value: 65, label: 'Mar' },
+    { value: 90, label: 'Apr' },
+  ]}
+  height={300}
+  color="#0066CC"
+/>
+```
+
+### 多系列数据
+
+```tsx
+<LineChart
+  data={[
+    {
+      label: 'Product A',
+      color: '#00BFA5',
+      data: [
+        { value: 120, label: 'Mon' },
+        { value: 150, label: 'Tue' },
+        { value: 110, label: 'Wed' },
+      ],
+    },
+    {
+      label: 'Product B',
+      color: '#FF6B00',
+      data: [
+        { value: 100, label: 'Mon' },
+        { value: 110, label: 'Tue' },
+        { value: 90, label: 'Wed' },
+      ],
+    },
+  ]}
+  showLegend
+  legendPosition="top"
+  height={400}
+/>
+```
+
+### 极简设计图风格
+
+```tsx
+<LineChart
+  data={multiSeriesData}
+  curveType="linear"
+  showDots={false}
+  showYAxis={false}
+  showLegend
+  legendPosition="top"
+  legendIconType="rect"
+  legendIconSize={{ width: 18, height: 8 }}
+  legendTextStyle={{
+    fontFamily: 'Bricolage Grotesque, sans-serif',
+    fontSize: 10,
+    fontWeight: 400,
+    letterSpacing: 0.1,
+  }}
+/>
+```
+
+### 自定义 Tooltip
+
+```tsx
+<LineChart
+  data={storeData}
+  tooltipFormatter={(data) => ({
+    title: data.label,
+    items: [
+      { label: 'Stores', value: data.value },
+      { label: 'Revenue', value: `$${revenue[data.dataIndex]}` },
+    ],
+  })}
+/>
+```
+
+### 数据点点击事件
+
+```tsx
+<LineChart
+  data={sampleData}
+  onLineClick={(seriesLabel, dataPoint, dataIndex) => {
+    console.log(`${seriesLabel}: ${dataPoint.label} = ${dataPoint.value}`);
+  }}
+/>
+```
+
+## 注意事项
+
+- **双平台渲染**：Web 端使用 recharts（功能完整），Native 端使用 react-native-svg-charts（功能受限）
+- Native 端多系列数据**仅渲染第一个系列**
+- Native 端不支持自定义 Tooltip、图例自定义、曲线类型选择
+- 图例仅在多系列数据时显示
+- `customTooltip` 和 `tooltipFormatter` 仅 Web 端有效（鼠标悬停触发）
+- 需安装对应平台依赖：Web 需要 `recharts`，Native 需要 `react-native-svg-charts` + `react-native-svg`

package/package/module/ListItem/README.md

@@ -0,0 +1,122 @@
+# ListItem
+
+列表项组件，基于 @rneui/themed ListItem 封装，支持选中状态、搜索高亮、描述文本、数量角标等功能，适合构建可交互的选择列表。
+
+## 功能特性
+
+- ✅ 选中状态指示（背景色变化 + 勾选图标）
+- ✅ 搜索关键字高亮显示（name 和 desc 同时高亮）
+- ✅ 支持主标题和描述文本
+- ✅ 数量角标（number 属性，圆形背景主题色）
+- ✅ 鼠标悬停效果（Web 端 Hoverable）
+- ✅ 禁用状态，颜色置灰且不可点击
+- ✅ 首末项圆角支持（isFirst / isLast，12px 圆角）
+- ✅ 高度自定义样式：容器、标题、描述、搜索高亮
+- ✅ 文本自适应宽度，自动单行截断
+
+## 安装使用
+
+```tsx
+import ListItem from '@beppla/tapas-ui/components/ListItem/ListItem';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| item | `ItemProps` | (必填) | 列表项数据 |
+| selected | `ItemProps` | (必填) | 当前选中项（通过 value 比较） |
+| key | `number \| string` | (必填) | 唯一标识 |
+| onItemPress | `(item: ItemProps) => void` | (必填) | 点击回调 |
+| disabled | `boolean` | - | 是否禁用 |
+| isFirst | `boolean` | - | 是否为第一项（添加顶部圆角） |
+| isLast | `boolean` | - | 是否为最后一项（添加底部圆角） |
+| search | `string` | - | 搜索关键字，匹配部分高亮 |
+| containerStyle | `StyleProp<ViewStyle>` | - | 外层容器样式 |
+| itemContainerStyle | `StyleProp<ViewStyle>` | - | 项容器样式 |
+| titleContainerStyle | `StyleProp<ViewStyle>` | - | 标题容器样式 |
+| searchHighlightStyle | `StyleProp<TextStyle>` | - | 搜索高亮文本样式 |
+| titleStyle | `StyleProp<TextStyle>` | - | 标题文本样式 |
+| descStyle | `StyleProp<TextStyle>` | - | 描述文本样式 |
+| testID | `string` | - | 测试标识 |
+
+### ItemProps 接口
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| name | `string` | 显示名称（必填） |
+| value | `string \| number` | 值（必填），用于比较选中状态 |
+| id | `string \| number` | 唯一标识 |
+| hide | `boolean` | 是否隐藏 |
+| desc | `string` | 描述文本 |
+| number | `number` | 数量角标 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+const data = [
+  { name: 'Apple', value: 'apple' },
+  { name: 'Banana', value: 'banana' },
+  { name: 'Cherry', value: 'cherry' },
+];
+
+const [selected, setSelected] = useState(data[0]);
+
+{data.map((item, index) => (
+  <ListItem
+    key={index}
+    item={item}
+    selected={selected}
+    onItemPress={(value) => setSelected(value)}
+    isFirst={index === 0}
+    isLast={index === data.length - 1}
+  />
+))}
+```
+
+### 带描述和搜索高亮
+
+```tsx
+<ListItem
+  key={0}
+  item={{ name: 'John', value: 'john', desc: 'Manager' }}
+  selected={selected}
+  onItemPress={setSelected}
+  search="jo"
+  searchHighlightStyle={{ color: 'red' }}
+/>
+```
+
+### 带数量角标
+
+```tsx
+<ListItem
+  key={0}
+  item={{ name: 'Orders', value: 'orders', number: 5 }}
+  selected={selected}
+  onItemPress={setSelected}
+/>
+```
+
+### 禁用状态
+
+```tsx
+<ListItem
+  key={0}
+  item={{ name: 'Unavailable', value: 'unavailable' }}
+  selected={selected}
+  onItemPress={setSelected}
+  disabled
+/>
+```
+
+## 注意事项
+
+- 选中状态通过比较 `selected.value === item.value` 判断
+- 当 `item.number` 存在时显示数量角标（白字主题色背景），否则选中时显示勾选图标
+- 禁用状态下点击不会触发 `onItemPress`
+- `isFirst` / `isLast` 用于列表首末项圆角（12px），需手动传入
+- 搜索高亮使用正则分割文本，大小写不敏感，同时作用于 name 和 desc 字段
+- 列表项固定高度 48px