@jjlmoya/utils-finance 1.45.0 → 1.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jjlmoya/utils-finance",
-    "version": "1.45.0",
+    "version": "1.47.0",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",

package/src/category/index.ts

@@ -23,10 +23,11 @@ import { subscriptionCostAnnualizer } from '../tool/subscriptionCostAnnualizer/e
 import { loanToIncomeRatio } from '../tool/loanToIncomeRatio/entry';
 import { capitalGainsTaxScenarioCalculator } from '../tool/capitalGainsTaxScenarioCalculator/entry';
 import { insuranceDeductibleBreakEvenCalculator } from '../tool/insuranceDeductibleBreakEvenCalculator/entry';
+import { loanAprScenarioCalculator } from '../tool/loanAprScenarioCalculator/entry';
 
 export const financeCategory: FinanceCategoryEntry = {
   icon: 'mdi:finance',
-  tools: [compoundInterest, financialFreedom, savingsRate, profitability, mortgage, inflation, percentageCalculator, lateInterest, ibanBicSwift, rentIncrease, lotteryOptimizer, courtFeeCalculator, legalInterestRate, fireCalculator, debtSnowball, revolvingCardCalculator, pesetaValue, salaryEmployerCost, dividendYield, inflationPurchasingPower, subscriptionCostAnnualizer, loanToIncomeRatio, capitalGainsTaxScenarioCalculator, insuranceDeductibleBreakEvenCalculator],
+  tools: [compoundInterest, financialFreedom, savingsRate, profitability, mortgage, inflation, percentageCalculator, lateInterest, ibanBicSwift, rentIncrease, lotteryOptimizer, courtFeeCalculator, legalInterestRate, fireCalculator, debtSnowball, revolvingCardCalculator, pesetaValue, salaryEmployerCost, dividendYield, inflationPurchasingPower, subscriptionCostAnnualizer, loanToIncomeRatio, capitalGainsTaxScenarioCalculator, insuranceDeductibleBreakEvenCalculator, loanAprScenarioCalculator],
   i18n: {
     en: () => import('./i18n/en').then((m) => m.content),
     es: () => import('./i18n/es').then((m) => m.content),

package/src/entries.ts

@@ -48,6 +48,8 @@ export { rentalDepositReturn } from './tool/rentalDepositReturn/entry';
 export type { RentalDepositReturnLocaleContent } from './tool/rentalDepositReturn/entry';
 export { capitalGainsTaxScenarioCalculator } from './tool/capitalGainsTaxScenarioCalculator/entry';
 export type { CapitalGainsTaxScenarioCalculatorLocaleContent } from './tool/capitalGainsTaxScenarioCalculator/entry';
+export { loanAprScenarioCalculator } from './tool/loanAprScenarioCalculator/entry';
+export type { LoanAprScenarioCalculatorLocaleContent } from './tool/loanAprScenarioCalculator/entry';
 export { insuranceDeductibleBreakEvenCalculator } from './tool/insuranceDeductibleBreakEvenCalculator/entry';
 export type { InsuranceDeductibleBreakEvenCalculatorLocaleContent } from './tool/insuranceDeductibleBreakEvenCalculator/entry';
 export { financeCategory } from './category';
@@ -76,4 +78,6 @@ import { loanToIncomeRatio } from './tool/loanToIncomeRatio/entry';
 import { rentalDepositReturn } from './tool/rentalDepositReturn/entry';
 import { capitalGainsTaxScenarioCalculator } from './tool/capitalGainsTaxScenarioCalculator/entry';
 import { insuranceDeductibleBreakEvenCalculator } from './tool/insuranceDeductibleBreakEvenCalculator/entry';
-export const ALL_ENTRIES = [compoundInterest, financialFreedom, savingsRate, profitability, courtFeeCalculator, debtSnowball, fireCalculator, ibanBicSwift, inflation, lateInterest, legalInterestRate, lotteryOptimizer, mortgage, percentageCalculator, rentIncrease, revolvingCardCalculator, pesetaValue, salaryEmployerCost, dividendYield, mortgageExtraPaymentPlanner, inflationPurchasingPower, subscriptionCostAnnualizer, loanToIncomeRatio, rentalDepositReturn, capitalGainsTaxScenarioCalculator, insuranceDeductibleBreakEvenCalculator];
+import { renterInsuranceCoverageGapCalculator } from './tool/renterInsuranceCoverageGapCalculator/entry';
+import { loanAprScenarioCalculator } from './tool/loanAprScenarioCalculator/entry';
+export const ALL_ENTRIES = [compoundInterest, financialFreedom, savingsRate, profitability, courtFeeCalculator, debtSnowball, fireCalculator, ibanBicSwift, inflation, lateInterest, legalInterestRate, lotteryOptimizer, mortgage, percentageCalculator, rentIncrease, revolvingCardCalculator, pesetaValue, salaryEmployerCost, dividendYield, mortgageExtraPaymentPlanner, inflationPurchasingPower, subscriptionCostAnnualizer, loanToIncomeRatio, rentalDepositReturn, capitalGainsTaxScenarioCalculator, insuranceDeductibleBreakEvenCalculator, renterInsuranceCoverageGapCalculator, loanAprScenarioCalculator];

package/src/tests/locale_completeness.test.ts

@@ -25,7 +25,7 @@ describe('Locale Completeness Validation', () => {
     });
   });
 
-  it('all 26 tools registered', () => {
-    expect(ALL_TOOLS.length).toBe(26);
+  it('all 28 tools registered', () => {
+    expect(ALL_TOOLS.length).toBe(28);
   });
 });

package/src/tests/mfe_assets_contract.test.ts

@@ -0,0 +1,48 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { ALL_TOOLS } from '../tools';
+import { CATEGORY_OG_IMAGE, getUtilityOgImage } from '../mfe/assets';
+
+const categoryImageMatch = CATEGORY_OG_IMAGE.match(
+  /^(\/_utilities\/[^/]+\/images)\/([^/]+\.webp)\?version=(.+)$/,
+);
+
+if (!categoryImageMatch) {
+  throw new Error(`Unexpected CATEGORY_OG_IMAGE format: ${CATEGORY_OG_IMAGE}`);
+}
+
+const [, imageUrlRoot, categoryImage, assetVersion] = categoryImageMatch;
+const assetRoot = join(process.cwd(), 'public', imageUrlRoot.slice(1));
+const categorySlug = basename(categoryImage, '.webp');
+
+describe('MFE asset contract', () => {
+  it('has one non-empty English-slug OG image per category and registered tool', async () => {
+    const expectedSlugs = new Set([categorySlug]);
+
+    for (const { entry } of ALL_TOOLS) {
+      const englishLoader = entry.i18n.en;
+      if (!englishLoader) throw new Error(`Missing English locale for ${entry.id}`);
+
+      const englishContent = await englishLoader();
+      expectedSlugs.add(englishContent.slug);
+    }
+
+    const actualSlugs = new Set(
+      readdirSync(assetRoot)
+        .filter((filename) => filename.endsWith('.webp'))
+        .map((filename) => filename.slice(0, -'.webp'.length)),
+    );
+
+    expect(actualSlugs).toEqual(expectedSlugs);
+
+    for (const slug of expectedSlugs) {
+      const imagePath = join(assetRoot, `${slug}.webp`);
+      expect(existsSync(imagePath), `${imagePath} should exist`).toBe(true);
+      expect(statSync(imagePath).size, `${imagePath} should not be empty`).toBeGreaterThan(0);
+      expect(getUtilityOgImage(slug)).toBe(
+        `${imageUrlRoot}/${slug}.webp?version=${assetVersion}`,
+      );
+    }
+  }, 30000);
+});

package/src/tests/tool_validation.test.ts

@@ -4,8 +4,8 @@ import { financeCategory } from '../data';
 
 describe('Tool Validation Suite', () => {
   describe('Library Registration', () => {
-    it('should have 26 tools in ALL_TOOLS', () => {
-      expect(ALL_TOOLS.length).toBe(26);
+    it('should have 28 tools in ALL_TOOLS', () => {
+      expect(ALL_TOOLS.length).toBe(28);
     });
 
     it('financeCategory should be defined', () => {

package/src/tool/loanAprScenarioCalculator/bibliography.astro

@@ -0,0 +1,11 @@
+---
+import { Bibliography as SharedBibliography } from '@jjlmoya/utils-shared';
+import { loanAprScenarioCalculator } from './index';
+import type { KnownLocale } from '../../types';
+
+interface Props { locale?: KnownLocale; }
+const { locale = 'en' } = Astro.props;
+const content = await loanAprScenarioCalculator.i18n[locale]?.() ?? await loanAprScenarioCalculator.i18n.en?.();
+---
+
+{content && <SharedBibliography links={content.bibliography} />}

package/src/tool/loanAprScenarioCalculator/bibliography.ts

@@ -0,0 +1,29 @@
+import type { BibliographyEntry } from "../../types";
+
+export const bibliography: BibliographyEntry[] = [
+  {
+    name: "Banco de España: TAE de un préstamo o producto de financiación",
+    url: "https://clientebancario.bde.es/pcb/es/menu-horizontal/productosservici/relacionados/tiposinteres/guia-textual/latae/tae_prestamo.html",
+  },
+  {
+    name: "Consumer Financial Protection Bureau: What is the difference between a loan interest rate and the APR?",
+    url: "https://www.consumerfinance.gov/ask-cfpb/what-is-the-difference-between-a-loan-interest-rate-and-the-apr-en-733/",
+  },
+];
+
+export const bibliographyTraceability = [
+  {
+    country: "Spain",
+    language: "Spanish",
+    claim:
+      "TAE includes the nominal rate, payment frequency, bank fees and some transaction expenses.",
+    url: bibliography[0].url,
+  },
+  {
+    country: "United States",
+    language: "English",
+    claim:
+      "APR is a broader borrowing-cost measure than the interest rate because it includes additional fees.",
+    url: bibliography[1].url,
+  },
+];

package/src/tool/loanAprScenarioCalculator/component.astro

@@ -0,0 +1,62 @@
+---
+import type { LoanAprScenarioCalculatorUI } from './ui';
+import type { KnownLocale } from '../../types';
+import { currencyOptions, defaultCurrencyByLocale } from './currency';
+
+interface Props { ui: LoanAprScenarioCalculatorUI; locale?: KnownLocale; }
+const { ui, locale = 'en' } = Astro.props;
+const defaultCurrency = defaultCurrencyByLocale[locale] ?? 'USD';
+const defaultCurrencyOption = currencyOptions.find(({ code }) => code === defaultCurrency);
+const defaultCurrencySymbol = defaultCurrencyOption?.symbol ?? defaultCurrency;
+const defaultCurrencyName = defaultCurrencyOption?.name ?? defaultCurrency;
+const data = JSON.stringify({ ui, locale, currency: defaultCurrency, currencies: currencyOptions }).replace(/</g, '\\u003c');
+---
+
+<div class="loan-apr-tool" data-loan-apr-tool>
+  <form class="loan-apr-input-ribbon" data-loan-apr-form>
+    <div class="loan-apr-ribbon-head">
+      <div class="loan-apr-currency-copy"><span class="loan-apr-currency-label">{ui.labelCurrency}</span><small>{ui.labelApproximateRates}</small></div>
+      <div class="loan-apr-header-controls">
+        <div class="loan-apr-actions"><button type="button" class="loan-apr-text-button" data-reset>{ui.labelReset}</button><button type="button" class="loan-apr-copy-button" data-copy>{ui.labelCopy}</button><span class="loan-apr-copy-status" data-copy-status aria-live="polite"></span></div>
+        <div class="loan-apr-currency-select"><button type="button" class="loan-apr-currency-trigger" data-currency-trigger aria-expanded="false" aria-haspopup="listbox" aria-label={ui.labelCurrency}><span class="loan-apr-currency-trigger-main"><strong data-selected-currency-symbol>{defaultCurrencySymbol}</strong><span data-selected-currency-name>{defaultCurrencyName}</span></span><span class="loan-apr-currency-arrow" aria-hidden="true"></span></button><div class="loan-apr-currency-menu" data-currency-menu role="listbox" aria-label={ui.labelCurrency} hidden>{currencyOptions.map(({ code, symbol, name }) => <button type="button" class="loan-apr-currency-option" data-currency={code} role="option" aria-selected={code === defaultCurrency} aria-label={`${symbol} ${name}`}><strong>{symbol}</strong><span>{name}</span></button>)}</div></div>
+      </div>
+    </div>
+    <div class="loan-apr-presets" role="group" aria-label={ui.labelPreset}><button type="button" data-preset="balanced">{ui.labelPresetBalanced}</button><button type="button" data-preset="low-fee">{ui.labelPresetLowFee}</button><button type="button" data-preset="long-term">{ui.labelPresetLongTerm}</button></div>
+    <div class="loan-apr-scenarios">
+      <fieldset class="loan-apr-scenario" data-scenario="a">
+        <legend><span class="loan-apr-scenario-index">A</span><input data-field="name" type="text" value={ui.labelOfferNameA} aria-label={ui.labelScenarioName} /></legend>
+        <div class="loan-apr-field-grid"><label><span>{ui.labelPrincipal}</span><span class="loan-apr-input-with-unit"><input data-field="principal" type="number" min="1" step="100" value="10000" required /><b data-currency-unit>{defaultCurrencySymbol}</b></span></label><label><span>{ui.labelTerm}</span><span class="loan-apr-input-with-unit"><input data-field="term" type="number" min="1" max="600" step="1" value="36" required /><b>{ui.labelMonths}</b></span></label></div>
+        <div class="loan-apr-mode-row" role="group" aria-label={ui.labelInputBasis}><button type="button" data-mode-side="a" data-mode="rate" aria-pressed="true">{ui.labelRateMode}</button><button type="button" data-mode-side="a" data-mode="payment" aria-pressed="false">{ui.labelPaymentMode}</button></div>
+        <label data-mode-field="rate"><span>{ui.labelAnnualRate}</span><span class="loan-apr-input-with-unit"><input data-field="rate" type="number" min="0" max="100" step="0.01" value="6" required /><b>%</b></span></label>
+        <label data-mode-field="payment" hidden><span>{ui.labelMonthlyPayment}</span><span class="loan-apr-input-with-unit"><input data-field="payment" type="number" min="0" step="0.01" value="304.22" required /><b data-currency-unit>{defaultCurrencySymbol}</b></span></label>
+        <div class="loan-apr-fees"><label><span>{ui.labelUpfrontFees}</span><span class="loan-apr-input-with-unit"><input data-field="upfrontFees" type="number" min="0" step="10" value="0" /><b data-currency-unit>{defaultCurrencySymbol}</b></span></label><label><span>{ui.labelMonthlyFees}</span><span class="loan-apr-input-with-unit"><input data-field="monthlyFees" type="number" min="0" step="1" value="0" /><b data-currency-unit>{defaultCurrencySymbol}</b></span></label><label><span>{ui.labelFinalFees}</span><span class="loan-apr-input-with-unit"><input data-field="finalFees" type="number" min="0" step="10" value="0" /><b data-currency-unit>{defaultCurrencySymbol}</b></span></label></div>
+      </fieldset>
+      <div class="loan-apr-divider" aria-hidden="true"><span>VS</span></div>
+      <fieldset class="loan-apr-scenario" data-scenario="b">
+        <legend><span class="loan-apr-scenario-index">B</span><input data-field="name" type="text" value={ui.labelOfferNameB} aria-label={ui.labelScenarioName} /></legend>
+        <div class="loan-apr-field-grid"><label><span>{ui.labelPrincipal}</span><span class="loan-apr-input-with-unit"><input data-field="principal" type="number" min="1" step="100" value="10000" required /><b data-currency-unit>{defaultCurrencySymbol}</b></span></label><label><span>{ui.labelTerm}</span><span class="loan-apr-input-with-unit"><input data-field="term" type="number" min="1" max="600" step="1" value="36" required /><b>{ui.labelMonths}</b></span></label></div>
+        <div class="loan-apr-mode-row" role="group" aria-label={ui.labelInputBasis}><button type="button" data-mode-side="b" data-mode="rate" aria-pressed="true">{ui.labelRateMode}</button><button type="button" data-mode-side="b" data-mode="payment" aria-pressed="false">{ui.labelPaymentMode}</button></div>
+        <label data-mode-field="rate"><span>{ui.labelAnnualRate}</span><span class="loan-apr-input-with-unit"><input data-field="rate" type="number" min="0" max="100" step="0.01" value="7.25" required /><b>%</b></span></label>
+        <label data-mode-field="payment" hidden><span>{ui.labelMonthlyPayment}</span><span class="loan-apr-input-with-unit"><input data-field="payment" type="number" min="0" step="0.01" value="309.88" required /><b data-currency-unit>{defaultCurrencySymbol}</b></span></label>
+        <div class="loan-apr-fees"><label><span>{ui.labelUpfrontFees}</span><span class="loan-apr-input-with-unit"><input data-field="upfrontFees" type="number" min="0" step="10" value="150" /><b data-currency-unit>{defaultCurrencySymbol}</b></span></label><label><span>{ui.labelMonthlyFees}</span><span class="loan-apr-input-with-unit"><input data-field="monthlyFees" type="number" min="0" step="1" value="0" /><b data-currency-unit>{defaultCurrencySymbol}</b></span></label><label><span>{ui.labelFinalFees}</span><span class="loan-apr-input-with-unit"><input data-field="finalFees" type="number" min="0" step="10" value="0" /><b data-currency-unit>{defaultCurrencySymbol}</b></span></label></div>
+      </fieldset>
+    </div>
+  </form>
+  <section class="loan-apr-result" data-result aria-live="polite"></section>
+  <script is:inline type="application/json" data-loan-apr-data set:html={data}></script>
+  <script>
+    import { setupLoanAprScenarioCalculator } from './controller';
+    import type { LoanAprScenarioCalculatorUI } from './ui';
+    import type { LoanAprCurrencyCode } from './currency';
+    const root = document.querySelector<HTMLElement>('[data-loan-apr-tool]');
+    const dataNode = root?.querySelector<HTMLScriptElement>('[data-loan-apr-data]');
+    if (root && dataNode?.textContent) {
+      const data = JSON.parse(dataNode.textContent) as { ui: LoanAprScenarioCalculatorUI; locale: string; currency: LoanAprCurrencyCode };
+      setupLoanAprScenarioCalculator(root, data.ui, data.locale, data.currency);
+    }
+  </script>
+</div>
+
+<style is:global>
+  @import './loan-apr-scenario-calculator.css';
+</style>

package/src/tool/loanAprScenarioCalculator/controller.ts

@@ -0,0 +1,205 @@
+import { calculateScenario, compareScenarios } from "./logic";
+import type { LoanAprCurrencyCode } from "./currency";
+import {
+  defaultState,
+  loadStoredState,
+  saveStoredState,
+  type LoanAprStoredState,
+} from "./storage";
+import { formatResultForCopy, renderComparison } from "./dom-views";
+import type { LoanAprScenarioCalculatorUI } from "./ui";
+import {
+  closeCurrencyMenu,
+  convertMoneyFields,
+  setCurrencyState,
+  toggleCurrencyMenu,
+} from "./currency-dom";
+import { applyPreset } from "./presets";
+import {
+  readScenario,
+  setMode,
+  writeScenario,
+  type ScenarioSide,
+} from "./scenario-dom";
+
+function readState(
+  root: HTMLElement,
+  currency: LoanAprCurrencyCode,
+): LoanAprStoredState {
+  return {
+    scenarioA: readScenario(root, "a"),
+    scenarioB: readScenario(root, "b"),
+    currency,
+  };
+}
+
+function render(
+  root: HTMLElement,
+  ui: LoanAprScenarioCalculatorUI,
+  locale: string,
+  currency: LoanAprCurrencyCode,
+): { copy: string } {
+  const state = readState(root, currency);
+  const first = calculateScenario(state.scenarioA);
+  const second = calculateScenario(state.scenarioB);
+  const comparison = compareScenarios(first, second);
+  const result = root.querySelector<HTMLElement>("[data-result]");
+  if (result)
+    renderComparison({
+      root: result,
+      first,
+      second,
+      comparison,
+      context: { ui, locale, currency },
+    });
+  saveStoredState(state);
+  return {
+    copy: formatResultForCopy({
+      first,
+      second,
+      comparison,
+      context: { ui, locale, currency },
+    }),
+  };
+}
+
+export function setupLoanAprScenarioCalculator(
+  root: HTMLElement,
+  ui: LoanAprScenarioCalculatorUI,
+  locale: string,
+  defaultCurrency: LoanAprCurrencyCode,
+): void {
+  const stored = loadStoredState();
+  const initialState = stored ?? defaultState();
+  let selectedCurrency = stored?.currency ?? defaultCurrency;
+  writeScenario(root, "a", initialState.scenarioA);
+  writeScenario(root, "b", initialState.scenarioB);
+  setCurrencyState(root, selectedCurrency);
+  const copyStatus = root.querySelector<HTMLElement>("[data-copy-status]");
+  render(root, ui, locale, selectedCurrency);
+  const context: ControllerContext = {
+    ui,
+    locale,
+    defaultCurrency,
+    status: copyStatus,
+    getCurrency: () => selectedCurrency,
+    setCurrency: (currency) => {
+      selectedCurrency = currency;
+    },
+  };
+  bindEvents(root, context);
+}
+
+function bindEvents(root: HTMLElement, context: ControllerContext): void {
+  root.addEventListener("input", () =>
+    render(root, context.ui, context.locale, context.getCurrency()),
+  );
+  root.addEventListener("change", () =>
+    render(root, context.ui, context.locale, context.getCurrency()),
+  );
+  root.addEventListener("click", (event) => handleClick(root, event, context));
+}
+
+interface ControllerContext {
+  ui: LoanAprScenarioCalculatorUI;
+  locale: string;
+  defaultCurrency: LoanAprCurrencyCode;
+  status: HTMLElement | null;
+  getCurrency: () => LoanAprCurrencyCode;
+  setCurrency: (currency: LoanAprCurrencyCode) => void;
+}
+
+function resetTool(root: HTMLElement, context: ControllerContext): void {
+  const reset = defaultState();
+  writeScenario(root, "a", reset.scenarioA);
+  writeScenario(root, "b", reset.scenarioB);
+  context.setCurrency(context.defaultCurrency);
+  setCurrencyState(root, context.defaultCurrency);
+  closeCurrencyMenu(root);
+  render(root, context.ui, context.locale, context.defaultCurrency);
+  if (context.status) context.status.textContent = "";
+}
+
+function handleCurrencyClick(
+  root: HTMLElement,
+  target: HTMLElement,
+  context: ControllerContext,
+): boolean {
+  const trigger = target.closest<HTMLButtonElement>("[data-currency-trigger]");
+  if (trigger) {
+    toggleCurrencyMenu(root);
+    return true;
+  }
+  const option = target.closest<HTMLButtonElement>("[data-currency]");
+  if (!option) return false;
+  const nextCurrency = option.dataset.currency as LoanAprCurrencyCode;
+  convertMoneyFields(root, context.getCurrency(), nextCurrency);
+  context.setCurrency(nextCurrency);
+  setCurrencyState(root, nextCurrency);
+  closeCurrencyMenu(root);
+  render(root, context.ui, context.locale, nextCurrency);
+  return true;
+}
+
+function handleScenarioClick(
+  root: HTMLElement,
+  target: HTMLElement,
+  context: ControllerContext,
+): boolean {
+  const modeButton = target.closest<HTMLButtonElement>(
+    "[data-mode-side][data-mode]",
+  );
+  if (modeButton) {
+    setMode(
+      root,
+      modeButton.dataset.modeSide as ScenarioSide,
+      modeButton.dataset.mode as LoanMode,
+    );
+    render(root, context.ui, context.locale, context.getCurrency());
+    return true;
+  }
+  const preset = target.closest<HTMLButtonElement>("[data-preset]");
+  if (!preset) return false;
+  applyPreset(root, preset.dataset.preset ?? "balanced");
+  render(root, context.ui, context.locale, context.getCurrency());
+  return true;
+}
+
+function handleActionClick(
+  root: HTMLElement,
+  target: HTMLElement,
+  context: ControllerContext,
+): void {
+  if (target.closest("[data-reset]")) {
+    resetTool(root, context);
+    return;
+  }
+  if (target.closest("[data-copy]"))
+    void copyText(
+      render(root, context.ui, context.locale, context.getCurrency()).copy,
+      context.status,
+      context.ui.labelCopied,
+    );
+}
+
+function handleClick(
+  root: HTMLElement,
+  event: Event,
+  context: ControllerContext,
+): void {
+  const target = event.target as HTMLElement;
+  if (handleCurrencyClick(root, target, context)) return;
+  if (handleScenarioClick(root, target, context)) return;
+  handleActionClick(root, target, context);
+}
+
+async function copyText(
+  text: string,
+  status: HTMLElement | null,
+  copiedLabel: string,
+): Promise<void> {
+  try {
+    await navigator.clipboard.writeText(text);
+    if (status) status.textContent = copiedLabel;
+  } catch {}
+}

package/src/tool/loanAprScenarioCalculator/currency-dom.ts

@@ -0,0 +1,107 @@
+import {
+  convertLoanCurrency,
+  currencyOptions,
+  type LoanAprCurrencyCode,
+} from "./currency";
+
+const moneyFields = [
+  "principal",
+  "payment",
+  "upfrontFees",
+  "monthlyFees",
+  "finalFees",
+] as const;
+
+function currencyDisplay(
+  currency: LoanAprCurrencyCode,
+  selected: HTMLButtonElement | null,
+): { symbol: string; name: string } {
+  const option = currencyOptions.find(({ code }) => code === currency);
+  return {
+    symbol:
+      option?.symbol ??
+      selected?.querySelector("strong")?.textContent ??
+      currency,
+    name: option?.name ?? currency,
+  };
+}
+
+function markCurrencyOptions(
+  root: HTMLElement,
+  currency: LoanAprCurrencyCode,
+): void {
+  root
+    .querySelectorAll<HTMLButtonElement>("[data-currency]")
+    .forEach((button) =>
+      button.setAttribute(
+        "aria-selected",
+        String(button.dataset.currency === currency),
+      ),
+    );
+}
+
+function updateCurrencyLabels(
+  root: HTMLElement,
+  display: { symbol: string; name: string },
+): void {
+  root
+    .querySelector<HTMLElement>("[data-selected-currency-symbol]")
+    ?.replaceChildren(display.symbol);
+  root
+    .querySelector<HTMLElement>("[data-selected-currency-name]")
+    ?.replaceChildren(display.name);
+  root
+    .querySelectorAll<HTMLElement>("[data-currency-unit]")
+    .forEach((unit) => (unit.textContent = display.symbol));
+}
+
+export function setCurrencyState(
+  root: HTMLElement,
+  currency: LoanAprCurrencyCode,
+): void {
+  const selected = root.querySelector<HTMLButtonElement>(
+    `[data-currency="${currency}"]`,
+  );
+  markCurrencyOptions(root, currency);
+  updateCurrencyLabels(root, currencyDisplay(currency, selected));
+}
+
+export function closeCurrencyMenu(root: HTMLElement): void {
+  const menu = root.querySelector<HTMLElement>("[data-currency-menu]");
+  const trigger = root.querySelector<HTMLButtonElement>(
+    "[data-currency-trigger]",
+  );
+  if (menu && trigger) {
+    menu.hidden = true;
+    trigger.setAttribute("aria-expanded", "false");
+  }
+}
+
+export function toggleCurrencyMenu(root: HTMLElement): void {
+  const menu = root.querySelector<HTMLElement>("[data-currency-menu]");
+  const trigger = root.querySelector<HTMLButtonElement>(
+    "[data-currency-trigger]",
+  );
+  if (menu && trigger) {
+    menu.hidden = !menu.hidden;
+    trigger.setAttribute("aria-expanded", String(!menu.hidden));
+  }
+}
+
+export function convertMoneyFields(
+  root: HTMLElement,
+  from: LoanAprCurrencyCode,
+  to: LoanAprCurrencyCode,
+): void {
+  if (from === to) return;
+  (["a", "b"] as const).forEach((side) =>
+    moneyFields.forEach((field) => {
+      const input = root.querySelector<HTMLInputElement>(
+        `[data-scenario="${side}"] [data-field="${field}"]`,
+      );
+      const value = Number(input?.value);
+      if (input && Number.isFinite(value))
+        input.value = String(convertLoanCurrency(value, from, to));
+    }),
+  );
+}

package/src/tool/loanAprScenarioCalculator/currency.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import {
+  convertLoanCurrency,
+  currencyOptions,
+  defaultCurrencyByLocale,
+} from "./currency";
+
+describe("loan APR currency support", () => {
+  it("offers the international currency set used by the other scenario tools", () => {
+    expect(currencyOptions.map(({ code }) => code)).toEqual([
+      "AUD",
+      "BRL",
+      "CAD",
+      "CHF",
+      "CNY",
+      "CZK",
+      "DKK",
+      "EUR",
+      "GBP",
+      "IDR",
+      "INR",
+      "JPY",
+      "KRW",
+      "MXN",
+      "NOK",
+      "PLN",
+      "RUB",
+      "SEK",
+      "TRY",
+      "USD",
+    ]);
+  });
+
+  it("uses a symbol and name for every currency option", () => {
+    expect(currencyOptions.find(({ code }) => code === "RUB")).toMatchObject({
+      symbol: "₽",
+      name: "Russian ruble",
+    });
+    expect(currencyOptions.every(({ symbol, name }) => symbol && name)).toBe(
+      true,
+    );
+  });
+
+  it("selects a useful default for each supported locale family", () => {
+    expect(defaultCurrencyByLocale).toMatchObject({
+      en: "USD",
+      es: "EUR",
+      ja: "JPY",
+      zh: "CNY",
+    });
+  });
+
+  it("converts monetary inputs with reversible planning factors", () => {
+    expect(convertLoanCurrency(100, "EUR", "USD")).toBe(108.7);
+    expect(convertLoanCurrency(108.7, "USD", "EUR")).toBe(100);
+  });
+});