@dogsbay/docs-layout 0.2.0-beta.94 → 0.2.0-beta.95

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/docs-layout",
-  "version": "0.2.0-beta.94",
+  "version": "0.2.0-beta.95",
   "description": "Standard documentation layout components for Dogsbay",
   "type": "module",
   "exports": {
@@ -30,8 +30,8 @@
     "./json-ld": "./src/json-ld.ts"
   },
   "dependencies": {
-    "@dogsbay/primitives": "0.2.0-beta.94",
-    "@dogsbay/ui": "0.2.0-beta.94"
+    "@dogsbay/primitives": "0.2.0-beta.95",
+    "@dogsbay/ui": "0.2.0-beta.95"
   },
   "devDependencies": {
     "happy-dom": "^20.10.6",

package/src/BlogIndex.astro

@@ -14,6 +14,8 @@
  * 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;
@@ -78,65 +80,68 @@ const hrefForPage = (n: number): string => (n === 1 ? `${base}/` : `${base}/page
   <p class="text-muted-foreground">No posts yet.</p>
 )}
 
-<ul class="not-prose flex flex-col gap-8" data-blog-index>
+{/*
+  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="group">
-      <article class="flex flex-col gap-2">
-        {post.heroImage && (
-          <a href={post.url} tabindex="-1" aria-hidden="true">
-            {/*
-              aspect-boxed for the same reason as the post hero: an
-              unsized image in a list shifts every card below it.
-            */}
+    <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="mb-2 w-full rounded-lg border border-border object-cover aspect-[2/1]"
+              class="aspect-[16/9] w-full rounded-md border border-border object-cover"
               loading="lazy"
               decoding="async"
             />
-          </a>
-        )}
+          )}
 
-        <h2 class="text-xl font-semibold tracking-tight">
-          <a
-            href={post.url}
-            class="text-foreground no-underline hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm"
-          >
+          <h2 class="text-lg font-semibold leading-snug tracking-tight text-foreground group-hover:underline">
             {post.title}
-          </a>
-        </h2>
+          </h2>
 
-        {/*
-          Byline mirrors the post page's, minus the reading estimate's
-          separator noise. data-pagefind-ignore because 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-sm 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>}
           {/*
-            Guarded like the post page's byline. Unconditional, a post with
-            neither author nor date opened with a stray "· 5 min read", and
-            the card disagreed with the page it linked to.
+            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.
           */}
-          {(post.author?.length || post.date) && <span aria-hidden="true">&middot;</span>}
-          <span>{post.readingMinutes} min read</span>
-        </div>
+          <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="text-muted-foreground">{post.description}</p>
-        )}
-      </article>
+          {post.description && (
+            <p class="m-0 text-sm leading-relaxed text-muted-foreground">
+              {post.description}
+            </p>
+          )}
+        </Card>
+      </a>
     </li>
   ))}
 </ul>

package/src/DocsLayout.astro

@@ -432,6 +432,18 @@ interface Props {
   readingMinutes?: number;
   /** Optional hero image URL, rendered above the prose. */
   heroImage?: string;
+  /**
+   * Series position, when the post belongs to one. Derived at emit time
+   * from publication order, so "Part 3 of 7" cannot disagree with reality
+   * the way a hand-typed line does.
+   */
+  series?: {
+    name: string;
+    part: number;
+    total: number;
+    /** URL of part 1, so a reader landing mid-series can start over. */
+    startHref?: string;
+  };
   /**
    * Table-of-contents placement. Default `"top"`.
    * - `"top"` — expandable "On this page" disclosure at the top of the
@@ -521,6 +533,7 @@ const {
   updatedDate,
   readingMinutes,
   heroImage,
+  series,
   linkIcons,
   class: className,
 } = Astro.props;
@@ -1155,6 +1168,34 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                 </div>
               )}
 
+              {/*
+                Series banner. Sits above the byline because it is the
+                first thing a reader arriving from search needs: which
+                series is this, where am I in it, and where does it start.
+                A blog index is chronological, so someone can easily meet
+                part 7 first.
+              */}
+              {chrome === "blog" && series && (
+                <div
+                  class="not-prose mb-4 flex flex-wrap items-center gap-x-2 gap-y-1 rounded-md border border-border bg-muted/40 px-3 py-2 text-sm"
+                  data-post-series
+                  data-pagefind-ignore
+                >
+                  <span class="font-medium text-foreground">
+                    Part {series.part} of {series.total}
+                  </span>
+                  <span class="text-muted-foreground">in {series.name}</span>
+                  {series.startHref && series.part !== 1 && (
+                    <a
+                      href={series.startHref}
+                      class="ml-auto text-foreground underline underline-offset-2"
+                    >
+                      Start at part 1
+                    </a>
+                  )}
+                </div>
+              )}
+
               {autoLede && description && (
                 <p class="text-lg text-muted-foreground mb-6">
                   {description}