@optifye/dashboard-core 1.0.0

package/README.md

@@ -0,0 +1,244 @@
+# @optifye/dashboard-core
+
+A reusable React component library and utility toolkit for building dashboard functionalities, tailored for Optifye applications.
+
+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.
+
+## Features
+
+-   **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.
+
+
+## Installation
+
+```bash
+npm install @optifye/dashboard-core
+# or
+yarn add @optifye/dashboard-core
+```
+
+## Quick Start & Usage
+
+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).
+
+```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';
+
+// 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!,
+  entityConfig: {
+    companyId: process.env.NEXT_PUBLIC_COMPANY_ID!,
+    // ... other entity-specific IDs like factoryId, defaultLineId etc.
+  },
+  // ... other configurations like theme, analytics, dateTimeConfig etc.
+};
+
+function MyApp({ Component, pageProps }: AppProps) {
+  return (
+    <DashboardProvider config={appConfig}>
+      <AuthProvider> { /* For authentication */ }
+        <DashboardOverridesProvider overrides={{ /* your component overrides */ }}>
+          <Component {...pageProps} />
+        </DashboardOverridesProvider>
+      </AuthProvider>
+    </DashboardProvider>
+  );
+}
+
+export default MyApp;
+```
+
+### Configuration (`DashboardConfig`)
+
+The `DashboardConfig` object is crucial for tailoring the package to your specific application instance. It allows you to define:
+
+-   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...
+
+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).
+
+## Core Modules
+
+This package is organized into several core modules:
+
+-   **`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.
+
+## Utility Hooks
+
+-   **`useNavigation`**: Abstracted navigation API.
+-   **`useDateFormatter`**: Configured date/time formatting.
+-   **`useWorkspaceNavigation`**: Utilities for workspace navigation parameters.
+-   **`useFormatNumber`**: Configured number formatting.
+
+## UI Components
+
+`@optifye/dashboard-core` provides a suite of reusable UI components.
+
+### Common Components
+
+-   **`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`
+
+### Dashboard Components
+
+#### Line Components
+
+-   **`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`
+
+#### Workspace Components
+
+-   **`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`
+
+#### Grid Components
+
+-   **`WorkspaceGrid`**: Layout for arranging `WorkspaceCard` components.
+    -   **Location**: `packages/dashboard-core/src/components/dashboard/grid/WorkspaceGrid.tsx`
+
+### Chart Components
+
+-   **`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`
+
+### KPI Components
+
+-   **`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`
+
+### Navigation Components
+
+-   **`SideNavBar`**: Configurable side navigation bar.
+    -   **Location**: `packages/dashboard-core/src/components/navigation/SideNavBar.tsx`
+
+### Layout Components
+
+-   **`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`
+
+
+### Leaderboard Components
+
+Location: `src/components/dashboard/leaderboard/`
+
+*   **`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.
+
+## Usage
+
+To use the `@optifye/dashboard-core` service factory in your application:
+
+1.  **Ensure you have a Supabase client instance initialized in your application.**
+
+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.
+
+3.  **Create the service instance:**
+
+```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
+
+// 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
+  }
+};
+
+export const dashboardService = createDashboardService(appDashboardConfig, supabase);
+```
+
+Now you can use `dashboardService.getLineInfo()`, `dashboardService.getWorkspacesData()`, etc., throughout your application.
+
+## Development
+
+(Information about local development, building, and contributing to this package would go here.)
+
+## Publishing to npm
+
+This package is published to npm as `@optifye/dashboard-core` and follows semantic versioning. New releases are automatically published when a PR with "RELEASE" in the title is merged to the main branch.
+
+### How to trigger a new release
+
+1. Create a changeset for your changes: `pnpm 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
+
+### Package Repository
+
+The package repository field has been properly formatted for npm publishing standards.
+
+## License
+
+(License information, e.g., MIT, would go here.)