@jjlmoya/utils-hardware 1.20.0 → 1.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jjlmoya/utils-hardware",
-    "version": "1.20.0",
+    "version": "1.21.0",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",

package/src/category/index.ts

@@ -10,10 +10,11 @@ import { toneGenerator } from '../tool/toneGenerator/index';
 import { refreshRateDetector } from '../tool/refreshRateDetector/index';
 import { monitorGhostingTest } from '../tool/monitorGhostingTest/index';
 import { spectrumCanvas } from '../tool/colorAccuracyTest/index';
+import { upsRuntimeCalculator } from '../tool/upsRuntimeCalculator/index';
 
 export const hardwareCategory: HardwareCategoryEntry = {
   icon: 'mdi:memory',
-  tools: [pixelesPantalla, testTeclado, testMando, probadorVibracionMando, testRaton, mouseDoubleClickTest, estimadorSaludBateria, toneGenerator, refreshRateDetector, monitorGhostingTest, spectrumCanvas],
+  tools: [pixelesPantalla, testTeclado, testMando, probadorVibracionMando, testRaton, mouseDoubleClickTest, estimadorSaludBateria, toneGenerator, refreshRateDetector, monitorGhostingTest, spectrumCanvas, upsRuntimeCalculator],
   i18n: {
     en: () => import('./i18n/en').then((m) => m.content),
     es: () => import('./i18n/es').then((m) => m.content),

package/src/entries.ts

@@ -20,6 +20,8 @@ export { monitorGhostingTest } from './tool/monitorGhostingTest/entry';
 export type { MonitorGhostingTestLocaleContent } from './tool/monitorGhostingTest/entry';
 export { spectrumCanvas } from './tool/colorAccuracyTest/entry';
 export type { SpectrumCanvasLocaleContent } from './tool/colorAccuracyTest/entry';
+export { upsRuntimeCalculator } from './tool/upsRuntimeCalculator/entry';
+export type { UpsRuntimeCalculatorLocaleContent } from './tool/upsRuntimeCalculator/entry';
 export { hardwareCategory } from './category';
 import { estimadorSaludBateria } from './tool/batteryHealthEstimator/entry';
 import { pixelesPantalla } from './tool/deadPixelTest/entry';
@@ -32,4 +34,5 @@ import { toneGenerator } from './tool/toneGenerator/entry';
 import { refreshRateDetector } from './tool/refreshRateDetector/entry';
 import { monitorGhostingTest } from './tool/monitorGhostingTest/entry';
 import { spectrumCanvas } from './tool/colorAccuracyTest/entry';
-export const ALL_ENTRIES = [estimadorSaludBateria, pixelesPantalla, testMando, probadorVibracionMando, testTeclado, testRaton, mouseDoubleClickTest, toneGenerator, refreshRateDetector, monitorGhostingTest, spectrumCanvas];
+import { upsRuntimeCalculator } from './tool/upsRuntimeCalculator/entry';
+export const ALL_ENTRIES = [estimadorSaludBateria, pixelesPantalla, testMando, probadorVibracionMando, testTeclado, testRaton, mouseDoubleClickTest, toneGenerator, refreshRateDetector, monitorGhostingTest, spectrumCanvas, upsRuntimeCalculator];

package/src/index.ts

@@ -28,3 +28,4 @@ export { TONE_GENERATOR_TOOL } from './tool/toneGenerator/index';
 export { REFRESH_RATE_DETECTOR_TOOL } from './tool/refreshRateDetector/index';
 export { MONITOR_GHOSTING_TEST_TOOL } from './tool/monitorGhostingTest/index';
 export { SPECTRUM_CANVAS_TOOL } from './tool/colorAccuracyTest/index';
+export { UPS_RUNTIME_CALCULATOR_TOOL } from './tool/upsRuntimeCalculator/index';

package/src/tests/locale_completeness.test.ts

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

package/src/tests/tool_validation.test.ts

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

package/src/tool/upsRuntimeCalculator/bibliography.astro

@@ -0,0 +1,14 @@
+---
+import { Bibliography as SharedBibliography } from '@jjlmoya/utils-shared';
+import type { KnownLocale } from '../../types';
+import { upsRuntimeCalculator } from './index';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'en' } = Astro.props;
+const content = await upsRuntimeCalculator.i18n[locale]?.();
+---
+
+{content && content.bibliography.length > 0 && <SharedBibliography links={content.bibliography} />}

package/src/tool/upsRuntimeCalculator/bibliography.ts

@@ -0,0 +1,16 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliography: BibliographyEntry[] = [
+  {
+    name: 'APC by Schneider Electric - UPS battery runtime and load behavior',
+    url: 'https://www.se.com/us/en/work/products/tools/ups-selector/',
+  },
+  {
+    name: 'CyberPower - Understanding watts, volt-amps, and power factor',
+    url: 'https://www.cyberpower.com/global/en/blog/watts-vs-volt-amperes-va-key-power-ratings-for-choosing-the-right-ups',
+  },
+  {
+    name: 'Eaton - UPS sizing and power protection fundamentals',
+    url: 'https://www.eaton.com/us/en-us/catalog/backup-power-ups-surge-it-power-distribution/ups-buying-guide.html',
+  },
+];

package/src/tool/upsRuntimeCalculator/component.astro

@@ -0,0 +1,384 @@
+---
+import { Icon } from 'astro-icon/components';
+import type { KnownLocale } from '../../types';
+import type { UpsRuntimeCalculatorUI } from './ui';
+
+interface Props {
+  locale?: KnownLocale;
+  ui?: Record<string, unknown>;
+}
+
+const { ui } = Astro.props;
+const t = (ui ?? {}) as UpsRuntimeCalculatorUI;
+---
+
+<div
+  class="ups-root"
+  data-config={JSON.stringify({
+    presetDesktop: t.presetDesktop,
+    presetMonitor: t.presetMonitor,
+    presetRouter: t.presetRouter,
+    presetNas: t.presetNas,
+    deviceName: t.deviceName,
+    watts: t.watts,
+    remove: t.remove,
+    bandLight: t.bandLight,
+    bandBalanced: t.bandBalanced,
+    bandHeavy: t.bandHeavy,
+    summaryPrefix: t.summaryPrefix,
+    minutes: t.minutes,
+    hours: t.hours,
+    wattsUnit: t.wattsUnit,
+    percentUnit: t.percentUnit,
+    assumptionsLabel: t.assumptionsLabel,
+  })}
+>
+  <section class="ups-panel">
+    <div class="ups-console ups-load">
+      <div class="ups-strip">
+        <span>{t.loadTitle}</span>
+        <button class="ups-add" type="button" data-add-device>{t.addDevice}</button>
+      </div>
+      <div class="ups-devices" data-devices></div>
+    </div>
+
+    <div class="ups-machine" aria-hidden="true">
+      <div class="ups-shell">
+        <div class="ups-port-row">
+          <i></i><i></i><i></i><i></i>
+        </div>
+        <div class="ups-screen">
+          <span data-runtime-big>0</span>
+          <small data-runtime-unit>{t.minutes}</small>
+        </div>
+        <div class="ups-core">
+          <b></b><b></b><b></b><b></b>
+        </div>
+      </div>
+      <div class="ups-energy-rail">
+        <span data-load-bar></span>
+      </div>
+    </div>
+
+    <div class="ups-console ups-controls" aria-label={t.assumptionsLabel}>
+      <label class="ups-capacity">
+        <span>{t.batteryWh}</span>
+        <span class="ups-number-field ups-number-field-large">
+          <input data-battery type="number" min="50" max="3000" step="10" value="432" />
+          <em>{t.whUnit}</em>
+        </span>
+      </label>
+      <label>
+        <span>{t.efficiency}</span>
+        <input data-efficiency type="range" min="70" max="95" value="86" />
+        <strong data-efficiency-label>86%</strong>
+      </label>
+      <label>
+        <span>{t.powerFactor}</span>
+        <input data-power-factor type="range" min="50" max="100" value="70" />
+        <strong data-power-factor-label>0.70</strong>
+      </label>
+      <label>
+        <span>{t.reserve}</span>
+        <input data-reserve type="range" min="0" max="50" value="20" />
+        <strong data-reserve-label>20%</strong>
+      </label>
+    </div>
+
+    <div class="ups-dashboard">
+      <div class="ups-metrics">
+        <article>
+          <span>{t.totalLoad}</span>
+          <strong><output data-total-load>0</output> {t.wattsUnit}</strong>
+          <i data-load-meter></i>
+        </article>
+        <article>
+          <span>{t.runtime}</span>
+          <strong><output data-runtime>0</output></strong>
+          <i data-runtime-meter></i>
+        </article>
+        <article>
+          <span>{t.recommendedUps}</span>
+          <strong><output data-recommended>0</output> {t.vaUnit}</strong>
+          <i data-va-meter></i>
+        </article>
+        <article>
+          <span>{t.usableEnergy}</span>
+          <strong><output data-usable-energy>0</output> {t.whUnit}</strong>
+          <i data-energy-meter></i>
+        </article>
+      </div>
+      <p class="ups-summary" data-summary></p>
+    </div>
+  </section>
+  <template data-trash-icon>
+    <Icon name="mdi:trash-can-outline" class="ups-trash-icon" />
+  </template>
+</div>
+
+<link rel="stylesheet" href="./ups-runtime-calculator.css" />
+
+<script>
+  interface Device {
+    name: string;
+    watts: number;
+  }
+  interface Config {
+    presetDesktop: string;
+    presetMonitor: string;
+    presetRouter: string;
+    presetNas: string;
+    deviceName: string;
+    watts: string;
+    remove: string;
+    bandLight: string;
+    bandBalanced: string;
+    bandHeavy: string;
+    summaryPrefix: string;
+    minutes: string;
+    hours: string;
+    wattsUnit: string;
+    percentUnit: string;
+    assumptionsLabel: string;
+  }
+  interface PersistedState {
+    devices?: Device[];
+    batteryWh?: string;
+    efficiency?: string;
+    powerFactor?: string;
+    reserve?: string;
+  }
+  type RuntimeStats = { totalWatts: number; usableWh: number; runtimeMinutes: number; recommendedWatts: number; recommendedVa: number };
+  const root = document.querySelector<HTMLElement>('.ups-root');
+  const storageKey = 'ups-runtime-calculator-state';
+  const config = JSON.parse(root?.dataset.config ?? '{}') as Config;
+  const defaultDevices: Device[] = [
+    { name: config.presetDesktop, watts: 260 },
+    { name: config.presetMonitor, watts: 45 },
+    { name: config.presetRouter, watts: 14 },
+    { name: config.presetNas, watts: 38 },
+  ];
+  const savedState = readState();
+  const devices: Device[] = Array.isArray(savedState.devices) && savedState.devices.length > 0
+    ? savedState.devices.map((device) => ({ name: String(device.name), watts: Number(device.watts) || 0 }))
+    : defaultDevices;
+  const els = {
+    devices: root?.querySelector<HTMLElement>('[data-devices]'),
+    add: root?.querySelector<HTMLButtonElement>('[data-add-device]'),
+    battery: root?.querySelector<HTMLInputElement>('[data-battery]'),
+    efficiency: root?.querySelector<HTMLInputElement>('[data-efficiency]'),
+    efficiencyLabel: root?.querySelector<HTMLElement>('[data-efficiency-label]'),
+    powerFactor: root?.querySelector<HTMLInputElement>('[data-power-factor]'),
+    powerFactorLabel: root?.querySelector<HTMLElement>('[data-power-factor-label]'),
+    reserve: root?.querySelector<HTMLInputElement>('[data-reserve]'),
+    reserveLabel: root?.querySelector<HTMLElement>('[data-reserve-label]'),
+    totalLoad: root?.querySelector<HTMLOutputElement>('[data-total-load]'),
+    runtime: root?.querySelector<HTMLOutputElement>('[data-runtime]'),
+    runtimeBig: root?.querySelector<HTMLElement>('[data-runtime-big]'),
+    runtimeUnit: root?.querySelector<HTMLElement>('[data-runtime-unit]'),
+    recommended: root?.querySelector<HTMLOutputElement>('[data-recommended]'),
+    usableEnergy: root?.querySelector<HTMLOutputElement>('[data-usable-energy]'),
+    summary: root?.querySelector<HTMLElement>('[data-summary]'),
+    loadBar: root?.querySelector<HTMLElement>('[data-load-bar]'),
+    loadMeter: root?.querySelector<HTMLElement>('[data-load-meter]'),
+    runtimeMeter: root?.querySelector<HTMLElement>('[data-runtime-meter]'),
+    vaMeter: root?.querySelector<HTMLElement>('[data-va-meter]'),
+    energyMeter: root?.querySelector<HTMLElement>('[data-energy-meter]'),
+    trashIcon: root?.querySelector<HTMLTemplateElement>('[data-trash-icon]'),
+  };
+  applySavedControls();
+  function readState(): PersistedState {
+    try {
+      return JSON.parse(localStorage.getItem(storageKey) ?? '{}') as PersistedState;
+    } catch {
+      return {};
+    }
+  }
+  function saveState() {
+    const nextState: PersistedState = {
+      devices,
+      batteryWh: els.battery?.value,
+      efficiency: els.efficiency?.value,
+      powerFactor: els.powerFactor?.value,
+      reserve: els.reserve?.value,
+    };
+    localStorage.setItem(storageKey, JSON.stringify(nextState));
+  }
+  function applySavedControls() {
+    [
+      [els.battery, savedState.batteryWh],
+      [els.efficiency, savedState.efficiency],
+      [els.powerFactor, savedState.powerFactor],
+      [els.reserve, savedState.reserve],
+    ].forEach(([input, value]) => applySavedValue(input as HTMLInputElement | null | undefined, value as string | undefined));
+  }
+  function applySavedValue(input: HTMLInputElement | null | undefined, value: string | undefined) {
+    if (input && value) {
+      input.value = value;
+    }
+  }
+  function calculate() {
+    const stats = getRuntimeStats();
+    updateLabels();
+    updateOutputs(stats);
+    updateMeters(stats);
+    saveState();
+  }
+  function getRuntimeStats(): RuntimeStats {
+    const totalWatts = devices.reduce((sum, device) => sum + Math.max(0, device.watts), 0);
+    const batteryWh = readNumber(els.battery, 0);
+    const efficiency = readNumber(els.efficiency, 86) / 100;
+    const reserve = readNumber(els.reserve, 20) / 100;
+    const powerFactor = readNumber(els.powerFactor, 70) / 100;
+    const usableWh = batteryWh * efficiency * (1 - reserve);
+    const runtimeMinutes = totalWatts > 0 ? (usableWh / totalWatts) * 60 : 0;
+    const recommendedWatts = Math.ceil((totalWatts * 1.25) / 10) * 10;
+    const recommendedVa = Math.ceil((recommendedWatts / powerFactor) / 50) * 50;
+    return { totalWatts, usableWh, runtimeMinutes, recommendedWatts, recommendedVa };
+  }
+  function updateLabels() {
+    const efficiency = readNumber(els.efficiency, 86) / 100;
+    const reserve = readNumber(els.reserve, 20) / 100;
+    const powerFactor = readNumber(els.powerFactor, 70) / 100;
+    els.efficiencyLabel!.textContent = `${Math.round(efficiency * 100)}${config.percentUnit}`;
+    els.powerFactorLabel!.textContent = powerFactor.toFixed(2);
+    els.reserveLabel!.textContent = `${Math.round(reserve * 100)}${config.percentUnit}`;
+  }
+
+  function updateOutputs(stats: RuntimeStats) {
+    const runtimeValue = getRuntimeValue(stats.runtimeMinutes);
+    const band = getBandText(stats.runtimeMinutes);
+    els.totalLoad!.textContent = stats.totalWatts.toFixed(0);
+    els.usableEnergy!.textContent = stats.usableWh.toFixed(0);
+    els.recommended!.textContent = stats.recommendedVa.toFixed(0);
+    els.runtime!.textContent = formatRuntime(stats.runtimeMinutes);
+    els.runtimeBig!.textContent = runtimeValue.value;
+    els.runtimeUnit!.textContent = runtimeValue.unit;
+    els.summary!.textContent = `${config.summaryPrefix} ${band} ${stats.recommendedVa.toFixed(0)} ${config.vaUnit} / ${stats.recommendedWatts.toFixed(0)} ${config.wattsUnit}.`;
+  }
+
+  function updateMeters(stats: RuntimeStats) {
+    const runtimeFill = clampFill(stats.runtimeMinutes * 2, 6);
+    const loadFill = clampFill(stats.totalWatts / 8, 8);
+    const vaFill = clampFill(stats.recommendedVa / 12, 8);
+    const energyFill = clampFill(stats.usableWh / 8, 8);
+    root?.style.setProperty('--ups-fill', `${runtimeFill}%`);
+    root?.style.setProperty('--ups-load-fill', `${loadFill}%`);
+    els.loadBar!.style.width = `${loadFill}%`;
+    els.loadMeter!.style.setProperty('--meter-fill', `${loadFill}%`);
+    els.runtimeMeter!.style.setProperty('--meter-fill', `${runtimeFill}%`);
+    els.vaMeter!.style.setProperty('--meter-fill', `${vaFill}%`);
+    els.energyMeter!.style.setProperty('--meter-fill', `${energyFill}%`);
+  }
+
+  function clampFill(value: number, min: number) {
+    return Math.max(min, Math.min(100, value));
+  }
+
+  function readNumber(input: HTMLInputElement | null | undefined, fallback: number) {
+    return input ? Number(input.value) : fallback;
+  }
+
+  function getRuntimeValue(minutes: number) {
+    if (minutes >= 60) {
+      return { value: (minutes / 60).toFixed(1), unit: config.hours };
+    }
+    return { value: minutes.toFixed(0), unit: config.minutes };
+  }
+
+  function getBandText(minutes: number) {
+    if (minutes >= 30) {
+      return config.bandLight;
+    }
+    if (minutes >= 12) {
+      return config.bandBalanced;
+    }
+    return config.bandHeavy;
+  }
+
+  function formatRuntime(minutes: number): string {
+    if (minutes >= 60) return `${(minutes / 60).toFixed(1)} ${config.hours}`;
+    return `${minutes.toFixed(0)} ${config.minutes}`;
+  }
+
+  function renderDevices() {
+    els.devices!.innerHTML = '';
+    devices.forEach((device, index) => els.devices!.append(createDeviceRow(device, index)));
+  }
+
+  function createDeviceRow(device: Device, index: number) {
+    const row = document.createElement('div');
+    const nameInput = createNameInput(device, index);
+    const wattsInput = createWattsInput(device, index);
+    row.className = 'ups-device';
+    row.append(nameInput, createWattsLabel(wattsInput), createRemoveButton(index));
+    return row;
+  }
+
+  function createNameInput(device: Device, index: number) {
+    const input = document.createElement('input');
+    input.type = 'text';
+    input.className = 'ups-device-name';
+    input.ariaLabel = config.deviceName;
+    input.value = device.name;
+    input.addEventListener('input', () => {
+      devices[index]!.name = input.value;
+      saveState();
+    });
+    return input;
+  }
+
+  function createWattsInput(device: Device, index: number) {
+    const input = document.createElement('input');
+    input.type = 'number';
+    input.min = '0';
+    input.max = '2000';
+    input.step = '5';
+    input.value = String(device.watts);
+    input.addEventListener('input', () => {
+      devices[index]!.watts = Number(input.value);
+      calculate();
+    });
+    return input;
+  }
+
+  function createWattsLabel(input: HTMLInputElement) {
+    const label = document.createElement('label');
+    const text = document.createElement('span');
+    const field = document.createElement('span');
+    const unit = document.createElement('em');
+    text.textContent = config.watts;
+    field.className = 'ups-number-field';
+    unit.textContent = config.wattsUnit;
+    field.append(input, unit);
+    label.append(text, field);
+    return label;
+  }
+
+  function createRemoveButton(index: number) {
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.ariaLabel = config.remove;
+    appendTrashIcon(button);
+    button.addEventListener('click', () => {
+      devices.splice(index, 1);
+      renderDevices();
+      calculate();
+    });
+    return button;
+  }
+
+  function appendTrashIcon(button: HTMLButtonElement) {
+    if (els.trashIcon?.content) button.append(els.trashIcon.content.cloneNode(true));
+  }
+
+  els.add?.addEventListener('click', () => {
+    devices.push({ name: config.deviceName, watts: 25 });
+    renderDevices();
+    calculate();
+  });
+  [els.battery, els.efficiency, els.powerFactor, els.reserve].forEach((input) => input?.addEventListener('input', calculate));
+
+  renderDevices();
+  calculate();
+</script>

package/src/tool/upsRuntimeCalculator/entry.ts

@@ -0,0 +1,29 @@
+import type { HardwareToolEntry, ToolLocaleContent } from '../../types';
+import type { UpsRuntimeCalculatorUI } from './ui';
+
+export type UpsRuntimeCalculatorLocaleContent = ToolLocaleContent<UpsRuntimeCalculatorUI>;
+
+export const upsRuntimeCalculator: HardwareToolEntry<UpsRuntimeCalculatorUI> = {
+  id: 'ups-runtime-calculator',
+  icons: {
+    bg: 'mdi:battery-clock',
+    fg: 'mdi:power-plug-battery',
+  },
+  i18n: {
+    de: () => import('./i18n/de').then((m) => m.content),
+    en: () => import('./i18n/en').then((m) => m.content),
+    es: () => import('./i18n/es').then((m) => m.content),
+    fr: () => import('./i18n/fr').then((m) => m.content),
+    id: () => import('./i18n/id').then((m) => m.content),
+    it: () => import('./i18n/it').then((m) => m.content),
+    ja: () => import('./i18n/ja').then((m) => m.content),
+    ko: () => import('./i18n/ko').then((m) => m.content),
+    nl: () => import('./i18n/nl').then((m) => m.content),
+    pl: () => import('./i18n/pl').then((m) => m.content),
+    pt: () => import('./i18n/pt').then((m) => m.content),
+    ru: () => import('./i18n/ru').then((m) => m.content),
+    sv: () => import('./i18n/sv').then((m) => m.content),
+    tr: () => import('./i18n/tr').then((m) => m.content),
+    zh: () => import('./i18n/zh').then((m) => m.content),
+  },
+};