@driftime/sanity-plugin-handbook 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,143 @@
+import type { ComponentType } from "react";
+import type { CurrentUser } from "sanity";
+import type { DocumentDefinition } from "sanity";
+import { ListItemBuilder } from "sanity/structure";
+import { PluginOptions } from "sanity";
+import type { PortableTextBlock } from "sanity";
+import type { PortableTextObject } from "sanity";
+import type { SanityDocument } from "sanity";
+import type { SchemaTypeDefinition } from "sanity";
+import type { StructureBuilder } from "sanity/structure";
+
+/** @public */
+export declare interface HandbookBlockDefinition {
+  /** Sanity schema type definition for the custom block. */
+  schema: SchemaTypeDefinition;
+  /** React component for rendering the block in the Handbook viewer. */
+  component: ComponentType<{
+    value: PortableTextObject;
+  }>;
+}
+
+/** @public */
+export declare interface HandbookConfig {
+  /** Title shown in the Studio tool navigation. */
+  title?: string;
+  /** Heading displayed at the top of the sidebar. */
+  sidebarTitle?: string;
+  /** Document type groups defining the hierarchy. */
+  groups?: HandbookStructureGroup[];
+  /** Custom Portable Text block definitions for guide content. */
+  blocks?: HandbookBlockDefinition[];
+  /** Email addresses permitted to edit handbook documents. */
+  editors?: string[];
+  /** Fallback message shown when a field has no description. */
+  undocumentedFieldMessage?: string;
+}
+
+/** @public */
+export declare interface HandbookGuideGroup {
+  /** Unique key assigned by Sanity for this array item. */
+  _key: string;
+  /** Display title for this group in the sidebar. */
+  title: string;
+  /** Ordered array of guide references. */
+  guides: SanityHandbookGuide[];
+}
+
+/** @public */
+export declare interface HandbookMetadata {
+  /** Display title override for the field or document. */
+  title?: string;
+  /** Description shown beneath the field or document heading. */
+  description?: string;
+  /** Illustrative example value for the field. */
+  example?: string;
+  /** Helpful tip displayed as a popover hint. */
+  tip?: string;
+  /** Informational note displayed as a popover hint. */
+  info?: string;
+  /** Warning displayed as a popover hint. */
+  caution?: string;
+}
+
+/**
+ * Creates a Handbook tool for Sanity Studio, providing auto-generated documentation
+ * for document types and Portable Text guides within the Studio interface.
+ *
+ * @public
+ * @param config - Optional plugin configuration.
+ * @returns Sanity plugin definition.
+ */
+export declare function handbookPlugin(config?: HandbookConfig): PluginOptions;
+
+/**
+ * Creates Structure tool items for handbook documents.
+ * Returns an empty array if the current user is not in the editors list
+ * configured via handbookPlugin.
+ *
+ * @public
+ * @param structureBuilder - The Sanity Structure builder instance.
+ * @param context - The Structure context containing the current user.
+ * @returns An array of list items for the handbook singleton and guides list.
+ */
+export declare function handbookStructure(
+  structureBuilder: StructureBuilder,
+  context: {
+    currentUser: CurrentUser | null;
+  },
+): ListItemBuilder[];
+
+/** @public */
+export declare interface HandbookStructureGroup {
+  /** Display title for the document type group. */
+  title: string;
+  /** Brief description of the group's purpose. */
+  description?: string;
+  /** Document definitions belonging to this group. */
+  documents: DocumentDefinition[];
+}
+
+/** @public */
+export declare interface SanityHandbook extends SanityDocument {
+  /** Document type identifier. */
+  _type: "handbook.handbook";
+  /** Ordered array of groups, each containing a title and guide references. */
+  groups: HandbookGuideGroup[];
+}
+
+/** @public */
+export declare interface SanityHandbookGuide extends SanityDocument {
+  /** Document type identifier. */
+  _type: "handbook.guide";
+  /** Unique key assigned by Sanity for this array item. */
+  _key: string;
+  /** Display title for this guide. */
+  title: string;
+  /** Brief description shown beneath the guide heading. */
+  description?: string;
+  /** Portable Text content of the guide. */
+  content: PortableTextBlock[];
+}
+
+/**
+ * Checks whether the current user is permitted to edit handbook content.
+ * Returns true if no editors list is provided (unrestricted) or if the
+ * current user's email is in the list.
+ *
+ * @public
+ * @param editors - Optional list of permitted email addresses.
+ * @returns Whether the current user can edit handbook documents.
+ */
+export declare function useIsHandbookEditor(editors?: string[]): boolean;
+
+export {};
+
+declare module "@sanity/types" {
+  interface FieldDefinitionBase {
+    handbook?: HandbookMetadata;
+  }
+  interface DocumentDefinition {
+    handbook?: HandbookMetadata;
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+import type { ComponentType } from "react";
+import type { CurrentUser } from "sanity";
+import type { DocumentDefinition } from "sanity";
+import { ListItemBuilder } from "sanity/structure";
+import { PluginOptions } from "sanity";
+import type { PortableTextBlock } from "sanity";
+import type { PortableTextObject } from "sanity";
+import type { SanityDocument } from "sanity";
+import type { SchemaTypeDefinition } from "sanity";
+import type { StructureBuilder } from "sanity/structure";
+
+/** @public */
+export declare interface HandbookBlockDefinition {
+  /** Sanity schema type definition for the custom block. */
+  schema: SchemaTypeDefinition;
+  /** React component for rendering the block in the Handbook viewer. */
+  component: ComponentType<{
+    value: PortableTextObject;
+  }>;
+}
+
+/** @public */
+export declare interface HandbookConfig {
+  /** Title shown in the Studio tool navigation. */
+  title?: string;
+  /** Heading displayed at the top of the sidebar. */
+  sidebarTitle?: string;
+  /** Document type groups defining the hierarchy. */
+  groups?: HandbookStructureGroup[];
+  /** Custom Portable Text block definitions for guide content. */
+  blocks?: HandbookBlockDefinition[];
+  /** Email addresses permitted to edit handbook documents. */
+  editors?: string[];
+  /** Fallback message shown when a field has no description. */
+  undocumentedFieldMessage?: string;
+}
+
+/** @public */
+export declare interface HandbookGuideGroup {
+  /** Unique key assigned by Sanity for this array item. */
+  _key: string;
+  /** Display title for this group in the sidebar. */
+  title: string;
+  /** Ordered array of guide references. */
+  guides: SanityHandbookGuide[];
+}
+
+/** @public */
+export declare interface HandbookMetadata {
+  /** Display title override for the field or document. */
+  title?: string;
+  /** Description shown beneath the field or document heading. */
+  description?: string;
+  /** Illustrative example value for the field. */
+  example?: string;
+  /** Helpful tip displayed as a popover hint. */
+  tip?: string;
+  /** Informational note displayed as a popover hint. */
+  info?: string;
+  /** Warning displayed as a popover hint. */
+  caution?: string;
+}
+
+/**
+ * Creates a Handbook tool for Sanity Studio, providing auto-generated documentation
+ * for document types and Portable Text guides within the Studio interface.
+ *
+ * @public
+ * @param config - Optional plugin configuration.
+ * @returns Sanity plugin definition.
+ */
+export declare function handbookPlugin(config?: HandbookConfig): PluginOptions;
+
+/**
+ * Creates Structure tool items for handbook documents.
+ * Returns an empty array if the current user is not in the editors list
+ * configured via handbookPlugin.
+ *
+ * @public
+ * @param structureBuilder - The Sanity Structure builder instance.
+ * @param context - The Structure context containing the current user.
+ * @returns An array of list items for the handbook singleton and guides list.
+ */
+export declare function handbookStructure(
+  structureBuilder: StructureBuilder,
+  context: {
+    currentUser: CurrentUser | null;
+  },
+): ListItemBuilder[];
+
+/** @public */
+export declare interface HandbookStructureGroup {
+  /** Display title for the document type group. */
+  title: string;
+  /** Brief description of the group's purpose. */
+  description?: string;
+  /** Document definitions belonging to this group. */
+  documents: DocumentDefinition[];
+}
+
+/** @public */
+export declare interface SanityHandbook extends SanityDocument {
+  /** Document type identifier. */
+  _type: "handbook.handbook";
+  /** Ordered array of groups, each containing a title and guide references. */
+  groups: HandbookGuideGroup[];
+}
+
+/** @public */
+export declare interface SanityHandbookGuide extends SanityDocument {
+  /** Document type identifier. */
+  _type: "handbook.guide";
+  /** Unique key assigned by Sanity for this array item. */
+  _key: string;
+  /** Display title for this guide. */
+  title: string;
+  /** Brief description shown beneath the guide heading. */
+  description?: string;
+  /** Portable Text content of the guide. */
+  content: PortableTextBlock[];
+}
+
+/**
+ * Checks whether the current user is permitted to edit handbook content.
+ * Returns true if no editors list is provided (unrestricted) or if the
+ * current user's email is in the list.
+ *
+ * @public
+ * @param editors - Optional list of permitted email addresses.
+ * @returns Whether the current user can edit handbook documents.
+ */
+export declare function useIsHandbookEditor(editors?: string[]): boolean;
+
+export {};
+
+declare module "@sanity/types" {
+  interface FieldDefinitionBase {
+    handbook?: HandbookMetadata;
+  }
+  interface DocumentDefinition {
+    handbook?: HandbookMetadata;
+  }
+}