@dcg-overseas/number-line 0.1.10 → 0.1.12

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 (4) hide show
  1. package/README.md +317 -317
  2. package/dist/index.cjs +4 -4
  3. package/dist/index.js +4 -4
  4. package/package.json +47 -47
package/README.md CHANGED
@@ -1,317 +1,317 @@
1
- # @dcg-overseas/number-line
2
-
3
- 交互式数轴组件，支持分组弧线（带箭头终点标签）、自由画笔、橡皮擦、撤销与键盘快捷键。
4
-
5
- - 容器自适应：`viewBox` 跟随容器实际像素，文字和线条始终保持设计尺寸
6
- - 笔迹归一化存储（`[0,1]` 坐标 + `vectorEffect="non-scaling-stroke"`），容器 resize 后笔迹位置稳定不漂移
7
- - Provider/Component 解耦：状态在 `NumberLineProvider` 中管理，工具栏与数轴 SVG 各自独立组装
8
-
9
- ---
10
-
11
- ## 安装
12
-
13
- ```bash
14
- pnpm add @dcg-overseas/number-line
15
- # peer deps
16
- pnpm add react react-dom
17
- ```
18
-
19
- ---
20
-
21
- ## 快速开始
22
-
23
- ```tsx
24
- import { NumberLineProvider, NumberLine } from '@dcg-overseas/number-line'
25
-
26
- function Demo() {
27
- return (
28
- <NumberLineProvider
29
- min={0}
30
- max={100}
31
- groupSize={10}
32
- groupCount={10}
33
- tickStep={5}
34
- >
35
- <div style={{ width: '100%', height: 200 }}>
36
- <NumberLine />
37
- </div>
38
- </NumberLineProvider>
39
- )
40
- }
41
- ```
42
-
43
- > ⚠️ **必须给 `<NumberLine />` 的父容器明确的宽高**（CSS 尺寸或 flex 布局），SVG 默认 `width:100% height:100%`，没有外部尺寸约束会塌陷为 0。
44
-
45
- ---
46
-
47
- ## API
48
-
49
- ### `<NumberLineProvider>`
50
-
51
- 数轴的状态根。包裹任何需要访问数轴上下文的子组件（`<NumberLine />` 和你自己的工具栏按钮）。
52
-
53
- | Prop | 类型 | 默认值 | 说明 |
54
- |------|------|-------|------|
55
- | `min` | `number` | — | 数轴起点值（含） |
56
- | `max` | `number` | — | 数轴终点值（含） |
57
- | `groupSize` | `number` | — | 每组弧线跨度（数轴单位）。例：`groupSize=8` 表示每段弧从 `n` 跳到 `n+8` |
58
- | `groupCount` | `number` | — | 弧线组数。从 `min` 起依次绘制 `groupCount` 段弧线 |
59
- | `tickStep` | `number` | — | 主刻度步长（数轴单位）。例：`tickStep=5` 表示 0、5、10、15… 为主刻度 |
60
- | `arcColors` | `string[]` | 5 色循环 | 弧线颜色数组，按 `groupIndex % length` 轮换。默认值见 [`utils/geometry.ts` ARC_COLORS](src/utils/geometry.ts) |
61
- | `showGroupTicks` | `boolean` | `true` | 是否显示分组边界刻度（最长，10px） |
62
- | `showMajorTicks` | `boolean` | `true` | 是否显示主刻度（中等，7px） |
63
- | `showMinorTicks` | `boolean` | `false` | 是否显示次刻度（最短，4px）。默认隐藏 |
64
- | `enableZoom` | `boolean` | `false` | 启用滚轮/双指缩放 + 拖拽平移。默认禁用 |
65
- | `minZoom` | `number` | `1` | 最小缩放级别（1 = 完整 `[min, max]` 范围） |
66
- | `maxZoom` | `number` | `50` | 最大缩放级别（50 = 放大 50 倍） |
67
- | `viewMin` | `number?` | — | 受控模式：当前可视范围起点。需与 `viewMax` 和 `onViewChange` 配合 |
68
- | `viewMax` | `number?` | — | 受控模式：当前可视范围终点 |
69
- | `onViewChange` | `(viewMin, viewMax) => void` | — | 非受控模式：viewport 变化时触发（滚轮/拖拽/双击重置） |
70
- | `children` | `ReactNode` | — | 子节点（必须包含 `<NumberLine />` 或自定义渲染器） |
71
-
72
- #### 弧线生成规则
73
-
74
- ```
75
- 弧线 g 的范围：[min + g*groupSize, min + (g+1)*groupSize]
76
- g ∈ [0, groupCount)
77
- 若 (min + (g+1)*groupSize) > max，弧线提前停止
78
- ```
79
-
80
- #### 三档刻度优先级
81
-
82
- 一个位置可能同时是多档刻度（例如 `tickStep=5, groupSize=10` 时，10 既是主刻度也是分组边界）。视觉与可见性按 **分组边界 > 主刻度 > 次刻度** 归类，仅看其最高档对应的 `show*Ticks`。
83
-
84
- ```tsx
85
- // 默认：只显示主刻度 + 分组边界
86
- <NumberLineProvider min={0} max={100} groupSize={10} groupCount={10} tickStep={5} />
87
-
88
- // 显示全部三档刻度
89
- <NumberLineProvider ... showMinorTicks />
90
-
91
- // 极简模式：仅分组边界
92
- <NumberLineProvider ... showMajorTicks={false} />
93
- ```
94
-
95
- #### 缩放与平移（`enableZoom`）
96
-
97
- 启用后支持：
98
- - **滚轮缩放**：以鼠标位置为中心放大/缩小
99
- - **拖拽平移**：`tool='none'` 时，左键拖拽 >5px 触发平移（避免与点击选中冲突）
100
- - **双指缩放**（触摸屏）：pinch 手势
101
- - **双击重置**：双击空白处恢复到完整 `[min, max]` 范围
102
-
103
- ```tsx
104
- // 非受控模式（内部维护 viewport）
105
- <NumberLineProvider
106
- min={0}
107
- max={100}
108
- enableZoom
109
- minZoom={1}
110
- maxZoom={50}
111
- onViewChange={(viewMin, viewMax) => console.log('viewport:', viewMin, viewMax)}
112
- ...
113
- />
114
-
115
- // 受控模式（父组件控制 viewport）
116
- function App() {
117
- const [view, setView] = useState([0, 100])
118
- return (
119
- <NumberLineProvider
120
- min={0}
121
- max={100}
122
- enableZoom
123
- viewMin={view[0]}
124
- viewMax={view[1]}
125
- onViewChange={(a, b) => setView([a, b])}
126
- ...
127
- />
128
- )
129
- }
130
- ```
131
-
132
- **注意事项**：
133
- - 笔迹坐标是归一化 `[0,1]`（容器像素比例），**不会跟随数值缩放移动**。适合「批注」语义，不适合「标记 v=50 处」语义。
134
- - viewport 始终夹紧在 `[min, max]` 内，不会平移到数据范围外。
135
- - 缩放时刻度密度自动调整（`labelStep` 按可视范围重算）。
136
- - **桌面端**：滚轮和 pinch 需要鼠标悬停或 SVG 获得焦点（视觉上有蓝色边框提示）。
137
- - **移动端**：双指 pinch 直接生效（触摸即激活）。**SVG 外的双指仍会触发浏览器整页缩放**——如果不需要整页缩放，可在宿主 HTML 添加：
138
- ```html
139
- <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
140
- ```
141
- 但出于无障碍考虑，禁用整页缩放需谨慎评估。
142
-
143
- ---
144
-
145
- ### `<NumberLine>`
146
-
147
- 数轴 SVG 视图。必须放在 `<NumberLineProvider>` 内，自动从 context 读取所有配置和事件处理。
148
-
149
- | Prop | 类型 | 默认值 | 说明 |
150
- |------|------|-------|------|
151
- | `className` | `string?` | — | 追加到 SVG 根节点的 className（基础类名 `nl-svg`） |
152
-
153
- **渲染层级（从下到上）：**
154
- 1. `AxisLayer` — 数轴线 + 刻度 + 标签
155
- 2. `GroupArcsLayer` — 分组弧线 + 弧顶箭头标签 + 选中高亮
156
- 3. `DrawingLayer` — 用户笔迹（normalized `[0,1]` 坐标，scale 还原）
157
-
158
- **布局参数（内部常量，无需配置）：**
159
-
160
- | 名称 | 值 | 含义 |
161
- |------|---|------|
162
- | `PAD_LEFT` | 30 | 数轴左 padding |
163
- | `PAD_RIGHT` | 40 | 数轴右 padding |
164
- | `AXIS_BOTTOM_OFFSET` | 50 | 数轴线距容器底部像素（给刻度数字留空间） |
165
- | `ARC_TOP_PADDING` | 16 | 弧线顶部距容器顶部像素 |
166
- | `MIN_ARC_HEIGHT` | 24 | 弧线最小高度（容器极小时兜底） |
167
-
168
- ---
169
-
170
- ### `useNumberLineContext()`
171
-
172
- 读取 / 操作数轴状态的 hook。**必须在 `<NumberLineProvider>` 子树内调用**，否则抛错。
173
-
174
- 返回 `NumberLineContextValue`：
175
-
176
- #### 布局
177
- | 字段 | 类型 | 说明 |
178
- |------|------|------|
179
- | `svgRef` | `RefObject<SVGSVGElement>` | SVG 元素 ref |
180
- | `containerWidth` | `number` | 容器实际像素宽 |
181
- | `containerHeight` | `number` | 容器实际像素高 |
182
- | `svgCursor` | `string` | 当前 SVG cursor（自动随 tool 切换） |
183
-
184
- #### 配置（透传自 Provider props）
185
- | 字段 | 类型 |
186
- |------|------|
187
- | `min` `max` `groupSize` `groupCount` `tickStep` | `number` |
188
- | `arcColors` | `string[] \| undefined` |
189
- | `showGroupTicks` `showMajorTicks` `showMinorTicks` | `boolean` |
190
-
191
- #### 绘图状态
192
- | 字段 | 类型 | 说明 |
193
- |------|------|------|
194
- | `tool` | `'none' \| 'pen' \| 'eraser'` | 当前工具 |
195
- | `strokes` | `Stroke[]` | 已落笔的所有笔迹 |
196
- | `liveStroke` | `Stroke \| null` | 正在绘制中的笔迹（半透明预览） |
197
- | `selectedArcIndices` | `Set<number>` | 当前选中的弧线 group index |
198
- | `deletedArcIndices` | `Set<number>` | 已被擦除/删除的弧线 group index |
199
-
200
- #### 事件回调（已绑定到 `<NumberLine>`，自定义渲染时使用）
201
- | 字段 | 类型 |
202
- |------|------|
203
- | `onPointerDown` `onPointerMove` `onPointerUp` | `(e: PointerEvent) => void` |
204
- | `onStrokeClick` | `(id: string, e: PointerEvent) => void` |
205
- | `onArcClick` | `(groupIndex: number, e: PointerEvent) => void` |
206
-
207
- #### 工具栏 API
208
- | 字段 | 类型 | 说明 |
209
- |------|------|------|
210
- | `canDelete` | `boolean` | 是否有可删除的选中项（笔迹或弧线） |
211
- | `canUndo` | `boolean` | 是否有可撤销的操作 |
212
- | `onTogglePen` | `() => void` | 切换画笔工具 |
213
- | `onToggleEraser` | `() => void` | 切换橡皮擦 |
214
- | `onDelete` | `() => void` | 删除当前选中 |
215
- | `onReset` | `() => void` | 清空所有笔迹和弧线删除记录 |
216
- | `onUndo` | `() => void` | 撤销上一步操作 |
217
-
218
- #### 缩放 API（仅 `enableZoom=true` 时有效）
219
- | 字段 | 类型 | 说明 |
220
- |------|------|------|
221
- | `viewMin` `viewMax` | `number` | 当前可视范围（等于 `[min, max]` 当 zoom 禁用） |
222
- | `resetView` | `() => void` | 重置到完整数据范围 |
223
- | `zoomAt` | `(factor: number, fraction: number) => void` | 以 viewport 的 `fraction` 位置（0..1）为中心缩放 `factor` 倍 |
224
- | `panByFraction` | `(df: number) => void` | 平移 viewport 宽度的 `df` 倍（正数右移，负数左移） |
225
-
226
- ---
227
-
228
- ## 自定义工具栏示例
229
-
230
- `<NumberLine>` 不附带工具栏。把按钮和数轴一起放在 `<NumberLineProvider>` 下，通过 `useNumberLineContext` 接入：
231
-
232
- ```tsx
233
- import { NumberLineProvider, NumberLine, useNumberLineContext } from '@dcg-overseas/number-line'
234
-
235
- function Toolbar() {
236
- const { tool, canDelete, canUndo, onTogglePen, onToggleEraser, onDelete, onReset, onUndo } =
237
- useNumberLineContext()
238
-
239
- return (
240
- <div className="flex gap-2">
241
- <button data-active={tool === 'pen'} onClick={onTogglePen}>✏️ 画笔</button>
242
- <button data-active={tool === 'eraser'} onClick={onToggleEraser}>🩹 擦除</button>
243
- <button disabled={!canDelete} onClick={onDelete}>🗑 删除</button>
244
- <button onClick={onReset}>♻️ 重置</button>
245
- <button disabled={!canUndo} onClick={onUndo}>↶ 撤销</button>
246
- </div>
247
- )
248
- }
249
-
250
- function App() {
251
- return (
252
- <NumberLineProvider min={0} max={80} groupSize={8} groupCount={10} tickStep={1}>
253
- <Toolbar />
254
- <div style={{ height: 220 }}>
255
- <NumberLine />
256
- </div>
257
- </NumberLineProvider>
258
- )
259
- }
260
- ```
261
-
262
- ---
263
-
264
- ## 键盘快捷键
265
-
266
- 快捷键绑定在 SVG 元素上（`tabIndex={0}`，需先聚焦 SVG），多实例互不干扰，也不会拦截外部输入框。
267
-
268
- | 按键 | 行为 |
269
- |------|------|
270
- | `Esc` | 切回 `'none'` 模式，清空弧线选中 |
271
- | `Delete` / `Backspace` | 删除当前选中的笔迹和弧线 |
272
- | `Ctrl+Z` / `Cmd+Z` | 撤销上一步 |
273
-
274
- ---
275
-
276
- ## 类型导出
277
-
278
- ```ts
279
- import type {
280
- NumberLineProps,
281
- NumberLineContextValue,
282
- } from '@dcg-overseas/number-line'
283
- ```
284
-
285
- 完整类型见 [src/types.ts](src/types.ts) 与 [src/context/NumberLineContext.ts](src/context/NumberLineContext.ts)。
286
-
287
- ---
288
-
289
- ## 设计要点
290
-
291
- ### 自适应坐标系
292
-
293
- `viewBox` 动态跟随容器实际像素（`viewBox={`0 0 ${w} ${h}`}` + `preserveAspectRatio="none"`），1 SVG 单位 = 1 CSS 像素。这样：
294
-
295
- - 文字和线条始终是设计尺寸（fontSize=11 永远是 11px），不会因为容器纵横比异常被缩到看不见
296
- - 数轴自动贴近容器底部，弧线撑满上方空间，无空白浪费
297
-
298
- ### 笔迹归一化（resize 稳定）
299
-
300
- 笔迹存储为 `[0, 1]` 归一化坐标（`M 0.234 0.456 L ...`）。渲染时用 `<g transform={`scale(${w} ${h})`}>` 还原到容器像素，并配合 `vectorEffect="non-scaling-stroke"` 锁定线宽。
301
-
302
- 效果：容器从 `400×200` 变成 `600×300`，所有笔迹的相对位置仍然贴合数轴，stroke 宽度保持 2.5px。
303
-
304
- ### 操作级撤销
305
-
306
- 撤销栈记录的是「操作」而非「状态」（`HistoryOp`），分两类：
307
-
308
- - `add` — 新增笔迹，撤销 = 移除指定 id
309
- - `delete` — 删除笔迹/弧线，撤销 = 恢复删除前完整快照 + 还原弧线 group index
310
-
311
- 这样即使一次 `delete` 同时删了多条笔迹和多条弧线，撤销也能精确还原。
312
-
313
- ---
314
-
315
- ## License
316
-
317
- MIT
1
+ # @dcg-overseas/number-line
2
+
3
+ 交互式数轴组件，支持分组弧线（带箭头终点标签）、自由画笔、橡皮擦、撤销与键盘快捷键。
4
+
5
+ - 容器自适应：`viewBox` 跟随容器实际像素，文字和线条始终保持设计尺寸
6
+ - 笔迹归一化存储（`[0,1]` 坐标 + `vectorEffect="non-scaling-stroke"`），容器 resize 后笔迹位置稳定不漂移
7
+ - Provider/Component 解耦：状态在 `NumberLineProvider` 中管理，工具栏与数轴 SVG 各自独立组装
8
+
9
+ ---
10
+
11
+ ## 安装
12
+
13
+ ```bash
14
+ pnpm add @dcg-overseas/number-line
15
+ # peer deps
16
+ pnpm add react react-dom
17
+ ```
18
+
19
+ ---
20
+
21
+ ## 快速开始
22
+
23
+ ```tsx
24
+ import { NumberLineProvider, NumberLine } from '@dcg-overseas/number-line'
25
+
26
+ function Demo() {
27
+ return (
28
+ <NumberLineProvider
29
+ min={0}
30
+ max={100}
31
+ groupSize={10}
32
+ groupCount={10}
33
+ tickStep={5}
34
+ >
35
+ <div style={{ width: '100%', height: 200 }}>
36
+ <NumberLine />
37
+ </div>
38
+ </NumberLineProvider>
39
+ )
40
+ }
41
+ ```
42
+
43
+ > ⚠️ **必须给 `<NumberLine />` 的父容器明确的宽高**（CSS 尺寸或 flex 布局），SVG 默认 `width:100% height:100%`，没有外部尺寸约束会塌陷为 0。
44
+
45
+ ---
46
+
47
+ ## API
48
+
49
+ ### `<NumberLineProvider>`
50
+
51
+ 数轴的状态根。包裹任何需要访问数轴上下文的子组件（`<NumberLine />` 和你自己的工具栏按钮）。
52
+
53
+ | Prop | 类型 | 默认值 | 说明 |
54
+ |------|------|-------|------|
55
+ | `min` | `number` | — | 数轴起点值（含） |
56
+ | `max` | `number` | — | 数轴终点值（含） |
57
+ | `groupSize` | `number` | — | 每组弧线跨度（数轴单位）。例：`groupSize=8` 表示每段弧从 `n` 跳到 `n+8` |
58
+ | `groupCount` | `number` | — | 弧线组数。从 `min` 起依次绘制 `groupCount` 段弧线 |
59
+ | `tickStep` | `number` | — | 主刻度步长（数轴单位）。例：`tickStep=5` 表示 0、5、10、15… 为主刻度 |
60
+ | `arcColors` | `string[]` | 5 色循环 | 弧线颜色数组，按 `groupIndex % length` 轮换。默认值见 [`utils/geometry.ts` ARC_COLORS](src/utils/geometry.ts) |
61
+ | `showGroupTicks` | `boolean` | `true` | 是否显示分组边界刻度（最长，10px） |
62
+ | `showMajorTicks` | `boolean` | `true` | 是否显示主刻度（中等，7px） |
63
+ | `showMinorTicks` | `boolean` | `false` | 是否显示次刻度（最短，4px）。默认隐藏 |
64
+ | `enableZoom` | `boolean` | `false` | 启用滚轮/双指缩放 + 拖拽平移。默认禁用 |
65
+ | `minZoom` | `number` | `1` | 最小缩放级别（1 = 完整 `[min, max]` 范围） |
66
+ | `maxZoom` | `number` | `50` | 最大缩放级别（50 = 放大 50 倍） |
67
+ | `viewMin` | `number?` | — | 受控模式：当前可视范围起点。需与 `viewMax` 和 `onViewChange` 配合 |
68
+ | `viewMax` | `number?` | — | 受控模式：当前可视范围终点 |
69
+ | `onViewChange` | `(viewMin, viewMax) => void` | — | 非受控模式：viewport 变化时触发（滚轮/拖拽/双击重置） |
70
+ | `children` | `ReactNode` | — | 子节点（必须包含 `<NumberLine />` 或自定义渲染器） |
71
+
72
+ #### 弧线生成规则
73
+
74
+ ```
75
+ 弧线 g 的范围：[min + g*groupSize, min + (g+1)*groupSize]
76
+ g ∈ [0, groupCount)
77
+ 若 (min + (g+1)*groupSize) > max，弧线提前停止
78
+ ```
79
+
80
+ #### 三档刻度优先级
81
+
82
+ 一个位置可能同时是多档刻度（例如 `tickStep=5, groupSize=10` 时，10 既是主刻度也是分组边界）。视觉与可见性按 **分组边界 > 主刻度 > 次刻度** 归类，仅看其最高档对应的 `show*Ticks`。
83
+
84
+ ```tsx
85
+ // 默认：只显示主刻度 + 分组边界
86
+ <NumberLineProvider min={0} max={100} groupSize={10} groupCount={10} tickStep={5} />
87
+
88
+ // 显示全部三档刻度
89
+ <NumberLineProvider ... showMinorTicks />
90
+
91
+ // 极简模式：仅分组边界
92
+ <NumberLineProvider ... showMajorTicks={false} />
93
+ ```
94
+
95
+ #### 缩放与平移（`enableZoom`）
96
+
97
+ 启用后支持：
98
+ - **滚轮缩放**：以鼠标位置为中心放大/缩小
99
+ - **拖拽平移**：`tool='none'` 时，左键拖拽 >5px 触发平移（避免与点击选中冲突）
100
+ - **双指缩放**（触摸屏）：pinch 手势
101
+ - **双击重置**：双击空白处恢复到完整 `[min, max]` 范围
102
+
103
+ ```tsx
104
+ // 非受控模式（内部维护 viewport）
105
+ <NumberLineProvider
106
+ min={0}
107
+ max={100}
108
+ enableZoom
109
+ minZoom={1}
110
+ maxZoom={50}
111
+ onViewChange={(viewMin, viewMax) => console.log('viewport:', viewMin, viewMax)}
112
+ ...
113
+ />
114
+
115
+ // 受控模式（父组件控制 viewport）
116
+ function App() {
117
+ const [view, setView] = useState([0, 100])
118
+ return (
119
+ <NumberLineProvider
120
+ min={0}
121
+ max={100}
122
+ enableZoom
123
+ viewMin={view[0]}
124
+ viewMax={view[1]}
125
+ onViewChange={(a, b) => setView([a, b])}
126
+ ...
127
+ />
128
+ )
129
+ }
130
+ ```
131
+
132
+ **注意事项**：
133
+ - 笔迹坐标是归一化 `[0,1]`（容器像素比例），**不会跟随数值缩放移动**。适合「批注」语义，不适合「标记 v=50 处」语义。
134
+ - viewport 始终夹紧在 `[min, max]` 内，不会平移到数据范围外。
135
+ - 缩放时刻度密度自动调整（`labelStep` 按可视范围重算）。
136
+ - **桌面端**：滚轮和 pinch 需要鼠标悬停或 SVG 获得焦点（视觉上有蓝色边框提示）。
137
+ - **移动端**：双指 pinch 直接生效（触摸即激活）。**SVG 外的双指仍会触发浏览器整页缩放**——如果不需要整页缩放，可在宿主 HTML 添加：
138
+ ```html
139
+ <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
140
+ ```
141
+ 但出于无障碍考虑，禁用整页缩放需谨慎评估。
142
+
143
+ ---
144
+
145
+ ### `<NumberLine>`
146
+
147
+ 数轴 SVG 视图。必须放在 `<NumberLineProvider>` 内，自动从 context 读取所有配置和事件处理。
148
+
149
+ | Prop | 类型 | 默认值 | 说明 |
150
+ |------|------|-------|------|
151
+ | `className` | `string?` | — | 追加到 SVG 根节点的 className（基础类名 `nl-svg`） |
152
+
153
+ **渲染层级（从下到上）：**
154
+ 1. `AxisLayer` — 数轴线 + 刻度 + 标签
155
+ 2. `GroupArcsLayer` — 分组弧线 + 弧顶箭头标签 + 选中高亮
156
+ 3. `DrawingLayer` — 用户笔迹（normalized `[0,1]` 坐标，scale 还原）
157
+
158
+ **布局参数（内部常量，无需配置）：**
159
+
160
+ | 名称 | 值 | 含义 |
161
+ |------|---|------|
162
+ | `PAD_LEFT` | 30 | 数轴左 padding |
163
+ | `PAD_RIGHT` | 40 | 数轴右 padding |
164
+ | `AXIS_BOTTOM_OFFSET` | 50 | 数轴线距容器底部像素（给刻度数字留空间） |
165
+ | `ARC_TOP_PADDING` | 16 | 弧线顶部距容器顶部像素 |
166
+ | `MIN_ARC_HEIGHT` | 24 | 弧线最小高度（容器极小时兜底） |
167
+
168
+ ---
169
+
170
+ ### `useNumberLineContext()`
171
+
172
+ 读取 / 操作数轴状态的 hook。**必须在 `<NumberLineProvider>` 子树内调用**，否则抛错。
173
+
174
+ 返回 `NumberLineContextValue`：
175
+
176
+ #### 布局
177
+ | 字段 | 类型 | 说明 |
178
+ |------|------|------|
179
+ | `svgRef` | `RefObject<SVGSVGElement>` | SVG 元素 ref |
180
+ | `containerWidth` | `number` | 容器实际像素宽 |
181
+ | `containerHeight` | `number` | 容器实际像素高 |
182
+ | `svgCursor` | `string` | 当前 SVG cursor（自动随 tool 切换） |
183
+
184
+ #### 配置（透传自 Provider props）
185
+ | 字段 | 类型 |
186
+ |------|------|
187
+ | `min` `max` `groupSize` `groupCount` `tickStep` | `number` |
188
+ | `arcColors` | `string[] \| undefined` |
189
+ | `showGroupTicks` `showMajorTicks` `showMinorTicks` | `boolean` |
190
+
191
+ #### 绘图状态
192
+ | 字段 | 类型 | 说明 |
193
+ |------|------|------|
194
+ | `tool` | `'none' \| 'pen' \| 'eraser'` | 当前工具 |
195
+ | `strokes` | `Stroke[]` | 已落笔的所有笔迹 |
196
+ | `liveStroke` | `Stroke \| null` | 正在绘制中的笔迹（半透明预览） |
197
+ | `selectedArcIndices` | `Set<number>` | 当前选中的弧线 group index |
198
+ | `deletedArcIndices` | `Set<number>` | 已被擦除/删除的弧线 group index |
199
+
200
+ #### 事件回调（已绑定到 `<NumberLine>`，自定义渲染时使用）
201
+ | 字段 | 类型 |
202
+ |------|------|
203
+ | `onPointerDown` `onPointerMove` `onPointerUp` | `(e: PointerEvent) => void` |
204
+ | `onStrokeClick` | `(id: string, e: PointerEvent) => void` |
205
+ | `onArcClick` | `(groupIndex: number, e: PointerEvent) => void` |
206
+
207
+ #### 工具栏 API
208
+ | 字段 | 类型 | 说明 |
209
+ |------|------|------|
210
+ | `canDelete` | `boolean` | 是否有可删除的选中项（笔迹或弧线） |
211
+ | `canUndo` | `boolean` | 是否有可撤销的操作 |
212
+ | `onTogglePen` | `() => void` | 切换画笔工具 |
213
+ | `onToggleEraser` | `() => void` | 切换橡皮擦 |
214
+ | `onDelete` | `() => void` | 删除当前选中 |
215
+ | `onReset` | `() => void` | 清空所有笔迹和弧线删除记录 |
216
+ | `onUndo` | `() => void` | 撤销上一步操作 |
217
+
218
+ #### 缩放 API（仅 `enableZoom=true` 时有效）
219
+ | 字段 | 类型 | 说明 |
220
+ |------|------|------|
221
+ | `viewMin` `viewMax` | `number` | 当前可视范围（等于 `[min, max]` 当 zoom 禁用） |
222
+ | `resetView` | `() => void` | 重置到完整数据范围 |
223
+ | `zoomAt` | `(factor: number, fraction: number) => void` | 以 viewport 的 `fraction` 位置（0..1）为中心缩放 `factor` 倍 |
224
+ | `panByFraction` | `(df: number) => void` | 平移 viewport 宽度的 `df` 倍（正数右移，负数左移） |
225
+
226
+ ---
227
+
228
+ ## 自定义工具栏示例
229
+
230
+ `<NumberLine>` 不附带工具栏。把按钮和数轴一起放在 `<NumberLineProvider>` 下，通过 `useNumberLineContext` 接入：
231
+
232
+ ```tsx
233
+ import { NumberLineProvider, NumberLine, useNumberLineContext } from '@dcg-overseas/number-line'
234
+
235
+ function Toolbar() {
236
+ const { tool, canDelete, canUndo, onTogglePen, onToggleEraser, onDelete, onReset, onUndo } =
237
+ useNumberLineContext()
238
+
239
+ return (
240
+ <div className="flex gap-2">
241
+ <button data-active={tool === 'pen'} onClick={onTogglePen}>✏️ 画笔</button>
242
+ <button data-active={tool === 'eraser'} onClick={onToggleEraser}>🩹 擦除</button>
243
+ <button disabled={!canDelete} onClick={onDelete}>🗑 删除</button>
244
+ <button onClick={onReset}>♻️ 重置</button>
245
+ <button disabled={!canUndo} onClick={onUndo}>↶ 撤销</button>
246
+ </div>
247
+ )
248
+ }
249
+
250
+ function App() {
251
+ return (
252
+ <NumberLineProvider min={0} max={80} groupSize={8} groupCount={10} tickStep={1}>
253
+ <Toolbar />
254
+ <div style={{ height: 220 }}>
255
+ <NumberLine />
256
+ </div>
257
+ </NumberLineProvider>
258
+ )
259
+ }
260
+ ```
261
+
262
+ ---
263
+
264
+ ## 键盘快捷键
265
+
266
+ 快捷键绑定在 SVG 元素上（`tabIndex={0}`，需先聚焦 SVG），多实例互不干扰，也不会拦截外部输入框。
267
+
268
+ | 按键 | 行为 |
269
+ |------|------|
270
+ | `Esc` | 切回 `'none'` 模式，清空弧线选中 |
271
+ | `Delete` / `Backspace` | 删除当前选中的笔迹和弧线 |
272
+ | `Ctrl+Z` / `Cmd+Z` | 撤销上一步 |
273
+
274
+ ---
275
+
276
+ ## 类型导出
277
+
278
+ ```ts
279
+ import type {
280
+ NumberLineProps,
281
+ NumberLineContextValue,
282
+ } from '@dcg-overseas/number-line'
283
+ ```
284
+
285
+ 完整类型见 [src/types.ts](src/types.ts) 与 [src/context/NumberLineContext.ts](src/context/NumberLineContext.ts)。
286
+
287
+ ---
288
+
289
+ ## 设计要点
290
+
291
+ ### 自适应坐标系
292
+
293
+ `viewBox` 动态跟随容器实际像素（`viewBox={`0 0 ${w} ${h}`}` + `preserveAspectRatio="none"`），1 SVG 单位 = 1 CSS 像素。这样：
294
+
295
+ - 文字和线条始终是设计尺寸（fontSize=11 永远是 11px），不会因为容器纵横比异常被缩到看不见
296
+ - 数轴自动贴近容器底部，弧线撑满上方空间，无空白浪费
297
+
298
+ ### 笔迹归一化（resize 稳定）
299
+
300
+ 笔迹存储为 `[0, 1]` 归一化坐标（`M 0.234 0.456 L ...`）。渲染时用 `<g transform={`scale(${w} ${h})`}>` 还原到容器像素，并配合 `vectorEffect="non-scaling-stroke"` 锁定线宽。
301
+
302
+ 效果：容器从 `400×200` 变成 `600×300`，所有笔迹的相对位置仍然贴合数轴，stroke 宽度保持 2.5px。
303
+
304
+ ### 操作级撤销
305
+
306
+ 撤销栈记录的是「操作」而非「状态」（`HistoryOp`），分两类：
307
+
308
+ - `add` — 新增笔迹，撤销 = 移除指定 id
309
+ - `delete` — 删除笔迹/弧线，撤销 = 恢复删除前完整快照 + 还原弧线 group index
310
+
311
+ 这样即使一次 `delete` 同时删了多条笔迹和多条弧线，撤销也能精确还原。
312
+
313
+ ---
314
+
315
+ ## License
316
+
317
+ MIT
package/dist/index.cjs CHANGED
@@ -771,7 +771,7 @@ function AnimatedArc({
771
771
  x: x2,
772
772
  y: textY,
773
773
  textAnchor: edgeTextAnchor(end, min, max),
774
- fontSize: 10,
774
+ fontSize: 14,
775
775
  fill: strokeColor,
776
776
  fontWeight: "600",
777
777
  pointerEvents: "none",
@@ -783,7 +783,7 @@ function AnimatedArc({
783
783
  "line",
784
784
  {
785
785
  x1: x2,
786
- y1: textY + 4,
786
+ y1: textY + 5,
787
787
  x2,
788
788
  y2: axisY - arrowHeadH,
789
789
  stroke: strokeColor,
@@ -836,7 +836,7 @@ const GroupArcsLayer = React.memo(function GroupArcsLayer2({
836
836
  const rx = (x2 - x1) / 2;
837
837
  const ry = Math.min(rx * ARC_RY_RATIO, arcMaxHeight);
838
838
  const color = arcColors[g % arcColors.length];
839
- const MIN_ARROW_SPAN = 18;
839
+ const MIN_ARROW_SPAN = 24;
840
840
  const textY = Math.min(axisY - ry - 6, axisY - MIN_ARROW_SPAN);
841
841
  const arcPath = buildArcPath({ x1, x2, y: axisY, rx, ry });
842
842
  const isSelected = selectedArcIndices.has(g);
@@ -937,7 +937,7 @@ function DrawingLayer({ strokes, liveStroke, tool, width, height, onStrokeClick
937
937
  ] });
938
938
  }
939
939
  const LABEL_SPACE_BELOW_AXIS = 42;
940
- const LABEL_ABOVE_AXIS_SLOP = 32;
940
+ const LABEL_ABOVE_AXIS_SLOP = 38;
941
941
  const ARC_TOP_PADDING = 16;
942
942
  const MIN_ARC_HEIGHT = 24;
943
943
  function NumberLine({ className }) {
package/dist/index.js CHANGED
@@ -769,7 +769,7 @@ function AnimatedArc({
769
769
  x: x2,
770
770
  y: textY,
771
771
  textAnchor: edgeTextAnchor(end, min, max),
772
- fontSize: 10,
772
+ fontSize: 14,
773
773
  fill: strokeColor,
774
774
  fontWeight: "600",
775
775
  pointerEvents: "none",
@@ -781,7 +781,7 @@ function AnimatedArc({
781
781
  "line",
782
782
  {
783
783
  x1: x2,
784
- y1: textY + 4,
784
+ y1: textY + 5,
785
785
  x2,
786
786
  y2: axisY - arrowHeadH,
787
787
  stroke: strokeColor,
@@ -834,7 +834,7 @@ const GroupArcsLayer = memo(function GroupArcsLayer2({
834
834
  const rx = (x2 - x1) / 2;
835
835
  const ry = Math.min(rx * ARC_RY_RATIO, arcMaxHeight);
836
836
  const color = arcColors[g % arcColors.length];
837
- const MIN_ARROW_SPAN = 18;
837
+ const MIN_ARROW_SPAN = 24;
838
838
  const textY = Math.min(axisY - ry - 6, axisY - MIN_ARROW_SPAN);
839
839
  const arcPath = buildArcPath({ x1, x2, y: axisY, rx, ry });
840
840
  const isSelected = selectedArcIndices.has(g);
@@ -935,7 +935,7 @@ function DrawingLayer({ strokes, liveStroke, tool, width, height, onStrokeClick
935
935
  ] });
936
936
  }
937
937
  const LABEL_SPACE_BELOW_AXIS = 42;
938
- const LABEL_ABOVE_AXIS_SLOP = 32;
938
+ const LABEL_ABOVE_AXIS_SLOP = 38;
939
939
  const ARC_TOP_PADDING = 16;
940
940
  const MIN_ARC_HEIGHT = 24;
941
941
  function NumberLine({ className }) {
package/package.json CHANGED
@@ -1,47 +1,47 @@
1
- {
2
- "name": "@dcg-overseas/number-line",
3
- "version": "0.1.10",
4
- "description": "Interactive number line component with group arcs and freehand drawing",
5
- "type": "module",
6
- "license": "MIT",
7
- "main": "./dist/index.cjs",
8
- "module": "./dist/index.js",
9
- "types": "./dist/index.d.ts",
10
- "exports": {
11
- ".": {
12
- "import": {
13
- "types": "./dist/index.d.ts",
14
- "default": "./dist/index.js"
15
- },
16
- "require": {
17
- "types": "./dist/index.d.cts",
18
- "default": "./dist/index.cjs"
19
- }
20
- }
21
- },
22
- "files": [
23
- "dist"
24
- ],
25
- "sideEffects": false,
26
- "scripts": {
27
- "build": "vite build",
28
- "build:watch": "vite build --watch",
29
- "typecheck": "tsc --noEmit",
30
- "clean": "rm -rf dist *.tsbuildinfo"
31
- },
32
- "peerDependencies": {
33
- "react": "^18.0.0",
34
- "react-dom": "^18.0.0"
35
- },
36
- "devDependencies": {
37
- "@types/react": "^18.3.3",
38
- "@types/react-dom": "^18.3.0",
39
- "@vitejs/plugin-react": "^4.3.1",
40
- "vite": "^5.3.1",
41
- "vite-plugin-dts": "^3.9.1"
42
- },
43
- "publishConfig": {
44
- "access": "public",
45
- "registry": "https://registry.npmjs.org/"
46
- }
47
- }
1
+ {
2
+ "name": "@dcg-overseas/number-line",
3
+ "version": "0.1.12",
4
+ "description": "Interactive number line component with group arcs and freehand drawing",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "main": "./dist/index.cjs",
8
+ "module": "./dist/index.js",
9
+ "types": "./dist/index.d.ts",
10
+ "exports": {
11
+ ".": {
12
+ "import": {
13
+ "types": "./dist/index.d.ts",
14
+ "default": "./dist/index.js"
15
+ },
16
+ "require": {
17
+ "types": "./dist/index.d.cts",
18
+ "default": "./dist/index.cjs"
19
+ }
20
+ }
21
+ },
22
+ "files": [
23
+ "dist"
24
+ ],
25
+ "sideEffects": false,
26
+ "scripts": {
27
+ "build": "vite build",
28
+ "build:watch": "vite build --watch",
29
+ "typecheck": "tsc --noEmit",
30
+ "clean": "rm -rf dist *.tsbuildinfo"
31
+ },
32
+ "peerDependencies": {
33
+ "react": "^18.0.0",
34
+ "react-dom": "^18.0.0"
35
+ },
36
+ "devDependencies": {
37
+ "@types/react": "^18.3.3",
38
+ "@types/react-dom": "^18.3.0",
39
+ "@vitejs/plugin-react": "^4.3.1",
40
+ "vite": "^5.3.1",
41
+ "vite-plugin-dts": "^3.9.1"
42
+ },
43
+ "publishConfig": {
44
+ "access": "public",
45
+ "registry": "https://registry.npmjs.org/"
46
+ }
47
+ }