Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.
TypeScript aeoai-agentai-searchanswer-engine-optimizationbrand-monitoringchatgptclaudecopilotdockergeminigeogoogle-ai-overviewsgrokmcpnextjsopen-sourceperplexityseosupabasetypescript
feat(mentions): add the Mentions sidebar item and the Mentions & Sentiment page shell (#1114)
Cihanf963d51d386a
diff --git a/web/messages/en.json b/web/messages/en.jsonindex e98d86761..cb56aac5d 100644--- a/web/messages/en.json+++ b/web/messages/en.json@@ -56,6 +56,7 @@"audit": "Site Audit","competitors": "Competitors","citations": "Citations",+ "mentions": "Mentions","shopping": "Shopping","reports": "Reports","settings": "Settings",@@ -2431,6 +2432,28 @@"order": "Furthest behind first: late or missing on the most AI platforms, then the worse average position."}},+ "mentions": {+ "title": "Mentions & Sentiment",+ "description": "Where AI mentions your brand, how it describes you, why, and what to do about it.",+ "selectBrand": "Select a brand to see its mentions.",+ "tabs": {+ "label": "Mentions & Sentiment views",+ "overview": "Overview",+ "mentions": "Mentions",+ "perception": "Perception"+ },+ "filters": {+ "platform": "Platform",+ "allPlatforms": "All platforms",+ "country": "Country",+ "allCountries": "All countries",+ "topic": "Topic",+ "allTopics": "All topics",+ "search": "Search",+ "searchPlaceholder": "Search prompts, brands, phrases…"+ },+ "comingSoon": "This view is on its way: its figures and charts arrive with the next updates."+ },"competitors": {"title": "Competitors","description": "Manage competitors and compare AI visibility head-to-head.",diff --git a/web/src/app/[locale]/(dashboard)/dashboard/mentions/_filter-bar.tsx b/web/src/app/[locale]/(dashboard)/dashboard/mentions/_filter-bar.tsxnew file mode 100644index 000000000..3b45f81d1--- /dev/null+++ b/web/src/app/[locale]/(dashboard)/dashboard/mentions/_filter-bar.tsx@@ -0,0 +1,143 @@+'use client';++import { useTranslations } from 'next-intl';+import { Search } from 'lucide-react';+import { DateRangeFilter } from '@/components/filters/date-range-filter';+import { Input } from '@/components/ui/input';+import {+ Select,+ SelectContent,+ SelectItem,+ SelectTrigger,+ SelectValue,+} from '@/components/ui/select';+import { PROMPT_RANGE_PRESETS } from '@/config/prompt-options';+import { POSITION_PLATFORMS } from '@/lib/prompt-positions';+import { formatRegionDisplay } from '@/lib/region';+import type { MentionsFilters } from '@/lib/mentions-filters';+import type { Topic } from '@/types';++const ALL = '__all__';++/**+ * The filter bar every Mentions & Sentiment tab shares (MS-05): the date+ * range, AI platform, country, topic and a search over prompts, brands and+ * phrases. The brand is the app's active brand, chosen in the sidebar.+ */+export function MentionsFilterBar({+ filters,+ onChange,+ regions,+ topics,+}: {+ filters: MentionsFilters;+ onChange: (patch: Partial<MentionsFilters>) => void;+ regions: string[];+ topics: Topic[];+}) {+ const t = useTranslations('mentions.filters');+ const platformItems = [+ { value: ALL, label: t('allPlatforms') },+ ...POSITION_PLATFORMS.map((p) => ({ value: p.id as string, label: p.label as string })),+ ];+ const regionItems = [+ { value: ALL, label: t('allCountries') },+ ...regions.map((r) => ({ value: r, label: formatRegionDisplay(r) })),+ ];+ const topicItems = [+ { value: ALL, label: t('allTopics') },+ ...topics.map((topic) => ({ value: topic.id, label: topic.name })),+ ];+ const pick = (v: string | null) => (!v || v === ALL ? '' : v);++ return (+ <div className="flex flex-wrap items-end gap-3">+ <DateRangeFilter+ value={filters.range}+ presets={PROMPT_RANGE_PRESETS}+ onChange={(range) => onChange({ range })}+ from={filters.from}+ to={filters.to}+ onFromChange={(from) => onChange({ from })}+ onToChange={(to) => onChange({ to })}+ />++ <FilterSelect+ label={t('platform')}+ value={filters.platform || ALL}+ items={platformItems}+ onChange={(v) => onChange({ platform: pick(v) })}+ className="w-44"+ />+ {regions.length > 1 && (+ <FilterSelect+ label={t('country')}+ value={filters.region || ALL}+ items={regionItems}+ onChange={(v) => onChange({ region: pick(v) })}+ className="w-44"+ />+ )}+ {topics.length > 0 && (+ <FilterSelect+ label={t('topic')}+ value={filters.topic || ALL}+ items={topicItems}+ onChange={(v) => onChange({ topic: pick(v) })}+ className="w-44"+ />+ )}++ <div className="min-w-48 flex-1">+ <label+ htmlFor="mentions-search"+ className="mb-1.5 block text-xs font-medium text-muted-foreground"+ >+ {t('search')}+ </label>+ <div className="relative">+ <Search className="absolute top-2.5 left-2.5 h-3.5 w-3.5 text-muted-foreground" />+ <Input+ id="mentions-search"+ value={filters.q}+ onChange={(e) => onChange({ q: e.target.value })}+ placeholder={t('searchPlaceholder')}+ className="h-8 pl-8 text-xs"+ />+ </div>+ </div>+ </div>+ );+}++function FilterSelect({+ label,+ value,+ items,+ onChange,+ className,+}: {+ label: string;+ value: string;+ items: { value: string; label: string }[];+ onChange: (value: string | null) => void;+ className?: string;+}) {+ return (+ <div>+ <label className="mb-1.5 block text-xs font-medium text-muted-foreground">{label}</label>+ <Select value={value} onValueChange={(v) => onChange(v as string | null)} items={items}>+ <SelectTrigger className={`h-8 text-xs ${className ?? ''}`} aria-label={label}>+ <SelectValue />+ </SelectTrigger>+ <SelectContent>+ {items.map((item) => (+ <SelectItem key={item.value} value={item.value}>+ {item.label}+ </SelectItem>+ ))}+ </SelectContent>+ </Select>+ </div>+ );+}diff --git a/web/src/app/[locale]/(dashboard)/dashboard/mentions/page.tsx b/web/src/app/[locale]/(dashboard)/dashboard/mentions/page.tsxnew file mode 100644index 000000000..d6d41a695--- /dev/null+++ b/web/src/app/[locale]/(dashboard)/dashboard/mentions/page.tsx@@ -0,0 +1,116 @@+'use client';++import { useEffect, useState } from 'react';+import { useTranslations } from 'next-intl';+import { Card, CardContent } from '@/components/ui/card';+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';+import { getTopics } from '@/lib/actions/topic';+import { getBrandFilterOptions } from '@/lib/actions/tracking';+import {+ DEFAULT_MENTIONS_FILTERS,+ DEFAULT_MENTIONS_TAB,+ MENTIONS_TABS,+ mentionsStateParams,+ readMentionsState,+ type MentionsFilters,+ type MentionsTab,+} from '@/lib/mentions-filters';+import { writeUrlParams } from '@/lib/url-state';+import { useBrandStore } from '@/stores/use-brand-store';+import type { Topic } from '@/types';+import { MentionsFilterBar } from './_filter-bar';++/**+ * Mentions & Sentiment (MS-05): where AI mentions the brand, how it describes+ * it, and what to do about it — built from the answers tracking already+ * stores, so opening the page or changing a filter never calls an LLM.+ *+ * Top-down as the spec orders it: the tabs, then the filters every tab+ * shares, then the tab's content. Tab and filters live in the URL.+ */+export default function MentionsPage() {+ const t = useTranslations('mentions');+ const activeBrandId = useBrandStore((s) => s.activeBrandId);++ const [tab, setTab] = useState<MentionsTab>(DEFAULT_MENTIONS_TAB);+ const [filters, setFilters] = useState<MentionsFilters>(DEFAULT_MENTIONS_FILTERS);+ // Read after mount (window isn't available during the server render), as+ // Citations does; the URL is written only once it has been read.+ const [urlRead, setUrlRead] = useState(false);+ useEffect(() => {+ const state = readMentionsState(new URLSearchParams(window.location.search));+ // eslint-disable-next-line react-hooks/set-state-in-effect -- one read of the URL after mount+ setTab(state.tab);+ setFilters(state.filters);+ setUrlRead(true);+ }, []);+ useEffect(() => {+ if (urlRead) writeUrlParams(mentionsStateParams(tab, filters));+ }, [urlRead, tab, filters]);++ const [regions, setRegions] = useState<string[]>([]);+ const [topics, setTopics] = useState<Topic[]>([]);+ useEffect(() => {+ if (!activeBrandId) return;+ let cancelled = false;+ getBrandFilterOptions(activeBrandId)+ .then((options) => {+ if (!cancelled) setRegions([...options.regions].sort((a, b) => a.localeCompare(b)));+ })+ .catch(() => {});+ getTopics(activeBrandId)+ .then((rows) => {+ if (!cancelled) setTopics(rows);+ })+ .catch(() => {});+ return () => {+ cancelled = true;+ };+ }, [activeBrandId]);++ if (!activeBrandId) {+ return (+ <div className="flex min-h-[400px] items-center justify-center">+ <p className="text-muted-foreground">{t('selectBrand')}</p>+ </div>+ );+ }++ return (+ <div className="space-y-6">+ <div>+ <h1 className="text-2xl font-bold tracking-tight">{t('title')}</h1>+ <p className="text-sm text-muted-foreground">{t('description')}</p>+ </div>++ <Tabs value={tab} onValueChange={(v) => setTab(v as MentionsTab)}>+ <TabsList aria-label={t('tabs.label')}>+ {MENTIONS_TABS.map((id) => (+ <TabsTrigger key={id} value={id}>+ {t(`tabs.${id}`)}+ </TabsTrigger>+ ))}+ </TabsList>++ <div className="mt-4">+ <MentionsFilterBar+ filters={filters}+ onChange={(patch) => setFilters((prev) => ({ ...prev, ...patch }))}+ regions={regions}+ topics={topics}+ />+ </div>++ {MENTIONS_TABS.map((id) => (+ <TabsContent key={id} value={id} className="mt-4">+ <Card>+ <CardContent className="py-10 text-center text-sm text-muted-foreground">+ {t('comingSoon')}+ </CardContent>+ </Card>+ </TabsContent>+ ))}+ </Tabs>+ </div>+ );+}diff --git a/web/src/config/dashboard.ts b/web/src/config/dashboard.tsindex bc24f1643..178a41672 100644--- a/web/src/config/dashboard.ts+++ b/web/src/config/dashboard.ts@@ -6,6 +6,7 @@ import {Gauge,Globe,LineChart,+ MessageCircleMore,Quote,ShoppingBag,Sparkles,@@ -88,6 +89,13 @@ export const dashboardNav: NavGroup[] = [href: '/dashboard/topics',icon: Tag,},+ // Mentions & Sentiment (MS-05): beside Citations, its sibling concept.+ {+ title: 'Mentions',+ href: '/dashboard/mentions',+ icon: MessageCircleMore,+ badge: 'New',+ },{title: 'Citations',href: '/dashboard/citations',diff --git a/web/src/lib/dashboard-navigation.test.ts b/web/src/lib/dashboard-navigation.test.tsindex ef8ca8d70..376e66255 100644--- a/web/src/lib/dashboard-navigation.test.ts+++ b/web/src/lib/dashboard-navigation.test.ts@@ -45,3 +45,16 @@ describe('shouldShowDashboardNavItem', () => {expect(shouldShowDashboardNavItem(shopping, { shoppingModeEnabled: true })).toBe(true);});});++describe('the Mentions item', () => {+ const analytics = dashboardNav.find((group) => group.title === 'Analytics')!.items;+ const index = (title: string) => analytics.findIndex((item) => item.title === title);++ it('sits directly above Citations, marked New', () => {+ expect(index('Mentions')).toBe(index('Citations') - 1);+ expect(analytics[index('Mentions')]).toMatchObject({+ href: '/dashboard/mentions',+ badge: 'New',+ });+ });+});diff --git a/web/src/lib/dashboard-navigation.ts b/web/src/lib/dashboard-navigation.tsindex 4c4af90df..290392198 100644--- a/web/src/lib/dashboard-navigation.ts+++ b/web/src/lib/dashboard-navigation.ts@@ -22,6 +22,7 @@ export const dashboardNavLabelKeys: Record<string, NavLabelKey> = {'Content Optimization': { namespace: 'nav', key: 'content' },'Site Audit': { namespace: 'nav', key: 'audit' },Citations: { namespace: 'nav', key: 'citations' },+ Mentions: { namespace: 'nav', key: 'mentions' },Shopping: { namespace: 'nav', key: 'shopping' },Reports: { namespace: 'nav', key: 'reports' },};diff --git a/web/src/lib/mentions-filters.test.ts b/web/src/lib/mentions-filters.test.tsnew file mode 100644index 000000000..7b5e5cf51--- /dev/null+++ b/web/src/lib/mentions-filters.test.ts@@ -0,0 +1,87 @@+import { describe, expect, it } from 'vitest';+import {+ DEFAULT_MENTIONS_FILTERS,+ mentionsStateParams,+ readMentionsState,+ type MentionsFilters,+} from './mentions-filters';++const read = (query: string) => readMentionsState(new URLSearchParams(query));++describe('readMentionsState', () => {+ it('opens on the Overview tab over 30 days with no filters', () => {+ expect(read('')).toEqual({ tab: 'overview', filters: DEFAULT_MENTIONS_FILTERS });+ });++ it('reads every filter a shared link carries', () => {+ expect(+ read(+ 'tab=mentions&range=custom&from=2026-10-01&to=2026-10-14&platform=gemini-web®ion=US&topic=t1&q=integrations',+ ),+ ).toEqual({+ tab: 'mentions',+ filters: {+ range: 'custom',+ from: '2026-10-01',+ to: '2026-10-14',+ platform: 'gemini-web',+ region: 'US',+ topic: 't1',+ q: 'integrations',+ },+ });+ });++ it('falls back to the defaults on an unknown tab or range', () => {+ expect(read('tab=fact-check&range=1y')).toEqual({+ tab: 'overview',+ filters: DEFAULT_MENTIONS_FILTERS,+ });+ });++ it('ignores custom dates unless the range is custom', () => {+ expect(read('range=7d&from=2026-10-01&to=2026-10-14').filters).toMatchObject({+ range: '7d',+ from: '',+ to: '',+ });+ });+});++describe('mentionsStateParams', () => {+ it('leaves the defaults out, so the default view has a clean URL', () => {+ expect(+ Object.values(mentionsStateParams('overview', DEFAULT_MENTIONS_FILTERS)).every(+ (v) => v === null,+ ),+ ).toBe(true);+ });++ it('round-trips through the URL', () => {+ const filters: MentionsFilters = {+ range: 'custom',+ from: '2026-10-01',+ to: '2026-10-14',+ platform: 'chatgpt-web',+ region: 'GB',+ topic: 't2',+ q: 'pricing',+ };+ const params = new URLSearchParams();+ for (const [k, v] of Object.entries(mentionsStateParams('perception', filters))) {+ if (v !== null) params.set(k, v);+ }+ expect(readMentionsState(params)).toEqual({ tab: 'perception', filters });+ });++ it('drops custom dates outside a custom range and trims the search', () => {+ expect(+ mentionsStateParams('overview', {+ ...DEFAULT_MENTIONS_FILTERS,+ range: '7d',+ from: '2026-10-01',+ q: ' pricing ',+ }),+ ).toMatchObject({ range: '7d', from: null, q: 'pricing' });+ });+});diff --git a/web/src/lib/mentions-filters.ts b/web/src/lib/mentions-filters.tsnew file mode 100644index 000000000..ba20a825c--- /dev/null+++ b/web/src/lib/mentions-filters.ts@@ -0,0 +1,83 @@+import { PROMPT_RANGE_PRESETS, type PromptRangePreset } from '@/config/prompt-options';++/**+ * The Mentions & Sentiment page's tab and filters (MS-05). One filter shape is+ * shared by every tab and kept in the URL, so a refresh or a shared link+ * restores the view. The V1.5 Sentiment and V2 Fact-check tabs join this list+ * when they are built.+ */+export const MENTIONS_TABS = ['overview', 'mentions', 'perception'] as const;+export type MentionsTab = (typeof MENTIONS_TABS)[number];++export interface MentionsFilters {+ range: PromptRangePreset;+ /** A custom range's first and last day, `YYYY-MM-DD`; empty otherwise. */+ from: string;+ to: string;+ /** A prompt_results platform id, e.g. `chatgpt-web`; empty for all. */+ platform: string;+ region: string;+ topic: string;+ /** Free text over prompts, brands and phrases. */+ q: string;+}++/** The mockup opens on 30 days. */+export const DEFAULT_MENTIONS_FILTERS: MentionsFilters = {+ range: '30d',+ from: '',+ to: '',+ platform: '',+ region: '',+ topic: '',+ q: '',+};++export const DEFAULT_MENTIONS_TAB: MentionsTab = 'overview';++const pick = <T extends string>(value: string | null, allowed: readonly T[], fallback: T): T =>+ value !== null && (allowed as readonly string[]).includes(value) ? (value as T) : fallback;++/** The tab and filters a query string describes; anything unknown falls back to the default. */+export function readMentionsState(search: URLSearchParams): {+ tab: MentionsTab;+ filters: MentionsFilters;+} {+ const range = pick(search.get('range'), PROMPT_RANGE_PRESETS, DEFAULT_MENTIONS_FILTERS.range);+ const custom = range === 'custom';+ return {+ tab: pick(search.get('tab'), MENTIONS_TABS, DEFAULT_MENTIONS_TAB),+ filters: {+ range,+ from: custom ? (search.get('from') ?? '') : '',+ to: custom ? (search.get('to') ?? '') : '',+ platform: search.get('platform') ?? '',+ region: search.get('region') ?? '',+ topic: search.get('topic') ?? '',+ q: search.get('q') ?? '',+ },+ };+}++/**+ * The query params for a tab and filters, for writeUrlParams: a default or+ * empty value maps to null so the URL stays clean, and custom dates are kept+ * only for a custom range.+ */+export function mentionsStateParams(+ tab: MentionsTab,+ filters: MentionsFilters,+): Record<string, string | null> {+ const custom = filters.range === 'custom';+ const orNull = (value: string) => value || null;+ return {+ tab: tab === DEFAULT_MENTIONS_TAB ? null : tab,+ range: filters.range === DEFAULT_MENTIONS_FILTERS.range ? null : filters.range,+ from: custom ? orNull(filters.from) : null,+ to: custom ? orNull(filters.to) : null,+ platform: orNull(filters.platform),+ region: orNull(filters.region),+ topic: orNull(filters.topic),+ q: orNull(filters.q.trim()),+ };+}