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 ca7144a57b The gate learns the aliases instead of being told them, and can read main 
A fleet-wide census with this gate as it stood would have been worth nothing, and
worse than nothing once mailed to seven owners. Three things had to be true
first.

IT HAD TO SEE OTHER PEOPLE'S CALL SITES. The first version matched tStatic/$t/t
and found four missing keys while sailing past the ten it was written for. Adding
`T` by hand took it to 22 — and that fix was the same mistake one level up. A
census of the tree finds FOUR wrapper names, not one: `const T` x16, `const L`
x6, `const tr` x1 (library/layouts/VerticalTabsLayout.vue) and `const v` x1. A
gate that knows about T and not tr is blind to whichever bundle used the other
name and reports it CLEAN. So the names are now read out of each file, and the
next author's alias is covered the day they write it. Negative-tested by renaming
T to Tz in a file: all six of its call sites are still found.

IT HAD TO RESOLVE THE PREFIX HELPERS IT WAS DECLINING TO. All six `L`
declarations carry a static prefix — four are `tStatic('dashboard.' + key)`, two
are a ladder `tStatic('controls.' + key) || tStatic('dashboard.' + key)`. Those
are ordinary keys with a known prefix, not runtime expressions, and counting them
as unresolved left most of this gate's coverage on the floor: 49 call sites moved
from unchecked to checked, and the unresolved count fell from 80 to 28. A key
resolves if ANY prefix in the ladder holds it, because that is what the ladder
does at runtime.
★ AND THE FIRST RUN OF THAT RESOLUTION INVENTED A DEFECT. BpResearchHeader
renders `L('reset_all', '') || tStatic('controls.reset_all') || 'Reset'` — the
author saying "if this prefix has nothing, fall to the next rung", and
controls.reset_all does hold it. Reported as missing, that is a gate manufacturing
a problem out of a working ladder — the precise failure I was about to mail seven
owners about. An empty English fallback is the author's own signal that the miss
is intended, and is now honoured.

IT HAD TO MEASURE A TREE IT IS NOT STANDING IN. A census has to be taken against
current main; every bundle but mine is stale in my worktree, so a local scan would
report keys another owner fixed an hour ago. A second checkout was not available
either (the box is at 97% disk), so `--rev` reads the files as blobs out of the
object store: one ls-tree and one cat-file --batch, parsed by length rather than
by scanning for a delimiter that could occur inside a file. No worktree, no temp
copy, no writes.

AND IT HAD TO STOP ITS OWN SILENCE BEING READ AS A PASS. This gate asks whether
the keys a bundle NAMES exist. A bundle that names none has nothing to be missing
and passes without a word — and seven do, including two of mine whose composites
render no chrome of their own. Reporting only the misses would let "0 missing
keys" be read as "fully localized", which is the opposite of true for exactly
those bundles. Participation is now counted and printed beside the result, and
the two are never merged into one number.

THE CENSUS, at origin/main 1a761741: 16 missing keys, and all sixteen are in this
lane — research-dashboard 14, big-picture 1, doxa-research-map 1. Every other
owner is clean. All sixteen are already fixed by this branch's parent, which
PASSES under `--rev`.
2026-09-26 17:28:56 +00:00
..
all-people-groups Three maps asked the window which engine drew them; now they ask the map 2026-09-26 17:28:46 +00:00
big-picture Twenty-two keys the code asks for that no catalogue has ever had 2026-09-26 17:10:06 +00:00
cities-internet Cities with Internet: a page that asks for MapLibre never silently gets Mapbox 2026-09-26 17:01:36 +00:00
country-posters Country posters: the map's loading and error lines speak the reader's language 2026-09-26 16:55:14 +00:00
dashboard-plus-grid Decouple prose: no go-base / nuxtbase / nuxtinator / doxa-base names in plugin comments and docs 2026-09-26 17:28:45 +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 Decouple prose: no go-base / nuxtbase / nuxtinator / doxa-base names in plugin comments and docs 2026-09-26 17:28:45 +00:00
doxa-research-map A dialect is called "Arabic, Sudanese", and one click is one event 2026-09-26 17:28:46 +00:00
doxa-simple-map Six entries hand-rolled the RTL text plugin; the library already installs it 2026-09-26 13:35:57 +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 P8: a partner's own list is an address 2026-09-26 13:36:15 +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 Six entries hand-rolled the RTL text plugin; the library already installs it 2026-09-26 13:35:57 +00:00
people-groups-grid D1: a filter may be several values, and one function decides what matches 2026-09-26 17:28:46 +00:00
plugin-studio Plugin Studio rail laid out like plugin-designs/: one folder per bundle, its elements inside 2026-09-26 12:23:49 +00:00
pplr-data-maps Three maps asked the window which engine drew them; now they ask the map 2026-09-26 17:28:46 +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 Register the embedder-key gate so it can actually run 2026-09-26 17:10:06 +00:00
research-dashboard D1: a filter may be several values, and one function decides what matches 2026-09-26 17:28:46 +00:00
research-map-plus-grid The gate learns the aliases instead of being told them, and can read main 2026-09-26 17:28:56 +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 My UPG Neighbors: the cockpit, list, flower and send panels speak the reader's language 2026-09-26 17:10:06 +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