@driftime/sanity-plugin-handbook 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -1,52 +1,21 @@
-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[];
+import { CurrentUser, DocumentDefinition, KeyedSegment, PortableTextBlock, PortableTextObject, PortableTextSpan, PortableTextTextBlock, SanityDocument, SchemaTypeDefinition } from "sanity";
+import { ComponentType } from "react";
+import "@sanity/ui";
+import { StructureBuilder } from "sanity/structure";
+declare module "@sanity/types" {
+  interface FieldDefinitionBase {
+    handbook?: SanityHandbookMetadata;
+  }
+  interface DocumentDefinition {
+    handbook?: SanityHandbookMetadata;
+  }
 }
-
-/** @public */
-export declare interface HandbookMetadata {
+/**
+ * Documentation a schema author attaches to a field or document, shown wherever the Handbook renders it.
+ *
+ * @public
+ */
+interface SanityHandbookMetadata {
   /** Display title override for the field or document. */
   title?: string;
   /** Description shown beneath the field or document heading. */
@@ -60,84 +29,208 @@ export declare interface HandbookMetadata {
   /** 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.
+ * A named part a set of document types plays in the content model, shown as one sidebar section.
  *
  * @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. */
+interface SanityHandbookDocumentRole {
+  /** Display title for the document role. */
   title: string;
-  /** Brief description of the group's purpose. */
+  /** Brief description of the role's purpose. */
   description?: string;
-  /** Document definitions belonging to this group. */
+  /** Document definitions filling this role. */
   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[];
+/**
+ * A Portable Text block a consumer adds to guide content, pairing its schema with how it renders.
+ *
+ * @public
+ */
+interface SanityHandbookBlockDefinition {
+  /** Sanity schema type definition for the custom block. */
+  schema: SchemaTypeDefinition;
+  /** React component for rendering the block in the Handbook viewer. */
+  component: ComponentType<{
+    value: PortableTextObject;
+  }>;
+}
+/**
+ * Everything the plugin accepts, of which only the document roles are required.
+ *
+ * @public
+ */
+interface SanityHandbookConfig {
+  /** Title shown in the Studio tool navigation. */
+  title?: string;
+  /** Heading displayed at the top of the sidebar. */
+  sidebarTitle?: string;
+  /** Document roles, each shown as a labelled section in the sidebar. */
+  roles: SanityHandbookDocumentRole[];
+  /** Custom Portable Text block definitions for guide content. */
+  blocks?: SanityHandbookBlockDefinition[];
+  /** Email addresses permitted to edit Handbook documents. */
+  editors?: string[];
+  /** Fallback message shown when a field has no description. */
+  undocumentedFieldMessage?: string;
 }
-
-/** @public */
-export declare interface SanityHandbookGuide extends SanityDocument {
-  /** Document type identifier. */
-  _type: "handbook.guide";
-  /** Unique key assigned by Sanity for this array item. */
-  _key: string;
+/**
+ * Creates a Handbook tool for Sanity Studio, generating documentation from document type schemas
+ * alongside the Portable Text guides authored in the dataset.
+ *
+ * @param config - Plugin configuration.
+ * @returns Sanity plugin definition.
+ * @public
+ */
+declare const handbookPlugin: import("sanity").Plugin<SanityHandbookConfig>;
+/**
+ * Creates the Structure tool items for Handbook documents, yielding nothing when the current user is
+ * not permitted to edit them.
+ *
+ * @param structureBuilder - The Sanity Structure builder instance.
+ * @param context - The Structure context carrying the current user.
+ * @param editors - Email addresses permitted to edit, defaulting to the configured list.
+ * @returns The list items for the Handbook singleton and the guides list.
+ * @public
+ */
+declare function handbookStructure(structureBuilder: StructureBuilder, context: {
+  currentUser: CurrentUser | null;
+}, editors?: string[]): import("sanity/structure").ListItemBuilder[];
+/**
+ * Checks whether the current user is permitted to edit Handbook content, treating an absent list as
+ * unrestricted access.
+ *
+ * @param editors - Email addresses permitted to edit, defaulting to the configured list.
+ * @returns Whether the current user can edit Handbook documents.
+ * @public
+ */
+declare function useIsHandbookEditor(editors?: string[]): boolean;
+/** Drops a type's catch-all index signature, so a mistyped field name is an error rather than an unknown value. */
+type Strict<T> = { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K]; };
+/** Array of objects each carrying the key Sanity assigns to array items, keeping members identifiable. */
+type SanityKeyedArray<T> = (KeyedSegment & T)[];
+/**
+ * A single Handbook page, authored as rich text and rendered in the tool.
+ *
+ * @public
+ */
+type SanityHandbookGuide = Strict<SanityDocument> & {
+  _type: typeof guideTypeName;
   /** Display title for this guide. */
   title: string;
   /** Brief description shown beneath the guide heading. */
   description?: string;
   /** Portable Text content of the guide. */
-  content: PortableTextBlock[];
-}
-
+  content: SanityKeyedArray<PortableTextBlock>;
+};
+/** Document type name of an individual guide. */
+declare const guideTypeName = "handbook.guide";
 /**
- * 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.
+ * A titled run of guides in the sidebar, holding them in the order they appear.
  *
  * @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;
-  }
+interface SanityHandbookGuideGroup {
+  /** Display title for this group in the sidebar. */
+  title: string;
+  /** Ordered array of guide references. */
+  guides: SanityKeyedArray<SanityHandbookGuide>;
 }
+/**
+ * The singleton naming every guide group and the order the sidebar lists them in.
+ *
+ * @public
+ */
+type SanityHandbook = Strict<SanityDocument> & {
+  _type: typeof handbookTypeName;
+  /** Ordered array of groups, each containing a title and guide references. */
+  groups: SanityKeyedArray<SanityHandbookGuideGroup>;
+};
+/** Document type name of the Handbook singleton. */
+declare const handbookTypeName = "handbook.handbook";
+/** The intent a callout is drawn with, choosing its icon and tone. */
+type CalloutVariant = "tip" | "info" | "warning";
+/**
+ * A highlighted message set apart from the surrounding guide text.
+ *
+ * @public
+ */
+type SanityHandbookCallout = Strict<PortableTextObject> & {
+  _type: typeof calloutTypeName;
+  /** Visual style and intent of the callout. */
+  variant: CalloutVariant;
+  /** Portable Text content displayed inside the callout, which offers no inline objects. */
+  body: SanityKeyedArray<PortableTextTextBlock<PortableTextSpan>>;
+};
+/** Type name of the callout block. */
+declare const calloutTypeName = "handbook.callout";
+/**
+ * A block of source code, rendered with syntax highlighting for its language.
+ *
+ * @public
+ */
+type SanityHandbookCode = Strict<PortableTextObject> & {
+  _type: typeof codeTypeName;
+  /** Source code to display. */
+  code?: string;
+  /** Programming language used for syntax highlighting. */
+  language?: string;
+};
+/** Type name of the code block. */
+declare const codeTypeName = "handbook.code";
+/**
+ * A divider between sections of a guide, carrying no authored content of its own.
+ *
+ * @public
+ */
+type SanityHandbookHorizontalRule = Strict<PortableTextObject> & {
+  _type: typeof horizontalRuleTypeName;
+};
+/** Type name of the horizontal rule block. */
+declare const horizontalRuleTypeName = "handbook.horizontalRule";
+/**
+ * An image placed in a guide, with the caption and alternative text shown alongside it.
+ *
+ * @public
+ */
+type SanityHandbookImage = Strict<PortableTextObject> & {
+  _type: typeof imageTypeName;
+  /** Uploaded image asset, narrowed by the query to the URL the viewer renders. */
+  asset?: {
+    url?: string;
+  };
+  /** Text displayed beneath the image. */
+  caption?: string;
+  /** Alternative text for screen readers. */
+  alt?: string;
+};
+/** Type name of the image block. */
+declare const imageTypeName = "handbook.image";
+/**
+ * A video placed in a guide, with the caption shown beneath it.
+ *
+ * @public
+ */
+type SanityHandbookVideo = Strict<PortableTextObject> & {
+  _type: typeof videoTypeName;
+  /** Uploaded video asset, narrowed by the query to the URL the viewer renders. */
+  asset?: {
+    url?: string;
+  };
+  /** Text displayed beneath the video. */
+  caption?: string;
+};
+/** Type name of the video block. */
+declare const videoTypeName = "handbook.video";
+/**
+ * A web address applied to a run of guide text.
+ *
+ * @public
+ */
+type SanityHandbookLink = Strict<PortableTextObject> & {
+  _type: "link";
+  /** Web address the link points to. */
+  href?: string;
+};
+export { type SanityHandbook, type SanityHandbookBlockDefinition, type SanityHandbookCallout, type SanityHandbookCode, type SanityHandbookConfig, type SanityHandbookDocumentRole, type SanityHandbookGuide, type SanityHandbookGuideGroup, type SanityHandbookHorizontalRule, type SanityHandbookImage, type SanityHandbookLink, type SanityHandbookMetadata, type SanityHandbookVideo, handbookPlugin, handbookStructure, useIsHandbookEditor };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/plugin.ts","../src/lib/structure.ts","../src/hooks/use-is-handbook-editor.ts","../src/types.ts","../src/schemas/types/guide.ts","../src/schemas/types/handbook.ts","../src/blocks/callout/content.tsx","../src/schemas/blocks/callout.ts","../src/schemas/blocks/code.ts","../src/schemas/blocks/horizontal-rule.ts","../src/schemas/blocks/image.ts","../src/schemas/blocks/video.ts","../src/schemas/annotations/link.ts"],"mappings":";;;;;YAoBY;IACR,WAAW;;YAIH;IACR,WAAW;;;;;;;;UASE;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;UAQe;;EAEf;;EAEA;;EAEA,WAAW;;;;;;;UAQI;;EAEf,QAAQ;;EAER,WAAW;IAAgB,OAAO;;;;;;;;UAQnB;;EAEf;;EAEA;;EAEA,OAAO;;EAEP,SAAS;;EAET;;EAEA;;;;;;;;;;cAWW,iCAAc,OAAA;;;;;;;;;;;iBCpFX,kBACd,kBAAkB,kBAClB;EAAW,aAAa;GACxB,gDAAkB;;;;;;;;;iBCXJ,oBAAoB;;KCNxB,OAAO,QAAQ,WAAW,oBAAoB,2BAA2B,YAAY,IAAI,EAAE;;KAG3F,iBAAiB,MAAM,eAAe;;;;;;KCMtC,sBAAsB,OAAO;EACvC,cAAc;;EAEd;;EAEA;;EAEA,SAAS,iBAAiB;;;cAIf;;;;;;UCVI;;EAEf;;EAEA,QAAQ,iBAAiB;;;;;;;KAQf,iBAAiB,OAAO;EAClC,cAAc;;EAEd,QAAQ,iBAAiB;;;cAId;;KCzBD;;;;;;KCOA,wBAAwB,OAAO;EACzC,cAAc;;EAEd,SAAS;;EAET,MAAM,iBAAiB,sBAAsB;;;cAIlC;;;;;;KCbD,qBAAqB,OAAO;EACtC,cAAc;;EAEd;;EAEA;;;cAIW;;;;;;KCTD,+BAA+B,OAAO;EAChD,cAAc;;;cAIH;;;;;;KCLD,sBAAsB,OAAO;EACvC,cAAc;;EAEd;IAAU;;;EAEV;;EAEA;;;cAIW;;;;;;KCXD,sBAAsB,OAAO;EACvC,cAAc;;EAEd;IAAU;;;EAEV;;;cAIW;;;;;;KCZD,qBAAqB,OAAO;EACtC;;EAEA"}