@jjlmoya/utils-finance 1.43.0 → 1.45.0

package/src/tool/insuranceDeductibleBreakEvenCalculator/insurance-deductible-break-even-calculator.css

@@ -0,0 +1,424 @@
+:root {
+  --idb-ink: #25251f;
+  --idb-muted: #716c60;
+  --idb-paper: #fbf8ef;
+  --idb-surface: #f0eadb;
+  --idb-edge: #d6c9aa;
+  --idb-claim: #36747b;
+  --idb-claim-soft: #d6e8e4;
+  --idb-pay: #b5533b;
+  --idb-pay-soft: #efd8c8;
+  --idb-gold: #bf8a37;
+  --idb-on-accent: #fffaf1;
+  --idb-shadow: #51463122;
+}
+
+:global(.theme-dark) {
+  --idb-ink: #f3eee3;
+  --idb-muted: #bbb3a4;
+  --idb-paper: #24251f;
+  --idb-surface: #2d3028;
+  --idb-edge: #565446;
+  --idb-claim: #84c3c3;
+  --idb-claim-soft: #294b4b;
+  --idb-pay: #df8663;
+  --idb-pay-soft: #5b352b;
+  --idb-gold: #e1b45d;
+  --idb-on-accent: #281d18;
+  --idb-shadow: #0006;
+}
+
+.idb-tool {
+  background: var(--idb-paper);
+  border: 1px solid var(--idb-edge);
+  border-radius: 1.35rem;
+  box-shadow: 0 1rem 2.5rem var(--idb-shadow);
+  color: var(--idb-ink);
+  margin: 0 auto;
+  max-width: 74rem;
+  overflow: hidden;
+  width: min(100%, calc(100vw - 2rem));
+}
+
+.idb-card {
+  display: grid;
+  gap: 1.35rem;
+  padding: 1.35rem;
+}
+
+.idb-glance {
+  align-items: stretch;
+  background: var(--idb-surface);
+  border: 1px solid var(--idb-edge);
+  border-radius: 1rem;
+  display: grid;
+  gap: 1px;
+  grid-template-columns: repeat(2, 1fr);
+  overflow: hidden;
+}
+
+.idb-glance > div {
+  display: grid;
+  gap: 0.35rem;
+  padding: 1rem;
+}
+
+.idb-glance > div + div {
+  border-left: 1px solid var(--idb-edge);
+}
+
+.idb-glance span,
+.idb-result-grid span,
+.idb-visual-heading,
+.idb-help,
+.idb-method,
+.idb-privacy,
+.idb-result-note {
+  color: var(--idb-muted);
+  font-size: 0.78rem;
+  line-height: 1.45;
+}
+
+.idb-glance strong {
+  font-size: clamp(1.15rem, 2.4vw, 1.65rem);
+  line-height: 1.1;
+}
+
+.idb-inputs {
+  display: grid;
+  gap: 1rem;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+}
+
+.idb-field {
+  display: grid;
+  gap: 0.38rem;
+}
+
+.idb-field label,
+.idb-label {
+  font-size: 0.82rem;
+  font-weight: 800;
+}
+
+.idb-input-wrap {
+  align-items: center;
+  background: var(--idb-paper);
+  border: 1px solid var(--idb-edge);
+  border-radius: 0.65rem;
+  display: flex;
+  min-height: 2.8rem;
+  overflow: hidden;
+}
+
+.idb-input-wrap input {
+  background: transparent;
+  border: 0;
+  box-sizing: border-box;
+  color: var(--idb-ink);
+  font: inherit;
+  min-width: 0;
+  outline: 0;
+  padding: 0.62rem 0.7rem;
+  width: 100%;
+}
+
+.idb-input-wrap span {
+  color: var(--idb-muted);
+  font-size: 0.85rem;
+  padding: 0 0.7rem;
+}
+
+.idb-field > small:not(.idb-help) {
+  color: var(--idb-pay);
+  font-size: 0.74rem;
+}
+
+.idb-field > small[hidden] {
+  display: none;
+}
+
+.idb-input-wrap:focus-within,
+.idb-currency:focus-visible,
+.idb-button:focus-visible,
+.idb-method summary:focus-visible {
+  outline: 3px solid var(--idb-gold);
+  outline-offset: 2px;
+}
+
+.idb-currency-field,
+.idb-currency-select {
+  position: relative;
+}
+
+.idb-currency-trigger {
+  align-items: center;
+  background: var(--idb-paper);
+  border: 1px solid var(--idb-edge);
+  border-radius: 0.65rem;
+  color: var(--idb-ink);
+  cursor: pointer;
+  display: flex;
+  font: inherit;
+  justify-content: space-between;
+  min-height: 2.8rem;
+  padding: 0.62rem 0.7rem;
+  text-align: left;
+  width: 100%;
+}
+
+.idb-currency-trigger-main {
+  align-items: center;
+  display: flex;
+  gap: 0.55rem;
+}
+
+.idb-currency-trigger-main strong {
+  font-size: 1.1rem;
+  line-height: 1;
+}
+
+.idb-currency-arrow {
+  border-bottom: 2px solid var(--idb-claim);
+  border-right: 2px solid var(--idb-claim);
+  height: 0.45rem;
+  transform: rotate(45deg) translateY(-0.15rem);
+  transition: transform 160ms ease;
+  width: 0.45rem;
+}
+
+.idb-currency-trigger[aria-expanded="true"] .idb-currency-arrow {
+  transform: rotate(225deg) translateY(-0.05rem);
+}
+
+.idb-currency-menu {
+  background: var(--idb-paper);
+  border: 1px solid var(--idb-edge);
+  border-radius: 0.75rem;
+  box-shadow: 0 1rem 2rem var(--idb-shadow);
+  display: grid;
+  gap: 0.35rem;
+  grid-template-columns: repeat(5, minmax(0, 1fr));
+  left: 0;
+  padding: 0.5rem;
+  position: absolute;
+  right: 0;
+  top: calc(100% + 0.4rem);
+  z-index: 20;
+}
+
+.idb-currency-menu[hidden] {
+  display: none;
+}
+
+.idb-currency-option {
+  align-items: center;
+  background: transparent;
+  border: 1px solid transparent;
+  border-radius: 0.55rem;
+  color: var(--idb-ink);
+  cursor: pointer;
+  display: flex;
+  font: inherit;
+  gap: 0.35rem;
+  justify-content: center;
+  min-width: 0;
+  padding: 0.55rem 0.3rem;
+}
+
+.idb-currency-option span {
+  color: var(--idb-muted);
+  font-size: 0.7rem;
+  font-weight: 800;
+}
+
+.idb-currency-option[aria-selected="true"],
+.idb-currency-option:hover {
+  background: var(--idb-claim-soft);
+  border-color: var(--idb-claim);
+  color: var(--idb-claim);
+}
+
+.idb-help {
+  margin: 0;
+}
+
+.idb-actions {
+  align-items: center;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.7rem;
+}
+
+.idb-button {
+  border: 1px solid var(--idb-claim);
+  border-radius: 99rem;
+  cursor: pointer;
+  font: inherit;
+  font-weight: 800;
+  min-height: 2.75rem;
+  padding: 0.55rem 1rem;
+}
+
+.idb-button-primary {
+  background: var(--idb-claim);
+  color: var(--idb-on-accent);
+}
+
+.idb-button-secondary {
+  background: transparent;
+  color: var(--idb-claim);
+}
+
+.idb-actions [role="status"] {
+  color: var(--idb-muted);
+  font-size: 0.78rem;
+}
+
+.idb-output {
+  border-top: 1px solid var(--idb-edge);
+  display: grid;
+  gap: 1rem;
+  padding-top: 1.35rem;
+}
+
+.idb-visual {
+  background: var(--idb-surface);
+  border: 1px solid var(--idb-edge);
+  border-radius: 1rem;
+  display: grid;
+  gap: 0.8rem;
+  padding: 1rem;
+}
+
+.idb-visual-heading {
+  display: flex;
+  font-weight: 800;
+  justify-content: space-between;
+}
+
+.idb-bars {
+  align-items: end;
+  display: grid;
+  gap: 0.75rem;
+  grid-template-columns: 1fr auto 1fr;
+}
+
+.idb-bar-side {
+  display: grid;
+  gap: 0.4rem;
+}
+
+.idb-bar-side:first-child {
+  text-align: left;
+}
+
+.idb-bar-side:last-child {
+  text-align: right;
+}
+
+.idb-bar-track {
+  background: var(--idb-paper);
+  border: 1px solid var(--idb-edge);
+  border-radius: 99rem;
+  height: 1rem;
+  overflow: hidden;
+}
+
+.idb-bar-track i {
+  border-radius: inherit;
+  display: block;
+  height: 100%;
+  min-width: 8%;
+  transition: width 180ms ease;
+}
+
+.idb-bar-side:first-child i {
+  background: var(--idb-claim);
+}
+
+.idb-bar-side:last-child i {
+  background: var(--idb-pay);
+  margin-left: auto;
+}
+
+.idb-scale {
+  color: var(--idb-gold);
+  font-size: 1.55rem;
+  font-weight: 800;
+}
+
+.idb-result-grid {
+  display: grid;
+  gap: 0.65rem;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+}
+
+.idb-result-grid > div {
+  background: var(--idb-surface);
+  border: 1px solid var(--idb-edge);
+  border-radius: 0.75rem;
+  display: grid;
+  gap: 0.35rem;
+  padding: 0.8rem;
+}
+
+.idb-result-grid strong {
+  font-size: 1.08rem;
+}
+
+.idb-result-grid .idb-emphasis {
+  background: var(--idb-claim-soft);
+  border-color: var(--idb-claim);
+}
+
+.idb-result-note {
+  margin: 0;
+}
+
+.idb-error-summary {
+  background: var(--idb-pay-soft);
+  border: 1px solid var(--idb-pay);
+  border-radius: 0.65rem;
+  color: var(--idb-ink);
+  margin: 0;
+  padding: 0.7rem 0.8rem;
+}
+
+.idb-error-summary[hidden] {
+  display: none;
+}
+
+.idb-privacy,
+.idb-method {
+  margin: 0;
+}
+
+.idb-method summary {
+  cursor: pointer;
+  font-weight: 800;
+}
+
+.idb-method p {
+  margin: 0.65rem 0 0;
+}
+
+@media (max-width: 42rem) {
+  .idb-card {
+    padding: 1rem;
+  }
+
+  .idb-inputs,
+  .idb-result-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .idb-glance {
+    grid-template-columns: 1fr;
+  }
+
+  .idb-glance > div + div {
+    border-left: 0;
+    border-top: 1px solid var(--idb-edge);
+  }
+}

package/src/tool/insuranceDeductibleBreakEvenCalculator/logic.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { calculateInsuranceDeductibleBreakEven, validateInsuranceInput, type InsuranceDeductibleInput } from './logic';
+
+const baseInput: InsuranceDeductibleInput = { currency: 'USD', damageCost: 2500, deductible: 500, annualPremium: 1200, premiumIncreasePercent: 10, surchargeYears: 3 };
+
+describe('calculateInsuranceDeductibleBreakEven', () => {
+  it('compares a claim with paying the full damage cost', () => {
+    const result = calculateInsuranceDeductibleBreakEven(baseInput);
+    expect(result).toMatchObject({ claimCost: 860, payYourselfCost: 2500, premiumSurcharge: 360, insurerShare: 2000, recommendation: 'claim', breakEvenDamage: 860 });
+  });
+
+  it('recommends paying yourself when the damage is below break even', () => {
+    const result = calculateInsuranceDeductibleBreakEven({ ...baseInput, damageCost: 700 });
+    expect(result?.recommendation).toBe('payYourself');
+    expect(result?.claimCost).toBe(860);
+  });
+
+  it('recognizes the exact break-even amount', () => {
+    const result = calculateInsuranceDeductibleBreakEven({ ...baseInput, damageCost: 860 });
+    expect(result?.recommendation).toBe('breakEven');
+    expect(result?.difference).toBe(0);
+  });
+
+  it('rejects invalid ranges and impossible values', () => {
+    const invalid = { ...baseInput, damageCost: 0, premiumIncreasePercent: 101, surchargeYears: 21 };
+    expect(Object.keys(validateInsuranceInput(invalid))).toEqual(['damageCost', 'premiumIncreasePercent', 'surchargeYears']);
+    expect(calculateInsuranceDeductibleBreakEven(invalid)).toBeNull();
+  });
+
+  it('handles a deductible larger than the damage', () => {
+    const result = calculateInsuranceDeductibleBreakEven({ ...baseInput, damageCost: 300, deductible: 500, premiumIncreasePercent: 0 });
+    expect(result).toMatchObject({ insurerShare: 0, claimCost: 300, recommendation: 'breakEven' });
+  });
+
+  it('accepts the documented upper bounds without losing a finite result', () => {
+    const result = calculateInsuranceDeductibleBreakEven({ currency: 'USD', damageCost: 1_000_000_000_000, deductible: 1_000_000_000_000, annualPremium: 1_000_000_000_000, premiumIncreasePercent: 100, surchargeYears: 20 });
+    expect(result?.claimCost).toBe(21_000_000_000_000);
+    expect(result?.payYourselfCost).toBe(1_000_000_000_000);
+  });
+});

package/src/tool/insuranceDeductibleBreakEvenCalculator/logic.ts

@@ -0,0 +1,72 @@
+import { isInsuranceCurrencyCode, type InsuranceCurrencyCode } from './currency';
+
+export interface InsuranceDeductibleInput {
+  currency: string;
+  damageCost: number;
+  deductible: number;
+  annualPremium: number;
+  premiumIncreasePercent: number;
+  surchargeYears: number;
+}
+
+export type InsuranceRecommendation = 'claim' | 'payYourself' | 'breakEven';
+
+export interface InsuranceValidationErrors {
+  currency?: string;
+  damageCost?: string;
+  deductible?: string;
+  annualPremium?: string;
+  premiumIncreasePercent?: string;
+  surchargeYears?: string;
+}
+
+export interface InsuranceDeductibleResult {
+  currency: InsuranceCurrencyCode;
+  damageCost: number;
+  deductible: number;
+  annualPremium: number;
+  premiumIncreasePercent: number;
+  surchargeYears: number;
+  premiumSurcharge: number;
+  insurerShare: number;
+  claimCost: number;
+  payYourselfCost: number;
+  difference: number;
+  breakEvenDamage: number;
+  recommendation: InsuranceRecommendation;
+}
+
+const roundMoney = (value: number): number => Number(value.toFixed(2));
+const isMoney = (value: number): boolean => Number.isFinite(value) && value >= 0 && value <= 1_000_000_000_000;
+
+export function validateInsuranceInput(input: InsuranceDeductibleInput): InsuranceValidationErrors {
+  const errors: InsuranceValidationErrors = {};
+  const currency = input.currency.trim().toUpperCase();
+  const addError = (key: keyof InsuranceValidationErrors, invalid: boolean): void => { if (invalid) errors[key] = key; };
+  addError('currency', !isInsuranceCurrencyCode(currency));
+  addError('damageCost', !Number.isFinite(input.damageCost) || input.damageCost <= 0 || input.damageCost > 1_000_000_000_000);
+  addError('deductible', !isMoney(input.deductible));
+  addError('annualPremium', !isMoney(input.annualPremium));
+  addError('premiumIncreasePercent', !Number.isFinite(input.premiumIncreasePercent) || input.premiumIncreasePercent < 0 || input.premiumIncreasePercent > 100);
+  addError('surchargeYears', !Number.isFinite(input.surchargeYears) || input.surchargeYears <= 0 || input.surchargeYears > 20);
+  return errors;
+}
+
+const recommendationFor = (difference: number): InsuranceRecommendation => {
+  if (difference > 0.005) return 'claim';
+  if (difference < -0.005) return 'payYourself';
+  return 'breakEven';
+};
+
+export function calculateInsuranceDeductibleBreakEven(input: InsuranceDeductibleInput): InsuranceDeductibleResult | null {
+  const errors = validateInsuranceInput(input);
+  if (Object.keys(errors).length > 0) return null;
+  const currency = input.currency.trim().toUpperCase() as InsuranceCurrencyCode;
+  const premiumSurcharge = roundMoney(input.annualPremium * input.premiumIncreasePercent / 100 * input.surchargeYears);
+  const insurerShare = roundMoney(Math.max(0, input.damageCost - input.deductible));
+  const claimCost = roundMoney(Math.min(input.damageCost, input.deductible) + premiumSurcharge);
+  const payYourselfCost = roundMoney(input.damageCost);
+  const difference = roundMoney(payYourselfCost - claimCost);
+  const breakEvenDamage = roundMoney(input.deductible + premiumSurcharge);
+  return { currency, damageCost: payYourselfCost, deductible: roundMoney(input.deductible), annualPremium: roundMoney(input.annualPremium), premiumIncreasePercent: input.premiumIncreasePercent, surchargeYears: input.surchargeYears, premiumSurcharge, insurerShare, claimCost, payYourselfCost, difference, breakEvenDamage, recommendation: recommendationFor(difference) };
+}

package/src/tool/insuranceDeductibleBreakEvenCalculator/seo.astro

@@ -0,0 +1,11 @@
+---
+import { SEORenderer } from '@jjlmoya/utils-shared';
+import { insuranceDeductibleBreakEvenCalculator } from './entry';
+import type { KnownLocale } from '../../types';
+
+interface Props { locale?: KnownLocale; }
+const { locale = 'en' } = Astro.props;
+const content = await insuranceDeductibleBreakEvenCalculator.i18n[locale]?.() ?? await insuranceDeductibleBreakEvenCalculator.i18n.en?.();
+---
+
+{content?.seo && <SEORenderer content={{ locale, sections: content.seo }} />}

package/src/tool/insuranceDeductibleBreakEvenCalculator/ui.ts

@@ -0,0 +1,33 @@
+export interface InsuranceDeductibleBreakEvenCalculatorUI extends Record<string, string> {
+  labelDamageCost: string;
+  labelDeductible: string;
+  labelAnnualPremium: string;
+  labelPremiumIncrease: string;
+  labelSurchargeYears: string;
+  labelCurrency: string;
+  labelClaimRoute: string;
+  labelPayYourselfRoute: string;
+  labelClaimCost: string;
+  labelPayYourselfCost: string;
+  labelPremiumSurcharge: string;
+  labelInsurerShare: string;
+  labelBreakEvenDamage: string;
+  labelDifference: string;
+  labelRecommendation: string;
+  labelClaimRecommended: string;
+  labelPayYourselfRecommended: string;
+  labelBreakEvenRecommendation: string;
+  labelVisual: string;
+  labelReset: string;
+  labelCopy: string;
+  labelCopied: string;
+  labelCopyFailed: string;
+  labelInvalidInput: string;
+  labelMethodTitle: string;
+  labelMethodText: string;
+  labelPrivacyNote: string;
+  labelAmountPlaceholder: string;
+  labelPercentPlaceholder: string;
+  labelYearsPlaceholder: string;
+  labelApproximateRates: string;
+}

package/src/tools.ts

@@ -25,5 +25,6 @@ import { SUBSCRIPTION_COST_ANNUALIZER_TOOL } from './tool/subscriptionCostAnnual
 import { LOAN_TO_INCOME_RATIO_TOOL } from './tool/loanToIncomeRatio';
 import { RENTAL_DEPOSIT_RETURN_TOOL } from './tool/rentalDepositReturn';
 import { CAPITAL_GAINS_TAX_SCENARIO_CALCULATOR_TOOL } from './tool/capitalGainsTaxScenarioCalculator';
+import { INSURANCE_DEDUCTIBLE_BREAK_EVEN_CALCULATOR_TOOL } from './tool/insuranceDeductibleBreakEvenCalculator';
 
-export const ALL_TOOLS: ToolDefinition[] = [COMPOUND_INTEREST_TOOL, FINANCIAL_FREEDOM_TOOL, SAVINGS_RATE_TOOL, PROFITABILITY_TOOL, MORTGAGE_TOOL, INFLATION_TOOL, PERCENTAGE_CALCULATOR_TOOL, LATE_INTEREST_TOOL, IBAN_BIC_SWIFT_TOOL, RENT_INCREASE_TOOL, LOTTERY_OPTIMIZER_TOOL, COURT_FEE_CALCULATOR_TOOL, LEGAL_INTEREST_RATE_TOOL, FIRE_CALCULATOR_TOOL, DEBT_SNOWBALL_TOOL, REVOLVING_CARD_CALCULATOR_TOOL, PESETA_VALUE_TOOL, SALARY_EMPLOYER_COST_TOOL, DIVIDEND_YIELD_TOOL, MORTGAGE_EXTRA_PAYMENT_PLANNER_TOOL, INFLATION_PURCHASING_POWER_TOOL, SUBSCRIPTION_COST_ANNUALIZER_TOOL, LOAN_TO_INCOME_RATIO_TOOL, RENTAL_DEPOSIT_RETURN_TOOL, CAPITAL_GAINS_TAX_SCENARIO_CALCULATOR_TOOL];
+export const ALL_TOOLS: ToolDefinition[] = [COMPOUND_INTEREST_TOOL, FINANCIAL_FREEDOM_TOOL, SAVINGS_RATE_TOOL, PROFITABILITY_TOOL, MORTGAGE_TOOL, INFLATION_TOOL, PERCENTAGE_CALCULATOR_TOOL, LATE_INTEREST_TOOL, IBAN_BIC_SWIFT_TOOL, RENT_INCREASE_TOOL, LOTTERY_OPTIMIZER_TOOL, COURT_FEE_CALCULATOR_TOOL, LEGAL_INTEREST_RATE_TOOL, FIRE_CALCULATOR_TOOL, DEBT_SNOWBALL_TOOL, REVOLVING_CARD_CALCULATOR_TOOL, PESETA_VALUE_TOOL, SALARY_EMPLOYER_COST_TOOL, DIVIDEND_YIELD_TOOL, MORTGAGE_EXTRA_PAYMENT_PLANNER_TOOL, INFLATION_PURCHASING_POWER_TOOL, SUBSCRIPTION_COST_ANNUALIZER_TOOL, LOAN_TO_INCOME_RATIO_TOOL, RENTAL_DEPOSIT_RETURN_TOOL, CAPITAL_GAINS_TAX_SCENARIO_CALCULATOR_TOOL, INSURANCE_DEDUCTIBLE_BREAK_EVEN_CALCULATOR_TOOL];