sanity-plugin-seofields 1.2.0 → 1.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sanity-plugin-seofields",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "A Sanity Studio plugin to manage SEO fields like meta titles, descriptions, and Open Graph tags for structured, search-optimized content.",
   "keywords": [
     "sanity",

package/src/components/SeoHealthDashboard.tsx

@@ -1,6 +1,7 @@
 import React, {useCallback, useEffect, useMemo, useState} from 'react'
 import {useClient} from 'sanity'
 import {useIntentLink} from 'sanity/router'
+import {usePaneRouter} from 'sanity/structure'
 import styled, {keyframes} from 'styled-components'
 
 import {DocumentWithSeoHealth, SeoHealthMetrics} from '../types'
@@ -24,6 +25,22 @@ const PageTitle = styled.h1`
   font-weight: 700;
   color: #111827;
   letter-spacing: -0.3px;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+`
+
+const PreviewBadge = styled.span`
+  display: inline-block;
+  background: #fef3c7;
+  color: #92400e;
+  font-size: 11px;
+  font-weight: 600;
+  padding: 4px 8px;
+  border-radius: 4px;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  margin-left: 8px;
 `
 
 const PageSubtitle = styled.p`
@@ -34,16 +51,9 @@ const PageSubtitle = styled.p`
 
 const StatsGrid = styled.div`
   display: grid;
-  grid-template-columns: repeat(6, 1fr);
+  grid-template-columns: repeat(auto-fit, minmax(130px, 1fr));
   gap: 14px;
   margin-bottom: 20px;
-
-  @media (max-width: 1100px) {
-    grid-template-columns: repeat(3, 1fr);
-  }
-  @media (max-width: 600px) {
-    grid-template-columns: repeat(2, 1fr);
-  }
 `
 
 const StatCard = styled.div<{$accent?: string}>`
@@ -202,6 +212,14 @@ const TitleWrapper = styled.div`
   align-items: center;
   gap: 4px;
   flex-wrap: wrap;
+  min-width: 0;
+`
+
+/* Constrains the title + doc-id block so text-overflow works inside flex */
+const TitleCell = styled.div`
+  min-width: 0;
+  overflow: hidden;
+  flex: 1;
 `
 
 const ColType = styled.div`
@@ -245,14 +263,14 @@ const DocId = styled.div`
   text-overflow: ellipsis;
 `
 
-const TypeBadge = styled.span`
+const TypeBadge = styled.span<{$bgColor?: string; $textColor?: string}>`
   display: inline-block;
   padding: 3px 8px;
   border-radius: 5px;
   font-size: 11px;
   font-weight: 500;
-  background: #ede9fe;
-  color: #5b21b6;
+  background: ${(p) => p.$bgColor || '#ede9fe'};
+  color: ${(p) => p.$textColor || '#5b21b6'};
 `
 
 const TypeText = styled.span`
@@ -465,6 +483,48 @@ const DocTitleAnchor: React.FC<{id: string; type: string; children: React.ReactN
   )
 }
 
+// Wrapper that applies DocTitleLink styles to the ChildLink <a> rendered by Sanity's pane router
+const PaneLinkWrapper = styled.span`
+  display: block;
+  min-width: 0;
+  overflow: hidden;
+
+  a {
+    font-size: 13px;
+    font-weight: 600;
+    color: #4f46e5;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    text-decoration: none;
+    display: block;
+    transition: color 0.15s;
+
+    &:hover {
+      color: #4338ca;
+      text-decoration: underline;
+    }
+  }
+`
+
+// Sub-component for desk-structure split-pane navigation.
+// Uses ChildLink from usePaneRouter to open the document editor to the right
+// while keeping the SEO Health pane visible on the left.
+const DocTitleAnchorPane: React.FC<{id: string; type: string; children: React.ReactNode}> = ({
+  id,
+  type,
+  children,
+}) => {
+  const {ChildLink} = usePaneRouter()
+  return (
+    <PaneLinkWrapper>
+      <ChildLink childId={id} childParameters={{type}}>
+        {children}
+      </ChildLink>
+    </PaneLinkWrapper>
+  )
+}
+
 // Sub-component to safely call docBadge outside a .map expression
 const DocBadgeRenderer: React.FC<{
   doc: DocumentWithSeoHealth & Record<string, unknown>
@@ -509,6 +569,47 @@ const EmptyState = styled.div`
   font-size: 13px;
 `
 
+/**
+ * Color palette for dynamic document type badges
+ * Colors are randomly assigned based on type hash for visual variety
+ * while maintaining consistency across sessions
+ */
+const TYPE_COLOR_PALETTE: Array<{bg: string; text: string}> = [
+  {bg: '#dbeafe', text: '#0c4a6e'}, // Blue
+  {bg: '#dcfce7', text: '#14532d'}, // Green
+  {bg: '#fce7f3', text: '#500724'}, // Pink
+  {bg: '#fed7aa', text: '#7c2d12'}, // Orange
+  {bg: '#e9d5ff', text: '#581c87'}, // Purple
+  {bg: '#f3e8ff', text: '#3f0f5c'}, // Deep Purple
+  {bg: '#ccfbf1', text: '#134e4a'}, // Teal
+  {bg: '#ddd6fe', text: '#3730a3'}, // Indigo
+  {bg: '#fca5a5', text: '#7f1d1d'}, // Red
+  {bg: '#a7f3d0', text: '#065f46'}, // Emerald
+  {bg: '#fbbf24', text: '#78350f'}, // Amber
+  {bg: '#c4b5fd', text: '#3b0764'}, // Violet
+  {bg: '#f0fdf4', text: '#15803d'}, // Light Green
+  {bg: '#fef2f2', text: '#991b1b'}, // Light Red
+  {bg: '#f5f3ff', text: '#5b21b6'}, // Light Purple
+  {bg: '#fffbeb', text: '#92400e'}, // Light Amber
+]
+
+/**
+ * Get dynamic color for a document type based on type name hash
+ * Same type always gets the same color, but assignment is not fixed
+ */
+const getTypeColor = (type: string): {bg: string; text: string} => {
+  // Generate consistent hash from type string using simple arithmetic
+  let hash = 0
+  for (let i = 0; i < type.length; i += 1) {
+    const char = type.charCodeAt(i)
+    hash = Math.abs(hash * 31 + char)
+  }
+
+  // Use modulo to get index within palette range
+  const colorIndex = hash % TYPE_COLOR_PALETTE.length
+  return TYPE_COLOR_PALETTE[colorIndex]
+}
+
 const getStatusCategory = (score: number): SeoHealthMetrics['status'] => {
   if (score >= 80) return 'excellent'
   if (score >= 60) return 'good'
@@ -760,6 +861,167 @@ export interface SeoHealthDashboardProps {
    * Defaults to `"No documents found"`.
    */
   noDocuments?: React.ReactNode
+  /**
+   * Enable preview/demo mode to show dummy data.
+   * Useful for testing, documentation, or showcasing the dashboard.
+   * When enabled, displays realistic sample documents with various SEO scores.
+   * Defaults to `false`.
+   */
+  previewMode?: boolean
+  /**
+   * When `true`, clicking a document title opens the document editor as a split
+   * pane to the right, keeping the SEO Health pane visible on the left.
+   * This uses Sanity's pane router and requires the component to be rendered
+   * inside a desk-structure pane context (i.e. via `createSeoHealthPane`).
+   *
+   * When `false` (default), clicking navigates to the document via the standard
+   * intent-link system (full navigation).
+   *
+   * This is set to `true` automatically by `createSeoHealthPane`.
+   */
+  openInPane?: boolean
+}
+
+/**
+ * Generate dummy data for preview mode showing various SEO health scenarios
+ */
+const generateDummyData = (): DocumentWithSeoHealth[] => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const dummyDocs: any[] = [
+    {
+      _id: 'preview-post-1',
+      _type: 'post',
+      title: 'Getting Started with SEO Best Practices',
+      slug: {current: 'getting-started-seo'},
+      _updatedAt: new Date(Date.now() - 2 * 24 * 60 * 60 * 1000).toISOString(),
+      seo: {
+        title: 'Getting Started with SEO Best Practices | My Blog',
+        description:
+          'Learn the fundamentals of SEO optimization to improve your website visibility and search rankings.',
+        keywords: ['seo', 'best practices', 'optimization'],
+        metaImage: {_type: 'image', asset: {_ref: 'image-123', _type: 'reference'}},
+        openGraph: {
+          title: 'SEO Best Practices Guide',
+          description: 'Master SEO optimization',
+          image: {_type: 'image', asset: {_ref: 'image-123', _type: 'reference'}, alt: 'SEO Guide'},
+          type: 'article',
+        },
+        twitter: {
+          title: 'SEO Best Practices',
+          description: 'Learn SEO optimization',
+          image: {_type: 'image', asset: {_ref: 'image-123', _type: 'reference'}, alt: 'Guide'},
+          card: 'summary_large_image',
+        },
+      },
+    },
+    {
+      _id: 'preview-post-2',
+      _type: 'post',
+      title: 'Advanced Analytics Strategy',
+      slug: {current: 'advanced-analytics'},
+      _updatedAt: new Date(Date.now() - 5 * 24 * 60 * 60 * 1000).toISOString(),
+      seo: {
+        title: 'Advanced Analytics',
+        description: 'Strategy tips',
+        keywords: ['analytics', 'data'],
+        openGraph: {
+          title: 'Analytics Guide',
+        },
+      },
+    },
+    {
+      _id: 'preview-page-1',
+      _type: 'page',
+      title: 'About Us',
+      slug: {current: 'about'},
+      _updatedAt: new Date(Date.now() - 10 * 24 * 60 * 60 * 1000).toISOString(),
+      seo: {
+        title: 'About',
+        keywords: ['company', 'team'],
+        metaImage: {_type: 'image', asset: {_ref: 'image-456', _type: 'reference'}},
+      },
+    },
+    {
+      _id: 'preview-post-3',
+      _type: 'post',
+      title: 'Content Marketing Trends for 2024',
+      slug: {current: 'content-marketing-trends'},
+      _updatedAt: new Date(Date.now() - 1 * 24 * 60 * 60 * 1000).toISOString(),
+      seo: {
+        title: 'Content Marketing Trends 2024',
+        description:
+          'Discover the latest content marketing trends and strategies to engage your audience effectively.',
+        keywords: ['content marketing', 'trends', 'strategy', 'engagement'],
+        metaImage: {_type: 'image', asset: {_ref: 'image-789', _type: 'reference'}},
+        openGraph: {
+          title: 'Content Marketing Trends 2024',
+          description: 'Latest trends in content marketing',
+          image: {_type: 'image', asset: {_ref: 'image-789', _type: 'reference'}, alt: 'Trends'},
+          type: 'article',
+        },
+        twitter: {
+          title: 'Content Marketing Trends',
+          description: 'Discover the latest trends',
+          card: 'summary',
+        },
+      },
+    },
+    {
+      _id: 'preview-post-4',
+      _type: 'product',
+      title: 'Pro Plan',
+      slug: {current: 'pro-plan'},
+      _updatedAt: new Date(Date.now() - 15 * 24 * 60 * 60 * 1000).toISOString(),
+      seo: {
+        title: 'Pro',
+        keywords: ['pricing'],
+      },
+    },
+    {
+      _id: 'preview-page-2',
+      _type: 'page',
+      title: 'Contact',
+      slug: {current: 'contact'},
+      _updatedAt: new Date(Date.now() - 8 * 24 * 60 * 60 * 1000).toISOString(),
+      seo: {
+        openGraph: {
+          title: 'Get in Touch',
+        },
+      },
+    },
+    {
+      _id: 'preview-post-5',
+      _type: 'post',
+      title: 'Mobile Optimization Guide',
+      slug: {current: 'mobile-optimization'},
+      _updatedAt: new Date(Date.now() - 3 * 24 * 60 * 60 * 1000).toISOString(),
+      seo: {
+        title: 'Mobile Optimization Guide: Best Practices for Responsive Design',
+        description:
+          'Complete guide to mobile optimization including responsive design, performance tips, and user experience best practices for modern web development.',
+        keywords: ['mobile', 'optimization', 'responsive', 'performance'],
+        metaImage: {_type: 'image', asset: {_ref: 'image-mobile', _type: 'reference'}},
+        openGraph: {
+          title: 'Mobile Optimization Best Practices',
+          description: 'Master mobile web optimization',
+          image: {_type: 'image', asset: {_ref: 'image-mobile', _type: 'reference'}, alt: 'Mobile'},
+          type: 'article',
+        },
+        twitter: {
+          title: 'Mobile Optimization Tips',
+          description: 'Responsive design best practices',
+          image: {_type: 'image', asset: {_ref: 'image-mobile', _type: 'reference'}, alt: 'Mobile'},
+          card: 'summary_large_image',
+        },
+      },
+    },
+  ]
+
+  // Calculate health scores and return
+  return dummyDocs.map((doc) => ({
+    ...doc,
+    health: calculateHealthScore(doc),
+  }))
 }
 
 const SeoHealthDashboard: React.FC<SeoHealthDashboardProps> = ({
@@ -780,6 +1042,8 @@ const SeoHealthDashboard: React.FC<SeoHealthDashboardProps> = ({
   loadingLicense,
   loadingDocuments,
   noDocuments,
+  previewMode = false,
+  openInPane = false,
 }) => {
   const client = useClient({apiVersion})
   const [licenseStatus, setLicenseStatus] = useState<'loading' | 'valid' | 'invalid'>('loading')
@@ -800,6 +1064,12 @@ const SeoHealthDashboard: React.FC<SeoHealthDashboardProps> = ({
 
   const validateLicense = useCallback(
     async (forceRefresh = false) => {
+      // Preview mode bypasses license validation
+      if (previewMode) {
+        setLicenseStatus('valid')
+        return
+      }
+
       // No key provided
       if (!licenseKey) {
         setLicenseStatus('invalid')
@@ -854,13 +1124,13 @@ const SeoHealthDashboard: React.FC<SeoHealthDashboardProps> = ({
       }
     },
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [licenseKey],
+    [licenseKey, previewMode],
   )
 
   useEffect(() => {
     validateLicense()
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [licenseKey])
+  }, [licenseKey, previewMode])
 
   const handleMouseEnterIssues = (el: HTMLDivElement | null, issues: string[]) => {
     if (!el) return
@@ -881,6 +1151,12 @@ const SeoHealthDashboard: React.FC<SeoHealthDashboardProps> = ({
       try {
         setLoading(true)
 
+        // Use dummy data in preview mode
+        if (previewMode) {
+          setDocuments(generateDummyData())
+          return
+        }
+
         let groqQuery: string
         let params: Record<string, unknown> = {}
 
@@ -932,7 +1208,16 @@ const SeoHealthDashboard: React.FC<SeoHealthDashboardProps> = ({
 
     fetchDocuments()
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [client, customQuery, queryRequireSeo, JSON.stringify(queryTypes), JSON.stringify(titleField)])
+  }, [
+    client,
+    customQuery,
+    queryRequireSeo,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    JSON.stringify(queryTypes),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    JSON.stringify(titleField),
+    previewMode,
+  ])
 
   const uniqueDocumentTypes = useMemo(() => {
     const types = new Set(documents.map((doc) => doc._type))
@@ -1060,7 +1345,10 @@ export default defineConfig({
           {/* Header */}
           <PageHeader>
             <PageTitle>
-              {icon} {title}
+              <span>
+                {icon} {title}
+              </span>
+              {previewMode && <PreviewBadge>Preview Mode</PreviewBadge>}
             </PageTitle>
             <PageSubtitle>{description}</PageSubtitle>
           </PageHeader>
@@ -1171,12 +1459,18 @@ export default defineConfig({
                       <TableRow key={doc._id}>
                         <ColTitle>
                           <TitleWrapper>
-                            <div>
-                              <DocTitleAnchor id={doc._id} type={doc._type}>
-                                {doc.title || 'Untitled'}
-                              </DocTitleAnchor>
+                            <TitleCell>
+                              {openInPane ? (
+                                <DocTitleAnchorPane id={doc._id} type={doc._type}>
+                                  {doc.title || 'Untitled'}
+                                </DocTitleAnchorPane>
+                              ) : (
+                                <DocTitleAnchor id={doc._id} type={doc._type}>
+                                  {doc.title || 'Untitled'}
+                                </DocTitleAnchor>
+                              )}
                               {showDocumentId && <DocId>{doc._id}</DocId>}
-                            </div>
+                            </TitleCell>
                             {docBadge && (
                               <DocBadgeRenderer
                                 doc={doc as DocumentWithSeoHealth & Record<string, unknown>}
@@ -1190,7 +1484,14 @@ export default defineConfig({
                             {typeColumnMode === 'text' ? (
                               <TypeText>{resolveTypeLabel(doc._type, typeLabels)}</TypeText>
                             ) : (
-                              <TypeBadge>{resolveTypeLabel(doc._type, typeLabels)}</TypeBadge>
+                              (() => {
+                                const typeColor = getTypeColor(doc._type)
+                                return (
+                                  <TypeBadge $bgColor={typeColor.bg} $textColor={typeColor.text}>
+                                    {resolveTypeLabel(doc._type, typeLabels)}
+                                  </TypeBadge>
+                                )
+                              })()
                             )}
                           </ColType>
                         )}

package/src/components/SeoHealthPane.tsx

@@ -0,0 +1,81 @@
+import React from 'react'
+import type {ComponentBuilder, StructureBuilder} from 'sanity/structure'
+
+import SeoHealthDashboard, {SeoHealthDashboardProps} from './SeoHealthDashboard'
+
+/**
+ * Options accepted by `createSeoHealthPane`.
+ * All props from `SeoHealthDashboardProps` are supported.
+ *
+ * `licenseKey` is **required** — the dashboard will not render without it.
+ */
+export interface SeoHealthPaneOptions extends Omit<SeoHealthDashboardProps, 'customQuery'> {
+  /** Required license key (format: `SEOF-XXXX-XXXX-XXXX`). */
+  licenseKey: string
+  /**
+   * A fully custom GROQ query used to fetch documents for the dashboard.
+   * The query must return documents with at least: `_id`, `_type`, `title`, `seo`, `_updatedAt`.
+   *
+   * Takes precedence over `queryTypes` when both are provided.
+   *
+   * @example
+   * query: `*[_type in ["post","page"] && defined(seo)]{ _id, _type, title, slug, seo, _updatedAt }`
+   */
+  query?: string
+}
+
+// function isStructureBuilder(arg: unknown): arg is StructureBuilder {
+//   return (
+//     arg !== null &&
+//     typeof arg === 'object' &&
+//     typeof (arg as StructureBuilder).component === 'function' &&
+//     typeof (arg as StructureBuilder).document === 'function'
+//   )
+// }
+
+/**
+ * Creates a desk-structure pane for the SEO Health Dashboard.
+ *
+ * Returns a **`ComponentBuilder`** with a built-in `.child()` resolver so that
+ * clicking any document row opens the document editor as a split pane to the right.
+ *
+ * Use it **directly** as the `.child()` value — do **not** wrap it in `S.component()`.
+ *
+ * ```ts
+ * // sanity.config.ts
+ * structure: (S) =>
+ *   S.list().items([
+ *     S.listItem()
+ *       .title('SEO Health')
+ *       .child(
+ *         createSeoHealthPane(S, {
+ *           licenseKey: 'SEOF-XXXX-XXXX-XXXX',
+ *           query: `*[_type == "post" && defined(seo)]{ _id, _type, title, slug, seo, _updatedAt }`,
+ *         })
+ *       ),
+ *   ])
+ * ```
+ */
+export function createSeoHealthPane(
+  optionsOrS: StructureBuilder,
+  optionsWhenS: SeoHealthPaneOptions,
+): ComponentBuilder {
+  // ── Two-arg form: structure builder passed as first arg ──────────────────
+  const S = optionsOrS
+  const {query, openInPane = true, title: paneTitle, ...rest} = optionsWhenS ?? {}
+
+  const SeoHealthPane: React.FC = () => (
+    <SeoHealthDashboard customQuery={query} openInPane={openInPane} title={paneTitle} {...rest} />
+  )
+  SeoHealthPane.displayName = 'SeoHealthPane'
+
+  // Wire up the child resolver so ChildLink URLs resolve to the document editor
+  return (S.component(SeoHealthPane) as ComponentBuilder)
+    .title(paneTitle ?? 'SEO Health')
+    .child((docId: string, {params}: {params: Record<string, string | undefined>}) => {
+      const builder = S.document().documentId(docId)
+      return params?.type ? builder.schemaType(params.type) : builder
+    })
+}
+
+export default createSeoHealthPane

package/src/index.ts

@@ -19,6 +19,8 @@ export {default as twitterSchema} from './schemas/types/twitter'
 // Export dashboard components and types
 export {default as SeoHealthDashboard} from './components/SeoHealthDashboard'
 export {default as SeoHealthTool} from './components/SeoHealthTool'
+export {createSeoHealthPane} from './components/SeoHealthPane'
+export type {SeoHealthPaneOptions} from './components/SeoHealthPane'
 
 // Export types
 export type {DocumentWithSeoHealth, SeoHealthMetrics, SeoHealthStatus} from './types'

package/src/plugin.ts

@@ -214,6 +214,16 @@ export interface SeoFieldsPluginConfig {
         docBadge?: (
           doc: DocumentWithSeoHealth & Record<string, unknown>,
         ) => {label: string; bgColor?: string; textColor?: string; fontSize?: string} | undefined
+        /**
+         * Enable preview/demo mode to show dummy data.
+         * Useful for testing, documentation, or showcasing the dashboard.
+         * When enabled, displays realistic sample documents with various SEO scores.
+         * Defaults to `false`.
+         *
+         * @example
+         * previewMode: true
+         */
+        previewMode?: boolean
       }
 }
 
@@ -242,6 +252,7 @@ interface ResolvedDashboardConfig {
   loadingLicense: string | undefined
   loadingDocuments: string | undefined
   noDocuments: string | undefined
+  previewMode: boolean | undefined
 }
 
 const resolveDashboardConfig = (
@@ -269,6 +280,7 @@ const resolveDashboardConfig = (
     loadingLicense: cfg?.content?.loadingLicense,
     loadingDocuments: cfg?.content?.loadingDocuments,
     noDocuments: cfg?.content?.noDocuments,
+    previewMode: cfg?.previewMode,
   }
 }
 
@@ -295,6 +307,7 @@ const seofields = definePlugin<SeoFieldsPluginConfig | void>((config = {}) => {
       loadingLicense: dash.loadingLicense,
       loadingDocuments: dash.loadingDocuments,
       noDocuments: dash.noDocuments,
+      previewMode: dash.previewMode,
     })
 
   return {