sanity-plugin-taxonomy-manager 4.7.2 → 5.0.0

package/src/test-setup.ts

@@ -0,0 +1,35 @@
+import '@testing-library/jest-dom/vitest'
+
+import {cleanup, configure} from '@testing-library/react'
+import {afterEach} from 'vitest'
+
+// CI runners (Linux especially) can be several times slower than local; give
+// findBy*/waitFor assertions headroom so async UI doesn't flake.
+configure({asyncUtilTimeout: 5000})
+
+// Vitest runs with globals: false, so Testing Library's automatic cleanup does
+// not fire. Clean the rendered DOM after each test to avoid query collisions.
+afterEach(() => cleanup())
+
+// jsdom does not implement matchMedia; @sanity/ui's responsive hooks call it.
+if (typeof window !== 'undefined' && typeof window.matchMedia !== 'function') {
+  window.matchMedia = ((query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: () => {},
+    removeListener: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    dispatchEvent: () => false,
+  })) as unknown as typeof window.matchMedia
+}
+
+// jsdom does not implement ResizeObserver; some @sanity/ui primitives use it.
+if (typeof globalThis.ResizeObserver === 'undefined') {
+  globalThis.ResizeObserver = class {
+    observe(): void {}
+    unobserve(): void {}
+    disconnect(): void {}
+  } as unknown as typeof ResizeObserver
+}

package/src/types.tsx

@@ -18,7 +18,8 @@ export interface ChildConceptTerm {
   _originalId?: string
   level?: number
   isOrphan?: boolean
-  score?: number
+  /** True when this concept is among the current semantic recommendations. */
+  recommended?: boolean
   hasMatchingDescendant?: boolean
   childConcepts?: ChildConceptTerm[]
 }
@@ -27,7 +28,8 @@ export interface TopConceptTerm {
   prefLabel: string
   id: string
   _originalId?: string
-  score?: number
+  /** True when this concept is among the current semantic recommendations. */
+  recommended?: boolean
   hasMatchingDescendant?: boolean
   childConcepts?: ChildConceptTerm[]
 }
@@ -39,7 +41,7 @@ export interface DocumentConcepts {
 
 export interface PrefLabelValue {
   value: string
-  // eslint-disable-next-line
+
   renderDefault: (props: PrefLabelValue) => React.ReactElement
 }
 
@@ -103,17 +105,34 @@ export interface ConceptSchemeDocument extends SanityDocument {
   }
 }
 
-export interface EmbeddingsResult {
+/**
+ * A semantic match score for a single concept, keyed by its published document id.
+ * Produced by the recommendations seam and merged into the hierarchy tree by
+ * `annotateRecommendations`. The GROQ `text::semanticSimilarity()` projection owns
+ * this shape directly — no wrapper object, no document type.
+ */
+export interface ConceptRecommendation {
+  conceptId: string
   score: number
-  value: {
-    documentId: string
-    type: string
-  }
 }
 
-export interface EmbeddingsIndexConfig {
-  indexName: string
+/**
+ * Configuration for the input components' semantic term recommendations. When
+ * provided, opening the tree browser scores concepts against the dataset's
+ * embeddings (via `text::semanticSimilarity()`) using the current values of the
+ * referenced fields, and annotates matching terms with a relevance score.
+ *
+ * Requires [dataset embeddings](https://www.sanity.io/docs/content-lake/dataset-embeddings)
+ * to be enabled; without them the tree still renders, just without scores.
+ */
+export interface SemanticSearchConfig {
+  /**
+   * Field names on the current document whose values are concatenated into the
+   * search query. Every listed field must hold a value when the tree is opened;
+   * empty fields surface a message in the tree view instead of scores.
+   */
   fieldReferences: string[]
+  /** Maximum number of matching terms to return. Defaults to `3`. */
   maxResults?: number
 }
 
@@ -123,6 +142,6 @@ export interface TreeViewProps {
   selectConcept?: (conceptId: {_ref: string; _type: 'reference'; _originalId?: string}) => void
   inputComponent?: boolean
   expanded?: boolean
-  conceptRecs?: EmbeddingsResult[]
+  conceptRecs?: ConceptRecommendation[]
   recsError?: string | null
 }

package/src/views/ConceptUseView.tsx

@@ -2,7 +2,6 @@ import {Flex, Spinner, Stack, Box, Card, Inline, Text, Button} from '@sanity/ui'
 import {fromString as pathFromString} from '@sanity/util/paths'
 import {useCallback} from 'react'
 import {Preview, useSchema, usePerspective, getPublishedId} from 'sanity'
-import type {SanityDocument} from 'sanity'
 import type {UserViewComponent} from 'sanity/structure'
 import {usePaneRouter} from 'sanity/structure'
 import {Feedback, useListeningQuery} from 'sanity-plugin-utils'
@@ -36,22 +35,18 @@ export const ConceptUseView: UserViewComponent<Record<string, never>> = ({
         template: {id},
       })
     },
-    [routerPanesState, groupIndex, handleEditReference]
+    [routerPanesState, groupIndex, handleEditReference],
   )
 
-  const {data, loading, error} = useListeningQuery<SanityDocument[]>(
+  const {data, loading, error} = useListeningQuery<TagReference[]>(
     `*[!(_type in ["skosConcept","skosConceptScheme"]) && references($refId)]{_id,_type,title}`,
     {
       params: {refId},
       options: {
         perspective: selectedPerspectiveName ? [selectedPerspectiveName] : 'drafts',
       },
-    }
-  ) as {
-    data: TagReference[]
-    loading: boolean
-    error: Error | null
-  }
+    },
+  )
 
   if (loading) {
     return (
@@ -106,7 +101,6 @@ export const ConceptUseView: UserViewComponent<Record<string, never>> = ({
               schemaType && (
                 <Button
                   key={d._id}
-                  // eslint-disable-next-line react/jsx-no-bind
                   onClick={() => handleClick(d._id, d._type)}
                   padding={2}
                   mode="bleed"

package/lib/index.esm.d.mts

@@ -1,492 +0,0 @@
-import type {ArrayFieldProps} from 'sanity'
-import type {FieldDefinition} from 'sanity'
-import {JSX} from 'react'
-import type {ObjectFieldProps} from 'sanity'
-import {Plugin as Plugin_2} from 'sanity'
-import type {Reference} from 'sanity'
-import type {SanityDocument} from 'sanity'
-import type {useClient} from 'sanity'
-
-/**
- * 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.
- *
- * @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 declare function ArrayHierarchyInput(props: ArrayHierarchyInputProps): JSX.Element
-
-declare type ArrayHierarchyInputProps = ArrayFieldProps & {
-  embeddingsIndex?: EmbeddingsIndexConfig
-}
-
-/**
- * #### Reference Field Scheme & Branch Filter
- * A pluggable Function for Filtering to a Top Concept Branch within a SKOS Concept Scheme
- * @param {string} schemeId - The unique six character concept identifier for
- *   the Concept Scheme to which you wish to filter.
- * @param {string} branchId - The unique six character concept identifier of
- *   a branch. Child concepts will be returned.
- * @param {boolean} [expanded] - Set to `true` to display open hierarchy trees for
- *   input components. Input component trees load closed by default.
- * @param {boolean} [browseOnly] - Set to `true` to hide the default Sanity search
- *   input and display only the "Browse Taxonomy Tree" button for selecting terms.
- * @returns A reference type filter for the child concepts of the designated branch in the selected Concept Scheme
- * @example
- * ```ts
- * import { branchFilter } from 'sanity-plugin-taxonomy-manager'
- * ...
- * {
- *   name: 'test',
- *   type: 'array',
- *   of: [
- *     {
- *       type: 'reference',
- *       to: {type: 'skosConcept'},
- *       options: {
- *         filter: branchFilter({
- *            schemeId: 'a1b2c3',
- *            branchId: 'd4e5f6',
- *            expanded: true, // optional; defaults to false (closed tree)
- *            browseOnly: true, // optional; hides search input
- *        }),
- *         disableNew: true,
- *       },
- *     },
- *   ],
- * }
- * ```
- */
-export declare const branchFilter: (
-  options: BranchOptions,
-) => ({
-  getClient,
-}: {
-  getClient: (clientOptions: {apiVersion: string}) => ReturnType<typeof useClient>
-}) => Promise<BranchFilterResult>
-
-declare type BranchFilterResult = {
-  filter: string
-  params: {
-    schemeId: string
-    branchId: string
-    concepts: string[]
-  }
-  expanded?: boolean
-  browseOnly?: boolean
-}
-
-declare type BranchOptions = {
-  schemeId: string
-  branchId: string
-  expanded?: boolean
-  browseOnly?: boolean
-}
-
-declare interface ConceptSchemeDocument extends SanityDocument {
-  displayed: {
-    _id: string
-    _type: 'skosConceptScheme'
-    title?: string
-    description?: string
-    baseIri?: string
-    schemeId?: string
-    topConcepts?: Array<{
-      _key: string
-      _ref: string
-      _type: 'reference'
-    }>
-    concepts?: Array<{
-      _key: string
-      _ref: string
-      _type: 'reference'
-    }>
-  }
-}
-
-declare interface EmbeddingsIndexConfig {
-  indexName: string
-  fieldReferences: string[]
-  maxResults?: number
-}
-
-declare interface EmbeddingsResult {
-  score: number
-  value: {
-    documentId: string
-    type: string
-  }
-}
-
-declare type HierarchyInput = ObjectFieldProps<Reference> & {
-  embeddingsIndex?: EmbeddingsIndexConfig
-}
-
-declare interface Options {
-  baseUri?: string
-  customConceptFields?: FieldDefinition[]
-  customSchemeFields?: FieldDefinition[]
-  ident?: {
-    pattern?: string
-    length?: number
-    prefix?: string
-    regenUi?: boolean
-  }
-}
-
-/**
- * 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.
- *
- * @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 declare function ReferenceHierarchyInput(props: HierarchyInput): JSX.Element
-
-/**
- * #### Reference Field Scheme Filter
- * Pluggable Function for Filtering to a Single SKOS Concept Scheme.
- * @param {string} schemeId - The unique six character concept identifier for
- *   the Concept Scheme to which you wish to filter.
- * @param {boolean} [expanded] - Set to `true` to display open hierarchy trees for
- *   input components. Input component trees load closed by default.
- * @param {boolean} [browseOnly] - Set to `true` to hide the default Sanity search
- *   input and display only the "Browse Taxonomy Tree" button for selecting terms.
- * @returns A reference type filter for Concepts and Top Concepts in
- *   the selected Concept Scheme test
- * @example
- * ```ts
- * import { schemeFilter } from 'sanity-plugin-taxonomy-manager'
- * ...
- * {
- *   name: 'test',
- *   type: 'array',
- *   of: [
- *     {
- *       type: 'reference',
- *       to: {type: 'skosConcept'},
- *       options: {
- *         filter: schemeFilter({
- *            schemeId: 'a1b2c3',
- *            expanded: true, // optional; defaults to false (closed tree)
- *            browseOnly: true, // optional; hides search input
- *          }),
- *         disableNew: true,
- *       },
- *     },
- *   ],
- * }
- * ```
- */
-export declare const schemeFilter: (
-  options: SchemeOptions,
-) => ({
-  getClient,
-}: {
-  getClient: (clientOptions: {apiVersion: string}) => ReturnType<typeof useClient>
-}) => Promise<SchemeFilterResult>
-
-declare type SchemeFilterResult = {
-  filter: string
-  params: {
-    schemeId: string
-    concepts: string[]
-    topConcepts: string[]
-  }
-  expanded?: boolean
-  browseOnly?: boolean
-}
-
-declare type SchemeOptions = {
-  schemeId: string
-  expanded?: boolean
-  browseOnly?: boolean
-}
-
-/**
- * #### Sanity Taxonomy Manager
- * Defines a Sanity plugin for managing SKOS compliant taxonomies in Sanity Studio.
- * #### Options
- * @param baseUri - The base URI to use for SKOS concepts and concept schemes. BaseURI should follow an IANA http/s scheme and should terminate with either a / or #.
- * @param customConceptFields - An array of additional fields to add to the skosConcept type.
- * @param customSchemeFields - An array of additional fields to add to the skosConceptScheme type.
- * #### Identifier Configuration
- * @param ident.pattern - The character set to use for identifiers (default: '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz').
- * @param ident.length - The length of the generated identifier (default: 6).
- * @param ident.prefix - A prefix to prepend to generated identifiers, for example to use Wikidata style IDs like "Q27521" (default: '').
- * @param ident.regenUi - Whether to display the "Create Unique Identifier" button in the UI by default.
- * @returns A Sanity plugin object.
- */
-export declare const taxonomyManager: Plugin_2<Options | undefined>
-
-/**
- * #### 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.
- * @param document - The document to render.
- * @param branchId - The branch ID to fetch concepts from.
- * @param inputComponent - Specifies whether the component is Studio input component, which will hide tree view controls and chrome.
- * @param selectConcept - The function to call when a concept is selected.
- */
-export declare const TreeView: ({
-  document,
-  branchId,
-  inputComponent,
-  selectConcept,
-  expanded,
-  conceptRecs,
-  recsError,
-}: TreeViewProps) => JSX.Element
-
-declare interface TreeViewProps {
-  document?: ConceptSchemeDocument
-  branchId?: string | null
-  selectConcept?: (conceptId: {_ref: string; _type: 'reference'; _originalId?: string}) => void
-  inputComponent?: boolean
-  expanded?: boolean
-  conceptRecs?: EmbeddingsResult[]
-  recsError?: string | null
-}
-
-export {}