sanity-plugin-singleton-management 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 RC Maples
+Copyright (c) 2024 RD Pennell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,193 @@
+[![CI](https://github.com/rcmaples/sanity-plugin-singleton-management/actions/workflows/ci.yml/badge.svg)](https://github.com/rcmaples/sanity-plugin-singleton-management/actions/workflows/ci.yml) [![codecov](https://codecov.io/github/rcmaples/sanity-plugin-singleton-management/graph/badge.svg?token=WYKSA756IY)](https://codecov.io/github/rcmaples/sanity-plugin-singleton-management)
+
+# sanity-plugin-singleton-tools
+
+> This is compatible with v4 and v3 of Sanity Studio.
+
+## What does this plugin do?
+
+This plugin adds convenience functions to reduce the overhead of creating [singleton](https://www.sanity.io/docs/studio/structure-builder-cheat-sheet#k5cd7ca204386) documents in the [Sanity Studio](https://www.sanity.io).
+
+In short, this does the following:
+
+- Limits a singleton document's actions to Publish, Unpublish, and Discard Changes.
+- Removes the ability to create new versions of the singleton document in both the global Create menu and Structure.
+- Adds simple methods for customizing the way your singletons are listed in your Studio's Structure.
+
+## Why Use This Plugin vs. Native Sanity Approaches?
+
+While Sanity Studio supports singleton documents through the Structure Builder API, this
+plugin eliminates the repetitive boilerplate and provides additional safeguards:
+
+### Native Sanity Approach
+```js
+// Requires manual Structure Builder configuration for each singleton
+export const structure = (S) =>
+  S.list()
+    .title('Content')
+    .items([
+      S.listItem()
+        .title('Site Settings')
+        .child(
+          S.document()
+            .schemaType('siteSettings')
+            .documentId('siteSettings')
+        ),
+      // Must manually filter out singletons from main list
+      ...S.documentTypeListItems().filter(listItem =>
+        !['siteSettings'].includes(listItem.getId()))
+    ])
+```
+
+**Issues:**
+
+- Repetitive boilerplate for each singleton
+- No prevention of duplicate document creation
+- Users can still create new versions via global Create menu
+- Manual filtering required to prevent duplicates in document lists
+
+
+**With This Plugin:**
+
+```js
+  // Schema configuration
+  export const siteSettings = {
+    name: 'siteSettings',
+    type: 'document',
+    options: { singleton: true } // That's it!
+  }
+
+  // Structure configuration
+  export const structure = (S, context) =>
+    S.list()
+      .items([
+        ...singletonDocumentListItems({ S, context }), // Auto-generates all singletons
+        ...filteredDocumentListItems({ S, context })   // Auto-filters singletons from main list
+      ])
+```
+
+  Benefits:
+  - ✅ Minimal configuration with `singleton: true`
+  - ✅ Automatic action restrictions (no duplicate creation)
+  - ✅ Global Create menu integration
+  - ✅ Helper functions eliminate boilerplate
+  - ✅ Consistent singleton behavior across your studio
+
+## Installation
+
+```sh
+npm install sanity-plugin-singleton-management
+```
+
+## Migration from sanity-plugin-singleton-tools
+
+This plugin is a modernized, actively maintained fork of `sanity-plugin-singleton-tools` with identical API compatibility. Migration is straightforward:
+
+### Steps
+1. **Uninstall the old package**:
+   ```sh
+   npm uninstall sanity-plugin-singleton-tools
+   ```
+
+2. **Install this package**:
+   ```sh
+   npm install sanity-plugin-singleton-management
+   ```
+
+3. **Update your import statements**:
+   ```diff
+   // sanity.config.js
+   - import { singletonTools } from 'sanity-plugin-singleton-tools'
+   + import { singletonTools } from 'sanity-plugin-singleton-management'
+
+   // structure.js
+   - import { singletonDocumentListItem } from 'sanity-plugin-singleton-tools'
+   + import { singletonDocumentListItem } from 'sanity-plugin-singleton-management'
+   ```
+
+**That's it!** No other code changes are required. Your existing schema configurations and structure customizations will work exactly the same.
+
+### What's New
+- ✅ **React 18/19 Support**: Compatible with modern React versions
+- ✅ **Sanity v3/v4 Support**: Works with both Sanity Studio versions
+- ✅ **Modern Tooling**: ESM/CommonJS dual package, better TypeScript support
+- ✅ **Comprehensive Tests**: 100% test coverage for reliability
+- ✅ **Active Maintenance**: Regular updates and dependency management
+- ✅ **Node 18+ Support**: Modern Node.js compatibility
+
+## Usage
+
+### 1. Add the plugin to your `sanity.config`
+
+```js
+//sanity.config.js
+import { defineConfig } from "sanity";
+import { singletonTools } from "sanity-plugin-singleton-management";
+
+export default defineConfig({
+  //...
+  plugins: [singletonTools()],
+});
+```
+
+### 2. Configure your singleton's schema
+
+```js
+//mySingleton.js
+export const mySingleton = {
+  name: "mySingleton",
+  title: "My Singleton",
+  type: "document",
+  options: {
+    singleton: true, // Identify this document as a singleton
+  },
+};
+```
+
+### 3. Customize how your singleton is shown in your Structure:
+
+```js
+// structure.js
+import {
+  singletonDocumentListItem,
+  singletonDocumentListItems,
+  filteredDocumentListItems,
+} from "sanity-plugin-singleton-management";
+import { PlugIcon } from "@sanity/icons";
+
+export const structure = (S, context) =>
+  S.list()
+    .title("Sanity Love Content")
+    .items([
+      // Create a list item for each singleton document in your schema that links directly to a document view
+      ...singletonDocumentListItems({ S, context }),
+      // Create a list item for a specific singleton
+      singletonDocumentListItem({
+        S,
+        context,
+        // Schema type
+        type: "mySingleton",
+        // Required for showing multiple singletons of the same schema type
+        title: "My Singleton",
+        // Required for showing multiple singletons of the same schema type
+        id: "mySingleton",
+        // Specify a custom icon
+        icon: PlugIcon,
+      }),
+      S.divider(),
+      // Filter singleton documents out of the default S.documentTypeListItems() to prevent them from being rendered as lists or as duplicates
+      ...filteredDocumentListItems({ S, context }),
+    ]);
+```
+
+## Appendix
+
+Other reading (Sanity docs):
+
+- [Singleton documents](https://www.sanity.io/docs/studio/structure-builder-cheat-sheet#k5cd7ca204386)
+- [Filtering out singletons in Structure](https://www.sanity.io/docs/studio/create-a-link-to-a-single-edit-page-in-your-main-document-type-list#fa1e82fd32be)
+- [Creating a link to a single edit page](https://www.sanity.io/docs/studio/create-a-link-to-a-single-edit-page-in-your-main-document-type-list)
+
+## License
+
+[MIT](LICENSE) © RD Pennell & RC Maples

package/dist/index.cjs

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: !0 });
+var sanity = require("sanity"), icons = require("@sanity/icons");
+const getSingletonDocuments = (schema) => {
+  if (schema?._original?.types)
+    return schema._original.types.filter(({ options }) => options?.singleton).map((s) => s.name);
+}, getIsSingleton = (schema, schemaType) => !schema?._original?.types || !schemaType ? !1 : schema._original.types.find(
+  ({ name }) => name === schemaType
+)?.options?.singleton ?? !1, actions = (prev, { schema, schemaType }) => getIsSingleton(schema, schemaType) ? prev.filter(
+  ({ action }) => ["publish", "discardChanges", "restore"].includes(action)
+) : prev, newDocumentOptions = (prev, { schema, creationContext: { type, schemaType } }) => {
+  const singletons = getSingletonDocuments(schema), filterSingletons = ({ templateId }) => !singletons?.includes(templateId);
+  return type === "global" || singletons?.includes(schemaType ?? "") ? prev.filter(filterSingletons) : prev;
+}, singletonTools = sanity.definePlugin(() => ({
+  name: "singleton-tools",
+  document: {
+    newDocumentOptions,
+    actions
+  }
+})), singletonDocumentListItem = (config) => {
+  if (!config?.S || !config?.type || !config.context)
+    throw new Error(
+      "S, context, and type must be provided to singletonDocumentListItem. Example: singletonDocumentListItem({ S, context, type: 'product' })"
+    );
+  const { S, type, title, icon, id, context } = config, { schema } = context;
+  if (!schema)
+    throw new Error(
+      "Schema is required in context for singletonDocumentListItem"
+    );
+  const schemaType = schema.get(type), listTitle = title ?? schemaType?.title ?? type, listIcon = icon ?? schemaType?.icon ?? icons.DocumentIcon, listId = id ?? type;
+  return S.listItem().title(listTitle).icon(listIcon).child(S.document().schemaType(type).title(listTitle).id(listId));
+}, singletonDocumentListItems = (config) => {
+  if (!config.S || !config.context)
+    throw new Error(
+      "S and context must be provided to singletonDocumentListItems. Example: singletonDocumentListItems({ S, context })"
+    );
+  const { S, context } = config, { schema } = context;
+  return getSingletonDocuments(schema)?.map(
+    (schemaType) => singletonDocumentListItem({ S, context, type: schemaType })
+  ) || [];
+}, filteredDocumentListItems = (config) => {
+  if (!config.S || !config.context)
+    throw new Error(
+      "S and context must be provided to filteredDocumentListItems. Example: filteredDocumentListItems({ S, context })"
+    );
+  const { S, context } = config, { schema } = context, singletons = getSingletonDocuments(schema);
+  return S.documentTypeListItems().filter(
+    (type) => !singletons || !singletons.includes(type.getId())
+  );
+};
+exports.filteredDocumentListItems = filteredDocumentListItems;
+exports.singletonDocumentListItem = singletonDocumentListItem;
+exports.singletonDocumentListItems = singletonDocumentListItems;
+exports.singletonTools = singletonTools;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/helpers/index.ts","../src/actions.ts","../src/newDocumentOptions.ts","../src/pluginConfig.ts","../src/structure/index.ts"],"sourcesContent":["import { Schema } from \"sanity\";\n\nimport { SingletonPluginOptions } from \"../types\";\n\nexport const getSingletonDocuments = (schema: Schema): string[] | undefined => {\n  if (!schema?._original?.types) {\n    return undefined;\n  }\n\n  return schema._original.types\n    .filter(({ options }) => (options as SingletonPluginOptions)?.singleton)\n    .map((s: { name: string }) => s.name);\n};\n\nexport const getIsSingleton = (schema: Schema, schemaType: string): boolean => {\n  if (!schema?._original?.types || !schemaType) {\n    return false;\n  }\n\n  const documentSchema = schema._original.types.find(\n    ({ name }) => name === schemaType,\n  );\n\n  return (\n    (documentSchema?.options as SingletonPluginOptions)?.singleton ?? false\n  );\n};\n","import { DocumentActionsContext, DocumentActionsResolver } from \"sanity\";\n\nimport { getIsSingleton } from \"./helpers\";\n\nexport const actions: DocumentActionsResolver = (\n  prev,\n  { schema, schemaType }: DocumentActionsContext,\n) => {\n  return getIsSingleton(schema, schemaType)\n    ? prev.filter(({ action }) =>\n        [\"publish\", \"discardChanges\", \"restore\"].includes(action as string),\n      )\n    : prev;\n};\n","import { NewDocumentOptionsContext, NewDocumentOptionsResolver } from \"sanity\";\n\nimport { getSingletonDocuments } from \"./helpers\";\n\nexport const newDocumentOptions: NewDocumentOptionsResolver = (\n  prev,\n  { schema, creationContext: { type, schemaType } }: NewDocumentOptionsContext,\n) => {\n  const singletons = getSingletonDocuments(schema);\n\n  const filterSingletons = ({ templateId }: { templateId: string }) =>\n    !singletons?.includes(templateId);\n\n  if (type === \"global\") return prev.filter(filterSingletons);\n\n  return singletons?.includes(schemaType ?? \"\")\n    ? prev.filter(filterSingletons)\n    : prev;\n};\n","import { definePlugin } from \"sanity\";\n\nimport { actions } from \"./actions\";\nimport { newDocumentOptions } from \"./newDocumentOptions\";\n\nexport const singletonTools = definePlugin(() => {\n  return {\n    name: \"singleton-tools\",\n    document: {\n      newDocumentOptions,\n      actions,\n    },\n  };\n});\n","import { DocumentIcon } from \"@sanity/icons\";\nimport type { ListItemBuilder } from \"sanity/structure\";\n\nimport { getSingletonDocuments } from \"../helpers\";\nimport {\n  SingletonDocumentListItemConfig,\n  SingletonPluginListItemsConfig,\n} from \"../types\";\n\nconst singletonDocumentListItem = (\n  config: SingletonDocumentListItemConfig,\n): ListItemBuilder => {\n  if (!config?.S || !config?.type || !config.context) {\n    throw new Error(\n      \"S, context, and type must be provided to singletonDocumentListItem. \" +\n        \"Example: singletonDocumentListItem({ S, context, type: 'product' })\",\n    );\n  }\n  const { S, type, title, icon, id, context } = config;\n  const { schema } = context;\n\n  if (!schema) {\n    throw new Error(\n      \"Schema is required in context for singletonDocumentListItem\",\n    );\n  }\n\n  const schemaType = schema.get(type);\n  const listTitle = title ?? schemaType?.title ?? type;\n  const listIcon = icon ?? schemaType?.icon ?? DocumentIcon;\n  const listId = id ?? type;\n\n  return S.listItem()\n    .title(listTitle)\n    .icon(listIcon)\n    .child(S.document().schemaType(type).title(listTitle).id(listId));\n};\n\nconst singletonDocumentListItems = (\n  config: SingletonPluginListItemsConfig,\n): ListItemBuilder[] => {\n  if (!config.S || !config.context) {\n    throw new Error(\n      \"S and context must be provided to singletonDocumentListItems. \" +\n        \"Example: singletonDocumentListItems({ S, context })\",\n    );\n  }\n\n  const { S, context } = config;\n  const { schema } = context;\n\n  const singletons = getSingletonDocuments(schema);\n\n  return (\n    singletons?.map((schemaType) =>\n      singletonDocumentListItem({ S, context, type: schemaType }),\n    ) || []\n  );\n};\n\nconst filteredDocumentListItems = (\n  config: SingletonPluginListItemsConfig,\n): ListItemBuilder[] => {\n  if (!config.S || !config.context) {\n    throw new Error(\n      \"S and context must be provided to filteredDocumentListItems. \" +\n        \"Example: filteredDocumentListItems({ S, context })\",\n    );\n  }\n  const { S, context } = config;\n  const { schema } = context;\n\n  const singletons = getSingletonDocuments(schema);\n\n  return S.documentTypeListItems().filter(\n    (type) => !singletons || !singletons.includes(type.getId() as string),\n  );\n};\n\nexport {\n  filteredDocumentListItems,\n  singletonDocumentListItem,\n  singletonDocumentListItems,\n};\n"],"names":["definePlugin","DocumentIcon"],"mappings":";;;AAIO,MAAM,wBAAwB,CAAC,WAAyC;AAC7E,MAAK,QAAQ,WAAW;AAIxB,WAAO,OAAO,UAAU,MACrB,OAAO,CAAC,EAAE,QAAA,MAAe,SAAoC,SAAS,EACtE,IAAI,CAAC,MAAwB,EAAE,IAAI;AACxC,GAEa,iBAAiB,CAAC,QAAgB,eACzC,CAAC,QAAQ,WAAW,SAAS,CAAC,aACzB,KAGc,OAAO,UAAU,MAAM;AAAA,EAC5C,CAAC,EAAE,KAAA,MAAW,SAAS;AACzB,GAGmB,SAAoC,aAAa,ICpBzD,UAAmC,CAC9C,MACA,EAAE,QAAQ,WAAA,MAEH,eAAe,QAAQ,UAAU,IACpC,KAAK;AAAA,EAAO,CAAC,EAAE,OAAA,MACb,CAAC,WAAW,kBAAkB,SAAS,EAAE,SAAS,MAAgB;AACpE,IACA,MCRO,qBAAiD,CAC5D,MACA,EAAE,QAAQ,iBAAiB,EAAE,MAAM,WAAA,QAChC;AACH,QAAM,aAAa,sBAAsB,MAAM,GAEzC,mBAAmB,CAAC,EAAE,iBAC1B,CAAC,YAAY,SAAS,UAAU;AAElC,SAAI,SAAS,YAEN,YAAY,SAAS,cAAc,EAAE,IAFd,KAAK,OAAO,gBAAgB,IAItD;AACN,GCba,iBAAiBA,OAAAA,aAAa,OAClC;AAAA,EACL,MAAM;AAAA,EACN,UAAU;AAAA,IACR;AAAA,IACA;AAAA,EAAA;AAEJ,EACD,GCJK,4BAA4B,CAChC,WACoB;AACpB,MAAI,CAAC,QAAQ,KAAK,CAAC,QAAQ,QAAQ,CAAC,OAAO;AACzC,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAIJ,QAAM,EAAE,GAAG,MAAM,OAAO,MAAM,IAAI,YAAY,QACxC,EAAE,OAAA,IAAW;AAEnB,MAAI,CAAC;AACH,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAIJ,QAAM,aAAa,OAAO,IAAI,IAAI,GAC5B,YAAY,SAAS,YAAY,SAAS,MAC1C,WAAW,QAAQ,YAAY,QAAQC,oBACvC,SAAS,MAAM;AAErB,SAAO,EAAE,WACN,MAAM,SAAS,EACf,KAAK,QAAQ,EACb,MAAM,EAAE,SAAA,EAAW,WAAW,IAAI,EAAE,MAAM,SAAS,EAAE,GAAG,MAAM,CAAC;AACpE,GAEM,6BAA6B,CACjC,WACsB;AACtB,MAAI,CAAC,OAAO,KAAK,CAAC,OAAO;AACvB,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAKJ,QAAM,EAAE,GAAG,QAAA,IAAY,QACjB,EAAE,WAAW;AAInB,SAFmB,sBAAsB,MAAM,GAGjC;AAAA,IAAI,CAAC,eACf,0BAA0B,EAAE,GAAG,SAAS,MAAM,YAAY;AAAA,EAAA,KACvD,CAAA;AAET,GAEM,4BAA4B,CAChC,WACsB;AACtB,MAAI,CAAC,OAAO,KAAK,CAAC,OAAO;AACvB,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAIJ,QAAM,EAAE,GAAG,QAAA,IAAY,QACjB,EAAE,OAAA,IAAW,SAEb,aAAa,sBAAsB,MAAM;AAE/C,SAAO,EAAE,wBAAwB;AAAA,IAC/B,CAAC,SAAS,CAAC,cAAc,CAAC,WAAW,SAAS,KAAK,MAAA,CAAiB;AAAA,EAAA;AAExE;;;;;"}

package/dist/index.d.cts

@@ -0,0 +1,40 @@
+import { ComponentType } from "react";
+import { ConfigContext } from "sanity";
+import type { ListItemBuilder } from "sanity/structure";
+import { Plugin as Plugin_2 } from "sanity";
+import { ReactNode } from "react";
+import { StructureBuilder } from "sanity/structure";
+
+export declare const filteredDocumentListItems: (
+  config: SingletonPluginListItemsConfig,
+) => ListItemBuilder[];
+
+export declare const singletonDocumentListItem: (
+  config: SingletonDocumentListItemConfig,
+) => ListItemBuilder;
+
+declare interface SingletonDocumentListItemConfig {
+  S: StructureBuilder;
+  context: ConfigContext;
+  type: string;
+  title?: string;
+  id?: string;
+  icon?: ComponentType | ReactNode;
+}
+
+export declare const singletonDocumentListItems: (
+  config: SingletonPluginListItemsConfig,
+) => ListItemBuilder[];
+
+declare interface SingletonPluginListItemsConfig {
+  S: StructureBuilder;
+  context: ConfigContext;
+}
+
+export declare const singletonTools: Plugin_2<void>;
+
+export {};
+
+declare module "sanity" {
+  interface DocumentOptions extends SingletonPluginOptions {}
+}

package/dist/index.esm.d.ts

@@ -0,0 +1,40 @@
+import { ComponentType } from "react";
+import { ConfigContext } from "sanity";
+import type { ListItemBuilder } from "sanity/structure";
+import { Plugin as Plugin_2 } from "sanity";
+import { ReactNode } from "react";
+import { StructureBuilder } from "sanity/structure";
+
+export declare const filteredDocumentListItems: (
+  config: SingletonPluginListItemsConfig,
+) => ListItemBuilder[];
+
+export declare const singletonDocumentListItem: (
+  config: SingletonDocumentListItemConfig,
+) => ListItemBuilder;
+
+declare interface SingletonDocumentListItemConfig {
+  S: StructureBuilder;
+  context: ConfigContext;
+  type: string;
+  title?: string;
+  id?: string;
+  icon?: ComponentType | ReactNode;
+}
+
+export declare const singletonDocumentListItems: (
+  config: SingletonPluginListItemsConfig,
+) => ListItemBuilder[];
+
+declare interface SingletonPluginListItemsConfig {
+  S: StructureBuilder;
+  context: ConfigContext;
+}
+
+export declare const singletonTools: Plugin_2<void>;
+
+export {};
+
+declare module "sanity" {
+  interface DocumentOptions extends SingletonPluginOptions {}
+}

package/dist/index.esm.js

@@ -0,0 +1,56 @@
+import { definePlugin } from "sanity";
+import { DocumentIcon } from "@sanity/icons";
+const getSingletonDocuments = (schema) => {
+  if (schema?._original?.types)
+    return schema._original.types.filter(({ options }) => options?.singleton).map((s) => s.name);
+}, getIsSingleton = (schema, schemaType) => !schema?._original?.types || !schemaType ? !1 : schema._original.types.find(
+  ({ name }) => name === schemaType
+)?.options?.singleton ?? !1, actions = (prev, { schema, schemaType }) => getIsSingleton(schema, schemaType) ? prev.filter(
+  ({ action }) => ["publish", "discardChanges", "restore"].includes(action)
+) : prev, newDocumentOptions = (prev, { schema, creationContext: { type, schemaType } }) => {
+  const singletons = getSingletonDocuments(schema), filterSingletons = ({ templateId }) => !singletons?.includes(templateId);
+  return type === "global" || singletons?.includes(schemaType ?? "") ? prev.filter(filterSingletons) : prev;
+}, singletonTools = definePlugin(() => ({
+  name: "singleton-tools",
+  document: {
+    newDocumentOptions,
+    actions
+  }
+})), singletonDocumentListItem = (config) => {
+  if (!config?.S || !config?.type || !config.context)
+    throw new Error(
+      "S, context, and type must be provided to singletonDocumentListItem. Example: singletonDocumentListItem({ S, context, type: 'product' })"
+    );
+  const { S, type, title, icon, id, context } = config, { schema } = context;
+  if (!schema)
+    throw new Error(
+      "Schema is required in context for singletonDocumentListItem"
+    );
+  const schemaType = schema.get(type), listTitle = title ?? schemaType?.title ?? type, listIcon = icon ?? schemaType?.icon ?? DocumentIcon, listId = id ?? type;
+  return S.listItem().title(listTitle).icon(listIcon).child(S.document().schemaType(type).title(listTitle).id(listId));
+}, singletonDocumentListItems = (config) => {
+  if (!config.S || !config.context)
+    throw new Error(
+      "S and context must be provided to singletonDocumentListItems. Example: singletonDocumentListItems({ S, context })"
+    );
+  const { S, context } = config, { schema } = context;
+  return getSingletonDocuments(schema)?.map(
+    (schemaType) => singletonDocumentListItem({ S, context, type: schemaType })
+  ) || [];
+}, filteredDocumentListItems = (config) => {
+  if (!config.S || !config.context)
+    throw new Error(
+      "S and context must be provided to filteredDocumentListItems. Example: filteredDocumentListItems({ S, context })"
+    );
+  const { S, context } = config, { schema } = context, singletons = getSingletonDocuments(schema);
+  return S.documentTypeListItems().filter(
+    (type) => !singletons || !singletons.includes(type.getId())
+  );
+};
+export {
+  filteredDocumentListItems,
+  singletonDocumentListItem,
+  singletonDocumentListItems,
+  singletonTools
+};
+//# sourceMappingURL=index.esm.js.map

package/dist/index.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.esm.js","sources":["../src/helpers/index.ts","../src/actions.ts","../src/newDocumentOptions.ts","../src/pluginConfig.ts","../src/structure/index.ts"],"sourcesContent":["import { Schema } from \"sanity\";\n\nimport { SingletonPluginOptions } from \"../types\";\n\nexport const getSingletonDocuments = (schema: Schema): string[] | undefined => {\n  if (!schema?._original?.types) {\n    return undefined;\n  }\n\n  return schema._original.types\n    .filter(({ options }) => (options as SingletonPluginOptions)?.singleton)\n    .map((s: { name: string }) => s.name);\n};\n\nexport const getIsSingleton = (schema: Schema, schemaType: string): boolean => {\n  if (!schema?._original?.types || !schemaType) {\n    return false;\n  }\n\n  const documentSchema = schema._original.types.find(\n    ({ name }) => name === schemaType,\n  );\n\n  return (\n    (documentSchema?.options as SingletonPluginOptions)?.singleton ?? false\n  );\n};\n","import { DocumentActionsContext, DocumentActionsResolver } from \"sanity\";\n\nimport { getIsSingleton } from \"./helpers\";\n\nexport const actions: DocumentActionsResolver = (\n  prev,\n  { schema, schemaType }: DocumentActionsContext,\n) => {\n  return getIsSingleton(schema, schemaType)\n    ? prev.filter(({ action }) =>\n        [\"publish\", \"discardChanges\", \"restore\"].includes(action as string),\n      )\n    : prev;\n};\n","import { NewDocumentOptionsContext, NewDocumentOptionsResolver } from \"sanity\";\n\nimport { getSingletonDocuments } from \"./helpers\";\n\nexport const newDocumentOptions: NewDocumentOptionsResolver = (\n  prev,\n  { schema, creationContext: { type, schemaType } }: NewDocumentOptionsContext,\n) => {\n  const singletons = getSingletonDocuments(schema);\n\n  const filterSingletons = ({ templateId }: { templateId: string }) =>\n    !singletons?.includes(templateId);\n\n  if (type === \"global\") return prev.filter(filterSingletons);\n\n  return singletons?.includes(schemaType ?? \"\")\n    ? prev.filter(filterSingletons)\n    : prev;\n};\n","import { definePlugin } from \"sanity\";\n\nimport { actions } from \"./actions\";\nimport { newDocumentOptions } from \"./newDocumentOptions\";\n\nexport const singletonTools = definePlugin(() => {\n  return {\n    name: \"singleton-tools\",\n    document: {\n      newDocumentOptions,\n      actions,\n    },\n  };\n});\n","import { DocumentIcon } from \"@sanity/icons\";\nimport type { ListItemBuilder } from \"sanity/structure\";\n\nimport { getSingletonDocuments } from \"../helpers\";\nimport {\n  SingletonDocumentListItemConfig,\n  SingletonPluginListItemsConfig,\n} from \"../types\";\n\nconst singletonDocumentListItem = (\n  config: SingletonDocumentListItemConfig,\n): ListItemBuilder => {\n  if (!config?.S || !config?.type || !config.context) {\n    throw new Error(\n      \"S, context, and type must be provided to singletonDocumentListItem. \" +\n        \"Example: singletonDocumentListItem({ S, context, type: 'product' })\",\n    );\n  }\n  const { S, type, title, icon, id, context } = config;\n  const { schema } = context;\n\n  if (!schema) {\n    throw new Error(\n      \"Schema is required in context for singletonDocumentListItem\",\n    );\n  }\n\n  const schemaType = schema.get(type);\n  const listTitle = title ?? schemaType?.title ?? type;\n  const listIcon = icon ?? schemaType?.icon ?? DocumentIcon;\n  const listId = id ?? type;\n\n  return S.listItem()\n    .title(listTitle)\n    .icon(listIcon)\n    .child(S.document().schemaType(type).title(listTitle).id(listId));\n};\n\nconst singletonDocumentListItems = (\n  config: SingletonPluginListItemsConfig,\n): ListItemBuilder[] => {\n  if (!config.S || !config.context) {\n    throw new Error(\n      \"S and context must be provided to singletonDocumentListItems. \" +\n        \"Example: singletonDocumentListItems({ S, context })\",\n    );\n  }\n\n  const { S, context } = config;\n  const { schema } = context;\n\n  const singletons = getSingletonDocuments(schema);\n\n  return (\n    singletons?.map((schemaType) =>\n      singletonDocumentListItem({ S, context, type: schemaType }),\n    ) || []\n  );\n};\n\nconst filteredDocumentListItems = (\n  config: SingletonPluginListItemsConfig,\n): ListItemBuilder[] => {\n  if (!config.S || !config.context) {\n    throw new Error(\n      \"S and context must be provided to filteredDocumentListItems. \" +\n        \"Example: filteredDocumentListItems({ S, context })\",\n    );\n  }\n  const { S, context } = config;\n  const { schema } = context;\n\n  const singletons = getSingletonDocuments(schema);\n\n  return S.documentTypeListItems().filter(\n    (type) => !singletons || !singletons.includes(type.getId() as string),\n  );\n};\n\nexport {\n  filteredDocumentListItems,\n  singletonDocumentListItem,\n  singletonDocumentListItems,\n};\n"],"names":[],"mappings":";;AAIO,MAAM,wBAAwB,CAAC,WAAyC;AAC7E,MAAK,QAAQ,WAAW;AAIxB,WAAO,OAAO,UAAU,MACrB,OAAO,CAAC,EAAE,QAAA,MAAe,SAAoC,SAAS,EACtE,IAAI,CAAC,MAAwB,EAAE,IAAI;AACxC,GAEa,iBAAiB,CAAC,QAAgB,eACzC,CAAC,QAAQ,WAAW,SAAS,CAAC,aACzB,KAGc,OAAO,UAAU,MAAM;AAAA,EAC5C,CAAC,EAAE,KAAA,MAAW,SAAS;AACzB,GAGmB,SAAoC,aAAa,ICpBzD,UAAmC,CAC9C,MACA,EAAE,QAAQ,WAAA,MAEH,eAAe,QAAQ,UAAU,IACpC,KAAK;AAAA,EAAO,CAAC,EAAE,OAAA,MACb,CAAC,WAAW,kBAAkB,SAAS,EAAE,SAAS,MAAgB;AACpE,IACA,MCRO,qBAAiD,CAC5D,MACA,EAAE,QAAQ,iBAAiB,EAAE,MAAM,WAAA,QAChC;AACH,QAAM,aAAa,sBAAsB,MAAM,GAEzC,mBAAmB,CAAC,EAAE,iBAC1B,CAAC,YAAY,SAAS,UAAU;AAElC,SAAI,SAAS,YAEN,YAAY,SAAS,cAAc,EAAE,IAFd,KAAK,OAAO,gBAAgB,IAItD;AACN,GCba,iBAAiB,aAAa,OAClC;AAAA,EACL,MAAM;AAAA,EACN,UAAU;AAAA,IACR;AAAA,IACA;AAAA,EAAA;AAEJ,EACD,GCJK,4BAA4B,CAChC,WACoB;AACpB,MAAI,CAAC,QAAQ,KAAK,CAAC,QAAQ,QAAQ,CAAC,OAAO;AACzC,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAIJ,QAAM,EAAE,GAAG,MAAM,OAAO,MAAM,IAAI,YAAY,QACxC,EAAE,OAAA,IAAW;AAEnB,MAAI,CAAC;AACH,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAIJ,QAAM,aAAa,OAAO,IAAI,IAAI,GAC5B,YAAY,SAAS,YAAY,SAAS,MAC1C,WAAW,QAAQ,YAAY,QAAQ,cACvC,SAAS,MAAM;AAErB,SAAO,EAAE,WACN,MAAM,SAAS,EACf,KAAK,QAAQ,EACb,MAAM,EAAE,SAAA,EAAW,WAAW,IAAI,EAAE,MAAM,SAAS,EAAE,GAAG,MAAM,CAAC;AACpE,GAEM,6BAA6B,CACjC,WACsB;AACtB,MAAI,CAAC,OAAO,KAAK,CAAC,OAAO;AACvB,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAKJ,QAAM,EAAE,GAAG,QAAA,IAAY,QACjB,EAAE,WAAW;AAInB,SAFmB,sBAAsB,MAAM,GAGjC;AAAA,IAAI,CAAC,eACf,0BAA0B,EAAE,GAAG,SAAS,MAAM,YAAY;AAAA,EAAA,KACvD,CAAA;AAET,GAEM,4BAA4B,CAChC,WACsB;AACtB,MAAI,CAAC,OAAO,KAAK,CAAC,OAAO;AACvB,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAIJ,QAAM,EAAE,GAAG,QAAA,IAAY,QACjB,EAAE,OAAA,IAAW,SAEb,aAAa,sBAAsB,MAAM;AAE/C,SAAO,EAAE,wBAAwB;AAAA,IAC/B,CAAC,SAAS,CAAC,cAAc,CAAC,WAAW,SAAS,KAAK,MAAA,CAAiB;AAAA,EAAA;AAExE;"}

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "sanity-plugin-singleton-management",
+  "version": "1.0.0",
+  "description": "A plugin to streamline singleton management in your Sanity Studio",
+  "keywords": [
+    "sanity",
+    "sanity-plugin"
+  ],
+  "license": "MIT",
+  "author": "RD Pennell <racheal@sanity.io> & RC Maples <rc@rcmaples.io>",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.esm.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.esm.js",
+  "types": "./dist/index.d.ts",
+  "browserslist": "extends @sanity/browserslist-config",
+  "files": [
+    "dist",
+    "sanity.json",
+    "src",
+    "v2-incompatible.js",
+    "!src/__tests__",
+    "!src/__mocks__"
+  ],
+  "scripts": {
+    "build": "npm run clean && npx @sanity/pkg-utils build --strict",
+    "clean": "rimraf dist",
+    "format": "prettier --write --cache --ignore-unknown .",
+    "link-watch": "plugin-kit link-watch",
+    "lint": "eslint .",
+    "prepare": "husky",
+    "prepublishOnly": "run-s build",
+    "watch": "pkg-utils watch --strict",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@sanity/icons": "^3.7.4",
+    "@sanity/incompatible-plugin": "^1.0.4"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.8.1",
+    "@commitlint/config-conventional": "^19.8.1",
+    "@sanity/browserslist-config": "^1.0.5",
+    "@sanity/pkg-utils": "^8.1.12",
+    "@sanity/plugin-kit": "^4.0.19",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.6",
+    "@semantic-release/npm": "^12.0.2",
+    "@testing-library/jest-dom": "^6.4.6",
+    "@types/react": "^19.1.13",
+    "@typescript-eslint/eslint-plugin": "^8.44.0",
+    "@typescript-eslint/parser": "^8.44.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "eslint": "^9.35.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-config-sanity": "^7.1.1",
+    "eslint-plugin-prettier": "^5.1.3",
+    "eslint-plugin-react": "^7.34.0",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "husky": "^9.1.7",
+    "jsdom": "^27.0.0",
+    "npm-run-all": "^4.1.5",
+    "prettier": "^3.2.5",
+    "prettier-plugin-packagejson": "^2.4.12",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "react-is": "^19.1.1",
+    "rimraf": "^6.0.1",
+    "sanity": "^4.9.0",
+    "semantic-release": "^24.2.8",
+    "styled-components": "^6.1.15",
+    "typescript": "^5.3.3",
+    "typescript-eslint": "^8.44.0",
+    "vitest": "^3.2.4"
+  },
+  "overrides": {
+    "esbuild": "0.25.0",
+    "prismjs": "1.30.0",
+    "tmp": "0.2.4"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19",
+    "sanity": "^3 || ^4"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rcmaples/sanity-plugin-singleton-management"
+  },
+  "sideEffects": true
+}

package/sanity.json

@@ -0,0 +1,8 @@
+{
+  "parts": [
+    {
+      "implements": "part:@sanity/base/sanity-root",
+      "path": "./v2-incompatible.js"
+    }
+  ]
+}

package/src/actions.ts

@@ -0,0 +1,14 @@
+import { DocumentActionsContext, DocumentActionsResolver } from "sanity";
+
+import { getIsSingleton } from "./helpers";
+
+export const actions: DocumentActionsResolver = (
+  prev,
+  { schema, schemaType }: DocumentActionsContext,
+) => {
+  return getIsSingleton(schema, schemaType)
+    ? prev.filter(({ action }) =>
+        ["publish", "discardChanges", "restore"].includes(action as string),
+      )
+    : prev;
+};

package/src/helpers/index.ts

@@ -0,0 +1,27 @@
+import { Schema } from "sanity";
+
+import { SingletonPluginOptions } from "../types";
+
+export const getSingletonDocuments = (schema: Schema): string[] | undefined => {
+  if (!schema?._original?.types) {
+    return undefined;
+  }
+
+  return schema._original.types
+    .filter(({ options }) => (options as SingletonPluginOptions)?.singleton)
+    .map((s: { name: string }) => s.name);
+};
+
+export const getIsSingleton = (schema: Schema, schemaType: string): boolean => {
+  if (!schema?._original?.types || !schemaType) {
+    return false;
+  }
+
+  const documentSchema = schema._original.types.find(
+    ({ name }) => name === schemaType,
+  );
+
+  return (
+    (documentSchema?.options as SingletonPluginOptions)?.singleton ?? false
+  );
+};

package/src/index.ts

@@ -0,0 +1,13 @@
+import { singletonTools } from "./pluginConfig";
+import {
+  filteredDocumentListItems,
+  singletonDocumentListItem,
+  singletonDocumentListItems,
+} from "./structure";
+
+export {
+  filteredDocumentListItems,
+  singletonDocumentListItem,
+  singletonDocumentListItems,
+  singletonTools,
+};

package/src/newDocumentOptions.ts

@@ -0,0 +1,19 @@
+import { NewDocumentOptionsContext, NewDocumentOptionsResolver } from "sanity";
+
+import { getSingletonDocuments } from "./helpers";
+
+export const newDocumentOptions: NewDocumentOptionsResolver = (
+  prev,
+  { schema, creationContext: { type, schemaType } }: NewDocumentOptionsContext,
+) => {
+  const singletons = getSingletonDocuments(schema);
+
+  const filterSingletons = ({ templateId }: { templateId: string }) =>
+    !singletons?.includes(templateId);
+
+  if (type === "global") return prev.filter(filterSingletons);
+
+  return singletons?.includes(schemaType ?? "")
+    ? prev.filter(filterSingletons)
+    : prev;
+};

package/src/pluginConfig.ts

@@ -0,0 +1,14 @@
+import { definePlugin } from "sanity";
+
+import { actions } from "./actions";
+import { newDocumentOptions } from "./newDocumentOptions";
+
+export const singletonTools = definePlugin(() => {
+  return {
+    name: "singleton-tools",
+    document: {
+      newDocumentOptions,
+      actions,
+    },
+  };
+});

package/src/structure/index.ts

@@ -0,0 +1,84 @@
+import { DocumentIcon } from "@sanity/icons";
+import type { ListItemBuilder } from "sanity/structure";
+
+import { getSingletonDocuments } from "../helpers";
+import {
+  SingletonDocumentListItemConfig,
+  SingletonPluginListItemsConfig,
+} from "../types";
+
+const singletonDocumentListItem = (
+  config: SingletonDocumentListItemConfig,
+): ListItemBuilder => {
+  if (!config?.S || !config?.type || !config.context) {
+    throw new Error(
+      "S, context, and type must be provided to singletonDocumentListItem. " +
+        "Example: singletonDocumentListItem({ S, context, type: 'product' })",
+    );
+  }
+  const { S, type, title, icon, id, context } = config;
+  const { schema } = context;
+
+  if (!schema) {
+    throw new Error(
+      "Schema is required in context for singletonDocumentListItem",
+    );
+  }
+
+  const schemaType = schema.get(type);
+  const listTitle = title ?? schemaType?.title ?? type;
+  const listIcon = icon ?? schemaType?.icon ?? DocumentIcon;
+  const listId = id ?? type;
+
+  return S.listItem()
+    .title(listTitle)
+    .icon(listIcon)
+    .child(S.document().schemaType(type).title(listTitle).id(listId));
+};
+
+const singletonDocumentListItems = (
+  config: SingletonPluginListItemsConfig,
+): ListItemBuilder[] => {
+  if (!config.S || !config.context) {
+    throw new Error(
+      "S and context must be provided to singletonDocumentListItems. " +
+        "Example: singletonDocumentListItems({ S, context })",
+    );
+  }
+
+  const { S, context } = config;
+  const { schema } = context;
+
+  const singletons = getSingletonDocuments(schema);
+
+  return (
+    singletons?.map((schemaType) =>
+      singletonDocumentListItem({ S, context, type: schemaType }),
+    ) || []
+  );
+};
+
+const filteredDocumentListItems = (
+  config: SingletonPluginListItemsConfig,
+): ListItemBuilder[] => {
+  if (!config.S || !config.context) {
+    throw new Error(
+      "S and context must be provided to filteredDocumentListItems. " +
+        "Example: filteredDocumentListItems({ S, context })",
+    );
+  }
+  const { S, context } = config;
+  const { schema } = context;
+
+  const singletons = getSingletonDocuments(schema);
+
+  return S.documentTypeListItems().filter(
+    (type) => !singletons || !singletons.includes(type.getId() as string),
+  );
+};
+
+export {
+  filteredDocumentListItems,
+  singletonDocumentListItem,
+  singletonDocumentListItems,
+};

package/src/types.ts

@@ -0,0 +1,32 @@
+import { ComponentType, ReactNode } from "react";
+import { ConfigContext, SanityDocument } from "sanity";
+import { StructureBuilder } from "sanity/structure";
+
+export interface SingletonDocumentListItemConfig {
+  S: StructureBuilder;
+  context: ConfigContext;
+  type: string;
+  title?: string;
+  id?: string;
+  icon?: ComponentType | ReactNode;
+}
+
+export interface SingletonPluginListItemsConfig {
+  S: StructureBuilder;
+  context: ConfigContext;
+}
+
+export interface SingletonPluginOptions {
+  singleton?: boolean;
+}
+
+export interface SanitySingletonDocument extends SanityDocument {
+  options?: {
+    singleton?: boolean;
+  };
+}
+
+declare module "sanity" {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface DocumentOptions extends SingletonPluginOptions {}
+}

package/v2-incompatible.js

@@ -0,0 +1,9 @@
+import { showIncompatiblePluginDialog } from "@sanity/incompatible-plugin";
+
+export default showIncompatiblePluginDialog({
+  name: "sanity-plugin-singleton-management",
+  versions: {
+    v3: "0.1.0",
+    v2: undefined,
+  },
+});