aural-ui 4.0.1 → 4.2.0

package/dist/components/search/Search.stories.tsx

@@ -1,694 +1,419 @@
-import React, { useState } from "react"
-import { Button } from "@components/button"
+import React, { useEffect, useRef, useState } from "react"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import Search, { SearchResult } from "."
 
+// ─── Meta ─────────────────────────────────────────────────────────────────────
+
 const meta: Meta<typeof Search> = {
   title: "Components/UI/Search",
   component: Search,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
     docs: {
       description: {
-        component: `
-# Search Component
-
-A comprehensive search input component with both controlled and uncontrolled modes, built with dark theme optimization and flexible content rendering.
-
-## Features
-
-- **Dual Mode Support**: Works as both controlled and uncontrolled component
-- **Search Icon**: Built-in search icon with proper theming
-- **Clear Functionality**: X button to clear search input
-- **Flexible Results**: Custom children rendering for search results
-- **Dark Theme Optimized**: Default styling for dark interfaces
-- **Accessibility**: Full keyboard navigation and screen reader support
-- **Event Handling**: Separate onChange and onSearch callbacks
-- **Input Ref Access**: Easily focus or manage the input programmatically
-
-## Component Modes
-
-### Controlled Component
-Use \`value\`, \`onChange\`, and \`onSearch\` for external state management:
-
-\`\`\`tsx
-const [searchValue, setSearchValue] = useState("")
-const inputRef = useRef<HTMLInputElement>(null)
-
-<Search
-  value={searchValue}
-  onChange={setSearchValue}
-  onSearch={(query) => handleSearch(query)}
-  inputRef={inputRef}
-/>
-\`\`\`
-
-### Uncontrolled Component
-Use \`initialValue\` and \`onSearch\` for internal state management:
-
-\`\`\`tsx
-const inputRef = useRef<HTMLInputElement>(null)
-
-<Search
-  initialValue="initial search"
-  onSearch={(query) => handleSearch(query)}
-  inputRef={inputRef}
-/>
-\`\`\`
-
-## Props Overview
-
-- **value**: Current value (controlled mode)
-- **onChange**: Value change handler (controlled mode)
-- **initialValue**: Initial value (uncontrolled mode)
-- **onSearch**: Search handler (both modes)
-- **results**: Array of search results
-- **children**: Custom content for rendering results
-- **placeholder**: Input placeholder text
-- **className**: Additional CSS classes
-- **inputRef**: Ref to access or focus the underlying input element
-        `,
+        component:
+          "A search input component with built-in search and clear icons, controlled and uncontrolled modes, and flexible children-based results rendering. Supports placeholder customisation, autoFocus, onChange/onSearch callbacks, and programmatic input access via inputRef.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "Search & Clear Icons",
+              description: "Built-in icon slots",
+            },
+            {
+              title: "Controlled Mode",
+              description: "onChange and onSearch",
+            },
+            {
+              title: "Results Slot",
+              description: "Children-based results",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
+  argTypes: {
+    placeholder: { control: { type: "text" } },
+    autoFocus: { control: { type: "boolean" } },
+    value: { control: { type: "text" } },
+  },
+  args: {
+    placeholder: "Search episodes",
+    autoFocus: false,
+  },
 }
 
 export default meta
 type Story = StoryObj<typeof Search>
 
-// 1. Basic Search Component Examples
-export const BasicSearch: Story = {
-  render: () => (
-    <div className="space-y-6">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">
-          Basic Search Component
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Simple search input with different placeholder examples
-        </p>
-      </div>
-
-      <div className="space-y-4">
-        {/* Default Placeholder */}
-        <div className="space-y-2">
-          <label className="text-fm-tertiary text-sm font-medium">
-            Default
-          </label>
-          <Search placeholder="Search episodes" />
-        </div>
-
-        {/* Custom Placeholders */}
-        <div className="space-y-2">
-          <label className="text-fm-tertiary text-sm font-medium">
-            Custom Placeholders
-          </label>
-          <div className="space-y-3">
-            <Search placeholder="Search podcasts..." />
-            <Search placeholder="Find your favorite shows" />
-            <Search placeholder="Type to search music" />
-          </div>
-        </div>
-
-        {/* With Initial Value */}
-        <div className="space-y-2">
-          <label className="text-fm-tertiary text-sm font-medium">
-            With Initial Value
-          </label>
-          <Search placeholder="Search episodes" initialValue="The Daily" />
-        </div>
-      </div>
-    </div>
-  ),
+// ─── Mock data ────────────────────────────────────────────────────────────────
+
+const ALL_PODCASTS = [
+  { id: "1", text: "The Daily" },
+  { id: "2", text: "Serial" },
+  { id: "3", text: "This American Life" },
+  { id: "4", text: "Stuff You Should Know" },
+  { id: "5", text: "Crime Junkie" },
+  { id: "6", text: "Conan O'Brien Needs a Friend" },
+  { id: "7", text: "The Tim Ferriss Show" },
+  { id: "8", text: "My Favorite Murder" },
+  { id: "9", text: "Hidden Brain" },
+  { id: "10", text: "Radiolab" },
+  { id: "11", text: "How I Built This" },
+  { id: "12", text: "Fresh Air" },
+]
+
+// ─── 1. Playground ────────────────────────────────────────────────────────────
+
+export const Playground: Story = {
   parameters: {
     docs: {
       description: {
         story:
-          "Basic search component examples with different placeholder text and initial values.",
+          "Controls-driven story. Use the Storybook sidebar to adjust placeholder, autoFocus, and value. The search input renders with the current args applied.",
       },
     },
   },
+  render: (args) => (
+    <div className="w-80">
+      <Search {...args} />
+    </div>
+  ),
 }
 
-// 2. Controlled Component Examples
-export const ControlledSearch: Story = {
-  render: () => {
-    const [searchValue1, setSearchValue1] = useState("")
-    const [searchValue2, setSearchValue2] = useState("Controlled")
-    const [searchValue3, setSearchValue3] = useState("")
-
-    return (
-      <div className="space-y-6">
-        <div className="text-center">
-          <h3 className="text-fm-primary mb-2 font-medium">
-            Controlled Search
-          </h3>
-          <p className="text-fm-secondary text-sm">
-            Search components with external state control
-          </p>
-        </div>
-
-        <div className="space-y-6">
-          {/* Basic Controlled */}
-          <div className="space-y-3">
-            <div className="flex items-center justify-between">
-              <label className="text-fm-tertiary text-sm font-medium">
-                Basic Controlled
-              </label>
-              <div className="text-fm-secondary text-xs">
-                Value: "{searchValue1}"
-              </div>
-            </div>
-            <Search
-              placeholder="Type something..."
-              value={searchValue1}
-              onChange={setSearchValue1}
-            />
-            <div className="flex gap-2">
-              <Button
-                size="sm"
-                variant="outline"
-                onClick={() => setSearchValue1("Preset Value")}
-              >
-                Set Value
-              </Button>
-              <Button
-                size="sm"
-                variant="outline"
-                onClick={() => setSearchValue1("")}
-              >
-                Clear
-              </Button>
-            </div>
-          </div>
-
-          {/* Pre-filled Controlled */}
-          <div className="space-y-3">
-            <div className="flex items-center justify-between">
-              <label className="text-fm-tertiary text-sm font-medium">
-                Pre-filled Controlled
-              </label>
-              <div className="text-fm-secondary text-xs">
-                Value: "{searchValue2}"
-              </div>
-            </div>
-            <Search
-              placeholder="Search with preset value"
-              value={searchValue2}
-              onChange={setSearchValue2}
-            />
-          </div>
+// ─── 2. States ────────────────────────────────────────────────────────────────
 
-          {/* Controlled with Validation */}
-          <div className="space-y-3">
-            <div className="flex items-center justify-between">
-              <label className="text-fm-tertiary text-sm font-medium">
-                With Validation
-              </label>
-              <div className="text-fm-secondary text-xs">
-                Length: {searchValue3.length}/20
-              </div>
-            </div>
-            <Search
-              placeholder="Max 20 characters"
-              value={searchValue3}
-              onChange={(value) => {
-                if (value.length <= 20) {
-                  setSearchValue3(value)
-                }
-              }}
-            />
-            {searchValue3.length >= 20 && (
-              <p className="text-fm-negative text-xs">Maximum length reached</p>
-            )}
-          </div>
-        </div>
-      </div>
-    )
-  },
+export const States: Story = {
   parameters: {
     docs: {
       description: {
         story:
-          "Controlled search component examples showing external state management, pre-filled values, and validation.",
+          "Five distinct states: empty (idle), has query (clear button visible), loading (async in-progress), no results (empty results set), and with results (list rendered below).",
       },
     },
   },
-}
-
-// 3. Uncontrolled Component Examples
-export const UncontrolledSearch: Story = {
   render: () => {
-    const [lastSearch1, setLastSearch1] = useState("")
-    const [lastSearch2, setLastSearch2] = useState("")
+    const [loadingQuery, setLoadingQuery] = useState("")
+    const [noResultsQuery, setNoResultsQuery] = useState("nonexistentshow")
+    const [resultsQuery, setResultsQuery] = useState("The")
 
-    return (
-      <div className="space-y-6">
-        <div className="text-center">
-          <h3 className="text-fm-primary mb-2 font-medium">
-            Uncontrolled Search
-          </h3>
-          <p className="text-fm-secondary text-sm">
-            Search components with internal state management
-          </p>
-        </div>
+    const filteredResults: SearchResult[] = resultsQuery
+      ? ALL_PODCASTS.filter((p) =>
+          p.text.toLowerCase().includes(resultsQuery.toLowerCase())
+        )
+      : []
 
-        <div className="space-y-6">
-          {/* Basic Uncontrolled */}
-          <div className="space-y-3">
-            <div className="flex items-center justify-between">
-              <label className="text-fm-tertiary text-sm font-medium">
-                Basic Uncontrolled
-              </label>
-              <div className="text-fm-secondary text-xs">
-                Last search: "{lastSearch1}"
-              </div>
-            </div>
-            <Search
-              placeholder="Search internally managed"
-              onSearch={setLastSearch1}
-            />
-          </div>
-
-          {/* With Initial Value */}
-          <div className="space-y-3">
-            <div className="flex items-center justify-between">
-              <label className="text-fm-tertiary text-sm font-medium">
-                With Initial Value
-              </label>
-              <div className="text-fm-secondary text-xs">
-                Last search: "{lastSearch2}"
-              </div>
-            </div>
-            <Search
-              placeholder="Search with initial value"
-              initialValue="Initial Search"
-              onSearch={setLastSearch2}
-            />
-          </div>
-
-          {/* Multiple Independent */}
-          <div className="space-y-3">
-            <label className="text-fm-tertiary text-sm font-medium">
-              Multiple Independent
-            </label>
-            <div className="grid grid-cols-2 gap-3">
-              <Search placeholder="Search A" />
-              <Search placeholder="Search B" />
-            </div>
-            <p className="text-fm-secondary text-xs">
-              Each search maintains its own independent state
+    return (
+      <div className="w-80 space-y-8">
+        {/* Empty */}
+        <div>
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-3 font-medium">
+            Empty
+          </h4>
+          <div className="space-y-2 text-center">
+            <Search placeholder="Search episodes" />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Idle — no input yet
             </p>
           </div>
         </div>
-      </div>
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Uncontrolled search component examples with internal state management and initial values.",
-      },
-    },
-  },
-}
-
-// 4. Interactive Search with Results
-export const InteractiveSearch: Story = {
-  render: () => {
-    const [query, setQuery] = useState("")
-    const [results, setResults] = useState<SearchResult[]>([])
-    const [selectedResult, setSelectedResult] = useState<string | null>(null)
-
-    // Mock search data
-    const allPodcasts = [
-      { id: "1", text: "The Joe Rogan Experience" },
-      { id: "2", text: "Serial" },
-      { id: "3", text: "This American Life" },
-      { id: "4", text: "Stuff You Should Know" },
-      { id: "5", text: "The Daily" },
-      { id: "6", text: "Crime Junkie" },
-      { id: "7", text: "The Michelle Obama Podcast" },
-      { id: "8", text: "Call Her Daddy" },
-      { id: "9", text: "My Favorite Murder" },
-      { id: "10", text: "The Tim Ferriss Show" },
-      { id: "11", text: "Conan O'Brien Needs a Friend" },
-      { id: "12", text: "The Ben Shapiro Show" },
-    ]
-
-    const handleSearch = (searchQuery: string) => {
-      setQuery(searchQuery)
-
-      if (!searchQuery.trim()) {
-        setResults([])
-        return
-      }
-
-      // Filter podcasts based on query
-      const filteredResults = allPodcasts.filter((podcast) =>
-        podcast.text.toLowerCase().includes(searchQuery.toLowerCase())
-      )
-
-      setResults(filteredResults)
-    }
-
-    return (
-      <div className="w-96 space-y-4">
-        <div className="text-center">
-          <h3 className="text-fm-primary mb-2 font-medium">
-            Interactive Search
-          </h3>
-          <p className="text-fm-secondary text-sm">
-            Real-time search with custom results rendering
-          </p>
-        </div>
 
-        <Search
-          placeholder="Search podcasts..."
-          value={query}
-          onChange={setQuery}
-          onSearch={handleSearch}
-          results={results}
-        >
-          {/* Custom Results Rendering */}
-          {results.length > 0 && (
-            <div className="border-fm-divider-secondary bg-fm-surface-primary mt-2 rounded-lg border shadow-xl">
-              <div className="p-3">
-                <div className="mb-2 flex items-center justify-between">
-                  <span className="text-fm-tertiary text-xs font-medium">
-                    Search Results
-                  </span>
-                  <span className="text-fm-secondary text-xs">
-                    {results.length} found
-                  </span>
-                </div>
-                <div className="max-h-64 space-y-1 overflow-y-auto">
-                  {results.map((result) => (
-                    <button
-                      key={result.id}
-                      onClick={() => {
-                        setSelectedResult(result.text)
-                        setQuery(result.text)
-                        setResults([])
-                      }}
-                      className="text-fm-primary hover:bg-fm-surface-secondary w-full rounded px-3 py-2 text-left text-sm"
-                    >
-                      {result.text}
-                    </button>
-                  ))}
-                </div>
-              </div>
-            </div>
-          )}
-        </Search>
-
-        {/* Search Info */}
-        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
-          <h4 className="text-fm-primary mb-2 text-sm font-medium">
-            Search Info
+        {/* Has query */}
+        <div>
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-3 font-medium">
+            Has Query
           </h4>
-          <div className="text-fm-secondary space-y-1 text-xs">
-            <div>Query: "{query || "(empty)"}"</div>
-            <div>Results: {results.length}</div>
-            <div>Selected: {selectedResult || "(none)"}</div>
+          <div className="space-y-2 text-center">
+            <Search placeholder="Search episodes" initialValue="The Daily" />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Clear button visible when input has value
+            </p>
           </div>
         </div>
-      </div>
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Interactive search example with real-time filtering, custom results rendering, and selection handling.",
-      },
-    },
-  },
-}
-
-// 5. Search with Different States
-export const SearchStates: Story = {
-  render: () => {
-    const [loadingQuery, setLoadingQuery] = useState("")
-    const [errorQuery, setErrorQuery] = useState("")
-    const [emptyQuery, setEmptyQuery] = useState("nonexistent")
 
-    return (
-      <div className="space-y-6">
-        <div className="text-center">
-          <h3 className="text-fm-primary mb-2 font-medium">Search States</h3>
-          <p className="text-fm-secondary text-sm">
-            Different search states and feedback
-          </p>
-        </div>
-
-        <div className="grid gap-6">
-          {/* Loading State */}
-          <div className="space-y-3">
-            <label className="text-fm-tertiary text-sm font-medium">
-              Loading State
-            </label>
+        {/* Loading */}
+        <div>
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-3 font-medium">
+            Loading
+          </h4>
+          <div className="space-y-2 text-center">
             <Search
-              placeholder="Search with loading..."
+              placeholder="Search episodes"
               value={loadingQuery}
               onChange={setLoadingQuery}
               onSearch={setLoadingQuery}
             >
               {loadingQuery && (
-                <div className="border-fm-divider-secondary bg-fm-surface-primary mt-2 rounded-lg border p-4 text-center">
+                <div className="border-fm-divider-secondary bg-fm-surface-secondary mt-2 rounded-lg border p-4 text-center">
                   <div className="flex items-center justify-center gap-2">
-                    <div className="border-fm-divider-secondary h-4 w-4 animate-spin rounded-full border-2 border-t-white"></div>
-                    <span className="text-fm-tertiary text-sm">
-                      Searching...
+                    <div className="border-fm-divider-contrast h-4 w-4 animate-spin rounded-full border-2 border-t-transparent" />
+                    <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                      Searching…
                     </span>
                   </div>
                 </div>
               )}
             </Search>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Type anything to trigger loading state
+            </p>
           </div>
+        </div>
 
-          {/* Error State */}
-          <div className="space-y-3">
-            <label className="text-fm-tertiary text-sm font-medium">
-              Error State
-            </label>
+        {/* No results */}
+        <div>
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-3 font-medium">
+            No Results
+          </h4>
+          <div className="space-y-2 text-center">
             <Search
-              placeholder="Search with error..."
-              value={errorQuery}
-              onChange={setErrorQuery}
-              onSearch={setErrorQuery}
+              placeholder="Search episodes"
+              value={noResultsQuery}
+              onChange={setNoResultsQuery}
+              onSearch={setNoResultsQuery}
             >
-              {errorQuery && (
-                <div className="border-fm-divider-secondary bg-fm-surface-negative-sec mt-2 rounded-lg border p-4">
-                  <div className="flex items-center gap-2">
-                    <svg
-                      className="text-fm-icon-negative h-4 w-4"
-                      fill="none"
-                      stroke="currentColor"
-                      viewBox="0 0 24 24"
-                    >
-                      <path
-                        strokeLinecap="round"
-                        strokeLinejoin="round"
-                        strokeWidth={2}
-                        d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"
-                      />
-                    </svg>
-                    <span className="text-fm-negative text-sm">
-                      Search failed. Please try again.
-                    </span>
+              {noResultsQuery && (
+                <div className="border-fm-divider-secondary bg-fm-surface-secondary mt-2 rounded-lg border p-4 text-center">
+                  <div className="space-y-1">
+                    <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                      No results found
+                    </p>
+                    <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                      Try different keywords or check your spelling.
+                    </p>
                   </div>
                 </div>
               )}
             </Search>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Pre-filled with a term that matches nothing
+            </p>
           </div>
+        </div>
 
-          {/* Empty State */}
-          <div className="space-y-3">
-            <label className="text-fm-tertiary text-sm font-medium">
-              Empty Results
-            </label>
+        {/* With results */}
+        <div>
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-3 font-medium">
+            With Results
+          </h4>
+          <div className="space-y-2 text-center">
             <Search
-              placeholder="Search with no results..."
-              value={emptyQuery}
-              onChange={setEmptyQuery}
-              onSearch={setEmptyQuery}
+              placeholder="Search podcasts…"
+              value={resultsQuery}
+              onChange={setResultsQuery}
+              onSearch={setResultsQuery}
+              results={filteredResults}
             >
-              {emptyQuery && (
-                <div className="border-fm-divider-secondary bg-fm-surface-primary mt-2 rounded-lg border p-4 text-center">
-                  <div className="space-y-2">
-                    <svg
-                      className="text-fm-secondary mx-auto h-8 w-8"
-                      fill="none"
-                      stroke="currentColor"
-                      viewBox="0 0 24 24"
-                    >
-                      <path
-                        strokeLinecap="round"
-                        strokeLinejoin="round"
-                        strokeWidth={2}
-                        d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"
-                      />
-                    </svg>
-                    <div>
-                      <p className="text-fm-primary text-sm font-medium">
-                        No results found
-                      </p>
-                      <p className="text-fm-secondary text-xs">
-                        Try different keywords or check your spelling
-                      </p>
-                    </div>
+              {filteredResults.length > 0 && (
+                <div className="border-fm-divider-secondary bg-fm-surface-secondary mt-2 rounded-lg border">
+                  <div className="flex items-center justify-between px-3 pt-3 pb-1">
+                    <span className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                      Results
+                    </span>
+                    <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                      {filteredResults.length} found
+                    </span>
+                  </div>
+                  <div className="max-h-48 overflow-y-auto pb-2">
+                    {filteredResults.map((r) => (
+                      <button
+                        key={r.id}
+                        className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm hover:bg-fm-surface-primary w-full px-3 py-2 text-left transition-colors"
+                      >
+                        {r.text}
+                      </button>
+                    ))}
                   </div>
                 </div>
               )}
             </Search>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Pre-filled with "The" — shows matching results
+            </p>
           </div>
         </div>
       </div>
     )
   },
+}
+
+// ─── 3. Interactive ───────────────────────────────────────────────────────────
+
+export const Interactive: Story = {
   parameters: {
     docs: {
       description: {
         story:
-          "Search component examples showing different states: loading, error, and empty results with appropriate feedback.",
+          "Live search with debounce simulation. Type in the search box to filter the podcast list. Results appear after a short delay (300 ms) to mimic a real API call. Selecting a result populates the input.",
       },
     },
   },
-}
-
-// 6. Advanced Search Features
-export const AdvancedFeatures: Story = {
   render: () => {
-    const [searchHistory, setSearchHistory] = useState<string[]>([
-      "The Daily",
-      "Serial",
-      "This American Life",
-    ])
-    const [currentSearch, setCurrentSearch] = useState("")
-    const [showHistory, setShowHistory] = useState(false)
+    const [query, setQuery] = useState("")
+    const [debouncedQuery, setDebouncedQuery] = useState("")
+    const [isSearching, setIsSearching] = useState(false)
+    const [results, setResults] = useState<SearchResult[]>([])
+    const [selected, setSelected] = useState<string | null>(null)
+    const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
 
-    const addToHistory = (query: string) => {
-      if (query.trim() && !searchHistory.includes(query)) {
-        setSearchHistory((prev) => [query, ...prev.slice(0, 4)])
+    // Debounced search simulation
+    useEffect(() => {
+      if (!query.trim()) {
+        setResults([])
+        setDebouncedQuery("")
+        setIsSearching(false)
+        return
       }
-    }
+
+      setIsSearching(true)
+
+      if (timerRef.current) clearTimeout(timerRef.current)
+      timerRef.current = setTimeout(() => {
+        const filtered = ALL_PODCASTS.filter((p) =>
+          p.text.toLowerCase().includes(query.toLowerCase())
+        )
+        setResults(filtered)
+        setDebouncedQuery(query)
+        setIsSearching(false)
+      }, 300)
+
+      return () => {
+        if (timerRef.current) clearTimeout(timerRef.current)
+      }
+    }, [query])
 
     return (
-      <div className="w-96 space-y-6">
-        <div className="text-center">
-          <h3 className="text-fm-primary mb-2 font-medium">
-            Advanced Features
-          </h3>
-          <p className="text-fm-secondary text-sm">
-            Search with history, suggestions, and shortcuts
-          </p>
-        </div>
+      <div className="w-full p-8">
+        <div className="mx-auto max-w-3xl space-y-6">
+          <div className="grid grid-cols-1 gap-6 lg:grid-cols-3">
+            {/* Controls panel */}
+            <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-5 rounded-xl border p-5">
+              <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                Search State
+              </p>
+
+              <div className="border-fm-divider-secondary bg-fm-surface-primary space-y-3 rounded-lg border p-3">
+                <div>
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                    Query
+                  </p>
+                  <p className="text-fm-primary font--(--font-fm-mono) text-fm-sm leading-fm-sm break-all">
+                    {query || "(empty)"}
+                  </p>
+                </div>
+                <div>
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                    Debounced
+                  </p>
+                  <p className="text-fm-primary font--(--font-fm-mono) text-fm-sm leading-fm-sm break-all">
+                    {debouncedQuery || "(empty)"}
+                  </p>
+                </div>
+                <div>
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                    Results
+                  </p>
+                  <p className="text-fm-primary font--(--font-fm-mono) text-fm-sm leading-fm-sm">
+                    {isSearching ? "searching…" : results.length}
+                  </p>
+                </div>
+                <div>
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                    Selected
+                  </p>
+                  <p className="text-fm-primary font--(--font-fm-mono) text-fm-sm leading-fm-sm break-all">
+                    {selected ?? "(none)"}
+                  </p>
+                </div>
+              </div>
 
-        <div className="space-y-6">
-          {/* Search with History */}
-          <div className="space-y-3">
-            <label className="text-fm-tertiary text-sm font-medium">
-              Search with History
-            </label>
-            <Search
-              placeholder="Search with history..."
-              value={currentSearch}
-              onChange={setCurrentSearch}
-              onSearch={(query) => {
-                addToHistory(query)
-                setShowHistory(false)
-              }}
-            >
-              {(showHistory ||
-                (!currentSearch && searchHistory.length > 0)) && (
-                <div className="border-fm-divider-secondary bg-fm-surface-primary mt-2 rounded-lg border shadow-xl">
-                  <div className="p-3">
-                    <div className="text-fm-tertiary mb-2 text-xs font-medium">
-                      Recent Searches
+              <div className="border-fm-divider-secondary border-t pt-4" />
+
+              <button
+                onClick={() => {
+                  setQuery("")
+                  setResults([])
+                  setSelected(null)
+                }}
+                className="border-fm-divider-secondary text-fm-primary font-fm-text text-fm-sm leading-fm-sm hover:bg-fm-surface-primary w-full rounded-lg border px-3 py-2 text-left transition-colors"
+              >
+                Clear all
+              </button>
+            </div>
+
+            {/* Preview stage */}
+            <div className="flex flex-col gap-3 lg:col-span-2">
+              <Search
+                placeholder="Search podcasts…"
+                value={query}
+                onChange={setQuery}
+                onSearch={setQuery}
+                results={results}
+              >
+                {/* Loading state */}
+                {isSearching && (
+                  <div className="border-fm-divider-secondary bg-fm-surface-secondary mt-2 rounded-lg border p-4 text-center">
+                    <div className="flex items-center justify-center gap-2">
+                      <div className="border-fm-divider-contrast h-4 w-4 animate-spin rounded-full border-2 border-t-transparent" />
+                      <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                        Searching…
+                      </span>
                     </div>
-                    <div className="space-y-1">
-                      {searchHistory.map((item, index) => (
+                  </div>
+                )}
+
+                {/* Results list */}
+                {!isSearching && query && results.length > 0 && (
+                  <div className="border-fm-divider-secondary bg-fm-surface-secondary mt-2 rounded-lg border">
+                    <div className="flex items-center justify-between px-3 pt-3 pb-1">
+                      <span className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                        Podcasts
+                      </span>
+                      <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                        {results.length} result{results.length !== 1 ? "s" : ""}
+                      </span>
+                    </div>
+                    <div className="max-h-56 overflow-y-auto pb-2">
+                      {results.map((r) => (
                         <button
-                          key={index}
+                          key={r.id}
                           onClick={() => {
-                            setCurrentSearch(item)
-                            setShowHistory(false)
+                            setSelected(r.text)
+                            setQuery(r.text)
+                            setResults([])
                           }}
-                          className="text-fm-primary hover:bg-fm-surface-secondary flex w-full items-center gap-2 rounded px-3 py-2 text-left text-sm"
+                          className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm hover:bg-fm-surface-primary w-full px-3 py-2.5 text-left transition-colors"
                         >
-                          <svg
-                            className="text-fm-secondary h-3 w-3"
-                            fill="none"
-                            stroke="currentColor"
-                            viewBox="0 0 24 24"
-                          >
-                            <path
-                              strokeLinecap="round"
-                              strokeLinejoin="round"
-                              strokeWidth={2}
-                              d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z"
-                            />
-                          </svg>
-                          {item}
+                          {r.text}
                         </button>
                       ))}
                     </div>
                   </div>
-                </div>
-              )}
-            </Search>
-            <div className="flex gap-2">
-              <Button
-                size="sm"
-                variant="outline"
-                onClick={() => setShowHistory(!showHistory)}
-              >
-                {showHistory ? "Hide" : "Show"} History
-              </Button>
-              <Button
-                size="sm"
-                variant="outline"
-                onClick={() => setSearchHistory([])}
-              >
-                Clear History
-              </Button>
-            </div>
-          </div>
+                )}
+
+                {/* No results */}
+                {!isSearching && query && results.length === 0 && (
+                  <div className="border-fm-divider-secondary bg-fm-surface-secondary mt-2 rounded-lg border p-4 text-center">
+                    <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                      No results for "{query}"
+                    </p>
+                    <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm mt-1">
+                      Try a different search term.
+                    </p>
+                  </div>
+                )}
+              </Search>
 
-          {/* Keyboard Shortcuts Info */}
-          <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
-            <h4 className="text-fm-primary mb-2 text-sm font-medium">
-              Keyboard Shortcuts
-            </h4>
-            <div className="text-fm-secondary space-y-1 text-xs">
-              <div className="flex justify-between">
-                <span>Focus search:</span>
-                <kbd className="bg-fm-surface-secondary rounded px-1 font-mono">
-                  Cmd+K
-                </kbd>
-              </div>
-              <div className="flex justify-between">
-                <span>Clear search:</span>
-                <kbd className="bg-fm-surface-secondary rounded px-1 font-mono">
-                  Esc
-                </kbd>
-              </div>
-              <div className="flex justify-between">
-                <span>Navigate results:</span>
-                <kbd className="bg-fm-surface-secondary rounded px-1 font-mono">
-                  ↑↓
-                </kbd>
+              <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border px-4 py-3">
+                <code className="text-fm-secondary font--(--font-fm-mono) text-fm-md leading-fm-md">
+                  {`<Search value="${query}" onChange={setQuery} results={[…]} />`}
+                </code>
               </div>
             </div>
           </div>
@@ -696,12 +421,4 @@ export const AdvancedFeatures: Story = {
       </div>
     )
   },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Advanced search features including search history, keyboard shortcuts, and enhanced user experience patterns.",
-      },
-    },
-  },
 }