sanity-plugin-seofields 1.0.10 → 1.2.0

package/README.md

@@ -20,6 +20,7 @@ A comprehensive Sanity Studio v3 plugin to manage SEO fields like meta titles, d
 - 📊 **Custom Attributes**: Flexible meta attribute system
 - ✅ **Validation**: Built-in character limits and best practices
 - 🎛️ **Field Visibility**: Hide sitewide fields on specific content types
+- 📊 **SEO Health Dashboard**: Studio-wide overview of SEO completeness with scores, issue highlights, and direct document links
 
 ## 📦 Installation
 
@@ -441,6 +442,95 @@ defineField({
 })
 ```
 
+## 📊 SEO Health Dashboard
+
+The plugin includes a built-in **SEO Health Dashboard** tool accessible directly from Sanity Studio. It scans all documents that contain an `seo` field and gives you an at-a-glance picture of your site's SEO completeness.
+
+### 🔑 License Key Required
+
+The SEO Health Dashboard requires a valid license key to use. **Good news**: it's completely free during the current period (2–3 months). When we transition to a paid model, your existing key will remain valid for a one-time $10 fee.
+
+[Get your free license key →](https://sanity-plugin-seofields.thehardik.in/get-license)
+
+### Configuration
+
+```typescript
+// Minimal — just add your license key
+seofields({
+  healthDashboard: {
+    licenseKey: 'YOUR_LICENSE_KEY',
+  },
+})
+
+// Full options — all nested under healthDashboard
+seofields({
+  healthDashboard: {
+    // Required
+    licenseKey: 'YOUR_LICENSE_KEY',
+
+    // Studio nav tab
+    tool: {
+      title: 'SEO Audit', // tab label in Studio sidebar (default: 'SEO Health')
+      name: 'seo-health-dashboard', // internal tool slug
+    },
+
+    // Dashboard page content
+    content: {
+      icon: '🔍', // emoji before the page heading
+      title: 'SEO Audit', // page heading (default: tool.title)
+      description: 'Track SEO quality across all published content.',
+    },
+
+    // Table columns
+    display: {
+      typeColumn: true, // show document type column (default: true)
+      documentId: false, // show document _id (default: true)
+    },
+
+    // Document query
+    query: {
+      types: ['post', 'page'], // limit to specific document types
+      requireSeo: true, // only include docs with seo != null (default: true)
+      // groq: '*[seo != null] { _id, _type, title, seo, _updatedAt }',
+      // ^ custom GROQ takes precedence over types + requireSeo
+    },
+
+    apiVersion: '2023-01-01', // Sanity API version (default: '2023-01-01')
+  },
+})
+
+// Or disable the dashboard entirely
+seofields({
+  healthDashboard: false,
+})
+```
+
+### What it shows
+
+| Feature                  | Details                                                                          |
+| ------------------------ | -------------------------------------------------------------------------------- |
+| **Summary stats**        | Total documents, average score, and count per health tier                        |
+| **Per-document score**   | 0–95 score based on which SEO fields are filled in                               |
+| **Color-coded badges**   | 🟢 Excellent (≥ 80) · 🟡 Good (≥ 60) · 🟠 Fair (≥ 40) · 🔴 Poor / Missing (< 40) |
+| **Inline issues**        | Top 2 issues per document shown inline; overflow count displayed                 |
+| **Direct document link** | Click the document title to open it in the desk (new tab)                        |
+| **Search & filter**      | Filter by health status, sort by score or title, and full-text search            |
+
+### Scoring breakdown
+
+| Field               | Max Points |
+| ------------------- | ---------- |
+| Meta Title          | 25         |
+| Meta Description    | 20         |
+| OG Title            | 15         |
+| OG Description      | 10         |
+| Twitter Title       | 10         |
+| Twitter Description | 10         |
+| Robots / No-Index   | 5          |
+| **Total**           | **95**     |
+
+> **Scoring logic:** each field earns its full points when a non-empty value is present, zero when missing. `query.groq` lets you control exactly which documents are included in the audit.
+
 ## 🌐 Frontend Integration
 
 ### Next.js Example

package/dist/index.d.mts

@@ -1,12 +1,26 @@
+import {JSX} from 'react'
 import {ObjectDefinition} from 'sanity'
 import {Plugin as Plugin_2} from 'sanity'
 import {PreviewConfig} from 'sanity'
+import {default as React_2} from 'react'
 import {SchemaTypeDefinition} from 'sanity'
 
 export declare type AllFieldKeys = SeoFieldKeys | openGraphFieldKeys | twitterFieldKeys
 
 export declare function allSchemas(config?: SeoFieldsPluginConfig): SchemaTypeDefinition[]
 
+export declare interface DocumentWithSeoHealth {
+  _id: string
+  _type: string
+  title?: string
+  slug?: {
+    current: string
+  }
+  seo?: SeoFields
+  _updatedAt?: string
+  health: SeoHealthMetrics
+}
+
 export declare interface FieldVisibilityConfig {
   hiddenFields?: ValidHiddenFieldKeys[]
 }
@@ -46,6 +60,17 @@ export declare type openGraphFieldKeys =
 
 export declare function openGraphSchema(config?: SeoFieldsPluginConfig): SchemaTypeDefinition
 
+declare interface OpenGraphSettings {
+  _type: 'openGraph'
+  title?: string
+  description?: string
+  siteName?: string
+  type?: 'website' | 'article' | 'profile' | 'book' | 'music' | 'video' | 'product'
+  imageType?: 'upload' | 'url'
+  image?: SanityImageWithAlt
+  imageUrl?: string
+}
+
 export declare const robotsSchema: {
   type: 'object'
   name: 'robots'
@@ -53,6 +78,36 @@ export declare const robotsSchema: {
     preview?: PreviewConfig<Record<string, string>, Record<never, any>> | undefined
   }
 
+declare interface RobotsSettings {
+  noIndex?: boolean
+  noFollow?: boolean
+}
+
+declare interface SanityImage {
+  _type: 'image'
+  asset: {
+    _ref: string
+    _type: 'reference'
+  }
+  hotspot?: {
+    x: number
+    y: number
+    height: number
+    width: number
+  }
+  crop?: {
+    top: number
+    bottom: number
+    left: number
+    right: number
+  }
+  alt?: string
+}
+
+declare interface SanityImageWithAlt extends SanityImage {
+  alt: string
+}
+
 export declare interface SeoFieldConfig {
   title?: string
   description?: string
@@ -67,6 +122,19 @@ export declare type SeoFieldKeys =
   | 'metaAttributes'
   | 'robots'
 
+declare interface SeoFields {
+  _type: 'seoFields'
+  robots?: RobotsSettings
+  preview?: string
+  title?: string
+  description?: string
+  metaImage?: SanityImage
+  keywords?: string[]
+  canonicalUrl?: string
+  openGraph?: OpenGraphSettings
+  twitter?: TwitterCardSettings
+}
+
 declare const seofields: Plugin_2<void | SeoFieldsPluginConfig>
 export default seofields
 
@@ -113,10 +181,265 @@ export declare interface SeoFieldsPluginConfig {
    * Defaults to 'https://www.example.com' if not provided.
    */
   baseUrl?: string
+  /**
+   * Enable or configure the SEO Health Dashboard tool.
+   * If set to `true`, the dashboard is enabled with all defaults.
+   * If set to an object, you can customise the tool and dashboard settings.
+   * Defaults to `true`.
+   * Example:
+   * ```
+   * healthDashboard: {
+   *   toolTitle: 'SEO Overview',  // Studio nav tab label
+   *   content: {
+   *     icon: '🔍',               // Emoji icon shown before the page heading
+   *     title: 'My SEO Dashboard',// Page heading inside the tool (no emoji)
+   *     description: 'Track SEO across all documents', // Subtitle under the heading
+   *   },
+   *   display: {
+   *     typeColumn: false,        // Hide the document type column (default: true)
+   *     documentId: false,        // Hide the document ID under titles (default: true)
+   *   },
+   *   query: {
+   *     // Option 1 – filter by specific document types
+   *     types: ['post', 'page'],
+   *     // Option 2 – provide a full custom GROQ query (takes precedence over `types`)
+   *     // Must return documents with at least: _id, _type, title, seo, _updatedAt
+   *     groq: `*[seo != null && defined(slug.current)]{ _id, _type, title, slug, seo, _updatedAt }`,
+   *   },
+   * }
+   * ```
+   */
+  healthDashboard?:
+    | boolean
+    | {
+        tool?: {
+          title?: string
+          name?: string
+        }
+        toolTitle?: string
+        content?: {
+          icon?: string
+          title?: string
+          description?: string
+          /** Text shown while the license key is being verified. Defaults to "Verifying license…" */
+          loadingLicense?: string
+          /** Text shown while documents are being fetched. Defaults to "Loading documents…" */
+          loadingDocuments?: string
+          /** Text shown when the query returns zero results. Defaults to "No documents found" */
+          noDocuments?: string
+        }
+        display?: {
+          typeColumn?: boolean
+          documentId?: boolean
+        }
+        query?: {
+          /**
+           * Limit the dashboard to specific document types.
+           * Example: `['post', 'page']`
+           */
+          types?: string[]
+          /**
+           * When using `types`, also require the `seo` field to be non-null.
+           * Set to `false` to include documents of those types even if `seo` is missing.
+           * Defaults to `true`.
+           */
+          requireSeo?: boolean
+          /**
+           * Provide a fully custom GROQ query. Takes precedence over `types`.
+           * The query must return documents with at least: _id, _type, title, seo, _updatedAt
+           */
+          groq?: string
+        }
+        /**
+         * The Sanity API version to use for the client (e.g. '2023-01-01').
+         * Defaults to '2023-01-01'.
+         */
+        apiVersion?: string
+        /**
+         * License key for the SEO Health Dashboard pro feature.
+         * Obtain a license at https://sanity-plugin-seofields.thehardik.in
+         */
+        licenseKey?: string
+        /**
+         * Map raw `_type` values to human-readable display labels.
+         * Used in both the Type column and the Type filter dropdown.
+         * Any type without an entry falls back to the raw `_type` string.
+         *
+         * @example
+         * typeLabels: { productDrug: 'Products', singleCondition: 'Condition' }
+         */
+        typeLabels?: Record<string, string>
+        /**
+         * Controls how the document type is rendered in the Type column.
+         * - `'badge'` (default) — coloured pill
+         * - `'text'` — plain text, useful for dense layouts
+         */
+        typeColumnMode?: 'badge' | 'text'
+        /**
+         * The document field to use as the display title in the dashboard.
+         *
+         * - `string` — use this field for every document type (e.g. `'name'`)
+         * - `Record<string, string>` — per-type mapping; unmapped types fall back to `title`
+         *
+         * @example
+         * titleField: 'name'
+         *
+         * @example
+         * titleField: { post: 'title', product: 'name', category: 'label' }
+         */
+        titleField?: string | Record<string, string>
+        /**
+         * Callback function to render a custom badge next to the document title.
+         * Receives the full document and should return badge data or undefined.
+         *
+         * @example
+         * docBadge: (doc) => {
+         *   if (doc.services === 'NHS')
+         *     return { label: 'NHS', bgColor: '#e0f2fe', textColor: '#0369a1' }
+         *   if (doc.services === 'Private')
+         *     return { label: 'Private', bgColor: '#fef3c7', textColor: '#92400e' }
+         * }
+         */
+        docBadge?: (doc: DocumentWithSeoHealth & Record<string, unknown>) =>
+          | {
+              label: string
+              bgColor?: string
+              textColor?: string
+              fontSize?: string
+            }
+          | undefined
+      }
 }
 
 export declare function seoFieldsSchema(config?: SeoFieldsPluginConfig): SchemaTypeDefinition
 
+export declare const SeoHealthDashboard: React_2.FC<SeoHealthDashboardProps>
+
+declare interface SeoHealthDashboardProps {
+  icon?: string
+  title?: string
+  description?: string
+  showTypeColumn?: boolean
+  showDocumentId?: boolean
+  /**
+   * Limit the dashboard to specific document type names.
+   * If both queryTypes and customQuery are provided, customQuery takes precedence.
+   */
+  queryTypes?: string[]
+  /**
+   * When using `queryTypes`, also filter by `seo != null`.
+   * Set to `false` to include documents of those types even without an seo field.
+   * Defaults to `true`.
+   */
+  queryRequireSeo?: boolean
+  /**
+   * A fully custom GROQ query used to fetch documents.
+   * Must return objects with at least: _id, _type, title, seo, _updatedAt
+   * Takes precedence over queryTypes.
+   */
+  customQuery?: string
+  /**
+   * The Sanity API version to use for the client (e.g. '2023-01-01').
+   * Defaults to '2023-01-01'.
+   */
+  apiVersion?: string
+  /**
+   * License key for the SEO Health Dashboard.
+   * Obtain a key at https://sanity-plugin-seofields.thehardik.in
+   */
+  licenseKey?: string
+  /**
+   * Map raw `_type` values to human-readable display labels used in the
+   * Type column and the Type filter dropdown.
+   * Any type without an entry falls back to the raw `_type` string.
+   *
+   * @example
+   * typeLabels={{ productDrug: 'Products', singleCondition: 'Condition' }}
+   */
+  typeLabels?: Record<string, string>
+  /**
+   * Controls how the type is rendered in the Type column.
+   * - `'badge'` (default) — coloured pill, consistent with score badges
+   * - `'text'` — plain text, useful for dense layouts
+   */
+  typeColumnMode?: 'badge' | 'text'
+  /**
+   * The document field to use as the display title.
+   *
+   * - `string` — use this field for every document type (e.g. `'name'`)
+   * - `Record<string, string>` — per-type mapping; unmapped types fall back to `title`
+   *
+   * @example
+   * // Same field for all types
+   * titleField: 'name'
+   *
+   * @example
+   * // Different field per type
+   * titleField: { post: 'title', product: 'name', category: 'label' }
+   */
+  titleField?: string | Record<string, string>
+  /**
+   * Callback function to render a custom badge next to the document title.
+   * Receives the full document and should return badge data or undefined.
+   *
+   * @example
+   * docBadge: (doc) => {
+   *   if (doc.services === 'NHS')
+   *     return { label: 'NHS', bgColor: '#e0f2fe', textColor: '#0369a1' }
+   *   if (doc.services === 'Private')
+   *     return { label: 'Private', bgColor: '#fef3c7', textColor: '#92400e' }
+   * }
+   */
+  docBadge?: (doc: DocumentWithSeoHealth & Record<string, unknown>) =>
+    | {
+        label: string
+        bgColor?: string
+        textColor?: string
+        fontSize?: string
+      }
+    | undefined
+  /**
+   * Custom text shown while the license key is being verified.
+   * Defaults to `"Verifying license…"`.
+   */
+  loadingLicense?: React_2.ReactNode
+  /**
+   * Custom text shown while documents are being fetched.
+   * Defaults to `"Loading documents…"`.
+   */
+  loadingDocuments?: React_2.ReactNode
+  /**
+   * Custom text shown when the query returns zero results.
+   * Defaults to `"No documents found"`.
+   */
+  noDocuments?: React_2.ReactNode
+}
+
+export declare interface SeoHealthMetrics {
+  score: number
+  status: SeoHealthStatus
+  issues: string[]
+}
+
+export declare type SeoHealthStatus = 'excellent' | 'good' | 'fair' | 'poor' | 'missing'
+
+/**
+ * Sanity Tool component for the SEO Health Dashboard
+ * This component wraps the SeoHealthDashboard for use as a custom tool in Sanity Studio
+ */
+export declare const SeoHealthTool: (props: SeoHealthDashboardProps) => JSX.Element
+
+declare interface TwitterCardSettings {
+  _type: 'twitter'
+  card?: 'summary' | 'summary_large_image' | 'app' | 'player'
+  site?: string
+  title?: string
+  description?: string
+  imageType?: 'upload' | 'url'
+  image?: SanityImageWithAlt
+  imageUrl?: string
+}
+
 export declare type twitterFieldKeys =
   | 'twitterCard'
   | 'twitterSite'