@cuemath/leap

A comprehensive React component library for educational applications, providing UI components, features, and utilities specifically designed for math education platforms. Supports both web (React DOM) and React Native (via Expo) platforms.

✨ Features

• 🎯 Educational Components - Interactive worksheets, games, puzzles, and learning activities
• 📊 Analytics Integration - Built-in tracking for educational events and user interactions
• 🎨 Consistent Design System - Cohesive UI components with educational themes
• 📱 Cross-Platform - Web and React Native support with platform-specific implementations
• 🔧 Developer Experience - TypeScript support, Storybook (web) and Expo preview (native) documentation
• ⚡ Performance Optimized - Tree-shakable exports and efficient bundle sizes

📦 Installation

Prerequisites

This package requires authentication to access Cuemath's private npm registry.

echo "npmAuthToken: ${AUTH_TOKEN}" > ~/.yarnrc.yml

Install the package

# Using yarn (recommended)
yarn add @cuemath/leap

Peer Dependencies

Web

yarn add react@^19.1.0 react-dom@^19.1.0 styled-components@^6.0.0 fast-equals@^5.0.1

React Native

yarn add [email protected] [email protected] [email protected] [email protected]

The package exposes a react-native entry point (dist/index.native.js) that Metro resolves automatically.

Font Setup (Web)

Add the required fonts to your HTML head:

<link rel="preconnect" href="https://fonts.gstatic.com" />
<link
  rel="preload"
  href="https://fonts.googleapis.com/css?family=Noto+Serif:400,400i,700"
  as="style"
  onload="this.onload=null;this.rel='stylesheet'"
/>
<noscript
  ><link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Noto+Serif:400,400i,700"
/></noscript>

🛠️ Development

Getting Started

# Clone and install dependencies
yarn install

# Start Storybook development server (web)
yarn start
# Opens http://localhost:6006

# Start Expo preview app (React Native)
yarn expo        # Start Expo dev server
yarn ios         # Start on iOS simulator
yarn android     # Start on Android emulator

# Run TypeScript compiler in watch mode
yarn ts-watch

Available Scripts

Build & Development

• yarn start - Prepare hooks and start Storybook on port 6006
• yarn build - Clean build for distribution using Vite
• yarn buildwatch - Build in watch mode for development
• yarn preview - Preview the built library
• yarn build:native - Build native (React Native) distribution files

Code Quality

• yarn lint - Full validation (TypeScript + ESLint) - run before committing
• yarn ts - TypeScript compilation check only
• yarn ts-watch - TypeScript in watch mode
• yarn eslint - ESLint with quiet output and cache
• yarn eslint:fix - ESLint with auto-fix enabled

Fast Development Workflow

• yarn eslint [files] - Lint specific files with cache
• yarn eslint [files] --fix - Lint and auto-fix specific files
• tsc --noEmit - Fast TypeScript validation only

Storybook (Web)

• yarn build-storybook - Build static Storybook for deployment

React Native / Expo Preview

• yarn expo - Start Expo dev server for native component preview
• yarn ios - Start Expo on iOS simulator
• yarn android - Start Expo on Android emulator

Development Workflow

1. Active Development: Use yarn eslint [files] --fix for instant feedback
2. Type Checking: Run yarn tsc --noEmit to catch type errors quickly
3. Before Committing: Always run yarn lint for full validation
4. Web Component Development: Use Storybook for testing and documentation
5. Native Component Development: Use yarn expo / yarn ios to preview native components

🏗️ Architecture

Project Structure

The codebase follows a feature-based architecture:

src/
├── features/           # Feature-based components
│   ├── ui/            # Reusable UI components
│   ├── worksheet/     # Learnosity integration
│   ├── games/         # Educational games
│   ├── puzzles/       # Puzzle components
│   ├── auth/          # Authentication flows
│   ├── analytics-events/ # Event tracking
│   └── hooks/         # Custom React hooks
├── assets/            # Static assets (images, icons, fonts)
├── constants/         # Global constants
└── types/             # TypeScript type definitions

Key Patterns

Barrel Exports

Each feature directory contains a barrel.ts file that re-exports all public APIs. Native has separate barrel files:

// features/ui/barrel.ts        → Web exports
// features/ui/barrel.native.ts → React Native exports
// src/barrel.native.ts         → Root native barrel

Component Structure

Web components:

component-name/
├── component-name.tsx           # Main component
├── component-name-types.ts      # TypeScript interfaces
├── component-name-styled.tsx    # Styled components
└── component-name.stories.tsx   # Storybook stories

Native components (colocated with web):

component-name/
├── component-name.tsx               # Web implementation
├── component-name.native.tsx        # React Native implementation
├── component-name-types.ts          # Web types
├── component-name-types.native.ts   # Native-specific types
├── component-name.stories.tsx       # Storybook stories (web)
└── component-name.native.stories.ts # Native stories (Expo preview)

Import Patterns

• Use relative paths within the same feature
• Use barrel exports when importing from other features
• Follow ESLint import ordering (builtin → internal → relative)
• Metro automatically resolves .native.tsx files for React Native builds

🎨 Component Development

Creating New Components

Web Components

1. Follow Existing Patterns - Check similar components for conventions
2. TypeScript First - Define interfaces in separate -types.ts files
3. Styled Components - Use transient props only ($prop)
4. Storybook Stories - Create comprehensive stories for all states
5. Barrel Exports - Export from feature's barrel.ts

Native Components

1. Colocate with web - Place .native.tsx files alongside web counterparts
2. Separate native types - Use *-types.native.ts files; extend from web types via Pick
3. Use styled-components/native - Import styled from styled-components/native
4. Theme via useTheme() - Access INativeTheme for colors, text, layout config
5. Native stories - Create .native.stories.ts using INativeStoryMeta/INativeStory types
6. Register stories - Add to expo-preview/story-registry.ts (Metro cannot do dynamic requires)
7. Barrel exports - Export from feature's barrel.native.ts

Naming Conventions

// Interfaces: I prefix
export interface IComponentProps {
  variant: 'primary' | 'secondary';
  size: 'small' | 'medium' | 'large';
}

// Native interfaces: I prefix with Native
export interface INativeComponentProps {
  variant: 'primary' | 'secondary';
}

// Types: T prefix
export type TComponentResult = ISuccess | IError;

// Enums: Avoided - use union types instead
export type TComponentState = 'LOADING' | 'SUCCESS' | 'ERROR';

Hook Development

Define hook interfaces as function signatures:

// ✅ Correct
interface IUseCustomHook {
  (): { data: string; loading: boolean };
}

interface IUseCustomHookWithParams {
  (params: { id: string }): () => void;
}

🧪 Testing & Quality

Code Quality Standards

• ESLint Configuration - Extends @cuemath/eslint-config
• TypeScript Strict Mode - Full type safety enforced
• Import Organization - Automatic sorting and grouping
• No React Imports - Uses automatic JSX runtime (React 19)

Component Testing

Web components are tested through comprehensive Storybook stories covering:

• Default state
• All prop variations
• Edge cases
• Error states
• Loading states

Native components are tested through the Expo preview app:

• Stories use INativeStoryMeta and INativeStory types from expo-preview/native-story-types.ts
• Register stories in expo-preview/story-registry.ts
• Run with yarn expo / yarn ios / yarn android

Performance Guidelines

• Use memo() for expensive components
• Implement proper dependency arrays in hooks
• Avoid inline object/function creation in render
• Optimize bundle size with tree-shaking

🛠️ Technology Stack

• React 19 - Latest React with automatic JSX runtime
• React Native + Expo - Cross-platform native support
• TypeScript 5.9 - Full type safety and modern language features
• Styled Components 6.0 - CSS-in-JS styling (web: styled-components, native: styled-components/native)
• Vite - Fast build tool and development server (web)
• Metro - React Native bundler (resolves .native extensions automatically)
• Storybook 8 - Web component development and documentation
• Expo Preview App - Native component development and preview
• ESLint + Prettier - Code quality and formatting
• Yarn 4 - Modern package manager with PnP

Dependencies

Core Dependencies

• @cuemath/analytics-v2 - Analytics tracking system
• date-fns - Date manipulation utilities
• lodash utilities - Debounce, throttle, isEqual
• query-string - URL query parameter handling
• react-datepicker - Date picker components

Development Tools

• Learnosity integration for educational content
• Google Maps integration for location features
• Lottie animations for engaging interactions
• Sentry for error tracking and monitoring

📱 React Native Support

Native Components

The library provides React Native implementations for core UI components:

| Component | Web | Native | | --------------- | ---------------------- | ----------------------------- | | Button | button.tsx | button.native.tsx | | IconButton | icon-button.tsx | icon-button.native.tsx | | TextButton | text-button.tsx | text-button.native.tsx | | Text | text.tsx | text.native.tsx | | Image | image.tsx | image.native.tsx | | RemoteImage | remote-image.tsx | remote-image.native.tsx | | Pressable | pressable.tsx | pressable.native.tsx | | FlexView | flex-view.tsx | flex-view.native.tsx | | Separator | separator.tsx | separator.native.tsx | | DelayedRenderer | delayed-renderer.tsx | delayed-renderer.native.tsx |

Native Theme System

Native components use INativeTheme accessed via useTheme():

interface INativeTheme {
  LAYOUT: { GUTTER: number; PIXEL_RATIO: 1 | 2 | 3 };
  CLRS: Record<TColorNames, string>;
  TXT: Record<TTextVariants, ITextConfig>;
  TEXT_BUTTON: ReturnType<typeof getTextButtonConfig>;
  BUTTON: ReturnType<typeof getButtonConfig>;
}

Expo Preview App

The expo-preview/ directory contains a standalone Expo app for native component development:

• App.tsx - Main app with ThemeProvider and StoryViewer
• theme.ts - Native theme configuration
• story-registry.ts - Manual registry of all .native.stories files
• story-viewer.tsx - Component to render and navigate native stories

Native Build

yarn build:native   # Compiles native entry point to dist/index.native.js

🤖 Claude Skills

/landing-page — Landing Page Builder

Creates, clones, or modifies signup-onboarding landing page variants. No coding required — Claude handles all code generation, lint checks, visual QA, and PR creation.

To use: type /landing-page in Claude Code.

What you need:

• A slug for the variant (e.g. google-sem-india)
• A Notion spec page with content for each section
• Images as Notion uploads or direct URLs

Available folds: ParentReviews · ClassComparison · InteractivePlatform · ParentTransparency · FaqSection · MathfitCards · AchieversCarousel · FeatureHighlightCards · FaqWithOverview

See .claude/skills/landing-page/SKILL.md for the full spec and Notion content template.

📚 Documentation

• Storybook - Interactive web component documentation
• Expo Preview (yarn expo) - Native component preview
• CLAUDE.md - AI assistant instructions and project context
• GUIDELINES.MD - Coding standards and conventions

🤝 Contributing

Before You Start

1. Read the Guidelines - Check GUIDELINES.MD for coding standards
2. Set Up Environment - Install dependencies and verify development setup
3. Run Quality Checks - Ensure yarn lint passes before any commits

Development Process

1. Create Feature Branch - Branch from master
2. Develop with Storybook - Use Storybook for web component development
3. Develop with Expo - Use yarn expo for native component development
4. Write Comprehensive Stories - Cover all component states (web .stories.tsx, native .native.stories.ts)
5. Run Full Lint - Execute yarn lint before committing
6. Create Pull Request - Target the master branch

Code Quality Requirements

• All TypeScript errors must be resolved
• ESLint validation must pass with zero warnings
• Components must have Storybook stories
• Follow established naming and file structure conventions
• Include proper error handling and loading states

🐛 Troubleshooting

Common Issues

Google Places Search not working

• Run on local.cuemath.com:PORT instead of localhost:PORT

Worksheet stories failing

• Use local-teacher.cuemath.com:PORT for worksheet components
• Update security object configuration if needed

Build or Type Errors

• Run yarn ts to check TypeScript compilation
• Clear .eslintcache if seeing stale linting errors
• Verify all peer dependencies are installed correctly

Storybook Issues

• Check browser console for detailed error messages
• Ensure all required fonts and assets are loaded
• Verify Storybook configuration in .storybook/ directory

Getting Help

1. Check Documentation - Review Storybook stories and code comments
2. Search Issues - Look for similar problems in project history
3. Ask Team - Reach out to the Cuemath development team
4. Create Issue - Document new bugs with reproduction steps

📄 License

Private package - © 2024 Cuemath. All rights reserved.