@netlify/spark-ui 1.11.0 → 1.12.0-alpha.1

package/dist/components/preact/index.js

@@ -2,9 +2,9 @@ import { default as t } from "./KeyboardKey/KeyboardKey.js";
 import { default as d } from "./Modal/Modal.js";
 import { default as m } from "./Icon/index.js";
 import { default as s } from "./SearchModal/components/SearchLink/SearchLink.js";
-import { default as x } from "./SearchModal/components/SearchHeading/SearchHeading.js";
+import { default as u } from "./SearchModal/components/SearchHeading/SearchHeading.js";
 import { default as i } from "./SearchModal/components/SearchToggle/SearchToggle.js";
-import { default as S } from "./AskNetlify/AskNetlify.js";
+import { A as S } from "../../chunks/AskNetlify.lrswYyKn.js";
 import "preact";
 import "../../chunks/hooks.module.DGkdD5n9.js";
 import { default as n } from "./SearchModal/components/SearchModal/SearchModal.js";
@@ -13,7 +13,7 @@ export {
   m as Icon,
   t as KeyboardKey,
   d as Modal,
-  x as SearchHeading,
+  u as SearchHeading,
   s as SearchLink,
   n as SearchModal,
   i as SearchToggle

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@netlify/spark-ui",
   "description": "Assets, design tokens, components, and utilities",
-  "version": "1.11.0",
+  "version": "1.12.0-alpha.1",
   "type": "module",
   "main": "dist/components/preact/index.js",
   "types": "dist/components/preact/index.d.ts",
@@ -68,4 +68,4 @@
     "prettier": "^3.5.3",
     "prettier-plugin-astro": "^0.14.1"
   }
-}
+}

package/packages/components/preact/AskNetlify/AskNetlify.css

@@ -12,11 +12,12 @@
 .n-ask-conversation {
   display: grid;
   align-items: flex-end;
+  gap: var(--space-s);
   height: calc(var(--n-search-container-height) + var(--n-search-footer-height));
   padding: var(--n-search-padding-inline);
   overflow-y: auto;
   scroll-behavior: smooth;
-  gap: var(--space-s);
+  grid-template-rows: 1fr;
 }
 
 .n-ask-form {
@@ -84,6 +85,9 @@
   display: grid;
   grid-template-columns: minmax(0, 1fr);
   gap: var(--space-s);
+}
+
+.n-ask-message:first-of-type {
   margin-block-start: var(--space-2xl);
 }
 
@@ -101,6 +105,54 @@
   background: var(--search-user-message-color);
 }
 
+.n-ask-sources {
+  margin-block-start: var(--space-m);
+}
+
+.n-ask-sources-title {
+  font-size: var(--step-0);
+  font-weight: var(--font-weight-bold);
+}
+
+.n-ask-sources a {
+  font-size: var(--step--1);
+}
+
+.n-ask-sources details summary::marker {
+  display: none;
+  content: none;
+}
+
+.n-ask-sources details {
+  background: var(--search-source-list-color);
+  padding: var(--space-xs) var(--space-xs);
+  border-radius: var(--radius-l);
+}
+
+.n-ask-sources details summary {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-xs);
+  cursor: pointer;
+}
+
+.n-ask-sources details ul {
+  margin-block-start: var(--space-3xs);
+}
+
+.n-ask-sources [data-icon='caretRight'] {
+  width: 0.8em;
+  display: inline-block;
+  transform: rotate(90deg);
+  height: auto;
+  color: var(--color-text-weaker);
+}
+
+.n-ask-sources details[open] [data-icon='caretRight'] {
+  transform: rotate(270deg);
+}
+
 /* ----------------------------- */
 /* Form UI                      */
 /* ----------------------------- */
@@ -235,6 +287,7 @@
 }
 
 .n-ask-message-loader :where(#ask-netlify-eyelid-left, #ask-netlify-eyelid-right) {
+  --n-ask-netlify-eyelid-color: var(--search-bg-color);
   transform-origin: top center;
   transform: scaleY(1.035);
   animation: askEyeBlink 4s infinite;

package/packages/components/preact/AskNetlify/AskNetlify.tsx

@@ -1,44 +1,108 @@
-import { useRef } from 'preact/hooks';
-import { KapaProvider } from '@kapaai/react-sdk';
-import Analytics from '../../../analytics/analytics';
-import ChatInterface from './components/ChatInterface';
+import { useState, useRef, useEffect } from 'preact/hooks';
+import { useChat } from '@kapaai/react-sdk';
+import { questions } from './components/QuestionList/questions';
+import { QuestionList } from './components/QuestionList/QuestionList';
+import { BackButton } from './components/BackButton';
+import { ChatMessages } from './components/ChatMessages';
+
 import './AskNetlify.css';
 
-interface AskNetlifyProps {
-  kapaIntegrationId?: string;
+interface Props {
   setModalState?: (e: { current: string }) => void;
+  initialQuery?: string;
 }
 
-export default function AskNetlify(props: AskNetlifyProps) {
-  const analyticsRef = useRef<Analytics>(new Analytics());
+export default function AskNetlify({ setModalState, initialQuery }: Props) {
+  const [message, setMessage] = useState('');
+  const [newMessageReady, setNewMessageReady] = useState(false);
+  const chatRef = useRef<HTMLDivElement>(null);
+  const menuRef = useRef<HTMLUListElement>(null);
+  const lastMessageRef = useRef<HTMLDivElement | null>(null);
+
+  const { conversation, submitQuery, isGeneratingAnswer, isPreparingAnswer, stopGeneration } =
+    useChat();
+
+  const handleSubmit = (e: Event | preact.JSX.TargetedMouseEvent<HTMLButtonElement>) => {
+    e.preventDefault();
+    const target = e.target as HTMLButtonElement;
+    const id = target?.getAttribute('data-question-id');
+    const text = id ? questions[id] : message;
+
+    if (text.trim()) {
+      submitQuery(text.trim());
+    }
+    if (!id) setMessage('');
 
-  if (!props.kapaIntegrationId) return;
+    setNewMessageReady(true);
+  };
+
+  /*
+   * When a new user message is ready, scroll it into view and reset the flag.
+   * This ensures the most recent message is visible to the user immediately after rendering.
+   */
+  useEffect(() => {
+    if (newMessageReady && lastMessageRef.current) {
+      lastMessageRef.current.scrollIntoView({ behavior: 'smooth' });
+      setNewMessageReady(false);
+    }
+  }, [newMessageReady]);
+
+  useEffect(() => {
+    if (initialQuery) {
+      submitQuery(initialQuery.trim());
+      setNewMessageReady(true);
+    }
+  }, [initialQuery]);
 
   return (
-    <KapaProvider
-      integrationId={props.kapaIntegrationId}
-      callbacks={{
-        askAI: {
-          onQuerySubmit: data => {
-            if (!data.question || !data.threadId) return;
-
-            analyticsRef?.current?.track('ask:new_query', {
-              question: data.question,
-              thread_id: data.threadId,
-            });
-          },
-          onAnswerGenerationCompleted: data => {
-            if (!data.questionAnswerId || !data.answer) return;
-
-            analyticsRef?.current?.track('ask:answer_generated', {
-              question_id: data.questionAnswerId,
-              answer_length: data.answer.length,
-            });
-          },
-        },
-      }}
-    >
-      <ChatInterface setModalState={props.setModalState} />
-    </KapaProvider>
+    <div className="n-ask-chat-container">
+      <BackButton onClick={() => setModalState?.({ current: 'search' })} />
+      <div ref={chatRef} className="n-ask-conversation n-search-window">
+        {!conversation.length ? (
+          <QuestionList onClick={handleSubmit} menuRef={menuRef} />
+        ) : (
+          <ChatMessages
+            isPreparingAnswer={isPreparingAnswer}
+            conversation={conversation}
+            lastMessageRef={lastMessageRef}
+          />
+        )}
+      </div>
+
+      <form onSubmit={handleSubmit} className="n-ask-form n-search-input-wrapper">
+        <input
+          className="n-ask-input n-search-input"
+          type="text"
+          value={message}
+          onInput={e => setMessage(e.currentTarget.value)}
+          placeholder="Ask a question..."
+          disabled={isPreparingAnswer || isGeneratingAnswer}
+        />
+
+        {isGeneratingAnswer ? (
+          <button
+            type="button"
+            className="n-ask-form-submit"
+            onClick={stopGeneration}
+            aria-label="Stop generation"
+          >
+            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="var(--neutral-100)">
+              <rect x="0" y="0" width="16" height="16" />
+            </svg>
+          </button>
+        ) : (
+          <button
+            type="submit"
+            className="n-ask-form-submit"
+            disabled={!message.trim() || isPreparingAnswer}
+            aria-label="Send message"
+          >
+            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512" fill="var(--neutral-100)">
+              <path d="M438.6 278.6c12.5-12.5 12.5-32.8 0-45.3l-160-160c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3L338.8 224 32 224c-17.7 0-32 14.3-32 32s14.3 32 32 32l306.7 0L233.4 393.4c-12.5 12.5-12.5 32.8 0 45.3s32.8 12.5 45.3 0l160-160z" />
+            </svg>
+          </button>
+        )}
+      </form>
+    </div>
   );
 }

package/packages/components/preact/AskNetlify/components/ChatMessages.tsx

@@ -1,13 +1,16 @@
 import { marked } from 'marked';
 import Icon from '../../Icon';
 import { Ref } from 'preact';
+import { SourcesList } from './SourcesList';
 
 export function ChatMessages({
   conversation,
   lastMessageRef,
+  isPreparingAnswer,
 }: {
   conversation: any[];
   lastMessageRef: Ref<HTMLDivElement>;
+  isPreparingAnswer: boolean;
 }) {
   return (
     <>
@@ -25,22 +28,24 @@ export function ChatMessages({
             </div>
 
             <div class="n-ask-message-left">
-              {qa.answer ? (
+              {qa.answer && (
                 <div class="n-ask-message-bubble n-ask-bot-message">
                   <div
                     class="n-ask-message-answer n-ask-prose prose flow"
                     dangerouslySetInnerHTML={{ __html: marked.parse(qa.answer) }}
                   />
-                </div>
-              ) : (
-                <div class="n-ask-message-loader">
-                  <Icon name="askNetlify" />
+                  {qa.id && <SourcesList sources={qa.sources} />}
                 </div>
               )}
             </div>
           </div>
         );
       })}
+      {isPreparingAnswer && (
+        <div class="n-ask-message-loader">
+          <Icon name="askNetlify" />
+        </div>
+      )}
     </>
   );
 }

package/packages/components/preact/AskNetlify/components/SourcesList.tsx

@@ -0,0 +1,33 @@
+import Icon from '../../Icon';
+
+export function SourcesList({ sources }) {
+  if (!sources?.length) return null;
+
+  return (
+    <div className="n-ask-sources">
+      <details>
+        <summary>
+          <h4 class="n-ask-sources-title">Sources:</h4>
+          <Icon name="caretRight" />
+        </summary>
+
+        <ul>
+          {sources.map((source, index) => {
+            if (!source.title) return;
+
+            return (
+              <li key={index}>
+                <a href={source.source_url} target="_blank" rel="noopener noreferrer">
+                  {source.title}
+                  {source.subtitle && source.subtitle !== source.title && (
+                    <span> - {source.subtitle}</span>
+                  )}
+                </a>
+              </li>
+            );
+          })}
+        </ul>
+      </details>
+    </div>
+  );
+}

package/packages/components/preact/AskNetlify/hooks/useAskAnalytics.tsx

@@ -0,0 +1,50 @@
+import type { QuerySubmitPayload, AnswerGenerationCompletedPayload } from '@kapaai/react-sdk';
+import { useRef, useCallback } from 'preact/hooks';
+import Analytics from '../../../../analytics/analytics';
+
+/**
+ * Custom hook that tracks analytics events related to Ask Netlify and pushes them to the Google Analytics 4 (GA4) data layer.
+ *
+ * This hook captures two key interaction events and pushes their payloads to the `dataLayer`, enabling tracking in GA4:
+ * - `ask:new_query`: Triggered when a user submits a new question. The payload includes the question text and a thread ID.
+ * - `ask:answer_generated`: Triggered when a generated answer is completed. The payload includes the question ID and the length of the answer.
+ *
+ * Internally, the hook uses an instance of the `Analytics` class to structure and dispatch events. All event payloads are pushed to `window.dataLayer` to be consumed by Google Tag Manager and GA4.
+ *
+ * @returns {Object} - An object with the following functions:
+ *   - `handleNewQuery`: Callback to be invoked when a user submits a new question. Sends a `ask:new_query` event with:
+ *     - `question` (string): The user-submitted question.
+ *     - `thread_id` (string): A unique identifier for the conversation thread.
+ *   - `handleAnswer`: Callback to be invoked when a answer is returned. Sends a `ask:answer_generated` event with:
+ *     - `question_id` (string): The ID linking the question to its answer.
+ *     - `answer_length` (number): The character length of the generated answer.
+
+ */
+
+export function useAskAnalytics() {
+  const ref = useRef<Analytics>(new Analytics());
+  const analytics = ref.current;
+
+  const handleNewQuery = useCallback((data: QuerySubmitPayload) => {
+    if (!data.question || !data.threadId) return;
+
+    analytics?.track('ask:new_query', {
+      question: data.question,
+      thread_id: data.threadId,
+    });
+  }, []);
+
+  const handleAnswer = useCallback((data: AnswerGenerationCompletedPayload) => {
+    if (!data.questionAnswerId || !data.answer) return;
+
+    analytics?.track('ask:answer_generated', {
+      question_id: data.questionAnswerId,
+      answer_length: data.answer.length,
+    });
+  }, []);
+
+  return {
+    handleNewQuery,
+    handleAnswer,
+  };
+}

package/packages/components/preact/Icon/index.tsx

@@ -67,7 +67,7 @@ const AskNetlify: FunctionComponent = () => {
         y="7.3"
         width="3"
         height="2"
-        fill="var(--search-bg-color, currentColor)"
+        fill="var(--n-ask-netlify-eyelid-color, currentColor)"
       />
       <rect
         id="ask-netlify-eyelid-right"
@@ -75,7 +75,7 @@ const AskNetlify: FunctionComponent = () => {
         y="7.3"
         width="3"
         height="2"
-        fill="var(--search-bg-color, currentColor)"
+        fill="var(--n-ask-netlify-eyelid-color, currentColor)"
       />
     </>
   );

package/packages/components/preact/SearchModal/components/SearchLink/SearchLink.css

@@ -33,11 +33,16 @@
   }
 
   & .n-search-link-icon :where(#ask-netlify-eyelid-left, #ask-netlify-eyelid-right) {
+    --n-ask-netlify-eyelid-color: var(--n-search-color-bg-2);
     animation: askEyeBlink 4s infinite;
     animation-delay: 200ms;
   }
 }
 
+.n-search-link-icon :where(#ask-netlify-eyelid-left, #ask-netlify-eyelid-right) {
+  --n-ask-netlify-eyelid-color: var(--search-bg-color);
+}
+
 .n-search-link-title {
   font-weight: var(--font-weight-medium);
   color: var(--color-text-1);

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

@@ -1,5 +1,5 @@
 import type { SearchLinkProps } from '../../types/search.types';
-import { useSearchLogger } from '../../hooks';
+import { useSearchAnalytics } from '../../hooks';
 import './SearchLink.css';
 
 import Icon from '../../../Icon';
@@ -12,8 +12,9 @@ const SearchLink = ({
   excerpt,
   resource,
   onClick,
+  children,
 }: SearchLinkProps) => {
-  const { handleClick: log } = useSearchLogger();
+  const { handleClick: trackClick } = useSearchAnalytics();
 
   return (
     <Component
@@ -21,7 +22,7 @@ const SearchLink = ({
       href={url}
       onClick={(e: Event) => {
         onClick && onClick();
-        log(e);
+        trackClick(e);
       }}
     >
       {icon && (
@@ -31,7 +32,8 @@ const SearchLink = ({
       )}
       <div className="n-search-link-body">
         <p className="n-search-link-title">
-          <span className="n-search-link-label">{label}</span>{' '}
+          {label && <span className="n-search-link-label">{label}</span>}
+          {children && <span className="n-search-link-label">{children}</span>}
           {resource && (
             <span className="n-search-link-badge" data-resource={resource}>
               {resource}

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

@@ -0,0 +1,19 @@
+import SearchLink from '../components/SearchLink/SearchLink';
+import { THEMES } from '../../../../utils/types';
+import { handleThemeChange, ThemeMap } from '../../../../utils/theme';
+
+export default function SearchLinkThemeToggle() {
+  return (
+    <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 THEMES]);
+      }}
+    />
+  );
+}

package/packages/components/preact/SearchModal/components/SearchModal/SearchModal.css

@@ -1,6 +1,7 @@
 @import '../../../KeyboardKey/KeyboardKey.css';
 @import '../SearchHeading/SearchHeading.css';
 @import '../SearchLink/SearchLink.css';
+@import '../../../../../styles/loaders.css';
 
 /* Root Variables */
 .n-search-modal {
@@ -26,9 +27,10 @@
   width: min(var(--n-search-max-w), 100%);
   margin: auto;
   background: var(--n-search-color-bg);
+  transition-delay: 200ms;
 }
 
-.n-search-modal-ask {
+.n-search-modal[data-state='ask'] {
   --n-search-max-w: 800px;
 }
 
@@ -90,6 +92,7 @@
 
 .n-search-links {
   padding: var(--space-2xs);
+  height: 100%;
 }
 
 .n-search-label {
@@ -98,6 +101,16 @@
   align-items: center;
 }
 
+.n-results-list {
+  padding-block-end: var(--space-2xs);
+}
+
+.n-results-info {
+  font-family: var(--font-family-display);
+  font-size: var(--step--1);
+  padding-inline: var(--space-xs);
+}
+
 .n-search-label > * {
   display: inline-block;
   margin: 0;
@@ -111,8 +124,8 @@
 }
 
 .n-search-term {
-  font-weight: var(--font-medium);
-  font-size: 1.1em;
+  font-weight: var(--font-bold);
+  color: var(--n-search-color-text-secondary);
 }
 
 /* Search Results */
@@ -126,6 +139,12 @@
   background: var(--n-search-color-bg);
 }
 
+.n-search-feedback {
+  height: calc(100% - 70px);
+  display: grid;
+  place-content: center;
+}
+
 /* Footer */
 .n-search-footer {
   position: relative;