@optifye/dashboard-core 1.0.0 → 2.0.2

package/README.md

@@ -1,228 +1,656 @@
 # @optifye/dashboard-core
 
-A reusable React component library and utility toolkit for building dashboard functionalities, tailored for Optifye applications.
+# @optifye/dashboard-core
+
+A comprehensive React component library and core utilities package for building enterprise-grade operational dashboards with real-time metrics, visualizations, and interactive views.
+
+## Overview
+
+The **@optifye/dashboard-core** package provides a complete solution for building data-rich, real-time operational dashboards for manufacturing, production lines, and industrial workspaces. It includes a comprehensive set of UI components, data hooks, services, utilities, and fully-composed view components that can be used to build complete dashboard applications with minimal effort.
+
+This package has been designed with a focus on:
+
+- **Component Reusability**: All UI components from atomic elements to complete page views
+- **Data Abstraction**: Hooks and services for clean data fetching and management
+- **Configurability**: Extensive prop-based configuration for all components
+- **Type Safety**: Comprehensive TypeScript types throughout
+- **Performance**: Optimized rendering and data fetching strategies
+- **Enterprise Readiness**: Authentication, real-time data, and role-based access controls
+
+## Package Structure
+
+### Core Architecture
+
+The package is organized into the following key directories:
+
+```
+@optifye/dashboard-core/
+├── src/
+│   ├── components/     # UI Components from atomic to composite
+│   ├── lib/            # Core logic, utilities, hooks, services
+│   ├── views/          # Complete page-level view components
+│   └── index.ts        # Main export file
+```
+
+### Component Architecture
+
+Components follow a hierarchical organization:
+
+```
+components/
+├── auth/           # Authentication components
+├── charts/         # Data visualization components
+├── common/         # Shared components across domains
+├── dashboard/      # Domain-specific dashboard components
+│   ├── grid/       # Workspace grid components
+│   ├── kpis/       # KPI visualization components
+│   ├── line/       # Production line components
+│   ├── video/      # Video streaming components
+│   └── workspace/  # Workspace detail components
+├── data/           # Data display and transformation components
+├── layouts/        # Layout components and structure
+├── navigation/     # Navigation components and menus
+├── ui/             # Fundamental UI components (buttons, cards, etc.)
+└── views/          # View-specific components
+```
+
+### Core Library Structure
+
+The core logic follows a clean separation of concerns:
+
+```
+lib/
+├── constants/      # Application constants and configuration values
+├── contexts/       # React context providers and consumers
+├── hooks/          # Custom React hooks for data and UI
+├── internal/       # Internal utilities (not exported)
+├── services/       # Data services and API clients
+│   └── factories/  # Service factory functions
+├── supabase/       # Supabase client configuration
+├── types/          # TypeScript type definitions
+└── utils/          # Utility functions by domain
+    └── dev/        # Development utilities
+```
+
+## Key Features
+
+### 1. UI Component System
+
+The package provides a complete UI component system for building operational dashboards:
+
+#### Foundational UI Components
+
+- **Button**: Versatile button component with multiple variants (primary, secondary, outline, ghost)
+- **Card**: Card components with header, body, and footer sections
+- **Select**: Form select components with dropdown options
+- **LoadingSpinner, LoadingOverlay, LoadingPage**: Loading indicators at various levels
+- **DateDisplay, TimeDisplay**: Timezone-aware date and time components
+- **Skeleton**: Loading skeleton placeholders
+- **EmptyStateMessage**: Consistent empty state messaging
+
+#### Data Visualization
+
+- **KPICard**: Key Performance Indicator display cards
+- **MetricCard**: General metric display cards
+- **LineChart, BarChart**: Chart components for data visualization
+- **HourlyOutputChart**: Specialized chart for hourly production data
+- **WorkspaceHistoryCalendar**: Calendar visualization for workspace metrics history
+- **OutputProgressChart**: Progress visualization for production output
+
+#### Video & Real-Time Components
+
+- **LiveView**: Real-time HLS video streaming component
+- **BottlenecksContent**: Video clip management for bottleneck analysis
+
+#### Navigation & Layout
+
+- **MainLayout**: Main application layout with sidebar
+- **DashboardLayout**: Full dashboard layout with header and sidebar
+- **SideNavBar**: Navigation sidebar with configurable items
+- **PageHeader**: Page header with breadcrumbs and user profile
+
+### 2. Data Services
+
+The package includes ready-to-use data services for common dashboard operations:
+
+- **dashboardService**: Core dashboard data operations
+- **workspaceService**: Workspace management and configuration
+- **actionService**: Action tracking and management
+- **whatsAppService**: WhatsApp integration for notifications
+- **realtimeService**: Real-time data streaming and subscriptions
+- **qualityService**: Quality metrics and analysis
+- **mixpanelService**: Event tracking and analytics
+
+### 3. Custom Hooks
 
-This package provides a set of configurable services, hooks, context providers, and utility functions to interact with a Supabase backend and manage dashboard-specific logic.
+Specialized hooks for data fetching and UI interactions:
 
-## Features
+- **useDashboardMetrics**: Dashboard-level metrics and KPIs
+- **useMetrics**: General metrics management
+- **useRealtimeLineMetrics**: Real-time line metrics with subscriptions
+- **useLineDetailedMetrics**: Detailed metrics for production lines
+- **useWorkspaceDetailedMetrics**: Detailed metrics for workspaces
+- **useLineWorkspaceMetrics**: Combined line and workspace metrics
+- **useHistoricWorkspaceMetrics**: Historical data for workspaces
+- **useLeaderboardMetrics**: Leaderboard and ranking metrics
+- **useFactoryOverviewMetrics**: Factory-level overview metrics
+- **useTargets**: Production targets management
+- **useWorkspaceOperators**: Operator assignment and management
+- **useShifts**: Shift schedule management
+- **useDateFormatter**: Date formatting utilities
+- **useFormatNumber**: Number formatting utilities
+- **useNavigation**: Navigation helpers
 
--   **Configurable**: Highly configurable via a central `DashboardConfig` object.
--   **React Hooks**: A rich set of hooks for accessing data, managing state, and handling metrics.
--   **Services**: Modular services for interacting with backend data (e.g., dashboard metrics, line info, user actions).
--   **Context Providers**: For managing global state like authentication, configuration, and component overrides.
--   **Type-Safe**: Written in TypeScript for improved developer experience and safety.
+### 4. Complete Views
 
+Full page-level view components that can be directly used in applications:
+
+- **HomeView**: Main dashboard overview
+- **FactoryView**: Factory-level overview with multiple lines
+- **KPIDetailView**: Detailed KPI view for a specific line
+- **WorkspaceDetailView**: Detailed view for a specific workspace
+- **TargetsView**: Production targets management view
+- **ShiftsView**: Shift scheduling and management view
 
 ## Installation
 
 ```bash
 npm install @optifye/dashboard-core
-# or
-yarn add @optifye/dashboard-core
 ```
 
-## Quick Start & Usage
+### Peer Dependencies
+
+This package requires the following peer dependencies to be installed in your project:
+
+```bash
+npm install react@^18 react-dom@^18 next@^13 tailwindcss@^3 @supabase/supabase-js@^2 date-fns@^4 date-fns-tz@^3
+```
+
+Or if using Yarn:
+
+```bash
+yarn add react@^18 react-dom@^18 next@^13 tailwindcss@^3 @supabase/supabase-js@^2 date-fns@^4 date-fns-tz@^3
+```
+
+### CSS Setup
 
-The primary way to integrate `@optifye/dashboard-core` into your application is by using the `DashboardProvider` at the root of your component tree (or a relevant section).
+This package includes global CSS styles that need to be imported in your application. In your Next.js app, import the global CSS file once in your `_app.tsx` or `layout.tsx`:
 
 ```tsx
-// Example: pages/_app.tsx in a Next.js application
-
-import type { AppProps } from 'next/app';
-import {
-  DashboardProvider,
-  DashboardConfig,
-  AuthProvider,
-  DashboardOverridesProvider
-} from '@optifye/dashboard-core';
+// pages/_app.tsx or app/layout.tsx
+import '@optifye/dashboard-core/global.css';
+```
 
-// 1. Define your application-specific dashboard configuration
-const appConfig: Partial<DashboardConfig> = {
-  supabaseUrl: process.env.NEXT_PUBLIC_SUPABASE_URL!,
-  supabaseKey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+This CSS file includes:
+- Tailwind CSS base styles
+- Custom component styles
+- React Day Picker styles (for calendar components)
+- Range slider styling
+
+**Note:** You do NOT need to separately import `react-day-picker/dist/style.css` as these styles are already included in the package's global CSS.
+
+## Integration Guide
+
+### Basic Setup
+
+1. Install the package:
+
+```bash
+npm install @optifye/dashboard-core
+```
+
+2. Wrap your application with the required providers:
+
+```tsx
+import { SupabaseProvider, DashboardProvider } from '@optifye/dashboard-core';
+import { createClient } from '@supabase/supabase-js';
+
+// Initialize Supabase client
+const supabaseClient = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+);
+
+// Dashboard configuration
+const dashboardConfig = {
   entityConfig: {
-    companyId: process.env.NEXT_PUBLIC_COMPANY_ID!,
-    // ... other entity-specific IDs like factoryId, defaultLineId etc.
+    lineId: 'your-line-id',
+    factoryViewId: 'factory',
+    companyId: 'your-company-id'
   },
-  // ... other configurations like theme, analytics, dateTimeConfig etc.
+  supabaseKey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+  apiUrl: process.env.NEXT_PUBLIC_API_URL!,
+  timezone: 'Asia/Kolkata',
+  // ... other configuration options
 };
 
-function MyApp({ Component, pageProps }: AppProps) {
+function MyApp({ Component, pageProps }) {
   return (
-    <DashboardProvider config={appConfig}>
-      <AuthProvider> { /* For authentication */ }
-        <DashboardOverridesProvider overrides={{ /* your component overrides */ }}>
+    <SupabaseProvider client={supabaseClient}>
+      <DashboardProvider config={dashboardConfig}>
           <Component {...pageProps} />
-        </DashboardOverridesProvider>
-      </AuthProvider>
     </DashboardProvider>
+    </SupabaseProvider>
   );
 }
 
 export default MyApp;
 ```
 
-### Configuration (`DashboardConfig`)
+### Using Individual Components
 
-The `DashboardConfig` object is crucial for tailoring the package to your specific application instance. It allows you to define:
+```tsx
+import { 
+  KPICard, 
+  Button, 
+  Card, 
+  DateDisplay,
+  useLineKPIs
+} from '@optifye/dashboard-core';
 
--   Supabase credentials (`supabaseUrl`, `supabaseKey` - **required**)
--   Entity identifiers (`entityConfig` - e.g., `companyId`, `factoryId`, line IDs - **often required for services/hooks**)
--   API endpoints (`apiBaseUrl`, `endpoints`)
--   Theme overrides (`theme`)
--   Date/time preferences (`dateTimeConfig`)
--   Database table names and schema (`databaseConfig`)
--   And more...
+function MyDashboardComponent() {
+  const { kpis, isLoading, error } = useLineKPIs('line-id');
 
-Refer to the `DashboardConfig` interface definition within the package (exported from `lib/types/dashboardConfig`) for all available options and their types. For a detailed setup guide, see the [Application Configuration Setup Guide](../../migration_outputs/14_app_configuration_setup.md).
+  if (isLoading) return <LoadingSpinner />;
+  if (error) return <div>Error loading KPIs</div>;
 
-## Core Modules
+  return (
+    <Card>
+      <Card.Header>
+        <Card.Title>Line Performance</Card.Title>
+        <DateDisplay date={new Date()} />
+      </Card.Header>
+      <Card.Content>
+        <div className="grid grid-cols-3 gap-4">
+          <KPICard 
+            title="Efficiency" 
+            value={kpis.efficiency} 
+            changeValue={kpis.efficiencyChange} 
+            variant="percentage"
+          />
+          <KPICard 
+            title="Output" 
+            value={kpis.output} 
+            changeValue={kpis.outputChange} 
+            variant="number"
+          />
+          <KPICard 
+            title="PPH" 
+            value={kpis.pph} 
+            changeValue={kpis.pphChange} 
+            variant="number"
+          />
+        </div>
+      </Card.Content>
+      <Card.Footer>
+        <Button>View Details</Button>
+      </Card.Footer>
+    </Card>
+  );
+}
+```
 
-This package is organized into several core modules:
+### Using Complete Views
 
--   **`lib/types`**: Contains all TypeScript interface and type definitions.
--   **`lib/constants`**: Provides default configurations and other constant values.
--   **`lib/contexts`**: Includes React Context providers and hooks for global state.
--   **`lib/hooks`**: Custom React hooks for fetching and managing data.
--   **`lib/services`**: Service factories for data interaction.
--   **`lib/utils`**: Utility functions for common tasks.
--   **`lib/supabaseClient`**: Supabase client utilities.
+```tsx
+import { FactoryView } from '@optifye/dashboard-core';
+import { withAuth } from '@optifye/dashboard-core';
 
-## Utility Hooks
+// Factory view with authentication protection
+function FactoryPage() {
+  return (
+    <FactoryView 
+      lineIds={['line-1-id', 'line-2-id']}
+      productIdMap={{
+        'line-1-id': 'product-1-id',
+        'line-2-id': 'product-2-id'
+      }}
+      showEfficiency={true}
+      showOutput={true}
+      showUnderperforming={true}
+    />
+  );
+}
 
--   **`useNavigation`**: Abstracted navigation API.
--   **`useDateFormatter`**: Configured date/time formatting.
--   **`useWorkspaceNavigation`**: Utilities for workspace navigation parameters.
--   **`useFormatNumber`**: Configured number formatting.
+export default withAuth(FactoryPage);
+```
 
-## UI Components
+## Authentication and Security
 
-`@optifye/dashboard-core` provides a suite of reusable UI components.
+The package includes a comprehensive authentication system:
 
-### Common Components
+- **withAuth**: Higher-order component for route protection
+- **useAuth**: Hook for accessing authentication state and user data
+- **AuthContext**: Context provider for authentication state
+- **Authentication-Ready Views**: All view components have authentication built-in
 
--   **`MetricCard`**: Displays a key metric, value, unit, and trend.
-    -   **Location**: `packages/dashboard-core/src/components/common/MetricCard.tsx`
--   **`DateTimeDisplay`**: Shows current date/time, formatted via `DateTimeConfig`.
-    -   **Location**: `packages/dashboard-core/src/components/common/DateTimeDisplay.tsx`
--   **`EmptyStateMessage`**: For displaying messages when content is unavailable.
-    -   **Location**: `packages/dashboard-core/src/components/common/EmptyStateMessage.tsx`
--   **`WhatsAppShareButton`**: Opens a WhatsApp share link.
-    -   **Location**: `packages/dashboard-core/src/components/common/WhatsAppShareButton.tsx`
--   **`BaseHistoryCalendar`**: Foundational calendar using `react-day-picker`.
-    -   **Location**: `packages/dashboard-core/src/components/common/BaseHistoryCalendar.tsx`
+## Performance Optimizations
 
-### Dashboard Components
+The package includes several performance optimizations:
 
-#### Line Components
+- **Component Memoization**: React.memo with custom comparison functions
+- **Data Caching**: SWR-based data caching and revalidation
+- **Lazy Loading**: Dynamic imports for heavy components
+- **Tree Shaking**: Proper module exports for better tree shaking
+- **Render Optimizations**: Proper useMemo and useCallback hooks
 
--   **`LinePdfExportButton`**: Captures a DOM element and exports as PDF.
-    -   **Location**: `packages/dashboard-core/src/components/dashboard/line/LinePdfExportButton.tsx`
--   **`LineHistoryCalendar`**: Displays monthly history for a line using `BaseHistoryCalendar`.
-    -   **Location**: `packages/dashboard-core/src/components/dashboard/line/LineHistoryCalendar.tsx`
--   **`LineMonthlyHistory`**: Monthly historical overview for a line, using `LineHistoryCalendar`.
-    -   **Location**: `packages/dashboard-core/src/components/dashboard/line/LineMonthlyHistory.tsx`
+## AWS Integration for Video
 
-#### Workspace Components
+The package includes AWS S3 integration for video clips:
 
--   **`WorkspacePdfExportButton`**: Similar to `LinePdfExportButton` for workspace data.
-    -   **Location**: `packages/dashboard-core/src/components/dashboard/workspace/WorkspacePdfExportButton.tsx`
--   **`WorkspaceCard`**: Presentational card for workspace information and metrics.
-    -   **Location**: `packages/dashboard-core/src/components/dashboard/workspace/WorkspaceCard.tsx`
--   **`LiveView`**: Displays HLS video streams for workspace cameras.
-    -   **Location**: `packages/dashboard-core/src/components/dashboard/workspace/LiveView.tsx`
--   **`OperatorsDisplay`**: Displays a list/row of operator avatars/names.
-    -   **Location**: `packages/dashboard-core/src/components/dashboard/workspace/OperatorsDisplay.tsx`
--   **`WorkspaceHistoryCalendar`**: Displays monthly history for a workspace, using `BaseHistoryCalendar`.
-    -   **Location**: `packages/dashboard-core/src/components/dashboard/workspace/WorkspaceHistoryCalendar.tsx`
+- **Direct S3 Integration**: No API endpoints required
+- **Signed URL Generation**: Secure access to video content
+- **Configurable Integration**: Custom fetch functions and credentials
+- **Fallback Mode**: Simulated mode when credentials are not available
 
-#### Grid Components
+## Configuration Reference
 
--   **`WorkspaceGrid`**: Layout for arranging `WorkspaceCard` components.
-    -   **Location**: `packages/dashboard-core/src/components/dashboard/grid/WorkspaceGrid.tsx`
+### DashboardConfig
 
-### Chart Components
+```typescript
+interface DashboardConfig {
+  // Entity configuration
+  entityConfig: {
+    lineId: string;
+    factoryViewId: string;
+    companyId: string;
+    // Optional additional line IDs
+    lineIds?: Record<string, string>;
+  };
+  
+  // API configuration
+  supabaseKey: string;
+  apiUrl: string;
+  
+  // Time configuration
+  timezone: string;
+  
+  // Feature flags
+  features?: {
+    enableRealtime?: boolean;
+    enableVideoStreaming?: boolean;
+    enableWhatsAppShare?: boolean;
+    enablePdfExport?: boolean;
+  };
+  
+  // Theme configuration
+  theme?: {
+    primaryColor?: string;
+    secondaryColor?: string;
+    accentColor?: string;
+    errorColor?: string;
+    warningColor?: string;
+    successColor?: string;
+  };
+  
+  // Other configuration options
+  options?: {
+    refreshInterval?: number;
+    dateFormat?: string;
+    timeFormat?: string;
+  };
+}
+```
 
--   **`BarChart`**: Generic wrapper for Recharts `BarChart`.
-    -   **Location**: `packages/dashboard-core/src/components/charts/BarChart.tsx`
--   **`LineChart`**: Flexible wrapper for Recharts `LineChart`.
-    -   **Location**: `packages/dashboard-core/src/components/charts/LineChart.tsx`
+## Working with Supabase
 
-### KPI Components
+The package is designed to work with Supabase for data storage and real-time capabilities:
 
--   **`KPICard`**: Displays KPI metrics with trends, secondary metrics, status indicators.
-    -   **Location**: `packages/dashboard-core/src/components/dashboard/kpis/KPICard.tsx`
--   **`KPIGrid`**: Layout for KPI cards (row or grid).
-    -   **Location**: `packages/dashboard-core/src/components/dashboard/kpis/KPIGrid.tsx`
--   **`KPIHeader`**: Header for KPI sections with title, subtitle, actions.
-    -   **Location**: `packages/dashboard-core/src/components/dashboard/kpis/KPIHeader.tsx`
--   **`KPISection`**: Displays a collection of KPIs using `KPICard`s and `KPIGrid`.
-    -   **Location**: `packages/dashboard-core/src/components/dashboard/kpis/KPISection.tsx`
+1. The `SupabaseProvider` component must be configured with a Supabase client.
+2. All data services will use this client for data operations.
+3. Real-time subscriptions use Supabase's real-time capabilities.
 
-### Navigation Components
+### Supabase Schema
 
--   **`SideNavBar`**: Configurable side navigation bar.
-    -   **Location**: `packages/dashboard-core/src/components/navigation/SideNavBar.tsx`
+The package expects the following Supabase tables and structure:
 
-### Layout Components
+- **metrics_current**: Current metrics for lines and workspaces
+- **metrics_hourly**: Hourly aggregated metrics
+- **metrics_daily**: Daily aggregated metrics
+- **line_operating_hours**: Shift configuration for lines
+- **workspaces**: Workspace definitions and configuration
+- **workspace_actions**: Action configurations for workspaces
+- **workspace_operators**: Operator assignments to workspaces
 
--   **`PageHeader`**: Responsive header for dashboard pages.
-    -   **Location**: `packages/dashboard-core/src/components/layouts/PageHeader.tsx`
--   **`DashboardLayout`**: Main layout component for dashboard pages.
-    -   **Location**: `packages/dashboard-core/src/components/layouts/DashboardLayout.tsx`
+## Integration Examples
 
+### Next.js Integration
 
-### Leaderboard Components
+For Next.js applications, a common pattern is to use the dynamic catch-all routing to render the appropriate view:
 
-Location: `src/components/dashboard/leaderboard/`
+```tsx
+// pages/[[...dashboard]].tsx
+import { useRouter } from 'next/router';
+import dynamic from 'next/dynamic';
+
+// Dynamic imports with loading fallbacks
+const HomeView = dynamic(() => import('@optifye/dashboard-core/views/HomeView'), {
+  loading: () => <div className="flex h-screen w-full items-center justify-center">Loading...</div>,
+  ssr: false
+});
+
+const FactoryView = dynamic(() => import('@optifye/dashboard-core/views/FactoryView'), {
+  loading: () => <div className="flex h-screen w-full items-center justify-center">Loading...</div>,
+  ssr: false
+});
+
+// ... other view imports
+
+export default function DashboardPage() {
+  const router = useRouter();
+  const { dashboard } = router.query;
+  
+  // Determine which view to render based on the route
+  const renderView = () => {
+    if (!dashboard || dashboard.length === 0) {
+      return <HomeView />;
+    }
+    
+    const [main, id] = dashboard as string[];
+    
+    switch (main) {
+      case 'factory-view':
+        return <FactoryView />;
+      case 'kpis':
+        return <KPIDetailView lineId={id} />;
+      case 'workspace':
+        return <WorkspaceDetailView workspaceId={id} />;
+      case 'targets':
+        return <TargetsView />;
+      case 'shifts':
+        return <ShiftsView />;
+      default:
+        return <div>Page not found</div>;
+    }
+  };
+  
+  return (
+    <MainLayout>
+      {renderView()}
+    </MainLayout>
+  );
+}
+```
 
-*   **`LeaderboardTable`**: A flexible and sortable table component designed to display leaderboard rankings. It supports custom column definitions, row click handlers, loading/error/empty states, and styling for highlighting top/bottom entries.
-    *   **Key Props**: `data: LeaderboardRowData[]`, `columns?: ColumnDefinitionUnion[]`, `title?: string`, `onRowClick?: (row: LeaderboardRowData) => void`.
-    *   **Usage**: Ideal for presenting ranked lists based on performance metrics.
+### React SPA Integration
 
-## Usage
+For React SPA applications, you can use React Router:
 
-To use the `@optifye/dashboard-core` service factory in your application:
+```tsx
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+import { 
+  HomeView, 
+  FactoryView, 
+  KPIDetailView,
+  WorkspaceDetailView,
+  TargetsView,
+  ShiftsView
+} from '@optifye/dashboard-core';
 
-1.  **Ensure you have a Supabase client instance initialized in your application.**
+export default function App() {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route path="/" element={<HomeView />} />
+        <Route path="/factory-view" element={<FactoryView />} />
+        <Route path="/kpis/:lineId" element={<KPIDetailView />} />
+        <Route path="/workspace/:id" element={<WorkspaceDetailView />} />
+        <Route path="/targets" element={<TargetsView />} />
+        <Route path="/shifts" element={<ShiftsView />} />
+      </Routes>
+    </BrowserRouter>
+  );
+}
+```
+
+## Available Services
 
-2.  **Prepare a configuration object.** The service factory `createDashboardService` expects a configuration object that can include:
-    *   `entityConfig`: Specifies `companyId`, `factoryId`, `defaultLineId`, `secondaryLineId`, `lineNames`, and `factoryViewId`.
-    *   `supabaseUrl`, `supabaseKey`: Required by certain internal parts of the service (e.g., Edge Function calls) even if a client is passed.
-    *   `apiBaseUrl`: Base URL for API calls, used by features like `getUnderperformingWorkspaces` if its endpoint is relative.
-    *   `endpoints`: Configuration for specific service endpoints, e.g., `worstPerformingWorkspaces`.
-    *   Other configurations like `databaseConfig`, `shiftConfig`, `dateTimeConfig` can be provided to override package defaults.
+### dashboardService
 
-3.  **Create the service instance:**
+The core service for dashboard data operations.
 
 ```typescript
-import { createDashboardService } from '@optifye/dashboard-core';
-import type { DashboardConfig } from '@optifye/dashboard-core';
-import { supabase } from '../path/to/your/supabaseClient'; // Your app's Supabase client
+// Key Methods
+dashboardService.getUnderperformingWorkspaces(lineId: string): Promise<WorkspaceMetrics[]>
+dashboardService.getLineInfo(lineId: string): Promise<LineInfo>
+dashboardService.getLineMetrics(lineId: string): Promise<LineMetrics>
+dashboardService.getWorkspacesForLine(lineId: string): Promise<Workspace[]>
+dashboardService.getHistoricalMetrics(params: HistoricalMetricsParams): Promise<HistoricalMetrics>
+```
 
-// Example application-specific configuration
-const appDashboardConfig: Partial<DashboardConfig> = {
-  entityConfig: {
-    companyId: 'YOUR_COMPANY_UUID',
-    defaultLineId: 'YOUR_DEFAULT_LINE_UUID',
-    // ... other entity properties
-  },
-  supabaseUrl: process.env.NEXT_PUBLIC_SUPABASE_URL,
-  supabaseKey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY,
-  apiBaseUrl: process.env.NEXT_PUBLIC_API_URL,
-  endpoints: {
-    worstPerformingWorkspaces: '/functions/v1/worst-performing-workspaces' // Or your specific endpoint path
-  }
-};
+### workspaceService
+
+Service for workspace management and configuration.
+
+```typescript
+// Key Methods
+workspaceService.getWorkspace(workspaceId: string): Promise<Workspace>
+workspaceService.getWorkspaceMetrics(workspaceId: string): Promise<WorkspaceDetailedMetrics>
+workspaceService.updateWorkspaceAction(params: WorkspaceActionUpdate): Promise<void>
+workspaceService.bulkUpdateWorkspaceActions(params: BulkWorkspaceActionUpdate): Promise<void>
+workspaceService.getLineWorkspaceThresholds(lineId: string): Promise<LineThreshold[]>
+```
+
+### actionService
+
+Service for action tracking and management.
+
+```typescript
+// Key Methods
+actionService.getActionForWorkspace(workspaceId: string): Promise<Action>
+actionService.updateAction(params: ActionUpdate): Promise<void>
+actionService.addAction(params: ActionCreate): Promise<Action>
+actionService.deleteAction(actionId: string): Promise<void>
+```
+
+### whatsAppService
 
-export const dashboardService = createDashboardService(appDashboardConfig, supabase);
+WhatsApp integration for notifications.
+
+```typescript
+// Key Methods
+whatsAppService.shareWorkspaceMetrics(params: ShareWorkspaceParams): Promise<string>
+whatsAppService.shareLineMetrics(params: ShareLineParams): Promise<string>
+whatsAppService.shareFactoryMetrics(params: ShareFactoryParams): Promise<string>
 ```
 
-Now you can use `dashboardService.getLineInfo()`, `dashboardService.getWorkspacesData()`, etc., throughout your application.
+### realtimeService
+
+Real-time data streaming and subscriptions.
+
+```typescript
+// Key Methods
+realtimeService.subscribeToLineMetrics(lineId: string, callback: Callback): Subscription
+realtimeService.subscribeToWorkspaceMetrics(workspaceId: string, callback: Callback): Subscription
+realtimeService.unsubscribe(subscription: Subscription): void
+```
 
-## Development
+## Extension and Customization
 
-(Information about local development, building, and contributing to this package would go here.)
+The package supports several extension mechanisms:
+
+### DashboardOverrides
+
+The `DashboardOverridesContext` allows overriding specific components:
+
+```tsx
+import { DashboardOverridesProvider } from '@optifye/dashboard-core';
+
+// Custom components for overrides
+const CustomKPICard = (props) => <div>Custom KPI Card: {props.title}</div>;
+const CustomWorkspaceCard = (props) => <div>Custom Workspace: {props.name}</div>;
+
+function MyApp({ Component, pageProps }) {
+  const overrides = {
+    components: {
+      KPICard: CustomKPICard,
+      WorkspaceCard: CustomWorkspaceCard
+    },
+    hooks: {
+      // Hook overrides
+    },
+    views: {
+      // View overrides
+    }
+  };
+
+  return (
+    <DashboardOverridesProvider overrides={overrides}>
+      <Component {...pageProps} />
+    </DashboardOverridesProvider>
+  );
+}
+```
+
+### View Customization
+
+All view components accept extensive prop-based customization:
+
+```tsx
+<FactoryView
+  lineIds={['line1', 'line2']}
+  showEfficiency={true}
+  showOutput={true}
+  showPPH={true}
+  refreshInterval={30000}
+  onLineSelect={(lineId) => console.log(`Selected line: ${lineId}`)}
+  customHeader={<MyCustomHeader />}
+  customFooter={<MyCustomFooter />}
+/>
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **React Version Compatibility**
+
+If you encounter React type compatibility issues between the package and your application, use type casting:
+
+```tsx
+import ComponentOriginal from '@optifye/dashboard-core/components/path/Component';
+const Component = ComponentOriginal as any;
+```
+
+2. **Supabase Client Not Initialized**
+
+Error: "Supabase client not initialized in @optifye/dashboard-core. Use SupabaseProvider."
+
+Solution: Ensure your application is wrapped with `SupabaseProvider` and a valid Supabase client is provided.
+
+3. **Missing Dashboard Configuration**
+
+Error: "Dashboard configuration not found. Use DashboardProvider."
+
+Solution: Ensure your application is wrapped with `DashboardProvider` and valid configuration is provided.
+
+## Contributing
+
+This package is continuously evolving. For contributions, please follow the established code patterns and ensure all tests pass.
+
+## License
+
+Proprietary - All rights reserved. This package is for internal use only.
 
 ## Publishing to npm
 
@@ -230,10 +658,20 @@ This package is published to npm as `@optifye/dashboard-core` and follows semant
 
 ### How to trigger a new release
 
-1. Create a changeset for your changes: `pnpm changeset`
+1. Create a changeset for your changes: `pnpm changeset` or `npx changeset`
 2. Choose the appropriate version bump (patch, minor, major)
-3. Create a PR with "RELEASE" in the title
-4. When merged, the GitHub Actions workflow will automatically publish the package to npm
+3. Commit the changeset file and push your branch
+4. Run `npx changeset version` to update package.json and CHANGELOG.md
+5. Commit the version changes
+6. Create a PR with **"RELEASE"** (all caps) in the title
+7. When merged, the GitHub Actions workflow will automatically publish the package to npm
+
+**Important:** The release workflow is triggered by PR merges, not direct pushes to main. The PR title MUST contain "RELEASE" for the workflow to run.
+
+### Example Release PR Title
+```
+RELEASE v2.0.1: Fix Next.js CSS import error
+```
 
 ### Package Repository