@thewhatmatters/wmds 0.4.7 → 0.4.9

package/docs/patterns/components-tilegrid--masonry.tsx

@@ -0,0 +1,44 @@
+// @thewhatmatters/wmds@0.4.9 · Pattern — tile grid
+// Storybook: Components/TileGrid → Pattern — tile grid (?path=/story/components-tilegrid--masonry)
+// Show code — copy verbatim and keep this header; upgrades find pasted patterns by it.
+
+import { LinkTile, TileGrid } from "@thewhatmatters/wmds";
+
+export interface ResourceTileItem {
+  id: string;
+  title: string;
+  href: string;
+  /** Another site: the tile opens it in a new tab. */
+  external?: boolean;
+  /** One line under the title, for example the domain. */
+  meta?: string;
+  /** The preview. Its width and height hold the tile's space before the image loads. */
+  image: { src: string; alt: string; width: number; height: number };
+}
+
+export function ResourceGrid({ label, items }: { label: string; items: ResourceTileItem[] }) {
+  return (
+    <TileGrid aria-label={label} empty={<p className="type-body text-muted">Nothing here yet.</p>}>
+      {items.map((item) => (
+        <TileGrid.Item key={item.id}>
+          <LinkTile
+            title={item.title}
+            href={item.href}
+            external={item.external}
+            meta={item.meta}
+            media={
+              <img
+                src={item.image.src}
+                alt={item.image.alt}
+                width={item.image.width}
+                height={item.image.height}
+                loading="lazy"
+                decoding="async"
+              />
+            }
+          />
+        </TileGrid.Item>
+      ))}
+    </TileGrid>
+  );
+}

package/docs/patterns/components-toast--stacked-notifications.tsx

@@ -1,4 +1,4 @@
-// @thewhatmatters/wmds@0.4.7 · Pattern — stacked notifications
+// @thewhatmatters/wmds@0.4.9 · Pattern — stacked notifications
 // Storybook: Components/Toast → Pattern — stacked notifications (?path=/story/components-toast--stacked-notifications)
 // Show code — copy verbatim and keep this header; upgrades find pasted patterns by it.
 

package/docs/patterns/components-tooltip--controlled.tsx

@@ -1,4 +1,4 @@
-// @thewhatmatters/wmds@0.4.7 · Pattern — controlled state
+// @thewhatmatters/wmds@0.4.9 · Pattern — controlled state
 // Storybook: Components/Tooltip → Pattern — controlled state (?path=/story/components-tooltip--controlled)
 // Show code — copy verbatim and keep this header; upgrades find pasted patterns by it.
 

package/docs/patterns/components-tooltip--disabled-control.tsx

@@ -1,4 +1,4 @@
-// @thewhatmatters/wmds@0.4.7 · Pattern — disabled control
+// @thewhatmatters/wmds@0.4.9 · Pattern — disabled control
 // Storybook: Components/Tooltip → Pattern — disabled control (?path=/story/components-tooltip--disabled-control)
 // Show code — copy verbatim and keep this header; upgrades find pasted patterns by it.
 

package/docs/patterns/components-tooltip--icon-action.tsx

@@ -1,4 +1,4 @@
-// @thewhatmatters/wmds@0.4.7 · Pattern — icon-only action
+// @thewhatmatters/wmds@0.4.9 · Pattern — icon-only action
 // Storybook: Components/Tooltip → Pattern — icon-only action (?path=/story/components-tooltip--icon-action)
 // Show code — copy verbatim and keep this header; upgrades find pasted patterns by it.
 

package/docs/patterns/components-tooltip--keyboard-shortcut.tsx

@@ -1,4 +1,4 @@
-// @thewhatmatters/wmds@0.4.7 · Pattern — keyboard shortcut
+// @thewhatmatters/wmds@0.4.9 · Pattern — keyboard shortcut
 // Storybook: Components/Tooltip → Pattern — keyboard shortcut (?path=/story/components-tooltip--keyboard-shortcut)
 // Show code — copy verbatim and keep this header; upgrades find pasted patterns by it.
 

package/docs/patterns/components-tooltip--placement.tsx

@@ -1,4 +1,4 @@
-// @thewhatmatters/wmds@0.4.7 · Pattern — placement
+// @thewhatmatters/wmds@0.4.9 · Pattern — placement
 // Storybook: Components/Tooltip → Pattern — placement (?path=/story/components-tooltip--placement)
 // Show code — copy verbatim and keep this header; upgrades find pasted patterns by it.
 

package/docs/patterns/foundations-scroll-fade--horizontal-rail.tsx

@@ -1,4 +1,4 @@
-// @thewhatmatters/wmds@0.4.7 · Pattern — horizontal rail
+// @thewhatmatters/wmds@0.4.9 · Pattern — horizontal rail
 // Storybook: Foundations/Scroll fade → Pattern — horizontal rail (?path=/story/foundations-scroll-fade--horizontal-rail)
 // Show code — copy verbatim and keep this header; upgrades find pasted patterns by it.
 

package/docs/patterns/foundations-scroll-fade--overflowing-list.tsx

@@ -1,4 +1,4 @@
-// @thewhatmatters/wmds@0.4.7 · Pattern — overflowing list
+// @thewhatmatters/wmds@0.4.9 · Pattern — overflowing list
 // Storybook: Foundations/Scroll fade → Pattern — overflowing list (?path=/story/foundations-scroll-fade--overflowing-list)
 // Show code — copy verbatim and keep this header; upgrades find pasted patterns by it.
 

package/docs/patterns/guides-chart-explorations--comparison-gallery.tsx

@@ -1,4 +1,4 @@
-// @thewhatmatters/wmds@0.4.7 · Pattern — chart comparison gallery
+// @thewhatmatters/wmds@0.4.9 · Pattern — chart comparison gallery
 // Storybook: Guides/Chart explorations → Pattern — chart comparison gallery (?path=/story/guides-chart-explorations--comparison-gallery)
 // Show code — copy verbatim and keep this header; upgrades find pasted patterns by it.
 

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

@@ -0,0 +1,182 @@
+// @thewhatmatters/wmds@0.4.9 · Pattern — filtered grid
+// Storybook: Guides/Filter panel → Pattern — filtered grid (?path=/story/guides-filter-panel--filtered-grid)
+// Show code — copy verbatim and keep this header; upgrades find pasted patterns by it.
+
+import { useId, type ReactElement, type ReactNode } from "react";
+import {
+  Badge,
+  FilterPanel,
+  LinkTile,
+  SectionCaption,
+  TileGrid,
+  countFilterOptions,
+  matchesFilterSelection,
+  useFilterSelection,
+  type FilterFacets,
+  type FilterPanelGroup,
+  type FilterSelection,
+  type TileGridColumns,
+  type TileGridLayout,
+} from "@thewhatmatters/wmds";
+
+export interface ResourceImage {
+  src: string;
+  alt: string;
+  /** The image's own size, in px. They hold the tile's space before the image loads. */
+  width: number;
+  height: number;
+}
+
+export interface FilteredResource {
+  id: string;
+  title: string;
+  /** Where the tile goes — the resource's page in the app, for example /resources/type-scale. */
+  href: string;
+  /** Only for a tile that links straight to another site: it opens a new tab. */
+  external?: boolean;
+  /** The preview. */
+  image: ResourceImage;
+  /** One line under the title, for example the domain. */
+  meta?: string;
+  /** A short label over the image, for example "Free". */
+  tag?: string;
+  /** The resource's options in each filter group, by group id — one or several, for example { type: ["tools", "fonts"] }. */
+  facets: FilterFacets;
+}
+
+function resourcesLabel(count: number) {
+  return count === 1 ? "1 resource" : `${count} resources`;
+}
+
+/** The image's shape in a uniform grid, and of the placeholders while loading, as width / height. */
+const uniformRatio = 4 / 3;
+
+/** One placeholder tile each, while loading. */
+const loadingTiles = ["one", "two", "three", "four", "five", "six"];
+
+export interface FilteredGridProps {
+  title: string;
+  /** The caption over the grid, in sentence case. It names the list. */
+  caption: string;
+  items: FilteredResource[];
+  groups: FilterPanelGroup[];
+  /** masonry (default): tiles keep their image's height and pack. uniform: every image is 4:3. */
+  layout?: TileGridLayout;
+  /** Columns per breakpoint. Default: 1 on phones, 2 from sm, 3 from lg. */
+  columns?: TileGridColumns;
+  /** Placeholder tiles while the items are on their way. */
+  loading?: boolean;
+  /** The filters on when the page opens — for example { type: ["tools"] } from /resources?type=tools. */
+  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;
+  /** The router's link for a tile, in place of a plain anchor — (item) => <Link href={item.href} />. Not used for external items. */
+  renderLink?: (item: FilteredResource) => ReactElement;
+  /** 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;
+}
+
+export function FilteredGrid({
+  title,
+  caption,
+  items,
+  groups,
+  layout = "masonry",
+  columns,
+  loading = false,
+  defaultSelection,
+  selection: selectionProp,
+  onSelectionChange,
+  renderLink,
+  renderImage,
+  overlay,
+}: FilteredGridProps) {
+  const gridHeadingId = useId();
+  const [selection, setSelection] = useFilterSelection({
+    defaultSelection,
+    selection: selectionProp,
+    onSelectionChange,
+  });
+  const shown = items.filter((item) => matchesFilterSelection(item.facets, selection));
+
+  return (
+    <FilterPanel
+      groups={countFilterOptions(groups, items, resourcesLabel)}
+      selection={selection}
+      onSelectionChange={setSelection}
+      resultsLabel={resourcesLabel(shown.length)}
+    >
+      <main className="grid-page bg-body">
+        {overlay}
+        <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} {loading ? null : <span className="tabular-nums text-muted">{shown.length}</span>}
+            </h1>
+            <FilterPanel.Trigger className="md:hidden" />
+          </header>
+          <p role="status" className="sr-only">
+            {loading ? "Loading" : resourcesLabel(shown.length)}
+          </p>
+
+          <FilterPanel.Rail className="hidden md:col-span-3 md:block" />
+
+          <div className="col-span-full md:col-span-5 lg:col-span-9">
+            <SectionCaption id={gridHeadingId}>{caption}</SectionCaption>
+            <TileGrid
+              aria-labelledby={gridHeadingId}
+              layout={layout}
+              columns={columns}
+              busy={loading}
+              empty={<p className="type-body text-muted">No resources match these filters.</p>}
+              className="mt-6"
+            >
+              {loading
+                ? loadingTiles.map((key) => (
+                    <TileGrid.Item key={key}>
+                      <LinkTile loading ratio={uniformRatio} />
+                    </TileGrid.Item>
+                  ))
+                : shown.map((item) => {
+                    const routed = renderLink != null && !item.external;
+                    return (
+                      <TileGrid.Item key={item.id}>
+                        <LinkTile
+                          title={item.title}
+                          href={routed ? undefined : item.href}
+                          render={routed ? renderLink(item) : undefined}
+                          external={item.external}
+                          meta={item.meta}
+                          ratio={layout === "uniform" ? uniformRatio : undefined}
+                          tag={item.tag != null ? <Badge>{item.tag}</Badge> : undefined}
+                          media={
+                            renderImage != null ? (
+                              renderImage(item.image)
+                            ) : (
+                              <img
+                                src={item.image.src}
+                                alt={item.image.alt}
+                                width={item.image.width}
+                                height={item.image.height}
+                                loading="lazy"
+                                decoding="async"
+                              />
+                            )
+                          }
+                        />
+                      </TileGrid.Item>
+                    );
+                  })}
+            </TileGrid>
+          </div>
+        </div>
+
+        <FilterPanel.Sheet />
+      </main>
+    </FilterPanel>
+  );
+}

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

@@ -1,16 +1,18 @@
-// @thewhatmatters/wmds@0.4.7 · Pattern — filtered index
+// @thewhatmatters/wmds@0.4.9 · 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 }[];
-}
+import { type ReactElement, type ReactNode } from "react";
+import {
+  FilterPanel,
+  IndexList,
+  countFilterOptions,
+  matchesFilterSelection,
+  useFilterSelection,
+  type FilterFacets,
+  type FilterPanelGroup,
+  type FilterSelection,
+} from "@thewhatmatters/wmds";
 
 export interface FilteredPost {
   slug: string;
@@ -22,80 +24,27 @@ export interface FilteredPost {
   dateLabel: string;
   description: 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[]>;
+  facets: FilterFacets;
 }
 
-/** 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 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 || facetValues(post, group.id).some((value) => values.includes(value));
-  });
-}
-
-function FilterGroups({
-  groups,
-  posts,
-  selection,
-  onGroupChange,
-}: {
-  groups: FilterGroupDef[];
-  posts: FilteredPost[];
-  selection: FilterSelection;
-  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) => facetValues(post, group.id).includes(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 interface FilteredIndexProps {
   title: string;
   posts: FilteredPost[];
-  groups: FilterGroupDef[];
+  groups: FilterPanelGroup[];
   /** 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;
+  /** The router's link for a post's title, in place of a plain anchor — (post) => <Link href={post.href} />. */
+  renderLink?: (post: FilteredPost) => ReactElement;
+  /** Page-level layers inside the page grid — for example a GridOverlay. */
+  overlay?: ReactNode;
 }
 
 export function FilteredIndex({
@@ -105,94 +54,60 @@ export function FilteredIndex({
   defaultSelection,
   selection: selectionProp,
   onSelectionChange,
+  renderLink,
+  overlay,
 }: FilteredIndexProps) {
-  const filtersHeadingId = useId();
-  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[]) {
-    changeSelection({ ...selection, [groupId]: values });
-  }
+  const [selection, setSelection] = useFilterSelection({
+    defaultSelection,
+    selection: selectionProp,
+    onSelectionChange,
+  });
+  const shown = posts.filter((post) => matchesFilterSelection(post.facets, selection));
 
   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={() => changeSelection({})}>
-                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>
+    <FilterPanel
+      groups={countFilterOptions(groups, posts, postsLabel)}
+      selection={selection}
+      onSelectionChange={setSelection}
+      resultsLabel={postsLabel(shown.length)}
+    >
+      <main className="grid-page bg-body">
+        {overlay}
+        <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>
+            <FilterPanel.Trigger className="md:hidden" />
+          </header>
+          <p role="status" className="sr-only">
+            {postsLabel(shown.length)}
+          </p>
+
+          <FilterPanel.Rail className="hidden md:col-span-3 md:block" />
+
+          <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={renderLink != null ? undefined : post.href}
+                  render={renderLink?.(post)}
+                  meta={<time dateTime={post.date}>{post.dateLabel}</time>}
+                  preview={<p>{post.description}</p>}
+                />
+              ))}
+            </IndexList>
+          </div>
         </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={() => changeSelection({})}>
-                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>
+        <FilterPanel.Sheet />
+      </main>
+    </FilterPanel>
   );
 }

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

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