@jjlmoya/utils-aquarium 1.60.0 → 1.62.0

package/src/tests/mfe_manifest.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { createUtilityManifestResponse } from "../mfe/manifest";
+
+describe("MFE utility manifest", () => {
+    it("returns a versioned installable manifest for the current utility", async () => {
+        const response = createUtilityManifestResponse({
+            title: "Card draw odds calculator",
+            description: "Calculate card draw probabilities.",
+            startUrl: "/en/utilities/categories/aquarium/card-draw-odds-calculator/",
+            englishSlug: "card-draw-odds-calculator",
+        });
+        const manifest = await response.json() as {
+            name: string;
+            start_url: string;
+            scope: string;
+            icons: { src: string; sizes: string; type: string; purpose: string }[];
+        };
+
+        expect(response.headers.get("Content-Type")).toContain("application/manifest+json");
+        expect(response.headers.get("Cache-Control")).toContain("immutable");
+        expect(manifest.name).toBe("Card draw odds calculator");
+        expect(manifest.start_url).toBe(manifest.scope);
+        expect(manifest.icons[0]?.src).toContain("/_utilities/aquarium/images/card-draw-odds-calculator.webp?version=");
+        expect(manifest.icons[0]?.sizes).toBe("512x512");
+        expect(manifest.icons[0]?.type).toBe("image/webp");
+        expect(manifest.icons[0]?.purpose).toBe("any");
+    });
+});

package/src/tests/registry_contract.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { pathToFileURL } from 'url';
+import { ALL_ENTRIES } from '../entries';
+import { ALL_TOOLS } from '../tools';
+import type { ToolDefinition } from '../types';
+
+function isToolDefinition(value: unknown): value is ToolDefinition {
+  if (!value || typeof value !== 'object') return false;
+
+  const candidate = value as Record<string, unknown>;
+  return Boolean(
+    candidate.entry &&
+      typeof candidate.entry === 'object' &&
+      typeof candidate.Component === 'function' &&
+      typeof candidate.SEOComponent === 'function' &&
+      typeof candidate.BibliographyComponent === 'function',
+  );
+}
+
+const toolRoot = join(process.cwd(), 'src', 'tool');
+const toolDirectories = readdirSync(toolRoot, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory() && existsSync(join(toolRoot, entry.name, 'index.ts')))
+  .map((entry) => entry.name)
+  .sort();
+
+describe('Library registry contract', () => {
+  it('keeps ALL_ENTRIES and ALL_TOOLS synchronized by id', () => {
+    const entryIds = ALL_ENTRIES.map((entry) => entry.id);
+    const toolIds = ALL_TOOLS.map((tool) => tool.entry.id);
+
+    expect(new Set(entryIds).size).toBe(entryIds.length);
+    expect(new Set(toolIds).size).toBe(toolIds.length);
+    expect([...toolIds].sort()).toEqual([...entryIds].sort());
+  });
+
+  it('registers every tool runtime index in both public registries', async () => {
+    const failures: string[] = [];
+
+    for (const directory of toolDirectories) {
+      const runtimeModule = await import(
+        pathToFileURL(join(toolRoot, directory, 'index.ts')).href,
+      );
+      const definitions = [...new Set(Object.values(runtimeModule).filter(isToolDefinition))];
+
+      if (definitions.length !== 1) {
+        failures.push(`${directory}: expected exactly one ToolDefinition export, found ${definitions.length}`);
+        continue;
+      }
+
+      const [definition] = definitions;
+      if (!definition) {
+        failures.push(`${directory}: runtime definition is undefined`);
+        continue;
+      }
+      if (!ALL_TOOLS.some((tool) => tool.entry.id === definition.entry.id)) {
+        failures.push(`${directory}: runtime definition is missing from ALL_TOOLS`);
+      }
+      if (!ALL_ENTRIES.some((entry) => entry.id === definition.entry.id)) {
+        failures.push(`${directory}: runtime entry is missing from ALL_ENTRIES`);
+      }
+    }
+
+    expect(failures).toEqual([]);
+  });
+});

package/src/tests/tool_validation.test.ts

@@ -3,13 +3,14 @@ import { ALL_TOOLS } from '../tools';
 import { aquariumCategory } from '../data';
 
 describe('Tool Validation Suite', () => {
-  it('registers exactly three aquarium production tools', () => {
-    expect(ALL_TOOLS.length).toBe(3);
-    expect(aquariumCategory.tools).toHaveLength(3);
+  it('registers exactly four aquarium production tools', () => {
+    expect(ALL_TOOLS.length).toBe(4);
+    expect(aquariumCategory.tools).toHaveLength(4);
     expect(aquariumCategory.tools.map((tool) => tool.id)).toEqual([
       'aquarium-tank-volume-water-change-calculator',
       'aquarium-filter-turnover-stocking-planner',
       'aquarium-lighting-photoperiod-schedule-planner',
+      'aquarium-evaporation-top-off-planner',
     ]);
   });
 });

package/src/tool/aquariumEvaporationTopOffPlanner/aquarium-evaporation-top-off-planner.css

@@ -0,0 +1,490 @@
+.n-evaporation {
+  --n-paper: #eef5f2;
+  --n-panel: #fff;
+  --n-ink: #12383a;
+  --n-muted: #607979;
+  --n-line: #c8dcda;
+  --n-teal: #147d79;
+  --n-teal-dark: #0b5655;
+  --n-water: #56b9b5;
+  --n-sand: #e7b75e;
+  --n-loss: #f3dfbb;
+  --n-good: #dcefe5;
+  --n-alert: #9a5d12;
+  --n-shadow: rgba(19, 62, 62, 0.12);
+
+  display: grid;
+  grid-template-columns: minmax(320px, 0.95fr) minmax(360px, 1.05fr);
+  max-width: 1080px;
+  margin: 0 auto;
+  overflow: hidden;
+  color: var(--n-ink);
+  background: var(--n-paper);
+  border: 1px solid var(--n-line);
+  border-radius: 24px;
+  box-shadow: 0 14px 36px var(--n-shadow);
+}
+
+.theme-dark .n-evaporation {
+  --n-paper: #111b1c;
+  --n-panel: #1c292a;
+  --n-ink: #edf5f2;
+  --n-muted: #afc7c4;
+  --n-line: #355355;
+  --n-teal: #72d4cb;
+  --n-teal-dark: #a2e9e0;
+  --n-water: #318e93;
+  --n-sand: #edc66c;
+  --n-loss: #493c29;
+  --n-good: #234239;
+  --n-alert: #f2bf68;
+  --n-shadow: rgba(0, 0, 0, 0.34);
+}
+
+.n-evaporation *,
+.n-evaporation *::before,
+.n-evaporation *::after {
+  box-sizing: border-box;
+}
+
+.n-evaporation h2,
+.n-evaporation h3,
+.n-evaporation p {
+  margin: 0;
+}
+
+.n-output,
+.n-controls {
+  min-width: 0;
+  align-self: start;
+  padding: clamp(22px, 3vw, 34px);
+}
+
+.n-controls {
+  background: var(--n-panel);
+  border-right: 1px solid var(--n-line);
+  grid-column: 1;
+  grid-row: 1;
+}
+
+.n-output {
+  grid-column: 2;
+  grid-row: 1;
+}
+
+.n-output-head,
+.n-controls-head,
+.n-schedule-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+}
+
+.n-main-result {
+  display: grid;
+  gap: 4px;
+  max-width: 420px;
+  color: var(--n-ink);
+  letter-spacing: -0.04em;
+  line-height: 1;
+}
+
+.n-answer-label {
+  display: block;
+  color: var(--n-muted);
+  font-size: 0.72rem;
+  font-weight: 800;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+.n-main-result strong {
+  color: var(--n-teal-dark);
+  font-size: clamp(2.25rem, 4vw, 3.25rem);
+  font-weight: 850;
+}
+
+.n-main-result span {
+  color: var(--n-ink);
+  font-size: clamp(1rem, 2vw, 1.35rem);
+  font-weight: 750;
+  letter-spacing: -0.02em;
+}
+
+.n-status {
+  flex: 0 0 auto;
+  width: 11px;
+  height: 11px;
+  overflow: hidden;
+  color: transparent;
+  background: var(--n-teal);
+  border-radius: 50%;
+}
+
+.n-scene {
+  margin-top: 22px;
+  padding: 8px;
+  background: var(--n-panel);
+  border: 1px solid var(--n-line);
+  border-radius: 18px;
+}
+
+.n-evaporation-scene {
+  display: block;
+  width: 100%;
+  height: 220px;
+}
+
+.n-tank-frame {
+  fill: var(--n-panel);
+  stroke: var(--n-teal-dark);
+  stroke-width: 3;
+}
+
+.n-water {
+  fill: var(--n-water);
+}
+
+.n-loss-zone {
+  fill: var(--n-loss);
+  opacity: 0.78;
+}
+
+.n-waterline,
+.n-mark {
+  fill: none;
+  stroke: var(--n-sand);
+  stroke-width: 3;
+}
+
+.n-mark-label,
+.n-scene-label,
+.n-scene-caption {
+  fill: var(--n-muted);
+  text-anchor: middle;
+}
+
+.n-mark-label {
+  font-size: 13px;
+  text-anchor: end;
+}
+
+.n-scene-label {
+  fill: var(--n-teal-dark);
+  font-size: 21px;
+  font-weight: 850;
+}
+
+.n-scene-caption {
+  font-size: 13px;
+}
+
+.n-stat-grid {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 1px;
+  margin-top: 18px;
+  overflow: hidden;
+  background: var(--n-line);
+  border: 1px solid var(--n-line);
+  border-radius: 12px;
+}
+
+.n-stat {
+  display: grid;
+  min-height: 70px;
+  gap: 6px;
+  padding: 12px;
+  background: var(--n-panel);
+}
+
+.n-stat-feature {
+  background: var(--n-good);
+}
+
+.n-stat span,
+.n-schedule-head span {
+  color: var(--n-muted);
+  font-size: 0.68rem;
+}
+
+.n-stat strong {
+  align-self: end;
+  color: var(--n-ink);
+  font-size: 1rem;
+  line-height: 1;
+}
+
+.n-stat-feature strong {
+  color: var(--n-teal-dark);
+  font-size: 1.12rem;
+}
+
+.n-alert {
+  margin-top: 12px;
+  padding: 10px 12px;
+  color: var(--n-alert);
+  background: var(--n-loss);
+  border: 1px solid var(--n-sand);
+  border-radius: 9px;
+  font-size: 0.72rem;
+  font-weight: 750;
+  line-height: 1.35;
+}
+
+.n-alert[hidden],
+.n-field[hidden],
+.n-mini-toggle button[hidden] {
+  display: none;
+}
+
+.n-schedule-head {
+  align-items: baseline;
+  margin-top: 22px;
+  padding-bottom: 9px;
+  border-bottom: 1px solid var(--n-line);
+}
+
+.n-schedule-head h3,
+.n-controls-head h2 {
+  color: var(--n-ink);
+  font-size: 0.92rem;
+}
+
+.n-calendar {
+  display: grid;
+  grid-template-columns: repeat(7, minmax(0, 1fr));
+  gap: 5px;
+  margin-top: 11px;
+}
+
+.n-calendar-item {
+  display: grid;
+  min-height: 48px;
+  gap: 4px;
+  padding: 7px 6px;
+  color: var(--n-muted);
+  background: var(--n-panel);
+  border: 1px solid var(--n-line);
+  border-radius: 8px;
+  font-size: 0.68rem;
+}
+
+.n-calendar-item span {
+  color: var(--n-ink);
+  font-weight: 850;
+}
+
+.n-calendar-item small {
+  font-size: 0.61rem;
+}
+
+.n-calendar-item strong {
+  color: var(--n-teal-dark);
+  font-size: 0.61rem;
+}
+
+.n-calendar-item.is-refill {
+  background: var(--n-good);
+  border-color: var(--n-teal);
+}
+
+.n-controls-head {
+  padding-bottom: 20px;
+  border-bottom: 1px solid var(--n-line);
+}
+
+.n-unit-toggle {
+  display: flex;
+  flex: 0 0 auto;
+  padding: 3px;
+  background: var(--n-paper);
+  border: 1px solid var(--n-line);
+  border-radius: 9px;
+}
+
+.n-unit-toggle button {
+  padding: 7px 8px;
+  color: var(--n-muted);
+  background: transparent;
+  border: 0;
+  border-radius: 6px;
+  cursor: pointer;
+  font: inherit;
+  font-size: 0.67rem;
+  font-weight: 800;
+}
+
+.n-unit-toggle button.is-active,
+.n-unit-toggle button:hover {
+  color: var(--n-teal-dark);
+  background: var(--n-good);
+}
+
+.n-fields {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 18px 12px;
+  padding-top: 22px;
+}
+
+.n-field {
+  display: grid;
+  gap: 8px;
+}
+
+.n-field-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 7px;
+}
+
+.n-field-head label,
+.n-water-type > span {
+  color: var(--n-ink);
+  font-size: 0.72rem;
+  font-weight: 800;
+  line-height: 1.2;
+}
+
+.n-field > span {
+  color: var(--n-ink);
+  font-size: 0.72rem;
+  font-weight: 800;
+  line-height: 1.2;
+}
+
+.n-field small {
+  color: var(--n-muted);
+  font-size: 0.65rem;
+  font-weight: 600;
+}
+
+.n-field input {
+  width: 100%;
+  min-height: 43px;
+  padding: 8px 10px;
+  color: var(--n-ink);
+  background: var(--n-paper);
+  border: 1px solid var(--n-line);
+  border-radius: 8px;
+  font: inherit;
+  font-size: 0.86rem;
+}
+
+.n-mini-toggle {
+  display: inline-flex;
+  flex: 0 0 auto;
+  padding: 2px;
+  background: var(--n-paper);
+  border: 1px solid var(--n-line);
+  border-radius: 7px;
+}
+
+.n-mini-toggle button {
+  padding: 4px 5px;
+  color: var(--n-muted);
+  background: transparent;
+  border: 0;
+  border-radius: 5px;
+  cursor: pointer;
+  font: inherit;
+  font-size: 0.59rem;
+  font-weight: 800;
+}
+
+.n-mini-toggle button.is-active,
+.n-mini-toggle button:hover {
+  color: var(--n-teal-dark);
+  background: var(--n-good);
+}
+
+.n-advanced {
+  margin-top: 22px;
+  padding-top: 17px;
+  border-top: 1px solid var(--n-line);
+}
+
+.n-advanced summary {
+  color: var(--n-teal-dark);
+  cursor: pointer;
+  font-size: 0.72rem;
+  font-weight: 850;
+}
+
+.n-advanced-grid {
+  display: grid;
+  gap: 18px;
+  padding-top: 17px;
+}
+
+.n-water-type {
+  display: grid;
+  gap: 8px;
+}
+
+.n-unit-toggle button:focus-visible,
+.n-field input:focus-visible {
+  outline: 3px solid var(--n-sand);
+  outline-offset: 3px;
+}
+
+@media (max-width: 760px) {
+  .n-evaporation {
+    grid-template-columns: 1fr;
+  }
+
+  .n-output,
+  .n-controls {
+    grid-column: 1;
+    grid-row: auto;
+  }
+
+  .n-controls {
+    order: 1;
+    border-top: 1px solid var(--n-line);
+    border-left: 0;
+    border-right: 0;
+  }
+
+  .n-output {
+    order: 2;
+  }
+
+}
+
+@media (max-width: 480px) {
+  .n-output,
+  .n-controls {
+    padding: 20px 16px;
+  }
+
+  .n-output-head,
+  .n-controls-head {
+    align-items: flex-start;
+    flex-direction: column;
+  }
+
+  .n-status {
+    display: none;
+  }
+
+  .n-stat {
+    min-height: 66px;
+    padding: 9px;
+  }
+
+  .n-stat-grid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .n-calendar {
+    gap: 4px;
+  }
+
+  .n-calendar-item {
+    padding: 6px 4px;
+  }
+}

package/src/tool/aquariumEvaporationTopOffPlanner/bibliography.astro

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

package/src/tool/aquariumEvaporationTopOffPlanner/bibliography.ts

@@ -0,0 +1,10 @@
+export const bibliography = [
+  {
+    name: 'FAO, Generalidades sobre las necesidades de agua para un estanque piscícola',
+    url: 'https://www.fao.org/fishery/static/FAO_Training/FAO_Training/General/x6705s/x6705s01.htm',
+  },
+  {
+    name: 'University of Florida IFAS, Marine Aquarium Project Book',
+    url: 'https://ask.ifas.ufl.edu/publication/4H433',
+  },
+];

package/src/tool/aquariumEvaporationTopOffPlanner/component.astro

@@ -0,0 +1,61 @@
+---
+import type { AquariumEvaporationTopOffPlannerUI } from './ui';
+import './aquarium-evaporation-top-off-planner.css';
+
+interface Props { ui: AquariumEvaporationTopOffPlannerUI; }
+
+const { ui } = Astro.props;
+---
+
+<div class="n-evaporation" data-tool-root data-ui={JSON.stringify(ui)}>
+  <section class="n-output" aria-labelledby="n-evaporation-results">
+    <div class="n-output-head">
+      <div class="n-answer">
+        <span class="n-answer-label">{ui.topOffLabel}</span>
+        <h2 id="n-evaporation-results" class="n-main-result"><strong data-output="main-amount">—</strong><span data-output="main-frequency">{ui.emptyState}</span></h2>
+      </div>
+      <span class="n-status" data-output="status">{ui.stableStatus}</span>
+    </div>
+
+    <div class="n-scene" data-output="scene" aria-live="polite"></div>
+
+    <div class="n-stat-grid" aria-live="polite">
+      <div class="n-stat n-stat-feature"><span>{ui.nextRefillLabel}</span><strong data-output="next-refill">—</strong></div>
+      <div class="n-stat"><span>{ui.dailyLossLabel}</span><strong data-output="daily-loss">—</strong></div>
+      <div class="n-stat"><span>{ui.levelAfterIntervalLabel}</span><strong data-output="level-after">—</strong></div>
+      <div class="n-stat"><span>{ui.reservoirDaysLabel}</span><strong data-output="reservoir-days">—</strong></div>
+      <div class="n-stat" data-salinity-result hidden><span>{ui.estimatedSalinityLabel}</span><strong data-output="salinity">—</strong></div>
+    </div>
+    <p class="n-alert" data-output="alert" role="status" hidden></p>
+  </section>
+
+  <section class="n-controls" aria-labelledby="n-evaporation-inputs">
+    <div class="n-controls-head">
+      <h2 id="n-evaporation-inputs">{ui.unitsLabel}</h2>
+      <div class="n-unit-toggle" role="group" aria-label={ui.unitsLabel}>
+        <button type="button" data-unit-choice="metric" class="is-active" aria-pressed="true">{ui.metricLabel}</button>
+        <button type="button" data-unit-choice="imperial" aria-pressed="false">{ui.imperialLabel}</button>
+      </div>
+    </div>
+
+    <div class="n-fields">
+      <label class="n-field"><span>{ui.tankVolumeLabel} <small data-unit="tank">{ui.litreUnit}</small></span><input data-field="tankVolume" type="number" min="0.1" max="100000" step="0.1" inputmode="decimal" /></label>
+      <div class="n-field"><div class="n-field-head"><label for="n-evaporation-loss">{ui.measuredLossLabel} <small data-unit="loss">{ui.millilitreUnit}</small></label><div class="n-mini-toggle" role="group" aria-label={ui.lossUnitLabel}><button type="button" data-loss-unit-choice="millilitres" class="is-active" aria-pressed="true">{ui.millilitreUnit}</button><button type="button" data-loss-unit-choice="litres" aria-pressed="false">{ui.litreUnit}</button><button type="button" data-loss-unit-choice="fluidOunces" aria-pressed="false">{ui.fluidOunceUnit}</button></div></div><input id="n-evaporation-loss" data-field="measuredLoss" type="number" min="0.1" max="100000" step="0.1" inputmode="decimal" /></div>
+      <label class="n-field"><span>{ui.observationDaysLabel} <small>{ui.dayUnit}</small></span><input data-field="observationDays" type="number" min="1" max="90" step="1" inputmode="numeric" /></label>
+      <label class="n-field"><span>{ui.refillIntervalLabel} <small>{ui.dayUnit}</small></span><input data-field="refillIntervalDays" type="number" min="1" max="30" step="1" inputmode="numeric" /></label>
+    </div>
+
+    <details class="n-advanced"><summary>{ui.advancedLabel}</summary><div class="n-advanced-grid"><label class="n-field"><span>{ui.reservoirCapacityLabel} <small data-unit="reservoir">{ui.litreUnit}</small></span><input data-field="reservoirCapacity" type="number" min="0.1" max="100000" step="0.1" inputmode="decimal" /></label><div class="n-water-type"><span>{ui.waterTypeLabel}</span><div class="n-mini-toggle" role="group" aria-label={ui.waterTypeLabel}><button type="button" data-water-type-choice="freshwater" class="is-active" aria-pressed="true">{ui.freshwaterLabel}</button><button type="button" data-water-type-choice="marine" aria-pressed="false">{ui.marineLabel}</button></div></div><label class="n-field" data-marine-field hidden><span>{ui.startingSalinityLabel} <small>SG</small></span><input data-field="startingSpecificGravity" type="number" min="1" max="1.04" step="0.001" inputmode="decimal" /></label></div></details>
+    <div class="n-schedule-head"><h3>{ui.scheduleTitle}</h3><span>{ui.levelLabel}</span></div>
+    <div class="n-calendar" data-output="schedule" role="list" aria-label={ui.scheduleTitle}></div>
+  </section>
+</div>
+
+<script>
+  import { startEvaporationController } from './controller';
+
+  const root = document.querySelector<HTMLElement>('[data-tool-root]');
+  if (root?.dataset.ui) {
+    startEvaporationController({ root, ui: JSON.parse(root.dataset.ui) });
+  }
+</script>