History

Doxa Maps a681fd3c65 A zoning gate that checks a list against what its author declared, not against my intuition Part 1 of making UPG-100 a reusable pattern (Driver via repo; dx-shepherd UPGPAT). Any project list — 7000 / 4700 / 3000 / 2000 / 700 — will be zoned by an agent who did not write this code. Zoning is human judgement (geography first, balanced with language), so a gate cannot decide whether a zoning is GOOD. It can decide whether it still matches what the author SAID, which turns "did I zone this right?" from a browser question into an exit code. ★ EVERY OBVIOUS RULE I WOULD HAVE WRITTEN FAILED THE REFERENCE IMPLEMENTATION. Measured against the live 28 zones and 2,107 records BEFORE writing the assertions, which is the only reason they are right: "every group in exactly one zone" → 112 groups are in two. 110 are the DEAF BLOC, and that is design-approved (legend-tree.js:151, slice 08): an affinity bloc's members also live in a geographic zone. So the rule is "at most one GEOGRAPHIC zone", with bloc zones declared as a second partition. "no group is unzoned" → 11 are, all JPN/CHN/MNG, plausibly deliberate. A gate cannot tell a deliberate exclusion from a silent drop; only a declaration can. "no two zones overlap" → 3 non-bloc overlaps exist, because "Scattered / Diaspora" (country_codes AND,CCK,GUF,USA) overlaps the regions it scatters across. A gate that fails on the only correct example of the thing it checks teaches people to disable it. ⚠ AND THE GATE FOUND A THIRD OVERLAP MY OWN HAND ANALYSIS HAD MISSED: deaf-cocos-islanders, in both oceania-indonesia and uncovered-scatter. I had filtered out every A017 group as "the design-approved deaf double-count" — but its TWO GEOGRAPHIC claims (CCK is in both zones' country lists) are a SEPARATE fact from its bloc membership. Conflating them is exactly what A2's bloc/geographic split exists to prevent, and the gate was right where I was wrong. Best argument for it existing. THE FIVE ASSERTIONS, and two would have caught this cycle's real defects before a browser did: A1 no zone resolves to zero groups ← `deaf` + the 5 wagf zones were in exactly this state, found only by generating all 28 and reading the log A2 at most one GEOGRAPHIC zone/group ← blocs declared; found the overlap above A3 orphan set EQUALS the declared set ← and a RESOLVED orphan fails too, deliberately: leaving a now-zoned group listed means the next real drop passes silently. An unmaintained declaration stops being evidence. A4 every selector type is supported ← the evaluator THROWS on an unknown type, at render time, on one zone's page; better as a build-time failure on the whole set A5 no zone over the declared budget ← a wildly oversized zone is usually a selector matching too much DECLARATIONS pre-filled with today's actuals and marked PENDING DRIVER, per UPGPAT: the 11 orphans and the 3 overlaps are recorded so the gate is green on arrival and any CHANGE fails. Both are in DRIVER-DECISIONS-DIGEST and neither membership was touched. VERIFIED: --self-test PASSes 12 cases, each assertion firing on a violation AND staying quiet on the declared exception (including the negative control that A2's bloc exemption is doing the work). Poison test on REAL data: removing ainu-japan from the declaration makes A3 fail with that slug, so a green run is meaningful rather than vacuous. ⚠ AND A package.json MISTAKE WORTH RECORDING. My first insertion put all three keys into the //scripts DOC block, because re.finditer over the whole file matched check:zone-census there (//scripts comes later in the file) — producing duplicate keys that json.load silently resolved last-wins, so the script COUNT WENT DOWN and `npm run check:zoning-declared` reported "Missing script". Fixed by scoping each insertion to its own block span. The diff is now exactly 3 added lines and reorders nothing: an earlier attempt that re-serialised the sorted object moved gospel's check:embed-contract and check:engine-contract, which is not mine to reshuffle in a shared file.		2026-09-27 03:36:19 +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-internet takes the locale-honouring fallback, and drops its English copy	2026-09-26 22:06:59 +00:00
country-posters	Country posters: a religion search names the family in the reader's language	2026-09-27 01:10:49 +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	The number's job was wrong, not its value	2026-09-27 02:17:35 +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	Every shipped link has evidence, and 1,412 of them did not	2026-09-27 01:26:50 +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	A zoning gate that checks a list against what its author declared, not against my intuition	2026-09-27 03:36:19 +00:00
people-groups-grid	The second consumer drops its copy of the highlighter	2026-09-27 01:16:50 +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	One guarded translator, and the fallback catalogue nobody needed	2026-09-26 22:06:57 +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	A bare-host embed under ?lang=ar now renders Arabic here too	2026-09-27 02:17:35 +00:00
research-dashboard	The layout drag was LTR-only, and my own migration was too eager	2026-09-27 02:17:35 +00:00
research-map-plus-grid	D3: the bus can point at a record without choosing it	2026-09-27 02:17:35 +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	One guarded translator, and the fallback catalogue nobody needed	2026-09-26 22:06:57 +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).