chris
671e72972a
Pure formatting — no behaviour change. Verified: build passes, all 14 routes render, service worker active, no console errors. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017Ve7HLspzeG2xDPtJQ8vmu
124 lines
4.6 KiB
Markdown
124 lines
4.6 KiB
Markdown
# Contributing to Pocketdex
|
|
|
|
Thanks for taking the time. This is a small, framework-free codebase and
|
|
easy to get into.
|
|
|
|
## Ground rules
|
|
|
|
- **No copyrighted assets.** Don't commit Pokémon sprites, artwork, audio,
|
|
ROMs or save files. Everything visual is fetched at runtime from PokéAPI.
|
|
PRs that add such files will be asked to remove them.
|
|
- **Non-commercial.** No ads, analytics, telemetry, paid tiers, affiliate
|
|
links or "sign in" flows.
|
|
- **Stay framework-free.** No React/Vue/Svelte/etc., and no new runtime
|
|
dependencies without discussing it in an issue first. Build-time dev
|
|
dependencies are a lower bar but still worth raising.
|
|
- **Offline-first stays true.** The list, search, sort, filters and game
|
|
switching must keep working with no network. New always-needed data goes
|
|
in the snapshot, not a runtime fetch.
|
|
- **Be kind.** Assume good faith in issues and reviews.
|
|
|
|
## Getting set up
|
|
|
|
Requires **Node 20+**.
|
|
|
|
```bash
|
|
npm install
|
|
npm run snapshot # build src/data/snapshot.json from PokéAPI (git-ignored)
|
|
npm run dev # http://localhost:5173
|
|
```
|
|
|
|
To exercise the service worker, offline behaviour or the install prompt,
|
|
you need a real build:
|
|
|
|
```bash
|
|
npm run build && npm run preview
|
|
```
|
|
|
|
## Where things live
|
|
|
|
See the **Project layout** and **How it works** sections in
|
|
[README.md](README.md). In short:
|
|
|
|
- `src/views/<Name>.js` — one file per route, an `async` function returning
|
|
a DOM node. Register it in `src/router.js`.
|
|
- `src/components/` — reusable pieces (`Card`, `Sprite`, `TypeChip`, …).
|
|
- `src/store/` — `createStore()`-backed reactive state, persisted to
|
|
`localStorage` under `pdx.*`.
|
|
- `src/lib/` — framework-y helpers with no app knowledge (`dom`, `anim`,
|
|
`damage-calc`, `savedex`, …).
|
|
- `src/data/` — the snapshot loader, the Pokédex resolver, the lazy PokéAPI
|
|
client, the type chart, natures.
|
|
- `scripts/build-snapshot.mjs` — the only thing that talks to PokéAPI at
|
|
build time.
|
|
|
|
## Code style
|
|
|
|
There's no linter or formatter config yet — **match the surrounding
|
|
code**:
|
|
|
|
- 2-space indent, semicolons, single quotes, trailing commas in
|
|
multi-line literals (an `.editorconfig` covers whitespace).
|
|
- Build DOM with the `el()` helper from `src/lib/dom.js`, not template
|
|
strings or `innerHTML` (except the deliberate `html:` prop for trusted
|
|
inline SVG).
|
|
- Stores: `set(fn)` **replaces** state — spread `...s` yourself. Read with
|
|
`get()`, react with `subscribe()`, and unsubscribe in the view's
|
|
teardown (`onTeardown(view, off)`).
|
|
- Keep comments about _why_, not _what_. Match the existing density.
|
|
- Respect `prefersReducedMotion()` for any new animation.
|
|
- Keep everything game-aware: if you touch typings, type effectiveness,
|
|
learnsets or evolution, honour the selected game's generation
|
|
(`typesForGen`, `multiplier(atk, def, gen)`, `past_values`, …).
|
|
|
|
## Common tasks
|
|
|
|
**Add a setting** — add the key + default to `src/store/settings.js`
|
|
(and `applyTheme()` if it affects the document), then a field in
|
|
`src/views/SettingsView.js`. Add it to the export payload if it should
|
|
survive a backup.
|
|
|
|
**Add a snapshot field** — add it in `scripts/build-snapshot.mjs`, run
|
|
`npm run snapshot -- --force`, and consume it via `loadSnapshot()`. Keep
|
|
the snapshot small; it's precached on every install.
|
|
|
|
**Add a route** — new file in `src/views/`, one entry in the `routes`
|
|
array in `src/router.js`. Add a skeleton if the view does async work
|
|
before it can render.
|
|
|
|
## Testing your change
|
|
|
|
There's no automated suite. Before opening a PR, manually check:
|
|
|
|
- The **dex grid** — filters, sort, the progress ring, catching from a
|
|
card.
|
|
- **Switching games** (the Games sheet) — regional numbers, era typings,
|
|
and per-game seen/caught all update.
|
|
- A **detail page** — every tab, form switching, the track buttons.
|
|
- **`npm run build`** succeeds, and `npm run preview` still works offline
|
|
(DevTools → Network → Offline, then reload).
|
|
- Light **and** dark theme, and a narrow (mobile) viewport.
|
|
|
|
Describe what you tested in the PR.
|
|
|
|
## Commits & pull requests
|
|
|
|
- Branch off `main`. One focused change per PR.
|
|
- Imperative commit subjects ("Add …", "Fix …"), with a body explaining
|
|
the _why_ when it isn't obvious.
|
|
- Don't commit `dist/` or `src/data/snapshot.json` (both git-ignored).
|
|
- Fill in the PR template. Screenshots or a short clip for anything
|
|
visual.
|
|
- It's fine to open a draft PR early to discuss direction.
|
|
|
|
## Reporting bugs
|
|
|
|
Open an issue with: what you did, what you expected, what happened, the
|
|
browser/OS, and the selected game if it's relevant. A screenshot or the
|
|
console output helps a lot.
|
|
|
|
## License
|
|
|
|
By contributing you agree that your contributions are licensed under the
|
|
[MIT License](LICENSE).
|