@sanity/orderable-document-list 0.0.8 → 1.0.0-v3-studio.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Simeon Griggs
+Copyright (c) 2022 Simeon Griggs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,5 +1,12 @@
 # @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](https://github.com/sanity-io/orderable-document-list).
+
+## What is it?
 Drag-and-drop Document Ordering without leaving the Editing surface.
 
 ![2022-04-26 12 23 39](https://user-images.githubusercontent.com/9684022/165289621-dbd9d841-028e-40c7-be14-7398fcdb1210.gif)
@@ -8,80 +15,149 @@ This plugin aims to be OS-like in that you can select and move multiple document
 
 ## Requirements
 
-A Sanity Studio with [Desk Structure](https://www.sanity.io/docs/structure-builder-introduction) configured.
+A Sanity Studio with [Desk Structure](https://www.sanity.io/docs/structure-builder-introduction) configured:
+
+```ts
+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
+
+```sh
+npm install --save @sanity/orderable-document-list@studio-v3
 ```
-sanity install @sanity/orderable-document-list
+
+or
+
+```sh
+yarn add @sanity/orderable-document-list@studio-v3
 ```
 
-### 1. Import the Document List into your Desk Structure
+## Usage
 
-The config parameter requires `type` and also accepts `title` and `icon`.
+### 1. Import the Document List into your Desk Structure
 
-```js
-// ./src/desk-structure/index.js (or similar)
+The config parameter requires `type`, `S` and `context`. It also accepts `title`, `icon`, `filter` and `params`.
+`S` and `context` are available in desk-tool structure callback, and should be forwarded as is:
 
-import S from '@sanity/desk-tool/structure-builder'
+```ts
+import {createConfig} from "sanity";
+import {deskTool, StructureBuilder} from "sanity/desk";
 import {orderableDocumentListDeskItem} from '@sanity/orderable-document-list'
 
-export default () =>
-  S.list()
-    .title('Content')
-    .items([
-      // Minimum required configuration
-      orderableDocumentListDeskItem({type: 'category'}),
-
-      // Optional configuration
-      orderableDocumentListDeskItem({
-        type: 'project',
-        title: 'Projects',
-        icon: Paint
-      }),
-
-      // ... all other desk items
+export default createConfig({
+    //...
+    plugins: [
+        deskTool({
+            structure: (S, context) => { 
+                return  S.list()
+                    .title('Content')
+                    .items([
+                        // Minimum required configuration
+                        orderableDocumentListDeskItem({type: 'category', S, context}),
+
+                        // Optional configuration
+                        orderableDocumentListDeskItem({
+                            type: 'project',
+                            title: 'Projects',
+                            icon: Paint,
+                            // Required if using multiple lists of the same 'type'
+                            id: 'orderable-en-projects',
+                            // See notes on adding a `filter` below
+                            filter: `__i18n_lang == $lang`,
+                            params: {
+                                lang: 'en_US'
+                            },
+                            // pass from the structure callback params above
+                            S, 
+                            context
+                        }),
+
+                        // ... all other desk items
+                ])
+            },
+        })
+    ]
+})
 ```
 
+**Caution: Adding a `filter`**
+
+By default, the plugin will display _all_ documents of the same `type`. However, you may wish to add a `filter` to reduce this down to a subset of documents. A typical usecase is for [internationalized document schema](https://github.com/sanity-io/document-internationalization) to order documents of just the base language version.
+
+However, order ranks are still computed based on _all_ documents of the same `type`. Creating multiple lists with different `filter` settings could produce unexpected results.
+
 ### 2. Add the `orderRank` field to your schema(s).
 
-You must pass in the `type` of the schema, to create an `initialValue` value.
+You must pass in the `type` of the schema and the schema `context`, to create an `initialValue` value.
+Context is available in the schema callback, and should be forwarded as is.
 
 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.
 
-Example:
+Take note that orderRankField requires a configured sanity client, that must be passed
+from the schema configuration context as shown in the following example:
 
 ```js
-// ./src/schema/category.js (or similar)
-
-import {
-  orderRankField,
-  orderRankOrdering,
-} from '@sanity/orderable-document-list';
-
-export default {
-  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' }),
-
-    // OR you can override _some_ of the field settings
-    orderRankField({ type: 'category', hidden: false }),
-
-    // ...all other fields
+// 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: {
+        // pass context to orderRankField
+        types: (previousTypes, context) => {
+            return [
+                ...previousTypes, 
+                {
+                    name: "category",
+                    title: "Category",
+                    type: "document",
+                    // Optional: The plugin also exports a set of 'orderings' for use in other Document Lists
+                    // https://www.sanity.io/docs/sort-orders
+                    orderings: [orderRankOrdering],
+                    fields: [
+                        // Minimum required configuration
+                        orderRankField({ type: "category", context }),
+
+                        // OR you can override _some_ of the field settings
+                        orderRankField({ type: 'category', hidden: false, context }),
+
+                        // ...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.
+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.
+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
 
@@ -97,10 +173,13 @@ To get this first version out the door there are few configuration settings and
 
 - 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 :)
 
+### Breaking change in the v3 version
+`orderRank` and `orderableDocumentListDeskItem` requires context from sanity config now.
+See the examples above.
+
 ## How it works
 
 Uses [kvandakes](https://github.com/kvandake)'s [TypeScript implementation](https://github.com/kvandake/lexorank-ts) of [Jira's Lexorank](https://www.youtube.com/watch?v=OjQv9xMoFbg) to create a "lexographical" Document order.
@@ -111,3 +190,18 @@ Put simply it updates the position of an individual – or many – Documents in
 
 MIT © Simeon Griggs
 See LICENSE
+
+## Develop & test
+
+This plugin uses [@sanity/plugin-kit](https://github.com/sanity-io/plugin-kit)
+with default configuration for build & watch scripts.
+
+See [Testing a plugin in Sanity Studio](https://github.com/sanity-io/plugin-kit#testing-a-plugin-in-sanity-studio)
+on how to run this plugin with hotreload in the studio.d & watch
+
+## Release new version
+
+Run ["CI & Release" workflow](https://github.com/sanity-io/code-input/actions).
+Make sure to select the main branch and check "Release new version".
+
+Semantic release will only release on configured branches, so it is safe to run release on any branch.

package/lib/index.d.ts

@@ -0,0 +1,38 @@
+import { ConfigContext } from "sanity";
+import { ComponentType } from "react";
+import { StructureBuilder } from "sanity/desk";
+type SchemaContext = Omit<ConfigContext, 'schema' | 'currentUser' | 'client'>;
+export interface RankFieldConfig {
+    type: string;
+    context: SchemaContext;
+}
+export const orderRankField: (config: RankFieldConfig) => {
+    name: "orderRank";
+    type: string;
+    initialValue: () => Promise<string>;
+    context: SchemaContext;
+    title: string;
+    readOnly: boolean;
+    hidden: boolean;
+};
+export const orderRankOrdering: {
+    title: string;
+    name: string;
+    by: {
+        field: "orderRank";
+        direction: string;
+    }[];
+};
+export interface OrderableListConfig {
+    type: string;
+    id?: string;
+    title?: string;
+    icon?: ComponentType;
+    params?: Record<string, unknown>;
+    filter?: string;
+    context: ConfigContext;
+    S: StructureBuilder;
+}
+export function orderableDocumentListDeskItem(config: OrderableListConfig): import("sanity/desk").ListItem;
+
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"mappings":";;;AGMA,qBAA4B,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,aAAa,GAAG,QAAQ,CAAC,CAAA;AAEpF;IACE,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,aAAa,CAAA;CACvB;AAED,OAAO,MAAM,yBAA0B,eAAe;;;;aAH3C,aAAa;;;;CAkCvB,CAAA;AC1CD,OAAO,MAAM;;;;;;;CAIZ,CAAA;AWED;IACE,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,aAAa,CAAA;IACtB,CAAC,EAAE,gBAAgB,CAAA;CACpB;AAED,8CAA8C,MAAM,EAAE,mBAAmB,kCA4CxE","sources":["src/src/helpers/constants.ts","src/src/helpers/initialRank.ts","src/src/desk-structure/globalClientWorkaround.ts","src/src/fields/orderRankField.ts","src/src/fields/orderRankOrdering.ts","src/src/OrderableContext.ts","src/src/Document.tsx","src/src/helpers/reorderDocuments.ts","src/src/helpers/client.ts","src/src/DraggableList.tsx","src/src/Feedback.tsx","src/src/DocumentListQuery.tsx","src/src/DocumentListWrapper.tsx","src/src/helpers/resetOrder.ts","src/src/OrderableDocumentList.tsx","src/src/desk-structure/orderableDocumentListDeskItem.ts","src/src/index.ts","src/index.ts"],"sourcesContent":[null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,"import {orderRankField, RankFieldConfig} from './fields/orderRankField'\nimport {orderRankOrdering} from './fields/orderRankOrdering'\nimport {\n  orderableDocumentListDeskItem,\n  type OrderableListConfig,\n} from './desk-structure/orderableDocumentListDeskItem'\n\nexport type {OrderableListConfig, RankFieldConfig}\nexport {orderRankField, orderRankOrdering, orderableDocumentListDeskItem}\n"],"names":[],"version":3,"file":"index.d.ts.map","sourceRoot":"../"}