@jjlmoya/utils-nautical 1.2.0

package/src/tool/endurance/component.astro

@@ -0,0 +1,310 @@
+---
+import './style.css';
+import type { EnduranceUI } from './index';
+
+interface Props {
+  ui: EnduranceUI;
+}
+
+const { ui } = Astro.props;
+---
+
+<section id="endurance-calculator" class="endurance-calculator" data-ui={JSON.stringify(ui)}>
+  <div class="ec-main-container">
+    <aside class="ec-sidebar-inputs">
+      <div class="ec-compact-group">
+        <label>{ui.tankCapacityLabel}</label>
+        <div class="ec-dual-row">
+          <div>
+            <span class="ec-sub-label">{ui.mainTankLabel}</span>
+            <div class="ec-field-wrapper">
+              <span class="ec-field-icon icon-fuel"></span>
+              <input type="number" id="tank1" class="ec-compact-input" value="200" min="0" step="10" />
+              <span class="ec-unit-tag">L</span>
+            </div>
+          </div>
+          <div>
+            <span class="ec-sub-label">{ui.auxTankLabel}</span>
+            <div class="ec-field-wrapper">
+              <span class="ec-field-icon icon-fuel"></span>
+              <input type="number" id="tank2" class="ec-compact-input" value="0" min="0" step="10" />
+              <span class="ec-unit-tag">L</span>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <div class="ec-compact-group">
+        <label>{ui.currentFuelLabel}</label>
+        <div class="ec-field-wrapper">
+          <span class="ec-field-icon icon-bucket"></span>
+          <input type="number" id="f-current" class="ec-compact-input" value="150" min="0" step="5" />
+          <span class="ec-unit-tag">L</span>
+        </div>
+      </div>
+
+      <div class="ec-compact-group">
+        <label>{ui.seaConditionsLabel}</label>
+        <div class="ec-field-wrapper">
+          <span class="ec-field-icon icon-wave"></span>
+          <select id="sea-s" class="ec-compact-select">
+            <option value="1.0">{ui.seaCalm}</option>
+            <option value="1.15">{ui.seaLight}</option>
+            <option value="1.30">{ui.seaModerate}</option>
+            <option value="1.60">{ui.seaStorm}</option>
+          </select>
+        </div>
+      </div>
+
+      <div class="ec-compact-group">
+        <label>{ui.consumptionLabel}</label>
+        <div class="ec-field-wrapper">
+          <span class="ec-field-icon icon-fire"></span>
+          <input type="number" id="f-cons" class="ec-compact-input" value="25" min="0.1" step="1" />
+          <span class="ec-unit-tag">L/h</span>
+        </div>
+      </div>
+
+      <div class="ec-compact-group">
+        <label>{ui.cruiseSpeedLabel}</label>
+        <div class="ec-field-wrapper">
+          <span class="ec-field-icon icon-wind"></span>
+          <input type="number" id="v-cruiser" class="ec-compact-input" value="8" min="0.1" step="0.5" />
+          <span class="ec-unit-tag">kn</span>
+        </div>
+      </div>
+
+      <div class="ec-compact-group">
+        <label>{ui.reserveLabel}</label>
+        <div class="ec-field-wrapper">
+          <span class="ec-field-icon icon-shield"></span>
+          <input type="number" id="f-res" class="ec-compact-input" value="20" min="0" max="50" step="5" />
+          <span class="ec-unit-tag">%</span>
+        </div>
+      </div>
+
+      <div class="ec-compact-group">
+        <label>{ui.fuelPriceLabel}</label>
+        <div class="ec-field-wrapper">
+          <span class="ec-field-icon">€</span>
+          <input type="number" id="f-price" class="ec-compact-input" value="1.8" min="0" step="0.05" />
+          <span class="ec-unit-tag">€/L</span>
+        </div>
+      </div>
+    </aside>
+
+    <div class="ec-dashboard-panel">
+      <div class="ec-hero-display">
+        <div class="ec-hero-top">
+          <div>
+            <div class="ec-display-title">{ui.maxRangeLabel}</div>
+            <div class="ec-main-value-row">
+              <span class="ec-main-value" id="out-dist">--</span>
+              <span class="ec-main-unit">MN</span>
+            </div>
+          </div>
+          <div class="ec-fuel-badge" id="out-fuel-pct">--%</div>
+        </div>
+        <div class="ec-progress-track">
+          <div class="ec-progress-fill" id="progress-fill"></div>
+          <div class="ec-marker" id="reserve-marker" style="left: 80%"></div>
+        </div>
+      </div>
+
+      <div class="ec-stats-grid">
+        <div class="ec-stat-card">
+          <span class="ec-stat-label">{ui.realPerformanceLabel}</span>
+          <span class="ec-stat-value" id="out-perf">--</span>
+          <span class="ec-stat-label">L/MN</span>
+        </div>
+        <div class="ec-stat-card">
+          <span class="ec-stat-label">{ui.hoursLabel}</span>
+          <span class="ec-stat-value" id="out-hours">--</span>
+          <span class="ec-stat-label">h</span>
+        </div>
+        <div class="ec-stat-card">
+          <span class="ec-stat-label">{ui.safeMilesLabel}</span>
+          <span class="ec-stat-value danger" id="out-safe">--</span>
+          <span class="ec-stat-label">MN</span>
+        </div>
+        <div class="ec-stat-card hidden" id="card-cost">
+          <span class="ec-stat-label">{ui.tankValueLabel}</span>
+          <span class="ec-stat-value" id="out-cost">--</span>
+          <span class="ec-stat-label">€</span>
+        </div>
+      </div>
+
+      <div class="ec-inverter-card">
+        <div class="ec-inverter-header">{ui.inverseCalcLabel}</div>
+        <div class="ec-inverter-row">
+          <div>
+            <div class="ec-inverter-label">{ui.desiredDistLabel}</div>
+            <div class="ec-field-wrapper">
+              <input type="number" id="inv-dist" class="ec-compact-input" value="50" min="0" step="5" />
+              <span class="ec-unit-tag">MN</span>
+            </div>
+          </div>
+          <div>
+            <div class="ec-inverter-label">{ui.minFuelLabel}</div>
+            <div class="ec-inverter-value" id="inv-res">-- <span class="ec-inverter-unit">L</span></div>
+          </div>
+        </div>
+      </div>
+
+      <div class="ec-warning-bar">
+        <span class="ec-warning-icon">!</span>
+        <span>{ui.warningLabel}</span>
+      </div>
+    </div>
+  </div>
+</section>
+
+<script>
+  const section = document.getElementById('endurance-calculator') as HTMLElement;
+  JSON.parse(section.dataset.ui as string);
+
+  const SEA_FACTORS = [1.0, 1.15, 1.30, 1.60];
+
+  class EnduranceCalculator {
+    private t1: HTMLInputElement;
+    private t2: HTMLInputElement;
+    private fCur: HTMLInputElement;
+    private seaSel: HTMLSelectElement;
+    private fCons: HTMLInputElement;
+    private vCruise: HTMLInputElement;
+    private fRes: HTMLInputElement;
+    private fPrice: HTMLInputElement;
+    private invDist: HTMLInputElement;
+
+    constructor() {
+      this.t1 = document.getElementById('tank1') as HTMLInputElement;
+      this.t2 = document.getElementById('tank2') as HTMLInputElement;
+      this.fCur = document.getElementById('f-current') as HTMLInputElement;
+      this.seaSel = document.getElementById('sea-s') as HTMLSelectElement;
+      this.fCons = document.getElementById('f-cons') as HTMLInputElement;
+      this.vCruise = document.getElementById('v-cruiser') as HTMLInputElement;
+      this.fRes = document.getElementById('f-res') as HTMLInputElement;
+      this.fPrice = document.getElementById('f-price') as HTMLInputElement;
+      this.invDist = document.getElementById('inv-dist') as HTMLInputElement;
+      this.init();
+    }
+
+    private init() {
+      const inputs = [this.t1, this.t2, this.fCur, this.fCons, this.vCruise, this.fRes, this.fPrice];
+      inputs.forEach((el) => el.addEventListener('input', () => { this.calculate(); this.save(); }));
+      this.seaSel.addEventListener('change', () => { this.calculate(); this.save(); });
+      this.invDist.addEventListener('input', () => { this.updateInverse(); this.save(); });
+      this.load();
+    }
+
+    private save() {
+      localStorage.setItem('jjlmoya-nautical-endurance', JSON.stringify({
+        t1: this.t1.value, t2: this.t2.value, fuel: this.fCur.value,
+        cons: this.fCons.value, speed: this.vCruise.value,
+        state: this.seaSel.value, res: this.fRes.value,
+        price: this.fPrice.value, inv: this.invDist.value,
+      }));
+    }
+
+    private restoreInputs(d: Record<string, string>) {
+      if (d.t1) this.t1.value = d.t1;
+      if (d.t2) this.t2.value = d.t2;
+      if (d.fuel) this.fCur.value = d.fuel;
+      if (d.cons) this.fCons.value = d.cons;
+    }
+
+    private restoreSettings(d: Record<string, string>) {
+      if (d.speed) this.vCruise.value = d.speed;
+      if (d.state) this.seaSel.value = d.state;
+      if (d.res) this.fRes.value = d.res;
+      if (d.price) this.fPrice.value = d.price;
+      if (d.inv) this.invDist.value = d.inv;
+    }
+
+    private restoreFields(d: Record<string, string>) {
+      this.restoreInputs(d);
+      this.restoreSettings(d);
+    }
+
+    private load() {
+      try {
+        const raw = localStorage.getItem('jjlmoya-nautical-endurance');
+        if (raw) this.restoreFields(JSON.parse(raw) as Record<string, string>);
+      } catch { }
+      this.calculate();
+    }
+
+    private readTanks() {
+      return {
+        tank1: parseFloat(this.t1.value) || 0,
+        tank2: parseFloat(this.t2.value) || 0,
+        fuelCurrent: parseFloat(this.fCur.value) || 0,
+      };
+    }
+
+    private readInputs() {
+      const tanks = this.readTanks();
+      return {
+        ...tanks,
+        seaFactor: parseFloat(this.seaSel.value) || 1.0,
+        consumption: parseFloat(this.fCons.value) || 0,
+        speed: parseFloat(this.vCruise.value) || 0,
+        reserve: parseFloat(this.fRes.value) || 0,
+        price: parseFloat(this.fPrice.value) || 0,
+      };
+    }
+
+    private calculate() {
+      const p = this.readInputs();
+      const realCons = p.consumption * p.seaFactor;
+      const lpmn = p.speed > 0 ? realCons / p.speed : 0;
+      const hTotal = realCons > 0 ? p.fuelCurrent / realCons : 0;
+      const maxDist = hTotal * p.speed;
+      const safeFuel = p.fuelCurrent * (1 - p.reserve / 100);
+      const safeHours = realCons > 0 ? safeFuel / realCons : 0;
+      const safeDist = safeHours * p.speed;
+      const tCap = p.tank1 + p.tank2;
+      const fuelPct = tCap > 0 ? (p.fuelCurrent / tCap) * 100 : 0;
+      this.updateDisplay({ maxDist, safeHours, safeDist, lpmn, fuelPct, price: p.price, fuelCurrent: p.fuelCurrent, reserve: p.reserve });
+      this.updateInverse();
+    }
+
+    private updateDisplay(r: { maxDist: number; safeHours: number; safeDist: number; lpmn: number; fuelPct: number; price: number; fuelCurrent: number; reserve: number }) {
+      this.setText('out-dist', r.maxDist.toFixed(1));
+      this.setText('out-fuel-pct', `${r.fuelPct.toFixed(0)}%`);
+      this.setText('out-perf', r.lpmn.toFixed(2));
+      this.setText('out-hours', r.safeHours.toFixed(1));
+      this.setText('out-safe', r.safeDist.toFixed(1));
+      const fill = document.getElementById('progress-fill') as HTMLElement;
+      fill.style.width = `${Math.min(100, r.fuelPct)}%`;
+      const marker = document.getElementById('reserve-marker') as HTMLElement;
+      marker.style.left = `${Math.max(0, Math.min(100, 100 - r.reserve))}%`;
+      const cost = r.price > 0 ? r.fuelCurrent * r.price : 0;
+      const cardCost = document.getElementById('card-cost') as HTMLElement;
+      if (r.price > 0) {
+        cardCost.classList.remove('hidden');
+        this.setText('out-cost', `${cost.toFixed(2)} €`);
+      } else {
+        cardCost.classList.add('hidden');
+      }
+    }
+
+    private updateInverse() {
+      const p = this.readInputs();
+      const realCons = p.consumption * p.seaFactor;
+      const lpmn = p.speed > 0 ? realCons / p.speed : 0;
+      const dist = parseFloat(this.invDist.value) || 0;
+      const reserveFactor = 1 - p.reserve / 100;
+      const needed = reserveFactor > 0 ? (dist * lpmn) / reserveFactor : 0;
+      this.setText('inv-res', `${needed.toFixed(1)} L`);
+    }
+
+    private setText(id: string, val: string) {
+      const el = document.getElementById(id);
+      if (el) el.textContent = val;
+    }
+  }
+
+  void SEA_FACTORS;
+  new EnduranceCalculator();
+</script>

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

@@ -0,0 +1,243 @@
+import type { WithContext, FAQPage, HowTo, SoftwareApplication } from 'schema-dts';
+import type { EnduranceUI, EnduranceLocaleContent } from '../index';
+
+const slug = 'nautical-endurance-calculator';
+const title = 'Nautical Endurance Calculator';
+const description =
+  'Calculate your maximum range and safe distance based on fuel consumption, tank capacity and cruise speed. Fuel management for motorboats.';
+
+const ui: EnduranceUI = {
+  tankCapacityLabel: 'Tank Capacity',
+  mainTankLabel: 'Main',
+  auxTankLabel: 'Aux',
+  currentFuelLabel: 'Current Fuel',
+  seaConditionsLabel: 'Sea / Wind Conditions',
+  consumptionLabel: 'Theoretical Consumption',
+  cruiseSpeedLabel: 'Cruise Speed',
+  reserveLabel: 'Reserve',
+  fuelPriceLabel: 'Price per Litre',
+  maxRangeLabel: 'Maximum Range',
+  realPerformanceLabel: 'Real Performance',
+  hoursLabel: 'Endurance Hours',
+  safeMilesLabel: 'Safe Miles',
+  tankValueLabel: 'Tank Value',
+  inverseCalcLabel: 'Reverse Calculation: How much do I need to refuel?',
+  desiredDistLabel: 'Desired Distance',
+  minFuelLabel: 'Minimum Fuel Required',
+  warningLabel: 'Reminder: A 20% reserve is the absolute minimum recommended for nautical safety.',
+  seaCalm: 'Calm (1.0x)',
+  seaLight: 'Light swell (+15%)',
+  seaModerate: 'Moderate swell (+30%)',
+  seaStorm: 'Storm (+60%)',
+  faqTitle: 'Frequently Asked Questions',
+  bibliographyTitle: 'Bibliography',
+};
+const faq: EnduranceLocaleContent['faq'] = [
+  {
+    question: 'How is the endurance of a motorboat calculated?',
+    answer: 'Endurance is calculated by dividing the available fuel by the hourly consumption to obtain total hours, then multiplying that time by the cruise speed. The tool also applies a sea state factor to reflect real navigating conditions.',
+  },
+  {
+    question: 'Why is a 20% reserve recommended in nautical navigation?',
+    answer: 'The 20% reserve is a nautical safety standard that ensures enough fuel in case of unforeseen events: contrary currents, detours due to bad weather, errors in consumption estimates, or the need to assist another vessel. Many insurers and harbour masters consider it mandatory.',
+  },
+  {
+    question: 'What is the L/NM performance and how does it affect planning?',
+    answer: 'Performance in litres per nautical mile (L/NM) is the real efficiency of the engine at sea conditions. Unlike hourly consumption, it lets you calculate exactly how much fuel you need to cover a specific distance, regardless of your speed.',
+  },
+  {
+    question: 'How does sea state affect actual consumption?',
+    answer: 'Sea state increases consumption because the hull works harder against water and wind resistance. In light swell consumption rises 15%, in moderate swell 30%, and in a storm it can spike 60% or more. Ignoring this factor can leave a vessel without fuel before reaching port.',
+  },
+];
+const howTo: EnduranceLocaleContent['howTo'] = [
+  {
+    name: 'Enter your tank capacity',
+    text: 'Enter the litres of the main tank and the auxiliary one if you have it. The tool will calculate the current fill percentage.',
+  },
+  {
+    name: 'Enter current fuel level',
+    text: 'Enter the actual litres you have right now. You can measure them with the boat level or estimate them from the last refuel.',
+  },
+  {
+    name: 'Adjust navigation conditions',
+    text: 'Select the expected sea state for your passage. The sea factor corrects the theoretical consumption to the expected real consumption.',
+  },
+  {
+    name: 'Enter consumption and cruise speed',
+    text: 'Use manufacturer data or your own records for hourly consumption and the speed at which you usually navigate.',
+  },
+  {
+    name: 'Review the safe distance and reverse calculation',
+    text: 'The tool shows how many miles you can safely cover and how much fuel you need to reach a specific destination.',
+  },
+];
+
+const bibliography: EnduranceLocaleContent['bibliography'] = [
+  {
+    name: 'UK Maritime and Coastguard Agency',
+    url: 'https://www.gov.uk/government/organisations/maritime-and-coastguard-agency',
+  },
+  {
+    name: 'RYA - Royal Yachting Association',
+    url: 'https://www.rya.org.uk/',
+  },
+];
+const seo: EnduranceLocaleContent['seo'] = [
+  {
+    type: 'title',
+    text: 'Fuel Management and Endurance in Motor Navigation',
+    level: 2,
+  },
+  {
+    type: 'paragraph',
+    html: '<strong>Nautical endurance</strong> is one of the most critical calculations before setting sail on a motorboat. Knowing precisely how many miles you can cover with the available fuel is the difference between a planned passage and an emergency at sea.',
+  },
+  {
+    type: 'paragraph',
+    html: 'This endurance calculator integrates the <strong>sea conditions factor</strong>, the safety reserve percentage, and the reverse fuel calculation so that fuel management is complete and reliable in any situation.',
+  },
+  {
+    type: 'title',
+    text: 'The Golden Rule: The Rule of Thirds',
+    level: 3,
+  },
+  {
+    type: 'paragraph',
+    html: 'The classic fuel management rule in nautical navigation divides the tank into three equal parts to always guarantee a safety margin:',
+  },
+  {
+    type: 'list',
+    items: [
+      '<strong>One third for the outward leg:</strong> The fuel needed to reach the planned destination.',
+      '<strong>One third for the return:</strong> The fuel to get back to the departure port or the nearest one.',
+      '<strong>One third as reserve:</strong> The safety margin for unforeseen events, currents or adverse conditions.',
+    ],
+  },
+  {
+    type: 'paragraph',
+    html: 'In the calculator you can set the reserve percentage according to your own criteria, although <strong>going below 20% is never recommended</strong>. With larger tanks or long passages, many experienced skippers raise this margin to 30% or even 33%.',
+  },
+  {
+    type: 'title',
+    text: 'Factors affecting Consumption (l/h)',
+    level: 3,
+  },
+  {
+    type: 'paragraph',
+    html: "The manufacturer's theoretical consumption is calculated under ideal laboratory conditions. In practice, multiple factors alter the <strong>real fuel consumption</strong>. Hull speed is the most decisive: navigating above the economical speed can double or triple consumption per mile covered.",
+  },  {
+    type: 'table',
+    headers: ['Navigation State', 'Effect on Endurance', 'Advice'],
+    rows: [
+      ['<strong>Fouled Hull</strong>', 'Reduces endurance by up to 20%', 'Clean the hull before the season'],
+      ['<strong>Head Current</strong>', 'Can reduce effective speed by 30%', 'Always calculate with speed over ground'],
+      ['<strong>Head Wind</strong>', 'Increases resistance and consumption by 10-25%', 'Use the light or moderate swell factor'],
+      ['<strong>Overloading</strong>', 'Increases draught and resistance', 'Weigh gear and provisions before calculating'],
+    ],
+  },
+  {
+    type: 'title',
+    text: 'Endurance Technical Glossary',
+    level: 3,
+  },
+  {
+    type: 'glossary',
+    items: [
+      { term: 'Performance (L/NM)', definition: 'Litres of fuel consumed per nautical mile covered. The most useful indicator for planning passages because it links consumption to actual distance.' },
+      { term: 'Cruise Speed', definition: 'The optimum speed at which the engine offers the best balance between speed and consumption. Generally between 70% and 80% of maximum power.' },
+      { term: 'Critical Reserve', definition: 'The percentage of the tank that must never be consumed. A minimum of 20% is recommended to cover contingencies and prevent air from entering the fuel circuit.' },
+      { term: 'Specific Consumption', definition: 'Grams of fuel per kilowatt-hour of power produced (g/kWh). Technical engine measure that allows comparing efficiency between different propulsion systems.' },
+    ],
+  },
+  {
+    type: 'title',
+    text: 'The Danger of Sludge and Movement',
+    level: 3,
+  },
+  {
+    type: 'paragraph',
+    html: 'A common source of problems on vessels with low fuel levels is <strong>tank bottom sludge</strong>. When the level drops too low, sediments accumulated over years can reach the filter and clog it, leaving the engine without fuel even though the gauge shows some litres.',
+  },
+  {
+    type: 'paragraph',
+    html: 'The movement of the boat at sea with little fuel can also cause problems: the liquid oscillates with the waves and can momentarily starve the fuel pump. Maintaining the reserve ensures this does not happen at a critical moment such as a harbour entry manoeuvre.',
+  },  {
+    type: 'tip',
+    title: 'Fuel Saving Tip',
+    html: 'Reducing speed by 10-15% below your usual cruise speed can improve efficiency by up to 30%. If you have time and the weather is favourable, going slower is always the most economical and safe decision.',
+  },
+  {
+    type: 'title',
+    text: 'Difference between Nautical Miles (NM) and Kilometres',
+    level: 3,
+  },
+  {
+    type: 'paragraph',
+    html: 'A <strong>nautical mile</strong> equals 1,852 metres (1.852 km), and is the universal distance unit in maritime and aeronautical navigation. It is based on one arc-minute of a geographic degree, making it ideal for navigation with charts in geographic coordinates. Speed in nautical miles per hour is called a knot (kn).',
+  },
+  {
+    type: 'comparative',
+    items: [
+      {
+        title: 'Needle Analogue Gauge',
+        description: 'Traditional float system',
+        points: [
+          'Low cost and simple installation',
+          'Requires no electricity to operate',
+          'Inaccurate in rough seas due to fuel movement',
+          'Does not show consumption or estimated endurance',
+        ],
+      },
+      {
+        title: 'Digital Flow Calculator',
+        description: 'Electronic flow sensors',
+        highlight: true,
+        points: [
+          '1-2% accuracy on real consumption',
+          'Shows endurance, consumption and cost in real time',
+          'Integrable with chartplotters and NMEA 2000',
+          'Requires initial calibration and maintenance',
+        ],
+      },
+    ],
+  },
+];
+const schemas: EnduranceLocaleContent['schemas'] = [
+  {
+    '@context': 'https://schema.org',
+    '@type': 'SoftwareApplication',
+    name: title,
+    description,
+    applicationCategory: 'UtilityApplication',
+    operatingSystem: 'Web',
+    offers: { '@type': 'Offer', price: '0', priceCurrency: 'EUR' },
+  } as WithContext<SoftwareApplication>,
+  {
+    '@context': 'https://schema.org',
+    '@type': 'FAQPage',
+    mainEntity: faq.map((item) => ({
+      '@type': 'Question',
+      name: item.question,
+      acceptedAnswer: { '@type': 'Answer', text: item.answer },
+    })),
+  } as WithContext<FAQPage>,
+  {
+    '@context': 'https://schema.org',
+    '@type': 'HowTo',
+    name: `How to use: ${title}`,
+    step: howTo.map((s) => ({ '@type': 'HowToStep', name: s.name, text: s.text })),
+  } as WithContext<HowTo>,
+];
+
+export const content: EnduranceLocaleContent = {
+  slug,
+  title,
+  description,
+  ui,
+  seo,
+  faq,
+  bibliography,
+  howTo,
+  schemas,
+};