react-country-kit-core 1.1.2 → 1.2.0

package/README.md

@@ -1,54 +1,83 @@
 # react-country-kit-core
 
-The engine behind `react-country-kit`. This package provides all the data, hooks, and utilities needed to build your own custom country-related UI components.
+The high-performance logic and data engine behind `react-country-kit`. This package provides all the comprehensive datasets, headless hooks, and utilities needed to build custom country-related UI components.
 
-## Features
+## 🚀 Features
 
-- **250+ Countries**: Comprehensive dataset with ISO codes (2 & 3), flags, and phone codes.
-- **Administrative Divisions**: State/Province data for major countries.
-- **Currencies & Timezones**: Linked data for every country.
-- **Native Language Support**: English and Native names for languages.
-- **Headless Hooks**: Logic-only hooks (`useCountryPicker`, `usePhoneInput`, etc.) for building custom UI.
-- **Phone Formatting**: Integrated `libphonenumber-js` for accurate phone number handling.
+- **250+ Countries**: Full dataset with ISO codes, flags, and phone codes.
+- **📑 Localized Metadata**: Built-in support for localized **Tax ID labels** (SSN, VAT, ABN) and **Postal Code labels** (ZIP, PIN, Postcode).
+- **🌍 Global Data**: Timezones (with legacy alias support), Currencies, and Native Language names.
+- **🏙 Administrative Divisions**: State/Province data for all countries.
+- **🧠 Headless Hooks**: Logic-only hooks (`useCountryPicker`, `usePhoneInput`, etc.) for building custom UI with any styling library.
+- **📞 Phone Validation**: Powered by `libphonenumber-js` for accurate formatting and validation.
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install react-country-kit-core
 ```
 
-## Available Hooks
+## 🛠 Utility Functions
 
-### `useCountryPicker(initialValue?, onChange?)`
+### Localized Metadata
 
-Manages country selection and searching.
+Get labels and placeholders for billing/registration forms:
 
-### `usePhoneInput(initialValue?, onChange?, defaultCountryIso2?)`
+```tsx
+import {
+  getTaxLabelByCountry,
+  getTaxPlaceholderByCountry,
+  getPostalLabelByCountry,
+} from "react-country-kit-core";
 
-Handles complex phone number input logic, including country switching and validation.
-
-### `useDivisionPicker(countryIso2, initialValue?, onChange?)`
-
-Manages state/province selection for a specific country.
-
-### `useCurrencyPicker(initialValue?, onChange?)`
-
-Manages currency selection.
+const label = getTaxLabelByCountry("US"); // "EIN / SSN"
+const placeholder = getTaxPlaceholderByCountry("US"); // "00-0000000"
+const postalLabel = getPostalLabelByCountry("JP"); // "Postal Code (〒)"
+```
 
-### `useTimezonePicker(initialValue?, onChange?, countryIso2?)`
+### Data Retrieval
 
-Manages timezone selection, optionally filtered by country.
+```tsx
+import {
+  getAllCountries,
+  getCountryByIso2,
+  searchCountries,
+} from "react-country-kit-core";
 
-## Utility Functions
+const usa = getCountryByIso2("US");
+const results = searchCountries("united");
+```
 
-- `getAllCountries()`
-- `getCountryByIso2(iso2)`
-- `getDivisionsByCountry(iso2)`
-- `getTimezonesByCountry(iso2)`
-- `searchCountries(query)`
-- ...and many more.
+## 🧠 Headless Hooks
+
+Our hooks handle state, filtering, and interaction logic so you can focus on the UI:
+
+```tsx
+import { useCountryPicker } from "react-country-kit-core";
+
+function CustomPicker() {
+  const { filteredItems, searchQuery, setSearchQuery, selectItem } =
+    useCountryPicker();
+
+  return (
+    <div>
+      <input
+        value={searchQuery}
+        onChange={(e) => setSearchQuery(e.target.value)}
+      />
+      <ul>
+        {filteredItems.map((c) => (
+          <li key={c.iso2} onClick={() => selectItem(c)}>
+            {c.name}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
 
-## Data Structure
+## 📄 Data Structure
 
 ```typescript
 export interface Country {
@@ -56,14 +85,17 @@ export interface Country {
   iso2: string;
   iso3: string;
   phone_code: string;
+  division_type: string;
   flag: string;
   flag_url: string;
   currency_code: string;
   language_code: string;
-  division_type: string;
+  tax_id_label: string;
+  tax_id_placeholder: string;
+  postal_code_label: string;
 }
 ```
 
-## License
+## 📄 License
 
 MIT

package/dist/index.d.ts

@@ -5,11 +5,7 @@ export declare interface Country {
     iso2: string;
     iso3: string;
     phone_code: string;
-    phone_format?: PhoneFormat;
-    currency?: Currency;
     division_type: string;
-    divisions?: Division[];
-    timezones?: Timezone[];
     /** Emoji flag computed from iso2 */
     flag: string;
     /** SVG/Image URL for the country flag */
@@ -19,11 +15,11 @@ export declare interface Country {
     /** Default currency code for the country */
     currency_code: string;
     /** Label for tax identification number (e.g. "VAT", "SSN", "ABN") */
-    tax_id_label?: string;
+    tax_id_label: string;
     /** Placeholder for tax identification number */
-    tax_id_placeholder?: string;
+    tax_id_placeholder: string;
     /** Label for postal/zip code (e.g. "ZIP Code", "Postcode", "PIN Code") */
-    postal_code_label?: string;
+    postal_code_label: string;
 }
 
 export declare interface CountryMultiSelectProps {
@@ -243,7 +239,6 @@ export declare interface LanguagePickerProps {
 export declare const PHONE_FORMATS: PhoneFormat[];
 
 export declare interface PhoneFormat {
-    countryCode?: string;
     iso2: string;
     dialCode: string;
     patterns: string;

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "react-country-kit-core",
-  "version": "1.1.2",
+  "version": "1.2.0",
+  "type": "module",
   "description": "Core datasets, utilities, and hooks for react-country-kit. Comprehensive data for countries, currencies, timezones, languages, and divisions.",
   "author": "Kishor Mainali",
   "license": "MIT",