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 de24e633f9 The region card becomes a shared component the plugin consumes 
The Driver's ask, and his negotiating point with the DX-life author depends on it
being true: the components cloned from their /regions page must be REUSABLE,
PARAMETERIZED components in the shared library, not private to one plugin. He named
the failure mode himself — someone opens the regions plugin folder and finds the
components are not reusable after all. I checked before building, and for the UI he
named he was right: only the DATA and LOGIC had been promoted.

So library/components/regions/RegionSectionCard.vue takes title, summary, countries
and footerLabel, emits what was clicked, and knows nothing about where regions come
from. The plugin version fetched its own data and owned the layout, which is exactly
what made it unusable anywhere else.

THE DESIGN TRAVELS WITH IT. The card carries the region-card, countries-grid and
country-link CSS lifted unchanged — including the RTL chevron rules, where a
"forward" chevron must mirror in Arabic while a disclosure caret must not, and where
[dir="rtl"] .region-card__icon at 0-2-0 would otherwise beat the 0-1-0 --open
modifier. A consumer gets the look, not a lookalike. It needs dir on an ancestor for
that mirroring, which is documented in the file as a requirement.

★ THE CARD OWNS THE DISCLOSURE ROW, after the first cut got it wrong. I put the
"View country posters" toggle in the consumer's slot — and immediately had to copy
the footer-link styling and the rotating caret back into the plugin, re-creating the
duplication this extraction exists to remove. A disclosure inside a card is a card
feature; only the revealed CONTENT is the consumer's, so PosterWall stays in the
slot with its fourteen props and does not become every consumer's API.

★ THE CHEVRON IS INLINE, NOT A <use href="#id">. The plugin declared the symbol once
and every card referenced it. A shadow-root id is scoped to that root, so the same
card mounted elsewhere would reference a symbol that does not exist — and an
unresolved <use> renders NOTHING, silently. The plugin's own comment warns about
that class for external hrefs; a cross-root id fails the same way.

check:regions-uses-library is registered and asserts BOTH halves: the plugin imports
from @map/ and renders the component, AND no longer holds the markup or the CSS it
delegated. A reusability claim only a human can audit is one that rots; this one
fails the day someone re-inlines a copy. Two negative controls keep it honest — the
plugin still uses its own .rl-root classes, and the other tab is asserted NOT to use
the card yet, so the check describes what is extracted rather than what I hope for.

Two of my own mechanical edits produced valid JS and broken content on the way here,
both caught by checking rather than by the parser: a line-numbered splice that
dropped PosterWall's closing /> (fixed by locating boundaries by CONTENT), and a
line-filtered CSS deletion that left 9 orphaned declarations and braces at 12/21
(fixed by removing rules brace-aware, then re-validating the concatenated stylesheet
rather than trusting check:sfc-parse, which only proves the JS parses).
2026-09-27 03:26:36 +00:00

18 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'
  • RegionSectionCard — RegionSectionCard.vue — one region as a card: a heading, a summary line, a grid of its countries,
    import … from '@map/components/regions/RegionSectionCard.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'
  • useDashboardSearch — useDashboardSearch.js — the ONE free-text search the whole dashboard shares.
    import … from '@map/composables/useDashboardSearch.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.