@umituz/web-canvas 1.2.0 → 1.2.1

package/dist/{chunk-YRC4YPMO.mjs → chunk-7YLVULSN.mjs}

@@ -604,19 +604,28 @@ function useReportExport() {
 import { useCallback as useCallback4, useEffect as useEffect4, useRef as useRef4, useState as useState4 } from "react";
 var DEFAULT_BRUSH_SIZE = 3;
 var DEFAULT_COLOR = "#1a1a1a";
+var DEFAULT_KEYBOARD_STEP = 4;
+var KEYBOARD_FAST_FACTOR = 4;
 function widthFor(stroke, point) {
   if (!stroke.dynamic) return stroke.size;
   return stroke.size * (0.5 + Math.min(1, Math.max(0, point.pressure)));
 }
 function useFreehandCanvas(options = {}) {
-  const { brushSize = DEFAULT_BRUSH_SIZE, color = DEFAULT_COLOR, pressureEnabled = true } = options;
-  const optionsRef = useRef4({ brushSize, color, pressureEnabled, onStrokeEnd: options.onStrokeEnd });
-  optionsRef.current = { brushSize, color, pressureEnabled, onStrokeEnd: options.onStrokeEnd };
+  const {
+    brushSize = DEFAULT_BRUSH_SIZE,
+    color = DEFAULT_COLOR,
+    pressureEnabled = true,
+    keyboard = false,
+    keyboardStep = DEFAULT_KEYBOARD_STEP
+  } = options;
+  const optionsRef = useRef4({ brushSize, color, pressureEnabled, keyboardStep, onStrokeEnd: options.onStrokeEnd });
+  optionsRef.current = { brushSize, color, pressureEnabled, keyboardStep, onStrokeEnd: options.onStrokeEnd };
   const canvasRef = useRef4(null);
   const strokesRef = useRef4([]);
   const activeStrokeRef = useRef4(null);
   const activePointerIdRef = useRef4(null);
   const dprRef = useRef4(1);
+  const penRef = useRef4(null);
   const [strokeCount, setStrokeCount] = useState4(0);
   const redraw = useCallback4(() => {
     const canvas = canvasRef.current;
@@ -649,6 +658,18 @@ function useFreehandCanvas(options = {}) {
         ctx.stroke();
       }
     }
+    const pen = penRef.current;
+    if (pen?.engaged && !pen.down) {
+      const reach = 5;
+      ctx.strokeStyle = "rgba(35, 37, 43, 0.55)";
+      ctx.lineWidth = 1;
+      ctx.beginPath();
+      ctx.moveTo(pen.x - reach, pen.y);
+      ctx.lineTo(pen.x + reach, pen.y);
+      ctx.moveTo(pen.x, pen.y - reach);
+      ctx.lineTo(pen.x, pen.y + reach);
+      ctx.stroke();
+    }
   }, []);
   const syncDimensions = useCallback4(() => {
     const canvas = canvasRef.current;
@@ -667,6 +688,8 @@ function useFreehandCanvas(options = {}) {
     if (!canvas) return;
     const el = canvas;
     el.style.touchAction = "none";
+    if (keyboard && !el.hasAttribute("tabindex")) el.tabIndex = 0;
+    if (!penRef.current) penRef.current = { x: el.clientWidth / 2, y: el.clientHeight / 2, down: false, engaged: false };
     syncDimensions();
     redraw();
     const observer = new ResizeObserver(() => {
@@ -715,6 +738,7 @@ function useFreehandCanvas(options = {}) {
         points: [pointFrom(event)]
       };
       activeStrokeRef.current = stroke;
+      penRef.current = { x: stroke.points[0].x, y: stroke.points[0].y, down: false, engaged: false };
       drawDot(stroke, stroke.points[0]);
     }
     function onPointerMove(event) {
@@ -738,18 +762,81 @@ function useFreehandCanvas(options = {}) {
       setStrokeCount(strokesRef.current.length);
       optionsRef.current.onStrokeEnd?.(stroke);
     }
+    function clampPen(pen) {
+      pen.x = Math.min(Math.max(pen.x, 0), Math.max(0, el.clientWidth - 1));
+      pen.y = Math.min(Math.max(pen.y, 0), Math.max(0, el.clientHeight - 1));
+    }
+    function startKeyboardStroke(pen) {
+      const { brushSize: size, color: ink } = optionsRef.current;
+      const stroke = {
+        size,
+        color: ink,
+        dynamic: false,
+        points: [{ x: pen.x, y: pen.y, pressure: 0.5 }]
+      };
+      activeStrokeRef.current = stroke;
+      pen.down = true;
+      drawDot(stroke, stroke.points[0]);
+    }
+    function commitKeyboardStroke(pen) {
+      const stroke = activeStrokeRef.current;
+      if (!stroke) return;
+      activeStrokeRef.current = null;
+      pen.down = false;
+      strokesRef.current = [...strokesRef.current, stroke];
+      setStrokeCount(strokesRef.current.length);
+      optionsRef.current.onStrokeEnd?.(stroke);
+      redraw();
+    }
+    function onKeyDown(event) {
+      const pen = penRef.current;
+      if (!pen) return;
+      const fast = event.shiftKey ? KEYBOARD_FAST_FACTOR : 1;
+      const step = optionsRef.current.keyboardStep * fast;
+      if (event.key === "ArrowLeft" || event.key === "ArrowRight" || event.key === "ArrowUp" || event.key === "ArrowDown") {
+        event.preventDefault();
+        pen.engaged = true;
+        pen.x += event.key === "ArrowLeft" ? -step : event.key === "ArrowRight" ? step : 0;
+        pen.y += event.key === "ArrowUp" ? -step : event.key === "ArrowDown" ? step : 0;
+        clampPen(pen);
+        const stroke = activeStrokeRef.current;
+        if (pen.down && stroke) {
+          const point = { x: pen.x, y: pen.y, pressure: 0.5 };
+          const previous = stroke.points[stroke.points.length - 1];
+          stroke.points.push(point);
+          drawSegment(stroke, previous, point);
+        } else {
+          redraw();
+        }
+        return;
+      }
+      if (event.key === " " || event.key === "Enter") {
+        event.preventDefault();
+        pen.engaged = true;
+        if (pen.down) commitKeyboardStroke(pen);
+        else startKeyboardStroke(pen);
+        return;
+      }
+      if (event.key === "Escape" && pen.down) {
+        activeStrokeRef.current = null;
+        pen.down = false;
+        redraw();
+      }
+    }
     el.addEventListener("pointerdown", onPointerDown);
     el.addEventListener("pointermove", onPointerMove);
     el.addEventListener("pointerup", commit);
     el.addEventListener("pointercancel", commit);
+    if (keyboard) el.addEventListener("keydown", onKeyDown);
     return () => {
       observer.disconnect();
       el.removeEventListener("pointerdown", onPointerDown);
       el.removeEventListener("pointermove", onPointerMove);
       el.removeEventListener("pointerup", commit);
       el.removeEventListener("pointercancel", commit);
+      el.removeEventListener("keydown", onKeyDown);
     };
-  }, [redraw, syncDimensions]);
+  }, [redraw, syncDimensions, keyboard]);
   const undo = useCallback4(() => {
     if (strokesRef.current.length === 0) return;
     strokesRef.current = strokesRef.current.slice(0, -1);

package/dist/domain/index.d.mts

@@ -2,43 +2,23 @@ export { A as AppStoreMetadata, B as BackgroundPattern, u as BackgroundPatternEn
 export { C as CSVExportOptions, E as ExcelExportOptions, a as ExportFormat, P as PDFExportOptions, R as ReportData, b as ReportExportResult, c as ReportItem, d as ReportItemType, e as ReportSummary } from '../report.types-DWDnprBx.mjs';
 export { AIConfig, DEFAULT_DEVICE_CONFIG, DEFAULT_SCREENSHOT_STUDIO_CONFIG, DEVICE_DIMENSIONS, DeviceConfigOption, ExportConfig, ScreenshotStudioConfig } from './config/index.mjs';
 
-/**
- * Freehand Types
- * Types for pointer-based freehand drawing on a canvas
- */
-/**
- * A single sampled point along a stroke, in CSS pixels relative to the canvas
- */
 interface FreehandPoint {
     x: number;
     y: number;
-    /** Normalized stylus pressure (0–1). ~0.5 for mouse/touch when unsupported. */
     pressure: number;
 }
-/**
- * A completed (or in-progress) freehand stroke
- */
 interface FreehandStroke {
-    /** Base brush size in CSS pixels. */
     size: number;
-    /** CSS color of the stroke. */
     color: string;
-    /** True when the stroke should vary width with per-point pressure. */
     dynamic: boolean;
-    /** Ordered points from pointer-down to pointer-up. */
     points: FreehandPoint[];
 }
-/**
- * Options for the useFreehandCanvas hook
- */
 interface UseFreehandCanvasOptions {
-    /** Base brush size in CSS pixels. Default: 3 */
     brushSize?: number;
-    /** Stroke color. Default: '#1a1a1a' */
     color?: string;
-    /** Vary stroke width with stylus pressure (mouse/touch stay constant). Default: true */
     pressureEnabled?: boolean;
-    /** Called after each completed stroke (pointer-up). */
+    keyboard?: boolean;
+    keyboardStep?: number;
     onStrokeEnd?: (stroke: FreehandStroke) => void;
 }
 

package/dist/domain/index.d.ts

@@ -2,43 +2,23 @@ export { A as AppStoreMetadata, B as BackgroundPattern, u as BackgroundPatternEn
 export { C as CSVExportOptions, E as ExcelExportOptions, a as ExportFormat, P as PDFExportOptions, R as ReportData, b as ReportExportResult, c as ReportItem, d as ReportItemType, e as ReportSummary } from '../report.types-DWDnprBx.js';
 export { AIConfig, DEFAULT_DEVICE_CONFIG, DEFAULT_SCREENSHOT_STUDIO_CONFIG, DEVICE_DIMENSIONS, DeviceConfigOption, ExportConfig, ScreenshotStudioConfig } from './config/index.js';
 
-/**
- * Freehand Types
- * Types for pointer-based freehand drawing on a canvas
- */
-/**
- * A single sampled point along a stroke, in CSS pixels relative to the canvas
- */
 interface FreehandPoint {
     x: number;
     y: number;
-    /** Normalized stylus pressure (0–1). ~0.5 for mouse/touch when unsupported. */
     pressure: number;
 }
-/**
- * A completed (or in-progress) freehand stroke
- */
 interface FreehandStroke {
-    /** Base brush size in CSS pixels. */
     size: number;
-    /** CSS color of the stroke. */
     color: string;
-    /** True when the stroke should vary width with per-point pressure. */
     dynamic: boolean;
-    /** Ordered points from pointer-down to pointer-up. */
     points: FreehandPoint[];
 }
-/**
- * Options for the useFreehandCanvas hook
- */
 interface UseFreehandCanvasOptions {
-    /** Base brush size in CSS pixels. Default: 3 */
     brushSize?: number;
-    /** Stroke color. Default: '#1a1a1a' */
     color?: string;
-    /** Vary stroke width with stylus pressure (mouse/touch stay constant). Default: true */
     pressureEnabled?: boolean;
-    /** Called after each completed stroke (pointer-up). */
+    keyboard?: boolean;
+    keyboardStep?: number;
     onStrokeEnd?: (stroke: FreehandStroke) => void;
 }
 

package/dist/index.js

@@ -1806,19 +1806,28 @@ function useReportExport() {
 var import_react4 = require("react");
 var DEFAULT_BRUSH_SIZE = 3;
 var DEFAULT_COLOR = "#1a1a1a";
+var DEFAULT_KEYBOARD_STEP = 4;
+var KEYBOARD_FAST_FACTOR = 4;
 function widthFor(stroke, point) {
   if (!stroke.dynamic) return stroke.size;
   return stroke.size * (0.5 + Math.min(1, Math.max(0, point.pressure)));
 }
 function useFreehandCanvas(options = {}) {
-  const { brushSize = DEFAULT_BRUSH_SIZE, color = DEFAULT_COLOR, pressureEnabled = true } = options;
-  const optionsRef = (0, import_react4.useRef)({ brushSize, color, pressureEnabled, onStrokeEnd: options.onStrokeEnd });
-  optionsRef.current = { brushSize, color, pressureEnabled, onStrokeEnd: options.onStrokeEnd };
+  const {
+    brushSize = DEFAULT_BRUSH_SIZE,
+    color = DEFAULT_COLOR,
+    pressureEnabled = true,
+    keyboard = false,
+    keyboardStep = DEFAULT_KEYBOARD_STEP
+  } = options;
+  const optionsRef = (0, import_react4.useRef)({ brushSize, color, pressureEnabled, keyboardStep, onStrokeEnd: options.onStrokeEnd });
+  optionsRef.current = { brushSize, color, pressureEnabled, keyboardStep, onStrokeEnd: options.onStrokeEnd };
   const canvasRef = (0, import_react4.useRef)(null);
   const strokesRef = (0, import_react4.useRef)([]);
   const activeStrokeRef = (0, import_react4.useRef)(null);
   const activePointerIdRef = (0, import_react4.useRef)(null);
   const dprRef = (0, import_react4.useRef)(1);
+  const penRef = (0, import_react4.useRef)(null);
   const [strokeCount, setStrokeCount] = (0, import_react4.useState)(0);
   const redraw = (0, import_react4.useCallback)(() => {
     const canvas = canvasRef.current;
@@ -1851,6 +1860,18 @@ function useFreehandCanvas(options = {}) {
         ctx.stroke();
       }
     }
+    const pen = penRef.current;
+    if (pen?.engaged && !pen.down) {
+      const reach = 5;
+      ctx.strokeStyle = "rgba(35, 37, 43, 0.55)";
+      ctx.lineWidth = 1;
+      ctx.beginPath();
+      ctx.moveTo(pen.x - reach, pen.y);
+      ctx.lineTo(pen.x + reach, pen.y);
+      ctx.moveTo(pen.x, pen.y - reach);
+      ctx.lineTo(pen.x, pen.y + reach);
+      ctx.stroke();
+    }
   }, []);
   const syncDimensions = (0, import_react4.useCallback)(() => {
     const canvas = canvasRef.current;
@@ -1869,6 +1890,8 @@ function useFreehandCanvas(options = {}) {
     if (!canvas) return;
     const el = canvas;
     el.style.touchAction = "none";
+    if (keyboard && !el.hasAttribute("tabindex")) el.tabIndex = 0;
+    if (!penRef.current) penRef.current = { x: el.clientWidth / 2, y: el.clientHeight / 2, down: false, engaged: false };
     syncDimensions();
     redraw();
     const observer = new ResizeObserver(() => {
@@ -1917,6 +1940,7 @@ function useFreehandCanvas(options = {}) {
         points: [pointFrom(event)]
       };
       activeStrokeRef.current = stroke;
+      penRef.current = { x: stroke.points[0].x, y: stroke.points[0].y, down: false, engaged: false };
       drawDot(stroke, stroke.points[0]);
     }
     function onPointerMove(event) {
@@ -1940,18 +1964,81 @@ function useFreehandCanvas(options = {}) {
       setStrokeCount(strokesRef.current.length);
       optionsRef.current.onStrokeEnd?.(stroke);
     }
+    function clampPen(pen) {
+      pen.x = Math.min(Math.max(pen.x, 0), Math.max(0, el.clientWidth - 1));
+      pen.y = Math.min(Math.max(pen.y, 0), Math.max(0, el.clientHeight - 1));
+    }
+    function startKeyboardStroke(pen) {
+      const { brushSize: size, color: ink } = optionsRef.current;
+      const stroke = {
+        size,
+        color: ink,
+        dynamic: false,
+        points: [{ x: pen.x, y: pen.y, pressure: 0.5 }]
+      };
+      activeStrokeRef.current = stroke;
+      pen.down = true;
+      drawDot(stroke, stroke.points[0]);
+    }
+    function commitKeyboardStroke(pen) {
+      const stroke = activeStrokeRef.current;
+      if (!stroke) return;
+      activeStrokeRef.current = null;
+      pen.down = false;
+      strokesRef.current = [...strokesRef.current, stroke];
+      setStrokeCount(strokesRef.current.length);
+      optionsRef.current.onStrokeEnd?.(stroke);
+      redraw();
+    }
+    function onKeyDown(event) {
+      const pen = penRef.current;
+      if (!pen) return;
+      const fast = event.shiftKey ? KEYBOARD_FAST_FACTOR : 1;
+      const step = optionsRef.current.keyboardStep * fast;
+      if (event.key === "ArrowLeft" || event.key === "ArrowRight" || event.key === "ArrowUp" || event.key === "ArrowDown") {
+        event.preventDefault();
+        pen.engaged = true;
+        pen.x += event.key === "ArrowLeft" ? -step : event.key === "ArrowRight" ? step : 0;
+        pen.y += event.key === "ArrowUp" ? -step : event.key === "ArrowDown" ? step : 0;
+        clampPen(pen);
+        const stroke = activeStrokeRef.current;
+        if (pen.down && stroke) {
+          const point = { x: pen.x, y: pen.y, pressure: 0.5 };
+          const previous = stroke.points[stroke.points.length - 1];
+          stroke.points.push(point);
+          drawSegment(stroke, previous, point);
+        } else {
+          redraw();
+        }
+        return;
+      }
+      if (event.key === " " || event.key === "Enter") {
+        event.preventDefault();
+        pen.engaged = true;
+        if (pen.down) commitKeyboardStroke(pen);
+        else startKeyboardStroke(pen);
+        return;
+      }
+      if (event.key === "Escape" && pen.down) {
+        activeStrokeRef.current = null;
+        pen.down = false;
+        redraw();
+      }
+    }
     el.addEventListener("pointerdown", onPointerDown);
     el.addEventListener("pointermove", onPointerMove);
     el.addEventListener("pointerup", commit);
     el.addEventListener("pointercancel", commit);
+    if (keyboard) el.addEventListener("keydown", onKeyDown);
     return () => {
       observer.disconnect();
       el.removeEventListener("pointerdown", onPointerDown);
       el.removeEventListener("pointermove", onPointerMove);
       el.removeEventListener("pointerup", commit);
       el.removeEventListener("pointercancel", commit);
+      el.removeEventListener("keydown", onKeyDown);
     };
-  }, [redraw, syncDimensions]);
+  }, [redraw, syncDimensions, keyboard]);
   const undo = (0, import_react4.useCallback)(() => {
     if (strokesRef.current.length === 0) return;
     strokesRef.current = strokesRef.current.slice(0, -1);

package/dist/index.mjs

@@ -3,7 +3,7 @@ import {
   useFreehandCanvas,
   useReportExport,
   useScreenshotStudio
-} from "./chunk-YRC4YPMO.mjs";
+} from "./chunk-7YLVULSN.mjs";
 import {
   ReportService,
   ScreenshotStudioService

package/dist/presentation/index.d.mts

@@ -106,40 +106,14 @@ interface UseReportExportReturn {
  */
 declare function useReportExport(): UseReportExportReturn;
 
-/**
- * useFreehandCanvas Hook
- * React hook for pointer-based freehand drawing on a canvas
- */
-
-/**
- * Return value of the useFreehandCanvas hook
- */
 interface UseFreehandCanvasReturn {
-    /** Ref to attach to the <canvas> element that captures drawing. */
     canvasRef: React.RefObject<HTMLCanvasElement | null>;
-    /** Remove the most recent stroke. */
     undo: () => void;
-    /** Remove all strokes. */
     clear: () => void;
-    /** Number of committed strokes. */
     strokeCount: number;
-    /** True when no strokes are committed. */
     isEmpty: boolean;
-    /** Snapshot of committed strokes (safe to serialize). */
     getStrokes: () => FreehandStroke[];
 }
-/**
- * useFreehandCanvas hook
- *
- * Attaches pointer-event drawing to a canvas element. The canvas is sized to
- * its CSS box at device-pixel resolution (and re-rendered on resize), strokes
- * are replayed from captured points so undo/clear are lossless, and stylus
- * pressure modulates line width when the pointer reports it.
- *
- * The canvas gets `touch-action: none` applied so drawing works on touch
- * screens without scrolling the page. Consumers typically layer the canvas
- * over their own guide content (e.g. a faint glyph to trace).
- */
 declare function useFreehandCanvas(options?: UseFreehandCanvasOptions): UseFreehandCanvasReturn;
 
 export { type UseCanvasExportOptions, type UseCanvasExportReturn, type UseFreehandCanvasReturn, type UseReportExportReturn, type UseScreenshotStudioOptions, type UseScreenshotStudioReturn, useCanvasExport, useFreehandCanvas, useReportExport, useScreenshotStudio };

package/dist/presentation/index.d.ts

@@ -106,40 +106,14 @@ interface UseReportExportReturn {
  */
 declare function useReportExport(): UseReportExportReturn;
 
-/**
- * useFreehandCanvas Hook
- * React hook for pointer-based freehand drawing on a canvas
- */
-
-/**
- * Return value of the useFreehandCanvas hook
- */
 interface UseFreehandCanvasReturn {
-    /** Ref to attach to the <canvas> element that captures drawing. */
     canvasRef: React.RefObject<HTMLCanvasElement | null>;
-    /** Remove the most recent stroke. */
     undo: () => void;
-    /** Remove all strokes. */
     clear: () => void;
-    /** Number of committed strokes. */
     strokeCount: number;
-    /** True when no strokes are committed. */
     isEmpty: boolean;
-    /** Snapshot of committed strokes (safe to serialize). */
     getStrokes: () => FreehandStroke[];
 }
-/**
- * useFreehandCanvas hook
- *
- * Attaches pointer-event drawing to a canvas element. The canvas is sized to
- * its CSS box at device-pixel resolution (and re-rendered on resize), strokes
- * are replayed from captured points so undo/clear are lossless, and stylus
- * pressure modulates line width when the pointer reports it.
- *
- * The canvas gets `touch-action: none` applied so drawing works on touch
- * screens without scrolling the page. Consumers typically layer the canvas
- * over their own guide content (e.g. a faint glyph to trace).
- */
 declare function useFreehandCanvas(options?: UseFreehandCanvasOptions): UseFreehandCanvasReturn;
 
 export { type UseCanvasExportOptions, type UseCanvasExportReturn, type UseFreehandCanvasReturn, type UseReportExportReturn, type UseScreenshotStudioOptions, type UseScreenshotStudioReturn, useCanvasExport, useFreehandCanvas, useReportExport, useScreenshotStudio };

package/dist/presentation/index.js

@@ -1800,19 +1800,28 @@ function useReportExport() {
 var import_react4 = require("react");
 var DEFAULT_BRUSH_SIZE = 3;
 var DEFAULT_COLOR = "#1a1a1a";
+var DEFAULT_KEYBOARD_STEP = 4;
+var KEYBOARD_FAST_FACTOR = 4;
 function widthFor(stroke, point) {
   if (!stroke.dynamic) return stroke.size;
   return stroke.size * (0.5 + Math.min(1, Math.max(0, point.pressure)));
 }
 function useFreehandCanvas(options = {}) {
-  const { brushSize = DEFAULT_BRUSH_SIZE, color = DEFAULT_COLOR, pressureEnabled = true } = options;
-  const optionsRef = (0, import_react4.useRef)({ brushSize, color, pressureEnabled, onStrokeEnd: options.onStrokeEnd });
-  optionsRef.current = { brushSize, color, pressureEnabled, onStrokeEnd: options.onStrokeEnd };
+  const {
+    brushSize = DEFAULT_BRUSH_SIZE,
+    color = DEFAULT_COLOR,
+    pressureEnabled = true,
+    keyboard = false,
+    keyboardStep = DEFAULT_KEYBOARD_STEP
+  } = options;
+  const optionsRef = (0, import_react4.useRef)({ brushSize, color, pressureEnabled, keyboardStep, onStrokeEnd: options.onStrokeEnd });
+  optionsRef.current = { brushSize, color, pressureEnabled, keyboardStep, onStrokeEnd: options.onStrokeEnd };
   const canvasRef = (0, import_react4.useRef)(null);
   const strokesRef = (0, import_react4.useRef)([]);
   const activeStrokeRef = (0, import_react4.useRef)(null);
   const activePointerIdRef = (0, import_react4.useRef)(null);
   const dprRef = (0, import_react4.useRef)(1);
+  const penRef = (0, import_react4.useRef)(null);
   const [strokeCount, setStrokeCount] = (0, import_react4.useState)(0);
   const redraw = (0, import_react4.useCallback)(() => {
     const canvas = canvasRef.current;
@@ -1845,6 +1854,18 @@ function useFreehandCanvas(options = {}) {
         ctx.stroke();
       }
     }
+    const pen = penRef.current;
+    if (pen?.engaged && !pen.down) {
+      const reach = 5;
+      ctx.strokeStyle = "rgba(35, 37, 43, 0.55)";
+      ctx.lineWidth = 1;
+      ctx.beginPath();
+      ctx.moveTo(pen.x - reach, pen.y);
+      ctx.lineTo(pen.x + reach, pen.y);
+      ctx.moveTo(pen.x, pen.y - reach);
+      ctx.lineTo(pen.x, pen.y + reach);
+      ctx.stroke();
+    }
   }, []);
   const syncDimensions = (0, import_react4.useCallback)(() => {
     const canvas = canvasRef.current;
@@ -1863,6 +1884,8 @@ function useFreehandCanvas(options = {}) {
     if (!canvas) return;
     const el = canvas;
     el.style.touchAction = "none";
+    if (keyboard && !el.hasAttribute("tabindex")) el.tabIndex = 0;
+    if (!penRef.current) penRef.current = { x: el.clientWidth / 2, y: el.clientHeight / 2, down: false, engaged: false };
     syncDimensions();
     redraw();
     const observer = new ResizeObserver(() => {
@@ -1911,6 +1934,7 @@ function useFreehandCanvas(options = {}) {
         points: [pointFrom(event)]
       };
       activeStrokeRef.current = stroke;
+      penRef.current = { x: stroke.points[0].x, y: stroke.points[0].y, down: false, engaged: false };
       drawDot(stroke, stroke.points[0]);
     }
     function onPointerMove(event) {
@@ -1934,18 +1958,81 @@ function useFreehandCanvas(options = {}) {
       setStrokeCount(strokesRef.current.length);
       optionsRef.current.onStrokeEnd?.(stroke);
     }
+    function clampPen(pen) {
+      pen.x = Math.min(Math.max(pen.x, 0), Math.max(0, el.clientWidth - 1));
+      pen.y = Math.min(Math.max(pen.y, 0), Math.max(0, el.clientHeight - 1));
+    }
+    function startKeyboardStroke(pen) {
+      const { brushSize: size, color: ink } = optionsRef.current;
+      const stroke = {
+        size,
+        color: ink,
+        dynamic: false,
+        points: [{ x: pen.x, y: pen.y, pressure: 0.5 }]
+      };
+      activeStrokeRef.current = stroke;
+      pen.down = true;
+      drawDot(stroke, stroke.points[0]);
+    }
+    function commitKeyboardStroke(pen) {
+      const stroke = activeStrokeRef.current;
+      if (!stroke) return;
+      activeStrokeRef.current = null;
+      pen.down = false;
+      strokesRef.current = [...strokesRef.current, stroke];
+      setStrokeCount(strokesRef.current.length);
+      optionsRef.current.onStrokeEnd?.(stroke);
+      redraw();
+    }
+    function onKeyDown(event) {
+      const pen = penRef.current;
+      if (!pen) return;
+      const fast = event.shiftKey ? KEYBOARD_FAST_FACTOR : 1;
+      const step = optionsRef.current.keyboardStep * fast;
+      if (event.key === "ArrowLeft" || event.key === "ArrowRight" || event.key === "ArrowUp" || event.key === "ArrowDown") {
+        event.preventDefault();
+        pen.engaged = true;
+        pen.x += event.key === "ArrowLeft" ? -step : event.key === "ArrowRight" ? step : 0;
+        pen.y += event.key === "ArrowUp" ? -step : event.key === "ArrowDown" ? step : 0;
+        clampPen(pen);
+        const stroke = activeStrokeRef.current;
+        if (pen.down && stroke) {
+          const point = { x: pen.x, y: pen.y, pressure: 0.5 };
+          const previous = stroke.points[stroke.points.length - 1];
+          stroke.points.push(point);
+          drawSegment(stroke, previous, point);
+        } else {
+          redraw();
+        }
+        return;
+      }
+      if (event.key === " " || event.key === "Enter") {
+        event.preventDefault();
+        pen.engaged = true;
+        if (pen.down) commitKeyboardStroke(pen);
+        else startKeyboardStroke(pen);
+        return;
+      }
+      if (event.key === "Escape" && pen.down) {
+        activeStrokeRef.current = null;
+        pen.down = false;
+        redraw();
+      }
+    }
     el.addEventListener("pointerdown", onPointerDown);
     el.addEventListener("pointermove", onPointerMove);
     el.addEventListener("pointerup", commit);
     el.addEventListener("pointercancel", commit);
+    if (keyboard) el.addEventListener("keydown", onKeyDown);
     return () => {
       observer.disconnect();
       el.removeEventListener("pointerdown", onPointerDown);
       el.removeEventListener("pointermove", onPointerMove);
       el.removeEventListener("pointerup", commit);
       el.removeEventListener("pointercancel", commit);
+      el.removeEventListener("keydown", onKeyDown);
     };
-  }, [redraw, syncDimensions]);
+  }, [redraw, syncDimensions, keyboard]);
   const undo = (0, import_react4.useCallback)(() => {
     if (strokesRef.current.length === 0) return;
     strokesRef.current = strokesRef.current.slice(0, -1);

package/dist/presentation/index.mjs

@@ -3,7 +3,7 @@ import {
   useFreehandCanvas,
   useReportExport,
   useScreenshotStudio
-} from "../chunk-YRC4YPMO.mjs";
+} from "../chunk-7YLVULSN.mjs";
 import "../chunk-P6RJ75US.mjs";
 import "../chunk-UOGTEMIJ.mjs";
 import "../chunk-Z6IB4BQV.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-canvas",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Comprehensive canvas and screenshot generation library with device frames, patterns, and PDF export",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/src/domain/types/freehand.types.ts

@@ -1,42 +1,21 @@
-/**
- * Freehand Types
- * Types for pointer-based freehand drawing on a canvas
- */
-
-/**
- * A single sampled point along a stroke, in CSS pixels relative to the canvas
- */
 export interface FreehandPoint {
   x: number;
   y: number;
-  /** Normalized stylus pressure (0–1). ~0.5 for mouse/touch when unsupported. */
   pressure: number;
 }
 
-/**
- * A completed (or in-progress) freehand stroke
- */
 export interface FreehandStroke {
-  /** Base brush size in CSS pixels. */
   size: number;
-  /** CSS color of the stroke. */
   color: string;
-  /** True when the stroke should vary width with per-point pressure. */
   dynamic: boolean;
-  /** Ordered points from pointer-down to pointer-up. */
   points: FreehandPoint[];
 }
 
-/**
- * Options for the useFreehandCanvas hook
- */
 export interface UseFreehandCanvasOptions {
-  /** Base brush size in CSS pixels. Default: 3 */
   brushSize?: number;
-  /** Stroke color. Default: '#1a1a1a' */
   color?: string;
-  /** Vary stroke width with stylus pressure (mouse/touch stay constant). Default: true */
   pressureEnabled?: boolean;
-  /** Called after each completed stroke (pointer-up). */
+  keyboard?: boolean;
+  keyboardStep?: number;
   onStrokeEnd?: (stroke: FreehandStroke) => void;
 }

package/src/presentation/hooks/useFreehandCanvas.ts

@@ -1,8 +1,3 @@
-/**
- * useFreehandCanvas Hook
- * React hook for pointer-based freehand drawing on a canvas
- */
-
 import { useCallback, useEffect, useRef, useState } from 'react';
 import type {
   FreehandPoint,
@@ -12,64 +7,53 @@ import type {
 
 const DEFAULT_BRUSH_SIZE = 3;
 const DEFAULT_COLOR = '#1a1a1a';
+const DEFAULT_KEYBOARD_STEP = 4;
+const KEYBOARD_FAST_FACTOR = 4;
 
-/**
- * Width for a point: constant for mouse/touch, pressure-scaled for pens
- */
 function widthFor(stroke: FreehandStroke, point: FreehandPoint): number {
   if (!stroke.dynamic) return stroke.size;
-  // pressure is 0 (some mice) – 1 (hard press); clamp the visual range
   return stroke.size * (0.5 + Math.min(1, Math.max(0, point.pressure)));
 }
 
-/**
- * Return value of the useFreehandCanvas hook
- */
 export interface UseFreehandCanvasReturn {
-  /** Ref to attach to the <canvas> element that captures drawing. */
   canvasRef: React.RefObject<HTMLCanvasElement | null>;
-  /** Remove the most recent stroke. */
   undo: () => void;
-  /** Remove all strokes. */
   clear: () => void;
-  /** Number of committed strokes. */
   strokeCount: number;
-  /** True when no strokes are committed. */
   isEmpty: boolean;
-  /** Snapshot of committed strokes (safe to serialize). */
   getStrokes: () => FreehandStroke[];
 }
 
-/**
- * useFreehandCanvas hook
- *
- * Attaches pointer-event drawing to a canvas element. The canvas is sized to
- * its CSS box at device-pixel resolution (and re-rendered on resize), strokes
- * are replayed from captured points so undo/clear are lossless, and stylus
- * pressure modulates line width when the pointer reports it.
- *
- * The canvas gets `touch-action: none` applied so drawing works on touch
- * screens without scrolling the page. Consumers typically layer the canvas
- * over their own guide content (e.g. a faint glyph to trace).
- */
+interface KeyboardPen {
+  x: number;
+  y: number;
+  down: boolean;
+  engaged: boolean;
+}
+
 export function useFreehandCanvas(
   options: UseFreehandCanvasOptions = {}
 ): UseFreehandCanvasReturn {
-  const { brushSize = DEFAULT_BRUSH_SIZE, color = DEFAULT_COLOR, pressureEnabled = true } = options;
+  const {
+    brushSize = DEFAULT_BRUSH_SIZE,
+    color = DEFAULT_COLOR,
+    pressureEnabled = true,
+    keyboard = false,
+    keyboardStep = DEFAULT_KEYBOARD_STEP,
+  } = options;
 
-  // Latest option values for event handlers, without re-binding listeners.
-  const optionsRef = useRef({ brushSize, color, pressureEnabled, onStrokeEnd: options.onStrokeEnd });
-  optionsRef.current = { brushSize, color, pressureEnabled, onStrokeEnd: options.onStrokeEnd };
+  const optionsRef = useRef({ brushSize, color, pressureEnabled, keyboardStep, onStrokeEnd: options.onStrokeEnd });
+  optionsRef.current = { brushSize, color, pressureEnabled, keyboardStep, onStrokeEnd: options.onStrokeEnd };
 
   const canvasRef = useRef<HTMLCanvasElement | null>(null);
   const strokesRef = useRef<FreehandStroke[]>([]);
   const activeStrokeRef = useRef<FreehandStroke | null>(null);
   const activePointerIdRef = useRef<number | null>(null);
   const dprRef = useRef(1);
+  const penRef = useRef<KeyboardPen | null>(null);
 
   const [strokeCount, setStrokeCount] = useState(0);
 
-  /** Replay every committed stroke (and the active one) at current DPR. */
   const redraw = useCallback(() => {
     const canvas = canvasRef.current;
     const ctx = canvas?.getContext('2d');
@@ -103,9 +87,20 @@ export function useFreehandCanvas(
         ctx.stroke();
       }
     }
+    const pen = penRef.current;
+    if (pen?.engaged && !pen.down) {
+      const reach = 5;
+      ctx.strokeStyle = 'rgba(35, 37, 43, 0.55)';
+      ctx.lineWidth = 1;
+      ctx.beginPath();
+      ctx.moveTo(pen.x - reach, pen.y);
+      ctx.lineTo(pen.x + reach, pen.y);
+      ctx.moveTo(pen.x, pen.y - reach);
+      ctx.lineTo(pen.x, pen.y + reach);
+      ctx.stroke();
+    }
   }, []);
 
-  /** Match the backing store to the CSS box; returns true when it changed. */
   const syncDimensions = useCallback((): boolean => {
     const canvas = canvasRef.current;
     if (!canvas) return false;
@@ -125,8 +120,9 @@ export function useFreehandCanvas(
 
     const el: HTMLCanvasElement = canvas;
 
-    // Touch screens must draw, not scroll, while the pointer is down.
     el.style.touchAction = 'none';
+    if (keyboard && !el.hasAttribute('tabindex')) el.tabIndex = 0;
+    if (!penRef.current) penRef.current = { x: el.clientWidth / 2, y: el.clientHeight / 2, down: false, engaged: false };
 
     syncDimensions();
     redraw();
@@ -169,8 +165,6 @@ export function useFreehandCanvas(
 
     function onPointerDown(event: PointerEvent): void {
       if (event.button !== 0 && event.pointerType === 'mouse') return;
-      // Only one stroke at a time: a resting palm or second finger touching
-      // mid-stroke must not hijack or corrupt the active stroke.
       if (activeStrokeRef.current != null) return;
       event.preventDefault();
       el.setPointerCapture(event.pointerId);
@@ -183,6 +177,7 @@ export function useFreehandCanvas(
         points: [pointFrom(event)],
       };
       activeStrokeRef.current = stroke;
+      penRef.current = { x: stroke.points[0].x, y: stroke.points[0].y, down: false, engaged: false };
       drawDot(stroke, stroke.points[0]);
     }
 
@@ -209,10 +204,76 @@ export function useFreehandCanvas(
       optionsRef.current.onStrokeEnd?.(stroke);
     }
 
+    function clampPen(pen: KeyboardPen): void {
+      pen.x = Math.min(Math.max(pen.x, 0), Math.max(0, el.clientWidth - 1));
+      pen.y = Math.min(Math.max(pen.y, 0), Math.max(0, el.clientHeight - 1));
+    }
+
+    function startKeyboardStroke(pen: KeyboardPen): void {
+      const { brushSize: size, color: ink } = optionsRef.current;
+      const stroke: FreehandStroke = {
+        size,
+        color: ink,
+        dynamic: false,
+        points: [{ x: pen.x, y: pen.y, pressure: 0.5 }],
+      };
+      activeStrokeRef.current = stroke;
+      pen.down = true;
+      drawDot(stroke, stroke.points[0]);
+    }
+
+    function commitKeyboardStroke(pen: KeyboardPen): void {
+      const stroke = activeStrokeRef.current;
+      if (!stroke) return;
+      activeStrokeRef.current = null;
+      pen.down = false;
+      strokesRef.current = [...strokesRef.current, stroke];
+      setStrokeCount(strokesRef.current.length);
+      optionsRef.current.onStrokeEnd?.(stroke);
+      redraw();
+    }
+
+    function onKeyDown(event: KeyboardEvent): void {
+      const pen = penRef.current;
+      if (!pen) return;
+      const fast = event.shiftKey ? KEYBOARD_FAST_FACTOR : 1;
+      const step = optionsRef.current.keyboardStep * fast;
+      if (event.key === 'ArrowLeft' || event.key === 'ArrowRight' || event.key === 'ArrowUp' || event.key === 'ArrowDown') {
+        event.preventDefault();
+        pen.engaged = true;
+        pen.x += event.key === 'ArrowLeft' ? -step : event.key === 'ArrowRight' ? step : 0;
+        pen.y += event.key === 'ArrowUp' ? -step : event.key === 'ArrowDown' ? step : 0;
+        clampPen(pen);
+        const stroke = activeStrokeRef.current;
+        if (pen.down && stroke) {
+          const point: FreehandPoint = { x: pen.x, y: pen.y, pressure: 0.5 };
+          const previous = stroke.points[stroke.points.length - 1];
+          stroke.points.push(point);
+          drawSegment(stroke, previous, point);
+        } else {
+          redraw();
+        }
+        return;
+      }
+      if (event.key === ' ' || event.key === 'Enter') {
+        event.preventDefault();
+        pen.engaged = true;
+        if (pen.down) commitKeyboardStroke(pen);
+        else startKeyboardStroke(pen);
+        return;
+      }
+      if (event.key === 'Escape' && pen.down) {
+        activeStrokeRef.current = null;
+        pen.down = false;
+        redraw();
+      }
+    }
+
     el.addEventListener('pointerdown', onPointerDown);
     el.addEventListener('pointermove', onPointerMove);
     el.addEventListener('pointerup', commit);
     el.addEventListener('pointercancel', commit);
+    if (keyboard) el.addEventListener('keydown', onKeyDown);
 
     return () => {
       observer.disconnect();
@@ -220,8 +281,9 @@ export function useFreehandCanvas(
       el.removeEventListener('pointermove', onPointerMove);
       el.removeEventListener('pointerup', commit);
       el.removeEventListener('pointercancel', commit);
+      el.removeEventListener('keydown', onKeyDown);
     };
-  }, [redraw, syncDimensions]);
+  }, [redraw, syncDimensions, keyboard]);
 
   const undo = useCallback(() => {
     if (strokesRef.current.length === 0) return;