@clidey/dory 0.30.0 → 0.33.0

package/src/sdk/react.tsx

@@ -0,0 +1,139 @@
+/**
+ * React SDK for Dory Embedded Documentation
+ * Usage: npm install @clidey/dory-embedded
+ */
+
+import { useEffect, useRef, useCallback } from 'react';
+import type { DoryDocsAPI } from '../embed/types';
+
+interface DoryDocsConfig {
+  docsUrl: string;
+  position?: 'left' | 'right' | 'bottom';
+  width?: number | string;
+  height?: string;
+  theme?: 'light' | 'dark' | 'inherit';
+  initialPath?: string;
+  showOverlay?: boolean;
+  closeOnEscape?: boolean;
+  closeOnOverlayClick?: boolean;
+  onOpen?: () => void;
+  onClose?: () => void;
+  onNavigate?: (path: string) => void;
+  onReady?: () => void;
+}
+
+/**
+ * Hook to use Dory Documentation in React components
+ */
+export function useDoryDocs(config: DoryDocsConfig) {
+  const docsRef = useRef<any>(null);
+  const configRef = useRef(config);
+
+  useEffect(() => {
+    configRef.current = config;
+  }, [config]);
+
+  useEffect(() => {
+    // Wait for DoryDocs to be available
+    const checkDoryDocs = () => {
+      if (window.DoryDocs) {
+        docsRef.current = window.DoryDocs.init(configRef.current);
+      } else {
+        console.warn('[useDoryDocs] DoryDocs not loaded. Make sure to include the embed script.');
+      }
+    };
+
+    if (document.readyState === 'loading') {
+      window.addEventListener('dory:ready', checkDoryDocs);
+    } else {
+      checkDoryDocs();
+    }
+
+    return () => {
+      window.removeEventListener('dory:ready', checkDoryDocs);
+      docsRef.current?.destroy();
+    };
+  }, []);
+
+  const open = useCallback((path?: string) => {
+    return docsRef.current?.open(path);
+  }, []);
+
+  const close = useCallback(() => {
+    return docsRef.current?.close();
+  }, []);
+
+  const toggle = useCallback(() => {
+    return docsRef.current?.toggle();
+  }, []);
+
+  const navigate = useCallback((path: string) => {
+    return docsRef.current?.navigate(path);
+  }, []);
+
+  const setTheme = useCallback((theme: 'light' | 'dark') => {
+    return docsRef.current?.setTheme(theme);
+  }, []);
+
+  const isOpen = useCallback(() => {
+    return docsRef.current?.isOpen() || false;
+  }, []);
+
+  return {
+    open,
+    close,
+    toggle,
+    navigate,
+    setTheme,
+    isOpen,
+  };
+}
+
+/**
+ * Component that renders a trigger button for Dory Documentation
+ */
+export function DoryDocsTrigger({
+  children,
+  config,
+  className,
+  path,
+}: {
+  children: React.ReactNode;
+  config: DoryDocsConfig;
+  className?: string;
+  path?: string;
+}) {
+  const docs = useDoryDocs(config);
+
+  const handleClick = () => {
+    docs.open(path);
+  };
+
+  return (
+    <button onClick={handleClick} className={className}>
+      {children}
+    </button>
+  );
+}
+
+/**
+ * Component that initializes Dory Documentation without rendering anything
+ */
+export function DoryDocsProvider({
+  config,
+  children,
+}: {
+  config: DoryDocsConfig;
+  children: React.ReactNode;
+}) {
+  useDoryDocs(config);
+
+  return <>{children}</>;
+}
+
+// Type declarations
+declare global {
+  interface Window {
+    DoryDocs: DoryDocsAPI;
+  }
+}

package/src/sdk/vue.ts

@@ -0,0 +1,107 @@
+/**
+ * Vue SDK for Dory Embedded Documentation
+ * Usage: npm install @clidey/dory-embedded
+ */
+
+// @ts-ignore - Vue is an optional peer dependency
+import { ref, onMounted, onUnmounted, computed } from 'vue';
+import type { DoryDocsAPI } from '../embed/types';
+
+interface DoryDocsConfig {
+  docsUrl: string;
+  position?: 'left' | 'right' | 'bottom';
+  width?: number | string;
+  height?: string;
+  theme?: 'light' | 'dark' | 'inherit';
+  initialPath?: string;
+  showOverlay?: boolean;
+  closeOnEscape?: boolean;
+  closeOnOverlayClick?: boolean;
+  onOpen?: () => void;
+  onClose?: () => void;
+  onNavigate?: (path: string) => void;
+  onReady?: () => void;
+}
+
+/**
+ * Composable to use Dory Documentation in Vue components
+ */
+export function useDoryDocs(config: DoryDocsConfig) {
+  const docsInstance = ref<any>(null);
+  const isReady = ref(false);
+
+  const initDocs = () => {
+    if (window.DoryDocs) {
+      docsInstance.value = window.DoryDocs.init(config);
+      isReady.value = true;
+    } else {
+      console.warn('[useDoryDocs] DoryDocs not loaded. Make sure to include the embed script.');
+    }
+  };
+
+  onMounted(() => {
+    if (document.readyState === 'loading') {
+      window.addEventListener('dory:ready', initDocs);
+    } else {
+      initDocs();
+    }
+  });
+
+  onUnmounted(() => {
+    window.removeEventListener('dory:ready', initDocs);
+    if (docsInstance.value) {
+      docsInstance.value.destroy();
+    }
+  });
+
+  const open = async (path?: string) => {
+    if (docsInstance.value) {
+      await docsInstance.value.open(path);
+    }
+  };
+
+  const close = async () => {
+    if (docsInstance.value) {
+      await docsInstance.value.close();
+    }
+  };
+
+  const toggle = async () => {
+    if (docsInstance.value) {
+      await docsInstance.value.toggle();
+    }
+  };
+
+  const navigate = async (path: string) => {
+    if (docsInstance.value) {
+      await docsInstance.value.navigate(path);
+    }
+  };
+
+  const setTheme = async (theme: 'light' | 'dark') => {
+    if (docsInstance.value) {
+      await docsInstance.value.setTheme(theme);
+    }
+  };
+
+  const isOpen = computed(() => {
+    return docsInstance.value?.isOpen() || false;
+  });
+
+  return {
+    open,
+    close,
+    toggle,
+    navigate,
+    setTheme,
+    isOpen: isOpen.value,
+    isReady,
+  };
+}
+
+// Type declarations
+declare global {
+  interface Window {
+    DoryDocs: DoryDocsAPI;
+  }
+}

package/src/theme.scss

@@ -0,0 +1,72 @@
+:root {
+    font-synthesis: none;
+    text-rendering: optimizeLegibility;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+
+    // Brand colors (dynamically set from dory.json via loadColors())
+    // These variables are set at runtime:
+    // --brand-primary: primary color
+    // --brand-light: light mode accent
+    // --brand-dark: dark mode accent
+    // --brand-foreground: legacy/fallback (set to primary)
+
+    // Default fallback colors (will be overridden by loadColors())
+    --brand-foreground: #0ea5e9;
+    --brand-primary: #0ea5e9;
+    --brand-light: #38bdf8;
+    --brand-dark: #0284c7;
+
+    // ShadCN/clidey/ux compatible primary color
+    // Using light color for light mode
+    --primary: var(--brand-light);
+    --primary-rgb: var(--brand-light-rgb);
+    
+    --ring: rgba(0, 0, 0, 0.1);
+}
+
+// Dark mode overrides
+:root.dark {
+    // Use dark color for dark mode
+    --primary: var(--brand-dark);
+    --primary-rgb: var(--brand-dark-rgb);
+
+    --ring: rgba(255, 255, 255, 0.1);
+}
+  
+article h2:first-of-type {
+    display: none;
+}
+
+article hr:first-of-type {
+    display: none;
+}
+
+article img {
+    margin-top: 1rem;
+    margin-bottom: 1rem;
+}
+
+[data-testid="header-actions"] button,
+[data-slot="dropdown-menu-content"] {
+    border-color: var(--ring);
+}
+
+[data-slot="search-input-wrapper"] {
+    font-size: 12px;
+    outline: none;
+}
+
+[data-slot="search-input"] {
+    font-size: 12px;
+}
+
+[data-slot="search-input-wrapper"]:focus-within {
+    outline: none !important;
+}
+
+[role="dialog"] [data-slot="search-input-wrapper"]:focus-within {
+    outline: none !important;
+    border: 0px;
+    box-shadow: none !important;
+}

package/src/types/config.ts

@@ -0,0 +1,89 @@
+/**
+ * TypeScript interfaces for dory.json configuration
+ */
+
+export interface DoryColors {
+  primary: string;
+  light: string;
+  dark: string;
+}
+
+export interface DoryFonts {
+  family: string;
+  source: string;
+  format: string;
+}
+
+export interface DoryLogo {
+  light: string;
+  dark: string;
+}
+
+export interface DoryNavigationPage {
+  [key: string]: string;
+}
+
+export interface DoryNavigationGroup {
+  group: string;
+  pages: string[];
+}
+
+export interface DoryNavigationTab {
+  tab: string;
+  groups: DoryNavigationGroup[];
+}
+
+export interface DoryNavigation {
+  tabs: DoryNavigationTab[];
+}
+
+export interface DoryEmbedConfig {
+  enabled?: boolean;
+  version?: string;
+  defaults?: {
+    position?: 'left' | 'right' | 'bottom';
+    width?: number;
+    height?: string;
+    theme?: 'light' | 'dark' | 'inherit';
+    showOverlay?: boolean;
+    closeOnEscape?: boolean;
+    closeOnOverlayClick?: boolean;
+  };
+  branding?: {
+    showLogo?: boolean;
+    showName?: boolean;
+    customCSS?: string;
+  };
+  features?: {
+    search?: boolean;
+    toc?: boolean;
+    codeBlocks?: boolean;
+    mermaid?: boolean;
+    katex?: boolean;
+    apiPlayground?: boolean;
+    darkMode?: boolean;
+  };
+  analytics?: {
+    enabled?: boolean;
+    trackEvents?: string[];
+  };
+  security?: {
+    allowedOrigins?: string[];
+    corsEnabled?: boolean;
+  };
+  performance?: {
+    lazyLoadImages?: boolean;
+    prefetchPages?: boolean;
+    cacheStrategy?: 'cache-first' | 'network-first';
+  };
+}
+
+export interface DoryConfig {
+  name: string;
+  favicon: string;
+  colors?: DoryColors;
+  fonts?: DoryFonts;
+  navigation: DoryNavigation;
+  logo: DoryLogo;
+  embed?: DoryEmbedConfig;
+}

package/src/ui/header.tsx

@@ -0,0 +1,96 @@
+import classNames from 'classnames';
+import { useEffect, useMemo, useState } from 'preact/hooks';
+import { Link } from 'wouter-preact';
+import { usePathname } from 'wouter-preact/use-browser-location';
+import docsConfig from '../../docs/dory.json' with { type: 'json' };
+import type { DoryConfig } from '../types/config';
+import { MobileSearch, Search } from '../components/search';
+import { ALL_NAVIGATION } from '../components/store';
+import { MobileNavigation } from './mobile-navigation';
+import { ModeToggle } from '@clidey/ux';
+import { useIsEmbedded } from '../components/hooks';
+
+const config = docsConfig as DoryConfig;
+
+function TopLevelNavItem({ href, children, isActive }: { href: string; children: string; isActive?: boolean }) {
+  return (
+    <li>
+      <Link
+        to={href}
+        className={classNames(
+          "text-xs transition hover:opacity-80",
+          {
+            "text-brand-foreground": isActive,
+          },
+        )}
+      >
+        {children}
+      </Link>
+    </li>
+  );
+}
+
+export function Header({ className }: { className?: string }) {
+  const [isScrolled, setIsScrolled] = useState(false);
+  const pathname = usePathname();
+  const isEmbedded = useIsEmbedded();
+
+  const { light, dark } = useMemo(() => {
+    return { light: config.logo.light, dark: config.logo.dark };
+  }, []);
+
+  useEffect(() => {
+    function onScroll() {
+      setIsScrolled(window.scrollY > 0);
+    }
+    onScroll();
+    window.addEventListener('scroll', onScroll, { passive: true });
+    return () => {
+      window.removeEventListener('scroll', onScroll);
+    }
+  }, []);
+
+  return (
+    <header
+      className={classNames(
+        'sticky top-0 z-50 flex flex-none flex-wrap items-center justify-between bg-white px-4 py-5 shadow-md shadow-gray-900/5 sm:px-6 lg:px-8 dark:shadow-none',
+        className,
+        {
+          'dark:bg-gray-900/95 dark:backdrop-blur-sm dark:[@supports(backdrop-filter:blur(0))]:bg-neutral-900/75': isScrolled,
+          'dark:bg-transparent': !isScrolled,
+        },
+      )}
+    >
+      <div className="relative flex justify-between gap-6 sm:gap-8 md:grow items-center w-full px-4">
+        <div className="flex items-center grow gap-2">
+          <img src={`/${light}`} alt="logo" className="w-8 hidden dark:block" />
+          <img src={`/${dark}`} alt="logo" className="w-8 block dark:hidden" />
+          <h1 className="text-base lg:text-2xl font-bold">{config.name}</h1>
+        </div>
+        <nav className="hidden md:block">
+          <ul role="list" className="flex items-center gap-8">
+            {ALL_NAVIGATION.map((tab) => (
+              <TopLevelNavItem 
+                key={tab.title} 
+                href={tab.groups[0].pages[0].href}
+                isActive={pathname.startsWith(`/${tab.groups[0].pages[0].href.split('/')[1]}`)}
+              >
+                {tab.title}
+              </TopLevelNavItem>
+            ))}
+          </ul>
+        </nav>
+        <div className="hidden md:block md:h-5 md:w-px md:bg-zinc-900/10 md:dark:bg-white/15" />
+        <div className="flex items-center gap-3" data-testid="header-actions">
+          <MobileSearch />
+          <Search />
+          {
+            !isEmbedded &&
+            <ModeToggle data-testid="mode-toggle" />
+          }
+          <MobileNavigation />
+        </div>
+      </div>
+    </header>
+  );
+}