handzon-core 0.6.1 → 0.7.0

package/src/pages/Home.astro

@@ -41,6 +41,16 @@ const stepsByTutorial = new Map(
 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 }));
+
+// Hit counts per facet. Computed server-side over the already-loaded
+// tutorials list (no extra IO). Passed to FilterBar as plain Records;
+// Maps don't serialize across the SSR/island boundary.
+const difficultyCounts: Record<string, number> = {};
+const tagCounts: Record<string, number> = {};
+for (const t of tutorials) {
+  difficultyCounts[t.data.difficulty] = (difficultyCounts[t.data.difficulty] ?? 0) + 1;
+  for (const tag of t.data.tags) tagCounts[tag] = (tagCounts[tag] ?? 0) + 1;
+}
 ---
 <BaseLayout
   siteName={siteName}
@@ -57,13 +67,21 @@ const compactTutorials = tutorials.map((t) => ({ slug: t.id, title: t.data.title
       <ResumeRail client:load tutorials={compactTutorials} />
     )}
 
-    <FilterBar client:load difficulties={difficulties} tags={tags} />
+    <FilterBar
+      client:load
+      difficulties={difficulties}
+      tags={tags}
+      difficultyCounts={difficultyCounts}
+      tagCounts={tagCounts}
+    />
+
+    <div class="results-status" data-results-status aria-live="polite"></div>
 
     <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} />;
+        return <TutorialCard tutorial={tut} duration={dur} stepCount={steps.length} />;
       })}
     </section>
 
@@ -88,21 +106,39 @@ const compactTutorials = tutorials.map((t) => ({ slug: t.id, title: t.data.title
     import { getStore } from "../lib/progress/local.ts";
     function refresh() {
       const state = getStore().get();
-      const totals = new Map<string, number>();
+      // Only the *numerator* (completed-step count) is computed from
+      // localStorage. The *denominator* comes from the card's
+      // server-rendered `data-step-count` so a learner who's only
+      // visited 1 of 4 steps still sees "1/4", not "1/1".
       const completed = new Map<string, number>();
       for (const [key, value] of Object.entries(state.steps)) {
+        if (value !== "complete") continue;
         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);
+        completed.set(slug, (completed.get(slug) ?? 0) + 1);
       }
+      // SVG ring geometry: r=9 → circumference 2π·9 ≈ 56.5485.
+      const R = 9;
+      const C = 2 * Math.PI * R;
       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>`;
+        const total = Number(el.dataset.stepCount ?? "0");
+        const done = Math.min(completed.get(slug) ?? 0, total);
+        if (total === 0 || done === 0) {
+          el.innerHTML = "";
+          return;
+        }
+        const pct = done / total;
+        const offset = C * (1 - pct);
+        el.setAttribute("title", `${done} of ${total} steps complete`);
+        el.innerHTML =
+          `<span class="ring-label">${done}/${total}</span>` +
+          `<svg class="ring" viewBox="0 0 24 24" width="22" height="22" aria-hidden="true">` +
+            `<circle class="ring-track" cx="12" cy="12" r="${R}"></circle>` +
+            `<circle class="ring-fill" cx="12" cy="12" r="${R}" ` +
+              `stroke-dasharray="${C.toFixed(2)}" ` +
+              `stroke-dashoffset="${offset.toFixed(2)}"></circle>` +
+          `</svg>`;
       });
     }
     refresh();
@@ -190,6 +226,12 @@ const compactTutorials = tutorials.map((t) => ({ slug: t.id, title: t.data.title
 
 <style>
   .home {
+    /* width: 100% defeats the auto-margin space-absorption that
+     * BaseLayout's flex-column body would otherwise apply, so the
+     * page actually reaches its max-width at wide viewports. Without
+     * this, auto margins eat all the slack and the column collapses
+     * to its content width. */
+    width: 100%;
     max-width: 80rem;
     margin: 0 auto;
     padding: 0 clamp(1rem, 4vw, 2rem) 4rem;
@@ -198,8 +240,16 @@ const compactTutorials = tutorials.map((t) => ({ slug: t.id, title: t.data.title
     display: grid;
     grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
     gap: 1rem;
-    margin-top: 1.5rem;
+    margin-top: 0.75rem;
+  }
+  .results-status {
+    margin-top: 1rem;
+    font-family: var(--font-mono);
+    font-size: 0.78em;
+    color: var(--color-muted);
+    min-height: 1em;
   }
+  .results-status:empty { display: none; }
   .empty {
     margin: 2rem 0;
     padding: 2rem;
@@ -252,107 +302,10 @@ const compactTutorials = tutorials.map((t) => ({ slug: t.id, title: t.data.title
   }
   .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. */
+  /* Filterbar + multi-select popover + pill styles live in
+   * packages/core/styles/components/filterbar.css and multiselect.css.
+   * Cards hidden by filter and/or pagination — both layers compose
+   * via their own data-attribute. */
   [data-filter-hidden],
   [data-page-hidden] {
     display: none !important;
@@ -388,21 +341,4 @@ const compactTutorials = tutorials.map((t) => ({ slug: t.id, title: t.data.title
   }
   .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>

package/src/pages/paths.ts

@@ -5,8 +5,9 @@
  *   export const getStaticPaths = getTutorialLandingPaths;
  *   export const getStaticPaths = getTutorialStepPaths;
  */
-import { getStepsForTutorial, getTutorials, parseStepId } from "../lib/content.ts";
+
 import type { StepEntry, TutorialEntry } from "../lib/content.ts";
+import { getStepsForTutorial, getTutorials, parseStepId } from "../lib/content.ts";
 
 export async function getTutorialLandingPaths() {
   const tutorials = await getTutorials();

package/src/server/auth/config.ts

@@ -10,8 +10,9 @@
  * GitHub is the only provider in 0.2; email/password and others are
  * out of scope (see plan: github-auth_d52529d5).
  */
-import { DrizzleAdapter } from "@auth/drizzle-adapter";
+
 import GitHub from "@auth/core/providers/github";
+import { DrizzleAdapter } from "@auth/drizzle-adapter";
 import { defineConfig } from "auth-astro";
 import { accounts, sessions, users, verificationTokens } from "./schema.ts";
 

package/src/server/auth/schema.ts

@@ -6,14 +6,7 @@
  * The `learners` row that maps a signed-in user to local progress lives
  * in `../db/schema.ts` — it adds a nullable `user_id` FK to `users` here.
  */
-import {
-  integer,
-  pgTable,
-  primaryKey,
-  text,
-  timestamp,
-  uuid,
-} from "drizzle-orm/pg-core";
+import { integer, pgTable, primaryKey, text, timestamp, uuid } from "drizzle-orm/pg-core";
 
 export const users = pgTable("users", {
   id: uuid("id").primaryKey().defaultRandom(),

package/src/server/auth.ts

@@ -61,11 +61,7 @@ export async function getOrCreateLearner(
   // Anonymous path — unchanged from pre-auth behaviour.
   let deviceId = cookies.get(COOKIE)?.value;
   if (deviceId) {
-    const found = await db
-      .select()
-      .from(learners)
-      .where(eq(learners.deviceId, deviceId))
-      .limit(1);
+    const found = await db.select().from(learners).where(eq(learners.deviceId, deviceId)).limit(1);
     if (found[0]) return { id: found[0].id, deviceId };
   }
   deviceId = randomDeviceId();

package/src/server/db/schema.ts

@@ -13,7 +13,7 @@ import { users } from "../auth/schema.ts";
 
 // Re-export the Auth.js tables so consumers (and drizzle-kit) see one
 // schema barrel.
-export { users, accounts, sessions, verificationTokens } from "../auth/schema.ts";
+export { accounts, sessions, users, verificationTokens } from "../auth/schema.ts";
 
 export const learners = pgTable(
   "learners",

package/src/server/handlers/progress.ts

@@ -1,5 +1,5 @@
 import type { APIRoute } from "astro";
-import { eq, sql } from "drizzle-orm";
+import { and, eq, sql } from "drizzle-orm";
 import { z } from "zod";
 import { getOrCreateLearner } from "../auth.ts";
 import { getDb } from "../db/client.ts";
@@ -61,30 +61,53 @@ export const POST: APIRoute = async ({ cookies, request }) => {
   const learner = await getOrCreateLearner(cookies, request);
   const db = getDb();
   const now = new Date();
-  const rows = parsed.map((b) => ({
-    learnerId: learner.id,
-    kind: b.kind,
-    scope: b.scope,
-    key: b.key,
-    value: b.value,
-    updatedAt: now,
-  }));
-  await db
-    .insert(progressEntries)
-    .values(rows)
-    .onConflictDoUpdate({
-      target: [
-        progressEntries.learnerId,
-        progressEntries.kind,
-        progressEntries.scope,
-        progressEntries.key,
-      ],
-      set: {
-        // `excluded` is the row Postgres would have inserted — without
-        // this the SET was a no-op (`value = progress_entries.value`).
-        value: sql`excluded.value`,
-        updatedAt: sql`excluded.updated_at`,
-      },
-    });
-  return json({ written: rows.length });
+
+  // `value: null` is the tombstone signal for "this entry was undone"
+  // (e.g. unchecking a checkpoint). The `value` column is NOT NULL, so
+  // we DELETE these rows instead of upserting them.
+  const deletes = parsed.filter((b) => b.value === null);
+  const upserts = parsed.filter((b) => b.value !== null);
+
+  for (const d of deletes) {
+    await db
+      .delete(progressEntries)
+      .where(
+        and(
+          eq(progressEntries.learnerId, learner.id),
+          eq(progressEntries.kind, d.kind),
+          eq(progressEntries.scope, d.scope),
+          eq(progressEntries.key, d.key),
+        ),
+      );
+  }
+
+  if (upserts.length > 0) {
+    const rows = upserts.map((b) => ({
+      learnerId: learner.id,
+      kind: b.kind,
+      scope: b.scope,
+      key: b.key,
+      value: b.value,
+      updatedAt: now,
+    }));
+    await db
+      .insert(progressEntries)
+      .values(rows)
+      .onConflictDoUpdate({
+        target: [
+          progressEntries.learnerId,
+          progressEntries.kind,
+          progressEntries.scope,
+          progressEntries.key,
+        ],
+        set: {
+          // `excluded` is the row Postgres would have inserted — without
+          // this the SET was a no-op (`value = progress_entries.value`).
+          value: sql`excluded.value`,
+          updatedAt: sql`excluded.updated_at`,
+        },
+      });
+  }
+
+  return json({ written: parsed.length });
 };

package/src/server/handlers/tutorialStats.ts

@@ -29,9 +29,12 @@ let cache: CacheEntry | null = null;
  */
 export const GET: APIRoute = async () => {
   if (!process.env.DATABASE_URL) {
-    return json({ stats: [] satisfies TutorialStat[] }, {
-      headers: { "Cache-Control": "public, max-age=60" },
-    });
+    return json(
+      { stats: [] satisfies TutorialStat[] },
+      {
+        headers: { "Cache-Control": "public, max-age=60" },
+      },
+    );
   }
   const now = Date.now();
   if (cache && cache.expiresAt > now) {

package/styles/components/dropdown.css

@@ -0,0 +1,144 @@
+/* Shared dropdown component (handzon-core/src/components/ui/Dropdown.tsx).
+ *
+ * Wraps Radix Select so we never ship the browser-native dropdown UI.
+ * Every dropdown in handzon-core inherits these styles — keep the look
+ * mono/brutalist (hard edges, uppercase mono label chip, accent border
+ * on focus / open) so dropdowns sit alongside the search input, pills,
+ * and pagination buttons without visual drift.
+ */
+
+.hz-dd {
+  display: inline-flex;
+  align-items: stretch;
+  font-family: var(--font-mono);
+  font-size: 0.78em;
+}
+
+/* Uppercase mono label chip glued to the trigger. */
+.hz-dd-label {
+  display: inline-flex;
+  align-items: center;
+  padding: 0 0.6rem;
+  border: 1px solid var(--color-border);
+  border-right: 0;
+  color: var(--color-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  user-select: none;
+}
+
+.hz-dd-trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.45rem;
+  padding: 0.4rem 0.6rem;
+  /* Match the search input's natural height so the whole toolbar row
+   * shares a single baseline. Without this, the Sort dropdown reads
+   * ~6px shorter than the multi-select triggers which stretch via
+   * the toolbar's align-items: stretch. */
+  min-height: 2.5rem;
+  background: transparent;
+  border: 1px solid var(--color-border);
+  color: var(--color-fg);
+  font: inherit;
+  cursor: pointer;
+  outline: none;
+  transition: border-color 0.12s ease, color 0.12s ease;
+}
+.hz-dd-trigger:hover {
+  border-color: var(--color-accent);
+}
+.hz-dd-trigger:focus-visible,
+.hz-dd-trigger[data-state="open"] {
+  border-color: var(--color-accent);
+  color: var(--color-accent);
+}
+.hz-dd-trigger[data-placeholder] {
+  color: var(--color-muted);
+}
+
+.hz-dd-tricon {
+  display: inline-flex;
+  align-items: center;
+  color: var(--color-muted);
+}
+
+.hz-dd-caret {
+  display: inline-flex;
+  align-items: center;
+  margin-left: 0.15rem;
+  color: var(--color-muted);
+  transition: transform 0.15s ease;
+}
+.hz-dd-trigger[data-state="open"] .hz-dd-caret {
+  transform: rotate(180deg);
+  color: var(--color-accent);
+}
+
+/* ---------- Popover ---------- */
+
+.hz-dd-content {
+  /* Radix Portal renders this outside the normal flow — float it above
+   * the page chrome, including the sticky sidebar (z=10) and the fixed
+   * topbar (z=50). */
+  z-index: 100;
+  min-width: var(--radix-select-trigger-width);
+  max-height: var(--radix-select-content-available-height);
+  background: var(--color-bg);
+  border: 1px solid var(--color-border);
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.35);
+  overflow: hidden;
+}
+
+.hz-dd-viewport {
+  padding: 0.25rem 0;
+}
+
+.hz-dd-item {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.45rem 0.75rem;
+  color: var(--color-fg);
+  cursor: pointer;
+  user-select: none;
+  outline: none;
+}
+.hz-dd-item[data-highlighted] {
+  background: var(--color-surface);
+  color: var(--color-accent);
+}
+.hz-dd-item[data-state="checked"] {
+  color: var(--color-accent);
+}
+.hz-dd-item[data-disabled] {
+  opacity: 0.4;
+  pointer-events: none;
+}
+
+.hz-dd-icon {
+  display: inline-flex;
+  align-items: center;
+  color: var(--color-muted);
+}
+.hz-dd-item[data-highlighted] .hz-dd-icon,
+.hz-dd-item[data-state="checked"] .hz-dd-icon {
+  color: var(--color-accent);
+}
+
+.hz-dd-check {
+  margin-left: auto;
+  display: inline-flex;
+  align-items: center;
+  color: var(--color-accent);
+}
+
+.hz-dd-scroll {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 1.5rem;
+  color: var(--color-muted);
+  background: var(--color-bg);
+  cursor: default;
+}

package/styles/components/filterbar.css

@@ -0,0 +1,128 @@
+/* Home-page filter bar.
+ *
+ * One toolbar row with search + Level dropdown + Topics dropdown + a
+ * vertical divider + Sort dropdown. Beneath it: optional "popular
+ * topics" pill row (top tags by count) and an "active filters" chip
+ * row that only appears when at least one filter is set.
+ *
+ * The dropdowns themselves (their trigger chrome and popover content)
+ * are styled in dropdown.css and multiselect.css respectively — this
+ * file only handles the toolbar layout + the inline pill + chip rows.
+ */
+
+.filterbar {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  margin-top: 1.5rem;
+}
+
+/* ---------- Toolbar (search + facets + sort) ---------- */
+
+.fb-toolbar {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: stretch;
+  gap: 0.75rem;
+}
+
+.fb-toolbar .search {
+  flex: 1 1 16rem;
+  min-width: 12rem;
+  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;
+}
+.fb-toolbar .search:focus-within {
+  border-color: var(--color-accent);
+  color: var(--color-fg);
+}
+.fb-toolbar .search input {
+  background: transparent;
+  border: 0;
+  color: var(--color-fg);
+  font: inherit;
+  outline: none;
+  width: 100%;
+}
+
+/* Visual separator marking "sort isn't a filter". The sort cluster
+ * pushes itself to the right edge so the divider falls in a natural
+ * spot. */
+.fb-divider {
+  width: 0;
+  border-left: 1px solid var(--color-border);
+  align-self: stretch;
+  margin: 0 0.25rem;
+}
+.fb-sort-slot {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+}
+
+/* On narrow viewports the toolbar wraps; sort drops to its own line.
+ * Keep the divider visible only when the row hasn't wrapped — when it
+ * has, the layout already reads as distinct rows. Cheap heuristic:
+ * hide the divider below ~640px viewport. */
+@media (max-width: 640px) {
+  .fb-divider { display: none; }
+}
+
+/* ---------- Active filter chips ---------- */
+
+.active-filters {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  padding-top: 0.75rem;
+  border-top: 1px solid var(--color-border);
+}
+
+.active-filter-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  padding: 0.25rem 0.55rem;
+  background: transparent;
+  border: 1px solid var(--color-border);
+  color: var(--color-muted);
+  font-family: var(--font-mono);
+  font-size: 0.72em;
+  cursor: pointer;
+  transition: color 0.12s ease, border-color 0.12s ease;
+}
+.active-filter-chip:hover,
+.active-filter-chip:focus-visible {
+  color: var(--color-accent);
+  border-color: var(--color-accent);
+  outline: none;
+}
+.active-filter-chip .afc-label { text-transform: lowercase; }
+
+.active-filter-clear {
+  margin-left: 0.25rem;
+  padding: 0.25rem 0.55rem;
+  background: transparent;
+  border: 0;
+  color: var(--color-muted);
+  font-family: var(--font-mono);
+  font-size: 0.72em;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  cursor: pointer;
+  text-decoration: underline;
+  text-decoration-color: transparent;
+  text-underline-offset: 3px;
+  transition: color 0.12s ease, text-decoration-color 0.12s ease;
+}
+.active-filter-clear:hover,
+.active-filter-clear:focus-visible {
+  color: var(--color-fg);
+  text-decoration-color: currentColor;
+  outline: none;
+}