astro-tractstack 2.0.0-rc.36 → 2.0.0-rc.38

package/dist/index.js

@@ -893,6 +893,23 @@ async function w(t, e, c) {
       src: t("../templates/src/components/Fragment.astro"),
       dest: "src/components/Fragment.astro"
     },
+    // Search Components
+    {
+      src: t("../templates/src/components/search/SearchWrapper.tsx"),
+      dest: "src/components/search/SearchWrapper.tsx"
+    },
+    {
+      src: t("../templates/src/components/search/SearchModal.tsx"),
+      dest: "src/components/search/SearchModal.tsx"
+    },
+    {
+      src: t("../templates/src/components/search/SearchResults.tsx"),
+      dest: "src/components/search/SearchResults.tsx"
+    },
+    {
+      src: t("../templates/src/hooks/useSearch.ts"),
+      dest: "src/hooks/useSearch.ts"
+    },
     // Profile Components
     {
       src: t("../templates/src/components/profile/ProfileConsent.tsx"),
@@ -2015,6 +2032,11 @@ async function w(t, e, c) {
       dest: "src/custom/CustomRoutes.astro",
       protected: !0
     },
+    {
+      src: t("../templates/src/utils/customHelpers.ts"),
+      dest: "src/utils/customHelpers.ts",
+      protected: !0
+    },
     // Example Components (Conditional)
     ...c?.includeExamples ? [
       {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-tractstack",
-  "version": "2.0.0-rc.36",
+  "version": "2.0.0-rc.38",
   "description": "Astro integration for TractStack - redeeming the web from boring experiences",
   "type": "module",
   "main": "dist/index.js",

package/templates/src/components/Header.astro

@@ -1,5 +1,7 @@
 ---
 import Menu from './Menu';
+import SearchWrapper from '@/components/search/SearchWrapper';
+import { getFullContentMap } from '@/stores/analytics';
 import { isAuthenticated, isAdmin, getUserRole } from '@/utils/auth';
 import ImpressionWrapper from '@/components/widgets/ImpressionWrapper';
 import type { MenuNode } from '@/types/tractstack';
@@ -33,6 +35,10 @@ const {
 
 const isHome = slug === brandConfig?.HOME_SLUG;
 
+const tenantId =
+  Astro.locals.tenant?.id || import.meta.env.PUBLIC_TENANTID || 'default';
+const fullContentMap = await getFullContentMap(tenantId);
+
 const getAssetPath = (configPath: string, fallback: string) => {
   // Always prioritize brandConfig values when they exist
   if (configPath && configPath !== '') {
@@ -40,11 +46,8 @@ const getAssetPath = (configPath: string, fallback: string) => {
   }
   return fallback;
 };
-
 const logo = getAssetPath(brandConfig?.LOGO, '/brand/logo.svg');
 const wordmark = getAssetPath(brandConfig?.WORDMARK, '/brand/wordmark.svg');
-
-// Handle empty WORDMARK_MODE by defaulting to "default"
 const wordmarkMode =
   brandConfig?.WORDMARK_MODE && brandConfig.WORDMARK_MODE !== ''
     ? brandConfig.WORDMARK_MODE
@@ -108,7 +111,6 @@ const authStatus = {
   >
     <h1 class="text-mydarkgrey truncate text-xl">{title}</h1>
     <div class="flex flex-row flex-nowrap items-center gap-x-2">
-      {/* Home Icon */}
       {
         !isHome ? (
           <a
@@ -133,7 +135,6 @@ const authStatus = {
         ) : null
       }
 
-      {/* StoryKeep Dashboard Icon */}
       {
         authStatus.isAdmin || authStatus.isAuthenticated ? (
           <a
@@ -158,7 +159,6 @@ const authStatus = {
         ) : null
       }
 
-      {/* Edit Icon */}
       {
         isEditable &&
         (authStatus.isAdmin || authStatus.userRole === 'editor') ? (
@@ -185,7 +185,8 @@ const authStatus = {
         ) : null
       }
 
-      {/* Remember Me Icon */}
+      <SearchWrapper contentMap={fullContentMap} client:load />
+
       <script is:inline define:vars={{ sessionId }}>
         function initRememberMe() {
           const consent = localStorage.getItem('tractstack_consent') === '1';
@@ -247,7 +248,6 @@ const authStatus = {
         ) : null
       }
 
-      {/* Logout Icon - Admin/Editor Only */}
       {
         authStatus.isAdmin || authStatus.userRole === 'editor' ? (
           <a

package/templates/src/components/search/SearchModal.tsx

@@ -0,0 +1,164 @@
+import { useState, useEffect, useRef } from 'react';
+import { Dialog } from '@ark-ui/react/dialog';
+import { Portal } from '@ark-ui/react/portal';
+import { MagnifyingGlassIcon, XMarkIcon } from '@heroicons/react/24/outline';
+import { useSearch } from '@/hooks/useSearch';
+import SearchResults from './SearchResults';
+import type { FullContentMapItem } from '@/types/tractstack';
+
+interface SearchModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  contentMap: FullContentMapItem[];
+}
+
+export default function SearchModal({
+  isOpen,
+  onClose,
+  contentMap,
+}: SearchModalProps) {
+  const [query, setQuery] = useState('');
+  const inputRef = useRef<HTMLInputElement>(null);
+  const {
+    searchResults,
+    isLoading,
+    error,
+    totalResults,
+    executeSearch,
+    clearResults,
+  } = useSearch();
+
+  useEffect(() => {
+    if (isOpen && inputRef.current) {
+      inputRef.current.focus();
+    }
+  }, [isOpen]);
+
+  useEffect(() => {
+    if (!isOpen) {
+      setQuery('');
+      clearResults();
+    }
+  }, [isOpen, clearResults]);
+
+  useEffect(() => {
+    if (query.trim().length >= 3) {
+      executeSearch(query.trim());
+    } else {
+      clearResults();
+    }
+  }, [query, executeSearch, clearResults]);
+
+  const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    setQuery(e.target.value);
+  };
+
+  const handleClose = () => {
+    setQuery('');
+    clearResults();
+    onClose();
+  };
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === 'Escape') {
+      handleClose();
+    }
+  };
+
+  return (
+    <Dialog.Root
+      open={isOpen}
+      onOpenChange={(details) => !details.open && handleClose()}
+    >
+      <Portal>
+        <Dialog.Backdrop className="fixed inset-0 z-50 bg-black bg-opacity-50 backdrop-blur-sm" />
+        <Dialog.Positioner className="fixed inset-0 z-50 flex items-start justify-center p-4 pt-16">
+          <Dialog.Content
+            className="bg-mywhite w-full max-w-5xl overflow-hidden rounded-lg shadow-2xl"
+            style={{ height: '80vh', display: 'flex', flexDirection: 'column' }}
+          >
+            {/* Fixed Header */}
+            <div
+              className="flex items-center gap-4 border-b border-gray-200 p-6"
+              style={{ flexShrink: 0 }}
+            >
+              <MagnifyingGlassIcon className="text-mydarkgrey h-6 w-6" />
+              <input
+                ref={inputRef}
+                type="text"
+                value={query}
+                onChange={handleInputChange}
+                onKeyDown={handleKeyDown}
+                placeholder="Search content..."
+                className="text-mydarkgrey flex-1 border-none bg-transparent px-4 text-xl placeholder-gray-500 outline-none"
+              />
+              <button
+                onClick={handleClose}
+                className="text-mydarkgrey hover:text-myblue rounded-lg p-2 transition-colors hover:bg-gray-100"
+                aria-label="Close search"
+              >
+                <XMarkIcon className="h-6 w-6" />
+              </button>
+            </div>
+
+            {/* Scrollable Content Area */}
+            <div className="overflow-y-auto" style={{ flex: 1 }}>
+              {query.length < 3 && (
+                <div className="p-8 text-center text-gray-500">
+                  <MagnifyingGlassIcon className="mx-auto mb-4 h-16 w-16 text-gray-300" />
+                  <p className="text-lg">Search across all content</p>
+                  <p className="mt-2 text-sm">
+                    Type at least 3 characters to search pages, context, and
+                    resources
+                  </p>
+                </div>
+              )}
+
+              {query.length >= 3 && isLoading && (
+                <div className="p-8 text-center">
+                  <div className="border-myblue inline-block h-8 w-8 animate-spin rounded-full border-b-2"></div>
+                  <p className="text-mydarkgrey mt-4">Searching...</p>
+                </div>
+              )}
+
+              {query.length >= 3 && error && (
+                <div className="p-8 text-center text-red-600">
+                  <p>Search failed: {error}</p>
+                  <button
+                    onClick={() => executeSearch(query.trim())}
+                    className="text-myblue mt-2 hover:underline"
+                  >
+                    Try again
+                  </button>
+                </div>
+              )}
+
+              {query.length >= 3 &&
+                !isLoading &&
+                !error &&
+                totalResults === 0 && (
+                  <div className="p-8 text-center text-gray-500">
+                    <p className="text-lg">No results found for "{query}"</p>
+                    <p className="mt-2 text-sm">
+                      Try different keywords or check your spelling
+                    </p>
+                  </div>
+                )}
+
+              {query.length >= 3 &&
+                !isLoading &&
+                !error &&
+                totalResults > 0 && (
+                  <SearchResults
+                    results={searchResults}
+                    contentMap={contentMap}
+                    onResultClick={handleClose}
+                  />
+                )}
+            </div>
+          </Dialog.Content>
+        </Dialog.Positioner>
+      </Portal>
+    </Dialog.Root>
+  );
+}

package/templates/src/components/search/SearchResults.tsx

@@ -0,0 +1,282 @@
+import { useState, useMemo } from 'react';
+import { Pagination } from '@ark-ui/react/pagination';
+import { ChevronLeftIcon, ChevronRightIcon } from '@heroicons/react/24/outline';
+import type { SearchResults as SearchResultsType } from '@/hooks/useSearch';
+import type { FullContentMapItem } from '@/types/tractstack';
+import { getResourceUrl, getResourceImage } from '@/utils/customHelpers';
+
+interface SearchResultsProps {
+  results: SearchResultsType;
+  contentMap: FullContentMapItem[];
+  onResultClick: () => void;
+}
+
+interface ResultItem {
+  id: string;
+  type: 'StoryFragment' | 'ContextPane' | 'Resource';
+  title: string;
+  slug: string;
+  description?: string;
+  topics?: string[];
+  changed?: string;
+  thumbSrc?: string;
+  categorySlug?: string;
+  url: string;
+  imageSrc: string;
+}
+
+const ITEMS_PER_PAGE = 10;
+
+export default function SearchResults({
+  results,
+  contentMap,
+  onResultClick,
+}: SearchResultsProps) {
+  const [currentPage, setCurrentPage] = useState(1);
+
+  const allResultItems = useMemo(() => {
+    const items: ResultItem[] = [];
+
+    results.storyFragmentIds.forEach((id) => {
+      const item = contentMap.find(
+        (item) => item.id === id && item.type === 'StoryFragment'
+      );
+      if (item) {
+        items.push({
+          id: item.id,
+          type: 'StoryFragment',
+          title: item.title,
+          slug: item.slug,
+          description: item.description || undefined,
+          topics: item.topics || undefined,
+          changed: item.changed || undefined,
+          thumbSrc: item.thumbSrc || undefined,
+          url: `/${item.slug}`,
+          imageSrc: item.thumbSrc || '/static.jpg',
+        });
+      }
+    });
+
+    results.contextPaneIds.forEach((id) => {
+      const item = contentMap.find(
+        (item) => item.id === id && item.type === 'Pane'
+      );
+      if (item) {
+        items.push({
+          id: item.id,
+          type: 'ContextPane',
+          title: item.title,
+          slug: item.slug,
+          url: `/context/${item.slug}`,
+          imageSrc: '/static.jpg',
+        });
+      }
+    });
+
+    results.resourceIds.forEach((id) => {
+      const item = contentMap.find(
+        (item) => item.id === id && item.type === 'Resource'
+      );
+      if (item) {
+        const resourceUrl = getResourceUrl(item.categorySlug || '', item.slug);
+        const resourceImage = getResourceImage(
+          item.id,
+          item.slug,
+          item.categorySlug || ''
+        );
+
+        items.push({
+          id: item.id,
+          type: 'Resource',
+          title: item.title,
+          slug: item.slug,
+          categorySlug: item.categorySlug || undefined,
+          url: resourceUrl,
+          imageSrc: resourceImage,
+        });
+      }
+    });
+
+    return items.sort((a, b) => {
+      const aHasRealImage = a.imageSrc !== '/static.jpg';
+      const bHasRealImage = b.imageSrc !== '/static.jpg';
+
+      if (aHasRealImage && !bHasRealImage) return -1;
+      if (!aHasRealImage && bHasRealImage) return 1;
+      return 0;
+    });
+  }, [results, contentMap]);
+
+  const totalPages = Math.ceil(allResultItems.length / ITEMS_PER_PAGE);
+  const startIndex = (currentPage - 1) * ITEMS_PER_PAGE;
+  const paginatedItems = allResultItems.slice(
+    startIndex,
+    startIndex + ITEMS_PER_PAGE
+  );
+
+  const handlePageChange = (page: number) => {
+    setCurrentPage(page);
+  };
+
+  const getResultBadge = (type: string, categorySlug?: string) => {
+    switch (type) {
+      case 'StoryFragment':
+        return (
+          <span className="inline-flex items-center rounded-full bg-blue-100 px-2 py-1 text-xs font-medium text-blue-800">
+            Page
+          </span>
+        );
+      case 'ContextPane':
+        return (
+          <span className="inline-flex items-center rounded-full bg-green-100 px-2 py-1 text-xs font-medium text-green-800">
+            Context
+          </span>
+        );
+      case 'Resource':
+        return (
+          <span className="inline-flex items-center rounded-full bg-orange-100 px-2 py-1 text-xs font-medium text-orange-800">
+            {categorySlug || 'Resource'}
+          </span>
+        );
+      default:
+        return null;
+    }
+  };
+
+  if (allResultItems.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className="p-6">
+      <div className="mb-6">
+        <h2 className="text-mydarkgrey text-lg font-semibold">
+          {allResultItems.length} result{allResultItems.length !== 1 ? 's' : ''}{' '}
+          found
+        </h2>
+        <p className="mt-1 text-sm text-gray-600">
+          Showing {startIndex + 1}-
+          {Math.min(startIndex + ITEMS_PER_PAGE, allResultItems.length)} of{' '}
+          {allResultItems.length}
+        </p>
+      </div>
+
+      <div className="mb-8 space-y-4">
+        {paginatedItems.map((item) => (
+          <div
+            key={item.id}
+            className="hover:border-myblue rounded-lg border border-gray-200 p-4 transition-colors"
+          >
+            <a href={item.url} onClick={onResultClick} className="group block">
+              <div className="flex items-start gap-4">
+                <div
+                  className="flex-shrink-0 overflow-hidden rounded-lg bg-gray-100"
+                  style={{ width: '120px', height: '67.5px' }}
+                >
+                  <img
+                    src={item.imageSrc}
+                    alt={item.title}
+                    className="h-full w-full object-cover"
+                    style={{ width: '100%', height: '100%' }}
+                  />
+                </div>
+
+                <div className="min-w-0 flex-1">
+                  <div className="flex items-start justify-between gap-4">
+                    <div className="flex-1">
+                      <div className="mb-2">
+                        <h3 className="text-mydarkgrey group-hover:text-myblue line-clamp-2 font-semibold transition-colors">
+                          {item.title}
+                        </h3>
+                      </div>
+
+                      {item.type === 'StoryFragment' && item.description && (
+                        <p className="mb-2 line-clamp-2 text-sm text-gray-600">
+                          {item.description}
+                        </p>
+                      )}
+
+                      {item.topics && item.topics.length > 0 && (
+                        <div className="mb-2 flex flex-wrap gap-1">
+                          {item.topics.slice(0, 3).map((topic) => (
+                            <span
+                              key={topic}
+                              className="inline-flex items-center rounded-full bg-gray-100 px-2 py-1 text-xs text-gray-700"
+                            >
+                              {topic}
+                            </span>
+                          ))}
+                          {item.topics.length > 3 && (
+                            <span className="text-xs text-gray-500">
+                              +{item.topics.length - 3} more
+                            </span>
+                          )}
+                        </div>
+                      )}
+
+                      <p className="truncate text-xs text-gray-500">
+                        {item.url}
+                      </p>
+                    </div>
+
+                    <div className="flex-shrink-0 text-right">
+                      <div className="mb-2">
+                        {getResultBadge(item.type, item.categorySlug)}
+                      </div>
+                    </div>
+                  </div>
+                </div>
+              </div>
+            </a>
+          </div>
+        ))}
+      </div>
+
+      {totalPages > 1 && (
+        <div className="flex items-center space-x-1">
+          <Pagination.Root
+            count={allResultItems.length}
+            pageSize={ITEMS_PER_PAGE}
+            page={currentPage}
+            onPageChange={(details) => handlePageChange(details.page)}
+          >
+            <Pagination.PrevTrigger className="text-mydarkgrey flex items-center rounded-md border border-gray-300 px-3 py-2 text-sm hover:bg-gray-50 disabled:cursor-not-allowed disabled:opacity-50">
+              <ChevronLeftIcon className="mr-1 h-4 w-4" />
+              Previous
+            </Pagination.PrevTrigger>
+
+            <Pagination.Context>
+              {(pagination) =>
+                pagination.pages.map((page, index) =>
+                  page.type === 'page' ? (
+                    <Pagination.Item
+                      key={index}
+                      value={page.value}
+                      type="page"
+                      className={`cursor-pointer rounded-md px-3 py-2 text-sm ${
+                        page.value === currentPage
+                          ? 'bg-myblue text-white'
+                          : 'text-mydarkgrey hover:bg-gray-50'
+                      }`}
+                    >
+                      {page.value}
+                    </Pagination.Item>
+                  ) : (
+                    <span key={index} className="px-2 text-gray-400">
+                      ...
+                    </span>
+                  )
+                )
+              }
+            </Pagination.Context>
+
+            <Pagination.NextTrigger className="text-mydarkgrey flex items-center rounded-md border border-gray-300 px-3 py-2 text-sm hover:bg-gray-50 disabled:cursor-not-allowed disabled:opacity-50">
+              Next
+              <ChevronRightIcon className="ml-1 h-4 w-4" />
+            </Pagination.NextTrigger>
+          </Pagination.Root>
+        </div>
+      )}
+    </div>
+  );
+}

package/templates/src/components/search/SearchWrapper.tsx

@@ -0,0 +1,41 @@
+import { useState } from 'react';
+import { MagnifyingGlassIcon } from '@heroicons/react/24/outline';
+import SearchModal from './SearchModal';
+import type { FullContentMapItem } from '@/types/tractstack';
+
+interface SearchWrapperProps {
+  contentMap: FullContentMapItem[];
+}
+
+export default function SearchWrapper({ contentMap }: SearchWrapperProps) {
+  const [isSearchOpen, setIsSearchOpen] = useState(false);
+
+  const handleSearchOpen = () => {
+    setIsSearchOpen(true);
+  };
+
+  const handleSearchClose = () => {
+    setIsSearchOpen(false);
+  };
+
+  return (
+    <>
+      <button
+        onClick={handleSearchOpen}
+        className="text-myblue/80 hover:text-myblue hover:rotate-6"
+        title="Search content"
+        aria-label="Search content"
+      >
+        <MagnifyingGlassIcon className="h-6 w-6" />
+      </button>
+
+      {isSearchOpen && (
+        <SearchModal
+          isOpen={isSearchOpen}
+          onClose={handleSearchClose}
+          contentMap={contentMap}
+        />
+      )}
+    </>
+  );
+}

package/templates/src/hooks/useSearch.ts

@@ -0,0 +1,179 @@
+import { useState, useCallback, useRef, useMemo } from 'react';
+import { TractStackAPI } from '@/utils/api';
+
+export interface SearchResults {
+  storyFragmentIds: string[];
+  contextPaneIds: string[];
+  resourceIds: string[];
+}
+
+interface UseSearchReturn {
+  searchResults: SearchResults;
+  isLoading: boolean;
+  error: string | null;
+  totalResults: number;
+  executeSearch: (query: string) => void;
+  clearResults: () => void;
+}
+
+const DEBOUNCE_MS = 100;
+const BACKEND_THROTTLE_MS = 1000;
+
+export function useSearch(): UseSearchReturn {
+  const [searchResults, setSearchResults] = useState<SearchResults>({
+    storyFragmentIds: [],
+    contextPaneIds: [],
+    resourceIds: [],
+  });
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const debounceRef = useRef<NodeJS.Timeout>();
+  const lastSearchTimeRef = useRef<number>(0);
+  const queuedQueryRef = useRef<string | null>(null);
+  const queueTimeoutRef = useRef<NodeJS.Timeout>();
+  const isFirstSearchRef = useRef<boolean>(true);
+
+  const api = useMemo(() => new TractStackAPI(), []);
+
+  const performSearch = useCallback(
+    async (query: string) => {
+      if (!query.trim() || query.trim().length < 3) {
+        return;
+      }
+
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const response = await api.search(query.trim());
+
+        if (response.success && response.data) {
+          setSearchResults(response.data);
+          lastSearchTimeRef.current = Date.now();
+        } else {
+          // Handle 429 silently - backend is protecting itself
+          if (response.error?.includes('too frequently')) {
+            // Don't set error for rate limiting, just maintain loading state
+            return;
+          }
+          setError(response.error || 'Search failed');
+          setSearchResults({
+            storyFragmentIds: [],
+            contextPaneIds: [],
+            resourceIds: [],
+          });
+        }
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Search failed');
+        setSearchResults({
+          storyFragmentIds: [],
+          contextPaneIds: [],
+          resourceIds: [],
+        });
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [api]
+  );
+
+  const processQueue = useCallback(() => {
+    if (queuedQueryRef.current) {
+      const queryToProcess = queuedQueryRef.current;
+      queuedQueryRef.current = null;
+      performSearch(queryToProcess);
+    }
+  }, [performSearch]);
+
+  const executeSearchWithThrottling = useCallback(
+    (query: string) => {
+      const now = Date.now();
+      const timeSinceLastSearch = now - lastSearchTimeRef.current;
+
+      // First search or enough time has passed - execute immediately
+      if (
+        isFirstSearchRef.current ||
+        timeSinceLastSearch >= BACKEND_THROTTLE_MS
+      ) {
+        isFirstSearchRef.current = false;
+        performSearch(query);
+      } else {
+        // Queue the search and schedule it to run when throttle window expires
+        queuedQueryRef.current = query;
+
+        // Clear any existing queue timeout
+        if (queueTimeoutRef.current) {
+          clearTimeout(queueTimeoutRef.current);
+        }
+
+        // Schedule execution for when the throttle window expires
+        const remainingTime = BACKEND_THROTTLE_MS - timeSinceLastSearch;
+        queueTimeoutRef.current = setTimeout(processQueue, remainingTime);
+      }
+    },
+    [performSearch, processQueue]
+  );
+
+  const executeSearch = useCallback(
+    (query: string) => {
+      // Clear existing debounce
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+
+      // Handle empty or short queries immediately
+      if (!query.trim() || query.trim().length < 3) {
+        setSearchResults({
+          storyFragmentIds: [],
+          contextPaneIds: [],
+          resourceIds: [],
+        });
+        setError(null);
+        setIsLoading(false);
+        return;
+      }
+
+      // Debounce the actual search execution
+      debounceRef.current = setTimeout(() => {
+        executeSearchWithThrottling(query);
+      }, DEBOUNCE_MS);
+    },
+    [executeSearchWithThrottling]
+  );
+
+  const clearResults = useCallback(() => {
+    // Clear all timeouts
+    if (debounceRef.current) {
+      clearTimeout(debounceRef.current);
+    }
+    if (queueTimeoutRef.current) {
+      clearTimeout(queueTimeoutRef.current);
+    }
+
+    // Reset state
+    setSearchResults({
+      storyFragmentIds: [],
+      contextPaneIds: [],
+      resourceIds: [],
+    });
+    setIsLoading(false);
+    setError(null);
+    queuedQueryRef.current = null;
+    isFirstSearchRef.current = true;
+  }, []);
+
+  const totalResults =
+    searchResults.storyFragmentIds.length +
+    searchResults.contextPaneIds.length +
+    searchResults.resourceIds.length;
+
+  return {
+    searchResults,
+    isLoading,
+    error,
+    totalResults,
+    executeSearch,
+    clearResults,
+  };
+}

package/templates/src/utils/api.ts

@@ -73,6 +73,11 @@ export class TractStackAPI {
     const defaultHeaders = {
       'Content-Type': 'application/json',
       'X-Tenant-ID': this.tenantId,
+      ...(typeof window !== 'undefined' &&
+        (window as any).TRACTSTACK_CONFIG?.sessionId && {
+          'X-TractStack-Session-ID': (window as any).TRACTSTACK_CONFIG
+            .sessionId,
+        }),
     };
 
     try {
@@ -133,6 +138,16 @@ export class TractStackAPI {
     });
   }
 
+  async search(query: string): Promise<
+    APIResponse<{
+      storyFragmentIds: string[];
+      contextPaneIds: string[];
+      resourceIds: string[];
+    }>
+  > {
+    return this.post('/api/v1/nodes/panes/search', { query });
+  }
+
   async getContent(slug: string): Promise<APIResponse> {
     return this.get(`/api/v1/content/${slug}`);
   }

package/templates/src/utils/customHelpers.ts

@@ -0,0 +1,23 @@
+// URL Helper: Strip category prefix from slug
+// e.g., "people-bleako" -> "bleako"
+export function getCleanSlug(categorySlug: string, fullSlug: string): string {
+  const prefix = `${categorySlug}-`;
+  return fullSlug.startsWith(prefix) ? fullSlug.slice(prefix.length) : fullSlug;
+}
+
+// Build proper URL for resource
+// e.g., category="people", slug="people-bleako" -> "/people/bleako"
+export function getResourceUrl(categorySlug: string, fullSlug: string): string {
+  const cleanSlug = getCleanSlug(categorySlug, fullSlug);
+  return `/${categorySlug}/${cleanSlug}`;
+}
+
+// Image Helper: Placeholder implementation
+export function getResourceImage(
+  id: string,
+  slug: string,
+  category: string
+): string {
+  console.log(`please define getResourceImage`, id, slug, category);
+  return '/static.jpg';
+}

package/utils/inject-files.ts

@@ -906,7 +906,23 @@ export async function injectTemplateFiles(
       src: resolve('../templates/src/components/Fragment.astro'),
       dest: 'src/components/Fragment.astro',
     },
-
+    // Search Components
+    {
+      src: resolve('../templates/src/components/search/SearchWrapper.tsx'),
+      dest: 'src/components/search/SearchWrapper.tsx',
+    },
+    {
+      src: resolve('../templates/src/components/search/SearchModal.tsx'),
+      dest: 'src/components/search/SearchModal.tsx',
+    },
+    {
+      src: resolve('../templates/src/components/search/SearchResults.tsx'),
+      dest: 'src/components/search/SearchResults.tsx',
+    },
+    {
+      src: resolve('../templates/src/hooks/useSearch.ts'),
+      dest: 'src/hooks/useSearch.ts',
+    },
     // Profile Components
     {
       src: resolve('../templates/src/components/profile/ProfileConsent.tsx'),
@@ -2058,6 +2074,11 @@ export async function injectTemplateFiles(
       dest: 'src/custom/CustomRoutes.astro',
       protected: true,
     },
+    {
+      src: resolve('../templates/src/utils/customHelpers.ts'),
+      dest: 'src/utils/customHelpers.ts',
+      protected: true,
+    },
 
     // Example Components (Conditional)
     ...(config?.includeExamples