@countriesdb/widget 0.1.23 → 0.1.24

package/README.md

@@ -89,7 +89,6 @@ CountriesWidgetLoad({
 ### 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`)
@@ -99,6 +98,7 @@ CountriesWidgetLoad({
 - `isoCountryNames` (optional): Use ISO country names (default: `false`)
 - `subdivisionRomanizationPreference` (optional): Preferred romanization system
 - `preferLocalVariant` (optional): Prefer local name variants (default: `false`)
+- `preferOfficialSubdivisions` (optional): Prefer official ISO subdivisions (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`)
@@ -143,6 +143,25 @@ document.addEventListener('countriesWidget:update', (event) => {
 });
 ```
 
+It also emits `countriesWidget:ready` whenever a country or subdivision select
+finishes loading options (initial load and subsequent reloads, like when a country
+changes). Listen once on `document` to react as soon as the widget is fully wired:
+
+```javascript
+document.addEventListener('countriesWidget:ready', (event) => {
+  console.log('Select ready:', event.detail);
+  // {
+  //   value: 'US',
+  //   selectedValues: ['US'],
+  //   name: 'country1',
+  //   country: null,
+  //   isSubdivision: false,
+  //   type: 'country' | 'subdivision',
+  //   phase: 'initial' | 'reload'
+  // }
+});
+```
+
 ## Examples
 
 ### Basic Usage
@@ -196,7 +215,7 @@ For complete API documentation, visit [countriesdb.com/docs](https://countriesdb
 
 ## License
 
-PROPRIETARY - Copyright (c) NAYEE LLC. See [LICENSE](LICENSE) for details.
+PROPRIETARY - Copyright (c) NAYEE LLC. See [LICENSE](https://github.com/countriesdb/countriesdb/blob/main/packages/npm/widget/LICENSE) for details.
 
 **Developed by [NAYEE LLC](https://nayee.net)**
 

package/dist/dom-manipulation.js

@@ -153,8 +153,6 @@ export function handleApiError(select, errorMessage, replace = false) {
     else {
         select.innerHTML += `<option value="${defaultValue}" disabled>${formattedMessage}</option>`;
     }
-    // Ensure select is enabled so users can see the error
-    select.disabled = false;
 }
 /**
  * Parse boolean from string value

package/dist/event-system.d.ts

@@ -1,11 +1,15 @@
 /**
  * Event system for widget updates
  */
-import type { SelectElement, UpdateEventDetail } from './types';
+import type { ReadyEventDetail, SelectElement, UpdateEventDetail } from './types';
 /**
  * Dispatch a custom update event for widget changes
  */
 export declare function dispatchUpdateEvent(select: SelectElement, detail?: Partial<UpdateEventDetail>): void;
+/**
+ * Dispatch a custom ready event once a select has been populated.
+ */
+export declare function dispatchReadyEvent(select: SelectElement, detail?: Partial<ReadyEventDetail>): void;
 /**
  * Check if an event was initiated by the widget (not user)
  */

package/dist/event-system.js

@@ -29,6 +29,34 @@ export function dispatchUpdateEvent(select, detail = {}) {
     });
     select.dispatchEvent(evt);
 }
+/**
+ * Dispatch a custom ready event once a select has been populated.
+ */
+export function dispatchReadyEvent(select, detail = {}) {
+    const selectedValues = select.multiple
+        ? Array.from(select.selectedOptions || [])
+            .map((opt) => opt.value)
+            .filter((v) => v !== '')
+        : select.value
+            ? [select.value]
+            : [];
+    const evt = new CustomEvent('countriesWidget:ready', {
+        bubbles: true,
+        detail: {
+            value: select.value || '',
+            selectedValues,
+            name: select.dataset.name || null,
+            country: select.dataset.country || null,
+            isSubdivision: select.classList.contains('subdivision-selection'),
+            type: select.classList.contains('subdivision-selection')
+                ? 'subdivision'
+                : 'country',
+            phase: 'initial',
+            ...detail,
+        },
+    });
+    select.dispatchEvent(evt);
+}
 /**
  * Check if an event was initiated by the widget (not user)
  */

package/dist/index.esm.js

@@ -154,8 +154,6 @@ function handleApiError(select, errorMessage, replace = false) {
     else {
         select.innerHTML += `<option value="${defaultValue}" disabled>${formattedMessage}</option>`;
     }
-    // Ensure select is enabled so users can see the error
-    select.disabled = false;
 }
 
 /**
@@ -189,6 +187,34 @@ function dispatchUpdateEvent(select, detail = {}) {
     });
     select.dispatchEvent(evt);
 }
+/**
+ * Dispatch a custom ready event once a select has been populated.
+ */
+function dispatchReadyEvent(select, detail = {}) {
+    const selectedValues = select.multiple
+        ? Array.from(select.selectedOptions || [])
+            .map((opt) => opt.value)
+            .filter((v) => v !== '')
+        : select.value
+            ? [select.value]
+            : [];
+    const evt = new CustomEvent('countriesWidget:ready', {
+        bubbles: true,
+        detail: {
+            value: select.value || '',
+            selectedValues,
+            name: select.dataset.name || null,
+            country: select.dataset.country || null,
+            isSubdivision: select.classList.contains('subdivision-selection'),
+            type: select.classList.contains('subdivision-selection')
+                ? 'subdivision'
+                : 'country',
+            phase: 'initial',
+            ...detail,
+        },
+    });
+    select.dispatchEvent(evt);
+}
 /**
  * Check if an event was initiated by the widget (not user)
  */
@@ -465,7 +491,8 @@ async function setupSubdivisionSelection(apiKey, backendUrl, state, config) {
             : null;
         // Check if linked country select is multi-select (not allowed)
         if (linkedCountrySelect && linkedCountrySelect.hasAttribute('multiple')) {
-            handleApiError(select, 'Cannot link to multi-select country. Use data-country-code instead.', true);
+            const defaultValue = select.dataset.defaultValue ?? '';
+            select.innerHTML = `<option value="${defaultValue}" disabled>Error: Cannot link to multi-select country. Use data-country-code instead.</option>`;
             continue;
         }
         // No direct link → maybe data-country-code
@@ -475,7 +502,8 @@ async function setupSubdivisionSelection(apiKey, backendUrl, state, config) {
                 await updateSubdivisionSelect(select, apiKey, backendUrl, state, config, select.dataset.countryCode);
             }
             else {
-                handleApiError(select, 'No country select present');
+                const defaultValue = select.dataset.defaultValue ?? '';
+                select.innerHTML += `<option value="${defaultValue}" disabled>Error: No country select present</option>`;
             }
         }
         // Always dispatch an update event for user-initiated subdivision changes
@@ -521,8 +549,10 @@ async function updateSubdivisionSelect(select, apiKey, backendUrl, state, config
             // Use GeoIP only if data-preselected attribute is not set at all
             const shouldUseGeoIP = preselectedValue === undefined || preselectedValue === null;
             // Check if this subdivision select prefers official subdivisions
-            const preferOfficial = select.hasAttribute('data-prefer-official') ||
-                config.preferOfficialSubdivisions;
+            // Use data attribute if present, otherwise use config
+            const preferOfficial = select.hasAttribute('data-prefer-official')
+                ? true
+                : config.preferOfficialSubdivisions;
             const languageHeaders = CountriesDBClient.getLanguageHeaders(config.forcedLanguage, config.defaultLanguage);
             const subdivisionsResult = await CountriesDBClient.fetchSubdivisions({
                 apiKey,
@@ -608,6 +638,10 @@ async function updateSubdivisionSelect(select, apiKey, backendUrl, state, config
         finally {
             // Mark initialization as complete
             state.isInitializing.delete(select);
+            dispatchReadyEvent(select, {
+                type: 'subdivision',
+                phase: isReload ? 'reload' : 'initial',
+            });
             // Only fire 'reload' if this is a reload, not initial load
             if (isReload && !valueSetByWidget) {
                 dispatchUpdateEvent(select, {
@@ -619,7 +653,8 @@ async function updateSubdivisionSelect(select, apiKey, backendUrl, state, config
     }
     else if (!select.dataset.country ||
         !document.querySelector(`.country-selection[data-name="${select.dataset.country}"]`)) {
-        handleApiError(select, 'No country select present');
+        const defaultValue = select.dataset.defaultValue ?? '';
+        select.innerHTML += `<option value="${defaultValue}" disabled>Error: No country select present</option>`;
     }
 }
 /**
@@ -648,7 +683,8 @@ async function setupCountrySelection(apiKey, backendUrl, state, config, subdivis
         if (name && seenNames[name]) {
             select.removeAttribute('data-name');
             initializeSelect(select, '&mdash;');
-            handleApiError(select, 'Duplicate field');
+            const defaultValue = select.dataset.defaultValue ?? '';
+            select.innerHTML += `<option value="${defaultValue}" disabled>Error: Duplicate field</option>`;
             continue;
         }
         if (name) {
@@ -749,6 +785,10 @@ async function setupCountrySelection(apiKey, backendUrl, state, config, subdivis
         finally {
             // Mark initialization as complete
             state.isInitializing.delete(select);
+            dispatchReadyEvent(select, {
+                type: 'country',
+                phase: 'initial',
+            });
             // If no preselected and no geoip selection happened, emit a regular update
             if (!valueSetByWidget) {
                 dispatchUpdateEvent(select, { type: 'country', reason: 'regular' });
@@ -855,29 +895,23 @@ async function CountriesWidgetLoad(options = {}) {
  * Get configuration from options or script URL parameters
  */
 function getConfigFromOptionsOrScript(options) {
-    // Check for global config first (for bundled widgets that need config before auto-init)
-    const globalConfig = typeof window !== 'undefined' && window.CountriesDBConfig
-        ? window.CountriesDBConfig
-        : null;
     // Try to get config from script URL (for backward compatibility with widget.blade.php)
     let scriptUrl = null;
     try {
         let loaderScript = null;
         // First try document.currentScript (works during script execution)
-        // But only if it matches the widget pattern (not a bundled file)
         if (document.currentScript && document.currentScript instanceof HTMLScriptElement) {
-            const src = document.currentScript.src;
-            if (src && (src.includes('@countriesdb/widget') ||
-                src.includes('widget/dist/index.js'))) {
-                loaderScript = document.currentScript;
-            }
+            loaderScript = document.currentScript;
         }
-        // If currentScript didn't match, search for widget script
-        if (!loaderScript) {
-            // Only consider script tags that loaded the widget bundle
+        else {
+            // Fallback: find script tag with @countriesdb/widget in src
             const scripts = Array.from(document.getElementsByTagName('script'));
             loaderScript = scripts.find((s) => s.src && (s.src.includes('@countriesdb/widget') ||
                 s.src.includes('widget/dist/index.js'))) || null;
+            // If still not found, try the last script with src
+            if (!loaderScript) {
+                loaderScript = scripts.filter((s) => s.src).pop() || null;
+            }
         }
         if (loaderScript && loaderScript.src) {
             scriptUrl = new URL(loaderScript.src);
@@ -887,57 +921,39 @@ function getConfigFromOptionsOrScript(options) {
         // Ignore errors
     }
     const config = {
-        // Priority: options > globalConfig > scriptUrl params > defaults
-        publicKey: options.publicKey ?? globalConfig?.publicKey ?? scriptUrl?.searchParams.get('public_key') ?? '',
-        backendUrl: options.backendUrl ?? globalConfig?.backendUrl ?? scriptUrl?.searchParams.get('backend_url') ?? getBackendUrlFromScript(),
-        defaultLanguage: options.defaultLanguage ?? globalConfig?.defaultLanguage ?? scriptUrl?.searchParams.get('default_language') ?? undefined,
-        forcedLanguage: options.forcedLanguage ?? globalConfig?.forcedLanguage ?? scriptUrl?.searchParams.get('forced_language') ?? undefined,
+        publicKey: options.publicKey || scriptUrl?.searchParams.get('public_key') || '',
+        backendUrl: options.backendUrl || scriptUrl?.searchParams.get('backend_url') || getBackendUrlFromScript(),
+        defaultLanguage: options.defaultLanguage || scriptUrl?.searchParams.get('default_language') || undefined,
+        forcedLanguage: options.forcedLanguage || scriptUrl?.searchParams.get('forced_language') || undefined,
         showSubdivisionType: options.showSubdivisionType !== undefined
             ? options.showSubdivisionType
-            : globalConfig?.showSubdivisionType !== undefined
-                ? globalConfig.showSubdivisionType
-                : parseBoolean(scriptUrl?.searchParams.get('show_subdivision_type') ?? '1'),
+            : parseBoolean(scriptUrl?.searchParams.get('show_subdivision_type') ?? '1'),
         followRelated: options.followRelated !== undefined
             ? options.followRelated
-            : globalConfig?.followRelated !== undefined
-                ? globalConfig.followRelated
-                : parseBoolean(scriptUrl?.searchParams.get('follow_related') ?? 'false'),
+            : parseBoolean(scriptUrl?.searchParams.get('follow_related') ?? 'false'),
         followUpward: options.followUpward !== undefined
             ? options.followUpward
-            : globalConfig?.followUpward !== undefined
-                ? globalConfig.followUpward
-                : parseBoolean(scriptUrl?.searchParams.get('follow_upward') ?? 'false'),
+            : parseBoolean(scriptUrl?.searchParams.get('follow_upward') ?? 'false'),
         allowParentSelection: options.allowParentSelection !== undefined
             ? options.allowParentSelection
-            : globalConfig?.allowParentSelection !== undefined
-                ? globalConfig.allowParentSelection
-                : parseBoolean(scriptUrl?.searchParams.get('allow_parent_selection') ?? 'false'),
+            : parseBoolean(scriptUrl?.searchParams.get('allow_parent_selection') ?? 'false'),
         isoCountryNames: options.isoCountryNames !== undefined
             ? options.isoCountryNames
-            : globalConfig?.isoCountryNames !== undefined
-                ? globalConfig.isoCountryNames
-                : parseBoolean(scriptUrl?.searchParams.get('iso_country_names') ?? 'false'),
-        preferOfficialSubdivisions: options.preferOfficialSubdivisions !== undefined
-            ? options.preferOfficialSubdivisions
-            : globalConfig?.preferOfficialSubdivisions !== undefined
-                ? globalConfig.preferOfficialSubdivisions
-                : parseBoolean(scriptUrl?.searchParams.get('prefer_official') ?? 'false'),
+            : parseBoolean(scriptUrl?.searchParams.get('iso_country_names') ?? 'false'),
         subdivisionRomanizationPreference: options.subdivisionRomanizationPreference ||
-            globalConfig?.subdivisionRomanizationPreference ||
             scriptUrl?.searchParams.get('subdivision_romanization_preference') ||
             undefined,
         preferLocalVariant: options.preferLocalVariant !== undefined
             ? options.preferLocalVariant
-            : globalConfig?.preferLocalVariant !== undefined
-                ? globalConfig.preferLocalVariant
-                : parseBoolean(scriptUrl?.searchParams.get('prefer_local_variant') ?? 'false'),
-        countryNameFilter: options.countryNameFilter ?? globalConfig?.countryNameFilter,
-        subdivisionNameFilter: options.subdivisionNameFilter ?? globalConfig?.subdivisionNameFilter,
+            : parseBoolean(scriptUrl?.searchParams.get('prefer_local_variant') ?? 'false'),
+        preferOfficialSubdivisions: options.preferOfficialSubdivisions !== undefined
+            ? options.preferOfficialSubdivisions
+            : parseBoolean(scriptUrl?.searchParams.get('prefer_official') ?? 'false'),
+        countryNameFilter: options.countryNameFilter,
+        subdivisionNameFilter: options.subdivisionNameFilter,
         autoInit: options.autoInit !== undefined
             ? options.autoInit
-            : globalConfig?.autoInit !== undefined
-                ? globalConfig.autoInit
-                : parseBoolean(scriptUrl?.searchParams.get('auto_init') ?? 'true'),
+            : parseBoolean(scriptUrl?.searchParams.get('auto_init') ?? 'true'),
     };
     // Resolve filter functions from global scope if specified by name
     if (scriptUrl) {
@@ -965,20 +981,18 @@ function getBackendUrlFromScript() {
     try {
         let loaderScript = null;
         // First try document.currentScript (works during script execution)
-        // But only if it matches the widget pattern (not a bundled file)
         if (document.currentScript && document.currentScript instanceof HTMLScriptElement) {
-            const src = document.currentScript.src;
-            if (src && (src.includes('@countriesdb/widget') ||
-                src.includes('widget/dist/index.js'))) {
-                loaderScript = document.currentScript;
-            }
+            loaderScript = document.currentScript;
         }
-        // If currentScript didn't match, search for widget script
-        if (!loaderScript) {
-            // Only consider script tags that loaded the widget bundle
+        else {
+            // Fallback: find script tag with @countriesdb/widget in src
             const scripts = Array.from(document.getElementsByTagName('script'));
             loaderScript = scripts.find((s) => s.src && (s.src.includes('@countriesdb/widget') ||
                 s.src.includes('widget/dist/index.js'))) || null;
+            // If still not found, try the last script with src
+            if (!loaderScript) {
+                loaderScript = scripts.filter((s) => s.src).pop() || null;
+            }
         }
         if (loaderScript && loaderScript.src) {
             const scriptUrl = new URL(loaderScript.src);
@@ -1037,26 +1051,19 @@ function parseBoolean(value) {
  * Show error when both follow_related and follow_upward are enabled
  */
 function showParamConflictError() {
-    const errorMessage = 'Cannot enable both follow_related and follow_upward';
+    const errorMessage = 'Error: Cannot enable both follow_related and follow_upward';
     const countrySelects = Array.from(document.querySelectorAll('.country-selection'));
     for (const select of countrySelects) {
-        handleApiError(select, errorMessage, true);
+        select.innerHTML = `<option value="${select.dataset.defaultValue ?? ''}" disabled>${errorMessage}</option>`;
     }
     const subdivisionSelects = Array.from(document.querySelectorAll('.subdivision-selection'));
     for (const select of subdivisionSelects) {
-        handleApiError(select, errorMessage, true);
+        select.innerHTML = `<option value="${select.dataset.defaultValue ?? ''}" disabled>${errorMessage}</option>`;
     }
 }
 // Expose public loader
 if (typeof window !== 'undefined') {
     window.CountriesWidgetLoad = CountriesWidgetLoad;
-    // Dispatch ready event to notify consumers that the widget is available
-    // Use setTimeout(0) to ensure it fires after any synchronous code completes
-    setTimeout(() => {
-        if (typeof window !== 'undefined') {
-            window.dispatchEvent(new CustomEvent('countriesWidget:ready'));
-        }
-    }, 0);
     // Auto-init if script URL has auto_init=true (or not set, default is true)
     // Use a function that waits for DOM to be ready and finds the script tag reliably
     (function checkAutoInit() {
@@ -1068,16 +1075,10 @@ if (typeof window !== 'undefined') {
         // Find the script tag that loaded this widget
         let loaderScript = null;
         // First try document.currentScript (works during script execution)
-        // But only if it matches the widget pattern (not a bundled file)
         if (document.currentScript && document.currentScript instanceof HTMLScriptElement) {
-            const src = document.currentScript.src;
-            if (src && (src.includes('@countriesdb/widget') ||
-                src.includes('widget/dist/index.js'))) {
-                loaderScript = document.currentScript;
-            }
+            loaderScript = document.currentScript;
         }
-        // If currentScript didn't match, search for widget script
-        if (!loaderScript) {
+        else {
             // Fallback: find script tag with @countriesdb/widget in src
             const scripts = Array.from(document.getElementsByTagName('script'));
             loaderScript = scripts.find((s) => s.src && (s.src.includes('@countriesdb/widget') ||
@@ -1085,13 +1086,7 @@ if (typeof window !== 'undefined') {
         }
         // Default to auto-init = true (only disable if explicitly set to false)
         let shouldAutoInit = true;
-        const globalConfig = typeof window !== 'undefined'
-            ? window.CountriesDBConfig || null
-            : null;
-        if (globalConfig && typeof globalConfig.autoInit !== 'undefined') {
-            shouldAutoInit = !!globalConfig.autoInit;
-        }
-        else if (loaderScript && loaderScript.src) {
+        if (loaderScript && loaderScript.src) {
             try {
                 const scriptUrl = new URL(loaderScript.src);
                 const autoInit = scriptUrl.searchParams.get('auto_init');