sanity-plugin-taxonomy-manager/lib/index.d.ts

Create and manage SKOS compliant taxonomies, thesauri, and classification schemes in Sanity Studio.

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'

/**
 * #### 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.
 *
 * Hierarchy view must be used in conjunction with the Taxonomy Manager
 * plugin `schemeFilter` or `branchFilter` options.
 *
 */
export declare function ArrayHierarchyInput(props: ArrayFieldProps): JSX.Element

/**
 * #### 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.
 * @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)
 *        }),
 *         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
}

declare type BranchOptions = {
  schemeId: string
  branchId: string
  expanded?: 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 Options {
  baseUri?: string
  customConceptFields?: FieldDefinition[]
  customSchemeFields?: FieldDefinition[]
}

/**
 * #### 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.
 *
 * Hierarchy view must be used in conjunction with the Taxonomy Manager
 * plugin `schemeFilter` or `branchFilter` options.
 */
export declare function ReferenceHierarchyInput(props: ObjectFieldProps<Reference>): 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.
 * @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)
 *          }),
 *         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
}

declare type SchemeOptions = {
  schemeId: string
  expanded?: boolean
}

/**
 * #### 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
 * 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,
}: TreeViewProps) => JSX.Element

declare interface TreeViewProps {
  document?: ConceptSchemeDocument
  branchId: string
  selectConcept?: (conceptId: {_ref: string; _type: 'reference'; _originalId?: string}) => void
  inputComponent?: boolean
  expanded?: boolean
}

export {}