antialias/soroban-abacus-flashcards
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: extract screen pixel ratio calculations to utility module (Phase 1)

Browse Source 
Extract duplicated screen pixel ratio calculations into reusable utility
functions. This is Phase 1 of the magnifier zoom refactoring.

Changes:
- Created utils/screenPixelRatio.ts with pure functions:
  - calculateScreenPixelRatio(): Calculate ratio from zoom context
  - isAboveThreshold(): Check if ratio exceeds threshold
  - calculateMaxZoomAtThreshold(): Calculate max zoom for capping
  - createZoomContext(): Helper to build context from DOM elements

- Replaced 5 duplicated calculations in MapRenderer.tsx:
  1. Pointer lock release zoom capping (line ~290)
  2. Current zoom threshold check in pause/resume effect (line ~493)
  3. Target zoom threshold check in pause/resume effect (line ~517)
  4. Zoom capping in handleMouseMove (line ~1581)
  5. Magnifier filter visual effect check (line ~2112)

- Also changed isNaN() to Number.isNaN() (best practice)

Benefits:
- Eliminates code duplication (5 instances → 1 utility)
- Adds comprehensive documentation of the formula
- Pure functions are easily testable
- Reduces MapRenderer.tsx complexity
- No behavior changes - purely structural refactor

Next Phase: Continue replacing remaining occurrences and extract more
zoom-related utilities.

🤖 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-24 05:47:04 -06:00
parent 3934cc2716
commit efb39b013c
2 changed files with 180 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
apps/web/src/arcade-games/know-your-world/components/MapRenderer.tsx
View File

@@ -15,6 +15,12 @@ import {
import { forceSimulation, forceCollide, forceX, forceY, type SimulationNodeDatum } from 'd3-force'
import { WORLD_MAP, USA_MAP, filterRegionsByContinent } from '../maps'
import type { ContinentId } from '../continents'
import {
calculateScreenPixelRatio,
calculateMaxZoomAtThreshold,
isAboveThreshold,
createZoomContext,
} from '../utils/screenPixelRatio'
// Debug flag: show technical info in magnifier (dev only)
const SHOW_MAGNIFIER_DEBUG_INFO = process.env.NODE_ENV === 'development'
@@ -278,24 +284,30 @@ export function MapRenderer({
svgWidth: svgRect.width.toFixed(1),
})
if (viewBoxWidth && !isNaN(viewBoxWidth)) {
if (viewBoxWidth && !Number.isNaN(viewBoxWidth)) {
// Calculate what the screen pixel ratio would be at the uncapped zoom
const uncappedZoom = uncappedAdaptiveZoomRef.current
const magnifiedViewBoxWidth = viewBoxWidth / uncappedZoom
const magnifierScreenPixelsPerSvgUnit = magnifierWidth / magnifiedViewBoxWidth
const mainMapSvgUnitsPerScreenPixel = viewBoxWidth / svgRect.width
const screenPixelRatio = mainMapSvgUnitsPerScreenPixel * magnifierScreenPixelsPerSvgUnit
const screenPixelRatio = calculateScreenPixelRatio({
magnifierWidth,
viewBoxWidth,
svgWidth: svgRect.width,
zoom: uncappedZoom,
})
console.log('[Pointer Lock] Screen pixel ratio check:', {
uncappedZoom: uncappedZoom.toFixed(1),
screenPixelRatio: screenPixelRatio.toFixed(1),
threshold: PRECISION_MODE_THRESHOLD,
exceedsThreshold: screenPixelRatio > PRECISION_MODE_THRESHOLD,
exceedsThreshold: isAboveThreshold(screenPixelRatio, PRECISION_MODE_THRESHOLD),
})
// If it exceeds threshold, cap the zoom to stay at threshold
if (screenPixelRatio > PRECISION_MODE_THRESHOLD) {
const maxZoom = PRECISION_MODE_THRESHOLD / (magnifierWidth / svgRect.width)
if (isAboveThreshold(screenPixelRatio, PRECISION_MODE_THRESHOLD)) {
const maxZoom = calculateMaxZoomAtThreshold(
PRECISION_MODE_THRESHOLD,
magnifierWidth,
svgRect.width
)
const cappedZoom = Math.min(uncappedZoom, maxZoom)
console.log(
`[Pointer Lock] ✅ Capping zoom: ${uncappedZoom.toFixed(1)}× → ${cappedZoom.toFixed(1)}× (threshold: ${PRECISION_MODE_THRESHOLD} px/px)`
@@ -476,14 +488,16 @@ export function MapRenderer({
const viewBoxParts = mapData.viewBox.split(' ').map(Number)
const viewBoxWidth = viewBoxParts[2]
if (!viewBoxWidth || isNaN(viewBoxWidth)) return false
if (!viewBoxWidth || Number.isNaN(viewBoxWidth)) return false
const magnifiedViewBoxWidth = viewBoxWidth / currentZoom
const magnifierScreenPixelsPerSvgUnit = magnifierWidth / magnifiedViewBoxWidth
const mainMapSvgUnitsPerScreenPixel = viewBoxWidth / svgRect.width
const screenPixelRatio = mainMapSvgUnitsPerScreenPixel * magnifierScreenPixelsPerSvgUnit
const screenPixelRatio = calculateScreenPixelRatio({
magnifierWidth,
viewBoxWidth,
svgWidth: svgRect.width,
zoom: currentZoom,
})
return screenPixelRatio >= PRECISION_MODE_THRESHOLD
return isAboveThreshold(screenPixelRatio, PRECISION_MODE_THRESHOLD)
})()
// Check if TARGET zoom would be at/above the threshold
@@ -498,14 +512,16 @@ export function MapRenderer({
const viewBoxParts = mapData.viewBox.split(' ').map(Number)
const viewBoxWidth = viewBoxParts[2]
if (!viewBoxWidth || isNaN(viewBoxWidth)) return false
if (!viewBoxWidth || Number.isNaN(viewBoxWidth)) return false
const magnifiedViewBoxWidth = viewBoxWidth / targetZoom
const magnifierScreenPixelsPerSvgUnit = magnifierWidth / magnifiedViewBoxWidth
const mainMapSvgUnitsPerScreenPixel = viewBoxWidth / svgRect.width
const screenPixelRatio = mainMapSvgUnitsPerScreenPixel * magnifierScreenPixelsPerSvgUnit
const screenPixelRatio = calculateScreenPixelRatio({
magnifierWidth,
viewBoxWidth,
svgWidth: svgRect.width,
zoom: targetZoom,
})
return screenPixelRatio >= PRECISION_MODE_THRESHOLD
return isAboveThreshold(screenPixelRatio, PRECISION_MODE_THRESHOLD)
})()
console.log('[Zoom Effect] Threshold checks:', {
@@ -1560,17 +1576,22 @@ export function MapRenderer({
const viewBoxParts = mapData.viewBox.split(' ').map(Number)
const viewBoxWidth = viewBoxParts[2]
if (viewBoxWidth && !isNaN(viewBoxWidth)) {
if (viewBoxWidth && !Number.isNaN(viewBoxWidth)) {
// Calculate what the screen pixel ratio would be at this zoom
const magnifiedViewBoxWidth = viewBoxWidth / adaptiveZoom
const magnifierScreenPixelsPerSvgUnit = magnifierWidth / magnifiedViewBoxWidth
const mainMapSvgUnitsPerScreenPixel = viewBoxWidth / svgRect.width
const screenPixelRatio = mainMapSvgUnitsPerScreenPixel * magnifierScreenPixelsPerSvgUnit
const screenPixelRatio = calculateScreenPixelRatio({
magnifierWidth,
viewBoxWidth,
svgWidth: svgRect.width,
zoom: adaptiveZoom,
})
// If it exceeds threshold, cap the zoom to stay at threshold
if (screenPixelRatio > PRECISION_MODE_THRESHOLD) {
// Solve for max zoom: ratio = zoom * (magnifierWidth / mainMapWidth)
const maxZoom = PRECISION_MODE_THRESHOLD / (magnifierWidth / svgRect.width)
if (isAboveThreshold(screenPixelRatio, PRECISION_MODE_THRESHOLD)) {
const maxZoom = calculateMaxZoomAtThreshold(
PRECISION_MODE_THRESHOLD,
magnifierWidth,
svgRect.width
)
adaptiveZoom = Math.min(adaptiveZoom, maxZoom)
console.log(
`[Magnifier] Capping zoom at ${adaptiveZoom.toFixed(1)}× (threshold: ${PRECISION_MODE_THRESHOLD} px/px, would have been ${screenPixelRatio.toFixed(1)} px/px)`
@@ -2085,17 +2106,18 @@ export function MapRenderer({
const magnifierWidth = containerRect.width * 0.5
const viewBoxParts = mapData.viewBox.split(' ').map(Number)
const viewBoxWidth = viewBoxParts[2]
if (!viewBoxWidth || isNaN(viewBoxWidth)) return 'none'
if (!viewBoxWidth || Number.isNaN(viewBoxWidth)) return 'none'
const currentZoom = magnifierSpring.zoom.get()
const magnifiedViewBoxWidth = viewBoxWidth / currentZoom
const magnifierScreenPixelsPerSvgUnit = magnifierWidth / magnifiedViewBoxWidth
const mainMapSvgUnitsPerScreenPixel = viewBoxWidth / svgRect.width
const screenPixelRatio =
mainMapSvgUnitsPerScreenPixel * magnifierScreenPixelsPerSvgUnit
const screenPixelRatio = calculateScreenPixelRatio({
magnifierWidth,
viewBoxWidth,
svgWidth: svgRect.width,
zoom: currentZoom,
})
// When at or above threshold (but not in precision mode), add disabled effect
if (screenPixelRatio >= PRECISION_MODE_THRESHOLD) {
if (isAboveThreshold(screenPixelRatio, PRECISION_MODE_THRESHOLD)) {
return 'brightness(0.6) saturate(0.5)'
}

123
apps/web/src/arcade-games/know-your-world/utils/screenPixelRatio.ts Normal file
View File

@@ -0,0 +1,123 @@
/**
* Screen Pixel Ratio Calculations
*
* This module contains pure functions for calculating the screen pixel ratio
* in the magnifier. The screen pixel ratio represents how many screen pixels
* the magnifier "jumps" when the mouse moves one pixel on the main map.
*
* A high ratio (e.g., 50) means precision mode is recommended.
*/
export interface ZoomContext {
/** Width of the magnifier in screen pixels */
magnifierWidth: number
/** Width of the SVG viewBox */
viewBoxWidth: number
/** Width of the SVG element in screen pixels */
svgWidth: number
/** Current zoom level */
zoom: number
}
/**
* Calculate the screen pixel ratio for the magnifier.
*
* This ratio represents how many screen pixels the magnifier "jumps over"
* when the mouse moves one pixel on the main map.
*
* Formula:
* 1. magnifiedViewBoxWidth = viewBoxWidth / zoom
* (How much of the viewBox is visible in the magnifier)
*
* 2. magnifierScreenPixelsPerSvgUnit = magnifierWidth / magnifiedViewBoxWidth
* (How many screen pixels per SVG unit in the magnifier)
*
* 3. mainMapSvgUnitsPerScreenPixel = viewBoxWidth / svgWidth
* (How many SVG units the mouse moves per screen pixel on main map)
*
* 4. screenPixelRatio = mainMapSvgUnitsPerScreenPixel * magnifierScreenPixelsPerSvgUnit
* (How many screen pixels the magnifier jumps per main map screen pixel)
*
* @param context - The zoom context containing dimensions and zoom level
* @returns The screen pixel ratio
*/
export function calculateScreenPixelRatio(context: ZoomContext): number {
const { magnifierWidth, viewBoxWidth, svgWidth, zoom } = context
// Step 1: How much of the viewBox is visible in the magnifier at this zoom
const magnifiedViewBoxWidth = viewBoxWidth / zoom
// Step 2: Screen pixels per SVG unit in the magnifier
const magnifierScreenPixelsPerSvgUnit = magnifierWidth / magnifiedViewBoxWidth
// Step 3: SVG units per screen pixel on the main map
const mainMapSvgUnitsPerScreenPixel = viewBoxWidth / svgWidth
// Step 4: Screen pixels the magnifier jumps per main map screen pixel
return mainMapSvgUnitsPerScreenPixel * magnifierScreenPixelsPerSvgUnit
}
/**
* Check if the screen pixel ratio is at or above a threshold.
*
* @param ratio - The screen pixel ratio to check
* @param threshold - The threshold value
* @returns True if ratio >= threshold
*/
export function isAboveThreshold(ratio: number, threshold: number): boolean {
return ratio >= threshold
}
/**
* Calculate the maximum zoom level that keeps the screen pixel ratio at the threshold.
*
* This is used for capping zoom when not in precision mode.
*
* Formula:
* screenPixelRatio = zoom × (magnifierWidth / svgWidth)
* Therefore:
* maxZoom = threshold / (magnifierWidth / svgWidth)
*
* @param threshold - The precision mode threshold
* @param magnifierWidth - Width of the magnifier in screen pixels
* @param svgWidth - Width of the SVG element in screen pixels
* @returns The maximum zoom level at the threshold
*/
export function calculateMaxZoomAtThreshold(
threshold: number,
magnifierWidth: number,
svgWidth: number
): number {
return threshold / (magnifierWidth / svgWidth)
}
/**
* Create a ZoomContext from DOM elements.
*
* @param containerElement - The container element
* @param svgElement - The SVG element
* @param viewBoxWidth - The SVG viewBox width
* @param zoom - The zoom level
* @returns A ZoomContext object, or null if elements are missing
*/
export function createZoomContext(
containerElement: HTMLElement | null,
svgElement: SVGSVGElement | null,
viewBoxWidth: number,
zoom: number
): ZoomContext | null {
if (!containerElement || !svgElement) {
return null
}
const containerRect = containerElement.getBoundingClientRect()
const svgRect = svgElement.getBoundingClientRect()
const magnifierWidth = containerRect.width * 0.5
return {
magnifierWidth,
viewBoxWidth,
svgWidth: svgRect.width,
zoom,
}
}