From 814e50c5168e8b10c4773d68307f20eefd2dda55 Mon Sep 17 00:00:00 2001
From: Timrossid <timrossid@users.noreply.github.com>
Date: Fri, 29 May 2026 15:11:16 +0100
Subject: [PATCH] feat: add filter controls customer support (#441)

- Add FilterHelpPopover component for inline per-filter help
- Add FilterSupportGuide modal with Guide/FAQ/Contact tabs
- Add useFilterCustomerSupport hook with content for 7 filter sections
- Integrate help popovers and support guide into FilterSidebar
- Integrate help popovers and support guide into FacetedFilterSystem
- Integrate help button and support guide into DashboardFilters
- Write unit tests for all new components and hook
---
 src/components/dashboard/DashboardFilters.tsx |  74 ++--
 src/components/search/FacetedFilterSystem.tsx |  52 ++-
 src/components/search/FilterHelpPopover.tsx   | 136 +++++++
 src/components/search/FilterSidebar.tsx       |  52 ++-
 src/components/search/FilterSupportGuide.tsx  | 194 ++++++++++
 .../__tests__/FilterCustomerSupport.test.tsx  | 348 ++++++++++++++++++
 src/hooks/useFilterCustomerSupport.ts         | 211 +++++++++++
 7 files changed, 1043 insertions(+), 24 deletions(-)
 create mode 100644 src/components/search/FilterHelpPopover.tsx
 create mode 100644 src/components/search/FilterSupportGuide.tsx
 create mode 100644 src/components/search/__tests__/FilterCustomerSupport.test.tsx
 create mode 100644 src/hooks/useFilterCustomerSupport.ts

diff --git a/src/components/dashboard/DashboardFilters.tsx b/src/components/dashboard/DashboardFilters.tsx
index 57c74cc3..95719632 100644
--- a/src/components/dashboard/DashboardFilters.tsx
+++ b/src/components/dashboard/DashboardFilters.tsx
@@ -7,7 +7,7 @@
 'use client';
 
 import React, { useState, useCallback, useMemo } from 'react';
-import { Filter, X, RotateCcw } from 'lucide-react';
+import { Filter, X, RotateCcw, LifeBuoy } from 'lucide-react';
 import { TimeRange, AggregationType, CHART_COLOR_PALETTE } from '@/utils/visualizationUtils';
 import type { DashboardFiltersState } from '@/hooks/useDashboardData';
 import { useInternationalization } from '@/hooks/useInternationalization';
@@ -18,6 +18,9 @@ import {
   getDashboardTimeRangeLabel,
   translateWithFallback,
 } from './dashboardI18n';
+import { FilterHelpPopover } from '@/components/search/FilterHelpPopover';
+import { FilterSupportGuide } from '@/components/search/FilterSupportGuide';
+import { useFilterCustomerSupport } from '@/hooks/useFilterCustomerSupport';
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -52,6 +55,7 @@ export const DashboardFilters = React.memo<DashboardFiltersProps>(
   }) => {
     const { t } = useInternationalization();
     const [isOpen, setIsOpen] = useState(false);
+    const support = useFilterCustomerSupport();
 
     const timeRangeOptions = useMemo(
       () =>
@@ -184,20 +188,32 @@ export const DashboardFilters = React.memo<DashboardFiltersProps>(
             </div>
           </div>
 
-          {activeFilterCount > 0 && (
+          <div className="flex items-center gap-2">
+            {activeFilterCount > 0 && (
+              <button
+                onClick={onReset}
+                aria-label={translateWithFallback(
+                  t,
+                  'dashboard.analytics.filters.resetAllAria',
+                  'Reset all filters',
+                )}
+                className="flex items-center gap-1 px-3 py-1.5 text-sm text-gray-500 dark:text-gray-400 hover:text-red-500 dark:hover:text-red-400 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-red-400 rounded-lg"
+              >
+                <RotateCcw className="w-3.5 h-3.5" aria-hidden="true" />
+                {translateWithFallback(t, 'dashboard.analytics.filters.resetAll', 'Reset All')}
+              </button>
+            )}
+
             <button
-              onClick={onReset}
-              aria-label={translateWithFallback(
-                t,
-                'dashboard.analytics.filters.resetAllAria',
-                'Reset all filters',
-              )}
-              className="flex items-center gap-1 px-3 py-1.5 text-sm text-gray-500 dark:text-gray-400 hover:text-red-500 dark:hover:text-red-400 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-red-400 rounded-lg"
+              type="button"
+              onClick={support.openGuide}
+              aria-label="Open filter help guide"
+              className="flex items-center gap-1 px-3 py-1.5 text-sm text-gray-500 dark:text-gray-400 hover:text-blue-500 dark:hover:text-blue-400 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-400 rounded-lg"
             >
-              <RotateCcw className="w-3.5 h-3.5" aria-hidden="true" />
-              {translateWithFallback(t, 'dashboard.analytics.filters.resetAll', 'Reset All')}
+              <LifeBuoy className="w-3.5 h-3.5" aria-hidden="true" />
+              Help
             </button>
-          )}
+          </div>
         </div>
 
         {/* Expandable panel */}
@@ -208,16 +224,24 @@ export const DashboardFilters = React.memo<DashboardFiltersProps>(
           >
             {/* Time Range */}
             <div>
-              <label
-                htmlFor="filter-time-range"
-                className="block text-xs font-semibold text-gray-500 dark:text-gray-400 uppercase tracking-wide mb-2"
-              >
-                {translateWithFallback(
-                  t,
-                  'dashboard.analytics.filters.timeRange',
-                  'Time Range',
-                )}
-              </label>
+              <div className="flex items-center gap-1 mb-2">
+                <label
+                  htmlFor="filter-time-range"
+                  className="block text-xs font-semibold text-gray-500 dark:text-gray-400 uppercase tracking-wide"
+                >
+                  {translateWithFallback(
+                    t,
+                    'dashboard.analytics.filters.timeRange',
+                    'Time Range',
+                  )}
+                </label>
+                <FilterHelpPopover
+                  content={support.FILTER_HELP_CONTENT.duration}
+                  isOpen={support.activeHelpId === 'duration'}
+                  onToggle={() => support.toggleHelp('duration')}
+                  onClose={support.closeHelp}
+                />
+              </div>
               <select
                 id="filter-time-range"
                 value={filters.timeRange}
@@ -336,6 +360,12 @@ export const DashboardFilters = React.memo<DashboardFiltersProps>(
             </div>
           </div>
         )}
+
+        <FilterSupportGuide
+          isOpen={support.guideOpen}
+          onClose={support.closeGuide}
+          helpContent={support.FILTER_HELP_CONTENT}
+        />
       </div>
     );
   },
diff --git a/src/components/search/FacetedFilterSystem.tsx b/src/components/search/FacetedFilterSystem.tsx
index 46aef4e4..d66e2af0 100644
--- a/src/components/search/FacetedFilterSystem.tsx
+++ b/src/components/search/FacetedFilterSystem.tsx
@@ -1,10 +1,13 @@
 'use client';
 
 import React, { useCallback } from 'react';
-import { BarChart, DollarSign, Tag as TagIcon, Star, Filter, RotateCcw, Check } from 'lucide-react';
+import { BarChart, DollarSign, Tag as TagIcon, Star, Filter, RotateCcw, Check, LifeBuoy } from 'lucide-react';
 import { SearchFilters, SearchContentType } from '../../utils/searchUtils';
 import { MultiSelect } from '../ui/MultiSelect';
 import { RangeSlider } from '../ui/RangeSlider';
+import { FilterHelpPopover } from './FilterHelpPopover';
+import { FilterSupportGuide } from './FilterSupportGuide';
+import { useFilterCustomerSupport } from '../../hooks/useFilterCustomerSupport';
 
 interface FacetedFilterSystemProps {
   filters: SearchFilters;
@@ -39,6 +42,8 @@ const DIFFICULTY_LEVELS = [
 
 export const FacetedFilterSystem = React.memo<FacetedFilterSystemProps>(
   ({ filters, onFilterChange, onReset }) => {
+    const support = useFilterCustomerSupport();
+
     const toggleContentType = useCallback(
       (type: SearchContentType) => {
         let newTypes: SearchContentType[];
@@ -76,6 +81,12 @@ export const FacetedFilterSystem = React.memo<FacetedFilterSystemProps>(
           <div className="flex items-center justify-between mb-4">
             <h3 className="text-xs font-mono font-bold text-slate-400 uppercase tracking-widest flex items-center gap-2">
               <Filter className="w-3 h-3" /> Content Type
+              <FilterHelpPopover
+                content={support.FILTER_HELP_CONTENT['content-type']}
+                isOpen={support.activeHelpId === 'content-type'}
+                onToggle={() => support.toggleHelp('content-type')}
+                onClose={support.closeHelp}
+              />
             </h3>
             <button
               onClick={onReset}
@@ -109,6 +120,12 @@ export const FacetedFilterSystem = React.memo<FacetedFilterSystemProps>(
           <div className="glass-panel p-6 rounded-2xl">
             <h3 className="text-xs font-mono font-bold text-slate-400 uppercase tracking-widest flex items-center gap-2 mb-4">
               <TagIcon className="w-3 h-3" /> Targeted Topics
+              <FilterHelpPopover
+                content={support.FILTER_HELP_CONTENT.topics}
+                isOpen={support.activeHelpId === 'topics'}
+                onToggle={() => support.toggleHelp('topics')}
+                onClose={support.closeHelp}
+              />
             </h3>
             <MultiSelect
               options={TOPIC_OPTIONS}
@@ -122,6 +139,12 @@ export const FacetedFilterSystem = React.memo<FacetedFilterSystemProps>(
           <div className="glass-panel p-6 rounded-2xl">
             <h3 className="text-xs font-mono font-bold text-slate-400 uppercase tracking-widest flex items-center gap-2 mb-4">
               <BarChart className="w-3 h-3" /> Complexity Level
+              <FilterHelpPopover
+                content={support.FILTER_HELP_CONTENT.difficulty}
+                isOpen={support.activeHelpId === 'difficulty'}
+                onToggle={() => support.toggleHelp('difficulty')}
+                onClose={support.closeHelp}
+              />
             </h3>
             <div className="flex flex-col gap-2">
               {DIFFICULTY_LEVELS.map((level) => {
@@ -153,6 +176,12 @@ export const FacetedFilterSystem = React.memo<FacetedFilterSystemProps>(
           <div className="glass-panel p-6 rounded-2xl md:col-span-2">
             <h3 className="text-xs font-mono font-bold text-slate-400 uppercase tracking-widest flex items-center gap-2 mb-6">
               <DollarSign className="w-3 h-3" /> Price Ceiling (USD)
+              <FilterHelpPopover
+                content={support.FILTER_HELP_CONTENT.price}
+                isOpen={support.activeHelpId === 'price'}
+                onToggle={() => support.toggleHelp('price')}
+                onClose={support.closeHelp}
+              />
             </h3>
             <RangeSlider
               min={0}
@@ -181,6 +210,12 @@ export const FacetedFilterSystem = React.memo<FacetedFilterSystemProps>(
           <div className="glass-panel p-6 rounded-2xl">
             <h3 className="text-xs font-mono font-bold text-slate-400 uppercase tracking-widest flex items-center gap-2 mb-4">
               <Star className="w-3 h-3" /> Min Rating
+              <FilterHelpPopover
+                content={support.FILTER_HELP_CONTENT.rating}
+                isOpen={support.activeHelpId === 'rating'}
+                onToggle={() => support.toggleHelp('rating')}
+                onClose={support.closeHelp}
+              />
             </h3>
             <div className="flex flex-col gap-2">
               {[4, 3, 2].map((min) => {
@@ -210,6 +245,21 @@ export const FacetedFilterSystem = React.memo<FacetedFilterSystemProps>(
             </div>
           </div>
         </div>
+
+        <button
+          type="button"
+          onClick={support.openGuide}
+          className="w-full py-3 px-4 bg-blue-50 border border-blue-200 text-blue-700 font-mono text-xs uppercase tracking-wider rounded-lg hover:bg-blue-100 hover:border-blue-300 transition-all duration-300 flex items-center justify-center gap-2 group cursor-pointer"
+        >
+          <LifeBuoy className="w-4 h-4" />
+          Need Help?
+        </button>
+
+        <FilterSupportGuide
+          isOpen={support.guideOpen}
+          onClose={support.closeGuide}
+          helpContent={support.FILTER_HELP_CONTENT}
+        />
       </div>
     );
   },
diff --git a/src/components/search/FilterHelpPopover.tsx b/src/components/search/FilterHelpPopover.tsx
new file mode 100644
index 00000000..630169f9
--- /dev/null
+++ b/src/components/search/FilterHelpPopover.tsx
@@ -0,0 +1,136 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+import { HelpCircle, X, Lightbulb, MessageCircle } from 'lucide-react';
+import type { FilterHelpContent } from '@/hooks/useFilterCustomerSupport';
+
+interface FilterHelpPopoverProps {
+  content: FilterHelpContent;
+  isOpen: boolean;
+  onToggle: () => void;
+  onClose: () => void;
+}
+
+export function FilterHelpPopover({
+  content,
+  isOpen,
+  onToggle,
+  onClose,
+}: FilterHelpPopoverProps) {
+  const popoverRef = useRef<HTMLDivElement>(null);
+  const buttonRef = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    if (!isOpen) return undefined;
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        onClose();
+        buttonRef.current?.focus();
+      }
+    };
+
+    const handleClickOutside = (e: MouseEvent) => {
+      if (
+        popoverRef.current &&
+        !popoverRef.current.contains(e.target as Node) &&
+        buttonRef.current &&
+        !buttonRef.current.contains(e.target as Node)
+      ) {
+        onClose();
+      }
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+      document.removeEventListener('mousedown', handleClickOutside);
+    };
+  }, [isOpen, onClose]);
+
+  return (
+    <div className="relative inline-flex">
+      <button
+        ref={buttonRef}
+        type="button"
+        onClick={onToggle}
+        aria-label={`Help: ${content.title}`}
+        aria-expanded={isOpen}
+        aria-controls={`help-popover-${content.id}`}
+        className="ml-1.5 inline-flex items-center justify-center rounded-full p-0.5 text-slate-400 hover:text-blue-500 hover:bg-blue-50 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500"
+      >
+        <HelpCircle size={14} aria-hidden="true" />
+      </button>
+
+      {isOpen && (
+        <div
+          ref={popoverRef}
+          id={`help-popover-${content.id}`}
+          role="dialog"
+          aria-label={`${content.title} help`}
+          className="absolute left-0 top-6 z-30 w-80 rounded-xl border border-slate-200 bg-white p-4 shadow-lg dark:border-slate-700 dark:bg-slate-900"
+        >
+          <div className="flex items-start justify-between mb-3">
+            <h4 className="text-sm font-semibold text-slate-900 dark:text-slate-100">
+              {content.title}
+            </h4>
+            <button
+              type="button"
+              onClick={onClose}
+              aria-label="Close help"
+              className="rounded p-0.5 text-slate-400 hover:text-slate-600 hover:bg-slate-100 transition-colors"
+            >
+              <X size={14} aria-hidden="true" />
+            </button>
+          </div>
+
+          <p className="text-xs text-slate-600 dark:text-slate-400 leading-relaxed mb-3">
+            {content.description}
+          </p>
+
+          {content.tips.length > 0 && (
+            <div className="mb-3">
+              <h5 className="flex items-center gap-1 text-xs font-semibold text-slate-700 dark:text-slate-300 mb-1.5">
+                <Lightbulb size={12} aria-hidden="true" />
+                Tips
+              </h5>
+              <ul className="space-y-1">
+                {content.tips.map((tip, i) => (
+                  <li
+                    key={i}
+                    className="text-xs text-slate-500 dark:text-slate-400 pl-4 -indent-3"
+                  >
+                    <span className="mr-1 text-blue-400">{'>'}</span>
+                    {tip}
+                  </li>
+                ))}
+              </ul>
+            </div>
+          )}
+
+          {content.faqs.length > 0 && (
+            <div>
+              <h5 className="flex items-center gap-1 text-xs font-semibold text-slate-700 dark:text-slate-300 mb-1.5">
+                <MessageCircle size={12} aria-hidden="true" />
+                FAQ
+              </h5>
+              <div className="space-y-2">
+                {content.faqs.slice(0, 2).map((faq, i) => (
+                  <div key={i}>
+                    <p className="text-xs font-medium text-slate-700 dark:text-slate-300">
+                      Q: {faq.question}
+                    </p>
+                    <p className="text-xs text-slate-500 dark:text-slate-400 mt-0.5">
+                      A: {faq.answer}
+                    </p>
+                  </div>
+                ))}
+              </div>
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/src/components/search/FilterSidebar.tsx b/src/components/search/FilterSidebar.tsx
index 468dd1fe..32a344b0 100644
--- a/src/components/search/FilterSidebar.tsx
+++ b/src/components/search/FilterSidebar.tsx
@@ -1,10 +1,13 @@
 'use client';
 
 import React, { useCallback } from 'react';
-import { BarChart2, Clock, Tag, Users, Search, RotateCcw } from 'lucide-react';
+import { BarChart2, Clock, Tag, Users, Search, RotateCcw, LifeBuoy } from 'lucide-react';
 import { FilterState } from '../../hooks/useSearchFilters';
 import { RangeSlider } from '../ui/RangeSlider';
 import { MultiSelect } from '../ui/MultiSelect';
+import { FilterHelpPopover } from './FilterHelpPopover';
+import { FilterSupportGuide } from './FilterSupportGuide';
+import { useFilterCustomerSupport } from '../../hooks/useFilterCustomerSupport';
 
 interface FilterSidebarProps {
   filters: FilterState;
@@ -16,6 +19,8 @@ const TOPIC_OPTIONS = ['Design', 'Coding', 'Business', 'Marketing', 'Health'];
 
 export const FilterSidebar = React.memo<FilterSidebarProps>(
   ({ filters, onFilterChange, onReset }) => {
+    const support = useFilterCustomerSupport();
+
     const handleDifficultyChange = useCallback(
       (input: string) => {
         const current = filters.difficulty || [];
@@ -43,6 +48,12 @@ export const FilterSidebar = React.memo<FilterSidebarProps>(
         <div className="glass-panel p-5 rounded-xl">
           <h3 className="flex items-center gap-2 text-xs font-mono font-bold text-tech-text uppercase tracking-widest mb-4">
             <BarChart2 className="w-3 h-3" /> Level
+            <FilterHelpPopover
+              content={support.FILTER_HELP_CONTENT.difficulty}
+              isOpen={support.activeHelpId === 'difficulty'}
+              onToggle={() => support.toggleHelp('difficulty')}
+              onClose={support.closeHelp}
+            />
           </h3>
           <div className="space-y-3">
             {[
@@ -74,6 +85,12 @@ export const FilterSidebar = React.memo<FilterSidebarProps>(
         <div className="glass-panel p-5 rounded-xl">
           <h3 className="flex items-center gap-2 text-xs font-mono font-bold text-tech-text uppercase tracking-widest mb-4">
             <Clock className="w-3 h-3" /> Duration
+            <FilterHelpPopover
+              content={support.FILTER_HELP_CONTENT.duration}
+              isOpen={support.activeHelpId === 'duration'}
+              onToggle={() => support.toggleHelp('duration')}
+              onClose={support.closeHelp}
+            />
           </h3>
           <RangeSlider
             min={0}
@@ -93,6 +110,12 @@ export const FilterSidebar = React.memo<FilterSidebarProps>(
         <div className="glass-panel p-5 rounded-xl">
           <h3 className="flex items-center gap-2 text-xs font-mono font-bold text-tech-text uppercase tracking-widest mb-4">
             <Clock className="w-3 h-3" /> Price
+            <FilterHelpPopover
+              content={support.FILTER_HELP_CONTENT.price}
+              isOpen={support.activeHelpId === 'price'}
+              onToggle={() => support.toggleHelp('price')}
+              onClose={support.closeHelp}
+            />
           </h3>
           <RangeSlider
             min={0}
@@ -113,6 +136,12 @@ export const FilterSidebar = React.memo<FilterSidebarProps>(
         <div className="glass-panel p-5 rounded-xl">
           <h3 className="flex items-center gap-2 text-xs font-mono font-bold text-tech-text uppercase tracking-widest mb-4">
             <Tag className="w-3 h-3" /> Topics
+            <FilterHelpPopover
+              content={support.FILTER_HELP_CONTENT.topics}
+              isOpen={support.activeHelpId === 'topics'}
+              onToggle={() => support.toggleHelp('topics')}
+              onClose={support.closeHelp}
+            />
           </h3>
           <MultiSelect
             options={TOPIC_OPTIONS}
@@ -125,6 +154,12 @@ export const FilterSidebar = React.memo<FilterSidebarProps>(
         <div className="glass-panel p-5 rounded-xl">
           <h3 className="flex items-center gap-2 text-xs font-mono font-bold text-tech-text uppercase tracking-widest mb-4">
             <Users className="w-3 h-3" /> Instructor
+            <FilterHelpPopover
+              content={support.FILTER_HELP_CONTENT.instructor}
+              isOpen={support.activeHelpId === 'instructor'}
+              onToggle={() => support.toggleHelp('instructor')}
+              onClose={support.closeHelp}
+            />
           </h3>
           <div className="relative group mb-4">
             <Search className="absolute left-3 top-1/2 -translate-y-1/2 text-slate-300 w-3.5 h-3.5 group-focus-within:text-primary" />
@@ -175,6 +210,21 @@ export const FilterSidebar = React.memo<FilterSidebarProps>(
           <RotateCcw className="w-4 h-4 group-hover:rotate-180 transition-transform duration-500" />
           Reset Parameters
         </button>
+
+        <button
+          type="button"
+          onClick={support.openGuide}
+          className="w-full py-3 px-4 bg-blue-50 border border-blue-200 text-blue-700 font-mono text-xs uppercase tracking-wider rounded-lg hover:bg-blue-100 hover:border-blue-300 transition-all duration-300 flex items-center justify-center gap-2 group cursor-pointer"
+        >
+          <LifeBuoy className="w-4 h-4" />
+          Need Help?
+        </button>
+
+        <FilterSupportGuide
+          isOpen={support.guideOpen}
+          onClose={support.closeGuide}
+          helpContent={support.FILTER_HELP_CONTENT}
+        />
       </aside>
     );
   },
diff --git a/src/components/search/FilterSupportGuide.tsx b/src/components/search/FilterSupportGuide.tsx
new file mode 100644
index 00000000..989c6dab
--- /dev/null
+++ b/src/components/search/FilterSupportGuide.tsx
@@ -0,0 +1,194 @@
+'use client';
+
+import { useState } from 'react';
+import { HelpCircle, Lightbulb, MessageCircle, BookOpen, Mail, ExternalLink } from 'lucide-react';
+import { Modal } from '@/components/ui/Modal';
+import type { FilterHelpContent } from '@/hooks/useFilterCustomerSupport';
+
+interface FilterSupportGuideProps {
+  isOpen: boolean;
+  onClose: () => void;
+  helpContent: Record<string, FilterHelpContent>;
+}
+
+type GuideTab = 'guide' | 'faq' | 'contact';
+
+export function FilterSupportGuide({
+  isOpen,
+  onClose,
+  helpContent,
+}: FilterSupportGuideProps) {
+  const [activeTab, setActiveTab] = useState<GuideTab>('guide');
+  const [expandedSection, setExpandedSection] = useState<string | null>(null);
+
+  const sections = Object.values(helpContent);
+
+  const allFaqs = sections.flatMap((s) =>
+    s.faqs.map((faq) => ({ ...faq, section: s.title })),
+  );
+
+  return (
+    <Modal isOpen={isOpen} onClose={onClose} title="Filter Controls Help" className="max-w-2xl">
+      {/* Tabs */}
+      <div className="flex gap-1 mb-6 border-b border-slate-200 dark:border-slate-700">
+        {[
+          { id: 'guide' as const, label: 'Guide', icon: BookOpen },
+          { id: 'faq' as const, label: 'FAQ', icon: MessageCircle },
+          { id: 'contact' as const, label: 'Contact Support', icon: Mail },
+        ].map((tab) => {
+          const Icon = tab.icon;
+          return (
+            <button
+              key={tab.id}
+              type="button"
+              onClick={() => setActiveTab(tab.id)}
+              role="tab"
+              aria-selected={activeTab === tab.id}
+              className={`flex items-center gap-1.5 px-4 py-2.5 text-xs font-medium rounded-t-lg transition-colors -mb-px ${
+                activeTab === tab.id
+                  ? 'border-b-2 border-blue-500 text-blue-600 dark:text-blue-400'
+                  : 'text-slate-500 hover:text-slate-700 dark:text-slate-400 dark:hover:text-slate-200'
+              }`}
+            >
+              <Icon size={14} aria-hidden="true" />
+              {tab.label}
+            </button>
+          );
+        })}
+      </div>
+
+      {/* Guide Tab */}
+      {activeTab === 'guide' && (
+        <div className="space-y-3 max-h-96 overflow-y-auto pr-1">
+          {sections.map((section) => (
+            <div
+              key={section.id}
+              className="rounded-xl border border-slate-100 dark:border-slate-700 overflow-hidden"
+            >
+              <button
+                type="button"
+                onClick={() =>
+                  setExpandedSection(
+                    expandedSection === section.id ? null : section.id,
+                  )
+                }
+                aria-expanded={expandedSection === section.id}
+                className="w-full flex items-center justify-between px-4 py-3 text-left text-sm font-medium text-slate-800 dark:text-slate-200 hover:bg-slate-50 dark:hover:bg-slate-800/50 transition-colors"
+              >
+                <span className="flex items-center gap-2">
+                  <HelpCircle size={14} className="text-blue-500 shrink-0" aria-hidden="true" />
+                  {section.title}
+                </span>
+                <span
+                  className={`text-slate-400 transition-transform ${
+                    expandedSection === section.id ? 'rotate-180' : ''
+                  }`}
+                >
+                  ▼
+                </span>
+              </button>
+              {expandedSection === section.id && (
+                <div className="px-4 pb-3 pt-1">
+                  <p className="text-xs text-slate-600 dark:text-slate-400 leading-relaxed mb-3">
+                    {section.description}
+                  </p>
+                  {section.tips.length > 0 && (
+                    <div className="mb-2">
+                      <h5 className="flex items-center gap-1 text-xs font-semibold text-slate-700 dark:text-slate-300 mb-1">
+                        <Lightbulb size={12} aria-hidden="true" />
+                        Tips
+                      </h5>
+                      <ul className="space-y-1">
+                        {section.tips.map((tip, i) => (
+                          <li
+                            key={i}
+                            className="text-xs text-slate-500 dark:text-slate-400 pl-4 -indent-3"
+                          >
+                            <span className="mr-1 text-blue-400">{'>'}</span>
+                            {tip}
+                          </li>
+                        ))}
+                      </ul>
+                    </div>
+                  )}
+                </div>
+              )}
+            </div>
+          ))}
+        </div>
+      )}
+
+      {/* FAQ Tab */}
+      {activeTab === 'faq' && (
+        <div className="max-h-96 overflow-y-auto pr-1">
+          {allFaqs.length === 0 ? (
+            <p className="text-sm text-slate-500 dark:text-slate-400 text-center py-8">
+              No FAQs available at this time.
+            </p>
+          ) : (
+            <div className="space-y-4">
+              {allFaqs.map((faq, i) => (
+                <div
+                  key={i}
+                  className="rounded-xl border border-slate-100 dark:border-slate-700 p-4"
+                >
+                  <div className="flex items-center gap-2 mb-1">
+                    <span className="text-[10px] font-mono uppercase text-blue-500 bg-blue-50 dark:bg-blue-900/30 px-1.5 py-0.5 rounded">
+                      {faq.section}
+                    </span>
+                  </div>
+                  <p className="text-sm font-medium text-slate-800 dark:text-slate-200 mb-1">
+                    Q: {faq.question}
+                  </p>
+                  <p className="text-xs text-slate-600 dark:text-slate-400">
+                    A: {faq.answer}
+                  </p>
+                </div>
+              ))}
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Contact Support Tab */}
+      {activeTab === 'contact' && (
+        <div className="space-y-4">
+          <div className="rounded-xl border border-slate-100 dark:border-slate-700 p-4">
+            <h4 className="flex items-center gap-2 text-sm font-semibold text-slate-800 dark:text-slate-200 mb-2">
+              <Mail size={14} aria-hidden="true" />
+              Still need help?
+            </h4>
+            <p className="text-xs text-slate-600 dark:text-slate-400 leading-relaxed mb-4">
+              If you couldn&apos;t find what you need in the guide or FAQ, our
+              support team is here to help.
+            </p>
+            <a
+              href="mailto:support@teachlink.app"
+              className="inline-flex items-center gap-1.5 px-4 py-2 rounded-lg bg-blue-600 text-white text-xs font-semibold hover:bg-blue-700 transition-colors"
+            >
+              <Mail size={14} aria-hidden="true" />
+              Contact Support
+              <ExternalLink size={12} aria-hidden="true" />
+            </a>
+          </div>
+
+          <div className="rounded-xl border border-slate-100 dark:border-slate-700 p-4">
+            <h4 className="flex items-center gap-2 text-sm font-semibold text-slate-800 dark:text-slate-200 mb-2">
+              <BookOpen size={14} aria-hidden="true" />
+              Feedback
+            </h4>
+            <p className="text-xs text-slate-600 dark:text-slate-400 leading-relaxed">
+              Help us improve! Send your feedback about the filter controls to{' '}
+              <a
+                href="mailto:feedback@teachlink.app"
+                className="text-blue-600 hover:underline dark:text-blue-400"
+              >
+                feedback@teachlink.app
+              </a>
+            </p>
+          </div>
+        </div>
+      )}
+    </Modal>
+  );
+}
diff --git a/src/components/search/__tests__/FilterCustomerSupport.test.tsx b/src/components/search/__tests__/FilterCustomerSupport.test.tsx
new file mode 100644
index 00000000..dac9ce11
--- /dev/null
+++ b/src/components/search/__tests__/FilterCustomerSupport.test.tsx
@@ -0,0 +1,348 @@
+import React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { FilterHelpPopover } from '../FilterHelpPopover';
+import { FilterSupportGuide } from '../FilterSupportGuide';
+import { useFilterCustomerSupport } from '@/hooks/useFilterCustomerSupport';
+
+// Guide content is static; verify it matches what we render
+import type { FilterHelpContent } from '@/hooks/useFilterCustomerSupport';
+
+const MOCK_CONTENT: FilterHelpContent = {
+  id: 'test-filter',
+  title: 'Test Filter',
+  description: 'This is a test filter description.',
+  tips: ['Tip one', 'Tip two', 'Tip three'],
+  faqs: [
+    { question: 'Test question?', answer: 'Test answer.' },
+    { question: 'Another question?', answer: 'Another answer.' },
+  ],
+};
+
+const MOCK_ALL_CONTENT: Record<string, FilterHelpContent> = {
+  'test-filter': MOCK_CONTENT,
+  'test-filter-2': {
+    id: 'test-filter-2',
+    title: 'Another Filter',
+    description: 'Another description.',
+    tips: ['Another tip'],
+    faqs: [],
+  },
+};
+
+describe('FilterHelpPopover', () => {
+  it('renders help button', () => {
+    render(
+      <FilterHelpPopover
+        content={MOCK_CONTENT}
+        isOpen={false}
+        onToggle={() => {}}
+        onClose={() => {}}
+      />,
+    );
+    expect(screen.getByLabelText(/help: test filter/i)).toBeInTheDocument();
+  });
+
+  it('shows popover content when open', () => {
+    render(
+      <FilterHelpPopover
+        content={MOCK_CONTENT}
+        isOpen={true}
+        onToggle={() => {}}
+        onClose={() => {}}
+      />,
+    );
+    expect(screen.getByText('Test Filter')).toBeInTheDocument();
+    expect(
+      screen.getByText('This is a test filter description.'),
+    ).toBeInTheDocument();
+  });
+
+  it('displays tips and FAQs', () => {
+    render(
+      <FilterHelpPopover
+        content={MOCK_CONTENT}
+        isOpen={true}
+        onToggle={() => {}}
+        onClose={() => {}}
+      />,
+    );
+    expect(screen.getByText('Tip one')).toBeInTheDocument();
+    expect(screen.getByText('Tip two')).toBeInTheDocument();
+    expect(screen.getByText('Q: Test question?')).toBeInTheDocument();
+    expect(screen.getByText('A: Test answer.')).toBeInTheDocument();
+  });
+
+  it('calls onToggle when button is clicked', async () => {
+    const onToggle = vi.fn();
+    render(
+      <FilterHelpPopover
+        content={MOCK_CONTENT}
+        isOpen={false}
+        onToggle={onToggle}
+        onClose={() => {}}
+      />,
+    );
+    await userEvent.click(screen.getByLabelText(/help: test filter/i));
+    expect(onToggle).toHaveBeenCalledTimes(1);
+  });
+
+  it('calls onClose when close button is clicked', async () => {
+    const onClose = vi.fn();
+    render(
+      <FilterHelpPopover
+        content={MOCK_CONTENT}
+        isOpen={true}
+        onToggle={() => {}}
+        onClose={onClose}
+      />,
+    );
+    await userEvent.click(screen.getByLabelText('Close help'));
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('calls onClose when Escape is pressed', () => {
+    const onClose = vi.fn();
+    render(
+      <FilterHelpPopover
+        content={MOCK_CONTENT}
+        isOpen={true}
+        onToggle={() => {}}
+        onClose={onClose}
+      />,
+    );
+    fireEvent.keyDown(document, { key: 'Escape' });
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('has proper aria attributes when closed', () => {
+    render(
+      <FilterHelpPopover
+        content={MOCK_CONTENT}
+        isOpen={false}
+        onToggle={() => {}}
+        onClose={() => {}}
+      />,
+    );
+    const btn = screen.getByLabelText(/help: test filter/i);
+    expect(btn).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('has proper aria attributes when open', () => {
+    render(
+      <FilterHelpPopover
+        content={MOCK_CONTENT}
+        isOpen={true}
+        onToggle={() => {}}
+        onClose={() => {}}
+      />,
+    );
+    const btn = screen.getByLabelText(/help: test filter/i);
+    expect(btn).toHaveAttribute('aria-expanded', 'true');
+  });
+});
+
+describe('FilterSupportGuide', () => {
+  it('does not render when closed', () => {
+    render(
+      <FilterSupportGuide
+        isOpen={false}
+        onClose={() => {}}
+        helpContent={MOCK_ALL_CONTENT}
+      />,
+    );
+    expect(screen.queryByText('Filter Controls Help')).not.toBeInTheDocument();
+  });
+
+  it('renders guide content when open', () => {
+    render(
+      <FilterSupportGuide
+        isOpen={true}
+        onClose={() => {}}
+        helpContent={MOCK_ALL_CONTENT}
+      />,
+    );
+    expect(screen.getByText('Filter Controls Help')).toBeInTheDocument();
+    expect(screen.getByText('Guide')).toBeInTheDocument();
+    expect(screen.getByText('FAQ')).toBeInTheDocument();
+    expect(screen.getByText('Contact Support')).toBeInTheDocument();
+  });
+
+  it('shows sections in guide tab', () => {
+    render(
+      <FilterSupportGuide
+        isOpen={true}
+        onClose={() => {}}
+        helpContent={MOCK_ALL_CONTENT}
+      />,
+    );
+    expect(screen.getByText('Test Filter')).toBeInTheDocument();
+    expect(screen.getByText('Another Filter')).toBeInTheDocument();
+  });
+
+  it('expands section on click', async () => {
+    render(
+      <FilterSupportGuide
+        isOpen={true}
+        onClose={() => {}}
+        helpContent={MOCK_ALL_CONTENT}
+      />,
+    );
+    const sectionBtn = screen.getByText('Test Filter').closest('button')!;
+    await userEvent.click(sectionBtn);
+    expect(
+      screen.getByText('This is a test filter description.'),
+    ).toBeInTheDocument();
+  });
+
+  it('switches to FAQ tab', async () => {
+    render(
+      <FilterSupportGuide
+        isOpen={true}
+        onClose={() => {}}
+        helpContent={MOCK_ALL_CONTENT}
+      />,
+    );
+    await userEvent.click(screen.getByText('FAQ'));
+    expect(screen.getByText(/Test question/)).toBeInTheDocument();
+    expect(screen.getByText(/Another question/)).toBeInTheDocument();
+  });
+
+  it('switches to Contact Support tab', async () => {
+    render(
+      <FilterSupportGuide
+        isOpen={true}
+        onClose={() => {}}
+        helpContent={MOCK_ALL_CONTENT}
+      />,
+    );
+    await userEvent.click(screen.getByText('Contact Support'));
+    expect(screen.getByText(/Still need help/)).toBeInTheDocument();
+    expect(
+      screen.getByText(/couldn't find what you need/),
+    ).toBeInTheDocument();
+  });
+
+  it('shows "No FAQs" when no FAQs exist', async () => {
+    const noFaqContent: Record<string, FilterHelpContent> = {
+      faqless: {
+        id: 'faqless',
+        title: 'No FAQs',
+        description: 'No FAQs here',
+        tips: [],
+        faqs: [],
+      },
+    };
+    render(
+      <FilterSupportGuide
+        isOpen={true}
+        onClose={() => {}}
+        helpContent={noFaqContent}
+      />,
+    );
+    await userEvent.click(screen.getByText('FAQ'));
+    expect(
+      screen.getByText('No FAQs available at this time.'),
+    ).toBeInTheDocument();
+  });
+
+  it('calls onClose when clicking close button', async () => {
+    const onClose = vi.fn();
+    render(
+      <FilterSupportGuide
+        isOpen={true}
+        onClose={onClose}
+        helpContent={MOCK_ALL_CONTENT}
+      />,
+    );
+    await userEvent.click(screen.getByLabelText('Close dialog'));
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('useFilterCustomerSupport', () => {
+  it('returns help content for known filter IDs', () => {
+    function TestComponent() {
+      const support = useFilterCustomerSupport();
+      const content = support.getHelpContent('difficulty');
+      return <div data-testid="result">{content ? content.title : 'not found'}</div>;
+    }
+    render(<TestComponent />);
+    expect(screen.getByTestId('result')).toHaveTextContent('Difficulty Level');
+  });
+
+  it('toggles activeHelpId', async () => {
+    function TestComponent() {
+      const support = useFilterCustomerSupport();
+      return (
+        <div>
+          <span data-testid="active">{support.activeHelpId ?? 'none'}</span>
+          <button onClick={() => support.toggleHelp('price')}>Toggle</button>
+        </div>
+      );
+    }
+    render(<TestComponent />);
+    expect(screen.getByTestId('active')).toHaveTextContent('none');
+    await userEvent.click(screen.getByText('Toggle'));
+    expect(screen.getByTestId('active')).toHaveTextContent('price');
+    await userEvent.click(screen.getByText('Toggle'));
+    expect(screen.getByTestId('active')).toHaveTextContent('none');
+  });
+
+  it('closes help and resets activeHelpId', async () => {
+    function TestComponent() {
+      const support = useFilterCustomerSupport();
+      return (
+        <div>
+          <span data-testid="active">{support.activeHelpId ?? 'none'}</span>
+          <button onClick={() => support.toggleHelp('topics')}>Open</button>
+          <button onClick={support.closeHelp}>Close</button>
+        </div>
+      );
+    }
+    render(<TestComponent />);
+    await userEvent.click(screen.getByText('Open'));
+    expect(screen.getByTestId('active')).toHaveTextContent('topics');
+    await userEvent.click(screen.getByText('Close'));
+    expect(screen.getByTestId('active')).toHaveTextContent('none');
+  });
+
+  it('manages guideOpen state', async () => {
+    function TestComponent() {
+      const support = useFilterCustomerSupport();
+      return (
+        <div>
+          <span data-testid="guide-open">
+            {support.guideOpen ? 'open' : 'closed'}
+          </span>
+          <button onClick={support.openGuide}>Open Guide</button>
+          <button onClick={support.closeGuide}>Close Guide</button>
+        </div>
+      );
+    }
+    render(<TestComponent />);
+    expect(screen.getByTestId('guide-open')).toHaveTextContent('closed');
+    await userEvent.click(screen.getByText('Open Guide'));
+    expect(screen.getByTestId('guide-open')).toHaveTextContent('open');
+    await userEvent.click(screen.getByText('Close Guide'));
+    expect(screen.getByTestId('guide-open')).toHaveTextContent('closed');
+  });
+
+  it('has all help content sections', () => {
+    function TestComponent() {
+      const support = useFilterCustomerSupport();
+      const ids = Object.keys(support.FILTER_HELP_CONTENT);
+      return <div data-testid="ids">{ids.join(',')}</div>;
+    }
+    render(<TestComponent />);
+    const ids = screen.getByTestId('ids').textContent!.split(',');
+    expect(ids).toContain('difficulty');
+    expect(ids).toContain('duration');
+    expect(ids).toContain('price');
+    expect(ids).toContain('topics');
+    expect(ids).toContain('instructor');
+    expect(ids).toContain('content-type');
+    expect(ids).toContain('rating');
+  });
+});
diff --git a/src/hooks/useFilterCustomerSupport.ts b/src/hooks/useFilterCustomerSupport.ts
new file mode 100644
index 00000000..e86f71f1
--- /dev/null
+++ b/src/hooks/useFilterCustomerSupport.ts
@@ -0,0 +1,211 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+
+export interface FilterHelpContent {
+  id: string;
+  title: string;
+  description: string;
+  tips: string[];
+  faqs: { question: string; answer: string }[];
+}
+
+const FILTER_HELP_CONTENT: Record<string, FilterHelpContent> = {
+  difficulty: {
+    id: 'difficulty',
+    title: 'Difficulty Level',
+    description:
+      'Filter courses and tutorials by their difficulty level to find content matching your current skill level. You can select multiple levels simultaneously.',
+    tips: [
+      'Beginners should start with Beginner level content before advancing',
+      'Select multiple levels to broaden your search results',
+      'Combine difficulty with topics for more targeted results',
+    ],
+    faqs: [
+      {
+        question: 'Can I select more than one difficulty level?',
+        answer:
+          'Yes, you can check multiple difficulty levels to see content from all selected levels at once.',
+      },
+      {
+        question: 'How is difficulty level determined?',
+        answer:
+          'Difficulty levels are assigned by content creators based on prerequisites, complexity, and target audience.',
+      },
+    ],
+  },
+  duration: {
+    id: 'duration',
+    title: 'Duration',
+    description:
+      'Set a maximum duration for courses or tutorials. Use the slider to filter content that fits your available time.',
+    tips: [
+      'Drag the slider handle to adjust the maximum duration',
+      'Shorter durations (1-5h) are ideal for quick learning sessions',
+      'Longer durations (20h+) are typically comprehensive courses',
+    ],
+    faqs: [
+      {
+        question: 'What does the duration slider do?',
+        answer:
+          'The slider sets the maximum course length. Only courses shorter than or equal to the selected value will be shown.',
+      },
+      {
+        question: 'Can I set a minimum duration?',
+        answer:
+          'Currently, only a maximum duration filter is available. We may add minimum duration in a future update.',
+      },
+    ],
+  },
+  price: {
+    id: 'price',
+    title: 'Price',
+    description:
+      'Filter content by price range. Set a maximum price to find courses within your budget.',
+    tips: [
+      'Use the slider to set your maximum budget',
+      'Many free courses are available — set the slider to $0 to find them',
+      'Paid courses often include additional resources and certificates',
+    ],
+    faqs: [
+      {
+        question: 'Are there free courses available?',
+        answer:
+          'Yes, many courses are free. Set the price slider to $0 to browse only free content.',
+      },
+      {
+        question: 'What currency are prices shown in?',
+        answer:
+          'Prices are displayed in USD. Currency conversion is not currently supported.',
+      },
+    ],
+  },
+  topics: {
+    id: 'topics',
+    title: 'Topics',
+    description:
+      'Narrow your search by selecting specific topics. You can choose multiple topics to find content covering various subjects.',
+    tips: [
+      'Type to search for topics if the list is long',
+      'Select multiple topics to find interdisciplinary content',
+      'Start with broad topics, then narrow down with other filters',
+    ],
+    faqs: [
+      {
+        question: 'How many topics can I select?',
+        answer:
+          'There is no limit. Select as many topics as you need to refine your search.',
+      },
+      {
+        question: 'Can I search for topics not in the list?',
+        answer:
+          'The topic list shows available categories. If you need a specific topic, try using the main search bar instead.',
+      },
+    ],
+  },
+  instructor: {
+    id: 'instructor',
+    title: 'Instructor',
+    description:
+      'Filter content by instructor. Search for a specific instructor or select from the suggested list.',
+    tips: [
+      'Type part of an instructor name to search',
+      'Click on a suggested instructor to select or deselect them',
+      'Following specific instructors helps you find consistent teaching styles',
+    ],
+    faqs: [
+      {
+        question: 'Can I select multiple instructors?',
+        answer:
+          'Currently, only one instructor can be selected at a time. This helps narrow down results more effectively.',
+      },
+      {
+        question: 'How do I clear an instructor selection?',
+        answer:
+          'Click the selected instructor again to deselect them, or use the Reset Parameters button.',
+      },
+    ],
+  },
+  'content-type': {
+    id: 'content-type',
+    title: 'Content Type',
+    description:
+      'Choose the type of content you want to browse. Filter between posts, courses, tutorials, authors, and topics.',
+    tips: [
+      'Select "All Content" to see everything available',
+      'Use specific types when you know what format you prefer',
+      'Tutorials are typically shorter and more focused than courses',
+    ],
+    faqs: [
+      {
+        question: 'What is the difference between a course and a tutorial?',
+        answer:
+          'Courses are comprehensive learning paths with multiple modules. Tutorials are shorter, focused lessons on specific topics.',
+      },
+      {
+        question: "What does 'Authors' content type show?",
+        answer:
+          "The 'Authors' type shows content creators and instructors rather than content itself. Select an author to see their profile and work.",
+      },
+    ],
+  },
+  rating: {
+    id: 'rating',
+    title: 'Minimum Rating',
+    description:
+      'Filter content by minimum star rating. Choose a rating threshold to only see highly-rated content.',
+    tips: [
+      'Select 4 stars for the highest quality content',
+      'Lower minimum ratings will include more results',
+      'Combine with other filters for best results',
+    ],
+    faqs: [
+      {
+        question: 'How are ratings calculated?',
+        answer:
+          'Ratings are averaged from all user reviews. Only content with enough reviews is shown with a rating.',
+      },
+      {
+        question: 'Can I filter by exact rating?',
+        answer:
+          'The filter shows content with at least the selected rating. For example, selecting 4 stars shows content rated 4 and above.',
+      },
+    ],
+  },
+};
+
+export function useFilterCustomerSupport() {
+  const [activeHelpId, setActiveHelpId] = useState<string | null>(null);
+  const [guideOpen, setGuideOpen] = useState(false);
+
+  const getHelpContent = useCallback((id: string): FilterHelpContent | undefined => {
+    return FILTER_HELP_CONTENT[id];
+  }, []);
+
+  const toggleHelp = useCallback((id: string) => {
+    setActiveHelpId((prev) => (prev === id ? null : id));
+  }, []);
+
+  const closeHelp = useCallback(() => {
+    setActiveHelpId(null);
+  }, []);
+
+  const openGuide = useCallback(() => {
+    setGuideOpen(true);
+  }, []);
+
+  const closeGuide = useCallback(() => {
+    setGuideOpen(false);
+  }, []);
+
+  return {
+    FILTER_HELP_CONTENT,
+    activeHelpId,
+    guideOpen,
+    getHelpContent,
+    toggleHelp,
+    closeHelp,
+    openGuide,
+    closeGuide,
+  };
+}