@driftime/sanity-plugin-handbook 0.2.1 → 0.3.1

package/src/components/pane-header.tsx

@@ -1,26 +0,0 @@
-import { Card, Flex, Text } from "@sanity/ui";
-
-interface PaneHeaderProps {
-  /** Heading text displayed in the pane header. */
-  title: string;
-}
-
-export function PaneHeader({ title }: PaneHeaderProps) {
-  return (
-    <div style={{ position: "sticky", top: 0, zIndex: 1, lineHeight: 0 }}>
-      <Card tone="inherit">
-        <Flex direction="column" padding={3} style={{ boxSizing: "border-box" }}>
-          <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" }}>
-                  {title}
-                </Text>
-              </Flex>
-            </Card>
-          </Flex>
-        </Flex>
-      </Card>
-    </div>
-  );
-}

package/src/components/sidebar-group.tsx

@@ -1,30 +0,0 @@
-import { Box, Card, Flex, Text } from "@sanity/ui";
-import type { PropsWithChildren } from "react";
-
-type SidebarGroupProps = PropsWithChildren<{
-  /** Text label displayed above the group. */
-  heading: string;
-}>;
-
-export function SidebarGroup({ heading, children }: SidebarGroupProps) {
-  return (
-    <div>
-      <Box paddingY={2}>
-        <Card paddingLeft={2} padding={2}>
-          <Flex align="center" gap={1}>
-            <Text
-              size={1}
-              muted
-              textOverflow="ellipsis"
-              weight="semibold"
-              style={{ cursor: "default", outline: "none" }}
-            >
-              {heading}
-            </Text>
-          </Flex>
-        </Card>
-      </Box>
-      {children}
-    </div>
-  );
-}

package/src/components/sidebar-tab.tsx

@@ -1,78 +0,0 @@
-import { ChevronRightIcon } from "@sanity/icons";
-import { Box, Card, Flex, Stack, Text } from "@sanity/ui";
-import type { ComponentType } from "react";
-
-import { useHandbookContext } from "../contexts/handbook-context";
-import { isDefined } from "../lib/utils";
-
-interface SidebarTabProps {
-  /** Unique identifier linking this tab to its content panel. */
-  id: string;
-  /** Text label displayed on the tab. */
-  label: string;
-  /** Optional icon component rendered beside the label. */
-  icon?: ComponentType;
-}
-
-export function SidebarTab({ id, label, icon: Icon }: SidebarTabProps) {
-  const { activeTab, setActiveTab, setSidebarExpanded } = useHandbookContext();
-  const selected = activeTab === id;
-
-  return (
-    <Card
-      id={id}
-      aria-controls={`panel-${id}`}
-      aria-selected={selected}
-      role="option"
-      as="button"
-      selected={selected}
-      marginBottom={1}
-      radius={2}
-      sizing="border"
-      tabIndex={-1}
-      tone="inherit"
-      onClick={() => {
-        setActiveTab(id);
-        setSidebarExpanded(false);
-      }}
-      style={{ width: "100%", textAlign: "left", border: "none", cursor: "pointer" }}
-    >
-      <Flex
-        align="center"
-        paddingLeft={isDefined(Icon) ? 1 : 2}
-        paddingRight={2}
-        paddingY={1}
-        style={{ height: "1.5625rem", boxSizing: "content-box" }}
-      >
-        <Flex align="center" flex={1} gap={2}>
-          {isDefined(Icon) && (
-            <div
-              style={{
-                display: "flex",
-                alignItems: "center",
-                justifyContent: "center",
-                width: "25px",
-                height: "25px",
-                color: "var(--card-icon-color)",
-              }}
-            >
-              <Icon />
-            </div>
-          )}
-          <Stack flex={1} space={2}>
-            <Text size={1} textOverflow="ellipsis" weight="medium" style={{ color: "inherit" }}>
-              {label}
-            </Text>
-          </Stack>
-          <Box paddingLeft={4} paddingRight={1}>
-            <Box style={{ opacity: 0.5 }}>
-              <Text muted size={1}>
-                <ChevronRightIcon />
-              </Text>
-            </Box>
-          </Box>
-        </Flex>
-      </Flex>
-    </Card>
-  );
-}

package/src/contexts/handbook-context.tsx

@@ -1,84 +0,0 @@
-import { createContext, useContext, useState } from "react";
-import type { ReactNode } from "react";
-
-import { useHandbookConfiguration } from "../hooks/use-handbook-configuration";
-import { isDefined } from "../lib/utils";
-import type { HandbookBlockDefinition, HandbookStructureGroup, SanityHandbook } from "../types";
-
-interface HandbookProviderConfig {
-  /** Heading displayed at the top of the sidebar. */
-  sidebarTitle: string;
-  /** Configured document type groups containing document definitions. */
-  groups: HandbookStructureGroup[];
-  /** Custom block definitions registered by the consumer. */
-  blocks: HandbookBlockDefinition[];
-  /** Fallback message shown when a field has no description. */
-  undocumentedFieldMessage: string;
-}
-
-interface HandbookContextValues extends HandbookProviderConfig {
-  /** Identifier of the currently selected tab, or null if none. */
-  activeTab: string | null;
-  /** Whether the sidebar is currently expanded. */
-  sidebarExpanded: boolean;
-  /** Whether configuration data is still loading from the dataset. */
-  loading: boolean;
-  /** Handbook configuration singleton fetched from the dataset. */
-  configuration: SanityHandbook | null;
-  /** Sets the active tab by identifier. */
-  setActiveTab: (id: string) => void;
-  /** Toggles the sidebar expanded state. */
-  setSidebarExpanded: (expanded: boolean) => void;
-}
-
-interface HandbookProviderProps extends HandbookProviderConfig {
-  /** Child elements wrapped by the provider. */
-  children: ReactNode;
-}
-
-const HandbookContext = createContext<HandbookContextValues | undefined>(undefined);
-
-export function HandbookProvider({
-  sidebarTitle,
-  groups,
-  blocks,
-  undocumentedFieldMessage,
-  children,
-}: HandbookProviderProps) {
-  const [activeTab, setActiveTab] = useState<string | null>(null);
-  const [sidebarExpanded, setSidebarExpanded] = useState(true);
-  const { configuration, loading } = useHandbookConfiguration();
-
-  return (
-    <HandbookContext
-      value={{
-        sidebarTitle,
-        activeTab,
-        sidebarExpanded,
-        loading,
-        groups,
-        configuration,
-        blocks,
-        undocumentedFieldMessage,
-        setActiveTab,
-        setSidebarExpanded,
-      }}
-    >
-      {children}
-    </HandbookContext>
-  );
-}
-
-/**
- * Accesses the Handbook context for tab state and schema configuration.
- *
- * @returns Handbook context values including active tab, groups, and configuration.
- * @throws Error if used outside HandbookProvider.
- */
-export function useHandbookContext() {
-  const handbookContext = useContext(HandbookContext);
-
-  if (!isDefined(handbookContext)) throw new Error("useHandbookContext can only be used within <HandbookProvider>");
-
-  return handbookContext;
-}

package/src/getting-started/document-types.tsx

@@ -1,104 +0,0 @@
-import { ChevronRightIcon } from "@sanity/icons";
-import { Box, Card, Flex, Stack, Text } from "@sanity/ui";
-
-import { useHandbookContext } from "../contexts/handbook-context";
-import { isDefined } from "../lib/utils";
-
-export function DocumentTypesOverview() {
-  const { groups, setActiveTab, setSidebarExpanded } = useHandbookContext();
-
-  return (
-    <div style={{ display: "flex", flexDirection: "column", gap: "2.5rem" }}>
-      {groups.map((group) => {
-        const { title, description, documents } = group;
-
-        return (
-          <Stack key={title} space={2}>
-            <Stack space={3}>
-              <Flex align="center" paddingY={1}>
-                <Text size={1} weight="medium">
-                  {title}
-                </Text>
-              </Flex>
-              {isDefined(description) && (
-                <Text size={1} muted>
-                  {description}
-                </Text>
-              )}
-            </Stack>
-            <Box marginTop={1}>
-              <Stack space={2}>
-                {documents.map((document) => {
-                  const Icon = typeof document.icon === "function" ? document.icon : undefined;
-                  const documentDescription =
-                    document.handbook?.description ??
-                    (typeof document.description === "string" ? document.description : undefined);
-
-                  return (
-                    <Card
-                      key={document.name}
-                      as="button"
-                      padding={3}
-                      radius={2}
-                      sizing="border"
-                      tone="inherit"
-                      onClick={() => {
-                        setActiveTab(document.name);
-                        setSidebarExpanded(false);
-                      }}
-                      style={{
-                        width: "calc(100% + 24px)",
-                        marginLeft: "-12px",
-                        textAlign: "left",
-                        border: "none",
-                        cursor: "pointer",
-                      }}
-                    >
-                      <Flex align="center" gap={3}>
-                        <Box flex={1}>
-                          <Stack space={3}>
-                            <Flex align="center" gap={2} style={{ marginLeft: "-4px" }}>
-                              {isDefined(Icon) && (
-                                <div
-                                  style={{
-                                    display: "flex",
-                                    alignItems: "center",
-                                    justifyContent: "center",
-                                    width: "25px",
-                                    height: "25px",
-                                    color: "var(--card-icon-color)",
-                                  }}
-                                >
-                                  <Icon />
-                                </div>
-                              )}
-                              <Text size={1} weight="medium">
-                                {document.title ?? document.name}
-                              </Text>
-                            </Flex>
-                            {isDefined(documentDescription) && (
-                              <Box paddingBottom={1}>
-                                <Text size={1} muted>
-                                  {documentDescription}
-                                </Text>
-                              </Box>
-                            )}
-                          </Stack>
-                        </Box>
-                        <Box flex="none" style={{ opacity: 0.5 }}>
-                          <Text muted size={1}>
-                            <ChevronRightIcon />
-                          </Text>
-                        </Box>
-                      </Flex>
-                    </Card>
-                  );
-                })}
-              </Stack>
-            </Box>
-          </Stack>
-        );
-      })}
-    </div>
-  );
-}

package/src/getting-started/how-to-use.tsx

@@ -1,95 +0,0 @@
-import { Box, Flex, Stack, 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";
-
-function HintRow({ icon, children }: { icon: ReactNode; children: string }) {
-  return (
-    <Flex align="center" gap={3}>
-      <div
-        style={{
-          display: "flex",
-          alignItems: "center",
-          flexShrink: 0,
-          fontSize: "16px",
-          color: "var(--card-icon-color)",
-        }}
-      >
-        {icon}
-      </div>
-      <Text size={1} muted>
-        {children}
-      </Text>
-    </Flex>
-  );
-}
-
-export function HowToUse() {
-  return (
-    <div style={{ display: "flex", flexDirection: "column", gap: "3rem" }}>
-      <Stack space={3}>
-        <Flex align="center" paddingY={1}>
-          <Text size={1} weight="medium">
-            Navigating the Handbook
-          </Text>
-        </Flex>
-        <Text size={1} muted>
-          Use the sidebar to browse document types and guides. Each entry opens a detailed view in the main panel
-          showing field descriptions, examples, and tips.
-        </Text>
-      </Stack>
-
-      <Stack space={3}>
-        <Flex align="center" paddingY={1}>
-          <Text size={1} weight="medium">
-            Understanding Fields
-          </Text>
-        </Flex>
-        <Text size={1} muted>
-          Each document type lists its fields with a name and type label. Below the name you will find a description
-          explaining what the field is for and how to use it. Some fields include an example value shown in italics.
-        </Text>
-        <Box marginTop={1}>
-          <Text size={1} muted style={{ fontStyle: "italic" }}>
-            e.g. Acme Inc.
-          </Text>
-        </Box>
-      </Stack>
-
-      <Stack space={3}>
-        <Flex align="center" paddingY={1}>
-          <Text size={1} weight="medium">
-            Hints and Warnings
-          </Text>
-        </Flex>
-        <Text size={1} muted>
-          Look for these icons next to field names. Hover or click them to reveal additional guidance.
-        </Text>
-        <Stack space={3} marginTop={2}>
-          <HintRow icon={<LightbulbIcon {...defaultIconProps} />}>
-            Helpful tips and best practices for content editors.
-          </HintRow>
-          <HintRow icon={<InfoIcon {...defaultIconProps} />}>Additional context about how the field is used.</HintRow>
-          <HintRow icon={<TriangleAlertIcon {...defaultIconProps} />}>
-            Important warnings about constraints or potential issues.
-          </HintRow>
-        </Stack>
-      </Stack>
-
-      <Stack space={3}>
-        <Flex align="center" paddingY={1}>
-          <Text size={1} weight="medium">
-            Nested Fields
-          </Text>
-        </Flex>
-        <Text size={1} muted>
-          Some fields contain subfields — for example, a content block might include a heading and body text. These are
-          shown as collapsible sections you can expand to explore the full structure.
-        </Text>
-      </Stack>
-    </div>
-  );
-}

package/src/getting-started/overview.tsx

@@ -1,65 +0,0 @@
-import type { ComponentType, ReactElement } from "react";
-
-import { ContentPanel } from "../components/content-panel";
-import { SidebarGroup } from "../components/sidebar-group";
-import { SidebarTab } from "../components/sidebar-tab";
-import { BookTextIcon } from "../icons/book-text";
-import { LayoutGridIcon } from "../icons/layout-grid";
-import { createSanityIcon } from "../lib/icons";
-import { DocumentTypesOverview } from "./document-types";
-import { HowToUse } from "./how-to-use";
-
-interface HandbookEntry {
-  /** Unique identifier used as the tab and panel key. */
-  name: string;
-  /** Display label in the sidebar. */
-  title: string;
-  /** Icon component shown beside the label. */
-  icon: ComponentType;
-  /** Optional description shown beneath the content heading. */
-  description?: string;
-  /** Component rendered in the content panel. */
-  component: () => ReactElement;
-}
-
-/** Built-in getting started pages shown at the top of the sidebar. */
-const entries: HandbookEntry[] = [
-  {
-    name: "how-to-use-this-handbook",
-    title: "How to Use This Handbook",
-    icon: createSanityIcon(BookTextIcon),
-    description:
-      "A quick guide to navigating the Handbook, understanding the information presented for each field, and making the most of tips, hints, and warnings.",
-    component: HowToUse,
-  },
-  {
-    name: "document-types",
-    title: "Document Types",
-    icon: createSanityIcon(LayoutGridIcon),
-    description:
-      "An overview of all document types, organised by group. Select a document type to view its fields, descriptions, and examples.",
-    component: DocumentTypesOverview,
-  },
-];
-
-export function GettingStartedTabs() {
-  return (
-    <SidebarGroup heading="Getting Started">
-      {entries.map((entry) => (
-        <SidebarTab key={entry.name} id={entry.name} label={entry.title} icon={entry.icon} />
-      ))}
-    </SidebarGroup>
-  );
-}
-
-export function GettingStartedPanels() {
-  return entries.map((entry) => {
-    const { name, title, description, component: Component } = entry;
-
-    return (
-      <ContentPanel key={name} id={name} title={title} description={description}>
-        <Component />
-      </ContentPanel>
-    );
-  });
-}

package/src/hooks/use-container-width.ts

@@ -1,41 +0,0 @@
-import { useEffect, useRef, useState } from "react";
-import type { RefObject } from "react";
-
-import { isDefined } from "../lib/utils";
-
-interface UseContainerWidthReturn<T extends HTMLElement> {
-  /** Ref to attach to the container element being measured. */
-  reference: RefObject<T | null>;
-  /** Measured width in pixels, or undefined before the first observation. */
-  width: number | undefined;
-}
-
-/**
- * Measures the width of a container element using ResizeObserver.
- *
- * @returns An object containing a ref to attach and the measured width.
- */
-export function useContainerWidth<T extends HTMLElement>(): UseContainerWidthReturn<T> {
-  const reference = useRef<T | null>(null);
-  const [width, setWidth] = useState<number | undefined>(undefined);
-
-  useEffect(() => {
-    const element = reference.current;
-
-    if (!isDefined(element)) return undefined;
-
-    const observer = new ResizeObserver((entries) => {
-      for (const entry of entries) {
-        setWidth(entry.contentRect.width);
-      }
-    });
-
-    observer.observe(element);
-
-    return () => {
-      observer.disconnect();
-    };
-  }, []);
-
-  return { reference, width };
-}

package/src/hooks/use-handbook-configuration.ts

@@ -1,74 +0,0 @@
-import { useEffect, useState } from "react";
-import { useClient } from "sanity";
-
-import type { SanityHandbook } from "../types";
-
-interface UseHandbookConfigurationReturn {
-  /** Handbook configuration singleton fetched from the dataset. */
-  configuration: SanityHandbook | null;
-  /** Whether configuration data is still loading from the dataset. */
-  loading: boolean;
-}
-
-/** GROQ query that fetches the handbook singleton with expanded guide references. */
-const query = `*[_type == "handbook.handbook"][0]{
-  groups[]{
-    _key,
-    title,
-    guides[]{
-      _key,
-      ...@->{
-        _id,
-        _type,
-        title,
-        description,
-        content[]{
-          ...,
-          _type == "handbook.image" => {
-            ...,
-            "asset": { "url": asset.asset->url }
-          },
-          _type == "handbook.video" => {
-            ...,
-            "asset": { "url": asset.asset->url }
-          }
-        }
-      }
-    }
-  }
-}`;
-
-/** GROQ filter used to subscribe to real-time changes on handbook documents. */
-const listenQuery = '*[_type == "handbook.handbook" || _type == "handbook.guide"]';
-
-/**
- * Fetches the handbook configuration singleton from the dataset with real-time updates.
- * Expands guide references within each group.
- *
- * @returns An object containing the configuration and a loading flag.
- */
-export function useHandbookConfiguration(): UseHandbookConfigurationReturn {
-  const client = useClient({ apiVersion: "2026-01-01" });
-  const [configuration, setConfiguration] = useState<SanityHandbook | null>(null);
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    async function fetchConfiguration() {
-      const result = await client.fetch<SanityHandbook | null>(query);
-      setConfiguration(result);
-      setLoading(false);
-    }
-
-    void fetchConfiguration();
-
-    const subscription = client.listen(listenQuery).subscribe(() => {
-      void fetchConfiguration();
-    });
-
-    return () => {
-      subscription.unsubscribe();
-    };
-  }, [client]);
-
-  return { configuration, loading };
-}

package/src/hooks/use-is-handbook-editor.ts

@@ -1,18 +0,0 @@
-import { useCurrentUser } from "sanity";
-
-import { isPermittedEditor } from "../lib/utils";
-
-/**
- * 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 function useIsHandbookEditor(editors?: string[]) {
-  const user = useCurrentUser();
-
-  return isPermittedEditor(editors, user?.email);
-}

package/src/icons/book-open-text.tsx

@@ -1,22 +0,0 @@
-import type { SVGProps } from "react";
-
-export function BookOpenTextIcon(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="M12 7v14" />
-      <path d="M16 12h2" />
-      <path d="M16 8h2" />
-      <path d="M3 18a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h5a4 4 0 0 1 4 4 4 4 0 0 1 4-4h5a1 1 0 0 1 1 1v13a1 1 0 0 1-1 1h-6a3 3 0 0 0-3 3 3 3 0 0 0-3-3z" />
-      <path d="M6 12h2" />
-      <path d="M6 8h2" />
-    </svg>
-  );
-}

package/src/icons/book-text.tsx

@@ -1,19 +0,0 @@
-import type { SVGProps } from "react";
-
-export function BookTextIcon(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="M4 19.5v-15A2.5 2.5 0 0 1 6.5 2H19a1 1 0 0 1 1 1v18a1 1 0 0 1-1 1H6.5a1 1 0 0 1 0-5H20" />
-      <path d="M8 11h8" />
-      <path d="M8 7h6" />
-    </svg>
-  );
-}

package/src/icons/code.tsx

@@ -1,18 +0,0 @@
-import type { SVGProps } from "react";
-
-export function CodeIcon(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 18 6-6-6-6" />
-      <path d="m8 6-6 6 6 6" />
-    </svg>
-  );
-}