@dcg-overseas/number-line 1.0.0-beta.4 → 1.0.0-beta.5

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 (5) hide show
  1. package/README.md +355 -316
  2. package/dist/index.cjs +48 -52
  3. package/dist/index.d.ts +9 -1
  4. package/dist/index.js +48 -52
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -1,316 +1,355 @@
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
- | `clearAll` | `() => void` | 可撤销地清空全部笔迹、弧线、选择和分组边界粗刻度；连续清空不会增加空历史项 |
216
- | `onReset` | `() => void` | `clearAll` 的兼容别名，已弃用；新代码请使用 `clearAll` |
217
- | `onUndo` | `() => void` | 撤销上一步操作 |
218
- | `showAllArcs` | `() => void` | 重新显示全部跳数弧线**及分组边界粗刻度**（清空删除记录）。即使参数未变、或刚 `clearAll` 隐藏后，也能强制把跳数显示出来，且不影响笔迹 |
219
-
220
- #### 缩放 API（仅 `enableZoom=true` 时有效）
221
- | 字段 | 类型 | 说明 |
222
- |------|------|------|
223
- | `viewMin` `viewMax` | `number` | 当前可视范围（等于 `[min, max]` 当 zoom 禁用） |
224
- | `resetView` | `() => void` | 重置到完整数据范围 |
225
- | `zoomAt` | `(factor: number, fraction: number) => void` | 以 viewport 的 `fraction` 位置（0..1）为中心缩放 `factor` 倍 |
226
- | `panByFraction` | `(df: number) => void` | 平移 viewport 宽度的 `df` 倍（正数右移，负数左移） |
227
-
228
- ---
229
-
230
- ## 自定义工具栏示例
231
-
232
- `<NumberLine>` 不附带工具栏。把按钮和数轴一起放在 `<NumberLineProvider>` 下，通过 `useNumberLineContext` 接入：
233
-
234
- ```tsx
235
- import { NumberLineProvider, NumberLine, useNumberLineContext } from '@dcg-overseas/number-line'
236
-
237
- function Toolbar() {
238
- const { tool, canDelete, canUndo, onTogglePen, onToggleEraser, onDelete, clearAll, onUndo } =
239
- useNumberLineContext()
240
-
241
- return (
242
- <div className="flex gap-2">
243
- <button data-active={tool === 'pen'} onClick={onTogglePen}>✏️ 画笔</button>
244
- <button data-active={tool === 'eraser'} onClick={onToggleEraser}>🩹 擦除</button>
245
- <button disabled={!canDelete} onClick={onDelete}>🗑 删除</button>
246
- <button onClick={clearAll}>♻️ 全部清除</button>
247
- <button disabled={!canUndo} onClick={onUndo}>↶ 撤销</button>
248
- </div>
249
- )
250
- }
251
-
252
- function App() {
253
- return (
254
- <NumberLineProvider min={0} max={80} groupSize={8} groupCount={10} tickStep={1}>
255
- <Toolbar />
256
- <div style={{ height: 220 }}>
257
- <NumberLine />
258
- </div>
259
- </NumberLineProvider>
260
- )
261
- }
262
- ```
263
-
264
- ---
265
-
266
- ## 键盘快捷键
267
-
268
- 快捷键绑定在 SVG 元素上（`tabIndex={0}`，需先聚焦 SVG），多实例互不干扰，也不会拦截外部输入框。
269
-
270
- | 按键 | 行为 |
271
- |------|------|
272
- | `Esc` | 切回 `'none'` 模式，清空弧线选中 |
273
- | `Delete` / `Backspace` | 删除当前选中的笔迹和弧线 |
274
- | `Ctrl+Z` / `Cmd+Z` | 撤销上一步 |
275
-
276
- ---
277
-
278
- ## 类型导出
279
-
280
- ```ts
281
- import type {
282
- NumberLineProps,
283
- NumberLineContextValue,
284
- } from '@dcg-overseas/number-line'
285
- ```
286
-
287
- 完整类型见 [src/types.ts](src/types.ts) 与 [src/context/NumberLineContext.ts](src/context/NumberLineContext.ts)。
288
-
289
- ---
290
-
291
- ## 设计要点
292
-
293
- ### 自适应坐标系
294
-
295
- `viewBox` 动态跟随容器实际像素（`viewBox={`0 0 ${w} ${h}`}` + `preserveAspectRatio="none"`），1 SVG 单位 = 1 CSS 像素。这样：
296
-
297
- - 文字和线条始终是设计尺寸（fontSize=11 永远是 11px），不会因为容器纵横比异常被缩到看不见
298
- - 数轴自动贴近容器底部，弧线撑满上方空间，无空白浪费
299
-
300
- ### 笔迹归一化（resize 稳定）
301
-
302
- 笔迹存储为 `[0, 1]` 归一化坐标（`M 0.234 0.456 L ...`）。渲染时用 `<g transform={`scale(${w} ${h})`}>` 还原到容器像素，并配合 `vectorEffect="non-scaling-stroke"` 锁定线宽。
303
-
304
- 效果：容器从 `400×200` 变成 `600×300`，所有笔迹的相对位置仍然贴合数轴，stroke 宽度保持 2.5px。
305
-
306
- ### 操作级撤销
307
-
308
- 撤销栈记录每次操作发生前的完整状态快照，包括笔迹、已删除弧线、已选弧线和粗分组刻度状态。
309
- 画笔、橡皮擦、删除选中及 `clearAll` 都复用同一恢复流程，因此一次清空或批量删除可以完整还原。
310
- `min`、`max`、`groupSize`、`groupCount` 或 `tickStep` 改变时会执行不可撤销初始化并清空历史，防止把上一道题的数据恢复到新坐标范围。
311
-
312
- ---
313
-
314
- ## License
315
-
316
- 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
+ | `coordinateScale` | `number` | `1` | SVG 内部逻辑坐标倍率。仅扩大 `viewBox` 与布局计算，不改变 SVG 的 CSS 宽高；整体缩放页面可传入反向倍率以保持设计稿的标签密度，避免 CSS `transform` 缩放。 |
61
+ | `arcColors` | `string[]` | 5 色循环 | 弧线颜色数组，按 `groupIndex % length` 轮换。默认值见 [`utils/geometry.ts` ARC_COLORS](src/utils/geometry.ts) |
62
+ | `showGroupTicks` | `boolean` | `true` | 是否显示分组边界刻度（最长，10px） |
63
+ | `showMajorTicks` | `boolean` | `true` | 是否显示主刻度（中等，7px） |
64
+ | `showMinorTicks` | `boolean` | `false` | 是否显示次刻度（最短，4px）。默认隐藏 |
65
+ | `enableZoom` | `boolean` | `false` | 启用滚轮/双指缩放 + 拖拽平移。默认禁用 |
66
+ | `minZoom` | `number` | `1` | 最小缩放级别（1 = 完整 `[min, max]` 范围） |
67
+ | `maxZoom` | `number` | `50` | 最大缩放级别（50 = 放大 50 倍） |
68
+ | `viewMin` | `number?` | — | 受控模式：当前可视范围起点。需与 `viewMax` 和 `onViewChange` 配合 |
69
+ | `viewMax` | `number?` | — | 受控模式：当前可视范围终点 |
70
+ | `onViewChange` | `(viewMin, viewMax) => void` | — | 非受控模式：viewport 变化时触发（滚轮/拖拽/双击重置） |
71
+ | `children` | `ReactNode` | — | 子节点（必须包含 `<NumberLine />` 或自定义渲染器） |
72
+
73
+ #### 弧线生成规则
74
+
75
+ ```
76
+ 弧线 g 的范围：[min + g*groupSize, min + (g+1)*groupSize]
77
+ g ∈ [0, groupCount)
78
+ 若 (min + (g+1)*groupSize) > max，弧线提前停止
79
+ ```
80
+
81
+ #### 三档刻度优先级
82
+
83
+ 一个位置可能同时是多档刻度（例如 `tickStep=5, groupSize=10` 时，10 既是主刻度也是分组边界）。视觉与可见性按 **分组边界 > 主刻度 > 次刻度** 归类，仅看其最高档对应的 `show*Ticks`。
84
+
85
+ ```tsx
86
+ // 默认：只显示主刻度 + 分组边界
87
+ <NumberLineProvider min={0} max={100} groupSize={10} groupCount={10} tickStep={5} />
88
+
89
+ // 显示全部三档刻度
90
+ <NumberLineProvider ... showMinorTicks />
91
+
92
+ // 极简模式：仅分组边界
93
+ <NumberLineProvider ... showMajorTicks={false} />
94
+ ```
95
+
96
+ #### 缩放与平移（`enableZoom`）
97
+
98
+ 启用后支持：
99
+
100
+ - **滚轮缩放**：以鼠标位置为中心放大/缩小
101
+ - **拖拽平移**：`tool='none'` 时，左键拖拽 >5px 触发平移（避免与点击选中冲突）
102
+ - **双指缩放**（触摸屏）：pinch 手势
103
+ - **双击重置**：双击空白处恢复到完整 `[min, max]` 范围
104
+
105
+ ```tsx
106
+ // 非受控模式（内部维护 viewport）
107
+ <NumberLineProvider
108
+ min={0}
109
+ max={100}
110
+ enableZoom
111
+ minZoom={1}
112
+ maxZoom={50}
113
+ onViewChange={(viewMin, viewMax) => console.log('viewport:', viewMin, viewMax)}
114
+ ...
115
+ />
116
+
117
+ // 受控模式（父组件控制 viewport）
118
+ function App() {
119
+ const [view, setView] = useState([0, 100])
120
+ return (
121
+ <NumberLineProvider
122
+ min={0}
123
+ max={100}
124
+ enableZoom
125
+ viewMin={view[0]}
126
+ viewMax={view[1]}
127
+ onViewChange={(a, b) => setView([a, b])}
128
+ ...
129
+ />
130
+ )
131
+ }
132
+ ```
133
+
134
+ **注意事项**：
135
+
136
+ - 笔迹坐标是归一化 `[0,1]`（容器像素比例），**不会跟随数值缩放移动**。适合「批注」语义，不适合「标记 v=50 处」语义。
137
+ - viewport 始终夹紧在 `[min, max]` 内，不会平移到数据范围外。
138
+ - 缩放时刻度密度自动调整（`labelStep` 按可视范围重算）。
139
+ - **桌面端**：滚轮和 pinch 需要鼠标悬停或 SVG 获得焦点（视觉上有蓝色边框提示）。
140
+ - **移动端**：双指 pinch 直接生效（触摸即激活）。**SVG 外的双指仍会触发浏览器整页缩放**——如果不需要整页缩放，可在宿主 HTML 添加：
141
+ ```html
142
+ <meta
143
+ name="viewport"
144
+ content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"
145
+ />
146
+ ```
147
+ 但出于无障碍考虑，禁用整页缩放需谨慎评估。
148
+
149
+ ---
150
+
151
+ ### `<NumberLine>`
152
+
153
+ 数轴 SVG 视图。必须放在 `<NumberLineProvider>` 内，自动从 context 读取所有配置和事件处理。
154
+
155
+ | Prop | 类型 | 默认值 | 说明 |
156
+ | ----------- | --------- | ------ | -------------------------------------------------- |
157
+ | `className` | `string?` | — | 追加到 SVG 根节点的 className（基础类名 `nl-svg`） |
158
+
159
+ **渲染层级（从下到上）：**
160
+
161
+ 1. `AxisLayer` — 数轴线 + 刻度 + 标签
162
+ 2. `GroupArcsLayer` — 分组弧线 + 弧顶箭头标签 + 选中高亮
163
+ 3. `DrawingLayer` — 用户笔迹（normalized `[0,1]` 坐标，scale 还原）
164
+
165
+ **布局参数（内部常量，无需配置）：**
166
+
167
+ | 名称 | 值 | 含义 |
168
+ | -------------------- | --- | ---------------------------------------- |
169
+ | `PAD_LEFT` | 30 | 数轴左 padding |
170
+ | `PAD_RIGHT` | 40 | 数轴右 padding |
171
+ | `AXIS_BOTTOM_OFFSET` | 50 | 数轴线距容器底部像素（给刻度数字留空间） |
172
+ | `ARC_TOP_PADDING` | 16 | 弧线顶部距容器顶部像素 |
173
+ | `MIN_ARC_HEIGHT` | 24 | 弧线最小高度（容器极小时兜底） |
174
+
175
+ ---
176
+
177
+ ### `useNumberLineContext()`
178
+
179
+ 读取 / 操作数轴状态的 hook。**必须在 `<NumberLineProvider>` 子树内调用**，否则抛错。
180
+
181
+ 返回 `NumberLineContextValue`：
182
+
183
+ #### 布局
184
+
185
+ | 字段 | 类型 | 说明 |
186
+ | ----------------- | -------------------------- | ----------------------------------- |
187
+ | `svgRef` | `RefObject<SVGSVGElement>` | SVG 元素 ref |
188
+ | `containerWidth` | `number` | 容器实际像素宽 |
189
+ | `containerHeight` | `number` | 容器实际像素高 |
190
+ | `svgCursor` | `string` | 当前 SVG cursor（自动随 tool 切换） |
191
+
192
+ #### 配置（透传自 Provider props）
193
+
194
+ | 字段 | 类型 |
195
+ | -------------------------------------------------- | ----------------------- |
196
+ | `min` `max` `groupSize` `groupCount` `tickStep` | `number` |
197
+ | `arcColors` | `string[] \| undefined` |
198
+ | `showGroupTicks` `showMajorTicks` `showMinorTicks` | `boolean` |
199
+
200
+ #### 绘图状态
201
+
202
+ | 字段 | 类型 | 说明 |
203
+ | -------------------- | ----------------------------- | ------------------------------- |
204
+ | `tool` | `'none' \| 'pen' \| 'eraser'` | 当前工具 |
205
+ | `strokes` | `Stroke[]` | 已落笔的所有笔迹 |
206
+ | `liveStroke` | `Stroke \| null` | 正在绘制中的笔迹（半透明预览） |
207
+ | `selectedArcIndices` | `Set<number>` | 当前选中的弧线 group index |
208
+ | `deletedArcIndices` | `Set<number>` | 已被擦除/删除的弧线 group index |
209
+
210
+ #### 事件回调（已绑定到 `<NumberLine>`，自定义渲染时使用）
211
+
212
+ | 字段 | 类型 |
213
+ | --------------------------------------------- | ----------------------------------------------- |
214
+ | `onPointerDown` `onPointerMove` `onPointerUp` | `(e: PointerEvent) => void` |
215
+ | `onStrokeClick` | `(id: string, e: PointerEvent) => void` |
216
+ | `onArcClick` | `(groupIndex: number, e: PointerEvent) => void` |
217
+
218
+ #### 工具栏 API
219
+
220
+ | 字段 | 类型 | 说明 |
221
+ | ---------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
222
+ | `canDelete` | `boolean` | 是否有可删除的选中项（笔迹或弧线） |
223
+ | `canUndo` | `boolean` | 是否有可撤销的操作 |
224
+ | `onTogglePen` | `() => void` | 切换画笔工具 |
225
+ | `onToggleEraser` | `() => void` | 切换橡皮擦 |
226
+ | `onDelete` | `() => void` | 删除当前选中 |
227
+ | `clearAll` | `() => void` | 可撤销地清空全部笔迹、弧线、选择和分组边界粗刻度；连续清空不会增加空历史项 |
228
+ | `onReset` | `() => void` | `clearAll` 的兼容别名，已弃用；新代码请使用 `clearAll` |
229
+ | `onUndo` | `() => void` | 撤销上一步操作 |
230
+ | `showAllArcs` | `() => void` | 重新显示全部跳数弧线**及分组边界粗刻度**（清空删除记录）。即使参数未变、或刚 `clearAll` 隐藏后，也能强制把跳数显示出来，且不影响笔迹 |
231
+
232
+ #### 缩放 API（仅 `enableZoom=true` 时有效）
233
+
234
+ | 字段 | 类型 | 说明 |
235
+ | ------------------- | -------------------------------------------- | ------------------------------------------------------------ |
236
+ | `viewMin` `viewMax` | `number` | 当前可视范围（等于 `[min, max]` 当 zoom 禁用） |
237
+ | `resetView` | `() => void` | 重置到完整数据范围 |
238
+ | `zoomAt` | `(factor: number, fraction: number) => void` | 以 viewport 的 `fraction` 位置（0..1）为中心缩放 `factor` 倍 |
239
+ | `panByFraction` | `(df: number) => void` | 平移 viewport 宽度的 `df` 倍（正数右移，负数左移） |
240
+
241
+ ---
242
+
243
+ ## 自定义工具栏示例
244
+
245
+ `<NumberLine>` 不附带工具栏。把按钮和数轴一起放在 `<NumberLineProvider>` 下，通过 `useNumberLineContext` 接入：
246
+
247
+ ```tsx
248
+ import {
249
+ NumberLineProvider,
250
+ NumberLine,
251
+ useNumberLineContext,
252
+ } from "@dcg-overseas/number-line";
253
+
254
+ function Toolbar() {
255
+ const {
256
+ tool,
257
+ canDelete,
258
+ canUndo,
259
+ onTogglePen,
260
+ onToggleEraser,
261
+ onDelete,
262
+ clearAll,
263
+ onUndo,
264
+ } = useNumberLineContext();
265
+
266
+ return (
267
+ <div className="flex gap-2">
268
+ <button data-active={tool === "pen"} onClick={onTogglePen}>
269
+ ✏️ 画笔
270
+ </button>
271
+ <button data-active={tool === "eraser"} onClick={onToggleEraser}>
272
+ 🩹 擦除
273
+ </button>
274
+ <button disabled={!canDelete} onClick={onDelete}>
275
+ 🗑 删除
276
+ </button>
277
+ <button onClick={clearAll}>♻️ 全部清除</button>
278
+ <button disabled={!canUndo} onClick={onUndo}>
279
+ ↶ 撤销
280
+ </button>
281
+ </div>
282
+ );
283
+ }
284
+
285
+ function App() {
286
+ return (
287
+ <NumberLineProvider
288
+ min={0}
289
+ max={80}
290
+ groupSize={8}
291
+ groupCount={10}
292
+ tickStep={1}
293
+ >
294
+ <Toolbar />
295
+ <div style={{ height: 220 }}>
296
+ <NumberLine />
297
+ </div>
298
+ </NumberLineProvider>
299
+ );
300
+ }
301
+ ```
302
+
303
+ ---
304
+
305
+ ## 键盘快捷键
306
+
307
+ 快捷键绑定在 SVG 元素上（`tabIndex={0}`，需先聚焦 SVG），多实例互不干扰，也不会拦截外部输入框。
308
+
309
+ | 按键 | 行为 |
310
+ | ---------------------- | -------------------------------- |
311
+ | `Esc` | 切回 `'none'` 模式，清空弧线选中 |
312
+ | `Delete` / `Backspace` | 删除当前选中的笔迹和弧线 |
313
+ | `Ctrl+Z` / `Cmd+Z` | 撤销上一步 |
314
+
315
+ ---
316
+
317
+ ## 类型导出
318
+
319
+ ```ts
320
+ import type {
321
+ NumberLineProps,
322
+ NumberLineContextValue,
323
+ } from "@dcg-overseas/number-line";
324
+ ```
325
+
326
+ 完整类型见 [src/types.ts](src/types.ts) 与 [src/context/NumberLineContext.ts](src/context/NumberLineContext.ts)。
327
+
328
+ ---
329
+
330
+ ## 设计要点
331
+
332
+ ### 自适应坐标系
333
+
334
+ `viewBox` 动态跟随容器实际像素（`viewBox={`0 0 ${w} ${h}`}` + `preserveAspectRatio="none"`），1 SVG 单位 = 1 CSS 像素。这样：
335
+
336
+ - 文字和线条始终是设计尺寸（fontSize=11 永远是 11px），不会因为容器纵横比异常被缩到看不见
337
+ - 数轴自动贴近容器底部，弧线撑满上方空间，无空白浪费
338
+
339
+ ### 笔迹归一化（resize 稳定）
340
+
341
+ 笔迹存储为 `[0, 1]` 归一化坐标（`M 0.234 0.456 L ...`）。渲染时用 `<g transform={`scale(${w} ${h})`}>` 还原到容器像素，并配合 `vectorEffect="non-scaling-stroke"` 锁定线宽。
342
+
343
+ 效果：容器从 `400×200` 变成 `600×300`，所有笔迹的相对位置仍然贴合数轴，stroke 宽度保持 2.5px。
344
+
345
+ ### 操作级撤销
346
+
347
+ 撤销栈记录每次操作发生前的完整状态快照，包括笔迹、已删除弧线、已选弧线和粗分组刻度状态。
348
+ 画笔、橡皮擦、删除选中及 `clearAll` 都复用同一恢复流程，因此一次清空或批量删除可以完整还原。
349
+ `min`、`max`、`groupSize`、`groupCount` 或 `tickStep` 改变时会执行不可撤销初始化并清空历史，防止把上一道题的数据恢复到新坐标范围。
350
+
351
+ ---
352
+
353
+ ## License
354
+
355
+ MIT
package/dist/index.cjs CHANGED
@@ -257,6 +257,7 @@ function NumberLineProvider({
257
257
  groupCount,
258
258
  tickStep,
259
259
  strokeWidth: configuredStrokeWidth,
260
+ coordinateScale: configuredCoordinateScale = 1,
260
261
  arcColors,
261
262
  showGroupTicks = true,
262
263
  showMajorTicks = true,
@@ -273,10 +274,13 @@ function NumberLineProvider({
273
274
  }) {
274
275
  const { min: domainMin, max: domainMax } = normalizeDomain(min, max);
275
276
  const strokeWidth = typeof configuredStrokeWidth === "number" && Number.isFinite(configuredStrokeWidth) && configuredStrokeWidth > 0 ? configuredStrokeWidth : DEFAULT_DRAWING_STROKE_WIDTH;
277
+ const coordinateScale = typeof configuredCoordinateScale === "number" && Number.isFinite(configuredCoordinateScale) && configuredCoordinateScale > 0 ? configuredCoordinateScale : 1;
276
278
  const [selectedArcIndices, setSelectedArcIndices] = React.useState(/* @__PURE__ */ new Set());
277
279
  const [deletedArcIndices, setDeletedArcIndices] = React.useState(/* @__PURE__ */ new Set());
278
280
  const [groupTicksHidden, setGroupTicksHidden] = React.useState(false);
279
- const { ref: svgRef, width: containerWidth, height: containerHeight } = useContainerSize();
281
+ const { ref: svgRef, width: measuredWidth, height: measuredHeight } = useContainerSize();
282
+ const containerWidth = measuredWidth * coordinateScale;
283
+ const containerHeight = measuredHeight * coordinateScale;
280
284
  const history = useHistory();
281
285
  const drawing = useDrawing();
282
286
  const { viewMin, viewMax, zoomAt, panByFraction, resetView } = useZoom({
@@ -293,7 +297,9 @@ function NumberLineProvider({
293
297
  const eraseGesture = React.useRef(null);
294
298
  const createHistorySnapshot = React.useCallback(
295
299
  (strokesOverride) => ({
296
- strokes: (strokesOverride ?? drawing.strokes).map((stroke) => ({ ...stroke })),
300
+ strokes: (strokesOverride ?? drawing.strokes).map((stroke) => ({
301
+ ...stroke
302
+ })),
297
303
  deletedArcIndices: [...deletedArcIndices],
298
304
  selectedArcIndices: [...selectedArcIndices],
299
305
  groupTicksHidden
@@ -309,26 +315,21 @@ function NumberLineProvider({
309
315
  setDeletedArcIndices(/* @__PURE__ */ new Set());
310
316
  setSelectedArcIndices(/* @__PURE__ */ new Set());
311
317
  setGroupTicksHidden(false);
312
- }, [
313
- domainMin,
314
- domainMax,
315
- groupSize,
316
- groupCount,
317
- tickStep,
318
- drawing.resetStrokes,
319
- history.clear
320
- ]);
321
- const getLocalCoords = React.useCallback((event) => {
322
- const svg = svgRef.current;
323
- if (!svg) return null;
324
- const rect = svg.getBoundingClientRect();
325
- const viewBox = svg.viewBox.baseVal;
326
- if (rect.width <= 0 || rect.height <= 0 || viewBox.width <= 0 || viewBox.height <= 0) return null;
327
- return [
328
- viewBox.x + (event.clientX - rect.left) / rect.width * viewBox.width,
329
- viewBox.y + (event.clientY - rect.top) / rect.height * viewBox.height
330
- ];
331
- }, [svgRef]);
318
+ }, [domainMin, domainMax, groupSize, groupCount, tickStep, drawing.resetStrokes, history.clear]);
319
+ const getLocalCoords = React.useCallback(
320
+ (event) => {
321
+ const svg = svgRef.current;
322
+ if (!svg) return null;
323
+ const rect = svg.getBoundingClientRect();
324
+ const viewBox = svg.viewBox.baseVal;
325
+ if (rect.width <= 0 || rect.height <= 0 || viewBox.width <= 0 || viewBox.height <= 0) return null;
326
+ return [
327
+ viewBox.x + (event.clientX - rect.left) / rect.width * viewBox.width,
328
+ viewBox.y + (event.clientY - rect.top) / rect.height * viewBox.height
329
+ ];
330
+ },
331
+ [svgRef]
332
+ );
332
333
  const strokeIdsNear = React.useCallback(
333
334
  (x, y, radius) => {
334
335
  const ids = [];
@@ -385,8 +386,7 @@ function NumberLineProvider({
385
386
  } else {
386
387
  const nextIds = strokeIdsNear(coords2[0], coords2[1], radius);
387
388
  setEraseHoverIds((prev) => {
388
- if (nextIds.length === prev.size && nextIds.every((id) => prev.has(id)))
389
- return prev;
389
+ if (nextIds.length === prev.size && nextIds.every((id) => prev.has(id))) return prev;
390
390
  return new Set(nextIds);
391
391
  });
392
392
  }
@@ -458,9 +458,7 @@ function NumberLineProvider({
458
458
  }, [drawing, history, selectedArcIndices, createHistorySnapshot]);
459
459
  const clearAll = React.useCallback(() => {
460
460
  const arcCount = Math.max(0, Math.ceil(Number(groupCount) || 0));
461
- const allArcsDeleted = deletedArcIndices.size >= arcCount && Array.from({ length: arcCount }, (_, index) => index).every(
462
- (index) => deletedArcIndices.has(index)
463
- );
461
+ const allArcsDeleted = deletedArcIndices.size >= arcCount && Array.from({ length: arcCount }, (_, index) => index).every((index) => deletedArcIndices.has(index));
464
462
  const alreadyClear = drawing.strokes.length === 0 && selectedArcIndices.size === 0 && allArcsDeleted && groupTicksHidden;
465
463
  if (alreadyClear) return;
466
464
  history.push(createHistorySnapshot());
@@ -471,15 +469,7 @@ function NumberLineProvider({
471
469
  setDeletedArcIndices(new Set(Array.from({ length: arcCount }, (_, i) => i)));
472
470
  setSelectedArcIndices(/* @__PURE__ */ new Set());
473
471
  setGroupTicksHidden(true);
474
- }, [
475
- drawing,
476
- history,
477
- groupCount,
478
- deletedArcIndices,
479
- selectedArcIndices,
480
- groupTicksHidden,
481
- createHistorySnapshot
482
- ]);
472
+ }, [drawing, history, groupCount, deletedArcIndices, selectedArcIndices, groupTicksHidden, createHistorySnapshot]);
483
473
  const onReset = clearAll;
484
474
  const showAllArcs = React.useCallback(() => {
485
475
  setDeletedArcIndices((prev) => prev.size === 0 ? prev : /* @__PURE__ */ new Set());
@@ -496,27 +486,33 @@ function NumberLineProvider({
496
486
  eraseGesture.current = null;
497
487
  setEraseHoverIds(/* @__PURE__ */ new Set());
498
488
  }, [history, drawing]);
499
- const onTogglePen = React.useCallback(
500
- () => {
501
- drawing.toggleTool("pen");
502
- clearArcSelection();
503
- },
504
- [drawing, clearArcSelection]
505
- );
506
- const onToggleEraser = React.useCallback(
507
- () => {
508
- drawing.toggleTool("eraser");
509
- clearArcSelection();
510
- },
511
- [drawing, clearArcSelection]
512
- );
489
+ const onTogglePen = React.useCallback(() => {
490
+ drawing.toggleTool("pen");
491
+ clearArcSelection();
492
+ }, [drawing, clearArcSelection]);
493
+ const onToggleEraser = React.useCallback(() => {
494
+ drawing.toggleTool("eraser");
495
+ clearArcSelection();
496
+ }, [drawing, clearArcSelection]);
513
497
  const canDelete = drawing.strokes.some((s) => s.selected) || selectedArcIndices.size > 0;
514
498
  React.useEffect(() => {
515
499
  setSelectedArcIndices(/* @__PURE__ */ new Set());
516
500
  setEraseHoverIds((prev) => prev.size === 0 ? prev : /* @__PURE__ */ new Set());
517
501
  }, [drawing.tool]);
518
- const keyHandlers = React.useRef({ toggleTool: drawing.toggleTool, clearArcSelection, canDelete, onDelete, onUndo });
519
- keyHandlers.current = { toggleTool: drawing.toggleTool, clearArcSelection, canDelete, onDelete, onUndo };
502
+ const keyHandlers = React.useRef({
503
+ toggleTool: drawing.toggleTool,
504
+ clearArcSelection,
505
+ canDelete,
506
+ onDelete,
507
+ onUndo
508
+ });
509
+ keyHandlers.current = {
510
+ toggleTool: drawing.toggleTool,
511
+ clearArcSelection,
512
+ canDelete,
513
+ onDelete,
514
+ onUndo
515
+ };
520
516
  React.useEffect(() => {
521
517
  const svg = svgRef.current;
522
518
  if (!svg) return;
package/dist/index.d.ts CHANGED
@@ -64,6 +64,14 @@ export declare interface NumberLineProps {
64
64
  tickStep: number;
65
65
  /** 用户自由绘制笔迹的固定视觉线宽，单位为 CSS 像素；默认 2.5。 */
66
66
  strokeWidth?: number;
67
+ /**
68
+ * SVG 逻辑坐标相对于实际 CSS 像素的倍率；默认 1。
69
+ *
70
+ * 大于 1 时只扩大内部 viewBox 和布局计算使用的坐标，不改变 SVG 元素本身的
71
+ * CSS 宽高。宿主可在整体 rem 缩放的场景传入反向倍率，使标签密度、弧线位置和
72
+ * 指针坐标仍以设计稿尺寸计算，同时避免 CSS transform 产生独立合成层。
73
+ */
74
+ coordinateScale?: number;
67
75
  arcColors?: string[];
68
76
  /** show group boundary ticks (tallest). Default: true */
69
77
  showGroupTicks?: boolean;
@@ -91,7 +99,7 @@ export declare interface NumberLineProps {
91
99
  getShowLabelStep?: (params: unknown) => boolean;
92
100
  }
93
101
 
94
- export declare function NumberLineProvider({ min, max, groupSize, groupCount, tickStep, strokeWidth: configuredStrokeWidth, arcColors, showGroupTicks, showMajorTicks, showMinorTicks, enableZoom, minZoom, maxZoom, showLabelStep, viewMin: controlledViewMin, viewMax: controlledViewMax, getShowLabelStep, onViewChange, children, }: NumberLineProviderProps): JSX_2.Element;
102
+ export declare function NumberLineProvider({ min, max, groupSize, groupCount, tickStep, strokeWidth: configuredStrokeWidth, coordinateScale: configuredCoordinateScale, arcColors, showGroupTicks, showMajorTicks, showMinorTicks, enableZoom, minZoom, maxZoom, showLabelStep, viewMin: controlledViewMin, viewMax: controlledViewMax, getShowLabelStep, onViewChange, children, }: NumberLineProviderProps): JSX_2.Element;
95
103
 
96
104
  declare interface NumberLineProviderProps extends NumberLineProps {
97
105
  children: default_2.ReactNode;
package/dist/index.js CHANGED
@@ -255,6 +255,7 @@ function NumberLineProvider({
255
255
  groupCount,
256
256
  tickStep,
257
257
  strokeWidth: configuredStrokeWidth,
258
+ coordinateScale: configuredCoordinateScale = 1,
258
259
  arcColors,
259
260
  showGroupTicks = true,
260
261
  showMajorTicks = true,
@@ -271,10 +272,13 @@ function NumberLineProvider({
271
272
  }) {
272
273
  const { min: domainMin, max: domainMax } = normalizeDomain(min, max);
273
274
  const strokeWidth = typeof configuredStrokeWidth === "number" && Number.isFinite(configuredStrokeWidth) && configuredStrokeWidth > 0 ? configuredStrokeWidth : DEFAULT_DRAWING_STROKE_WIDTH;
275
+ const coordinateScale = typeof configuredCoordinateScale === "number" && Number.isFinite(configuredCoordinateScale) && configuredCoordinateScale > 0 ? configuredCoordinateScale : 1;
274
276
  const [selectedArcIndices, setSelectedArcIndices] = useState(/* @__PURE__ */ new Set());
275
277
  const [deletedArcIndices, setDeletedArcIndices] = useState(/* @__PURE__ */ new Set());
276
278
  const [groupTicksHidden, setGroupTicksHidden] = useState(false);
277
- const { ref: svgRef, width: containerWidth, height: containerHeight } = useContainerSize();
279
+ const { ref: svgRef, width: measuredWidth, height: measuredHeight } = useContainerSize();
280
+ const containerWidth = measuredWidth * coordinateScale;
281
+ const containerHeight = measuredHeight * coordinateScale;
278
282
  const history = useHistory();
279
283
  const drawing = useDrawing();
280
284
  const { viewMin, viewMax, zoomAt, panByFraction, resetView } = useZoom({
@@ -291,7 +295,9 @@ function NumberLineProvider({
291
295
  const eraseGesture = useRef(null);
292
296
  const createHistorySnapshot = useCallback(
293
297
  (strokesOverride) => ({
294
- strokes: (strokesOverride ?? drawing.strokes).map((stroke) => ({ ...stroke })),
298
+ strokes: (strokesOverride ?? drawing.strokes).map((stroke) => ({
299
+ ...stroke
300
+ })),
295
301
  deletedArcIndices: [...deletedArcIndices],
296
302
  selectedArcIndices: [...selectedArcIndices],
297
303
  groupTicksHidden
@@ -307,26 +313,21 @@ function NumberLineProvider({
307
313
  setDeletedArcIndices(/* @__PURE__ */ new Set());
308
314
  setSelectedArcIndices(/* @__PURE__ */ new Set());
309
315
  setGroupTicksHidden(false);
310
- }, [
311
- domainMin,
312
- domainMax,
313
- groupSize,
314
- groupCount,
315
- tickStep,
316
- drawing.resetStrokes,
317
- history.clear
318
- ]);
319
- const getLocalCoords = useCallback((event) => {
320
- const svg = svgRef.current;
321
- if (!svg) return null;
322
- const rect = svg.getBoundingClientRect();
323
- const viewBox = svg.viewBox.baseVal;
324
- if (rect.width <= 0 || rect.height <= 0 || viewBox.width <= 0 || viewBox.height <= 0) return null;
325
- return [
326
- viewBox.x + (event.clientX - rect.left) / rect.width * viewBox.width,
327
- viewBox.y + (event.clientY - rect.top) / rect.height * viewBox.height
328
- ];
329
- }, [svgRef]);
316
+ }, [domainMin, domainMax, groupSize, groupCount, tickStep, drawing.resetStrokes, history.clear]);
317
+ const getLocalCoords = useCallback(
318
+ (event) => {
319
+ const svg = svgRef.current;
320
+ if (!svg) return null;
321
+ const rect = svg.getBoundingClientRect();
322
+ const viewBox = svg.viewBox.baseVal;
323
+ if (rect.width <= 0 || rect.height <= 0 || viewBox.width <= 0 || viewBox.height <= 0) return null;
324
+ return [
325
+ viewBox.x + (event.clientX - rect.left) / rect.width * viewBox.width,
326
+ viewBox.y + (event.clientY - rect.top) / rect.height * viewBox.height
327
+ ];
328
+ },
329
+ [svgRef]
330
+ );
330
331
  const strokeIdsNear = useCallback(
331
332
  (x, y, radius) => {
332
333
  const ids = [];
@@ -383,8 +384,7 @@ function NumberLineProvider({
383
384
  } else {
384
385
  const nextIds = strokeIdsNear(coords2[0], coords2[1], radius);
385
386
  setEraseHoverIds((prev) => {
386
- if (nextIds.length === prev.size && nextIds.every((id) => prev.has(id)))
387
- return prev;
387
+ if (nextIds.length === prev.size && nextIds.every((id) => prev.has(id))) return prev;
388
388
  return new Set(nextIds);
389
389
  });
390
390
  }
@@ -456,9 +456,7 @@ function NumberLineProvider({
456
456
  }, [drawing, history, selectedArcIndices, createHistorySnapshot]);
457
457
  const clearAll = useCallback(() => {
458
458
  const arcCount = Math.max(0, Math.ceil(Number(groupCount) || 0));
459
- const allArcsDeleted = deletedArcIndices.size >= arcCount && Array.from({ length: arcCount }, (_, index) => index).every(
460
- (index) => deletedArcIndices.has(index)
461
- );
459
+ const allArcsDeleted = deletedArcIndices.size >= arcCount && Array.from({ length: arcCount }, (_, index) => index).every((index) => deletedArcIndices.has(index));
462
460
  const alreadyClear = drawing.strokes.length === 0 && selectedArcIndices.size === 0 && allArcsDeleted && groupTicksHidden;
463
461
  if (alreadyClear) return;
464
462
  history.push(createHistorySnapshot());
@@ -469,15 +467,7 @@ function NumberLineProvider({
469
467
  setDeletedArcIndices(new Set(Array.from({ length: arcCount }, (_, i) => i)));
470
468
  setSelectedArcIndices(/* @__PURE__ */ new Set());
471
469
  setGroupTicksHidden(true);
472
- }, [
473
- drawing,
474
- history,
475
- groupCount,
476
- deletedArcIndices,
477
- selectedArcIndices,
478
- groupTicksHidden,
479
- createHistorySnapshot
480
- ]);
470
+ }, [drawing, history, groupCount, deletedArcIndices, selectedArcIndices, groupTicksHidden, createHistorySnapshot]);
481
471
  const onReset = clearAll;
482
472
  const showAllArcs = useCallback(() => {
483
473
  setDeletedArcIndices((prev) => prev.size === 0 ? prev : /* @__PURE__ */ new Set());
@@ -494,27 +484,33 @@ function NumberLineProvider({
494
484
  eraseGesture.current = null;
495
485
  setEraseHoverIds(/* @__PURE__ */ new Set());
496
486
  }, [history, drawing]);
497
- const onTogglePen = useCallback(
498
- () => {
499
- drawing.toggleTool("pen");
500
- clearArcSelection();
501
- },
502
- [drawing, clearArcSelection]
503
- );
504
- const onToggleEraser = useCallback(
505
- () => {
506
- drawing.toggleTool("eraser");
507
- clearArcSelection();
508
- },
509
- [drawing, clearArcSelection]
510
- );
487
+ const onTogglePen = useCallback(() => {
488
+ drawing.toggleTool("pen");
489
+ clearArcSelection();
490
+ }, [drawing, clearArcSelection]);
491
+ const onToggleEraser = useCallback(() => {
492
+ drawing.toggleTool("eraser");
493
+ clearArcSelection();
494
+ }, [drawing, clearArcSelection]);
511
495
  const canDelete = drawing.strokes.some((s) => s.selected) || selectedArcIndices.size > 0;
512
496
  useEffect(() => {
513
497
  setSelectedArcIndices(/* @__PURE__ */ new Set());
514
498
  setEraseHoverIds((prev) => prev.size === 0 ? prev : /* @__PURE__ */ new Set());
515
499
  }, [drawing.tool]);
516
- const keyHandlers = useRef({ toggleTool: drawing.toggleTool, clearArcSelection, canDelete, onDelete, onUndo });
517
- keyHandlers.current = { toggleTool: drawing.toggleTool, clearArcSelection, canDelete, onDelete, onUndo };
500
+ const keyHandlers = useRef({
501
+ toggleTool: drawing.toggleTool,
502
+ clearArcSelection,
503
+ canDelete,
504
+ onDelete,
505
+ onUndo
506
+ });
507
+ keyHandlers.current = {
508
+ toggleTool: drawing.toggleTool,
509
+ clearArcSelection,
510
+ canDelete,
511
+ onDelete,
512
+ onUndo
513
+ };
518
514
  useEffect(() => {
519
515
  const svg = svgRef.current;
520
516
  if (!svg) return;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dcg-overseas/number-line",
3
- "version": "1.0.0-beta.4",
3
+ "version": "1.0.0-beta.5",
4
4
  "description": "Interactive number line component with group arcs and freehand drawing",
5
5
  "type": "module",
6
6
  "license": "MIT",