@nuxtseo/design-system 0.0.0-stage → 0.1.0

package/app/components/element/eject-menu.ts

@@ -0,0 +1,359 @@
+import type { LocationQueryRaw, RouteLocationRaw } from 'vue-router'
+import { CLI_INVOCATION } from '../../shared/cli'
+
+/**
+ * Eject-to-code / eject-to-chat payload shapes shared by `<UiEjectMenu>` and any
+ * primitive that embeds it (e.g. `<UiCard chat>`). The URL contract for the chat
+ * deep-link is owned by `layers/chat/app/internal/schemas/chat-deep-link.ts`; keep
+ * the `entity` / `filter` / `seed` fields in sync with that schema.
+ */
+export interface EjectChat {
+  /**
+   * Navigation target. **Default (omit `to`): open the contextual chat
+   * slide-over in place** on the current route — <ProChatPanel> self-opens on
+   * the `?seed=&entity=&filter=` query everywhere except `/chat` routes. This is
+   * the rule for every data-surface eject (card / row / section): stay in
+   * context. Only set `to: '/pro/dashboard/chat'` (full-page chat) in the two
+   * cases where an in-place slide-over can't or shouldn't open: (1) the eject
+   * lives inside another open overlay/modal, where a slide-over would stack; (2)
+   * a global launcher (command palette) where chat IS the destination.
+   */
+  to?: RouteLocationRaw
+  entity?: ChatEntityRef
+  filter?: Record<string, unknown>
+  seed?: string
+  // When true, the chat fires `sendMessage(seed)` automatically once hydrate
+  // resolves. Convention: eject seeds are complete, self-contained questions
+  // built from real card/row state, so they auto-send (`true`) — the user gets
+  // an answer on open, not a half-typed box. Leave unset only when the seed is a
+  // deliberate starting point the user is expected to edit before sending.
+  autoSend?: boolean
+}
+
+export interface EjectLink {
+  to: RouteLocationRaw
+  label?: string
+}
+
+export interface EjectMcp {
+  tool: string
+  args?: Record<string, unknown>
+  /**
+   * The Site this payload is about, as the `nuxtseo` CLI's `--site` expects it:
+   * the Site public id (`s_…`) that `nuxtseo sites list` prints. The canonical
+   * site id resolves too, so either is safe; a URL or a bare domain is NOT the
+   * same identifier and must never be passed here.
+   *
+   * `args.siteUrl` cannot stand in for it. That field is the MCP wire argument,
+   * a URL, and the CLI has no flag that takes one.
+   *
+   * Omit it only for an account-scoped tool. A site-scoped tool without it
+   * yields no CLI item at all (`serializeCliCommand` returns null) rather than a
+   * command that exits 5 `site_ambiguous` for anyone with two or more Sites.
+   * Pro surfaces build this payload as `ProMcpToolCall`, whose site-scoped
+   * variant makes the field REQUIRED, so a call site cannot forget it.
+   */
+  site?: string
+}
+
+/**
+ * Serialise an MCP eject payload in the MCP tools/call wire shape
+ * (`arguments`, not our internal `args`), so anything an agent or MCP inspector
+ * accepts can take it verbatim. Single owner of the copied string; UiEjectMenu
+ * and any bespoke menu must serialise through this.
+ *
+ * The payload is always the structured shape, never a pre-serialised string: a
+ * string carries no `tool` and no `site`, so the menu could not derive the CLI
+ * command that leads the eject set (ADR-0124). `ProActionRow` passed one for a
+ * while and silently lost its CLI item.
+ */
+export function serializeMcpCall(mcp: EjectMcp): string {
+  return JSON.stringify({ tool: mcp.tool, arguments: mcp.args ?? {} }, null, 2)
+}
+
+/**
+ * MCP tool → shipped `nuxtseo` CLI command. ADR-0124 makes the CLI the primary
+ * access surface, so the eject menu leads with a CLI command wherever one
+ * exists.
+ *
+ * Only tools whose command SHIPS today appear here. An unmapped tool returns
+ * null and the menu simply omits the item — a copied command that does not
+ * exist is the same broken promise the cURL ban used to guard against.
+ *
+ * `crux_vitals` (and its deprecated `performance` alias) is deliberately absent:
+ * it reads CrUX field p75, while the `performance` CLI command reads the
+ * Lighthouse lab overview. A mapping would copy a command that answers a
+ * different question.
+ */
+type CliArgs = Record<string, unknown>
+
+/**
+ * The raw pieces of one copied command, NOT a rendered string.
+ *
+ * An argument value may itself contain ` --` (a keyword like
+ * `best tools -- 2026 guide`, already legal under `shellArg` quoting), so any
+ * insertion point derived by splitting the rendered command lands INSIDE a
+ * quoted value and mangles it. Composing tokens and ordered flags structurally
+ * keeps every insertion point structural: `--site` joins between the root
+ * tokens and the command's own flags, whatever the values contain.
+ */
+interface CliFlag {
+  name: string
+  /** Omitted for a valueless flag; raw (unquoted) when present. */
+  value?: string
+}
+
+interface CliCommand {
+  /** Root positional tokens before any flag; raw (unquoted). */
+  tokens: string[]
+  /** Command-specific flags, ordered as the CLI documents them. */
+  flags: CliFlag[]
+}
+
+function cliCommand(tokens: string[], flags: Array<CliFlag | null>): CliCommand {
+  return { tokens, flags: flags.filter((entry): entry is CliFlag => entry !== null) }
+}
+
+// Quote only when the shell would otherwise split or interpret the value. A
+// bare `actions show t_9` is what the user would type; `actions show "t_9"`
+// reads like machine output and invites a copy that keeps the quotes.
+function shellArg(value: string): string {
+  return /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`
+}
+
+/** Renders one flag, quoting its value at emit time. */
+function renderFlag(entry: CliFlag): string {
+  return entry.value === undefined ? `--${entry.name}` : `--${entry.name} ${shellArg(entry.value)}`
+}
+
+function optionalFlag(args: CliArgs, key: string, name: string): CliFlag | null {
+  const value = args[key]
+  if (value === undefined || value === null || value === '')
+    return null
+  return { name, value: String(value) }
+}
+
+/**
+ * Every command below except `usage` and `sites list` resolves a Site before it
+ * runs (`apiAndSite` in `packages/cli/src/commands.ts`). Without `--site`, a
+ * non-interactive run of one of those exits 5 `site_ambiguous` the moment the
+ * token can see two Sites, so `scope: 'site'` is what makes the menu omit the
+ * item instead of copying a command that fails.
+ */
+interface CliCommandSpec {
+  scope: 'site' | 'account'
+  /**
+   * Null when the payload cannot make a runnable command — a required positional
+   * the args do not carry. The menu then omits the item, the same as for an
+   * unmapped tool. `nuxtseo research keywords --site s_x --json` with no topic
+   * exits 2 `invalid_cli_input`, which is a broken copy just as surely as an
+   * exit 5 is.
+   */
+  build: (args: CliArgs) => CliCommand | null
+}
+
+function text(args: CliArgs, ...keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = args[key]
+    if (typeof value === 'string' && value.trim())
+      return value.trim()
+  }
+  return undefined
+}
+
+// `search analytics <view>` takes the same view vocabulary `gsc_query` does
+// (pages · keywords · countries · devices · timeseries · page-detail ·
+// keyword-detail · analysis), so the copied command answers the question the
+// ejected section asks. It used to hardcode `keywords`, which meant ejecting the
+// Top pages card copied a keywords read.
+const GSC_QUERY_ROW_VIEWS = new Set(['pages', 'keywords', 'countries', 'devices', 'timeseries'])
+
+// The three views the CLI refuses without one more argument. Each names the arg
+// it needs on both surfaces, so a payload either carries it or the view has no
+// runnable command.
+const GSC_QUERY_DETAIL_VIEWS: Record<string, { argument: string, flag: string }> = {
+  'page-detail': { argument: 'pageUrl', flag: 'page-url' },
+  'keyword-detail': { argument: 'keyword', flag: 'keyword' },
+  'analysis': { argument: 'preset', flag: 'preset' },
+}
+
+// Analysis presets that additionally require `--brand-terms`; the CLI exits 2
+// `invalid_cli_input` without one.
+const GSC_QUERY_BRAND_PRESETS = new Set(['brand-only', 'non-brand'])
+
+function gscQueryCommand(args: CliArgs): CliCommand | null {
+  const view = text(args, 'view') ?? 'keywords'
+  const detail = GSC_QUERY_DETAIL_VIEWS[view]
+  if (!detail && !GSC_QUERY_ROW_VIEWS.has(view))
+    return null
+  const required = detail ? optionalFlag(args, detail.argument, detail.flag) : null
+  if (detail && !required)
+    return null
+  const flags = [required, optionalFlag(args, 'period', 'period'), optionalFlag(args, 'limit', 'limit')]
+  const preset = text(args, 'preset') ?? ''
+  if (view === 'analysis' && GSC_QUERY_BRAND_PRESETS.has(preset)) {
+    const brandTerms = text(args, 'brandTerms')
+    // The brand-only/non-brand presets exit 2 without --brand-terms; absent
+    // beats degraded, same rule as the Site guard.
+    if (!brandTerms)
+      return null
+    return cliCommand(['search', 'analytics', view], [...flags, { name: 'brand-terms', value: brandTerms }])
+  }
+  return cliCommand(['search', 'analytics', view], flags)
+}
+
+/**
+ * `keyword_research` is three commands, not one. Its `type` selects which, and
+ * each takes a different required positional: `research` and `serp` take a
+ * topic, `rankings` takes a domain. The map used to emit `research keywords`
+ * for all three, so the dashboard's Keywords eject (`type: 'rankings'`) copied a
+ * keyword-ideas command with no topic at all.
+ */
+function keywordResearchCommand(args: CliArgs): CliCommand | null {
+  const type = text(args, 'type') ?? 'research'
+  if (type === 'rankings') {
+    const domain = text(args, 'domain')
+    return domain ? cliCommand(['research', 'rankings', domain], [optionalFlag(args, 'limit', 'limit')]) : null
+  }
+  const topic = text(args, 'topic', 'keyword', 'seed')
+  if (!topic)
+    return null
+  return type === 'serp'
+    ? cliCommand(['research', 'serp', topic], [optionalFlag(args, 'depth', 'depth')])
+    : cliCommand(['research', 'keywords', topic], [optionalFlag(args, 'limit', 'limit')])
+}
+
+const CLI_COMMAND_BY_MCP_TOOL: Record<string, CliCommandSpec> = {
+  account_usage: { scope: 'account', build: () => cliCommand(['usage'], []) },
+  list_sites: { scope: 'account', build: () => cliCommand(['sites', 'list'], []) },
+  backlinks: { scope: 'site', build: args => cliCommand(['backlinks', 'recoverable'], [optionalFlag(args, 'limit', 'limit')]) },
+  competitors: { scope: 'site', build: () => cliCommand(['research', 'overview'], []) },
+  content_decay: { scope: 'site', build: args => cliCommand(['audit', 'content-decay'], [optionalFlag(args, 'limit', 'limit')]) },
+  domain_info: { scope: 'site', build: () => cliCommand(['research', 'overview'], []) },
+  duplicate_clusters: { scope: 'site', build: () => cliCommand(['audit', 'duplicates'], []) },
+  gsc_status: { scope: 'site', build: () => cliCommand(['search', 'status'], []) },
+  gsc_query: { scope: 'site', build: gscQueryCommand },
+  inspect_url: { scope: 'site', build: (args) => {
+    const url = text(args, 'url', 'pageUrl')
+    return url ? cliCommand(['page', 'inspect', url], []) : null
+  } },
+  keyword_research: { scope: 'site', build: keywordResearchCommand },
+  link_opportunities: { scope: 'site', build: args => cliCommand(['audit', 'link-opportunities'], [optionalFlag(args, 'limit', 'limit')]) },
+  mentions: { scope: 'site', build: args => cliCommand(['mentions', 'list'], [optionalFlag(args, 'limit', 'limit')]) },
+  next_actions: { scope: 'site', build: args => cliCommand(['actions', 'list'], [optionalFlag(args, 'limit', 'limit')]) },
+  action_details: { scope: 'site', build: (args) => {
+    const actionId = text(args, 'actionId', 'id')
+    return actionId ? cliCommand(['actions', 'show', actionId], []) : null
+  } },
+}
+
+/**
+ * Build the `nuxtseo` command that answers the same question as an MCP eject
+ * payload, or null when the CLI cannot answer it. Single owner of the copied
+ * string, the way `serializeMcpCall` owns the MCP one.
+ *
+ * Three reasons to return null, and each means the menu shows no CLI item: the
+ * tool has no shipped command, the command needs a Site and the payload carries
+ * none, or the payload is missing an argument the command requires. Absent beats
+ * degraded — a copied `nuxtseo actions list --json` with no `--site` exits 5 for
+ * every Caller with more than one Site.
+ *
+ * `--site` sits directly after the command, before any command-specific flags,
+ * matching the shape the shipped agent skill documents. `--json` is always last:
+ * an agent parses the envelope, and a human reading the command can drop it.
+ */
+export function serializeCliCommand(mcp: EjectMcp): string | null {
+  const spec = CLI_COMMAND_BY_MCP_TOOL[mcp.tool]
+  if (!spec)
+    return null
+  const site = typeof mcp.site === 'string' ? mcp.site.trim() : ''
+  if (spec.scope === 'site' && !site)
+    return null
+  const built = spec.build(mcp.args ?? {})
+  if (!built)
+    return null
+  // Structural composition, joined exactly once: root tokens, then --site,
+  // then the command's own flags in documented order, then --json. Values are
+  // quoted per value at emit time, so an argument containing ' --' can never
+  // be mistaken for a flag boundary.
+  const segments = [
+    ...built.tokens.map(shellArg),
+    ...(site ? [renderFlag({ name: 'site', value: site })] : []),
+    ...built.flags.map(renderFlag),
+    '--json',
+  ]
+  return [CLI_INVOCATION, ...segments].join(' ')
+}
+
+/**
+ * A first-class operation (not an eject-to-code copy), e.g. "Run checks now".
+ * Rendered as a leading group above the cURL/MCP/schema items so a row can carry
+ * its own actions through the menu it already has, instead of an extra button.
+ */
+export interface EjectAction {
+  label: string
+  icon?: string
+  onSelect: () => void | Promise<void>
+  disabled?: boolean
+}
+
+/**
+ * A scheme-prefixed chat entity reference (`site:s_x`, `page:https://…`). The
+ * template type rejects the bare-id mistake at compile time; UiEjectMenu adds a
+ * dev-mode warning for the case the type can't catch (a raw URL, whose "https"
+ * prefix satisfies the pattern but is no registered scheme).
+ */
+export type ChatEntityRef = `${string}:${string}`
+
+/**
+ * Entity references the chat hydrate registry can resolve (`chat:hydrate` Nitro
+ * hook — site/page/query/issue in pro-gsc, competitor/keyword in pro-dataforseo,
+ * cwv in pro-perf, country in pro-gsc). Always build `EjectChat.entity` through
+ * these instead of string-interpolating: a bare id ("s_x…") or raw URL parses as
+ * no scheme / scheme "https" and the hydrate step silently skips, so the chat
+ * answers without the grounding the eject promised.
+ */
+export const chatEntity = {
+  site: (id: string): `site:${string}` => `site:${id}`,
+  page: (url: string): `page:${string}` => `page:${url}`,
+  query: (keyword: string): `query:${string}` => `query:${keyword}`,
+  keyword: (keyword: string): `keyword:${string}` => `keyword:${keyword}`,
+  competitor: (domain: string): `competitor:${string}` => `competitor:${domain}`,
+  cwv: (metric: string): `cwv:${string}` => `cwv:${metric}`,
+  issue: (id: string): `issue:${string}` => `issue:${id}`,
+  country: (code: string): `country:${string}` => `country:${code}`,
+} as const
+
+/**
+ * Query keys owned by the chat deep-link contract (plus chat-page-only keys a
+ *  handoff must never carry over). Kept in sync with
+ *  `layers/chat/app/internal/schemas/chat-deep-link.ts`.
+ */
+const CHAT_DEEP_LINK_KEYS = ['entity', 'filter', 'seed', 'autoSend', 'chatNonce', 'conversationId', 'context', 'prefill'] as const
+
+/**
+ * Single builder for the chat deep-link query. Preserves the surface's own query
+ * state (filters, tabs, sort) by spreading `currentQuery` minus any stale
+ * deep-link keys — ejecting must never wipe the URL state the user set up,
+ * because `clear()` on the receiving side can only strip the deep-link keys, not
+ * restore what a bare `{ query }` navigation dropped.
+ */
+export function buildChatDeepLinkQuery(
+  currentQuery: Record<string, unknown>,
+  c: Pick<EjectChat, 'entity' | 'filter' | 'seed' | 'autoSend'>,
+): LocationQueryRaw {
+  const rest: LocationQueryRaw = {}
+  for (const [k, v] of Object.entries(currentQuery)) {
+    if (!(CHAT_DEEP_LINK_KEYS as readonly string[]).includes(k))
+      rest[k] = v as LocationQueryRaw[string]
+  }
+  if (c.entity)
+    rest.entity = c.entity
+  if (c.filter)
+    rest.filter = JSON.stringify(c.filter)
+  if (c.seed)
+    rest.seed = c.seed
+  if (c.autoSend)
+    rest.autoSend = '1'
+  return rest
+}

package/app/components/element/eject-tracker.ts

@@ -0,0 +1,34 @@
+import type { InjectionKey } from 'vue'
+import { inject } from 'vue'
+
+/** Code-eject actions a UiEjectMenu can fire. Mirrors the menu's item set. */
+export type EjectTrackAction = 'copy-cli' | 'copy-mcp' | 'open-chat' | 'view-schema'
+
+/**
+ * A code-eject was invoked from a UiEjectMenu. `action` + the implied
+ * surface='eject-menu' are filled by the menu itself; `kind`/`variant` are
+ * optional call-site enrichment (the menu can't know its domain entity).
+ */
+export interface EjectTrackEvent {
+  action: EjectTrackAction
+  /** Domain entity the menu was attached to, e.g. 'keyword' | 'competitor' | 'cwv'. */
+  kind?: string
+  /** Sub-variant within the kind (page goal, competitor focus, …). */
+  variant?: string
+}
+
+export type EjectTracker = (event: EjectTrackEvent) => void
+
+/**
+ * Provide/inject seam so design-system's UiEjectMenu can emit eject telemetry
+ * without importing the pro-features tracker (layer rule: design-system MUST
+ * NOT depend on runtime services). pro-features provides the impl via an app
+ * plugin; absent a provider this no-ops.
+ */
+export const ejectTrackerKey: InjectionKey<EjectTracker> = Symbol('eject-tracker')
+
+const noop: EjectTracker = () => {}
+
+export function useEjectTracker(): EjectTracker {
+  return inject(ejectTrackerKey, noop)
+}

package/app/components/element/onboarding-answers.ts

@@ -0,0 +1,68 @@
+// The onboarding "About you" questions: display data only (id/label), ordered.
+// The ids are shared with gscdump.com and Request Indexing, which keep a copy of
+// this file. Change an id in all three repositories or not at all.
+// The goal list is per product and lives in onboarding-intents.ts.
+import { ONBOARDING_INTENTS } from './onboarding-intents'
+
+export const ONBOARDING_ROLES = [
+  { id: 'solo', label: 'Solo developer' },
+  { id: 'agency', label: 'Agency or freelancer' },
+  { id: 'in-house', label: 'In-house team' },
+  { id: 'tool-builder', label: 'Building an SEO tool' },
+  { id: 'other', label: 'Something else' },
+] as const
+
+export const ONBOARDING_SITE_COUNTS = [
+  { id: '1', label: '1' },
+  { id: '2-5', label: '2–5' },
+  { id: '6-20', label: '6–20' },
+  { id: '21+', label: '21+' },
+] as const
+
+export const ONBOARDING_SEO_EXPERIENCE = [
+  { id: 'new', label: 'New to it' },
+  { id: 'basics', label: 'Know the basics' },
+  { id: 'professional', label: 'Do it for a living' },
+] as const
+
+export type OnboardingRole = (typeof ONBOARDING_ROLES)[number]['id']
+export type OnboardingSiteCount = (typeof ONBOARDING_SITE_COUNTS)[number]['id']
+export type OnboardingSeoExperience = (typeof ONBOARDING_SEO_EXPERIENCE)[number]['id']
+
+export const ONBOARDING_ROLE_IDS = ONBOARDING_ROLES.map(option => option.id) as [OnboardingRole, ...OnboardingRole[]]
+export const ONBOARDING_SITE_COUNT_IDS = ONBOARDING_SITE_COUNTS.map(option => option.id) as [OnboardingSiteCount, ...OnboardingSiteCount[]]
+export const ONBOARDING_SEO_EXPERIENCE_IDS = ONBOARDING_SEO_EXPERIENCE.map(option => option.id) as [OnboardingSeoExperience, ...OnboardingSeoExperience[]]
+export const ONBOARDING_INTENT_IDS = ONBOARDING_INTENTS.map(intent => intent.id) as [string, ...string[]]
+
+/** Free text under the goals question. The server schema enforces the same limit. */
+export const ONBOARDING_OTHER_MAX_LENGTH = 500
+
+export const ONBOARDING_QUESTIONS = {
+  role: 'What best describes you?',
+  siteCount: 'How many websites do you look after?',
+  seoExperience: 'How comfortable are you with SEO?',
+  intents: 'What do you want to do with Nuxt SEO Pro?',
+} as const
+
+/** Label lookup for stored ids. An unknown id renders as itself. */
+export function onboardingAnswerLabel(options: readonly { id: string, label: string }[], id: string): string {
+  return options.find(option => option.id === id)?.label ?? id
+}
+
+/** The help step's unsaved answers. A single-choice question with no chip picked is `undefined`. */
+export interface OnboardingAnswersDraft {
+  role?: OnboardingRole
+  siteCount?: OnboardingSiteCount
+  seoExperience?: OnboardingSeoExperience
+  intents: string[]
+  other: string
+}
+
+export function emptyOnboardingAnswersDraft(): OnboardingAnswersDraft {
+  return { intents: [], other: '' }
+}
+
+/** True when the user picked a chip or wrote text, so there is something to save. */
+export function hasOnboardingAnswers(draft: OnboardingAnswersDraft): boolean {
+  return !!(draft.role || draft.siteCount || draft.seoExperience || draft.intents.length || draft.other.trim())
+}

package/app/components/element/onboarding-intents.ts

@@ -0,0 +1,19 @@
+// The onboarding "How can we help?" options — display data only (id/label/icon),
+// ordered. Lives in design-system (alongside the UiWizard* family + the in-memory
+// onboarding service) so both the live pro flow and the brand-kit showcase render
+// the same list. The app maps id → internal focus separately (teams/create.vue).
+export interface OnboardingIntent {
+  id: string
+  label: string
+  icon: string
+}
+
+export const ONBOARDING_INTENTS: OnboardingIntent[] = [
+  { id: 'competitors', label: 'Beat my competitors', icon: 'chart-line' },
+  { id: 'visitors', label: 'Get more visitors', icon: 'search' },
+  { id: 'technical', label: 'Improve technical SEO', icon: 'shield-check' },
+  { id: 'ai', label: 'Show up in AI answers', icon: 'bot' },
+  { id: 'recover', label: 'Recover lost traffic', icon: 'i-lucide-rotate-ccw' },
+  { id: 'speed', label: 'Speed up my site', icon: 'i-lucide-gauge' },
+  { id: 'authority', label: 'Earn backlinks & mentions', icon: 'i-lucide-megaphone' },
+]