@studyjoyful/shared 1.0.10 → 1.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studyjoyful/shared",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "Shared code for StudyJoyful Web and App (i18n, constants, types, utils)",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/i18n/locales/en/home.json

@@ -129,6 +129,8 @@
     "choosePhoto": "Choose from Gallery",
     "analyzing": "Analyzing...",
     "detected": "Detected",
+    "inScope": "Ready to practice",
+    "outOfScope": "Out of scope",
     "confidence": {
       "high": "High confidence",
       "medium": "Please verify",
@@ -138,7 +140,9 @@
     "tryAgain": "Try Again",
     "switchToChat": "Describe Instead",
     "advancedSettings": "Advanced Settings",
-    "generatePractice": "Generate Practice"
+    "generatePractice": "Generate Practice",
+    "browseTopics": "Browse Topics",
+    "tryInstead": "Try these topics instead:"
   }
 }
 

package/src/i18n/locales/en/sidebar.json

@@ -1,6 +1,8 @@
 {
   "menu": {
     "home": "StudyJoyful",
+    "scan": "Scan Homework",
+    "chat": "AI Chat",
     "tasks": "My Tasks",
     "admin": "Admin",
     "settings": "Settings"

package/src/index.ts

@@ -7,6 +7,7 @@
  * - i18n: Internationalization (translations, resources)
  * - constants: Shared constants (examples, etc.)
  * - types: Common type definitions
+ * - topics: Topic definitions with AI context
  * - utils: Utility functions
  */
 
@@ -41,5 +42,29 @@ export {
   type PaginationMeta,
 } from './types';
 
+// Topics exports
+export {
+  // Types
+  type TopicDefinition,
+  type TopicCategory,
+  type TopicIconName,
+  // Constants
+  ALL_TOPICS,
+  MATH_TOPICS,
+  ENGLISH_TOPICS,
+  ICON_MAP,
+  // Functions
+  getAllTopics,
+  getTopicById,
+  getTopicsBySubject,
+  getTopicsBySubjectAndGrade,
+  getPopularTopicsBySubject,
+  getPopularTopicsBySubjectAndGrade,
+  getTopicAIContext,
+  findTopicsByKeyword,
+  getSuggestedAlternatives,
+  getIconForPlatform,
+} from './topics';
+
 // Utils exports
 export { randomSelect, shuffle } from './utils';

package/src/topics/english-topics.ts

@@ -0,0 +1,120 @@
+/**
+ * English Topics
+ *
+ * English topics for P1-P3 based on Singapore MOE syllabus.
+ * aiContext provides concise topic description for AI generation.
+ * Grade-specific adaptation is handled by the API prompt.
+ */
+
+import type { TopicDefinition } from './types';
+
+/**
+ * All English topics
+ */
+export const ENGLISH_TOPICS: TopicDefinition[] = [
+  // ============================================
+  // Phonics & Sounds
+  // ============================================
+  {
+    id: 'english-phonics',
+    subject: 'English',
+    label: 'Phonics',
+    description: 'Letter sounds & blending',
+    aiContext: `Phonics practice focusing on letter-sound relationships, blending sounds to read words, and segmenting words for spelling.
+Question types: Match sounds to letters, blend sounds to read words, identify vowel sounds, rhyming words.`,
+    keywords: ['phonics', 'sounds', 'letters', 'blend', 'vowels', 'consonants', 'CVC', 'rhyme'],
+    gradeRange: ['P1', 'P2', 'P3'],
+    category: 'phonics',
+    iconName: 'music',
+  },
+
+  // ============================================
+  // Vocabulary
+  // ============================================
+  {
+    id: 'english-spelling',
+    subject: 'English',
+    label: 'Spelling',
+    description: 'Common words & patterns',
+    aiContext: `Spelling practice focusing on sight words, spelling patterns, and word families.
+Question types: Complete the spelling, correct misspelled words, fill in missing letters, word family exercises.`,
+    keywords: ['spelling', 'spell', 'words', 'sight words', 'patterns', 'letters'],
+    gradeRange: ['P1', 'P2', 'P3'],
+    category: 'vocabulary',
+    isPopular: true,
+    iconName: 'text',
+  },
+  {
+    id: 'english-vocabulary',
+    subject: 'English',
+    label: 'Vocabulary',
+    description: 'Word meanings & usage',
+    aiContext: `Vocabulary practice focusing on word meanings, usage in sentences, and categorizing words.
+Question types: Match word to meaning, use word in sentence, find synonyms/antonyms, complete sentences with correct word.`,
+    keywords: ['vocabulary', 'words', 'meanings', 'synonyms', 'antonyms', 'definition'],
+    gradeRange: ['P1', 'P2', 'P3'],
+    category: 'vocabulary',
+    isPopular: true,
+    iconName: 'book',
+  },
+
+  // ============================================
+  // Grammar
+  // ============================================
+  {
+    id: 'english-grammar',
+    subject: 'English',
+    label: 'Grammar',
+    description: 'Sentence structure & rules',
+    aiContext: `Grammar practice focusing on parts of speech (nouns, verbs, adjectives), sentence structure, and correct usage.
+Question types: Identify parts of speech, fill in correct word form, correct the sentence, complete sentences.`,
+    keywords: ['grammar', 'nouns', 'verbs', 'adjectives', 'sentences', 'tenses', 'pronouns'],
+    gradeRange: ['P1', 'P2', 'P3'],
+    category: 'grammar',
+    isPopular: true,
+    iconName: 'list',
+  },
+  {
+    id: 'english-punctuation',
+    subject: 'English',
+    label: 'Punctuation',
+    description: 'Periods, commas & capitals',
+    aiContext: `Punctuation practice focusing on end punctuation, capital letters, and basic comma usage.
+Question types: Add correct punctuation, correct the punctuation, identify punctuation marks, rewrite with correct punctuation.`,
+    keywords: ['punctuation', 'period', 'comma', 'capital', 'question mark', 'apostrophe', 'exclamation'],
+    gradeRange: ['P1', 'P2', 'P3'],
+    category: 'punctuation',
+    iconName: 'code',
+  },
+
+  // ============================================
+  // Reading
+  // ============================================
+  {
+    id: 'english-reading',
+    subject: 'English',
+    label: 'Reading Comprehension',
+    description: 'Understanding texts',
+    aiContext: `Reading comprehension practice with age-appropriate passages about school, family, animals, and everyday life.
+Question types: Multiple choice comprehension, true/false, short answer questions, sequencing events.
+Focus: Understanding main idea, finding information, making connections.`,
+    keywords: ['reading', 'comprehension', 'passage', 'understand', 'main idea', 'inference'],
+    gradeRange: ['P1', 'P2', 'P3'],
+    category: 'reading',
+    iconName: 'book',
+  },
+];
+
+/**
+ * Get English topics filtered by grade
+ */
+export function getEnglishTopicsByGrade(grade: 'P1' | 'P2' | 'P3'): TopicDefinition[] {
+  return ENGLISH_TOPICS.filter((topic) => topic.gradeRange.includes(grade));
+}
+
+/**
+ * Get popular English topics
+ */
+export function getPopularEnglishTopics(): TopicDefinition[] {
+  return ENGLISH_TOPICS.filter((topic) => topic.isPopular);
+}

package/src/topics/index.ts

@@ -0,0 +1,139 @@
+/**
+ * Topics Module
+ *
+ * Unified topic definitions for StudyJoyful.
+ * Based on Singapore MOE (Ministry of Education) syllabus for P1-P3.
+ *
+ * Usage:
+ * ```ts
+ * import { getAllTopics, getTopicById, getTopicsBySubject } from '@studyjoyful/shared';
+ *
+ * // Get all topics
+ * const topics = getAllTopics();
+ *
+ * // Get topics by subject
+ * const mathTopics = getTopicsBySubject('Math');
+ *
+ * // Get topic by ID
+ * const addition = getTopicById('math-addition');
+ *
+ * // Get AI context for a topic
+ * const context = getTopicAIContext('math-addition');
+ * ```
+ */
+
+import type { ChildGrade, Subject } from '../types/child';
+import { ENGLISH_TOPICS, getEnglishTopicsByGrade, getPopularEnglishTopics } from './english-topics';
+import { MATH_TOPICS, getMathTopicsByGrade, getPopularMathTopics } from './math-topics';
+import type { TopicCategory, TopicDefinition, TopicIconName } from './types';
+import { getIconForPlatform, ICON_MAP } from './types';
+
+// Re-export types
+export type { TopicCategory, TopicDefinition, TopicIconName };
+export { ICON_MAP, getIconForPlatform };
+
+// Re-export topic arrays
+export { ENGLISH_TOPICS, MATH_TOPICS };
+
+/**
+ * All topics combined
+ */
+export const ALL_TOPICS: TopicDefinition[] = [...MATH_TOPICS, ...ENGLISH_TOPICS];
+
+/**
+ * Get all topics
+ */
+export function getAllTopics(): TopicDefinition[] {
+  return ALL_TOPICS;
+}
+
+/**
+ * Get topic by ID
+ */
+export function getTopicById(id: string): TopicDefinition | undefined {
+  return ALL_TOPICS.find((topic) => topic.id === id);
+}
+
+/**
+ * Get topics by subject
+ */
+export function getTopicsBySubject(subject: Subject): TopicDefinition[] {
+  return subject === 'Math' ? MATH_TOPICS : ENGLISH_TOPICS;
+}
+
+/**
+ * Get topics by subject and grade
+ */
+export function getTopicsBySubjectAndGrade(subject: Subject, grade: ChildGrade): TopicDefinition[] {
+  return subject === 'Math' ? getMathTopicsByGrade(grade) : getEnglishTopicsByGrade(grade);
+}
+
+/**
+ * Get popular topics by subject
+ */
+export function getPopularTopicsBySubject(subject: Subject): TopicDefinition[] {
+  return subject === 'Math' ? getPopularMathTopics() : getPopularEnglishTopics();
+}
+
+/**
+ * Get popular topics by subject and grade
+ */
+export function getPopularTopicsBySubjectAndGrade(subject: Subject, grade: ChildGrade): TopicDefinition[] {
+  const topics = getTopicsBySubjectAndGrade(subject, grade);
+  return topics.filter((topic) => topic.isPopular);
+}
+
+/**
+ * Get AI context for a topic
+ *
+ * @param topicId - Topic ID or label
+ * @returns Formatted context string for AI (grade adaptation handled by API prompt)
+ */
+export function getTopicAIContext(topicId: string): string {
+  // Try to find by ID first
+  let topic = getTopicById(topicId);
+
+  // If not found, try to match by label (case-insensitive)
+  if (!topic) {
+    const lowerTopicId = topicId.toLowerCase();
+    topic = ALL_TOPICS.find(
+      (t) =>
+        t.label.toLowerCase() === lowerTopicId ||
+        t.id.toLowerCase().includes(lowerTopicId) ||
+        t.keywords.some((k) => k.toLowerCase() === lowerTopicId)
+    );
+  }
+
+  if (!topic) {
+    return `Topic: ${topicId}`;
+  }
+
+  return `Topic: ${topic.label}
+Subject: ${topic.subject}
+${topic.aiContext}`;
+}
+
+/**
+ * Find topics matching keywords
+ */
+export function findTopicsByKeyword(keyword: string, subject?: Subject): TopicDefinition[] {
+  const lowerKeyword = keyword.toLowerCase();
+  const topics = subject ? getTopicsBySubject(subject) : ALL_TOPICS;
+
+  return topics.filter(
+    (topic) =>
+      topic.label.toLowerCase().includes(lowerKeyword) ||
+      topic.description.toLowerCase().includes(lowerKeyword) ||
+      topic.keywords.some((k) => k.toLowerCase().includes(lowerKeyword))
+  );
+}
+
+/**
+ * Get suggested topics for out-of-scope content
+ */
+export function getSuggestedAlternatives(subject: Subject, grade: ChildGrade, count: number = 3): string[] {
+  const popularTopics = getPopularTopicsBySubjectAndGrade(subject, grade);
+  const topics = popularTopics.length > 0 ? popularTopics : getTopicsBySubjectAndGrade(subject, grade);
+  return topics.slice(0, count).map((t) => t.label);
+}
+

package/src/topics/math-topics.ts

@@ -0,0 +1,172 @@
+/**
+ * Math Topics
+ *
+ * Math topics for P1-P3 based on Singapore MOE syllabus.
+ * aiContext provides concise topic description for AI generation.
+ * Grade-specific adaptation is handled by the API prompt.
+ */
+
+import type { TopicDefinition } from './types';
+
+/**
+ * All Math topics
+ */
+export const MATH_TOPICS: TopicDefinition[] = [
+  // ============================================
+  // Arithmetic
+  // ============================================
+  {
+    id: 'math-addition',
+    subject: 'Math',
+    label: 'Addition',
+    description: 'With & without carrying',
+    aiContext: `Addition practice focusing on number bonds, place value, and step-by-step regrouping (carrying).
+Question types: Fill in blanks, find the sum, word problems with "altogether", "total", "in all".`,
+    keywords: ['add', 'plus', 'sum', 'total', 'altogether', 'carrying', 'regrouping', 'number bonds'],
+    gradeRange: ['P1', 'P2', 'P3'],
+    category: 'arithmetic',
+    isPopular: true,
+    iconName: 'add',
+  },
+  {
+    id: 'math-subtraction',
+    subject: 'Math',
+    label: 'Subtraction',
+    description: 'With & without borrowing',
+    aiContext: `Subtraction practice focusing on relationship with addition, place value, and step-by-step borrowing (regrouping).
+Question types: Find the difference, how many more/fewer, word problems with "left", "remaining", "gave away".`,
+    keywords: ['subtract', 'minus', 'difference', 'left', 'remaining', 'borrowing', 'regrouping', 'take away'],
+    gradeRange: ['P1', 'P2', 'P3'],
+    category: 'arithmetic',
+    isPopular: true,
+    iconName: 'subtract',
+  },
+  {
+    id: 'math-multiplication',
+    subject: 'Math',
+    label: 'Multiplication',
+    description: 'Times tables & word problems',
+    aiContext: `Multiplication practice focusing on equal groups, arrays, times tables, and relationship with repeated addition.
+Question types: Times tables practice, array problems, "groups of", word problems with equal sharing/grouping.`,
+    keywords: ['multiply', 'times', 'product', 'groups of', 'times tables', 'arrays', 'repeated addition'],
+    gradeRange: ['P2', 'P3'],
+    category: 'arithmetic',
+    isPopular: true,
+    iconName: 'multiply',
+  },
+  {
+    id: 'math-division',
+    subject: 'Math',
+    label: 'Division',
+    description: 'Equal sharing & grouping',
+    aiContext: `Division practice focusing on equal sharing, grouping, and inverse relationship with multiplication.
+Question types: Share equally, how many groups, word problems with "each", "equally divided".`,
+    keywords: ['divide', 'share', 'equally', 'groups', 'quotient', 'remainder', 'each'],
+    gradeRange: ['P2', 'P3'],
+    category: 'arithmetic',
+    iconName: 'divide',
+  },
+
+  // ============================================
+  // Fractions
+  // ============================================
+  {
+    id: 'math-fractions',
+    subject: 'Math',
+    label: 'Fractions',
+    description: 'Halves, quarters, thirds',
+    aiContext: `Fractions practice focusing on equal parts, visual models (circles, rectangles), and relating to everyday objects.
+Question types: Shade fractions, identify fractions, compare fractions, word problems with sharing.`,
+    keywords: ['fraction', 'half', 'quarter', 'third', 'parts', 'whole', 'numerator', 'denominator'],
+    gradeRange: ['P2', 'P3'],
+    category: 'fractions',
+    iconName: 'fraction',
+  },
+
+  // ============================================
+  // Geometry
+  // ============================================
+  {
+    id: 'math-shapes',
+    subject: 'Math',
+    label: 'Shapes',
+    description: '2D and 3D shapes',
+    aiContext: `Shapes practice focusing on 2D shapes (circle, triangle, square, rectangle) and 3D shapes (cube, cuboid, cone, cylinder).
+Question types: Identify shapes, count sides/corners, match shapes to objects, spot shapes in pictures.`,
+    keywords: ['shapes', 'circle', 'triangle', 'square', 'rectangle', 'sides', 'corners', '3D', 'cube'],
+    gradeRange: ['P1', 'P2', 'P3'],
+    category: 'geometry',
+    iconName: 'shapes',
+  },
+
+  // ============================================
+  // Measurement
+  // ============================================
+  {
+    id: 'math-time',
+    subject: 'Math',
+    label: 'Time',
+    description: 'Telling time & duration',
+    aiContext: `Time practice focusing on analog clock reading, digital time, duration, and connecting to daily routines.
+Question types: What time is it?, Draw hands on clock, calculate duration, sequence events.`,
+    keywords: ['time', 'clock', "o'clock", 'half past', 'quarter', 'minutes', 'hours', 'duration'],
+    gradeRange: ['P1', 'P2', 'P3'],
+    category: 'measurement',
+    iconName: 'time',
+  },
+  {
+    id: 'math-money',
+    subject: 'Math',
+    label: 'Money',
+    description: 'Counting & calculating',
+    aiContext: `Money practice using Singapore currency (dollars and cents), focusing on counting, adding, and making change.
+Question types: Count the money, find total cost, calculate change, shopping word problems.`,
+    keywords: ['money', 'cents', 'dollars', 'coins', 'change', 'cost', 'price', 'buy', 'pay'],
+    gradeRange: ['P1', 'P2', 'P3'],
+    category: 'measurement',
+    iconName: 'money',
+  },
+  {
+    id: 'math-measurement',
+    subject: 'Math',
+    label: 'Measurement',
+    description: 'Length, mass, volume',
+    aiContext: `Measurement practice focusing on length (cm, m), mass (g, kg), volume (ml, L), estimation, and appropriate units.
+Question types: Compare lengths, measure and record, convert units, word problems with measurement.`,
+    keywords: ['length', 'mass', 'volume', 'centimeter', 'meter', 'kilogram', 'gram', 'liter', 'measure'],
+    gradeRange: ['P1', 'P2', 'P3'],
+    category: 'measurement',
+    iconName: 'ruler',
+  },
+
+  // ============================================
+  // Problem Solving
+  // ============================================
+  {
+    id: 'math-word-problems',
+    subject: 'Math',
+    label: 'Word Problems',
+    description: 'Mixed operations & reasoning',
+    aiContext: `Word problems practice using Singapore Math bar model / model drawing method for visualization.
+Question types: One-step, two-step, comparison ("more than", "fewer than"), part-whole problems.
+Focus: Understanding the question, identifying operation, showing working, checking answer.`,
+    keywords: ['word problem', 'story problem', 'solve', 'altogether', 'remaining', 'how many', 'model drawing'],
+    gradeRange: ['P1', 'P2', 'P3'],
+    category: 'problem-solving',
+    iconName: 'document',
+  },
+];
+
+/**
+ * Get Math topics filtered by grade
+ */
+export function getMathTopicsByGrade(grade: 'P1' | 'P2' | 'P3'): TopicDefinition[] {
+  return MATH_TOPICS.filter((topic) => topic.gradeRange.includes(grade));
+}
+
+/**
+ * Get popular Math topics
+ */
+export function getPopularMathTopics(): TopicDefinition[] {
+  return MATH_TOPICS.filter((topic) => topic.isPopular);
+}

package/src/topics/types.ts

@@ -0,0 +1,143 @@
+/**
+ * Topics Types
+ *
+ * Type definitions for topic data used across Web and App.
+ * Topics are based on Singapore MOE (Ministry of Education) syllabus.
+ */
+
+import type { ChildGrade, Subject } from '../types/child';
+
+/**
+ * Topic definition with rich context for AI
+ */
+export interface TopicDefinition {
+  /** Unique identifier: 'math-addition', 'english-spelling' */
+  id: string;
+
+  /** Subject: Math or English */
+  subject: Subject;
+
+  /** Display label: 'Addition' */
+  label: string;
+
+  /** Short description for UI: 'With & without carrying' */
+  description: string;
+
+  /**
+   * Rich context for AI generation
+   * Should include:
+   * - What the topic covers
+   * - Grade-specific variations
+   * - Common question types
+   */
+  aiContext: string;
+
+  /** Related keywords for matching */
+  keywords: string[];
+
+  /** Applicable grades */
+  gradeRange: ChildGrade[];
+
+  /** Topic category for grouping */
+  category: TopicCategory;
+
+  /** Whether this is a popular/recommended topic */
+  isPopular?: boolean;
+
+  /** Icon name (platform-agnostic) */
+  iconName: TopicIconName;
+}
+
+/**
+ * Topic categories
+ */
+export type TopicCategory =
+  // Math categories
+  | 'arithmetic'      // +, -, ×, ÷
+  | 'numbers'         // Number sense, place value
+  | 'fractions'       // Fractions, decimals
+  | 'geometry'        // Shapes, angles
+  | 'measurement'     // Length, mass, volume, time
+  | 'data'            // Graphs, charts
+  | 'problem-solving' // Word problems
+  // English categories
+  | 'phonics'         // Letter sounds, blending
+  | 'vocabulary'      // Words, meanings
+  | 'grammar'         // Parts of speech, sentences
+  | 'reading'         // Comprehension
+  | 'writing'         // Composition, sentences
+  | 'punctuation';    // Punctuation marks
+
+/**
+ * Platform-agnostic icon names
+ * Maps to:
+ * - Ionicons (App): add-outline, remove-outline, etc.
+ * - Lucide (Web): Plus, Minus, etc.
+ */
+export type TopicIconName =
+  | 'add'
+  | 'subtract'
+  | 'multiply'
+  | 'divide'
+  | 'fraction'
+  | 'shapes'
+  | 'time'
+  | 'money'
+  | 'ruler'
+  | 'document'
+  | 'text'
+  | 'book'
+  | 'list'
+  | 'music'
+  | 'code';
+
+/**
+ * Icon mappings for different platforms
+ */
+export const ICON_MAP = {
+  ionicons: {
+    add: 'add-outline',
+    subtract: 'remove-outline',
+    multiply: 'close-outline',
+    divide: 'git-compare-outline',
+    fraction: 'pie-chart-outline',
+    shapes: 'shapes-outline',
+    time: 'time-outline',
+    money: 'cash-outline',
+    ruler: 'resize-outline',
+    document: 'document-text-outline',
+    text: 'text-outline',
+    book: 'book-outline',
+    list: 'list-outline',
+    music: 'musical-notes-outline',
+    code: 'code-outline',
+  },
+  lucide: {
+    add: 'Plus',
+    subtract: 'Minus',
+    multiply: 'X',
+    divide: 'Divide',
+    fraction: 'PieChart',
+    shapes: 'Shapes',
+    time: 'Clock',
+    money: 'Coins',
+    ruler: 'Ruler',
+    document: 'FileText',
+    text: 'Type',
+    book: 'BookOpen',
+    list: 'List',
+    music: 'Music',
+    code: 'Code',
+  },
+} as const;
+
+/**
+ * Get icon name for a specific platform
+ */
+export function getIconForPlatform(
+  iconName: TopicIconName,
+  platform: 'ionicons' | 'lucide'
+): string {
+  return ICON_MAP[platform][iconName];
+}
+