sanity-plugin-taxonomy-manager 3.1.5 → 3.2.1

package/README.md

@@ -1,6 +1,5 @@
 # Sanity Taxonomy Manager
 
-
 ![NPM Version](https://img.shields.io/npm/v/sanity-plugin-taxonomy-manager?style=flat-square)
 ![License](https://img.shields.io/npm/l/sanity-plugin-taxonomy-manager?style=flat-square)
 
@@ -11,19 +10,20 @@
 The Taxonomy Manager document schema is based on the [World Wide Web Consortium](https://www.w3.org/) (W3C) [Simple Knowledge Organization Scheme](https://www.w3.org/TR/skos-reference/) (SKOS) recommendation. Concept and concept scheme editor tools include standard SKOS properties, hints for creating consistent concepts and vocabularies, and validation functions for preventing consistency errors. -->
 
 | ![taxonomy manager plugin screenshot](docs/_images/taxonomyManager.png) |
-| --- |
+| ----------------------------------------------------------------------- |
 
 ## Documentation
 
 For full documentation, visit [sanitytaxonomymanager.com](https://sanitytaxonomymanager.com).
 
 ## Features
+
 <!-- make this more concise -->
+
 - Adds two document types to your Sanity schema which are used to generate [SKOS](https://www.w3.org/TR/skos-primer/) compliant concepts and taxonomies: `skosConcept` and `skosConceptScheme`
 - Includes reference filter helpers to allow you to easily include a specific taxonomy, or particular branch of a taxonomy in your Sanity documents
 - Encourages taxonomy and thesaurus design best practices by enforcing [disjunction between Broader and Related relationships](https://www.w3.org/TR/skos-reference/#L2422) and [disjunction between Preferred and Alternate/Hidden labels](https://www.w3.org/TR/skos-reference/#L1567)
-- Standards compliant architecture means that taxonomy terms and structures can be migrated to standards compliant standalone tools when you need higher level taxonomy and knowledge graph support. 
-
+- Standards compliant architecture means that taxonomy terms and structures can be migrated to standards compliant standalone tools when you need higher level taxonomy and knowledge graph support.
 
 ## Installation
 
@@ -62,6 +62,16 @@ export default defineConfig({
     taxonomyManager({
       // Optional: Set a Base URI to use for new concepts & concept schemes
       baseUri: 'https://example.com/',
+      // Optional: Use `customConceptFields` and `customSchemeFields` keys to add custom fields to Concept or Concept Scheme document types
+      customConceptFields: [
+        {
+          name: 'sameAs',
+          title: 'Same As',
+          type: 'url',
+          description:
+            'Specify a fully qualified IRI that identifies the same concept in another vocabulary',
+        },
+      ],
     }),
   ],
   schema: {
@@ -96,9 +106,7 @@ export default defineConfig({
             ),
           ]),
     }),
-    taxonomyManager({
-      baseUri: 'https://example.com/',
-    }),
+    taxonomyManager(),
   ],
   schema: {
     types: schemaTypes,
@@ -107,7 +115,65 @@ export default defineConfig({
 ```
 
 ## Contributing
-Community collaboration is highly encouraged. To make sure your contributions are aligned with project goals and principles, please read the [contributing docs](https://sanitytaxonomymanager.com/#/contributing) before submitting a pull request. 
+
+Community collaboration is highly encouraged. To make sure your contributions are aligned with project goals and principles, please read the [contributing docs](https://sanitytaxonomymanager.com/#/contributing) before submitting a pull request.
+
+- This plugin uses [@sanity/plugin-kit](https://github.com/sanity-io/plugin-kit)
+  with default configuration for build & watch scripts.
+
+- See [Testing a plugin in Sanity Studio](https://github.com/sanity-io/plugin-kit#testing-a-plugin-in-sanity-studio)
+  on how to run the plugin with hot-reload in the studio.
+
+### Component Diagrams
+
+The following diagrams map out the relationships between the components used in this plugin and are intended to help those interested in contributing to the project orient themselves. The Taxonomy Manager tree view is designed to support polyhierarchy, and to provide UI affordances common to other taxonomy management tools, both of which lend some complexity to the component structure.
+
+> [!TIP]
+> You **do not** need to understand any of this to use the plugin!
+
+<Details>
+<Summary><h4>Tree View</h4></Summary>
+
+The [Tree View component](docs/_images/taxonomyManager.png) creates the user interface for interacting with a given taxonomy (SKOS Concept Scheme) visually in the Sanity Structure tool.
+
+```mermaid
+graph BT
+    subgraph SchemeContext.Provider
+      direction BT
+      Hierarchy.tsx-->TreeView.tsx
+      subgraph TreeContext.Provider
+        direction BT
+        TreeStructure.tsx-->Hierarchy.tsx
+        TopConcepts.tsx[
+          TopConcepts.tsx
+          <i style="color: gray; font-size: small">uses SchemeContext</i>
+          <i style="color: gray; font-size: small">uses TreeContext</i>
+        ]-->TreeStructure.tsx
+        Orphans.tsx[
+          Orphans.tsx
+          <i style="color: gray; font-size: small">uses SchemeContext</i>
+          <i style="color: gray; font-size: small">uses TreeContext</i>
+        ]-->TreeStructure.tsx
+
+
+        %% Sequence below maintains RTL ordering:
+        ConceptDetailLink.tsx-->TopConcepts.tsx
+        ConceptDetailLink.tsx-->Orphans.tsx
+
+        ChildConcepts.tsx-->TopConcepts.tsx
+        ChildConcepts.tsx-->Orphans.tsx
+        Children.tsx-->ChildConcepts.tsx
+
+        ConceptDetailDialogue.tsx-->Orphans.tsx
+        ConceptDetailDialogue.tsx-->TopConcepts.tsx
+
+        ConceptDetailLink.tsx-->Children.tsx
+        ConceptDetailDialogue.tsx-->Children.tsx
+      end
+    end
+```
+
+</Details>
 
 ## License
 

package/lib/index.d.ts

@@ -1,10 +1,10 @@
+import {FieldDefinition} from 'sanity'
 import {JSX as JSX_2} from 'react'
 import {ObjectFieldProps} from 'sanity'
 import {Plugin as Plugin_2} from 'sanity'
 
 /**
- * Document Branch Filter
- *
+ * #### Document Branch Filter
  * A pluggable Function for Filtering to a Top Concept Branch within a SKOS Concept Scheme
  * @param schemeId - The unique six character concept identifier for the Concept Scheme to which you wish to filter.
  * @param branchId - The unique six character concept identifier of a branch. Child concepts will be returned.
@@ -24,18 +24,17 @@ declare type BranchOptions = {
 
 /**
  * Hierarchy View Input Component for Reference Fields
- * TODO check for scheme or branch filters — it only works if they're used; alternatively
- * provide optional parameters if a custom filter is used?
  */
 export declare function HierarchyInput(props: ObjectFieldProps): JSX_2.Element
 
 declare interface Options {
   baseUri?: string
+  customConceptFields?: FieldDefinition[]
+  customSchemeFields?: FieldDefinition[]
 }
 
 /**
- * Document Scheme Filter
- *
+ * #### Document Scheme Filter
  * Pluggable Function for Filtering to a Single SKOS Concept Scheme
  * @param schemeId - The unique six character concept identifier for the Concept Scheme to which you wish to filter.
  * @returns A reference type filter for Concepts and Top Concepts in the selected Concept Scheme
@@ -52,23 +51,23 @@ declare type SchemeOptions = {
 }
 
 /**
- * Defines a Sanity plugin for managing taxonomies.
- *
+ * #### Defines a Sanity plugin for managing taxonomies
  * BaseURI should follow an IANA http/s scheme and should terminate with either a / or #.
  * @param options - Optional configuration options for the plugin.
  * @param options.baseUri - The base URI to use for SKOS concepts and concept schemes.
+ * @param options.customConceptFields - An array of additional fields to add to the skosConcept type.
+ * @param options.customSchemeFields - An array of additional fields to add to the skosConceptScheme type.
  * @returns A Sanity plugin object.
  */
 export declare const taxonomyManager: Plugin_2<Options | undefined>
 
 /**
- * Tree View Component Wrapper
+ * #### Tree View Component Wrapper
  * This is the view component for the hierarchy tree. It is the
  * top level of concept scheme views and is passed into Desk
  * structure to render the primary view for taxonomy documents.
- * TODO: Extend SanityDocument type to include display properties.
- *       What is the type of the document object returned by the Desk
- *       structure?
+ * @param inputComponent - Specifies whether the component is Studio
+ *    input component, which will hide tree view controls and chrome.
  */
 export declare const TreeView: ({
   document,

package/lib/index.esm.d.mts

@@ -1,10 +1,10 @@
+import {FieldDefinition} from 'sanity'
 import {JSX as JSX_2} from 'react'
 import {ObjectFieldProps} from 'sanity'
 import {Plugin as Plugin_2} from 'sanity'
 
 /**
- * Document Branch Filter
- *
+ * #### Document Branch Filter
  * A pluggable Function for Filtering to a Top Concept Branch within a SKOS Concept Scheme
  * @param schemeId - The unique six character concept identifier for the Concept Scheme to which you wish to filter.
  * @param branchId - The unique six character concept identifier of a branch. Child concepts will be returned.
@@ -24,18 +24,17 @@ declare type BranchOptions = {
 
 /**
  * Hierarchy View Input Component for Reference Fields
- * TODO check for scheme or branch filters — it only works if they're used; alternatively
- * provide optional parameters if a custom filter is used?
  */
 export declare function HierarchyInput(props: ObjectFieldProps): JSX_2.Element
 
 declare interface Options {
   baseUri?: string
+  customConceptFields?: FieldDefinition[]
+  customSchemeFields?: FieldDefinition[]
 }
 
 /**
- * Document Scheme Filter
- *
+ * #### Document Scheme Filter
  * Pluggable Function for Filtering to a Single SKOS Concept Scheme
  * @param schemeId - The unique six character concept identifier for the Concept Scheme to which you wish to filter.
  * @returns A reference type filter for Concepts and Top Concepts in the selected Concept Scheme
@@ -52,23 +51,23 @@ declare type SchemeOptions = {
 }
 
 /**
- * Defines a Sanity plugin for managing taxonomies.
- *
+ * #### Defines a Sanity plugin for managing taxonomies
  * BaseURI should follow an IANA http/s scheme and should terminate with either a / or #.
  * @param options - Optional configuration options for the plugin.
  * @param options.baseUri - The base URI to use for SKOS concepts and concept schemes.
+ * @param options.customConceptFields - An array of additional fields to add to the skosConcept type.
+ * @param options.customSchemeFields - An array of additional fields to add to the skosConceptScheme type.
  * @returns A Sanity plugin object.
  */
 export declare const taxonomyManager: Plugin_2<Options | undefined>
 
 /**
- * Tree View Component Wrapper
+ * #### Tree View Component Wrapper
  * This is the view component for the hierarchy tree. It is the
  * top level of concept scheme views and is passed into Desk
  * structure to render the primary view for taxonomy documents.
- * TODO: Extend SanityDocument type to include display properties.
- *       What is the type of the document object returned by the Desk
- *       structure?
+ * @param inputComponent - Specifies whether the component is Studio
+ *    input component, which will hide tree view controls and chrome.
  */
 export declare const TreeView: ({
   document,