@driftime/sanity-plugin-handbook 0.1.0

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@driftime/sanity-plugin-handbook",
+  "version": "0.1.0",
+  "description": "Schema-driven documentation and editorial guides, built right into Sanity Studio.",
+  "keywords": [
+    "sanity",
+    "sanity-plugin"
+  ],
+  "homepage": "https://github.com/driftime/sanity-plugin-handbook",
+  "bugs": {
+    "url": "https://github.com/driftime/sanity-plugin-handbook/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Kenny Heard",
+    "email": "kenny@driftime.com",
+    "url": "https://driftime.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/driftime/sanity-plugin-handbook.git"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "import": "./dist/index.js",
+        "require": "./dist/index.cjs",
+        "default": "./dist/index.js"
+      },
+      "./package.json": "./package.json"
+    }
+  },
+  "scripts": {
+    "check": "oxfmt --check && oxlint",
+    "fix": "oxfmt && oxlint --fix",
+    "dev": "plugin-kit link-watch",
+    "watch": "pkg-utils watch --strict",
+    "build": "plugin-kit verify-package --silent && pkg-utils build --strict --clean --check"
+  },
+  "dependencies": {
+    "lucide-react": "1.7.0"
+  },
+  "devDependencies": {
+    "@sanity/browserslist-config": "1.0.5",
+    "@sanity/pkg-utils": "10.4.13",
+    "@sanity/plugin-kit": "4.0.20",
+    "@sanity/ui": "3.1.14",
+    "@types/node": "25.5.2",
+    "@types/react": "19.2.14",
+    "oxfmt": "0.44.0",
+    "oxlint": "1.59.0",
+    "oxlint-tsgolint": "0.20.0",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "sanity": "5.20.0",
+    "typescript": "6.0.2"
+  },
+  "peerDependencies": {
+    "@sanity/ui": "2 || 3",
+    "react": "18 || 19",
+    "sanity": "3 || 4 || 5"
+  },
+  "browserslist": "extends @sanity/browserslist-config",
+  "engines": {
+    "node": ">=18"
+  },
+  "sanityPlugin": {
+    "verifyPackage": {
+      "sanityV2Json": false,
+      "eslintImports": false,
+      "scripts": false
+    }
+  }
+}

package/src/blocks/callout/block.tsx

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

@@ -0,0 +1,39 @@
+import { Card, Flex, Text } from "@sanity/ui";
+import { InfoIcon, LightbulbIcon, TriangleAlertIcon } from "lucide-react";
+import type { ReactNode } from "react";
+
+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

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

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

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

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

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

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

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

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

package/src/blocks/image/block.tsx

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

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

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

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

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

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

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

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

@@ -0,0 +1,49 @@
+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>
+      );
+    });
+  });
+}