@jjlmoya/utils-language 1.10.0 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jjlmoya/utils-language",
-    "version": "1.10.0",
+    "version": "1.11.0",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",

package/src/category/index.ts

@@ -1,11 +1,12 @@
 import { cefrLanguageSkillProfilePlanner } from '../tool/cefr-language-skill-profile-planner/entry';
 import { languageShadowingSessionPlanner } from '../tool/language-shadowing-session-planner/entry';
 import { languageLearningStudyPlanPlanner } from '../tool/language-learning-study-plan-planner/entry';
+import { lexicalCoverageVocabularyCalculator } from '../tool/lexical-coverage-vocabulary-calculator/entry';
 import type { CategoryLocaleContent, KnownLocale } from '../types';
 
 export const languageCategory = {
   icon: 'mdi:translate-variant',
-  tools: [languageLearningStudyPlanPlanner, cefrLanguageSkillProfilePlanner, languageShadowingSessionPlanner],
+  tools: [languageLearningStudyPlanPlanner, cefrLanguageSkillProfilePlanner, languageShadowingSessionPlanner, lexicalCoverageVocabularyCalculator],
   i18n: {
     de: () => import('./i18n/de').then((module) => module.content),
     en: () => import('./i18n/en').then((module) => module.content),

package/src/entries.ts

@@ -1,5 +1,6 @@
 import { cefrLanguageSkillProfilePlanner } from './tool/cefr-language-skill-profile-planner/entry';
 import { languageShadowingSessionPlanner } from './tool/language-shadowing-session-planner/entry';
 import { languageLearningStudyPlanPlanner } from './tool/language-learning-study-plan-planner/entry';
+import { lexicalCoverageVocabularyCalculator } from './tool/lexical-coverage-vocabulary-calculator/entry';
 
-export const ALL_ENTRIES = [languageLearningStudyPlanPlanner, cefrLanguageSkillProfilePlanner, languageShadowingSessionPlanner];
+export const ALL_ENTRIES = [languageLearningStudyPlanPlanner, cefrLanguageSkillProfilePlanner, languageShadowingSessionPlanner, lexicalCoverageVocabularyCalculator];

package/src/tests/locale_completeness.test.ts

@@ -18,6 +18,6 @@ describe('Locale Completeness Validation', () => {
   });
 
   it('all tools registered', () => {
-    expect(ALL_TOOLS.length).toBe(3);
+    expect(ALL_TOOLS.length).toBe(4);
   });
 });

package/src/tests/registry_contract.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { pathToFileURL } from 'url';
+import { ALL_ENTRIES } from '../entries';
+import { ALL_TOOLS } from '../tools';
+import type { ToolDefinition } from '../types';
+
+function isToolDefinition(value: unknown): value is ToolDefinition {
+  if (!value || typeof value !== 'object') return false;
+
+  const candidate = value as Record<string, unknown>;
+  return Boolean(
+    candidate.entry &&
+      typeof candidate.entry === 'object' &&
+      typeof candidate.Component === 'function' &&
+      typeof candidate.SEOComponent === 'function' &&
+      typeof candidate.BibliographyComponent === 'function',
+  );
+}
+
+const toolRoot = join(process.cwd(), 'src', 'tool');
+const toolDirectories = readdirSync(toolRoot, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory() && existsSync(join(toolRoot, entry.name, 'index.ts')))
+  .map((entry) => entry.name)
+  .sort();
+
+describe('Library registry contract', () => {
+  it('keeps ALL_ENTRIES and ALL_TOOLS synchronized by id', () => {
+    const entryIds = ALL_ENTRIES.map((entry) => entry.id);
+    const toolIds = ALL_TOOLS.map((tool) => tool.entry.id);
+
+    expect(new Set(entryIds).size).toBe(entryIds.length);
+    expect(new Set(toolIds).size).toBe(toolIds.length);
+    expect([...toolIds].sort()).toEqual([...entryIds].sort());
+  });
+
+  it('registers every tool runtime index in both public registries', async () => {
+    const failures: string[] = [];
+
+    for (const directory of toolDirectories) {
+      const runtimeModule = await import(
+        pathToFileURL(join(toolRoot, directory, 'index.ts')).href,
+      );
+      const definitions = [...new Set(Object.values(runtimeModule).filter(isToolDefinition))];
+
+      if (definitions.length !== 1) {
+        failures.push(`${directory}: expected exactly one ToolDefinition export, found ${definitions.length}`);
+        continue;
+      }
+
+      const [definition] = definitions;
+      if (!definition) {
+        failures.push(`${directory}: runtime definition is undefined`);
+        continue;
+      }
+      if (!ALL_TOOLS.some((tool) => tool.entry.id === definition.entry.id)) {
+        failures.push(`${directory}: runtime definition is missing from ALL_TOOLS`);
+      }
+      if (!ALL_ENTRIES.some((entry) => entry.id === definition.entry.id)) {
+        failures.push(`${directory}: runtime entry is missing from ALL_ENTRIES`);
+      }
+    }
+
+    expect(failures).toEqual([]);
+  });
+});

package/src/tests/tool_exports.test.ts

@@ -1,4 +1,6 @@
 import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { ALL_TOOLS } from '../tools';
 import { validateToolExports } from './shared-test-helpers';
 
@@ -20,6 +22,12 @@ describe('Tool Exports Pattern Validation', () => {
         expect(tool.BibliographyComponent).toBeInstanceOf(Function);
       });
     });
+
+    it.each(ALL_TOOLS)('$entry.id: Component should load its tool stylesheet', (tool) => {
+      const componentPath = join(process.cwd(), 'src', 'tool', tool.entry.id, 'component.astro');
+      const source = readFileSync(componentPath, 'utf8');
+      expect(source).toContain(`import './${tool.entry.id}.css';`);
+    });
   });
 
   describe('Dynamic Import Validation', () => {

package/src/tests/tool_validation.test.ts

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

package/src/tool/language-shadowing-session-planner/component.astro

@@ -1,4 +1,5 @@
 ---
+import './language-shadowing-session-planner.css';
 import { calculateShadowingPlan, DEFAULT_SHADOWING_INPUTS } from './logic';
 import type { ShadowingSessionUI } from './ui';
 

package/src/tool/lexical-coverage-vocabulary-calculator/bibliography.astro

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

package/src/tool/lexical-coverage-vocabulary-calculator/bibliography.ts

@@ -0,0 +1,6 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliography: BibliographyEntry[] = [
+  { name: 'Paul Nation, How Large a Vocabulary Is Needed for Reading and Listening?', url: 'https://www.scienceguide.nl/wp-content/uploads/2017/11/nation-2006-vocabulary.pdf' },
+  { name: 'Izquierdo Gil, La selección del léxico en la enseñanza del español como lengua extranjera', url: 'https://asele.org/media/2025/03/8izquierdogilm-adelcarmenlaselecciondellexicoenlaensananza.pdf' },
+];

package/src/tool/lexical-coverage-vocabulary-calculator/component.astro

@@ -0,0 +1,77 @@
+---
+import './lexical-coverage-vocabulary-calculator.css';
+import { COVERAGE_TARGETS } from './logic';
+import type { ContentType } from './types';
+import type { LexicalCoverageUI } from './ui';
+
+interface Props {
+  ui: LexicalCoverageUI;
+}
+
+const { ui } = Astro.props as Props;
+const contentTypes: ContentType[] = ['conversation', 'travel', 'media', 'generalReading', 'novels', 'business', 'academic'];
+const contentLabels: Record<ContentType, string> = {
+  conversation: ui.conversation, travel: ui.travel, media: ui.media, generalReading: ui.generalReading, novels: ui.novels, business: ui.business, academic: ui.academic,
+};
+const coverageLabels: Record<number, string> = { 80: ui.coverage80, 90: ui.coverage90, 95: ui.coverage95, 98: ui.coverage98 };
+---
+
+<div class="lexical-coverage" data-lexical-coverage data-ui={JSON.stringify(ui)}>
+  <form class="lexical-form" data-lexical-form>
+    <div class="content-field" data-content-choice>
+      <span class="field-label">{ui.contentType}</span>
+      <input type="hidden" name="contentType" value="conversation" />
+      <button class="choice-trigger" type="button" aria-haspopup="listbox" aria-expanded="false">{ui.conversation}</button>
+      <div class="choice-menu" role="listbox" hidden>
+        {contentTypes.map((type) => <button type="button" role="option" data-choice-value={type} aria-selected={type === 'conversation'}>{contentLabels[type]}</button>)}
+      </div>
+    </div>
+
+    <label class="words-field">
+      <span class="field-label">{ui.knownWords}</span>
+      <input type="number" name="knownWords" min="0" max="50000" step="100" value="1000" required />
+      <input class="words-range" type="range" name="knownWordsRange" min="0" max="15000" step="100" value="1000" aria-label={ui.knownWords} />
+      <span class="words-hint">{ui.knownWordsHint}</span>
+    </label>
+
+    <fieldset>
+      <legend class="coverage-label">{ui.targetCoverage}</legend>
+      <input type="hidden" name="targetCoverage" value="80" />
+      <div class="coverage-options">
+        {COVERAGE_TARGETS.map((coverage) => <button type="button" data-coverage-value={coverage} aria-label={coverageLabels[coverage]} aria-pressed={coverage === 80}>{coverage}%</button>)}
+      </div>
+    </fieldset>
+
+    <div>
+      <span class="preset-label">{ui.quickStart}</span>
+      <div class="preset-grid">
+        <button type="button" data-lexical-preset="conversation">{ui.conversationPreset}</button>
+        <button type="button" data-lexical-preset="reading">{ui.readingPreset}</button>
+        <button type="button" data-lexical-preset="work">{ui.workPreset}</button>
+      </div>
+    </div>
+
+    <p class="lexical-note">{ui.contentTypeHelp} {ui.coverageNote} {ui.wordFamilyNote}</p>
+    <div class="lexical-actions">
+      <button class="reset-button" type="reset">{ui.resetButton}</button>
+    </div>
+  </form>
+
+  <section class="lexical-result" aria-live="polite" aria-atomic="true">
+    <h2 class="lexical-result-title">{ui.resultTitle}</h2>
+    <div data-lexical-results>
+      <div class="lexical-empty">
+        <svg class="empty-atlas-glyph" viewBox="0 0 120 90" aria-hidden="true"><path class="empty-page" d="M 18 68 L 27 18 L 88 10 L 102 66 Z"></path><line class="empty-line" x1="36" y1="37" x2="82" y2="31"></line><line class="empty-line" x1="33" y1="49" x2="79" y2="43"></line></svg>
+        <span class="lexical-empty-copy">{ui.emptyResult}</span>
+      </div>
+    </div>
+  </section>
+</div>
+
+<script>
+  import { mountLexicalCoverage } from './controller';
+  import type { LexicalCoverageUI } from './ui';
+
+  const root = document.querySelector<HTMLElement>('[data-lexical-coverage]');
+  if (root) mountLexicalCoverage(root, JSON.parse(root.dataset.ui ?? '{}') as LexicalCoverageUI);
+</script>

package/src/tool/lexical-coverage-vocabulary-calculator/controller.ts

@@ -0,0 +1,157 @@
+import { calculateLexicalCoverage } from './logic';
+import { renderLexicalCoverage, renderLexicalCoverageEmpty, renderLexicalCoverageError } from './dom-views';
+import { clearLexicalCoverageInputs, readLexicalCoverageInputs, saveLexicalCoverageInputs } from './storage';
+import type { ContentType, CoverageTarget, LexicalCoverageInputs } from './types';
+import type { LexicalCoverageUI } from './ui';
+
+export function mountLexicalCoverage(root: HTMLElement, ui: LexicalCoverageUI): void {
+  const form = root.querySelector<HTMLFormElement>('[data-lexical-form]');
+  if (!form) return;
+  applySavedInputs(form, readLexicalCoverageInputs());
+  const recalculate = (): void => calculateAndRender(root, form, ui);
+  setupContentChoice(root, form, recalculate);
+  setupCoverageChips(form, recalculate);
+  setupWordSync(form, recalculate);
+  form.addEventListener('submit', (event) => submit(event, root, form, ui));
+  form.addEventListener('reset', () => reset(root, form, ui));
+  root.querySelectorAll<HTMLButtonElement>('[data-lexical-preset]').forEach((button) => button.addEventListener('click', () => applyPreset(button.dataset.lexicalPreset, form, recalculate)));
+  recalculate();
+}
+
+function submit(event: SubmitEvent, root: HTMLElement, form: HTMLFormElement, ui: LexicalCoverageUI): void {
+  event.preventDefault();
+  calculateAndRender(root, form, ui);
+}
+
+function calculateAndRender(root: HTMLElement, form: HTMLFormElement, ui: LexicalCoverageUI): void {
+  const result = calculateLexicalCoverage(readInputs(form));
+  if (!result.ok) {
+    renderLexicalCoverageError(root, translateError(result.error, ui), ui);
+    return;
+  }
+  saveLexicalCoverageInputs(result.plan.inputs);
+  renderLexicalCoverage(root, result.plan, ui);
+}
+
+function reset(root: HTMLElement, form: HTMLFormElement, ui: LexicalCoverageUI): void {
+  window.setTimeout(() => {
+    clearLexicalCoverageInputs();
+    setField(form, 'contentType', 'conversation');
+    setField(form, 'knownWords', 1000);
+    setField(form, 'knownWordsRange', 1000);
+    setField(form, 'targetCoverage', 80);
+    syncChoice(form);
+    syncCoverage(form);
+    renderLexicalCoverageEmpty(root, ui);
+  }, 0);
+}
+
+function setupContentChoice(root: HTMLElement, form: HTMLFormElement, onChange: () => void): void {
+  const choice = root.querySelector<HTMLElement>('[data-content-choice]');
+  const trigger = choice?.querySelector<HTMLButtonElement>('.choice-trigger');
+  const menu = choice?.querySelector<HTMLElement>('.choice-menu');
+  if (!choice || !trigger || !menu) return;
+  trigger.addEventListener('click', () => {
+    const open = trigger.getAttribute('aria-expanded') === 'true';
+    closeChoice(trigger, menu);
+    if (!open) {
+      trigger.setAttribute('aria-expanded', 'true');
+      menu.hidden = false;
+    }
+  });
+  menu.querySelectorAll<HTMLButtonElement>('[data-choice-value]').forEach((option) => option.addEventListener('click', () => {
+    setField(form, 'contentType', option.dataset.choiceValue);
+    trigger.textContent = option.textContent;
+    menu.hidden = true;
+    trigger.setAttribute('aria-expanded', 'false');
+    menu.querySelectorAll('[data-choice-value]').forEach((item) => item.setAttribute('aria-selected', String(item === option)));
+    onChange();
+  }));
+  document.addEventListener('click', (event) => {
+    if (!choice.contains(event.target as Node)) closeChoice(trigger, menu);
+  });
+  trigger.addEventListener('keydown', (event) => {
+    if (event.key === 'Escape') closeChoice(trigger, menu);
+  });
+  syncChoice(form);
+}
+
+function setupCoverageChips(form: HTMLFormElement, onChange: () => void): void {
+  form.querySelectorAll<HTMLButtonElement>('[data-coverage-value]').forEach((button) => button.addEventListener('click', () => {
+    setField(form, 'targetCoverage', button.dataset.coverageValue);
+    syncCoverage(form);
+    onChange();
+  }));
+  syncCoverage(form);
+}
+
+function setupWordSync(form: HTMLFormElement, onChange: () => void): void {
+  const range = form.elements.namedItem('knownWordsRange') as HTMLInputElement | null;
+  const number = form.elements.namedItem('knownWords') as HTMLInputElement | null;
+  if (!range || !number) return;
+  range.addEventListener('input', () => { number.value = range.value; onChange(); });
+  number.addEventListener('input', () => { range.value = number.value; onChange(); });
+}
+
+function applyPreset(preset: string | undefined, form: HTMLFormElement, onChange: () => void): void {
+  const values: Record<string, [ContentType, number, CoverageTarget]> = {
+    conversation: ['conversation', 1000, 80], reading: ['novels', 4000, 95], work: ['business', 5000, 95],
+  };
+  const value = values[preset ?? 'conversation'] ?? values.conversation!;
+  setField(form, 'contentType', value[0]);
+  setField(form, 'knownWords', value[1]);
+  setField(form, 'knownWordsRange', value[1]);
+  setField(form, 'targetCoverage', value[2]);
+  syncChoice(form);
+  syncCoverage(form);
+  onChange();
+}
+
+function applySavedInputs(form: HTMLFormElement, saved: Partial<LexicalCoverageInputs> | null): void {
+  if (!saved) return;
+  setField(form, 'contentType', saved.contentType);
+  setField(form, 'knownWords', saved.knownWords);
+  setField(form, 'knownWordsRange', saved.knownWords);
+  setField(form, 'targetCoverage', saved.targetCoverage);
+}
+
+function readInputs(form: HTMLFormElement): LexicalCoverageInputs {
+  return { contentType: value(form, 'contentType') as ContentType, knownWords: Number(value(form, 'knownWords')), targetCoverage: Number(value(form, 'targetCoverage')) as CoverageTarget };
+}
+
+function syncChoice(form: HTMLFormElement): void {
+  const choice = form.querySelector<HTMLElement>('[data-content-choice]');
+  const hidden = form.elements.namedItem('contentType') as HTMLInputElement | null;
+  if (!choice || !hidden) return;
+  const selected = choice.querySelector<HTMLButtonElement>(`[data-choice-value="${hidden.value}"]`);
+  const trigger = choice.querySelector<HTMLButtonElement>('.choice-trigger');
+  if (selected && trigger) trigger.textContent = selected.textContent;
+  choice.querySelectorAll('[data-choice-value]').forEach((item) => item.setAttribute('aria-selected', String((item as HTMLElement).dataset.choiceValue === hidden.value)));
+}
+
+function syncCoverage(form: HTMLFormElement): void {
+  const selected = value(form, 'targetCoverage');
+  form.querySelectorAll('[data-coverage-value]').forEach((item) => item.setAttribute('aria-pressed', String((item as HTMLElement).dataset.coverageValue === selected)));
+}
+
+function closeChoice(trigger: HTMLButtonElement, menu: HTMLElement): void {
+  trigger.setAttribute('aria-expanded', 'false');
+  menu.hidden = true;
+}
+
+function translateError(error: string, ui: LexicalCoverageUI): string {
+  if (error.includes('content type')) return ui.invalidContentType;
+  if (error.includes('Known vocabulary')) return ui.invalidWords;
+  if (error.includes('coverage target')) return ui.invalidCoverage;
+  return error;
+}
+
+function value(form: HTMLFormElement, name: string): string {
+  return String((form.elements.namedItem(name) as HTMLInputElement).value);
+}
+
+function setField(form: HTMLFormElement, name: string, fieldValue: unknown): void {
+  if (fieldValue === undefined) return;
+  const field = form.elements.namedItem(name) as HTMLInputElement | null;
+  if (field) field.value = String(fieldValue);
+}

package/src/tool/lexical-coverage-vocabulary-calculator/dom-views.ts

@@ -0,0 +1,158 @@
+import { evaluateLexicalCoverage } from './evaluator';
+import type { LexicalCoveragePlan } from './types';
+import type { LexicalCoverageUI } from './ui';
+
+export function renderLexicalCoverage(root: HTMLElement, plan: LexicalCoveragePlan, ui: LexicalCoverageUI): void {
+  const results = root.querySelector<HTMLElement>('[data-lexical-results]');
+  if (!results) return;
+  const evaluation = evaluateLexicalCoverage(plan);
+  results.replaceChildren(createStatus(evaluation.messageKey, ui), createHeadline(plan, ui), createCoverageScene(plan, ui), createReadout(plan, ui));
+}
+
+export function renderLexicalCoverageEmpty(root: HTMLElement, ui: LexicalCoverageUI): void {
+  const results = root.querySelector<HTMLElement>('[data-lexical-results]');
+  if (!results) return;
+  const empty = document.createElement('div');
+  empty.className = 'lexical-empty';
+  empty.append(createEmptyGlyph(), createText('lexical-empty-copy', ui.emptyResult));
+  results.replaceChildren(empty);
+}
+
+export function renderLexicalCoverageError(root: HTMLElement, message: string, ui: LexicalCoverageUI): void {
+  const results = root.querySelector<HTMLElement>('[data-lexical-results]');
+  if (!results) return;
+  results.replaceChildren(createText('lexical-error', `${ui.checkInputs}: ${message}`));
+}
+
+function createStatus(messageKey: 'belowTarget' | 'atTarget' | 'buffer', ui: LexicalCoverageUI): HTMLElement {
+  const status = document.createElement('p');
+  status.className = `lexical-status ${messageKey.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`;
+  status.textContent = ui[messageKey];
+  return status;
+}
+
+function createHeadline(plan: LexicalCoveragePlan, ui: LexicalCoverageUI): HTMLElement {
+  const headline = document.createElement('div');
+  headline.className = 'lexical-headline';
+  headline.append(metric(ui.recommendedWords, `${formatNumber(plan.recommendedWords)} ${ui.wordUnit}`), metric(ui.gapWords, `${formatNumber(plan.gapWords)} ${ui.wordUnit}`));
+  return headline;
+}
+
+function createCoverageScene(plan: LexicalCoveragePlan, ui: LexicalCoverageUI): HTMLElement {
+  const section = document.createElement('section');
+  section.className = 'lexical-scene-wrap';
+  section.append(createText('lexical-scene-label', ui.coverageRoute), createAtlas(plan, ui));
+  return section;
+}
+
+function createAtlas(plan: LexicalCoveragePlan, ui: LexicalCoverageUI): SVGSVGElement {
+  const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+  svg.classList.add('lexical-atlas');
+  svg.setAttribute('viewBox', '0 0 720 240');
+  svg.setAttribute('role', 'img');
+  svg.setAttribute('aria-label', `${formatNumber(plan.estimatedCoverage)}% ${ui.targetMarker}: ${formatNumber(plan.knownWords)} ${ui.wordUnit}`);
+  svg.append(createSvgPath('atlas-river', 'M 34 170 C 160 120 190 190 310 140 S 490 80 686 54'), createSvgPath('atlas-bank', 'M 34 194 C 160 144 190 214 310 164 S 490 104 686 78'));
+  plan.checkpoints.forEach((checkpoint, index) => appendCheckpoint(svg, { checkpoint, index, checkpointCount: plan.checkpoints.length, ui }));
+  const markerX = getMarkerX(plan.estimatedCoverage);
+  svg.append(createSvgCircle(markerX, 112, 'atlas-current-marker'), createSvgText(markerX, 91, `${formatNumber(plan.estimatedCoverage)}%`, 'atlas-current-label'));
+  return svg;
+}
+
+function appendCheckpoint(svg: SVGSVGElement, data: { checkpoint: { coverage: number; words: number }; index: number; checkpointCount: number; ui: LexicalCoverageUI }): void {
+  const { checkpoint, index, checkpointCount, ui } = data;
+  const x = getMarkerX(checkpoint.coverage);
+  const y = 170 - index * 39;
+  const coverageLabel = createSvgText(x, 228, `${checkpoint.coverage}%`, 'atlas-coverage');
+  coverageLabel.setAttribute('text-anchor', index === checkpointCount - 1 ? 'start' : 'end');
+  const wordLabel = createSvgText(x, index === 2 ? 38 : 16, `${formatNumber(checkpoint.words)} ${ui.wordUnit}`, 'atlas-word-count');
+  wordLabel.classList.toggle('atlas-word-count-intermediate', index > 0 && index < checkpointCount - 1);
+  wordLabel.setAttribute('text-anchor', index === checkpointCount - 1 ? 'start' : 'end');
+  svg.append(createSvgLine({ x1: x, y1: y, x2: x, y2: 210 }, 'atlas-guide'), createSvgCircle(x, y, 'atlas-checkpoint'), coverageLabel, wordLabel);
+}
+
+function createReadout(plan: LexicalCoveragePlan, ui: LexicalCoverageUI): HTMLElement {
+  const readout = document.createElement('div');
+  readout.className = 'lexical-readout';
+  readout.append(metric(ui.vocabularyKnown, `${formatNumber(plan.knownWords)} ${ui.wordUnit}`), metric(ui.estimatedCoverage, `${formatNumber(plan.estimatedCoverage)}%`), metric(ui.unknownPerHundred, `${formatNumber(plan.unknownPerHundred)} ${ui.unknownWords}`));
+  const interpretation = document.createElement('div');
+  interpretation.className = 'lexical-interpretation';
+  interpretation.append(createText('lexical-interpretation-title', ui.interpretationTitle), createText('lexical-interpretation-copy', getAction(plan, ui)));
+  const next = document.createElement('p');
+  next.className = 'lexical-next';
+  next.textContent = plan.nextCheckpoint ? `${ui.nextCheckpoint}: ${formatNumber(plan.nextCheckpoint.words)} ${ui.wordUnit} at ${plan.nextCheckpoint.coverage}%` : ui.noMoreCheckpoints;
+  readout.append(interpretation, next);
+  return readout;
+}
+
+function getAction(plan: LexicalCoveragePlan, ui: LexicalCoverageUI): string {
+  if (plan.status === 'below-target') return ui.actionBelow;
+  if (plan.status === 'at-target') return ui.actionAt;
+  return ui.actionBuffer;
+}
+
+function createEmptyGlyph(): SVGSVGElement {
+  const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+  svg.classList.add('empty-atlas-glyph');
+  svg.setAttribute('viewBox', '0 0 120 90');
+  svg.setAttribute('aria-hidden', 'true');
+  svg.append(createSvgPath('empty-page', 'M 18 68 L 27 18 L 88 10 L 102 66 Z'), createSvgLine({ x1: 36, y1: 37, x2: 82, y2: 31 }, 'empty-line'), createSvgLine({ x1: 33, y1: 49, x2: 79, y2: 43 }, 'empty-line'));
+  return svg;
+}
+
+function createSvgPath(className: string, d: string): SVGPathElement {
+  const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+  path.classList.add(className);
+  path.setAttribute('d', d);
+  return path;
+}
+
+function createSvgLine(lineData: { x1: number; y1: number; x2: number; y2: number }, className: string): SVGLineElement {
+  const line = document.createElementNS('http://www.w3.org/2000/svg', 'line');
+  line.classList.add(className);
+  line.setAttribute('x1', String(lineData.x1));
+  line.setAttribute('y1', String(lineData.y1));
+  line.setAttribute('x2', String(lineData.x2));
+  line.setAttribute('y2', String(lineData.y2));
+  return line;
+}
+
+function createSvgCircle(cx: number, cy: number, className: string): SVGCircleElement {
+  const circle = document.createElementNS('http://www.w3.org/2000/svg', 'circle');
+  circle.classList.add(className);
+  circle.setAttribute('cx', String(cx));
+  circle.setAttribute('cy', String(cy));
+  circle.setAttribute('r', className === 'atlas-current-marker' ? '10' : '7');
+  return circle;
+}
+
+function createSvgText(x: number, y: number, text: string, className: string): SVGTextElement {
+  const element = document.createElementNS('http://www.w3.org/2000/svg', 'text');
+  element.classList.add(className);
+  element.setAttribute('x', String(x));
+  element.setAttribute('y', String(y));
+  element.setAttribute('text-anchor', 'middle');
+  element.textContent = text;
+  return element;
+}
+
+function createText(className: string, text: string): HTMLElement {
+  const element = document.createElement('span');
+  element.className = className;
+  element.textContent = text;
+  return element;
+}
+
+function metric(label: string, value: string): HTMLElement {
+  const item = document.createElement('div');
+  item.className = 'lexical-metric';
+  item.append(createText('lexical-metric-label', label), createText('lexical-metric-value', value));
+  return item;
+}
+
+function getMarkerX(coverage: number): number {
+  return 34 + (Math.min(98, Math.max(0, coverage)) / 98) * 652;
+}
+
+function formatNumber(value: number): string {
+  return new Intl.NumberFormat(undefined, { maximumFractionDigits: 1 }).format(value);
+}

package/src/tool/lexical-coverage-vocabulary-calculator/entry.ts

@@ -0,0 +1,34 @@
+import type { LanguageToolEntry, ToolDefinition, ToolLocaleContent } from '../../types';
+import type { LexicalCoverageUI } from './ui';
+
+export type { LexicalCoverageUI } from './ui';
+export type LexicalCoverageVocabularyCalculatorLocaleContent = ToolLocaleContent<LexicalCoverageUI>;
+
+export const lexicalCoverageVocabularyCalculator: LanguageToolEntry<LexicalCoverageUI> = {
+  id: 'lexical-coverage-vocabulary-calculator',
+  icons: { bg: 'mdi:book-search-outline', fg: 'mdi:translate-variant' },
+  i18n: {
+    de: () => import('./i18n/de').then((module) => module.content),
+    en: () => import('./i18n/en').then((module) => module.content),
+    es: () => import('./i18n/es').then((module) => module.content),
+    fr: () => import('./i18n/fr').then((module) => module.content),
+    id: () => import('./i18n/id').then((module) => module.content),
+    it: () => import('./i18n/it').then((module) => module.content),
+    ja: () => import('./i18n/ja').then((module) => module.content),
+    ko: () => import('./i18n/ko').then((module) => module.content),
+    nl: () => import('./i18n/nl').then((module) => module.content),
+    pl: () => import('./i18n/pl').then((module) => module.content),
+    pt: () => import('./i18n/pt').then((module) => module.content),
+    ru: () => import('./i18n/ru').then((module) => module.content),
+    sv: () => import('./i18n/sv').then((module) => module.content),
+    tr: () => import('./i18n/tr').then((module) => module.content),
+    zh: () => import('./i18n/zh').then((module) => module.content),
+  },
+};
+
+export const LEXICAL_COVERAGE_VOCABULARY_CALCULATOR_TOOL: ToolDefinition = {
+  entry: lexicalCoverageVocabularyCalculator,
+  Component: () => import('./component.astro'),
+  SEOComponent: () => import('./seo.astro'),
+  BibliographyComponent: () => import('./bibliography.astro'),
+};

package/src/tool/lexical-coverage-vocabulary-calculator/evaluator.ts

@@ -0,0 +1,13 @@
+import type { CoverageStatus, LexicalCoveragePlan } from './types';
+
+export interface CoverageEvaluation {
+  status: CoverageStatus;
+  tone: 'warn' | 'good' | 'strong';
+  messageKey: 'belowTarget' | 'atTarget' | 'buffer';
+}
+
+export function evaluateLexicalCoverage(plan: LexicalCoveragePlan): CoverageEvaluation {
+  if (plan.status === 'below-target') return { status: plan.status, tone: 'warn', messageKey: 'belowTarget' };
+  if (plan.status === 'at-target') return { status: plan.status, tone: 'good', messageKey: 'atTarget' };
+  return { status: plan.status, tone: 'strong', messageKey: 'buffer' };
+}

package/src/tool/lexical-coverage-vocabulary-calculator/i18n/de.ts

@@ -0,0 +1,13 @@
+import type { FAQPage, HowTo, SoftwareApplication } from 'schema-dts';
+import type { ToolLocaleContent } from '../../../types';
+import type { LexicalCoverageUI } from '../ui';
+
+const ui: LexicalCoverageUI = { contentType: 'Was möchtest du verstehen?', conversation: 'Alltagsgespräche', travel: 'Reisen und Alltag', media: 'Filme und Serien', generalReading: 'Allgemeines Lesen', novels: 'Romane', business: 'Business und Arbeit', academic: 'Akademische Texte', knownWords: 'Bereits bekannte Wörter', knownWordsHint: 'Nutze möglichst eine begründete Schätzung. Zähle Wortfamilien oder Lemmata konsequent.', targetCoverage: 'Gewünschte Abdeckung', coverage80: 'Erste Orientierung', coverage90: 'Dem Faden folgen', coverage95: 'Mit Unterstützung lesen', coverage98: 'Selbstständig lesen', resetButton: 'Zurücksetzen', quickStart: 'Schnellstart', conversationPreset: 'Gespräch', readingPreset: 'Roman', workPreset: 'Arbeit', resultTitle: 'Deine Wortschatzkarte', emptyResult: 'Wähle einen Inhalt und gib deinen bekannten Wortschatz ein, um den nächsten sinnvollen Meilenstein zu sehen.', checkInputs: 'Prüfe deine Eingaben', invalidWords: 'Gib zwischen 0 und 50.000 bekannte Wörter ein.', invalidContentType: 'Wähle einen verfügbaren Inhaltstyp.', invalidCoverage: 'Wähle ein Ziel zwischen 80 % und 98 %.', belowTarget: 'Du liegst unter dem gewählten Abdeckungsband. Die Lücke ist dein nächstes Wortschatzprojekt.', atTarget: 'Du hast das gewählte Planungsband erreicht. Halte thematische Wörter griffbereit.', buffer: 'Du hast für diesen Inhaltstyp einen guten Puffer. Prüfe jetzt echte Texte aus deinem Zielbereich.', recommendedWords: 'Wörter für dein Ziel', vocabularyKnown: 'Gezählte Wörter', estimatedCoverage: 'Geschätzte Abdeckung', gapWords: 'Wörter bis zum Ziel', unknownPerHundred: 'Unbekannt je 100', coverageRoute: 'Leseroute von häufigen Wörtern zum selbstständigen Lesen', nextCheckpoint: 'Nächster Meilenstein', noMoreCheckpoints: 'Du liegst über dem höchsten Meilenstein dieses Planungsmodells.', words: 'Wörter', wordUnit: 'Wörter', unknownWords: 'unbekannt', targetMarker: 'Ziel', coverageNote: 'Abdeckung bezeichnet den Anteil der laufenden Wörter eines Textes, den dein Wortschatz erkennt. Sie ist nicht dasselbe wie vollständiges Sprachverständnis.', wordFamilyNote: 'Forschung zählt oft Wortfamilien, während Apps Lemmata oder Formen zählen. Vergleiche deshalb nur gleiche Einheiten.', contentTypeHelp: 'Das Genre verändert die Schwelle: Häufige Gesprächswörter kommen früher, Romane, Arbeit und Studium bringen seltenere Fachwörter.', interpretationTitle: 'So nutzt du die Karte', actionBelow: 'Erstelle aus echten Gesprächen, Büchern oder Arbeitsdokumenten eine fokussierte Liste und lerne wiederkehrende Wörter in Phrasen.', actionAt: 'Prüfe eine Seite oder ein Transkript aus deinem Zielgenre und ergänze wiederkehrende unbekannte Wörter.', actionBuffer: 'Sammle weniger Einzelwörter und mehr Wendungen, Kollokationen und Fachwortschatz für deinen nächsten Text.' };
+const faq = [{ question: 'Was schätzt der Rechner für lexikalische Abdeckung?', answer: 'Er schätzt eine nützliche Wortschatzgröße für Gespräche, Medien, Romane, Arbeit oder Studium bei 80 %, 90 %, 95 % oder 98 % Abdeckung und zeigt die nächste Schwelle.' }, { question: 'Warum braucht ein Roman mehr Wörter als ein Gespräch?', answer: 'Gesprochene Alltagssprache wiederholt häufige Wörter. Romane und Fachtexte enthalten mehr seltene, thematische und formelhafte Ausdrücke, sodass dieselbe Wortzahl weniger Text abdeckt.' }, { question: 'Bedeutet 80 % Abdeckung, dass ich 80 % des Sinns verstehe?', answer: 'Nein. Die Zahl beschreibt den Anteil erkannter laufender Wörter. Fehlende Schlüsselwörter, Grammatik, Vorwissen, Aussprache und Sprechtempo beeinflussen das Verständnis zusätzlich.' }, { question: 'Soll ich Wörter, Lemmata oder Wortfamilien zählen?', answer: 'Wähle eine Einheit und bleibe dabei. Forschung berichtet oft Wortfamilien, Apps dagegen Lemmata oder Wortformen. Diese Zahlen sind nicht direkt austauschbar.' }, { question: 'Was mache ich mit der Lücke?', answer: 'Nimm kurze Proben aus deinem Zielgenre, notiere wiederkehrende Wörter und lerne sie in Phrasen. Prüfe nach dem Wiederholen erneut eine ähnliche Probe.' }];
+const howTo = [{ name: 'Inhalt wählen', text: 'Wähle den Inhalt, den du als Nächstes verstehen möchtest.' }, { name: 'Wortschatz schätzen', text: 'Gib eine konsistente Schätzung der Wörter, Lemmata oder Wortfamilien ein, die du erkennst.' }, { name: 'Abdeckung festlegen', text: 'Wähle ein Planungsband von erster Orientierung bis selbstständigem Lesen.' }, { name: 'Lücke nutzen', text: 'Baue mit der Lücke und dem nächsten Meilenstein eine Liste aus echten Texten deines Genres.' }];
+const appSchema: SoftwareApplication = { '@type': 'SoftwareApplication', name: 'Rechner für lexikalische Abdeckung und Wortschatz', applicationCategory: 'EducationalApplication', operatingSystem: 'Any', isAccessibleForFree: true, url: 'https://gamebob.dev/de/lexikalische-abdeckung-wortschatz-rechner' };
+const howToSchema: HowTo = { '@type': 'HowTo', name: 'Benötigten Wortschatz nach Inhalt schätzen', step: howTo.map((item) => ({ '@type': 'HowToStep', ...item })) };
+const faqSchema: FAQPage = { '@type': 'FAQPage', mainEntity: faq.map((item) => ({ '@type': 'Question', name: item.question, acceptedAnswer: { '@type': 'Answer', text: item.answer } })) };
+const withContext = (schema: SoftwareApplication | HowTo | FAQPage): Record<string, unknown> => ({ '@context': 'https://schema.org', ...schema });
+
+export const content: ToolLocaleContent<LexicalCoverageUI> = { slug: 'lexikalische-abdeckung-wortschatz-rechner', title: 'Rechner für lexikalische Abdeckung und Wortschatz', description: 'Schätze den nötigen Wortschatz für Gespräche, Romane, Arbeit, Medien und Studium anhand einer verständlichen Abdeckungsschwelle.', ui, seo: [{ type: 'title', text: 'Wortschatz nach Inhalt sinnvoll planen', level: 2 }, { type: 'paragraph', html: 'Ein kleiner Kern häufiger Wörter kann Gespräche öffnen, deckt aber einen Roman oder Fachtext nicht im gleichen Maß ab. Dieser Rechner verbindet dein Zielgenre mit einer konkreten Wortzahl und zeigt die nächste erreichbare Schwelle.' }, { type: 'title', text: 'Was lexikalische Abdeckung misst', level: 2 }, { type: 'paragraph', html: 'Lexikalische Abdeckung ist der Anteil laufender Wörter in einer Textprobe, den dein bekannter Wortschatz erkennt. 80 %, 90 %, 95 % und 98 % sind Planungsbänder, keine Prüfung und keine Garantie für vollständiges Verstehen.' }, { type: 'title', text: 'Warum das Genre die Zahl verändert', level: 2 }, { type: 'table', headers: ['Inhalt', 'Planung bei 80 %', 'Planung bei 95 %', 'Typische Ergänzung'], rows: [['Alltagsgespräch', '2.000 Wörter', '4.500 Wörter', 'Routinen und häufige Wendungen'], ['Filme und Serien', '3.000 Wörter', '6.000 Wörter', 'Dialog, Umgangssprache und Themenwechsel'], ['Romane', '5.000 Wörter', '8.000 Wörter', 'Erzählung, Beschreibung und Genrewörter'], ['Arbeit', '5.000 Wörter', '8.000 Wörter', 'Fachbegriffe und Dokumentformeln'], ['Akademische Texte', '6.000 Wörter', '10.000 Wörter', 'Abstrakte und disziplinspezifische Begriffe']] }, { type: 'title', text: 'Aus der Lücke eine Lernentscheidung machen', level: 2 }, { type: 'paragraph', html: 'Wenn du unter dem Band liegst, sammle nicht wahllos Wörter. Nimm eine kurze Probe aus dem echten Inhalt, behalte wiederkehrende oder bedeutungsentscheidende Wörter und lerne sie als Teil einer Wendung.' }, { type: 'list', items: ['Wähle das Genre deiner nächsten realen Aufgabe.', 'Zähle immer dieselbe Einheit.', 'Priorisiere Wörter, die in mehreren Proben wiederkehren.', 'Prüfe dieselbe Textsorte nach dem Lernen erneut.'] }, { type: 'tip', title: 'Evidenz und Grenzen', html: 'Die Referenz von 2.000 Wörtern bei 80 % stammt aus Forschung zu Wortfrequenz und Textabdeckung. Höhere schriftsprachliche Werte unterscheiden sich nach Korpus und Genre. Sprache, Morphologie, Eigennamen, Vorwissen, Grammatik und Tempo bleiben wichtige Faktoren.' }], faq, bibliography: [{ name: 'Paul Nation, How Large a Vocabulary Is Needed for Reading and Listening?', url: 'https://www.scienceguide.nl/wp-content/uploads/2017/11/nation-2006-vocabulary.pdf' }, { name: 'Izquierdo Gil, La selección del léxico en la enseñanza del español como lengua extranjera', url: 'https://asele.org/media/2025/03/8izquierdogilm-adelcarmenlaselecciondellexicoenlaensananza.pdf' }], howTo, schemas: [withContext(appSchema), withContext(faqSchema), withContext(howToSchema)] };