jamdesk 1.0.0

package/vendored/lib/docs-types.ts

@@ -0,0 +1,874 @@
+// Types and client-safe utilities for docs configuration
+// This file contains no Node.js-specific imports and can be used in client components
+// Updated to support the new hierarchical docs.json schema
+
+// =============================================================================
+// ASSET PATH CONSTANTS
+// =============================================================================
+
+/**
+ * Asset prefix for Jamdesk project assets.
+ *
+ * All project images and assets are served under this prefix to avoid conflicts
+ * with customer site paths when using Cloudflare Workers for subpath hosting.
+ * For example, a customer hosting docs at example.com/docs won't have their
+ * /images/ path conflict with documentation images.
+ */
+export const ASSET_PREFIX = '/_jd';
+
+// =============================================================================
+// THEME TYPES
+// =============================================================================
+
+/**
+ * Available themes
+ */
+export type ThemeName = 'jam' | 'nebula' | 'pulsar';
+
+// =============================================================================
+// ICON TYPES
+// =============================================================================
+
+/**
+ * Icon style options for FontAwesome
+ */
+export type IconStyle = 
+  | 'brands' 
+  | 'duotone' 
+  | 'light' 
+  | 'regular' 
+  | 'sharp-duotone-solid' 
+  | 'sharp-light' 
+  | 'sharp-regular' 
+  | 'sharp-solid' 
+  | 'sharp-thin' 
+  | 'solid' 
+  | 'thin';
+
+/**
+ * Icon library options
+ */
+export type IconLibrary = 'fontawesome' | 'lucide';
+
+/**
+ * Icon configuration - can be a string or object with style/library
+ */
+export interface IconConfigObject {
+  name: string;
+  style?: IconStyle;
+  library?: IconLibrary;
+}
+
+export type IconConfig = string | IconConfigObject;
+
+// =============================================================================
+// COLOR TYPES
+// =============================================================================
+
+/**
+ * Color configuration for light/dark themes
+ */
+export interface ColorPair {
+  light?: string;
+  dark?: string;
+}
+
+/**
+ * Colors configuration
+ */
+export interface ColorsConfig {
+  primary: string;
+  light?: string;
+  dark?: string;
+}
+
+// =============================================================================
+// LOGO & FAVICON TYPES
+// =============================================================================
+
+/**
+ * Logo configuration - can be a string path or object with light/dark variants
+ */
+export interface LogoConfig {
+  light: string;
+  dark?: string;
+  href?: string;
+}
+
+export type Logo = LogoConfig | string;
+
+/**
+ * Favicon configuration - can be a string or object with light/dark variants
+ */
+export interface FaviconConfig {
+  light: string;
+  dark: string;
+}
+
+export type Favicon = FaviconConfig | string;
+
+// =============================================================================
+// FONT TYPES
+// =============================================================================
+
+/**
+ * Single font configuration
+ */
+export interface SingleFontConfig {
+  family: string;
+  weight?: number;
+  source?: string;
+  format?: 'woff' | 'woff2';
+}
+
+/**
+ * Font configuration for heading/body split
+ */
+export interface HeadingBodyFontConfig {
+  heading?: SingleFontConfig;
+  body?: SingleFontConfig;
+}
+
+/**
+ * Font configuration - can be a single font or heading/body split
+ * Legacy support: { primary?: string; mono?: string }
+ */
+export type FontConfig = SingleFontConfig | HeadingBodyFontConfig | {
+  primary?: string;
+  mono?: string;
+};
+
+// =============================================================================
+// NAVIGATION TYPES - PAGES AND GROUPS
+// =============================================================================
+
+/**
+ * Page with optional method and title (for API endpoints)
+ */
+export interface NavigationPageObject {
+  page: string;
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  title?: string;
+  icon?: IconConfig;
+  tag?: string;
+}
+
+/**
+ * A page can be a string path or an object with additional metadata
+ */
+export type NavigationPage = string | NavigationPageObject;
+
+/**
+ * Group configuration - can contain pages and nested groups
+ */
+export interface GroupConfig {
+  group: string;
+  icon?: IconConfig;
+  hidden?: boolean;
+  root?: string;
+  tag?: string;
+  expanded?: boolean;
+  public?: boolean;
+  pages?: (NavigationPage | GroupConfig)[];
+  openapi?: string | string[];
+  asyncapi?: string | string[];
+}
+
+// =============================================================================
+// NAVIGATION TYPES - TABS, ANCHORS, ETC.
+// =============================================================================
+
+/**
+ * Tab position options
+ * - 'top': Tabs appear in header/tab bar
+ * - 'left': Tabs appear at top of sidebar
+ */
+export type TabsPosition = 'top' | 'left';
+
+/**
+ * External link anchor - appears at top of sidebar on all pages
+ * These are simple external navigation links, NOT content sections
+ */
+export interface ExternalAnchorConfig {
+  name: string;
+  href: string;
+  icon?: IconConfig;
+}
+
+/**
+ * Tab configuration
+ */
+export interface TabConfig {
+  tab: string;
+  icon?: IconConfig;
+  hidden?: boolean;
+  href?: string;
+  groups?: GroupConfig[];
+  pages?: (NavigationPage | GroupConfig)[];
+  // Can also have nested structures (anchors removed - use tabs instead)
+  dropdowns?: DropdownConfig[];
+  products?: ProductConfig[];
+  menu?: MenuItemConfig[];
+  openapi?: string | string[];
+  asyncapi?: string | string[];
+}
+
+/**
+ * Anchor configuration (top-level navigation sections)
+ * @deprecated Use TabConfig instead. Anchors in navigation are deprecated.
+ * For external links, use the top-level `anchors` field with ExternalAnchorConfig.
+ */
+export interface AnchorConfig {
+  anchor: string;
+  icon?: IconConfig;
+  color?: ColorPair;
+  hidden?: boolean;
+  href?: string;
+  groups?: GroupConfig[];
+  pages?: (NavigationPage | GroupConfig)[];
+  tabs?: TabConfig[];
+  versions?: VersionConfig[];
+  languages?: LanguageConfig[];
+  dropdowns?: DropdownConfig[];
+  products?: ProductConfig[];
+  openapi?: string | string[];
+  asyncapi?: string | string[];
+  global?: GlobalConfig;
+}
+
+/**
+ * Dropdown configuration
+ */
+export interface DropdownConfig {
+  dropdown: string;
+  icon?: IconConfig;
+  color?: ColorPair;
+  description?: string;
+  hidden?: boolean;
+  href?: string;
+  groups?: GroupConfig[];
+  pages?: (NavigationPage | GroupConfig)[];
+  tabs?: TabConfig[];
+  anchors?: AnchorConfig[];
+  products?: ProductConfig[];
+  versions?: VersionConfig[];
+  languages?: LanguageConfig[];
+  openapi?: string | string[];
+  asyncapi?: string | string[];
+}
+
+/**
+ * Product configuration (for multi-product docs)
+ */
+export interface ProductConfig {
+  product: string;
+  name?: string;
+  icon?: IconConfig;
+  color?: ColorPair;
+  description?: string;
+  hidden?: boolean;
+  href?: string;
+  groups?: GroupConfig[];
+  pages?: (NavigationPage | GroupConfig)[];
+  tabs?: TabConfig[];
+  anchors?: AnchorConfig[];
+  dropdowns?: DropdownConfig[];
+  versions?: VersionConfig[];
+  languages?: LanguageConfig[];
+  openapi?: string | string[];
+  asyncapi?: string | string[];
+}
+
+/**
+ * Menu item configuration
+ */
+export interface MenuItemConfig {
+  item: string;
+  icon?: IconConfig;
+  description?: string;
+  hidden?: boolean;
+  href?: string;
+  groups?: GroupConfig[];
+  pages?: (NavigationPage | GroupConfig)[];
+  openapi?: string | string[];
+  asyncapi?: string | string[];
+}
+
+/**
+ * Version configuration
+ */
+export interface VersionConfig {
+  version: string;
+  default?: boolean;
+  hidden?: boolean;
+  href?: string;
+  groups?: GroupConfig[];
+  pages?: (NavigationPage | GroupConfig)[];
+  tabs?: TabConfig[];
+  anchors?: AnchorConfig[];
+  dropdowns?: DropdownConfig[];
+  products?: ProductConfig[];
+  languages?: LanguageConfig[];
+  openapi?: string | string[];
+  asyncapi?: string | string[];
+}
+
+/**
+ * Supported language codes
+ */
+export type LanguageCode = 
+  | 'en' | 'cn' | 'zh' | 'zh-Hans' | 'zh-Hant' 
+  | 'es' | 'fr' | 'fr-CA' | 'fr-ca' 
+  | 'ja' | 'jp' | 'ja-jp' 
+  | 'pt' | 'pt-BR' | 'de' | 'ko' | 'it' | 'ru' | 'ro' 
+  | 'cs' | 'id' | 'ar' | 'tr' | 'hi' | 'sv' | 'no' 
+  | 'lv' | 'nl' | 'uk' | 'vi' | 'pl' | 'uz' | 'he';
+
+/**
+ * Language configuration
+ */
+export interface LanguageConfig {
+  language: LanguageCode;
+  default?: boolean;
+  hidden?: boolean;
+  href?: string;
+  groups?: GroupConfig[];
+  pages?: (NavigationPage | GroupConfig)[];
+  tabs?: TabConfig[];
+  anchors?: AnchorConfig[];
+  dropdowns?: DropdownConfig[];
+  products?: ProductConfig[];
+  versions?: VersionConfig[];
+  banner?: BannerConfig;
+  openapi?: string | string[];
+  asyncapi?: string | string[];
+}
+
+/**
+ * Global navigation configuration
+ */
+export interface GlobalConfig {
+  languages?: Array<{ language: LanguageCode; default?: boolean; hidden?: boolean; href: string }>;
+  versions?: Array<{ version: string; default?: boolean; hidden?: boolean; href: string }>;
+  tabs?: Array<{ tab: string; icon?: IconConfig; hidden?: boolean; href: string }>;
+  dropdowns?: Array<{ dropdown: string; icon?: IconConfig; color?: ColorPair; description?: string; hidden?: boolean; href: string }>;
+  anchors?: Array<{ anchor: string; icon?: IconConfig; color?: ColorPair; hidden?: boolean; href: string }>;
+  products?: Array<{ product: string; name?: string; icon?: IconConfig; color?: ColorPair; description?: string; hidden?: boolean; href: string }>;
+}
+
+// =============================================================================
+// NAVIGATION CONFIG (TOP-LEVEL)
+// =============================================================================
+
+/**
+ * Navigation configuration - one of these structures
+ */
+export interface NavigationConfig {
+  global?: GlobalConfig;
+  /**
+   * @deprecated Use `tabs` instead. Anchors with content should be converted to tabs.
+   * For external links, use the top-level `anchors` field in DocsConfig.
+   */
+  anchors?: AnchorConfig[];
+  tabs?: TabConfig[];
+  groups?: GroupConfig[];
+  pages?: (NavigationPage | GroupConfig)[];
+  products?: ProductConfig[];
+  dropdowns?: DropdownConfig[];
+  versions?: VersionConfig[];
+  languages?: LanguageConfig[];
+  openapi?: string | string[];
+  asyncapi?: string | string[];
+}
+
+// =============================================================================
+// NAVBAR & FOOTER TYPES
+// =============================================================================
+
+/**
+ * Navbar link
+ */
+export interface NavbarLink {
+  label: string;
+  icon?: IconConfig;
+  href: string;
+}
+
+/**
+ * Navbar primary button/action
+ */
+export interface NavbarPrimary {
+  type: 'button' | 'github';
+  label?: string;
+  href: string;
+}
+
+/**
+ * Mintlify navbar style (accepted for compatibility, ignored in rendering)
+ */
+export type NavbarStyle = 'default' | 'topOfContent';
+
+/**
+ * Navbar configuration
+ */
+export interface NavbarConfig {
+  links?: NavbarLink[];
+  primary?: NavbarPrimary;
+  style?: NavbarStyle;  // Mintlify compat - accepted but ignored
+}
+
+/**
+ * Footer social media platforms
+ */
+export type SocialPlatform = 
+  | 'x' | 'website' | 'facebook' | 'youtube' | 'discord' | 'slack' 
+  | 'github' | 'linkedin' | 'instagram' | 'hacker-news' | 'medium' 
+  | 'telegram' | 'twitter' | 'x-twitter' | 'earth-americas' 
+  | 'bluesky' | 'threads' | 'reddit' | 'podcast';
+
+/**
+ * Footer link item
+ */
+export interface FooterLinkItem {
+  label: string;
+  href: string;
+}
+
+/**
+ * Footer link column
+ */
+export interface FooterLinkColumn {
+  header?: string;
+  items: FooterLinkItem[];
+}
+
+/**
+ * Footer configuration
+ */
+export interface FooterConfig {
+  socials?: Partial<Record<SocialPlatform, string>>;
+  links?: FooterLinkColumn[];
+}
+
+// =============================================================================
+// PAGE FRONTMATTER
+// =============================================================================
+
+/**
+ * MDX page frontmatter fields
+ * Used in page.tsx for type-safe access to frontmatter data
+ */
+export interface PageFrontmatter {
+  title?: string;
+  description?: string;
+  sidebarTitle?: string;
+  icon?: string;
+  mode?: 'wide';
+  api?: string;
+  openapi?: string;
+  hideFooter?: boolean;
+}
+
+// =============================================================================
+// API CONFIGURATION
+// =============================================================================
+
+/**
+ * API authentication method
+ */
+export type ApiAuthMethod = 'bearer' | 'basic' | 'key' | 'cobo';
+
+/**
+ * API playground display mode
+ */
+export type ApiPlaygroundDisplay = 'interactive' | 'simple' | 'none';
+
+/**
+ * API configuration
+ */
+export interface ApiConfig {
+  openapi?: string | string[];
+  asyncapi?: string | string[];
+  params?: {
+    expanded?: 'all' | 'closed';
+  };
+  playground?: {
+    display?: ApiPlaygroundDisplay;
+    proxy?: boolean;
+  };
+  examples?: {
+    defaults?: 'required' | 'all';
+    languages?: string[];
+    prefill?: boolean;
+  };
+  mdx?: {
+    auth?: {
+      method?: ApiAuthMethod;
+      name?: string;
+    };
+    server?: string | string[];
+  };
+}
+
+// =============================================================================
+// APPEARANCE & STYLING
+// =============================================================================
+
+/**
+ * Appearance configuration
+ */
+export interface AppearanceConfig {
+  default?: 'system' | 'light' | 'dark';
+  strict?: boolean;
+}
+
+/**
+ * Mintlify modeToggle configuration (backward compatibility)
+ * Maps to AppearanceConfig at runtime
+ */
+export interface ModeToggleConfig {
+  default?: 'dark' | 'light';
+  isHidden?: boolean;
+}
+
+/**
+ * Mintlify layout type (accepted for compatibility, ignored - theme determines layout)
+ */
+export type MintlifyLayout = 'sidenav' | 'topnav';
+
+/**
+ * Background configuration
+ */
+export interface BackgroundConfig {
+  image?: string | { light: string; dark: string };
+  decoration?: 'gradient' | 'grid' | 'windows';
+  color?: ColorPair;
+}
+
+/**
+ * Styling configuration
+ */
+export interface StylingConfig {
+  eyebrows?: 'section' | 'breadcrumbs';
+  codeblocks?: 'system' | 'dark' | {
+    theme?: string | { light: string; dark: string };
+    languages?: { custom?: string[] };
+  };
+  latex?: boolean;
+  /**
+   * Enable typography enhancements (smart quotes, dashes, ellipses).
+   * Uses remark-smartypants to convert:
+   * - "quotes" → "curly quotes"
+   * - -- → en-dash (–)
+   * - --- → em-dash (—)
+   * - ... → ellipsis (…)
+   *
+   * Default: false (disabled for performance).
+   * Note: May interfere with code examples containing quote characters.
+   */
+  typography?: boolean;
+}
+
+// =============================================================================
+// INTEGRATIONS
+// =============================================================================
+
+/**
+ * Analytics and integration configurations (stubs - TODO: implement)
+ */
+export interface IntegrationsConfig {
+  ga4?: { measurementId: string };
+  amplitude?: { apiKey: string };
+  clarity?: { projectId: string };
+  clearbit?: { publicApiKey: string };
+  fathom?: { siteId: string };
+  frontchat?: { snippetId: string };
+  gtm?: { tagId: string };
+  heap?: { appId: string };
+  hightouch?: { writeKey: string; apiHost?: string };
+  hotjar?: { hjid: string; hjsv: string };
+  intercom?: { appId: string };
+  koala?: { publicApiKey: string };
+  logrocket?: { appId: string };
+  mixpanel?: { projectToken: string };
+  osano?: { scriptSource: string };
+  pirsch?: { id: string };
+  posthog?: { apiKey: string; apiHost?: string };
+  plausible?: { domain: string; server?: string };
+  segment?: { key: string };
+  telemetry?: { enabled: boolean };
+  cookies?: { key?: string; value?: string };
+}
+
+// =============================================================================
+// OTHER CONFIGURATION
+// =============================================================================
+
+/**
+ * Search configuration
+ */
+export interface SearchConfig {
+  prompt?: string;
+  /** Popular pages to show in search empty state */
+  popularPages?: Array<{
+    title: string;
+    slug: string;
+    icon?: string;
+  }>;
+}
+
+/**
+ * SEO configuration
+ */
+export interface SeoConfig {
+  metatags?: Record<string, string>;
+  indexing?: 'navigable' | 'all';
+  /** Include hidden pages in sitemap (default: false) */
+  indexHiddenPages?: boolean;
+}
+
+/**
+ * Redirect configuration
+ */
+export interface RedirectConfig {
+  source: string;
+  destination: string;
+  permanent?: boolean;
+}
+
+/**
+ * Banner configuration
+ */
+export interface BannerConfig {
+  content: string;
+  dismissible?: boolean;
+}
+
+/**
+ * Error page configuration
+ */
+export interface ErrorsConfig {
+  '404'?: {
+    redirect?: boolean;
+    title?: string;
+    description?: string;
+  };
+}
+
+/**
+ * Contextual option - built-in or custom
+ */
+export type ContextualOption = 
+  | 'copy' | 'view' | 'chatgpt' | 'claude' | 'perplexity' 
+  | 'mcp' | 'cursor' | 'vscode'
+  | {
+      title: string;
+      description: string;
+      icon?: IconConfig;
+      href: string | { base: string; query?: Array<{ key: string; value: string }> };
+    };
+
+/**
+ * Contextual menu configuration
+ */
+export interface ContextualConfig {
+  options: ContextualOption[];
+}
+
+/**
+ * Thumbnail configuration
+ */
+export interface ThumbnailsConfig {
+  appearance?: 'light' | 'dark';
+  background?: string;
+  fonts?: { family: string };
+}
+
+/**
+ * Interaction configuration
+ */
+export interface InteractionConfig {
+  drilldown?: boolean;
+}
+
+/**
+ * Metadata configuration
+ */
+export interface MetadataConfig {
+  timestamp?: boolean;
+}
+
+/**
+ * Icons library configuration
+ */
+export interface IconsConfig {
+  library: IconLibrary;
+}
+
+/**
+ * Analytics configuration
+ */
+export interface AnalyticsConfig {
+  /** Enable/disable Jamdesk analytics (default: true) */
+  enabled?: boolean;
+}
+
+// =============================================================================
+// MAIN DOCS CONFIG
+// =============================================================================
+
+/**
+ * Main documentation configuration
+ * Only supports the new hierarchical format
+ */
+export interface DocsConfig {
+  // Schema reference
+  $schema?: string;
+
+  // Required fields
+  theme: ThemeName;
+  name: string;
+  colors: ColorsConfig;
+  navigation: NavigationConfig;
+
+  // Optional fields
+  description?: string;
+  favicon?: Favicon;
+  logo?: Logo;
+
+  // Tab position - controls where tabs are displayed
+  // 'top': Tabs in header/tab bar (default for pulsar)
+  // 'left': Tabs at top of sidebar (default for jam/nebula)
+  tabsPosition?: TabsPosition;
+
+  // External link anchors - appear at top of sidebar on all pages
+  anchors?: ExternalAnchorConfig[];
+
+  // Navigation helpers
+  navbar?: NavbarConfig;
+  footer?: FooterConfig;
+  
+  // API configuration
+  api?: ApiConfig;
+  
+  // Appearance
+  appearance?: AppearanceConfig;
+  background?: BackgroundConfig;
+  
+  // Search & SEO
+  search?: SearchConfig;
+  seo?: SeoConfig;
+  
+  // Styling
+  fonts?: FontConfig;
+  icons?: IconsConfig;
+  styling?: StylingConfig;
+  
+  // Features
+  redirects?: RedirectConfig[];
+  integrations?: IntegrationsConfig;
+  banner?: BannerConfig;
+  errors?: ErrorsConfig;
+  contextual?: ContextualConfig;
+  thumbnails?: ThumbnailsConfig;
+  interaction?: InteractionConfig;
+  metadata?: MetadataConfig;
+  analytics?: AnalyticsConfig;
+
+  // Mintlify compatibility fields (normalized at load time)
+  modeToggle?: ModeToggleConfig;
+  layout?: MintlifyLayout;
+
+  // Auto-detected at build time
+  _hasCustomCss?: boolean;
+  _hasCustomJs?: boolean;
+
+  // Runtime: Set by ISR middleware based on project config
+  // When true, all navigation links should be prefixed with /docs
+  hostAtDocs?: boolean;
+}
+
+// =============================================================================
+// HELPER FUNCTIONS
+// =============================================================================
+
+/**
+ * Helper to normalize navigation page to consistent format
+ */
+export function normalizeNavPage(page: NavigationPage): {
+  path: string;
+  method?: string;
+  title: string;
+  icon?: string;
+  tag?: string;
+} {
+  if (typeof page === 'string') {
+    return {
+      path: page,
+      title: page
+        .split('/')
+        .pop()
+        ?.replace(/-/g, ' ')
+        .replace(/\b\w/g, (l) => l.toUpperCase()) || page,
+    };
+  }
+  return {
+    path: page.page,
+    method: page.method,
+    title: page.title || page.page
+      .split('/')
+      .pop()
+      ?.replace(/-/g, ' ')
+      .replace(/\b\w/g, (l) => l.toUpperCase()) || page.page,
+    icon: getIconName(page.icon),
+    tag: page.tag,
+  };
+}
+
+/**
+ * Transform an image path from /images/... to /_jd/images/...
+ *
+ * Used for config-defined images (favicon, logo) that need the asset prefix.
+ */
+export function transformConfigImagePath(path: string | undefined): string | undefined {
+  if (!path) return path;
+  if (path.startsWith('/images/')) {
+    return ASSET_PREFIX + path;
+  }
+  return path;
+}
+
+/**
+ * Normalize logo config to consistent object format.
+ * Also transforms /images/... paths to /_jd/images/...
+ */
+export function normalizeLogo(logo: Logo | undefined): LogoConfig | null {
+  if (!logo) return null;
+  if (typeof logo === 'string') {
+    return { light: transformConfigImagePath(logo)! };
+  }
+  return {
+    ...logo,
+    light: transformConfigImagePath(logo.light)!,
+    dark: transformConfigImagePath(logo.dark),
+  };
+}
+
+
+/**
+ * Normalize icon config to get the icon name string
+ */
+export function getIconName(icon: IconConfig | undefined): string | undefined {
+  if (!icon) return undefined;
+  if (typeof icon === 'string') return icon;
+  return icon.name;
+}
+
+/**
+ * Get icon library from config
+ */
+export function getIconLibrary(icon: IconConfig | undefined): IconLibrary | undefined {
+  if (!icon) return undefined;
+  if (typeof icon === 'string') return undefined;
+  return icon.library;
+}