fix(dees-statsgrid): Adjust stats grid styling for better alignment and improved visualizations in gauge and trend tiles.

2025-06-10 18:58:05 +00:00
parent f7e4582fde
commit cd86001713
4 changed files with 268 additions and 26 deletions
--- a/readme.md
+++ b/readme.md
@ -15,7 +15,7 @@ npm install @design.estate/dees-catalog
 | Core UI | `DeesButton`, `DeesBadge`, `DeesChips`, `DeesIcon`, `DeesLabel`, `DeesSpinner`, `DeesToast` |
 | Forms | `DeesForm`, `DeesInputText`, `DeesInputCheckbox`, `DeesInputDropdown`, `DeesInputRadio`, `DeesInputFileupload`, `DeesInputIban`, `DeesInputPhone`, `DeesInputQuantitySelector`, `DeesInputMultitoggle`, `DeesFormSubmit` |
 | Layout | `DeesAppuiBase`, `DeesAppuiMainmenu`, `DeesAppuiMainselector`, `DeesAppuiMaincontent`, `DeesAppuiAppbar`, `DeesMobileNavigation` |
-| Data Display | `DeesTable`, `DeesDataviewCodebox`, `DeesDataviewStatusobject`, `DeesPdf` |
+| Data Display | `DeesTable`, `DeesDataviewCodebox`, `DeesDataviewStatusobject`, `DeesPdf`, `DeesStatsGrid` |
 | Visualization | `DeesChartArea`, `DeesChartLog` |
 | Dialogs & Overlays | `DeesModal`, `DeesContextmenu`, `DeesSpeechbubble`, `DeesWindowlayer` |
 | Navigation | `DeesStepper`, `DeesProgressbar` |
@ -528,6 +528,213 @@ Key Features:
  - Responsive layout
  - Loading states

+#### `DeesStatsGrid`
+A responsive grid component for displaying statistical data with various visualization types including numbers, gauges, percentages, and trends.
+
+```typescript
+<dees-statsgrid
+  .tiles=${[
+    {
+      id: 'revenue',
+      title: 'Total Revenue',
+      value: 125420,
+      unit: '$',
+      type: 'number',
+      icon: 'faDollarSign',
+      description: '+12.5% from last month',
+      color: '#22c55e',
+      actions: [
+        {
+          name: 'View Details',
+          iconName: 'faChartLine',
+          action: async () => {
+            console.log('Viewing revenue details');
+          }
+        },
+        {
+          name: 'Export Data',
+          iconName: 'faFileExport',
+          action: async () => {
+            console.log('Exporting revenue data');
+          }
+        }
+      ]
+    },
+    {
+      id: 'cpu',
+      title: 'CPU Usage',
+      value: 73,
+      type: 'gauge',
+      icon: 'faMicrochip',
+      gaugeOptions: {
+        min: 0,
+        max: 100,
+        thresholds: [
+          { value: 0, color: '#22c55e' },
+          { value: 60, color: '#f59e0b' },
+          { value: 80, color: '#ef4444' }
+        ]
+      }
+    },
+    {
+      id: 'storage',
+      title: 'Storage Used',
+      value: 65,
+      type: 'percentage',
+      icon: 'faHardDrive',
+      description: '650 GB of 1 TB',
+      color: '#3b82f6'
+    },
+    {
+      id: 'requests',
+      title: 'API Requests',
+      value: '1.2k',
+      unit: '/min',
+      type: 'trend',
+      icon: 'faServer',
+      trendData: [45, 52, 38, 65, 72, 68, 75, 82, 79, 85, 88, 92]
+    },
+    {
+      id: 'uptime',
+      title: 'System Uptime',
+      value: '99.95%',
+      type: 'text',
+      icon: 'faCheckCircle',
+      color: '#22c55e',
+      description: 'Last 30 days'
+    }
+  ]}
+  .gridActions=${[
+    {
+      name: 'Refresh',
+      iconName: 'faSync',
+      action: async () => {
+        console.log('Refreshing stats...');
+      }
+    },
+    {
+      name: 'Export Report',
+      iconName: 'faFileExport',
+      action: async () => {
+        console.log('Exporting stats report...');
+      }
+    }
+  ]}
+  .minTileWidth=${250}  // Minimum tile width in pixels
+  .gap=${16}            // Gap between tiles in pixels
+></dees-statsgrid>
+```
+
+Key Features:
+- Auto-responsive grid layout with configurable minimum tile width
+- Multiple tile types for different data visualizations
+- Full theme support (light/dark mode)
+- Interactive tiles with action support
+- Grid-level and tile-level actions
+- Smooth animations and transitions
+- Icon support for visual hierarchy
+
+Tile Types:
+1. **`number`** - Display numeric values with optional units
+   - Large, prominent value display
+   - Optional unit display
+   - Custom color support
+   - Description text
+
+2. **`gauge`** - Circular gauge visualization
+   - Min/max value configuration
+   - Color thresholds for visual alerts
+   - Animated value transitions
+   - Compact circular design
+
+3. **`percentage`** - Progress bar visualization
+   - Horizontal progress bar
+   - Percentage display overlay
+   - Custom color support
+   - Ideal for capacity metrics
+
+4. **`trend`** - Mini sparkline chart
+   - Array of numeric values for trend data
+   - Area chart visualization
+   - Current value display
+   - Responsive SVG rendering
+
+5. **`text`** - Simple text display
+   - Flexible text content
+   - Custom color support
+   - Ideal for status messages
+
+Action System:
+- **Grid Actions**: Displayed as buttons in the grid header
+  - Apply to the entire stats grid
+  - Use standard `dees-button` components
+  - Support icons and text
+
+- **Tile Actions**: Context-specific actions per tile
+  - Single action: Direct click on tile
+  - Multiple actions: Right-click context menu
+  - Actions access tile data through closures
+  - Consistent with other library components
+
+Configuration Options:
+- `tiles`: Array of `IStatsTile` objects defining the grid content
+- `gridActions`: Array of actions for the entire grid
+- `minTileWidth`: Minimum width for tiles (default: 250px)
+- `gap`: Space between tiles (default: 16px)
+
+Best Practices:
+1. **Data Organization**
+   - Group related metrics together
+   - Use consistent units and scales
+   - Provide meaningful descriptions
+   - Choose appropriate tile types for data
+
+2. **Visual Hierarchy**
+   - Use colors strategically for alerts
+   - Include relevant icons
+   - Keep titles concise
+   - Balance tile types for visual interest
+
+3. **Interactivity**
+   - Provide relevant actions for detailed views
+   - Use tile actions for item-specific operations
+   - Use grid actions for global operations
+   - Keep action names clear and concise
+
+4. **Performance**
+   - Update only changed tiles
+   - Use reasonable update intervals
+   - Batch updates when possible
+   - Consider data volume for trends
+
+Common Use Cases:
+- System monitoring dashboards
+- Business intelligence displays
+- Performance metrics
+- Resource utilization
+- Real-time statistics
+- KPI tracking
+
+Integration Example:
+```typescript
+// Real-time updates
+setInterval(() => {
+  const grid = document.querySelector('dees-statsgrid');
+  const updatedTiles = [...grid.tiles];
+  
+  // Update specific tile
+  const cpuTile = updatedTiles.find(t => t.id === 'cpu');
+  cpuTile.value = Math.round(Math.random() * 100);
+  
+  // Update trend data
+  const trendTile = updatedTiles.find(t => t.id === 'requests');
+  trendTile.trendData = [...trendTile.trendData.slice(1), 
+    Math.round(Math.random() * 100)];
+  
+  grid.tiles = updatedTiles;
+}, 3000);
+```
+
 ### Visualization Components

 #### `DeesChartArea`