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

package/src/features/fluency/visual-scaffolding/components/RelationalBlock.tsx

@@ -0,0 +1,225 @@
+import React from 'react'
+import { View, StyleSheet } from 'react-native'
+import Svg, { Line, Circle, Text as SvgText } from 'react-native-svg'
+import { COLORS, FONT_FAMILY, BORDER_RADIUS, SPACING, Typography } from '@magmamath/react-native-ui'
+
+import type { NodeValue, RelationalSpec } from '../types'
+import type { VisualColors } from './visualColors'
+
+type RelationalBlockProps = {
+  spec: RelationalSpec
+  colors: VisualColors
+}
+
+// L2 — shifts focus from absolute counting to relative part-whole structures.
+export const RelationalBlock = ({ spec, colors }: RelationalBlockProps) => {
+  if (spec.model.type === 'bond') {
+    return (
+      <NumberBond
+        top={spec.model.top}
+        bottomLeft={spec.model.bottomLeft}
+        bottomRight={spec.model.bottomRight}
+        colors={colors}
+      />
+    )
+  }
+  return (
+    <AreaModel top={spec.model.top} side={spec.model.side} center={spec.model.center} colors={colors} />
+  )
+}
+
+// ── Number bond (addition / subtraction) ────────────────────────────────────
+
+const VB_W = 220
+const VB_H = 126
+const R = 28
+const NODES = {
+  top: { cx: 110, cy: 32 },
+  left: { cx: 58, cy: 94 },
+  right: { cx: 162, cy: 94 },
+}
+
+type NumberBondProps = {
+  top: NodeValue
+  bottomLeft: NodeValue
+  bottomRight: NodeValue
+  colors: VisualColors
+}
+
+const NumberBond = ({ top, bottomLeft, bottomRight, colors }: NumberBondProps) => {
+  return (
+    <View style={styles.bondWrapper}>
+      <Svg width="100%" height="100%" viewBox={`0 0 ${VB_W} ${VB_H}`} preserveAspectRatio="xMidYMid meet">
+        <Line x1={NODES.top.cx} y1={NODES.top.cy} x2={NODES.left.cx} y2={NODES.left.cy} stroke={colors.mid} strokeWidth={2.5} />
+        <Line x1={NODES.top.cx} y1={NODES.top.cy} x2={NODES.right.cx} y2={NODES.right.cy} stroke={colors.mid} strokeWidth={2.5} />
+        <BondNode pos={NODES.top} value={top} colors={colors} />
+        <BondNode pos={NODES.left} value={bottomLeft} colors={colors} />
+        <BondNode pos={NODES.right} value={bottomRight} colors={colors} />
+      </Svg>
+    </View>
+  )
+}
+
+type BondNodeProps = {
+  pos: { cx: number; cy: number }
+  value: NodeValue
+  colors: VisualColors
+}
+
+const BondNode = ({ pos, value, colors }: BondNodeProps) => {
+  const isUnknown = value === null
+  return (
+    <>
+      <Circle
+        cx={pos.cx}
+        cy={pos.cy}
+        r={R}
+        fill={isUnknown ? COLORS.NEUTRAL_1 : colors.bg}
+        stroke={colors.accent}
+        strokeWidth={2.5}
+        strokeDasharray={isUnknown ? '5 4' : undefined}
+      />
+      <SvgText
+        x={pos.cx}
+        y={pos.cy + 10}
+        fontSize={28}
+        fontWeight="700"
+        fontFamily={FONT_FAMILY.buenosAires}
+        fill={isUnknown ? colors.accent : colors.dark}
+        textAnchor="middle"
+      >
+        {isUnknown ? '?' : value}
+      </SvgText>
+    </>
+  )
+}
+
+// ── Area model (multiplication / division) ──────────────────────────────────
+
+type AreaModelProps = {
+  top: NodeValue
+  side: NodeValue
+  center: NodeValue
+  colors: VisualColors
+}
+
+// The rectangle is proportional to the factors using ONE shared unit, so the
+// shape is representative: 4×4 is square, and the larger factor always gives
+// the longer side. `unit` grows until either dimension hits its available cap,
+// so most facts fill the height-limited zone; `maxUnit` only bounds very small
+// facts (e.g. 1×1) so they don't balloon to the full box.
+const AREA = { availW: 300, availH: 52, maxUnit: 18, minDim: 18, divHeight: 44 }
+
+type Dims = { width: number; height: number }
+
+const asFactor = (value: NodeValue): number | null =>
+  typeof value === 'number' && value > 0 ? value : null
+
+const areaDims = (top: NodeValue, side: NodeValue): Dims => {
+  const a = asFactor(top)
+  const b = asFactor(side)
+
+  if (a !== null && b !== null) {
+    const unit = Math.min(AREA.availW / a, AREA.availH / b, AREA.maxUnit)
+    return { width: Math.max(AREA.minDim, a * unit), height: Math.max(AREA.minDim, b * unit) }
+  }
+  // One dimension unknown (division): scale the known side, leave a neutral height.
+  if (a !== null) {
+    const unit = Math.min(AREA.availW / a, AREA.maxUnit)
+    return { width: Math.max(AREA.minDim, a * unit), height: AREA.divHeight }
+  }
+  return { width: AREA.divHeight, height: AREA.divHeight }
+}
+
+const AreaModel = ({ top, side, center, colors }: AreaModelProps) => {
+  const { width, height } = areaDims(top, side)
+
+  // Two aligned rows with a matched side column on BOTH sides of the rect, so the
+  // rect is centered horizontally: the side label sits in the left column, an
+  // equal-width spacer balances the right. The top label box matches the rect
+  // width so it centers over the rect.
+  return (
+    <View style={styles.areaContainer}>
+      <View style={styles.areaRow}>
+        <View style={styles.sideCol} />
+        <View style={[styles.topCol, { width }]}>
+          <Dimension value={top} colors={colors} />
+        </View>
+        <View style={styles.sideCol} />
+      </View>
+      <View style={styles.areaRow}>
+        <View style={[styles.sideCol, styles.sideLabel]}>
+          <Dimension value={side} colors={colors} />
+        </View>
+        <View
+          style={[styles.rect, { width, height, borderColor: colors.accent, backgroundColor: colors.bg }]}
+        >
+          <Dimension value={center} colors={colors} large />
+        </View>
+        <View style={styles.sideCol} />
+      </View>
+    </View>
+  )
+}
+
+type DimensionProps = {
+  value: NodeValue
+  colors: VisualColors
+  large?: boolean
+}
+
+const Dimension = ({ value, colors, large = false }: DimensionProps) => {
+  const isUnknown = value === null
+  return (
+    <Typography
+      style={[styles.dimText, large && styles.dimTextLarge, { color: isUnknown ? colors.accent : colors.dark }]}
+    >
+      {isUnknown ? '?' : value}
+    </Typography>
+  )
+}
+
+const styles = StyleSheet.create({
+  bondWrapper: {
+    // Size by HEIGHT so the bond fits the short visual zone (card 260 → flex-4
+    // zone ≈104px − padding ≈88px content); width follows the viewBox ratio.
+    // Width-driven sizing overshot because the zone is wide but short.
+    height: 84,
+    aspectRatio: VB_W / VB_H,
+    alignSelf: 'center',
+  },
+  areaContainer: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: SPACING[100],
+  },
+  areaRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: SPACING[200],
+  },
+  sideCol: {
+    width: 32,
+  },
+  sideLabel: {
+    alignItems: 'flex-end',
+    justifyContent: 'center',
+  },
+  topCol: {
+    alignItems: 'center',
+  },
+  rect: {
+    borderWidth: 2,
+    borderRadius: BORDER_RADIUS[200],
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  dimText: {
+    fontSize: 17,
+    fontWeight: '700',
+    fontFamily: FONT_FAMILY.buenosAires,
+  },
+  dimTextLarge: {
+    fontSize: 24,
+  },
+})

package/src/features/fluency/visual-scaffolding/components/visualColors.ts

@@ -0,0 +1,45 @@
+import { COLORS } from '@magmamath/react-native-ui'
+import type { Operation } from '../types'
+
+/**
+ * Per-operation color set (spec §6):
+ *   accent → dots / lines / fills
+ *   bg     → the tinted visual-zone background (lightest tint)
+ *   mid    → the "second" quantity (2nd addend, dashed group outline)
+ *   dark   → small text labels (number-line tick/jump captions)
+ */
+export type VisualColors = {
+  accent: string
+  bg: string
+  mid: string
+  dark: string
+}
+
+export const VISUAL_COLORS: Record<Operation, VisualColors> = {
+  addition: {
+    accent: COLORS.PRIMARY_GREEN,
+    bg: COLORS.GREEN_1,
+    // Second addend: a darker green than the first so the tokens stay legible
+    // (GREEN_3 was too light against the frame).
+    mid: COLORS.GREEN_6,
+    dark: COLORS.GREEN_7,
+  },
+  subtraction: {
+    accent: COLORS.PRIMARY_ORANGE,
+    bg: COLORS.ORANGE_1,
+    mid: COLORS.ORANGE_3,
+    dark: COLORS.ORANGE_7,
+  },
+  multiplication: {
+    accent: COLORS.PRIMARY_BLUE,
+    bg: COLORS.BLUE_1,
+    mid: COLORS.BLUE_3,
+    dark: COLORS.BLUE_7,
+  },
+  division: {
+    accent: COLORS.PRIMARY_PURPLE,
+    bg: COLORS.PURPLE_1,
+    mid: COLORS.PURPLE_3,
+    dark: COLORS.PURPLE_7,
+  },
+}

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

@@ -0,0 +1,5 @@
+export * from './types'
+export { renderFact, hasVisual, levelForBox, TEN_FRAME_CAPACITY } from './renderFact'
+export { FactVisual } from './components/FactVisual'
+export { VISUAL_COLORS } from './components/visualColors'
+export { toFactPresentation } from './adapter'

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

@@ -0,0 +1,219 @@
+/**
+ * Pure renderer core for the Unified Math Fact Fluency Visual Engine.
+ *
+ *   box        → level            (levelForBox)
+ *   level      → component         (L1 grid, L2 relational, L3 line, L4/L5 none)
+ *   operation  → component variant + layout data
+ *
+ * Everything is derived; nothing is persisted. `renderFact` is pure so it can
+ * be snapshot-tested in isolation from React.
+ */
+import type {
+  BarSpec,
+  FactPresentation,
+  GridLayout,
+  GridSpec,
+  Level,
+  LineJump,
+  LineSpec,
+  NoVisualSpec,
+  Operation,
+  RelationalModel,
+  RelationalSpec,
+  VisualSpec,
+} from './types'
+
+export const TEN_FRAME_CAPACITY = 10
+const MINUS = '−' // U+2212
+
+/** box → level. Five boxes map one-to-one onto the five engine levels. */
+export function levelForBox(box: number): Level {
+  switch (box) {
+    case 0:
+      return 'L1'
+    case 1:
+      return 'L2'
+    case 2:
+      return 'L3'
+    case 3:
+      return 'L4'
+    default:
+      return 'L5'
+  }
+}
+
+/** Coerce to a safe non-negative integer for layout math. */
+const toCount = (n: number): number => (Number.isFinite(n) && n > 0 ? Math.floor(n) : 0)
+
+/** Multiples of ten strictly between `lo` and `hi`, ascending. */
+const tensBetween = (lo: number, hi: number): number[] => {
+  const out: number[] = []
+  for (let t = Math.floor(lo / TEN_FRAME_CAPACITY) * TEN_FRAME_CAPACITY + TEN_FRAME_CAPACITY; t < hi; t += TEN_FRAME_CAPACITY) {
+    out.push(t)
+  }
+  return out
+}
+
+/** Consecutive [from, to] pairs over a list of stops. */
+const pairs = (xs: number[]): Array<[number, number]> => xs.slice(1).map((x, i) => [xs[i], x])
+
+const uniqueAsc = (xs: number[]): number[] => [...new Set(xs)].sort((x, y) => x - y)
+
+type BaseFields = { operation: Operation; left: number; right: number; level: Level }
+
+// ── L1: DiscreteCounterGrid ─────────────────────────────────────────────────
+
+function buildGrid(operation: Operation, left: number, right: number, base: BaseFields): GridSpec {
+  const a = toCount(left)
+  const b = toCount(right)
+
+  const layout = ((): GridLayout => {
+    switch (operation) {
+      case 'addition':
+        return { type: 'tenframes', a, b, capacity: TEN_FRAME_CAPACITY }
+      case 'subtraction':
+        return {
+          type: 'tenframes_takeaway',
+          total: a,
+          removed: Math.min(b, a),
+          capacity: TEN_FRAME_CAPACITY,
+        }
+      case 'multiplication':
+        // 3×4 shown as 3 groups of 4 (first factor = number of groups), mirroring
+        // the division grouping so multiplication also reads as equal groups.
+        return { type: 'groups', groupCount: a, perGroup: b }
+      case 'division':
+        // 12 ÷ 4 → 3 clusters of 4: quotient groups, each holding the divisor.
+        return { type: 'groups', groupCount: b > 0 ? Math.floor(a / b) : 0, perGroup: b }
+    }
+  })()
+
+  return { ...base, kind: 'grid', layout }
+}
+
+// ── L2: RelationalBlock ─────────────────────────────────────────────────────
+
+function buildRelational(
+  operation: Operation,
+  left: number,
+  right: number,
+  base: BaseFields,
+): RelationalSpec {
+  const model = ((): RelationalModel => {
+    switch (operation) {
+      case 'addition':
+        // whole (sum) unknown on top; addends below.
+        return { type: 'bond', top: null, bottomLeft: left, bottomRight: right }
+      case 'subtraction':
+        // minuend whole on top; one part (the difference) unknown.
+        return { type: 'bond', top: left, bottomLeft: right, bottomRight: null }
+      case 'multiplication':
+        // both dimensions known; product (center) unknown. First factor is the
+        // number of rows (vertical side) to match the L1 array — "3×4" = 3 rows
+        // of 4, so left drives height (side), right drives width (top).
+        return { type: 'area', top: right, side: left, center: null }
+      case 'division':
+        // dividend (product) and divisor known; missing side dimension.
+        return { type: 'area', top: right, side: null, center: left }
+    }
+  })()
+
+  return { ...base, kind: 'relational', model }
+}
+
+// ── L3: DynamicNumberLine — add/sub bridge through every ten; mult skip-counts ─
+
+function buildLine(
+  operation: Exclude<Operation, 'division'>,
+  left: number,
+  right: number,
+  base: BaseFields,
+): LineSpec {
+  const a = toCount(left)
+  const b = toCount(right)
+
+  if (operation === 'addition') {
+    const sum = a + b
+    // Bridge through EVERY ten: 8 + 15 → 8→10→20→23 (make-a-ten, repeated).
+    const stops = [a, ...tensBetween(a, sum), sum]
+    const jumps: LineJump[] = pairs(stops).map(([from, to]) => ({
+      from,
+      to,
+      label: `+${to - from}`,
+    }))
+    const ticks = uniqueAsc([0, ...stops])
+    return { ...base, kind: 'line', lo: 0, hi: sum, ticks, jumps, hiddenTick: sum }
+  }
+
+  if (operation === 'subtraction') {
+    const diff = a - b
+    // Step back through every ten: 23 − 15 → 23→20→10→8.
+    const stopsDesc = [a, ...tensBetween(diff, a).reverse(), diff]
+    const jumps: LineJump[] = pairs(stopsDesc).map(([from, to]) => ({
+      from,
+      to,
+      label: `${MINUS}${from - to}`,
+    }))
+    const ticks = uniqueAsc([diff, ...tensBetween(diff, a), a])
+    return { ...base, kind: 'line', lo: diff, hi: a, ticks, jumps, hiddenTick: diff }
+  }
+
+  // multiplication: skip-count — a hops of b up to the product.
+  const total = a * b
+  const jumps: LineJump[] = Array.from({ length: a }, (_, i) => ({
+    from: i * b,
+    to: (i + 1) * b,
+    label: `+${b}`,
+  }))
+  const ticks = Array.from({ length: a + 1 }, (_, i) => i * b)
+  return { ...base, kind: 'line', lo: 0, hi: total, ticks, jumps, hiddenTick: total }
+}
+
+// ── L2 (division): QuotativeBars ─────────────────────────────────────────────
+
+// Quotative division: the dividend as a bar split into equal groups of the
+// divisor; the count of groups (quotient) is the answer the student reads off.
+function buildBars(left: number, right: number, base: BaseFields): BarSpec {
+  const total = toCount(left)
+  const segment = toCount(right)
+  const segmentCount = segment > 0 ? Math.floor(total / segment) : 0
+  return { ...base, kind: 'bars', total, segment, segmentCount }
+}
+
+function buildNone(base: BaseFields): NoVisualSpec {
+  return { ...base, kind: 'none' }
+}
+
+/**
+ * Single entry point the card calls. Returns the visual spec for the current
+ * fact at its current box. The symbolic equation is rendered separately and is
+ * always present.
+ */
+export function renderFact(p: FactPresentation): VisualSpec {
+  const level = levelForBox(p.box)
+  const base: BaseFields = { operation: p.operation, left: p.left, right: p.right, level }
+
+  switch (level) {
+    case 'L1':
+      return buildGrid(p.operation, p.left, p.right, base)
+    case 'L2':
+      // Division → concrete quotative bar; multiplication → number line
+      // (skip-count); addition/subtraction → number bond.
+      if (p.operation === 'division') return buildBars(p.left, p.right, base)
+      if (p.operation === 'multiplication') return buildLine(p.operation, p.left, p.right, base)
+      return buildRelational(p.operation, p.left, p.right, base)
+    case 'L3':
+      // Addition/subtraction → number line; multiplication/division → area model.
+      if (p.operation === 'addition' || p.operation === 'subtraction')
+        return buildLine(p.operation, p.left, p.right, base)
+      return buildRelational(p.operation, p.left, p.right, base)
+    case 'L4':
+    case 'L5':
+      return buildNone(base)
+  }
+}
+
+/** Whether the fact has any visual scaffold at its current box (false at L4/L5). */
+export function hasVisual(p: FactPresentation): boolean {
+  return renderFact(p).kind !== 'none'
+}

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

@@ -0,0 +1,108 @@
+/**
+ * Unified Math Fact Fluency Visual Engine — pure data contract.
+ *
+ * Three polymorphic components render the visual scaffold, chosen by the
+ * student's level (derived from the Leitner box). Each component mutates by
+ * operation. These types describe *what to draw* — never pixels — so the same
+ * spec drives the real RN UI and the snapshot test harness.
+ *
+ *   L1 → DiscreteCounterGrid   (discrete quantities)
+ *   L2 → RelationalBlock       (part-whole structures)
+ *   L3 → DynamicNumberLine     (forward jumps)
+ *   L4 → PureEquationText      (plain text; hint deferred)
+ *   L5 → PureEquationText      (plain text only)
+ */
+
+export type Operation = 'addition' | 'subtraction' | 'multiplication' | 'division'
+
+export type Level = 'L1' | 'L2' | 'L3' | 'L4' | 'L5'
+
+/** Operands in the ORDER presented to the student (already direction-resolved). */
+export type FactPresentation = {
+  operation: Operation
+  left: number
+  right: number
+  box: 0 | 1 | 2 | 3 | 4
+}
+
+type BaseVisualSpec = {
+  operation: Operation
+  left: number
+  right: number
+  level: Level
+}
+
+// ── L1: DiscreteCounterGrid ─────────────────────────────────────────────────
+
+/** A ten-frame token tone: first set, second set, or taken-away. */
+export type TokenTone = 'a' | 'b' | 'gone'
+
+export type GridLayout =
+  // Addition: two ten-frames, `a` tone-A tokens + `b` tone-B tokens.
+  | { type: 'tenframes'; a: number; b: number; capacity: number }
+  // Subtraction: fill `total` tokens across two ten-frames, strike the last `removed`.
+  | { type: 'tenframes_takeaway'; total: number; removed: number; capacity: number }
+  // Multiplication: a `rows` × `cols` dot array.
+  | { type: 'array'; rows: number; cols: number }
+  // Division: `groupCount` bordered clusters, each holding `perGroup` tokens.
+  | { type: 'groups'; groupCount: number; perGroup: number }
+
+export type GridSpec = BaseVisualSpec & {
+  kind: 'grid'
+  layout: GridLayout
+}
+
+// ── L2: RelationalBlock ─────────────────────────────────────────────────────
+
+/** A node/dimension value, or null for the unknown (rendered as a placeholder). */
+export type NodeValue = number | null
+
+export type RelationalModel =
+  // Number bond (add/sub): whole on top, two parts below.
+  | { type: 'bond'; top: NodeValue; bottomLeft: NodeValue; bottomRight: NodeValue }
+  // Area model (mult/div): top + left dimensions, product inside.
+  | { type: 'area'; top: NodeValue; side: NodeValue; center: NodeValue }
+
+export type RelationalSpec = BaseVisualSpec & {
+  kind: 'relational'
+  model: RelationalModel
+}
+
+// ── L3: DynamicNumberLine ───────────────────────────────────────────────────
+
+export type LineJump = {
+  from: number
+  to: number
+  label: string
+}
+
+export type LineSpec = BaseVisualSpec & {
+  kind: 'line'
+  lo: number
+  hi: number
+  ticks: number[]
+  jumps: LineJump[]
+  /** Tick value whose label is masked as "?" (the answer), or null to label all. */
+  hiddenTick: number | null
+}
+
+// ── L2 (division): QuotativeBars ─────────────────────────────────────────────
+
+/**
+ * Quotative ("measurement") division: the dividend laid out as a bar cut into
+ * equal segments of `segment` (the divisor); the student counts the segments,
+ * and that count (`segmentCount`, the quotient) is the answer.
+ */
+export type BarSpec = BaseVisualSpec & {
+  kind: 'bars'
+  total: number
+  segment: number
+  segmentCount: number
+}
+
+// ── L4 / L5: no visual ──────────────────────────────────────────────────────
+
+export type NoVisualSpec = BaseVisualSpec & { kind: 'none' }
+
+/** Discriminated union the views switch on. */
+export type VisualSpec = GridSpec | RelationalSpec | LineSpec | BarSpec | NoVisualSpec

package/src/features/fluency-teacher/assets/SortDefaultIcon.tsx

@@ -0,0 +1,10 @@
+import React from 'react'
+import Svg, { Path } from 'react-native-svg'
+import { COLORS, IconProps } from '@magmamath/react-native-ui'
+
+export const SortDefaultIcon = ({ color = COLORS.NEUTRAL_9, size = 10 }: IconProps) => (
+  <Svg width={size} height={size} viewBox="0 0 10 10" fill="none">
+    <Path d="M5 1 L8 4 H2 Z" fill={color} />
+    <Path d="M5 9 L2 6 H8 Z" fill={color} />
+  </Svg>
+)

package/src/features/fluency-teacher/components/FluencyTeacher.tsx

@@ -4,10 +4,10 @@ import { View, StyleSheet } from 'react-native'
 import { SPACING } from '@magmamath/react-native-ui'
 import { TeacherFluencyModel } from '../model/TeacherFluencyModel'
 import { FluencyTeacherStudentsTable } from './table/FluencyTeacherStudentsTable'
-import { FluencyTeacherFooter } from './FluencyTeacherFooter'
 import { FluencyTeacherFilters } from './table/FluencyTeacherFilters'
 import { FluencyTeacherHeader } from './header/FluencyTeacherHeader'
 import { FluencyTeacherDrawer } from './drawer/FluencyTeacherDrawer'
+import { FluencyTeacherFooter } from './FluencyTeacherFooter'
 import { FluencyStudent } from '../fluencyTeacher.types'
 import { TeacherFluencyProvider } from '../context/TeacherFluencyContext'
 
@@ -21,13 +21,13 @@ export const FluencyTeacher = ({ model, students, grade }: FluencyTeacherProps)
   useGate(model.gate, { students, grade })
 
   return (
-    <TeacherFluencyProvider value={{ model, grade }}>
+    <TeacherFluencyProvider value={{ model }}>
       <View style={styles.container}>
         <FluencyTeacherHeader />
         <FluencyTeacherFilters />
         <FluencyTeacherStudentsTable />
-        <FluencyTeacherFooter />
         <FluencyTeacherDrawer />
+        <FluencyTeacherFooter />
       </View>
     </TeacherFluencyProvider>
   )