@snorreeb/orderable-document-list NPM

@sanity/orderable-document-list

NOTE
This is the Sanity Studio v3 version of @sanity/orderable-document-list.
For the v2 version, please refer to the v2-branch.

What is it?

Drag-and-drop Document Ordering without leaving the Editing surface.

2022-04-26 12 23 39

This plugin aims to be OS-like in that you can select and move multiple documents by holding shift and clicking a second item, and toggling on/off selections by holding command/control.

Requirements

A Sanity Studio with Desk Structure configured:

import {createConfig} from "sanity";
import {deskTool, StructureBuilder} from "sanity/desk";

export default createConfig({
    //...
    plugins: [
        deskTool({
            structure: (S, context) => { /* Strucure code */},
        })
    ]
})

Installation

Run the following command in your studio directory

npm install --save @sanity/orderable-document-list@studio-v3

yarn add @sanity/orderable-document-list@studio-v3

Usage

1. Import the Document List into your Desk Structure

The config parameter requires type and also accepts title and icon.

import {createConfig} from "sanity";
import {deskTool, StructureBuilder} from "sanity/desk";
import {orderableDocumentListDeskItem} from '@sanity/orderable-document-list'

export default createConfig({
    //...
    plugins: [
        deskTool({
            structure: (S, context) => { 
                return  S.list()
                    .title('Content')
                    .items([
                        // Minimum required configuration
                        orderableDocumentListDeskItem({type: 'category'}),

                        // Optional configuration
                        orderableDocumentListDeskItem({
                            type: 'project',
                            title: 'Projects',
                            icon: Paint
                        }),

                        // ... all other desk items
                ])
            },
        })
    ]
})

2. Add the `orderRank` field to your schema(s).

You must pass in the type of the schema, to create an initialValue value.

Additionally, pass in overrides for the field, such as making it visible by passing hidden: false.

You cannot override the name, type or initialValue attributes.

Take note that orderRankField requires a configured sanity client, that must be passed from the schema configuration context as shown in the following example:

// sanity.config.js
import {createConfig} from "sanity";
import {deskTool, StructureBuilder} from "sanity/desk";
import {orderableDocumentListDeskItem} from '@sanity/orderable-document-list'

export default createConfig({
    //...
    plugins: [
        deskTool({structure: (S, context) => {/* snip */}})
    ],
    schema: {
        // get client from context ant pass to orderRankField
        types: (previousTypes, {client}) => {
            return [
                ...previousTypes, 
                {
                    name: "category",
                    title: "Category",
                    type: "document",
                    // Optional: The plugin also exports a set of 'orderings' for use in other Document Lists
                    orderings: [orderRankOrdering],
                    fields: [
                        // Minimum required configuration
                        orderRankField({ type: "category", client }),

                        // OR you can override _some_ of the field settings
                        // orderRankField({ type: 'category', hidden: false }),

                        // ...all other fields
                    ],
                },
            ]
        }
    }
}

3. Generate initial Ranks

On first load, your Document list will not have any Order. You can select "Reset Order" from the menu in the top right of the list. You can also re-run this at any time.

The orderRankField will query the last Document to set an initialValue to come after it. New Documents always start at the end of the Ordered list.

Querying Ordered Documents

Now when writing a GROQ Query for Documents, use the orderRank field value to return ordered results:

*[_type == "category"]|order(orderRank)

Notes

To get this first version out the door there are few configuration settings and a lot of opinions. Such as:

The name of the orderRank field is constant
The ability to only sort across all Documents of a type
The absence of a filter configuration on the Document List

Feedback and PRs welcome :)

How it works

Uses kvandakes's TypeScript implementation of Jira's Lexorank to create a "lexographical" Document order.

Put simply it updates the position of an individual – or many – Documents in an ordered list without updating any others. It's fast.

License

MIT © Simeon Griggs See LICENSE

Develop & test

Make sure to run npm run build once, then run

npm run link-watch

In another shell, cd to your test studio and run:

npx yalc add @sanity/orderable-document-list && yarn install

Now, changes in this repo will be automatically built and pushed to the studio, triggering hotreload. Yalc avoids issues with react-hooks that are typical when using yarn/npm link.