@thewhatmatters/wmds 0.4.6 → 0.4.8

package/docs/patterns/guides-post-page--post-page.tsx

@@ -1,4 +1,4 @@
-// @thewhatmatters/wmds@0.4.6 · Pattern — post page
+// @thewhatmatters/wmds@0.4.8 · Pattern — post page
 // Storybook: Guides/Post page → Pattern — post page (?path=/story/guides-post-page--post-page)
 // Show code — copy verbatim and keep this header; upgrades find pasted patterns by it.
 
@@ -77,6 +77,9 @@ function CopyButton({ text, label }: { text: string; label: string }) {
 /** Where the metadata panel sits from lg: before the article (start) or after it (end). */
 export type PostMetadataSide = "start" | "end";
 
+/** Where the panel sits below lg, where it stacks: before the article or after it (default). */
+export type PostMetadataStack = "before" | "after";
+
 /** How many of the page's 12 columns the panel takes from lg; the article takes the rest. */
 export type PostMetadataColumns = 3 | 4;
 
@@ -94,84 +97,125 @@ export interface PostPageProps {
   post: PostPageData;
   /** The post's rendered markdown. */
   children: ReactNode;
-  /** Where the panel sits from lg. Below lg it stacks above the article either way. Default: "start". */
+  /** Where the panel sits from lg, beside the article. Default: "start". */
   metadataSide?: PostMetadataSide;
   /** The panel's width from lg, in columns. Default: 4. */
   metadataColumns?: PostMetadataColumns;
+  /**
+   * Where the panel sits below lg, where it stacks. "after" (default) puts the article first, with
+   * the date and reading time in a line under the title. It is also the panel's place in reading
+   * and tab order at every width, so pair "after" with metadataSide="end" and "before" with "start".
+   */
+  metadataStack?: PostMetadataStack;
+  /** Page-level layers inside the page grid — for example a GridOverlay. */
+  overlay?: ReactNode;
 }
 
 /** A blog post: the title, a metadata panel, and the article, which is the rendered markdown. */
-export function PostPage({ post, children, metadataSide = "start", metadataColumns = 4 }: PostPageProps) {
+export function PostPage({
+  post,
+  children,
+  metadataSide = "start",
+  metadataColumns = 4,
+  metadataStack = "after",
+  overlay,
+}: PostPageProps) {
   const metadataHeadingId = useId();
   const encodedUrl = encodeURIComponent(post.url);
   const encodedTitle = encodeURIComponent(post.title);
+  const stackedAfter = metadataStack === "after";
+  // From lg the panel's side wins; the order utility moves it only when its side and its place
+  // in the markup disagree.
+  const panelOrder =
+    metadataSide === "end" && !stackedAfter ? " lg:order-last" : metadataSide === "start" && stackedAfter ? " lg:order-1" : "";
+  const articleOrder = metadataSide === "start" && stackedAfter ? " lg:order-2" : "";
+
+  const panel = (
+    <aside
+      aria-labelledby={metadataHeadingId}
+      className={
+        "col-span-full lg:sticky lg:top-[calc(var(--site-nav-height)+1rem)] lg:mt-0 " +
+        (stackedAfter ? "mt-10 " : "") +
+        metadataColumnClasses[metadataColumns] +
+        panelOrder
+      }
+    >
+      <SectionCaption id={metadataHeadingId}>Metadata</SectionCaption>
+      <DescriptionList variant="mono" rule="dotted">
+        <DescriptionList.Item name="Date">
+          <time dateTime={post.date}>{post.dateLabel}</time>
+        </DescriptionList.Item>
+        <DescriptionList.Item name="Author">
+          <Badge emphasis="outline" mono>
+            {post.author}
+          </Badge>
+        </DescriptionList.Item>
+        <DescriptionList.Item name="Reading time">{post.readingTime}</DescriptionList.Item>
+        <DescriptionList.Item name="Categories">
+          {post.categories.map((category) => (
+            <Badge key={category.href} emphasis="outline" mono render={<a href={category.href} />}>
+              {category.label}
+            </Badge>
+          ))}
+        </DescriptionList.Item>
+        <DescriptionList.Item name="Agents" layout="stacked">
+          <CopyButton text={post.markdown} label="Copy for LLM" />
+          <Button role="secondary" size="sm" icon={<FileText />} render={<a href={post.markdownHref} />}>
+            View as Markdown
+          </Button>
+        </DescriptionList.Item>
+        <DescriptionList.Item name="Share" layout="stacked">
+          <Button
+            role="secondary"
+            size="sm"
+            external
+            render={<a href={"https://x.com/intent/post?url=" + encodedUrl + "&text=" + encodedTitle} />}
+          >
+            Twitter/X
+          </Button>
+          <Button
+            role="secondary"
+            size="sm"
+            external
+            render={<a href={"https://www.linkedin.com/sharing/share-offsite/?url=" + encodedUrl} />}
+          >
+            LinkedIn
+          </Button>
+        </DescriptionList.Item>
+      </DescriptionList>
+    </aside>
+  );
 
   return (
     <main className="grid-page bg-body">
+      {overlay}
       <article className="band py-6 sm:py-10 lg:py-14">
         <header className="col-span-full mb-4 flex flex-col gap-3 sm:mb-8 lg:col-span-10">
           <Breadcrumb items={post.breadcrumb} variant="mono" separator="slash" className="mb-3" />
           <h1 className="type-display-2 text-balance text-fg">{post.title}</h1>
           <p className="type-reading max-w-[40rem] text-muted">{post.description}</p>
+          {stackedAfter ? (
+            <p className="type-eyebrow text-muted lg:hidden">
+              <time dateTime={post.date}>{post.dateLabel}</time>
+              <span aria-hidden="true"> / </span>
+              <span className="sr-only">, </span>
+              {post.readingTime} read
+            </p>
+          ) : null}
         </header>
 
-        <aside
-          aria-labelledby={metadataHeadingId}
+        {stackedAfter ? null : panel}
+
+        <div
           className={
-            "col-span-full lg:sticky lg:top-[calc(var(--site-nav-height)+1rem)] " +
-            metadataColumnClasses[metadataColumns] +
-            (metadataSide === "end" ? " lg:order-last" : "")
+            "col-span-full lg:mt-0 " + (stackedAfter ? "" : "mt-6 ") + articleColumnClasses[metadataColumns] + articleOrder
           }
         >
-          <SectionCaption id={metadataHeadingId}>Metadata</SectionCaption>
-          <DescriptionList variant="mono" rule="dotted">
-            <DescriptionList.Item name="Date">
-              <time dateTime={post.date}>{post.dateLabel}</time>
-            </DescriptionList.Item>
-            <DescriptionList.Item name="Author">
-              <Badge emphasis="outline" mono>
-                {post.author}
-              </Badge>
-            </DescriptionList.Item>
-            <DescriptionList.Item name="Reading time">{post.readingTime}</DescriptionList.Item>
-            <DescriptionList.Item name="Categories">
-              {post.categories.map((category) => (
-                <Badge key={category.href} emphasis="outline" mono render={<a href={category.href} />}>
-                  {category.label}
-                </Badge>
-              ))}
-            </DescriptionList.Item>
-            <DescriptionList.Item name="Agents" layout="stacked">
-              <CopyButton text={post.markdown} label="Copy for LLM" />
-              <Button role="secondary" size="sm" icon={<FileText />} render={<a href={post.markdownHref} />}>
-                View as Markdown
-              </Button>
-            </DescriptionList.Item>
-            <DescriptionList.Item name="Share" layout="stacked">
-              <Button
-                role="secondary"
-                size="sm"
-                external
-                render={<a href={"https://x.com/intent/post?url=" + encodedUrl + "&text=" + encodedTitle} />}
-              >
-                Twitter/X
-              </Button>
-              <Button
-                role="secondary"
-                size="sm"
-                external
-                render={<a href={"https://www.linkedin.com/sharing/share-offsite/?url=" + encodedUrl} />}
-              >
-                LinkedIn
-              </Button>
-            </DescriptionList.Item>
-          </DescriptionList>
-        </aside>
-
-        <div className={"col-span-full mt-6 lg:mt-0 " + articleColumnClasses[metadataColumns]}>
           <SectionCaption as="p">Article</SectionCaption>
           <Prose className="mt-6">{children}</Prose>
         </div>
+
+        {stackedAfter ? panel : null}
       </article>
     </main>
   );

package/docs/patterns/guides-profile-typography--editorial-profile.tsx

@@ -1,4 +1,4 @@
-// @thewhatmatters/wmds@0.4.6 · Pattern — editorial profile
+// @thewhatmatters/wmds@0.4.8 · Pattern — editorial profile
 // Storybook: Guides/Profile typography → Pattern — editorial profile (?path=/story/guides-profile-typography--editorial-profile)
 // Show code — copy verbatim and keep this header; upgrades find pasted patterns by it.
 

package/docs/patterns/guides-resource-detail--detail.tsx

@@ -0,0 +1,261 @@
+// @thewhatmatters/wmds@0.4.8 · Pattern — resource detail
+// Storybook: Guides/Resource detail → Pattern — resource detail (?path=/story/guides-resource-detail--detail)
+// Show code — copy verbatim and keep this header; upgrades find pasted patterns by it.
+
+import { useEffect, useId, type ReactNode } from "react";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import {
+  Badge,
+  Breadcrumb,
+  Button,
+  DescriptionList,
+  Dialog,
+  IconButton,
+  type BreadcrumbItemDef,
+} from "@thewhatmatters/wmds";
+
+export interface ResourceImage {
+  src: string;
+  alt: string;
+  /** The image's own size, in px. */
+  width: number;
+  height: number;
+}
+
+export interface ResourceVideo {
+  src: string;
+  /** The frame shown before the video plays. */
+  poster: string;
+  /** A WebVTT captions file, when the video has speech. */
+  captions?: string;
+}
+
+export interface ResourceDetailItem {
+  id: string;
+  title: string;
+  /** The preview. Shown unless there is a video. */
+  image: ResourceImage;
+  /** One video, with controls. It does not play by itself. */
+  video?: ResourceVideo;
+  /** The eyebrow over the title and the Category row, for example "Tools". */
+  category: string;
+  tags?: string[];
+  /** Where the resource lives, for example the domain — the Source row and the Visit button. */
+  meta?: string;
+  /** The curator's note: one or two sentences. */
+  note: string;
+  /** ISO date the resource was added, for the time element. */
+  added: string;
+  /** The date as readers see it, for example "Sep 14, 2026". */
+  addedLabel: string;
+  /** The resource itself, on its own site. */
+  visitHref: string;
+  /** More metadata rows, after Source. */
+  rows?: { name: string; value: string }[];
+}
+
+/** The media well: one image or one video, whole, on the page floor. */
+const mediaClasses =
+  "flex items-center justify-center overflow-hidden rounded-[var(--radius-card-body)] border border-border bg-muted-surface [&>img]:block [&>img]:h-auto [&>img]:w-full [&>video]:block [&>video]:h-auto [&>video]:w-full";
+
+/** Over the grid, from md: the well takes the height the window allows and the media fits inside it. */
+const mediaFillClasses =
+  "md:h-full md:min-h-0 md:[&>img]:max-h-full md:[&>img]:w-auto md:[&>img]:max-w-full md:[&>img]:object-contain md:[&>video]:max-h-full md:[&>video]:w-auto md:[&>video]:max-w-full";
+
+function ResourceMedia({
+  item,
+  fill = false,
+  renderImage,
+}: {
+  item: ResourceDetailItem;
+  fill?: boolean;
+  renderImage?: (image: ResourceImage) => ReactNode;
+}) {
+  return (
+    <div className={fill ? mediaClasses + " " + mediaFillClasses : mediaClasses}>
+      {item.video != null ? (
+        <video key={item.video.src} controls playsInline preload="metadata" poster={item.video.poster}>
+          <source src={item.video.src} />
+          {item.video.captions != null ? (
+            <track kind="captions" src={item.video.captions} srcLang="en" label="English" default />
+          ) : null}
+        </video>
+      ) : renderImage != null ? (
+        renderImage(item.image)
+      ) : (
+        <img src={item.image.src} alt={item.image.alt} width={item.image.width} height={item.image.height} />
+      )}
+    </div>
+  );
+}
+
+function ResourceInfo({
+  item,
+  headingId,
+  titleAs: Title,
+}: {
+  item: ResourceDetailItem;
+  headingId: string;
+  titleAs: "h1" | "h2";
+}) {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <p className="type-eyebrow text-muted">{item.category}</p>
+        <Title id={headingId} className="type-heading-1 text-balance text-fg">
+          {item.title}
+        </Title>
+        <p className="type-reading text-fg">{item.note}</p>
+        <p className="type-supporting text-muted">
+          Added <time dateTime={item.added}>{item.addedLabel}</time>
+        </p>
+      </div>
+      <DescriptionList variant="mono" rule="dotted" aria-label="Details">
+        <DescriptionList.Item name="Category">{item.category}</DescriptionList.Item>
+        {item.tags != null && item.tags.length > 0 ? (
+          <DescriptionList.Item name="Tags">
+            {item.tags.map((tag) => (
+              <Badge key={tag} emphasis="outline" mono>
+                {tag}
+              </Badge>
+            ))}
+          </DescriptionList.Item>
+        ) : null}
+        {item.meta != null ? <DescriptionList.Item name="Source">{item.meta}</DescriptionList.Item> : null}
+        {item.rows?.map((row) => (
+          <DescriptionList.Item key={row.name} name={row.name}>
+            {row.value}
+          </DescriptionList.Item>
+        ))}
+      </DescriptionList>
+    </div>
+  );
+}
+
+function VisitButton({ item }: { item: ResourceDetailItem }) {
+  return (
+    <Button role="primary" external render={<a href={item.visitHref} />}>
+      Visit {item.meta ?? "resource"}
+    </Button>
+  );
+}
+
+export interface ResourceDetailDialogProps {
+  item: ResourceDetailItem;
+  open: boolean;
+  /** Close, the scrim, and Escape. Go back to the grid's route here. */
+  onClose: () => void;
+  /** Go to the resource before this one. Leave it out on the first: the control is off. */
+  onPrevious?: () => void;
+  /** Go to the resource after this one. Leave it out on the last. */
+  onNext?: () => void;
+  /** Where this resource is in the list, for example "3 of 9". */
+  position?: string;
+  /** The app's image component, in place of img — (image) => <Image {...image} sizes="…" />. */
+  renderImage?: (image: ResourceImage) => ReactNode;
+}
+
+/** The detail over the grid: the page behind is dimmed and does not scroll. */
+export function ResourceDetailDialog({
+  item,
+  open,
+  onClose,
+  onPrevious,
+  onNext,
+  position,
+  renderImage,
+}: ResourceDetailDialogProps) {
+  const headingId = useId();
+
+  // Left and Right move between resources — except in the video, where they seek.
+  useEffect(() => {
+    if (!open) return;
+    function onKeyDown(event: KeyboardEvent) {
+      if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
+      if (event.target instanceof HTMLVideoElement) return;
+      if (event.key === "ArrowLeft" && onPrevious != null) {
+        event.preventDefault();
+        onPrevious();
+      } else if (event.key === "ArrowRight" && onNext != null) {
+        event.preventDefault();
+        onNext();
+      }
+    }
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [open, onPrevious, onNext]);
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => {
+        if (!next) onClose();
+      }}
+    >
+      <Dialog.Content
+        size="full"
+        aria-labelledby={headingId}
+        headerStart={position != null ? <span className="type-supporting tabular-nums">{position}</span> : undefined}
+        headerEnd={
+          <>
+            <IconButton
+              size="sm"
+              role="ghost"
+              icon={<ChevronLeft />}
+              aria-label="Previous resource"
+              disabled={onPrevious == null}
+              onClick={onPrevious}
+            />
+            <IconButton
+              size="sm"
+              role="ghost"
+              icon={<ChevronRight />}
+              aria-label="Next resource"
+              disabled={onNext == null}
+              onClick={onNext}
+            />
+          </>
+        }
+        footer={<VisitButton item={item} />}
+      >
+        <div className="grid gap-6 md:h-full md:grid-cols-[minmax(0,1fr)_20rem] lg:grid-cols-[minmax(0,1fr)_24rem]">
+          <ResourceMedia item={item} fill renderImage={renderImage} />
+          <div className="md:min-h-0 md:overflow-y-auto">
+            <ResourceInfo item={item} headingId={headingId} titleAs="h2" />
+          </div>
+        </div>
+      </Dialog.Content>
+    </Dialog>
+  );
+}
+
+export interface ResourceDetailPageProps {
+  item: ResourceDetailItem;
+  /** The path to this resource, ending with it — Home, Resources, this resource. */
+  breadcrumb: BreadcrumbItemDef[];
+  /** The app's image component, in place of img — (image) => <Image {...image} sizes="…" />. */
+  renderImage?: (image: ResourceImage) => ReactNode;
+  /** Page-level layers inside the page grid — for example a GridOverlay. */
+  overlay?: ReactNode;
+}
+
+/** The detail as its own page: opened directly, or from a shared link. */
+export function ResourceDetailPage({ item, breadcrumb, renderImage, overlay }: ResourceDetailPageProps) {
+  const headingId = useId();
+
+  return (
+    <main className="grid-page bg-body">
+      {overlay}
+      <article aria-labelledby={headingId} className="band py-6 sm:py-10 lg:py-14">
+        <Breadcrumb items={breadcrumb} variant="mono" separator="slash" className="col-span-full mb-6" />
+        <div className="col-span-full lg:col-span-8">
+          <ResourceMedia item={item} renderImage={renderImage} />
+        </div>
+        <div className="col-span-full mt-6 flex flex-col items-start gap-6 lg:col-span-4 lg:mt-0">
+          <ResourceInfo item={item} headingId={headingId} titleAs="h1" />
+          <VisitButton item={item} />
+        </div>
+      </article>
+    </main>
+  );
+}

package/docs/patterns/index.json

@@ -1,6 +1,6 @@
 {
   "package": "@thewhatmatters/wmds",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "patterns": [
     {
       "id": "components-accordion--flush",
@@ -242,6 +242,14 @@
       "storybook": "?path=/story/components-card-selectablecard--selectable-cards-pattern",
       "source": "src/components/molecules/SelectableCard/SelectableCard.stories.tsx"
     },
+    {
+      "id": "components-carousel--image-carousel",
+      "title": "Components/Carousel",
+      "name": "Pattern — image carousel",
+      "file": "patterns/components-carousel--image-carousel.tsx",
+      "storybook": "?path=/story/components-carousel--image-carousel",
+      "source": "src/components/organisms/Carousel/Carousel.stories.tsx"
+    },
     {
       "id": "components-chart--audience-activity-heatmap",
       "title": "Components/Chart",
@@ -434,6 +442,14 @@
       "storybook": "?path=/story/components-field--multi-control",
       "source": "src/components/molecules/Field/Field.stories.tsx"
     },
+    {
+      "id": "components-filterpanel--panel",
+      "title": "Components/FilterPanel",
+      "name": "Pattern — filter panel",
+      "file": "patterns/components-filterpanel--panel.tsx",
+      "storybook": "?path=/story/components-filterpanel--panel",
+      "source": "src/components/organisms/FilterPanel/FilterPanel.stories.tsx"
+    },
     {
       "id": "components-footerreveal--marketing-hero-pattern",
       "title": "Components/FooterReveal",
@@ -586,6 +602,22 @@
       "storybook": "?path=/story/components-kbd--shortcut",
       "source": "src/components/atoms/Kbd/Kbd.stories.tsx"
     },
+    {
+      "id": "components-linktile--resource-tile",
+      "title": "Components/LinkTile",
+      "name": "Pattern — resource tile",
+      "file": "patterns/components-linktile--resource-tile.tsx",
+      "storybook": "?path=/story/components-linktile--resource-tile",
+      "source": "src/components/molecules/LinkTile/LinkTile.stories.tsx"
+    },
+    {
+      "id": "components-linktile--router-link",
+      "title": "Components/LinkTile",
+      "name": "Pattern — router link",
+      "file": "patterns/components-linktile--router-link.tsx",
+      "storybook": "?path=/story/components-linktile--router-link",
+      "source": "src/components/molecules/LinkTile/LinkTile.stories.tsx"
+    },
     {
       "id": "components-moremenu--action-menu",
       "title": "Components/MoreMenu",
@@ -914,6 +946,14 @@
       "storybook": "?path=/story/components-textsequence--shapes",
       "source": "src/components/molecules/TextSequence/TextSequence.stories.tsx"
     },
+    {
+      "id": "components-tilegrid--masonry",
+      "title": "Components/TileGrid",
+      "name": "Pattern — tile grid",
+      "file": "patterns/components-tilegrid--masonry.tsx",
+      "storybook": "?path=/story/components-tilegrid--masonry",
+      "source": "src/components/molecules/TileGrid/TileGrid.stories.tsx"
+    },
     {
       "id": "components-toast--stacked-notifications",
       "title": "Components/Toast",
@@ -986,6 +1026,14 @@
       "storybook": "?path=/story/guides-chart-explorations--comparison-gallery",
       "source": "src/guides/ChartExplorations/ChartExplorations.stories.tsx"
     },
+    {
+      "id": "guides-filter-panel--filtered-grid",
+      "title": "Guides/Filter panel",
+      "name": "Pattern — filtered grid",
+      "file": "patterns/guides-filter-panel--filtered-grid.tsx",
+      "storybook": "?path=/story/guides-filter-panel--filtered-grid",
+      "source": "src/guides/FilterPanel/FilterPanel.stories.tsx"
+    },
     {
       "id": "guides-filter-panel--filtered-index",
       "title": "Guides/Filter panel",
@@ -1017,6 +1065,14 @@
       "file": "patterns/guides-profile-typography--editorial-profile.tsx",
       "storybook": "?path=/story/guides-profile-typography--editorial-profile",
       "source": "src/guides/ProfileTypography/ProfileTypography.stories.tsx"
+    },
+    {
+      "id": "guides-resource-detail--detail",
+      "title": "Guides/Resource detail",
+      "name": "Pattern — resource detail",
+      "file": "patterns/guides-resource-detail--detail.tsx",
+      "storybook": "?path=/story/guides-resource-detail--detail",
+      "source": "src/guides/ResourceDetail/ResourceDetail.stories.tsx"
     }
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thewhatmatters/wmds",
   "description": "WhatMatters Design System — React components, Tailwind v4 theme, and Storybook patterns",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "type": "module",
   "license": "MIT",
   "repository": {