@beppla/tapas-ui 1.5.10 → 1.5.12

package/package/module/Tag/README.md

@@ -0,0 +1,93 @@
+# Tag
+
+标签组件，用于标记和分类信息。支持关闭按钮、多种尺寸和禁用状态。
+
+## 功能特性
+
+- ✅ 支持三种尺寸：small（32px）、middle（36px）、large（40px）
+- ✅ 可选的关闭按钮，支持点击关闭回调
+- ✅ 支持禁用状态，禁用时关闭按钮不可点击
+- ✅ 文字超出宽度自动省略（可设置最大宽度）
+- ✅ 胶囊形圆角样式
+- ✅ 灰色背景，主题色文字
+- ✅ 使用 React.memo 优化渲染性能
+- ✅ 支持无障碍标签（accessibilityRole="button"）
+
+## 安装使用
+
+```tsx
+import Tag from '@beppla/tapas-ui/components/Tag/Tag';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| children | `React.ReactNode` | - | 标签内容 |
+| closable | `boolean` | `true` | 是否显示关闭按钮 |
+| onClose | `() => void` | - | 关闭按钮点击回调 |
+| style | `StyleProp<ViewStyle>` | - | 自定义容器样式 |
+| size | `'small' \| 'middle' \| 'large'` | `'large'` | 标签尺寸 |
+| textMaxWidth | `number` | `226` | 文字最大宽度 |
+| disabled | `boolean` | `false` | 是否禁用 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<Tag>标签文字</Tag>
+```
+
+### 可关闭标签
+
+```tsx
+<Tag closable onClose={() => console.log('closed')}>
+  可关闭
+</Tag>
+```
+
+### 不同尺寸
+
+```tsx
+<Tag size="small">Small</Tag>
+<Tag size="middle">Middle</Tag>
+<Tag size="large">Large</Tag>
+```
+
+### 禁用状态
+
+```tsx
+<Tag disabled>禁用标签</Tag>
+```
+
+### 标签列表（可删除）
+
+```tsx
+const [list, setList] = useState([
+  { name: '标签1', value: '1' },
+  { name: '标签2', value: '2' },
+]);
+
+<View style={{ flexDirection: 'row' }}>
+  {list.map((item, idx) => (
+    <Tag
+      key={item.value}
+      onClose={() => {
+        const newList = [...list];
+        newList.splice(idx, 1);
+        setList(newList);
+      }}
+    >
+      {item.name}
+    </Tag>
+  ))}
+</View>
+```
+
+## 注意事项
+
+- 默认 `closable` 为 `true`，如不需要关闭按钮请显式设置为 `false`
+- 禁用状态下关闭图标仍然显示，但不可点击
+- `textMaxWidth` 默认为 226，超出文字会被裁剪（overflow: hidden）
+- 标签之间默认有 `marginRight: 8` 和 `marginBottom: 8` 的间距

package/package/module/Task/README.md

@@ -0,0 +1,110 @@
+# Task
+
+任务卡片组件（TaskCard），用于在甘特图或看板中展示任务的详细信息。包含标题、描述、状态标签、完成进度和时间范围，四种状态（Waiting / Ongoing / Delay / Completed）各有对应的颜色和样式。
+
+## 功能特性
+
+- ✅ 四种任务状态：Waiting（等待）、Ongoing（进行中）、Delay（延迟）、Completed（已完成）
+- ✅ 状态自动匹配颜色和背景（绿色/红色/蓝色/灰色）
+- ✅ 进度条背景色覆盖（左侧彩色边框 + 背景填充）
+- ✅ 多条描述文本展示（description 数组）
+- ✅ 完成百分比显示
+- ✅ 时间范围展示（开始时间 - 结束时间）
+- ✅ Completed 状态自动隐藏时间范围和状态标签
+- ✅ 支持自定义状态文本（statusText）和完成文本（completedText）
+- ✅ 卡片阴影效果
+- ✅ 主题色适配
+
+## 安装使用
+
+```tsx
+import { TaskCard } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| title | `string` | - | 任务标题（必填） |
+| description | `string[]` | - | 描述文本数组（必填） |
+| state | `keyof typeof TaskStatus` | - | 任务状态（必填） |
+| timeRange | `string[]` | - | 时间范围 [start, end]（必填） |
+| completion | `number` | - | 完成比例（0-1） |
+| statusText | `Record<keyof typeof TaskStatus, string>` | - | 自定义状态文本映射 |
+| completedText | `string` | - | 完成状态显示文本 |
+| style | `CSSProperties` | `{}` | 自定义外层样式 |
+
+### TaskStatus 枚举
+
+```tsx
+enum TaskStatus {
+  Waiting = 'Waiting',
+  Ongoing = 'Ongoing',
+  Delay = 'Delay',
+  Completed = 'Completed',
+}
+```
+
+## 使用示例
+
+### 进行中的任务
+
+```tsx
+<TaskCard
+  title="Kitchen preparation"
+  description={['Table 5', 'Main course']}
+  state="Ongoing"
+  timeRange={['09:00', '10:30']}
+  completion={0.6}
+/>
+```
+
+### 延迟任务
+
+```tsx
+<TaskCard
+  title="Delivery order #123"
+  description={['Customer: John', 'Priority: High']}
+  state="Delay"
+  timeRange={['14:00', '15:00']}
+  completion={0.3}
+/>
+```
+
+### 已完成任务
+
+```tsx
+<TaskCard
+  title="Inventory check"
+  description={['Warehouse A']}
+  state="Completed"
+  timeRange={['08:00', '09:00']}
+  completedText="Done"
+/>
+```
+
+### 自定义状态文本
+
+```tsx
+<TaskCard
+  title="Task"
+  description={['Info']}
+  state="Waiting"
+  timeRange={['10:00', '11:00']}
+  statusText={{
+    Waiting: 'Pending',
+    Ongoing: 'In Progress',
+    Delay: 'Overdue',
+    Completed: 'Finished',
+  }}
+/>
+```
+
+## 注意事项
+
+- 组件使用 HTML div + span 元素，仅适用于 Web 平台
+- `completion` 值范围 0-1，Completed 状态自动设为 1，Waiting 状态自动设为 0
+- 进度背景宽度通过 CSS calc 计算：`calc(completion * 100% + 28px)`
+- 描述文本超长会自动省略（text-overflow: ellipsis）
+- 卡片使用 @rneui/themed 的 Card 组件，带有 boxShadow 效果
+- 需在 `ThemeProvider` 内使用

package/package/module/Text/README.md

@@ -0,0 +1,97 @@
+# Text
+
+可交互的文本标签组件，支持选中状态、悬停效果、多种尺寸和两种视觉类型。适用于筛选标签、价格区间选择、分类标签等场景，非通用 Text 组件。
+
+## 功能特性
+
+- ✅ 两种视觉类型：primary（填充灰色背景）和 secondary（边框样式）
+- ✅ 三种尺寸模式：standard (40px) / medium (36px) / small (32px)
+- ✅ 选中状态：primary 变为主题色背景+白字，secondary 显示主题色边框
+- ✅ 鼠标悬停效果（仅 Web 端，Hoverable 实现）
+- ✅ 禁用状态，颜色置灰，渲染为不可交互的 Text
+- ✅ 支持点击事件
+- ✅ 文本单行截断（numberOfLines=1）
+- ✅ 继承 @rneui/themed TextProps
+- ✅ 圆角样式（theme.radius.rounded）
+
+## 安装使用
+
+```tsx
+import Text from '@beppla/tapas-ui/components/Text/Text';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| children | `React.ReactNode` | - | 文本内容 |
+| mode | `'standard' \| 'medium' \| 'small'` | - | 尺寸模式，影响高度和字号 |
+| type | `'primary' \| 'secondary'` | `'primary'` | 视觉类型 |
+| selected | `boolean` | `false` | 是否选中 |
+| disabled | `boolean` | - | 是否禁用 |
+| onPress | `() => void` | - | 点击回调 |
+| hoverStyle | `StyleProp<ViewStyle>` | - | 自定义悬停样式 |
+| style | 继承自 TextProps | - | 自定义样式 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<Text mode="standard">Hello World</Text>
+```
+
+### 不同尺寸
+
+```tsx
+<Text mode="standard" style={{ width: 200 }}>Standard (40px)</Text>
+<Text mode="medium" style={{ width: 160 }}>Medium (36px)</Text>
+<Text mode="small" style={{ width: 100 }}>Small (32px)</Text>
+```
+
+### Secondary 类型
+
+```tsx
+<Text mode="standard" type="secondary">边框样式</Text>
+<Text mode="medium" type="secondary" selected>选中状态</Text>
+```
+
+### 选中与禁用
+
+```tsx
+<Text mode="small" selected>已选中（Primary）</Text>
+<Text mode="medium" disabled>已禁用</Text>
+<Text mode="small" type="secondary" disabled>禁用边框</Text>
+```
+
+### 带点击事件
+
+```tsx
+<Text mode="standard" onPress={() => console.log('Clicked')}>
+  可点击标签
+</Text>
+```
+
+### 动态选择
+
+```tsx
+const [selected, setSelected] = useState(false);
+
+<Text
+  mode="standard"
+  selected={selected}
+  onPress={() => setSelected(!selected)}
+>
+  切换选择状态
+</Text>
+```
+
+## 注意事项
+
+- 该组件是专用的**标签/筛选按钮组件**，非通用文本渲染组件
+- 禁用状态下不渲染 TouchableOpacity，直接渲染为普通 RNText
+- Web 端通过 Hoverable 实现悬停效果，Native 端无悬停
+- `selected` 状态受外部控制，内部通过 `useEffect` 同步
+- `mode` 属性决定高度和字号：standard=40px、medium=36px、small=32px（small 字号也更小）
+- primary 类型选中时背景变为主色+白字，secondary 类型选中时添加主色边框
+- 组件使用 `@rneui/themed` 主题系统，需在 ThemeProvider 内使用

package/package/module/TextArea/README.md

@@ -0,0 +1,127 @@
+# TextArea
+
+多行文本输入组件，支持浮动标签、字符计数、清空按钮和错误状态等功能。
+
+## 功能特性
+
+- ✅ 支持多行文本输入
+- ✅ 浮动标签动画（聚焦/有内容时标签上移）
+- ✅ 字符计数功能（显示当前字数/最大字数）
+- ✅ 一键清空按钮
+- ✅ 必填标识（红色星号）
+- ✅ 错误状态（红色边框 + 错误提示文字）
+- ✅ 聚焦时边框变粗并使用主题色
+- ✅ 可自定义高度、行数和背景色
+- ✅ 支持禁用状态
+- ✅ 兼容 RN 0.77 Bridgeless 模式（Android 焦点管理修复）
+
+## 安装使用
+
+```tsx
+import TextArea from '@beppla/tapas-ui/components/TextArea/TextArea';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| height | `number` | `88` | 输入框高度 |
+| label | `string` | - | 浮动标签文字 |
+| showCount | `boolean` | `false` | 是否显示字符计数 |
+| showClearBtn | `boolean` | `false` | 是否显示清空按钮 |
+| value | `string` | - | 输入框内容 |
+| numberOfLines | `number` | `4` | 显示行数 |
+| maxCount | `number` | `100` | 最大字符数（仅用于计数显示） |
+| placeholder | `string` | - | 占位文字 |
+| required | `boolean` | `false` | 是否必填（显示红色星号） |
+| onChangeText | `(value: string) => void` | - | 内容变化回调 |
+| backgroundColor | `string` | - | 标签背景色 |
+| state | `'normal' \| 'error'` | `'normal'` | 状态 |
+| stateMsg | `string` | - | 状态提示信息 |
+| disabled | `boolean` | - | 是否禁用 |
+| enableBridgelessFix | `boolean` | `true` | 是否启用 RN 0.77 Bridgeless 模式兼容修复 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<TextArea
+  label="描述"
+  placeholder="请输入详细描述..."
+/>
+```
+
+### 带字符计数
+
+```tsx
+<TextArea
+  label="产品描述"
+  placeholder="请详细描述产品特性..."
+  showCount={true}
+  maxCount={150}
+  required={true}
+/>
+```
+
+### 带清空按钮
+
+```tsx
+<TextArea
+  label="备注信息"
+  placeholder="请输入备注..."
+  showClearBtn={true}
+  value="示例文本"
+/>
+```
+
+### 错误状态
+
+```tsx
+<TextArea
+  label="必填字段"
+  placeholder="此字段不能为空"
+  required={true}
+  state="error"
+  stateMsg="请输入有效的内容"
+  showCount={true}
+  maxCount={100}
+/>
+```
+
+### 完整功能
+
+```tsx
+const [value, setValue] = useState('');
+
+<TextArea
+  label="用户反馈"
+  placeholder="请详细描述您遇到的问题..."
+  required={true}
+  showCount={true}
+  showClearBtn={true}
+  maxCount={300}
+  numberOfLines={6}
+  height={120}
+  value={value}
+  onChangeText={setValue}
+/>
+```
+
+### 禁用状态
+
+```tsx
+<TextArea
+  label="只读内容"
+  value="这是只读的文本内容"
+  disabled={true}
+/>
+```
+
+## 注意事项
+
+- `maxCount` 仅用于计数显示，不会限制实际输入字数
+- 当设置 `label` 时，`placeholder` 会在未聚焦且无内容时作为标签文字显示
+- 不设置 `label` 时，`placeholder` 作为普通占位符显示
+- 容器高度会根据 `height`、`numberOfLines`、`label` 和 `showCount` 自动计算
+- Android 上启用了 Bridgeless 模式兼容修复，如遇焦点异常可设置 `enableBridgelessFix={false}`

package/package/module/Theme/README.md

@@ -0,0 +1,161 @@
+# ThemeProvider
+
+主题提供组件，基于 `@rneui/themed` 的 ThemeProvider 封装，为整个应用提供统一的设计令牌（Design Tokens）。包含颜色、间距、圆角、字体、阴影等完整的主题配置，为换肤功能做好预备。
+
+## 功能特性
+
+- ✅ 统一主题注入：colors、spacing、radius、fonts、elevation
+- ✅ 支持 light / dark 模式切换（预留）
+- ✅ 80+ 颜色令牌：涵盖文本、表面、边框、图标、状态、图表等
+- ✅ 12 级间距系统（4px ~ 112px）
+- ✅ 3 级圆角系统（mini: 4 / rounded: 12 / full: 360）
+- ✅ 完整字体配置：5 级字号、5 级字重、行高、字间距
+- ✅ 4 级阴影/elevation 系统
+- ✅ Figma Design Token 对齐
+- ✅ 中文字体支持（MiSans VF / PingFang SC）
+- ✅ 组件级别主题覆盖（components.Button）
+
+## 安装使用
+
+```tsx
+import { TapasThemeProvider } from '@beppla/tapas-ui';
+// 或
+import ThemeProvider from '@beppla/tapas-ui/components/Theme/ThemeProvider';
+```
+
+## ThemeProvider Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| mode | `'light' \| 'dark'` | `'dark'` | 主题模式 |
+| children | `React.ReactNode` | - | 子组件 |
+| testID | `string` | - | 测试标识 |
+
+## defaultTheme 函数
+
+```tsx
+import { defaultTheme } from '@beppla/tapas-ui';
+
+const theme = defaultTheme({ mode: 'dark' });
+```
+
+### ThemeOptions
+
+```tsx
+interface ThemeOptions {
+  mode?: 'light' | 'dark';
+}
+```
+
+## 主题令牌一览
+
+### 颜色（theme.colors）
+
+| 分类 | 主要令牌 | 示例 |
+|------|---------|------|
+| 基础色 | primary, secondary, background, white, black | `rgba(0,0,0,0.87)` |
+| 灰阶 | grey0 ~ grey5, greyOutline | `rgba(0,0,0,0.04)` ~ `rgba(0,0,0,0.87)` |
+| 语义色 | success, warning, error, info | `#57B07B`, `#B81F1E`, `#007AFF` |
+| 文本色 | colorTextPrimary, colorTextSecondary, colorTextBrand, colorTextAccent | `#895F38`, `#F55523` |
+| 表面色 | colorSurface ~ colorSurface11 | `#F9F2E8` ~ `rgba(255,255,255,0.30)` |
+| 边框色 | colorPrimaryBorder, colorBorder1, colorBorder2, colorErrorBorder, colorActiveBorder | `rgba(0,0,0,0.12)` |
+| 图标色 | colorNormalIcon, colorActiveIcon, colorDisabledIcon, colorAccentIcon | `#F55523` |
+| 状态色 | colorStatusAvailable, colorStatusOccupied, colorStatusReserved 等 | `#57B07B`, `#B81F1E` |
+| 图表色 | colorChartCategoryTeal, colorChartProductBrown 等 | `#1FBCAD`, `#895F38` |
+
+### 间距（theme.spacing）
+
+| 令牌 | 值 | Figma 别名 |
+|------|------|-----------|
+| tp2xs | 4 | spacing2xs |
+| tpXs | 8 | spacingXs |
+| tpSm | 12 | spacingSm |
+| tpRg | 16 | spacingRg |
+| tpMd | 24 | spacingMd |
+| tpLg | 32 | spacingLg |
+| tpXl | 48 | spacingXl |
+| tp2xl | 88 | spacingBlg |
+| tp3xl | 112 | spacingBlgger |
+
+### 圆角（theme.radius）
+
+| 令牌 | 值 | 用途 |
+|------|------|------|
+| mini | 4 | 卡片、标签 |
+| rounded | 12 | 按钮、输入框 |
+| full | 360 | 圆形头像、胶囊按钮 |
+
+### 字体（theme.fonts）
+
+| 令牌 | 值 | 说明 |
+|------|------|------|
+| fontFamily | `BricolageGrotesque-Regular` | 英文主字体 |
+| fontFamilyCN | `MiSans VF` | 中文主字体 |
+| h1 ~ h4 | 44 / 32 / 24 / 21 | 标题字号 |
+| sizeL / sizeM / sizeS / sizeXs | 16 / 14 / 12 / 10 | 正文字号 |
+| weightL / weightM / weightS / weightR | 700 / 600 / 500 / 400 | 字重 |
+
+### 阴影（theme.elevation）
+
+| 令牌 | shadowRadius | elevation | 场景 |
+|------|-------------|-----------|------|
+| e1 | 3 | 2 | 卡片 |
+| e2 | 6 | 4 | 浮动按钮 |
+| e3 | 12 | 8 | 弹窗 |
+| e4 | 24 | 16 | 对话框 |
+
+## 使用示例
+
+### 应用根节点
+
+```tsx
+import { TapasThemeProvider } from '@beppla/tapas-ui';
+
+export default function App() {
+  return (
+    <TapasThemeProvider mode="dark">
+      <MainNavigator />
+    </TapasThemeProvider>
+  );
+}
+```
+
+### 在组件中使用主题
+
+```tsx
+import { useTheme, makeStyles } from '@rneui/themed';
+
+const MyComponent = () => {
+  const { theme } = useTheme();
+  return <View style={{ backgroundColor: theme.colors.background }} />;
+};
+
+// 或使用 makeStyles
+const useStyles = makeStyles((theme) => ({
+  container: {
+    padding: theme.spacing.tpRg,
+    borderRadius: theme.radius.rounded,
+  },
+}));
+```
+
+### Storybook 中使用
+
+```tsx
+export const decorators = [
+  (Story) => (
+    <TapasThemeProvider mode="dark">
+      <Story />
+    </TapasThemeProvider>
+  ),
+];
+```
+
+## 注意事项
+
+- 当前 `light` 和 `dark` 模式使用相同的颜色值（darkColors = colors），待设计师确认后更新
+- 所有 tapas-ui 组件都需要在 ThemeProvider 内使用
+- 主题对象通过 `@rneui/themed` 的 `useTheme` / `makeStyles` / `withTheme` 消费
+- `defaultTheme` 返回的是完整配置对象，不是 React 组件
+- 字体文件需要在应用层加载（expo-font 或原生配置）
+- 组件级覆盖目前仅配置了 Button 的默认样式

package/package/module/Timeline/README.md

@@ -0,0 +1,111 @@
+# Timeline
+
+时间线组件，用于展示按时间排列的事件或活动列表。每个事件节点包含时间和描述，支持多种状态（选中、禁用、错误），并提供 Hover 交互效果和点击回调。
+
+## 功能特性
+
+- ✅ 纵向时间线布局，节点 + 连接线
+- ✅ 四种节点状态：默认、selected（选中）、disabled（禁用）、error（错误）
+- ✅ 状态对应不同的颜色和线条样式（实线/虚线）
+- ✅ 错误状态显示警告图标
+- ✅ Hover 高亮效果（Hoverable 组件）
+- ✅ 支持点击事件回调
+- ✅ 标题 + 滚动内容区域
+- ✅ 自定义容器和内容区域样式
+- ✅ 主题色适配
+
+## 安装使用
+
+```tsx
+import { Timeline } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| data | `IData` | - | 时间线数据（必填） |
+| itemContainerStyle | `StyleProp<ViewStyle>` | - | 事件列表容器样式（必填） |
+| onPress | `(item: Item) => void` | - | 事件项点击回调 |
+| selected | `boolean` | `false` | 全局选中状态（预留） |
+| disabled | `boolean` | - | 全局禁用状态（预留） |
+| containerStyle | `StyleProp<ViewStyle>` | - | 最外层容器样式 |
+| testID | `string` | - | 测试标识 |
+
+### IData
+
+```tsx
+interface IData {
+  title: string;
+  items: Item[];
+}
+```
+
+### Item
+
+```tsx
+interface Item {
+  id: string;
+  time: string;
+  description: string;
+  selected?: boolean;
+  disabled?: boolean;
+  error?: boolean;
+}
+```
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+const data = {
+  title: 'Order History',
+  items: [
+    { id: '1', time: '09:00', description: 'Order placed', selected: true },
+    { id: '2', time: '10:30', description: 'Payment confirmed' },
+    { id: '3', time: '14:00', description: 'Shipped' },
+  ],
+};
+
+<Timeline
+  data={data}
+  itemContainerStyle={{ minHeight: 200 }}
+  onPress={(item) => console.log('Clicked:', item.id)}
+/>
+```
+
+### 错误状态
+
+```tsx
+const data = {
+  title: 'Delivery Status',
+  items: [
+    { id: '1', time: '08:00', description: 'Dispatched', selected: true },
+    { id: '2', time: '12:00', description: 'Delivery failed', error: true },
+    { id: '3', time: '15:00', description: 'Rescheduled', disabled: true },
+  ],
+};
+
+<Timeline data={data} itemContainerStyle={{ minHeight: 300 }} />
+```
+
+### 自定义样式
+
+```tsx
+<Timeline
+  data={data}
+  itemContainerStyle={{ minHeight: 400 }}
+  containerStyle={{ width: 300, backgroundColor: '#FFF' }}
+  onPress={handleItemPress}
+/>
+```
+
+## 注意事项
+
+- 容器默认宽度 192px，可通过 `containerStyle` 覆盖
+- 事件列表在 ScrollView 内，支持滚动
+- Hover 效果基于 Hoverable 组件实现，仅在 Web 端生效
+- 连接线在 `disabled` 状态下为虚线样式
+- 节点状态在 item 级别控制（item.selected / item.disabled / item.error）
+- 需在 `ThemeProvider` 内使用