Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
feat: add tabs for keyword research (#185)
Ben Senescu0bfdc56c454d
diff --git a/src/client/features/keywords/components/DisplayPrimitives.tsx b/src/client/features/keywords/components/DisplayPrimitives.tsxindex c7a551ac..cd51db48 100644--- a/src/client/features/keywords/components/DisplayPrimitives.tsx+++ b/src/client/features/keywords/components/DisplayPrimitives.tsx@@ -11,7 +11,7 @@ import {YAxis,} from "recharts";import type { MonthlySearch } from "@/types/keywords";-import { formatNumber } from "../utils";+import { formatCompactNumber } from "../utils";import { FloatingTooltip, useFloatingTooltip } from "./FloatingTooltip";export type SortField =@@ -148,10 +148,10 @@ export function AreaTrendChart({ trend }: { trend: MonthlySearch[] }) {/><YAxistickFormatter={(value: number | string) =>- formatNumber(Number(value))+ formatCompactNumber(Number(value))}tick={{ fill: "var(--trend-axis-color)", fontSize: 11 }}- width={56}+ width={44}axisLine={false}tickLine={false}/>diff --git a/src/client/features/keywords/hooks/useKeywordControlsForm.ts b/src/client/features/keywords/hooks/useKeywordControlsForm.tsindex 5ad1dac8..5b1db082 100644--- a/src/client/features/keywords/hooks/useKeywordControlsForm.ts+++ b/src/client/features/keywords/hooks/useKeywordControlsForm.ts@@ -5,19 +5,29 @@ import {shouldValidateFieldOnChange,} from "@/client/lib/forms";import {+ MAX_KEYWORDS_PER_SUBMIT,type KeywordMode,type ResultLimit,} from "@/client/features/keywords/keywordResearchTypes";import { parseKeywordInput } from "@/client/features/keywords/state/keywordControllerActions";+type KeywordTabValidationInput = {+ keyword: string;+ locationCode: number;+ resultLimit: ResultLimit;+ mode: KeywordMode;+};+type UseKeywordControlsFormInput = {keywordInput: string;locationCode: number;resultLimit: ResultLimit;keywordMode: KeywordMode;+ getOpenKeywordTabs?: () => readonly KeywordTabValidationInput[];+ keywordTabsLimit?: number;};-type KeywordControlsValues = {+export type KeywordControlsValues = {keyword: string;locationCode: number;resultLimit: ResultLimit;@@ -27,22 +37,86 @@ type KeywordControlsValues = {function getKeywordSearchValidationErrors(value: KeywordControlsValues,shouldValidateUntouchedField: boolean,+ validateEmptyKeyword: boolean,) {- if (parseKeywordInput(value.keyword).length > 0) {- return null;+ const keywords = parseKeywordInput(value.keyword);++ if (keywords.length === 0) {+ if (!validateEmptyKeyword) return null;+ return createFormValidationErrors({+ fields: {+ keyword: "Please enter at least one keyword.",+ },+ });}- if (!shouldValidateUntouchedField) {- return null;+ if (!shouldValidateUntouchedField) return null;++ if (keywords.length > MAX_KEYWORDS_PER_SUBMIT) {+ return createFormValidationErrors({+ fields: {+ keyword: `Please enter no more than ${MAX_KEYWORDS_PER_SUBMIT} keywords (one per line).`,+ },+ });}+ return null;+}++function getKeywordTabCapacityError(+ value: KeywordControlsValues,+ openKeywordTabs: readonly KeywordTabValidationInput[] | undefined,+ keywordTabsLimit: number | undefined,+) {+ if (!openKeywordTabs || keywordTabsLimit == null) return null;++ const keywords = parseKeywordInput(value.keyword);+ if (keywords.length === 0) return null;++ let simulatedOpenTabs = [...openKeywordTabs];+ let skippedCount = 0;++ for (const keyword of keywords) {+ const input = {+ keyword,+ locationCode: value.locationCode,+ resultLimit: value.resultLimit,+ mode: value.mode,+ };+ const alreadyOpen = simulatedOpenTabs.some((tab) =>+ keywordTabMatches(tab, input),+ );+ if (alreadyOpen) continue;++ if (simulatedOpenTabs.length >= keywordTabsLimit) {+ skippedCount += 1;+ continue;+ }++ simulatedOpenTabs = [...simulatedOpenTabs, input];+ }++ if (skippedCount === 0) return null;+return createFormValidationErrors({fields: {- keyword: "Please enter at least one keyword.",+ keyword: `${skippedCount} keyword${skippedCount === 1 ? "" : "s"} skipped - close a tab to open more (max ${keywordTabsLimit}).`,},});}+function keywordTabMatches(+ tab: KeywordTabValidationInput,+ input: KeywordTabValidationInput,+) {+ return (+ tab.keyword === input.keyword &&+ tab.locationCode === input.locationCode &&+ tab.resultLimit === input.resultLimit &&+ tab.mode === input.mode+ );+}+export function useKeywordControlsForm(input: UseKeywordControlsFormInput,onSubmit: (value: KeywordControlsValues) => void,@@ -59,8 +133,15 @@ export function useKeywordControlsForm(getKeywordSearchValidationErrors(value,shouldValidateFieldOnChange(formApi, "keyword"),+ false,+ ),+ onSubmit: ({ value }) =>+ getKeywordSearchValidationErrors(value, true, true) ??+ getKeywordTabCapacityError(+ value,+ input.getOpenKeywordTabs?.(),+ input.keywordTabsLimit,),- onSubmit: ({ value }) => getKeywordSearchValidationErrors(value, true),},onSubmit: ({ value }) => {onSubmit(value);diff --git a/src/client/features/keywords/hooks/useKeywordResearchData.ts b/src/client/features/keywords/hooks/useKeywordResearchData.tsindex 381d0f72..d4ec9a39 100644--- a/src/client/features/keywords/hooks/useKeywordResearchData.ts+++ b/src/client/features/keywords/hooks/useKeywordResearchData.ts@@ -4,6 +4,7 @@ import { getStandardErrorMessage } from "@/client/lib/error-messages";import { captureClientEvent } from "@/client/lib/posthog";import { LOCATIONS, getLanguageCode } from "@/client/features/keywords/utils";import { DEFAULT_LOCATION_CODE } from "@/client/features/keywords/locations";+import { parseKeywordInput } from "@/client/features/keywords/state/keywordControllerActions";import { researchKeywords } from "@/serverFunctions/keywords";import type {KeywordMode,@@ -35,16 +36,29 @@ type KeywordResearchRequest = {mode: KeywordMode;};-const KEYWORD_RESEARCH_STALE_TIME_MS = 24 * 60 * 60 * 1000;+export const KEYWORD_RESEARCH_STALE_TIME_MS = 24 * 60 * 60 * 1000;-function parseSearchKeywords(value: string) {- return value- .split(/[\n,]/)- .map((keyword) => keyword.trim())- .filter(Boolean);+export function buildKeywordResearchRequest(+ input: KeywordResearchQueryInput,+): KeywordResearchRequest | null {+ const keywords = parseKeywordInput(input.keywordInput);+ const seedKeyword = keywords[0] ?? "";+ if (!seedKeyword) return null;++ return {+ projectId: input.projectId,+ keywords,+ seedKeyword,+ locationCode: input.locationCode,+ languageCode: getLanguageCode(input.locationCode),+ resultLimit: input.resultLimit,+ mode: input.mode,+ };}-function buildKeywordResearchQueryKey(request: KeywordResearchRequest | null) {+export function buildKeywordResearchQueryKey(+ request: KeywordResearchRequest | null,+) {return request? ["keywordResearch",@@ -58,34 +72,35 @@ function buildKeywordResearchQueryKey(request: KeywordResearchRequest | null) {: ["keywordResearch", "idle"];}+export function keywordResearchQueryFn(request: KeywordResearchRequest) {+ return researchKeywords({+ data: {+ projectId: request.projectId,+ keywords: request.keywords,+ locationCode: request.locationCode,+ languageCode: request.languageCode,+ resultLimit: request.resultLimit,+ mode: request.mode,+ },+ });+}+export function useKeywordResearchData(input: KeywordResearchQueryInput,addSearch: AddSearchFn,) {- const keywords = useMemo(- () => parseSearchKeywords(input.keywordInput),- [input.keywordInput],+ const { keywordInput, locationCode, mode, projectId, resultLimit } = input;+ const request = useMemo<KeywordResearchRequest | null>(+ () =>+ buildKeywordResearchRequest({+ keywordInput,+ locationCode,+ mode,+ projectId,+ resultLimit,+ }),+ [keywordInput, locationCode, mode, projectId, resultLimit],);- const request = useMemo<KeywordResearchRequest | null>(() => {- const seedKeyword = keywords[0] ?? "";- if (!seedKeyword) return null;-- return {- projectId: input.projectId,- keywords,- seedKeyword,- locationCode: input.locationCode,- languageCode: getLanguageCode(input.locationCode),- resultLimit: input.resultLimit,- mode: input.mode,- };- }, [- input.locationCode,- input.mode,- input.projectId,- input.resultLimit,- keywords,- ]);const queryKey = useMemo(() => buildKeywordResearchQueryKey(request),[request],@@ -99,16 +114,7 @@ export function useKeywordResearchData(throw new Error("Keyword research query ran without request params");}- return researchKeywords({- data: {- projectId: request.projectId,- keywords: request.keywords,- locationCode: request.locationCode,- languageCode: request.languageCode,- resultLimit: request.resultLimit,- mode: request.mode,- },- });+ return keywordResearchQueryFn(request);},enabled: request !== null,staleTime: KEYWORD_RESEARCH_STALE_TIME_MS,diff --git a/src/client/features/keywords/keywordResearchTypes.ts b/src/client/features/keywords/keywordResearchTypes.tsindex 72853d4d..37578f5a 100644--- a/src/client/features/keywords/keywordResearchTypes.ts+++ b/src/client/features/keywords/keywordResearchTypes.ts@@ -1,3 +1,5 @@+export const MAX_KEYWORDS_PER_SUBMIT = 5;+export type ResultLimit = 150 | 300 | 500;export const RESULT_LIMITS: ResultLimit[] = [150, 300, 500];diff --git a/src/client/features/keywords/page/KeywordResearchDesktopResults.tsx b/src/client/features/keywords/page/KeywordResearchDesktopResults.tsxindex 01b1d0ee..6d48cd8d 100644--- a/src/client/features/keywords/page/KeywordResearchDesktopResults.tsx+++ b/src/client/features/keywords/page/KeywordResearchDesktopResults.tsx@@ -22,6 +22,10 @@ import {FilterTextInput,} from "./keywordResearchDesktopFilters";import { KeywordResearchDesktopTable } from "./KeywordResearchDesktopTable";+import {+ KeywordResearchPagination,+ useKeywordResearchPagination,+} from "./KeywordResearchPagination";const MONTH_SHORT_LABELS = ["Jan",@@ -64,7 +68,7 @@ type Props = {export function KeywordResearchDesktopResults({ controller }: Props) {return (- <div className="flex-1 hidden md:flex flex-col xl:flex-row overflow-y-auto xl:overflow-hidden gap-4 mt-2">+ <div className="flex-1 hidden md:flex flex-col xl:flex-row overflow-y-auto xl:overflow-hidden gap-4"><DesktopKeywordPanel controller={controller} /><DesktopSerpPanel controller={controller} /></div>@@ -114,6 +118,8 @@ function DesktopTableCard({ controller }: Props) {sheetsExportRows,showFilters,} = controller;+ const { page, pageSize, pageRows, setPage, setPageSize } =+ useKeywordResearchPagination(filteredRows);const keywordCountLabel =selectedRows.size > 0@@ -192,7 +198,7 @@ function DesktopTableCard({ controller }: Props) {{showFilters ? <DesktopFilters controller={controller} /> : null}<KeywordResearchDesktopTableactiveFilterCount={controller.activeFilterCount}- filteredRows={controller.filteredRows}+ filteredRows={pageRows}overviewKeyword={controller.overviewKeyword}selectedRows={controller.selectedRows}setSelectedRows={controller.setSelectedRows}@@ -202,6 +208,15 @@ function DesktopTableCard({ controller }: Props) {resetFilters={controller.resetFilters}handleRowClick={controller.handleRowClick}/>+ {filteredRows.length > 0 ? (+ <KeywordResearchPagination+ page={page}+ pageSize={pageSize}+ totalCount={filteredRows.length}+ onPageChange={setPage}+ onPageSizeChange={setPageSize}+ />+ ) : null}</div>);}diff --git a/src/client/features/keywords/page/KeywordResearchLoadingState.tsx b/src/client/features/keywords/page/KeywordResearchLoadingState.tsxindex 26bec0ae..c666019e 100644--- a/src/client/features/keywords/page/KeywordResearchLoadingState.tsx+++ b/src/client/features/keywords/page/KeywordResearchLoadingState.tsx@@ -1,7 +1,7 @@export function KeywordResearchLoadingState() {return (- <div className="flex-1 w-full pt-1">- <div className="hidden md:flex h-full gap-4 mt-2">+ <div className="flex-1 w-full">+ <div className="hidden md:flex h-full gap-4"><div className="flex-1 flex flex-col min-w-0 gap-2"><div className="rounded-xl border border-base-300 bg-base-100 p-4"><div className="skeleton h-5 w-56" />@@ -46,7 +46,7 @@ export function KeywordResearchLoadingState() {</div></div>- <div className="md:hidden mt-2 space-y-3">+ <div className="md:hidden space-y-3"><div className="rounded-xl border border-base-300 bg-base-100 p-4 space-y-3"><div className="skeleton h-8 w-full" /><div className="skeleton h-8 w-2/3" />diff --git a/src/client/features/keywords/page/KeywordResearchMobileResults.tsx b/src/client/features/keywords/page/KeywordResearchMobileResults.tsxindex 861720fd..a9eb0d16 100644--- a/src/client/features/keywords/page/KeywordResearchMobileResults.tsx+++ b/src/client/features/keywords/page/KeywordResearchMobileResults.tsx@@ -11,6 +11,10 @@ import { KEYWORD_RESEARCH_HEADERS } from "@/client/features/keywords/state/keywoimport { exportTableToSheets } from "@/client/lib/exportToSheets";import { SerpAnalysisCard } from "@/client/features/keywords/components";import { KeywordResearchDesktopTable } from "./KeywordResearchDesktopTable";+import {+ KeywordResearchPagination,+ useKeywordResearchPagination,+} from "./KeywordResearchPagination";import type { KeywordResearchControllerState } from "./types";type Props = {@@ -74,6 +78,8 @@ function MobileKeywordResults({ controller }: Props) {sheetsExportRows,showFilters,} = controller;+ const { page, pageSize, pageRows, setPage, setPageSize } =+ useKeywordResearchPagination(filteredRows);const keywordCountLabel =selectedRows.size > 0@@ -162,7 +168,7 @@ function MobileKeywordResults({ controller }: Props) {<KeywordResearchDesktopTableactiveFilterCount={controller.activeFilterCount}- filteredRows={controller.filteredRows}+ filteredRows={pageRows}overviewKeyword={controller.overviewKeyword}selectedRows={controller.selectedRows}setSelectedRows={controller.setSelectedRows}@@ -172,6 +178,15 @@ function MobileKeywordResults({ controller }: Props) {resetFilters={controller.resetFilters}handleRowClick={controller.handleRowClick}/>+ {filteredRows.length > 0 ? (+ <KeywordResearchPagination+ page={page}+ pageSize={pageSize}+ totalCount={filteredRows.length}+ onPageChange={setPage}+ onPageSizeChange={setPageSize}+ />+ ) : null}</div>);}diff --git a/src/client/features/keywords/page/KeywordResearchPage.tsx b/src/client/features/keywords/page/KeywordResearchPage.tsxindex 3cd8278a..cb3b1367 100644--- a/src/client/features/keywords/page/KeywordResearchPage.tsx+++ b/src/client/features/keywords/page/KeywordResearchPage.tsx@@ -1,23 +1,274 @@import { Link } from "@tanstack/react-router";+import { useQuery } from "@tanstack/react-query";+import { useCallback, useEffect, useMemo } from "react";import { AlertCircle, ArrowLeft } from "lucide-react";import { getErrorCode } from "@/client/lib/error-messages";import { BILLING_ROUTE } from "@/shared/billing";+import {+ KEYWORD_RESEARCH_STALE_TIME_MS,+ buildKeywordResearchQueryKey,+ buildKeywordResearchRequest,+ keywordResearchQueryFn,+} from "@/client/features/keywords/hooks/useKeywordResearchData";import { useKeywordResearchController } from "@/client/features/keywords/state/useKeywordResearchController";import type { KeywordResearchControllerInput } from "@/client/features/keywords/state/useKeywordResearchController";+import type { KeywordControlsValues } from "@/client/features/keywords/hooks/useKeywordControlsForm";+import {+ parseKeywordInput,+ buildKeywordSearchKey,+} from "@/client/features/keywords/state/keywordControllerActions";+import { useKeywordSearchParams } from "@/client/features/keywords/state/keywordControllerInternals";+import { useKeywordTabs } from "@/client/features/keywords/state/useKeywordTabs";+import {+ getKeywordTabsSnapshot,+ type OpenTabInput,+} from "@/client/features/keywords/state/keywordTabsStore";+import { DEFAULT_LOCATION_CODE } from "@/client/features/keywords/locations";import { KeywordResearchEmptyState } from "./KeywordResearchEmptyState";import { KeywordResearchLoadingState } from "./KeywordResearchLoadingState";import { KeywordResearchResults } from "./KeywordResearchResults";import { KeywordResearchSearchBar } from "./KeywordResearchSearchBar";+import { KeywordResearchTabStrip } from "./KeywordResearchTabStrip";import type { KeywordResearchControllerState } from "./types";-type Props = KeywordResearchControllerInput;+type Props = Omit<KeywordResearchControllerInput, "onFormSubmit">;export function KeywordResearchPage(input: Props) {- const controller = useKeywordResearchController(input);+ const tabs = useKeywordTabs(input.projectId);+ const { openTabs, setActiveTab, findMatchingTab } = tabs;+ const setSearchParams = useKeywordSearchParams();+ const projectId = input.projectId;++ const setSearchParamsForTab = useCallback(+ (tab: OpenTabInput | null) => {+ if (!tab) {+ setSearchParams({+ q: undefined,+ loc: undefined,+ kLimit: undefined,+ mode: undefined,+ });+ return;+ }++ setSearchParams({+ q: tab.keyword,+ loc:+ tab.locationCode === DEFAULT_LOCATION_CODE+ ? undefined+ : tab.locationCode,+ kLimit: tab.resultLimit === 150 ? undefined : tab.resultLimit,+ mode: tab.mode === "auto" ? undefined : tab.mode,+ });+ },+ [setSearchParams],+ );++ const urlInput = useMemo<OpenTabInput | null>(() => {+ const keywords = parseKeywordInput(input.keywordInput);+ const keyword = keywords[0];+ if (!keyword) return null;+ return {+ keyword,+ locationCode: input.locationCode,+ resultLimit: input.resultLimit,+ mode: input.keywordMode,+ };+ }, [+ input.keywordInput,+ input.keywordMode,+ input.locationCode,+ input.resultLimit,+ ]);+ const currentUrlKey = useMemo(+ () =>+ buildKeywordSearchKey({+ keyword: input.keywordInput,+ locationCode: input.locationCode,+ resultLimit: input.resultLimit,+ mode: input.keywordMode,+ }),+ [+ input.keywordInput,+ input.keywordMode,+ input.locationCode,+ input.resultLimit,+ ],+ );++ // Effect: URL → activeTab. When the URL params resolve to a tab we already+ // have, focus it. Otherwise create one matching the URL (handles deep links+ // and back/forward navigation).+ useEffect(() => {+ if (!urlInput) {+ if (getKeywordTabsSnapshot(projectId).activeTabId !== null) {+ setActiveTab(null);+ }+ return;+ }++ const existing = findMatchingTab(urlInput);+ if (existing) {+ if (getKeywordTabsSnapshot(projectId).activeTabId !== existing.id) {+ setActiveTab(existing.id);+ }+ return;+ }++ openTabs([urlInput]);+ }, [urlInput, projectId, openTabs, setActiveTab, findMatchingTab]);++ // Effect: activeTab → URL. After user actions (click tab, close tab, open+ // tabs from a multi-keyword submit) the active tab can diverge from the URL.+ // Re-align the URL so the controller below keeps reading the right query.+ const activeTab = tabs.activeTab;+ const activeTabUrlKey = useMemo(+ () =>+ activeTab+ ? buildKeywordSearchKey({+ keyword: activeTab.keyword,+ locationCode: activeTab.locationCode,+ resultLimit: activeTab.resultLimit,+ mode: activeTab.mode,+ })+ : null,+ [activeTab],+ );+ useEffect(() => {+ if (!activeTab) return;++ if (currentUrlKey === activeTabUrlKey) return;++ setSearchParamsForTab(activeTab);+ }, [+ activeTab,+ activeTab?.id,+ activeTab?.keyword,+ activeTab?.locationCode,+ activeTab?.resultLimit,+ activeTab?.mode,+ activeTabUrlKey,+ currentUrlKey,+ setSearchParamsForTab,+ ]);++ const onFormSubmit = useCallback(+ (value: KeywordControlsValues) => {+ const keywords = parseKeywordInput(value.keyword);+ if (keywords.length === 0) return;++ const inputs: OpenTabInput[] = keywords.map((keyword) => ({+ keyword,+ locationCode: value.locationCode,+ resultLimit: value.resultLimit,+ mode: value.mode,+ }));++ const result = openTabs(inputs);+ if (result.activeTab) setSearchParamsForTab(result.activeTab);+ },+ [openTabs, setSearchParamsForTab],+ );+ const closeTab = useCallback(+ (tabId: string) => {+ const result = tabs.closeTab(tabId);+ if (result.closedActive) {+ setSearchParamsForTab(result.nextActiveTab);+ }+ },+ [setSearchParamsForTab, tabs],+ );+ const getOpenKeywordTabs = useCallback(+ () => getKeywordTabsSnapshot(projectId).tabs,+ [projectId],+ );++ const controllerInput = useMemo<Props>(+ () =>+ activeTab+ ? {+ ...input,+ keywordInput: activeTab.keyword,+ locationCode: activeTab.locationCode,+ hasExplicitLocationCode: true,+ resultLimit: activeTab.resultLimit,+ keywordMode: activeTab.mode,+ getOpenKeywordTabs,+ keywordTabsLimit: tabs.limit,+ }+ : {+ ...input,+ getOpenKeywordTabs,+ keywordTabsLimit: tabs.limit,+ },+ [activeTab, getOpenKeywordTabs, input, tabs.limit],+ );+ const controller = useKeywordResearchController({+ ...controllerInput,+ onFormSubmit,+ });+ useEffect(() => {+ controller.controlsForm.setErrorMap({ onSubmit: undefined });+ controller.controlsForm.setFieldMeta("keyword", (meta) => ({+ ...meta,+ errorMap: {+ ...meta.errorMap,+ onSubmit: undefined,+ },+ errorSourceMap: {+ ...meta.errorSourceMap,+ onSubmit: undefined,+ },+ }));+ }, [controller.controlsForm, tabs.tabs]);++ // Mark the active tab as viewed once its data lands. Reads cache state via+ // the same query key the controller uses, so this catches both fresh fetches+ // and warm-cache loads on tab switch.+ const activeRequest = useMemo(+ () =>+ activeTab+ ? buildKeywordResearchRequest({+ projectId,+ keywordInput: activeTab.keyword,+ locationCode: activeTab.locationCode,+ resultLimit: activeTab.resultLimit,+ mode: activeTab.mode,+ })+ : null,+ [activeTab, projectId],+ );+ const activeTabQuery = useQuery({+ queryKey: buildKeywordResearchQueryKey(activeRequest),+ queryFn: () => {+ if (!activeRequest) throw new Error("Active tab missing request");+ return keywordResearchQueryFn(activeRequest);+ },+ enabled: false,+ staleTime: KEYWORD_RESEARCH_STALE_TIME_MS,+ gcTime: KEYWORD_RESEARCH_STALE_TIME_MS,+ });++ const markTabViewed = tabs.markTabViewed;+ useEffect(() => {+ if (!activeTab) return;+ if (!activeTabQuery.isSuccess) return;+ const dataUpdatedAt = activeTabQuery.dataUpdatedAt;+ if (dataUpdatedAt <= 0) return;+ if (activeTab.viewedAt !== null && activeTab.viewedAt >= dataUpdatedAt) {+ return;+ }+ markTabViewed(activeTab.id, dataUpdatedAt);+ }, [+ activeTab,+ activeTabQuery.dataUpdatedAt,+ activeTabQuery.isSuccess,+ markTabViewed,+ ]);return (<div className="px-4 py-4 md:px-6 md:py-6 pb-24 md:pb-8 overflow-auto">- <div className="mx-auto max-w-7xl space-y-4">+ <div className="mx-auto flex max-w-7xl flex-col gap-5"><div><h1 className="text-2xl font-semibold">Keyword Research</h1><p className="text-sm text-base-content/70">@@ -26,6 +277,30 @@ export function KeywordResearchPage(input: Props) {</div><KeywordResearchSearchBar controller={controller} />+ {controller.hasSearched ? (+ <div className="flex flex-col gap-2">+ <Link+ from="/p/$projectId/keywords"+ to="/p/$projectId/keywords"+ params={{ projectId }}+ search={{}}+ replace+ className="btn btn-ghost btn-sm w-fit gap-2 px-0 text-base-content/70 hover:bg-transparent"+ onClick={() => {+ setActiveTab(null);+ setSearchParamsForTab(null);+ }}+ >+ <ArrowLeft className="size-4" />+ Recent searches+ </Link>+ <KeywordResearchTabStrip+ projectId={projectId}+ tabs={tabs}+ closeTab={closeTab}+ />+ </div>+ ) : null}<KeywordResearchContentcontroller={controller}projectId={input.projectId}@@ -43,22 +318,6 @@ function KeywordResearchContent({controller: KeywordResearchControllerState;projectId: string;}) {- const recentSearchesButton = controller.hasSearched ? (- <div>- <Link- from="/p/$projectId/keywords"- to="/p/$projectId/keywords"- params={{ projectId }}- search={{}}- replace- className="btn btn-ghost btn-sm gap-2 px-0 text-base-content/70 hover:bg-transparent"- >- <ArrowLeft className="size-4" />- Recent searches- </Link>- </div>- ) : null;-if (controller.isLoading) {return <KeywordResearchLoadingState />;}@@ -68,24 +327,21 @@ function KeywordResearchContent({getErrorCode(controller.researchMutationError) === "INSUFFICIENT_CREDITS";return (- <div className="space-y-4 pt-1">- {recentSearchesButton}- <div className="flex-1 flex items-center justify-center">- <div className="w-full max-w-xl rounded-xl border border-error/30 bg-error/10 p-5 text-error space-y-3">- <div className="flex items-start gap-2">- <AlertCircle className="mt-0.5 size-4 shrink-0" />- <p className="text-sm">{controller.researchError}</p>- </div>- {isCreditsError ? (- <Link to={BILLING_ROUTE} className="btn btn-sm">- Go to Billing- </Link>- ) : (- <button className="btn btn-sm" onClick={controller.retrySearch}>- Try again- </button>- )}+ <div className="flex-1 flex items-center justify-center pt-1">+ <div className="w-full max-w-xl rounded-xl border border-error/30 bg-error/10 p-5 text-error space-y-3">+ <div className="flex items-start gap-2">+ <AlertCircle className="mt-0.5 size-4 shrink-0" />+ <p className="text-sm">{controller.researchError}</p></div>+ {isCreditsError ? (+ <Link to={BILLING_ROUTE} className="btn btn-sm">+ Go to Billing+ </Link>+ ) : (+ <button className="btn btn-sm" onClick={controller.retrySearch}>+ Try again+ </button>+ )}</div></div>);@@ -93,22 +349,14 @@ function KeywordResearchContent({if (controller.rows.length === 0) {return (- <div className="space-y-4 pt-1">- {recentSearchesButton}- <KeywordResearchEmptyState- controller={controller}- projectId={projectId}- />- </div>+ <KeywordResearchEmptyState+ controller={controller}+ projectId={projectId}+ />);}- return (- <div className="space-y-4 pt-1">- {recentSearchesButton}- <KeywordResearchResults controller={controller} />- </div>- );+ return <KeywordResearchResults controller={controller} />;}function KeywordSaveDialog({diff --git a/src/client/features/keywords/page/KeywordResearchPagination.tsx b/src/client/features/keywords/page/KeywordResearchPagination.tsxnew file mode 100644index 00000000..cbeaf571--- /dev/null+++ b/src/client/features/keywords/page/KeywordResearchPagination.tsx@@ -0,0 +1,150 @@+import { ChevronLeft, ChevronRight } from "lucide-react";+import { useEffect, useMemo, useState } from "react";+import type { KeywordResearchRow } from "@/types/keywords";++const KEYWORD_RESEARCH_PAGE_SIZES = [50, 100, 300, 500] as const;+const DEFAULT_KEYWORD_RESEARCH_PAGE_SIZE = 50;+const KEYWORD_RESEARCH_PAGE_SIZE_STORAGE_KEY =+ "keyword-research-table-page-size";++type KeywordResearchPageSize = (typeof KEYWORD_RESEARCH_PAGE_SIZES)[number];++type Props = {+ page: number;+ pageSize: KeywordResearchPageSize;+ totalCount: number;+ onPageChange: (page: number) => void;+ onPageSizeChange: (pageSize: KeywordResearchPageSize) => void;+};++export function KeywordResearchPagination({+ page,+ pageSize,+ totalCount,+ onPageChange,+ onPageSizeChange,+}: Props) {+ const totalPages = Math.max(1, Math.ceil(totalCount / pageSize));+ const start = totalCount === 0 ? 0 : (page - 1) * pageSize + 1;+ const end = Math.min(totalCount, page * pageSize);++ return (+ <div className="flex flex-col gap-3 border-t border-base-300 px-4 py-3 sm:flex-row sm:items-center sm:justify-between">+ <div className="text-sm tabular-nums text-base-content/70">+ {start.toLocaleString()}-{end.toLocaleString()} of{" "}+ {totalCount.toLocaleString()}+ </div>+ <div className="flex items-center gap-6">+ <label className="flex items-center gap-2 text-sm text-base-content/70">+ <span className="whitespace-nowrap">Rows per page</span>+ <select+ className="select select-bordered select-sm w-20"+ value={pageSize}+ onChange={(event) =>+ onPageSizeChange(parseKeywordResearchPageSize(event.target.value))+ }+ >+ {KEYWORD_RESEARCH_PAGE_SIZES.map((size) => (+ <option key={size} value={size}>+ {size}+ </option>+ ))}+ </select>+ </label>+ <div className="flex items-center gap-2">+ <span className="whitespace-nowrap text-sm tabular-nums text-base-content/70">+ Page {page.toLocaleString()} of {totalPages.toLocaleString()}+ </span>+ <div className="flex items-center gap-1">+ <button+ type="button"+ className="btn btn-ghost btn-sm btn-square"+ disabled={page <= 1}+ onClick={() => onPageChange(page - 1)}+ aria-label="Previous page"+ >+ <ChevronLeft className="size-4" />+ </button>+ <button+ type="button"+ className="btn btn-ghost btn-sm btn-square"+ disabled={page >= totalPages}+ onClick={() => onPageChange(page + 1)}+ aria-label="Next page"+ >+ <ChevronRight className="size-4" />+ </button>+ </div>+ </div>+ </div>+ </div>+ );+}++function parseKeywordResearchPageSize(value: string): KeywordResearchPageSize {+ const parsed = Number(value);+ return (+ KEYWORD_RESEARCH_PAGE_SIZES.find((size) => size === parsed) ??+ DEFAULT_KEYWORD_RESEARCH_PAGE_SIZE+ );+}++export function useKeywordResearchPagination(rows: KeywordResearchRow[]) {+ const [page, setPage] = useState(1);+ const [pageSize, setPageSize] = useState<KeywordResearchPageSize>(() =>+ getStoredKeywordResearchPageSize(),+ );+ const totalPages = Math.max(1, Math.ceil(rows.length / pageSize));++ useEffect(() => {+ setPage(1);+ }, [rows]);++ useEffect(() => {+ setPage((current) => Math.min(current, totalPages));+ }, [totalPages]);++ const pageRows = useMemo(() => {+ const start = (page - 1) * pageSize;+ return rows.slice(start, start + pageSize);+ }, [page, pageSize, rows]);++ return {+ page,+ pageSize,+ pageRows,+ setPage,+ setPageSize: (nextPageSize: KeywordResearchPageSize) => {+ setPageSize(nextPageSize);+ persistKeywordResearchPageSize(nextPageSize);+ setPage(1);+ },+ totalPages,+ };+}++function getStoredKeywordResearchPageSize(): KeywordResearchPageSize {+ if (typeof window === "undefined") return DEFAULT_KEYWORD_RESEARCH_PAGE_SIZE;+ try {+ const stored = window.localStorage.getItem(+ KEYWORD_RESEARCH_PAGE_SIZE_STORAGE_KEY,+ );+ return stored+ ? parseKeywordResearchPageSize(stored)+ : DEFAULT_KEYWORD_RESEARCH_PAGE_SIZE;+ } catch {+ return DEFAULT_KEYWORD_RESEARCH_PAGE_SIZE;+ }+}++function persistKeywordResearchPageSize(pageSize: KeywordResearchPageSize) {+ if (typeof window === "undefined") return;+ try {+ window.localStorage.setItem(+ KEYWORD_RESEARCH_PAGE_SIZE_STORAGE_KEY,+ String(pageSize),+ );+ } catch {+ // localStorage can be unavailable; keep the in-memory selection working.+ }+}diff --git a/src/client/features/keywords/page/KeywordResearchResults.tsx b/src/client/features/keywords/page/KeywordResearchResults.tsxindex 4ac0e34a..f543378b 100644--- a/src/client/features/keywords/page/KeywordResearchResults.tsx+++ b/src/client/features/keywords/page/KeywordResearchResults.tsx@@ -8,7 +8,7 @@ type Props = {export function KeywordResearchResults({ controller }: Props) {return (- <div className="flex-1 flex flex-col overflow-hidden w-full pt-1">+ <div className="flex-1 flex flex-col overflow-hidden w-full"><KeywordResearchDesktopResults controller={controller} /><KeywordResearchMobileResults controller={controller} /></div>diff --git a/src/client/features/keywords/page/KeywordResearchSearchBar.tsx b/src/client/features/keywords/page/KeywordResearchSearchBar.tsxindex df7a07ad..a7ae130e 100644--- a/src/client/features/keywords/page/KeywordResearchSearchBar.tsx+++ b/src/client/features/keywords/page/KeywordResearchSearchBar.tsx@@ -4,7 +4,10 @@ import {isResultLimit,normalizeKeywordMode,} from "@/client/features/keywords/keywordSearchParams";-import { RESULT_LIMITS } from "@/client/features/keywords/keywordResearchTypes";+import {+ MAX_KEYWORDS_PER_SUBMIT,+ RESULT_LIMITS,+} from "@/client/features/keywords/keywordResearchTypes";import { LOCATION_OPTIONS } from "@/client/features/keywords/locations";import type { KeywordResearchControllerState } from "./types";@@ -12,30 +15,52 @@ type Props = {controller: KeywordResearchControllerState;};+function getTextareaRows(value: string): number {+ const newlines = (value.match(/\n/g) ?? []).length;+ const lines = newlines + 1;+ return Math.min(MAX_KEYWORDS_PER_SUBMIT, Math.max(1, lines));+}+export function KeywordResearchSearchBar({ controller }: Props) {- const { controlsForm, handleSearchSubmit, isLoading } = controller;+ const { controlsForm, handleSearchSubmit } = controller;return (<div className="card border border-base-300 bg-base-100"><div className="card-body gap-2"><form- className="flex flex-col gap-3 lg:flex-row lg:flex-wrap lg:items-center lg:gap-2"+ className="flex flex-col gap-3 lg:flex-row lg:flex-wrap lg:items-start lg:gap-2"onSubmit={handleSearchSubmit}><controlsForm.Field name="keyword">{(field) => {const keywordError = getFieldError(field.state.meta.errors);+ const rows = getTextareaRows(field.state.value);return (<label- className={`input input-bordered flex items-center gap-2 w-full lg:flex-1 lg:min-w-0 lg:max-w-md ${keywordError ? "input-error" : ""}`}+ className={`flex w-full lg:flex-1 lg:min-w-0 lg:max-w-md items-start gap-2 rounded-lg border bg-base-100 px-4 py-3 transition-colors focus-within:border-primary ${+ keywordError ? "border-error" : "border-base-300"+ }`}>- <Search className="size-4 shrink-0 text-base-content/60" />- <input- className="grow min-w-0"- placeholder="Enter keyword"+ <Search className="mt-0.5 size-4 shrink-0 text-base-content/60" />+ <textarea+ className="grow min-w-0 resize-none bg-transparent text-sm leading-6 outline-none placeholder:text-base-content/40"+ rows={rows}+ placeholder="Enter keywords, one per line"value={field.state.value}onChange={(event) => field.handleChange(event.target.value)}+ onKeyDown={(event) => {+ // Cmd/Ctrl+Enter submits without leaving a stray newline.+ // Bare Enter stays as the textarea default (insert newline)+ // so multi-keyword input remains discoverable.+ if (+ event.key === "Enter" &&+ (event.metaKey || event.ctrlKey)+ ) {+ event.preventDefault();+ void controlsForm.handleSubmit();+ }+ }}/></label>);@@ -100,9 +125,8 @@ export function KeywordResearchSearchBar({ controller }: Props) {<buttontype="submit"className="btn btn-primary w-full px-6 font-semibold lg:w-auto lg:shrink-0"- disabled={isLoading}>- {isLoading ? "Searching..." : "Search"}+ Search</button></div></form>diff --git a/src/client/features/keywords/page/KeywordResearchTabStrip.tsx b/src/client/features/keywords/page/KeywordResearchTabStrip.tsxnew file mode 100644index 00000000..b04a74b2--- /dev/null+++ b/src/client/features/keywords/page/KeywordResearchTabStrip.tsx@@ -0,0 +1,132 @@+import { useQuery } from "@tanstack/react-query";+import { X } from "lucide-react";+import { memo } from "react";+import {+ KEYWORD_RESEARCH_STALE_TIME_MS,+ buildKeywordResearchQueryKey,+ buildKeywordResearchRequest,+ keywordResearchQueryFn,+} from "@/client/features/keywords/hooks/useKeywordResearchData";+import type {+ KeywordTab,+ UseKeywordTabsReturn,+} from "@/client/features/keywords/state/useKeywordTabs";++type Props = {+ projectId: string;+ tabs: UseKeywordTabsReturn;+ closeTab: (tabId: string) => void;+};++export function KeywordResearchTabStrip({ projectId, tabs, closeTab }: Props) {+ if (tabs.tabs.length === 0) return null;++ return (+ <div className="rounded-xl border border-base-300 bg-base-100 p-1">+ <div+ role="tablist"+ className="flex min-w-0 items-stretch gap-1 overflow-x-auto"+ >+ {tabs.tabs.map((tab) => (+ <TabPill+ key={tab.id}+ tab={tab}+ projectId={projectId}+ active={tab.id === tabs.activeTabId}+ setActiveTab={tabs.setActiveTab}+ closeTab={closeTab}+ />+ ))}+ </div>+ </div>+ );+}++const TabPill = memo(function TabPill({+ tab,+ projectId,+ active,+ setActiveTab,+ closeTab,+}: {+ tab: KeywordTab;+ projectId: string;+ active: boolean;+ setActiveTab: (tabId: string | null) => void;+ closeTab: (tabId: string) => void;+}) {+ const request = buildKeywordResearchRequest({+ projectId,+ keywordInput: tab.keyword,+ locationCode: tab.locationCode,+ resultLimit: tab.resultLimit,+ mode: tab.mode,+ });+ const queryKey = buildKeywordResearchQueryKey(request);++ // enabled: false — observer only. The active tab's controller owns fetching.+ const query = useQuery({+ queryKey,+ queryFn: () => {+ if (!request) throw new Error("Tab is missing a research request");+ return keywordResearchQueryFn(request);+ },+ enabled: false,+ select: () => null,+ notifyOnChangeProps: ["dataUpdatedAt", "errorUpdatedAt"],+ staleTime: KEYWORD_RESEARCH_STALE_TIME_MS,+ gcTime: KEYWORD_RESEARCH_STALE_TIME_MS,+ });++ const hasResult = query.dataUpdatedAt > 0;+ const unviewed =+ !active &&+ hasResult &&+ (tab.viewedAt === null || tab.viewedAt < query.dataUpdatedAt);+ const isError = query.isError;++ return (+ <div+ role="tab"+ aria-selected={active}+ tabIndex={0}+ onClick={() => setActiveTab(tab.id)}+ onKeyDown={(event) => {+ if (event.key === "Enter" || event.key === " ") {+ event.preventDefault();+ setActiveTab(tab.id);+ }+ }}+ className={`group flex shrink-0 cursor-pointer items-center gap-1.5 rounded-md px-2.5 py-1.5 text-sm transition ${+ active+ ? "bg-base-300 text-base-content shadow-sm"+ : "text-base-content/80 hover:bg-base-200"+ }`}+ >+ <span+ className="flex w-3.5 shrink-0 items-center justify-center"+ aria-hidden+ >+ {isError ? (+ <span className="size-2 rounded-full bg-error" />+ ) : unviewed ? (+ <span className="size-2 rounded-full bg-primary" />+ ) : null}+ </span>+ <span className="max-w-[10rem] truncate font-medium" title={tab.keyword}>+ {tab.keyword}+ </span>+ <button+ type="button"+ className="rounded p-0.5 text-base-content/50 opacity-60 transition hover:bg-base-content/10 hover:text-base-content hover:opacity-100 group-hover:opacity-100"+ onClick={(event) => {+ event.stopPropagation();+ closeTab(tab.id);+ }}+ aria-label={`Close ${tab.keyword} tab`}+ >+ <X className="size-3.5" />+ </button>+ </div>+ );+});diff --git a/src/client/features/keywords/state/keywordControllerInternals.ts b/src/client/features/keywords/state/keywordControllerInternals.tsindex 64d07252..13e59d63 100644--- a/src/client/features/keywords/state/keywordControllerInternals.ts+++ b/src/client/features/keywords/state/keywordControllerInternals.ts@@ -1,6 +1,6 @@import { useNavigate } from "@tanstack/react-router";import { useMutation, useQueryClient } from "@tanstack/react-query";-import { useState } from "react";+import { useCallback, useState } from "react";import { usePreferredKeywordLocation } from "@/client/features/keywords/hooks/usePreferredKeywordLocation";import { saveKeywords } from "@/serverFunctions/keywords";import type { SaveKeywordsInput } from "@/types/schemas/keywords";@@ -42,12 +42,15 @@ export function useKeywordUiState(initialShowFilters: boolean) {export function useKeywordSearchParams() {const navigate = useNavigate({ from: "/p/$projectId/keywords" });- return (updates: Record<string, string | number | boolean | undefined>) => {- void navigate({- search: (prev) => ({ ...prev, ...updates }),- replace: true,- });- };+ return useCallback(+ (updates: Record<string, string | number | boolean | undefined>) => {+ void navigate({+ search: (prev) => ({ ...prev, ...updates }),+ replace: true,+ });+ },+ [navigate],+ );}export function useKeywordSaveMutation(projectId: string) {diff --git a/src/client/features/keywords/state/keywordTabsStore.ts b/src/client/features/keywords/state/keywordTabsStore.tsnew file mode 100644index 00000000..72a50ece--- /dev/null+++ b/src/client/features/keywords/state/keywordTabsStore.ts@@ -0,0 +1,291 @@+import type {+ KeywordMode,+ ResultLimit,+} from "@/client/features/keywords/keywordResearchTypes";++export type KeywordTab = {+ id: string;+ keyword: string;+ locationCode: number;+ resultLimit: ResultLimit;+ mode: KeywordMode;+ createdAt: number;+ viewedAt: number | null;+};++export type ProjectTabsState = {+ tabs: KeywordTab[];+ activeTabId: string | null;+};++export type OpenTabInput = {+ keyword: string;+ locationCode: number;+ resultLimit: ResultLimit;+ mode: KeywordMode;+};++type OpenTabsResult = {+ opened: KeywordTab[];+ focused: KeywordTab[];+ activeTab: KeywordTab | null;+ dropped: OpenTabInput[];+};++export const KEYWORD_TABS_LIMIT = 8;+export const EMPTY_TABS_STATE: ProjectTabsState = {+ tabs: [],+ activeTabId: null,+};++const STORAGE_KEY_PREFIX = "keyword-tabs:";+const CHANGE_EVENT = "keyword-tabs-change";++// Module-level cache. Returning stable references keeps useSyncExternalStore+// from infinite-looping on Object.is equality checks.+const projectStates = new Map<string, ProjectTabsState>();++function storageKey(projectId: string): string {+ return `${STORAGE_KEY_PREFIX}${projectId}`;+}++function isRecord(value: unknown): value is Record<string, unknown> {+ return typeof value === "object" && value !== null;+}++function isResultLimit(value: unknown): value is ResultLimit {+ return value === 150 || value === 300 || value === 500;+}++function isKeywordMode(value: unknown): value is KeywordMode {+ return (+ value === "auto" ||+ value === "related" ||+ value === "suggestions" ||+ value === "ideas"+ );+}++function parseTab(value: unknown): KeywordTab | null {+ if (!isRecord(value)) return null;+ if (typeof value.id !== "string" || value.id === "") return null;+ if (typeof value.keyword !== "string" || value.keyword === "") return null;+ if (typeof value.locationCode !== "number") return null;+ if (!isResultLimit(value.resultLimit)) return null;+ if (!isKeywordMode(value.mode)) return null;+ if (typeof value.createdAt !== "number") return null;+ const viewedAt =+ value.viewedAt === null+ ? null+ : typeof value.viewedAt === "number"+ ? value.viewedAt+ : null;+ return {+ id: value.id,+ keyword: value.keyword,+ locationCode: value.locationCode,+ resultLimit: value.resultLimit,+ mode: value.mode,+ createdAt: value.createdAt,+ viewedAt,+ };+}++function parseStoredState(value: unknown): ProjectTabsState {+ if (!isRecord(value)) return EMPTY_TABS_STATE;+ if (!Array.isArray(value.tabs)) return EMPTY_TABS_STATE;+ const tabs: KeywordTab[] = [];+ for (const raw of value.tabs) {+ const parsed = parseTab(raw);+ if (parsed) tabs.push(parsed);+ }+ const activeTabId =+ typeof value.activeTabId === "string" &&+ tabs.some((tab) => tab.id === value.activeTabId)+ ? value.activeTabId+ : null;+ return { tabs, activeTabId };+}++function loadFromStorage(projectId: string): ProjectTabsState {+ if (typeof window === "undefined") return EMPTY_TABS_STATE;+ try {+ const raw = window.sessionStorage.getItem(storageKey(projectId));+ if (!raw) return EMPTY_TABS_STATE;+ const parsed: unknown = JSON.parse(raw);+ return parseStoredState(parsed);+ } catch {+ return EMPTY_TABS_STATE;+ }+}++function persist(projectId: string, state: ProjectTabsState) {+ if (typeof window === "undefined") return;+ try {+ window.sessionStorage.setItem(storageKey(projectId), JSON.stringify(state));+ } catch {+ // sessionStorage unavailable or full; in-memory cache still works.+ }+}++function notify() {+ if (typeof window === "undefined") return;+ window.dispatchEvent(new Event(CHANGE_EVENT));+}++export function getKeywordTabsSnapshot(projectId: string): ProjectTabsState {+ let state = projectStates.get(projectId);+ if (!state) {+ state = loadFromStorage(projectId);+ projectStates.set(projectId, state);+ }+ return state;+}++export function subscribeKeywordTabsStore(onChange: () => void): () => void {+ if (typeof window === "undefined") return () => {};+ window.addEventListener(CHANGE_EVENT, onChange);+ return () => window.removeEventListener(CHANGE_EVENT, onChange);+}++function update(+ projectId: string,+ updater: (current: ProjectTabsState) => ProjectTabsState,+) {+ const current = getKeywordTabsSnapshot(projectId);+ const next = updater(current);+ if (next === current) return;+ projectStates.set(projectId, next);+ persist(projectId, next);+ notify();+}++function generateTabId(): string {+ if (typeof crypto !== "undefined" && "randomUUID" in crypto) {+ return crypto.randomUUID();+ }+ return `tab_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;+}++function tabMatches(tab: KeywordTab, input: OpenTabInput): boolean {+ return (+ tab.keyword === input.keyword &&+ tab.locationCode === input.locationCode &&+ tab.resultLimit === input.resultLimit &&+ tab.mode === input.mode+ );+}++export function findMatchingTab(+ state: ProjectTabsState,+ input: OpenTabInput,+): KeywordTab | null {+ return state.tabs.find((tab) => tabMatches(tab, input)) ?? null;+}++export function openTabs(+ projectId: string,+ inputs: OpenTabInput[],+): OpenTabsResult {+ const opened: KeywordTab[] = [];+ const focused: KeywordTab[] = [];+ const dropped: OpenTabInput[] = [];+ let resultActiveTab: KeywordTab | null = null;++ update(projectId, (current) => {+ let tabs = current.tabs;+ let activeTabId = current.activeTabId;++ for (const input of inputs) {+ const existing = tabs.find((tab) => tabMatches(tab, input));+ if (existing) {+ focused.push(existing);+ activeTabId = existing.id;+ resultActiveTab = existing;+ continue;+ }++ if (tabs.length >= KEYWORD_TABS_LIMIT) {+ dropped.push(input);+ continue;+ }++ const next: KeywordTab = {+ id: generateTabId(),+ keyword: input.keyword,+ locationCode: input.locationCode,+ resultLimit: input.resultLimit,+ mode: input.mode,+ createdAt: Date.now(),+ viewedAt: null,+ };+ tabs = [...tabs, next];+ opened.push(next);+ activeTabId = next.id;+ resultActiveTab = next;+ }++ if (tabs === current.tabs && activeTabId === current.activeTabId) {+ return current;+ }+ return { tabs, activeTabId };+ });++ return { opened, focused, activeTab: resultActiveTab, dropped };+}++export function setActiveTab(projectId: string, tabId: string | null) {+ update(projectId, (current) => {+ if (current.activeTabId === tabId) return current;+ if (tabId !== null && !current.tabs.some((tab) => tab.id === tabId)) {+ return current;+ }+ return { ...current, activeTabId: tabId };+ });+}++export function closeTab(+ projectId: string,+ tabId: string,+): { nextActiveTab: KeywordTab | null; closedActive: boolean } {+ let nextActiveTab: KeywordTab | null = null;+ let closedActive = false;++ update(projectId, (current) => {+ const index = current.tabs.findIndex((tab) => tab.id === tabId);+ if (index === -1) return current;++ const tabs = current.tabs.filter((tab) => tab.id !== tabId);+ let activeTabId = current.activeTabId;++ if (current.activeTabId === tabId) {+ closedActive = true;+ // Activate the right neighbor, fall back to the left, fall back to null.+ const neighbor = tabs[index] ?? tabs[index - 1] ?? null;+ activeTabId = neighbor?.id ?? null;+ nextActiveTab = neighbor;+ }++ return { tabs, activeTabId };+ });++ return { nextActiveTab, closedActive };+}++export function markTabViewed(+ projectId: string,+ tabId: string,+ when = Date.now(),+) {+ update(projectId, (current) => {+ let changed = false;+ const tabs = current.tabs.map((tab) => {+ if (tab.id !== tabId) return tab;+ if (tab.viewedAt !== null && tab.viewedAt >= when) return tab;+ changed = true;+ return { ...tab, viewedAt: when };+ });+ if (!changed) return current;+ return { ...current, tabs };+ });+}diff --git a/src/client/features/keywords/state/useKeywordResearchController.ts b/src/client/features/keywords/state/useKeywordResearchController.tsindex 70dae316..fd877314 100644--- a/src/client/features/keywords/state/useKeywordResearchController.ts+++ b/src/client/features/keywords/state/useKeywordResearchController.ts@@ -1,5 +1,8 @@import { useCallback, useEffect, useRef, type FormEvent } from "react";-import { useKeywordControlsForm } from "@/client/features/keywords/hooks/useKeywordControlsForm";+import {+ useKeywordControlsForm,+ type KeywordControlsValues,+} from "@/client/features/keywords/hooks/useKeywordControlsForm";import { useKeywordFiltering } from "@/client/features/keywords/hooks/useKeywordFiltering";import { useLocalKeywordFilters } from "@/client/features/keywords/hooks/useLocalKeywordFilters";import { useKeywordResearchData } from "@/client/features/keywords/hooks/useKeywordResearchData";@@ -11,7 +14,7 @@ import {type KeywordMode,type ResultLimit,} from "@/client/features/keywords/keywordResearchTypes";-import { DEFAULT_LOCATION_CODE } from "@/client/features/keywords/locations";+import type { OpenTabInput } from "@/client/features/keywords/state/keywordTabsStore";import type { KeywordResearchRow } from "@/types/keywords";import type { SortDir, SortField } from "@/client/features/keywords/components";import {@@ -36,6 +39,14 @@ export type KeywordResearchControllerInput = {keywordMode: KeywordMode;sortField: SortField;sortDir: SortDir;+ getOpenKeywordTabs?: () => readonly OpenTabInput[];+ keywordTabsLimit?: number;+ /**+ * Called when the user submits the search form. Lets the caller decide+ * whether the submission opens tabs or just rewrites the URL — the+ * controller stays agnostic.+ */+ onFormSubmit: (value: KeywordControlsValues) => void;};export function useKeywordResearchController(@@ -238,23 +249,17 @@ function useKeywordControllerState(input: KeywordResearchControllerInput) {setSerpPage(0);}, [clearSelection, setSerpKeyword, setSerpPage, uiState]);+ const onFormSubmit = input.onFormSubmit;const controlsForm = useKeywordControlsForm({...input,locationCode,+ getOpenKeywordTabs: input.getOpenKeywordTabs,+ keywordTabsLimit: input.keywordTabsLimit,},(value) => {setPreferredLocationCode(value.locationCode);- setSearchParams({- q: value.keyword,- loc:- input.hasExplicitLocationCode ||- value.locationCode !== DEFAULT_LOCATION_CODE- ? value.locationCode- : undefined,- kLimit: value.resultLimit === 150 ? undefined : value.resultLimit,- mode: value.mode === "auto" ? undefined : value.mode,- });+ onFormSubmit(value);},);diff --git a/src/client/features/keywords/state/useKeywordTabs.ts b/src/client/features/keywords/state/useKeywordTabs.tsnew file mode 100644index 00000000..bf4a973b--- /dev/null+++ b/src/client/features/keywords/state/useKeywordTabs.ts@@ -0,0 +1,81 @@+import { useCallback, useMemo, useSyncExternalStore } from "react";+import {+ EMPTY_TABS_STATE,+ KEYWORD_TABS_LIMIT,+ closeTab as closeTabAction,+ findMatchingTab,+ getKeywordTabsSnapshot,+ markTabViewed as markTabViewedAction,+ openTabs as openTabsAction,+ setActiveTab as setActiveTabAction,+ subscribeKeywordTabsStore,+ type KeywordTab,+ type OpenTabInput,+ type ProjectTabsState,+} from "./keywordTabsStore";++function useKeywordTabsSnapshot(projectId: string): ProjectTabsState {+ const getSnapshot = useCallback(+ () => getKeywordTabsSnapshot(projectId),+ [projectId],+ );+ return useSyncExternalStore(+ subscribeKeywordTabsStore,+ getSnapshot,+ () => EMPTY_TABS_STATE,+ );+}++export function useKeywordTabs(projectId: string) {+ const state = useKeywordTabsSnapshot(projectId);++ const openTabs = useCallback(+ (inputs: OpenTabInput[]) => openTabsAction(projectId, inputs),+ [projectId],+ );++ const closeTab = useCallback(+ (tabId: string) => closeTabAction(projectId, tabId),+ [projectId],+ );++ const setActiveTab = useCallback(+ (tabId: string | null) => setActiveTabAction(projectId, tabId),+ [projectId],+ );++ const markTabViewed = useCallback(+ (tabId: string, when?: number) =>+ markTabViewedAction(projectId, tabId, when),+ [projectId],+ );++ // Reads the latest module snapshot directly so this callback is safe to use+ // in effect dependency arrays — its reference is stable across renders.+ const findMatching = useCallback(+ (input: OpenTabInput) =>+ findMatchingTab(getKeywordTabsSnapshot(projectId), input),+ [projectId],+ );++ const activeTab = useMemo(+ () => state.tabs.find((tab) => tab.id === state.activeTabId) ?? null,+ [state],+ );++ return {+ tabs: state.tabs,+ activeTabId: state.activeTabId,+ activeTab,+ isAtCap: state.tabs.length >= KEYWORD_TABS_LIMIT,+ limit: KEYWORD_TABS_LIMIT,+ openTabs,+ closeTab,+ setActiveTab,+ markTabViewed,+ findMatchingTab: findMatching,+ };+}++export type UseKeywordTabsReturn = ReturnType<typeof useKeywordTabs>;+export type { KeywordTab };diff --git a/src/client/features/keywords/utils.ts b/src/client/features/keywords/utils.tsindex 1f3bc4a3..4bb64484 100644--- a/src/client/features/keywords/utils.ts+++ b/src/client/features/keywords/utils.ts@@ -22,3 +22,11 @@ export function formatNumber(value: number | null | undefined): string {if (value == null) return "-";return new Intl.NumberFormat().format(value);}++export function formatCompactNumber(value: number | null | undefined): string {+ if (value == null) return "-";+ return new Intl.NumberFormat(undefined, {+ notation: "compact",+ maximumFractionDigits: 1,+ }).format(value);+}