@rio-cloud/uikit-mcp 1.0.0 → 1.1.0

package/dist/docs/utilities/useTableExport.md

@@ -0,0 +1,404 @@
+# useTableExport
+
+*Category:* Utilities
+*Section:* Table & data hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useTableExport
+*Captured:* 2025-12-12T12:39:50.404Z
+
+The useTableExport hook provides a simple and reusable way to export tabular data as a downloadable CSV file in React applications. It supports custom delimiters, UTF-8 BOM for Excel compatibility, and column header mapping for more readable exports. This is especially useful for tables with user-facing data that may need to be downloaded for offline analysis or reporting.
+
+## useTableExport
+
+### Example: Example 1
+
+Export data
+
+IdFirst nameLast nameE-mail
+
+1GinaWatsicaLoyal.Feil57@hotmail.com
+2GunnerEbertErika59@hotmail.com
+3CandaceGloverTroy.Lebsack@hotmail.com
+4TommieDibbertLinwood_Anderson33@hotmail.com
+5LacyRippinAbby98@yahoo.com
+6EnaOsinskiCyril28@hotmail.com
+7EthylNolanTroy.Jast22@hotmail.com
+8NatashaAuerBeth.Huel78@hotmail.com
+9AftonLefflerTheresa.Witting@hotmail.com
+10ChaseKuhlmanNapoleon6@gmail.com
+
+#### Summary
+
+Export data
+
+IdFirst nameLast nameE-mail
+
+1GinaWatsicaLoyal.Feil57@hotmail.com
+2GunnerEbertErika59@hotmail.com
+3CandaceGloverTroy.Lebsack@hotmail.com
+4TommieDibbertLinwood_Anderson33@hotmail.com
+5LacyRippinAbby98@yahoo.com
+6EnaOsinskiCyril28@hotmail.com
+7EthylNolanTroy.Jast22@hotmail.com
+8NatashaAuerBeth.Huel78@hotmail.com
+9AftonLefflerTheresa.Witting@hotmail.com
+10ChaseKuhlmanNapoleon6@gmail.com
+
+#### React (tsx)
+
+```tsx
+import classNames from 'classnames';
+import faker from 'faker';
+
+import TableHead from '@rio-cloud/rio-uikit/TableHead';
+import TableCol, { type ColumnDetailsMap } from '@rio-cloud/rio-uikit/TableCol';
+import TableToolbar from '@rio-cloud/rio-uikit/TableToolbar';
+import useTableExport from '@rio-cloud/rio-uikit/useTableExport';
+import useSorting from '@rio-cloud/rio-uikit/useSorting';
+import Button from '@rio-cloud/rio-uikit/Button';
+
+type Driver = {
+    driverId: string;
+    firstName: string;
+    lastName: string;
+    email: string;
+};
+
+type ColumnLabel = { [key in keyof Driver]: string };
+
+const columnLabels: ColumnLabel = {
+    driverId: 'Id',
+    firstName: 'First name',
+    lastName: 'Last name',
+    email: 'E-mail',
+};
+
+const defaultColumnOrder = ['driverId', 'firstName', 'lastName', 'email'];
+
+const demoColumnsDetails: ColumnDetailsMap = {
+    driverId: {
+        width: 100,
+        defaultWidth: 200,
+        maxWidth: 300,
+    },
+    firstName: {
+        width: 200,
+        defaultWidth: 200,
+        maxWidth: 200,
+    },
+    lastName: {
+        width: 0, // Note: 0 means auto width
+        defaultWidth: 0,
+        maxWidth: 350,
+    },
+};
+
+// Function to generate random entries to work with.
+// Increase length to generate more items.
+const driverList: Driver[] = Array.from({ length: 10 }, (_, index) => ({
+    driverId: `${index + 1}`,
+    firstName: faker.name.firstName(),
+    lastName: faker.name.lastName(),
+    email: faker.internet.email(),
+}));
+
+export default () => {
+    const { sortedItems, sortKey, sortDirection, setSortKey, toggleDirection } = useSorting(driverList, 'driverId');
+
+    // Hook to export the Table data
+    const { exportToCSV } = useTableExport<Driver>();
+
+    const handleTableExport = () => {
+        exportToCSV({
+            data: sortedItems,
+            fileName: 'drivers.csv',
+            headers: columnLabels,
+        });
+    };
+
+    const handleSortChange = (event: React.MouseEvent<HTMLTableCellElement>) => {
+        const newSortBy = event.currentTarget.getAttribute('data-sortby');
+        if (newSortBy) {
+            setSortKey(newSortBy as keyof Driver);
+        }
+        if (newSortBy === sortKey) {
+            toggleDirection();
+        }
+    };
+
+    const tableClassNames = classNames(
+        'table',
+        'table-layout-fixed',
+        'table-column-overflow-hidden',
+        'table-bordered',
+        'table-sticky',
+        'table-hover',
+        'table-head-filled'
+    );
+
+    return (
+        <div>
+            <TableToolbar>
+                <div className='table-toolbar-container'>
+                    <div className='table-toolbar-group-right'>
+                        <div className='table-toolbar-column'>
+                            <Button iconName='rioglyph-download' onClick={handleTableExport}>
+                                Export data
+                            </Button>
+                        </div>
+                    </div>
+                </div>
+            </TableToolbar>
+
+            <div className='table-responsive'>
+                <table className={tableClassNames}>
+                    <colgroup>
+                        {defaultColumnOrder.map(column => (
+                            <TableCol key={column} columnDetails={demoColumnsDetails[column]} />
+                        ))}
+                    </colgroup>
+                    <thead>
+                        <tr>
+                            {defaultColumnOrder.map(column => (
+                                <TableHead
+                                    key={column}
+                                    column={column}
+                                    label={columnLabels[column as keyof ColumnLabel]}
+                                    sortBy={sortKey as string}
+                                    sortDir={sortDirection}
+                                    onClick={handleSortChange}
+                                />
+                            ))}
+                        </tr>
+                    </thead>
+                    <tbody>
+                        {sortedItems.map(row => (
+                            <tr key={row.driverId} data-id={row.driverId} className='cursor-pointer'>
+                                {defaultColumnOrder.map(col => (
+                                    <td key={col} data-field={columnLabels[col as keyof Driver]}>
+                                        <span>{row[col as keyof Driver]}</span>
+                                    </td>
+                                ))}
+                            </tr>
+                        ))}
+                    </tbody>
+                </table>
+            </div>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div>
+    <div class="table-toolbar">
+        <div class="table-toolbar-container">
+            <div class="table-toolbar-group-right">
+                <div class="table-toolbar-column">
+                    <button type="button" class="btn btn-default btn-component" tabindex="0">
+                        <span class="rioglyph rioglyph-download">
+                        </span>Export data</button>
+                </div>
+            </div>
+        </div>
+    </div>
+    <div class="table-responsive">
+        <table class="table table-layout-fixed table-column-overflow-hidden table-bordered table-sticky table-hover table-head-filled">
+            <colgroup>
+                <col class="" style="min-width: 100px; width: 100px;">
+                <col class="" style="min-width: 200px; width: 200px;">
+                <col class="">
+                <col class="">
+            </colgroup>
+            <thead>
+                <tr>
+                    <th class="user-select-none sort-column" data-field="driverId" data-sortby="driverId" title="Id">
+                        <span>
+                            <span class="sort-arrows sort-asc">
+                            </span>
+                            <span>Id</span>
+                        </span>
+                    </th>
+                    <th class="user-select-none sort-column" data-field="firstName" data-sortby="firstName" title="First name">
+                        <span>
+                            <span class="sort-arrows ">
+                            </span>
+                            <span>First name</span>
+                        </span>
+                    </th>
+                    <th class="user-select-none sort-column" data-field="lastName" data-sortby="lastName" title="Last name">
+                        <span>
+                            <span class="sort-arrows ">
+                            </span>
+                            <span>Last name</span>
+                        </span>
+                    </th>
+                    <th class="user-select-none sort-column" data-field="email" data-sortby="email" title="E-mail">
+                        <span>
+                            <span class="sort-arrows ">
+                            </span>
+                            <span>E-mail</span>
+                        </span>
+                    </th>
+                </tr>
+            </thead>
+            <tbody>
+                <tr data-id="1" class="cursor-pointer">
+                    <td data-field="Id">
+                        <span>1</span>
+                    </td>
+                    <td data-field="First name">
+                        <span>Gina</span>
+                    </td>
+                    <td data-field="Last name">
+                        <span>Watsica</span>
+                    </td>
+                    <td data-field="E-mail">
+                        <span>Loyal.Feil57@hotmail.com</span>
+                    </td>
+                </tr>
+                <tr data-id="2" class="cursor-pointer">
+                    <td data-field="Id">
+                        <span>2</span>
+                    </td>
+                    <td data-field="First name">
+                        <span>Gunner</span>
+                    </td>
+                    <td data-field="Last name">
+                        <span>Ebert</span>
+                    </td>
+                    <td data-field="E-mail">
+                        <span>Erika59@hotmail.com</span>
+                    </td>
+                </tr>
+                <tr data-id="3" class="cursor-pointer">
+                    <td data-field="Id">
+                        <span>3</span>
+                    </td>
+                    <td data-field="First name">
+                        <span>Candace</span>
+                    </td>
+                    <td data-field="Last name">
+                        <span>Glover</span>
+                    </td>
+                    <td data-field="E-mail">
+                        <span>Troy.Lebsack@hotmail.com</span>
+                    </td>
+                </tr>
+                <tr data-id="4" class="cursor-pointer">
+                    <td data-field="Id">
+                        <span>4</span>
+                    </td>
+                    <td data-field="First name">
+                        <span>Tommie</span>
+                    </td>
+                    <td data-field="Last name">
+                        <span>Dibbert</span>
+                    </td>
+                    <td data-field="E-mail">
+                        <span>Linwood_Anderson33@hotmail.com</span>
+                    </td>
+                </tr>
+                <tr data-id="5" class="cursor-pointer">
+                    <td data-field="Id">
+                        <span>5</span>
+                    </td>
+                    <td data-field="First name">
+                        <span>Lacy</span>
+                    </td>
+                    <td data-field="Last name">
+                        <span>Rippin</span>
+                    </td>
+                    <td data-field="E-mail">
+                        <span>Abby98@yahoo.com</span>
+                    </td>
+                </tr>
+                <tr data-id="6" class="cursor-pointer">
+                    <td data-field="Id">
+                        <span>6</span>
+                    </td>
+                    <td data-field="First name">
+                        <span>Ena</span>
+                    </td>
+                    <td data-field="Last name">
+                        <span>Osinski</span>
+                    </td>
+                    <td data-field="E-mail">
+                        <span>Cyril28@hotmail.com</span>
+                    </td>
+                </tr>
+                <tr data-id="7" class="cursor-pointer">
+                    <td data-field="Id">
+                        <span>7</span>
+                    </td>
+                    <td data-field="First name">
+                        <span>Ethyl</span>
+                    </td>
+                    <td data-field="Last name">
+                        <span>Nolan</span>
+                    </td>
+                    <td data-field="E-mail">
+                        <span>Troy.Jast22@hotmail.com</span>
+                    </td>
+                </tr>
+                <tr data-id="8" class="cursor-pointer">
+                    <td data-field="Id">
+                        <span>8</span>
+                    </td>
+                    <td data-field="First name">
+                        <span>Natasha</span>
+                    </td>
+                    <td data-field="Last name">
+                        <span>Auer</span>
+                    </td>
+                    <td data-field="E-mail">
+                        <span>Beth.Huel78@hotmail.com</span>
+                    </td>
+                </tr>
+                <tr data-id="9" class="cursor-pointer">
+                    <td data-field="Id">
+                        <span>9</span>
+                    </td>
+                    <td data-field="First name">
+                        <span>Afton</span>
+                    </td>
+                    <td data-field="Last name">
+                        <span>Leffler</span>
+                    </td>
+                    <td data-field="E-mail">
+                        <span>Theresa.Witting@hotmail.com</span>
+                    </td>
+                </tr>
+                <tr data-id="10" class="cursor-pointer">
+                    <td data-field="Id">
+                        <span>10</span>
+                    </td>
+                    <td data-field="First name">
+                        <span>Chase</span>
+                    </td>
+                    <td data-field="Last name">
+                        <span>Kuhlman</span>
+                    </td>
+                    <td data-field="E-mail">
+                        <span>Napoleon6@gmail.com</span>
+                    </td>
+                </tr>
+            </tbody>
+        </table>
+    </div>
+</div>
+```
+
+#### Props: Options of the returned `exportToCSV` function
+
+### Options of the returned `exportToCSV` function
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| data | T[] | — | Array of data objects to export. Each object represents one row in the table. |
+| fileName | string | export.csv | Optional name for the exported file. |
+| columns | (keyof T)[] | — | Optional list of object keys to export as columns. If omitted, all keys from the first row will be used. |
+| headers | Partial<Record<keyof T, string>> | — | Optional map of column keys to custom header labels. Example: { firstName: 'First Name' } |
+| delimiter | string | , | Optional delimiter to use between values in the CSV. You can use `";"` or `"\t"` for other formats. |
+| withBom | boolean | true | Whether to include UTF-8 BOM (useful for Excel). |