@countriesdb/widget 0.1.36 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@countriesdb/widget",
-  "version": "0.1.36",
+  "version": "1.0.0",
   "description": "Country and state/province select widget with ISO 3166-1 and ISO 3166-2 codes. Auto-populates dropdowns with up-to-date country and subdivision data in multiple languages. Easy integration for forms, location selection, and address validation.",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",