[DataTables] Add DataTables UX integration

src/DataTables/.gitattributes

@@ -0,0 +1,8 @@
+/.gitattributes export-ignore
+/.gitignore export-ignore
+/.symfony.bundle.yaml export-ignore
+/assets/src export-ignore
+/assets/test export-ignore
+/assets/vitest.config.js export-ignore
+/phpunit.xml.dist export-ignore
+/tests export-ignore

src/DataTables/.gitignore

@@ -0,0 +1,4 @@
+/vendor/
+.phpunit.result.cache
+.php_cs.cache
+composer.lock

src/DataTables/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2020-present Fabien Potencier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

src/DataTables/README.md

@@ -0,0 +1,30 @@
+# Symfony UX DataTables
+
+Symfony UX DataTables is a Symfony bundle integrating the [DataTables](https://datatables.net/)
+library in Symfony applications. It is part of [the Symfony UX initiative](https://ux.symfony.com/).
+
+**This repository is a READ-ONLY sub-tree split**. See
+https://github.com/symfony/ux to create issues or submit pull requests.
+
+## Sponsor
+
+The Symfony UX packages are [backed][1] by [Mercure.rocks][2].
+
+Create real-time experiences in minutes! Mercure.rocks provides a realtime API service
+that is tightly integrated with Symfony: create UIs that update in live with UX Turbo,
+send notifications with the Notifier component, expose async APIs with API Platform and
+create low level stuffs with the Mercure component. We maintain and scale the complex
+infrastructure for you!
+
+Help Symfony by [sponsoring][3] its development!
+
+## Resources
+
+-   [Documentation](https://symfony.com/bundles/ux-datatables/current/index.html)
+-   [Report issues](https://github.com/symfony/ux/issues) and
+    [send Pull Requests](https://github.com/symfony/ux/pulls)
+    in the [main Symfony UX repository](https://github.com/symfony/ux)
+
+[1]: https://symfony.com/backers
+[2]: https://mercure.rocks
+[3]: https://symfony.com/sponsor

src/DataTables/assets/dist/controller.d.ts

@@ -0,0 +1,9 @@
+import { Controller } from '@hotwired/stimulus';
+export default class extends Controller {
+    readonly viewValue: any;
+    static values: {
+        view: ObjectConstructor;
+    };
+    connect(): void;
+    private dispatchEvent;
+}

src/DataTables/assets/dist/controller.js

@@ -0,0 +1,33 @@
+import { Controller } from '@hotwired/stimulus';
+import DataTable from 'datatables.net-dt';
+
+let isDataTableInitialized = false;
+class default_1 extends Controller {
+    constructor() {
+        super(...arguments);
+        this.table = null;
+    }
+    connect() {
+        if (isDataTableInitialized) {
+            return;
+        }
+        if (!(this.element instanceof HTMLTableElement)) {
+            throw new Error('Invalid element');
+        }
+        const payload = this.viewValue;
+        this.dispatchEvent('pre-connect', {
+            config: payload,
+        });
+        this.table = new DataTable(this.element, payload);
+        this.dispatchEvent('connect', { table: this.table });
+        isDataTableInitialized = true;
+    }
+    dispatchEvent(name, payload) {
+        this.dispatch(name, { detail: payload, prefix: 'datatables' });
+    }
+}
+default_1.values = {
+    view: Object,
+};
+
+export { default_1 as default };

src/DataTables/assets/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@symfony/ux-datatables",
+  "description": "DataTables integration for Symfony",
+  "license": "MIT",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/controller.js",
+  "symfony": {
+    "controllers": {
+      "datatable": {
+        "main": "dist/controller.js",
+        "webpackMode": "eager",
+        "fetch": "eager",
+        "enabled": true,
+        "autoimport": {
+          "datatables.net-dt/css/dataTables.dataTables.min.css": true
+        }
+      }
+    },
+    "importmap": {
+      "@hotwired/stimulus": "^3.0.0",
+      "datatables.net-dt": "^2.1.5"
+    }
+  },
+  "peerDependencies": {
+    "@hotwired/stimulus": "^3.0.0",
+    "datatables.net-dt": "^2.1.5"
+  },
+  "devDependencies": {
+    "@hotwired/stimulus": "^3.0.0",
+    "datatables.net-dt": "^2.1.5"
+  }
+}

src/DataTables/assets/src/controller.ts

@@ -0,0 +1,49 @@
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { Controller } from '@hotwired/stimulus';
+import DataTable from 'datatables.net-dt';
+
+let isDataTableInitialized = false;
+
+export default class extends Controller {
+    declare readonly viewValue: any;
+
+    static values = {
+        view: Object,
+    };
+
+    private table: DataTable | null = null;
+
+    connect() {
+        if (isDataTableInitialized) {
+            return;
+        }
+
+        if (!(this.element instanceof HTMLTableElement)) {
+            throw new Error('Invalid element');
+        }
+
+        const payload = this.viewValue;
+
+        this.dispatchEvent('pre-connect', {
+            config: payload,
+        });
+
+        new DataTable(this.element as HTMLElement, payload);
+
+        this.dispatchEvent('connect', { table: this.table });
+
+        isDataTableInitialized = true;
+    }
+
+    private dispatchEvent(name: string, payload: any) {
+        this.dispatch(name, { detail: payload, prefix: 'datatables' });
+    }
+}

src/DataTables/composer.json

@@ -0,0 +1,53 @@
+{
+  "name": "symfony/ux-datatables",
+  "type": "symfony-bundle",
+  "description": "DataTables.net integration for Symfony",
+  "keywords": [
+    "symfony-ux"
+  ],
+  "homepage": "https://symfony.com",
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "Tanguy Lemarié",
+      "email": "[email protected]"
+    },
+    {
+      "name": "Symfony Community",
+      "homepage": "https://symfony.com/contributors"
+    }
+  ],
+  "autoload": {
+    "psr-4": {
+      "Symfony\\UX\\DataTables\\": "src/"
+    }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "Symfony\\UX\\DataTables\\Tests\\": "tests/"
+    }
+  },
+  "require": {
+    "php": ">=8.1",
+    "symfony/config": "^5.4|^6.0|^7.0",
+    "symfony/dependency-injection": "^5.4|^6.0|^7.0",
+    "symfony/http-kernel": "^5.4|^6.0|^7.0",
+    "symfony/stimulus-bundle": "^2.9.1"
+  },
+  "require-dev": {
+    "symfony/framework-bundle": "^5.4|^6.0|^7.0",
+    "symfony/phpunit-bridge": "^5.4|^6.0|^7.0",
+    "symfony/twig-bundle": "^5.4|^6.0|^7.0",
+    "symfony/var-dumper": "^5.4|^6.0|^7.0"
+  },
+  "conflict": {
+    "symfony/flex": "<1.13"
+  },
+  "extra": {
+    "thanks": {
+      "name": "symfony/ux",
+      "url": "https://github.com/symfony/ux"
+    }
+  },
+  "minimum-stability": "dev"
+}

src/DataTables/doc/index.rst

@@ -0,0 +1,146 @@
+Symfony UX DataTables
+=====================
+
+Symfony UX DataTables is a Symfony bundle integrating the
+`DataTables`_ library in Symfony applications.
+It is part of `the Symfony UX initiative`_.
+
+Installation
+------------
+
+.. caution::
+
+    Before you start, make sure you have `StimulusBundle configured in your app`_.
+
+Install the bundle using Composer and Symfony Flex:
+
+.. code-block:: terminal
+
+    $ composer require symfony/ux-datatables
+
+If you're using WebpackEncore, install your assets and restart Encore (not
+needed if you're using AssetMapper):
+
+.. code-block:: terminal
+
+    $ npm install --force
+    $ npm run watch
+
+    # or use yarn
+    $ yarn install --force
+    $ yarn watch
+
+Usage
+-----
+
+To use Symfony UX DataTables, inject the ``DataTableBuilderInterface`` service
+and create tables in PHP::
+
+    // ...
+    use Symfony\UX\DataTables\Builder\DataTableBuilderInterface;
+    use Symfony\UX\DataTables\Model\DataTable;
+
+    class HomeController extends AbstractController
+    {
+        #[Route('/', name: 'app_homepage')]
+        public function index(DataTableBuilderInterface $tableBuilder): Response
+        {
+            $table= $tableBuilder->('usersTable');
+
+            $table->setData([
+                'columns' => ['First name', 'Last name'],
+                'data' => [
+                    ['John', 'Doe'],
+                    ['Jane', 'Smith'],
+                ],
+            ]);
+
+            $table->setOptions([
+                'order' => [
+                    ['idx': 1, 'dir': 'asc']
+                ],
+            ]);
+
+            return $this->render('home/index.html.twig', [
+                'table' => $table,
+            ]);
+        }
+    }
+
+All options and data are provided as-is to DataTables. You can read
+`DataTables documentation`_ to discover them all.
+
+Once created in PHP, a table can be displayed using Twig:
+
+.. code-block:: html+twig
+
+    {{ render_datatable(table) }}
+
+    {# You can pass HTML attributes as a second argument to add them on the <table> tag #}
+    {{ render_datatable(table, {'class': 'my-table'}) }}
+
+Extend the default behavior
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Symfony UX DataTables allows you to extend its default behavior using a
+custom Stimulus controller:
+
+.. code-block:: javascript
+
+    // mytable_controller.js
+
+    import { Controller } from '@hotwired/stimulus';
+
+    export default class extends Controller {
+        connect() {
+            this.element.addEventListener('datatables:pre-connect', this._onPreConnect);
+            this.element.addEventListener('datatables:connect', this._onConnect);
+        }
+
+        disconnect() {
+            // You should always remove listeners when the controller is disconnected to avoid side effects
+            this.element.removeEventListener('datatables:pre-connect', this._onPreConnect);
+            this.element.removeEventListener('datatables:connect', this._onConnect);
+        }
+
+        _onPreConnect(event) {
+            // The table is not yet created
+            // You can access the config that will be passed to "new DataTable()"
+            console.log(event.detail.config);
+
+            // For instance you can define a render callback for a given column
+            event.detail.config.columns[0].render = function (data, type, row, meta) {
+				return '<a href="' + data + '">Download</a>';
+			}
+        }
+
+        _onConnect(event) {
+            // The table was just created
+            console.log(event.detail.table); // You can access the table instance using the event details
+
+            // For instance you can listen to additional events
+            event.detail.table.on('init', (event) => {
+                /* ... */
+            };
+            event.detail.table.on('draw', (event) => {
+                /* ... */
+            };
+        }
+    }
+
+Then in your render call, add your controller as an HTML attribute:
+
+.. code-block:: twig
+
+    {{ render_datatable(table, {'data-controller': 'mytable'}) }}
+
+Backward Compatibility promise
+------------------------------
+
+This bundle aims at following the same Backward Compatibility promise as
+the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html.
+
+.. _`DataTables`: https://datatables.net
+.. _`the Symfony UX initiative`: https://ux.symfony.com/
+.. _`DataTables documentation`: https://datatables.net/manual/
+.. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html