@jjlmoya/utils-language 1.1.0

package/src/tool/language-learning-study-plan-planner/language-learning-study-plan-planner.css

@@ -0,0 +1,403 @@
+.language-planner {
+  --planner-surface: var(--bg-surface);
+  --planner-muted: var(--text-muted);
+  --planner-line: var(--border-base);
+  --planner-control: var(--bg-muted);
+  --planner-accent: var(--primary);
+  --planner-accent-soft: var(--primary-bg);
+  --planner-shadow: var(--shadow-base);
+  --planner-success: var(--color-success);
+  --planner-warning: var(--color-warning);
+  --planner-danger: var(--color-error);
+
+  display: grid;
+  gap: 1rem;
+  grid-template-columns: minmax(290px, 0.9fr) minmax(400px, 1.1fr);
+  padding: clamp(1.25rem, 3vw, 2.25rem);
+  background: var(--planner-surface);
+  border: 1px solid var(--planner-line);
+  border-radius: 1.25rem;
+  box-shadow: 0 1rem 2.5rem var(--planner-shadow);
+  color: var(--text-base);
+}
+
+.planner-editor,
+.planner-output {
+  min-width: 0;
+}
+
+.planner-output {
+  padding-left: clamp(1rem, 3vw, 2rem);
+  border-left: 1px solid var(--planner-line);
+}
+
+.form-intro,
+.result-heading,
+.form-actions,
+.preset-row,
+.output-heading {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.form-intro {
+  align-items: flex-start;
+  margin-bottom: 1.4rem;
+}
+
+.eyebrow,
+.section-title,
+.metric-label,
+.allocation-label,
+.status-label,
+.milestone-hours {
+  margin: 0;
+  color: var(--planner-accent);
+  font-size: 0.7rem;
+  font-weight: 900;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+}
+
+.form-intro h2,
+.empty-result h2,
+.error-result h2,
+.output-heading h2 {
+  margin: 0.45rem 0;
+  font-size: clamp(1.5rem, 3vw, 2.4rem);
+  letter-spacing: -0.05em;
+  line-height: 1;
+}
+
+.form-note,
+.empty-result p,
+.error-result p {
+  max-width: 27rem;
+  margin: 0;
+  color: var(--planner-muted);
+  font-size: 0.85rem;
+  line-height: 1.5;
+}
+
+.form-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 0 0.7rem;
+}
+
+.form-grid label {
+  display: grid;
+  gap: 0.35rem;
+  margin: 0.85rem 0 0.4rem;
+  font-size: 0.78rem;
+  font-weight: 800;
+}
+
+.wide-field {
+  grid-column: span 2;
+}
+
+select,
+input {
+  width: 100%;
+  min-height: 2.85rem;
+  box-sizing: border-box;
+  padding: 0.7rem;
+  border: 1px solid var(--planner-line);
+  border-radius: 0.6rem;
+  background: var(--planner-control);
+  color: var(--text-base);
+  font: inherit;
+}
+
+select {
+  appearance: auto;
+}
+
+select:focus-visible,
+input:focus-visible,
+button:focus-visible {
+  outline: 3px solid var(--planner-accent-soft);
+  outline-offset: 2px;
+}
+
+button {
+  cursor: pointer;
+  border: 1px solid var(--planner-line);
+  border-radius: 999px;
+  background: var(--planner-control);
+  color: var(--text-base);
+  font: inherit;
+  font-size: 0.75rem;
+  font-weight: 800;
+  padding: 0.55rem 0.75rem;
+}
+
+button:hover {
+  border-color: var(--planner-accent);
+}
+
+.preset-row {
+  justify-content: flex-start;
+  flex-wrap: wrap;
+  margin-top: 1rem;
+  padding-top: 1rem;
+  border-top: 1px solid var(--planner-line);
+}
+
+.preset-row > span {
+  color: var(--planner-muted);
+  font-size: 0.78rem;
+  font-weight: 800;
+}
+
+.preset-row button,
+.text-button {
+  border-color: transparent;
+  background: var(--planner-accent-soft);
+  color: var(--planner-accent);
+}
+
+.form-actions {
+  justify-content: flex-start;
+  margin-top: 1.25rem;
+  padding-top: 1.25rem;
+  border-top: 1px solid var(--planner-line);
+}
+
+.primary-button {
+  border-color: var(--planner-accent);
+  border-radius: 0.6rem;
+  background: var(--planner-accent);
+  color: var(--text-on-primary, #fff);
+  padding: 0.8rem 1.1rem;
+}
+
+.text-button {
+  padding: 0.45rem 0.7rem;
+}
+
+.output-heading {
+  align-items: flex-start;
+  margin-bottom: 1.4rem;
+}
+
+.live-badge {
+  padding: 0.4rem 0.6rem;
+  border-radius: 999px;
+  background: var(--planner-accent-soft);
+  color: var(--planner-accent);
+  font-size: 0.62rem;
+  font-weight: 900;
+  letter-spacing: 0.1em;
+}
+
+.empty-result,
+.error-result {
+  display: flex;
+  min-height: 13rem;
+  flex-direction: column;
+  align-items: flex-start;
+  justify-content: center;
+  gap: 1rem;
+}
+
+.route-mark {
+  display: grid;
+  width: 3.2rem;
+  height: 3.2rem;
+  place-items: center;
+  border-radius: 50%;
+  background: var(--planner-accent);
+  color: var(--text-on-primary, #fff);
+  font-size: 1.8rem;
+}
+
+.error-result {
+  min-height: auto;
+  padding: 1rem;
+  border: 1px solid var(--planner-danger);
+  border-left-width: 4px;
+  border-radius: 0.75rem;
+  background: var(--planner-control);
+}
+
+.error-result h2 {
+  color: var(--planner-danger);
+  font-size: 1.2rem;
+}
+
+.plan-result {
+  display: grid;
+  gap: 1.5rem;
+}
+
+.status-banner {
+  display: grid;
+  gap: 0.35rem;
+  padding: 1rem;
+  border: 1px solid currentcolor;
+  border-left-width: 4px;
+  border-radius: 0.5rem;
+  background: var(--planner-control);
+}
+
+.status-banner.on-track {
+  color: var(--planner-success);
+}
+
+.status-banner.tight {
+  color: var(--planner-warning);
+}
+
+.status-banner.insufficient {
+  color: var(--planner-danger);
+}
+
+.status-copy {
+  color: var(--text-base);
+  line-height: 1.45;
+}
+
+.result-heading {
+  align-items: flex-end;
+}
+
+.result-level {
+  font-size: clamp(1.4rem, 3vw, 2.25rem);
+  font-weight: 850;
+  line-height: 1;
+  text-align: right;
+}
+
+.metric-grid,
+.allocation-grid {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 0.75rem;
+}
+
+.metric-card {
+  display: grid;
+  gap: 0.45rem;
+  padding: 0.8rem 0;
+  border-top: 3px solid var(--planner-accent);
+}
+
+.metric-label,
+.allocation-label,
+.section-title {
+  color: var(--planner-muted);
+}
+
+.metric-value {
+  font-size: clamp(1.2rem, 2.5vw, 1.8rem);
+  font-weight: 850;
+}
+
+.metric-detail,
+.milestone-date {
+  color: var(--planner-muted);
+  font-size: 0.72rem;
+}
+
+.allocation-section,
+.milestones-section {
+  display: grid;
+  gap: 0.75rem;
+}
+
+.allocation-item {
+  display: grid;
+  gap: 0.35rem;
+  padding: 0.75rem 0;
+  border-bottom: 3px solid var(--planner-accent);
+}
+
+.allocation-time {
+  font-size: 1.1rem;
+  font-weight: 800;
+}
+
+.milestone-list {
+  display: grid;
+  gap: 0.65rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.milestone-list li {
+  display: grid;
+  grid-template-columns: 1fr auto auto;
+  align-items: center;
+  gap: 1rem;
+  padding: 0.8rem 0;
+  border-top: 1px solid var(--planner-line);
+}
+
+.milestone-level {
+  font-weight: 800;
+}
+
+@media (max-width: 820px) {
+  .language-planner {
+    grid-template-columns: 1fr;
+  }
+
+  .planner-output {
+    padding-top: 1.5rem;
+    padding-left: 0;
+    border-top: 1px solid var(--planner-line);
+    border-left: 0;
+  }
+}
+
+@media (max-width: 700px) {
+  .form-intro,
+  .result-heading {
+    display: grid;
+  }
+
+  .form-grid,
+  .metric-grid,
+  .allocation-grid {
+    grid-template-columns: 1fr 1fr;
+  }
+
+  .wide-field {
+    grid-column: span 2;
+  }
+
+  .milestone-list li {
+    grid-template-columns: 1fr auto;
+  }
+
+  .milestone-hours {
+    grid-column: 1 / -1;
+  }
+}
+
+@media (max-width: 460px) {
+  .form-grid,
+  .metric-grid,
+  .allocation-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .wide-field {
+    grid-column: auto;
+  }
+
+  .form-actions {
+    align-items: stretch;
+    flex-direction: column;
+  }
+
+  .primary-button,
+  .text-button {
+    width: 100%;
+  }
+}

package/src/tool/language-learning-study-plan-planner/logic.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import { calculateStudyPlan, validateInputs } from './logic';
+import type { LanguagePlannerInputs } from './types';
+
+const TODAY = new Date('2026-08-29T12:00:00Z');
+
+const baseInputs: LanguagePlannerInputs = {
+  sourceLanguage: 'English',
+  targetLanguage: 'Spanish',
+  currentLevel: 'A1',
+  targetLevel: 'B1',
+  targetDate: '2027-08-29',
+  weeklyHours: 5,
+  priority: 'balanced',
+};
+
+describe('calculateStudyPlan', () => {
+  it('calculates a range, available time, and level milestones', () => {
+    const result = calculateStudyPlan(baseInputs, TODAY);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.plan.hoursLow).toBe(260);
+    expect(result.plan.hoursHigh).toBe(300);
+    expect(result.plan.weeksRemaining).toBe(53);
+    expect(result.plan.availableHours).toBe(265);
+    expect(result.plan.status).toBe('tight');
+    expect(result.plan.milestones.map((milestone) => milestone.level)).toEqual(['A2', 'B1']);
+  });
+
+  it('handles the beginner boundary and a short deadline', () => {
+    const result = calculateStudyPlan({ ...baseInputs, currentLevel: 'A0', targetLevel: 'A1', targetDate: '2026-11-27', weeklyHours: 10 }, TODAY);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.plan.hoursLow).toBe(90);
+    expect(result.plan.hoursHigh).toBe(100);
+    expect(result.plan.status).toBe('on-track');
+  });
+
+  it('reports insufficient time without pretending the goal is guaranteed', () => {
+    const result = calculateStudyPlan({ ...baseInputs, targetLevel: 'C2', targetDate: '2026-09-12', weeklyHours: 1 }, TODAY);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.plan.status).toBe('insufficient');
+    expect(result.plan.recommendedWeeklyHoursHigh).toBe(550);
+  });
+});
+
+describe('validateInputs', () => {
+  it('rejects same languages, reversed levels, invalid dates, and impossible schedules', () => {
+    expect(validateInputs({ ...baseInputs, targetLanguage: 'English' }, TODAY)).toContain('different');
+    expect(validateInputs({ ...baseInputs, currentLevel: 'B2', targetLevel: 'A2' }, TODAY)).toContain('above');
+    expect(validateInputs({ ...baseInputs, targetDate: '2026-02-30' }, TODAY)).toContain('valid target date');
+    expect(validateInputs({ ...baseInputs, weeklyHours: 0.25 }, TODAY)).toContain('between 0.5 and 40');
+    expect(validateInputs({ ...baseInputs, targetDate: '2026-08-29' }, TODAY)).toContain('future');
+  });
+});

package/src/tool/language-learning-study-plan-planner/logic.ts

@@ -0,0 +1,157 @@
+import type {
+  LanguagePlannerInputs,
+  PlanStatus,
+  SkillAllocation,
+  StudyLevel,
+  StudyMilestone,
+  StudyPlan,
+} from './types';
+
+export const STUDY_LEVELS: StudyLevel[] = ['A0', 'A1', 'A2', 'B1', 'B2', 'C1', 'C2'];
+
+export const LEVEL_LABELS: Record<StudyLevel, string> = {
+  A0: 'Pre-A1',
+  A1: 'A1',
+  A2: 'A2',
+  B1: 'B1',
+  B2: 'B2',
+  C1: 'C1',
+  C2: 'C2',
+};
+
+export const GUIDED_HOURS_FROM_BEGINNER: Record<StudyLevel, readonly [number, number]> = {
+  A0: [0, 0],
+  A1: [90, 100],
+  A2: [180, 200],
+  B1: [350, 400],
+  B2: [500, 600],
+  C1: [700, 800],
+  C2: [1000, 1200],
+};
+
+export const PRIORITY_ALLOCATIONS: Record<'balanced' | 'comprehension' | 'production', SkillAllocation> = {
+  balanced: { listening: 25, speaking: 25, reading: 25, writing: 25 },
+  comprehension: { listening: 35, speaking: 15, reading: 35, writing: 15 },
+  production: { listening: 15, speaking: 35, reading: 15, writing: 35 },
+};
+
+export type StudyPlanResult = { ok: true; plan: StudyPlan } | { ok: false; error: string };
+
+export function calculateStudyPlan(inputs: LanguagePlannerInputs, today = new Date()): StudyPlanResult {
+  const validationError = validateInputs(inputs, today);
+  if (validationError) return { ok: false, error: validationError };
+
+  const currentIndex = STUDY_LEVELS.indexOf(inputs.currentLevel);
+  const targetIndex = STUDY_LEVELS.indexOf(inputs.targetLevel);
+  const todayDate = startOfDay(today);
+  const hours = getHoursNeeded(inputs.currentLevel, inputs.targetLevel);
+  const schedule = getSchedule(inputs, todayDate);
+  const milestones = createMilestones(inputs, currentIndex, targetIndex, todayDate);
+
+  return {
+    ok: true,
+    plan: {
+      inputs,
+      weeksRemaining: schedule.weeksRemaining,
+      availableHours: schedule.availableHours,
+      hoursLow: hours.low,
+      hoursHigh: hours.high,
+      recommendedWeeklyHoursLow: round(hours.low / schedule.weeksRemaining, 1),
+      recommendedWeeklyHoursHigh: round(hours.high / schedule.weeksRemaining, 1),
+      allocation: PRIORITY_ALLOCATIONS[inputs.priority],
+      status: getStatus(schedule.availableHours, hours.low, hours.high),
+      milestones,
+    },
+  };
+}
+
+export function validateInputs(inputs: LanguagePlannerInputs, today = new Date()): string | null {
+  const languageError = validateLanguages(inputs);
+  if (languageError) return languageError;
+  const levelError = validateLevels(inputs);
+  if (levelError) return levelError;
+  const scheduleError = validateSchedule(inputs, today);
+  if (scheduleError) return scheduleError;
+  return null;
+}
+
+function validateLanguages(inputs: LanguagePlannerInputs): string | null {
+  if (!inputs.sourceLanguage || !inputs.targetLanguage) return 'Choose both a starting language and a target language.';
+  if (inputs.sourceLanguage === inputs.targetLanguage) return 'Choose different starting and target languages.';
+  return null;
+}
+
+function validateLevels(inputs: LanguagePlannerInputs): string | null {
+  if (!STUDY_LEVELS.includes(inputs.currentLevel) || !STUDY_LEVELS.includes(inputs.targetLevel)) return 'Choose valid CEFR levels.';
+  if (STUDY_LEVELS.indexOf(inputs.targetLevel) <= STUDY_LEVELS.indexOf(inputs.currentLevel)) return 'Your target level must be above your current level.';
+  return null;
+}
+
+function validateSchedule(inputs: LanguagePlannerInputs, today: Date): string | null {
+  if (!Number.isFinite(inputs.weeklyHours) || inputs.weeklyHours < 0.5 || inputs.weeklyHours > 40) return 'Weekly study time must be between 0.5 and 40 hours.';
+  const targetDate = parseDate(inputs.targetDate);
+  if (!targetDate) return 'Choose a valid target date.';
+  if (targetDate.getTime() <= startOfDay(today).getTime()) return 'Choose a target date in the future.';
+  return null;
+}
+
+function getHoursNeeded(currentLevel: StudyLevel, targetLevel: StudyLevel) {
+  const [currentLow, currentHigh] = GUIDED_HOURS_FROM_BEGINNER[currentLevel];
+  const [targetLow, targetHigh] = GUIDED_HOURS_FROM_BEGINNER[targetLevel];
+  return { low: targetLow - currentLow, high: targetHigh - currentHigh };
+}
+
+function getSchedule(inputs: LanguagePlannerInputs, today: Date) {
+  const targetDate = parseDate(inputs.targetDate)!;
+  const daysRemaining = Math.floor((targetDate.getTime() - today.getTime()) / 86_400_000);
+  const weeksRemaining = Math.max(1, Math.ceil(daysRemaining / 7));
+  return { weeksRemaining, availableHours: round(inputs.weeklyHours * weeksRemaining, 1) };
+}
+
+function createMilestones(inputs: LanguagePlannerInputs, currentIndex: number, targetIndex: number, today: Date): StudyMilestone[] {
+  return STUDY_LEVELS.slice(currentIndex + 1, targetIndex + 1).map((level, offset) => {
+    const previousLevel = STUDY_LEVELS[currentIndex + offset]!;
+    const [previousLow, previousHigh] = GUIDED_HOURS_FROM_BEGINNER[previousLevel];
+    const [levelLow, levelHigh] = GUIDED_HOURS_FROM_BEGINNER[level];
+    const midpointHours = ((levelLow - previousLow) + (levelHigh - previousHigh)) / 2;
+    const week = Math.max(1, Math.ceil(midpointHours / inputs.weeklyHours));
+    return {
+      level,
+      hoursLow: levelLow - previousLow,
+      hoursHigh: levelHigh - previousHigh,
+      week,
+      date: formatDate(addDays(today, week * 7)),
+    };
+  });
+}
+
+function getStatus(availableHours: number, hoursLow: number, hoursHigh: number): PlanStatus {
+  if (availableHours < hoursLow) return 'insufficient';
+  if (availableHours < hoursHigh) return 'tight';
+  return 'on-track';
+}
+
+function parseDate(value: string): Date | null {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return null;
+  const date = new Date(`${value}T00:00:00Z`);
+  return Number.isNaN(date.getTime()) || formatDate(date) !== value ? null : date;
+}
+
+function startOfDay(date: Date): Date {
+  return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+}
+
+function addDays(date: Date, days: number): Date {
+  const result = new Date(date);
+  result.setUTCDate(result.getUTCDate() + days);
+  return result;
+}
+
+function formatDate(date: Date): string {
+  return date.toISOString().slice(0, 10);
+}
+
+function round(value: number, decimals: number): number {
+  const factor = 10 ** decimals;
+  return Math.round(value * factor) / factor;
+}

package/src/tool/language-learning-study-plan-planner/seo.astro

@@ -0,0 +1,9 @@
+---
+import { SEORenderer } from '@jjlmoya/utils-shared';
+import { languageLearningStudyPlanPlanner } from './entry';
+
+const locale = Astro.props.locale ?? 'en';
+const content = await languageLearningStudyPlanPlanner.i18n.en?.();
+---
+
+{content && <SEORenderer content={{ locale, sections: content.seo }} />}

package/src/tool/language-learning-study-plan-planner/types.ts

@@ -0,0 +1,42 @@
+export type StudyLevel = 'A0' | 'A1' | 'A2' | 'B1' | 'B2' | 'C1' | 'C2';
+export type StudyPriority = 'balanced' | 'comprehension' | 'production';
+
+export interface LanguagePlannerInputs {
+  sourceLanguage: string;
+  targetLanguage: string;
+  currentLevel: StudyLevel;
+  targetLevel: StudyLevel;
+  targetDate: string;
+  weeklyHours: number;
+  priority: StudyPriority;
+}
+
+export interface SkillAllocation {
+  listening: number;
+  speaking: number;
+  reading: number;
+  writing: number;
+}
+
+export interface StudyMilestone {
+  level: StudyLevel;
+  hoursLow: number;
+  hoursHigh: number;
+  week: number;
+  date: string;
+}
+
+export type PlanStatus = 'on-track' | 'tight' | 'insufficient';
+
+export interface StudyPlan {
+  inputs: LanguagePlannerInputs;
+  weeksRemaining: number;
+  availableHours: number;
+  hoursLow: number;
+  hoursHigh: number;
+  recommendedWeeklyHoursLow: number;
+  recommendedWeeklyHoursHigh: number;
+  allocation: SkillAllocation;
+  status: PlanStatus;
+  milestones: StudyMilestone[];
+}

package/src/tool/language-learning-study-plan-planner/ui.ts

@@ -0,0 +1,46 @@
+export interface LanguagePlannerUI extends Record<string, string> {
+  plannerKicker: string;
+  plannerHeading: string;
+  sourceLanguage: string;
+  targetLanguage: string;
+  currentLevel: string;
+  targetLevel: string;
+  targetDate: string;
+  weeklyHours: string;
+  priority: string;
+  balanced: string;
+  comprehension: string;
+  production: string;
+  planButton: string;
+  resetButton: string;
+  presetsLabel: string;
+  casualPreset: string;
+  steadyPreset: string;
+  sprintPreset: string;
+  plannerNote: string;
+  resultTitle: string;
+  liveLabel: string;
+  hoursRange: string;
+  weeksAvailable: string;
+  hoursAvailable: string;
+  recommendedTime: string;
+  onTrack: string;
+  tight: string;
+  insufficient: string;
+  statusLabel: string;
+  weeklyAllocation: string;
+  milestones: string;
+  skillListening: string;
+  skillSpeaking: string;
+  skillReading: string;
+  skillWriting: string;
+  milestoneTarget: string;
+  milestoneWeek: string;
+  errorPrefix: string;
+  languageOptions: string;
+  emptyResultDescription: string;
+  guidedLearningDetail: string;
+  targetDateDetail: string;
+  weeklyPaceDetail: string;
+  recommendedRangeDetail: string;
+}