# doxa-maps — one build, maps that embed everywhere

**A Vite bundler that turns each map into a self-contained web component.** One `bun run build` produces a
`doxa-maps/` folder you drop on any host — iframe it, script-embed it, ship it as a mobile app, or open the
whole thing as one SPA. **Same code, every screen.**

This README is a **show, don't tell** index. Skim the three tables, then jump to the section you need.

---

## Index

### The 5 plugin (app) types — from simplest to full app

| # | Capability | What it is | Example plugin | Section |
|---|------------|------------|----------------|---------|
| 1 | **Single element** | One folder → one bundle → one custom element. The lightest tier. | `doxa-vision-card` | [§1](#cap-1--single-element) |
| 2 | **Preset element (prop-table)** | ONE `root.vue` rendered N ways by preset props — one plugin, many maps. | `doxa-simple-map` (prayer · engagement · adoption) | [§1](#cap-2--preset-element-prop-table) |
| 3 | **Monolithic / multi-view** | A whole research map, all in one `root.vue`. | `doxa-research-map` | [§1](#cap-3--monolithic-research-map) |
| 4 | **Composite element** (nested-element SPA) | A composite element that nests other elements and wires them via props/events. | `my-upg-100-list` | [§1](#cap-4--composite-element) |
| 5 | **App shell** (nested-SPA) | The full doxa-maps app — every plugin in one deep-linkable page. | the doxa-maps SPA | [§1](#cap-5--app-shell--the-doxa-maps-app) |

### The 5 deployment methods

| # | Method | Status | Section |
|---|--------|--------|---------|
| 1 | **iframe embed** on any site | required | [§2](#deploy-1--iframe-embed) |
| 2 | **Mobile app** (Android / Capacitor) | required | [§2](#deploy-2--mobile-app) |
| 3 | **Direct-JS / research dashboard** (props + events + SRI) | required | [§2](#deploy-3--research-dashboard-direct-js) |
| 4 | **WordPress** (same artifacts, Custom HTML block) | deferred POC | [§3](#3-cli-commands--installs-per-deploy-method) |
| 5 | **Desktop** (Tauri) | deferred POC | [§3](#3-cli-commands--installs-per-deploy-method) |

### CLI commands + what to install

Install **[Bun](https://bun.sh)** once, then:

```bash
bun install        # download node_modules (one time)
bun run dev        # live plugin gallery at http://localhost:5173
bun run build      # build every plugin-designs/<map>/ → public/doxa-maps/
bun run serve      # preview the built tree
bun run phone      # build → Capacitor → Android APK on a connected device
```

The full command matrix (per deploy method, with prereqs like the Android SDK / JDK for mobile) lives in
**§3 → [docs/README-SECTION-3-cli-commands.md](./docs/README-SECTION-3-cli-commands.md)**.

> **The data caveat:** maps ship **without data**. Being JAMstack, each fetches its people-group data from an
> **API** at runtime, and its Mapbox token from a token endpoint (never baked into the bundle). That is what
> keeps them embeddable everywhere. See [docs/how-to.md](./docs/how-to.md).

---

## 1. Plugin types — one screenshot each

Every image below is a real map from this repo's `bun run build` output (`public/doxa-maps/`), captured in a
headless browser.

### CAP 1 — Single element

*One folder → one bundle → one custom element.* The lightest tier: `plugin-designs/doxa-vision-card/`. No map
engine, mounts instantly — a self-contained "mission vision card."

![Capability 1 — a single-element plugin (doxa-vision-card)](docs/readme-images/cap1-single-element.png)

### CAP 2 — Preset element (prop-table)

*One `root.vue`, many maps.* `plugin-designs/doxa-simple-map/` is a single parameterized profile. A preset
prop-table (`simple-map.instances.json`) renders it three ways — **prayer**, **engagement**, **adoption** —
each a standalone embeddable page. Same code, three maps.

| Prayer | Engagement | Adoption |
|--------|------------|----------|
| ![Prayer map](docs/readme-images/cap2-prayer.png) | ![Engagement map](docs/readme-images/cap2-engagement.png) | ![Adoption map](docs/readme-images/cap2-adoption.png) |

*All three come from the **same** `doxa-simple-map` plugin-design folder — differentiated only by preset props.*

### CAP 3 — Monolithic research map

*A whole research map, all from one `root.vue`.* `plugin-designs/doxa-research-map/` — the monolithic tier.

![Capability 3 — the monolithic research map](docs/readme-images/cap3-monolithic-research.png)

### CAP 4 — Composite element

*A composite element that nests lower-tier elements and wires them via props/events.* `plugin-designs/my-upg-100-list/` —
the UPG-100 list plugin. The composite (`upg-100-mfe`) plus its list pages:

| Composite element (`upg-100-mfe`) | List — page 1 | List — page 2 |
|-----------------------------------|---------------|---------------|
| ![UPG-100 composite](docs/readme-images/cap4-upg100-mfe.png) | ![UPG-100 list page 1](docs/readme-images/cap4-upg100-list-page1.png) | ![UPG-100 list page 2](docs/readme-images/cap4-upg100-list-page2.png) |

### CAP 5 — App shell / the doxa-maps app

*The top tier: every plugin in one deep-linkable single-page app* — `public/index.html`, generated by the
build. A vertical-tab sidebar groups every plugin by capability (CAP 5 → 1); clicking a row mounts that
plugin. This same SPA is the Capacitor mobile-app entry (see deploy 2).

![Capability 5 — the doxa-maps SPA (all plugins, one app)](docs/readme-images/cap5-doxa-maps-spa.png)

---

## 2. Deployment methods — one screenshot each

The exact commands + install prereqs for each are in **§3**. These shots show what each method looks like live.

### Deploy 1 — iframe embed

*The simplest.* One `<iframe>` line drops a map into an "embed section" on any partner site — no build step on
their site. Below: the prayer map running in an iframe inside a church's missions page.

![Deploy 1 — a map running in an iframe embed on a real site](docs/readme-images/deploy1-iframe.png)

### Deploy 2 — mobile app

*Same code, native app.* `bun run phone` wraps the SPA into an Android app via Capacitor. Below: the doxa-maps
SPA at a phone viewport — the exact web output that `cap:sync` copies into the APK.

<p align="center">
  <img src="docs/readme-images/deploy2-mobile-spa.png" alt="Deploy 2 — the doxa-maps SPA at phone viewport (the Capacitor mobile-app surface)" width="280">
</p>

### Deploy 3 — research dashboard (direct-JS)

*Props + events + SRI.* `plugin-designs/research-dashboard/` embeds via a direct `<script src>` (with a
Subresource-Integrity hash) so the map talks to the surrounding page — a coordinated-views dashboard where the
map, the facet rail, and the people-groups table brush-and-link over one store.

![Deploy 3 — the unified research dashboard (map + people-groups, connected via props/events)](docs/readme-images/deploy3-research-dashboard.png)

---

## 3. CLI commands + installs (per deploy method)

The complete, copy-paste command matrix — every deploy method mapped to its install prereqs and exact
commands, grounded in this branch's `package.json` — lives in its own doc:

**→ [docs/README-SECTION-3-cli-commands.md](./docs/README-SECTION-3-cli-commands.md)**

Quick reference:

| # | Deploy method | Install first | Command(s) |
|---|---------------|---------------|------------|
| 1 | **iframe embed** | Bun | `bun install` → `bun run build` → `bun run serve` (or drop `public/doxa-maps/` on any host) |
| 2 | **Mobile (Android)** | Bun · Android SDK + `adb` · JDK 17 · Capacitor (devDep) | `bun run phone` |
| 3 | **Direct-JS / dashboard** | Bun | `bun run build`, then paste the `<script src> + integrity` snippet from `manifest.json` |
| 4 | **WordPress** | Bun | `bun run build`, then paste the iframe/script snippet into a Custom HTML block *(deferred POC)* |
| 5 | **Desktop (Tauri)** | Rust + Tauri CLI *(not yet scaffolded)* | *deferred POC* |

Every build writes `public/doxa-maps/manifest.json` — a machine-readable index carrying the ready-to-paste
**iframe** and **`<script src>` + SRI** embed snippet for every map.

---

## More docs

| Read this | When |
|---|---|
| **[docs/README-SECTION-3-cli-commands.md](./docs/README-SECTION-3-cli-commands.md)** | the full per-method CLI + install matrix |
| **[docs/why.md](./docs/why.md)** | 2 min — the problem, the idea, one diagram |
| **[docs/tutorial.md](./docs/tutorial.md)** | build your first map, step by step |
| **[docs/how-to.md](./docs/how-to.md)** | task recipes (embed, data, mobile) |
| **[docs/README-longform.md](./docs/README-longform.md)** | the original story-first README (the "why maps" manifesto) |
| **[docs/architecture/](./docs/architecture/)** | the deep end — embeddability, app-wrappers, file map |

---

> **Bottom line: maps should be open source, run everywhere, and multiply.** This bundler makes each map a
> self-contained file that embeds on your site, your partners' sites, WordPress, and mobile — from one build.