feat(seo): enhance SEO functionality with dynamic updates and improved validation

Author: abedshaaban

packages/devtools-seo/src/heading-structure-preview.tsx

@@ -1,4 +1,11 @@
-import { For, Show, createMemo, createSignal } from 'solid-js'
+import {
+  For,
+  Show,
+  createMemo,
+  createSignal,
+  onCleanup,
+  onMount,
+} from 'solid-js'
 import { Section, SectionDescription } from '@tanstack/devtools-ui'
 import { useSeoStyles } from './use-seo-styles'
 import { pickSeverityClass } from './seo-severity'
@@ -143,9 +150,29 @@ function headingTagClass(
 export function HeadingStructurePreviewSection() {
   const styles = useSeoStyles()
   const [tick, setTick] = createSignal(0)
+  const rescan = () => setTick((t) => t + 1)
 
-  useLocationChanges(() => {
-    setTick((t) => t + 1)
+  useLocationChanges(rescan)
+
+  onMount(() => {
+    const observer = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        const target = mutation.target
+        if (target instanceof Element && isInsideDevtools(target)) continue
+        if (target.parentElement && isInsideDevtools(target.parentElement))
+          continue
+        rescan()
+        break
+      }
+    })
+
+    observer.observe(document.body, {
+      childList: true,
+      characterData: true,
+      subtree: true,
+    })
+
+    onCleanup(() => observer.disconnect())
   })
 
   const headings = createMemo(() => {
@@ -174,7 +201,7 @@ export function HeadingStructurePreviewSection() {
     <Section>
       <SectionDescription>
         Visualizes heading structure (`h1`-`h6`) in DOM order and highlights
-        common hierarchy issues. This section scans once when opened.
+        common hierarchy issues. This section refreshes as the page changes.
       </SectionDescription>
 
       <div class={s.serpPreviewBlock}>

packages/devtools-seo/src/hooks/use-location-changes.ts

@@ -32,23 +32,30 @@ function observeLocationChanges() {
     emitLocationChangeIfNeeded()
   }
 
-  window.history.pushState = function (...args) {
-    originalPushState.apply(this, args)
+  function patchedPushState(...args: Parameters<History['pushState']>) {
+    originalPushState.apply(window.history, args)
     dispatchLocationChangeEvent()
   }
 
-  window.history.replaceState = function (...args) {
-    originalReplaceState.apply(this, args)
+  function patchedReplaceState(...args: Parameters<History['replaceState']>) {
+    originalReplaceState.apply(window.history, args)
     dispatchLocationChangeEvent()
   }
 
+  window.history.pushState = patchedPushState
+  window.history.replaceState = patchedReplaceState
+
   window.addEventListener('popstate', handleLocationSignal)
   window.addEventListener('hashchange', handleLocationSignal)
   window.addEventListener(LOCATION_CHANGE_EVENT, handleLocationSignal)
 
   teardownLocationObservation = () => {
-    window.history.pushState = originalPushState
-    window.history.replaceState = originalReplaceState
+    if (window.history.pushState === patchedPushState) {
+      window.history.pushState = originalPushState
+    }
+    if (window.history.replaceState === patchedReplaceState) {
+      window.history.replaceState = originalReplaceState
+    }
     window.removeEventListener('popstate', handleLocationSignal)
     window.removeEventListener('hashchange', handleLocationSignal)
     window.removeEventListener(LOCATION_CHANGE_EVENT, handleLocationSignal)

packages/devtools-seo/src/json-ld-preview.tsx

@@ -4,6 +4,7 @@ import { isInsideDevtools } from './devtools-dom-filter'
 import { useSeoStyles } from './use-seo-styles'
 import { pickSeverityClass, seoHealthTier } from './seo-severity'
 import type { SeoSeverity } from './seo-severity'
+import { sectionHealthScore } from './seo-section-summary'
 import type { SeoSectionSummary } from './seo-section-summary'
 
 type JsonLdValue = Record<string, unknown>
@@ -84,8 +85,6 @@ function entryUsesOnlySupportedTypes(entry: JsonLdEntry): boolean {
   return entry.types.every(isSupportedSchemaType)
 }
 
-const RESERVED_KEYS = new Set(['@context', '@type', '@id', '@graph'])
-
 function isRecord(value: unknown): value is JsonLdValue {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
@@ -134,9 +133,32 @@ const VALID_SCHEMA_CONTEXTS = new Set([
 
 function validateContext(entity: JsonLdValue): Array<ValidationIssue> {
   const context = entity['@context']
-  if (!context) {
+  if (context === undefined) {
     return [{ severity: 'error', message: 'Missing @context attribute.' }]
   }
+  if (context === null || isRecord(context)) {
+    return []
+  }
+  if (Array.isArray(context)) {
+    const stringContexts = context.filter(
+      (value): value is string => typeof value === 'string',
+    )
+
+    if (
+      stringContexts.length > 0 &&
+      !stringContexts.some((value) => VALID_SCHEMA_CONTEXTS.has(value))
+    ) {
+      return [
+        {
+          severity: 'error',
+          message:
+            'Array @context is missing a schema.org context URL in its string entries.',
+        },
+      ]
+    }
+
+    return []
+  }
   if (typeof context === 'string') {
     if (!VALID_SCHEMA_CONTEXTS.has(context)) {
       return [
@@ -151,7 +173,8 @@ function validateContext(entity: JsonLdValue): Array<ValidationIssue> {
   return [
     {
       severity: 'error',
-      message: 'Invalid @context type. Expected a string schema.org URL.',
+      message:
+        'Invalid @context type. Expected a schema.org URL, object, array, or null.',
     },
   ]
 }
@@ -202,20 +225,6 @@ function validateEntityByType(
     })
   }
 
-  const allowedSet = new Set([
-    ...rules.required,
-    ...rules.recommended,
-    ...rules.optional,
-    ...RESERVED_KEYS,
-  ])
-  const unknownKeys = Object.keys(entity).filter((key) => !allowedSet.has(key))
-  if (unknownKeys.length > 0) {
-    issues.push({
-      severity: 'warning',
-      message: `Possible invalid attributes for ${typeName}: ${unknownKeys.join(', ')}`,
-    })
-  }
-
   return issues
 }
 
@@ -455,20 +464,7 @@ function sumMissingSchemaFieldCounts(entries: Array<JsonLdEntry>): {
  * small penalty so optional-field gaps match how the SEO overview weights them.
  */
 function getJsonLdScore(entries: Array<JsonLdEntry>): number {
-  let errors = 0
-  let warnings = 0
-  let infos = 0
-
-  for (const entry of entries) {
-    for (const issue of entry.issues) {
-      if (issue.severity === 'error') errors += 1
-      else if (issue.severity === 'warning') warnings += 1
-      else infos += 1
-    }
-  }
-
-  const penalty = Math.min(100, errors * 20 + warnings * 10 + infos * 2)
-  return Math.max(0, 100 - penalty)
+  return sectionHealthScore(entries.flatMap((entry) => entry.issues))
 }
 
 function JsonLdEntityPreviewCard(props: { entity: JsonLdValue }) {

packages/devtools-seo/src/seo-tab.tsx

@@ -17,44 +17,60 @@ export const SeoTab = () => {
 
   return (
     <MainPanel withPadding>
-      <nav class={styles().seoSubNav} aria-label="SEO sections">
+      <nav
+        class={styles().seoSubNav}
+        aria-label="SEO sections"
+        role="tablist"
+      >
         <button
           type="button"
+          role="tab"
+          aria-selected={activeView() === 'overview'}
           class={`${styles().seoSubNavLabel} ${activeView() === 'overview' ? styles().seoSubNavLabelActive : ''}`}
           onClick={() => setActiveView('overview')}
         >
           SEO Overview
         </button>
         <button
           type="button"
+          role="tab"
+          aria-selected={activeView() === 'heading-structure'}
           class={`${styles().seoSubNavLabel} ${activeView() === 'heading-structure' ? styles().seoSubNavLabelActive : ''}`}
           onClick={() => setActiveView('heading-structure')}
         >
           Heading Structure
         </button>
         <button
           type="button"
+          role="tab"
+          aria-selected={activeView() === 'links-preview'}
           class={`${styles().seoSubNavLabel} ${activeView() === 'links-preview' ? styles().seoSubNavLabelActive : ''}`}
           onClick={() => setActiveView('links-preview')}
         >
           Links Preview
         </button>
         <button
           type="button"
+          role="tab"
+          aria-selected={activeView() === 'social-previews'}
           class={`${styles().seoSubNavLabel} ${activeView() === 'social-previews' ? styles().seoSubNavLabelActive : ''}`}
           onClick={() => setActiveView('social-previews')}
         >
           Social Previews
         </button>
         <button
           type="button"
+          role="tab"
+          aria-selected={activeView() === 'serp-preview'}
           class={`${styles().seoSubNavLabel} ${activeView() === 'serp-preview' ? styles().seoSubNavLabelActive : ''}`}
           onClick={() => setActiveView('serp-preview')}
         >
           SERP Preview
         </button>
         <button
           type="button"
+          role="tab"
+          aria-selected={activeView() === 'json-ld-preview'}
           class={`${styles().seoSubNavLabel} ${activeView() === 'json-ld-preview' ? styles().seoSubNavLabelActive : ''}`}
           onClick={() => setActiveView('json-ld-preview')}
         >

packages/devtools-seo/src/serp-preview.tsx

@@ -1,6 +1,7 @@
 import { Section, SectionDescription } from '@tanstack/devtools-ui'
 import { For, createMemo, createSignal } from 'solid-js'
 import { useHeadChanges } from './hooks/use-head-changes'
+import { useLocationChanges } from './hooks/use-location-changes'
 import { tokens } from './tokens'
 import { useSeoStyles } from './use-seo-styles'
 import type { SeoIssue, SeoSectionSummary } from './seo-section-summary'
@@ -529,6 +530,10 @@ export function SerpPreviewSection() {
     setSerp(getSerpFromHead())
   })
 
+  useLocationChanges(() => {
+    setSerp(getSerpFromHead())
+  })
+
   const serpPreviewState = createMemo(() => {
     return getSerpPreviewState(serp())
   })