tunisian-departments

A comprehensive Node.js library for working with Tunisian governorates (departments). Includes an interactive SVG map web component with accurate geographical boundaries for all 24 governorates.

Features

• All 24 Tunisian governorates with official codes
• Interactive SVG map as a Web Component
• Hover highlighting with tooltips
• Click to select with info panel
• Search/filter functionality
• Neighboring governorates display
• Regional groupings
• Zero dependencies
• Works in browser and Node.js

Installation

npm install tunisian-departments

Quick Start

Browser (Web Component)

<script src="node_modules/tunisian-departments/dist/tunisian-map.js"></script>

<tunisian-map></tunisian-map>

Or via CDN (after publishing):

<script src="https://unpkg.com/tunisian-departments/dist/tunisian-map.js"></script>

<tunisian-map></tunisian-map>

Node.js

const {
  getAllDepartments,
  lookupByCode,
  lookupByLabel,
  filterByText,
  getRegion,
  getNeighbors
} = require('tunisian-departments');

// Get all departments
const all = getAllDepartments();
console.log(all); // [{code: '11', label: 'Tunis'}, ...]

// Lookup by code
console.log(lookupByCode('51')); // 'Sousse'

// Lookup by label
console.log(lookupByLabel('Mahdia')); // '53'

// Filter by text
console.log(filterByText('sou')); // [{code: '51', label: 'Sousse'}]

// Get region
console.log(getRegion('11')); // 'Grand Tunis'

// Get neighbors
console.log(getNeighbors('11')); // ['12', '13', '14']

API Reference

Functions

| Function | Description | Example | |----------|-------------|---------| | getAllDepartments() | Returns array of all departments | [{code, label}, ...] | | lookupByCode(code) | Get label by code | lookupByCode('51') → 'Sousse' | | lookupByLabel(label) | Get code by label (case-insensitive) | lookupByLabel('tunis') → '11' | | filterByText(text) | Filter by text fragment | filterByText('bi') → [{code: '23', label: 'Bizerte'}] | | getRegion(code) | Get region name | getRegion('51') → 'Centre-Est' | | getNeighbors(code) | Get neighboring department codes | getNeighbors('51') → ['21', '22', '41', '52'] |

Web Component API

const map = document.querySelector('tunisian-map');

// Select a department
map.select('51');

// Get selected
const selected = map.getSelected();

// Highlight multiple
map.highlight(['11', '12', '13', '14']); // Highlight Grand Tunis

// Clear highlights
map.clearHighlight();

// Get all departments
map.getAllDepartments();

// Filter
map.filter('sou');

Events

// Selection changed
map.addEventListener('department-select', (e) => {
  console.log(e.detail.code);       // '51'
  console.log(e.detail.department); // {code: '51', label: 'Sousse'}
  console.log(e.detail.region);     // 'Centre-Est'
});

// Map ready
map.addEventListener('map-ready', (e) => {
  console.log('Map loaded');
});

Governorates List

| Code | Label | Region | |------|-------|--------| | 11 | Tunis | Grand Tunis | | 12 | Ariana | Grand Tunis | | 13 | Ben Arous | Grand Tunis | | 14 | Manouba | Grand Tunis | | 21 | Nabeul | Nord-Est | | 22 | Zaghouan | Nord-Est | | 23 | Bizerte | Nord-Est | | 31 | Béja | Nord-Ouest | | 32 | Jendouba | Nord-Ouest | | 33 | Kef | Nord-Ouest | | 34 | Siliana | Nord-Ouest | | 41 | Kairouan | Centre-Ouest | | 42 | Kasserine | Centre-Ouest | | 43 | Sidi Bouzid | Centre-Ouest | | 51 | Sousse | Centre-Est | | 52 | Monastir | Centre-Est | | 53 | Mahdia | Centre-Est | | 61 | Sfax | Centre-Est | | 71 | Gafsa | Sud-Ouest | | 72 | Tozeur | Sud-Ouest | | 73 | Kebili | Sud-Ouest | | 81 | Gabès | Sud-Est | | 82 | Medenine | Sud-Est | | 83 | Tataouine | Sud-Est |

Regions

• Grand Tunis: Tunis, Ariana, Ben Arous, Manouba
• Nord-Est: Nabeul, Zaghouan, Bizerte
• Nord-Ouest: Béja, Jendouba, Kef, Siliana
• Centre-Est: Sousse, Monastir, Mahdia, Sfax
• Centre-Ouest: Kairouan, Kasserine, Sidi Bouzid
• Sud-Ouest: Gafsa, Tozeur, Kebili
• Sud-Est: Gabès, Medenine, Tataouine

License

MIT

Credits

Map data from SimpleMaps - Free for commercial use.