feat(examples): add flashcard-app example with flip interaction and keyboard navigation

[pranvxag]

Description

Adds a new example app examples/flashcard-app demonstrating a terminal-based
flashcard study tool. The app showcases flip interaction, self-marking,
card navigation, and a summary screen — interaction patterns not covered
by any existing example.

##Features

• Space to flip card between question and answer
• y / n to mark card as known or still learning
• → / ← arrow keys to navigate between cards
• Summary screen showing known/unknown count and score percentage
• r to restart, q / Ctrl+C to quit

Related Issue

Closes #1729

Which package(s)?

examples/flashcard-app

Type of Change

• 🐛 Bug fix (type:bug)
• ✨ Feature (type:feature)
• 📝 Docs (type:docs)
• 🧪 Tests (type:testing)
• ♻️ Refactor (type:refactor)
• 🎨 Design / UX (type:design)
• ♿ Accessibility (type:accessibility)
• ⚡ Performance (type:performance)
• 🔧 DevOps / CI (type:devops)
• 🔒 Security (type:security)

Checklist

• ⭐ You starred the repo. The needs-star check blocks your merge otherwise.
• Tests pass locally: bun vitest run
• Build passes: bun run build
• Typecheck passes: bun run typecheck
• You read CONTRIBUTING.md.
• Your PR title follows type: short description.
• Widget state mutators call markDirty() (if your change affects rendering).
• No new any types without an inline comment explaining why.
• No unrelated refactors bundled into this PR.

GSSoC 2026 Participation

• You are a GSSoC 2026 contributor.
• Your GSSoC profile: `https://gssoc.girlscript.org/profile/790b367a-48ea-45f6-af27-c353fb2d49cb

Notes for the Reviewer

Follows the same structure as examples/quiz-app — single index.tsx with
a Widget subclass, no external dependencies beyond @termuijs/core and
@termuijs/widgets. Tested manually in Codespaces terminal with all key
bindings verified working.

I reviewed the code against quiz-app patterns and tested all interactions manually before submitting.

Summary by CodeRabbit

• New Features
  • Added a new Flashcard App example with interactive flashcards, flip-to-reveal answers, keyboard controls for marking known/unknown, and progress/completion summaries.
• Chores
  • Added TypeScript and Bun setup for the example, including standard start/dev scripts and type-checking to streamline running and validating the example.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2fe4b13a-9f23-4918-9454-485ebe474216

📥 Commits

Reviewing files that changed from the base of the PR and between 7558b1b and 9c26dcb.

📒 Files selected for processing (1)

• examples/flashcard-app/src/index.tsx

🚧 Files skipped from review as they are similar to previous changes (1)

• examples/flashcard-app/src/index.tsx

---

📝 Walkthrough

Walkthrough

Adds a new examples/flashcard-app example to the repository. The addition includes a package.json with Bun scripts and workspace dependencies, a tsconfig.json extending the repo base config, and a complete FlashcardApp widget in src/index.tsx implementing flip, mark, navigate, and restart interactions with a summary screen.

Changes

Flashcard App Example

Layer / File(s)	Summary
Package and TypeScript configuration examples/flashcard-app/package.json, examples/flashcard-app/tsconfig.json	Defines the package metadata, start/dev/typecheck Bun scripts, workspace dependencies on @termuijs/core and @termuijs/widgets, and TypeScript compiler options extending ../../tsconfig.base.json.
Flashcard type, dataset, and layout constants examples/flashcard-app/src/index.tsx	Declares the Flashcard type, the CARDS array of question/answer pairs, and WIDGET_WIDTH/WIDGET_HEIGHT sizing constants.
Widget constructor and child UI elements examples/flashcard-app/src/index.tsx	Implements the FlashcardApp constructor that configures the container layout and instantiates all child Text and spacer box elements for header, card body, hint, feedback, and footer.
State management, UI text helpers, refresh, and render examples/flashcard-app/src/index.tsx	Adds flip(), markKnown()/markUnknown(), advance(), navigatePrev()/navigateNext(), restart() methods; UI text derivation helpers for header/body/hint/footer/completion screen; refresh() to sync all text fields; and an empty _renderSelf() override.
Key handler and main entrypoint examples/flashcard-app/src/index.tsx	Implements handleKey() mapping space, y/n, arrow keys, q/Ctrl+C, and r to widget actions; main() mounts the widget in a centered container, starts the App full-screen, wires key events, and adds top-level error handling.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

quality:clean, level:beginner

Suggested reviewers

• Karanjot786

Poem

🐇 A flashcard flips, a question appears,
Space reveals the answer — no more fears!
Press y for known, n for review,
r to restart when the session is through.
The rabbit hops along each card with glee,
Learning TypeScript terms most eagerly! 🎴

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the primary changes: adding a new flashcard-app example with flip interaction and keyboard navigation features.
Description check	✅ Passed	The description includes all required template sections: clear feature description, linked issue (#1729), affected package, type of change (Feature), completed checklist items, and GSSoC participation details.
Linked Issues check	✅ Passed	The implementation comprehensively addresses all objectives from issue #1729: flip interaction via space bar, arrow key navigation, y/n marking, summary screen, and restart/quit controls are all included in the example.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the flashcard-app example: package.json, tsconfig.json, and index.tsx files. No unrelated modifications to existing code or packages are present.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

examples/flashcard-app/tsconfig.json (1)

2-7: 🧹 Nitpick | 🔵 Trivial

Strict mode is already enforced through inheritance; consider making it explicit locally for clarity.

This config extends tsconfig.base.json, which sets "strict": true on line 9. The example is compliant. However, declaring "strict": true locally would make the requirement explicit and protect against future changes to the base config.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@examples/flashcard-app/tsconfig.json` around lines 2 - 7, The tsconfig.json
file's compilerOptions object inherits strict mode enforcement from the extended
tsconfig.base.json but does not explicitly declare it locally. Add "strict":
true to the compilerOptions object in this file to make the strict mode
requirement explicit and protect against potential future changes to the base
configuration.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/flashcard-app/src/index.tsx`:
- Around line 203-206: The showSummary() method sets done to true and calls
refresh() but does not clear the _feedback field, causing stale per-card status
messages to appear on the summary screen. Add a line in the showSummary() method
to reset the _feedback field to its initial/empty state (likely null, empty
string, or undefined depending on its type definition) before or after setting
done to true, ensuring the summary view displays without any leftover feedback
from individual cards.

---

Nitpick comments:
In `@examples/flashcard-app/tsconfig.json`:
- Around line 2-7: The tsconfig.json file's compilerOptions object inherits
strict mode enforcement from the extended tsconfig.base.json but does not
explicitly declare it locally. Add "strict": true to the compilerOptions object
in this file to make the strict mode requirement explicit and protect against
potential future changes to the base configuration.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b4d9b6cc-464c-4ebc-91c0-0b3168b2b37b

📥 Commits

Reviewing files that changed from the base of the PR and between 35c2213 and 7558b1b.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (3)

• examples/flashcard-app/package.json
• examples/flashcard-app/src/index.tsx
• examples/flashcard-app/tsconfig.json