@jjlmoya/utils-aquarium 1.65.0 → 1.66.0

package/src/tests/qa_logic_reference_coverage.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { basename, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import {
+  displayPath,
+  findFiles,
+  listToolDirectories,
+  read,
+  repositoryRoot,
+} from './qa-test-helpers';
+
+function hasDedicatedLogicTest(toolDirectory: string): boolean {
+  const localCandidates = [
+    join(toolDirectory, 'logic.test.ts'),
+    join(toolDirectory, 'logic.spec.ts'),
+    join(toolDirectory, '__tests__', 'logic.test.ts'),
+    join(toolDirectory, '__tests__', 'logic.spec.ts'),
+  ];
+  if (localCandidates.some(existsSync)) return true;
+
+  const toolName = basename(toolDirectory);
+  const centralTests = findFiles(join(repositoryRoot, 'src', 'tests'), ['.test.ts', '.spec.ts']);
+  return centralTests.some((testPath) => {
+    const source = read(testPath).replace(/\\/g, '/');
+    return source.includes(`/tool/${toolName}/logic`) || source.includes(`../tool/${toolName}/logic`);
+  });
+}
+
+describe('QA: calculation logic has reference tests', () => {
+  it('gives every public calculator logic module its own behavioral test suite', () => {
+    const failures = listToolDirectories()
+      .filter((directory) => existsSync(join(directory, 'logic.ts')))
+      .filter((directory) => !hasDedicatedLogicTest(directory))
+      .map((directory) => `${displayPath(join(directory, 'logic.ts'))} -> no test imports this module`);
+
+    expect(
+      failures,
+      [
+        'Add behavioral tests through each logic module public API.',
+        'At minimum cover a documented reference case, boundaries, invalid input and invariants.',
+        ...failures,
+      ].join('\n'),
+    ).toEqual([]);
+  });
+});
+

package/src/tests/qa_runtime_i18n.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from 'vitest';
+import { basename, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import {
+  displayPath,
+  findFiles,
+  listToolDirectories,
+  read,
+  repositoryRoot,
+} from './qa-test-helpers';
+import { localizedContents } from '../tool/aquariumSaltDosingCalculator/localized-content';
+
+interface VisibleLiteral {
+  line: number;
+  value: string;
+}
+
+const domTextAssignment = /\.(?:innerText|textContent|innerHTML)\s*=/;
+const quotedLiteral = /(['"`])((?:\\.|(?!\1).)*)\1/g;
+
+const knownLegacyUnusedKeys = new Map<string, Set<string>>([
+  [
+    'src/tool/aquariumEvaporationTopOffPlanner/ui.ts',
+    new Set([
+      'volumeHint',
+      'lossHint',
+      'intervalHint',
+      'resultTitle',
+      'dailyRateLabel',
+      'thirtyDayLabel',
+      'twoPercentDaysLabel',
+      'dayLabel',
+      'measurementNote',
+      'saltwaterNote',
+      'resetLabel',
+    ]),
+  ],
+  ['src/tool/aquariumFilterTurnoverStockingPlanner/ui.ts', new Set(['effectiveTurnoverLabel'])],
+  ['src/tool/aquariumLightingPhotoperiodPlanner/ui.ts', new Set(['phaseRampDown'])],
+  ['src/tool/aquariumTankVolumeWaterChangeCalculator/ui.ts', new Set(['resetLabel'])],
+]);
+
+function visibleWords(value: string): string {
+  return value
+    .replace(/\$\{[^}]*\}/g, ' ')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&[a-z]+;/gi, ' ')
+    .replace(/[\d\p{P}\p{S}_]+/gu, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function isTechnicalLiteral(value: string): boolean {
+  return ['.', '#', '['].some((prefix) => value.startsWith(prefix))
+    || /^data-[a-z0-9-]+$/i.test(value);
+}
+
+function hardcodedVisibleLiterals(source: string): VisibleLiteral[] {
+  const failures: VisibleLiteral[] = [];
+
+  source.split(/\r?\n/).forEach((line, index) => {
+    if (!domTextAssignment.test(line)) return;
+
+    const assignment = line.slice(line.search(domTextAssignment));
+    for (const match of assignment.matchAll(quotedLiteral)) {
+      const literal = match[2] ?? '';
+      if (isTechnicalLiteral(literal)) continue;
+      const words = visibleWords(literal);
+      if (words && /\p{L}/u.test(words)) {
+        failures.push({ line: index + 1, value: literal });
+      }
+    }
+  });
+
+  return failures;
+}
+
+function runtimeSources(toolDirectory: string): string {
+  return findFiles(toolDirectory, ['.astro', '.ts', '.js'])
+    .filter((path) => !path.includes(`${join(toolDirectory, 'i18n')}`))
+    .filter((path) => basename(path) !== 'ui.ts')
+    .map(read)
+    .join('\n');
+}
+
+describe('QA: runtime copy is localized', () => {
+  const componentFiles = findFiles(join(repositoryRoot, 'src', 'tool'), ['.astro']);
+
+  it('does not write user-facing string literals directly into the DOM', () => {
+    const failures = componentFiles.flatMap((path) =>
+      hardcodedVisibleLiterals(read(path)).map(
+        ({ line, value }) => `${displayPath(path)}:${line} -> ${JSON.stringify(value)}`,
+      ),
+    );
+
+    expect(
+      failures,
+      `Move visible browser copy to the tool UI locale contract:\n${failures.join('\n')}`,
+    ).toEqual([]);
+  });
+
+  it('uses every string declared by each UI locale contract', () => {
+    const failures: string[] = [];
+
+    for (const directory of listToolDirectories()) {
+      const uiPath = join(directory, 'ui.ts');
+      if (!existsSync(uiPath)) continue;
+
+      const keys = Array.from(read(uiPath).matchAll(/^\s*(\w+)\??:\s*string\s*;/gm), (match) => match[1]).filter(
+        (key): key is string => Boolean(key),
+      );
+      const runtime = runtimeSources(directory);
+      const unused = keys.filter((key) => !new RegExp(`\\b${key}\\b`).test(runtime));
+      const unexpectedUnused = unused.filter(
+        (key) => !knownLegacyUnusedKeys.get(displayPath(uiPath))?.has(key),
+      );
+
+      if (unexpectedUnused.length > 0) {
+        failures.push(`${displayPath(uiPath)} -> unused: ${unexpectedUnused.join(', ')}`);
+      }
+    }
+
+    expect(
+      failures,
+      `Unused locale keys are dead copy or may mean the browser bypasses translations:\n${failures.join('\n')}`,
+    ).toEqual([]);
+  });
+
+  it('keeps validation errors localized for the salt calculator', () => {
+    const englishError = localizedContents.en?.ui.invalidState;
+    const fallbacks = Object.entries(localizedContents)
+      .filter(([locale]) => locale !== 'en')
+      .filter(([, content]) => content.ui.invalidState === englishError)
+      .map(([locale]) => locale);
+
+    expect(fallbacks, `Validation error still falls back to English: ${fallbacks.join(', ')}`).toEqual([]);
+  });
+});

package/src/tests/tool_validation.test.ts

@@ -3,14 +3,15 @@ import { ALL_TOOLS } from '../tools';
 import { aquariumCategory } from '../data';
 
 describe('Tool Validation Suite', () => {
-  it('registers exactly four aquarium production tools', () => {
-    expect(ALL_TOOLS.length).toBe(4);
-    expect(aquariumCategory.tools).toHaveLength(4);
+  it('registers exactly five aquarium production tools', () => {
+    expect(ALL_TOOLS.length).toBe(5);
+    expect(aquariumCategory.tools).toHaveLength(5);
     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',
+      'aquarium-salt-dosing-calculator',
     ]);
   });
 });

package/src/tool/aquariumSaltDosingCalculator/aquarium-salt-dosing-calculator.css

@@ -0,0 +1,503 @@
+:root {
+  --assd-ink: #17343b;
+  --assd-muted: #5f777b;
+  --assd-paper: #f3f8f5;
+  --assd-surface: #fff;
+  --assd-line: #c8dbd5;
+  --assd-water: #23869b;
+  --assd-water-soft: #d7eff0;
+  --assd-salt: #fffdf3;
+  --assd-coral: #e27657;
+  --assd-shadow: #dbe9e3;
+  --assd-error: #a83a35;
+}
+
+.theme-dark {
+  --assd-ink: #edf8f4;
+  --assd-muted: #b4cbc7;
+  --assd-paper: #142b30;
+  --assd-surface: #203c41;
+  --assd-line: #4e6c6e;
+  --assd-water: #72c8d0;
+  --assd-water-soft: #244e57;
+  --assd-salt: #eee8cd;
+  --assd-coral: #f09a78;
+  --assd-shadow: #0e1d20;
+  --assd-error: #ffaaa0;
+}
+
+.assd-root {
+  background:
+    radial-gradient(circle at 88% 8%, color-mix(in srgb, var(--assd-water) 12%, transparent), transparent 31%),
+    linear-gradient(135deg, var(--assd-paper), color-mix(in srgb, var(--assd-water-soft) 28%, var(--assd-paper)));
+  border: 1px solid var(--assd-line);
+  border-radius: 1.75rem;
+  box-shadow: 0 1.5rem 3rem color-mix(in srgb, var(--assd-shadow) 82%, transparent);
+  color: var(--assd-ink);
+  display: grid;
+  gap: clamp(1.25rem, 3vw, 2.5rem);
+  grid-template-columns: minmax(0, 1.04fr) minmax(21rem, .96fr);
+  overflow: hidden;
+  padding: clamp(1rem, 3vw, 2.4rem);
+}
+
+#aquarium-salt-dosing-calculator [hidden] {
+  display: none;
+}
+
+.assd-result,
+.assd-controls {
+  min-width: 0;
+}
+
+.assd-result {
+  background: color-mix(in srgb, var(--assd-surface) 78%, transparent);
+  border: 1px solid var(--assd-line);
+  border-radius: 1.35rem;
+  box-shadow: inset 0 1px 0 color-mix(in srgb, white 20%, transparent);
+  min-height: 100%;
+  padding: clamp(1.1rem, 2.5vw, 1.75rem);
+}
+
+.assd-result-head,
+.assd-unit-row,
+.assd-answer-label {
+  align-items: flex-start;
+  display: flex;
+  gap: .9rem;
+  justify-content: space-between;
+}
+
+.assd-kicker {
+  color: var(--assd-water);
+  font-size: .72rem;
+  font-weight: 900;
+  letter-spacing: .15em;
+  line-height: 1.2;
+  margin: 0 0 .45rem;
+  text-transform: uppercase;
+}
+
+.assd-root h2 {
+  font-size: clamp(1.25rem, 2.2vw, 1.65rem);
+  letter-spacing: -.035em;
+  line-height: 1.05;
+  margin: 0;
+}
+
+.assd-action {
+  align-self: flex-start;
+  background: var(--assd-water-soft);
+  border: 1px solid color-mix(in srgb, var(--assd-water) 30%, transparent);
+  border-radius: 99rem;
+  color: var(--assd-ink);
+  font-size: .76rem;
+  font-weight: 900;
+  line-height: 1.25;
+  max-width: 12rem;
+  padding: .5rem .75rem;
+  text-align: center;
+}
+
+.assd-scene {
+  align-items: end;
+  background: linear-gradient(145deg, color-mix(in srgb, var(--assd-water-soft) 70%, transparent), color-mix(in srgb, var(--assd-surface) 55%, transparent));
+  border: 1px solid color-mix(in srgb, var(--assd-water) 22%, var(--assd-line));
+  border-radius: 1rem;
+  display: flex;
+  height: 13.5rem;
+  justify-content: center;
+  margin: 1.35rem 0 1rem;
+  overflow: hidden;
+  position: relative;
+}
+
+.assd-scene::before,
+.assd-scene::after {
+  border: 1px solid color-mix(in srgb, var(--assd-water) 22%, transparent);
+  border-radius: 50%;
+  content: '';
+  height: 15rem;
+  position: absolute;
+  right: -6rem;
+  top: -9rem;
+  width: 15rem;
+}
+
+.assd-scene::after {
+  height: 7rem;
+  left: -3rem;
+  right: auto;
+  top: auto;
+  width: 7rem;
+}
+
+.assd-water-vessel {
+  background: linear-gradient(180deg, color-mix(in srgb, var(--assd-surface) 60%, transparent), color-mix(in srgb, var(--assd-water-soft) 88%, transparent));
+  border: 3px solid var(--assd-ink);
+  border-radius: 1rem 1rem 2.3rem 2.3rem;
+  bottom: 1.45rem;
+  height: 9.6rem;
+  overflow: hidden;
+  position: absolute;
+  width: min(70%, 18rem);
+}
+
+.assd-water {
+  background: var(--assd-water);
+  bottom: 0;
+  height: 72%;
+  opacity: .72;
+  position: absolute;
+  width: 100%;
+}
+
+.assd-water::before,
+.assd-water::after {
+  border: 2px solid color-mix(in srgb, white 75%, transparent);
+  border-color: color-mix(in srgb, white 75%, transparent) transparent transparent;
+  border-radius: 50%;
+  content: '';
+  height: 3rem;
+  left: 12%;
+  position: absolute;
+  top: .7rem;
+  transform: rotate(-8deg);
+  width: 75%;
+}
+
+.assd-water::after {
+  left: 18%;
+  top: 1.25rem;
+  transform: rotate(7deg);
+}
+
+.assd-salt-cloud {
+  background: var(--assd-salt);
+  border-radius: 45% 55% 50% 48%;
+  bottom: calc(var(--salt-fill, 20%) * .55);
+  box-shadow: 0 0 .4rem color-mix(in srgb, var(--assd-salt) 80%, transparent);
+  height: 2.2rem;
+  left: 40%;
+  opacity: .95;
+  position: absolute;
+  transform: rotate(-10deg);
+  width: 3.2rem;
+}
+
+.assd-scoop {
+  background: var(--assd-salt);
+  border: 2px solid var(--assd-ink);
+  border-radius: 60% 60% 35% 35%;
+  height: 2.8rem;
+  left: 56%;
+  position: absolute;
+  top: .65rem;
+  transform: rotate(25deg);
+  width: 4rem;
+}
+
+.assd-scoop::after {
+  background: var(--assd-water);
+  border: 2px solid var(--assd-ink);
+  border-radius: 99rem;
+  content: '';
+  height: .65rem;
+  position: absolute;
+  right: -3.4rem;
+  top: .9rem;
+  transform: rotate(18deg);
+  width: 3.6rem;
+}
+
+.assd-scoop span,
+.assd-scoop span::before,
+.assd-scoop span::after {
+  background: var(--assd-ink);
+  border-radius: 50%;
+  content: '';
+  height: .25rem;
+  position: absolute;
+  width: .25rem;
+}
+
+.assd-scoop span {
+  left: 1rem;
+  top: .8rem;
+}
+
+.assd-scoop span::before {
+  left: .7rem;
+  top: .4rem;
+}
+
+.assd-scoop span::after {
+  left: 1.5rem;
+  top: .15rem;
+}
+
+.assd-refractometer {
+  background: linear-gradient(90deg, var(--assd-ink), var(--assd-water));
+  border: 2px solid var(--assd-ink);
+  border-radius: .4rem 1rem 1rem .4rem;
+  bottom: .3rem;
+  height: 1.35rem;
+  position: absolute;
+  right: 6%;
+  transform: rotate(-18deg);
+  width: 7rem;
+}
+
+.assd-refractometer::before {
+  background: var(--assd-surface);
+  border: 2px solid var(--assd-ink);
+  border-radius: .3rem;
+  content: '';
+  height: 1.05rem;
+  left: .5rem;
+  position: absolute;
+  top: .05rem;
+  width: 2.1rem;
+}
+
+.assd-answer {
+  border-top: 1px solid var(--assd-line);
+  padding-top: 1rem;
+}
+
+.assd-answer-label {
+  align-items: center;
+  justify-content: flex-start;
+}
+
+.assd-answer-label > span:first-child,
+.assd-unit-row > span,
+.assd-presets > span {
+  color: var(--assd-muted);
+  font-size: .78rem;
+  font-weight: 800;
+}
+
+.assd-answer-rule {
+  background: color-mix(in srgb, var(--assd-water) 45%, var(--assd-line));
+  height: 1px;
+  width: 2.5rem;
+}
+
+.assd-answer strong {
+  display: block;
+  font-size: clamp(2.6rem, 6vw, 4.3rem);
+  letter-spacing: -.075em;
+  line-height: .95;
+  margin-top: .35rem;
+  overflow-wrap: anywhere;
+}
+
+.assd-answer p,
+.assd-help,
+.assd-note,
+.assd-error {
+  color: var(--assd-muted);
+  font-size: .86rem;
+  line-height: 1.5;
+  margin: .65rem 0 0;
+}
+
+.assd-note {
+  background: color-mix(in srgb, var(--assd-water-soft) 72%, transparent);
+  border-left: 3px solid var(--assd-water);
+  border-radius: 0 .5rem .5rem 0;
+  padding: .7rem .8rem;
+}
+
+.assd-controls {
+  border-left: 1px solid var(--assd-line);
+  padding: .35rem 0 .35rem clamp(0rem, 1vw, .4rem);
+}
+
+.assd-controls-head {
+  display: grid;
+  gap: 1rem;
+}
+
+.assd-toggle,
+.assd-preset-buttons {
+  display: flex;
+  flex-wrap: wrap;
+  gap: .45rem;
+}
+
+.assd-mode-toggle {
+  width: 100%;
+}
+
+.assd-mode-toggle button {
+  flex: 1 1 10rem;
+}
+
+.assd-toggle button,
+.assd-preset-buttons button,
+.assd-reset {
+  background: color-mix(in srgb, var(--assd-surface) 68%, transparent);
+  border: 1px solid var(--assd-line);
+  border-radius: .75rem;
+  color: var(--assd-ink);
+  cursor: pointer;
+  font: inherit;
+  min-height: 2.55rem;
+  padding: .55rem .8rem;
+  transition: background .2s ease, border-color .2s ease, transform .2s ease;
+}
+
+.assd-toggle button:hover,
+.assd-preset-buttons button:hover,
+.assd-reset:hover {
+  border-color: var(--assd-water);
+  transform: translateY(-1px);
+}
+
+.assd-toggle button.is-active,
+.assd-preset-buttons button:focus-visible,
+.assd-preset-buttons button:hover {
+  background: var(--assd-water-soft);
+  border-color: var(--assd-water);
+  font-weight: 900;
+}
+
+.assd-toggle button:focus-visible,
+.assd-preset-buttons button:focus-visible,
+.assd-reset:focus-visible,
+.assd-field input:focus-visible {
+  outline: 3px solid var(--assd-water);
+  outline-offset: 2px;
+}
+
+.assd-unit-row {
+  border-bottom: 1px solid var(--assd-line);
+  border-top: 1px solid var(--assd-line);
+  margin-top: 1.4rem;
+  padding: .8rem 0;
+}
+
+.assd-unit-row > span {
+  align-self: center;
+}
+
+.assd-help {
+  background: color-mix(in srgb, var(--assd-water-soft) 42%, transparent);
+  border-radius: .65rem;
+  margin-top: 1rem;
+  padding: .7rem .8rem;
+}
+
+.assd-fields {
+  display: grid;
+  gap: 1rem;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  margin-top: 1.15rem;
+}
+
+.assd-field {
+  display: grid;
+  gap: .4rem;
+}
+
+.assd-field > span {
+  display: flex;
+  font-size: .82rem;
+  font-weight: 900;
+  gap: .4rem;
+  justify-content: space-between;
+  line-height: 1.25;
+}
+
+.assd-field small {
+  color: var(--assd-muted);
+  font-size: .75rem;
+  font-weight: 700;
+  white-space: nowrap;
+}
+
+.assd-field input {
+  background: color-mix(in srgb, var(--assd-surface) 75%, transparent);
+  border: 1px solid var(--assd-line);
+  border-radius: .75rem;
+  box-sizing: border-box;
+  color: var(--assd-ink);
+  font: inherit;
+  font-size: 1rem;
+  font-weight: 700;
+  min-height: 3rem;
+  padding: .65rem .75rem;
+  width: 100%;
+}
+
+.assd-presets {
+  display: grid;
+  gap: .6rem;
+  margin-top: 1.15rem;
+}
+
+.assd-preset-buttons {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+}
+
+.assd-reset {
+  margin-top: 1.15rem;
+}
+
+.assd-error {
+  color: var(--assd-error);
+  display: none;
+  font-weight: 800;
+}
+
+.assd-root.has-error .assd-error {
+  display: block;
+}
+
+@media (max-width: 760px) {
+  .assd-root {
+    grid-template-columns: 1fr;
+  }
+
+  .assd-controls {
+    border-left: 0;
+    border-top: 1px solid var(--assd-line);
+    padding: 1.35rem 0 0;
+  }
+}
+
+@media (max-width: 520px) {
+  .assd-result-head {
+    flex-direction: column;
+  }
+
+  .assd-action {
+    max-width: none;
+  }
+
+  .assd-fields {
+    grid-template-columns: 1fr;
+  }
+
+  .assd-preset-buttons {
+    grid-template-columns: 1fr;
+  }
+
+  .assd-scene {
+    height: 11.5rem;
+  }
+
+  .assd-water-vessel {
+    height: 8.6rem;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    scroll-behavior: auto;
+    transition-duration: .01ms;
+  }
+}

package/src/tool/aquariumSaltDosingCalculator/bibliography.astro

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

package/src/tool/aquariumSaltDosingCalculator/bibliography.ts

@@ -0,0 +1,5 @@
+export const bibliography = [
+  { name: 'NOAA Ocean Service, What is salinity?', url: 'https://oceanservice.noaa.gov/facts/salinity.html' },
+  { name: 'USGS Water Science School, Water density', url: 'https://www.usgs.gov/special-topics/water-science-school/science/water-density' },
+  { name: 'FAO, Manual de acuicultura en español', url: 'https://www.fao.org/4/x5685s/x5685s00.htm' },
+];