sanity-plugin-recursive-hierarchy 1.0.0

package/src/types.ts

@@ -0,0 +1,216 @@
+import type {ComponentType} from 'react'
+import type {CurrentUser, SanityDocument, Slug} from 'sanity'
+
+/* eslint-disable no-use-before-define */
+
+// --- Constants ---
+
+/** @public */
+export const ACTION_GROUP_ADD = 'ADD' as const
+/** @public */
+export const ACTION_GROUP_DELETE = 'DELETE' as const
+/** @public */
+export const ACTION_GROUP_EDIT = 'EDIT' as const
+/** @public */
+export const DEFAULT_LOCALE_KEY = 'default'
+export const DEFAULT_LOCALES: LocaleOption[] = [{id: 'en-US', title: 'English', flag: '🇺🇸'}]
+
+// --- Types ---
+
+/** @public */
+export type CreateDraftParams = {
+  timestamp: number
+  type: string
+  template: string
+  parentId: string
+  parentSummary: SanityDocumentWithDraftInfo | undefined
+  parentPaneId: string
+  additionalAttributes?: {
+    title?: string
+    language?: string
+    filters?: string[]
+    topLevelNode?: boolean
+  }
+}
+
+/** @public */
+export type Locale = {
+  fallbackLocale?: null | string
+  flag: string
+  id: string
+  releaseId?: string
+  status?: 'draft' | 'in_release' | 'published'
+  title: string
+}
+
+/** @public */
+export type LocaleOption = {id: string; title: string; flag?: string}
+
+/** @public */
+export type MapUpdatePayload = {
+  timestamp: number
+  treeId: string
+  documentType: string
+  nodeDocumentType: string
+  leafDocumentType: string
+  documentId: string
+  oldParentIds: Array<string>
+  newParentIds: Array<string>
+  language: string
+  suppressRouting: boolean
+  rebuildFromRoot: boolean
+  patchFields?: {
+    title?: string
+    slug?: {current?: string; fullUrl?: string}
+  }
+  actionGroup: typeof ACTION_GROUP_ADD | typeof ACTION_GROUP_DELETE | typeof ACTION_GROUP_EDIT | ''
+}
+
+/**
+ * Outer key = treeId, inner key = localeKey
+ * @public
+ */
+export type NodeAndLeafMap = Record<string, Record<string, StructureMapAndNodesDict>>
+
+export type NodeInfo = {
+  leaves: SanityDocumentWithDraftInfo[]
+  node: SanityDocumentWithDraftInfo | undefined
+}
+
+export type NodesDictionary = Record<string, NodeInfo>
+
+/** @public */
+export type PluginOptions = {
+  trees: TreeConfig[]
+  t?: (key: string, language?: string, params?: Record<string, unknown>) => string
+  createStructureFilter?: () => FilterBuilder
+  icons?: {
+    plus?: ComponentType
+    folderTree?: ComponentType
+  }
+  apiVersion?: string
+}
+
+export type RecursiveMapStoreState = {
+  inMultiLanguageWorkspace: boolean
+  setInMultiLanguageWorkspace: (inMultiLanguageWorkspace: boolean) => void
+  createDraftRequested: CreateDraftParams
+  setCreateDraftRequested: (createRequested: CreateDraftParams) => void
+  resetCreateDraftRequested: () => void
+  nodeAndLeafMap: NodeAndLeafMap
+  setNodeAndLeafMap: (nodeAndLeafMap: NodeAndLeafMap, timestamp: number) => void
+  timestampOfLastUpdate: number
+  updateTriggered: MapUpdatePayload
+  setUpdateTriggered: (updateTriggered: MapUpdatePayload) => void
+  resetUpdateTriggered: () => void
+}
+
+/** @public */
+export type SanityDocumentWithDraftInfo = Omit<
+  SanityDocument,
+  '_rev' | 'createdAt' | 'updatedAt'
+> & {
+  _id: string
+  _type: string
+  _originalId: string
+  language?: string
+  title: string
+  slug: Slug & {fullUrl?: string}
+  parentIds?: Array<string>
+  topLevelNode?: boolean
+}
+
+export type StructureMap = Record<
+  string,
+  {children: Array<SanityDocumentWithDraftInfo>; title: string}
+>
+
+/** @public */
+export type StructureMapAndNodesDict = {
+  nodesDictionary: NodesDictionary
+  structureMap: StructureMap
+}
+
+/** @public */
+export type TreeConfig = {
+  id: string
+  documentTypes: {node: string; leaf: string}
+  languageFieldName?: string
+  getLocales?: (client: unknown) => LocaleOption[]
+  leafParentReferenceField?: string
+}
+
+/* eslint-enable no-use-before-define */
+
+/** @public */
+export type TreeTemplateIds = {
+  parentNode: string
+  descendentNode: string
+  leaf: string
+}
+
+// --- Interfaces ---
+
+/** @public */
+export interface FilterBuilder {
+  type: (type: string) => FilterBuilder
+  language: (lang: string, langFieldName?: string) => FilterBuilder
+  userScope: (user: CurrentUser | null) => FilterBuilder
+  excludeSingletons: (ids: string[]) => FilterBuilder
+  custom: (filter: string) => FilterBuilder
+  build: () => string
+  getParams: () => Record<string, unknown>
+}
+
+// --- Functions ---
+
+let pluginOptions: PluginOptions = {trees: []}
+let cachedLocales: LocaleOption[] = DEFAULT_LOCALES
+
+/** @public */
+export function getAllTrees(): TreeConfig[] {
+  return pluginOptions.trees ?? []
+}
+
+export function getLocalesForRouting(): LocaleOption[] {
+  return cachedLocales
+}
+
+/** @public */
+export function getPluginOptions(): PluginOptions {
+  return pluginOptions
+}
+
+/** @public */
+export function getStructureApiVersion(): string {
+  const v = pluginOptions.apiVersion
+  if (v) return v.startsWith('v') ? v : `v${v}`
+  const envVersion = typeof process === 'undefined' ? undefined : process.env?.SANITY_API_VERSION
+  if (envVersion) {
+    return envVersion.startsWith('v') ? envVersion : `v${envVersion}`
+  }
+  return 'v2026-02-01'
+}
+
+/** @public */
+export function getTreeConfig(treeId: string): TreeConfig {
+  const tree = pluginOptions.trees?.find((t) => t.id === treeId)
+  if (!tree) throw new Error(`recursiveNestedListPlugin: no tree config found for id "${treeId}"`)
+  return tree
+}
+
+/** @public */
+export function getTreeForDocumentType(docType: string): TreeConfig | undefined {
+  return pluginOptions.trees?.find(
+    (t) => t.documentTypes.node === docType || t.documentTypes.leaf === docType,
+  )
+}
+
+export function setCachedLocales(locales: LocaleOption[]): void {
+  cachedLocales = locales
+}
+
+/** @public */
+export function setPluginOptions(options: PluginOptions): void {
+  pluginOptions = options ?? {trees: []}
+}

package/src/urlSlug/components/AsyncUrlSlugInput.tsx

@@ -0,0 +1,167 @@
+import {CloseCircleIcon} from '@sanity/icons'
+import {Box, Button, Card, Code, Flex, Spinner, Text, TextInput, Tooltip} from '@sanity/ui'
+import React, {Suspense, use, useEffect, useRef} from 'react'
+import {type ObjectInputProps, set, unset, useFormValue, usePerspective} from 'sanity'
+
+import {formatUrlPrefix, type UrlSlugValue} from '../lib/slugGeneration'
+import {cleanSlug} from '../lib/slugify'
+import {setSlugValidationPerspective} from '../lib/slugValidationPerspective'
+import {PrefixErrorBoundary} from './PrefixErrorBoundary'
+import {useAsyncUrlSlugLogic} from './useAsyncUrlSlugLogic'
+
+const urlPrefixStyle: React.CSSProperties = {
+  flex: '0 1 min-content',
+}
+
+const codeOverflowStyle: React.CSSProperties = {
+  whiteSpace: 'nowrap',
+}
+
+function PrefixLoading() {
+  return (
+    <Card style={urlPrefixStyle}>
+      <Flex align="center" gap={2} padding={3}>
+        <Spinner muted size={1} />
+        <Text muted size={1}>
+          Loading URL...
+        </Text>
+      </Flex>
+    </Card>
+  )
+}
+
+function PrefixDisplay({
+  promise,
+  sourceField,
+}: {
+  promise: Promise<string | undefined>
+  sourceField?: string
+}) {
+  const rawPrefix = use(promise)
+  const prefix = formatUrlPrefix(rawPrefix || '')
+
+  if (!prefix) return null
+
+  const maxChars = sourceField ? 30 : 35
+  const isTruncated = prefix.length > maxChars
+  const displayPrefix = isTruncated ? `${prefix.slice(0, maxChars - 1)}\u2026` : prefix
+
+  const codeElement = (
+    <Card style={urlPrefixStyle}>
+      <Code size={1} style={codeOverflowStyle}>
+        {displayPrefix}
+      </Code>
+    </Card>
+  )
+
+  if (isTruncated) {
+    return (
+      <Tooltip
+        content={
+          <Box padding={2}>
+            <Text>{prefix}</Text>
+          </Box>
+        }
+      >
+        {codeElement}
+      </Tooltip>
+    )
+  }
+
+  return codeElement
+}
+
+export const AsyncUrlSlugInput = (props: ObjectInputProps): React.JSX.Element => {
+  const {value, schemaType, onChange} = props
+  const sourceField = schemaType.options?.source as string | undefined
+  const sourceValue = useFormValue([sourceField ?? '']) as string | undefined
+  const sourceValueSlugified = sourceValue ? cleanSlug(sourceValue) : ''
+  const urlSlugValue = value as UrlSlugValue | undefined
+
+  const slugifiedSourceAtLastSyncRef = useRef<string | null>(null)
+  const currentSlug = urlSlugValue?.current ?? ''
+  if (currentSlug && sourceValueSlugified && currentSlug === sourceValueSlugified) {
+    // eslint-disable-next-line react-hooks/refs -- intentional: sync ref during render for slug tracking
+    slugifiedSourceAtLastSyncRef.current = sourceValueSlugified
+  }
+
+  const perspectiveContextValue = usePerspective()
+
+  useEffect(() => {
+    setSlugValidationPerspective(perspectiveContextValue)
+    return () => setSlugValidationPerspective(undefined)
+  }, [perspectiveContextValue])
+
+  const {optimisticSlug, prefixPromise, generateSlug, updateSlugValue, formatSlug} =
+    useAsyncUrlSlugLogic({
+      ...props,
+      value: urlSlugValue as UrlSlugValue,
+      onSlugChange: (newValue: UrlSlugValue | undefined) => {
+        onChange(newValue ? set(newValue) : unset())
+      },
+    })
+
+  function handleGenerateClick() {
+    generateSlug()
+    slugifiedSourceAtLastSyncRef.current = sourceValueSlugified || null
+  }
+
+  function onSlugChange(event: React.FormEvent<HTMLInputElement>) {
+    updateSlugValue(event.currentTarget.value)
+  }
+
+  function onSlugBlur(event: React.FocusEvent<HTMLInputElement, Element>) {
+    formatSlug(event.currentTarget.value)
+    props.elementProps.onBlur?.(event)
+  }
+
+  /* eslint-disable react-hooks/refs, no-negated-condition -- intentional: read ref during render for slug change detection */
+  const slugRefValue = slugifiedSourceAtLastSyncRef.current
+  const sourceValueChanged =
+    sourceField &&
+    sourceValueSlugified &&
+    (slugRefValue !== null
+      ? sourceValueSlugified !== slugRefValue
+      : (urlSlugValue?.current?.length ?? 0) > 0 && urlSlugValue?.current !== sourceValueSlugified)
+  /* eslint-enable react-hooks/refs, no-negated-condition */
+
+  return (
+    <Flex direction="column" gap={3}>
+      <Flex style={{gap: '0.5em'}} align="center">
+        <PrefixErrorBoundary>
+          <Suspense fallback={<PrefixLoading />}>
+            <PrefixDisplay promise={prefixPromise} sourceField={sourceField} />
+          </Suspense>
+        </PrefixErrorBoundary>
+        <Box flex={3}>
+          <TextInput
+            value={optimisticSlug?.current || ''}
+            readOnly={props.readOnly}
+            {...props.elementProps}
+            onChange={onSlugChange} // eslint-disable-line react/jsx-no-bind
+            onBlur={onSlugBlur} // eslint-disable-line react/jsx-no-bind
+            placeholder="url-friendly-slug"
+          />
+        </Box>
+        {sourceField && (
+          <Button
+            mode="ghost"
+            type="button"
+            disabled={props.readOnly}
+            onClick={handleGenerateClick} // eslint-disable-line react/jsx-no-bind
+            text={'Generate'}
+          />
+        )}
+      </Flex>
+      {sourceValueChanged && (
+        <Text accent size={0}>
+          <Flex direction="row" gap={2} align="center" justify="flex-start">
+            <CloseCircleIcon style={{flexShrink: 0}} />
+            The source value for the slug has changed. Please press &quot;generate&quot; to get the
+            updated slug (publish when ready).
+          </Flex>
+        </Text>
+      )}
+    </Flex>
+  )
+}

package/src/urlSlug/components/PrefixErrorBoundary.tsx

@@ -0,0 +1,43 @@
+import {Box, Card, Code, Text, Tooltip} from '@sanity/ui'
+import React from 'react'
+
+const urlPrefixStyle: React.CSSProperties = {flex: '0 1 min-content'}
+
+interface PrefixErrorBoundaryProps {
+  children: React.ReactNode
+}
+
+interface PrefixErrorBoundaryState {
+  error: Error | null
+}
+
+export class PrefixErrorBoundary extends React.Component<
+  PrefixErrorBoundaryProps,
+  PrefixErrorBoundaryState
+> {
+  state: PrefixErrorBoundaryState = {error: null}
+
+  static getDerivedStateFromError(error: Error): PrefixErrorBoundaryState {
+    return {error}
+  }
+
+  render(): React.ReactNode {
+    if (this.state.error) {
+      return (
+        <Tooltip
+          content={
+            <Box padding={2}>
+              <Text>Error loading prefix: {this.state.error.message}</Text>
+            </Box>
+          }
+        >
+          <Card style={urlPrefixStyle}>
+            <Code size={1}>Error</Code>
+          </Card>
+        </Tooltip>
+      )
+    }
+
+    return this.props.children
+  }
+}

package/src/urlSlug/components/useAsyncUrlSlugLogic.ts

@@ -0,0 +1,132 @@
+import {startTransition, useEffect, useEffectEvent, useOptimistic, useRef, useState} from 'react'
+import type {ObjectInputProps, SanityDocument} from 'sanity'
+import {useFormValue} from 'sanity'
+
+import {
+  formatSlugString,
+  formatUrlPrefix,
+  resolveUrlPrefix,
+  type SlugGenerationOptions,
+  type UrlSlugValue,
+} from '../lib/slugGeneration'
+
+interface UseAsyncUrlSlugLogicProps extends ObjectInputProps {
+  value: UrlSlugValue
+  onSlugChange: (value: UrlSlugValue | undefined) => void
+}
+
+export function useAsyncUrlSlugLogic(props: UseAsyncUrlSlugLogicProps): {
+  optimisticSlug: UrlSlugValue | undefined
+  prefix: string
+  prefixPromise: Promise<string | undefined>
+  generateSlug: () => void
+  updateSlugValue: (currentValue: string) => void
+  formatSlug: (input?: string) => void
+} {
+  const {value, schemaType, onSlugChange, readOnly} = props
+
+  const document = useFormValue([]) as SanityDocument | undefined
+  const options = schemaType.options as SlugGenerationOptions
+
+  const [optimisticSlug, setOptimisticSlug] = useOptimistic<
+    UrlSlugValue | undefined,
+    UrlSlugValue | undefined
+  >(value, (_prev, next) => next)
+  const [urlPrefix, setUrlPrefix] = useState<string | undefined>()
+  const [prefixPromise, setPrefixPromise] = useState<Promise<string | undefined>>(() =>
+    Promise.resolve(undefined),
+  )
+  const initialPrefixRef = useRef<string | null>(null)
+  const finalPrefix = formatUrlPrefix(urlPrefix || '')
+  const parentIds =
+    document?.parents && Array.isArray(document.parents)
+      ? document.parents.map((parent) => parent?._ref).filter(Boolean)
+      : []
+  const parentIdsString = parentIds.join(',')
+  const parentRef =
+    document?.parent && typeof document.parent === 'object' && '_ref' in document.parent
+      ? (document.parent as {_ref?: string})._ref
+      : undefined
+
+  const createPrefixPromise = useEffectEvent(
+    (doc: SanityDocument | undefined): Promise<string | undefined> => {
+      if (!doc || !doc._id) {
+        return Promise.resolve(undefined)
+      }
+      return resolveUrlPrefix(doc, options)
+    },
+  )
+
+  useEffect(() => {
+    const promise = createPrefixPromise(document)
+    setPrefixPromise(promise)
+    promise.then(
+      (prefix) => setUrlPrefix(prefix),
+      (error) => {
+        console.error(`[async-url-slug] Couldn't generate URL prefix: `, error)
+        setUrlPrefix(undefined)
+      },
+    )
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [parentIdsString, parentRef, document?.language])
+
+  const syncFullUrl = useEffectEvent(() => {
+    if (readOnly || !value?.current || !finalPrefix) return
+    if (initialPrefixRef.current === null) {
+      initialPrefixRef.current = finalPrefix
+      if (value.fullUrl) return
+    }
+    const newFullUrl = `${finalPrefix}${value.current}`
+    if (newFullUrl === value.fullUrl) return
+
+    const newValue: UrlSlugValue = {
+      current: value.current,
+      fullUrl: `${finalPrefix}${value.current}`,
+    }
+    onSlugChange(newValue)
+  })
+
+  useEffect(() => {
+    syncFullUrl()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [readOnly, finalPrefix, value?.current, value?.fullUrl])
+
+  function updateSlugValue(currentValue: string) {
+    const newValue: UrlSlugValue | undefined = currentValue
+      ? {
+          current: currentValue,
+          fullUrl: finalPrefix ? `${finalPrefix}${currentValue}` : undefined,
+        }
+      : undefined
+
+    startTransition(() => {
+      setOptimisticSlug(newValue)
+    })
+    onSlugChange(newValue)
+  }
+
+  function formatSlug(input?: string) {
+    const finalSlug = formatSlugString(input || value?.current || '', options?.maxLength)
+    updateSlugValue(finalSlug)
+  }
+
+  function generateSlug() {
+    if (!document) return
+
+    const sourceValue =
+      typeof options?.source === 'string'
+        ? (document[options.source] as string | undefined)
+        : undefined
+
+    formatSlug(sourceValue)
+  }
+
+  return {
+    optimisticSlug,
+    prefix: finalPrefix,
+    prefixPromise,
+    generateSlug,
+    updateSlugValue,
+    formatSlug,
+  }
+}

package/src/urlSlug/index.ts

@@ -0,0 +1,15 @@
+export {AsyncUrlSlugInput} from './components/AsyncUrlSlugInput'
+export {type SlugGenerationOptions, type UrlSlugValue} from './lib/slugGeneration'
+export {
+  createUrlSlugValue,
+  formatSlugString,
+  formatUrlPrefix,
+  generateUrlSlug,
+  resolveUrlPrefix,
+} from './lib/slugGeneration'
+export {cleanSlug as cleanUrlSlug, createPathSlug, sanitySlugify} from './lib/slugify'
+export {
+  getSlugValidationPerspective,
+  setSlugValidationPerspective,
+} from './lib/slugValidationPerspective'
+export {urlSlugObject} from './urlSlugObject'

package/src/urlSlug/lib/slugGeneration.ts

@@ -0,0 +1,86 @@
+import {sanitySlugify} from './slugify'
+
+export interface UrlSlugValue {
+  current?: string
+  fullUrl?: string
+}
+
+export interface SlugGenerationOptions {
+  urlPrefix?: string | ((document: Record<string, unknown>) => Promise<string> | string)
+  source?: string
+  maxLength?: number
+}
+
+export async function resolveUrlPrefix(
+  document: Record<string, unknown>,
+  options: SlugGenerationOptions,
+): Promise<string> {
+  if (!document || !document._id) {
+    return ''
+  }
+
+  if (typeof options?.urlPrefix === 'string') {
+    return options.urlPrefix
+  }
+
+  if (typeof options?.urlPrefix === 'function') {
+    const value = await Promise.resolve(options.urlPrefix(document))
+    return value as string
+  }
+
+  return ''
+}
+
+export function formatUrlPrefix(prefix: string): string {
+  if (!prefix) return ''
+
+  return `${prefix}${
+    !prefix.endsWith('/') && !prefix.includes('#') && !prefix.includes('?') ? '/' : ''
+  }`
+}
+
+export function formatSlugString(input: string, maxLength?: number): string {
+  let finalSlug = input || ''
+
+  finalSlug = finalSlug
+    .split('/')
+    .filter((segment) => !!segment)
+    .map((segment) => sanitySlugify(segment))
+    .join('/')
+
+  if (maxLength && finalSlug.length > maxLength) {
+    finalSlug = finalSlug.substring(0, maxLength)
+  }
+
+  return finalSlug
+}
+
+export async function generateUrlSlug(
+  document: Record<string, unknown>,
+  options: SlugGenerationOptions,
+): Promise<UrlSlugValue> {
+  const sourceValue = options.source ? (document[options.source] as string | undefined) : ''
+
+  if (!sourceValue) {
+    return {current: '', fullUrl: ''}
+  }
+
+  const slugValue = formatSlugString(sourceValue, options.maxLength)
+
+  const prefix = await resolveUrlPrefix(document, options)
+  const finalPrefix = formatUrlPrefix(prefix)
+
+  return {
+    current: slugValue,
+    fullUrl: finalPrefix ? `${finalPrefix}${slugValue}` : slugValue,
+  }
+}
+
+export function createUrlSlugValue(currentSlug: string, prefix: string): UrlSlugValue {
+  const finalPrefix = formatUrlPrefix(prefix)
+
+  return {
+    current: currentSlug,
+    fullUrl: finalPrefix ? `${finalPrefix}${currentSlug}` : currentSlug,
+  }
+}

package/src/urlSlug/lib/slugValidationPerspective.ts

@@ -0,0 +1,13 @@
+import {type PerspectiveContextValue} from 'sanity'
+
+let current: PerspectiveContextValue | undefined
+
+export function getSlugValidationPerspective(): PerspectiveContextValue | undefined {
+  return current
+}
+
+export function setSlugValidationPerspective(
+  perspective: PerspectiveContextValue | undefined,
+): void {
+  current = perspective
+}

package/src/urlSlug/lib/slugify.ts

@@ -0,0 +1,22 @@
+import {cleanSlug} from '../../lib/helpers'
+
+export {cleanSlug}
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- required by Sanity slugify signature
+export const sanitySlugify = (input: string, _schemaType?: unknown): string => {
+  return cleanSlug(input)
+}
+
+export const createPathSlug = (input: string): string => {
+  const segments = input.split('/')
+
+  if (segments.length === 1) {
+    return cleanSlug(segments[0] || '')
+  }
+
+  const pathPrefix = segments.slice(0, -1)
+  const titleSegment = segments[segments.length - 1] || ''
+  const cleanedTitle = cleanSlug(titleSegment)
+
+  return `${pathPrefix.join('/')}/${cleanedTitle}`
+}