@dcg-overseas/number-line 0.1.2 → 0.1.4

package/README.md

@@ -0,0 +1,255 @@
+# @dcg-overseas/number-line
+
+交互式数轴组件，支持分组弧线（带箭头终点标签）、自由画笔、橡皮擦、撤销与键盘快捷键。
+
+- 容器自适应：`viewBox` 跟随容器实际像素，文字和线条始终保持设计尺寸
+- 笔迹归一化存储（`[0,1]` 坐标 + `vectorEffect="non-scaling-stroke"`），容器 resize 后笔迹位置稳定不漂移
+- Provider/Component 解耦：状态在 `NumberLineProvider` 中管理，工具栏与数轴 SVG 各自独立组装
+
+---
+
+## 安装
+
+```bash
+pnpm add @dcg-overseas/number-line
+# peer deps
+pnpm add react react-dom
+```
+
+---
+
+## 快速开始
+
+```tsx
+import { NumberLineProvider, NumberLine } from '@dcg-overseas/number-line'
+
+function Demo() {
+  return (
+    <NumberLineProvider
+      min={0}
+      max={100}
+      groupSize={10}
+      groupCount={10}
+      tickStep={5}
+    >
+      <div style={{ width: '100%', height: 200 }}>
+        <NumberLine />
+      </div>
+    </NumberLineProvider>
+  )
+}
+```
+
+> ⚠️ **必须给 `<NumberLine />` 的父容器明确的宽高**（CSS 尺寸或 flex 布局），SVG 默认 `width:100% height:100%`，没有外部尺寸约束会塌陷为 0。
+
+---
+
+## API
+
+### `<NumberLineProvider>`
+
+数轴的状态根。包裹任何需要访问数轴上下文的子组件（`<NumberLine />` 和你自己的工具栏按钮）。
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|-------|------|
+| `min` | `number` | — | 数轴起点值（含） |
+| `max` | `number` | — | 数轴终点值（含） |
+| `groupSize` | `number` | — | 每组弧线跨度（数轴单位）。例：`groupSize=8` 表示每段弧从 `n` 跳到 `n+8` |
+| `groupCount` | `number` | — | 弧线组数。从 `min` 起依次绘制 `groupCount` 段弧线 |
+| `tickStep` | `number` | — | 主刻度步长（数轴单位）。例：`tickStep=5` 表示 0、5、10、15… 为主刻度 |
+| `arcColors` | `string[]` | 5 色循环 | 弧线颜色数组，按 `groupIndex % length` 轮换。默认值见 [`utils/geometry.ts` ARC_COLORS](src/utils/geometry.ts) |
+| `showGroupTicks` | `boolean` | `true` | 是否显示分组边界刻度（最长，10px） |
+| `showMajorTicks` | `boolean` | `true` | 是否显示主刻度（中等，7px） |
+| `showMinorTicks` | `boolean` | `false` | 是否显示次刻度（最短，4px）。默认隐藏 |
+| `children` | `ReactNode` | — | 子节点（必须包含 `<NumberLine />` 或自定义渲染器） |
+
+#### 弧线生成规则
+
+```
+弧线 g 的范围：[min + g*groupSize, min + (g+1)*groupSize]
+g ∈ [0, groupCount)
+若 (min + (g+1)*groupSize) > max，弧线提前停止
+```
+
+#### 三档刻度优先级
+
+一个位置可能同时是多档刻度（例如 `tickStep=5, groupSize=10` 时，10 既是主刻度也是分组边界）。视觉与可见性按 **分组边界 > 主刻度 > 次刻度** 归类，仅看其最高档对应的 `show*Ticks`。
+
+```tsx
+// 默认：只显示主刻度 + 分组边界
+<NumberLineProvider min={0} max={100} groupSize={10} groupCount={10} tickStep={5} />
+
+// 显示全部三档刻度
+<NumberLineProvider ... showMinorTicks />
+
+// 极简模式：仅分组边界
+<NumberLineProvider ... showMajorTicks={false} />
+```
+
+---
+
+### `<NumberLine>`
+
+数轴 SVG 视图。必须放在 `<NumberLineProvider>` 内，自动从 context 读取所有配置和事件处理。
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|-------|------|
+| `className` | `string?` | — | 追加到 SVG 根节点的 className（基础类名 `nl-svg`） |
+
+**渲染层级（从下到上）：**
+1. `AxisLayer` — 数轴线 + 刻度 + 标签
+2. `GroupArcsLayer` — 分组弧线 + 弧顶箭头标签 + 选中高亮
+3. `DrawingLayer` — 用户笔迹（normalized `[0,1]` 坐标，scale 还原）
+
+**布局参数（内部常量，无需配置）：**
+
+| 名称 | 值 | 含义 |
+|------|---|------|
+| `PAD_LEFT` | 30 | 数轴左 padding |
+| `PAD_RIGHT` | 40 | 数轴右 padding |
+| `AXIS_BOTTOM_OFFSET` | 50 | 数轴线距容器底部像素（给刻度数字留空间） |
+| `ARC_TOP_PADDING` | 16 | 弧线顶部距容器顶部像素 |
+| `MIN_ARC_HEIGHT` | 24 | 弧线最小高度（容器极小时兜底） |
+
+---
+
+### `useNumberLineContext()`
+
+读取 / 操作数轴状态的 hook。**必须在 `<NumberLineProvider>` 子树内调用**，否则抛错。
+
+返回 `NumberLineContextValue`：
+
+#### 布局
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `svgRef` | `RefObject<SVGSVGElement>` | SVG 元素 ref |
+| `containerWidth` | `number` | 容器实际像素宽 |
+| `containerHeight` | `number` | 容器实际像素高 |
+| `svgCursor` | `string` | 当前 SVG cursor（自动随 tool 切换） |
+
+#### 配置（透传自 Provider props）
+| 字段 | 类型 |
+|------|------|
+| `min` `max` `groupSize` `groupCount` `tickStep` | `number` |
+| `arcColors` | `string[] \| undefined` |
+| `showGroupTicks` `showMajorTicks` `showMinorTicks` | `boolean` |
+
+#### 绘图状态
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `tool` | `'none' \| 'pen' \| 'eraser'` | 当前工具 |
+| `strokes` | `Stroke[]` | 已落笔的所有笔迹 |
+| `liveStroke` | `Stroke \| null` | 正在绘制中的笔迹（半透明预览） |
+| `selectedArcIndices` | `Set<number>` | 当前选中的弧线 group index |
+| `deletedArcIndices` | `Set<number>` | 已被擦除/删除的弧线 group index |
+
+#### 事件回调（已绑定到 `<NumberLine>`，自定义渲染时使用）
+| 字段 | 类型 |
+|------|------|
+| `onPointerDown` `onPointerMove` `onPointerUp` | `(e: PointerEvent) => void` |
+| `onStrokeClick` | `(id: string, e: PointerEvent) => void` |
+| `onArcClick` | `(groupIndex: number, e: PointerEvent) => void` |
+
+#### 工具栏 API
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `canDelete` | `boolean` | 是否有可删除的选中项（笔迹或弧线） |
+| `canUndo` | `boolean` | 是否有可撤销的操作 |
+| `onTogglePen` | `() => void` | 切换画笔工具 |
+| `onToggleEraser` | `() => void` | 切换橡皮擦 |
+| `onDelete` | `() => void` | 删除当前选中 |
+| `onReset` | `() => void` | 清空所有笔迹和弧线删除记录 |
+| `onUndo` | `() => void` | 撤销上一步操作 |
+
+---
+
+## 自定义工具栏示例
+
+`<NumberLine>` 不附带工具栏。把按钮和数轴一起放在 `<NumberLineProvider>` 下，通过 `useNumberLineContext` 接入：
+
+```tsx
+import { NumberLineProvider, NumberLine, useNumberLineContext } from '@dcg-overseas/number-line'
+
+function Toolbar() {
+  const { tool, canDelete, canUndo, onTogglePen, onToggleEraser, onDelete, onReset, onUndo } =
+    useNumberLineContext()
+
+  return (
+    <div className="flex gap-2">
+      <button data-active={tool === 'pen'} onClick={onTogglePen}>✏️ 画笔</button>
+      <button data-active={tool === 'eraser'} onClick={onToggleEraser}>🩹 擦除</button>
+      <button disabled={!canDelete} onClick={onDelete}>🗑 删除</button>
+      <button onClick={onReset}>♻️ 重置</button>
+      <button disabled={!canUndo} onClick={onUndo}>↶ 撤销</button>
+    </div>
+  )
+}
+
+function App() {
+  return (
+    <NumberLineProvider min={0} max={80} groupSize={8} groupCount={10} tickStep={1}>
+      <Toolbar />
+      <div style={{ height: 220 }}>
+        <NumberLine />
+      </div>
+    </NumberLineProvider>
+  )
+}
+```
+
+---
+
+## 键盘快捷键
+
+快捷键绑定在 SVG 元素上（`tabIndex={0}`，需先聚焦 SVG），多实例互不干扰，也不会拦截外部输入框。
+
+| 按键 | 行为 |
+|------|------|
+| `Esc` | 切回 `'none'` 模式，清空弧线选中 |
+| `Delete` / `Backspace` | 删除当前选中的笔迹和弧线 |
+| `Ctrl+Z` / `Cmd+Z` | 撤销上一步 |
+
+---
+
+## 类型导出
+
+```ts
+import type {
+  NumberLineProps,
+  NumberLineContextValue,
+} from '@dcg-overseas/number-line'
+```
+
+完整类型见 [src/types.ts](src/types.ts) 与 [src/context/NumberLineContext.ts](src/context/NumberLineContext.ts)。
+
+---
+
+## 设计要点
+
+### 自适应坐标系
+
+`viewBox` 动态跟随容器实际像素（`viewBox={`0 0 ${w} ${h}`}` + `preserveAspectRatio="none"`），1 SVG 单位 = 1 CSS 像素。这样：
+
+- 文字和线条始终是设计尺寸（fontSize=11 永远是 11px），不会因为容器纵横比异常被缩到看不见
+- 数轴自动贴近容器底部，弧线撑满上方空间，无空白浪费
+
+### 笔迹归一化（resize 稳定）
+
+笔迹存储为 `[0, 1]` 归一化坐标（`M 0.234 0.456 L ...`）。渲染时用 `<g transform={`scale(${w} ${h})`}>` 还原到容器像素，并配合 `vectorEffect="non-scaling-stroke"` 锁定线宽。
+
+效果：容器从 `400×200` 变成 `600×300`，所有笔迹的相对位置仍然贴合数轴，stroke 宽度保持 2.5px。
+
+### 操作级撤销
+
+撤销栈记录的是「操作」而非「状态」（`HistoryOp`），分两类：
+
+- `add` — 新增笔迹，撤销 = 移除指定 id
+- `delete` — 删除笔迹/弧线，撤销 = 恢复删除前完整快照 + 还原弧线 group index
+
+这样即使一次 `delete` 同时删了多条笔迹和多条弧线，撤销也能精确还原。
+
+---
+
+## License
+
+MIT

package/dist/index.cjs

@@ -47,16 +47,20 @@ function useDrawing() {
     });
     setStrokes((prev) => prev.map((s) => ({ ...s, selected: false })));
   }, []);
-  const startStroke = React.useCallback((x, y) => {
+  const startStroke = React.useCallback((x, y, w, h) => {
     drawing.current = true;
     pointCount.current = 1;
-    currentD.current = `M ${x} ${y}`;
+    const xN = w > 0 ? x / w : 0;
+    const yN = h > 0 ? y / h : 0;
+    currentD.current = `M ${xN} ${yN}`;
     currentId.current = `${Date.now()}-${Math.random()}`;
   }, []);
-  const continueStroke = React.useCallback((x, y) => {
+  const continueStroke = React.useCallback((x, y, w, h) => {
     if (!drawing.current) return null;
     pointCount.current++;
-    currentD.current += ` L ${x} ${y}`;
+    const xN = w > 0 ? x / w : 0;
+    const yN = h > 0 ? y / h : 0;
+    currentD.current += ` L ${xN} ${yN}`;
     return {
       id: currentId.current,
       d: currentD.current,
@@ -117,21 +121,29 @@ function useDrawing() {
 }
 function useContainerSize() {
   const ref = React.useRef(null);
-  const [width, setWidth] = React.useState(600);
+  const [size, setSize] = React.useState({ width: 600, height: 200 });
+  React.useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const rect = el.getBoundingClientRect();
+    if (rect.width > 0 && rect.height > 0) {
+      setSize({ width: rect.width, height: rect.height });
+    }
+  }, []);
   React.useEffect(() => {
     const el = ref.current;
     if (!el) return;
     const ro = new ResizeObserver((entries) => {
       var _a;
-      const w = (_a = entries[0]) == null ? void 0 : _a.contentRect.width;
-      if (w && w > 0) setWidth(w);
+      const rect = (_a = entries[0]) == null ? void 0 : _a.contentRect;
+      if (rect && rect.width > 0 && rect.height > 0) {
+        setSize({ width: rect.width, height: rect.height });
+      }
     });
     ro.observe(el);
-    const rect = el.getBoundingClientRect();
-    if (rect.width > 0) setWidth(rect.width);
     return () => ro.disconnect();
   }, []);
-  return { ref, width };
+  return { ref, width: size.width, height: size.height };
 }
 const NumberLineContext = React.createContext(null);
 function useNumberLineContext() {
@@ -139,8 +151,6 @@ function useNumberLineContext() {
   if (!ctx) throw new Error("Must be used inside <NumberLineProvider>");
   return ctx;
 }
-const DESIGN_WIDTH = 1e3;
-const DESIGN_HEIGHT = 200;
 function NumberLineProvider({
   min,
   max,
@@ -148,11 +158,14 @@ function NumberLineProvider({
   groupCount,
   tickStep,
   arcColors,
+  showGroupTicks = true,
+  showMajorTicks = true,
+  showMinorTicks = false,
   children
 }) {
   const [selectedArcIndices, setSelectedArcIndices] = React.useState(/* @__PURE__ */ new Set());
   const [deletedArcIndices, setDeletedArcIndices] = React.useState(/* @__PURE__ */ new Set());
-  const { ref: svgRef, width: containerWidth } = useContainerSize();
+  const { ref: svgRef, width: containerWidth, height: containerHeight } = useContainerSize();
   const history = useHistory();
   const drawing = useDrawing();
   const [liveStroke, setLiveStroke] = React.useState(null);
@@ -182,19 +195,19 @@ function NumberLineProvider({
       e.currentTarget.setPointerCapture(e.pointerId);
       const coords = getLocalCoords(e);
       if (!coords) return;
-      drawing.startStroke(...coords);
+      drawing.startStroke(coords[0], coords[1], containerWidth, containerHeight);
     },
-    [drawing, getLocalCoords]
+    [drawing, getLocalCoords, containerWidth, containerHeight]
   );
   const onPointerMove = React.useCallback(
     (e) => {
       if (drawing.tool !== "pen") return;
       const coords = getLocalCoords(e);
       if (!coords) return;
-      const live = drawing.continueStroke(...coords);
+      const live = drawing.continueStroke(coords[0], coords[1], containerWidth, containerHeight);
       if (live) setLiveStroke(live);
     },
-    [drawing, getLocalCoords]
+    [drawing, getLocalCoords, containerWidth, containerHeight]
   );
   const onPointerUp = React.useCallback(() => {
     if (drawing.tool !== "pen") return;
@@ -314,8 +327,8 @@ function NumberLineProvider({
     {
       value: {
         svgRef,
-        viewWidth: DESIGN_WIDTH,
         containerWidth,
+        containerHeight,
         svgCursor,
         min,
         max,
@@ -323,6 +336,9 @@ function NumberLineProvider({
         groupCount,
         tickStep,
         arcColors,
+        showGroupTicks,
+        showMajorTicks,
+        showMinorTicks,
         tool: drawing.tool,
         strokes: drawing.strokes,
         liveStroke,
@@ -362,6 +378,12 @@ const ARC_COLORS = [
   "#be185d",
   "#16a34a"
 ];
+function gcd(a, b) {
+  let x = Math.max(1, Math.abs(Math.round(a)));
+  let y = Math.max(1, Math.abs(Math.round(b)));
+  while (y !== 0) [x, y] = [y, x % y];
+  return x;
+}
 const AxisLayer = React.memo(function AxisLayer2({
   min,
   max,
@@ -371,7 +393,10 @@ const AxisLayer = React.memo(function AxisLayer2({
   viewWidth,
   containerWidth,
   groupSize,
-  tickStep
+  tickStep,
+  showGroupTicks,
+  showMajorTicks,
+  showMinorTicks
 }) {
   const range = max - min;
   if (range <= 0) return null;
@@ -381,9 +406,11 @@ const AxisLayer = React.memo(function AxisLayer2({
   const rawLabelStep = computeLabelStep(containerWidth, range);
   const labelStep = Math.max(step, Math.ceil(rawLabelStep / step) * step);
   const MAX_TICKS = 500;
-  const minorStep = Math.max(1, Math.ceil(range / MAX_TICKS));
+  const capStep = Math.max(1, Math.ceil(range / MAX_TICKS));
+  const visibleStep = groupSize > 0 ? gcd(step, groupSize) : step;
+  const iterStep = showMinorTicks ? capStep : Math.max(capStep, visibleStep);
   const allTicks = [];
-  for (let v = min; v <= max; v += minorStep) allTicks.push(v);
+  for (let v = min; v <= max; v += iterStep) allTicks.push(v);
   return /* @__PURE__ */ jsxRuntime.jsxs("g", { className: "nl-axis-layer", children: [
     /* @__PURE__ */ jsxRuntime.jsx(
       "line",
@@ -401,10 +428,14 @@ const AxisLayer = React.memo(function AxisLayer2({
       const offset = v - min;
       const isMajor = offset % step === 0;
       const isGroupBoundary = groupSize > 0 && offset % groupSize === 0;
-      const showLabel = isMajor && offset % labelStep === 0;
-      const tickH = isGroupBoundary ? 10 : isMajor ? 7 : 4;
-      const strokeW = isGroupBoundary ? 1.5 : isMajor ? 1 : 0.5;
-      const color = isMajor ? "#374151" : "#9ca3af";
+      const visible = isGroupBoundary && showGroupTicks || isMajor && showMajorTicks || !isGroupBoundary && !isMajor && showMinorTicks;
+      if (!visible) return null;
+      const renderAsGroup = isGroupBoundary && showGroupTicks;
+      const renderAsMajor = !renderAsGroup && isMajor && showMajorTicks;
+      const showLabel = (renderAsGroup || renderAsMajor) && offset % labelStep === 0;
+      const tickH = renderAsGroup ? 7 : renderAsMajor ? 10 : 4;
+      const strokeW = renderAsGroup ? 1.5 : renderAsMajor ? 1 : 0.5;
+      const color = renderAsGroup || renderAsMajor ? "#374151" : "#9ca3af";
       return /* @__PURE__ */ jsxRuntime.jsxs("g", { children: [
         /* @__PURE__ */ jsxRuntime.jsx(
           "line",
@@ -465,9 +496,10 @@ const GroupArcsLayer = React.memo(function GroupArcsLayer2({
     const rx = (x2 - x1) / 2;
     const ry = Math.min(rx * 0.7, arcMaxHeight);
     const color = arcColors[g % arcColors.length];
-    const textY = axisY - ry - 6;
     const arrowHeadH = 7;
     const arrowHeadHW = 4;
+    const MIN_ARROW_SPAN = 18;
+    const textY = Math.min(axisY - ry - 6, axisY - MIN_ARROW_SPAN);
     const arcPath = buildArcPath({ x1, x2, y: axisY, rx, ry });
     const isSelected = selectedArcIndices.has(g);
     const hitCursor = tool === "eraser" ? "cell" : tool === "none" ? "pointer" : "default";
@@ -551,8 +583,8 @@ const GroupArcsLayer = React.memo(function GroupArcsLayer2({
   }
   return /* @__PURE__ */ jsxRuntime.jsx("g", { className: "nl-arcs-layer", children: arcs });
 });
-function DrawingLayer({ strokes, liveStroke, tool, onStrokeClick }) {
-  return /* @__PURE__ */ jsxRuntime.jsxs("g", { className: "nl-drawing-layer", children: [
+function DrawingLayer({ strokes, liveStroke, tool, width, height, onStrokeClick }) {
+  return /* @__PURE__ */ jsxRuntime.jsxs("g", { className: "nl-drawing-layer", transform: `scale(${width} ${height})`, children: [
     strokes.map((s) => /* @__PURE__ */ jsxRuntime.jsxs("g", { children: [
       s.selected && /* @__PURE__ */ jsxRuntime.jsx(
         "path",
@@ -563,6 +595,7 @@ function DrawingLayer({ strokes, liveStroke, tool, onStrokeClick }) {
           strokeWidth: 18,
           strokeLinecap: "round",
           strokeLinejoin: "round",
+          vectorEffect: "non-scaling-stroke",
           pointerEvents: "none"
         }
       ),
@@ -575,6 +608,7 @@ function DrawingLayer({ strokes, liveStroke, tool, onStrokeClick }) {
           strokeWidth: tool === "eraser" ? 32 : 28,
           strokeLinecap: "round",
           strokeLinejoin: "round",
+          vectorEffect: "non-scaling-stroke",
           pointerEvents: "stroke",
           style: { cursor: tool === "eraser" ? "cell" : tool === "none" ? "pointer" : "default" },
           onPointerDown: (e) => {
@@ -594,6 +628,7 @@ function DrawingLayer({ strokes, liveStroke, tool, onStrokeClick }) {
           strokeWidth: 2.5,
           strokeLinecap: "round",
           strokeLinejoin: "round",
+          vectorEffect: "non-scaling-stroke",
           pointerEvents: "none"
         }
       )
@@ -607,6 +642,7 @@ function DrawingLayer({ strokes, liveStroke, tool, onStrokeClick }) {
         strokeWidth: 2.5,
         strokeLinecap: "round",
         strokeLinejoin: "round",
+        vectorEffect: "non-scaling-stroke",
         pointerEvents: "none",
         opacity: 0.7
       }
@@ -615,12 +651,14 @@ function DrawingLayer({ strokes, liveStroke, tool, onStrokeClick }) {
 }
 const PAD_LEFT = 30;
 const PAD_RIGHT = 40;
-const AXIS_Y = 130;
-const ARC_MAX_HEIGHT = 80;
+const AXIS_BOTTOM_OFFSET = 50;
+const ARC_TOP_PADDING = 16;
+const MIN_ARC_HEIGHT = 24;
 function NumberLine({ className }) {
   const {
     svgRef,
     containerWidth,
+    containerHeight,
     svgCursor,
     min,
     max,
@@ -628,6 +666,9 @@ function NumberLine({ className }) {
     groupCount,
     tickStep,
     arcColors,
+    showGroupTicks,
+    showMajorTicks,
+    showMinorTicks,
     tool,
     strokes,
     liveStroke,
@@ -639,14 +680,18 @@ function NumberLine({ className }) {
     onStrokeClick,
     onArcClick
   } = useNumberLineContext();
+  const w = containerWidth;
+  const h = containerHeight;
+  const axisY = Math.max(MIN_ARC_HEIGHT + ARC_TOP_PADDING, h - AXIS_BOTTOM_OFFSET);
+  const arcMaxHeight = Math.max(MIN_ARC_HEIGHT, axisY - ARC_TOP_PADDING);
   return /* @__PURE__ */ jsxRuntime.jsxs(
     "svg",
     {
       ref: svgRef,
       tabIndex: 0,
       className: className ? `nl-svg ${className}` : "nl-svg",
-      viewBox: `0 0 ${DESIGN_WIDTH} ${DESIGN_HEIGHT}`,
-      preserveAspectRatio: "xMidYMid meet",
+      viewBox: `0 0 ${w} ${h}`,
+      preserveAspectRatio: "none",
       style: { width: "100%", height: "100%", display: "block", outline: "none", cursor: svgCursor, touchAction: "none" },
       onPointerDown,
       onPointerMove,
@@ -657,13 +702,16 @@ function NumberLine({ className }) {
           {
             min,
             max,
-            axisY: AXIS_Y,
+            axisY,
             padLeft: PAD_LEFT,
             padRight: PAD_RIGHT,
-            viewWidth: DESIGN_WIDTH,
-            containerWidth,
+            viewWidth: w,
+            containerWidth: w,
             groupSize,
-            tickStep
+            tickStep,
+            showGroupTicks,
+            showMajorTicks,
+            showMinorTicks
           }
         ),
         /* @__PURE__ */ jsxRuntime.jsx(
@@ -673,11 +721,11 @@ function NumberLine({ className }) {
             max,
             groupSize,
             groupCount,
-            axisY: AXIS_Y,
+            axisY,
             padLeft: PAD_LEFT,
             padRight: PAD_RIGHT,
-            viewWidth: DESIGN_WIDTH,
-            arcMaxHeight: ARC_MAX_HEIGHT,
+            viewWidth: w,
+            arcMaxHeight,
             tool,
             selectedArcIndices,
             deletedArcIndices,
@@ -691,6 +739,8 @@ function NumberLine({ className }) {
             strokes,
             liveStroke,
             tool,
+            width: w,
+            height: h,
             onStrokeClick
           }
         )

package/dist/index.d.ts

@@ -7,8 +7,8 @@ export declare function NumberLine({ className }: {
 
 export declare interface NumberLineContextValue {
     svgRef: default_2.RefObject<SVGSVGElement>;
-    viewWidth: number;
     containerWidth: number;
+    containerHeight: number;
     svgCursor: string;
     min: number;
     max: number;
@@ -16,6 +16,9 @@ export declare interface NumberLineContextValue {
     groupCount: number;
     tickStep: number;
     arcColors?: string[];
+    showGroupTicks: boolean;
+    showMajorTicks: boolean;
+    showMinorTicks: boolean;
     tool: Tool;
     strokes: Stroke[];
     liveStroke: Stroke | null;
@@ -42,9 +45,15 @@ export declare interface NumberLineProps {
     groupCount: number;
     tickStep: number;
     arcColors?: string[];
+    /** show group boundary ticks (tallest). Default: true */
+    showGroupTicks?: boolean;
+    /** show major ticks. Default: true */
+    showMajorTicks?: boolean;
+    /** show minor ticks (in-between). Default: false */
+    showMinorTicks?: boolean;
 }
 
-export declare function NumberLineProvider({ min, max, groupSize, groupCount, tickStep, arcColors, children, }: NumberLineProviderProps): JSX_2.Element;
+export declare function NumberLineProvider({ min, max, groupSize, groupCount, tickStep, arcColors, showGroupTicks, showMajorTicks, showMinorTicks, children, }: NumberLineProviderProps): JSX_2.Element;
 
 declare interface NumberLineProviderProps extends NumberLineProps {
     children: default_2.ReactNode;

package/dist/index.js

@@ -1,5 +1,5 @@
 import { jsx, jsxs } from "react/jsx-runtime";
-import React, { useRef, useState, useCallback, useEffect, createContext, useContext, memo } from "react";
+import React, { useRef, useState, useCallback, useLayoutEffect, useEffect, createContext, useContext, memo } from "react";
 function useHistory() {
   const stackRef = useRef([]);
   const [stackLen, setStackLen] = useState(0);
@@ -45,16 +45,20 @@ function useDrawing() {
     });
     setStrokes((prev) => prev.map((s) => ({ ...s, selected: false })));
   }, []);
-  const startStroke = useCallback((x, y) => {
+  const startStroke = useCallback((x, y, w, h) => {
     drawing.current = true;
     pointCount.current = 1;
-    currentD.current = `M ${x} ${y}`;
+    const xN = w > 0 ? x / w : 0;
+    const yN = h > 0 ? y / h : 0;
+    currentD.current = `M ${xN} ${yN}`;
     currentId.current = `${Date.now()}-${Math.random()}`;
   }, []);
-  const continueStroke = useCallback((x, y) => {
+  const continueStroke = useCallback((x, y, w, h) => {
     if (!drawing.current) return null;
     pointCount.current++;
-    currentD.current += ` L ${x} ${y}`;
+    const xN = w > 0 ? x / w : 0;
+    const yN = h > 0 ? y / h : 0;
+    currentD.current += ` L ${xN} ${yN}`;
     return {
       id: currentId.current,
       d: currentD.current,
@@ -115,21 +119,29 @@ function useDrawing() {
 }
 function useContainerSize() {
   const ref = useRef(null);
-  const [width, setWidth] = useState(600);
+  const [size, setSize] = useState({ width: 600, height: 200 });
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const rect = el.getBoundingClientRect();
+    if (rect.width > 0 && rect.height > 0) {
+      setSize({ width: rect.width, height: rect.height });
+    }
+  }, []);
   useEffect(() => {
     const el = ref.current;
     if (!el) return;
     const ro = new ResizeObserver((entries) => {
       var _a;
-      const w = (_a = entries[0]) == null ? void 0 : _a.contentRect.width;
-      if (w && w > 0) setWidth(w);
+      const rect = (_a = entries[0]) == null ? void 0 : _a.contentRect;
+      if (rect && rect.width > 0 && rect.height > 0) {
+        setSize({ width: rect.width, height: rect.height });
+      }
     });
     ro.observe(el);
-    const rect = el.getBoundingClientRect();
-    if (rect.width > 0) setWidth(rect.width);
     return () => ro.disconnect();
   }, []);
-  return { ref, width };
+  return { ref, width: size.width, height: size.height };
 }
 const NumberLineContext = createContext(null);
 function useNumberLineContext() {
@@ -137,8 +149,6 @@ function useNumberLineContext() {
   if (!ctx) throw new Error("Must be used inside <NumberLineProvider>");
   return ctx;
 }
-const DESIGN_WIDTH = 1e3;
-const DESIGN_HEIGHT = 200;
 function NumberLineProvider({
   min,
   max,
@@ -146,11 +156,14 @@ function NumberLineProvider({
   groupCount,
   tickStep,
   arcColors,
+  showGroupTicks = true,
+  showMajorTicks = true,
+  showMinorTicks = false,
   children
 }) {
   const [selectedArcIndices, setSelectedArcIndices] = useState(/* @__PURE__ */ new Set());
   const [deletedArcIndices, setDeletedArcIndices] = useState(/* @__PURE__ */ new Set());
-  const { ref: svgRef, width: containerWidth } = useContainerSize();
+  const { ref: svgRef, width: containerWidth, height: containerHeight } = useContainerSize();
   const history = useHistory();
   const drawing = useDrawing();
   const [liveStroke, setLiveStroke] = useState(null);
@@ -180,19 +193,19 @@ function NumberLineProvider({
       e.currentTarget.setPointerCapture(e.pointerId);
       const coords = getLocalCoords(e);
       if (!coords) return;
-      drawing.startStroke(...coords);
+      drawing.startStroke(coords[0], coords[1], containerWidth, containerHeight);
     },
-    [drawing, getLocalCoords]
+    [drawing, getLocalCoords, containerWidth, containerHeight]
   );
   const onPointerMove = useCallback(
     (e) => {
       if (drawing.tool !== "pen") return;
       const coords = getLocalCoords(e);
       if (!coords) return;
-      const live = drawing.continueStroke(...coords);
+      const live = drawing.continueStroke(coords[0], coords[1], containerWidth, containerHeight);
       if (live) setLiveStroke(live);
     },
-    [drawing, getLocalCoords]
+    [drawing, getLocalCoords, containerWidth, containerHeight]
   );
   const onPointerUp = useCallback(() => {
     if (drawing.tool !== "pen") return;
@@ -312,8 +325,8 @@ function NumberLineProvider({
     {
       value: {
         svgRef,
-        viewWidth: DESIGN_WIDTH,
         containerWidth,
+        containerHeight,
         svgCursor,
         min,
         max,
@@ -321,6 +334,9 @@ function NumberLineProvider({
         groupCount,
         tickStep,
         arcColors,
+        showGroupTicks,
+        showMajorTicks,
+        showMinorTicks,
         tool: drawing.tool,
         strokes: drawing.strokes,
         liveStroke,
@@ -360,6 +376,12 @@ const ARC_COLORS = [
   "#be185d",
   "#16a34a"
 ];
+function gcd(a, b) {
+  let x = Math.max(1, Math.abs(Math.round(a)));
+  let y = Math.max(1, Math.abs(Math.round(b)));
+  while (y !== 0) [x, y] = [y, x % y];
+  return x;
+}
 const AxisLayer = React.memo(function AxisLayer2({
   min,
   max,
@@ -369,7 +391,10 @@ const AxisLayer = React.memo(function AxisLayer2({
   viewWidth,
   containerWidth,
   groupSize,
-  tickStep
+  tickStep,
+  showGroupTicks,
+  showMajorTicks,
+  showMinorTicks
 }) {
   const range = max - min;
   if (range <= 0) return null;
@@ -379,9 +404,11 @@ const AxisLayer = React.memo(function AxisLayer2({
   const rawLabelStep = computeLabelStep(containerWidth, range);
   const labelStep = Math.max(step, Math.ceil(rawLabelStep / step) * step);
   const MAX_TICKS = 500;
-  const minorStep = Math.max(1, Math.ceil(range / MAX_TICKS));
+  const capStep = Math.max(1, Math.ceil(range / MAX_TICKS));
+  const visibleStep = groupSize > 0 ? gcd(step, groupSize) : step;
+  const iterStep = showMinorTicks ? capStep : Math.max(capStep, visibleStep);
   const allTicks = [];
-  for (let v = min; v <= max; v += minorStep) allTicks.push(v);
+  for (let v = min; v <= max; v += iterStep) allTicks.push(v);
   return /* @__PURE__ */ jsxs("g", { className: "nl-axis-layer", children: [
     /* @__PURE__ */ jsx(
       "line",
@@ -399,10 +426,14 @@ const AxisLayer = React.memo(function AxisLayer2({
       const offset = v - min;
       const isMajor = offset % step === 0;
       const isGroupBoundary = groupSize > 0 && offset % groupSize === 0;
-      const showLabel = isMajor && offset % labelStep === 0;
-      const tickH = isGroupBoundary ? 10 : isMajor ? 7 : 4;
-      const strokeW = isGroupBoundary ? 1.5 : isMajor ? 1 : 0.5;
-      const color = isMajor ? "#374151" : "#9ca3af";
+      const visible = isGroupBoundary && showGroupTicks || isMajor && showMajorTicks || !isGroupBoundary && !isMajor && showMinorTicks;
+      if (!visible) return null;
+      const renderAsGroup = isGroupBoundary && showGroupTicks;
+      const renderAsMajor = !renderAsGroup && isMajor && showMajorTicks;
+      const showLabel = (renderAsGroup || renderAsMajor) && offset % labelStep === 0;
+      const tickH = renderAsGroup ? 7 : renderAsMajor ? 10 : 4;
+      const strokeW = renderAsGroup ? 1.5 : renderAsMajor ? 1 : 0.5;
+      const color = renderAsGroup || renderAsMajor ? "#374151" : "#9ca3af";
       return /* @__PURE__ */ jsxs("g", { children: [
         /* @__PURE__ */ jsx(
           "line",
@@ -463,9 +494,10 @@ const GroupArcsLayer = memo(function GroupArcsLayer2({
     const rx = (x2 - x1) / 2;
     const ry = Math.min(rx * 0.7, arcMaxHeight);
     const color = arcColors[g % arcColors.length];
-    const textY = axisY - ry - 6;
     const arrowHeadH = 7;
     const arrowHeadHW = 4;
+    const MIN_ARROW_SPAN = 18;
+    const textY = Math.min(axisY - ry - 6, axisY - MIN_ARROW_SPAN);
     const arcPath = buildArcPath({ x1, x2, y: axisY, rx, ry });
     const isSelected = selectedArcIndices.has(g);
     const hitCursor = tool === "eraser" ? "cell" : tool === "none" ? "pointer" : "default";
@@ -549,8 +581,8 @@ const GroupArcsLayer = memo(function GroupArcsLayer2({
   }
   return /* @__PURE__ */ jsx("g", { className: "nl-arcs-layer", children: arcs });
 });
-function DrawingLayer({ strokes, liveStroke, tool, onStrokeClick }) {
-  return /* @__PURE__ */ jsxs("g", { className: "nl-drawing-layer", children: [
+function DrawingLayer({ strokes, liveStroke, tool, width, height, onStrokeClick }) {
+  return /* @__PURE__ */ jsxs("g", { className: "nl-drawing-layer", transform: `scale(${width} ${height})`, children: [
     strokes.map((s) => /* @__PURE__ */ jsxs("g", { children: [
       s.selected && /* @__PURE__ */ jsx(
         "path",
@@ -561,6 +593,7 @@ function DrawingLayer({ strokes, liveStroke, tool, onStrokeClick }) {
           strokeWidth: 18,
           strokeLinecap: "round",
           strokeLinejoin: "round",
+          vectorEffect: "non-scaling-stroke",
           pointerEvents: "none"
         }
       ),
@@ -573,6 +606,7 @@ function DrawingLayer({ strokes, liveStroke, tool, onStrokeClick }) {
           strokeWidth: tool === "eraser" ? 32 : 28,
           strokeLinecap: "round",
           strokeLinejoin: "round",
+          vectorEffect: "non-scaling-stroke",
           pointerEvents: "stroke",
           style: { cursor: tool === "eraser" ? "cell" : tool === "none" ? "pointer" : "default" },
           onPointerDown: (e) => {
@@ -592,6 +626,7 @@ function DrawingLayer({ strokes, liveStroke, tool, onStrokeClick }) {
           strokeWidth: 2.5,
           strokeLinecap: "round",
           strokeLinejoin: "round",
+          vectorEffect: "non-scaling-stroke",
           pointerEvents: "none"
         }
       )
@@ -605,6 +640,7 @@ function DrawingLayer({ strokes, liveStroke, tool, onStrokeClick }) {
         strokeWidth: 2.5,
         strokeLinecap: "round",
         strokeLinejoin: "round",
+        vectorEffect: "non-scaling-stroke",
         pointerEvents: "none",
         opacity: 0.7
       }
@@ -613,12 +649,14 @@ function DrawingLayer({ strokes, liveStroke, tool, onStrokeClick }) {
 }
 const PAD_LEFT = 30;
 const PAD_RIGHT = 40;
-const AXIS_Y = 130;
-const ARC_MAX_HEIGHT = 80;
+const AXIS_BOTTOM_OFFSET = 50;
+const ARC_TOP_PADDING = 16;
+const MIN_ARC_HEIGHT = 24;
 function NumberLine({ className }) {
   const {
     svgRef,
     containerWidth,
+    containerHeight,
     svgCursor,
     min,
     max,
@@ -626,6 +664,9 @@ function NumberLine({ className }) {
     groupCount,
     tickStep,
     arcColors,
+    showGroupTicks,
+    showMajorTicks,
+    showMinorTicks,
     tool,
     strokes,
     liveStroke,
@@ -637,14 +678,18 @@ function NumberLine({ className }) {
     onStrokeClick,
     onArcClick
   } = useNumberLineContext();
+  const w = containerWidth;
+  const h = containerHeight;
+  const axisY = Math.max(MIN_ARC_HEIGHT + ARC_TOP_PADDING, h - AXIS_BOTTOM_OFFSET);
+  const arcMaxHeight = Math.max(MIN_ARC_HEIGHT, axisY - ARC_TOP_PADDING);
   return /* @__PURE__ */ jsxs(
     "svg",
     {
       ref: svgRef,
       tabIndex: 0,
       className: className ? `nl-svg ${className}` : "nl-svg",
-      viewBox: `0 0 ${DESIGN_WIDTH} ${DESIGN_HEIGHT}`,
-      preserveAspectRatio: "xMidYMid meet",
+      viewBox: `0 0 ${w} ${h}`,
+      preserveAspectRatio: "none",
       style: { width: "100%", height: "100%", display: "block", outline: "none", cursor: svgCursor, touchAction: "none" },
       onPointerDown,
       onPointerMove,
@@ -655,13 +700,16 @@ function NumberLine({ className }) {
           {
             min,
             max,
-            axisY: AXIS_Y,
+            axisY,
             padLeft: PAD_LEFT,
             padRight: PAD_RIGHT,
-            viewWidth: DESIGN_WIDTH,
-            containerWidth,
+            viewWidth: w,
+            containerWidth: w,
             groupSize,
-            tickStep
+            tickStep,
+            showGroupTicks,
+            showMajorTicks,
+            showMinorTicks
           }
         ),
         /* @__PURE__ */ jsx(
@@ -671,11 +719,11 @@ function NumberLine({ className }) {
             max,
             groupSize,
             groupCount,
-            axisY: AXIS_Y,
+            axisY,
             padLeft: PAD_LEFT,
             padRight: PAD_RIGHT,
-            viewWidth: DESIGN_WIDTH,
-            arcMaxHeight: ARC_MAX_HEIGHT,
+            viewWidth: w,
+            arcMaxHeight,
             tool,
             selectedArcIndices,
             deletedArcIndices,
@@ -689,6 +737,8 @@ function NumberLine({ className }) {
             strokes,
             liveStroke,
             tool,
+            width: w,
+            height: h,
             onStrokeClick
           }
         )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dcg-overseas/number-line",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Interactive number line component with group arcs and freehand drawing",
   "type": "module",
   "license": "MIT",