Skip to content

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.

feat(action-center): open a card on the right for each Getting started step (#1236)

Cihan7a5374434dd5
diff --git a/web/messages/en.json b/web/messages/en.json
index 267f82d24..5d795f490 100644
--- a/web/messages/en.json
+++ b/web/messages/en.json
@@ -1423,72 +1423,218 @@
"steps": {
"kpis": {
"title": "Set your KPIs",
- "summary": "Pick 3–5 goals. We track them for you."
+ "summary": "Pick 3–5 goals. We track them for you.",
+ "open": "Open KPIs",
+ "doneWhen": "1 KPI saved",
+ "why": [
+ "KPIs turn your data into goals you can track.",
+ "Action Center shows your progress against them every week."
+ ],
+ "how": [
+ "Open KPIs",
+ "Pick 3–5, like AI visibility or citations",
+ "Set a goal for each and save"
+ ]
},
"competitors": {
"title": "Add at least 3 competitors",
- "summary": "Works best with 5–20 competitors."
+ "summary": "Works best with 5–20 competitors.",
+ "open": "Add competitors",
+ "doneWhen": "3 competitors",
+ "why": [
+ "Every AI answer is compared with your competitors.",
+ "5–20 competitors give the clearest picture."
+ ],
+ "how": ["Open Competitors", "Add the brands buyers compare you with", "Aim for 5–20"]
},
"topics": {
"title": "Add at least 3 topics",
- "summary": "Pick from topic suggestions."
+ "summary": "Pick from topic suggestions.",
+ "open": "Open topic suggestions",
+ "doneWhen": "3 topics",
+ "why": [
+ "Topics group your prompts and show where you lead or lag.",
+ "Suggestions come from your site and market."
+ ],
+ "how": ["Open Topics", "Pick 3 topics that match what you sell", "Add them"]
},
"prompts": {
"title": "Add 3 prompts per topic",
- "summary": "Pick from prompt suggestions."
+ "summary": "Pick from prompt suggestions.",
+ "open": "Open prompt suggestions",
+ "doneWhen": "3 prompts in every topic",
+ "why": [
+ "Prompts are the questions buyers ask AI.",
+ "3 per topic is enough to see a trend."
+ ],
+ "how": [
+ "Open Prompt Suggestions",
+ "Pick 3 prompts for each topic",
+ "Add them. First answers arrive within hours"
+ ]
},
"gsc": {
"title": "Connect Google Search Console",
- "summary": "Strongly recommended."
+ "summary": "Strongly recommended.",
+ "name": "Google Search Console",
+ "open": "Connect",
+ "doneWhen": "Connected",
+ "why": [
+ "We start analyzing your data within 24 hours.",
+ "Prompt and content suggestions come from real searches.",
+ "Shows whether your work brings clicks."
+ ],
+ "how": [
+ "Click Connect",
+ "Sign in with Google and pick your property",
+ "Allow read-only access"
+ ]
},
"ga": {
"title": "Connect Google Analytics",
- "summary": "See which AI visits engage and convert."
+ "summary": "See which AI visits engage and convert.",
+ "name": "Google Analytics",
+ "open": "Connect",
+ "doneWhen": "Connected",
+ "why": [
+ "Shows which AI visits engage and convert.",
+ "Needed for traffic and conversion reports."
+ ],
+ "how": ["Click Connect", "Pick your GA4 property", "Allow read-only access"]
},
"snippet": {
"title": "Add the AI Traffic snippet",
- "summary": "One line in your site’s head."
+ "summary": "One line in your site’s head.",
+ "open": "Get the code",
+ "doneWhen": "First visit detected",
+ "why": [
+ "Counts visits from ChatGPT, Gemini, Perplexity and more.",
+ "Works without Google Analytics."
+ ],
+ "how": [
+ "Copy the code",
+ "Paste it in your site’s head",
+ "Publish. We detect the first visit"
+ ]
},
"visibility": {
"title": "See where you stand in Visibility",
- "summary": "Your share of AI answers vs competitors."
+ "summary": "Your share of AI answers vs competitors.",
+ "open": "Open Visibility",
+ "doneWhen": "Page opened",
+ "why": ["Your share of AI answers vs competitors.", "The starting point for every goal."],
+ "how": ["Open Visibility", "Check your rank and the leader", "Note your weakest platform"]
},
"answers": {
"title": "Read your first AI answers",
- "summary": "Answers and follow-up searches, per prompt."
+ "summary": "Answers and follow-up searches, per prompt.",
+ "open": "Open Prompts",
+ "doneWhen": "Page opened",
+ "why": ["See exactly what AI tells your buyers."],
+ "how": ["Open Prompts", "Open one prompt", "Read the answer and its follow-up searches"]
},
"data_prompts": {
"title": "Track high-value prompt suggestions",
- "summary": "Built from your Search Console and Analytics data."
+ "summary": "Built from your Search Console and Analytics data.",
+ "open": "Open prompt suggestions",
+ "doneWhen": "5 suggested prompts tracked",
+ "why": [
+ "Built from the searches and pages that bring you visitors.",
+ "So you track what matters for revenue."
+ ],
+ "how": [
+ "Open Prompt Suggestions",
+ "Filter: From your data",
+ "Track the ones that fit, 5 or more"
+ ]
},
"mentions": {
"title": "Check what AI says about you",
- "summary": "Mentions and tone."
+ "summary": "Mentions and tone.",
+ "open": "Open Mentions",
+ "doneWhen": "Page opened",
+ "why": ["How often AI names you, and in what tone."],
+ "how": ["Open Mentions", "Check your share and sentiment"]
},
"citations": {
"title": "See who AI quotes",
- "summary": "The pages and sites AI uses as sources."
+ "summary": "The pages and sites AI uses as sources.",
+ "open": "Open Citations",
+ "doneWhen": "Page opened",
+ "why": ["The sources AI trusts. Where you should be listed."],
+ "how": ["Open Citations", "See which sites AI quotes most"]
},
"traffic": {
"title": "See visits from AI",
- "summary": "Which platforms send visitors, to which pages."
+ "summary": "Which platforms send visitors, to which pages.",
+ "open": "Open AI Traffic",
+ "doneWhen": "Page opened",
+ "why": ["Which AI platforms send visitors, and to which pages."],
+ "how": ["Open AI Traffic", "Check your top pages"]
},
"pick_content": {
"title": "Pick content from suggestions",
- "summary": "Choose 1–3 suggestions."
+ "summary": "Choose 1–3 suggestions.",
+ "open": "Open Content",
+ "doneWhen": "1 suggestion picked",
+ "why": ["Suggestions are built from your prompts and searches."],
+ "how": [
+ "Open Content",
+ "Pick 1–3 suggestions: review them, create a brief or send them to Action Center"
+ ]
},
"create_content": {
"title": "Create your first content",
- "summary": "Draft in your brand voice, then publish."
+ "summary": "Draft in your brand voice, then publish.",
+ "open": "Open Content",
+ "doneWhen": "Sent to your CMS, or its action completed",
+ "why": ["Content is the main way to appear in more answers."],
+ "how": [
+ "Open Content",
+ "Create a brief for one suggestion",
+ "Publish it: send it to your CMS, or complete its action"
+ ]
},
"optimize_page": {
"title": "Optimize a page",
- "summary": "Audit a page, then apply its fixes."
+ "summary": "Audit a page, then apply its fixes.",
+ "open": "Open Audit",
+ "doneWhen": "1 page audited",
+ "why": ["Small fixes on pages AI already reads can win fast."],
+ "how": ["Open Audit", "Audit one page", "Apply the fixes it suggests"]
},
"ready": {
"title": "You’re ready",
- "summary": "AI actions start appearing here."
+ "summary": "AI actions start appearing here.",
+ "open": "See what’s next",
+ "doneWhen": "Automatic",
+ "why": ["From now on, AI turns your signals into actions here."],
+ "how": ["Keep checking Action Center each week"]
}
+ },
+ "panel": {
+ "close": "Close",
+ "ready": "Ready: {when}",
+ "optionalRecommended": "Optional · recommended",
+ "why": "Why it’s important",
+ "how": "How to do this",
+ "videosSoon": "Videos coming soon",
+ "doneWhen": "Done when: {condition}",
+ "doneAuto": "Done · checked automatically",
+ "inNewTab": "Finish it in the new tab. This step updates when you come back.",
+ "skip": "Skip",
+ "skippedNote": "Skipped. Suggestions may be less accurate. You can still connect it."
+ },
+ "skipDialog": {
+ "title": "Skip {name}?",
+ "body": "This is the last time we suggest it. Without it:",
+ "lessAccurate": "Prompt and content suggestions are less accurate",
+ "noClicks": "We can’t show whether your work brings clicks",
+ "later": "You can connect it any time from Settings.",
+ "skip": "Skip anyway",
+ "connect": "Connect now",
+ "skipped": "Skipped · you can connect it later",
+ "failed": "Couldn’t skip the step. Try again."
}
},
"actionTexts": {
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/action-center/actions/page.test.tsx b/web/src/app/[locale]/(dashboard)/dashboard/action-center/actions/page.test.tsx
index 95d0221a4..6fd70259c 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/action-center/actions/page.test.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/action-center/actions/page.test.tsx
@@ -7,6 +7,7 @@ import {
buildGettingStarted,
type GettingStartedFacts,
type GettingStartedStatus,
+ type GettingStartedStep,
} from '@/lib/getting-started/steps';
/**
@@ -81,11 +82,31 @@ vi.mock('@/components/action-center/action-center-tabs', () => ({ ActionCenterTa
vi.mock('@/components/action-center/action-table', () => ({ ActionTable: () => null }));
vi.mock('@/components/action-center/action-drawer', () => ({ ActionDrawer: () => null }));
vi.mock('@/components/getting-started/getting-started-table', () => ({
- GettingStartedTable: ({ steps, showNote }: { steps: unknown[]; showNote: boolean }) => (
- <div data-testid="steps">{`${steps.length} steps${showNote ? ', with the note' : ''}`}</div>
+ GettingStartedTable: ({
+ steps,
+ showNote,
+ onSelect,
+ }: {
+ steps: GettingStartedStep[];
+ showNote: boolean;
+ onSelect: (step: GettingStartedStep) => void;
+ }) => (
+ <div data-testid="steps">
+ <span data-testid="steps-summary">{`${steps.length} steps${showNote ? ', with the note' : ''}`}</span>
+ {steps.map((step) => (
+ <button key={step.key} data-step={step.key} onClick={() => onSelect(step)}>
+ {step.key}
+ </button>
+ ))}
+ </div>
),
readyWhenKey: () => 'setup',
}));
+vi.mock('@/components/getting-started/step-card', () => ({
+ GettingStartedStepCard: ({ step }: { step: GettingStartedStep }) => (
+ <div data-testid="card">{step.key}</div>
+ ),
+}));
const { default: ActionCenterActionsPage } = await import('./page');
@@ -205,7 +226,9 @@ describe('Getting started in the actions list', () => {
getGettingStarted.mockResolvedValue(started());
await render();
- expect(steps()?.textContent).toBe('17 steps, with the note');
+ expect(container.querySelector('[data-testid="steps-summary"]')?.textContent).toBe(
+ '17 steps, with the note',
+ );
expect(text()).toContain('card.title');
expect(text().match(/firstSignals/g)).toHaveLength(3);
// Getting started takes Highest Priority's place; the filters are for actions.
@@ -213,6 +236,23 @@ describe('Getting started in the actions list', () => {
expect(exportButton()).toBeUndefined();
});
+ it("opens a step's card, and says when a step still waiting for data opens", async () => {
+ getGettingStarted.mockResolvedValue(started());
+ await render();
+ const card = () => container.querySelector('[data-testid="card"]');
+ expect(card()).toBeNull();
+
+ const stepButton = (key: string) =>
+ container.querySelector<HTMLButtonElement>(`[data-step="${key}"]`)!;
+ await act(async () => stepButton('competitors').click());
+ expect(card()?.textContent).toBe('competitors');
+
+ // Mentions waits for the first answers.
+ await act(async () => stepButton('mentions').click());
+ expect(toast).toHaveBeenCalledWith('opensWhenReady');
+ expect(card()?.textContent).toBe('competitors');
+ });
+
// gkhngyk on #1235: Create action, a signal and the history drawer link to
// ?action=<id>; on a new brand the drawer opened over the steps.
it('lists the actions for a link to one action, or to a filtered list', async () => {
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/action-center/actions/page.tsx b/web/src/app/[locale]/(dashboard)/dashboard/action-center/actions/page.tsx
index c6a9d9498..4e6c1c767 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/action-center/actions/page.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/action-center/actions/page.tsx
@@ -60,6 +60,7 @@ import {
readyWhenKey,
} from '@/components/getting-started/getting-started-table';
import { GettingStartedSummaryCard } from '@/components/getting-started/summary-card';
+import { GettingStartedStepCard } from '@/components/getting-started/step-card';
import { Button } from '@/components/ui/button';
import { Card, CardContent } from '@/components/ui/card';
import { Input } from '@/components/ui/input';
@@ -140,6 +141,8 @@ function ActionsContent({ brand }: { brand: Brand }) {
// Null for a brand that doesn't run Getting started, or when it can't be
// read: the page is then exactly as without it.
const [gettingStarted, setGettingStarted] = useState<GettingStartedStatus | null>(null);
+ // The step whose card is open.
+ const [stepKey, setStepKey] = useState<string | null>(null);
const [members, setMembers] = useState<TeamMember[]>([]);
const [isLoading, setIsLoading] = useState(true);
const [loadFailed, setLoadFailed] = useState(false);
@@ -250,6 +253,14 @@ function ActionsContent({ brand }: { brand: Brand }) {
}
}, [gettingStarted, category]);
+ const refreshSteps = useCallback(() => {
+ getGettingStarted(brand.id)
+ .then((started) => {
+ if (started && mounted.current) setGettingStarted(started);
+ })
+ .catch(() => {});
+ }, [brand.id]);
+
// A step is done in another tab (its page opens in one): read the steps
// again when this tab is back in front.
useEffect(() => {
@@ -259,11 +270,7 @@ function ActionsContent({ brand }: { brand: Brand }) {
const refresh = () => {
if (document.visibilityState !== 'visible' || Date.now() - last < 1_000) return;
last = Date.now();
- getGettingStarted(brand.id)
- .then((started) => {
- if (started && mounted.current) setGettingStarted(started);
- })
- .catch(() => {});
+ refreshSteps();
};
window.addEventListener('focus', refresh);
document.addEventListener('visibilitychange', refresh);
@@ -271,20 +278,17 @@ function ActionsContent({ brand }: { brand: Brand }) {
window.removeEventListener('focus', refresh);
document.removeEventListener('visibilitychange', refresh);
};
- }, [startedActive, brand.id]);
+ }, [startedActive, refreshSteps]);
+ // A step opens its card; one still waiting for its data says when it opens.
const openStep = (step: GettingStartedStep) => {
if (step.state === 'waiting') {
toast(tStarted('opensWhenReady', { when: tStarted(`readyWhen.${readyWhenKey(step)}`) }));
return;
}
- // The last step points at the actions themselves.
- if (step.key === 'ready') {
- setCategory('all');
- return;
- }
- window.open(step.href, '_blank', 'noopener');
+ setStepKey(step.key);
};
+ const closeStep = useCallback(() => setStepKey(null), []);
// A change made in the drawer, shown in its row at once: reading the whole
// list again after each one held the drawer for seconds.
@@ -509,6 +513,7 @@ function ActionsContent({ brand }: { brand: Brand }) {
const list = actions ?? [];
const showSteps = startedActive && gettingStarted !== null && category === GETTING_STARTED;
+ const openCard = showSteps ? gettingStarted.steps.find((s) => s.key === stepKey) : undefined;
// Before the first signals, the cards that rank actions have nothing to say.
const noActions = list.length === 0;
const showStepsCategory = () => {
@@ -526,7 +531,8 @@ function ActionsContent({ brand }: { brand: Brand }) {
: { value, sub, isActive: focus === card, onClick: () => toggleFocus(card) };
return (
- <div className="space-y-4">
+ // With a step's card open, the list makes room for it on wide screens.
+ <div className={cn('space-y-4', openCard && 'min-[1300px]:pr-[440px]')}>
<div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-5">
{startedActive && gettingStarted && (
<GettingStartedSummaryCard
@@ -696,6 +702,7 @@ function ActionsContent({ brand }: { brand: Brand }) {
steps={gettingStarted.steps}
members={members}
onSelect={openStep}
+ selectedKey={openCard?.key ?? null}
showNote={noActions}
/>
) : visible.length > 0 ? (
@@ -716,6 +723,21 @@ function ActionsContent({ brand }: { brand: Brand }) {
</div>
)}
+ {openCard && (
+ <GettingStartedStepCard
+ brandId={brand.id}
+ step={openCard}
+ members={members}
+ canManage={canManage}
+ onClose={closeStep}
+ onChanged={refreshSteps}
+ onReady={() => {
+ closeStep();
+ setCategory('all');
+ }}
+ />
+ )}
+
<ActionDrawer
brandId={brand.id}
action={selected}
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/prompts/_suggestions-card.tsx b/web/src/app/[locale]/(dashboard)/dashboard/prompts/_suggestions-card.tsx
index 881b09506..815494721 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/prompts/_suggestions-card.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/prompts/_suggestions-card.tsx
@@ -35,6 +35,7 @@ import {
import { toast } from 'sonner';
import { cn } from '@/lib/utils';
import { formatNumber } from '@/lib/format';
+import { readUrlChoice } from '@/lib/url-state';
import {
getPromptSuggestions,
refreshPromptSuggestions,
@@ -43,6 +44,7 @@ import {
type PromptSuggestion,
} from '@/lib/actions/prompt-suggestions';
import {
+ fromYourData,
gaSourceData,
gscSourceData,
type GaSuggestionSourceData,
@@ -195,10 +197,13 @@ function SourceBadges({ suggestion }: { suggestion: PromptSuggestion }) {
}
/** Which data source a row carries, for the source filter. */
-type SourceFilter = 'all' | 'gsc' | 'ga' | 'agents';
+type SourceFilter = 'all' | 'data' | 'gsc' | 'ga' | 'agents';
const SOURCE_FILTER_LABELS: Record<SourceFilter, string> = {
all: 'All sources',
+ // Either Google source: Getting started's high-value prompts step links here
+ // with ?source=data.
+ data: 'From your data',
gsc: 'Google Search Console',
ga: 'Google Analytics (GA4)',
agents: 'Ansvisor Agents only',
@@ -265,6 +270,16 @@ export function SuggestionsCard({ brandId, onAccepted, sourceStates }: Props) {
const [refreshing, setRefreshing] = useState(false);
const [pendingId, setPendingId] = useState<string | null>(null);
const [sourceFilter, setSourceFilter] = useState<SourceFilter>('all');
+ // A link can open the list on a source (?source=data).
+ useEffect(() => {
+ setSourceFilter(
+ readUrlChoice<SourceFilter>(
+ 'source',
+ Object.keys(SOURCE_FILTER_LABELS) as SourceFilter[],
+ 'all',
+ ),
+ );
+ }, []);
const [search, setSearch] = useState('');
const [clearing, setClearing] = useState(false);
const [, startTransition] = useTransition();
@@ -319,9 +334,10 @@ export function SuggestionsCard({ brandId, onAccepted, sourceStates }: Props) {
const visible = useMemo(() => {
const q = search.trim().toLowerCase();
return suggestions.filter((s) => {
+ if (sourceFilter === 'data' && !fromYourData(s)) return false;
if (sourceFilter === 'gsc' && !gscSourceData(s)) return false;
if (sourceFilter === 'ga' && !gaSourceData(s)) return false;
- if (sourceFilter === 'agents' && (gscSourceData(s) || gaSourceData(s))) return false;
+ if (sourceFilter === 'agents' && fromYourData(s)) return false;
if (!q) return true;
return (
s.suggestedText.toLowerCase().includes(q) ||
diff --git a/web/src/components/getting-started/getting-started-table.tsx b/web/src/components/getting-started/getting-started-table.tsx
index 16ccc944e..1f9e2efb2 100644
--- a/web/src/components/getting-started/getting-started-table.tsx
+++ b/web/src/components/getting-started/getting-started-table.tsx
@@ -87,7 +87,7 @@ export function StepStatusBadge({ state }: { state: GettingStartedState }) {
}
/** Getting started is everyone's: the workspace's first members, then a count. */
-function WorkspaceAvatars({ members }: { members: TeamMember[] }) {
+export function WorkspaceAvatars({ members }: { members: TeamMember[] }) {
const t = useTranslations('actionCenter.gettingStarted');
if (members.length === 0) return <span className="text-xs text-muted-foreground">—</span>;
const shown = members.slice(0, 3);
@@ -114,11 +114,14 @@ export function GettingStartedTable({
steps,
members,
onSelect,
+ selectedKey,
showNote,
}: {
steps: GettingStartedStep[];
members: TeamMember[];
onSelect: (step: GettingStartedStep) => void;
+ /** The step whose card is open. */
+ selectedKey: string | null;
/** Says where the AI actions will appear, while there are none yet. */
showNote: boolean;
}) {
@@ -147,7 +150,12 @@ export function GettingStartedTable({
return (
<TableRow
key={step.key}
- className={waiting ? 'cursor-default' : 'cursor-pointer'}
+ aria-selected={step.key === selectedKey}
+ className={cn(
+ waiting ? 'cursor-default' : 'cursor-pointer',
+ step.key === selectedKey &&
+ 'bg-muted/50 shadow-[inset_3px_0_0_var(--foreground)]',
+ )}
onClick={() => onSelect(step)}
>
<TableCell className="max-w-[380px]">
@@ -183,9 +191,6 @@ export function GettingStartedTable({
>
{t('category')}
</Badge>
- <Badge variant="outline" className="text-[10px]">
- {t(`stages.${step.stage}`)}
- </Badge>
{step.optional && (
<Badge variant="outline" className={cn('text-[10px]', OPTIONAL_CHIP)}>
{t('optional')}
diff --git a/web/src/components/getting-started/step-card.test.tsx b/web/src/components/getting-started/step-card.test.tsx
new file mode 100644
index 000000000..a54355071
--- /dev/null
+++ b/web/src/components/getting-started/step-card.test.tsx
@@ -0,0 +1,182 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { GettingStartedStep } from '@/lib/getting-started/steps';
+
+/**
+ * A Getting started step's card (AC-ALT2 §6): why, how (a video's place and
+ * the steps), done when, and a button that opens the page in a new tab. An
+ * optional step can be skipped after a last-chance question.
+ */
+
+(
+ globalThis as typeof globalThis & {
+ IS_REACT_ACT_ENVIRONMENT: boolean;
+ }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+const { skipGettingStartedStep, toast, asked } = vi.hoisted(() => ({
+ skipGettingStartedStep: vi.fn(),
+ toast: { error: vi.fn(), success: vi.fn() },
+ // Every message key the card asked for.
+ asked: new Set<string>(),
+}));
+
+vi.mock('next-intl', () => ({
+ useTranslations: () =>
+ Object.assign(
+ (key: string) => {
+ asked.add(key);
+ return key;
+ },
+ { raw: (key: string) => [`${key} 1`, `${key} 2`] },
+ ),
+}));
+vi.mock('sonner', () => ({ toast }));
+vi.mock('@/lib/actions/getting-started', () => ({ skipGettingStartedStep }));
+
+const { GettingStartedStepCard } = await import('./step-card');
+
+const step = (over: Partial<GettingStartedStep> = {}): GettingStartedStep => ({
+ key: 'mentions',
+ stage: 'explore',
+ href: '/dashboard/mentions',
+ state: 'new',
+ progress: null,
+ updatedAt: null,
+ ...over,
+});
+
+let container: HTMLDivElement;
+let root: Root;
+const onClose = vi.fn();
+const onChanged = vi.fn();
+const onReady = vi.fn();
+
+async function render(s: GettingStartedStep, { canManage = true } = {}) {
+ await act(async () =>
+ root.render(
+ <GettingStartedStepCard
+ brandId="b1"
+ step={s}
+ members={[]}
+ canManage={canManage}
+ onClose={onClose}
+ onChanged={onChanged}
+ onReady={onReady}
+ />,
+ ),
+ );
+}
+
+const text = () => document.body.textContent ?? '';
+const button = (label: string) =>
+ [...document.querySelectorAll('button')].find((b) => b.textContent?.includes(label));
+
+beforeEach(() => {
+ asked.clear();
+ container = document.createElement('div');
+ document.body.append(container);
+ root = createRoot(container);
+ for (const fn of [onClose, onChanged, onReady, skipGettingStartedStep, toast.success]) {
+ fn.mockReset();
+ }
+});
+
+afterEach(() => {
+ act(() => root.unmount());
+ container.remove();
+});
+
+describe('GettingStartedStepCard', () => {
+ it('says why and how, with the video’s place, and when it counts as done', async () => {
+ await render(step({ key: 'competitors', progress: { value: 2, target: 3 } }));
+ expect(text()).toContain('steps.competitors.title');
+ expect(text()).toContain('steps.competitors.why 1');
+ expect(text()).toContain('steps.competitors.how 2');
+ expect(text()).toContain('panel.videosSoon');
+ expect(text()).toContain('panel.doneWhen · 2/3');
+ });
+
+ it("opens the step's page in a new tab and says to finish there", async () => {
+ const open = vi.spyOn(window, 'open').mockReturnValue(null);
+ await render(step());
+ await act(async () => button('steps.mentions.open')!.click());
+ expect(open).toHaveBeenCalledWith('/dashboard/mentions', '_blank', 'noopener');
+ expect(text()).toContain('panel.inNewTab');
+ open.mockRestore();
+ });
+
+ it('has no button for a step that is done, or still waiting for its data', async () => {
+ await render(step({ state: 'done' }));
+ expect(text()).toContain('panel.doneAuto');
+ expect(button('steps.mentions.open')).toBeUndefined();
+
+ await render(step({ state: 'waiting' }));
+ expect(text()).toContain('opensWhenReady');
+ expect(button('steps.mentions.open')).toBeUndefined();
+ });
+
+ it('skips an optional step only after the last-chance question', async () => {
+ skipGettingStartedStep.mockResolvedValue(undefined);
+ await render(step({ key: 'gsc', stage: 'setup', optional: true }));
+ expect(text()).toContain('panel.optionalRecommended');
+
+ await act(async () => button('panel.skip')!.click());
+ expect(skipGettingStartedStep).not.toHaveBeenCalled();
+ expect(text()).toContain('skipDialog.lessAccurate');
+
+ await act(async () => button('skipDialog.skip')!.click());
+ expect(skipGettingStartedStep).toHaveBeenCalledWith('b1', 'gsc');
+ expect(toast.success).toHaveBeenCalledWith('skipDialog.skipped');
+ expect(onChanged).toHaveBeenCalled();
+ });
+
+ it('offers no Skip on a required step or one already skipped', async () => {
+ await render(step());
+ expect(button('panel.skip')).toBeUndefined();
+ await render(step({ key: 'ga', stage: 'setup', optional: true, state: 'skipped' }));
+ expect(button('panel.skip')).toBeUndefined();
+ expect(text()).toContain('panel.skippedNote');
+ });
+
+ it('leads on to the actions from the last step', async () => {
+ await render(step({ key: 'ready', stage: 'ready', state: 'done' }));
+ await act(async () => button('steps.ready.open')!.click());
+ expect(onReady).toHaveBeenCalled();
+ });
+
+ it('asks for a name only on the steps that have one (the optional ones)', async () => {
+ await render(step());
+ expect(asked.has('steps.mentions.name')).toBe(false);
+ await render(step({ key: 'gsc', stage: 'setup', optional: true }));
+ expect(asked.has('steps.gsc.name')).toBe(true);
+ });
+
+ // gkhngyk on #1234/#1236: only admins and managers skip a step.
+ it('offers no Skip to someone who can’t set the steps up', async () => {
+ await render(step({ key: 'gsc', stage: 'setup', optional: true }), { canManage: false });
+ expect(button('panel.skip')).toBeUndefined();
+ expect(button('steps.gsc.open')).toBeDefined();
+ });
+
+ it('leaves Escape to a dialog open over the page', async () => {
+ await render(step());
+ const dialog = document.createElement('div');
+ dialog.setAttribute('role', 'dialog');
+ document.body.append(dialog);
+ await act(async () => {
+ window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' }));
+ });
+ expect(onClose).not.toHaveBeenCalled();
+ dialog.remove();
+ });
+
+ it('closes on Escape', async () => {
+ await render(step());
+ await act(async () => {
+ window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' }));
+ });
+ expect(onClose).toHaveBeenCalled();
+ });
+});
diff --git a/web/src/components/getting-started/step-card.tsx b/web/src/components/getting-started/step-card.tsx
new file mode 100644
index 000000000..46401fa63
--- /dev/null
+++ b/web/src/components/getting-started/step-card.tsx
@@ -0,0 +1,257 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useTranslations } from 'next-intl';
+import { toast } from 'sonner';
+import { Check, ExternalLink, Play, X } from 'lucide-react';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import {
+ Dialog,
+ DialogClose,
+ DialogContent,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+} from '@/components/ui/dialog';
+import { ACTION_STATUS_BADGE } from '@/components/action-center/action-table';
+import { skipGettingStartedStep } from '@/lib/actions/getting-started';
+import type { TeamMember } from '@/lib/actions/team';
+import type { GettingStartedStep } from '@/lib/getting-started/steps';
+import { cn } from '@/lib/utils';
+import {
+ GETTING_STARTED_CHIP,
+ StepStatusBadge,
+ WorkspaceAvatars,
+ readyWhenKey,
+} from './getting-started-table';
+
+const AMBER_NOTE = ACTION_STATUS_BADGE.on_hold;
+
+/**
+ * A Getting started step's card (AC-ALT2 §6), on the right of the Actions
+ * page: why the step matters, how to do it, and when it counts as done. Its
+ * button opens the step's page in a new tab; an optional step can be skipped
+ * after a last-chance question. Not modal: the list stays usable beside it
+ * and makes room for it on wide screens.
+ */
+export function GettingStartedStepCard({
+ brandId,
+ step,
+ members,
+ canManage,
+ onClose,
+ onChanged,
+ onReady,
+}: {
+ brandId: string;
+ step: GettingStartedStep;
+ members: TeamMember[];
+ /** Admins and managers: only they skip a step (00196). */
+ canManage: boolean;
+ onClose: () => void;
+ /** A step was skipped: read the steps again. */
+ onChanged: () => void;
+ /** The last step's button: on to the actions. */
+ onReady: () => void;
+}) {
+ const t = useTranslations('actionCenter.gettingStarted');
+ const [opened, setOpened] = useState(false);
+ const [confirmingSkip, setConfirmingSkip] = useState(false);
+ const [skipping, setSkipping] = useState(false);
+
+ // Another step: its own "opened" note.
+ useEffect(() => setOpened(false), [step.key]);
+
+ useEffect(() => {
+ const onKey = (event: KeyboardEvent) => {
+ // Escape belongs to a dialog open over the page (this card's Skip
+ // question, or another), not to the card under it.
+ const dialogOpen = document.querySelector('[role="dialog"]:not([aria-modal="false"])');
+ if (event.key === 'Escape' && !confirmingSkip && !dialogOpen) onClose();
+ };
+ window.addEventListener('keydown', onKey);
+ return () => window.removeEventListener('keydown', onKey);
+ }, [onClose, confirmingSkip]);
+
+ const text = (key: string) => t(`steps.${step.key}.${key}`);
+ const list = (key: 'why' | 'how') => t.raw(`steps.${step.key}.${key}`) as string[];
+ const when = t(`readyWhen.${readyWhenKey(step)}`);
+
+ const openPage = () => {
+ window.open(step.href, '_blank', 'noopener');
+ setOpened(true);
+ };
+
+ const skip = async () => {
+ setSkipping(true);
+ try {
+ await skipGettingStartedStep(brandId, step.key);
+ toast.success(t('skipDialog.skipped'));
+ onChanged();
+ } catch {
+ toast.error(t('skipDialog.failed'));
+ } finally {
+ setSkipping(false);
+ }
+ };
+
+ const footer = () => {
+ if (step.key === 'ready' && step.state !== 'waiting') {
+ return <Button onClick={onReady}>{text('open')}</Button>;
+ }
+ if (step.state === 'done') {
+ return (
+ <span className="flex items-center gap-1.5 text-sm font-medium text-green-600 dark:text-green-400">
+ <Check className="h-4 w-4" />
+ {t('panel.doneAuto')}
+ </span>
+ );
+ }
+ if (step.state === 'waiting') {
+ return <span className="text-sm text-muted-foreground">{t('opensWhenReady', { when })}</span>;
+ }
+ return (
+ <div className="flex w-full flex-col gap-2">
+ <div className="flex items-center gap-2">
+ <Button onClick={openPage}>
+ {text('open')}
+ <ExternalLink className="h-3.5 w-3.5" />
+ </Button>
+ {step.optional && step.state !== 'skipped' && canManage && (
+ <Button
+ variant="ghost"
+ disabled={skipping}
+ onClick={() => setConfirmingSkip(true)}
+ className="text-muted-foreground"
+ >
+ {t('panel.skip')}
+ </Button>
+ )}
+ </div>
+ {opened && <p className="text-xs text-muted-foreground">{t('panel.inNewTab')}</p>}
+ </div>
+ );
+ };
+
+ return (
+ <aside
+ role="dialog"
+ aria-modal="false"
+ aria-labelledby="getting-started-step-title"
+ className="fixed inset-y-0 right-0 z-40 flex w-full flex-col border-l bg-card shadow-lg sm:w-[440px]"
+ >
+ <div className="flex items-center justify-between gap-2 border-b px-5 py-3">
+ <div className="flex flex-wrap items-center gap-1.5">
+ <Badge variant="outline" className={cn('text-[10px]', GETTING_STARTED_CHIP)}>
+ {t('category')}
+ </Badge>
+ <Badge variant="outline" className="text-[10px]">
+ {t(`stages.${step.stage}`)}
+ </Badge>
+ </div>
+ <Button variant="ghost" size="icon-sm" aria-label={t('panel.close')} onClick={onClose}>
+ <X className="h-4 w-4" />
+ </Button>
+ </div>
+
+ <div className="flex-1 space-y-5 overflow-y-auto px-5 py-4">
+ <div>
+ <div className="flex flex-wrap items-center gap-1.5">
+ <StepStatusBadge state={step.state} />
+ {step.optional && (
+ <Badge variant="outline" className={cn('text-[10px]', AMBER_NOTE)}>
+ {t('panel.optionalRecommended')}
+ </Badge>
+ )}
+ </div>
+ <h2 id="getting-started-step-title" className="mt-2.5 text-lg font-semibold">
+ {text('title')}
+ </h2>
+ <p className="mt-1 text-sm text-muted-foreground">{text('summary')}</p>
+ <div className="mt-3 flex flex-wrap items-center gap-2 text-xs text-muted-foreground">
+ <WorkspaceAvatars members={members} />
+ <span>{t('everyone')}</span>
+ <span>· {t('panel.ready', { when })}</span>
+ </div>
+ </div>
+
+ <section>
+ <h3 className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+ {t('panel.why')}
+ </h3>
+ <ul className="mt-2 list-disc space-y-1 pl-5 text-sm">
+ {list('why').map((reason) => (
+ <li key={reason}>{reason}</li>
+ ))}
+ </ul>
+ </section>
+
+ <section>
+ <h3 className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+ {t('panel.how')}
+ </h3>
+ {/* The video's place, 16:9, until the videos are recorded. */}
+ <div className="mt-2 flex aspect-video flex-col items-center justify-center gap-2 rounded-lg border bg-muted/40 text-muted-foreground">
+ <span className="flex h-11 w-11 items-center justify-center rounded-full border bg-card">
+ <Play className="h-4 w-4" />
+ </span>
+ <span className="text-xs font-medium">{t('panel.videosSoon')}</span>
+ </div>
+ <ol className="mt-3 list-decimal space-y-1 pl-5 text-sm">
+ {list('how').map((how) => (
+ <li key={how}>{how}</li>
+ ))}
+ </ol>
+ </section>
+
+ {step.state === 'skipped' && (
+ <p className={cn('rounded-md border px-3 py-2 text-xs', AMBER_NOTE)}>
+ {t('panel.skippedNote')}
+ </p>
+ )}
+
+ <div className="flex items-start gap-2 rounded-md border bg-muted/30 px-3 py-2 text-sm">
+ <Check className="mt-0.5 h-4 w-4 shrink-0 text-muted-foreground" />
+ <span>
+ {t('panel.doneWhen', { condition: text('doneWhen') })}
+ {step.progress && (
+ <span className="font-semibold tabular-nums">
+ {' · '}
+ {step.progress.value}/{step.progress.target}
+ </span>
+ )}
+ </span>
+ </div>
+ </div>
+
+ <div className="flex min-h-14 items-center border-t px-5 py-3">{footer()}</div>
+
+ {/* Only the optional steps (Search Console, Analytics) have a name to ask about. */}
+ {step.optional && (
+ <Dialog open={confirmingSkip} onOpenChange={setConfirmingSkip}>
+ <DialogContent className="sm:max-w-sm">
+ <DialogHeader>
+ <DialogTitle>{t('skipDialog.title', { name: text('name') })}</DialogTitle>
+ <DialogDescription>{t('skipDialog.body')}</DialogDescription>
+ </DialogHeader>
+ <ul className="list-disc space-y-1 pl-5 text-sm">
+ <li>{t('skipDialog.lessAccurate')}</li>
+ <li>{t('skipDialog.noClicks')}</li>
+ </ul>
+ <p className="text-xs text-muted-foreground">{t('skipDialog.later')}</p>
+ <DialogFooter>
+ <DialogClose render={<Button variant="outline" onClick={() => void skip()} />}>
+ {t('skipDialog.skip')}
+ </DialogClose>
+ <DialogClose render={<Button onClick={openPage} />}>
+ {t('skipDialog.connect')}
+ </DialogClose>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ )}
+ </aside>
+ );
+}
diff --git a/web/src/lib/getting-started/steps.ts b/web/src/lib/getting-started/steps.ts
index 405ce9cfb..9233718ed 100644
--- a/web/src/lib/getting-started/steps.ts
+++ b/web/src/lib/getting-started/steps.ts
@@ -57,7 +57,8 @@ export const GETTING_STARTED_STEPS: readonly GettingStartedStepDef[] = [
{ key: 'snippet', stage: 'setup', href: '/dashboard/traffic' },
{ key: 'visibility', stage: 'explore', href: '/dashboard/insights' },
{ key: 'answers', stage: 'explore', href: '/dashboard/prompts/tracked' },
- { key: 'data_prompts', stage: 'explore', href: '/dashboard/prompts/suggestions' },
+ // Opens on Prompt Suggestions' "From your data" filter.
+ { key: 'data_prompts', stage: 'explore', href: '/dashboard/prompts/suggestions?source=data' },
{ key: 'mentions', stage: 'explore', href: '/dashboard/mentions' },
{ key: 'citations', stage: 'explore', href: '/dashboard/citations' },
{ key: 'traffic', stage: 'explore', href: '/dashboard/traffic' },
diff --git a/web/src/lib/prompt-suggestion-source.test.ts b/web/src/lib/prompt-suggestion-source.test.ts
index 00a70a3a4..21cb63865 100644
--- a/web/src/lib/prompt-suggestion-source.test.ts
+++ b/web/src/lib/prompt-suggestion-source.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, it } from 'vitest';
import {
+ fromYourData,
gaSourceData,
gscSourceData,
type GaSuggestionSourceData,
@@ -64,3 +65,16 @@ describe('gaSourceData', () => {
expect(gaSourceData({ source: 'heuristic', sourceData: gaData })).toBeNull();
});
});
+
+describe('fromYourData', () => {
+ it('takes a suggestion built from Search Console or Analytics data', () => {
+ expect(fromYourData({ source: 'gsc', sourceData: gscData })).toBe(true);
+ expect(fromYourData({ source: 'ga', sourceData: gaData })).toBe(true);
+ });
+
+ it("leaves out the agents' suggestions and a source without its data", () => {
+ expect(fromYourData({ source: 'llm', sourceData: null })).toBe(false);
+ expect(fromYourData({ source: 'gsc', sourceData: null })).toBe(false);
+ expect(fromYourData({ source: 'ga', sourceData: gscData })).toBe(false);
+ });
+});
diff --git a/web/src/lib/prompt-suggestion-source.ts b/web/src/lib/prompt-suggestion-source.ts
index 6d9354ad5..573971db0 100644
--- a/web/src/lib/prompt-suggestion-source.ts
+++ b/web/src/lib/prompt-suggestion-source.ts
@@ -59,3 +59,11 @@ export function gscSourceData(s: SourceCarrier): GscSuggestionSourceData | null
export function gaSourceData(s: SourceCarrier): GaSuggestionSourceData | null {
return s.source === 'ga' && s.sourceData && 'landingPage' in s.sourceData ? s.sourceData : null;
}
+
+/**
+ * Built from the brand's own Search Console or Analytics data: Prompt
+ * Suggestions' "From your data" filter, which Getting started links to.
+ */
+export function fromYourData(s: SourceCarrier): boolean {
+ return gscSourceData(s) !== null || gaSourceData(s) !== null;
+}