@grove-dev/astro 0.5.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grove-dev/astro",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "description": "Composable Astro UI, data adapters, and integration for Grove directories.",
   "license": "MIT",
@@ -34,6 +34,7 @@
     "src/layouts",
     "src/lib",
     "src/server",
+    "src/ui",
     "src/index.ts",
     "src/styles.css",
     "README.md"
@@ -59,7 +60,7 @@
     "sanitize-html": "^2.17.5",
     "shiki": "^1.29.2",
     "yaml": "^2.9.0",
-    "@grove-dev/core": "0.5.0"
+    "@grove-dev/core": "0.5.1"
   },
   "peerDependencies": {
     "astro": "^6.0.0 || ^7.0.0"

package/src/ui/Badge.astro

@@ -0,0 +1,38 @@
+---
+/**
+ * Badge — small labeled state indicator.
+ *
+ * Variant is the MEANING, not the color:
+ * - `neutral`  — plain metadata (counts, kinds).
+ * - `selected` — "you are here" (neutral inversion, never green).
+ * - `success` / `warning` / `danger` / `info` — actual status. These
+ *   use the status tokens, so green here means "healthy/succeeded",
+ *   not "brand" and not "selected".
+ */
+
+export type BadgeVariant = "neutral" | "selected" | "success" | "warning" | "danger" | "info";
+
+interface Props {
+  variant?: BadgeVariant;
+  class?: string;
+  [key: string]: unknown;
+}
+
+const VARIANTS: Record<BadgeVariant, string> = {
+  neutral: "border-border bg-secondary text-secondary-foreground",
+  selected: "border-transparent bg-selected text-selected-foreground",
+  success: "border-transparent bg-success text-success-foreground",
+  warning: "border-transparent bg-warning text-warning-foreground",
+  danger: "border-transparent bg-danger text-danger-foreground",
+  info: "border-transparent bg-info text-info-foreground",
+};
+
+const { variant = "neutral", class: className = "", ...rest } = Astro.props;
+---
+
+<span
+  class={`inline-flex min-h-5 items-center gap-1 rounded-full border px-2 py-0.5 text-xs font-medium leading-none ${VARIANTS[variant]} ${className}`}
+  {...rest}
+>
+  <slot />
+</span>

package/src/ui/Button.astro

@@ -0,0 +1,42 @@
+---
+/**
+ * Button — the shared interactive control.
+ *
+ * Renders an `<a>` when `href` is given, otherwise a `<button>`.
+ * Styling comes exclusively from `buttonClass()` (ui/button.ts) so
+ * server components, consumer pages, and the client script share one
+ * definition. Pass layout-only extras (widths, one-off spacing)
+ * through `class`.
+ */
+import { buttonClass, type ButtonSize, type ButtonVariant } from "./button.js";
+
+interface Props {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  href?: string;
+  type?: "button" | "submit" | "reset";
+  rel?: string;
+  target?: string;
+  disabled?: boolean;
+  id?: string;
+  class?: string;
+  [key: string]: unknown;
+}
+
+const {
+  variant = "secondary",
+  size = "sm",
+  href,
+  type = "button",
+  class: className = "",
+  ...rest
+} = Astro.props;
+
+const classes = buttonClass(variant, size, className);
+---
+
+{href ? (
+  <a href={href} class={classes} {...rest}><slot /></a>
+) : (
+  <button type={type} class={classes} {...rest}><slot /></button>
+)}

package/src/ui/EmptyState.astro

@@ -0,0 +1,38 @@
+---
+/**
+ * EmptyState — a deliberate "nothing here" block that cannot be
+ * mistaken for normal content. Explains WHY the area is empty and
+ * offers a recovery action.
+ *
+ * Marked with `data-grove-empty-state` so quality gates can assert
+ * that empty regions render as empty states, not silent gaps.
+ */
+import { buttonClass, type ButtonVariant } from "./button.js";
+
+interface Props {
+  title: string;
+  /** Why it's empty / what will make it non-empty. */
+  description?: string;
+  /** Recovery action (rendered as a button-styled link). */
+  action?: { label: string; href: string; variant?: ButtonVariant };
+  class?: string;
+}
+
+const { title, description, action, class: className = "" } = Astro.props;
+---
+
+<div
+  data-grove-empty-state
+  class={`flex flex-col items-center gap-2 rounded-[calc(var(--radius)+0.25rem)] border border-dashed border-border bg-surface-sunken px-6 py-10 text-center ${className}`}
+>
+  <p class="m-0 text-sm font-medium text-foreground">{title}</p>
+  {description && (
+    <p class="m-0 max-w-[52ch] text-sm leading-relaxed text-muted-foreground">{description}</p>
+  )}
+  <slot />
+  {action && (
+    <a href={action.href} class={buttonClass(action.variant ?? "secondary", "sm", "mt-2")}>
+      {action.label}
+    </a>
+  )}
+</div>

package/src/ui/FilterDrawer.astro

@@ -0,0 +1,104 @@
+---
+/**
+ * FilterDrawer — mobile filter surface built on native `<dialog>`.
+ *
+ * `showModal()` gives focus trapping, Escape handling, and the
+ * top-layer backdrop for free — no dependency, no hand-rolled trap.
+ * On viewports ≥ md the trigger button hides and the slotted filter
+ * controls render inline through the same slot used on desktop, so
+ * there is exactly one copy of the filter markup.
+ *
+ * No-JS fallback: the slot content stays in normal flow (the dialog
+ * only wraps it once the client script moves it), so filters remain
+ * usable without JavaScript.
+ */
+import { buttonClass } from "./button.js";
+
+interface Props {
+  /** Trigger button label. */
+  label?: string;
+  /** Count of active filters shown on the trigger. */
+  activeCount?: number;
+  class?: string;
+}
+
+const { label = "Filters", activeCount = 0, class: className = "" } = Astro.props;
+---
+
+<div class={`grove-filter-drawer ${className}`} data-grove-filter-drawer>
+  <button
+    type="button"
+    data-drawer-open
+    class={buttonClass("secondary", "md", "w-full md:hidden")}
+    aria-haspopup="dialog"
+  >
+    {label}
+    {/* Always in the DOM (hidden at zero) so the client script can
+        update it from the live URL state on this prerendered page. */}
+    <span
+      data-drawer-count
+      class:list={[
+        "inline-flex min-w-5 items-center justify-center rounded-full bg-selected px-1.5 py-0.5 font-mono text-2xs leading-none text-selected-foreground",
+        activeCount === 0 && "hidden",
+      ]}
+    >
+      {activeCount}
+    </span>
+  </button>
+
+  {/* On mobile the client script moves this content into the dialog;
+      on ≥ md it stays inline. Not hidden by CSS — without JS the
+      filters must remain visible in flow on every viewport. */}
+  <div data-drawer-content class="md:contents">
+    <slot />
+  </div>
+
+  <dialog
+    data-drawer-dialog
+    class="m-0 mt-auto w-full max-w-none rounded-t-[calc(var(--radius)+0.5rem)] border-0 bg-surface-overlay p-0 text-foreground backdrop:bg-black/40 md:hidden"
+    aria-label={label}
+  >
+    <div class="flex items-center justify-between border-b border-border px-4 py-3">
+      <p class="m-0 text-sm font-semibold">{label}</p>
+      <button type="button" data-drawer-close class={buttonClass("ghost", "sm")}>
+        Done
+      </button>
+    </div>
+    <div data-drawer-body class="max-h-[70vh] overflow-y-auto p-4"></div>
+  </dialog>
+</div>
+
+<script>
+  document.querySelectorAll<HTMLElement>("[data-grove-filter-drawer]").forEach((root) => {
+    const dialog = root.querySelector<HTMLDialogElement>("[data-drawer-dialog]");
+    const content = root.querySelector<HTMLElement>("[data-drawer-content]");
+    const body = root.querySelector<HTMLElement>("[data-drawer-body]");
+    const open = root.querySelector<HTMLButtonElement>("[data-drawer-open]");
+    const close = root.querySelector<HTMLButtonElement>("[data-drawer-close]");
+    if (!dialog || !content || !body || !open) return;
+
+    const mobile = window.matchMedia("(max-width: 47.999rem)");
+    const place = () => {
+      // One copy of the filter markup, moved between the inline slot
+      // (desktop) and the dialog body (mobile).
+      if (mobile.matches) {
+        body.append(...content.children);
+        content.classList.add("hidden");
+      } else {
+        if (dialog.open) dialog.close();
+        content.append(...body.children);
+        content.classList.remove("hidden");
+      }
+    };
+    place();
+    mobile.addEventListener("change", place);
+
+    open.addEventListener("click", () => dialog.showModal());
+    close?.addEventListener("click", () => dialog.close());
+    dialog.addEventListener("click", (event) => {
+      // Backdrop click closes: the dialog element itself is the
+      // target only when the click lands outside the panel content.
+      if (event.target === dialog) dialog.close();
+    });
+  });
+</script>

package/src/ui/PageHeader.astro

@@ -0,0 +1,39 @@
+---
+/**
+ * PageHeader — the page's title block. Always renders a semantic
+ * heading (h1 by default — every route needs exactly one) with an
+ * optional eyebrow and description.
+ *
+ * For section headings INSIDE a page keep using `SectionHeader`
+ * (layouts/), which defaults to h2/h3.
+ */
+
+interface Props {
+  eyebrow?: string;
+  title: string;
+  description?: string;
+  /** Escape hatch for embedded use; the default 1 is the point. */
+  level?: 1 | 2;
+  class?: string;
+}
+
+const { eyebrow, title, description, level = 1, class: className = "" } = Astro.props;
+const Heading = `h${level}` as "h1" | "h2";
+---
+
+<header class={`flex flex-col gap-1 ${className}`}>
+  {eyebrow && (
+    <span class="text-2xs font-medium uppercase tracking-wider text-muted-foreground">
+      {eyebrow}
+    </span>
+  )}
+  <Heading class="m-0 text-[1.875rem] font-semibold tracking-tight text-foreground sm:text-[2.125rem]">
+    {title}
+  </Heading>
+  {description && (
+    <p class="m-0 mt-1 max-w-[64ch] text-[0.9375rem] leading-relaxed text-muted-foreground">
+      {description}
+    </p>
+  )}
+  <slot />
+</header>

package/src/ui/SearchField.astro

@@ -0,0 +1,50 @@
+---
+/**
+ * SearchField — labeled search input with the leading glass icon.
+ *
+ * The label is visually hidden but always present; placeholder text
+ * is display copy, not the accessible name. Pass the derived
+ * placeholder from `getDirectoryIndexModel().searchPlaceholder` so it
+ * only names ENABLED facets.
+ */
+
+interface Props {
+  label: string;
+  name?: string;
+  id?: string;
+  value?: string;
+  placeholder?: string;
+  class?: string;
+}
+
+const {
+  label,
+  name = "q",
+  id = "search-input",
+  value = "",
+  placeholder,
+  class: className = "",
+} = Astro.props;
+---
+
+<label class={`relative block ${className}`}>
+  <span class="sr-only">{label}</span>
+  <svg
+    viewBox="0 0 16 16"
+    width="16"
+    height="16"
+    aria-hidden="true"
+    class="pointer-events-none absolute left-3 top-1/2 -translate-y-1/2 text-muted-foreground"
+    fill="currentColor"
+  >
+    <path d="M10.68 11.74a6 6 0 0 1-7.922-8.982 6 6 0 0 1 8.982 7.922l3.04 3.04a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215ZM11.5 7a4.5 4.5 0 1 0-9 0 4.5 4.5 0 0 0 9 0Z" />
+  </svg>
+  <input
+    id={id}
+    type="search"
+    name={name}
+    value={value}
+    placeholder={placeholder}
+    class="h-10 w-full rounded-md border border-input bg-background py-2 pl-9 pr-3 text-sm text-foreground placeholder:text-muted-foreground focus:border-ring focus:outline-none focus:ring-2 focus:ring-ring/20"
+  />
+</label>

package/src/ui/button.test.ts

@@ -0,0 +1,54 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { buttonClass, chipClass, filterTriggerClass, lensTabClass } from "./button.js";
+
+describe("button class builders", () => {
+  it("keeps selection state on the selected tokens, never the brand primary", () => {
+    for (const cls of [
+      buttonClass("selected"),
+      filterTriggerClass(true),
+      lensTabClass(true),
+    ]) {
+      expect(cls).toContain("bg-selected");
+      expect(cls).not.toContain("bg-primary");
+    }
+  });
+
+  it("uses the brand primary only for the primary variant", () => {
+    expect(buttonClass("primary")).toContain("bg-primary");
+    expect(buttonClass("secondary")).not.toContain("bg-primary");
+  });
+
+  it("guarantees a 44px mobile hit target on md and lg sizes", () => {
+    expect(buttonClass("secondary", "md")).toContain("max-sm:min-h-11");
+    expect(buttonClass("secondary", "lg")).toContain("h-11");
+    expect(filterTriggerClass(false)).toContain("max-sm:min-h-11");
+    expect(lensTabClass(false)).toContain("max-sm:min-h-11");
+  });
+
+  it("keeps the filter-trigger hook class through client reassignment", () => {
+    expect(filterTriggerClass(true)).toContain("grove-filter-trigger");
+    expect(filterTriggerClass(false)).toContain("grove-filter-trigger");
+  });
+
+  it("is the single source for chip classes on both server and client", () => {
+    // The browse page (server) and DirectoryIndexClient (client JS)
+    // must render byte-identical chips. Both now import chipClass —
+    // assert neither has regressed to an inline copy of the string.
+    const clientSource = readFileSync(
+      resolve(import.meta.dirname, "../components/DirectoryIndexClient.astro"),
+      "utf8",
+    );
+    const serverPage = readFileSync(
+      resolve(import.meta.dirname, "../../../../apps/example/src/pages/[slug]/index.astro"),
+      "utf8",
+    );
+    expect(clientSource).toContain("chipClass()");
+    expect(serverPage).toContain("chipClass()");
+    const inlineChip = "min-h-5 items-center justify-center gap-1 rounded-full";
+    expect(clientSource).not.toContain(inlineChip);
+    expect(serverPage).not.toContain(inlineChip);
+    expect(chipClass()).toContain(inlineChip);
+  });
+});

package/src/ui/button.ts

@@ -0,0 +1,98 @@
+/**
+ * Button / chip class builders — the single source for interactive
+ * control styling.
+ *
+ * Plain TS (not an .astro component) on purpose: `DirectoryIndexClient`
+ * rebuilds pagination links and active-filter chips in CLIENT-side JS,
+ * and those class strings must stay byte-identical with the server
+ * render. Both sides import these builders, so they cannot drift.
+ *
+ * Variant semantics (see styles.css):
+ * - `primary`   — the brand action (config `theme.primaryColor`).
+ * - `secondary` — default chrome buttons.
+ * - `outline` / `ghost` — quieter chrome.
+ * - `selected`  — "you are here" state (active filter, current lens,
+ *   current page). Neutral inversion via the `selected` tokens —
+ *   deliberately NOT the brand primary, so green never doubles as a
+ *   selection indicator.
+ */
+
+export type ButtonVariant = "primary" | "secondary" | "outline" | "ghost" | "selected";
+/** `bare` emits no size classes — pass custom geometry via `extra`. */
+export type ButtonSize = "sm" | "md" | "lg" | "bare";
+
+const BASE =
+  "inline-flex cursor-pointer items-center justify-center gap-1.5 rounded-[var(--radius)] border border-transparent font-medium leading-none no-underline outline-none transition-colors focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/35";
+
+/**
+ * `md`/`lg` guarantee a ≥44px hit target on small viewports
+ * (`max-sm:min-h-11`) while keeping the compact desktop height.
+ */
+const SIZES: Record<ButtonSize, string> = {
+  sm: "h-8 px-3 text-sm",
+  md: "h-9 px-3 text-sm max-sm:min-h-11",
+  lg: "h-11 px-4 text-sm",
+  bare: "",
+};
+
+const VARIANTS: Record<ButtonVariant, string> = {
+  primary: "bg-primary text-primary-foreground hover:bg-primary/90",
+  secondary: "border-border bg-secondary text-foreground hover:bg-accent",
+  outline: "border-border bg-transparent text-foreground hover:bg-accent",
+  ghost: "text-foreground hover:bg-accent",
+  selected: "bg-selected text-selected-foreground hover:bg-selected/90",
+};
+
+export function buttonClass(
+  variant: ButtonVariant = "secondary",
+  size: ButtonSize = "sm",
+  extra = "",
+): string {
+  return [BASE, SIZES[size], VARIANTS[variant], extra].filter(Boolean).join(" ");
+}
+
+/**
+ * Layout extras for pagination controls — shared by `Pagination.astro`
+ * and the client-side pagination rebuild in `DirectoryIndexClient`.
+ */
+export const PAGINATION_EXTRA = "min-w-9 px-2 py-1.5 text-2xs";
+
+/**
+ * Facet filter trigger (the "Stack: Any" dropdown buttons). Includes
+ * the `grove-filter-trigger` hook class because the client script
+ * reassigns the whole className when the active state changes — the
+ * hook must survive that reassignment.
+ */
+export function filterTriggerClass(active: boolean): string {
+  return [
+    "grove-filter-trigger",
+    BASE,
+    "h-9 px-3 text-[0.8125rem] max-sm:min-h-11",
+    active ? `${VARIANTS.selected} hover:text-selected-foreground` : VARIANTS.secondary,
+  ].join(" ");
+}
+
+/**
+ * Lens tab (the All / Hot / Mature row). Same geometry as the filter
+ * trigger; `data-lens-id` targeting keeps its own hook attribute.
+ */
+export function lensTabClass(active: boolean): string {
+  return [
+    BASE,
+    "h-9 px-3 text-[0.8125rem] max-sm:min-h-11",
+    active ? `${VARIANTS.selected} hover:text-selected-foreground` : VARIANTS.secondary,
+  ].join(" ");
+}
+
+/**
+ * Active-filter chip (the removable "Stack: Python ×" pills). One
+ * definition for the server render and the client rebuild.
+ */
+export function chipClass(extra = ""): string {
+  return [
+    "inline-flex min-h-5 items-center justify-center gap-1 rounded-full border border-transparent bg-secondary px-2 py-0.5 align-middle text-xs font-medium leading-none text-secondary-foreground transition-colors hover:border-ink-400",
+    extra,
+  ]
+    .filter(Boolean)
+    .join(" ");
+}