@sanity/hierarchical-document-list 1.0.0 → 2.0.0

package/src/createDeskHierarchy.tsx

@@ -0,0 +1,110 @@
+import {AddIcon} from '@sanity/icons'
+import * as React from 'react'
+import type {ConfigContext} from 'sanity'
+import {StructureBuilder} from 'sanity/desk'
+
+import TreeDeskStructure from './TreeDeskStructure'
+import {TreeDeskStructureProps} from './types'
+import throwError from './utils/throwError'
+
+export interface TreeProps extends TreeDeskStructureProps {
+  /**
+   * Visible title above the tree.
+   * Also used as the label in the desk list item.
+   */
+  title: string
+
+  /**
+   * Optional icon for rendering the item in the desk structure.
+   */
+  icon?: any
+
+  context?: ConfigContext | any
+  S?: StructureBuilder | any
+  /**
+   * Restrict document types that can be created.
+   */
+  creatableTypes?: string[]
+}
+
+const deskTreeValidator = (props: TreeProps): React.FC => {
+  const {documentId, referenceTo} = props
+  if (typeof documentId !== 'string' && !documentId) {
+    throwError('invalidDocumentId')
+  }
+  if (!Array.isArray(referenceTo)) {
+    throwError('invalidReferenceTo', `(documentId "${documentId}")`)
+  }
+
+  return (deskProps) => <TreeDeskStructure {...deskProps} options={props} />
+}
+
+export default function createDeskHierarchy(props: TreeProps) {
+  const {documentId, referenceTo, referenceOptions, context, S, creatableTypes} = props
+  if (!S || !context) {
+    throw new Error('Invalid configuration. S or context props are undefined. ' +
+      'These props are available as function parameters when configuring structure, and must be passed along to createDeskHierarchy. ' +
+      'Confer the plugin README for example usage.')
+  }
+
+  const {schema} = context
+
+  const safelyCreatableTypes =
+    creatableTypes && !creatableTypes.some((type) => referenceTo.indexOf(type))
+      ? creatableTypes
+      : referenceTo
+
+  let mainList = (
+    referenceTo?.length === 1
+      ? S.documentTypeList(referenceTo[0]).schemaType(referenceTo[0])
+      : S.documentList().filter('_type in $types').params({types: referenceTo})
+  )
+    .id(documentId)
+    .menuItems(
+      (safelyCreatableTypes || []).map((schemaType) =>
+        S.menuItem()
+          .intent({
+            type: 'create',
+            params: {type: schemaType}
+          })
+          .title(`Create ${schema.get(schemaType)?.title}`)
+          .icon(schema.get(schemaType)?.icon || AddIcon)
+      )
+    )
+    .canHandleIntent((intent: string, c: Record<string, unknown>) => {
+      // Can edit itself
+      if (intent === 'edit' && c.id === props.documentId) {
+        return true
+      }
+      // Can create & edit referenced document types
+      if (safelyCreatableTypes.includes(c.type as string)) {
+        return true
+      }
+      return false
+    })
+
+  if (referenceOptions?.filter) {
+    mainList = mainList.filter(referenceOptions.filter)
+  }
+
+  if (referenceOptions?.filterParams) {
+    mainList = mainList.params(referenceOptions.filterParams)
+  }
+
+  return S.listItem()
+    .id(documentId)
+    .title(props.title || documentId)
+    .icon(props.icon)
+    .child(
+      Object.assign(
+        mainList.serialize(),
+        {
+          type: 'component',
+          component: deskTreeValidator(props),
+          options: props,
+          __preserveInstance: true
+        },
+        props.title ? {title: props.title} : {}
+      )
+    )
+}

package/src/createHierarchicalSchemas.tsx

@@ -0,0 +1,151 @@
+import * as React from 'react'
+import {ArraySchemaType} from 'sanity'
+import {DEFAULT_FIELD_KEY} from './TreeDeskStructure'
+import TreeInputComponent from './TreeInputComponent'
+import {TreeDeskStructureProps, TreeFieldSchema} from './types'
+import {
+  INTERNAL_NODE_ARRAY_TYPE,
+  INTERNAL_NODE_TYPE,
+  INTERNAL_NODE_VALUE_TYPE,
+  getSchemaTypeName
+} from './utils/injectNodeTypeInPatches'
+import throwError from './utils/throwError'
+
+type SchemaOptions = Omit<TreeDeskStructureProps, 'documentId' | 'maxDepth'>
+
+function createHierarchicalNodeValueType({
+  referenceTo,
+  referenceOptions,
+  documentType
+}: SchemaOptions) {
+  return {
+    // when used inside the field, name & type are overwritten by createHierarchicalNodeType
+    name: documentType ? getSchemaTypeName(documentType, 'nodeValue') : INTERNAL_NODE_VALUE_TYPE,
+    type: 'object',
+    title: `Hierarchical node value (${documentType})`,
+
+    fields: [
+      {name: 'docType', type: 'string'},
+      {
+        name: 'reference',
+        type: 'reference',
+        weak: true,
+        to: referenceTo.map((type) => ({type})),
+        options: referenceOptions
+      }
+    ]
+  }
+}
+
+function createHierarchicalNodeType(options: SchemaOptions) {
+  return {
+    // name & type are overwritten by createHierarchicalField
+    name: options.documentType
+      ? getSchemaTypeName(options.documentType, 'node')
+      : INTERNAL_NODE_TYPE,
+    title: `Hierarchical node (${options.documentType})`,
+    type: 'object',
+    fields: [
+      {name: 'parent', type: 'string'},
+
+      options.documentType
+        ? {name: 'value', type: getSchemaTypeName(options.documentType, 'nodeValue')}
+        : // If no documentType is defined, use an anonymized inline object to avoid
+          // having to define another custom schema type through the plugin
+          {
+            ...createHierarchicalNodeValueType(options),
+            name: 'value',
+            type: 'object'
+          }
+    ]
+  }
+}
+
+function createHierarchicalArrayType(options: SchemaOptions) {
+  return {
+    // name & type are overwritten by createHierarchicalField
+    name: options.documentType
+      ? getSchemaTypeName(options.documentType, 'array')
+      : INTERNAL_NODE_ARRAY_TYPE,
+    title: `Hierarchical array of nodes (${options.documentType})`,
+    type: 'array',
+    of: [
+      options.documentType
+        ? {type: getSchemaTypeName(options.documentType, 'node')}
+        : createHierarchicalNodeType(options)
+    ]
+  }
+}
+
+export function createHierarchicalField({name, title, options, ...rest}: TreeFieldSchema): Omit<
+  ArraySchemaType,
+  'type' | 'jsonType' | 'of'
+> & {
+  type: string
+  inputComponent: React.FC<any>
+  of?: any[]
+} {
+  if (!Array.isArray(options?.referenceTo)) {
+    throwError('invalidReferenceTo', `(field of name "${name}")`)
+  }
+
+  return {
+    ...rest,
+    name,
+    title,
+    inputComponent: TreeInputComponent,
+    options,
+    ...(options.documentType
+      ? {type: getSchemaTypeName(options.documentType, 'array')}
+      : {
+          ...createHierarchicalArrayType(options),
+          name
+        })
+  }
+}
+
+function createHierarchicalDocType(options: SchemaOptions) {
+  return {
+    name: options.documentType,
+    title: 'Hierarchical tree',
+    type: 'document',
+    // The plugin needs to define a `schemaType` with liveEdit enabled so that
+    // `useDocumentOperation` in TreeDeskStructure.tsx doesn't create drafts at every patch.
+    liveEdit: true,
+    fields: [
+      createHierarchicalField({
+        name: options.fieldKeyInDocument || DEFAULT_FIELD_KEY,
+        title: 'Hierarchical Tree',
+        options
+      })
+    ],
+    preview: {
+      select: {
+        id: '_id',
+        tree: 'tree'
+      },
+      prepare({id, tree}: {id: string; tree: unknown[]}): Record<string, string> {
+        return {
+          title: `Hierarchical documents (ID: ${id})`,
+          subtitle: `${tree?.length || 0} document(s) in its list.`
+        }
+      }
+    }
+  }
+}
+
+export default function createHierarchicalSchemas(options: SchemaOptions) {
+  if (!Array.isArray(options.referenceTo) || options.referenceTo.length <= 0) {
+    throwError('invalidReferenceTo')
+  }
+  if (!options.documentType) {
+    throwError('invalidDocumentType')
+  }
+
+  return [
+    createHierarchicalDocType(options),
+    createHierarchicalArrayType(options),
+    createHierarchicalNodeType(options),
+    createHierarchicalNodeValueType(options)
+  ]
+}

package/src/hooks/useAllItems.ts

@@ -0,0 +1,119 @@
+import * as React from 'react'
+import {SanityDocument, useClient} from 'sanity'
+import {AllItems, TreeInputOptions} from '../types'
+import {isDraft, unprefixId} from '../utils/idUtils'
+
+function getDeskFilter({referenceTo, referenceOptions}: TreeInputOptions): {
+  filter: string
+  params: Record<string, unknown>
+} {
+  const filterParts: string[] = ['_type in $docTypes']
+
+  if (referenceOptions?.filter) {
+    filterParts.push(referenceOptions.filter)
+  }
+
+  return {
+    filter: filterParts.join(' && '),
+    params: {
+      ...(referenceOptions?.filterParams || {}),
+      docTypes: referenceTo.map((schemaType) => schemaType)
+    }
+  }
+}
+
+type Status = 'loading' | 'success' | 'error'
+
+type ACTIONTYPE =
+  | {type: 'addOrEditItem'; item: SanityDocument}
+  | {type: 'removeItem'; itemId: string}
+  | {type: 'setInitialData'; items: SanityDocument[]}
+
+function updateItemInState(state: AllItems, item: SanityDocument): AllItems {
+  const newState = {...state}
+  const publishedId = unprefixId(item._id)
+  newState[publishedId] = {
+    ...(newState[publishedId] || {}),
+    [isDraft(item._id) ? 'draft' : 'published']: item
+  }
+  return newState
+}
+
+function allItemsReducer(state: AllItems, action: ACTIONTYPE): AllItems {
+  if (action.type === 'addOrEditItem' && action.item?._id) {
+    return updateItemInState(state, action.item)
+  }
+
+  if (action.type === 'removeItem') {
+    const publishedId = unprefixId(action.itemId)
+    return {
+      ...state,
+      [publishedId]: isDraft(action.itemId)
+        ? // If a draft, keep only published
+          {
+            published: state[publishedId]?.published
+          }
+        : {
+            draft: state[publishedId]?.draft
+          }
+    }
+  }
+
+  if (action.type === 'setInitialData') {
+    return action.items.reduce(updateItemInState, {} as AllItems)
+  }
+  return state
+}
+
+export default function useAllItems(options: TreeInputOptions): {
+  status: Status
+  allItems: AllItems
+} {
+  const client = useClient({
+    apiVersion: '2021-09-01'
+  })
+  const [status, setStatus] = React.useState<Status>('loading')
+  const [allItems, dispatch] = React.useReducer(allItemsReducer, {})
+
+  function handleListener(event: any) {
+    if (event.type !== 'mutation') {
+      return
+    }
+
+    if (event.result) {
+      dispatch({type: 'addOrEditItem', item: event.result})
+    } else {
+      dispatch({type: 'removeItem', itemId: event.documentId})
+    }
+  }
+
+  function handleFirstLoad(items: SanityDocument[]) {
+    dispatch({type: 'setInitialData', items})
+    setStatus('success')
+  }
+
+  React.useEffect(() => {
+    const {filter, params} = getDeskFilter(options)
+    const query = `*[${filter}] {
+      _id,
+      _type,
+      _updatedAt,
+    }`
+    client
+      .fetch<SanityDocument[]>(query, params)
+      .then(handleFirstLoad)
+      .catch(() => {
+        setStatus('error')
+      })
+
+    const listener = client.listen(query, params).subscribe(handleListener)
+    return () => {
+      listener.unsubscribe()
+    }
+  }, [])
+
+  return {
+    status,
+    allItems
+  }
+}

package/src/hooks/useLocalTree.ts

@@ -0,0 +1,40 @@
+import * as React from 'react'
+import {AllItems, LocalTreeItem, StoredTreeItem, VisibilityMap} from '../types'
+import {dataToEditorTree} from '../utils/treeData'
+
+/**
+ * Enhances tree data with information on:
+ *   - `expanded` - native property of react-sortable-tree to determine collapsing & expanding of a node's children
+ *   - `draftId` & `publishedId` - refer to LocalTreeItem's type annotations
+ *
+ * Doesn't modify the main tree or has side-effects on data.
+ * Has the added benefit of being local to the user, so external changes won't affect local visibility.
+ */
+export default function useLocalTree({
+  tree,
+  allItems,
+}: {
+  tree: StoredTreeItem[]
+  allItems: AllItems
+}): {
+  handleVisibilityToggle: (data: any) => void
+  localTree: LocalTreeItem[]
+} {
+  const [visibilityMap, setVisibilityMap] = React.useState<VisibilityMap>({})
+
+  function handleVisibilityToggle(data: any) {
+    setVisibilityMap({
+      ...visibilityMap,
+      [data.node._key]: data.expanded,
+    })
+  }
+
+  return {
+    localTree: dataToEditorTree({
+      tree,
+      allItems,
+      visibilityMap,
+    }),
+    handleVisibilityToggle,
+  }
+}

package/src/hooks/useTreeOperations.ts

@@ -0,0 +1,25 @@
+import * as React from 'react'
+import useAllItems from './useAllItems'
+import useTreeOperationsProvider from './useTreeOperationsProvider'
+
+type ContextValue = ReturnType<typeof useTreeOperationsProvider> & {
+  allItemsStatus: ReturnType<typeof useAllItems>['status']
+}
+
+function placeholder() {
+  // no-op
+}
+
+export const TreeOperationsContext = React.createContext<ContextValue>({
+  addItem: placeholder,
+  duplicateItem: placeholder,
+  removeItem: placeholder,
+  handleMovedNode: placeholder,
+  moveItemDown: placeholder,
+  moveItemUp: placeholder,
+  allItemsStatus: 'loading',
+})
+
+export default function useTreeOperations(): ContextValue {
+  return React.useContext(TreeOperationsContext)
+}

package/src/hooks/useTreeOperationsProvider.ts

@@ -0,0 +1,86 @@
+import {PatchEvent, PathSegment, prefixPath, setIfMissing} from 'sanity'
+import {LocalTreeItem, NodeProps} from '../types'
+import {
+  HandleMovedNode,
+  HandleMovedNodeData,
+  getAddItemPatch,
+  getDuplicateItemPatch,
+  getMoveItemPatch,
+  getMovedNodePatch,
+  getRemoveItemPatch
+} from '../utils/treePatches'
+
+export default function useTreeOperationsProvider(props: {
+  patchPrefix?: PathSegment
+  onChange: (patch: PatchEvent) => void
+  localTree: LocalTreeItem[]
+}): {
+  handleMovedNode: HandleMovedNode
+  addItem: (item: LocalTreeItem) => void
+  duplicateItem: (nodeProps: NodeProps) => void
+  removeItem: (nodeProps: NodeProps) => void
+  moveItemUp: (nodeProps: NodeProps) => void
+  moveItemDown: (nodeProps: NodeProps) => void
+} {
+  const {localTree} = props
+
+  function runPatches(patches: any) {
+    const finalPatches = [
+      // Ensure tree array exists before any operation
+      setIfMissing([]),
+      ...(patches || [])
+    ]
+    let patchEvent = PatchEvent.from(finalPatches)
+    if (props.patchPrefix) {
+      patchEvent = PatchEvent.from(
+        finalPatches.map((patch) => prefixPath(patch, props.patchPrefix as PathSegment))
+      )
+    }
+    props.onChange(patchEvent)
+  }
+
+  function handleMovedNode(data: HandleMovedNodeData & {node: LocalTreeItem}) {
+    runPatches(getMovedNodePatch(data))
+  }
+
+  function addItem(item: LocalTreeItem) {
+    runPatches(getAddItemPatch(item))
+  }
+
+  function duplicateItem(nodeProps: NodeProps & {node: LocalTreeItem}) {
+    runPatches(getDuplicateItemPatch(nodeProps))
+  }
+
+  function removeItem(nodeProps: NodeProps) {
+    runPatches(getRemoveItemPatch(nodeProps))
+  }
+
+  function moveItemUp(nodeProps: NodeProps) {
+    runPatches(
+      getMoveItemPatch({
+        nodeProps,
+        localTree,
+        direction: 'up'
+      })
+    )
+  }
+
+  function moveItemDown(nodeProps: NodeProps) {
+    runPatches(
+      getMoveItemPatch({
+        nodeProps,
+        localTree,
+        direction: 'down'
+      })
+    )
+  }
+
+  return {
+    handleMovedNode,
+    addItem,
+    removeItem,
+    moveItemUp,
+    moveItemDown,
+    duplicateItem
+  }
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+import {definePlugin} from 'sanity'
+import {default as createDeskHierarchy, type TreeProps} from './createDeskHierarchy'
+import {default as createHierarchicalSchemas} from './createHierarchicalSchemas'
+import {default as hierarchyTree} from './schemas/hierarchy.tree'
+import {default as flatDataToTree} from './utils/flatDataToTree'
+
+export {createDeskHierarchy, createHierarchicalSchemas, flatDataToTree, hierarchyTree, TreeProps}
+
+/**
+ * Usage in `sanity.config.ts` (or .js)
+ *
+ * ```ts
+ * import {defineConfig} from 'sanity'
+ * import {myPlugin} from 'sanity-plugin-hdl-sanity'
+ *
+ * export default defineConfig({
+ *   // ...
+ *   plugins: [myPlugin()],
+ * })
+ * ```
+ */
+
+export const hierarchicalDocumentList = definePlugin({
+  name: 'sanity-plugin-hierarchical-document-list'
+})

package/src/schemas/hierarchy.tree.ts

@@ -0,0 +1,19 @@
+import {defineType} from 'sanity'
+
+export default defineType({
+  name: 'hierarchy.tree',
+  title: 'Hierarchical tree',
+  type: 'document',
+  // The plugin needs to define a `schemaType` with liveEdit enabled so that
+  // `useDocumentOperation` in TreeDeskStructure.tsx doesn't create drafts at every patch.
+  liveEdit: true,
+  // Let's avoid defining the actual hierarchical field, else GraphQL users won't be able to deploy schemas
+  fields: [
+    {
+      name: 'unusedField',
+      title: 'Unused field',
+      type: 'string',
+      hidden: true,
+    },
+  ],
+})