Change File Structuring + Add Webpack Compilation

Author: HikwaMehluli

.gitignore

@@ -10,7 +10,6 @@ lerna-debug.log*
 ai
 AGENTS.md
 /node_modules
-/dist
 
 # Editor directories and files
 .vscode/*

README.md

@@ -1,20 +1,20 @@
 # Zimbabwe National & Provincial Delimitation Maps
 
-Interactive SVG maps of Zimbabwe's 10 provinces with detailed ward boundaries. This prject is a demonstration of the practical use of interactive SVG graphics in websites and web apps.
+Interactive SVG maps of Zimbabwe's 10 provinces with detailed ward boundaries. I created this project demo to showcase the practical use of interactive SVG graphics in websites and web apps. This allowed me to upscale my creative technoligist services to local and some international clients.
 
 **View Live Demo:** https://hikwamehluli.github.io/Zimbabwe-National-and-Provincial-Delimitation-Maps
 
-Real world examples of websites in Zimbabwe which interactive SVG's:
+Real world examples of websites in Zimbabwe with interactive SVG's:
 - [Graylands Park](https://www.graylandspark.co.zw/stands)
 - [Northgate Estates](https://portal.northgateestates.co.zw)
 
 ## Features
 
-- :earth_africa: **National overview** — Zoomable SVG map of all 10 provinces on `index.html`
-- :city_sunset: **Per-province pages** — Detailed ward boundaries for each province
-- :mag: **Pan & zoom** — Drag to pan, buttons to zoom in/out/reset
-- :speech_balloon: **Tooltips** — Hover over any region to see its name (powered by TippyJS)
-- :handshake: **Touch-friendly** — Pinch-to-zoom and pan on mobile
+- **National overview** — Zoomable SVG map of all 10 provinces on `index.html`
+- **Per-province pages** — Detailed ward boundaries for each province with breadcrumb navigation
+- **Pan & zoom** — Drag to pan, buttons to zoom in/out/reset
+- **Tooltips** — Hover over any region to see its name (powered by TippyJS)
+- **Touch-friendly** — Pinch-to-zoom and pan on mobile
 
 ## Map index
 
@@ -34,38 +34,93 @@ Real world examples of websites in Zimbabwe which interactive SVG's:
 
 ## Technical stack
 
-- **Pure static site** — No build tools, no server, no framework. Open `.html` files directly in a browser.
+- **Pure static site** — No build tools required for viewing. Open `.html` files directly in a browser.
 - **SVG maps** — All map coordinates are inline `<polyline points="...">` in the HTML (no external data files)
-- **Libraries** (vendored in `js/`):
+- **Libraries** (bundled into `dist/js/app.js` via webpack):
   - `svg-pan-zoom` — Pan and zoom controls
   - `TippyJS` + `Popper.js` — Tooltip popups
-- **Font**: Roboto via Google Fonts
+- **Fonts**: Roboto + Pliant via Google Fonts
+- **Build tools**: Sass (SCSS → CSS), Webpack (JS bundling + CSS inlining)
+
+### Setup & scripts
+
+```bash
+npm install
+```
+
+| Script | Command | What it does |
+|--------|---------|-------------|
+| `npm run css-dev` | `sass --no-source-map --watch src/scss/_entry.scss:dist/css/app.css` | Compile SCSS → CSS (expanded output, watch mode) |
+| `npm run css-prod` | `sass --no-source-map --watch src/scss/_entry.scss:dist/css/app.css --style compressed` | Compile SCSS → CSS (minified, watch mode) |
+| `npm run js-dev` | `webpack --mode development --watch` | Bundle JS (development mode, watch for changes) |
+| `npm run js-prod` | `webpack --mode production --watch` | Bundle JS (production/minified, watch for changes) |
+| `npm run start:public` | `http-server -c-1` | Serve files locally at `http://localhost:8080` (no caching) |
+| `npm run start:root` | `http-server . -c-1` | Same as above, explicit `.` root directory |
+
+**dependencies:** `tippy.js` (tooltip library)
+
+**devDependencies:**
+| Package | Purpose |
+|---------|---------|
+| `http-server` | Local dev server with no caching |
+| `sass` | SCSS → CSS compiler |
+| `webpack` + `webpack-cli` | JS bundler — bundles `src/js/_entry.js` and its imports into `dist/js/app.js` |
+| `css-loader` + `style-loader` | Webpack loaders — inline `tippy.js/dist/tippy.css` into the JS bundle as `<style>` tags |
+
+### JS compilation pipeline
+
+1. **Entry point:** `src/js/_entry.js`
+2. **Webpack** resolves bare imports (`popper.min.js`, `svg-pan-zoom.min.js`) from `src/js/`, and npm imports (`tippy.js`) from `node_modules/`
+3. **CSS imports** (e.g. `tippy.js/dist/tippy.css`) are inlined into the bundle via `style-loader` + `css-loader`
+4. **Output:** a single `dist/js/app.js` loaded by all HTML pages
+
+Run `npm run js-dev` (development, unminified) or `npm run js-prod` (production, minified).
 
 ## Project structure
 
 ```
-css/
-  style.css       — Map colors, layout, typography
-  icons-map.css   — Icon font styles
-font/             — Icon font files
-js/
-  popper.min.js
-  tippy.min.js
-  svg-pan-zoom.min.js
-  script.js       — Initializes pan/zoom and tooltips
-*.html            — 11 HTML pages (1 national + 10 provincial)
+├── index.html              National overview map
+├── {province}.html          10 per-province ward maps
+├── dist/
+│   ├── js/
+│   │   └── app.js           Webpack-bundled JS (tippy.js, Popper, svg-pan-zoom + init code)
+│   ├── css/
+│   │   └── app.css          Compiled SCSS stylesheet
+│   └── font/                Custom icon font (interactive-map)
+├── src/
+│   ├── js/
+│   │   ├── _entry.js        Webpack entry point
+│   │   ├── popper.min.js    Vendored Popper.js
+│   │   ├── svg-pan-zoom.min.js
+│   │   └── tippy.min.js
+│   └── scss/                SCSS source files
+│       ├── _entry.scss      Entry point — imports all partials
+│       ├── style.scss       Map colours, layout, typography
+│       ├── breadcrumb.scss  Breadcrumb navigation styles
+│       └── icons-map.scss   Icon font @font-face + classes
+├── webpack.config.js        Webpack bundler configuration
+├── package.json             Build scripts, dependencies, devDependencies
+└── .gitignore
 ```
 
 ## Styling
 
-Map colours are controlled via CSS custom properties in `css/style.css`:
+Map colours are controlled via CSS custom properties defined in `src/scss/style.scss` (compiled to `dist/css/app.css`):
 
 | Variable | Default | Purpose |
 |----------|---------|---------|
+| `--bg-color` | `#d1d3be` | Page background |
 | `--color-active` | `#a8a965` | Fill colour of regions |
 | `--color-hover` | `#5f6035` | Hover colour |
 | `--color-stroke` | `black` | Stroke outline colour |
 
+### Rebuilding CSS
+
+```bash
+npm run css-dev    # watch mode, expanded output
+npm run css-prod   # watch mode, compressed output
+```
+
 ## Map Version
 
 Maps are based on the 2022-2023 delimitation exercise.

bulawayo.html

@@ -235,9 +235,6 @@ <h3>Provinces are constituent political entities of Zimbabwe. Zimbabwe currently
         </div>
     </main>
 
-    <script src='./dist/js/popper.min.js'></script>
-    <script src='./dist/js/tippy.min.js'></script>
-    <script src='./dist/js/svg-pan-zoom.min.js'></script>
-    <script src="./dist/js/script.js"></script>
+    <script src="./dist/js/app.js"></script>
 </body>
 </html>

dist/api/zim_facts.md

@@ -0,0 +1,18 @@
+# Zimbabwe Facts
+
+## Coat of arms of Zimbabwe
+The coat of arms of Zimbabwe was adopted on 21 September 1981, one year and five months after the national flag was adopted. Previously the coat of arms of Zimbabwe was identical to the former coat of arms of Rhodesia.
+
+## Meanings
+
+The official symbolism of the Zimbabwean coat of arms is as follows:
+
+- **Kudus**: the unity of purpose of Zimbabwe's various ethnic groups; the kudus are "a harmonious blend of black, white and brown".
+- **Earth mound**: the plants from which food and clothing is obtained.
+- Motto: the need to maintain the desire for national unity and the will to work for the preservation of freedom.
+- Green shield: the fertility of the country's soil and water. Blue and white wavy lines symbolise prosperity-bringing water.
+- Great Zimbabwe: the historical heritage of Zimbabwe.
+- Hoe and Rifle: the transition from war to peace.
+- Wreath of gold and green: the mining and agricultural enterprise which "protects our national economy".
+- Star: ancient symbol of hope for the future. Tinctured red to "remind us of the suffering of all our people and the need to avoid any recurrence of that suffering".
+- Great Zimbabwe Bird: distinctive national emblem.

dist/css/app.css

@@ -0,0 +1,4 @@
+Fontello - Typicons v2.0.2
+- minus
+- plus
+- refresh