@dogsbay/docs-layout 0.2.0-beta.10 → 0.2.0-beta.100

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/docs-layout",
-  "version": "0.2.0-beta.10",
+  "version": "0.2.0-beta.100",
   "description": "Standard documentation layout components for Dogsbay",
   "type": "module",
   "exports": {
@@ -13,6 +13,7 @@
     "./TagList.astro": "./src/TagList.astro",
     "./StatusBadge.astro": "./src/StatusBadge.astro",
     "./TypeBadge.astro": "./src/TypeBadge.astro",
+    "./BlogIndex.astro": "./src/BlogIndex.astro",
     "./TaxonomyIndex.astro": "./src/TaxonomyIndex.astro",
     "./TaxonomyTerm.astro": "./src/TaxonomyTerm.astro",
     "./SearchDialog.astro": "./src/SearchDialog.astro",
@@ -29,14 +30,15 @@
     "./json-ld": "./src/json-ld.ts"
   },
   "dependencies": {
-    "@dogsbay/ui": "0.2.0-beta.10",
-    "@dogsbay/primitives": "0.2.0-beta.10"
+    "@dogsbay/primitives": "0.2.0-beta.100",
+    "@dogsbay/ui": "0.2.0-beta.100"
   },
   "devDependencies": {
-    "vitest": "^3.0.0"
+    "happy-dom": "^20.10.6",
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "astro": "^5.0.0 || ^6.0.0"
+    "astro": "^5.0.0 || ^6.0.0 || ^7.0.0"
   },
   "files": [
     "src",

package/src/BlogIndex.astro

@@ -0,0 +1,179 @@
+---
+/**
+ * BlogIndex — reverse-chronological list of posts.
+ *
+ * Reads the slice its route file hands it from `src/data/blog.json`
+ * (emitted by `format-astro/src/blog.ts` during `dogsbay site build`)
+ * and renders one card per post plus page navigation.
+ *
+ * All layout lives here rather than in the generated route files, so a
+ * design fix propagates on the next build instead of being baked into
+ * every emitted page — the same reason `TaxonomyIndex` exists.
+ *
+ * Uses the shared theme tokens only. The blog is the same site as the
+ * docs, so there is no blog palette, no blog typography scale, and no
+ * second set of card styles to keep in sync.
+ */
+import Card from "@dogsbay/ui/card/Card.astro";
+
+interface BlogPostRef {
+  slug: string;
+  title: string;
+  url: string;
+  description?: string;
+  date?: string;
+  author?: string[];
+  tags?: string[];
+  heroImage?: string;
+  readingMinutes: number;
+}
+
+interface Props {
+  /** The posts for THIS page of the index, newest first. */
+  posts: BlogPostRef[];
+  /** URL-form index path, already basePath-prefixed. */
+  indexPath: string;
+  pageNo: number;
+  totalPages: number;
+  /** Page heading. Defaults to "Blog", or "Blog — page N" beyond page 1. */
+  heading?: string;
+}
+
+const {
+  posts,
+  indexPath,
+  pageNo,
+  totalPages,
+  heading = pageNo === 1 ? "Blog" : `Blog — page ${pageNo}`,
+} = Astro.props;
+
+/** Build time, so every reader sees the same string. See DocsLayout. */
+function formatDate(iso: string): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  // timeZone: "UTC" is load-bearing. parseMeta normalizes `created:
+  // 2026-01-01` to "2026-01-01T00:00:00.000Z", so a build host in any
+  // negative-offset zone (the default on many CI runners) would render
+  // "31 December 2025". DocsFooter already carries this fix; these
+  // copies dropped it.
+  return d.toLocaleDateString("en-GB", {
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+    timeZone: "UTC",
+  });
+}
+
+const base = indexPath === "/" ? "" : indexPath.replace(/\/+$/, "");
+const hrefForPage = (n: number): string => (n === 1 ? `${base}/` : `${base}/page/${n}`);
+---
+
+{/*
+  The index needs its own <h1>. Post titles are <h2>, so without one the
+  page has an h2 with no h1 above it — a heading-order violation axe-core
+  flags, and a missing page heading for anyone navigating by headings.
+  The sticky header's site name is chrome, not a page heading.
+*/}
+<h1 class="text-3xl font-bold tracking-tight mb-8">{heading}</h1>
+
+{posts.length === 0 && (
+  <p class="text-muted-foreground">No posts yet.</p>
+)}
+
+{/*
+  Three across at lg, two at sm, one on mobile. The card is one link, not
+  a card containing links: nesting interactive elements inside a clickable
+  card is the classic keyboard-and-screen-reader trap, so tags and other
+  links stay off the card and live on the post page instead.
+
+  `items-stretch` + `h-full` keeps a short post's card the same height as
+  a long one's — ragged card bottoms are the thing that makes a grid look
+  broken rather than sparse.
+*/}
+<ul
+  class="not-prose grid list-none grid-cols-1 items-stretch gap-6 p-0 sm:grid-cols-2 lg:grid-cols-3"
+  data-blog-index
+>
+  {posts.map((post) => (
+    <li class="m-0 p-0">
+      <a
+        href={post.url}
+        class="group block h-full rounded-lg no-underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+      >
+        <Card class="flex h-full flex-col gap-3 p-5 transition-colors group-hover:border-ring">
+          {post.heroImage && (
+            <img
+              src={post.heroImage}
+              alt=""
+              class="aspect-[16/9] w-full rounded-md border border-border object-cover"
+              loading="lazy"
+              decoding="async"
+            />
+          )}
+
+          <h2 class="text-lg font-semibold leading-snug tracking-tight text-foreground group-hover:underline">
+            {post.title}
+          </h2>
+
+          {/*
+            data-pagefind-ignore: the same values are indexed as structured
+            filters on the post itself. Without it every card's date leads
+            its search excerpt.
+          */}
+          <div
+            class="flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-muted-foreground"
+            data-pagefind-ignore
+          >
+            {post.author && post.author.length > 0 && (
+              <span class="font-medium text-foreground">{post.author.join(", ")}</span>
+            )}
+            {post.author && post.author.length > 0 && post.date && (
+              <span aria-hidden="true">&middot;</span>
+            )}
+            {post.date && <time datetime={post.date}>{formatDate(post.date)}</time>}
+            {(post.author?.length || post.date) && <span aria-hidden="true">&middot;</span>}
+            <span>{post.readingMinutes} min read</span>
+          </div>
+
+          {post.description && (
+            <p class="m-0 text-sm leading-relaxed text-muted-foreground">
+              {post.description}
+            </p>
+          )}
+        </Card>
+      </a>
+    </li>
+  ))}
+</ul>
+
+{totalPages > 1 && (
+  <nav class="not-prose mt-12 flex items-center justify-between" aria-label="Blog pages">
+    {pageNo > 1 ? (
+      <a
+        href={hrefForPage(pageNo - 1)}
+        class="text-sm text-foreground no-underline hover:underline"
+        rel="prev"
+      >
+        &larr; Newer posts
+      </a>
+    ) : (
+      <span></span>
+    )}
+
+    <span class="text-sm text-muted-foreground">
+      Page {pageNo} of {totalPages}
+    </span>
+
+    {pageNo < totalPages ? (
+      <a
+        href={hrefForPage(pageNo + 1)}
+        class="text-sm text-foreground no-underline hover:underline"
+        rel="next"
+      >
+        Older posts &rarr;
+      </a>
+    ) : (
+      <span></span>
+    )}
+  </nav>
+)}

package/src/DocsFooter.astro

@@ -14,6 +14,14 @@ interface Props {
   lastUpdated?: string;
   prev?: PaginationLink;
   next?: PaginationLink;
+  /**
+   * Captions above the prev/next titles. Default "Previous" / "Next",
+   * which is right for docs, where adjacency is position in the sidebar.
+   * A blog's adjacency is TIME, so it passes "Newer" / "Older" — the
+   * link means something different there and the label should say so.
+   */
+  prevLabel?: string;
+  nextLabel?: string;
   copyright?: string;
   /**
    * When true, render a low-key footer link to `/llms.txt` so
@@ -32,11 +40,27 @@ const {
   lastUpdated,
   prev,
   next,
+  prevLabel = "Previous",
+  nextLabel = "Next",
   copyright,
   llmsLink = false,
   llmsLinkHref = "/llms.txt",
   class: className,
 } = Astro.props;
+
+// `lastUpdated` is a canonical ISO string (e.g. "2026-06-16T00:00:00.000Z").
+// Render it as a clean, locale-stable date; UTC avoids an off-by-one when the
+// build host isn't on UTC. Non-date strings (e.g. a version/tag) pass through.
+function formatDate(value: string): string {
+  const d = new Date(value);
+  if (Number.isNaN(d.getTime())) return value;
+  return d.toLocaleDateString("en-US", {
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+    timeZone: "UTC",
+  });
+}
 ---
 
 <footer class:list={["mt-12 border-t pt-6", className]}>
@@ -49,7 +73,7 @@ const {
           Edit this page
         </a>
       )}
-      {lastUpdated && <span>Last updated: {lastUpdated}</span>}
+      {lastUpdated && <span>Last updated: {formatDate(lastUpdated)}</span>}
     </div>
   )}
 
@@ -60,7 +84,7 @@ const {
         <a href={prev.href} class="inline-flex items-center gap-2 rounded-md border px-4 py-2 text-sm font-medium transition-colors hover:bg-accent" rel="prev">
           <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="15 18 9 12 15 6"/></svg>
           <div class="text-left">
-            <div class="text-xs text-muted-foreground">Previous</div>
+            <div class="text-xs text-muted-foreground">{prevLabel}</div>
             <div>{prev.label}</div>
           </div>
         </a>
@@ -68,7 +92,7 @@ const {
       {next ? (
         <a href={next.href} class="inline-flex items-center gap-2 rounded-md border px-4 py-2 text-sm font-medium transition-colors hover:bg-accent" rel="next">
           <div class="text-right">
-            <div class="text-xs text-muted-foreground">Next</div>
+            <div class="text-xs text-muted-foreground">{nextLabel}</div>
             <div>{next.label}</div>
           </div>
           <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 18 15 12 9 6"/></svg>