doxa-life/doxa-maps
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
doxa-maps/documentation/reference-library-index.md
Doxa Maps 15820f1432 Dashboard kit, landing 3: the camera and the CSV exporter 
Both are zero-domain in the sense the spec meant: they import only `vue` and read
rows through accessors. Bodies are what research-dashboard shipped apart from the
two parameters the spec named and one policy object, and the old paths re-export
for one cycle.

★ THE FIRST STEP FOUND TWO GATES THAT READ THESE FILES BY PATH, which is why it is
now the first step. Landing 1 nearly disarmed check-facet-cascade the same way.
  internal/check-csv-export-shape.mjs does not import useCsvExport; it READS the
  source and extracts esc() out of it. Left at the plugin path it would have read
  the one-line shim, found no esc(), and failed with "could not extract esc()" — a
  gate accusing a working exporter because its subject moved.
  check-filter-multivalue.mjs — MINE — lists the same file in its PANELS array.
  Left at the plugin path it would have read the shim, found no predicate to
  object to, and PASSED VACUOUSLY. That is worse: a gate going quiet about the
  thing it guards. Both move in this commit.

THE COORDINATE IS A PARAMETER; WHAT MAKES A COORDINATE VALID IS NOT. `coords`
replaces only the READ of row.longitude / row.latitude, which is pray-tools'
spelling and not a universal one. Every guard stays shared: Number() on API
strings, 0 accepted per axis, the exact 0,0 null-island sentinel rejected, the
out-of-range check. A kit that let each caller re-implement that validation would
hand the next dashboard the same four bugs to rediscover.

★ AND THE OPTION WAS DEAD WHEN I FIRST WROTE IT. `coords` was accepted in the
signature and never passed to selectionBounds, so a caller could set it,
type-check clean, build clean, and watch it do nothing. This tree has paid for
that shape before — a defineProps on a component the custom element never binds —
and it is worse than a missing feature because it READS as supported. Nobody files
a bug against a knob they assume they misused. check:kit-options-reachable now
asserts, across all four shared composables, that every option accepted is used.

THE CAMERA'S EIGHT CONSTANTS ARE ONE DECISION, so CAMERA_POLICY exports them
together. The failure that prevents is a second dashboard re-picking them one at a
time and arriving at a camera that feels different from Big Picture's for no reason
anybody wrote down. It is read-only and deliberately not yet overridable: making
each a per-caller option means threading eight of them through every use, and no
consumer has asked for a different camera. Exporting the decision so it can be
cited is the half with a use today; saying so is better than shipping eight
options nobody passes.

THE EXPORTER GAINS exportLabel and sources. "Research Dashboard" was this
dashboard's name, and the provenance line said nothing about where the data came
from — which is what a provenance line is for. Both default to today's output, to
the byte.

★ AND THE NEW GATE HAD THE COMMENT HOLE TWICE IN ONE SITTING. First it searched
the raw body, and the comment beside the fixed call site says "`coords` IS PASSED
HERE" — so the mutant that removed the argument left it green. Then, stripping
comments only per-part, it split the signature's comment PROSE on commas and
reported that useCsvExport accepts `and`. Comments are text; every text search has
to say so, in both directions. That is the fourth variant of one mistake this
week, and all four were caught by running the mutant rather than by reading.

Library index regenerated in the same commit, 103 items. Source only.
STUDIO: needs a rebuild of research-dashboard and dashboard-plus-grid. The
internal/ hunk is one line in check-csv-export-shape.mjs.
2026-09-27 01:16:52 +00:00

17 KiB
Raw Blame History

REFERENCE-library-index — reusable pieces you can import into an app-profile

DERIVED FILE — do not hand-edit. Regenerate: node internal/generate-library-index.mjs Generated: run node internal/generate-library-index.mjs to refresh

You are a programmer (or an agent) building a map. This is the menu of REUSABLE, parameterized pieces the shared library/ offers. Import what you need with the @map/… alias; build your own custom code in your app-profile's src/ folder. Do NOT edit anything listed here unless you know what you're doing — these are shared across every map, and a change here can break other maps.

  • Three zones: library/ (this menu — reuse, don't edit) · plugin-designs/<map>/ (your sandbox — build anything) · internal/ (the build machine — never touch).
  • To make a new map: copy plugin-designs/template-bundle/, read its README, list your requirements, pick from below.

Components (reusable UI)

  • PeopleGroupDetail — (no description)
    import … from '@map/components/PeopleGroupDetail.vue'
  • ResearchMapFilterPanel — ResearchMapFilterPanel.vue — Multi-field filter UI for the research-map.
    import … from '@map/components/ResearchMapFilterPanel.vue'
  • ResearchMapSideMenu — ResearchMapSideMenu.vue — Side drawer specific to the research-map profile.
    import … from '@map/components/ResearchMapSideMenu.vue'
  • SideMenuDrawer — SideMenuDrawer.vue — Slide-in side panel for the map application.
    import … from '@map/components/SideMenuDrawer.vue'
  • ViewSelect — ViewSelect.vue — the "SELECT VIEW" switcher: a fieldset + legend wrapping a row of
    import … from '@map/components/ViewSelect.vue'
  • BarChart — BarChart.vue — THE SHARED HORIZONTAL BAR CHART (hand-rolled SVG, zero dependencies).
    import … from '@map/components/charts/BarChart.vue'
  • PinHint — PinHint.vue — the conversion coach-mark (bottom-center of any map).
    import … from '@map/components/hints/PinHint.vue'
  • ApproxPinNote — ApproxPinNote.vue — the ONE wording every map with people-group pins uses (APPROXPIN, 2026-09-26).
    import … from '@map/components/legends/ApproxPinNote.vue'
  • LegendDesktop — This component's chrome, read out of the catalogue. tStatic and not useI18n: these mount inside
    import … from '@map/components/legends/LegendDesktop.vue'
  • LegendMobile — (no description)
    import … from '@map/components/legends/LegendMobile.vue'
  • LegendProgressBar — LegendProgressBar — the prayer legend's header progress bar.
    import … from '@map/components/legends/LegendProgressBar.vue'
  • LegendRows — (no description)
    import … from '@map/components/legends/LegendRows.vue'
  • LegendTools — Does the Fly + Clusters toolbar render for this legend type?
    import … from '@map/components/legends/LegendTools.vue'
  • SemanticTreeLegend — SemanticTreeLegend — reusable hierarchical legend for any one-to-many semantic tree.
    import … from '@map/components/legends/SemanticTreeLegend.vue'
  • FullscreenButton — FullscreenButton.vue — Toggles fullscreen for the map host element.
    import … from '@map/components/map-controls/FullscreenButton.vue'
  • GeocoderComponent — GeocoderComponent.vue — Mapbox Geocoder search bar as a self-contained Vue component.
    import … from '@map/components/map-controls/GeocoderComponent.vue'
  • HamburgerButton — HamburgerButton.vue — Toggle button for the side menu drawer.
    import … from '@map/components/map-controls/HamburgerButton.vue'
  • HelpButton — HelpButton.vue — Opens the "About this map" help modal.
    import … from '@map/components/map-controls/HelpButton.vue'
  • LocationButton — LocationButton.vue — Flies the map to the user's current location via the
    import … from '@map/components/map-controls/LocationButton.vue'
  • MapControlButton — MapControlButton.vue — Shared base button for all map toolbar controls.
    import … from '@map/components/map-controls/MapControlButton.vue'
  • MapControlMenu — MapControlMenu.vue — the ONE menu every map control opens.
    import … from '@map/components/map-controls/MapControlMenu.vue'
  • MapToolbar — MapToolbar.vue — Positioned layout shell for map control buttons.
    import … from '@map/components/map-controls/MapToolbar.vue'
  • ShareButton — ShareButton.vue — Non-technical share modal for the map toolbar.
    import … from '@map/components/map-controls/ShareButton.vue'
  • ThemeToggleButton — ThemeToggleButton.vue — Switches the app between light and dark mode.
    import … from '@map/components/map-controls/ThemeToggleButton.vue'
  • ZoomInButton — ZoomInButton.vue — Increments the map zoom level by one step.
    import … from '@map/components/map-controls/ZoomInButton.vue'
  • ZoomOutButton — ZoomOutButton.vue — Decrements the map zoom level by one step.
    import … from '@map/components/map-controls/ZoomOutButton.vue'
  • PosterDialog — PosterDialog.vue — modal for previewing + rendering a poster export.
    import … from '@map/components/poster/PosterDialog.vue'
  • PosterPreview — PosterPreview.vue — scaled live preview of the poster composition.
    import … from '@map/components/poster/PosterPreview.vue'
  • PosterWall — PosterWall.vue — THE SHARED POSTER WALL.
    import … from '@map/components/poster/PosterWall.vue'
  • FooterSlot — FooterSlot.vue — STUB. Poster-rendering slot for FooterSlot.
    import … from '@map/components/poster/slots/FooterSlot.vue'
  • LegendSlot — LegendSlot.vue — STUB. Poster-rendering slot for LegendSlot.
    import … from '@map/components/poster/slots/LegendSlot.vue'
  • NorthArrowSlot — NorthArrowSlot.vue — STUB. Poster-rendering slot for NorthArrowSlot.
    import … from '@map/components/poster/slots/NorthArrowSlot.vue'
  • ScaleBarSlot — ScaleBarSlot.vue — STUB. Poster-rendering slot for ScaleBarSlot.
    import … from '@map/components/poster/slots/ScaleBarSlot.vue'
  • TitleSlot — TitleSlot.vue — renders the poster title strip.
    import … from '@map/components/poster/slots/TitleSlot.vue'
  • QaCorner — QaCorner.vue — the embeddable QA corner widget (bottom-right of any map).
    import … from '@map/components/qa/QaCorner.vue'
  • FilterDropdown — FilterDropdown.vue — SHARED (@map/components/search/FilterDropdown.vue).
    import … from '@map/components/search/FilterDropdown.vue'
  • SearchBar — SearchBar.vue — SHARED (@map/components/search/SearchBar.vue).
    import … from '@map/components/search/SearchBar.vue'
  • SearchFilterHeader — SearchFilterHeader.vue — SHARED (@map/components/search/SearchFilterHeader.vue).
    import … from '@map/components/search/SearchFilterHeader.vue'
  • DataTable — DataTable.vue — THE SHARED TABULATOR LIST VIEW.
    import … from '@map/components/tables/DataTable.vue'

Composables (reusable logic — Vue Composition API)

  • researchLegendOptions — researchLegendOptions.js — research-mfe-only options passed to the shared
    import … from '@map/composables/legends/researchLegendOptions.js'
  • useAffinityBlockLegendData — useAffinityBlockLegendData — 4-tier affinity-block legend data for SemanticTreeLegend.
    import … from '@map/composables/legends/useAffinityBlockLegendData.js'
  • useLanguageFamilyLegendData — useLanguageFamilyLegendData — language-family legend rows with
    import … from '@map/composables/legends/useLanguageFamilyLegendData.js'
  • useLegendData — useLegendData — builds a unified, data-driven legend item tree
    import … from '@map/composables/legends/useLegendData.js'
  • useWagfRegionsLegendData — useWagfRegionsLegendData — 3-tier WAGF Regions legend for SemanticTreeLegend.
    import … from '@map/composables/legends/useWagfRegionsLegendData.js'
  • useMapPoster — useMapPoster — render a Mapbox GL map to a poster-grade PNG or PDF blob.
    import … from '@map/composables/poster/useMapPoster.js'
  • usePosterLayout — usePosterLayout — slot positioning math for poster compositions.
    import … from '@map/composables/poster/usePosterLayout.js'
  • printInPlace — printInPlace.js — SHARED (@map/composables/printInPlace.js).
    import … from '@map/composables/printInPlace.js'
  • retryableAsyncComponent — retryableAsyncComponent.js — SHARED (@map/composables/retryableAsyncComponent.js).
    import … from '@map/composables/retryableAsyncComponent.js'
  • useAvatarGenerator — Avatar Generator Composable
    import … from '@map/composables/useAvatarGenerator.js'
  • useCountryOutline — useCountryOutline.js — country boundary OUTLINE overlay on country search.
    import … from '@map/composables/useCountryOutline.js'
  • useCsvExport — useCsvExport.js — ★ SHARED LIBRARY CODE (dashboard-kit landing 3). Two parameters make it
    import … from '@map/composables/useCsvExport.js'
  • useDashboardLayout — useDashboardLayout.js — reusable drag-resize + persistence engine for the CMV dashboard grid.
    import … from '@map/composables/useDashboardLayout.js'
  • useDocumentFont — useDocumentFont.js — register a self-hosted @font-face at DOCUMENT level, once per page.
    import … from '@map/composables/useDocumentFont.js'
  • useEdgeScrollAffordance — useEdgeScrollAffordance — the gray "you can scroll past this" edge strips.
    import … from '@map/composables/useEdgeScrollAffordance.js'
  • useGeocoderSearch — Shared geocoder→map search logic (kind-switch + Mapbox filter builder + the
    import … from '@map/composables/useGeocoderSearch.js'
  • useMapAttribution — useMapAttribution.js — the data-credit line every map MUST carry.
    import … from '@map/composables/useMapAttribution.js'
  • useMapClustering — useMapClustering.js — Map Clustering Composable
    import … from '@map/composables/useMapClustering.js'
  • useMapData — useMapData.js - Map Data Loading Composable
    import … from '@map/composables/useMapData.js'
  • useMapEvents — useMapEvents.js - Map Event Handlers Composable
    import … from '@map/composables/useMapEvents.js'
  • useMapFly — useMapFly.js - Map Navigation/Fly Composable
    import … from '@map/composables/useMapFly.js'
  • useMapInstance — useMapInstance.js — Map Initialization Composable
    import … from '@map/composables/useMapInstance.js'
  • useMapLayers — useMapLayers.js - Map Layers Composable
    import … from '@map/composables/useMapLayers.js'
  • useMapPacket — useMapPacket — render a multi-page "prayer packet" PDF for a map selection.
    import … from '@map/composables/useMapPacket.js'
  • useMapProvider — useMapProvider.js — resolve the active map engine ("provider").
    import … from '@map/composables/useMapProvider.js'
  • useMapSelection — useMapSelection.js - Map Selection Composable
    import … from '@map/composables/useMapSelection.js'
  • useMapTheme — useMapTheme.js — shared light/dark theme for every map profile.
    import … from '@map/composables/useMapTheme.js'
  • useOptionalT — ★ NO .-SHAPED EXAMPLES IN THIS FILE'S COMMENTS. check:i18n-keys-exist reads any such
    import … from '@map/composables/useOptionalT.js'
  • usePosterPrints — usePosterPrints.js — THE print actions every poster wall shares.
    import … from '@map/composables/usePosterPrints.js'
  • usePplrInstance — usePplrInstance.js — per-map "instance store" mediator.
    import … from '@map/composables/usePplrInstance.js'
  • usePrayedLocally — usePrayedLocally.js — the "my dot glows" encouragement loop.
    import … from '@map/composables/usePrayedLocally.js'
  • usePrayerStatistics — usePrayerStatistics.js — the ONE authoritative prayer-coverage source of truth.
    import … from '@map/composables/usePrayerStatistics.js'
  • useSearch — useSearch.js — Local geocoder search composable
    import … from '@map/composables/useSearch.js'
  • useSelectedPin — useSelectedPin.js - Selected Pin Highlight + Animated GO Marker
    import … from '@map/composables/useSelectedPin.js'
  • useSelectionBus — useSelectionBus.js — hand-rolled pub/sub brushing-and-linking bus.
    import … from '@map/composables/useSelectionBus.js'
  • useSelectionCamera — useSelectionCamera.js — "select rows in the table, the map zooms to that selection."
    import … from '@map/composables/useSelectionCamera.js'
  • useShadowStyles — useShadowStyles.js — Shadow DOM Style Injection
    import … from '@map/composables/useShadowStyles.js'
  • useSharedMapToken — useSharedMapToken.js — ONE page, ONE map token, shared by every element on it.
    import … from '@map/composables/useSharedMapToken.js'
  • useTextHighlight — highlightRanges(value, indices) — wrap each matched index range in
    import … from '@map/composables/useTextHighlight.js'

Utilities (pure helper functions)

  • ClusterHelpers — ClusterHelpers.js — Pure helpers shared across clustering modes.
    import … from '@map/utils/ClusterHelpers.js'
  • DataSourceManager — Back-compat shim. The real DataSourceManager.js lives in the api/ seam
    import … from '@map/utils/DataSourceManager.js'
  • MSTClusteringUtil — MSTClusteringUtil.js
    import … from '@map/utils/MSTClusteringUtil.js'
  • NetworkClusteringUtil — NetworkClusteringUtil.js
    import … from '@map/utils/NetworkClusteringUtil.js'
  • apiBaseUrl — Back-compat shim. The real apiBaseUrl.js lives in the api/ seam folder.
    import … from '@map/utils/apiBaseUrl.js'
  • colocation — colocation.js — which people groups share ONE coordinate on a map (APPROXPIN, 2026-09-26).
    import … from '@map/utils/colocation.js'
  • countries-meta — countries-meta.js — a PORT of DX-life's config/countries-meta.ts (326 lines), the rollup
    import … from '@map/utils/countries-meta.js'
  • embedBase — embedBase.js — Where THIS bundle's built tree is served from, resolved at runtime.
    import … from '@map/utils/embedBase.js'
  • geoUtils — geoUtils.js — Geographic / GeoJSON Utility Functions
    import … from '@map/utils/geoUtils.js'
  • html — html.js — the two helpers every HTML string built in library/ must use (CRITIC-3, 2026-09-26).
    import … from '@map/utils/html.js'
  • loadPinnedUmd — loadPinnedUmd — load a PINNED, integrity-checked UMD library and capture it WITHOUT touching the host
    import … from '@map/utils/loadPinnedUmd.js'
  • viewportScrim — viewportScrim.js — make a position:fixed full-screen SCRIM actually cover the VIEWPORT,
    import … from '@map/utils/viewportScrim.js'

Stores (Pinia — shared state)

  • dataStore — dataStore.js — Centralized data cache
    import … from '@map/stores/dataStore.js'
  • mapStore — Map Store - Centralized state management for all map instances
    import … from '@map/stores/mapStore.js'
  • uiStore — UI Store - Centralized UI state management
    import … from '@map/stores/uiStore.js'

Constants (never-change values)

  • cdn — cdn.js — EVERY third-party script and stylesheet a plugin loads at runtime, pinned to an EXACT version
    import … from '@map/constants/cdn.js'
  • mapDefaults — mapDefaults.js — Default map initialization settings
    import … from '@map/constants/mapDefaults.js'
  • posterDefaults — posterDefaults.js — default margins, bleed, slot sizes, and typography
    import … from '@map/constants/posterDefaults.js'
  • posterSizes — posterSizes.js — preset poster dimensions (US + ISO).
    import … from '@map/constants/posterSizes.js'
  • zoom — zoom.js - Centralized Zoom Configuration
    import … from '@map/constants/zoom.js'

Data (static reference tables)

  • countries — "value": "AFG",
    import … from '@map/data/countries.json'
  • country-posters — "stats": {
    import … from '@map/data/country-posters.json'
  • iso-numeric-to-alpha2 — "4":"AF","8":"AL","12":"DZ","24":"AO","32":"AR","36":"AU","40":"AT","50":"BD",
    import … from '@map/data/iso-numeric-to-alpha2.json'
  • langFamilyByIso — "aar": "Afro-Asiatic",
    import … from '@map/data/langFamilyByIso.json'
  • langFamilyByLanguage — {"Chamacoco":"Zamucoan","Ninam":"Yanomaman","Yagua":"Yaguan","Muinane":"Witotoan","Finnish":"Uralic","Hill Mar
    import … from '@map/data/langFamilyByLanguage.json'

API / data sources (@map/api)

The library provides the data-source mechanism; you declare WHICH sources your map uses in your own src/api/sources.json. Add a REST API, CSV, or MCP source by adding one entry — no code. Mechanism (do not edit): @map/api/_registry.js, @map/api/DataSourceManager.js.

Colors (@map/colors)

The library provides the color-strategy registry (the mechanism). Shared color taxonomies (religion, adoption, engagement, language-family) live here. Your map's OWN colors live in your app-profile's src/colors/ folder — strategy .js files auto-merge OVER the shared set for your map only, so editing them can't break other maps. Mechanism (do not edit): @map/colors/_registry.js.