@jjlmoya/utils-motor 1.1.0

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

@@ -0,0 +1,38 @@
+import { createLocalizedContent } from './factory';
+
+export const content = createLocalizedContent({
+  locale: 'sv', slug: 'berakna-bromsstracka', title: 'Beräkna bromssträcka för bil och motorcykel',
+  description: 'Beräkna reaktionssträcka, bromssträcka och total stoppsträcka utifrån hastighet, reaktionstid, väggrepp och lutning.', faqTitle: 'Vanliga frågor', bibliographyTitle: 'Källor',
+  ui: {
+    unitLabel: 'Enheter', metricUnit: 'km/h', imperialUnit: 'mph', vehicleLabel: 'Fordon', carLabel: 'Bil', motorcycleLabel: 'Motorcykel', speedLabel: 'Starthastighet', reactionTimeLabel: 'Reaktionstid', gradeLabel: 'Vägens lutning',
+    roadConditionLabel: 'Väggrepp', dryRoadLabel: 'Torrt', wetRoadLabel: 'Vått', snowRoadLabel: 'Snö', iceRoadLabel: 'Is', decelerationLabel: 'Antagen retardation', reactionDistanceLabel: 'Reaktion', brakingDistanceLabel: 'Bromsning',
+    totalDistanceLabel: 'Total stoppsträcka', totalTimeLabel: 'Total stopptid', roadStartLabel: 'Faran upptäcks', brakePointLabel: 'Bromsning börjar', stopPointLabel: 'Helt stilla', safetyExperimentLabel: 'Test av säkerhetsavstånd',
+    safetyExperimentHint: 'Försiktigt scenario: trafiken framför blir ett fast hinder så snart du upptäcker den.', gapTimeLabel: 'Tidsavstånd', availableDistanceLabel: 'Tillgängligt utrymme', marginLabel: 'Säkerhetsmarginal', shortfallLabel: 'Saknad sträcka',
+    simulateLabel: 'Simulera stoppet', leadVehicleLabel: 'Fordon framför', enoughGapMessage: 'Det beräknade stoppet ryms och lämnar en viss marginal.', tightGapMessage: 'Stoppet ryms precis. Verkliga förhållanden kräver större marginal.',
+    insufficientGapMessage: 'Fordonet når trafiken framför innan det beräknade stoppet är klart.', advancedLabel: 'Avancerat bromsantagande', normalMessage: 'Den beräknade stoppsträckan är måttlig, men verkliga förhållanden kräver ändå säkerhetsmarginal.',
+    warningMessage: 'Vägsträckan som går åt är längre än den känns från förarplatsen.', criticalMessage: 'Mycket lågt grepp eller hög hastighet ger en extrem stoppsträcka.', carNote: 'Bilens beteende varierar med däck, bromsskick, last, ABS och vägyta.',
+    motorcycleNote: 'För motorcykeln påverkar även körteknik, bromsfördelning, lutning, däck och vägyta.', estimateNotice: 'Endast en pedagogisk uppskattning. Använd aldrig resultatet som garanterat säkerhetsavstånd eller ersättning för trafikregler.',
+  },
+  faq: [
+    { question: 'Vad är skillnaden mellan reaktionssträcka och bromssträcka?', answer: 'Reaktionssträckan är den sträcka som körs innan bromsningen börjar. Bromssträckan börjar när bromsarna verkar och slutar när fordonet står stilla. Tillsammans bildar de den totala stoppsträckan.' },
+    { question: 'Varför ökar stoppsträckan så snabbt med hastigheten?', answer: 'Reaktionssträckan ökar proportionellt med hastigheten, medan bromssträckan ökar ungefär med hastigheten i kvadrat. Under samma förhållanden kan en fördubblad hastighet göra bromsdelen cirka fyra gånger längre.' },
+    { question: 'Hur påverkar vägens lutning beräkningen?', answer: 'Uppför ökar den effektiva retardationen och nedför minskar den. Kalkylatorn behandlar lutningen som en gravitationskomponent enligt uppbyggnaden i FHWA:s modell för stoppsikt.' },
+    { question: 'Är resultatet ett garanterat säkerhetsavstånd?', answer: 'Nej. Däck, bromsar, uppmärksamhet, last, väder, föroreningar, ABS och mätfel kan ändra den verkliga sträckan. Följ trafikreglerna och lämna större marginal.' },
+  ],
+  howTo: [
+    { name: 'Välj enhet och fordon', text: 'Välj kilometer eller miles per timme och därefter bil eller motorcykel för rätt säkerhetsinformation.' },
+    { name: 'Ställ in hastighet och reaktionstid', text: 'Anpassa reglagen till scenariot du vill undersöka.' },
+    { name: 'Beskriv vägen', text: 'Välj grepp, finjustera retardationen vid behov och ange ett positivt värde uppför eller negativt nedför.' },
+    { name: 'Läs stoppförloppet', text: 'Jämför den blå reaktionsdelen med den gula bromsdelen och granska total sträcka och tid.' },
+    { name: 'Prova avståndet', text: 'Ange ett tidsavstånd och kör simuleringen för att se om fordonet stannar före trafiken framför i det försiktiga scenariot.' },
+  ],
+  seo: {
+    constructionTitle: 'Så byggs den totala stoppsträckan upp', constructionText: 'Ett fullständigt stopp har två faser. Under <strong>upptäckt och reaktion</strong> fortsätter fordonet nästan i starthastigheten. När bromsarna verkar måste krafter mellan däck och väg ta bort rörelseenergin. Kalkylatorn visar sträckorna separat så att reaktionstid inte förväxlas med bromsförmåga.',
+    partsValue: '2 faser', partsLabel: 'Reaktion plus bromsning', speedValue: 'Hastighet²', speedLabel: 'Bromssträckans ökning', localValue: '100 % lokalt', localLabel: 'Inga färddata skickas', formulaTitle: 'Formeln bakom uppskattningen',
+    formulaText: 'Reaktionssträckan är hastigheten i meter per sekund multiplicerad med reaktionstiden. Bromssträckan är hastigheten i kvadrat dividerad med två gånger den effektiva retardationen. Den kombinerar bromsantagandet med lutningens gravitationseffekt.',
+    tableHeaders: ['Indata', 'Vad som ändras', 'Varför det spelar roll'], tableRows: [['Hastighet', 'Båda faserna', 'Bromssträckan ökar ungefär med hastigheten i kvadrat'], ['Reaktionstid', 'Reaktionsfasen', 'Distraktion och trötthet lägger till meter före bromsning'], ['Retardation', 'Bromsfasen', 'Grepp, däck, bromsar och vägyta avgör inbromsningen'], ['Lutning', 'Bromsfasen', 'Tyngdkraften hjälper nedför och motverkar uppför']],
+    presetsTitle: 'Väglägen är scenarier, inte certifieringar', tipTitle: 'Välj den försiktiga sidan', tipText: 'Torrt, vått, snö och is är tydliga modellantaganden. De undersöker inte däck eller väg. Prova lägre retardation och längre reaktionstid när förhållandena är osäkra och följ officiella avståndsregler.',
+    experimentTitle: 'Experimentera med utrymmet framför', experimentText: 'Testet omvandlar tidsavståndet till meter vid vald hastighet och jämför det med total stoppsträcka. Animationen behandlar avsiktligt trafiken framför som ett fast hinder. Det är en försiktig illustration, inte en prognos för två fordon i rörelse.',
+    marginTitle: 'Bilar och motorcyklar behöver verklig marginal', marginText: 'Samma fysikmodell illustrerar båda fordonstyperna men återskapar inget enskilt fordon. Bromstemperatur, däckblandning, lastförskjutning, ABS-kalibrering, körteknik, smuts och väder kan ändra det verkliga utfallet avsevärt.',
+  },
+});

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

@@ -0,0 +1,38 @@
+import { createLocalizedContent } from './factory';
+
+export const content = createLocalizedContent({
+  locale: 'tr', slug: 'fren-mesafesi-hesaplama', title: 'Otomobil ve motosiklet fren mesafesi hesaplama',
+  description: 'Hız, tepki süresi, yol tutuşu ve eğime göre tepki, fren ve toplam durma mesafesini hesaplayın.', faqTitle: 'Sık sorulan sorular', bibliographyTitle: 'Kaynaklar',
+  ui: {
+    unitLabel: 'Birimler', metricUnit: 'km/sa', imperialUnit: 'mph', vehicleLabel: 'Araç', carLabel: 'Otomobil', motorcycleLabel: 'Motosiklet', speedLabel: 'Başlangıç hızı', reactionTimeLabel: 'Tepki süresi', gradeLabel: 'Yol eğimi',
+    roadConditionLabel: 'Yol tutuşu', dryRoadLabel: 'Kuru', wetRoadLabel: 'Islak', snowRoadLabel: 'Karlı', iceRoadLabel: 'Buzlu', decelerationLabel: 'Varsayılan yavaşlama', reactionDistanceLabel: 'Tepki', brakingDistanceLabel: 'Frenleme',
+    totalDistanceLabel: 'Toplam durma mesafesi', totalTimeLabel: 'Toplam durma süresi', roadStartLabel: 'Tehlike fark edildi', brakePointLabel: 'Fren uygulandı', stopPointLabel: 'Tam duruş', safetyExperimentLabel: 'Güvenli takip mesafesi deneyi',
+    safetyExperimentHint: 'Temkinli senaryo: öndeki trafik fark edildiği anda sabit bir engele dönüşür.', gapTimeLabel: 'Takip süresi', availableDistanceLabel: 'Öndeki boşluk', marginLabel: 'Güvenlik payı', shortfallLabel: 'Eksik mesafe',
+    simulateLabel: 'Durmayı canlandır', leadVehicleLabel: 'Öndeki araç', enoughGapMessage: 'Hesaplanan duruş mevcut alana sığıyor ve bir miktar pay bırakıyor.', tightGapMessage: 'Araç ancak durabiliyor. Gerçek koşullarda daha fazla pay gerekir.',
+    insufficientGapMessage: 'Araç, hesaplanan duruş tamamlanmadan öndeki trafiğe ulaşıyor.', advancedLabel: 'Gelişmiş fren varsayımı', normalMessage: 'Hesaplanan durma mesafesi sınırlı olsa da gerçek koşullar güvenlik payı gerektirir.',
+    warningMessage: 'Kullanılan yol, sürücü koltuğundan hissedilenden daha uzundur.', criticalMessage: 'Çok düşük yol tutuşu veya yüksek hız aşırı bir durma mesafesi oluşturur.', carNote: 'Otomobil davranışı lastiklere, fren durumuna, yüke, ABS\'ye ve yol yüzeyine göre değişir.',
+    motorcycleNote: 'Motosiklet frenlemesinde sürüş tekniği, fren dağılımı, yatış, lastikler ve zemin de etkilidir.', estimateNotice: 'Yalnızca eğitim amaçlı tahmindir. Sonucu garantili güvenli mesafe veya trafik kurallarının yerine kullanmayın.',
+  },
+  faq: [
+    { question: 'Tepki mesafesi ile fren mesafesi arasındaki fark nedir?', answer: 'Tepki mesafesi, frenleme başlamadan önce alınan yoldur. Fren mesafesi frenlerin etkisinden aracın durmasına kadar sürer. İkisinin toplamı, toplam durma mesafesidir.' },
+    { question: 'Durma mesafesi hızla neden bu kadar hızlı artar?', answer: 'Tepki mesafesi hızla doğru orantılı, fren mesafesi ise yaklaşık olarak hızın karesiyle artar. Aynı koşullarda hızı iki katına çıkarmak frenleme bölümünü yaklaşık dört katına çıkarabilir.' },
+    { question: 'Yol eğimi hesabı nasıl etkiler?', answer: 'Yokuş yukarı eğim etkili yavaşlamayı artırır, yokuş aşağı eğim azaltır. Hesaplayıcı eğimi, FHWA duruş görüş mesafesi modelinin yapısına uygun bir yer çekimi bileşeni olarak uygular.' },
+    { question: 'Sonuç garantili bir güvenli takip mesafesi midir?', answer: 'Hayır. Lastikler, frenler, dikkat, yük, hava, yüzey kirliliği, ABS ve ölçüm hataları gerçek mesafeyi değiştirebilir. Resmî kurallara uyun ve daha geniş pay bırakın.' },
+  ],
+  howTo: [
+    { name: 'Birimi ve aracı seçin', text: 'Saatte kilometre veya mili, ardından uygun güvenlik notu için otomobil ya da motosikleti seçin.' },
+    { name: 'Hızı ve tepki süresini ayarlayın', text: 'İncelemek istediğiniz senaryoya göre iki kaydırıcıyı ayarlayın.' },
+    { name: 'Yol koşullarını tanımlayın', text: 'Yol tutuşunu seçin, gerekirse yavaşlamayı düzenleyin; yokuş yukarı için pozitif, aşağı için negatif değer kullanın.' },
+    { name: 'Durma sürecini okuyun', text: 'Mavi tepki bölümüyle sarı fren bölümünü karşılaştırın ve toplam mesafe ile süreyi inceleyin.' },
+    { name: 'Takip mesafesini deneyin', text: 'Bir takip süresi belirleyip canlandırmayı çalıştırarak temkinli senaryoda aracın öndeki trafikten önce durup durmadığını görün.' },
+  ],
+  seo: {
+    constructionTitle: 'Toplam durma mesafesi nasıl oluşur?', constructionText: 'Tam duruş iki aşamadan oluşur. <strong>Algılama ve tepki</strong> sırasında araç başlangıç hızına yakın biçimde ilerlemeye devam eder. Frenler çalıştığında lastik ile yol arasındaki kuvvetler hareket enerjisini azaltır. Hesaplayıcı, tepki süresiyle fren performansının karıştırılmaması için iki mesafeyi ayrı gösterir.',
+    partsValue: '2 aşama', partsLabel: 'Tepki ve frenleme', speedValue: 'Hız²', speedLabel: 'Fren mesafesinin artışı', localValue: '%100 yerel', localLabel: 'Sürüş verisi gönderilmez', formulaTitle: 'Tahminin arkasındaki formül',
+    formulaText: 'Tepki mesafesi, saniyede metre cinsinden hız ile tepki süresinin çarpımıdır. Fren mesafesi, hızın karesinin etkili yavaşlamanın iki katına bölünmesiyle bulunur. Etkili yavaşlama, fren varsayımını eğimin yer çekimi etkisiyle birleştirir.',
+    tableHeaders: ['Girdi', 'Neyi değiştirir?', 'Neden önemlidir?'], tableRows: [['Hız', 'İki aşamayı da', 'Fren mesafesi yaklaşık olarak hızın karesiyle artar'], ['Tepki süresi', 'Tepki aşamasını', 'Dikkat dağınıklığı ve yorgunluk fren öncesi mesafeyi uzatır'], ['Yavaşlama', 'Fren aşamasını', 'Tutuş, lastikler, frenler ve zemin yavaşlamayı belirler'], ['Eğim', 'Fren aşamasını', 'Yer çekimi inişi destekler, çıkışa karşı koyar']],
+    presetsTitle: 'Yol seçenekleri senaryodur, sertifika değildir', tipTitle: 'Temkinli tarafı seçin', tipText: 'Kuru, ıslak, karlı ve buzlu seçenekleri açık model varsayımlarıdır; lastiğinizi veya yolu incelemez. Belirsizlikte daha düşük yavaşlama ve daha uzun tepki süresi deneyin, resmî kurallara uyun.',
+    experimentTitle: 'Öndeki boşlukla deney yapın', experimentText: 'Deney, seçilen takip süresini mevcut hızda metreye dönüştürüp toplam durma mesafesiyle karşılaştırır. Canlandırma öndeki trafiği bilerek sabit engel sayar. Bu, iki hareketli aracın tahmini değil, temkinli bir gösterimdir.',
+    marginTitle: 'Otomobil ve motosikletler gerçek pay ister', marginText: 'Aynı fizik modeli iki araç türünü gösterebilir ancak belirli bir aracı taklit etmez. Fren sıcaklığı, lastik hamuru, yük aktarımı, ABS ayarı, sürüş tekniği, zemin kirliliği ve hava gerçek sonucu önemli ölçüde değiştirebilir.',
+  },
+});

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

@@ -0,0 +1,38 @@
+import { createLocalizedContent } from './factory';
+
+export const content = createLocalizedContent({
+  locale: 'zh', slug: 'braking-distance-calculator', title: '汽车与摩托车刹车距离计算器',
+  description: '根据速度、反应时间、路面附着力和坡度，估算反应距离、制动距离与总停车距离。', faqTitle: '常见问题', bibliographyTitle: '参考资料',
+  ui: {
+    unitLabel: '单位', metricUnit: '公里/小时', imperialUnit: '英里/小时', vehicleLabel: '车辆', carLabel: '汽车', motorcycleLabel: '摩托车', speedLabel: '初始速度', reactionTimeLabel: '反应时间', gradeLabel: '道路坡度',
+    roadConditionLabel: '路面附着力', dryRoadLabel: '干燥', wetRoadLabel: '湿滑', snowRoadLabel: '积雪', iceRoadLabel: '结冰', decelerationLabel: '假定减速度', reactionDistanceLabel: '反应', brakingDistanceLabel: '制动',
+    totalDistanceLabel: '总停车距离', totalTimeLabel: '总停车时间', roadStartLabel: '发现危险', brakePointLabel: '开始制动', stopPointLabel: '完全停车', safetyExperimentLabel: '安全距离实验',
+    safetyExperimentHint: '保守场景：发现前方车辆的瞬间，将其视为固定障碍物。', gapTimeLabel: '跟车时间间隔', availableDistanceLabel: '前方空间', marginLabel: '安全余量', shortfallLabel: '不足距离',
+    simulateLabel: '运行停车模拟', leadVehicleLabel: '前方车辆', enoughGapMessage: '计算出的停车过程可在现有空间内完成，并留有一定余量。', tightGapMessage: '计算结果仅能勉强停住，实际驾驶需要更大余量。',
+    insufficientGapMessage: '车辆在完成计算出的停车过程之前就会到达前方车辆位置。', advancedLabel: '高级制动假设', normalMessage: '计算出的停车距离较短，但真实路况仍需要安全余量。',
+    warningMessage: '停车所需的道路长度比驾驶座上的感觉更长。', criticalMessage: '附着力极低或车速过高会产生极长的停车距离。', carNote: '汽车表现会随轮胎、制动器状态、载荷、ABS及路面质量而变化。',
+    motorcycleNote: '摩托车制动还受骑手技术、前后制动力分配、倾角、轮胎和路面状况影响。', estimateNotice: '仅供学习参考。请勿将结果视为有保证的安全距离，也不能用它替代交通法规。',
+  },
+  faq: [
+    { question: '反应距离和制动距离有什么区别？', answer: '反应距离是发现危险后、制动开始前车辆驶过的距离。制动距离从制动器开始发挥作用算起，到车辆停止为止。两者相加就是总停车距离。' },
+    { question: '为什么停车距离会随速度快速增加？', answer: '反应距离与速度成正比，而制动距离大致与速度的平方成正比。在其他条件相同时，速度加倍可能使制动部分增至约四倍。' },
+    { question: '道路坡度如何影响计算结果？', answer: '上坡会提高有效减速度，下坡则会降低它。计算器依照FHWA停车视距模型的结构，将坡度作为重力分量计入。' },
+    { question: '计算结果能作为有保证的安全跟车距离吗？', answer: '不能。轮胎、制动器、注意力、载荷、天气、路面污染、ABS和测量误差都会改变实际距离。请遵守当地交通法规，并预留更大余量。' },
+  ],
+  howTo: [
+    { name: '选择单位和车辆', text: '选择公里/小时或英里/小时，再选择汽车或摩托车，以显示相应的安全提示。' },
+    { name: '设置速度和反应时间', text: '按照想要研究的场景调整初始速度和感知反应时间。' },
+    { name: '设置道路条件', text: '选择路面附着力，必要时微调减速度；上坡使用正值，下坡使用负值。' },
+    { name: '查看停车过程', text: '比较蓝色反应区段与黄色制动区段，然后查看总距离和总时间。' },
+    { name: '尝试不同跟车距离', text: '设置跟车时间间隔并运行模拟，查看在保守场景下车辆能否在前车位置之前停下。' },
+  ],
+  seo: {
+    constructionTitle: '总停车距离由哪些部分组成', constructionText: '完整停车包含两个阶段。在<strong>感知和反应</strong>期间，车辆仍以接近初始速度继续前进。制动器工作后，轮胎与路面之间的力开始消耗动能。计算器将两段距离分开显示，避免把反应延迟误认为制动性能。',
+    partsValue: '2个阶段', partsLabel: '反应加制动', speedValue: '速度²', speedLabel: '制动距离的增长', localValue: '100%本地', localLabel: '不会上传行程数据', formulaTitle: '估算所采用的公式',
+    formulaText: '反应距离等于以米/秒表示的速度乘以反应时间。制动距离等于速度平方除以两倍有效减速度。有效减速度结合了所选制动假设和道路坡度产生的重力影响。',
+    tableHeaders: ['输入项', '影响部分', '为什么重要'], tableRows: [['速度', '两个阶段', '制动距离大致随速度平方增长'], ['反应时间', '反应阶段', '分心和疲劳会增加制动前的行驶距离'], ['减速度', '制动阶段', '附着力、轮胎、制动器和路面决定减速能力'], ['坡度', '制动阶段', '重力在下坡时推动前进，在上坡时阻碍前进']],
+    presetsTitle: '路面选项是场景假设，并非性能认证', tipTitle: '优先采用保守条件', tipText: '干燥、湿滑、积雪和结冰是透明的模型假设，不会检测您的轮胎或道路。条件不确定时，请尝试较低减速度和较长反应时间，并遵守当地法规。',
+    experimentTitle: '尝试不同的前方空间', experimentText: '安全距离实验会按当前速度把所选时间间隔换算成米，并与总停车距离比较。动画有意把前方车辆当作固定障碍物。这是偏向安全的示意，不是对两辆运动车辆的预测。',
+    marginTitle: '汽车和摩托车都需要现实余量', marginText: '同一物理模型可以说明两类车辆，但无法复现某一辆具体车辆。制动器温度、轮胎配方、载荷转移、ABS标定、驾驶技术、路面污染和天气都可能让实际结果明显偏离理想计算。',
+  },
+});

package/src/tool/brakingDistanceCalculator/index.ts

@@ -0,0 +1,10 @@
+import { brakingDistanceCalculator } from './entry';
+
+export * from './entry';
+
+export const BRAKING_DISTANCE_CALCULATOR_TOOL = {
+  entry: brakingDistanceCalculator,
+  Component: () => import('./component.astro'),
+  SEOComponent: () => import('./seo.astro'),
+  BibliographyComponent: () => import('./bibliography.astro'),
+};

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

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest';
+import {
+  calculateBrakingDistance,
+  calculateEffectiveDeceleration,
+  calculateSafetyDistanceScenario,
+  speedToMetersPerSecond,
+} from './logic';
+
+describe('braking distance calculator logic', () => {
+  it('converts metric and imperial speeds', () => {
+    expect(speedToMetersPerSecond(36, 'kmh')).toBeCloseTo(10, 6);
+    expect(speedToMetersPerSecond(60, 'mph')).toBeCloseTo(26.8224, 6);
+  });
+
+  it('separates reaction and braking distance', () => {
+    const result = calculateBrakingDistance({
+      speed: 80,
+      unit: 'kmh',
+      reactionTime: 2.5,
+      deceleration: 3.4,
+      gradePercent: 0,
+    });
+
+    expect(result.reactionDistance).toBeCloseTo(55.56, 2);
+    expect(result.brakingDistance).toBeCloseTo(72.62, 2);
+    expect(result.totalDistance).toBeCloseTo(128.18, 2);
+  });
+
+  it('increases stopping distance downhill', () => {
+    const base = {
+      speed: 70,
+      unit: 'kmh' as const,
+      reactionTime: 2.5,
+      deceleration: 3.4,
+    };
+    const uphill = calculateBrakingDistance({ ...base, gradePercent: 6 });
+    const downhill = calculateBrakingDistance({ ...base, gradePercent: -6 });
+
+    expect(downhill.brakingDistance).toBeGreaterThan(uphill.brakingDistance);
+  });
+
+  it('keeps the denominator positive for extreme inputs', () => {
+    expect(calculateEffectiveDeceleration(0.2, -20)).toBe(0.1);
+  });
+
+  it('handles invalid and negative values without NaN', () => {
+    const result = calculateBrakingDistance({
+      speed: Number.NaN,
+      unit: 'kmh',
+      reactionTime: -2,
+      deceleration: -1,
+      gradePercent: 0,
+    });
+
+    expect(result.totalDistance).toBe(0);
+    expect(Number.isFinite(result.totalTime)).toBe(true);
+  });
+
+  it('turns a time gap into distance and exposes the stopping margin', () => {
+    const result = calculateBrakingDistance({
+      speed: 90,
+      unit: 'kmh',
+      reactionTime: 1,
+      deceleration: 5,
+      gradePercent: 0,
+    });
+    const scenario = calculateSafetyDistanceScenario(result, 3);
+
+    expect(scenario.gapDistance).toBeCloseTo(75, 6);
+    expect(scenario.marginDistance).toBeCloseTo(75 - result.totalDistance, 6);
+  });
+
+  it('clamps an invalid time gap instead of returning NaN', () => {
+    const result = calculateBrakingDistance({
+      speed: 50,
+      unit: 'kmh',
+      reactionTime: 1,
+      deceleration: 4,
+      gradePercent: 0,
+    });
+
+    expect(calculateSafetyDistanceScenario(result, Number.NaN).gapDistance).toBe(0);
+  });
+});

package/src/tool/brakingDistanceCalculator/logic.ts

@@ -0,0 +1,82 @@
+export type SpeedUnit = 'kmh' | 'mph';
+export type VehicleType = 'car' | 'motorcycle';
+
+export interface BrakingInput {
+  speed: number;
+  unit: SpeedUnit;
+  reactionTime: number;
+  deceleration: number;
+  gradePercent: number;
+}
+
+export interface BrakingResult {
+  speedMps: number;
+  reactionDistance: number;
+  brakingDistance: number;
+  totalDistance: number;
+  brakingTime: number;
+  totalTime: number;
+  effectiveDeceleration: number;
+}
+
+export interface SafetyDistanceScenario {
+  gapSeconds: number;
+  gapDistance: number;
+  marginDistance: number;
+}
+
+export const GRAVITY = 9.80665;
+export const MPH_TO_MPS = 0.44704;
+
+function nonNegative(value: number): number {
+  return Number.isFinite(value) ? Math.max(0, value) : 0;
+}
+
+export function speedToMetersPerSecond(speed: number, unit: SpeedUnit): number {
+  const safeSpeed = nonNegative(speed);
+  return unit === 'mph' ? safeSpeed * MPH_TO_MPS : safeSpeed / 3.6;
+}
+
+export function calculateEffectiveDeceleration(
+  deceleration: number,
+  gradePercent: number,
+): number {
+  const gradeEffect = GRAVITY * (gradePercent / 100);
+  return Math.max(0.1, nonNegative(deceleration) + gradeEffect);
+}
+
+export function calculateBrakingDistance(input: BrakingInput): BrakingResult {
+  const speedMps = speedToMetersPerSecond(input.speed, input.unit);
+  const reactionTime = nonNegative(input.reactionTime);
+  const effectiveDeceleration = calculateEffectiveDeceleration(
+    input.deceleration,
+    input.gradePercent,
+  );
+  const reactionDistance = speedMps * reactionTime;
+  const brakingDistance = (speedMps ** 2) / (2 * effectiveDeceleration);
+  const brakingTime = speedMps / effectiveDeceleration;
+
+  return {
+    speedMps,
+    reactionDistance,
+    brakingDistance,
+    totalDistance: reactionDistance + brakingDistance,
+    brakingTime,
+    totalTime: reactionTime + brakingTime,
+    effectiveDeceleration,
+  };
+}
+
+export function calculateSafetyDistanceScenario(
+  result: BrakingResult,
+  gapSeconds: number,
+): SafetyDistanceScenario {
+  const safeGapSeconds = nonNegative(gapSeconds);
+  const gapDistance = result.speedMps * safeGapSeconds;
+
+  return {
+    gapSeconds: safeGapSeconds,
+    gapDistance,
+    marginDistance: gapDistance - result.totalDistance,
+  };
+}

package/src/tool/brakingDistanceCalculator/seo.astro

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

package/src/tool/brakingDistanceCalculator/storage.ts

@@ -0,0 +1,28 @@
+import type { SpeedUnit, VehicleType } from './logic';
+
+export interface BrakingState {
+  speed: number;
+  unit: SpeedUnit;
+  reactionTime: number;
+  deceleration: number;
+  gradePercent: number;
+  gapSeconds: number;
+  vehicle: VehicleType;
+}
+
+const STORAGE_KEY = 'braking-distance-calculator-state';
+
+export function loadBrakingState(): BrakingState | null {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    return raw ? JSON.parse(raw) as BrakingState : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveBrakingState(state: BrakingState): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+  } catch {}
+}

package/src/tool/brakingDistanceCalculator/ui.ts

@@ -0,0 +1,42 @@
+export interface BrakingDistanceCalculatorUI extends Record<string, string> {
+  unitLabel: string;
+  metricUnit: string;
+  imperialUnit: string;
+  vehicleLabel: string;
+  carLabel: string;
+  motorcycleLabel: string;
+  speedLabel: string;
+  reactionTimeLabel: string;
+  gradeLabel: string;
+  roadConditionLabel: string;
+  dryRoadLabel: string;
+  wetRoadLabel: string;
+  snowRoadLabel: string;
+  iceRoadLabel: string;
+  decelerationLabel: string;
+  reactionDistanceLabel: string;
+  brakingDistanceLabel: string;
+  totalDistanceLabel: string;
+  totalTimeLabel: string;
+  roadStartLabel: string;
+  brakePointLabel: string;
+  stopPointLabel: string;
+  safetyExperimentLabel: string;
+  safetyExperimentHint: string;
+  gapTimeLabel: string;
+  availableDistanceLabel: string;
+  marginLabel: string;
+  shortfallLabel: string;
+  simulateLabel: string;
+  leadVehicleLabel: string;
+  enoughGapMessage: string;
+  tightGapMessage: string;
+  insufficientGapMessage: string;
+  advancedLabel: string;
+  normalMessage: string;
+  warningMessage: string;
+  criticalMessage: string;
+  carNote: string;
+  motorcycleNote: string;
+  estimateNotice: string;
+}

package/src/tools.ts

@@ -0,0 +1,4 @@
+export { ALL_ENTRIES } from './entries';
+import { BRAKING_DISTANCE_CALCULATOR_TOOL } from './tool/brakingDistanceCalculator';
+
+export const ALL_TOOLS = [BRAKING_DISTANCE_CALCULATOR_TOOL];

package/src/types.ts

@@ -0,0 +1,72 @@
+import type { SEOSection } from '@jjlmoya/utils-shared';
+import type { WithContext, Thing } from 'schema-dts';
+
+export type { SEOSection };
+
+export type KnownLocale =
+  | 'ar' | 'da' | 'de' | 'en' | 'es' | 'fi'
+  | 'fr' | 'id' | 'it' | 'ja' | 'ko' | 'nb' | 'nl'
+  | 'pl' | 'pt' | 'ru' | 'sv' | 'tr' | 'zh';
+
+export interface FAQItem {
+  question: string;
+  answer: string;
+}
+
+export interface BibliographyEntry {
+  name: string;
+  url: string;
+}
+
+export interface HowToStep {
+  name: string;
+  text: string;
+}
+
+export interface ToolLocaleContent<TUI extends Record<string, string> = Record<string, string>> {
+  slug: string;
+  title: string;
+  description: string;
+  ui: TUI;
+  seo: SEOSection[];
+  faqTitle?: string;
+  faq: FAQItem[];
+  bibliographyTitle?: string;
+  bibliography: BibliographyEntry[];
+  howTo: HowToStep[];
+  schemas: WithContext<Thing>[];
+}
+
+export interface CategoryLocaleContent {
+  slug: string;
+  title: string;
+  description: string;
+  seo: SEOSection[];
+}
+
+export type LocaleLoader<T> = () => Promise<T>;
+
+export type LocaleMap<T> = Partial<Record<KnownLocale, LocaleLoader<T>>>;
+
+export interface MotorToolEntry<TUI extends Record<string, string> = Record<string, string>> {
+  id: string;
+  icons: {
+    bg: string;
+    fg: string;
+  };
+  i18n: LocaleMap<ToolLocaleContent<TUI>>;
+}
+
+export interface MotorCategoryEntry {
+  icon: string;
+  tools: MotorToolEntry<Record<string, string>>[];
+  i18n: LocaleMap<CategoryLocaleContent>;
+}
+
+export interface ToolDefinition {
+  entry: MotorToolEntry<Record<string, string>>;
+  Component: unknown;
+  SEOComponent: unknown;
+  BibliographyComponent: unknown;
+}
+