@countriesdb/widget 0.1.35 → 1.0.0

package/README.md

@@ -40,20 +40,15 @@ For detailed documentation, visit [countriesdb.com/docs](https://countriesdb.com
 ### 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>
+<!-- Widget auto-initializes when script loads -->
+<script src="https://unpkg.com/@countriesdb/widget@latest/dist/index.js?public_key=YOUR_PUBLIC_KEY"></script>
 
 <!-- Add CSS classes to your select elements -->
-<select class="country-selection" name="country">
+<select class="country-selection" data-name="country1" name="country">
   <option value="">Select Country</option>
 </select>
 
-<select class="subdivision-selection" name="state" data-country="country">
+<select class="subdivision-selection" name="state" data-country="country1">
   <option value="">Select State/Province</option>
 </select>
 ```
@@ -62,7 +57,10 @@ For detailed documentation, visit [countriesdb.com/docs](https://countriesdb.com
 
 ```html
 <script type="module">
-  import { CountriesWidgetLoad } from '@countriesdb/widget';
+  import CountriesWidgetLoad from '@countriesdb/widget';
+  
+  // Or use auto-init with window.CountriesDBConfig:
+  // import '@countriesdb/widget';
   
   CountriesWidgetLoad({
     publicKey: 'YOUR_PUBLIC_KEY',
@@ -74,12 +72,12 @@ For detailed documentation, visit [countriesdb.com/docs](https://countriesdb.com
 ### Node.js / Bundler
 
 ```javascript
-import { CountriesWidgetLoad } from '@countriesdb/widget';
+import CountriesWidgetLoad from '@countriesdb/widget';
 
 CountriesWidgetLoad({
   publicKey: 'YOUR_PUBLIC_KEY',
-  defaultLanguage: 'en',
-  enableGeolocation: true
+  defaultLanguage: 'en'
+  // GeoIP is enabled by default unless disabled via data-preselected=""
 });
 ```
 
@@ -101,6 +99,7 @@ CountriesWidgetLoad({
 - `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`)
+- `reload` (optional): Force re-initialization, clearing cached state and reapplying preselected values (default: `false`)
 
 ### Data Attributes
 
@@ -134,7 +133,7 @@ document.addEventListener('countriesWidget:update', (event) => {
   //   value: 'US',
   //   selectedValues: ['US'],
   //   name: 'country1',
-  //   country: null,
+  //   country: null, // For subdivision selects: linked country select's data-name
   //   isSubdivision: false,
   //   type: 'country',
   //   reason: 'regular' | 'geoip' | 'preselected' | 'reload' | 'follow'
@@ -153,7 +152,7 @@ document.addEventListener('countriesWidget:ready', (event) => {
   //   value: 'US',
   //   selectedValues: ['US'],
   //   name: 'country1',
-  //   country: null,
+  //   country: null, // For subdivision selects: linked country select's data-name
   //   isSubdivision: false,
   //   type: 'country' | 'subdivision',
   //   phase: 'initial' | 'reload'
@@ -186,7 +185,19 @@ document.addEventListener('countriesWidget:ready', (event) => {
 ### Custom Name Filter
 
 ```javascript
-CountriesWidgetLoad({
+// Using window.CountriesDBConfig (before script loads)
+window.CountriesDBConfig = {
+  publicKey: 'YOUR_PUBLIC_KEY',
+  countryNameFilter: (code, name, language, item) => {
+    if (code === 'US') {
+      return 'United States of America';
+    }
+    return name;
+  }
+};
+
+// Or using window.CountriesWidgetLoad (after script loads)
+window.CountriesWidgetLoad({
   publicKey: 'YOUR_PUBLIC_KEY',
   countryNameFilter: (code, name, language, item) => {
     if (code === 'US') {
@@ -201,7 +212,25 @@ CountriesWidgetLoad({
 
 ### `CountriesWidgetLoad(options)`
 
-Main initialization function. Returns a Promise that resolves when initialization is complete.
+Main initialization function. Returns a Promise that resolves to `true` when initialization is complete, or `false` if initialization failed (e.g., due to conflicting parameters like `followRelated` and `followUpward`).
+
+**Parameters:**
+- `options` (object): Configuration options (see [Options](#options) above)
+
+**Example:**
+```javascript
+// Basic initialization
+await CountriesWidgetLoad({
+  publicKey: 'YOUR_PUBLIC_KEY',
+  defaultLanguage: 'en'
+});
+
+// Force reload (clears cached state and reapplies preselected values)
+await CountriesWidgetLoad({
+  publicKey: 'YOUR_PUBLIC_KEY',
+  reload: true
+});
+```
 
 For complete API documentation, visit [countriesdb.com/docs](https://countriesdb.com/docs).
 
@@ -214,7 +243,7 @@ For complete API documentation, visit [countriesdb.com/docs](https://countriesdb
 
 ## License
 
-PROPRIETARY - Copyright (c) NAYEE LLC. See [LICENSE](https://github.com/countriesdb/countriesdb/blob/main/packages/npm/widget/LICENSE) for details.
+PROPRIETARY - Copyright (c) NAYEE LLC.
 
 **Developed by [NAYEE LLC](https://nayee.net)**
 

package/dist/index.esm.js

@@ -649,50 +649,36 @@ async function updateSubdivisionSelect(select, apiKey, backendUrl, state, config
                             if (preselectedSubdivision) {
                                 const isMultiple = select.hasAttribute('multiple');
                                 let subdivisionToSelect = preselectedSubdivision;
-                                // Check if the preselected subdivision is disabled (parent with children when allowParentSelection is false)
+                                // If preselected is disabled and allowParentSelection is false, find first enabled child
                                 if (!config.allowParentSelection && !isMultiple) {
-                                    const option = Array.from(select.options).find((opt) => opt.value === preselectedSubdivision.code);
-                                    // If option is disabled, find the first child subdivision
-                                    if (option && option.disabled) {
-                                        const tree = buildSubdivisionTree(subdivisions);
-                                        // Find the node in the tree
-                                        function findNodeInTree(nodes, code) {
-                                            for (const node of nodes) {
-                                                if (node.code === code) {
-                                                    return node;
+                                    const preselectedOption = Array.from(select.options).find((opt) => opt.value === preselectedSubdivision.code);
+                                    if (preselectedOption?.disabled) {
+                                        // Find direct children by parent_id
+                                        const directChildren = subdivisions.filter((sub) => sub.parent_id === preselectedSubdivision.id);
+                                        if (directChildren.length > 0) {
+                                            // Sort by name and get first child
+                                            const sorted = directChildren.sort((a, b) => {
+                                                return (a.name || '').localeCompare(b.name || '', subdivisionsLanguage, { sensitivity: 'accent' });
+                                            });
+                                            const firstChild = sorted[0];
+                                            // Check if first child is also disabled (has its own children)
+                                            const firstChildOption = Array.from(select.options).find((opt) => opt.value === firstChild.code);
+                                            if (firstChildOption?.disabled) {
+                                                // First child is disabled, find its first child (grandchild)
+                                                const grandChildren = subdivisions.filter((sub) => sub.parent_id === firstChild.id);
+                                                if (grandChildren.length > 0) {
+                                                    const sortedGrandChildren = grandChildren.sort((a, b) => {
+                                                        return (a.name || '').localeCompare(b.name || '', subdivisionsLanguage, { sensitivity: 'accent' });
+                                                    });
+                                                    subdivisionToSelect = sortedGrandChildren[0];
                                                 }
-                                                if (node.children && node.children.length > 0) {
-                                                    const found = findNodeInTree(node.children, code);
-                                                    if (found)
-                                                        return found;
+                                                else {
+                                                    subdivisionToSelect = firstChild;
                                                 }
                                             }
-                                            return null;
-                                        }
-                                        const preselectedNode = findNodeInTree(tree, preselectedSubdivision.code);
-                                        // Get the first child (recursively if needed)
-                                        function getFirstChild(node) {
-                                            if (!node || !node.children || node.children.length === 0) {
-                                                return null;
+                                            else {
+                                                subdivisionToSelect = firstChild;
                                             }
-                                            // Sort children to get consistent first child
-                                            const sortedChildren = [...node.children].sort((a, b) => {
-                                                const nameA = a.name || '';
-                                                const nameB = b.name || '';
-                                                return nameA.localeCompare(nameB);
-                                            });
-                                            const firstChild = sortedChildren[0];
-                                            // If first child also has children and would be disabled, recurse
-                                            if (firstChild.children && firstChild.children.length > 0) {
-                                                const deeperChild = getFirstChild(firstChild);
-                                                return deeperChild || firstChild;
-                                            }
-                                            return firstChild;
-                                        }
-                                        const firstChild = preselectedNode ? getFirstChild(preselectedNode) : null;
-                                        if (firstChild) {
-                                            // Find the subdivision object by code
-                                            subdivisionToSelect = subdivisions.find((sub) => sub.code === firstChild.code) || preselectedSubdivision;
                                         }
                                     }
                                 }