Command K (#5)

* cleanup from base-stack

* sidebar initial working version

* functional table of content component

* small change in the knip.json

* custom script to validate content folder positions inside frontmatter, and some fixes in sidebar, toc and ocumentation page

* updated readme.md file

* updated readme.md file

* small refactoring and added documnetation for some components

* footer component

* initial theme switcher, changes on UI, additional components

* fonts, some fixes

* small change

* convention xx-file-name.mdx update - still updates needed

* refactoring

* small changes and updated package.json

* ts fix?

* ts fix?

* ts fix?

* ts fix?

* ts fix?

* sidebar fix

* added content folder and some fixes and improvements in UI

* removed _index route, added index.mdx file for hopemage, reorganized routes.ts

* refactoring

* small update in update-frontmatter logic

* small refactoring

* small ui improvements

* small ui improvements

* refactoring

* command palette component - initial version

* refactoring

* theme toggle fix

* refactoring ad vitest tests for some helper functions

* small refactoring

* fix in breadcrumbs building

* fix in breadcrumbs building

* unit tests and small improvements

* comments and tests

* refactoring

* initial changes

* small fixes

* fixed so it doesnt contains v1.0.1 now

* fixes

* small update

* small fixes

* small change

* small update

* dropdown versions and fixed build script

* check-with no verify

* small fix in sidebar

* working version

* for now in url for documentation page it will be shown every verion, even last one

* dropdown fix

* load content collections fix

* sorting tags in versions.ts

* refactoring

* improvements

* update

* updated docs.build.ts

* updates with docs.build.ts

* small update

* updates

* updates

* changes

* updates

* small changes

* small fix in breadcrumbs tests

* small update

* removed DEFAULT_BRANCH env from the yml and passed using cli args in the generate:docs command

* small update

* reorganized and refactored command k

* fix to work with multiple versions

* refactoring

* fix with versions and search history

* refactoring

* removed unused icons

* small refactoring

* fixes to handle search on server side

* refactoring

* update so search Index is created on the app startup

* small fix

* small fix

* small updates

Author: abrulic

app/components/backdrop.tsx

@@ -0,0 +1,13 @@
+import { cn } from "~/utils/css"
+
+export const Backdrop = ({ onClose }: { onClose: () => void }) => (
+	// biome-ignore lint/a11y/useKeyWithClickEvents: We don't need keyboard events for backdrop
+	<div
+		className={cn("fixed inset-0 bg-[var(--color-modal-backdrop)] backdrop-blur-sm transition-opacity duration-200")}
+		onClick={(e) => {
+			if (e.target === e.currentTarget) {
+				onClose()
+			}
+		}}
+	/>
+)

app/components/command-k/components/command-k.tsx

@@ -0,0 +1,135 @@
+import { useRef, useState } from "react"
+import { useTranslation } from "react-i18next"
+import { useNavigate } from "react-router"
+import { Modal } from "~/components/modal"
+import type { Version } from "~/utils/version-resolvers"
+import { useKeyboardNavigation } from "../hooks/use-keyboard-navigation"
+import { useModalState } from "../hooks/use-modal-state"
+import { useSearch } from "../hooks/use-search"
+import { useSearchHistory } from "../hooks/use-search-history"
+import type { HistoryItem, MatchType, SearchResult } from "../search-types"
+import { EmptyState } from "./empty-state"
+import { ResultsFooter } from "./results-footer"
+import { SearchHistory } from "./search-history"
+import { SearchInput } from "./search-input"
+import { SearchResultRow } from "./search-result"
+import { TriggerButton } from "./trigger-button"
+
+interface CommandPaletteProps {
+	placeholder?: string
+	version: Version
+}
+
+export const CommandK = ({ placeholder, version }: CommandPaletteProps) => {
+	const { t } = useTranslation()
+	const navigate = useNavigate()
+	const inputRef = useRef<HTMLInputElement>(null)
+	const [query, setQuery] = useState("")
+	const { isOpen, openModal, closeModal } = useModalState()
+	const { history, addToHistory, clearHistory, removeFromHistory } = useSearchHistory(version)
+	const { results, search } = useSearch({ version })
+
+	const hasQuery = !!query.trim()
+	const hasResults = !!results.length
+	const hasHistory = !!history.length
+	const searchPlaceholder = placeholder ?? t("placeholders.search_documentation")
+
+	const handleClose = () => {
+		closeModal()
+		setQuery("")
+		search("")
+	}
+
+	const navigateToPage = (id: string) => {
+		const path = [version, id]
+			.filter(Boolean)
+			.map((s) => s.replace(/^\/+|\/+$/g, ""))
+			.join("/")
+
+		navigate(`/${path}`)
+	}
+
+	const handleResultSelect = (result: SearchResult) => {
+		if (!isOpen) return
+		const rowItem = result.item
+		const matchType: MatchType = result.refIndex === 0 ? "heading" : "paragraph"
+		const historyItem = {
+			...rowItem,
+			type: matchType,
+			highlightedText: result.highlightedText,
+		}
+
+		addToHistory(historyItem)
+		navigateToPage(rowItem.id)
+		handleClose()
+	}
+
+	const handleHistorySelect = (item: HistoryItem) => {
+		navigateToPage(item.id)
+		handleClose()
+	}
+
+	const handleToggle = () => {
+		isOpen ? handleClose() : openModal()
+	}
+
+	const { selectedIndex } = useKeyboardNavigation({
+		isOpen,
+		results,
+		onSelect: handleResultSelect,
+		onClose: handleClose,
+		onToggle: handleToggle,
+	})
+
+	if (!isOpen) {
+		return <TriggerButton onOpen={openModal} placeholder={searchPlaceholder} />
+	}
+
+	const renderBody = () => {
+		if (hasQuery) {
+			if (!hasResults) return <EmptyState query={query} />
+
+			return results.map((result, index) => (
+				<SearchResultRow
+					key={`${result.item.id}-${result.refIndex}`}
+					item={result.item}
+					highlightedText={result.highlightedText}
+					isSelected={index === selectedIndex}
+					onClick={() => handleResultSelect(result)}
+					matchType={result.refIndex === 0 ? "heading" : "paragraph"}
+				/>
+			))
+		}
+
+		if (hasHistory) {
+			return (
+				<SearchHistory
+					history={history}
+					onSelect={handleHistorySelect}
+					onRemove={removeFromHistory}
+					onClear={clearHistory}
+				/>
+			)
+		}
+
+		return <EmptyState />
+	}
+
+	return (
+		<Modal isOpen={isOpen} onClose={handleClose} getInitialFocus={() => inputRef.current} ariaLabel={searchPlaceholder}>
+			<SearchInput
+				ref={inputRef}
+				value={query}
+				onChange={(val) => {
+					setQuery(val)
+					search(val.trim())
+				}}
+				placeholder={searchPlaceholder}
+			/>
+			<div className="max-h-96 overflow-y-auto overscroll-contain" aria-label={searchPlaceholder}>
+				{renderBody()}
+			</div>
+			<ResultsFooter resultsCount={results.length} query={query} />
+		</Modal>
+	)
+}

app/components/command-k/components/empty-state.tsx

@@ -0,0 +1,29 @@
+import { useTranslation } from "react-i18next"
+import { KeyboardHint } from "./keyboard-hint"
+import { ResultsFooterNote } from "./results-footer-note"
+
+export const EmptyState = ({ query }: { query?: string }) => {
+	const { t } = useTranslation()
+	if (query) {
+		return (
+			<div className="px-4 py-8 text-center">
+				<p className="font-medium text-[var(--color-empty-text)]">
+					{t("text.no_results_for")} "{query}"
+				</p>
+				<p className="mt-1 text-[var(--color-empty-text-muted)] text-sm">{t("text.adjust_search")}</p>
+			</div>
+		)
+	}
+
+	return (
+		<div className="space-y-6 px-4 py-8 text-center">
+			<p className="mb-4 font-medium text-[var(--color-empty-text)]">{t("text.start_typing_to_search")}</p>
+			<div className="flex items-center justify-center gap-6 text-[var(--color-empty-text-muted)] text-xs">
+				<KeyboardHint keys={["↑", "↓"]} label={t("controls.navigate")} />
+				<KeyboardHint keys="↵" label={t("controls.select")} />
+				<KeyboardHint keys="⇥" label={t("controls.cycle")} />
+			</div>
+			<ResultsFooterNote />
+		</div>
+	)
+}

app/components/command-k/components/keyboard-hint.tsx

@@ -0,0 +1,21 @@
+import { Kbd } from "~/ui/kbd"
+import { cn } from "~/utils/css"
+
+interface KeyboardHintProps {
+	keys: string | string[]
+	label: string
+	className?: string
+}
+
+export const KeyboardHint = ({ keys, label, className }: KeyboardHintProps) => {
+	const keyArray = Array.isArray(keys) ? keys : [keys]
+
+	return (
+		<div className={cn("flex items-center gap-1", className)}>
+			{keyArray.map((key) => (
+				<Kbd key={key}>{key}</Kbd>
+			))}
+			<span>{label}</span>
+		</div>
+	)
+}

app/components/command-k/components/results-footer-note.tsx

@@ -0,0 +1,15 @@
+import { useTranslation } from "react-i18next"
+
+export const ResultsFooterNote = () => {
+	const { t } = useTranslation()
+	return (
+		<span className="text-[var(--color-footer-text)] text-xs opacity-70">
+			{t("p.search_by")}{" "}
+			<span className="font-semibold">
+				<a href="https://www.forge42.dev/" target="_blank" rel="noopener noreferrer">
+					Forge 42
+				</a>
+			</span>
+		</span>
+	)
+}

app/components/command-k/components/results-footer.tsx

@@ -0,0 +1,28 @@
+import { useTranslation } from "react-i18next"
+import { cn } from "~/utils/css"
+import { KeyboardHint } from "./keyboard-hint"
+import { ResultsFooterNote } from "./results-footer-note"
+
+export const ResultsFooter = ({
+	resultsCount,
+	query,
+}: {
+	resultsCount: number
+	query: string
+}) => {
+	const { t } = useTranslation()
+	if (!query || resultsCount === 0) return null
+
+	return (
+		<div className={cn("border-[var(--color-footer-border)] border-t bg-[var(--color-footer-bg)] px-4 py-3")}>
+			<div className="flex items-center justify-between text-xs">
+				<span className="font-medium text-[var(--color-footer-text)]">{t("text.result", { count: resultsCount })}</span>
+				<div className="flex items-center gap-4 text-[var(--color-footer-text)]">
+					<KeyboardHint keys={["↑", "↓"]} label={t("controls.navigate")} />
+					<KeyboardHint keys="↵" label={t("controls.select")} />
+					<ResultsFooterNote />
+				</div>
+			</div>
+		</div>
+	)
+}

app/components/command-k/components/search-history.tsx

@@ -0,0 +1,122 @@
+import { useTranslation } from "react-i18next"
+import { Icon } from "~/ui/icon/icon"
+import { cn } from "~/utils/css"
+import type { HistoryItem } from "../search-types"
+import { SearchResultRow } from "./search-result"
+interface SearchHistoryProps {
+	history: HistoryItem[]
+	onSelect: (item: HistoryItem) => void
+	onRemove: (id: string) => void
+	onClear: () => void
+}
+
+const SearchHistoryHeader = ({ onClear }: Pick<SearchHistoryProps, "onClear">) => {
+	const { t } = useTranslation()
+	return (
+		<div
+			className={cn(
+				"flex items-center justify-between border-[var(--color-history-header-border)] border-b",
+				"bg-[var(--color-history-header-bg)] px-4 py-3"
+			)}
+		>
+			<div className="flex items-center gap-2">
+				<Icon name="Clock" className="size-4 text-[var(--color-result-meta)]" />
+				<span className="font-medium text-[var(--color-history-header-text)] text-sm">{t("text.recent_searches")}</span>
+			</div>
+			<ClearHistoryButton onClear={onClear} />
+		</div>
+	)
+}
+
+const ClearHistoryButton = ({ onClear }: Pick<SearchHistoryProps, "onClear">) => {
+	const { t } = useTranslation()
+	return (
+		<button
+			type="button"
+			onClick={onClear}
+			className={cn(
+				"flex items-center gap-1 rounded px-2 py-1 text-xs transition-colors",
+				"text-[var(--color-result-meta)] hover:bg-[var(--color-history-clear-hover-bg)] hover:text-[var(--color-history-clear-hover-text)]"
+			)}
+			title="Clear history"
+			aria-label="Clear search history"
+		>
+			<Icon name="Trash2" className="size-3" />
+			<span className="hidden sm:inline">{t("buttons.clear")}</span>
+		</button>
+	)
+}
+
+const RemoveItemButton = ({
+	onRemove,
+	id,
+}: {
+	onRemove: Pick<SearchHistoryProps, "onRemove">["onRemove"]
+	id: string
+}) => (
+	<button
+		type="button"
+		onClick={(e) => {
+			e.stopPropagation()
+			onRemove(id)
+		}}
+		className={cn(
+			"-translate-y-1/2 absolute top-1/2 right-2 flex h-6 w-6 items-center justify-center rounded-full border opacity-0 transition-all duration-150 group-hover:opacity-100",
+			"border-[var(--color-history-remove-border)] bg-[var(--color-history-remove-bg)] text-[var(--color-history-remove-text)]",
+			"hover:border-[var(--color-history-remove-hover-border)] hover:text-[var(--color-history-remove-hover-text)]"
+		)}
+		title="Remove from history"
+		aria-label={"Remove from history"}
+	>
+		<Icon name="X" className="size-3" />
+	</button>
+)
+
+const HistoryItemRow = ({
+	item,
+	index,
+	onSelect,
+	onRemove,
+}: {
+	item: HistoryItem
+	index: number
+	onSelect: Pick<SearchHistoryProps, "onSelect">["onSelect"]
+	onRemove: Pick<SearchHistoryProps, "onRemove">["onRemove"]
+}) => (
+	<div key={`${item.id}-${index}`} className="group relative">
+		<SearchResultRow
+			item={item}
+			highlightedText={item.highlightedText ?? item.title}
+			isSelected={false}
+			onClick={() => onSelect(item)}
+			matchType={item.type ?? "heading"}
+		/>
+		<RemoveItemButton onRemove={onRemove} id={item.id} />
+	</div>
+)
+
+const HistoryItemsList = ({
+	history,
+	onSelect,
+	onRemove,
+}: {
+	history: HistoryItem[]
+	onSelect: Pick<SearchHistoryProps, "onSelect">["onSelect"]
+	onRemove: Pick<SearchHistoryProps, "onRemove">["onRemove"]
+}) => (
+	<div className="max-h-64 overflow-y-auto">
+		{history.map((item, index) => (
+			<HistoryItemRow key={`${item.id}-${index}`} item={item} index={index} onSelect={onSelect} onRemove={onRemove} />
+		))}
+	</div>
+)
+
+export const SearchHistory = ({ history, onSelect, onRemove, onClear }: SearchHistoryProps) => {
+	if (history.length === 0) return null
+	return (
+		<div>
+			<SearchHistoryHeader onClear={onClear} />
+			<HistoryItemsList history={history} onSelect={onSelect} onRemove={onRemove} />
+		</div>
+	)
+}