📚 Docs: Add missing JSDoc/TSDoc to components and utilities

.jules/docs-progress.md

@@ -35,3 +35,8 @@
 - **[2026-03-20] Markdown Links & Link Checker configuration**
   - Updated `mlc_config.json` configuration file to ignore `keras.io` and `developers.google.com/machine-learning/crash-course` which return false positives (403 or 0 codes) from anti-bot mechanisms.
   - Successfully passed `markdown-link-check` script.
+
+- **[2026-03-22] JSDoc Improvements**
+  - Added missing typed JSDoc comments and `@returns` tags to `src/components/CopyButton.tsx`, `src/components/ExerciseWidget.tsx`, `src/components/MarkdownRenderer.tsx`, and `src/components/Sidebar.tsx`.
+  - Added missing typed JSDoc comments and `@returns` tags to `src/utils/prism.ts` and `src/utils/curriculumConfig.ts`.
+  - All modified components and utilities now meet documentation standards.

src/components/CopyButton.tsx

@@ -22,6 +22,16 @@ interface CopyButtonProps {
   ariaLabel?: string
 }
 
+/**
+ * Renders a button that copies the provided text to the clipboard when clicked.
+ *
+ * @param {CopyButtonProps} props - The component properties.
+ * @param {string} props.text - The text content to be copied.
+ * @param {string} [props.className='code-block-copy'] - Optional custom class names.
+ * @param {boolean} [props.showEmoji=false] - Whether to display a clipboard emoji icon.
+ * @param {string} [props.ariaLabel] - Optional aria-label for accessibility.
+ * @returns {React.ReactElement} The rendered button component.
+ */
 export default function CopyButton({
   text,
   className = 'code-block-copy',

src/components/ExerciseWidget.tsx

@@ -66,6 +66,18 @@ interface ExerciseWidgetProps {
   solution?: string
 }
 
+/**
+ * Renders an interactive exercise widget for practicing Python code.
+ *
+ * @param {ExerciseWidgetProps} props - The component properties.
+ * @param {string} props.title - Exercise title (must be unique within the day).
+ * @param {string} [props.goal] - Brief goal statement explaining what to achieve.
+ * @param {string} [props.instructions] - Detailed step-by-step instructions.
+ * @param {string} props.starterCode - Initial code populated in the editor.
+ * @param {string} [props.expectedOutput] - The exact output string the user code should produce to pass.
+ * @param {string} [props.solution] - Complete solution code for reference.
+ * @returns {React.ReactElement} The rendered exercise widget component.
+ */
 export default function ExerciseWidget({
   title,
   goal,

src/components/MarkdownRenderer.tsx

@@ -366,7 +366,12 @@ function extractLabeledTextFromParagraph(node: Content, label: string): string {
   return rest.replace(/^:\s*/, '').trim()
 }
 
-/** Parse exercise and mastery sections so they can render as interactive widgets. */
+/**
+ * Parse exercise and mastery sections so they can render as interactive widgets.
+ *
+ * @param {string} content - The raw markdown content to be parsed.
+ * @returns {InteractiveBlock[]} An array of objects representing parsed blocks (text, exercises, or mastery checks).
+ */
 function findInteractiveBlocks(content: string): InteractiveBlock[] {
   const tree = unified().use(remarkParse).use(remarkGfm).parse(content) as Root
   const topLevelNodes = tree.children
@@ -692,6 +697,10 @@ interface MarkdownRendererProps {
 /**
  * Render lesson markdown with safe HTML, custom code blocks, glossary tooltips,
  * and interactive exercise/mastery widgets.
+ *
+ * @param {MarkdownRendererProps} props - The component properties.
+ * @param {string} props.content - The raw markdown content string to be rendered.
+ * @returns {React.ReactElement} The rendered markdown content wrapped in a responsive container.
  */
 function MarkdownRenderer({ content }: MarkdownRendererProps) {
   if (!content) {

src/components/Sidebar.tsx

@@ -35,9 +35,10 @@ interface SidebarProps {
  * - Mobile overlay with click-outside to close
  * - Phase-level progress counters
  *
- * @param isOpen - Controls sidebar visibility on mobile.
- * @param onClose - Function to close the sidebar.
- * @returns A navigation sidebar with phase accordion.
+ * @param {SidebarProps} props - The component properties.
+ * @param {boolean} props.isOpen - Controls sidebar visibility on mobile.
+ * @param {() => void} props.onClose - Function to close the sidebar.
+ * @returns {React.ReactElement} A navigation sidebar with phase accordion.
  */
 export default function Sidebar({ isOpen, onClose }: SidebarProps) {
   const location = useLocation()

src/utils/curriculumConfig.ts

@@ -28,6 +28,8 @@ export type PhaseIcons = z.infer<typeof phaseIconsSchema>
 /**
  * Configuration mapping for lesson difficulty levels, providing labels and associated UI styling colors.
  * Validated against `difficultyConfigSchema`.
+ *
+ * @type {DifficultyConfig}
  */
 export const difficultyConfig: DifficultyConfig = difficultyConfigSchema.parse({
   beginner: { label: 'Beginner', color: '#22c55e', bg: 'rgba(34,197,94,0.12)' },
@@ -39,6 +41,8 @@ export const difficultyConfig: DifficultyConfig = difficultyConfigSchema.parse({
 /**
  * Ordered array of icons representing the 9 curriculum phases.
  * Validated against `phaseIconsSchema`.
+ *
+ * @type {PhaseIcons}
  */
 export const phaseIcons: PhaseIcons = phaseIconsSchema.parse([
   '🐍',

src/utils/prism.ts

@@ -24,4 +24,11 @@ SyntaxHighlighter.registerLanguage('markdown', markdown)
 SyntaxHighlighter.registerLanguage('typescript', typescript)
 SyntaxHighlighter.registerLanguage('javascript', javascript)
 
+/**
+ * A configured instance of `react-syntax-highlighter` using PrismLight.
+ * This exported component has language definitions for python, bash, json,
+ * markdown, typescript, and javascript pre-registered to minimize bundle size.
+ *
+ * @type {React.ComponentType}
+ */
 export default SyntaxHighlighter