Rulers Quiz
Put a name to a portrait, a number to a name, years to a reign, or any other pairing.
47 US presidential terms in English and 31 Russian rulers in Russian, on one quiz engine.
https://github.com/user-attachments/assets/4868459c-415d-4b8a-a999-10c31e7e71a9
Two quizzes, one engine
Both domains share every screen, component and grading rule. Each one is a registry of fields,
modes, strings and an accent colour, and nothing in the UI names a language or a mode.
On your phone
Android comes first; the web build works just as well in a mobile browser.
Features
- Five ways to play. You get one piece of a reign and supply the rest. The piece can be the
presidency number, the name, the years, a portrait, or a mix that changes every question.
/ru has no numbers, so it offers four modes.
- Your own pool. Narrow the quiz to the Founders, the 19th century, the Soviet period, or
any run you drag out on the slider. Your choice is remembered per quiz and can be shared as
?range=1-19,28-31.
- A gallery. Every ruler is listed as a row or as a portrait card.
- Strict, fair grading:
- Repeat holders. Cleveland (#22/#24), Trump (#45/#47) and Putin each hold two terms.
Given the name, either term counts and the reveal lists both. A number from one term with
the years of the other is wrong.
- Ongoing terms accept
present / «н. в.», the bare start year, or the scheduled end.
- Suffixes and numerals are required.
Barack Hussein Obama isn't #44, and Николай I
isn't Николай II.
- Birth names and aliases. Hiram Ulysses Grant, Lenin's and Stalin's real names, and
Catherine the Great's Sophie of Anhalt-Zerbst are all accepted.
- Unicode-aware matching folds case, punctuation and
ё → е.
- Mobile keyboards that work. The years field gets a keyboard on every platform where
1762-1796 can actually be typed.
How it works
flowchart LR
D["DomainCore<br/><sub>src/domains/{us,ru}-core.ts</sub>"] --> P["pickGiven + answerFields<br/><sub>src/lib/quiz.ts</sub>"]
P --> Q["Question<br/><sub>{ rec, given, answers }</sub>"]
Q --> S["QuizScreen<br/><sub>prompt + AnswerField × n</sub>"]
S -- inputs --> G["grade()"]
G --> R["RevealPanel<br/><sub>one row per term</sub>"]
A mode names the prompt. pickGiven resolves it (mixed picks a different given piece
each time), and answerFields asks for every other field in the domain's order. Each field's
FieldSpec carries its label, placeholder, keyboard, how to show it and how to check it, so
QuizScreen just renders q.answers.map(...). grade scores each candidate term as a whole
and keeps the best one, which is how the two-row Cleveland reveal happens without any special
case.
The grading logic in src/lib/ and src/domains/*-core.ts imports no React Native values,
so the whole suite runs on bare Node with no test framework.
Getting started
git clone https://github.com/l4nzel0d/US-Presidents-Quiz-App.git
cd US-Presidents-Quiz-App
npm install
npm run web # run in the browser
npm start # dev server for Android (needs a dev client, see below)
npm test # 127 grading assertions over both domains
npx tsc --noEmit # typecheck
[!NOTE]
Expo Go won't work. The app links react-native-keyboard-controller, a native module, so
on a device you need a development build (expo-dev-client is already a dependency):
eas build --profile development, install it, then npm start.
Project structure
src/
├── app/ Expo Router routes: thin wrappers only
│ ├── index the chooser
│ ├── us/ _layout · index (menu) · list · quiz/[mode]
│ └── ru/ same shape
├── screens/ MenuScreen · ListScreen · QuizScreen, shared by both domains
├── lib/ pure logic: domain vocabulary, quiz, grading, ranges, storage
├── domains/ us-core / ru-core (pure, tested) + us / ru (adds images)
├── data/ us-presidents.ts (47) · ru-rulers.ts (31)
├── components/ UI pieces + portrait maps
├── state/ DomainContext · RangeContext
└── theme/ a translation of .legacy/styles.css
tests/ grading.test.ts + a tiny Node resolver hook
.legacy/ the original vanilla-JS web app this was ported from
Building & deploying
Android APK (arm64-v8a) via EAS:
eas build --profile preview
Web: a static export, hosted on Vercel:
npx expo export --platform web # writes dist/
Static rendering emits the dynamic quiz routes as literal dist/us/quiz/[mode].html and
dist/ru/quiz/[mode].html, so vercel.json rewrites /us/quiz/:mode and /ru/quiz/:mode
onto them. Any other static host needs the same two rewrites.
Contributing
Read AGENTS.md before you touch anything. It covers the architecture, the
grading rules worth keeping, and the pitfalls that have already bitten once: typed-route
poisoning, accent colours that can't live in a StyleSheet, the twin-thumb slider. Run
npm test after any change to src/lib/ or src/domains/.
