@sanity/hierarchical-document-list 1.1.0 → 2.0.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Sanity.io
+Copyright (c) 2025 Sanity.io
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,5 +1,7 @@
 # sanity-plugin-hierarchical-document-list
 
+> This is a **Sanity Studio v3** plugin.
+
 Plugin for visually organizing documents as hierarchies in the [Sanity studio](https://www.sanity.io/docs/sanity-studio). Applications include:
 
 - Tables of content - such as a book's sections and chapters
@@ -8,53 +10,100 @@ Plugin for visually organizing documents as hierarchies in the [Sanity studio](h
 
 ![Screenshot of the plugin](/screenshot-1.jpg)
 
-⚠️ **Compatibility:** This plugin requires Sanity Studio [version 2.25.0](https://github.com/sanity-io/sanity/releases/tag/v2.25.0) or higher.
+⚠️ **Compatibility:** This plugin requires Sanity Studio [version 3.3.0](https://github.com/sanity-io/sanity/releases/tag/v3.3.0) or higher.
 
 If you're looking for a way to order documents on a flat list, refer to [@sanity/orderable-document-list](https://github.com/sanity-io/orderable-document-list).
 
-## Getting started
+
+## Installation
+
 
 ```bash
 # From the root of your sanity project
-sanity install @sanity/hierarchical-document-list
+npm i @sanity/hierarchical-document-list
 ```
 
-Once you've installed the plugin the next step is to add one or more hierarchy documents to your Structure Builder.
+## Usage
 
-💡 _To learn about custom desk structures, refer to the [Structure Builder docs](https://www.sanity.io/docs/overview-structure-builder)._
+### 1. Add the plugin and the default documentType to the sanity.config.ts
 
 ```js
-// deskStructure.js
-import S from '@sanity/desk-tool/structure-builder'
-import {createDeskHierarchy} from '@sanity/hierarchical-document-list'
-
-export default () => {
-  return S.list()
-    .title('Content')
-    .items([
-      ...S.documentTypeListItems(), // or whatever other structure you have
-      createDeskHierarchy({
-        title: 'Main table of contents',
-
-        // The hierarchy will be stored in this document ID 👇
-        documentId: 'main-table-of-contents',
-
-        // Document types editors should be able to include in the hierarchy
-        referenceTo: ['site.page', 'site.post', 'docs.article', 'social.youtubeVideo'],
-
-        // ❓ Optional: provide filters and/or parameters for narrowing which documents can be added
-        referenceOptions: {
-          filter: 'status in $acceptedStatuses',
-          filterParams: {
-            acceptedStatuses: ['published', 'approved']
-          }
-        },
+// sanity.config.js
+import {defineConfig} from 'sanity'
+import {hierarchicalDocumentList, hierarchyTree} from '@sanity/hierarchical-document-list'
+ 
+export default defineConfig({
+   // ...
+   plugins: [hierarchicalDocumentList()],
+   schema: {
+    types: [
+      //...,
+      hierarchyTree
+    ]
+   }
 
-        // ❓ Optional: limit the depth of your hierarachies
-        maxDept: 3
-      })
-    ])
-}
+})
+```
+
+### 2. Add one or more hierarchy documents to your Structure Builder.
+
+💡 _To learn about custom desk structures, refer to the [Structure Builder docs](https://www.sanity.io/docs/overview-structure-builder)._
+
+```ts
+// sanity.config.ts
+import {defineConfig} from 'sanity'
+import {deskTool} from 'sanity/desk'
+import {createDeskHierarchy, hierarchicalDocumentList, hierarchyTree} from '@sanity/hierarchical-document-list'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    deskTool({
+      // NOTE: I'n V3 you MUST pass S and Context along to createDeskHierarchy as props
+      structure: (S, context) =>  S.list()
+          .title('Content')
+          .items([
+            ...S.documentTypeListItems(), // or whatever other structure you have
+            createDeskHierarchy({
+              //prop drill S and context:
+              S,
+              context,
+
+              //configure plugin
+
+              title: 'Main table of contents',
+
+              // The hierarchy will be stored in this document ID 👇
+              documentId: 'main-table-of-contents',
+
+              // Document types editors should be able to include in the hierarchy
+              referenceTo: ['site.page', 'site.post', 'docs.article', 'social.youtubeVideo'],
+
+              // ❓ Optional: provide filters and/or parameters for narrowing which documents can be added
+              referenceOptions: {
+                filter: 'status in $acceptedStatuses',
+                filterParams: {
+                  acceptedStatuses: ['published', 'approved']
+                }
+              },
+
+              // ❓ Optional: limit the depth of your hierarachies
+              maxDepth: 3,
+
+              // ❓ Optional: subarray of referenceTo, when it should not be possible to create new types from all referenceTo types
+              creatableTypes: ['site.page']
+            })
+          ])
+    }),
+    hierarchicalDocumentList()
+  ],
+  schema: {
+    types: [
+      //...,
+      hierarchyTree
+    ]
+  }
+})
 ```
 
 ## How it works
@@ -296,34 +345,21 @@ We're considering adapting this input to support any type of nest-able data, not
 
 MIT-licensed. See LICENSE.
 
-## Developing
+## License
 
-If you want to test a dev-build of this plugin in the studio there is a bit of a workaround.
-npm/yarn link does not integrate correctly with StructureBuilder and schema part registration in
-the Studio.
+[MIT](LICENSE) © Sanity
 
-The most consistent workflow is:
+## Develop & test
 
-1.Install [yalc](https://github.com/wclr/yalc)
-2. Run `npm run build && yalc publish` in this repo
-3. In Sanity Studio:
-   1. Run `yalc link @sanity/hierarchical-document-list`
-   2. Run `yarn install` (installs the dependencies for the plugin)
-   3. Ensure `"@sanity/hierarchical-document-list"` is present in `sanity.json` plugins array.
-   4. Configure the plugin for structure as documented above
+This plugin uses [@sanity/plugin-kit](https://github.com/sanity-io/plugin-kit)
+with default configuration for build & watch scripts.
 
-Rerun steps 2. and 3.1 after making edits to the plugin (or automate it).
+See [Testing a plugin in Sanity Studio](https://github.com/sanity-io/plugin-kit#testing-a-plugin-in-sanity-studio)
+on how to run this plugin with hotreload in the studio.
 
-### Publishing
+### Release new version
 
-Test publish command safely: 
-* `yalc publish`
+Run ["CI & Release" workflow](https://github.com/sanity-io/hierarchical-document-list/actions/workflows/main.yml).
+Make sure to select the main branch and check "Release new version".
 
-To go live with a new version, run:
-* `npm run release`
-  * runs [standard-version](https://www.npmjs.com/package/standard-version) which will bump version according to semver, commit and tag
-  * feel free to inspect the results in package.json and git log before continuing
-* `npm publish`
-  * Will clean, lint and build before finally publishing to npm.
-* After publishing, you should push with tags: 
-  * `git push --follow-tags`
+Semantic release will only release on configured branches, so it is safe to run release on any branch.

package/dist/index.d.ts

@@ -0,0 +1,240 @@
+import {ArraySchemaType} from 'sanity'
+import type {ConfigContext} from 'sanity'
+import {DocumentDefinition} from 'sanity'
+import {Plugin as Plugin_2} from 'sanity'
+import {PreviewConfig} from 'sanity'
+import * as React_2 from 'react'
+import {StructureBuilder} from 'sanity/desk'
+
+export declare function createDeskHierarchy(props: TreeProps): any
+
+export declare function createHierarchicalSchemas(options: SchemaOptions): (
+  | {
+      name: string
+      title: string
+      type: string
+      fields: (
+        | {
+            name: string
+            type: string
+          }
+        | {
+            name: string
+            type: string
+            title: string
+            fields: (
+              | {
+                  name: string
+                  type: string
+                  weak?: undefined
+                  to?: undefined
+                  options?: undefined
+                }
+              | {
+                  name: string
+                  type: string
+                  weak: boolean
+                  to: {
+                    type: string
+                  }[]
+                  options:
+                    | {
+                        filter?: string | undefined
+                        filterParams?: Record<string, unknown> | undefined
+                      }
+                    | undefined
+                }
+            )[]
+          }
+      )[]
+    }
+  | {
+      name: string
+      title: string
+      type: string
+      of: (
+        | {
+            name: string
+            title: string
+            type: string
+            fields: (
+              | {
+                  name: string
+                  type: string
+                }
+              | {
+                  name: string
+                  type: string
+                  title: string
+                  fields: (
+                    | {
+                        name: string
+                        type: string
+                        weak?: undefined
+                        to?: undefined
+                        options?: undefined
+                      }
+                    | {
+                        name: string
+                        type: string
+                        weak: boolean
+                        to: {
+                          type: string
+                        }[]
+                        options:
+                          | {
+                              filter?: string | undefined
+                              filterParams?: Record<string, unknown> | undefined
+                            }
+                          | undefined
+                      }
+                  )[]
+                }
+            )[]
+          }
+        | {
+            type: string
+          }
+      )[]
+    }
+  | {
+      name: string | undefined
+      title: string
+      type: string
+      liveEdit: boolean
+      fields: (Omit<ArraySchemaType<unknown>, 'type' | 'of' | 'jsonType'> & {
+        type: string
+        inputComponent: React_2.FC<any>
+        of?: any[] | undefined
+      })[]
+      preview: {
+        select: {
+          id: string
+          tree: string
+        }
+        prepare({id, tree}: {id: string; tree: unknown[]}): Record<string, string>
+      }
+    }
+)[]
+
+export declare function flatDataToTree(data: StoredTreeItem[]): TreeItemWithChildren[]
+
+/**
+ * Usage in `sanity.config.ts` (or .js)
+ *
+ * ```ts
+ * import {defineConfig} from 'sanity'
+ * import {hierarchicalDocumentList} from '@sanity/hierarchical-document-list'
+ *
+ * export default defineConfig({
+ *   // ...
+ *   plugins: [hierarchicalDocumentList()],
+ * })
+ * ```
+ */
+export declare const hierarchicalDocumentList: Plugin_2<void>
+
+export declare const hierarchyTree: {
+  type: 'document'
+  name: 'hierarchy.tree'
+} & Omit<DocumentDefinition, 'preview'> & {
+    preview?: PreviewConfig<Record<string, string>, Record<never, any>> | undefined
+  }
+
+declare const INTERNAL_NODE_TYPE: string
+
+declare const INTERNAL_NODE_VALUE_TYPE: string
+
+declare interface SanityReference {
+  _type: 'reference'
+  _ref: string
+  _weak?: boolean
+}
+
+declare type SchemaOptions = Omit<TreeDeskStructureProps, 'documentId' | 'maxDepth'>
+
+/**
+ * Objects saved to tree documents in Sanity's Content Lake
+ */
+declare interface StoredTreeItem {
+  _key: string
+  _type: typeof INTERNAL_NODE_TYPE | string
+  value?: {
+    _type: typeof INTERNAL_NODE_VALUE_TYPE | string
+    reference?: SanityReference
+    docType?: string
+  }
+  /**
+   * _key of parent node
+   */
+  parent?: string | null
+}
+
+declare interface TreeDeskStructureProps extends TreeInputOptions {
+  /**
+   * _id of the document that will hold the tree data.
+   */
+  documentId: string
+  /**
+   * (Optional)
+   * Key for the field representing the hierarchical tree inside the document.
+   * `tree` by default.
+   */
+  fieldKeyInDocument?: string
+}
+
+declare interface TreeInputOptions {
+  /**
+   * What document types this hierarchy can refer to.
+   * Similar to the `to` property of the [reference field](https://www.sanity.io/docs/reference-type).
+   */
+  referenceTo: string[]
+  /**
+   * Used to provide fine-grained filtering for documents.
+   */
+  referenceOptions?: {
+    /**
+     * Static filter to apply to tree document queries.
+     */
+    filter?: string
+    /**
+     * Parameters / variables to pass to the GROQ query ran to fetch documents.
+     */
+    filterParams?: Record<string, unknown>
+  }
+  /**
+   * How deep should editors be allowed to nest items.
+   */
+  maxDepth?: number
+  /**
+   * Schema type for your hierarchical documents.
+   * Refer to documentation on how to provide these schemas in your studio.
+   *
+   * Defautlt: 'hierarchy.tree' - this schema is bundled with the plugin
+   */
+  documentType?: string
+}
+
+declare interface TreeItemWithChildren extends StoredTreeItem {
+  children?: TreeItemWithChildren[]
+}
+
+export declare interface TreeProps extends TreeDeskStructureProps {
+  /**
+   * Visible title above the tree.
+   * Also used as the label in the desk list item.
+   */
+  title: string
+  /**
+   * Optional icon for rendering the item in the desk structure.
+   */
+  icon?: any
+  context?: ConfigContext | any
+  S?: StructureBuilder | any
+  /**
+   * Restrict document types that can be created.
+   */
+  creatableTypes?: string[]
+}
+
+export {}