@countriesdb/widget 0.1.1

package/LICENSE

@@ -0,0 +1,26 @@
+PROPRIETARY LICENSE
+
+Copyright (c) NAYEE LLC
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are the 
+proprietary property of NAYEE LLC.
+
+PERMITTED USES:
+- You may use this Software in your applications and projects
+- You may distribute this Software as part of your applications
+
+PROHIBITED USES:
+- You may NOT modify, adapt, or create derivative works of this Software
+- You may NOT reverse engineer, decompile, or disassemble this Software
+- You may NOT redistribute modified versions of this Software
+- You may NOT remove or alter any copyright notices or proprietary markings
+
+The Software is provided "AS IS", without warranty of any kind, express or 
+implied, including but not limited to the warranties of merchantability, 
+fitness for a particular purpose and noninfringement.
+
+For licensing inquiries, please contact NAYEE LLC at https://nayee.net
+
+

package/README.md

@@ -0,0 +1,202 @@
+# @countriesdb/widget
+
+**Country and state/province select widget with ISO 3166-1 and ISO 3166-2 codes.** Auto-populates dropdown menus with up-to-date country and subdivision data in multiple languages. Perfect for forms, location selection, and address validation.
+
+📖 **[Full Documentation](https://countriesdb.com/docs)** | 🌐 **[Website](https://countriesdb.com)**
+
+## Getting Started
+
+**⚠️ API Key Required:** This widget requires a CountriesDB API key to function. You must create an account at [countriesdb.com](https://countriesdb.com) to obtain your public API key. Test accounts are available with limited functionality. Once you have your key, you can use it to initialize the widget.
+
+- 🔑 [Get your API key](https://countriesdb.com) - Create an account
+- 📚 [View documentation](https://countriesdb.com/docs) - Complete API reference and examples
+- 💬 [Support](https://countriesdb.com) - Get help and support
+
+## Features
+
+- ✅ **ISO 3166 compliant** - Uses official ISO 3166-1 country codes and ISO 3166-2 subdivision codes
+- ✅ **Multilingual support** - Country and subdivision names in multiple languages
+- ✅ **Always up-to-date** - Regularly updated database with latest country and subdivision data
+- ✅ **Easy integration** - Works with plain HTML, no framework required
+- ✅ **Auto-initialization** - Automatically populates select elements on page load
+- ✅ **TypeScript support** - Full type definitions included
+
+## Installation
+
+```bash
+npm install @countriesdb/widget
+```
+
+## Quick Start
+
+1. **Get your API key** - Sign up at [countriesdb.com](https://countriesdb.com) to get your public API key (test accounts available with limited functionality)
+2. **Install the package** - `npm install @countriesdb/widget`
+3. **Initialize the widget** - See usage examples below
+
+For detailed documentation, visit [countriesdb.com/docs](https://countriesdb.com/docs).
+
+## Usage
+
+### Script Tag (UMD)
+
+```html
+<script src="https://unpkg.com/@countriesdb/widget@latest/dist/index.js"></script>
+<script>
+  CountriesWidget.CountriesWidgetLoad({
+    publicKey: 'YOUR_PUBLIC_KEY',
+    defaultLanguage: 'en'
+  });
+</script>
+
+<!-- Add CSS classes to your select elements -->
+<select class="country-selection" name="country">
+  <option value="">Select Country</option>
+</select>
+
+<select class="subdivision-selection" name="state" data-country="country">
+  <option value="">Select State/Province</option>
+</select>
+```
+
+### ES Module
+
+```html
+<script type="module">
+  import { CountriesWidgetLoad } from '@countriesdb/widget';
+  
+  CountriesWidgetLoad({
+    publicKey: 'YOUR_PUBLIC_KEY',
+    defaultLanguage: 'en'
+  });
+</script>
+```
+
+### Node.js / Bundler
+
+```javascript
+import { CountriesWidgetLoad } from '@countriesdb/widget';
+
+CountriesWidgetLoad({
+  publicKey: 'YOUR_PUBLIC_KEY',
+  backendUrl: 'https://api.countriesdb.com',
+  defaultLanguage: 'en',
+  enableGeolocation: true
+});
+```
+
+## Configuration
+
+### Options
+
+- `publicKey` (required): Your CountriesDB public API key. [Get your API key](https://countriesdb.com) by creating an account.
+- `backendUrl` (optional): Backend API URL (defaults to script origin or `https://api.countriesdb.com`)
+- `defaultLanguage` (optional): Default language for country/subdivision names
+- `forcedLanguage` (optional): Force a specific language
+- `showSubdivisionType` (optional): Show subdivision type names (default: `true`)
+- `followRelated` (optional): Enable forward navigation between related countries/subdivisions
+- `followUpward` (optional): Enable reverse navigation to parent subdivisions
+- `allowParentSelection` (optional): Allow selecting parent subdivisions (default: `false`)
+- `isoCountryNames` (optional): Use ISO country names (default: `false`)
+- `subdivisionRomanizationPreference` (optional): Preferred romanization system
+- `preferLocalVariant` (optional): Prefer local name variants (default: `false`)
+- `countryNameFilter` (optional): Custom function to filter/transform country names
+- `subdivisionNameFilter` (optional): Custom function to filter/transform subdivision names
+- `autoInit` (optional): Auto-initialize on load (default: `true`)
+
+### Data Attributes
+
+#### Country Select
+
+- `class="country-selection"` (required): Identifies the country select element
+- `data-name`: Unique name for linking subdivisions
+- `data-preselected`: Preselected country code
+- `data-default-value`: Default option value
+- `data-label`: Default option label
+
+#### Subdivision Select
+
+- `class="subdivision-selection"` (required): Identifies the subdivision select element
+- `data-country`: Link to country select by `data-name`
+- `data-country-code`: Direct country code (if no linked country select)
+- `data-preselected`: Preselected subdivision code
+- `data-default-value`: Default option value
+- `data-label`: Default option label
+- `data-prefer-official`: Prefer official subdivisions
+- `data-nested{level}-prefix`: Prefix for nested subdivision levels
+
+## Events
+
+The widget dispatches custom `countriesWidget:update` events on select elements:
+
+```javascript
+document.addEventListener('countriesWidget:update', (event) => {
+  console.log('Widget updated:', event.detail);
+  // {
+  //   value: 'US',
+  //   selectedValues: ['US'],
+  //   name: 'country1',
+  //   country: null,
+  //   isSubdivision: false,
+  //   type: 'country',
+  //   reason: 'regular' | 'geoip' | 'preselected' | 'reload' | 'follow'
+  // }
+});
+```
+
+## Examples
+
+### Basic Usage
+
+```html
+<select class="country-selection" data-name="country1"></select>
+<select class="subdivision-selection" data-country="country1"></select>
+```
+
+### With Preselected Values
+
+```html
+<select class="country-selection" data-name="country1" data-preselected="US"></select>
+<select class="subdivision-selection" data-country="country1" data-preselected="US-CA"></select>
+```
+
+### Multi-Select Countries
+
+```html
+<select class="country-selection" data-name="countries" multiple></select>
+```
+
+### Custom Name Filter
+
+```javascript
+CountriesWidgetLoad({
+  publicKey: 'YOUR_PUBLIC_KEY',
+  countryNameFilter: (code, name, language, item) => {
+    if (code === 'US') {
+      return 'United States of America';
+    }
+    return name;
+  }
+});
+```
+
+## API Reference
+
+### `CountriesWidgetLoad(options)`
+
+Main initialization function. Returns a Promise that resolves when initialization is complete.
+
+For complete API documentation, visit [countriesdb.com/docs](https://countriesdb.com/docs).
+
+## Resources
+
+- 🌐 [Website](https://countriesdb.com) - Main CountriesDB website
+- 📚 [Documentation](https://countriesdb.com/docs) - Complete API reference and guides
+- 🔑 [Get API Key](https://countriesdb.com) - Create account and get your public key
+- 💬 [Support](https://countriesdb.com) - Get help and contact support
+
+## License
+
+PROPRIETARY - Copyright (c) NAYEE LLC. See [LICENSE](LICENSE) for details.
+
+**Developed by [NAYEE LLC](https://nayee.net)**
+

package/dist/dom-manipulation.d.ts

@@ -0,0 +1,29 @@
+/**
+ * DOM manipulation utilities
+ */
+import type { SelectElement } from './types';
+import type { Country, Subdivision } from '@countriesdb/widget-core';
+/**
+ * Initialize a select element with default option
+ */
+export declare function initializeSelect(select: SelectElement, fallbackLabel?: string, isSubdivision?: boolean): void;
+/**
+ * Populate a select element with countries
+ */
+export declare function populateCountrySelect(select: SelectElement, countries: Country[], language: string, countryNameFilter?: (code: string, name: string, lang: string, item: Country) => string | false | null | undefined): void;
+/**
+ * Populate a select element with subdivisions
+ */
+export declare function buildSubdivisionOptionsHTML(subdivisions: Subdivision[], select: SelectElement, language: string, showSubdivisionType: boolean, allowParentSelection: boolean, subdivisionNameFilter?: (code: string, originalName: string, language: string, countryCode: string | null, item: Subdivision) => string | false | null | undefined): string;
+/**
+ * Apply preselected value to a select element
+ */
+export declare function applyPreselectedValue(select: SelectElement, value: string): void;
+/**
+ * Handle API error by showing error message in select
+ */
+export declare function handleApiError(select: SelectElement, errorMessage: string | Error): void;
+/**
+ * Parse boolean from string value
+ */
+export declare function parseBoolean(value: string | null | undefined): boolean;

package/dist/dom-manipulation.js

@@ -0,0 +1,133 @@
+/**
+ * DOM manipulation utilities
+ */
+import { applyCountryNameFilter, sortCountries, buildSubdivisionTree, flattenSubdivisionOptions, parseNestingPrefixes, } from '@countriesdb/widget-core';
+/**
+ * Initialize a select element with default option
+ */
+export function initializeSelect(select, fallbackLabel = 'Not Applicable', isSubdivision = false) {
+    const isMultiple = select.hasAttribute('multiple');
+    // For multi-select, don't add default option or use data-label/data-default-value
+    if (isMultiple) {
+        select.innerHTML = '';
+        // Remove data-label and data-default-value for multi-select (they're ignored)
+        if (select.dataset.label !== undefined) {
+            delete select.dataset.label;
+        }
+        if (select.dataset.defaultValue !== undefined) {
+            delete select.dataset.defaultValue;
+        }
+    }
+    else {
+        const dataLabel = select.dataset.label;
+        const dataDefaultValue = select.dataset.defaultValue;
+        const label = dataLabel || fallbackLabel;
+        const defaultValue = dataDefaultValue ?? '';
+        select.innerHTML = `<option value="${defaultValue}">${label}</option>`;
+        if (dataLabel !== undefined) {
+            select.dataset.label = dataLabel;
+        }
+        if (dataDefaultValue !== undefined) {
+            select.dataset.defaultValue = dataDefaultValue;
+        }
+    }
+    if (isSubdivision) {
+        select.disabled = true;
+    }
+}
+/**
+ * Populate a select element with countries
+ */
+export function populateCountrySelect(select, countries, language, countryNameFilter) {
+    // Apply filter and get display names
+    let filteredCountries = applyCountryNameFilter(countries, countryNameFilter, language);
+    // Sort if filter was applied
+    if (countryNameFilter) {
+        filteredCountries = sortCountries(filteredCountries, language);
+    }
+    // Clear existing options (except default)
+    const defaultOption = select.querySelector('option[value=""]') ||
+        (select.dataset.defaultValue ? select.querySelector(`option[value="${select.dataset.defaultValue}"]`) : null);
+    const defaultValue = select.dataset.defaultValue ?? '';
+    // Keep default option if it exists
+    select.innerHTML = defaultOption ? defaultOption.outerHTML : `<option value="${defaultValue}">${select.dataset.label || '&mdash;'}</option>`;
+    // Add country options
+    filteredCountries.forEach((country) => {
+        const option = document.createElement('option');
+        option.value = country.iso_alpha_2;
+        option.textContent = country._displayName;
+        select.appendChild(option);
+    });
+}
+/**
+ * Populate a select element with subdivisions
+ */
+export function buildSubdivisionOptionsHTML(subdivisions, select, language, showSubdivisionType, allowParentSelection, subdivisionNameFilter) {
+    const tree = buildSubdivisionTree(subdivisions);
+    // Parse nesting prefixes from data attributes
+    const dataAttributes = {};
+    for (let lvl = 1; lvl <= 10; lvl++) {
+        const key = `nested${lvl}Prefix`;
+        const value = select.dataset[key];
+        if (value !== undefined) {
+            dataAttributes[`nested${lvl}Prefix`] = value;
+        }
+        else {
+            break;
+        }
+    }
+    const prefixes = parseNestingPrefixes(dataAttributes);
+    const isMultiple = select.hasAttribute('multiple');
+    const labelKey = showSubdivisionType ? 'full_name' : 'name';
+    let html = '';
+    // For multi-select, don't add default option
+    if (!isMultiple) {
+        const defaultLabel = select.dataset.label || '&mdash;';
+        const defaultValue = select.dataset.defaultValue ?? '';
+        html = `<option value="${defaultValue}">${defaultLabel}</option>`;
+    }
+    html += flattenSubdivisionOptions(tree, 0, prefixes, labelKey, language, allowParentSelection, subdivisionNameFilter);
+    return html;
+}
+/**
+ * Apply preselected value to a select element
+ */
+export function applyPreselectedValue(select, value) {
+    if (!value || value.trim() === '') {
+        return;
+    }
+    const isMultiple = select.hasAttribute('multiple');
+    if (isMultiple) {
+        // For multi-select, parse comma-separated values
+        const values = value
+            .split(',')
+            .map((v) => v.trim())
+            .filter((v) => v !== '');
+        // Select all matching options
+        Array.from(select.options).forEach((option) => {
+            option.selected = values.includes(option.value);
+        });
+    }
+    else {
+        // Single select: set single value
+        select.value = value;
+    }
+}
+/**
+ * Handle API error by showing error message in select
+ */
+export function handleApiError(select, errorMessage) {
+    const message = errorMessage instanceof Error ? errorMessage.message : errorMessage;
+    const defaultValue = select.dataset.defaultValue ?? '';
+    select.innerHTML += `<option value="${defaultValue}" disabled>${message}</option>`;
+}
+/**
+ * Parse boolean from string value
+ */
+export function parseBoolean(value) {
+    if (value === null || value === undefined) {
+        return false;
+    }
+    const lowered = String(value).trim().toLowerCase();
+    return !(lowered === '0' || lowered === 'false');
+}

package/dist/event-system.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Event system for widget updates
+ */
+import type { SelectElement, UpdateEventDetail } from './types';
+/**
+ * Dispatch a custom update event for widget changes
+ */
+export declare function dispatchUpdateEvent(select: SelectElement, detail?: Partial<UpdateEventDetail>): void;
+/**
+ * Check if an event was initiated by the widget (not user)
+ */
+export declare function isWidgetInitiatedEvent(event: Event): boolean;
+/**
+ * Mark an event as widget-initiated
+ */
+export declare function markEventAsWidgetInitiated(event: Event): void;

package/dist/event-system.js

@@ -0,0 +1,43 @@
+/**
+ * Event system for widget updates
+ */
+/**
+ * Dispatch a custom update event for widget changes
+ */
+export function dispatchUpdateEvent(select, detail = {}) {
+    let selectedValues = [];
+    if (select.multiple) {
+        // For multi-select, selectedOptions is a HTMLCollection, convert to array
+        selectedValues = Array.from(select.selectedOptions || [])
+            .map((opt) => opt.value)
+            .filter((v) => v !== '');
+    }
+    else {
+        // For single-select, use value
+        selectedValues = select.value ? [select.value] : [];
+    }
+    const evt = new CustomEvent('countriesWidget:update', {
+        bubbles: true,
+        detail: {
+            value: select.value || '',
+            selectedValues,
+            name: select.dataset.name || null,
+            country: select.dataset.country || null,
+            isSubdivision: select.classList.contains('subdivision-selection'),
+            ...detail,
+        },
+    });
+    select.dispatchEvent(evt);
+}
+/**
+ * Check if an event was initiated by the widget (not user)
+ */
+export function isWidgetInitiatedEvent(event) {
+    return event.isWidgetInitiated === true;
+}
+/**
+ * Mark an event as widget-initiated
+ */
+export function markEventAsWidgetInitiated(event) {
+    event.isWidgetInitiated = true;
+}

package/dist/follow-logic.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Follow logic for related and upward navigation
+ */
+import type { SelectElement, WidgetState } from './types';
+/**
+ * Trigger follow logic when a subdivision is selected
+ */
+export declare function triggerFollowLogic(select: SelectElement, apiKey: string, backendUrl: string, state: WidgetState, followRelated: boolean, followUpward: boolean, updateSubdivisionSelectFn: (select: SelectElement, apiKey: string, countryCode: string) => Promise<void>): Promise<void>;
+/**
+ * Handle follow_related from subdivision change event
+ */
+export declare function handleFollowRelatedFromSubdivision(select: SelectElement, apiKey: string, backendUrl: string, state: WidgetState, followRelated: boolean, updateSubdivisionSelectFn: (select: SelectElement, apiKey: string, countryCode: string) => Promise<void>): Promise<void>;
+/**
+ * Handle follow_upward from subdivision change event
+ */
+export declare function handleFollowUpwardFromSubdivision(select: SelectElement, apiKey: string, backendUrl: string, state: WidgetState, followUpward: boolean, updateSubdivisionSelectFn: (select: SelectElement, apiKey: string, countryCode: string) => Promise<void>): Promise<void>;
+/**
+ * Handle follow_upward from country change event
+ */
+export declare function handleFollowUpwardFromCountry(select: SelectElement, apiKey: string, backendUrl: string, state: WidgetState, followUpward: boolean, updateSubdivisionSelectFn: (select: SelectElement, apiKey: string, countryCode: string) => Promise<void>): Promise<void>;

package/dist/follow-logic.js

@@ -0,0 +1,213 @@
+/**
+ * Follow logic for related and upward navigation
+ */
+import { dispatchUpdateEvent } from './event-system';
+/**
+ * Trigger follow logic when a subdivision is selected
+ */
+export async function triggerFollowLogic(select, apiKey, backendUrl, state, followRelated, followUpward, updateSubdivisionSelectFn) {
+    if (!followRelated && !followUpward) {
+        return;
+    }
+    const linkedCountrySelect = document.querySelector(`.country-selection[data-name="${select.dataset.country}"]`);
+    // Only work if country is single-select (never when country is multi)
+    if (!linkedCountrySelect || linkedCountrySelect.multiple) {
+        return;
+    }
+    const allSubs = state.subdivisionsMap.get(select);
+    if (!allSubs) {
+        return;
+    }
+    // For follow_upward, only work if subdivision is single-select
+    if (followUpward && select.multiple) {
+        return;
+    }
+    const selectedCode = select.value;
+    if (!selectedCode) {
+        return;
+    }
+    const picked = allSubs.find((s) => s.code === selectedCode);
+    if (!picked) {
+        return;
+    }
+    // follow_related
+    if (followRelated && picked.related_country_code) {
+        const targetCountry = picked.related_country_code;
+        const targetSubdivision = picked.related_subdivision_code;
+        const relatedSubsSelect = document.querySelector(`.subdivision-selection[data-country="${linkedCountrySelect.dataset.name}"]`);
+        if (relatedSubsSelect && targetSubdivision) {
+            relatedSubsSelect.dataset._widgetTempPreselect = targetSubdivision; // one-time preselect
+        }
+        if (linkedCountrySelect.value !== targetCountry) {
+            linkedCountrySelect.value = targetCountry;
+            dispatchUpdateEvent(linkedCountrySelect, { type: 'country', reason: 'regular' });
+            await updateSubdivisionSelectFn(linkedCountrySelect, apiKey, targetCountry);
+        }
+        else {
+            if (relatedSubsSelect && targetSubdivision) {
+                await updateSubdivisionSelectFn(relatedSubsSelect, apiKey, targetCountry);
+            }
+        }
+    }
+    // follow_upward
+    if (followUpward && picked.is_subdivision_of) {
+        const parentCode = picked.is_subdivision_of.parent_country_code;
+        const parentSub = picked.is_subdivision_of.subdivision_code;
+        if (parentSub) {
+            const relatedSubsSelect = document.querySelector(`.subdivision-selection[data-country="${linkedCountrySelect.dataset.name}"]`);
+            // Only preselect if subdivision is single-select (follow_upward doesn't work with multi)
+            if (relatedSubsSelect && !relatedSubsSelect.multiple) {
+                relatedSubsSelect.dataset._widgetTempPreselect = parentSub; // one-time preselect
+            }
+        }
+        if (linkedCountrySelect.value !== parentCode) {
+            linkedCountrySelect.value = parentCode;
+            dispatchUpdateEvent(linkedCountrySelect, { type: 'country', reason: 'regular' });
+            await updateSubdivisionSelectFn(linkedCountrySelect, apiKey, parentCode);
+        }
+        else if (parentSub) {
+            const relatedSubsSelect = document.querySelector(`.subdivision-selection[data-country="${linkedCountrySelect.dataset.name}"]`);
+            if (relatedSubsSelect && !relatedSubsSelect.multiple) {
+                await updateSubdivisionSelectFn(relatedSubsSelect, apiKey, parentCode);
+            }
+        }
+    }
+}
+/**
+ * Handle follow_related from subdivision change event
+ */
+export async function handleFollowRelatedFromSubdivision(select, apiKey, backendUrl, state, followRelated, updateSubdivisionSelectFn) {
+    if (!followRelated) {
+        return;
+    }
+    const linkedCountrySelect = document.querySelector(`.country-selection[data-name="${select.dataset.country}"]`);
+    // Only work if country is single-select (never when country is multi)
+    if (!linkedCountrySelect || linkedCountrySelect.multiple) {
+        return;
+    }
+    const allSubs = state.subdivisionsMap.get(select);
+    if (!allSubs) {
+        return;
+    }
+    // Get selected code (for multi-select, use first selected value)
+    const selectedCode = select.multiple
+        ? (select.selectedOptions[0]?.value || null)
+        : select.value;
+    if (!selectedCode) {
+        return;
+    }
+    const picked = allSubs.find((s) => s.code === selectedCode);
+    if (!picked || !picked.related_country_code) {
+        return;
+    }
+    const targetCountry = picked.related_country_code;
+    const targetSubdivision = picked.related_subdivision_code;
+    const relatedSubsSelect = document.querySelector(`.subdivision-selection[data-country="${linkedCountrySelect.dataset.name}"]`);
+    if (relatedSubsSelect && targetSubdivision) {
+        relatedSubsSelect.dataset.preselected = targetSubdivision;
+    }
+    if (linkedCountrySelect.value !== targetCountry) {
+        linkedCountrySelect.value = targetCountry;
+        dispatchUpdateEvent(linkedCountrySelect, { type: 'country', reason: 'regular' });
+        await updateSubdivisionSelectFn(linkedCountrySelect, apiKey, targetCountry);
+    }
+    else {
+        if (relatedSubsSelect && targetSubdivision) {
+            await updateSubdivisionSelectFn(relatedSubsSelect, apiKey, targetCountry);
+        }
+    }
+}
+/**
+ * Handle follow_upward from subdivision change event
+ */
+export async function handleFollowUpwardFromSubdivision(select, apiKey, backendUrl, state, followUpward, updateSubdivisionSelectFn) {
+    if (!followUpward) {
+        return;
+    }
+    // Disable for multi-select subdivisions
+    if (select.multiple) {
+        return;
+    }
+    const linkedCountrySelect = document.querySelector(`.country-selection[data-name="${select.dataset.country}"]`);
+    // Only work if country is single-select (never when country is multi)
+    if (!linkedCountrySelect || linkedCountrySelect.multiple) {
+        return;
+    }
+    const allSubs = state.subdivisionsMap.get(select);
+    if (!allSubs) {
+        return;
+    }
+    const selectedCode = select.value;
+    if (!selectedCode) {
+        return;
+    }
+    const picked = allSubs.find((s) => s.code === selectedCode);
+    if (!picked || !picked.is_subdivision_of) {
+        return;
+    }
+    const parentCode = picked.is_subdivision_of.parent_country_code;
+    const parentSub = picked.is_subdivision_of.subdivision_code;
+    if (parentSub) {
+        const relatedSubsSelect = document.querySelector(`.subdivision-selection[data-country="${linkedCountrySelect.dataset.name}"]`);
+        if (relatedSubsSelect) {
+            relatedSubsSelect.dataset.preselected = parentSub;
+        }
+    }
+    if (linkedCountrySelect.value !== parentCode) {
+        linkedCountrySelect.value = parentCode;
+        dispatchUpdateEvent(linkedCountrySelect, { type: 'country', reason: 'follow' });
+        await updateSubdivisionSelectFn(linkedCountrySelect, apiKey, parentCode);
+    }
+    else if (parentSub) {
+        const relatedSubsSelect = document.querySelector(`.subdivision-selection[data-country="${linkedCountrySelect.dataset.name}"]`);
+        if (relatedSubsSelect) {
+            await updateSubdivisionSelectFn(relatedSubsSelect, apiKey, parentCode);
+        }
+    }
+}
+/**
+ * Handle follow_upward from country change event
+ */
+export async function handleFollowUpwardFromCountry(select, apiKey, backendUrl, state, followUpward, updateSubdivisionSelectFn) {
+    // Only works when country is single-select (never for multi-select)
+    if (!followUpward || select.multiple) {
+        return;
+    }
+    const countries = state.countriesMap.get(select);
+    if (!countries) {
+        return;
+    }
+    const chosen = select.value;
+    if (!chosen) {
+        return;
+    }
+    const picked = countries.find((c) => c.iso_alpha_2 === chosen);
+    if (!picked || !picked.is_subdivision_of) {
+        return;
+    }
+    const parentCode = picked.is_subdivision_of.parent_country_code;
+    const parentSub = picked.is_subdivision_of.subdivision_code;
+    if (select.value !== parentCode) {
+        if (parentSub) {
+            const linkedSubdivisionSelects = Array.from(document.querySelectorAll(`.subdivision-selection[data-country="${select.dataset.name}"]`));
+            for (const s of linkedSubdivisionSelects) {
+                // Only preselect if subdivision is single-select (follow_upward doesn't work with multi)
+                if (!s.multiple) {
+                    s.dataset.preselected = parentSub;
+                }
+            }
+        }
+        select.value = parentCode;
+        dispatchUpdateEvent(select, { type: 'country', reason: 'regular' });
+        await updateSubdivisionSelectFn(select, apiKey, parentCode);
+    }
+    else if (parentSub) {
+        const linkedSubdivisionSelects = Array.from(document.querySelectorAll(`.subdivision-selection[data-country="${select.dataset.name}"]`));
+        for (const s of linkedSubdivisionSelects) {
+            // Only update if subdivision is single-select
+            if (!s.multiple) {
+                await updateSubdivisionSelectFn(s, apiKey, parentCode);
+            }
+        }
+    }
+}