@grove-dev/astro 0.1.5 → 0.2.5

package/src/index.ts

@@ -1,17 +1,64 @@
 /**
- * @grove-dev/astro — Astro UI primitives for Grove.
+ * @grove-dev/astro — Astro framework adapter for Grove.
  *
- * This package only owns Astro components, layouts, styles, and
- * Astro-specific integrations. Generic filter/sort/stats/score
- * helpers live in `@grove-dev/ui` and are re-exported from here for
- * convenience.
- *
- * Astro components are not exported from this barrel — consumers
- * import them by path, e.g.:
- *   import ItemCard from "@grove-dev/astro/components/ItemCard.astro";
- *   import BaseLayout from "@grove-dev/astro/layouts/BaseLayout.astro";
- *
- * That keeps the barrel type-only and lets `astro check` validate
- * the .astro files in their own context.
+ * Provides:
+ *  - `default` export: an Astro integration that wires the
+ *    `@grove-dev/astro/components/*` and `@grove-dev/astro/layouts/*`
+ *    subpath imports into Vite so consumer projects can write:
+ *        import ItemCard from "@grove-dev/astro/components/ItemCard.astro";
+ *    and have Vite resolve the source `.astro` file (the package's
+ *    `dist/` only contains TypeScript helpers, not the components
+ *    themselves).
+ *  - Re-exports the framework-agnostic `Resource` types from
+ *    `@grove-dev/core` so the component prop signatures stay
+ *    type-safe without forcing a dependency on the core package
+ *    in every consumer file.
+ *  - Re-exports the generic `lib/` helpers (search, lenses, scores,
+ *    repo, format, display, taxonomy-counts) under a single import
+ *    path so consumers can `import { ... } from "@grove-dev/astro"`.
  */
-export * from "@grove-dev/ui";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import type { AstroIntegration } from "astro";
+
+export * from "@grove-dev/core";
+
+// Generic lib helpers — repo URL parsing, formatting, search /
+// facet / sort / paginate, lens application, score tiers, taxonomy
+// counts, and pretty-print display maps. All dependency-free and
+// typed against `@grove-dev/core`.
+export * from "./lib/index.js";
+
+const here = dirname(fileURLToPath(import.meta.url));
+// `here` is the compiled `dist/` directory. The components and
+// layouts live in the source tree (the `dist/` is for the
+// integration helper only). Walk up one level to reach `src/`
+// before resolving the subpath roots.
+const srcRoot = resolve(here, "..", "src");
+const componentsDir = resolve(srcRoot, "components");
+const layoutsDir = resolve(srcRoot, "layouts");
+
+export default function groveAstro(): AstroIntegration {
+  return {
+    name: "@grove-dev/astro",
+    hooks: {
+      "astro:config:setup": ({ updateConfig }) => {
+        // Alias the components/layouts source directories so
+        // consumer builds can import from
+        //   @grove-dev/astro/components/ItemCard.astro
+        // without us shipping a glob-shaped `exports` map that
+        // Vite/Rollup does not expand reliably.
+        updateConfig({
+          vite: {
+            resolve: {
+              alias: {
+                "@grove-dev/astro/components": componentsDir,
+                "@grove-dev/astro/layouts": layoutsDir,
+              },
+            },
+          },
+        });
+      },
+    },
+  };
+}

package/src/layouts/BaseLayout.astro

@@ -1,32 +1,244 @@
 ---
+/**
+ * BaseLayout — wraps every page. Owns the theme-detection inline
+ * script and the global shell (Header, Footer). Per-page SEO
+ * (title, description, OG, JSON-LD) is delegated to <Seo /> so each
+ * page can declare what it needs without polluting the layout.
+ *
+ * Generic: takes a `site` prop with brand + nav, no siteConfig import.
+ * The header / footer / SEO components are imported from sibling
+ * files; consumers can override the Header/Footer via Astro's slot
+ * mechanism (`<Header slot="header" />`) if they need custom branding.
+ *
+ * The THEME_INIT inline script persists user preference in
+ * `localStorage` under the key "grove-theme" — matching the key
+ * `ThemeToggle.astro` uses.
+ */
+
 import "../styles.css";
+import Header from "./Header.astro";
+import Footer from "./Footer.astro";
+import Seo from "./Seo.astro";
+
+interface NavItem {
+  label: string;
+  href: string;
+}
+
+interface Site {
+  name: string;
+  tagline?: string;
+  description?: string;
+  nav: NavItem[];
+  repoUrl?: string;
+  url?: string;
+}
 
 interface Props {
   title: string;
-  description?: string;
+  description: string;
+  site: Site;
+  type?: "website" | "article" | "profile";
+  noindex?: boolean;
+  jsonLd?: Record<string, unknown> | Record<string, unknown>[];
+  /** Optional Google Analytics 4 Measurement ID (e.g. "G-XXXXXX"). */
+  gaId?: string;
+  /** Path used for JSON-LD `SearchAction` target. Defaults to "/projects". */
+  searchPath?: string;
+  /** Submit button label rendered in the header. Omit to hide. */
+  submitLabel?: string;
+  /** Submit button href rendered in the header. */
+  submitHref?: string;
 }
 
-const { title, description = "A living, health-aware developer directory." } = Astro.props;
+const {
+  title,
+  description,
+  site,
+  type,
+  noindex,
+  jsonLd,
+  gaId,
+  searchPath,
+  submitLabel,
+  submitHref,
+} = Astro.props;
+
+const favicon =
+  "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Crect width='16' height='16' rx='3' fill='%2318181b'/%3E%3C/svg%3E";
 ---
 
 <!doctype html>
 <html lang="en">
   <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <meta name="description" content={description} />
-    <title>{title}</title>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="generator" content={Astro.generator} />
+    <meta name="theme-color" content="#0a0a0c" media="(prefers-color-scheme: dark)" />
+    <meta name="theme-color" content="#fafafa" media="(prefers-color-scheme: light)" />
+    <link rel="icon" href={favicon} />
+    <link rel="sitemap" href="/sitemap.xml" />
+    <link
+      rel="alternate"
+      type="text/plain"
+      href="/llms.txt"
+      title="LLM usage guidance"
+    />
+
+    {gaId && (
+      <>
+        {/* GA4 — gtag.js loader. We send the initial page_view with
+            the current path + query string so the dashboard
+            distinguishes /projects?stack=flutter from
+            /projects?stack=react (otherwise they'd all collapse to
+            /projects). */}
+        <script
+          is:inline
+          async
+          src={`https://www.googletagmanager.com/gtag/js?id=${gaId}`}
+        />
+        <script is:inline define:vars={{ gaId }}>
+          window.dataLayer = window.dataLayer || [];
+          function gtag() {
+            dataLayer.push(arguments);
+          }
+          gtag("js", new Date());
+          gtag("config", gaId, {
+            page_path: window.location.pathname + window.location.search,
+            page_title: document.title,
+          });
+        </script>
+      </>
+    )}
+
+    <Seo
+      title={title}
+      description={description}
+      type={type}
+      noindex={noindex}
+      jsonLd={jsonLd}
+      site={site}
+      searchPath={searchPath}
+    />
+
+    <slot name="head" />
+
+    <script is:inline>
+      // THEME_INIT — runs before paint so the user never sees a
+      // flash of the wrong theme. State is persisted in localStorage
+      // under the key "grove-theme" (matching ThemeToggle.astro).
+      (function () {
+        var STORAGE_KEY = "grove-theme";
+        function getMode() {
+          try {
+            var stored = localStorage.getItem(STORAGE_KEY);
+            if (stored === "light" || stored === "dark" || stored === "system")
+              return stored;
+          } catch (e) {
+            // localStorage may be blocked (private mode, etc.) —
+            // fall through to the system default.
+          }
+          return "system";
+        }
+        function apply(mode) {
+          var resolved =
+            mode === "system"
+              ? (window.matchMedia("(prefers-color-scheme: dark)").matches
+                  ? "dark"
+                  : "light")
+              : mode;
+          var root = document.documentElement;
+          if (resolved === "dark") root.classList.add("dark");
+          else root.classList.remove("dark");
+          root.dataset.theme = mode;
+          root.dataset.resolvedTheme = resolved;
+        }
+        apply(getMode());
+        window.addEventListener("theme:set", function (e) {
+          apply(e.detail);
+        });
+        var mq = window.matchMedia("(prefers-color-scheme: dark)");
+        mq.addEventListener("change", function () {
+          if (getMode() === "system") apply("system");
+        });
+      })();
+    </script>
   </head>
-  <body>
-    <header class="oc-topbar">
-      <a href="/" class="oc-brand">Grove</a>
-      <nav aria-label="Primary">
-        <a href="/projects">Directory</a>
-        <a href="/methodology">Methodology</a>
-      </nav>
-    </header>
-    <main class="oc-shell">
+  <body class="min-h-screen bg-white text-ink-900 dark:bg-ink-950 dark:text-ink-100">
+    <slot name="header">
+      <Header
+        site={site}
+        submitLabel={submitLabel}
+        submitHref={submitHref}
+      />
+    </slot>
+
+    <main>
       <slot />
     </main>
+
+    <slot name="footer">
+      <Footer site={site} />
+    </slot>
+
+    <slot name="body-end" />
+
+    {gaId && (
+      <script is:inline define:vars={{ gaId }}>
+        // Mirror in-page SPA navigation (history.pushState /
+        // replaceState) into GA4 page_view events so filter changes
+        // on /projects show up as separate page views in the
+        // dashboard instead of one inflated session.
+        (function () {
+          var last = location.pathname + location.search;
+          function report() {
+            var next = location.pathname + location.search;
+            if (next === last) return;
+            last = next;
+            window.gtag("event", "page_view", {
+              page_path: next,
+              page_title: document.title,
+              page_location: location.href,
+            });
+          }
+          window.addEventListener("popstate", report);
+          var origPush = history.pushState;
+          var origReplace = history.replaceState;
+          history.pushState = function () {
+            origPush.apply(this, arguments);
+            report();
+          };
+          history.replaceState = function () {
+            origReplace.apply(this, arguments);
+            report();
+          };
+        })();
+      </script>
+    )}
+
+    {gaId && (
+      <script is:inline>
+        // Delegated click handler for `data-event` elements. We do
+        // this in one place so individual components just emit data
+        // attributes and stay declarative.
+        (function () {
+          document.addEventListener("click", function (e) {
+            var el = e.target instanceof Element
+              ? e.target.closest("[data-event]")
+              : null;
+            if (!el) return;
+            var name = el.getAttribute("data-event");
+            if (!name) return;
+            var params = {
+              source: el.getAttribute("data-event-source") || undefined,
+              app_slug: el.getAttribute("data-event-app") || undefined,
+              channel: el.getAttribute("data-event-channel") || undefined,
+              link_url: el.getAttribute("href") || undefined,
+            };
+            window.gtag("event", name, params);
+          });
+        })();
+      </script>
+    )}
   </body>
 </html>

package/src/layouts/Container.astro

@@ -0,0 +1,57 @@
+---
+/**
+ * Container — page-width wrapper.
+ *
+ * Centralizes the three layout widths the showcase uses:
+ *
+ *   - "default" → 1140px (the standard reading width)
+ *   - "wide"    → 1400px (home, full-bleed grid sections)
+ *   - "narrow"  → 720px  (about, methodology, content-heavy pages)
+ *
+ * Pure layout, no styling dependencies beyond Tailwind's `max-w-*`
+ * tokens defined in `@grove-dev/astro/styles.css`.
+ */
+
+interface Props {
+  size?: "default" | "wide" | "narrow";
+  class?: string;
+  /** Padding preset. Defaults to a comfortable 1.25rem / 1.75rem. */
+  padding?: "default" | "none" | "tight";
+}
+
+const {
+  size = "default",
+  class: className = "",
+  padding = "default",
+} = Astro.props;
+
+const sizeClass =
+  size === "wide"
+    ? "grove-container-wide"
+    : size === "narrow"
+      ? "grove-container-narrow"
+      : "grove-container";
+
+const paddingClass =
+  padding === "none"
+    ? ""
+    : padding === "tight"
+      ? "px-4 sm:px-5"
+      : "px-5 sm:px-7";
+---
+
+<div class:list={["mx-auto", sizeClass, paddingClass, className]}>
+  <slot />
+</div>
+
+<style>
+  .grove-container {
+    max-width: var(--container-container, 1140px);
+  }
+  .grove-container-wide {
+    max-width: var(--container-wide, 1400px);
+  }
+  .grove-container-narrow {
+    max-width: var(--container-narrow, 720px);
+  }
+</style>

package/src/layouts/Footer.astro

@@ -0,0 +1,235 @@
+---
+/**
+ * Footer — 4-column grid (brand + Discover + Contribute + Project) plus
+ * a thin bar at the bottom with copyright + repo link.
+ *
+ * Generic: takes a `site` prop with brand + repoUrl. No siteConfig
+ * import — consumers compose props from their own config.
+ *
+ * Each column's links are passed in as a `{ heading, items[] }` shape
+ * so consumers can customize the order and copy. Defaults are provided
+ * for the brand and bar so the footer still renders if no extra
+ * link data is supplied.
+ */
+
+interface NavItem {
+  label: string;
+  href: string;
+  /** When true, opens in a new tab (external). */
+  external?: boolean;
+}
+
+interface FooterColumn {
+  heading: string;
+  items: NavItem[];
+}
+
+interface Site {
+  name: string;
+  tagline?: string;
+  description?: string;
+  repoUrl?: string;
+}
+
+interface Props {
+  site: Site;
+  /** Discover links — first content column. */
+  discover?: FooterColumn;
+  /** Contribute links — second content column. */
+  contribute?: FooterColumn;
+  /** Project links — third content column. */
+  project?: FooterColumn;
+  /** Stats line under brand blurb (e.g. "79 apps · 12 categories"). */
+  stats?: { apps?: number; categories?: number; contributors?: number };
+  /** Copyright suffix. Defaults to site.name. */
+  copyrightHolder?: string;
+  /** License line under the bar (e.g. "Content under CC BY-SA 4.0."). */
+  licenseLine?: string;
+  /** Extra class for the outer footer element. */
+  class?: string;
+}
+
+const {
+  site,
+  discover = { heading: "Discover", items: [] },
+  contribute = { heading: "Contribute", items: [] },
+  project = { heading: "Project", items: [] },
+  stats,
+  copyrightHolder,
+  licenseLine,
+  class: className = "",
+} = Astro.props;
+
+const year = new Date().getFullYear();
+const holder = copyrightHolder ?? site.name;
+const gh = site.repoUrl;
+
+const defaultDiscover: NavItem[] = gh
+  ? [
+      { label: "Source on GitHub", href: gh, external: true },
+      { label: "Latest release", href: `${gh}/releases`, external: true },
+    ]
+  : [];
+const defaultContribute: NavItem[] = gh
+  ? [
+      { label: "Submit via GitHub", href: `${gh}/blob/main/CONTRIBUTING.md`, external: true },
+      { label: "Report an issue", href: `${gh}/issues`, external: true },
+      { label: "Contributing guide", href: `${gh}/blob/main/CONTRIBUTING.md`, external: true },
+    ]
+  : [];
+const defaultProject: NavItem[] = gh
+  ? [
+      { label: "README", href: `${gh}/blob/main/README.md`, external: true },
+      { label: "Changelog", href: `${gh}/blob/main/CHANGELOG.md`, external: true },
+    ]
+  : [];
+
+const discoverItems = discover.items.length ? discover.items : defaultDiscover;
+const contributeItems = contribute.items.length ? contribute.items : defaultContribute;
+const projectItems = project.items.length ? project.items : defaultProject;
+---
+
+<footer
+  class:list={[
+    "mt-16 border-t border-ink-200 bg-white text-ink-500 dark:border-ink-800 dark:bg-ink-950 dark:text-ink-400",
+    className,
+  ]}
+>
+  <div
+    class="mx-auto grid max-w-wide grid-cols-2 gap-8 px-5 py-12 md:grid-cols-4 sm:px-7"
+    style="max-width: var(--container-wide, 1400px);"
+  >
+    <div class="col-span-2 md:col-span-1">
+      <div
+        class="mb-2 inline-flex items-center gap-2 text-[0.95rem] font-semibold text-ink-900 dark:text-ink-100"
+      >
+        <span
+          aria-hidden="true"
+          class="inline-block h-3.5 w-3.5 rounded bg-ink-900 dark:bg-ink-100"
+        ></span>
+        <span>{site.name}</span>
+      </div>
+      {site.tagline && (
+        <p class="m-0 max-w-[36ch] text-[0.8125rem] leading-relaxed text-ink-500 dark:text-ink-400">
+          {site.tagline}
+        </p>
+      )}
+      {stats && (
+        <p class="mt-3 m-0 text-2xs text-ink-500 dark:text-ink-400">
+          {stats.apps !== undefined && (
+            <>
+              <span class="font-mono">{stats.apps}</span> apps
+            </>
+          )}
+          {stats.apps !== undefined && (stats.categories !== undefined || stats.contributors !== undefined) && (
+            <span class="mx-1 text-ink-300 dark:text-ink-700">·</span>
+          )}
+          {stats.categories !== undefined && (
+            <>
+              <span class="font-mono">{stats.categories}</span> categories
+            </>
+          )}
+          {stats.categories !== undefined && stats.contributors !== undefined && (
+            <span class="mx-1 text-ink-300 dark:text-ink-700">·</span>
+          )}
+          {stats.contributors !== undefined && (
+            <>
+              <span class="font-mono">{stats.contributors}</span> contributors
+            </>
+          )}
+        </p>
+      )}
+    </div>
+
+    {discoverItems.length > 0 && (
+      <div>
+        <h4 class="mb-3 text-2xs font-semibold uppercase tracking-wider text-ink-900 dark:text-ink-100">
+          {discover.heading}
+        </h4>
+        <ul class="m-0 flex list-none flex-col gap-2 p-0">
+          {discoverItems.map((item) => (
+            <li>
+              <a
+                href={item.href}
+                class="text-sm transition-colors hover:text-ink-900 dark:hover:text-ink-100"
+                {...(item.external
+                  ? { target: "_blank", rel: "noopener noreferrer" }
+                  : {})}
+              >
+                {item.label}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </div>
+    )}
+
+    {contributeItems.length > 0 && (
+      <div>
+        <h4 class="mb-3 text-2xs font-semibold uppercase tracking-wider text-ink-900 dark:text-ink-100">
+          {contribute.heading}
+        </h4>
+        <ul class="m-0 flex list-none flex-col gap-2 p-0">
+          {contributeItems.map((item) => (
+            <li>
+              <a
+                href={item.href}
+                class="text-sm transition-colors hover:text-ink-900 dark:hover:text-ink-100"
+                {...(item.external
+                  ? { target: "_blank", rel: "noopener noreferrer" }
+                  : {})}
+              >
+                {item.label}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </div>
+    )}
+
+    {projectItems.length > 0 && (
+      <div>
+        <h4 class="mb-3 text-2xs font-semibold uppercase tracking-wider text-ink-900 dark:text-ink-100">
+          {project.heading}
+        </h4>
+        <ul class="m-0 flex list-none flex-col gap-2 p-0">
+          {projectItems.map((item) => (
+            <li>
+              <a
+                href={item.href}
+                class="text-sm transition-colors hover:text-ink-900 dark:hover:text-ink-100"
+                {...(item.external
+                  ? { target: "_blank", rel: "noopener noreferrer" }
+                  : {})}
+              >
+                {item.label}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </div>
+    )}
+  </div>
+
+  <div class="border-t border-ink-200 dark:border-ink-800">
+    <div
+      class="mx-auto flex max-w-wide flex-wrap items-center gap-3 px-5 py-4 text-2xs text-ink-500 sm:px-7 dark:text-ink-400"
+      style="max-width: var(--container-wide, 1400px);"
+    >
+      <span>© {year} {holder}.{licenseLine ? ` ${licenseLine}` : ""}</span>
+      {gh && (
+        <>
+          <span class="text-ink-300 dark:text-ink-700">·</span>
+          <a
+            href={gh}
+            target="_blank"
+            rel="noopener noreferrer"
+            class="transition-colors hover:text-ink-900 dark:hover:text-ink-100"
+          >
+            View source on GitHub
+          </a>
+        </>
+      )}
+    </div>
+  </div>
+</footer>