@jjlmoya/utils-finance 1.43.0 → 1.44.0

package/src/tool/insuranceDeductibleBreakEvenCalculator/i18n/en.ts

@@ -0,0 +1,100 @@
+import type { ToolLocaleContent } from '../../../types';
+import { bibliography } from '../bibliography';
+import type { InsuranceDeductibleBreakEvenCalculatorUI } from '../ui';
+
+export const ui: InsuranceDeductibleBreakEvenCalculatorUI = {
+  labelDamageCost: 'Estimated damage cost',
+  labelDeductible: 'Policy deductible',
+  labelAnnualPremium: 'Current annual premium',
+  labelPremiumIncrease: 'Possible premium increase',
+  labelSurchargeYears: 'Years with the increase',
+  labelCurrency: 'Display currency',
+  labelClaimRoute: 'File a claim',
+  labelPayYourselfRoute: 'Pay the damage yourself',
+  labelClaimCost: 'Your estimated claim cost',
+  labelPayYourselfCost: 'Your estimated self-pay cost',
+  labelPremiumSurcharge: 'Estimated premium surcharge',
+  labelInsurerShare: 'Amount above the deductible',
+  labelBreakEvenDamage: 'Break-even damage amount',
+  labelDifference: 'Potential saving by choosing the cheaper route',
+  labelRecommendation: 'Model recommendation',
+  labelClaimRecommended: 'Filing may cost less',
+  labelPayYourselfRecommended: 'Paying yourself may cost less',
+  labelBreakEvenRecommendation: 'Both routes cost about the same',
+  labelVisual: 'Comparison of estimated costs for filing a claim and paying the damage yourself',
+  labelReset: 'Reset example',
+  labelCopy: 'Copy summary',
+  labelCopied: 'Summary copied',
+  labelCopyFailed: 'Copy it manually from the result',
+  labelInvalidInput: 'Check the highlighted value',
+  labelMethodTitle: 'How this estimate works',
+  labelMethodText: 'The model treats the claim route as the deductible, or the full damage when the damage is below the deductible, plus the extra premium caused by the increase you enter. It compares that amount with paying the full damage yourself. The break-even damage amount is the deductible plus the estimated total surcharge. Check that your policy covers this type of loss and ask your insurer how a claim could affect your premium.',
+  labelPrivacyNote: 'Your figures stay in this browser. No account, API or server calculation is required.',
+  labelAmountPlaceholder: '0.00',
+  labelPercentPlaceholder: '0 to 100',
+  labelYearsPlaceholder: '0.5 to 20',
+  labelApproximateRates: 'Currency changes use approximate planning factors, not live exchange rates.',
+};
+
+const slug = 'insurance-deductible-break-even-calculator';
+const title = 'Insurance Deductible Break Even Calculator';
+const description = 'Compare filing an insurance claim with paying for a loss yourself using your damage cost, deductible, premium and possible surcharge. This private browser estimate helps you see the break-even amount without predicting your insurer\'s decision.';
+
+const faq = [
+  {
+    question: 'What does this insurance deductible calculator compare?',
+    answer: 'It compares two user-defined routes for one loss: the estimated out-of-pocket cost of filing a claim and the full cost of paying for the damage yourself. The claim route includes the deductible and the possible premium surcharge you enter.',
+  },
+  {
+    question: 'What is the break-even damage amount?',
+    answer: 'In this model, it is the deductible plus the estimated total premium surcharge. Damage above that amount may make a claim cheaper, while damage below it may make self-payment cheaper. The result assumes the loss is covered and the insurer pays the eligible amount above the deductible.',
+  },
+  {
+    question: 'Can this calculator predict whether my premium will increase?',
+    answer: 'No. You provide the possible percentage and the number of years for the estimate. Your insurer, policy, claim history, location and type of loss determine what actually happens.',
+  },
+  {
+    question: 'What if the damage is smaller than my deductible?',
+    answer: 'The model shows no insurer contribution because the damage does not exceed the deductible. Filing may still have policy or reporting implications, so check your policy and ask the insurer before deciding.',
+  },
+  {
+    question: 'Is the result insurance or legal advice?',
+    answer: 'No. It is a transparent comparison using your own assumptions. It does not check coverage, depreciation, claim limits, taxes, reporting deadlines or local rules, and it does not recommend concealing a loss or delaying a required notice.',
+  },
+];
+
+const howTo = [
+  { name: 'Enter the estimated damage', text: 'Use the repair, replacement or loss amount you are currently considering, in the currency shown.' },
+  { name: 'Add the policy deductible', text: 'Enter the deductible that applies to this type of claim, rather than a different deductible from another part of the policy.' },
+  { name: 'Test the premium effect', text: 'Enter a possible percentage increase and how many years you want to include. Use zero when you want to see the deductible-only comparison.' },
+  { name: 'Read the decision boundary', text: 'Compare the two estimated costs and the break-even damage amount, then confirm coverage and any reporting requirement with your insurer.' },
+];
+
+export const content: ToolLocaleContent<InsuranceDeductibleBreakEvenCalculatorUI> = {
+  slug,
+  title,
+  description,
+  ui,
+  seo: [
+    { type: 'title', text: 'Should you file a claim or pay for the damage?', level: 2 },
+    { type: 'paragraph', html: '<p>A small loss can create an awkward insurance decision. The deductible is only part of the picture if you expect a claim to affect future premiums. This calculator puts your own damage estimate, deductible and possible surcharge into one transparent comparison so you can see the cost boundary before contacting the insurer.</p>' },
+    { type: 'title', text: 'What you need to enter', level: 2 },
+    { type: 'list', items: ['The estimated cost of the damage or repair.', 'The deductible shown for this coverage in your policy.', 'Your current annual premium.', 'A possible premium increase and how long you want to model it.'] },
+    { type: 'title', text: 'How to interpret the result', level: 2 },
+    { type: 'paragraph', html: '<p>The claim estimate combines the deductible with the total surcharge you entered. The self-pay estimate is the full damage cost. The break-even amount shows the loss size at which those two simplified routes meet. A recommendation is only a cost comparison: it does not establish coverage, claim eligibility or the insurer\'s actual premium decision.</p>' },
+    { type: 'comparative', columns: 2, items: [
+      { title: 'File a claim', description: 'Useful when the covered amount above the deductible outweighs the possible surcharge.', points: ['Pays the deductible in the model', 'Includes the entered premium effect', 'Shows the estimated insurer contribution'] },
+      { title: 'Pay yourself', description: 'Useful when the loss is close to or below the modelled break-even amount.', points: ['Avoids the modelled surcharge', 'Pays the full damage estimate', 'May avoid a claim process, subject to your policy'] },
+    ] },
+    { type: 'title', text: 'Limits and privacy', level: 2 },
+    { type: 'paragraph', html: '<p>This is not a claim decision engine. It does not read your policy, check whether the loss is covered, estimate depreciation or predict a premium. It assumes a simple covered loss where the insurer pays eligible costs above the deductible. All figures are processed in your browser, so you can test private scenarios without uploading them.</p>' },
+  ],
+  faq,
+  bibliography,
+  howTo,
+  schemas: [
+    { '@context': 'https://schema.org', '@type': 'FAQPage', mainEntity: faq.map((item) => ({ '@type': 'Question', name: item.question, acceptedAnswer: { '@type': 'Answer', text: item.answer } })) },
+    { '@context': 'https://schema.org', '@type': 'HowTo', name: title, step: howTo.map((step, index) => ({ '@type': 'HowToStep', position: index + 1, name: step.name, text: step.text })) },
+    { '@context': 'https://schema.org', '@type': 'SoftwareApplication', name: title, description, applicationCategory: 'FinanceApplication', operatingSystem: 'All', offers: { '@type': 'Offer', price: '0', priceCurrency: 'USD' } },
+  ],
+};

package/src/tool/insuranceDeductibleBreakEvenCalculator/i18n/es.ts

@@ -0,0 +1,2 @@
+import { createInsuranceDeductibleContent } from './content-factory';
+export const content = createInsuranceDeductibleContent('es');

package/src/tool/insuranceDeductibleBreakEvenCalculator/i18n/fr.ts

@@ -0,0 +1,2 @@
+import { createInsuranceDeductibleContent } from './content-factory';
+export const content = createInsuranceDeductibleContent('fr');

package/src/tool/insuranceDeductibleBreakEvenCalculator/i18n/id.ts

@@ -0,0 +1,2 @@
+import { createInsuranceDeductibleContent } from './content-factory';
+export const content = createInsuranceDeductibleContent('id');

package/src/tool/insuranceDeductibleBreakEvenCalculator/i18n/it.ts

@@ -0,0 +1,2 @@
+import { createInsuranceDeductibleContent } from './content-factory';
+export const content = createInsuranceDeductibleContent('it');

package/src/tool/insuranceDeductibleBreakEvenCalculator/i18n/ja.ts

@@ -0,0 +1,2 @@
+import { createInsuranceDeductibleContent } from './content-factory';
+export const content = createInsuranceDeductibleContent('ja');

package/src/tool/insuranceDeductibleBreakEvenCalculator/i18n/ko.ts

@@ -0,0 +1,2 @@
+import { createInsuranceDeductibleContent } from './content-factory';
+export const content = createInsuranceDeductibleContent('ko');

package/src/tool/insuranceDeductibleBreakEvenCalculator/i18n/nl.ts

@@ -0,0 +1,2 @@
+import { createInsuranceDeductibleContent } from './content-factory';
+export const content = createInsuranceDeductibleContent('nl');

package/src/tool/insuranceDeductibleBreakEvenCalculator/i18n/pl.ts

@@ -0,0 +1,2 @@
+import { createInsuranceDeductibleContent } from './content-factory';
+export const content = createInsuranceDeductibleContent('pl');

package/src/tool/insuranceDeductibleBreakEvenCalculator/i18n/pt.ts

@@ -0,0 +1,2 @@
+import { createInsuranceDeductibleContent } from './content-factory';
+export const content = createInsuranceDeductibleContent('pt');

package/src/tool/insuranceDeductibleBreakEvenCalculator/i18n/ru.ts

@@ -0,0 +1,2 @@
+import { createInsuranceDeductibleContent } from './content-factory';
+export const content = createInsuranceDeductibleContent('ru');

package/src/tool/insuranceDeductibleBreakEvenCalculator/i18n/sv.ts

@@ -0,0 +1,2 @@
+import { createInsuranceDeductibleContent } from './content-factory';
+export const content = createInsuranceDeductibleContent('sv');

package/src/tool/insuranceDeductibleBreakEvenCalculator/i18n/tr.ts

@@ -0,0 +1,2 @@
+import { createInsuranceDeductibleContent } from './content-factory';
+export const content = createInsuranceDeductibleContent('tr');

package/src/tool/insuranceDeductibleBreakEvenCalculator/i18n/zh.ts

@@ -0,0 +1,2 @@
+import { createInsuranceDeductibleContent } from './content-factory';
+export const content = createInsuranceDeductibleContent('zh');

package/src/tool/insuranceDeductibleBreakEvenCalculator/index.ts

@@ -0,0 +1,11 @@
+import type { ToolDefinition } from '../../types';
+import { insuranceDeductibleBreakEvenCalculator } from './entry';
+
+export * from './entry';
+
+export const INSURANCE_DEDUCTIBLE_BREAK_EVEN_CALCULATOR_TOOL: ToolDefinition = {
+  entry: insuranceDeductibleBreakEvenCalculator,
+  Component: () => import('./component.astro'),
+  SEOComponent: () => import('./seo.astro'),
+  BibliographyComponent: () => import('./bibliography.astro'),
+};

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);
+  });
+});