@driftime/sanity-plugin-handbook 0.3.2 → 0.4.1

package/dist/index.d.ts

@@ -1,229 +1,232 @@
-import { CurrentUser, DocumentDefinition, KeyedSegment, PortableTextBlock, PortableTextObject, PortableTextSpan, PortableTextTextBlock, SanityDocument, SchemaTypeDefinition } from "sanity";
 import { ComponentType } from "react";
-import "@sanity/ui";
+import { CurrentUser, DocumentDefinition, KeyedSegment, PortableTextBlock, PortableTextObject, PortableTextSpan, PortableTextTextBlock, SanityDocument, SchemaTypeDefinition } from "sanity";
 import { StructureBuilder } from "sanity/structure";
 declare module "@sanity/types" {
   interface FieldDefinitionBase {
+    /** Handbook documentation for the field. */
     handbook?: SanityHandbookMetadata;
   }
   interface DocumentDefinition {
+    /** Handbook documentation for the document type. */
     handbook?: SanityHandbookMetadata;
   }
 }
 /**
- * Documentation a schema author attaches to a field or document, shown wherever the Handbook renders it.
+ * Documentation added to a field or document definition, shown in the Handbook.
  *
  * @public
  */
 interface SanityHandbookMetadata {
-  /** Display title override for the field or document. */
+  /** Title to show instead of the schema title. */
   title?: string;
-  /** Description shown beneath the field or document heading. */
+  /** Description shown below the field or document heading. */
   description?: string;
-  /** Illustrative example value for the field. */
+  /** Example value for the field. */
   example?: string;
-  /** Helpful tip displayed as a popover hint. */
+  /** Tip, shown as a hint icon. */
   tip?: string;
-  /** Informational note displayed as a popover hint. */
+  /** Extra information, shown as a hint icon. */
   info?: string;
-  /** Warning displayed as a popover hint. */
+  /** Warning, shown as a hint icon. */
   caution?: string;
 }
 /**
- * A named part a set of document types plays in the content model, shown as one sidebar section.
+ * A group of document types with the same role in the content model, shown as one sidebar section.
  *
  * @public
  */
 interface SanityHandbookDocumentRole {
-  /** Display title for the document role. */
+  /** Role title. */
   title: string;
-  /** Brief description of the role's purpose. */
+  /** Short description of the role. */
   description?: string;
-  /** Document definitions filling this role. */
+  /** Document definitions in the role. */
   documents: DocumentDefinition[];
 }
 /**
- * A Portable Text block a consumer adds to guide content, pairing its schema with how it renders.
+ * A custom Portable Text block for guides: its schema and the component that renders it.
  *
  * @public
  */
 interface SanityHandbookBlockDefinition {
-  /** Sanity schema type definition for the custom block. */
+  /** Schema type definition for the block. */
   schema: SchemaTypeDefinition;
-  /** React component for rendering the block in the Handbook viewer. */
+  /** Component that renders the block in the Handbook. */
   component: ComponentType<{
     value: PortableTextObject;
   }>;
 }
 /**
- * Everything the plugin accepts, of which only the document roles are required.
+ * Plugin configuration. Only `roles` is required.
  *
  * @public
  */
 interface SanityHandbookConfig {
-  /** Title shown in the Studio tool navigation. */
+  /** Title in the Studio's tool menu. Defaults to `"Handbook"`. */
   title?: string;
-  /** Heading displayed at the top of the sidebar. */
+  /** Heading at the top of the sidebar. Defaults to `"Handbook"`. */
   sidebarTitle?: string;
-  /** Document roles, each shown as a labelled section in the sidebar. */
+  /** Document roles, each shown as a section in the sidebar. */
   roles: SanityHandbookDocumentRole[];
-  /** Custom Portable Text block definitions for guide content. */
+  /** Custom Portable Text blocks for guides. Defaults to none. */
   blocks?: SanityHandbookBlockDefinition[];
-  /** Email addresses permitted to edit Handbook documents. */
+  /** Email addresses of the people who can edit Handbook documents. Defaults to everyone. */
   editors?: string[];
-  /** Fallback message shown when a field has no description. */
+  /** Message shown for fields without a description. Defaults to a prompt to ask the development team. */
   undocumentedFieldMessage?: string;
 }
 /**
- * Creates a Handbook tool for Sanity Studio, generating documentation from document type schemas
- * alongside the Portable Text guides authored in the dataset.
+ * Adds a Handbook tool to Sanity Studio, with documentation generated from the schema and guides written
+ * in the Studio.
  *
- * @param config - Plugin configuration.
- * @returns Sanity plugin definition.
+ * @param config - The plugin configuration.
+ * @returns The plugin.
  * @public
  */
 export 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.
+ * Creates Structure tool items for the Handbook documents, or none when the current user can't 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.
+ * @param structureBuilder - The structure builder.
+ * @param context - The structure context, with the current user.
+ * @param editors - Email addresses of the editors, defaulting to the configured list.
+ * @returns List items for the Handbook document and the guides list, oldest guide first.
  * @public
  */
 export 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.
+ * Checks whether the current user can edit Handbook documents. Without an editors list, everyone can.
  *
- * @param editors - Email addresses permitted to edit, defaulting to the configured list.
+ * @param editors - Email addresses of the editors, defaulting to the configured list.
  * @returns Whether the current user can edit Handbook documents.
  * @public
  */
 export 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. */
+/** Removes a type's index signatures, so a misspelt property is an error rather than `unknown`. */
 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. */
+/** Array whose items carry the `_key` Sanity gives array members. */
 type SanityKeyedArray<T> = (KeyedSegment & T)[];
 /**
- * A single Handbook page, authored as rich text and rendered in the tool.
+ * A Handbook guide, written in rich text and shown in the tool.
  *
  * @public
  */
 type SanityHandbookGuide = Strict<SanityDocument> & {
   _type: typeof guideTypeName;
-  /** Display title for this guide. */
+  /** Guide title. */
   title: string;
-  /** Brief description shown beneath the guide heading. */
+  /** Short description below the guide heading. */
   description?: string;
-  /** Portable Text content of the guide. */
+  /** Portable Text content. */
   content: SanityKeyedArray<PortableTextBlock>;
 };
-/** Document type name of an individual guide. */
+/** Schema type name of the guide document. */
 declare const guideTypeName = "handbook.guide";
 /**
- * A titled run of guides in the sidebar, holding them in the order they appear.
+ * A group of guides in the sidebar, in order.
  *
  * @public
  */
 interface SanityHandbookGuideGroup {
-  /** Display title for this group in the sidebar. */
+  /** Group title in the sidebar. */
   title: string;
-  /** Ordered array of guide references. */
+  /** Guides in the group, in order. */
   guides: SanityKeyedArray<SanityHandbookGuide>;
 }
 /**
- * The singleton naming every guide group and the order the sidebar lists them in.
+ * The Handbook document, listing the guide groups in sidebar order.
  *
  * @public
  */
 type SanityHandbook = Strict<SanityDocument> & {
   _type: typeof handbookTypeName;
-  /** Ordered array of groups, each containing a title and guide references. */
+  /** Guide groups, in order. */
   groups: SanityKeyedArray<SanityHandbookGuideGroup>;
 };
-/** Document type name of the Handbook singleton. */
+/** Schema type name of the Handbook document. */
 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.
+ * An image in a guide, with its caption and alternative 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 SanityHandbookImage = Strict<PortableTextObject> & {
+  _type: typeof imageTypeName;
+  /** Image asset, reduced by the query to its URL. */
+  asset?: {
+    url?: string;
+  };
+  /** Text shown below the image. */
+  caption?: string;
+  /** Alternative text. */
+  alt?: string;
 };
-/** Type name of the callout block. */
-declare const calloutTypeName = "handbook.callout";
+/** Schema type name of the image block. */
+declare const imageTypeName = "handbook.image";
+/**
+ * A video in a guide, with its caption.
+ *
+ * @public
+ */
+type SanityHandbookVideo = Strict<PortableTextObject> & {
+  _type: typeof videoTypeName;
+  /** Video asset, reduced by the query to its URL. */
+  asset?: {
+    url?: string;
+  };
+  /** Text shown below the video. */
+  caption?: string;
+};
+/** Schema type name of the video block. */
+declare const videoTypeName = "handbook.video";
 /**
- * A block of source code, rendered with syntax highlighting for its language.
+ * A code block, highlighted for its language.
  *
  * @public
  */
 type SanityHandbookCode = Strict<PortableTextObject> & {
   _type: typeof codeTypeName;
-  /** Source code to display. */
+  /** Code to display. */
   code?: string;
-  /** Programming language used for syntax highlighting. */
+  /** Language used for syntax highlighting. */
   language?: string;
 };
-/** Type name of the code block. */
+/** Schema 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.
+ * Kind of callout, which sets its icon and tone.
  *
  * @public
  */
-type SanityHandbookHorizontalRule = Strict<PortableTextObject> & {
-  _type: typeof horizontalRuleTypeName;
-};
-/** Type name of the horizontal rule block. */
-declare const horizontalRuleTypeName = "handbook.horizontalRule";
+type SanityHandbookCalloutVariant = "tip" | "info" | "warning";
 /**
- * An image placed in a guide, with the caption and alternative text shown alongside it.
+ * A highlighted message in a guide.
  *
  * @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 SanityHandbookCallout = Strict<PortableTextObject> & {
+  _type: typeof calloutTypeName;
+  /** Kind of callout. */
+  variant: SanityHandbookCalloutVariant;
+  /** Portable Text inside the callout, without inline objects. */
+  body: SanityKeyedArray<PortableTextTextBlock<PortableTextSpan>>;
 };
-/** Type name of the image block. */
-declare const imageTypeName = "handbook.image";
+/** Schema type name of the callout block. */
+declare const calloutTypeName = "handbook.callout";
 /**
- * A video placed in a guide, with the caption shown beneath it.
+ * A divider between sections of a guide.
  *
  * @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 SanityHandbookHorizontalRule = Strict<PortableTextObject> & {
+  _type: typeof horizontalRuleTypeName;
 };
-/** Type name of the video block. */
-declare const videoTypeName = "handbook.video";
+/** Schema type name of the horizontal rule block. */
+declare const horizontalRuleTypeName = "handbook.horizontalRule";
 /**
- * A web address applied to a run of guide text.
+ * A link on a run of guide text.
  *
  * @public
  */
@@ -232,5 +235,5 @@ type SanityHandbookLink = Strict<PortableTextObject> & {
   /** Web address the link points to. */
   href?: string;
 };
-export type { SanityHandbook, SanityHandbookBlockDefinition, SanityHandbookCallout, SanityHandbookCode, SanityHandbookConfig, SanityHandbookDocumentRole, SanityHandbookGuide, SanityHandbookGuideGroup, SanityHandbookHorizontalRule, SanityHandbookImage, SanityHandbookLink, SanityHandbookMetadata, SanityHandbookVideo };
+export type { SanityHandbook, SanityHandbookBlockDefinition, SanityHandbookCallout, SanityHandbookCalloutVariant, SanityHandbookCode, SanityHandbookConfig, SanityHandbookDocumentRole, SanityHandbookGuide, SanityHandbookGuideGroup, SanityHandbookHorizontalRule, SanityHandbookImage, SanityHandbookLink, SanityHandbookMetadata, SanityHandbookVideo };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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;;;;;;;;;;qBAWW,iCAAc,OAAA;;;;;;;;;;;wBCpFX,kBACd,kBAAkB,kBAClB;EAAW,aAAa;GACxB,gDAAkB;;;;;;;;;wBCXJ,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"}
+{"version":3,"file":"index.d.ts","names":["ComponentType","DocumentDefinition","PortableTextObject","SchemaTypeDefinition","_0","SanityHandbookMetadata","sideEffect","SanityHandbookDocumentRole","SanityHandbookBlockDefinition","SanityHandbookConfig","handbookPlugin","CurrentUser","StructureBuilder","handbookStructure","useIsHandbookEditor","KeyedSegment","PortableTextBlock","PortableTextObject","PortableTextSpan","PortableTextTextBlock","SanityDocument","Strict","T","K","SanityKeyedArray","SanityHandbookGuide","guideTypeName","SanityHandbookGuideGroup","SanityHandbook","handbookTypeName","SanityHandbookImage","imageTypeName","SanityHandbookVideo","videoTypeName","SanityHandbookCode","codeTypeName","SanityHandbookCalloutVariant","SanityHandbookCallout","calloutTypeName","SanityHandbookHorizontalRule","horizontalRuleTypeName","SanityHandbookLink"],"sources":["../src/plugin.ts","../src/lib/structure.ts","../src/hooks/use-is-handbook-editor.ts","../src/types.ts"],"mappings":";;;;YAoBY;;IAER,WAAWK;;YAIH;;IAER,WAAWA;;;;;;;;UASEA;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;UAQeE;;EAEf;;EAEA;;EAEA,WAAWN;;;;;;;UAQIO;;EAEf,QAAQL;;EAER,WAAWH;IAAgB,OAAOE;;;;;;;;UAQnBO;;EAEf;;EAEA;;EAEA,OAAOF;;EAEP,SAASC;;EAET;;EAEA;;;;;;;;;;qBAWWE,iCAAc,OAAAD;;;;;;;;;;wBCxFXI,kBACd,kBAAkBD,kBAClB;EAAW,aAAaD;GACxB,gDAAkB;;;;;;;;wBCVJG,oBAAoB;;KCDxBO,OAAO,QAAQ,WAAWC,oBAAoBC,2BAA2BA,YAAYA,IAAID,EAAEC;;KAG3FC,iBAAiB,MAAMT,eAAeO;;;;;;KAOtCG,sBAAsBJ,OAAOD;EACvC,cAAcM;;EAEd;;EAEA;;EAEA,SAASF,iBAAiBR;;;cAIfU;;;;;;UAOIC;;EAEf;;EAEA,QAAQH,iBAAiBC;;;;;;;KAQfG,iBAAiBP,OAAOD;EAClC,cAAcS;;EAEd,QAAQL,iBAAiBG;;;cAIdE;;;;;;KAODC,sBAAsBT,OAAOJ;EACvC,cAAcc;;EAEd;IAAU;;;EAEV;;EAEA;;;cAIWA;;;;;;KAODC,sBAAsBX,OAAOJ;EACvC,cAAcgB;;EAEd;IAAU;;;EAEV;;;cAIWA;;;;;;KAODC,qBAAqBb,OAAOJ;EACtC,cAAckB;;EAEd;;EAEA;;;cAIWA;;;;;;KAODC;;;;;;KAOAC,wBAAwBhB,OAAOJ;EACzC,cAAcqB;;EAEd,SAASF;;EAET,MAAMZ,iBAAiBL,sBAAsBD;;;cAIlCoB;;;;;;KAODC,+BAA+BlB,OAAOJ;EAChD,cAAcuB;;;cAIHA;;;;;;KAODC,qBAAqBpB,OAAOJ;EACtC;;EAEA"}