handzon-core 0.6.0

package/src/components/mdx/Diff.tsx

@@ -0,0 +1,100 @@
+import { diffLines } from "diff";
+import { useMemo, useState } from "react";
+
+interface Props {
+  before: string;
+  after: string;
+  lang?: string;
+  layout?: "side-by-side" | "unified";
+  beforeLabel?: string;
+  afterLabel?: string;
+}
+
+export default function Diff({
+  before,
+  after,
+  layout: initialLayout = "side-by-side",
+  beforeLabel = "Before",
+  afterLabel = "After",
+}: Props) {
+  const [layout, setLayout] = useState(initialLayout);
+  const parts = useMemo(() => diffLines(before, after), [before, after]);
+
+  if (layout === "unified") {
+    return (
+      <div className="diff">
+        <div className="diff-bar">
+          <button type="button" onClick={() => setLayout("side-by-side")}>
+            Side-by-side
+          </button>
+        </div>
+        <pre className="diff-body">
+          {parts.map((part, i) => (
+            <span
+              key={i}
+              className={part.added ? "diff-add" : part.removed ? "diff-del" : "diff-ctx"}
+            >
+              {part.added ? "+ " : part.removed ? "- " : "  "}
+              {part.value}
+            </span>
+          ))}
+        </pre>
+      </div>
+    );
+  }
+
+  const leftLines: string[] = [];
+  const rightLines: string[] = [];
+  for (const p of parts) {
+    const lines = p.value.split("\n");
+    if (lines[lines.length - 1] === "") lines.pop();
+    if (p.added) {
+      for (const l of lines) {
+        leftLines.push("");
+        rightLines.push(`+ ${l}`);
+      }
+    } else if (p.removed) {
+      for (const l of lines) {
+        leftLines.push(`- ${l}`);
+        rightLines.push("");
+      }
+    } else {
+      for (const l of lines) {
+        leftLines.push(`  ${l}`);
+        rightLines.push(`  ${l}`);
+      }
+    }
+  }
+
+  return (
+    <div className="diff">
+      <div className="diff-bar">
+        <button type="button" onClick={() => setLayout("unified")}>
+          Unified
+        </button>
+      </div>
+      <div className="diff-grid">
+        <div className="diff-col">
+          <div className="diff-label">{beforeLabel}</div>
+          <pre>
+            {leftLines.map((l, i) => (
+              <div key={i} className={l.startsWith("- ") ? "diff-del" : "diff-ctx"}>
+                {l || " "}
+              </div>
+            ))}
+          </pre>
+        </div>
+        <div className="diff-col">
+          <div className="diff-label">{afterLabel}</div>
+          <pre>
+            {rightLines.map((l, i) => (
+              <div key={i} className={l.startsWith("+ ") ? "diff-add" : "diff-ctx"}>
+                {l || " "}
+              </div>
+            ))}
+          </pre>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/mdx/Download.astro

@@ -0,0 +1,37 @@
+---
+interface Props {
+  href: string;
+  label?: string;
+  size?: string;
+}
+const { href, label, size } = Astro.props;
+const filename = label ?? href.split("/").pop() ?? "download";
+---
+<a class="download" href={href} download>
+  <span class="download-icon" aria-hidden="true">⬇</span>
+  <span class="download-name">{filename}</span>
+  {size && <span class="download-size">{size}</span>}
+</a>
+
+<style>
+  .download {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.5rem 0.9rem;
+    border: var(--border-default, 2px) solid var(--color-fg);
+    background: var(--color-bg);
+    color: var(--color-fg);
+    font-family: var(--font-mono);
+    font-size: 0.9em;
+    text-decoration: none;
+    transition: transform 0.08s ease, box-shadow 0.08s ease;
+  }
+  .download:hover {
+    transform: translate(-2px, -2px);
+    box-shadow: var(--shadow-raised);
+    color: var(--color-fg);
+  }
+  .download-icon { color: var(--color-accent); }
+  .download-size { color: var(--color-muted); font-size: 0.85em; margin-left: 0.5rem; }
+</style>

package/src/components/mdx/Embed.astro

@@ -0,0 +1,56 @@
+---
+interface Props {
+  src: string;
+  title?: string;
+  aspect?: string;
+  type?: "iframe" | "video";
+}
+const { src, title = "Embedded content", aspect = "16/9", type = "iframe" } = Astro.props;
+
+function normalize(url: string): string {
+  try {
+    const u = new URL(url, "https://example.com");
+    if (u.hostname.endsWith("youtube.com")) {
+      u.hostname = "www.youtube-nocookie.com";
+      return u.toString();
+    }
+    return url;
+  } catch {
+    return url;
+  }
+}
+
+const finalSrc = type === "iframe" ? normalize(src) : src;
+---
+<div class="embed" style={`aspect-ratio: ${aspect};`}>
+  {type === "iframe" ? (
+    <iframe
+      src={finalSrc}
+      title={title}
+      loading="lazy"
+      allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+      referrerpolicy="strict-origin-when-cross-origin"
+      allowfullscreen
+    />
+  ) : (
+    <video controls preload="metadata">
+      <source src={finalSrc} />
+    </video>
+  )}
+</div>
+
+<style>
+  .embed {
+    margin: 1.5rem 0;
+    border: var(--border-default, 2px) solid var(--color-border);
+    background: var(--color-surface);
+    overflow: hidden;
+  }
+  .embed iframe,
+  .embed video {
+    width: 100%;
+    height: 100%;
+    border: 0;
+    display: block;
+  }
+</style>

package/src/components/mdx/File.astro

@@ -0,0 +1,28 @@
+---
+interface Props {
+  name: string;
+}
+const { name } = Astro.props;
+---
+<div class="file-label">
+  <span class="file-icon" aria-hidden="true">▸</span>
+  <span class="file-name">{name}</span>
+</div>
+<div class="file-body"><slot /></div>
+
+<style>
+  .file-label {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    background: var(--color-surface);
+    border: var(--border-default, 2px) solid var(--color-border);
+    border-bottom: none;
+    padding: 0.3rem 0.6rem;
+    font-family: var(--font-mono);
+    font-size: 0.85em;
+    color: var(--color-muted);
+  }
+  .file-icon { color: var(--color-accent); }
+  .file-body :global(pre) { margin-top: 0 !important; }
+</style>

package/src/components/mdx/FileTree.astro

@@ -0,0 +1,6 @@
+---
+import FileTreeIsland from "./FileTree.tsx";
+type Props = Parameters<typeof FileTreeIsland>[0];
+const props = Astro.props as Props;
+---
+<FileTreeIsland client:visible {...props} />

package/src/components/mdx/FileTree.tsx

@@ -0,0 +1,71 @@
+import { File as FileIcon, Folder, FolderOpen } from "lucide-react";
+import { useState } from "react";
+
+type Node = { name: string; children?: Node[] };
+
+interface Props {
+  paths?: string[];
+  tree?: Node[];
+}
+
+function pathsToTree(paths: string[]): Node[] {
+  const root: Node = { name: "", children: [] };
+  for (const path of paths) {
+    const parts = path.split("/").filter(Boolean);
+    let cursor = root;
+    for (const part of parts) {
+      cursor.children ??= [];
+      let child = cursor.children.find((c) => c.name === part);
+      if (!child) {
+        child = { name: part };
+        cursor.children.push(child);
+      }
+      cursor = child;
+    }
+  }
+  return root.children ?? [];
+}
+
+function isFolder(node: Node): boolean {
+  return Array.isArray(node.children) && node.children.length > 0;
+}
+
+function NodeRow({ node }: { node: Node }) {
+  const [open, setOpen] = useState(true);
+  const folder = isFolder(node);
+  return (
+    <li className="ft-row">
+      <button
+        type="button"
+        className="ft-btn"
+        onClick={() => folder && setOpen((o) => !o)}
+        aria-expanded={folder ? open : undefined}
+      >
+        {folder ? open ? <FolderOpen size={13} /> : <Folder size={13} /> : <FileIcon size={13} />}
+        <span className="ft-name">{node.name}</span>
+      </button>
+      {folder && open && node.children && (
+        <ul className="ft-list">
+          {node.children.map((child) => (
+            // Indentation comes from .ft-list CSS (padding-left + guide
+            // line), not an inline marginLeft. Compounding the inline
+            // offset with the browser-default UL padding produced the
+            // huge stair-step in the screenshot.
+            <NodeRow key={child.name} node={child} />
+          ))}
+        </ul>
+      )}
+    </li>
+  );
+}
+
+export default function FileTree({ paths, tree }: Props) {
+  const resolved = tree ?? (paths ? pathsToTree(paths) : []);
+  return (
+    <ul className="ft-root">
+      {resolved.map((node) => (
+        <NodeRow key={node.name} node={node} />
+      ))}
+    </ul>
+  );
+}

package/src/components/mdx/Hint.astro

@@ -0,0 +1,51 @@
+---
+interface Props {
+  title?: string;
+}
+const { title = "Show hint" } = Astro.props;
+---
+
+<details class="hint">
+  <summary>
+    <svg class="hint-icon" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+      <path d="M9 18h6"></path>
+      <path d="M10 22h4"></path>
+      <path d="M15.09 14c.18-.98.65-1.74 1.41-2.5A4.65 4.65 0 0 0 18 8 6 6 0 0 0 6 8c0 1 .23 2.23 1.5 3.5A4.61 4.61 0 0 1 8.91 14"></path>
+    </svg>
+    <span>{title}</span>
+  </summary>
+  <div class="hint-body"><slot /></div>
+</details>
+
+<style>
+  .hint {
+    margin: 1rem 0;
+    background: var(--color-surface);
+    border: var(--border-default) solid var(--color-border);
+    border-radius: 0;
+    overflow: hidden;
+  }
+  .hint > summary {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.65rem 0.9rem;
+    cursor: pointer;
+    font-weight: 500;
+    color: var(--color-accent);
+    list-style: none;
+    user-select: none;
+  }
+  .hint > summary::-webkit-details-marker { display: none; }
+  .hint-icon {
+    color: var(--color-accent);
+    transition: transform 0.15s ease;
+    flex-shrink: 0;
+  }
+  .hint[open] .hint-icon { transform: rotate(15deg); }
+  .hint-body {
+    padding: 0.6rem 0.85rem;
+    background: var(--color-bg);
+    margin: 0 0.5rem 0.5rem;
+  }
+</style>

package/src/components/mdx/Mermaid.astro

@@ -0,0 +1,6 @@
+---
+import MermaidIsland from "./Mermaid.tsx";
+type Props = Parameters<typeof MermaidIsland>[0];
+const props = Astro.props as Props;
+---
+<MermaidIsland client:visible {...props} />

package/src/components/mdx/Mermaid.tsx

@@ -0,0 +1,47 @@
+import { useEffect, useRef, useState } from "react";
+
+interface Props {
+  chart: string;
+  id?: string;
+}
+
+/**
+ * Interactive mermaid island. The default authoring path is fenced
+ * ```mermaid blocks, which rehype-mermaid renders at build time. Use
+ * this island only when the diagram needs to respond to runtime state.
+ */
+export default function Mermaid({ chart, id }: Props) {
+  const ref = useRef<HTMLDivElement>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      try {
+        const mermaid = (await import("mermaid")).default;
+        mermaid.initialize({ startOnLoad: false, theme: "dark", securityLevel: "strict" });
+        const { svg } = await mermaid.render(
+          id ?? `mermaid-${Math.random().toString(36).slice(2)}`,
+          chart,
+        );
+        if (!cancelled && ref.current) ref.current.innerHTML = svg;
+      } catch (e) {
+        if (!cancelled) setError(e instanceof Error ? e.message : String(e));
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [chart, id]);
+
+  if (error) {
+    return (
+      <pre className="mermaid-error">
+        Mermaid render failed: {error}
+        {"\n"}
+        {chart}
+      </pre>
+    );
+  }
+  return <div ref={ref} className="mermaid-wrap" />;
+}

package/src/components/mdx/Playground.astro

@@ -0,0 +1,6 @@
+---
+import PlaygroundIsland from "./Playground.tsx";
+type Props = Parameters<typeof PlaygroundIsland>[0];
+const props = Astro.props as Props;
+---
+<PlaygroundIsland client:load {...props} />

package/src/components/mdx/Playground.tsx

@@ -0,0 +1,34 @@
+import { Sandpack, type SandpackPredefinedTemplate } from "@codesandbox/sandpack-react";
+
+interface Props {
+  template?: SandpackPredefinedTemplate;
+  files?: Record<string, string | { code: string; hidden?: boolean }>;
+  dependencies?: Record<string, string>;
+  height?: number;
+  showConsole?: boolean;
+}
+
+export default function Playground({
+  template = "react-ts",
+  files,
+  dependencies,
+  height = 480,
+  showConsole = true,
+}: Props) {
+  return (
+    <div className="playground" style={{ height }}>
+      <Sandpack
+        template={template}
+        files={files}
+        customSetup={dependencies ? { dependencies } : undefined}
+        theme="dark"
+        options={{
+          showConsole,
+          showConsoleButton: true,
+          editorHeight: height,
+          editorWidthPercentage: 50,
+        }}
+      />
+    </div>
+  );
+}

package/src/components/mdx/Quiz.astro

@@ -0,0 +1,6 @@
+---
+import QuizIsland from "./Quiz.tsx";
+type Props = Parameters<typeof QuizIsland>[0];
+const props = Astro.props as Props;
+---
+<QuizIsland client:load {...props} />

package/src/components/mdx/Quiz.tsx

@@ -0,0 +1,102 @@
+import { Check, X } from "lucide-react";
+import { useId, useState } from "react";
+import { useProgress } from "../../lib/progress/useProgress";
+
+interface Props {
+  question: string;
+  options: string[];
+  answer: number | number[];
+  explanation?: string;
+  id?: string;
+  multi?: boolean;
+}
+
+export default function Quiz({ question, options, answer, explanation, id, multi }: Props) {
+  const reactId = useId();
+  const questionId = id ?? `quiz:${reactId}:${question.slice(0, 40)}`;
+  const { state, recordQuiz } = useProgress();
+
+  const previous = state.quizzes[questionId];
+  const [chosen, setChosen] = useState<number[]>(previous?.chosen ?? []);
+  const [submitted, setSubmitted] = useState<boolean>(!!previous);
+
+  const correctSet = new Set(Array.isArray(answer) ? answer : [answer]);
+  const expectMulti = multi ?? Array.isArray(answer);
+
+  function toggle(i: number) {
+    if (submitted) return;
+    if (expectMulti) {
+      setChosen((c) => (c.includes(i) ? c.filter((x) => x !== i) : [...c, i]));
+    } else {
+      setChosen([i]);
+    }
+  }
+
+  function submit() {
+    const sorted = [...chosen].sort((a, b) => a - b);
+    const correct = sorted.length === correctSet.size && sorted.every((v) => correctSet.has(v));
+    recordQuiz(questionId, sorted, correct);
+    setSubmitted(true);
+  }
+
+  function reset() {
+    setChosen([]);
+    setSubmitted(false);
+  }
+
+  return (
+    <fieldset className="quiz" disabled={submitted}>
+      <legend className="quiz-q">{question}</legend>
+      <div className="quiz-options">
+        {options.map((opt, i) => {
+          const isChosen = chosen.includes(i);
+          const isCorrect = submitted && correctSet.has(i);
+          const wasWrong = submitted && isChosen && !correctSet.has(i);
+          return (
+            <label
+              key={i}
+              className={[
+                "quiz-opt",
+                isChosen ? "is-chosen" : "",
+                isCorrect ? "is-correct" : "",
+                wasWrong ? "is-wrong" : "",
+              ].join(" ")}
+            >
+              <input
+                type={expectMulti ? "checkbox" : "radio"}
+                name={questionId}
+                checked={isChosen}
+                onChange={() => toggle(i)}
+              />
+              <span
+                className={`quiz-opt-toggle quiz-opt-toggle--${expectMulti ? "multi" : "single"}`}
+                aria-hidden="true"
+              >
+                {isCorrect ? <Check size={12} /> : wasWrong ? <X size={12} /> : null}
+              </span>
+              <span>{opt}</span>
+            </label>
+          );
+        })}
+      </div>
+      <div className="quiz-actions">
+        {!submitted && (
+          <button type="button" onClick={submit} disabled={chosen.length === 0}>
+            Check
+          </button>
+        )}
+        {submitted && (
+          <button type="button" onClick={reset}>
+            Try again
+          </button>
+        )}
+        {submitted && (
+          <span className={previous?.correct ? "quiz-msg ok" : "quiz-msg no"}>
+            {previous?.correct ? "Correct" : "Not quite"}
+          </span>
+        )}
+      </div>
+      {submitted && explanation && <p className="quiz-exp">{explanation}</p>}
+    </fieldset>
+  );
+}

package/src/components/mdx/Recap.astro

@@ -0,0 +1,65 @@
+---
+interface Props {
+  title?: string;
+  items: string[];
+}
+const { title = "What you learned", items } = Astro.props;
+---
+<section class="recap">
+  <h3 class="recap-title">
+    <svg class="recap-icon" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+      <polyline points="20 6 9 17 4 12"></polyline>
+    </svg>
+    <span>{title}</span>
+  </h3>
+  <ul class="recap-items">
+    {items.map((item) => (
+      <li>
+        <svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+          <polyline points="20 6 9 17 4 12"></polyline>
+        </svg>
+        <span>{item}</span>
+      </li>
+    ))}
+  </ul>
+</section>
+
+<style>
+  .recap {
+    margin: 2rem 0;
+    padding: 1rem 1.25rem;
+    background: var(--color-surface);
+    border: var(--border-default) solid var(--color-border);
+    border-left: var(--border-thick) solid var(--color-accent);
+    border-radius: 0;
+  }
+  .recap-title {
+    margin: 0 0 0.6rem;
+    font-size: 0.78rem;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--color-accent);
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+  }
+  .recap-icon { color: var(--color-accent); flex-shrink: 0; }
+  .recap-items {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: grid;
+    gap: 0.3rem;
+  }
+  .recap-items li {
+    display: grid;
+    grid-template-columns: 1.1rem 1fr;
+    gap: 0.55rem;
+    align-items: start;
+    margin: 0;
+  }
+  .recap-items li :global(svg) {
+    color: var(--color-accent);
+    margin-top: 0.25em;
+  }
+</style>

package/src/components/mdx/Reveal.astro

@@ -0,0 +1,7 @@
+---
+import RevealIsland from "./Reveal.tsx";
+const { label } = Astro.props;
+---
+<RevealIsland client:visible label={label}>
+  <slot />
+</RevealIsland>

package/src/components/mdx/Reveal.tsx

@@ -0,0 +1,25 @@
+import { Eye, EyeOff } from "lucide-react";
+import { type ReactNode, useState } from "react";
+
+interface Props {
+  label?: string;
+  children: ReactNode;
+}
+
+export default function Reveal({ label = "Show solution", children }: Props) {
+  const [open, setOpen] = useState(false);
+  return (
+    <div className="reveal">
+      <button
+        type="button"
+        onClick={() => setOpen((o) => !o)}
+        className="reveal-btn"
+        aria-expanded={open}
+      >
+        {open ? <EyeOff size={16} /> : <Eye size={16} />}
+        <span>{open ? "Hide" : label}</span>
+      </button>
+      {open && <div className="reveal-content">{children}</div>}
+    </div>
+  );
+}

package/src/components/mdx/Step.astro

@@ -0,0 +1,12 @@
+---
+interface Props {
+  title?: string;
+}
+const { title } = Astro.props;
+---
+<li class="step">
+  <div>
+    {title && <strong>{title}</strong>}
+    <slot />
+  </div>
+</li>