feat(datatables): add column sum calculation feature

- Add sum() method to Column class for enabling footer calculations
- Implement getSumColumns() method in Datatable class to identify sum-enabled columns
- Add automatic footerCallback generation with JavaScript for client-side sum calculations
- Add conditional table footer in datatable Blade component when sum columns exist
- Add comprehensive test coverage with SumTest and TestSumDatatable classes
- Update column documentation with sum method usage and features
- Support HTML content extraction and locale-formatted number display in footer

Author: Sébastien HEYD

docs/docs/8.x/datatables/column.md

@@ -50,6 +50,7 @@ public function columns(): array
 | [class](#class)                 | Sets the column class                                  |
 | [width](#width)                 | Sets the column width                                  |
 | [hidden](#hidden)               | Hide the column                                        |
+| [sum](#sum)                     | Enable sum calculation in footer for numeric columns   |
 
 ---
 
@@ -319,3 +320,33 @@ Hide the column.
 ```php
 ->hidden()
 ```
+
+## sum
+
+Enables automatic sum calculation for numeric columns. When applied to a column, the sum of all visible values will be displayed in the table footer.
+
+```php
+Column::add('Price')
+    ->data('price')
+    ->sum(),
+
+Column::add('Quantity') 
+    ->data('quantity')
+    ->sum(),
+```
+
+**Features**
+
+- **Automatic Calculation**: Sums are calculated client-side using JavaScript for optimal performance
+- **Locale Formatting**: Numbers are formatted according to the user's locale (e.g., `1,234.56`)
+- **Dynamic Updates**: Sums update automatically when filtering or searching the table
+- **Current Page Only**: Calculations are performed on currently visible rows only
+- The column data should contain numeric values
+- Non-numeric values are treated as zero in calculations
+- Works with both integer and decimal numbers
+- The sum is calculated using `parseFloat()` to handle both integers and decimals
+- Empty or non-numeric cells contribute 0 to the sum
+- The footer is automatically generated when at least one column has sum enabled
+- Multiple columns can have sum calculations simultaneously
+- **HTML-formatted columns**: The sum calculation automatically extracts numeric values from HTML content (e.g., `<span class="badge">5</span>` → `5`)
+- Special handling for empty indicators: dots (`.`) are treated as zero values

src/Datatables/Column.php

@@ -15,6 +15,7 @@ class Column
     protected $raw = null;
     protected $title = '';
     protected $tooltip = '';
+    protected $sum = false;
 
     /**
      * Instanciate a new column.
@@ -331,6 +332,18 @@ public function __get($name)
         return null;
     }
 
+    /**
+     * Enable calculation of the sum for this column in the footer.
+     *
+     * @return Column
+     */
+    public function sum(): Column
+    {
+        $this->sum = true;
+
+        return $this;
+    }
+
     /**
      * Magic method to know if magic property or attribute is set.
      *

src/Datatables/Datatable.php

@@ -41,6 +41,7 @@ abstract class Datatable
         'condensed'    => false,
         'lengthMenu'   => [[10, 25, 50, 100, -1], [10, 25, 50, 100, '∞']],
         'buttons'      => ['filters'],
+        'footerCallback' => null,
     ];
 
     /**
@@ -537,6 +538,23 @@ protected function getRequestSearchValue($name)
         return request()->input('columns')[$idx]['search']['value'];
     }
 
+    /**
+     * Get columns that must calculate a sum.
+     *
+     * @return array
+     */
+    public function getSumColumns(): array
+    {
+        $sumColumns = [];
+        foreach ($this->getColumns() as $index => $column) {
+            if ($column->sum) {
+                $sumColumns[] = $index;
+            }
+        }
+
+        return $sumColumns;
+    }
+
     /**
      * Magic method to get property or attribute.
      *
@@ -559,6 +577,41 @@ public function __get($name)
             return json_encode($this->attributes[$name]);
         }
 
+        if ($name === 'footerCallback') {
+            $sumColumns = $this->getSumColumns();
+            if (! empty($sumColumns)) {
+                $columnsJson = json_encode($sumColumns);
+
+                return "function (row, data, start, end, display) {
+                    var api = this.api();
+                    var sumColumns = $columnsJson;
+
+                    sumColumns.forEach(function(colIndex) {
+                        var total = api
+                            .column(colIndex, {page: 'current'})
+                            .data()
+                            .reduce(function (a, b) {
+                                // Extract numeric value from HTML content if present
+                                var val = b;
+                                if (typeof b === 'string' && b.includes('<')) {
+                                    // Extract text content from HTML tags
+                                    var tempDiv = document.createElement('div');
+                                    tempDiv.innerHTML = b;
+                                    val = tempDiv.textContent || tempDiv.innerText || '';
+                                    // Replace '.' with 0 for empty level indicators
+                                    val = val === '.' ? '0' : val;
+                                }
+                                return a + (parseFloat(val) || 0);
+                            }, 0);
+
+                        \$(api.column(colIndex).footer()).html(total.toLocaleString());
+                    });
+                }";
+            }
+
+            return $this->attributes[$name];
+        }
+
         if (isset($this->attributes[$name])) {
             return $this->attributes[$name];
         }

src/resources/views/components/datatable.blade.php

@@ -44,6 +44,15 @@
         @endif
         </thead>
         <tbody></tbody>
+        @if(!empty($datatable->getSumColumns()))
+        <tfoot>
+        <tr>
+            @foreach($datatable->getColumns() as $index => $column)
+                <th>{{ $column->sum ? '0' : '' }}</th>
+            @endforeach
+        </tr>
+        </tfoot>
+        @endif
     </table>
 </div>
 @include('boilerplate::load.async.datatables', ['buttons' => true])
@@ -89,6 +98,9 @@
                     {!! $column->get() !!},
                 @endforeach
             ],
+            @if($datatable->footerCallback)
+                footerCallback: {!! $datatable->footerCallback !!},
+            @endif
             initComplete: $.fn.dataTable.init,
             dom:
                 "<'d-flex flex-wrap justify-content-between'<'dt_top_left mb-2 mr-2'l><'dt_top_right d-flex mb-2'f>>" +

tests/Datatables/SumTest.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace Sebastienheyd\Boilerplate\Tests\Datatables;
+
+use Sebastienheyd\Boilerplate\Tests\TestCase;
+
+class SumTest extends TestCase
+{
+    public function testColumnSumMethod()
+    {
+        $datatable = new TestSumDatatable();
+        $columns = $datatable->getColumns();
+
+        // Vérifier que les colonnes Price et Quantity ont la propriété sum activée
+        $this->assertTrue($columns[2]->sum); // Price column
+        $this->assertTrue($columns[3]->sum); // Quantity column
+        $this->assertFalse($columns[0]->sum); // ID column
+        $this->assertFalse($columns[1]->sum); // Name column
+    }
+
+    public function testGetSumColumns()
+    {
+        $datatable = new TestSumDatatable();
+        $sumColumns = $datatable->getSumColumns();
+
+        // Vérifier que les index des colonnes avec sum sont corrects
+        $this->assertEquals([2, 3], $sumColumns);
+    }
+
+    public function testFooterCallbackGeneration()
+    {
+        $datatable = new TestSumDatatable();
+        $footerCallback = $datatable->footerCallback;
+
+        // Vérifier que le footerCallback est généré
+        $this->assertNotNull($footerCallback);
+        $this->assertStringContainsString('function (row, data, start, end, display)', $footerCallback);
+        $this->assertStringContainsString('[2,3]', $footerCallback); // Les colonnes avec sum
+    }
+
+    public function testFooterCallbackHandlesFormattedData()
+    {
+        $datatable = new TestSumDatatable();
+        $footerCallback = $datatable->footerCallback;
+
+        // Vérifier que le JavaScript gère le contenu HTML
+        $this->assertStringContainsString('tempDiv.innerHTML = b;', $footerCallback);
+        $this->assertStringContainsString('tempDiv.textContent', $footerCallback);
+        $this->assertStringContainsString("val === '.' ? '0' : val", $footerCallback);
+    }
+}

tests/Datatables/TestSumDatatable.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace Sebastienheyd\Boilerplate\Tests\Datatables;
+
+use Sebastienheyd\Boilerplate\Datatables\Column;
+use Sebastienheyd\Boilerplate\Datatables\Datatable;
+
+class TestSumDatatable extends Datatable
+{
+    public $slug = 'test-sum';
+
+    public function datasource()
+    {
+        return collect([
+            ['id' => 1, 'name' => 'Item 1', 'price' => 100.50, 'quantity' => 5],
+            ['id' => 2, 'name' => 'Item 2', 'price' => 75.25, 'quantity' => 3],
+            ['id' => 3, 'name' => 'Item 3', 'price' => 200.00, 'quantity' => 2],
+        ]);
+    }
+
+    public function columns(): array
+    {
+        return [
+            Column::add('ID')
+                ->data('id'),
+
+            Column::add('Name')
+                ->data('name'),
+
+            Column::add('Price')
+                ->data('price')
+                ->sum(),
+
+            Column::add('Quantity')
+                ->data('quantity')
+                ->sum(),
+        ];
+    }
+}