@jjlmoya/utils-games-development 1.60.0 → 1.62.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jjlmoya/utils-games-development",
-    "version": "1.60.0",
+    "version": "1.62.0",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",

package/src/category/index.ts

@@ -4,10 +4,11 @@ import { spriteSheetPacker } from '../tool/spriteSheetPacker/entry';
 import { audioLoopPointFinder } from '../tool/audioLoopPointFinder/entry';
 import { saveFileEditor } from '../tool/saveFileEditor/entry';
 import { steamBbcodeTranslator } from '../tool/steamBbcodeTranslator/entry';
+import { gameUiAccessibilityTester } from '../tool/gameUIAccessibilityTester/entry';
 
 export const gamesCategory: GamesCategoryEntry = {
   icon: 'mdi:gamepad-variant',
-  tools: [steamCapsuleGenerator, spriteSheetPacker, audioLoopPointFinder, saveFileEditor, steamBbcodeTranslator],
+  tools: [steamCapsuleGenerator, spriteSheetPacker, audioLoopPointFinder, saveFileEditor, steamBbcodeTranslator, gameUiAccessibilityTester],
   i18n: {
     de: () => import('./i18n/de').then((m) => m.content),
     en: () => import('./i18n/en').then((m) => m.content),

package/src/entries.ts

@@ -26,5 +26,6 @@ import { localizationSanitizer } from './tool/localizationSanitizer/entry';
 import { steamBbcodeTranslator } from './tool/steamBbcodeTranslator/entry';
 import { retroSfxGenerator } from './tool/retroSfxGenerator/entry';
 import { pixelArtPaletteSwapper } from './tool/pixelArtPaletteSwapper/entry';
+import { gameUiAccessibilityTester } from './tool/gameUIAccessibilityTester/entry';
 
-export const ALL_ENTRIES = [steamCapsuleGenerator, itchioGameTester, spriteSheetPacker, audioLoopPointFinder, saveFileEditor, localizationSanitizer, steamBbcodeTranslator, retroSfxGenerator, pixelArtPaletteSwapper];
+export const ALL_ENTRIES = [steamCapsuleGenerator, itchioGameTester, spriteSheetPacker, audioLoopPointFinder, saveFileEditor, localizationSanitizer, steamBbcodeTranslator, retroSfxGenerator, pixelArtPaletteSwapper, gameUiAccessibilityTester];

package/src/index.ts

@@ -20,5 +20,6 @@ export { STEAM_CAPSULE_GENERATOR_TOOL, steamCapsuleGenerator } from './tool/stea
 export { STEAM_BBCODE_TRANSLATOR_TOOL, steamBbcodeTranslator } from './tool/steamBbcodeTranslator';
 export { RETRO_SFX_GENERATOR_TOOL, retroSfxGenerator } from './tool/retroSfxGenerator';
 export { PIXEL_ART_PALETTE_SWAPPER_TOOL, pixelArtPaletteSwapper } from './tool/pixelArtPaletteSwapper';
+export { GAME_UI_ACCESSIBILITY_TESTER_TOOL, gameUiAccessibilityTester } from './tool/gameUIAccessibilityTester';
 
 export type { ToolLocaleContent as GamesToolLocaleContent } from './types';

package/src/tests/locale_completeness.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect } from 'vitest';
 import { ALL_TOOLS } from '../tools';
 
 describe('Locale Completeness Validation', () => {
-  it('nine tools are registered', () => {
-    expect(ALL_TOOLS.length).toBe(9);
+  it('ten tools are registered', () => {
+    expect(ALL_TOOLS.length).toBe(10);
   });
 });

package/src/tests/spanish_leakage.test.ts

@@ -28,6 +28,8 @@ const TRANSLATABLE_KEYS = [
   'schemas',
 ] as const;
 
+const COPY_THRESHOLD = 0.9;
+
 const SPANISH_MARKERS = [
   ['sangre', /\bsangre\b/gi],
   ['molino', /\bmolino\b/gi],
@@ -65,12 +67,16 @@ function normalize(value: string): string {
 }
 
 function isTechnicalInvariant(text: string): boolean {
+  const ledUnitMatches = text.match(/\b\d+(?:-\d+)?\s*(?:w|lm)\b/g) ?? [];
   return [
     'data:image/svg+xml;base64',
     'background-image: url',
     '.layout-playground {',
     'const samplerate =',
-  ].some((pattern) => text.includes(pattern)) || (text.includes('presets') && text.includes('hz'));
+  ].some((pattern) => text.includes(pattern)) ||
+    (text.includes('presets') && text.includes('hz')) ||
+    (text.includes('t_rectal') && text.includes('exp(-k * t)')) ||
+    (text.includes('led') && ledUnitMatches.length >= 3);
 }
 
 function collectString(value: string, output: string[]): void {
@@ -111,10 +117,26 @@ function findSpanishMarkers(text: string[]): string[] {
   );
 }
 
+function similarity(left: string, right: string): number {
+  const leftTokens = left.split(/\s+/);
+  const rightCounts = new Map<string, number>();
+  right.split(/\s+/).forEach((token) => rightCounts.set(token, (rightCounts.get(token) ?? 0) + 1));
+  const matches = leftTokens.reduce((total, token) => {
+    const count = rightCounts.get(token) ?? 0;
+    if (count > 0) rightCounts.set(token, count - 1);
+    return total + (count > 0 ? 1 : 0);
+  }, 0);
+  return (2 * matches) / (leftTokens.length + right.split(/\s+/).length);
+}
+
 function findCopiedFragments(spanish: string[], translated: string[]): string[] {
-  const corpus = translated.join(' ');
   return spanish
-    .filter((fragment) => fragment.length >= 80 && corpus.includes(fragment))
+    .filter((fragment) => fragment.length >= 80)
+    .filter((fragment) => translated.some((candidate) =>
+      candidate.length >= 80 &&
+      Math.min(fragment.length, candidate.length) / Math.max(fragment.length, candidate.length) >= COPY_THRESHOLD &&
+      similarity(fragment, candidate) >= COPY_THRESHOLD,
+    ))
     .sort((a, b) => b.length - a.length)
     .slice(0, 3);
 }

package/src/tests/tool_validation.test.ts

@@ -4,8 +4,8 @@ import { gamesCategory } from '../data';
 
 describe('Tool Validation Suite', () => {
   describe('Library Registration', () => {
-    it('should have 9 tools in ALL_TOOLS', () => {
-      expect(ALL_TOOLS.length).toBe(9);
+    it('should have 10 tools in ALL_TOOLS', () => {
+      expect(ALL_TOOLS.length).toBe(10);
     });
 
     it('gamesCategory should be defined', () => {

package/src/tool/gameUIAccessibilityTester/bibliography.astro

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

package/src/tool/gameUIAccessibilityTester/bibliography.ts

@@ -0,0 +1,10 @@
+export const bibliographyEntries = [
+  {
+    name: 'Machado, Oliveira and Fernandes: A Physiologically Based Model for Simulation of Color Vision Deficiency',
+    url: 'https://profs.ic.uff.br/~laffernandes/content/publications/journal/2009_tvcg_15%286%29/machado_oliveira_fernandes-tvcg-15%286%29-2009-corrected.pdf',
+  },
+  {
+    name: 'W3C Web Accessibility Initiative: Understanding Non Text Contrast',
+    url: 'https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast',
+  },
+];

package/src/tool/gameUIAccessibilityTester/component.astro

@@ -0,0 +1,210 @@
+---
+import type { GameUiAccessibilityTesterUI } from './ui';
+
+interface Props {
+  ui: GameUiAccessibilityTesterUI;
+}
+
+const { ui } = Astro.props;
+const serializedUi = JSON.stringify(ui).replace(/</g, '\\u003c');
+---
+
+<article class="gax" data-game-ui-accessibility-tester data-ready="false" data-compare="side" data-zoom="1">
+  <script is:inline type="application/json" data-ui set:html={serializedUi}></script>
+
+  <div class="gax-intro">
+    <div class="gax-signal" aria-hidden="true"><span></span><span></span><span></span></div>
+    <p>{ui.onboarding}</p>
+    <p class="gax-privacy">{ui.privacyNote}</p>
+  </div>
+
+  <section class="gax-upload" data-dropzone aria-labelledby="game-ui-drop-title">
+    <svg viewBox="0 0 64 64" aria-hidden="true">
+      <path d="M12 17h40v30H12z M20 37l8-9 7 7 5-5 8 9 M32 10v13 M26 16l6 7 6-7" />
+    </svg>
+    <div>
+      <h2 id="game-ui-drop-title">{ui.dropTitle}</h2>
+      <p>{ui.dropHint}</p>
+      <small>{ui.supportedFiles}</small>
+    </div>
+    <input
+      class="gax-file-input"
+      id="game-ui-image-input"
+      data-file-input
+      type="file"
+      accept="image/png,image/jpeg,image/webp"
+    />
+    <label class="gax-upload-action" for="game-ui-image-input">
+      <span class="gax-upload-new">{ui.chooseImage}</span>
+      <span class="gax-upload-replace">{ui.replaceImage}</span>
+    </label>
+  </section>
+
+  <section class="gax-optics" aria-label={ui.lensLabel}>
+    <div class="gax-control-head">
+      <span>{ui.lensLabel}</span>
+      <span class="gax-control-rule" aria-hidden="true"></span>
+    </div>
+    <div class="gax-lens-rack">
+      <button type="button" data-mode value="original" aria-pressed="false">{ui.lensOriginal}</button>
+      <button type="button" data-mode value="protanopia" aria-pressed="false">{ui.lensProtanopia}</button>
+      <button type="button" data-mode value="deuteranopia" aria-pressed="true">{ui.lensDeuteranopia}</button>
+      <button type="button" data-mode value="tritanopia" aria-pressed="false">{ui.lensTritanopia}</button>
+      <button type="button" data-mode value="achromatopsia" aria-pressed="false">{ui.lensAchromatopsia}</button>
+      <button type="button" data-mode value="reduced-contrast" aria-pressed="false">{ui.lensReducedContrast}</button>
+      <button type="button" data-mode value="desaturation" aria-pressed="false">{ui.lensDesaturation}</button>
+    </div>
+  </section>
+
+  <section class="gax-stage" aria-label={ui.simulatedView}>
+    <div class="gax-stage-toolbar">
+      <div class="gax-segment" role="group" aria-label={ui.compareLabel}>
+        <button type="button" data-compare value="side" class="is-active" aria-pressed="true">{ui.compareSideBySide}</button>
+        <button type="button" data-compare value="split" aria-pressed="false">{ui.compareSplit}</button>
+        <button type="button" data-compare value="press" aria-pressed="false">{ui.comparePress}</button>
+      </div>
+      <div class="gax-segment" role="group" aria-label={ui.zoomLabel}>
+        <button type="button" data-zoom value="1" class="is-active" aria-pressed="true">1x</button>
+        <button type="button" data-zoom value="2" aria-pressed="false">2x</button>
+        <button type="button" data-zoom value="4" aria-pressed="false">4x</button>
+      </div>
+    </div>
+
+    <div class="gax-viewports">
+      <figure class="gax-viewport gax-original">
+        <figcaption><span></span>{ui.originalView}</figcaption>
+        <div class="gax-canvas-wrap">
+          <canvas data-original-canvas tabindex="0" aria-label={ui.originalView}></canvas>
+          <span class="gax-marker gax-marker-a" data-marker="0" hidden>A</span>
+          <span class="gax-marker gax-marker-b" data-marker="1" hidden>B</span>
+        </div>
+      </figure>
+      <figure class="gax-viewport gax-simulated">
+        <figcaption><span></span>{ui.simulatedView}</figcaption>
+        <div class="gax-canvas-wrap">
+          <canvas data-simulated-canvas aria-label={ui.simulatedView}></canvas>
+        </div>
+      </figure>
+      <p class="gax-empty">{ui.emptyCanvas}</p>
+    </div>
+
+    <div class="gax-compare-actions">
+      <label class="gax-split-control" for="game-ui-split">
+        {ui.splitPosition}
+        <input id="game-ui-split" data-split type="range" min="10" max="90" value="50" />
+      </label>
+      <button type="button" class="gax-hold" data-hold-original>{ui.holdOriginal}</button>
+    </div>
+  </section>
+
+  <section class="gax-stress" aria-labelledby="game-ui-stress-title">
+    <div class="gax-control-head">
+      <h2 id="game-ui-stress-title">{ui.stressLabel}</h2>
+      <span class="gax-control-rule" aria-hidden="true"></span>
+    </div>
+    <div class="gax-stress-line">
+      <label for="game-ui-blur">{ui.blurLabel}</label>
+      <input id="game-ui-blur" data-blur type="range" min="0" max="8" step="0.5" value="0" />
+      <div class="gax-segment" role="group" aria-label={ui.downscaleLabel}>
+        <button type="button" data-downscale value="1" class="is-active" aria-pressed="true">{ui.downscaleFull}</button>
+        <button type="button" data-downscale value="0.5" aria-pressed="false">{ui.downscaleHalf}</button>
+        <button type="button" data-downscale value="0.25" aria-pressed="false">{ui.downscaleQuarter}</button>
+        <button type="button" data-downscale value="0.125" aria-pressed="false">{ui.downscaleEighth}</button>
+      </div>
+      <label class="gax-toggle">
+        <input data-heatmap type="checkbox" />
+        <span aria-hidden="true"></span>
+        <span><strong>{ui.heatmapLabel}</strong><small>{ui.heatmapHint}</small></span>
+      </label>
+    </div>
+  </section>
+
+  <section class="gax-sampler" aria-labelledby="game-ui-sample-title">
+    <header>
+      <div>
+        <h2 id="game-ui-sample-title">{ui.sampleTitle}</h2>
+        <p>{ui.sampleInstructions}</p>
+      </div>
+      <span class="gax-classification">{ui.heuristicLabel}</span>
+    </header>
+    <div class="gax-sample-strip">
+      <div class="gax-sample-unit">
+        <button type="button" data-sample-button value="0" class="is-active" aria-pressed="true">
+          <span data-swatch="0" class="gax-swatch"></span>{ui.sampleA}
+        </button>
+        <div class="gax-sample-copy">
+          <label for="game-ui-sample-a">{ui.sampleAName}</label>
+          <input id="game-ui-sample-a" data-name="0" type="text" value={ui.sampleAInitial} maxlength="40" />
+          <code data-hex="0">{ui.noSample}</code>
+        </div>
+        <label class="gax-color-input" for="game-ui-color-a">{ui.manualColor}</label>
+        <input id="game-ui-color-a" data-color-input="0" type="color" value="#000000" />
+      </div>
+      <div class="gax-link-beam" aria-hidden="true"><span></span></div>
+      <div class="gax-sample-unit">
+        <button type="button" data-sample-button value="1" aria-pressed="false">
+          <span data-swatch="1" class="gax-swatch"></span>{ui.sampleB}
+        </button>
+        <div class="gax-sample-copy">
+          <label for="game-ui-sample-b">{ui.sampleBName}</label>
+          <input id="game-ui-sample-b" data-name="1" type="text" value={ui.sampleBInitial} maxlength="40" />
+          <code data-hex="1">{ui.noSample}</code>
+        </div>
+        <label class="gax-color-input" for="game-ui-color-b">{ui.manualColor}</label>
+        <input id="game-ui-color-b" data-color-input="1" type="color" value="#000000" />
+      </div>
+    </div>
+    <div class="gax-instruments" aria-live="polite">
+      <div><span>{ui.originalContrast}</span><strong data-original-contrast>--</strong><small>{ui.measurementLabel}</small></div>
+      <div><span>{ui.simulatedContrast}</span><strong data-simulated-contrast>--</strong><small>{ui.measurementLabel}</small></div>
+      <div><span>{ui.separationRetained}</span><strong data-retained>--</strong><small>{ui.heuristicLabel}</small></div>
+      <div class="gax-diagnostic"><span>{ui.manualReviewLabel}</span><strong data-diagnostic data-level="pending">{ui.statusPending}</strong></div>
+    </div>
+    <div class="gax-method-notes">
+      <p><strong>{ui.measurementLabel}</strong>{ui.measurementHint}</p>
+      <p><strong>{ui.heuristicLabel}</strong>{ui.heuristicHint}</p>
+    </div>
+  </section>
+
+  <section class="gax-review" aria-labelledby="game-ui-review-title">
+    <div class="gax-review-rail">
+      <h2 id="game-ui-review-title">{ui.promptTitle}</h2>
+      <ol>
+        <li>{ui.promptColorOnly}</li>
+        <li>{ui.promptChangingBackground}</li>
+        <li>{ui.promptMinimap}</li>
+        <li>{ui.promptStates}</li>
+        <li>{ui.promptShape}</li>
+      </ol>
+    </div>
+    <div class="gax-findings-panel">
+      <label for="game-ui-finding">{ui.findingLabel}</label>
+      <div class="gax-finding-entry">
+        <input id="game-ui-finding" data-finding-input type="text" placeholder={ui.findingPlaceholder} maxlength="180" />
+        <button type="button" data-add-finding>{ui.addFinding}</button>
+      </div>
+      <p data-findings-empty>{ui.findingsEmpty}</p>
+      <ul data-findings></ul>
+    </div>
+  </section>
+
+  <footer class="gax-actions">
+    <div>
+      <p>{ui.localOnlyDisclosure}</p>
+      <p>{ui.limitationDisclosure}</p>
+      <p data-status role="status">{ui.noSample}</p>
+    </div>
+    <div class="gax-action-buttons">
+      <button type="button" data-export-sheet disabled>{ui.exportSheet}</button>
+      <button type="button" data-export-report disabled>{ui.exportReport}</button>
+      <button type="button" data-reset>{ui.resetTool}</button>
+    </div>
+  </footer>
+</article>
+
+<script>
+  import { mountGameUiAccessibilityTester } from './controller';
+
+  document.querySelectorAll<HTMLElement>('[data-game-ui-accessibility-tester]')
+    .forEach((root) => mountGameUiAccessibilityTester(root));
+</script>

package/src/tool/gameUIAccessibilityTester/controller-actions.ts

@@ -0,0 +1,92 @@
+import { evaluatePair } from './evaluator';
+import { createComparisonSheet, downloadCanvas } from './dom-views';
+import { downloadStructuredReport } from './report';
+import { clearSettings } from './storage';
+import type { TesterState } from './controller';
+
+function required<T extends Element>(root: ParentNode, selector: string): T {
+  const element = root.querySelector<T>(selector);
+  if (!element) throw new Error(`Missing tester element ${selector}`);
+  return element;
+}
+
+function setStatus(state: TesterState, message: string): void {
+  required<HTMLElement>(state.root, '[data-status]').textContent = message;
+}
+
+function addFinding(state: TesterState): void {
+  const input = required<HTMLInputElement>(state.root, '[data-finding-input]');
+  const finding = input.value.trim();
+  if (!finding) return;
+  state.findings.push(finding);
+  const item = document.createElement('li');
+  item.textContent = finding;
+  required(state.root, '[data-findings]').append(item);
+  required<HTMLElement>(state.root, '[data-findings-empty]').hidden = true;
+  input.value = '';
+}
+
+function exportReport(state: TesterState): void {
+  const [first, second] = state.samples;
+  if (!first || !second) return;
+  downloadStructuredReport({
+    mode: state.settings.mode,
+    blur: state.settings.blur,
+    downscale: state.settings.downscale,
+    firstName: required<HTMLInputElement>(state.root, '[data-name="0"]').value,
+    secondName: required<HTMLInputElement>(state.root, '[data-name="1"]').value,
+    first,
+    second,
+    diagnostic: evaluatePair(first, second, state.settings.mode),
+    findings: state.findings,
+  }, state.ui);
+  setStatus(state, state.ui.reportDownloaded);
+}
+
+function exportSheet(state: TesterState): void {
+  if (!state.source) return;
+  const simulated = required<HTMLCanvasElement>(state.root, '[data-simulated-canvas]');
+  const settings = `${state.ui.lensLabel}: ${state.settings.mode}, ${state.ui.blurLabel}: ${state.settings.blur}px`;
+  const sheet = createComparisonSheet(state.source, simulated, {
+    title: state.ui.reportTitle,
+    original: state.ui.originalView,
+    simulated: state.ui.simulatedView,
+    settings,
+    localOnly: state.ui.localOnlyDisclosure,
+  });
+  downloadCanvas(sheet, 'game-ui-accessibility-comparison.png');
+  setStatus(state, state.ui.sheetDownloaded);
+}
+
+function reset(state: TesterState): void {
+  clearSettings();
+  state.source = null;
+  state.samples = [null, null];
+  state.findings = [];
+  state.root.dataset.ready = 'false';
+  state.root.querySelectorAll<HTMLButtonElement>('[data-export-sheet], [data-export-report]')
+    .forEach((button) => { button.disabled = true; });
+  required(state.root, '[data-findings]').replaceChildren();
+  required<HTMLElement>(state.root, '[data-findings-empty]').hidden = false;
+  required<HTMLInputElement>(state.root, '[data-file-input]').value = '';
+  setStatus(state, state.ui.noSample);
+  const diagnostic = required<HTMLElement>(state.root, '[data-diagnostic]');
+  diagnostic.textContent = state.ui.statusPending;
+  diagnostic.dataset.level = 'pending';
+}
+
+function bindHold(state: TesterState): void {
+  const hold = required(state.root, '[data-hold-original]');
+  hold.addEventListener('pointerdown', () => { state.root.dataset.hold = 'true'; });
+  ['pointerup', 'pointerleave', 'blur'].forEach((event) => {
+    hold.addEventListener(event, () => { delete state.root.dataset.hold; });
+  });
+}
+
+export function bindActions(state: TesterState): void {
+  required(state.root, '[data-add-finding]').addEventListener('click', () => addFinding(state));
+  required(state.root, '[data-export-report]').addEventListener('click', () => exportReport(state));
+  required(state.root, '[data-export-sheet]').addEventListener('click', () => exportSheet(state));
+  required(state.root, '[data-reset]').addEventListener('click', () => reset(state));
+  bindHold(state);
+}