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

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

@@ -0,0 +1,222 @@
+import React, { useState } from 'react'
+import { View, StyleSheet, type LayoutChangeEvent } from 'react-native'
+import { COLORS, SPACING, BORDER_RADIUS } from '@magmamath/react-native-ui'
+
+import { Dot } from './Dot'
+import type { GridSpec, TokenTone } from '../types'
+import type { VisualColors } from './visualColors'
+
+const CELL_SIZE = 24
+const CELL_GAP = 4
+const FRAME_COLUMNS = 5
+const TOKEN_SIZE = 14
+const GROUP_COLUMNS = 5
+const GROUP_PADDING = SPACING[200]
+const GROUP_BORDER = 2
+// Wide enough to fit GROUP_COLUMNS dots per row (incl. padding + border, border-box),
+// so a group of five fills one row like the ten-frame instead of wrapping at four.
+const GROUP_MAX_WIDTH = GROUP_COLUMNS * (TOKEN_SIZE + CELL_GAP) + 2 * GROUP_PADDING + 2 * GROUP_BORDER
+// Max groups per row; groups are split into balanced rows (10 → 5+5, 20 → 5×4).
+const GROUPS_PER_ROW_MAX = 5
+
+// Budget the grid is allowed to occupy in the visual zone; bigger facts (e.g.
+// 9 × 9 → many groups) are scaled down uniformly to fit rather than overflowing.
+const FIT_W = 500
+const FIT_H = 92
+
+type Size = { width: number; height: number }
+
+type DiscreteCounterGridProps = {
+  spec: GridSpec
+  colors: VisualColors
+}
+
+// L1 — renders absolute, discrete quantities to build a conceptual baseline.
+export const DiscreteCounterGrid = ({ spec, colors }: DiscreteCounterGridProps) => {
+  const { layout } = spec
+  const [size, setSize] = useState<Size | null>(null)
+
+  const measure = (event: LayoutChangeEvent) => {
+    const { width, height } = event.nativeEvent.layout
+    setSize((prev) => (prev?.width === width && prev?.height === height ? prev : { width, height }))
+  }
+
+  // Shrink only when the natural size exceeds the budget; otherwise render 1:1.
+  const scale =
+    size && size.width > 0 && size.height > 0
+      ? Math.min(1, FIT_W / size.width, FIT_H / size.height)
+      : 1
+
+  const content = ((): React.ReactNode => {
+    switch (layout.type) {
+      case 'tenframes': {
+      // Pour `a` tone-A tokens then `b` tone-B tokens into the frame, filling it
+      // up; a second frame appears only once the sum spills past ten.
+      const total = layout.a + layout.b
+      const frameCount = total > layout.capacity ? 2 : 1
+      const cells = Array.from(
+        { length: layout.capacity * frameCount },
+        (_, i): TokenTone | null => {
+          if (i < layout.a) return 'a'
+          if (i < total) return 'b'
+          return null
+        },
+      )
+      return (
+        <View style={styles.frameRow}>
+          {Array.from({ length: frameCount }, (_, f) => (
+            <TenFrame
+              key={f}
+              tones={cells.slice(f * layout.capacity, (f + 1) * layout.capacity)}
+              colors={colors}
+            />
+          ))}
+        </View>
+      )
+    }
+    case 'tenframes_takeaway': {
+      // Fill `total` tokens (striking the last `removed`); a second frame shows
+      // only when the minuend spills past ten, matching the addition frames.
+      const frameCount = layout.total > layout.capacity ? 2 : 1
+      const cells = Array.from(
+        { length: layout.capacity * frameCount },
+        (_, i): TokenTone | null => {
+          if (i >= layout.total) return null
+          return i >= layout.total - layout.removed ? 'gone' : 'a'
+        },
+      )
+      return (
+        <View style={styles.frameRow}>
+          {Array.from({ length: frameCount }, (_, f) => (
+            <TenFrame
+              key={f}
+              tones={cells.slice(f * layout.capacity, (f + 1) * layout.capacity)}
+              colors={colors}
+            />
+          ))}
+        </View>
+      )
+    }
+    case 'array':
+      return (
+        <View style={styles.array}>
+          {Array.from({ length: layout.rows }, (_, r) => (
+            <View key={r} style={styles.arrayRow}>
+              {Array.from({ length: layout.cols }, (_, c) => (
+                <Dot key={c} color={colors.accent} size={TOKEN_SIZE} />
+              ))}
+            </View>
+          ))}
+        </View>
+      )
+    case 'groups': {
+      const rowCount = Math.max(1, Math.ceil(layout.groupCount / GROUPS_PER_ROW_MAX))
+      const perRow = Math.ceil(layout.groupCount / rowCount)
+      return (
+        <View style={styles.groupGrid}>
+          {Array.from({ length: rowCount }, (_, r) => (
+            <View key={r} style={styles.groupRow}>
+              {Array.from({ length: Math.min(perRow, layout.groupCount - r * perRow) }, (_, g) => (
+                <View key={g} style={[styles.group, { borderColor: colors.mid }]}>
+                  {Array.from({ length: layout.perGroup }, (_, d) => (
+                    <Dot key={d} color={colors.accent} size={TOKEN_SIZE} />
+                  ))}
+                </View>
+              ))}
+            </View>
+          ))}
+        </View>
+      )
+    }
+    }
+  })()
+
+  return (
+    <View onLayout={measure} style={[styles.fit, { transform: [{ scale }] }]}>
+      {content}
+    </View>
+  )
+}
+
+type TenFrameProps = {
+  tones: Array<TokenTone | null>
+  colors: VisualColors
+}
+
+const TONE_COLOR = (tone: Exclude<TokenTone, 'gone'>, colors: VisualColors): string =>
+  tone === 'a' ? colors.accent : colors.mid
+
+const TenFrame = ({ tones, colors }: TenFrameProps) => {
+  return (
+    <View style={styles.frame}>
+      {tones.map((tone, i) => (
+        <View key={i} style={styles.cell}>
+          {tone === 'gone' && <Dot color={colors.accent} strike size={TOKEN_SIZE} />}
+          {(tone === 'a' || tone === 'b') && (
+            <Dot color={TONE_COLOR(tone, colors)} size={TOKEN_SIZE} />
+          )}
+        </View>
+      ))}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  // Measures its natural size; transform-scales down to the budget if it overflows.
+  fit: {
+    alignItems: 'center',
+  },
+  groupGrid: {
+    gap: SPACING[200],
+    alignItems: 'center',
+  },
+  frameRow: {
+    flexDirection: 'row',
+    gap: SPACING[300],
+    alignItems: 'center',
+    flexWrap: 'wrap',
+    justifyContent: 'center',
+  },
+  frame: {
+    width: FRAME_COLUMNS * CELL_SIZE + (FRAME_COLUMNS - 1) * CELL_GAP,
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    gap: CELL_GAP,
+  },
+  cell: {
+    width: CELL_SIZE,
+    height: CELL_SIZE,
+    borderRadius: 4,
+    borderWidth: 1.5,
+    borderColor: COLORS.NEUTRAL_5,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  array: {
+    gap: CELL_GAP + 2,
+    alignItems: 'center',
+  },
+  arrayRow: {
+    flexDirection: 'row',
+    gap: CELL_GAP + 2,
+  },
+  groupRow: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    gap: SPACING[200],
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  group: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    // Shrink to fit the dots it holds (a single dot gets a small box); cap at
+    // five columns so larger groups wrap instead of stretching.
+    maxWidth: GROUP_MAX_WIDTH,
+    gap: CELL_GAP,
+    padding: GROUP_PADDING,
+    borderWidth: GROUP_BORDER,
+    borderRadius: BORDER_RADIUS[200],
+    backgroundColor: COLORS.NEUTRAL_2,
+  },
+})

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

@@ -0,0 +1,36 @@
+import React from 'react'
+import { View, StyleSheet } from 'react-native'
+import { COLORS } from '@magmamath/react-native-ui'
+
+export const DOT_SIZE = 12
+
+type DotProps = {
+  color: string
+  // Taken-away token: keep the fill, overlay a 45° strikethrough.
+  strike?: boolean
+  size?: number
+}
+
+// Shared quantity primitive: a filled circle.
+export const Dot = ({ color, strike = false, size = DOT_SIZE }: DotProps) => {
+  const circle = { width: size, height: size, borderRadius: size / 2 }
+  return (
+    <View style={[circle, { backgroundColor: color }]}>
+      {strike && <View style={styles.strike} />}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  strike: {
+    position: 'absolute',
+    top: '50%',
+    left: '-15%',
+    width: '130%',
+    height: 2,
+    marginTop: -1, // pull up half the height so the bar is centered, not top-aligned
+    borderRadius: 1, // round the stroke ends
+    backgroundColor: COLORS.NEUTRAL_10,
+    transform: [{ rotate: '-45deg' }],
+  },
+})

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

@@ -0,0 +1,98 @@
+import React from 'react'
+import { View, StyleSheet } from 'react-native'
+import Svg, { Line, Path, Circle, Text as SvgText } from 'react-native-svg'
+import { COLORS, FONT_FAMILY } from '@magmamath/react-native-ui'
+
+import type { LineSpec } from '../types'
+import type { VisualColors } from './visualColors'
+
+const VB_W = 560
+const VB_H = 110
+const PAD_X = 22
+const BASE_Y = 74
+const ARC_H = 56
+
+type DynamicNumberLineProps = {
+  spec: LineSpec
+  colors: VisualColors
+}
+
+// L3 — addition jumps forward, subtraction backward; both bridge through every
+// ten (jumps land on each multiple of 10 crossed). Multiplication skip-counts.
+export const DynamicNumberLine = ({ spec, colors }: DynamicNumberLineProps) => {
+  const span = spec.hi - spec.lo
+  const denom = span === 0 ? 1 : span
+  const x = (v: number) => PAD_X + ((v - spec.lo) / denom) * (VB_W - 2 * PAD_X)
+
+  return (
+    <View style={styles.wrapper}>
+      <Svg width="100%" height="100%" viewBox={`0 0 ${VB_W} ${VB_H}`} preserveAspectRatio="xMidYMid meet">
+        <Line
+          x1={PAD_X - 14}
+          y1={BASE_Y}
+          x2={VB_W - PAD_X + 14}
+          y2={BASE_Y}
+          stroke={COLORS.NEUTRAL_5}
+          strokeWidth={3}
+          strokeLinecap="round"
+        />
+
+        {spec.ticks.map((value) => (
+          <React.Fragment key={`t${value}`}>
+            <Line x1={x(value)} y1={BASE_Y - 6} x2={x(value)} y2={BASE_Y + 6} stroke={COLORS.NEUTRAL_6} strokeWidth={3} />
+            <SvgText
+              x={x(value)}
+              y={BASE_Y + 25}
+              fontSize={20}
+              fontWeight="700"
+              fontFamily={FONT_FAMILY.buenosAires}
+              fill={COLORS.NEUTRAL_8}
+              textAnchor="middle"
+            >
+              {value === spec.hiddenTick ? '?' : value}
+            </SvgText>
+          </React.Fragment>
+        ))}
+
+        {spec.jumps.map((jump, i) => {
+          const midX = (x(jump.from) + x(jump.to)) / 2
+          return (
+            <React.Fragment key={`j${i}`}>
+              <Path
+                d={`M ${x(jump.from)} ${BASE_Y - 4} Q ${midX} ${BASE_Y - ARC_H - 12} ${x(jump.to)} ${BASE_Y - 4}`}
+                stroke={colors.accent}
+                strokeWidth={4}
+                fill="none"
+              />
+              <Circle cx={x(jump.to)} cy={BASE_Y} r={6.5} fill={colors.accent} />
+              <SvgText
+                x={midX}
+                y={BASE_Y - ARC_H - 1}
+                fontSize={20}
+                fontWeight="800"
+                fontFamily={FONT_FAMILY.buenosAires}
+                fill={colors.dark}
+                textAnchor="middle"
+              >
+                {jump.label}
+              </SvgText>
+            </React.Fragment>
+          )
+        })}
+
+        {spec.jumps.length > 0 && (
+          <Circle cx={x(spec.jumps[0].from)} cy={BASE_Y} r={6.5} fill={colors.accent} />
+        )}
+      </Svg>
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  wrapper: {
+    width: '100%',
+    maxWidth: VB_W,
+    aspectRatio: VB_W / VB_H,
+    alignSelf: 'center',
+  },
+})

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

@@ -0,0 +1,61 @@
+import React from 'react'
+import { View, StyleSheet } from 'react-native'
+
+import type { VisualSpec } from '../types'
+import { DiscreteCounterGrid } from './DiscreteCounterGrid'
+import { RelationalBlock } from './RelationalBlock'
+import { DynamicNumberLine } from './DynamicNumberLine'
+import { QuotativeBars } from './QuotativeBars'
+import type { VisualColors } from './visualColors'
+
+type FactVisualProps = {
+  spec: VisualSpec
+  colors: VisualColors
+}
+
+// Text alternative for the decorative-supportive visual.
+const labelFor = (spec: VisualSpec): string => {
+  switch (spec.kind) {
+    case 'grid':
+    case 'relational':
+    case 'line':
+    case 'bars':
+      return `${spec.left} ${spec.operation} ${spec.right}`
+    case 'none':
+      return ''
+  }
+}
+
+const renderVisual = (spec: VisualSpec, colors: VisualColors) => {
+  switch (spec.kind) {
+    case 'grid':
+      return <DiscreteCounterGrid spec={spec} colors={colors} />
+    case 'relational':
+      return <RelationalBlock spec={spec} colors={colors} />
+    case 'line':
+      return <DynamicNumberLine spec={spec} colors={colors} />
+    case 'bars':
+      return <QuotativeBars spec={spec} colors={colors} />
+    case 'none':
+      return null
+  }
+}
+
+// Renders the scaffold for the current spec. Whether a visual shows at all is
+// decided by the card (none at L4/L5); this component just draws it.
+export const FactVisual = ({ spec, colors }: FactVisualProps) => {
+  if (spec.kind === 'none') return null
+
+  return (
+    <View style={styles.container} accessible accessibilityLabel={labelFor(spec)}>
+      {renderVisual(spec, colors)}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  container: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+})

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

@@ -0,0 +1,92 @@
+import React from 'react'
+import { View, StyleSheet } from 'react-native'
+import Svg, { Rect, Path, Text as SvgText } from 'react-native-svg'
+import { COLORS, FONT_FAMILY } from '@magmamath/react-native-ui'
+
+import type { BarSpec } from '../types'
+import type { VisualColors } from './visualColors'
+
+const VB_W = 480
+const VB_H = 98
+const PAD_X = 24
+const BAR_Y = 12
+const BAR_H = 46
+const BRACKET_Y = BAR_Y + BAR_H + 8
+
+type QuotativeBarsProps = {
+  spec: BarSpec
+  colors: VisualColors
+}
+
+// L2 (division) — quotative model: the dividend bar is cut into equal groups of
+// the divisor; counting the groups gives the quotient (the answer).
+export const QuotativeBars = ({ spec, colors }: QuotativeBarsProps) => {
+  const segments = Math.max(1, spec.segmentCount)
+  const barW = VB_W - 2 * PAD_X
+  const segW = barW / segments
+
+  return (
+    <View style={styles.wrapper}>
+      <Svg width="100%" height="100%" viewBox={`0 0 ${VB_W} ${VB_H}`} preserveAspectRatio="xMidYMid meet">
+        {Array.from({ length: segments }, (_, i) => {
+          const x = PAD_X + i * segW
+          return (
+            <React.Fragment key={i}>
+              <Rect
+                x={x}
+                y={BAR_Y}
+                width={segW}
+                height={BAR_H}
+                rx={6}
+                fill={i % 2 === 0 ? colors.bg : colors.mid}
+                stroke={colors.accent}
+                strokeWidth={2.5}
+              />
+              <SvgText
+                x={x + segW / 2}
+                y={BAR_Y + BAR_H / 2 + 7}
+                fontSize={20}
+                fontWeight="700"
+                fontFamily={FONT_FAMILY.buenosAires}
+                fill={colors.dark}
+                textAnchor="middle"
+              >
+                {spec.segment}
+              </SvgText>
+            </React.Fragment>
+          )
+        })}
+
+        {/* Bracket spanning the whole bar, drawn as one continuous line. */}
+        <Path
+          d={`M ${PAD_X} ${BRACKET_Y} L ${PAD_X} ${BRACKET_Y + 6} L ${VB_W - PAD_X} ${BRACKET_Y + 6} L ${VB_W - PAD_X} ${BRACKET_Y}`}
+          fill="none"
+          stroke={COLORS.NEUTRAL_6}
+          strokeWidth={2.5}
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+        <SvgText
+          x={VB_W / 2}
+          y={BRACKET_Y + 20}
+          fontSize={15}
+          fontWeight="700"
+          fontFamily={FONT_FAMILY.buenosAires}
+          fill={COLORS.NEUTRAL_8}
+          textAnchor="middle"
+        >
+          {spec.total}
+        </SvgText>
+      </Svg>
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  wrapper: {
+    width: '100%',
+    maxWidth: VB_W,
+    aspectRatio: VB_W / VB_H,
+    alignSelf: 'center',
+  },
+})