diff --git a/README.md b/README.md index dd0e08aa7..4ce68d256 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,21 @@ standalone embeds *and* the building blocks of a full site. is a runtime setting, not baked in. You can point a map at a different API — or swap the map engine itself (Mapbox ↔ MapLibre) — by changing config, no rebuild. Portable and future-proof. +## Why it's fast (one self-contained file) + +Everything a map needs is built into **one file** — the Vue runtime, the components, and the CSS +are all inlined. The browser makes **one request** and the map runs. There's no waterfall of extra +downloads and no dependency on a separate Vue CDN being online or version-matched. + +- **One output file.** The JS carries its own CSS (`cssCodeSplit: false`) and its own Vue, built as + a single IIFE. Nothing to wire up, nothing that can 404 on its own. +- **Faster than loading Vue from a CDN.** A CDN copy of Vue is an extra request plus a version you + have to keep in sync; inlining removes both. Fewer moving parts, less technical debt. +- **Lean.** Tree-shaking drops unused code, so the single file stays small even though it's complete. + +(The one deliberate exception is the heavy PDF-export library — loaded from a CDN only if someone +actually exports — so the everyday map load never pays for it.) + ## Quickstart Bun is required (`bun.lock` is the committed lockfile — install from ). diff --git a/app-profiles/README.md b/app-profiles/README.md index d55e1f8f1..ad53c6b2d 100644 --- a/app-profiles/README.md +++ b/app-profiles/README.md @@ -1,224 +1,72 @@ # app-profiles/ — where YOUR maps live -> **Zero-context summary:** the `doxa-maps` repo is a **shared Apache template** -> in `../library/` (aliased `@map`). You never edit it per-map. Instead, you make a -> folder **here**, in `app-profiles//`, and build *your* map by -> composing the template's building blocks. Your folder is **yours** — your -> color strategy, your API connections, your i18n. The template is **shared** — -> Apache-2.0, common to everyone, propagated to every map on the next build. +The shared template lives in `../library/` (aliased `@map`) — you never edit it per-map. +You build your map by making a folder **here**, `app-profiles//`, 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). -If you only remember one thing: **shared template → `app-profiles//` → -your custom color + API + i18n.** Read on for exactly where each piece goes. - ---- - -## The bundle pattern (folder → bundle → profiles → script tags) - -This is the whole convention in one picture: +## The pattern in one picture ``` -app-profiles// ← a FOLDER here = one JS BUNDLE named after the folder - ├── index.js ← entry: registers the custom element, discovers profiles - ├── overview.vue ← one .vue = one APP PROFILE (FLAT — directly in the folder) - └── detail.vue ← another profile in the SAME bundle +app-profiles// ← 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/doxa-maps//.js (one file) + builds to ─────────────► public/doxa-maps//.js (one file) ``` -- **Folder name = bundle name.** `app-profiles//` builds to exactly one - file, `public/doxa-maps//.js`. (Folders starting with `_` or `.` are - skipped — handy for staging WIP.) -- **Each `.vue` in the folder = one app profile.** Profiles sit **flat, directly - in the bundle folder** — there is **no `profiles/` subfolder**. A profile is one - map screen; one bundle can hold many. (See `template-bundle/` for a minimal - two-profile example.) -- **Each profile is reachable from a single ` ``` ---- - -## The embed template (paste-ready — just swap the bundle name) - -Copy this onto any page. Change **``** to your folder name and -**`profile`** to one of your `.vue` filenames (without `.vue`). Nothing else -changes between maps. - -```html - - - - - - - - - - -``` - -- The ` -# +# 3. embed the script tag + element (dev staging at `npm run dev` shows a paste-ready snippet) ``` -The dev staging index (`npm run dev`, served at `/`) also **auto-detects** the new -folder and shows a copy-paste embed snippet for each profile — no edit to any -index needed. See `../CONTRIBUTING.md` for the build-vs-dev distinction. +## 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 `app-profiles//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 model — three zones, never mixed +## The one hosting variable -``` -doxa-maps/ -├── library/ (alias @map) ← THE SHARED APACHE TEMPLATE — do not customize per-map -│ ├── components/ reusable map UI (legends, toolbar, buttons, drawers) -│ ├── composables/ useMapInstance, useMapData, useMapLayers, … -│ ├── colors/ the menu of ways to color pins (one strategy per file) -│ ├── config/ posterDefaults.js · posterSizes.js (map defaults: constants/mapDefaults.js) -│ ├── api/ DataSourceManager (csv | api | rest-api), sources.json, registry -│ ├── i18n/locales/ 11 base languages: ar de en es fr hi it pt ro ru zh -│ ├── utils/ shared helpers -│ └── stores/ Pinia stores (map / data / ui) -│ -├── internal/ ← THE BUNDLER'S OWN BUILD SCRIPTS — never edited by map builders -│ -└── app-profiles// ← YOUR PRIVATE APP PROFILE — everything here is yours - ├── index.js bundle entry (registers the web component) - ├── *.vue your map screen(s) — FLAT in the folder, one per profile - └── data/*.json (optional) your own bundled data -``` +The only thing that changes between hosting modes is the ` - - - - ``` -(`profile` must match a `.vue` filename in this folder, without the `.vue`.) - -## Build / preview - -```bash -# build just this bundle → public/doxa-maps/template-bundle/template-bundle.js -BUNDLE=template-bundle npm run build:bundle - -# or build every bundle -npm run build - -# preview in isolation (HMR) — open the staging page for this bundle -npm run dev -``` - -## Add a third profile - -Drop another flat `.vue` next to the others — no config to edit: - -```bash -# app-profiles/template-bundle/template-map-c.vue -npm run build # → still one file, template-bundle.js, now with 3 profiles -``` - -Then request it: ``. +(`profile` must match a `.vue` filename in this folder, without `.vue`. Add a third profile by +dropping another flat `.vue` next to these and rebuilding — no config to edit.) ## See also -- `src/README.md` — the sandbox layout and the two import styles. -- `../../docs/tutorial.md` — the 3 zones + 3 rules, in one page. -- `../../docs/reference.md` — the menu of reusable `@map/…` pieces. -- `../README.md` — the app-profiles authoring guide (bundle pattern, embed template). -- `../../CONTRIBUTING.md` — build vs dev, the two CDN modes, partner-site embedding. -- `../doxa-simple-map/index.js` — a fuller, real-map reference bundle entry. +- `src/README.md` — sandbox layout · `../README.md` — the app-profiles authoring guide +- `../../docs/tutorial.md` — 3 zones + 3 rules in one page · `../../docs/reference.md` — the `@map/…` menu +- `../doxa-simple-map/index.js` — a fuller, real-map reference entry