@jjlmoya/utils-motor 1.12.0 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jjlmoya/utils-motor",
-    "version": "1.12.0",
+    "version": "1.14.0",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",

package/src/category/index.ts

@@ -6,10 +6,11 @@ import { realFuelConsumptionCalculator } from '../tool/realFuelConsumptionCalcul
 import { tirePressureConverter } from '../tool/tirePressureConverter/entry';
 import { evChargingTimeCostPlanner } from '../tool/evChargingTimeCostPlanner/entry';
 import { trailerTongueWeightCalculator } from '../tool/trailerTongueWeightCalculator/entry';
+import { vehicleTotalCostPerKilometreCalculator } from '../tool/vehicleTotalCostPerKilometreCalculator/entry';
 
 export const motorCategory: MotorCategoryEntry = {
   icon: 'mdi:car-cog',
-  tools: [brakingDistanceCalculator, realFuelConsumptionCalculator, carMotorcycleGearRatioCalculator, tirePressureConverter, motorcycleSkidMarkSpeedEstimator, evChargingTimeCostPlanner, trailerTongueWeightCalculator] as unknown as MotorToolEntry<Record<string, string>>[],
+  tools: [brakingDistanceCalculator, realFuelConsumptionCalculator, carMotorcycleGearRatioCalculator, tirePressureConverter, motorcycleSkidMarkSpeedEstimator, evChargingTimeCostPlanner, trailerTongueWeightCalculator, vehicleTotalCostPerKilometreCalculator] as unknown as MotorToolEntry<Record<string, string>>[],
   i18n: {
     es: () => import('./i18n/es').then((module) => module.content),
     en: () => import('./i18n/en').then((module) => module.content),

package/src/entries.ts

@@ -10,6 +10,8 @@ export { tirePressureConverter } from './tool/tirePressureConverter/entry';
 export type { TirePressureConverterLocaleContent } from './tool/tirePressureConverter/entry';
 export { trailerTongueWeightCalculator } from './tool/trailerTongueWeightCalculator/entry';
 export type { TrailerTongueWeightCalculatorLocaleContent } from './tool/trailerTongueWeightCalculator/entry';
+export { vehicleTotalCostPerKilometreCalculator } from './tool/vehicleTotalCostPerKilometreCalculator/entry';
+export type { VehicleTotalCostPerKilometreCalculatorLocaleContent } from './tool/vehicleTotalCostPerKilometreCalculator/entry';
 export { motorCategory } from './category';
 
 import { brakingDistanceCalculator } from './tool/brakingDistanceCalculator/entry';
@@ -19,5 +21,6 @@ import { realFuelConsumptionCalculator } from './tool/realFuelConsumptionCalcula
 import { tirePressureConverter } from './tool/tirePressureConverter/entry';
 import { evChargingTimeCostPlanner } from './tool/evChargingTimeCostPlanner/entry';
 import { trailerTongueWeightCalculator } from './tool/trailerTongueWeightCalculator/entry';
+import { vehicleTotalCostPerKilometreCalculator } from './tool/vehicleTotalCostPerKilometreCalculator/entry';
 
-export const ALL_ENTRIES = [brakingDistanceCalculator, realFuelConsumptionCalculator, carMotorcycleGearRatioCalculator, tirePressureConverter, motorcycleSkidMarkSpeedEstimator, evChargingTimeCostPlanner, trailerTongueWeightCalculator];
+export const ALL_ENTRIES = [brakingDistanceCalculator, realFuelConsumptionCalculator, carMotorcycleGearRatioCalculator, tirePressureConverter, motorcycleSkidMarkSpeedEstimator, evChargingTimeCostPlanner, trailerTongueWeightCalculator, vehicleTotalCostPerKilometreCalculator];

package/src/tests/locale_completeness.test.ts

@@ -4,7 +4,7 @@ import type { ToolLocaleContent } from '../types';
 
 describe('Locale Completeness and Slug Validation', () => {
   it('all tools registered in ALL_TOOLS', () => {
-    expect(ALL_TOOLS.length).toBe(7);
+    expect(ALL_TOOLS.length).toBe(8);
   });
 
   ALL_TOOLS.forEach((tool) => {

package/src/tests/mfe_assets_contract.test.ts

@@ -0,0 +1,53 @@
+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 = categoryImageMatch[1];
+const categoryImage = categoryImageMatch[2];
+const assetVersion = categoryImageMatch[3];
+if (!imageUrlRoot || !categoryImage || !assetVersion) {
+  throw new Error(`Unexpected CATEGORY_OG_IMAGE capture groups: ${CATEGORY_OG_IMAGE}`);
+}
+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/registry_contract.test.ts

@@ -64,4 +64,27 @@ describe('Library registry contract', () => {
 
     expect(failures).toEqual([]);
   });
+
+  it('keeps the vehicle cost calculator consumer boundary localized and lazy', async () => {
+    const tool = ALL_TOOLS.find((candidate) => candidate.entry.id === 'vehicle-total-cost-per-kilometre-calculator');
+    expect(tool).toBeDefined();
+    if (!tool) return;
+
+    expect(Object.keys(tool.entry.i18n).sort()).toEqual([
+      'de', 'en', 'es', 'fr', 'id', 'it', 'ja', 'ko', 'nl', 'pl', 'pt', 'ru', 'sv', 'tr', 'zh',
+    ]);
+
+    const localizedContent = await tool.entry.i18n.de?.();
+    expect(localizedContent?.title).toContain('Fahrzeug');
+    expect(localizedContent?.ui.currencyLabel).toBeTruthy();
+
+    const [component, seo, bibliography] = await Promise.all([
+      tool.Component(),
+      tool.SEOComponent(),
+      tool.BibliographyComponent(),
+    ]);
+    expect(component).toBeTruthy();
+    expect(seo).toBeTruthy();
+    expect(bibliography).toBeTruthy();
+  });
 });

package/src/tests/tool_validation.test.ts

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

package/src/tool/vehicleTotalCostPerKilometreCalculator/bibliography.astro

@@ -0,0 +1,6 @@
+---
+import { Bibliography as SharedBibliography } from '@jjlmoya/utils-shared';
+import { bibliographyEntries } from './bibliography';
+---
+
+<SharedBibliography links={bibliographyEntries} />

package/src/tool/vehicleTotalCostPerKilometreCalculator/bibliography.ts

@@ -0,0 +1,12 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliographyEntries: BibliographyEntry[] = [
+  {
+    name: 'ADAC, Übersicht: Autokosten von A bis Z',
+    url: 'https://www.adac.de/rund-ums-fahrzeug/auto-kaufen-verkaufen/autokosten/uebersicht/',
+  },
+  {
+    name: 'RAC Drive, Car running costs: a complete guide',
+    url: 'https://www.rac.co.uk/drive/advice/driving-advice/car-running-costs-a-complete-guide-to-help-you-save-money/',
+  },
+];

package/src/tool/vehicleTotalCostPerKilometreCalculator/component.astro

@@ -0,0 +1,97 @@
+---
+import './vehicle-total-cost-per-kilometre-calculator.css';
+import { CURRENCY_OPTIONS, DEFAULT_CURRENCY } from './logic';
+import type { VehicleTotalCostPerKilometreCalculatorUI } from './ui';
+
+interface Props {
+  ui: VehicleTotalCostPerKilometreCalculatorUI;
+  locale?: string;
+}
+
+const { ui, locale = 'en' } = Astro.props as Props;
+const initialCurrency = DEFAULT_CURRENCY;
+const currencyNames = (() => {
+  try {
+    return new Intl.DisplayNames([locale], { type: 'currency' });
+  } catch {
+    return null;
+  }
+})();
+const currencyName = (code: string, fallback: string): string => currencyNames?.of(code) ?? fallback;
+const defaults = {
+  primary: { annualKm: 15000, fuelUsePer100Km: 6.4, fuelPrice: 1.75, insurance: 700, maintenance: 650, tax: 190, depreciation: 2600 },
+  secondary: { annualKm: 15000, fuelUsePer100Km: 7.2, fuelPrice: 1.75, insurance: 760, maintenance: 700, tax: 210, depreciation: 2300 },
+  comparisonEnabled: false,
+  currency: initialCurrency,
+};
+const config = JSON.stringify({ ui, defaults, locale });
+---
+
+<div class="vehicle-cost-tool" data-vehicle-total-cost>
+  <script is:inline type="application/json" data-vehicle-cost-config set:html={config}></script>
+  <form class="vehicle-cost-surface" data-cost-form>
+    <div class="vehicle-cost-controls">
+      <div class="vehicle-cost-toolbar">
+        <div class="vehicle-cost-presets" aria-label={ui.presetLabel}>
+          <span class="vehicle-cost-toolbar-label">{ui.presetLabel}</span>
+          <button type="button" data-preset="city">{ui.presetCity}</button>
+          <button type="button" data-preset="balanced">{ui.presetBalanced}</button>
+          <button type="button" data-preset="distance">{ui.presetLongDistance}</button>
+        </div>
+        <label class="vehicle-cost-currency-picker">
+          <span class="vehicle-cost-toolbar-label">{ui.currencyLabel}</span>
+          <select data-currency-select aria-label={ui.currencyLabel}>
+            {CURRENCY_OPTIONS.map((option) => <option value={option.code} selected={option.code === initialCurrency}>{option.code} - {currencyName(option.code, option.name)} ({option.symbol})</option>)}
+          </select>
+        </label>
+      </div>
+
+      <section class="vehicle-cost-scenario" aria-labelledby="vehicle-cost-primary-label">
+        <div class="vehicle-cost-section-heading">
+          <h2 id="vehicle-cost-primary-label">{ui.primaryScenarioLabel}</h2>
+          <button type="button" class="vehicle-cost-compare-button" data-action="comparison" aria-pressed="false">{ui.compareOffLabel}</button>
+        </div>
+        <div class="vehicle-cost-fields">
+          <label class="vehicle-cost-field vehicle-cost-field-wide"><span>{ui.distanceLabel}</span><small>{ui.distanceHint}</small><div class="vehicle-cost-input-wrap"><input data-cost-input data-scenario="primary" data-field="annualKm" type="number" min="1" step="100" inputmode="decimal" /><b>{ui.inputUnitDistance}</b></div></label>
+          <label class="vehicle-cost-field"><span>{ui.fuelUseLabel}</span><small>{ui.fuelUseHint}</small><div class="vehicle-cost-input-wrap"><input data-cost-input data-scenario="primary" data-field="fuelUsePer100Km" type="number" min="0" step="0.1" inputmode="decimal" /><b>{ui.inputUnitFuelUse}</b></div></label>
+          <label class="vehicle-cost-field"><span>{ui.fuelPriceLabel}</span><small>{ui.fuelPriceHint}</small><div class="vehicle-cost-input-wrap"><input data-cost-input data-scenario="primary" data-field="fuelPrice" type="number" min="0" step="0.01" inputmode="decimal" /><b data-currency-unit="price">{ui.inputUnitFuelPrice}</b></div></label>
+          <label class="vehicle-cost-field"><span>{ui.insuranceLabel}</span><small>{ui.insuranceHint}</small><div class="vehicle-cost-input-wrap"><input data-cost-input data-scenario="primary" data-field="insurance" type="number" min="0" step="10" inputmode="decimal" /><b data-currency-unit="annual">{ui.inputUnitAnnualCost}</b></div></label>
+          <label class="vehicle-cost-field"><span>{ui.maintenanceLabel}</span><small>{ui.maintenanceHint}</small><div class="vehicle-cost-input-wrap"><input data-cost-input data-scenario="primary" data-field="maintenance" type="number" min="0" step="10" inputmode="decimal" /><b data-currency-unit="annual">{ui.inputUnitAnnualCost}</b></div></label>
+          <label class="vehicle-cost-field"><span>{ui.taxLabel}</span><small>{ui.taxHint}</small><div class="vehicle-cost-input-wrap"><input data-cost-input data-scenario="primary" data-field="tax" type="number" min="0" step="10" inputmode="decimal" /><b data-currency-unit="annual">{ui.inputUnitAnnualCost}</b></div></label>
+          <label class="vehicle-cost-field"><span>{ui.depreciationLabel}</span><small>{ui.depreciationHint}</small><div class="vehicle-cost-input-wrap"><input data-cost-input data-scenario="primary" data-field="depreciation" type="number" min="0" step="50" inputmode="decimal" /><b data-currency-unit="annual">{ui.inputUnitAnnualCost}</b></div></label>
+        </div>
+      </section>
+
+      <section class="vehicle-cost-scenario vehicle-cost-comparison-panel" data-comparison-panel hidden aria-labelledby="vehicle-cost-comparison-label">
+        <div class="vehicle-cost-section-heading"><h2 id="vehicle-cost-comparison-label">{ui.comparisonScenarioLabel}</h2><button type="button" class="vehicle-cost-compare-button" data-action="comparison">{ui.removeComparisonLabel}</button></div>
+        <div class="vehicle-cost-fields">
+          <label class="vehicle-cost-field vehicle-cost-field-wide"><span>{ui.distanceLabel}</span><small>{ui.distanceHint}</small><div class="vehicle-cost-input-wrap"><input data-cost-input data-scenario="secondary" data-field="annualKm" type="number" min="1" step="100" inputmode="decimal" /><b>{ui.inputUnitDistance}</b></div></label>
+          <label class="vehicle-cost-field"><span>{ui.fuelUseLabel}</span><small>{ui.fuelUseHint}</small><div class="vehicle-cost-input-wrap"><input data-cost-input data-scenario="secondary" data-field="fuelUsePer100Km" type="number" min="0" step="0.1" inputmode="decimal" /><b>{ui.inputUnitFuelUse}</b></div></label>
+          <label class="vehicle-cost-field"><span>{ui.fuelPriceLabel}</span><small>{ui.fuelPriceHint}</small><div class="vehicle-cost-input-wrap"><input data-cost-input data-scenario="secondary" data-field="fuelPrice" type="number" min="0" step="0.01" inputmode="decimal" /><b data-currency-unit="price">{ui.inputUnitFuelPrice}</b></div></label>
+          <label class="vehicle-cost-field"><span>{ui.insuranceLabel}</span><small>{ui.insuranceHint}</small><div class="vehicle-cost-input-wrap"><input data-cost-input data-scenario="secondary" data-field="insurance" type="number" min="0" step="10" inputmode="decimal" /><b data-currency-unit="annual">{ui.inputUnitAnnualCost}</b></div></label>
+          <label class="vehicle-cost-field"><span>{ui.maintenanceLabel}</span><small>{ui.maintenanceHint}</small><div class="vehicle-cost-input-wrap"><input data-cost-input data-scenario="secondary" data-field="maintenance" type="number" min="0" step="10" inputmode="decimal" /><b data-currency-unit="annual">{ui.inputUnitAnnualCost}</b></div></label>
+          <label class="vehicle-cost-field"><span>{ui.taxLabel}</span><small>{ui.taxHint}</small><div class="vehicle-cost-input-wrap"><input data-cost-input data-scenario="secondary" data-field="tax" type="number" min="0" step="10" inputmode="decimal" /><b data-currency-unit="annual">{ui.inputUnitAnnualCost}</b></div></label>
+          <label class="vehicle-cost-field"><span>{ui.depreciationLabel}</span><small>{ui.depreciationHint}</small><div class="vehicle-cost-input-wrap"><input data-cost-input data-scenario="secondary" data-field="depreciation" type="number" min="0" step="50" inputmode="decimal" /><b data-currency-unit="annual">{ui.inputUnitAnnualCost}</b></div></label>
+        </div>
+      </section>
+    </div>
+
+    <section class="vehicle-cost-result" aria-labelledby="vehicle-cost-result-label">
+      <div class="vehicle-cost-result-heading"><span>{ui.resultLabel}</span><h2 id="vehicle-cost-result-label">{ui.resultTitle}</h2><button type="button" class="vehicle-cost-reset" data-action="reset">{ui.resetLabel}</button></div>
+      <p class="vehicle-cost-error" data-result-error hidden></p>
+      <div data-result-body>
+        <div class="vehicle-cost-scene" data-cost-scene role="img" aria-label={ui.resultSceneLabel}></div>
+        <div class="vehicle-cost-metrics">
+          <div class="vehicle-cost-primary-metric"><span>{ui.costPerKmLabel}</span><strong data-cost-per-km></strong><b>{ui.outputUnitDistance}</b><em data-status></em></div>
+          <div class="vehicle-cost-secondary-metrics"><div><span>{ui.monthlyCostLabel}</span><strong data-monthly-cost></strong></div><div><span>{ui.annualCostLabel}</span><strong data-annual-cost></strong></div><div><span>{ui.fuelCostLabel}</span><strong data-fuel-cost></strong><small data-fuel-litres></small></div><div><span>{ui.fixedCostLabel}</span><strong data-fixed-cost></strong></div></div>
+        </div>
+        <p class="vehicle-cost-comparison-summary" data-comparison-summary hidden></p>
+      </div>
+    </section>
+  </form>
+</div>
+
+<script>
+  import { createVehicleTotalCostController } from './controller';
+  document.querySelectorAll<HTMLElement>('[data-vehicle-total-cost]').forEach((root) => createVehicleTotalCostController(root));
+</script>

package/src/tool/vehicleTotalCostPerKilometreCalculator/controller.ts

@@ -0,0 +1,198 @@
+import { calculateVehicleCost, compareVehicleCosts, convertVehicleCostInput, getCurrencyOption, isCurrencyCode, type CurrencyCode, type VehicleCostInput } from './logic';
+import { renderCostScene, formatMoney, formatNumber } from './dom-views';
+import { evaluateVehicleCost } from './evaluator';
+import { loadVehicleCostState, saveVehicleCostState, type VehicleCostStorageState } from './storage';
+import type { VehicleTotalCostPerKilometreCalculatorUI } from './ui';
+
+interface ControllerConfig {
+  ui: VehicleTotalCostPerKilometreCalculatorUI;
+  defaults: VehicleCostStorageState;
+  locale: string;
+}
+
+interface RenderContext {
+  currency: CurrencyCode;
+  locale: string;
+  ui: VehicleTotalCostPerKilometreCalculatorUI;
+}
+
+interface ControllerRuntime {
+  root: HTMLElement;
+  config: ControllerConfig;
+  currencySelect: HTMLSelectElement | null;
+  state: VehicleCostStorageState;
+  render: () => void;
+}
+
+const storageKey = 'jjlmoya:vehicle-total-cost-per-kilometre-calculator';
+
+function readScenario(root: HTMLElement, prefix: string): VehicleCostInput {
+  const read = (field: string): number => Number(root.querySelector<HTMLInputElement>(`[data-scenario="${prefix}"][data-field="${field}"]`)?.value ?? 0);
+  return { annualKm: read('annualKm'), fuelUsePer100Km: read('fuelUsePer100Km'), fuelPrice: read('fuelPrice'), insurance: read('insurance'), maintenance: read('maintenance'), tax: read('tax'), depreciation: read('depreciation') };
+}
+
+function writeScenario(root: HTMLElement, prefix: string, input: VehicleCostInput): void {
+  Object.entries(input).forEach(([field, value]) => {
+    const element = root.querySelector<HTMLInputElement>(`[data-scenario="${prefix}"][data-field="${field}"]`);
+    if (element) element.value = String(value);
+  });
+}
+
+function setText(root: HTMLElement, selector: string, text: string): void {
+  const element = root.querySelector<HTMLElement>(selector);
+  if (element) element.textContent = text;
+}
+
+function updateComparisonVisibility(root: HTMLElement, enabled: boolean, ui: VehicleTotalCostPerKilometreCalculatorUI): void {
+  const panel = root.querySelector<HTMLElement>('[data-comparison-panel]');
+  const toggle = root.querySelector<HTMLButtonElement>('[data-action="comparison"]');
+  if (panel) panel.hidden = !enabled;
+  if (toggle) {
+    toggle.setAttribute('aria-pressed', String(enabled));
+    toggle.textContent = enabled ? ui.compareOnLabel : ui.compareOffLabel;
+  }
+}
+
+function renderPrimaryMetrics(root: HTMLElement, primary: ReturnType<typeof calculateVehicleCost>, context: RenderContext): void {
+  if (!primary) return;
+  const evaluation = evaluateVehicleCost(primary);
+  const status = root.querySelector<HTMLElement>('[data-status]');
+  if (status) { status.textContent = context.ui[evaluation.labelKey]; status.dataset.profile = evaluation.profile; }
+  setText(root, '[data-cost-per-km]', formatMoney(primary.costPerKm, context.currency, context.locale));
+  setText(root, '[data-monthly-cost]', formatMoney(primary.monthlyCost, context.currency, context.locale));
+  setText(root, '[data-annual-cost]', formatMoney(primary.annualCost, context.currency, context.locale));
+  setText(root, '[data-fuel-cost]', formatMoney(primary.annualFuelCost, context.currency, context.locale));
+  setText(root, '[data-fixed-cost]', formatMoney(primary.fixedCost, context.currency, context.locale));
+  setText(root, '[data-fuel-litres]', `${formatNumber(primary.annualFuelLitres, context.locale)} L`);
+}
+
+function renderComparisonSummary(root: HTMLElement, comparison: ReturnType<typeof compareVehicleCosts>, context: RenderContext): void {
+  const comparisonText = root.querySelector<HTMLElement>('[data-comparison-summary]');
+  if (!comparisonText) return;
+  comparisonText.hidden = !comparison;
+  if (!comparison) return;
+  let template = context.ui.comparisonSame;
+  if (comparison.cheaper === 'primary') template = context.ui.comparisonPrimaryCheaper;
+  if (comparison.cheaper === 'secondary') template = context.ui.comparisonSecondaryCheaper;
+  comparisonText.textContent = `${context.ui.comparisonTitle}: ${template} ${formatMoney(Math.abs(comparison.differencePerKm), context.currency, context.locale)} / ${context.ui.outputUnitDistance}.`;
+}
+
+function renderCurrencyUnits(root: HTMLElement, currency: CurrencyCode, ui: VehicleTotalCostPerKilometreCalculatorUI): void {
+  const symbol = getCurrencyOption(currency).symbol;
+  root.querySelectorAll<HTMLElement>('[data-currency-unit="price"]').forEach((element) => { element.textContent = `${symbol} ${ui.inputUnitFuelPrice}`; });
+  root.querySelectorAll<HTMLElement>('[data-currency-unit="annual"]').forEach((element) => { element.textContent = `${symbol} ${ui.inputUnitAnnualCost}`; });
+}
+
+function renderInvalidResult(root: HTMLElement, message: string): void {
+  const error = root.querySelector<HTMLElement>('[data-result-error]');
+  const body = root.querySelector<HTMLElement>('[data-result-body]');
+  if (error) { error.hidden = false; error.textContent = message; }
+  if (body) body.hidden = true;
+}
+
+function renderValidResult(root: HTMLElement): void {
+  const error = root.querySelector<HTMLElement>('[data-result-error]');
+  const body = root.querySelector<HTMLElement>('[data-result-body]');
+  if (error) error.hidden = true;
+  if (body) body.hidden = false;
+}
+
+function renderResult(root: HTMLElement, state: VehicleCostStorageState, config: ControllerConfig): void {
+  const { ui, locale } = config;
+  const primary = calculateVehicleCost(state.primary);
+  const secondary = state.comparisonEnabled ? calculateVehicleCost(state.secondary) : null;
+  if (!primary || (state.comparisonEnabled && !secondary)) {
+    renderInvalidResult(root, ui.validationError);
+    return;
+  }
+  renderValidResult(root);
+  const context = { currency: state.currency, locale, ui };
+  renderPrimaryMetrics(root, primary, context);
+  renderCostScene({ container: root.querySelector<HTMLElement>('[data-cost-scene]') as HTMLElement, primary, secondary, ...context });
+  const comparison = secondary ? compareVehicleCosts(state.primary, state.secondary) : null;
+  renderComparisonSummary(root, comparison, context);
+}
+
+function makeState(root: HTMLElement, previous: VehicleCostStorageState): VehicleCostStorageState {
+  return { ...previous, primary: readScenario(root, 'primary'), secondary: readScenario(root, 'secondary') };
+}
+
+function getPresetInput(preset: string): VehicleCostInput | null {
+  if (preset === 'city') return { annualKm: 10000, fuelUsePer100Km: 8.2, fuelPrice: 1.75, insurance: 620, maintenance: 520, tax: 160, depreciation: 1800 };
+  if (preset === 'balanced') return { annualKm: 15000, fuelUsePer100Km: 6.4, fuelPrice: 1.75, insurance: 700, maintenance: 650, tax: 190, depreciation: 2600 };
+  if (preset === 'distance') return { annualKm: 24000, fuelUsePer100Km: 5.4, fuelPrice: 1.72, insurance: 780, maintenance: 850, tax: 220, depreciation: 3200 };
+  return null;
+}
+
+function bindCurrencyEvent(runtime: ControllerRuntime): void {
+  const { root, config, currencySelect } = runtime;
+  currencySelect?.addEventListener('change', () => {
+    const nextCurrency = currencySelect.value;
+    if (!isCurrencyCode(nextCurrency)) return;
+    runtime.state.primary = convertVehicleCostInput(runtime.state.primary, runtime.state.currency, nextCurrency);
+    runtime.state.secondary = convertVehicleCostInput(runtime.state.secondary, runtime.state.currency, nextCurrency);
+    runtime.state.currency = nextCurrency;
+    writeScenario(root, 'primary', runtime.state.primary);
+    writeScenario(root, 'secondary', runtime.state.secondary);
+    renderCurrencyUnits(root, runtime.state.currency, config.ui);
+    runtime.render();
+  });
+}
+
+function bindPresetEvents(runtime: ControllerRuntime): void {
+  const { root } = runtime;
+  root.querySelectorAll<HTMLButtonElement>('[data-preset]').forEach((button) => button.addEventListener('click', () => {
+    const preset = getPresetInput(button.dataset.preset ?? '');
+    if (!preset) return;
+    runtime.state.primary = convertVehicleCostInput(preset, 'EUR', runtime.state.currency);
+    writeScenario(root, 'primary', runtime.state.primary);
+    runtime.render();
+  }));
+}
+
+function bindScenarioEvents(runtime: ControllerRuntime): void {
+  const { root, config, currencySelect } = runtime;
+  root.querySelector<HTMLButtonElement>('[data-action="comparison"]')?.addEventListener('click', () => {
+    runtime.state.comparisonEnabled = !runtime.state.comparisonEnabled;
+    updateComparisonVisibility(root, runtime.state.comparisonEnabled, config.ui);
+    runtime.render();
+  });
+  root.querySelector<HTMLButtonElement>('[data-action="reset"]')?.addEventListener('click', () => {
+    runtime.state = { ...config.defaults, primary: { ...config.defaults.primary }, secondary: { ...config.defaults.secondary } };
+    writeScenario(root, 'primary', runtime.state.primary);
+    writeScenario(root, 'secondary', runtime.state.secondary);
+    if (currencySelect) currencySelect.value = runtime.state.currency;
+    renderCurrencyUnits(root, runtime.state.currency, config.ui);
+    updateComparisonVisibility(root, runtime.state.comparisonEnabled, config.ui);
+    runtime.render();
+  });
+}
+
+function bindControllerEvents(runtime: ControllerRuntime): void {
+  runtime.root.querySelectorAll<HTMLInputElement>('[data-cost-input]').forEach((input) => input.addEventListener('input', runtime.render));
+  bindCurrencyEvent(runtime);
+  bindPresetEvents(runtime);
+  bindScenarioEvents(runtime);
+}
+
+export function createVehicleTotalCostController(root: HTMLElement): void {
+  const script = root.querySelector<HTMLScriptElement>('[data-vehicle-cost-config]');
+  if (!script) return;
+  const config = JSON.parse(script.textContent ?? '{}') as ControllerConfig;
+  const currencySelect = root.querySelector<HTMLSelectElement>('[data-currency-select]');
+  const runtime: ControllerRuntime = {
+    root, config, currencySelect, state: loadVehicleCostState(storageKey, config.defaults), render: () => {},
+  };
+  writeScenario(root, 'primary', runtime.state.primary);
+  writeScenario(root, 'secondary', runtime.state.secondary);
+  updateComparisonVisibility(root, runtime.state.comparisonEnabled, config.ui);
+  if (currencySelect) currencySelect.value = runtime.state.currency;
+  renderCurrencyUnits(root, runtime.state.currency, config.ui);
+  runtime.render = (): void => {
+    runtime.state = makeState(root, runtime.state);
+    saveVehicleCostState(storageKey, runtime.state);
+    renderResult(root, runtime.state, config);
+  };
+  bindControllerEvents(runtime);
+  runtime.render();
+}

package/src/tool/vehicleTotalCostPerKilometreCalculator/dom-views.ts

@@ -0,0 +1,47 @@
+import type { VehicleCostResult } from './logic';
+import type { CurrencyCode } from './logic';
+import type { VehicleTotalCostPerKilometreCalculatorUI } from './ui';
+
+export function formatMoney(value: number, currency: CurrencyCode, locale = 'en'): string {
+  return new Intl.NumberFormat(locale, {
+    style: 'currency', currency, currencyDisplay: 'symbol', maximumFractionDigits: 2,
+  }).format(value);
+}
+
+export function formatNumber(value: number, locale = 'en'): string {
+  return new Intl.NumberFormat(locale, { maximumFractionDigits: 2 }).format(value);
+}
+
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>'"]/g, (character) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', "'": '&#39;', '"': '&quot;' }[character] ?? character));
+}
+
+interface SceneRow {
+  result: VehicleCostResult;
+  label: string;
+  currency: CurrencyCode;
+  locale: string;
+  ui: VehicleTotalCostPerKilometreCalculatorUI;
+  y: number;
+}
+
+function rowMarkup({ result, label, currency, locale, ui, y }: SceneRow): string {
+  const fixedWidth = Math.max(26, result.fixedShare * 210);
+  const fuelWidth = Math.max(26, result.runningShare * 210);
+  return `<g transform="translate(0 ${y})"><text x="0" y="0" class="route-label">${escapeHtml(label)}</text><rect x="0" y="18" width="240" height="12" rx="6" class="route-base"/><rect x="0" y="18" width="${fixedWidth}" height="12" rx="6" class="route-fixed"/><rect x="${Math.max(0, fixedWidth - 4)}" y="18" width="${fuelWidth}" height="12" rx="6" class="route-fuel"/><circle cx="${Math.min(236, fixedWidth + fuelWidth)}" cy="24" r="7" class="route-end"/><text x="0" y="55" class="route-meta">${escapeHtml(ui.fixedLaneLabel)} ${escapeHtml(formatMoney(result.fixedCost, currency, locale))}</text><text x="240" y="55" text-anchor="end" class="route-meta">${escapeHtml(ui.fuelLaneLabel)} ${escapeHtml(formatMoney(result.annualFuelCost, currency, locale))}</text><text x="0" y="80" class="route-total">${escapeHtml(ui.totalLaneLabel)} ${escapeHtml(formatMoney(result.costPerKm, currency, locale))} / ${escapeHtml(ui.outputUnitDistance)}</text></g>`;
+}
+
+interface SceneConfig {
+  container: HTMLElement;
+  primary: VehicleCostResult;
+  secondary: VehicleCostResult | null;
+  currency: CurrencyCode;
+  locale: string;
+  ui: VehicleTotalCostPerKilometreCalculatorUI;
+}
+
+export function renderCostScene({ container, primary, secondary, currency, locale, ui }: SceneConfig): void {
+  const height = secondary ? 250 : 150;
+  const rows = rowMarkup({ result: primary, label: ui.primaryScenarioLabel, currency, locale, ui, y: 18 }) + (secondary ? rowMarkup({ result: secondary, label: ui.comparisonScenarioLabel, currency, locale, ui, y: 132 }) : '');
+  container.innerHTML = `<svg viewBox="0 0 280 ${height}" role="img" aria-label="${escapeHtml(ui.resultSceneLabel)}"><path d="M0 106 C72 78 136 136 210 102 S260 76 280 88" class="route-path" fill="none"/><path d="M0 220 C72 192 136 250 210 216 S260 190 280 202" class="route-path route-path-secondary" fill="none"/>${rows}</svg>`;
+}

package/src/tool/vehicleTotalCostPerKilometreCalculator/entry.ts

@@ -0,0 +1,30 @@
+import type { MotorToolEntry, ToolLocaleContent } from '../../types';
+import type { VehicleTotalCostPerKilometreCalculatorUI } from './ui';
+
+export type { VehicleTotalCostPerKilometreCalculatorUI };
+export type VehicleTotalCostPerKilometreCalculatorLocaleContent = ToolLocaleContent<VehicleTotalCostPerKilometreCalculatorUI>;
+
+export const vehicleTotalCostPerKilometreCalculator: MotorToolEntry<VehicleTotalCostPerKilometreCalculatorUI> = {
+  id: 'vehicle-total-cost-per-kilometre-calculator',
+  icons: {
+    bg: 'mdi:road-variant',
+    fg: 'mdi:cash-multiple',
+  },
+  i18n: {
+    de: () => import('./i18n/de').then((module) => module.content),
+    en: () => import('./i18n/en').then((module) => module.content),
+    es: () => import('./i18n/es').then((module) => module.content),
+    fr: () => import('./i18n/fr').then((module) => module.content),
+    id: () => import('./i18n/id').then((module) => module.content),
+    it: () => import('./i18n/it').then((module) => module.content),
+    ja: () => import('./i18n/ja').then((module) => module.content),
+    ko: () => import('./i18n/ko').then((module) => module.content),
+    nl: () => import('./i18n/nl').then((module) => module.content),
+    pl: () => import('./i18n/pl').then((module) => module.content),
+    pt: () => import('./i18n/pt').then((module) => module.content),
+    ru: () => import('./i18n/ru').then((module) => module.content),
+    sv: () => import('./i18n/sv').then((module) => module.content),
+    tr: () => import('./i18n/tr').then((module) => module.content),
+    zh: () => import('./i18n/zh').then((module) => module.content),
+  },
+};

package/src/tool/vehicleTotalCostPerKilometreCalculator/evaluator.ts

@@ -0,0 +1,14 @@
+import type { VehicleCostResult } from './logic';
+
+export type CostProfile = 'balanced' | 'fixed-heavy' | 'running-heavy';
+
+export interface CostEvaluation {
+  profile: CostProfile;
+  labelKey: 'statusBalanced' | 'statusFixedHeavy' | 'statusRunningHeavy';
+}
+
+export function evaluateVehicleCost(result: VehicleCostResult): CostEvaluation {
+  if (result.fixedShare >= 0.65) return { profile: 'fixed-heavy', labelKey: 'statusFixedHeavy' };
+  if (result.runningShare >= 0.65) return { profile: 'running-heavy', labelKey: 'statusRunningHeavy' };
+  return { profile: 'balanced', labelKey: 'statusBalanced' };
+}

package/src/tool/vehicleTotalCostPerKilometreCalculator/i18n/de.ts

@@ -0,0 +1,30 @@
+import type { FAQItem, HowToStep } from '../../../types';
+import { createVehicleCostContent, createVehicleCostSeo } from './factory';
+import type { VehicleTotalCostPerKilometreCalculatorUI } from '../ui';
+
+const ui: VehicleTotalCostPerKilometreCalculatorUI = {
+  presetLabel: 'Mit einem realistischen Muster beginnen', presetCity: 'Überwiegend Stadt', presetBalanced: 'Gemischte Strecke', presetLongDistance: 'Lange Strecke', resetLabel: 'Werte zurücksetzen',
+  primaryScenarioLabel: 'Dein Fahrzeug', comparisonScenarioLabel: 'Zweites Szenario', distanceLabel: 'Kilometer pro Jahr', distanceHint: 'Gib die erwartete Jahresfahrleistung ein', fuelUseLabel: 'Verbrauch', fuelUseHint: 'Durchschnitt deines Fahrzeugs in Litern pro 100 km', fuelPriceLabel: 'Kraftstoffpreis', fuelPriceHint: 'Preis pro Liter', insuranceLabel: 'Versicherung pro Jahr', insuranceHint: 'Deine tatsächliche Jahresprämie', maintenanceLabel: 'Wartung pro Jahr', maintenanceHint: 'Service, Reparaturen, Reifen und Prüfungen', taxLabel: 'Steuern und Gebühren pro Jahr', taxHint: 'Kfz-Steuer, Zulassung und regelmäßige Gebühren', depreciationLabel: 'Wertverlust pro Jahr', depreciationHint: 'Geschätzter Wertverlust während eines Jahres', currencyLabel: 'Währung', compareLabel: 'Szenario vergleichen', compareOnLabel: 'Vergleich aktiv', compareOffLabel: 'Vergleich hinzufügen', removeComparisonLabel: 'Vergleich ausblenden', resultLabel: 'Die Kostenstrecke', resultTitle: 'Was jeder Kilometer wirklich kostet', resultSceneLabel: 'Eine Strecke zeigt feste Fahrzeugkosten und Kraftstoffkosten bis zum Kilometerpreis', costPerKmLabel: 'Kosten pro Kilometer', monthlyCostLabel: 'Monatlicher Durchschnitt', annualCostLabel: 'Gesamtes Jahr', fuelCostLabel: 'Kraftstoff pro Jahr', fixedCostLabel: 'Feste und laufende Kosten', statusBalanced: 'Die Kosten verteilen sich gleichmäßig', statusFixedHeavy: 'Die Besitzkosten tragen den größten Anteil', statusRunningHeavy: 'Der Kraftstoff trägt den größten Anteil', validationError: 'Gib eine positive Jahresfahrleistung und keine negativen Kosten ein.', comparisonTitle: 'Szenarienvergleich', comparisonPrimaryCheaper: 'Dein Fahrzeug ist günstiger um', comparisonSecondaryCheaper: 'Das zweite Szenario ist günstiger um', comparisonSame: 'Beide Szenarien kosten ungefähr gleich viel', fixedLaneLabel: 'Fix', fuelLaneLabel: 'Kraftstoff', totalLaneLabel: 'Gesamt', formulaLabel: 'Berechnung', formulaText: 'Jahreskosten = Jahreskilometer × Verbrauch ÷ 100 × Kraftstoffpreis + Versicherung + Wartung + Steuern + Wertverlust. Kosten pro Kilometer = Jahreskosten ÷ Jahreskilometer.', inputUnitDistance: 'km', inputUnitFuelUse: 'L / 100 km', inputUnitFuelPrice: '/ L', inputUnitAnnualCost: '/ Jahr', outputUnitDistance: 'km',
+};
+
+const faq: FAQItem[] = [
+  { question: 'Welche Kosten berücksichtigt der Rechner?', answer: 'Er verbindet Kraftstoff mit Versicherung, Wartung, Steuern und Gebühren sowie dem geschätzten jährlichen Wertverlust. Du gibst deine eigenen Zahlen ein, damit das Ergebnis zu deinem Fahrzeug und deiner Nutzung passt.' },
+  { question: 'Warum ist das Ergebnis höher als beim Kraftstoffrechner?', answer: 'Kraftstoff ist nur der variable Teil. Versicherung, Reparaturen, Gebühren und Wertverlust können einen niedrigen Verbrauch trotzdem teuer pro Kilometer machen.' },
+  { question: 'Wie schätze ich den Wertverlust?', answer: 'Ziehe den erwarteten Jahresendwert vom Anfangswert ab. Wenn der Wiederverkaufswert unsicher ist, rechne mit einem niedrigen und einem hohen Szenario.' },
+  { question: 'Kann ich zwei Fahrzeuge vergleichen?', answer: 'Ja. Aktiviere den Vergleich und verwende für beide Szenarien denselben Zeitraum, dieselbe Entfernung und dieselbe Währung.' },
+  { question: 'Ist das Ergebnis eine exakte Prognose?', answer: 'Nein. Es ist eine transparente Planungshilfe. Kraftstoffpreise, Reparaturen, Fahrleistung und Wiederverkaufswert können sich ändern.' },
+];
+
+const howTo: HowToStep[] = [
+  { name: 'Jahresstrecke festlegen', text: 'Gib ein, wie viele Kilometer du voraussichtlich pro Jahr fährst.' },
+  { name: 'Kraftstoff ergänzen', text: 'Trage den Verbrauch und den tatsächlichen Preis pro Liter ein.' },
+  { name: 'Besitzkosten ergänzen', text: 'Füge Versicherung, Wartung, Gebühren und jährlichen Wertverlust hinzu.' },
+  { name: 'Ergebnis vergleichen', text: 'Nutze die Kosten pro Kilometer und prüfe zusätzlich die festen und variablen Anteile.' },
+];
+
+export const content = createVehicleCostContent({
+  locale: 'de', slug: 'fahrzeug-gesamtkosten-pro-kilometer-rechner', title: 'Rechner für die Gesamtkosten eines Fahrzeugs pro Kilometer', description: 'Berechne die echten Fahrzeugkosten pro Kilometer mit Kraftstoff, Besitzkosten und Jahresfahrleistung.', faqTitle: 'Häufige Fragen', bibliographyTitle: 'Bibliografische Quellen', ui, faq, howTo,
+  seo: createVehicleCostSeo({
+    introTitle: 'Die Kosten hinter jedem Kilometer sichtbar machen', introA: 'Ein Kraftstoffpreis allein zeigt nicht, was ein Fahrzeug wirklich kostet. Versicherung, Wartung, Reifen, Steuern und der Wertverlust gehören ebenfalls zur Entscheidung. Dieser Rechner verteilt die jährlichen Kosten auf deine erwartete Fahrleistung und stellt sie dem Kraftstoffverbrauch gegenüber.', introB: 'Trage deine eigenen Werte ein, statt dich auf einen allgemeinen Durchschnitt zu verlassen. Das wichtigste Ergebnis sind die Kosten pro Kilometer, ergänzt um Monatswert, Jahreswert und die visuelle Aufteilung zwischen Besitz und Betrieb.', costsTitle: 'Welche Kosten gehören in die Schätzung', costsText: 'Kraftstoff verändert sich mit der Entfernung. Versicherung, Wartung, Gebühren und Wertverlust werden als jährliche Beträge eingegeben. Bei geringer Fahrleistung wiegen feste Kosten pro Kilometer stärker.', costsHeaders: ['Eingabe', 'Verwendung im Rechner', 'Worauf achten'], costsRows: [['Jahresfahrleistung', 'Verteilt die Gesamtkosten auf Kilometer', 'Nutze eine realistische Entfernung'], ['Verbrauch und Preis', 'Erzeugen die variablen Kraftstoffkosten', 'Verwende dieselbe Grundlage in beiden Szenarien'], ['Versicherung, Wartung und Gebühren', 'Addieren wiederkehrende Jahreskosten', 'Vergiss Reifen und Prüfungen nicht'], ['Wertverlust', 'Fügt eine jährliche Abschreibung hinzu', 'Teste mehrere Wiederverkaufswerte']], readTitle: 'Die Kostenstrecke lesen', readText: 'Der feste Abschnitt zeigt Kosten, die nicht direkt mit jedem Kilometer steigen. Der Kraftstoffabschnitt zeigt den entfernungsabhängigen Anteil. Der Endpunkt ist der vollständige Kilometerpreis und eignet sich zum Vergleich.', list: ['Rechne bei unsicherem Wiederverkaufswert mit einer niedrigen und hohen Annahme.', 'Vergleiche Fahrzeuge mit derselben Jahresfahrleistung und Währung.', 'Ersetze Schätzungen nach einigen Monaten durch deine echten Belege.', 'Prüfe Monats- und Jahreswert gegen dein Budget.'], decisionTitle: 'Vergleiche Annahmen statt nur Fahrzeuge', decisionText: 'Ein Vergleich ist nur sinnvoll, wenn beide Szenarien denselben Besitzzeitraum und dieselben Regeln verwenden. Ändere jeweils nur eine Annahme, wenn du einen Kauf oder eine regelmäßige Strecke untersuchst.', tipTitle: 'Das ist ein Planungsmodell, kein Angebot', tipText: 'Der Rechner ruft keine Marktpreise ab, bewertet keine rechtlichen Erstattungen und kennt den zukünftigen Wiederverkaufswert nicht. Er macht deine eigenen Annahmen transparent.'
+  }),
+});