react-native-directional-toggle 0.1.0 → 0.1.2

package/README.en.md

@@ -1,65 +1,265 @@
-# Description
+# react-native-directional-toggle
 
-This is a React Native / Expo component library.
+<p align="center">
+  <a href="https://www.npmjs.com/package/react-native-directional-toggle">
+    <img src="https://img.shields.io/npm/v/react-native-directional-toggle.svg?style=for-the-badge" alt="NPM Version" />
+  </a>
+  <a href="https://github.com/alansuhe/react-native-directional-toggle/actions/workflows/ci.yml">
+    <img src="https://img.shields.io/github/actions/workflow/status/alansuhe/react-native-directional-toggle/ci.yml?branch=main&style=for-the-badge" alt="CI Status" />
+  </a>
+  <a href="https://github.com/alansuhe/react-native-directional-toggle/blob/main/LICENSE">
+    <img src="https://img.shields.io/npm/l/react-native-directional-toggle.svg?style=for-the-badge" alt="License" />
+  </a>
+  <a href="https://www.npmjs.com/package/react-native-directional-toggle">
+    <img src="https://img.shields.io/npm/dm/react-native-directional-toggle.svg?style=for-the-badge" alt="NPM Downloads" />
+  </a>
+</p>
 
-For Chinese version, please click: [中文](README.md).
+<p align="center">
+  <b>Multi-Element Toggle Component</b><br/>
+  A multi-option toggle switch component for React Native and Expo with support for horizontal and vertical layouts and smooth animations.
+</p>
 
-## Installation
+<p align="center">
+  English | <a href="./README.md">中文</a>
+</p>
+
+---
+
+## ✨ Features
+
+- 🎯 **Multi-Option Support** - Toggle between two or more options
+- 📱 **Bidirectional Layout** - Support for horizontal and vertical layouts
+- 🎨 **Highly Customizable** - Customize styles, colors, and text styles
+- ⚡ **Smooth Animations** - High-performance animations powered by Reanimated
+- 👆 **Gesture Support** - Support for tap and swipe gestures
+- 🔧 **TypeScript** - Complete TypeScript type support
+- 📦 **Lightweight** - Zero dependencies (except peer dependencies)
+- 🚀 **Expo Compatible** - Works with Expo projects
+
+## 📦 Installation
+
+### Using npm
 
 ```bash
-pnpm add react-native-directional-toggle
+npm install react-native-directional-toggle
+```
 
+### Using yarn
+
+```bash
 yarn add react-native-directional-toggle
 ```
 
-## Peer Dependencies
+### Using pnpm
 
 ```bash
-pnpm add react-native-gesture-handler react-native-reanimated react-native-worklets --save-peer
+pnpm add react-native-directional-toggle
 ```
 
-Dependencies required:
-- react-native-gesture-handler
-- react-native-reanimated
-- react-native-worklets
+### Install Peer Dependencies
 
-Note: Only works with `expo run` after prebuild, not supported by `expo go`.
+This component relies on the following peer dependencies. Please ensure they are installed:
 
-## Usage
+```bash
+# npm
+npm install react-native-gesture-handler react-native-reanimated react-native-worklets
+
+# yarn
+yarn add react-native-gesture-handler react-native-reanimated react-native-worklets
+
+# pnpm
+pnpm add react-native-gesture-handler react-native-reanimated react-native-worklets
+```
 
-> Refer to the [example project](example/).
+**Note:**
 
-### Import and use
+- Expo projects require `expo prebuild` and `expo run`, not supported in Expo Go
+- You need to wrap your app with `GestureHandlerRootView`
+
+## 🚀 Usage
+
+### Basic Usage
 
 ```tsx
 import { GestureHandlerRootView } from 'react-native-gesture-handler';
 import Switcher from 'react-native-directional-toggle';
 
 const options = [
-  {
-    label: 'Option 1',
-    value: 'Option 1',
-  },
-  {
-    label: 'Option 2',
-    value: 'Option 2',
-  },
-  {
-    label: 'Option 3',
-    value: 'Option 3',
-  },
+  { label: 'Option 1', value: 'Option 1' },
+  { label: 'Option 2', value: 'Option 2' },
+  { label: 'Option 3', value: 'Option 3' },
 ];
 
-...
+function App() {
+  const [value, setValue] = useState('Option 2');
+
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      {/* Horizontal mode: specify width and height */}
+      <Switcher
+        options={options}
+        value={value}
+        onChange={setValue}
+        style={{ width: 300, height: 40, backgroundColor: '#f2f2f2' }}
+        thumbStyle={{ backgroundColor: '#fff', elevation: 3 }}
+      />
+    </GestureHandlerRootView>
+  );
+}
+```
 
-<GestureHandlerRootView>
-    <Switcher
-            options={options}
-            value={'Option 2'}
-            height={36}
-            onChange={value => console.log(value)}
-    />
-</GestureHandlerRootView>
+### Vertical Mode
 
+```tsx
+import { View } from 'react-native';
+
+// Vertical mode: adapts to parent container height
+<View style={{ height: 200, width: 60 }}>
+  <Switcher
+    vertical
+    options={options}
+    value={value}
+    onChange={setValue}
+    style={{ flex: 1 }}
+  />
+</View>;
 ```
-Note: You need to wrap the outer layer of your App (such as _layout.tsx, etc.) with `GestureHandlerRootView`.
+
+### Custom Styles
+
+```tsx
+<Switcher
+  options={[
+    { label: 'Day', value: 'day' },
+    { label: 'Week', value: 'week' },
+    { label: 'Month', value: 'month' },
+  ]}
+  value={value}
+  onChange={setValue}
+  style={{
+    width: 240,
+    height: 44,
+    backgroundColor: '#e8e8e8',
+    borderRadius: 22,
+    padding: 3,
+  }}
+  thumbStyle={{
+    backgroundColor: '#fff',
+    borderRadius: 20,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.1,
+    shadowRadius: 4,
+    elevation: 3,
+  }}
+  textStyle={{
+    fontSize: 14,
+    fontWeight: '600',
+  }}
+  activeTextStyle={{
+    color: '#007AFF',
+  }}
+  inactiveTextStyle={{
+    color: '#666',
+  }}
+/>
+```
+
+## 📖 API Documentation
+
+### Props
+
+| Prop                | Type                                   | Required | Default             | Description                                            |
+| ------------------- | -------------------------------------- | -------- | ------------------- | ------------------------------------------------------ |
+| `options`           | `Option[]`                             | ✅       | -                   | List of options, each with `label` and `value`         |
+| `value`             | `string \| number`                     | ✅       | -                   | Currently selected value                               |
+| `onChange`          | `(value: string \| number) => void`    | ✅       | -                   | Callback when value changes                            |
+| `vertical`          | `boolean`                              | ❌       | `false`             | Whether to use vertical layout                         |
+| `style`             | `StyleProp<ViewStyle>`                 | ❌       | -                   | Container style for width, height, background, etc.    |
+| `thumbStyle`        | `StyleProp<ViewStyle>`                 | ❌       | -                   | Style for the sliding thumb (selected item background) |
+| `textStyle`         | `StyleProp<TextStyle>`                 | ❌       | -                   | Default style for option text                          |
+| `activeTextStyle`   | `StyleProp<TextStyle>`                 | ❌       | -                   | Text style when active/selected                        |
+| `inactiveTextStyle` | `StyleProp<TextStyle>`                 | ❌       | -                   | Text style when inactive                               |
+| `animationConfig`   | `WithTimingConfig \| WithSpringConfig` | ❌       | `{ duration: 150 }` | Animation configuration                                |
+
+### Type Definitions
+
+```typescript
+type Option = {
+  label: string;
+  value: string | number;
+};
+
+type AnimatedSwitchProps = {
+  options: Option[];
+  value: string | number;
+  onChange: (value: string | number) => void;
+  vertical?: boolean;
+  style?: StyleProp<ViewStyle>;
+  thumbStyle?: StyleProp<ViewStyle>;
+  textStyle?: StyleProp<TextStyle>;
+  activeTextStyle?: StyleProp<TextStyle>;
+  inactiveTextStyle?: StyleProp<TextStyle>;
+  animationConfig?: WithTimingConfig | WithSpringConfig;
+};
+```
+
+### Animation Configuration
+
+Customize animations via `animationConfig`:
+
+```tsx
+// Using timing animation
+<Switcher
+  animationConfig={{
+    duration: 200, // Animation duration in milliseconds
+  }}
+/>
+
+// Using spring animation
+<Switcher
+  animationConfig={{
+    damping: 15,    // Damping coefficient
+    stiffness: 150, // Stiffness
+    mass: 1,        // Mass
+  }}
+/>
+```
+
+## 📱 Example
+
+Check the [example](example/) directory for a complete example project.
+
+```bash
+# Clone the repository
+git clone https://github.com/alansuhe/react-native-directional-toggle.git
+
+# Navigate to the example directory
+cd react-native-directional-toggle/example
+
+# Install dependencies
+pnpm install
+
+# Run on iOS
+pnpm ios
+
+# Run on Android
+pnpm android
+```
+
+## 🤝 Contributing
+
+Issues and Pull Requests are welcome!
+
+Please read our [Contributing Guide](./CONTRIBUTING.md) for more information.
+
+## 📄 License
+
+[MIT](./LICENSE) © [Alan Suhe](https://github.com/alansuhe)
+
+---
+
+<p align="center">
+  If this project helped you, please give it a ⭐️
+</p>

package/README.md

@@ -1,65 +1,265 @@
-# 说明
+# react-native-directional-toggle
 
-这是一个 React Native / Expo 组件库。
+<p align="center">
+  <a href="https://www.npmjs.com/package/react-native-directional-toggle">
+    <img src="https://img.shields.io/npm/v/react-native-directional-toggle.svg?style=for-the-badge" alt="NPM Version" />
+  </a>
+  <a href="https://github.com/alansuhe/react-native-directional-toggle/actions/workflows/ci.yml">
+    <img src="https://img.shields.io/github/actions/workflow/status/alansuhe/react-native-directional-toggle/ci.yml?branch=main&style=for-the-badge" alt="CI Status" />
+  </a>
+  <a href="https://github.com/alansuhe/react-native-directional-toggle/blob/main/LICENSE">
+    <img src="https://img.shields.io/npm/l/react-native-directional-toggle.svg?style=for-the-badge" alt="License" />
+  </a>
+  <a href="https://www.npmjs.com/package/react-native-directional-toggle">
+    <img src="https://img.shields.io/npm/dm/react-native-directional-toggle.svg?style=for-the-badge" alt="NPM Downloads" />
+  </a>
+</p>
 
-For English version, please click: [English](README.en.md)。
+<p align="center">
+  <b>多元素切换组件</b><br/>
+  支持 React Native 和 Expo 的多选项切换开关组件，支持横向和纵向布局及流畅动画。
+</p>
 
-## 安装
+<p align="center">
+  <a href="./README.en.md">English</a> | 中文
+</p>
+
+---
+
+## ✨ 特性
+
+- 🎯 **多选项支持** - 支持两个或更多选项的切换
+- 📱 **双方向布局** - 支持横向（horizontal）和纵向（vertical）布局
+- 🎨 **高度可定制** - 自定义样式、颜色、文字样式
+- ⚡ **流畅动画** - 基于 Reanimated 的高性能动画
+- 👆 **手势支持** - 支持点击和滑动手势
+- 🔧 **TypeScript** - 完整的 TypeScript 类型支持
+- 📦 **轻量级** - 零依赖（peer dependencies 除外）
+- 🚀 **Expo 支持** - 兼容 Expo 项目
+
+## 📦 安装
+
+### 使用 npm
 
 ```bash
-pnpm add react-native-directional-toggle
+npm install react-native-directional-toggle
+```
 
+### 使用 yarn
+
+```bash
 yarn add react-native-directional-toggle
 ```
 
-## 依赖包
+### 使用 pnpm
 
 ```bash
-pnpm add react-native-gesture-handler react-native-reanimated react-native-worklets --save-peer
+pnpm add react-native-directional-toggle
 ```
 
-需要安装的依赖包：
-- react-native-gesture-handler
-- react-native-reanimated
-- react-native-worklets
+### 安装 peer dependencies
 
-注意：只能在prebuild后正常用`expo run`的方式运行，不支持expo go。
+本组件依赖以下 peer dependencies，请确保已安装：
 
-## 使用
+```bash
+# npm
+npm install react-native-gesture-handler react-native-reanimated react-native-worklets
+
+# yarn
+yarn add react-native-gesture-handler react-native-reanimated react-native-worklets
+
+# pnpm
+pnpm add react-native-gesture-handler react-native-reanimated react-native-worklets
+```
 
-> 参考[示例项目](example/)。
+**注意：**
 
-###  导入组件使用
+- Expo 项目需要使用 `expo prebuild` 后通过 `expo run` 运行，不支持 Expo Go
+- 需要在应用外层包裹 `GestureHandlerRootView`
+
+## 🚀 使用
+
+### 基础用法
 
 ```tsx
 import { GestureHandlerRootView } from 'react-native-gesture-handler';
 import Switcher from 'react-native-directional-toggle';
 
 const options = [
-  {
-    label: 'Option 1',
-    value: 'Option 1',
-  },
-  {
-    label: 'Option 2',
-    value: 'Option 2',
-  },
-  {
-    label: 'Option 3',
-    value: 'Option 3',
-  },
+  { label: 'Option 1', value: 'Option 1' },
+  { label: 'Option 2', value: 'Option 2' },
+  { label: 'Option 3', value: 'Option 3' },
 ];
 
-...
+function App() {
+  const [value, setValue] = useState('Option 2');
+
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      {/* 横向模式：指定宽度和高度 */}
+      <Switcher
+        options={options}
+        value={value}
+        onChange={setValue}
+        style={{ width: 300, height: 40, backgroundColor: '#f2f2f2' }}
+        thumbStyle={{ backgroundColor: '#fff', elevation: 3 }}
+      />
+    </GestureHandlerRootView>
+  );
+}
+```
 
-<GestureHandlerRootView>
-    <Switcher
-            options={options}
-            value={'Option 2'}
-            height={36}
-            onChange={value => console.log(value)}
-    />
-</GestureHandlerRootView>
+### 纵向模式
 
+```tsx
+import { View } from 'react-native';
+
+// 纵向模式：自适应父容器高度
+<View style={{ height: 200, width: 60 }}>
+  <Switcher
+    vertical
+    options={options}
+    value={value}
+    onChange={setValue}
+    style={{ flex: 1 }}
+  />
+</View>;
 ```
-注意: App中需要在外层（如_layout.tsx等）包裹GestureHandlerRootView。
+
+### 自定义样式
+
+```tsx
+<Switcher
+  options={[
+    { label: '日', value: 'day' },
+    { label: '周', value: 'week' },
+    { label: '月', value: 'month' },
+  ]}
+  value={value}
+  onChange={setValue}
+  style={{
+    width: 240,
+    height: 44,
+    backgroundColor: '#e8e8e8',
+    borderRadius: 22,
+    padding: 3,
+  }}
+  thumbStyle={{
+    backgroundColor: '#fff',
+    borderRadius: 20,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.1,
+    shadowRadius: 4,
+    elevation: 3,
+  }}
+  textStyle={{
+    fontSize: 14,
+    fontWeight: '600',
+  }}
+  activeTextStyle={{
+    color: '#007AFF',
+  }}
+  inactiveTextStyle={{
+    color: '#666',
+  }}
+/>
+```
+
+## 📖 API 文档
+
+### Props
+
+| 属性                | 类型                                   | 必填 | 默认值              | 描述                                      |
+| ------------------- | -------------------------------------- | ---- | ------------------- | ----------------------------------------- |
+| `options`           | `Option[]`                             | ✅   | -                   | 选项列表，每个选项包含 `label` 和 `value` |
+| `value`             | `string \| number`                     | ✅   | -                   | 当前选中的值                              |
+| `onChange`          | `(value: string \| number) => void`    | ✅   | -                   | 值改变时的回调函数                        |
+| `vertical`          | `boolean`                              | ❌   | `false`             | 是否为纵向布局                            |
+| `style`             | `StyleProp<ViewStyle>`                 | ❌   | -                   | 容器样式，用于设置宽度、高度、背景色等    |
+| `thumbStyle`        | `StyleProp<ViewStyle>`                 | ❌   | -                   | 滑块（选中项背景）样式                    |
+| `textStyle`         | `StyleProp<TextStyle>`                 | ❌   | -                   | 选项文字的默认样式                        |
+| `activeTextStyle`   | `StyleProp<TextStyle>`                 | ❌   | -                   | 选中状态的文字样式                        |
+| `inactiveTextStyle` | `StyleProp<TextStyle>`                 | ❌   | -                   | 未选中状态的文字样式                      |
+| `animationConfig`   | `WithTimingConfig \| WithSpringConfig` | ❌   | `{ duration: 150 }` | 动画配置                                  |
+
+### 类型定义
+
+```typescript
+type Option = {
+  label: string;
+  value: string | number;
+};
+
+type AnimatedSwitchProps = {
+  options: Option[];
+  value: string | number;
+  onChange: (value: string | number) => void;
+  vertical?: boolean;
+  style?: StyleProp<ViewStyle>;
+  thumbStyle?: StyleProp<ViewStyle>;
+  textStyle?: StyleProp<TextStyle>;
+  activeTextStyle?: StyleProp<TextStyle>;
+  inactiveTextStyle?: StyleProp<TextStyle>;
+  animationConfig?: WithTimingConfig | WithSpringConfig;
+};
+```
+
+### 动画配置
+
+可以通过 `animationConfig` 自定义动画效果：
+
+```tsx
+// 使用 timing 动画
+<Switcher
+  animationConfig={{
+    duration: 200, // 动画时长（毫秒）
+  }}
+/>
+
+// 使用 spring 动画
+<Switcher
+  animationConfig={{
+    damping: 15,    // 阻尼系数
+    stiffness: 150, // 刚度
+    mass: 1,        // 质量
+  }}
+/>
+```
+
+## 📱 示例
+
+查看 [example](example/) 目录获取完整的示例项目。
+
+```bash
+# 克隆仓库
+git clone https://github.com/alansuhe/react-native-directional-toggle.git
+
+# 进入示例目录
+cd react-native-directional-toggle/example
+
+# 安装依赖
+pnpm install
+
+# 运行 iOS
+pnpm ios
+
+# 运行 Android
+pnpm android
+```
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+请阅读我们的[贡献指南](./CONTRIBUTING.md)了解详细信息。
+
+## 📄 许可证
+
+[MIT](./LICENSE) © [Alan Suhe](https://github.com/alansuhe)
+
+---
+
+<p align="center">
+  如果这个项目对您有帮助，请给它一个 ⭐️
+</p>