@jjlmoya/utils-aquarium 1.58.0 → 1.59.0

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

@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+import {
+  calculateSchedule,
+  DEFAULT_INPUT,
+  formatHours,
+  getLightingBand,
+  getLightWindow,
+  PRESETS,
+} from "./logic";
+
+describe("aquarium lighting photoperiod planner logic", () => {
+  it("calculates a planted schedule with transitions and seven days", () => {
+    const result = calculateSchedule(DEFAULT_INPUT);
+
+    expect(result.status).toBe("inside");
+    expect(result.band).toEqual({ low: 7, high: 9 });
+    expect(result.photoperiodMinutes).toBe(480);
+    expect(result.fullIntensityMinutes).toBe(420);
+    expect(result.phases.map((phase) => phase.phase)).toEqual([
+      "ramp-up",
+      "full",
+      "ramp-down",
+      "dark",
+    ]);
+    expect(result.phases[0]).toMatchObject({
+      startTime: "08:00",
+      endTime: "08:30",
+      duration: 30,
+    });
+    expect(result.phases[3]).toMatchObject({
+      startTime: "16:00",
+      endTime: "08:00",
+      duration: 960,
+    });
+    expect(result.days).toHaveLength(7);
+    expect(result.days[6]?.label).toBe("sunday");
+    expect(getLightWindow(result)).toEqual({
+      startTime: "08:00",
+      endTime: "16:00",
+    });
+  });
+
+  it("supports schedules that cross midnight and removes zero length transitions", () => {
+    const result = calculateSchedule({
+      ...DEFAULT_INPUT,
+      startTime: "20:45",
+      photoperiodHours: 6,
+      rampUpMinutes: 0,
+      rampDownMinutes: 0,
+    });
+
+    expect(result.status).toBe("below");
+    expect(result.differenceHours).toBe(1);
+    expect(result.phases.map((phase) => phase.phase)).toEqual(["full", "dark"]);
+    expect(result.phases[0]).toMatchObject({
+      startTime: "20:45",
+      endTime: "02:45",
+      duration: 360,
+    });
+  });
+
+  it("caps long transitions so a light cycle always leaves a dark period", () => {
+    const result = calculateSchedule({
+      ...DEFAULT_INPUT,
+      photoperiodHours: 6,
+      rampUpMinutes: 180,
+      rampDownMinutes: 180,
+    });
+
+    expect(result.input.rampUpMinutes).toBe(165);
+    expect(result.input.rampDownMinutes).toBe(165);
+    expect(result.fullIntensityMinutes).toBe(30);
+    expect(result.status).toBe("below");
+  });
+
+  it("falls back safely when persisted enum values are invalid", () => {
+    const result = calculateSchedule({
+      ...DEFAULT_INPUT,
+      aquariumType: "invalid" as "tropical",
+      plantProfile: "invalid" as "low",
+    });
+
+    expect(result.input.aquariumType).toBe("tropical");
+    expect(result.input.plantProfile).toBe("low");
+  });
+
+  it("reports above-band and inside-band combinations", () => {
+    const above = calculateSchedule({
+      ...DEFAULT_INPUT,
+      ...PRESETS.marine,
+      photoperiodHours: 12,
+    });
+    const inside = calculateSchedule({
+      ...DEFAULT_INPUT,
+      ...PRESETS.marine,
+      photoperiodHours: 8,
+    });
+
+    expect(above.status).toBe("above");
+    expect(above.differenceHours).toBe(4);
+    expect(inside.status).toBe("inside");
+    expect(inside.differenceHours).toBe(0);
+  });
+
+  it("merges aquarium and plant profile bands", () => {
+    expect(
+      getLightingBand({ aquariumType: "coldwater", plantProfile: "high" }),
+    ).toEqual({ low: 8, high: 8 });
+    expect(
+      getLightingBand({ aquariumType: "marine", plantProfile: "none" }),
+    ).toEqual({ low: 8, high: 8 });
+    expect(formatHours(8)).toBe("8");
+    expect(formatHours(8.5)).toBe("8.5");
+  });
+});

package/src/tool/aquariumLightingPhotoperiodPlanner/logic.ts

@@ -0,0 +1,248 @@
+export type AquariumType = "tropical" | "coldwater" | "marine";
+export type PlantProfile = "none" | "low" | "high";
+export type SchedulePhase = "dark" | "ramp-up" | "full" | "ramp-down";
+export type ScheduleStatus = "below" | "inside" | "above";
+
+export interface LightingInput {
+  aquariumType: AquariumType;
+  plantProfile: PlantProfile;
+  startTime: string;
+  photoperiodHours: number;
+  rampUpMinutes: number;
+  rampDownMinutes: number;
+}
+
+export interface LightingBand {
+  low: number;
+  high: number;
+}
+export interface PhaseSegment {
+  phase: SchedulePhase;
+  startOffset: number;
+  duration: number;
+  startTime: string;
+  endTime: string;
+}
+export interface DaySchedule {
+  key: string;
+  label: string;
+  phases: PhaseSegment[];
+}
+export interface LightingSchedule {
+  input: LightingInput;
+  band: LightingBand;
+  status: ScheduleStatus;
+  differenceHours: number;
+  photoperiodMinutes: number;
+  fullIntensityMinutes: number;
+  phases: PhaseSegment[];
+  days: DaySchedule[];
+}
+
+const TYPE_BANDS: Record<AquariumType, LightingBand> = {
+  tropical: { low: 7, high: 10 },
+  coldwater: { low: 6, high: 8 },
+  marine: { low: 8, high: 10 },
+};
+
+const PLANT_BANDS: Record<PlantProfile, LightingBand> = {
+  none: { low: 6, high: 8 },
+  low: { low: 7, high: 9 },
+  high: { low: 8, high: 10 },
+};
+
+const DAY_KEYS = [
+  "monday",
+  "tuesday",
+  "wednesday",
+  "thursday",
+  "friday",
+  "saturday",
+  "sunday",
+] as const;
+
+export const DEFAULT_INPUT: LightingInput = {
+  aquariumType: "tropical",
+  plantProfile: "low",
+  startTime: "08:00",
+  photoperiodHours: 8,
+  rampUpMinutes: 30,
+  rampDownMinutes: 30,
+};
+
+export const PRESETS: Record<string, LightingInput> = {
+  tropical: {
+    ...DEFAULT_INPUT,
+    aquariumType: "tropical",
+    plantProfile: "none",
+    photoperiodHours: 7,
+    rampUpMinutes: 15,
+    rampDownMinutes: 15,
+  },
+  planted: { ...DEFAULT_INPUT },
+  marine: {
+    ...DEFAULT_INPUT,
+    aquariumType: "marine",
+    plantProfile: "none",
+    startTime: "10:00",
+    photoperiodHours: 8,
+    rampUpMinutes: 60,
+    rampDownMinutes: 60,
+  },
+};
+
+function clamp(value: number, low: number, high: number): number {
+  return Math.min(Math.max(value, low), high);
+}
+
+function parseClock(value: string): number {
+  const [hourText, minuteText] = value.split(":");
+  const hour = Number(hourText);
+  const minute = Number(minuteText);
+  if (!Number.isFinite(hour) || !Number.isFinite(minute)) return 0;
+  return clamp(Math.round(hour) * 60 + Math.round(minute), 0, 1439);
+}
+
+function formatClock(minutes: number): string {
+  const normalized = ((Math.round(minutes) % 1440) + 1440) % 1440;
+  const hour = Math.floor(normalized / 60)
+    .toString()
+    .padStart(2, "0");
+  const minute = (normalized % 60).toString().padStart(2, "0");
+  return `${hour}:${minute}`;
+}
+
+function normalizeAquariumType(value: string): AquariumType {
+  if (value === "coldwater" || value === "marine") return value;
+  return "tropical";
+}
+
+function normalizePlantProfile(value: string): PlantProfile {
+  if (value === "none" || value === "high") return value;
+  return "low";
+}
+
+function normalizeInput(input: LightingInput): LightingInput {
+  const photoperiodHours = clamp(Number(input.photoperiodHours) || 8, 6, 12);
+  const photoperiodMinutes = Math.round(photoperiodHours * 60);
+  const rampUpMinutes = clamp(Number(input.rampUpMinutes) || 0, 0, 180);
+  const rampDownMinutes = clamp(Number(input.rampDownMinutes) || 0, 0, 180);
+  const availableTransition = Math.max(0, photoperiodMinutes - 30);
+  const totalTransitions = rampUpMinutes + rampDownMinutes;
+  const scale =
+    totalTransitions > availableTransition && totalTransitions > 0
+      ? availableTransition / totalTransitions
+      : 1;
+  return {
+    aquariumType: normalizeAquariumType(input.aquariumType),
+    plantProfile: normalizePlantProfile(input.plantProfile),
+    startTime: formatClock(parseClock(input.startTime)),
+    photoperiodHours,
+    rampUpMinutes: Math.round(rampUpMinutes * scale),
+    rampDownMinutes: Math.round(rampDownMinutes * scale),
+  };
+}
+
+function mergeBands(
+  typeBand: LightingBand,
+  plantBand: LightingBand,
+): LightingBand {
+  const low = Math.max(typeBand.low, plantBand.low);
+  const high = Math.min(typeBand.high, plantBand.high);
+  return low <= high
+    ? { low, high }
+    : {
+        low: Math.min(typeBand.low, plantBand.low),
+        high: Math.max(typeBand.high, plantBand.high),
+      };
+}
+
+export function getLightingBand(
+  input: Pick<LightingInput, "aquariumType" | "plantProfile">,
+): LightingBand {
+  return mergeBands(
+    TYPE_BANDS[input.aquariumType],
+    PLANT_BANDS[input.plantProfile],
+  );
+}
+
+function getStatus(hours: number, band: LightingBand): ScheduleStatus {
+  if (hours < band.low) return "below";
+  if (hours > band.high) return "above";
+  return "inside";
+}
+
+function getDifference(hours: number, band: LightingBand): number {
+  if (hours < band.low) return band.low - hours;
+  if (hours > band.high) return hours - band.high;
+  return 0;
+}
+
+function makePhase(
+  phase: SchedulePhase,
+  startOffset: number,
+  duration: number,
+  startMinutes: number,
+): PhaseSegment {
+  return {
+    phase,
+    startOffset,
+    duration,
+    startTime: formatClock(startMinutes + startOffset),
+    endTime: formatClock(startMinutes + startOffset + duration),
+  };
+}
+
+function makePhases(input: LightingInput): PhaseSegment[] {
+  const total = input.photoperiodHours * 60;
+  const full = total - input.rampUpMinutes - input.rampDownMinutes;
+  const start = parseClock(input.startTime);
+  return [
+    makePhase("ramp-up", 0, input.rampUpMinutes, start),
+    makePhase("full", input.rampUpMinutes, full, start),
+    makePhase(
+      "ramp-down",
+      input.rampUpMinutes + full,
+      input.rampDownMinutes,
+      start,
+    ),
+    makePhase("dark", total, 1440 - total, start),
+  ].filter((phase) => phase.duration > 0);
+}
+
+function makeDays(phases: PhaseSegment[]): DaySchedule[] {
+  return DAY_KEYS.map((key) => ({ key, label: key, phases }));
+}
+
+export function calculateSchedule(rawInput: LightingInput): LightingSchedule {
+  const input = normalizeInput(rawInput);
+  const band = getLightingBand(input);
+  const phases = makePhases(input);
+  const photoperiodMinutes = Math.round(input.photoperiodHours * 60);
+  return {
+    input,
+    band,
+    status: getStatus(input.photoperiodHours, band),
+    differenceHours: getDifference(input.photoperiodHours, band),
+    photoperiodMinutes,
+    fullIntensityMinutes:
+      photoperiodMinutes - input.rampUpMinutes - input.rampDownMinutes,
+    phases,
+    days: makeDays(phases),
+  };
+}
+
+export function formatHours(value: number): string {
+  return Number.isInteger(value) ? `${value}` : value.toFixed(1);
+}
+
+export function getLightWindow(schedule: Pick<LightingSchedule, "phases">): {
+  startTime: string;
+  endTime: string;
+} {
+  const lightPhases = schedule.phases.filter((phase) => phase.phase !== "dark");
+  return {
+    startTime: lightPhases[0]?.startTime ?? "",
+    endTime: lightPhases[lightPhases.length - 1]?.endTime ?? "",
+  };
+}

package/src/tool/aquariumLightingPhotoperiodPlanner/seo.astro

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

package/src/tool/aquariumLightingPhotoperiodPlanner/storage.ts

@@ -0,0 +1,39 @@
+import type { LightingInput } from "./logic";
+
+const STORAGE_KEY = "jjlmoya-aquarium-lighting-photoperiod-planner";
+
+function isLightingInput(value: unknown): value is LightingInput {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Partial<LightingInput>;
+  return (
+    typeof candidate.aquariumType === "string" &&
+    typeof candidate.plantProfile === "string" &&
+    typeof candidate.startTime === "string" &&
+    typeof candidate.photoperiodHours === "number" &&
+    typeof candidate.rampUpMinutes === "number" &&
+    typeof candidate.rampDownMinutes === "number"
+  );
+}
+
+export function loadInput(): LightingInput | undefined {
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (!raw) return undefined;
+    const parsed: unknown = JSON.parse(raw);
+    return isLightingInput(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function saveInput(input: LightingInput): void {
+  try {
+    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(input));
+  } catch {}
+}
+
+export function clearInput(): void {
+  try {
+    window.localStorage.removeItem(STORAGE_KEY);
+  } catch {}
+}

package/src/tool/aquariumLightingPhotoperiodPlanner/ui.ts

@@ -0,0 +1,44 @@
+export interface AquariumLightingPhotoperiodPlannerUI extends Record<
+  string,
+  string
+> {
+  controlsLabel: string;
+  aquariumTypeLabel: string;
+  aquariumTypeTropical: string;
+  aquariumTypeColdwater: string;
+  aquariumTypeMarine: string;
+  plantProfileLabel: string;
+  plantProfileNone: string;
+  plantProfileLow: string;
+  plantProfileHigh: string;
+  startTimeLabel: string;
+  photoperiodLabel: string;
+  rampUpLabel: string;
+  rampDownLabel: string;
+  optionalRampsLabel: string;
+  optionalRampsSummary: string;
+  hoursUnit: string;
+  minutesUnit: string;
+  statusBelow: string;
+  statusInside: string;
+  statusAbove: string;
+  targetBandLabel: string;
+  lightWindowLabel: string;
+  fullIntensityLabel: string;
+  lightsOnLabel: string;
+  fullLightLabel: string;
+  lightsOffLabel: string;
+  dayNightLabel: string;
+  fullDayLabel: string;
+  dailyRepeatLabel: string;
+  co2Label: string;
+  co2Hint: string;
+  phaseDark: string;
+  phaseRampUp: string;
+  phaseFull: string;
+  phaseRampDown: string;
+  adjustmentBelow: string;
+  adjustmentInside: string;
+  adjustmentAbove: string;
+  limitsText: string;
+}

package/src/tools.ts

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