handzon-core 0.6.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handzon-core",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "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/collections.ts

@@ -121,6 +121,11 @@ export function tutorialsSchema({ image }: { image: () => import("astro/zod").Zo
     estimatedDuration: z.string().optional(),
     prerequisites: z.array(z.string()).default([]),
     nextTutorial: z.string().optional(),
+    // TODO(handzon): `cover` and `icon` are accepted by the schema for
+    // forward compatibility, but no page currently renders them
+    // (Home cards, TutorialLanding, OG meta all ignore them). Wire them
+    // up in TutorialCard and BaseLayout's OG tags before promoting
+    // cover art in author-facing docs and skills.
     cover: image().optional(),
     icon: z.union([z.string(), image()]).optional(),
     steps: z.array(z.string()).optional(),

package/src/components/ai/ChatButton.tsx

@@ -1,7 +1,7 @@
 import { Sparkles } from "lucide-react";
 import { useState } from "react";
-import type { AiConfig } from "../../types/ai";
 import type { AssistantContext } from "../../lib/ai/context";
+import type { AiConfig } from "../../types/ai";
 import ChatPanel from "./ChatPanel";
 
 interface Props {

package/src/components/ai/ChatPanel.tsx

@@ -3,9 +3,9 @@ import { KeyRound, Send, Settings, Sparkles, Trash2, X } from "lucide-react";
 import { useEffect, useRef, useState } from "react";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
-import type { AiConfig } from "../../types/ai";
 import { type ChatMessage, clearLearnerKey, loadLearnerKey, streamChat } from "../../lib/ai/client";
 import type { AssistantContext } from "../../lib/ai/context";
+import type { AiConfig } from "../../types/ai";
 import ByokSetup from "./ByokSetup";
 
 interface Props {
@@ -45,6 +45,11 @@ export default function ChatPanel({ open, onOpenChange, config, context }: Props
 
   // Keep the latest message in view as chunks stream in (and on every
   // send / clear). Without this, long responses scroll out of frame.
+  // The deps aren't read inside the effect — they're triggers, so the
+  // effect re-runs when a new chunk arrives or streaming flips. Biome's
+  // exhaustive-deps lint would have us remove them; that would break
+  // the autoscroll. Keep the suppression scoped to this single effect.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: messages + streaming are intentional triggers
   useEffect(() => {
     listRef.current?.scrollTo({ top: listRef.current.scrollHeight });
   }, [messages, streaming]);
@@ -162,8 +167,8 @@ export default function ChatPanel({ open, onOpenChange, config, context }: Props
                 <KeyRound size={22} aria-hidden="true" />
                 <h3>API key required</h3>
                 <p>
-                  {config.name} needs an API key to answer questions. Add one to get started —
-                  it's stored in this browser only.
+                  {config.name} needs an API key to answer questions. Add one to get started — it's
+                  stored in this browser only.
                 </p>
                 <button type="button" onClick={() => setByokOpen(true)}>
                   Set up key
@@ -197,7 +202,7 @@ export default function ChatPanel({ open, onOpenChange, config, context }: Props
                   <div className="chat-msg chat-msg-assistant">
                     <span className="chat-role">{config.name}</span>
                     <div className="chat-content">
-                      <span className="chat-thinking" aria-label="Thinking">
+                      <span className="chat-thinking" role="status" aria-label="Thinking">
                         <span /> <span /> <span />
                       </span>
                     </div>

package/src/components/auth/UserMenu.tsx

@@ -53,7 +53,7 @@ export default function UserMenu() {
         }
         const sess = (await sessRes.json()) as Session | null;
         const csrf = (await csrfRes.json()) as { csrfToken?: string } | null;
-        setSession(sess && sess.user ? sess : null);
+        setSession(sess?.user ? sess : null);
         setCsrfToken(csrf?.csrfToken ?? null);
       } catch {
         if (!cancelled) {
@@ -73,22 +73,31 @@ 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,88 @@
+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 (
+    // biome-ignore lint/a11y/useSemanticElements: <fieldset> requires <legend> and carries form-control semantics; this row groups filter-removal buttons.
+    <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,48 @@
-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 +50,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 +66,10 @@ 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 +77,124 @@ 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/Pagination.tsx

@@ -19,9 +19,7 @@ interface Props {
  */
 function applyPagination(page: number, pageSize: number): number {
   const visibleByFilter = Array.from(
-    document.querySelectorAll<HTMLElement>(
-      "[data-search]:not([data-filter-hidden])",
-    ),
+    document.querySelectorAll<HTMLElement>("[data-search]:not([data-filter-hidden])"),
   );
   const start = (page - 1) * pageSize;
   const end = start + pageSize;

package/src/components/home/ResumeRail.tsx

@@ -44,7 +44,9 @@ export default function ResumeRail({ tutorials }: Props) {
       <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>
+      <span className="rr-arrow" aria-hidden="true">
+        →
+      </span>
     </a>
   );
 }

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"
+    />
+  );
+}