88 lines
3.6 KiB
Markdown
88 lines
3.6 KiB
Markdown
# Editing map colors
|
|
|
|
Pins on a map are colored by a **color strategy** — one small file that says "for this
|
|
color mode, paint each pin this color." There are two places a color strategy can live,
|
|
and which one you pick follows the one rule:
|
|
|
|
> **Reused by more than one map → shared library. Only your map uses it → your profile.**
|
|
|
|
---
|
|
|
|
## Path A — tweak a color in the shared library
|
|
|
|
Use this when the color is genuinely shared (prayer-progress, engagement, adoption,
|
|
religion, language-family — these are used by the shared map machinery across
|
|
profiles).
|
|
|
|
1. Open `library/colors/<name>.js` (e.g. `religion.js`).
|
|
2. Edit the `PALETTE` — just change a hex value.
|
|
3. `bun run dev` → the change shows on every map that uses that mode, live (HMR).
|
|
|
|
The library **auto-discovers** every `<name>.js` in that folder (`import.meta.glob`), so
|
|
there's no registration step — edit the palette and you're done. The full strategy
|
|
**contract** (the required `export default` shape) is in
|
|
`library/colors/README.md`; `religion.js` is the canonical worked example.
|
|
|
|
**Be deliberate here** — a change to a shared strategy affects *every* map that uses it.
|
|
If you only want to change *your* map, use Path B instead.
|
|
|
|
---
|
|
|
|
## Path B — a color private to YOUR map (override or add)
|
|
|
|
Use this when the color is specific to your map — you want a different shade than the
|
|
shared one, or a brand-new coloring nobody else has. This keeps the shared library clean
|
|
("local by default").
|
|
|
|
1. In your bundle folder, create `plugin-designs/<your-map>/src/colors/<name>.js`.
|
|
(No such folder yet? Just make it. `template-bundle/src/colors/example-mode.js`
|
|
is a copy-me starting point.)
|
|
2. Follow the same contract as a library strategy
|
|
(`export default { name, propertyKey, getColor, applyColor }`).
|
|
3. `bun run dev` → your map picks it up via HMR. No rebuild.
|
|
|
|
### How override vs. add is decided (the filename)
|
|
|
|
Your bundle's `index.js` runs, at startup:
|
|
|
|
```js
|
|
registerStrategies(import.meta.glob('./src/colors/*.js', { eager: true }))
|
|
```
|
|
|
|
(The glob is `*.js`, so a `colors.json` of plain values sitting in the same
|
|
`src/colors/` folder is ignored by the registry — values and strategies coexist.)
|
|
|
|
That merges your local files **over** the shared library set. The **filename** derives
|
|
the mode key:
|
|
|
|
- `language-family.js` → mode `languageFamily` / `COLOR_MODES.LANGUAGE_FAMILY`
|
|
- `example-mode.js` → mode `exampleMode` / `COLOR_MODES.EXAMPLE_MODE`
|
|
|
|
Then:
|
|
|
|
- **Same mode key as a shared strategy → your file OVERRIDES it** (for your map only).
|
|
- **A new mode key → your file ADDS a private strategy** (only your map sees it).
|
|
|
|
### It can't break other maps
|
|
|
|
Each bundle is built as its own self-contained IIFE, so it carries its **own** copy of
|
|
the color registry. Registering a local strategy changes **only your bundle** — it can
|
|
never leak into another map. Which is exactly why "local by default" is safe.
|
|
|
|
---
|
|
|
|
## Which colors are shared vs. private (today)
|
|
|
|
The five strategies currently in `library/colors/` are **shared** — the
|
|
reusable map machinery (`useMapLayers`, `useLegendData`, the mobile legend, the data
|
|
loader, the store) references them, so they correctly stay in the library:
|
|
|
|
`adoption`, `engagement`, `language-family`, `prayer-progress`, `religion`.
|
|
|
|
Three more are **research-only** and live in the research bundle's own folder,
|
|
`plugin-designs/doxa-research-map/src/colors/`: `affinity-block`, `doxa-region`,
|
|
`resource`.
|
|
|
|
If you want *your* map to color one of these differently, don't edit the library — drop
|
|
a same-named file in your profile's `src/colors/` (Path B) and it overrides the
|
|
shared one for your map alone.
|