feat: add search filters for platform and gen version

Add visible filter controls inside the DocSearch modal so users can
narrow search results by platform and Gen version. Platform uses
optionalFacetFilters for boosting (cross-platform results still appear,
ranked lower). Gen version uses hard filtering with Gen1/Gen2/Both
options. Defaults to All platforms and Gen 2.

Also adds getMissingResultsUrl so zero-result searches show a link to
report missing content on GitHub.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: harsh62

src/components/Layout/LayoutHeader.tsx

@@ -1,4 +1,4 @@
-import { useContext, useRef } from 'react';
+import { useContext, useRef, useState, useMemo } from 'react';
 import { useRouter } from 'next/router';
 import { Button, Flex, View, VisuallyHidden } from '@aws-amplify/ui-react';
 import classNames from 'classnames';
@@ -19,6 +19,8 @@ import { PageLastUpdated } from '../PageLastUpdated';
 import Feedback from '../Feedback';
 import RepoActions from '../Menu/RepoActions';
 import { usePathWithoutHash } from '@/utils/usePathWithoutHash';
+import { SearchFilters } from '@/components/Search';
+import type { GenFilter, PlatformFilter } from '@/components/Search';
 
 export const LayoutHeader = ({
   currentPlatform,
@@ -39,6 +41,14 @@ export const LayoutHeader = ({
   const router = useRouter();
   const asPathWithNoHash = usePathWithoutHash();
 
+  const [platformFilter, setPlatformFilter] = useState<PlatformFilter>('all');
+  const [genFilter, setGenFilter] = useState<GenFilter>('gen2');
+
+  const searchParams = useMemo(() => ({
+    ...(platformFilter !== 'all' && { optionalFacetFilters: [`platform:${platformFilter}`] }),
+    ...(genFilter !== 'both' && { facetFilters: [`gen:${genFilter}`] })
+  }), [platformFilter, genFilter]);
+
   const handleMenuToggle = () => {
     if (!menuOpen) {
       toggleMenuOpen(true);
@@ -90,13 +100,17 @@ export const LayoutHeader = ({
               appId={process.env.ALGOLIA_APP_ID || ALGOLIA_APP_ID}
               indexName={process.env.ALGOLIA_INDEX_NAME || ALGOLIA_INDEX_NAME}
               apiKey={process.env.ALGOLIA_API_KEY || ALGOLIA_API_KEY}
-              searchParameters={{
-                facetFilters: [
-                  `platform:${currentPlatform}`,
-                  `gen:${isGen1 ? 'gen1' : 'gen2'}`
-                ]
-              }}
+              searchParameters={searchParams}
               transformItems={transformItems}
+              getMissingResultsUrl={({ query }) =>
+                `https://github.com/aws-amplify/docs/issues/new?title=${encodeURIComponent(`[search] Missing results for: ${query}`)}&labels=v2`
+              }
+            />
+            <SearchFilters
+              platformFilter={platformFilter}
+              genFilter={genFilter}
+              onPlatformChange={setPlatformFilter}
+              onGenChange={setGenFilter}
             />
           </View>
         </View>

src/components/Search/SearchFilters.tsx

@@ -0,0 +1,91 @@
+import { useState, useEffect, useRef } from 'react';
+import { createPortal } from 'react-dom';
+import { PLATFORMS, PLATFORM_DISPLAY_NAMES } from '@/data/platforms';
+import type { Platform } from '@/data/platforms';
+
+export type GenFilter = 'gen1' | 'gen2' | 'both';
+export type PlatformFilter = Platform | 'all';
+
+interface SearchFiltersProps {
+  platformFilter: PlatformFilter;
+  genFilter: GenFilter;
+  onPlatformChange: (platform: PlatformFilter) => void;
+  onGenChange: (gen: GenFilter) => void;
+}
+
+const GEN_DISPLAY: Record<GenFilter, string> = {
+  gen2: 'Gen 2',
+  gen1: 'Gen 1',
+  both: 'Both'
+};
+
+export function SearchFilters({
+  platformFilter,
+  genFilter,
+  onPlatformChange,
+  onGenChange
+}: SearchFiltersProps) {
+  const [portalContainer, setPortalContainer] = useState<HTMLElement | null>(null);
+  const containerRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    const observer = new MutationObserver(() => {
+      const modal = document.querySelector('.DocSearch-Modal');
+      const searchBar = modal?.querySelector('.DocSearch-SearchBar');
+
+      if (searchBar && !modal?.querySelector('.search-filters-container')) {
+        const container = document.createElement('div');
+        container.className = 'search-filters-container';
+        searchBar.insertAdjacentElement('afterend', container);
+        containerRef.current = container;
+        setPortalContainer(container);
+      } else if (!modal) {
+        containerRef.current = null;
+        setPortalContainer(null);
+      }
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+    return () => {
+      observer.disconnect();
+      containerRef.current?.remove();
+    };
+  }, []);
+
+  if (!portalContainer) return null;
+
+  return createPortal(
+    <div className="search-filters" role="toolbar" aria-label="Search filters">
+      <div className="search-filters__group">
+        <span className="search-filters__label">Platform:</span>
+        <select
+          className="search-filters__select"
+          value={platformFilter}
+          onChange={(e) => onPlatformChange(e.target.value as PlatformFilter)}
+          aria-label="Platform filter"
+        >
+          <option value="all">All</option>
+          {PLATFORMS.map((p) => (
+            <option key={p} value={p}>
+              {PLATFORM_DISPLAY_NAMES[p]}
+            </option>
+          ))}
+        </select>
+      </div>
+      <div className="search-filters__separator" />
+      <div className="search-filters__group">
+        <span className="search-filters__label">Version:</span>
+        <select
+          className="search-filters__select"
+          value={genFilter}
+          onChange={(e) => onGenChange(e.target.value as GenFilter)}
+          aria-label="Generation filter"
+        >
+          <option value="gen2">{GEN_DISPLAY.gen2}</option>
+          <option value="gen1">{GEN_DISPLAY.gen1}</option>
+          <option value="both">{GEN_DISPLAY.both}</option>
+        </select>
+      </div>
+    </div>,
+    portalContainer
+  );
+}

src/components/Search/__tests__/SearchFilters.test.tsx

@@ -0,0 +1,83 @@
+import * as React from 'react';
+import { render, waitFor } from '@testing-library/react';
+import { SearchFilters } from '../SearchFilters';
+import type { GenFilter, PlatformFilter } from '../SearchFilters';
+
+describe('SearchFilters', () => {
+  let mockModal: HTMLElement;
+  let onPlatformChange: jest.Mock;
+  let onGenChange: jest.Mock;
+
+  beforeEach(() => {
+    onPlatformChange = jest.fn();
+    onGenChange = jest.fn();
+  });
+
+  afterEach(() => {
+    if (mockModal) mockModal.remove();
+  });
+
+  function renderFilters(
+    platformFilter: PlatformFilter = 'react',
+    genFilter: GenFilter = 'gen2'
+  ) {
+    const result = render(
+      <SearchFilters
+        platformFilter={platformFilter}
+        genFilter={genFilter}
+        onPlatformChange={onPlatformChange}
+        onGenChange={onGenChange}
+      />
+    );
+    // Simulate DocSearch modal DOM structure
+    mockModal = document.createElement('div');
+    mockModal.className = 'DocSearch-Modal';
+    const searchBar = document.createElement('div');
+    searchBar.className = 'DocSearch-SearchBar';
+    const form = document.createElement('form');
+    form.className = 'DocSearch-Form';
+    searchBar.appendChild(form);
+    mockModal.appendChild(searchBar);
+    document.body.appendChild(mockModal);
+    return result;
+  }
+
+  it('should render both select dropdowns inside the modal', async () => {
+    renderFilters();
+    await waitFor(() => {
+      expect(mockModal.querySelector('.search-filters')).toBeInTheDocument();
+    });
+    const selects = mockModal.querySelectorAll('.search-filters__select');
+    expect(selects.length).toBe(2);
+  });
+
+  it('should include "All" option in platform select', async () => {
+    renderFilters();
+    await waitFor(() => {
+      expect(mockModal.querySelector('.search-filters')).toBeInTheDocument();
+    });
+    const platformSelect = mockModal.querySelectorAll('.search-filters__select')[0] as HTMLSelectElement;
+    const options = Array.from(platformSelect.options).map((o) => o.value);
+    expect(options).toContain('all');
+    expect(options).toContain('react');
+  });
+
+  it('should include Gen options in version select', async () => {
+    renderFilters();
+    await waitFor(() => {
+      expect(mockModal.querySelector('.search-filters')).toBeInTheDocument();
+    });
+    const genSelect = mockModal.querySelectorAll('.search-filters__select')[1] as HTMLSelectElement;
+    const options = Array.from(genSelect.options).map((o) => o.value);
+    expect(options).toEqual(['gen2', 'gen1', 'both']);
+  });
+
+  it('should reflect current platform value', async () => {
+    renderFilters('swift', 'gen2');
+    await waitFor(() => {
+      expect(mockModal.querySelector('.search-filters')).toBeInTheDocument();
+    });
+    const platformSelect = mockModal.querySelectorAll('.search-filters__select')[0] as HTMLSelectElement;
+    expect(platformSelect.value).toBe('swift');
+  });
+});

src/components/Search/index.ts

@@ -0,0 +1,2 @@
+export { SearchFilters } from './SearchFilters';
+export type { GenFilter, PlatformFilter } from './SearchFilters';

src/styles/algolia.scss

@@ -105,3 +105,44 @@
     box-shadow: inset 0 0 0 2px var(--amplify-colors-border-focus);
   }
 }
+
+// Search filters — compact row below search input inside the modal
+.search-filters {
+  display: flex;
+  align-items: center;
+  gap: var(--amplify-space-xs);
+  padding: 6px var(--amplify-space-small);
+  border-bottom: 1px solid var(--amplify-colors-border-tertiary);
+  font-size: 11px;
+
+  &__group {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+  }
+
+  &__label {
+    color: var(--amplify-colors-font-tertiary);
+  }
+
+  &__separator {
+    width: 1px;
+    height: 16px;
+    background: var(--amplify-colors-border-tertiary);
+  }
+
+  &__select {
+    font-size: 11px;
+    padding: 2px 4px;
+    border: 1px solid var(--amplify-colors-border-secondary);
+    border-radius: var(--amplify-radii-small);
+    background: var(--amplify-colors-background-primary);
+    color: var(--amplify-colors-font-primary);
+    cursor: pointer;
+
+    &:focus-visible {
+      outline: 2px solid var(--amplify-colors-border-focus);
+      outline-offset: 1px;
+    }
+  }
+}