Skip to content

Commit b109f54

Browse files
honghuangdchonghuangdc
committed
docs(README): enhance documentation for SoybeanUI and SoybeanHeadless
1 parent b41a90b commit b109f54

File tree

4 files changed

+436
-8
lines changed

4 files changed

+436
-8
lines changed

‎README.md‎

Lines changed: 77 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,59 @@
11
# SoybeanUI
22

3-
SoybeanUI is built on top of SoybeanHeadless, providing a collection of styled components for Vue 3.
3+
English | [中文](./README.zh-CN.md)
44

5-
## Installation
5+
[![license](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
6+
[![github stars](https://img.shields.io/github/stars/soybeanjs/soybean-ui)](https://github.com/soybeanjs/soybean-ui)
7+
8+
SoybeanUI is a modern, high-quality UI component library for Vue 3, built on top of a robust headless foundation. It provides a comprehensive set of accessible, customizable, and performant components.
9+
10+
## 📚 Architecture
11+
12+
SoybeanUI consists of two main packages:
13+
14+
- **@soybeanjs/headless**: The logic layer. It handles state management, accessibility (A11y), keyboard interactions, and focus management. It is completely unstyled, giving you maximum control if you want to build your own design system.
15+
- **@soybeanjs/ui**: The presentation layer. It wraps the headless components with beautiful, customizable styles using UnoCSS (via `tailwind-variants`). It is ready to use out of the box.
16+
17+
## 📦 Installation
18+
19+
### Using the Styled UI Library (Recommended)
20+
21+
If you want ready-to-use components with a modern design:
622

723
```bash
824
pnpm add @soybeanjs/ui
925
```
1026

11-
## Usage
27+
### Using the Headless Library
1228

13-
- import styles
29+
If you want to build your own design system from scratch:
30+
31+
```bash
32+
pnpm add @soybeanjs/headless
33+
```
34+
35+
## 🚀 Usage
36+
37+
### @soybeanjs/ui
38+
39+
1. **Import Styles**
40+
41+
Import the CSS file in your main entry file (e.g., `main.ts`):
1442

1543
```ts
1644
import '@soybeanjs/ui/styles.css';
1745
```
1846

19-
- use with `unplugin-vue-components`
47+
2. **Global Registration (Optional)**
48+
49+
You can register components globally or import them on demand.
50+
51+
3. **On-demand Import (Recommended)**
52+
53+
We recommend using `unplugin-vue-components` for auto-importing components.
2054

2155
```ts
56+
// vite.config.ts
2257
import Components from 'unplugin-vue-components/vite';
2358
import UiResolver from '@soybeanjs/ui/resolver';
2459

@@ -31,7 +66,43 @@ export default defineConfig({
3166
});
3267
```
3368

34-
## Roadmap
69+
4. **Nuxt Module**
70+
71+
```ts
72+
// nuxt.config.ts
73+
export default defineNuxtConfig({
74+
modules: ['@soybeanjs/ui/nuxt']
75+
});
76+
```
77+
78+
### @soybeanjs/headless
79+
80+
The headless components provide the functionality without the styles.
81+
82+
```vue
83+
<script setup>
84+
import { AccordionRoot, AccordionItem, AccordionTrigger, AccordionContent } from '@soybeanjs/headless';
85+
</script>
86+
87+
<template>
88+
<AccordionRoot>
89+
<AccordionItem value="item-1">
90+
<AccordionTrigger>Is it accessible?</AccordionTrigger>
91+
<AccordionContent>Yes. It adheres to the WAI-ARIA design pattern.</AccordionContent>
92+
</AccordionItem>
93+
</AccordionRoot>
94+
</template>
95+
```
96+
97+
## ✨ Features
98+
99+
- **Accessible**: Follows WAI-ARIA patterns for accessibility.
100+
- **Headless**: Logic and styles are separated.
101+
- **Type Safe**: Written in TypeScript with full type support.
102+
- **Customizable**: Built with UnoCSS and `tailwind-variants` for easy theming.
103+
- **Lightweight**: Tree-shakable components.
104+
105+
## 🗺️ Roadmap
35106

36107
### Components
37108

‎README.zh-CN.md‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
# SoybeanUI
2+
3+
[English](./README.md) | 中文
4+
5+
[![license](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
6+
[![github stars](https://img.shields.io/github/stars/soybeanjs/soybean-ui)](https://github.com/soybeanjs/soybean-ui)
7+
8+
SoybeanUI 是一个基于 Vue 3 的现代化、高质量 UI 组件库，构建在强大的 Headless 基础之上。它提供了一套全面、可访问、可定制且高性能的组件。
9+
10+
## 📚 架构
11+
12+
SoybeanUI 由两个主要包组成：
13+
14+
- **@soybeanjs/headless**: 逻辑层。它处理状态管理、可访问性 (A11y)、键盘交互和焦点管理。它完全不包含样式，如果您想构建自己的设计系统，它能为您提供最大的控制权。
15+
- **@soybeanjs/ui**: 表现层。它使用 UnoCSS (通过 `tailwind-variants`) 为 Headless 组件包装了美观、可定制的样式。它开箱即用。
16+
17+
## 📦 安装
18+
19+
### 使用带样式的 UI 库 (推荐)
20+
21+
如果您想要具有现代设计的现成组件：
22+
23+
```bash
24+
pnpm add @soybeanjs/ui
25+
```
26+
27+
### 使用 Headless 库
28+
29+
如果您想从头开始构建自己的设计系统：
30+
31+
```bash
32+
pnpm add @soybeanjs/headless
33+
```
34+
35+
## 🚀 使用方法
36+
37+
### @soybeanjs/ui
38+
39+
1. **引入样式**
40+
41+
在您的主入口文件 (例如 `main.ts`) 中引入 CSS 文件：
42+
43+
```ts
44+
import '@soybeanjs/ui/styles.css';
45+
```
46+
47+
2. **全局注册 (可选)**
48+
49+
您可以全局注册组件，也可以按需引入。
50+
51+
3. **按需引入 (推荐)**
52+
53+
我们推荐使用 `unplugin-vue-components` 来自动引入组件。
54+
55+
```ts
56+
// vite.config.ts
57+
import Components from 'unplugin-vue-components/vite';
58+
import UiResolver from '@soybeanjs/ui/resolver';
59+
60+
export default defineConfig({
61+
plugins: [
62+
Components({
63+
resolvers: [UiResolver()]
64+
})
65+
]
66+
});
67+
```
68+
69+
4. **Nuxt 模块**
70+
71+
```ts
72+
// nuxt.config.ts
73+
export default defineNuxtConfig({
74+
modules: ['@soybeanjs/ui/nuxt']
75+
});
76+
```
77+
78+
### @soybeanjs/headless
79+
80+
Headless 组件提供功能但不包含样式。
81+
82+
```vue
83+
<script setup>
84+
import { AccordionRoot, AccordionItem, AccordionTrigger, AccordionContent } from '@soybeanjs/headless';
85+
</script>
86+
87+
<template>
88+
<AccordionRoot>
89+
<AccordionItem value="item-1">
90+
<AccordionTrigger>Is it accessible?</AccordionTrigger>
91+
<AccordionContent>Yes. It adheres to the WAI-ARIA design pattern.</AccordionContent>
92+
</AccordionItem>
93+
</AccordionRoot>
94+
</template>
95+
```
96+
97+
## ✨ 特性
98+
99+
- **可访问性**: 遵循 WAI-ARIA 模式以实现可访问性。
100+
- **Headless**: 逻辑与样式分离。
101+
- **类型安全**: 使用 TypeScript 编写，提供完整的类型支持。
102+
- **可定制**: 基于 UnoCSS 和 `tailwind-variants` 构建，易于主题化。
103+
- **轻量级**: 支持 Tree-shaking 的组件。
104+
105+
## 🗺️ 路线图
106+
107+
### 组件
108+
109+
✅: 已完成 ✨: 已实现
110+
111+
✅ 46 / 总计: 107
112+
113+
| 序号 | 优先级 | 名称 | 状态 | 别名 | 📝 备注 |
114+
| ---- | ------ | --------------- | ------------ | -------------------- | ------------------------ |
115+
| 1 | 1 | Accordion | ✅ Completed | | |
116+
| 2 | 1 | Alert | ✅ Completed | | |
117+
| 3 | 1 | AlertDialog | ✅ Completed | | |
118+
| 4 | 1 | Arrow | ✅ Completed | | |
119+
| 5 | 1 | AspectRatio | ✅ Completed | | |
120+
| 6 | 1 | Avatar | ✅ Completed | | |
121+
| 7 | 1 | Badge | ✅ Completed | Chip | |
122+
| 8 | 1 | Breadcrumb | ✅ Completed | | |
123+
| 9 | 1 | Button | ✅ Completed | | ✨ support loading |
124+
| 10 | 1 | Card | ✅ Completed | | |
125+
| 11 | 1 | Checkbox | ✅ Completed | | ✨ support checkbox card |
126+
| 12 | 1 | Collapsible | ✅ Completed | | |
127+
| 13 | 1 | Command | ✅ Completed | | |
128+
| 14 | 1 | ConfigProvider | ✅ Completed | | |
129+
| 15 | 1 | ContextMenu | ✅ Completed | | |
130+
| 16 | 1 | Dialog | ✅ Completed | | |
131+
| 17 | 1 | Drawer | ✅ Completed | Sheet | |
132+
| 18 | 1 | DropdownMenu | ✅ Completed | | ✨ support hover trigger |
133+
| 19 | 1 | Form | ✅ Completed | | |
134+
| 20 | 1 | Icon | ✅ Completed | | ✨ based on iconify |
135+
| 21 | 1 | Input | ✅ Completed | | |
136+
| 22 | 1 | Kbd | ✅ Completed | | |
137+
| 23 | 1 | Label | ✅ Completed | | |
138+
| 24 | 1 | Layout | ✅ Completed | | |
139+
| 25 | 1 | Link | ✅ Completed | | |
140+
| 26 | 1 | List | ✅ Completed | | |
141+
| 27 | 1 | Listbox | ✅ Completed | | |
142+
| 28 | 1 | Menu | ✅ Completed | | |
143+
| 29 | 1 | NavigationMenu | ✅ Completed | | |
144+
| 30 | 1 | NumberInput | ✅ Completed | NumberField | |
145+
| 31 | 1 | Pagination | ✅ Completed | | |
146+
| 32 | 1 | Password | ✅ Completed | | |
147+
| 33 | 1 | Popover | ✅ Completed | | |
148+
| 34 | 1 | RadioGroup | ✅ Completed | | ✨ support radio card |
149+
| 35 | 1 | Segment | ✅ Completed | | |
150+
| 36 | 1 | Select | ✅ Completed | | |
151+
| 37 | 1 | Separator | ✅ Completed | Divider | |
152+
| 38 | 1 | Switch | ✅ Completed | | ✨ support switch card |
153+
| 39 | 1 | Tabs | ✅ Completed | | |
154+
| 40 | 1 | Tag | ✅ Completed | Badge(shadcn-ui) | |
155+
| 41 | 1 | Textarea | ✅ Completed | | ✨ support auto size |
156+
| 42 | 1 | Toast | ✅ Completed | Sonner | migrate from vue-sonner |
157+
| 43 | 1 | Tooltip | ✅ Completed | | |
158+
| 44 | 1 | Tree | ✅ Completed | | ✨ support virtualized |
159+
| 45 | 1 | TreeMenu | ✅ Completed | | |
160+
| 46 | 1 | Virtualizer | ✅ Completed | | |
161+
| 47 | 1 | VisuallyHidden | ✅ Completed | | |
162+
| 48 | 2 | ColorPicker | | | |
163+
| 49 | 2 | Combobox | | | support virtualized |
164+
| 50 | 2 | DataTable | | | support virtualized |
165+
| 51 | 2 | Menubar | | | |
166+
| 52 | 2 | PinInput | | InputOPT, OPTInput | |
167+
| 53 | 2 | Popconfirm | | | |
168+
| 54 | 2 | Progress | | | include circle |
169+
| 55 | 2 | ScrollArea | | | |
170+
| 56 | 2 | Skeleton | | | |
171+
| 57 | 2 | Slider | | | |
172+
| 58 | 2 | Table | | | |
173+
| 59 | 2 | Toggle | | | |
174+
| 60 | 2 | ToggleGroup | | | |
175+
| 61 | 3 | BottomSheet | | Drawer(shadcn-ui) | |
176+
| 62 | 3 | Calendar | | | v-calendar |
177+
| 63 | 3 | Carousel | | | |
178+
| 64 | 3 | DateField | | | |
179+
| 65 | 3 | DatePicker | | | |
180+
| 66 | 3 | DateRangeField | | | |
181+
| 67 | 3 | DateRangePicker | | | |
182+
| 68 | 3 | Editable | | | |
183+
| 69 | 3 | HoverCard | | | |
184+
| 70 | 3 | RangeCalendar | | | v-calendar |
185+
| 71 | 3 | Resizable | | | |
186+
| 72 | 3 | Splitter | | | |
187+
| 73 | 3 | Stepper | | | |
188+
| 74 | 3 | TagsInput | | | |
189+
| 75 | 3 | TimeField | | | |
190+
| 76 | 3 | Timeline | | | ui things |
191+
| 77 | 3 | TimePicker | | | element-plus |
192+
| 78 | 3 | Toolbar | | | |
193+
| 79 | 4 | Affix | | | |
194+
| 80 | 4 | Anchor | | | |
195+
| 81 | 4 | AutoComplete | | | support virtualized |
196+
| 82 | 4 | Backtop | | | |
197+
| 83 | 4 | Cascader | | | support virtualized |
198+
| 84 | 4 | Clipboard | | | |
199+
| 85 | 4 | Code | | | |
200+
| 86 | 4 | Comment | | | |
201+
| 87 | 4 | Countdown | | | |
202+
| 88 | 4 | CurrencyInput | | | |
203+
| 89 | 4 | Descriptions | | | |
204+
| 90 | 4 | Ellipsis | | | |
205+
| 91 | 4 | Empty | | | |
206+
| 92 | 4 | Equation | | | based on katex |
207+
| 93 | 4 | InfiniteScroll | | | |
208+
| 94 | 4 | Mention | | | element-plus |
209+
| 95 | 4 | Navbar | | | |
210+
| 96 | 4 | NumberAnimation | | | naive-ui |
211+
| 97 | 4 | PageTab | | | |
212+
| 98 | 4 | QRCode | | | |
213+
| 99 | 4 | Rating | | Rate | element-plus |
214+
| 100 | 4 | Result | | | |
215+
| 101 | 4 | Spinner | | Loader, Spin | github ldrs |
216+
| 102 | 4 | Statistic | | | |
217+
| 103 | 4 | Tour | | | |
218+
| 104 | 4 | Transfer | | | |
219+
| 105 | 4 | TreeSelect | | | |
220+
| 106 | 4 | Typography | | | shadcn-ui |
221+
| 107 | 4 | Upload | | FileUpload, Dropfile | |
222+
| 108 | 4 | Watermark | | | |
223+
224+
### 工具函数
225+
226+
✅ 12 / 总计: 13
227+
228+
| 序号 | 优先级 | 名称 | 状态 | 📝 备注 |
229+
| ---- | ------ | ------------------- | ------------ | -------------- |
230+
| 1 | 1 | Popper | ✅ Completed | |
231+
| 2 | 1 | Portal | ✅ Completed | alias Teleport |
232+
| 3 | 1 | Primitive | ✅ Completed | |
233+
| 4 | 1 | RovingFocus | ✅ Completed | |
234+
| 5 | 1 | Slot | ✅ Completed | |
235+
| 6 | 1 | useCollection | ✅ Completed | |
236+
| 7 | 1 | useDismissableLayer | ✅ Completed | |
237+
| 8 | 1 | useFocusGuards | ✅ Completed | |
238+
| 9 | 1 | useFocusScope | ✅ Completed | |
239+
| 10 | 1 | usePresence | ✅ Completed | |
240+
| 11 | 1 | useDialog | ✅ Completed | |
241+
| 12 | 1 | useToast | ✅ Completed | |
242+
| 13 | 2 | useLoadingBar | | |

0 commit comments

Comments
 (0)