History

Doxa Maps 6eae46c002 The legend reaches the map immediately: the shader variant compiles at boot, not on the first click The Driver: on Simple Research the research map is not connecting with the legend. It was connecting — two seconds later, which a reader correctly reads as "nothing happened". I was wrong about the cause twice, and both wrong answers were cheap to discard because they were measured. First guess: a late echo through applyDimFilter's 80ms dedupe, whose toggle branch would read the echo as a second click and clear the highlight. rega instrumented the pin layer every frame for 2 s: ZERO 'legend:highlight' events on every click and no apply-then-revert anywhere. Second guess: the JS filter scan in zoomToLegendRow, which walks 2,106 features evaluating ['in',['get','uniqueId'], ['literal', ~700 ids]] linearly. Benchmarked at the real shapes: 13.9 ms per full scan, 4.4 ms with a memoised Set. Two orders of magnitude short, so nothing there was "optimised". rega's CPU profile named it. ONE task of 3.2-3.5 s, self time getShaderParameter 3,583 ms + getProgramParameter 551 ms: the GPU compiling a NEW SHADER VARIANT. The click was the first moment circle-opacity stopped being a constant and became a per-feature expression, and a data-driven paint property needs a different program. The second click on the same map costs 205 ms — the program is cached — which is the signature of a one-time compile and not of anything in our logic. The legend's DOM was never involved: 34 rows before the click, 34 after. So the fix is not a smaller expression. It is that the first SELECTION must not be the moment the variant is first needed. With nothing selected the value is now ['case',['has','uniqueId'], a, a] — both branches identical, so not one pixel changes — and circle-opacity is data-driven from the first paint. The program compiles during boot beside every other one, and a selection afterwards only re-uploads attribute values. The trade, stated rather than hidden: boot compiles one more program. On a real GPU that is tens of milliseconds; rega measured seconds only because that box rasterises on the CPU through SwiftShader. Paying it at load beats freezing the map mid-gesture, and the variant was going to be compiled on the first interaction anyway. Second finding from the same profile, fixed here too: circle-opacity was being rewritten 4-8 times for a single click (+1.52, +1.57, +1.94, +5.17 s) because the selection handler, the glow sync and the slider watcher all end up in this one function, and every write re-uploads the per-feature attribute. It now writes only when the value actually differs — asked of the MAP rather than of a remembered key, so a layer that gets torn down and re-added cannot leave the skip holding a dim that is no longer painted. Verified: gates:pre 12/12 (check:setup-order included, since this touches module-scope state next to a function that reads it). Needs eyes: rega, the same affinity click — expect the dim at the first frame and one long task at BOOT instead.		2026-09-28 02:38:50 +00:00
..
all-people-groups	A bare-host embed under ?lang=ar now renders Arabic here too	2026-09-27 02:17:35 +00:00
big-picture	Big Picture: the live count speaks, and the locale reaches the children	2026-09-26 22:06:58 +00:00
cities-internet	Cities with Internet: the Women / Men toggle is a 24px touch target	2026-09-27 23:52:08 +00:00
country-posters	Country posters: Show on map, go to the map, come back: the same card shows the country again	2026-09-27 07:28:32 +00:00
dashboard-plus-grid	Plugin Studio and the gallery split production from experimental, from each bundle's own stage	2026-09-27 06:04:08 +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	Capability is derived from what a plugin composes, and the preset-plugin standard is written down	2026-09-27 23:14:15 +00:00
doxa-research-map	The legend reaches the map immediately: the shader variant compiles at boot, not on the first click	2026-09-28 02:38:50 +00:00
doxa-simple-map	Plugin Studio and the gallery split production from experimental, from each bundle's own stage	2026-09-27 06:04:08 +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-internet	Gospel x Internet: the row checkbox hit area is a full 24 x 24 px	2026-09-28 02:33:15 +00:00
gospel-resources	Neutral wording in a table strangers read	2026-09-28 00:45:42 +00:00
key-cities	Key cities: the map honours provider=maplibre instead of always building Mapbox GL	2026-09-27 04:38:17 +00:00
my-upg-100-list	The share-alike field should have held 65, not 7	2026-09-28 01:51:24 +00:00
people-groups-grid	One place decides how a count is punctuated, and it still says en-US	2026-09-27 06:04:08 +00:00
plugin-studio	Plugin Studio names each row from the plugin's own meta label, never a bare profile id	2026-09-28 02:38:49 +00:00
pplr-data-maps	PPLR maps: the ready counts use the library's count formatter	2026-09-28 00:20:34 +00:00
prayer-walk-planner	Prayer Walk Planner: the phone toolbar fits, with the list actions behind More	2026-09-28 00:36:26 +00:00
regions-dashboard	The manifest descriptions were mine	2026-09-28 02:01:46 +00:00
research-dashboard	The country's code comes from the row, not from its name	2026-09-28 02:38:50 +00:00
research-map-plus-grid	Shared links keep partner param names, and a CSV export matches multi-value filters	2026-09-27 18:40:47 +00:00
rudder-voice	Rudder with RUDDER_ENGINE=0 never starts the engine, and a page on another machine never offers to record the server's mic	2026-09-27 23:24:08 +00:00
stack-demo	Decouple prose: no go-base / nuxtbase / nuxtinator / doxa-base names in plugin comments and docs	2026-09-26 17:28:45 +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	UPG Neighbor: the start view shows the unreached dots	2026-09-27 23:52:08 +00:00
wall-of-people-groups	Wall of People Groups opens where the photos are, with rows as far apart as columns	2026-09-27 05:30:05 +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).