@thewhatmatters/wmds 0.4.0 → 0.4.1

package/docs/patterns/guides-filter-panel--filtered-index.tsx

@@ -0,0 +1,174 @@
+// @thewhatmatters/wmds@0.4.1 · Pattern — filtered index
+// Storybook: Guides/Filter panel → Pattern — filtered index (?path=/story/guides-filter-panel--filtered-index)
+// Show code — copy verbatim and keep this header; upgrades find pasted patterns by it.
+
+import { useId, useState } from "react";
+import { SlidersHorizontal } from "lucide-react";
+import { Accordion, Button, CheckboxGroup, IndexList, SectionCaption, Sheet } from "@thewhatmatters/wmds";
+
+export interface FilterGroupDef {
+  id: string;
+  label: string;
+  options: { value: string; label: string }[];
+}
+
+export interface FilteredPost {
+  slug: string;
+  title: string;
+  href: string;
+  /** ISO date, for the time element. */
+  date: string;
+  /** The date as readers see it, for example "Sep 14, 2026". */
+  dateLabel: string;
+  description: string;
+  /** The post's option in each filter group, by group id — for example { topic: "guides" }. */
+  facets: Record<string, string>;
+}
+
+type Selection = Record<string, string[]>;
+
+function postsLabel(count: number) {
+  return count === 1 ? "1 post" : `${count} posts`;
+}
+
+function matches(post: FilteredPost, groups: FilterGroupDef[], selection: Selection) {
+  return groups.every((group) => {
+    const values = selection[group.id] ?? [];
+    return values.length === 0 || values.includes(post.facets[group.id] ?? "");
+  });
+}
+
+function FilterGroups({
+  groups,
+  posts,
+  selection,
+  onGroupChange,
+}: {
+  groups: FilterGroupDef[];
+  posts: FilteredPost[];
+  selection: Selection;
+  onGroupChange: (groupId: string, values: string[]) => void;
+}) {
+  return (
+    <Accordion variant="plain" flush>
+      {groups.map((group) => (
+        <Accordion.Item key={group.id} label={group.label} defaultOpen>
+          <CheckboxGroup
+            label={group.label}
+            labelHidden
+            size="sm"
+            values={selection[group.id] ?? []}
+            onValuesChange={(values) => onGroupChange(group.id, values)}
+          >
+            {group.options.map((option) => {
+              const count = posts.filter((post) => post.facets[group.id] === option.value).length;
+              return (
+                <CheckboxGroup.Item
+                  key={option.value}
+                  value={option.value}
+                  label={option.label}
+                  count={count}
+                  countLabel={postsLabel(count)}
+                />
+              );
+            })}
+          </CheckboxGroup>
+        </Accordion.Item>
+      ))}
+    </Accordion>
+  );
+}
+
+export function FilteredIndex({
+  title,
+  posts,
+  groups,
+}: {
+  title: string;
+  posts: FilteredPost[];
+  groups: FilterGroupDef[];
+}) {
+  const filtersHeadingId = useId();
+  const [selection, setSelection] = useState<Selection>({});
+  const [sheetOpen, setSheetOpen] = useState(false);
+  const activeCount = Object.values(selection).reduce((total, values) => total + values.length, 0);
+  const shown = posts.filter((post) => matches(post, groups, selection));
+
+  function setGroup(groupId: string, values: string[]) {
+    setSelection((current) => ({ ...current, [groupId]: values }));
+  }
+
+  return (
+    <main className="grid-page bg-body">
+      <div className="band py-6 sm:py-10 lg:py-14">
+        <header className="col-span-full mb-4 flex items-end justify-between gap-4 sm:mb-8">
+          <h1 className="type-display-2 text-fg">
+            {title} <span className="tabular-nums text-muted">{shown.length}</span>
+          </h1>
+          <Button
+            role="secondary"
+            icon={<SlidersHorizontal />}
+            count={activeCount > 0 ? activeCount : undefined}
+            className="md:hidden"
+            onClick={() => setSheetOpen(true)}
+          >
+            Filters
+          </Button>
+        </header>
+        <p role="status" className="sr-only">
+          {postsLabel(shown.length)}
+        </p>
+
+        <aside aria-labelledby={filtersHeadingId} className="hidden md:col-span-3 md:block">
+          <SectionCaption
+            id={filtersHeadingId}
+            end={
+              <Button role="ghost" size="xs" disabled={activeCount === 0} onClick={() => setSelection({})}>
+                Clear all
+              </Button>
+            }
+          >
+            Filters
+          </SectionCaption>
+          <FilterGroups groups={groups} posts={posts} selection={selection} onGroupChange={setGroup} />
+        </aside>
+
+        <div className="col-span-full md:col-span-5 lg:col-span-9">
+          <IndexList
+            aria-label="Posts"
+            captions={{ meta: "Date", title: "Name" }}
+            empty={<p className="type-body text-muted">No posts match these filters.</p>}
+          >
+            {shown.map((post) => (
+              <IndexList.Item
+                key={post.slug}
+                title={post.title}
+                href={post.href}
+                meta={<time dateTime={post.date}>{post.dateLabel}</time>}
+                preview={<p>{post.description}</p>}
+              />
+            ))}
+          </IndexList>
+        </div>
+      </div>
+
+      <Sheet open={sheetOpen} onOpenChange={setSheetOpen}>
+        <Sheet.Content
+          title="Filters"
+          footer={
+            <div className="flex items-center justify-end gap-2">
+              <Button role="secondary" size="sm" disabled={activeCount === 0} onClick={() => setSelection({})}>
+                Clear all
+              </Button>
+              <Button role="primary" size="sm" onClick={() => setSheetOpen(false)}>
+                Show {postsLabel(shown.length)}
+              </Button>
+            </div>
+          }
+        >
+          <FilterGroups groups={groups} posts={posts} selection={selection} onGroupChange={setGroup} />
+        </Sheet.Content>
+      </Sheet>
+    </main>
+  );
+}

package/docs/patterns/guides-overlay-flows--notification-preferences.tsx

@@ -1,4 +1,4 @@
-// @thewhatmatters/wmds@0.4.0 · Pattern — notification preferences
+// @thewhatmatters/wmds@0.4.1 · Pattern — notification preferences
 // Storybook: Guides/Overlay flows → Pattern — notification preferences (?path=/story/guides-overlay-flows--notification-preferences)
 // Show code — copy verbatim and keep this header; upgrades find pasted patterns by it.
 

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

@@ -0,0 +1,143 @@
+// @thewhatmatters/wmds@0.4.1 · 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.
+
+import { useEffect, useId, useState, type ReactNode } from "react";
+import { Copy, FileText } from "lucide-react";
+import {
+  Badge,
+  Button,
+  DescriptionList,
+  Prose,
+  SectionCaption,
+  buttonStatusHoldMs,
+  type ButtonStatus,
+} from "@thewhatmatters/wmds";
+
+export interface PostCategory {
+  label: string;
+  href: string;
+}
+
+export interface PostPageData {
+  title: string;
+  description: string;
+  /** ISO date, for the time element. */
+  date: string;
+  /** The date as readers see it, for example "Sep 14, 2026". */
+  dateLabel: string;
+  author: string;
+  /** For example "6 min". */
+  readingTime: string;
+  categories: PostCategory[];
+  /** The post's own address, for the share links. */
+  url: string;
+  /** The post's markdown source, for Copy for LLM. */
+  markdown: string;
+  /** The post as plain markdown, for View as Markdown. */
+  markdownHref: string;
+}
+
+function CopyButton({ text, label }: { text: string; label: string }) {
+  const [status, setStatus] = useState<ButtonStatus>("idle");
+
+  useEffect(() => {
+    if (status !== "success" && status !== "error") return;
+    const timer = window.setTimeout(() => setStatus("idle"), buttonStatusHoldMs);
+    return () => window.clearTimeout(timer);
+  }, [status]);
+
+  async function copy() {
+    try {
+      await navigator.clipboard.writeText(text);
+      setStatus("success");
+    } catch {
+      setStatus("error");
+    }
+  }
+
+  return (
+    <Button
+      role="secondary"
+      size="sm"
+      icon={<Copy />}
+      status={status}
+      statusLabels={{ success: "Copied", error: "Couldn't copy" }}
+      onClick={copy}
+    >
+      {label}
+    </Button>
+  );
+}
+
+/** A blog post: the title, a metadata panel, and the article, which is the rendered markdown. */
+export function PostPage({ post, children }: { post: PostPageData; children: ReactNode }) {
+  const metadataHeadingId = useId();
+  const encodedUrl = encodeURIComponent(post.url);
+  const encodedTitle = encodeURIComponent(post.title);
+
+  return (
+    <main className="grid-page bg-body">
+      <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">
+          <h1 className="type-display-2 text-balance text-fg">{post.title}</h1>
+          <p className="type-reading max-w-[40rem] text-muted">{post.description}</p>
+        </header>
+
+        <aside
+          aria-labelledby={metadataHeadingId}
+          className="col-span-full lg:sticky lg:top-[calc(var(--site-nav-height)+1rem)] lg:col-span-4"
+        >
+          <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:col-span-8 lg:mt-0">
+          <SectionCaption as="p">Article</SectionCaption>
+          <Prose className="mt-6">{children}</Prose>
+        </div>
+      </article>
+    </main>
+  );
+}

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

@@ -1,4 +1,4 @@
-// @thewhatmatters/wmds@0.4.0 · Pattern — editorial profile
+// @thewhatmatters/wmds@0.4.1 · 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/index.json

@@ -1,7 +1,15 @@
 {
   "package": "@thewhatmatters/wmds",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "patterns": [
+    {
+      "id": "components-accordion--flush",
+      "title": "Components/Accordion",
+      "name": "Pattern — flush",
+      "file": "patterns/components-accordion--flush.tsx",
+      "storybook": "?path=/story/components-accordion--flush",
+      "source": "src/components/molecules/Accordion/Accordion.stories.tsx"
+    },
     {
       "id": "components-avatar--dropdown-row",
       "title": "Components/Avatar",
@@ -10,6 +18,14 @@
       "storybook": "?path=/story/components-avatar--dropdown-row",
       "source": "src/components/atoms/Avatar/Avatar.stories.tsx"
     },
+    {
+      "id": "components-badge--outline-tags",
+      "title": "Components/Badge",
+      "name": "Pattern — outline tags",
+      "file": "patterns/components-badge--outline-tags.tsx",
+      "storybook": "?path=/story/components-badge--outline-tags",
+      "source": "src/components/atoms/Badge/Badge.stories.tsx"
+    },
     {
       "id": "components-badge--with-avatar",
       "title": "Components/Badge",
@@ -18,6 +34,14 @@
       "storybook": "?path=/story/components-badge--with-avatar",
       "source": "src/components/atoms/Badge/Badge.stories.tsx"
     },
+    {
+      "id": "components-button-button--copy-button",
+      "title": "Components/Button/Button",
+      "name": "Pattern — copy button",
+      "file": "patterns/components-button-button--copy-button.tsx",
+      "storybook": "?path=/story/components-button-button--copy-button",
+      "source": "src/components/atoms/Button/Button.stories.tsx"
+    },
     {
       "id": "components-button-button--destructive-action",
       "title": "Components/Button/Button",
@@ -26,6 +50,14 @@
       "storybook": "?path=/story/components-button-button--destructive-action",
       "source": "src/components/atoms/Button/Button.stories.tsx"
     },
+    {
+      "id": "components-button-button--external-link",
+      "title": "Components/Button/Button",
+      "name": "Pattern — external link",
+      "file": "patterns/components-button-button--external-link.tsx",
+      "storybook": "?path=/story/components-button-button--external-link",
+      "source": "src/components/atoms/Button/Button.stories.tsx"
+    },
     {
       "id": "components-button-button--ghost-action",
       "title": "Components/Button/Button",
@@ -242,6 +274,14 @@
       "storybook": "?path=/story/components-chatdock--pattern-chat-dock",
       "source": "src/components/organisms/ChatDock/ChatDock.stories.tsx"
     },
+    {
+      "id": "components-chatdock--pattern-start-project-gate",
+      "title": "Components/ChatDock",
+      "name": "Pattern — start a project gate",
+      "file": "patterns/components-chatdock--pattern-start-project-gate.tsx",
+      "storybook": "?path=/story/components-chatdock--pattern-start-project-gate",
+      "source": "src/components/organisms/ChatDock/ChatDock.stories.tsx"
+    },
     {
       "id": "components-chatqa--pattern-qa-with-reply",
       "title": "Components/ChatQa",
@@ -258,6 +298,14 @@
       "storybook": "?path=/story/components-checkbox-checkbox--default",
       "source": "src/components/atoms/Checkbox/Checkbox.stories.tsx"
     },
+    {
+      "id": "components-checkbox-checkbox--with-count",
+      "title": "Components/Checkbox/Checkbox",
+      "name": "Pattern — with count",
+      "file": "patterns/components-checkbox-checkbox--with-count.tsx",
+      "storybook": "?path=/story/components-checkbox-checkbox--with-count",
+      "source": "src/components/atoms/Checkbox/Checkbox.stories.tsx"
+    },
     {
       "id": "components-checkbox-checkbox--with-description",
       "title": "Components/Checkbox/Checkbox",
@@ -274,6 +322,30 @@
       "storybook": "?path=/story/components-checkbox-checkboxgroup--default",
       "source": "src/components/molecules/CheckboxGroup/CheckboxGroup.stories.tsx"
     },
+    {
+      "id": "components-checkbox-checkboxgroup--option-counts",
+      "title": "Components/Checkbox/CheckboxGroup",
+      "name": "Pattern — option counts",
+      "file": "patterns/components-checkbox-checkboxgroup--option-counts.tsx",
+      "storybook": "?path=/story/components-checkbox-checkboxgroup--option-counts",
+      "source": "src/components/molecules/CheckboxGroup/CheckboxGroup.stories.tsx"
+    },
+    {
+      "id": "components-descriptionlist--details",
+      "title": "Components/DescriptionList",
+      "name": "Pattern — details",
+      "file": "patterns/components-descriptionlist--details.tsx",
+      "storybook": "?path=/story/components-descriptionlist--details",
+      "source": "src/components/molecules/DescriptionList/DescriptionList.stories.tsx"
+    },
+    {
+      "id": "components-descriptionlist--post-metadata",
+      "title": "Components/DescriptionList",
+      "name": "Pattern — post metadata",
+      "file": "patterns/components-descriptionlist--post-metadata.tsx",
+      "storybook": "?path=/story/components-descriptionlist--post-metadata",
+      "source": "src/components/molecules/DescriptionList/DescriptionList.stories.tsx"
+    },
     {
       "id": "components-dialog--alert-dialog-destructive",
       "title": "Components/Dialog",
@@ -410,6 +482,14 @@
       "storybook": "?path=/story/components-herotilestack--marketing-hero-with-gallery-intro",
       "source": "src/components/organisms/HeroTileStack/HeroTileStack.galleryIntro.stories.tsx"
     },
+    {
+      "id": "components-indexlist--post-index",
+      "title": "Components/IndexList",
+      "name": "Pattern — post index",
+      "file": "patterns/components-indexlist--post-index.tsx",
+      "storybook": "?path=/story/components-indexlist--post-index",
+      "source": "src/components/molecules/IndexList/IndexList.stories.tsx"
+    },
     {
       "id": "components-intakeconfirmation--booked-pattern",
       "title": "Components/IntakeConfirmation",
@@ -538,6 +618,14 @@
       "storybook": "?path=/story/components-promptbar--pattern-prompt-bar",
       "source": "src/components/molecules/PromptBar/PromptBar.stories.tsx"
     },
+    {
+      "id": "components-prose--article-body",
+      "title": "Components/Prose",
+      "name": "Pattern — article body",
+      "file": "patterns/components-prose--article-body.tsx",
+      "storybook": "?path=/story/components-prose--article-body",
+      "source": "src/components/atoms/Prose/Prose.stories.tsx"
+    },
     {
       "id": "components-radio-radiogroup--default",
       "title": "Components/Radio/RadioGroup",
@@ -562,6 +650,22 @@
       "storybook": "?path=/story/components-scrollhorizontal--with-intro",
       "source": "src/components/organisms/ScrollHorizontal/ScrollHorizontal.stories.tsx"
     },
+    {
+      "id": "components-sectioncaption--column-caption",
+      "title": "Components/SectionCaption",
+      "name": "Pattern — column caption",
+      "file": "patterns/components-sectioncaption--column-caption.tsx",
+      "storybook": "?path=/story/components-sectioncaption--column-caption",
+      "source": "src/components/atoms/SectionCaption/SectionCaption.stories.tsx"
+    },
+    {
+      "id": "components-sectioncaption--with-action",
+      "title": "Components/SectionCaption",
+      "name": "Pattern — caption with an action",
+      "file": "patterns/components-sectioncaption--with-action.tsx",
+      "storybook": "?path=/story/components-sectioncaption--with-action",
+      "source": "src/components/atoms/SectionCaption/SectionCaption.stories.tsx"
+    },
     {
       "id": "components-sheet--bottom-sheet",
       "title": "Components/Sheet",
@@ -730,6 +834,14 @@
       "storybook": "?path=/story/components-textlink--inline-prose",
       "source": "src/components/atoms/TextLink/TextLink.stories.tsx"
     },
+    {
+      "id": "components-textlink--quiet-title",
+      "title": "Components/TextLink",
+      "name": "Pattern — quiet title link",
+      "file": "patterns/components-textlink--quiet-title.tsx",
+      "storybook": "?path=/story/components-textlink--quiet-title",
+      "source": "src/components/atoms/TextLink/TextLink.stories.tsx"
+    },
     {
       "id": "components-textlink--supporting-copy",
       "title": "Components/TextLink",
@@ -834,6 +946,14 @@
       "storybook": "?path=/story/guides-chart-explorations--comparison-gallery",
       "source": "src/guides/ChartExplorations/ChartExplorations.stories.tsx"
     },
+    {
+      "id": "guides-filter-panel--filtered-index",
+      "title": "Guides/Filter panel",
+      "name": "Pattern — filtered index",
+      "file": "patterns/guides-filter-panel--filtered-index.tsx",
+      "storybook": "?path=/story/guides-filter-panel--filtered-index",
+      "source": "src/guides/FilterPanel/FilterPanel.stories.tsx"
+    },
     {
       "id": "guides-overlay-flows--notification-preferences",
       "title": "Guides/Overlay flows",
@@ -842,6 +962,14 @@
       "storybook": "?path=/story/guides-overlay-flows--notification-preferences",
       "source": "src/guides/OverlayFlows/OverlayFlows.stories.tsx"
     },
+    {
+      "id": "guides-post-page--post-page",
+      "title": "Guides/Post page",
+      "name": "Pattern — post page",
+      "file": "patterns/guides-post-page--post-page.tsx",
+      "storybook": "?path=/story/guides-post-page--post-page",
+      "source": "src/guides/PostPage/PostPage.stories.tsx"
+    },
     {
       "id": "guides-profile-typography--editorial-profile",
       "title": "Guides/Profile typography",

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.0",
+  "version": "0.4.1",
   "type": "module",
   "license": "MIT",
   "repository": {