titaned-frontend-library 1.0.1

package/CHANGELOG.md

@@ -0,0 +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

package/MEILISEARCH_INTEGRATION.md

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,236 @@
+# TitanEd Library
+
+Internal React TypeScript component library for TitanEd applications, featuring modern UI components with built-in search functionality and responsive design.
+
+## Features
+
+- 🎨 **Modern UI Components** - Pre-built, customizable React components
+- 🔍 **Integrated Search** - MeiliSearch integration with search highlighting
+- 📱 **Responsive Design** - Mobile-first approach with responsive breakpoints
+- 🎯 **TypeScript Support** - Full TypeScript definitions and type safety
+- 🎨 **SCSS Styling** - Customizable styles with SCSS support
+- 🧩 **Modular Architecture** - Tree-shakeable components for optimal bundle size
+
+## Installation
+
+### Clone the Repository
+
+```bash
+git clone https://github.com/TitanEd/titaned-frontend-libraries.git
+cd titaned-frontend-libraries
+npm install
+```
+
+### Peer Dependencies
+
+Make sure you have the required peer dependencies installed in your project:
+
+```bash
+npm install react react-dom @openedx/paragon @edx/frontend-platform meilisearch sass
+```
+
+## Quick Start
+
+```tsx
+import React from 'react';
+import { 
+  MainHeader, 
+  Sidebar, 
+  Footer, 
+  SidebarProvider,
+  useSidebar 
+} from 'titaned-lib';
+
+function App() {
+  return (
+    <SidebarProvider>
+      <div className="app">
+        <MainHeader />
+        <Sidebar />
+        <main>
+          {/* Your content */}
+        </main>
+        <Footer />
+      </div>
+    </SidebarProvider>
+  );
+}
+
+export default App;
+```
+
+## Components
+
+### MainHeader
+A responsive header component with integrated search functionality.
+
+```tsx
+import { MainHeader, SimpleSearchProvider } from 'titaned-lib';
+
+const searchConfig = {
+  host: 'https://your-meilisearch-host.com',
+  apiKey: 'your-api-key',
+  indexName: 'your-index'
+};
+
+function App() {
+  return (
+    <SimpleSearchProvider config={searchConfig}>
+      <MainHeader 
+        title="Your App"
+        onSearch={(query) => console.log('Search:', query)}
+      />
+    </SimpleSearchProvider>
+  );
+}
+```
+
+### Sidebar
+A collapsible sidebar component with mobile support.
+
+```tsx
+import { Sidebar, SidebarProvider, useSidebar } from 'titaned-lib';
+
+function SidebarContent() {
+  const { isOpen, toggle } = useSidebar();
+  
+  return (
+    <Sidebar>
+      <nav>
+        <a href="/dashboard">Dashboard</a>
+        <a href="/courses">Courses</a>
+        <a href="/profile">Profile</a>
+      </nav>
+    </Sidebar>
+  );
+}
+
+function App() {
+  return (
+    <SidebarProvider>
+      <SidebarContent />
+    </SidebarProvider>
+  );
+}
+```
+
+### Footer
+A customizable footer component.
+
+```tsx
+import { Footer } from 'titaned-lib';
+
+function App() {
+  return (
+    <Footer 
+      copyright="© 2024 TitanEd"
+      links={[
+        { label: 'Privacy Policy', href: '/privacy' },
+        { label: 'Terms of Service', href: '/terms' }
+      ]}
+    />
+  );
+}
+```
+
+## Styling
+
+The library includes global SCSS styles that are automatically imported. You can override styles by targeting the component classes:
+
+```scss
+// Override global styles
+.titaned-lib {
+  --primary-color: #your-color;
+  --secondary-color: #your-color;
+}
+
+// Override specific component styles
+.main-header {
+  background-color: var(--primary-color);
+}
+```
+
+## TypeScript Support
+
+All components come with full TypeScript definitions:
+
+```tsx
+import type { 
+  MainHeaderProps, 
+  MeiliSearchConfig,
+  SearchResult 
+} from 'titaned-lib';
+
+interface MyComponentProps {
+  headerConfig: MainHeaderProps;
+  searchConfig: MeiliSearchConfig;
+}
+```
+
+## API Reference
+
+### Hooks
+
+#### `useSidebar()`
+Returns sidebar state and controls.
+
+```tsx
+const { isOpen, toggle, close, open } = useSidebar();
+```
+
+#### `useSimpleSearch()`
+Provides search functionality and state.
+
+```tsx
+const { 
+  searchQuery, 
+  searchResults, 
+  isSearching, 
+  performSearch 
+} = useSimpleSearch();
+```
+
+### Types
+
+- `MainHeaderProps` - Props for the MainHeader component
+- `MeiliSearchConfig` - Configuration for MeiliSearch integration
+- `SearchResult` - Structure of search result items
+
+## Development
+
+### Prerequisites
+- Node.js 18+
+- npm or yarn
+- Access to the private repository
+
+### Setup
+```bash
+git clone https://github.com/TitanEd/titaned-frontend-libraries.git
+cd titaned-lib
+npm install
+```
+
+### Build
+```bash
+npm run build
+```
+
+### Development
+```bash
+npm run dev
+```
+
+## Internal Team Guidelines
+
+- Follow the established coding standards and patterns
+- Update CHANGELOG.md when making significant changes
+- Coordinate with the team for breaking changes
+
+
+## Support
+
+For support and questions, contact the development team directly.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a list of changes and version history.