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 7e04a94c34 Kit landing 4c-3: the facet rail follows the chip bar into the library 
The rail's rendering is unchanged. What changed is where its last two plugin imports point. 4b had
already removed the research COLOUR and LABEL tables -- those stay in plugin-designs and arrive on
dashboardConfig.legend -- which left exactly two, and both now read the module that OWNS the
function rather than a re-export:
  useDashboardAggregations -> @map/composables/useFacetAggregation.js   (extracted by 4c-1)
  useDashboardShell        -> @map/composables/useDashboardSearch.js    (extracted by 4a)
Pointing at the shim instead would have been invisible and wrong in a way this tree has already
measured: check:filter-multivalue carries the note from landing 3 that a gate left at the plugin path
read the shim, found no predicate to object to, and PASSED VACUOUSLY.

The dead injects go too. `dataStore` and `searchSourceId` were here only to construct
useTreeLegendColors and useTreeLegendLabels, and 4b removed both constructions. An unused inject is a
claim about the host: a kit component that appears to need a research dataStore is one a new
dashboard will dutifully provide before finding out it was never read. The chip bar shed the same
pair in 4c-2.

check:filter-multivalue and check:legend-mirrors follow the file rather than being left pointing at a
path that no longer exists -- the multivalue gate fails loudly on a missing panel, which is what it
is for, and it is how I would have caught forgetting.

UNLIKE THE CHIP BAR, THIS ONE IS ON SCREEN. 4c-2's component is mounted by nobody, so its gate was
the whole story. The rail is mounted by research-dashboard.vue and is 770 lines of tree, search and
drag behaviour: "the imports resolve" says nothing about whether it still opens four trees by
default or whether its search still narrows. It needs eyes.

The barrel re-exports from the library for one cycle, so no importer's line changes in the same
landing that moves the file. documentation/reference-library-index.md regenerated.
2026-09-27 04:14:14 +00:00

260 lines
18 KiB
Markdown
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'`
- **DashboardFacetRail** — DashboardFacetRail (was Sidebar.vue) — RDASH redesign phase 2: the floating @map SemanticTreeLegend is DROPPED
`import … from '@map/components/dashboards/DashboardFacetRail.vue'`
- **DashboardFilterChips** — DashboardFilterChips — the live filterSet rendered as removable AND-stacked chips
`import … from '@map/components/dashboards/DashboardFilterChips.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'`
- **useFacetAggregation** — useFacetAggregation.js — count rows by a facet accessor, and roll the tail into one bucket.
`import … from '@map/composables/useFacetAggregation.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 <area>.<key>-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`.
Reference in a new issue View git blame Copy permalink