handzon-core 0.6.1 → 0.7.0

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

package/src/components/mdx/Checkpoint.tsx

@@ -27,12 +27,17 @@ function useRoute() {
 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 { state, recordCheckpoint, removeCheckpoint, markStepComplete, markStepIncomplete } =
+    useProgress();
   const route = useRoute();
   const done = !!state.checkpoints[checkpointId];
 
   function onToggle() {
-    if (done) return;
+    if (done) {
+      removeCheckpoint(checkpointId);
+      if (route) markStepIncomplete(route.tutorial, route.step);
+      return;
+    }
     recordCheckpoint(checkpointId);
     if (route) markStepComplete(route.tutorial, route.step);
   }

package/src/components/ui/Dropdown.tsx

@@ -0,0 +1,91 @@
+import * as Select from "@radix-ui/react-select";
+import { Check, ChevronDown, ChevronUp } from "lucide-react";
+import type { ReactNode } from "react";
+
+export interface DropdownOption<V extends string = string> {
+  value: V;
+  label: string;
+  /** Optional leading glyph rendered before the label inside the item. */
+  icon?: ReactNode;
+}
+
+export interface DropdownProps<V extends string = string> {
+  value: V;
+  onChange: (value: V) => void;
+  options: DropdownOption<V>[];
+  /** Visible label glued to the left of the trigger (uppercase mono chip). */
+  label?: string;
+  /** Optional leading icon rendered inside the trigger before the label. */
+  triggerIcon?: ReactNode;
+  /** aria-label for the trigger when no `label` is shown. */
+  ariaLabel?: string;
+  /** Placeholder shown when `value` doesn't match any option. */
+  placeholder?: string;
+  /** Extra class on the outer wrapper for layout tweaks. */
+  className?: string;
+  id?: string;
+}
+
+/**
+ * Project-wide dropdown. Wraps Radix Select so we never ship the native
+ * browser dropdown UI — those look out-of-place against the brutalist
+ * mono/hard-edge palette and vary wildly across OSes. Every new select
+ * in handzon-core should use this; do not introduce raw `<select>`.
+ */
+export default function Dropdown<V extends string = string>({
+  value,
+  onChange,
+  options,
+  label,
+  triggerIcon,
+  ariaLabel,
+  placeholder,
+  className,
+  id,
+}: DropdownProps<V>) {
+  return (
+    <div className={`hz-dd${className ? ` ${className}` : ""}`}>
+      {label && (
+        <span className="hz-dd-label" id={id ? `${id}-label` : undefined}>
+          {label}
+        </span>
+      )}
+      <Select.Root value={value} onValueChange={(v) => onChange(v as V)}>
+        <Select.Trigger
+          id={id}
+          className="hz-dd-trigger"
+          aria-label={ariaLabel ?? label}
+          aria-labelledby={label && id ? `${id}-label` : undefined}
+        >
+          {triggerIcon && <span className="hz-dd-tricon">{triggerIcon}</span>}
+          <Select.Value placeholder={placeholder ?? "Select…"} />
+          <Select.Icon className="hz-dd-caret">
+            <ChevronDown size={14} aria-hidden="true" />
+          </Select.Icon>
+        </Select.Trigger>
+
+        <Select.Portal>
+          <Select.Content className="hz-dd-content" position="popper" sideOffset={6}>
+            <Select.ScrollUpButton className="hz-dd-scroll">
+              <ChevronUp size={14} aria-hidden="true" />
+            </Select.ScrollUpButton>
+            <Select.Viewport className="hz-dd-viewport">
+              {options.map((opt) => (
+                <Select.Item key={opt.value} value={opt.value} className="hz-dd-item">
+                  {opt.icon && <span className="hz-dd-icon">{opt.icon}</span>}
+                  <Select.ItemText>{opt.label}</Select.ItemText>
+                  <Select.ItemIndicator className="hz-dd-check">
+                    <Check size={14} aria-hidden="true" />
+                  </Select.ItemIndicator>
+                </Select.Item>
+              ))}
+            </Select.Viewport>
+            <Select.ScrollDownButton className="hz-dd-scroll">
+              <ChevronDown size={14} aria-hidden="true" />
+            </Select.ScrollDownButton>
+          </Select.Content>
+        </Select.Portal>
+      </Select.Root>
+    </div>
+  );
+}

package/src/components/ui/MultiSelect.tsx

@@ -0,0 +1,205 @@
+import * as Popover from "@radix-ui/react-popover";
+import { Check, ChevronDown, Search, X } from "lucide-react";
+import { type KeyboardEvent, type ReactNode, useEffect, useMemo, useRef, useState } from "react";
+
+export interface MultiSelectOption {
+  value: string;
+  label: string;
+  count: number;
+}
+
+export interface MultiSelectProps {
+  values: Set<string>;
+  onChange: (next: Set<string>) => void;
+  options: MultiSelectOption[];
+  /** Label chip glued to the left of the trigger (uppercase mono). */
+  label: string;
+  /** Optional icon rendered inside the trigger. */
+  triggerIcon?: ReactNode;
+  /** Adds a "Filter values…" input inside the popover. Use for the
+   *  Topics popover (long lists); skip for Level (only 3 options). */
+  searchable?: boolean;
+  /** Trigger aria-label override (falls back to `label`). */
+  ariaLabel?: string;
+  id?: string;
+}
+
+/**
+ * Project-wide multi-select dropdown. Wraps Radix Popover so we never
+ * ship the browser-native UI and so every dropdown across the app
+ * shares the same visual chrome (mono label chip + hard-edge trigger
+ * + accent-on-focus). Pairs with Dropdown.tsx — that one handles
+ * single-select, this one handles multi.
+ *
+ * Layout: trigger summarises selection count; popover holds the full
+ * list with optional in-popover search, count badges per option, and
+ * a footer "Clear" that empties this facet (doesn't close).
+ *
+ * Keyboard: arrow keys move focus across options (roving tabIndex),
+ * Space toggles, Esc closes. Radix Popover doesn't provide list-nav,
+ * so we implement it explicitly on each row.
+ */
+export default function MultiSelect({
+  values,
+  onChange,
+  options,
+  label,
+  triggerIcon,
+  searchable = false,
+  ariaLabel,
+  id,
+}: MultiSelectProps) {
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const optionRefs = useRef<Array<HTMLDivElement | null>>([]);
+  const [focusIdx, setFocusIdx] = useState(0);
+
+  // Sort by count desc so "weighty" facets bubble up. Stable
+  // alphabetical secondary sort keeps neighbours predictable.
+  const sorted = useMemo(
+    () => [...options].sort((a, b) => b.count - a.count || a.label.localeCompare(b.label)),
+    [options],
+  );
+
+  const filtered = useMemo(() => {
+    if (!query.trim()) return sorted;
+    const q = query.trim().toLowerCase();
+    return sorted.filter(
+      (o) => o.label.toLowerCase().includes(q) || o.value.toLowerCase().includes(q),
+    );
+  }, [sorted, query]);
+
+  // Reset the search field every time the popover closes so the next
+  // open starts clean. Keep focus index in range as `filtered` shrinks.
+  useEffect(() => {
+    if (!open) {
+      setQuery("");
+      setFocusIdx(0);
+    }
+  }, [open]);
+  useEffect(() => {
+    if (focusIdx >= filtered.length) setFocusIdx(Math.max(0, filtered.length - 1));
+  }, [filtered.length, focusIdx]);
+
+  function toggle(value: string) {
+    const next = new Set(values);
+    if (next.has(value)) next.delete(value);
+    else next.add(value);
+    onChange(next);
+  }
+
+  function clear() {
+    if (values.size === 0) return;
+    onChange(new Set());
+  }
+
+  function summary(): string {
+    // The label chip on the left already names the facet ("LEVEL",
+    // "TOPICS"), so the trigger body only carries the *value* — no
+    // repeat. Empty state reads "Any" (meaning "no filter applied").
+    if (values.size === 0) return "Any";
+    if (values.size === 1) {
+      const only = [...values][0];
+      const match = options.find((o) => o.value === only);
+      return match?.label ?? only;
+    }
+    return `${values.size} selected`;
+  }
+
+  function onOptionKey(e: KeyboardEvent<HTMLDivElement>, idx: number) {
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      const next = Math.min(idx + 1, filtered.length - 1);
+      setFocusIdx(next);
+      optionRefs.current[next]?.focus();
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      const next = Math.max(idx - 1, 0);
+      setFocusIdx(next);
+      optionRefs.current[next]?.focus();
+    } else if (e.key === " " || e.key === "Enter") {
+      e.preventDefault();
+      toggle(filtered[idx].value);
+    }
+  }
+
+  return (
+    <Popover.Root open={open} onOpenChange={setOpen}>
+      <Popover.Trigger asChild>
+        <button
+          id={id}
+          type="button"
+          className="hz-dd hz-ms-trigger"
+          aria-label={ariaLabel ?? label}
+          data-active={values.size > 0 || undefined}
+        >
+          <span className="hz-dd-label hz-ms-label">
+            {triggerIcon && <span className="hz-ms-label-icon">{triggerIcon}</span>}
+            <span>{label}</span>
+          </span>
+          <span className="hz-dd-trigger hz-ms-trigger-body">
+            <span className="hz-ms-value" data-empty={values.size === 0 || undefined}>
+              {summary()}
+            </span>
+            <span className="hz-dd-caret">
+              <ChevronDown size={14} aria-hidden="true" />
+            </span>
+          </span>
+        </button>
+      </Popover.Trigger>
+      <Popover.Portal>
+        <Popover.Content className="hz-ms-content" align="start" sideOffset={6}>
+          {searchable && (
+            <label className="hz-ms-search">
+              <Search size={14} aria-hidden="true" />
+              <input
+                type="search"
+                placeholder={`Filter ${label.toLowerCase()}…`}
+                value={query}
+                onChange={(e) => setQuery(e.target.value)}
+                aria-label={`Filter ${label.toLowerCase()}`}
+              />
+            </label>
+          )}
+          <div className="hz-ms-viewport" role="listbox" aria-multiselectable="true">
+            {filtered.length === 0 ? (
+              <div className="hz-ms-empty">No matches.</div>
+            ) : (
+              filtered.map((opt, idx) => {
+                const checked = values.has(opt.value);
+                return (
+                  <div
+                    key={opt.value}
+                    ref={(el) => {
+                      optionRefs.current[idx] = el;
+                    }}
+                    role="option"
+                    aria-selected={checked}
+                    tabIndex={idx === focusIdx ? 0 : -1}
+                    className="hz-ms-option"
+                    data-checked={checked || undefined}
+                    onClick={() => toggle(opt.value)}
+                    onKeyDown={(e) => onOptionKey(e, idx)}
+                  >
+                    <span className="hz-ms-check" aria-hidden="true">
+                      {checked && <Check size={12} />}
+                    </span>
+                    <span className="hz-ms-option-label">{opt.label}</span>
+                    <span className="hz-ms-count">{opt.count}</span>
+                  </div>
+                );
+              })
+            )}
+          </div>
+          {values.size > 0 && (
+            <div className="hz-ms-footer">
+              <button type="button" className="hz-ms-clear" onClick={clear}>
+                <X size={12} aria-hidden="true" /> Clear {label.toLowerCase()}
+              </button>
+            </div>
+          )}
+        </Popover.Content>
+      </Popover.Portal>
+    </Popover.Root>
+  );
+}

package/src/index.ts

@@ -8,48 +8,43 @@
  * and types.
  */
 
+// AI client (browser-side BYOK + streaming chat to handzon-ai).
+export {
+  type ChatMessage,
+  clearLearnerKey,
+  loadLearnerKey,
+  saveLearnerKey,
+  streamChat,
+} from "./lib/ai/client.ts";
+export { type AssistantContext, buildContext } from "./lib/ai/context.ts";
 // Content collection helpers (built on top of astro:content).
 export {
-  parseStepId,
-  getTutorials,
-  getTutorialBySlug,
-  getStepsForTutorial,
   getStep,
+  getStepsForTutorial,
+  getTutorialBySlug,
+  getTutorials,
+  parseStepId,
+  type StepEntry,
   sumDurations,
   type TutorialEntry,
-  type StepEntry,
 } from "./lib/content.ts";
-
 // MDX component map used by .astro pages rendering tutorial content.
 export { mdxComponents } from "./lib/mdx-components.ts";
-
-// Rehype plugin that lets Mermaid code fences round-trip as <pre class="mermaid">.
-export { default as rehypeMermaidPassthrough } from "./lib/rehype-mermaid-passthrough.ts";
-
-// AI client (browser-side BYOK + streaming chat to handzon-ai).
-export {
-  streamChat,
-  loadLearnerKey,
-  saveLearnerKey,
-  clearLearnerKey,
-  type ChatMessage,
-} from "./lib/ai/client.ts";
-
-export { buildContext, type AssistantContext } from "./lib/ai/context.ts";
-
 // Progress store (localStorage + optional server sync).
 export { getStore } from "./lib/progress/local.ts";
-export {
-  useProgress,
-  useProgressAfterMount,
-} from "./lib/progress/useProgress.ts";
 export {
   emptyState,
-  type ProgressState,
-  type StepKey,
   type LastVisitedEntry,
+  type ProgressState,
   type ProgressStore,
+  type StepKey,
 } from "./lib/progress/types.ts";
+export {
+  useProgress,
+  useProgressAfterMount,
+} from "./lib/progress/useProgress.ts";
+// Rehype plugin that lets Mermaid code fences round-trip as <pre class="mermaid">.
+export { default as rehypeMermaidPassthrough } from "./lib/rehype-mermaid-passthrough.ts";
 
 // AI config type (consumers provide concrete values; framework consumes shape).
 export type { AiConfig } from "./types/ai.ts";

package/src/layouts/BaseLayout.astro

@@ -85,7 +85,11 @@ const desc = description ?? tagline;
         <UserMenu />
       </div>
     )}
-    <slot />
+    {/* Wrap the slot in a flex-growing region so the footer hugs the
+        bottom of the viewport even when the page content is short. */}
+    <div class="hz-page">
+      <slot />
+    </div>
     {showFooter && <Footer repoUrl={repoUrl} />}
     <script>
       // Render any <pre class="mermaid"> blocks emitted by rehype-mermaid.
@@ -98,6 +102,25 @@ const desc = description ?? tagline;
     </script>
 
     <style is:global>
+      /* Sticky-footer layout: body is a flex column at viewport height
+       * minimum; the page-content region grows to fill, pushing the
+       * footer to the bottom when content is short. */
+      html, body {
+        min-height: 100dvh;
+      }
+      body {
+        display: flex;
+        flex-direction: column;
+      }
+      .hz-page {
+        flex: 1 0 auto;
+        display: flex;
+        flex-direction: column;
+      }
+      .hz-page > * {
+        flex: 1 0 auto;
+      }
+
       .hz-topbar {
         position: fixed;
         top: 0.75rem;

package/src/lib/progress/remote.ts

@@ -65,6 +65,13 @@ function diffState(prev: ProgressState, next: ProgressState): ProgressEntry[] {
       out.push({ kind: "checkpoint", scope: "global", key: id, value });
     }
   }
+  // Emit deletions so the server tombstones unchecked checkpoints; without
+  // this the next snapshot fetch would resurrect them from the DB.
+  for (const id of Object.keys(prev.checkpoints)) {
+    if (!next.checkpoints[id]) {
+      out.push({ kind: "checkpoint", scope: "global", key: id, value: null });
+    }
+  }
   for (const [k, value] of Object.entries(next.prefs)) {
     if ((prev.prefs as Record<string, unknown>)[k] !== value) {
       out.push({ kind: "pref", scope: "global", key: k, value });
@@ -150,6 +157,7 @@ export function createRemoteStore(): ProgressStore {
           } else if (e.kind === "quiz") {
             merged.quizzes[e.key] = e.value as ProgressState["quizzes"][string];
           } else if (e.kind === "checkpoint") {
+            if (e.value == null) continue;
             merged.checkpoints[e.key] = e.value as ProgressState["checkpoints"][string];
           } else if (e.kind === "pref") {
             (merged.prefs as Record<string, unknown>)[e.key] = e.value;

package/src/lib/progress/useProgress.ts

@@ -8,6 +8,7 @@ interface ProgressApi {
   markStepIncomplete: (tutorial: string, step: string) => void;
   recordQuiz: (questionId: string, chosen: number[], correct: boolean) => void;
   recordCheckpoint: (checkpointId: string) => void;
+  removeCheckpoint: (checkpointId: string) => void;
   setPref: <K extends keyof ProgressState["prefs"]>(
     key: K,
     value: ProgressState["prefs"][K],
@@ -56,6 +57,13 @@ export function useProgress(): ProgressApi {
           ...s,
           checkpoints: { ...s.checkpoints, [checkpointId]: { ts: Date.now() } },
         })),
+      removeCheckpoint: (checkpointId: string) =>
+        store.set((s) => {
+          if (!s.checkpoints[checkpointId]) return s;
+          const next = { ...s.checkpoints };
+          delete next[checkpointId];
+          return { ...s, checkpoints: next };
+        }),
       setPref: <K extends keyof ProgressState["prefs"]>(key: K, value: ProgressState["prefs"][K]) =>
         store.set((s) => ({ ...s, prefs: { ...s.prefs, [key]: value } })),
       setLastVisited: (tutorial: string, step: string) =>