handzon-core 0.6.0

package/src/lib/rehype-mermaid-passthrough.ts

@@ -0,0 +1,31 @@
+import type { Element, Root, Text } from "hast";
+import { visit } from "unist-util-visit";
+
+/**
+ * Rewrite <pre><code class="language-mermaid">…</code></pre> into
+ * <pre class="mermaid">…</pre> so the client-side mermaid loader in
+ * BaseLayout can render it. Zero build-time deps (no playwright).
+ */
+export default function rehypeMermaidPassthrough() {
+  return (tree: Root) => {
+    visit(tree, "element", (node: Element, index, parent) => {
+      if (node.tagName !== "pre" || !parent || index === undefined) return;
+      const code = node.children.find(
+        (c): c is Element => c.type === "element" && c.tagName === "code",
+      );
+      if (!code) return;
+      const classes = (code.properties?.className as string[] | undefined) ?? [];
+      if (!classes.includes("language-mermaid")) return;
+      const source = code.children
+        .filter((c): c is Text => c.type === "text")
+        .map((c) => c.value)
+        .join("");
+      (parent.children as Element[])[index] = {
+        type: "element",
+        tagName: "pre",
+        properties: { className: ["mermaid"] },
+        children: [{ type: "text", value: source }],
+      };
+    });
+  };
+}

package/src/pages/Home.astro

@@ -0,0 +1,408 @@
+---
+import BaseLayout from "../layouts/BaseLayout.astro";
+import Hero from "../components/home/Hero.astro";
+import TutorialCard from "../components/home/TutorialCard.astro";
+import FilterBar from "../components/home/FilterBar.tsx";
+import Pagination from "../components/home/Pagination.tsx";
+import ResumeRail from "../components/home/ResumeRail.tsx";
+import { getTutorials, getStepsForTutorial, sumDurations } from "../lib/content.ts";
+
+interface Props {
+  siteName?: string;
+  tagline?: string;
+  hero?: { title?: string; subtitle?: string };
+  logoUrl?: string;
+  faviconUrl?: string;
+  repoUrl?: string;
+  showResumeRail?: boolean;
+  emptyStateCommand?: string;
+  /** Tutorials per page on the grid. */
+  pageSize?: number;
+}
+
+const {
+  siteName = "Handzon",
+  tagline = "Hands-on tutorials",
+  hero,
+  logoUrl,
+  faviconUrl,
+  repoUrl,
+  showResumeRail = true,
+  emptyStateCommand = "pnpm handzon:new",
+  pageSize = 9,
+} = Astro.props;
+
+const tutorials = await getTutorials();
+const stepsByTutorial = new Map(
+  await Promise.all(
+    tutorials.map(async (t) => [t.id, await getStepsForTutorial(t.id)] as const),
+  ),
+);
+const difficulties = ["beginner", "intermediate", "advanced"];
+const tags = Array.from(new Set(tutorials.flatMap((t) => t.data.tags))).sort();
+const compactTutorials = tutorials.map((t) => ({ slug: t.id, title: t.data.title }));
+---
+<BaseLayout
+  siteName={siteName}
+  tagline={tagline}
+  logoUrl={logoUrl}
+  faviconUrl={faviconUrl}
+  repoUrl={repoUrl}
+  nav="userMenu"
+>
+  <div class="home">
+    <Hero title={hero?.title} subtitle={hero?.subtitle} logoUrl={logoUrl} />
+
+    {showResumeRail && (
+      <ResumeRail client:load tutorials={compactTutorials} />
+    )}
+
+    <FilterBar client:load difficulties={difficulties} tags={tags} />
+
+    <section class="grid">
+      {tutorials.map((tut) => {
+        const steps = stepsByTutorial.get(tut.id) ?? [];
+        const dur = tut.data.estimatedDuration ?? sumDurations(steps);
+        return <TutorialCard tutorial={tut} duration={dur} />;
+      })}
+    </section>
+
+    <Pagination client:load pageSize={pageSize} />
+
+    <div class="empty" data-empty-state hidden>
+      <p>No tutorials match the current filters.</p>
+    </div>
+
+    {tutorials.length === 0 && (
+      <div class="empty">
+        <p>
+          No tutorials yet. Run <code>{emptyStateCommand}</code> to create your first one.
+        </p>
+      </div>
+    )}
+  </div>
+
+  <script>
+    // Hydrate per-card progress mini-bars from localStorage. Use a subpath
+    // import to avoid pulling the server-only barrel into the client bundle.
+    import { getStore } from "../lib/progress/local.ts";
+    function refresh() {
+      const state = getStore().get();
+      const totals = new Map<string, number>();
+      const completed = new Map<string, number>();
+      for (const [key, value] of Object.entries(state.steps)) {
+        const slug = key.split("/")[0];
+        if (!slug) continue;
+        totals.set(slug, (totals.get(slug) ?? 0) + 1);
+        if (value === "complete") completed.set(slug, (completed.get(slug) ?? 0) + 1);
+      }
+      document.querySelectorAll<HTMLElement>("[data-tutorial-slug]").forEach((el) => {
+        const slug = el.dataset.tutorialSlug!;
+        const done = completed.get(slug) ?? 0;
+        const total = totals.get(slug) ?? 0;
+        if (total === 0) return;
+        const pct = Math.round((done / total) * 100);
+        el.innerHTML = `<div class="mini-bar"><div style="width:${pct}%"></div></div><span>${done}/${total} steps</span>`;
+      });
+    }
+    refresh();
+    getStore().subscribe(refresh);
+  </script>
+
+  <script>
+    // Hydrate cross-learner popularity numbers and the `data-popularity`
+    // attribute used by the FilterBar's "Popular" sort. Single fetch on
+    // mount; Cache-Control: max-age=60 on the response handles SPA-like
+    // navigations. Failures are silent — cards just show no numbers,
+    // which is the desired state on Tier 1 anyway.
+    type Stat = { slug: string; started: number; completed: number };
+    function fmt(n: number): string {
+      if (n < 1000) return String(n);
+      if (n < 10_000) return `${(n / 1000).toFixed(1)}k`;
+      if (n < 1_000_000) return `${Math.round(n / 1000)}k`;
+      return `${(n / 1_000_000).toFixed(1)}M`;
+    }
+    function popularityScore(stat: Stat): number {
+      // Weight completion higher than start. Completed learners are a
+      // much stronger signal than visitors who bounced after step 1.
+      return stat.completed * 3 + stat.started;
+    }
+    async function hydrateStats() {
+      try {
+        const res = await fetch("/api/tutorials/stats", { credentials: "same-origin" });
+        if (!res.ok) return;
+        const data = (await res.json()) as { stats: Stat[] };
+        for (const stat of data.stats) {
+          const card = document.querySelector<HTMLElement>(
+            `[data-card-slug="${CSS.escape(stat.slug)}"]`,
+          );
+          if (!card) continue;
+          card.dataset.popularity = String(popularityScore(stat));
+          const slot = card.querySelector<HTMLElement>(
+            `[data-tutorial-stats-slug="${CSS.escape(stat.slug)}"]`,
+          );
+          if (!slot) continue;
+          if (stat.started === 0 && stat.completed === 0) continue;
+          slot.innerHTML =
+            `<span class="stat" title="Unique learners started">▶ ${fmt(stat.started)} started</span>` +
+            `<span class="stat-divider">·</span>` +
+            `<span class="stat" title="Unique learners completed">✓ ${fmt(stat.completed)} finished</span>`;
+        }
+        window.dispatchEvent(new CustomEvent("hz:stats-loaded"));
+      } catch {
+        // ignore
+      }
+    }
+    hydrateStats();
+  </script>
+
+  <script>
+    // Popularity sort: re-orders cards in place by writing CSS `order`
+    // from `data-popularity`. Composes with the existing filter/page
+    // hide attributes because order is a flex/grid layout concern, not
+    // a visibility concern.
+    function applySort(mode: string) {
+      const cards = document.querySelectorAll<HTMLElement>("[data-card-slug]");
+      if (mode === "popular") {
+        const sorted = Array.from(cards).sort((a, b) => {
+          return Number(b.dataset.popularity ?? 0) - Number(a.dataset.popularity ?? 0);
+        });
+        sorted.forEach((card, idx) => {
+          card.style.order = String(idx);
+        });
+      } else {
+        cards.forEach((card) => {
+          card.style.removeProperty("order");
+        });
+      }
+    }
+    function syncFromUrl() {
+      const url = new URL(window.location.href);
+      applySort(url.searchParams.get("sort") ?? "");
+    }
+    syncFromUrl();
+    window.addEventListener("hz:sort-changed", (e) => {
+      applySort((e as CustomEvent<{ sort: string }>).detail.sort);
+    });
+    window.addEventListener("hz:stats-loaded", syncFromUrl);
+  </script>
+</BaseLayout>
+
+<style>
+  .home {
+    max-width: 80rem;
+    margin: 0 auto;
+    padding: 0 clamp(1rem, 4vw, 2rem) 4rem;
+  }
+  .grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+    gap: 1rem;
+    margin-top: 1.5rem;
+  }
+  .empty {
+    margin: 2rem 0;
+    padding: 2rem;
+    border: var(--border-default, 2px) solid var(--color-border);
+    text-align: center;
+    color: var(--color-muted);
+  }
+</style>
+
+<style is:global>
+  /* ---------- Resume rail ---------- */
+  /* One coherent link, not a stack of three competing styles. Border
+   * lights up on hover; the trailing → is the accent. Everything else
+   * sits on a single muted/foreground baseline. */
+  .resume-rail {
+    display: flex;
+    align-items: baseline;
+    gap: 0.5rem;
+    margin-top: 1.5rem;
+    padding: 0.7rem 0.95rem;
+    border: 1px solid var(--color-border);
+    color: var(--color-fg);
+    font-size: 0.95em;
+    text-decoration: none;
+    transition: border-color 0.12s ease, background 0.12s ease;
+  }
+  .resume-rail:hover {
+    border-color: var(--color-accent);
+    background: color-mix(in oklab, var(--color-accent) 6%, transparent);
+  }
+  .rr-prefix {
+    font-family: var(--font-mono);
+    font-size: 0.78em;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--color-muted);
+  }
+  .rr-title { font-weight: 600; }
+  .rr-step {
+    color: var(--color-muted);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .rr-arrow {
+    margin-left: auto;
+    color: var(--color-accent);
+    font-family: var(--font-mono);
+    transition: transform 0.12s ease;
+  }
+  .resume-rail:hover .rr-arrow { transform: translateX(3px); }
+
+  /* ---------- Filter bar ---------- */
+  /* Two rows: search + level + clear on top, tag pills on a wrapping
+   * second row. Replaces the previous one-line flex-wrap that crammed
+   * 20+ pills into the same row as the input. */
+  /* Consistent vertical rhythm on the home page:
+   *   - Every block (resume rail, filterbar, grid) gets 1.5rem above.
+   *   - Inside the filterbar, the search row → tags row gap is 1rem.
+   * The previous design also had padding-bottom + border-bottom on
+   * the filterbar, which doubled the spacing below the tags
+   * relative to the 1.5rem above the search bar — that visible
+   * imbalance is gone now. */
+  .filterbar {
+    display: flex;
+    flex-direction: column;
+    gap: 1.5rem;
+    margin-top: 1.5rem;
+  }
+  .fb-row-primary {
+    display: flex;
+    gap: 0.75rem;
+    align-items: stretch;
+    flex-wrap: wrap;
+  }
+  /* Stretch the pills group itself so each pill can flex to row height */
+  .fb-row-primary .pills {
+    align-items: stretch;
+  }
+  .filterbar .search {
+    flex: 1 1 22rem;
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.45rem 0.7rem;
+    border: 1px solid var(--color-border);
+    color: var(--color-muted);
+    transition: border-color 0.12s ease, color 0.12s ease;
+  }
+  .filterbar .search:focus-within {
+    border-color: var(--color-accent);
+    color: var(--color-fg);
+  }
+  .filterbar input {
+    background: transparent;
+    border: 0;
+    color: var(--color-fg);
+    font: inherit;
+    outline: none;
+    width: 100%;
+  }
+  .pills {
+    display: inline-flex;
+    flex-wrap: wrap;
+    gap: 0.3rem;
+    align-items: center;
+  }
+  .pill {
+    padding: 0.3rem 0.65rem;
+    border: 1px solid var(--color-border);
+    background: transparent;
+    color: var(--color-muted);
+    font-family: var(--font-mono);
+    font-size: 0.75em;
+    cursor: pointer;
+    text-transform: lowercase;
+    transition: border-color 0.12s ease, color 0.12s ease, background 0.12s ease;
+  }
+  /* Pills in the primary row stretch to match the search input's
+   * height so the whole row reads as one strip. align-items on the
+   * inner flex re-centers the text within each grown pill. Tag pills
+   * stay compact on the secondary row. */
+  .fb-row-primary .pill,
+  .fb-row-primary .clear {
+    padding: 0 0.85rem;
+    align-items: center;
+  }
+  .pill:hover {
+    border-color: var(--color-accent);
+    color: var(--color-fg);
+  }
+  .pill.is-active {
+    background: var(--color-accent);
+    color: var(--color-accent-fg);
+    border-color: var(--color-accent);
+  }
+  .clear {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.3rem;
+    padding: 0.3rem 0.6rem;
+    background: transparent;
+    border: 1px solid var(--color-border);
+    color: var(--color-muted);
+    font-family: var(--font-mono);
+    font-size: 0.75em;
+    cursor: pointer;
+    transition: color 0.12s ease, border-color 0.12s ease;
+  }
+  .clear:hover { color: var(--color-fg); border-color: var(--color-fg); }
+
+  /* Cards hidden by filter and/or pagination. Both layers set their
+   * own data-attribute so they compose without stomping each other. */
+  [data-filter-hidden],
+  [data-page-hidden] {
+    display: none !important;
+  }
+
+  /* ---------- Pagination ---------- */
+  .pagination {
+    margin-top: 1.5rem;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    gap: 1rem;
+    font-family: var(--font-mono);
+    font-size: 0.85em;
+    color: var(--color-muted);
+  }
+  .pg-btn {
+    padding: 0.45rem 0.85rem;
+    background: transparent;
+    border: 1px solid var(--color-border);
+    color: var(--color-fg);
+    font: inherit;
+    cursor: pointer;
+    transition: border-color 0.12s ease, color 0.12s ease;
+  }
+  .pg-btn:hover:not(:disabled) {
+    border-color: var(--color-accent);
+    color: var(--color-accent);
+  }
+  .pg-btn:disabled {
+    opacity: 0.4;
+    cursor: not-allowed;
+  }
+  .pg-status strong { color: var(--color-fg); }
+
+  /* ---------- Per-card mini progress bar ---------- */
+  [data-tutorial-slug] {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    margin-top: 0.75rem;
+    font-family: var(--font-mono);
+    font-size: 0.7em;
+    color: var(--color-muted);
+  }
+  .mini-bar {
+    flex: 1;
+    height: 3px;
+    background: var(--color-surface);
+    overflow: hidden;
+  }
+  .mini-bar div { background: var(--color-accent); height: 100%; }
+</style>