feat(abacus-react): add React hooks for abacus calculations

Add AbacusHooks.ts with memoized hooks:
- useAbacusDiff: Calculate bead differences for tutorials
- useAbacusState: Convert numbers to abacus state

These hooks provide performant, memoized access to core utility
functions for use in React components.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Thomas Hallock
2025-11-03 17:07:36 -06:00
parent e65541c100
commit de038d2afc

View File

@@ -0,0 +1,71 @@
/**
* Utility hooks for working with abacus calculations and state
*/
import { useMemo } from 'react'
import {
calculateBeadDiffFromValues,
numberToAbacusState,
type BeadDiffOutput,
type AbacusState,
} from './AbacusUtils'
/**
* Hook to calculate bead differences between two values
* Useful for tutorials, animations, and highlighting which beads need to move
*
* @param fromValue - Starting value
* @param toValue - Target value
* @param maxPlaces - Maximum number of place values to consider (default: 5)
* @returns BeadDiffOutput with changes, highlights, and summary
*
* @example
* ```tsx
* function Tutorial() {
* const diff = useAbacusDiff(5, 15)
*
* return (
* <AbacusReact
* value={currentValue}
* stepBeadHighlights={diff.highlights}
* />
* )
* }
* ```
*/
export function useAbacusDiff(
fromValue: number | bigint,
toValue: number | bigint,
maxPlaces: number = 5
): BeadDiffOutput {
return useMemo(() => {
return calculateBeadDiffFromValues(fromValue, toValue, maxPlaces)
}, [fromValue, toValue, maxPlaces])
}
/**
* Hook to convert a number to abacus state
* Memoized for performance when used in components
*
* @param value - The number to convert
* @param maxPlaces - Maximum number of place values (default: 5)
* @returns AbacusState representing the bead positions
*
* @example
* ```tsx
* function MyComponent() {
* const state = useAbacusState(123)
*
* // Check if ones column has heaven bead active
* const onesHasHeaven = state[0].heavenActive
* }
* ```
*/
export function useAbacusState(
value: number | bigint,
maxPlaces: number = 5
): AbacusState {
return useMemo(() => {
return numberToAbacusState(value, maxPlaces)
}, [value, maxPlaces])
}