@driftime/sanity-plugin-handbook 0.2.1 → 0.3.1

package/src/lib/utils.ts

@@ -1,69 +0,0 @@
-/**
- * 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

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

@@ -1,69 +0,0 @@
-import { defineArrayMember, defineField, defineType } from "sanity";
-
-import { CalloutPreview } from "../../blocks/callout/preview";
-import { InlineCodeDecorator, ParagraphDecorator } from "../../components/decorators";
-import { MessageCircleQuestionMarkIcon } from "../../icons/message-circle-question-mark";
-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

@@ -1,46 +0,0 @@
-import { defineField, defineType } from "sanity";
-
-import { CodePreview } from "../../blocks/code/preview";
-import { CodeIcon } from "../../icons/code";
-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

@@ -1,31 +0,0 @@
-import { defineField, defineType } from "sanity";
-
-import { HorizontalRulePreview } from "../../blocks/horizontal-rule/preview";
-import { MinusIcon } from "../../icons/minus";
-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",
-    }),
-  ],
-});

package/src/schemas/blocks/image.ts

@@ -1,40 +0,0 @@
-import { defineField, defineType } from "sanity";
-
-import { ImagePreview } from "../../blocks/image/preview";
-import { ImageIcon } from "../../icons/image";
-import { createSanityIcon } from "../../lib/icons";
-
-export const handbookImageType = defineType({
-  name: "handbook.image",
-  title: "Image",
-  type: "object",
-  icon: createSanityIcon(ImageIcon),
-  description: "An image with optional caption and alternative text for accessibility.",
-  preview: {
-    select: { caption: "caption", alt: "alt", url: "asset.asset.url" },
-  },
-  components: {
-    preview: ImagePreview,
-  },
-  fields: [
-    defineField({
-      name: "asset",
-      title: "Image",
-      type: "image",
-      description: "Upload or select an image from the media library.",
-      options: { hotspot: true },
-    }),
-    defineField({
-      name: "caption",
-      title: "Caption",
-      type: "string",
-      description: "Text displayed beneath the image in the handbook.",
-    }),
-    defineField({
-      name: "alt",
-      title: "Alternative Text",
-      type: "string",
-      description: "Describes the image for screen readers and accessibility tools.",
-    }),
-  ],
-});

package/src/schemas/blocks/video.ts

@@ -1,34 +0,0 @@
-import { defineField, defineType } from "sanity";
-
-import { VideoPreview } from "../../blocks/video/preview";
-import { VideoIcon } from "../../icons/video";
-import { createSanityIcon } from "../../lib/icons";
-
-export const handbookVideoType = defineType({
-  name: "handbook.video",
-  title: "Video",
-  type: "object",
-  icon: createSanityIcon(VideoIcon),
-  description: "An uploaded video with optional caption.",
-  preview: {
-    select: { caption: "caption", url: "asset.asset.url" },
-  },
-  components: {
-    preview: VideoPreview,
-  },
-  fields: [
-    defineField({
-      name: "asset",
-      title: "Video",
-      type: "file",
-      description: "Upload or select a video from the media library.",
-      options: { accept: "video/*" },
-    }),
-    defineField({
-      name: "caption",
-      title: "Caption",
-      type: "string",
-      description: "Text displayed beneath the video in the handbook.",
-    }),
-  ],
-});

package/src/schemas/guide-content.ts

@@ -1,58 +0,0 @@
-import { defineArrayMember, defineField } from "sanity";
-
-import {
-  BlockquoteDecorator,
-  BulletListDecorator,
-  HeadingDecorator,
-  InlineCodeDecorator,
-  NumberListDecorator,
-  ParagraphDecorator,
-} from "../components/decorators";
-import type { HandbookBlockDefinition } from "../types";
-import { linkAnnotation } from "./annotations/link";
-
-/**
- * Creates the Portable Text content field for handbook guides, merging
- * default blocks with any custom blocks from the plugin configuration.
- *
- * @param customBlocks - Custom block definitions registered by the consumer.
- * @returns A field definition for the guide content array.
- */
-export function createGuideContentField(customBlocks: HandbookBlockDefinition[] = []) {
-  return defineField({
-    name: "content",
-    title: "Content",
-    type: "array",
-    description: "Rich text content for this guide. Supports headings, lists, images, code blocks, and custom blocks.",
-    of: [
-      defineArrayMember({
-        name: "block",
-        type: "block",
-        styles: [
-          { title: "Paragraph", value: "normal", component: ParagraphDecorator },
-          { title: "Heading", value: "h2", component: HeadingDecorator },
-          { title: "Blockquote", value: "blockquote", component: BlockquoteDecorator },
-        ],
-        marks: {
-          decorators: [
-            { title: "Bold", value: "strong" },
-            { title: "Italic", value: "em" },
-            { title: "Strikethrough", value: "strike-through" },
-            { title: "Code", value: "code", component: InlineCodeDecorator },
-          ],
-          annotations: [linkAnnotation],
-        },
-        lists: [
-          { title: "Bullet", value: "bullet", component: BulletListDecorator },
-          { title: "Number", value: "number", component: NumberListDecorator },
-        ],
-      }),
-      defineArrayMember({ type: "handbook.image" }),
-      defineArrayMember({ type: "handbook.video" }),
-      defineArrayMember({ type: "handbook.code" }),
-      defineArrayMember({ type: "handbook.callout" }),
-      defineArrayMember({ type: "handbook.horizontalRule" }),
-      ...customBlocks.map((block) => defineArrayMember({ type: block.schema.name })),
-    ],
-  });
-}

package/src/schemas/types/guide.ts

@@ -1,48 +0,0 @@
-import { defineField, defineType } from "sanity";
-
-import { BookOpenTextIcon } from "../../icons/book-open-text";
-import { createSanityIcon } from "../../lib/icons";
-import type { HandbookBlockDefinition, SanityHandbookGuide } from "../../types";
-import { createGuideContentField } from "../guide-content";
-
-/**
- * Creates the handbook.guide document type with the content field
- * composed from default and custom blocks.
- *
- * @param customBlocks - Custom block definitions registered by the consumer.
- * @returns A document type definition for handbook guides.
- */
-export function createHandbookGuideType(customBlocks: HandbookBlockDefinition[] = []) {
-  return defineType({
-    name: "handbook.guide" satisfies SanityHandbookGuide["_type"],
-    title: "Handbook Guide",
-    type: "document",
-    icon: createSanityIcon(BookOpenTextIcon),
-    description: "A handbook page authored with rich text, images, and custom blocks.",
-    preview: {
-      select: { title: "title", description: "description" },
-      prepare({ title, description }: { title?: string; description?: string }) {
-        return {
-          title: title ?? "Untitled Guide",
-          subtitle: description,
-        };
-      },
-    },
-    fields: [
-      defineField({
-        name: "title" satisfies keyof SanityHandbookGuide,
-        title: "Title",
-        type: "string",
-        description: "Display title shown in the handbook sidebar and as the page heading.",
-        validation: (rule) => rule.required(),
-      }),
-      defineField({
-        name: "description" satisfies keyof SanityHandbookGuide,
-        title: "Description",
-        type: "string",
-        description: "Brief summary displayed beneath the guide heading.",
-      }),
-      createGuideContentField(customBlocks),
-    ],
-  });
-}

package/src/schemas/types/handbook.ts

@@ -1,86 +0,0 @@
-import { defineArrayMember, defineField, defineType } from "sanity";
-
-import { BookTextIcon } from "../../icons/book-text";
-import { ListPlusIcon } from "../../icons/list-plus";
-import { createSanityIcon } from "../../lib/icons";
-import { isDefined } from "../../lib/utils";
-import type { SanityHandbook } from "../../types";
-
-export const handbookType = defineType({
-  name: "handbook.handbook" satisfies SanityHandbook["_type"],
-  title: "Handbook",
-  type: "document",
-  icon: createSanityIcon(BookTextIcon),
-  description: "Defines the structure and ordering of the handbook, including groups and their guides.",
-  preview: {
-    prepare() {
-      return { title: "Handbook" };
-    },
-  },
-  fields: [
-    defineField({
-      name: "groups" satisfies keyof SanityHandbook,
-      title: "Groups",
-      type: "array",
-      description:
-        "Ordered list of groups displayed in the handbook sidebar. Each group contains a title and an ordered list of guide references.",
-      of: [
-        defineArrayMember({
-          name: "group",
-          type: "object",
-          icon: createSanityIcon(ListPlusIcon),
-          fields: [
-            defineField({
-              name: "title",
-              title: "Title",
-              type: "string",
-              description: "Heading displayed above this group of guides in the sidebar.",
-              validation: (rule) => rule.required(),
-            }),
-            defineField({
-              name: "guides",
-              title: "Guides",
-              type: "array",
-              description: "Ordered list of guides within this group. Drag to reorder.",
-              of: [
-                defineArrayMember({
-                  type: "reference",
-                  to: [{ type: "handbook.guide" }],
-                }),
-              ],
-            }),
-          ],
-          preview: {
-            select: { title: "title", guide0: "guides.0.title", guide1: "guides.1.title", guide2: "guides.2.title" },
-            prepare({
-              title,
-              guide0,
-              guide1,
-              guide2,
-            }: {
-              title?: string;
-              guide0?: string;
-              guide1?: string;
-              guide2?: string;
-            }) {
-              const all = [guide0, guide1, guide2].filter((guide): guide is string => isDefined(guide));
-              const shown = all.slice(0, 2);
-              const hasMore = isDefined(guide2);
-
-              function formatSubtitle() {
-                if (!isDefined(shown)) return "No guides selected";
-                if (hasMore) return `${shown.join(", ")}, and others`;
-                return shown.join(" and ");
-              }
-
-              return {
-                title: title ?? "Untitled Group",
-                subtitle: formatSubtitle(),
-              };
-            },
-          },
-        }),
-      ],
-    }),
-  ],
-});

package/src/types.ts

@@ -1,101 +0,0 @@
-import type { ComponentType } from "react";
-import type {
-  DocumentDefinition,
-  PortableTextBlock,
-  PortableTextObject,
-  SanityDocument,
-  SchemaTypeDefinition,
-} from "sanity";
-
-declare module "@sanity/types" {
-  interface FieldDefinitionBase {
-    handbook?: HandbookMetadata;
-  }
-
-  // oxlint-disable-next-line no-shadow -- Module augmentation intentionally redeclares the imported type.
-  interface DocumentDefinition {
-    handbook?: HandbookMetadata;
-  }
-}
-
-/** @public */
-export 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;
-}
-
-/** @public */
-export 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 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 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 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 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 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[];
-}