insytful-ai-search-components 2.1.2 → 2.1.3

package/README.md

@@ -2,23 +2,45 @@
 
 AI-powered search modals with two delivery options:
 
-1. **[Web Component](#web-component-setup)** — Standalone `<insytful-search>` custom element for any HTML page. No React, no build step, no npm. Ideal for CMS sites (Contensis, WordPress, static HTML).
-2. **[React Components](#react-setup)** — Radix-style compound components for React applications. Install via npm.
-
-Both share the same visual design, CSS theming, and Contensis RAG API integration.
+1. **[Web Component](#web-component)** — Standalone `<insytful-search>` custom element for any HTML page. No React, no build step, no npm. Ideal for CMS sites (Contensis, WordPress, static HTML).
+2. **[React Components](#react-components)** — Radix-style compound components for React applications. Install via npm.
+
+Both share the same visual design, [CSS theming](#css-custom-properties), and Contensis RAG API integration.
+
+## Table of Contents
+
+- [Web Component](#web-component)
+  - [Setup](#setup)
+  - [Contensis CMS (Razor)](#contensis-cms--razor)
+  - [Attributes](#attributes)
+  - [Slots](#slots)
+  - [Child Elements](#child-elements)
+  - [JavaScript API](#javascript-api)
+  - [Dynamic Offsets](#dynamic-offsets)
+- [React Components](#react-components)
+  - [Installation](#installation)
+  - [Quick Start](#quick-start)
+  - [Architecture](#architecture)
+  - [Components](#components)
+  - [Mode Switching](#mode-switching)
+  - [Context Hooks](#context-hooks)
+  - [Styling](#styling)
+  - [Markdown Rendering](#markdown-rendering)
+  - [TypeScript](#typescript)
+- [CSS Custom Properties](#css-custom-properties)
+- [Accessibility](#accessibility)
+- [Browser Support](#browser-support)
 
 ---
 
-## Web Component Setup
+## Web Component
 
 A single script tag adds AI search to any page. No build step, no npm, no framework required.
 
 ### Setup
 
-Add the script to your page, then use the `<insytful-search>` element:
-
 ```html
-<script src="https://unpkg.com/insytful-ai-search-components/dist/insytful-search.js"></script>
+<script src="https://unpkg.com/insytful-ai-search-components@2.1.2/dist/insytful-search.js"></script>
 
 <insytful-search
   api-uri="https://your-api.com"
@@ -29,20 +51,20 @@ Add the script to your page, then use the `<insytful-search>` element:
   <span slot="description">Ask a question in your own words</span>
   <span slot="disclaimer">AI responses may not always be accurate.</span>
 
+  <insytful-close></insytful-close>
   <insytful-suggestion>How do I get started?</insytful-suggestion>
   <insytful-suggestion>What courses do you offer?</insytful-suggestion>
 </insytful-search>
 ```
 
-### Contensis CMS (C# / Razor)
+### Contensis CMS / Razor
 
 For classic Contensis sites using the .NET framework, add the Web Component to your layout or view:
 
 ```cshtml
 @{
-    // Brand the modal — vars are documented under "CSS Custom Properties" below.
     const string InsytfulAISearchTheme = @"
-        :host {
+        .insytful-root {
           --insytful-font-family: 'Helvetica Neue', Arial, sans-serif;
           --insytful-btn-prompt-bg-default: #f2f2f2;
           --insytful-btn-prompt-bg-hover: #e5e5e5;
@@ -52,11 +74,9 @@ For classic Contensis sites using the .NET framework, add the Web Component to y
     ";
 }
 
-<!-- Insytful AI Search Web Component -->
-<script src="https://unpkg.com/insytful-ai-search-components@2.1.0/dist/insytful-search.js"></script>
+<script src="https://unpkg.com/insytful-ai-search-components@2.1.2/dist/insytful-search.js"></script>
 
 <style>
-  /* Prevent flash of unstyled content before the script loads */
   insytful-search:not(:defined) { display: none; }
 </style>
 
@@ -66,16 +86,14 @@ For classic Contensis sites using the .NET framework, add the Web Component to y
   suggestions-position="below"
   theme="@InsytfulAISearchTheme"
 >
-  <button slot="trigger" class="search-trigger">Search this site</button>
+  <button slot="trigger">Search this site</button>
   <span slot="title">Ask our AI</span>
   <span slot="description">Get instant answers about our courses and services</span>
   <span slot="disclaimer">AI responses may not always be accurate. Please verify important information.</span>
 
-  <!-- Built-in close button (top-right). Empty content uses the default ✕ icon. -->
   <insytful-close></insytful-close>
 
-  <!-- Avatar shown next to AI responses -->
-  <img slot="avatar" src="/_design/img/logo-icon.png" alt="" width="32" height="32" style="width:100%;height:100%;object-fit:contain;" />
+  <img slot="avatar" src="/logo.png" alt="" width="32" height="32" />
 
   <insytful-suggestion>How do I apply?</insytful-suggestion>
   <insytful-suggestion>What courses do you offer?</insytful-suggestion>
@@ -86,75 +104,21 @@ For classic Contensis sites using the .NET framework, add the Web Component to y
 </insytful-search>
 ```
 
-To integrate with an existing search form (e.g. a dropdown with search types), you can open the AI search dialog programmatically when the user selects "AI Search":
-
-```cshtml
-<div class="sys_textBoxWithRedirect">
-  <input type="text" name="search" aria-label="Search" placeholder="Search..." id="search" />
-  <select id="searchType" name="searchType" aria-label="Select a type of search">
-    <option value="courses">Courses</option>
-    <option value="all">Whole site</option>
-    <option value="ai">AI Search</option>
-  </select>
-  <input type="image" id="topSearchButton" alt="Search" src="/_design/img/search-button-50px-2017.png" />
-</div>
-
-<!-- AI search component (trigger hidden — opened programmatically) -->
-<insytful-search
-  id="ai-search"
-  api-uri="CurrentContext.Site.AI.Endpoint"
-  project-id="CurrentContext.Site.AI.ProjectId"
-  suggestions-position="below"
->
-  <span slot="title">Ask our AI</span>
-  <span slot="description">Get instant answers about our courses and services</span>
-  <span slot="disclaimer">AI responses may not always be accurate.</span>
-
-  <!-- Built-in close button — focus-trap-aware, no light-DOM hacks needed -->
-  <insytful-close></insytful-close>
-
-  <!-- Avatar next to AI responses -->
-  <img slot="avatar" src="/_design/img/logo-icon.png" alt="" width="32" height="32" style="width:100%;height:100%;object-fit:contain;" />
+To open the dialog programmatically from your own search form:
 
-  <insytful-suggestion>How do I apply?</insytful-suggestion>
-  <insytful-suggestion>What courses do you offer?</insytful-suggestion>
-</insytful-search>
-
-<script src="https://unpkg.com/insytful-ai-search-components@2.1.0/dist/insytful-search.js"></script>
-```
-
-```cshtml
-@{
-    string custom = @"
-    (function($) {
-        $(function() {
-            var element = document.getElementById('ai-search');
-
-            $('#search').keypress(function(e) {
-                if (e.which == 13) {
-                    e.preventDefault();
-                    $('#btn').trigger('click');
-                }
-            });
-
-            $('#btn').on('click', function(e) {
-                e.preventDefault();
-                var type = $('#type :selected').val();
-                var query = $('#search')
-                    .val()
-                    .replace(/[^0-9a-z\s]/gi, '')
-                    .replace(/\s+/gi, '+');
-
-                if (type === 'ai') element.open();
-            });
-        });
-    })(jQuery);
-    ";
-    CurrentContext.Page.Scripts.AddInline(custom, ScriptLocation.BodyEnd);
-}
+```javascript
+const element = document.getElementById('ai-search');
+const input = document.getElementById('search');
+
+input.addEventListener('keydown', (e) => {
+  if (e.key === 'Enter') {
+    e.preventDefault();
+    element.open(input.value.trim());
+  }
+});
 ```
 
-### Web Component Attributes
+### Attributes
 
 | Attribute | Required | Description |
 |-----------|----------|-------------|
@@ -162,8 +126,8 @@ To integrate with an existing search form (e.g. a dropdown with search types), y
 | `project-id` | Yes | Project identifier for the RAG API |
 | `sections` | No | Comma-separated section slugs to scope results |
 | `dev-mode` | No | Enable mock responses for development (no backend needed) |
-| `theme` | No | Custom CSS string injected into the Shadow DOM |
-| `suggestions-position` | No | `"above"` (default) or `"below"` — position of the suggestion chips relative to the input field |
+| `theme` | No | Custom CSS string injected into the Shadow DOM (use `.insytful-root` to set [CSS custom properties](#css-custom-properties)) |
+| `suggestions-position` | No | `"above"` (default) or `"below"` — position of suggestion chips relative to the input field |
 
 ### Slots
 
@@ -173,7 +137,7 @@ To integrate with an existing search form (e.g. a dropdown with search types), y
 | `title` | Heading text for the empty state |
 | `description` | Subheading text below the title |
 | `disclaimer` | Footer text (e.g. AI accuracy warning) |
-| `logo` | Logo image shown in the dialog empty state |
+| `logo` | Image shown in the dialog empty state (not in messages) |
 | `avatar` | Image shown next to AI responses and the typing indicator |
 
 ### Child Elements
@@ -182,8 +146,8 @@ To integrate with an existing search form (e.g. a dropdown with search types), y
 <!-- Suggestion chips (shown before the first query) -->
 <insytful-suggestion>How do I apply?</insytful-suggestion>
 
-<!-- Close button (renders a top-right ✕ inside the dialog).
-     Empty content uses the default ✕ icon; or pass your own markup. -->
+<!-- Close button (top-right inside the dialog).
+     Empty content uses the default X icon; or pass your own markup. -->
 <insytful-close></insytful-close>
 <insytful-close aria-label="Dismiss search">Cancel</insytful-close>
 
@@ -195,9 +159,9 @@ To integrate with an existing search form (e.g. a dropdown with search types), y
 <insytful-mode name="classic" path="/search?q=">Classic Search</insytful-mode>
 ```
 
-The close button lives **inside the dialog** (so the focus trap includes it) and is styled via the `--insytful-btn-close-*` CSS variables.
+The **close button** lives inside the dialog (focus-trap-aware) and is styled via `--insytful-btn-close-*` variables.
 
-The avatar appears next to each AI response and the typing indicator. On desktop it sits as a column beside the message; on mobile it floats left so the first line of text wraps beside it and subsequent content flows full width. Style the wrapper via `.insytful-search-message-logo` in your theme CSS. This is the Web Component equivalent of the React `logo` prop on `Root`.
+The **avatar** appears next to each AI response and the typing indicator. On desktop it sits as a column beside the message; on mobile it floats left so the first line of text wraps beside it and subsequent content flows full width. Style the wrapper via `.insytful-search-message-logo` in your theme CSS. This is the Web Component equivalent of the React `logo` prop on `Root`.
 
 ### JavaScript API
 
@@ -205,7 +169,8 @@ The avatar appears next to each AI response and the typing indicator. On desktop
 const element = document.querySelector('insytful-search');
 
 // Open/close programmatically
-element.open();
+element.open();          // open the empty dialog
+element.open('query');   // open and immediately send a query
 element.close();
 element.toggle();
 
@@ -232,9 +197,11 @@ If your site has a sticky header, add `data-insytful-modal-offset` so the dialog
 <header data-insytful-modal-offset>Your sticky header</header>
 ```
 
+The modal measures their combined height via `ResizeObserver` and adjusts its `top` offset.
+
 ---
 
-## React Setup
+## React Components
 
 Radix-style compound components for React applications.
 
@@ -281,16 +248,16 @@ function App() {
 ### Architecture
 
 ```
-InsytfulSearch.Root          — Context provider (lives in your DOM tree)
-├── InsytfulSearch.Trigger   — Toggle button (place anywhere in your DOM)
-└── InsytfulSearch.Portal    — Shadow DOM dialog (portalled to document.body)
-    ├── InsytfulSearch.Close — Close button (top-right; optional)
-    ├── InsytfulSearch.Title
-    ├── InsytfulSearch.Description
-    ├── InsytfulSearch.Input
-    ├── InsytfulSearch.Messages
-    ├── InsytfulSearch.Suggestions
-    └── InsytfulSearch.Disclaimer
+InsytfulSearch.Root          -- Context provider (lives in your DOM tree)
++-- InsytfulSearch.Trigger   -- Toggle button (place anywhere in your DOM)
++-- InsytfulSearch.Portal    -- Shadow DOM dialog (portalled to document.body)
+    +-- InsytfulSearch.Close -- Close button (top-right; optional)
+    +-- InsytfulSearch.Title
+    +-- InsytfulSearch.Description
+    +-- InsytfulSearch.Input
+    +-- InsytfulSearch.Messages
+    +-- InsytfulSearch.Suggestions
+    +-- InsytfulSearch.Disclaimer
 ```
 
 `Root` lives in the consumer's DOM so components like `Trigger` can be placed anywhere (e.g. in a site header). `Portal` creates the Shadow DOM boundary for the modal dialog.
@@ -355,7 +322,7 @@ Toggles the modal. Renders a `<button>` by default, or merges props onto your ch
 
 #### `InsytfulSearch.Close`
 
-Closes the modal. Place inside `InsytfulSearch.Portal` so the focus trap includes it. Renders a top-right ✕ button styled via `--insytful-btn-close-*` tokens; pass children to override the icon, or `asChild` to merge props onto your own element.
+Closes the modal. Place inside `InsytfulSearch.Portal` so the focus trap includes it. Renders a top-right X button styled via `--insytful-btn-close-*` tokens; pass children to override the icon, or `asChild` to merge props onto your own element.
 
 ```tsx
 <InsytfulSearch.Portal>
@@ -368,7 +335,7 @@ Closes the modal. Place inside `InsytfulSearch.Portal` so the focus trap include
 
   {/* Or your own button element */}
   <InsytfulSearch.Close asChild>
-    <button className="my-close-btn" aria-label="Dismiss">×</button>
+    <button aria-label="Dismiss">x</button>
   </InsytfulSearch.Close>
 </InsytfulSearch.Portal>
 ```
@@ -418,6 +385,24 @@ Displays the AI conversation thread with auto-scroll, typing indicator, gradient
 <InsytfulSearch.Messages className="px-4" />
 ```
 
+#### `InsytfulSearch.ErrorCallout`
+
+Renders an error callout when the AI search fails. Place it conditionally based on the `error` state from `useSearchContext`. Optionally includes a "Try classic?" button to switch modes.
+
+```tsx
+const { error } = InsytfulSearch.useSearchContext('MyComponent');
+
+{error && <InsytfulSearch.ErrorCallout />}
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `onSwitchClassic` | `() => void` | Optional callback to switch to classic search mode. When provided, renders a "Try classic?" button. |
+
+Styled via `--insytful-callout-error-border`, `--insytful-callout-error-bg`, and `--insytful-callout-error-text` CSS variables.
+
+> **Web Component:** The error callout is built-in and renders automatically when the RAG API fails. The "Try classic?" button appears when a classic mode with a `path` is configured. No consumer code needed.
+
 #### `InsytfulSearch.Suggestions`
 
 Clickable suggestion chips. Clicking sends the suggestion text via context `onSend`.
@@ -452,14 +437,10 @@ Switch between AI search and classic (URL-based) search:
   <InsytfulSearch.Modes defaultValue="ai">
     <InsytfulSearch.ModeSwitch>
       {({ mode, onSwitch }) => (
-        <div className="tabs">
-          <button onClick={() => onSwitch('ai')} className={mode === 'ai' ? 'active' : ''}>
-            AI Search
-          </button>
-          <button onClick={() => onSwitch('classic')} className={mode === 'classic' ? 'active' : ''}>
-            Classic Search
-          </button>
-        </div>
+        <>
+          <button onClick={() => onSwitch('ai')}>AI Search</button>
+          <button onClick={() => onSwitch('classic')}>Classic Search</button>
+        </>
       )}
     </InsytfulSearch.ModeSwitch>
 
@@ -516,13 +497,13 @@ For advanced usage, the library exports context hooks:
 ```tsx
 import { InsytfulSearch } from 'insytful-ai-search-components';
 
-// Inside a Search.Root descendant — throws if used outside Root
+// Inside a Search.Root descendant -- throws if used outside Root
 const { messages, loading, onSend, open } = InsytfulSearch.useSearchContext('MyComponent');
 
-// Inside a Search.Modes descendant — throws if used outside Modes
+// Inside a Search.Modes descendant -- throws if used outside Modes
 const { mode, onSwitchMode } = InsytfulSearch.useModeContext('MyComponent');
 
-// Safe variant — returns null if not inside Search.Modes
+// Safe variant -- returns null if not inside Search.Modes
 const modeCtx = InsytfulSearch.useModeContextSafe();
 ```
 
@@ -538,72 +519,9 @@ import theme from './my-theme.css?inline';
 <InsytfulSearch.Root theme={theme} options={...}>
 ```
 
-> **Security note:** The `theme` prop injects raw CSS into the Shadow DOM. Only pass trusted, developer-authored CSS — never user-generated content.
-
-#### CSS Custom Properties
+> **Security note:** The `theme` prop injects raw CSS into the Shadow DOM. Only pass trusted, developer-authored CSS -- never user-generated content.
 
-Override these variables in your theme CSS to change colours:
-
-```css
-:host {
-  /* Typography */
-  --insytful-font-family: system-ui, -apple-system, sans-serif;
-
-  /* Text */
-  --insytful-text-default: #333333;
-  --insytful-text-muted: #6c6c6c;
-  --insytful-text-link-default: #1d70b8;
-  --insytful-text-link-hover: #184b76;
-  --insytful-typing-indicator-text: var(--insytful-text-muted);
-  --insytful-disclaimer-text: var(--insytful-text-muted);
-
-  /* Brand */
-  --insytful-brand-primary: #195491;
-
-  /* Modal surface */
-  --insytful-modal-bg: #ffffff;
-  --insytful-modal-max-width: 784px;
-  --insytful-modal-radius: 0px;
-
-  /* Suggestion buttons */
-  --insytful-btn-prompt-bg-default: #e2eefa;
-  --insytful-btn-prompt-bg-hover: #c8daec;
-  --insytful-btn-prompt-text: #333333;
-  --insytful-btn-prompt-radius: 12px;
-  --insytful-btn-prompt-focus: var(--insytful-semantic-search-field-focus);
-
-  /* Input card */
-  --insytful-input-card-bg: #ffffff;
-  --insytful-input-card-radius: 16px;
-  --insytful-input-card-border: var(--insytful-semantic-search-field-stroke);
-  --insytful-input-card-border-width: 1px;
-
-  /* Send button */
-  --insytful-btn-icon-search-bg-default: #2e3339;
-  --insytful-btn-icon-search-bg-hover: #3c444d;
-  --insytful-btn-icon-search-icon: #ffffff;
-
-  /* Close button */
-  --insytful-btn-close-bg: transparent;
-  --insytful-btn-close-bg-hover: #f2f2f2;
-  --insytful-btn-close-icon: var(--insytful-text-default);
-  --insytful-btn-close-size: 40px;
-
-  /* Error callout */
-  --insytful-callout-error-border: #d93025;
-  --insytful-callout-error-bg: #fce8e6;
-
-  /* Search field */
-  --insytful-semantic-search-field-stroke: #333333;
-  --insytful-semantic-search-field-focus: #35d2c5;
-
-  /* Transitions */
-  --insytful-search-transition-duration: 200ms;
-
-  /* Z-index */
-  --insytful-z-index: 999;
-}
-```
+See [CSS Custom Properties](#css-custom-properties) for the full list of theming tokens.
 
 #### Dynamic Offsets
 
@@ -628,7 +546,7 @@ import ReactMarkdown from 'react-markdown';
 >
 ```
 
-> **Security note:** Your `renderMarkdown` implementation must sanitize output. AI responses are untrusted content — do not use `dangerouslySetInnerHTML` or enable raw HTML passthrough. Libraries like `react-markdown` are safe by default.
+> **Security note:** Your `renderMarkdown` implementation must sanitize output. AI responses are untrusted content -- do not use `dangerouslySetInnerHTML` or enable raw HTML passthrough. Libraries like `react-markdown` are safe by default.
 
 ### TypeScript
 
@@ -645,6 +563,71 @@ import type {
 } from 'insytful-ai-search-components';
 ```
 
+---
+
+## CSS Custom Properties
+
+Both versions support the same theme variables. For the Web Component, set these on `.insytful-root` inside your `theme` attribute. For React, set them on `:host` inside your `theme` prop.
+
+```css
+/* Typography */
+--insytful-font-family: system-ui, -apple-system, sans-serif;
+
+/* Text */
+--insytful-text-default: #333333;
+--insytful-text-muted: #6c6c6c;
+--insytful-text-link-default: #1d70b8;
+--insytful-text-link-hover: #184b76;
+--insytful-typing-indicator-text: var(--insytful-text-muted);
+--insytful-disclaimer-text: var(--insytful-text-muted);
+
+/* Brand */
+--insytful-brand-primary: #195491;
+
+/* Modal surface */
+--insytful-modal-bg: #ffffff;
+--insytful-modal-max-width: 784px;
+--insytful-modal-radius: 0px;
+
+/* Suggestion buttons */
+--insytful-btn-prompt-bg-default: #e2eefa;
+--insytful-btn-prompt-bg-hover: #c8daec;
+--insytful-btn-prompt-text: #333333;
+--insytful-btn-prompt-radius: 12px;
+--insytful-btn-prompt-focus: var(--insytful-semantic-search-field-focus);
+
+/* Input card */
+--insytful-input-card-bg: #ffffff;
+--insytful-input-card-radius: 16px;
+--insytful-input-card-border: var(--insytful-semantic-search-field-stroke);
+--insytful-input-card-border-width: 1px;
+
+/* Send button */
+--insytful-btn-icon-search-bg-default: #2e3339;
+--insytful-btn-icon-search-bg-hover: #3c444d;
+--insytful-btn-icon-search-icon: #ffffff;
+
+/* Close button */
+--insytful-btn-close-bg: transparent;
+--insytful-btn-close-bg-hover: #f2f2f2;
+--insytful-btn-close-icon: var(--insytful-text-default);
+--insytful-btn-close-size: 40px;
+
+/* Error callout */
+--insytful-callout-error-border: #d93025;
+--insytful-callout-error-bg: #fce8e6;
+
+/* Search field */
+--insytful-semantic-search-field-stroke: #333333;
+--insytful-semantic-search-field-focus: #35d2c5;
+
+/* Transitions */
+--insytful-search-transition-duration: 200ms;
+
+/* Z-index */
+--insytful-z-index: 999;
+```
+
 ## Accessibility
 
 Both the React and Web Component versions share the same accessibility features:
@@ -656,36 +639,6 @@ Both the React and Web Component versions share the same accessibility features:
 - `inert` attribute hides the dialog from assistive tech when closed
 - Respects `prefers-reduced-motion` (transitions disabled)
 
-## CSS Custom Properties
-
-Both versions support the same theme variables. Override them in your custom CSS:
-
-```css
-:host {
-  --insytful-font-family: system-ui, -apple-system, sans-serif;
-  --insytful-text-default: #333333;
-  --insytful-text-muted: #6c6c6c;
-  --insytful-disclaimer-text: var(--insytful-text-muted);
-  --insytful-typing-indicator-text: var(--insytful-text-muted);
-  --insytful-brand-primary: #195491;
-  --insytful-modal-bg: #ffffff;
-  --insytful-modal-max-width: 784px;
-  --insytful-btn-prompt-bg-default: #e2eefa;
-  --insytful-btn-prompt-radius: 12px;
-  --insytful-input-card-bg: #ffffff;
-  --insytful-input-card-radius: 16px;
-  --insytful-input-card-border: var(--insytful-semantic-search-field-stroke);
-  --insytful-btn-icon-search-bg-default: #2e3339;
-  --insytful-btn-close-bg-hover: #f2f2f2;
-  --insytful-btn-close-icon: var(--insytful-text-default);
-  --insytful-semantic-search-field-focus: #35d2c5;
-  --insytful-search-transition-duration: 200ms;
-  --insytful-z-index: 999;
-}
-```
-
-See the [full CSS Custom Properties](#css-custom-properties) section above for the complete token list with defaults.
-
 ## Browser Support
 
 Modern browsers with [Shadow DOM v1](https://caniuse.com/shadowdomv1). Client-side rendering only (no SSR).