@unif/react-native-ui 0.1.0

package/src/hooks/index.md

@@ -0,0 +1,71 @@
+# Hooks
+
+基础组件库的工具 hooks。
+
+## mergeStyles
+
+按 slot 维度合并多来源样式的纯函数。借鉴 antd v6 `useMergeSemantic`（`components/_util/hooks/useMergeSemantic.ts:69-80`）。
+
+### 何时使用
+
+- 组件内部合并默认样式 + 变体样式 + 用户传入的 `styles` 语义插槽
+- 构建支持 Semantic Styles 的自定义组件时
+
+### 代码演示
+
+```tsx
+import {mergeStyles} from '../hooks';
+
+type MySemanticStyles = {
+  root?: ViewStyle;
+  content?: TextStyle;
+};
+
+const DEFAULT: MySemanticStyles = {
+  root: {padding: 16},
+  content: {fontSize: 14, color: tokens.colorText},
+};
+
+const MyComponent = ({styles: userStyles}: {styles?: Partial<MySemanticStyles>}) => {
+  // ✅ 配合 useMemo，仅 userStyles 变化时重算
+  const s = useMemo(
+    () => mergeStyles(DEFAULT, userStyles),
+    [userStyles],
+  );
+
+  return (
+    <View style={s.root}>
+      <Text style={s.content}>...</Text>
+    </View>
+  );
+};
+```
+
+### API
+
+```ts
+function mergeStyles<T extends Record<string, StyleValue | undefined>>(
+  ...sources: (Partial<T> | undefined)[]
+): T
+```
+
+| 参数 | 说明 | 类型 |
+|------|------|------|
+| sources | 多个样式源，按顺序合并 | `(Partial<T> \| undefined)[]` |
+
+### 合并规则
+
+- 按 slot key 维度合并（`root`、`content` 等分别合并）
+- 同一 slot 内使用对象展开（`{...prev, ...next}`），后传入的覆盖先传入的
+- `undefined` 源自动跳过
+- 纯函数，不包含 `useMemo`，调用方自行控制缓存
+
+### 与 antd v6 对比
+
+| 特性 | antd v6 `mergeStyles` | RN 版 `mergeStyles` |
+|------|----------------------|---------------------|
+| classNames 合并 | ✅ | ❌（RN 无 CSS 类名） |
+| schema 嵌套 | ✅ | ❌（当前不需要） |
+| 函数形式 style | ✅ | ❌（不需要动态计算） |
+| slot 展开合并 | ✅ | ✅（核心逻辑一致） |
+| 纯函数 | ✅ | ✅ |

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export { mergeStyles } from './useMergeStyles';

package/src/hooks/useMergeStyles.ts

@@ -0,0 +1,27 @@
+/**
+ * 语义样式合并
+ *
+ * 纯函数版本，调用方通过 useMemo 控制缓存策略。
+ */
+
+import type { ImageStyle, TextStyle, ViewStyle } from 'react-native';
+
+type StyleValue = ViewStyle | TextStyle | ImageStyle;
+
+/**
+ * 按 slot 维度合并多来源样式。
+ */
+export function mergeStyles<T extends Record<string, StyleValue | undefined>>(
+  ...sources: (Partial<T> | undefined)[]
+): T {
+  const merged = {} as Record<string, StyleValue>;
+  for (const source of sources) {
+    if (!source) {
+      continue;
+    }
+    for (const key of Object.keys(source)) {
+      merged[key] = { ...(merged[key] as object), ...(source[key] as object) };
+    }
+  }
+  return merged as T;
+}

package/src/index.tsx

@@ -0,0 +1,49 @@
+// Theme
+export { configure } from './theme/config';
+export type { ThemeConfig } from './theme/config';
+export { tokens } from './theme/tokens';
+
+// Hooks
+export { mergeStyles } from './hooks';
+
+// Layout
+export { default as Row } from './row';
+export type { RowProps } from './row';
+export { default as Column } from './column';
+export type { ColumnProps } from './column';
+export { default as Center } from './center';
+export type { CenterProps } from './center';
+export { default as Space } from './space';
+export type { SpaceProps } from './space';
+
+// Components
+export { default as Text } from './text';
+export type { TextProps } from './text';
+export { default as Button } from './button';
+export type { ButtonProps } from './button';
+export type { ButtonSemanticStyles } from './button/style';
+export { default as Divider } from './divider';
+export { default as ListItem } from './list-item';
+export { default as Touchable } from './touchable';
+export type { TouchableProps } from './touchable';
+
+// Atoms
+export { default as Avatar } from './avatar';
+export type { AvatarProps } from './avatar';
+export type { AvatarSemanticStyles } from './avatar/style';
+export { default as WaveAnimation } from './wave-animation';
+export type { WaveAnimationProps } from './wave-animation';
+
+// Base (new)
+export { default as Input } from './input';
+export type { InputProps } from './input';
+export type { InputSemanticStyles } from './input/style';
+export { default as Chip } from './chip';
+export type { ChipProps } from './chip';
+export type { ChipSemanticStyles } from './chip/style';
+export { default as ActionSheet } from './action-sheet';
+export type { ActionSheetProps } from './action-sheet';
+export type { ActionSheetOption, ActionSheetSemanticStyles } from './action-sheet/style';
+export { default as Popover } from './popover';
+export type { PopoverProps } from './popover';
+export type { PopoverSemanticStyles } from './popover/style';

package/src/input/index.md

@@ -0,0 +1,73 @@
+---
+title: Input
+nav:
+  title: 组件
+  order: 1
+group:
+  title: 基础
+  order: 2
+---
+
+# Input 输入框
+
+TextInput 容器，支持多行输入、底部工具栏和自动聚焦。
+
+## 何时使用
+
+- 需要文本输入时
+- 需要带工具栏的输入框时
+- 聊天输入场景
+
+## 代码演示
+
+```tsx
+import { Input, Icon } from '@unif/react-native-ui';
+
+// 基本用法
+<Input
+  value={text}
+  onChangeText={setText}
+  placeholder="请输入..."
+/>
+
+// 多行 + 工具栏
+<Input
+  multiline
+  maxHeight={100}
+  autoFocus
+  toolbar={
+    <View style={{ flexDirection: 'row' }}>
+      <Icon name="mic-outline" size={24} />
+    </View>
+  }
+/>
+```
+
+## API
+
+| 属性            | 说明             | 类型                   | 默认值  |
+| --------------- | ---------------- | ---------------------- | ------- |
+| value           | 输入值           | `string`               | -       |
+| onChangeText    | 文本变化回调     | `(text: string) => void` | -     |
+| placeholder     | 占位文本         | `string`               | -       |
+| multiline       | 多行模式         | `boolean`              | `false` |
+| maxLength       | 最大字符数       | `number`               | -       |
+| maxHeight       | 最大高度         | `number`               | -       |
+| autoFocus       | 自动聚焦         | `boolean`              | -       |
+| returnKeyType   | 回车键类型       | `ReturnKeyTypeOptions` | -       |
+| onSubmitEditing | 提交回调         | `() => void`           | -       |
+| onBlur          | 失焦回调         | `() => void`           | -       |
+| onFocus         | 聚焦回调         | `() => void`           | -       |
+| disabled        | 禁用状态         | `boolean`              | -       |
+| toolbar         | 底部工具栏       | `ReactNode`            | -       |
+| style           | 容器样式         | `ViewStyle`            | -       |
+| styles          | 语义样式         | `InputSemanticStyles`  | -       |
+| testID          | 测试标识         | `string`               | -       |
+
+## Semantic Styles
+
+| Slot    | 说明           |
+| ------- | -------------- |
+| root    | 外层容器       |
+| input   | TextInput 本身 |
+| toolbar | 工具栏容器     |

package/src/input/index.tsx

@@ -0,0 +1,95 @@
+/**
+ * Input 基础组件
+ *
+ * TextInput 容器，支持多行、工具栏插槽、自动聚焦。
+ */
+
+import React, { useRef, useEffect, useMemo, forwardRef } from 'react';
+import { View, TextInput } from 'react-native';
+import type { ViewStyle, ReturnKeyTypeOptions } from 'react-native';
+import { mergeStyles } from '../hooks';
+import { tokens } from '../theme/tokens';
+import type { InputSemanticStyles } from './style';
+import { DEFAULT_STYLES } from './style';
+
+export interface InputProps {
+  value?: string;
+  onChangeText?: (text: string) => void;
+  placeholder?: string;
+  multiline?: boolean;
+  maxLength?: number;
+  maxHeight?: number;
+  autoFocus?: boolean;
+  returnKeyType?: ReturnKeyTypeOptions;
+  onSubmitEditing?: () => void;
+  onBlur?: () => void;
+  onFocus?: () => void;
+  disabled?: boolean;
+  toolbar?: React.ReactNode;
+  style?: ViewStyle;
+  styles?: Partial<InputSemanticStyles>;
+  testID?: string;
+}
+
+type InputRef = React.ElementRef<typeof TextInput>;
+
+const Input = forwardRef<InputRef, InputProps>(({
+  value,
+  onChangeText,
+  placeholder,
+  multiline = false,
+  maxLength,
+  maxHeight,
+  autoFocus,
+  returnKeyType,
+  onSubmitEditing,
+  onBlur,
+  onFocus,
+  disabled,
+  toolbar,
+  style,
+  styles: semanticStyles,
+  testID,
+}, ref) => {
+  const inputRef = useRef<InputRef>(null);
+
+  React.useImperativeHandle(ref, () => inputRef.current as InputRef);
+
+  const s = useMemo(
+    () => mergeStyles<InputSemanticStyles>(DEFAULT_STYLES, semanticStyles),
+    [semanticStyles],
+  );
+
+  useEffect(() => {
+    if (autoFocus) {
+      inputRef.current?.focus();
+    }
+  }, [autoFocus]);
+
+  return (
+    <View style={[s.root, style]}>
+      <TextInput
+        ref={inputRef}
+        testID={testID}
+        style={[s.input, maxHeight ? { maxHeight } : undefined]}
+        value={value}
+        onChangeText={onChangeText}
+        placeholder={placeholder}
+        placeholderTextColor={tokens.colorTextPlaceholder}
+        multiline={multiline}
+        maxLength={maxLength}
+        returnKeyType={returnKeyType}
+        onSubmitEditing={onSubmitEditing}
+        onBlur={onBlur}
+        onFocus={onFocus}
+        editable={!disabled}
+        blurOnSubmit={false}
+      />
+      {toolbar && <View style={s.toolbar}>{toolbar}</View>}
+    </View>
+  );
+});
+
+Input.displayName = 'Input';
+
+export default Input;

package/src/input/style/index.tsx

@@ -0,0 +1,32 @@
+import { Platform } from 'react-native';
+import type { ViewStyle, TextStyle } from 'react-native';
+import { tokens } from '../../theme/tokens';
+
+export type InputSemanticStyles = {
+  root?: ViewStyle;
+  input?: TextStyle;
+  toolbar?: ViewStyle;
+};
+
+export const DEFAULT_STYLES: InputSemanticStyles = {
+  root: {
+    backgroundColor: tokens.colorBgElevated,
+    borderRadius: tokens.radiusXl,
+    paddingHorizontal: 12,
+    paddingTop: 8,
+    paddingBottom: 6,
+    ...tokens.shadow,
+  },
+  input: {
+    fontSize: tokens.fontSize,
+    color: tokens.colorText,
+    lineHeight: tokens.lineHeight,
+    paddingVertical: Platform.OS === 'ios' ? 4 : 2,
+    paddingHorizontal: 4,
+  },
+  toolbar: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingTop: 4,
+  },
+};

package/src/list-item/index.md

@@ -0,0 +1,101 @@
+# ListItem 列表行
+
+4 个语义 slot（root / content / description / extra），支持 `styles` 精确覆盖。
+
+## 何时使用
+
+- 替代 `<TouchableOpacity>` + icon + text + arrow 的手写列表行
+- 统一列表行样式：设置菜单、选择列表、会话列表等
+
+## 代码演示
+
+```tsx
+// 基础 — 带箭头
+<ListItem title="关于" arrow onPress={handleAbout} />
+
+// 带右侧额外信息
+<ListItem title="关于" extra="v1.0.0" onPress={handleAbout} />
+
+// 带左侧图标
+<ListItem
+  thumb={<Icon name="information-circle-outline" size={22} color={tokens.colorTextSecondary} />}
+  title="关于"
+  extra="v1.0.0"
+  onPress={handleAbout}
+/>
+
+// 带描述文字（双行）
+<ListItem
+  thumb={<Icon name="chatbubble-outline" size={16} />}
+  title="今天的会话"
+  description="最后一条消息预览..."
+  onPress={handleSelect}
+  onLongPress={handleDelete}
+/>
+
+// 语义插槽覆盖 — 选中态
+<ListItem
+  title={model.name}
+  description={model.desc}
+  extra={isSelected ? <Icon name="checkmark-circle" size={22} color={tokens.colorPrimary} /> : undefined}
+  onPress={() => handleSelect(model.id)}
+  styles={isSelected ? {
+    root: {backgroundColor: '#FFF7F0'},
+    content: {color: tokens.colorPrimary},
+  } : undefined}
+/>
+
+// 语义插槽覆盖 — 危险操作
+<ListItem
+  thumb={<Icon name="log-out-outline" size={22} color={tokens.colorError} />}
+  title="退出登录"
+  onPress={handleLogout}
+  styles={{content: {color: tokens.colorError}}}
+/>
+```
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| thumb | 左侧缩略（图标、头像等） | `ReactNode` | - |
+| title | 主标题 | `string` \| `ReactNode` | **必填** |
+| description | 描述文字（单行截断） | `string` | - |
+| extra | 右侧额外内容 | `ReactNode` \| `string` | - |
+| arrow | 显示右箭头 | `boolean` | `false` |
+| onPress | 点击回调（有值时渲染为 Pressable） | `() => void` | - |
+| onLongPress | 长按回调 | `() => void` | - |
+| disabled | 禁用状态 | `boolean` | `false` |
+| style | 外层容器样式 | `ViewStyle` | - |
+| styles | 语义插槽样式 | `Partial<ListItemSemanticStyles>` | - |
+| testID | 测试标识 | `string` | - |
+
+## Semantic Styles
+
+通过 `styles` prop 精确覆盖组件内部各 slot 的样式。
+
+| 插槽 | 类型 | 说明 |
+|------|------|------|
+| root | `ViewStyle` | 整行容器（padding、背景等） |
+| content | `TextStyle` | 主标题文字（字号、颜色、flex 等） |
+| description | `TextStyle` | 描述文字（字号、颜色等） |
+| extra | `ViewStyle & TextStyle` | 右侧额外内容区域 |
+
+## 内部布局
+
+```
+┌─ root ──────────────────────────────────┐
+│ [thumb]  ┌─ line ─────────────────────┐ │
+│          │ ┌─ contentWrap ──────────┐ │ │
+│          │ │ [content]              │ │ │
+│          │ │ [description]          │ │ │
+│          │ └────────────────────────┘ │ │
+│          │ [extra]  [arrow]           │ │
+│          └────────────────────────────┘ │
+└─────────────────────────────────────────┘
+```
+
+## 交互行为
+
+- 有 `onPress` 时自动包裹 `Pressable`，无 `onPress` 时渲染为纯 `View`
+- `onLongPress` 仅在有 `onPress` 时生效

package/src/list-item/index.tsx

@@ -0,0 +1,91 @@
+/**
+ * 列表行组件
+ *
+ * 语义 slot：root / content / description / extra。
+ */
+
+import React, { useMemo } from 'react';
+import { View, Text, Pressable } from 'react-native';
+import type { ViewStyle, TextStyle } from 'react-native';
+import { mergeStyles } from '../hooks';
+import { tokens } from '../theme/tokens';
+import type { ListItemSemanticStyles } from './style';
+import { DEFAULT_SEMANTIC, lineStyle, contentWrapStyle } from './style';
+
+interface ListItemProps {
+  thumb?: React.ReactNode;
+  title: string | React.ReactNode;
+  description?: string;
+  extra?: React.ReactNode | string;
+  arrow?: boolean;
+  arrowIcon?: React.ReactNode;
+  onPress?: () => void;
+  onLongPress?: () => void;
+  disabled?: boolean;
+  style?: ViewStyle;
+  styles?: Partial<ListItemSemanticStyles>;
+  testID?: string;
+}
+
+const defaultArrowStyle = { fontSize: 18, color: tokens.colorTextSecondary };
+
+const ListItem: React.FC<ListItemProps> = ({
+  thumb,
+  title,
+  description,
+  extra,
+  arrow,
+  arrowIcon,
+  style,
+  styles: semanticStyles,
+  ...props
+}: ListItemProps) => {
+  const s = useMemo(
+    () => mergeStyles(DEFAULT_SEMANTIC, semanticStyles),
+    [semanticStyles],
+  );
+
+  const content = (
+    <View style={[s.root, style]}>
+      {thumb}
+      <View style={lineStyle}>
+        <View style={contentWrapStyle}>
+          {typeof title === 'string' ? (
+            <Text style={s.content}>{title}</Text>
+          ) : (
+            title
+          )}
+          {description != null && (
+            <Text style={s.description} numberOfLines={1}>
+              {description}
+            </Text>
+          )}
+        </View>
+        {extra != null &&
+          (typeof extra === 'string' ? (
+            <Text style={s.extra as TextStyle}>{extra}</Text>
+          ) : (
+            <View style={s.extra as ViewStyle}>{extra}</View>
+          ))}
+        {arrow &&
+          (arrowIcon ?? <Text style={defaultArrowStyle}>›</Text>)}
+      </View>
+    </View>
+  );
+
+  if (props.onPress) {
+    return (
+      <Pressable
+        onPress={props.onPress}
+        onLongPress={props.onLongPress}
+        disabled={props.disabled}
+        testID={props.testID}
+      >
+        {content}
+      </Pressable>
+    );
+  }
+  return content;
+};
+
+export default ListItem;

package/src/list-item/style/index.tsx

@@ -0,0 +1,41 @@
+import { StyleSheet } from 'react-native';
+import type { ViewStyle, TextStyle } from 'react-native';
+import { tokens } from '../../theme/tokens';
+
+export type ListItemSemanticStyles = {
+  root?: ViewStyle;
+  content?: TextStyle;
+  description?: TextStyle;
+  extra?: ViewStyle & TextStyle;
+};
+
+export const DEFAULT_SEMANTIC: ListItemSemanticStyles = {
+  root: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingHorizontal: 16,
+    paddingVertical: 14,
+  },
+  content: {
+    fontSize: 15,
+    color: tokens.colorText,
+    flex: 1,
+  },
+  description: {
+    fontSize: 12,
+    color: tokens.colorTextSecondary,
+    marginTop: 2,
+  },
+  extra: {
+    color: tokens.colorTextSecondary,
+    fontSize: 14,
+  },
+};
+
+export const lineStyle = StyleSheet.create({
+  s: { flex: 1, flexDirection: 'row', alignItems: 'center' },
+}).s;
+
+export const contentWrapStyle = StyleSheet.create({
+  s: { flex: 1 },
+}).s;

package/src/popover/index.md

@@ -0,0 +1,57 @@
+---
+title: Popover
+nav:
+  title: 组件
+  order: 1
+group:
+  title: 基础
+  order: 2
+---
+
+# Popover 弹出定位容器
+
+锚定在指定元素下方的弹出容器，用于下拉菜单等场景。
+
+## 何时使用
+
+- 下拉选择菜单
+- 模型选择器
+- 任何需要锚定定位的浮层
+
+## 代码演示
+
+```tsx
+import { Popover } from '@unif/react-native-ui';
+
+<Popover
+  visible={visible}
+  onClose={() => setVisible(false)}
+  anchorLayout={{ x: 100, y: 50, width: 120, height: 40 }}
+  width={180}
+>
+  <View>
+    <Text>下拉内容</Text>
+  </View>
+</Popover>
+```
+
+## API
+
+| 属性         | 说明           | 类型                                          | 默认值     |
+| ------------ | -------------- | --------------------------------------------- | ---------- |
+| visible      | 是否可见       | `boolean`                                     | -          |
+| onClose      | 关闭回调       | `() => void`                                  | -          |
+| anchorLayout | 锚点布局       | `{ x, y, width, height }`                     | -          |
+| width        | 内容宽度       | `number`                                      | `180`      |
+| placement    | 弹出方向       | `'bottom'` \| `'top'`                         | `'bottom'` |
+| children     | 弹出内容       | `ReactNode`                                   | -          |
+| style        | 内容容器样式   | `ViewStyle`                                   | -          |
+| styles       | 语义样式       | `PopoverSemanticStyles`                       | -          |
+| testID       | 测试标识       | `string`                                      | -          |
+
+## Semantic Styles
+
+| Slot    | 说明         |
+| ------- | ------------ |
+| overlay | 遮罩层       |
+| content | 内容容器     |