@iquji-web/web-component 0.1.1 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +113 -136
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,136 +1,113 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
##
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
`IqujiDropdownMenu` 的 `items` 接受操作项、分隔线、分组标签和结构化子菜单。操作项支持 `icon`、`label`、`shortcut`、`keyshortcuts`、`disabled`、`tone` 与 `onSelect`;`kind: "submenu"` 用 `items` 递归组合子菜单,旧的 `submenu` 自定义节点仍可用于特殊内容。
|
|
115
|
-
|
|
116
|
-
菜单项至少 40px 高,图标、标签、快捷键和子菜单箭头使用统一样式。`shortcut` 只负责视觉展示,需要读屏快捷键语义时同时提供 `keyshortcuts`。`popupStyle`、`side`、`sideOffset` 和 `ariaLabel` 用于调用方控制弹层位置、宽度和名称;菜单触发器和业务操作仍由应用传入。
|
|
117
|
-
|
|
118
|
-
## 多选
|
|
119
|
-
|
|
120
|
-
`IqujiMultiSelect` 使用受控的 `value`、`onChange`,由调用方提供 `label`、`options`、`placeholder` 和可选文案。选项包含稳定的 `value`、显示用 `label`、可选说明与禁用状态;所有可见文案由应用注入。
|
|
121
|
-
|
|
122
|
-
触发器显示当前选中项的 `label`,浮层内使用 `IqujiPopover`、`IqujiCheckbox` 与 `IqujiInput` 组合。`searchable` 打开本地关键字过滤,`selectAllLabel`、`clearLabel` 分别提供全选与清空操作;禁用项不会被选中,清空只提交空数组。组件不读取应用词典,也不执行业务校验。
|
|
123
|
-
|
|
124
|
-
## 进度条
|
|
125
|
-
|
|
126
|
-
`IqujiProgressBar` 使用 `label`、`value`、`max` 表达确定进度,`max` 必须为正数,越界值在实际渲染时裁剪。`indeterminate` 表达不携带比例的运行中状态;此时不输出 `aria-valuenow`,避免伪造进度。
|
|
127
|
-
|
|
128
|
-
`tone` 支持 `neutral`、`info`、`success`、`warning`、`danger`;`showValue` 与 `formatValue` 控制可见数值,格式由调用方决定。减少动态效果时停止不定动画并保留可读状态。
|
|
129
|
-
|
|
130
|
-
## 时间线
|
|
131
|
-
|
|
132
|
-
`IqujiTimeline` 使用有序列表渲染 `items`,每项提供跨项唯一的 `id`、`title` 和可选的 `description`、`timestamp`、`status`、`icon`、`tone`。组件只负责时间线的结构与语义,不生成任务、审计或业务数据;空数组显示 `emptyLabel`,其中不带操作按钮。
|
|
133
|
-
|
|
134
|
-
## 滚动区域
|
|
135
|
-
|
|
136
|
-
`IqujiScrollArea` 提供带 `role="region"`、`aria-label` 和可聚焦滚动的通用容器。`height`、`maxHeight` 接受数字像素或字符串尺寸;`orientation` 支持 `vertical`、`horizontal` 和 `both`。滚动条、焦点环和 overscroll 行为随正式 CSS 交付,内容与业务滚动语义仍由调用方提供。
|
|
1
|
+
# @iquji-web/web-component
|
|
2
|
+
|
|
3
|
+
简体中文 | [English](README.en.md)
|
|
4
|
+
|
|
5
|
+
Iquji Web 核心 UI 组件库,基于 Base UI 与 WAI-ARIA 规范构建,涵盖常用表单控件、数据展示、导航、反馈通知、浮层对话框、三栏工作台及桌面端应用外壳。
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 安装
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install @iquji-web/web-component @iquji-web/web-theme @iquji-web/web-icons
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
> **注意**:组件库要求消费应用提供 `react`、`react-dom` (>= 19) 及 Base UI 依赖,并显式引入样式:
|
|
16
|
+
> ```tsx
|
|
17
|
+
> import "@iquji-web/web-theme/tokens.css";
|
|
18
|
+
> import "@iquji-web/web-component/styles.css";
|
|
19
|
+
> ```
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## 核心组件分类
|
|
24
|
+
|
|
25
|
+
### 1. 基础与操作 (General)
|
|
26
|
+
- **`IqujiButton` / `IconButton` / `IqujiButtonLink`**:支持 `primary`、`secondary`、`ghost`、`danger` 等语义样式,提供原生 `disabled` 与 `loading` 防重防失焦保护。
|
|
27
|
+
- **`StatusBadge` / `IqujiBadge`**:用于状态标识与数量徽标。
|
|
28
|
+
- **`IqujiEmptyState` / `IqujiLoadingState`**:空白与加载占位视图。
|
|
29
|
+
|
|
30
|
+
### 2. 表单控件 (Forms)
|
|
31
|
+
- **`IqujiField`**:表单字段容器,自动关联 `label`、必填标记、辅助说明、校验错误与 `aria-describedby`。
|
|
32
|
+
- **输入与选择**:`IqujiInput`、`IqujiTextarea`、`IqujiSelect`、`IqujiMultiSelect`、`IqujiCheckbox`、`IqujiRadio`、`IqujiSwitch`、`IqujiSegmentedControl`。
|
|
33
|
+
- **时间与特殊输入**:`IqujiCalendar`、`IqujiDatePicker`、`IqujiColorPicker`、`IqujiEmojiPicker`。
|
|
34
|
+
|
|
35
|
+
### 3. 导航与步骤 (Navigation)
|
|
36
|
+
- **`IqujiTabs`**:下划线或分段按钮样式的标签页切换,支持方向键导航与受控状态。
|
|
37
|
+
- **`IqujiPagination`**:标准受控分页组件。
|
|
38
|
+
- **`IqujiFormSteps`**:清晰的数字步骤导航。
|
|
39
|
+
- **`IqujiSettingsNav`**:设置中心侧边分类导航。
|
|
40
|
+
|
|
41
|
+
### 4. 浮层与对话框 (Overlays)
|
|
42
|
+
- **`IqujiOverlayProvider`**:应用级浮层容器上下文,统筹层级与焦点。
|
|
43
|
+
- **`IqujiDialog` / `IqujiDrawer`**:受控模态弹窗与抽屉,具备优雅的进入/退出动画和焦点管理。
|
|
44
|
+
- **`IqujiConfirmDialog`**:二次确认弹窗,默认安全聚焦取消操作,防止误触危险操作。
|
|
45
|
+
- **`IqujiFormDialog`**:支持居中放大展开的沉浸式表单对话框。
|
|
46
|
+
- **`IqujiSearchDialog`**:跨组过滤、键盘快捷操作的通用全局搜索框。
|
|
47
|
+
- **`IqujiTooltip` / `IqujiPopover` / `IqujiDropdownMenu`**:轻量定位弹出层。
|
|
48
|
+
|
|
49
|
+
### 5. 反馈与通知 (Feedback)
|
|
50
|
+
- **`IqujiNotificationProvider` & `useIqujiNotification`**:全局非阻塞轻量通知,支持自动关闭、同 key 更新、视觉倒计时进度与鼠标悬停暂停。
|
|
51
|
+
- **`IqujiAlert`**:内嵌行内提醒,用于页面级或区块级提示。
|
|
52
|
+
- **`IqujiProgressBar` / `IqujiSkeleton` / `IqujiTimeline`**:进度条、骨架屏与时间线。
|
|
53
|
+
|
|
54
|
+
### 6. 布局与工作台 (Layout & Desktop)
|
|
55
|
+
- **`AppShell`**:经典应用外框与侧栏导航分组。
|
|
56
|
+
- **`IqujiWorkbenchLayout`**:经典三栏自适应工作台(左侧栏、中央主屏、右侧栏,支持折叠与分隔线拖拽)。
|
|
57
|
+
- **`IqujiDesktopShell`**:适用于 Electron / Tauri 的桌面端窗口外壳(支持自定义标题栏、标签条与侧栏)。
|
|
58
|
+
- **`IqujiDataTable` / `IqujiTableFrame`**:统一的数据表格与滚动容器。
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## 快速使用示例
|
|
63
|
+
|
|
64
|
+
```tsx
|
|
65
|
+
import { useState } from "react";
|
|
66
|
+
import {
|
|
67
|
+
IqujiOverlayProvider,
|
|
68
|
+
IqujiButton,
|
|
69
|
+
IqujiDialog,
|
|
70
|
+
IqujiField,
|
|
71
|
+
IqujiInput
|
|
72
|
+
} from "@iquji-web/web-component";
|
|
73
|
+
|
|
74
|
+
export function Example() {
|
|
75
|
+
const [open, setOpen] = useState(false);
|
|
76
|
+
|
|
77
|
+
return (
|
|
78
|
+
<IqujiOverlayProvider>
|
|
79
|
+
<IqujiButton onClick={() => setOpen(true)}>打开对话框</IqujiButton>
|
|
80
|
+
|
|
81
|
+
<IqujiDialog
|
|
82
|
+
open={open}
|
|
83
|
+
onOpenChange={setOpen}
|
|
84
|
+
title="编辑配置"
|
|
85
|
+
description="修改项目的基本设置并保存。"
|
|
86
|
+
closeLabel="关闭"
|
|
87
|
+
actions={
|
|
88
|
+
<>
|
|
89
|
+
<IqujiButton onClick={() => setOpen(false)}>保存</IqujiButton>
|
|
90
|
+
<IqujiButton variant="secondary" onClick={() => setOpen(false)}>取消</IqujiButton>
|
|
91
|
+
</>
|
|
92
|
+
}
|
|
93
|
+
>
|
|
94
|
+
<IqujiField label="项目名称" required>
|
|
95
|
+
<IqujiInput placeholder="输入项目名称" />
|
|
96
|
+
</IqujiField>
|
|
97
|
+
</IqujiDialog>
|
|
98
|
+
</IqujiOverlayProvider>
|
|
99
|
+
);
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## 开发与构建
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
bun install --frozen-lockfile
|
|
109
|
+
bun run build # 编译构建到 dist/
|
|
110
|
+
bun run typecheck # TypeScript 类型校验
|
|
111
|
+
bun run test # 单元测试与无障碍测试
|
|
112
|
+
bun run check # 全量自检
|
|
113
|
+
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@iquji-web/web-component",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.3",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|
|
@@ -24,8 +24,8 @@
|
|
|
24
24
|
"react": "19.2.4"
|
|
25
25
|
},
|
|
26
26
|
"dependencies": {
|
|
27
|
-
"@iquji-web/web-icons": "0.1.
|
|
28
|
-
"@iquji-web/web-theme": "0.1.
|
|
27
|
+
"@iquji-web/web-icons": "0.1.3",
|
|
28
|
+
"@iquji-web/web-theme": "0.1.3",
|
|
29
29
|
"@tanstack/react-table": "8.21.3"
|
|
30
30
|
},
|
|
31
31
|
"description": "React 通用交互组件与布局。",
|