@e-llm-studio/requirement-ai 0.0.1

package/README.md

@@ -0,0 +1,2307 @@
+# 📚 e-llm-studio/citation
+
+
+## Table of Contents
+
+1. [Project Overview](#project-overview)
+2. [Installation](#installation)
+3. [Available Components](#available-citations)
+   - [Citation Components](#citation-components)
+      - [BookCitation](#bookcitation) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/BookCitation/README.MD)
+      - [ChatCitation](#chatcitation) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/ChatCitation/ChatCitationReadme.md)
+      - [CitationRenderer](#citationrenderer) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/CitationRenderer/CitationRendererReadme.md)
+      - [CognitiveDecisioningCard](#cognitivedecisioningcard) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/CognitiveDecisioning/CognitiveDecisioningReadme.md)
+      - [CognitiveInternalGPTReasoning](#cognitiveinternalgptreasoning) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/CognitiveInternalgptReasoning/README.md)
+      - [CodeCitation](#codecitation) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/CodeCitation/README.md)
+      - [CitationsViewer](#citationsviewer) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/CitationViewer/CitationViewerReadme.md)
+      - [PdfEditorCitation](#pdfeditorcitation) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/PdfEditorCitation/README.md)
+      - [RequirementAICitation](#requirementaicitation) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/RequirementAiCitations/RequirementAiCitationsReadme.md)
+      - [ScannedDocCitation](#scanneddoccitation) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/ScannedDocCitation/README.md)
+   - [Other Components](#other-components)
+      - [Bookemon](#bookemon) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/Bookemon/BookemonReadme.md)
+      - [DatagestMon](#datagestmon) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/DatagestMon/README.md)
+      - [DataSelector](#dataselector)[<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/DataSelector/DataSelectorReadme.md)
+      - [PaginatedTable](#paginatedtable) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/PaginatedTable/PaginatedTableReadme.md)
+      - [PdfViewer](#pdfviewer) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/PdfViewer/PdfViewerReadme.md)
+      - [ProjectAccordion](#projectaccordion) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/ProjectAccordion/README.md)
+      - [UploadData](#uploaddata) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/UploadData/README.md)
+      - [ReviewPanel](#reviewpanel) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/ReviewPanel/README.md)
+      - [TableCitationContent](#tablecitationcontent) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/TableCitation/README.md)
+4. [Common Use Cases](#common-use-cases)
+5. [Development & Contribution](#development--contribution)
+6. [License](#license)
+
+
+## Project Overview
+
+The @e-llm-studio/citation library is a comprehensive React component library designed to render various types of citations and related UI elements within the e-LLM Studio ecosystem. It provides a robust set of reusable, production-ready components that enable developers to display citations, reasoning chains, code snippets, PDFs, and other content types with rich interactive features and highly customizable styling.
+
+This library serves as a foundational building block for applications that need to present complex information in an organized, user-friendly manner. Whether you're displaying book citations with highlighted passages, rendering AI reasoning with confidence scores, showcasing code with syntax highlighting, or managing large datasets with pagination, the citation library offers flexible, well-documented components that integrate seamlessly into modern React applications.
+
+The library emphasizes developer experience through comprehensive documentation, TypeScript support, and extensive customization options. Each component is designed with accessibility and performance in mind, ensuring that applications built with these components provide excellent user experiences across different devices and use cases.
+
+---
+
+## Installation
+
+### Prerequisites
+
+Before you begin, ensure you have the following installed on your system:
+
+- **Node.js & npm** - Required for package management and running build scripts
+- **Git** - Required for cloning the repository
+- Basic familiarity with Git and the command line
+
+### Installation Steps
+
+#### 1. Clone the Repository
+
+Start by cloning the citation library repository to your local machine:
+
+```bash
+git clone https://github.com/e-llm-studio/citation.git
+
+cd citation
+```
+
+#### 2. Install Dependencies
+
+Install all required dependencies using npm:
+
+```bash
+npm install
+```
+
+Alternatively, you can use yarn if you prefer:
+
+```bash
+yarn install
+```
+
+#### 3. Link the Library Locally (Optional)
+
+If you want to test the library in another project before publishing, you can link it locally:
+
+```bash
+# In the citation library folder
+npm link
+
+# In your test project folder
+cd ../your-project
+npm link @e-llm-studio/citation
+```
+
+This allows you to test changes in your local library without publishing to npm.
+
+#### 4. Build the Library
+
+Build the library to compile TypeScript and prepare distribution files:
+
+```bash
+npm run build
+```
+
+#### 5. Test Locally
+
+After building, you can test the library in your project:
+
+```bash
+# In your test project
+npm start
+# or
+npm run build
+```
+
+Import the library components and verify that your changes work as expected.
+
+### Quick Installation for End Users
+
+If you're installing the published package from npm:
+
+```bash
+# Using npm
+npm install @e-llm-studio/citation
+
+# Using yarn
+yarn add @e-llm-studio/citation
+
+# Using pnpm
+pnpm add @e-llm-studio/citation
+```
+
+---
+
+
+# Citation Components
+## BookCitation
+
+### Overview
+
+The BookCitation component is designed to display book citations with an interactive and expandable interface. It provides a rich, user-friendly way to present quoted text from books with support for highlighting, citation details management, and book cover images. The component enables readers to explore citations in context while maintaining a clean, organized presentation.
+
+### Features
+
+- **Text highlighting with partial and full match support** - Highlights specific text passages within citations using flexible matching algorithms
+- **Automatic cleaning of scanned text to remove artifacts** - Intelligently removes OCR artifacts, page numbers, headers, and footers
+- **Expandable/collapsible view of citation details** - Toggle between collapsed citation button and expanded view
+- **Blur effect for non-highlighted text** - Applies visual blur to non-highlighted portions to focus reader attention
+- **Scroll-to-highlight functionality** - Automatically scrolls to and centers highlighted text when expanded
+- **Support for book cover images and external links** - Displays book cover images and provides clickable external links
+- **Customizable styling through the customStyle prop** - Allows fine-grained control over component appearance
+
+
+### Usage:
+
+```tsx
+import BookCitation from '@e-llm-studio/citation/BookCitation'
+
+<BookCitation
+ citationTitle="Sample Book"
+ paragraphs={['<p>Highlighted text example</p>']}
+ textToHighlight={['example']}
+ partialMatch={true}
+/>
+```
+
+### Props:
+
+| Prop Name | Type | Description |
+|-----------|------|-------------|
+| `title` | `string` | Optional title of the book or publication being cited |
+| `author` | `string \| string[]` | Optional author name(s) of the book or publication |
+| `pageNumber` | `string` | Optional current page number where the citation is located |
+| `totalPageNumber` | `string` | Optional total number of pages in the book or publication |
+| `paragraphs` | `string[]` | Required array of HTML strings containing the text content |
+| `citationTitle` | `string` | Required title or label for the citation |
+| `textToHighlight` | `string[]` | Required array of text strings to highlight within the paragraphs |
+| `bookCoverImage` | `string` | Optional URL or path to the book cover image |
+| `handleExternalLinkClick` | `() => void` | Optional callback function triggered when external link is clicked |
+| `externalLinkComponent` | `React.ReactNode` | Optional React component to render as an external link button |
+| `citationNumber` | `number` | Optional citation number displayed in the citation button |
+| `partialMatch` | `boolean` | Optional flag to enable partial text matching when highlighting |
+| `defaultState` | `boolean` | Optional flag to set the initial expanded/collapsed state |
+| `isNonHighlightedBlur` | `boolean` | Optional flag to enable blur effect on non-highlighted text |
+| `customStyle` | `object` | Optional object for overriding default styles |
+
+---
+
+
+## ChatCitation
+
+### Overview
+
+ChatCitation is a composable React UI component for rendering chat-based citations, including summarized and detailed chat views alongside a rule book/reference section. The component is designed to be highly customizable via renderers, slot styles, and slot props, making it flexible for various use cases.
+
+### Features
+
+- **Composable chat views** - Supports both summarized and detailed chat display modes
+- **Rule book/reference section** - Optional left panel for displaying supporting rules and references
+- **Markdown rendering** - Rich text support with customizable markdown renderers
+- **Customizable styling** - Fine-grained control over styles through slot-based customization
+- **Relevance scoring** - Display AI relevance scores for citations
+- **Tab-based navigation** - Toggle between summarized and detailed views
+- **Flexible content rendering** - Support for custom renderers and markdown components
+
+### Usage
+
+```tsx
+import ChatCitation from '@e-llm-studio/citation/ChatCitation'
+
+<ChatCitation
+ chatContainer={{
+ chatData: [
+ { role: 'user', message: 'Hello', userName: 'User1', timeStamp: dayjs() }
+ ]
+ }}
+ ruleBookContainer={{
+ title: 'References',
+ data: { content: 'Rule content', highlighted_texts: ['important'] }
+ }}
+/>
+```
+
+### Props
+
+| Prop Name | Type | Description |
+|-----------|------|-------------|
+| `rootContainer` | `RootContainerProps` | Optional top-level container configuration |
+| `chatContainer` | `ChatContainerProps` | Required chat container configuration with chat data |
+| `ruleBookContainer` | `RuleBookContainerProps` | Optional rule book/reference section configuration |
+| `renderer` | `FeatureModMarkdownProps["renderers"]` | Optional custom markdown renderers |
+
+---
+
+
+## CitationRenderer
+
+### Overview
+
+CitationRenderer is a versatile, interactive "Pill" component designed to display a compact reference citation that expands into detailed content. It provides a space-efficient toggle mechanism, perfect for displaying source material, footnotes, or reasoning chains without cluttering the main UI. It works seamlessly with MarkdownRenderer to display rich, interactive text content.
+
+### Features
+
+- **Expandable pill button** - Compact display that expands on click
+- **Customizable icons** - Support for custom icons for chevron and citation indicators
+- **Markdown content support** - Render rich text content using MarkdownRenderer
+- **Controlled and uncontrolled modes** - Manage state internally or externally
+- **Flexible styling** - Customize appearance through style props
+- **Callback support** - Optional callbacks for side effects on toggle
+
+### Usage
+
+```tsx
+import CitationRenderer from '@e-llm-studio/citation/CitationRenderer'
+
+<CitationRenderer
+ inLineCitation={true}
+ citationTitle="Reference 1"
+ citationComponent={<div>Detailed content here</div>}
+ chevronDownComponent={<ChevronDownIcon />}
+ chevronUpComponent={<ChevronUpIcon />}
+/>
+```
+
+### Props 
+
+| Prop Name | Type | Description |
+|-----------|------|-------------|
+| `inLineCitation` | `boolean` | Must be true to enable expand/collapse behavior |
+| `citationTitle` | `string` | The text displayed inside the pill button |
+| `citationComponent` | `ReactNode` | The content to render when expanded |
+| `citationIcon` | `ReactNode` | Icon displayed to the left of the title |
+| `chevronUpComponent` | `ReactNode` | Icon shown when the citation is expanded |
+| `chevronDownComponent` | `ReactNode` | Icon shown when the citation is collapsed |
+| `additionalCallbackForPillButton` | `func` | Hook to trigger side effects on click |
+| `styles` | `Object` | CSS overrides for styling |
+| `isOpen` | `boolean` | Forces the expanded state (controlled mode) |
+| `onToggle` | `func` | Callback fired when the pill is clicked |
+
+---
+
+
+## CognitiveDecisioningCard
+
+### Overview
+
+CognitiveDecisioningCard is a specialized React UI component designed to provide transparency into AI workflows. It renders a toggleable "Pill" that expands into a detailed card, displaying the AI's Reasoning, identified Gaps, and a confidence Score. It features a nested accordion design, robust Markdown rendering for content, and full styling customization.
+
+
+### Features
+
+- **Toggleable pill button** - Click to expand/collapse the detailed card
+- **Reasoning and gap sections** - Display AI reasoning and identified gaps with markdown support
+- **Confidence score badge** - Show confidence percentage in the header
+- **Nested accordion design** - Collapsible sections for organized content
+- **Custom markdown rendering** - Support for custom markdown components
+- **Icon customization** - Replace default icons with custom components
+- **Advanced section customization** - Override default sections with custom data structures
+
+### Usage
+
+```tsx
+import CognitiveDecisioningCard from '@e-llm-studio/citation/CognitiveDecisioningCard'
+
+<CognitiveDecisioningCard
+ isOpen={isOpen}
+ onToggle={() => setIsOpen(!isOpen)}
+ score="92"
+ reasoning="**Analysis:** Based on document review..."
+ gap="Missing date information in section 3."
+ title="AI Analysis Report"
+/>
+```
+
+**Advanced Customization**:
+```tsx
+const customSections = [
+ {
+ id: 'step1',
+ title: 'Data Retrieval',
+ subtitle: '3 sources processed',
+ icon: <CheckIcon />,
+ content: 'Data retrieved successfully'
+ }
+]
+
+<CognitiveDecisioningCard
+ isOpen={true}
+ sections={customSections}
+ score="100"
+ mdComponents={{
+ a: ({ node, ...props }) => <a {...props} target="_blank" />
+ }}
+/>
+```
+
+### Props
+
+| Prop Name | Type | Description |
+|-----------|------|-------------|
+| `reasoning` | `string` | Markdown text explaining the AI's logic |
+| `gap` | `string` | Markdown text explaining missing info or uncertainties |
+| `score` | `string` | Confidence score percentage (e.g., "92") |
+| `isOpen` | `boolean` | Controls the visibility of the expanded card |
+| `onToggle` | `() => void` | Callback handler for the pill trigger click |
+| `title` | `string` | Header title. Default: "Cognitive Decisioning AI" |
+| `hideTrigger` | `boolean` | If true, hides the pill button |
+| `sections` | `SectionContent[]` | Advanced: Overrides default Reasoning/Gap sections |
+| `mdComponents` | `Object` | Custom renderers for react-markdown |
+| `headerIcon` | `ReactNode` | Replaces the default brain icon |
+| `reasoningIcon` | `ReactNode` | Replaces the icon for the reasoning section |
+| `gapIcon` | `ReactNode` | Replaces the icon for the gap section |
+| `scoreIcon` | `ReactNode` | Replaces the sparkle icon in the score badge |
+
+---
+
+## CognitiveInternalGPTReasoning
+
+### Overview
+
+The CognitiveInternalgptReasoningComponent is a React component designed to render non-web search reasoning citations with advanced interactive features. It provides a comprehensive display of reasoning data with support for expandable content, highlight navigation, and modal fullscreen viewing. This component is particularly useful for displaying AI-generated reasoning, training data citations, and confidence scores in a user-friendly format.
+
+### Features
+
+- **Expandable Content** - Display a paraphrase text that expands to show the full data source content
+- **Highlight Navigation** - Automatically extract and navigate between highlighted sections within the content
+- **Confidence Score Display** - Show confidence percentage in both expanded view and modal
+- **Fullscreen Modal View** - Open a fullscreen modal for detailed examination of reasoning data
+- **Text Formatting Support** - Handle bold text, list items, headers, and special highlight tags
+- **Custom Icon Support** - Replace default icons with custom React components
+
+### Usage
+
+```tsx
+import NonWebReasoningComponent from '@e-llm-studio/citation/CognitiveInternalgptReasoningComponent'
+
+const reasoningData = {
+ text: "Reasoning text here",
+ dataSource: "Source with <highlight>highlighted text</highlight>",
+ trainingDataTitle: "Training Dataset v1.0",
+ confidence_score: 95,
+ paraphrase: "Brief summary"
+}
+
+<NonWebReasoningComponent
+ item={reasoningData}
+ index={1}
+ headerTitle="GPT Reasoning"
+/>
+```
+
+**Highlight Navigation**:
+- Extracts `<highlight>` tags from dataSource
+- Provides navigation between highlighted sections
+- Shows current position (e.g., "2/5 highlights")
+- Auto-scrolls to active highlight
+
+---
+
+
+## CodeCitation
+
+### Overview
+
+CodeCitation is a composable React UI component for rendering code citations with interactive features, syntax highlighting, and customizable display modes. It provides developers with a powerful tool for displaying code snippets with syntax highlighting, diagnostics, and theme support.
+
+### Features
+
+- **Inline and popup citation views** - Flexible display modes for different use cases
+- **Syntax highlighting** - Support for multiple programming languages
+- **Dark/Light mode theme toggling** - Accessibility and user preference support
+- **Code highlighting** - Highlight specific lines or variables
+- **Displaying diagnostics** - Show errors and warnings with customizable styling
+- **Fetching code from backend** - Support for dynamic code retrieval
+- **Customizable UI** - Extensive customization through props and inline styles
+- **Fullscreen view support** - View code in fullscreen modal
+- **Responsive design** - Works well on various screen sizes
+
+### Usage
+
+```tsx
+import { CodeCitation } from '@e-llm-studio/citation/CodeCitation'
+
+<CodeCitation
+ citationTitle="Example Code"
+ filename="example.js"
+ filepath="/src/example.js"
+ customCode={`function hello() { return "world"; }`}
+ inLineCitation={true}
+ isDarkModeEnabled={false}
+ showThemeToggle={true}
+ editorHeight={400}
+/>
+```
+
+**Advanced Features**:
+```tsx
+const diagnostics = [
+ {
+ range: { lineStart: 2, lineEnd: 2, columnStart: 6, columnEnd: 11 },
+ severity: 1 
+ }
+]
+
+const highlightRanges = [
+ {
+ startIndex: 2,
+ endIndex: 5,
+ color: 'rgba(255, 255, 0, 0.3)',
+ lightModeColor: 'rgba(255, 255, 0, 0.2)'
+ }
+]
+
+<CodeCitation
+ customCode={sampleCode}
+ diagnostics={diagnostics}
+ diagnosticStylesBySeverity={{
+ 1: { style: { backgroundColor: 'rgba(255,0,0,0.2)' } }
+ }}
+ startIndex={2}
+ endIndex={5}
+ isHighlightingEnabled={true}
+/>
+```
+
+### Props
+
+| Prop Name | Type | Description |
+|-----------|------|-------------|
+| `citationTitle` | `string` | Display name for the citation |
+| `filename` | `string` | Filename with extension to identify the language |
+| `filepath` | `string` | File path for reference |
+| `customCode` | `string` | The code string to display in the editor |
+| `inLineCitation` | `boolean` | Set to true for inline display or false for popup modal |
+| `isDarkModeEnabled` | `boolean` | Enable dark theme by default |
+| `showThemeToggle` | `boolean` | Display theme toggle button |
+| `editorHeight` | `number` | Height of the code editor in pixels |
+| `editorWidth` | `string \| number` | Width of the code editor |
+| `baseUrlForCodeRetrieval` | `string` | Base URL for fetching code from backend |
+| `assistantName` | `string` | Name of the assistant for context |
+| `organizationName` | `string` | Name of the organization |
+| `userId` | `string` | User ID for tracking |
+| `taskId` | `string` | Task ID for context |
+| `repoUrl` | `string` | Repository URL for reference |
+| `showFullscreenIcon` | `boolean` | Display fullscreen toggle button |
+| `showFileSummaryIButton` | `boolean` | Display file summary info button |
+| `isHighlightingEnabled` | `boolean` | Enable code highlighting |
+
+---
+
+## CitationsViewer
+
+### Overview
+
+The Citation Viewer is a rich, interactive React component designed to display AI-generated audio citations. It features a synchronized audio waveform player, a transcript view that highlights active segments, and a summary of key takeaways. This component is ideal for displaying RAG (Retrieval-Augmented Generation) results where the source material is audio or video, allowing users to listen to the specific segment referenced by the AI.
+
+### Features
+
+- **Interactive Waveform** - Visualizes audio using `wavesurfer.js` with playback controls
+- **Smart Highlighting** - Automatically highlights the specific time range referenced in the citation on the waveform
+- **Synchronized Transcript** - Displays chat history and highlights the active message segment
+- **Key Takeaways** - Renders extracted insights with bold text formatting and keyword tags
+- **GCS Integration** - Built-in hook to resolve Google Cloud Storage (`gs://`) URLs to signed URLs via a backend endpoint
+- **Themable** - Fully customizable colors and typography via a theme config object
+
+### Usage
+
+```tsx
+import CitationsViewer from '@e-llm-studio/citation/CitationsViewer'
+
+<CitationsViewer
+ artifact={{
+ baseUrl: "https://api.example.com",
+ artifactTitle: "Quarterly Earnings Call",
+ fileUrl: "gs://bucket/audio.mp3",
+ chatHistory: [
+ {
+ role: "Speaker 1",
+ message: "Revenue increased by 20%",
+ timestamp: "10:30",
+ timestamp_start: 120.5,
+ timestamp_end: 125.0
+ }
+ ],
+ keyTakeaways: [
+ {
+ takeawayId: "1",
+ name: "Revenue Growth",
+ content: "**20% year-over-year growth**",
+ keywords: ["Revenue", "Growth"]
+ }
+ ]
+ }}
+ onCloseHandler={() => console.log('Closed')}
+/>
+```
+
+### Props
+
+| Prop Name | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `artifact` | `ArtifactData` | ✅ | The main data object containing audio, transcript, and metadata |
+| `onCloseHandler` | `() => void` | ❌ | Callback function triggered when the close (X) button is clicked |
+| `theme` | `ThemeConfig` | ❌ | Object to override default colors and fonts |
+| `iconsConfig` | `IconsConfig` | ❌ | Object to inject custom React icons (Play, Pause, Close) |
+
+---
+
+
+## PdfEditorCitation
+
+### Overview
+
+PdfEditorCitation is a core component for the Advanced Document Management and Citation System. It provides a user-friendly interface for viewing, editing, and citing PDF documents directly within the application. It combines interactive PDF viewing capabilities with a collapsible UI pattern, allowing users to manage document space efficiently while maintaining full access to PDF editing and annotation features.
+
+### Features
+
+- **Collapsible PDF viewer functionality** - Users can expand and collapse the PDF editor section
+- **Interactive PDF editing capabilities** - Full support for PDF editing, annotations, and collaborative features
+- **Sentence highlighting support** - Ability to highlight specific sentences within PDF documents
+- **Customizable UI through CSS classes** - Flexible styling options for seamless integration
+
+### Usage
+
+```tsx
+import { PdfEditorCitation } from '@e-llm-studio/citation/PdfEditorCitation'
+
+<PdfEditorCitation
+ citationTitleElement={<div>Research Paper.pdf</div>}
+ pdfUrl="https://example.com/document.pdf"
+ pdfEditorBackendBaseUrl="https://pdf-backend.example.com"
+ sentenceHighlightDetails={{
+ pdfPageNumber: 5,
+ sentenceToHighlight: "key finding in the research"
+ }}
+ currentUserId="user-123"
+/>
+```
+
+### Props
+
+| Prop Name | Type | Description |
+|-----------|------|-------------|
+| `citationTitleElement` | `ReactElement` | A React element to display as the clickable title |
+| `pdfUrl` | `string` | The URL of the PDF file to be displayed and edited |
+| `pdfEditorBackendBaseUrl` | `string` | The base URL of the PDF editor backend service |
+| `citationRootClassName` | `string` | Optional CSS class name for the root container |
+| `citationBodyClassName` | `string` | Optional CSS class name for the body section |
+| `citationBodyWhenCollapsedClassName` | `string` | Optional CSS class name for collapsed state |
+| `citationTitleClassName` | `string` | Optional CSS class name for the title section |
+| `rlefEventServiceBaseUrl` | `string` | Optional base URL for the RLEF event service |
+| `currentUserId` | `string` | Optional user ID of the current user |
+| `sentenceHighlightDetails` | `object` | Optional sentence highlighting configuration |
+
+---
+
+
+## RequirementAICitation
+
+### Overview
+
+RequirementAICitation is a comprehensive React module for displaying AI-generated insights and rich media evidence. It serves two primary purposes: displaying an AI Reasoning Card with expandable sections for logic, gaps, and confidence scores with embedded citations, and providing standalone media citations for Files, Images, and Web Links.
+
+### Features
+
+- **AI Reasoning Card** - Complex, expandable card displaying AI logic, gaps, and confidence scores with embedded, clickable citations
+- **Standalone Media Citations** - Individual, stylized citation pills for Files, Images, and Web Links
+- **Multiple Citation Types** - Support for file citations (PDFs), image citations, and web citations
+- **Relevance Scoring** - Display AI relevance scores for all citation types
+- **Rich Media Preview** - Integrated viewers for PDFs, images, and web content
+- **Customizable Styling** - Deep CSS injection for all components
+
+### Usage 1: AI Reasoning Card (Composite Component)
+Use this when you want to display AI analysis with embedded, clickable citations that open in a preview panel.
+
+```tsx
+import { AiReasoningCitation } from '@e-llm-studio/citation/AiReasoningCitation'
+
+<AiReasoningCitation
+  title="AI Analysis"
+  aiReasoningAccordionProps={{
+    icons: {
+      chevronUp: <i className="pi pi-angle-up" />,
+      chevronDown: <i className="pi pi-angle-down" />
+    }
+  }}
+  aiReason={{
+    id: "1",
+    relevance_score: 95,
+    reason: ["The <a href='document_citation$1'>ADK.pdf</a> mentions the Agent Card..."],
+    gap: ["Registry mechanism is undefined"]
+  }}
+  citationList={{
+    file_citations: [{
+      citation_number: "1",
+      customMetadata: {
+        type: "book_citation_pdf",
+        file_name: "ADK.pdf",
+        highlighted_pdf_signed_url: "https://storage.googleapis.com/..."
+      }
+    }],
+    image_citations: [],
+    web_citations: []
+  }}
+  
+  projectDetails={null}
+/>
+```
+
+**How Citations Work in AI Reasoning Card:**
+- Text contains links like `<a href='document_citation$1'>` or `<a href='image_citation$2'>`
+- Clicking a link opens the corresponding citation in a preview panel
+- Citation data is looked up from `citationList` using the citation number
+
+---
+
+### Usage 2: Standalone Image Citation
+
+Use this component independently to display an image with relevance scoring.
+
+```tsx
+import { ImageCitationContent } from '@e-llm-studio/citation/ImageCitationContent'
+
+<ImageCitationContent
+  citationTitle="Visual Reference"
+  relevanceScore={95}
+  signedUrl="https://images.pexels.com/photo.jpeg"
+  
+  // Optional: For closeable preview
+  closeCitationConfig={{
+    CloseIcon: () => <span>✕</span>,
+    handleCloseCitationPreview: () => console.log('Closed')
+  }}
+  
+  // Optional: Custom styling
+  styles={{
+    container: { border: '1px solid #ccc' },
+    image: { maxHeight: '500px' },
+    aiConfidenceDisplayPill: {
+      container: { border: "2px solid blue" }
+    }
+  }}
+/>
+```
+
+**With CitationRenderer (Expandable Pill):**
+```tsx
+import { CitationRenderer } from '@e-llm-studio/citation/CitationRenderer'
+import { ImageCitationContent } from '@e-llm-studio/citation/ImageCitationContent'
+
+<CitationRenderer
+  inLineCitation={true}
+  citationTitle="Screenshot Reference"
+  citationComponent={
+    <ImageCitationContent
+      relevanceScore={95}
+      signedUrl="https://images.pexels.com/photo.jpeg"
+    />
+  }
+  chevronDownComponent={<span>▼</span>}
+  chevronUpComponent={<span>▲</span>}
+/>
+```
+
+---
+
+### Usage 3: Standalone File/PDF Citation
+
+Use this component independently to display PDF documents with relevance scoring.
+
+```tsx
+import { FileCitationContent } from '@e-llm-studio/citation/FileCitationContent'
+
+<FileCitationContent
+  title="Technical Specification.pdf"
+  relevanceScore={88}
+  signedUrl="https://example.com/sample.pdf"
+  
+  // Optional: For closeable preview
+  closeCitationConfig={{
+    CloseIcon: () => <span>✕</span>,
+    handleCloseCitationPreview: () => console.log('Closed')
+  }}
+/>
+```
+
+**With CitationRenderer (Expandable Pill):**
+```tsx
+import { CitationRenderer } from '@e-llm-studio/citation/CitationRenderer'
+import { FileCitationContent } from '@e-llm-studio/citation/FileCitationContent'
+
+<CitationRenderer
+  inLineCitation={true}
+  citationTitle="Technical Spec.pdf"
+  citationComponent={
+    <FileCitationContent
+      title="Spec.pdf"
+      relevanceScore={88}
+      signedUrl="https://example.com/sample.pdf"
+      styles={{ pdfWrapper: { height: "750px" } }}
+    />
+  }
+  chevronDownComponent={<span>▼</span>}
+  chevronUpComponent={<span>▲</span>}
+/>
+```
+
+---
+
+### Usage 4: Standalone Web Citation
+
+Use this component independently to display web content with screenshot preview.
+
+```tsx
+import { WebCitationWithImageContent } from '@e-llm-studio/citation/WebCitationWithImageContent'
+
+<WebCitationWithImageContent
+  label="Pexels - Free Stock Photos"
+  url="https://www.pexels.com/photo/..."
+  relevanceScore={92}
+  signedUrl="https://images.pexels.com/screenshot.jpeg"
+  
+  PreviewDialogCloseIcon={() => <span>✕</span>}
+  visitIcon={() => <span>→</span>}
+
+  closeCitationConfig={{
+    CloseIcon: () => <span>✕</span>,
+    handleCloseCitationPreview: () => console.log('Closed')
+  }}
+/>
+```
+
+**With CitationRenderer (Expandable Pill):**
+```tsx
+import { CitationRenderer } from '@e-llm-studio/citation/CitationRenderer'
+import { WebCitationWithImageContent } from '@e-llm-studio/citation/WebCitationWithImageContent'
+
+<CitationRenderer
+  inLineCitation={true}
+  citationTitle="Pexels Source"
+  citationComponent={
+    <WebCitationWithImageContent
+      label="Pexels Source"
+      url="https://www.pexels.com/..."
+      relevanceScore={92}
+      signedUrl="https://images.pexels.com/screenshot.jpeg"
+      PreviewDialogCloseIcon={() => <span>✕</span>}
+      visitIcon={() => <span>→</span>}
+    />
+  }
+  chevronDownComponent={<span>▼</span>}
+  chevronUpComponent={<span>▲</span>}
+/>
+```
+
+---
+
+### Component Props Reference
+
+#### AiReasoningCitation Props
+
+| Prop Name | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `title` | `string` | ✅ | Title on the main pill |
+| `aiReason` | `TAIReasoning` | ✅ | Contains `id`, `reason`, `gap`, `relevance_score` |
+| `citationList` | `Citations` | ✅ | Lookup object for all referenced files/images/web |
+| `aiReasoningAccordionProps` | `Object` | ✅ | Must contain `icons: { chevronUp, chevronDown }` |
+| `projectDetails` | `Array` | ❌ | Context for specific app-mod logic |
+| `cachingConfig` | `Object` | ❌ | For using `gsUtilPath` instead of `signedUrl` |
+| `iconConfig` | `Object` | ❌ | Custom icons: `citationIcon`, `reasoningIcon`, `gapIcon` |
+| `titleConfig` | `Object` | ❌ | Custom titles for sections |
+| `styles` | `Object` | ❌ | Deep style overrides |
+
+#### ImageCitationContent Props
+
+| Prop Name | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `signedUrl` | `string` | ✅ | Direct URL to the image |
+| `gsUtilPath` | `string` | ✅ | GCS Path (requires `cachingConfig`) |
+| `citationTitle` | `string` | ❌ | Title shown in header (default: "Visual Reference") |
+| `relevanceScore` | `number` | ❌ | Score to display (0-100) |
+| `closeCitationConfig` | `Object` | ❌ | `{ CloseIcon, handleCloseCitationPreview }` |
+| `cachingConfig` | `Object` | ❌ | For GCS URL resolution |
+| `styles` | `Object` | ❌ | Deep style overrides |
+
+*Either `signedUrl` or `gsUtilPath` must be provided
+
+#### FileCitationContent Props
+
+| Prop Name | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `title` | `string` | ✅ | Title shown in the viewer header |
+| `signedUrl` | `string` | ✅ | Direct URL to the PDF |
+| `gsUtilPath` | `string` | ✅ | GCS Path (requires `cachingConfig`) |
+| `relevanceScore` | `number` | ❌ | Score to display (0-100) |
+| `closeCitationConfig` | `Object` | ❌ | `{ CloseIcon, handleCloseCitationPreview }` |
+| `cachingConfig` | `Object` | ❌ | For GCS URL resolution |
+| `styles` | `Object` | ❌ | Deep style overrides including `pdfWrapper` height |
+
+*Either `signedUrl` or `gsUtilPath` must be provided
+
+#### WebCitationWithImageContent Props
+
+| Prop Name | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | `string` | ✅ | The actual link to visit |
+| `label` | `string` | ✅ | Text for the link anchor |
+| `signedUrl` | `string` | ✅ | URL for the screenshot image |
+| `gsUtilPath` | `string` | ✅ | GCS Path (requires `cachingConfig`) |
+| `PreviewDialogCloseIcon` | `Component` | ✅ | Icon for fullscreen modal close button |
+| `visitIcon` | `Component` | ✅ | Icon for the "Visit Link" button |
+| `relevanceScore` | `number` | ❌ | Score to display (0-100) |
+| `closeCitationConfig` | `Object` | ❌ | `{ CloseIcon, handleCloseCitationPreview }` |
+| `cachingConfig` | `Object` | ❌ | For GCS URL resolution |
+| `styles` | `Object` | ❌ | Deep style overrides |
+
+*Either `signedUrl` or `gsUtilPath` must be provided
+
+---
+
+**Required peer dependencies:**
+```bash
+npm install react-markdown rehype-raw @react-pdf-viewer/core @material-ui/core
+```
+
+---
+
+## ScannedDocCitation
+
+### Overview
+
+ScannedDocCitation is a React component for displaying scanned documents with interactive bounding box highlight overlays. It supports multi-page scrolling, highlight navigation via arrows, and a fullscreen view.
+
+### Features
+
+- **Multi-page scrolling** - All pages stacked vertically inside a fixed-height scrollable container
+- **Bounding box highlights** - Overlay highlights on document pages using normalized pixel coordinates
+- **Highlight navigation** - Jump between highlights using ↑↓ arrows, auto-scrolls to active highlight
+- **Fullscreen modal** - Expand to a larger view for detailed examination
+- **Customizable highlight colors** - Control highlight color, active color, and border color
+- **Pixel coordinate normalization** - Accepts raw pixel coordinates and normalizes using page dimensions
+
+### Usage
+```tsx
+import ScannedDocCitation from '@e-llm-studio/citation/ScannedDocCitation'
+
+<ScannedDocCitation
+  images={[
+    'https://example.com/page1.png',
+    'https://example.com/page2.png'
+  ]}
+  highlights={[
+    {
+      pageIndex: 0,
+      dimensions: { width: 1275, height: 1650 },
+      bboxes: [
+        { xmin: 127, ymin: 132, xmax: 1147, ymax: 297 }
+      ]
+    },
+    {
+      pageIndex: 1,
+      dimensions: { width: 1275, height: 1650 },
+      bboxes: [
+        { xmin: 89, ymin: 742, xmax: 1147, ymax: 891 }
+      ]
+    }
+  ]}
+  height="700px"
+/>
+```
+
+**With Custom Highlight Colors**:
+```tsx
+<ScannedDocCitation
+  images={imageUrls}
+  highlights={highlights}
+  highlightColor="rgba(100, 160, 255, 0.3)"
+  highlightActiveColor="rgba(100, 160, 255, 0.6)"
+  highlightBorderColor="rgba(50, 100, 220, 0.8)"
+/>
+```
+
+### Props
+
+| Prop Name | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `images` | `string[]` | ✅ | — | Array of image URLs, one per page |
+| `highlights` | `PageHighlight[]` | ✅ | — | Array of highlights with bounding boxes per page |
+| `highlightColor` | `string` | ❌ | `rgba(255,220,0,0.35)` | Background color of inactive highlights |
+| `highlightActiveColor` | `string` | ❌ | `rgba(255,220,0,0.65)` | Background color of the currently active highlight |
+| `highlightBorderColor` | `string` | ❌ | `rgba(200,160,0,0.8)` | Border color of the active highlight |
+| `height` | `string \| number` | ❌ | `700px` | Height of the scrollable container |
+
+### Type Definitions
+```typescript
+interface BBox {
+  xmin: number;  // raw pixel coordinate
+  ymin: number;
+  xmax: number;
+  ymax: number;
+}
+
+interface PageHighlight {
+  pageIndex: number;               // zero-based page index (page_no - 1)
+  bboxes: BBox[];                  // bounding boxes on this page
+  dimensions: {
+    width: number;                 // original image width in pixels e.g. 1275
+    height: number;                // original image height in pixels e.g. 1650
+  };
+}
+
+interface ScannedDocCitationProps {
+  images: string[];
+  highlights: PageHighlight[];
+  highlightColor?: string;
+  highlightActiveColor?: string;
+  highlightBorderColor?: string;
+  height?: string | number;
+}
+```
+
+---
+
+
+# Other Components
+## Bookemon
+
+### Overview
+
+Bookemon is a composable, dialog-based React UI component designed for deep book inspection. It features a resizable split-panel layout that allows users to browse detailed metadata while simultaneously viewing and interacting with specific manuscript content. The component is designed to be highly customizable via style injections and handles complex logic for smart text citation, server-side pagination, and focus-mode blurring.
+
+### Features
+
+- **Resizable split-panel layout** - Left panel for metadata, right panel for content preview
+- **Deep book inspection** - Browse detailed metadata including overview, elements, copyrights, and awards
+- **Smart text citation** - Automatically highlights and focuses on specific text passages
+- **Server-side pagination** - Efficiently handles large datasets with pagination support
+- **Focus-mode blurring** - Blur non-highlighted text to focus reader attention on relevant content
+- **Highly customizable styling** - Inject custom styles for layout containers and citation elements
+- **Interactive accordions** - Collapsible sections for book metadata organization
+
+
+### Usage
+
+```tsx
+import Bookemon from '@e-llm-studio/citation/Bookemon'
+
+<Bookemon
+ open={isOpen}
+ onClose={() => setIsOpen(false)}
+ data={bookData}
+ getHighlightContent={fetchContent}
+ isBlurToggleVisible={true}
+/>
+```
+
+### Props
+
+| Prop Name | Type | Description |
+|-----------|------|-------------|
+| `open` | `boolean` | Controls the visibility of the dialog |
+| `onClose` | `() => void` | Callback function triggered when the dialog is closed |
+| `data` | `BookemonData` | Object containing book metadata and elements |
+| `getHighlightContent` | `(chunkIds: string[]) => Promise<ContentItem[]>` | Async handler to fetch content for highlighting |
+| `handleFetchManuscriptElements` | `(params: FetchElementsParams) => Promise<PaginatedResponse>` | Async handler for fetching paginated manuscript elements |
+| `isBookemon` | `boolean` | Default: true. Feature flag for Bookemon-specific behavior |
+| `isBlurToggleVisible` | `boolean` | Default: false. Shows the blur switch in header |
+| `isNonHighlightedBlur` | `boolean` | Default: false. Initial blur state |
+| `showComingSoon` | `boolean` | Default: false. Gates the UI with coming soon overlay |
+| `customStyle` | `BookemonCustomStyles` | Optional custom styles for layout and citation elements |
+
+---
+
+
+## DatagestMon
+
+### Overview
+
+DatagestMon is a React component for monitoring and displaying structured data from processing stages (analysis, transform, rag). It provides a comprehensive interface that combines dynamic data visualization with an integrated EPUB viewer. The component uses Material-UI Dialog for display and includes a built-in EPUB reader powered by react-reader.
+
+### Features
+
+- **Multi-stage data display** - Visualize data from analysis, transform, and rag stages
+- **Processed and error data** - Display both successful processing results and error information
+- **Integrated EPUB viewer** - View associated EPUB content side-by-side with data
+- **Dynamic data visualization** - Automatically render various data types
+- **Material-UI Dialog** - Professional modal presentation
+- **Graceful error handling** - Handle missing or malformed data gracefully
+
+### Usage
+
+```tsx
+import DatagestMon from '@e-llm-studio/citation/DatagestMon'
+
+const pipelineData = {
+ "analysis": {
+ "processed_data": {
+ "summary": "Analysis completed",
+ "functions": "15 functions extracted"
+ },
+ "error_data": {
+ "rate_limit_exceeded": true
+ }
+ },
+ "transform": {
+ "processed_data": {
+ "embeddings": 123,
+ "transformed_records": 1200
+ },
+ "error_data": {}
+ }
+}
+
+<DatagestMon
+ open={isOpen}
+ onClose={() => setIsOpen(false)}
+ data={pipelineData}
+ url="https://example.com/document.epub"
+/>
+```
+
+### Props
+
+| Prop Name | Type | Description |
+|-----------|------|-------------|
+| `open` | `boolean` | Controls whether the dialog is open or closed |
+| `onClose` | `function` | Callback function triggered when the dialog is closed |
+| `data` | `object` | Object containing structured data from processing stages |
+| `url` | `string` | Optional URL of the EPUB file to display in the viewer |
+
+---
+
+
+## DataSelector
+ 
+### Overview
+
+DataSelector is a robust, multi-step wizard designed to handle complex data import workflows. It acts as a central hub where users can select data from various sources—including remote RLEF projects, historical copilot data, saved datasets, or local file uploads—and aggregates them into a unified selection state. It features a built-in state machine for navigation, breadcrumb management, and context-driven state sharing.
+
+### Features
+
+- **Multi-step wizard interface** - Guide users through complex data selection workflows
+- **Multiple data sources** - Support for RLEF projects, historical data, saved datasets, and local files
+- **Breadcrumb navigation** - Easy navigation through wizard steps
+- **Server-side pagination** - Efficiently handle large datasets
+- **Search and filtering** - Find data quickly with built-in search
+- **State machine navigation** - Robust step management
+- **Context-driven state sharing** - Centralized state management via React Context
+
+### Usage
+
+```tsx
+import { DataSelectedContextProvider } from '@e-llm-studio/citation/context/DataSelectedContext'
+import DataSelector from '@e-llm-studio/citation/DataSelector'
+
+<DataSelectedContextProvider>
+ <DataSelector
+ pageTitle="Import Dataset"
+ selectedRlefResources={resources}
+ setSelectedRlefResources={setResources}
+ selectedLocalFiles={files}
+ setSelectedLocalFiles={setFiles}
+ />
+</DataSelectedContextProvider>
+```
+
+**Wizard Steps**:
+1. **Data source selection** - Choose from RLEF, Local, Google Drive, Saved Datasets
+2. **Project/task selection** - Select specific projects or tasks
+3. **Data collection selection** - Choose from available data collections
+4. **Data point selection** - Select specific data points within collections
+5. **Final review** - Review and confirm selections
+
+
+### Props
+
+| Prop Name | Type | Description |
+|-----------|------|-------------|
+| `selectedRlefResources` | `Array` | Initial array of selected remote resources |
+| `setSelectedRlefResources` | `Function` | State setter for remote resources |
+| `selectedLocalFiles` | `Array` | Initial array of selected local files |
+| `setSelectedLocalFiles` | `Function` | State setter for local files |
+| `pageTitle` | `string` | Customizes the header text |
+| `renderDefaultActionsFooter` | `boolean` | Show/hide the default "Next" button |
+
+---
+
+## PaginatedTable
+
+### Overview
+
+PaginatedTable is a high-performance React component designed to display large datasets efficiently. It leverages virtualization (via react-window) to render only the visible rows, ensuring smooth scrolling even with thousands of records. It also supports infinite scrolling, automatically triggering a "load more" callback when the user scrolls near the bottom.
+
+### Features
+
+- **Virtualization** - Efficiently renders massive datasets using windowing
+- **Infinite scroll** - Automatically calls onNextPage when scrolling to the bottom
+- **Sticky headers** - Headers remain visible while scrolling vertically
+- **Horizontal scrolling** - Handles wide tables with a custom scrollbar
+- **Loading states** - Displays a skeleton loader row when fetching more data
+- **Customizable** - Supports custom dimensions and granular style overrides
+
+### Usage
+
+```tsx
+import PaginatedTable from '@e-llm-studio/citation/PaginatedTable'
+
+<PaginatedTable
+ headers={["ID", "Name", "Email", "Status"]}
+ tableData={users}
+ totalFileRecords={10000}
+ onNextPage={fetchNextPage}
+ loadingMore={isLoading}
+ headerRefs={headerRefs}
+ columnWidth={200}
+ rowHeight={50}
+ style={{ height: "600px" }}
+/>
+```
+
+**Performance Characteristics**:
+- Renders only visible rows (windowed rendering)
+- Handles thousands of rows efficiently
+- Smooth scrolling even with large datasets
+- Memory efficient for large data volumes
+
+### Props
+
+| Prop Name | Type | Description |
+|-----------|------|-------------|
+| `headers` | `string[]` | An array of column header names |
+| `tableData` | `Object[]` | Array of data objects where keys match the headers |
+| `onNextPage` | `() => void` | Callback triggered when scrolling near the bottom |
+| `headerRefs` | `RefObject` | A ref object to store references to header DOM elements |
+| `totalFileRecords` | `number` | The total count of records available on the server |
+| `loadingMore` | `boolean` | If true, shows a skeleton loader at the bottom |
+| `columnWidth` | `number` | Fixed width (in px) for every column |
+| `rowHeight` | `number` | Fixed height (in px) for every row |
+| `className` | `string` | Custom CSS class for the main container |
+| `style` | `CSSProperties` | Inline styles for the main container |
+| `styleOverrides` | `Object` | Granular styles for internal elements |
+
+---
+
+
+## PdfViewer
+### Overview 
+PdfViewer is a specialized, highly customizable React component designed to render PDF documents with built-in capabilities for text highlighting and highlight navigation. It is built on top of the @react-pdf-viewer library and is optimized for review workflows. It takes a specific list of keywords to highlight and a list of relevant pages, allowing users to "jump" directly between pages that contain relevant information. It supports deep UI overrides via custom classes, styles, and icons to fit seamlessly into any theme.FeaturesText highlighting - Automatically highlight keywords within the documentHighlight navigation - Jump between pages with relevant contentZoom controls - In/out zoom and popover zoom optionsPage navigation - Navigate between highlighted pagesCustom toolbar - Sticky header with navigation controlsDeep UI Customization - Extensive customization through customStyles, customClasses, and customIcons propsResponsive design - Works well on various screen sizesUsageTypeScriptimport PdfViewer from '@e-llm-studio/citation/PdfViewer'
+
+### Usage
+```tsx
+import PdfViewer from '@e-llm-studio/citation/PdfViewer'
+<PdfViewer
+ pdfUrl="https://example.com/contract.pdf"
+ highlightText={["confidential", "termination", "liability"]}
+ highlightPages={[3, 8, 12]}
+ jumpToPageValue={3}
+ // Optional Customization Hooks
+ customStyles={{ 
+   pdfIconWrapper: { background: "#ffe4e6", border: "6px solid #fff1f2" },
+   pdfName: { color: "#e11d48", fontWeight: "bold" },
+ }}
+ customClasses={{ 
+   actionButton: "p-2 hover:bg-red-100 rounded-lg transition-colors text-red-500", 
+ }}
+ customIcons={{ 
+   pdfIcon: <MyCustomIcon /> 
+ }}
+/>
+
+### Navigation Behavior
+- "Next" button jumps to next page with highlights
+- "Previous" button jumps to previous highlighted page
+- Direct page navigation based on highlightPages array
+- Auto-zoom to actual size on load
+
+### Props
+Prop Name	Type	Description
+pdfUrl	- string -	The direct URL to the PDF file to be rendered
+highlightText - 	string[] -	An array of keywords or phrases to automatically highlight
+highlightPages -	number[] -	An object of page numbers (1-based) where highlights appear
+jumpToPageValue -	number -	The specific page number to open the document at initially
+customStyles -	CustomStylesType -	Optional object to override default inline styles for elements like the viewer wrapper, header, or icons
+customClasses -	CustomClassesType -	Optional object to inject custom CSS or Tailwind classes
+customIcons - 	CustomIconsType -	Optional object to replace default SVG icons (pdfIcon, fullScreenIcon, downloadIcon, closeIcon)
+
+## ProjectAccordion
+
+### Overview
+
+ProjectAccordion is a React component designed to display project-related information in an accordion format. Further details to be added.
+
+### Features
+
+- Expandable/collapsible accordion design
+- Markdown rendering for executive summaries
+- Checkbox selection support
+- API integration for fetching summaries
+- Customizable styling
+
+### Usage
+
+```tsx
+import ProjectAccordion from '@e-llm-studio/citation/ProjectAccordion'
+
+<ProjectAccordion
+ baseUrl="https://api.example.com"
+ taskId="project-123"
+ citationTitle="Executive Summary"
+ isChecked={selected}
+ onCheckChange={(checked) => setSelected(checked)}
+ chevronUpComponent={<UpIcon />}
+ chevronDownComponent={<DownIcon />}
+ styles={{
+ pillButton: {
+ fontFamily: 'Plus Jakarta Sans, sans-serif',
+ border: '0px',
+ padding: '8px',
+ cursor: 'pointer'
+ }
+ }}
+/>
+```
+
+### Props
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `baseUrl` | string | Yes | API base URL |
+| `taskId` | string | Yes | Task/project identifier |
+| `citationTitle` | string \| ReactNode | Yes | Accordion header title |
+| `isChecked` | boolean | No | Controlled checkbox state |
+| `onCheckChange` | function | No | Checkbox change callback |
+| `execSummary` | string | No | Pre-fetched summary text |
+
+---
+
+
+## UploadData
+
+### Overview
+
+UploadData is a feature within the DataSelector component that handles data import from various sources. It provides a comprehensive interface for users to upload data from multiple sources including RLEF projects, Google Drive, local file systems, and saved datasets. The role of its sub-components is to manage the data selection process across different data sources.
+
+### Features
+
+- **Multiple data source support** - Import from RLEF, Google Drive, local files, and saved datasets
+- **Unified selection interface** - Aggregate data from various sources
+- **File upload handling** - Support for local file uploads
+- **Cloud integration** - Google Drive integration for cloud-based data
+- **Saved dataset management** - Access and manage previously saved datasets
+
+### Usage
+
+```tsx
+import { UploadData } from '@e-llm-studio/citation'
+import { DataSelectedProvider } from '@e-llm-studio/citation/context/DataSelectedContext'
+
+<DataSelectedProvider>
+ <UploadData />
+</DataSelectedProvider>
+```
+
+### Upload Sources
+
+- **RLEF Projects**: Data from Research Learning Ecosystem Framework
+- **Google Drive**: Cloud-based file storage
+- **Local Files**: Direct file upload from device
+- **Saved Datasets**: Previously saved data collections
+
+
+**Integration Example**:
+```tsx
+import { useSelectDataContext } from '@e-llm-studio/citation/context/DataSelectedContext'
+
+const MyComponent = () => {
+ const { selectedRlefResources, saveSelectedDataAsDataSet } = useSelectDataContext()
+ 
+ return (
+ <DataSelectedProvider>
+ <UploadData />
+ <button onClick={() => saveSelectedDataAsDataSet()}>
+ Save as Dataset
+ </button>
+ </DataSelectedProvider>
+ )
+}
+```
+
+---
+
+## ReviewPanel
+
+### Overview
+
+ReviewPanel is a flexible and accessible component for displaying and managing a list of items with review status tracking. It allows users to navigate through items, track completion status, and customize rendering and styling. The component supports both controlled and uncontrolled modes, making it suitable for various use cases from simple item lists to complex review workflows.
+
+### Features
+
+- **Flexible item rendering** - Custom `renderItem` prop for complete control over item appearance
+- **Expand/collapse functionality** - Collapsible item list with smooth animations
+- **Navigation and status tracking** - Previous/next buttons and visual status indicators
+- **Controlled and uncontrolled modes** - Flexible state management options
+- **Customizable theming** - Light and dark modes using CSS variables
+- **Accessibility support** - Full keyboard navigation and ARIA attributes
+
+### Usage
+
+```tsx
+import { ReviewPanel } from '@e-llm-studio/citation/ReviewPanel'
+
+const items = [
+  { id: '1', label: 'Item 1' },
+  { id: '2', label: 'Item 2' },
+  { id: '3', label: 'Item 3' },
+];
+
+function App() {
+  return (
+    <ReviewPanel
+      data={items}
+      itemConfig={{
+        textKey: 'label',
+        showStatusIcon: true,
+      }}
+      theme="dark"
+    />
+  );
+}
+```
+
+### Props
+
+| Prop Name | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `data` | `T[]` | Required | Array of items to display in the review panel |
+| `renderItem` | `(params) => ReactNode` | `undefined` | Custom render function for items. If not provided, uses default rendering |
+| `itemConfig` | `DefaultItemConfig<T>` | `{}` | Configuration for default item rendering including textKey, showStatusIcon, and showRightBadge |
+| `activeIndex` | `number` | `undefined` | Current active item index (controlled mode). When undefined, component manages state internally |
+| `onActiveChange` | `(index: number) => void` | `undefined` | Callback fired when active index changes |
+| `expanded` | `boolean` | `undefined` | Whether the item list is expanded (controlled mode). When undefined, component manages state internally |
+| `onExpandedChange` | `(expanded: boolean) => void` | `undefined` | Callback fired when expanded state changes |
+| `headerLeftSlot` | `ReactNode` | `undefined` | Custom content to display on the left side of the header |
+| `headerRightSlot` | `(params) => ReactNode` | `undefined` | Custom content to display on the right side of the header |
+| `footerSlot` | `ReactNode` | `undefined` | Custom content to display in the footer section |
+| `getItemStatus` | `(item: T, index: number) => ReviewStatus` | `undefined` | Function to determine the review status of each item |
+| `theme` | `'light' \| 'dark'` | `'dark'` | Color theme for the component |
+| `classes` | `ReviewPanelClasses` | `undefined` | Custom CSS class names for component sections |
+| `keyExtractor` | `(item: T, index: number) => string` | `(_, i) => i.toString()` | Function to extract unique key for each item |
+| `className` | `string` | `undefined` | Custom CSS class for the root container |
+
+---
+
+## TableCitationContent
+
+### Overview
+
+TableCitationContent is a component for rendering tabular data citations with flexible styling and formatting. It automatically discovers columns from data, handles smart formatting for numbers and booleans, and provides built-in support for highlighting specific rows and columns. The component is designed to display structured data in a clean, organized table format with responsive scrolling and sticky headers, making it ideal for presenting data citations, validation results, and metrics in applications.
+
+### Features
+
+- **Automatic column discovery** - Dynamically generates headers from the keys provided in the data rows
+- **Smart data formatting** - Automatically formats numbers to fixed decimals and booleans to visual icons (✓/✕)
+- **Theming via CSS Variables** - Easily customize appearance using CSS custom properties without modifying source code
+- **Highlighting for rows and columns** - Built-in support for highlighting specific rows or columns for emphasis
+- **Sticky headers and responsive scrolling** - Keeps table headers visible while scrolling through large datasets with horizontal and vertical scroll support
+- **Data validation UI** - Built-in support for highlighting "failed" cells using the `markFailed` property
+
+### Usage
+
+```tsx
+import TableCitationContent from '@e-llm-studio/citation/TableCitationContent';
+
+const tableData = [
+  { id: 1, name: "Project Alpha", status: true },
+  { id: 2, name: "Project Beta", status: false },
+];
+
+function App() {
+  return (
+    <TableCitationContent
+      title="Deployment Status"
+      timestamp="Feb 04, 2026"
+      rows={tableData}
+      onClose={() => console.log('Closed')}
+    />
+  );
+}
+```
+
+### Props
+
+| Prop Name | Type | Description |
+|-----------|------|-------------|
+| `rows` | `Record<string, any>[]` | Array of objects representing the table data. Required prop. |
+| `title` | `string` | The main title displayed in the header. |
+| `timestamp` | `string` | Sub-header text for dates or versions. |
+| `highlightColumns` | `string[]` | List of column keys to apply a highlight background. |
+| `highlightRowIndex` | `number` | Zero-based index of a specific row to highlight. |
+| `onClose` | `() => void` | Callback function triggered when the close button is clicked. |
+| `CloseIcon` | `React.ElementType` | Custom React component to use as the close icon. |
+| `className` | `string` | Custom CSS class to apply to the root container. |
+
+---
+
+## Common Use Cases
+
+### RAG (Retrieval Augmented Generation) Applications
+```tsx
+// Display book citations in RAG responses
+<BookCitation
+ citationTitle="Source: Machine Learning Textbook"
+ paragraphs={[relevantParagraph]}
+ textToHighlight={[queryKeywords]}
+/>
+
+// Show AI reasoning behind answers
+<CognitiveDecisioningCard
+ score="88"
+ reasoning="Based on chapter 3 of the textbook..."
+ gap="The textbook doesn't cover recent developments after 2020"
+/>
+```
+
+### Code Review and Documentation
+```tsx
+// Display code snippets with diagnostics
+<CodeCitation
+ filename="utils.js"
+ customCode={problematicCode}
+ diagnostics={lintErrors}
+ isHighlightingEnabled={true}
+ startIndex={errorLine - 1}
+ endIndex={errorLine + 1}
+/>
+
+// Show training data citations for code explanations
+<NonWebReasoningComponent
+ item={trainingDataCitation}
+ index={1}
+ headerTitle="Training Data Reference"
+/>
+```
+
+### Audio/Video Content Analysis
+```tsx
+// Show audio citations with synchronized transcripts
+<CitationsViewer
+ artifact={audioAnalysis}
+ onCloseHandler={closePlayer}
+/>
+
+// Display key takeaways from audio content
+<CitationsViewer
+ artifact={{
+ fileUrl: "gs://bucket/interview.mp3",
+ keyTakeaways: [
+ {
+ takeawayId: "1",
+ name: "Key Insight",
+ content: "**Important finding** from the interview",
+ keywords: ["insight", "finding"]
+ }
+ ]
+ }}
+/>
+```
+
+### Document Review Workflows
+```tsx
+// PDF review with highlighting
+<PdfViewer
+ pdfUrl={contractUrl}
+ highlightText={keyClauses}
+ highlightPages={relevantPages}
+/>
+
+// Collaborative PDF editing
+<PdfEditorCitation
+ citationTitleElement={<div>Legal Document.pdf</div>}
+ pdfUrl={legalDocUrl}
+ currentUserId={user.id}
+ pdfEditorBackendBaseUrl="https://pdf-backend.example.com"
+/>
+```
+
+### Data Import and Management
+```tsx
+// Multi-step data import wizard
+<DataSelectedContextProvider>
+ <DataSelector
+ pageTitle="Import Training Data"
+ selectedRlefResources={trainingData}
+ setSelectedRlefResources={setTrainingData}
+ />
+</DataSelectedContextProvider>
+
+// Upload interface wrapper
+<DataSelectedProvider>
+ <UploadData />
+</DataSelectedProvider>
+```
+
+### Performance-Optimized Data Display
+```tsx
+// Virtualized table for large datasets
+<PaginatedTable
+ headers={columns}
+ tableData={largeDataset}
+ totalFileRecords={100000}
+ onNextPage={loadMoreData}
+ loadingMore={loading}
+ style={{ height: "500px" }}
+/>
+```
+
+---
+
+# RequirementAIWrapper
+
+---
+
+# Props
+
+| Prop           | Type                                                         |
+| -------------- | ------------------------------------------------------------ |
+| userStory      | `IUserStory \| null`                                         |
+| setUserStory   | `React.Dispatch<React.SetStateAction<IUserStory \| null>>`   |
+| aiReasoning    | `TAIReasoning[]`                                             |
+| setAiReasoning | `React.Dispatch<React.SetStateAction<TAIReasoning[]>>`       |
+| citations      | `UserStoryCitations[]`                                       |
+| setCitations   | `React.Dispatch<React.SetStateAction<UserStoryCitations[]>>` |
+| children       | `ReactNode`                                                  |
+
+---
+
+# Data Structures
+
+## IUserStory
+
+```ts
+export interface IUserStory {
+  artifactId: string;
+  title: string;
+  value: string;
+  sub_features?: IUserStory[];
+
+  storyNumber?: string;
+  description?: string;
+  section?: "intro" | "subfeature";
+  blockNumber?: string;
+
+  citation?: UserStoryCitations;
+  aiReasoning?: TAIReasoning[];
+
+  isEnd?: boolean;
+}
+```
+
+---
+
+## TAIReasoning
+
+```ts
+export type TAIReasoning = {
+  id: string;
+  reason: string;
+  gap: string;
+  relevance_score: number;
+  reasonSource?: string;
+  gapSource?: string;
+  isOpen?: boolean;
+  relevance_score_diff?: number;
+  explanation?: string;
+};
+```
+
+---
+
+## UserStoryCitations
+
+```ts
+export type UserStoryCitations = {
+  image_citations?: ImageCitation[];
+  appmod_citations?: TextCitation[];
+  audio_citations?: AudioCitation[];
+  file_citations?: FileCitation[];
+  file_image_data?: ImageCitationsForFile | null;
+  rca_citations?: RcaCitation[];
+  web_citations?: WebCitation[];
+  code_generated?: GeneratedCodeCitation[];
+};
+```
+
+---
+
+## ImageCitationsForFile
+
+```ts
+interface ImageCitationsForFile {
+  [key: string]: FileImageData;
+}
+```
+
+---
+
+## FileImageData
+
+```ts
+interface FileImageData {
+  filename: string;
+  signed_url: string;
+  gs_url: string;
+}
+```
+
+---
+
+# Usage
+
+## Create State
+
+```tsx
+const [userStory, setUserStory] = useState<IUserStory | null>(null);
+
+const [aiReasoning, setAiReasoning] = useState<TAIReasoning[]>([]);
+
+const [citations, setCitations] = useState<UserStoryCitations[]>([]);
+```
+
+---
+
+## Wrap Components
+
+```tsx
+<RequirementAIWrapper
+  userStory={userStory}
+  setUserStory={setUserStory}
+  aiReasoning={aiReasoning}
+  setAiReasoning={setAiReasoning}
+  citations={citations}
+  setCitations={setCitations}
+>
+  {children}
+</RequirementAIWrapper>
+```
+
+---
+
+# Context Value
+
+The wrapper provides the following context value:
+
+```ts
+{
+  (userStory,
+    setUserStory,
+    aiReasoning,
+    setAiReasoning,
+    citations,
+    setCitations);
+}
+```
+
+# Usage
+
+```tsx
+import { useStreamContentHandler } from "@e-llm-studio/citation";
+
+function StreamingComponent() {
+  const { processStreamContent } = useStreamContentHandler({
+    setUserStory,
+    setAiReasoning,
+    setUserStoryCitations,
+    onStreamingCompleted,
+    isGraphQLCallInProgress,
+    knowledgeBase,
+    projectAnalyserSummary,
+    dataSourceFiles,
+    aiReasoning,
+    setRedisValue,
+    fetchCitationByBlock,
+  });
+
+  const handleStream = (blockList) => {
+    processStreamContent(blockList, metadata, "story-artifact-id");
+  };
+
+  return <div>Streaming...</div>;
+}
+```
+
+---
+
+# Hook API
+
+## useStreamContentHandler(props)
+
+### Returns
+
+```ts
+{
+  processStreamContent: (
+    blockList: BlockStreamItem[],
+    customMetadata: any,
+    storyArtifactID: string
+  ) => void
+}
+```
+
+---
+
+# Props
+
+## setUserStory
+
+React state setter used to store generated user stories.
+
+```ts
+React.Dispatch<React.SetStateAction<IUserStory[]>>;
+```
+
+---
+
+## setAiReasoning
+
+State setter used to store extracted AI reasoning.
+
+```ts
+React.Dispatch<React.SetStateAction<TAIReasoning[]>>;
+```
+
+---
+
+## setUserStoryCitations
+
+State setter used to store citations generated from blocks.
+
+```ts
+React.Dispatch<React.SetStateAction<UserStoryCitations>>;
+```
+
+---
+
+## onStreamingCompleted
+
+Callback executed once **all citation generation tasks have completed**.
+
+```ts
+(gap_items_prompt?: string, risk_items_prompt?: string) => Promise<void>;
+```
+
+---
+
+## isGraphQLCallInProgress
+
+Boolean flag indicating whether a GraphQL call is currently running.
+
+This prevents the completion callback from firing prematurely.
+
+```ts
+boolean;
+```
+
+---
+
+## knowledgeBase
+
+Knowledge base metadata associated with the current stream.
+
+```ts
+any;
+```
+
+---
+
+## projectAnalyserSummary
+
+Project analysis summary used during processing.
+
+```ts
+any;
+```
+
+---
+
+## dataSourceFiles
+
+Information about uploaded data source files.
+
+```ts
+{
+  document: string[];
+  image: string[];
+  meetingRecording: string[];
+}
+```
+
+---
+
+## aiReasoning
+
+Existing AI reasoning state.
+
+```ts
+TAIReasoning[]
+```
+
+---
+
+## setRedisValue
+
+Function responsible for storing streaming state in Redis.
+
+```ts
+<T>({ key, value }: SetRedisParams<T>) => Promise<any>;
+```
+
+Example implementation:
+
+```ts
+async function setRedisValue({ key, value }) {
+  await redis.set(key, JSON.stringify(value));
+}
+```
+
+---
+
+## fetchCitationByBlock
+
+Async function responsible for generating citations for a given block.
+
+```ts
+(block: BlockStreamItem, metadata: any, ai_reasonings: TAIReasoning[]) =>
+  Promise<IGetCitationsByBlock>;
+```
+
+---
+
+# Types
+
+## BlockStreamItem
+
+Represents a streamed AI block.
+
+```ts
+type BlockStreamItem = {
+  title: string;
+  section: "intro" | "subfeature";
+  description?: string;
+  blockNumber: string;
+  value: string;
+  storyNumber: string;
+};
+```
+
+---
+
+# Streaming Flow
+
+```
+AI Stream
+   ↓
+Block List
+   ↓
+processStreamContent
+   ↓
+Reasoning Extraction
+   ↓
+User Story Generation
+   ↓
+Citation Generation
+   ↓
+Redis Persistence
+   ↓
+Streaming Completed Callback
+```
+
+---
+
+# Internal Safeguards
+
+The hook includes several mechanisms to optimize streaming performance:
+
+| Mechanism                          | Purpose                                   |
+| ---------------------------------- | ----------------------------------------- |
+| updateCitationCallKeysRef          | Prevents duplicate citation requests      |
+| citationGenerationCompletedKeysRef | Tracks completed citation tasks           |
+| lastProcessedBlockListHashRef      | Avoids reprocessing identical block lists |
+| lastRedisValueRef                  | Prevents redundant Redis writes           |
+
+---
+
+# Best Practices
+
+- Ensure `fetchCitationByBlock` is idempotent.
+- Avoid extremely frequent calls to `processStreamContent` without batching.
+- Always serialize Redis values using JSON.
+
+---
+
+# UserStoryScreen Component
+
+A composable UI component system for displaying and editing user stories with AI reasoning citations. It must be wrapped within `RequirementAIWrapper` to access shared state.
+
+## Quick Demo
+
+```tsx
+import React, { useState } from "react";
+import RequirementAIWrapper from "@e-llm-studio/citation";
+import UserStoryScreen from "@e-llm-studio/citation";
+import UserStoryWithCitations from "@e-llm-studio/citation";
+import RichTextEditor from "@e-llm-studio/citation";
+import AtomicButton from "@e-llm-studio/citation";
+
+function MyStoryApp() {
+  const [userStory, setUserStory] = useState<IUserStory[]>([
+    {
+      artifactId: "story-1",
+      title: "User Login",
+      value: "As a user, I want to login to the system",
+    },
+  ]);
+
+  const [aiReasoning, setAiReasoning] = useState<TAIReasoning[]>([]);
+  const [citations, setCitations] = useState<UserStoryCitations[]>([]);
+
+  return (
+    <RequirementAIWrapper
+      userStory={userStory}
+      setUserStory={setUserStory}
+      aiReasoning={aiReasoning}
+      setAiReasoning={setAiReasoning}
+      citations={citations}
+      setCitations={setCitations}
+      apiCachingConfig={{
+        queryClient: null, // replace with original tanstack-query client
+        useGetSignedUrlQuery: (gsUtilPath: string, cacheKey: string[]) => null, // replace with original hook
+        useGetSignedUrlMutation: (gsUtilPath: string) => null, // replace with original hook
+        useExtractAudioPeaksMutation: () => null, // replace with original hook
+        useExtractAudioPeaksQuery: (gsUtilPath: string, cacheKey: string[]) => null, // replace with original hook
+        useGetVideoSignedUrlMutation: (gsUtilPath: string) => null, // replace with original hook
+        useGetVideoSignedUrlQuery: (gsUtilPath: string, cacheKey: string[]) => null, // replace with original hook
+      }}
+    >
+      <UserStoryScreen scenario="ready" isCitationLoadingNotStarted={true}>
+        <UserStoryScreen.Content AtomicButton={AtomicButton}>
+          <UserStoryScreen.Body>
+            <UserStoryScreen.Story Component={UserStoryWithCitations} />
+            <UserStoryScreen.Editor Component={RichTextEditor} />
+            <UserStoryScreen.SubFeatures />
+          </UserStoryScreen.Body>
+          <UserStoryScreen.ScrollButton />
+        </UserStoryScreen.Content>
+      </UserStoryScreen>
+    </RequirementAIWrapper>
+  );
+}
+```
+
+## Core Sub-Components
+
+| Component                       | Purpose                                               |
+| ------------------------------- | ----------------------------------------------------- |
+| `UserStoryScreen.Sidebar`       | Navigation sidebar for story selection                |
+| `UserStoryScreen.SidebarToggle` | Collapse/expand sidebar button                        |
+| `UserStoryScreen.Content`       | Main content wrapper with header and controls         |
+| `UserStoryScreen.Body`          | Container for Story/Editor (handles mutual exclusion) |
+| `UserStoryScreen.Story`         | Displays selected story with citations (read mode)    |
+| `UserStoryScreen.Editor`        | Rich text editor for editing stories (edit mode)      |
+| `UserStoryScreen.SubFeatures`   | Accordion for nested sub-features                     |
+| `UserStoryScreen.ScrollButton`  | Floating button to scroll to bottom                   |
+
+## Root Props
+
+```ts
+interface UserStoryScreenProps {
+  scenario: "streaming" | "ready"; // "streaming" for real-time, "ready" for static
+  isCitationLoadingNotStarted: boolean; // Flag for citation loading state
+  children: React.ReactNode; // Sub-components
+  classNames?: UserStoryScreenClassNames; // Optional custom CSS classes
+}
+```
+
+## Key Features
+
+- **Automatic State Management**: All components pull from `RequirementAIWrapper` context
+- **Mutual Exclusion**: Story and Editor views are automatically exclusive
+- **Streaming Support**: Real-time updates with skeleton loaders
+- **Citation Integration**: AI reasoning and citations highlighted in stories
+- **Markdown Support**: Stories support markdown formatting with custom tags
+
+## Usage Notes
+
+1. **Always wrap with `RequirementAIWrapper`** - Provides context for all sub-components
+2. **Use `Body` wrapper** - Ensures proper Story/Editor mutual exclusion
+3. **Pass custom components** - Story and Editor expect React components as props
+4. **Set scenario correctly** - "streaming" for real-time data, "ready" for static content
+
+---
+
+# UserStoryApprovalScreen Component
+
+A dedicated approval workflow component for reviewing and approving AI-generated user stories. It must be wrapped within `RequirementAIWrapper` to access shared state.
+
+## Overview
+
+UserStoryApprovalScreen provides a structured interface for:
+
+- Reviewing generated user stories segment-by-segment
+- Editing individual content segments
+- Approving content progressively
+- Managing sub-features with delete capabilities
+- Bulk approval with "Approve All" functionality
+
+## Quick Demo
+
+```tsx
+import React, { useState } from "react";
+import RequirementAIWrapper from "@e-llm-studio/citation";
+import UserStoryApprovalScreen from "@e-llm-studio/citation";
+import UserStoryWithCitations from "@e-llm-studio/citation";
+import RichTextEditor from "@e-llm-studio/citation";
+import AtomicButton from "@e-llm-studio/citation";
+
+function MyApprovalFlow() {
+  const [userStory, setUserStory] = useState<IUserStory[]>([]);
+  const [aiReasoning, setAiReasoning] = useState<TAIReasoning[]>([]);
+  const [citations, setCitations] = useState<UserStoryCitations[]>([]);
+
+  return (
+    <RequirementAIWrapper
+      userStory={userStory}
+      setUserStory={setUserStory}
+      aiReasoning={aiReasoning}
+      setAiReasoning={setAiReasoning}
+      citations={citations}
+      setCitations={setCitations}
+      apiCachingConfig={{
+        queryClient: null, // replace with original tanstack-query client
+        useGetSignedUrlQuery: (gsUtilPath: string, cacheKey: string[]) => null, // replace with original hook
+        useGetSignedUrlMutation: (gsUtilPath: string) => null, // replace with original hook
+        useExtractAudioPeaksMutation: () => null, // replace with original hook
+        useExtractAudioPeaksQuery: (gsUtilPath: string, cacheKey: string[]) => null, // replace with original hook
+        useGetVideoSignedUrlMutation: (gsUtilPath: string) => null, // replace with original hook
+        useGetVideoSignedUrlQuery: (gsUtilPath: string, cacheKey: string[]) => null, // replace with original hook
+      }}
+    >
+      <UserStoryApprovalScreen
+        artifactTitleIds={["STORY-001"]}
+        config={{
+          showApproveAllButton: true,
+          allowEditing: true,
+          allowDeletion: true,
+          containerHeight: "calc(100vh - 100px)",
+        }}
+        callbacks={{
+          onShowNotification: (type, title, message) => {
+            console.log(`[${type}] ${title}: ${message}`);
+          },
+          onInitialize: () => {
+            console.log("Approval screen initialized");
+          },
+          onSaveState: async (stories) => {
+            await saveToRedis(stories);
+          },
+          onAllApproved: async (stories) => {
+            await submitApprovedStories(stories);
+          },
+        }}
+      >
+        <UserStoryApprovalScreen.Content ButtonComponent={AtomicButton}>
+          <UserStoryApprovalScreen.Body
+            EditorComponent={RichTextEditor}
+            ViewerComponent={UserStoryWithCitations}
+          />
+        </UserStoryApprovalScreen.Content>
+      </UserStoryApprovalScreen>
+    </RequirementAIWrapper>
+  );
+}
+```
+
+## Component Structure
+
+| Component                         | Purpose                                                   |
+| --------------------------------- | --------------------------------------------------------- |
+| `UserStoryApprovalScreen` (Root)  | Container with approval state management                  |
+| `UserStoryApprovalScreen.Content` | Header with title, metadata, and "Approve All" button     |
+| `UserStoryApprovalScreen.Body`    | Renders content segments with edit/approve/delete actions |
+
+---
+
+## Root Component Props
+
+```ts
+interface UserStoryApprovalScreenProps {
+  artifactTitleIds: string[]; // Display IDs for each story
+  config?: UserStoryApprovalScreenConfig; // Feature toggles
+  callbacks?: UserStoryApprovalScreenCallbacks; // Platform-specific handlers
+  labels?: Partial<UserStoryApprovalScreenLabels>; // Custom text labels
+  isDisabled?: boolean; // Disable all interactions
+  children: React.ReactNode; // Sub-components
+  classNames?: UserStoryApprovalScreenClassNames; // Custom CSS classes
+}
+```
+
+## Configuration Options
+
+```ts
+interface UserStoryApprovalScreenConfig {
+  showApproveAllButton?: boolean; // Show/hide "Approve All" button (default: true)
+  allowEditing?: boolean; // Enable editing segments (default: true)
+  allowDeletion?: boolean; // Enable deleting sub-features (default: true)
+  showSidebar?: boolean; // Show sidebar for multi-story navigation (default: false)
+  containerHeight?: string; // CSS height value (default: "calc(100vh - 100px)")
+  useFullWidth?: boolean; // Use 100% width without margins (default: false)
+}
+```
+
+## Callback Handlers
+
+```ts
+interface UserStoryApprovalScreenCallbacks {
+  /** Show toast/notification - required for user feedback */
+  onShowNotification?: (
+    type: "success" | "error" | "warn" | "info",
+    title: string,
+    message: string,
+    duration?: number,
+  ) => void;
+
+  /** Initialize platform (e.g., adjust chat width in web app) */
+  onInitialize?: () => void;
+
+  /** Persist approval state to Redis/storage */
+  onSaveState?: (stories: IUserStoryForApproval[]) => Promise<void>;
+
+  /** Triggered when all stories are approved */
+  onAllApproved?: (stories: IUserStoryForApproval[]) => Promise<void>;
+
+  /** Custom scroll behavior for focusing segments */
+  onScrollToElement?: (element: HTMLElement) => void;
+}
+```
+
+## Accessing Context
+
+Use `useRequirementAI()` hook within UserStoryScreen components:
+
+```tsx
+import { useRequirementAI } from "@e-llm-studio/citation";
+
+function MyCustomComponent() {
+  const { userStory, setUserStory, aiReasoning } = useRequirementAI();
+  return <div>{userStory?.[0]?.title}</div>;
+}
+```
+
+For detailed documentation, see [USERSTORYSCREEN_GUIDE.md](../../docs/USERSTORYSCREEN_GUIDE.md)
+
+```
+
+```
+
+
+## Development & Contribution
+
+Contributions are welcome! This guide walks you through making changes to the citation library.
+
+### Prerequisites
+
+- **Node.js & npm** installed
+- **Git** installed
+- Basic familiarity with Git and the command line
+
+### Development Setup
+
+1. **Fork & Clone the Repository**
+ ```bash
+ git clone https://github.com/<your-username>/citation.git
+ cd citation
+ ```
+
+2. **Install Dependencies**
+ ```bash
+ npm install
+ ```
+
+3. **Link the Library Locally** (Optional - for testing before publishing)
+ ```bash
+ git checkout -b my-change-branch
+ npm link
+ 
+ # In your test project folder
+ npm link @e-llm-studio/citation
+ ```
+
+4. **Build the Library**
+ ```bash
+ npm run build
+ ```
+
+5. **Test Locally**
+ - Start or build your test project to verify changes work as expected
+ - Ensure all existing tests pass
+
+### Making Changes
+
+- Edit source files in the `src/` directory
+- Add or update tests as needed
+- Follow the existing code style and formatting guidelines
+- Ensure your changes are well-documented with comments
+
+### Submitting Changes
+
+1. **Commit Your Changes**
+ ```bash
+ git add .
+ git commit -m "fix: describe your change"
+ git push origin my-change-branch
+ ```
+
+2. **Submit a Pull Request**
+ - Open a pull request on GitHub with a clear description of your changes
+ - Reference any related issues
+ - Ensure all tests pass before submitting
+
+### Versioning
+
+When publishing updates, follow [Semantic Versioning](https://semver.org/):
+
+```bash
+npm version patch # for bug fixes
+npm version minor # for new features
+npm version major # for breaking changes
+```
+
+For more details, refer to the [npm version documentation](https://docs.npmjs.com/cli/v8/commands/npm-version).
+
+### Publishing to npm
+
+> Ensure you have npm account permissions and are on the correct branch.
+
+```bash
+npm login
+npm publish --access public
+```
+
+After publishing, verify the package:
+
+```bash
+npm unlink @e-llm-studio/citation
+npm install @e-llm-studio/citation@latest
+```
+
+### Additional Tips
+
+- Use `npm pack` to generate a `.tgz` and test installation before publishing
+- Open a Pull Request when ready for review
+- We appreciate your help in improving the citation library through bug fixes, feature enhancements, and documentation improvements
+
+---
+
+## License
+
+This library is released under the MIT License. See the LICENSE file for more details.
+
+The license information is also available in the `citation/package.json` file under the 'license' field.