Merge pull request #5 from python-chile/feat-4-educational-python-errors

feat: add educational Python error help

Author: ale0aranda

src/components/station/editor/PythonEditor.astro

@@ -35,7 +35,7 @@ const resolvedChallenge = challenge
     : undefined}
 >
   <div class="border-line shadow-editor overflow-hidden border bg-white">
-    <div
+    <header
       class="border-line-soft bg-panel flex items-center justify-between gap-4 border-b px-5 py-3.5"
     >
       <div class="flex items-center gap-3">
@@ -51,11 +51,11 @@ const resolvedChallenge = challenge
         role="status"
         aria-live="polite"
       >
-        <span class="bg-brand size-1.5 rounded-full" aria-hidden="true"></span>
+        <span class="bg-brand size-1.5 rounded-full" aria-hidden="true"> </span>
 
-        <span data-python-status-text>Preparando entorno…</span>
+        <span data-python-status-text> Preparando entorno… </span>
       </div>
-    </div>
+    </header>
 
     <div class="grid min-h-96 lg:h-128 lg:min-h-0" data-python-workspace>
       <div class="min-h-80 min-w-0 lg:h-full lg:min-h-0" data-python-code-panel>
@@ -68,7 +68,7 @@ const resolvedChallenge = challenge
         aria-label="Resultado de la ejecución"
         data-python-results
       >
-        <div
+        <header
           class="border-line-soft flex items-center gap-2 border-b bg-white px-5 py-3.5"
         >
           <span
@@ -81,7 +81,7 @@ const resolvedChallenge = challenge
           <span class="text-ink font-mono text-xs font-bold tracking-widest">
             SALIDA
           </span>
-        </div>
+        </header>
 
         <div class="text-muted px-5 py-3 font-mono text-xs">
           $ python main.py
@@ -95,13 +95,13 @@ const resolvedChallenge = challenge
       </section>
     </div>
 
-    <div
+    <footer
       class="border-line-soft bg-paper flex flex-wrap items-center gap-2 border-t px-4 py-4 sm:px-5"
     >
       <button
         type="button"
         disabled
-        class="bg-accent text-ink shadow-action hover:bg-accent-dark inline-flex items-center gap-3 px-5 py-3 font-bold transition-colors disabled:cursor-not-allowed disabled:opacity-50"
+        class="bg-accent text-ink shadow-action hover:bg-accent-dark focus-visible:outline-brand inline-flex items-center gap-3 px-5 py-3 font-bold transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 disabled:cursor-not-allowed disabled:opacity-50"
         data-python-run
       >
         <span aria-hidden="true">▶</span>
@@ -135,13 +135,76 @@ const resolvedChallenge = challenge
         </button>
       </div>
 
+      <label
+        class="text-muted hover:bg-ink/5 hover:text-ink flex cursor-pointer items-center gap-2 px-3 py-2 text-sm font-medium transition-colors"
+        title="Mostrar explicaciones sencillas para errores comunes de Python"
+      >
+        <input
+          type="checkbox"
+          class="accent-brand size-4"
+          data-python-error-help-toggle
+        />
+
+        <span>Explicar errores</span>
+      </label>
+
       <a
         hidden
         class="text-brand decoration-accent hover:text-brand-dark ml-auto px-2 py-2 font-bold underline decoration-2 underline-offset-4 transition-colors"
-        data-python-next></a>
-    </div>
+        data-python-next
+      >
+      </a>
+    </footer>
   </div>
 
+  <aside
+    hidden
+    class="border-line-soft bg-panel border-l-brand mt-3 border-l-4 px-4 py-3"
+    role="note"
+    aria-live="polite"
+    data-python-error-help
+  >
+    <div class="flex items-start gap-3">
+      <span
+        class="bg-brand/10 text-brand grid size-7 shrink-0 place-items-center rounded-full font-mono text-xs font-bold"
+        aria-hidden="true"
+      >
+        ?
+      </span>
+
+      <div class="min-w-0 flex-1">
+        <div class="flex flex-wrap items-center gap-x-2 gap-y-1">
+          <span class="text-brand font-mono text-xs font-bold tracking-widest">
+            AYUDA
+          </span>
+
+          <span aria-hidden="true" class="text-muted"> · </span>
+
+          <span class="text-ink text-sm font-bold" data-python-error-help-name>
+          </span>
+        </div>
+
+        <div
+          class="text-muted mt-1 text-sm leading-6"
+          data-python-error-help-explanation
+        >
+        </div>
+
+        <div class="mt-2 flex items-start gap-2 text-sm leading-6">
+          <span class="text-ink shrink-0 font-bold" aria-hidden="true">
+            →
+          </span>
+
+          <div>
+            <span class="text-ink font-bold"> Sugerencia: </span>
+
+            <span class="text-muted" data-python-error-help-suggestion> </span>
+          </div>
+        </div>
+      </div>
+    </div>
+  </aside>
+
   <p
     hidden
     class="mt-5 border-l-4 px-4 py-3 text-sm font-medium"
@@ -176,7 +239,9 @@ const resolvedChallenge = challenge
     sandbox="allow-scripts"
     referrerpolicy="no-referrer"
     class="hidden"
-    data-python-runner></iframe>
+    data-python-runner
+  >
+  </iframe>
 </div>
 
 <script>
@@ -188,7 +253,9 @@ const resolvedChallenge = challenge
 <style>
   @media (min-width: 64rem) {
     .python-workspace--with-results {
-      grid-template-columns: minmax(0, 1.2fr) minmax(17rem, 0.8fr);
+      grid-template-columns:
+        minmax(0, 1.2fr)
+        minmax(17rem, 0.8fr);
     }
   }
 </style>

src/components/station/editor/dom.ts

@@ -13,6 +13,11 @@ export type PythonEditorElements = {
   chartContainer: HTMLElement;
   chart: HTMLImageElement;
   runner: HTMLIFrameElement;
+  errorHelpToggle: HTMLInputElement;
+  errorHelp: HTMLElement;
+  errorHelpName: HTMLElement;
+  errorHelpExplanation: HTMLElement;
+  errorHelpSuggestion: HTMLElement;
 };
 
 function queryRequiredElement<T extends Element>(
@@ -49,5 +54,22 @@ export function getPythonEditorElements(
     ),
     chart: queryRequiredElement(editor, "[data-python-chart]"),
     runner: queryRequiredElement(editor, "[data-python-runner]"),
+    errorHelpToggle: queryRequiredElement(
+      editor,
+      "[data-python-error-help-toggle]",
+    ),
+    errorHelp: queryRequiredElement(editor, "[data-python-error-help]"),
+    errorHelpName: queryRequiredElement(
+      editor,
+      "[data-python-error-help-name]",
+    ),
+    errorHelpExplanation: queryRequiredElement(
+      editor,
+      "[data-python-error-help-explanation]",
+    ),
+    errorHelpSuggestion: queryRequiredElement(
+      editor,
+      "[data-python-error-help-suggestion]",
+    ),
   };
 }

src/components/station/editor/initialize.ts

@@ -1,5 +1,9 @@
 import { createPythonCodeEditor } from "./code-editor";
 import { getPythonEditorElements } from "./dom";
+import {
+  getErrorHelpPreference,
+  setErrorHelpPreference,
+} from "./python-error-help";
 import { createPythonRunner } from "./runner";
 import type { Challenge } from "./types";
 import { createPythonEditorUi } from "./ui";
@@ -35,7 +39,20 @@ function initializePythonEditor(editor: HTMLElement) {
   moveHintIntoEditor(editor, elements.hintSlot);
 
   const editorView = createPythonCodeEditor(elements.codeElement, starterCode);
+
   const ui = createPythonEditorUi(elements);
+  const errorHelpEnabled = getErrorHelpPreference();
+
+  elements.errorHelpToggle.checked = errorHelpEnabled;
+  ui.setErrorHelpEnabled(errorHelpEnabled);
+
+  elements.errorHelpToggle.addEventListener("change", () => {
+    const enabled = elements.errorHelpToggle.checked;
+
+    setErrorHelpPreference(enabled);
+    ui.setErrorHelpEnabled(enabled);
+  });
+
   const runner = createPythonRunner({
     challenge,
     elements,

src/components/station/editor/python-error-help.ts

@@ -0,0 +1,100 @@
+export type PythonErrorHelp = {
+  errorName: string;
+  explanation: string;
+  suggestion: string;
+};
+
+type PythonErrorRule = PythonErrorHelp & {
+  pattern: RegExp;
+};
+
+const ERROR_HELP_STORAGE_KEY = "pyschool-python-error-help";
+
+const PYTHON_ERROR_RULES: PythonErrorRule[] = [
+  {
+    pattern: /\bIndentationError\b|\bTabError\b/,
+    errorName: "Error de indentación",
+    explanation:
+      "Python encontró un bloque de código cuya sangría no es válida o no coincide con las líneas cercanas.",
+    suggestion:
+      "Revisa los espacios al comienzo de la línea. El código dentro de un if, for, while o función debe tener la misma indentación.",
+  },
+  {
+    pattern: /\bSyntaxError\b/,
+    errorName: "Error de sintaxis",
+    explanation:
+      "Python no pudo comprender una parte del código porque su estructura no es válida.",
+    suggestion:
+      "Revisa la línea indicada. Comprueba paréntesis, comillas, dos puntos y palabras reservadas.",
+  },
+  {
+    pattern: /\bNameError\b/,
+    errorName: "Nombre no definido",
+    explanation:
+      "Python intentó utilizar una variable o función que todavía no está definida.",
+    suggestion:
+      "Comprueba que el nombre exista, esté escrito correctamente y haya sido definido antes de utilizarlo.",
+  },
+  {
+    pattern: /\bTypeError\b/,
+    errorName: "Tipos incompatibles",
+    explanation:
+      "Python recibió un tipo de dato que no puede utilizar en esa operación o función.",
+    suggestion:
+      "Revisa los valores involucrados. Es posible que estés mezclando texto, números, listas u otros tipos incompatibles.",
+  },
+  {
+    pattern: /\bIndexError\b/,
+    errorName: "Índice fuera de rango",
+    explanation:
+      "Se intentó acceder a una posición que no existe dentro de una lista o secuencia.",
+    suggestion:
+      "Revisa la cantidad de elementos y recuerda que los índices de las listas comienzan en cero.",
+  },
+  {
+    pattern: /\bKeyError\b/,
+    errorName: "Clave inexistente",
+    explanation:
+      "Se intentó obtener una clave que no existe dentro de un diccionario.",
+    suggestion:
+      "Comprueba cómo está escrita la clave o verifica su existencia antes de acceder a ella.",
+  },
+  {
+    pattern: /\bZeroDivisionError\b/,
+    errorName: "División por cero",
+    explanation: "Python intentó realizar una división cuyo divisor es cero.",
+    suggestion:
+      "Revisa el valor utilizado como divisor y valida que sea distinto de cero antes de dividir.",
+  },
+];
+
+export function getPythonErrorHelp(output: string): PythonErrorHelp | null {
+  const rule = PYTHON_ERROR_RULES.find(({ pattern }) => pattern.test(output));
+
+  if (!rule) {
+    return null;
+  }
+
+  return {
+    errorName: rule.errorName,
+    explanation: rule.explanation,
+    suggestion: rule.suggestion,
+  };
+}
+
+export function getErrorHelpPreference(): boolean {
+  try {
+    return window.localStorage.getItem(ERROR_HELP_STORAGE_KEY) === "true";
+  } catch {
+    return false;
+  }
+}
+
+export function setErrorHelpPreference(enabled: boolean): void {
+  try {
+    window.localStorage.setItem(ERROR_HELP_STORAGE_KEY, String(enabled));
+  } catch {
+    // La ayuda continúa funcionando durante la sesión
+    // aunque el almacenamiento local no esté disponible.
+  }
+}