@driftime/sanity-plugin-handbook 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -1,143 +0,0 @@
-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/src/blocks/callout/block.tsx

@@ -1,56 +0,0 @@
-import { PortableText } from "@portabletext/react";
-import type { PortableTextBlock } from "@portabletext/react";
-import type { ReactNode } from "react";
-
-import type { CalloutVariant } from "./content";
-import { CalloutContent } from "./content";
-
-interface HandbookCalloutValue {
-  /** Document type identifier. */
-  _type: "handbook.callout";
-  /** Visual style and intent of the callout. */
-  variant: CalloutVariant;
-  /** Portable Text content displayed inside the callout. */
-  body: PortableTextBlock[];
-}
-
-export function CalloutBlock({ value }: { value: HandbookCalloutValue }) {
-  return (
-    <div style={{ marginBlock: "2rem" }}>
-      <CalloutContent variant={value.variant}>
-        <PortableText
-          value={value.body}
-          components={{
-            block: { normal: ({ children }) => <>{children}</> },
-            marks: {
-              strong: ({ children }) => <strong>{children}</strong>,
-              em: ({ children }) => <em>{children}</em>,
-              code: ({ children }) => (
-                <code
-                  style={{
-                    padding: "0.125rem 0.25rem",
-                    fontSize: "0.875em",
-                    backgroundColor: "var(--card-code-bg-color)",
-                    borderRadius: "0.125rem",
-                  }}
-                >
-                  {children}
-                </code>
-              ),
-              link: ({ children, value: mark }: { children: ReactNode; value?: { href?: string } }) => (
-                <a
-                  href={mark?.href}
-                  target="_blank"
-                  rel="noopener noreferrer"
-                  style={{ color: "var(--card-fg-color)" }}
-                >
-                  {children}
-                </a>
-              ),
-            },
-          }}
-        />
-      </CalloutContent>
-    </div>
-  );
-}

package/src/blocks/callout/content.tsx

@@ -1,41 +0,0 @@
-import { Card, Flex, Text } from "@sanity/ui";
-import type { ReactNode } from "react";
-
-import { InfoIcon } from "../../icons/info";
-import { LightbulbIcon } from "../../icons/lightbulb";
-import { TriangleAlertIcon } from "../../icons/triangle-alert";
-import { defaultIconProps } from "../../lib/icons";
-
-export type CalloutVariant = "tip" | "info" | "warning";
-
-interface CalloutContentProps {
-  /** Visual style variant determining the icon and tone. */
-  variant: CalloutVariant;
-  /** Content displayed inside the callout. */
-  children: ReactNode;
-}
-
-/** Icon and tone mapping for each callout variant. */
-export const variantConfig = {
-  tip: { icon: LightbulbIcon, tone: "positive" },
-  info: { icon: InfoIcon, tone: "primary" },
-  warning: { icon: TriangleAlertIcon, tone: "caution" },
-} as const;
-
-export function CalloutContent({ variant, children }: CalloutContentProps) {
-  const config = variantConfig[variant];
-  const Icon = config.icon;
-
-  return (
-    <Card padding={4} radius={2} tone={config.tone}>
-      <Flex align="flex-start" gap={3}>
-        <div style={{ flexShrink: 0, marginTop: "-2px", fontSize: "16px", color: "var(--card-icon-color)" }}>
-          <Icon {...defaultIconProps} />
-        </div>
-        <Text size={1} style={{ color: "var(--card-icon-color)" }}>
-          {children}
-        </Text>
-      </Flex>
-    </Card>
-  );
-}

package/src/blocks/callout/preview.tsx

@@ -1,15 +0,0 @@
-import type { PreviewProps } from "sanity";
-
-import type { CalloutVariant } from "./content";
-import { CalloutContent } from "./content";
-
-interface CalloutPreviewProps extends PreviewProps {
-  /** Visual style variant for the callout. */
-  variant?: CalloutVariant;
-  /** Plain text content extracted from the callout body. */
-  text?: string;
-}
-
-export function CalloutPreview({ variant, text }: CalloutPreviewProps) {
-  return <CalloutContent variant={variant ?? "tip"}>{text}</CalloutContent>;
-}

package/src/blocks/code/block.tsx

@@ -1,18 +0,0 @@
-import { CodeContent } from "./content";
-
-interface HandbookCodeValue {
-  /** Document type identifier. */
-  _type: "handbook.code";
-  /** Source code to display. */
-  code: string;
-  /** Programming language for syntax highlighting. */
-  language?: string;
-}
-
-export function CodeBlock({ value }: { value: HandbookCodeValue }) {
-  return (
-    <div style={{ marginBlock: "1.5rem" }}>
-      <CodeContent code={value.code} language={value.language} />
-    </div>
-  );
-}

package/src/blocks/code/content.tsx

@@ -1,18 +0,0 @@
-import { Card, Code } from "@sanity/ui";
-
-interface CodeContentProps {
-  /** Source code to display. */
-  code: string;
-  /** Programming language for syntax highlighting. */
-  language?: string;
-}
-
-export function CodeContent({ code, language }: CodeContentProps) {
-  return (
-    <Card padding={4} radius={2} tone="transparent" style={{ overflowX: "auto" }}>
-      <Code size={1} language={language}>
-        {code}
-      </Code>
-    </Card>
-  );
-}

package/src/blocks/code/preview.tsx

@@ -1,17 +0,0 @@
-import type { PreviewProps } from "sanity";
-
-import { isDefined } from "../../lib/utils";
-import { CodeContent } from "./content";
-
-interface CodePreviewProps extends PreviewProps {
-  /** Source code to display. */
-  code?: string;
-  /** Programming language for syntax highlighting. */
-  language?: string;
-}
-
-export function CodePreview({ code, language }: CodePreviewProps) {
-  if (!isDefined(code)) return null;
-
-  return <CodeContent code={code} language={language} />;
-}

package/src/blocks/horizontal-rule/block.tsx

@@ -1,5 +0,0 @@
-import { HorizontalRuleContent } from "./content";
-
-export function HorizontalRuleBlock() {
-  return <HorizontalRuleContent marginBlock="2.5rem" />;
-}

package/src/blocks/horizontal-rule/content.tsx

@@ -1,8 +0,0 @@
-interface HorizontalRuleContentProps {
-  /** Vertical spacing above and below the rule. */
-  marginBlock?: string;
-}
-
-export function HorizontalRuleContent({ marginBlock = "0" }: HorizontalRuleContentProps) {
-  return <hr style={{ marginBlock, border: "none", borderTop: "1px solid var(--card-border-color)" }} />;
-}

package/src/blocks/horizontal-rule/preview.tsx

@@ -1,5 +0,0 @@
-import { HorizontalRuleContent } from "./content";
-
-export function HorizontalRulePreview() {
-  return <HorizontalRuleContent marginBlock="0.5rem" />;
-}

package/src/blocks/image/block.tsx

@@ -1,23 +0,0 @@
-import { isDefined } from "../../lib/utils";
-import { ImageContent } from "./content";
-
-interface HandbookImageValue {
-  /** Document type identifier. */
-  _type: "handbook.image";
-  /** Resolved image asset containing the URL. */
-  asset?: { url?: string };
-  /** Text displayed beneath the image. */
-  caption?: string;
-  /** Alternative text for screen readers. */
-  alt?: string;
-}
-
-export function ImageBlock({ value }: { value: HandbookImageValue }) {
-  if (!isDefined(value.asset?.url)) return null;
-
-  return (
-    <div style={{ marginBlock: "1.5rem" }}>
-      <ImageContent url={value.asset.url} alt={value.alt} caption={value.caption} />
-    </div>
-  );
-}

package/src/blocks/image/content.tsx

@@ -1,31 +0,0 @@
-import { Text } from "@sanity/ui";
-
-import { isDefined } from "../../lib/utils";
-
-interface ImageContentProps {
-  /** Image source URL. */
-  url: string;
-  /** Alternative text for screen readers. */
-  alt?: string;
-  /** Text displayed beneath the image. */
-  caption?: string;
-}
-
-export function ImageContent({ url, alt, caption }: ImageContentProps) {
-  return (
-    <>
-      <img
-        src={url}
-        alt={alt ?? ""}
-        style={{ display: "block", maxWidth: "100%", borderRadius: "0.25rem", overflow: "hidden" }}
-      />
-      {isDefined(caption) && (
-        <div style={{ marginBlockStart: "0.75rem" }}>
-          <Text size={1} muted style={{ fontStyle: "italic" }}>
-            {caption}
-          </Text>
-        </div>
-      )}
-    </>
-  );
-}

package/src/blocks/image/preview.tsx

@@ -1,23 +0,0 @@
-import type { PreviewProps } from "sanity";
-
-import { isDefined } from "../../lib/utils";
-import { ImageContent } from "./content";
-
-interface ImagePreviewProps extends PreviewProps {
-  /** Resolved image URL from the asset. */
-  url?: string;
-  /** Alternative text for screen readers. */
-  alt?: string;
-  /** Text displayed beneath the image. */
-  caption?: string;
-}
-
-export function ImagePreview({ url, alt, caption }: ImagePreviewProps) {
-  if (!isDefined(url)) return null;
-
-  return (
-    <div style={{ padding: "0.5rem" }}>
-      <ImageContent url={url} alt={alt} caption={caption} />
-    </div>
-  );
-}

package/src/blocks/video/block.tsx

@@ -1,21 +0,0 @@
-import { isDefined } from "../../lib/utils";
-import { VideoContent } from "./content";
-
-interface HandbookVideoValue {
-  /** Document type identifier. */
-  _type: "handbook.video";
-  /** Resolved video asset containing the URL. */
-  asset?: { url?: string };
-  /** Text displayed beneath the video. */
-  caption?: string;
-}
-
-export function VideoBlock({ value }: { value: HandbookVideoValue }) {
-  if (!isDefined(value.asset?.url)) return null;
-
-  return (
-    <div style={{ marginBlock: "1.5rem" }}>
-      <VideoContent url={value.asset.url} caption={value.caption} />
-    </div>
-  );
-}

package/src/blocks/video/content.tsx

@@ -1,37 +0,0 @@
-import { Text } from "@sanity/ui";
-
-import { isDefined } from "../../lib/utils";
-
-interface VideoContentProps {
-  /** Video source URL. */
-  url: string;
-  /** Text displayed beneath the video. */
-  caption?: string;
-}
-
-export function VideoContent({ url, caption }: VideoContentProps) {
-  return (
-    <>
-      <video
-        src={url}
-        controls
-        style={{
-          display: "block",
-          maxWidth: "100%",
-          borderRadius: "0.25rem",
-          overflow: "hidden",
-          WebkitTransform: "translateZ(0)",
-        }}
-      >
-        <track kind="captions" label={caption ?? "Video"} />
-      </video>
-      {isDefined(caption) && (
-        <div style={{ marginBlockStart: "0.75rem" }}>
-          <Text size={1} muted style={{ fontStyle: "italic" }}>
-            {caption}
-          </Text>
-        </div>
-      )}
-    </>
-  );
-}

package/src/blocks/video/preview.tsx

@@ -1,21 +0,0 @@
-import type { PreviewProps } from "sanity";
-
-import { isDefined } from "../../lib/utils";
-import { VideoContent } from "./content";
-
-interface VideoPreviewProps extends PreviewProps {
-  /** Resolved video URL from the asset. */
-  url?: string;
-  /** Text displayed beneath the video. */
-  caption?: string;
-}
-
-export function VideoPreview({ url, caption }: VideoPreviewProps) {
-  if (!isDefined(url)) return null;
-
-  return (
-    <div style={{ padding: "0.5rem" }}>
-      <VideoContent url={url} caption={caption} />
-    </div>
-  );
-}

package/src/components/content-panel.tsx

@@ -1,58 +0,0 @@
-import { Box, Heading, Stack, Text } from "@sanity/ui";
-import type { ReactNode } from "react";
-
-import { useHandbookContext } from "../contexts/handbook-context";
-import { isDefined } from "../lib/utils";
-import { PaneHeader } from "./pane-header";
-
-interface ContentPanelProps {
-  /** Unique identifier linking this panel to its sidebar tab. */
-  id: string;
-  /** Heading displayed at the top of the panel. */
-  title: string;
-  /** Optional description shown beneath the heading. */
-  description?: string;
-  /** Panel body content. */
-  children: ReactNode;
-}
-
-export function ContentPanel({ id, title, description, children }: ContentPanelProps) {
-  const { activeTab } = useHandbookContext();
-
-  if (activeTab !== id) return null;
-
-  return (
-    <div
-      id={`panel-${id}`}
-      aria-labelledby={id}
-      role="tabpanel"
-      style={{ display: "flex", flexDirection: "column", height: "100%" }}
-    >
-      <PaneHeader title={title} />
-      <div style={{ flex: 1, overflowY: "auto" }}>
-        <Box
-          style={{
-            maxWidth: "640px",
-            boxSizing: "border-box",
-            marginInline: "auto",
-            paddingInline: "20px",
-            paddingBlockStart: "32px",
-            paddingBlockEnd: "220px",
-          }}
-        >
-          <Stack marginBottom={6} space={5}>
-            <Heading as="h2" size={4}>
-              {title}
-            </Heading>
-            {isDefined(description) && (
-              <Text size={1} muted>
-                {description}
-              </Text>
-            )}
-          </Stack>
-          {children}
-        </Box>
-      </div>
-    </div>
-  );
-}

package/src/components/decorators.tsx

@@ -1,53 +0,0 @@
-import type { ReactNode } from "react";
-
-interface DecoratorProps {
-  /** Text content wrapped by the decorator. */
-  children: ReactNode;
-}
-
-export function ParagraphDecorator({ children }: DecoratorProps) {
-  return <span style={{ fontSize: "0.8125rem" }}>{children}</span>;
-}
-
-export function HeadingDecorator({ children }: DecoratorProps) {
-  return <span style={{ fontSize: "0.8125rem", fontWeight: "500" }}>{children}</span>;
-}
-
-export function BlockquoteDecorator({ children }: DecoratorProps) {
-  return (
-    <div
-      style={{
-        paddingLeft: "0.75em",
-        fontSize: "0.8125rem",
-        fontStyle: "italic",
-        borderLeft: "2px solid var(--card-border-color)",
-      }}
-    >
-      {children}
-    </div>
-  );
-}
-
-export function BulletListDecorator({ children }: DecoratorProps) {
-  return <div style={{ marginTop: "-0.25em", fontSize: "0.8125rem" }}>{children}</div>;
-}
-
-export function NumberListDecorator({ children }: DecoratorProps) {
-  return <div style={{ marginTop: "-0.25em", fontSize: "0.8125rem" }}>{children}</div>;
-}
-
-export function InlineCodeDecorator({ children }: DecoratorProps) {
-  return (
-    <code
-      style={{
-        padding: "0.125rem 0.25rem",
-        fontSize: "0.8125rem",
-        color: "var(--card-muted-fg-color)",
-        backgroundColor: "var(--card-code-bg-color)",
-        borderRadius: "0.125rem",
-      }}
-    >
-      {children}
-    </code>
-  );
-}

package/src/components/document-types.tsx

@@ -1,49 +0,0 @@
-import { useHandbookContext } from "../contexts/handbook-context";
-import { convertCase } from "../lib/utils";
-import { ContentPanel } from "./content-panel";
-import { Field } from "./field";
-import { SidebarGroup } from "./sidebar-group";
-import { SidebarTab } from "./sidebar-tab";
-
-export function DocumentTypesTabs() {
-  const { groups } = useHandbookContext();
-
-  return groups.map((group) => {
-    const { title, documents } = group;
-
-    return (
-      <SidebarGroup key={title} heading={title}>
-        {documents.map((document) => {
-          const effectiveTitle = document.handbook?.title ?? document.title ?? convertCase(document.name, "title");
-          const icon = typeof document.icon === "function" ? document.icon : undefined;
-
-          return <SidebarTab key={document.name} id={document.name} label={effectiveTitle} icon={icon} />;
-        })}
-      </SidebarGroup>
-    );
-  });
-}
-
-export function DocumentTypesPanels() {
-  const { groups } = useHandbookContext();
-
-  return groups.map((group) => {
-    const { documents } = group;
-
-    return documents.map((document) => {
-      const effectiveTitle = document.handbook?.title ?? document.title ?? convertCase(document.name, "title");
-      const effectiveDescription =
-        document.handbook?.description ?? (typeof document.description === "string" ? document.description : undefined);
-
-      return (
-        <ContentPanel key={document.name} id={document.name} title={effectiveTitle} description={effectiveDescription}>
-          <div style={{ display: "flex", flexDirection: "column", gap: "3.25rem" }}>
-            {document.fields.map((field) => (
-              <Field key={field.name} field={field} />
-            ))}
-          </div>
-        </ContentPanel>
-      );
-    });
-  });
-}