@netlify/spark-ui 1.12.0-alpha.0 → 1.12.0-alpha.2

package/packages/components/preact/SearchModal/components/SearchModal/SearchModal.tsx

@@ -1,6 +1,8 @@
 import { type ComponentChildren } from 'preact';
 import { useState, useEffect, useRef } from 'preact/hooks';
 
+import { KapaProvider } from '@kapaai/react-sdk';
+
 import Modal from '../../../../preact/Modal/Modal';
 import KeyboardKey from '../../../../preact/KeyboardKey/KeyboardKey';
 import SearchWindow from '../../components/SearchWindow';
@@ -13,10 +15,11 @@ import {
   useSearchHotkeys,
   useSearchParams,
   useSearchToggles,
-  useSearchLogger,
+  useSearchAnalytics,
 } from '../../hooks';
 
 import AskNetlify from '../../../../preact/AskNetlify/AskNetlify';
+import { useAskAnalytics } from '../../../../preact/AskNetlify/hooks/useAskAnalytics';
 
 import './SearchModal.css';
 
@@ -30,31 +33,9 @@ interface Props {
 function SearchModal(
   props: Props = { className: '', children: undefined, debug: false, kapaIntegrationId: undefined }
 ) {
-  const [isPagefindLoaded, setIsPagefindLoaded] = useState(false);
-  const [modalState, setModalState] = useState({ current: 'search' });
-
-  // Poll for the existence of window.pagefind.
-  useEffect(() => {
-    let intervalId: number;
-
-    const checkForPagefind = () => {
-      if (window.pagefind) {
-        setIsPagefindLoaded(true);
-        if (intervalId) clearInterval(intervalId);
-      }
-    };
-
-    // Check immediately and then start polling every 100ms.
-    checkForPagefind();
-    intervalId = setInterval(checkForPagefind, 100);
-
-    // Cleanup the interval when the component unmounts.
-    return () => clearInterval(intervalId);
-  }, []);
-
   const { children, className, debug, ...rest } = props;
-  const { state, actions } = useSearch();
 
+  const [modalState, setModalState] = useState({ current: 'search' });
   const [searchOpen, setSearchOpen] = useState(false);
   const openSearch = () => setSearchOpen(true);
   const closeSearch = () => setSearchOpen(false);
@@ -62,11 +43,13 @@ function SearchModal(
   const modalRef = useRef<HTMLDialogElement>(null);
   const containerRef = useClickOutside<HTMLDivElement>(closeSearch);
 
-  useSearchLogger(state, debug);
-  useSearchToggles(isPagefindLoaded, openSearch, setModalState);
-  useSearchParams(isPagefindLoaded, actions.setSearchTerm, openSearch);
-  useSearchHotkeys(isPagefindLoaded, searchOpen, openSearch, closeSearch);
-  useKeyboardNav(isPagefindLoaded, modalRef, searchOpen, closeSearch);
+  const { state, actions } = useSearch();
+  useSearchToggles(openSearch, setModalState);
+  useSearchParams(actions.setSearchTerm, openSearch);
+  useSearchHotkeys(searchOpen, openSearch, closeSearch);
+  useKeyboardNav(modalRef, searchOpen, closeSearch);
+  useSearchAnalytics(state, debug);
+  const { handleNewQuery, handleAnswer } = useAskAnalytics();
 
   useEffect(() => {
     if (!modalRef.current) return;
@@ -75,71 +58,72 @@ function SearchModal(
 
   useEffect(() => {
     const input = modalRef.current?.querySelector('input');
-
     if (input) input.focus();
-
-    if (modalState.current === 'ask') {
-      setTimeout(() => {
-        modalRef.current.classList.add('n-search-modal-ask');
-      }, 150);
-    } else if (modalState.current === 'search') {
-      setTimeout(() => {
-        modalRef.current.classList.remove('n-search-modal-ask');
-      }, 150);
-    }
   }, [modalState.current]);
 
   return (
-    <Modal
-      ref={modalRef}
-      className={`n-search-modal ${className ? className : ''}`}
-      data-state={modalState.current}
-      {...rest}
+    <KapaProvider
+      integrationId={props.kapaIntegrationId || ''}
+      callbacks={{
+        askAI: {
+          onQuerySubmit: handleNewQuery,
+          onAnswerGenerationCompleted: handleAnswer,
+        },
+      }}
     >
-      <div ref={containerRef} className="n-search-container">
-        {modalState.current === 'ask' && (
-          <AskNetlify setModalState={setModalState} kapaIntegrationId={props.kapaIntegrationId} />
-        )}
-        {modalState.current === 'search' && (
-          <>
-            <SearchInput setSearchTerm={actions.setSearchTerm} initialValue={state.searchTerm} />
-
-            <SearchWindow
-              searchLoading={state.isLoading}
-              searchTerm={state.searchTerm}
-              results={state.results}
-            >
-              <>
-                {props.kapaIntegrationId && (
-                  <SearchLink
-                    as="button"
-                    icon="askNetlify"
-                    label="Ask Netlify AI"
-                    onClick={() => {
-                      setModalState({ current: 'ask' });
-                    }}
-                  />
-                )}
-                {children}
-              </>
-            </SearchWindow>
-
-            <div className="n-search-footer">
-              <p className="n-search-footer-tip">
-                <KeyboardKey keyNames={['Esc']} />
-                to close
-              </p>
-              <p className="n-search-footer-tip">
-                <KeyboardKey keyNames={['Tab']} />
-                <span>or</span>
-                <KeyboardKey keyNames={['↑', '↓']} />
-                to navigate
-              </p>
-            </div>
-          </>
-        )}
-      </div>
-    </Modal>
+      <Modal
+        ref={modalRef}
+        className={`n-search-modal ${className ? className : ''}`}
+        data-state={modalState.current}
+        {...rest}
+      >
+        <div ref={containerRef} className="n-search-container">
+          {modalState.current === 'ask' && (
+            <AskNetlify setModalState={setModalState} initialQuery={state.searchTerm} />
+          )}
+          {modalState.current === 'search' && (
+            <>
+              <SearchInput setSearchTerm={actions.setSearchTerm} initialValue={state.searchTerm} />
+
+              <SearchWindow
+                setModalState={setModalState}
+                searchLoading={state.isLoading}
+                searchTerm={state.searchTerm}
+                results={state.results}
+              >
+                <>
+                  {props.kapaIntegrationId && (
+                    <SearchLink
+                      as="button"
+                      icon="askNetlify"
+                      label="Ask Netlify"
+                      excerpt="Get an instant AI-generated answer"
+                      onClick={() => {
+                        setModalState({ current: 'ask' });
+                      }}
+                    />
+                  )}
+                  {children}
+                </>
+              </SearchWindow>
+
+              <div className="n-search-footer">
+                <p className="n-search-footer-tip">
+                  <KeyboardKey keyNames={['Esc']} />
+                  to close
+                </p>
+                <p className="n-search-footer-tip">
+                  <KeyboardKey keyNames={['Tab']} />
+                  <span>or</span>
+                  <KeyboardKey keyNames={['↑', '↓']} />
+                  to navigate
+                </p>
+              </div>
+            </>
+          )}
+        </div>
+      </Modal>
+    </KapaProvider>
   );
 }
 

package/packages/components/preact/SearchModal/components/SearchWindow.tsx

@@ -1,78 +1,96 @@
 import type { FunctionComponent } from 'preact';
 import type { SearchResultsProps, SearchWindowProps } from '../types/search.types';
-import { useMemo } from 'preact/hooks';
 import SearchHeading from './SearchHeading/SearchHeading';
 import SearchLink from './SearchLink/SearchLink';
+import SearchLinkThemeToggle from './SearchLinkThemeToggle';
 
-import { handleThemeChange, ThemeMap, Theme } from '../../../../utils/theme';
+const AskNetlifyLink = ({
+  searchTerm,
+  setModalState,
+}: {
+  searchTerm: string;
+  setModalState: (state: { current: string }) => void;
+}) => (
+  <SearchLink
+    as="button"
+    icon="askNetlify"
+    excerpt="Get an instant AI-generated answer"
+    onClick={() => setModalState({ current: 'ask' })}
+  >
+    Ask Netlify: <span className="n-search-term">{searchTerm}</span>
+  </SearchLink>
+);
+
+const NoResults = ({ searchTerm }: { searchTerm: string }) => (
+  <div className="n-search-feedback">
+    <p className="n-results-info">
+      0 results for <span className="n-search-term">{searchTerm}</span>
+    </p>
+  </div>
+);
 
-/* --- Search Results Window (for active searches) --- */
 const SearchResults: FunctionComponent<SearchResultsProps> = ({
+  setModalState,
   searchLoading,
   searchTerm,
   results,
 }) => {
-  if (searchLoading) {
-    return (
-      <SearchHeading>
-        Searching for <span className="n-search-term">{searchTerm}</span> ...
-      </SearchHeading>
-    );
-  }
-
-  if (!results || results.length === 0) {
-    return (
-      <SearchHeading>
-        0 results for <span className="n-search-term">{searchTerm}</span>
-      </SearchHeading>
-    );
-  }
-
-  const renderedResults = useMemo(() => {
-    return results.map((result, i) => (
-      <li key={i} className="n-results-list-item">
-        <SearchLink {...result} />
-      </li>
-    ));
-  }, [results]);
+  const noResults =
+    searchTerm === 'no results' || (!searchLoading && (!results || results.length === 0));
 
   return (
-    <ul className="n-results-list" role="list">
-      {renderedResults}
-    </ul>
+    <>
+      <AskNetlifyLink searchTerm={searchTerm} setModalState={setModalState} />
+      {noResults ? (
+        <NoResults searchTerm={searchTerm} />
+      ) : (
+        <ul className="n-results-list" role="list">
+          {results?.map((result, i) => (
+            <li key={i} className="n-results-list-item">
+              <SearchLink {...result} />
+            </li>
+          ))}
+        </ul>
+      )}
+    </>
   );
 };
 
-/* --- Main Search Results Component --- */
 export default function SearchWindow({
+  setModalState,
   searchLoading,
   searchTerm,
   results,
   children: DefaultWindow,
 }: SearchWindowProps) {
+  const hasQuery = searchTerm?.length > 1;
+
   return (
     <div className="n-search-window">
       <div className="n-search-links">
-        {searchTerm && searchTerm.length > 1 ? (
-          <SearchResults searchLoading={searchLoading} searchTerm={searchTerm} results={results} />
-        ) : DefaultWindow ? (
+        {hasQuery ? (
+          searchLoading ? (
+            <>
+              <AskNetlifyLink searchTerm={searchTerm} setModalState={setModalState} />
+              <div className="n-search-feedback">
+                <div className="n-loader-dots-spinner" />
+              </div>
+            </>
+          ) : (
+            <SearchResults
+              setModalState={setModalState}
+              searchLoading={searchLoading}
+              searchTerm={searchTerm}
+              results={results}
+            />
+          )
+        ) : (
           <>
             {DefaultWindow}
-
             <SearchHeading>Actions</SearchHeading>
-            <SearchLink
-              as="button"
-              icon="lightbulb"
-              label="Toggle theme"
-              onClick={() => {
-                const isDarkTheme = window.matchMedia('(prefers-color-scheme: dark)').matches;
-                const currentTheme = document.documentElement.getAttribute('data-theme');
-                const theme = isDarkTheme ? 'dark' : currentTheme ? currentTheme : 'light';
-                theme && handleThemeChange(ThemeMap[theme as Theme]);
-              }}
-            />
+            <SearchLinkThemeToggle />
           </>
-        ) : null}
+        )}
       </div>
     </div>
   );

package/packages/components/preact/SearchModal/hooks/index.ts

@@ -1,5 +1,5 @@
 export { useSearch } from '../hooks/useSearch';
-export { useSearchLogger } from './useSearchLogger';
+export { useSearchAnalytics } from './useSearchAnalytics';
 export { useKeyboardNav } from '../hooks/useKeyboardNav';
 export { useSearchHotkeys } from '../hooks/useSearchHotkeys';
 export { useSearchParams } from '../hooks/useSearchParams';

package/packages/components/preact/SearchModal/hooks/useKeyboardNav.ts

@@ -15,13 +15,11 @@ import { useEffect } from 'preact/hooks';
  */
 
 export function useKeyboardNav(
-  isPagefindLoaded: boolean,
   containerRef: RefObject<HTMLElement>,
   isOpen: boolean,
   onClose: () => void
 ) {
   useEffect(() => {
-    if (!isPagefindLoaded) return;
     const handleKeydown = (e: KeyboardEvent) => {
       if (!isOpen) return;
 
@@ -48,5 +46,5 @@ export function useKeyboardNav(
 
     document.addEventListener('keydown', handleKeydown);
     return () => document.removeEventListener('keydown', handleKeydown);
-  }, [isPagefindLoaded, containerRef, isOpen, onClose]);
+  }, [containerRef, isOpen, onClose]);
 }

package/packages/components/preact/SearchModal/hooks/useSearch.ts

@@ -21,14 +21,14 @@ export function useSearch() {
   const cacheRef = useRef(new Map());
 
   const { reset, run } = useTimeout((query: string) => {
-      submitSearch(query);
+    if (query && query.length >= 2) submitSearch(query);
   }, 150);
 
   const submitSearch = async (query: string) => {
     if (!window?.pagefind) return;
 
     setSearchState(prev => ({ ...prev, isLoading: true }));
-    
+
     if (cacheRef.current.has(query)) {
       setSearchState(prev => ({
         ...prev,
@@ -38,20 +38,24 @@ export function useSearch() {
       return;
     }
     const search = await window.pagefind.debouncedSearch(query);
-    const results = search?.results && await Promise.all(
-      search?.results?.slice(0, 15).map(async (result: any) => {
-        const data = await result.data();
-        const removeAnchorLink = (text: string) => text.replace("#", '')
+    const results =
+      search?.results &&
+      (await Promise.all(
+        search?.results?.slice(0, 15).map(async (result: any) => {
+          const data = await result.data();
+          const removeAnchorLink = (text: string) => text.replace('#', '');
+
+          return {
+            icon: 'pageWithLines',
+            resource: data.meta?.resource,
+            label: data.meta?.title,
+            url: data.url,
+            excerpt: removeAnchorLink(data.excerpt),
+          };
+        })
+      ));
 
-        return {
-          icon: 'pageWithLines',
-          resource: data.meta?.resource,
-          label: data.meta?.title,
-          url: data.url,
-          excerpt: removeAnchorLink(data.excerpt),
-        };
-      })
-    );
+    cacheRef.current.set(query, results);
 
     setSearchState(prev => ({
       ...prev,
@@ -61,7 +65,7 @@ export function useSearch() {
   };
 
   const handleSearchChange = (query: string) => {
-    setSearchState(prev => ({ ...prev, searchTerm: query }));
+    setSearchState(prev => ({ ...prev, results: [], searchTerm: query }));
     reset();
     run(query);
   };

package/packages/components/preact/SearchModal/hooks/{useSearchLogger.ts → useSearchAnalytics.ts}

@@ -16,29 +16,29 @@ import Analytics from '../../../../analytics/analytics';
  *   - `state.searchTerm`: The current search query string.
  *   - `state.results`: The search results array. If it's empty, the hook will log a no-results event.
  * @param {boolean} [debug=false] - Flag to enable debug mode. If true, additional debug information will be sent with the event payloads.
- * 
+ *
  * @returns {Object} - An object with the following function:
  *   - `handleClick`: A callback function that should be attached to search result click events. It tracks `search:result_selected` events with the clicked result's title and URL.
  *
  * @example
- * const { handleClick } = useSearchLogger(searchState);
+ * const { handleClick } = useSearchAnalytics(searchState);
  *
  * // In your component, attach handleClick to the search result links
  * <a href="result-url" onClick={handleClick}>Search Result</a>
  */
 
-export function useSearchLogger(state?: SearchState, debug?: boolean) {
+export function useSearchAnalytics(state?: SearchState, debug?: boolean) {
   const ref = useRef<Analytics>(new Analytics());
   const analytics = ref.current;
 
-  const enableDebugger = (o: SearchGTMObjectProps) => o.debug_mode = true
+  const enableDebugger = (o: SearchGTMObjectProps) => (o.debug_mode = true);
 
-  // Log search query
+  // Log search query that is minimum of 3 characters long
   useEffect(() => {
-    if (!state?.searchTerm) return;
+    if (!state?.searchTerm || state?.searchTerm.length < 3) return;
     const payload = { query: state?.searchTerm };
 
-    if (debug) enableDebugger(payload)
+    if (debug) enableDebugger(payload);
 
     analytics.track('search:new_query', payload);
   }, [state?.searchTerm]);
@@ -49,7 +49,7 @@ export function useSearchLogger(state?: SearchState, debug?: boolean) {
 
     const payload = { query: state?.searchTerm };
 
-    if (debug) enableDebugger(payload)
+    if (debug) enableDebugger(payload);
 
     if (state?.searchTerm && state.results.length === 0) {
       analytics.track('search:no_results', payload);
@@ -68,8 +68,7 @@ export function useSearchLogger(state?: SearchState, debug?: boolean) {
       resultUrl: url,
     };
 
-    if (debug) enableDebugger(payload)
-
+    if (debug) enableDebugger(payload);
 
     analytics.track('search:result_selected', payload);
   }, []);

package/packages/components/preact/SearchModal/hooks/useSearchHotkeys.ts

@@ -13,10 +13,8 @@ import { useEffect } from 'preact/hooks';
  * @param onClose - Callback to close the search interface.
  */
 
-export function useSearchHotkeys(isPagefindLoaded: boolean, isOpen: boolean, onOpen: () => void, onClose: () => void) {
+export function useSearchHotkeys(isOpen: boolean, onOpen: () => void, onClose: () => void) {
   useEffect(() => {
-    if (!isPagefindLoaded) return;
-    
     const handleKeydown = (e: KeyboardEvent) => {
       if (e.metaKey && e.key === 'k') {
         e.preventDefault();
@@ -27,5 +25,5 @@ export function useSearchHotkeys(isPagefindLoaded: boolean, isOpen: boolean, onO
 
     document.addEventListener('keydown', handleKeydown);
     return () => document.removeEventListener('keydown', handleKeydown);
-  }, [isPagefindLoaded, isOpen, onOpen, onClose]);
+  }, [isOpen, onOpen, onClose]);
 }

package/packages/components/preact/SearchModal/hooks/useSearchParams.ts

@@ -1,4 +1,4 @@
-import { useEffect } from 'preact/hooks';
+import { useEffect, useState } from 'preact/hooks';
 
 /**
  * Custom hook that checks the current URL for a `search` query parameter
@@ -11,8 +11,30 @@ import { useEffect } from 'preact/hooks';
  * @param onOpen - Function to trigger opening of the search interface (e.g., modal or drawer).
  */
 
-export function useSearchParams(isPagefindLoaded: boolean, setSearchTerm: (term: string) => void, onOpen: () => void) {
+export function useSearchParams(setSearchTerm: (term: string) => void, onOpen: () => void) {
+  const [isPagefindLoaded, setIsPagefindLoaded] = useState(false);
+
+  // Poll for the existence of window.pagefind.
+  useEffect(() => {
+    let intervalId: number;
+
+    const checkForPagefind = () => {
+      if (window.pagefind) {
+        setIsPagefindLoaded(true);
+        if (intervalId) clearInterval(intervalId);
+      }
+    };
+
+    // Check immediately and then start polling every 100ms.
+    checkForPagefind();
+    intervalId = setInterval(checkForPagefind, 100);
+
+    // Cleanup the interval when the component unmounts.
+    return () => clearInterval(intervalId);
+  }, []);
+
   useEffect(() => {
+    // Cleanup the interval when the component unmounts.
     if (typeof location === 'undefined' || isPagefindLoaded) return;
     const query = location?.search && new URLSearchParams(location.search).get('search');
     if (query) {

package/packages/components/preact/SearchModal/hooks/useSearchToggles.ts

@@ -13,12 +13,10 @@ import { useEffect } from 'preact/hooks';
  */
 
 export function useSearchToggles(
-  isPagefindLoaded: boolean,
   onOpen: () => void,
   setState: (state: { current: string }) => void
 ) {
   useEffect(() => {
-    if (!isPagefindLoaded) return;
     const toggles = document.querySelectorAll('[data-ntl-search-toggle]');
 
     if (!toggles.length) return;
@@ -35,5 +33,5 @@ export function useSearchToggles(
     return () => {
       toggles.forEach(t => t.removeEventListener('click', onOpen));
     };
-  }, [isPagefindLoaded, onOpen]);
+  }, [onOpen]);
 }

package/packages/components/preact/SearchModal/types/search.types.tsx

@@ -3,24 +3,27 @@ import type { IconName } from '../../Icon';
 
 export interface SearchLinkProps {
   as?: any;
-  icon: IconName;
-  label: string;
+  icon?: IconName;
+  label?: string;
   resource?: 'blog' | 'changelog' | 'docs' | 'guide';
   url?: string;
   excerpt?: string;
+  children?: ComponentChildren;
   onClick?: () => void;
 }
 
 export interface SearchWindowProps {
+  setModalState: (e: { current: string }) => void;
   searchLoading: boolean;
-  searchTerm?: string;
+  searchTerm: string;
   results?: SearchLinkProps[];
   children: ComponentChildren;
 }
 
 export interface SearchResultsProps {
+  setModalState: (e: { current: string }) => void;
   searchLoading: boolean;
-  searchTerm?: string;
+  searchTerm: string;
   results?: SearchLinkProps[];
 }
 

package/packages/styles/loaders.css

@@ -0,0 +1,18 @@
+.n-loader-dots-spinner {
+  width: var(--n-loader-dot-w, 50px);
+  aspect-ratio: 1;
+  --_c: no-repeat
+    radial-gradient(farthest-side, var(--n-loader-dot-color, var(--teal-600)) 92%, #0000);
+  background:
+    var(--_c) top,
+    var(--_c) left,
+    var(--_c) right,
+    var(--_c) bottom;
+  background-size: 12px 12px;
+  animation: l7 1s infinite;
+}
+@keyframes l7 {
+  to {
+    transform: rotate(0.5turn);
+  }
+}

package/packages/styles/tokens.css

@@ -166,6 +166,7 @@
   --search-icon-color: var(--neutral-400);
   --search-input-bg-color: var(--neutral-100);
   --search-loading-color: var(--teal-700);
+  --search-source-list-color: var(--neutral-100);
   --search-submit-btn-bg-color: var(--teal-200);
   --search-user-message-color: var(--teal-000);
   --shadow-deep: 0 16px 24px 0 color(srgb 0 0 0 / 0.07), 0 6px 30px 0 color(srgb 0 0 0 / 0.06), 0 8px 10px 0 color(srgb 0 0 0 / 0.1);
@@ -274,6 +275,7 @@
     --search-icon-color: var(--neutral-300);
     --search-input-bg-color: var(--neutral-600);
     --search-loading-color: var(--teal-200);
+    --search-source-list-color: var(--neutral-700);
     --search-submit-btn-bg-color: var(--teal-200);
     --search-user-message-color: var(--teal-800);
     --tabbed-content-bg-color: color(srgb 0.047058823529411764 0.16470588235294117 0.16470588235294117 / 0.2);
@@ -358,6 +360,7 @@
   --search-icon-color: var(--neutral-300);
   --search-input-bg-color: var(--neutral-600);
   --search-loading-color: var(--teal-200);
+  --search-source-list-color: var(--neutral-700);
   --search-submit-btn-bg-color: var(--teal-200);
   --search-user-message-color: var(--teal-800);
   --tabbed-content-bg-color: color(srgb 0.047058823529411764 0.16470588235294117 0.16470588235294117 / 0.2);
@@ -440,6 +443,7 @@
   --search-icon-color: var(--neutral-400);
   --search-input-bg-color: var(--neutral-100);
   --search-loading-color: var(--teal-700);
+  --search-source-list-color: var(--neutral-100);
   --search-submit-btn-bg-color: var(--teal-200);
   --search-user-message-color: var(--teal-000);
   --tabbed-content-bg-color: var(--neutral-000);

package/dist/components/preact/AskNetlify/components/ChatInterface.d.ts

@@ -1,7 +0,0 @@
-interface Props {
-    setModalState?: (e: {
-        current: string;
-    }) => void;
-}
-export default function ChatInterface({ setModalState }: Props): import("preact").JSX.Element;
-export {};