@magmamath/students-features 1.3.10-rc.1 → 1.3.10

package/dist/typescript/commonjs/features/uiMode/__tests__/getUIMode.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=getUIMode.test.d.ts.map

package/dist/typescript/commonjs/features/uiMode/__tests__/getUIMode.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getUIMode.test.d.ts","sourceRoot":"","sources":["../../../../../../src/features/uiMode/__tests__/getUIMode.test.ts"],"names":[],"mappings":""}

package/dist/typescript/module/features/uiMode/__tests__/getUIMode.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=getUIMode.test.d.ts.map

package/dist/typescript/module/features/uiMode/__tests__/getUIMode.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getUIMode.test.d.ts","sourceRoot":"","sources":["../../../../../../src/features/uiMode/__tests__/getUIMode.test.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magmamath/students-features",
-  "version": "1.3.10-rc.1",
+  "version": "1.3.10",
   "description": "Magmamath features library",
   "source": "src/index.ts",
   "main": "src/index.ts",
@@ -41,7 +41,7 @@
   },
   "devDependencies": {
     "@magmamath/frontend-config": "1.1.3",
-    "@magmamath/react-native-draw-board": "1.8.2-rc.3",
+    "@magmamath/react-native-draw-board": "1.8.2",
     "@magmamath/react-native-ui": "0.4.83",
     "@matteappen/skills-utils": "^3.7.1",
     "@react-native-masked-view/masked-view": "^0.3.2",

package/src/features/uiMode/__tests__/SPEC.md

@@ -0,0 +1,114 @@
+# UIMode Specification
+
+## Inputs
+
+| Input                | Type              | Description                                       |
+|----------------------|-------------------|---------------------------------------------------|
+| `user.grade`         | `number \| null`  | User's grade level. Invalid when `null` or `-1`   |
+| `practice.isEnabled` | `boolean`         | Whether this is a practice exercise               |
+| `practice.grade`     | `number \| null`  | Grade of the practice problem                     |
+| `assignment.grade`   | `number \| null`  | From `assignment.classes[0].grade`                |
+| `locale`             | `Locale`          | e.g. `US`, `CA`, `SE`                             |
+| `problem.answerType` | `AnswerType`      | Current problem's answer type                     |
+| `problem.characterType` | `number`       | Current problem's character type                  |
+| `problem.hasAnswerVariants` | `boolean`  | Whether the current problem has answer variants   |
+
+## Output
+
+| Field        | Type             | Values                          |
+|--------------|------------------|---------------------------------|
+| `general`    | `UIMode`         | `SIMPLE` or `REGULAR`           |
+| `toolbar`    | `ToolBarVariants` | `SIMPLE`, `COMMON`, `ADVANCED` |
+| `answerArea` | `UIMode`         | `SIMPLE` or `REGULAR`           |
+
+---
+
+## Step 1: Determine `isSimpleMode`
+
+A grade is "simple" when it is **not null** and is **between 0 and 2 inclusive**.
+
+| Condition                          | Grade used           |
+|------------------------------------|----------------------|
+| `practice.isEnabled` is `true`     | `practice.grade`     |
+| `user.grade` is valid (not null/-1)| `user.grade`         |
+| `user.grade` is null or -1         | `assignment.grade`   |
+
+### Test cases
+
+| #  | practice.isEnabled | practice.grade | user.grade | assignment.grade | isSimpleMode |
+|----|--------------------|----------------|------------|------------------|--------------|
+| 1  | true               | 0              | -          | -                | true         |
+| 2  | true               | 2              | -          | -                | true         |
+| 3  | true               | 3              | -          | -                | false        |
+| 4  | true               | null           | -          | -                | false        |
+| 5  | false              | -              | 1          | -                | true         |
+| 6  | false              | -              | 5          | -                | false        |
+| 7  | false              | -              | null       | 2                | true         |
+| 8  | false              | -              | -1         | 2                | true         |
+| 9  | false              | -              | null       | 5                | false        |
+| 10 | false              | -              | null       | null             | false        |
+
+---
+
+## Step 2: `general`
+
+| isSimpleMode | general   |
+|--------------|-----------|
+| true         | `SIMPLE`  |
+| false        | `REGULAR` |
+
+---
+
+## Step 3: `toolbar`
+
+Effective grade = `assignment.grade ?? practice.grade`
+
+| #  | assignment.grade | practice.grade | locale | isSimpleMode | toolbar    |
+|----|------------------|----------------|--------|--------------|------------|
+| 11 | 7                | -              | SE     | any          | `ADVANCED` |
+| 12 | 8                | -              | US     | any          | `ADVANCED` |
+| 13 | 6                | -              | US     | any          | `ADVANCED` |
+| 14 | 6                | -              | CA     | any          | `ADVANCED` |
+| 15 | 6                | -              | SE     | true         | `SIMPLE`   |
+| 16 | 6                | -              | SE     | false        | `COMMON`   |
+| 17 | 3                | -              | US     | true         | `SIMPLE`   |
+| 18 | 3                | -              | US     | false        | `COMMON`   |
+| 19 | null             | 8              | US     | any          | `ADVANCED` |
+| 20 | null             | null           | -      | true         | `SIMPLE`   |
+| 21 | null             | null           | -      | false        | `COMMON`   |
+
+**Advanced threshold:**
+
+| Locale   | Grade >= | Result     |
+|----------|----------|------------|
+| US or CA | 6        | `ADVANCED` |
+| Other    | 7        | `ADVANCED` |
+
+**Priority:** `ADVANCED` > `SIMPLE` > `COMMON`
+
+---
+
+## Step 4: `answerArea`
+
+| #  | isSimpleMode | practice.isEnabled | hasAnswerVariants | answerType   | characterType | answerArea |
+|----|--------------|--------------------|-------------------|--------------|---------------|------------|
+| 22 | false        | any                | any               | any          | any           | `REGULAR`  |
+| 23 | true         | true               | any               | any          | any           | `SIMPLE`   |
+| 24 | true         | false              | true              | any          | any           | `SIMPLE`   |
+| 25 | true         | false              | false             | HANDWRITING  | 10            | `SIMPLE`   |
+| 26 | true         | false              | false             | HANDWRITING  | 5             | `REGULAR`  |
+| 27 | true         | false              | false             | MULTI_CHOICE | 10            | `REGULAR`  |
+| 28 | true         | false              | false             | other        | any           | `REGULAR`  |
+
+---
+
+## Full combined scenarios
+
+| #  | Mode     | user.grade | assignment.grade | practice.grade | locale | hasVariants | answerType  | charType | general   | toolbar    | answerArea |
+|----|----------|------------|------------------|----------------|--------|-------------|-------------|----------|-----------|------------|------------|
+| 29 | practice | -          | -                | 1              | US     | true        | -           | -        | `SIMPLE`  | `SIMPLE`   | `SIMPLE`   |
+| 30 | practice | -          | -                | 8              | US     | false       | -           | -        | `REGULAR` | `ADVANCED` | `REGULAR`  |
+| 31 | regular  | 2          | 7                | -              | SE     | true        | -           | -        | `SIMPLE`  | `ADVANCED` | `SIMPLE`   |
+| 32 | regular  | 5          | 3                | -              | US     | false       | SINGLE      | -        | `REGULAR` | `COMMON`   | `REGULAR`  |
+| 33 | regular  | null       | 1                | -              | SE     | false       | HANDWRITING | 10       | `SIMPLE`  | `SIMPLE`   | `SIMPLE`   |
+| 34 | regular  | null       | null             | null           | SE     | -           | -           | -        | `REGULAR` | `COMMON`   | `REGULAR`  |

package/src/features/uiMode/__tests__/getUIMode.test.ts

@@ -0,0 +1,364 @@
+jest.mock('@magmamath/react-native-draw-board', () => ({
+  ToolBarVariants: {
+    COMMON: 'COMMON',
+    SIMPLE: 'SIMPLE',
+    ADVANCED: 'ADVANCED',
+    REPLAY: 'REPLAY',
+    NO_CONTROLLER: 'NO_CONTROLLER',
+  },
+}))
+
+jest.mock('@magmamath/frontend-config', () => ({
+  Locale: {
+    US: 'en-SE',
+    SE: 'sv-SE',
+    CA: 'en-CA',
+    GB: 'en-GB',
+    SCT: 'en-SCT',
+    DE: 'de-DE',
+  },
+}))
+
+import { getUIMode } from '../getUIMode'
+import { UIMode } from '../uiMode.constants'
+import { AnswerType } from '../../../types/answerTypes'
+import { MyScriptMathCharacterTypes } from '../../../types/characterTypes'
+import { ToolBarVariants } from '@magmamath/react-native-draw-board'
+import { Locale } from '@magmamath/frontend-config'
+import { GetUIModeProps } from '../uiMode.types'
+
+const defaults: GetUIModeProps = {
+  user: { grade: null },
+  practice: { isEnabled: false, grade: null },
+  assignment: { grade: null },
+  locale: Locale.US,
+  problem: {
+    answerType: AnswerType.HANDWRITING,
+    characterType: MyScriptMathCharacterTypes.DEFAULT,
+    hasAnswerVariants: false,
+  },
+}
+
+const getUIModeWithDefaults = (overrides: Partial<GetUIModeProps>) =>
+  getUIMode({ ...defaults, ...overrides })
+
+describe('practice mode uses practice grade to determine simple mode (grades 0-2 are simple)', () => {
+  it('grade 0 → simple', () => {
+    const result = getUIModeWithDefaults({ practice: { isEnabled: true, grade: 0 } })
+    expect(result.general).toBe(UIMode.SIMPLE)
+  })
+
+  it('grade 2 → simple', () => {
+    const result = getUIModeWithDefaults({ practice: { isEnabled: true, grade: 2 } })
+    expect(result.general).toBe(UIMode.SIMPLE)
+  })
+
+  it('grade 3 → regular', () => {
+    const result = getUIModeWithDefaults({ practice: { isEnabled: true, grade: 3 } })
+    expect(result.general).toBe(UIMode.REGULAR)
+  })
+
+  it('null grade → regular', () => {
+    const result = getUIModeWithDefaults({ practice: { isEnabled: true, grade: null } })
+    expect(result.general).toBe(UIMode.REGULAR)
+  })
+
+  it('young student practicing with answer variants gets full simple experience', () => {
+    const result = getUIModeWithDefaults({
+      practice: { isEnabled: true, grade: 1 },
+      locale: Locale.US,
+      problem: {
+        answerType: AnswerType.HANDWRITING,
+        characterType: MyScriptMathCharacterTypes.DEFAULT,
+        hasAnswerVariants: true,
+      },
+    })
+    expect(result).toEqual({
+      general: UIMode.SIMPLE,
+      toolbar: ToolBarVariants.SIMPLE,
+      answerArea: UIMode.SIMPLE,
+    })
+  })
+
+  it('older student practicing gets advanced toolbar with regular UI', () => {
+    const result = getUIModeWithDefaults({
+      practice: { isEnabled: true, grade: 8 },
+      locale: Locale.US,
+      problem: {
+        answerType: AnswerType.HANDWRITING,
+        characterType: MyScriptMathCharacterTypes.DEFAULT,
+        hasAnswerVariants: false,
+      },
+    })
+    expect(result).toEqual({
+      general: UIMode.REGULAR,
+      toolbar: ToolBarVariants.ADVANCED,
+      answerArea: UIMode.REGULAR,
+    })
+  })
+})
+
+describe('regular mode uses user grade, falls back to assignment grade when user grade is null, undefined, or -1', () => {
+  it('user grade 1 → simple', () => {
+    const result = getUIModeWithDefaults({ user: { grade: 1 } })
+    expect(result.general).toBe(UIMode.SIMPLE)
+  })
+
+  it('user grade 5 → regular', () => {
+    const result = getUIModeWithDefaults({ user: { grade: 5 } })
+    expect(result.general).toBe(UIMode.REGULAR)
+  })
+
+  it('user grade null falls back to assignment grade 2 → simple', () => {
+    const result = getUIModeWithDefaults({ user: { grade: null }, assignment: { grade: 2 } })
+    expect(result.general).toBe(UIMode.SIMPLE)
+  })
+
+  it('user grade undefined falls back to assignment grade 2 → simple', () => {
+    const result = getUIModeWithDefaults({ user: { grade: undefined }, assignment: { grade: 2 } })
+    expect(result.general).toBe(UIMode.SIMPLE)
+  })
+
+  it('user grade -1 (invalid) falls back to assignment grade 2 → simple', () => {
+    const result = getUIModeWithDefaults({ user: { grade: -1 }, assignment: { grade: 2 } })
+    expect(result.general).toBe(UIMode.SIMPLE)
+  })
+
+  it('user grade null falls back to assignment grade 5 → regular', () => {
+    const result = getUIModeWithDefaults({ user: { grade: null }, assignment: { grade: 5 } })
+    expect(result.general).toBe(UIMode.REGULAR)
+  })
+
+  it('user grade undefined falls back to assignment grade 5 → regular', () => {
+    const result = getUIModeWithDefaults({ user: { grade: undefined }, assignment: { grade: 5 } })
+    expect(result.general).toBe(UIMode.REGULAR)
+  })
+
+  it('both user and assignment grade null → regular', () => {
+    const result = getUIModeWithDefaults({ user: { grade: null }, assignment: { grade: null } })
+    expect(result.general).toBe(UIMode.REGULAR)
+  })
+
+  it('user grade 2 in grade 7 SE assignment gets simple mode but advanced toolbar', () => {
+    const result = getUIModeWithDefaults({
+      user: { grade: 2 },
+      assignment: { grade: 7 },
+      locale: Locale.SE,
+      problem: {
+        answerType: AnswerType.HANDWRITING,
+        characterType: MyScriptMathCharacterTypes.DEFAULT,
+        hasAnswerVariants: true,
+      },
+    })
+    expect(result).toEqual({
+      general: UIMode.SIMPLE,
+      toolbar: ToolBarVariants.ADVANCED,
+      answerArea: UIMode.SIMPLE,
+    })
+  })
+
+  it('user grade 5 in grade 3 US assignment gets fully regular experience', () => {
+    const result = getUIModeWithDefaults({
+      user: { grade: 5 },
+      assignment: { grade: 3 },
+      locale: Locale.US,
+      problem: {
+        answerType: AnswerType.SINGLE_CHOICE,
+        characterType: MyScriptMathCharacterTypes.DEFAULT,
+        hasAnswerVariants: false,
+      },
+    })
+    expect(result).toEqual({
+      general: UIMode.REGULAR,
+      toolbar: ToolBarVariants.COMMON,
+      answerArea: UIMode.REGULAR,
+    })
+  })
+
+  it('unknown user falls back to assignment grade 1 in SE with handwriting whole numbers', () => {
+    const result = getUIModeWithDefaults({
+      user: { grade: null },
+      assignment: { grade: 1 },
+      locale: Locale.SE,
+      problem: {
+        answerType: AnswerType.HANDWRITING,
+        characterType: MyScriptMathCharacterTypes.NUMBERS_WHOLE,
+        hasAnswerVariants: false,
+      },
+    })
+    expect(result).toEqual({
+      general: UIMode.SIMPLE,
+      toolbar: ToolBarVariants.SIMPLE,
+      answerArea: UIMode.SIMPLE,
+    })
+  })
+
+  it('all grades unknown defaults to fully regular experience', () => {
+    const result = getUIModeWithDefaults({
+      user: { grade: null },
+      assignment: { grade: null },
+      practice: { isEnabled: false, grade: null },
+      locale: Locale.SE,
+    })
+    expect(result).toEqual({
+      general: UIMode.REGULAR,
+      toolbar: ToolBarVariants.COMMON,
+      answerArea: UIMode.REGULAR,
+    })
+  })
+})
+
+describe('toolbar is ADVANCED for high grades (>=6 US/CA, >=7 elsewhere), SIMPLE for young students, COMMON otherwise', () => {
+  it('grade 7 in SE → ADVANCED', () => {
+    const result = getUIModeWithDefaults({ assignment: { grade: 7 }, locale: Locale.SE, user: { grade: 7 } })
+    expect(result.toolbar).toBe(ToolBarVariants.ADVANCED)
+  })
+
+  it('grade 8 in US → ADVANCED', () => {
+    const result = getUIModeWithDefaults({ assignment: { grade: 8 }, locale: Locale.US, user: { grade: 8 } })
+    expect(result.toolbar).toBe(ToolBarVariants.ADVANCED)
+  })
+
+  it('grade 6 in US → ADVANCED', () => {
+    const result = getUIModeWithDefaults({ assignment: { grade: 6 }, locale: Locale.US, user: { grade: 6 } })
+    expect(result.toolbar).toBe(ToolBarVariants.ADVANCED)
+  })
+
+  it('grade 6 in CA → ADVANCED', () => {
+    const result = getUIModeWithDefaults({ assignment: { grade: 6 }, locale: Locale.CA, user: { grade: 6 } })
+    expect(result.toolbar).toBe(ToolBarVariants.ADVANCED)
+  })
+
+  it('grade 6 in SE with simple mode student → SIMPLE (not advanced in SE until grade 7)', () => {
+    const result = getUIModeWithDefaults({ assignment: { grade: 6 }, locale: Locale.SE, user: { grade: 1 } })
+    expect(result.toolbar).toBe(ToolBarVariants.SIMPLE)
+  })
+
+  it('grade 6 in SE with regular mode student → COMMON', () => {
+    const result = getUIModeWithDefaults({ assignment: { grade: 6 }, locale: Locale.SE, user: { grade: 6 } })
+    expect(result.toolbar).toBe(ToolBarVariants.COMMON)
+  })
+
+  it('grade 3 in US with simple mode student → SIMPLE', () => {
+    const result = getUIModeWithDefaults({ assignment: { grade: 3 }, locale: Locale.US, user: { grade: 1 } })
+    expect(result.toolbar).toBe(ToolBarVariants.SIMPLE)
+  })
+
+  it('grade 3 in US with regular mode student → COMMON', () => {
+    const result = getUIModeWithDefaults({ assignment: { grade: 3 }, locale: Locale.US, user: { grade: 3 } })
+    expect(result.toolbar).toBe(ToolBarVariants.COMMON)
+  })
+
+  it('no assignment grade falls back to practice grade 8 → ADVANCED', () => {
+    const result = getUIModeWithDefaults({
+      assignment: { grade: null },
+      practice: { isEnabled: true, grade: 8 },
+      locale: Locale.US,
+    })
+    expect(result.toolbar).toBe(ToolBarVariants.ADVANCED)
+  })
+
+  it('no grades at all with simple mode → SIMPLE', () => {
+    const result = getUIModeWithDefaults({
+      assignment: { grade: null },
+      practice: { isEnabled: true, grade: 1 },
+    })
+    expect(result.toolbar).toBe(ToolBarVariants.SIMPLE)
+  })
+
+  it('no grades at all with regular mode → COMMON', () => {
+    const result = getUIModeWithDefaults({
+      assignment: { grade: null },
+      practice: { isEnabled: false, grade: null },
+      user: { grade: 5 },
+    })
+    expect(result.toolbar).toBe(ToolBarVariants.COMMON)
+  })
+})
+
+describe('answer area is SIMPLE only in simple mode when practicing, has variants, or handwriting whole numbers', () => {
+  it('regular mode → always REGULAR regardless of other inputs', () => {
+    const result = getUIModeWithDefaults({
+      user: { grade: 5 },
+      practice: { isEnabled: true, grade: 5 },
+      problem: {
+        answerType: AnswerType.HANDWRITING,
+        characterType: MyScriptMathCharacterTypes.NUMBERS_WHOLE,
+        hasAnswerVariants: true,
+      },
+    })
+    expect(result.answerArea).toBe(UIMode.REGULAR)
+  })
+
+  it('simple mode + practice exercise → SIMPLE', () => {
+    const result = getUIModeWithDefaults({
+      practice: { isEnabled: true, grade: 1 },
+      problem: {
+        answerType: AnswerType.HANDWRITING,
+        characterType: MyScriptMathCharacterTypes.DEFAULT,
+        hasAnswerVariants: false,
+      },
+    })
+    expect(result.answerArea).toBe(UIMode.SIMPLE)
+  })
+
+  it('simple mode + answer variants → SIMPLE', () => {
+    const result = getUIModeWithDefaults({
+      user: { grade: 1 },
+      problem: {
+        answerType: AnswerType.HANDWRITING,
+        characterType: MyScriptMathCharacterTypes.DEFAULT,
+        hasAnswerVariants: true,
+      },
+    })
+    expect(result.answerArea).toBe(UIMode.SIMPLE)
+  })
+
+  it('simple mode + handwriting whole numbers → SIMPLE', () => {
+    const result = getUIModeWithDefaults({
+      user: { grade: 1 },
+      problem: {
+        answerType: AnswerType.HANDWRITING,
+        characterType: MyScriptMathCharacterTypes.NUMBERS_WHOLE,
+        hasAnswerVariants: false,
+      },
+    })
+    expect(result.answerArea).toBe(UIMode.SIMPLE)
+  })
+
+  it('simple mode + handwriting but not whole numbers → REGULAR', () => {
+    const result = getUIModeWithDefaults({
+      user: { grade: 1 },
+      problem: {
+        answerType: AnswerType.HANDWRITING,
+        characterType: MyScriptMathCharacterTypes.NUMBERS,
+        hasAnswerVariants: false,
+      },
+    })
+    expect(result.answerArea).toBe(UIMode.REGULAR)
+  })
+
+  it('simple mode + multiple choice even with whole numbers → REGULAR', () => {
+    const result = getUIModeWithDefaults({
+      user: { grade: 1 },
+      problem: {
+        answerType: AnswerType.MULTIPLE_CHOICE,
+        characterType: MyScriptMathCharacterTypes.NUMBERS_WHOLE,
+        hasAnswerVariants: false,
+      },
+    })
+    expect(result.answerArea).toBe(UIMode.REGULAR)
+  })
+
+  it('simple mode + no special conditions → REGULAR', () => {
+    const result = getUIModeWithDefaults({
+      user: { grade: 1 },
+      problem: {
+        answerType: AnswerType.SINGLE_CHOICE,
+        characterType: MyScriptMathCharacterTypes.DEFAULT,
+        hasAnswerVariants: false,
+      },
+    })
+    expect(result.answerArea).toBe(UIMode.REGULAR)
+  })
+})