@jjlmoya/utils-drones 1.35.0 → 1.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jjlmoya/utils-drones",
-    "version": "1.35.0",
+    "version": "1.36.0",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",

package/src/entries.ts

@@ -14,6 +14,8 @@ export { fpvDroneThrustToWeightRatio } from './tool/fpv-drone-thrust-to-weight-r
 export type { FpvDroneThrustToWeightRatioUI, FpvDroneThrustToWeightRatioLocaleContent } from './tool/fpv-drone-thrust-to-weight-ratio/entry';
 export { droneMotorPropellerCalculator } from './tool/drone-motor-propeller-calculator/entry';
 export type { DroneMotorPropellerUI, DroneMotorPropellerLocaleContent } from './tool/drone-motor-propeller-calculator/entry';
+export { fpvDroneSpeedCalculator } from './tool/fpv-drone-speed-calculator/entry';
+export type { FpvDroneSpeedUI, FpvDroneSpeedLocaleContent } from './tool/fpv-drone-speed-calculator/entry';
 export { dronesCategory } from './category';
 
 import { antennaLengthCalculator } from './tool/antenna-length-calculator/entry';
@@ -24,6 +26,7 @@ import { gsdFlightPlanner } from './tool/gsd-flight-planner/entry';
 import { droneBatteryCRatingCalculator } from './tool/drone-battery-c-rating-calculator/entry';
 import { fpvDroneThrustToWeightRatio } from './tool/fpv-drone-thrust-to-weight-ratio/entry';
 import { droneMotorPropellerCalculator } from './tool/drone-motor-propeller-calculator/entry';
+import { fpvDroneSpeedCalculator } from './tool/fpv-drone-speed-calculator/entry';
 
 export const ALL_ENTRIES = [
   antennaLengthCalculator,
@@ -34,4 +37,5 @@ export const ALL_ENTRIES = [
   droneBatteryCRatingCalculator,
   fpvDroneThrustToWeightRatio,
   droneMotorPropellerCalculator,
+  fpvDroneSpeedCalculator,
 ];

package/src/index.ts

@@ -22,3 +22,4 @@ export { GPS_COORDINATES_CONVERTER_TOOL } from './tool/gps-coordinates-converter
 export { DRONE_POWER_ANALYZER_TOOL } from './tool/drone-power-analyzer/index';
 export { GSD_FLIGHT_PLANNER_TOOL } from './tool/gsd-flight-planner/index';
 export { DRONE_MOTOR_PROPELLER_CALCULATOR_TOOL } from './tool/drone-motor-propeller-calculator/index';
+export { FPV_DRONE_SPEED_CALCULATOR_TOOL } from './tool/fpv-drone-speed-calculator/index';

package/src/tests/locale_completeness.test.ts

@@ -17,7 +17,7 @@ describe('Locale Completeness Validation', () => {
     });
   });
 
-  it('all 7 tools registered', () => {
-    expect(ALL_TOOLS.length).toBe(8);
+  it('all 9 tools registered', () => {
+    expect(ALL_TOOLS.length).toBe(9);
   });
 });

package/src/tests/tool_validation.test.ts

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

package/src/tool/fpv-drone-speed-calculator/bibliography.astro

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

package/src/tool/fpv-drone-speed-calculator/bibliography.ts

@@ -0,0 +1,14 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliography: BibliographyEntry[] = [
+  {
+    name: 'Universidad Politécnica de Madrid - Comparación de una hélice de paso fijo con una de paso variable para una aplicación de un avión VTOL',
+    url: 'https://oa.upm.es/64973/',
+  },
+  {
+    name: 'NASA Technical Reports Server - Efficient Variable-Pitch Propeller Aerodynamic Model Development for Vectored-Thrust eVTOL Aircraft',
+    url: 'https://ntrs.nasa.gov/citations/20220005627',
+  },
+];
+
+export const BIBLIOGRAPHY_ITEMS = bibliography;

package/src/tool/fpv-drone-speed-calculator/component.astro

@@ -0,0 +1,115 @@
+---
+import type { FpvDroneSpeedUI } from './ui';
+
+interface Props {
+  ui: FpvDroneSpeedUI;
+}
+
+const { ui } = Astro.props;
+---
+
+<div class="fpv-speed-tool" data-fpv-speed-calculator data-unit="metric">
+  <script is:inline type="application/json" data-fpv-speed-ui set:html={JSON.stringify(ui)}></script>
+
+  <div class="speed-brief">
+    <div>
+      <span class="brief-kicker">{ui.calculateFromLabel}</span>
+      <p>{ui.assumptionsText}</p>
+    </div>
+    <div class="unit-switch" role="group" aria-label={ui.unitsLabel}>
+      <button type="button" class="unit-button is-selected" data-unit="metric" aria-pressed="true">{ui.metricUnit}</button>
+      <button type="button" class="unit-button" data-unit="imperial" aria-pressed="false">{ui.imperialUnit}</button>
+    </div>
+  </div>
+
+  <section class="flight-deck" aria-labelledby="speed-inputs-title">
+    <div class="control-rail">
+      <div class="rail-heading">
+        <span class="brief-kicker">{ui.inputsLabel}</span>
+        <h2 id="speed-inputs-title">{ui.presetsLabel}</h2>
+      </div>
+      <div class="preset-track">
+        <button type="button" class="preset-button" data-preset="racing">{ui.presetRacing}</button>
+        <button type="button" class="preset-button is-selected" data-preset="freestyle">{ui.presetFreestyle}</button>
+        <button type="button" class="preset-button" data-preset="cruiser">{ui.presetCruiser}</button>
+      </div>
+      <div class="input-list">
+        <label class="input-row"><span>{ui.motorKvLabel}</span><input data-field="motorKv" type="number" min="100" max="10000" step="50" inputmode="decimal" /><small>KV</small></label>
+        <label class="input-row"><span>{ui.batteryVoltageLabel}</span><input data-field="batteryVoltage" type="number" min="1" max="80" step="0.1" inputmode="decimal" /><small>V</small></label>
+        <label class="input-row"><span>{ui.propellerPitchLabel}</span><input data-field="propellerPitchInches" type="number" min="0.5" max="25" step="0.1" inputmode="decimal" /><small>in</small></label>
+        <label class="input-row"><span>{ui.efficiencyLabel}</span><input data-field="efficiencyPercent" type="number" min="50" max="98" step="1" inputmode="decimal" /><small>%</small></label>
+        <label class="input-row"><span>{ui.aircraftMassLabel}</span><input data-field="aircraftMassGrams" type="number" min="1" max="50000" step="10" inputmode="decimal" /><small data-unit-label="mass">g</small></label>
+      </div>
+    </div>
+
+    <div class="speed-orchestra">
+      <div class="speed-orchestra-header">
+        <div>
+          <span class="brief-kicker">{ui.resultsLabel}</span>
+          <h2>{ui.speedLaneLabel}</h2>
+        </div>
+        <div class="diagnosis" data-output="diagnosis" aria-live="polite">{ui.diagnosisPlanning}</div>
+      </div>
+
+      <div class="speed-lane" aria-label={ui.speedLaneLabel}>
+        <div class="lane-grid" aria-hidden="true"></div>
+        <div class="lane-horizon" aria-hidden="true"></div>
+        <div class="lane-header">
+          <span>{ui.speedLaneLabel}</span>
+          <span><b data-output="speed-axis-start">{ui.speedAxisStart}</b><i></i><b data-output="speed-axis-end">{ui.speedAxisEnd}</b></span>
+        </div>
+        <div class="speed-comparison">
+          <div class="comparison-scale" aria-hidden="true">
+            <span data-output="speed-axis-start">{ui.speedAxisStart}</span>
+            <span data-output="speed-axis-mid">150 km/h</span>
+            <span data-output="speed-axis-end">{ui.speedAxisEnd}</span>
+          </div>
+          <div class="comparison-row">
+            <div class="comparison-label"><span>{ui.estimatedSpeedLabel}</span><strong data-output="estimated-speed">178 km/h</strong></div>
+            <div class="comparison-track"><i class="comparison-fill comparison-fill-estimated"></i></div>
+          </div>
+          <div class="comparison-row">
+            <div class="comparison-label"><span>{ui.pitchSpeedLabel}</span><strong data-output="pitch-speed">217 km/h</strong></div>
+            <div class="comparison-track"><i class="comparison-fill comparison-fill-pitch"></i></div>
+          </div>
+          <div class="comparison-gap"><span>{ui.slipLabel}</span><strong data-output="speed-gap">39 km/h</strong><small data-output="slip">18%</small></div>
+        </div>
+      </div>
+
+      <div class="speed-readouts">
+        <div class="hero-readout"><strong data-output="estimated-speed">178 km/h</strong><span>{ui.estimatedSpeedLabel}</span></div>
+        <div class="readout"><strong data-output="pitch-speed">217 km/h</strong><span>{ui.pitchSpeedLabel}</span></div>
+        <div class="readout"><strong data-output="loaded-rpm">36,000 rpm</strong><span>{ui.loadedRpmLabel}</span></div>
+      </div>
+
+      <p class="diagnosis-advice" data-output="diagnosis-advice" aria-live="polite">{ui.diagnosisPlanningAdvice}</p>
+
+      <section class="sensitivity" aria-labelledby="sensitivity-title">
+        <div class="subheading"><span class="brief-kicker">{ui.sensitivityLabel}</span><h3 id="sensitivity-title">{ui.propellerPitchLabel}</h3></div>
+        <div class="sensitivity-row">
+          <div class="sensitivity-point"><span>{ui.lowerPitchLabel}</span><strong data-output="lower-speed">158 km/h</strong><small data-output="lower-pitch">3.8 in</small><div class="sensitivity-bar"><i data-bar="lower"></i></div></div>
+          <div class="sensitivity-point is-current"><span>{ui.selectedPitchLabel}</span><strong data-output="current-speed">178 km/h</strong><small data-output="current-pitch">4.3 in</small><div class="sensitivity-bar"><i data-bar="current"></i></div></div>
+          <div class="sensitivity-point"><span>{ui.higherPitchLabel}</span><strong data-output="higher-speed">199 km/h</strong><small data-output="higher-pitch">4.8 in</small><div class="sensitivity-bar"><i data-bar="higher"></i></div></div>
+        </div>
+      </section>
+
+      <div class="metric-strip">
+        <div><span>{ui.noLoadRpmLabel}</span><strong data-output="no-load-rpm">43,290 rpm</strong></div>
+        <div><span>{ui.slipLabel}</span><strong data-output="slip">18%</strong></div>
+        <div><span>{ui.loadEffectLabel}</span><strong data-output="load-effect">7%</strong></div>
+      </div>
+    </div>
+  </section>
+
+  <div class="assumptions-row">
+    <p><strong>{ui.assumptionsLabel}</strong> {ui.assumptionsText}</p>
+    <p>{ui.safetyText}</p>
+  </div>
+</div>
+
+<script>
+  import { initFpvDroneSpeedCalculator } from './controller';
+
+  const root = document.querySelector<HTMLElement>('[data-fpv-speed-calculator]');
+  if (root) initFpvDroneSpeedCalculator(root);
+</script>

package/src/tool/fpv-drone-speed-calculator/controller.ts

@@ -0,0 +1,105 @@
+import { calculateFpvDroneSpeed, type FpvDroneSpeedInputs } from './logic';
+import { formatMassInput, parseMassInput, renderResults, updateUnitLabels, type DisplayUnit } from './dom-views';
+import type { FpvDroneSpeedUI } from './ui';
+
+interface Preset {
+  id: string;
+  inputs: FpvDroneSpeedInputs;
+}
+
+const PRESETS: Preset[] = [
+  { id: 'racing', inputs: { motorKv: 2450, batteryVoltage: 16.8, propellerPitchInches: 4.3, efficiencyPercent: 84, aircraftMassGrams: 620 } },
+  { id: 'freestyle', inputs: { motorKv: 1950, batteryVoltage: 22.2, propellerPitchInches: 4.3, efficiencyPercent: 82, aircraftMassGrams: 700 } },
+  { id: 'cruiser', inputs: { motorKv: 1500, batteryVoltage: 22.2, propellerPitchInches: 3.5, efficiencyPercent: 78, aircraftMassGrams: 1200 } },
+];
+
+const DEFAULT_INPUTS = PRESETS[1]!.inputs;
+
+function input(root: HTMLElement, field: string): HTMLInputElement | null {
+  return root.querySelector<HTMLInputElement>(`[data-field="${field}"]`);
+}
+
+function setInput(root: HTMLElement, field: string, value: string): void {
+  const element = input(root, field);
+  if (element) element.value = value;
+}
+
+function readInputs(root: HTMLElement, unit: DisplayUnit): FpvDroneSpeedInputs {
+  const read = (field: string): number => Number(input(root, field)?.value ?? 0);
+  return {
+    motorKv: read('motorKv'),
+    batteryVoltage: read('batteryVoltage'),
+    propellerPitchInches: read('propellerPitchInches'),
+    efficiencyPercent: read('efficiencyPercent'),
+    aircraftMassGrams: parseMassInput(input(root, 'aircraftMassGrams')?.value ?? '', unit),
+  };
+}
+
+function setInputs(root: HTMLElement, values: FpvDroneSpeedInputs, unit: DisplayUnit): void {
+  setInput(root, 'motorKv', String(values.motorKv));
+  setInput(root, 'batteryVoltage', String(values.batteryVoltage));
+  setInput(root, 'propellerPitchInches', String(values.propellerPitchInches));
+  setInput(root, 'efficiencyPercent', String(values.efficiencyPercent));
+  setInput(root, 'aircraftMassGrams', formatMassInput(values.aircraftMassGrams, unit));
+}
+
+function selectPreset(root: HTMLElement, id: string): void {
+  root.querySelectorAll<HTMLElement>('[data-preset]').forEach((element) => {
+    element.classList.toggle('is-selected', element.dataset.preset === id);
+  });
+}
+
+function selectUnit(root: HTMLElement, unit: DisplayUnit): void {
+  root.querySelectorAll<HTMLElement>('[data-unit]').forEach((element) => {
+    const active = element.dataset.unit === unit;
+    element.classList.toggle('is-selected', active);
+    element.setAttribute('aria-pressed', String(active));
+  });
+}
+
+function recalculate(root: HTMLElement, ui: FpvDroneSpeedUI, unit: DisplayUnit): void {
+  const results = calculateFpvDroneSpeed(readInputs(root, unit));
+  renderResults({ root, results, ui, unit });
+}
+
+function changeUnit(root: HTMLElement, ui: FpvDroneSpeedUI, from: DisplayUnit, to: DisplayUnit): void {
+  if (from === to) return;
+  const values = readInputs(root, from);
+  setInputs(root, values, to);
+  root.dataset.unit = to;
+  selectUnit(root, to);
+  updateUnitLabels(root, to, ui);
+  recalculate(root, ui, to);
+}
+
+function readUi(root: HTMLElement): FpvDroneSpeedUI {
+  const element = root.querySelector<HTMLScriptElement>('[data-fpv-speed-ui]');
+  return JSON.parse(element?.textContent ?? '{}') as FpvDroneSpeedUI;
+}
+
+export function initFpvDroneSpeedCalculator(root: HTMLElement): void {
+  const ui = readUi(root);
+  let unit: DisplayUnit = 'metric';
+  setInputs(root, DEFAULT_INPUTS, unit);
+  updateUnitLabels(root, unit, ui);
+  selectUnit(root, unit);
+  root.dataset.unit = unit;
+
+  root.querySelectorAll<HTMLElement>('[data-preset]').forEach((element) => element.addEventListener('click', () => {
+    const preset = PRESETS.find((item) => item.id === element.dataset.preset);
+    if (!preset) return;
+    setInputs(root, preset.inputs, unit);
+    selectPreset(root, preset.id);
+    recalculate(root, ui, unit);
+  }));
+  root.querySelectorAll<HTMLElement>('[data-unit]').forEach((element) => element.addEventListener('click', () => {
+    const next = element.dataset.unit === 'imperial' ? 'imperial' : 'metric';
+    changeUnit(root, ui, unit, next);
+    unit = next;
+  }));
+  root.querySelectorAll<HTMLInputElement>('input[data-field]').forEach((element) => element.addEventListener('input', () => {
+    selectPreset(root, '');
+    recalculate(root, ui, unit);
+  }));
+  recalculate(root, ui, unit);
+}

package/src/tool/fpv-drone-speed-calculator/dom-views.ts

@@ -0,0 +1,80 @@
+import type { FpvDroneSpeedResults } from './logic';
+import type { FpvDroneSpeedUI } from './ui';
+
+export type DisplayUnit = 'metric' | 'imperial';
+
+interface RenderContext {
+  root: HTMLElement;
+  results: FpvDroneSpeedResults;
+  ui: FpvDroneSpeedUI;
+  unit: DisplayUnit;
+}
+
+function number(value: number, digits = 0): string {
+  return new Intl.NumberFormat(undefined, { maximumFractionDigits: digits }).format(value);
+}
+
+function speed(value: number, unit: DisplayUnit): string {
+  return `${number(unit === 'metric' ? value : value / 1.60934)} ${unit === 'metric' ? 'km/h' : 'mph'}`;
+}
+
+function mass(value: number, unit: DisplayUnit): string {
+  return `${number(unit === 'metric' ? value : value / 28.3495, unit === 'metric' ? 0 : 1)} ${unit === 'metric' ? 'g' : 'oz'}`;
+}
+
+function setText(root: HTMLElement, key: string, value: string): void {
+  root.querySelectorAll<HTMLElement>(`[data-output="${key}"]`).forEach((target) => {
+    target.textContent = value;
+  });
+}
+
+function diagnosisText(results: FpvDroneSpeedResults, ui: FpvDroneSpeedUI): [string, string] {
+  if (results.diagnosis === 'overspeed') return [ui.diagnosisOverspeed, ui.diagnosisOverspeedAdvice];
+  if (results.diagnosis === 'high-slip') return [ui.diagnosisHighSlip, ui.diagnosisHighSlipAdvice];
+  if (results.diagnosis === 'heavy-load') return [ui.diagnosisHeavyLoad, ui.diagnosisHeavyLoadAdvice];
+  return [ui.diagnosisPlanning, ui.diagnosisPlanningAdvice];
+}
+
+export function renderResults({ root, results, ui, unit }: RenderContext): void {
+  const [diagnosis, advice] = diagnosisText(results, ui);
+  setText(root, 'estimated-speed', speed(results.estimatedSpeedKmh, unit));
+  setText(root, 'pitch-speed', speed(results.pitchSpeedKmh, unit));
+  setText(root, 'loaded-rpm', `${number(results.loadedRpm)} rpm`);
+  setText(root, 'no-load-rpm', `${number(results.noLoadRpm)} rpm`);
+  setText(root, 'slip', `${number(results.slipPercent, 1)}%`);
+  setText(root, 'load-effect', `${number(results.loadPenaltyPercent, 1)}%`);
+  setText(root, 'speed-gap', speed(Math.max(0, results.pitchSpeedKmh - results.estimatedSpeedKmh), unit));
+  setText(root, 'speed-axis-start', speed(0, unit));
+  setText(root, 'speed-axis-end', speed(300, unit));
+  setText(root, 'diagnosis', diagnosis);
+  setText(root, 'diagnosis-advice', advice);
+  results.sensitivity.forEach((point) => {
+    setText(root, `${point.label}-pitch`, `${number(point.pitchInches, 1)} in`);
+    setText(root, `${point.label}-speed`, speed(point.speedKmh, unit));
+    const bar = root.querySelector<HTMLElement>(`[data-bar="${point.label}"]`);
+    if (bar) bar.style.setProperty('--bar-width', `${Math.min(100, Math.max(4, point.speedKmh / Math.max(results.sensitivity[2]?.speedKmh ?? 1, 1) * 100))}%`);
+  });
+  root.dataset.diagnosis = results.diagnosis;
+  const speedPosition = Math.min(92, Math.max(8, results.estimatedSpeedKmh / 300 * 84 + 8));
+  const pitchPosition = Math.min(92, Math.max(8, results.pitchSpeedKmh / 300 * 84 + 8));
+  root.style.setProperty('--speed-position', `${speedPosition}%`);
+  root.style.setProperty('--pitch-position', `${pitchPosition}%`);
+}
+
+export function updateUnitLabels(root: HTMLElement, unit: DisplayUnit, ui: FpvDroneSpeedUI): void {
+  root.querySelectorAll<HTMLElement>('[data-unit-label="mass"]').forEach((element) => { element.textContent = unit === 'metric' ? 'g' : 'oz'; });
+  root.querySelectorAll<HTMLElement>('[data-unit-label="speed"]').forEach((element) => { element.textContent = unit === 'metric' ? ui.speedUnit : 'mph'; });
+}
+
+export function formatMassInput(grams: number, unit: DisplayUnit): string {
+  return unit === 'metric' ? String(Math.round(grams)) : String(Math.round(grams / 28.3495 * 10) / 10);
+}
+
+export function parseMassInput(value: string, unit: DisplayUnit): number {
+  const parsed = Number(value);
+  return unit === 'metric' ? parsed : parsed * 28.3495;
+}
+
+export function formatMassLabel(grams: number, unit: DisplayUnit): string {
+  return mass(grams, unit);
+}

package/src/tool/fpv-drone-speed-calculator/entry.ts

@@ -0,0 +1,27 @@
+import type { DronesToolEntry, ToolLocaleContent } from '../../types';
+import type { FpvDroneSpeedUI } from './ui';
+
+export type { FpvDroneSpeedUI };
+export type FpvDroneSpeedLocaleContent = ToolLocaleContent<FpvDroneSpeedUI>;
+
+export const fpvDroneSpeedCalculator: DronesToolEntry<FpvDroneSpeedUI> = {
+  id: 'fpv-drone-speed-calculator',
+  icons: { bg: 'mdi:quadcopter', fg: 'mdi:speedometer' },
+  i18n: {
+    es: () => import('./i18n/es').then((module) => module.content),
+    en: () => import('./i18n/en').then((module) => module.content),
+    fr: () => import('./i18n/fr').then((module) => module.content),
+    de: () => import('./i18n/de').then((module) => module.content),
+    it: () => import('./i18n/it').then((module) => module.content),
+    pt: () => import('./i18n/pt').then((module) => module.content),
+    nl: () => import('./i18n/nl').then((module) => module.content),
+    pl: () => import('./i18n/pl').then((module) => module.content),
+    ru: () => import('./i18n/ru').then((module) => module.content),
+    ja: () => import('./i18n/ja').then((module) => module.content),
+    ko: () => import('./i18n/ko').then((module) => module.content),
+    zh: () => import('./i18n/zh').then((module) => module.content),
+    tr: () => import('./i18n/tr').then((module) => module.content),
+    sv: () => import('./i18n/sv').then((module) => module.content),
+    id: () => import('./i18n/id').then((module) => module.content),
+  },
+};