Add search and category to the gallery (#10256)

<img width="942" height="895" alt="image"
src="https://github.com/user-attachments/assets/09f1b001-7a64-4942-80af-29e131ba2c60"
/>

Author: timotheeguerin

.chronus/changes/sample-gallery-category-search-2026-3-2-22-0-53.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: feature
+packages:
+  - "@typespec/playground"
+---
+
+Add search and category grouping to samples

packages/playground/src/react/samples-drawer/samples-drawer-trigger.tsx

@@ -4,11 +4,13 @@ import {
   DrawerHeader,
   DrawerHeaderTitle,
   OverlayDrawer,
+  SearchBox,
+  Text,
   ToolbarButton,
   Tooltip,
 } from "@fluentui/react-components";
 import { Dismiss24Regular, DocumentBulletList24Regular } from "@fluentui/react-icons";
-import { useCallback, useState, type FunctionComponent } from "react";
+import { useCallback, useMemo, useState, type FunctionComponent } from "react";
 import type { PlaygroundSample } from "../../types.js";
 import { SampleCard } from "./sample-card.js";
 import style from "./samples-drawer.module.css";
@@ -23,13 +25,49 @@ export interface SamplesDrawerOverlayProps extends SamplesDrawerProps {
   onOpenChange: (open: boolean) => void;
 }
 
+interface SampleCategory {
+  name: string;
+  entries: [string, PlaygroundSample][];
+}
+
+function groupAndFilterSamples(
+  samples: Record<string, PlaygroundSample>,
+  searchQuery: string,
+): SampleCategory[] {
+  const query = searchQuery.toLowerCase().trim();
+  const categoryMap = new Map<string, [string, PlaygroundSample][]>();
+
+  for (const [name, sample] of Object.entries(samples)) {
+    if (query) {
+      const matchesName = name.toLowerCase().includes(query);
+      const matchesDescription = sample.description?.toLowerCase().includes(query);
+      const matchesCategory = sample.category?.toLowerCase().includes(query);
+      if (!matchesName && !matchesDescription && !matchesCategory) continue;
+    }
+
+    const category = sample.category ?? "Other";
+    let entries = categoryMap.get(category);
+    if (!entries) {
+      entries = [];
+      categoryMap.set(category, entries);
+    }
+    entries.push([name, sample]);
+  }
+
+  return Array.from(categoryMap.entries())
+    .map(([name, entries]) => ({ name, entries }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
 /** The overlay drawer showing the sample gallery. Controlled via open/onOpenChange. */
 export const SamplesDrawerOverlay: FunctionComponent<SamplesDrawerOverlayProps> = ({
   samples,
   onSelectedSampleNameChange,
   open,
   onOpenChange,
 }) => {
+  const [searchQuery, setSearchQuery] = useState("");
+
   const handleSampleSelect = useCallback(
     (sampleName: string) => {
       onSelectedSampleNameChange(sampleName);
@@ -38,10 +76,23 @@ export const SamplesDrawerOverlay: FunctionComponent<SamplesDrawerOverlayProps>
     [onSelectedSampleNameChange, onOpenChange],
   );
 
+  const categories = useMemo(
+    () => groupAndFilterSamples(samples, searchQuery),
+    [samples, searchQuery],
+  );
+  const hasCategories = useMemo(() => Object.values(samples).some((s) => s.category), [samples]);
+  const totalFiltered = useMemo(
+    () => categories.reduce((sum, c) => sum + c.entries.length, 0),
+    [categories],
+  );
+
   return (
     <OverlayDrawer
       open={open}
-      onOpenChange={(_, data) => onOpenChange(data.open)}
+      onOpenChange={(_, data) => {
+        onOpenChange(data.open);
+        if (!data.open) setSearchQuery("");
+      }}
       position="end"
       size="large"
     >
@@ -60,11 +111,46 @@ export const SamplesDrawerOverlay: FunctionComponent<SamplesDrawerOverlayProps>
         </DrawerHeaderTitle>
       </DrawerHeader>
       <DrawerBody>
-        <div className={style["samples-grid"]}>
-          {Object.entries(samples).map(([name, sample]) => (
-            <SampleCard key={name} name={name} sample={sample} onSelect={handleSampleSelect} />
-          ))}
+        <div className={style["samples-search"]}>
+          <SearchBox
+            placeholder="Search samples..."
+            value={searchQuery}
+            onChange={(_, data) => setSearchQuery(data.value)}
+            className={style["search-input"]}
+          />
         </div>
+
+        {totalFiltered === 0 ? (
+          <div className={style["samples-empty"]}>
+            <Text>No samples match your search.</Text>
+          </div>
+        ) : hasCategories ? (
+          categories.map((category) => (
+            <div key={category.name} className={style["samples-category"]}>
+              <Text as="h3" weight="semibold" className={style["category-title"]}>
+                {category.name}
+              </Text>
+              <div className={style["samples-grid"]}>
+                {category.entries.map(([name, sample]) => (
+                  <SampleCard
+                    key={name}
+                    name={name}
+                    sample={sample}
+                    onSelect={handleSampleSelect}
+                  />
+                ))}
+              </div>
+            </div>
+          ))
+        ) : (
+          <div className={style["samples-grid"]}>
+            {categories.flatMap((c) =>
+              c.entries.map(([name, sample]) => (
+                <SampleCard key={name} name={name} sample={sample} onSelect={handleSampleSelect} />
+              )),
+            )}
+          </div>
+        )}
       </DrawerBody>
     </OverlayDrawer>
   );

packages/playground/src/react/samples-drawer/samples-drawer.module.css

@@ -1,3 +1,32 @@
+.samples-search {
+  padding: 0 0 16px 0;
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  background: var(--colorNeutralBackground1);
+}
+
+.search-input {
+  width: 100%;
+}
+
+.samples-category {
+  margin-bottom: 24px;
+}
+
+.category-title {
+  font-size: var(--fontSizeBase400);
+  margin: 0 0 12px 0;
+  color: var(--colorNeutralForeground1);
+}
+
+.samples-empty {
+  display: flex;
+  justify-content: center;
+  padding: 48px 16px;
+  color: var(--colorNeutralForeground3);
+}
+
 .samples-grid {
   display: grid;
   grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));

packages/playground/src/types.ts

@@ -16,6 +16,11 @@ export interface PlaygroundSample {
    */
   description?: string;
 
+  /**
+   * Category for grouping samples in the sample gallery.
+   */
+  category?: string;
+
   /**
    * Compiler options for the sample.
    */