@jjlmoya/utils-aquarium 1.57.0 → 1.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jjlmoya/utils-aquarium",
-    "version": "1.57.0",
+    "version": "1.59.0",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",

package/src/category/index.ts

@@ -1,9 +1,11 @@
 import type { AquariumCategoryEntry } from '../types';
 import { aquariumTankVolumeWaterChangeCalculator } from '../tool/aquariumTankVolumeWaterChangeCalculator/entry';
+import { aquariumFilterTurnoverStockingPlanner } from '../tool/aquariumFilterTurnoverStockingPlanner/entry';
+import { aquariumLightingPhotoperiodPlanner } from '../tool/aquariumLightingPhotoperiodPlanner/entry';
 
 export const aquariumCategory: AquariumCategoryEntry = {
   icon: 'mdi:fishbowl-outline',
-  tools: [aquariumTankVolumeWaterChangeCalculator],
+  tools: [aquariumTankVolumeWaterChangeCalculator, aquariumFilterTurnoverStockingPlanner, aquariumLightingPhotoperiodPlanner],
   i18n: {
     en: () => import('./i18n/en').then((m) => m.content),
     es: () => import('./i18n/es').then((m) => m.content),

package/src/entries.ts

@@ -1,7 +1,13 @@
 export { aquariumTankVolumeWaterChangeCalculator } from './tool/aquariumTankVolumeWaterChangeCalculator/entry';
 export type { AquariumTankVolumeWaterChangeCalculatorLocaleContent } from './tool/aquariumTankVolumeWaterChangeCalculator/entry';
+export { aquariumFilterTurnoverStockingPlanner } from './tool/aquariumFilterTurnoverStockingPlanner/entry';
+export type { AquariumFilterTurnoverStockingPlannerLocaleContent } from './tool/aquariumFilterTurnoverStockingPlanner/entry';
+export { aquariumLightingPhotoperiodPlanner } from './tool/aquariumLightingPhotoperiodPlanner/entry';
+export type { AquariumLightingPhotoperiodPlannerLocaleContent } from './tool/aquariumLightingPhotoperiodPlanner/entry';
 export { aquariumCategory } from './category';
 
 import { aquariumTankVolumeWaterChangeCalculator } from './tool/aquariumTankVolumeWaterChangeCalculator/entry';
+import { aquariumFilterTurnoverStockingPlanner } from './tool/aquariumFilterTurnoverStockingPlanner/entry';
+import { aquariumLightingPhotoperiodPlanner } from './tool/aquariumLightingPhotoperiodPlanner/entry';
 
-export const ALL_ENTRIES = [aquariumTankVolumeWaterChangeCalculator];
+export const ALL_ENTRIES = [aquariumTankVolumeWaterChangeCalculator, aquariumFilterTurnoverStockingPlanner, aquariumLightingPhotoperiodPlanner];

package/src/index.ts

@@ -18,3 +18,5 @@ export type {
 export { ALL_ENTRIES, ALL_TOOLS } from './tools';
 export { AQUARIUM_TANK_VOLUME_WATER_CHANGE_CALCULATOR_TOOL, aquariumTankVolumeWaterChangeCalculator } from './tool/aquariumTankVolumeWaterChangeCalculator/index';
 export type { AquariumTankVolumeWaterChangeCalculatorUI, AquariumTankVolumeWaterChangeCalculatorLocaleContent } from './tool/aquariumTankVolumeWaterChangeCalculator/index';
+export { AQUARIUM_FILTER_TURNOVER_STOCKING_PLANNER_TOOL, aquariumFilterTurnoverStockingPlanner } from './tool/aquariumFilterTurnoverStockingPlanner/index';
+export type { AquariumFilterTurnoverStockingPlannerUI, AquariumFilterTurnoverStockingPlannerLocaleContent } from './tool/aquariumFilterTurnoverStockingPlanner/index';

package/src/layouts/PreviewLayout.astro

@@ -82,6 +82,8 @@ const { title, currentLocale = "es", localeUrls = {}, hasSidebar = false } = Ast
 
   main {
     padding: 0 2rem;
+    min-width: 0;
+    width: 100%;
   }
 
   .page-wrapper {
@@ -112,6 +114,17 @@ const { title, currentLocale = "es", localeUrls = {}, hasSidebar = false } = Ast
     .sidebar-area {
       display: none;
     }
+
+    :global(.utility-header-title),
+    :global(.utility-header-title > *) {
+      max-width: 100%;
+      min-width: 0;
+      overflow-wrap: anywhere;
+    }
+
+    main {
+      overflow-x: hidden;
+      padding: 0 1rem;
+    }
   }
 </style>
-

package/src/tests/i18n_coverage.test.ts

@@ -2,12 +2,14 @@ import { describe, expect, it } from 'vitest';
 import { ALL_TOOLS } from '../tools';
 
 const EXPECTED_LOCALES = ['de', 'en', 'es', 'fr', 'id', 'it', 'ja', 'ko', 'nl', 'pl', 'pt', 'ru', 'sv', 'tr', 'zh'];
+const ENGLISH_FIRST_TOOL_IDS = new Set<string>([]);
 
 describe('I18n Coverage Validation', () => {
   ALL_TOOLS.forEach(({ entry }) => {
     describe('Tool: ' + entry.id, () => {
       it('has the current phase locale set', () => {
-        expect(Object.keys(entry.i18n)).toEqual(EXPECTED_LOCALES);
+        const expectedLocales = ENGLISH_FIRST_TOOL_IDS.has(entry.id) ? ['en'] : EXPECTED_LOCALES;
+        expect(Object.keys(entry.i18n)).toEqual(expectedLocales);
       });
     });
   });

package/src/tests/tool_validation.test.ts

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

package/src/tool/aquariumFilterTurnoverStockingPlanner/aquarium-filter-turnover-stocking-planner.css

@@ -0,0 +1,404 @@
+:root {
+  --n-ink: #10272a;
+  --n-muted: #4d6a6c;
+  --n-paper: #f5fbf8;
+  --n-card: #fff;
+  --n-line: #c7ded8;
+  --n-water: #0f7f83;
+  --n-water-soft: #cbeeed;
+  --n-coral: #bd553c;
+  --n-gold: #b27a25;
+  --n-shadow: rgba(16, 39, 42, .12);
+}
+
+.theme-dark {
+  --n-ink: #effbf8;
+  --n-muted: #b3cbc5;
+  --n-paper: #101c1d;
+  --n-card: #192829;
+  --n-line: #3b5e5d;
+  --n-water: #56d2ca;
+  --n-water-soft: #1e4e50;
+  --n-coral: #f08b6f;
+  --n-gold: #e8ba59;
+  --n-shadow: rgba(0, 0, 0, .3);
+}
+
+.aquarium-filter-planner {
+  --n-ink: #10272a;
+  --n-muted: #4d6a6c;
+  --n-paper: #f5fbf8;
+  --n-card: #fff;
+  --n-line: #c7ded8;
+  --n-water: #0f7f83;
+  --n-water-soft: #cbeeed;
+  --n-coral: #bd553c;
+  --n-gold: #b27a25;
+  --n-shadow: rgba(16, 39, 42, .12);
+
+  box-sizing: border-box;
+  color: var(--n-ink);
+  background: var(--n-paper);
+  border: 1px solid var(--n-line);
+  border-radius: 24px;
+  box-shadow: 0 18px 42px var(--n-shadow);
+  overflow: hidden;
+  min-width: 0;
+  width: 100%;
+  max-width: 100%;
+}
+
+.theme-dark .aquarium-filter-planner {
+  --n-ink: #effbf8;
+  --n-muted: #b3cbc5;
+  --n-paper: #101c1d;
+  --n-card: #192829;
+  --n-line: #3b5e5d;
+  --n-water: #56d2ca;
+  --n-water-soft: #1e4e50;
+  --n-coral: #f08b6f;
+  --n-gold: #e8ba59;
+  --n-shadow: rgba(0, 0, 0, .3);
+}
+
+.planner-main {
+  display: grid;
+  grid-template-columns: minmax(250px, .8fr) minmax(320px, 1.2fr);
+  gap: 0;
+  min-width: 0;
+}
+
+.planner-controls,
+.planner-result {
+  min-width: 0;
+  padding: 2rem;
+}
+
+.planner-controls {
+  border-right: 1px solid var(--n-line);
+}
+
+.preset-label,
+.result-eyebrow,
+.field-label,
+.visual-caption {
+  color: var(--n-muted);
+  font-size: .72rem;
+  font-weight: 800;
+  letter-spacing: .12em;
+  text-transform: uppercase;
+}
+
+.preset-label,
+.result-eyebrow {
+  margin: 0 0 .8rem;
+}
+
+.preset-row,
+.setup-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: .5rem;
+}
+
+.preset-button,
+.setup-button {
+  border: 1px solid var(--n-line);
+  border-radius: 999px;
+  color: var(--n-ink);
+  background: var(--n-card);
+  cursor: pointer;
+  font: inherit;
+  font-size: .82rem;
+  padding: .65rem .85rem;
+}
+
+.preset-button:hover,
+.preset-button:focus-visible,
+.setup-button:hover,
+.setup-button:focus-visible,
+.setup-button.is-active {
+  border-color: var(--n-water);
+  color: var(--n-water);
+  outline: 3px solid var(--n-water-soft);
+}
+
+.field-stack {
+  display: grid;
+  gap: 1.15rem;
+  margin-top: 2rem;
+}
+
+.field {
+  display: grid;
+  gap: .45rem;
+}
+
+.field-label {
+  color: var(--n-ink);
+  letter-spacing: .04em;
+}
+
+.field-hint {
+  color: var(--n-muted);
+  font-size: .78rem;
+  line-height: 1.45;
+}
+
+.field input[type='number'] {
+  width: 100%;
+  box-sizing: border-box;
+  border: 1px solid var(--n-line);
+  border-radius: 12px;
+  color: var(--n-ink);
+  background: var(--n-card);
+  font: inherit;
+  font-size: 1.05rem;
+  min-height: 3rem;
+  padding: .7rem .8rem;
+}
+
+.field input:focus-visible {
+  border-color: var(--n-water);
+  outline: 3px solid var(--n-water-soft);
+}
+
+.range-wrap {
+  display: grid;
+  grid-template-columns: 1fr auto;
+  align-items: center;
+  gap: .8rem;
+}
+
+.field input[type='range'] {
+  accent-color: var(--n-water);
+  width: 100%;
+}
+
+.range-value {
+  color: var(--n-water);
+  font-weight: 800;
+  min-width: 3.3rem;
+  text-align: right;
+}
+
+.setup-button[aria-pressed='true'] {
+  background: var(--n-water-soft);
+}
+
+.result-hero {
+  display: flex;
+  align-items: flex-end;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.result-hero h2 {
+  font-size: clamp(2.5rem, 7vw, 5.5rem);
+  letter-spacing: -.08em;
+  line-height: .9;
+  margin: 0;
+}
+
+.result-status {
+  border: 1px solid var(--n-line);
+  border-radius: 999px;
+  color: var(--n-water);
+  font-size: .78rem;
+  font-weight: 800;
+  padding: .5rem .75rem;
+  text-align: center;
+}
+
+[data-status='under'] .result-status {
+  color: var(--n-coral);
+}
+
+[data-status='high'] .result-status {
+  color: var(--n-gold);
+}
+
+.tank-scene {
+  background: var(--n-card);
+  border: 1px solid var(--n-line);
+  border-radius: 18px;
+  margin-top: 1.8rem;
+  padding: .5rem;
+}
+
+.tank-scene svg {
+  display: block;
+  height: auto;
+  max-width: 100%;
+  min-width: 0;
+  width: 100%;
+}
+
+.tank-frame {
+  fill: var(--n-card);
+  stroke: var(--n-ink);
+  stroke-width: 2;
+}
+
+.tank-water {
+  fill: var(--n-water-soft);
+}
+
+.filter-body {
+  fill: var(--n-ink);
+}
+
+.pipe,
+.flow-line {
+  fill: none;
+  stroke: var(--n-water);
+  stroke-linecap: round;
+  stroke-width: 5;
+}
+
+.flow-line {
+  stroke-width: calc(2px + var(--n-current) * 4px);
+  stroke-dasharray: 8 11;
+  animation: current-drift 2.4s linear infinite;
+}
+
+.water-label,
+.filter-label {
+  fill: var(--n-ink);
+  font-size: 9px;
+  font-weight: 800;
+  letter-spacing: .08em;
+  text-transform: uppercase;
+}
+
+.filter-label {
+  fill: var(--n-card);
+}
+
+.bubble {
+  fill: var(--n-coral);
+}
+
+.metrics {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: .7rem;
+  margin-top: 1rem;
+}
+
+.metric {
+  border-top: 2px solid var(--n-line);
+  padding-top: .75rem;
+}
+
+.metric-label {
+  color: var(--n-muted);
+  display: block;
+  font-size: .75rem;
+  line-height: 1.3;
+}
+
+.metric-value {
+  display: block;
+  font-size: 1rem;
+  font-weight: 800;
+  margin-top: .3rem;
+}
+
+.turnover-gauge {
+  margin-top: 1.5rem;
+}
+
+.gauge-head {
+  align-items: baseline;
+  display: flex;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.gauge-head strong {
+  font-size: .95rem;
+}
+
+.gauge-track {
+  background: var(--n-water-soft);
+  border-radius: 999px;
+  height: .75rem;
+  margin-top: .55rem;
+  overflow: hidden;
+}
+
+.gauge-progress {
+  background: var(--n-water);
+  border-radius: inherit;
+  height: 100%;
+  transition: width .25s ease;
+  width: var(--n-progress, 4%);
+}
+
+.load-line,
+.caution {
+  border-left: 3px solid var(--n-water);
+  margin-top: 1.25rem;
+  padding-left: .85rem;
+}
+
+.load-line {
+  color: var(--n-muted);
+  font-size: .86rem;
+}
+
+.load-line strong {
+  color: var(--n-ink);
+}
+
+.caution {
+  border-left-color: var(--n-coral);
+}
+
+.caution h3 {
+  font-size: .9rem;
+  margin: 0 0 .3rem;
+}
+
+.caution p {
+  color: var(--n-muted);
+  font-size: .83rem;
+  line-height: 1.5;
+  margin: 0;
+}
+
+@keyframes current-drift {
+  to { stroke-dashoffset: -38; }
+}
+
+@media (max-width: 760px) {
+  .aquarium-filter-planner {
+    max-width: 100%;
+    width: 100%;
+  }
+
+  .planner-main {
+    grid-template-columns: 1fr;
+  }
+
+  .planner-controls {
+    border-bottom: 1px solid var(--n-line);
+    border-right: 0;
+  }
+
+  .planner-controls,
+  .planner-result {
+    padding: 1.25rem;
+  }
+
+  .result-hero {
+    align-items: flex-start;
+    flex-direction: column;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .flow-line { animation: none; }
+  .gauge-progress { transition: none; }
+}

package/src/tool/aquariumFilterTurnoverStockingPlanner/bibliography.astro

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

package/src/tool/aquariumFilterTurnoverStockingPlanner/bibliography.ts

@@ -0,0 +1,16 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliography: BibliographyEntry[] = [
+  {
+    name: 'Fluval, 06 Series Filter Manual: turnover rates and flow rates',
+    url: 'https://fluvalaquatics.com/manuals/Fluval_A202-A207-A212-A217_06-Filter-Series_Manual_NA.pdf',
+  },
+  {
+    name: 'OATA, How to set up and look after a freshwater tank or aquarium',
+    url: 'https://ornamentalfish.org/what-we-do/advice-information/care-sheets/caresheets-tropical-freshwater-fish/how-to-set-up-and-look-after-a-freshwater-tank-aquarium/',
+  },
+  {
+    name: 'Deutscher Tierschutzbund, Die Haltung von Aquarienfischen',
+    url: 'https://www.tierschutzbund.de/fileadmin/Seiten/tierschutzbund.de/Downloads/Broschueren/Broschuere_Aquarienfische_Haltung.pdf',
+  },
+];

package/src/tool/aquariumFilterTurnoverStockingPlanner/component.astro

@@ -0,0 +1,140 @@
+---
+import type { AquariumFilterTurnoverStockingPlannerUI } from './ui';
+import './aquarium-filter-turnover-stocking-planner.css';
+
+interface Props {
+  ui: AquariumFilterTurnoverStockingPlannerUI;
+}
+
+const { ui } = Astro.props;
+---
+
+<div class="aquarium-filter-planner" data-aquarium-filter-planner>
+  <div class="planner-main">
+    <section class="planner-controls" aria-label="Aquarium filter inputs">
+      <p class="preset-label">{ui.presetsLabel}</p>
+      <div class="preset-row">
+        <button class="preset-button" type="button" data-preset="community">{ui.presetCommunity}</button>
+        <button class="preset-button" type="button" data-preset="planted">{ui.presetPlanted}</button>
+        <button class="preset-button" type="button" data-preset="highWaste">{ui.presetHighWaste}</button>
+      </div>
+
+      <div class="field-stack">
+        <label class="field">
+          <span class="field-label">{ui.tankVolumeLabel}</span>
+          <input name="tankVolumeLiters" type="number" min="10" max="2000" step="1" value="100" inputmode="decimal" />
+          <span class="field-hint">{ui.tankVolumeHint}</span>
+        </label>
+
+        <label class="field">
+          <span class="field-label">{ui.ratedFlowLabel}</span>
+          <input name="ratedFlowLitersPerHour" type="number" min="50" max="20000" step="10" value="600" inputmode="decimal" />
+          <span class="field-hint">{ui.ratedFlowHint}</span>
+        </label>
+
+        <label class="field">
+          <span class="field-label">{ui.flowLossLabel}</span>
+          <span class="range-wrap">
+            <input name="flowLossPercent" type="range" min="0" max="90" step="5" value="25" />
+            <output id="aquarium-filter-flow-loss-value" class="range-value">25%</output>
+          </span>
+          <span class="field-hint">{ui.flowLossHint}</span>
+        </label>
+
+        <label class="field">
+          <span class="field-label">{ui.fishCountLabel}</span>
+          <input name="fishCount" type="number" min="0" max="200" step="1" value="10" inputmode="numeric" />
+        </label>
+
+        <label class="field">
+          <span class="field-label">{ui.averageLengthLabel}</span>
+          <input name="averageAdultLengthCm" type="number" min="0" max="80" step="0.5" value="5" inputmode="decimal" />
+        </label>
+
+        <div class="field">
+          <span class="field-label">{ui.setupLabel}</span>
+          <div class="setup-row" role="group" aria-label={ui.setupLabel}>
+            <button class="setup-button" type="button" data-setup="community" aria-pressed="false">{ui.setupCommunity}</button>
+            <button class="setup-button" type="button" data-setup="planted" aria-pressed="false">{ui.setupPlanted}</button>
+            <button class="setup-button" type="button" data-setup="highWaste" aria-pressed="false">{ui.setupHighWaste}</button>
+          </div>
+        </div>
+      </div>
+    </section>
+
+    <section class="planner-result" aria-live="polite">
+      <div class="result-hero">
+        <div>
+          <p class="result-eyebrow">{ui.resultEyebrow}</p>
+          <h2 id="aquarium-filter-effective-turnover">4.5×</h2>
+        </div>
+        <div id="aquarium-filter-status" class="result-status">{ui.statusTarget}</div>
+      </div>
+
+      <div class="tank-scene">
+        <svg viewBox="0 0 620 250" role="img" aria-labelledby="aquarium-filter-scene-title aquarium-filter-scene-desc">
+          <title id="aquarium-filter-scene-title">{ui.currentTitle}</title>
+          <desc id="aquarium-filter-scene-desc">{ui.currentDescription}</desc>
+          <rect class="tank-frame" x="48" y="28" width="440" height="188" rx="10" />
+          <rect class="tank-water" x="50" y="92" width="436" height="122" rx="8" />
+          <rect class="filter-body" x="514" y="72" width="66" height="110" rx="10" />
+          <path class="pipe" d="M514 96 H480 V62 H370" />
+          <path class="pipe" d="M514 160 H472 V194 H140" />
+          <path id="aquarium-filter-current-ribbon" class="flow-line" d="M372 62 C310 84 260 82 190 106 C130 126 112 160 154 184 C204 213 284 192 362 194" />
+          <circle class="bubble" cx="102" cy="75" r="5" />
+          <circle class="bubble" cx="125" cy="58" r="3" />
+          <circle class="bubble" cx="145" cy="78" r="2" />
+          <text class="water-label" x="70" y="112">AQUARIUM CURRENT</text>
+          <text class="filter-label" x="525" y="121">FILTER</text>
+          <text class="filter-label" x="525" y="136">OUTPUT</text>
+        </svg>
+      </div>
+
+      <div class="metrics">
+        <div class="metric">
+          <span class="metric-label">{ui.targetLabel}</span>
+          <strong id="aquarium-filter-target" class="metric-value">4.0 to 6.0×</strong>
+        </div>
+        <div class="metric">
+          <span class="metric-label">{ui.effectiveFlowLabel}</span>
+          <strong id="aquarium-filter-effective-flow" class="metric-value">450 L/h</strong>
+        </div>
+        <div class="metric">
+          <span class="metric-label">{ui.stockingProxyLabel}</span>
+          <strong id="aquarium-filter-stock-proxy" class="metric-value">0.50 cm/L</strong>
+        </div>
+      </div>
+
+      <div class="turnover-gauge">
+        <div class="gauge-head">
+          <span class="visual-caption">{ui.currentTitle}</span>
+          <strong id="aquarium-filter-load-badge">{ui.loadLight}</strong>
+        </div>
+        <div class="gauge-track" aria-hidden="true"><div id="aquarium-filter-turnover-progress" class="gauge-progress"></div></div>
+      </div>
+
+      <div class="load-line">
+        <strong id="aquarium-filter-gap">{ui.bandSignalInside}</strong>
+      </div>
+
+      <div class="caution">
+        <h3>{ui.cautionTitle}</h3>
+        <p>{ui.maintenanceText}</p>
+        <p>{ui.useTestKits}</p>
+      </div>
+    </section>
+  </div>
+</div>
+
+<script is:inline type="application/json" id="aquarium-filter-planner-ui" set:html={JSON.stringify(ui)}></script>
+<script>
+  import { initPlanner } from './controller';
+  import type { AquariumFilterTurnoverStockingPlannerUI } from './ui';
+
+  const root = document.querySelector<HTMLElement>('[data-aquarium-filter-planner]');
+  const uiElement = document.querySelector<HTMLScriptElement>('#aquarium-filter-planner-ui');
+  if (root && uiElement) {
+    const ui = JSON.parse(uiElement.textContent ?? '{}') as AquariumFilterTurnoverStockingPlannerUI;
+    initPlanner(root, ui);
+  }
+</script>