@aravindc26/velu 0.12.7 → 0.12.9

package/src/engine-core/components/search.tsx

@@ -0,0 +1,318 @@
+'use client';
+
+import { useEffect, useRef, useState, useCallback, type KeyboardEvent } from 'react';
+
+interface PagefindResult {
+  url: string;
+  excerpt: string;
+  meta: { title?: string };
+  sub_results?: Array<{
+    url: string;
+    title: string;
+    excerpt: string;
+  }>;
+}
+
+interface PagefindResponse {
+  results: Array<{ data: () => Promise<PagefindResult> }>;
+}
+
+interface PagefindInstance {
+  init: () => Promise<void>;
+  search: (query: string, options?: { filters?: Record<string, string | string[]> }) => Promise<PagefindResponse>;
+  destroy: () => void;
+}
+
+interface SearchFilters {
+  language?: string;
+  version?: string;
+  product?: string;
+}
+
+function parseFilterAttribute(value: string | null): SearchFilters {
+  const out: SearchFilters = {};
+  if (!value) return out;
+
+  for (const entry of value.split(',')) {
+    const part = entry.trim();
+    if (!part) continue;
+    const index = part.indexOf(':');
+    if (index <= 0) continue;
+    const key = part.slice(0, index).trim();
+    const val = part.slice(index + 1).trim();
+    if (!val) continue;
+    if (key === 'language') out.language = val;
+    if (key === 'version') out.version = val;
+    if (key === 'product') out.product = val;
+  }
+  return out;
+}
+
+function getActiveFiltersFromPage(): SearchFilters {
+  if (typeof document === 'undefined') return {};
+  const node = document.querySelector('[data-pagefind-body]');
+  if (!node) return {};
+  return parseFilterAttribute(node.getAttribute('data-pagefind-filter'));
+}
+
+function detectSiteBasePath(): string {
+  if (typeof document === 'undefined' || typeof window === 'undefined') return '';
+  const scripts = Array.from(document.querySelectorAll('script[src]')) as HTMLScriptElement[];
+  for (const script of scripts) {
+    const src = script.getAttribute('src');
+    if (!src || !src.includes('/_next/static/')) continue;
+    try {
+      const parsed = new URL(src, window.location.origin);
+      const marker = '/_next/static/';
+      const idx = parsed.pathname.indexOf(marker);
+      if (idx >= 0) return parsed.pathname.slice(0, idx);
+    } catch {
+      // ignore invalid script URL and continue
+    }
+  }
+  return '';
+}
+
+async function loadPagefindRuntime(): Promise<PagefindInstance | null> {
+  const basePath = detectSiteBasePath().replace(/\/+$/, '');
+  const candidates = Array.from(
+    new Set([
+      basePath ? `${basePath}/pagefind/pagefind.js` : '',
+      '/pagefind/pagefind.js',
+    ].filter(Boolean)),
+  );
+
+  for (const path of candidates) {
+    try {
+      const moduleLoader = new Function('modulePath', 'return import(modulePath)');
+      const mod = await moduleLoader(path) as unknown as PagefindInstance;
+      await mod.init();
+      return mod;
+    } catch {
+      // try next candidate
+    }
+  }
+
+  return null;
+}
+
+export function PagefindSearch({
+  open,
+  onOpenChange,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}) {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  const pagefindRef = useRef<PagefindInstance | null>(null);
+  const resultRefs = useRef<Array<HTMLAnchorElement | null>>([]);
+  const [query, setQuery] = useState('');
+  const [results, setResults] = useState<PagefindResult[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [available, setAvailable] = useState(true);
+  const [activeFilters, setActiveFilters] = useState<SearchFilters>({});
+  const [activeIndex, setActiveIndex] = useState<number>(-1);
+
+  // Extract page-level filters from rendered metadata when search opens.
+  useEffect(() => {
+    if (open) {
+      setActiveFilters(getActiveFiltersFromPage());
+    }
+  }, [open]);
+
+  useEffect(() => {
+    async function loadPagefind() {
+      if (process.env.NODE_ENV !== 'production') {
+        setAvailable(false);
+        return;
+      }
+      try {
+        pagefindRef.current = await loadPagefindRuntime();
+        if (!pagefindRef.current) setAvailable(false);
+      } catch {
+        setAvailable(false);
+      }
+    }
+    loadPagefind();
+  }, []);
+
+  useEffect(() => {
+    if (open) {
+      dialogRef.current?.showModal();
+      setTimeout(() => inputRef.current?.focus(), 50);
+    } else {
+      dialogRef.current?.close();
+      setQuery('');
+      setResults([]);
+      setActiveIndex(-1);
+    }
+  }, [open]);
+
+  useEffect(() => {
+    if (!results.length) {
+      setActiveIndex(-1);
+      return;
+    }
+    if (activeIndex >= results.length) {
+      setActiveIndex(results.length - 1);
+    }
+  }, [results, activeIndex]);
+
+  useEffect(() => {
+    if (activeIndex < 0) return;
+    const node = resultRefs.current[activeIndex];
+    node?.scrollIntoView({ block: 'nearest' });
+  }, [activeIndex]);
+
+  const search = useCallback(
+    async (q: string) => {
+      setQuery(q);
+      if (!q.trim() || !pagefindRef.current) {
+        setResults([]);
+        setActiveIndex(-1);
+        return;
+      }
+      setLoading(true);
+      try {
+        // Build filters for pagefind
+        const filters: Record<string, string> = {};
+        if (activeFilters.language) filters.language = activeFilters.language;
+        if (activeFilters.version) filters.version = activeFilters.version;
+        if (activeFilters.product) filters.product = activeFilters.product;
+
+        const withFilters = Object.keys(filters).length > 0;
+        const response = await pagefindRef.current.search(
+          q,
+          withFilters ? { filters } : undefined,
+        );
+
+        // If scoped filters return nothing, fall back to global results
+        // to avoid false "No results" from stale/missing filter metadata.
+        const fallbackResponse = withFilters && response.results.length === 0
+          ? await pagefindRef.current.search(q)
+          : response;
+
+        const items = await Promise.all(
+          fallbackResponse.results.slice(0, 8).map((r) => r.data()),
+        );
+        setResults(items);
+        setActiveIndex(items.length > 0 ? 0 : -1);
+      } catch {
+        setResults([]);
+        setActiveIndex(-1);
+      }
+      setLoading(false);
+    },
+    [activeFilters]
+  );
+
+  const onInputKeyDown = useCallback((event: KeyboardEvent<HTMLInputElement>) => {
+    if (!results.length) return;
+
+    if (event.key === 'ArrowDown') {
+      event.preventDefault();
+      setActiveIndex((prev) => (prev < 0 ? 0 : (prev + 1) % results.length));
+      return;
+    }
+
+    if (event.key === 'ArrowUp') {
+      event.preventDefault();
+      setActiveIndex((prev) => {
+        if (prev < 0) return results.length - 1;
+        return prev === 0 ? results.length - 1 : prev - 1;
+      });
+      return;
+    }
+
+    if (event.key === 'Enter' && activeIndex >= 0 && activeIndex < results.length) {
+      event.preventDefault();
+      const target = results[activeIndex];
+      onOpenChange(false);
+      window.location.href = target.url;
+    }
+  }, [activeIndex, onOpenChange, results]);
+
+  return (
+    <dialog
+      ref={dialogRef}
+      className="fd-search-dialog"
+      onClick={(e) => {
+        if (e.target === dialogRef.current) onOpenChange(false);
+      }}
+      onClose={() => onOpenChange(false)}
+    >
+      <div className="fd-search-content">
+        <div className="fd-search-input-wrap">
+          <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
+          <input
+            ref={inputRef}
+            type="text"
+            placeholder="Search documentation..."
+            value={query}
+            onChange={(e) => search(e.target.value)}
+            onKeyDown={onInputKeyDown}
+            className="fd-search-input"
+          />
+          <kbd className="fd-search-kbd" onClick={() => onOpenChange(false)}>
+            Esc
+          </kbd>
+        </div>
+
+        <div className="fd-search-results">
+          {!available && (
+            <p className="fd-search-empty">
+              Search is available after building the site.
+            </p>
+          )}
+          {available && loading && (
+            <p className="fd-search-empty">Searching…</p>
+          )}
+          {available && !loading && query && results.length === 0 && (
+            <p className="fd-search-empty">No results found.</p>
+          )}
+          {results.map((r, i) => (
+            <a
+              key={i}
+              href={r.url}
+              ref={(node) => {
+                resultRefs.current[i] = node;
+              }}
+              className={['fd-search-result', activeIndex === i ? 'is-active' : ''].join(' ')}
+              aria-current={activeIndex === i ? 'true' : undefined}
+              onMouseEnter={() => setActiveIndex(i)}
+              onClick={() => onOpenChange(false)}
+            >
+              <span className="fd-search-result-title">
+                {r.meta?.title || r.url}
+              </span>
+              <span
+                className="fd-search-result-excerpt"
+                dangerouslySetInnerHTML={{ __html: r.excerpt }}
+              />
+            </a>
+          ))}
+        </div>
+      </div>
+    </dialog>
+  );
+}
+
+export function SearchToggle({
+  onClick,
+}: {
+  onClick: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      className="fd-search-trigger"
+      onClick={onClick}
+      aria-label="Search"
+    >
+      <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
+      <span>Search…</span>
+      <kbd>⌘K</kbd>
+    </button>
+  );
+}

package/src/engine-core/components/sidebar-links.tsx

@@ -0,0 +1,54 @@
+import type { VeluAnchor, VeluIconLibrary } from '@core/types';
+import { ThemeToggle } from './theme-toggle';
+import { LanguageSwitcher } from './lang-switcher';
+import { VeluIcon } from './icon';
+
+function ExternalLinkIcon() {
+  return (
+    <VeluIcon name="external-link" className="velu-sidebar-link-icon" fallback={false} />
+  );
+}
+
+export function SidebarLinks({
+  anchors,
+  languages,
+  iconLibrary,
+}: {
+  anchors: VeluAnchor[];
+  languages: string[];
+  iconLibrary: VeluIconLibrary;
+}) {
+
+  return (
+    <div className="velu-sidebar-footer">
+      {anchors.length > 0 && (
+        <div className="velu-sidebar-links">
+          {anchors.map((anchor) => (
+            <a
+              key={anchor.href}
+              href={anchor.href}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="velu-sidebar-link"
+            >
+              <span className="velu-sidebar-link-left">
+                <VeluIcon
+                  name={anchor.icon}
+                  iconType={anchor.iconType}
+                  library={iconLibrary}
+                  className="velu-sidebar-link-leading-icon"
+                />
+                <span className="velu-sidebar-link-text">{anchor.anchor}</span>
+              </span>
+              <ExternalLinkIcon />
+            </a>
+          ))}
+        </div>
+      )}
+      <div className="velu-sidebar-footer-row">
+        {languages.length > 1 && <LanguageSwitcher languages={languages} defaultLang={languages[0]} />}
+        <ThemeToggle />
+      </div>
+    </div>
+  );
+}

package/src/engine-core/components/synced-tabs.tsx

@@ -0,0 +1,57 @@
+"use client";
+
+import { Children, isValidElement, type ReactElement, type ReactNode, useMemo } from "react";
+import { Tabs as FumaTabs } from "fumadocs-ui/components/tabs";
+
+const SYNCED_GROUP_ID = "velu-synced-tabs";
+
+function findTitle(node: ReactNode): string | undefined {
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      const found = findTitle(item);
+      if (found) return found;
+    }
+    return undefined;
+  }
+  if (!isValidElement(node)) return undefined;
+  const props = (node as ReactElement<Record<string, unknown>>).props;
+  const direct = props?.title ?? props?.["data-title"];
+  if (typeof direct === "string" && direct.trim()) return direct.trim();
+  return findTitle(props?.children as ReactNode);
+}
+
+interface VeluSyncedTabsProps {
+  items?: string[];
+  children?: ReactNode;
+  sync?: boolean;
+  borderBottom?: boolean;
+  className?: string;
+  groupId?: string;
+  [key: string]: unknown;
+}
+
+export function VeluSyncedTabs({ items, children, sync = true, borderBottom, className, groupId, ...props }: VeluSyncedTabsProps) {
+  const tabItems = useMemo(() => {
+    if (Array.isArray(items) && items.length > 0) return items;
+    const tabChildren = Children.toArray(children).filter((child) => isValidElement(child)) as ReactElement<any>[];
+    return tabChildren.map((child, idx) => findTitle(child) ?? `Tab ${idx + 1}`);
+  }, [children, items]);
+
+  return (
+    <FumaTabs
+      {...(props as any)}
+      items={tabItems}
+      groupId={sync ? (groupId ?? SYNCED_GROUP_ID) : undefined}
+      persist={sync}
+      className={[
+        "velu-tabs-plain !border-0 !bg-transparent !rounded-none !my-2",
+        className,
+        borderBottom ? "velu-tabs-border-bottom" : "",
+      ]
+        .filter(Boolean)
+        .join(" ")}
+    >
+      {children}
+    </FumaTabs>
+  );
+}

package/src/engine-core/components/theme-toggle.tsx

@@ -0,0 +1,39 @@
+'use client';
+
+import { useTheme } from 'next-themes';
+import { useEffect, useState } from 'react';
+
+export function ThemeToggle() {
+  const { setTheme, resolvedTheme } = useTheme();
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => setMounted(true), []);
+
+  const isDark = mounted ? resolvedTheme === 'dark' : false;
+
+  return (
+    <div className="velu-theme-toggle" style={mounted ? undefined : { opacity: 0 }}>
+      <button
+        type="button"
+        className={`velu-theme-btn ${!isDark ? 'active' : ''}`}
+        onClick={() => setTheme('light')}
+        aria-label="Light mode"
+      >
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" width="16" height="16">
+          <circle cx="12" cy="12" r="4" />
+          <path d="M12 2v2" /><path d="M12 20v2" /><path d="m4.93 4.93 1.41 1.41" /><path d="m17.66 17.66 1.41 1.41" /><path d="M2 12h2" /><path d="M20 12h2" /><path d="m6.34 17.66-1.41 1.41" /><path d="m19.07 4.93-1.41 1.41" />
+        </svg>
+      </button>
+      <button
+        type="button"
+        className={`velu-theme-btn ${isDark ? 'active' : ''}`}
+        onClick={() => setTheme('dark')}
+        aria-label="Dark mode"
+      >
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" width="16" height="16">
+          <path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z" />
+        </svg>
+      </button>
+    </div>
+  );
+}

package/src/engine-core/components/toc-examples.tsx

@@ -0,0 +1,110 @@
+"use client";
+
+import { usePathname } from 'next/navigation';
+import { useEffect } from 'react';
+
+export function TocExamples() {
+  const pathname = usePathname();
+
+  useEffect(() => {
+    const page = document.getElementById('nd-page');
+    const toc = document.getElementById('nd-toc');
+    const layout = document.getElementById('nd-docs-layout');
+    if (!page || !toc) return;
+
+    let wrapper: HTMLDivElement | null = null;
+    let placeholders: Array<{ node: HTMLElement; marker: Comment }> = [];
+    const media = window.matchMedia('(min-width: 1024px)');
+
+    const isTocVisible = () => {
+      if (!media.matches) return false;
+      const styles = window.getComputedStyle(toc);
+      return styles.display !== 'none' && styles.visibility !== 'hidden';
+    };
+
+    const mountIntoToc = () => {
+      if (wrapper) return;
+      const examples = Array.from(
+        page.querySelectorAll<HTMLElement>('.velu-request-example, .velu-response-example, .velu-panel'),
+      );
+      if (examples.length === 0) return;
+
+      wrapper = document.createElement('div');
+      wrapper.className = 'velu-toc-examples';
+      placeholders = [];
+
+      for (const node of examples) {
+        const marker = document.createComment('velu-example-placeholder');
+        node.parentNode?.insertBefore(marker, node);
+        placeholders.push({ node, marker });
+        node.classList.add('velu-in-toc-example');
+        wrapper.appendChild(node);
+      }
+
+      toc.classList.add('velu-toc-replaced');
+      page.classList.add('velu-page-with-toc-examples');
+      if (layout) layout.style.setProperty('--fd-toc-width', '420px');
+      toc.appendChild(wrapper);
+    };
+
+    const restoreToPage = () => {
+      if (wrapper) {
+        for (const { node, marker } of placeholders) {
+          if (marker.parentNode) {
+            marker.parentNode.insertBefore(node, marker);
+            marker.parentNode.removeChild(marker);
+          }
+          node.classList.remove('velu-in-toc-example');
+        }
+        wrapper.remove();
+        wrapper = null;
+        placeholders = [];
+      }
+
+      // Defensive cleanup in case of interrupted transitions.
+      toc.querySelectorAll('.velu-toc-examples').forEach((node) => node.remove());
+      document.querySelectorAll('.velu-in-toc-example').forEach((node) => {
+        node.classList.remove('velu-in-toc-example');
+      });
+
+      toc.classList.remove('velu-toc-replaced');
+      page.classList.remove('velu-page-with-toc-examples');
+      if (layout) layout.style.removeProperty('--fd-toc-width');
+    };
+
+    const syncPlacement = () => {
+      if (isTocVisible()) {
+        mountIntoToc();
+      } else {
+        restoreToPage();
+      }
+    };
+
+    syncPlacement();
+    if (media.addEventListener) {
+      media.addEventListener('change', syncPlacement);
+    } else {
+      // Fallback for older MediaQueryList implementations.
+      (media as any).addListener(syncPlacement);
+    }
+    window.addEventListener('resize', syncPlacement);
+    window.addEventListener('orientationchange', syncPlacement);
+    document.addEventListener('visibilitychange', syncPlacement);
+    const intervalId = window.setInterval(syncPlacement, 600);
+
+    return () => {
+      if (media.removeEventListener) {
+        media.removeEventListener('change', syncPlacement);
+      } else {
+        (media as any).removeListener(syncPlacement);
+      }
+      window.removeEventListener('resize', syncPlacement);
+      window.removeEventListener('orientationchange', syncPlacement);
+      document.removeEventListener('visibilitychange', syncPlacement);
+      window.clearInterval(intervalId);
+      restoreToPage();
+    };
+  }, [pathname]);
+
+  return null;
+}

package/src/engine-core/components/version-switcher.tsx

@@ -0,0 +1,95 @@
+'use client';
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { usePathname } from 'next/navigation';
+import type { VeluVersionOption } from '@core/types';
+
+function VersionIcon() {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round">
+      <path d="M4 6h16" />
+      <path d="M4 12h16" />
+      <path d="M4 18h16" />
+    </svg>
+  );
+}
+
+function ChevronDownIcon() {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round">
+      <path d="m6 9 6 6 6-6" />
+    </svg>
+  );
+}
+
+function withTrailingSlashPath(path: string): string {
+  if (!path.startsWith('/')) return path;
+  if (path === '/' || path.endsWith('/')) return path;
+  return `${path}/`;
+}
+
+export function VersionSwitcher({ versions }: { versions: VeluVersionOption[] }) {
+  const pathname = usePathname();
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+
+  const fallback = useMemo(() => versions.find((v) => v.isDefault) ?? versions[0], [versions]);
+
+  const current = useMemo(() => {
+    const firstSeg = pathname.split('/').filter(Boolean)[0] ?? '';
+    return versions.find((version) => version.tabSlugs.includes(firstSeg)) ?? fallback;
+  }, [pathname, versions, fallback]);
+
+  useEffect(() => {
+    function handleClick(e: MouseEvent) {
+      if (ref.current && !ref.current.contains(e.target as Node)) setOpen(false);
+    }
+    document.addEventListener('mousedown', handleClick);
+    return () => document.removeEventListener('mousedown', handleClick);
+  }, []);
+
+  if (!fallback || versions.length <= 1) return null;
+
+  function switchTo(target: VeluVersionOption) {
+    setOpen(false);
+
+    const segments = pathname.split('/').filter(Boolean);
+    const firstSeg = segments[0] ?? '';
+
+    if (current && current.tabSlugs.includes(firstSeg)) {
+      const index = current.tabSlugs.indexOf(firstSeg);
+      const targetTab = target.tabSlugs[index] ?? target.tabSlugs[0];
+      if (targetTab) {
+        const rest = segments.slice(1);
+        window.location.href = withTrailingSlashPath('/' + [targetTab, ...rest].join('/'));
+        return;
+      }
+    }
+
+    window.location.href = withTrailingSlashPath(target.defaultPath);
+  }
+
+  return (
+    <div className="velu-version-switcher-wrap" ref={ref}>
+      <button type="button" className="velu-version-switcher" onClick={() => setOpen((v) => !v)}>
+        <VersionIcon />
+        <span>{current.version}</span>
+        <ChevronDownIcon />
+      </button>
+      {open && (
+        <div className="velu-version-menu">
+          {versions.map((version) => (
+            <button
+              key={version.slug}
+              type="button"
+              className={`velu-version-option ${version.slug === current.slug ? 'active' : ''}`}
+              onClick={() => switchTo(version)}
+            >
+              {version.version}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}