@taruvi/navkit 0.0.1

package/README.md

@@ -0,0 +1,757 @@
+# Taruvi Navkit
+
+A modern, responsive, and highly performant navigation bar component library for the Taruvi ecosystem. Built with React 19, TypeScript, and Material-UI with automatic optimizations via React Compiler.
+
+[![React](https://img.shields.io/badge/React-19.1.1-blue)](https://react.dev/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9.3-blue)](https://www.typescriptlang.org/)
+[![Vite](https://img.shields.io/badge/Vite-7.1.7-646CFF)](https://vite.dev/)
+[![Material-UI](https://img.shields.io/badge/MUI-v5-007FFF)](https://mui.com/)
+
+## Features
+
+### Core Components
+
+- **App Launcher**: Grid-based application launcher with real-time search and filtering
+- **Smart Shortcuts**: Quick access shortcuts with responsive desktop/mobile views and hamburger menu on mobile
+- **User Profile**: Avatar-based profile menu with preferences access and logout functionality
+- **Mattermost Chat Integration**: Embedded chat modal with JWT authentication and external link option
+- **Click-Outside Detection**: Intelligent menu closing with mutually exclusive dropdown behavior
+
+### Technical Highlights
+
+- **Responsive Design**: Mobile-first approach with strategic breakpoints (900px for desktop)
+- **Smart Navigation**: Context-aware navigation system (desk mode vs external mode)
+- **Type-Safe**: Full TypeScript support with strict mode enabled
+- **Optimized Performance**: React Compiler with automatic memoization + manual optimizations
+- **Modern React**: Leverages React 19 features (startTransition, concurrent rendering)
+- **Design System**: Centralized design tokens for consistent theming
+- **Accessibility**: MUI components with built-in ARIA attributes and keyboard navigation
+
+## Quick Start
+
+### Installation
+
+```bash
+# Clone or add as dependency
+npm install @taruvi/navkit
+
+# Install peer dependencies
+npm install @mui/material @emotion/react @emotion/styled
+npm install @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons @fortawesome/free-regular-svg-icons @fortawesome/react-fontawesome
+```
+
+### Basic Setup
+
+```tsx
+import Navkit from '@taruvi/navkit'
+import { TaruviClient } from '@taruvi-io/sdk'
+
+function App() {
+  const client = new TaruviClient({
+    apiUrl: 'https://api.taruvi.io',
+    // ... other config
+  })
+
+  return <Navkit client={client} />
+}
+
+export default App
+```
+
+## Development
+
+### Development Scripts
+
+```bash
+# Start development server with HMR (Hot Module Replacement)
+npm run dev
+
+# Build for production (TypeScript check + Vite build)
+npm run build
+
+# Preview production build locally
+npm run preview
+
+# Run ESLint for code quality
+npm run lint
+
+# Test Mattermost integration in isolation
+npm run test:mattermost
+```
+
+### Development Workflow
+
+1. **Make changes** to source files in `src/`
+2. **See updates instantly** with Vite's Fast Refresh (HMR)
+3. **Type-check** automatically via TypeScript in your IDE
+4. **Lint before commit** with `npm run lint`
+5. **Build before deploy** with `npm run build`
+
+## Usage
+
+### Integration Patterns
+
+#### Standalone App Integration
+
+```tsx
+import Navkit from '@taruvi/navkit'
+import { TaruviClient } from '@taruvi-io/sdk'
+
+function App() {
+  const client = new TaruviClient({
+    apiUrl: process.env.VITE_API_URL,
+    tenantId: process.env.VITE_TENANT_ID,
+  })
+
+  return (
+    <>
+      <Navkit client={client} />
+      <main>{/* Your app content */}</main>
+    </>
+  )
+}
+```
+
+#### Taruvi Desk Integration
+
+```tsx
+import Navkit from '@taruvi/navkit'
+import { useDesk } from '@taruvi-io/desk-sdk'
+
+function DeskApp() {
+  const { client } = useDesk()
+
+  return <Navkit client={client} />
+}
+```
+
+### Client Object Requirements
+
+The `client` prop expects an object compatible with `@taruvi-io/sdk` that provides:
+
+- **User** class for user data and apps
+  - `getApps()`: Fetch available applications
+  - `getData()`: Fetch user profile data (fullName, pfp, username, email)
+
+- **Settings** class for site configuration
+  - `get()`: Fetch site settings (logo, frontendUrl, mattermostUrl, shortcuts)
+
+- **Auth** class for authentication
+  - `isUserAuthenticated()`: Check authentication status
+  - JWT token management (future)
+
+## Architecture
+
+### Component Structure
+
+```
+Navkit (App.tsx)
+├── NavkitProvider (NavkitContext) - React Context for global state
+│   ├── State: appsList, userData, isUserAuthenticated, jwtToken, isDesk
+│   ├── Refs: siteSettings, user, settings (SDK instances)
+│   └── Functions: navigateToUrl, getData, authenticateUser
+├── NavkitContent - Main UI component
+    ├── AppLauncher - App grid with search
+    ├── Profile - User avatar and name
+    │   └── ProfileMenu - Preferences and logout
+    ├── Shortcuts - Quick action icons
+    │   └── ShortcutsMenu - Mobile dropdown
+    └── MattermostChat - Chat modal
+```
+
+### State Management
+
+Navkit uses React Context API for centralized state management:
+
+- **NavigationContext** - Centralized provider for all app state and navigation logic
+- **useNavigation hook** - Custom hook for consuming context in child components
+- **Separate state variables** for granular updates (reduces unnecessary re-renders)
+- **useRef for SDK instances** and siteSettings to prevent re-renders
+- **startTransition** for batching multiple state updates on initial load (6+ renders → 1 render)
+- **BroadcastChannel** for cross-tab synchronization (refreshes on profile updates)
+- **React Compiler** for automatic memoization and optimization
+
+#### Performance Optimizations
+
+- Initial render count reduced from 6+ to 1 via `startTransition`
+- SDK instances and siteSettings in refs prevent re-renders
+- Separate state variables allow granular component updates
+- React Compiler automatically memoizes components and callbacks
+- BroadcastChannel enables real-time updates across tabs
+
+### Navigation Modes
+
+Navkit intelligently handles navigation based on context:
+
+#### 1. Desk Mode (when `frontendUrl` is set)
+
+- **When**: Running inside Taruvi Desk application
+- **Behavior**: Relative navigation within the app
+- **Examples**:
+  - `https://app.taruvi.io/mail` → navigates to `/mail`
+  - `/preferences` → navigates to `/preferences`
+- **Detection**: Checks if `window.location.href` includes `frontendUrl`
+
+```typescript
+// Site settings with frontendUrl
+{
+  frontendUrl: 'https://desk.taruvi.io',
+  // ... other settings
+}
+```
+
+#### 2. External Mode (no `frontendUrl`)
+
+- **When**: Running in standalone app or `frontendUrl` not set
+- **Behavior**: Opens URLs in new tab
+- **Examples**:
+  - `https://mail.taruvi.io` → opens in new tab
+  - `https://external-app.com` → opens in new tab
+- **Purpose**: Prevents navigating away from host application
+
+```typescript
+// Site settings without frontendUrl
+{
+  frontendUrl: '', // or null/undefined
+  // ... other settings
+}
+```
+
+#### Navigation Hook
+
+```typescript
+import { useNavigation } from './NavkitContext'
+
+// In any child component
+function MyComponent() {
+  const { navigateToUrl, isDesk, siteSettings } = useNavigation()
+
+  // Automatically detects mode and navigates appropriately
+  navigateToUrl('/app-name')
+}
+```
+
+### Responsive Breakpoints
+
+Navkit uses a mobile-first responsive design strategy:
+
+#### Mobile (xs): < 900px
+
+- **User name**: Hidden (avatar only)
+- **Shortcuts**: Hamburger menu dropdown
+- **App launcher**: Full-width (95vw)
+- **Touch targets**: Minimum 44x44px
+- **Optimizations**: Reduced clutter for small screens
+
+#### Desktop (md+): ≥ 900px
+
+- **User name**: Visible next to avatar
+- **Shortcuts**: Inline horizontal layout
+- **App launcher**: Fixed width (600px)
+- **Enhanced UX**: More information density
+
+#### Implementation Example
+
+```typescript
+// Conditional rendering based on breakpoint
+<Typography sx={{ display: { xs: 'none', md: 'block' } }}>
+  {userData.fullName}
+</Typography>
+
+// Responsive dimensions
+container: {
+  width: { xs: '95vw', sm: '80vw', md: '70vw', lg: '600px' },
+  height: { xs: '90vh', md: '80vh' },
+}
+```
+
+#### Testing Breakpoints
+
+Test the following widths for complete coverage:
+- **320px**: Minimum mobile (iPhone SE)
+- **768px**: Tablet
+- **900px**: Breakpoint threshold
+- **1024px**: Small desktop
+- **1920px**: Large desktop
+
+## Configuration
+
+### Site Settings
+
+The component expects the following settings from the SDK:
+
+```typescript
+interface SiteSettings {
+  logo: string              // Navigation bar logo URL
+  frontendUrl: string      // Base URL for desk mode navigation (optional)
+  mattermostUrl: string    // Mattermost server URL (optional)
+  shortcuts: AppData[]     // Quick action shortcuts
+}
+
+// Example
+{
+  logo: 'https://cdn.taruvi.io/logo.png',
+  frontendUrl: 'https://desk.taruvi.io',
+  mattermostUrl: 'https://chat.taruvi.io',
+  shortcuts: [
+    {
+      id: '1',
+      appname: 'Mail',
+      icon: 'envelope',
+      url: '/mail'
+    },
+    {
+      id: '2',
+      appname: 'Calendar',
+      icon: 'calendar',
+      url: '/calendar'
+    },
+    {
+      id: '3',
+      appname: 'Chat',
+      icon: 'comments',
+      url: '#' // Special handling for chat
+    }
+  ]
+}
+```
+
+### User Data
+
+```typescript
+interface UserData {
+  fullName: string         // Full display name
+  pfp: string             // Profile picture URL
+  username: string        // Username or handle
+  email: string          // User email address
+}
+
+// Example
+{
+  fullName: 'John Doe',
+  pfp: 'https://cdn.taruvi.io/avatars/johndoe.jpg',
+  username: 'johndoe',
+  email: 'john.doe@taruvi.io'
+}
+```
+
+### App Data
+
+```typescript
+interface AppData {
+  id: string              // Unique app identifier
+  appname: string        // Display name
+  icon: string           // FontAwesome icon name (without 'fa-' prefix)
+  url: string           // App URL or path
+}
+
+// Example
+{
+  id: 'app-mail-001',
+  appname: 'Mail',
+  icon: 'envelope',        // Renders as fa-envelope
+  url: 'https://mail.taruvi.io'
+}
+```
+
+#### FontAwesome Icon Names
+
+Icons use FontAwesome Free icon names without the `fa-` prefix:
+- `envelope` → `fa-envelope`
+- `calendar` → `fa-calendar`
+- `home` → `fa-home`
+- `cog` → `fa-cog`
+
+See [FontAwesome Free Icons](https://fontawesome.com/search?o=r&m=free) for available icons.
+
+## Styling
+
+### Design System
+
+Navkit uses a centralized design system with design tokens in [src/styles/variables.ts](src/styles/variables.ts):
+
+#### Color Palette
+
+```typescript
+colours = {
+  text: {
+    primary: '#333333',    // Main text
+    secondary: '#424242',  // Secondary text
+    tertiary: '#9e9e9e',  // Disabled/subtle text
+  },
+  bg: {
+    white: '#fff',        // White background
+    light: '#f5f5f5',    // Light grey background
+    avatar: '#E0E0E0',   // Avatar placeholder
+  },
+  border: {
+    light: '#e0e0e0',    // Border color
+  },
+}
+```
+
+#### Spacing Scale
+
+```typescript
+spacing = {
+  xs: '10px',  // Extra small
+  sm: 1.5,     // Small (12px with MUI 8px base)
+  md: 2,       // Medium (16px)
+  lg: 3,       // Large (24px)
+}
+```
+
+#### Typography
+
+```typescript
+typography = {
+  sizes: {
+    xs: '0.8125rem',  // 13px
+    sm: '0.875rem',   // 14px
+    md: '1.125rem',   // 18px
+  },
+  weights: {
+    regular: 400,
+    semibold: 600,
+  },
+}
+```
+
+#### Dimensions
+
+```typescript
+dimensions = {
+  navHeight: '60px',
+  avatarSize: 40,
+  iconSize: {
+    sm: '18px',
+    md: '24px',
+    lg: '1.25rem',
+  },
+}
+```
+
+### Customization Options
+
+#### 1. Component-Specific Styles
+
+Each component has a `.styles.ts` file:
+
+```typescript
+// Profile.styles.ts
+import { colours, spacing, typography } from '../../styles/variables'
+
+export const profileStyles = {
+  userName: {
+    fontSize: typography.sizes.sm,
+    color: colours.text.primary,
+    padding: spacing.xs,
+  }
+}
+```
+
+#### 2. Design Tokens
+
+Modify `src/styles/variables.ts` for global changes:
+
+```typescript
+// Change primary text color globally
+export const colours = {
+  text: {
+    primary: '#000000',  // Darker text
+    // ...
+  }
+}
+```
+
+#### 3. MUI Theme Provider
+
+Wrap Navkit with MUI ThemeProvider for advanced theming:
+
+```tsx
+import { createTheme, ThemeProvider } from '@mui/material/styles'
+
+const theme = createTheme({
+  palette: {
+    primary: {
+      main: '#1976d2',
+    },
+  },
+})
+
+function App() {
+  return (
+    <ThemeProvider theme={theme}>
+      <Navkit client={client} />
+    </ThemeProvider>
+  )
+}
+```
+
+## Tech Stack
+
+### Core Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| **React** | 19.1.1 | UI framework with concurrent features |
+| **React DOM** | 19.1.1 | DOM rendering |
+| **TypeScript** | ~5.9.3 | Type safety and developer experience |
+
+### Peer Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| **@mui/material** | ^5.0.0 | UI component library |
+| **@emotion/react** | ^11.0.0 | CSS-in-JS (MUI dependency) |
+| **@emotion/styled** | ^11.0.0 | Styled components (MUI dependency) |
+| **@fortawesome/fontawesome-svg-core** | ^6.0.0 | Icon library core |
+| **@fortawesome/free-solid-svg-icons** | ^6.0.0 | Solid icons |
+| **@fortawesome/free-regular-svg-icons** | ^6.0.0 | Regular icons |
+| **@fortawesome/react-fontawesome** | ^0.2.0 | React icon components |
+| **@taruvi-io/sdk** | latest | Taruvi SDK for API integration |
+
+### Development Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| **Vite** | 7.1.7 | Build tool and dev server |
+| **@vitejs/plugin-react** | ^5.0.4 | Vite React plugin |
+| **babel-plugin-react-compiler** | ^19.1.0-rc.3 | Automatic optimizations |
+| **ESLint** | ^9.36.0 | Code linting |
+| **typescript-eslint** | ^8.45.0 | TypeScript ESLint support |
+
+### Why These Choices?
+
+- **React 19**: Latest features (startTransition, concurrent rendering)
+- **Vite**: Fast HMR (< 100ms), optimized builds
+- **MUI**: Accessible, responsive, well-maintained
+- **TypeScript**: Catch errors at compile time
+- **React Compiler**: Automatic performance optimizations
+
+## Performance Optimizations
+
+### Automatic Optimizations
+
+#### React Compiler
+- **Automatic memoization** of components and values
+- **Callback stabilization** without manual `useCallback`
+- **Reduced re-renders** through intelligent optimization
+- **No boilerplate** (no manual `useMemo`, `React.memo`)
+
+#### Vite Build Pipeline
+- **Code splitting**: Automatic chunking for optimal loading
+- **Tree shaking**: Removes unused code in production
+- **Minification**: Terser for JavaScript, CSS minification
+- **Fast Refresh**: Sub-second HMR during development
+
+### Manual Optimizations
+
+#### State Management
+```typescript
+// Separate state variables for granular updates
+const [showAppLauncher, setShowAppLauncher] = useState(false)
+const [showProfileMenu, setShowProfileMenu] = useState(false)
+
+// useRef for SDK instances (no re-renders)
+const settings = useRef<any>(null)
+
+// startTransition for batched updates
+startTransition(() => {
+  setAppsList(apps)
+  setUserData(userData)
+  setSiteSettings(settings)
+})
+```
+
+#### Performance Metrics
+
+| Metric | Value | Target |
+|--------|-------|--------|
+| Initial renders | 1 | < 3 |
+| Bundle size (gzipped) | ~150KB | < 200KB |
+| Time to Interactive | < 1s | < 2s |
+| First Contentful Paint | < 500ms | < 1s |
+
+### Best Practices
+
+1. **Avoid unnecessary renders**: Separate state variables
+2. **Batch updates**: Use `startTransition` for multiple state changes
+3. **Stable references**: Use `useRef` for non-rendering data
+4. **Trust the compiler**: Let React Compiler handle optimization
+
+## Browser Support
+
+Modern browsers with ES2020+ support:
+- Chrome/Edge 88+
+- Firefox 78+
+- Safari 14+
+
+## Project Structure
+
+```
+taruvi-navkit/
+├── docs/
+│   └── adr/                    # Architecture Decision Records
+│       └── 001-navkit-architecture.md
+├── src/
+│   ├── components/
+│   │   ├── AppLauncher/
+│   │   ├── Profile/
+│   │   ├── Shortucts/
+│   │   ├── Search/
+│   │   └── MattermostChat/
+│   ├── styles/
+│   │   └── variables.ts        # Design tokens
+│   ├── NavkitContext.tsx       # React Context provider & hook
+│   ├── App.tsx                 # Main Navkit component
+│   ├── App.styles.ts
+│   └── types.ts                # TypeScript interfaces
+├── package.json
+├── tsconfig.json
+├── vite.config.ts
+└── README.md
+```
+
+## Build Configuration
+
+### Vite
+
+The project uses Vite 7 with:
+- **@vitejs/plugin-react** for Fast Refresh
+- **babel-plugin-react-compiler** for automatic optimizations
+- HMR (Hot Module Replacement) enabled
+- TypeScript support out of the box
+
+### TypeScript
+
+Strict mode enabled with:
+- **noImplicitAny**: Require explicit types
+- **strictNullChecks**: Catch null/undefined errors
+- **esModuleInterop**: Better module compatibility
+
+## Contributing
+
+1. Follow the existing code style
+2. Use TypeScript for all new files
+3. Add/update ADRs for architectural decisions
+4. Test responsive behavior on mobile and desktop
+5. Ensure no console errors or warnings
+
+## Troubleshooting
+
+### Common Issues
+
+#### Navigation not working
+
+**Symptoms**: Clicks don't navigate, URLs incorrect
+
+**Solutions**:
+- Ensure `frontendUrl` is set in site settings for desk mode
+- Check that URLs are valid (full URLs or relative paths starting with `/`)
+- Verify SDK settings instance is being passed correctly
+- Check console for navigation errors
+
+```typescript
+// Debug navigation
+console.log('Settings:', await settings.get())
+console.log('Is Desk?', await isDesk(settings))
+```
+
+#### Styles not applying
+
+**Symptoms**: Components look unstyled or broken
+
+**Solutions**:
+- Check that MUI is installed as a peer dependency: `npm list @mui/material`
+- Verify design tokens are imported in component styles
+- Ensure `sx` prop is used (not `style`)
+- Check for CSS conflicts from parent app
+
+```bash
+# Verify MUI installation
+npm list @mui/material @emotion/react @emotion/styled
+```
+
+#### Click-outside not working
+
+**Symptoms**: Menus don't close when clicking outside
+
+**Solutions**:
+- Check that menus have proper refs assigned
+- Verify useEffect dependencies include all `show*` states
+- Ensure no other click handlers are interfering with event propagation
+- Check that `menuRef` is attached to menu container
+
+#### App launcher empty
+
+**Symptoms**: No apps showing in launcher
+
+**Solutions**:
+- Verify `user.getApps()` returns data
+- Check console for API errors
+- Ensure apps have required fields: `id`, `appname`, `icon`, `url`
+- Test with mock data to isolate issue
+
+```typescript
+// Debug apps data
+console.log('Apps:', await user.current.getApps())
+```
+
+#### Icons not showing
+
+**Symptoms**: Icons appear as boxes or missing
+
+**Solutions**:
+- Verify FontAwesome packages installed
+- Check icon names match FontAwesome free icons
+- Ensure `library.add(fas, far)` is called
+- Use correct icon name format (without `fa-` prefix)
+
+```typescript
+// Debug icon
+<FontAwesomeIcon icon={["fas", "envelope"]} />  // Correct
+<FontAwesomeIcon icon={["fas", "fa-envelope"]} />  // Wrong
+```
+
+### Getting Help
+
+1. Check the [ADR documentation](./adr.md) for architecture details
+2. Review [existing ADRs](./docs/adr/) for design decisions
+3. Enable verbose logging in development
+4. Contact the Taruvi development team for support
+
+## License
+
+Internal Taruvi project - All rights reserved
+
+## Documentation
+
+### Architecture Decision Records (ADRs)
+
+- **[Comprehensive ADR](./adr.md)** - Complete architectural decisions and rationale
+- **[ADR 001: Navkit Architecture](./docs/adr/001-navkit-architecture.md)** - Detailed component architecture
+- **[Future Considerations](./adr.md#future-considerations)** - Planned enhancements
+
+### Key Documentation Sections
+
+| Topic | Location |
+|-------|----------|
+| Technology stack decisions | [adr.md - Tech Stack](./adr.md#technology-stack) |
+| State management strategy | [adr.md - State Management](./adr.md#state-management-strategy) |
+| Navigation system | [adr.md - Navigation System](./adr.md#navigation-system) |
+| Responsive design | [adr.md - Responsive Design](./adr.md#responsive-design) |
+| Performance optimizations | [adr.md - Performance](./adr.md#performance-optimizations) |
+| Component architecture | [docs/adr/001](./docs/adr/001-navkit-architecture.md) |
+
+### External Resources
+
+- [React 19 Documentation](https://react.dev/)
+- [Material-UI Documentation](https://mui.com/)
+- [Vite Documentation](https://vite.dev/)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
+- [FontAwesome Icons](https://fontawesome.com/search?o=r&m=free)
+
+## Support
+
+For issues, questions, or feature requests, contact the Taruvi development team.