sanity-plugin-taxonomy-manager 4.7.0 → 4.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sanity-plugin-taxonomy-manager",
-  "version": "4.7.0",
+  "version": "4.7.2",
   "description": "Create and manage SKOS compliant taxonomies, thesauri, and classification schemes in Sanity Studio.",
   "keywords": [
     "sanity",

package/src/components/inputs/ArrayHierarchyInput.tsx

@@ -15,7 +15,7 @@ import {
 } from '@sanity/ui'
 import {useState, useEffect, useCallback} from 'react'
 import type {ArrayFieldProps, ObjectOptions} from 'sanity'
-import {useClient, useFormValue, isVersionId, isDraftId, usePerspective} from 'sanity'
+import {FormField, useClient, useFormValue, isVersionId, isDraftId, usePerspective} from 'sanity'
 
 import {useEmbeddingsRecs} from '../../hooks'
 import NodeTree from '../../static/NodeTree'
@@ -44,14 +44,142 @@ type ArrayHierarchyInputProps = ArrayFieldProps & {
 type FilterResult = Awaited<ReturnType<ReferenceOptions['filter']>>
 
 /**
- * #### Hierarchy View Input Component
- * Allows Studio users to browse and select taxonomy
- * terms from a hierarchical tree structure. It is designed to be
- * used as an input for taxonomy array fields in Sanity Studio.
+ * Input component that replaces Sanity's default array field input with a
+ * hierarchical taxonomy tree browser. Studio users can browse taxonomy terms
+ * organized in their scheme hierarchy and select terms to add to the array field.
  *
- * Hierarchy view must be used in conjunction with the Taxonomy Manager
- * plugin `schemeFilter` or `branchFilter` options.
+ * @remarks
+ * - Must be used with a `schemeFilter` or `branchFilter` helper in the field's
+ *   `options.filter`. Rendering without a filter will display a configuration warning.
+ * - Supports only **single-schema arrays** (i.e., `of: [{type: 'reference'}]`). Arrays
+ *   with multiple schema types will render a warning and fall back to the default input.
+ * - Taxonomy selection is disabled when viewing the published perspective.
+ * - When `browseOnly` is set in the filter configuration, Sanity's default search input
+ *   is suppressed and only the tree browser is available for term selection.
+ * - When `expanded` is set in the filter configuration, the hierarchy tree loads open
+ *   by default instead of collapsed.
  *
+ * @param props - Standard Sanity `ArrayFieldProps` extended with an optional
+ *   `embeddingsIndex` configuration object.
+ * @param props.embeddingsIndex - Optional configuration for AI-assisted term
+ *   recommendations via a Sanity Embeddings Index. When provided, opening the tree
+ *   browser queries the specified index and annotates matching taxonomy terms with
+ *   a relevance score to help authors identify the most appropriate terms.
+ * @param props.embeddingsIndex.indexName - The name of the Sanity Embeddings Index
+ *   to query. Must be an index that includes `skosConcept` documents.
+ * @param props.embeddingsIndex.fieldReferences - An array of field names from the
+ *   current document whose values are concatenated and sent as the embeddings search
+ *   query. All listed fields must contain values when the tree browser is opened;
+ *   empty fields will display an error message in the tree view rather than scores.
+ * @param props.embeddingsIndex.maxResults - Maximum number of semantically matching
+ *   terms to return from the embeddings index. Defaults to `3`.
+ *
+ * @example
+ * Basic usage with a scheme filter:
+ * ```js
+ * import {ArrayHierarchyInput, schemeFilter} from 'sanity-plugin-taxonomy-manager'
+ *
+ * defineField({
+ *   name: 'categories',
+ *   title: 'Categories',
+ *   type: 'array',
+ *   of: [
+ *     {
+ *       type: 'reference',
+ *       to: {type: 'skosConcept'},
+ *       options: {
+ *         filter: schemeFilter({schemeId: 'f3deba'}),
+ *         disableNew: true,
+ *       },
+ *     },
+ *   ],
+ *   components: {field: ArrayHierarchyInput},
+ * })
+ * ```
+ *
+ * @example
+ * Branch filter with tree expanded by default:
+ * ```js
+ * import {ArrayHierarchyInput, branchFilter} from 'sanity-plugin-taxonomy-manager'
+ *
+ * defineField({
+ *   name: 'habitats',
+ *   title: 'Habitats',
+ *   type: 'array',
+ *   of: [
+ *     {
+ *       type: 'reference',
+ *       to: {type: 'skosConcept'},
+ *       options: {
+ *         filter: branchFilter({schemeId: 'cf76c1', branchId: '1e5e6c', expanded: true}),
+ *         disableNew: true,
+ *       },
+ *     },
+ *   ],
+ *   components: {field: ArrayHierarchyInput},
+ * })
+ * ```
+ *
+ * @example
+ * Browse-only mode (suppresses the default Sanity search input):
+ * ```js
+ * import {ArrayHierarchyInput, branchFilter} from 'sanity-plugin-taxonomy-manager'
+ *
+ * defineField({
+ *   name: 'habitats',
+ *   title: 'Habitats',
+ *   type: 'array',
+ *   of: [
+ *     {
+ *       type: 'reference',
+ *       to: {type: 'skosConcept'},
+ *       options: {
+ *         filter: branchFilter({schemeId: 'cf76c1', branchId: '1e5e6c', browseOnly: true}),
+ *         disableNew: true,
+ *       },
+ *     },
+ *   ],
+ *   components: {field: ArrayHierarchyInput},
+ * })
+ * ```
+ *
+ * @example
+ * AI-assisted recommendations via an embeddings index:
+ * ```jsx
+ * import {ArrayHierarchyInput, branchFilter} from 'sanity-plugin-taxonomy-manager'
+ *
+ * defineField({
+ *   name: 'categories',
+ *   title: 'Categories',
+ *   type: 'array',
+ *   of: [
+ *     {
+ *       type: 'reference',
+ *       to: [{type: 'skosConcept'}],
+ *       options: {
+ *         filter: branchFilter({schemeId: 'f3deba', branchId: '25f826'}),
+ *         disableNew: true,
+ *       },
+ *     },
+ *   ],
+ *   components: {
+ *     field: (props) => (
+ *       <ArrayHierarchyInput
+ *         {...props}
+ *         embeddingsIndex={{
+ *           indexName: 'my-taxonomy-index',
+ *           fieldReferences: ['title', 'description'],
+ *           maxResults: 4,
+ *         }}
+ *       />
+ *     ),
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link ReferenceHierarchyInput} for single-value `reference` fields
+ * @see {@link schemeFilter} for filtering by a full concept scheme
+ * @see {@link branchFilter} for filtering by a branch within a concept scheme
  */
 export function ArrayHierarchyInput(props: ArrayHierarchyInputProps) {
   const client = useClient({apiVersion: '2025-02-19'})
@@ -279,19 +407,24 @@ export function ArrayHierarchyInput(props: ArrayHierarchyInputProps) {
       return props.renderDefault(props)
     }
 
+    // Wrap the empty state in `FormField` so the field exposes the same
+    // DOM target Sanity's Validation panel uses for scroll-to-field /
+    // highlight on click. Without this wrapper, clicking a required
+    // browse-only field's validation error has no effect.
     return (
-      <Stack space={2}>
-        <Box paddingY={3}>
-          <Text size={1} weight={'medium'}>
-            {title}
-          </Text>
-        </Box>
+      <FormField
+        title={title}
+        description={props.description}
+        level={props.level}
+        validation={props.validation}
+        __unstable_presence={props.presence}
+      >
         <Card padding={3} radius={2} border>
           <Text muted align="center" size={1}>
             No items
           </Text>
         </Card>
-      </Stack>
+      </FormField>
     )
   }
 

package/src/components/inputs/ReferenceHierarchyInput.tsx

@@ -4,7 +4,7 @@ import type {DocumentId} from '@sanity/id-utils'
 import {Grid, Stack, Button, Dialog, Box, Spinner, Text, Flex, Card} from '@sanity/ui'
 import {useState, useEffect, useCallback} from 'react'
 import type {ObjectFieldProps, ObjectOptions, Reference} from 'sanity'
-import {isDraftId, useClient, useFormValue, usePerspective} from 'sanity'
+import {FormField, isDraftId, useClient, useFormValue, usePerspective} from 'sanity'
 
 import {useEmbeddingsRecs} from '../../hooks'
 import NodeTree from '../../static/NodeTree'
@@ -33,13 +33,120 @@ type HierarchyInput = ObjectFieldProps<Reference> & {
 type FilterResult = Awaited<ReturnType<ReferenceOptions['filter']>>
 
 /**
- * #### Hierarchy View Input Component for Reference Fields
- * Allows Studio users to browse and select taxonomy
- * terms from a hierarchical tree structure. It is designed to be
- * used as an input for taxonomy reference fields in Sanity Studio.
+ * Input component that replaces Sanity's default reference field input with a
+ * hierarchical taxonomy tree browser. Studio users can browse taxonomy terms
+ * organized in their scheme hierarchy and select a single term for the field.
  *
- * Hierarchy view must be used in conjunction with the Taxonomy Manager
- * plugin `schemeFilter` or `branchFilter` options.
+ * @remarks
+ * - Must be used with a `schemeFilter` or `branchFilter` helper in the field's
+ *   `options.filter`. Rendering without a filter will display a configuration warning.
+ * - Taxonomy selection is disabled when viewing the published perspective.
+ * - When `browseOnly` is set in the filter configuration, Sanity's default search input
+ *   is suppressed and only the tree browser is available for term selection.
+ * - When `expanded` is set in the filter configuration, the hierarchy tree loads open
+ *   by default instead of collapsed.
+ *
+ * @param props - Standard Sanity `ObjectFieldProps<Reference>` extended with an optional
+ *   `embeddingsIndex` configuration object.
+ * @param props.embeddingsIndex - Optional configuration for AI-assisted term
+ *   recommendations via a Sanity Embeddings Index. When provided, opening the tree
+ *   browser queries the specified index and annotates matching taxonomy terms with
+ *   a relevance score to help authors identify the most appropriate term.
+ * @param props.embeddingsIndex.indexName - The name of the Sanity Embeddings Index
+ *   to query. Must be an index that includes `skosConcept` documents.
+ * @param props.embeddingsIndex.fieldReferences - An array of field names from the
+ *   current document whose values are concatenated and sent as the embeddings search
+ *   query. All listed fields must contain values when the tree browser is opened;
+ *   empty fields will display an error message in the tree view rather than scores.
+ * @param props.embeddingsIndex.maxResults - Maximum number of semantically matching
+ *   terms to return from the embeddings index. Defaults to `3`.
+ *
+ * @example
+ * Basic usage with a scheme filter:
+ * ```js
+ * import {ReferenceHierarchyInput, schemeFilter} from 'sanity-plugin-taxonomy-manager'
+ *
+ * defineField({
+ *   name: 'gradeLevel',
+ *   title: 'Grade Level',
+ *   type: 'reference',
+ *   to: {type: 'skosConcept'},
+ *   options: {
+ *     filter: schemeFilter({schemeId: 'f3deba'}),
+ *     disableNew: true,
+ *   },
+ *   components: {field: ReferenceHierarchyInput},
+ * })
+ * ```
+ *
+ * @example
+ * Branch filter with tree expanded by default:
+ * ```js
+ * import {ReferenceHierarchyInput, branchFilter} from 'sanity-plugin-taxonomy-manager'
+ *
+ * defineField({
+ *   name: 'topics',
+ *   title: 'Topics',
+ *   type: 'reference',
+ *   to: {type: 'skosConcept'},
+ *   options: {
+ *     filter: branchFilter({schemeId: 'cf76c1', branchId: '1e5e6c', expanded: true}),
+ *     disableNew: true,
+ *   },
+ *   components: {field: ReferenceHierarchyInput},
+ * })
+ * ```
+ *
+ * @example
+ * Browse-only mode (suppresses the default Sanity search input):
+ * ```js
+ * import {ReferenceHierarchyInput, branchFilter} from 'sanity-plugin-taxonomy-manager'
+ *
+ * defineField({
+ *   name: 'topics',
+ *   title: 'Topics',
+ *   type: 'reference',
+ *   to: {type: 'skosConcept'},
+ *   options: {
+ *     filter: branchFilter({schemeId: 'cf76c1', branchId: '1e5e6c', browseOnly: true}),
+ *     disableNew: true,
+ *   },
+ *   components: {field: ReferenceHierarchyInput},
+ * })
+ * ```
+ *
+ * @example
+ * AI-assisted recommendations via an embeddings index:
+ * ```jsx
+ * import {ReferenceHierarchyInput, schemeFilter} from 'sanity-plugin-taxonomy-manager'
+ *
+ * defineField({
+ *   name: 'topics',
+ *   title: 'Topics',
+ *   type: 'reference',
+ *   to: [{type: 'skosConcept'}],
+ *   options: {
+ *     filter: schemeFilter({schemeId: 'f3deba'}),
+ *     disableNew: true,
+ *   },
+ *   components: {
+ *     field: (props) => (
+ *       <ReferenceHierarchyInput
+ *         {...props}
+ *         embeddingsIndex={{
+ *           indexName: 'my-taxonomy-index',
+ *           fieldReferences: ['title', 'metaDescription'],
+ *           maxResults: 4,
+ *         }}
+ *       />
+ *     ),
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link ArrayHierarchyInput} for multi-value `array` fields
+ * @see {@link schemeFilter} for filtering by a full concept scheme
+ * @see {@link branchFilter} for filtering by a branch within a concept scheme
  */
 export function ReferenceHierarchyInput(props: HierarchyInput) {
   const client = useClient({apiVersion: 'vX'})
@@ -223,19 +330,24 @@ export function ReferenceHierarchyInput(props: HierarchyInput) {
     if (value) {
       return props.renderDefault(props)
     }
+    // Wrap the empty state in `FormField` so the field exposes the same
+    // DOM target Sanity's Validation panel uses for scroll-to-field /
+    // highlight on click. Without this wrapper, clicking a required
+    // browse-only field's validation error has no effect.
     return (
-      <Stack space={2}>
-        <Box paddingY={3}>
-          <Text size={1} weight={'medium'}>
-            {title}
-          </Text>
-        </Box>
+      <FormField
+        title={title}
+        description={props.description}
+        level={props.level}
+        validation={props.validation}
+        __unstable_presence={props.presence}
+      >
         <Card padding={3} radius={2} border>
           <Text muted align="center" size={1}>
             No items
           </Text>
         </Card>
-      </Stack>
+      </FormField>
     )
   }