@prenta/admin 1.15.0 → 1.17.0

package/src/views/seo/AiVisibilityTab.tsx

@@ -0,0 +1,616 @@
+'use client'
+
+/**
+ * SEO → AI visibility (spec 2026-09-08 §6): daily AI/search crawler trend,
+ * AI-engine referral visits, and the pages behind both. Data is self-reported
+ * by the site middleware via `POST /geo/beacon`; the tab says so. Everything
+ * flows through `fetchSeoGeo` in `lib/seo-service.ts`.
+ */
+import { useMemo, useState } from 'react'
+import {
+  Bar,
+  BarChart,
+  CartesianGrid,
+  Legend,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from 'recharts'
+import {
+  Bot,
+  ExternalLink,
+  Minus,
+  RefreshCw,
+  ShieldAlert,
+  ShieldCheck,
+  ShieldOff,
+  TrendingDown,
+  TrendingUp,
+} from 'lucide-react'
+import {
+  fetchSeoGeo,
+  type SeoGeoBotCategory,
+  type SeoGeoBotPolicy,
+  type SeoGeoDays,
+  type SeoGeoEntityRef,
+  type SeoGeoReport,
+} from '../../lib/seo-service.js'
+import { sourceEditPath } from '../../lib/collection-routes.js'
+import {
+  SectionCard,
+  SeoEmptyState,
+  SeoErrorState,
+  SeoLoading,
+  btnSecondary,
+} from '../../components/seo/primitives.js'
+import { relativeAge } from './relative-age.js'
+import { useSeoResource } from './useSeoResource.js'
+
+const WINDOWS: ReadonlyArray<{ days: SeoGeoDays; label: string }> = [
+  { days: 7, label: '7 days' },
+  { days: 28, label: '28 days' },
+  { days: 90, label: '90 days' },
+]
+const CATEGORY_LABEL: Record<SeoGeoBotCategory, string> = {
+  training: 'AI training',
+  retrieval: 'AI retrieval',
+  search: 'Search',
+}
+/** Bots drawn as their own stacked series; the rest fold into "Other". */
+const CHART_SERIES = 5
+/**
+ * recharts paints SVG `fill`s, which Tailwind utilities cannot reach, so the
+ * chart tokens are referenced as CSS variables. They are the theme's own
+ * `--chart-*` series colours and follow dark mode.
+ */
+const CHART_TOKENS = [
+  'var(--chart-1)',
+  'var(--chart-2)',
+  'var(--chart-3)',
+  'var(--chart-4)',
+  'var(--chart-5)',
+] as const
+const CHART_OTHER_TOKEN = 'var(--muted-foreground)'
+const CHART_TOOLTIP_STYLE = {
+  background: 'var(--card)',
+  border: '1px solid var(--border)',
+  borderRadius: 'var(--radius-md)',
+  color: 'var(--foreground)',
+  fontSize: 12,
+} as const
+const SEO_SETTINGS_PATH = '/settings?tab=seo'
+const EM_DASH = '—'
+
+const th = 'py-2 pr-3 font-medium'
+const thRight = 'py-2 pr-3 text-right font-medium'
+const headRow = 'border-border text-muted-foreground border-b text-left'
+const tdNum = 'text-foreground py-2 pr-3 text-right tabular-nums'
+
+// ─── Cells ───────────────────────────────────────────────────────────────
+
+/** Percentage change vs the prior window; `null` prev means "no full baseline". */
+function Delta({ current, prev }: { current: number; prev: number | null }) {
+  if (prev === null) {
+    return (
+      <span className="text-muted-foreground" title="No full prior window yet">
+        <span aria-hidden>{EM_DASH}</span>
+        <span className="sr-only">No full prior window yet</span>
+      </span>
+    )
+  }
+  if (prev === 0 && current > 0) return <span className="text-muted-foreground">new</span>
+  const pct = prev === 0 ? 0 : Math.round(((current - prev) / prev) * 100)
+  const Icon = pct > 0 ? TrendingUp : pct < 0 ? TrendingDown : Minus
+  const tone = pct > 0 ? 'text-success' : pct < 0 ? 'text-destructive' : 'text-muted-foreground'
+  return (
+    <span className={`inline-flex items-center gap-1 tabular-nums ${tone}`}>
+      <Icon className="h-4 w-4" aria-hidden />
+      {pct > 0 ? '+' : ''}
+      {pct}%
+    </span>
+  )
+}
+
+function PolicyLabel({ policy }: { policy: SeoGeoBotPolicy }) {
+  switch (policy) {
+    case 'allowed':
+      return (
+        <span className="text-muted-foreground inline-flex items-center gap-1">
+          <ShieldCheck className="h-4 w-4" aria-hidden /> Allowed
+        </span>
+      )
+    case 'blocked':
+      return (
+        <span className="text-muted-foreground inline-flex items-center gap-1">
+          <ShieldOff className="h-4 w-4" aria-hidden /> Blocked
+        </span>
+      )
+    case 'blocked_still_crawling':
+      return (
+        <span className="text-destructive inline-flex items-center gap-1">
+          <ShieldAlert className="h-4 w-4" aria-hidden /> Blocked — still crawling
+        </span>
+      )
+    default: {
+      const _exhaustive: never = policy
+      return _exhaustive
+    }
+  }
+}
+
+/**
+ * A path, promoted to an "open in editor" button only when the server joined
+ * it to a document *and* the host gave us a navigator.
+ */
+function PathCell({
+  path,
+  entityId,
+  entityTitle,
+  collection,
+  onNavigate,
+}: SeoGeoEntityRef & { path: string; onNavigate?: (p: string) => void }) {
+  if (!entityId || !onNavigate) return <span className="text-foreground break-all">{path}</span>
+  return (
+    <button
+      type="button"
+      className="text-foreground hover:text-primary focus-visible:ring-ring inline-flex items-center gap-1 rounded-sm text-left break-all underline-offset-2 hover:underline focus-visible:ring-2 focus-visible:outline-none"
+      onClick={() => onNavigate(sourceEditPath(collection, entityId))}
+      aria-label={`Open ${entityTitle ?? path} in editor`}
+    >
+      {path}
+      <ExternalLink className="h-3.5 w-3.5 shrink-0" aria-hidden />
+    </button>
+  )
+}
+
+// ─── Controls ────────────────────────────────────────────────────────────
+
+/**
+ * Segmented window picker — the same `role="group"` + `aria-pressed` toggle
+ * pattern as the Audit / Content filters. Never disabled while loading:
+ * `useSeoResource` discards stale responses, and disabling the focused
+ * button would drop keyboard focus to `<body>` mid-request.
+ */
+function WindowSwitch({
+  value,
+  onChange,
+}: {
+  value: SeoGeoDays
+  onChange: (d: SeoGeoDays) => void
+}) {
+  return (
+    <div
+      role="group"
+      aria-label="Window"
+      className="border-border inline-flex rounded-md border p-0.5"
+    >
+      {WINDOWS.map((w) => (
+        <button
+          key={w.days}
+          type="button"
+          aria-pressed={value === w.days}
+          className={`focus-visible:ring-ring rounded-sm px-3 py-1 text-sm font-medium transition-colors focus-visible:ring-2 focus-visible:outline-none ${
+            value === w.days
+              ? 'bg-primary text-primary-foreground'
+              : 'text-muted-foreground hover:bg-accent hover:text-foreground'
+          }`}
+          onClick={() => onChange(w.days)}
+        >
+          {w.label}
+        </button>
+      ))}
+    </div>
+  )
+}
+
+// ─── Chart ───────────────────────────────────────────────────────────────
+
+function CrawlChart({
+  series,
+  bots,
+}: {
+  series: SeoGeoReport['crawl']['series']
+  bots: SeoGeoReport['crawl']['bots']
+}) {
+  const { top, data, hasOther } = useMemo(() => {
+    const top = bots.slice(0, CHART_SERIES).map((b) => b.bot)
+    const hasOther = bots.length > CHART_SERIES
+    const data = series.map((day) => {
+      const row: Record<string, number | string> = { date: day.date.slice(5) }
+      let other = 0
+      for (const [bot, hits] of Object.entries(day.hits)) {
+        if (top.includes(bot)) row[bot] = hits
+        else other += hits
+      }
+      if (hasOther) row.Other = other
+      return row
+    })
+    return { top, data, hasOther }
+  }, [series, bots])
+
+  return (
+    // The Crawlers table below carries the same numbers for assistive tech.
+    <div className="h-56 w-full" role="img" aria-label="Daily crawler hits by bot">
+      <ResponsiveContainer width="100%" height="100%">
+        <BarChart data={data}>
+          <CartesianGrid strokeDasharray="3 3" stroke="var(--border)" />
+          <XAxis dataKey="date" tick={{ fontSize: 12, fill: 'var(--muted-foreground)' }} />
+          <YAxis
+            allowDecimals={false}
+            tick={{ fontSize: 12, fill: 'var(--muted-foreground)' }}
+            width={32}
+          />
+          <Tooltip contentStyle={CHART_TOOLTIP_STYLE} cursor={{ fill: 'var(--accent)' }} />
+          <Legend wrapperStyle={{ fontSize: 12 }} />
+          {top.map((bot, i) => (
+            <Bar
+              key={bot}
+              dataKey={bot}
+              stackId="hits"
+              fill={CHART_TOKENS[i % CHART_TOKENS.length]}
+            />
+          ))}
+          {hasOther && <Bar dataKey="Other" stackId="hits" fill={CHART_OTHER_TOKEN} />}
+        </BarChart>
+      </ResponsiveContainer>
+    </div>
+  )
+}
+
+// ─── Sections ────────────────────────────────────────────────────────────
+
+function CrawlSection({ crawl }: { crawl: SeoGeoReport['crawl'] }) {
+  return (
+    <SectionCard
+      title="Crawl trend"
+      description="Daily hits by AI training, AI retrieval, and search crawlers (Googlebot, Bingbot — counted so AI answer surfaces backed by web search are visible; the AI robots policy never blocks these)."
+    >
+      <div className="space-y-4">
+        <dl
+          role="group"
+          aria-label="Crawl summary"
+          className="grid grid-cols-2 gap-3 text-sm sm:grid-cols-3"
+        >
+          <div>
+            <dt className="text-muted-foreground">Crawler hits</dt>
+            <dd className="text-foreground font-medium tabular-nums">{crawl.total.hits}</dd>
+          </div>
+          <div>
+            <dt className="text-muted-foreground">Δ vs prior</dt>
+            <dd>
+              <Delta current={crawl.total.hits} prev={crawl.total.prevHits} />
+            </dd>
+          </div>
+          <div>
+            <dt className="text-muted-foreground">Distinct bots</dt>
+            <dd className="text-foreground font-medium tabular-nums">{crawl.bots.length}</dd>
+          </div>
+        </dl>
+        <CrawlChart series={crawl.series} bots={crawl.bots} />
+        <div className="overflow-x-auto">
+          <table className="w-full min-w-[640px] text-sm" aria-label="Crawlers">
+            <thead>
+              <tr className={headRow}>
+                <th scope="col" className={th}>
+                  Bot
+                </th>
+                <th scope="col" className={th}>
+                  Type
+                </th>
+                <th scope="col" className={thRight}>
+                  Hits
+                </th>
+                <th scope="col" className={thRight}>
+                  Δ vs prior
+                </th>
+                <th scope="col" className={th}>
+                  Last seen
+                </th>
+                <th scope="col" className={th}>
+                  Policy
+                </th>
+              </tr>
+            </thead>
+            <tbody className="divide-border divide-y">
+              {crawl.bots.map((b) => (
+                <tr key={b.bot}>
+                  <td className="text-foreground py-2 pr-3 font-medium">{b.bot}</td>
+                  <td className="text-muted-foreground py-2 pr-3">{CATEGORY_LABEL[b.category]}</td>
+                  <td className={tdNum}>{b.hits}</td>
+                  <td className="py-2 pr-3 text-right">
+                    <Delta current={b.hits} prev={b.prevHits} />
+                  </td>
+                  <td className="text-muted-foreground py-2 pr-3 tabular-nums">
+                    {b.lastSeenAt ?? EM_DASH}
+                  </td>
+                  <td className="py-2">
+                    <PolicyLabel policy={b.policy} />
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </SectionCard>
+  )
+}
+
+function ReferralsSection({
+  referrals,
+  onNavigate,
+}: {
+  referrals: SeoGeoReport['referrals']
+  onNavigate?: (path: string) => void
+}) {
+  return (
+    <SectionCard
+      title="AI referrals"
+      description="Visits that arrived from an answer engine (Referer or utm_source)."
+    >
+      <div className="space-y-4">
+        <dl
+          role="group"
+          aria-label="Referral summary"
+          className="grid grid-cols-2 gap-3 text-sm sm:grid-cols-3"
+        >
+          <div>
+            <dt className="text-muted-foreground">Visits</dt>
+            <dd className="text-foreground font-medium tabular-nums">{referrals.total.visits}</dd>
+          </div>
+          <div>
+            <dt className="text-muted-foreground">Δ vs prior</dt>
+            <dd>
+              <Delta current={referrals.total.visits} prev={referrals.total.prevVisits} />
+            </dd>
+          </div>
+        </dl>
+        {referrals.engines.length > 0 && (
+          <div className="overflow-x-auto">
+            <table className="w-full min-w-[480px] text-sm" aria-label="Engines">
+              <thead>
+                <tr className={headRow}>
+                  <th scope="col" className={th}>
+                    Engine
+                  </th>
+                  <th scope="col" className={thRight}>
+                    Visits
+                  </th>
+                  <th scope="col" className={thRight}>
+                    Δ vs prior
+                  </th>
+                </tr>
+              </thead>
+              <tbody className="divide-border divide-y">
+                {referrals.engines.map((e) => (
+                  <tr key={e.engine}>
+                    <td className="text-foreground py-2 pr-3 font-medium">{e.engine}</td>
+                    <td className={tdNum}>{e.visits}</td>
+                    <td className="py-2 pr-3 text-right">
+                      <Delta current={e.visits} prev={e.prevVisits} />
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        )}
+        {referrals.topPaths.length > 0 && (
+          <div className="overflow-x-auto">
+            <table className="w-full min-w-[640px] text-sm" aria-label="Top cited pages">
+              <thead>
+                <tr className={headRow}>
+                  <th scope="col" className={th}>
+                    Path
+                  </th>
+                  <th scope="col" className={thRight}>
+                    Visits
+                  </th>
+                  <th scope="col" className={th}>
+                    Engines
+                  </th>
+                </tr>
+              </thead>
+              <tbody className="divide-border divide-y">
+                {referrals.topPaths.map((p) => (
+                  <tr key={p.path}>
+                    <td className="py-2 pr-3">
+                      <PathCell
+                        path={p.path}
+                        entityId={p.entityId}
+                        entityTitle={p.entityTitle}
+                        collection={p.collection}
+                        onNavigate={onNavigate}
+                      />
+                    </td>
+                    <td className={tdNum}>{p.visits}</td>
+                    <td className="text-muted-foreground py-2">{p.engines.join(', ')}</td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        )}
+        {referrals.otherVisits > 0 && (
+          <p className="text-muted-foreground text-sm">
+            {referrals.otherVisits} visits on paths beyond the daily cap.
+          </p>
+        )}
+      </div>
+    </SectionCard>
+  )
+}
+
+function TopCrawledSection({
+  crawl,
+  onNavigate,
+}: {
+  crawl: SeoGeoReport['crawl']
+  onNavigate?: (path: string) => void
+}) {
+  return (
+    <SectionCard
+      title="Top crawled pages"
+      description="Paths most fetched by AI and search crawlers in this window."
+    >
+      <div className="overflow-x-auto">
+        <table className="w-full min-w-[640px] text-sm" aria-label="Top crawled pages">
+          <thead>
+            <tr className={headRow}>
+              <th scope="col" className={th}>
+                Path
+              </th>
+              <th scope="col" className={thRight}>
+                Hits
+              </th>
+              <th scope="col" className={th}>
+                Bots
+              </th>
+            </tr>
+          </thead>
+          <tbody className="divide-border divide-y">
+            {crawl.topPaths.map((p) => (
+              <tr key={p.path}>
+                <td className="py-2 pr-3">
+                  <PathCell
+                    path={p.path}
+                    entityId={p.entityId}
+                    entityTitle={p.entityTitle}
+                    collection={p.collection}
+                    onNavigate={onNavigate}
+                  />
+                </td>
+                <td className={tdNum}>{p.hits}</td>
+                <td className="text-muted-foreground py-2">{p.bots.join(', ')}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+      {crawl.otherHits > 0 && (
+        <p className="text-muted-foreground mt-3 text-sm">
+          {crawl.otherHits} hits on paths beyond the daily cap.
+        </p>
+      )}
+    </SectionCard>
+  )
+}
+
+// ─── Tab ─────────────────────────────────────────────────────────────────
+
+export function AiVisibilityTab({ onNavigate }: { onNavigate?: (path: string) => void }) {
+  const [days, setDays] = useState<SeoGeoDays>(28)
+  const { data, loading, error, refetch } = useSeoResource(() => fetchSeoGeo(days), [days])
+
+  const header = (
+    <div className="flex flex-wrap items-center justify-between gap-3">
+      <div className="flex flex-wrap items-center gap-3">
+        <WindowSwitch value={days} onChange={setDays} />
+        {data?.firstSeenAt && (
+          <span className="text-muted-foreground text-sm">
+            First seen {relativeAge(data.firstSeenAt) || data.firstSeenAt}
+          </span>
+        )}
+      </div>
+      <button type="button" className={btnSecondary} onClick={() => refetch()} disabled={loading}>
+        <RefreshCw className={`h-4 w-4 ${loading ? 'motion-safe:animate-spin' : ''}`} aria-hidden />
+        Refresh
+      </button>
+    </div>
+  )
+
+  if (loading && !data) {
+    return (
+      <div className="space-y-4">
+        {header}
+        <SeoLoading label="Loading AI visibility…" />
+      </div>
+    )
+  }
+  if (error) {
+    return (
+      <div className="space-y-4">
+        {header}
+        <SeoErrorState message={error} onRetry={refetch} />
+      </div>
+    )
+  }
+  if (!data) return null
+
+  // Both setup-ish empty states send the editor to Settings → SEO (the kill
+  // switch and the middleware snippet live on the same card).
+  const settingsAction = (label: string) =>
+    onNavigate && (
+      <button type="button" className={btnSecondary} onClick={() => onNavigate(SEO_SETTINGS_PATH)}>
+        {label}
+      </button>
+    )
+
+  if (!data.enabled) {
+    // `unavailable` = the tables are not in the schema; the setting cannot
+    // fix that, so no settings action is offered for it.
+    const unavailable = data.disabledReason === 'unavailable'
+    return (
+      <div className="space-y-4">
+        {header}
+        {unavailable ? (
+          <SeoEmptyState
+            icon={<Bot size={24} />}
+            title="GEO tables not migrated"
+            description="Run `prisma migrate deploy` (migration `0018_geo_daily`) on the CMS database, then reload."
+          />
+        ) : (
+          <SeoEmptyState
+            icon={<Bot size={24} />}
+            title="Measurement is off"
+            description="Turn on AI visibility measurement in Settings → SEO to start recording AI crawler hits and AI-engine referrals."
+            action={settingsAction('Open SEO settings')}
+          />
+        )}
+      </div>
+    )
+  }
+
+  if (data.firstSeenAt === null) {
+    return (
+      <div className="space-y-4">
+        {header}
+        <SeoEmptyState
+          icon={<Bot size={24} />}
+          title="The site middleware is not reporting yet"
+          description="Add observeGeoTraffic to your site's proxy.ts (Next) or use createAstroRedirectMiddleware (Astro). Counts appear here as soon as the first AI or search crawler visits."
+          action={settingsAction('Show middleware snippet')}
+        />
+      </div>
+    )
+  }
+
+  const hasRows = data.crawl.bots.length > 0 || data.referrals.engines.length > 0
+
+  return (
+    <div className="space-y-4">
+      {header}
+      <p className="text-muted-foreground text-sm">
+        Counts are self-reported by your middleware; they show real bot names on real paths but are
+        not audited traffic.
+      </p>
+
+      {!hasRows ? (
+        <SeoEmptyState
+          icon={<Bot size={24} />}
+          title="No AI crawler or referral activity in this window"
+          description="Try a longer window."
+        />
+      ) : (
+        <>
+          <CrawlSection crawl={data.crawl} />
+          <ReferralsSection referrals={data.referrals} onNavigate={onNavigate} />
+          {data.crawl.topPaths.length > 0 && (
+            <TopCrawledSection crawl={data.crawl} onNavigate={onNavigate} />
+          )}
+        </>
+      )}
+    </div>
+  )
+}