@iquji-web/web-component 0.1.2 → 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.
Files changed (2) hide show
  1. package/README.md +113 -136
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,136 +1,113 @@
1
- # Web component
2
-
3
- `@iquji-web/web-component` 只提供通用 component 能力,JavaScript、类型声明、必要样式及功能测试随源码交付。
4
-
5
- 安装使用本目录锁文件,运行 `bun install --frozen-lockfile` 和 `bun run check`。正式入口只导出 `dist` 中的 JavaScript、类型声明和独立 CSS,不要求消费者编译本包源码。
6
-
7
- JavaScript 构建显式使用生产环境的 JSX runtime,不依赖调用方 shell 的 `NODE_ENV`。自身检查通过正式包出口在独立生产 React 进程中渲染按钮、字段与图标,防止开发 JSX 产物进入生产消费者后白屏。
8
-
9
- ## AppShell 导航
10
-
11
- `AppShell` 可用 `navigationGroups` 将链接按工作区分组。每组提供稳定的 `id`、可见标题和 `items`;组内项目继续使用 `AppNavigationItem` 的链接、图标、禁用和当前页状态。未提供分组时继续显示 `navigation` 平铺项目。侧栏标题使用真实分组标题,调用方不需要伪造分隔链接。
12
-
13
- 运行消费者需提供正式 icons、theme 与 React、Base UI 依赖,显式先导入 `@iquji-web/web-theme/tokens.css`,再导入 `@iquji-web/web-component/styles.css`;组件样式不隐式设置全局主题。当前源码开发的 icons 和 theme 使用相邻已构建工作区,其他叶子不进入本包闭包。
14
-
15
- 正式 component 产物通过精确 dependencies 声明 icons 与 theme;源码工作区使用明确的本地 overrides 定位相邻已构建工作区。这些本地安装映射不替代包消费者自己的正式依赖解析。
16
-
17
- ## 通知与表单
18
-
19
- 应用在 `IqujiOverlayProvider` 内、路由外注册 `IqujiNotificationProvider`,传入 `closeLabel`,可通过 `label` 注入通知区域名称(默认“通知”)。`placement` 支持 `topLeft`、`topRight`、`bottomLeft`、`bottomRight`,默认右上;`duration` 单位为毫秒,默认 5000,`0` 表示常驻;`maxCount` 默认 3,超出时关闭最早的通知。自动关闭通知显示剩余秒数与进度条;悬停、键盘聚焦或窗口失焦期间同步暂停自动关闭与视觉计时,重复 key 更新时重新计时。
20
-
21
- `useIqujiNotification()` 提供 `open({ key?, title, description?, tone?, duration?, actions?, onClose? })` 与 `close(key?)`。`open` 返回通知 key,重复 key 更新内容并重新计时;`tone` 沿用 `info | success | warning | danger`。不传 key 时创建独立通知,`close()` 关闭全部,`close(key)` 关闭指定通知。标题、正文与操作节点由应用提供;成功提交与实际执行结果须由应用准确区分,公共包不请求接口或宣称任务完成。
22
-
23
- 通知以中性浮层、状态图标和关闭按钮呈现,不占据内容布局。打开时不抢焦点,F6 可进入通知区域;在对话框或抽屉打开期间,通知 Portal 跟随顶层浮层,保留键盘操作和可访问边界。操作结果使用通知;字段校验、页面读取失败和需要持续阅读的说明继续使用字段错误或 `IqujiAlert`。
24
-
25
- `IqujiField` 统一标签、必填标记、说明和错误间距,自动连接 `label`、`aria-describedby`、`aria-invalid`。Input、Textarea、Select 和 DatePicker 的中性聚焦描边使用 theme 独立控件变量,不再叠加带间隔的品牌色粗环;错误聚焦保持危险色,禁用与只读状态保留区别,高对比度模式使用系统焦点线。
26
-
27
- ## 操作状态
28
-
29
- `IqujiButton`、`IconButton` 与 `IqujiButtonLink` 的 `disabled`、`loading` 都阻止操作。链接同时尊重 `aria-disabled=true`,禁用时移除 `href`、退出 Tab 顺序并阻止点击及其冒泡;恢复后继续使用原有目标、回调和 Tab 设置。
30
-
31
- 填充的 primary、danger 操作使用 theme 的 `--iquji-color-action-*` 变量,在明暗主题及悬停时保持白色文字或图标。禁用状态使用独立灰色变量,不通过整体透明度或保留红底表达不可用;进入禁用或恢复可用时,前景与底色同时切换,避免颜色过渡产生红底灰字的中间态。
32
-
33
- ## 页签
34
-
35
- `IqujiTabs` 由 `value`、`onChange` 受控,`tabs` 提供 `value`、`label` 和可选的 `disabled`。默认使用下划线样式;`variant="segmented"` 使用按内容收紧的中性灰分段按钮,不把每项撑满整行。两种外观共用 `tablist` / `tab` 语义、选中态和单个可用 Tab 入口,方向键循环切换,Home/End 定位首尾,跳过禁用项,输入法组合期间不切换。
36
-
37
- 调用方通过 `label` 提供页签组名称,`panelId` 指向当前 `tabpanel`。需要建立面板的反向命名时传稳定 `id`,每个页签的正式 ID 为 `${id}-${value}`,面板将 `aria-labelledby` 设为当前页签 ID;未传 `id` 时组件生成唯一 ID。内容面板和数据加载仍由业务管理。
38
-
39
- ## 分页
40
-
41
- `IqujiPagination` 使用唯一的 `page`、`pageSize`、`total` 和 `onPageChange` 合同;页码、页大小必须为正整数,总数为非负整数。边界操作与缺少变更回调的只读操作使用原生禁用状态,空结果保持一页且两端禁用,不查询数据或决定业务筛选。
42
-
43
- 应用注入 `label`、`previousLabel`、`nextLabel` 及可选的 `summary(total, range)`,公共包不读取应用词典。样式随正式 CSS 出口交付,应用无需生成分页配方。
44
-
45
- ## 浮层
46
-
47
- 应用在入口组合 `IqujiOverlayProvider`,通过 `IqujiDialog`、`IqujiDrawer`、`IqujiConfirmDialog`、`IqujiDropdownMenu` 和 `IqujiPopover` 使用同一套 Base UI 浮层。单个 Dialog 或 Drawer 在入口尚未提供 provider 时也有自身边界;需要跨容器排序时应共用应用入口的 provider。
48
-
49
- Dialog 与 Drawer 使用受控的 `open`、`onOpenChange`。请求关闭时调用方可以保留 `open=true`,继续处理草稿或提交保护;实际退出完成才触发一次 `onCloseComplete`。该通知等待 CSS 动画完成、叠层释放及父层焦点管理恢复,不使用固定时长。重开或卸载取消旧轮完成,已打开的新容器不会被旧轮返回焦点打断。
50
-
51
- 关闭完成可用于清理业务会话或恢复业务入口。`destroyOnClose` 决定是否保留内容:Dialog 默认销毁,Drawer 默认保留;保留内容的容器在退出完成后使用正式 `hidden` 与 `display:none`,不会保留可见表面。叠层在退出期间继续维持滚动锁,最后一层退出恢复原有滚动状态。
52
-
53
- 祖先容器保持在仍活动的后代下方,即使祖先在子层退出期间重新打开,也不会抢先取得顶层焦点。Dialog 与 Drawer 均提供 `initialFocusRef`;宿主在关闭完成回调之后才新建或重开父容器时,通过该属性指定本轮初始入口。
54
-
55
- 关闭按钮、标题、说明和操作文字由应用传入。可关闭 Dialog 和所有 Drawer 必须提供 `closeLabel`;`mandatory` Dialog 禁止指针、Escape 和关闭按钮退出。`IqujiConfirmDialog` 的提交、成功和关闭由调用方决定,`confirmLoading` 使用正式禁用状态阻止取消和重复提交。
56
-
57
- `IqujiConfirmDialog` 统一复用 `compact` 布局,默认宽度不超过 420px 和视口的 92%:标题和说明左对齐,关闭按钮在右上,不显示空正文;取消使用满宽 secondary 按钮,危险确认在其下方纵向排列。显式 `size` 或 `width` 仍覆盖默认尺寸,`width` 优先。初始焦点落在取消操作,显式 `initialFocusRef` 可以指定安全入口;`confirmDisabled` 仅禁止确认,仍允许继续编辑,`confirmLoading` 同时禁止取消和重复提交。`additionalActions` 可提供保存、保留草稿等业务决策,标题、说明和附加正文仍由调用方提供。普通 `IqujiDialog` 继续使用原表单宽度。
58
-
59
- Dialog 和 Drawer 的表面 Portal 挂载到 `document.body`,菜单、Popover、Select 进入所属容器的浮层区域;这同时保留嵌套层级、顶层 Escape 与 WebKit 可访问性边界。浮层 CSS 全部随本包交付,消费者无需额外的应用构建配置;应用只保留业务表单组合和响应式布局。
60
-
61
- `IqujiPopover.anchor` 沿 Base UI 接受元素、元素 ref、虚拟矩形或返回锚点的函数,省略时继续围绕触发器定位。触发按钮继续持有打开、关闭和焦点返回语义,定位仍由底座处理。需要按自身尺寸改变展开方向时,调用方可组合 `popupStyle` 的 CSS `translate` 与宽高过渡,并按实际视口约束尺寸。
62
-
63
- `IqujiEmojiPicker.variant` 控制选择器触发按钮的强调程度,沿用 `IqujiButtonVariant`;省略时保留默认 `primary`,资料字段可显式使用 `secondary`。选项与清空操作继续使用原有按钮语义。
64
-
65
- ## 表单对话框与步骤
66
-
67
- `IqujiFormDialog` 复用 `IqujiDialog` 的 Portal、层级、关闭保护和焦点返回,使用受控 `expanded`、`onExpandedChange` 与必填的 `expandLabel`、`collapseLabel`。普通模式居中显示,展开模式保持居中,宽度最多 1000px、高度不超过视口减去 64px,四周至少保留 16px 和圆角;标题与操作区固定,正文独立滚动,背景使用模糊遮罩。展开和收起只改变尺寸,不重建表单、不清空草稿,也不触发关闭。尺寸过渡沿用主题的浮层时长和标准缓动:在提交前后测量实际宽高,连续插值布局尺寸,不缩放文字;中途反向从当前尺寸继续,结束恢复自动高度。减少动态效果偏好直接切换目标尺寸,视口变化和卸载取消旧动画。
68
-
69
- 通用 Dialog 的 `heading` 接受顶部左侧的可视标题或面包屑;提供该插槽时,真实 `title` 仍通过视觉隐藏的 `Dialog.Title` 参与可访问命名。`headerActions` 允许在正式关闭按钮之前组合操作;FormDialog 用它加入展开按钮。`actions` 提供底部业务操作,`onOpenChange(false)` 仍由宿主决定是否允许关闭,不绕过未保存确认。
70
-
71
- `IqujiFormSteps` 用 `label` 命名步骤导航,`steps` 包含 `id`、`label` 与可选的 `description`、`disabled`、`completed`。`completedLabel` 可注入供读屏使用的完成状态文案。`value`、`onChange(id)` 控制当前步骤和导航意图;公共组件不执行业务校验、不自动放行后续步骤。步骤以紧凑数字标记和连接线表示顺序,不套用卡片或整行底色;标签与说明保持整行,窄容器使用导航内部水平滚动,不将文字挤成逐字断行。导航使用有序列表和原生按钮,当前项提供 `aria-current="step"`;方向键、Home/End 移动焦点并跳过禁用项,Enter、Space 和点击才请求切换,输入法组合期间不处理方向键。
72
-
73
- ## 搜索弹窗
74
-
75
- `IqujiSearchDialog` 使用受控的 `open`、`onOpenChange`,由调用方提供 `title`、`placeholder`、`emptyLabel`、`closeLabel`、`groups` 与 `onSelect(id)`。`groups` 是只读数组,每组包含 `id`、`label`、`items`;条目包含跨组唯一的 `id`、`title`,以及可选的 `description`、`keywords`、`metadata`、`icon`、`disabled`。`metadata` 与图标接受 React 节点,组件不生成业务数据或查询接口。
76
-
77
- 输入在标题、说明与关键词中进行不区分大小写的本地子串过滤,空分组不显示。关闭及重新打开清空查询;数据变化后保持仍有效的活动项,否则选择首个可用项,没有可用结果时移除 `aria-activedescendant`。方向键跨组循环跳过禁用项,Home/End 定位首尾,Enter 通知 `onSelect(id)`;输入法组合期间不处理这些快捷键。鼠标选择与键盘共用同一活动项,键盘移动会滚动到该项。
78
-
79
- 选择结果只通知调用方,不自动关闭。可直接导航时由调用方更新 `open=false`;需要草稿确认时保留搜索,待确认后再关闭,使取消确认能返回仍挂载的搜索输入。明确关闭按钮、Escape 和遮罩仍通过 `onOpenChange(false)` 请求关闭。
80
-
81
- 搜索弹窗消费正式 `IqujiDialog` 的层级、Escape、初始输入焦点及关闭后返回入口的合同。Dialog.Title 仍参与可访问命名,视觉只展示输入、分组结果与关闭图标;约 560px 宽的紧凑外观只作用于搜索弹窗,样式随正式 CSS 出口交付。
82
-
83
- ## 桌面壳
84
-
85
- `IqujiDesktopShell` 只提供窗口外框,`windowBar`、`rail` 和内容区都由调用方组合。标准组合是 `IqujiDesktopTitleBar` + `IqujiDesktopTabStrip`、`IqujiDesktopRail` 和 `IqujiDesktopAccount`,业务内容放在 `children`。所有文案、图标、标签、账户数据、菜单项与回调都由调用方传入。
86
-
87
- `IqujiDesktopTitleBar` 不渲染红黄绿窗口按钮,也不判断运行平台:
88
-
89
- - 纯网页不传 `windowControls`,标题栏从导航操作开始;
90
- - Electron 或自绘窗口按钮通过 `windowControls` 传入,并用 `windowControlsPlacement` 决定放在起始或结束侧;
91
- - Tauri 等由系统覆盖绘制控件时,用 `windowControlsSpace` 预留起始或结束空间;
92
- - Electron 拖拽区传 `dragRegion`,Tauri 的 `data-tauri-drag-region` 直接作为标题栏属性传入;两者都不影响纯网页。
93
-
94
- `IqujiDesktopTabStrip` 使用 `activeTabId`、`onActiveTabChange`、`onTabClose`、`onTabAdd` 驱动标签切换、关闭和新增,支持方向键、Home/End、Delete、dirty 标记和关闭按钮文案。关闭按钮与标签选择按钮是兄弟节点,避免按钮嵌套。`IqujiDesktopRail` 的每个图标项提供 `label` 作为无障碍名称,`tooltip` 作为悬浮提示;激活项使用 `aria-current="page"`。`IqujiDesktopAccount` 复用 `IqujiPopover` 承载账户卡,`usage` 输出可访问的进度条,`sections` 定义分组操作、快捷键和危险/禁用状态。
95
-
96
- `IqujiDesktopRail.showDivider` 默认是 `true`,保留图标栏与内容区之间的贯穿分隔线。调用方可传 `false` 隐藏这条线;切换时保留图标栏宽度、导航交互和无障碍语义,不影响工作台内部的拖拽分隔条。
97
-
98
- ## 三栏工作台
99
-
100
- `IqujiWorkbenchLayout` 的 `center` 必填且始终渲染,`left`、`right` 不传即不显示;`leftCollapsed`、`rightCollapsed` 由调用方控制。折叠时内容保留挂载,但使用 `inert` 和 `aria-hidden` 退出交互与辅助技术树,宽度归零并隐藏分隔条。
101
-
102
- 布局使用三列 grid:左右轨道为 `minmax(0, width)`,中心轨道为 `minmax(centerMinWidth, 1fr)`,空间不足时先压缩两侧,中心仍保持最小宽度。左右分隔条支持指针拖拽、方向键/Home/End、双击恢复默认宽度,并使用 `role="separator"` 与正式 ARIA 数值。`leftWidth`/`rightWidth` 支持受控和非受控;调用方需要本地化分隔条名称时传 `leftResizeLabel`、`rightResizeLabel`。
103
-
104
- `onLayoutChange` 接收 `IqujiWorkbenchGeometry`,报告实际渲染的 `leftWidth`、`centerWidth` 和 `rightWidth`,用于让窗口顶栏等外部区域跟随分栏边界。首次挂载、折叠与实际尺寸变化时测量,宽度相同不重复通知;缺失或折叠的侧栏报告 `0`。实际宽度通过 `ResizeObserver` 跟踪,不修改 `leftWidth`/`rightWidth` 的用户设定,也不触发其宽度调整回调。
105
-
106
- ## 设置页
107
-
108
- `IqujiSettingsLayout` 只负责导航与内容的双栏关系,`IqujiSettingsNav` 的 `groups`、活动项、图标和搜索值都由调用方定义。搜索是受控输入,只上报字符串,不替调用方过滤数据;`emptyLabel` 用于调用方完成过滤后的空结果。
109
-
110
- `IqujiSettingsContent`、`IqujiSettingsSection` 提供页面标题、分区标题和带分隔线的行容器。`IqujiSettingsRow` 是通用标题/说明/控件行;`IqujiSettingsSwitchRow` 复用 `IqujiSwitch` 并让整行可点击;`IqujiSettingsSelectRow` 复用 `IqujiSelect` 并把行标题与说明接到 `aria-labelledby`/`aria-describedby`;`IqujiSettingsActionRow` 用于值或路径加操作按钮。业务字段、选中状态和保存行为留在应用。
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.2",
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.2",
28
- "@iquji-web/web-theme": "0.1.2",
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 通用交互组件与布局。",