+97

packages/core/src/tools.ts

reviewed

··· 1 1 + import type { Action } from "./actions"; 2 2 + import type { EditorState, ToolId } from "./reactivity"; 3 3 + 4 4 + /** 5 5 + * Tool interface - defines behavior for each editor tool 6 6 + * 7 7 + * Tools are explicit state machines that handle user input actions. 8 8 + * Each tool decides how to respond to actions and can update editor state. 9 9 + */ 10 10 + export interface Tool { 11 11 + /** Unique identifier for this tool */ 12 12 + readonly id: ToolId; 13 13 + 14 14 + /** 15 15 + * Called when the tool becomes active 16 16 + * 17 17 + * @param state - Current editor state 18 18 + * @returns Updated editor state 19 19 + */ 20 20 + onEnter(state: EditorState): EditorState; 21 21 + 22 22 + /** 23 23 + * Called when an action occurs while this tool is active 24 24 + * 25 25 + * @param state - Current editor state 26 26 + * @param action - The action to handle 27 27 + * @returns Updated editor state 28 28 + */ 29 29 + onAction(state: EditorState, action: Action): EditorState; 30 30 + 31 31 + /** 32 32 + * Called when the tool becomes inactive 33 33 + * 34 34 + * @param state - Current editor state 35 35 + * @returns Updated editor state 36 36 + */ 37 37 + onExit(state: EditorState): EditorState; 38 38 + } 39 39 + 40 40 + /** 41 41 + * Route an action to the currently active tool 42 42 + * 43 43 + * @param state - Current editor state 44 44 + * @param action - Action to route 45 45 + * @param tools - Map of tool ID to tool instance 46 46 + * @returns Updated editor state after tool handles the action 47 47 + */ 48 48 + export function routeAction(state: EditorState, action: Action, tools: Map<ToolId, Tool>): EditorState { 49 49 + const currentTool = tools.get(state.ui.toolId); 50 50 + if (!currentTool) return state; 51 51 + return currentTool.onAction(state, action); 52 52 + } 53 53 + 54 54 + /** 55 55 + * Switch from current tool to a new tool 56 56 + * 57 57 + * Calls onExit on the current tool (if it exists), then onEnter on the new tool. 58 58 + * 59 59 + * @param state - Current editor state 60 60 + * @param newToolId - ID of tool to switch to 61 61 + * @param tools - Map of tool ID to tool instance 62 62 + * @returns Updated editor state with new tool active 63 63 + */ 64 64 + export function switchTool(state: EditorState, newToolId: ToolId, tools: Map<ToolId, Tool>): EditorState { 65 65 + if (state.ui.toolId === newToolId) { 66 66 + return state; 67 67 + } 68 68 + 69 69 + const currentTool = tools.get(state.ui.toolId); 70 70 + let nextState = state; 71 71 + if (currentTool) { 72 72 + nextState = currentTool.onExit(nextState); 73 73 + } 74 74 + 75 75 + nextState = { ...nextState, ui: { ...nextState.ui, toolId: newToolId } }; 76 76 + 77 77 + const newTool = tools.get(newToolId); 78 78 + if (newTool) { 79 79 + nextState = newTool.onEnter(nextState); 80 80 + } 81 81 + 82 82 + return nextState; 83 83 + } 84 84 + 85 85 + /** 86 86 + * Create a map of tools from an array 87 87 + * 88 88 + * @param toolList - Array of tool instances 89 89 + * @returns Map of tool ID to tool instance 90 90 + */ 91 91 + export function createToolMap(toolList: Tool[]): Map<ToolId, Tool> { 92 92 + const map = new Map<ToolId, Tool>(); 93 93 + for (const tool of toolList) { 94 94 + map.set(tool.id, tool); 95 95 + } 96 96 + return map; 97 97 + }

+449

packages/core/tests/tools.test.ts

reviewed

··· 1 1 + import { describe, expect, it } from "vitest"; 2 2 + import { Action, Modifiers, PointerButtons } from "../src/actions"; 3 3 + import { Vec2 } from "../src/math"; 4 4 + import { EditorState } from "../src/reactivity"; 5 5 + import type { Tool } from "../src/tools"; 6 6 + import { createToolMap, routeAction, switchTool } from "../src/tools"; 7 7 + 8 8 + describe("Tools", () => { 9 9 + describe("Tool interface", () => { 10 10 + it("should allow creating a tool with all required methods", () => { 11 11 + const tool: Tool = { 12 12 + id: "select", 13 13 + onEnter: (state) => state, 14 14 + onAction: (state, _action) => state, 15 15 + onExit: (state) => state, 16 16 + }; 17 17 + 18 18 + expect(tool.id).toBe("select"); 19 19 + expect(typeof tool.onEnter).toBe("function"); 20 20 + expect(typeof tool.onAction).toBe("function"); 21 21 + expect(typeof tool.onExit).toBe("function"); 22 22 + }); 23 23 + }); 24 24 + 25 25 + describe("createToolMap", () => { 26 26 + it("should create a map from tool array", () => { 27 27 + const selectTool: Tool = { 28 28 + id: "select", 29 29 + onEnter: (state) => state, 30 30 + onAction: (state, _action) => state, 31 31 + onExit: (state) => state, 32 32 + }; 33 33 + 34 34 + const rectTool: Tool = { 35 35 + id: "rect", 36 36 + onEnter: (state) => state, 37 37 + onAction: (state, _action) => state, 38 38 + onExit: (state) => state, 39 39 + }; 40 40 + 41 41 + const map = createToolMap([selectTool, rectTool]); 42 42 + 43 43 + expect(map.size).toBe(2); 44 44 + expect(map.get("select")).toBe(selectTool); 45 45 + expect(map.get("rect")).toBe(rectTool); 46 46 + }); 47 47 + 48 48 + it("should handle empty array", () => { 49 49 + const map = createToolMap([]); 50 50 + expect(map.size).toBe(0); 51 51 + }); 52 52 + }); 53 53 + 54 54 + describe("switchTool", () => { 55 55 + it("should call onExit and onEnter in correct order when switching tools", () => { 56 56 + const callLog: string[] = []; 57 57 + 58 58 + const selectTool: Tool = { 59 59 + id: "select", 60 60 + onEnter: (state) => { 61 61 + callLog.push("select:onEnter"); 62 62 + return state; 63 63 + }, 64 64 + onAction: (state, _action) => state, 65 65 + onExit: (state) => { 66 66 + callLog.push("select:onExit"); 67 67 + return state; 68 68 + }, 69 69 + }; 70 70 + 71 71 + const rectTool: Tool = { 72 72 + id: "rect", 73 73 + onEnter: (state) => { 74 74 + callLog.push("rect:onEnter"); 75 75 + return state; 76 76 + }, 77 77 + onAction: (state, _action) => state, 78 78 + onExit: (state) => { 79 79 + callLog.push("rect:onExit"); 80 80 + return state; 81 81 + }, 82 82 + }; 83 83 + 84 84 + const tools = createToolMap([selectTool, rectTool]); 85 85 + const initialState = EditorState.create(); 86 86 + const newState = switchTool(initialState, "rect", tools); 87 87 + 88 88 + expect(callLog).toEqual(["select:onExit", "rect:onEnter"]); 89 89 + expect(newState.ui.toolId).toBe("rect"); 90 90 + }); 91 91 + 92 92 + it("should update toolId in state", () => { 93 93 + const selectTool: Tool = { 94 94 + id: "select", 95 95 + onEnter: (state) => state, 96 96 + onAction: (state, _action) => state, 97 97 + onExit: (state) => state, 98 98 + }; 99 99 + 100 100 + const rectTool: Tool = { 101 101 + id: "rect", 102 102 + onEnter: (state) => state, 103 103 + onAction: (state, _action) => state, 104 104 + onExit: (state) => state, 105 105 + }; 106 106 + 107 107 + const tools = createToolMap([selectTool, rectTool]); 108 108 + const initialState = EditorState.create(); 109 109 + 110 110 + expect(initialState.ui.toolId).toBe("select"); 111 111 + 112 112 + const newState = switchTool(initialState, "rect", tools); 113 113 + expect(newState.ui.toolId).toBe("rect"); 114 114 + }); 115 115 + 116 116 + it("should do nothing if already on the target tool", () => { 117 117 + const callLog: string[] = []; 118 118 + 119 119 + const selectTool: Tool = { 120 120 + id: "select", 121 121 + onEnter: (state) => { 122 122 + callLog.push("select:onEnter"); 123 123 + return state; 124 124 + }, 125 125 + onAction: (state, _action) => state, 126 126 + onExit: (state) => { 127 127 + callLog.push("select:onExit"); 128 128 + return state; 129 129 + }, 130 130 + }; 131 131 + 132 132 + const tools = createToolMap([selectTool]); 133 133 + const initialState = EditorState.create(); 134 134 + 135 135 + const newState = switchTool(initialState, "select", tools); 136 136 + 137 137 + expect(callLog).toEqual([]); 138 138 + expect(newState.ui.toolId).toBe("select"); 139 139 + expect(newState).toBe(initialState); 140 140 + }); 141 141 + 142 142 + it("should handle switching when current tool is not registered", () => { 143 143 + const rectTool: Tool = { 144 144 + id: "rect", 145 145 + onEnter: (state) => state, 146 146 + onAction: (state, _action) => state, 147 147 + onExit: (state) => state, 148 148 + }; 149 149 + 150 150 + const tools = createToolMap([rectTool]); 151 151 + const initialState = EditorState.create(); 152 152 + const newState = switchTool(initialState, "rect", tools); 153 153 + expect(newState.ui.toolId).toBe("rect"); 154 154 + }); 155 155 + 156 156 + it("should handle switching to unregistered tool", () => { 157 157 + const selectTool: Tool = { 158 158 + id: "select", 159 159 + onEnter: (state) => state, 160 160 + onAction: (state, _action) => state, 161 161 + onExit: (state) => state, 162 162 + }; 163 163 + 164 164 + const tools = createToolMap([selectTool]); 165 165 + const initialState = EditorState.create(); 166 166 + const newState = switchTool(initialState, "rect", tools); 167 167 + expect(newState.ui.toolId).toBe("rect"); 168 168 + }); 169 169 + 170 170 + it("should allow tools to modify state during onExit and onEnter", () => { 171 171 + const selectTool: Tool = { 172 172 + id: "select", 173 173 + onEnter: (state) => state, 174 174 + onAction: (state, _action) => state, 175 175 + onExit: (state) => ({ ...state, ui: { ...state.ui, selectionIds: [] } }), 176 176 + }; 177 177 + 178 178 + const rectTool: Tool = { 179 179 + id: "rect", 180 180 + onEnter: (state) => ({ ...state, ui: { ...state.ui, selectionIds: [] } }), 181 181 + onAction: (state, _action) => state, 182 182 + onExit: (state) => state, 183 183 + }; 184 184 + 185 185 + const tools = createToolMap([selectTool, rectTool]); 186 186 + const initialState = { 187 187 + ...EditorState.create(), 188 188 + ui: { ...EditorState.create().ui, selectionIds: ["shape-1", "shape-2"] }, 189 189 + }; 190 190 + 191 191 + const newState = switchTool(initialState, "rect", tools); 192 192 + 193 193 + expect(newState.ui.toolId).toBe("rect"); 194 194 + expect(newState.ui.selectionIds).toEqual([]); 195 195 + }); 196 196 + }); 197 197 + 198 198 + describe("routeAction", () => { 199 199 + it("should delegate action to active tool", () => { 200 200 + const actionsReceived: Action[] = []; 201 201 + 202 202 + const selectTool: Tool = { 203 203 + id: "select", 204 204 + onEnter: (state) => state, 205 205 + onAction: (state, action) => { 206 206 + actionsReceived.push(action); 207 207 + return state; 208 208 + }, 209 209 + onExit: (state) => state, 210 210 + }; 211 211 + 212 212 + const tools = createToolMap([selectTool]); 213 213 + const state = EditorState.create(); 214 214 + 215 215 + const action = Action.pointerDown( 216 216 + Vec2.create(100, 200), 217 217 + Vec2.create(50, 100), 218 218 + 0, 219 219 + PointerButtons.create(true, false, false), 220 220 + Modifiers.create(), 221 221 + ); 222 222 + 223 223 + routeAction(state, action, tools); 224 224 + 225 225 + expect(actionsReceived).toHaveLength(1); 226 226 + expect(actionsReceived[0]).toMatchObject({ 227 227 + type: "pointer-down", 228 228 + screen: { x: 100, y: 200 }, 229 229 + world: { x: 50, y: 100 }, 230 230 + }); 231 231 + }); 232 232 + 233 233 + it("should allow tool to update state based on action", () => { 234 234 + const selectTool: Tool = { 235 235 + id: "select", 236 236 + onEnter: (state) => state, 237 237 + onAction: (state, action) => { 238 238 + if (action.type === "pointer-down") { 239 239 + return { ...state, ui: { ...state.ui, selectionIds: ["shape-1"] } }; 240 240 + } 241 241 + return state; 242 242 + }, 243 243 + onExit: (state) => state, 244 244 + }; 245 245 + 246 246 + const tools = createToolMap([selectTool]); 247 247 + const initialState = EditorState.create(); 248 248 + 249 249 + const action = Action.pointerDown( 250 250 + Vec2.create(100, 200), 251 251 + Vec2.create(50, 100), 252 252 + 0, 253 253 + PointerButtons.create(true, false, false), 254 254 + Modifiers.create(), 255 255 + ); 256 256 + 257 257 + const newState = routeAction(initialState, action, tools); 258 258 + 259 259 + expect(newState.ui.selectionIds).toEqual(["shape-1"]); 260 260 + }); 261 261 + 262 262 + it("should return state unchanged if current tool is not registered", () => { 263 263 + const tools = createToolMap([]); 264 264 + const state = EditorState.create(); 265 265 + 266 266 + const action = Action.pointerDown( 267 267 + Vec2.create(100, 200), 268 268 + Vec2.create(50, 100), 269 269 + 0, 270 270 + PointerButtons.create(true, false, false), 271 271 + Modifiers.create(), 272 272 + ); 273 273 + 274 274 + const newState = routeAction(state, action, tools); 275 275 + 276 276 + expect(newState).toBe(state); 277 277 + }); 278 278 + 279 279 + it("should allow tool to ignore actions it doesn't care about", () => { 280 280 + const callLog: string[] = []; 281 281 + 282 282 + const selectTool: Tool = { 283 283 + id: "select", 284 284 + onEnter: (state) => state, 285 285 + onAction: (state, action) => { 286 286 + if (action.type.startsWith("pointer-")) { 287 287 + callLog.push(action.type); 288 288 + return { ...state, ui: { ...state.ui, selectionIds: ["handled"] } }; 289 289 + } 290 290 + 291 291 + return state; 292 292 + }, 293 293 + onExit: (state) => state, 294 294 + }; 295 295 + 296 296 + const tools = createToolMap([selectTool]); 297 297 + const state = EditorState.create(); 298 298 + const keyAction = Action.keyDown("a", "KeyA", Modifiers.create()); 299 299 + const afterKeyAction = routeAction(state, keyAction, tools); 300 300 + 301 301 + expect(afterKeyAction.ui.selectionIds).toEqual([]); 302 302 + expect(callLog).toEqual([]); 303 303 + 304 304 + const pointerAction = Action.pointerDown( 305 305 + Vec2.create(0, 0), 306 306 + Vec2.create(0, 0), 307 307 + 0, 308 308 + PointerButtons.create(true, false, false), 309 309 + Modifiers.create(), 310 310 + ); 311 311 + const afterPointerAction = routeAction(state, pointerAction, tools); 312 312 + 313 313 + expect(afterPointerAction.ui.selectionIds).toEqual(["handled"]); 314 314 + expect(callLog).toEqual(["pointer-down"]); 315 315 + }); 316 316 + 317 317 + it("should handle multiple different actions deterministically", () => { 318 318 + const stateLog: string[] = []; 319 319 + 320 320 + const dummyTool: Tool = { 321 321 + id: "select", 322 322 + onEnter: (state) => state, 323 323 + onAction: (state, action) => { 324 324 + switch (action.type) { 325 325 + case "pointer-down": { 326 326 + stateLog.push("down"); 327 327 + return { ...state, ui: { ...state.ui, selectionIds: ["pointer-down"] } }; 328 328 + } 329 329 + case "pointer-move": { 330 330 + stateLog.push("move"); 331 331 + return { ...state, ui: { ...state.ui, selectionIds: ["pointer-move"] } }; 332 332 + } 333 333 + case "pointer-up": { 334 334 + stateLog.push("up"); 335 335 + return { ...state, ui: { ...state.ui, selectionIds: [] } }; 336 336 + } 337 337 + default: { 338 338 + return state; 339 339 + } 340 340 + } 341 341 + }, 342 342 + onExit: (state) => state, 343 343 + }; 344 344 + 345 345 + const tools = createToolMap([dummyTool]); 346 346 + let state = EditorState.create(); 347 347 + 348 348 + const down = Action.pointerDown( 349 349 + Vec2.create(0, 0), 350 350 + Vec2.create(0, 0), 351 351 + 0, 352 352 + PointerButtons.create(true, false, false), 353 353 + Modifiers.create(), 354 354 + ); 355 355 + state = routeAction(state, down, tools); 356 356 + 357 357 + const move = Action.pointerMove( 358 358 + Vec2.create(10, 10), 359 359 + Vec2.create(5, 5), 360 360 + PointerButtons.create(true, false, false), 361 361 + Modifiers.create(), 362 362 + ); 363 363 + state = routeAction(state, move, tools); 364 364 + 365 365 + const up = Action.pointerUp( 366 366 + Vec2.create(10, 10), 367 367 + Vec2.create(5, 5), 368 368 + 0, 369 369 + PointerButtons.create(false, false, false), 370 370 + Modifiers.create(), 371 371 + ); 372 372 + state = routeAction(state, up, tools); 373 373 + 374 374 + expect(stateLog).toEqual(["down", "move", "up"]); 375 375 + expect(state.ui.selectionIds).toEqual([]); 376 376 + }); 377 377 + }); 378 378 + 379 379 + describe("Tool state machine behavior", () => { 380 380 + it("should demonstrate complete tool lifecycle", () => { 381 381 + const lifecycle: string[] = []; 382 382 + 383 383 + const selectTool: Tool = { 384 384 + id: "select", 385 385 + onEnter: (state) => { 386 386 + lifecycle.push("select:enter"); 387 387 + return state; 388 388 + }, 389 389 + onAction: (state, action) => { 390 390 + lifecycle.push(`select:action:${action.type}`); 391 391 + return state; 392 392 + }, 393 393 + onExit: (state) => { 394 394 + lifecycle.push("select:exit"); 395 395 + return state; 396 396 + }, 397 397 + }; 398 398 + 399 399 + const rectTool: Tool = { 400 400 + id: "rect", 401 401 + onEnter: (state) => { 402 402 + lifecycle.push("rect:enter"); 403 403 + return state; 404 404 + }, 405 405 + onAction: (state, action) => { 406 406 + lifecycle.push(`rect:action:${action.type}`); 407 407 + return state; 408 408 + }, 409 409 + onExit: (state) => { 410 410 + lifecycle.push("rect:exit"); 411 411 + return state; 412 412 + }, 413 413 + }; 414 414 + 415 415 + const tools = createToolMap([selectTool, rectTool]); 416 416 + let _state = EditorState.create(); 417 417 + 418 418 + const action1 = Action.pointerDown( 419 419 + Vec2.create(0, 0), 420 420 + Vec2.create(0, 0), 421 421 + 0, 422 422 + PointerButtons.create(true, false, false), 423 423 + Modifiers.create(), 424 424 + ); 425 425 + _state = routeAction(_state, action1, tools); 426 426 + 427 427 + _state = switchTool(_state, "rect", tools); 428 428 + 429 429 + const action2 = Action.pointerMove( 430 430 + Vec2.create(10, 10), 431 431 + Vec2.create(5, 5), 432 432 + PointerButtons.create(true, false, false), 433 433 + Modifiers.create(), 434 434 + ); 435 435 + _state = routeAction(_state, action2, tools); 436 436 + 437 437 + _state = switchTool(_state, "select", tools); 438 438 + 439 439 + expect(lifecycle).toEqual([ 440 440 + "select:action:pointer-down", 441 441 + "select:exit", 442 442 + "rect:enter", 443 443 + "rect:action:pointer-move", 444 444 + "rect:exit", 445 445 + "select:enter", 446 446 + ]); 447 447 + }); 448 448 + }); 449 449 + });