kilfx 4.0.1

package/README.md

@@ -0,0 +1,164 @@
+# kilfx
+
+UI-only currency pair selector (flags + search) for:
+- CDN `<script>` (single JS file with auto CSS injection)
+- Node/Express pages
+- Next.js / React (`npm install kilfx`)
+
+`kilfx` does **not** fetch FX rates or call external FX APIs.  
+It only handles UI + emits change events so your app can fetch rates manually.
+
+## Install
+
+```bash
+npm install kilfx
+```
+
+## DOM Convention
+
+```html
+<div class="kilfx" kilfx_int="JM" kilfx_only="JM,US,IN">
+  <select name="kilfx_base"></select>
+  <select name="kilfx_to"></select>
+  <input type="text" name="fx_rate" readonly />
+</div>
+```
+
+Required:
+- `select[name="kilfx_base"]`
+- `select[name="kilfx_to"]`
+
+Optional:
+- `input[name="fx_rate"]` (forced readonly and cleared on pair change)
+
+## CDN Usage
+
+```html
+<script src="https://yourcdn.com/kilfx.iife.min.js"></script>
+```
+
+That alone auto-inits `.kilfx` blocks on page load.
+
+If you want custom config, add:
+
+```html
+<script src="https://yourcdn.com/kilfx.iife.min.js"></script>
+<script>
+  KILFX.init({
+    flagsPath: "/svg",
+    defaultBase: "JM",
+    defaultTo: "US"
+  });
+</script>
+```
+
+Optional explicit helper:
+
+```html
+<script>
+  KILFX.autoInit({ flagsPath: "/svg" });
+</script>
+```
+
+## npm / ESM Usage
+
+```js
+import { init } from "kilfx";
+init({ flagsPath: "/svg" });
+```
+
+Optional CSS import (JS still injects CSS automatically):
+
+```js
+import "kilfx/dist/kilfx.css";
+```
+
+## React / Next Usage
+
+```jsx
+"use client";
+import { KilFx } from "kilfx/react";
+
+export default function Page() {
+  return <KilFx flagsPath="/svg" defaultBase="JM" defaultTo="US" />;
+}
+```
+
+Or render your own `.kilfx` markup and call `init()` in `useEffect`.
+
+## Events
+
+On every base/to change, `kilfx`:
+1. Updates hidden native `<select>` value
+2. Dispatches native `change` on that `<select>`
+3. Dispatches global event:
+
+```js
+document.addEventListener("kilfx:change", (e) => {
+  const { base, to, rootEl, baseSelectEl, toSelectEl, baseItem, toItem } = e.detail;
+});
+```
+
+`detail` shape:
+- `base` / `to`: ISO2 code (`"US"`, `"JM"`, etc.)
+- `rootEl`: current `.kilfx` container
+- `baseSelectEl`, `toSelectEl`: underlying native selects
+- `baseItem`, `toItem`: `{ name, code, dial_code }`
+
+## API
+
+```js
+init({
+  rootSelector: ".kilfx",
+  baseName: "kilfx_base",
+  toName: "kilfx_to",
+  rateName: "fx_rate",
+  flagsPath: "/svg",
+  fileCase: "auto",       // auto | upper | lower
+  enableSearch: true,
+  defaultBase: "JM",
+  defaultTo: "JM",
+  initCountry: "JM",      // fallback for both (same idea as kilfx_int)
+  only: "JM,US,IN",       // restrict both dropdowns
+  onlyBase: "JM,US",      // optional base-only restriction
+  onlyTo: "IN,US",        // optional to-only restriction
+  data: null              // custom country data array or null for built-in
+});
+```
+
+## Attribute Shortcuts (Per `.kilfx`)
+
+Container attributes:
+- `kilfx_int="JM"`: default code for both dropdowns (if specific defaults not set)
+- `kilfx_only="JM,US,IN"`: restrict both dropdowns to selected ISO2 codes
+- `kilfx_base_int="US"` / `kilfx_to_int="IN"`: specific defaults
+- `kilfx_base_only="US,CA"` / `kilfx_to_only="IN,JM"`: specific allowed lists
+
+Select-level overrides also supported:
+- `select ... kilfx_int="US"`
+- `select ... kilfx_only="US,JM"`
+
+If nothing is provided, both dropdowns default to `JM`.
+
+## Acceptance Example
+
+```html
+<div class="kilfx">
+  <select name="kilfx_base"></select>
+  <select name="kilfx_to"></select>
+  <input name="fx_rate" readonly />
+</div>
+
+<script src="/dist/kilfx.iife.min.js"></script>
+<script>
+  KILFX.init({ flagsPath: "/svg", defaultBase: "JM", defaultTo: "US" });
+
+  document.addEventListener("kilfx:change", async (e) => {
+    const { base, to, rootEl } = e.detail;
+    const rateInput = rootEl.querySelector('input[name="fx_rate"]');
+    rateInput.value = "...";
+    // const { data } = await axios.get("/api/fx/rate", { params: { base, to } });
+    // rateInput.value = data.rate;
+  });
+</script>
+```