@grove-dev/astro 0.1.4 → 0.2.2

package/src/lib/format.ts

@@ -0,0 +1,65 @@
+/**
+ * Shared formatting helpers.
+ *
+ * Dependency-free — importable by both server-rendered Astro
+ * components and any future client-side script. No `Intl`-heavy
+ * calls that would explode the client bundle.
+ */
+
+/**
+ * Format a number compactly: 1234 → "1.2k", 12345 → "12k", 79 → "79".
+ * Used for hero/header star counts and other large-num displays.
+ */
+export function compact(n: number): string {
+  if (n >= 1000) {
+    const k = n / 1000;
+    return (k >= 10 ? Math.round(k).toString() : k.toFixed(1)) + "k";
+  }
+  return n.toString();
+}
+
+/**
+ * Format a star count compactly. Returns `null` when input is not a
+ * finite number, so callers can render "—" without an extra guard.
+ */
+export function formatStars(n: number | null | undefined): string | null {
+  if (typeof n !== "number" || !Number.isFinite(n)) return null;
+  return compact(n);
+}
+
+/**
+ * Format an ISO date as a human "Xd ago" / "Xmo ago" / "Xy ago" string.
+ * Returns "—" for missing or invalid input, and "today" for future
+ * dates (which can happen with bad upstream timestamps).
+ */
+export function formatRelative(date: string | null | undefined): string {
+  if (!date) return "—";
+  const d = new Date(date);
+  if (Number.isNaN(d.valueOf())) return "—";
+  const days = Math.floor((Date.now() - d.valueOf()) / (1000 * 60 * 60 * 24));
+  if (days <= 0) return "today";
+  if (days === 1) return "1d ago";
+  if (days < 30) return `${days}d ago`;
+  const months = Math.floor(days / 30);
+  if (months === 1) return "1mo ago";
+  if (months < 12) return `${months}mo ago`;
+  const years = Math.floor(months / 12);
+  if (years === 1) return "1y ago";
+  return `${years}y ago`;
+}
+
+/**
+ * Format an ISO date as a localized short date (e.g. "Jan 5, 2026").
+ * Returns the original string for unparseable input, or "—" when
+ * no value is provided.
+ */
+export function formatDate(date: string | null | undefined): string {
+  if (!date) return "—";
+  const d = new Date(date);
+  if (Number.isNaN(d.valueOf())) return date;
+  return d.toLocaleDateString("en-US", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  });
+}

package/src/lib/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @grove-dev/astro — framework-agnostic lib helpers.
+ *
+ * Re-exports every helper that the showcase component library
+ * (and any future consumer) can use to:
+ *
+ *   - parse GitHub repo URLs (`lib/repo`)
+ *   - format counts, dates, stars (`lib/format`)
+ *   - apply curated lenses / facets / search filters (`lib/lenses`,
+ *     `lib/search`)
+ *   - render score bars (`lib/scores`)
+ *   - compute taxonomy counts at build time (`lib/taxonomy-counts`)
+ *   - pretty-print slugs and label/lens/sort/status ids (`lib/display`)
+ *
+ * All helpers are pure, dependency-free, and typed against
+ * `@grove-dev/core` (specifically `ProjectRecord` for the index
+ * payload and the `Score` / `HealthStatus` unions).
+ */
+
+export * from "./repo.js";
+export * from "./format.js";
+export * from "./lenses.js";
+export * from "./search.js";
+export * from "./scores.js";
+export * from "./taxonomy-counts.js";
+export * from "./display.js";

package/src/lib/lenses.ts

@@ -0,0 +1,241 @@
+/**
+ * Curated lenses for the list / discovery page.
+ *
+ * A lens is a single-select view that translates into a (possibly
+ * empty) URL search-param filter. The 6 lenses below cover the
+ * "what should I look at next?" mental shortcut:
+ *
+ *   - "all"          — no filter
+ *   - "hot"          — recent attention: stars ≥ 1000 OR pushed within 30d
+ *   - "new"          — fresh entries: pushed within 7d OR curated "new" label
+ *   - "mature"       — long-running projects: curated tier AND pushed > 365d ago
+ *   - "featured"     — curated "featured" label
+ *   - "needs-review" — cleanup candidate (stale / archived / etc.)
+ *
+ * The lens id is what shows up in the URL as `?lens=...`. Filter
+ * resolution happens in `lib/search.ts` (`filterApps`).
+ *
+ * Keep this list in sync with `lib/search.ts` and any UI tabs.
+ */
+
+import type {
+  HealthStatus,
+  ProjectRecord,
+} from "@grove-dev/core";
+
+export type LensId =
+  | "all"
+  | "hot"
+  | "new"
+  | "mature"
+  | "featured"
+  | "needs-review";
+
+export interface LensDef {
+  id: LensId;
+  label: string;
+  description: string;
+  /**
+   * Returns true when the record matches this lens. Designed to
+   * operate on the index payload (`toIndexRecord`) shape — the
+   * same record the list page already holds — so consumers don't
+   * need to do a second fetch.
+   */
+  match: (record: AppLike) => boolean;
+}
+
+const DAY_MS = 86_400_000;
+
+/**
+ * The shape that lens matching actually reads. Decoupled from
+ * `ProjectRecord` so the search lib can also pass the index payload
+ * (which omits a few heavy fields) and tests can pass minimal
+ * fixtures.
+ */
+export interface AppLike {
+  curation?: { labels?: string[] };
+  health?: {
+    status?: HealthStatus;
+    tier?: "curated" | "listed" | "experimental" | "hidden";
+    cleanupCandidate?: boolean;
+  };
+  github?: {
+    stars?: number;
+    pushedAt?: string | null;
+  };
+}
+
+function daysSince(iso: string | null | undefined): number {
+  if (!iso) return Infinity;
+  const d = new Date(iso);
+  if (Number.isNaN(d.valueOf())) return Infinity;
+  return (Date.now() - d.valueOf()) / DAY_MS;
+}
+
+function hasLabel(record: AppLike, label: string): boolean {
+  return record.curation?.labels?.includes(label) ?? false;
+}
+
+const CLEANUP_STATUSES: HealthStatus[] = [
+  "stale",
+  "inactive",
+  "archived",
+  "unavailable",
+  "needs_review",
+];
+
+function isCleanupCandidate(record: AppLike): boolean {
+  if (record.health?.cleanupCandidate) return true;
+  const status = record.health?.status;
+  if (!status) return false;
+  return CLEANUP_STATUSES.includes(status);
+}
+
+export const LENSES: LensDef[] = [
+  {
+    id: "all",
+    label: "All",
+    description: "Every record in the directory.",
+    match: () => true,
+  },
+  {
+    id: "hot",
+    label: "Trending",
+    description:
+      "Records with recent attention — stars ≥ 1000 or pushed within 30 days.",
+    match: (r) => {
+      const stars = r.github?.stars ?? 0;
+      const pushed = daysSince(r.github?.pushedAt);
+      return stars >= 1000 || pushed <= 30;
+    },
+  },
+  {
+    id: "new",
+    label: "Recently added",
+    description:
+      "Fresh entries — pushed within 7 days or curated with the “new” label.",
+    match: (r) => {
+      const pushed = daysSince(r.github?.pushedAt);
+      return pushed <= 7 || hasLabel(r, "new");
+    },
+  },
+  {
+    id: "mature",
+    label: "Established",
+    description:
+      "Long-running projects — curated tier and last push > 365 days ago.",
+    match: (r) => {
+      const tier = r.health?.tier;
+      const pushed = daysSince(r.github?.pushedAt);
+      return tier === "curated" && pushed > 365;
+    },
+  },
+  {
+    id: "featured",
+    label: "Featured",
+    description: "Records curated with the “featured” label.",
+    match: (r) => hasLabel(r, "featured"),
+  },
+  {
+    id: "needs-review",
+    label: "Needs review",
+    description: "Cleanup candidates — stale, archived, or unmaintained.",
+    match: (r) => isCleanupCandidate(r),
+  },
+];
+
+/**
+ * The lenses rendered as top-row tabs on the list page. Order
+ * matters — left to right. Keep this in sync with what the design
+ * calls for; URL deep-linking accepts any `LensId` even if it's not
+ * in the primary row.
+ */
+export const PRIMARY_LENSES: LensId[] = [
+  "all",
+  "hot",
+  "new",
+  "mature",
+  "featured",
+  "needs-review",
+];
+
+export function lensById(id: string | null | undefined): LensDef | undefined {
+  if (!id) return undefined;
+  return LENSES.find((l) => l.id === id);
+}
+
+export function isPrimaryLens(id: string | null | undefined): id is LensId {
+  if (!id) return false;
+  return PRIMARY_LENSES.includes(id as LensId);
+}
+
+/**
+ * Resolve the active lens from URL search params. Returns the empty
+ * string when no `lens=...` is set, so callers can treat both
+ * "absent" and "unknown" identically.
+ */
+export function lensFromSearchParams(
+  params: URLSearchParams,
+): LensId | "" {
+  const v = params.get("lens");
+  if (!v) return "";
+  if (LENSES.some((l) => l.id === v)) return v as LensId;
+  return "";
+}
+
+/**
+ * `true` when the URL search params currently reflect this lens's
+ * filter shape. The "all" lens is the implicit "no filter" state —
+ * it's active only when no other lens-shaped params are present.
+ */
+export function isLensActive(lensId: LensId, params: URLSearchParams): boolean {
+  if (lensId === "all") {
+    return lensFromSearchParams(params) === "" && !params.get("label");
+  }
+  return lensFromSearchParams(params) === lensId;
+}
+
+/**
+ * Build a `href` for a lens tab. Selecting a lens resets the other
+ * "view" params (label, page) and applies only the chosen lens's
+ * filter. Other filters (q, stack, platform, category, sort) are
+ * preserved.
+ *
+ * `pathPrefix` is the URL root for the list page — typically
+ * `/projects` for the project-directory blueprint, `/resources` for
+ * resource-hub, `/entities` for ecosystem-map. Defaults to `/`.
+ */
+export function hrefForLens(
+  lensId: LensId,
+  params: URLSearchParams,
+  pathPrefix: string = "/",
+): string {
+  const sp = new URLSearchParams(params);
+  sp.delete("lens");
+  sp.delete("label");
+  sp.delete("page");
+  if (lensId && lensId !== "all") {
+    sp.set("lens", lensId);
+  }
+  const qs = sp.toString();
+  const base = pathPrefix.replace(/\/$/, "");
+  return qs ? `${base}?${qs}` : base || "/";
+}
+
+/**
+ * Apply the lens filter to a record array. When `lensId` is
+ * `""` (no lens) or `"all"`, returns the input unchanged.
+ *
+ * Type-parameterized so the same helper works on `ProjectRecord[]`
+ * and on the lighter index payload that list pages ship.
+ */
+export function applyLens<T extends AppLike>(records: T[], lensId: LensId | ""): T[] {
+  if (!lensId || lensId === "all") return records;
+  const def = lensById(lensId);
+  if (!def) return records;
+  return records.filter((r) => def.match(r));
+}
+
+// Re-export the type so consumers can write `import type { AppLike }`
+// without depending on `@grove-dev/core` directly.
+export type { ProjectRecord };

package/src/lib/repo.ts

@@ -0,0 +1,44 @@
+/**
+ * Parse a GitHub repo URL into its owner and repo components.
+ *
+ * Returns `null` (not `{ owner: null, repo: null }`) if the URL
+ * doesn't match the github.com path shape — this lets callers
+ * distinguish "no URL" from "URL without owner" with a single
+ * null check.
+ *
+ * Used in:
+ *  - ItemCard / AppCard avatar fallback (owner avatar via GitHub
+ *    avatars API).
+ *  - Detail page (showing owner + repo name in breadcrumb / header).
+ *  - Anywhere we need to display "@owner / repo" or link to the owner.
+ */
+export function getOwnerAndRepoFromRepoUrl(
+  repoUrl: string | null | undefined,
+): { owner: string; repo: string } | null {
+  if (!repoUrl || !repoUrl.includes("github.com/")) return null;
+  const m = repoUrl.match(/github\.com\/([^/]+)\/([^/?#]+)/);
+  if (!m) return null;
+  return {
+    owner: m[1],
+    repo: m[2].replace(/\.git$/, ""),
+  };
+}
+
+/**
+ * Build a GitHub avatar URL for a given owner. Defaults to size 80
+ * which is the smallest "high quality" size in GitHub's avatar CDN.
+ *
+ * Returns a string (not nullable) so callers can plug the result
+ * straight into an `src` attribute. The avatar endpoint always
+ * returns a placeholder image for unknown owners, so the only
+ * reason to check `null` upstream is when you specifically want
+ * to render a different fallback (e.g. initials).
+ */
+export function getOwnerAvatarUrl(owner: string, size = 80): string {
+  if (!owner) {
+    // Defensive: callers may pass a possibly-empty string. Return the
+    // generic GitHub identicon so an `<img>` doesn't 404.
+    return `https://avatars.githubusercontent.com/identicon?v=4&s=${size}`;
+  }
+  return `https://avatars.githubusercontent.com/${owner}?v=4&s=${size}`;
+}

package/src/lib/scores.ts

@@ -0,0 +1,94 @@
+/**
+ * Score-dimension utilities.
+ *
+ * Operates on the `scores` field of a `ProjectRecord` (or any
+ * object that has the same shape — defined as `Score` in
+ * `@grove-dev/core`). All helpers are dependency-free.
+ */
+
+import type { Score } from "@grove-dev/core";
+
+/**
+ * Format a single score (0-100) into a 0-5 "tier" used by the UI:
+ *
+ *   0-19  → 0  (very low)
+ *   20-39 → 1  (low)
+ *   40-59 → 2  (medium)
+ *   60-79 → 3  (high)
+ *   80-100 → 4 (very high)
+ *
+ * The list page renders each score as a 4-cell bar; this gives
+ * the visual a stable shape regardless of the underlying number.
+ */
+export function scoreTier(n: number): 0 | 1 | 2 | 3 | 4 {
+  if (n < 20) return 0;
+  if (n < 40) return 1;
+  if (n < 60) return 2;
+  if (n < 80) return 3;
+  return 4;
+}
+
+/** Compact textual label for a score tier (used in tooltips). */
+export function scoreTierLabel(n: number): string {
+  switch (scoreTier(n)) {
+    case 0:
+      return "Very low";
+    case 1:
+      return "Low";
+    case 2:
+      return "Medium";
+    case 3:
+      return "High";
+    case 4:
+      return "Very high";
+  }
+}
+
+/** Short numeric label used inline next to a score bar, e.g. "82". */
+export function scoreLabel(n: number | undefined): string {
+  if (typeof n !== "number") return "—";
+  return Math.round(n).toString();
+}
+
+/** Order of score dimensions, used by both list and detail. */
+export const SCORE_DIMENSIONS: (keyof Score)[] = [
+  "activity",
+  "maturity",
+  "learning",
+  "contribution",
+  "docs",
+  "overall",
+];
+
+/** Human-readable label for a score dimension. */
+export const SCORE_LABELS: Record<keyof Score, string> = {
+  activity: "Activity",
+  maturity: "Maturity",
+  learning: "Learning",
+  contribution: "Contribution",
+  docs: "Docs",
+  overall: "Overall",
+};
+
+/**
+ * Reasoning copy per dimension, surfaced in the detail page so the
+ * numbers don't feel magical. These are intentionally short — the
+ * curation notes on each record carry the longer story.
+ */
+export const SCORE_REASONING: Record<keyof Score, string> = {
+  activity:
+    "Recent commits, open and merged PRs, issue response time, release cadence.",
+  maturity:
+    "Repo age, stable structure, real-world production usage, contributor stability.",
+  learning:
+    "Codebase readability, useful architecture patterns, comment quality, examples.",
+  contribution:
+    "Open issues, recent merged PRs from new contributors, maintainer responsiveness, contribution guide.",
+  docs:
+    "README quality, architecture docs, contributing guide, examples, code comments.",
+  overall:
+    "Composite judgment — how likely this record is to satisfy a curious developer.",
+};
+
+/** Re-export the `Score` type for callers that only need the lib API. */
+export type { Score };