{"_id":"@bbihq/sanity-plugin-orderable-document-list","_rev":"6-f0c16588e0825fac6768335446722ec5","name":"@bbihq/sanity-plugin-orderable-document-list","dist-tags":{"latest":"1.2.0"},"versions":{"1.2.0":{"name":"@bbihq/sanity-plugin-orderable-document-list","version":"1.2.0","keywords":["sanity","sanity-plugin"],"author":{"name":"Sanity.io","email":"hello@sanity.io"},"license":"MIT","_id":"@bbihq/sanity-plugin-orderable-document-list@1.2.0","maintainers":[{"name":"williamli","email":"william@bbi.studio"}],"homepage":"https://github.com/sanity-io/orderable-document-list#readme","bugs":{"url":"https://github.com/sanity-io/orderable-document-list/issues"},"dist":{"shasum":"1ac037a734de7c433d68c08b5aab5c7483e735e4","tarball":"https://registry.npmjs.org/@bbihq/sanity-plugin-orderable-document-list/-/sanity-plugin-orderable-document-list-1.2.0.tgz","fileCount":26,"integrity":"sha512-dsXb64NbFZI71/xg5rTWiKOQ50s+XkxYYYI1qgyXx3YrReSGwh6vrcDu04YjqBzfGVlIe5urUdCg0CgH6LVyng==","signatures":[{"sig":"MEYCIQC8u7JmmoJ249akdecl3kxgCaHF3h9vtC//NVMm43pakwIhAN+Xl9Sgiha/4cM0+YuFUzNE6iNVwiPCB0fB4m8XTE0u","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":222100},"main":"./lib/index.js","husky":{"hooks":{"pre-commit":"npm run lint:fix"}},"types":"./lib/index.d.ts","module":"./lib/index.esm.js","source":"./src/index.ts","engines":{"node":">=14"},"exports":{".":{"types":"./lib/index.d.ts","import":"./lib/index.esm.js","source":"./src/index.ts","default":"./lib/index.esm.js","require":"./lib/index.js"},"./package.json":"./package.json"},"gitHead":"aa4f98fc89010ee8613e314a4c5e48f5082a69a5","scripts":{"lint":"eslint .","build":"run-s clean && plugin-kit verify-package --silent && pkg-utils build --strict && pkg-utils --strict","clean":"rimraf lib","watch":"pkg-utils watch --strict","format":"prettier --write --cache --ignore-unknown .","compile":"tsc --noEmit","prepare":"husky install","lint:fix":"eslint . --fix","prebuild":"npm run clean && plugin-kit verify-package --silent && pkg-utils","link-watch":"plugin-kit link-watch","prepublishOnly":"run-s build"},"_npmUser":{"name":"williamli","email":"william@bbi.studio"},"repository":{"url":"git+ssh://git@github.com/bbihq/sanity-plugin-orderable-document-list.git","type":"git"},"_npmVersion":"9.8.0","description":"Drag-and-drop Document Ordering without leaving the Editing surface","directories":{},"_nodeVersion":"20.9.0","dependencies":{"lexorank":"^1.0.4","@sanity/ui":"^1.7.1","prop-types":"^15.8.1","@sanity/icons":"^2.4.1","@hello-pangea/dnd":"^16.2.0","sanity-plugin-utils":"^1.6.2","@sanity/incompatible-plugin":"^1.0.4"},"_hasShrinkwrap":false,"devDependencies":{"husky":"^8.0.3","react":"^18.2.0","eslint":"^8.44.0","rimraf":"^5.0.1","sanity":"^3.14.1","prettier":"^2.8.8","react-is":"^18.2.0","react-dom":"^18.2.0","typescript":"^5.1.6","lint-staged":"^13.2.3","npm-run-all":"^4.1.5","@types/react":"^18.2.14","autoprefixer":"^10.3.6","babel-eslint":"^10.1.0","@commitlint/cli":"^17.6.6","semantic-release":"^21.0.7","@sanity/pkg-utils":"^2.3.3","styled-components":"^5.3.6","@sanity/plugin-kit":"^3.1.7","eslint-plugin-react":"^7.32.2","eslint-config-sanity":"^6.0.0","eslint-config-prettier":"^8.8.0","eslint-plugin-prettier":"^4.2.1","@typescript-eslint/parser":"^5.61.0","eslint-plugin-react-hooks":"^4.6.0","prettier-plugin-packagejson":"^2.4.4","@commitlint/config-conventional":"^17.6.6","@sanity/semantic-release-preset":"^4.1.1","@typescript-eslint/eslint-plugin":"^5.61.0"},"peerDependencies":{"react":"^18","sanity":"^3"},"sanityExchangeUrl":"https://www.sanity.io/plugins/orderable-document-list","_npmOperationalInternal":{"tmp":"tmp/sanity-plugin-orderable-document-list_1.2.0_1700647031958_0.3859065279063969","host":"s3://npm-registry-packages"}}},"time":{"created":"2023-11-22T09:57:11.958Z","modified":"2025-08-31T17:16:27.535Z","1.0.0":"2023-11-22T08:43:47.648Z","1.2.0":"2023-11-22T09:57:12.163Z"},"bugs":{"url":"https://github.com/sanity-io/orderable-document-list/issues"},"author":{"name":"Sanity.io","email":"hello@sanity.io"},"license":"MIT","homepage":"https://github.com/sanity-io/orderable-document-list#readme","keywords":["sanity","sanity-plugin"],"repository":{"url":"git+ssh://git@github.com/bbihq/sanity-plugin-orderable-document-list.git","type":"git"},"description":"Drag-and-drop Document Ordering without leaving the Editing surface","maintainers":[{"email":"william@bbi.studio","name":"williamli"},{"email":"email@wiiiimm.codes","name":"wiiiimm"}],"readme":"# @sanity/orderable-document-list\n\n> This is a **Sanity Studio v3** plugin.\n> For the v2 version, please refer to the [v2-branch](https://github.com/sanity-io/orderable-document-list/tree/studio-v2).\n\n# What is it?\n\nDrag-and-drop Document Ordering without leaving the Editing surface.\n\n![2022-04-26 12 23 39](https://user-images.githubusercontent.com/9684022/165289621-dbd9d841-028e-40c7-be14-7398fcdb1210.gif)\n\nThis 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`.\n\n## Requirements\n\nA Sanity Studio with [Desk Structure](https://www.sanity.io/docs/structure-builder-introduction) configured:\n\n```ts\nimport {defineConfig} from 'sanity'\nimport {deskTool, StructureBuilder} from 'sanity/desk'\n\nexport default defineConfig({\n  //...\n  plugins: [\n    deskTool({\n      structure: (S, context) => {\n        /* Structure code */\n      },\n    }),\n  ],\n})\n```\n\n## Installation\n\nRun the following command in your studio directory\n\n```sh\nnpm install --save @sanity/orderable-document-list\n```\n\nor\n\n```sh\nyarn add @sanity/orderable-document-list\n```\n\n## Usage\n\n### 1. Import the Document List into your Desk Structure\n\nThe config parameter requires `type`, `S` and `context`. It also accepts `title`, `icon`, `filter` and `params`.\n`S` and `context` are available in desk-tool structure callback, and should be forwarded as is:\n\n```ts\nimport {defineConfig} from 'sanity'\nimport {deskTool, StructureBuilder} from 'sanity/desk'\nimport {orderableDocumentListDeskItem} from '@sanity/orderable-document-list'\n\nexport default defineConfig({\n  //...\n  plugins: [\n    deskTool({\n      structure: (S, context) => {\n        return S.list()\n          .title('Content')\n          .items([\n            // Minimum required configuration\n            orderableDocumentListDeskItem({type: 'category', S, context}),\n\n            // Optional configuration\n            orderableDocumentListDeskItem({\n              type: 'project',\n              title: 'Projects',\n              icon: Paint,\n              // Required if using multiple lists of the same 'type'\n              id: 'orderable-en-projects',\n              // See notes on adding a `filter` below\n              filter: `__i18n_lang == $lang`,\n              params: {\n                lang: 'en_US',\n              },\n              // pass from the structure callback params above\n              S,\n              context,\n            }),\n\n            // ... all other desk items\n          ])\n      },\n    }),\n  ],\n})\n```\n\n**Caution: Adding a `filter`**\n\nBy 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.\n\nHowever, order ranks are still computed based on _all_ documents of the same `type`. Creating multiple lists with different `filter` settings could produce unexpected results.\n\n### 2. Add the `orderRank` field to your schema(s).\n\nYou must pass in the `type` of the schema and the schema `context`, to create an `initialValue` value.\nContext is available in the schema callback, and should be forwarded as is.\n\nAdditionally, pass in overrides for the field, such as making it visible by passing `hidden: false`.\n\nYou cannot override the `name`, `type` or `initialValue` attributes.\n\n```js\n// sanity.config.js\nimport {defineConfig} from \"sanity\";\nimport {deskTool, StructureBuilder} from \"sanity/desk\";\nimport {orderRankField, orderRankOrdering} from '@sanity/orderable-document-list'\n\nexport default defineConfig({\n    //...\n    plugins: [\n        deskTool({structure: (S, context) => {/* snip */}})\n    ],\n    schema: {\n        types: (previousTypes) => {\n            return [\n                ...previousTypes,\n                {\n                    name: \"category\",\n                    title: \"Category\",\n                    type: \"document\",\n                    // Optional: The plugin also exports a set of 'orderings' for use in other Document Lists\n                    // https://www.sanity.io/docs/sort-orders\n                    orderings: [orderRankOrdering],\n                    fields: [\n                        // Minimum required configuration\n                        orderRankField({ type: \"category\" }),\n\n                        // OR you can override _some_ of the field settings\n                        orderRankField({ type: 'category', hidden: false }),\n\n                        // ...all other fields\n                    ],\n                },\n            ]\n        }\n    }\n}\n```\n\n### 3. Generate initial Ranks\n\nOn 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.\nYou can also re-run this at any time.\n\nThe `orderRankField` will query the last Document to set an `initialValue` to come after it.\nNew Documents always start at the end of the Ordered list.\n\n## Querying Ordered Documents\n\nNow when writing a GROQ Query for Documents, use the `orderRank` field value to return ordered results:\n\n```groq\n*[_type == \"category\"]|order(orderRank)\n```\n\nIf fetching documents using [the `document-internationalization` plugin](https://github.com/sanity-io/document-internationalization), you may want to sort by the rank of the base document when the document is not in the base language, so all locales share the same order. When changing the order of documents using this plugin, the `orderRank` field of documents in alternate locales won't be updated. The query below ensures a consistent order for documents in the base language and in alternate languages.\n\n```groq\n*[_type == \"category\" && __i18n_lang == $lang]|order(coalesce(__i18n_base->orderRank, orderRank))\n```\n\n## Notes\n\nTo get this first version out the door there are few configuration settings and a lot of opinions. Such as:\n\n- The `name` of the `orderRank` field is constant\n- The ability to only sort across _all_ Documents of a `type`\n\nFeedback and PRs welcome :)\n\n### Breaking change in the v3 version\n\n`orderableDocumentListDeskItem` requires context from sanity config now.\nSee the examples above.\n\n## How it works\n\nUses [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.\n\nPut simply it updates the position of an individual – or many – Documents in an ordered list without updating any others. It's fast.\n\n## Develop & test\n\nThis plugin uses [@sanity/plugin-kit](https://github.com/sanity-io/plugin-kit)\nwith default configuration for build & watch scripts.\n\nSee [Testing a plugin in Sanity Studio](https://github.com/sanity-io/plugin-kit#testing-a-plugin-in-sanity-studio)\non how to run this plugin with hotreload in the studio.\n\n### Release new version\n\nRun [\"CI & Release\" workflow](https://github.com/sanity-io/orderable-document-list/actions/workflows/main.yml).\nMake sure to select the v3 branch and check \"Release new version\".\n\nSemantic release will only release on configured branches, so it is safe to run release on any branch.\n\n## License\n\n[MIT](LICENSE) © Sanity.io\n","readmeFilename":"README.md"}