sanity-plugin-taxonomy-manager 4.7.2 → 5.0.0

package/src/helpers/schemeFilter.ts

@@ -1,22 +1,13 @@
 import type {useClient} from 'sanity'
 
+import {assertSchemeId, buildSchemeFilterResult, type SchemeFilterResult} from '../core/filters'
+
 type SchemeOptions = {
   schemeId: string
   expanded?: boolean
   browseOnly?: boolean
 }
 
-type SchemeFilterResult = {
-  filter: string
-  params: {
-    schemeId: string
-    concepts: string[]
-    topConcepts: string[]
-  }
-  expanded?: boolean
-  browseOnly?: boolean
-}
-
 /**
  * #### Reference Field Scheme Filter
  * Pluggable Function for Filtering to a Single SKOS Concept Scheme.
@@ -53,7 +44,7 @@ type SchemeFilterResult = {
  * ```
  */
 export const schemeFilter = (
-  options: SchemeOptions
+  options: SchemeOptions,
 ): (({
   getClient,
 }: {
@@ -61,10 +52,7 @@ export const schemeFilter = (
 }) => Promise<SchemeFilterResult>) => {
   // Get and validate the schemeId from options
   const {schemeId} = options || {}
-
-  if (!schemeId || typeof schemeId !== 'string') {
-    throw new Error('Invalid or missing schemeId: scheme Id must be a string')
-  }
+  assertSchemeId(schemeId)
 
   return async (props) => {
     const client = props?.getClient({apiVersion: '2025-02-19'})
@@ -72,20 +60,20 @@ export const schemeFilter = (
       throw new Error('Client not available')
     }
     // Fetch concepts and topConcepts for the given schemeId
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unnecessary-type-assertion
+
     const {concepts, topConcepts} = (await client.fetch(
       `{
       "concepts": *[_type=="skosConceptScheme" && schemeId == "${schemeId}"].concepts[]._ref,
       "topConcepts": *[_type=="skosConceptScheme" && schemeId == "${schemeId}"].topConcepts[]._ref
-    }`
+    }`,
     )) as {concepts: string[]; topConcepts: string[]}
     // schemeId is included in params for use by the ArrayHierarchyInput component
-    return {
-      filter: `(_id in $concepts
-              || _id in $topConcepts)`,
-      params: {concepts, topConcepts, schemeId},
+    return buildSchemeFilterResult({
+      schemeId,
+      concepts,
+      topConcepts,
       expanded: options?.expanded,
       browseOnly: options?.browseOnly,
-    }
+    })
   }
 }

package/src/hooks/index.ts

@@ -2,4 +2,4 @@ export * from './useAddTitle'
 export * from './useCreateConcept'
 export * from './useOpenNewConceptPane'
 export * from './useRemoveConcept'
-export * from './useEmbeddingsRecs'
+export * from './useSemanticRecommendations'

package/src/hooks/useCreateConcept.tsx

@@ -1,129 +1,52 @@
-import {
-  DocumentId,
-  getDraftId,
-  getVersionId,
-  getVersionNameFromId,
-  isVersionId,
-  getPublishedId,
-  type VersionId,
-} from '@sanity/id-utils'
 import {useToast} from '@sanity/ui'
 import {uuid} from '@sanity/uuid'
-import {useCallback} from 'react'
-import {isPublishedId, useClient} from 'sanity'
+import {useCallback, useContext} from 'react'
 
-import {getPluginConfig} from '../config'
-import {createId} from '../helpers/createId'
-import type {SkosConceptDocument, SkosConceptReference, ConceptSchemeDocument} from '../types'
+import {TaxonomyConfigContext} from '../context'
+import {createId} from '../core/createId'
+import {planCreateConcept} from '../core/mutations'
+import {useTaxonomyDataPort} from '../seams/TaxonomyPortContext'
+import type {ConceptSchemeDocument} from '../types'
 
 import {useOpenNewConceptPane} from './useOpenNewConceptPane'
 
 /**
  * #### Concept Creation Hook
- * Used for creating concepts and top concepts from the
- * Concept Scheme hierarchy view.
+ * Used for creating concepts and top concepts from the Concept Scheme hierarchy
+ * view. The release/version-aware transaction is planned purely in
+ * `core/mutations` and executed through the data port; this hook stays thin —
+ * it generates the random ids/keys, builds the plan, and handles the toast +
+ * new-pane navigation.
  */
 export function useCreateConcept(document: ConceptSchemeDocument) {
   const toast = useToast()
-  const client = useClient({apiVersion: '2025-02-19'})
   const openInNewPane = useOpenNewConceptPane()
+  const port = useTaxonomyDataPort()
+  const applyConceptPlan = port.useApplyConceptPlan()
 
-  // Get ident config from plugin
-  const pluginConfig = getPluginConfig()
-  const ident = pluginConfig?.ident
-
+  // Ident config (identifier generation) comes from plugin options via context.
+  const {ident} = useContext(TaxonomyConfigContext)
   const schemaBaseIri = document.displayed.baseIri
 
   const createConcept = useCallback(
-    (
-      conceptType: 'topConcept' | 'concept',
-      concept?: {
-        id: string
-        _originalId?: string
-      }
-    ) => {
-      // destructure IDs and rename for this context
-      const {id: broaderConceptId, _originalId: broaderConceptOriginalId = ''} = concept || {}
-      // check if the skosConceptScheme is in a release
-      const isInRelease = isVersionId(document.displayed._id as DocumentId)
-      // if so, get the release name
-      const releaseName = isInRelease
-        ? getVersionNameFromId(document.displayed._id as VersionId)
-        : undefined
-
-      // create a scheme ID based on context
-      const schemeId = isInRelease
-        ? getVersionId(DocumentId(document.displayed._id), releaseName as string)
-        : getDraftId(DocumentId(document.displayed._id))
-
-      // Generate the appropriate concept ID based on context
-      const newConceptId = isInRelease
-        ? getVersionId(DocumentId(uuid()), releaseName as string)
-        : getDraftId(DocumentId(uuid()))
-
-      // create the new skosConcept document
-      const skosConcept: SkosConceptDocument = {
-        _id: newConceptId, // either a draft ID or a release ID
-        _type: 'skosConcept',
+    (conceptType: 'topConcept' | 'concept', concept?: {id: string; _originalId?: string}) => {
+      const plan = planCreateConcept({
+        scheme: document.displayed,
+        conceptType,
+        broaderConcept: concept?.id
+          ? {id: concept.id, _originalId: concept._originalId ?? ''}
+          : undefined,
+        newConceptUuid: uuid(),
         conceptId: createId(ident),
-        prefLabel: '',
-        baseIri: schemaBaseIri,
-        broader: [],
-        related: [],
-      }
-
-      // if a broader concept ID is provided, add it to the skosConcept
-      if (broaderConceptId) {
-        // check if the broader concept is published
-        const isPublished = isPublishedId(DocumentId(broaderConceptOriginalId))
-        // add broader as _strengthenOnPublish if it's not published
-        skosConcept.broader = [
-          {
-            _key: uuid(),
-            _ref: getPublishedId(DocumentId(broaderConceptId)),
-            _type: 'reference',
-            _weak: !isPublished,
-            _strengthenOnPublish: isPublished
-              ? undefined
-              : {
-                  type: 'skosConcept',
-                  template: {id: 'skosConcept'},
-                },
-          },
-        ]
-      }
-
-      const skosConceptReference: SkosConceptReference = {
-        _ref: getPublishedId(newConceptId),
-        _type: 'reference',
-        _key: uuid(),
-        _strengthenOnPublish: {
-          type: 'skosConcept',
-          template: {id: 'skosConcept'},
-        },
-        _weak: true,
-      }
-
-      client
-        .transaction()
-        .createIfNotExists({...document.displayed, _id: schemeId})
-        .create(skosConcept)
-        .patch(schemeId, (patch) => {
-          if (conceptType === 'topConcept') {
-            return patch
-              .setIfMissing({topConcepts: []})
-              .append('topConcepts', [skosConceptReference])
-          }
-          return patch.setIfMissing({concepts: []}).append('concepts', [skosConceptReference])
-        })
-        .commit({autoGenerateArrayKeys: true})
-        .then((_res) => {
-          toast.push({
-            closable: true,
-            status: 'success',
-            title: 'Created new concept',
-          })
-          openInNewPane(newConceptId)
+        schemeBaseIri: schemaBaseIri,
+        newConceptKey: uuid(),
+        broaderKey: uuid(),
+      })
+
+      applyConceptPlan(plan)
+        .then(() => {
+          toast.push({closable: true, status: 'success', title: 'Created new concept'})
+          openInNewPane(plan.newConceptId)
         })
         .catch((err) => {
           toast.push({
@@ -134,7 +57,7 @@ export function useCreateConcept(document: ConceptSchemeDocument) {
           })
         })
     },
-    [document.displayed, ident, schemaBaseIri, client, toast, openInNewPane]
+    [document.displayed, ident, schemaBaseIri, applyConceptPlan, toast, openInNewPane]
   )
   return createConcept
 }

package/src/hooks/useRemoveConcept.tsx

@@ -1,53 +1,39 @@
-import {
-  DocumentId,
-  getDraftId,
-  getVersionId,
-  getVersionNameFromId,
-  isVersionId,
-  type VersionId,
-} from '@sanity/id-utils'
 import {useToast} from '@sanity/ui'
-import {useCallback} from 'react'
-import {useClient} from 'sanity'
+import {useCallback, useContext} from 'react'
 
+import {OptimisticTreeContext} from '../context'
+import {planRemoveConcept} from '../core/mutations'
+import {useTaxonomyDataPort} from '../seams/TaxonomyPortContext'
 import type {ConceptSchemeDocument} from '../types'
 
 /**
  * #### Concept Removal Hook
- * Used for removing concepts and top concepts from
- * the Concept Scheme hierarchy view.
+ * Used for removing concepts and top concepts from the Concept Scheme hierarchy
+ * view. The release/version-aware transaction is planned purely in
+ * `core/mutations` and executed through the data port; this hook replays the
+ * plan, prunes the concept from the tree optimistically (reverting if the
+ * mutation fails), and handles the toast.
  */
 export function useRemoveConcept(document: ConceptSchemeDocument) {
   const toast = useToast()
-  const client = useClient({apiVersion: '2025-02-19'})
+  const port = useTaxonomyDataPort()
+  const applyConceptPlan = port.useApplyConceptPlan()
+  const {markRemoved, unmarkRemoved} = useContext(OptimisticTreeContext)
 
   // conceptId is the id of the concept to be removed
   const removeConcept = useCallback(
     (conceptId: string, conceptType: string, prefLabel?: string) => {
-      const type = conceptType == 'topConcept' ? 'topConcepts' : 'concepts'
+      const plan = planRemoveConcept({
+        scheme: document.displayed,
+        conceptRef: conceptId,
+        conceptType,
+      })
 
-      const isInRelease = isVersionId(document.displayed._id as DocumentId)
-      const releaseName = isInRelease
-        ? getVersionNameFromId(document.displayed._id as VersionId)
-        : undefined
+      // Prune from the tree immediately; the live listener reconciles after.
+      markRemoved(conceptId)
 
-      const schemeId = isInRelease
-        ? getVersionId(DocumentId(document.displayed._id), releaseName as string)
-        : getDraftId(DocumentId(document.displayed._id))
-
-      // Ensure concepts are removed from a draft of the concept scheme document
-      // const draftConceptScheme = JSON.parse(JSON.stringify(document.displayed))
-
-      // if (!draftConceptScheme._id.includes('drafts.')) {
-      //   draftConceptScheme._id = `drafts.${draftConceptScheme._id}`
-      // }
-
-      client
-        .transaction()
-        .createIfNotExists({...document.displayed, _id: schemeId})
-        .patch(schemeId, (patch) => patch.unset([`${type}[_ref=="${conceptId}"]`]))
-        .commit()
-        .then((_res) => {
+      applyConceptPlan(plan)
+        .then(() => {
           toast.push({
             closable: true,
             status: 'success',
@@ -55,6 +41,8 @@ export function useRemoveConcept(document: ConceptSchemeDocument) {
           })
         })
         .catch((err) => {
+          // Roll the optimistic removal back so the concept reappears.
+          unmarkRemoved(conceptId)
           toast.push({
             closable: true,
             status: 'error',
@@ -63,7 +51,7 @@ export function useRemoveConcept(document: ConceptSchemeDocument) {
           })
         })
     },
-    [client, document.displayed, toast]
+    [applyConceptPlan, document.displayed, toast, markRemoved, unmarkRemoved]
   )
   return removeConcept
 }

package/src/hooks/useSemanticRecommendations.tsx

@@ -0,0 +1,75 @@
+import {useState, useCallback, useMemo} from 'react'
+import {useClient, useGetFormValue} from 'sanity'
+
+import {
+  assembleQueryText,
+  recommendationsErrorMessage,
+  recommendationsQuery,
+  toConceptRecommendations,
+  type RecommendationRow,
+} from '../core/semanticRecommendations'
+import type {ConceptRecommendation, SemanticSearchConfig} from '../types'
+
+/**
+ * GROQ API version for the recommendations query. `text::semanticSimilarity()`
+ * is documented as a stable function, but its minimum dated API version isn't
+ * published; `vX` is the channel known to expose it (and what the pre-migration
+ * embeddings hook already used, so this is no stability regression). Pin to a
+ * dated version once confirmed against the live API.
+ */
+const SEMANTIC_API_VERSION = 'vX'
+
+/** Default number of recommended terms — preserved from the prior behavior. */
+const DEFAULT_MAX_RESULTS = 3
+
+/**
+ * Studio-side implementation of the semantic-recommendations seam. Reads the
+ * configured form fields, runs the `text::semanticSimilarity()` query against the
+ * published perspective, and exposes the scored concepts plus a friendly error.
+ * All decision-bearing logic (query, validation, mapping, error wording) lives in
+ * the pure `core/semanticRecommendations`; this hook only wires Studio (client +
+ * form values) and React state.
+ */
+export function useSemanticRecommendations(semanticSearch?: SemanticSearchConfig) {
+  // Recommend established terms: score against the published perspective, matching
+  // the old published embeddings index. Memoized so the client ref stays stable.
+  const baseClient = useClient({apiVersion: SEMANTIC_API_VERSION})
+  const client = useMemo(() => baseClient.withConfig({perspective: 'published'}), [baseClient])
+  const getFormValue = useGetFormValue()
+
+  const [conceptRecs, setConceptRecs] = useState<ConceptRecommendation[]>([])
+  const [recsError, setRecsError] = useState<string | null>(null)
+
+  const triggerSearch = useCallback(
+    (schemeId?: string) => {
+      setRecsError(null)
+      // Recommendations are scoped to the field's scheme; without a resolved
+      // schemeId there is nothing to scope against, so skip the search.
+      if (!semanticSearch || !schemeId) return
+      const {fieldReferences, maxResults = DEFAULT_MAX_RESULTS} = semanticSearch
+
+      let searchQuery: string
+      try {
+        searchQuery = assembleQueryText(
+          fieldReferences.map((name) => ({name, value: getFormValue([name])}))
+        )
+      } catch (error) {
+        setRecsError(
+          error instanceof Error ? error.message : 'One or more required fields are empty'
+        )
+        return
+      }
+
+      client
+        .fetch(recommendationsQuery(), {searchQuery, maxResults, schemeId})
+        .then((rows: RecommendationRow[]) => setConceptRecs(toConceptRecommendations(rows)))
+        .catch((error) => {
+          console.error('Error fetching semantic recommendations: ', error)
+          setRecsError(recommendationsErrorMessage(error))
+        })
+    },
+    [client, getFormValue, semanticSearch]
+  )
+
+  return {conceptRecs, recsError, triggerSearch}
+}

package/src/index.test.ts

@@ -0,0 +1,31 @@
+import {describe, expect, it} from 'vitest'
+
+import * as publicApi from './index'
+
+// The consumer contract: exactly these names are exported, and the plugin
+// registers exactly these two schema types. Renaming or removing any is a
+// breaking change — pin them so it can't happen by accident before 5.0.0.
+
+describe('public export surface', () => {
+  it('exports exactly the six documented members', () => {
+    expect(Object.keys(publicApi).sort()).toEqual(
+      [
+        'ArrayHierarchyInput',
+        'ReferenceHierarchyInput',
+        'TreeView',
+        'branchFilter',
+        'schemeFilter',
+        'taxonomyManager',
+      ].sort()
+    )
+  })
+
+  it('registers the plugin under its documented name with both schema types', () => {
+    const plugin = publicApi.taxonomyManager({})
+    expect(plugin.name).toBe('taxonomyManager')
+
+    const types = plugin.schema?.types
+    const typeNames = Array.isArray(types) ? types.map((type) => type.name).sort() : []
+    expect(typeNames).toEqual(['skosConcept', 'skosConceptScheme'])
+  })
+})

package/src/index.ts

@@ -3,12 +3,11 @@ import {structureTool} from 'sanity/structure'
 
 import {ReferenceHierarchyInput, ArrayHierarchyInput} from './components/inputs'
 import {TreeView} from './components/TreeView'
-import {setPluginConfig} from './config'
 import {schemeFilter, branchFilter} from './helpers'
 import skosConcept from './skosConcept'
 import skosConceptScheme from './skosConceptScheme'
 import NodeTree from './static/NodeTree'
-import {defaultDocumentNode, structure} from './structure'
+import {createDefaultDocumentNode, structure} from './structure'
 import type {Options} from './types'
 
 /**
@@ -28,9 +27,6 @@ import type {Options} from './types'
 const taxonomyManager = definePlugin((options?: Options) => {
   const {baseUri, customConceptFields, customSchemeFields, ident} = options || {}
 
-  // Store config for access in hooks
-  setPluginConfig(options)
-
   return {
     name: 'taxonomyManager',
     options,
@@ -45,7 +41,7 @@ const taxonomyManager = definePlugin((options?: Options) => {
         name: 'taxonomy',
         title: 'Taxonomy',
         structure,
-        defaultDocumentNode,
+        defaultDocumentNode: createDefaultDocumentNode({ident}),
         icon: NodeTree,
       }),
     ],

package/src/seams/StudioDataAdapter.ts

@@ -0,0 +1,81 @@
+import {useCallback} from 'react'
+import {useClient} from 'sanity'
+import {useListeningQuery} from 'sanity-plugin-utils'
+
+import type {ConceptPlan, ConceptTreeParams, TaxonomyDataPort, WatchResult} from '../core/ports'
+import {inputBuilder, trunkBuilder} from '../core/queries'
+import {useSemanticRecommendations} from '../hooks/useSemanticRecommendations'
+import type {DocumentConcepts} from '../types'
+
+/**
+ * #### Studio Data Adapter
+ * The default `TaxonomyDataPort` implementation: today's behavior, lifted
+ * verbatim behind the interface. Tree watching stays on Studio's
+ * `documentStore.listenQuery` (via `useListeningQuery`), mutations replay
+ * `core/mutations` plans onto `client.transaction()`, and recommendations run a
+ * `text::semanticSimilarity()` GROQ query (`useSemanticRecommendations`). Watch
+ * and mutation behavior matches the pre-port components; recommendations were
+ * migrated off the deprecated Embeddings Index API in Stage 5.
+ */
+
+// Content Releases API version — must be preserved on the mutation path.
+const MUTATION_API_VERSION = '2025-02-19'
+
+function useWatchTree(params: ConceptTreeParams): WatchResult<DocumentConcepts> {
+  const isInput = params.mode === 'input'
+  const result = useListeningQuery<DocumentConcepts>(
+    {
+      fetch: isInput ? inputBuilder() : trunkBuilder(),
+      listen: isInput
+        ? `*[_type == "skosConcept" || _id == $id]`
+        : `*[_type == "skosConcept" || _type == "skosConceptScheme" ]`,
+    },
+    {
+      params: isInput
+        ? // GROQ's select($branchId != null => …) needs null, not ''. ListenQueryParams
+          // rejects null, so we cast past it — preserved from the original InputHierarchy.
+          ({id: params.documentId, branchId: params.branchId} as any)
+        : {id: params.documentId},
+      options: {
+        perspective: params.perspective === undefined ? 'drafts' : [params.perspective],
+      },
+    }
+  ) as {data: DocumentConcepts | null; loading: boolean; error: unknown}
+
+  return {
+    data: result.data ?? null,
+    loading: result.loading,
+    error: result.error ? (result.error as Error) : null,
+  }
+}
+
+function useApplyConceptPlan(): (plan: ConceptPlan) => Promise<void> {
+  const client = useClient({apiVersion: MUTATION_API_VERSION})
+  return useCallback(
+    async (plan: ConceptPlan): Promise<void> => {
+      if (plan.kind === 'remove') {
+        await client
+          .transaction()
+          .createIfNotExists(plan.createIfNotExists)
+          .patch(plan.schemeId, (patch) => patch.unset(plan.unsetPaths))
+          .commit()
+        return
+      }
+      await client
+        .transaction()
+        .createIfNotExists(plan.createIfNotExists)
+        .create(plan.create)
+        .patch(plan.schemeId, (patch) =>
+          patch.setIfMissing({[plan.appendField]: []}).append(plan.appendField, [plan.reference])
+        )
+        .commit({autoGenerateArrayKeys: true})
+    },
+    [client]
+  )
+}
+
+export const studioDataAdapter: TaxonomyDataPort = {
+  useWatchTree,
+  useApplyConceptPlan,
+  useSemanticRecommendations,
+}

package/src/seams/TaxonomyPortContext.tsx

@@ -0,0 +1,33 @@
+import {createContext, useContext} from 'react'
+import type {ReactElement, ReactNode} from 'react'
+
+import type {TaxonomyDataPort} from '../core/ports'
+
+import {studioDataAdapter} from './StudioDataAdapter'
+
+/**
+ * #### Taxonomy Port Context
+ * Carries the active `TaxonomyDataPort`. The default is the real
+ * `StudioDataAdapter`, so production renders need **no provider mounted** —
+ * which matters because Sanity mounts our Tree View (structure) and our field
+ * inputs (document forms) in separate trees with no shared root we own.
+ *
+ * Tests inject an in-memory fake:
+ * `<TaxonomyPortProvider port={createFakeDataPort({tree})}>…</TaxonomyPortProvider>`.
+ */
+const TaxonomyPortContext = createContext<TaxonomyDataPort>(studioDataAdapter)
+
+export function TaxonomyPortProvider({
+  port,
+  children,
+}: {
+  port: TaxonomyDataPort
+  children: ReactNode
+}): ReactElement {
+  return <TaxonomyPortContext.Provider value={port}>{children}</TaxonomyPortContext.Provider>
+}
+
+/** Read the active data port (default: `StudioDataAdapter`). */
+export function useTaxonomyDataPort(): TaxonomyDataPort {
+  return useContext(TaxonomyPortContext)
+}