handzon-core 0.6.0

package/src/components/home/FilterBar.tsx

@@ -0,0 +1,152 @@
+import { Flame, Search, X } from "lucide-react";
+import { useEffect, useState } from "react";
+
+interface Props {
+  difficulties: string[];
+  tags: string[];
+}
+
+interface FilterState {
+  q: string;
+  difficulty: string;
+  tag: string;
+  /** "" = curated (numeric-prefix) order; "popular" = by data-popularity desc. */
+  sort: string;
+}
+
+function readUrlState(): FilterState {
+  if (typeof window === "undefined") return { q: "", difficulty: "", tag: "", sort: "" };
+  const url = new URL(window.location.href);
+  return {
+    q: url.searchParams.get("q") ?? "",
+    difficulty: url.searchParams.get("difficulty") ?? "",
+    tag: url.searchParams.get("tag") ?? "",
+    sort: url.searchParams.get("sort") ?? "",
+  };
+}
+
+function writeUrlState(state: FilterState) {
+  const url = new URL(window.location.href);
+  if (state.q) url.searchParams.set("q", state.q);
+  else url.searchParams.delete("q");
+  if (state.difficulty) url.searchParams.set("difficulty", state.difficulty);
+  else url.searchParams.delete("difficulty");
+  if (state.tag) url.searchParams.set("tag", state.tag);
+  else url.searchParams.delete("tag");
+  if (state.sort) url.searchParams.set("sort", state.sort);
+  else url.searchParams.delete("sort");
+  window.history.replaceState({}, "", url.toString());
+}
+
+function applyFilters(state: FilterState) {
+  const cards = document.querySelectorAll<HTMLElement>("[data-search]");
+  const q = state.q.trim().toLowerCase();
+  let visible = 0;
+  cards.forEach((card) => {
+    const matchesQ = !q || card.dataset.search!.includes(q);
+    const matchesDiff = !state.difficulty || card.dataset.difficulty === state.difficulty;
+    const matchesTag = !state.tag || (card.dataset.tags ?? "").split(",").includes(state.tag);
+    const show = matchesQ && matchesDiff && matchesTag;
+    if (show) {
+      card.removeAttribute("data-filter-hidden");
+      visible += 1;
+    } else {
+      card.setAttribute("data-filter-hidden", "");
+    }
+  });
+  const empty = document.querySelector<HTMLElement>("[data-empty-state]");
+  if (empty) empty.style.display = visible === 0 ? "" : "none";
+  // Notify Pagination (and any other listeners) that the filtered set
+  // changed so they can reset their slice.
+  window.dispatchEvent(new CustomEvent("hz:filter-changed"));
+}
+
+export default function FilterBar({ difficulties, tags }: Props) {
+  const [state, setState] = useState<FilterState>(readUrlState);
+
+  useEffect(() => {
+    applyFilters(state);
+    writeUrlState(state);
+    // Sort lives in a separate inline script on Home.astro because it
+    // doesn't depend on React state — it just reads data-popularity.
+    // Fire an event so it can re-run.
+    window.dispatchEvent(
+      new CustomEvent("hz:sort-changed", { detail: { sort: state.sort } }),
+    );
+  }, [state]);
+
+  function set<K extends keyof FilterState>(key: K, value: FilterState[K]) {
+    setState((prev) => ({ ...prev, [key]: value }));
+  }
+
+  function clear() {
+    setState({ q: "", difficulty: "", tag: "", sort: "" });
+  }
+
+  const hasFilters = state.q || state.difficulty || state.tag || state.sort;
+
+  return (
+    <div className="filterbar">
+      {/* Row 1: search takes the lion's share + level + clear */}
+      <div className="fb-row fb-row-primary">
+        <label className="search">
+          <Search size={16} aria-hidden="true" />
+          <input
+            type="search"
+            placeholder="Search tutorials…"
+            value={state.q}
+            onChange={(e) => set("q", e.target.value)}
+            aria-label="Search tutorials"
+          />
+        </label>
+
+        <div className="pills" role="group" aria-label="Difficulty">
+          {difficulties.map((d) => (
+            <button
+              key={d}
+              type="button"
+              className={`pill ${state.difficulty === d ? "is-active" : ""}`}
+              onClick={() => set("difficulty", state.difficulty === d ? "" : d)}
+            >
+              {d}
+            </button>
+          ))}
+        </div>
+
+        <div className="pills" role="group" aria-label="Sort">
+          <button
+            type="button"
+            className={`pill ${state.sort === "popular" ? "is-active" : ""}`}
+            onClick={() => set("sort", state.sort === "popular" ? "" : "popular")}
+            aria-pressed={state.sort === "popular"}
+            title="Sort by cross-learner popularity"
+          >
+            <Flame size={12} aria-hidden="true" /> popular
+          </button>
+        </div>
+
+        {hasFilters && (
+          <button type="button" className="clear" onClick={clear}>
+            <X size={14} aria-hidden="true" /> Clear
+          </button>
+        )}
+      </div>
+
+      {/* Row 2: tags wrap freely under the primary row */}
+      {tags.length > 0 && (
+        <div className="pills pills-tags" role="group" aria-label="Tags">
+          {tags.map((t) => (
+            <button
+              key={t}
+              type="button"
+              className={`pill ${state.tag === t ? "is-active" : ""}`}
+              onClick={() => set("tag", state.tag === t ? "" : t)}
+            >
+              #{t}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/home/Hero.astro

@@ -0,0 +1,60 @@
+---
+interface Props {
+  title?: string;
+  subtitle?: string;
+  /**
+   * Brand mark shown left of the headline. Defaults to `/logo.svg`
+   * (the scaffold ships a starter at `public/logo.svg`). Pass `""`
+   * to hide the logo entirely.
+   */
+  logoUrl?: string;
+}
+const {
+  title = "Handzon.",
+  subtitle = "Step-by-step tutorials.",
+  logoUrl = "/logo.svg",
+} = Astro.props;
+---
+<header class="hero">
+  <h1 class="hero-headline">
+    {logoUrl && (
+      <img class="hero-logo" src={logoUrl} alt="" aria-hidden="true" />
+    )}
+    <span>{title}</span>
+  </h1>
+  <p>{subtitle}</p>
+</header>
+
+<style>
+  .hero {
+    padding: 4rem 0 2rem;
+    border-bottom: var(--border-default, 2px) solid var(--color-border);
+  }
+  .hero-headline {
+    display: flex;
+    align-items: center;
+    gap: clamp(0.6rem, 1.2vw, 1rem);
+    margin: 0 0 0.75rem;
+    font-size: clamp(2.25rem, 5vw, 3.75rem);
+    font-weight: 700;
+    letter-spacing: -0.025em;
+    line-height: 1.05;
+  }
+  /* Logo height tracks the heading's cap-height (~0.72em of the
+   * font-size) so the brand mark visually matches the "H" glyph. The
+   * SVG's viewBox has been tightened to remove padding, so the box
+   * dimensions are the visible mark. */
+  .hero-logo {
+    height: 0.72em;
+    width: auto;
+    display: block;
+    flex-shrink: 0;
+  }
+  .hero p {
+    font-size: 1.125rem;
+    line-height: 1.55;
+    color: var(--color-muted);
+    max-width: 60ch;
+    margin: 0;
+  }
+</style>

package/src/components/home/Pagination.tsx

@@ -0,0 +1,89 @@
+import { useEffect, useState } from "react";
+
+interface Props {
+  /** How many cards to show per page. */
+  pageSize?: number;
+}
+
+/**
+ * Client-side pagination for the homepage tutorial grid.
+ *
+ * Works in concert with FilterBar:
+ * - FilterBar marks non-matching cards with `data-filter-hidden`.
+ * - Pagination marks beyond-page cards with `data-page-hidden`.
+ * - The CSS hides a card if either attribute is set.
+ *
+ * FilterBar fires a `hz:filter-changed` window event when the filter
+ * state changes; pagination listens and resets to page 1, then
+ * re-applies the page slice over the new filtered set.
+ */
+function applyPagination(page: number, pageSize: number): number {
+  const visibleByFilter = Array.from(
+    document.querySelectorAll<HTMLElement>(
+      "[data-search]:not([data-filter-hidden])",
+    ),
+  );
+  const start = (page - 1) * pageSize;
+  const end = start + pageSize;
+  visibleByFilter.forEach((card, idx) => {
+    if (idx >= start && idx < end) {
+      card.removeAttribute("data-page-hidden");
+    } else {
+      card.setAttribute("data-page-hidden", "");
+    }
+  });
+  return visibleByFilter.length;
+}
+
+export default function Pagination({ pageSize = 9 }: Props) {
+  const [page, setPage] = useState(1);
+  const [total, setTotal] = useState(0);
+
+  useEffect(() => {
+    setTotal(applyPagination(page, pageSize));
+  }, [page, pageSize]);
+
+  useEffect(() => {
+    function onFilterChanged() {
+      setPage(1);
+      setTotal(applyPagination(1, pageSize));
+    }
+    window.addEventListener("hz:filter-changed", onFilterChanged);
+    return () => window.removeEventListener("hz:filter-changed", onFilterChanged);
+  }, [pageSize]);
+
+  const totalPages = Math.max(1, Math.ceil(total / pageSize));
+  const safePage = Math.min(page, totalPages);
+  // Keep state coherent if the filter shrinks below the current page.
+  useEffect(() => {
+    if (safePage !== page) setPage(safePage);
+  }, [safePage, page]);
+
+  if (total <= pageSize) return null;
+
+  return (
+    <nav className="pagination" aria-label="Tutorial pages">
+      <button
+        type="button"
+        className="pg-btn"
+        onClick={() => setPage((p) => Math.max(1, p - 1))}
+        disabled={safePage <= 1}
+        aria-label="Previous page"
+      >
+        ← Prev
+      </button>
+      <span className="pg-status" aria-live="polite">
+        Page <strong>{safePage}</strong> of {totalPages}
+      </span>
+      <button
+        type="button"
+        className="pg-btn"
+        onClick={() => setPage((p) => Math.min(totalPages, p + 1))}
+        disabled={safePage >= totalPages}
+        aria-label="Next page"
+      >
+        Next →
+      </button>
+    </nav>
+  );
+}

package/src/components/home/ResumeRail.tsx

@@ -0,0 +1,50 @@
+import { useMemo } from "react";
+import { useProgressAfterMount } from "../../lib/progress/useProgress";
+
+interface Tutorial {
+  slug: string;
+  title: string;
+}
+
+interface Props {
+  tutorials: Tutorial[];
+}
+
+/**
+ * "Continue [Tutorial] / step  →" — a single bordered link that reads
+ * as one coherent action, replacing the previous three-color, three-
+ * size stack of label + title + step.
+ */
+export default function ResumeRail({ tutorials }: Props) {
+  const state = useProgressAfterMount();
+
+  const mostRecent = useMemo(() => {
+    if (!state) return null;
+    let best: { slug: string; step: string; ts: number } | null = null;
+    for (const [slug, entry] of Object.entries(state.lastVisited)) {
+      // Legacy shape (older builds stored `step` as a bare string)
+      // shows up as `unknown` at runtime — coerce so we don't crash.
+      const raw = entry as unknown;
+      const next =
+        typeof raw === "string"
+          ? { step: raw, ts: 0 }
+          : { step: (raw as { step: string }).step, ts: (raw as { ts?: number }).ts ?? 0 };
+      if (!best || next.ts > best.ts) best = { slug, ...next };
+    }
+    if (!best) return null;
+    const tutorial = tutorials.find((t) => t.slug === best.slug);
+    if (!tutorial) return null;
+    return { slug: best.slug, title: tutorial.title, step: best.step };
+  }, [state, tutorials]);
+
+  if (!state || !mostRecent) return null;
+
+  return (
+    <a className="resume-rail" href={`/${mostRecent.slug}/${mostRecent.step}`}>
+      <span className="rr-prefix">Continue</span>
+      <span className="rr-title">{mostRecent.title}</span>
+      <span className="rr-step">/ {mostRecent.step}</span>
+      <span className="rr-arrow" aria-hidden="true">→</span>
+    </a>
+  );
+}

package/src/components/home/TutorialCard.astro

@@ -0,0 +1,185 @@
+---
+import type { TutorialEntry } from "../../lib/content";
+
+interface Props {
+  tutorial: TutorialEntry;
+  duration?: string;
+}
+const { tutorial, duration } = Astro.props;
+const data = tutorial.data;
+const slug = tutorial.id;
+---
+<article
+  class="card"
+  data-difficulty={data.difficulty}
+  data-tags={data.tags.join(",")}
+  data-search={`${data.title} ${data.description} ${data.tags.join(" ")}`.toLowerCase()}
+  data-card-slug={slug}
+  data-popularity="0"
+>
+  <a href={`/${slug}`} class="card-link">
+    <div class="card-body">
+      <h3>{data.title}</h3>
+      <p>{data.description}</p>
+      <div class="badges">
+        <span class={`badge badge-${data.difficulty}`}>{data.difficulty}</span>
+        {duration && (
+          <span class="badge badge-neutral">
+            <svg
+              viewBox="0 0 24 24"
+              width="11"
+              height="11"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+              aria-hidden="true"
+            >
+              <circle cx="12" cy="12" r="10" />
+              <polyline points="12 7 12 12 15 14" />
+            </svg>
+            {duration}
+          </span>
+        )}
+      </div>
+      {data.tags.length > 0 && (
+        <div class="tags">
+          {data.tags.map((tag) => <span class="tag">#{tag}</span>)}
+        </div>
+      )}
+      <div
+        class="card-stats"
+        data-tutorial-stats-slug={slug}
+        aria-hidden="true"
+      ></div>
+      <div class="card-progress" data-tutorial-slug={slug}></div>
+    </div>
+  </a>
+</article>
+
+<style>
+  .card {
+    border: 1px solid var(--color-border);
+    background: var(--color-bg);
+    display: flex;
+    transition: border-color 0.12s ease, transform 0.12s ease;
+  }
+  .card:hover {
+    border-color: var(--color-accent);
+    transform: translateY(-2px);
+  }
+  .card-link {
+    color: var(--color-fg);
+    text-decoration: none;
+    display: flex;
+    flex-direction: column;
+    width: 100%;
+  }
+  .card-body {
+    padding: 1.1rem 1.2rem 1.2rem;
+    display: flex;
+    flex-direction: column;
+    flex: 1;
+  }
+
+  /* Metadata row: difficulty + duration, sitting *below* the
+   * description (was above). Keeps the title as the lead element and
+   * groups all the meta — badges, tags, progress — in the lower half
+   * of the card. */
+  .badges {
+    display: flex;
+    gap: 0.4rem;
+    margin-top: 0.85rem;
+    padding-bottom: 0.85rem;
+    border-bottom: 1px solid var(--color-border);
+    flex-wrap: wrap;
+  }
+  .badge svg {
+    flex-shrink: 0;
+  }
+  .badge {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    padding: 0.18rem 0.5rem;
+    font-family: var(--font-mono);
+    font-size: 0.68em;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    border: 1px solid var(--color-border);
+    color: var(--color-muted);
+  }
+  .badge-beginner::before,
+  .badge-intermediate::before,
+  .badge-advanced::before {
+    content: "";
+    width: 0.45rem;
+    height: 0.45rem;
+    border-radius: 50%;
+    background: currentColor;
+    flex-shrink: 0;
+  }
+  .badge-beginner { color: var(--color-success); }
+  .badge-intermediate { color: var(--color-warn); }
+  .badge-advanced { color: var(--color-danger); }
+
+  h3 {
+    font-size: 1.05rem;
+    font-weight: 700;
+    margin: 0 0 0.5rem;
+    letter-spacing: -0.015em;
+    line-height: 1.3;
+  }
+  p {
+    margin: 0;
+    color: var(--color-muted);
+    font-size: 0.92em;
+    line-height: 1.5;
+    /* Clamp to 3 lines so cards stay the same height regardless of
+     * description length. Keeps the grid visually consistent. */
+    display: -webkit-box;
+    -webkit-line-clamp: 3;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
+  }
+
+  /* Tags — quiet, hash-prefixed. Pinned toward the bottom via
+   * margin-top: auto so cards in the grid stay the same height when
+   * descriptions vary. */
+  .tags {
+    display: flex;
+    gap: 0.5rem;
+    flex-wrap: wrap;
+    margin-top: 0.85rem;
+  }
+  .tag {
+    font-family: var(--font-mono);
+    font-size: 0.7em;
+    color: var(--color-muted);
+  }
+
+  .card-progress:not(:empty) { padding-top: 0.5rem; }
+
+  /* Cross-learner popularity, hydrated from /api/tutorials/stats.
+   * Hidden until the script populates content so the card height
+   * stays stable on first paint and gracefully degrades on Tier 1
+   * (no DB → no numbers → no row). */
+  .card-stats:empty { display: none; }
+  .card-stats {
+    margin-top: 0.6rem;
+    display: flex;
+    gap: 0.6rem;
+    font-family: var(--font-mono);
+    font-size: 0.7em;
+    color: var(--color-muted);
+  }
+  .card-stats .stat {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.3rem;
+  }
+  .card-stats .stat-divider {
+    color: var(--color-border);
+  }
+</style>

package/src/components/mdx/Callout.astro

@@ -0,0 +1,77 @@
+---
+type CalloutType = "info" | "tip" | "warn" | "danger";
+
+interface Props {
+  type?: CalloutType;
+  title?: string;
+}
+
+const { type = "info", title } = Astro.props;
+
+const colorVar = {
+  info: "var(--color-info)",
+  tip: "var(--color-tip)",
+  warn: "var(--color-warn)",
+  danger: "var(--color-danger)",
+}[type];
+
+const label = {
+  info: "Note",
+  tip: "Tip",
+  warn: "Warning",
+  danger: "Heads up",
+}[type];
+
+// Single-element SVG per type (Astro templates don't support React-style
+// fragments inside expressions). Each is a Lucide-style outline icon.
+const iconPaths = {
+  info: '<circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/>',
+  tip: '<path d="M15 14c.2-1 .7-1.7 1.5-2.5C17.7 10.2 18 9 18 8a6 6 0 0 0-12 0c0 1 .3 2.2 1.5 3.5.8.8 1.3 1.5 1.5 2.5"/><path d="M9 18h6"/><path d="M10 22h4"/>',
+  warn: '<path d="M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/>',
+  danger:
+    '<circle cx="12" cy="12" r="10"/><line x1="12" y1="8" x2="12" y2="12"/><line x1="12" y1="16" x2="12.01" y2="16"/>',
+}[type];
+---
+
+<aside class="callout" data-type={type} style={`--callout-color: ${colorVar};`}>
+  <div class="callout-bar"></div>
+  <div class="callout-body">
+    <div class="callout-label">
+      <svg class="callout-icon" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" set:html={iconPaths} />
+      <span>{title ?? label}</span>
+    </div>
+    <div class="callout-content"><slot /></div>
+  </div>
+</aside>
+
+<style>
+  .callout {
+    display: flex;
+    gap: 0;
+    margin: 1.25rem 0;
+    background: color-mix(in oklab, var(--callout-color) 12%, var(--color-bg));
+    border: var(--border-default) solid color-mix(in oklab, var(--callout-color) 40%, var(--color-border));
+    border-left: 3px solid var(--callout-color);
+    border-radius: 0;
+    overflow: hidden;
+  }
+  .callout-bar { display: none; }
+  .callout-body {
+    padding: 0.7rem 1rem;
+    flex: 1;
+  }
+  .callout-label {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    text-transform: uppercase;
+    font-size: 0.7rem;
+    letter-spacing: 0.08em;
+    color: var(--callout-color);
+    font-weight: 700;
+    margin-bottom: 0.3rem;
+  }
+  .callout-icon { color: var(--callout-color); flex-shrink: 0; }
+  .callout-content :global(p:first-child) { margin-top: 0; }
+  .callout-content :global(p:last-child) { margin-bottom: 0; }
+</style>

package/src/components/mdx/Checkpoint.astro

@@ -0,0 +1,14 @@
+---
+import CheckpointIsland from "./Checkpoint.tsx";
+
+interface Props {
+  label: string;
+  id?: string;
+}
+const props = Astro.props as Props;
+
+// The host step/tutorial come from the page-level route marker (set by
+// TutorialLayout). Reading them client-side keeps the Astro wrapper simple
+// and means authors never have to pass them by hand.
+---
+<CheckpointIsland client:load {...props} />

package/src/components/mdx/Checkpoint.tsx

@@ -0,0 +1,49 @@
+import { Check } from "lucide-react";
+import { useEffect, useId, useState } from "react";
+import { useProgress } from "../../lib/progress/useProgress";
+
+interface Props {
+  label: string;
+  id?: string;
+}
+
+/**
+ * Reads the host tutorial/step from the page-level route marker
+ * (<div id="tt-route" data-tutorial-slug=... data-step-slug=...>) that
+ * TutorialLayout emits. Looking it up here keeps the Astro wrapper trivial.
+ */
+function useRoute() {
+  const [route, setRoute] = useState<{ tutorial: string; step: string } | null>(null);
+  useEffect(() => {
+    const el = document.getElementById("tt-route");
+    if (!el) return;
+    const tutorial = el.dataset.tutorialSlug;
+    const step = el.dataset.stepSlug;
+    if (tutorial && step) setRoute({ tutorial, step });
+  }, []);
+  return route;
+}
+
+export default function Checkpoint({ label, id }: Props) {
+  const reactId = useId();
+  const checkpointId = id ?? `checkpoint:${reactId}:${label.slice(0, 40)}`;
+  const { state, recordCheckpoint, markStepComplete } = useProgress();
+  const route = useRoute();
+  const done = !!state.checkpoints[checkpointId];
+
+  function onToggle() {
+    if (done) return;
+    recordCheckpoint(checkpointId);
+    if (route) markStepComplete(route.tutorial, route.step);
+  }
+
+  return (
+    <div className={done ? "checkpoint is-done" : "checkpoint"}>
+      <button type="button" onClick={onToggle} aria-pressed={done}>
+        <span className="checkpoint-box">{done && <Check size={16} />}</span>
+        <span>{label}</span>
+      </button>
+      {done && <span className="checkpoint-msg">Step complete</span>}
+    </div>
+  );
+}

package/src/components/mdx/Diff.astro

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