@beppla/tapas-ui 1.5.10 → 1.5.11

package/package/module/Button/README.md

@@ -0,0 +1,108 @@
+# Button / ButtonGroup
+
+Button 是基于 React Native Elements 的增强按钮组件，提供多种类型、hover 效果和自定义样式。ButtonGroup 是按钮组组件，将多个操作按钮组合展示。
+
+## 功能特性
+
+- ✅ 支持三种按钮类型：solid（实心）、outline（描边）、clear（透明）
+- ✅ Web 端自动 hover 效果，hover 时不产生尺寸变化
+- ✅ 可自定义按钮宽度和样式
+- ✅ 支持禁用状态
+- ✅ 继承 React Native Elements ButtonProps 的全部能力（图标、loading 等）
+- ✅ hover 样式与用户自定义样式可叠加，用户样式优先
+- ✅ ButtonGroup 支持图标 + 文字组合
+- ✅ ButtonGroup 支持单个按钮禁用
+- ✅ ButtonGroup 内置选中状态管理
+- ✅ ButtonGroup 自动处理首尾圆角和中间分隔线
+
+## 安装使用
+
+```tsx
+import { Button } from '@beppla/tapas-ui';
+import ButtonGroup from '@beppla/tapas-ui/components/Button/ButtonGroup';
+```
+
+## Props
+
+### Button Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| hoverStyle | `any` | - | 鼠标悬停时的自定义样式 |
+| buttonStyle | `any` | - | 按钮自定义样式 |
+| titleStyle | `any` | - | 标题文字样式 |
+| selectedTitleStyle | `any` | - | 选中/hover 时的标题样式 |
+| width | `number` | - | 按钮宽度 |
+| type | `'solid' \| 'outline' \| 'clear'` | - | 按钮类型（继承自 ButtonProps） |
+| disabled | `boolean` | - | 是否禁用（继承自 ButtonProps） |
+| onPress | `() => void` | - | 点击回调（继承自 ButtonProps） |
+| title | `string` | - | 按钮文字（继承自 ButtonProps） |
+
+### ButtonGroup Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| buttons | `ButtonType[]` | - | 按钮配置数组 |
+| hoveredStyle | `StyleProp<ViewStyle>` | `{}` | hover 时的自定义样式 |
+| selectedStyle | `StyleProp<ViewStyle>` | `{}` | 选中时的自定义样式 |
+
+### ButtonType
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| icon | `string` | - | 图标名称 |
+| title | `string` | - | 按钮文字 |
+| disabled | `boolean` | - | 是否禁用 |
+| onPress | `(index: number) => void` | - | 点击回调，参数为按钮索引 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<Button title="Hello" type="solid" width={120} onPress={() => {}} />
+```
+
+### 三种按钮类型
+
+```tsx
+<Button title="Solid Button" type="solid" />
+<Button title="Outline Button" type="outline" />
+<Button title="Clear Button" type="clear" />
+```
+
+### 禁用状态
+
+```tsx
+<Button title="Disabled" type="solid" disabled={true} />
+```
+
+### 自定义样式
+
+```tsx
+<Button
+  title="Custom"
+  buttonStyle={{ backgroundColor: '#FF6B6B', borderRadius: 25 }}
+  titleStyle={{ color: 'white', fontWeight: 'bold' }}
+/>
+```
+
+### 按钮组
+
+```tsx
+<ButtonGroup
+  buttons={[
+    { title: '下载模板', icon: 'download', onPress: (index) => console.log(index) },
+    { title: '编辑', icon: 'edit', onPress: (index) => console.log(index) },
+    { title: '上传', icon: 'upload', disabled: true },
+  ]}
+/>
+```
+
+## 注意事项
+
+- Button 的 hover 效果仅在 Web 平台生效，原生平台不渲染 Hoverable 包装
+- `type="clear"` 类型的按钮不会应用 hover 效果
+- hover 样式合并优先级：`primaryStyle < hoveredStyle < buttonStyle < hoverStyle`
+- ButtonGroup 使用 `memo` 优化渲染性能
+- ButtonGroup 中禁用的按钮不可点击，也不会触发 hover 效果

package/package/module/Calendar/README.md

@@ -0,0 +1,410 @@
+# Calendar
+
+日历与时间选择器组件族，提供完整的日期时间选择能力。包含 Calendar（日历）、TimeSelector（时间段选择器）、ConcreteTimeSelector（精确时间选择器）、CustomRange（自定义日期范围）、DaySelector（日期选择器）、WeekDaySelector（星期选择器）、MonthSelector（月份选择器）共 7 个子组件。
+
+## 功能特性
+
+- 支持单日选择和日期范围选择两种日历模式（`selectionMode`）
+- 支持中文（zh）、英文（en）、西班牙语（es）三种语言国际化
+- 内置自定义日期范围选择（年/月/日三列滚轮）
+- 时间段选择器支持开始时间 + 持续时长的双滚轮模式
+- 精确时间选择器支持小时/分钟独立滚轮选择（逐分钟精度）
+- 日期选择器（1-31日）、星期选择器（周一-周日）、月份选择器（1-12月）均支持单选/多选
+- 容器尺寸自适应（`autoSize`）或固定宽高模式
+- 可配置时间范围（`minTime`/`maxTime`）和间隔（`interval`）
+- 基于 `react-native-calendars` 的日历核心，支持滑动切月
+- 虚拟滚动列表（FixedSizeGrid）保障大数据量流畅选择
+- 支持 `@rneui/themed` 主题定制，所有子组件均通过 `withTheme` 包装
+- 提供完善的工具函数（`formatDate`、`getTimes`、`getConcreteTimes` 等）
+
+## 安装使用
+
+```tsx
+import {
+  TapasCalendar,
+  TapasTimeSelector,
+  TapasConcreteTimeSelector,
+  TapasCustomRange,
+  TapasDaySelector,
+  TapasWeekDaySelector,
+  TapasMonthSelector,
+} from '@beppla/tapas-ui';
+```
+
+## 类型定义
+
+### CalendarMode 枚举
+
+```tsx
+enum CalendarMode {
+  Month = 'month',
+  Week = 'week',
+  Day = 'day',
+  Range = 'range',
+}
+```
+
+### LanguageCode 类型
+
+```tsx
+type LanguageCode = 'zh' | 'en' | 'es';
+```
+
+### DateInfo 接口
+
+```tsx
+interface DateInfo {
+  day?: number;
+  year?: number;
+  month?: number;
+}
+```
+
+---
+
+## Calendar（日历主组件）
+
+主要的日历组件，提供基础日历选择和自定义范围选择两个 Tab 页面。
+
+### Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| languageCode | `LanguageCode` | `'en'` | 语言代码，支持 zh/en/es |
+| mode | `CalendarMode` | - | 日历模式（month/week/day/range） |
+| current | `string` | 当前日期 | 初始显示日期，格式 `YYYY-MM-DD` |
+| defaultSelectedDate | `string \| string[]` | - | 默认选中日期 |
+| theme | `any` | - | 主题对象（自动注入） |
+| autoSize | `boolean` | `true` | 是否自适应容器尺寸 |
+| width | `number` | `360` | 固定宽度（autoSize=false 时生效） |
+| height | `number` | `436` | 固定高度（autoSize=false 时生效） |
+| hideDayNames | `boolean` | `false` | 是否隐藏星期名称行 |
+| hideRange | `boolean` | `false` | 是否隐藏"自定义范围"按钮 |
+| selectionMode | `'single' \| 'range'` | `'single'` | 选择模式：单日或范围 |
+| attachSelectedDate | `(date: string \| string[]) => void` | - | 选中日期回调 |
+| attachCancel | `() => void` | - | 取消/清除选择回调 |
+
+> Calendar 继承 `react-native-calendars` 的 `CalendarProps`，支持所有原生日历属性。
+
+### 使用示例
+
+#### 基础日历（单日选择）
+
+```tsx
+<TapasCalendar
+  languageCode="zh"
+  hideRange={true}
+  attachSelectedDate={(date) => alert(date)}
+/>
+```
+
+#### 固定尺寸 + 显示范围按钮
+
+```tsx
+<TapasCalendar
+  languageCode="es"
+  autoSize={false}
+  width={400}
+  height={500}
+  hideRange={false}
+  attachSelectedDate={(date) => console.log(date)}
+/>
+```
+
+#### 范围选择模式
+
+```tsx
+<TapasCalendar
+  languageCode="zh"
+  selectionMode="range"
+  defaultSelectedDate={['2026-04-01', '2026-04-07']}
+  attachSelectedDate={(dates) => console.log('选中范围:', dates)}
+/>
+```
+
+---
+
+## TimeSelector（时间段选择器）
+
+通过开始时间和持续时长两个滚轮来选择时间段。
+
+### Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| languageCode | `LanguageCode` | `'en'` | 语言代码 |
+| rangeVal | `string[]` | - | 初始时间范围值（必填） |
+| backFn | `() => void` | - | 返回按钮回调 |
+| attachComplete | `(range: string[]) => void` | - | 完成选择回调，返回 `[开始时间, 结束时间]` |
+| showCloseBtn | `boolean` | `false` | 是否显示关闭按钮 |
+| closeBtnText | `string` | - | 关闭按钮文本 |
+| attatchClose | `() => void` | - | 关闭按钮回调 |
+| minTime | `string` | `'8:00'` | 最小可选时间 |
+| maxTime | `string` | `'24:00'` | 最大可选时间 |
+| interval | `number` | `30` | 时间间隔（分钟） |
+| theme | `any` | - | 主题对象（自动注入） |
+
+### 使用示例
+
+```tsx
+<TapasTimeSelector
+  languageCode="en"
+  rangeVal={[]}
+  minTime="8:00"
+  maxTime="22:00"
+  interval={30}
+  attachComplete={(range) => console.log('时间段:', range)}
+/>
+```
+
+---
+
+## ConcreteTimeSelector（精确时间选择器）
+
+通过小时和分钟两个独立滚轮选择具体时间点，精度为逐分钟。
+
+### Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| languageCode | `keyof typeof SupportLanguage` | `'en'` | 语言代码 |
+| hour | `string` | - | 初始小时值，如 `'08'` |
+| minute | `string` | - | 初始分钟值，如 `'30'` |
+| backFn | `() => void` | - | 返回按钮回调 |
+| attachComplete | `(range: string[]) => void` | - | 完成回调，返回 `[小时, 分钟]` |
+| showCloseBtn | `boolean` | `false` | 是否显示关闭按钮 |
+| closeBtnText | `string` | - | 关闭按钮文本 |
+| attatchClose | `() => void` | - | 关闭按钮回调 |
+| minTime | `string` | `'00:00'` | 最小可选时间 |
+| maxTime | `string` | `'23:59'` | 最大可选时间 |
+| theme | `any` | - | 主题对象（自动注入） |
+
+### 使用示例
+
+```tsx
+<TapasConcreteTimeSelector
+  hour="08"
+  minute="30"
+  minTime="00:00"
+  maxTime="23:59"
+  languageCode="en"
+  showCloseBtn={true}
+  closeBtnText="Close"
+  attachComplete={([hour, minute]) => {
+    alert(`Selected Time: ${hour}:${minute}`);
+  }}
+/>
+```
+
+---
+
+## CustomRange（自定义日期范围）
+
+通过年/月/日三个滚轮选择日期范围的起止日期，分步操作（先选开始日期，再选结束日期）。
+
+### Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| languageCode | `LanguageCode` | `'en'` | 语言代码 |
+| backFn | `() => void` | - | 返回按钮回调（必填） |
+| rangeVal | `string[]` | - | 初始范围值 |
+| attachComplete | `(range: (DateInfo \| null)[]) => void` | - | 完成回调，返回 `[起始DateInfo, 结束DateInfo]` |
+| theme | `any` | - | 主题对象（自动注入） |
+
+### 使用示例
+
+```tsx
+<TapasCustomRange
+  languageCode="zh"
+  backFn={() => console.log('返回')}
+  rangeVal={[]}
+  attachComplete={(range) => {
+    const [start, end] = range;
+    console.log('起始:', start, '结束:', end);
+  }}
+/>
+```
+
+---
+
+## DaySelector（日期选择器）
+
+以网格形式展示 1-31 日，支持单选和多选。
+
+### Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| selectMode | `'single' \| 'multi'` | `'single'` | 选择模式 |
+| defaultSelected | `number \| number[]` | `-1` | 默认选中日期（single 为 number，multi 为 number[]） |
+| attachComplete | `(selected: null \| number \| number[]) => void` | - | 完成选择回调 |
+| languageCode | `LanguageCode` | - | 语言代码（必填） |
+| theme | `any` | - | 主题对象（自动注入） |
+
+### 使用示例
+
+```tsx
+// 多选模式
+<TapasDaySelector
+  languageCode="en"
+  selectMode="multi"
+  defaultSelected={[2]}
+  attachComplete={(days) => console.log('选中日期:', days)}
+/>
+```
+
+---
+
+## WeekDaySelector（星期选择器）
+
+以列表形式展示星期一至星期日，支持单选和多选。
+
+### Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| selectMode | `'single' \| 'multi'` | `'single'` | 选择模式 |
+| defaultSelected | `number \| number[]` | `-1` | 默认选中（1=周一, 7=周日） |
+| attachComplete | `(selected: null \| number \| number[]) => void` | - | 完成选择回调 |
+| languageCode | `LanguageCode` | - | 语言代码（必填） |
+| theme | `any` | - | 主题对象（自动注入） |
+
+### 使用示例
+
+```tsx
+<TapasWeekDaySelector
+  languageCode="en"
+  selectMode="multi"
+  defaultSelected={[1, 2]}
+  attachComplete={(days) => console.log('选中星期:', days)}
+/>
+```
+
+---
+
+## MonthSelector（月份选择器）
+
+以网格形式展示 1-12 月，支持单选和多选。
+
+### Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| selectMode | `'single' \| 'multi'` | `'single'` | 选择模式 |
+| defaultSelected | `number \| number[]` | `-1` | 默认选中月份（1-12） |
+| attachComplete | `(selected: null \| number \| number[]) => void` | - | 完成选择回调 |
+| languageCode | `LanguageCode` | - | 语言代码（必填） |
+| theme | `any` | - | 主题对象（自动注入） |
+
+### 使用示例
+
+```tsx
+<TapasMonthSelector
+  languageCode="en"
+  selectMode="multi"
+  defaultSelected={[1, 2]}
+  attachComplete={(months) => console.log('选中月份:', months)}
+/>
+```
+
+---
+
+## 综合使用示例
+
+### 日历 + 时间选择组合
+
+```tsx
+import { useState } from 'react';
+import { View } from 'react-native';
+import TapasCalendar from './Calendar';
+import TimeSelector from './TimeSelector';
+
+export const DateTimePicker = () => {
+  const [date, setDate] = useState('');
+  const [timeRange, setTimeRange] = useState<string[]>([]);
+
+  return (
+    <View style={{ flex: 1 }}>
+      <View style={{ height: 400 }}>
+        <TapasCalendar
+          languageCode="zh"
+          hideRange={true}
+          attachSelectedDate={(d) => setDate(d as string)}
+        />
+      </View>
+      <View style={{ height: 300 }}>
+        <TimeSelector
+          languageCode="zh"
+          rangeVal={[]}
+          minTime="8:00"
+          maxTime="22:00"
+          attachComplete={(range) => setTimeRange(range)}
+        />
+      </View>
+    </View>
+  );
+};
+```
+
+### 工作排班选择器
+
+```tsx
+import { View } from 'react-native';
+import WeekDaySelector from './WeekDaySelector';
+import ConcreteTimeSelector from './ConcreteTimeSelector';
+
+export const SchedulePicker = () => (
+  <View style={{ flex: 1 }}>
+    <WeekDaySelector
+      selectMode="multi"
+      defaultSelected={[1, 2, 3, 4, 5]}
+      languageCode="zh"
+      attachComplete={(days) => console.log('工作日:', days)}
+    />
+    <ConcreteTimeSelector
+      hour="09"
+      minute="00"
+      languageCode="zh"
+      attachComplete={([h, m]) => console.log(`上班时间: ${h}:${m}`)}
+    />
+  </View>
+);
+```
+
+### 季度月份选择
+
+```tsx
+import MonthSelector from './MonthSelector';
+
+<MonthSelector
+  selectMode="multi"
+  defaultSelected={[1, 4, 7, 10]}
+  languageCode="es"
+  attachComplete={(months) => console.log('Quarterly months:', months)}
+/>
+```
+
+## 工具函数（helper.ts）
+
+| 函数 | 签名 | 说明 |
+|------|------|------|
+| `formatDate` | `(date: Date) => string` | 格式化日期为 `YYYY-MM-DD` |
+| `formatTitle` | `(dateStr: string, languageCode: LanguageCode) => string` | 格式化日历标题（如 `Jan 2026`） |
+| `calcHeaderWidth` | `(width: number) => number` | 计算日历头部宽度 |
+| `getTimes` | `(startTime: string, interval?: number) => string[]` | 生成时间列表 |
+| `getConcreteTimes` | `(startTime: string, endTime: string, returnType?: string) => string[]` | 生成精确时间列表 |
+| `getIntervalValues` | `(minTime: string, maxTime: string) => DurationItem[]` | 生成持续时长选项 |
+| `getDays` | `(date: Date, languageCode: LanguageCode) => string[]` | 获取月份天数列表 |
+| `getYears` | `(date: Date, languageCode: LanguageCode) => string[]` | 获取年份列表（1900至今） |
+
+## 注意事项
+
+- Calendar 组件依赖 `react-native-calendars`，需确保已安装
+- 范围选择模式（`selectionMode='range'`）需选择两个日期后点击确认按钮才触发回调
+- TimeSelector 的 `rangeVal` 为必填属性，初始值传空数组 `[]`
+- ConcreteTimeSelector 的 `minTime`/`maxTime` 需符合 `HH:MM` 格式（24小时制），正则校验不通过会返回空数组
+- 所有滚轮选择器使用虚拟滚动（FixedSizeGrid），中间行为当前选中项
+- `TapasCustomRnageProps` 为已废弃的拼写错误别名，请使用 `TapasCustomRangeProps`
+- CustomRange 的 reset 功能中滚动重置尚未完善（源码含 TODO 注释）
+- 回调函数返回值类型各异：Calendar 返回 `string | string[]`，TimeSelector/ConcreteTimeSelector 返回 `string[]`，CustomRange 返回 `(DateInfo | null)[]`，Selector 系列返回 `number | number[]`

package/package/module/Card/README.md

@@ -0,0 +1,126 @@
+# Card
+
+通用卡片组件，支持图标、状态指示、导航按钮和更多选项菜单，适用于仪表板入口、功能模块展示等场景。
+
+## 功能特性
+
+- ✅ 支持自定义图标显示（TapasIcon）
+- ✅ 状态指示器（normal / warning / error / success），带对应颜色背景标签
+- ✅ 可选的导航按钮（showNavBtn），带圆形边框样式
+- ✅ 更多选项按钮（showMore），支持自定义图标
+- ✅ 鼠标悬停阴影效果
+- ✅ 自定义卡片宽度，固定高度 128px
+- ✅ 标题与副标题显示，自动单行截断
+- ✅ 点击事件回调，返回 `path--cardId` 格式
+- ✅ 继承 ViewProps，支持自定义样式
+- ✅ 基于 @rneui/themed 主题系统
+
+## 安装使用
+
+```tsx
+import Card from '@beppla/tapas-ui/components/Card/Card';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| cardId | `string` | (必填) | 卡片唯一标识 |
+| title | `string` | - | 卡片标题 |
+| subTitle | `string` | - | 卡片副标题 |
+| icon | `string` | - | 卡片图标名称（TapasIcon） |
+| showMore | `boolean` | - | 是否显示更多选项按钮 |
+| moreBtnIcon | `string` | `'more_vert'` | 更多按钮图标名称 |
+| showMoreOptions | `(key: string) => void` | - | 更多选项按钮点击回调，参数为 cardId |
+| path | `string` | - | 路径标识，拼接到 onPress 回调参数中 |
+| showNavBtn | `boolean` | - | 是否显示导航按钮 |
+| navBtnIcon | `string` | `'back'` | 导航按钮图标名称 |
+| state | `'normal' \| 'warning' \| 'error' \| 'success'` | - | 卡片状态 |
+| stateText | `string` | - | 状态指示文本 |
+| width | `number` | `285` | 卡片宽度（像素） |
+| onPress | `(key: string) => void` | - | 卡片点击回调，参数为 `${path}--${cardId}` |
+| actions | `Action[]` | - | 操作按钮数组 |
+| style | `ViewStyle` | - | 自定义样式（继承自 ViewProps） |
+
+### Action 接口
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| key | `string` | 操作唯一标识 |
+| name | `string` | 操作名称 |
+| icon | `string` | 操作图标名称 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<Card
+  cardId="card-1"
+  title="示例卡片"
+  subTitle="这是一个示例卡片"
+  icon="dashboard"
+  showNavBtn
+  width={285}
+/>
+```
+
+### 带状态指示
+
+```tsx
+<Card
+  cardId="card-2"
+  title="运行状态"
+  subTitle="服务器状态"
+  icon="dashboard"
+  state="success"
+  stateText="运行正常"
+/>
+```
+
+### 带更多选项
+
+```tsx
+<Card
+  cardId="card-3"
+  title="功能模块"
+  subTitle="点击查看更多"
+  icon="restaurant_menu"
+  showMore
+  showMoreOptions={(cardId) => console.log(`More: ${cardId}`)}
+/>
+```
+
+### 不同尺寸
+
+```tsx
+<Card cardId="small-card" width={200} title="小尺寸卡片" />
+<Card cardId="standard-card" width={285} title="标准尺寸卡片" />
+<Card cardId="large-card" width={350} title="大尺寸卡片" />
+```
+
+### 交互卡片
+
+```tsx
+<Card
+  cardId="card-4"
+  title="可点击卡片"
+  subTitle="点击触发事件"
+  icon="dashboard"
+  showMore
+  showNavBtn
+  state="warning"
+  stateText="需要注意"
+  onPress={(key) => console.log(`Pressed: ${key}`)}
+  showMoreOptions={(cardId) => console.log(`More: ${cardId}`)}
+/>
+```
+
+## 注意事项
+
+- `cardId` 属性是必填项，用于唯一标识卡片
+- `onPress` 回调返回的 key 格式为 `${path}--${cardId}`
+- `state` 和 `stateText` 需同时设置才会显示状态标签
+- 卡片固定高度为 128px，宽度通过 `width` 属性控制，默认 285px
+- 更多选项按钮点击事件通过 `stopPropagation` 阻止冒泡到卡片点击
+- 组件使用 `@rneui/themed` 主题系统，需在 ThemeProvider 内使用