@driftime/sanity-plugin-handbook 0.1.0

package/src/index.ts

@@ -0,0 +1,145 @@
+import { BookTextIcon } from "lucide-react";
+import { definePlugin } from "sanity";
+
+import { createHandbookTool } from "./layouts/tool";
+import { setHandbookEditors } from "./lib/handbook-structure";
+import { createSanityIcon } from "./lib/icons";
+import { isDefined, isPermittedEditor } from "./lib/utils";
+import { handbookCalloutType } from "./schemas/blocks/callout";
+import { handbookCodeType } from "./schemas/blocks/code";
+import { handbookHorizontalRuleType } from "./schemas/blocks/horizontal-rule";
+import { handbookImageType } from "./schemas/blocks/image";
+import { handbookVideoType } from "./schemas/blocks/video";
+import { createHandbookGuideType } from "./schemas/types/guide";
+import { handbookType } from "./schemas/types/handbook";
+import type { HandbookConfig, HandbookStructureGroup } from "./types";
+
+export type {
+  HandbookBlockDefinition,
+  HandbookConfig,
+  HandbookGuideGroup,
+  HandbookMetadata,
+  HandbookStructureGroup,
+  SanityHandbook,
+  SanityHandbookGuide,
+} from "./types";
+export { handbookStructure } from "./lib/handbook-structure";
+export { useIsHandbookEditor } from "./hooks/use-is-handbook-editor";
+
+/** Document types that should not appear in the "create new" menu. */
+const handbookSingletonTypes = new Set(["handbook.handbook"]);
+
+/** All handbook document types used to filter template items for non-editors. */
+const handbookDocumentTypes = new Set(["handbook.handbook", "handbook.guide"]);
+
+/**
+ * Checks whether a template ID matches or is a variant of any type in the given set.
+ *
+ * @param templateId - The template identifier to check.
+ * @param typeSet - The set of document type names to match against.
+ * @returns True if the template ID matches a type or starts with a type prefix.
+ */
+function isHandbookTemplate(templateId: string, typeSet: Set<string>) {
+  return typeSet.has(templateId) || [...typeSet].some((type) => templateId.startsWith(`${type}-`));
+}
+
+/**
+ * Validates a single document type group entry in the plugin configuration.
+ *
+ * @param index - Position of the group in the configuration array.
+ * @param group - The document type group to validate.
+ */
+function validateGroup(index: number, group: HandbookStructureGroup) {
+  const prefix = `sanity-handbook: groups[${index}]`;
+
+  if (!isDefined(group.title)) throw new Error(`${prefix} is missing a required "title" property.`);
+
+  if (!Array.isArray(group.documents) || group.documents.length === 0) {
+    throw new Error(`${prefix} must have a non-empty "documents" array.`);
+  }
+
+  for (const document of group.documents) {
+    if (!isDefined(document.name)) {
+      throw new Error(`${prefix}.documents contains a document without a "name" property.`);
+    }
+
+    if (!Array.isArray(document.fields)) {
+      throw new TypeError(`${prefix}.documents.${document.name} is missing a "fields" array.`);
+    }
+  }
+}
+
+/**
+ * Validates the full handbook plugin configuration, checking all groups.
+ *
+ * @param config - The plugin configuration to validate.
+ */
+function validateConfig(config: HandbookConfig) {
+  if (config.groups) {
+    for (const [index, group] of config.groups.entries()) {
+      validateGroup(index, group);
+    }
+  }
+}
+
+/**
+ * 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 function handbookPlugin(config?: HandbookConfig) {
+  if (config) validateConfig(config);
+
+  const customBlocks = config?.blocks ?? [];
+  const editors = config?.editors;
+  setHandbookEditors(editors);
+
+  const guideType = createHandbookGuideType(customBlocks);
+
+  return definePlugin(() => ({
+    name: "@driftime/sanity-plugin-handbook",
+    schema: {
+      types: [
+        handbookType,
+        guideType,
+        handbookImageType,
+        handbookVideoType,
+        handbookCodeType,
+        handbookCalloutType,
+        handbookHorizontalRuleType,
+        ...customBlocks.map((block) => block.schema),
+      ],
+    },
+    document: {
+      newDocumentOptions: (templateItems, { creationContext, currentUser }) => {
+        if (creationContext.type === "global" || creationContext.type === "structure") {
+          if (!isPermittedEditor(editors, currentUser?.email)) {
+            return templateItems.filter((item) => !isHandbookTemplate(item.templateId, handbookDocumentTypes));
+          }
+
+          return templateItems.filter((item) => !isHandbookTemplate(item.templateId, handbookSingletonTypes));
+        }
+
+        return templateItems;
+      },
+      actions: (actionComponents, { schemaType }) => {
+        if (handbookSingletonTypes.has(schemaType)) {
+          return actionComponents.filter(({ action }) => action !== "duplicate");
+        }
+
+        return actionComponents;
+      },
+    },
+    tools: [
+      {
+        name: "handbook",
+        title: config?.title ?? "Handbook",
+        icon: createSanityIcon(BookTextIcon),
+        component: createHandbookTool({ ...config, blocks: customBlocks }),
+      },
+    ],
+  }))();
+}

package/src/layouts/content.tsx

@@ -0,0 +1,13 @@
+import { DocumentTypesPanels } from "../components/document-types";
+import { GuidesPanels } from "../components/guides";
+import { GettingStartedPanels } from "../getting-started/overview";
+
+export function Content() {
+  return (
+    <>
+      <GettingStartedPanels />
+      <DocumentTypesPanels />
+      <GuidesPanels />
+    </>
+  );
+}

package/src/layouts/sidebar.tsx

@@ -0,0 +1,15 @@
+import { Box } from "@sanity/ui";
+
+import { DocumentTypesTabs } from "../components/document-types";
+import { GuidesTabs } from "../components/guides";
+import { GettingStartedTabs } from "../getting-started/overview";
+
+export function Sidebar() {
+  return (
+    <Box paddingX={3} paddingBottom={1}>
+      <GettingStartedTabs />
+      <DocumentTypesTabs />
+      <GuidesTabs />
+    </Box>
+  );
+}

package/src/layouts/tool.tsx

@@ -0,0 +1,205 @@
+import { ArrowLeftIcon } from "@sanity/icons";
+import { Button, Card, Flex, Text } from "@sanity/ui";
+
+import { PaneHeader } from "../components/pane-header";
+import { HandbookProvider, useHandbookContext } from "../contexts/handbook-context";
+import { useContainerWidth } from "../hooks/use-container-width";
+import { isDefined } from "../lib/utils";
+import type { HandbookConfig } from "../types";
+import { Content } from "./content";
+import { Sidebar } from "./sidebar";
+
+/** Default fallback message shown when a field has no description. */
+const defaultUndocumentedFieldMessage =
+  "This field has not been documented yet. Contact your development team for guidance.";
+
+/** Minimum container width for the wide (sidebar always visible) layout. */
+const wideBreakpoint = 920;
+
+/** Minimum container width for the medium (collapsible sidebar) layout. */
+const narrowBreakpoint = 480;
+
+/** Sidebar width in pixels when fully expanded. */
+const sidebarWidth = 320;
+
+/** Sidebar width in pixels when collapsed to a vertical label. */
+const collapsedSidebarWidth = 51;
+
+function CollapsedSidebar() {
+  const { sidebarTitle, setSidebarExpanded } = useHandbookContext();
+
+  return (
+    <div
+      style={{
+        width: `${collapsedSidebarWidth}px`,
+        minWidth: `${collapsedSidebarWidth}px`,
+        overflow: "hidden",
+        borderRight: "1px solid var(--card-border-color)",
+      }}
+    >
+      <Card tone="inherit" data-collapsed="">
+        <Flex
+          direction="column"
+          padding={3}
+          onClick={() => {
+            setSidebarExpanded(true);
+          }}
+          style={{
+            width: "100vh",
+            boxSizing: "border-box",
+            transform: "rotate(90deg)",
+            transformOrigin: `calc(${collapsedSidebarWidth}px / 2)`,
+            cursor: "pointer",
+          }}
+        >
+          <Flex align="flex-start">
+            <Card flex={1} paddingLeft={2} padding={2}>
+              <Flex align="center" gap={1}>
+                <Text size={1} textOverflow="ellipsis" weight="semibold" style={{ cursor: "default", outline: "none" }}>
+                  {sidebarTitle}
+                </Text>
+              </Flex>
+            </Card>
+          </Flex>
+        </Flex>
+      </Card>
+    </div>
+  );
+}
+
+function NarrowContentHeader() {
+  const { sidebarTitle, setSidebarExpanded } = useHandbookContext();
+
+  return (
+    <Flex align="center" gap={2} padding={3}>
+      <Button
+        icon={ArrowLeftIcon}
+        mode="bleed"
+        onClick={() => {
+          setSidebarExpanded(true);
+        }}
+      />
+      <Text size={1} weight="semibold">
+        {sidebarTitle}
+      </Text>
+    </Flex>
+  );
+}
+
+function ExpandedSidebar() {
+  const { sidebarTitle } = useHandbookContext();
+
+  return (
+    <Card
+      borderRight
+      style={{ display: "flex", flexDirection: "column", width: `${sidebarWidth}px`, minWidth: `${sidebarWidth}px` }}
+    >
+      <PaneHeader title={sidebarTitle} />
+      <div style={{ flex: 1, paddingBottom: "4px", overflowY: "auto" }}>
+        <Sidebar />
+      </div>
+    </Card>
+  );
+}
+
+function NarrowLayout() {
+  const { sidebarTitle, sidebarExpanded } = useHandbookContext();
+
+  if (sidebarExpanded) {
+    return (
+      <div style={{ display: "flex", flexDirection: "column", flex: 1 }}>
+        <PaneHeader title={sidebarTitle} />
+        <div style={{ flex: 1, paddingBottom: "4px", overflowY: "auto" }}>
+          <Sidebar />
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", flex: 1 }}>
+      <NarrowContentHeader />
+      <Content />
+    </div>
+  );
+}
+
+function MediumLayout() {
+  const { sidebarExpanded, setSidebarExpanded } = useHandbookContext();
+
+  if (sidebarExpanded) {
+    return (
+      <Flex style={{ flex: 1 }}>
+        <ExpandedSidebar />
+        <Card
+          flex={1}
+          padding={3}
+          onClick={() => {
+            setSidebarExpanded(false);
+          }}
+          style={{ opacity: 0.4, overflowY: "auto", cursor: "pointer" }}
+        />
+      </Flex>
+    );
+  }
+
+  return (
+    <Flex style={{ flex: 1 }}>
+      <CollapsedSidebar />
+      <Card flex={1} style={{ display: "flex", flexDirection: "column" }}>
+        <Content />
+      </Card>
+    </Flex>
+  );
+}
+
+function WideLayout() {
+  return (
+    <Flex style={{ flex: 1 }}>
+      <ExpandedSidebar />
+      <Card flex={1} style={{ display: "flex", flexDirection: "column" }}>
+        <Content />
+      </Card>
+    </Flex>
+  );
+}
+
+function HandbookLayout() {
+  const { reference: containerReference, width: containerWidth } = useContainerWidth<HTMLDivElement>();
+
+  const isNarrow = isDefined(containerWidth) && containerWidth < narrowBreakpoint;
+  const isMedium = isDefined(containerWidth) && containerWidth >= narrowBreakpoint && containerWidth < wideBreakpoint;
+
+  function renderLayout() {
+    if (isNarrow) return <NarrowLayout />;
+    if (isMedium) return <MediumLayout />;
+    return <WideLayout />;
+  }
+
+  return (
+    <div ref={containerReference} style={{ display: "flex", flexDirection: "column", height: "100%" }}>
+      {renderLayout()}
+    </div>
+  );
+}
+
+/**
+ * Creates the Handbook tool component bound to the given plugin configuration.
+ *
+ * @param config - Handbook plugin configuration.
+ * @returns Tool component for Sanity Studio.
+ */
+export function createHandbookTool(config: HandbookConfig) {
+  return function HandbookTool() {
+    return (
+      <HandbookProvider
+        sidebarTitle={config.sidebarTitle ?? "Handbook"}
+        groups={config.groups ?? []}
+        blocks={config.blocks ?? []}
+        undocumentedFieldMessage={config.undocumentedFieldMessage ?? defaultUndocumentedFieldMessage}
+      >
+        <HandbookLayout />
+      </HandbookProvider>
+    );
+  };
+}

package/src/lib/handbook-structure.ts

@@ -0,0 +1,46 @@
+import { BookOpenTextIcon, BookTextIcon } from "lucide-react";
+import type { CurrentUser } from "sanity";
+import type { StructureBuilder } from "sanity/structure";
+
+import { createSanityIcon } from "./icons";
+import { isPermittedEditor } from "./utils";
+
+/** Editor email addresses stored from plugin configuration for use by the structure helper. */
+let registeredEditors: string[] | undefined = undefined;
+
+/**
+ * Stores the editors list from the plugin configuration for use by the structure helper.
+ *
+ * @internal
+ * @param editors - The editors list from HandbookConfig.
+ */
+export function setHandbookEditors(editors?: string[]) {
+  registeredEditors = editors;
+}
+
+/**
+ * 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 function handbookStructure(structureBuilder: StructureBuilder, context: { currentUser: CurrentUser | null }) {
+  if (!isPermittedEditor(registeredEditors, context.currentUser?.email)) return [];
+
+  const { listItem, document, documentTypeList } = structureBuilder;
+
+  return [
+    listItem()
+      .title("Handbook")
+      .icon(createSanityIcon(BookTextIcon))
+      .child(document().id("handbook.handbook").schemaType("handbook.handbook").title("Handbook")),
+    listItem()
+      .title("Handbook Guides")
+      .icon(createSanityIcon(BookOpenTextIcon))
+      .child(documentTypeList("handbook.guide").title("Handbook Guides")),
+  ];
+}

package/src/lib/icons.ts

@@ -0,0 +1,18 @@
+import type { LucideIcon, LucideProps } from "lucide-react";
+import { createElement } from "react";
+
+/**
+ * Default properties applied to all Lucide icons throughout the plugin.
+ */
+export const defaultIconProps: LucideProps = { width: "1em", height: "1em", strokeWidth: 1.5 };
+
+/**
+ * Creates a Sanity Studio icon component from a Lucide icon with default props applied.
+ *
+ * @param icon - The Lucide icon component to wrap.
+ * @param props - Optional props to merge with defaults.
+ * @returns A React component function for use in Sanity Studio.
+ */
+export function createSanityIcon(icon: LucideIcon, props?: LucideProps) {
+  return () => createElement(icon, { ...defaultIconProps, ...props });
+}

package/src/lib/utils.ts

@@ -0,0 +1,69 @@
+/**
+ * Determines whether a value is defined and non-empty. Treats `false`, empty strings,
+ * empty arrays, and empty objects as not defined.
+ *
+ * @param value - The value to check.
+ * @returns True if the value is defined and not empty.
+ */
+export function isDefined<T>(value: T | null | undefined | false): value is T {
+  if (value === undefined || value === null || value === false) return false;
+  if (typeof value === "string") return value.trim() !== "";
+  if (Array.isArray(value)) return value.some((element) => isDefined(element));
+  if (typeof value === "object") return Object.keys(value).length > 0;
+
+  return true;
+}
+
+/**
+ * Checks whether an email address is in the permitted editors list.
+ * Returns true if no editors list is provided or the list is empty (unrestricted access).
+ *
+ * @param editors - Optional list of permitted email addresses.
+ * @param email - The email address to check.
+ * @returns Whether the email is permitted to edit.
+ */
+export function isPermittedEditor(editors: string[] | undefined, email: string | undefined) {
+  if (!isDefined(editors)) return true;
+  if (!isDefined(email)) return false;
+
+  return editors.includes(email);
+}
+
+/**
+ * Converts a string between different casing formats.
+ *
+ * @param value - The string to convert.
+ * @param format - The target casing format.
+ * @returns The converted string.
+ */
+export function convertCase(value: string, format: "kebab" | "snake" | "camel" | "pascal" | "title" | "sentence") {
+  const words = value
+    .replaceAll(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replaceAll(/[-_\s]+/g, " ")
+    .trim()
+    .toLowerCase();
+
+  switch (format) {
+    case "kebab": {
+      return words.replaceAll(/\s+/g, "-");
+    }
+    case "snake": {
+      return words.replaceAll(/\s+/g, "_");
+    }
+    case "camel": {
+      return words.replaceAll(/\s+(.)/g, (_match, character: string) => character.toUpperCase());
+    }
+    case "pascal": {
+      return words.replaceAll(/(?:^|\s+)(.)/g, (_match, character: string) => character.toUpperCase());
+    }
+    case "title": {
+      return words.replaceAll(/\b\w/g, (character) => character.toUpperCase());
+    }
+    case "sentence": {
+      return words.replaceAll(/^(.)/g, (character) => character.toUpperCase());
+    }
+    default: {
+      return value;
+    }
+  }
+}

package/src/schemas/annotations/link.ts

@@ -0,0 +1,19 @@
+import { defineArrayMember, defineField } from "sanity";
+
+/**
+ * Inline link annotation for Portable Text fields.
+ * Supports http, https, mailto, and tel URI schemes.
+ */
+export const linkAnnotation = defineArrayMember({
+  name: "link",
+  type: "object",
+  fields: [
+    defineField({
+      name: "href",
+      title: "URL",
+      type: "url",
+      description: "Web address for this link. Supports http, https, mailto, and tel schemes.",
+      validation: (rule) => rule.uri({ scheme: ["http", "https", "mailto", "tel"] }),
+    }),
+  ],
+});

package/src/schemas/blocks/callout.ts

@@ -0,0 +1,69 @@
+import { MessageCircleQuestionMarkIcon } from "lucide-react";
+import { defineArrayMember, defineField, defineType } from "sanity";
+
+import { CalloutPreview } from "../../blocks/callout/preview";
+import { InlineCodeDecorator, ParagraphDecorator } from "../../components/decorators";
+import { createSanityIcon } from "../../lib/icons";
+import { linkAnnotation } from "../annotations/link";
+
+export const handbookCalloutType = defineType({
+  name: "handbook.callout",
+  title: "Callout",
+  type: "object",
+  icon: createSanityIcon(MessageCircleQuestionMarkIcon),
+  description: "A highlighted message block used to draw attention to tips, supplementary information, or warnings.",
+  preview: {
+    select: { variant: "variant", body: "body" },
+    prepare({ variant, body }: { variant?: string; body?: { children?: { text?: string }[] }[] }) {
+      const text = Array.isArray(body)
+        ? body.flatMap((block) => (block.children ?? []).map((child) => child.text ?? "")).join("")
+        : "";
+
+      return { variant, text };
+    },
+  },
+  components: {
+    preview: CalloutPreview,
+  },
+  fields: [
+    defineField({
+      name: "variant",
+      title: "Variant",
+      type: "string",
+      description: "Visual style and intent of the callout.",
+      initialValue: "tip",
+      validation: (rule) => rule.required(),
+      options: {
+        list: [
+          { title: "Tip", value: "tip" },
+          { title: "Information", value: "info" },
+          { title: "Warning", value: "warning" },
+        ],
+        layout: "radio",
+        direction: "horizontal",
+      },
+    }),
+    defineField({
+      name: "body",
+      title: "Body",
+      type: "array",
+      description: "Content displayed inside the callout. Supports inline formatting and links.",
+      of: [
+        defineArrayMember({
+          type: "block",
+          styles: [{ title: "Normal", value: "normal", component: ParagraphDecorator }],
+          marks: {
+            decorators: [
+              { title: "Bold", value: "strong" },
+              { title: "Italic", value: "em" },
+              { title: "Strikethrough", value: "strike-through" },
+              { title: "Code", value: "code", component: InlineCodeDecorator },
+            ],
+            annotations: [linkAnnotation],
+          },
+          lists: [],
+        }),
+      ],
+    }),
+  ],
+});

package/src/schemas/blocks/code.ts

@@ -0,0 +1,46 @@
+import { CodeIcon } from "lucide-react";
+import { defineField, defineType } from "sanity";
+
+import { CodePreview } from "../../blocks/code/preview";
+import { createSanityIcon } from "../../lib/icons";
+
+export const handbookCodeType = defineType({
+  name: "handbook.code",
+  title: "Code",
+  type: "object",
+  icon: createSanityIcon(CodeIcon),
+  description: "A syntax-highlighted code block with language selection.",
+  preview: {
+    select: { code: "code", language: "language" },
+  },
+  components: {
+    preview: CodePreview,
+  },
+  fields: [
+    defineField({
+      name: "code",
+      title: "Code",
+      type: "text",
+      description: "The source code to display.",
+    }),
+    defineField({
+      name: "language",
+      title: "Language",
+      type: "string",
+      description: "Programming language used for syntax highlighting.",
+      options: {
+        list: [
+          { title: "CSS", value: "css" },
+          { title: "GROQ", value: "groq" },
+          { title: "HTML", value: "html" },
+          { title: "JavaScript", value: "javascript" },
+          { title: "JSON", value: "json" },
+          { title: "Plain Text", value: "text" },
+          { title: "React", value: "tsx" },
+          { title: "Shell", value: "shell" },
+          { title: "TypeScript", value: "typescript" },
+        ],
+      },
+    }),
+  ],
+});

package/src/schemas/blocks/horizontal-rule.ts

@@ -0,0 +1,31 @@
+import { MinusIcon } from "lucide-react";
+import { defineField, defineType } from "sanity";
+
+import { HorizontalRulePreview } from "../../blocks/horizontal-rule/preview";
+import { createSanityIcon } from "../../lib/icons";
+
+export const handbookHorizontalRuleType = defineType({
+  name: "handbook.horizontalRule",
+  title: "Horizontal Rule",
+  type: "object",
+  icon: createSanityIcon(MinusIcon),
+  description: "A visual divider between sections of content.",
+  preview: {
+    prepare() {
+      return { title: "Horizontal Rule" };
+    },
+  },
+  components: {
+    preview: HorizontalRulePreview,
+  },
+  fields: [
+    defineField({
+      name: "style",
+      title: "Style",
+      type: "string",
+      description: "Presentation style for the divider.",
+      hidden: true,
+      initialValue: "default",
+    }),
+  ],
+});