sanity-plugin-taxonomy-manager 4.7.2 → 5.0.0

package/src/core/semanticRecommendations.ts

@@ -0,0 +1,127 @@
+import {getPublishedId, type DocumentId} from '@sanity/id-utils'
+
+import type {ConceptRecommendation} from '../types'
+
+/**
+ * #### Semantic Recommendations (pure core)
+ * The decision-bearing logic for the semantic term-recommendation seam: the GROQ
+ * query, the query-text assembly + validation, result mapping, and error
+ * messaging. The Studio adapter (`useSemanticRecommendations`) supplies the form
+ * values, runs the query, and owns React state; everything here is pure so it can
+ * be unit-tested without Studio or the network.
+ *
+ * Replaces the deprecated Embeddings Index API (`/embeddings-index/query/…`,
+ * `text::embedding()`) with dataset embeddings queried through
+ * `text::semanticSimilarity()` — no named index, scored in GROQ.
+ */
+
+/**
+ * GROQ for the recommendations query. Scores the `skosConcept`s belonging to the
+ * scheme identified by `$schemeId` — those referenced by that scheme's `topConcepts`
+ * or `concepts` (concepts carry no scheme back-reference, so membership runs through
+ * the scheme) — by semantic similarity to `$searchQuery`, returning the top
+ * `$maxResults` as `{conceptId, score}`, most-relevant first. Scoping to the field's
+ * scheme keeps recommendations within the vocabulary the field draws from rather than
+ * the whole dataset. `text::semanticSimilarity()` is only valid inside `score()`, and
+ * the dataset must have embeddings enabled or the query errors (surfaced via
+ * {@link recommendationsErrorMessage}).
+ *
+ * Scoping is scheme-level: a `branchFilter` field still scores the whole scheme, not
+ * just the displayed branch. Branch-level scoping is tracked in #93.
+ */
+export const recommendationsQuery = (): string =>
+  `*[_type == "skosConcept" && _id in *[_type == "skosConceptScheme" && schemeId == $schemeId][0]{
+    "ids": coalesce(topConcepts[]._ref, []) + coalesce(concepts[]._ref, [])
+  }.ids] | score(text::semanticSimilarity($searchQuery)) | order(_score desc) [0...$maxResults] {
+    "conceptId": _id,
+    "score": _score
+  }`
+
+/** A document field name paired with its current value, read from the edited document. */
+export interface RecommendationField {
+  name: string
+  value: unknown
+}
+
+/**
+ * Concatenate the referenced fields' values into the semantic-search query text.
+ * Every field must hold a non-empty string; otherwise this throws with a message
+ * naming the empty field(s), which the adapter surfaces as `recsError` rather than
+ * searching against partial input. The messages are preserved verbatim from the
+ * pre-migration embeddings hook.
+ */
+export function assembleQueryText(fields: RecommendationField[]): string {
+  const values: string[] = []
+  const emptyFields: string[] = []
+  for (const {name, value} of fields) {
+    if (typeof value === 'string' && value.trim() !== '') {
+      values.push(value)
+    } else {
+      emptyFields.push(name)
+    }
+  }
+  if (emptyFields.length === 1) {
+    throw new Error(`Please fill out the ${emptyFields[0]} field to enable match scores.`)
+  }
+  if (emptyFields.length > 1) {
+    throw new Error(
+      `The following fields must be filled out to enable match scores: ${emptyFields.join(', ')}`
+    )
+  }
+  return values.join(' ')
+}
+
+/** A raw row from {@link recommendationsQuery}, before id normalization. */
+export interface RecommendationRow {
+  conceptId: string
+  score: number
+}
+
+/**
+ * Map raw query rows to {@link ConceptRecommendation}s, normalizing each concept id
+ * to its published form so they line up with `annotateRanks`, which keys the tree by
+ * published id. Rows missing a string id or numeric score are dropped.
+ */
+export function toConceptRecommendations(
+  rows: readonly RecommendationRow[] | null | undefined
+): ConceptRecommendation[] {
+  if (!rows) return []
+  const recs: ConceptRecommendation[] = []
+  for (const row of rows) {
+    if (!row || typeof row.conceptId !== 'string' || row.conceptId === '') continue
+    if (typeof row.score !== 'number') continue
+    recs.push({conceptId: getPublishedId(row.conceptId as DocumentId), score: row.score})
+  }
+  return recs
+}
+
+/**
+ * The set of published concept ids that are semantic recommendations. The raw
+ * `text::semanticSimilarity()` score is opaque and unitless (meaningful only for
+ * relative ordering within one query), so we keep only set membership — a concept
+ * is either recommended or it isn't — and let the query's `maxResults` bound the
+ * size. De-duplicated by construction.
+ */
+export function recommendedConceptIds(recs: readonly ConceptRecommendation[]): Set<string> {
+  return new Set(recs.map((rec) => rec.conceptId))
+}
+
+/** Friendly message shown when a dataset has no embeddings enabled. */
+const EMBEDDINGS_DISABLED_MESSAGE = "Semantic recommendations aren't enabled for this dataset."
+/** Fallback for any other recommendations failure. */
+const GENERIC_RECS_ERROR_MESSAGE = 'Unable to load semantic recommendations.'
+
+/**
+ * Map a failed recommendations fetch to a friendly `recsError` message. A dataset
+ * without embeddings is the expected failure — `text::semanticSimilarity()` errors
+ * there — so an embeddings-related error becomes a clear setup hint; anything else
+ * falls back to a generic message. Either way the tree still renders, only without
+ * scores.
+ *
+ * The embeddings-disabled detection matches on the error text; confirm it against
+ * the live API error in a `pnpm dev` pass and widen the match if the wording differs.
+ */
+export function recommendationsErrorMessage(error: unknown): string {
+  const text = error instanceof Error ? error.message : typeof error === 'string' ? error : ''
+  return /embedding/i.test(text) ? EMBEDDINGS_DISABLED_MESSAGE : GENERIC_RECS_ERROR_MESSAGE
+}

package/src/core/tree/annotateRecommendations.test.ts

@@ -0,0 +1,43 @@
+import {describe, expect, it} from 'vitest'
+
+import type {ChildConceptTerm} from '../../types'
+
+import {annotateRecommendations} from './annotateRecommendations'
+
+function node(id: string, childConcepts?: ChildConceptTerm[]): ChildConceptTerm {
+  return {id, prefLabel: id, ...(childConcepts ? {childConcepts} : {})}
+}
+
+describe('annotateRecommendations', () => {
+  it('marks a matching node as recommended', () => {
+    const result = annotateRecommendations(node('c-1'), new Set(['c-1']))
+    expect(result.recommended).toBe(true)
+  })
+
+  it('normalizes the node id (strips drafts. prefix) before lookup', () => {
+    const result = annotateRecommendations(node('drafts.c-1'), new Set(['c-1']))
+    expect(result.recommended).toBe(true)
+  })
+
+  it('leaves recommended and hasMatchingDescendant unset when nothing matches', () => {
+    const result = annotateRecommendations(node('c-1'), new Set())
+    expect(result.recommended).toBeUndefined()
+    expect(result.hasMatchingDescendant).toBeUndefined()
+  })
+
+  it('flags hasMatchingDescendant up the ancestor chain when a descendant is recommended', () => {
+    const tree = node('root', [node('mid', [node('leaf')])])
+    const result = annotateRecommendations(tree, new Set(['leaf']))
+
+    expect(result.recommended).toBeUndefined()
+    expect(result.hasMatchingDescendant).toBe(true)
+    expect(result.childConcepts?.[0]?.hasMatchingDescendant).toBe(true)
+    expect(result.childConcepts?.[0]?.childConcepts?.[0]?.recommended).toBe(true)
+  })
+
+  it('does not mutate the input node', () => {
+    const input = node('c-1', [node('c-2')])
+    annotateRecommendations(input, new Set(['c-1']))
+    expect(input).toEqual(node('c-1', [node('c-2')]))
+  })
+})

package/src/core/tree/annotateRecommendations.ts

@@ -0,0 +1,30 @@
+import {getPublishedId, type DocumentId} from '@sanity/id-utils'
+
+import type {ChildConceptTerm} from '../../types'
+
+/**
+ * Recursively annotate hierarchy nodes: mark a node `recommended` when its published
+ * id is in the recommendation set, and set `hasMatchingDescendant` when any descendant
+ * is recommended. Children are processed first so the flag propagates up the ancestor
+ * chain. Pure: returns new nodes and never mutates the input.
+ */
+export function annotateRecommendations<T extends ChildConceptTerm>(
+  node: T,
+  recommendedIds: Set<string>
+): T {
+  const recommended = recommendedIds.has(getPublishedId(node.id as DocumentId))
+
+  const annotatedChildren = node.childConcepts?.map((child) =>
+    annotateRecommendations(child, recommendedIds)
+  )
+
+  const hasMatchingDescendant =
+    annotatedChildren?.some((child) => child.recommended || child.hasMatchingDescendant) ?? false
+
+  return {
+    ...node,
+    ...(recommended ? {recommended: true} : {}),
+    ...(hasMatchingDescendant ? {hasMatchingDescendant: true} : {}),
+    ...(annotatedChildren ? {childConcepts: annotatedChildren} : {}),
+  } as T
+}

package/src/core/tree/pruneConcepts.test.ts

@@ -0,0 +1,77 @@
+import {describe, expect, it} from 'vitest'
+
+import type {DocumentConcepts} from '../../types'
+
+import {collectConceptIds, pruneConcepts} from './pruneConcepts'
+
+const tree = (): DocumentConcepts => ({
+  topConcepts: [
+    {
+      id: 'top-1',
+      prefLabel: 'Top 1',
+      childConcepts: [
+        {id: 'child-1', prefLabel: 'Child 1', level: 1},
+        {
+          id: 'child-2',
+          prefLabel: 'Child 2',
+          level: 1,
+          childConcepts: [{id: 'grandchild-1', prefLabel: 'Grandchild 1', level: 2}],
+        },
+      ],
+    },
+    {id: 'top-2', prefLabel: 'Top 2'},
+  ],
+  concepts: [{id: 'orphan-1', prefLabel: 'Orphan 1', isOrphan: true}],
+})
+
+describe('pruneConcepts', () => {
+  it('returns the same reference when nothing is removed', () => {
+    const data = tree()
+    expect(pruneConcepts(data, new Set())).toBe(data)
+  })
+
+  it('passes null through', () => {
+    expect(pruneConcepts(null, new Set(['top-1']))).toBeNull()
+  })
+
+  it('removes a top concept (and its subtree) by id', () => {
+    const result = pruneConcepts(tree(), new Set(['top-1']))
+    expect(result?.topConcepts.map((c) => c.id)).toEqual(['top-2'])
+    expect(result?.concepts.map((c) => c.id)).toEqual(['orphan-1'])
+  })
+
+  it('removes a nested child without touching its siblings', () => {
+    const result = pruneConcepts(tree(), new Set(['child-1']))
+    expect(result?.topConcepts[0].childConcepts?.map((c) => c.id)).toEqual(['child-2'])
+  })
+
+  it('removes a deeply nested grandchild', () => {
+    const result = pruneConcepts(tree(), new Set(['grandchild-1']))
+    const child2 = result?.topConcepts[0].childConcepts?.find((c) => c.id === 'child-2')
+    expect(child2?.childConcepts).toEqual([])
+  })
+
+  it('removes an orphan concept', () => {
+    const result = pruneConcepts(tree(), new Set(['orphan-1']))
+    expect(result?.concepts).toEqual([])
+  })
+
+  it('does not mutate the input', () => {
+    const data = tree()
+    pruneConcepts(data, new Set(['child-1', 'orphan-1']))
+    expect(data.topConcepts[0].childConcepts?.map((c) => c.id)).toEqual(['child-1', 'child-2'])
+    expect(data.concepts.map((c) => c.id)).toEqual(['orphan-1'])
+  })
+})
+
+describe('collectConceptIds', () => {
+  it('collects every id across top, orphan, and nested children', () => {
+    expect(collectConceptIds(tree())).toEqual(
+      new Set(['top-1', 'child-1', 'child-2', 'grandchild-1', 'top-2', 'orphan-1'])
+    )
+  })
+
+  it('returns an empty set for null', () => {
+    expect(collectConceptIds(null)).toEqual(new Set())
+  })
+})

package/src/core/tree/pruneConcepts.ts

@@ -0,0 +1,72 @@
+import type {ChildConceptTerm, DocumentConcepts} from '../../types'
+
+type ConceptNodeList = readonly {id: string; childConcepts?: ChildConceptTerm[]}[] | undefined
+
+/**
+ * Recursively remove every concept whose `id` is in `removedIds` from a concept
+ * tree — top concepts, orphan/concepts, and all nested `childConcepts`. Returns
+ * a new tree without mutating the input; passes `null` and an empty removal set
+ * through unchanged (same reference).
+ *
+ * Used by the optimistic-removal layer in `Hierarchy`: a concept unset from a
+ * scheme disappears tree-wide (the trunk query gates every node on scheme
+ * membership), so pruning by id mirrors what the live listener will eventually
+ * return — letting the tree update instantly instead of waiting on the refetch.
+ */
+export function pruneConcepts(
+  data: DocumentConcepts | null,
+  removedIds: ReadonlySet<string>
+): DocumentConcepts | null {
+  if (!data || removedIds.size === 0) return data
+  return {
+    ...data,
+    topConcepts: (data.topConcepts ?? [])
+      .filter((concept) => !removedIds.has(concept.id))
+      .map((concept) =>
+        concept.childConcepts
+          ? {...concept, childConcepts: pruneChildren(concept.childConcepts, removedIds)}
+          : concept
+      ),
+    concepts: (data.concepts ?? [])
+      .filter((concept) => !removedIds.has(concept.id))
+      .map((concept) =>
+        concept.childConcepts
+          ? {...concept, childConcepts: pruneChildren(concept.childConcepts, removedIds)}
+          : concept
+      ),
+  }
+}
+
+function pruneChildren(
+  children: ChildConceptTerm[],
+  removedIds: ReadonlySet<string>
+): ChildConceptTerm[] {
+  return children
+    .filter((concept) => !removedIds.has(concept.id))
+    .map((concept) =>
+      concept.childConcepts
+        ? {...concept, childConcepts: pruneChildren(concept.childConcepts, removedIds)}
+        : concept
+    )
+}
+
+/**
+ * Collect every concept `id` present anywhere in the tree (top, orphan, and all
+ * nested children). Used to reconcile the optimistic removal set against fresh
+ * listener data — once an id is gone from the data, it can be forgotten.
+ */
+export function collectConceptIds(data: DocumentConcepts | null): Set<string> {
+  const ids = new Set<string>()
+  const walk = (concepts: ConceptNodeList): void => {
+    if (!concepts) return
+    for (const concept of concepts) {
+      ids.add(concept.id)
+      walk(concept.childConcepts)
+    }
+  }
+  if (data) {
+    walk(data.topConcepts)
+    walk(data.concepts)
+  }
+  return ids
+}

package/src/core/validation.test.ts

@@ -0,0 +1,42 @@
+import {describe, expect, it} from 'vitest'
+
+import {conceptFilter, prefLabelUniquenessResult} from './validation'
+
+describe('conceptFilter', () => {
+  it('excludes self and already-referenced broader/related concepts', () => {
+    const result = conceptFilter({
+      document: {_id: 'concept-1', broader: [{_ref: 'b-1'}, {_ref: 'b-2'}], related: [{_ref: 'r-1'}]} as never,
+    })
+    expect(result.filter).toBe('!(_id in $broader || _id in $related || _id == $self)')
+    expect(result.params).toEqual({self: 'concept-1', broader: ['b-1', 'b-2'], related: ['r-1']})
+  })
+
+  it('defaults broader/related to empty arrays when absent', () => {
+    const result = conceptFilter({document: {_id: 'concept-1'} as never})
+    expect(result.params.broader).toEqual([])
+    expect(result.params.related).toEqual([])
+  })
+
+  it('normalizes self to the published id (strips the drafts. prefix)', () => {
+    const result = conceptFilter({document: {_id: 'drafts.concept-1'} as never})
+    expect(result.params.self).toBe('concept-1')
+  })
+})
+
+describe('prefLabelUniquenessResult', () => {
+  it('returns the error when a different published concept already uses the label', () => {
+    expect(prefLabelUniquenessResult('other-concept', 'concept-1')).toBe(
+      'Preferred Label must be unique.',
+    )
+  })
+
+  it('passes when the existing match is the current document (draft or published)', () => {
+    expect(prefLabelUniquenessResult('concept-1', 'drafts.concept-1')).toBe(true)
+    expect(prefLabelUniquenessResult('concept-1', 'concept-1')).toBe(true)
+  })
+
+  it('passes when no existing concept uses the label', () => {
+    expect(prefLabelUniquenessResult(null, 'concept-1')).toBe(true)
+    expect(prefLabelUniquenessResult(undefined, 'concept-1')).toBe(true)
+  })
+})

package/src/core/validation.ts

@@ -0,0 +1,42 @@
+import {DocumentId, getPublishedId} from '@sanity/id-utils'
+import type {SanityDocument} from 'sanity'
+
+/**
+ * #### Concept reference filter
+ * Reference-field `options.filter` for broader/related concept fields: excludes
+ * the concept itself and any concepts already chosen as broader/related, keeping
+ * the two relationship sets mutually exclusive. Pure — the host calls it with
+ * the current document.
+ */
+export function conceptFilter({document}: {document: SanityDocument}) {
+  const publishedId = getPublishedId(DocumentId(document._id))
+  return {
+    filter: '!(_id in $broader || _id in $related || _id == $self)',
+    params: {
+      self: publishedId,
+      broader: Array.isArray(document?.broader)
+        ? document.broader.map(({_ref}: {_ref: string}) => _ref)
+        : [],
+      related: Array.isArray(document?.related)
+        ? document.related.map(({_ref}: {_ref: string}) => _ref)
+        : [],
+    },
+  }
+}
+
+/**
+ * #### Preferred-label uniqueness result
+ * Given the id of an existing published concept that already uses a candidate
+ * prefLabel (or null/undefined if none), decide the validation result. Returns
+ * the error message when the match is a *different* document, otherwise `true`.
+ * The fetch that finds the existing concept stays in the schema (impure).
+ */
+export function prefLabelUniquenessResult(
+  existingConceptId: string | null | undefined,
+  currentDocumentId: string | undefined,
+): string | true {
+  if (existingConceptId && !currentDocumentId?.includes(existingConceptId)) {
+    return 'Preferred Label must be unique.'
+  }
+  return true
+}

package/src/helpers/baseIriField.ts

@@ -0,0 +1,22 @@
+import {defineField} from 'sanity'
+
+import {RdfUri} from '../components/inputs'
+
+/**
+ * #### Base Universal Resource Identifier object for Sanity Taxonomy Manager
+ * Used for Concept and Concept Scheme URI fields
+ */
+export default [
+  defineField({
+    name: 'baseIri',
+    title: 'Base URI',
+    type: 'url',
+    validation: (Rule) =>
+      Rule.required().error(`Please supply a base URI in the format 'http://example.com/'`),
+    description:
+      'The root URI (Uniform Resource Identifier) used to create unique concept identifiers.',
+    components: {
+      input: RdfUri as any,
+    },
+  }),
+]

package/src/helpers/branchFilter.test.ts

@@ -0,0 +1,48 @@
+import {describe, expect, it, vi} from 'vitest'
+
+import {branchFilter} from './branchFilter'
+
+type FilterProps = Parameters<ReturnType<typeof branchFilter>>[0]
+
+function stubProps(result: {concepts: string[]}) {
+  const fetch = vi.fn().mockResolvedValue(result)
+  const getClient = vi.fn(() => ({fetch}))
+  return {props: {getClient} as unknown as FilterProps, fetch, getClient}
+}
+
+describe('branchFilter', () => {
+  it('throws synchronously when schemeId is missing or not a string', () => {
+    expect(() => branchFilter({branchId: 'd4e5f6'} as never)).toThrow(
+      'Invalid or missing schemeId: scheme Id must be a string',
+    )
+  })
+
+  it('throws synchronously when branchId is missing or not a string', () => {
+    expect(() => branchFilter({schemeId: 'abc123'} as never)).toThrow(
+      'Invalid or missing branchId: branch Id must be a string',
+    )
+  })
+
+  it('fetches with apiVersion 2023-01-01 and returns the filter, params, and options', async () => {
+    const {props, fetch, getClient} = stubProps({concepts: ['concept-x', 'concept-y']})
+
+    const result = await branchFilter({
+      schemeId: 'abc123',
+      branchId: 'd4e5f6',
+      expanded: true,
+      browseOnly: true,
+    })(props)
+
+    expect(getClient).toHaveBeenCalledWith({apiVersion: '2023-01-01'})
+    expect(result.filter).toMatchInlineSnapshot(`"_id in $concepts"`)
+    expect(result.params).toEqual({
+      concepts: ['concept-x', 'concept-y'],
+      schemeId: 'abc123',
+      branchId: 'd4e5f6',
+    })
+    expect(result.expanded).toBe(true)
+    expect(result.browseOnly).toBe(true)
+    // schemeId and branchId are passed as GROQ params (not interpolated)
+    expect(fetch.mock.calls[0]?.[1]).toEqual({schemeId: 'abc123', branchId: 'd4e5f6'})
+  })
+})

package/src/helpers/branchFilter.ts

@@ -1,5 +1,12 @@
 import type {useClient} from 'sanity'
 
+import {
+  assertBranchId,
+  assertSchemeId,
+  buildBranchFilterResult,
+  type BranchFilterResult,
+} from '../core/filters'
+
 type BranchOptions = {
   schemeId: string
   branchId: string
@@ -7,17 +14,6 @@ type BranchOptions = {
   browseOnly?: boolean
 }
 
-type BranchFilterResult = {
-  filter: string
-  params: {
-    schemeId: string
-    branchId: string
-    concepts: string[]
-  }
-  expanded?: boolean
-  browseOnly?: boolean
-}
-
 /**
  * #### Reference Field Scheme & Branch Filter
  * A pluggable Function for Filtering to a Top Concept Branch within a SKOS Concept Scheme
@@ -56,21 +52,15 @@ type BranchFilterResult = {
  * ```
  */
 export const branchFilter = (
-  options: BranchOptions
+  options: BranchOptions,
 ): (({
   getClient,
 }: {
   getClient: (clientOptions: {apiVersion: string}) => ReturnType<typeof useClient>
 }) => Promise<BranchFilterResult>) => {
   const {schemeId, branchId = null} = options || {}
-
-  if (!schemeId || typeof schemeId !== 'string') {
-    throw new Error('Invalid or missing schemeId: scheme Id must be a string')
-  }
-
-  if (!branchId || typeof branchId !== 'string') {
-    throw new Error('Invalid or missing branchId: branch Id must be a string')
-  }
+  assertSchemeId(schemeId)
+  assertBranchId(branchId)
 
   return async (props) => {
     const client = props?.getClient({apiVersion: '2023-01-01'})
@@ -79,7 +69,7 @@ export const branchFilter = (
     }
 
     // Fetch concepts for the given schemeId and branchId
-    // 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} = (await client.fetch(
       `{      
         "concepts": *[
@@ -91,14 +81,15 @@ export const branchFilter = (
               || $branchId in broader[]->broader[]->broader[]->broader[]->broader[]->conceptId)
           ]._id
       }`,
-      {schemeId, branchId}
+      {schemeId, branchId},
     )) as {concepts: string[]}
     // schemeId is included in params for use by the ArrayHierarchyInput component
-    return {
-      filter: `_id in $concepts`,
-      params: {concepts, schemeId, branchId},
+    return buildBranchFilterResult({
+      schemeId,
+      branchId,
+      concepts,
       expanded: options?.expanded,
       browseOnly: options?.browseOnly,
-    }
+    })
   }
 }

package/src/helpers/schemeFilter.test.ts

@@ -0,0 +1,51 @@
+import {describe, expect, it, vi} from 'vitest'
+
+import {schemeFilter} from './schemeFilter'
+
+type FilterProps = Parameters<ReturnType<typeof schemeFilter>>[0]
+
+function stubProps(result: {concepts: string[]; topConcepts: string[]}) {
+  const fetch = vi.fn().mockResolvedValue(result)
+  const getClient = vi.fn(() => ({fetch}))
+  return {props: {getClient} as unknown as FilterProps, fetch, getClient}
+}
+
+describe('schemeFilter', () => {
+  it('throws synchronously when schemeId is missing or not a string', () => {
+    expect(() => schemeFilter({} as never)).toThrow(
+      'Invalid or missing schemeId: scheme Id must be a string',
+    )
+    expect(() => schemeFilter({schemeId: 123 as never})).toThrow('Invalid or missing schemeId')
+  })
+
+  it('fetches with apiVersion 2025-02-19 and returns the filter, params, and options', async () => {
+    const {props, fetch, getClient} = stubProps({
+      concepts: ['concept-a', 'concept-b'],
+      topConcepts: ['top-1'],
+    })
+
+    const result = await schemeFilter({schemeId: 'abc123', expanded: true, browseOnly: true})(props)
+
+    expect(getClient).toHaveBeenCalledWith({apiVersion: '2025-02-19'})
+    expect(result.filter).toMatchInlineSnapshot(`
+      "(_id in $concepts
+                    || _id in $topConcepts)"
+    `)
+    expect(result.params).toEqual({
+      concepts: ['concept-a', 'concept-b'],
+      topConcepts: ['top-1'],
+      schemeId: 'abc123',
+    })
+    expect(result.expanded).toBe(true)
+    expect(result.browseOnly).toBe(true)
+    // schemeId is string-interpolated into the fetch query (not passed as a param)
+    expect(fetch.mock.calls[0]?.[0]).toContain('schemeId == "abc123"')
+  })
+
+  it('passes expanded/browseOnly through as undefined when omitted', async () => {
+    const {props} = stubProps({concepts: [], topConcepts: []})
+    const result = await schemeFilter({schemeId: 'abc123'})(props)
+    expect(result.expanded).toBeUndefined()
+    expect(result.browseOnly).toBeUndefined()
+  })
+})