create-trellis-docs 1.0.0

package/template/src/components/CustomSearch/NavbarSearch.js

@@ -0,0 +1,211 @@
+// src/components/CustomSearch/NavbarSearch.js
+import React, { useState, useEffect, useCallback, useRef } from 'react';
+import { Input } from 'antd';
+import { SearchOutlined } from '@ant-design/icons';
+import { useHistory } from '@docusaurus/router';
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+
+let Fuse = null;
+if (ExecutionEnvironment.canUseDOM) {
+  import('fuse.js').then(module => {
+    Fuse = module.default;
+  }).catch(err => {
+    console.warn('Error loading Fuse.js:', err);
+  });
+}
+import styles from './styles.module.css';
+
+const fuseOptions = {
+  includeScore: true,
+  threshold: 0.4,
+  minMatchCharLength: 2,
+  keys: [
+    { name: 'keywords', weight: 0.7 },
+    { name: 'title', weight: 0.5 },
+    { name: 'description', weight: 0.3 }
+  ]
+};
+
+function NavbarSearch() {
+  const [isExpanded, setIsExpanded] = useState(false);
+  const [searchTerm, setSearchTerm] = useState('');
+  const [searchResults, setSearchResults] = useState([]);
+  const [searchIndex, setSearchIndex] = useState([]);
+  const [fuse, setFuse] = useState(null);
+  const inputRef = useRef(null);
+  const dropdownRef = useRef(null);
+  const history = useHistory();
+
+  useEffect(() => {
+    const loadSearchIndex = async () => {
+      try {
+        const response = await fetch('/searchIndex.json');
+        if (!response.ok) throw new Error('Failed to load search index');
+        const data = await response.json();
+
+        const processedData = data.map(item => ({
+          ...item,
+          keywords: Array.isArray(item.keywords)
+            ? item.keywords.map(k => k?.toLowerCase()?.trim()).filter(Boolean)
+            : [],
+        }));
+
+        setSearchIndex(processedData);
+        setFuse(new Fuse(processedData, fuseOptions));
+      } catch (error) {
+        console.error('Error loading search index:', error);
+      }
+    };
+
+    loadSearchIndex();
+
+    // Click outside handler
+    const handleClickOutside = (event) => {
+      // Check if the click is on the theme toggle or its children
+      if (event.target.closest('.navbar__items--right')) {
+        return;
+      }
+
+      if (dropdownRef.current && !dropdownRef.current.contains(event.target) &&
+          !event.target.closest('.navbar-search-container')) {
+        setIsExpanded(false);
+        setSearchTerm('');
+        setSearchResults([]);
+      }
+    };
+
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => document.removeEventListener('mousedown', handleClickOutside);
+  }, []);
+
+  const performSearch = useCallback((value) => {
+    if (!value?.trim() || !fuse) {
+      setSearchResults([]);
+      return;
+    }
+
+    try {
+      const results = fuse.search(value.trim());
+      const processedResults = Array.from(
+        new Map(results.map(result => [result.item.id, result.item])).values()
+      );
+      setSearchResults(processedResults);
+    } catch (error) {
+      console.error('Search error:', error);
+      setSearchResults([]);
+    }
+  }, [fuse]);
+
+  const handleSearchChange = useCallback((e) => {
+    const value = e.target.value;
+    setSearchTerm(value);
+    performSearch(value);
+  }, [performSearch]);
+
+  const navigateToPage = (url) => {
+    setIsExpanded(false);
+    setSearchTerm('');
+    setSearchResults([]);
+    const formattedUrl = url.startsWith('/') ? url : `/${url}`;
+    history.replace(formattedUrl);
+  };
+
+  const formatDate = (lastUpdate) => {
+    if (!lastUpdate) return null;
+    try {
+      const dateStr = typeof lastUpdate === 'string'
+        ? lastUpdate
+        : lastUpdate.date || lastUpdate.lastUpdatedAt;
+
+      if (!dateStr) return null;
+
+      const date = new Date(dateStr);
+      return isNaN(date.getTime()) ? null : {
+        date: date.toLocaleDateString('en-US', {
+          year: 'numeric',
+          month: 'long',
+          day: 'numeric'
+        }),
+        author: typeof lastUpdate === 'object' ? lastUpdate.author : null
+      };
+    } catch (error) {
+      return null;
+    }
+  };
+
+  const handleSearchIconClick = (e) => {
+    e.preventDefault();
+    if (isExpanded && !searchTerm) {
+      setIsExpanded(false);
+      // Remove focus from the input field without selecting nearby elements
+      inputRef.current?.blur();
+    } else {
+      setIsExpanded(true);
+      // Add a slight delay to ensure smooth transition before focusing
+      setTimeout(() => {
+        inputRef.current?.focus();
+      }, 100);
+    }
+  };
+
+  return (
+    <div className={styles.searchContainer}>
+      <div className={`${styles.searchWrapper} navbar-search-container ${isExpanded ? styles.expanded : ''}`}>
+        <SearchOutlined
+          className={styles.searchIcon}
+          onClick={handleSearchIconClick}
+        />
+        <Input
+          ref={inputRef}
+          placeholder="Search documentation..."
+          value={searchTerm}
+          onChange={handleSearchChange}
+          className={`${styles.searchInput} ${isExpanded ? styles.visible : ''}`}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter' && searchResults.length > 0) {
+              navigateToPage(searchResults[0].url);
+            } else if (e.key === 'Escape') {
+              setIsExpanded(false);
+              setSearchTerm('');
+              setSearchResults([]);
+            }
+          }}
+        />
+      </div>
+
+      {isExpanded && searchTerm && (
+        <div className={styles.dropdownResults} ref={dropdownRef}>
+          <div className={styles.resultCount}>
+            {searchResults.length === 0 ? 'No results found' :
+             `Found ${searchResults.length} result${searchResults.length === 1 ? '' : 's'}`}
+          </div>
+          {searchResults.map((item) => (
+            <div
+              key={item.id}
+              className={styles.resultItem}
+              onClick={() => navigateToPage(item.url)}
+              onKeyDown={(e) => {
+                if (e.key === 'Enter') {
+                  navigateToPage(item.url);
+                }
+              }}
+              tabIndex={0}
+              role="button"
+            >
+              <div className={styles.resultTitle}>{item.title}</div>
+              <div className={styles.resultDescription}>{item.description}</div>
+              {item.last_update && (
+                <div className={styles.resultMeta}>
+                  {formatDate(item.last_update)?.date &&
+                    `Last updated: ${formatDate(item.last_update).date}`}
+                </div>
+              )}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default NavbarSearch;

package/template/src/components/CustomSearch/SearchContext.js

@@ -0,0 +1,26 @@
+// src/components/CustomSearch/SearchContext.js
+import React, { createContext, useContext, useState } from 'react';
+
+const SearchContext = createContext();
+
+export function SearchProvider({ children }) {
+  const [isModalOpen, setIsModalOpen] = useState(false);
+
+  return (
+    <SearchContext.Provider value={{ isModalOpen, setIsModalOpen }}>
+      {children}
+    </SearchContext.Provider>
+  );
+}
+
+export function useModalSearch() {
+  const context = useContext(SearchContext);
+  if (!context) {
+    throw new Error('useModalSearch must be used within a SearchProvider');
+  }
+  return {
+    isSearchModalOpen: context.isModalOpen,
+    openSearchModal: () => context.setIsModalOpen(true),
+    closeSearchModal: () => context.setIsModalOpen(false)
+  };
+}

package/template/src/components/CustomSearch/styles.module.css

@@ -0,0 +1,171 @@
+/* src/components/CustomSearch/styles.module.css */
+.searchContainer {
+  position: relative;
+  display: flex;
+  align-items: center;
+  z-index: var(--ifm-z-index-fixed);
+}
+
+/* Position the search elements relative to navbar */
+.searchContainer :global(.navbar__items--right) {
+  margin-left: 1rem;
+}
+
+:global(.theme-toggle-button) {
+  padding: 0.5rem;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: background-color 0.2s;
+}
+
+:global(.theme-toggle-button:hover) {
+  background-color: var(--ifm-color-emphasis-200);
+}
+
+/* Ensure other navbar items remain accessible */
+:global(.navbar__items--right) {
+  position: relative;
+  z-index: calc(var(--ifm-z-index-fixed) + 1);
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.searchWrapper {
+  display: flex;
+  align-items: center;
+  position: relative;
+  transition: all 0.3s ease;
+}
+
+.searchIcon {
+  font-size: 20px;
+  color: var(--ifm-navbar-link-color);
+  cursor: pointer;
+  padding: 8px;
+  z-index: 2;
+  user-select: none;
+  -webkit-user-select: none;
+  -moz-user-select: none;
+  -ms-user-select: none;
+}
+
+.searchInput {
+  position: absolute;
+  right: 100%;
+  width: 0;
+  opacity: 0;
+  transition: all 0.3s ease;
+  background: var(--ifm-background-color);
+  border-radius: 4px;
+  border: 1px solid var(--ifm-color-emphasis-300);
+}
+
+.searchWrapper.expanded .searchInput {
+  width: 300px;
+  opacity: 1;
+  padding-right: 32px;
+}
+
+.searchInput.visible {
+  width: 300px;
+  opacity: 1;
+}
+
+.dropdownResults {
+  position: absolute;
+  top: 100%;
+  right: 0;
+  width: 400px;
+  max-height: 70vh;
+  overflow-y: auto;
+  background: var(--ifm-background-color);
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: 4px;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+  z-index: 1000;
+  margin-top: 8px;
+  scrollbar-width: thin;
+  scrollbar-color: var(--ifm-color-emphasis-500) var(--ifm-color-emphasis-200);
+}
+
+.dropdownResults::-webkit-scrollbar {
+  width: 8px;
+}
+
+.dropdownResults::-webkit-scrollbar-track {
+  background: var(--ifm-color-emphasis-200);
+  border-radius: 4px;
+}
+
+.dropdownResults::-webkit-scrollbar-thumb {
+  background-color: var(--ifm-color-emphasis-500);
+  border-radius: 4px;
+}
+
+.resultCount {
+  padding: 8px 16px;
+  background-color: var(--ifm-color-emphasis-100);
+  border-bottom: 1px solid var(--ifm-color-emphasis-300);
+  font-size: 0.875rem;
+  color: var(--ifm-color-emphasis-700);
+  font-weight: 500;
+}
+
+.resultItem {
+  padding: 12px 16px;
+  cursor: pointer;
+  border-bottom: 1px solid var(--ifm-color-emphasis-200);
+  transition: background-color 0.2s ease;
+}
+
+.resultItem:last-child {
+  border-bottom: none;
+}
+
+.resultItem:hover {
+  background-color: var(--ifm-hover-overlay);
+}
+
+.resultTitle {
+  color: var(--ifm-color-primary);
+  font-size: 1rem;
+  font-weight: 600;
+  margin-bottom: 4px;
+}
+
+.resultDescription {
+  font-size: 0.875rem;
+  color: var(--ifm-color-emphasis-700);
+  margin-bottom: 4px;
+  line-height: 1.4;
+}
+
+.resultMeta {
+  font-size: 0.75rem;
+  color: var(--ifm-color-emphasis-600);
+}
+
+@media (max-width: 996px) {
+  .searchWrapper.expanded .searchInput {
+    width: 200px;
+  }
+
+  .dropdownResults {
+    width: 300px;
+    right: -40px;
+  }
+}
+
+/* Dark mode adjustments */
+[data-theme='dark'] .searchInput {
+  background: var(--ifm-background-color);
+  color: var(--ifm-color-white);
+}
+
+[data-theme='dark'] .dropdownResults {
+  background: var(--ifm-background-color);
+  border-color: var(--ifm-color-emphasis-300);
+}

package/template/src/components/CustomSearch/wrapperInit.js

@@ -0,0 +1,11 @@
+// src/components/CustomSearch/wrapperInit.js
+import React from 'react';
+import { SearchProvider } from './SearchContext';
+
+const wrapRootElement = ({ element }) => (
+  <SearchProvider>
+    {element}
+  </SearchProvider>
+);
+
+export default wrapRootElement;

package/template/src/components/FaqTableOfContents/index.jsx

@@ -0,0 +1,176 @@
+import React, { useState, useMemo, useCallback } from 'react';
+import Link from '@docusaurus/Link';
+import useGlobalData from '@docusaurus/useGlobalData';
+import styles from './styles.module.css';
+
+/**
+ * Retrieves FAQ topics from the faq-index-plugin's global data.
+ * Returns an empty array if the plugin data is unavailable.
+ */
+function useFaqTopics(pluginId) {
+  try {
+    const globalData = useGlobalData();
+    const pluginData = globalData?.[pluginId]?.default;
+    return pluginData?.topics || [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Searchable FAQ table of contents for Docusaurus.
+ *
+ * Reads the FAQ index produced by faq-index-plugin and renders a
+ * filterable list of every question, grouped by topic file.
+ *
+ * @param {Object} props
+ * @param {string} [props.pluginId='docusaurus-plugin-faq-index'] - Plugin name to look up in global data.
+ * @param {string} [props.searchPlaceholder='Search FAQs...'] - Placeholder for the search input.
+ * @param {string} [props.title] - Optional heading above the TOC.
+ */
+export default function FaqTableOfContents({
+  pluginId = 'docusaurus-plugin-faq-index',
+  searchPlaceholder = 'Search FAQs...',
+  title,
+}) {
+  const [searchQuery, setSearchQuery] = useState('');
+  const topics = useFaqTopics(pluginId);
+
+  // Total question count
+  const totalQuestions = useMemo(
+    () => topics.reduce((sum, t) => sum + t.questions.length, 0),
+    [topics],
+  );
+
+  // Filter topics and questions by search query
+  const filtered = useMemo(() => {
+    if (!searchQuery.trim()) return topics;
+
+    const query = searchQuery.toLowerCase();
+    return topics
+      .map((topic) => {
+        const topicMatches = topic.title.toLowerCase().includes(query);
+        const matchingQuestions = topic.questions.filter((q) =>
+          q.text.toLowerCase().includes(query),
+        );
+
+        if (topicMatches) return topic;
+        if (matchingQuestions.length > 0) {
+          return { ...topic, questions: matchingQuestions };
+        }
+        return null;
+      })
+      .filter(Boolean);
+  }, [topics, searchQuery]);
+
+  const filteredQuestionCount = useMemo(
+    () => filtered.reduce((sum, t) => sum + t.questions.length, 0),
+    [filtered],
+  );
+
+  const handleSearchChange = useCallback((e) => {
+    setSearchQuery(e.target.value);
+  }, []);
+
+  const handleClear = useCallback(() => {
+    setSearchQuery('');
+  }, []);
+
+  if (topics.length === 0) {
+    return (
+      <div className={styles.faqToc}>
+        <p className={styles.emptyState}>
+          No FAQ topics found. Verify that the{' '}
+          <code>faq-index-plugin</code> is registered in{' '}
+          <code>docusaurus.config.js</code> and that <code>docs/faq/</code>{' '}
+          contains <code>.mdx</code> files with <code>###</code> question
+          headings.
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className={styles.faqToc}>
+      {title && <h2 className={styles.title}>{title}</h2>}
+
+      {/* Search input */}
+      <div className={styles.searchContainer}>
+        <svg
+          className={styles.searchIcon}
+          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" />
+          <line x1="21" y1="21" x2="16.65" y2="16.65" />
+        </svg>
+        <input
+          type="text"
+          className={styles.searchInput}
+          placeholder={searchPlaceholder}
+          value={searchQuery}
+          onChange={handleSearchChange}
+          aria-label="Search FAQ entries"
+        />
+        {searchQuery && (
+          <button
+            className={styles.clearButton}
+            onClick={handleClear}
+            aria-label="Clear search"
+            type="button"
+          >
+            ✕
+          </button>
+        )}
+      </div>
+
+      {/* Result count */}
+      {searchQuery && (
+        <p className={styles.resultCount}>
+          {filteredQuestionCount} of {totalQuestions}{' '}
+          {totalQuestions === 1 ? 'question' : 'questions'} match
+        </p>
+      )}
+
+      {/* FAQ list */}
+      {filtered.length === 0 ? (
+        <p className={styles.noResults}>
+          No FAQs match "<strong>{searchQuery}</strong>". Try a different search
+          term.
+        </p>
+      ) : (
+        filtered.map((topic) => (
+          <div key={topic.slug} className={styles.topicGroup}>
+            <h2 className={styles.topicHeading}>
+                {topic.title}
+              <span className={styles.questionCount}>
+                {topic.questions.length}
+              </span>
+            </h2>
+            {topic.description && (
+              <p className={styles.topicDescription}>{topic.description}</p>
+            )}
+            <ul className={styles.questionList}>
+              {topic.questions.map((q) => (
+                <li key={q.anchor} className={styles.questionItem}>
+                  <Link
+                    to={`${topic.permalink}#${q.anchor}`}
+                    className={styles.questionLink}
+                  >
+                    {q.text}
+                  </Link>
+                </li>
+              ))}
+            </ul>
+          </div>
+        ))
+      )}
+    </div>
+  );
+}