@magmamath/students-features 1.8.0 → 1.8.1-rc.0

package/src/features/fluency/components/fluency-solving/components/EquationContent.tsx

@@ -53,10 +53,6 @@ export const EquationContent = ({
 }: EquationContentProps) => {
   const t = useText()
   const modePreset = useFluencySolvingPreset({ mode })
-  const labelColor = status ? STATUS_COLOR[status] : COLORS.NEUTRAL_7
-  const labelText = status
-    ? t(STATUS_LABELS[status], { answer: correctAnswer })
-    : t('student.fluency.typeYourAnswer')
   const answerAreaColor =
     status === AttemptStatus.INCORRECT ? COLORS.PRIMARY_RED : modePreset.colors.accent
 
@@ -65,9 +61,14 @@ export const EquationContent = ({
 
   return (
     <>
-      <Typography variant={HeadingVariants.H9} style={[styles.cardLabel, { color: labelColor }]}>
-        {labelText}
-      </Typography>
+      {status && (
+        <Typography
+          variant={HeadingVariants.H9}
+          style={[styles.cardLabel, { color: STATUS_COLOR[status] }]}
+        >
+          {t(STATUS_LABELS[status], { answer: correctAnswer })}
+        </Typography>
+      )}
       <View style={styles.equationRow}>
         <Typography style={styles.number}>{leftOperand}</Typography>
         <Typography style={[styles.number, { color: modePreset.colors.accent }]}>
@@ -107,7 +108,10 @@ const styles = StyleSheet.create({
     flexDirection: 'row',
     alignItems: 'center',
     gap: SPACING[300],
-    marginTop: SPACING[600],
+    // The answer input hangs ~16px below the number row; counting that here
+    // makes the row's measured box match its visual extent, so the parent
+    // centers the equation accurately at any card height (visual or mastered).
+    paddingBottom: SPACING[400],
   },
   number: {
     fontSize: 75,

package/src/features/fluency/components/fluency-solving/components/FluencyCardDeck.tsx

@@ -45,7 +45,11 @@ export const FluencyCardDeck = ({
       <Animated.View style={[styles.card, styles.cardMid, snapStyles.mid]} />
 
       <Animated.View style={[styles.card, styles.cardNear, snapStyles.near]}>
-        <FluencyEquationCard cardContent={backingCardContent} readOnly />
+        <FluencyEquationCard
+          cardContent={backingCardContent}
+          readOnly
+          showVisual={!!exitingCardContent}
+        />
       </Animated.View>
 
       {!exitingCardContent && (
@@ -92,6 +96,7 @@ const styles = StyleSheet.create({
     height: 260,
     borderRadius: BORDER_RADIUS[400],
     backgroundColor: COLORS.NEUTRAL_1,
+    overflow: 'hidden',
     ...SHADOWS[5],
   },
   cardFar: {

package/src/features/fluency/components/fluency-solving/components/FluencyEquationCard.tsx

@@ -1,6 +1,9 @@
 import React from 'react'
+import { View, StyleSheet } from 'react-native'
+import { SPACING } from '@magmamath/react-native-ui'
 
 import { EquationContent } from './EquationContent'
+import { FactVisual, renderFact, toFactPresentation, VISUAL_COLORS } from '../../../visual-scaffolding'
 import type { FluencyCardDisplayContent, SolvingFact } from '../../../shared/fluencySolving.types'
 import type { AttemptStatus, FluencyMode } from '../../../shared/fluency.constants'
 
@@ -14,6 +17,10 @@ type FluencyEquationCardProps = {
   cardContent: FluencyCardDisplayContent
   readOnly?: boolean
   status?: AttemptStatus
+  // Whether to render the visual. The deck enables it on the active card, the
+  // exiting card, and the backing card *while it steps up*, so the visual is
+  // present as fast as the equation (no pop-in after the swipe).
+  showVisual?: boolean
   onAnswerChange?: (text: string) => void
 }
 
@@ -32,20 +39,65 @@ export const FluencyEquationCard = ({
   cardContent,
   readOnly = false,
   status,
+  showVisual = true,
   onAnswerChange,
 }: FluencyEquationCardProps) => {
-  const equation = getDisplayedEquation(cardContent.fact)
+  const { fact } = cardContent
+  const equation = getDisplayedEquation(fact)
+
+  const presentation = fact && showVisual ? toFactPresentation(fact) : null
+  const spec = presentation ? renderFact(presentation) : null
+  const colors = presentation ? VISUAL_COLORS[presentation.operation] : null
+  // Narrow away the "none" variant (L4/L5 → no visual).
+  const visualSpec = spec && spec.kind !== 'none' ? spec : null
 
   return (
-    <EquationContent
-      leftOperand={equation.leftOperand}
-      rightOperand={equation.rightOperand}
-      mode={equation.mode}
-      value={cardContent.answer}
-      readOnly={readOnly}
-      status={status}
-      correctAnswer={cardContent.fact?.answer}
-      onChange={onAnswerChange}
-    />
+    <View style={styles.body}>
+      {visualSpec && colors && (
+        <View style={[styles.visualZone, { backgroundColor: colors.bg }]}>
+          <FactVisual spec={visualSpec} colors={colors} />
+        </View>
+      )}
+      <View style={styles.eqZone}>
+        <EquationContent
+          leftOperand={equation.leftOperand}
+          rightOperand={equation.rightOperand}
+          mode={equation.mode}
+          value={cardContent.answer}
+          readOnly={readOnly}
+          status={status}
+          correctAnswer={fact?.answer}
+          onChange={onAnswerChange}
+        />
+      </View>
+    </View>
   )
 }
+
+const styles = StyleSheet.create({
+  body: {
+    flex: 1,
+    alignSelf: 'stretch',
+  },
+  // Tinted top zone (background set per operation), ~40% of the card height.
+  // Clips oversized visuals so the fixed-size card never grows.
+  visualZone: {
+    flex: 4,
+    alignSelf: 'stretch',
+    alignItems: 'center',
+    justifyContent: 'center',
+    overflow: 'hidden',
+    paddingVertical: SPACING[200],
+    paddingHorizontal: SPACING[400],
+  },
+  // White equation zone, ~60% of the card height. The equation is centered so
+  // it keeps whitespace above and below (and clears the negative-margin answer
+  // input under the card's overflow:hidden clip).
+  eqZone: {
+    flex: 6,
+    alignSelf: 'stretch',
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingHorizontal: SPACING[400],
+  },
+})

package/src/features/fluency/components/fluency-solving/components/FluencySolvingHeader.tsx

@@ -13,6 +13,7 @@ import {
   Typography,
 } from '@magmamath/react-native-ui'
 import { useFluencySolvingPreset } from '../../../hooks/useFluencySolvingPreset'
+import { FluencySolvingProgress } from './FluencySolvingProgress'
 import { XCloseIcon } from '../../../../../shared/icons/XCloseIcon'
 
 type FluencySolvingHeaderProps = {
@@ -39,6 +40,9 @@ export const FluencySolvingHeader = ({ onClosePress }: FluencySolvingHeaderProps
       <Typography variant={HeadingVariants.H4} style={styles.title}>
         {modePreset.label}
       </Typography>
+      <View style={styles.progress} pointerEvents="none">
+        <FluencySolvingProgress />
+      </View>
     </View>
   )
 }
@@ -54,6 +58,11 @@ const styles = StyleSheet.create({
     backgroundColor: COLORS.NEUTRAL_1,
     ...SHADOWS[1],
   },
+  progress: {
+    ...StyleSheet.absoluteFillObject,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
   operatorBadge: {
     width: 32,
     height: 32,

package/src/features/fluency/components/fluency-solving/components/FluencySolvingProgress.tsx

@@ -50,8 +50,6 @@ const styles = StyleSheet.create({
   container: {
     flexDirection: 'row',
     gap: SPACING[500],
-    paddingHorizontal: SPACING[600],
-    paddingVertical: 14,
     justifyContent: 'center',
     alignItems: 'center',
   },

package/src/features/fluency/index.ts

@@ -1,6 +1,7 @@
 export * from './shared/fluency.constants'
 export * from './shared/fluency.types'
 export * from './shared/fluency.helpers'
+export * from './visual-scaffolding'
 export { Fluency } from './components/Fluency'
 export { FluencySolving } from './components/FluencySolving'
 export { FluencyModel } from './model/FluencyModel'

package/src/features/fluency/visual-scaffolding/__tests__/__snapshots__/renderFact.test.ts.snap

@@ -0,0 +1,64 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`L1 — DiscreteCounterGrid (box 0) addition 6 + 9 → two ten-frames, a tone-A + b tone-B 1`] = `
+{
+  "kind": "grid",
+  "layout": {
+    "a": 6,
+    "b": 9,
+    "capacity": 10,
+    "type": "tenframes",
+  },
+  "left": 6,
+  "level": "L1",
+  "operation": "addition",
+  "right": 9,
+}
+`;
+
+exports[`L2 — RelationalBlock (box 1) addition → bond with empty sum (top) node 1`] = `
+{
+  "kind": "relational",
+  "left": 6,
+  "level": "L2",
+  "model": {
+    "bottomLeft": 6,
+    "bottomRight": 9,
+    "top": null,
+    "type": "bond",
+  },
+  "operation": "addition",
+  "right": 9,
+}
+`;
+
+exports[`L3 — DynamicNumberLine (box 2) addition 7 + 6 → bridges 10 (7→10→13), end tick hidden 1`] = `
+{
+  "hi": 13,
+  "hiddenTick": 13,
+  "jumps": [
+    {
+      "from": 7,
+      "label": "+3",
+      "to": 10,
+    },
+    {
+      "from": 10,
+      "label": "+3",
+      "to": 13,
+    },
+  ],
+  "kind": "line",
+  "left": 7,
+  "level": "L3",
+  "lo": 0,
+  "operation": "addition",
+  "right": 6,
+  "ticks": [
+    0,
+    7,
+    10,
+    13,
+  ],
+}
+`;

package/src/features/fluency/visual-scaffolding/__tests__/renderFact.test.ts

@@ -0,0 +1,192 @@
+import { renderFact, levelForBox, hasVisual } from '../renderFact'
+import type { FactPresentation } from '../types'
+
+describe('levelForBox', () => {
+  it.each([
+    [0, 'L1'],
+    [1, 'L2'],
+    [2, 'L3'],
+    [3, 'L4'],
+    [4, 'L5'],
+  ] as const)('box %i → %s', (box, level) => {
+    expect(levelForBox(box)).toBe(level)
+  })
+})
+
+const fact = (
+  p: Partial<FactPresentation> & Pick<FactPresentation, 'operation'>,
+): FactPresentation => ({ left: 0, right: 0, box: 0, ...p })
+
+describe('L1 — DiscreteCounterGrid (box 0)', () => {
+  it('addition 6 + 9 → two ten-frames, a tone-A + b tone-B', () => {
+    const spec = renderFact(fact({ operation: 'addition', left: 6, right: 9, box: 0 }))
+    expect(spec).toMatchSnapshot()
+    if (spec.kind !== 'grid' || spec.layout.type !== 'tenframes') throw new Error('expected tenframes')
+    expect(spec.layout.a).toBe(6)
+    expect(spec.layout.b).toBe(9)
+    expect(spec.layout.capacity).toBe(10)
+  })
+
+  it('subtraction 15 − 9 → fill 15, strike last 9', () => {
+    const spec = renderFact(fact({ operation: 'subtraction', left: 15, right: 9, box: 0 }))
+    if (spec.kind !== 'grid' || spec.layout.type !== 'tenframes_takeaway') throw new Error('bad')
+    expect(spec.layout.total).toBe(15)
+    expect(spec.layout.removed).toBe(9)
+  })
+
+  it('multiplication 3 × 4 → 3 groups of 4', () => {
+    const spec = renderFact(fact({ operation: 'multiplication', left: 3, right: 4, box: 0 }))
+    if (spec.kind !== 'grid' || spec.layout.type !== 'groups') throw new Error('expected groups')
+    expect(spec.layout.groupCount).toBe(3)
+    expect(spec.layout.perGroup).toBe(4)
+  })
+
+  it('division 12 ÷ 4 → 3 clusters of 4', () => {
+    const spec = renderFact(fact({ operation: 'division', left: 12, right: 4, box: 0 }))
+    if (spec.kind !== 'grid' || spec.layout.type !== 'groups') throw new Error('expected groups')
+    expect(spec.layout.groupCount).toBe(3)
+    expect(spec.layout.perGroup).toBe(4)
+  })
+})
+
+describe('L2 — RelationalBlock (box 1)', () => {
+  it('addition → bond with empty sum (top) node', () => {
+    const spec = renderFact(fact({ operation: 'addition', left: 6, right: 9, box: 1 }))
+    expect(spec).toMatchSnapshot()
+    if (spec.kind !== 'relational' || spec.model.type !== 'bond') throw new Error('expected bond')
+    expect(spec.model.top).toBeNull()
+    expect(spec.model.bottomLeft).toBe(6)
+    expect(spec.model.bottomRight).toBe(9)
+  })
+
+  it('subtraction → bond with empty part (bottom-right) node', () => {
+    const spec = renderFact(fact({ operation: 'subtraction', left: 15, right: 9, box: 1 }))
+    if (spec.kind !== 'relational' || spec.model.type !== 'bond') throw new Error('expected bond')
+    expect(spec.model.top).toBe(15)
+    expect(spec.model.bottomLeft).toBe(9)
+    expect(spec.model.bottomRight).toBeNull()
+  })
+
+  it('multiplication (box 1) → number line: three +4 hops, end hidden', () => {
+    const spec = renderFact(fact({ operation: 'multiplication', left: 3, right: 4, box: 1 }))
+    if (spec.kind !== 'line') throw new Error('expected line')
+    expect(spec.jumps.map((j) => j.to)).toEqual([4, 8, 12])
+    expect(spec.ticks).toEqual([0, 4, 8, 12])
+    expect(spec.hiddenTick).toBe(12)
+  })
+
+  it('division (box 1) → quotative bars: 3 groups of 4 spanning 12', () => {
+    const spec = renderFact(fact({ operation: 'division', left: 12, right: 4, box: 1 }))
+    if (spec.kind !== 'bars') throw new Error('expected bars')
+    expect(spec.total).toBe(12)
+    expect(spec.segment).toBe(4)
+    expect(spec.segmentCount).toBe(3)
+  })
+})
+
+describe('L3 — DynamicNumberLine (box 2)', () => {
+  it('addition 7 + 6 → bridges 10 (7→10→13), end tick hidden', () => {
+    const spec = renderFact(fact({ operation: 'addition', left: 7, right: 6, box: 2 }))
+    expect(spec).toMatchSnapshot()
+    if (spec.kind !== 'line') throw new Error('expected line')
+    expect(spec.jumps).toEqual([
+      { from: 7, to: 10, label: '+3' },
+      { from: 10, to: 13, label: '+3' },
+    ])
+    expect(spec.ticks).toEqual([0, 7, 10, 13])
+    expect(spec.hiddenTick).toBe(13)
+  })
+
+  it('addition 4 + 3 → single jump, no bridge', () => {
+    const spec = renderFact(fact({ operation: 'addition', left: 4, right: 3, box: 2 }))
+    if (spec.kind !== 'line') throw new Error('expected line')
+    expect(spec.jumps).toEqual([{ from: 4, to: 7, label: '+3' }])
+    expect(spec.ticks).toEqual([0, 4, 7])
+  })
+
+  it('subtraction 13 − 5 → backward, bridges 10 (13→10→8)', () => {
+    const spec = renderFact(fact({ operation: 'subtraction', left: 13, right: 5, box: 2 }))
+    if (spec.kind !== 'line') throw new Error('expected line')
+    expect(spec.jumps).toEqual([
+      { from: 13, to: 10, label: '−3' },
+      { from: 10, to: 8, label: '−2' },
+    ])
+    expect(spec.lo).toBe(8)
+    expect(spec.hi).toBe(13)
+    expect(spec.hiddenTick).toBe(8)
+  })
+
+  it('addition 8 + 15 → bridges every ten (8→10→20→23)', () => {
+    const spec = renderFact(fact({ operation: 'addition', left: 8, right: 15, box: 2 }))
+    if (spec.kind !== 'line') throw new Error('expected line')
+    expect(spec.jumps).toEqual([
+      { from: 8, to: 10, label: '+2' },
+      { from: 10, to: 20, label: '+10' },
+      { from: 20, to: 23, label: '+3' },
+    ])
+    expect(spec.ticks).toEqual([0, 8, 10, 20, 23])
+    expect(spec.hiddenTick).toBe(23)
+  })
+
+  it('subtraction 23 − 15 → steps back through every ten (23→20→10→8)', () => {
+    const spec = renderFact(fact({ operation: 'subtraction', left: 23, right: 15, box: 2 }))
+    if (spec.kind !== 'line') throw new Error('expected line')
+    expect(spec.jumps).toEqual([
+      { from: 23, to: 20, label: '−3' },
+      { from: 20, to: 10, label: '−10' },
+      { from: 10, to: 8, label: '−2' },
+    ])
+    expect(spec.ticks).toEqual([8, 10, 20, 23])
+    expect(spec.hiddenTick).toBe(8)
+  })
+
+  it('multiplication (box 2) → area model with empty center (first factor = vertical side)', () => {
+    const spec = renderFact(fact({ operation: 'multiplication', left: 3, right: 4, box: 2 }))
+    if (spec.kind !== 'relational' || spec.model.type !== 'area') throw new Error('expected area')
+    // "3×4" = 3 rows of 4: left (3) → height (side), right (4) → width (top).
+    expect(spec.model.top).toBe(4)
+    expect(spec.model.side).toBe(3)
+    expect(spec.model.center).toBeNull()
+  })
+
+  it('division (box 2) → area model with empty side, dividend in center', () => {
+    const spec = renderFact(fact({ operation: 'division', left: 12, right: 4, box: 2 }))
+    if (spec.kind !== 'relational' || spec.model.type !== 'area') throw new Error('expected area')
+    expect(spec.model.top).toBe(4)
+    expect(spec.model.side).toBeNull()
+    expect(spec.model.center).toBe(12)
+  })
+})
+
+describe('L4 / L5 — no visual', () => {
+  it.each([3, 4] as const)('box %i → none', (box) => {
+    const spec = renderFact(fact({ operation: 'multiplication', left: 7, right: 8, box }))
+    expect(spec.kind).toBe('none')
+    expect(hasVisual(fact({ operation: 'multiplication', left: 7, right: 8, box }))).toBe(false)
+  })
+})
+
+describe('orientation matches the prompt', () => {
+  it('3×4 ≠ 4×3 as L1 groups (first factor = number of groups)', () => {
+    const a = renderFact(fact({ operation: 'multiplication', left: 3, right: 4, box: 0 }))
+    const b = renderFact(fact({ operation: 'multiplication', left: 4, right: 3, box: 0 }))
+    if (a.kind !== 'grid' || a.layout.type !== 'groups') throw new Error('bad')
+    if (b.kind !== 'grid' || b.layout.type !== 'groups') throw new Error('bad')
+    expect([a.layout.groupCount, a.layout.perGroup]).toEqual([3, 4])
+    expect([b.layout.groupCount, b.layout.perGroup]).toEqual([4, 3])
+  })
+})
+
+describe('defensive guards', () => {
+  it('subtracting more than the minuend clamps removed', () => {
+    const spec = renderFact(fact({ operation: 'subtraction', left: 3, right: 9, box: 0 }))
+    if (spec.kind !== 'grid' || spec.layout.type !== 'tenframes_takeaway') throw new Error('bad')
+    expect(spec.layout.removed).toBe(3)
+  })
+
+  it('division by zero does not throw', () => {
+    const spec = renderFact(fact({ operation: 'division', left: 8, right: 0, box: 0 }))
+    if (spec.kind !== 'grid' || spec.layout.type !== 'groups') throw new Error('bad')
+    expect(spec.layout.groupCount).toBe(0)
+  })
+})

package/src/features/fluency/visual-scaffolding/adapter.ts

@@ -0,0 +1,33 @@
+/**
+ * Adapts the fluency model's `SolvingFact` (the shape held in
+ * `FluencyModel.solving.$current`) to the pure `FactPresentation` contract.
+ *
+ * The picker has already resolved the presented direction, so `numbers` is in
+ * prompt order: numbers[0] = left, numbers[1] = right. `mode` is the operation
+ * (its enum values match `Operation` exactly), and `box` is the Leitner box.
+ */
+import { FluencyMode } from '../shared/fluency.constants'
+import type { SolvingFact } from '../shared/fluencySolving.types'
+import type { FactPresentation, Operation } from './types'
+
+const MODE_TO_OPERATION: Record<FluencyMode, Operation> = {
+  [FluencyMode.ADDITION]: 'addition',
+  [FluencyMode.SUBTRACTION]: 'subtraction',
+  [FluencyMode.MULTIPLICATION]: 'multiplication',
+  [FluencyMode.DIVISION]: 'division',
+}
+
+const clampBox = (box: number): FactPresentation['box'] => {
+  const clamped = Math.max(0, Math.min(4, Math.round(box)))
+  return clamped as FactPresentation['box']
+}
+
+export function toFactPresentation(fact: SolvingFact): FactPresentation {
+  const [left, right] = fact.numbers
+  return {
+    operation: MODE_TO_OPERATION[fact.mode],
+    left,
+    right,
+    box: clampBox(fact.box),
+  }
+}