handzon-core 0.6.0 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handzon-core",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Core framework for Handzon — layouts, components, content + AI libs, and server runtime (handlers, DB, auth, migration runner) consumed by Handzon scaffolds.",
   "publishConfig": {
     "access": "public"
@@ -46,6 +46,8 @@
     "@fontsource-variable/geist": "^5.2.9",
     "@fontsource-variable/geist-mono": "^5.2.8",
     "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-popover": "^1.1.15",
+    "@radix-ui/react-select": "^2.1.6",
     "auth-astro": "^4.2.0",
     "cookie": "^1.0.2",
     "diff": "^9.0.0",

package/src/components/auth/UserMenu.tsx

@@ -73,22 +73,29 @@ export default function UserMenu() {
   const user = session?.user;
   const callbackUrl = typeof window !== "undefined" ? window.location.href : "/";
 
+  // Compact label for the topbar: first word of `name`, falling back
+  // to the local part of `email`, falling back to a generic. Full name
+  // / email stays in the `alt` text and `title` for accessibility +
+  // long-form context.
+  const fullLabel = user?.name ?? user?.email ?? "Signed in";
+  const displayName = user
+    ? (user.name ? user.name.trim().split(/\s+/)[0] : null) ??
+      (user.email ? user.email.split("@")[0] : null) ??
+      "Signed in"
+    : "";
+
   return (
     <div className="user-menu">
       {user ? (
         <>
           {user.image ? (
-            <img
-              className="um-avatar"
-              src={user.image}
-              alt={user.name ?? user.email ?? "Signed in"}
-            />
+            <img className="um-avatar" src={user.image} alt={fullLabel} />
           ) : (
             <span className="um-avatar um-avatar-fallback" aria-hidden="true">
-              {(user.name ?? user.email ?? "?").trim().charAt(0).toUpperCase()}
+              {fullLabel.trim().charAt(0).toUpperCase()}
             </span>
           )}
-          <span className="um-name">{user.name ?? user.email ?? "Signed in"}</span>
+          <span className="um-name" title={fullLabel}>{displayName}</span>
           <form method="post" action="/api/auth/signout">
             <input type="hidden" name="csrfToken" value={csrfToken} />
             <input type="hidden" name="callbackUrl" value={callbackUrl} />

package/src/components/home/ActiveFilterChips.tsx

@@ -0,0 +1,91 @@
+import { X } from "lucide-react";
+import type { KeyboardEvent } from "react";
+
+interface Props {
+  q: string;
+  levels: Set<string>;
+  tags: Set<string>;
+  onClearQ: () => void;
+  onRemoveLevel: (level: string) => void;
+  onRemoveTag: (tag: string) => void;
+  onClearAll: () => void;
+}
+
+/**
+ * Active-filter chip row. Pure presentation — the parent FilterBar
+ * owns state mutations and URL writes. Shown only when the parent
+ * has determined at least one filter is active.
+ *
+ * Each chip is a button. Clicking removes the facet value.
+ * Backspace/Delete on a focused chip removes it via keyboard.
+ *
+ * The trailing "Clear all" sits at the end and resets everything
+ * (search + levels + tags). This is the only "clear" affordance now;
+ * the in-toolbar Clear button was removed.
+ */
+export default function ActiveFilterChips({
+  q,
+  levels,
+  tags,
+  onClearQ,
+  onRemoveLevel,
+  onRemoveTag,
+  onClearAll,
+}: Props) {
+  function chipKey(e: KeyboardEvent<HTMLButtonElement>, remove: () => void) {
+    if (e.key === "Backspace" || e.key === "Delete") {
+      e.preventDefault();
+      remove();
+    }
+  }
+
+  return (
+    <div className="active-filters" role="group" aria-label="Active filters">
+      {q && (
+        <button
+          type="button"
+          className="active-filter-chip"
+          aria-label={`Remove search: ${q}`}
+          onClick={onClearQ}
+          onKeyDown={(e) => chipKey(e, onClearQ)}
+        >
+          <span className="afc-label">search: {q}</span>
+          <X size={12} aria-hidden="true" />
+        </button>
+      )}
+      {[...levels].sort().map((level) => (
+        <button
+          key={`l:${level}`}
+          type="button"
+          className="active-filter-chip"
+          aria-label={`Remove level: ${level}`}
+          onClick={() => onRemoveLevel(level)}
+          onKeyDown={(e) => chipKey(e, () => onRemoveLevel(level))}
+        >
+          <span className="afc-label">{level}</span>
+          <X size={12} aria-hidden="true" />
+        </button>
+      ))}
+      {[...tags].sort().map((tag) => (
+        <button
+          key={`t:${tag}`}
+          type="button"
+          className="active-filter-chip"
+          aria-label={`Remove topic: ${tag}`}
+          onClick={() => onRemoveTag(tag)}
+          onKeyDown={(e) => chipKey(e, () => onRemoveTag(tag))}
+        >
+          <span className="afc-label">#{tag}</span>
+          <X size={12} aria-hidden="true" />
+        </button>
+      ))}
+      <button
+        type="button"
+        className="active-filter-clear"
+        onClick={onClearAll}
+      >
+        Clear all
+      </button>
+    </div>
+  );
+}

package/src/components/home/FilterBar.tsx

@@ -1,27 +1,43 @@
-import { Flame, Search, X } from "lucide-react";
+import { GraduationCap, Hash, Search } from "lucide-react";
 import { useEffect, useState } from "react";
+import MultiSelect, { type MultiSelectOption } from "../ui/MultiSelect.tsx";
+import ActiveFilterChips from "./ActiveFilterChips.tsx";
+import SortBar from "./SortBar.tsx";
 
 interface Props {
   difficulties: string[];
   tags: string[];
+  /** Hit counts per difficulty value, server-computed. */
+  difficultyCounts: Record<string, number>;
+  /** Hit counts per tag, server-computed. */
+  tagCounts: Record<string, number>;
 }
 
 interface FilterState {
   q: string;
-  difficulty: string;
-  tag: string;
-  /** "" = curated (numeric-prefix) order; "popular" = by data-popularity desc. */
-  sort: string;
+  levels: Set<string>;
+  tags: Set<string>;
+}
+
+function parseCsv(value: string | null): Set<string> {
+  if (!value) return new Set();
+  return new Set(value.split(",").map((s) => s.trim()).filter(Boolean));
 }
 
 function readUrlState(): FilterState {
-  if (typeof window === "undefined") return { q: "", difficulty: "", tag: "", sort: "" };
+  if (typeof window === "undefined") {
+    return { q: "", levels: new Set(), tags: new Set() };
+  }
   const url = new URL(window.location.href);
+  const levels = url.searchParams.get("level")
+    ? parseCsv(url.searchParams.get("level"))
+    : // Legacy single-value shape; honor on read so shared links keep
+      // working. The next interaction rewrites to ?level=.
+      parseCsv(url.searchParams.get("difficulty"));
   return {
     q: url.searchParams.get("q") ?? "",
-    difficulty: url.searchParams.get("difficulty") ?? "",
-    tag: url.searchParams.get("tag") ?? "",
-    sort: url.searchParams.get("sort") ?? "",
+    levels,
+    tags: parseCsv(url.searchParams.get("tag")),
   };
 }
 
@@ -29,12 +45,13 @@ 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);
+  if (state.levels.size > 0) url.searchParams.set("level", [...state.levels].join(","));
+  else url.searchParams.delete("level");
+  if (state.tags.size > 0) url.searchParams.set("tag", [...state.tags].join(","));
   else url.searchParams.delete("tag");
-  if (state.sort) url.searchParams.set("sort", state.sort);
-  else url.searchParams.delete("sort");
+  // Always strip the legacy key so an upgraded URL doesn't carry both
+  // shapes. First user interaction "migrates" the link.
+  url.searchParams.delete("difficulty");
   window.history.replaceState({}, "", url.toString());
 }
 
@@ -44,9 +61,12 @@ function applyFilters(state: FilterState) {
   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;
+    const matchesLevel =
+      state.levels.size === 0 || state.levels.has(card.dataset.difficulty ?? "");
+    const cardTags = (card.dataset.tags ?? "").split(",");
+    const matchesTag =
+      state.tags.size === 0 || cardTags.some((t) => state.tags.has(t));
+    const show = matchesQ && matchesLevel && matchesTag;
     if (show) {
       card.removeAttribute("data-filter-hidden");
       visible += 1;
@@ -54,98 +74,129 @@ function applyFilters(state: FilterState) {
       card.setAttribute("data-filter-hidden", "");
     }
   });
+  // Empty state element controls its own visibility; we just set it.
+  // The Home.astro inline empty-state is shown when visible === 0.
   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.
+  // Results status line. Read total from rendered card count (server
+  // SSR'd them; localStorage / pagination don't change cards.length).
+  const status = document.querySelector<HTMLElement>("[data-results-status]");
+  if (status) {
+    const total = cards.length;
+    if (total === 0) {
+      status.textContent = "";
+    } else if (visible === total) {
+      status.textContent = `Showing all ${total} tutorial${total === 1 ? "" : "s"}`;
+    } else {
+      status.textContent = `Showing ${visible} of ${total} tutorial${total === 1 ? "" : "s"}`;
+    }
+  }
+  // Fire once per state transition so Pagination resets to page 1.
   window.dispatchEvent(new CustomEvent("hz:filter-changed"));
 }
 
-export default function FilterBar({ difficulties, tags }: Props) {
+export default function FilterBar({
+  difficulties,
+  tags,
+  difficultyCounts,
+  tagCounts,
+}: 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 setQ(q: string) {
+    setState((prev) => ({ ...prev, q }));
   }
-
-  function clear() {
-    setState({ q: "", difficulty: "", tag: "", sort: "" });
+  function setLevels(levels: Set<string>) {
+    setState((prev) => ({ ...prev, levels }));
+  }
+  function setTags(next: Set<string>) {
+    setState((prev) => ({ ...prev, tags: next }));
   }
+  function removeLevel(level: string) {
+    setState((prev) => {
+      const next = new Set(prev.levels);
+      next.delete(level);
+      return { ...prev, levels: next };
+    });
+  }
+  function removeTag(tag: string) {
+    setState((prev) => {
+      const next = new Set(prev.tags);
+      next.delete(tag);
+      return { ...prev, tags: next };
+    });
+  }
+  function clearAll() {
+    setState({ q: "", levels: new Set(), tags: new Set() });
+  }
+
+  const levelOpts: MultiSelectOption[] = difficulties.map((d) => ({
+    value: d,
+    label: d,
+    count: difficultyCounts[d] ?? 0,
+  }));
+  const tagOpts: MultiSelectOption[] = tags.map((t) => ({
+    value: t,
+    label: `#${t}`,
+    count: tagCounts[t] ?? 0,
+  }));
 
-  const hasFilters = state.q || state.difficulty || state.tag || state.sort;
+  const hasActive = state.q.length > 0 || state.levels.size > 0 || state.tags.size > 0;
 
   return (
     <div className="filterbar">
-      {/* Row 1: search takes the lion's share + level + clear */}
-      <div className="fb-row fb-row-primary">
+      <div className="fb-toolbar">
         <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)}
+            onChange={(e) => setQ(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>
+        <MultiSelect
+          id="hz-level"
+          label="Level"
+          values={state.levels}
+          onChange={setLevels}
+          options={levelOpts}
+          triggerIcon={<GraduationCap size={14} aria-hidden="true" />}
+        />
 
-        <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>
+        <MultiSelect
+          id="hz-topics"
+          label="Topics"
+          values={state.tags}
+          onChange={setTags}
+          options={tagOpts}
+          searchable
+          triggerIcon={<Hash size={14} aria-hidden="true" />}
+        />
 
-        {hasFilters && (
-          <button type="button" className="clear" onClick={clear}>
-            <X size={14} aria-hidden="true" /> Clear
-          </button>
-        )}
+        <span className="fb-divider" aria-hidden="true" />
+        <div className="fb-sort-slot">
+          <SortBar />
+        </div>
       </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>
+      {hasActive && (
+        <ActiveFilterChips
+          q={state.q}
+          levels={state.levels}
+          tags={state.tags}
+          onClearQ={() => setQ("")}
+          onRemoveLevel={removeLevel}
+          onRemoveTag={removeTag}
+          onClearAll={clearAll}
+        />
       )}
     </div>
   );

package/src/components/home/SortBar.tsx

@@ -0,0 +1,65 @@
+import { ArrowUpDown } from "lucide-react";
+import { useEffect, useState } from "react";
+import Dropdown, { type DropdownOption } from "../ui/Dropdown.tsx";
+
+/**
+ * Sort dropdown for the homepage tutorial grid. Lives above the grid
+ * (not inside the filterbar) so the UI affordance signals "order"
+ * rather than "filter".
+ *
+ * URL-driven via `?sort=`. Internally we use the sentinel "default"
+ * because Radix Select forbids "" as an item value; the URL still
+ * uses an absent param to mean "curated default order".
+ * Emits `hz:sort-changed` so the inline script on Home.astro that
+ * rewrites CSS `order` on each card re-runs without React coupling.
+ */
+type SortValue = "default" | "popular";
+
+const OPTIONS: DropdownOption<SortValue>[] = [
+  { value: "default", label: "Default" },
+  { value: "popular", label: "Most popular" },
+];
+
+function readSortFromUrl(): SortValue {
+  if (typeof window === "undefined") return "default";
+  const v = new URL(window.location.href).searchParams.get("sort") ?? "";
+  return v === "popular" ? "popular" : "default";
+}
+
+function writeSortToUrl(value: SortValue) {
+  const url = new URL(window.location.href);
+  if (value === "popular") url.searchParams.set("sort", "popular");
+  else url.searchParams.delete("sort");
+  window.history.replaceState({}, "", url.toString());
+}
+
+export default function SortBar() {
+  const [sort, setSort] = useState<SortValue>("default");
+
+  // Read once on mount (client-only) so SSR doesn't try to touch
+  // `window`. After the initial sync, the dropdown owns the URL.
+  useEffect(() => {
+    setSort(readSortFromUrl());
+  }, []);
+
+  useEffect(() => {
+    writeSortToUrl(sort);
+    // Translate the internal sentinel back to "" on the wire so the
+    // existing Home.astro inline reorder script (which checks for the
+    // "popular" string) keeps working without changes.
+    const wire = sort === "popular" ? "popular" : "";
+    window.dispatchEvent(new CustomEvent("hz:sort-changed", { detail: { sort: wire } }));
+  }, [sort]);
+
+  return (
+    <Dropdown<SortValue>
+      id="hz-sort"
+      value={sort}
+      onChange={setSort}
+      options={OPTIONS}
+      label="Sort"
+      triggerIcon={<ArrowUpDown size={14} aria-hidden="true" />}
+      ariaLabel="Sort tutorials"
+    />
+  );
+}

package/src/components/home/TutorialCard.astro

@@ -4,8 +4,14 @@ import type { TutorialEntry } from "../../lib/content";
 interface Props {
   tutorial: TutorialEntry;
   duration?: string;
+  /** Total number of steps in this tutorial. Used as the denominator
+   *  for the per-card progress bar — has to come from the server-side
+   *  content collection because localStorage only holds states for the
+   *  steps the user has visited (so a fresh learner who completed 1 of
+   *  4 steps would otherwise see 1/1). */
+  stepCount: number;
 }
-const { tutorial, duration } = Astro.props;
+const { tutorial, duration, stepCount } = Astro.props;
 const data = tutorial.data;
 const slug = tutorial.id;
 ---
@@ -42,6 +48,11 @@ const slug = tutorial.id;
             {duration}
           </span>
         )}
+        <span
+          class="card-progress"
+          data-tutorial-slug={slug}
+          data-step-count={stepCount}
+        ></span>
       </div>
       {data.tags.length > 0 && (
         <div class="tags">
@@ -53,7 +64,6 @@ const slug = tutorial.id;
         data-tutorial-stats-slug={slug}
         aria-hidden="true"
       ></div>
-      <div class="card-progress" data-tutorial-slug={slug}></div>
     </div>
   </a>
 </article>
@@ -83,14 +93,16 @@ const slug = tutorial.id;
     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. */
+  /* Metadata row: difficulty + duration with a divider beneath it.
+   * `margin-top: auto` pins this row (and everything below it — tags,
+   * stats, progress) to the bottom of the card so all cards in the
+   * grid share the same bottom alignment regardless of how short the
+   * description is. */
   .badges {
     display: flex;
     gap: 0.4rem;
-    margin-top: 0.85rem;
+    margin-top: auto;
+    padding-top: 0.85rem;
     padding-bottom: 0.85rem;
     border-bottom: 1px solid var(--color-border);
     flex-wrap: wrap;
@@ -159,7 +171,44 @@ const slug = tutorial.id;
     color: var(--color-muted);
   }
 
-  .card-progress:not(:empty) { padding-top: 0.5rem; }
+  /* Per-card completion ring, hydrated by the home-page script.
+   * Sits inside the `.badges` row, pushed to the right edge so it
+   * lines up with the level + duration chips on the same baseline. */
+  .card-progress {
+    margin-left: auto;
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    font-family: var(--font-mono);
+    font-size: 0.68em;
+    color: var(--color-muted);
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+  }
+  .card-progress:empty { display: none; }
+  /* The ring + label live inside `.card-progress` but are injected
+   * via innerHTML at runtime, so Astro's scope hash doesn't apply to
+   * them. Use :global() so the rules still match. */
+  .card-progress :global(.ring) {
+    /* Start the fill at 12 o'clock. */
+    transform: rotate(-90deg);
+    flex-shrink: 0;
+  }
+  .card-progress :global(.ring-track) {
+    fill: none;
+    stroke: var(--color-border);
+    stroke-width: 2.5;
+  }
+  .card-progress :global(.ring-fill) {
+    fill: none;
+    stroke: var(--color-accent);
+    stroke-width: 2.5;
+    stroke-linecap: round;
+    transition: stroke-dashoffset 0.3s ease;
+  }
+  .card-progress :global(.ring-label) {
+    color: var(--color-accent);
+  }
 
   /* Cross-learner popularity, hydrated from /api/tutorials/stats.
    * Hidden until the script populates content so the card height