@thewhatmatters/wmds 0.4.1 → 0.4.3

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

@@ -1,4 +1,4 @@
-// @thewhatmatters/wmds@0.4.1 · Pattern — filtered index
+// @thewhatmatters/wmds@0.4.3 · 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.
 
@@ -21,20 +21,27 @@ export interface FilteredPost {
   /** 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>;
+  /** The post's options in each filter group, by group id — one or several, for example { topic: ["guides", "brand"] }. */
+  facets: Record<string, string | string[]>;
 }
 
-type Selection = Record<string, string[]>;
+/** The options on in each group, by group id — for example { topic: ["guides"] }. */
+export type FilterSelection = Record<string, string[]>;
 
 function postsLabel(count: number) {
   return count === 1 ? "1 post" : `${count} posts`;
 }
 
-function matches(post: FilteredPost, groups: FilterGroupDef[], selection: Selection) {
+function facetValues(post: FilteredPost, groupId: string): string[] {
+  const value = post.facets[groupId];
+  return value == null ? [] : Array.isArray(value) ? value : [value];
+}
+
+/** A post shows when, in every group with options on, it has at least one of them. */
+function matches(post: FilteredPost, groups: FilterGroupDef[], selection: FilterSelection) {
   return groups.every((group) => {
     const values = selection[group.id] ?? [];
-    return values.length === 0 || values.includes(post.facets[group.id] ?? "");
+    return values.length === 0 || facetValues(post, group.id).some((value) => values.includes(value));
   });
 }
 
@@ -46,7 +53,7 @@ function FilterGroups({
 }: {
   groups: FilterGroupDef[];
   posts: FilteredPost[];
-  selection: Selection;
+  selection: FilterSelection;
   onGroupChange: (groupId: string, values: string[]) => void;
 }) {
   return (
@@ -61,7 +68,7 @@ function FilterGroups({
             onValuesChange={(values) => onGroupChange(group.id, values)}
           >
             {group.options.map((option) => {
-              const count = posts.filter((post) => post.facets[group.id] === option.value).length;
+              const count = posts.filter((post) => facetValues(post, group.id).includes(option.value)).length;
               return (
                 <CheckboxGroup.Item
                   key={option.value}
@@ -79,23 +86,40 @@ function FilterGroups({
   );
 }
 
+export interface FilteredIndexProps {
+  title: string;
+  posts: FilteredPost[];
+  groups: FilterGroupDef[];
+  /** The filters on when the page opens — for example { topic: ["guides"] } from /blog?topic=guides. */
+  defaultSelection?: FilterSelection;
+  /** The filters on, when the app holds them — for example in the URL. Pass with onSelectionChange. */
+  selection?: FilterSelection;
+  /** Every change: an option on or off, or Clear all. */
+  onSelectionChange?: (selection: FilterSelection) => void;
+}
+
 export function FilteredIndex({
   title,
   posts,
   groups,
-}: {
-  title: string;
-  posts: FilteredPost[];
-  groups: FilterGroupDef[];
-}) {
+  defaultSelection,
+  selection: selectionProp,
+  onSelectionChange,
+}: FilteredIndexProps) {
   const filtersHeadingId = useId();
-  const [selection, setSelection] = useState<Selection>({});
+  const [ownSelection, setOwnSelection] = useState<FilterSelection>(defaultSelection ?? {});
+  const selection = selectionProp ?? ownSelection;
   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 changeSelection(next: FilterSelection) {
+    if (selectionProp == null) setOwnSelection(next);
+    onSelectionChange?.(next);
+  }
+
   function setGroup(groupId: string, values: string[]) {
-    setSelection((current) => ({ ...current, [groupId]: values }));
+    changeSelection({ ...selection, [groupId]: values });
   }
 
   return (
@@ -123,7 +147,7 @@ export function FilteredIndex({
           <SectionCaption
             id={filtersHeadingId}
             end={
-              <Button role="ghost" size="xs" disabled={activeCount === 0} onClick={() => setSelection({})}>
+              <Button role="ghost" size="xs" disabled={activeCount === 0} onClick={() => changeSelection({})}>
                 Clear all
               </Button>
             }
@@ -157,7 +181,7 @@ export function FilteredIndex({
           title="Filters"
           footer={
             <div className="flex items-center justify-end gap-2">
-              <Button role="secondary" size="sm" disabled={activeCount === 0} onClick={() => setSelection({})}>
+              <Button role="secondary" size="sm" disabled={activeCount === 0} onClick={() => changeSelection({})}>
                 Clear all
               </Button>
               <Button role="primary" size="sm" onClick={() => setSheetOpen(false)}>

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

@@ -1,4 +1,4 @@
-// @thewhatmatters/wmds@0.4.1 · Pattern — notification preferences
+// @thewhatmatters/wmds@0.4.3 · 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

@@ -1,4 +1,4 @@
-// @thewhatmatters/wmds@0.4.1 · Pattern — post page
+// @thewhatmatters/wmds@0.4.3 · 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.
 
@@ -6,11 +6,13 @@ import { useEffect, useId, useState, type ReactNode } from "react";
 import { Copy, FileText } from "lucide-react";
 import {
   Badge,
+  Breadcrumb,
   Button,
   DescriptionList,
   Prose,
   SectionCaption,
   buttonStatusHoldMs,
+  type BreadcrumbItemDef,
   type ButtonStatus,
 } from "@thewhatmatters/wmds";
 
@@ -20,6 +22,8 @@ export interface PostCategory {
 }
 
 export interface PostPageData {
+  /** The path to this post, ending with it — for example Home, Blog, Guides, this post. */
+  breadcrumb: BreadcrumbItemDef[];
   title: string;
   description: string;
   /** ISO date, for the time element. */
@@ -70,8 +74,34 @@ 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";
+
+/** How many of the page's 12 columns the panel takes from lg; the article takes the rest. */
+export type PostMetadataColumns = 3 | 4;
+
+const metadataColumnClasses: Record<PostMetadataColumns, string> = {
+  3: "lg:col-span-3",
+  4: "lg:col-span-4",
+};
+
+const articleColumnClasses: Record<PostMetadataColumns, string> = {
+  3: "lg:col-span-9",
+  4: "lg:col-span-8",
+};
+
+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". */
+  metadataSide?: PostMetadataSide;
+  /** The panel's width from lg, in columns. Default: 4. */
+  metadataColumns?: PostMetadataColumns;
+}
+
 /** 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 }) {
+export function PostPage({ post, children, metadataSide = "start", metadataColumns = 4 }: PostPageProps) {
   const metadataHeadingId = useId();
   const encodedUrl = encodeURIComponent(post.url);
   const encodedTitle = encodeURIComponent(post.title);
@@ -80,13 +110,18 @@ export function PostPage({ post, children }: { post: PostPageData; children: Rea
     <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">
+          <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>
         </header>
 
         <aside
           aria-labelledby={metadataHeadingId}
-          className="col-span-full lg:sticky lg:top-[calc(var(--site-nav-height)+1rem)] lg:col-span-4"
+          className={
+            "col-span-full lg:sticky lg:top-[calc(var(--site-nav-height)+1rem)] " +
+            metadataColumnClasses[metadataColumns] +
+            (metadataSide === "end" ? " lg:order-last" : "")
+          }
         >
           <SectionCaption id={metadataHeadingId}>Metadata</SectionCaption>
           <DescriptionList variant="mono" rule="dotted">
@@ -133,7 +168,7 @@ export function PostPage({ post, children }: { post: PostPageData; children: Rea
           </DescriptionList>
         </aside>
 
-        <div className="col-span-full mt-6 lg:col-span-8 lg:mt-0">
+        <div className={"col-span-full mt-6 lg:mt-0 " + articleColumnClasses[metadataColumns]}>
           <SectionCaption as="p">Article</SectionCaption>
           <Prose className="mt-6">{children}</Prose>
         </div>

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

@@ -1,4 +1,4 @@
-// @thewhatmatters/wmds@0.4.1 · Pattern — editorial profile
+// @thewhatmatters/wmds@0.4.3 · 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,6 +1,6 @@
 {
   "package": "@thewhatmatters/wmds",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "patterns": [
     {
       "id": "components-accordion--flush",
@@ -34,6 +34,38 @@
       "storybook": "?path=/story/components-badge--with-avatar",
       "source": "src/components/atoms/Badge/Badge.stories.tsx"
     },
+    {
+      "id": "components-breadcrumb--editorial",
+      "title": "Components/Breadcrumb",
+      "name": "Pattern — editorial",
+      "file": "patterns/components-breadcrumb--editorial.tsx",
+      "storybook": "?path=/story/components-breadcrumb--editorial",
+      "source": "src/components/molecules/Breadcrumb/Breadcrumb.stories.tsx"
+    },
+    {
+      "id": "components-breadcrumb--long-path",
+      "title": "Components/Breadcrumb",
+      "name": "Pattern — long path",
+      "file": "patterns/components-breadcrumb--long-path.tsx",
+      "storybook": "?path=/story/components-breadcrumb--long-path",
+      "source": "src/components/molecules/Breadcrumb/Breadcrumb.stories.tsx"
+    },
+    {
+      "id": "components-breadcrumb--path",
+      "title": "Components/Breadcrumb",
+      "name": "Pattern — path",
+      "file": "patterns/components-breadcrumb--path.tsx",
+      "storybook": "?path=/story/components-breadcrumb--path",
+      "source": "src/components/molecules/Breadcrumb/Breadcrumb.stories.tsx"
+    },
+    {
+      "id": "components-breadcrumb--router-links",
+      "title": "Components/Breadcrumb",
+      "name": "Pattern — router links",
+      "file": "patterns/components-breadcrumb--router-links.tsx",
+      "storybook": "?path=/story/components-breadcrumb--router-links",
+      "source": "src/components/molecules/Breadcrumb/Breadcrumb.stories.tsx"
+    },
     {
       "id": "components-button-button--copy-button",
       "title": "Components/Button/Button",

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