@jjlmoya/utils-language 1.8.0 → 1.10.0

package/src/tool/language-shadowing-session-planner/language-shadowing-session-planner.css

@@ -0,0 +1,561 @@
+:root {
+  --n-base-bg: #f5efe5;
+  --n-base-surface: #fffaf2;
+  --n-base-surface-raised: #fffdf8;
+  --n-base-ink: #2c2723;
+  --n-base-muted: #756b62;
+  --n-base-line: #d8cbbd;
+  --n-base-track: #eadfd2;
+  --n-base-accent: #d65a3d;
+  --n-base-accent-deep: #963b2c;
+  --n-base-action-bg: #b13d25;
+  --n-base-action-ink: #fffaf2;
+  --n-base-action-hover: #963b2c;
+  --n-base-disabled-ink: #5d5148;
+  --n-base-blue: #477a89;
+  --n-base-gold: #c7953d;
+  --n-base-good: #37745d;
+  --n-base-stage: #efe5d9;
+  --n-base-shadow: rgba(77, 52, 38, 0.12);
+}
+
+.theme-dark {
+  --n-base-bg: #17181b;
+  --n-base-surface: #202226;
+  --n-base-surface-raised: #282a2f;
+  --n-base-ink: #f6efe5;
+  --n-base-muted: #b7aaa0;
+  --n-base-line: #464148;
+  --n-base-track: #343238;
+  --n-base-accent: #f07a58;
+  --n-base-accent-deep: #f6efe5;
+  --n-base-action-bg: #f6efe5;
+  --n-base-action-ink: #17181b;
+  --n-base-action-hover: #fffaf2;
+  --n-base-disabled-ink: #d2c7bd;
+  --n-base-blue: #77b4c3;
+  --n-base-gold: #e1b25b;
+  --n-base-good: #82c5a4;
+  --n-base-stage: #2a2927;
+  --n-base-shadow: rgba(0, 0, 0, 0.28);
+}
+
+.shadowing-tool {
+  --n-bg: var(--n-base-bg);
+  --n-surface: var(--n-base-surface);
+  --n-surface-raised: var(--n-base-surface-raised);
+  --n-ink: var(--n-base-ink);
+  --n-muted: var(--n-base-muted);
+  --n-line: var(--n-base-line);
+  --n-track: var(--n-base-track);
+  --n-accent: var(--n-base-accent);
+  --n-accent-deep: var(--n-base-accent-deep);
+  --n-action-bg: var(--n-base-action-bg);
+  --n-action-ink: var(--n-base-action-ink);
+  --n-action-hover: var(--n-base-action-hover);
+  --n-disabled-ink: var(--n-base-disabled-ink);
+  --n-blue: var(--n-base-blue);
+  --n-gold: var(--n-base-gold);
+  --n-good: var(--n-base-good);
+  --n-stage: var(--n-base-stage);
+  --n-shadow: var(--n-base-shadow);
+
+  display: grid;
+  grid-template-columns: minmax(250px, 0.75fr) minmax(360px, 1.25fr);
+  overflow: hidden;
+  border: 2px solid var(--n-line);
+  border-radius: 1.5rem;
+  background: var(--n-bg);
+  color: var(--n-ink);
+  box-shadow: 0 0.35rem 0.8rem var(--n-shadow);
+  isolation: isolate;
+}
+
+.shadowing-controls,
+.shadowing-result {
+  min-width: 0;
+  padding: clamp(1.25rem, 3vw, 2.5rem);
+}
+
+.shadowing-controls {
+  display: flex;
+  flex-direction: column;
+  gap: 1.5rem;
+  border-right: 1px solid var(--n-line);
+  background: var(--n-surface);
+}
+
+.quick-starts,
+.field-grid {
+  display: grid;
+  gap: 0.7rem;
+}
+
+.control-label,
+.result-kicker,
+.timeline-heading,
+.metric-strip span,
+.input-help,
+.budget-note,
+.timeline-legend,
+.field-value {
+  font-size: 0.72rem;
+  letter-spacing: 0.06em;
+  line-height: 1.35;
+  text-transform: uppercase;
+}
+
+.control-label,
+.result-kicker,
+.timeline-heading,
+.metric-strip span,
+.timeline-legend,
+.field-value {
+  color: var(--n-muted);
+}
+
+.quick-start-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 0.45rem;
+}
+
+.quick-start,
+.reset-button {
+  border: 1px solid var(--n-line);
+  border-radius: 999px;
+  background: var(--n-surface-raised);
+  color: var(--n-ink);
+  cursor: pointer;
+  font: inherit;
+  font-size: 0.78rem;
+  padding: 0.65rem 0.55rem;
+}
+
+.quick-start:hover,
+.quick-start:focus-visible,
+.quick-start.is-active {
+  border-color: var(--n-line);
+  background: var(--n-surface);
+  color: var(--n-ink);
+}
+
+.quick-start.is-active {
+  border-color: var(--n-action-bg);
+  background: var(--n-action-bg);
+  color: var(--n-action-ink);
+}
+
+.field-grid {
+  gap: 1rem;
+}
+
+.shadowing-field {
+  display: grid;
+  grid-template-columns: 1fr auto;
+  gap: 0.5rem 0.7rem;
+  align-items: center;
+}
+
+.field-value {
+  display: flex;
+  gap: 0.25rem;
+  align-items: baseline;
+  color: var(--n-accent-deep);
+  font-weight: 800;
+}
+
+.field-value output {
+  font-size: 1.15rem;
+  letter-spacing: normal;
+}
+
+.shadowing-field input[type='range'] {
+  grid-column: 1 / -1;
+  width: 100%;
+  accent-color: var(--n-accent);
+  cursor: pointer;
+}
+
+.shadowing-field input[type='number'] {
+  grid-column: 1 / -1;
+  width: 100%;
+  border: 1px solid var(--n-line);
+  border-radius: 0.65rem;
+  background: var(--n-surface-raised);
+  color: var(--n-ink);
+  font: inherit;
+  font-size: 1rem;
+  min-height: 2.75rem;
+  padding: 0.55rem 0.7rem;
+}
+
+.shadowing-field input:focus-visible,
+.quick-start:focus-visible,
+.reset-button:focus-visible {
+  outline: 3px solid var(--n-gold);
+  outline-offset: 2px;
+}
+
+.input-help,
+.budget-note {
+  margin: 0;
+  color: var(--n-muted);
+  letter-spacing: normal;
+  text-transform: none;
+}
+
+.reset-button {
+  align-self: flex-start;
+  padding-inline: 1rem;
+}
+
+.shadowing-result {
+  display: flex;
+  flex-direction: column;
+  gap: 1.25rem;
+  background: var(--n-bg);
+}
+
+.timeline-card {
+  display: grid;
+  gap: 0.9rem;
+  min-width: 0;
+  padding: 1rem;
+  border: 1px solid var(--n-line);
+  border-radius: 1rem;
+  background: var(--n-surface);
+}
+
+.result-topline,
+.timeline-heading,
+.metric-strip,
+.timeline-legend {
+  display: flex;
+  gap: 0.75rem;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.status-pill {
+  border: 1px solid var(--n-line);
+  border-radius: 999px;
+  color: var(--n-muted);
+  font-size: 0.75rem;
+  font-weight: 800;
+  padding: 0.45rem 0.7rem;
+}
+
+.status-pill[data-tone='good'] {
+  border-color: var(--n-good);
+  color: var(--n-good);
+}
+
+.status-pill[data-tone='warn'] {
+  border-color: var(--n-accent);
+  color: var(--n-accent-deep);
+}
+
+.result-headline {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 1rem;
+}
+
+.result-stat {
+  min-width: 0;
+}
+
+.result-stat strong {
+  display: block;
+  overflow: visible;
+  color: var(--n-ink);
+  font-size: clamp(1.85rem, 4.5vw, 3.6rem);
+  line-height: 1;
+  white-space: nowrap;
+}
+
+.result-stat span {
+  display: block;
+  margin-top: 0.4rem;
+  color: var(--n-muted);
+  font-size: 0.82rem;
+  line-height: 1.2;
+}
+
+.result-detail {
+  margin: 0;
+  color: var(--n-ink);
+  line-height: 1.5;
+  max-width: 42rem;
+}
+
+.timer-dock {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  gap: 1rem;
+  align-items: center;
+  padding: 1rem;
+  border: 1px solid var(--n-line);
+  border-radius: 1rem;
+  background: var(--n-surface);
+}
+
+.timer-readout {
+  display: grid;
+  grid-template-columns: auto auto;
+  gap: 0.35rem 0.75rem;
+  align-items: baseline;
+}
+
+.timer-title,
+.timer-status {
+  color: var(--n-muted);
+  font-size: 0.72rem;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+
+.timer-readout strong {
+  grid-column: 1;
+  color: var(--n-ink);
+  font-size: clamp(1.8rem, 4vw, 2.7rem);
+  line-height: 1;
+  letter-spacing: 0.04em;
+}
+
+.timer-status {
+  grid-column: 2;
+  color: var(--n-accent-deep);
+}
+
+.timer-block {
+  grid-column: 1 / -1;
+  color: var(--n-muted);
+  font-size: 0.8rem;
+  line-height: 1.4;
+}
+
+.timer-actions {
+  display: flex;
+  gap: 0.45rem;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+}
+
+.timer-actions button {
+  border: 1px solid var(--n-line);
+  border-radius: 999px;
+  background: var(--n-surface-raised);
+  color: var(--n-ink);
+  cursor: pointer;
+  font: inherit;
+  font-size: 0.75rem;
+  font-weight: 800;
+  padding: 0.65rem 0.8rem;
+}
+
+.timer-actions .timer-toggle {
+  border-color: var(--n-action-bg);
+  background: var(--n-action-bg);
+  color: var(--n-action-ink);
+}
+
+.timer-actions button:hover:not(:disabled),
+.timer-actions button:focus-visible {
+  border-color: var(--n-line);
+  background: var(--n-surface);
+  color: var(--n-ink);
+}
+
+.timer-actions .timer-toggle:hover:not(:disabled),
+.timer-actions .timer-toggle:focus-visible {
+  border-color: var(--n-action-hover);
+  background: var(--n-action-hover);
+  color: var(--n-action-ink);
+}
+
+.timer-actions button:disabled {
+  border-color: var(--n-line);
+  background: var(--n-track);
+  color: var(--n-disabled-ink);
+  cursor: not-allowed;
+}
+
+.timeline-heading {
+  margin-top: 0.75rem;
+}
+
+.timeline {
+  display: flex;
+  min-height: 7.5rem;
+  gap: 0.2rem;
+  align-items: stretch;
+  min-width: 0;
+  overflow: hidden;
+  padding: 0.55rem;
+  border: 1px solid var(--n-line);
+  border-radius: 1rem;
+  background: var(--n-stage);
+}
+
+.shadowing-timeline-block {
+  flex: 0 1 calc(var(--n-block-width) - 0.2rem);
+  min-width: 0.35rem;
+  display: flex;
+  align-items: flex-end;
+  justify-content: center;
+  border-radius: 0.55rem;
+  color: var(--n-surface-raised);
+  padding: 0.6rem 0.25rem;
+}
+
+.shadowing-timeline-block[data-kind='shadow'] {
+  min-width: 1.35rem;
+  background: var(--n-accent);
+}
+
+.shadowing-timeline-block[data-kind='pause'] {
+  background: var(--n-blue);
+}
+
+.shadowing-timeline-block[data-kind='pause'] .shadowing-block-label {
+  display: none;
+}
+
+.shadowing-timeline-block[data-kind='buffer'] {
+  background: var(--n-gold);
+  color: var(--n-ink);
+}
+
+.shadowing-block-label {
+  overflow: hidden;
+  font-size: 0.68rem;
+  font-weight: 800;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.timeline-legend {
+  justify-content: flex-start;
+  flex-wrap: wrap;
+  gap: 0.85rem;
+  font-size: 0.68rem;
+}
+
+.timeline-legend span {
+  display: inline-flex;
+  gap: 0.35rem;
+  align-items: center;
+}
+
+.timeline-legend i {
+  display: inline-block;
+  width: 0.7rem;
+  height: 0.7rem;
+  border-radius: 0.2rem;
+}
+
+.timeline-legend i[data-kind='shadow'] {
+  background: var(--n-accent);
+}
+
+.timeline-legend i[data-kind='pause'] {
+  background: var(--n-blue);
+}
+
+.timeline-legend i[data-kind='buffer'] {
+  background: var(--n-gold);
+}
+
+.metric-strip {
+  justify-content: stretch;
+  gap: 0.5rem;
+}
+
+.metric-strip div {
+  flex: 1;
+  display: grid;
+  gap: 0.35rem;
+  padding-top: 0.75rem;
+  border-top: 1px solid var(--n-line);
+}
+
+.metric-strip strong {
+  color: var(--n-ink);
+  font-size: 1.05rem;
+}
+
+.rehearsal-cues {
+  display: grid;
+  gap: 0.75rem;
+  margin-top: auto;
+  padding-top: 1.1rem;
+  border-top: 1px solid var(--n-line);
+}
+
+.cue-title {
+  color: var(--n-muted);
+  font-size: 0.72rem;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+
+.cue-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 0.75rem;
+}
+
+.cue-grid p {
+  display: grid;
+  gap: 0.4rem;
+  margin: 0;
+  color: var(--n-muted);
+  font-size: 0.78rem;
+  line-height: 1.4;
+}
+
+.cue-grid strong {
+  color: var(--n-accent-deep);
+  font-size: 0.72rem;
+  letter-spacing: 0.08em;
+}
+
+@media (max-width: 780px) {
+  .shadowing-tool {
+    grid-template-columns: 1fr;
+  }
+
+  .shadowing-controls {
+    border-right: 0;
+    border-bottom: 1px solid var(--n-line);
+  }
+}
+
+@media (max-width: 480px) {
+  .shadowing-controls,
+  .shadowing-result {
+    padding: 1.1rem;
+  }
+
+  .result-headline {
+    grid-template-columns: 1fr;
+  }
+
+  .timer-dock {
+    grid-template-columns: 1fr;
+  }
+
+  .timer-actions {
+    justify-content: flex-start;
+  }
+
+  .timeline {
+    min-height: 6rem;
+  }
+
+  .cue-grid {
+    grid-template-columns: 1fr;
+  }
+}

package/src/tool/language-shadowing-session-planner/logic.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import { calculateShadowingPlan, DEFAULT_SHADOWING_INPUTS, normalizeShadowingInputs } from './logic';
+
+describe('calculateShadowingPlan', () => {
+  it('fits every requested repetition and exposes the spare buffer', () => {
+    const result = calculateShadowingPlan({ totalMinutes: 2, clipSeconds: 20, repetitions: 4, pauseSeconds: 10 });
+
+    expect(result.plannedRepetitions).toBe(4);
+    expect(result.activeSeconds).toBe(80);
+    expect(result.pauseTotalSeconds).toBe(30);
+    expect(result.scheduledSeconds).toBe(110);
+    expect(result.remainingSeconds).toBe(10);
+    expect(result.status).toBe('buffer');
+    expect(result.blocks.at(-1)?.kind).toBe('buffer');
+  });
+
+  it('stops before an incomplete repetition when the budget is short', () => {
+    const result = calculateShadowingPlan({ totalMinutes: 1, clipSeconds: 25, repetitions: 4, pauseSeconds: 10 });
+
+    expect(result.plannedRepetitions).toBe(2);
+    expect(result.scheduledSeconds).toBe(60);
+    expect(result.remainingSeconds).toBe(0);
+    expect(result.status).toBe('short');
+    expect(result.blocks.map((block) => block.kind)).toEqual(['shadow', 'pause', 'shadow']);
+  });
+
+  it('fits exactly without adding a buffer block', () => {
+    const result = calculateShadowingPlan({ totalMinutes: 1, clipSeconds: 20, repetitions: 3, pauseSeconds: 0 });
+
+    expect(result.scheduledSeconds).toBe(60);
+    expect(result.remainingSeconds).toBe(0);
+    expect(result.status).toBe('fits');
+    expect(result.blocks).toHaveLength(3);
+  });
+
+  it('returns an empty active schedule when one complete pass cannot fit', () => {
+    const result = calculateShadowingPlan({ totalMinutes: 1, clipSeconds: 100, repetitions: 2, pauseSeconds: 20 });
+
+    expect(result.plannedRepetitions).toBe(0);
+    expect(result.activeSeconds).toBe(0);
+    expect(result.blocks).toEqual([{ kind: 'buffer', startSeconds: 0, endSeconds: 60 }]);
+    expect(result.status).toBe('short');
+  });
+
+  it('normalizes invalid and out of range values', () => {
+    expect(normalizeShadowingInputs({ totalMinutes: Number.NaN, clipSeconds: 900, repetitions: 0, pauseSeconds: -9 })).toEqual({
+      totalMinutes: DEFAULT_SHADOWING_INPUTS.totalMinutes,
+      clipSeconds: 300,
+      repetitions: 1,
+      pauseSeconds: 0,
+    });
+  });
+});

package/src/tool/language-shadowing-session-planner/logic.ts

@@ -0,0 +1,94 @@
+import type { ShadowingBlock, ShadowingPlanInputs, ShadowingPlanResult } from './types';
+
+export const DEFAULT_SHADOWING_INPUTS: ShadowingPlanInputs = {
+  totalMinutes: 8,
+  clipSeconds: 20,
+  repetitions: 12,
+  pauseSeconds: 10,
+};
+
+const MINUTES_MIN = 1;
+const MINUTES_MAX = 180;
+const CLIP_MIN = 3;
+const CLIP_MAX = 300;
+const REPETITIONS_MIN = 1;
+const REPETITIONS_MAX = 30;
+const PAUSE_MIN = 0;
+const PAUSE_MAX = 120;
+
+function clamp(value: number, minimum: number, maximum: number): number {
+  return Math.min(maximum, Math.max(minimum, value));
+}
+
+function safeInteger(value: number, fallback: number): number {
+  return Number.isFinite(value) ? Math.round(value) : fallback;
+}
+
+export function normalizeShadowingInputs(inputs: ShadowingPlanInputs): ShadowingPlanInputs {
+  return {
+    totalMinutes: clamp(safeInteger(inputs.totalMinutes, DEFAULT_SHADOWING_INPUTS.totalMinutes), MINUTES_MIN, MINUTES_MAX),
+    clipSeconds: clamp(safeInteger(inputs.clipSeconds, DEFAULT_SHADOWING_INPUTS.clipSeconds), CLIP_MIN, CLIP_MAX),
+    repetitions: clamp(safeInteger(inputs.repetitions, DEFAULT_SHADOWING_INPUTS.repetitions), REPETITIONS_MIN, REPETITIONS_MAX),
+    pauseSeconds: clamp(safeInteger(inputs.pauseSeconds, DEFAULT_SHADOWING_INPUTS.pauseSeconds), PAUSE_MIN, PAUSE_MAX),
+  };
+}
+
+function buildBlocks(inputs: ShadowingPlanInputs, plannedRepetitions: number, remainingSeconds: number): ShadowingBlock[] {
+  const blocks: ShadowingBlock[] = [];
+  let cursor = 0;
+
+  for (let index = 1; index <= plannedRepetitions; index += 1) {
+    blocks.push({ kind: 'shadow', index, startSeconds: cursor, endSeconds: cursor + inputs.clipSeconds });
+    cursor += inputs.clipSeconds;
+    if (index < plannedRepetitions && inputs.pauseSeconds > 0) {
+      blocks.push({ kind: 'pause', startSeconds: cursor, endSeconds: cursor + inputs.pauseSeconds });
+      cursor += inputs.pauseSeconds;
+    }
+  }
+
+  if (remainingSeconds > 0) {
+    blocks.push({ kind: 'buffer', startSeconds: cursor, endSeconds: cursor + remainingSeconds });
+  }
+
+  return blocks;
+}
+
+function plannedRepetitionsForBudget(inputs: ShadowingPlanInputs, budgetSeconds: number): number {
+  const cycleSeconds = inputs.clipSeconds + inputs.pauseSeconds;
+  const maximum = Math.floor((budgetSeconds + inputs.pauseSeconds) / cycleSeconds);
+  return Math.min(inputs.repetitions, Math.max(0, maximum));
+}
+
+function getStatus(plannedRepetitions: number, requestedRepetitions: number, remainingSeconds: number) {
+  if (plannedRepetitions < requestedRepetitions) return 'short' as const;
+  if (remainingSeconds > 0) return 'buffer' as const;
+  return 'fits' as const;
+}
+
+export function calculateShadowingPlan(rawInputs: ShadowingPlanInputs): ShadowingPlanResult {
+  const inputs = normalizeShadowingInputs(rawInputs);
+  const budgetSeconds = inputs.totalMinutes * 60;
+  const requestedSeconds = inputs.repetitions * inputs.clipSeconds + Math.max(0, inputs.repetitions - 1) * inputs.pauseSeconds;
+  const plannedRepetitions = plannedRepetitionsForBudget(inputs, budgetSeconds);
+  const activeSeconds = plannedRepetitions * inputs.clipSeconds;
+  const pauseTotalSeconds = Math.max(0, plannedRepetitions - 1) * inputs.pauseSeconds;
+  const scheduledSeconds = activeSeconds + pauseTotalSeconds;
+  const remainingSeconds = Math.max(0, budgetSeconds - scheduledSeconds);
+  const coveragePercent = budgetSeconds === 0 ? 0 : Math.round((scheduledSeconds / budgetSeconds) * 100);
+  const status = getStatus(plannedRepetitions, inputs.repetitions, remainingSeconds);
+
+  return {
+    inputs,
+    budgetSeconds,
+    requestedSeconds,
+    activeSeconds,
+    pauseTotalSeconds,
+    scheduledSeconds,
+    remainingSeconds,
+    requestedRepetitions: inputs.repetitions,
+    plannedRepetitions,
+    coveragePercent,
+    status,
+    blocks: buildBlocks(inputs, plannedRepetitions, remainingSeconds),
+  };
+}

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

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