# Pokédex PWA

A responsive, offline-capable Pokédex reference built on
[PokéAPI](https://pokeapi.co/). Vanilla JS + Vite + Workbox — no UI
framework.

## Two headline features

| Feature | How it works |
| --- | --- |
| **Game series selection** | Pick a *game* (PokéAPI version group, e.g. Scarlet & Violet). If it has more than one regional dex (Paldea / Kitakami / Blueberry) a sub-dex switcher appears. The choice drives which species show, their regional numbering, and which version's flavor text the detail page uses. Stored in `localStorage`. |
| **Unified Pokémon selection** | One tracking record per Pokémon, keyed by **National Dex id**. Mark Pikachu once and every game's view reflects it — each dex computes its own "Seen / Caught" totals by intersecting its species list with that single map. The active Pokémon is also a single deep-linkable route (`#/pokemon/25`). |

## Data & storage split

- **Preferences + tracking state** → `localStorage` (`pdx.settings`, `pdx.selection`). Tiny, synchronous, restored on reload.
- **Build-time snapshot** (`src/data/snapshot.json`, ~150 KB) → generated by `npm run snapshot` from PokéAPI: every species (id, name, generation, types), all regional Pokédex lists, and all version groups. Precached by the service worker, so the list / search / game switching work on the first offline launch.
- **Detail data** (stats, abilities, flavor text, evolution) → fetched lazily from `pokeapi.co` per Pokémon, then cached by the service worker (stale-while-revalidate, 30-day TTL).
- **Sprites** → cache-first with a capped LRU.

Export / import of `settings` + `selection` as JSON lives in **Settings**.

## Scripts

```bash
npm install
npm run snapshot     # fetch data from PokéAPI -> src/data/snapshot.json (run once; refreshes if >30 days old)
npm run dev          # vite dev server
npm run build        # runs snapshot (prebuild) then vite build
npm run preview      # serve the production build (needed to exercise the service worker)
```

Deploying under a sub-path (e.g. GitHub Pages project site): `BASE_PATH=/repo-name/ npm run build`.

## Docker

Multi-stage build (Node → nginx) that serves the static `dist/`:

```bash
docker compose up --build        # → http://localhost:8080
# or without compose:
docker build -t pokedex-pwa .
docker run --rm -p 8080:80 pokedex-pwa
```

The build stage runs `npm run build`, whose `prebuild` step fetches the
PokéAPI snapshot — so `docker build` needs network access to `pokeapi.co`
unless a fresh `src/data/snapshot.json` is already present (it gets copied in
and reused). Serving under a sub-path: `docker build --build-arg BASE_PATH=/dex/ .`.
`nginx.conf` sets the SPA fallback and long-cache headers for `/assets/*`
while keeping `index.html` / `sw.js` uncached.

## Project layout

```
scripts/build-snapshot.mjs   PokéAPI -> snapshot.json
src/
  main.js                    boot: theme, nav, router, SW registration
  router.js                  hash router (#/, #/pokemon/:id, #/games, #/search, #/settings)
  sw.js                      Workbox service worker (injectManifest)
  store/                     createStore + settings + selection (localStorage)
  data/                      snapshot loader, pokedex resolver, lazy API client
  components/                Card, Sprite, TypeChip, StatBar, ProgressHeader, Nav
  views/                     DexGrid, PokemonDetail, GamePicker, SearchView, SettingsView
  styles/                    tokens.css (palette, type colors, light/dark), layout.css
```

## Status

Working app with a type-themed UI:

- **Dex grid** — type-tinted cards (official artwork, spotlight, ghost number),
  per-dex progress, name/number filter, caught/favorite filters.
- **Detail** — type-gradient hero + tabbed sheet (About / Stats / Evolution /
  Moves / Locations); coloured animated stat bars; defensive type matchups;
  evolution chain re-parented to the selected game's generation; learnset with
  per-move power/type/accuracy/PP/effect (era-accurate via `past_values`,
  incl. pre-Gen-4 physical/special-by-type); wild encounter locations.
- **Game-aware** — abilities gated to Gen 3+ (hidden to Gen 5+); type chart
  applies Gen 1 / pre-Gen 6 rules.
- **Games / Search / Settings** — game picker with sub-dex switch, offline
  global search, theme + sprite-style + JSON export/import.
- **PWA** — Workbox SW: precache shell + snapshot, SWR for API JSON,
  cache-first LRU for sprites, in-app update toast.

Not yet done: version-exclusive badges, type/generation filters on the grid,
an interactive region map (PokéAPI has no map imagery or coordinates),
skeleton loaders, install-prompt handling, PNG/maskable raster icons
(currently SVG only), and a Lighthouse PWA pass.

## Notes

- `npm audit` reports the known esbuild dev-server advisory via Vite 5. It
  affects the local dev server only, not the production build. Vite 8 (which
  fixes it) requires a newer Node than this environment has.
- Data and images © Nintendo / Game Freak / The Pokémon Company, served via
  PokéAPI. This project is a non-commercial reference tool.