Merge pull request #83 from Renumics/feature/docu-new-api

Feat: New API (onAction) Documentation
Renumics · Mar 6, 2025 · ea3f6e9 · ea3f6e9
2 parents 9b4abc7 + 5d2fa08
commit ea3f6e9
Show file tree

Hide file tree

Showing 51 changed files with 3,447 additions and 3,260 deletions.
diff --git a/README.md b/README.md
@@ -1,28 +1,27 @@
-<p align="center"><a href="https://renumics.com/lexio-ui"><img src="lexio/src/stories/assets/lexio logo transparent.png" alt="Gray shape shifter" height="60"/></a></p>
+<p align="center"><a href="https://renumics.com/lexio-ui"><img src="lexio/src/stories/assets/lexio logo transparent.png" alt="Gray shape shifter" height="80"/></a></p>
 
 <p align="center">Quickest way to production grade RAG UI. </p>
 
 <p align="center">
-	<a href="https://github.com/Renumics/lexio/blob/main/LICENSE"><img src="https://img.shields.io/github/license/renumics/lexio" height="20"/></a>
-    <a href="README.md"><img src="https://img.shields.io/github/actions/workflow/status/Renumics/lexio/check.yml" height="20"/></a>
-    <a href="https://www.npmjs.com/package/lexio"><img src="https://img.shields.io/npm/v/lexio" height="20"/></a>
-    <a href="https://pypi.org/project/lexio/"><img src="https://img.shields.io/pypi/v/lexio" height="20"/></a>
+<a href="https://github.com/Renumics/lexio/blob/main/LICENSE"><img src="https://img.shields.io/github/license/renumics/lexio" height="20"/></a>
+  <a href="README.md"><img src="https://img.shields.io/github/actions/workflow/status/Renumics/lexio/check.yml" height="20"/></a>
+  <a href="https://www.npmjs.com/package/lexio"><img src="https://img.shields.io/npm/v/lexio" height="20"/></a>
+  <a href="https://pypi.org/project/lexio/"><img src="https://img.shields.io/pypi/v/lexio" height="20"/></a>
 </p>
 
 <h3 align="center">
-   <a href="https://renumics.com/lexio-ui"><b>Documentation</b></a> &bull;
-   <a href="https://renumics.com/blog/"><b>Blog</b></a>
- </h3>
+<a href="https://renumics.com/lexio-ui"><b>Documentation</b></a> &bull;
+<a href="https://renumics.com/blog/"><b>Blog</b></a>
+</h3>
 
-Lexio is a robust React library for Retrieval-Augmented Generation (RAG) document QA interfaces, handling complex workflows out of the box while remaining simple to use. 
+Lexio is a powerful React library for building Retrieval-Augmented Generation (RAG) interfaces, handling complex workflows out of the box while remaining simple to use and highly customizable.
 
-It supports multiple document types (PDF, HTML, Markdown) with advanced features like streaming responses and source highlighting. 
+It supports multiple document types (PDF, HTML, Markdown, Text) with advanced features like streaming responses, source highlighting, and a comprehensive state management system.
 
-Developers can use ready-made components or easily build custom ones using React hooks.
+Developers can use ready-made components or easily build custom ones using React hooks and the flexible action handler pattern.
 
 ![RAG UI Example](lexio/src/stories/assets/shot_lexio_llama_index.png)
 
-
 ## Quick Start
 
 You can install the library with npm or yarn:
@@ -31,63 +30,191 @@ You can install the library with npm or yarn:
 npm install lexio
 ```
 
-To use the GUI components, you need to provide retrieval and generation functions to the `RAGProvider` context:
+To use the GUI components, you need to provide an action handler to the `LexioProvider` context:
 
 ```tsx
-import { RAGProvider, ChatWindow, AdvancedQueryField, SourcesDisplay, ContentDisplay, ErrorDisplay } from 'lexio';
+import { 
+  LexioProvider, 
+  ChatWindow, 
+  AdvancedQueryField, 
+  SourcesDisplay, 
+  ContentDisplay, 
+  ErrorDisplay 
+} from 'lexio';
 
 const App = () => (
-<RAGProvider
-  retrieveAndGenerate={(messages) => {
-    return {
-      sources: Promise.resolve([
-        {
-          source: "example-doc.pdf",
-        },
-          relevanceScore: 0.95
-        }
-      ]),
-      response: Promise.resolve("This is a sample response based on the retrieved documents.")
-    };
-  }}
->
-  <ChatWindow />
-  <AdvancedQueryField />
-  <SourcesDisplay />
-  <ContentDisplay />
-  <ErrorDisplay />
-</RAGProvider>
+  <LexioProvider
+    onAction={(action, messages, sources, activeSources, selectedSource) => {
+      // Handle user messages
+      if (action.type === 'ADD_USER_MESSAGE') {
+        return {
+          // Return sources as a Promise that resolves to Source[]
+          sources: Promise.resolve([
+            {
+              title: "Example Document",
+              type: "pdf",
+              relevance: 0.95,
+              metadata: {
+                author: "Documentation Team",
+                page: 3
+              }
+            }
+          ]),
+          // Return a response as a Promise or use streaming
+          response: Promise.resolve("This is a sample response based on the retrieved documents.")
+        };
+      }
+
+      // Handle source selection
+      if (action.type === 'SET_SELECTED_SOURCE' && action.sourceObject) {
+        return {
+          sourceData: fetchSourceContent(action.sourceObject.id)
+        };
+      }
+
+      return undefined;
+    }}
+    config={{
+      timeouts: {
+        request: 30000,  // 30 seconds for entire operations
+        stream: 5000     // 5 seconds between stream chunks
+      }
+    }}
+  >
+    <div className="flex flex-col h-screen">
+      <div className="flex-1">
+        <ChatWindow markdown={true} />
+      </div>
+      <div>
+        <AdvancedQueryField />
+      </div>
+      <div className="flex">
+        <SourcesDisplay />
+        <ContentDisplay />
+      </div>
+    </div>
+    <ErrorDisplay />
+  </LexioProvider>
 );
 ```
-Follow the Tutorial to learn more about the library.
+
+Follow the [documentation](https://renumics.com/lexio/) to learn more about the library.
+
+## Core Concepts
+
+### 🔄 LexioProvider
+
+The [LexioProvider](lexio%2Flib%2Fcomponents%2FLexioProvider%2Fprovider.tsx) is the core component that provides the context for all Lexio UI components:
+- It manages the shared state for all UI components
+- It processes user actions through the `onAction` ActionHandler
+- It handles error states and loading indicators
+- It provides configuration options for timeouts and other settings
+
+### 🧩 UI Components 
+
+Lexio provides several ready-to-use UI components:
+
+- **[ChatWindow](lexio%2Flib%2Fcomponents%2FChatWindow%2FChatWindow.tsx)**: 💬 Displays the conversation history and AI responses with markdown support
+- **[AdvancedQueryField](lexio%2Flib%2Fcomponents%2FAdvancedQueryField%2FAdvancedQueryField.tsx)**: 📝 Input field for user messages with optional advanced features
+- **[SourcesDisplay](lexio%2Flib%2Fcomponents%2FSourcesDisplay%2FSourcesDisplay.tsx)**: 📚 Shows retrieved sources with metadata and selection capabilities
+- **[ContentDisplay](lexio%2Flib%2Fcomponents%2FContentDisplay%2FContentDisplay.tsx)**: 📄 Renders the content of selected sources with highlighting
+- **[ErrorDisplay](lexio%2Flib%2Fcomponents%2FErrorDisplay%2FErrorDisplay.tsx)**: ❗ Shows error messages and loading states
+
+### 🔗 React Hooks
+
+Lexio provides a set of React hooks that allow you to interact with the state and trigger actions from your custom components:
+
+- **[useSources](lexio%2Flib%2Fhooks%2Fhooks.ts)**: 📊 Access and manipulate source-related state
+- **[useMessages](lexio%2Flib%2Fhooks%2Fhooks.ts)**: 💌 Access and manipulate message-related state
+- **[useStatus](lexio%2Flib%2Fhooks%2Fhooks.ts)**: ⏳ Access loading and error states
 
 ## Key Features
-- **Powerful Viewers**: Pre-built components for chat interfaces, source selection and viewing with source highlighting
-- **Integrated State Management**: Transparent state handling for interaction between components
-- **Opinionated Architecture**: Implements RAG best practices out of the box
-- **Highly Customizable**: Theming and component customization options through ...
+
+<div align="center">
+  <div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 20px; margin: 20px 0; color: #000;">
+    <div style="background-color: #f5f5f5; border-radius: 8px; padding: 15px; border-left: 4px solid #3498db;">
+      <h3>🔄 Action Handler Pattern</h3>
+      <p style="color: #000;">A flexible pattern for handling user interactions and state updates</p>
+    </div>
+    <div style="background-color: #f5f5f5; border-radius: 8px; padding: 15px; border-left: 4px solid #3498db;">
+      <h3>🧩 Powerful Components</h3>
+      <p style="color: #000;">Pre-built components for chat interfaces, source selection, and document viewing with highlighting</p>
+    </div>
+    <div style="background-color: #f5f5f5; border-radius: 8px; padding: 15px; border-left: 4px solid #3498db;">
+      <h3>⚙️ Integrated State Management</h3>
+      <p style="color: #000;">Transparent state handling for seamless interaction between components</p>
+    </div>
+    <div style="background-color: #f5f5f5; border-radius: 8px; padding: 15px; border-left: 4px solid #3498db;">
+      <h3>🌊 Streaming Responses</h3>
+      <p style="color: #000;">Support for real-time, incremental responses with source updates</p>
+    </div>
+    <div style="background-color: #f5f5f5; border-radius: 8px; padding: 15px; border-left: 4px solid #3498db;">
+      <h3>🛡️ Comprehensive Error Handling</h3>
+      <p style="color: #000;">Built-in error handling and timeout management</p>
+    </div>
+    <div style="background-color: #f5f5f5; border-radius: 8px; padding: 15px; border-left: 4px solid #3498db;">
+      <h3>🎨 Highly Customizable</h3>
+      <p style="color: #000;">Theming and component customization options</p>
+    </div>
+  </div>
+</div>
 
 ## Advantages
-- **Quick Implementation**: Get your RAG interface running with just a few lines of code
-- **Production Ready**: Built for integration into mature web applications
-- **Best Practices Built-in**: Follows RAG implementation patterns from real-world applications
-- **Framework Agnostic**: Works with any backend RAG implementation
+
+<div align="center">
+  <div style="display: grid; grid-template-columns: repeat(2, 1fr); gap: 20px; margin: 20px 0; color: #000;">
+    <div style="background-color: #f5f5f5; border-radius: 8px; padding: 15px; border-left: 4px solid #2ecc71;">
+      <h3>⚡ Quick Implementation</h3>
+      <p style="color: #000;">Get your RAG interface running with just a few lines of code</p>
+    </div>
+    <div style="background-color: #f5f5f5; border-radius: 8px; padding: 15px; border-left: 4px solid #2ecc71;">
+      <h3>🚀 Production Ready</h3>
+      <p style="color: #000;">Built for integration into mature web applications</p>
+    </div>
+    <div style="background-color: #f5f5f5; border-radius: 8px; padding: 15px; border-left: 4px solid #2ecc71;">
+      <h3>📚 Best Practices Built-in</h3>
+      <p style="color: #000;">Follows RAG implementation patterns from real-world applications</p>
+    </div>
+    <div style="background-color: #f5f5f5; border-radius: 8px; padding: 15px; border-left: 4px solid #2ecc71;">
+      <h3>🔌 Framework Agnostic</h3>
+      <p style="color: #000;">Works with any backend RAG implementation</p>
+    </div>
+  </div>
+  <div style="background-color: #f5f5f5; border-radius: 8px; padding: 15px; border-left: 4px solid #2ecc71; max-width: 500px; margin: 0 auto; color: #000;">
+    <h3>🧩 Flexible Architecture</h3>
+    <p style="color: #000;">Adapt to various use cases from simple chat to complex document analysis</p>
+  </div>
+</div>
 
 ## Target Groups
 
-### 🚀 Startups
-- Rapid prototyping capabilities
-- Quick time-to-market
-- Flexible customization options
-
-### 🌐 Enterprise
-- Enterprise-grade reliability
-- Seamless integration with existing systems
-- Production-ready components
-- Professional support options
-
-### 👨‍💻 AI Developers
-- Full control over RAG pipeline
-- Custom component development
-- Advanced configuration options
-- Direct access to underlying state
+<div align="center">
+  <div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 20px; margin: 20px 0; color: #000;">
+    <div style="background-color: #f5f5f5; border-radius: 8px; padding: 15px; border-left: 4px solid #e74c3c;">
+      <h3>🚀 Startups</h3>
+      <ul>
+        <li style="color: #000;">Rapid prototyping capabilities</li>
+        <li style="color: #000;">Quick time-to-market</li>
+        <li style="color: #000;">Flexible customization options</li>
+      </ul>
+    </div>
+    <div style="background-color: #f5f5f5; border-radius: 8px; padding: 15px; border-left: 4px solid #e74c3c;">
+      <h3>🌐 Enterprise</h3>
+      <ul>
+        <li style="color: #000;">Enterprise-grade reliability</li>
+        <li style="color: #000;">Seamless integration with existing systems</li>
+        <li style="color: #000;">Production-ready components</li>
+        <li style="color: #000;">Professional support options</li>
+      </ul>
+    </div>
+    <div style="background-color: #f5f5f5; border-radius: 8px; padding: 15px; border-left: 4px solid #e74c3c;">
+      <h3>👨‍💻 AI Developers</h3>
+      <ul>
+        <li style="color: #000;">Full control over RAG pipeline</li>
+        <li style="color: #000;">Custom component development</li>
+        <li style="color: #000;">Advanced configuration options</li>
+        <li style="color: #000;">Direct access to underlying state</li>
+      </ul>
+    </div>
+  </div>
+</div>
diff --git a/TODOS.md b/TODOS.md
diff --git a/lexio/.gitignore b/lexio/.gitignore
@@ -33,3 +33,5 @@ dist-ssr
 
 # ignore auto generated file
 scripts/types.json
+
+storybook-static
diff --git a/lexio/.storybook/preview.tsx b/lexio/.storybook/preview.tsx
@@ -14,7 +14,7 @@ const preview: Preview = {
     },
     options: {
       storySort: {
-        order: ['Welcome', 'Concepts', 'Components', "*", "Gallery"],
+        order: ['Welcome', 'Concepts', "Basic Usage", "Additional Features", "Components", "*", "Gallery"],
       },
     },
     docs: {

diff --git a/lexio/lib/components/AdvancedQueryField/AdvancedQueryField.tsx b/lexio/lib/components/AdvancedQueryField/AdvancedQueryField.tsx
@@ -175,25 +175,35 @@ interface AdvancedQueryFieldProps {
 }
 
 /**
- * An advanced query input component with source mention capabilities
+ * A rich text editor component that allows users to mention and reference sources within their queries.
+ * 
+ * The AdvancedQueryField provides a more sophisticated input experience than the standard QueryField,
+ * with support for source mentions that appear as interactive chips within the text.
+ * 
+ * @component
  * 
  * Features:
- * - Rich text editing with source mentions
- * - Auto-expanding editor
- * - Source filtering and selection
- * - Visual workflow status indicator
+ * - Source mentions with @ symbol trigger
+ * - Interactive source chips that can be deleted
+ * - Keyboard navigation between source chips
  * - Customizable styling
  * - Responsive design
- *
+ * 
  * @example
- *
+ * 
  * ```tsx
  * <AdvancedQueryField
- *   onSubmit={(message, mentions) => {
- *     console.log('Message:', message);
- *     console.log('Mentioned sources:', mentions);
- *   }}
+ *   componentKey="my-query-field"
+ *   onSubmit={(text, sources) => console.log(text, sources)}
+ *   onSourceAdded={(source) => console.log('Source added:', source)}
+ *   onSourceDeleted={(source) => console.log('Source deleted:', source)}
+ *   onChange={(text) => console.log('Text changed:', text)}
  *   placeholder="Type @ to mention a source..."
+ *   styleOverrides={{
+ *     backgroundColor: '#f5f5f5',
+ *     borderRadius: '8px',
+ *     padding: '12px',
+ *   }}
  * />
  * ```
  */
Original file line number	Diff line number	Diff line change
Expand Up		@@ -33,3 +33,5 @@ dist-ssr

		# ignore auto generated file
		scripts/types.json

		storybook-static