@magmamath/students-features 1.8.0-rc.0-fluency-visuals → 1.8.0

package/src/features/fluency-teacher/fluencyTeacher.constants.ts

@@ -1,5 +1,11 @@
 import { COLORS } from '@magmamath/react-native-ui'
-import { type OperatorColumnConfig } from './fluencyTeacher.types'
+import type {
+  LegendItem,
+  OperatorCardConfig,
+  OperatorColumnConfig,
+  OperatorPalette,
+  FluencyOperatorColumn,
+} from './fluencyTeacher.types'
 
 export const TEACHER_FLUENCY_GOAL_MINUTES = 25
 
@@ -10,33 +16,103 @@ export enum FluencyOperator {
   DIVISION = 'division',
 }
 
-export const MATRIX_CELL_COLORS: Record<FluencyOperator, Record<number, string>> = {
+export enum MasteryLevel {
+  LEARNING = 1,
+  GROWING = 2,
+  STRONG = 3,
+  AUTOMATIC = 4,
+}
+
+export const OPERATOR_PALETTES: Record<FluencyOperator, OperatorPalette> = {
   [FluencyOperator.ADDITION]: {
-    1: COLORS.GREEN_2,
-    2: COLORS.GREEN_3,
-    3: COLORS.PRIMARY_GREEN,
-    4: COLORS.GREEN_6,
+    bands: [COLORS.GREEN_1, COLORS.GREEN_2, COLORS.GREEN_3, COLORS.GREEN_4, COLORS.PRIMARY_GREEN],
+    bandBorders: [
+      COLORS.GREEN_2,
+      COLORS.GREEN_3,
+      COLORS.GREEN_4,
+      COLORS.PRIMARY_GREEN,
+      COLORS.GREEN_6,
+    ],
+    darkText: COLORS.GREEN_8,
+    legendCount: COLORS.GREEN_7,
+    boxBorder: COLORS.GREEN_2,
   },
   [FluencyOperator.SUBTRACTION]: {
-    1: COLORS.ORANGE_2,
-    2: COLORS.ORANGE_3,
-    3: COLORS.PRIMARY_ORANGE,
-    4: COLORS.ORANGE_6,
+    bands: [
+      COLORS.ORANGE_1,
+      COLORS.ORANGE_2,
+      COLORS.ORANGE_3,
+      COLORS.ORANGE_4,
+      COLORS.PRIMARY_ORANGE,
+    ],
+    bandBorders: [
+      COLORS.ORANGE_2,
+      COLORS.ORANGE_3,
+      COLORS.ORANGE_4,
+      COLORS.PRIMARY_ORANGE,
+      COLORS.ORANGE_6,
+    ],
+    darkText: COLORS.ORANGE_8,
+    legendCount: COLORS.ORANGE_7,
+    boxBorder: COLORS.ORANGE_2,
   },
   [FluencyOperator.MULTIPLICATION]: {
-    1: COLORS.BLUE_2,
-    2: COLORS.BLUE_3,
-    3: COLORS.PRIMARY_BLUE,
-    4: COLORS.BLUE_6,
+    bands: [COLORS.BLUE_1, COLORS.BLUE_2, COLORS.BLUE_3, COLORS.BLUE_4, COLORS.PRIMARY_BLUE],
+    bandBorders: [COLORS.BLUE_2, COLORS.BLUE_3, COLORS.BLUE_4, COLORS.PRIMARY_BLUE, COLORS.BLUE_6],
+    darkText: COLORS.BLUE_8,
+    legendCount: COLORS.BLUE_7,
+    boxBorder: COLORS.BLUE_2,
   },
   [FluencyOperator.DIVISION]: {
-    1: COLORS.PURPLE_2,
-    2: COLORS.PURPLE_3,
-    3: COLORS.PRIMARY_PURPLE,
-    4: COLORS.PURPLE_6,
+    bands: [
+      COLORS.PURPLE_1,
+      COLORS.PURPLE_2,
+      COLORS.PURPLE_3,
+      COLORS.PURPLE_4,
+      COLORS.PRIMARY_PURPLE,
+    ],
+    bandBorders: [
+      COLORS.PURPLE_2,
+      COLORS.PURPLE_3,
+      COLORS.PURPLE_4,
+      COLORS.PRIMARY_PURPLE,
+      COLORS.PURPLE_6,
+    ],
+    darkText: COLORS.PURPLE_8,
+    legendCount: COLORS.PURPLE_7,
+    boxBorder: COLORS.PURPLE_2,
   },
 }
 
+export const MATRIX_CELL_COLORS: Record<FluencyOperator, Record<MasteryLevel, string>> = {
+  [FluencyOperator.ADDITION]: {
+    [MasteryLevel.LEARNING]: COLORS.GREEN_1,
+    [MasteryLevel.GROWING]: COLORS.GREEN_2,
+    [MasteryLevel.STRONG]: COLORS.GREEN_4,
+    [MasteryLevel.AUTOMATIC]: COLORS.GREEN_7,
+  },
+  [FluencyOperator.SUBTRACTION]: {
+    [MasteryLevel.LEARNING]: COLORS.ORANGE_1,
+    [MasteryLevel.GROWING]: COLORS.ORANGE_2,
+    [MasteryLevel.STRONG]: COLORS.ORANGE_4,
+    [MasteryLevel.AUTOMATIC]: COLORS.ORANGE_7,
+  },
+  [FluencyOperator.MULTIPLICATION]: {
+    [MasteryLevel.LEARNING]: COLORS.BLUE_1,
+    [MasteryLevel.GROWING]: COLORS.BLUE_2,
+    [MasteryLevel.STRONG]: COLORS.BLUE_4,
+    [MasteryLevel.AUTOMATIC]: COLORS.BLUE_7,
+  },
+  [FluencyOperator.DIVISION]: {
+    [MasteryLevel.LEARNING]: COLORS.PURPLE_1,
+    [MasteryLevel.GROWING]: COLORS.PURPLE_2,
+    [MasteryLevel.STRONG]: COLORS.PURPLE_4,
+    [MasteryLevel.AUTOMATIC]: COLORS.PURPLE_7,
+  },
+}
+
+export const MATRIX_NOT_STARTED_COLOR = COLORS.NEUTRAL_3
+
 export enum FluencyTableColumn {
   AVERAGE = 'average',
   ADDITION = 'addition',
@@ -45,8 +121,6 @@ export enum FluencyTableColumn {
   DIVISION = 'division',
 }
 
-export type FluencyOperatorColumn = Exclude<FluencyTableColumn, FluencyTableColumn.AVERAGE>
-
 export enum FluencyMathOperatorSymbol {
   ADDITION = '+',
   SUBTRACTION = '−',
@@ -54,33 +128,57 @@ export enum FluencyMathOperatorSymbol {
   DIVISION = '÷',
 }
 
-export const TABLE_OPERATOR_COLUMNS: readonly OperatorColumnConfig[] = [
-  {
-    operator: FluencyTableColumn.ADDITION,
+export const COLUMN_TO_OPERATOR: Record<FluencyOperatorColumn, FluencyOperator> = {
+  [FluencyTableColumn.ADDITION]: FluencyOperator.ADDITION,
+  [FluencyTableColumn.SUBTRACTION]: FluencyOperator.SUBTRACTION,
+  [FluencyTableColumn.MULTIPLICATION]: FluencyOperator.MULTIPLICATION,
+  [FluencyTableColumn.DIVISION]: FluencyOperator.DIVISION,
+}
+
+export const OPERATOR_TO_COLUMN: Record<FluencyOperator, FluencyOperatorColumn> = {
+  [FluencyOperator.ADDITION]: FluencyTableColumn.ADDITION,
+  [FluencyOperator.SUBTRACTION]: FluencyTableColumn.SUBTRACTION,
+  [FluencyOperator.MULTIPLICATION]: FluencyTableColumn.MULTIPLICATION,
+  [FluencyOperator.DIVISION]: FluencyTableColumn.DIVISION,
+}
+
+export const MAX_GRADE_WITH_TWO_OPERATORS = 2
+
+export const TWO_OPERATOR_SET: readonly FluencyOperator[] = [
+  FluencyOperator.ADDITION,
+  FluencyOperator.SUBTRACTION,
+]
+
+export const OPERATOR_CARD_CONFIG: Record<FluencyOperator, OperatorCardConfig> = {
+  [FluencyOperator.ADDITION]: {
     labelKey: 'student.fluency.addition',
     symbol: FluencyMathOperatorSymbol.ADDITION,
-    badgeBg: COLORS.GREEN_3,
-    badgeText: COLORS.GREEN_8,
   },
-  {
-    operator: FluencyTableColumn.SUBTRACTION,
+  [FluencyOperator.SUBTRACTION]: {
     labelKey: 'student.fluency.subtraction',
     symbol: FluencyMathOperatorSymbol.SUBTRACTION,
-    badgeBg: COLORS.ORANGE_3,
-    badgeText: COLORS.ORANGE_8,
-  },
-  {
-    operator: FluencyTableColumn.DIVISION,
-    labelKey: 'student.fluency.division',
-    symbol: FluencyMathOperatorSymbol.DIVISION,
-    badgeBg: COLORS.BLUE_3,
-    badgeText: COLORS.BLUE_8,
   },
-  {
-    operator: FluencyTableColumn.MULTIPLICATION,
+  [FluencyOperator.MULTIPLICATION]: {
     labelKey: 'student.fluency.multiplication',
     symbol: FluencyMathOperatorSymbol.MULTIPLICATION,
-    badgeBg: COLORS.PURPLE_2,
-    badgeText: COLORS.PURPLE_8,
   },
+  [FluencyOperator.DIVISION]: {
+    labelKey: 'student.fluency.division',
+    symbol: FluencyMathOperatorSymbol.DIVISION,
+  },
+}
+
+export const TABLE_OPERATOR_COLUMNS: readonly OperatorColumnConfig[] = Object.values(
+  FluencyOperator,
+).map((operator) => ({
+  operator: OPERATOR_TO_COLUMN[operator],
+  labelKey: OPERATOR_CARD_CONFIG[operator].labelKey,
+}))
+
+export const LEGEND_LEVELS: readonly LegendItem[] = [
+  { box: MasteryLevel.AUTOMATIC, labelKey: 'student.fluency.masteryMastered' },
+  { box: MasteryLevel.STRONG, labelKey: 'student.fluency.masteryStrong' },
+  { box: MasteryLevel.GROWING, labelKey: 'student.fluency.masteryGrowing' },
+  { box: MasteryLevel.LEARNING, labelKey: 'student.fluency.masteryLearning' },
+  { box: null, labelKey: 'teacher.fluency.progressNotStarted' },
 ]

package/src/features/fluency-teacher/fluencyTeacher.helpers.ts

@@ -1,22 +1,95 @@
 import { COLORS } from '@magmamath/react-native-ui'
-import type { TranslationKey } from '../../i18n/i18n'
+import {
+  COLUMN_TO_OPERATOR,
+  FluencyOperator,
+  FluencyTableColumn,
+  MasteryLevel,
+  MATRIX_NOT_STARTED_COLOR,
+  MAX_GRADE_WITH_TWO_OPERATORS,
+  OPERATOR_PALETTES,
+  TABLE_OPERATOR_COLUMNS,
+  TWO_OPERATOR_SET,
+} from './fluencyTeacher.constants'
 import type {
   ClassFluencySummaryResponse,
   ClassFluencyStats,
   ClassOperatorAverages,
+  DrawerGrid,
   FluencyStudent,
+  OperatorBandColors,
+  OperatorColumnConfig,
   StudentResult,
 } from './fluencyTeacher.types'
 
-export const getCellColor = (box: number | null, colorMap: Record<number, string>): string =>
-  box ? (colorMap[box] ?? COLORS.NEUTRAL_2) : COLORS.NEUTRAL_2
+export const getCellColor = (
+  box: MasteryLevel | null,
+  colorMap: Record<MasteryLevel, string>,
+): string => (box ? (colorMap[box] ?? MATRIX_NOT_STARTED_COLOR) : MATRIX_NOT_STARTED_COLOR)
 
-export const toAverageLabel = (overallPercent: number): TranslationKey => {
-  if (overallPercent >= 0.9) return 'teacher.fluency.progressFluent'
-  if (overallPercent >= 0.65) return 'teacher.fluency.progressProficient'
-  if (overallPercent >= 0.35) return 'teacher.fluency.progressDeveloping'
-  if (overallPercent >= 0.05) return 'teacher.fluency.progressLearning'
-  return 'teacher.fluency.progressNotStarted'
+export const isTwoOperatorGrade = (grade: number) => grade <= MAX_GRADE_WITH_TWO_OPERATORS
+
+export const getTableOperatorColumns = (grade: number): readonly OperatorColumnConfig[] =>
+  isTwoOperatorGrade(grade)
+    ? TABLE_OPERATOR_COLUMNS.filter(({ operator }) =>
+        TWO_OPERATOR_SET.includes(COLUMN_TO_OPERATOR[operator]),
+      )
+    : TABLE_OPERATOR_COLUMNS
+
+export const getOperatorsForGrade = (grade: number): readonly FluencyOperator[] =>
+  isTwoOperatorGrade(grade) ? TWO_OPERATOR_SET : Object.values(FluencyOperator)
+
+export const isColumnVisibleForGrade = (column: FluencyTableColumn, grade: number): boolean =>
+  column === FluencyTableColumn.AVERAGE ||
+  getTableOperatorColumns(grade).some(({ operator }) => operator === column)
+
+export const isCommutativeOperator = (operator: FluencyOperator): boolean =>
+  operator === FluencyOperator.ADDITION || operator === FluencyOperator.MULTIPLICATION
+
+export const getHigherMasteryLevel = (a: MasteryLevel, b: MasteryLevel): MasteryLevel =>
+  a > b ? a : b
+
+const toValidMasteryLevel = (box: MasteryLevel | null): MasteryLevel | null =>
+  box !== null && box >= MasteryLevel.LEARNING && box <= MasteryLevel.AUTOMATIC ? box : null
+
+export const countFactsByMasteryLevel = (
+  grid: DrawerGrid | null,
+  operator: FluencyOperator,
+): Map<MasteryLevel | null, number> => {
+  const counts = new Map<MasteryLevel | null, number>()
+  const commutative = isCommutativeOperator(operator)
+  grid?.rows.forEach((row) =>
+    row.cells.forEach((cell, columnIndex) => {
+      if (cell.isEmpty) return
+      // Commutative grids mirror each fact into (a,b) and (b,a) cells —
+      // count only the upper triangle so each fact is counted once.
+      if (commutative && grid.colLabels[columnIndex] < row.label) return
+      const box = toValidMasteryLevel(cell.box)
+      counts.set(box, (counts.get(box) ?? 0) + 1)
+    }),
+  )
+  return counts
+}
+
+const toBandIndex = (percent: number): number => {
+  if (percent <= 20) return 0
+  if (percent <= 40) return 1
+  if (percent <= 60) return 2
+  if (percent <= 80) return 3
+  return 4
+}
+
+// Dark shades (bands 4-5) need white text to stay readable
+export const getOperatorBandColors = (
+  operator: FluencyOperator,
+  percent: number,
+): OperatorBandColors => {
+  const palette = OPERATOR_PALETTES[operator]
+  const band = toBandIndex(percent)
+  return {
+    background: palette.bands[band],
+    border: palette.bandBorders[band],
+    text: band >= 3 ? COLORS.NEUTRAL_1 : palette.darkText,
+  }
 }
 
 const toPercent = (decimal: number): number => Math.round(decimal * 100)
@@ -68,7 +141,6 @@ export const buildStudentsFluencyTable = ({
         id: row.studentId,
         name: student.name,
         averagePercent: toPercent(row.overallPercent),
-        averageLabel: toAverageLabel(row.overallPercent),
         scores: {
           addition: toPercent(row.byOperator.addition),
           subtraction: toPercent(row.byOperator.subtraction),

package/src/features/fluency-teacher/fluencyTeacher.types.ts

@@ -1,5 +1,10 @@
 import type { TranslationKey } from '../../i18n/i18n'
-import { FluencyOperator, FluencyOperatorColumn, FluencyTableColumn } from './fluencyTeacher.constants'
+import {
+  FluencyMathOperatorSymbol,
+  FluencyOperator,
+  FluencyTableColumn,
+  MasteryLevel,
+} from './fluencyTeacher.constants'
 import { SortingDirection } from '../../shared/common.constants'
 
 type FactId = string
@@ -10,7 +15,7 @@ type FactPosition = {
 }
 
 type FactState = {
-  box: number
+  box: MasteryLevel
   lastAttemptedAt: string | null
   lastSolvedAt: string | null
   attemptsCount: number
@@ -62,6 +67,8 @@ export type ClassFluencySummaryResponse = {
   hardestFacts: TeacherFluencyHardestFact[]
 }
 
+export type FluencyOperatorColumn = Exclude<FluencyTableColumn, FluencyTableColumn.AVERAGE>
+
 export type ClassOperatorAverages = Record<FluencyOperatorColumn, number>
 
 export type ClassFluencyStats = ClassFluencySummaryResponse & {
@@ -88,7 +95,6 @@ export type StudentResult = {
   id: string
   name: string
   averagePercent: number
-  averageLabel: TranslationKey
   scores: StudentOperatorScores
 }
 
@@ -99,11 +105,38 @@ export type StudentDrawerInfo = StudentResult & {
 export type OperatorColumnConfig = {
   operator: FluencyOperatorColumn
   labelKey: TranslationKey
-  symbol: string
-  badgeBg: string
-  badgeText: string
 }
 
+export type OperatorCardConfig = {
+  labelKey: TranslationKey
+  symbol: FluencyMathOperatorSymbol
+}
+
+export type OperatorPalette = {
+  bands: [string, string, string, string, string]
+  bandBorders: [string, string, string, string, string]
+  darkText: string
+  legendCount: string
+  boxBorder: string
+}
+
+export type OperatorBandColors = {
+  background: string
+  border: string
+  text: string
+}
+
+export type LegendItem = {
+  box: MasteryLevel | null
+  labelKey: TranslationKey
+}
+
+export type DrawerGridCell = { box: MasteryLevel | null; isEmpty: boolean }
+
+export type DrawerGridRow = { label: number; cells: DrawerGridCell[] }
+
+export type DrawerGrid = { colLabels: number[]; rows: DrawerGridRow[] }
+
 export type TeacherFluencyGateProps = {
   students: FluencyStudent[]
   grade: number

package/src/features/fluency-teacher/hooks/useDrawerGrid.ts

@@ -2,10 +2,8 @@ import { useMemo } from 'react'
 import { useUnit } from 'effector-react'
 import { useTeacherFluency } from '../context/TeacherFluencyContext'
 import { FluencyOperator } from '../fluencyTeacher.constants'
-
-export type DrawerGridCell = { box: number | null; isEmpty: boolean }
-export type DrawerGridRow = { label: number; cells: DrawerGridCell[] }
-export type DrawerGrid = { colLabels: number[]; rows: DrawerGridRow[] }
+import { getHigherMasteryLevel, isCommutativeOperator } from '../fluencyTeacher.helpers'
+import type { DrawerGrid } from '../fluencyTeacher.types'
 
 export const useDrawerGrid = (operator: FluencyOperator): DrawerGrid | null => {
   const { model } = useTeacherFluency()
@@ -19,8 +17,7 @@ export const useDrawerGrid = (operator: FluencyOperator): DrawerGrid | null => {
 
     const isDivision = operator === FluencyOperator.DIVISION
     const isSubtraction = operator === FluencyOperator.SUBTRACTION
-    const isCommutative =
-      operator === FluencyOperator.ADDITION || operator === FluencyOperator.MULTIPLICATION
+    const isCommutative = isCommutativeOperator(operator)
 
     const maxRow = Math.max(...factList.map((f) => f.position.row))
     const maxCol = Math.max(...factList.map((f) => f.position.column))
@@ -46,7 +43,7 @@ export const useDrawerGrid = (operator: FluencyOperator): DrawerGrid | null => {
         const mirrorBox = mirrorFact?.box ?? null
         const box =
           primaryBox !== null && mirrorBox !== null
-            ? Math.max(primaryBox, mirrorBox)
+            ? getHigherMasteryLevel(primaryBox, mirrorBox)
             : (primaryBox ?? mirrorBox)
 
         return { box, isEmpty: false }

package/src/features/fluency-teacher/hooks/useDrawerMatrix.ts

@@ -1,7 +1,8 @@
 import { useMemo, useState } from 'react'
 import type { LayoutChangeEvent } from 'react-native'
-import { FluencyOperator, MATRIX_CELL_COLORS } from '../fluencyTeacher.constants'
-import { useDrawerGrid, type DrawerGrid } from './useDrawerGrid'
+import { FluencyOperator, MasteryLevel, MATRIX_CELL_COLORS } from '../fluencyTeacher.constants'
+import type { DrawerGrid } from '../fluencyTeacher.types'
+import { useDrawerGrid } from './useDrawerGrid'
 
 const MATRIX_CELL_GAP = 2
 
@@ -10,7 +11,7 @@ type DrawerMatrixLayout = {
   cellSize: number
   fontSize: number
   borderRadius: number
-  cellColorMap: Record<number, string>
+  cellColorMap: Record<MasteryLevel, string>
   onLayout: (e: LayoutChangeEvent) => void
 }
 

package/src/features/fluency-teacher/model/TeacherFluencyFiltersModel.ts

@@ -8,13 +8,16 @@ export class TeacherFluencyFiltersModel {
   public readonly $search = restore(this.setSearch, '')
 
   public readonly toggleSort = createEvent<FluencyTableColumn>()
+  public readonly resetSort = createEvent()
   public readonly $sort = createStore<SortState>({
     column: FluencyTableColumn.AVERAGE,
     direction: SortingDirection.DESC,
-  }).on(this.toggleSort, (state, column) => {
-    if (state.column !== column) return { column, direction: SortingDirection.DESC }
-    const direction =
-      state.direction === SortingDirection.DESC ? SortingDirection.ASC : SortingDirection.DESC
-    return { column, direction }
   })
+    .reset(this.resetSort)
+    .on(this.toggleSort, (state, column) => {
+      if (state.column !== column) return { column, direction: SortingDirection.DESC }
+      const direction =
+        state.direction === SortingDirection.DESC ? SortingDirection.ASC : SortingDirection.DESC
+      return { column, direction }
+    })
 }

package/src/features/fluency-teacher/model/TeacherFluencyModel.ts

@@ -3,6 +3,7 @@ import { createGate } from 'effector-react'
 import { TeacherFluencyApiModel } from './TeacherFluencyApiModel'
 import { TeacherFluencyFiltersModel } from './TeacherFluencyFiltersModel'
 import { TeacherFluencyTableModel } from './TeacherFluencyTableModel'
+import { isColumnVisibleForGrade } from '../fluencyTeacher.helpers'
 import type { TeacherFluencyGateProps, TeacherFluencyModelProps } from '../fluencyTeacher.types'
 
 export class TeacherFluencyModel {
@@ -26,6 +27,13 @@ export class TeacherFluencyModel {
       target: this.table.reset,
     })
 
+    sample({
+      clock: this.gate.state,
+      source: this.filters.$sort,
+      filter: (sort, { grade }) => !isColumnVisibleForGrade(sort.column, grade),
+      target: this.filters.resetSort,
+    })
+
     sample({
       clock: this.gate.state,
       source: this.table.initFx.pending,