handzon-core 0.6.1 → 0.6.2

package/src/components/ui/Dropdown.tsx

@@ -0,0 +1,99 @@
+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,219 @@
+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/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/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>