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 e644550d89 Three requests in flight instead of two rounds, and 1.6 MB off the first paint 
THE BOOT CHAIN WAS STRICTLY SERIAL and the sizes are the story. Measured
2026-09-26: `await Promise.all([3 boundaries])` and only THEN `await fetch(API)`,
so 3,549 KB of geojson — world-adm0 1,866, gb-IND-ADM1 1,628, gb-CHN-ADM1 54 —
had to download AND JSON.parse before the API request was even issued. rega
measured the first paint at 9.5-16.5 s, which is why a 7 s screenshot wait caught
a blank map.

THREE CHEAP WINS, no restructuring of the paint itself (dx-shepherd
ENDTOKEN-DXS-UPG-PERFGO, cheap first):

1. THE API REQUEST IS ISSUED FIRST, NOT LAST. Nothing needed to build that URL
   depends on the boundaries, so the fetch starts immediately and is awaited where
   it always was — the rejection still surfaces at the same place in the same
   try/catch. Creating it early changes WHEN the request goes out, not where its
   failure lands.

2. gb-IND-ADM1 (1,628 KB) IS OFF THE CRITICAL PATH. Only the India pg_slugs zones
   need it, and they are resolved well after the first layer could be drawn. It now
   downloads alongside the other two and is awaited beside the records.
   ⚠ AND THE ORDER OF THAT LINE IS LOAD-BEARING. My first version put the
   getJSON() under the Promise.all and it overlapped NOTHING: a promise created
   after an await does not start until that await resolves, so the code read as
   three parallel downloads while behaving exactly as serially as before — a
   parallel-looking shape with serial behaviour. Caught by checking the line
   numbers rather than the intent.

3. `cache: 'no-store'` DROPPED from the boot fetch. It forced a full ~870 KB
   re-download on every reload and could never hit the HTTP cache. This list
   changes on the order of days, not within a session, and the default lets the
   API's own headers decide — which is the server's call rather than this client's.
   ⚠ The other three no-store fetches are DELIBERATELY LEFT: packetRecords and
   selectionAsList are user-triggered (a reader asking for a packet should get
   today's data), and enrichLegendFromRecords runs only on the degraded paths where
   no engine or no token means the map pipeline never ran at all — so it is a
   fallback, not a duplicate of the boot fetch. Verified both call sites.

The blocking await is now 1,920 KB instead of 3,549 KB plus a serial API round
trip, with three requests in flight from the start.

⚠ NOT MEASURED AT THE RENDERED LAYER. Every number here is file sizes and code
order; the 9.5-16.5 s is rega's. dx-shepherd is having rega take a BASELINE trace
and a second on this branch so the gain is measured rather than inferred, and I
would rather that number came from them than from me. The two-pass paint (15
record-free zones first, then the 12 pg_slugs zones and the pins) is next and
deliberately a separate commit.

BUNDLE=my-upg-100-list vite build clean.
2026-09-26 08:25:42 +00:00
..
all-people-groups All People Groups loads fast on a light map; the Vision Card becomes a true funnel from data 2026-09-25 07:18:30 +00:00
big-picture 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
cities-internet 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
country-posters Show-on-map, second pass: stop trusting the bookkeeping, and make deselect mean something 2026-09-26 05:26:48 +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 Move internal files out of the repo; fix five dead links; a fuller delegation diagram 2026-09-25 05:14:10 +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 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
doxa-simple-map 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
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 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
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 Three requests in flight instead of two rounds, and 1.6 MB off the first paint 2026-09-26 08:25:42 +00:00
people-groups-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
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 Every runtime CDN script and stylesheet is an exact version with an integrity hash 2026-09-26 05:50:24 +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 Merge branch 'main' of https://git.nuxtbase.app/doxa-life/doxa-maps into bundler-1/work 2026-09-26 05:42:29 +00:00
research-dashboard check:dashboard-geocoder-provider: a leaf with no search bar fails instead of passing hollow 2026-09-26 05:50:24 +00:00
research-map-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
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 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
wall-of-people-groups 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
.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