@countriesdb/widget 0.1.23 → 0.1.25

package/README.md

@@ -78,7 +78,6 @@ import { CountriesWidgetLoad } from '@countriesdb/widget';
 
 CountriesWidgetLoad({
   publicKey: 'YOUR_PUBLIC_KEY',
-  backendUrl: 'https://api.countriesdb.com',
   defaultLanguage: 'en',
   enableGeolocation: true
 });
@@ -89,7 +88,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 +97,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 +142,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 +214,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' });
@@ -867,14 +907,12 @@ function getConfigFromOptionsOrScript(options) {
         // 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'))) {
+            if (src && (src.includes('@countriesdb/widget') || src.includes('widget/dist/index.js'))) {
                 loaderScript = document.currentScript;
             }
         }
         // If currentScript didn't match, search for widget script
         if (!loaderScript) {
-            // Only consider script tags that loaded the widget bundle
             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;
@@ -917,11 +955,6 @@ function getConfigFromOptionsOrScript(options) {
             : 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'),
         subdivisionRomanizationPreference: options.subdivisionRomanizationPreference ||
             globalConfig?.subdivisionRomanizationPreference ||
             scriptUrl?.searchParams.get('subdivision_romanization_preference') ||
@@ -931,6 +964,11 @@ function getConfigFromOptionsOrScript(options) {
             : globalConfig?.preferLocalVariant !== undefined
                 ? globalConfig.preferLocalVariant
                 : parseBoolean(scriptUrl?.searchParams.get('prefer_local_variant') ?? 'false'),
+        preferOfficialSubdivisions: options.preferOfficialSubdivisions !== undefined
+            ? options.preferOfficialSubdivisions
+            : globalConfig?.preferOfficialSubdivisions !== undefined
+                ? globalConfig.preferOfficialSubdivisions
+                : parseBoolean(scriptUrl?.searchParams.get('prefer_official') ?? 'false'),
         countryNameFilter: options.countryNameFilter ?? globalConfig?.countryNameFilter,
         subdivisionNameFilter: options.subdivisionNameFilter ?? globalConfig?.subdivisionNameFilter,
         autoInit: options.autoInit !== undefined
@@ -968,8 +1006,7 @@ function getBackendUrlFromScript() {
         // 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'))) {
+            if (src && (src.includes('@countriesdb/widget') || src.includes('widget/dist/index.js'))) {
                 loaderScript = document.currentScript;
             }
         }
@@ -1037,26 +1074,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() {
@@ -1071,14 +1101,12 @@ if (typeof window !== 'undefined') {
         // 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'))) {
+            if (src && (src.includes('@countriesdb/widget') || src.includes('widget/dist/index.js'))) {
                 loaderScript = document.currentScript;
             }
         }
         // If currentScript didn't match, search for widget script
         if (!loaderScript) {
-            // 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;