@jjlmoya/utils-aquarium 1.60.0 → 1.61.0

package/src/tool/aquariumEvaporationTopOffPlanner/i18n/zh.ts

@@ -0,0 +1,3 @@
+import { localizedContents } from './translations';
+
+export const content = localizedContents.zh;

package/src/tool/aquariumEvaporationTopOffPlanner/index.ts

@@ -0,0 +1,11 @@
+import { aquariumEvaporationTopOffPlanner } from './entry';
+import type { ToolDefinition } from '../../types';
+
+export * from './entry';
+
+export const AQUARIUM_EVAPORATION_TOP_OFF_PLANNER_TOOL: ToolDefinition = {
+  entry: aquariumEvaporationTopOffPlanner,
+  Component: () => import('./component.astro'),
+  SEOComponent: () => import('./seo.astro'),
+  BibliographyComponent: () => import('./bibliography.astro'),
+};

package/src/tool/aquariumEvaporationTopOffPlanner/logic.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+import { calculateEvaporation } from './logic';
+
+describe('calculateEvaporation', () => {
+  it('converts an observed loss into daily and scheduled top off volumes', () => {
+    const result = calculateEvaporation({
+      tankVolumeLitres: 120,
+      measuredLossMillilitres: 1200,
+      observationDays: 7,
+      refillIntervalDays: 3,
+    });
+    expect(result?.dailyLossLitres).toBeCloseTo(0.1714286, 6);
+    expect(result?.nextRefillLitres).toBeCloseTo(0.5142857, 6);
+    expect(result?.thirtyDayLossLitres).toBeCloseTo(5.142857, 5);
+    expect(result?.levelAfterIntervalPercent).toBeCloseTo(99.5714286, 6);
+  });
+
+  it('shows the level before refill and the amount added on refill days', () => {
+    const result = calculateEvaporation({
+      tankVolumeLitres: 100,
+      measuredLossMillilitres: 700,
+      observationDays: 7,
+      refillIntervalDays: 2,
+    });
+    expect(result).not.toBeNull();
+    if (result === null) return;
+    expect(result.schedule[1]?.levelPercent).toBeCloseTo(99.9, 6);
+    expect(result.schedule[2]?.levelPercent).toBeCloseTo(99.8, 6);
+    expect(result.schedule[2]?.refillLitres).toBeCloseTo(0.2, 6);
+    expect(result.schedule[3]?.levelPercent).toBeCloseTo(99.9, 6);
+  });
+
+  it('estimates reservoir autonomy, marine concentration and critical swings', () => {
+    const result = calculateEvaporation({
+      tankVolumeLitres: 100,
+      measuredLossMillilitres: 3000,
+      observationDays: 10,
+      refillIntervalDays: 10,
+      reservoirCapacityLitres: 12,
+      startingSpecificGravity: 1.025,
+    });
+    expect(result?.reservoirDays).toBeCloseTo(40, 6);
+    expect(result?.salinityAfterInterval).toBeCloseTo(1.025773, 6);
+    expect(result?.isCritical).toBe(true);
+  });
+
+  it('rejects impossible or unsupported values', () => {
+    expect(calculateEvaporation({
+      tankVolumeLitres: 0,
+      measuredLossMillilitres: 500,
+      observationDays: 7,
+      refillIntervalDays: 3,
+    })).toBeNull();
+    expect(calculateEvaporation({
+      tankVolumeLitres: 100,
+      measuredLossMillilitres: 500,
+      observationDays: 91,
+      refillIntervalDays: 3,
+    })).toBeNull();
+  });
+});

package/src/tool/aquariumEvaporationTopOffPlanner/logic.ts

@@ -0,0 +1,102 @@
+export interface EvaporationInputs {
+  tankVolumeLitres: number;
+  measuredLossMillilitres: number;
+  observationDays: number;
+  refillIntervalDays: number;
+  reservoirCapacityLitres?: number;
+  startingSpecificGravity?: number;
+}
+
+export interface SchedulePoint {
+  day: number;
+  levelPercent: number;
+  lostLitres: number;
+  refillLitres: number;
+}
+
+export interface EvaporationResult {
+  tankVolumeLitres: number;
+  dailyLossLitres: number;
+  dailyRatePercent: number;
+  nextRefillLitres: number;
+  thirtyDayLossLitres: number;
+  levelAfterIntervalPercent: number;
+  twoPercentDays: number;
+  reservoirDays?: number;
+  salinityAfterInterval?: number;
+  isCritical: boolean;
+  schedule: SchedulePoint[];
+}
+
+function isPositive(value: number): boolean {
+  return Number.isFinite(value) && value > 0;
+}
+
+function validLimits(input: EvaporationInputs): boolean {
+  return input.observationDays <= 90 && input.refillIntervalDays <= 30;
+}
+
+function validOptionalFields(input: EvaporationInputs): boolean {
+  const validReservoir = input.reservoirCapacityLitres === undefined || isPositive(input.reservoirCapacityLitres);
+  const validSalinity = input.startingSpecificGravity === undefined || (input.startingSpecificGravity >= 1 && input.startingSpecificGravity <= 1.04);
+  return validReservoir && validSalinity;
+}
+
+function isValidInput(input: EvaporationInputs): boolean {
+  return isPositive(input.tankVolumeLitres)
+    && isPositive(input.measuredLossMillilitres)
+    && isPositive(input.observationDays)
+    && isPositive(input.refillIntervalDays)
+    && validLimits(input)
+    && validOptionalFields(input);
+}
+
+function daysSinceRefill(day: number, intervalDays: number): number {
+  if (day === 0) return 0;
+  const remainder = day % intervalDays;
+  return remainder === 0 ? intervalDays : remainder;
+}
+
+function createSchedule(
+  dailyLossLitres: number,
+  tankVolumeLitres: number,
+  intervalDays: number,
+): SchedulePoint[] {
+  const schedule: SchedulePoint[] = [];
+  for (let day = 0; day <= 14; day += 1) {
+    const daySinceRefill = daysSinceRefill(day, intervalDays);
+    const refillDue = day > 0 && day % intervalDays === 0;
+    const lostLitres = daySinceRefill * dailyLossLitres;
+    schedule.push({
+      day,
+      levelPercent: Math.max(0, 100 - (lostLitres / tankVolumeLitres) * 100),
+      lostLitres,
+      refillLitres: refillDue ? intervalDays * dailyLossLitres : 0,
+    });
+  }
+  return schedule;
+}
+
+export function calculateEvaporation(input: EvaporationInputs): EvaporationResult | null {
+  if (!isValidInput(input)) return null;
+  const dailyLossLitres = input.measuredLossMillilitres / 1000 / input.observationDays;
+  const dailyRatePercent = (dailyLossLitres / input.tankVolumeLitres) * 100;
+  const nextRefillLitres = dailyLossLitres * input.refillIntervalDays;
+  const remainingVolumeLitres = input.tankVolumeLitres - nextRefillLitres;
+  const result: EvaporationResult = {
+    tankVolumeLitres: input.tankVolumeLitres,
+    dailyLossLitres,
+    dailyRatePercent,
+    nextRefillLitres,
+    thirtyDayLossLitres: dailyLossLitres * 30,
+    levelAfterIntervalPercent: Math.max(0, 100 - dailyRatePercent * input.refillIntervalDays),
+    twoPercentDays: 2 / dailyRatePercent,
+    isCritical: dailyRatePercent * input.refillIntervalDays >= 2,
+    schedule: createSchedule(dailyLossLitres, input.tankVolumeLitres, input.refillIntervalDays),
+  };
+  if (input.reservoirCapacityLitres !== undefined) result.reservoirDays = input.reservoirCapacityLitres / dailyLossLitres;
+  if (input.startingSpecificGravity !== undefined && remainingVolumeLitres > 0) {
+    result.salinityAfterInterval = 1 + ((input.startingSpecificGravity - 1) * input.tankVolumeLitres) / remainingVolumeLitres;
+  }
+  return result;
+}

package/src/tool/aquariumEvaporationTopOffPlanner/seo.astro

@@ -0,0 +1,13 @@
+---
+import { SEORenderer } from '@jjlmoya/utils-shared';
+import { aquariumEvaporationTopOffPlanner } from './entry';
+import type { KnownLocale } from '../../types';
+
+interface Props { locale?: KnownLocale; }
+
+const { locale = 'en' } = Astro.props;
+const loader = aquariumEvaporationTopOffPlanner.i18n[locale] ?? aquariumEvaporationTopOffPlanner.i18n.en;
+const content = loader === undefined ? undefined : await loader();
+---
+
+{content && <SEORenderer content={{ locale, sections: content.seo }} />}

package/src/tool/aquariumEvaporationTopOffPlanner/storage.ts

@@ -0,0 +1,28 @@
+import type { EvaporationInputs } from './logic';
+
+const STORAGE_KEY = 'aquarium-evaporation-top-off-planner';
+
+export interface StoredEvaporationState {
+  units: 'metric' | 'imperial';
+  lossUnit?: 'millilitres' | 'litres' | 'fluidOunces';
+  waterType?: 'freshwater' | 'marine';
+  input: EvaporationInputs;
+}
+
+export function readEvaporationState(): StoredEvaporationState | null {
+  if (typeof window === 'undefined') return null;
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (raw === null) return null;
+    return JSON.parse(raw) as StoredEvaporationState;
+  } catch {
+    return null;
+  }
+}
+
+export function writeEvaporationState(state: StoredEvaporationState): void {
+  if (typeof window === 'undefined') return;
+  try {
+    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+  } catch {}
+}

package/src/tool/aquariumEvaporationTopOffPlanner/ui.ts

@@ -0,0 +1,49 @@
+export interface AquariumEvaporationTopOffPlannerUI {
+  [key: string]: string;
+  unitsLabel: string;
+  metricLabel: string;
+  imperialLabel: string;
+  tankVolumeLabel: string;
+  measuredLossLabel: string;
+  lossUnitLabel: string;
+  observationDaysLabel: string;
+  refillIntervalLabel: string;
+  reservoirCapacityLabel: string;
+  advancedLabel: string;
+  waterTypeLabel: string;
+  freshwaterLabel: string;
+  marineLabel: string;
+  startingSalinityLabel: string;
+  estimatedSalinityLabel: string;
+  reservoirDaysLabel: string;
+  criticalAlert: string;
+  volumeHint: string;
+  lossHint: string;
+  intervalHint: string;
+  resultTitle: string;
+  dailyLossLabel: string;
+  dailyRateLabel: string;
+  nextRefillLabel: string;
+  thirtyDayLabel: string;
+  levelAfterIntervalLabel: string;
+  twoPercentDaysLabel: string;
+  scheduleTitle: string;
+  dayLabel: string;
+  topOffLabel: string;
+  everyLabel: string;
+  levelLabel: string;
+  stableStatus: string;
+  watchStatus: string;
+  frequentStatus: string;
+  emptyState: string;
+  invalidState: string;
+  measurementNote: string;
+  saltwaterNote: string;
+  resetLabel: string;
+  litreUnit: string;
+  gallonUnit: string;
+  millilitreUnit: string;
+  fluidOunceUnit: string;
+  dayUnit: string;
+  percentUnit: string;
+}

package/src/tool/aquariumLightingPhotoperiodPlanner/i18n/zh.ts

@@ -67,7 +67,7 @@ const softwareApplicationSchema: WithContext<SoftwareApplication> = {
   name: '水族箱灯光光照周期规划器',
   applicationCategory: 'UtilitiesApplication',
   operatingSystem: 'Web',
-  description: '根据水族箱类型、水草需求及调光功能，计算并规划水族灯自动定时时间表。',
+  description: '根据水族箱类型、水草需求及调光功能，计算并规划水族灯自动定时时间表，方便日常维护和安排。',
   offers: { '@type': 'Offer', price: '0', priceCurrency: 'CNY' },
 };
 
@@ -87,7 +87,7 @@ const howToSchema: WithContext<HowTo> = {
 export const content: AquariumLightingPhotoperiodPlannerLocaleContent = {
   slug: 'aquarium-lighting-photoperiod-schedule-planner',
   title: '水族箱灯光与光照周期（Photoperiod）规划器',
-  description: '结合水族箱类型、水草环境、开灯时间及调光渐变，制定稳定高效的水族箱定时开灯时间表。',
+  description: '结合水族箱类型、水草环境、开灯时间及调光渐变，制定稳定高效的水族箱定时开灯时间表，帮助安排日常养护。',
   ui,
   seo: [
     { type: 'title', level: 2, text: '为什么规律的光照周期至关重要' },

package/src/tool/aquariumTankVolumeWaterChangeCalculator/i18n/fr.ts

@@ -4,7 +4,7 @@ export const content = createAquariumContent({
   locale: 'fr',
   slug: 'calculateur-volume-aquarium-changement-eau',
   title: "Calculateur du volume d'aquarium et du changement d'eau",
-  description: "Calculez le volume d'eau utile, le déplacement du substrat et la quantité d'eau à remplacer à partir des dimensions intérieures de votre aquarium.",
+  description: "Calculez le volume d'eau utile, le déplacement du substrat et la quantité d'eau à remplacer à partir des dimensions intérieures de votre aquarium pour planifier l'entretien.",
   faq: [
     { question: "Le calculateur utilise-t-il la capacité indiquée sur l'aquarium ?", answer: "Non. Il retire la hauteur du substrat du volume géométrique et fournit une estimation de l'eau réellement disponible." },
     { question: "Comment fonctionne l'option façade bombée ?", answer: "Elle ajoute un segment circulaire approximatif à une base rectangulaire. Le résultat reste indicatif, car les profils de verre varient selon les aquariums." },

package/src/tool/aquariumTankVolumeWaterChangeCalculator/i18n/it.ts

@@ -4,7 +4,7 @@ export const content = createAquariumContent({
   locale: 'it',
   slug: 'calcolatore-volume-acquario-cambio-acqua',
   title: "Calcolatore del volume dell'acquario e del cambio d'acqua",
-  description: "Calcola il volume d'acqua utile, lo spazio occupato dal substrato e la quantità da sostituire usando le misure interne del tuo acquario.",
+  description: "Calcola il volume d'acqua utile, lo spazio occupato dal substrato e la quantità da sostituire usando le misure interne del tuo acquario per pianificare la manutenzione.",
   faq: [
     { question: "Il calcolatore usa la capacità indicata sulla confezione?", answer: "No. Sottrae l'altezza del substrato dal volume geometrico e fornisce una stima dell'acqua effettivamente disponibile." },
     { question: "Come funziona l'opzione con fronte curvo?", answer: "Aggiunge un segmento circolare approssimato alla base rettangolare. Il risultato è indicativo perché i profili del vetro curvo cambiano da una vasca all'altra." },

package/src/tools.ts

@@ -2,6 +2,7 @@ export { ALL_ENTRIES } from './entries';
 import { aquariumTankVolumeWaterChangeCalculator } from './tool/aquariumTankVolumeWaterChangeCalculator/entry';
 import { aquariumFilterTurnoverStockingPlanner } from './tool/aquariumFilterTurnoverStockingPlanner/entry';
 import { aquariumLightingPhotoperiodPlanner } from './tool/aquariumLightingPhotoperiodPlanner/entry';
+import { aquariumEvaporationTopOffPlanner } from './tool/aquariumEvaporationTopOffPlanner/entry';
 
 export const ALL_TOOLS = [{
   entry: aquariumTankVolumeWaterChangeCalculator,
@@ -18,4 +19,9 @@ export const ALL_TOOLS = [{
   Component: () => import('./tool/aquariumLightingPhotoperiodPlanner/component.astro'),
   SEOComponent: () => import('./tool/aquariumLightingPhotoperiodPlanner/seo.astro'),
   BibliographyComponent: () => import('./tool/aquariumLightingPhotoperiodPlanner/bibliography.astro'),
+}, {
+  entry: aquariumEvaporationTopOffPlanner,
+  Component: () => import('./tool/aquariumEvaporationTopOffPlanner/component.astro'),
+  SEOComponent: () => import('./tool/aquariumEvaporationTopOffPlanner/seo.astro'),
+  BibliographyComponent: () => import('./tool/aquariumEvaporationTopOffPlanner/bibliography.astro'),
 }];