);
};
```
### Advanced Features
- **Spring Animations**: React-Spring powered smooth transitions
- **Gesture Support**: Drag and touch interactions with @use-gesture/react
- **Real-time Updates**: Live value synchronization
- **Event Handling**: Comprehensive bead interaction callbacks
- **Hook-based API**: Reusable state and dimension management
## 🛠️ Typst Template System
### Main Template (flashcards.typ)
```typst
#let draw-soroban(
value,
columns: auto,
show-empty: false,
hide-inactive: false,
bead-shape: "diamond",
color-scheme: "monochrome",
color-palette: "default",
base-size: 1.0,
show-crop-marks: false,
crop-margin: 10pt
) = {
// Parse value into digits
let digits = str(value).clusters().map(d => int(d))
// Calculate dimensions
let rod-width = 3pt * base-size
let bead-size = 12pt * base-size
let column-spacing = 25pt * base-size
let heaven-earth-gap = 30pt * base-size
// Color palette definitions (colorblind-friendly)
let color-palettes = (
"default": (
rgb("#2E86AB"), // ones - blue
rgb("#A23B72"), // tens - magenta
rgb("#F18F01"), // hundreds - orange
rgb("#6A994E"), // thousands - green
rgb("#BC4B51"), // ten-thousands - red
),
"colorblind": ( /* ... */ ),
"mnemonic": ( /* ... */ )
)
// Render abacus with specified configuration...
}
```
### Bead Shape Variants
```typst
// Diamond beads (default)
polygon((0pt, bead-size/2), (bead-size/2, 0pt), (0pt, -bead-size/2), (-bead-size/2, 0pt))
// Circle beads
circle(radius: bead-size/2)
// Square beads
rect(width: bead-size, height: bead-size)
```
### Color Scheme Options
- **`monochrome`**: Single color (black/gray)
- **`place-value`**: Each column gets distinct color
- **`heaven-earth`**: Heaven beads vs. earth beads
- **`alternating`**: Alternating pattern across columns
## 🔧 SVG Post-Processing
### Crop Mark Analysis
```javascript
// svg-crop-processor.js
function extractCropMarks(svgPath) {
const svgContent = fs.readFileSync(svgPath, "utf8");
// Parse SVG and find crop mark elements
const cropMarks = {
left: null,
right: null,
top: null,
bottom: null,
};
// Analyze with transform accumulation
const result = analyzeCropMarksWithTransforms(svgContent);
if (result.complete) {
const viewBox = `${result.left} ${result.top} ${result.width} ${result.height}`;
console.log(`📏 Calculated viewBox: "${viewBox}"`);
return { viewBox, ...result };
}
return null;
}
```
### Smart ViewBox Optimization
- Automatically detects crop mark positions
- Handles complex SVG coordinate transformations
- Calculates optimal viewBox for content
- Generates before/after comparisons
## 📊 Development Tools
### Storybook Integration
```bash
# Run Storybook for component development
cd packages/templates
npm run storybook # http://localhost:6007
# Build static Storybook
npm run build-storybook
```
### Testing & Validation
```bash
# Run all tests
npm test
# Individual test suites
npm run test:node # Node.js functionality
npm run test:python # Python integration
npm run test:validate # Template validation
npm run test:integration # End-to-end tests
```
### CI/CD Support
```bash
# Continuous integration test
./ci-test.sh
# Watch mode for development
npm run test:watch
```
## 🎯 Integration Examples
### Node.js Integration
```javascript
const { FLASHCARDS_TEMPLATE, processSVG } = require("@soroban/templates");
const fs = require("fs");
// Use template in Node.js application
const templateContent = fs.readFileSync(FLASHCARDS_TEMPLATE, "utf-8");
// Process generated SVG
const processedSVG = processSVG(svgContent, {
cropMarks: true,
optimize: true,
});
```
### Web App Integration
```typescript
// TypeScript support with full type definitions
import { getTemplatePath, processSVGFile } from "@soroban/templates";
const flashcardsPath = getTemplatePath("flashcards.typ");
const result = await processSVGFile("./output.svg", {
extractCropMarks: true,
generateComparison: true,
});
```
## 🚀 Performance Features
### Optimized HTML Generation
- **Inline SVGs**: Eliminates network requests
- **Efficient bundling**: Minimal dependencies
- **Responsive images**: Automatic scaling
- **Progressive enhancement**: Works without JavaScript
### Smart Caching
- **Template compilation**: Cached Typst outputs
- **SVG processing**: Incremental regeneration
- **Gallery building**: Only rebuilds changed content
## 🎨 Customization Guide
### Adding New Examples
```javascript
// In generate-gallery.js or build-unified-gallery.js
const newExample = {
id: "custom-789",
title: "Custom Configuration",
description: "Demonstrates custom styling options",
number: 789,
category: "basic", // 'basic' | 'crop' | 'debug'
config: {
bead_shape: "circle",
color_scheme: "heaven-earth",
base_size: 1.5,
hide_inactive: true,
show_crop_marks: false,
},
};
```
### Custom CSS Styling
```css
/* Override gallery styles */
.example-card {
border-radius: 12px;
box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1);
transition: transform 0.3s ease;
}
.example-card:hover {
transform: translateY(-4px);
}
.card-content svg {
max-width: 100%;
height: auto;
}
```
### Extending React Components
```tsx
// Custom abacus wrapper with additional features
const EnhancedAbacus: React.FC = (props) => {
const [history, setHistory] = useState([]);
const handleValueChange = (newValue: number) => {
setHistory((prev) => [...prev, newValue]);
props.onValueChange?.(newValue);
};
return (
{history.map((value, i) => (
{value}
))}
);
};
```
## 🏗️ Build System Architecture
### Multi-Stage Pipeline
1. **Template Processing**: Typst → SVG compilation
2. **SVG Enhancement**: Crop analysis and optimization
3. **Gallery Assembly**: HTML generation with embedded assets
4. **Interactive Layer**: React component integration
5. **Documentation**: Storybook and example generation
### Cross-Platform Support
- **Node.js**: Server-side generation
- **Browser**: Client-side interactivity
- **Python**: Template system integration
- **TypeScript**: Full type safety
## 📋 HTML Generation Components
### Complete HTML Output System
The packages/templates system generates **multiple HTML outputs**, not a single "flashcards.html" file:
#### **Primary HTML Generators**
1. **`build-unified-gallery.js`** → **`gallery-unified.html`**
- **Main gallery system** with tabbed interface (Basic/Crop Tools/Debug)
- Embeds SVGs inline for instant loading
- Professional UI with CSS Grid and responsive design
- **Primary recommended output**
2. **`build-gallery.js`** → **`gallery-static.html`**
- Static gallery version with simplified layout
- Alternative presentation format
- Maintains compatibility with older systems
3. **`demo-crop-comparison.js`** → **`crop-marks-demo.html`**
- Specialized crop mark analysis demonstration
- Before/after comparison views
- Development and debugging tool
4. **`interactive-gallery-demo.html`** (standalone)
- React-powered interactive demonstrations
- Live component examples with AbacusExample.tsx
- Storybook-style interface
### ✅ **FOUND: Complete Flashcards Website with Games**
**CORRECTION**: I found the comprehensive flashcards website generator! The user was absolutely right - there IS a sophisticated system that generates a complete interactive website with abacus games.
#### **🎮 Main Comprehensive Website Generator**
**Location**: `/Users/antialias/projects/soroban-abacus-flashcards/packages/core/src/web_generator.py`
- **583KB** comprehensive Python script
- Generates complete interactive flashcards website with games
- Creates rich HTML with embedded SVG abacus representations
**Command Tool**: `/Users/antialias/projects/soroban-abacus-flashcards/packages/core/src/generate.py`
- Command-line interface for website generation
- Supports configuration files and custom ranges
**Example Output**: `/Users/antialias/projects/soroban-abacus-flashcards/out/flashcards.html`
- Complete interactive website example (substantial file)
- Contains all games and learning features
#### **🎯 Four Interactive Games Included**
1. **Speed Memory Quiz** (`quiz-game`)
- Flash memory training with abacus patterns
- Timed challenges and scoring system
2. **Speed Complement Race** (`race-track-section`)
- **🚂 Features realistic train racing mechanics**
- Steam train journey visualization with momentum system
- Time-of-day progression (dawn → morning → midday → evening → night)
- Geographic landmarks and city stations
- Multiple difficulty modes (Practice, Sprint, Survival)
3. **Matching Pairs Challenge** (`matching-card`)
- Memory-style card matching game
- Match abacus patterns with numerical values
- Perfect for pattern recognition skills
4. **Card Sorting Challenge** (`sorting-game-layout`)
- Drag and drop sorting interface
- Sort abacus cards from lowest to highest value
- Develops number sense and comparison skills
#### **🚂 Train Racing Features (Detailed)**
The Speed Complement Race includes sophisticated train elements:
- **Dynamic track generation** with race-track CSS styling
- **Steam locomotive physics** - momentum affects speed
- **Coal shoveling mechanism** - correct answers provide fuel
- **Time-based lighting** - gradual progression through day/night cycle
- **Geographic progression** - cities and landmarks along route
- **Survival modes** with circular track layouts
#### **📚 Complete Learning System Features**
- **Comprehensive abacus guide** with interactive tutorials
- **100+ practice flashcards** with multiple configurations
- **Multiple color schemes** (monochrome, place-value, heaven-earth, colorblind-friendly palettes)
- **Responsive design** for all devices with mobile optimization
- **Print-ready layouts** for physical flashcards
- **Accessibility features** and keyboard navigation
- **Offline functionality** - works without internet connection
### Complete HTML Generation Pipeline
```mermaid
graph TB
A[flashcards.typ] --> B[generate-gallery.js]
A --> F[packages/core/src/web_generator.py]
B --> C[SVG Files]
C --> D1[build-unified-gallery.js]
C --> D2[build-gallery.js]
C --> D3[demo-crop-comparison.js]
D1 --> E1[gallery-unified.html]
D2 --> E2[gallery-static.html]
D3 --> E3[crop-marks-demo.html]
F --> G[Complete Interactive Website]
G --> H["🎮 Speed Memory Quiz"]
G --> I["🚂 Speed Complement Race"]
G --> J["🃏 Matching Pairs Challenge"]
G --> K["🔄 Card Sorting Challenge"]
G --> L["📚 Comprehensive Abacus Guide"]
G --> M[out/flashcards.html]
style F fill:#ff6b6b,stroke:#d63031,color:#fff
style G fill:#74b9ff,stroke:#0984e3,color:#fff
style M fill:#00b894,stroke:#00a085,color:#fff
```
#### **Two Distinct Systems**
1. **Gallery System** (packages/templates/): Creates showcase galleries of SVG examples
2. **🎮 Games Website System** (packages/core/): Creates complete interactive learning platform with games
This system represents a sophisticated approach to educational content generation, combining the precision of mathematical typesetting with modern web technologies to create engaging, interactive learning materials.