myio-js-library 0.1.21 → 0.1.23

package/README.md

@@ -945,6 +945,362 @@ The component includes premium MyIO styling with:
 - Responsive design for mobile and desktop
 - Portuguese month names and day abbreviations
 
+### Premium Date Range Input Component
+
+#### `createInputDateRangePickerInsideDIV(params: CreateInputDateRangePickerInsideDIVParams): Promise<DateRangeInputController>`
+
+Creates a complete, beautifully styled date range input inside a target DIV container, combining the functionality of `createDateRangePicker` with premium MyIO styling. This component automatically creates the HTML structure, injects styling, and provides a clean API for ThingsBoard widgets and other applications.
+
+**Parameters:**
+- `params: CreateInputDateRangePickerInsideDIVParams` - Configuration object:
+  - `containerId: string` - The DIV id where the input will be created (required)
+  - `inputId: string` - The id to set on the created input (required)
+  - `label?: string` - Optional label text (default: "Período de Datas")
+  - `placeholder?: string` - Input placeholder (default: "Clique para selecionar período")
+  - `pickerOptions?: CreateDateRangePickerOptions` - Pass-through options for createDateRangePicker
+  - `classNames?: object` - Custom CSS classes for wrapper, label, input, and helper
+  - `injectStyles?: boolean` - Inject premium MyIO styling (default: true)
+  - `showHelper?: boolean` - Show helper text with format info (default: true)
+
+**Returns:** Promise resolving to `DateRangeInputController` object with:
+- `input: HTMLInputElement` - The created input element
+- `container: HTMLElement` - The target container element
+- `wrapper: HTMLElement` - The wrapper element created by this component
+- `picker: DateRangeControl` - The date range picker instance
+- `getDisplayValue(): string` - Get current display value from input
+- `getDates(): DateRangeResult` - Get current date range data
+- `setDates(startISO: string, endISO: string): void` - Set date range programmatically
+- `setHelperText(text: string, type?: 'default' | 'success' | 'error'): void` - Update helper text
+- `destroy(): void` - Clean up and remove all created elements
+
+**Key Features:**
+- **Automatic HTML Creation**: Creates complete styled input structure inside target DIV
+- **Premium MyIO Styling**: Beautiful styling matching demos/energy.html with purple brand colors
+- **Container-Based**: Works with any DIV container, perfect for ThingsBoard widgets
+- **Accessibility Built-in**: ARIA labels, keyboard navigation, screen reader support
+- **Responsive Design**: Mobile-friendly with proper touch targets
+- **Error Handling**: Robust validation and graceful error recovery
+- **Memory Management**: Proper cleanup with destroy() method
+
+**Usage Example:**
+```javascript
+import { createInputDateRangePickerInsideDIV } from 'myio-js-library';
+
+const controller = await createInputDateRangePickerInsideDIV({
+  containerId: 'date-picker-container',
+  inputId: 'energy-date-range',
+  label: 'Período de Análise',
+  pickerOptions: {
+    presetStart: '2025-09-01',
+    presetEnd: '2025-09-25',
+    onApply: (result) => {
+      console.log('Date range selected:', result);
+      // result.startISO: "2025-09-01T00:00:00-03:00"
+      // result.endISO: "2025-09-25T23:59:59-03:00"
+      loadEnergyData(result.startISO, result.endISO);
+    }
+  }
+});
+
+// Get current selection
+const dates = controller.getDates();
+console.log('Current range:', dates.startISO, 'to', dates.endISO);
+
+// Update helper text
+controller.setHelperText('Período válido selecionado', 'success');
+
+// Clean up when done
+controller.destroy();
+```
+
+**ThingsBoard Widget Integration:**
+```html
+<script src="https://unpkg.com/myio-js-library@latest/dist/myio-js-library.umd.min.js"></script>
+<script>
+  const { createInputDateRangePickerInsideDIV } = MyIOLibrary;
+  
+  // In your widget's onInit function
+  self.onInit = async function() {
+    try {
+      // Create date range picker in existing container
+      self.dateRangePicker = await createInputDateRangePickerInsideDIV({
+        containerId: 'widget-date-container',
+        inputId: 'energy-widget-dates',
+        label: 'Período de Datas',
+        placeholder: 'Selecione o período de análise',
+        pickerOptions: {
+          maxRangeDays: 31,
+          onApply: (result) => {
+            // Update widget state and reload data
+            updateWidgetData(result.startISO, result.endISO);
+          }
+        }
+      });
+      
+      console.log('[ENERGY] Date range picker initialized successfully');
+    } catch (error) {
+      console.error('[ENERGY] Failed to initialize date picker:', error);
+      // Fallback to legacy implementation
+      initLegacyDatePicker();
+    }
+  };
+
+  // Clean up on widget destroy
+  self.onDestroy = function() {
+    if (self.dateRangePicker) {
+      self.dateRangePicker.destroy();
+    }
+  };
+</script>
+```
+
+**Premium Styling Features:**
+- **MyIO Brand Colors**: Purple theme (#4A148C) with hover effects
+- **Responsive Layout**: Adapts to mobile and desktop with proper spacing
+- **Accessibility**: High contrast mode support, reduced motion support
+- **Visual Feedback**: Hover states, focus indicators, success/error states
+- **Typography**: Roboto font family with proper line heights
+- **Shadow Effects**: Subtle shadows and smooth transitions
+
+**Migration from Basic Implementation:**
+```javascript
+// OLD: Manual HTML + basic styling
+var $inputStart = $('input[name="startDatetimes"]');
+MyIOLibrary.createDateRangePicker($inputStart[0], options);
+
+// NEW: Automatic creation + premium styling
+const controller = await MyIOLibrary.createInputDateRangePickerInsideDIV({
+  containerId: 'date-container',
+  inputId: 'startDatetimes',
+  label: 'Período de Datas',
+  pickerOptions: options
+});
+```
+
+### Premium Modal Components
+
+The library includes four premium modal components for ThingsBoard dashboards that provide comprehensive device analytics and reporting capabilities.
+
+#### `openDashboardPopupReport(params: OpenDeviceReportParams): ModalHandle`
+
+Opens a device-specific daily consumption report modal with built-in date range picker, sortable table, and CSV export functionality.
+
+**Parameters:**
+- `ingestionId: string` - Data ingestion identifier (required)
+- `deviceId?: string` - Optional device ID for additional metadata
+- `identifier?: string` - Device identifier/code (e.g., "ENTRADA-001", "CHILLER-A")
+- `label?: string` - Human-readable label/name (e.g., "Outback", "Shopping Center Norte")
+- `ui?: object` - UI configuration (theme, width)
+- `api: object` - API configuration:
+  - `clientId?: string` - Client ID for data API
+  - `clientSecret?: string` - Client secret for data API
+  - `dataApiBaseUrl?: string` - Data API base URL
+  - `ingestionToken?: string` - Token for data ingestion access
+
+**Returns:** `ModalHandle` object with:
+- `close(): void` - Close the modal
+- `on(event: 'close'|'loaded'|'error', handler: Function): void` - Event listeners
+
+**Key Features:**
+- **Built-in Date Range Picker**: No need to specify dates in parameters
+- **Automatic Data Loading**: Fetches daily consumption data for selected period
+- **Sortable Table**: Click column headers to sort by date or consumption
+- **CSV Export**: Download report data with proper Brazilian formatting
+- **Responsive Design**: Works on desktop and mobile devices
+- **Error Handling**: Graceful error display and recovery
+
+**Usage Example:**
+```javascript
+import { openDashboardPopupReport } from 'myio-js-library';
+
+const modal = openDashboardPopupReport({
+  ingestionId: 'abc123-ingestion-id',
+  deviceId: 'device-uuid',
+  identifier: 'ENTRADA-001',
+  label: 'Outback Shopping',
+  api: {
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+    dataApiBaseUrl: 'https://api.data.apps.myio-bas.com',
+    ingestionToken: 'your-ingestion-token'
+  }
+});
+
+modal.on('loaded', (data) => {
+  console.log('Report loaded:', data.count, 'days');
+});
+
+modal.on('close', () => {
+  console.log('Modal closed');
+});
+```
+
+#### `openDashboardPopupAllReport(params: OpenAllReportParams): ModalHandle`
+
+Opens a customer-level energy consumption report modal with real-time data from the Customer Totals API. This modal provides comprehensive reporting across all devices for a customer with advanced sorting, filtering, and export capabilities.
+
+**Parameters:**
+- `customerId: string` - ThingsBoard customer ID (required)
+- `ui?: object` - UI configuration (theme, width)
+- `api: object` - API configuration:
+  - `clientId?: string` - Client ID for data API authentication
+  - `clientSecret?: string` - Client secret for data API authentication
+  - `dataApiBaseUrl?: string` - Data API base URL (default: 'https://api.data.apps.myio-bas.com')
+- `filters?: object` - Optional filtering configuration:
+  - `excludeLabels?: (RegExp | string)[]` - Patterns to exclude devices by label
+- `fetcher?: Function` - Optional custom fetcher for testing/mocking
+
+**Returns:** `ModalHandle` object with:
+- `close(): void` - Close the modal
+- `on(event: 'close'|'loaded'|'error', handler: Function): void` - Event listeners
+
+**Key Features:**
+- **Real Customer Totals API Integration**: Calls `/api/v1/telemetry/customers/{customerId}/energy/devices/totals`
+- **Built-in Date Range Picker**: Interactive date selection with validation
+- **Robust Data Processing**: Handles pagination, fallback chains, and data normalization
+- **Sortable Table Structure**: Sticky totals row + sortable columns (Identifier, Name, Consumption)
+- **Portuguese Locale Support**: Brazilian number formatting and sorting
+- **Comprehensive Error Handling**: Network failures, authentication, and validation errors
+- **CSV Export**: Consistent formatting with UI using `MyIOLibrary.formatEnergy`
+- **Production Ready**: Authentication via `fetchWithAuth` pattern with automatic token refresh
+
+**Usage Example:**
+```javascript
+import { openDashboardPopupAllReport } from 'myio-js-library';
+
+const modal = openDashboardPopupAllReport({
+  customerId: '73d4c75d-c311-4e98-a852-10a2231007c4',
+  api: {
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+    dataApiBaseUrl: 'https://api.data.apps.myio-bas.com'
+  },
+  filters: {
+    excludeLabels: [
+      /bomba.*secund[aá]ria/i,     // Regex patterns
+      /^administra[cç][aã]o\s*1$/i,
+      'Entrada Principal'           // Exact string matches
+    ]
+  }
+});
+
+modal.on('loaded', (data) => {
+  console.log('Customer report loaded:', data.count, 'devices');
+  console.log('Total consumption:', data.totalKwh, 'kWh');
+});
+
+modal.on('error', (error) => {
+  console.error('Report error:', error.message);
+});
+```
+
+**UMD Usage (ThingsBoard widgets):**
+```html
+<script src="https://unpkg.com/myio-js-library@latest/dist/myio-js-library.umd.min.js"></script>
+<script>
+  const { openDashboardPopupAllReport } = MyIOLibrary;
+  
+  const modal = openDashboardPopupAllReport({
+    customerId: 'your-customer-id',
+    api: {
+      clientId: 'your-client-id',
+      clientSecret: 'your-client-secret'
+    }
+  });
+  
+  modal.on('loaded', (data) => {
+    console.log('All stores report loaded with', data.count, 'devices');
+    console.log('Grand total:', data.totalKwh, 'kWh');
+  });
+</script>
+```
+
+**Data Flow:**
+```
+User clicks "Carregar" 
+→ Format timestamps with timezone offset
+→ Call Customer Totals API with fetchWithAuth
+→ Process response with mapCustomerTotalsResponse
+→ Apply sorting with applySorting (Portuguese locale)
+→ Update table with updateAllReportTable
+→ Update totals with updateGrandTotal
+→ Enable CSV export with habilitarBotaoExportAll
+```
+
+**API Integration:**
+```
+GET ${DATA_API_HOST}/api/v1/telemetry/customers/{customerId}/energy/devices/totals
+  ?startTime=2025-09-01T00%3A00%3A00-03%3A00
+  &endTime=2025-09-25T23%3A59%3A59-03%3A00
+
+Authorization: Bearer ${MyIOAuth.getToken()}
+```
+
+**Migration from Legacy Implementation:**
+```javascript
+// OLD: Mock/placeholder data
+MyIOLibrary.openDashboardPopupAllReport({
+  // Used mock data or device-by-device calls
+});
+
+// NEW: Real Customer Totals API
+MyIOLibrary.openDashboardPopupAllReport({
+  customerId: 'your-customer-id',        // ✅ Real customer ID
+  api: {
+    clientId: 'your-client-id',          // ✅ Real API credentials
+    clientSecret: 'your-client-secret'
+  }
+  // ✅ Calls real Customer Totals API endpoint
+  // ✅ Handles pagination automatically
+  // ✅ Robust error handling and recovery
+});
+```
+
+**UMD Usage (ThingsBoard widgets):**
+```html
+<script src="https://unpkg.com/myio-js-library@latest/dist/myio-js-library.umd.min.js"></script>
+<script>
+  const { openDashboardPopupReport } = MyIOLibrary;
+  
+  const modal = openDashboardPopupReport({
+    ingestionId: 'demo-ingestion-123',
+    deviceId: 'demo-device-123',
+    identifier: 'ENTRADA-001',
+    label: 'Outback',
+    api: { 
+      clientId: 'demo-client',
+      clientSecret: 'demo-secret',
+      dataApiBaseUrl: 'https://api.data.apps.myio-bas.com',
+      ingestionToken: 'demo-ingestion-token'
+    }
+  });
+  
+  modal.on('loaded', (data) => {
+    console.log('Device report loaded with', data.count, 'days of data');
+  });
+</script>
+```
+
+**Migration from Legacy API:**
+```javascript
+// OLD API (deprecated)
+MyIOLibrary.openDashboardPopupReport({
+  ingestionId: 'demo-ingestion-123',
+  deviceLabel: 'Entrada Subestação',    // ❌ Deprecated
+  storeLabel: 'Outback',                // ❌ Deprecated
+  date: { start: '2025-09-01', end: '2025-09-25' }, // ❌ Deprecated
+  api: { tbJwtToken: 'jwt-token' }      // ❌ Deprecated
+});
+
+// NEW API (recommended)
+MyIOLibrary.openDashboardPopupReport({
+  ingestionId: 'demo-ingestion-123',
+  identifier: 'ENTRADA-001',           // ✅ Clear device identifier
+  label: 'Outback',                    // ✅ Clear human-readable name
+  api: { ingestionToken: 'ingestion-token' } // ✅ Clear token purpose
+});
+```
+
 ### MYIO Components - Drag-to-Footer Dock Implementation
 
 The library includes three main interactive components for building comparative selection interfaces: