Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

feat: Create first scaffolding around search v2 and feature flag addition (#50236)

Jeremias Menichelli9bf43188f1b4
diff --git a/apps/docs/components/Navigation/NavigationMenu/TopNavBar.tsx b/apps/docs/components/Navigation/NavigationMenu/TopNavBar.tsx
index b41dbbe7896..db6ca275c1b 100644
--- a/apps/docs/components/Navigation/NavigationMenu/TopNavBar.tsx
+++ b/apps/docs/components/Navigation/NavigationMenu/TopNavBar.tsx
@@ -16,6 +16,7 @@ import { CommandMenuTriggerInput } from 'ui-patterns/CommandMenu'
import { getCustomContent } from '../../../lib/custom-content/getCustomContent'
import GlobalNavigationMenu from './GlobalNavigationMenu'
import useDropdownMenu from './useDropdownMenu'
+import { SearchV2Trigger, useSearchV2Variant } from '@/features/SearchV2'
const GlobalMobileMenu = dynamic(() => import('./GlobalMobileMenu'))
const TopNavDropdown = dynamic(() => import('./TopNavDropdown'))
@@ -28,6 +29,7 @@ const TopNavBar: FC = () => {
const [mobileMenuOpen, setMobileMenuOpen] = useState(false)
const user = useUser()
const menu = useDropdownMenu(user)
+ const searchVariant = useSearchV2Variant()
return (
<>
@@ -47,15 +49,27 @@ const TopNavBar: FC = () => {
<div className="flex gap-2 items-center">
<DevToolbarTrigger />
- <CommandMenuTriggerInput
- className="[&>div>p]:text-foreground-lighter"
- placeholder={
- <>
- Search
- <span className="hidden xl:inline ml-1"> docs...</span>
- </>
- }
- />
+ {searchVariant === 'search-v2-active' ? (
+ <SearchV2Trigger
+ className="[&>div>p]:text-foreground-lighter"
+ placeholder={
+ <>
+ Search
+ <span className="hidden xl:inline ml-1"> docs...</span>
+ </>
+ }
+ />
+ ) : (
+ <CommandMenuTriggerInput
+ className="[&>div>p]:text-foreground-lighter"
+ placeholder={
+ <>
+ Search
+ <span className="hidden xl:inline ml-1"> docs...</span>
+ </>
+ }
+ />
+ )}
<button
tabIndex={0}
title="Menu dropdown button"
diff --git a/apps/docs/features/SearchV2/SearchV2Dialog.tsx b/apps/docs/features/SearchV2/SearchV2Dialog.tsx
new file mode 100644
index 00000000000..f49a27c5c77
--- /dev/null
+++ b/apps/docs/features/SearchV2/SearchV2Dialog.tsx
@@ -0,0 +1,132 @@
+'use client'
+
+import { useDocsSearch, type DocsSearchResult } from 'common'
+import { Loader2 } from 'lucide-react'
+import { useRouter } from 'next/navigation'
+import { VisuallyHidden } from 'radix-ui'
+import { useEffect } from 'react'
+import {
+ Command,
+ CommandEmpty,
+ CommandGroup,
+ CommandInput,
+ CommandItem,
+ CommandList,
+ Dialog,
+ DialogContent,
+ DialogDescription,
+ DialogTitle,
+} from 'ui'
+
+interface SearchV2DialogProps {
+ open: boolean
+ onOpenChange: (open: boolean) => void
+}
+
+export function SearchV2Dialog({ open, onOpenChange }: SearchV2DialogProps) {
+ const router = useRouter()
+ const { searchState, handleDocsSearchDebounced, resetSearch } = useDocsSearch()
+
+ // Clear stale results once the dialog closes
+ useEffect(() => {
+ if (!open) resetSearch()
+ }, [open, resetSearch])
+
+ const results: DocsSearchResult[] =
+ 'results' in searchState
+ ? searchState.results
+ : 'staleResults' in searchState
+ ? searchState.staleResults
+ : []
+
+ function handleValueChange(value: string) {
+ if (value) {
+ handleDocsSearchDebounced(value)
+ } else {
+ resetSearch()
+ }
+ }
+
+ function handleSelect(path: string) {
+ router.push(path)
+ onOpenChange(false)
+ }
+
+ // Announced via the aria-live region below — a sighted user sees the spinner/list update,
+ // but a screen reader user gets no equivalent signal unless we say so explicitly. Also covers
+ // the result count, which isn't reliably announced by the listbox/option roles alone.
+ function getStatusMessage(): string {
+ if (searchState.status === 'loading') return 'Searching the docs…'
+ if (searchState.status === 'noResults') return 'No results found.'
+ if (searchState.status === 'error') return 'Something went wrong. Please try again.'
+ if (results.length > 0) {
+ return `${results.length} result${results.length === 1 ? '' : 's'} found.`
+ }
+ return ''
+ }
+
+ return (
+ <Dialog open={open} onOpenChange={onOpenChange}>
+ {/* hideClose: this is a search box, not a form — closing is Escape/click-outside only, no "X" */}
+ <DialogContent hideClose size="large" className="overflow-hidden p-0 shadow-lg">
+ <Command>
+ <VisuallyHidden.VisuallyHidden>
+ <DialogTitle>Search docs</DialogTitle>
+ <DialogDescription>Search the Supabase documentation</DialogDescription>
+ </VisuallyHidden.VisuallyHidden>
+ <CommandInput
+ placeholder="Search docs..."
+ aria-label="Search the Supabase documentation"
+ onValueChange={handleValueChange}
+ wrapperClassName="[&_svg]:h-5 [&_svg]:w-5 border-0"
+ className="h-14 text-base"
+ />
+ {/*
+ Screen-reader-only status announcement. Focus stays in the input as results come in
+ (that's what lets people keep typing), so nothing else here gets read aloud on its
+ own — this is what tells a screen reader user a search ran and how many results it found.
+ */}
+ <div role="status" aria-live="polite" className="sr-only">
+ {getStatusMessage()}
+ </div>
+ <CommandList label="Search results">
+ {searchState.status === 'initial' && (
+ <CommandEmpty>Start typing to search the docs.</CommandEmpty>
+ )}
+ {searchState.status === 'loading' && results.length === 0 && (
+ <div className="flex items-center justify-center gap-2 py-6 text-sm text-foreground-muted">
+ <Loader2 className="animate-spin" size={14} aria-hidden="true" />
+ Searching...
+ </div>
+ )}
+ {searchState.status === 'noResults' && <CommandEmpty>No results found.</CommandEmpty>}
+ {searchState.status === 'error' && (
+ <CommandEmpty>Something went wrong. Please try again.</CommandEmpty>
+ )}
+ {results.length > 0 && (
+ <CommandGroup heading="Results" forceMount>
+ {results.map((page) => (
+ <CommandItem
+ key={page.id}
+ value={String(page.id)}
+ forceMount
+ onSelect={() => handleSelect(page.path)}
+ >
+ <div className="flex flex-col">
+ <span className="text-sm">{page.title}</span>
+ {(page.description || page.subtitle) && (
+ <span className="text-xs text-foreground-muted">
+ {page.description || page.subtitle}
+ </span>
+ )}
+ </div>
+ </CommandItem>
+ ))}
+ </CommandGroup>
+ )}
+ </CommandList>
+ </Command>
+ </DialogContent>
+ </Dialog>
+ )
+}
diff --git a/apps/docs/features/SearchV2/SearchV2Trigger.tsx b/apps/docs/features/SearchV2/SearchV2Trigger.tsx
new file mode 100644
index 00000000000..ae91f54d1f8
--- /dev/null
+++ b/apps/docs/features/SearchV2/SearchV2Trigger.tsx
@@ -0,0 +1,75 @@
+'use client'
+
+import { Search } from 'lucide-react'
+import { useEffect, useState, type ReactNode } from 'react'
+import { cn, KeyboardShortcut } from 'ui'
+
+import { SearchV2Dialog } from './SearchV2Dialog'
+
+interface SearchV2TriggerProps {
+ className?: string
+ placeholder?: ReactNode
+}
+
+export function SearchV2Trigger({ className, placeholder = 'Search...' }: SearchV2TriggerProps) {
+ const [open, setOpen] = useState(false)
+
+ useEffect(() => {
+ function openOnKeyDown(event: globalThis.KeyboardEvent) {
+ if (event.key === 'k' && event.metaKey) {
+ /**
+ * This two methods prevent, first search V1 dialog to open and second
+ * browser propietary search commands to be fired, repectively.
+ */
+ event.stopImmediatePropagation()
+ event.preventDefault()
+
+ setOpen(true)
+ }
+ }
+
+ window.addEventListener('keydown', openOnKeyDown, { capture: true })
+
+ return () => {
+ window.removeEventListener('keydown', openOnKeyDown, { capture: true })
+ }
+ }, [])
+
+ return (
+ <>
+ <button
+ type="button"
+ tabIndex={0}
+ aria-haspopup="dialog"
+ aria-expanded={open}
+ onClick={() => setOpen(true)}
+ className={cn(
+ 'group cursor-pointer',
+ 'grow md:min-w-44 xl:min-w-56 h-[30px] rounded-md',
+ 'pl-1.5 md:pl-2 pr-1',
+ 'flex items-center justify-between',
+ 'bg-transparent text-foreground-lighter border border-strong',
+ 'hover:bg-popover hover:border-control-hover',
+ 'focus-ring',
+ 'transition-colors',
+ className
+ )}
+ >
+ <div className="flex items-center space-x-1.5 text-foreground-lighter">
+ <Search
+ size={16}
+ strokeWidth={1.5}
+ className="group-hover:text-foreground-light transition-colors"
+ />
+ <p className="flex text-xs pr-2 text-foreground-muted">{placeholder}</p>
+ </div>
+ <KeyboardShortcut
+ keys={['Meta', 'k']}
+ aria-hidden
+ className="hidden md:inline-flex border border-default bg-surface-300 text-foreground-lighter shadow-xs shadow-background-surface-100"
+ />
+ </button>
+ <SearchV2Dialog open={open} onOpenChange={setOpen} />
+ </>
+ )
+}
diff --git a/apps/docs/features/SearchV2/constants.ts b/apps/docs/features/SearchV2/constants.ts
new file mode 100644
index 00000000000..e934ed44244
--- /dev/null
+++ b/apps/docs/features/SearchV2/constants.ts
@@ -0,0 +1,4 @@
+// PostHog multivariate flag, already configured on staging.
+export const SEARCH_V2_FLAG = 'docs-search-v2'
+
+export type SearchV2Variant = 'control' | 'search-v2-active'
diff --git a/apps/docs/features/SearchV2/index.ts b/apps/docs/features/SearchV2/index.ts
new file mode 100644
index 00000000000..264c1c8f5e1
--- /dev/null
+++ b/apps/docs/features/SearchV2/index.ts
@@ -0,0 +1,2 @@
+export { SearchV2Trigger } from './SearchV2Trigger'
+export { useSearchV2Variant } from './useSearchV2Variant'
diff --git a/apps/docs/features/SearchV2/useSearchV2Variant.ts b/apps/docs/features/SearchV2/useSearchV2Variant.ts
new file mode 100644
index 00000000000..d9f515dc4cb
--- /dev/null
+++ b/apps/docs/features/SearchV2/useSearchV2Variant.ts
@@ -0,0 +1,25 @@
+'use client'
+
+import { useFeatureFlags, useSearchParamsShallow } from 'common'
+
+import { SEARCH_V2_FLAG, type SearchV2Variant } from './constants'
+import { IS_PRODUCTION } from '@/lib/constants'
+
+const VARIANTS: SearchV2Variant[] = ['control', 'search-v2-active']
+
+/**
+ * Reads the `docs-search-v2` PostHog experiment flag.
+ * Defaults to `'control'` while the flag store is loading or if the flag is unset,
+ * so an unresolved state always falls back to the current search experience.
+ */
+export function useSearchV2Variant(): SearchV2Variant {
+ const { posthog } = useFeatureFlags()
+ const searchParams = useSearchParamsShallow()
+ const override = searchParams.get(SEARCH_V2_FLAG)
+
+ if (VARIANTS.includes(override as SearchV2Variant)) {
+ return override as SearchV2Variant
+ }
+
+ return posthog[SEARCH_V2_FLAG] === 'search-v2-active' ? 'search-v2-active' : 'control'
+}