sanity-plugin-seofields 1.2.0 → 1.2.2

package/README.md

@@ -21,6 +21,7 @@ A comprehensive Sanity Studio v3 plugin to manage SEO fields like meta titles, d
 - ✅ **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
+- 🗂️ **Desk Structure Pane**: Embed the dashboard inside the Structure tool with `createSeoHealthPane` — supports split-pane document editing
 
 ## 📦 Installation
 
@@ -531,6 +532,65 @@ seofields({
 
 > **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.
 
+## 🗂️ Desk Structure Pane
+
+Embed the SEO Health Dashboard **directly inside the Structure tool** as a pane with split-pane document editing — clicking any row opens the document editor to the right.
+
+### Import
+
+```typescript
+import {createSeoHealthPane} from 'sanity-plugin-seofields'
+```
+
+### Usage
+
+`createSeoHealthPane(S, options)` requires both arguments: Sanity's structure builder `S` and an options object with a required `licenseKey`. It returns a **`ComponentBuilder`** — use it **directly** as the `.child()` value.
+
+> ⚠️ **Do NOT wrap in `S.component()`.** The function already calls `S.component()` internally. Wrapping it again causes: _"component is required for component structure item"_.
+
+```typescript
+// sanity.config.ts
+import {defineConfig} from 'sanity'
+import {structureTool} from 'sanity/structure'
+import seofields, {createSeoHealthPane} from 'sanity-plugin-seofields'
+
+export default defineConfig({
+  plugins: [
+    seofields({healthDashboard: false}), // optional: hide the top-level tool tab
+    structureTool({
+      structure: (S) =>
+        S.list()
+          .title('Content')
+          .items([
+            S.documentTypeListItem('post').title('Posts'),
+            S.divider(),
+            S.listItem()
+              .title('SEO Health')
+              .child(
+                createSeoHealthPane(S, {
+                  licenseKey: 'SEOF-XXXX-XXXX-XXXX',
+                  query: `*[_type == "post" && defined(seo)]{
+                    _id, _type, title, slug, seo, _updatedAt
+                  }`,
+                  title: 'Posts SEO Health',
+                }),
+              ),
+          ]),
+    }),
+  ],
+})
+```
+
+### `createSeoHealthPane` options
+
+| Option       | Type      | Default        | Description                                                           |
+| ------------ | --------- | -------------- | --------------------------------------------------------------------- |
+| `licenseKey` | `string`  | **required**   | License key (format `SEOF-XXXX-XXXX-XXXX`).                           |
+| `query`      | `string`  | —              | GROQ query. Must return `_id`, `_type`, `title`, `seo`, `_updatedAt`. |
+| `title`      | `string`  | `'SEO Health'` | Pane title shown in breadcrumb                                        |
+| `openInPane` | `boolean` | `true`         | Enable row links that open the document editor as a pane to the right. |
+| `...rest`    | —         | —              | All other `SeoHealthDashboardProps`                                   |
+
 ## 🌐 Frontend Integration
 
 ### Next.js Example

package/dist/index.d.mts

@@ -1,14 +1,44 @@
+import type {ComponentBuilder} from 'sanity/structure'
 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'
+import type {StructureBuilder} from 'sanity/structure'
 
 export declare type AllFieldKeys = SeoFieldKeys | openGraphFieldKeys | twitterFieldKeys
 
 export declare function allSchemas(config?: SeoFieldsPluginConfig): SchemaTypeDefinition[]
 
+/**
+ * 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 declare function createSeoHealthPane(
+  optionsOrS: StructureBuilder,
+  optionsWhenS: SeoHealthPaneOptions,
+): ComponentBuilder
+
 export declare interface DocumentWithSeoHealth {
   _id: string
   _type: string
@@ -308,6 +338,16 @@ export declare interface SeoFieldsPluginConfig {
               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
       }
 }
 
@@ -413,6 +453,25 @@ declare interface SeoHealthDashboardProps {
    * Defaults to `"No documents found"`.
    */
   noDocuments?: React_2.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
 }
 
 export declare interface SeoHealthMetrics {
@@ -421,6 +480,27 @@ export declare interface SeoHealthMetrics {
   issues: string[]
 }
 
+/**
+ * Options accepted by `createSeoHealthPane`.
+ * All props from `SeoHealthDashboardProps` are supported.
+ *
+ * `licenseKey` is **required** — the dashboard will not render without it.
+ */
+export declare 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
+}
+
 export declare type SeoHealthStatus = 'excellent' | 'good' | 'fair' | 'poor' | 'missing'
 
 /**

package/dist/index.d.ts

@@ -1,14 +1,44 @@
+import type {ComponentBuilder} from 'sanity/structure'
 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'
+import type {StructureBuilder} from 'sanity/structure'
 
 export declare type AllFieldKeys = SeoFieldKeys | openGraphFieldKeys | twitterFieldKeys
 
 export declare function allSchemas(config?: SeoFieldsPluginConfig): SchemaTypeDefinition[]
 
+/**
+ * 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 declare function createSeoHealthPane(
+  optionsOrS: StructureBuilder,
+  optionsWhenS: SeoHealthPaneOptions,
+): ComponentBuilder
+
 export declare interface DocumentWithSeoHealth {
   _id: string
   _type: string
@@ -308,6 +338,16 @@ export declare interface SeoFieldsPluginConfig {
               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
       }
 }
 
@@ -413,6 +453,25 @@ declare interface SeoHealthDashboardProps {
    * Defaults to `"No documents found"`.
    */
   noDocuments?: React_2.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
 }
 
 export declare interface SeoHealthMetrics {
@@ -421,6 +480,27 @@ export declare interface SeoHealthMetrics {
   issues: string[]
 }
 
+/**
+ * Options accepted by `createSeoHealthPane`.
+ * All props from `SeoHealthDashboardProps` are supported.
+ *
+ * `licenseKey` is **required** — the dashboard will not render without it.
+ */
+export declare 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
+}
+
 export declare type SeoHealthStatus = 'excellent' | 'good' | 'fair' | 'poor' | 'missing'
 
 /**