@grove-dev/astro 0.1.5 → 0.2.2

package/src/layouts/Header.astro

@@ -0,0 +1,159 @@
+---
+/**
+ * Header — sticky brand + nav + theme toggle.
+ *
+ * Generic: takes a `site` prop with brand + nav. No `siteConfig`
+ * import — consumers compose the props from their own config.
+ *
+ * Optional `submit` button renders a "Submit app" / "Submit project"
+ * call-to-action on the right side of the nav. Set `submitHref` /
+ * `submitLabel` to enable, leave them undefined for a clean header.
+ *
+ * Optional `repoUrl` adds a "View source" GitHub button. Set
+ * `repoLabel` to change the visible text.
+ */
+
+import ThemeToggle from "./ThemeToggle.astro";
+
+interface NavItem {
+  label: string;
+  href: string;
+}
+
+interface Site {
+  name: string;
+  tagline?: string;
+  nav: NavItem[];
+  description?: string;
+  repoUrl?: string;
+}
+
+interface Props {
+  site: Site;
+  /** Submit button label, e.g. "Submit app". Omit to hide. */
+  submitLabel?: string;
+  /** Submit button href, e.g. "/submit". Omit to hide. */
+  submitHref?: string;
+  /** GitHub button label, e.g. "View source". */
+  repoLabel?: string;
+  /** Extra class for the outer header element. */
+  class?: string;
+}
+
+const {
+  site,
+  submitLabel,
+  submitHref,
+  repoLabel = "Star",
+  class: className = "",
+} = Astro.props;
+---
+
+<header
+  class:list={[
+    "sticky top-0 z-50 border-b border-ink-200 bg-white/85 backdrop-blur dark:border-ink-800 dark:bg-ink-950/85",
+    className,
+  ]}
+>
+  <div
+    class="mx-auto flex max-w-wide items-center gap-6 px-5 py-3 sm:px-7"
+    style="max-width: var(--container-wide, 1400px);"
+  >
+    <a
+      href="/"
+      class="inline-flex items-center gap-2 text-[0.95rem] font-semibold tracking-tight text-ink-900 dark:text-ink-100"
+    >
+      <span
+        aria-hidden="true"
+        class="inline-block h-[18px] w-[18px] rounded bg-ink-900 dark:bg-ink-100"
+      ></span>
+      <span>{site.name}</span>
+    </a>
+
+    <nav class="hidden flex-1 md:block" aria-label="Primary">
+      <ul class="m-0 flex list-none gap-5 p-0">
+        {site.nav.map((item) => (
+          <li>
+            <a
+              href={item.href}
+              class="text-[0.875rem] font-medium text-ink-500 transition-colors hover:text-ink-900 dark:text-ink-400 dark:hover:text-ink-100"
+            >
+              {item.label}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+
+    <div class="ml-auto flex items-center gap-2">
+      {submitHref && (
+        <a
+          href={submitHref}
+          class="grove-btn grove-btn-outline"
+        >
+          <svg
+            viewBox="0 0 16 16"
+            width="13"
+            height="13"
+            aria-hidden="true"
+            fill="currentColor"
+          >
+            <path d="M7.75 2a.75.75 0 0 1 .75.75v3.5h3.5a.75.75 0 0 1 0 1.5h-3.5v3.5a.75.75 0 0 1-1.5 0v-3.5h-3.5a.75.75 0 0 1 0-1.5h3.5v-3.5A.75.75 0 0 1 7.75 2Z"></path>
+          </svg>
+          <span>{submitLabel ?? "Submit"}</span>
+        </a>
+      )}
+
+      {site.repoUrl && (
+        <a
+          href={site.repoUrl}
+          target="_blank"
+          rel="noopener noreferrer"
+          aria-label={repoLabel}
+          title={repoLabel}
+          class="grove-btn grove-btn-outline"
+        >
+          <svg
+            viewBox="0 0 16 16"
+            width="16"
+            height="16"
+            aria-hidden="true"
+            fill="currentColor"
+          >
+            <path
+              d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38v-1.33c-2.22.48-2.69-1.07-2.69-1.07-.36-.92-.89-1.17-.89-1.17-.73-.5.05-.49.05-.49.8.06 1.23.83 1.23.83.72 1.22 1.87.87 2.33.67.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48v2.19c0 .21.15.46.55.38A8 8 0 0 0 8 0Z"
+            ></path>
+          </svg>
+          <span>{repoLabel}</span>
+        </a>
+      )}
+
+      <ThemeToggle />
+    </div>
+  </div>
+</header>
+
+<script>
+  // Smooth-scroll for in-page anchor links (Header nav + Hero CTA).
+  // Works on any <a href="#…"> that points to an existing element on
+  // the current page. External links (e.g. /about, /projects?…) are
+  // skipped because they don't start with "#". Modifier-clicks
+  // (Cmd/Ctrl/Shift/middle) let the browser handle the anchor
+  // normally so users can open the same section in a new tab.
+  document.addEventListener("click", (e) => {
+    if (e.defaultPrevented) return;
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+    if (e.button !== 0) return;
+    const link = (e.target as HTMLElement).closest<HTMLAnchorElement>(
+      'a[href^="#"]',
+    );
+    if (!link) return;
+    const id = link.getAttribute("href")!;
+    if (id.length <= 1) return;
+    const target = document.querySelector(id);
+    if (!target) return;
+    e.preventDefault();
+    target.scrollIntoView({ behavior: "smooth", block: "start" });
+    history.replaceState(null, "", id);
+  });
+</script>

package/src/layouts/SectionHeader.astro

@@ -0,0 +1,58 @@
+---
+/**
+ * SectionHeader — eyebrow + title + description, used to title
+ * every section on the home page. Optionally centered (good for
+ * "Why this exists" and friends).
+ */
+
+interface Props {
+  eyebrow?: string;
+  title: string;
+  description?: string;
+  align?: "left" | "center";
+  /** 2 (default) for top-level sections, 3 for nested ones. */
+  level?: 2 | 3;
+  /** Extra class for the outer header element. */
+  class?: string;
+}
+
+const {
+  eyebrow,
+  title,
+  description,
+  align = "left",
+  level = 2,
+  class: className = "",
+} = Astro.props;
+const Heading = `h${level}` as "h2" | "h3";
+---
+
+<header
+  class:list={[
+    "mb-6 flex flex-col gap-2",
+    align === "center" ? "items-center text-center" : "",
+    className,
+  ]}
+>
+  {eyebrow && (
+    <span class="text-2xs font-medium uppercase tracking-wider text-ink-500 dark:text-ink-400">
+      {eyebrow}
+    </span>
+  )}
+  <div class="flex flex-wrap items-end justify-between gap-3">
+    <Heading class="m-0 text-[1.5rem] sm:text-[1.625rem] font-semibold tracking-tight text-ink-900 dark:text-ink-100">
+      {title}
+    </Heading>
+    <slot name="actions" />
+  </div>
+  {description && (
+    <p
+      class:list={[
+        "m-0 text-[0.9375rem] leading-relaxed text-ink-500 dark:text-ink-400",
+        align === "center" ? "max-w-2xl" : "max-w-[56ch]",
+      ]}
+    >
+      {description}
+    </p>
+  )}
+</header>

package/{templates/default/src/components/layout → src/layouts}/Seo.astro

@@ -1,36 +1,44 @@
 ---
-import { siteConfig } from "../../data/config";
-// SPDX-License-Identifier: MIT
-
 /**
- * Per-page SEO: <title>, description, canonical, Open Graph, Twitter Card,
- * and JSON-LD structured data. Designed to be used inside <head> by the
- * BaseLayout. Pages pass the rich props they care about; everything else
- * has a sensible default derived from the site config and the Astro URL.
+ * Seo — per-page <head> content: title, description, canonical,
+ * Open Graph, Twitter Card, and JSON-LD structured data. Designed
+ * to be used inside the <head> slot of BaseLayout. Pages pass the
+ * rich props they care about; everything else has a sensible default
+ * derived from `site` and the Astro URL.
  *
  * Renders:
  *   - <title>, meta description, canonical link
  *   - Open Graph (og:*) for Facebook, LinkedIn, Discord, Slack, etc.
  *   - Twitter Card (twitter:*) for X / Twitter
  *   - JSON-LD WebSite + Organization on every page
- *   - JSON-LD SoftwareSourceCode (or custom) when `jsonLd` is provided
- *     (e.g. on /apps/[slug] for the per-app structured data)
+ *   - JSON-LD custom payload (e.g. SoftwareSourceCode) when `jsonLd`
+ *     is provided.
  *
- * Noindex is opt-in via the `noindex` prop. By default everything is
- * indexable; the only noindex target today is the thin /submit wrapper.
+ * Noindex is opt-in via the `noindex` prop. By default everything
+ * is indexable.
  */
 
+interface SiteRef {
+  name: string;
+  description?: string;
+  url?: string;
+  repoUrl?: string;
+  searchPath?: string;
+}
+
 interface Props {
   title: string;
   description: string;
-  /** Open Graph / Twitter image. Default: /og-image.svg. Should be absolute or root-relative. */
+  /** Open Graph / Twitter image. Default: /og-image.svg. */
   image?: string;
-  /** og:type. Default: "website". Use "article" for blog posts / changelog. */
+  /** og:type. Default: "website". */
   type?: "website" | "article" | "profile";
   /** Set true to add noindex,nofollow. */
   noindex?: boolean;
-  /** Extra JSON-LD payload (object) — typically SoftwareSourceCode on app pages. */
+  /** Extra JSON-LD payload (object) — typically SoftwareSourceCode. */
   jsonLd?: Record<string, unknown> | Record<string, unknown>[];
+  /** Site identity (name, description, url, repoUrl). Required. */
+  site: SiteRef;
 }
 
 const {
@@ -40,45 +48,53 @@ const {
   type = "website",
   noindex = false,
   jsonLd,
+  site,
 } = Astro.props;
 
-const site = Astro.site ?? new URL("https://open-apps.dev");
-const canonical = new URL(Astro.url.pathname, site).toString();
-const ogImage = new URL(image, site).toString();
+const siteUrl = site.url
+  ? new URL(site.url)
+  : (Astro.site ?? new URL("https://grove.dev"));
+const canonical = new URL(Astro.url.pathname, siteUrl).toString();
+const ogImage = new URL(image, siteUrl).toString();
 
-// Truncate description for OG/Twitter where longer is worse (160–200 chars).
+// Truncate description for OG/Twitter where longer is worse (160-200 chars).
 function truncate(s: string, max: number): string {
   if (s.length <= max) return s;
   return s.slice(0, max - 1).trimEnd() + "\u2026";
 }
 const shortDescription = truncate(description, 200);
+const siteDescription =
+  site.description ??
+  "A growing community knowledge site powered by Grove.";
 
-// WebSite + Organization JSON-LD. These are site-wide identity signals
-// that should appear on every page (Google uses them for site links
-// and the knowledge panel).
-const websiteLd = {
+// JSON-LD: site-wide identity. Google uses these for site links
+// and the knowledge panel.
+const searchPath = site.searchPath ?? "/projects";
+const websiteLd: Record<string, unknown> = {
   "@context": "https://schema.org",
   "@type": "WebSite",
-  name: `${siteConfig.name}`,
-  description:
-    "A curated, self-refreshing directory of real open-source application codebases.",
-  url: site.toString().replace(/\/$/, ""),
+  name: site.name,
+  description: siteDescription,
+  url: siteUrl.toString().replace(/\/$/, ""),
   inLanguage: "en",
   potentialAction: {
     "@type": "SearchAction",
-    target: `${site.toString().replace(/\/$/, "")}/apps?q={search_term_string}`,
+    target: `${siteUrl.toString().replace(/\/$/, "")}${searchPath}?q={search_term_string}`,
     "query-input": "required name=search_term_string",
   },
 };
 
-const organizationLd = {
+const organizationLd: Record<string, unknown> = {
   "@context": "https://schema.org",
   "@type": "Organization",
-  name: `${siteConfig.name}`,
-  url: site.toString().replace(/\/$/, ""),
-  logo: new URL("/og-image.svg", site).toString(),
-  sameAs: ["https://github.com/tortuvshin/open-apps"],
+  name: site.name,
+  url: siteUrl.toString().replace(/\/$/, ""),
+  logo: new URL("/og-image.svg", siteUrl).toString(),
 };
+
+if (site.repoUrl) {
+  organizationLd.sameAs = [site.repoUrl];
+}
 ---
 
 <!-- Primary meta -->
@@ -95,8 +111,8 @@ const organizationLd = {
 <meta property="og:image" content={ogImage} />
 <meta property="og:image:width" content="1200" />
 <meta property="og:image:height" content="630" />
-<meta property="og:image:alt" content="{siteConfig.name} — a directory of real open-source apps" />
-<meta property="og:site_name" content="{siteConfig.name}" />
+<meta property="og:image:alt" content={`${site.name} — ${siteDescription}`} />
+<meta property="og:site_name" content={site.name} />
 <meta property="og:locale" content="en" />
 
 <!-- Twitter Card -->
@@ -104,13 +120,21 @@ const organizationLd = {
 <meta name="twitter:title" content={title} />
 <meta name="twitter:description" content={shortDescription} />
 <meta name="twitter:image" content={ogImage} />
-<meta name="twitter:image:alt" content="{siteConfig.name} — a directory of real open-source apps" />
+<meta name="twitter:image:alt" content={`${site.name} — ${siteDescription}`} />
 
 <!-- JSON-LD: site-wide identity -->
-<script is:inline type="application/ld+json" set:html={JSON.stringify(websiteLd)} />
-<script is:inline type="application/ld+json" set:html={JSON.stringify(organizationLd)} />
+<script
+  is:inline
+  type="application/ld+json"
+  set:html={JSON.stringify(websiteLd)}
+></script>
+<script
+  is:inline
+  type="application/ld+json"
+  set:html={JSON.stringify(organizationLd)}
+></script>
 
-<!-- JSON-LD: per-page (SoftwareSourceCode for /apps/[slug], etc.) -->
+<!-- JSON-LD: per-page (SoftwareSourceCode for [slug], etc.) -->
 {jsonLd && (
   <script
     is:inline

package/src/layouts/ThemeToggle.astro

@@ -0,0 +1,110 @@
+---
+/**
+ * ThemeToggle — a three-position theme switcher (light / dark / system).
+ *
+ * State is persisted in `localStorage` under the key "grove-theme"
+ * (matching `STORAGE_KEY` in `BaseLayout.astro`'s THEME_INIT script).
+ *
+ * The actual `<html class="dark">` toggle happens in the inline
+ * THEME_INIT script in BaseLayout — that script runs before paint
+ * so the user never sees a flash of the wrong theme.
+ *
+ * This button just rotates the stored mode and dispatches a
+ * `theme:set` event that the THEME_INIT listener picks up.
+ */
+
+interface Props {
+  class?: string;
+}
+
+const { class: className = "" } = Astro.props;
+---
+
+<button
+  type="button"
+  data-theme-toggle
+  aria-label="Toggle theme"
+  title="Toggle theme"
+  class:list={[
+    "relative inline-flex h-8 w-8 items-center justify-center rounded-md border border-ink-200 bg-white text-ink-700 transition-colors hover:border-ink-300 hover:bg-ink-50 dark:border-ink-800 dark:bg-ink-950 dark:text-ink-200 dark:hover:border-ink-700 dark:hover:bg-ink-900/40",
+    className,
+  ]}
+>
+  {/* Sun — shown in dark mode (click to go light) */}
+  <svg
+    class="hidden h-4 w-4 dark:block"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="1.8"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    aria-hidden="true"
+  >
+    <circle cx="12" cy="12" r="4"></circle>
+    <path d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M4.93 19.07l1.41-1.41M17.66 6.34l1.41-1.41"></path>
+  </svg>
+  {/* Moon — shown in light mode (click to go dark) */}
+  <svg
+    class="block h-4 w-4 dark:hidden"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="1.8"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    aria-hidden="true"
+  >
+    <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79Z"></path>
+  </svg>
+</button>
+
+<script>
+  // The toggle button simply rotates between the three modes on
+  // click. The actual class application lives in the page-level
+  // THEME_INIT script so behaviour stays consistent.
+  const STORAGE_KEY = "grove-theme";
+  type Mode = "light" | "dark" | "system";
+
+  function currentMode(): Mode {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY);
+      return stored === "light" || stored === "dark" || stored === "system"
+        ? stored
+        : "system";
+    } catch {
+      return "system";
+    }
+  }
+
+  function rotate(): Mode {
+    const order: Mode[] = ["light", "dark", "system"];
+    const cur = currentMode();
+    const next = order[(order.indexOf(cur) + 1) % order.length];
+    try {
+      localStorage.setItem(STORAGE_KEY, next);
+    } catch {
+      // localStorage may be blocked (private mode, etc.) — we still
+      // dispatch the event so the UI updates for the current page.
+    }
+    // Notify the page-level listener (THEME_INIT).
+    window.dispatchEvent(new CustomEvent("theme:set", { detail: next }));
+    return next;
+  }
+
+  function updateLabel(btn: HTMLButtonElement) {
+    btn.title = `Theme: ${currentMode()} (click to switch)`;
+  }
+
+  document
+    .querySelectorAll<HTMLButtonElement>("[data-theme-toggle]")
+    .forEach((btn) => {
+      updateLabel(btn);
+      btn.addEventListener("click", () => {
+        rotate();
+        updateLabel(btn);
+      });
+      btn.addEventListener("mouseenter", () => updateLabel(btn));
+      btn.addEventListener("focus", () => updateLabel(btn));
+    });
+</script>

package/src/layouts/astro-shim.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Type declarations for the .astro layout components.
+ *
+ * The `.astro` files are excluded from `tsc` (the build only emits
+ * TypeScript helpers, not compiled components), so we declare the
+ * module shape here for the rare consumer that wants to write:
+ *
+ *   import { BaseLayout } from "@grove-dev/astro/layouts";
+ *
+ * Consumers that just want the components should import them by
+ * file:
+ *
+ *   import BaseLayout from "@grove-dev/astro/layouts/BaseLayout.astro";
+ *
+ * The `AstroComponentFactory` is the runtime type Astro uses for
+ * every `.astro` module's default export. In a normal Astro project
+ * this is declared by the generated `.astro/types.d.ts` (produced
+ * by `astro sync`); the `@grove-dev/astro` package itself doesn't
+ * run an Astro build, so we re-declare it here.
+ */
+
+declare module "*.astro" {
+  // Pull the factory type from Astro's server runtime. The path
+  // `astro/runtime/server` is a documented deep import that has
+  // shipped across Astro 4 and 5.
+  import type { AstroComponentFactory } from "astro/runtime/server";
+  const component: AstroComponentFactory;
+  export default component;
+}

package/src/layouts/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @grove-dev/astro — generic layout components.
+ *
+ * These layouts are the public, framework-agnostic shell used by
+ * every consumer page. They:
+ *
+ *   - take a `site` prop (name, tagline, nav, repoUrl) instead of
+ *     importing a `siteConfig` from a project-local path;
+ *   - compose the standard Header / Footer / Seo / Container /
+ *     SectionHeader / ThemeToggle components;
+ *   - share the `grove-theme` localStorage key for theme state.
+ *
+ * Re-exported as ESM module names. Astro resolves the
+ * `@grove-dev/astro/layouts/*` subpath import from `src/layouts/`
+ * (the package's `dist/` only contains TypeScript helpers, not the
+ * `.astro` files themselves).
+ */
+export { default as BaseLayout } from "./BaseLayout.astro";
+export { default as Container } from "./Container.astro";
+export { default as Footer } from "./Footer.astro";
+export { default as Header } from "./Header.astro";
+export { default as SectionHeader } from "./SectionHeader.astro";
+export { default as Seo } from "./Seo.astro";
+export { default as ThemeToggle } from "./ThemeToggle.astro";

package/src/lib/display.ts

@@ -0,0 +1,118 @@
+/**
+ * Display-name helpers for curation labels, statuses, lenses, and
+ * sort options. Internal ids (e.g. "hot", "stale", "production-like")
+ * stay stable for URL state and data files; this module owns the
+ * mapping from id → user-facing string.
+ *
+ * Every export is dependency-free so it can be imported by both
+ * server-rendered Astro components and any client-side script.
+ *
+ * Status ids accept the `HealthStatus` union from `@grove-dev/core`
+ * plus a couple of curated composites (e.g. "needs-maintainer")
+ * that appear in URL state.
+ */
+
+import type {
+  AppLabel,
+  HealthStatus,
+} from "@grove-dev/core";
+
+// ── Label ids (the `curation.labels` array on a record) ──────────
+export type LabelId = AppLabel;
+
+export const LABEL_DISPLAY: Record<LabelId, string> = {
+  new: "Recently added",
+  hot: "Trending",
+  mature: "Established",
+  featured: "Featured",
+};
+
+/** Pretty-print a slug to Title Case. Used for arbitrary slugs. */
+export function prettySlug(slug: string | null | undefined): string {
+  if (!slug) return "";
+  return slug
+    .replace(/[-_]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .split(" ")
+    .map((w) => (w ? w[0]!.toUpperCase() + w.slice(1) : ""))
+    .join(" ");
+}
+
+/** Returns a human-readable name for a label id, or null if unknown. */
+export function labelDisplay(id: string | null | undefined): string | null {
+  if (!id) return null;
+  if (id in LABEL_DISPLAY) {
+    return LABEL_DISPLAY[id as LabelId];
+  }
+  return prettySlug(id);
+}
+
+// ── Status ids (the `health.status` field on a record) ───────────
+/**
+ * Canonical status display map. Includes the curated
+ * "needs-maintainer" composite that's emitted by the
+ * `needs-maintainer` lens.
+ */
+export const STATUS_DISPLAY: Record<string, string> = {
+  active: "Active",
+  mature: "Mature",
+  stale: "Not recently active",
+  inactive: "Inactive",
+  archived: "Archived",
+  unknown: "Unknown",
+  historical: "Historical",
+  needs_review: "Needs review",
+  quiet: "Quiet",
+  unavailable: "Unavailable",
+  "needs-maintainer": "Needs maintainer",
+};
+
+export function statusDisplay(
+  s: HealthStatus | string | null | undefined,
+): string {
+  if (!s) return STATUS_DISPLAY.unknown;
+  return STATUS_DISPLAY[s] ?? prettySlug(s);
+}
+
+// ── Lens ids (the curated tabs on /projects) ─────────────────────
+export const LENS_DISPLAY: Record<string, string> = {
+  all: "All",
+  hot: "Trending",
+  new: "Recently added",
+  mature: "Established",
+  featured: "Featured",
+  "needs-review": "Needs review",
+};
+
+export function lensDisplay(id: string | null | undefined): string {
+  if (!id) return LENS_DISPLAY.all;
+  return LENS_DISPLAY[id] ?? prettySlug(id);
+}
+
+// ── Sort ids (the /projects sort dropdown) ───────────────────────
+export const SORT_DISPLAY: Record<string, string> = {
+  "recently-updated": "Recently updated",
+  "most-starred": "Most starred",
+  "recently-added": "Recently added",
+  "best-overall": "Best overall",
+  alphabetical: "Alphabetical",
+};
+
+export function sortDisplay(id: string | null | undefined): string {
+  if (!id) return SORT_DISPLAY["recently-updated"];
+  return SORT_DISPLAY[id] ?? prettySlug(id);
+}
+
+// ── Status option list (used by filter dropdowns) ───────────────
+// "needs-maintainer" is included even though it's a derived/composite
+// status — filter dropdowns and chip rendering need to offer it
+// alongside the raw HealthStatus values.
+export const STATUS_OPTIONS: string[] = [
+  "active",
+  "quiet",
+  "stale",
+  "needs-maintainer",
+  "archived",
+  "unknown",
+];