titaned-frontend-library 1.0.16 → 1.0.18

package/CHANGELOG.md

@@ -1,43 +1,43 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-### Added
-- Initial release of TitanEd Library
-- MainHeader component with search functionality
-- Sidebar component with responsive design
-- Footer component
-- SidebarProvider and useSidebar hook
-- SimpleSearchProvider and useSimpleSearch hook
-- MeiliSearch integration
-- TypeScript support with full type definitions
-- SCSS styling support
-- Global style overrides
-
-### Changed
-- Nothing yet
-
-### Deprecated
-- Nothing yet
-
-### Removed
-- Nothing yet
-
-### Fixed
-- Nothing yet
-
-### Security
-- Nothing yet
-
-## [0.0.134] - 2024-01-XX
-
-### Added
-- Initial version with core components
-- Basic TypeScript setup
-- Vite build configuration
-- SCSS support with static copying
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial release of TitanEd Library
+- MainHeader component with search functionality
+- Sidebar component with responsive design
+- Footer component
+- SidebarProvider and useSidebar hook
+- SimpleSearchProvider and useSimpleSearch hook
+- MeiliSearch integration
+- TypeScript support with full type definitions
+- SCSS styling support
+- Global style overrides
+
+### Changed
+- Nothing yet
+
+### Deprecated
+- Nothing yet
+
+### Removed
+- Nothing yet
+
+### Fixed
+- Nothing yet
+
+### Security
+- Nothing yet
+
+## [0.0.134] - 2024-01-XX
+
+### Added
+- Initial version with core components
+- Basic TypeScript setup
+- Vite build configuration
+- SCSS support with static copying

package/MEILISEARCH_INTEGRATION.md

@@ -1,261 +1,261 @@
-# MeiliSearch Integration for TitanEd Library
-
-This document explains how to use the MeiliSearch integration in the TitanEd library's MainHeader component.
-
-## Overview
-
-The MainHeader component now supports MeiliSearch integration for content searching. It uses the exact API payload structure from your Open edX authoring console logs, making it compatible with your existing MeiliSearch setup.
-
-## Features
-
-- **Real-time Search**: Search as you type with MeiliSearch API
-- **Search Results Display**: Shows search results in a dropdown with highlighting
-- **Mobile Support**: Full mobile search modal with results
-- **Error Handling**: Proper error states and loading indicators
-- **Faceted Search**: Supports MeiliSearch facets for advanced filtering
-- **Highlighting**: Search term highlighting in results
-
-## Configuration
-
-### Required Props
-
-The MainHeader component now requires a `meiliSearchConfig` prop:
-
-```typescript
-interface MeiliSearchConfig {
-  host: string;        // MeiliSearch server URL
-  apiKey: string;      // MeiliSearch API key
-  indexName: string;   // Index name (e.g., 'tutor_studio_content')
-}
-```
-
-### Example Usage
-
-```tsx
-import MainHeader from 'titaned-lib';
-import { MeiliSearchConfig } from 'titaned-lib';
-
-const meiliSearchConfig: MeiliSearchConfig = {
-  host: 'http://meilisearch.local.openedx.io:7700',
-  apiKey: 'your-api-key-here',
-  indexName: 'tutor_studio_content'
-};
-
-<MainHeader
-  logoUrl="/path/to/logo.png"
-  menuAlignment="left"
-  menuList={menuList}
-  loginSignupButtons={false}
-  authenticatedUser={user}
-  userMenuItems={userMenuItems}
-  onLanguageChange={handleLanguageChange}
-  getBaseUrl={() => '/'}
-  onSearchResults={handleSearchResults}
-  meiliSearchConfig={meiliSearchConfig}
-  headerButtons={headerButtons}
-/>
-```
-
-## API Integration
-
-The integration uses the exact payload structure from your console logs:
-
-### Search Payload
-```json
-{
-  "queries": [
-    {
-      "indexUid": "tutor_studio_content",
-      "q": "search query",
-      "filter": [[], "type = \"course_block\""],
-      "attributesToHighlight": ["display_name", "description", "published"],
-      "highlightPreTag": "__meili-highlight__",
-      "highlightPostTag": "__/meili-highlight__",
-      "attributesToCrop": ["description", "published"],
-      "sort": [],
-      "offset": 0,
-      "limit": 20
-    },
-    {
-      "indexUid": "tutor_studio_content",
-      "facets": ["block_type", "content.problem_types"],
-      "filter": ["type = \"course_block\""],
-      "limit": 0
-    }
-  ]
-}
-```
-
-### Headers and Authentication
-
-The service automatically includes all necessary headers for MeiliSearch API calls:
-
-```typescript
-{
-  'Content-Type': 'application/json',
-  'Authorization': 'Bearer your-api-key-here',
-  'X-Meilisearch-Client': 'Meilisearch JavaScript (v0.41.0)'
-}
-```
-
-**Important**: When you pass the complete MeiliSearch client object (recommended), the service will automatically extract and use the exact headers from your client, ensuring compatibility with your existing setup.
-
-### Response Handling
-
-The component handles MeiliSearch responses and converts them to a consistent format:
-
-```typescript
-interface MeiliSearchResult {
-  id: string;
-  display_name: string;
-  type: string;
-  description?: string;
-  published?: string;
-  url?: string;
-  block_type?: string;
-  content?: {
-    problem_types?: string[];
-  };
-  _formatted?: {
-    display_name?: string;
-    description?: string;
-    published?: string;
-  };
-}
-```
-
-## Search Results Display
-
-### Desktop
-- Results appear in a dropdown below the search field
-- Shows up to 5 results with "show more" indicator
-- Includes highlighting for search terms
-- Displays result type and metadata
-
-### Mobile
-- Full-screen search modal
-- Scrollable results list
-- Same highlighting and metadata as desktop
-
-## Styling
-
-The component includes comprehensive CSS for:
-- Search result dropdowns
-- Loading states
-- Error messages
-- Mobile search modal
-- Result highlighting
-
-All styles are included in `MainHeader.scss` and follow the existing design system.
-
-## Error Handling
-
-The component handles various error states:
-- Network errors
-- API errors
-- Empty results
-- Loading states
-
-Error messages are displayed to users with appropriate styling.
-
-## Integration with Open edX Authoring
-
-To use this in your Open edX authoring repository:
-
-1. **Install the library**:
-   ```bash
-   npm install titaned-lib
-   ```
-
-2. **Import and configure** (Recommended approach - pass the complete client):
-   ```tsx
-   import { MainHeader } from 'titaned-lib';
-   import { useContentSearchConnection } from './your-search-hook';
-
-   const MyComponent = () => {
-     const { client, indexName, hasConnectionError } = useContentSearchConnection();
-     
-     const meiliSearchConfig = {
-       host: client.config.host,
-       apiKey: client.config.apiKey,
-       indexName: indexName,
-       client: client // Pass the complete client for automatic header extraction
-     };
-
-     return (
-       <MainHeader
-         // ... other props
-         meiliSearchConfig={meiliSearchConfig}
-         onSearchResults={(results, totalHits, facets) => {
-           // Handle search results
-           console.log('Search results:', results);
-         }}
-       />
-     );
-   };
-   ```
-
-3. **Alternative approach - Manual header configuration**:
-   ```tsx
-   const meiliSearchConfig = {
-     host: 'http://meilisearch.local.openedx.io:7700',
-     apiKey: 'your-api-key-here',
-     indexName: 'tutor_studio_content'
-     // Headers will be automatically set based on the API key
-   };
-   ```
-
-## Advanced Features
-
-### Faceted Search
-The component supports MeiliSearch facets for advanced filtering. Facets are available in the `onSearchResults` callback:
-
-```tsx
-onSearchResults={(results, totalHits, facets) => {
-  console.log('Facets:', facets);
-  // facets.block_type: { "chapter": 4, "problem": 6, ... }
-  // facets['content.problem_types']: { "multiplechoiceresponse": 1, ... }
-}}
-```
-
-### Custom Search Options
-You can customize search behavior by modifying the `MeiliSearchService`:
-
-```typescript
-// In meiliSearchService.ts
-const result = await searchService.search(query, {
-  limit: 20,
-  offset: 0,
-  filter: ['type = "course_block"', 'published = true'],
-  attributesToHighlight: ['display_name', 'description'],
-  sort: ['published:desc']
-});
-```
-
-## Troubleshooting
-
-### Common Issues
-
-1. **CORS Errors**: Ensure your MeiliSearch server allows CORS from your domain
-2. **API Key Issues**: Verify the API key has proper permissions
-3. **Index Not Found**: Check that the index name matches your MeiliSearch setup
-4. **Network Errors**: Verify the host URL is accessible
-
-### Debug Mode
-
-Enable debug logging by checking the browser console. The component logs:
-- Search queries
-- API responses
-- Error messages
-- Performance metrics
-
-## Migration from Simple Search
-
-If you're migrating from the simple search implementation:
-
-1. Update your MainHeader props to include `meiliSearchConfig`
-2. Remove any custom search logic
-3. Update your `onSearchResults` callback to handle the new result format
-4. Test with your MeiliSearch setup
-
-The component maintains backward compatibility for other props and functionality.
+# MeiliSearch Integration for TitanEd Library
+
+This document explains how to use the MeiliSearch integration in the TitanEd library's MainHeader component.
+
+## Overview
+
+The MainHeader component now supports MeiliSearch integration for content searching. It uses the exact API payload structure from your Open edX authoring console logs, making it compatible with your existing MeiliSearch setup.
+
+## Features
+
+- **Real-time Search**: Search as you type with MeiliSearch API
+- **Search Results Display**: Shows search results in a dropdown with highlighting
+- **Mobile Support**: Full mobile search modal with results
+- **Error Handling**: Proper error states and loading indicators
+- **Faceted Search**: Supports MeiliSearch facets for advanced filtering
+- **Highlighting**: Search term highlighting in results
+
+## Configuration
+
+### Required Props
+
+The MainHeader component now requires a `meiliSearchConfig` prop:
+
+```typescript
+interface MeiliSearchConfig {
+  host: string;        // MeiliSearch server URL
+  apiKey: string;      // MeiliSearch API key
+  indexName: string;   // Index name (e.g., 'tutor_studio_content')
+}
+```
+
+### Example Usage
+
+```tsx
+import MainHeader from 'titaned-lib';
+import { MeiliSearchConfig } from 'titaned-lib';
+
+const meiliSearchConfig: MeiliSearchConfig = {
+  host: 'http://meilisearch.local.openedx.io:7700',
+  apiKey: 'your-api-key-here',
+  indexName: 'tutor_studio_content'
+};
+
+<MainHeader
+  logoUrl="/path/to/logo.png"
+  menuAlignment="left"
+  menuList={menuList}
+  loginSignupButtons={false}
+  authenticatedUser={user}
+  userMenuItems={userMenuItems}
+  onLanguageChange={handleLanguageChange}
+  getBaseUrl={() => '/'}
+  onSearchResults={handleSearchResults}
+  meiliSearchConfig={meiliSearchConfig}
+  headerButtons={headerButtons}
+/>
+```
+
+## API Integration
+
+The integration uses the exact payload structure from your console logs:
+
+### Search Payload
+```json
+{
+  "queries": [
+    {
+      "indexUid": "tutor_studio_content",
+      "q": "search query",
+      "filter": [[], "type = \"course_block\""],
+      "attributesToHighlight": ["display_name", "description", "published"],
+      "highlightPreTag": "__meili-highlight__",
+      "highlightPostTag": "__/meili-highlight__",
+      "attributesToCrop": ["description", "published"],
+      "sort": [],
+      "offset": 0,
+      "limit": 20
+    },
+    {
+      "indexUid": "tutor_studio_content",
+      "facets": ["block_type", "content.problem_types"],
+      "filter": ["type = \"course_block\""],
+      "limit": 0
+    }
+  ]
+}
+```
+
+### Headers and Authentication
+
+The service automatically includes all necessary headers for MeiliSearch API calls:
+
+```typescript
+{
+  'Content-Type': 'application/json',
+  'Authorization': 'Bearer your-api-key-here',
+  'X-Meilisearch-Client': 'Meilisearch JavaScript (v0.41.0)'
+}
+```
+
+**Important**: When you pass the complete MeiliSearch client object (recommended), the service will automatically extract and use the exact headers from your client, ensuring compatibility with your existing setup.
+
+### Response Handling
+
+The component handles MeiliSearch responses and converts them to a consistent format:
+
+```typescript
+interface MeiliSearchResult {
+  id: string;
+  display_name: string;
+  type: string;
+  description?: string;
+  published?: string;
+  url?: string;
+  block_type?: string;
+  content?: {
+    problem_types?: string[];
+  };
+  _formatted?: {
+    display_name?: string;
+    description?: string;
+    published?: string;
+  };
+}
+```
+
+## Search Results Display
+
+### Desktop
+- Results appear in a dropdown below the search field
+- Shows up to 5 results with "show more" indicator
+- Includes highlighting for search terms
+- Displays result type and metadata
+
+### Mobile
+- Full-screen search modal
+- Scrollable results list
+- Same highlighting and metadata as desktop
+
+## Styling
+
+The component includes comprehensive CSS for:
+- Search result dropdowns
+- Loading states
+- Error messages
+- Mobile search modal
+- Result highlighting
+
+All styles are included in `MainHeader.scss` and follow the existing design system.
+
+## Error Handling
+
+The component handles various error states:
+- Network errors
+- API errors
+- Empty results
+- Loading states
+
+Error messages are displayed to users with appropriate styling.
+
+## Integration with Open edX Authoring
+
+To use this in your Open edX authoring repository:
+
+1. **Install the library**:
+   ```bash
+   npm install titaned-lib
+   ```
+
+2. **Import and configure** (Recommended approach - pass the complete client):
+   ```tsx
+   import { MainHeader } from 'titaned-lib';
+   import { useContentSearchConnection } from './your-search-hook';
+
+   const MyComponent = () => {
+     const { client, indexName, hasConnectionError } = useContentSearchConnection();
+     
+     const meiliSearchConfig = {
+       host: client.config.host,
+       apiKey: client.config.apiKey,
+       indexName: indexName,
+       client: client // Pass the complete client for automatic header extraction
+     };
+
+     return (
+       <MainHeader
+         // ... other props
+         meiliSearchConfig={meiliSearchConfig}
+         onSearchResults={(results, totalHits, facets) => {
+           // Handle search results
+           console.log('Search results:', results);
+         }}
+       />
+     );
+   };
+   ```
+
+3. **Alternative approach - Manual header configuration**:
+   ```tsx
+   const meiliSearchConfig = {
+     host: 'http://meilisearch.local.openedx.io:7700',
+     apiKey: 'your-api-key-here',
+     indexName: 'tutor_studio_content'
+     // Headers will be automatically set based on the API key
+   };
+   ```
+
+## Advanced Features
+
+### Faceted Search
+The component supports MeiliSearch facets for advanced filtering. Facets are available in the `onSearchResults` callback:
+
+```tsx
+onSearchResults={(results, totalHits, facets) => {
+  console.log('Facets:', facets);
+  // facets.block_type: { "chapter": 4, "problem": 6, ... }
+  // facets['content.problem_types']: { "multiplechoiceresponse": 1, ... }
+}}
+```
+
+### Custom Search Options
+You can customize search behavior by modifying the `MeiliSearchService`:
+
+```typescript
+// In meiliSearchService.ts
+const result = await searchService.search(query, {
+  limit: 20,
+  offset: 0,
+  filter: ['type = "course_block"', 'published = true'],
+  attributesToHighlight: ['display_name', 'description'],
+  sort: ['published:desc']
+});
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **CORS Errors**: Ensure your MeiliSearch server allows CORS from your domain
+2. **API Key Issues**: Verify the API key has proper permissions
+3. **Index Not Found**: Check that the index name matches your MeiliSearch setup
+4. **Network Errors**: Verify the host URL is accessible
+
+### Debug Mode
+
+Enable debug logging by checking the browser console. The component logs:
+- Search queries
+- API responses
+- Error messages
+- Performance metrics
+
+## Migration from Simple Search
+
+If you're migrating from the simple search implementation:
+
+1. Update your MainHeader props to include `meiliSearchConfig`
+2. Remove any custom search logic
+3. Update your `onSearchResults` callback to handle the new result format
+4. Test with your MeiliSearch setup
+
+The component maintains backward compatibility for other props and functionality.