@dcg-overseas/number-line 0.1.4 → 0.1.5

package/README.md

@@ -61,6 +61,12 @@ function Demo() {
 | `showGroupTicks` | `boolean` | `true` | 是否显示分组边界刻度（最长，10px） |
 | `showMajorTicks` | `boolean` | `true` | 是否显示主刻度（中等，7px） |
 | `showMinorTicks` | `boolean` | `false` | 是否显示次刻度（最短，4px）。默认隐藏 |
+| `enableZoom` | `boolean` | `false` | 启用滚轮/双指缩放 + 拖拽平移。默认禁用 |
+| `minZoom` | `number` | `1` | 最小缩放级别（1 = 完整 `[min, max]` 范围） |
+| `maxZoom` | `number` | `50` | 最大缩放级别（50 = 放大 50 倍） |
+| `viewMin` | `number?` | — | 受控模式：当前可视范围起点。需与 `viewMax` 和 `onViewChange` 配合 |
+| `viewMax` | `number?` | — | 受控模式：当前可视范围终点 |
+| `onViewChange` | `(viewMin, viewMax) => void` | — | 非受控模式：viewport 变化时触发（滚轮/拖拽/双击重置） |
 | `children` | `ReactNode` | — | 子节点（必须包含 `<NumberLine />` 或自定义渲染器） |
 
 #### 弧线生成规则
@@ -86,6 +92,54 @@ g ∈ [0, groupCount)
 <NumberLineProvider ... showMajorTicks={false} />
 ```
 
+#### 缩放与平移（`enableZoom`）
+
+启用后支持：
+- **滚轮缩放**：以鼠标位置为中心放大/缩小
+- **拖拽平移**：`tool='none'` 时，左键拖拽 >5px 触发平移（避免与点击选中冲突）
+- **双指缩放**（触摸屏）：pinch 手势
+- **双击重置**：双击空白处恢复到完整 `[min, max]` 范围
+
+```tsx
+// 非受控模式（内部维护 viewport）
+<NumberLineProvider
+  min={0}
+  max={100}
+  enableZoom
+  minZoom={1}
+  maxZoom={50}
+  onViewChange={(viewMin, viewMax) => console.log('viewport:', viewMin, viewMax)}
+  ...
+/>
+
+// 受控模式（父组件控制 viewport）
+function App() {
+  const [view, setView] = useState([0, 100])
+  return (
+    <NumberLineProvider
+      min={0}
+      max={100}
+      enableZoom
+      viewMin={view[0]}
+      viewMax={view[1]}
+      onViewChange={(a, b) => setView([a, b])}
+      ...
+    />
+  )
+}
+```
+
+**注意事项**：
+- 笔迹坐标是归一化 `[0,1]`（容器像素比例），**不会跟随数值缩放移动**。适合「批注」语义，不适合「标记 v=50 处」语义。
+- viewport 始终夹紧在 `[min, max]` 内，不会平移到数据范围外。
+- 缩放时刻度密度自动调整（`labelStep` 按可视范围重算）。
+- **桌面端**：滚轮和 pinch 需要鼠标悬停或 SVG 获得焦点（视觉上有蓝色边框提示）。
+- **移动端**：双指 pinch 直接生效（触摸即激活）。**SVG 外的双指仍会触发浏览器整页缩放**——如果不需要整页缩放，可在宿主 HTML 添加：
+  ```html
+  <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
+  ```
+  但出于无障碍考虑，禁用整页缩放需谨慎评估。
+
 ---
 
 ### `<NumberLine>`
@@ -161,6 +215,14 @@ g ∈ [0, groupCount)
 | `onReset` | `() => void` | 清空所有笔迹和弧线删除记录 |
 | `onUndo` | `() => void` | 撤销上一步操作 |
 
+#### 缩放 API（仅 `enableZoom=true` 时有效）
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `viewMin` `viewMax` | `number` | 当前可视范围（等于 `[min, max]` 当 zoom 禁用） |
+| `resetView` | `() => void` | 重置到完整数据范围 |
+| `zoomAt` | `(factor: number, fraction: number) => void` | 以 viewport 的 `fraction` 位置（0..1）为中心缩放 `factor` 倍 |
+| `panByFraction` | `(df: number) => void` | 平移 viewport 宽度的 `df` 倍（正数右移，负数左移） |
+
 ---
 
 ## 自定义工具栏示例

package/dist/index.cjs

@@ -145,6 +145,89 @@ function useContainerSize() {
   }, []);
   return { ref, width: size.width, height: size.height };
 }
+function useZoom({
+  dataMin,
+  dataMax,
+  minZoom,
+  maxZoom,
+  controlledMin,
+  controlledMax,
+  onChange
+}) {
+  const isControlled = controlledMin !== void 0 && controlledMax !== void 0;
+  const [internal, setInternal] = React.useState([dataMin, dataMax]);
+  const lastRange = React.useRef([dataMin, dataMax]);
+  React.useEffect(() => {
+    const [lm, lM] = lastRange.current;
+    if (lm !== dataMin || lM !== dataMax) {
+      lastRange.current = [dataMin, dataMax];
+      if (!isControlled) setInternal([dataMin, dataMax]);
+    }
+  }, [dataMin, dataMax, isControlled]);
+  const viewMin = isControlled ? controlledMin : internal[0];
+  const viewMax = isControlled ? controlledMax : internal[1];
+  const viewRef = React.useRef({ viewMin, viewMax });
+  viewRef.current = { viewMin, viewMax };
+  const dataRange = dataMax - dataMin;
+  const minView = dataRange / Math.max(1, maxZoom);
+  const maxView = dataRange / Math.max(1, Math.min(minZoom, maxZoom));
+  const commit = React.useCallback(
+    (next) => {
+      const { viewMin: curMin, viewMax: curMax } = viewRef.current;
+      let [a, b] = next;
+      let width = b - a;
+      if (width < minView) {
+        const c = (a + b) / 2;
+        a = c - minView / 2;
+        b = c + minView / 2;
+        width = minView;
+      }
+      if (width > maxView) {
+        const c = (a + b) / 2;
+        a = c - maxView / 2;
+        b = c + maxView / 2;
+        width = maxView;
+      }
+      if (a < dataMin) {
+        b += dataMin - a;
+        a = dataMin;
+      }
+      if (b > dataMax) {
+        a -= b - dataMax;
+        b = dataMax;
+      }
+      if (a < dataMin) a = dataMin;
+      if (b > dataMax) b = dataMax;
+      if (a === curMin && b === curMax) return;
+      if (!isControlled) setInternal([a, b]);
+      onChange == null ? void 0 : onChange(a, b);
+    },
+    [minView, maxView, dataMin, dataMax, isControlled, onChange]
+  );
+  const zoomAt = React.useCallback(
+    (factor, f) => {
+      const width = viewMax - viewMin;
+      const anchorVal = viewMin + width * f;
+      const newWidth = width / factor;
+      const a = anchorVal - newWidth * f;
+      const b = anchorVal + newWidth * (1 - f);
+      commit([a, b]);
+    },
+    [viewMin, viewMax, commit]
+  );
+  const panByFraction = React.useCallback(
+    (df) => {
+      const width = viewMax - viewMin;
+      const dv = width * df;
+      commit([viewMin + dv, viewMax + dv]);
+    },
+    [viewMin, viewMax, commit]
+  );
+  const resetView = React.useCallback(() => {
+    commit([dataMin, dataMax]);
+  }, [commit, dataMin, dataMax]);
+  return { viewMin, viewMax, zoomAt, panByFraction, resetView };
+}
 const NumberLineContext = React.createContext(null);
 function useNumberLineContext() {
   const ctx = React.useContext(NumberLineContext);
@@ -161,6 +244,12 @@ function NumberLineProvider({
   showGroupTicks = true,
   showMajorTicks = true,
   showMinorTicks = false,
+  enableZoom = false,
+  minZoom = 1,
+  maxZoom = 50,
+  viewMin: controlledViewMin,
+  viewMax: controlledViewMax,
+  onViewChange,
   children
 }) {
   const [selectedArcIndices, setSelectedArcIndices] = React.useState(/* @__PURE__ */ new Set());
@@ -168,6 +257,15 @@ function NumberLineProvider({
   const { ref: svgRef, width: containerWidth, height: containerHeight } = useContainerSize();
   const history = useHistory();
   const drawing = useDrawing();
+  const { viewMin, viewMax, zoomAt, panByFraction, resetView } = useZoom({
+    dataMin: min,
+    dataMax: max,
+    minZoom,
+    maxZoom,
+    controlledMin: controlledViewMin,
+    controlledMax: controlledViewMax,
+    onChange: onViewChange
+  });
   const [liveStroke, setLiveStroke] = React.useState(null);
   const svgPoint = React.useRef(null);
   React.useEffect(() => {
@@ -339,6 +437,12 @@ function NumberLineProvider({
         showGroupTicks,
         showMajorTicks,
         showMinorTicks,
+        viewMin,
+        viewMax,
+        enableZoom,
+        resetView,
+        zoomAt,
+        panByFraction,
         tool: drawing.tool,
         strokes: drawing.strokes,
         liveStroke,
@@ -386,22 +490,24 @@ function gcd(a, b) {
 }
 const AxisLayer = React.memo(function AxisLayer2({
   min,
-  max,
+  viewMin,
+  viewMax,
   axisY,
   padLeft,
   padRight,
   viewWidth,
   containerWidth,
   groupSize,
+  groupCount,
   tickStep,
   showGroupTicks,
   showMajorTicks,
   showMinorTicks
 }) {
-  const range = max - min;
+  const range = viewMax - viewMin;
   if (range <= 0) return null;
   const usable = viewWidth - padLeft - padRight;
-  const toX = (v) => padLeft + (v - min) / range * usable;
+  const toX = (v) => padLeft + (v - viewMin) / range * usable;
   const step = Math.max(1, Math.round(tickStep));
   const rawLabelStep = computeLabelStep(containerWidth, range);
   const labelStep = Math.max(step, Math.ceil(rawLabelStep / step) * step);
@@ -409,8 +515,11 @@ const AxisLayer = React.memo(function AxisLayer2({
   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 startVal = Math.floor(viewMin / iterStep) * iterStep;
   const allTicks = [];
-  for (let v = min; v <= max; v += iterStep) allTicks.push(v);
+  for (let v = startVal; v <= viewMax; v += iterStep) {
+    if (v >= viewMin && v <= viewMax) allTicks.push(v);
+  }
   return /* @__PURE__ */ jsxRuntime.jsxs("g", { className: "nl-axis-layer", children: [
     /* @__PURE__ */ jsxRuntime.jsx(
       "line",
@@ -427,7 +536,8 @@ const AxisLayer = React.memo(function AxisLayer2({
       const x = toX(v);
       const offset = v - min;
       const isMajor = offset % step === 0;
-      const isGroupBoundary = groupSize > 0 && offset % groupSize === 0;
+      const maxGroupBoundary = min + groupCount * groupSize;
+      const isGroupBoundary = groupSize > 0 && offset % groupSize === 0 && v <= maxGroupBoundary;
       const visible = isGroupBoundary && showGroupTicks || isMajor && showMajorTicks || !isGroupBoundary && !isMajor && showMinorTicks;
       if (!visible) return null;
       const renderAsGroup = isGroupBoundary && showGroupTicks;
@@ -468,6 +578,8 @@ const AxisLayer = React.memo(function AxisLayer2({
 const GroupArcsLayer = React.memo(function GroupArcsLayer2({
   min,
   max,
+  viewMin,
+  viewMax,
   groupSize,
   groupCount,
   axisY,
@@ -482,15 +594,17 @@ const GroupArcsLayer = React.memo(function GroupArcsLayer2({
   arcColors = ARC_COLORS
 }) {
   if (groupSize <= 0 || groupCount <= 0) return null;
-  const range = max - min;
+  const range = viewMax - viewMin;
   const usable = viewWidth - padLeft - padRight;
-  const toX = (v) => padLeft + (v - min) / range * usable;
+  const toX = (v) => padLeft + (v - viewMin) / range * usable;
+  const clipId = React.useId().replace(/:/g, "_") + "-arcs-clip";
   const arcs = [];
   for (let g = 0; g < groupCount; g++) {
     if (deletedArcIndices.has(g)) continue;
     const start = min + g * groupSize;
     const end = start + groupSize;
     if (end > max) break;
+    if (end < viewMin || start > viewMax) continue;
     const x1 = toX(start);
     const x2 = toX(end);
     const rx = (x2 - x1) / 2;
@@ -536,7 +650,7 @@ const GroupArcsLayer = React.memo(function GroupArcsLayer2({
             strokeLinecap: "round",
             pointerEvents: "stroke",
             style: { cursor: hitCursor },
-            onPointerDown: (e) => {
+            onClick: (e) => {
               if (tool === "eraser" || tool === "none") {
                 e.stopPropagation();
                 onArcClick(g, e);
@@ -581,7 +695,18 @@ const GroupArcsLayer = React.memo(function GroupArcsLayer2({
       ] }, g)
     );
   }
-  return /* @__PURE__ */ jsxRuntime.jsx("g", { className: "nl-arcs-layer", children: arcs });
+  return /* @__PURE__ */ jsxRuntime.jsxs("g", { className: "nl-arcs-layer", children: [
+    /* @__PURE__ */ jsxRuntime.jsx("defs", { children: /* @__PURE__ */ jsxRuntime.jsx("clipPath", { id: clipId, children: /* @__PURE__ */ jsxRuntime.jsx(
+      "rect",
+      {
+        x: padLeft,
+        y: 0,
+        width: usable,
+        height: axisY + 1
+      }
+    ) }) }),
+    /* @__PURE__ */ jsxRuntime.jsx("g", { clipPath: `url(#${clipId})`, children: arcs })
+  ] });
 });
 function DrawingLayer({ strokes, liveStroke, tool, width, height, onStrokeClick }) {
   return /* @__PURE__ */ jsxRuntime.jsxs("g", { className: "nl-drawing-layer", transform: `scale(${width} ${height})`, children: [
@@ -611,7 +736,7 @@ function DrawingLayer({ strokes, liveStroke, tool, width, height, onStrokeClick
           vectorEffect: "non-scaling-stroke",
           pointerEvents: "stroke",
           style: { cursor: tool === "eraser" ? "cell" : tool === "none" ? "pointer" : "default" },
-          onPointerDown: (e) => {
+          onClick: (e) => {
             if (tool === "eraser" || tool === "none") {
               e.stopPropagation();
               onStrokeClick(s.id, e);
@@ -669,6 +794,12 @@ function NumberLine({ className }) {
     showGroupTicks,
     showMajorTicks,
     showMinorTicks,
+    viewMin,
+    viewMax,
+    enableZoom,
+    resetView,
+    zoomAt,
+    panByFraction,
     tool,
     strokes,
     liveStroke,
@@ -684,6 +815,137 @@ function NumberLine({ className }) {
   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);
+  const [isZoomActive, setIsZoomActive] = React.useState(false);
+  const [isPanning, setIsPanning] = React.useState(false);
+  const panStart = React.useRef(null);
+  const activePointers = React.useRef(/* @__PURE__ */ new Map());
+  const pinchState = React.useRef(null);
+  const handleWheel = React.useCallback(
+    (e) => {
+      if (!enableZoom || !isZoomActive) return;
+      e.preventDefault();
+      e.stopPropagation();
+      const svg = svgRef.current;
+      if (!svg) return;
+      const rect = svg.getBoundingClientRect();
+      const mouseX = e.clientX - rect.left;
+      const fraction = mouseX / w;
+      const factor = e.deltaY < 0 ? 1.15 : 1 / 1.15;
+      zoomAt(factor, fraction);
+    },
+    [enableZoom, isZoomActive, svgRef, w, zoomAt]
+  );
+  const handlePanStart = React.useCallback(
+    (e) => {
+      if (!enableZoom || tool !== "none") return;
+      if (e.button !== 0 && e.button !== 1) return;
+      const svg = svgRef.current;
+      if (!svg) return;
+      const rect = svg.getBoundingClientRect();
+      panStart.current = { x: e.clientX - rect.left, pointerId: e.pointerId };
+    },
+    [enableZoom, tool, svgRef]
+  );
+  const handlePanMove = React.useCallback(
+    (e) => {
+      if (!enableZoom || !panStart.current) return;
+      if (e.pointerId !== panStart.current.pointerId) return;
+      const svg = svgRef.current;
+      if (!svg) return;
+      const rect = svg.getBoundingClientRect();
+      const x = e.clientX - rect.left;
+      const dx = x - panStart.current.x;
+      if (!isPanning && Math.abs(dx) < 5) return;
+      if (!isPanning) {
+        setIsPanning(true);
+        svg.setPointerCapture(e.pointerId);
+      }
+      const df = -dx / w;
+      panByFraction(df);
+      panStart.current.x = x;
+    },
+    [enableZoom, isPanning, svgRef, w, panByFraction]
+  );
+  const handlePanEnd = React.useCallback(() => {
+    panStart.current = null;
+    setIsPanning(false);
+  }, []);
+  const updatePinch = React.useCallback(() => {
+    if (!enableZoom || activePointers.current.size !== 2) return;
+    const [p1, p2] = Array.from(activePointers.current.values());
+    const dist = Math.hypot(p2.x - p1.x, p2.y - p1.y);
+    const midX = (p1.x + p2.x) / 2;
+    if (!pinchState.current) {
+      pinchState.current = { dist, midX };
+    } else {
+      const factor = dist / pinchState.current.dist;
+      const fraction = midX / w;
+      zoomAt(factor, fraction);
+      pinchState.current = { dist, midX };
+    }
+  }, [enableZoom, w, zoomAt]);
+  const handlePointerDown = React.useCallback(
+    (e) => {
+      if (e.pointerType === "touch" && enableZoom) {
+        const svg = svgRef.current;
+        if (!svg) return;
+        const rect = svg.getBoundingClientRect();
+        activePointers.current.set(e.pointerId, {
+          x: e.clientX - rect.left,
+          y: e.clientY - rect.top
+        });
+        setIsZoomActive(true);
+        updatePinch();
+      }
+      if (tool === "pen") {
+        onPointerDown(e);
+      } else {
+        handlePanStart(e);
+        onPointerDown(e);
+      }
+    },
+    [tool, enableZoom, svgRef, onPointerDown, handlePanStart, updatePinch]
+  );
+  const handlePointerMove = React.useCallback(
+    (e) => {
+      if (e.pointerType === "touch" && enableZoom && activePointers.current.has(e.pointerId)) {
+        const svg = svgRef.current;
+        if (!svg) return;
+        const rect = svg.getBoundingClientRect();
+        activePointers.current.set(e.pointerId, {
+          x: e.clientX - rect.left,
+          y: e.clientY - rect.top
+        });
+        updatePinch();
+      }
+      onPointerMove(e);
+      handlePanMove(e);
+    },
+    [enableZoom, svgRef, onPointerMove, handlePanMove, updatePinch]
+  );
+  const handlePointerUp = React.useCallback(
+    (e) => {
+      if (activePointers.current.has(e.pointerId)) {
+        activePointers.current.delete(e.pointerId);
+        if (activePointers.current.size < 2) {
+          pinchState.current = null;
+        }
+        if (activePointers.current.size === 0 && e.pointerType === "touch") {
+          setIsZoomActive(false);
+        }
+      }
+      onPointerUp();
+      handlePanEnd();
+    },
+    [onPointerUp, handlePanEnd]
+  );
+  const handleDoubleClick = React.useCallback(
+    () => {
+      if (!enableZoom) return;
+      resetView();
+    },
+    [enableZoom, resetView]
+  );
   return /* @__PURE__ */ jsxRuntime.jsxs(
     "svg",
     {
@@ -692,22 +954,38 @@ function NumberLine({ className }) {
       className: className ? `nl-svg ${className}` : "nl-svg",
       viewBox: `0 0 ${w} ${h}`,
       preserveAspectRatio: "none",
-      style: { width: "100%", height: "100%", display: "block", outline: "none", cursor: svgCursor, touchAction: "none" },
-      onPointerDown,
-      onPointerMove,
-      onPointerUp,
+      style: {
+        width: "100%",
+        height: "100%",
+        display: "block",
+        outline: enableZoom && isZoomActive ? "2px solid rgba(59, 130, 246, 0.5)" : "none",
+        cursor: svgCursor,
+        touchAction: "none"
+      },
+      onPointerDown: handlePointerDown,
+      onPointerMove: handlePointerMove,
+      onPointerUp: handlePointerUp,
+      onWheel: handleWheel,
+      onDoubleClick: handleDoubleClick,
+      onMouseEnter: () => enableZoom && setIsZoomActive(true),
+      onMouseLeave: () => enableZoom && setIsZoomActive(false),
+      onFocus: () => enableZoom && setIsZoomActive(true),
+      onBlur: () => enableZoom && setIsZoomActive(false),
       children: [
         /* @__PURE__ */ jsxRuntime.jsx(
           AxisLayer,
           {
             min,
             max,
+            viewMin,
+            viewMax,
             axisY,
             padLeft: PAD_LEFT,
             padRight: PAD_RIGHT,
             viewWidth: w,
             containerWidth: w,
             groupSize,
+            groupCount,
             tickStep,
             showGroupTicks,
             showMajorTicks,
@@ -719,6 +997,8 @@ function NumberLine({ className }) {
           {
             min,
             max,
+            viewMin,
+            viewMax,
             groupSize,
             groupCount,
             axisY,

package/dist/index.d.ts

@@ -19,6 +19,12 @@ export declare interface NumberLineContextValue {
     showGroupTicks: boolean;
     showMajorTicks: boolean;
     showMinorTicks: boolean;
+    viewMin: number;
+    viewMax: number;
+    enableZoom: boolean;
+    resetView: () => void;
+    zoomAt: (factor: number, fraction: number) => void;
+    panByFraction: (df: number) => void;
     tool: Tool;
     strokes: Stroke[];
     liveStroke: Stroke | null;
@@ -51,9 +57,20 @@ export declare interface NumberLineProps {
     showMajorTicks?: boolean;
     /** show minor ticks (in-between). Default: false */
     showMinorTicks?: boolean;
+    /** enable mouse-wheel / pinch zoom + drag-to-pan. Default: false */
+    enableZoom?: boolean;
+    /** minimum zoom level. 1 = full [min, max] range. Default: 1 */
+    minZoom?: number;
+    /** maximum zoom level. Default: 50 */
+    maxZoom?: number;
+    /** controlled view: if both provided, viewport is driven by parent */
+    viewMin?: number;
+    viewMax?: number;
+    /** fired whenever internal viewport changes (uncontrolled mode) */
+    onViewChange?: (viewMin: number, viewMax: number) => void;
 }
 
-export declare function NumberLineProvider({ min, max, groupSize, groupCount, tickStep, arcColors, showGroupTicks, showMajorTicks, showMinorTicks, children, }: NumberLineProviderProps): JSX_2.Element;
+export declare function NumberLineProvider({ min, max, groupSize, groupCount, tickStep, arcColors, showGroupTicks, showMajorTicks, showMinorTicks, enableZoom, minZoom, maxZoom, viewMin: controlledViewMin, viewMax: controlledViewMax, onViewChange, children, }: NumberLineProviderProps): JSX_2.Element;
 
 declare interface NumberLineProviderProps extends NumberLineProps {
     children: default_2.ReactNode;

package/dist/index.js

@@ -143,6 +143,89 @@ function useContainerSize() {
   }, []);
   return { ref, width: size.width, height: size.height };
 }
+function useZoom({
+  dataMin,
+  dataMax,
+  minZoom,
+  maxZoom,
+  controlledMin,
+  controlledMax,
+  onChange
+}) {
+  const isControlled = controlledMin !== void 0 && controlledMax !== void 0;
+  const [internal, setInternal] = useState([dataMin, dataMax]);
+  const lastRange = useRef([dataMin, dataMax]);
+  useEffect(() => {
+    const [lm, lM] = lastRange.current;
+    if (lm !== dataMin || lM !== dataMax) {
+      lastRange.current = [dataMin, dataMax];
+      if (!isControlled) setInternal([dataMin, dataMax]);
+    }
+  }, [dataMin, dataMax, isControlled]);
+  const viewMin = isControlled ? controlledMin : internal[0];
+  const viewMax = isControlled ? controlledMax : internal[1];
+  const viewRef = useRef({ viewMin, viewMax });
+  viewRef.current = { viewMin, viewMax };
+  const dataRange = dataMax - dataMin;
+  const minView = dataRange / Math.max(1, maxZoom);
+  const maxView = dataRange / Math.max(1, Math.min(minZoom, maxZoom));
+  const commit = useCallback(
+    (next) => {
+      const { viewMin: curMin, viewMax: curMax } = viewRef.current;
+      let [a, b] = next;
+      let width = b - a;
+      if (width < minView) {
+        const c = (a + b) / 2;
+        a = c - minView / 2;
+        b = c + minView / 2;
+        width = minView;
+      }
+      if (width > maxView) {
+        const c = (a + b) / 2;
+        a = c - maxView / 2;
+        b = c + maxView / 2;
+        width = maxView;
+      }
+      if (a < dataMin) {
+        b += dataMin - a;
+        a = dataMin;
+      }
+      if (b > dataMax) {
+        a -= b - dataMax;
+        b = dataMax;
+      }
+      if (a < dataMin) a = dataMin;
+      if (b > dataMax) b = dataMax;
+      if (a === curMin && b === curMax) return;
+      if (!isControlled) setInternal([a, b]);
+      onChange == null ? void 0 : onChange(a, b);
+    },
+    [minView, maxView, dataMin, dataMax, isControlled, onChange]
+  );
+  const zoomAt = useCallback(
+    (factor, f) => {
+      const width = viewMax - viewMin;
+      const anchorVal = viewMin + width * f;
+      const newWidth = width / factor;
+      const a = anchorVal - newWidth * f;
+      const b = anchorVal + newWidth * (1 - f);
+      commit([a, b]);
+    },
+    [viewMin, viewMax, commit]
+  );
+  const panByFraction = useCallback(
+    (df) => {
+      const width = viewMax - viewMin;
+      const dv = width * df;
+      commit([viewMin + dv, viewMax + dv]);
+    },
+    [viewMin, viewMax, commit]
+  );
+  const resetView = useCallback(() => {
+    commit([dataMin, dataMax]);
+  }, [commit, dataMin, dataMax]);
+  return { viewMin, viewMax, zoomAt, panByFraction, resetView };
+}
 const NumberLineContext = createContext(null);
 function useNumberLineContext() {
   const ctx = useContext(NumberLineContext);
@@ -159,6 +242,12 @@ function NumberLineProvider({
   showGroupTicks = true,
   showMajorTicks = true,
   showMinorTicks = false,
+  enableZoom = false,
+  minZoom = 1,
+  maxZoom = 50,
+  viewMin: controlledViewMin,
+  viewMax: controlledViewMax,
+  onViewChange,
   children
 }) {
   const [selectedArcIndices, setSelectedArcIndices] = useState(/* @__PURE__ */ new Set());
@@ -166,6 +255,15 @@ function NumberLineProvider({
   const { ref: svgRef, width: containerWidth, height: containerHeight } = useContainerSize();
   const history = useHistory();
   const drawing = useDrawing();
+  const { viewMin, viewMax, zoomAt, panByFraction, resetView } = useZoom({
+    dataMin: min,
+    dataMax: max,
+    minZoom,
+    maxZoom,
+    controlledMin: controlledViewMin,
+    controlledMax: controlledViewMax,
+    onChange: onViewChange
+  });
   const [liveStroke, setLiveStroke] = useState(null);
   const svgPoint = useRef(null);
   useEffect(() => {
@@ -337,6 +435,12 @@ function NumberLineProvider({
         showGroupTicks,
         showMajorTicks,
         showMinorTicks,
+        viewMin,
+        viewMax,
+        enableZoom,
+        resetView,
+        zoomAt,
+        panByFraction,
         tool: drawing.tool,
         strokes: drawing.strokes,
         liveStroke,
@@ -384,22 +488,24 @@ function gcd(a, b) {
 }
 const AxisLayer = React.memo(function AxisLayer2({
   min,
-  max,
+  viewMin,
+  viewMax,
   axisY,
   padLeft,
   padRight,
   viewWidth,
   containerWidth,
   groupSize,
+  groupCount,
   tickStep,
   showGroupTicks,
   showMajorTicks,
   showMinorTicks
 }) {
-  const range = max - min;
+  const range = viewMax - viewMin;
   if (range <= 0) return null;
   const usable = viewWidth - padLeft - padRight;
-  const toX = (v) => padLeft + (v - min) / range * usable;
+  const toX = (v) => padLeft + (v - viewMin) / range * usable;
   const step = Math.max(1, Math.round(tickStep));
   const rawLabelStep = computeLabelStep(containerWidth, range);
   const labelStep = Math.max(step, Math.ceil(rawLabelStep / step) * step);
@@ -407,8 +513,11 @@ const AxisLayer = React.memo(function AxisLayer2({
   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 startVal = Math.floor(viewMin / iterStep) * iterStep;
   const allTicks = [];
-  for (let v = min; v <= max; v += iterStep) allTicks.push(v);
+  for (let v = startVal; v <= viewMax; v += iterStep) {
+    if (v >= viewMin && v <= viewMax) allTicks.push(v);
+  }
   return /* @__PURE__ */ jsxs("g", { className: "nl-axis-layer", children: [
     /* @__PURE__ */ jsx(
       "line",
@@ -425,7 +534,8 @@ const AxisLayer = React.memo(function AxisLayer2({
       const x = toX(v);
       const offset = v - min;
       const isMajor = offset % step === 0;
-      const isGroupBoundary = groupSize > 0 && offset % groupSize === 0;
+      const maxGroupBoundary = min + groupCount * groupSize;
+      const isGroupBoundary = groupSize > 0 && offset % groupSize === 0 && v <= maxGroupBoundary;
       const visible = isGroupBoundary && showGroupTicks || isMajor && showMajorTicks || !isGroupBoundary && !isMajor && showMinorTicks;
       if (!visible) return null;
       const renderAsGroup = isGroupBoundary && showGroupTicks;
@@ -466,6 +576,8 @@ const AxisLayer = React.memo(function AxisLayer2({
 const GroupArcsLayer = memo(function GroupArcsLayer2({
   min,
   max,
+  viewMin,
+  viewMax,
   groupSize,
   groupCount,
   axisY,
@@ -480,15 +592,17 @@ const GroupArcsLayer = memo(function GroupArcsLayer2({
   arcColors = ARC_COLORS
 }) {
   if (groupSize <= 0 || groupCount <= 0) return null;
-  const range = max - min;
+  const range = viewMax - viewMin;
   const usable = viewWidth - padLeft - padRight;
-  const toX = (v) => padLeft + (v - min) / range * usable;
+  const toX = (v) => padLeft + (v - viewMin) / range * usable;
+  const clipId = React.useId().replace(/:/g, "_") + "-arcs-clip";
   const arcs = [];
   for (let g = 0; g < groupCount; g++) {
     if (deletedArcIndices.has(g)) continue;
     const start = min + g * groupSize;
     const end = start + groupSize;
     if (end > max) break;
+    if (end < viewMin || start > viewMax) continue;
     const x1 = toX(start);
     const x2 = toX(end);
     const rx = (x2 - x1) / 2;
@@ -534,7 +648,7 @@ const GroupArcsLayer = memo(function GroupArcsLayer2({
             strokeLinecap: "round",
             pointerEvents: "stroke",
             style: { cursor: hitCursor },
-            onPointerDown: (e) => {
+            onClick: (e) => {
               if (tool === "eraser" || tool === "none") {
                 e.stopPropagation();
                 onArcClick(g, e);
@@ -579,7 +693,18 @@ const GroupArcsLayer = memo(function GroupArcsLayer2({
       ] }, g)
     );
   }
-  return /* @__PURE__ */ jsx("g", { className: "nl-arcs-layer", children: arcs });
+  return /* @__PURE__ */ jsxs("g", { className: "nl-arcs-layer", children: [
+    /* @__PURE__ */ jsx("defs", { children: /* @__PURE__ */ jsx("clipPath", { id: clipId, children: /* @__PURE__ */ jsx(
+      "rect",
+      {
+        x: padLeft,
+        y: 0,
+        width: usable,
+        height: axisY + 1
+      }
+    ) }) }),
+    /* @__PURE__ */ jsx("g", { clipPath: `url(#${clipId})`, children: arcs })
+  ] });
 });
 function DrawingLayer({ strokes, liveStroke, tool, width, height, onStrokeClick }) {
   return /* @__PURE__ */ jsxs("g", { className: "nl-drawing-layer", transform: `scale(${width} ${height})`, children: [
@@ -609,7 +734,7 @@ function DrawingLayer({ strokes, liveStroke, tool, width, height, onStrokeClick
           vectorEffect: "non-scaling-stroke",
           pointerEvents: "stroke",
           style: { cursor: tool === "eraser" ? "cell" : tool === "none" ? "pointer" : "default" },
-          onPointerDown: (e) => {
+          onClick: (e) => {
             if (tool === "eraser" || tool === "none") {
               e.stopPropagation();
               onStrokeClick(s.id, e);
@@ -667,6 +792,12 @@ function NumberLine({ className }) {
     showGroupTicks,
     showMajorTicks,
     showMinorTicks,
+    viewMin,
+    viewMax,
+    enableZoom,
+    resetView,
+    zoomAt,
+    panByFraction,
     tool,
     strokes,
     liveStroke,
@@ -682,6 +813,137 @@ function NumberLine({ className }) {
   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);
+  const [isZoomActive, setIsZoomActive] = useState(false);
+  const [isPanning, setIsPanning] = useState(false);
+  const panStart = useRef(null);
+  const activePointers = useRef(/* @__PURE__ */ new Map());
+  const pinchState = useRef(null);
+  const handleWheel = useCallback(
+    (e) => {
+      if (!enableZoom || !isZoomActive) return;
+      e.preventDefault();
+      e.stopPropagation();
+      const svg = svgRef.current;
+      if (!svg) return;
+      const rect = svg.getBoundingClientRect();
+      const mouseX = e.clientX - rect.left;
+      const fraction = mouseX / w;
+      const factor = e.deltaY < 0 ? 1.15 : 1 / 1.15;
+      zoomAt(factor, fraction);
+    },
+    [enableZoom, isZoomActive, svgRef, w, zoomAt]
+  );
+  const handlePanStart = useCallback(
+    (e) => {
+      if (!enableZoom || tool !== "none") return;
+      if (e.button !== 0 && e.button !== 1) return;
+      const svg = svgRef.current;
+      if (!svg) return;
+      const rect = svg.getBoundingClientRect();
+      panStart.current = { x: e.clientX - rect.left, pointerId: e.pointerId };
+    },
+    [enableZoom, tool, svgRef]
+  );
+  const handlePanMove = useCallback(
+    (e) => {
+      if (!enableZoom || !panStart.current) return;
+      if (e.pointerId !== panStart.current.pointerId) return;
+      const svg = svgRef.current;
+      if (!svg) return;
+      const rect = svg.getBoundingClientRect();
+      const x = e.clientX - rect.left;
+      const dx = x - panStart.current.x;
+      if (!isPanning && Math.abs(dx) < 5) return;
+      if (!isPanning) {
+        setIsPanning(true);
+        svg.setPointerCapture(e.pointerId);
+      }
+      const df = -dx / w;
+      panByFraction(df);
+      panStart.current.x = x;
+    },
+    [enableZoom, isPanning, svgRef, w, panByFraction]
+  );
+  const handlePanEnd = useCallback(() => {
+    panStart.current = null;
+    setIsPanning(false);
+  }, []);
+  const updatePinch = useCallback(() => {
+    if (!enableZoom || activePointers.current.size !== 2) return;
+    const [p1, p2] = Array.from(activePointers.current.values());
+    const dist = Math.hypot(p2.x - p1.x, p2.y - p1.y);
+    const midX = (p1.x + p2.x) / 2;
+    if (!pinchState.current) {
+      pinchState.current = { dist, midX };
+    } else {
+      const factor = dist / pinchState.current.dist;
+      const fraction = midX / w;
+      zoomAt(factor, fraction);
+      pinchState.current = { dist, midX };
+    }
+  }, [enableZoom, w, zoomAt]);
+  const handlePointerDown = useCallback(
+    (e) => {
+      if (e.pointerType === "touch" && enableZoom) {
+        const svg = svgRef.current;
+        if (!svg) return;
+        const rect = svg.getBoundingClientRect();
+        activePointers.current.set(e.pointerId, {
+          x: e.clientX - rect.left,
+          y: e.clientY - rect.top
+        });
+        setIsZoomActive(true);
+        updatePinch();
+      }
+      if (tool === "pen") {
+        onPointerDown(e);
+      } else {
+        handlePanStart(e);
+        onPointerDown(e);
+      }
+    },
+    [tool, enableZoom, svgRef, onPointerDown, handlePanStart, updatePinch]
+  );
+  const handlePointerMove = useCallback(
+    (e) => {
+      if (e.pointerType === "touch" && enableZoom && activePointers.current.has(e.pointerId)) {
+        const svg = svgRef.current;
+        if (!svg) return;
+        const rect = svg.getBoundingClientRect();
+        activePointers.current.set(e.pointerId, {
+          x: e.clientX - rect.left,
+          y: e.clientY - rect.top
+        });
+        updatePinch();
+      }
+      onPointerMove(e);
+      handlePanMove(e);
+    },
+    [enableZoom, svgRef, onPointerMove, handlePanMove, updatePinch]
+  );
+  const handlePointerUp = useCallback(
+    (e) => {
+      if (activePointers.current.has(e.pointerId)) {
+        activePointers.current.delete(e.pointerId);
+        if (activePointers.current.size < 2) {
+          pinchState.current = null;
+        }
+        if (activePointers.current.size === 0 && e.pointerType === "touch") {
+          setIsZoomActive(false);
+        }
+      }
+      onPointerUp();
+      handlePanEnd();
+    },
+    [onPointerUp, handlePanEnd]
+  );
+  const handleDoubleClick = useCallback(
+    () => {
+      if (!enableZoom) return;
+      resetView();
+    },
+    [enableZoom, resetView]
+  );
   return /* @__PURE__ */ jsxs(
     "svg",
     {
@@ -690,22 +952,38 @@ function NumberLine({ className }) {
       className: className ? `nl-svg ${className}` : "nl-svg",
       viewBox: `0 0 ${w} ${h}`,
       preserveAspectRatio: "none",
-      style: { width: "100%", height: "100%", display: "block", outline: "none", cursor: svgCursor, touchAction: "none" },
-      onPointerDown,
-      onPointerMove,
-      onPointerUp,
+      style: {
+        width: "100%",
+        height: "100%",
+        display: "block",
+        outline: enableZoom && isZoomActive ? "2px solid rgba(59, 130, 246, 0.5)" : "none",
+        cursor: svgCursor,
+        touchAction: "none"
+      },
+      onPointerDown: handlePointerDown,
+      onPointerMove: handlePointerMove,
+      onPointerUp: handlePointerUp,
+      onWheel: handleWheel,
+      onDoubleClick: handleDoubleClick,
+      onMouseEnter: () => enableZoom && setIsZoomActive(true),
+      onMouseLeave: () => enableZoom && setIsZoomActive(false),
+      onFocus: () => enableZoom && setIsZoomActive(true),
+      onBlur: () => enableZoom && setIsZoomActive(false),
       children: [
         /* @__PURE__ */ jsx(
           AxisLayer,
           {
             min,
             max,
+            viewMin,
+            viewMax,
             axisY,
             padLeft: PAD_LEFT,
             padRight: PAD_RIGHT,
             viewWidth: w,
             containerWidth: w,
             groupSize,
+            groupCount,
             tickStep,
             showGroupTicks,
             showMajorTicks,
@@ -717,6 +995,8 @@ function NumberLine({ className }) {
           {
             min,
             max,
+            viewMin,
+            viewMax,
             groupSize,
             groupCount,
             axisY,

package/package.json

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