@countriesdb/widget-core 0.1.1

package/LICENSE

@@ -0,0 +1,25 @@
+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,39 @@
+# @countriesdb/widget-core
+
+**Internal package** - Core TypeScript API client and utilities for CountriesDB widget and validation libraries. This package is intended for internal use by other CountriesDB packages only.
+
+> ⚠️ **Not for direct use** - If you're looking to use CountriesDB in your project, please use the public packages:
+> - [`@countriesdb/widget`](../widget) - Plain JavaScript widget for country/subdivision selects
+> - [`@countriesdb/react-widget`](../react-widget) - React components for CountriesDB
+> 
+> 📖 **[Full Documentation](https://countriesdb.com/docs)** | 🌐 **[Website](https://countriesdb.com)**
+
+## Purpose
+
+This package contains shared TypeScript code, API client, type definitions, and utilities used internally by other CountriesDB packages. It is not intended for direct use by end users.
+
+## For Package Maintainers
+
+This package provides:
+- TypeScript API client for CountriesDB REST API
+- Type definitions for Country, Subdivision, and configuration types
+- Utility functions for data processing and tree building
+- Shared constants and helpers
+
+The API and internal structure may change without notice. Use the public widget packages for stable, documented APIs.
+
+## Installation
+
+This package is automatically installed as a dependency of other CountriesDB packages. You should not install it directly.
+
+## Resources
+
+- 🌐 [Website](https://countriesdb.com) - Main CountriesDB website
+- 📚 [Documentation](https://countriesdb.com/docs) - Complete API reference and guides
+
+## License
+
+PROPRIETARY - Copyright (c) NAYEE LLC. See [LICENSE](LICENSE) for details.
+
+**Developed by [NAYEE LLC](https://nayee.net)**
+

package/dist/api-client.d.ts

@@ -0,0 +1,22 @@
+/**
+ * API client for CountriesDB API
+ */
+import type { Country, Subdivision, ApiResponse, LanguageHeaders, FetchCountriesOptions, FetchSubdivisionsOptions } from './types';
+export declare class CountriesDBClient {
+    /**
+     * Fetch countries from the API
+     */
+    static fetchCountries(options: FetchCountriesOptions): Promise<ApiResponse<Country[]>>;
+    /**
+     * Fetch subdivisions for a specific country
+     */
+    static fetchSubdivisions(options: FetchSubdivisionsOptions): Promise<ApiResponse<Subdivision[]>>;
+    /**
+     * Generic API fetch method
+     */
+    private static fetchFromApi;
+    /**
+     * Get language headers from browser and config
+     */
+    static getLanguageHeaders(forcedLanguage?: string, defaultLanguage?: string): LanguageHeaders;
+}

package/dist/api-client.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * API client for CountriesDB API
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CountriesDBClient = void 0;
+class CountriesDBClient {
+    /**
+     * Fetch countries from the API
+     */
+    static async fetchCountries(options) {
+        const { apiKey, backendUrl, shouldUseGeoIP = true, isoCountryNames = false, languageHeaders = {}, } = options;
+        const base = `${backendUrl}/api/countries`;
+        const params = [];
+        if (!shouldUseGeoIP) {
+            params.push('no_geoip=1');
+        }
+        if (isoCountryNames) {
+            params.push('country_name_source=iso');
+        }
+        const url = params.length ? `${base}?${params.join('&')}` : base;
+        return this.fetchFromApi(url, apiKey, languageHeaders);
+    }
+    /**
+     * Fetch subdivisions for a specific country
+     */
+    static async fetchSubdivisions(options) {
+        const { apiKey, backendUrl, countryCode, shouldUseGeoIP = true, preferOfficial = false, subdivisionRomanizationPreference, preferLocalVariant = false, languageHeaders = {}, } = options;
+        if (!countryCode) {
+            return { data: [], language: null };
+        }
+        const base = `${backendUrl}/api/countries/${countryCode}/subdivisions`;
+        const params = [];
+        if (!shouldUseGeoIP) {
+            params.push('no_geoip=1');
+        }
+        if (subdivisionRomanizationPreference) {
+            params.push(`subdivision_romanization_preference=${encodeURIComponent(subdivisionRomanizationPreference)}`);
+        }
+        if (preferLocalVariant) {
+            params.push('prefer_local_variant=1');
+        }
+        if (preferOfficial) {
+            params.push('prefer_official=1');
+        }
+        const url = params.length ? `${base}?${params.join('&')}` : base;
+        return this.fetchFromApi(url, apiKey, languageHeaders);
+    }
+    /**
+     * Generic API fetch method
+     */
+    static async fetchFromApi(url, apiKey, languageHeaders) {
+        try {
+            const response = await fetch(url, {
+                headers: {
+                    ...languageHeaders,
+                    'X-API-KEY': apiKey,
+                    'Content-Type': 'application/json',
+                },
+            });
+            if (!response.ok) {
+                let errorMessage = `HTTP Error: ${response.status}`;
+                try {
+                    const errorData = await response.json();
+                    if (errorData.error) {
+                        errorMessage = errorData.error;
+                    }
+                }
+                catch {
+                    // Ignore JSON parse errors
+                }
+                throw new Error(errorMessage);
+            }
+            const data = (await response.json());
+            const language = response.headers.get('X-Selected-Language') || null;
+            return { data, language };
+        }
+        catch (error) {
+            console.error(`Failed to fetch data from ${url}:`, error);
+            throw error;
+        }
+    }
+    /**
+     * Get language headers from browser and config
+     */
+    static getLanguageHeaders(forcedLanguage, defaultLanguage) {
+        const headers = {};
+        if (forcedLanguage) {
+            headers['X-Forced-Language'] = forcedLanguage;
+        }
+        if (defaultLanguage) {
+            headers['X-Default-Language'] = defaultLanguage;
+        }
+        // Use browser's language preference
+        if (typeof navigator !== 'undefined' && navigator.language) {
+            headers['Accept-Language'] = navigator.language;
+        }
+        else {
+            headers['Accept-Language'] = 'en';
+        }
+        return headers;
+    }
+}
+exports.CountriesDBClient = CountriesDBClient;

package/dist/esm/api-client.d.ts

@@ -0,0 +1,22 @@
+/**
+ * API client for CountriesDB API
+ */
+import type { Country, Subdivision, ApiResponse, LanguageHeaders, FetchCountriesOptions, FetchSubdivisionsOptions } from './types';
+export declare class CountriesDBClient {
+    /**
+     * Fetch countries from the API
+     */
+    static fetchCountries(options: FetchCountriesOptions): Promise<ApiResponse<Country[]>>;
+    /**
+     * Fetch subdivisions for a specific country
+     */
+    static fetchSubdivisions(options: FetchSubdivisionsOptions): Promise<ApiResponse<Subdivision[]>>;
+    /**
+     * Generic API fetch method
+     */
+    private static fetchFromApi;
+    /**
+     * Get language headers from browser and config
+     */
+    static getLanguageHeaders(forcedLanguage?: string, defaultLanguage?: string): LanguageHeaders;
+}

package/dist/esm/api-client.js

@@ -0,0 +1,100 @@
+/**
+ * API client for CountriesDB API
+ */
+export class CountriesDBClient {
+    /**
+     * Fetch countries from the API
+     */
+    static async fetchCountries(options) {
+        const { apiKey, backendUrl, shouldUseGeoIP = true, isoCountryNames = false, languageHeaders = {}, } = options;
+        const base = `${backendUrl}/api/countries`;
+        const params = [];
+        if (!shouldUseGeoIP) {
+            params.push('no_geoip=1');
+        }
+        if (isoCountryNames) {
+            params.push('country_name_source=iso');
+        }
+        const url = params.length ? `${base}?${params.join('&')}` : base;
+        return this.fetchFromApi(url, apiKey, languageHeaders);
+    }
+    /**
+     * Fetch subdivisions for a specific country
+     */
+    static async fetchSubdivisions(options) {
+        const { apiKey, backendUrl, countryCode, shouldUseGeoIP = true, preferOfficial = false, subdivisionRomanizationPreference, preferLocalVariant = false, languageHeaders = {}, } = options;
+        if (!countryCode) {
+            return { data: [], language: null };
+        }
+        const base = `${backendUrl}/api/countries/${countryCode}/subdivisions`;
+        const params = [];
+        if (!shouldUseGeoIP) {
+            params.push('no_geoip=1');
+        }
+        if (subdivisionRomanizationPreference) {
+            params.push(`subdivision_romanization_preference=${encodeURIComponent(subdivisionRomanizationPreference)}`);
+        }
+        if (preferLocalVariant) {
+            params.push('prefer_local_variant=1');
+        }
+        if (preferOfficial) {
+            params.push('prefer_official=1');
+        }
+        const url = params.length ? `${base}?${params.join('&')}` : base;
+        return this.fetchFromApi(url, apiKey, languageHeaders);
+    }
+    /**
+     * Generic API fetch method
+     */
+    static async fetchFromApi(url, apiKey, languageHeaders) {
+        try {
+            const response = await fetch(url, {
+                headers: {
+                    ...languageHeaders,
+                    'X-API-KEY': apiKey,
+                    'Content-Type': 'application/json',
+                },
+            });
+            if (!response.ok) {
+                let errorMessage = `HTTP Error: ${response.status}`;
+                try {
+                    const errorData = await response.json();
+                    if (errorData.error) {
+                        errorMessage = errorData.error;
+                    }
+                }
+                catch {
+                    // Ignore JSON parse errors
+                }
+                throw new Error(errorMessage);
+            }
+            const data = (await response.json());
+            const language = response.headers.get('X-Selected-Language') || null;
+            return { data, language };
+        }
+        catch (error) {
+            console.error(`Failed to fetch data from ${url}:`, error);
+            throw error;
+        }
+    }
+    /**
+     * Get language headers from browser and config
+     */
+    static getLanguageHeaders(forcedLanguage, defaultLanguage) {
+        const headers = {};
+        if (forcedLanguage) {
+            headers['X-Forced-Language'] = forcedLanguage;
+        }
+        if (defaultLanguage) {
+            headers['X-Default-Language'] = defaultLanguage;
+        }
+        // Use browser's language preference
+        if (typeof navigator !== 'undefined' && navigator.language) {
+            headers['Accept-Language'] = navigator.language;
+        }
+        else {
+            headers['Accept-Language'] = 'en';
+        }
+        return headers;
+    }
+}

package/dist/esm/filters.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Name filtering utilities
+ */
+import type { Country, Subdivision, CountryNameFilter, SubdivisionNameFilter } from './types';
+/**
+ * Apply country name filter to a list of countries
+ */
+export declare function applyCountryNameFilter(countries: Country[], filter: CountryNameFilter | undefined, language: string): Array<Country & {
+    _displayName: string;
+}>;
+/**
+ * Sort countries with Unicode-aware sorting
+ */
+export declare function sortCountries(countries: Array<Country & {
+    _displayName: string;
+}>, language?: string): Array<Country & {
+    _displayName: string;
+}>;
+/**
+ * Apply subdivision name filter to a list of subdivisions
+ */
+export declare function applySubdivisionNameFilter(subdivisions: Subdivision[], filter: SubdivisionNameFilter | undefined, language: string, countryCode: string | null): Array<Subdivision & {
+    _displayName: string;
+}>;

package/dist/esm/filters.js

@@ -0,0 +1,62 @@
+/**
+ * Name filtering utilities
+ */
+/**
+ * Apply country name filter to a list of countries
+ */
+export function applyCountryNameFilter(countries, filter, language) {
+    if (!filter || typeof filter !== 'function') {
+        return countries.map((c) => ({ ...c, _displayName: c.name }));
+    }
+    return countries
+        .map((country) => {
+        const filteredName = filter(country.iso_alpha_2, country.name, language, country);
+        if (filteredName === false) {
+            return null; // Skip this item
+        }
+        const displayName = filteredName !== null && filteredName !== undefined
+            ? filteredName
+            : country.name;
+        return { ...country, _displayName: displayName };
+    })
+        .filter((c) => c !== null);
+}
+/**
+ * Sort countries with Unicode-aware sorting
+ */
+export function sortCountries(countries, language) {
+    const locale = language || undefined;
+    return [...countries].sort((a, b) => {
+        if (locale) {
+            return a._displayName.localeCompare(b._displayName, locale, {
+                sensitivity: 'accent', // Case-insensitive, accent-sensitive
+                ignorePunctuation: false,
+            });
+        }
+        return a._displayName.localeCompare(b._displayName);
+    });
+}
+/**
+ * Apply subdivision name filter to a list of subdivisions
+ */
+export function applySubdivisionNameFilter(subdivisions, filter, language, countryCode) {
+    if (!filter || typeof filter !== 'function') {
+        return subdivisions.map((s) => ({
+            ...s,
+            _displayName: s.full_name || s.name,
+        }));
+    }
+    return subdivisions
+        .map((subdivision) => {
+        const originalName = subdivision.full_name || subdivision.name;
+        const filteredName = filter(subdivision.code, originalName, language, countryCode, subdivision);
+        if (filteredName === false) {
+            return null; // Skip this item
+        }
+        const displayName = filteredName !== null && filteredName !== undefined
+            ? filteredName
+            : originalName;
+        return { ...subdivision, _displayName: displayName };
+    })
+        .filter((s) => s !== null);
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @countriesdb/widget-core
+ *
+ * Core package for CountriesDB widget functionality.
+ * Contains API client, types, and utilities shared across widget implementations.
+ */
+export { CountriesDBClient } from './api-client';
+export { buildSubdivisionTree, flattenSubdivisionOptions, parseNestingPrefixes, } from './subdivision-tree';
+export { applyCountryNameFilter, sortCountries, applySubdivisionNameFilter, } from './filters';
+export type { Country, Subdivision, ApiResponse, LanguageHeaders, FetchCountriesOptions, FetchSubdivisionsOptions, CountryNameFilter, SubdivisionNameFilter, WidgetConfig, SubdivisionTreeNode, NestedPrefixes, } from './types';

package/dist/esm/index.js

@@ -0,0 +1,9 @@
+/**
+ * @countriesdb/widget-core
+ *
+ * Core package for CountriesDB widget functionality.
+ * Contains API client, types, and utilities shared across widget implementations.
+ */
+export { CountriesDBClient } from './api-client';
+export { buildSubdivisionTree, flattenSubdivisionOptions, parseNestingPrefixes, } from './subdivision-tree';
+export { applyCountryNameFilter, sortCountries, applySubdivisionNameFilter, } from './filters';

package/dist/esm/subdivision-tree.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Utilities for building and working with subdivision trees
+ */
+import type { Subdivision, SubdivisionTreeNode, NestedPrefixes } from './types';
+/**
+ * Build a tree structure from a flat list of subdivisions
+ */
+export declare function buildSubdivisionTree(subdivisions: Subdivision[]): SubdivisionTreeNode[];
+/**
+ * Flatten subdivision tree into HTML options
+ */
+export declare function flattenSubdivisionOptions(nodes: SubdivisionTreeNode[], level: number, prefixes: NestedPrefixes, labelKey: 'name' | 'full_name', language: string, allowParentSelection: boolean, subdivisionNameFilter?: (code: string, originalName: string, language: string, countryCode: string | null, item: Subdivision) => string | false | null | undefined): string;
+/**
+ * Parse nesting prefixes from data attributes
+ */
+export declare function parseNestingPrefixes(dataAttributes: Record<string, string | undefined>): NestedPrefixes;

package/dist/esm/subdivision-tree.js

@@ -0,0 +1,102 @@
+/**
+ * Utilities for building and working with subdivision trees
+ */
+/**
+ * Build a tree structure from a flat list of subdivisions
+ */
+export function buildSubdivisionTree(subdivisions) {
+    const map = {};
+    const roots = [];
+    // Create map of all subdivisions
+    subdivisions.forEach((item) => {
+        map[item.id] = {
+            ...item,
+            children: [],
+        };
+    });
+    // Build tree structure
+    subdivisions.forEach((item) => {
+        const node = map[item.id];
+        if (item.parent_id && map[item.parent_id]) {
+            map[item.parent_id].children.push(node);
+        }
+        else {
+            roots.push(node);
+        }
+    });
+    return roots;
+}
+/**
+ * Flatten subdivision tree into HTML options
+ */
+export function flattenSubdivisionOptions(nodes, level, prefixes, labelKey, language, allowParentSelection, subdivisionNameFilter) {
+    let html = '';
+    // Apply name filter and get display names
+    const nodesWithDisplayNames = nodes
+        .map((node) => {
+        let displayName = node[labelKey] || node.name;
+        const countryCode = node.code ? node.code.split('-')[0] : null;
+        // Apply subdivisionNameFilter if provided
+        if (subdivisionNameFilter && typeof subdivisionNameFilter === 'function') {
+            const filteredName = subdivisionNameFilter(node.code, displayName, language, countryCode, node);
+            if (filteredName === false) {
+                return null; // Mark for filtering - remove this item
+            }
+            if (filteredName !== null && filteredName !== undefined) {
+                displayName = filteredName;
+            }
+        }
+        return { ...node, _displayName: displayName };
+    })
+        .filter((node) => node !== null);
+    // Sort: use Unicode-aware sorting if subdivisionNameFilter was used
+    const locale = subdivisionNameFilter && typeof subdivisionNameFilter === 'function' && language
+        ? language
+        : undefined;
+    nodesWithDisplayNames.sort((a, b) => {
+        if (locale) {
+            return a._displayName.localeCompare(b._displayName, locale, {
+                sensitivity: 'accent', // Case-insensitive, accent-sensitive
+                ignorePunctuation: false,
+            });
+        }
+        return a._displayName.localeCompare(b._displayName); // Default behavior
+    });
+    const prefix = level > 0 ? (prefixes[level] ?? ' '.repeat(level * 2)) : '';
+    const cssClass = `subdivision-level-${level}`;
+    for (const node of nodesWithDisplayNames) {
+        const hasChildren = node.children && node.children.length > 0;
+        const displayName = node._displayName;
+        const label = `${prefix}${displayName}`;
+        if (hasChildren) {
+            if (allowParentSelection) {
+                html += `<option value="${node.code}" class="${cssClass}">${label}</option>`;
+            }
+            else {
+                html += `<option disabled value="${node.code}" class="${cssClass}">${label}</option>`;
+            }
+            html += flattenSubdivisionOptions(node.children, level + 1, prefixes, labelKey, language, allowParentSelection, subdivisionNameFilter);
+        }
+        else {
+            html += `<option value="${node.code}" class="${cssClass}">${label}</option>`;
+        }
+    }
+    return html;
+}
+/**
+ * Parse nesting prefixes from data attributes
+ */
+export function parseNestingPrefixes(dataAttributes) {
+    const prefixes = {};
+    for (let lvl = 1; lvl <= 10; lvl++) {
+        const key = `nested${lvl}Prefix`;
+        const value = dataAttributes[key];
+        if (value !== undefined) {
+            prefixes[lvl] = value;
+        }
+        else {
+            break;
+        }
+    }
+    return prefixes;
+}

package/dist/esm/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Core types for CountriesDB widget packages
+ */
+export interface Country {
+    iso_alpha_2: string;
+    iso_alpha_3?: string;
+    iso_numeric?: string;
+    name: string;
+    preselected?: boolean;
+    is_subdivision_of?: {
+        parent_country_code: string;
+        subdivision_code: string;
+    } | null;
+    related_country_code?: string | null;
+    related_subdivision_code?: string | null;
+    [key: string]: any;
+}
+export interface Subdivision {
+    id: number;
+    code: string;
+    name: string;
+    full_name?: string;
+    parent_id?: number | null;
+    preselected?: boolean;
+    is_subdivision_of?: {
+        parent_country_code: string;
+        subdivision_code: string;
+    } | null;
+    related_country_code?: string | null;
+    related_subdivision_code?: string | null;
+    children?: Subdivision[];
+    [key: string]: any;
+}
+export interface ApiResponse<T> {
+    data: T;
+    language: string | null;
+}
+export interface LanguageHeaders {
+    'Accept-Language'?: string;
+    'X-Forced-Language'?: string;
+    'X-Default-Language'?: string;
+}
+export interface FetchCountriesOptions {
+    apiKey: string;
+    backendUrl: string;
+    shouldUseGeoIP?: boolean;
+    isoCountryNames?: boolean;
+    languageHeaders?: LanguageHeaders;
+}
+export interface FetchSubdivisionsOptions {
+    apiKey: string;
+    backendUrl: string;
+    countryCode: string;
+    shouldUseGeoIP?: boolean;
+    preferOfficial?: boolean;
+    subdivisionRomanizationPreference?: string;
+    preferLocalVariant?: boolean;
+    languageHeaders?: LanguageHeaders;
+}
+export type CountryNameFilter = (code: string, originalName: string, language: string, item: Country) => string | false | null | undefined;
+export type SubdivisionNameFilter = (code: string, originalName: string, language: string, countryCode: string | null, item: Subdivision) => string | false | null | undefined;
+export interface WidgetConfig {
+    publicKey: string;
+    backendUrl?: string;
+    defaultLanguage?: string;
+    forcedLanguage?: string;
+    showSubdivisionType?: boolean;
+    followRelated?: boolean;
+    followUpward?: boolean;
+    allowParentSelection?: boolean;
+    isoCountryNames?: boolean;
+    subdivisionRomanizationPreference?: string;
+    preferLocalVariant?: boolean;
+    countryNameFilter?: CountryNameFilter;
+    subdivisionNameFilter?: SubdivisionNameFilter;
+    autoInit?: boolean;
+}
+export interface SubdivisionTreeNode {
+    id: number;
+    code: string;
+    name: string;
+    full_name?: string;
+    parent_id?: number | null;
+    children: SubdivisionTreeNode[];
+    [key: string]: any;
+}
+export interface NestedPrefixes {
+    [level: number]: string;
+}

package/dist/esm/types.js

@@ -0,0 +1,4 @@
+/**
+ * Core types for CountriesDB widget packages
+ */
+export {};

package/dist/filters.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Name filtering utilities
+ */
+import type { Country, Subdivision, CountryNameFilter, SubdivisionNameFilter } from './types';
+/**
+ * Apply country name filter to a list of countries
+ */
+export declare function applyCountryNameFilter(countries: Country[], filter: CountryNameFilter | undefined, language: string): Array<Country & {
+    _displayName: string;
+}>;
+/**
+ * Sort countries with Unicode-aware sorting
+ */
+export declare function sortCountries(countries: Array<Country & {
+    _displayName: string;
+}>, language?: string): Array<Country & {
+    _displayName: string;
+}>;
+/**
+ * Apply subdivision name filter to a list of subdivisions
+ */
+export declare function applySubdivisionNameFilter(subdivisions: Subdivision[], filter: SubdivisionNameFilter | undefined, language: string, countryCode: string | null): Array<Subdivision & {
+    _displayName: string;
+}>;

package/dist/filters.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * Name filtering utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyCountryNameFilter = applyCountryNameFilter;
+exports.sortCountries = sortCountries;
+exports.applySubdivisionNameFilter = applySubdivisionNameFilter;
+/**
+ * Apply country name filter to a list of countries
+ */
+function applyCountryNameFilter(countries, filter, language) {
+    if (!filter || typeof filter !== 'function') {
+        return countries.map((c) => ({ ...c, _displayName: c.name }));
+    }
+    return countries
+        .map((country) => {
+        const filteredName = filter(country.iso_alpha_2, country.name, language, country);
+        if (filteredName === false) {
+            return null; // Skip this item
+        }
+        const displayName = filteredName !== null && filteredName !== undefined
+            ? filteredName
+            : country.name;
+        return { ...country, _displayName: displayName };
+    })
+        .filter((c) => c !== null);
+}
+/**
+ * Sort countries with Unicode-aware sorting
+ */
+function sortCountries(countries, language) {
+    const locale = language || undefined;
+    return [...countries].sort((a, b) => {
+        if (locale) {
+            return a._displayName.localeCompare(b._displayName, locale, {
+                sensitivity: 'accent', // Case-insensitive, accent-sensitive
+                ignorePunctuation: false,
+            });
+        }
+        return a._displayName.localeCompare(b._displayName);
+    });
+}
+/**
+ * Apply subdivision name filter to a list of subdivisions
+ */
+function applySubdivisionNameFilter(subdivisions, filter, language, countryCode) {
+    if (!filter || typeof filter !== 'function') {
+        return subdivisions.map((s) => ({
+            ...s,
+            _displayName: s.full_name || s.name,
+        }));
+    }
+    return subdivisions
+        .map((subdivision) => {
+        const originalName = subdivision.full_name || subdivision.name;
+        const filteredName = filter(subdivision.code, originalName, language, countryCode, subdivision);
+        if (filteredName === false) {
+            return null; // Skip this item
+        }
+        const displayName = filteredName !== null && filteredName !== undefined
+            ? filteredName
+            : originalName;
+        return { ...subdivision, _displayName: displayName };
+    })
+        .filter((s) => s !== null);
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @countriesdb/widget-core
+ *
+ * Core package for CountriesDB widget functionality.
+ * Contains API client, types, and utilities shared across widget implementations.
+ */
+export { CountriesDBClient } from './api-client';
+export { buildSubdivisionTree, flattenSubdivisionOptions, parseNestingPrefixes, } from './subdivision-tree';
+export { applyCountryNameFilter, sortCountries, applySubdivisionNameFilter, } from './filters';
+export type { Country, Subdivision, ApiResponse, LanguageHeaders, FetchCountriesOptions, FetchSubdivisionsOptions, CountryNameFilter, SubdivisionNameFilter, WidgetConfig, SubdivisionTreeNode, NestedPrefixes, } from './types';

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * @countriesdb/widget-core
+ *
+ * Core package for CountriesDB widget functionality.
+ * Contains API client, types, and utilities shared across widget implementations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applySubdivisionNameFilter = exports.sortCountries = exports.applyCountryNameFilter = exports.parseNestingPrefixes = exports.flattenSubdivisionOptions = exports.buildSubdivisionTree = exports.CountriesDBClient = void 0;
+var api_client_1 = require("./api-client");
+Object.defineProperty(exports, "CountriesDBClient", { enumerable: true, get: function () { return api_client_1.CountriesDBClient; } });
+var subdivision_tree_1 = require("./subdivision-tree");
+Object.defineProperty(exports, "buildSubdivisionTree", { enumerable: true, get: function () { return subdivision_tree_1.buildSubdivisionTree; } });
+Object.defineProperty(exports, "flattenSubdivisionOptions", { enumerable: true, get: function () { return subdivision_tree_1.flattenSubdivisionOptions; } });
+Object.defineProperty(exports, "parseNestingPrefixes", { enumerable: true, get: function () { return subdivision_tree_1.parseNestingPrefixes; } });
+var filters_1 = require("./filters");
+Object.defineProperty(exports, "applyCountryNameFilter", { enumerable: true, get: function () { return filters_1.applyCountryNameFilter; } });
+Object.defineProperty(exports, "sortCountries", { enumerable: true, get: function () { return filters_1.sortCountries; } });
+Object.defineProperty(exports, "applySubdivisionNameFilter", { enumerable: true, get: function () { return filters_1.applySubdivisionNameFilter; } });

package/dist/subdivision-tree.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Utilities for building and working with subdivision trees
+ */
+import type { Subdivision, SubdivisionTreeNode, NestedPrefixes } from './types';
+/**
+ * Build a tree structure from a flat list of subdivisions
+ */
+export declare function buildSubdivisionTree(subdivisions: Subdivision[]): SubdivisionTreeNode[];
+/**
+ * Flatten subdivision tree into HTML options
+ */
+export declare function flattenSubdivisionOptions(nodes: SubdivisionTreeNode[], level: number, prefixes: NestedPrefixes, labelKey: 'name' | 'full_name', language: string, allowParentSelection: boolean, subdivisionNameFilter?: (code: string, originalName: string, language: string, countryCode: string | null, item: Subdivision) => string | false | null | undefined): string;
+/**
+ * Parse nesting prefixes from data attributes
+ */
+export declare function parseNestingPrefixes(dataAttributes: Record<string, string | undefined>): NestedPrefixes;

package/dist/subdivision-tree.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * Utilities for building and working with subdivision trees
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSubdivisionTree = buildSubdivisionTree;
+exports.flattenSubdivisionOptions = flattenSubdivisionOptions;
+exports.parseNestingPrefixes = parseNestingPrefixes;
+/**
+ * Build a tree structure from a flat list of subdivisions
+ */
+function buildSubdivisionTree(subdivisions) {
+    const map = {};
+    const roots = [];
+    // Create map of all subdivisions
+    subdivisions.forEach((item) => {
+        map[item.id] = {
+            ...item,
+            children: [],
+        };
+    });
+    // Build tree structure
+    subdivisions.forEach((item) => {
+        const node = map[item.id];
+        if (item.parent_id && map[item.parent_id]) {
+            map[item.parent_id].children.push(node);
+        }
+        else {
+            roots.push(node);
+        }
+    });
+    return roots;
+}
+/**
+ * Flatten subdivision tree into HTML options
+ */
+function flattenSubdivisionOptions(nodes, level, prefixes, labelKey, language, allowParentSelection, subdivisionNameFilter) {
+    let html = '';
+    // Apply name filter and get display names
+    const nodesWithDisplayNames = nodes
+        .map((node) => {
+        let displayName = node[labelKey] || node.name;
+        const countryCode = node.code ? node.code.split('-')[0] : null;
+        // Apply subdivisionNameFilter if provided
+        if (subdivisionNameFilter && typeof subdivisionNameFilter === 'function') {
+            const filteredName = subdivisionNameFilter(node.code, displayName, language, countryCode, node);
+            if (filteredName === false) {
+                return null; // Mark for filtering - remove this item
+            }
+            if (filteredName !== null && filteredName !== undefined) {
+                displayName = filteredName;
+            }
+        }
+        return { ...node, _displayName: displayName };
+    })
+        .filter((node) => node !== null);
+    // Sort: use Unicode-aware sorting if subdivisionNameFilter was used
+    const locale = subdivisionNameFilter && typeof subdivisionNameFilter === 'function' && language
+        ? language
+        : undefined;
+    nodesWithDisplayNames.sort((a, b) => {
+        if (locale) {
+            return a._displayName.localeCompare(b._displayName, locale, {
+                sensitivity: 'accent', // Case-insensitive, accent-sensitive
+                ignorePunctuation: false,
+            });
+        }
+        return a._displayName.localeCompare(b._displayName); // Default behavior
+    });
+    const prefix = level > 0 ? (prefixes[level] ?? ' '.repeat(level * 2)) : '';
+    const cssClass = `subdivision-level-${level}`;
+    for (const node of nodesWithDisplayNames) {
+        const hasChildren = node.children && node.children.length > 0;
+        const displayName = node._displayName;
+        const label = `${prefix}${displayName}`;
+        if (hasChildren) {
+            if (allowParentSelection) {
+                html += `<option value="${node.code}" class="${cssClass}">${label}</option>`;
+            }
+            else {
+                html += `<option disabled value="${node.code}" class="${cssClass}">${label}</option>`;
+            }
+            html += flattenSubdivisionOptions(node.children, level + 1, prefixes, labelKey, language, allowParentSelection, subdivisionNameFilter);
+        }
+        else {
+            html += `<option value="${node.code}" class="${cssClass}">${label}</option>`;
+        }
+    }
+    return html;
+}
+/**
+ * Parse nesting prefixes from data attributes
+ */
+function parseNestingPrefixes(dataAttributes) {
+    const prefixes = {};
+    for (let lvl = 1; lvl <= 10; lvl++) {
+        const key = `nested${lvl}Prefix`;
+        const value = dataAttributes[key];
+        if (value !== undefined) {
+            prefixes[lvl] = value;
+        }
+        else {
+            break;
+        }
+    }
+    return prefixes;
+}

package/dist/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Core types for CountriesDB widget packages
+ */
+export interface Country {
+    iso_alpha_2: string;
+    iso_alpha_3?: string;
+    iso_numeric?: string;
+    name: string;
+    preselected?: boolean;
+    is_subdivision_of?: {
+        parent_country_code: string;
+        subdivision_code: string;
+    } | null;
+    related_country_code?: string | null;
+    related_subdivision_code?: string | null;
+    [key: string]: any;
+}
+export interface Subdivision {
+    id: number;
+    code: string;
+    name: string;
+    full_name?: string;
+    parent_id?: number | null;
+    preselected?: boolean;
+    is_subdivision_of?: {
+        parent_country_code: string;
+        subdivision_code: string;
+    } | null;
+    related_country_code?: string | null;
+    related_subdivision_code?: string | null;
+    children?: Subdivision[];
+    [key: string]: any;
+}
+export interface ApiResponse<T> {
+    data: T;
+    language: string | null;
+}
+export interface LanguageHeaders {
+    'Accept-Language'?: string;
+    'X-Forced-Language'?: string;
+    'X-Default-Language'?: string;
+}
+export interface FetchCountriesOptions {
+    apiKey: string;
+    backendUrl: string;
+    shouldUseGeoIP?: boolean;
+    isoCountryNames?: boolean;
+    languageHeaders?: LanguageHeaders;
+}
+export interface FetchSubdivisionsOptions {
+    apiKey: string;
+    backendUrl: string;
+    countryCode: string;
+    shouldUseGeoIP?: boolean;
+    preferOfficial?: boolean;
+    subdivisionRomanizationPreference?: string;
+    preferLocalVariant?: boolean;
+    languageHeaders?: LanguageHeaders;
+}
+export type CountryNameFilter = (code: string, originalName: string, language: string, item: Country) => string | false | null | undefined;
+export type SubdivisionNameFilter = (code: string, originalName: string, language: string, countryCode: string | null, item: Subdivision) => string | false | null | undefined;
+export interface WidgetConfig {
+    publicKey: string;
+    backendUrl?: string;
+    defaultLanguage?: string;
+    forcedLanguage?: string;
+    showSubdivisionType?: boolean;
+    followRelated?: boolean;
+    followUpward?: boolean;
+    allowParentSelection?: boolean;
+    isoCountryNames?: boolean;
+    subdivisionRomanizationPreference?: string;
+    preferLocalVariant?: boolean;
+    countryNameFilter?: CountryNameFilter;
+    subdivisionNameFilter?: SubdivisionNameFilter;
+    autoInit?: boolean;
+}
+export interface SubdivisionTreeNode {
+    id: number;
+    code: string;
+    name: string;
+    full_name?: string;
+    parent_id?: number | null;
+    children: SubdivisionTreeNode[];
+    [key: string]: any;
+}
+export interface NestedPrefixes {
+    [level: number]: string;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Core types for CountriesDB widget packages
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@countriesdb/widget-core",
+  "version": "0.1.1",
+  "description": "Internal package - Core TypeScript API client and utilities for CountriesDB widget and validation libraries. Not intended for direct use.",
+  "main": "dist/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && tsc --module esnext --outDir dist/esm",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "countries",
+    "subdivisions",
+    "widget",
+    "api",
+    "countriesdb",
+    "iso-3166",
+    "iso-3166-1",
+    "iso-3166-2",
+    "iso3166",
+    "iso3166-1",
+    "iso3166-2",
+    "api-client",
+    "countries-api",
+    "subdivisions-api",
+    "rest-api",
+    "country-data",
+    "subdivision-data",
+    "geography-data",
+    "typescript",
+    "types"
+  ],
+  "author": {
+    "name": "NAYEE LLC",
+    "url": "https://nayee.net"
+  },
+  "license": "PROPRIETARY",
+  "homepage": "https://countriesdb.com",
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
+