doxa-life/doxa-maps
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
doxa-maps/plugin-designs
History
Doxa Maps 3c69770422 C2: one library helper for per-engine projection, across 12 call sites in 9 plugins 
SPEC-LIBRARY-CURATION.md's first migration, in the order the shepherd approved.
Source only; studio rebuilds (rule 5B — library/ plus eight other owners' plugins).

THE ASYMMETRY, which is why 12 sites each solved it or failed at it separately:
    Mapbox    getProjection() -> { name }               setProjection('mercator')
    MapLibre  getProjection() -> { type } | undefined   setProjection({ type: 'mercator' })
Passing the Mapbox shape to MapLibre THROWS. Measured on regions-dashboard, where
the throw aborted the camera fly so a region dashboard never framed its region.

WHAT THE 12 SITES WERE DOING:
  · NINE passed a bare string, so on MapLibre the projection silently never changed.
    Eight swallowed the throw in a try/catch; doxa-simple-map.vue:1244 did NOT, so
    there it threw uncaught.
  · TWO had solved it independently and differently: pplr-data-maps'
    setProjectionFor() (instance-tested — the correct one, and the shape adopted)
    and regions-dashboard's local pair (config-derived, which is weaker: it trusts
    what the page was configured with rather than what the map IS).
  · ONE probed by exception, trying the object form and falling back on throw.

The helper reads the engine from the INSTANCE, never from config, because a page can
hold a map built by the other engine. Both functions return something observable —
setProjectionOn returns whether it applied, projectionOf returns null rather than
throwing — on upg100-plugin's argument that a precondition which bails without
recording it is indistinguishable from the request never arriving.
pplrData.setProjectionFor stays as a delegating named export so its three views need
no change.

GATE: _chk-c2-projection-helper-equivalence.mjs, 20 assertions. It runs all THREE old
patterns and the helper against the same stub maps and compares outcomes, rather than
testing the helper alone. Controls prove pattern A really does fail on MapLibre and
leave the projection untouched, and that the bare string really throws — so the
"equivalence" claim has something to be equivalent to. A NEG control catches a helper
that reports success it did not achieve.

★ I DESTROYED 984 LINES OF ANOTHER TEAM'S CODE GETTING HERE, and only the build caught
it. My import-inserting script did `s[:at] + IMPORT` and never appended `s[at:]`, so
every file where the import was ADDED rather than extended was truncated at its last
import line: MapCell.vue -458, FlowerClusters.vue -334, lang-cluster.vue -192.
check:no-free-identifiers PASSED on all three, because a truncated script block is
still valid script. Restored from HEAD and redone with an assertion that a migration
must change the line count by exactly +1 and never remove a line — which is the check
that would have caught it in the first second.

Verified after: all 9 affected bundles build, both gates green, and a per-file line
delta on all 13 changed files with the only negative being the 2 lines I deliberately
deleted from RegionCountryMap when its local pair became an import.
2026-09-26 08:39:53 +00:00
..
all-people-groups C2: one library helper for per-engine projection, across 12 call sites in 9 plugins 2026-09-26 08:39:53 +00:00
big-picture Integrate main into bundler-2/work 2026-09-26 06:43:22 +00:00
cities-internet India by state: all 36 states, Mizoram and Nagaland included 2026-09-26 08:13:34 +00:00
country-posters C2: one library helper for per-engine projection, across 12 call sites in 9 plugins 2026-09-26 08:39:53 +00:00
dashboard-plus-grid The people-group list is a universal prop: the same maps can show any project's list 2026-09-26 05:16:02 +00:00
demo-map C2: one library helper for per-engine projection, across 12 call sites in 9 plugins 2026-09-26 08:39:53 +00:00
doxa-maps-spa Research Gallery: PPLR Data Maps and Wall of People Groups are named in all 11 languages 2026-09-25 23:41:17 +00:00
doxa-research-map C2: one library helper for per-engine projection, across 12 call sites in 9 plugins 2026-09-26 08:39:53 +00:00
doxa-simple-map C2: one library helper for per-engine projection, across 12 call sites in 9 plugins 2026-09-26 08:39:53 +00:00
doxa-vision-card Doxa Vision Card: take the page language from profile-config lang as well as locale 2026-09-26 01:10:51 +00:00
golden-path-check golden-path-check: walk the develop-a-plugin-and-see-it-live path end to end 2026-09-22 03:55:18 +00:00
gospel-resources Guard the last three catalogue snapshots against a bad network day 2026-09-26 07:56:31 +00:00
key-cities Key Cities (gated): the map, list, tables and posters speak the reader's language 2026-09-26 03:34:30 +00:00
my-upg-100-list The funnel states the list it was actually drawn from 2026-09-26 08:13:34 +00:00
people-groups-grid The grid's DATA follows the URL's language, and the grid turns round in Arabic 2026-09-26 07:56:38 +00:00
plugin-studio Plugin Studio: collapse the header to give the plugin the whole page, and bring it back in one click 2026-09-26 04:39:00 +00:00
pplr-data-maps C2: one library helper for per-engine projection, across 12 call sites in 9 plugins 2026-09-26 08:39:53 +00:00
prayer-walk-planner Export gate reads the tree name from the build config 2026-09-25 21:32:35 +00:00
regions-dashboard C2: one library helper for per-engine projection, across 12 call sites in 9 plugins 2026-09-26 08:39:53 +00:00
research-dashboard C2: one library helper for per-engine projection, across 12 call sites in 9 plugins 2026-09-26 08:39:53 +00:00
research-map-plus-grid Link language on the ISO code, not the display name, because the name moves with the locale 2026-09-26 08:07:39 +00:00
stack-demo Studio and stack-demo hand the host's language down to what they mount 2026-09-25 13:26:01 +00:00
template-bundle template-bundle: the starter's first screen is now a real map 2026-09-26 04:38:12 +00:00
upg-neighbor C2: one library helper for per-engine projection, across 12 call sites in 9 plugins 2026-09-26 08:39:53 +00:00
wall-of-people-groups One pinned-UMD loader for PPLR and the Wall: library/utils/loadPinnedUmd.js 2026-09-26 07:24:25 +00:00
.gitkeep Rename app-profiles -> plugin-designs; build green under new naming (load-bearing paths updated, guards pass) 2026-09-17 18:18:18 +00:00
README.md plugin-designs/README: the tree is dx-maps, and a bundle's tag is its folder name 2026-09-26 01:19:53 +00:00

README.md

plugin-designs/ — where YOUR maps live

The shared template lives in ../library/ (aliased @map) — you never edit it per-map. You build your map by making a folder here, plugin-designs/<your-map>/, and composing the template's building blocks. Your folder is yours (colors, API, i18n); the template is shared (Apache-2.0, propagated to every map on the next build).

Shared vs. yours — the balance

  library/  (@map)  ── SHARED, reusable, parameterized ──►  legend · map · map-controls
        │                                                    (every map reuses these)
        │  imported by
        ▼
  plugin-designs/<your-map>/  ── YOURS ──►  the map's "main" class (the .vue profile = the Vue
        │                                  instance for that map)
        └── src/            ── YOURS ──►  this map's OWN non-reusable components, colors, API, utils

  One bundle can hold as many maps as you want — add another .vue profile and rebuild.
  • Reusable → library/. The legend, the map, the map-controls are shared, parameterized components every map reuses. Fix once, every map benefits. Never edit it to customize one map.
  • This map's own → plugin-designs/<your-map>/. It holds two things: the map's "main" class (each .vue profile is the Vue instance for that map) and that map's own non-reusable components (in src/). Nothing here leaks to another map.
  • Many maps per bundle. The bundler bundles one map or many — add another flat .vue and rebuild.

Production or experimental — every profile declares itself

Every app profile is one of two things, and experimental profiles are unlimited and encouraged — create as many as you need:

  • Experimental, not built: prefix the folder with _ — the build skips it; it just sits in code. Zero cost, zero risk.
  • Experimental, built: builds normally, but it belongs in the Experimental section of the power app's layout (nav section) — never embedded on partner surfaces.
  • Production: a real product — main sections of the power app + individually embeddable.

(The power app = the SPA layout that composes all profiles into one application.)

The pattern in one picture

plugin-designs/<your-map>/     ← one FOLDER = one BUNDLE, named after the folder
   ├── index.js               ← entry: registers the custom element, finds the profiles
   ├── overview.vue           ← one .vue = one PROFILE (flat in the folder — no profiles/ subfolder)
   └── detail.vue             ← another profile in the SAME bundle

     builds to ─────────────► public/dx-maps/<your-map>/<your-map>.js   (one file)
  • Folder name = bundle name. Folders starting with _ or . are skipped (handy for WIP).
  • Each .vue = one profile (one map screen). One bundle can hold many.
  • Pick the profile at embed time with the profile field — every profile shares one bundle:
<script src="/dx-maps/<your-map>/<your-map>.js"></script>
<your-map profile-config='{"profile":"overview","tk":"pk.eyJ..."}'></your-map>
<your-map profile-config='{"profile":"detail","tk":"pk.eyJ..."}'></your-map>

Add a map — three steps

# 1. create the folder + one profile
mkdir -p plugin-designs/<your-map>
#    index.js   ← copy doxa-simple-map/index.js, rename the tag
#    <name>.vue ← your screen, built from @map/* blocks (flat in the folder)

# 2. build
npm run build            # → public/dx-maps/<your-map>/<your-map>.js
#    (just this one:  BUNDLE=<your-map> npm run build:bundle)

# 3. embed the script tag + element (dev staging at `npm run dev` shows a paste-ready snippet)

Your three things (everything else is shared)

  • Colors — how pins are colored. Pick one the template ships (getColorStrategy('language-family')), or drop your own in plugin-designs/<your-map>/src/colors/ (start from template-bundle/src/colors/example-mode.js). Never edit @map/colors/ to recolor your map.
  • API — your map reads its data from the profile-config on the page, so the same bundle points at different data with no rebuild. DataSourceManager accepts csv (bundled file), api (one JSON URL), or rest-api (a live REST endpoint, the default). Prefer the real API over inlined JSON.
  • i18n — the template ships 11 base locales in @map/i18n/locales/. Use useI18n() for strings and RTL_LOCALES for right-to-left; add or override strings from your own profile.

The one hosting variable

The only thing that changes between hosting modes is the <script src>: a relative path when your own site serves the file, or an absolute CDN URL when a partner site serves it. The bundle is identical either way. See ../documentation/CONTRIBUTING.md for the two CDN modes and partner-site embedding.

Profile patterns (mix freely)

  • Individual — one .vue per bundle (simplest).
  • Parameterized — one profile, behavior driven by profile-config props (e.g. tabs[]).
  • Nested — one profile that renders others (workbench-style, like doxa-research-map).

See also

  • doxa-simple-map/index.js — fully commented reference bundle entry
  • template-bundle/ — minimal two-profile skeleton to copy
  • ../library/colors/README.md — the color-strategy contract
  • ../README.md — repo overview & build pipeline · ../documentation/CONTRIBUTING.md — build vs dev, CDN modes