@driftime/sanity-plugin-handbook 0.2.0 → 0.3.0

package/src/icons/image.tsx

@@ -1,19 +0,0 @@
-import type { SVGProps } from "react";
-
-export function ImageIcon(props: SVGProps<SVGSVGElement>) {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      {...props}
-    >
-      <rect width="18" height="18" x="3" y="3" rx="2" ry="2" />
-      <circle cx="9" cy="9" r="2" />
-      <path d="m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21" />
-    </svg>
-  );
-}

package/src/icons/info.tsx

@@ -1,19 +0,0 @@
-import type { SVGProps } from "react";
-
-export function InfoIcon(props: SVGProps<SVGSVGElement>) {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      {...props}
-    >
-      <circle cx="12" cy="12" r="10" />
-      <path d="M12 16v-4" />
-      <path d="M12 8h.01" />
-    </svg>
-  );
-}

package/src/icons/layout-grid.tsx

@@ -1,20 +0,0 @@
-import type { SVGProps } from "react";
-
-export function LayoutGridIcon(props: SVGProps<SVGSVGElement>) {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      {...props}
-    >
-      <rect width="7" height="7" x="3" y="3" rx="1" />
-      <rect width="7" height="7" x="14" y="3" rx="1" />
-      <rect width="7" height="7" x="14" y="14" rx="1" />
-      <rect width="7" height="7" x="3" y="14" rx="1" />
-    </svg>
-  );
-}

package/src/icons/lightbulb.tsx

@@ -1,19 +0,0 @@
-import type { SVGProps } from "react";
-
-export function LightbulbIcon(props: SVGProps<SVGSVGElement>) {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      {...props}
-    >
-      <path d="M15 14c.2-1 .7-1.7 1.5-2.5 1-.9 1.5-2.2 1.5-3.5A6 6 0 0 0 6 8c0 1 .2 2.2 1.5 3.5.7.7 1.3 1.5 1.5 2.5" />
-      <path d="M9 18h6" />
-      <path d="M10 22h4" />
-    </svg>
-  );
-}

package/src/icons/list-plus.tsx

@@ -1,21 +0,0 @@
-import type { SVGProps } from "react";
-
-export function ListPlusIcon(props: SVGProps<SVGSVGElement>) {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      {...props}
-    >
-      <path d="M16 5H3" />
-      <path d="M11 12H3" />
-      <path d="M16 19H3" />
-      <path d="M18 9v6" />
-      <path d="M21 12h-6" />
-    </svg>
-  );
-}

package/src/icons/message-circle-question-mark.tsx

@@ -1,19 +0,0 @@
-import type { SVGProps } from "react";
-
-export function MessageCircleQuestionMarkIcon(props: SVGProps<SVGSVGElement>) {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      {...props}
-    >
-      <path d="M2.992 16.342a2 2 0 0 1 .094 1.167l-1.065 3.29a1 1 0 0 0 1.236 1.168l3.413-.998a2 2 0 0 1 1.099.092 10 10 0 1 0-4.777-4.719" />
-      <path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3" />
-      <path d="M12 17h.01" />
-    </svg>
-  );
-}

package/src/icons/minus.tsx

@@ -1,17 +0,0 @@
-import type { SVGProps } from "react";
-
-export function MinusIcon(props: SVGProps<SVGSVGElement>) {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      {...props}
-    >
-      <path d="M5 12h14" />
-    </svg>
-  );
-}

package/src/icons/triangle-alert.tsx

@@ -1,19 +0,0 @@
-import type { SVGProps } from "react";
-
-export function TriangleAlertIcon(props: SVGProps<SVGSVGElement>) {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      {...props}
-    >
-      <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" />
-      <path d="M12 9v4" />
-      <path d="M12 17h.01" />
-    </svg>
-  );
-}

package/src/icons/video.tsx

@@ -1,18 +0,0 @@
-import type { SVGProps } from "react";
-
-export function VideoIcon(props: SVGProps<SVGSVGElement>) {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      {...props}
-    >
-      <path d="m16 13 5.223 3.482a.5.5 0 0 0 .777-.416V7.87a.5.5 0 0 0-.752-.432L16 10.5" />
-      <rect x="2" y="6" width="14" height="12" rx="2" />
-    </svg>
-  );
-}

package/src/index.ts

@@ -1,145 +0,0 @@
-import { definePlugin } from "sanity";
-
-import { BookTextIcon } from "./icons/book-text";
-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

@@ -1,13 +0,0 @@
-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

@@ -1,15 +0,0 @@
-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

@@ -1,205 +0,0 @@
-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

@@ -1,47 +0,0 @@
-import type { CurrentUser } from "sanity";
-import type { StructureBuilder } from "sanity/structure";
-
-import { BookOpenTextIcon } from "../icons/book-open-text";
-import { BookTextIcon } from "../icons/book-text";
-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

@@ -1,16 +0,0 @@
-import type { ComponentType, SVGProps } from "react";
-import { createElement } from "react";
-
-/** Default properties applied to all icons throughout the plugin. */
-export const defaultIconProps: SVGProps<SVGSVGElement> = { width: "1em", height: "1em", strokeWidth: 1.5 };
-
-/**
- * Creates a Sanity Studio icon component from an SVG icon with default props applied.
- *
- * @param icon - The 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: ComponentType<SVGProps<SVGSVGElement>>, props?: SVGProps<SVGSVGElement>) {
-  return () => createElement(icon, { ...defaultIconProps, ...props });
-}