@hamsterbase/ui 0.1.0 → 0.3.0
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/dist/components/Button/Button.d.ts +5 -3
- package/dist/components/Button/styles.d.ts +3 -3
- package/dist/components/Checkbox/Checkbox.d.ts +3 -3
- package/dist/components/Divider/Divider.d.ts +10 -6
- package/dist/components/Divider/styles.d.ts +8 -4
- package/dist/components/IconButton/IconButton.d.ts +7 -7
- package/dist/components/IconButton/styles.d.ts +3 -3
- package/dist/components/ResizeHandle/ResizeHandle.d.ts +7 -4
- package/dist/components/ResizeHandle/styles.d.ts +6 -4
- package/dist/components/Select/Select.d.ts +17 -0
- package/dist/components/Select/layout.d.ts +39 -0
- package/dist/components/Select/styles.d.ts +26 -0
- package/dist/components/Select/useScrollAffordance.d.ts +12 -0
- package/dist/components/Select/useSelectValue.d.ts +15 -0
- package/dist/components/Toast/Toast.d.ts +17 -0
- package/dist/components/Toast/ToastStore.d.ts +33 -0
- package/dist/components/Toast/Toaster.d.ts +7 -0
- package/dist/components/Toast/styles.d.ts +15 -0
- package/dist/components/Tooltip/Tooltip.d.ts +10 -0
- package/dist/components/Tooltip/coordinator.d.ts +79 -0
- package/dist/components/Tooltip/layout.d.ts +28 -0
- package/dist/components/Tooltip/styles.d.ts +6 -0
- package/dist/index.d.ts +13 -3
- package/dist/index.js +1265 -58
- package/dist/styles.css +776 -115
- package/dist/utils/css.d.ts +6 -0
- package/dist/utils/focus.d.ts +4 -0
- package/docs/Checkbox.md +2 -0
- package/docs/IconButton.md +1 -1
- package/docs/ResizeHandle.md +2 -1
- package/docs/Select.md +20 -0
- package/docs/Toast.md +60 -0
- package/docs/Tooltip.md +20 -0
- package/docs/index.md +3 -0
- package/package.json +10 -8
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
/** CSS 变量的计算值(去除首尾空白)。 */
|
|
2
|
+
export declare function cssValue(element: Element, name: string): string;
|
|
3
|
+
/** 以 px 表示的 CSS 变量的数值。 */
|
|
4
|
+
export declare function cssPx(element: Element, name: string): number;
|
|
5
|
+
/** CSS 变量里的时长(ms 或 s),返回毫秒;读不到时为 0。 */
|
|
6
|
+
export declare function cssMs(element: Element, name: string): number;
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
/** 元素自身获得键盘焦点时。 */
|
|
2
|
+
export declare const focusRing = "focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-hub-focus-ring";
|
|
3
|
+
/** 前一个兄弟节点(peer,如隐藏的原生 input)获得键盘焦点时。 */
|
|
4
|
+
export declare const peerFocusRing = "peer-focus-visible:outline-2 peer-focus-visible:outline-solid peer-focus-visible:outline-offset-2 peer-focus-visible:outline-hub-focus-ring";
|
package/docs/Checkbox.md
CHANGED
package/docs/IconButton.md
CHANGED
|
@@ -2,6 +2,6 @@
|
|
|
2
2
|
|
|
3
3
|
| 属性 | 类型 | 默认值 | 说明 |
|
|
4
4
|
| --- | --- | --- | --- |
|
|
5
|
-
| variant | `'
|
|
5
|
+
| variant | `'surface' \| 'ghost'` | `'surface'` | surface 带描边与轻阴影;ghost 透明、无边框,与 Button 的 ghost 含义一致。 |
|
|
6
6
|
| size | `'sm' \| 'md' \| 'lg'` | `'md'` | 按钮尺寸分别为 24、28、32px;内部 SVG 尺寸分别为 14、14、16px。 |
|
|
7
7
|
| pressed | `boolean` | `undefined` | 受控选中状态,内部映射为 `aria-pressed`。不传时为普通按钮;点击不会自动修改状态。 |
|
package/docs/ResizeHandle.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
受控面板调宽手柄,组合 Divider 显示边界。放在具有定位的面板内,由调用方把 value 应用到面板宽度并处理持久化。保留 7px 拖拽热区、半像素边界与跟随指针的渐变反馈。
|
|
4
4
|
|
|
5
|
-
支持原生 div 展示属性和 ref;交互事件由组件管理。label 和 controls 分别提供可访问名称和受控面板 id
|
|
5
|
+
支持原生 div 展示属性和 ref;交互事件由组件管理。label 和 controls 分别提供可访问名称和受控面板 id。←/→ 按 step 移动边界,Home/End 调至最小/最大值;提供 defaultValue 后可双击复位。所有交互输出都限制在 min/max 范围内。调用方应保证 min ≤ value ≤ max。
|
|
6
6
|
|
|
7
7
|
| 属性 | 类型 | 默认值 | 说明 |
|
|
8
8
|
| --- | --- | --- | --- |
|
|
@@ -13,6 +13,7 @@
|
|
|
13
13
|
| max | `number` | 必填 | 最大宽度。 |
|
|
14
14
|
| onChange | `(value: number) => void` | 必填 | 宽度变化回调。 |
|
|
15
15
|
| defaultValue | `number` | — | 双击复位宽度;不提供时不复位,不代表非受控初值。 |
|
|
16
|
+
| step | `number` | `16` | 每次按 ←/→ 移动的像素数。方向键移动的是边界:`edge='left'` 时按 → 宽度减小。 |
|
|
16
17
|
| showDivider | `boolean` | `true` | 是否显示静态分隔线,隐藏时仍保留交互反馈。 |
|
|
17
18
|
| inset | `number` | `0` | 手柄上下内缩像素数。 |
|
|
18
19
|
| edge | `'left' \| 'right'` | `'right'` | 面板的可拖动边界;左边界向左移动时增大宽度。 |
|
package/docs/Select.md
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Select
|
|
2
|
+
|
|
3
|
+
| 属性 | 类型 | 默认值 | 说明 |
|
|
4
|
+
| --- | --- | --- | --- |
|
|
5
|
+
| options | `readonly SelectOption[]` | 必填 | 每项包含唯一 `value`、显示用 `label`,可选 `icon` 和 `disabled`。 |
|
|
6
|
+
| value | `string` | — | 受控值,勾选标记仅表示该值。 |
|
|
7
|
+
| defaultValue | `string` | `''` | 非受控初值。 |
|
|
8
|
+
| onValueChange | `(value: string) => void` | — | 点击或 Enter/Space 确认不同值时触发,移动高亮不触发。 |
|
|
9
|
+
| size | `'small' \| 'default'` | `'default'` | 小号触发器/选项高 24px、字号 12px;默认触发器高 30px、选项高 32px、字号 13px。 |
|
|
10
|
+
| placeholder | `string` | `'请选择'` | 无匹配选项时显示。 |
|
|
11
|
+
|
|
12
|
+
使用 `aria-label` 或 `aria-labelledby` 提供可访问名称。`name` 会提交隐藏表单字段,禁用时不提交;`form` 属性同样作用于该字段。所属表单重置时,非受控值恢复为 `defaultValue`。`className` 用于触发器。
|
|
13
|
+
|
|
14
|
+
菜单在浏览器 top layer 中显示,不受父级 overflow 裁剪,保留祖先的主题 token。
|
|
15
|
+
|
|
16
|
+
打开时高亮当前值。勾选与高亮独立:鼠标移动、上下方向键和 Home/End 改变高亮(不支持输入字符搜索),Enter/Space 才提交;Escape 取消并返回触发器;Tab 移到下一个控件;点击外部关闭。禁用选项不能被选择,键盘会跳过。菜单关闭时只响应打开菜单的按键,Escape 等其他按键照常冒泡给宿主(例如关闭外层对话框)。
|
|
17
|
+
|
|
18
|
+
默认将当前行与触发器对齐。部分超出视口时裁剪菜单并滚动至当前项,边缘以渐隐和箭头提示,悬停箭头连续滚动;当触发器贴近屏幕边缘、无法容纳当前行与滚动提示时,改为下方或上方展开。长列表限制高度并支持滚轮;滚动/窗口尺寸变化时关闭,避免脱离触发器。
|
|
19
|
+
|
|
20
|
+
示例的静态截图与示例脚本截图(含各种定位的展开状态)由 `component-docs` 采集。`playground/tests/e2e/select.spec.ts` 在 `tests/e2e/fixture/select/` 的页面上验证本文描述的交互(直接渲染文档示例),测试代码上报 Evidra `component-e2e-docs`,截图作为附带观察。新增基线需人工审核,测试不自动审批。
|
package/docs/Toast.md
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Toast
|
|
2
|
+
|
|
3
|
+
轻提示。包含三部分:`ToastStore` 保存状态,`Toaster` 订阅并渲染到右下角,`Toast` 是单张卡片。应用通常只创建一个 `ToastStore`,在根节点放一个 `Toaster`。
|
|
4
|
+
|
|
5
|
+
```tsx
|
|
6
|
+
const toasts = new ToastStore();
|
|
7
|
+
|
|
8
|
+
<Toaster store={toasts} closeLabel="关闭" aria-label="通知" />;
|
|
9
|
+
|
|
10
|
+
toasts.show({ message: '已复制', variant: 'success' });
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## ToastStore
|
|
14
|
+
|
|
15
|
+
不依赖 React 的状态容器。
|
|
16
|
+
|
|
17
|
+
| 成员 | 类型 | 说明 |
|
|
18
|
+
| --- | --- | --- |
|
|
19
|
+
| constructor | `(options?: { max?: number })` | `max` 为同时展示的最大条数,默认 `1`;超出时移除最早的一条。 |
|
|
20
|
+
| show | `(options: ToastOptions) => string` | 显示一条提示并返回 id。`message`、`description`、`variant` 都相同且双方都没有 `action` 时,不新增,而是刷新已有提示的计时并强调。 |
|
|
21
|
+
| dismiss | `(id?: string) => void` | 立即移除指定提示;不传 id 时移除全部。 |
|
|
22
|
+
| subscribe | `(listener: () => void) => () => void` | 订阅变化,返回取消订阅函数。 |
|
|
23
|
+
| getSnapshot | `() => readonly ToastItem[]` | 当前提示列表;内容不变时引用不变。 |
|
|
24
|
+
|
|
25
|
+
### ToastOptions
|
|
26
|
+
|
|
27
|
+
| 属性 | 类型 | 默认值 | 说明 |
|
|
28
|
+
| --- | --- | --- | --- |
|
|
29
|
+
| message | `string` | 必填 | 主文案。 |
|
|
30
|
+
| description | `string` | `undefined` | 补充说明,最多显示两行。 |
|
|
31
|
+
| variant | `'info' \| 'success' \| 'error'` | `'info'` | 图标与语义。 |
|
|
32
|
+
| duration | `number` | `4000`,error 为 `8000` | 自动关闭的毫秒数;`0` 表示不自动关闭。 |
|
|
33
|
+
| action | `{ label: ReactNode; onClick: () => void \| Promise<void> }` | `undefined` | 操作按钮,见下方 Toast 的说明。 |
|
|
34
|
+
| onClose | `() => void` | `undefined` | 提示被移除后调用,包括超时、手动关闭、被新提示挤掉和 `dismiss`。 |
|
|
35
|
+
|
|
36
|
+
## Toaster
|
|
37
|
+
|
|
38
|
+
| 属性 | 类型 | 默认值 | 说明 |
|
|
39
|
+
| --- | --- | --- | --- |
|
|
40
|
+
| store | `ToastStore` | 必填 | 要渲染的状态容器。 |
|
|
41
|
+
| closeLabel | `string` | 必填 | 每张卡片关闭按钮的无障碍名称。 |
|
|
42
|
+
|
|
43
|
+
没有提示时不渲染任何节点。容器为 `position: fixed`,位于右下角,`z-index` 取自 `--hub-z-toast`(默认 1500);其余属性透传到容器,可用 `style` 覆盖层级与位置(`--hub-z-toast` 是内部变量,不建议直接覆盖)。组件不使用 portal,祖先元素有 `transform` 等属性时需由应用自行挂到 `body`。
|
|
44
|
+
|
|
45
|
+
## Toast
|
|
46
|
+
|
|
47
|
+
单张卡片,不负责定位。直接使用时由调用方决定何时挂载和卸载。
|
|
48
|
+
|
|
49
|
+
| 属性 | 类型 | 默认值 | 说明 |
|
|
50
|
+
| --- | --- | --- | --- |
|
|
51
|
+
| message | `ReactNode` | 必填 | 主文案。error 变体以 `role="alert"` 播报,其余为 `role="status"`。 |
|
|
52
|
+
| description | `ReactNode` | `undefined` | 补充说明,最多显示两行。 |
|
|
53
|
+
| variant | `'info' \| 'success' \| 'error'` | `'info'` | 图标与语义。 |
|
|
54
|
+
| action | `{ label: ReactNode; onClick: () => void \| Promise<void> }` | `undefined` | 操作按钮。`onClick` 返回 Promise 时,等待期间禁用按钮并暂停计时;成功后关闭;失败(抛出异常或 Promise 被拒绝)后保持打开、恢复按钮并重新计时,异常不会被捕获,错误提示由调用方在 `onClick` 内自行处理。 |
|
|
55
|
+
| duration | `number` | `4000`,error 为 `8000` | 自动关闭的毫秒数;`0` 表示不自动关闭。鼠标悬停或焦点在卡片内时暂停。 |
|
|
56
|
+
| revision | `number` | `0` | 数值变化时重新计时并播放强调动画。 |
|
|
57
|
+
| closeLabel | `string` | 必填 | 关闭按钮的无障碍名称。 |
|
|
58
|
+
| onDismiss | `() => void` | 必填 | 退出动画结束后调用,调用方应在此时卸载组件。 |
|
|
59
|
+
|
|
60
|
+
`className`、`ref` 和其余属性落在最外层的动画容器上。
|
package/docs/Tooltip.md
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Tooltip
|
|
2
|
+
|
|
3
|
+
| 属性 | 类型 | 默认值 | 说明 |
|
|
4
|
+
| --- | --- | --- | --- |
|
|
5
|
+
| children | `ReactElement` | 必填 | 单个触发元素,需要将 ref、事件和 ARIA 属性传递给实际 DOM 元素。 |
|
|
6
|
+
| content | `ReactNode` | 必填 | 提示内容,仅包含文本或非交互内容。 |
|
|
7
|
+
| shortcut | `readonly string[]` | 不显示 | 同一组快捷键的各个按键,例如 `['1']` 或 `['⌘', 'K']`。空数组等同于不传。 |
|
|
8
|
+
| side | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | 优先显示方向,空间不足时自动调整。 |
|
|
9
|
+
| align | `'start' \| 'center' \| 'end'` | `'center'` | 沿触发器边缘的对齐方式,start 和 end 遵循文字方向。 |
|
|
10
|
+
| disabled | `boolean` | `false` | 禁用提示;变为 true 时关闭浮层并取消等待。 |
|
|
11
|
+
|
|
12
|
+
不需要 Provider:同一文档中的 Tooltip 自动共享状态,同一时刻最多显示一个。触发元素原有的 ref、事件和 `aria-describedby` 都会保留,不额外包裹元素;图标按钮的 `aria-label` 和业务快捷键的 `aria-keyshortcuts` 仍由宿主提供。触发器不要同时设置原生 `title`,原生 disabled 控件不能作为触发器。
|
|
13
|
+
|
|
14
|
+
首次鼠标悬停等待 500ms 后显示。提示显示期间或关闭后 300ms 内移到另一个触发器,立即切换。键盘使触发器获得可见焦点时立即显示,鼠标点击带来的聚焦不显示。鼠标可以移到提示内容上,停留期间继续显示。
|
|
15
|
+
|
|
16
|
+
点击触发器会关闭提示,之后需要重新进入或聚焦才会再次显示;Escape 不关闭提示。触摸不模拟悬停。页面滚动、窗口尺寸变化、窗口失焦和页面隐藏时关闭;由键盘焦点保持的提示在滚动时跟随触发器,触发器离开视口或被滚动容器完全裁剪后关闭。触发器位于 top layer 内时,仅检查浮层自身及内部祖先的裁剪,不受浮层外祖先的 overflow 影响。
|
|
17
|
+
|
|
18
|
+
`shortcut` 的每一项渲染成一个 `<kbd>`,按下对应的键时高亮。高亮只反映当前按键状态,Tooltip 不注册快捷键、不执行操作,也不拦截键盘事件。显示文字原样展示,常用写法会映射到键名:`⌘`/`Cmd`/`Command`/`Meta`、`Ctrl`/`Control`/`⌃`、`Alt`/`Option`/`⌥`、`Shift`/`⇧`、`Esc`、`Enter`/`Return`/`↵`、`Space`/`␣` 和方向箭头;单个字母忽略大小写,其余按 `KeyboardEvent.key` 匹配。
|
|
19
|
+
|
|
20
|
+
提示在浏览器 top layer 中显示,不受父级 overflow 裁剪,保留祖先的主题 token。首选方向放不下时改用反方向,并始终留在视口内;长内容限制宽度并换行,超出视口高度时可在提示内滚动。提示浮层显式排除在 Tab 顺序之外,长内容滚动区域也不会插入额外的焦点位置。
|
package/docs/index.md
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hamsterbase/ui",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"files": [
|
|
5
5
|
"dist",
|
|
6
6
|
"docs",
|
|
@@ -31,6 +31,14 @@
|
|
|
31
31
|
"peerDependencies": {
|
|
32
32
|
"react": "^19.0.0"
|
|
33
33
|
},
|
|
34
|
+
"packageManager": "pnpm@10.14.0",
|
|
35
|
+
"scripts": {
|
|
36
|
+
"dev": "pnpm --filter @hamsterbase/ui-playground exec vite --host 0.0.0.0",
|
|
37
|
+
"build": "vite build && tsc -p tsconfig.build.json && node scripts/finalize-build.mjs",
|
|
38
|
+
"check": "tsc -p tsconfig.json",
|
|
39
|
+
"build:playground": "pnpm --filter @hamsterbase/ui-playground exec vite build",
|
|
40
|
+
"prepack": "pnpm build"
|
|
41
|
+
},
|
|
34
42
|
"dependencies": {
|
|
35
43
|
"clsx": "^2.1.1",
|
|
36
44
|
"lucide-react": "^1.68.0"
|
|
@@ -40,11 +48,5 @@
|
|
|
40
48
|
"publishConfig": {
|
|
41
49
|
"access": "public",
|
|
42
50
|
"registry": "https://registry.npmjs.org/"
|
|
43
|
-
},
|
|
44
|
-
"scripts": {
|
|
45
|
-
"dev": "pnpm --filter @hamsterbase/ui-playground exec vite --host 0.0.0.0",
|
|
46
|
-
"build": "vite build && tsc -p tsconfig.build.json && node scripts/finalize-build.mjs",
|
|
47
|
-
"check": "tsc -p tsconfig.json",
|
|
48
|
-
"build:playground": "pnpm --filter @hamsterbase/ui-playground exec vite build"
|
|
49
51
|
}
|
|
50
|
-
}
|
|
52
|
+
}
|